@erclx/canon 5.26.0 → 5.28.0

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,9 +37,10 @@ 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
+- [The pull request checklist tick](pr-tick.md): How canon pr tick marks the checklist boxes a UI pass drove, the stamp that names the commit each passed at, why a render at a newer head clears a tick, the refusal reasons it names, and why a taste box is never ticked
 - [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
 - [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
@@ -61,7 +62,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Targets](targets.md): The projects this toolkit installed into, the record the install writes against the sweep that backs it, what bounds each answer, and the cross-target pull request read
 - [Tasks archive](tasks-archive.md): Archiving a shipped task by stem or pull request, declining one decided against, the refusal reasons each carries, and how the plan and ready folder move with the task
 - [Tasks plans](tasks-plans.md): The five verbs that read or write a task's plan, being where it sits and who cites it, whether it waits on the operator, the branch it derives, what a branch reached against what it declared, and writing its Plan line
-- [Tasks validate](tasks-validate.md): Validating the board against the tree, the seven checks, the untested, claims, wide, and unplaced arrays, the exit codes, and the refusal reasons
+- [Tasks validate](tasks-validate.md): Validating the board against the tree, the seven checks, the five report arrays, the exit codes, and the refusal reasons
 - [Tasks](tasks.md): Claiming the next phase label, recording a pull request number and closing an outcome, listing each task's readiness, and where archiving, the plan verbs, and board validation are described
 - [Teach authoring](teach-authoring.md): Resolving what the next lesson needs before it is written, rendering a lesson body's blocks to HTML, and rewriting the root listing, a contents page, and each lesson's chrome and quiz stepper from its marker regions
 - [Teach](teach.md): Listing learning workspaces with what their records schedule next, opening one with its required files, recording sources and glossary terms, viewing one with its chrome refreshed, where the lesson authoring verbs are described, the refusal reasons, and why every write here runs through a verb

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

@@ -33,16 +33,16 @@ its filename carries an image extension (`png`, `jpg`, `jpeg`, `gif`, `webp`,
 folder holds whatever else a project keeps beside its captures. This
 repository's own tree carries eight `.md` files, two `.sh` scripts, a `.tsv`,
 a `.json`, and an `.html` file against a single `.png`, and every one of them
-would render as a broken `![]()` embed without the extension filter.
+would render as a broken image embed without the extension filter.
 
 ## What the record carries
 
 The record groups every evidence path by state, the remainder of its
 directory under the `evidence/` segment, and within a state by filename stem,
 so a `before/hero.png` and an `after/hero.png` naming the same case group as
-one entry rather than two unrelated files. Each entry carries whether it
-existed at the base commit, which decides whether the comment shows a base
-image or marks the case new.
+one entry, not two files. Each entry carries whether it existed at the base
+commit, so the comment shows a base image or marks it new. All-new states drop
+the Base column and each image is an `<img width="1000">`.
 
 `reason` on the record is what a caller branches on, not the exit code:
 
@@ -70,9 +70,10 @@ 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. |
+| `boxes`     | Each box's `number`, `text`, tick, `stamp`, and `isTaste`.        |
 
 These come from the comment already posted, never from the flags the call
 passed, so a skill driving a review reads which address and which checklist a
@@ -102,7 +103,7 @@ The trade is that the verb no longer sees evidence that is uncommitted or
 unpushed, which the comment's head-pinned image links could not show anyway.
 A path the pull request renamed or copied counts as added, since the new path
 has no counterpart at the merge base, so a rename loses its before image and
-renders `*(new)*`. A path the pull request removed is dropped, since it has no
+reads as new. A path the pull request removed is dropped, since it has no
 head image to show. A failed files read refuses as `unreadable-changes` rather
 than rendering a short set, and a missing merge base refuses as `no-base`.
 
@@ -142,11 +143,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
 
@@ -158,9 +182,9 @@ screenshots, and what a reviewer has to look at. The file is what
 
 A run without the option carries forward whatever checklist the marked comment
 already holds, the same way the preview address is carried. That is what keeps
-`git-followup`'s re-render after a push from wiping boxes a reviewer has
-already ticked, since `git-pr` deletes the handoff once the first post reports
-success and no later call has a file to pass.
+`git-followup`'s re-render after a push from dropping the checklist, since
+`git-pr` deletes the handoff once the first post reports success and no later
+call has a file to pass. `canon docs pr-tick` covers what a tick carries.
 
 The option decides `no-evidence` on its own. A branch with a checklist and no
 changed evidence image renders `ok` with a marked body holding the checklist,
@@ -173,11 +197,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 +229,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/pr-tick.md

@@ -0,0 +1,72 @@
+---
+title: The pull request checklist tick
+description: How canon pr tick marks the checklist boxes a UI pass drove, the stamp that names the commit each passed at, why a render at a newer head clears a tick, the refusal reasons it names, and why a taste box is never ticked
+---
+
+# The pull request checklist tick
+
+`canon pr tick` ticks the boxes of the visual checklist on the pull request's
+evidence comment. `review-ui` calls it once its verdict has posted, for every
+box that passed at the head it drove, so the person merging reads a checklist
+a driver worked through instead of one that stays empty.
+
+```bash
+canon pr tick 1341 --boxes 1,2,4 --head <sha> --json
+```
+
+Box numbers come from the `boxes` field of `canon pr evidence --json`, which
+numbers the checklist's box lines in order. A caller never counts lines itself.
+
+## What a tick looks like
+
+A ticked box ends in the commit it passed at, visible on the comment:
+
+```markdown
+- [x] click "Pricing" in the header → the pricing page opens · passed at `<short-sha>`
+```
+
+The stamp is visible rather than an HTML comment because the person it is for
+reads the merge record, and a hidden head would tell the machine what the
+reader cannot see. The reader matches the stamp only as the trailing segment of
+a line, so a box whose own text says `passed at` is left alone.
+
+## When a tick is cleared
+
+A tick is a claim about one commit, so a render at another commit does not
+carry it forward. `canon pr evidence` settles the checklist before it renders:
+
+- A tick stamped for the render's head stays.
+- A tick stamped for any other head is cleared and loses its stamp.
+- A tick with no stamp, such as one an author or the operator added by hand,
+  stays only when the comment it came from described the render's head.
+
+A render at the same head after `--preview` keeps every tick. A push that
+reaches the branch without a render leaves its ticks in place until the next
+one, and the stamp still shows which head earned them.
+
+## What it refuses
+
+`reason` on the record is what a caller branches on, not the exit code:
+
+| Reason         | What it means                                                                                                |
+| -------------- | ------------------------------------------------------------------------------------------------------------ |
+| `ticked`       | The boxes were ticked, with the remote tip in `head`.                                                        |
+| `stale-head`   | `--head` is not the branch tip on the remote. Nothing is written.                                            |
+| `taste-box`    | A named box ends in `(taste)`. Nothing is written.                                                           |
+| `no-box`       | A named number is past the end of the checklist. Nothing is written.                                         |
+| `no-checklist` | The evidence comment carries no checklist.                                                                   |
+| `no-comment`   | No comment on the pull request carries the evidence marker.                                                  |
+| `bad-boxes`    | `--boxes` is not a list of positive whole numbers, or `--head` is not a hex sha of seven characters or more. |
+
+A taste box is a judgment of look or feel that a driver reports as needing a
+person's eyes. Refusing it in the verb makes that rule a check rather than a
+sentence a driver can talk itself out of, and a refusal writes none of the
+boxes named beside it.
+
+The head is compared against the tip read from the remote rather than the pull
+request object, which lags a push by up to a minute. A push landing between
+that read and the write leaves a tick at an older head until the next render
+clears it, the same window `canon pr head` documents.
+
+The verb edits the marked comment in place with a `PATCH`, the way
+`canon pr local --remove` does, and ticking a box again restamps it.

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 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`:
+Scenarios live under `sandbox/`, one folder per category and one file per command, either a TypeScript module or a bash script, and provisioning refuses a command present in both forms. `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
@@ -69,7 +93,7 @@ The baseline is a detached worktree with full history, removed on exit including
 
 The record lists per arm `identical`, `differs` with the manifest keys that differ, `red-on-base` when both sides fail the same way, or `skipped-anchor`. It also carries `canonVersion`, `baseCommit`, `masksApplied`, `errors`, and `counts`. A declared arm adds a `check` entry from `canon sandbox check` on the head tree, whose `asserted` count shows its `expect.toml` resolved from `sandbox/fixtures/`.
 
-Exit 0 means every compared arm is identical or red the same way on both sides. Exit 1 means any `differs`, a base and head exit that disagree, or an armed arm that `canon sandbox coverage` lists and enumeration lacks.
+Exit 0 means every compared arm is identical or red the same way on both sides. Exit 1 means any `differs`, a base and head exit that disagree, an armed arm that `canon sandbox coverage` lists and enumeration lacks, a scenario present as both `.sh` and `.ts`, or a `.ts` scenario that fails to load.
 
 ## Scenario coverage
 
@@ -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

@@ -38,6 +38,7 @@ Each check traces to a line in the standard.
 - 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 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.
 
@@ -61,7 +62,7 @@ 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, practice shape, and reference contents 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.
 

package/docs/agents/tasks-plans.md

@@ -59,7 +59,7 @@ The question block is read through the same parser `canon tasks validate` runs,
 
 Branch on `launchable` rather than on the exit code, for the reason the section above states: a shell profile wrapping `canon` in a function can take a later command's status and mask every non-zero exit, which reads a waiting plan as a launchable one.
 
-The orchestrator dispatch runbook calls this before it checks the branch or the file sets, so a row whose plan still needs a person is handed back rather than launched into a worker that halts on the same question.
+The orchestrator dispatch runbook calls this before it checks the branch or runs its conflict check, so a row whose plan still needs a person is handed back rather than launched into a worker that halts on the same question.
 
 ```bash
 canon tasks plan-answers dispatch-answer-gate --json | jq -r '.launchable'