@erclx/canon 4.69.0 → 4.70.0

package/docs/agents/commands.md

@@ -32,6 +32,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon feedback`                 | Write toolkit feedback from stdin to `.canon/review/feedback/`, or open a GitHub issue with `--github`, refusing either when a required field is absent                                                                                                                                                                |
 | `canon transcripts <url>`        | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                                                                                                                                                                                                                                                  |
 | `canon tasks archive`            | Move a shipped task and its plan off the board, clear its ordering row, and regenerate the index                                                                                                                                                                                                                       |
+| `canon tasks decline`            | Move a decided-against task and its plan into `.canon/tasks/declined/`, recording who decided and why (`--reason`, `--by`, `--json`)                                                                                                                                                                                   |
 | `canon tasks pull-request`       | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                                                                                                                                                                                                               |
 | `canon tasks plan-link`          | Write or correct a task's `Plan:` line to point at a plan, by stem and plan path or slug (`--json`)                                                                                                                                                                                                                    |
 | `canon tasks outcome`            | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)                                                                                                                                                                                                                                              |
@@ -81,6 +82,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon pr key-changes`           | Compare the files a pull request body's Key Changes names against its own diff, in both directions (`--body`, `--base`, `--json`)                                                                                                                                                                                      |
 | `canon pr head`                  | Compare the head a pull request object reports against the branch tip the remote carries, naming both shas (`--root`, `--json`)                                                                                                                                                                                        |
 | `canon pr checks`                | Report the check runs belonging to the branch tip, reading pending for a tip carrying none rather than clean (`--root`, `--json`)                                                                                                                                                                                      |
+| `canon pr review-state`          | Report the commit and instant the last review pass covered, off the pass's own marker rather than the fields GitHub stamps at submission (`--root`, `--json`)                                                                                                                                                          |
 | `canon repo metadata propose`    | Compare a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing (`--root`, `--json`)                                                                                                                                                       |
 | `canon repo metadata apply`      | Write an explicitly supplied description, homepage, or topic set to the remote through `gh repo edit` (`--description`, `--homepage`, `--topics`, `--root`, `--json`)                                                                                                                                                  |
 | `canon census [path]`            | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                                                                                                                                                                                                   |

package/docs/agents/demo.md

@@ -18,13 +18,13 @@ canon demo frames demos/inline-edit.webm --fps 2
 
 ## The draft and the plan are different files
 
-`canon-screencast` drafts beats for a person. A beat carries what is on screen, one verb, what to watch for, an emphasis, and a caption, and none of that names a selector, a URL, a wait condition, or a timing. Those four are what an executor needs and what would ruin the draft, since the format is pre-seeded so the operator edits down rather than fills blanks.
+`draft-screencast` drafts beats for a person. A beat carries what is on screen, one verb, what to watch for, an emphasis, and a caption, and none of that names a selector, a URL, a wait condition, or a timing. Those four are what an executor needs and what would ruin the draft, since the format is pre-seeded so the operator edits down rather than fills blanks.
 
 So `canon demo compile` writes a second artifact rather than adding fields to a beat. It maps each beat's verb to a step, seeds the timing, marks which beat the still comes from, and leaves the target and the URL empty for a person to fill. The report names every field it could not supply.
 
 The plan is committed, not scratch. Its timing is a starting point tuned by watching a recording, and the draft cannot reproduce a tuned value, so a recompile over an existing plan refuses and names `--force`.
 
-`canon-record` is the routed way to run both verbs from a draft path: it compiles only when no plan exists yet, then runs, stopping to report any field still unresolved rather than guessing one.
+`record-screencast` is the routed way to run both verbs from a draft path: it compiles only when no plan exists yet, then runs, stopping to report any field still unresolved rather than guessing one.
 
 | Option          | Behavior                                                          |
 | --------------- | ----------------------------------------------------------------- |
@@ -64,7 +64,7 @@ A step waits on its `waitFor` selector becoming visible and then holds for its o
 | `--fps <n>`       | Frames extracted per second of video, default `1`        |
 | `--json`          | Add a record on stdout carrying every frame path written |
 
