docs/book/src/architecture/generated-documentation-pipeline.md
ZeroClaw documentation combines hand-authored Markdown with references and snippets materialized from Rust types, command definitions, registries, WIT contracts, workflow files, and UI metadata. The generated file is not a second source of truth: fix the owning source or generator, then rebuild the documentation.
Use this page when a change touches a schema, CLI flag, feature or hardware inventory, plugin contract, default keymap, theme registry, mdBook directive, generated reference, docs gate, or deployment workflow. For configuration values specifically, also read Config lifecycle. For translated output, continue with Localization catalog lifecycle.
| Surface | Canonical source | Materializer | Output | Repository state | Consumer |
|---|---|---|---|---|---|
| Config reference | zeroclaw_config::schema::Config plus Configurable derives | cargo mdbook refs or cargo mdbook build, through markdown-schema | docs/book/src/reference/config.md | Ignored derived file | Config reference chapter and schema-backed directives |
| CLI reference | Clap command tree in src/main.rs | cargo mdbook refs or cargo mdbook build, through markdown-help | docs/book/src/reference/cli.md | Ignored derived file | CLI reference chapter |
| Rust API reference | Public Rust items across workspace crates | cargo doc inside cargo mdbook refs or cargo mdbook build | target/doc/, copied to docs/book/book/api/ | Ignored build output | Published API reference |
| Feature matrix | Channel inventory, model-provider slots, default tools, and docs/book/feature-matrix-parity.toml | xtask/src/cmd/mdbook/feature_matrix.rs during locale builds | docs/book/src/_snippets/feature-matrix-*.md | Ignored derived snippets | Feature comparison pages through {{#include}} |
| Hardware tables | Hardware board registry and tool catalog, transport descriptions in the generator, release workflow targets, and the low-memory threshold in install.sh | xtask/src/cmd/mdbook/hardware.rs during locale builds | docs/book/src/_snippets/hardware-*.md | Ignored derived snippets | Hardware and release-target guides |
| Plugin contract values | WIT contracts, plugin guides, and src/plugin_registry.rs limits | xtask/src/cmd/mdbook/plugins.rs during locale builds | docs/book/src/_snippets/plugin-*.md | Ignored derived snippets | Plugin authoring guides |
| zerocode key tables | Default keymap in apps/zerocode/src/keymap/actions.rs | xtask/src/cmd/mdbook/keymap.rs during locale builds | docs/book/src/_snippets/zerocode-*-keys.md | Ignored derived snippets | zerocode keybinding pages |
| Peer-group blocks | docs/book/peer-groups.toml | xtask/src/cmd/mdbook/peer_groups.rs mdBook preprocessor | Expanded chapter content | Build-time only | Channel and peer-group pages using peer-group directives |
| Theme CSS and names | web/src/contexts/themes.json | xtask/src/cmd/mdbook/themes.rs during locale builds | Ignored CSS/name fragments plus the generated marker region in tracked docs/book/theme/index.hbs | Mixed: derived files are ignored; the template outside its marker remains authored | mdBook theme picker and zerocode theme reference |
| Locale switcher | locales.toml and tracked docs/book/theme/lang-switcher.js.tpl | inject_lang_switcher_locales during locale builds | docs/book/theme/lang-switcher.js | Ignored derived file | Published language selector |
| Authored chapters | docs/book/src/**/*.md and tracked snippets | mdBook preprocessors and renderers | Locale/version HTML under docs/book/book/ | Tracked source, ignored output | Published documentation site |
| Dashboard API types | zeroclaw_gateway::openapi::build_spec() and gateway runtime types | cargo web gen-api | target/openapi.json, web/src/lib/api-generated.ts, web/src/lib/api-descriptions.ts, and web/src/lib/api-enums.ts | Ignored derived files | TypeScript dashboard build |
This matrix describes the current high-value surfaces, not every helper file produced during a build. The reusable rule is ownership: a generated value should have one canonical input and one deterministic materialization path.
cargo mdbook is the xtask command surface defined in .cargo/config.toml. Its main commands compose the pipeline rather than invoking a plain mdbook build directly.
cargo mdbook refs generates the CLI and config Markdown from live code, builds workspace rustdoc, and copies the API output into the docs build tree. cargo mdbook build performs the full publication-shaped sequence:
reference/cli.md and reference/config.md from the current command tree and config schema.locales.toml, with preprocessors configured by docs/book/book.toml.docs/book/book/.The peer-group preprocessor expands its directives while mdBook processes each chapter. Other standard mdBook preprocessors handle links, Mermaid blocks, and gettext localization. Generated references therefore need to exist before chapter preprocessing, while directive expansion and translation happen during the locale build.
The docs deployment workflow initializes the translation submodule, installs the required mdBook tools, runs cargo mdbook build, and merges the assembled version into the gh-pages branch. It does not call a translation provider or repair catalogs during deployment.
Tracked files are reviewable inputs or templates: authored Markdown, locales.toml, docs/book/peer-groups.toml, feature-matrix parity metadata, theme templates, Rust/WIT sources, and workflow definitions. The docs/book/po path is a tracked gitlink to the separate translation-catalog repository; its contents and release tags have their own lifecycle.
Ignored files are reproducible materializations: CLI and config references, generated snippets, rustdoc, rendered HTML, locale-switcher JavaScript, generated theme CSS, and the dashboard TypeScript API client. They may exist in a working tree after a docs build without belonging in a commit.
docs/book/theme/index.hbs is the notable mixed case. It is a tracked template, but the theme generator rewrites only the marked theme-list region from themes.json. If a standard generation command changes that region, inspect whether the canonical registry or generator changed; do not treat the generated list as independently authored content.
Different checks cover different failure classes:
| Check | What it proves | What it does not prove |
|---|---|---|
| Docs quality gate | Changed Markdown passes prose em-dash policy and markdownlint | Ignored references or snippets were regenerated from current code |
| Added-link gate | New local Markdown links in the compared diff resolve | Existing links, generated links outside the diff, or rendered navigation all work |
cargo mdbook check | PO catalogs parse and pass generated-response, protected-literal, and local-path audits | CLI/config references and ignored snippets match current Rust sources |
cargo mdbook refs | CLI/config reference Markdown and rustdoc can be generated from current code | Every locale and theme assembles into a complete site |
cargo mdbook build | Full references, snippets, locale builds, rendered links, and site assembly complete | Ignored outputs are committed or compared by ordinary PR CI |
| Translation pin workflow | The docs/book/po gitlink is initialized and satisfies the catalog-repository pin contract | Catalog coverage is complete or translation quality is acceptable |
| Docs deployment | The selected ref builds and can be merged into the versioned gh-pages layout | A normal source PR regenerated every ignored output before review |
Required PR CI runs the docs quality and added-link gates, but it does not run the full mdBook build for every documentation change. Reviewers should request the narrowest additional evidence that covers the changed generator or rendered boundary instead of assuming green prose checks prove generated output is current.
themes.json or the marked-region generator, not by hand-editing generated buttons.docs/book/book/, rustdoc output, or another ignored materialization merely to make a local build look current.xtask/src/cmd/mdbook/xtask/src/cmd/mdbook/refs.rsxtask/src/cmd/mdbook/build.rsdocs/book/book.tomllocales.tomlscripts/ci/docs_quality_gate.sh, scripts/ci/docs_links_gate.sh.github/workflows/validate-translations-pin.yml.github/workflows/docs-deploy.yml