Design: documentation is one system — proto comments, godoc, generated reference, markdown, and mermaid each own facts, and nothing says a fact twice

Docs-system design record, capping the docs thread (#408 package docs, #415 examples/pkgsite). The parts are individually strong; this issue writes down how they compose so they sharpen rather than contradict each other as both grow.

The inventory, measured

• Proto comments are the best-documented surface in the repo: 3,408 comment lines in 4,886 (70%), 87 of 93 messages carrying leading comments — and they travel: protoc-gen-go copies them onto the generated types, so one authored comment renders on pkg.go.dev, in every gopls hover on a flowstatev1 type, and in buf/BSR schema browsing. The schema comment is the single highest-leverage documentation location in the project.
• Go doc comments: modern syntax in active use (#415's measurement — doc links in 162 files, headings in 244 places); package docs excellent where present, absent on engine/server (#408).
• Generated reference (docs/reference/: cli, tasks, mcp, diagnostics, envvars): derived from the registries and pinned by git diff --exit-code — the house's proven anti-drift mechanism.
• Hand-written narrative (docs/: ARCHITECTURE, DSL, CLI_DESIGN, DEPLOYMENT, EMBEDDING, …): where the why lives; ARCHITECTURE.md's invariants are load-bearing for every structural issue this month.
• Mermaid: present in README.md and docs/CLI_DESIGN.md, rendered by GitHub, pinned by nothing.

The routing rule (the design)

Each fact is authored exactly once, at the surface closest to the code that enforces it, and every other surface renders or links it. Concretely:

• What a message/field means → the proto comment. It's the only authoring point that reaches Go consumers, schema browsers, and editor hovers at once. Corollary: proto comments are written knowing they render as godoc — leading-identifier sentences (// Workflow describes…), complete first sentences (pkgsite truncates at the first period for summaries), no reliance on proto-only context. The 6 uncommented messages get comments; worth evaluating buf's COMMENT_MESSAGE/COMMENT_FIELD lint rules (not in STANDARD) to make presence mechanical — the zero-suppressions policy in proto/buf.yaml makes an opt-in category a real commitment, so adopt only the granularity the team will keep.
• What a Go API does and how to hold it → doc comments + testable examples (#408, #415). Never restate schema semantics there — link the type ([Workflow]) and let the proto comment speak.
• What exists (every task, flag, RPC, env var, diagnostic) → generated reference, never hand-listed anywhere else. The four-surface drift the doc audit found is the standing proof.
• Why the system is shaped this way → hand-written markdown, which links down into godoc/reference rather than excerpting them. An excerpt is a copy; a copy is a thing that drifts (the CLAUDE.md make-check/ci.yml pairing survives only by being explicitly co-maintained — that's the expensive kind, spent deliberately).
• Structure a reader should see at a glance → mermaid, small and adjacent to its prose. GitHub renders it; pkgsite does not — so a diagram belongs in markdown, and godoc links to the doc that holds it rather than ASCII-arting a copy.

The gaps this surfaces (each small)

1. docs/DSL.md vs the generated reference mirror's DSL.md — two files, one name, different provenance. Verify which is source and which is derived; if both are authored, that's the one live same-fact-twice violation in the tree and needs a merge or a renaming that states the relationship.
2. Mermaid is the one unpinned renderer. Cheap floor: a CI step that parses every ```mermaid block with mermaid-cli so a syntax break can't merge (GitHub renders an error box today and nothing would notice). The interesting ceiling, true to the self-sharpening ethos: the architecture diagram of package layering can be derived from the import graph (#406's invariant test walks it anyway) — a generated .mmd pinned like any generated file, so the picture of the layering is the layering.
3. Proto comment style pass riding #407's split: as messages move into four files, normalize their comments to godoc-shaped leading sentences file by file — the split PR touches every message anyway, and buf breaking doesn't see comments.
4. README transcripts are hand-pasted CLI output; #402/#404's golden/transcript machinery is the eventual pin, noted so the READMEs join the system instead of staying the last unpinned copies.

What deliberately stays duplicated

Named so nobody "fixes" them: CLAUDE.md's command list ↔ make check (explicitly co-maintained, the file says so); docs/reference/mirror/ (a mirror is its mechanism); example YAMLs quoted in docs where the example directory is CI-run (the quote is pinned transitively). The rule isn't "never twice" — it's "twice only with a mechanism, or a written reason."

Start by reading the routing rule and comparing docs/DSL.md with docs/reference/mirror/DSL.md to establish their provenance. Then inspect the existing generated-reference drift check, proto comments, README transcripts, and Mermaid blocks alongside issues #402, #404, #406, #407, and #415. Done means the ownership rules and follow-up scope are agreed without leaving competing sources of truth.