0068. The reference docs are generated from spec/, and the CLI's commands are spec too
- Status: Proposed
- Date: 2026-11-14
- Decided by: toolchain work package (WP15), pending Mik's approval
- Planning item: WP15 (toolchain), goal 3
Context
Elements, attributes, events, kit parts, diagnostics and utilities are all defined in spec/. Hand-written reference pages would drift from it, and nothing described the CLI in one place.
Decision
- **
pnpm generatewritesdocs/reference/**:elements.md,attributes.md,events.md,kit.md,diagnostics.md,utilities.md,cli.mdand aREADME.mdindex, fromspec/language/, the kit parts,spec/diagnostics/catalogue.yaml, the styling tables andspec/schemas/cli/commands.yaml. The generators live intools/generate/reference/. - **
pnpm check:repofails when they are out of date**, as for every other generated file. - **
spec/schemas/cli/commands.yamllists every command**, its arguments, its options (and which take a value) and the schema of its--jsonoutput. A CLI test reads it and checks that each command accepts exactly the options listed, so the reference and the binary cannot disagree.
Alternatives considered
| Option | Why not |
|---|---|
Generate the CLI reference from --help text | Help text is prose for people; the YAML is data that the tests can hold the binary to |
| A docs site generator | Not needed yet; Markdown reads well on GitHub and in editors |
Consequences
- Changing an element, part, diagnostic or command in
spec/changes its page in the same commit.