@erclx/canon 5.16.0 → 5.17.0

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.16.0",
+  "version": "5.17.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -9,12 +9,17 @@ description: Why a figure decides between Mermaid and freehand SVG before drawin
 
 Without this skill, a session asked for a figure reaches for whichever path it thought of first. A graph-shaped subject gets model-authored SVG coordinates nobody checked against a render, drifting from the hand-drawn look every other figure in the project carries. A subject that is not graph-shaped gets forced through Mermaid's node-and-edge model, producing a diagram that answers a different question than the one asked. Either failure ships a figure a reader cannot trust, and a figure exists only to be trusted at a glance.
 
+A teach lesson breaks the Mermaid path outright. The lesson letters its figures in a hand font the renderer cannot load, so the render sizes every label in a narrower fallback face and the lesson clips the text it actually shows. The check then reads the standalone image, rendered in that same fallback, and passes a figure the reader sees clipped. Both happened on one lesson, where every group title clipped mid-word and only a capture taken inside the lesson showed it.
+
 The color failure is the quiet one. Mermaid's own theme writes literal hex values, and a figure carrying one stops re-coloring itself the moment the host page switches its palette, which the figure standard's own accessibility bar rules out.
 
 ## Must
 
 - Apply the standard's earn-its-place bar before drawing anything
 - Decide between the Mermaid path and the freehand path by whether the subject reduces to a graph, not by which is faster to produce
+- Draw a figure bound for a teach lesson freehand whatever its shape, since the lesson's hand font is one the renderer cannot measure
+- Verify a figure bound for a rendered page by capturing it inside that page, and fall back to the standalone render only where the destination has no page to load
+- Keep the scoped overflow style as the documented fallback for a clipped group title wherever the Mermaid path still runs
 - Render the Mermaid path with the hand-drawn look and the figure font stack, never with Mermaid's default look
 - Rewrite every literal color the renderer wrote into the custom property the host stylesheet defines
 - Read the Mermaid render back and judge it against what the figure means to say, the same verification `draft-diagram` runs for the architecture surface
@@ -22,7 +27,8 @@ The color failure is the quiet one. Mermaid's own theme writes literal hex value
 
 ## Must not
 
-- Force a non-graph-shaped subject through Mermaid, or route a graph-shaped one through freehand SVG coordinates a model authored by hand
+- Force a non-graph-shaped subject through Mermaid, or route a graph-shaped one through freehand SVG coordinates a model authored by hand outside a teach lesson
+- Report a figure bound for a rendered page as verified from the standalone render alone
 - Ship a literal hex color on either path
 - Report a clean verification when the Mermaid render was skipped or a defect survived
 - Loop past two correction passes on a surviving defect
@@ -39,4 +45,4 @@ The color failure is the quiet one. Mermaid's own theme writes literal hex value
 - The toolkit's own `.canon/diagrams/` architecture surface, which shares no code, font, or visual language with this convention: `draft-diagram`
 - Mermaid's own layout, budgets, and label rules for the fence itself: the mermaid standard, cited rather than restated here
 - A UI wireframe or screen mockup: `draft-wireframes`
-- `teach-workspace`'s own lesson-figure authoring, which stays inline rather than calling this skill
+- Which lesson needs a figure and where it sits among the lesson's blocks: `teach-workspace`, which calls this skill to draw one

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

@@ -27,10 +27,11 @@ Apply the standard's bar: a relationship, a boundary, a path, or a before-and-af
 
 ## Step 3: decide the render path
 
+- **A teach lesson**, meaning the destination is a lesson page in a learning workspace's `lessons/` folder: draw it through Step 5 whatever its shape. The lesson letters its figures in a hand font the renderer cannot load, so a Mermaid render measures its labels in a narrower face and the lesson clips them.
 - **Graph-shaped**, meaning the relationship, boundary, or path is already what a flowchart or sequence diagram expresses: draw it through Step 4.
 - **Not graph-shaped**, meaning the subject is a spatial or physical arrangement no flowchart reduces to: draw it through Step 5.
 
-State which path was picked and why in one sentence. The standard states this as a render-first policy rather than a ban on any tool-exported drawing, so a graph-shaped subject always routes through Mermaid even though that is itself an external renderer.
+Take the first that matches, and state which path was picked and why in one sentence. The standard states this as a render-first policy rather than a ban on any tool-exported drawing, so outside a teach lesson a graph-shaped subject always routes through Mermaid even though that is itself an external renderer.
 
 ## Step 4: the Mermaid path
 
@@ -51,6 +52,8 @@ Render both formats in one pass: the SVG is what ships inside the `<figure>`, an
 Use `bunx` when bun is available, falling back to `npx -y @mermaid-js/mermaid-cli ...` otherwise.
 
 - Rewrite every stroke, fill, and text color the renderer wrote as a literal hex value into the custom property the host stylesheet defines, per the standard's color rule. Mermaid's own theme has no notion of a custom property, so this is a source edit made to the rendered SVG, not a config option.
