docs: publish the build graph as a gate-checked Mermaid page

[totollygeek]

What & why

Adds docs/graph.md — Zuke's own dependency graph (38 targets, 24 edges) rendered as a Mermaid diagram GitHub draws natively, plus a target reference table with descriptions and dependencies — so anyone can click through from the README and see the live build graph of zuke.ts itself.

The page is kept current with the same generate-then-verify pattern as the workflows and the plugin skills:

• ./zuke graphDoc regenerates the page from discoverTargets(this) — the same nodes and hard dependsOn edges ./zuke graph prints, in declaration order.
• graphDocCheck is a new dependency of the ci gate and fails with "Run ./zuke graphDoc and commit the result." when the page drifts from the build.

The generator (build/graph_doc.ts) is pure apart from the two file operations, so the drift check is a string comparison. Mermaid nodes use synthetic ids (t0, t1, …) so a target name can never collide with a Mermaid keyword, and labels/table cells are escaped. Mermaid was chosen over a committed image: GitHub renders it natively in markdown, and there is no binary asset to regenerate or drift.

The README links the page from the intro paragraph and the Documentation list; AGENTS.md's gate-dependency snapshot records the new check. No generated workflow YAML changes — the CI job invokes the ci hub target as a single step.

Tests: unit coverage of row extraction, Mermaid rendering, escaping, determinism, the empty build, and the write/check drift states, plus two integration tests driving a fixture build through the real CLI main() (generate → check passes; build gains a target → check fails). An adversarial pass added a guard against rendering a broken edge for a dependency naming no row, with its own regression test.

Related issues

None.

Checklist

• The PR title is a Conventional Commit (type(scope): summary).
• deno task ci passes locally (lint, fmt, type-check, tests, spell). (security's zizmor audit could not reach the GitHub advisories API from the sandbox; every other gate target is green, gitleaks included.)
• Tests were added or updated; coverage stays at 95%+ (lines and branches).
• Docs updated in the same PR (README.md, JSDoc, docs/) when behaviour changed.
• Public API changes were regenerated with ./zuke apiDocs (llms.txt, llms-full.txt, package README ## API). — N/A: no packages/ change; apiDocsCheck is green.
• No any, no as casts or ! non-null assertions in src/ (narrow with type guards instead).
• A new package was wired into all seven places (see AGENTS.md), if applicable. — N/A: no new package.
• The code is written using AI assisted coding.

🤖 Generated with Claude Code

https://claude.ai/code/session_0187myXRLofTjVoCkzN51tG8

---

Generated by Claude Code

[github-actions]

🤖 Zuke AI review

🔎 security review — review

Score: 0/10 · Severity: none · 0 finding(s)

Tokens: 28444 in · 36 out · 28480 total

Budget: 28,480 tokens of 500,000 tokens

No security issues were introduced by the diff.

[github-actions]

🤖 Zuke AI review

🔎 generic review — review

Score: 0/10 · Severity: none · 0 finding(s)

Tokens: 15285 in · 45 out · 15330 total

Budget: 43,810 tokens of 500,000 tokens

The change adds a new graph documentation generator, tests, and CI gate wiring without introducing notable maintainability or correctness risks.