-`canon-frames-read` is the routed way to call this verb and read the frames back: it runs the verb, reads each returned frame with the Read tool, and reports one plain description per frame. It never renders a verdict, since a frame read is evidence a person weighs rather than a pass or fail this toolkit states on their behalf.
+`read-frames` is the routed way to call this verb and read the frames back: it runs the verb, reads each returned frame with the Read tool, and reports one plain description per frame. It never renders a verdict, since a frame read is evidence a person weighs rather than a pass or fail this toolkit states on their behalf.
 
 ## The pointer is painted inside the page
 

package/docs/agents/index.md

@@ -28,7 +28,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
-- [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading check runs keyed on that tip, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
+- [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](records.md): The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file and every path-scoped rule share with the seed, the shipped 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
 - [Review classification](review-classification.md): Deciding whether a changed set needs the review pass, the two tests it runs, why an empty set refuses rather than skipping, and the written fallback a target on an older binary falls back to

package/docs/agents/pr-reads.md

@@ -1,17 +1,19 @@
 ---
 title: Head-sensitive pull request reads
-description: Resolving a branch tip from the remote rather than from the pull request object, reading check runs keyed on that tip, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
+description: 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
 ---
 
 # Head-sensitive pull request reads
 
-`canon pr head` and `canon pr checks` answer about a commit. Both resolve the branch tip from the remote with `git ls-remote` and report what they found for that sha, rather than taking the pull request object's word for which commit the branch is on.
+`canon pr head`, `canon pr checks`, and `canon pr review-state` each answer about a commit, and each exists because the field GitHub offers answers a different question. The first two resolve the branch tip from the remote with `git ls-remote` rather than taking the pull request object's word for which commit the branch is on. The third reads what a review pass covered off a marker the pass wrote, rather than off the head GitHub stamped when the review was submitted.
 
 ```bash
 canon pr head
 canon pr head 1341 --json
 canon pr checks
 canon pr checks 1341 --json
+canon pr review-state
+canon pr review-state 1341 --json
 ```
 
 ## The pull request object is not the authority for a head
@@ -30,8 +32,40 @@ The argument is stated here once. The shipped skill bodies call the verb rather
 
 `canon pr checks` reads `repos/{owner}/{repo}/commits/<tip>/check-runs` and collapses it to `passing`, `failing`, or `pending`. A failure outranks a run still going, since a run in flight cannot clear a job that already failed.
 
+`canon pr review-state` reports `heading` and `state` for the newest pass in the review family, `commit` and `readAt` for what it covered, `submittedAt` for when GitHub recorded it, and `source` for which of those readings answered. A thread carrying no pass reports `state` and `source` both as `none` with nothing else on the record.
+
 `gh pr checks` cannot be made to answer this question at all, which is the argument for the move rather than a preference between two working commands. Its `--json` field set is `bucket, completedAt, description, event, link, name, startedAt, state, workflow`, with no sha among them, so a caller cannot even learn which commit its answer describes.
 
+## A review's stamps describe the submission, not the read
+
+`commit.oid` on a review names whatever the pull request head was at the instant the review was submitted. `submittedAt` names that instant. Neither names the commit the reviewing session actually opened, and the two are only the same when nothing was pushed while the comment was being written.
+
+A push landing in that window moves both onto a commit nobody reviewed. The next pass then scopes its delta past that commit and reports it covered, which is the failure direction that loses work: the commit is skipped rather than re-read. It fired on a pull request in this toolkit on 2026-09-07, where a pass read one commit, the branch pushed another during the compose, and the poll reported the second as already seen. What it skipped was a genuine fix, and a reader comparing the sha in the report against the sha in the pass caught it.
+
+`review-pr` therefore ends every body it posts with a marker naming what it read:
+
+```markdown
+<!-- review-pr: commit=<sha> read-at=<iso8601> -->
+```
+
+Both values are taken at the top of the pass rather than at the post, so the compose window falls outside what the marker claims. An HTML comment renders as nothing on GitHub, so a reader of the thread never meets it.
+
+The last non-empty line is where it has to sit, and the reader looks nowhere else. Searching a body for the last match instead reads a marker the body was displaying rather than claiming, since a fenced block showing the format on its own line trims to exactly the pattern, and a pass carrying no marker of its own would then hand the next reader a commit taken from an illustration. That is the same defect through a second door, so position rather than shape is what separates a claim from a quotation.
+
+`canon pr review-state` is the only parser of that format. Two parsers was the alternative, one in the shipped skill body and one in the orchestrator poll's jq, and those two ship on different cadences, so a format change to either would leave the other reading a reviewed commit as unreviewed.
+
+`source` on the record says which reading answered, and a caller checks it before trusting the rest:
+
+| Source     | What it means                                                                               |
+| ---------- | ------------------------------------------------------------------------------------------- |
+| `marker`   | The pass wrote its own read-time record, which is the authority                             |
+| `fallback` | A pass posted before this shipped, read off the submission stamps and carrying their defect |
+| `none`     | The thread carries no pass, so the next one is a first pass                                 |
+
+The record carries `submittedAt` beside `readAt` rather than in place of it, because each is right about a different question. What a pass had read is a fact about the read, and how long a posted comment has waited on a human is a fact about the submission. The orchestrator poll reads the first for its coverage test and the second for its age test.
+
+A `PUT` rewrite of a standing close-out inherits the fix without a mechanism of its own. That request replaces the body and the marker rides in it, so a rewritten comment names the commit the rewriting pass read. `submittedAt` stays pinned to the original submission, which is the reading the age test wants anyway.
+
 ## An empty run list is not a pass
 
 Keying the query on a sha is necessary and not sufficient. The endpoint answered with `total_count` 2 and an empty row list during a measured window on 2026-09-02, so a reader that finds no run for the tip and reports `passing` reproduces the false green behind a better query.
@@ -50,15 +84,16 @@ Branch on the record rather than on the exit. Both verbs exit 0 whenever they re
 
 Each refusal names a different repair:
 
-| Reason             | What it means                                                                              |
-| ------------------ | ------------------------------------------------------------------------------------------ |
-| `gh-missing`       | `gh` is not on the path, so no pull request resolved                                       |
-| `gh-failed`        | `gh` could not answer for this branch, so name a number instead                            |
-| `no-branch`        | The pull request carries no head branch name, so no ref could be read                      |
-| `unresolvable-ref` | The remote read failed, which is not the same answer as an absent branch                   |
-| `no-remote-branch` | The remote carries no branch by that name, so there is no tip to compare against           |
-| `no-object-head`   | The pull request object reported no head, so `head` has nothing to compare the tip against |
-| `runs-unreadable`  | The check runs for the tip could not be read, which is unread rather than none             |
+| Reason               | What it means                                                                              |
+| -------------------- | ------------------------------------------------------------------------------------------ |
+| `gh-missing`         | `gh` is not on the path, so no pull request resolved                                       |
+| `gh-failed`          | `gh` could not answer for this branch, so name a number instead                            |
+| `no-branch`          | The pull request carries no head branch name, so no ref could be read                      |
+| `unresolvable-ref`   | The remote read failed, which is not the same answer as an absent branch                   |
+| `no-remote-branch`   | The remote carries no branch by that name, so there is no tip to compare against           |
+| `no-object-head`     | The pull request object reported no head, so `head` has nothing to compare the tip against |
+| `runs-unreadable`    | The check runs for the tip could not be read, which is unread rather than none             |
+| `reviews-unreadable` | The reviews on the pull request could not be parsed, which is unread rather than none      |
 
 A failed remote read and a branch the remote does not carry stay apart rather than collapsing into one reason. Reading the first as the second would report a network refusal as a deleted branch, and the repairs have nothing in common.
 
@@ -68,6 +103,6 @@ One remote round trip per call, sampled here at 0.41s, 0.55s, and 0.67s on 2026-
 
 One head-sensitive read is left on the object deliberately. `canon targets pulls` reads `statusCheckRollup` for every open pull request across every target, where resolving a tip per row would cost one remote read per pull request across a dozen projects, against a surface that reports a listing rather than gating a push.
 
-The orchestrator poll spends that same read per open pull request and repeats it on a three-minute timer, which makes it the heaviest caller here rather than an exception to the paragraph above. Six open pull requests is around 120 remote reads an hour. What separates the two cases is what each reading decides rather than what it costs. The poll's head fires the review trigger, so a stale one sends a pass at a commit nobody read or withholds one that is owed. The listing decides nothing, so the same spend buys a fresher column in a report and no correctness at all.
+The orchestrator poll spends that same read per open pull request and repeats it on a three-minute timer, which makes it the heaviest caller here rather than an exception to the paragraph above. Six open pull requests is around 120 remote reads an hour. It now spends a third read per pull request per tick besides, since `canon pr review-state` makes its own `gh pr view` call beside the payload the poll already fetched. That one is an API round trip rather than a remote ref read, and it buys a coverage test that answers about what a session read. What separates the two cases is what each reading decides rather than what it costs. The poll's head fires the review trigger, so a stale one sends a pass at a commit nobody read or withholds one that is owed. The listing decides nothing, so the same spend buys a fresher column in a report and no correctness at all.
 
 `canon pr key-changes` also stays on the object, for a different reason. It reads the body, the file list, and `headRefOid` in one call on purpose, so the three describe one commit. That is a consistency requirement rather than a freshness one, and keying its head elsewhere would break it.

package/docs/agents/tasks.md

@@ -72,6 +72,36 @@ Skills branch on the reason rather than on the exit code:
 canon tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .reason end'
 ```
 
+## Decline
+
+`canon tasks decline <task>` moves a task decided against from `.canon/tasks/` into `.canon/tasks/declined/`, clears whichever of `priority.md` or `backlog.md` holds its row, and regenerates the board index. Unlike `canon tasks archive`, it carries no outcome-state gate: a task can be decided against at any outcome state.
+
+```bash
+canon tasks decline v28.1-trigger-escalation --reason "superseded by v30.2" # canon-allow-reference: illustrates the stem-selection form, not a citation of a real task
+canon tasks decline v28.1-trigger-escalation --reason "no longer needed" --by Alex --json
+```
+
+| Option            | Behavior                                          |
+| ----------------- | ------------------------------------------------- |
+| `--reason <text>` | Why the task was decided against, required        |
+| `--by <name>`     | Who decided, defaulting to `git config user.name` |
+| `--json`          | Emit a machine-readable record on stdout          |
+| `--root <path>`   | Board root, defaulting to the main worktree       |
+
+Exit codes: `0` declined, `1` refused. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, or `bad-input`. `bad-input` covers a missing `--reason` and a `--by` that resolves to nobody, git config included.
+
+`DECLINE_REFUSALS` is kept apart from archive's own refusal set on purpose. Archive and decline answer different questions, shipped versus decided-against, and a shared gate would let one archive a task that cannot yet ship or decline one that already has.
+
+The decision is written onto the task as a `Declined: <reason>, <who> on <YYYY-MM-DD>` line, anchored the same way `Pull request:` is, after the last origin line the task carries.
+
+The task carries its plan with it the same way archive does, when the declining task is the last live citation. A declined task's plan lands in `.canon/plans/archive/`, indistinguishable from a shipped one by folder alone. The task file under `.canon/tasks/declined/` is what records which it was.
+
+Skills branch on the reason rather than on the exit code, the same rule `canon tasks archive` states:
+
+```bash
+canon tasks decline v28.1-trigger-escalation --reason "superseded by v30.2" --json | jq -r 'if .ok then .task else .reason end' # canon-allow-reference: illustrates the stem-selection form, not a citation of a real task
+```
+
 ## Plan citations
 
 `canon tasks plan-citations <stem>` answers where a task's plan sits and which other live tasks hold it. It reports and never writes.
@@ -244,7 +274,7 @@ Seven checks run. Plan and Collisions reach one half each of the `## Run now` te
 | Grouping   | A task carrying a row in more than one readiness group, or on both surfaces                                             |
 | Ordering   | A `## Needs a plan` row whose stated position disagrees with where it actually sits, or which states no position at all |
 | Collisions | Two `## Run now` rows whose Touches columns name a path in common                                                       |
-| Blockers   | A parked row whose blocker has stopped holding, or whose cited task resolves nowhere                                    |
+| Blockers   | A parked row whose blocker has stopped holding, whose cited task resolves nowhere, or whose cited task was declined     |
 
 Shape runs before any other check reads a row, since a row failing it carries no dependable fields for the rest to check. A blank or prose line closes the table above it, so the walk treats the next pipe line as a fresh header candidate rather than as a continuation. That candidate counts as a header only when the line behind it is a separator carrying the same cell count, and one that fails is `row-untabled`, stranded behind a table that already closed. Cell count still has to match the header on every row that clears that test, and a row whose count disagrees is `row-misshapen`, the shape a dropped pipe or a merged column produces.
 
@@ -264,7 +294,20 @@ The collision check is the one a person cannot run by eye. Paths come from the b
 
 Where a directory holds the other row's file, the finding names the row that claimed it, reading `both touch src/tasks, which v2.0-second claims as a folder.` The shared strings alone leave an over-broad cell and a genuine overlap identical, which is how a correct report was once read as the verb comparing folders rather than files. <!-- canon-allow-reference: illustrates the finding's own sentence shape, not a citation of a real task -->
 
-The blocker check re-takes a measurement the board records once and never repeats. Two of the five blocker kinds put a fact on disk: a dependency is settled by the cited task being archived or by its work reaching the trunk, and a collision is settled by nothing under `## Run now` still holding the file the cell cites.
+The blocker check re-takes a measurement the board records once and never repeats. Two of the five blocker kinds put a fact on disk: a dependency is settled by the cited task being archived or by its work reaching the trunk, and a collision is settled by nothing under `## Run now` still holding the file the cell cites. A cited task resolving under `.canon/tasks/declined/` instead reports separately as `blocker-declined`, since a decided-against task is neither the shipped work `blocker-settled` reports nor the dangling pointer `blocker-unresolved` reports.
+
+```json
+{
+  "findings": [
+    {
+      "kind": "blocker-declined",
+      "group": "Up next",
+      "subject": "v50.6-a-standard-no-skill-reads", // canon-allow-reference: shows the subject field's real vXX.Y-slug shape, not a citation of a real task
+      "message": "waits on v9.0-superseded, which was declined." // canon-allow-reference: illustrates the finding's own sentence shape, not a citation of a real task
+    }
+  ]
+}
+```
 
 A closed outcome is not the fact the dependency half needs. The ship chain marks outcomes as its first step and opens the pull request several steps later, so a check reading the checkbox reports the row settled while the branch is still in review. A live task therefore settles the row only once it closed every outcome and carries a `Pull request:` line the trunk holds. One that names no pull request, and one whose number no trunk ref could answer for, land in the untested array below rather than being settled or left silent.
 
@@ -272,7 +315,7 @@ The trunk is read as the clone already holds it, `origin/main` first and local `
 
 Both halves gate on a citation inside the `Waiting on` cell, never on the columns beside it. The board format gives a collision cell the file held by the running task, so a row whose cell names no file was parked by something else, and testing its Touches column instead reports a cleared collision on a row no collision ever parked while counting that row as re-tested. A cited task is a bare sibling link, the way the Task column spells one, so a pointer into another folder names a plan rather than a task and settles nothing. A cited task carrying no outcome box settles nothing either, since a file the check could not parse is not evidence of a finished one.
 
-A citation resolving in neither the board nor the archive is `blocker-unresolved` rather than a settled row. Reading an absent file as archived states a specific fact about a file nobody ever wrote, which is what a renamed task or a typo produces, and only a task that genuinely closed releases the row waiting on it.
+A citation resolving in none of the board, the archive, or the declined folder is `blocker-unresolved` rather than a settled row. Reading an absent file as archived or declined states a specific fact about a file nobody ever wrote, which is what a renamed task or a typo produces, and only a task that genuinely closed or was genuinely declined releases the row waiting on it.
 
 The other three kinds rest on a person's judgment, so a row neither half reached lands in a second array rather than in the findings:
 

package/docs/workflow/ai-workflow.md

@@ -80,7 +80,7 @@ When features are independent, run them in parallel instead of sequentially. Use
 - Invoke `canon:plan-feature` in each session. Plans land at the main worktree root as `.canon/plans/feature-<slug>.md`, one per feature, no collisions. Small features stay in chat and skip the file.
 - Implement, verify, and review each feature independently. `review-branch` writes a per-branch report at the main worktree root (`review/branch/review-<slug>.md`), and `ui-test` writes a per-branch checklist handoff there too (`tmp/ui-checklist/<slug>.md`) that `git-pr` posts to the pull request and removes, so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
 - Ship each worktree separately with `canon:git-ship`
-- For full autonomy per worktree, invoke `canon:auto-ship` instead of the manual chain. Approve the plan, walk away, come back to a pull request the chain marked as a draft and then read the flag back on. The mark says the work has had no review yet, and it holds no window, since readying a pull request to merge lifts it and is the operator's act.
+- For full autonomy per worktree, invoke `canon:auto-ship` instead of the manual chain. Approve the plan, walk away, come back to a pull request the chain marked as a draft and then read the flag back on. The mark says the work has had no review yet, and it holds no window, since readying a pull request to merge lifts it directly, an act reserved to the operator or to the controlling session that closed the review.
 
 To run several worktrees as a coordinated flow rather than ad hoc, assert the orchestrator role in one warm session with `canon:role-orchestrator`. It holds the cross-feature call, plans each feature itself or dispatches a cold planner under `canon:role-planner` to write the plan, refills the ready queue so a free worker never waits, and reviews each worker's PR with `canon:review-pr`, then tells the session holding that branch to run `canon:review-address` whenever the pass posted a finding at any severity, which is the same threshold `canon:review-pr` states and posts its open heading under. The human launches workers and merges. See [operating model](operating-model.md) for the full loop.
 
@@ -289,23 +289,23 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Generate an artifact on demand
 
-| Skill                      | When to use                                                                                       |
-| -------------------------- | ------------------------------------------------------------------------------------------------- |
-| `canon:create-rule`        | For a project-specific governance rule the toolkit does not ship                                  |
-| `canon:create-skill`       | For a new `SKILL.md`                                                                              |
-| `canon:create-snippet`     | For a reusable prompt                                                                             |
-| `canon:create-standard`    | For a new authoring convention                                                                    |
-| `canon:draft-docs`         | For a brand-new `docs/*.md` page, drafted against `standards/docs.md`                             |
-| `canon:draft-context`      | For a brand-new `.claude/context/<domain>.md` entry, drafted against `standards/context.md`       |
-| `canon:draft-wireframes`   | For a brand-new `.claude/wireframes/<surface>.md` file, drafted against `standards/wireframes.md` |
-| `canon:draft-readme`       | For a project's `README.md`, drafted against `standards/readme.md`                                |
-| `canon:bash-script`        | For an interactive, human-facing shell tool                                                       |
-| `canon:bash-cli-script`    | For a non-interactive automation, CI, or pipeline script                                          |
-| `canon:ci-workflow`        | For a GitHub Actions workflow file                                                                |
-| `canon:canon-slides-draft` | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                             |
-| `canon:canon-screencast`   | For a recording script with beats and defaults already seeded                                     |
-| `canon:canon-record`       | For compiling and running a screencast draft into a recording and a still                         |
-| `canon:identity`           | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop       |
+| Skill                     | When to use                                                                                       |
+| ------------------------- | ------------------------------------------------------------------------------------------------- |
+| `canon:create-rule`       | For a project-specific governance rule the toolkit does not ship                                  |
+| `canon:create-skill`      | For a new `SKILL.md`                                                                              |
+| `canon:create-snippet`    | For a reusable prompt                                                                             |
+| `canon:create-standard`   | For a new authoring convention                                                                    |
+| `canon:draft-docs`        | For a brand-new `docs/*.md` page, drafted against `standards/docs.md`                             |
+| `canon:draft-context`     | For a brand-new `.claude/context/<domain>.md` entry, drafted against `standards/context.md`       |
+| `canon:draft-wireframes`  | For a brand-new `.claude/wireframes/<surface>.md` file, drafted against `standards/wireframes.md` |
+| `canon:draft-readme`      | For a project's `README.md`, drafted against `standards/readme.md`                                |
+| `canon:bash-script`       | For an interactive, human-facing shell tool                                                       |
+| `canon:bash-cli-script`   | For a non-interactive automation, CI, or pipeline script                                          |
+| `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                |
+| `canon:draft-slides`      | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                             |
+| `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                     |
+| `canon:record-screencast` | For compiling and running a screencast draft into a recording and a still                         |
+| `canon:identity`          | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop       |
 
 ### Answer a question at any point
 
@@ -314,7 +314,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:canon-cli`           | Before running an unfamiliar verb, a sync, or an install, to learn which command to run, which reference doc covers it, or what it overwrites, merges, or leaves alone |
 | `canon:index-lookup`        | To find where a topic is documented across the tracked `index.md` catalogs                                                                                             |
 | `canon:youtube-transcripts` | When a video transcript is wanted in the repo as context                                                                                                               |
-| `canon:canon-frames-read`   | To read a recorded demo back frame by frame and report what each one shows, with no verdict on whether the recording looks right                                       |
+| `canon:read-frames`         | To read a recorded demo back frame by frame and report what each one shows, with no verdict on whether the recording looks right                                       |
 | `canon:teach-workspace`     | To learn a subject across sessions, in a workspace that holds the progress                                                                                             |
 | `canon:write-human`         | Before drafting or revising prose, for voice, rhythm, and density                                                                                                      |
 | `canon:restate-plainly`     | When an answer or a document has to be read again in plain words                                                                                                       |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.69.0",
+  "version": "4.70.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -44,7 +44,8 @@
     "web:tokens": "bun src/cli.ts design css --no-components > web/src/styles/tokens.css.new && (echo '/* Generated by `canon design css --no-components`. Regenerate with `bun run web:tokens`. Do not hand-edit. */'; cat web/src/styles/tokens.css.new) > web/src/styles/tokens.css && rm web/src/styles/tokens.css.new",
     "web:dev": "cd web && astro dev",
     "web:favicon": "bun scripts/core/regen-web-favicon.ts",
-    "web:build": "bun run web:tokens && bun run web:favicon && cd web && astro check && astro build",
+    "web:previews": "bun scripts/core/regen-web-previews.ts",
+    "web:build": "bun run web:tokens && bun run web:favicon && bun run web:previews && cd web && astro check && astro build",
     "web:preview": "cd web && astro preview",
     "web:e2e": "cd web && playwright test"
   },

