@erclx/canon 5.23.0 → 5.25.0

package/src/pr/rest.ts

@@ -0,0 +1,137 @@
+/**
+ * The REST shapes `canon pr` reads a pull request through, put into the shapes
+ * its readers already take.
+ *
+ * A cloud session's GitHub proxy refuses GraphQL and serves REST, and every
+ * `gh pr view` runs on GraphQL. The verbs therefore read the pulls, reviews,
+ * and issue-comments endpoints, and this module is the one boundary where
+ * those payloads meet the field names the rest of `src/pr/` was written
+ * against.
+ */
+import type { ReviewRow } from '@/pr/review-scope'
+
+/** One row of `repos/{owner}/{repo}/pulls/<n>` or of the pulls listing. */
+export interface RestPull {
+  readonly number?: number
+  readonly body?: string | null
+  readonly head?: { readonly ref?: string; readonly sha?: string }
+  readonly base?: { readonly ref?: string }
+  readonly mergeable_state?: string
+}
+
+/** One row of `repos/{owner}/{repo}/pulls/<n>/reviews`. */
+export interface RestReview {
+  readonly body?: string | null
+  readonly commit_id?: string | null
+  readonly submitted_at?: string | null
+}
+
+/** One row of `repos/{owner}/{repo}/issues/<n>/comments`. */
+export interface RestComment {
+  readonly html_url?: string
+  readonly body?: string | null
+}
+
+/** The head branch, reported head, and base of the pull request a caller named. */
+export interface PullIdentity {
+  readonly number: number | undefined
+  readonly branch: string
+  readonly head?: string
+  readonly base?: string
+  readonly mergeState?: string
+}
+
+export type BranchPull =
+  | { readonly kind: 'found'; readonly number: number }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'gh-failed' | 'ambiguous-pull'
+    }
+
+/**
+ * Spells `mergeable_state` the way GraphQL's `mergeStateStatus` spells it.
+ *
+ * The two vocabularies hold the same values in different cases, so the
+ * mapping is a case change. `unknown` stays `UNKNOWN`, which `withMergeState`
+ * already reads as not conflicted while GitHub computes the state lazily.
+ */
+export function mergeStateOf(state: string | undefined): string | undefined {
+  return state === undefined || state === '' ? undefined : state.toUpperCase()
+}
+
+export function identityOf(row: RestPull): PullIdentity {
+  const mergeState = mergeStateOf(row.mergeable_state)
+  return {
+    number: row.number,
+    branch: row.head?.ref ?? '',
+    ...(row.head?.sha !== undefined && { head: row.head.sha }),
+    ...(row.base?.ref !== undefined && { base: row.base.ref }),
+    ...(mergeState !== undefined && { mergeState }),
+  }
+}
+
+/**
+ * The one open pull request a branch carries.
+ *
+ * Two open pull requests on one head against different bases refuse rather
+ * than resolving to the first, since the listing's order says nothing about
+ * which one the caller meant.
+ */
+export function selectBranchPull(rows: readonly RestPull[]): BranchPull {
+  const numbers = rows
+    .map((row) => row.number)
+    .filter((number): number is number => number !== undefined)
+  if (numbers.length > 1) return { kind: 'refused', reason: 'ambiguous-pull' }
+  const [number] = numbers
+  return number === undefined
+    ? { kind: 'refused', reason: 'gh-failed' }
+    : { kind: 'found', number }
+}
+
+/**
+ * A pending review carries no `submitted_at`, which reads as null the way the
+ * GraphQL listing reported it.
+ */
+export function reviewRowOf(review: RestReview): ReviewRow {
+  return {
+    body: review.body ?? '',
+    commit:
+      review.commit_id === undefined || review.commit_id === null
+        ? null
+        : { oid: review.commit_id },
+    submittedAt: review.submitted_at ?? null,
+  }
+}
+
+/** `html_url` ends in the same `#issuecomment-<id>` anchor GraphQL's `url` did. */
+export function commentRowOf(comment: RestComment): {
+  readonly url?: string
+  readonly body: string
+} {
+  return {
+    ...(comment.html_url !== undefined && { url: comment.html_url }),
+    body: comment.body ?? '',
+  }
+}
+
+/**
+ * Parses the output of `gh api --paginate --jq '.[] | @json'`, one compact
+ * object per line across every page.
+ *
+ * A filter that reshapes each row makes `--paginate` emit one value per page
+ * rather than one merged array, so a line per row is the form that survives
+ * paging. A line that does not parse refuses the whole listing, since a list
+ * short by one review reads as a thread missing its newest pass.
+ */
+export function parseJsonLines<T>(stdout: string): T[] | undefined {
+  const rows: T[] = []
+  for (const line of stdout.split('\n')) {
+    if (line.trim() === '') continue
+    try {
+      rows.push(JSON.parse(line) as T)
+    } catch {
+      return undefined
+    }
+  }
+  return rows
+}

