feat(docs): render every diagram with Archify; add illustrations and a new social card

[CodeWithJuber]

What & why

This follows #165, which has shipped in v1.6.0. It carries out two requests:

• draw every diagram in the docs, the docs site and the Pages site with Archify;
• integrate the generated visual assets.

1. Thirteen Archify diagrams replace the fifteen hand-written Mermaid diagrams.

• Where they appear: README, ARCHITECTURE, ONBOARDING, GUIDE, the substrate docs, docs/UNIVERSAL_ROUTING.md, the plan overview and eight docs-site pages.
• New views: four diagrams are new rather than replacements: the claim lifecycle, one Claude Code session's hooks, the forge verify pipeline and the universal-router cascade.
• Validation: the sources in docs/diagrams/src/ use Archify's typed schemas (architecture, workflow, sequence, dataflow, lifecycle). Each passes Archify's showcase bar: 9/9 artifact checks, 0 errors, 0 warnings. Each also passes Archify's visual check at 1440×900 to 2048×1320 in both themes.
• Accuracy: every diagram was checked against the code.
  • The router diagram says forge route fit is a MAP shrinkage toward the shipped prior, not a Bayesian update.
  • The verify diagram binds untracked files into the code state.
  • The team loop names all four oracles: forge verify, forge imagine --run, CI and a human accept/revert.
  • The onboarding diagram says "guided", because the docs deliberately say it is not zero-config.
• Embeds: the Markdown docs embed a dual-theme SVG linked to an interactive page. The docs site shows the same SVG in a <Frame>, with a link. The interactive pages support pan, zoom, search (/), a guide (?) and tracing a node's dependencies.
• Pipeline: scripts/diagrams.mjs pins Archify by commit and uses only node and git.
  • build validates, renders, exports the SVG through the viewer's own Export menu (Archify's headless-Chrome driver), refreshes the docs-site copy and writes a receipt to docs/diagrams/diagrams.json.
  • check runs offline and is in the quality gate. It fails when a source changed without a re-render, when a source isn't registered, when an SVG or docs-site copy is missing or stale, or when a declared embed is gone.
  • sync refreshes the byte-identical docs-site copies in mintlify/images/diagrams/; Git stores each identical file once.
  • site is the Pages step. It renders the ~0.8 MB interactive pages, which are not committed, and refuses to publish any page whose sha256 differs from its validated receipt.
• Reproducibility: rendering is byte-deterministic. A fresh fetch of the pinned commit reproduced all 13 receipts.
• Gallery: /diagrams/ is linked from the landing page's nav and footer and from the status page. It meets WCAG AA in both themes: the worst contrast is 5.84:1 in dark and 4.62:1 in light, with no overflow at 1440, 760 or 390 px.
• Docs check: forge docs check now rejects hand-written Mermaid diagrams and embeds of unregistered diagrams. The generated repository map stays Mermaid, because it is laid out from the live import graph.
• Credits: Archify is MIT (© tt-a1i, © Cocoon AI). The SVGs embed JetBrains Mono subsets under the OFL, with the license text inside each file. See docs/diagrams/README.md.

2. Illustrations and the social card.

• Docs site: seven docs-site pages open with an illustration. The art is text-free and geometric, in the brand palette, and each image has descriptive alt text.
• Landing page: the evidence band has a background image with a 55% veil, measured at ≥ 5.4:1 text contrast at 1440, 760 and 390 px. It falls back to a flat color under prefers-contrast: more.
• Social card: the link preview is now og.jpg (284 KB), rendered by scripts/og-card.mjs from docs/assets/og.svg. The script refuses to write the card if a font didn't load, if text crosses into the art or out of the crop-safe margins, or if the file exceeds the ~300 KB that link-preview scrapers accept. The old og.png was 1.3 MB. test/pages.test.js now checks that the og:image file ships from docs/assets and that twitter:image is the same card.
• Hero: the landing hero says 10 native targets; it still said 9.

3. .cache/ stays out of the import graph. forge impact, forge scope and the generated repository map walked into .cache/. Locally, the pinned Archify checkout there showed up as 219 project files. .cache is now in IGNORE_DIRS, with a regression test that fails without the fix.

Checklist

• npm test passes on the rebased tree: 1,700 tests, 1,696 pass, 0 fail, 4 platform-gated skips (Node 22)
• npm run check passes (Biome lint + format)
• New public functions have a test
• Conventional commit message (feat:/fix:/docs: …)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency (dev deps ok). Archify is a pinned build-time tool fetched by git, not an npm dependency. The MDX compile and Chromium checks ran from a scratch directory, not the repo.
• Substrate/docs updated if this changes forge substrate, forge impact, router/gate, or MCP substrate tools

Risk & rollback

• Risk level: low. The code changes are the offline diagram check, two docs-check rules and one entry in IGNORE_DIRS. The rest is docs, images and a build-time diagram pipeline.
• The Pages workflow now fetches Archify at a pinned commit and fails, rather than publishing, if a rendered page doesn't match its receipt.
• Local CodeQL 2.27.0 (javascript-code-scanning) finds 0 results on this tree. One finding in a new test regex was removed before the push.
• Three things for you to decide or do:
  • Social preview: upload github-social-preview.png from the asset bundle in the repository's GitHub settings.
  • Touch icon: the star-only touch icon removes the "F" from the mark, so it's a brand decision and not applied here.
  • README banner: optional, since the README already has a hero image.
• Rollback plan: revert the merge commit.

Extra checks (tick if applicable)

• npm run typecheck passes
• Input validated at boundaries; errors handled (no swallowing)
• 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_01GVVG2VDETWsDxMu6MBWPz2

---

Generated by Claude Code