package/scripts/core/regen-web-previews.ts

@@ -0,0 +1,94 @@
+/**
+ * Writes `web/public/previews/design-tokens/index.html` and `design.css` by
+ * calling `renderDesignDoc` directly, the in-process pattern
+ * `regen-web-favicon.ts` already takes rather than spawning a subprocess.
+ * Writes `web/public/previews/teach-workspace/` the same way, calling
+ * `generateNav` over an isolated copy of one workspace.
+ *
+ * Both are embedded live in a landing section as an `<iframe>` rather than a
+ * screenshot, since `web/e2e/home.spec.ts` asserts no `<img>` renders inside
+ * `<main>`.
+ */
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { DESIGN_DOCUMENT } from '@/design/regen'
+import { renderDesignDoc } from '@/design/render'
+import { generateNav } from '@/teach/nav'
+
+const root = new URL('../..', import.meta.url).pathname
+
+const { cssPath } = renderDesignDoc(
+  `${root}${DESIGN_DOCUMENT}`,
+  `${root}web/public/previews/design-tokens`,
+)
+
+const css = readFileSync(cssPath, 'utf8')
+if (!/--(color|space|type|radius)-/.test(css)) {
+  console.error(
+    'regen-web-previews: design-tokens render carries no custom properties, refusing an empty preview',
+  )
+  process.exit(1)
+}
+
+console.log('regen-web-previews: wrote web/public/previews/design-tokens/')
+
+/**
+ * The workspace ships alone, on its own isolated nav tree, rather than
+ * copied straight out of `.canon/teach/`. That folder cross-links every
+ * sibling workspace by relative path, including the operator's own personal
+ * study notes, so a copy carrying its live chrome would ship either dead
+ * links or a path into content never meant to be public. Regenerating the
+ * chrome over a scratch copy holding this one workspace alone is what keeps
+ * the jump menus from naming anything else.
+ *
+ * `.canon/teach/` is gitignored session scratch, per `standards/teach.md`, so
+ * it exists on the machine that authored the lesson and nowhere else,
+ * including CI. `web/public/previews/teach-workspace/` is therefore the
+ * durable copy: committed once the workspace exists, regenerated here as a
+ * local convenience when authoring continues, and left untouched by a build
+ * that cannot see the source, the same way a target without Playwright still
+ * builds against a committed capture.
+ */
+const TEACH_SLUG = '04-governance-rule-loading'
+const teachSource = `${root}.canon/teach/${TEACH_SLUG}`
+
+if (!existsSync(teachSource)) {
+  console.log(
+    `regen-web-previews: no workspace at .canon/teach/${TEACH_SLUG} on this machine, leaving the committed web/public/previews/teach-workspace/ as is`,
+  )
+} else {
+  const scratchRoot = mkdtempSync(join(tmpdir(), 'canon-teach-preview-'))
+  try {
+    cpSync(teachSource, join(scratchRoot, '.canon', 'teach', TEACH_SLUG), {
+      recursive: true,
+    })
+
+    const nav = await generateNav(scratchRoot)
+    if (!nav.ok) {
+      console.error(`regen-web-previews: ${nav.message}`)
+      process.exit(1)
+    }
+    if (nav.lessons === 0) {
+      console.error(
+        'regen-web-previews: teach-workspace render carries no lesson, refusing an empty preview',
+      )
+      process.exit(1)
+    }
+
+    const dest = `${root}web/public/previews/teach-workspace`
+    rmSync(dest, { recursive: true, force: true })
+    cpSync(join(scratchRoot, '.canon', 'teach'), dest, {
+      recursive: true,
+      // Only the rendered chrome ships. MISSION.md, RESOURCES.md, and
+      // GLOSSARY.md carry links relative to `.canon/teach/`, which resolve to
+      // nothing once copied under `web/public/`, and nothing links to them
+      // from the rendered pages anyway.
+      filter: (path) => !path.endsWith('.md'),
+    })
+  } finally {
+    rmSync(scratchRoot, { recursive: true, force: true })
+  }
+
+  console.log('regen-web-previews: wrote web/public/previews/teach-workspace/')
+}