+- Expect a group title or a long label to clip once the destination shows it in the hand font, since the renderer sized its box in a fallback face.
+- When the in-page check shows a clipped title, add a `<style>` inside the SVG, scoped to that SVG's own id, that sets `overflow: visible` on the clipped label's `foreignObject` and centers the label within it, so the wider text spills past both edges evenly. The style hides the mismatch for a title and does nothing for a node label crowding its box, which takes a shorter label instead.
 - Check whether the project ran `canon design css --figures`. The figure and figcaption styling ships unconditionally either way, but that flag alone embeds the Virgil and Excalifont font files. Without it, the figure falls back to the browser's own generic `cursive` face rather than the intended hand-drawn font, and Step 7's output names that gap when the flag was not passed.
 
 ## Step 5: the freehand path
@@ -58,7 +61,7 @@ Use `bunx` when bun is available, falling back to `npx -y @mermaid-js/mermaid-cl
 - Author the SVG by hand: plain shapes and lines authored directly in the markup.
 - Follow the standard's `## Color and accessibility` section for every fill, stroke, and accessible name.
 
-There is no external render to verify a freehand drawing against. The check here is the stroke-and-fill audit above and a read of the markup against what the subject means to show, done once rather than looped.
+There is no external render to verify a freehand drawing against before it is written. The check here is the stroke-and-fill audit above and a read of the markup against what the subject means to show, done once rather than looped. Hand-placed coordinates can drift out of line where a layout engine would not, so a freehand figure bound for a rendered page also takes Step 7's in-page capture.
 
 ## Step 6: wrap, caption, and verify
 
@@ -66,12 +69,23 @@ There is no external render to verify a freehand drawing against. The check here
 - On the Mermaid path, read the rendered PNG back and judge it against what the figure means to say, the same check `draft-diagram` Steps 5 and 6 run for the architecture surface. Fix the mermaid source and re-render on a defect. Stop after two correction passes. When a defect survives, keep the figure and name the defect in the output rather than reporting a false verification.
 - On either path, confirm the figure still reads once every color and font it depends on is stripped to its fallback, per the standard's own working-figure bar.
 - When the render fails for any reason, no browser engine, no network, no package manager, continue to Step 7 and name the skipped check. A missing renderer degrades the loop rather than failing it.
+- When the destination is a rendered page, an HTML file a browser loads, the check that counts is the figure inside that page, which Step 7 runs once the figure is written. The standalone PNG is measured in the renderer's own fonts and can read clean while the page clips it. A markdown destination has no page to load, so the standalone check above is the whole check there.
 
 ## Step 7: confirm and write
 
 Show the destination path, the decided render path, and the full `<figure>` markup before writing. Confirm with the user, since the graph-shaped decision and the render verdict are judgment calls with no diff to preview either against.
 
-Write the figure into the destination document at the location the user named. Renders under `.canon/tmp/figures/` are verification artifacts, and the scratch PNG and JSON config are deleted after Step 6 confirms, since only the SVG ships.
+Write the figure into the destination document at the location the user named.
+
+When the destination is a rendered page, capture the figure inside it and read the capture against what the figure means to say:
+
+```bash
+canon capture <destination> --selector figure --out .canon/tmp/figures/
+```
+
+Narrow the selector to this figure, such as by an id on its `<figure>`, when the page carries more than one. Fix a clipped label, a misaligned shape, or an arrow that misses its target in the destination and capture again, within the same two correction passes Step 6 allows. A clipped group title on the Mermaid path takes the scoped overflow style Step 4 states. When the capture fails, keep the figure and name the skipped check in the output, the same way Step 6 treats a failed render.
+
+Renders and captures under `.canon/tmp/figures/` are verification artifacts, and the scratch PNGs, the stamps the capture writes beside them, and the JSON config are deleted once the checks confirm, since only the SVG ships.
 
 ## Output
 
@@ -88,6 +102,7 @@ Write the figure into the destination document at the location the user named. R
 
 ```plaintext
 ✅ Drafted figure in <path>
-Verified render. <defect or skipped check, one line, omitted when clean>
+Render path: <mermaid | freehand>
+Verified <in page | as a standalone render>. <defect or skipped check, one line, omitted when clean>
 <Font not embedded: run `canon design css --figures` to ship Virgil and Excalifont. Omitted when the project already ran it.>
 ```

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

@@ -24,7 +24,7 @@ This skill stays fully independent of `context-fold`'s wireframe coverage sweep,
 
 ## Tier detection
 
-- Read `canon/DESIGN.md` and every existing `canon/wireframes/` file for a tier signal: a Stitch, Excalidraw, or Figma reference, or a marker naming one of them.
+- Read `canon/DESIGN.md` and every existing `canon/wireframes/` file for a tier signal: an Excalidraw or Figma reference, or a marker naming one of them.
 - State the detected tier at the confirm step. Always draft the regions-and-states shape regardless of what is detected, since that is the only shape this skill or any other shipped mechanism produces, adding the ASCII sketch fence only when the layout is not built yet. Report a higher tier rather than attempting a companion render for it.
 - Default silently to tier 0 when nothing is detected.
 

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

