docs: architecture diagrams across the site, rendered to SVG by Merlion

[debuggingfuture]

The docs site draws its architecture: 51 diagrams across 26 pages, covering how a dispatch travels from a GitHub Action to a check-run, how runs are triggered and serialized, how the substrate admits, fences and polices an execution, and how an upgrade is verified. Diagrams follow the site theme in light and dark, pan and zoom, and are real SVG text that search and screen readers read.

Problem & Insight

The site had one Mermaid block, which Starlight rendered as a code listing. The pages that most need a picture (request flows across the Action, Dispatcher, Workflow and GitHub; admission tickets; the exec fence; egress policy) were prose only. Several of those pages had also drifted from the code.

Take

• Rendering: Merlion renders every ```mermaid block to static SVG at build time through its Astro integration (apps/docs/astro.config.mjs). No Mermaid runtime ships to the browser. apps/docs/src/styles/diagrams.css maps the brand palette onto Merlion's light and dark tokens. The Merlion packages are not on npm, so apps/docs/vendor/merlion/ holds their pnpm pack tarballs and records the source commit and the wasm SHA-256.
• Diagrams: sequence diagrams for cross-component flows, state diagrams for lifecycles (serial gate, pool slot, detached process, expand/migrate/contract), flowcharts for step graphs and decisions. Each is checked against the code it describes, and every page passes merlion check --strict. The same blocks render on GitHub.
• Prose corrected to the code:
  • The dispatch action makes 3 attempts in total and treats every status except 202/400/401/404 as transient.
  • health-check-url is requested exactly as given.
  • The facade has thirteen methods.
  • All six grant profiles are served, and report enforcement exists.
  • Platform 520s are recorded and read through denials().
  • /health answers 503 unverified until the canary passes.
  • The deploy job order includes canary.

Key actions

• Docs build, link validation, astro check and lint pass. Every diagram was screenshotted in both themes with no console errors.
• Substrate ADRs 0004, 0010 and 0012 describe behaviour the code does not match (queue-age admission, recipe-based pool selection, ticket claims, the detached gone/unknown status). The diagrams draw the code; the ADR text is unchanged pending decisions.
• When Merlion publishes to npm, replace the file: tarballs with a version range.

[flaredispatch-fractalboxdev]

AI code review — 🛑 Request changes

Risk tier: full · 1 critical · 0 warnings · 0 suggestions

Reviewers: security ⚠️ · performance ⚠️ · code-quality ⚠️ · documentation ⚠️ · release-management 1 · compliance ⚠️ · agents-md ⚠️

1. 🛑 Critical — New local dependencies require a synchronized pnpm lockfile

📍 apps/docs/package.json:16-20

Five new 'file:' package dependencies are added, but no corresponding lockfile update is present in the supplied diff. CI installs with a frozen lockfile, so the docs build will fail with an out-of-date lockfile unless 'pnpm-lock.yaml' is regenerated and committed along with the vendored tarballs.

📋 View full logs & reviewed diff ↗