RR-20: schema docs generator drift

[michaeljgrimm]

Cause

scripts/generate-schema-docs.mjs is deterministic: two runs give identical output, and $defs are listed in schema order. The committed docs were wrong in three ways:

• Hand edits in RR-54 (RR-54: chart and table data — strict numbers, formats, datasets, series mapping #376). Chart and table rows in docs/schema-reference.md were rewritten by hand (short summaries, string instead of the enum types, inline/dataset in the Required column), and ChartDataSource/NumberFormat were moved.
• Hand edit in RR-30 (RR-30: Markdown and outline to and from OPF (core subpath, opf from-md, opf to-md) #268). The examples/markdown/ line was added to docs/examples.md but not to the generator, so every run deleted it.
• No rerun after schema changes. RR-41 (RR-41: deprecate the six plural audience ids (replacedBy the singular gallery ids) #309) changed the audience descriptions without rerunning the generator, which left stale truncation points in both references.

Fix

• The examples/markdown/ line now lives in the generator, so docs/examples.md keeps it.
• The generator renders if/then/else requirements as a "Conditional requirement" line. For Table that is dataset, otherwise rows, which keeps what the RR-54 hand edit was trying to say.
• docs/schema-reference.md and docs/catalog-schema-reference.md are regenerated. The schema descriptions are the source of truth, so the RR-54 hand-written summaries are replaced by their (truncated) schema text.
• New node scripts/generate-schema-docs.mjs --check and pnpm check:schema-docs. It fails and names the stale files when a committed file differs from a fresh build (CRLF is normalized for Windows checkouts). As a check:* script it runs in pnpm test through scripts/run-checks.mjs with no checks.json entry.
• Changelog fragment changes/rr-20-schema-docs-drift.md (packages: []).

Verification

• check:schema-docs fails on origin/main (schema-reference.md, catalog-schema-reference.md) and passes after regenerating.
• check:changes, check:runners and check:text pass, and run-checks.mjs --list includes check:schema-docs.

Coordination with RR-55 (#423)

#423 hand-edits both references. After this lands it should run node scripts/generate-schema-docs.mjs instead of hand-reverting:

• The Slide.layout row in schema-reference.md comes from its schema description change, so the generator reproduces it. This PR does not touch that row.
• The new intro paragraph in catalog-schema-reference.md (the link to finding-schema-reference.md) is generator text. It has to go into catalogReference(). If RR-55: short-verb API, one validate, Finding schema, stats (core 0.14.0, breaking) #423 adds a finding.schema.json under spec/schemas/, the generator also needs to exclude it from the catalog list, as it already excludes opf.schema.json. Otherwise check:schema-docs fails on the rebased branch.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and doc-generation tooling only; no runtime schema or engine behavior changes.

Overview
RR-20 restores the schema docs as true generator output and blocks future hand-edit drift.

scripts/generate-schema-docs.mjs now documents that docs/schema-reference.md, docs/catalog-schema-reference.md, and docs/examples.md must not be edited by hand. It emits conditional requirements from JSON Schema if/then/else (e.g. Table: dataset when present, otherwise rows), moves the examples/markdown/ bullet into the generator so it is not wiped on regen, and supports --check to compare committed files to a fresh build (CRLF-normalized). Writers return in-memory content; pnpm check:schema-docs wires that into CI via package.json.

The two reference markdown files are regenerated from schemas, replacing prior manual chart/table rows and stale truncation from missed regens after description changes. A changelog fragment records the fix.

^{Reviewed by Cursor Bugbot for commit b907b5c. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 1a5e8a19-49ef-4782-99d1-2f5ced77f578)