@erclx/canon 5.25.0 → 5.27.0

package/docs/agents/commands.md

@@ -26,7 +26,7 @@ One row per top-level command, in the order `canon --help` prints them. A domain
 | `canon indexes <verb>`      | Regenerate `index.md` files from sibling frontmatter, or flatten them                      |
 | `canon docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                                   |
 | `canon design <verb>`       | Render or regenerate `canon/DESIGN.md` tokens, emit their CSS, install the base stylesheet |
-| `canon slides <verb>`       | Render a `.claude/SLIDES.md` deck, or list its layouts                                     |
+| `canon slides <verb>`       | Render a deck folder of HTML slides, or list the decks                                     |
 | `canon capture [source]`    | Render HTML or a URL to PNG and prove each declared font resolved                          |
 | `canon serve [dir]`         | Serve a directory on loopback and print the link that opens it                             |
 | `canon demo <verb>`         | Compile and record a running app                                                           |
@@ -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`
@@ -128,8 +128,8 @@ Subcommands no other page describes:
 - `claude plugin-update` matches the installed marketplace plugin against `claude/.claude-plugin/plugin.json`'s own name and runs `claude plugin update` on it, reading the version back off `claude plugin list --json`, since the update call reports none of its own (`--json`).
 - `claude skills rank` scores either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`).
 - `design regen` rewrites this repository's `canon/DESIGN.md` from `src/design/tokens.ts` and `src/design/base.css` from `src/design/neutral.ts`. `design css` emits the tokens and components as CSS on stdout, with `--no-components` for properties alone, and `design render` declares each vendored face the typography table names under `--embed-fonts`.
-- `slides render` renders a `.claude/SLIDES.md` source into a PowerPoint deck and reports any unrecognized layout name on stderr, and `slides list --json` emits the layout catalog.
-- `slides render --source <folder>` lays out each `.html` file in filename order in Chromium at 1280 by 720 and rebuilds it as editable shapes. Each element drawn as a picture prints one `✗` line on stderr naming the slide, the selector, and the properties that forced it. A link left out, being a `#slide-N` past the deck's end or any target that is neither that nor an absolute URL, prints one too, and the exit stays 0.
+- `slides list --json` emits one row per deck under `.canon/slides/`, carrying `name`, `title`, `slides`, and `path`.
+- `slides render [deck]` takes a deck name or a folder, defaulting to the only deck, and lays out each `.html` file in filename order in Chromium at 1280 by 720 and rebuilds it as editable shapes. Each element drawn as a picture prints one `✗` line on stderr naming the slide, the selector, and the properties that forced it. A link left out, being a `#slide-N` past the deck's end or any target that is neither that nor an absolute URL, prints one too, and the exit stays 0.
 - A deck folder's `deck.json` and the faces it embeds, its per-slide `<body>` attributes, transitions and entrances, speaker notes, and charts are described in `slides.md`.
 - `canvas`, with its verbs, content format, and write routes, is described in `canvas.md`.
 - `labels scan` fails a pull request or a posted review whose title, body, or review comment carries a phase label, a label a code span quotes, a gitignored record path, a session link, a title word no dictionary holds, or a title breaking `standards/pr.md`'s format, casing, or length rule (`--event`, `--body-file`, `--json`).

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,11 +37,11 @@ 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, and the exit codes and refusals
+- [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
 - [Records validate](records-validate.md): Validating the session records and the standards corpus, the per-kind checks, which root each kind defaults to, the exit codes, and the refusal reasons
 - [Records](records.md): The two roots a record folder resolves at, migrating a record a frontmatter change orphaned, claiming the ordinal intake and groundwork share, reading each folder's size and growth, pruning stale scratch, and where validation, the memory review queue, and the private-remote backup are described
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file and every path-scoped rule share with the seed, the skill bodies, and each other, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
@@ -54,7 +54,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, what each session surface can see, and where moving a session to another machine is described
 - [Skill audit](skills-audit.md): Measuring both skill corpora against the skill standards, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [Citation reach](skills-reach.md): Reporting the skill bodies that cite a path no target project receives, which corpus the verb reads, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
-- [Slides](slides.md): What a folder of HTML slides declares for the whole deck in deck.json, the faces it embeds, what each slide declares on its own body, transitions and entrances, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
+- [Slides](slides.md): Where a deck folder lives and what it holds, what it declares for the whole deck in deck.json, the faces it embeds, what each slide declares on its own body, transitions and entrances, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
 - [Standard success criteria](standards-audit.md): Reading the corpus against the success-criterion gate, the two headings it accepts, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
 - [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
 - [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the family stem behind a templated citation, the exemption marker, the blind spots it cannot reach, and why it reports rather than gates

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.

package/docs/agents/pr-preview.md

@@ -1,6 +1,6 @@
 ---
 title: The pull request preview deploy
-description: 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
+description: 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
 ---
 
 # The pull request preview deploy
@@ -8,8 +8,8 @@ description: How canon pr preview finds a fenced Cloudflare Pages deploy, dispat
 `canon pr preview` publishes a pull request's branch to a Cloudflare Pages
 preview and reports the address. `git-pr` calls it after the evidence
 comparison, then re-renders that comment through `canon pr evidence --preview`
-so the link opens it. A reviewer gets a page to click into before merging
-rather than screenshots and a checklist alone.
+so the link sits on the address line under its heading. A reviewer gets a page
+to click into before merging rather than screenshots and a checklist alone.
 
 ```bash
 canon pr preview --json
@@ -31,6 +31,24 @@ the first file, in path order, that meets four tests:
 The workflow is read before the pull request, so a project with no fenced
 deploy is refused without a network call.
 
+## Which branches it serves
+
+A dispatch runs the workflow whatever its `on.push.paths` filter says, so a
+branch that touched nothing the site builds from would get a preview showing
+none of its change. The verb reads the pull request's changed paths and matches
+them against the picked workflow's own `on.push.paths` or `on.push.paths-ignore`
+list, applying `!` patterns in order the way GitHub does. When nothing matches,
+it refuses as `unserved` and dispatches nothing. `--check` answers `unserved`
+the same way.
+
+The push filter is the one statement of what the site builds from, since it
+already decides when production deploys. A workflow with neither list, with no
+push trigger, or that does not parse as YAML serves every change, so a project
+whose every change ships keeps minting for every branch.
+
+A removed path counts, the same as GitHub's own push filter counts it, so a
+branch whose only site change deletes a file still gets a preview.
+
 ## Why an unfenced deploy is refused
 
 Cloudflare Pages publishes a deploy that names no branch to production. A
@@ -62,19 +80,21 @@ keeps the match independent of the local clock.
 
 `reason` on the record is what a caller branches on, not the exit code:
 
-| Reason          | What it means                                                              |
-| --------------- | -------------------------------------------------------------------------- |
-| `ok`            | The preview was published. `url` carries the address and `runId` the run.  |
-| `no-deploy`     | No dispatchable workflow runs `pages deploy`.                              |
-| `unfenced`      | The deploy passes no `--branch`, so nothing was dispatched.                |
-| `no-alias`      | The workflow prints no alias line, or the finished run's log carried none. |
-| `run-failed`    | The deploy run finished without succeeding. `runId` names it.              |
-| `timeout`       | The run did not finish inside `--timeout` minutes, 15 by default.          |
-| `bad-timeout`   | `--timeout` was not a positive number.                                     |
-| `gh-missing`    | `gh` is not on the path.                                                   |
-| `gh-failed`     | `gh` could not read the pull request, or list or dispatch the workflow.    |
-| `no-branch`     | The pull request carries no head branch name.                              |
-| `check-timeout` | `--check` was combined with `--timeout`.                                   |
+| Reason               | What it means                                                              |
+| -------------------- | -------------------------------------------------------------------------- |
+| `ok`                 | The preview was published. `url` carries the address and `runId` the run.  |
+| `no-deploy`          | No dispatchable workflow runs `pages deploy`.                              |
+| `unserved`           | The push path filter matches no changed path, so nothing was dispatched.   |
+| `unreadable-changes` | The pull request's changed paths could not be read.                        |
+| `unfenced`           | The deploy passes no `--branch`, so nothing was dispatched.                |
+| `no-alias`           | The workflow prints no alias line, or the finished run's log carried none. |
+| `run-failed`         | The deploy run finished without succeeding. `runId` names it.              |
+| `timeout`            | The run did not finish inside `--timeout` minutes, 15 by default.          |
+| `bad-timeout`        | `--timeout` was not a positive number.                                     |
+| `gh-missing`         | `gh` is not on the path.                                                   |
+| `gh-failed`          | `gh` could not read the pull request, or list or dispatch the workflow.    |
+| `no-branch`          | The pull request carries no head branch name.                              |
+| `check-timeout`      | `--check` was combined with `--timeout`.                                   |
 
 The exit is 0 on `ok` and 1 on every refusal. A `timeout` leaves the run
 going, so the preview may still land after the verb has given up on it.
@@ -107,10 +127,11 @@ reason but `fresh`.
 
 ## How the address reaches the pull request
 
-`canon pr evidence --preview <url>` puts `**Preview:** <url>` on the first line
-of the evidence body. With no evidence image in the diff, the body is that line
-and the trailing marker alone, so a pull request whose screenshots did not
-change still gets one comment a later call can find and edit.
+`canon pr evidence --preview <url>` puts `**Preview:** <url>` on the address
+line under the evidence body's `## Evidence` heading. With no evidence image in
+the diff, the body is the heading, that line, and the trailing marker alone, so
+a pull request whose screenshots did not change still gets one comment a later
+call can find and edit.
 
 A later `canon pr evidence` run without `--preview` reads the address off the
 marked comment and carries it into the new body. `git-followup` re-renders the
@@ -123,7 +144,9 @@ way, which is what keeps that push from wiping boxes a reviewer already ticked.
 A `pull_request` trigger on `closed` in the same workflow runs a cleanup job
 that deletes every preview deployment Cloudflare holds for the branch. The
 deploy job carries `if: github.event_name != 'pull_request'`, so a closed pull
-request never deploys.
+request never deploys. The same close runs `canon pr local --remove`, which
+drops the address line from the evidence comment, hosted link included, so the
+comment never links a deployment that no longer exists.
 
 ## What this does not cover
 

package/docs/agents/records-stale.md

@@ -1,25 +1,26 @@
 ---
 title: Records stale
-description: 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, and the exit codes and refusals
+description: 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
 ---
 
 # Records stale
 
-`canon records stale memory` reports each memory entry's review state and every backticked path it cites that the project no longer holds. It answers what a review of the pen should read next, so a skill takes the queue from the verb rather than re-deriving it by grep.
+`canon records stale memory` reports each memory entry's review state and every backticked path it cites that the project no longer holds. It answers what a review of the pen should read next, so a skill takes the queue from the verb rather than re-deriving it by grep. `canon records stale canonical` reports when the requirements and architecture records were last reviewed and how many releases have shipped since.
 
 ```bash
 canon records stale memory
 canon records stale memory --json
 canon records stale memory --days 60 --json
+canon records stale canonical --json
 ```
 
-| Option          | Behavior                                                      |
-| --------------- | ------------------------------------------------------------- |
-| `--json`        | Add a machine-readable record on stdout                       |
-| `--days <n>`    | Days after a review before an entry is due again (default 30) |
-| `--root <path>` | Project root, defaulting to the main worktree                 |
+| Option          | Behavior                                                                                            |
+| --------------- | --------------------------------------------------------------------------------------------------- |
+| `--json`        | Add a machine-readable record on stdout                                                             |
+| `--days <n>`    | Days after a review before a memory entry is due again (default 30)                                 |
+| `--root <path>` | Project root, defaulting to the main worktree for `memory` and the current worktree for `canonical` |
 
-`memory` is the only kind it reads, since a memory entry is the one record carrying a review date. Any other argument refuses as `unknown-kind`.
+`memory` and `canonical` are the two kinds it reads, since each is a record carrying a review date. Any other argument refuses as `unknown-kind`.
 
 It reports and never writes. It moves, archives, and rewrites no entry, matching `validate` and `size`.
 
@@ -53,10 +54,22 @@ canon records stale memory --json | jq -r '[.entries[] | select(.due)][0:20][] |
 
 The record carries `total`, `due`, `days`, the `folder` read relative to the root, and one `entries` row per entry with `name`, `category`, `reviewed`, `due`, and `unresolved`.
 
+## Canonical records
+
+`canonical` reads `REQUIREMENTS.md` and `ARCHITECTURE.md` at whichever surface root carries each, `canon/` ahead of `.claude/`, and omits one the project does not hold. Both are tracked, so `--root` defaults to the worktree the caller stands in rather than the main one, and a stamp a branch just wrote reads back from that branch.
+
+Each doc's review point is an optional `reviewed: YYYY-MM-DD` frontmatter field, set by whoever finishes a review, per `canon standards requirements` and `canon standards architecture`. It is a date rather than a commit, since a commit written on a feature branch never reaches a trunk that squash-merges. The field is read the way the memory field is, so a value that is not a calendar date comes back as `invalidReviewed`.
+
+The count is every release tag merged into `HEAD` whose creator date falls after the reviewed day. A release tag ends in a dotted version, bare as `v5.25.0` or behind a component prefix as `canon-v2.1.0`, so an eval, deploy, or snapshot tag on the trunk never inflates it. A lightweight tag's creator date is its commit's date and an annotated tag's is the tagging date, so a project mixing both counts by two clocks.
+
+The record carries `tagged`, false when `HEAD` has merged no release tag or the repository has no commit yet, and one `docs` row per doc with `path`, `reviewed`, `releasesSince`, and `latestRelease`. `releasesSince` is null on a doc never reviewed and `0` on one reviewed after every tag. With no tags it is also `0`, which is why `tagged` travels beside it.
+
+It gates nothing, and no hook, gate stage, or workflow runs it. `canon:document-health` reads it when asked to review the two records.
+
 ## Exit codes and refusals
 
 Exit codes: `0` the reading completed, whatever it found, and `1` refused. A due entry is a queue position rather than a failure, so nothing here gates.
 
-A `reason` field carries which gate fired: `no-folder` when the project holds no memory folder at either record root, `unknown-kind` for any kind but `memory`, and `bad-days` when `--days` is not a positive whole number. An empty pen is not a refusal. It reports an empty list and exits `0`.
+A `reason` field carries which gate fired: `no-folder` when the project holds no memory folder at either record root, `unknown-kind` for any kind but `memory` or `canonical`, `bad-days` when `--days` is not a positive whole number or is passed to `canonical`, and `unreadable-tags` when `canonical` cannot read the tags. An empty pen is not a refusal. It reports an empty list and exits `0`.
 
 The pen is shared scratch at the main worktree root, so `--root` defaults there, the same default `validate memory` takes. A pen at the legacy `.claude/memory/` root resolves the way every record verb resolves it, per `records.md`. <!-- canon-keep-record-root -->

package/docs/agents/records.md

@@ -118,7 +118,7 @@ Exit codes: `0` nothing to prune, or `--write` deleted every candidate. `1` refu
 
 ## Stale
 
-`canon records stale memory` reports which memory entries are due for review and which cite a path the tree no longer holds, ordered so a review takes the first N as a batch. What makes an entry due, how a cited path resolves, and the refusals are in `records-stale.md`.
+`canon records stale memory` reports which memory entries are due for review and which cite a path the tree no longer holds, ordered so a review takes the first N as a batch. `canon records stale canonical` reports when the requirements and architecture records were last reviewed and how many releases have shipped since. What makes an entry due, how a cited path resolves, how the release count is taken, and the refusals are in `records-stale.md`.
 
 ## Push and pull
 

package/docs/agents/sandbox.md

@@ -9,7 +9,7 @@ description: Scenario routing, the expectation scoring surface, and the coverage
 
 ## Scenarios
 
-Scenarios live under `sandbox/`, one folder per category. `sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so both pickers filter it out. That tree sits outside `files` in `package.json`, so an installed `canon` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
+Scenarios live under `sandbox/`, one folder per category. `sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so the picker and the coverage report both filter it out. That tree sits outside `files` in `package.json`, so an installed `canon` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
 
 ```bash
 SANDBOX_SCENARIO=sync canon sandbox infra:tooling
@@ -39,15 +39,39 @@ The verdict `state` is `pass`, `fail`, or `unchecked`. An arm with no `expect.to
 
 Omitting `--writes`, `--escapes`, or `--envelope` does not silently drop the assertion kinds that need them. Write scope, escape scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. Supplying `--escapes` without `--escapes-watched` reports the same way: a zero-escape result with no root confirmed watched is unmeasured rather than a pass. A verdict never reports `pass` with zero assertions.
 
-An arm declaring `escape_scope` asserts a bound on `run.sh`'s own escape watch rather than on the sandbox tree. `write_scope` skips when the run wrote nothing, since a required output missing is itself a finding, but `escape_scope` passes on zero escapes outright, since a clean run producing none is the expected outcome for a destination nothing requires a skill to touch, provided `--escapes-watched` confirms a root held something to watch. Declaring `escape_scope = []` asserts that a correct run reaches none of the watched destinations at all. `canon/context/sandbox/isolation.md` names what the watch reaches and what it cannot.
+An arm declaring `escape_scope` asserts a bound on the headless runner's own escape watch rather than on the sandbox tree. `write_scope` skips when the run wrote nothing, since a required output missing is itself a finding, but `escape_scope` passes on zero escapes outright, since a clean run producing none is the expected outcome for a destination nothing requires a skill to touch, provided `--escapes-watched` confirms a root held something to watch. Declaring `escape_scope = []` asserts that a correct run reaches none of the watched destinations at all. `canon/context/sandbox/isolation.md` names what the watch reaches and what it cannot.
 
 An envelope that parses but carries no `result` field skips the reply assertion the same way an absent file does. An envelope carrying an empty `result` fails it, since a run that returned no text is a finding rather than a gap in the input.
 
 Exit 0 means `pass` or `unchecked`. Exit 1 means `fail`, or a caller error: a malformed target, or a sandbox that was never provisioned. A missing sandbox reports as an error rather than a failed verdict, because failing every path assertion would read as a skill that did nothing. `--strict` moves `unchecked` to exit 1 for a caller that has finished arming its scenarios.
 
+## Headless runs
+
+`canon sandbox run` provisions a scenario, drives one `claude -p` session over it, and scores the result with `canon sandbox check`. `sandbox/run.sh` is a wrapper that passes its arguments to the verb, so either spelling runs the same code.
+
+```bash
+canon sandbox run <category>:<command> "<prompt>" [arm]
+canon sandbox run claude:plan-feature "/canon:plan-feature add a widget" small
+```
+
+Every run bills a real session through the `claude` binary on `PATH`. The session runs with `--plugin-dir` pointed at this checkout's `claude/`, so it loads the branch's skills rather than an installed copy, and provisioning injects no skill into the tree for the same reason. Four variables override the flags it hands to `claude -p`:
+
+| Variable                           | Default                          |
+| ---------------------------------- | -------------------------------- |
+| `CANON_SKILL_TEST_MODEL`           | `sonnet`                         |
+| `CANON_SKILL_TEST_TOOLS`           | `Bash,Read,Glob,Grep,Edit,Write` |
+| `CANON_SKILL_TEST_MAX_TURNS`       | `30`                             |
+| `CANON_SKILL_TEST_PERMISSION_MODE` | `bypassPermissions`              |
+
+The max-turns value is the only budget a run has. An arm's `max_turns` is asserted after the run and cannot raise it.
+
+Stdout carries one JSON record: the session's envelope with `verdict`, `escapes`, and `sessions` merged in, described under the skills census below. Stderr carries the framed timeline, the provisioning output, the session's own stderr, the verdict report, and a warning for each escape, new session record, or reaped process. An envelope that does not parse still prints its verdict, under `is_error: true`.
+
+Exit codes follow whichever step stopped the run. Provisioning's code ends a run before the session starts, and a session that exits non-zero ends it with that code after writing a dead-run record, `{is_error, exit_code, raw_output}`, to the same runs folder the merged record uses. Otherwise the verdict's code stands, except that an envelope that does not parse forces 1. An interrupt reaps the session's process group before the runner exits.
+
 ## Provisioning equivalence
 
-`canon sandbox equivalence` proves a change moved nothing in what scenarios provision. It provisions every arm of the named targets on a base ref and on the working checkout, builds a manifest of each tree, and names what differs. It runs offline and never calls `sandbox/run.sh` or a `claude` binary, so no arm it runs bills a model.
+`canon sandbox equivalence` proves a change moved nothing in what scenarios provision. It provisions every arm of the named targets on a base ref and on the working checkout, builds a manifest of each tree, and names what differs. It runs offline and never calls `canon sandbox run` or a `claude` binary, so no arm it runs bills a model.
 
 ```bash
 canon sandbox equivalence claude --base origin/main --json
@@ -95,8 +119,8 @@ A skill pairs to a scenario by filename, `<category>-<command>` first and bare `
 
 `exempt` means no arm should be written and holds only with a reason, declared in `sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
 
-`sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.canon/tmp/runs/sandbox/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
+`canon sandbox run` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.canon/tmp/runs/sandbox/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
 
 Two more fields ride alongside the verdict rather than inside it. `escapes` lists what the run wrote under a watched toolkit root, which the verdict cannot assert over because those files sit outside the sandbox tree. `sessions` reports the nested-dispatch bound, carrying `watched` for whether the client's session registry was there to read, `new` for the records that appeared while the run was in flight, `concurrent` for the records present both before and after, and `reap` for what the run found in the session's process group afterwards. Neither field fails a run on its own.
 
-`run.sh` passes `concurrent` through `--concurrent-sessions` to `sandbox check`, and `checkEscapeScope` appends a witness count to an `unbounded escape:` message rather than lets it soften the verdict.
+`canon sandbox run` passes `concurrent` through `--concurrent-sessions` to `sandbox check`, and `checkEscapeScope` appends a witness count to an `unbounded escape:` message rather than lets it soften the verdict.

package/docs/agents/scripting.md

@@ -17,7 +17,7 @@ Use these to discover what's available instead of hardcoding names.
 | `canon standards list --json`     | Standards docs and the paths each governs                        |
 | `canon gov list --json`           | Governance stacks, rule sets, and unreferenced rules             |
 | `canon claude seeds list --json`  | Seed doc sources with content                                    |
-| `canon claude skills list --json` | Plugin skills, descriptions, requirement flag                    |
+| `canon claude skills list --json` | Plugin skills, descriptions, requirement flag, family vocabulary |
 | `canon docs list --json`          | Consumer docs plus per-domain context                            |
 | `canon audits list --json`        | Audits the set runs, the corpus each reads, and whether it gates |
 
@@ -68,6 +68,13 @@ or unparseable returns an empty description rather than failing the listing, so
 one malformed file cannot hide the rest of the catalog. `--names` emits skill
 names one per line.
 
+Each skill in `--json` carries `family`, the `metadata.family` its frontmatter
+declares, or `null` where it declares none. A top-level `families` array holds
+the vocabulary as `{ key, group }` entries in skill map order, where `group` is
+the map heading the family's rows sit under. Read a new skill's family from it
+rather than from the map. `--by-family` prints the human listing as one step per
+family, with a trailing step for any skill whose family is missing or unknown.
+
 Each entry also carries `requirement`, whether the folder holds a sibling
 `REQUIREMENT.md`. Every skill is meant to carry one, so a `false` is a gap to
 close rather than a recorded exemption, and the flag answers which skills are

package/docs/agents/skills-audit.md

@@ -36,7 +36,9 @@ Each check traces to a line in the standard.
 - Folder name in kebab-case
 - Each `REQUIREMENT.md` declaring `Gap` and `Must`, matched at any heading level
 - No ISO date in `SKILL.md` or any file under `references/`, reported as `datedProvenance` in the JSON record's `findings`
-- Each listed practice skill closing with `## Excuses and rebuttals`, `## Red flags`, and `## Before handing over`, and carrying `references/adopted.md`, reported as `practiceShape`
+- Each listed practice skill closing with `## Excuses and rebuttals`, `## Red flags`, and `## Before handing over`, and each skill on the wider ledger list carrying `references/adopted.md`, reported together as `practiceShape`
+- Each file under `references/` running over 100 lines opening with a `## Contents` H2, reported as `referenceContents`
+- Each skill under `claude/skills/` declaring a `metadata.family` that names a key in `checkpoints.families`, reported as `family`
 
 A body whose frontmatter does not parse reports as declaring neither field rather than ending the run, so one malformed file cannot hide the corpus behind it. A key present with an empty value reads as absent, since a blank `name` would otherwise report as a name disagreeing with every folder. A folder carrying no requirement is reported once under presence rather than counted again for the sections it therefore lacks.
 
@@ -44,7 +46,11 @@ The date check reads prose alone. A date inside a fence or a code span is exampl
 
 Each finding names the file and the line, such as `claude/skills/<name>/references/<file>.md  line 12: <date>`. A date after "measured" or "verified" reports like any other, unlike the context audit, because a skill body states the rule a session follows today rather than a reading of the tree.
 
-The practice check reads only the skills the audit lists, which the JSON record carries as `checkpoints.practiceSkills`. The list names folders under the toolkit's shipped `claude/skills/` corpus alone, so a project's own skill is never read as a practice skill and a same-named folder under `.claude/skills/` produces no finding. Where `claude/skills/` resolves, a listed folder it does not hold reports as a missing skill, so a renamed or misspelled entry cannot pass unread. Each closing section matches only as an exact H2 outside a fence, so an H3 or a heading carrying more words reports as missing.
+The practice check reads only the skills the audit lists, which the JSON record carries as `checkpoints.practiceSkills` for the closing sections and `checkpoints.ledgerSkills` for the ledger. The ledger list holds every practice skill plus the skills that cite outside sources without a practice's closing shape, so a skill on it alone owes the ledger and none of the sections.
+
+Both lists name folders under the toolkit's shipped `claude/skills/` corpus alone, so a project's own skill is never read as a practice skill and a same-named folder under `.claude/skills/` produces no finding. Where `claude/skills/` resolves, a listed folder it does not hold reports as a missing skill, so a renamed or misspelled entry cannot pass unread. Each closing section matches only as an exact H2 outside a fence, so an H3 or a heading carrying more words reports as missing.
+
+The contents check counts every line of a reference, frontmatter included, the way `wc -l` does, so a file of exactly 100 lines passes and one of 101 needs the list. `## Contents` matches the same way the closing sections do, as an exact H2 outside a fence. `SKILL.md` is never read for it, and the threshold travels in the JSON record as `checkpoints.contentsThreshold`.
 
 ## What it leaves alone
 
@@ -56,7 +62,9 @@ A check with no rule behind it prints an opinion as a defect, which is where the
 
 ## Exit codes
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, requirement-section, dated-provenance, and practice shape findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around. In the toolkit, two `bun run check` stages read the same report in-process and fail a push on dated provenance and on practice shape, since its own corpus is held at zero on both.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, requirement-section, dated-provenance, practice shape, reference contents, and family findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around. In the toolkit, three `bun run check` stages read the same report in-process and fail a push on dated provenance, on practice shape, and on family, since its own corpus is held at zero on all three.
+
+No stage reads reference contents, so a long reference without a list stays a report.
 
 ## The requirement gate
 

package/docs/agents/slides.md

@@ -1,16 +1,28 @@
 ---
 title: Slides
-description: What a folder of HTML slides declares for the whole deck in deck.json, the faces it embeds, what each slide declares on its own body, transitions and entrances, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
+description: Where a deck folder lives and what it holds, what it declares for the whole deck in deck.json, the faces it embeds, what each slide declares on its own body, transitions and entrances, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
 ---
 
 # Slides
 
-`canon slides render --source <folder>` turns a folder of `.html` slides into an editable PowerPoint deck. Each slide describes its own shapes. What belongs to the whole deck, being the bands, the numbers, and the mark, sits in one file beside them, and the master that carries it takes the project's own colors and face.
+`canon slides render <deck>` turns a folder of `.html` slides into an editable PowerPoint deck. Each deck lives in its own folder under `.canon/slides/`, which `canon records push` backs and git ignores, and `canon slides list --json` lists them. Each slide describes its own shapes. What belongs to the whole deck, being the bands, the numbers, and the mark, sits in one file beside them, and the master that carries it takes the project's own colors and face.
 
 ```bash
-canon slides render --source slides/q3-review
+canon slides list --json
+canon slides render q3-review
 ```
 
+## The deck folder
+
+| Path                             | Holds                                                |
+| -------------------------------- | ---------------------------------------------------- |
+| `.canon/slides/<deck>/*.html`    | the slides, rendered in filename order               |
+| `.canon/slides/<deck>/deck.json` | what belongs to the whole deck, described below      |
+| `.canon/slides/<deck>/assets/`   | images the slides reference by a relative path       |
+| `.canon/slides/layouts/`         | the project's shared layouts, never listed as a deck |
+
+A folder holding no `.html` file is not a deck. `render` with no name takes the only deck there is, and refuses with the list when there are several. It also takes a folder path outside `.canon/slides/`.
+
 ## The deck file
 
 `deck.json` beside the slides is optional. Without it the deck gets its defaults.