Duolith docs

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 generate writes docs/reference/**: elements.md, attributes.md, events.md, kit.md, diagnostics.md, utilities.md, cli.md and a README.md index, from spec/language/, the kit parts, spec/diagnostics/catalogue.yaml, the styling tables and spec/schemas/cli/commands.yaml. The generators live in tools/generate/reference/.
  • **pnpm check:repo fails when they are out of date**, as for every other generated file.
  • **spec/schemas/cli/commands.yaml lists every command**, its arguments, its options (and which take a value) and the schema of its --json output. 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

OptionWhy not
Generate the CLI reference from --help textHelp text is prose for people; the YAML is data that the tests can hold the binary to
A docs site generatorNot 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.