feat(docs): forge docs render — self-writing doc surfaces + one brand diagram theme

[CodeWithJuber]

What & why

Keeping the docs in full sync with the code was manual: forge docs check detects drift and fails CI, but every fix was still a human hand-editing tables across five files (the last feature PR needed the "N MCP tools" count bumped in six places by hand). And the mermaid diagrams each carried their own hand-pasted theme string.

forge docs render closes the loop — the derivable doc surfaces are now generated from the same registries the check reads, into marker-managed blocks (the exact pattern npm run bench already uses for reports/benchmarks.md). Prose stays human; tables and diagrams become machine-owned:

• README command table + GUIDE group map — rendered from COMMANDS/GROUPS, so the docs always show exactly the --help grouping, one source of truth.
• GUIDE MCP tool table — rendered from the TOOLS registry.
• "N MCP tools" count phrases — auto-corrected across all six files they live in.
• One shared mermaid theme derived from brand.json (no hardcoded hexes) with readability settings the hand-written init strings lacked (edge label background, cluster colors, font size, curve, spacing) — normalized across every tracked markdown file; deliberate bad-example blocks opted out with docs-check-ignore stay untouched. Change the brand → run render → every diagram re-themes.
• A repo map in ARCHITECTURE.md drawn from the live import graph (directories sized by file count, edges = import counts) — the architecture picture cannot drift from the tree it describes.

docs check gains a render reconciler with calibrated severity: a stale registry-derived block is an error whose message is the fix (run forge docs render); tree-derived output (repo map, diagram theme) is a warning, so moving a file never fails an unrelated PR — but shipping a new command with a stale table always does. Roots without markers manage nothing and stay ok (fixture safety; forks can opt out by deleting markers).

forge docs render --check reports drift without writing (exit 1), for local pre-push use.

Checklist

• npm test passes (1,097 pass / 0 fail locally, Node 20)
• npm run check passes (Biome lint + format)
• New public functions have a test (test/docs_render.test.js ×9: renderer/registry coverage, splice idempotence, count rewrite, theme normalization + opt-outs, repo map from a real tree, end-to-end render → tamper → strict-drift, fixture safety)
• Conventional commit message (feat:/fix:/docs: …)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency (dev deps ok)
• Substrate/docs updated if this changes forge substrate, forge impact, router/gate, or MCP substrate tools (GUIDE section for docs render, mintlify core.mdx, COMMANDS usage/flags)

Risk & rollback

• Risk level: low — additive subcommand + one new reconciler; generated block content is identical in spirit to the hand tables it replaces (now sourced from COMMANDS summaries); the only repo-wide rewrite is the mermaid %%{init line, which keeps the two brand hexes docs check already enforces.
• Rollback plan: revert the commit; the docs keep their last rendered content (fully valid markdown), and deleting the markers returns any table to hand maintenance.

Extra checks (tick if applicable)

• npm run typecheck passes
• Input validated at boundaries; errors handled (no swallowing) — renderer failure never takes docs check down (try/catch → skip); missing files/markers degrade to informational
• Authorization/ownership checked (if it touches access) — n/a
• Logs contain no secrets/PII
• If AI-assisted: I understand it, verified the package APIs, and it has tests

🤖 Generated with Claude Code

https://claude.ai/code/session_01LXmzxfRVDRVPU6LG8W39Rz

---

Generated by Claude Code