@erclx/canon 4.79.0 → 4.81.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.79.0",
+  "version": "4.81.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canon-rollout/SKILL.md

@@ -36,7 +36,7 @@ Every target in every wave takes the same branch and the same title, written fro
 - Title: `chore(agents): <what changed in that target>`.
 - Body: the sections `${CLAUDE_SKILL_DIR}/../../standards/pr.md` fixes, describing what that target received.
 - Body, one line: name this toolkit as the source of the changed files and where to change the content upstream. A reader in that repository months later has no other route to the fact that these files are toolkit-managed and that a local edit is lost at the next wave.
-- Body, no version number anywhere in it. `${CLAUDE_SKILL_DIR}/../../standards/versioning.md` permits a semver tag only where the pull request cuts a release, and `.claude/canon/config.json` in the target already records `syncedAt` and a sha256 per synced file. A version in the body is a second copy of a fact the target holds canonically, and it is the copy that goes stale while the pull request sits open.
+- Body, no version number anywhere in it. `${CLAUDE_SKILL_DIR}/../../standards/versioning.md` permits a semver tag only where the pull request cuts a release, and `canon/config/config.json` in the target already records `syncedAt` and a sha256 per synced file. A version in the body is a second copy of a fact the target holds canonically, and it is the copy that goes stale while the pull request sits open.
 
 The title withholds the source and the body supplies it, because the two have different audiences. `agents` says what changed without saying where it came from, which is what a target's own history wants, and the source line is for a reader inside that repository rather than for whoever merges.
 

package/claude/skills/design-extract/SKILL.md

@@ -17,7 +17,7 @@ Step 1 carries two more stops that apply to one path only. Do not evaluate them
 Check the project root for UI surfaces: `src/ui.ts`, `src/ui.tsx`, `src/components/**`, `scripts/lib/ui.sh`, and any `*.css`, `tailwind.config.*`, or `theme.*`.
 
 - Any match takes the source path. Existing code defines the system, so every filled cell traces to a value already in the tree.
-- No match takes the greenfield path. Nothing anchors a value, so every filled cell is a proposal and carries the tag that says so.
+- No match takes the greenfield path. Nothing anchors a value there unless a picked reference does, so name `sketch-design` as the first move: a picked reference anchors a cell where a paragraph alone cannot. A direct run of this skill still falls through to the proposal-from-personality rules in Step 4, tag included, so this skill stays runnable on its own with nothing rendered yet.
 
 The project decides this, never a user flag or an argument. Announce which path ran in one line before Step 2, since the two produce different-looking output from the same skill.
 