@@ -69,7 +69,7 @@ canon teach resource <topic> --json \
   --lead "<title>=<url>"
 ```
 
-Each flag repeats, and the pair splits on the first `=` so a URL carrying one survives. A URL already listed is refused rather than repeated.
+Each flag repeats, and the pair splits on the first `=` so a URL carrying one survives. A listed URL is refused, but `--read` moves an opened lead.
 
 A claim nothing was read for is the failure this step exists against. Where no source is reachable, say so in the lesson and mark what rests on recall.
 

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

@@ -40,7 +40,7 @@ Decide the figure once per lesson, before writing the body.
 
 1. Name the one relationship, boundary, path, or before-and-after the lesson is about. A lesson about none ends here, with `Figure: none, <why it names no structure>` on the reply.
 2. Hold it against the bar in `${CLAUDE_SKILL_DIR}/../../standards/figures.md`, which also carries the drawing rules.
-3. Draw it through `canon:draft-figure` into a `raw` block in the body, before the quiz entry and never inside it or after its feedback, which breaks the stepper's gating. Report it, never hand-draw, when that skill does not resolve.
+3. Draw it hand-written through `canon:draft-figure` into a `raw` block before the quiz, never inside it or after its feedback, which breaks the stepper's gating. Report it, never draw it yourself, if the skill does not resolve.
 4. Or write one line on why prose carries it better, such as a structure an earlier lesson gave.
 
 A structure lesson takes step 3 or 4, never neither. Put the outcome on the reply's `Figure:` line, off the lesson page. Never draw to satisfy the step, or on every section (`## Restraint`).

package/docs/agents/demo.md

@@ -26,7 +26,7 @@ Each demo owns a folder, `demos/<slug>/`, and `compile` writes the plan into it.
 | `plan.json`  | yes       | The compiled plan, with its hand-tuned timing         |
 | `index.html` | yes       | The HyperFrames composition, when the demo is wrapped |
 | `demo.gif`   | yes       | The one deliverable a README embeds                   |
-| `take/`      | no        | The raw recording and its still, written by `run`     |
+| `take/`      | no        | The raw recording, its still, and its timeline        |
 | `renders/`   | no        | The composed mp4, written by the render               |
 
 A project carries `demos/*/take/` and `demos/*/renders/` in its `.gitignore`, since both are one command away and a webm is large. A plan compiled before this layout, at `demos/<slug>.json`, still runs by path, because only the default moved.
@@ -58,6 +58,8 @@ A recording that has to match both themes takes one plan per scheme, committed s
 
 A step's caption from the draft renders as an overlay while its hold plays, so the narration a person wrote is what shows on screen rather than the name of the action the engine performed.
 
+Beside the webm, the run writes `<video-basename>.timeline.json`, so a composition can aim a zoom at the moment and the place of an action rather than adding up holds by hand. It holds an `entries` array with one entry per step, each carrying the step's `index`, its `kind`, and `startMs` and `endMs` counted from the recording's first frame. A step ends once its hold has played. A click, fill, or hover entry also carries `box`, the target's `x`, `y`, `width`, and `height` in viewport pixels, which are the video frame's own coordinates. A navigate, scroll, wait, or hold entry carries no `box`, and the file is still written. A run under `--no-video` writes no timeline, since there is no video for it to sit beside. The `--json` record names the file under `timeline`, and `null` when none was written.
+
 When `ffmpeg` is on PATH, the run also writes an mp4 beside the webm, since webm plays in a `<video>` tag but nothing else accepts it. A target without `ffmpeg` still gets the webm and a line naming what to install, and the run does not fail over the missing converter.
 
 `--gif` adds a third file from the same converter, and it is opt-in where the mp4 is not. A gif runs several times the size of the webm it derives from, and the destination that needs one is a README on a host that strips `<video>`, which GitHub does. The filter generates a palette from the source and then applies it, rather than quantizing per frame, since a per-frame palette is what makes a recording of flat interface colors band and shimmer. It applies that palette without dithering, because the command records applications rather than photographs and the dither writes noise the encoder then stores. One recording measured 3,193,715 bytes dithered against 2,701,941 without, with the same text region cropped from both and read as identical. A missing converter is reported the same way it is for the mp4, so an absent `ffmpeg` costs the gif and not the run.

package/docs/agents/teach.md

@@ -83,7 +83,7 @@ canon teach resource regular-expressions \
 
 The pair splits on the first `=`, so a URL carrying its own separator survives intact. Say in the title which claims rest on the source, since the entry is the only place a later session reads that from. Which sources qualify is the source ladder in `canon standards teach`, and a source below its first two rungs also names why no higher one covers the claim.
 
-A URL either heading already lists is refused rather than written twice. Two entries for one source split what rests on it across two lines, and a reader checking a claim then finds half of the answer.
+A URL either heading already lists is refused rather than written twice. Two entries for one source split what rests on it across two lines, and a reader checking a claim then finds half of the answer. The exception is a `--read` URL already under `## Leads`, which moves to `## Read` under the title the call carries, since opening a lead is how it becomes read. A `--read` URL already under `## Read`, and any `--lead` URL already listed, stays refused, and a refusal leaves the whole batch unwritten.
 
 A URL a file displays inside a fence does not count as listed, which is how a workspace quoting the entry format in its own prose is read as the sample it is.
 
@@ -142,7 +142,7 @@ Read `url` off the record rather than building one from the port that was asked
 | `exists`       | A workspace already covers the topic an open names              |
 | `no-file`      | The workspace carries no file the verb writes into              |
 | `no-section`   | `RESOURCES.md` carries no heading the entries belong under      |
