@erclx/canon 4.75.1 → 4.76.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.75.1",
+  "version": "4.76.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/draft-figure/REQUIREMENT.md

@@ -0,0 +1,42 @@
+---
+name: draft-figure
+description: Why a figure decides between Mermaid and freehand SVG before drawing, and why only the Mermaid path carries a render-verification loop
+---
+
+# Draft figure requirement
+
+## Gap
+
+Without this skill, a session asked for a figure reaches for whichever path it thought of first. A graph-shaped subject gets model-authored SVG coordinates nobody checked against a render, drifting from the hand-drawn look every other figure in the project carries. A subject that is not graph-shaped gets forced through Mermaid's node-and-edge model, producing a diagram that answers a different question than the one asked. Either failure ships a figure a reader cannot trust, and a figure exists only to be trusted at a glance.
+
+The color failure is the quiet one. Mermaid's own theme writes literal hex values, and a figure carrying one stops re-coloring itself the moment the host page switches its palette, which the figure standard's own accessibility bar rules out.
+
+## Must
+
+- Apply the standard's earn-its-place bar before drawing anything
+- Decide between the Mermaid path and the freehand path by whether the subject reduces to a graph, not by which is faster to produce
+- Render the Mermaid path with the hand-drawn look and the figure font stack, never with Mermaid's default look
+- Rewrite every literal color the renderer wrote into the custom property the host stylesheet defines
+- Read the Mermaid render back and judge it against what the figure means to say, the same verification `draft-diagram` runs for the architecture surface
+- Wrap either path in a `<figure>` and `<figcaption>` and give it an accessible name
+
+## Must not
+
+- Force a non-graph-shaped subject through Mermaid, or route a graph-shaped one through freehand SVG coordinates a model authored by hand
+- Ship a literal hex color on either path
+- Report a clean verification when the Mermaid render was skipped or a defect survived
+- Loop past two correction passes on a surviving defect
+- Commit a scratch render. Only the SVG that ships in the destination document survives
+
+## Guards
+
+- No subject given: stop, since nothing states what the figure has to show
+- No destination document given: stop, since the figure has nowhere to land
+- Subject does not clear the earn-its-place bar: stop rather than drawing decoration
+
+## Out of scope
+
+- The toolkit's own `.canon/diagrams/` architecture surface, which shares no code, font, or visual language with this convention: `draft-diagram`
+- Mermaid's own layout, budgets, and label rules for the fence itself: the mermaid standard, cited rather than restated here
+- A UI wireframe or screen mockup: `draft-wireframes`
+- `teach-workspace`'s own lesson-figure authoring, which stays inline rather than calling this skill