package/src/claude/cases/workflow.ts

@@ -41,7 +41,7 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
   {
     prompt:
       'The video just finished recording. Read it back and tell me what each part shows.',
-    expect: 'canon-frames-read',
+    expect: 'read-frames',
   },
   {
     prompt:
@@ -87,7 +87,7 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
   {
     prompt:
       'The screencast draft is finished. Turn it into an actual video now.',
-    expect: 'canon-record',
+    expect: 'record-screencast',
   },
   {
     prompt:
@@ -96,7 +96,7 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'Draft me a script with beats for a screencast recording.',
-    expect: 'canon-screencast',
+    expect: 'draft-screencast',
   },
   {
     prompt:
@@ -105,7 +105,7 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'Turn this topic into a slide deck I can render.',
-    expect: 'canon-slides-draft',
+    expect: 'draft-slides',
   },
   {
     prompt:

package/src/commands/demo.ts

@@ -54,7 +54,7 @@ export function register(program: Command): void {
   demo
     .command('compile')
     .description('Turn a screencast draft into a plan a run can drive')
-    .argument('<draft>', 'Screencast draft written by canon-screencast')
+    .argument('<draft>', 'Screencast draft written by draft-screencast')
     .helpOption('-h, --help', 'Show this help message')
     .option('-o, --out <dir>', 'Directory the plan is written to', DEFAULT_OUT)
     .option('-s, --slug <slug>', 'Plan name, defaulting to the draft filename')