Merge pull request #119 from CodeWithJuber/claude/repo-review-agentic-generics-tteyld

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

Author: CodeWithJuber

ARCHITECTURE.md

@@ -42,7 +42,7 @@ native config. The four layers are how the brain is expressed; the compiler is h
 is delivered.
 
 ```mermaid
-%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%%
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','edgeLabelBackground':'#201a15','clusterBkg':'#171310','clusterBorder':'#4a3b2e','fontFamily':'ui-sans-serif, system-ui, sans-serif','fontSize':'14px'},'flowchart':{'curve':'basis','padding':10,'nodeSpacing':36,'rankSpacing':44}}}%%
 flowchart TD
     S["source/<br/>rules.json · substrate.json · mcp.json"] -->|"forge sync<br/>content-hash + DO-NOT-EDIT headers"| N["native configs<br/>CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider · …"]
     S -. configures .-> L
@@ -87,7 +87,7 @@ checks and returns a single verdict. It composes the individually-callable stage
 `anchor`, `verify`) into one pre-action contract.
 
 ```mermaid
-%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%%
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','edgeLabelBackground':'#201a15','clusterBkg':'#171310','clusterBorder':'#4a3b2e','fontFamily':'ui-sans-serif, system-ui, sans-serif','fontSize':'14px'},'flowchart':{'curve':'basis','padding':10,'nodeSpacing':36,'rankSpacing':44}}}%%
 flowchart TD
     RE["referenced entities"] --> INTAKE
     subgraph INTAKE["intake"]
@@ -136,7 +136,7 @@ claims into `.forge/ledger/`. Because a claim's bytes are a pure function of
 fold together over plain git with no conflicts.
 
 ```mermaid
-%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%%
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','edgeLabelBackground':'#201a15','clusterBkg':'#171310','clusterBorder':'#4a3b2e','fontFamily':'ui-sans-serif, system-ui, sans-serif','fontSize':'14px'},'flowchart':{'curve':'basis','padding':10,'nodeSpacing':36,'rankSpacing':44}}}%%
 flowchart LR
     subgraph EV["local events"]
         direction TB
@@ -171,7 +171,7 @@ dependencies still resolve. Otherwise it falls through to generation and mints a
 claim on the way back.
 
 ```mermaid
-%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%%
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','edgeLabelBackground':'#201a15','clusterBkg':'#171310','clusterBorder':'#4a3b2e','fontFamily':'ui-sans-serif, system-ui, sans-serif','fontSize':'14px'},'flowchart':{'curve':'basis','padding':10,'nodeSpacing':36,'rankSpacing':44}}}%%
 flowchart LR
     SP["spec"] --> FP["fingerprint<br/>MinHash + LSH"]
     FP --> LD["match ladder<br/>exact → near → adapt → miss"]
@@ -510,3 +510,31 @@ asserts all three resolve to `global/`.
 
 See [ROADMAP.md](ROADMAP.md) for direction and [`docs/adr/`](docs/adr/) for the recorded
 architecture decisions (zero runtime deps, the SKILL.md standard, guard-over-prose).
+
+## Repo map (generated)
+
+Top-level directories sized by file count, edges = import counts between them —
+rendered from the live import graph by `forge docs render`, so it can never drift
+from the tree it describes.
+
+<!-- forge:render:repo-map:begin (generated by `forge docs render` — do not edit) -->
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','edgeLabelBackground':'#201a15','clusterBkg':'#171310','clusterBorder':'#4a3b2e','fontFamily':'ui-sans-serif, system-ui, sans-serif','fontSize':'14px'},'flowchart':{'curve':'basis','padding':10,'nodeSpacing':36,'rankSpacing':44}}}%%
+flowchart LR
+  test["test<br/>98 files"]
+  src["src<br/>93 files"]
+  landing["landing<br/>60 files"]
+  research["research<br/>35 files"]
+  bench["bench<br/>2 files"]
+  global["global<br/>2 files"]
+  scripts["scripts<br/>2 files"]
+  docs["docs<br/>1 file"]
+  examples["examples<br/>1 file"]
+  test -- 191 --> src
+  bench -- 7 --> src
+  examples -- 4 --> src
+  test -- 2 --> scripts
+  scripts --> src
+  test --> bench
+```
+<!-- forge:render:repo-map:end -->

CHANGELOG.md

@@ -6,6 +6,21 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- **`forge docs render` — the docs that can write themselves, do.** `docs check` could
+  only detect drift; every fix was still a human hand-editing tables across five files.
+  The derivable doc surfaces are now generated from the same registries the check reads,
+  into marker-managed blocks (the `reports/benchmarks.md` pattern): the README command
+  table and the GUIDE group map from `COMMANDS`/`GROUPS`, the MCP tool table from the
+  `TOOLS` registry, every literal "N MCP tools" count phrase across all six files it
+  lives in, one shared mermaid theme derived from `brand.json` (change the brand,
+  re-render, every diagram in every tracked markdown file re-themes), and a repo map in
+  `ARCHITECTURE.md` drawn from the live import graph. `docs check` gains a `render`
+  reconciler: a stale registry-derived block is an error whose message is the fix
+  (`forge docs render`); tree-derived output (repo map, diagram theme) warns without
+  failing unrelated PRs.
+
 ## [0.28.0] - 2026-08-07
 
 ### Added

ONBOARDING.md

@@ -11,7 +11,7 @@ This page is the fast path: install, configure a repo, do a task, and watch the
 start paying off on day two.
 
 ```mermaid
-%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%%
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','edgeLabelBackground':'#201a15','clusterBkg':'#171310','clusterBorder':'#4a3b2e','fontFamily':'ui-sans-serif, system-ui, sans-serif','fontSize':'14px'},'flowchart':{'curve':'basis','padding':10,'nodeSpacing':36,'rankSpacing':44}}}%%
 flowchart TD
     I["forge init"] --> Cfg["every tool configured<br/>from one source"]
     Cfg --> Work["you work as usual"]