package/claude/skills/draft-figure/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: draft-figure
+description: Drafts one hand-drawn figure for a document, deciding whether the subject is Mermaid-shaped or needs freehand SVG, then draws it. Renders the Mermaid path through Mermaid's own hand-drawn look, reads the render back, and fixes what it exposes. Wraps either path in the figure standard's caption, color, and accessibility rules. Use when asked to "draw a figure", "add a hand-drawn diagram", "draft a figure for this doc", or "draw this relationship as a figure". Do NOT use for the toolkit's own `.canon/diagrams/` architecture surface, which is `draft-diagram`, or for a UI wireframe, which is `draft-wireframes`.
+---
+
+# Draft figure
+
+Decide whether a requested figure reduces to a graph Mermaid can draw, or needs freehand SVG, then draw it and verify what a reader will actually see.
+
+## Guards
+
+- If no subject is given, stop: `❌ No subject given. Name the relationship, boundary, path, or before-and-after this figure should show.`
+- If no destination document is given, stop: `❌ No destination given. Name the file this figure belongs in.`
+
+## Step 1: read sources
+
+Read these in parallel:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/figures.md`: when a figure earns its place, the render-first policy, wrapping and captioning, and the color and accessibility rules
+- `${CLAUDE_SKILL_DIR}/../../standards/mermaid.md`: direction and layout, node and edge budgets, the accessibility fields, and how a render is verified, for the Mermaid path
+- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words and formatting for the caption prose
+- The `write-human` skill: voice and rhythm for the caption prose
+
+## Step 2: does it earn its place
+
+Apply the standard's bar: a relationship, a boundary, a path, or a before-and-after that prose or a list cannot carry as well. Stop when it does not: `❌ <subject> reads fine as prose. A figure adds nothing here.`
+
+## Step 3: decide the render path
+
+- **Graph-shaped**, meaning the relationship, boundary, or path is already what a flowchart or sequence diagram expresses: draw it through Step 4.
+- **Not graph-shaped**, meaning the subject is a spatial or physical arrangement no flowchart reduces to: draw it through Step 5.
+
+State which path was picked and why in one sentence. The standard states this as a render-first policy rather than a ban on any tool-exported drawing, so a graph-shaped subject always routes through Mermaid even though that is itself an external renderer.
+
+## Step 4: the Mermaid path
+
+- Draft the fence against `mermaid.md`: direction, node and edge budgets, `accTitle`/`accDescr`, and quoted labels.
+- Render it with the hand-drawn look and the figure font stack, writing scratch files under `.canon/tmp/figures/`:
+
+```bash
+mkdir -p .canon/tmp/figures
+cat <<'EOF' >.canon/tmp/figures/<slug>.json
+{"look": "handDrawn", "themeVariables": {"fontFamily": "Virgil, Excalifont, cursive"}}
+EOF
+bunx -y @mermaid-js/mermaid-cli -i .canon/tmp/figures/<slug>.mmd -o .canon/tmp/figures/<slug>.svg -c .canon/tmp/figures/<slug>.json
+bunx -y @mermaid-js/mermaid-cli -i .canon/tmp/figures/<slug>.mmd -o .canon/tmp/figures/<slug>.png -c .canon/tmp/figures/<slug>.json
+```
+
+Render both formats in one pass: the SVG is what ships inside the `<figure>`, and the PNG is what Step 6 reads back, since an SVG's markup carries no recoverable spatial meaning the way `draft-diagram` Step 5 already states for the architecture surface.
+
+Use `bunx` when bun is available, falling back to `npx -y @mermaid-js/mermaid-cli ...` otherwise.
+
+- Rewrite every stroke, fill, and text color the renderer wrote as a literal hex value into the custom property the host stylesheet defines, per the standard's color rule. Mermaid's own theme has no notion of a custom property, so this is a source edit made to the rendered SVG, not a config option.
+- Check whether the project ran `canon design css --figures`. The figure and figcaption styling ships unconditionally either way, but that flag alone embeds the Virgil and Excalifont font files. Without it, the figure falls back to the browser's own generic `cursive` face rather than the intended hand-drawn font, and Step 7's output names that gap when the flag was not passed.
+
+## Step 5: the freehand path
+
+- Author the SVG by hand: plain shapes and lines authored directly in the markup.
+- Follow the standard's `## Color and accessibility` section for every fill, stroke, and accessible name.
+
+There is no external render to verify a freehand drawing against. The check here is the stroke-and-fill audit above and a read of the markup against what the subject means to show, done once rather than looped.
+
+## Step 6: wrap, caption, and verify
+
+- Wrap the drawing in a `<figure>` element with a `<figcaption>` naming what to take from the figure, never what it shows. Let it run wider than the surrounding prose column.
+- On the Mermaid path, read the rendered PNG back and judge it against what the figure means to say, the same check `draft-diagram` Steps 5 and 6 run for the architecture surface. Fix the mermaid source and re-render on a defect. Stop after two correction passes. When a defect survives, keep the figure and name the defect in the output rather than reporting a false verification.
+- On either path, confirm the figure still reads once every color and font it depends on is stripped to its fallback, per the standard's own working-figure bar.
+- When the render fails for any reason, no browser engine, no network, no package manager, continue to Step 7 and name the skipped check. A missing renderer degrades the loop rather than failing it.
+
+## Step 7: confirm and write
+
+Show the destination path, the decided render path, and the full `<figure>` markup before writing. Confirm with the user, since the graph-shaped decision and the render verdict are judgment calls with no diff to preview either against.
+
+Write the figure into the destination document at the location the user named. Renders under `.canon/tmp/figures/` are verification artifacts, and the scratch PNG and JSON config are deleted after Step 6 confirms, since only the SVG ships.
+
+## Output
+
+### Preview
+
+**Destination:** `<path>`
+**Render path:** `<mermaid | freehand>`, `<one-sentence reason>`
+
+```html
+<drafted figure markup></drafted>
+```
+
+### After confirmation
+
+```plaintext
+✅ Drafted figure in <path>
+Verified render. <defect or skipped check, one line, omitted when clean>
+<Font not embedded: run `canon design css --figures` to ship Virgil and Excalifont. Omitted when the project already ran it.>
+```

package/docs/agents/commands.md