-| `listed`       | A URL is already listed under either heading                    |
+| `listed`       | A URL is already read, or a lead is offered as listed           |
 | `defined`      | A term already carries a glossary entry                         |
 | `bad-input`    | The command line is malformed, before any folder is read        |
 

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

@@ -8,9 +8,9 @@ category: Workflow
 
 Three tiers cover the range from prose-only design docs to a fully graphical design source of truth. Pick one per project based on how UI-heavy the work is, whether stakeholders review visuals, and whether a designer is involved. Tiers stack, so moving up does not invalidate work done at a lower tier.
 
-The tier framework sits alongside [Claude Design](../../wiki/claude/design.md), the one catalog page in this range. Stitch, Excalidraw, and the surrounding MCP and skill ecosystem are named inline below rather than catalogued separately. This page decides when to reach for what.
+The tier framework sits alongside [Claude Design](../../wiki/claude/design.md), the one catalog page in this range. Excalidraw and the surrounding MCP and skill ecosystem are named inline below rather than catalogued separately. This page decides when to reach for what.
 
-Two tools anchor tier 1 and tier 2. Stitch is the agent-addressable default through its MCP server at `stitch.googleapis.com/mcp`, with a free tier of 400 daily credits that covers daily iteration. [Claude Design](../../wiki/claude/design.md), released 2026-04-17 and priced inside Claude subscriptions, is the ceiling tool reserved for codebase extraction and the richly annotated handoff bundle. Each covers a different job, they are not swappable.
+[Claude Design](../../wiki/claude/design.md), released 2026-04-17 and priced inside Claude subscriptions, is the ceiling tool for tier 1 and tier 2. Reserve it for codebase extraction and the richly annotated handoff bundle.
 
 ## Tier 0: prose only
 
@@ -56,21 +56,19 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 
 ASCII and prose stay as source of truth. Add a visual render as a feedback surface for the agent and for human review.
 
-- Stitch via MCP handles agent-driven generation of prototypes and design systems
 - Excalidraw handles agent-driven wireframes when the round-trip canvas loop matters
 - Claude Design joins only when codebase extraction or the annotated handoff bundle is worth the ceiling cost
 
-All three produce derived artifacts, so human edits are review annotations rather than source changes.
+Both produce derived artifacts, so human edits are review annotations rather than source changes.
 
 ### Seed shape
 
-Same as tier 0 with two additions. `WIREFRAMES.md` opts into Excalidraw rendering via a top-of-file marker like `<!-- excalidraw: WIREFRAMES.excalidraw -->`. `DESIGN.md` stays human-maintained, and its content is what the toolkit provisions into Stitch via `create_design_system` when visual generation is needed.
+Same as tier 0 with one addition. `WIREFRAMES.md` opts into Excalidraw rendering via a top-of-file marker like `<!-- excalidraw: WIREFRAMES.excalidraw -->`. `DESIGN.md` stays human-maintained.
 
-Impeccable, if installed, keeps its own root `DESIGN.md` and `PRODUCT.md` in the Stitch DESIGN.md spec format. These are separate files from the toolkit's `canon/DESIGN.md` and are not synced with it. Treat impeccable's pair as its own source of truth for its commands, and the toolkit's `canon/DESIGN.md` as the source other toolkit skills read.
+Impeccable, if installed, keeps its own root `DESIGN.md` and `PRODUCT.md` in its own format. These are separate files from the toolkit's `canon/DESIGN.md` and are not synced with it. Treat impeccable's pair as its own source of truth for its commands, and the toolkit's `canon/DESIGN.md` as the source other toolkit skills read.
 
 ### Tools
 
