@erclx/canon 5.26.0 → 5.27.0

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

@@ -1,11 +1,22 @@
 ---
 title: Lesson craft reference
-description: Typography, restraint, quiz construction, what makes a lesson worth returning to, and the verbs that build the lesson body
+description: Typography, restraint, quiz construction, and what makes a lesson worth returning to
 ---
 
 # Lesson craft reference
 
-Judgment rather than shape. The workspace standard fixes where a lesson sits and what it is named, and this file covers what makes one worth opening twice.
+Judgment rather than shape. The workspace standard fixes where a lesson sits and what it is named, and this file covers what makes one worth opening twice. The block list and the verbs that build the lesson body sit in `lesson-build.md`.
+
+## Contents
+
+- [One course, not a pile of pages](#one-course-not-a-pile-of-pages)
+- [Typography](#typography)
+- [Restraint](#restraint)
+- [Diagrams](#diagrams)
+- [Quiz construction](#quiz-construction)
+- [Teach back](#teach-back)
+- [Tokens travel with the course](#tokens-travel-with-the-course)
+- [What makes a lesson worth returning to](#what-makes-a-lesson-worth-returning-to)
 
 ## One course, not a pile of pages
 
@@ -79,23 +90,6 @@ 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 a lesson body composes. Six 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,"cites":[1]}`: a `<p>`, marked `lede` for the dek that opens the lesson. `cites` adds a footnote marker per reference number after the text, and a lede takes none.
-- `{"type":"list","items":["<text>", ...],"ordered":true}`: a `<ul>` or, with `ordered`, an `<ol>`.
-- `{"type":"refs","items":[{"title":"<name>","url":"<https URL>","note":"<text>"}, ...]}`: the lesson's one reference list, numbered from 1 in item order. `url` and `note` are optional, and a `url` must be http or https.
-- `{"type":"code","lang":"ts","text":"<source>"}`: a code sample, highlighted at render time with no script. `lang` is optional and takes a highlight.js name or alias. One the renderer does not register renders as plain escaped code.
-- `{"type":"raw","html":"<markup>"}`: the escape hatch, passed through unescaped.
-
-Code never travels through `raw`. A hand-written `<pre><code>` renders with no color, and `nav` never highlights markup already in a lesson body, so a sample written that way stays plain for good. A fenced block in a reference page's markdown is highlighted by `nav` on its own.
-
-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 last `raw` entry, followed only by `refs`, rather than reaching for `raw` anywhere the other types could carry the content instead.
-
-A claim resting on a source carries a `cites` number, and the source goes in the lesson's one `refs` block rather than into the sentence. Draw every reference from what `canon teach resource --read` recorded, never from a lead, since a lead is a source nobody opened. Render refuses a cite no reference resolves, so number the list before citing into it.
-
 ## 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.
@@ -131,53 +125,3 @@ Pick values the material needs rather than values the project happens to hold. I
 - The lesson states what it assumes. A returning reader can tell in one line whether they are in the right place.
 - The hard part is named as the hard part. Material that flattens everything to one difficulty gives a returning reader nothing to navigate by.
 - Nothing depends on the session it was written in. A lesson referring to what was discussed is unreadable a week later.
-
-## Building the lesson body
-
-Step 4 of `teach-workspace` reads this section before writing a lesson, after the lesson verb has resolved its path and quiz order. 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":"paragraph","text":"<a claim resting on a source>","cites":[1]},
-  {"type":"list","ordered":true,"items":["<step one>","<step two>"]},
-  {"type":"raw","html":"<the quiz and teach-back block composed above>"},
-  {"type":"refs","items":[{"title":"<source name>","url":"<https URL>"}]}
-]' | canon teach render --json
-```
-
-`## The block list` above states each type and where `raw` belongs. 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
-```
-
-It fills every marker pair from what the workspace holds on disk: the embedded stylesheet, the header with its breadcrumb and jump menus, the prev/next footer nav, and the behavior scripts, and it rewrites the workspace's contents page and the teach-root listing in the same run. It refuses a lesson missing one of the four marker pairs by name rather than guessing at the boundary, so a marker dropped while writing the lesson is caught here rather than read back later as a lesson nothing links to. Report it rather than proceeding silently when the verb does not resolve, which is an installed CLI predating it, and never compose the chrome by hand as a fallback.
-
-Seed the stylesheet through the verb rather than authoring a palette, on the first lesson in a workspace:
-
-```bash
-canon teach stylesheet <topic> --json
-```
-
-It writes the design tokens as custom properties and the components built on them, from the one source every other rendered surface reads. Add lesson rules under the seed and reach a value through its property rather than restating the hex, which is what let each workspace fork the palette from every other. It refuses to overwrite, so running it again on a workspace that has grown its own rules is safe and reports `written` as false.
-
-Report it rather than proceeding silently when the verb does not resolve, which is an installed CLI predating it. Do not fall back to writing a palette by hand.
-
-Add every term the lesson defines to `GLOSSARY.md` through the verb, which places the entries alphabetically in the shape the standard fixes:
-
-```bash
-canon teach glossary <topic> --json \
-  --term "<term>=<definition, written without using the term>" \
-  --first-seen <the lesson or reference page this batch comes from>
-```
-
-`--term` repeats and one call writes the file once, which is what keeps a batch of terms from racing on it. A term already defined is refused, since a definition the subject has moved under is a revision of the entry rather than a second one.

package/claude/skills/teach-workspace/references/revisit.md

@@ -0,0 +1,22 @@
+---
+title: Revisit schedule
+description: How teach-workspace Step 5 writes a learning record's Revisit section, being the bullet shape, where each date and rung is copied from, the first schedule for a new item, and how a later record revises one
+---
+
+# Write the Revisit section
+
+Part of Step 5 of `teach-workspace`. The session reads this file once the record's lessons, retrievals, and wrong answers are written, before restating the mission's success lines.
+
+Then write `## Revisit`, one bullet per item, in the shape `${CLAUDE_SKILL_DIR}/../../standards/teach.md` fixes:
+
+```markdown
+## Revisit
+
+- **<what comes back up>**: due <YYYY-MM-DD>, rung <n>
+```
+
+Take both the date and the rung from the `due` entry Step 1 already read, copying `hit` for an item the learner retrieved unaided and `miss` for one they did not, with the rung stepped the same way. Do not compute a date from the ladder. A session told to widen a gap still picks the number by judgment, which is the reason the verb reports both dates at all.
+
+An item the records have never scheduled has no `due` entry to copy from. Open it at rung 1, dated the day after this session, which is the ladder's floor and the one number this body states. Every later date for it comes from the verb.
+
+An entry outside this shape schedules nothing and nothing reports that it was skipped, so write the shape exactly. A later record naming the same item supersedes an earlier entry, so revise a schedule by writing the new bullet rather than editing the record it was set in.

package/claude/skills/test-craft/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: test-craft
 description: Carries the rule that decides which layer a test belongs at, the question each one opens with, the end to end budget, and the final filter a session runs over what it wrote. Use when writing, changing, or judging a test, after implementing as well as before, when adding a regression guard, when choosing between unit, component, or end to end, or when asked "where should this test go", "is this a good test", "should this be an e2e test", or "why is our e2e suite so slow". Do NOT use for the red, green, refactor procedure, which is `test-first`, or for a bug nobody has explained yet, which is `systematic-debugging`.
+metadata:
+  family: build
 ---
 
 # Test craft

package/claude/skills/test-first/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: test-first
 description: Write the failing test for a behavior before writing the code that satisfies it, confirm it fails for the right reason, implement the smallest change that turns it green, then refactor with the suite green. Auto-triggers before implementing a planned feature, adding a function or an endpoint, or extending existing behavior whose new shape is already decided. Do NOT use for a failure with no known cause, which is canon:systematic-debugging, or when the test for the behavior already exists and already passes.
+metadata:
+  family: build
 ---
 
 # Test first

package/claude/skills/ui-checklist/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: ui-checklist
 description: Writes the visual checklist a reviewer reads beside the evidence screenshots, and names each changed behavior shipping with no test so `test-craft` can place one. Use after implementing UI changes, or when asked "what should I look at", "what do I verify", or "give me a visual checklist". Do NOT use in empty sessions with no implementation context, and do NOT use to write the tests themselves.
+metadata:
+  family: build
 ---
 
 # UI checklist

package/claude/skills/ux-audit/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: ux-audit
 description: Audits the current UI for incomplete, inconsistent, or confusing patterns. Reads DESIGN.md and canon/wireframes/ for intent, scans UI files, and outputs observations grouped by surface. Use when asked "audit the UX", "audit the UI", "UX audit", or "find UI roughness". Do NOT use for new feature planning or code changes, and do NOT use to measure what a running interface costs to paint, which is `ux-measure`.
+metadata:
+  family: check
 ---
 
 # UX audit

package/claude/skills/ux-measure/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: ux-measure
 description: Measures paint, processor, and layout cost against a running interface and reports numbers against published thresholds. Detects the project's existing browser harness rather than requiring one. Use when asked "how fast is this page", "measure the UI", "what does this cost to render", "check Core Web Vitals", or "profile the interface". Do NOT use to judge UI quality by reading source, which is `ux-audit`.
+metadata:
+  family: check
 ---
 
 # UX measure

package/claude/skills/ux-walkthrough/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: ux-walkthrough
 description: Runs an inspection walkthrough over a running app with the operator. Measures each finding off the built page, drafts arms as served HTML pages lifted from the app's own markup and stylesheet, hands over the localhost link before every pick question, records findings and picks with the arms they beat in one walkthrough file, and relays picks only in batches the operator calls. Use when asked to "run a first-use walkthrough", "do an operator walkthrough", "go through my findings one by one", "inspection walkthrough over the app", or "walk through everything I listed with me". Do NOT use for one decision on its own, which is `draft-and-pick`, to read source for roughness, which is `ux-audit`, or to build a pick, which is `plan-feature` and a worker.
+metadata:
+  family: check
 ---
 
 # UX walkthrough

package/claude/skills/video-craft/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: video-craft
 description: Carries what makes a composed video of software read as designed rather than generic, being captions that name only what the frame shows, which moment earns a zoom and how fast it lands, how a real pointer behaves on a real interface, music or silence and how far under a voice the music sits, and reading a frame before dismissing a checker finding. Every number traces to a source. Use before composing or judging any video, whether a product demo, an explainer, a pull request walkthrough, or a launch clip, when a render reads generic or slow, or when asked "make this video look designed", "is this zoom too slow", "what should this caption say", "should this have music", or "the checker flagged a frame, is it real". Do NOT use for general motion such as easing, speed variety, and click timing, which HyperFrames' `hyperframes-animation` and `hyperframes-creative` carry, to fetch or generate a media file, which is `media-use`, or to record the take, which is `record-screencast`.
+metadata:
+  family: build
 ---
 
 # Video craft

package/claude/skills/write-human/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: write-human
 description: Carries the voice, word choice, rhythm, sentence construction, and information density rules a banned-character scan cannot express, plus the catalog of machine tells that survive a clean ban scan. Use when writing or revising prose a person will read, when a passage reads flat or uniform, or when asked to "make this read like a person", "fix the cadence", "this reads like AI wrote it", "vary the sentences", or "tighten this without gutting it". Do NOT use for banned characters, which `markdown.md` states and `canon markdown audit` gates, and do NOT use to restate text that already exists in plainer words, which is `restate-plainly`, whose body loads these rules from here.
+metadata:
+  family: answer
 ---
 
 # Write human

package/claude/skills/youtube-transcripts/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: youtube-transcripts
 description: Fetches a YouTube video transcript with metadata frontmatter into the current repo via `canon transcripts`. Use when the user pastes a YouTube URL and asks to "grab the transcript", pull captions, or save a transcript for context. Do NOT use for downloading the video file, summarizing a transcript that already exists, or non-YouTube links.
+metadata:
+  family: answer
 ---
 
 # YouTube transcripts

package/docs/agents/canvas.md

@@ -1,6 +1,6 @@
 ---
 title: Canvas
-description: The canvas server, its content format, and the verbs that list, arrange, select, edit, and capture frames
+description: The canvas server, its content format, and the verbs that list, arrange, select, edit, mark, and capture frames
 ---
 
 # Canvas
@@ -11,7 +11,9 @@ description: The canvas server, its content format, and the verbs that list, arr
 
 `canvas serve` serves the canvas on `127.0.0.1`, walks ports like `canon serve`, refuses a `Host` other than loopback on its own port, and runs until interrupted. Each frame gets the project's token stylesheet injected, being this toolkit's tokens in its own checkout, else `.claude/design/base.css` plus anything under `.claude/design/project/`, else none with a notice. An open canvas reloads a frame whose file changes.
 
-The toolkit's own tokens arrive with the font faces they name embedded, so a frame renders in them on a machine that never installed them. An installed base owns its fonts and gets no faces added.
+The toolkit's own tokens arrive with the font faces they name embedded, so a frame renders in them on a machine that never installed them. An installed base gets the same treatment: each vendored face its sheets name is embedded, unless a project rule declares that family itself.
+
+A project's own `@font-face` rules under `.claude/design/project/` have each `url()` inlined as a `data:` URI. A rule whose file is missing, or whose path leads out of `.claude/design/project/` after links resolve, is dropped and the frame still renders. `canvas serve` warns once per dropped rule and names each under `tokens.dropped` in its `--json` record. The confinement check reads each `url()` after percent-decoding it. `canon design fonts add` writes those rules.
 
 Before it binds a port, `canvas serve` checks that `preact` and `@preact/signals` resolve from the package the CLI runs from, never from the served project. When either is missing it refuses with reason `missing-client-deps` and names `bun install` in the detail, rather than serving a shell that loads as a blank page.
 
@@ -25,28 +27,42 @@ The write routes the shell posts to also refuse a request carrying an `Origin` o
 
 `frame move <page> <name> --x <px> --y <px>` rewrites one frame's position in `layout.json` and keeps its size. An omitted axis stays where the frame is. It refuses a frame or page that does not exist and a layout that does not parse.
 
-The shell writes through the same writer when the operator drags a frame. Both take a lock file beside the layout, read it, merge their change, and replace it, so a drag released while a verb writes loses neither position. A writer that cannot get the lock within two seconds refuses with reason `busy`.
+`frame resize <page> <name> --width <px> --height <px>` rewrites one frame's whole box in one write, and `--x` and `--y` move it at the same time. An omitted flag keeps the frame's current value. It refuses a width or height that is not a positive number as `invalid-size`, a position that is not a number as `invalid-position`, and a missing frame, a missing page, or a layout that does not parse as `frame move` does.
+
+The shell writes through the same writer when the operator drags a frame or one of its corner handles. Both take a lock file beside the layout, read it, merge their change, and replace it, so a drag released while a verb writes loses neither position. A writer that cannot get the lock within two seconds refuses with reason `busy`.
 
 `canvas selection --json` emits `{ ok, selection }` with the page, frame, file, box, and path of the frame the operator selected, or `selection: null` when nothing is selected or the selected frame has since been removed. Read it when the operator says "this one".
 
 The operator can also pick one element inside a frame, by clicking it on the surface or in the frame's layers tree. The selection then carries `element`, recording the `index` in document order, `tag`, `classes`, and `text` excerpt as they were at the pick. An edit to the frame since can shift that index onto another element, so `stale` turns true once the file's content no longer matches what the pick was made against. Check it before acting on the index.
 
-A pick is refused as `address-mismatch` when the browser builds elements the file never states, such as a `tbody` a table leaves out or the document wrapper around a fragment. The shell sends its own element count beside the index, so a frame the two sides count differently is reported rather than recorded against the wrong element. A pick is refused as `stale-address` when the frame file changed between the frame being served and the pick arriving, since every served frame carries the hash of its file and the shell sends that hash back.
+A pick is refused as `address-mismatch` when the browser builds elements the file never states, such as a `tbody` a table leaves out or a `body` after a `head` the file states. A fragment is picked like a whole document, since the server writes the missing `html`, `head`, and `body` into the served frame and the shell leaves them out of its count. The shell sends its own element count beside the index, so a frame the two sides count differently is reported rather than recorded against the wrong element. A pick is refused as `stale-address` when the frame file changed between the frame being served and the pick arriving, since every served frame carries the hash of its file and the shell sends that hash back.
 
 ## Edit
 
-`canvas edit <page>/<frame> --element <index> --set <property>=<value>` sets one property of the element at that index, the same index `canvas selection` reports. The properties are `text`, `color`, `background-color`, `font-size`, `font-weight`, `width`, `height`, `padding`, `gap`, and `flex-direction`. A style property is written into the element's inline `style`, replacing that property and leaving the others as they were, and an empty value drops it.
+`canvas edit <page>/<frame> --element <index> --set <property>=<value>` sets one property of the element at that index, the same index `canvas selection` reports. The properties are `text`, `color`, `background-color`, `font-size`, `font-weight`, `width`, `height`, `padding`, `gap`, `display`, `flex-direction`, `justify-content`, `align-items`, `flex-wrap`, `opacity`, `border-radius`, `border-top-left-radius`, `border-top-right-radius`, `border-bottom-right-radius`, and `border-bottom-left-radius`. A style property is written into the element's inline `style`, replacing that property and leaving the others as they were, and an empty value drops it. Writing `border-radius` or `padding` also drops that shorthand's longhands from the same `style`, so no corner or side left over overrides the new value. Writing a longhand leaves its shorthand in place, since the longhand comes later and wins.
 
 `text` replaces the text of an element holding text alone and refuses one holding other elements as `not-text-only`. Every byte outside the element stays as it was. `--json` emits the page, frame, file, path, and the file's new `hash`.
 
-The operator edits the same set from the inspector, which posts to the same writer with the hash the frame was served with. An edit made against a version of the file Claude has since rewritten is refused as `stale-address` and the shell reloads the frame, so nothing lands on a shifted element. Both writers take the frame file's lock, and an edit that keeps the selected element where it was keeps the selection fresh.
+The operator edits the same set from the inspector, which posts to the same writer with the hash the frame was served with. Dragging a selected element's corner handle writes `width` and then `height` in pixels through that writer, the second edit carrying the hash the first answered. An edit made against a version of the file Claude has since rewritten is refused as `stale-address` and the shell reloads the frame, so nothing lands on a shifted element. Both writers take the frame file's lock, and an edit that keeps the selected element where it was keeps the selection fresh.
 
-A color picked from the project's tokens is written as `var(--<name>)`, and below full opacity as a `color-mix()` of that `var()` with `transparent` at the opacity percent, so it keeps following the theme. A browser older than 2023 drops a `color-mix()` value, which leaves the property unset there. A hex is written as six digits, or eight below full opacity.
+Size, padding, opacity, and radius show in the inspector for every element. The flex fields show only on a flex container, a grid container gets none, and the inspector sets `display` only to `flex`, so any other `display` change goes through the verb.
+
+A color picked from the project's tokens is written as `var(--<name>)`, and below full opacity as a `color-mix()` of that `var()` with `transparent` at the opacity percent, so it keeps following the theme. A browser older than 2023 drops a `color-mix()` value, which leaves the property unset there. A hex is written as six digits, or eight below full opacity. The inspector's full color picker writes a hex for any color it sets, so the field marks the value raw, and only its alpha keeps a token through the `color-mix()` form.
 
 Inline style beats a class, so an operator's edit masks a class change Claude makes later. Read a frame's inline styles before restyling it, and remove one the change should replace. The inspector marks a color or background set inline with the word `raw` when its value names no `var()` and is not `currentColor` or a CSS-wide keyword, since that value stays fixed when the theme changes. A property outside the set, or a value carrying `;`, `{`, `}`, `<`, `>`, or a line break, is refused as `invalid-edit`.
 
 The Theme tab in the shell lists what the token stylesheet defines, grouped as color, spacing, radius, font family, font size, and other. The page record at `/api/pages` carries the same list as `tokens.groups`.
 
+## Mark a frame being edited
+
+`canvas editing <page>/<frame>` marks a frame as being edited, so an open canvas can show who is working on it before the write lands. Run it before writing a frame and again with `--done` once the edits are written. A bare `canvas editing` lists the live marks, and `--json` emits `{ ok, editing }` after each of the three, with each mark carrying `page`, `frame`, `by`, `since`, and `until`.
+
+The label is `--by <name>` when given. Without it, the verb reads the caller's name off the session roster, and falls back to `a session` when the environment names no session or the roster holds none matching it.
+
+The marks live in `.canon/canvas/editing.json`, keyed by `<page>/<frame>`. Each write takes the record's lock and merges its one key, so two sessions marking two frames both keep their marks. A mark lapses five minutes after it was written, and marking the frame again renews it, so a session that never clears its mark misleads the operator for five minutes at most. A read leaves out a lapsed mark and a mark on a frame since removed, and a record that does not parse reads as holding none and is replaced by the next mark.
+
+A mark refuses `no-page` or `no-frame` for a target not on disk, and `invalid-name` for a target that is not `<page>/<frame>` or for `--done` with no target. `--done` on a frame holding no mark succeeds and writes nothing. The mark gates no write, so an inspector edit to a marked frame still lands, and the hash check still refuses one made against a file the session rewrote. The page record at `/api/pages` carries the live marks as `editing`, each with `page`, `frame`, `by`, and `until`.
+
 ## Capture
 
 `canvas capture <page>/<frame>` renders one frame as a PNG, and `canvas capture <page>` renders every frame on the page. Each goes through a server started for the call, so the injected tokens are in the image, and renders at the frame's own width from the layout, so a media query resolves there. It never captures the file on disk.

package/docs/agents/capture.md

@@ -5,11 +5,11 @@ description: Rendering HTML sources to PNG, what the command asserts about fonts
 
 # Capture
 
-`canon capture [source] --selector <sel>` renders HTML sources to PNG, which is how a generated documentation image is rebuilt from the markup it was generated out of. The source defaults to `assets/`, where a directory expands to every `.html` directly inside it, so adding a capture means dropping a file beside the first one and running the same command. That default is a generic starting point rather than a convention every target shares, and it stays because a missing folder still refuses loud, naming the argument, rather than failing silently. This repository no longer takes it: its own sources moved to `assets/captures/` and its images moved to `assets/evidence/`, so a run here names the source explicitly and sends the output where that run wants it, `--out assets/evidence` to rebuild the committed images and somewhere disposable to preview them.
+`canon capture [source] --selector <sel>` renders HTML sources to PNG, which is how a generated documentation image is rebuilt from the markup it was generated out of. The source defaults to `assets/`, where a directory expands to every `.html` directly inside it, so adding a capture means dropping a file beside the first one and running the same command. That default is a generic starting point rather than a convention every target shares, and it stays because a missing folder still refuses loud, naming the argument, rather than failing silently. This repository no longer takes it: its own sources moved to `assets/captures/` and its images moved to `assets/frames/`, so a run here names the source explicitly and sends the output where that run wants it, `--out assets/frames` to rebuild the committed images and somewhere disposable to preview them.
 
 ```bash
 canon capture --selector .window
-canon capture assets/captures/install.html --selector .window --out assets/evidence
+canon capture assets/captures/install.html --selector .window --out assets/frames
 canon capture assets/captures --selector .window --out .canon/review/captures
 canon capture https://example.com --selector .window --out preview.png
 ```
@@ -18,9 +18,9 @@ canon capture https://example.com --selector .window --out preview.png
 
 ## What this repository captures
 
-A capture set here spans two folders. `assets/captures/` holds three sources and the two templates they are written from, and `assets/evidence/` holds their images and the built-page capture a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the sources is edited by hand. `scripts/core/regen-hero.ts` writes each `.html` from the template beside it, filling one shared value map into all of them. A branch commits none of them for a moved count or token, since the refresh workflow regenerates them from `main` and opens one pull request, and `bun run check` runs the script with `--check`, which fills every template into a temp folder and fails when the regeneration cannot run.
+A capture set here spans two folders. `assets/captures/` holds three sources and the two templates they are written from, and `assets/frames/` holds their images and the built-page capture a document points at with the stamp answering for each, outside the `evidence` segment `canon pr evidence` compares. The folder name is this repository's own layout, and a target picks its own `--out`. One run over the source folder rebuilds every image, and it takes `--out assets/frames` to put each PNG where its document points rather than beside the markup it rendered. None of the sources is edited by hand. `scripts/core/regen-hero.ts` writes each `.html` from the template beside it, filling one shared value map into all of them. A branch commits none of them for a moved count or token, since the refresh workflow regenerates them from `main` and opens one pull request, and `bun run check` runs the script with `--check`, which fills every template into a temp folder and fails when the regeneration cannot run.
 
-The `hero` template takes catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` is the exception, since it holds terminal text from a real run in its template rather than derived from a live catalog at build time. `assets/evidence/arrival.png` is the one image with no source here: it is the built page's `.fold` element captured in dark mode against a local `web/` preview, since `canon capture` takes no color scheme and the page follows the browser's default of light, so it is retaken by hand when the page's first screen changes.
+The `hero` template takes catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` is the exception, since it holds terminal text from a real run in its template rather than derived from a live catalog at build time. `assets/frames/arrival.png` is the one image with no source here: it is the built page's `.fold` element captured in dark mode against a local `web/` preview, since `canon capture` takes no color scheme and the page follows the browser's default of light, so it is retaken by hand when the page's first screen changes.
 
 The README shows each still in two themes through `<picture>`, so a frame is a pair named `<name>` and `<name>-light`. `install` takes the light half from its template, which `regen-hero.ts` fills a second time with the plain color roles pointed at the light ones, and each half is its own capture set with its own stamp. `arrival-light.png` is the same `.fold` capture of the same address taken without forcing dark, so it is retaken by hand alongside `arrival.png`, and nothing catches one drifting from the other.
 
@@ -28,7 +28,7 @@ A stamp for a URL source digests the address string rather than the page it serv
 
 `assets/captures/` is read flat and never descends, by the regeneration script and by this command alike. A source nested a further folder down is skipped by both with nothing reported, so a new frame is a template dropped directly in rather than a folder of its own. The split is what retired the name prefix the flat layout used to need: a frame is named for itself now, since `assets/captures/` no longer mixes markup in with the images.
 
-A branch is not asked whether the HTML is current. The PNG is a chromium render whose bytes move with the browser version, so the refresh workflow rebuilds it with `canon capture assets/captures --selector .window --out assets/evidence` only when the regenerated HTML changed.
+A branch is not asked whether the HTML is current. The PNG is a chromium render whose bytes move with the browser version, so the refresh workflow rebuilds it with `canon capture assets/captures --selector .window --out assets/frames` only when the regenerated HTML changed.
 
 Every render writes a stamp beside its PNG, `hero.png` next to `hero.stamp`, holding the source filename, a `source-sha256` over the markup bytes it read, and an `image-sha256` over the image bytes it wrote. Both digests are what `bun run check` compares, so a markup edit committed without a capture and a PNG swapped under unchanged markup each fail. The stamp is tracked and commits alongside the pair. A capture that cannot write it reports that source as failed and exits 1, so an image whose stamp never landed is reported rather than passed over.
 

package/docs/agents/commands.md

@@ -91,12 +91,12 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 - `wiki`, in `scripting.md`: `init`
 - `indexes`, in `indexes.md`: `regen`, `list`
 - `docs`, in `docs.md`: `list`, `<topic>`
-- `design`, in `install-and-sync.md` for `install` and `sync`, and described below for the rest: `render`, `regen`, `css`, `install`, `sync`
+- `design`, in `install-and-sync.md` for `install`, `sync`, and `fonts`, and below for the rest: `render`, `regen`, `css`, `install`, `sync`, `fonts`
 - `slides`, described below: `render`, `list`
 - `demo`, in `demo.md`: `compile`, `run`, `frames`
 - `inventory`, described above: `run`
 - `teach`, in `teach.md`: `list`, `open`, `resource`, `glossary`, `lesson`, `stylesheet`, `nav`, `render`
-- `canvas`, described below: `serve`, `list`, `page add`, `page rename`, `frame add`, `frame move`, `selection`, `edit`, `capture`
+- `canvas`, described below: `serve`, `list`, `page add`, `page rename`, `frame add`, `frame move`, `frame resize`, `selection`, `edit`, `editing`, `capture`
 - `sandbox`, in `sandbox.md`: `reset`, `clean`, `check`, `coverage`
 - `tasks`, in `tasks.md`: `next-label`, `archive`, `decline`, `plan-citations`, `plan-answers`, `plan-branch`, `plan-reach`, `plan-link`, `pull-request`, `outcome`, `list`, `validate`
 - `intake`, in `intake.md`: `list`, `answer`

package/docs/agents/index.md

@@ -10,7 +10,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 
 - [Architecture record](architecture-record.md): The findings canon context audit reads off the architecture record, being the entry cap, revisit sentence, length, decision word, and risk bullet gates the record states for itself, the claim coverage report, and the word counts, plus the requirements record's word cap
 - [Audits](audits.md): Running every health check as one set, what the single verdict means, the exit code each outcome takes, the retained baseline and the delta it reports, and which corpora are kept out of the record
-- [Canvas](canvas.md): The canvas server, its content format, and the verbs that list, arrange, select, edit, and capture frames
+- [Canvas](canvas.md): The canvas server, its content format, and the verbs that list, arrange, select, edit, mark, and capture frames
 - [Capture](capture.md): Rendering HTML sources to PNG, what the command asserts about fonts, and why the selector has no default
 - [Census](census.md): Tracked-plus-untracked file count, a breakdown by extension, and a line total that skips whatever reads as binary
 - [Command catalog](commands.md): Every top-level command with its purpose, each domain's subcommands and the page describing them, the browser commands, and the version skew report
@@ -37,8 +37,8 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [The pull request evidence comparison](pr-evidence.md): What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, what the --check read reports as owed, and why the comparison anchors at the merge base rather than the previous push
 - [The pull request frame store](pr-frames.md): How canon pr frames pushes a UI review frame to a never-merged branch through the GitHub API and returns a branch-path link, which ref it writes, the pass segment that keeps an earlier image fixed, the refusal reasons it names, and how --drop and --prune rewrite the branch so a dropped frame leaves history
-- [The pull request local preview](pr-local.md): How canon pr local finds the server a worktree is running, why a server in another worktree is never reported, the refusal reasons it names, and how a close workflow removes the link with --remove
-- [The pull request preview deploy](pr-preview.md): How canon pr preview finds a fenced Cloudflare Pages deploy, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
+- [The pull request local preview](pr-local.md): How canon pr local finds the server a worktree is running, why a server in another worktree is never reported, the refusal reasons it names, and how a close workflow drops the address line with --remove
+- [The pull request preview deploy](pr-preview.md): How canon pr preview finds a fenced Cloudflare Pages deploy, refuses a branch its push filter does not serve, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
 - [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
 - [Records push](records-push.md): Backing the record folders to a private remote and restoring them, which folders the payload carries, the one-time setup, the refusal reasons, and the hook that runs the push
 - [Records stale](records-stale.md): Reading the memory pen as a review queue, what makes an entry due, how a cited path is read and resolved, the order entries come back in, counting the releases since the requirements and architecture records were last reviewed, and the exit codes and refusals

package/docs/agents/install-and-sync.md

@@ -57,6 +57,13 @@ touches, because that subfolder is project-authored by location the way
 `.claude/rules/project/` is. An override named exactly like the shipped file is
 still the project's.
 
+A project's faces sit in that subfolder too, under `fonts/` with plain
+`@font-face` rules in `fonts.css`. `canon design fonts add <file> --family <name>`
+copies a `woff2`, `woff`, `ttf`, or `otf` face in and appends its rule
+(`--weight`, `--style`, `--json`), refusing bytes that disagree with the
+extension as `invalid-font`. `fonts list --json` emits one row per rule, with a
+`problem` where the file is missing or lies outside the subfolder.
+
 The override ships absent rather than empty. An empty file is one the project
 did not ask for and did not write, the reconciliation already handles a missing
 side, and an empty override invites a target to fill it before it has an

package/docs/agents/key-changes.md

@@ -113,4 +113,4 @@ One class stays open and is named rather than closed. A bullet can cite where so
 
 ## Where it runs
 
-`review-pr` Step 3 calls it and files an `unmet` path as a `should-fix` finding under the `**PR body**` block the stale ticked box already takes, since what both corrupt is the merge record rather than a file in the diff. A body is edited between pushes, so a finding names the head the comparison ran at. `unnamed` is read there and raised off no count, since the step's own history is a question sent over bullets that already answered it. `unresolved` and `incidental` are reported nowhere.
+`review-pr` Step 3 calls it through its `references/key-changes.md` and files an `unmet` path as a `should-fix` finding under the `**PR body**` block the stale ticked box already takes, since what both corrupt is the merge record rather than a file in the diff. A body is edited between pushes, so a finding names the head the comparison ran at. `unnamed` is read there and raised off no count, since the step's own history is a question sent over bullets that already answered it. `unresolved` and `incidental` are reported nowhere.

package/docs/agents/pr-evidence.md

@@ -70,8 +70,8 @@ shows a reviewer, each field present only when that comment holds it:
 
 | Field       | What it carries                                                   |
 | ----------- | ----------------------------------------------------------------- |
-| `preview`   | The hosted `**Preview:**` address the comment opens with.         |
-| `local`     | The `**Local preview:**` address under it.                        |
+| `preview`   | The hosted `**Preview:**` address on the comment's address line.  |
+| `local`     | The `**Local preview:**` address beside it.                       |
 | `checklist` | The checklist between its delimiters, with any ticked boxes kept. |
 
 These come from the comment already posted, never from the flags the call
@@ -142,11 +142,34 @@ details wrapper lands once, not twice.
 
 ## The preview line
 
-`--preview <url>` opens the body with the branch's preview address, and a run
+Every body opens with `## Evidence`. Under it sits one address line carrying
+whichever previews apply, joined by a middle dot:
+
+```plaintext
+## Evidence
+
+**Preview:** <url> · **Local preview:** <url>
+
+**Base:** `<base>` · **Head:** `<head>`
+```
+
+The Base and Head line follows only when the comment carries screenshots.
+
+`--preview <url>` puts the branch's hosted address on that line, and a run
 without it carries forward the address the marked comment already holds. With
-no evidence in the diff and an address in hand, the body is the address and the
-marker alone, reported as `ok`. `canon docs pr-preview` covers where the
-address comes from.
+no evidence in the diff and an address in hand, the body is the heading, the
+address line, and the marker alone, reported as `ok`. `canon docs pr-preview`
+covers where the address comes from.
+
+A carried hosted address is dropped when a deploy workflow resolves and its
+push path filter matches no path the pull request changed, since the site it
+links shows none of the change. An explicit `--preview` is always kept.
+
+The carry-forward reads every line above the commit line, the checklist, and
+the comparison for each prefix, wherever it sits. A comment posted before the
+heading opened the body, with each address on a line of its own at the top,
+reads the same way, so an open pull request keeps its links on its first
+re-render.
 
 ## The checklist line
 
@@ -173,11 +196,10 @@ gone.
 
 ## The local preview line
 
-`--local <url>` adds `**Local preview:** <url>` to the opening block: under the
-hosted `**Preview:**` line when there is one, and as the first line when there
-is not. The hosted line always keeps the first position, since that is the one
-line the carry-forward reads for it. A run without the option carries forward
-the local address the marked comment already holds, the same as the other two.
+`--local <url>` adds `**Local preview:** <url>` to the address line, after the
+hosted segment when there is one and alone when there is not. A run without the
+option carries forward the local address the marked comment already holds, the
+same as the other two.
 
 The option does not turn `no-evidence` into `ok` on its own. A branch with a
 dev server running and no rendered change would otherwise get a comment holding
@@ -206,10 +228,11 @@ canon pr evidence 1341 --check --json
 - `evidence` is owed when the changed set carries an evidence image and no
   comment carries the marker.
 - `preview` is owed when the pull request has a marked comment or an evidence
-  change, a deploy workflow resolves in the checkout the verb runs from, and
-  the marked comment's first line is no `**Preview:**` line. A
-  `**Local preview:**` line does not satisfy it. A project deploying nothing is
-  never owed a preview.
+  change, a deploy workflow resolves in the checkout the verb runs from, its
+  push path filter matches a path the pull request changed, and the marked
+  comment carries no `**Preview:**` address. A `**Local preview:**` address
+  does not satisfy it. A project deploying nothing is never owed a preview,
+  and neither is a branch its deploy does not build from.
 
 The record carries `owed`, `commentId` when a marked comment exists, and the
 same `preview`, `local`, and `checklist` fields the other reasons carry, so a

package/docs/agents/pr-local.md

@@ -1,6 +1,6 @@
 ---
 title: The pull request local preview
-description: How canon pr local finds the server a worktree is running, why a server in another worktree is never reported, the refusal reasons it names, and how a close workflow removes the link with --remove
+description: How canon pr local finds the server a worktree is running, why a server in another worktree is never reported, the refusal reasons it names, and how a close workflow drops the address line with --remove
 ---
 
 # The pull request local preview
@@ -10,7 +10,7 @@ worktree is running. `git-pr` calls it ahead of the evidence comparison and
 passes the address through `canon pr evidence --local`, so a reviewer on the
 same machine gets the running branch to click into beside the screenshots and
 the checklist. A workflow on the pull request's `closed` event calls it again
-with `--remove`, which replaces the line with a note.
+with `--remove`, which drops the address line and leaves nothing in its place.
 
 ```bash
 canon pr local --json
@@ -62,9 +62,9 @@ to it on this pull request would show a reviewer the wrong code.
 | `ok`                 | A server answered. `url` carries the address and `port` the port.     |
 | `no-server`          | Nothing inside this worktree served an HTML page.                     |
 | `no-listener-reader` | Neither `lsof` nor `/proc` is available, so no socket could be read.  |
-| `removed`            | `--remove` replaced the local line on the evidence comment.           |
+| `removed`            | `--remove` dropped the address line from the evidence comment.        |
 | `no-comment`         | `--remove` found no comment carrying the evidence marker.             |
-| `no-line`            | `--remove` found the comment but no local line on it.                 |
+| `no-line`            | `--remove` found the comment but no address line on it.               |
 | `gh-missing`         | `--remove` needs `gh` and it is not on the path.                      |
 | `gh-failed`          | `--remove` could not read the comments or could not edit the comment. |
 
@@ -84,12 +84,19 @@ on:
     types: [closed]
 ```
 
-It reads the comment carrying the `pr-evidence` marker, replaces the
-`**Local preview:**` line with the `--note` text, and edits the comment itself
-through `gh api`. The verb writes here rather than handing a body back, because
-its caller is a workflow with no session to post one. Every other byte of the
-comment stays as it was, which keeps the marker, the checklist delimiters, and
-any ticked box intact. A second run finds no line and reports `no-line`.
+It reads the comment carrying the `pr-evidence` marker, drops the address line
+under `## Evidence`, the hosted `**Preview:**` segment and the
+`**Local preview:**` segment together, and edits the comment itself through
+`gh api`. The hosted link goes too because the deploy workflow deletes the
+branch's preview deployments on the same close. No note replaces the line, and
+the blank line it sat on goes with it so no gap doubles under the heading. A
+comment in the older layout, with each address on its own line at the top,
+loses both lines the same way.
+
+The verb writes here rather than handing a body back, because its caller is a
+workflow with no session to post one. Every other byte of the comment stays as
+it was, which keeps the marker, the checklist delimiters, and any ticked box
+intact. A second run finds no line and reports `no-line`.
 
 A fork pull request gets a read-only token, so the workflow skips the edit with
 a notice rather than failing the close.
@@ -100,6 +107,5 @@ The link can still go dead while the pull request is open, such as when the
 session holding the server retires. Only the close is covered, and a re-render
 after a push carries the line forward whether the server still answers or not.
 
-The hosted `**Preview:**` line from `canon pr preview` stays on the comment
-after close, even though its deployments are deleted then. `canon docs
-pr-preview` covers that path.
+`canon docs pr-preview` covers how the hosted address is minted and when it is
+refused.