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

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/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/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`)                                                                                                                                                                                                 |
@@ -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`                                                                                                                               |

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/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/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.80.0",
+  "version": "4.81.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

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',

package/src/commands/design.ts

@@ -11,12 +11,17 @@ import { buildDesignCss } from '@/design/css'
 import { HAND_DRAWN_FONT_FACES } from '@/design/fonts'
 import { renderDesignDoc } from '@/design/render'
 import { DESIGN_BASE_CSS, DESIGN_DOCUMENT, regenDesign } from '@/design/regen'
-import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
+import {
+  checkoutMismatchWarning,
+  isOwnCheckout,
+  PROJECT_ROOT,
+} from '@/project-root'
 import { creationRel } from '@/record-root'
 import { surfaceDir } from '@/surface-root'
 import { recordStamp, runDomainSync } from '@/sync/engine'
 import { resolveTarget } from '@/target'
 import { intro, logAdd, logError, logInfo, logWarn, outro, palette } from '@/ui'
+import { mainWorktreeRoot } from '@/worktree'
 
 export function register(program: Command): void {
   const design = program
@@ -133,33 +138,44 @@ export function register(program: Command): void {
   design
     .command('board')
     .description(
-      'Generate the design board, an index over this repository’s own design surfaces',
+      'Generate the design board, an index over a project’s design surfaces',
     )
     .option(
       '-o, --out <path>',
       'Output directory',
       creationRel(process.cwd(), 'review', 'board'),
     )
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
     .addHelpText(
       'after',
       [
         '',
-        'Like regen, this runs against the toolkit checkout rather than a',
-        'target: it reads five sources already on disk relative to the',
-        'project root and writes a static page set, never installed or',
-        'synced. Open it with canon serve <out>.',
+        'Reads its sources from --root, defaulting to the main worktree of',
+        'whatever project the caller stands in, and writes a static page',
+        'set, never installed or synced. The surfaces panel’s landing-page',
+        'half and the whole components panel render only when that root is',
+        'this toolkit’s own checkout. Open the result with canon serve <out>.',
         '',
       ].join('\n'),
     )
-    .action((opts: { out: string }) => {
+    .action(async (opts: { out: string; root?: string }) => {
       const outDir = resolve(process.cwd(), opts.out)
+      const root = opts.root
+        ? resolve(process.cwd(), opts.root)
+        : await mainWorktreeRoot()
+      const isToolkitCheckout = isOwnCheckout(root)
       const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
       const mismatch = checkoutMismatchWarning(process.cwd())
       process.stderr.write(
         `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}Generate design board${NC}\n`,
       )
       if (mismatch !== undefined) logWarn(mismatch)
-      const result = generateBoard(PROJECT_ROOT, outDir, process.cwd())
+      const result = generateBoard(
+        root,
+        outDir,
+        process.cwd(),
+        isToolkitCheckout,
+      )
       if (!result.ok) {
         process.stderr.write(
           `${GREY}│${NC} ${RED}✗${NC} ${result.detail}\n${GREY}└${NC}\n`,

package/src/commands/teach.ts

@@ -2,6 +2,7 @@ import { relative } from 'node:path'
 import type { Command } from 'commander'
 import { type LessonOutcome, planLesson } from '@/teach/lesson'
 import { type NavOutcome, generateNav } from '@/teach/nav'
+import { type RenderOutcome, renderLessonBody } from '@/teach/render'
 import {
   defineTerms,
   type ListOutcome,
@@ -81,6 +82,10 @@ interface NavCommandOptions {
   readonly root?: string
 }
 
+interface RenderCommandOptions {
+  readonly json?: boolean
+}
+
 export function register(program: Command): void {
   const teach = program
     .command('teach')
@@ -357,6 +362,36 @@ export function register(program: Command): void {
     .action(async (topic: string | undefined, opts: NavCommandOptions) => {
       process.exitCode = await runNav(topic, opts)
     })
+
+  teach
+    .command('render')
+    .description('Render a lesson body block list to HTML')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the block list rendered',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Reads a JSON array of blocks from stdin, each a heading, paragraph,',
+        'list, or raw block, and renders it through the same components the',
+        'fixture lesson is generated from. Content the three cannot express',
+        'takes type raw, carrying its own html verbatim, unescaped.',
+        '',
+        'Takes no topic and no --root: the verb is a stateless transform,',
+        'reading nothing off a workspace on disk.',
+        '',
+        'Examples:',
+        '  echo \'[{"type":"heading","level":1,"text":"Compass bearings"}]\' | canon teach render --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RenderCommandOptions) => {
+      process.exitCode = await runRender(opts)
+    })
 }
 
 interface StylesheetCommandOptions {
@@ -403,6 +438,17 @@ function collect(value: string, previous: string[]): string[] {
   return [...previous, value]
 }
 
+function readStdin(): Promise<string> {
+  return new Promise((resolveStream, rejectStream) => {
+    const chunks: Buffer[] = []
+    process.stdin.on('data', (chunk: Buffer) => chunks.push(chunk))
+    process.stdin.on('end', () =>
+      resolveStream(Buffer.concat(chunks).toString('utf8')),
+    )
+    process.stdin.on('error', rejectStream)
+  })
+}
+
 /**
  * Splits every pair or reports the ones that carry no separator. Both halves
  * are reported together, so a caller passing four pairs learns about all the
@@ -648,6 +694,78 @@ async function runNav(
   return reportNav(await generateNav(root, topic), emitJson, root)
 }
 
+async function runRender(opts: RenderCommandOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (process.stdin.isTTY) {
+    return reportRenderRefusal(
+      badInput(
+        "No blocks on stdin. Pipe a JSON array: echo '[...]' | canon teach render",
+      ),
+      emitJson,
+    )
+  }
+
+  const body = (await readStdin()).trim()
+
+  if (!body) {
+    return reportRenderRefusal(
+      badInput('Empty stdin. Pipe a JSON array of blocks.'),
+      emitJson,
+    )
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(body)
+  } catch {
+    return reportRenderRefusal(badInput('Malformed JSON on stdin.'), emitJson)
+  }
+
+  if (!Array.isArray(parsed)) {
+    return reportRenderRefusal(
+      badInput('Stdin must be a JSON array of blocks.'),
+      emitJson,
+    )
+  }
+
+  return reportRender(renderLessonBody(parsed), emitJson)
+}
+
+function reportRenderRefusal(refused: TeachRefused, emitJson: boolean): number {
+  if (emitJson) {
+    process.stderr.write(`${refused.message}\n`)
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: false,
+        reason: refused.reason,
+        message: refused.message,
+      })}\n`,
+    )
+    return 1
+  }
+
+  intro('canon teach render')
+  logStep('Refused')
+  logError(refused.message)
+  outro()
+  return 1
+}
+
+function reportRender(outcome: RenderOutcome, emitJson: boolean): number {
+  if (!outcome.ok) return reportRenderRefusal(outcome, emitJson)
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, html: outcome.html })}\n`,
+    )
+    return 0
+  }
+
+  process.stdout.write(`${outcome.html}\n`)
+  return 0
+}
+
 function reportNav(
   outcome: NavOutcome,
   emitJson: boolean,

package/src/design/board.ts

@@ -11,13 +11,17 @@ import { join, relative, sep } from 'node:path'
 import { DESIGN_DOCUMENT } from '@/design/regen'
 import { renderDesignDoc } from '@/design/render'
 import { colorValue } from '@/design/tokens'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { recordDir } from '@/record-root'
+import { surfaceDir } from '@/surface-root'
 
 /**
- * The one named site for this repository's wireframe corpus, so the surface
- * move retargets a single constant rather than a literal repeated per panel.
- * The board reads this checkout alone, which has moved, so the new root is
- * spelled directly rather than resolved.
+ * The wireframes panel's creation-root spelling, used in its own empty-state
+ * message and by this module's tests to seed a fixture. The panel itself
+ * resolves its actual read path through `surfaceDir`, which also reads
+ * `.claude/wireframes/` for a target that has not run the surface-roots
+ * migration, so this constant names where a fresh file lands rather than
+ * where every root's corpus necessarily sits.
  */
 export const WIREFRAME_DIR = join('canon', 'wireframes')
 
@@ -34,26 +38,6 @@ const WEB_DIST_ENTRY = 'index.html'
 const WEB_GALLERY_DIST = join('web', 'gallery-dist')
 const WEB_GALLERY_DIST_ENTRY = 'index.html'
 
-interface WireframeEntry {
-  readonly path: string
-  readonly describes: string
-}
-
-/**
- * The six files the wireframes panel renders, each beside the surface it
- * describes. `index.md` at either level is a catalog rather than a wireframe
- * and is excluded, which is why this list holds six rather than the eight
- * files the corpus carries today.
- */
-const WIREFRAMES: readonly WireframeEntry[] = [
-  { path: 'landing-page.md', describes: 'The canon.erclx.dev landing page' },
-  { path: 'slides.md', describes: 'The SLIDES.md render' },
-  { path: 'teach/root.md', describes: 'A teach workspace root listing' },
-  { path: 'teach/contents.md', describes: 'A workspace contents page' },
-  { path: 'teach/lesson.md', describes: 'A lesson page and quiz stepper' },
-  { path: 'teach/chrome.md', describes: 'The shared teach chrome' },
-]
-
 const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.svg', '.webp']
 
 export interface BoardPanel {
@@ -233,7 +217,8 @@ iframe { width: 100%; height: 480px; border: 1px solid var(--board-border); bord
 <body>
 <header>
 <h1>Design board</h1>
-<p class="meta">Generated by <code>canon design board</code>. Repository-local, never installed into a target.</p>
+<p class="meta">Generated by <code>canon design board</code>. Reads from a caller-resolved root, never installed or synced.</p>
+<p class="meta">Drafting a new candidate: <code>canon:draft-and-pick</code>. Auditing a rendered surface: <code>canon:ux-audit</code>.</p>
 </header>
 <nav>${navLinks}${THEME_TOGGLE_BUTTON}</nav>
 <main>
@@ -282,7 +267,7 @@ ${body}
 }
 
 function writeTokensPanel(root: string, outDir: string): void {
-  const sourcePath = join(root, DESIGN_DOCUMENT)
+  const sourcePath = surfaceDir(root, 'DESIGN.md')
   const dir = join(outDir, 'tokens')
 
   if (!existsSync(sourcePath)) {
@@ -300,18 +285,56 @@ function writeTokensPanel(root: string, outDir: string): void {
   renderDesignDoc(sourcePath, dir)
 }
 
+interface WireframeFile {
+  readonly relPath: string
+  readonly text: string
+  readonly description: string | undefined
+}
+
+/**
+ * Every wireframe under whichever root the corpus resolves at, sorted for a
+ * stable render order across runs. `surfaceDir` reads `.claude/wireframes/`
+ * for a target that has not run the surface-roots migration, the same
+ * fallback `recordDir` already gives the surfaces panel's teach half.
+ * `index.md` at any depth is a catalog rather than a wireframe and is
+ * excluded. A glob emits OS-native separators, and the corpus nests one
+ * level deep, so the label always reads with forward slashes regardless of
+ * platform.
+ */
+function listWireframes(root: string): readonly WireframeFile[] {
+  const dir = surfaceDir(root, 'wireframes')
+  if (!existsSync(dir)) return []
+
+  const glob = new Bun.Glob('**/*.md')
+  const relPaths = [...glob.scanSync({ cwd: dir })]
+    .filter((relPath) => relPath.split(sep).pop() !== 'index.md')
+    .map((relPath) => relPath.split(sep).join('/'))
+    .sort()
+
+  return relPaths.map((relPath) => {
+    const text = readFileSync(join(dir, relPath), 'utf8')
+    return {
+      relPath,
+      text,
+      description: readField(parseFrontmatter(text), 'description'),
+    }
+  })
+}
+
 function writeWireframesPanel(root: string, outDir: string): void {
   const dir = join(outDir, 'wireframes')
   mkdirSync(dir, { recursive: true })
 
-  const sections = WIREFRAMES.map((entry) => {
-    const sourcePath = join(root, WIREFRAME_DIR, entry.path)
-    if (!existsSync(sourcePath)) {
-      return `<h2>${escapeHtml(entry.path)}</h2>\n<p class="empty">Missing from ${WIREFRAME_DIR}/.</p>`
-    }
-    const text = readFileSync(sourcePath, 'utf8')
-    return `<h2>${escapeHtml(entry.path)}</h2>\n<p>${escapeHtml(entry.describes)}</p>\n<pre>${escapeHtml(text)}</pre>`
-  }).join('\n')
+  const files = listWireframes(root)
+  const sections =
+    files.length === 0
+      ? `<p class="empty">No wireframe files under ${WIREFRAME_DIR}/.</p>`
+      : files
+          .map((file) => {
+            const description = file.description ?? file.relPath
+            return `<h2>${escapeHtml(file.relPath)}</h2>\n<p>${escapeHtml(description)}</p>\n<pre>${escapeHtml(file.text)}</pre>`
+          })
+          .join('\n')
 
   writeFileSync(join(dir, 'index.html'), panelPage('Wireframes', sections))
 }
@@ -322,15 +345,21 @@ function copyBuilt(source: string, dest: string): void {
   cpSync(source, dest, { recursive: true })
 }
 
-function writeSurfacesPanel(root: string, outDir: string): void {
+function writeSurfacesPanel(
+  root: string,
+  outDir: string,
+  isToolkitCheckout: boolean,
+): void {
   const dir = join(outDir, 'surfaces')
   mkdirSync(dir, { recursive: true })
 
   const distSource = join(root, WEB_DIST)
-  const landingBody = existsSync(join(distSource, WEB_DIST_ENTRY))
-    ? (copyBuilt(distSource, join(dir, 'landing')),
-      '<iframe src="landing/index.html" loading="lazy"></iframe>')
-    : `<p class="empty">No ${WEB_DIST}/ build. Run bun run web:build, then regenerate the board.</p>`
+  const landingBody = !isToolkitCheckout
+    ? `<p class="empty">The landing page panel only renders in this toolkit's own checkout.</p>`
+    : existsSync(join(distSource, WEB_DIST_ENTRY))
+      ? (copyBuilt(distSource, join(dir, 'landing')),
+        '<iframe src="landing/index.html" loading="lazy"></iframe>')
+      : `<p class="empty">No ${WEB_DIST}/ build. Run bun run web:build, then regenerate the board.</p>`
 
   const teachSource = recordDir(root, 'teach')
   const teachBody = existsSync(join(teachSource, 'index.html'))
@@ -347,15 +376,21 @@ function writeSurfacesPanel(root: string, outDir: string): void {
   )
 }
 
-function writeComponentsPanel(root: string, outDir: string): void {
+function writeComponentsPanel(
+  root: string,
+  outDir: string,
+  isToolkitCheckout: boolean,
+): void {
   const dir = join(outDir, 'components')
   mkdirSync(dir, { recursive: true })
 
   const gallerySource = join(root, WEB_GALLERY_DIST)
-  const body = existsSync(join(gallerySource, WEB_GALLERY_DIST_ENTRY))
-    ? (copyBuilt(gallerySource, join(dir, 'gallery')),
-      '<iframe src="gallery/index.html" loading="lazy"></iframe>')
-    : `<p class="empty">No ${WEB_GALLERY_DIST}/ build. Run bun run web:gallery, then regenerate the board.</p>`
+  const body = !isToolkitCheckout
+    ? `<p class="empty">The components panel only renders in this toolkit's own checkout.</p>`
+    : existsSync(join(gallerySource, WEB_GALLERY_DIST_ENTRY))
+      ? (copyBuilt(gallerySource, join(dir, 'gallery')),
+        '<iframe src="gallery/index.html" loading="lazy"></iframe>')
+      : `<p class="empty">No ${WEB_GALLERY_DIST}/ build. Run bun run web:gallery, then regenerate the board.</p>`
 
   writeFileSync(join(dir, 'index.html'), panelPage('Components', body))
 }
@@ -416,13 +451,54 @@ function writeCandidatesPanel(root: string, outDir: string): void {
   const sections = found
     .map(
       ({ folder, images }) =>
-        `<h2>${escapeHtml(folder)}</h2>\n${images.map((image) => `<img src="${folder}/${image}" alt="${escapeHtml(image)}">`).join('\n')}`,
+        `<h2>${escapeHtml(folder)}</h2>\n${images.map((image) => `<img src="${escapeHtml(`${folder}/${image}`)}" alt="${escapeHtml(image)}">`).join('\n')}`,
     )
     .join('\n')
 
   writeFileSync(join(dir, 'index.html'), panelPage('Past candidates', sections))
 }
 
+function writeReferencesPanel(root: string, outDir: string): void {
+  const dir = join(outDir, 'references')
+  mkdirSync(dir, { recursive: true })
+
+  const referencesDir = recordDir(root, 'review', 'references')
+  if (!existsSync(referencesDir)) {
+    writeFileSync(
+      join(dir, 'index.html'),
+      panelPage(
+        'References',
+        `<p class="empty">No ${relative(root, referencesDir)} folder yet.</p>`,
+      ),
+    )
+    return
+  }
+
+  const images = imagesIn(referencesDir)
+  if (images.length === 0) {
+    writeFileSync(
+      join(dir, 'index.html'),
+      panelPage(
+        'References',
+        `<p class="empty">${relative(root, referencesDir)} exists but carries no image yet.</p>`,
+      ),
+    )
+    return
+  }
+
+  for (const image of images) {
+    cpSync(join(referencesDir, image), join(dir, image))
+  }
+
+  const sections = images
+    .map(
+      (image) => `<img src="${escapeHtml(image)}" alt="${escapeHtml(image)}">`,
+    )
+    .join('\n')
+
+  writeFileSync(join(dir, 'index.html'), panelPage('References', sections))
+}
+
 /**
  * Generates the board's page set into `outDir`, clearing whatever was there.
  *
@@ -433,11 +509,16 @@ function writeCandidatesPanel(root: string, outDir: string): void {
  * `cwd` is the caller's own working directory, resolved and passed in
  * explicitly rather than read here, so a test can exercise the checkout-
  * mismatch case without touching the process's real cwd.
+ *
+ * `isToolkitCheckout` gates the surfaces panel's landing-page half and the
+ * whole components panel, both of which read this repository's own build
+ * output rather than anything a target project produces.
  */
 export function generateBoard(
   root: string,
   outDir: string,
   cwd: string,
+  isToolkitCheckout: boolean,
 ): BoardOutcome {
   if (wouldDeleteRoot([root, cwd], outDir)) {
     return {
@@ -460,13 +541,15 @@ export function generateBoard(
       path: 'candidates/index.html',
     },
     { id: 'components', title: 'Components', path: 'components/index.html' },
+    { id: 'references', title: 'References', path: 'references/index.html' },
   ]
 
   writeTokensPanel(root, outDir)
-  writeSurfacesPanel(root, outDir)
+  writeSurfacesPanel(root, outDir, isToolkitCheckout)
   writeWireframesPanel(root, outDir)
   writeCandidatesPanel(root, outDir)
-  writeComponentsPanel(root, outDir)
+  writeComponentsPanel(root, outDir, isToolkitCheckout)
+  writeReferencesPanel(root, outDir)
 
   const indexPath = join(outDir, 'index.html')
   writeFileSync(indexPath, shellHtml(panels))

package/src/project-root.ts

@@ -28,6 +28,22 @@ const readPackageName = (root: string): string | undefined => {
   }
 }
 
+/**
+ * Whether `root` is a checkout of this same package, judged by package name
+ * rather than by path equality against `PROJECT_ROOT`.
+ *
+ * A linked worktree tracks the identical `package.json` the main worktree
+ * does, so this reads true for either. Comparing `root` against `PROJECT_ROOT`
+ * directly reads true only for the one directory this process happened to
+ * load its own source from, which is wrong for a caller whose CLI runs out of
+ * a linked worktree while `root` correctly points at the main one, or at
+ * another worktree of the same repository.
+ */
+export function isOwnCheckout(root: string): boolean {
+  const ownName = readPackageName(PROJECT_ROOT)
+  return ownName !== undefined && readPackageName(root) === ownName
+}
+
 /**
  * Walks upward from `startDir` for the nearest ancestor `package.json`
  * sharing this package's own `name`, and reports its path when that ancestor

package/src/teach/render.ts

@@ -0,0 +1,126 @@
+import { Heading } from '@/teach/components/heading'
+import { List } from '@/teach/components/list'
+import { Paragraph } from '@/teach/components/paragraph'
+import { render } from '@/teach/html/jsx-runtime'
+import type { TeachRefused } from '@/teach/workspace'
+
+export type LessonBlock =
+  | { readonly type: 'heading'; readonly level: 1 | 2; readonly text: string }
+  | {
+      readonly type: 'paragraph'
+      readonly text: string
+      readonly lede?: boolean
+    }
+  | {
+      readonly type: 'list'
+      readonly items: readonly string[]
+      readonly ordered?: boolean
+    }
+  | { readonly type: 'raw'; readonly html: string }
+
+export interface RenderRendered {
+  readonly ok: true
+  readonly html: string
+}
+
+export type RenderOutcome = RenderRendered | TeachRefused
+
+const BLOCK_TYPES = ['heading', 'paragraph', 'list', 'raw'] as const
+
+function isBlockType(value: unknown): value is LessonBlock['type'] {
+  return (BLOCK_TYPES as readonly string[]).includes(value as string)
+}
+
+function badBlock(index: number, message: string): TeachRefused {
+  return {
+    ok: false,
+    reason: 'bad-input',
+    message: `Block ${index}: ${message}`,
+    detail: [],
+  }
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === 'string'
+}
+
+function isStringArray(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every(isString)
+}
+
+function renderBlock(
+  block: unknown,
+  index: number,
+): { readonly html: string } | TeachRefused {
+  if (typeof block !== 'object' || block === null || !('type' in block)) {
+    return badBlock(index, 'not an object carrying a type')
+  }
+
+  const type = (block as { readonly type: unknown }).type
+
+  if (!isBlockType(type)) {
+    return badBlock(index, `unrecognized type ${JSON.stringify(type)}`)
+  }
+
+  const fields = block as Record<string, unknown>
+
+  switch (type) {
+    case 'heading': {
+      if (fields.level !== 1 && fields.level !== 2) {
+        return badBlock(index, 'heading needs level 1 or 2')
+      }
+      if (!isString(fields.text)) {
+        return badBlock(index, 'heading needs a string text')
+      }
+      return {
+        html: render(Heading({ level: fields.level, children: fields.text })),
+      }
+    }
+    case 'paragraph': {
+      if (!isString(fields.text)) {
+        return badBlock(index, 'paragraph needs a string text')
+      }
+      if (fields.lede !== undefined && typeof fields.lede !== 'boolean') {
+        return badBlock(index, 'paragraph lede must be a boolean')
+      }
+      return {
+        html: render(Paragraph({ lede: fields.lede, children: fields.text })),
+      }
+    }
+    case 'list': {
+      if (!isStringArray(fields.items)) {
+        return badBlock(index, 'list needs an items array of strings')
+      }
+      if (fields.ordered !== undefined && typeof fields.ordered !== 'boolean') {
+        return badBlock(index, 'list ordered must be a boolean')
+      }
+      return {
+        html: render(List({ ordered: fields.ordered, items: fields.items })),
+      }
+    }
+    case 'raw': {
+      if (!isString(fields.html)) {
+        return badBlock(index, 'raw needs a string html')
+      }
+      return { html: fields.html }
+    }
+  }
+}
+
+/**
+ * Renders a lesson body's structural blocks through the same components
+ * `render-fixture.tsx` composes by hand, so a real lesson and the committed
+ * fixture share one rendering mechanism. Every block past the first refusal
+ * goes unread, matching how a malformed JSON parse refuses the whole call.
+ */
+export function renderLessonBody(blocks: readonly unknown[]): RenderOutcome {
+  const rendered: string[] = []
+
+  for (const [index, block] of blocks.entries()) {
+    const result = renderBlock(block, index)
+    if ('ok' in result) return result
+    rendered.push(result.html)
+  }
+
+  return { ok: true, html: rendered.join('\n') }
+}