@@ -24,6 +24,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon docs [topic]`             | Emit toolkit reference docs (`list`, or a topic by name)                                                                                                                                                                                                                                                               |
 | `canon design render`            | Render `.claude/DESIGN.md` tokens to HTML and CSS                                                                                                                                                                                                                                                                      |
 | `canon design regen`             | Rewrite this repository's `.claude/DESIGN.md` and `src/design/base.css` from `src/design/tokens.ts`                                                                                                                                                                                                                    |
+| `canon design board`             | Generate a static page set indexing tokens, surfaces, wireframes, and past candidates, against the toolkit checkout like `regen` (`--out`)                                                                                                                                                                             |
 | `canon design css`               | Emit the design tokens and components as CSS on stdout (`--no-components` for properties alone)                                                                                                                                                                                                                        |
 | `canon design install`           | Install the base stylesheet into a project at `.claude/design/base.css`                                                                                                                                                                                                                                                |
 | `canon design sync`              | Update a base stylesheet already installed under `.claude/design/`                                                                                                                                                                                                                                                     |

package/docs/agents/design-board.md

@@ -0,0 +1,30 @@
+---
+title: Design board
+description: Generating a static index over the toolkit checkout's own design surfaces, what each panel reads, and why it never runs against a target
+---
+
+# Design board
+
+`canon design board [--out <path>]` generates a static page set indexing four design surfaces and reports the path a reader opens with `canon serve`. Like `canon design regen`, it runs against the toolkit checkout the CLI resolves its own root from, never against a target project's own files: a target holds none of the sources below, since none of `.claude/DESIGN.md`, `.claude/wireframes/`, `web/`, or the gitignored `.canon/` records ship with the published package. Running the installed CLI from inside a checkout of this project prints a mismatch warning when the caller's working directory disagrees with the root it resolved.
+
+Each panel reads what is already on disk and reports its own missing source rather than failing the run, so an absent build or an empty corpus renders an empty-state message instead of a broken frame.
+
+```bash
+canon design board
+canon serve .canon/review/board
+```
+
+| Option             | Default               | Behavior         |
+| ------------------ | --------------------- | ---------------- |
+| `-o, --out <path>` | `.canon/review/board` | Output directory |
+
+## Panels
+
+- **Tokens** renders `.claude/DESIGN.md` through the same renderer `canon design render` uses, rather than a second one.
+- **Surfaces** iframes the built landing page from `web/dist/` and a teach workspace from `.canon/teach/`, copying each whole into the board's own tree. Either reports its own missing build or absent workspace rather than rendering a broken frame.
+- **Wireframes** renders each of the six files under `.claude/wireframes/` as-is inside a `<pre>`, beside a line naming the surface it describes.
+- **Past candidates** lists an arm capture image per folder under `.canon/review/evidence/`, and states the corpus carries none rather than rendering an empty grid.
+
+## What it does not do
+
+The board never writes outside its own output directory and never builds `web/dist/` on a caller's behalf. `web/dist/` and `.canon/teach/` are read, not written, and copied into the board's tree only for that run: the generator clears and recreates its output directory on every call, so a caller relying on it to persist between runs is relying on an accident. It refuses rather than clearing a directory that is or contains the project root or the caller's own working directory, which is what an `--out .` typo would otherwise do, including when a global install resolves the project root to a different checkout than the one the caller stands in.

package/docs/agents/index.md

@@ -17,6 +17,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Context audit](context-audit.md): Running the audit, its flags and folder scope, the exit codes, the citation gate, and the widened gate the seed stage runs
 - [Self-stated counts](counts.md): Reading a sentence that asserts a closed catalog's size, how a match is decided, the plausibility filter that keeps a generic word from matching a subset, and why the sweep reports rather than gates
 - [Demo](demo.md): Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, reading numbered frames back out of a recording, the pointer the recording paints, and what each refusal reports
+- [Design board](design-board.md): Generating a static index over the toolkit checkout's own design surfaces, what each panel reads, and why it never runs against a target
 - [Docs](docs.md): How canon docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
 - [Driver](driver.md): Walking a page through named interactions, the probe catalog and the false finding each one carries, why viewport heights are never defaulted, and what each refusal reports
 - [Merge gate](gate.md): Running the gate this repository verifies a branch with, what the stage table holds and what stays a script, how the changed set scopes three stages, and why a stage that cannot read its input reports rather than passing

package/docs/workflow/ai-workflow.md

@@ -290,23 +290,24 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Generate an artifact on demand
 
-| Skill                     | When to use                                                                                       |
-| ------------------------- | ------------------------------------------------------------------------------------------------- |
-| `canon:create-rule`       | For a project-specific governance rule the toolkit does not ship                                  |
-| `canon:create-skill`      | For a new `SKILL.md`                                                                              |
-| `canon:create-snippet`    | For a reusable prompt                                                                             |
-| `canon:create-standard`   | For a new authoring convention                                                                    |
-| `canon:draft-docs`        | For a brand-new `docs/*.md` page, drafted against `standards/docs.md`                             |
-| `canon:draft-context`     | For a brand-new `.claude/context/<domain>.md` entry, drafted against `standards/context.md`       |
-| `canon:draft-wireframes`  | For a brand-new `.claude/wireframes/<surface>.md` file, drafted against `standards/wireframes.md` |
-| `canon:draft-readme`      | For a project's `README.md`, drafted against `standards/readme.md`                                |
-| `canon:bash-script`       | For an interactive, human-facing shell tool                                                       |
-| `canon:bash-cli-script`   | For a non-interactive automation, CI, or pipeline script                                          |
-| `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                |
-| `canon:draft-slides`      | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                             |
-| `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                     |
-| `canon:record-screencast` | For compiling and running a screencast draft into a recording and a still                         |
-| `canon:draft-identity`    | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop       |
+| Skill                     | When to use                                                                                                                         |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `canon:create-rule`       | For a project-specific governance rule the toolkit does not ship                                                                    |
+| `canon:create-skill`      | For a new `SKILL.md`                                                                                                                |
+| `canon:create-snippet`    | For a reusable prompt                                                                                                               |
+| `canon:create-standard`   | For a new authoring convention                                                                                                      |
+| `canon:draft-docs`        | For a brand-new `docs/*.md` page, drafted against `standards/docs.md`                                                               |
+| `canon:draft-context`     | For a brand-new `.claude/context/<domain>.md` entry, drafted against `standards/context.md`                                         |
+| `canon:draft-wireframes`  | For a brand-new `.claude/wireframes/<surface>.md` file, drafted against `standards/wireframes.md`                                   |
+| `canon:draft-figure`      | For a hand-drawn figure inside an existing doc, drafted against `standards/figures.md` and rendered through Mermaid or freehand SVG |
+| `canon:draft-readme`      | For a project's `README.md`, drafted against `standards/readme.md`                                                                  |
+| `canon:bash-script`       | For an interactive, human-facing shell tool                                                                                         |
+| `canon:bash-cli-script`   | For a non-interactive automation, CI, or pipeline script                                                                            |
+| `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                                                  |
+| `canon:draft-slides`      | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                                                               |
+| `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                                                       |
+| `canon:record-screencast` | For compiling and running a screencast draft into a recording and a still                                                           |
+| `canon:draft-identity`    | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop                                         |
 
 ### Answer a question at any point
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.75.1",
+  "version": "4.76.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/claude/cases/workflow.ts

@@ -28,6 +28,11 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
     prompt: 'Draw me a diagram of how the pieces of this system connect.',
     expect: 'draft-diagram',
   },
+  {
+    prompt:
+      'This onboarding doc needs a hand-drawn picture of the signup-to-active path, sketch it in and make sure it actually renders correctly.',
+    expect: 'draft-figure',
+  },
   {
     prompt:
       'Bring the internal planning docs under .claude up to date with what we decided this session.',

package/src/cli.ts

@@ -65,7 +65,7 @@ function showHelp(): void {
     `${GREY}│${NC}    wiki [cmd]         ${GREY}# Wiki commands (init)${NC}`,
     `${GREY}│${NC}    indexes [cmd]      ${GREY}# Regenerate index.md files (regen)${NC}`,
     `${GREY}│${NC}    docs [cmd|topic]   ${GREY}# Emit toolkit reference docs (list, <topic>)${NC}`,
-    `${GREY}│${NC}    design [cmd]       ${GREY}# Design system commands (render)${NC}`,
+    `${GREY}│${NC}    design [cmd]       ${GREY}# Design system commands (render, board)${NC}`,
     `${GREY}│${NC}    slides [cmd]       ${GREY}# Slide deck commands (render, list)${NC}`,
     `${GREY}│${NC}    capture [source]   ${GREY}# Render HTML capture sources to PNG${NC}`,
     `${GREY}│${NC}    serve [dir]        ${GREY}# Serve a directory over localhost and print the preview link${NC}`,
@@ -118,6 +118,7 @@ function showHelp(): void {
     `${GREY}│${NC}    canon docs list --json`,
     `${GREY}│${NC}    canon docs agents`,
     `${GREY}│${NC}    canon design render`,
+    `${GREY}│${NC}    canon design board`,
     `${GREY}│${NC}    canon slides render`,
     `${GREY}│${NC}    canon slides list --json`,
     `${GREY}│${NC}    canon capture assets/captures/install.html --selector .window --out assets`,

package/src/commands/design.ts

@@ -6,6 +6,7 @@ import {
   DESIGN_INSTALL_DIR,
   DESIGN_PROJECT_SUBDIR,
 } from '@/design/adapter'
+import { generateBoard } from '@/design/board'
 import { buildDesignCss } from '@/design/css'
 import { HAND_DRAWN_FONT_FACES } from '@/design/fonts'
 import { renderDesignDoc } from '@/design/render'
@@ -20,7 +21,9 @@ import { intro, logAdd, logError, logInfo, logWarn, outro, palette } from '@/ui'
 export function register(program: Command): void {
   const design = program
     .command('design')
-    .description('Design system commands (regen, css, render, install, sync)')
+    .description(
+      'Design system commands (regen, css, render, board, install, sync)',
+    )
 
   design
     .command('regen')
@@ -127,6 +130,48 @@ export function register(program: Command): void {
       )
     })
 
+  design
+    .command('board')
+    .description(
+      'Generate the design board, an index over this repository’s own design surfaces',
+    )
+    .option(
+      '-o, --out <path>',
+      'Output directory',
+      creationRel(process.cwd(), 'review', 'board'),
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Like regen, this runs against the toolkit checkout rather than a',
+        'target: it reads five sources already on disk relative to the',
+        'project root and writes a static page set, never installed or',
+        'synced. Open it with canon serve <out>.',
+        '',
+      ].join('\n'),
+    )
+    .action((opts: { out: string }) => {
+      const outDir = resolve(process.cwd(), opts.out)
+      const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
+      const mismatch = checkoutMismatchWarning(process.cwd())
+      process.stderr.write(
+        `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}Generate design board${NC}\n`,
+      )
+      if (mismatch !== undefined) logWarn(mismatch)
+      const result = generateBoard(PROJECT_ROOT, outDir, process.cwd())
+      if (!result.ok) {
+        process.stderr.write(
+          `${GREY}│${NC} ${RED}✗${NC} ${result.detail}\n${GREY}└${NC}\n`,
+        )
+        process.exitCode = 1
+        return
+      }
+      process.stderr.write(
+        `${GREY}│${NC} ${GREEN}✓${NC} ${relative(process.cwd(), result.indexPath)}\n${GREY}│${NC}   Open with: canon serve ${relative(process.cwd(), result.outDir)}\n${GREY}└${NC}\n`,
+      )
+    })
+
   design
     .command('install')
     .description('Install the base stylesheet into a project')

package/src/design/board.ts

@@ -0,0 +1,451 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { join, relative, sep } from 'node:path'
+import { DESIGN_DOCUMENT } from '@/design/regen'
+import { renderDesignDoc } from '@/design/render'
+import { colorValue } from '@/design/tokens'
+import { recordDir } from '@/record-root'
+
+/**
+ * The one named site for this repository's wireframe corpus. `standards/`
+ * moves it to `canon/wireframes/` under the answered
+ * `.canon/intake/88-surface-roots-and-corpus-debt/` item 1, and that move
+ * retargets this constant alone rather than a literal repeated per panel.
+ */
+export const WIREFRAME_DIR = join('.claude', 'wireframes')
+
+/** Landing page for the built site the surfaces panel iframes when present. */
+const WEB_DIST = join('web', 'dist')
+const WEB_DIST_ENTRY = 'index.html'
+
+interface WireframeEntry {
+  readonly path: string
+  readonly describes: string
+}
+
+/**
+ * The six files the wireframes panel renders, each beside the surface it
+ * describes. `index.md` at either level is a catalog rather than a wireframe
+ * and is excluded, which is why this list holds six rather than the eight
+ * files the corpus carries today.
+ */
+const WIREFRAMES: readonly WireframeEntry[] = [
+  { path: 'landing-page.md', describes: 'The canon.erclx.dev landing page' },
+  { path: 'slides.md', describes: 'The SLIDES.md render' },
+  { path: 'teach/root.md', describes: 'A teach workspace root listing' },
+  { path: 'teach/contents.md', describes: 'A workspace contents page' },
+  { path: 'teach/lesson.md', describes: 'A lesson page and quiz stepper' },
+  { path: 'teach/chrome.md', describes: 'The shared teach chrome' },
+]
+
+const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.svg', '.webp']
+
+export interface BoardPanel {
+  readonly id: string
+  readonly title: string
+  /** Relative to the board's own output directory. */
+  readonly path: string
+}
+
+export interface BoardResult {
+  readonly ok: true
+  readonly outDir: string
+  readonly indexPath: string
+  readonly panels: readonly BoardPanel[]
+}
+
+export interface BoardRefused {
+  readonly ok: false
+  readonly reason: 'unsafe-out'
+  readonly detail: string
+}
+
+export type BoardOutcome = BoardResult | BoardRefused
+
+/**
+ * Whether clearing `outDir` would take a protected directory down with it:
+ * the directory equals one of them, or contains one.
+ *
+ * `generateBoard` clears its output directory on every run, and `--out` is
+ * resolved against the caller's cwd while the panels read from `PROJECT_ROOT`.
+ * Those agree in the ordinary case and diverge in exactly one: a second
+ * checkout, where a global `canon` resolves `PROJECT_ROOT` to a different
+ * tree than the one the caller stands in. Guarding `PROJECT_ROOT` alone misses
+ * that case, since `--out .` then resolves under the caller's own cwd, which
+ * shares no containment with the unrelated root the guard compared it to.
+ */
+function wouldDeleteRoot(protect: readonly string[], outDir: string): boolean {
+  return protect.some((dir) => dir === outDir || dir.startsWith(outDir + sep))
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+const THEME_TOGGLE_BUTTON = `<button class="theme-toggle" type="button" aria-label="Switch between light and dark"><svg class="sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg><svg class="moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z"/></svg></button>`
+
+const THEME_TOGGLE_SCRIPT = [
+  '<script>(function(){',
+  'var r=document.documentElement;',
+  'try{var s=localStorage.getItem("board-theme");if(s)r.dataset.theme=s;}catch(e){}',
+  'document.addEventListener("click",function(e){',
+  'var b=e.target.closest(".theme-toggle");if(!b)return;',
+  'var dark=r.dataset.theme==="dark"||(!r.dataset.theme&&matchMedia("(prefers-color-scheme: dark)").matches);',
+  'r.dataset.theme=dark?"light":"dark";',
+  'try{localStorage.setItem("board-theme",r.dataset.theme);}catch(e){}',
+  '});',
+  '})();</script>',
+].join('')
+
+/**
+ * Highlights the nav link for whichever section fills the most of the
+ * viewport, following the same largest-intersection-ratio rule the landing
+ * page's own floating pill uses, so a reader scrolling through the four
+ * panels sees the pill track their position rather than sitting static.
+ */
+const SCROLLSPY_SCRIPT = [
+  '<script>(function(){',
+  'var links={};',
+  'document.querySelectorAll("nav a[href^=\\"#\\"]").forEach(function(a){links[a.getAttribute("href").slice(1)]=a;});',
+  'var ratios={};',
+  'var current="";',
+  'var observer=new IntersectionObserver(function(entries){',
+  'entries.forEach(function(entry){ratios[entry.target.id]=entry.isIntersecting?entry.intersectionRatio:0;});',
+  'var bestId="";',
+  'var bestRatio=0;',
+  'Object.keys(ratios).forEach(function(id){if(ratios[id]>bestRatio){bestRatio=ratios[id];bestId=id;}});',
+  'if(bestId&&bestId!==current){',
+  'if(links[current])links[current].classList.remove("active");',
+  'current=bestId;',
+  'if(links[current])links[current].classList.add("active");',
+  '}',
+  '},{threshold:[0,0.25,0.5,0.75,1]});',
+  'Object.keys(links).forEach(function(id){',
+  'var section=document.getElementById(id);',
+  'if(section)observer.observe(section);',
+  '});',
+  '})();</script>',
+].join('')
+
+/**
+ * The same brand mark `src/design/render.ts` embeds in its own preview,
+ * colored with the dark accent since the board's default chrome is dark
+ * where that preview's is light. Duplicated here rather than imported,
+ * following that module's own precedent of three independently-colored
+ * copies rather than a shared icon helper for the first second caller.
+ */
+function faviconLink(): string {
+  const color = colorValue('accent') ?? '#e0724b'
+  const href = `data:image/svg+xml,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 10 80 80"><path d="M34,20 L15,28 L15,72 L34,80 Z M66,20 L85,28 L85,72 L66,80 Z" fill="${color}" /><rect x="44" y="15" width="12" height="70" rx="2" fill="${color}" /></svg>`,
+  )}`
+  return `<link rel="icon" href="${href}">`
+}
+
+/** The board shell's own chrome, read off the toolkit's design source. */
+function shellChrome(): string {
+  const roles: ReadonlyArray<readonly [string, string]> = [
+    ['background', 'background'],
+    ['surface', 'surface'],
+    ['text', 'text'],
+    ['muted', 'muted'],
+    ['border', 'border'],
+    ['accent', 'accent'],
+  ]
+  const dark = roles
+    .map(([name, role]) => {
+      const value = colorValue(role)
+      return value === undefined ? '' : `  --board-${name}: ${value};`
+    })
+    .filter((line) => line !== '')
+  const light = roles
+    .map(([name, role]) => {
+      const value = colorValue(`light-${role}`)
+      return value === undefined ? '' : `  --board-${name}: ${value};`
+    })
+    .filter((line) => line !== '')
+
+  return `:root {\n${dark.join('\n')}\n}\n[data-theme='light'] {\n${light.join('\n')}\n}`
+}
+
+function shellHtml(panels: readonly BoardPanel[]): string {
+  const navLinks = panels
+    .map((panel) => `<a href="#${panel.id}">${escapeHtml(panel.title)}</a>`)
+    .join('')
+
+  const sections = panels
+    .map(
+      (panel, index) =>
+        `<section id="${panel.id}">\n<div class="eyebrow">Panel 0${index + 1}</div>\n<h2>${escapeHtml(panel.title)}</h2>\n<iframe src="${panel.path}" loading="lazy"></iframe>\n</section>`,
+    )
+    .join('\n')
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+${faviconLink()}
+<title>Design board</title>
+<style>
+${shellChrome()}
+* { box-sizing: border-box; }
+body { font-family: 'Noto Sans Mono', 'DejaVu Sans Mono', monospace; margin: 0; color: var(--board-text); background: var(--board-background); }
+header { padding: 2.5rem 3rem 1.5rem; }
+h1 { margin: 0 0 0.4rem; font-size: 1.6rem; font-weight: 600; letter-spacing: -0.01em; }
+.meta { color: var(--board-muted); font-size: 0.85rem; margin: 0; }
+nav { position: fixed; top: 1.25rem; left: 50%; transform: translateX(-50%); z-index: 1; display: flex; align-items: center; gap: 1.25rem; padding: 0.5rem 0.6rem 0.5rem 1.1rem; background: var(--board-surface); border: 1px solid var(--board-border); border-radius: 999px; box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25); white-space: nowrap; }
+nav a { color: var(--board-muted); text-decoration: none; font-size: 0.8rem; }
+nav a:hover { color: var(--board-accent); }
+nav a.active { color: var(--board-accent); }
+.theme-toggle { display: flex; align-items: center; justify-content: center; width: 1.8rem; height: 1.8rem; background: var(--board-background); color: var(--board-text); border: 1px solid var(--board-border); border-radius: 50%; padding: 0; cursor: pointer; }
+.theme-toggle .sun { display: none; }
+.theme-toggle .moon { display: block; }
+[data-theme='light'] .theme-toggle .sun { display: block; }
+[data-theme='light'] .theme-toggle .moon { display: none; }
+.theme-toggle svg { width: 0.95rem; height: 0.95rem; }
+main { padding: 0 3rem 4.5rem; }
+section { margin-top: 2.5rem; padding-top: 1.25rem; border-top: 1px solid var(--board-border); scroll-margin-top: 4.5rem; }
+.eyebrow { color: var(--board-accent); font-size: 0.7rem; letter-spacing: 0.12em; text-transform: uppercase; margin-bottom: 0.35rem; }
+section h2 { margin: 0 0 0.75rem; font-size: 1.1rem; font-weight: 600; }
+iframe { width: 100%; height: 480px; border: 1px solid var(--board-border); border-radius: 4px; background: var(--board-surface); }
+</style>
+</head>
+<body>
+<header>
+<h1>Design board</h1>
+<p class="meta">Generated by <code>canon design board</code>. Repository-local, never installed into a target.</p>
+</header>
+<nav>${navLinks}${THEME_TOGGLE_BUTTON}</nav>
+<main>
+${sections}
+</main>
+${THEME_TOGGLE_SCRIPT}
+${SCROLLSPY_SCRIPT}
+</body>
+</html>
+`
+}
+
+function panelPage(title: string, body: string): string {
+  const accent = colorValue('light-accent') ?? '#a4471c'
+  const surface = colorValue('light-surface') ?? '#f4efe6'
+  const border = colorValue('light-border') ?? '#e4dcd0'
+  const muted = colorValue('light-muted') ?? '#726b62'
+  const text = colorValue('light-text') ?? '#1a1815'
+  const background = colorValue('light-background') ?? '#faf7f2'
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+${faviconLink()}
+<title>${escapeHtml(title)}</title>
+<style>
+* { box-sizing: border-box; }
+body { font-family: 'Noto Sans Mono', 'DejaVu Sans Mono', monospace; margin: 0; padding: 1.75rem 2.25rem; color: ${text}; background: ${background}; }
+h2 { margin: 2rem 0 0.6rem; padding-top: 1.1rem; border-top: 1px solid ${border}; font-size: 1rem; font-weight: 600; }
+h2:first-of-type { margin-top: 0; padding-top: 0; border-top: none; }
+p { color: ${muted}; font-size: 0.85rem; }
+table { border-collapse: collapse; width: 100%; margin-top: 0.5rem; font-size: 0.85rem; }
+td, th { padding: 0.4rem 0.6rem; border-bottom: 1px solid ${border}; text-align: left; }
+pre { white-space: pre-wrap; background: ${surface}; border-radius: 4px; padding: 1rem; font-size: 0.8rem; }
+img { border-radius: 4px; border: 1px solid ${border}; margin-top: 0.5rem; }
+a { color: ${accent}; }
+.empty { color: ${muted}; font-style: italic; background: ${surface}; border-radius: 4px; padding: 0.9rem 1rem; }
+</style>
+</head>
+<body>
+${body}
+</body>
+</html>
+`
+}
+
+function writeTokensPanel(root: string, outDir: string): void {
+  const sourcePath = join(root, DESIGN_DOCUMENT)
+  const dir = join(outDir, 'tokens')
+
+  if (!existsSync(sourcePath)) {
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(
+      join(dir, 'index.html'),
+      panelPage(
+        'Tokens',
+        `<p class="empty">No ${DESIGN_DOCUMENT} at the repository root.</p>`,
+      ),
+    )
+    return
+  }
+
+  renderDesignDoc(sourcePath, dir)
+}
+
+function writeWireframesPanel(root: string, outDir: string): void {
+  const dir = join(outDir, 'wireframes')
+  mkdirSync(dir, { recursive: true })
+
+  const sections = WIREFRAMES.map((entry) => {
+    const sourcePath = join(root, WIREFRAME_DIR, entry.path)
+    if (!existsSync(sourcePath)) {
+      return `<h2>${escapeHtml(entry.path)}</h2>\n<p class="empty">Missing from ${WIREFRAME_DIR}/.</p>`
+    }
+    const text = readFileSync(sourcePath, 'utf8')
+    return `<h2>${escapeHtml(entry.path)}</h2>\n<p>${escapeHtml(entry.describes)}</p>\n<pre>${escapeHtml(text)}</pre>`
+  }).join('\n')
+
+  writeFileSync(join(dir, 'index.html'), panelPage('Wireframes', sections))
+}
+
+/** Copies a built directory whole, filtering nothing, into the board's own tree. */
+function copyBuilt(source: string, dest: string): void {
+  rmSync(dest, { recursive: true, force: true })
+  cpSync(source, dest, { recursive: true })
+}
+
+function writeSurfacesPanel(root: string, outDir: string): void {
+  const dir = join(outDir, 'surfaces')
+  mkdirSync(dir, { recursive: true })
+
+  const distSource = join(root, WEB_DIST)
+  const landingBody = existsSync(join(distSource, WEB_DIST_ENTRY))
+    ? (copyBuilt(distSource, join(dir, 'landing')),
+      '<iframe src="landing/index.html" loading="lazy"></iframe>')
+    : `<p class="empty">No ${WEB_DIST}/ build. Run bun run web:build, then regenerate the board.</p>`
+
+  const teachSource = recordDir(root, 'teach')
+  const teachBody = existsSync(join(teachSource, 'index.html'))
+    ? (copyBuilt(teachSource, join(dir, 'teach')),
+      '<iframe src="teach/index.html" loading="lazy"></iframe>')
+    : `<p class="empty">${relative(root, teachSource)} is gitignored and machine-local, so this panel renders empty in a fresh clone and on CI.</p>`
+
+  writeFileSync(
+    join(dir, 'index.html'),
+    panelPage(
+      'Surfaces',
+      `<h2>Landing page</h2>\n${landingBody}\n<h2>Teach workspaces</h2>\n${teachBody}`,
+    ),
+  )
+}
+
+function isImage(name: string): boolean {
+  return IMAGE_EXTENSIONS.some((ext) => name.toLowerCase().endsWith(ext))
+}
+
+/** Every image file directly inside an evidence arm folder, one level deep. */
+function imagesIn(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && isImage(entry.name))
+    .map((entry) => entry.name)
+    .sort()
+}
+
+function writeCandidatesPanel(root: string, outDir: string): void {
+  const dir = join(outDir, 'candidates')
+  mkdirSync(dir, { recursive: true })
+
+  const evidenceDir = recordDir(root, 'review', 'evidence')
+  if (!existsSync(evidenceDir)) {
+    writeFileSync(
+      join(dir, 'index.html'),
+      panelPage(
+        'Past candidates',
+        `<p class="empty">No ${relative(root, evidenceDir)} folder yet.</p>`,
+      ),
+    )
+    return
+  }
+
+  const folders = readdirSync(evidenceDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+
+  const found: Array<{ folder: string; images: string[] }> = []
+  for (const folder of folders) {
+    const images = imagesIn(join(evidenceDir, folder))
+    if (images.length > 0) {
+      cpSync(join(evidenceDir, folder), join(dir, folder), { recursive: true })
+      found.push({ folder, images })
+    }
+  }
+
+  if (found.length === 0) {
+    writeFileSync(
+      join(dir, 'index.html'),
+      panelPage(
+        'Past candidates',
+        `<p class="empty">${folders.length} folders under ${relative(root, evidenceDir)}/ and none carries a draft-and-pick arm capture. The archival capture step has not run since it shipped.</p>`,
+      ),
+    )
+    return
+  }
+
+  const sections = found
+    .map(
+      ({ folder, images }) =>
+        `<h2>${escapeHtml(folder)}</h2>\n${images.map((image) => `<img src="${folder}/${image}" alt="${escapeHtml(image)}">`).join('\n')}`,
+    )
+    .join('\n')
+
+  writeFileSync(join(dir, 'index.html'), panelPage('Past candidates', sections))
+}
+
+/**
+ * Generates the board's page set into `outDir`, clearing whatever was there.
+ *
+ * This function is the directory's only writer, per the constraint every
+ * caller shares it under: `canon serve` and a future `canon capture` pass
+ * both read the result and neither may assume it exists ahead of a run.
+ *
+ * `cwd` is the caller's own working directory, resolved and passed in
+ * explicitly rather than read here, so a test can exercise the checkout-
+ * mismatch case without touching the process's real cwd.
+ */
+export function generateBoard(
+  root: string,
+  outDir: string,
+  cwd: string,
+): BoardOutcome {
+  if (wouldDeleteRoot([root, cwd], outDir)) {
+    return {
+      ok: false,
+      reason: 'unsafe-out',
+      detail: `${outDir} is or contains ${root} or ${cwd}. Refusing to clear it.`,
+    }
+  }
+
+  rmSync(outDir, { recursive: true, force: true })
+  mkdirSync(outDir, { recursive: true })
+
+  const panels: readonly BoardPanel[] = [
+    { id: 'tokens', title: 'Tokens', path: 'tokens/index.html' },
+    { id: 'surfaces', title: 'Surfaces', path: 'surfaces/index.html' },
+    { id: 'wireframes', title: 'Wireframes', path: 'wireframes/index.html' },
+    {
+      id: 'candidates',
+      title: 'Past candidates',
+      path: 'candidates/index.html',
+    },
+  ]
+
+  writeTokensPanel(root, outDir)
+  writeSurfacesPanel(root, outDir)
+  writeWireframesPanel(root, outDir)
+  writeCandidatesPanel(root, outDir)
+
+  const indexPath = join(outDir, 'index.html')
+  writeFileSync(indexPath, shellHtml(panels))
+
+  return { ok: true, outDir, indexPath, panels }
+}