package/standards/canvas.md

@@ -0,0 +1,112 @@
+---
+title: Canvas reference
+description: Page folders, frame files, the layout.json shape, token resolution, and what a frame must not assume on a local design canvas
+---
+
+# Canvas reference
+
+Applies to the canvas content under `.canon/canvas/`, where each page is a folder of HTML frames and a layout file placing them. A frame is a draft drawn to be looked at and picked from, so it changes whenever someone tries a direction, and the operator clears it once the direction lands where the project keeps its design.
+
+The folder is gitignored, so nothing in a repository checks its shape and nothing backs it up by default.
+
+## Scope
+
+Governs the canvas content under `.canon/canvas/`: page folder names, frame files, the `layout.json` shape, how tokens reach a frame, and what a frame must not assume about where it renders.
+
+Does not govern:
+
+- The design decisions a frame is drafting, such as type, color, and layout taste: the project's own design document
+- The project's design document and the token module it renders from, which a picked direction is carried into: `design.md`
+- The procedure that starts the canvas, reads the operator's selection, and carries a pick back, which belongs to the surface driving the canvas
+- Voice, rhythm, and sentence construction in any text a frame shows: the `write-human` skill
+
+## What a working canvas looks like
+
+A canvas works when the operator and a session can point at the same thing and see the same thing:
+
+- Which pages exist, and which frames sit on each?
+- Where does each frame sit on its page, and at what width does it render?
+- Does each frame show the project's own tokens rather than values copied into it?
+- Does a frame render the same in the live canvas as in a capture?
+
+A canvas failing these is non-conforming even when it satisfies every shape rule below.
+
+## Pages
+
+- Make one folder per page directly under `.canon/canvas/`. A page groups the frames compared side by side, such as the candidates for one decision.
+- Name a page as one path segment of letters, digits, dots, dashes, and underscores, starting with a letter or a digit. A name opening with a dot is hidden from every listing.
+- Never write a folder whose name opens with a dot. Those names are reserved for files the canvas generates and removes itself.
+- Rename a page rather than copying it under a new name, so its layout and frames stay together.
+
+## Frames
+
+- Write one frame as one `.html` file inside its page folder. The filename without its extension is the frame's name, and the name follows the page naming rule.
+- Write each frame as a whole document, with a doctype, a `head`, and a `body`. A fragment gets elements the browser builds around it, and an address the operator picks inside it can no longer be matched to the file.
+- Write every table with its `tbody` stated, for the same reason. A browser adds one the file leaves out.
+- Keep a frame self-contained. Inline its own styles and scripts, or link a file inside the same page folder, since a frame is served from its page and nothing outside the canvas resolves.
+- Use the project's custom properties, `var(--<name>)`, for every value the token stylesheet defines. A literal copied from it shows the right color today and the wrong one after the next token change.
+- Edit a frame by rewriting its file. The file is the frame, and nothing else holds a copy of its markup.
+
+## Layout
+
+- Keep one `layout.json` per page, beside its frames. It holds each frame's box and nothing else, so moving a frame never rewrites its markup.
+- Key each box by the frame's name, under one top-level `frames` object.
+- Give every box four finite numbers in pixels: `x` and `y` for its top-left corner on the page, `width` for the width the frame renders at, and `height` for the height it shows on the canvas.
+- Leave a frame out of the layout only when its position does not matter yet. A reader places an unnamed frame in a row after the others, at the default size of 1440 by 900.
+- Never write the file while a writer holds its lock, which is the same name with `.lock` appended. Two writers each replacing the whole file lose one of the two edits.
+- Treat a layout that does not parse as a defect to repair, never as an empty one to overwrite. Writing over it erases every box it held.
+
+The keys below are the ones a reader parses. The frame names are placeholders.
+
+```json
+{
+  "frames": {
+    "hero-a": { "x": 0, "y": 0, "width": 1440, "height": 900 },
+    "hero-b": { "x": 1520, "y": 0, "width": 1440, "height": 900 }
+  }
+}
+```
+
+## Tokens
+
+- Expect the token stylesheet first in every frame's `head` when it is served, ahead of anything the frame links. A stylesheet the frame links itself still wins the cascade.
+- Read where the tokens come from in this order: the canvas tool's own module inside its own checkout, else the project's installed base stylesheet plus anything in its project override folder, else none. A canvas with no token source renders unstyled and says so.
+- Never paste the token stylesheet into a frame. The injected copy follows the project, and a pasted one stops following it the moment it is written.
+
+## What a frame must not assume
+
+- Do not assume a viewport. A frame renders at its layout width on the canvas and in a capture alike, so size it with media queries against that width rather than against the operator's window.
+- Do not assume the theme. The canvas theme toggle is the operator's own state, and a capture shows each frame in its default theme.
+- Do not assume a network. Name only fonts the machine has, or ship the font beside the frame, since a capture refuses a frame naming a font it cannot find.
+- Do not assume a default font. Set `font-family` on the `html` element with an installed family first, since a capture checks the root's first family and the browser's default serif is absent from many machines.
+- Do not assume the frame is the source. A picked direction is carried into the project's design document or its wireframes, and the operator clears the frame once it has been carried.
+- Do not assume the canvas survives the checkout. The folder is gitignored, so a lost checkout loses every page in it.
+
+## Template
+
+A new frame starts from this skeleton. The names in it are placeholders.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>frame-name</title>
+    <style>
+      html {
+        font-family: installed-family, sans-serif;
+      }
+      main {
+        padding: var(--space-lg);
+        color: var(--color-text);
+        background: var(--color-background);
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>frame-name</h1>
+    </main>
+  </body>
+</html>
+```

package/standards/context.md

@@ -21,7 +21,8 @@ Does not govern:
 - Decisions filling a stack, delivery, boundary, layout, or build-principle slot, and system-wide risks: `architecture.md`
 - Product scope, goals, and non-goals: `requirements.md`
 - Path-scoped coding rules: `rule.md`
-- Diagrams and wireframes, which answer structure and layout questions an entry hands off: `diagrams.md` and `wireframes.md`
+- Wireframes, which answer layout questions an entry hands off: `wireframes.md`
+- Figures and architecture views, which answer structure questions an entry hands off: the `draft-figure` skill
 - The consumer-facing reference under `docs/`, whose reader is operating the project without the source open: `docs.md`
 
 ## Organizing principle

package/standards/design.md

@@ -33,10 +33,20 @@ Does not govern:
 
 ## Format
 
-- Use tables for token systems, one row per token. Use short bullets for component rules, one decision per line.
+- Use tables for token systems, one row per token. Write every other rule as a short bullet, one decision per line, within `## Prose budget`.
 - Plain English over technical notation. If a section could be removed and the developer would still build correctly from wireframes and code alone, remove it.
 - Keep table headers and role names intact so the render tooling can parse the token tables.
 
+## Prose budget
+
+The record is a lookup, so its prose stays short enough to scan beside the tables. Why a value was chosen belongs in the project's context entry for design, never here.
+
+- Personality: one paragraph of at most 60 words
+- Any other section: at most 3 rules beside its table, each at most 25 words. A bullet is one rule, and so is a paragraph.
+- The lead before the first section: at most 40 words
+
+Headings and table rows are never counted, and a section holding a table and no rules is within budget. A bullet wrapping over several lines counts as one rule, and a nested bullet counts as its own.
+
 ## The uncertainty tag
 
 A cell no source anchors ends in ` ? verify`, written inside the cell rather than as a trailing column, since a trailing marker breaks the table parse. A cell wrapping itself in a code span carries the tag inside the span, as in `` `#ffffff ? verify` ``. Both spellings parse.
@@ -93,9 +103,9 @@ The column headers are the strings the renderer parses, read by exact key, so th
 
 ## Motion
 
-<whether motion is used at all, and if so the default duration and easing>
+- <whether motion is used at all, and if so the default duration and easing>
 
 ## Iconography
 
-<style, source library, and whether custom icons are allowed>
+- <style, source library, and whether custom icons are allowed>
 ```

package/standards/figures.md

@@ -14,7 +14,6 @@ Governs a hand-drawn figure wherever one is authored, naming no path because an
 Does not govern:
 
 - Direction, layout, node and edge budgets, labels, and render verification for the Mermaid path: `mermaid.md`
-- The toolkit's own architecture-diagram surface at `.canon/diagrams/`, which shares no code, font, or visual language with this convention: `diagrams.md`
 - Language, word choice, punctuation, and formatting in the caption or surrounding prose: `markdown.md`
 - Voice, rhythm, and sentence construction in that prose: the `write-human` skill
 - Which document types may carry a figure, and what else they require: that document type's own standard

package/standards/index.md

@@ -10,10 +10,10 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Architecture reference](architecture.md): Shape and content rules for canon/ARCHITECTURE.md
 - [Board reference](board.md): Readiness groups, row cells, and ordering for priority.md, the unordered backlog.md beside it, and the generated index under .canon/tasks/
 - [Branch reference](branch.md): Branch naming format and type conventions
+- [Canvas reference](canvas.md): Page folders, frame files, the layout.json shape, token resolution, and what a frame must not assume on a local design canvas
 - [Commit reference](commit.md): Commit message format and type conventions
 - [Context entry reference](context.md): Shape and content rules for canon/context/<domain>.md entries
 - [Design reference](design.md): Shape and content rules for canon/DESIGN.md
-- [Diagram reference](diagrams.md): Shape and content rules for .canon/diagrams/<kind>.md files
 - [Docs reference](docs.md): Reader and jurisdiction, frontmatter, page structure, what a page links out to, the diagram permission, and when a category earns a subfolder
 - [Figure reference](figures.md): When a figure earns its place, the render-first policy for a graph-shaped subject, freehand SVG as the escape hatch, and its wrapping, color, and accessibility rules
 - [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries

package/standards/markdown.md

@@ -7,6 +7,7 @@ rule:
   - 'Read it before a substantial markdown edit. Do not work the banned characters from memory.'
   - 'Run `canon markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.'
   - 'Voice, rhythm, and sentence construction are a separate topic. `800-prose` routes them.'
+  - 'Load the `canon:draft-figure` skill before drafting or revising a Mermaid fence or a figure, and report it rather than proceeding silently when it does not resolve.'
 ---
 
 # Markdown reference

package/standards/mermaid.md

@@ -1,12 +1,6 @@
 ---
 title: Mermaid reference
 description: Direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram
-paths:
-  - '**/*.md'
-rule:
-  - 'Apply this rule only when the edit drafts or revises a Mermaid fence. Skip it on a markdown edit carrying no diagram.'
-  - 'Read it before drafting the fence. Do not work the layout or the budgets from memory.'
-  - 'Which diagram a document carries and what question it answers is a separate topic. The diagrams standard routes it.'
 ---
 
 # Mermaid reference
@@ -19,7 +13,7 @@ Governs the Mermaid attribute wherever a fence is written, naming no path becaus
 
 Does not govern:
 
-- Which diagram a document carries, what question it answers, its frontmatter, and the explanation prose beneath it: `diagrams.md`
+- Which architecture view a figure draws and what question it answers: the `draft-figure` skill's architecture set
 - Language, word choice, punctuation, and formatting in the prose around a fence: `markdown.md`
 - Voice, rhythm, and sentence construction in that prose: the `write-human` skill
 - The mechanism behind any component a diagram draws: `context.md`

package/tooling/claude/reference.md

@@ -23,7 +23,6 @@ canon/
 
 .canon/
 ├── tasks/             ← seeded. One file per task plus a generated index.md, local scratch only. `archive/` holds the tasks that shipped.
-├── diagrams/          ← seeded. Per-kind Mermaid views. `index.md` is the discovery anchor. `<kind>.md` files hold one diagram each, grouped by the `category` frontmatter field.
 ├── plans/             ← execution detail for multi-step tasks. `feature-*.md` entries swept by context-fold into `archive/`.
 ├── review/            ← one subfolder per producer. `branch/` for review-branch, `feedback/` for canon feedback, `memory/` for memory-review with its own `archive/`, `design/` for canon design render.
 ├── tmp/               ← ephemeral scratch space, safe to delete without loss
@@ -60,10 +59,6 @@ Convert by hand, once per project:
 2. Replace `MEMORY.md` with an `index.md` carrying `title` and `subtitle` frontmatter and nothing else.
 3. Run `canon indexes regen --no-stage --root . .canon/memory/index.md` to build the catalog, and compare its entry count against the file count before deleting anything.
 
-## Upgrading from a single-file diagram set
-
-A project installed before the diagram surface became a folder still holds `.claude/DIAGRAMS.md`. Unlike the board, this one migrates itself. The `draft-diagram` skill reads the flat file when `.canon/diagrams/` holds no entries, splits it by kind into the folder, and reports what it wrote. The old file stays on disk so the split can be compared against its source, and deleting it is a manual step once that check passes.
-
 ## Gitignore
 
 - `# Claude`: `.canon/`, `.claude/worktrees/`, `.claude/.tmp/` <!-- canon-keep-record-root -->

package/tooling/claude/seeds/.claude/hooks/scratch-guard.sh

@@ -57,5 +57,5 @@ marker="$marker_dir/$key"
 mkdir -p "$marker_dir"
 : >"$marker"
 
-msg='Temporary file write outside the project scratch folder. Write temp files to .canon/tmp/<slug>/ in the project root, or .claude/.tmp/<slug>/ where the project carries no .canon/ root, not system temp. See the Scratch rule (604-scratch, under canon/ in your installed governance rules).'
+msg='Temporary file write outside the project scratch folder. Write temp files to .canon/tmp/<slug>/ in the project root, not system temp. See the Scratch rule (604-scratch, under canon/ in your installed governance rules).'
 jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

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

@@ -1,45 +0,0 @@
----
-name: draft-diagram
-description: Why diagrams are a folder of per-kind entries rather than one file, and why the verified marker is spent only on a render that was read back
----
-
-# Draft diagram requirement
-
-## Gap
-
-Without this skill, a session asked to refresh one view rewrites the whole surface, so four diagrams nobody checked change in the same commit and the reviewer cannot tell which one the pass was about. It picks a filename of its own, and the next refresh writes a duplicate beside the old entry instead of finding it. It reaches for C4, state, or class diagrams that render differently in every viewer.
-
-The verification failure is the expensive one. A mermaid source can satisfy every rule in the standard and still render as a picture that asserts something false about the system, so a session that judges the source and stamps the entry as verified has spent the only signal a reader has on a diagram nobody looked at. The standards hook toggles off inside a fenced block, so a banned character in a node label passes silently while the same character one line below is caught.
-
-## Must
-
-- Write one entry per kind under the filename and category the standard fixes, so a later refresh finds its target
-- Pick which entries this pass writes from whether the source signal exists and whether the pass has reason to touch it
-- Stay inside `flowchart` and `sequenceDiagram`
-- Render every entry this pass wrote and read the image back against what the entry means to say
-- Stamp the verified marker only on an entry whose render was read back and judged correct
-- Name every skipped render and every surviving defect in the output
-- Regenerate the catalog from sibling frontmatter after the last entry is written
-- Read the node labels by hand, since no hook checks inside a fence
-
-## Must not
-
-- Rewrite an entry this pass had no reason to touch, or report one as written when it was left alone
-- Stamp an untouched entry, a skipped render, or an entry whose defect survived
-- Report a clean verification when a check did not run
-- Commit a render, which is a verification artifact rather than a deliverable
-- Redraw a diagram during a migration pass, since a rewrite and a move landing together leaves no way to tell which one broke it
-- Loop on a defect past two correction passes
-
-## Guards
-
-- No architecture file, no requirements file, and no folder structure to scan: stop, because nothing anchors a diagram
-- Render fails for any reason: continue to the output and name the skipped check. A missing renderer degrades the loop rather than failing it.
-- `canon` not on PATH: report the catalog as stale rather than hand-editing it
-
-## Out of scope
-
-- Design tokens and the visual system, which `design-extract` owns
-- UI roughness, which `ux-audit` owns
-- Writing the catalog file, which the index regen owns from frontmatter
-- Deleting a pre-split flat diagrams file after a migration, which stays the user's call

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

@@ -1,177 +0,0 @@
----
-name: draft-diagram
-description: Writes per-kind Mermaid diagram entries into `.canon/diagrams/`, covering system context, components, request flow, data pipeline, and deployment. Reads `canon/ARCHITECTURE.md` and `REQUIREMENTS.md` when present, falls back to a code-structure scan. Use when asked to "draw the architecture", "diagram the system", "show the components", "give me a flow chart", "refresh the deploy diagram", or "visualize the project". Do NOT use for design tokens (use `design-extract`) or UI audits (use `ux-audit`).
----
-
-# Draft diagram
-
-Write one entry per diagram kind. Never rewrite the folder wholesale. A pass that refreshes the deploy view leaves the other four files byte-identical, which is the whole reason the surface is a folder.
-
-## Guards
-
-- If no `canon/ARCHITECTURE.md`, no `canon/REQUIREMENTS.md`, and no top-level folder structure to scan, stop: `❌ No source signal. Add canon/ARCHITECTURE.md or run inside a project folder.`
-
-## Step 1: read sources and locate the surface
-
-Read these from the project root in parallel, skipping any that do not exist:
-
-- `.canon/diagrams/index.md` and every `.canon/diagrams/*.md`: which entries exist and what they already say
-- `canon/REQUIREMENTS.md`: users, external dependencies, tech stack, MVP feature list
-- `canon/ARCHITECTURE.md`: layered components, key technical decisions
-- `CLAUDE.md`: project type, conventions
-- `package.json`, `pyproject.toml`, `Cargo.toml`: language and framework markers
-- Top-level folder layout and root config files via `ls`: deploy targets, infrastructure config, component boundaries
-
-Do not recurse speculatively.
-
-Follow `${CLAUDE_SKILL_DIR}/../../standards/diagrams.md` for frontmatter, entry kinds, and explanation rules. Follow `${CLAUDE_SKILL_DIR}/../../standards/mermaid.md` for what goes inside the fence: layout, budgets, accessibility, labels, and verification.
-
-### Migrating a pre-split flat file
-
-When `.canon/diagrams/` holds no entry and `.claude/DIAGRAMS.md` exists, this pass converts it. An entry is any `*.md` in the folder other than `index.md`. The seed ships `index.md` alone, so a folder holding only the catalog is an empty set and still converts.
-
-Split each H2 section into the entry whose kind it matches, carry its mermaid body and explanation prose across unchanged, and add the frontmatter the standard requires. Leave `.claude/DIAGRAMS.md` on disk so the split can be compared against its source, and say in Step 7 that deleting it is the user's call.
-
-Convert only. Do not redraw a diagram during a migration pass, since a rewrite and a move landing together leaves no way to tell which one broke a diagram.
-
-## Step 2: pick which entries this pass writes
-
-Write an entry only when its source signal exists, and only when this pass has a reason to touch it. Skip the rest and leave their files alone.
-
-Count entries the way Step 1 does, excluding `index.md`. Counting the catalog as an entry sends a first pass down the compare branch with nothing to compare, and it writes nothing.
-
-- The user named a kind: write that one.
-- The user asked broadly and the folder holds no entry: write every kind whose signal exists.
-- The user asked broadly and at least one entry exists: compare each entry against its source signal and write only the ones whose signal moved. Report the untouched ones as current.
-
-The standard fixes one filename and one `category` value per kind. Use them verbatim rather than inventing a name, since a refresh finds its target by filename and a new name writes a duplicate entry beside the old one. Emit `system-context.md` whenever `canon/REQUIREMENTS.md` exists, since it is the entry a reader outside the team opens first and the set is incomplete without it.
-
-Stay inside `flowchart` and `sequenceDiagram`. C4, state, ER, and class diagrams render inconsistently across viewers.
-
-## Step 3: write the entries
-
-One file per kind at `.canon/diagrams/<kind>.md`. Write only the files Step 2 selected.
-
-````markdown
----
-title: <what the entry answers, sentence case>
-description: <the question it settles and the signal that drives it>
-category: <the kind, matching the standard>
-verified: 'TODO: never verified'
----
-
-# <Same as title>
-
-<one-line statement of what the diagram shows>
-
-```mermaid
-<diagram type>
-  accTitle: <what the diagram answers>
-  accDescr: <the structure in one sentence>
-  <body>
-```
-
-<one to three explanation paragraphs>
-````
-
-Write `verified` as the literal `TODO: never verified` here, quoted so the colon parses. Step 6 replaces it once a render has been read back, so a SHA written beside the diagram would assert a check that has not run yet. The placeholder is what keeps a render-less project conforming, since Step 5 sends a failed render past Step 6 and nothing stamps the entry. Carry an existing entry's current value across untouched when this pass is rewriting one, and let Step 6 replace that instead.
-
-When sources came from a code scan rather than planning prose, lead the explanation with `Source: code.` and add `Fidelity is lower than prose-driven diagrams. Verify against the project's intent.`
-
-A reader deciding whether the entry still holds starts from the code paths the explanation cites, so cite paths that exist and spell them exactly.
-
-Quote node labels containing spaces or special characters with double quotes (`A["Web shell"]`). Avoid parentheses inside labels, they break some renderers. Use `<br/>` for line breaks inside labels.
-
-Run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against the whole file, including inside mermaid `subgraph` labels and node text. The file lands in the repository rather than on a remote, so the scan's destination scoping leaves the character checks and not the phase-label one, and the `pull_request` check the git-pr surface carries reads only a pull request's own title and body, never a file the diff carries. A colon also works as a replacement inside a label. The pedagogical voice the diagram standard asks for is a yield on voice alone and buys no exemption from these bans.
-
-Nothing enforces the ban inside the diagram. The standards-audit hook toggles on a fence and skips every line within it, so a label carrying an em dash passes silently while the same character in the explanation paragraph below is caught. Check the labels by reading them. This is the one place in the file where the author is the only gate.
-
-## Step 4: regenerate the catalog
-
-```bash
-canon indexes regen
-```
-
-Run it after the last entry is written. It rebuilds `.canon/diagrams/index.md` from sibling frontmatter and groups entries under their `category`. Never hand-edit that file.
-
-When `canon` is not on PATH, say so in Step 7 and name `.canon/diagrams/index.md` as stale rather than writing it by hand.
-
-Scaffold `.canon/diagrams/index.md` with `title` and `subtitle` frontmatter before the first regen when the folder is new and the seed did not provide one. The subtitle routes a first-time reader to the system context entry, since the catalog sorts categories alphabetically rather than in narrative order.
-
-## Step 5: render what this pass changed
-
-A source that satisfies every rule in the standard can still render as a picture that asserts something false about the system. Verification runs on the image.
-
-Render each entry this pass wrote. Skip every entry Step 2 left alone, since an untouched diagram cannot develop a new render defect.
-
-Before the first render in a project, say what is about to block:
-
-```plaintext
-Rendering to verify layout. The first run downloads the Mermaid CLI and takes about 15 seconds.
-```
-
-Write each diagram's mermaid body to its own scratch file, then render it:
-
-```bash
-mkdir -p .canon/tmp/diagrams && bunx -y @mermaid-js/mermaid-cli -i .canon/tmp/diagrams/<kind>.mmd -o .canon/tmp/diagrams/<kind>.png
-```
-
-Render to PNG. An SVG export reads back as markup with no recoverable spatial meaning, so it cannot be verified. Use `bunx` when bun is available. Fall back to `npx -y @mermaid-js/mermaid-cli ...` otherwise.
-
-Renders are verification artifacts, not deliverables. They stay in `.canon/tmp/diagrams/` and are never committed.
-
-When the render fails for any reason (no browser engine, no network, no package manager), continue to Step 7 and name the skipped check in the chat output. A missing renderer degrades the loop, it does not fail it.
-
-## Step 6: read the renders back
-
-Read each PNG and judge the picture against what the entry means to say. Apply the verification properties in `${CLAUDE_SKILL_DIR}/../../standards/mermaid.md`.
-
-Fix the source and re-render. Stop after two correction passes on an entry.
-
-When a defect survives, keep the entry and name the defect in the chat output. A diagram whose author states the flaw is recoverable. A wrong diagram reported as verified is not.
-
-### Stamp the marker
-
-Stamp every entry that passed. Set `verified` to the short SHA of `HEAD` and today's ISO date, and delete any `stale` key the entry carries:
-
-```bash
-git rev-parse --short HEAD
-```
-
-The result is one line, `<sha> <date>`, as in `73e9a3f8 2026-08-02`. <!-- canon-allow-reference: illustrates the verified field's two-token format, which a qualified sha would misstate -->
-
-Stamp nothing else. An entry Step 2 left alone was never re-checked, an entry whose defect survived is known wrong, and an entry whose render was skipped was never seen. All three keep the marker they already carry, and Step 7 names the last two. The field means a render was read back and judged correct, so stamping any of these spends the only signal a reader has on a diagram nobody confirmed.
-
-A migration pass stamps on the same rule. Conversion writes entries, Step 5 renders them, and this step reads them back, so the marker records the commit the split was checked against rather than the commit the flat file was written at.
-
-## Step 7: chat output
-
-```plaintext
-📝 Wrote N entries to .canon/diagrams/
-   .canon/diagrams/<kind>.md
-   <one line per entry written>
-
-Left untouched: <kind, kind> <omitted when the folder was empty>
-
-Verified N renders. <defect or skipped check, one line each, omitted when clean>
-
-Open in any viewer with native Mermaid support (VS Code with `bierner.markdown-mermaid`, GitHub, Cursor) to render. Ask to export if you want SVG or PNG files.
-```
-
-Emit the full path for every file written. Do not echo the diagram bodies in chat. Never report a clean verification when a render was skipped or a defect survived. Never report an entry as written when this pass left it alone.
-
-After a migration pass, add: `Converted .claude/DIAGRAMS.md into N entries. The original is untouched, delete it once you have compared the split against it.`
-
-## Step 8: export on request
-
-If the user asks to export the diagrams (`export to svg`, `give me images`, `render to png`), run:
-
-```bash
-mkdir -p .canon/tmp/render/diagrams && bunx -y @mermaid-js/mermaid-cli -i .canon/diagrams/<kind>.md -o .canon/tmp/render/diagrams/<kind>.png
-```
-
-Export PNG by default. Swap the extension for `.svg` only when the user asks for vector, and never for the Step 5 verification path. The CLI writes one file per `mermaid` block, suffixing when an entry holds more than one. Export every entry when the user names no kind. Output line:
-
-```plaintext
-📝 Wrote N files to .canon/tmp/render/diagrams/
-```

package/docs/agents/design-board.md

@@ -1,33 +0,0 @@
----
-title: Design board
-description: Generating a static index over a project's design surfaces, what each panel reads, and which two stay toolkit-checkout-only
----
-
-# Design board
-
-`canon design board [--out <path>] [--root <path>]` generates a static page set indexing six design surfaces and reports the path a reader opens with `canon serve`. `--root` defaults to the main worktree the same way `canon teach`'s verbs resolve their own root. The surfaces panel's landing-page half and the whole components panel render only when that root is this toolkit's own checkout, since both read this repository's own build output rather than anything a target project produces. 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, an empty corpus, or a toolkit-only gate renders an empty-state message instead of a broken frame.
-
-```bash
-canon design board
-canon serve .canon/tmp/render/board
-```
-
-| Option             | Default                   | Behavior                                      |
-| ------------------ | ------------------------- | --------------------------------------------- |
-| `-o, --out <path>` | `.canon/tmp/render/board` | Output directory                              |
-| `--root <path>`    | The main worktree         | Project root the board reads its sources from |
-
-## Panels
-
-- **Tokens** renders `DESIGN.md` through the same renderer `canon design render` uses, rather than a second one, reading `<root>/canon/DESIGN.md` or `<root>/.claude/DESIGN.md` for a target that has not run `canon migrate surface-roots`.
-- **Surfaces** iframes the built landing page from `<root>/web/dist/` and a teach workspace from `<root>/.canon/teach/`, copying each whole into the board's own tree. The landing-page half reports a toolkit-only notice outside this toolkit's own checkout, and either half reports its own missing build or absent workspace rather than rendering a broken frame.
-- **Wireframes** reads every `**/*.md` under `<root>/canon/wireframes/` or `<root>/.claude/wireframes/`, excluding `index.md` at any depth, and renders each file as-is inside a `<pre>`, labeled from its own `description` frontmatter field. Reports the whole panel empty rather than per file when the directory is absent or holds nothing to render.
-- **Past candidates** lists an arm capture image per folder under `<root>/.canon/picks/`, skipping `references/`, and states the corpus carries none rather than rendering an empty grid.
-- **Components** iframes the gallery built by `bun run web:gallery`, a second Astro config at `web/gallery.config.mjs` reading `web/gallery-src/` and writing `web/gallery-dist/`. That config's `srcDir` is never read by `web:build`'s own config, so the gallery never reaches the published `web/dist/`. The gallery page renders every component under `web/src/components/` except two whose props carry no defaults, which it names rather than filling with invented data. Reports a toolkit-only notice outside this toolkit's own checkout, and a missing gallery build otherwise.
-- **References** lists whatever image an operator has dropped flat under `<root>/.canon/picks/references/`, with no fetching and no second token source: a reference is an image, nothing more. Reports the folder as absent or as present but carrying no image 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.