@@ -39,6 +39,8 @@ On the source path, also read the UI surfaces matched in Step 1 plus `canon docs
 
 On the greenfield path, also read `canon/ARCHITECTURE.md` for platform, tech stack, and surface type. Do not scan `src/`, stylesheets, or UI modules. Step 1 already established they hold nothing.
 
+On the greenfield path, also check `.canon/review/evidence/*/design-handoff.md` for a file the `sketch-design` skill wrote, taking the most recently modified match when more than one exists. Read it when found. Its presence is what Step 4 traces cells from instead of proposing them.
+
 Run these reads in parallel. Do not speculatively recurse into every directory.
 
 ## Step 3: fetch the seed template
@@ -72,6 +74,8 @@ On the source path, the tag marks the exception. On the greenfield path it marks
 
 Anchor every proposal to a signal, never to a default. "Calm and dense" pins muted grays and tight spacing. A requirements non-goal of "no motion" makes Motion read `No animation.` with no tag. A CLI-only surface leans Typography monospaced and keeps Borders minimal.
 
+- **Traced cells**: when Step 2 matched a `design-handoff.md` file, fill only the fields it actually states, no tag, the same traced-versus-proposed distinction the source path draws for a stylesheet value.
+- The handoff carries hex and family and size, never Weight, Line height, or a color's Intent. Those cells, every field of a role the handoff never names, and Motion and Iconography regardless, still follow the proposal rules below, tag included.
 - **Personality**: transcribe the `## Personality` paragraph from `canon/REQUIREMENTS.md` verbatim. This is the one section that is not a proposal. No tag.
 - **Color**: one row per role. Rewrite the Intent cell in personality language, for example `warm off-white page canvas` instead of the seed default `page canvas`. Propose hex values matching the personality. Dense and calm gives low saturation and high text contrast. Playful gives saturated accents. Every Intent and Value cell gets `? verify`.
 - **Typography**: one row per role. Propose families fitting the platform, system UI for web, monospaced for CLI tools, serif for editorial, and a harmonious scale. Every cell gets `? verify`.

package/claude/skills/git-pr/SKILL.md

@@ -11,7 +11,7 @@ Read these files in parallel:
 
 - `${CLAUDE_SKILL_DIR}/../../standards/branch.md`: branch format, valid types, and constraints
 - `${CLAUDE_SKILL_DIR}/../../standards/pr.md`: structure, rules, and banned phrases
-- `${CLAUDE_SKILL_DIR}/references/labels.md`: label map format, matching, and the missing-label warning. Skip when the project has no `.claude/canon/pr-labels.toml`.
+- `${CLAUDE_SKILL_DIR}/references/labels.md`: label map format, matching, and the missing-label warning. Skip when the project has no `canon/config/pr-labels.toml` and no `.claude/canon/pr-labels.toml`.
 - `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for all generated text
 - The `write-human` skill: voice, rhythm, and sentence construction for all generated text
 - `${CLAUDE_SKILL_DIR}/../../standards/versioning.md`: phase label vs semver discipline
@@ -119,7 +119,7 @@ A `reason` of `no-map` is the answer that the project declared no map, which ear
 
 Every other `reason` is a map or a range the verb could not read, which is `unreadable-map`, `no-domains`, `no-base`, and `unreadable-changes`, plus `bad-base` for a ref this skill resolved wrongly. Take the fallback below and warn beside the result line, naming the reason. A map with a typo in it still has rows a prefix match can reach, and reading the refusal as an absence would open the pull request with no labels and nothing said, which is the surface merging bare that the verb exists to name.
 
-The fallback is reading `.claude/canon/pr-labels.toml` and matching it against the name-only diff per `${CLAUDE_SKILL_DIR}/references/labels.md`. It also covers no record coming back at all, which is an installed `canon` predating the verb, since a skill reaches a target the moment it merges while the CLI reaches one only when a release publishes. The fallback labels correctly and reports no uncovered path, which is the half only the verb carries.
+The fallback is reading `canon/config/pr-labels.toml`, or `.claude/canon/pr-labels.toml` when the project has not moved, and matching it against the name-only diff per `${CLAUDE_SKILL_DIR}/references/labels.md`. It also covers no record coming back at all, which is an installed `canon` predating the verb, since a skill reaches a target the moment it merges while the CLI reaches one only when a release publishes. Naming both spellings matters exactly here: the binary old enough to need this fallback is the same binary that may predate the move, so the project's map can still sit at the older path. The fallback labels correctly and reports no uncovered path, which is the half only the verb carries.
 
 Leave `pr_labels` empty when no map resolves or no prefix matches, which skips the labelling command rather than running it against nothing.
 
@@ -223,7 +223,7 @@ Respond with one line, using the `url` the final command printed:
 
 Add a line for each `uncovered` path the labels step reported, naming the path and the map it belongs in:
 
-`⚠️ No label covers <path>. Add a row to .claude/canon/pr-labels.toml or a [declined] entry.`
+`⚠️ No label covers <path>. Add a row to canon/config/pr-labels.toml or a [declined] entry.`
 
 Add a further line only when the labelling command printed its warning, quoting the label `gh` refused:
 

package/claude/skills/git-pr/references/labels.md

@@ -17,7 +17,7 @@ Does not govern:
 
 ## Map format
 
-The map lives at `.claude/canon/pr-labels.toml` in the project root. Each key under `[domains]` is a label name and its value is the list of path prefixes that earn it.
+The map lives at `canon/config/pr-labels.toml` in the project root, or `.claude/canon/pr-labels.toml` for a project that has not moved. Each key under `[domains]` is a label name and its value is the list of path prefixes that earn it.
 
 ```toml
 [domains]

package/claude/skills/sketch-design/REQUIREMENT.md

@@ -0,0 +1,38 @@
+---
+name: sketch-design
+description: Why a greenfield design value needs a render behind it before it reaches DESIGN.md, and where the reference loop stops short of writing that file itself
+---
+
+# Sketch design requirement
+
+## Gap
+
+Without this skill, a session asked to match a look an operator has in mind either invents token values from a personality paragraph alone, which is what `design-extract`'s greenfield path already does and states plainly as a proposal rather than a fact, or builds a one-off render-and-pick comparison by hand for each request, restating `draft-and-pick`'s candidate page, hand-off, and pick mechanics from scratch with nothing comparing the copy to the shipped one. Neither path lets an operator point at a reference image or a live page and have the values that follow trace back to what was actually looked at and picked.
+
+## Must
+
+- Take at least two operator-supplied references, each a path to an image on disk or a URL to render, and gather them through this skill's own Step 1 prompt rather than a caller-supplied argument
+- Render every URL reference before drafting, and report a capture refusal naming an unrecognized source as a version gap rather than a broken reference
+- Follow `draft-and-pick`'s candidate page, render, hand-off, structured pick, and archival capture mechanics rather than restating them
+- Trace the picked reference's color, type, and spacing by reading its render, and carry the operator's own stated reason for the pick forward as written
+- Write the handoff one field per line, grouped under the section names `standards/design.md` already fixes for `canon/DESIGN.md`, so `design-extract` can read it mechanically
+- Resolve the handoff file and the archival capture against the main worktree root, never against a linked worktree this run happens to be building in
+
+## Must not
+
+- Write to `canon/DESIGN.md`. Tracing values into the handoff is this skill's whole output. Filling the design document from them is `design-extract`'s Step 2, kept as the one place that file is written.
+- Take the pick on the operator's behalf. That call is theirs on every arm that is defensible, the same boundary `draft-and-pick` states for itself.
+- Restate `draft-and-pick`'s render, hand-off, pick, or loop mechanics, or `canon capture`'s render mechanics
+- Assume this skill's own invocation frequency needs no check. `design-extract` Step 1 points to it as the first move on the greenfield path, and an operator can also type its name directly, so whether anything else reaches for it has an answer only after a review pass reads usage back, rather than at creation time.
+
+## Guards
+
+- `canon` not on PATH: stop, since the render loop and the capture calls both need it
+- Fires on a direct request or on `design-extract`'s own pointer, never on the model's own read that a project could use a design direction
+
+## Out of scope
+
+- `design-extract` reads the handoff this skill writes and fills `canon/DESIGN.md` from it. That fill, and the seed template it starts from, stay entirely that skill's own.
+- `draft-and-pick` owns the render, hand-off, pick, and loop mechanics this skill invokes rather than reimplements
+- `canon capture` and `canon serve` own the render and the address mechanics
+- Auditing an implemented UI against its tokens, which `ux-audit` owns

package/claude/skills/sketch-design/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: sketch-design
+description: Runs a reference-and-pick loop against operator-supplied images and URLs, then writes the picked reference's traced color, type, and spacing values to a handoff file `design-extract` reads. Use when asked to "sketch a design direction", "compare these reference sites", "pick a look before we build DESIGN.md", "show me a few design directions", or as the first move on `design-extract`'s greenfield path when nothing has been rendered yet. Do NOT use when a value is already anchored to running code or a stylesheet, which is `design-extract`'s source path, or to draft the design system document itself, which stays `design-extract`'s job.
+---
+
+# Sketch design
+
+`design-extract`'s greenfield path proposes color, type, and spacing from a personality paragraph alone, with no render behind any value. This skill puts operator-supplied references in front of a render instead, so the values `design-extract` fills are traced to a picked reference rather than invented from prose.
+
+## Guards
+
+- If `canon` is not on PATH, stop: `❌ canon CLI not found.`
+- Draft no comparison for a reference set the operator has not supplied. This skill fires on a direct request or on `design-extract` pointing at it, never on the model's own read that a project could use one.
+
+## Step 1: gather the references and render what needs it
+
+Ask the operator, in this step's own prompt, for the references to compare: a path to an image already on disk for each one already rendered somewhere, and a full URL for each live page to render. Take at least two.
+
+Follow `${CLAUDE_SKILL_DIR}/../draft-and-pick/SKILL.md` Step 1 items 2 through 5 to name the decision and derive `<dest>`, with the decision fixed rather than derived: "which of these references the project's design should draw from." Arm 0 is the current state when `canon/DESIGN.md` already carries filled Color, Typography, or Spacing cells. Arms start at 1 otherwise, since a greenfield project asking for this loop has nothing shipped yet to anchor a baseline arm against.
+
+Render every URL reference before drafting, one call per reference since each targets its own file:
+
+```bash
+canon capture <url> --selector body --out <dest>/refs/arm-<id>.png
+```
+
+`--selector body` is the right choice here, unlike inside `draft-and-pick`'s own arms: the page belongs to someone else, so nothing on it is a wrapper this skill can name, and a full-page render is what a reference comparison needs. An operator-supplied image needs no render. Reference it directly from `<dest>/refs/` by copying it there under the same `arm-<id>` naming, so every arm resolves through one path shape regardless of source.
+
+`canon capture <url>` reaches a target only once a release ships the URL-source capability. Report a refusal naming an unrecognized source as that gap rather than a broken reference, and name upgrading the installed `canon` as the repair.
+
+## Step 2: author the candidate set as one page
+
+Follow `${CLAUDE_SKILL_DIR}/../draft-and-pick/SKILL.md` Step 2, with one substitution: each arm is an `<img>` of the file `<dest>/refs/arm-<id>.png` produced in Step 1, not markup drafted from scratch. Wrap each in the shared class that skill's Step 2 fixes, label it with its id and its cost, and inline everything else the page needs, per that step's rules.
+
+## Step 3: render, hand off, and take the pick
+
+Follow `${CLAUDE_SKILL_DIR}/../draft-and-pick/SKILL.md` Steps 3 and 4 unchanged: render the combined page, hand over the address, and put the choice to the operator through the structured question surface. Take whatever reason the operator's answer already states, whether through the surface's own free-text escape or in the surrounding turn, as the reason Step 5 records. The surface takes the pick and the reason in one turn when the operator gives both together, rather than needing a second one.
+
+## Step 4: loop, when the operator asks for a change
+
+The arms here are fixed references rather than drafted markup, so nothing about a picked arm's own content can be revised. A loop here narrows the set instead: drop an arm the operator rules out, or add a new reference by returning to Step 1 for it alone. Return to Step 2 with the adjusted set and repeat Step 3. Stop when the operator says the pick is right, the same rule `draft-and-pick` Step 5 states, never when the set stops changing.
+
+## Step 5: trace and write the handoff
+
+1. Carry forward the reason Step 3's pick already stated, as written rather than paraphrased. Ask the operator to state, in their own words, why the picked reference won only when the pick arrived with no reason attached.
+2. Read the picked arm's render at `<dest>/refs/arm-<id>.png` and trace its color, type, and spacing by looking, the same reading a person does against a screenshot. Name a role only where the reference actually shows it. Leave one out rather than guessing.
+3. Write `.canon/review/evidence/<slug>/design-handoff.md`, resolved against the main worktree root rather than the linked worktree this run may be building in, since shared session scratch always resolves there. One field per line, grouped under the section names `${CLAUDE_SKILL_DIR}/../../standards/design.md` fixes, so `design-extract` reads it mechanically:
+
+   ```markdown
+   # Design handoff
+
+   Picked: arm-<id> (<label>)
+   Reason: <the operator's own sentence from item 1>
+
+   ## Color
+
+   - <role>: <hex>
+
+   ## Typography
+
+   - <role>: <family>, <size>
+
+   ## Spacing
+
+   - base unit: <value>
+
+   ## Borders
+
+   - <role>: <radius>, <width>
+   ```
+
+   Write only the sections and roles the trace actually names. A role or a whole section with nothing traced is left out rather than written empty, since `design-extract` Step 2 treats an absent line as untraced and an empty one as a claim about the source.
+
+4. Batch-capture the final round's arm files, the same directory-batch convention `draft-and-pick` Step 6 uses: `canon capture <dest>/arms --selector <wrapper-class> --out .canon/review/evidence/<slug>/`, naming Step 2's chosen class, so every arm considered, not only the winner, survives past the pick as a revert record.
+5. Delete `<dest>` and everything in it, now that the handoff and the arms both sit at the durable path above. Report the path as still standing when the delete is refused, rather than closing on a report the tree contradicts.
+
+## Response format
+
+```plaintext
+📝 Wrote .canon/review/evidence/<slug>/design-handoff.md
+📝 Wrote .canon/review/evidence/<slug>/arm-<id>.png (and every other arm considered)
+
+Picked arm-<id>: <label>. Run /canon:design-extract to fill canon/DESIGN.md from the trace.
+```
+
+## What this delegates
+
+Cite these rather than restating them. A step reimplemented here rots against the skill that owns it.
+
+- `draft-and-pick` owns the candidate page, the render and hand-off, the structured pick, and the archival capture convention, cited above
+- `design-extract` reads the handoff file this skill writes and fills `canon/DESIGN.md` from it. This skill never writes that file itself.
+- `canon capture` owns the render mechanics, including the URL source and its font refusal

package/claude/skills/teach-workspace/SKILL.md

@@ -113,7 +113,29 @@ Write each option as a `<label class="opt" data-k="<letter>">` holding a radio `
 
 Then carry a teach-back block beside the quiz. A quiz is recognition and the pedagogy prefers production, so a lesson offering only a quiz tests the weak form. Ask for an explanation to a named audience, and carry a `<details>` listing what a complete explanation covers, closed by default, so a learner reading with no session in the room can grade themselves. The reference states both shapes in full.
 
-Write the chrome as four empty marker pairs rather than composing it by hand: `<!-- canon:teach:style -->`/`<!-- /canon:teach:style -->` inside `<head>`, and `<!-- canon:teach:header -->`, `<!-- canon:teach:footnav -->`, and `<!-- canon:teach:scripts -->` each with its own close marker, in that order in `<body>`. Write the authored `<h1>`, lede, body, and quiz between the header's close marker and the footnav's open marker, and nothing else anywhere in the file. Then run:
+Compose the quiz and the teach-back block as one string. Below, that string is the block list's trailing `raw` entry, rather than markup written into the file by hand.
+
+### Building the lesson body
+
+Write the chrome as four empty marker pairs rather than composing it by hand: `<!-- canon:teach:style -->`/`<!-- /canon:teach:style -->` inside `<head>`, and `<!-- canon:teach:header -->`, `<!-- canon:teach:footnav -->`, and `<!-- canon:teach:scripts -->` each with its own close marker, in that order in `<body>`.
+
+Build the authored `<h1>`, lede, body, and quiz as a JSON array of blocks rather than composing markup by hand, and render it through the verb rather than through a component import:
+
+```bash
+echo '[
+  {"type":"heading","level":1,"text":"<title>"},
+  {"type":"paragraph","lede":true,"text":"<the dek>"},
+  {"type":"paragraph","text":"<a body paragraph>"},
+  {"type":"list","ordered":true,"items":["<step one>","<step two>"]},
+  {"type":"raw","html":"<the quiz and teach-back block composed above>"}
+]' | canon teach render --json
+```
+
+A `heading`, a `paragraph` (`lede: true` for the dek), and a `list` cover the structural body. Reach for `raw` only where none of the three can carry the content, never as a shortcut around composing one, and give the quiz and teach-back block the array's trailing `raw` entry every time, since their fixed contract is not a components concern. Take the call's `html` field and write it between the header's close marker and the footnav's open marker, and nothing else anywhere in the file.
+
+Report it rather than proceeding silently when the verb does not resolve, which is an installed CLI predating it, and never compose the lesson body by hand as a fallback. That is the state this section exists to end, and a target holds this skill body before it holds the verb, since a plugin skill reaches a target the moment it merges while the CLI reaches one only when a release publishes.
+
+Then run:
 
 ```bash
 canon teach nav <topic> --json

package/claude/skills/teach-workspace/references/lesson-craft.md

@@ -71,6 +71,17 @@ The quiz shape is a contract rather than a convention. `canon teach nav` splices
 
 The stepper hides and shows and sets nothing else, so how a selected option looks, and whether a wrong one is marked as wrong, is the workspace stylesheet's to grow. Name the correct option in the feedback text for that reason: it is what a learner reads to find out whether they were right.
 
+## The block list
+
+`canon teach render` takes a JSON array of blocks and renders it through the same components the fixture lesson is generated from. Four types, and every structural body composes from them:
+
+- `{"type":"heading","level":1|2,"text":"<text>"}`: an `<h1>` or `<h2>`.
+- `{"type":"paragraph","text":"<text>","lede":true}`: a `<p>`, marked `lede` for the dek that opens the lesson.
+- `{"type":"list","items":["<text>", ...],"ordered":true}`: a `<ul>` or, with `ordered`, an `<ol>`.
+- `{"type":"raw","html":"<markup>"}`: the escape hatch, passed through unescaped.
+
+The quiz and the teach-back block above are the one case `raw` is always needed for, since their fixed contract is not a components concern. Give them the array's trailing entry rather than reaching for `raw` anywhere the other three could carry the content instead.
+
 ## Teach back
 
 A quiz is recognition and a teach-back is production, which is the form retrieval practice prefers. Carry both: the quiz places the learner against options someone could hold, and the teach-back is where the learner finds out what they cannot say without help.

package/docs/agents/audits.md

@@ -19,7 +19,7 @@ canon audits list --json
 | ----------------- | ---------------------------------------------------------------------------------------------------------- |
 | `--json`          | Add a machine-readable record on stdout, keeping the frame                                                 |
 | `--root <path>`   | Measure this tree instead of the current worktree                                                          |
-| `--record`        | Write this run's tracked counts to `.claude/canon/baseline.json`                                           |
+| `--record`        | Write this run's tracked counts to `canon/config/baseline.json`                                            |
 | `--corpus <name>` | Limit the run to one corpus (`tracked`, `per-machine`, `upstream`), repeatable, defaulting to every corpus |
 
 ## What it runs
@@ -75,7 +75,7 @@ Every run states how many corpora it measured against how many it skipped, inclu
 
 ## The retained baseline
 
-`.claude/canon/baseline.json` holds the counts from the last run recorded with `--record`, alongside the day it was taken and the commit it was read at. Each later run reports which counts moved and by how much.
+`canon/config/baseline.json` holds the counts from the last run recorded with `--record`, alongside the day it was taken and the commit it was read at, falling back to `.claude/canon/baseline.json` for a project that has not moved. Each later run reports which counts moved and by how much.
 
 The file is committed. A per-machine record cannot answer the question this half exists for, which is whether a number grew since anyone last looked, and a fresh checkout has to inherit that answer rather than start over. The cost is that a branch moving a count either fixes it or re-records it and says why, which is the shape the consumed-copy assertion already carries.
 

package/docs/agents/commands.md

@@ -24,7 +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 `canon/DESIGN.md` tokens to HTML and CSS                                                                                                                                                                                                                                                                        |
 | `canon design regen`             | Rewrite this repository's `canon/DESIGN.md` and `src/design/base.css` from `src/design/tokens.ts`                                                                                                                                                                                                                      |
-| `canon design board`             | Generate a static page set indexing tokens, surfaces, wireframes, past candidates, and components, against the toolkit checkout like `regen` (`--out`)                                                                                                                                                                 |
+| `canon design board`             | Generate a static page set indexing tokens, surfaces, wireframes, past candidates, components, and references against a caller-resolved `--root` (`--out`), defaulting to the main worktree                                                                                                                            |
 | `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/`                                                                                                                                                                                                                                                     |
@@ -45,8 +45,10 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon teach open`               | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`)                                                                                                                                                                                                                        |
 | `canon teach resource`           | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                                                                                                                                                                                                  |
 | `canon teach glossary`           | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                                                                                                                                                                                                    |
+| `canon teach lesson`             | Resolve the numbered path, shared stylesheet, mission success lines, and one quiz option order per question for the next lesson, writing nothing (`--json`)                                                                                                                                                            |
 | `canon teach stylesheet`         | Seed a workspace stylesheet from the design source, leaving an existing one alone without `--force` (`--json`)                                                                                                                                                                                                         |
 | `canon teach nav`                | Rewrite the teach-root listing, a workspace's contents page, and each lesson's chrome from its four marker regions (`--json`)                                                                                                                                                                                          |
+| `canon teach render`             | Render a JSON block list (heading, paragraph, list, raw) from stdin to HTML through the shared components, refusing `bad-input` by block index (`--json`)                                                                                                                                                              |
 | `canon records validate`         | Report a session record or a standard against the standard governing it, per kind (`--json`)                                                                                                                                                                                                                           |
 | `canon records migrate`          | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`)                                                                                                                                                                                                                         |
 | `canon records ordinal`          | Report or claim the next ordinal `intake` and `groundwork` share, creating the folder atomically (`--claim`, `--json`)                                                                                                                                                                                                 |
@@ -56,7 +58,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon migrate rename`           | Rewrite every unprotected `aitk` token to `canon` and move the paths that carry the name, reporting the plan without `--write` (`--scope`, `--json`)                                                                                                                                                                   |
 | `canon migrate skill-names`      | Move the prefixed skill folders onto their two-word names and rewrite every citation, reporting the plan without `--write` (`--root`, `--json`)                                                                                                                                                                        |
 | `canon migrate records`          | Move the gitignored session records to `.canon/` and repoint every tracked citation, reporting the plan without `--write` (`--root`, `--json`)                                                                                                                                                                         |
-| `canon migrate surface-roots`    | Move the tracked surfaces (`context/`, `wireframes/`, and the three loose documents) from `.claude/` to `canon/` with `git mv` and repoint every tracked citation, reporting the plan without `--write` (`--root`, `--json`)                                                                                           |
+| `canon migrate surface-roots`    | Move the tracked surfaces (`context/`, `wireframes/`, the three loose documents, and the install stamp folder) from `.claude/` to `canon/` with `git mv` and repoint every tracked citation, reporting the plan without `--write` (`--root`, `--json`)                                                                 |
 | `canon migrate record-tree`      | Repoint the old-root citations inside the records themselves, scoped to the live folders and reporting every line without `--write` (`--root`, `--json`)                                                                                                                                                               |
 | `canon migrate rule-layout`      | Move a target's installed rules from the flat `.claude/rules/<subdir>/` layout to `.claude/rules/canon/<subdir>/`, reporting the plan without `--write` (`--root`, `--json`)                                                                                                                                           |
 | `canon migrate scratch-evidence` | Move a folder under `.tmp/` that a durable record cites as evidence to `.canon/review/evidence/`, repointing every citation live or archived, reporting the plan without `--write` (`--root`, `--json`)                                                                                                                |
@@ -139,7 +141,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `slides`    | `render`, `list`                                                                                                                      |
 | `tasks`     | `archive`, `validate`                                                                                                                 |
 | `intake`    | `list`, `answer`                                                                                                                      |
-| `teach`     | `list`, `open`, `resource`, `glossary`, `lesson`, `stylesheet`, `nav`                                                                 |
+| `teach`     | `list`, `open`, `resource`, `glossary`, `lesson`, `stylesheet`, `nav`, `render`                                                       |
 | `comments`  | `scan`                                                                                                                                |
 | `context`   | `audit`                                                                                                                               |
 | `markdown`  | `audit`                                                                                                                               |
@@ -167,7 +169,7 @@ Common patterns:
 
 A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the nearest non-blank line below it, keeps the old spelling for prose that dates a decision. The records themselves are never swept: everything under `.canon/` and every `.claude/` record folder is passed over and reported as a count on its own line, which is what keeps the run that follows the ignore collapse touching the same files as one before it. Running it twice rewrites nothing, which is the check that the exclusions, the markers, and that skip all fired.
 
-`migrate surface-roots` moves the tracked surfaces from `.claude/` to `canon/`: `context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, and `DESIGN.md`. Every path is tracked, so each file moves with `git mv` and its history follows it, and every tracked citation of one is rewritten in the same run. `.claude/canon/`, `rules/`, `skills/`, `hooks/`, and `settings.json` stay where Claude Code reads them. It reports until `--write` is passed, and a destination already present under `canon/` refuses the whole plan rather than splitting a surface across both roots.
+`migrate surface-roots` moves the tracked surfaces from `.claude/` to `canon/`: `context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the install stamp folder, respelled `canon/config/` since a project under `canon/` reserves the bare `canon` name for the CLI's own install. Every path is tracked, so each file moves with `git mv` and its history follows it, and every tracked citation of one is rewritten in the same run. `rules/`, `skills/`, `hooks/`, and `settings.json` stay where Claude Code reads them. It reports until `--write` is passed, and a destination already present under `canon/` refuses the whole plan rather than splitting a surface across both roots.
 
 A line carrying `canon-keep-surface-root`, or the nearest non-blank line above it, keeps the old spelling. A rule's frontmatter `paths:` glob, a citation shaped like a path into another repository, and one inside a dated paragraph are reported by file and line and left alone. Running it twice rewrites nothing, which is the idempotence check. A project that never runs it keeps resolving each surface under `.claude/`, since every reader takes whichever root holds the entry.
 

package/docs/agents/design-board.md

@@ -1,30 +1,32 @@
 ---
 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
+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>]` generates a static page set indexing five 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 `canon/DESIGN.md`, `canon/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.
+`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 or an empty corpus renders an empty-state message instead of a broken frame.
+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/review/board
 ```
 
-| Option             | Default               | Behavior         |
-| ------------------ | --------------------- | ---------------- |
-| `-o, --out <path>` | `.canon/review/board` | Output directory |
+| Option             | Default               | Behavior                                      |
+| ------------------ | --------------------- | --------------------------------------------- |
+| `-o, --out <path>` | `.canon/review/board` | Output directory                              |
+| `--root <path>`    | The main worktree     | Project root the board reads its sources from |
 
 ## Panels
 
-- **Tokens** renders `canon/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 `canon/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.
-- **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 missing gallery build rather than rendering a broken frame.
+- **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/review/evidence/`, 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/review/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
 

package/docs/agents/index.md

@@ -17,7 +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
+- [Design board](design-board.md): Generating a static index over a project's design surfaces, what each panel reads, and which two stay toolkit-checkout-only
 - [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/agents/install-and-sync.md

@@ -158,9 +158,9 @@ Use `--json` for the machine-readable report and `--exit-code` to fail a CI job.
 and missing files are both excluded from that exit code: a project-authored
 rule never converges, and a sync that added a missing one silently changes
 what the project is governed by, which stays a separate command an operator
-chooses to run. Attribution reads `canon/config/config.json` first and falls
-back to `.claude/canon/config.json`, which every install and sync still writes
-in this release.
+chooses to run. Attribution reads `canon/config/config.json` first, which every
+install and sync now writes, and falls back to `.claude/canon/config.json` for
+a target that has not moved.
 
 A target installed before stamping shipped has no such file, and neither does
 that fallback do anything to migrate it. A target stamped before the file

package/docs/agents/label-coverage.md

@@ -28,7 +28,7 @@ Under `--json` the record holds stdout alone and the frame still renders on stde
 
 ## The map it reads
 
-The map sits at `.claude/canon/pr-labels.toml` and carries two tables. `[domains]` keys a label name to the path prefixes that earn it, and `[declined]` keys a reason to the prefixes that earn no label on purpose.
+The map sits at `canon/config/pr-labels.toml`, falling back to `.claude/canon/pr-labels.toml` for a project that has not moved, and carries two tables. `[domains]` keys a label name to the path prefixes that earn it, and `[declined]` keys a reason to the prefixes that earn no label on purpose.
 
 ```toml
 [domains]

package/docs/agents/teach.md

@@ -137,6 +137,22 @@ Each `quiz` entry carries `order`, the authored option indices in presentation o
 
 The order is drawn here rather than instructed, and that is the point of the verb. An author told to vary the position still varies it by judgment, and the judgment settles on the first slot, which is the defect this design departs from. The draw is uniform over the options, so the position carries no information about which answer is correct.
 
+## Render
+
+`canon teach render` renders a lesson body's structural blocks to HTML, through the same components the fixture lesson under `examples/teach/00-fixture/` is generated from. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
+
+```bash
+echo '[{"type":"heading","level":1,"text":"Compass bearings"}]' | canon teach render --json
+```
+
+| Option   | Behavior                                 |
+| -------- | ---------------------------------------- |
+| `--json` | Emit a machine-readable record on stdout |
+
+It reads a JSON array of blocks from stdin, each a `heading`, `paragraph`, `list`, or `raw` block, and reports `{ ok: true, html }` on `--json` or the bare rendered HTML on stdout otherwise. Content none of the three components can express takes a `raw` block, carrying its own HTML verbatim and unescaped, which is the shape the quiz and the teach-back block travel in.
+
+It refuses `bad-input` on empty stdin, on malformed JSON, on stdin that does not parse to an array, and on a block carrying an unrecognized `type` or a field of the wrong shape for its type, naming the block's index in the message.
+
 ## Nav
 
 `canon teach nav` rewrites the teach-root listing, a workspace's contents page, and each of its lessons' chrome, from what the workspace holds on disk.

package/docs/target-projects.md

@@ -208,7 +208,7 @@ The report opens by naming the binary running it. The installed version reads ag
 
 A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `canon:seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is a relocation the report names but no command runs.
 
-That attribution comes from `canon/config/config.json` when a project carries it, falling back to `.claude/canon/config.json`, a stamp every install and sync still writes in this release. A target stamped before that path shipped is read from the retired `.claude/canon.json` instead, reported rather than migrated. Governance records a hash per installed file, plus the stack `canon gov install` was given, and tooling records the stack chain it resolved instead of any file hash, since its install runs no per-file walk to attribute.
+That attribution comes from `canon/config/config.json`, which every install and sync now writes, falling back to `.claude/canon/config.json` for a target stamped before that move. A target stamped before that path shipped is read from the retired `.claude/canon.json` instead, reported rather than migrated. Governance records a hash per installed file, plus the stack `canon gov install` was given, and tooling records the stack chain it resolved instead of any file hash, since its install runs no per-file walk to attribute.
 
 Each domain holds its own toolkit commit, so syncing governance today does not move the revision tooling measures against, and each domain reports the upstream commits touching its own source path. Running any sync stamps that domain, and the report names the ones still unstamped.
 

package/docs/workflow/ai-workflow.md

@@ -204,6 +204,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:setup-plugins`  | On a new machine, to install the community and official plugins user-scoped                                     |
 | `canon:setup-verify`   | After the agent generates configs, to run the installed scripts and report pass or fail                         |
 | `canon:setup-smoke`    | After `setup-verify` passes, to check the dev and preview servers, end-to-end tests, and the screenshot harness |
+| `canon:sketch-design`  | Before `design-extract`'s greenfield path, to trace a design direction from reference images or URLs            |
 | `canon:design-extract` | Before the first UI feature, to draft `canon/DESIGN.md`                                                         |
 | `canon:draft-diagram`  | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                            |
 | `canon:repo-metadata`  | When the GitHub About text, homepage, or topics may have drifted, to reconcile them against the README          |

package/docs/workflow/visual-design-workflow.md

@@ -35,6 +35,7 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 
 ### Skills
 
+- `canon:sketch-design` to trace a design direction from reference images or URLs, before `design-extract`'s greenfield path proposes from a personality paragraph alone
 - `canon:design-extract` to draft `canon/DESIGN.md`, from existing project signals or from requirements alone on day one
 - `canon:ui-test` for e2e test generation after UI changes
 - `canon:ux-audit` for UX gap detection on existing surfaces

package/package.json

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

package/src/audits/baseline.ts

@@ -1,6 +1,7 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
+import { dirname, join, relative } from 'node:path'
 import type { AuditResult } from '@/audits/catalog'
+import { resolveExisting } from '@/legacy-path'
 
 /**
  * Where the retained counts live, relative to the project root.
@@ -15,7 +16,14 @@ import type { AuditResult } from '@/audits/catalog'
  * that installs the CLI. A baseline in the package would hand a target this
  * repository's counts to measure its own tree against.
  */