-- Stitch via MCP at `stitch.googleapis.com/mcp`, Google's Gemini-powered design product. Agent-addressable through `generate_screen_from_text`, `edit_screens`, and `generate_variants`. Default pick for agent-driven visual generation. Free tier of 400 daily credits.
 - Excalidraw canvas server on localhost plus the community [`yctimlin/mcp_excalidraw`](https://github.com/yctimlin/mcp_excalidraw) MCP shim, for projects that need an agent to draw, read back, and revise a canvas. MIT-licensed, plaintext JSON scene format. `describe_scene` and `get_canvas_screenshot` let the agent verify its own layout before claiming it is correct.
 - Playwright MCP ([`microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp)) for browser-side verification, driven off the accessibility tree rather than screenshots.
 - Chrome DevTools MCP ([`ChromeDevTools/chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp)) for live frontend debugging: performance traces, network inspection, and DOM and CSS inspection.
@@ -88,17 +86,15 @@ Impeccable, if installed, keeps its own root `DESIGN.md` and `PRODUCT.md` in the
 - Design decisions benefit from visual inspection
 - A single contributor owns both design and implementation
 
-### Stitch vs Excalidraw vs Claude Design in tier 1
+### Excalidraw vs Claude Design in tier 1
 
-The three tools solve non-overlapping halves of the visual companion problem.
-
-Stitch via MCP generates polished prototypes from text and a provisioned design system, scripted from a Claude Code session. Output is human-facing and lives in Stitch. Free daily quota makes it the right pick for frequent iteration.
+The two tools solve non-overlapping halves of the visual companion problem.
 
 Excalidraw gives the agent a canvas it can read back over MCP. Output is agent-facing and persists as a JSON file in the repo. Pick it when Claude Code needs to iterate on wireframes autonomously, not when a human needs polished review artifacts.
 
 Claude Design reads the raw codebase without prose curation and produces a polished handoff bundle with chat history. Weekly quota makes it expensive, so reserve it for the extraction pass or the final handoff moment, not daily iteration.
 
-Most tier 1 projects pick one. Projects with a messy codebase and no curated `DESIGN.md` may want Claude Design once for the initial extraction, then move to Stitch for ongoing work.
+Most tier 1 projects pick one. Projects with a messy codebase and no curated `DESIGN.md` may want Claude Design once for the initial extraction.
 
 ## Tier 2: visual as source of truth
 
@@ -112,7 +108,6 @@ Design happens in a graphical tool. `canon/DESIGN.md` either regenerates from th
 
 - Figma desktop app with the official [Figma Dev Mode MCP](https://www.figma.com/blog/introducing-claude-code-to-figma/) for teams with a dedicated designer already on Figma. Bidirectional sync and Code to Canvas capture of a running Claude Code UI into editable Figma frames.
 - Claude Design with its Claude Code handoff bundle for teams without an existing Figma investment and for solo founders or PMs driving design themselves. One-way handoff, no bidirectional sync. See [Claude Design](../../wiki/claude/design.md).
-- Stitch via MCP as a low-cost complement to either, used for bulk screen generation driven by Claude Code.
 - Playwright and Chrome DevTools MCPs as in tier 1
 
 ### Skills
@@ -132,8 +127,6 @@ Figma wins when a dedicated designer already owns a Figma file, external collabo
 
 Claude Design wins when nobody on the team has a Figma workflow yet and the handoff bundle with chat history is the intended implementation path. Claude Design's handoff is one-way, and its quota limits daily iteration, so it is most useful for the initial extraction pass and the final handoff moment rather than day-to-day design work.
 
-Either of the above pairs cleanly with Stitch via MCP for agent-driven screen generation between the two anchor moments.
-
 ## Decision guide
 
 Four questions. Each yes weighs toward a higher tier.

package/governance/rules/claude/566-output.md

@@ -7,12 +7,10 @@ description: Report file paths correctly for the reading surface and group them
 ## Reporting paths
 
 - After creating or modifying a file, include its path on its own line so the reader can open it. Do not paraphrase paths into prose ("the seeds folder", "your CLAUDE.md").
-- Read `CLAUDE_CODE_ENTRYPOINT` once, at the first response that emits a path, and reuse it for the rest of the session. The surface cannot change mid-session, so a second read only confirms the first.
-- When it reads `claude-desktop`, emit each path as a markdown link carrying the path as its text and an absolute `file://` URI as its target, resolving a relative path against the main project root to build that target. The desktop file tree hides dotted folders, so a bare path into one names a file the reader cannot reach.
-- On every other value, including unset, emit the path bare. A terminal emulator makes it clickable through its own path detection, and link markup defeats that.
-- Both forms govern a path emitted in a response. A path written into a markdown file follows the markdown standard instead, which your toolkit resolves by name, and which backticks a file reference and never repeats it as a link label.
+- Emit a path in the form the surface's own instructions give, such as a markdown link where the harness asks for one, and bare where it gives none. A terminal makes a bare path clickable through its own path detection, and link markup defeats that.
+- That form governs a path emitted in a response. A path written into a markdown file follows the markdown standard instead, which your toolkit resolves by name, and which backticks a file reference and never repeats it as a link label.
 - In a linked worktree (under `.claude/worktrees/<name>/`), emit the absolute path, since the editor is rooted at the main project root and a path relative to the worktree resolves nowhere there. Prefer the form a `PostToolUse` hook hands back after a write where one is installed.
 
 ## Grouping multiple files
 
-- When the response covers multiple files, group paths under headers: `**Created:**`, `**Modified:**`, `**Deleted:**`. Every path under them takes the form the entrypoint selected rather than the first alone. For single-file changes, the path on its own line is enough.
+- When the response covers multiple files, group paths under headers: `**Created:**`, `**Modified:**`, `**Deleted:**`. Every path under them takes that form, not the first alone. For single-file changes, the path on its own line is enough.

package/governance/rules/claude/575-hooks.md

@@ -9,7 +9,7 @@ paths:
 
 ## Reading a payload
 
-- Open a hook that reads a payload with a bounded `IFS= read -r -d '' -t 2 input`, exiting non-zero on an empty payload. An unbounded `cat` blocks forever against a hand run or an open socket, holding the session open with it. A test already checks this per file across both hook trees, but the rule stops the pattern being rediscovered rather than caught only after the fact.
+- Open a hook that reads a payload with a bounded `IFS= read -r -d '' -t 2 input`, exiting non-zero on an empty payload. An unbounded `cat` blocks forever against a hand run or an open socket, holding the session open with it.
 
 ## Silencing output
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.16.0",
+  "version": "5.17.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/commands/demo.ts

@@ -333,6 +333,7 @@ async function runDrive(planPath: string, opts: RunOptions): Promise<number> {
 
   if (result.videoPath) logInfo(display(result.videoPath))
   if (result.stillPath) logInfo(`${display(result.stillPath)}  still`)
+  if (result.timelinePath) logInfo(`${display(result.timelinePath)}  timeline`)
   logInfo(
     `${result.steps} steps in ${Math.round(result.durationMs / 100) / 10}s`,
   )
@@ -380,6 +381,7 @@ async function runDrive(planPath: string, opts: RunOptions): Promise<number> {
     mp4: mp4Path ?? null,
     gif: gifPath ?? null,
     still: result.stillPath ?? null,
+    timeline: result.timelinePath ?? null,
     steps: result.steps,
     durationMs: result.durationMs,
     ...(mp4Reason ? { mp4Reason } : {}),

package/src/commands/teach.ts

@@ -237,7 +237,9 @@ export function register(program: Command): void {
         'only place a later session reads that from.',
         '',
         'A URL already listed under either heading is refused rather than',
-        'repeated, because two entries split what rests on one source.',
+        'repeated, because two entries split what rests on one source. The one',
+        'exception is a --read URL listed under Leads, which moves to Read under',
+        'its new title.',
         '',
         'Examples:',
         '  canon teach resource regular-expressions --read "MDN regular expressions=https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions"',

package/src/demo/drive.ts

@@ -8,6 +8,8 @@ import { deriveSteps } from '@/demo/compile'
 import type { DemoPlan, DemoStep } from '@/demo/compile'
 import type { CursorSet } from '@/demo/pointer'
 import { pointerSource } from '@/demo/pointer'
+import type { StepTiming, TargetBox } from '@/demo/timeline'
+import { timelineEntry, timelinePath, writeTimeline } from '@/demo/timeline'
 
 declare global {
   interface Window {
@@ -84,6 +86,7 @@ export type DriveResult =
       status: 'recorded'
       videoPath?: string
       stillPath?: string
+      timelinePath?: string
       steps: number
       durationMs: number
     }
@@ -150,6 +153,7 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
 
   let stillPath: string | undefined
   let videoPath: string | undefined
+  let timeline: string | undefined
 
   try {
     await context.addInitScript({
@@ -157,7 +161,12 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
     })
     await context.addInitScript({ content: captionInitScript() })
     const page = await context.newPage()
+    // The recording begins with the page, so this is the instant a frame of
+    // the take is zero. Taking it at the first step instead would drift every
+    // entry by the opening page load.
+    const recordingStart = performance.now()
     const video = page.video()
+    const timings: StepTiming[] = []
     const pace: PointerPace = {}
 
     // The opening navigate is skipped when the plan already starts with one,
@@ -170,8 +179,16 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
       }
     }
 
-    for (const step of plan.steps) {
-      await runStep(page, plan, step, pace)
+    for (const [index, step] of plan.steps.entries()) {
+      const startedAt = performance.now()
+      const box = await runStep(page, plan, step, pace)
+      timings.push({
+        index,
+        kind: step.kind,
+        startedAt,
+        endedAt: performance.now(),
+        ...(box ? { box } : {}),
+      })
       // The first marked step wins. One file holds one frame, so a plan a
       // person edited to mark several would otherwise write each over the last
       // and keep whichever ran last, with nothing saying so.
@@ -191,6 +208,11 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
       // The engine keeps the auto-named recording beside the saved copy, so a
       // run that skipped this would leave two files for every demo.
       await video.delete()
+      timeline = timelinePath(videoPath)
+      writeTimeline(
+        timeline,
+        timings.map((timing) => timelineEntry(timing, recordingStart)),
+      )
     }
   } catch (error) {
     return failed('drive-failed', error)
@@ -203,6 +225,7 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
     status: 'recorded',
     ...(videoPath ? { videoPath } : {}),
     ...(stillPath ? { stillPath } : {}),
+    ...(timeline ? { timelinePath: timeline } : {}),
     steps: plan.steps.length,
     durationMs: Date.now() - started,
   }
@@ -237,13 +260,17 @@ export interface PointerPace {
  * Exported so `drive.e2e.test.ts` can drive one real step against a real
  * caption and read it back, which is the integration a full `drive()` call
  * cannot assert without decoding the video it writes.
+ *
+ * Returns the box the pointer moved to, for the timeline, and nothing for
+ * a step that points at no target.
  */
 export async function runStep(
   page: Page,
   plan: DemoPlan,
   step: DemoStep,
   pace: PointerPace,
-): Promise<void> {
+): Promise<TargetBox | undefined> {
+  let box: TargetBox | undefined
   switch (step.kind) {
     case 'navigate':
       await page.goto(step.target || plan.url)
@@ -252,18 +279,18 @@ export async function runStep(
       }
       break
     case 'click':
-      await moveTo(page, plan, step, pace)
+      box = await moveTo(page, plan, step, pace)
       await page.mouse.down()
       await page.mouse.up()
       break
     case 'fill':
-      await moveTo(page, plan, step, pace)
+      box = await moveTo(page, plan, step, pace)
       await page.mouse.down()
       await page.mouse.up()
       await page.keyboard.type(step.text, { delay: plan.pointer.typeDelayMs })
       break
     case 'hover':
-      await moveTo(page, plan, step, pace)
+      box = await moveTo(page, plan, step, pace)
       break
     case 'scroll':
       // Centred rather than `scrollIntoViewIfNeeded`, which scrolls the least
@@ -307,6 +334,7 @@ export async function runStep(
   await setCaption(page, step.caption)
   if (step.waitFor) await page.locator(step.waitFor).first().waitFor()
   await page.waitForTimeout(step.holdMs)
+  return box
 }
 
 /**
@@ -333,7 +361,7 @@ async function moveTo(
   plan: DemoPlan,
   step: DemoStep,
   pace: PointerPace,
-): Promise<void> {
+): Promise<TargetBox> {
   pace.roundTripMs ??= await calibrateRoundTrip(page)
   const locator = page.locator(step.target).first()
   await locator.waitFor()
@@ -342,6 +370,7 @@ async function moveTo(
   await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, {
     steps: deriveSteps(plan.pointer.travelMs, pace.roundTripMs),
   })
+  return box
 }
 
 /**

package/src/demo/timeline.ts

@@ -0,0 +1,64 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname, join } from 'node:path'
+import type { DemoStep } from '@/demo/compile'
+
+/**
+ * A step's target in viewport pixels, which are the video frame's own
+ * coordinates because the recording is sized to the viewport.
+ */
+export interface TargetBox {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+/** One step as the run clocked it, in wall-clock milliseconds. */
+export interface StepTiming {
+  readonly index: number
+  readonly kind: DemoStep['kind']
+  readonly startedAt: number
+  readonly endedAt: number
+  readonly box?: TargetBox
+}
+
+/**
+ * Times count from the recording's start rather than the first step, since
+ * that is the clock a composition places the take on. A step ends once its
+ * hold has played, so the span covers what the viewer sees of it.
+ */
+export interface TimelineEntry {
+  readonly index: number
+  readonly kind: DemoStep['kind']
+  readonly startMs: number
+  readonly endMs: number
+  readonly box?: TargetBox
+}
+
+export function timelineEntry(
+  timing: StepTiming,
+  recordingStart: number,
+): TimelineEntry {
+  return {
+    index: timing.index,
+    kind: timing.kind,
+    startMs: Math.round(timing.startedAt - recordingStart),
+    endMs: Math.round(timing.endedAt - recordingStart),
+    ...(timing.box ? { box: timing.box } : {}),
+  }
+}
+
+export function timelinePath(videoPath: string): string {
+  return join(
+    dirname(videoPath),
+    `${basename(videoPath, extname(videoPath))}.timeline.json`,
+  )
+}
+
+export function writeTimeline(
+  path: string,
+  entries: readonly TimelineEntry[],
+): void {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${JSON.stringify({ entries }, null, 2)}\n`)
+}

package/src/teach/workspace.ts

@@ -885,12 +885,60 @@ async function openFile(
   return path
 }
 
+/** The entry lines of the file, or of one heading's section. */
+function listedEntries(text: string, heading?: string): string[] {
+  const body = unfenced(text)
+  const section = heading
+    ? sectionRange(body, heading, text.split('\n').length)
+    : undefined
+  if (heading && !section) return []
+
+  return body
+    .filter(
+      (line) =>
+        isEntry(line.text) &&
+        (!section ||
+          (line.number - 1 >= section.start && line.number - 1 < section.end)),
+    )
+    .map((line) => line.text)
+}
+
+function lists(entries: readonly string[], source: Source): boolean {
+  return entries.some((line) => line.includes(`(${source.url})`))
+}
+
+/**
+ * Drops the lead entries naming the given URLs, wrapped continuation lines
+ * included, and restores the placeholder when the section empties.
+ */
+function withoutLeads(text: string, urls: ReadonlySet<string>): string {
+  const lines = text.split('\n')
+  const section = sectionRange(unfenced(text), LEADS_HEADING, lines.length)
+  if (!section) return text
+
+  const bullets = bulletRange(unfenced(text), section)
+  if (!bullets) return text
+
+  const kept = bulletBlocks(lines.slice(bullets.start, bullets.end)).filter(
+    (block) => ![...urls].some((url) => block[0].includes(`(${url})`)),
+  )
+
+  return [
+    ...lines.slice(0, bullets.start),
+    ...(kept.length > 0 ? kept.flat() : [PLACEHOLDER]),
+    ...lines.slice(bullets.end),
+  ].join('\n')
+}
+
 /**
  * Appends sources to `RESOURCES.md`, keeping what was read apart from what was
  * only found.
  *
  * A URL already listed under either heading is refused rather than repeated,
  * since a second entry for one source splits what rests on it across two lines.
+ * The one exception is a read source found under `## Leads`, which moves to
+ * `## Read` under its new title, since opening a lead is how it becomes read.
+ * Any refusal leaves the file untouched, so a batch lands whole or not at all.
  */
 export async function recordSources(
   root: string,
@@ -905,13 +953,16 @@ export async function recordSources(
   if (typeof path !== 'string') return path
 
   let text = await readFile(path, 'utf8')
-  const listed = unfenced(text)
-    .map((line) => line.text)
-    .filter(isEntry)
+  const listed = listedEntries(text)
+  const leadEntries = listedEntries(text, LEADS_HEADING)
 
-  const repeated = [...read, ...leads].filter((source) =>
-    listed.some((line) => line.includes(`(${source.url})`)),
-  )
+  const isPromotion = (source: Source) => lists(leadEntries, source)
+  const promoted = read.filter(isPromotion)
+
+  const repeated = [
+    ...read.filter((source) => !isPromotion(source)),
+    ...leads,
+  ].filter((source) => lists(listed, source))
 
   if (repeated.length > 0) {
     return refuse(
@@ -921,6 +972,10 @@ export async function recordSources(
     )
   }
 
+  if (promoted.length > 0) {
+    text = withoutLeads(text, new Set(promoted.map((source) => source.url)))
+  }
+
   for (const [heading, sources] of [
     [READ_HEADING, read],
     [LEADS_HEADING, leads],

package/standards/figures.md

@@ -38,6 +38,7 @@ A figure failing these is non-conforming even when it satisfies every shape rule
 
 - Route a graph-shaped subject, one whose relationship, boundary, or path a flowchart already expresses, through Mermaid's own hand-drawn look rather than through model-authored SVG coordinates. `mermaid.md` governs the fence itself.
 - Reserve freehand inline SVG, plain shapes and lines authored directly in the markup, for a subject that is not graph-shaped. A figure that cannot express its subject through the deterministic path is a worse failure than an inconsistent one drawn by hand, so the hatch stays open rather than forcing every figure through the renderer.
+- Draw a figure in a teach lesson freehand whatever its shape. A lesson letters its figures in a hand font the renderer cannot load, so Mermaid measures every label in a narrower fallback face, and the page then clips the wider text it actually shows.
 - State this as a render-first policy rather than a ban on a tool-exported drawing. Routing a graph-shaped figure through Mermaid is itself running it through an external tool, so a rule banning any diagram "exported from a diagramming tool" would forbid the path this policy requires.
 
 ## Wrapping and captioning

package/tooling/claude/reference.md

@@ -91,6 +91,6 @@ The first entry covers the whole record root, so a record folder added later nee
 
 ## settings.json
 
-- Project seed at `tooling/claude/seeds/.claude/settings.json` ships two PreToolUse hooks (pairing with `.claude/hooks/index-reminder.sh` and `.claude/hooks/scratch-guard.sh`) and a PostToolUse hook (pairs with `.claude/hooks/standards-audit.sh`). Project settings layer over user settings, so per-project files only carry what is genuinely project-specific.
+- Project seed at `tooling/claude/seeds/.claude/settings.json` ships three PreToolUse hooks (pairing with `.claude/hooks/index-reminder.sh`, `.claude/hooks/search-reminder.sh`, and `.claude/hooks/scratch-guard.sh`) and a PostToolUse hook (pairs with `.claude/hooks/standards-audit.sh`). Project settings layer over user settings, so per-project files only carry what is genuinely project-specific.
 - User-level template at `tooling/claude/user/settings.template.json` carries `attribution.commit` and `attribution.pr` (empty strings to suppress co-author tags), `permissions.allow` with `Bash(bun run *)`, and `permissions.deny` with `Read(**/.env)` and `Read(**/.env.*)` to block accidental secret exposure across any project. Installed once per machine via `canon claude setup`.
 - The deprecated `includeCoAuthoredBy` key is not used.

package/tooling/claude/seeds/.claude/hooks/path-form.sh

@@ -8,10 +8,8 @@
 # and no error appears. This computes the fact a session was asking itself
 # to infer on every response and hands the answer back instead.
 #
-# The entrypoint branch (bare vs. `file://` link) stays prose in
-# governance/rules/claude/566-output.md. CLAUDE_CODE_ENTRYPOINT is not among
-# the environment variables Claude Code documents as passed to a hook
-# subprocess, unlike CLAUDE_PROJECT_DIR, so a hook cannot read it reliably.
+# The link form a response uses comes from the harness's own instruction for
+# its surface, not from this hook or the output rule.
 #
 # The worktree branch comes from the path rather than from `git rev-parse`,
 # the way `tasks-index.sh` and `memory-index.sh` already derive their main

package/tooling/claude/seeds/.claude/hooks/search-reminder.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
+
+tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
+[ "$tool" = "WebSearch" ] || exit 0
+
+# Without a session id there is no stable key to dedupe on, and a shared marker
+# would silence every later session, so stay quiet rather than guess one.
+session=$(printf '%s' "$input" | jq -r '.session_id // empty')
+[ -n "$session" ] || exit 0
+
+key=$(printf '%s' "$session" | tr -c 'A-Za-z0-9' '_')
+# The marker is scratch, so it follows the scratch folder to whichever record
+# root the project carries rather than creating a second one beside it.
+project="${CLAUDE_PROJECT_DIR:-.}"
+if [ -d "$project/.canon" ]; then
+  marker_dir="$project/.canon/tmp/hooks/search-reminder"
+else
+  marker_dir="$project/.claude/.tmp/hooks/search-reminder"
+fi
+marker="$marker_dir/$key"
+[ -f "$marker" ] && exit 0
+mkdir -p "$marker_dir"
+: >"$marker"
+
+msg='Load the canon:search-craft skill before this web search. Report it rather than proceeding silently when the skill does not resolve.'
+jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

package/tooling/claude/seeds/.claude/settings.json

@@ -10,6 +10,15 @@
           }
         ]
       },
+      {
+        "matcher": "WebSearch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/search-reminder.sh"
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit",
         "hooks": [