-export const BASELINE_REL = join('.claude', 'canon', 'baseline.json')
+export const BASELINE_REL = join('canon', 'config', 'baseline.json')
+
+/**
+ * Where the baseline wrote before this move, `.claude/canon/baseline.json`.
+ * `readBaseline` falls back to it so a target that has not moved still reads
+ * its recorded floor, and the write no longer lands there.
+ */
+const LEGACY_BASELINE_REL = join('.claude', 'canon', 'baseline.json')
 
 export interface Baseline {
   /** The day the record was taken, as `YYYY-MM-DD`. */
@@ -165,7 +173,11 @@ function isBaseline(value: unknown): value is Baseline {
 export async function readBaseline(
   root: string,
 ): Promise<Baseline | undefined> {
-  const path = join(root, BASELINE_REL)
+  const path = resolveExisting([
+    join(root, BASELINE_REL),
+    join(root, LEGACY_BASELINE_REL),
+  ])
+  const rel = relative(root, path)
 
   let raw: string
   try {
@@ -178,12 +190,12 @@ export async function readBaseline(
   try {
     parsed = JSON.parse(raw)
   } catch {
-    throw new Error(`${BASELINE_REL} does not parse as JSON. Fix or delete it.`)
+    throw new Error(`${rel} does not parse as JSON. Fix or delete it.`)
   }
 
   if (!isBaseline(parsed)) {
     throw new Error(
-      `${BASELINE_REL} carries no recordedAt, commit, and checks. Fix or delete it.`,
+      `${rel} carries no recordedAt, commit, and checks. Fix or delete it.`,
     )
   }
 

package/src/claude/cases/misc.ts

@@ -17,6 +17,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'This project has no logo yet. Draft one and give me a social card to go with it.',
     expect: 'draft-identity',
   },
+  {
+    prompt:
+      "I found two sites whose look I want us to draw from. Put them side by side and let's settle which one the design should follow before anyone writes a token.",
+    expect: 'sketch-design',
+  },
   {
     prompt: 'Fire up the dev server the way this project documents it.',
     expect: 'project-commands',