@erclx/canon 5.39.0 → 5.40.0

package/README.md

@@ -161,13 +161,13 @@ For the full journey from scaffold through adding a domain later to syncing upst
 
 Each domain carries an entry written for someone maintaining the toolkit rather than installing it. These paths resolve in a clone only. The published package ships `docs` and not `.claude`, so an installed copy does not carry them.
 
-- [Claude Code plugin](canon/context/claude-plugin/index.md)
-- [Governance rules](canon/context/governance/index.md)
-- [Tooling stacks](canon/context/tooling/index.md)
-- [Design system](canon/context/design.md)
+- [Claude Code plugin](canon/context/surfaces/plugin.md)
+- [Governance rules](canon/context/surfaces/governance.md)
+- [Tooling stacks](canon/context/surfaces/tooling.md)
+- [Design system](canon/context/features/design.md)
 - [Slides](canon/context/features/slides.md)
 - [Transcripts](canon/context/features/transcripts.md)
-- [Sandbox](canon/context/sandbox/index.md)
+- [Sandbox](canon/context/development/sandbox.md)
 
 ## Contributing
 

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

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

package/claude/skills/canvas-board/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 Drive the canvas the operator is looking at. A page is a folder of HTML frames and a frame is one file, so a session draws by writing files and the operator sees each write land in the browser. The content format is fixed by `${CLAUDE_SKILL_DIR}/references/canvas.md`. Read it before writing a frame.
 
-Every verb below is `canon canvas`. Run `canon docs canvas` for the full verb reference, its records, and its refusals.
+Every verb below is `canon canvas`. Run `canon canvas --help` for the verbs and their refusals, and read `${CLAUDE_SKILL_DIR}/references/canvas.md` for the content format.
 
 ## Guards
 

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

@@ -11,16 +11,15 @@ Draw each slide as an HTML file in a deck folder, then shell out to `canon slide
 
 ## Read the decks and the format
 
-Run both first. Never hardcode a deck name, an attribute, or a chart type. The CLI is the source of truth for each.
+Run the list first, then read the format. Never hardcode a deck name, an attribute, or a chart type.
 
 ```bash
 canon slides list --json 2>/dev/null
-canon docs slides
 ```
 
 The list returns one row per deck, carrying its `name`, `title`, slide count, and `path`. When the request names a deck the list holds, edit that folder. Otherwise pick a new kebab-case name no row carries.
 
-The docs page states what `deck.json` holds, what each slide declares on its `<body>`, the motion attributes, speaker notes, charts, and what each refusal reports.
+Read `${CLAUDE_SKILL_DIR}/references/deck.md`. It states what `deck.json` holds, what each slide declares on its `<body>`, the motion attributes, speaker notes, and charts. Each refusal prints as a `✗` line from the render.
 
 ## Draw the deck
 

package/claude/skills/draft-slides/references/deck.md

@@ -0,0 +1,183 @@
+---
+title: Deck reference
+description: The deck folder, the deck.json fields, the attributes a slide sets on its body, motion, the master's token roles, speaker notes, and charts
+---
+
+# Deck reference
+
+Applies to the slides under `.canon/slides/<deck>/`, which `canon slides render <deck>` turns into an editable PowerPoint file. Each slide describes its own shapes. What belongs to the whole deck sits in `deck.json`.
+
+## Contents
+
+- [The deck folder](#the-deck-folder)
+- [The deck file](#the-deck-file)
+- [What each slide declares](#what-each-slide-declares)
+- [Motion](#motion)
+- [The master](#the-master)
+- [Speaker notes](#speaker-notes)
+- [Charts](#charts)
+
+## 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                       |
+| `.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, and refuses with the list when there are several. It also takes a folder path outside `.canon/slides/`.
+
+## The deck file
+
+`deck.json` is optional. Without it the deck takes the defaults below.
+
+| Field          | Default                        | What it sets                                      |
+| -------------- | ------------------------------ | ------------------------------------------------- |
+| `title`        | the folder name                | the file's title and the default footer text      |
+| `header`       | off                            | a band at the top, with `left`, `center`, `right` |
+| `footer`       | on, with the title on the left | a band at the bottom, with the same three slots   |
+| `slideNumbers` | `true`                         | the number at the right of the footer             |
+| `mark`         | none                           | an image path, relative to the folder, top right  |
+| `fonts`        | none                           | faces to embed in the file                        |
+
+```json
+{
+  "title": "Q3 review",
+  "header": { "left": "Acme" },
+  "footer": { "center": "Internal" },
+  "mark": "assets/mark.png",
+  "fonts": [
+    { "family": "Inter", "path": "fonts/Inter-Regular.ttf" },
+    { "family": "Inter", "weight": 700, "path": "fonts/Inter-Bold.ttf" }
+  ]
+}
+```
+
+### Bands and the mark
+
+A band takes `show` and the three slots. A declared band merges over its default, so `"footer": { "center": "Internal" }` keeps the title on the left. Declaring any slot turns a band on unless it also says `"show": false`. Set a slot to `""` to empty it.
+
+- Slide numbers hold the footer's right slot and show only where the footer does. Set `slideNumbers` to `false` to use `footer.right`.
+- Prefer a raster mark, since an SVG mark lands as a vector with a broken fallback.
+
+### Embedded faces
+
+Each `fonts` entry names one TrueType or OpenType file inside the deck folder:
+
+| Key      | Default  | Rule                                                                |
+| -------- | -------- | ------------------------------------------------------------------- |
+| `family` | required | match the family the slides set                                     |
+| `weight` | `400`    | `600` and above fills the bold slot, anything lighter fills regular |
+| `style`  | `normal` | `normal` or `italic`                                                |
+| `path`   | required | relative to the folder, and has to stay inside it                   |
+
+A face is left out, and the deck still written, when its license forbids embedding, when it is a variable font or a `woff` or `woff2` file, or when a second face lands in a filled slot. Supply static instances, one per weight, and the TrueType or OpenType file a `woff2` was compressed from.
+
+## What each slide declares
+
+A slide sets its place in the deck through attributes on `<body>`.
+
+| Attribute                               | Effect                                        |
+| --------------------------------------- | --------------------------------------------- |
+| `data-section="Results"`                | opens a section the slides after it stay in   |
+| `data-hidden`                           | hides the slide in the show                   |
+| `data-header="off"`                     | drops the header on this slide                |
+| `data-footer="off"`                     | drops the footer and its number on this slide |
+| `data-footer-left`, `-center`, `-right` | replaces that footer slot on this slide alone |
+| `data-header-left`, `-center`, `-right` | replaces that header slot on this slide alone |
+
+Once any slide opens a section, slides ahead of the first sit in a section named after the deck. A title the deck returns to after another section opens a new section numbered `Intro (2)`.
+
+A slide dropping one band keeps the other from the master. A slide replacing a slot draws its band as its own text, so a later edit in the master view skips it.
+
+## Motion
+
+| Attribute                  | Takes                           | Effect                                 |
+| -------------------------- | ------------------------------- | -------------------------------------- |
+| `data-transition`          | `fade`, `push`, `wipe`, `cover` | the transition into this slide         |
+| `data-transition-duration` | `500`, `500ms`, or `0.5s`       | rounded to 0.5, 0.75, or 1 second      |
+| `data-enter`               | `fade`, `fly`, `wipe`, `zoom`   | an entrance played on a click          |
+| `data-enter-order`         | a number                        | the click it plays on, lowest first    |
+| `data-enter-duration`      | `500`, `500ms`, or `0.5s`       | the entrance length, 500 ms by default |
+
+`data-transition` and `data-transition-duration` go on `<body>`. The `data-enter` family goes on the element.
+
+```html
+<body data-transition="fade">
+  <h1>Results</h1>
+  <div class="card" data-enter="fly" data-enter-order="1">…</div>
+  <div class="card" data-enter="fly" data-enter-order="2">…</div>
+</body>
+```
+
+- Each entrance is its own click, and entrances without an order play after the ordered ones, in page order.
+- An entrance brings in every shape drawn from its element and the elements inside it, so a card's box and text arrive together.
+- An inner element with its own `data-enter` waits for its own click.
+- Fly comes in from the bottom and wipe from the left.
+
+## The master
+
+The master takes its colors from the `<html>` element of the first slide, laid out with the project's token stylesheet injected:
+
+| Source                                       | Used for         |
+| -------------------------------------------- | ---------------- |
+| `--color-background`                         | the slide ground |
+| `--color-text`                               | the header text  |
+| `--color-muted`                              | the footer text  |
+| `--color-accent`                             | the slide number |
+| `<body>` font family, ` Variable` suffix cut | the theme face   |
+
+A role the project declares no token for falls back to the slide body's own color and prints one `✗` line naming it. It never falls back to the toolkit's palette.
+
+A slide whose `<body>` background differs from the master's keeps its own. A slide whose `<body>` computes a `--color-text` apart from the master's prints a `✗` line, since its bands keep the master's colors and may not read against its ground.
+
+## Speaker notes
+
+`<aside class="notes">` becomes the slide's notes and is never drawn. Each paragraph or list item becomes its own line, and markup is dropped.
+
+## Charts
+
+A `<figure data-chart="...">` holding a `<table>` becomes a native, editable chart where the figure was laid out. The table is not drawn as well.
+
+```html
+<figure data-chart="bar" data-labels>
+  <figcaption>Revenue by region</figcaption>
+  <table>
+    <tr>
+      <th>Region</th>
+      <th>Q1</th>
+      <th>Q2</th>
+    </tr>
+    <tr>
+      <td>North</td>
+      <td>12</td>
+      <td>16</td>
+    </tr>
+    <tr>
+      <td>South</td>
+      <td></td>
+      <td>11</td>
+    </tr>
+  </table>
+</figure>
+```
+
+- `data-chart` takes `bar`, `line`, `area`, `pie`, or `doughnut`.
+- The header row names the series and the first column names the categories.
+- An empty cell is a gap, not a zero. A comma is a thousands separator only where it groups in threes, as in `12,345.5`, so a comma-decimal `3,5` refuses.
+- `data-labels` shows each value, and a `<figcaption>` becomes the chart title.
+- Series take the accent first, then every other declared `--color-*` role in sheet order except the background and surface, repeating past the last.
+
+A refused chart, effect, or face is left out and the rest of the deck is written. Each prints a `✗` line, and the exit depends on the case:
+
+| Case                                                                    | Exit |
+| ----------------------------------------------------------------------- | ---- |
+| malformed or unknown `deck.json` field                                  | 1    |
+| `mark` path missing                                                     | 1    |
+| `fonts` path missing or outside the folder                              | 1    |
+| face that cannot embed                                                  | 0    |
+| unknown transition or entrance name                                     | 0    |
+| entrance on an element that draws nothing                               | 0    |
+| chart cell that is not a number, or `data-chart` off-list               | 0    |
+| token role not declared, or a slide body setting its own `--color-text` | 0    |

package/claude/skills/git-pr/references/evidence.md

@@ -31,7 +31,7 @@ A reviewer on the operator's machine can open the branch's running dev server, w
 canon pr local --json
 ```
 
-The verb reads the listening sockets on this machine, keeps those whose process runs inside this worktree, and reports the lowest port serving an HTML page. A server in another worktree or in the main checkout is never reported, since it shows a different branch. `canon docs pr-local` states the contract. Read `reason` on the record rather than the exit code.
+The verb reads the listening sockets on this machine, keeps those whose process runs inside this worktree, and reports the lowest port serving an HTML page. A server in another worktree or in the main checkout is never reported, since it shows a different branch. `canon pr local --help` states the contract. Read `reason` on the record rather than the exit code.
 
 - `ok`: hold the record's `url` for the evidence step below.
 - `no-server` or `no-listener-reader`: hold the reason for the closing report, pass no link, and move on. Do not start a server here, since one started inside the ship chain has no owner to stop it.
@@ -110,7 +110,7 @@ The evidence comment is already posted, so the reviewer has the screenshots whil
 canon pr preview <number> --json
 ```
 
-The verb dispatches the project's Pages deploy on the pull request's branch and waits on the run for up to 15 minutes. It refuses before dispatching anything when the deploy command passes no `--branch`, since that deploy would publish the branch to production, and when the workflow's own push path filter matches no path the pull request changed, since a dispatch ignores that filter and the site it published would show none of the change. `canon docs pr-preview` states the contract. Read `reason` on the record rather than the exit code.
+The verb dispatches the project's Pages deploy on the pull request's branch and waits on the run for up to 15 minutes. It refuses before dispatching anything when the deploy command passes no `--branch`, since that deploy would publish the branch to production, and when the workflow's own push path filter matches no path the pull request changed, since a dispatch ignores that filter and the site it published would show none of the change. `canon pr preview --help` states the contract. Read `reason` on the record rather than the exit code.
 
 - `ok`: re-render the evidence body with the address on the line under `## Evidence`, then post or update it exactly as the evidence step does, through the same tmp file and the `commentId` the record carries:
 

package/claude/skills/git-pr/references/final-command.md

@@ -54,7 +54,7 @@ case "$links" in
   printf 'Removed %s session link(s) from the live body of #%s.\n' "$links" "$pr_number" >&2
   ;;
 esac
-record=$(canon labels apply "$pr_number" --base "$base_branch" --json 2>/dev/null | tail -n 1)
+record=$(canon labels apply "$pr_number" --json 2>/dev/null | tail -n 1)
 if printf '%s' "$record" | jq -e 'has("earned")' >/dev/null 2>&1; then
   owed=$(printf '%s' "$record" | jq -r '.owed | join(",")')
   missing=$(printf '%s' "$record" | jq -r '.missingOnRemote | join(",")')

package/claude/skills/git-pr/references/labels.md

@@ -82,7 +82,7 @@ What it leaves unmeasured is a prefix reaching no path, so a row left behind by
 
 Apply labels after the pull request resolves, never as a field on the create. A create carrying a label the remote lacks either fails whole or creates the label, depending on the surface, and neither is the map's call. One step against a pull request that already exists covers the create and the edit path alike. It runs over REST, so it works where GraphQL is blocked, and the REST endpoint creates any label it is handed that the remote lacks, so the step reads each name off the remote first and warns on a missing one rather than adding it.
 
-`canon labels apply <number>` is that step. It resolves the earned set the way `canon labels audit` does, binds to the pull request only when its head is the current branch and it is open, and adds each earned label the pull request lacks. `--check` reports what is owed and writes nothing. The record carries `number`, `earned`, `present`, `added`, `owed`, `missingOnRemote`, and `uncovered`.
+`canon labels apply <number>` is that step. It resolves the earned set from the pull request's own files listing, or from the git range when `--base` is passed, binds to the pull request only when its head is the current branch and it is open, and adds each earned label the pull request lacks. `--check` reports what is owed and writes nothing. The record carries `number`, `earned`, `present`, `added`, `owed`, `missingOnRemote`, and `uncovered`.
 
 A pull request opened outside this skill, such as by `gh pr create`, takes the same command, since nothing else labels it.
 

package/claude/skills/git-pr/references/publish.md

@@ -44,7 +44,7 @@ A phase label is one way text names the board, and a path under a record root is
 
 Two shapes get past a reader scanning for a bare label. A code span quoting a label is still the label, so read a span whose whole content is one as a hit and leave a longer token inside a span alone, which is a fixture name rather than a reference. The second shape is a path under a record root, gitignored and therefore absent from every clone, so `.canon/feedback/` names a folder the remote's reader cannot open.
 
-Under the tracked `canon/` and `.claude/` folders there is no hit, since `canon/context/governance/rules.md` resolves everywhere. `.canon/` carries no such carve-out: one ignore line covers the root whole, so every path beneath it is a hit regardless of which folder names it.
+Under the tracked `canon/` and `.claude/` folders there is no hit, since `canon/context/surfaces/governance.md` resolves everywhere. `.canon/` carries no such carve-out: one ignore line covers the root whole, so every path beneath it is a hit regardless of which folder names it.
 
 Rewrite a hit to name what the reader can reach rather than deleting it. A row's subject stated plainly replaces its label, and what a record folder holds, said in a sentence, replaces its path.
 

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

@@ -26,6 +26,7 @@ A pass stops rather than repeat a verdict that already covers the head.
 - An open verdict at the head stops the same way, unless a `## Review response` or `## Post-review findings` comment is newer than it or the launch names an address
 - The hosted preview was not built from the head: stop and post nothing, naming `built`, `tip`, and `canon pr preview <number> --json` for the dispatcher
 - Post, then run `canon pr lift <number>` on a close. Never merge or ready the PR by hand, and edit the evidence comment only through `canon pr tick`.
+- A push after a close owes a re-drive only when it changed a painted path, since the lift carries the close across the rest.
 
 ## Step 1: resolve the pull request
 

package/claude/skills/role-orchestrator/references/orchestrator-handback.md

@@ -11,7 +11,7 @@ Read this at loop step 6, once the poll reports a branch stale or conflicted, or
 - Resolve the target at the moment of sending with `canon sessions list --branch`, never from a mapping written down earlier, since names rotate as sessions end and one recorded earlier in a session has failed inside the hour. `orchestrator-poll.md` routes on the count and the confidence it answers with
 - Open the message with the worktree and branch the sender believes the reader holds, asking to be corrected, whenever that mapping is inferred rather than confirmed
 - Name the skill for the reader to run rather than writing an invocation, which arrives as text
-- Read the pull request's own draft flag rather than the state a worker reports, and report what the read returned and when rather than the state alone. `canon docs pr-reads` states why a reported field can lag and say nothing about it. The flag settles the question only once the worker's chain has run its undo, and nothing marks that moment, so a read taken between the pull request opening and that call sees a genuinely ready pull request about to become a draft and has told an operator the opposite of what the worker had said.
+- Read the pull request's own draft flag rather than the state a worker reports, and report what the read returned and when rather than the state alone. `canon pr head --help` states why a reported field can lag and say nothing about it. The flag settles the question only once the worker's chain has run its undo, and nothing marks that moment, so a read taken between the pull request opening and that call sees a genuinely ready pull request about to become a draft and has told an operator the opposite of what the worker had said.
 
 ## The rebase handback
 

package/claude/skills/task-board/references/board.md

@@ -144,4 +144,4 @@ Add no fourth readiness group in place of this file. The three group names are t
 
 ## Validation
 
-`canon tasks validate` reads the board against the tree, and what it checks, what it refuses on, and what it reports are at `canon docs tasks-validate`. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on.
+`canon tasks validate` reads the board against the tree, and what it checks, what it refuses on, and what it reports are at `canon tasks validate --help`. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on.

package/claude/skills/task-board/references/tasks.md

@@ -171,7 +171,7 @@ The line is what lets a merge close its own task. `canon tasks archive --pull-re
 
 ## Archiving
 
-Never delete a task file. A shipped task moves to `.canon/tasks/archive/` under its own name, and the live index regenerates without it. `canon tasks archive` owns that move, and what it does and what it refuses on are at `canon docs tasks-archive`.
+Never delete a task file. A shipped task moves to `.canon/tasks/archive/` under its own name, and the live index regenerates without it. `canon tasks archive` owns that move, and what it does and what it refuses on are at `canon tasks archive --help`.
 
 The archive nests inside `.canon/tasks/` rather than sitting beside it as a flat `.claude/task-archive/`, which is what a binary predating this convention still writes. Meeting the flat sibling names an older checkout rather than a second archive to reconcile.
 

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

@@ -20,7 +20,7 @@ Report numbers. A sentence about what the source looks like is what this exists
 Read these in parallel from the project root, skipping any that do not exist:
 
 - `package.json`: the `scripts` block naming a dev, preview, or start command
-- `canon/context/development/`: the documented run commands and the port each serves
+- `canon/context/development/local-loop.md`: the documented run commands and the port each serves
 - `CLAUDE.md`: project type and conventions
 
 Prefer a production-shaped build (`preview`, `start`) over the dev server, since a dev server ships unminified modules and reports a cost no user pays.

package/docs/agents/audits.md

@@ -1,11 +1,12 @@
 ---
 title: Audits
-description: 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
+description: Running every health check as one set, the verdict and exit codes, the corpus states, the retained baseline and its delta, and a catalog of every audit verb with whether a finding gates
+kind: reference
 ---
 
 # Audits
 
-`canon audits run` runs every audit this repository owns, reports each one under a single verdict, and compares each count to the floor the last recorded run left behind. Nothing here is a new measure. Every number it prints comes from a verb that already published it, which is what makes the command cheap and what separates it from writing another check.
+`canon audits run` runs every audit this repository owns, reports each under one verdict, and compares each count to the baseline the last recorded run left. Every number comes from a verb in the catalog below.
 
 ```bash
 canon audits run
@@ -15,36 +16,11 @@ canon audits run --corpus tracked --corpus per-machine
 canon audits list --json
 ```
 
-| Option            | Behavior                                                                                                   |
-| ----------------- | ---------------------------------------------------------------------------------------------------------- |
-| `--json`          | Add a machine-readable record on stdout, keeping the frame                                                 |
-| `--root <path>`   | Measure this tree instead of the current worktree                                                          |
-| `--record`        | Write this run's tracked counts to `canon/config/baseline.json`                                            |
-| `--corpus <name>` | Limit the run to one corpus (`tracked`, `per-machine`, `upstream`), repeatable, defaulting to every corpus |
+`--record` writes the tracked counts to `canon/config/baseline.json`. `--corpus` limits the run to `tracked`, `per-machine`, or `upstream` and repeats. `--root <path>` measures another tree. `canon audits list` prints the catalog the run reads.
 
-## What it runs
+## Output
 
-Twenty-one verbs, listed by `canon audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
-
-The verbs walk separate trees and share no state, so they run together. Measured on the authoring machine at twelve verbs, a run finished in 0.8 seconds of wall clock against 4.4 seconds of processor, which is under every other stage in `bun run check`. `canon deps audit` is the one that changes that reading, since it reaches a network rather than a tree and its latency is the index's rather than this machine's: three clean runs measured 44.7, 77.6, and 62.9 seconds, and a stalled lookup runs to an explicit 120-second timeout rather than to bun's own 299-second ceiling. `--corpus` is what keeps a caller from paying that cost when it wants only the corpora on this disk.
-
-Eighteen of the twenty-one read a tree on this disk, the one added by `restated.md` and the one added by `census.md` among them, since the first reads four such trees against each other and the second counts every file in one. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction, and the one added by `label-coverage.md` reads a branch range against a map the project declares.
-
-The placement entry runs `canon context classify sweep` pinned to `--backend off`, so it reads the regex layer alone whatever classifier setting the project resolves. A count that moves with whichever model a machine runs is not comparable across clones, and the model layer turned a sub-second read into one measured at about 17 minutes over this repository's context sections on the authoring machine. It retains one tally per verdict, `keep`, `rewrite`, and `move`, and gates on nothing, since each verdict is a judgment. `document-health` is the surface that reads the same sections with the model.
-
-Each is invoked as the CLI the caller is running rather than as a global `canon`. A globally installed binary resolves to the main checkout no matter which worktree is executing, so the aggregate would measure a tree the branch never touched and report a pass over it.
-
-## What gates and what reports
-
-Five findings fail the run: an unresolved context citation, a banned character, a relative link resolving to nothing on disk, a skill folder carrying no `REQUIREMENT.md`, and a credential-shaped value in the tree the package ships. Each is a fact with no false-positive class behind it.
-
-Four of the five are the ones `canon gate run` already fails a push on. The secret scan is the one entry gating without a stage behind it, added on that same fact-or-judgment test rather than as a side effect of registering a measure, and the toolkit already ranks content leaving the repository above content that stays.
-
-Everything else reports. A heavy bullet, a long entry, a board row nothing resolves, a degradation term in a comment, and an implementation reaching history ahead of its test are judgments a reader settles. A push failing on one of those teaches contributors to route around the stage, which is the split recorded across every audit here and the one this command inherits rather than moves.
-
-Growth against the baseline reports too. The standards behind the largest measures set no hard cap, so a count that rose is a fact about the corpus and a judgment about whether it matters.
-
-## Exit codes
+`summary.verdict` is `clean`, `reported`, `findings`, or `incomplete`. Every run also states how many corpora it measured against how many it skipped.
 
 | Code | Meaning                                                              |
 | ---- | -------------------------------------------------------------------- |
@@ -53,52 +29,77 @@ Growth against the baseline reports too. The standards behind the largest measur
 | `2`  | An audit carries a finding that is a fact                            |
 | `3`  | An audit did not report, so the run measured less than the whole set |
 
-`3` is a defect in the run rather than in the tree, which is why it takes a code of its own. An aggregate reporting a pass over a set it never finished measuring is the failure the command exists against, so an unparseable record, a verb that could not be started, and an exit no verb documents all land there instead of quietly counting as clean. The `markdown audit` empty-ban-set exit is the precedent: a corpus walked with nothing looked for is a broken check, not a clean tree.
-
-The verdict is published as a field as well as an exit code. A reader branching on `summary.verdict` gets `clean`, `reported`, `findings`, or `incomplete` without inferring the difference between a quiet corpus and one nobody finished measuring.
-
-### An absent corpus is not an unmeasured one
-
-A per-machine folder that is not on this disk reports as `absent` and moves neither the verdict nor the exit code. Every one of those folders is gitignored, so a fresh clone and every CI run carry none of them, and counting six expected absences as failures pins the verdict at `incomplete` forever. A signal that never changes is one nobody reads after the second time they see it.
-
-Which refusals count as an absence is declared per audit rather than inferred from the corpus alone. A per-machine corpus counts a missing folder. An upstream corpus counts every reason the advisory verb publishes, since each of the three means there is nothing resolved to measure. Several tracked audits override that default too, wherever the corpus not being there is the ordinary state of a target rather than a broken checkout: the secret scan for a project that publishes nothing, the skill corpora, the citation reach check, and the routing measure for a project holding no skills tree, and the context audit for a project that adopted none of the folders it measures.
-
-Everything else stays `unmeasured`. That covers a tree git cannot list, which is a broken checkout, and a package declaring no `files` field, where a publish would pack the whole tree and the scan read none of it. Both are a corpus that exists and went unread, so softening either would report a pass over a shipped tree nobody measured.
+Code `3` marks a defect in the run rather than in the tree. An unparseable record, a verb that could not start, and an undocumented exit all land there.
 
-Each override exists because the corpus answers the wrong question for that audit. The secret scan earns its from `private: true`, the one declaration that a package is never published, so a project carrying it reports an absent corpus rather than a broken one. Without that the aggregate would report `incomplete` in every such project on every run, which is the permanent signal this section opens by rejecting.
+Four findings gate, being an unresolved context citation, a banned character, a skill folder with no `REQUIREMENT.md`, and a credential-shaped value in the shipped tree. Everything else reports, and growth against the baseline reports too.
 
-`upstream` is the third corpus value, carried by the advisory check alone. Its count moves when someone publishes rather than when someone edits here, so it is kept out of the retained baseline for the mirror image of the reason gitignored scratch is, and an offline run reports it absent rather than pinning the verdict at `incomplete` on every machine without a network.
+**Corpus states.**
 
-Every run states how many corpora it measured against how many it skipped, including a run with no findings at all. A count of what passed reads as a verdict on the whole set unless the run also says what it never reached.
+An audit that finds no corpus reports `absent`, which moves neither the verdict nor the exit code. Anything unread that should exist is `unmeasured`, which sets `incomplete` and exit `3`.
 
-### What a shallow checkout changes
+- A per-machine folder missing from this disk is `absent`
+- `upstream` is `absent` offline, and stays out of the baseline
+- The secret scan reports `no-manifest`, `no-publish`, and `no-shipped-files` as `absent`, and `no-files-field` and `no-git` as `unmeasured`
+- The skill audits, the citation reach check, and the routing measure report `absent` for a project with no skills tree
+- The context audit reports `absent` for a project that adopted none of its folders, and a tree git cannot list is `unmeasured`
 
-`canon gov test-order` scopes its range against the trunk and falls back to the root commit when no trunk ref resolves. A depth-1 checkout has neither, so the range is empty and the verb reports zero of everything rather than refusing. The numbers are real for the history present, which means a shallow run under-reports against a baseline taken from a full clone and shows as shrinkage. That is the safe direction, and it is the reason a `test-order` delta is worth reading only from a clone carrying the history.
+**Baseline.**
 
-## The retained baseline
+`canon/config/baseline.json` holds the counts from the last `--record`, with the day and the commit. It falls back to `.claude/canon/baseline.json` for a project that has not moved. Each run reports which counts moved and by how much.
 
-`canon/config/baseline.json` holds the counts from the last run recorded with `--record`, alongside the day it was taken and the commit it was read at, falling back to `.claude/canon/baseline.json` for a project that has not moved. Each later run reports which counts moved and by how much.
+- A run with no baseline says so rather than showing a delta of zero
+- A key on one side only is named as new or gone
+- A per-machine record and the task board are reported every run and never recorded
+- An audit that did not report is left out, never written as zero
+- A baseline that does not parse refuses the run
 
-The file is committed. A per-machine record cannot answer the question this half exists for, which is whether a number grew since anyone last looked, and a fresh checkout has to inherit that answer rather than start over. The cost is that a branch moving a count either fixes it or re-records it and says why, which is the shape the consumed-copy assertion already carries.
+`gov test-order` reads zero in a shallow clone, so read its delta only from a clone carrying the history.
 
-It sits under the project root rather than beside the aggregator in `src/`. The numbers describe one repository's corpus, and `src/` ships to every project that installs the CLI, so a baseline in the package would hand a target these counts to measure its own tree against.
+**In `bun run check`.**
 
-### What is kept out of it
+`bun run check` runs `--corpus tracked --corpus per-machine` as a reporting stage after the gating stages, and never fails on it. `summary` is a flat object of unique scalar keys that a shell stage greps without a JSON parser. `deps` runs weekly instead.
 
-A gitignored record folder holds one machine's session scratch. Its counts describe somebody else's disk, so committing them writes a floor no other clone can reproduce and every contributor reads a regression against a number that was never about their tree. The board and every record kind are therefore reported on every run and recorded in none.
+The placement entry runs pinned to `--backend off`, so its tally stays comparable across machines. Each audit runs as the CLI the caller is running, never a global `canon`.
 
-An audit that did not report is left out rather than written as zero. Zero there records a clean corpus nobody measured, and the next run reads its real numbers as a regression against a floor that was never taken.
+**Catalog.**
 
-### The first run
+`canon audits list` reports the first 19 rows. The rows marked `outside` run by hand or from a skill and sit beside the aggregate.
 
-A run with no baseline behind it says so rather than showing a delta of zero. Those two states say the same thing to a reader and mean opposite things, which is a defect this repository has already had to fix twice elsewhere. The same reasoning covers a check the baseline never recorded, a key the run produced that the record does not carry, and a key the record carries that this run did not produce. Each is named for what it is.
+| Id                   | Verb                                | Measures                                                                           | Finding        |
+| -------------------- | ----------------------------------- | ---------------------------------------------------------------------------------- | -------------- |
+| `context`            | `canon context audit`               | Context folder structure, citations, and the requirements record's word cap        | Gates          |
+| `placement`          | `canon context classify sweep`      | Keep, rewrite, and move tally per context section, regex layer only                | Reports        |
+| `markdown`           | `canon markdown audit`              | Bans, dead links, density, and reference shape                                     | Gates          |
+| `skills`             | `canon claude skills audit`         | Both skill corpora against the skill standards                                     | Gates          |
+| `skills-reach`       | `canon claude skills reach`         | Skill bodies citing a path no target receives                                      | Reports        |
+| `skills-rank`        | `canon claude skills rank`          | Whether skill descriptions separate against a routing case corpus                  | Reports        |
+| `tasks`              | `canon tasks validate`              | Board rows nothing resolves                                                        | Reports        |
+| `records-plans`      | `canon records validate plans`      | Plan records against their shape                                                   | Reports        |
+| `records-groundwork` | `canon records validate groundwork` | Groundwork folders against their shape                                             | Reports        |
+| `records-intake`     | `canon records validate intake`     | Intake folders against their shape                                                 | Reports        |
+| `records-teach`      | `canon records validate teach`      | Teach records against their shape                                                  | Reports        |
+| `comments`           | `canon comments scan`               | Comment density by language and kind, and `TODO`, `FIXME`, `HACK`, `XXX`           | Reports        |
+| `test-order`         | `canon gov test-order`              | Implementations that reached branch history before their test                      | Reports        |
+| `secrets`            | `canon secrets scan`                | Credential-shaped values in the shipped tree                                       | Gates          |
+| `labels`             | `canon labels audit`                | Changed paths no row of the label map reaches                                      | Reports        |
+| `restated`           | `canon gov restated`                | Instructions `CLAUDE.md` states that a second surface states too                   | Reports        |
+| `counts`             | `canon gov counts`                  | Sentences stating a closed catalog's size that disagree with the tree              | Reports        |
+| `census`             | `canon census`                      | File count, extension breakdown, and line total                                    | Reports        |
+| `deps`               | `canon deps audit`                  | Advisories against the resolved dependencies                                       | Reports        |
+| `outside`            | `canon gov citations`               | Rule citations and internal frontmatter globs reaching nothing                     | Gates in check |
+| `outside`            | `canon gov superseded <old> <new>`  | Where the tree still asserts a value a changed convention no longer produces       | Reports        |
+| `outside`            | `canon claude skills drift <ref>`   | Shipped skill bodies rewritten since a ref                                         | Reports        |
+| `outside`            | `canon claude routing`              | Per `CLAUDE.md` section, how many bullets name a path and whether a rule covers it | Reports        |
+| `outside`            | `canon context classify diff`       | Classification of the chunks a git range changed                                   | Reports        |
 
-A hand-edited baseline that does not parse refuses the whole run. Reading a broken record as an absent one would reset the floor the file exists to hold, silently.
+A deliberate secret takes a `canon-allow-secret: <reason>` marker. A deliberate citation takes `canon-allow-citation: <reason>` and a deliberate superseded value takes `canon-allow-superseded: <reason>`, each on its own line or the one above. Run any verb with `--help` for its flags and refusal reasons.
 
-## In the verify pipeline
+## Refusals
 
-`bun run check` runs a reporting stage after the three gating stages, and never fails on it. Those three stages keep their own specific remedies, so the aggregate reports the rest and the growth, and a fact still fails the push at the stage that names what to do about it.
+- A baseline that does not parse
+- A `--root` that is not a tree git can list
 
-The stage runs `--corpus tracked --corpus per-machine` rather than the full set, so `deps` and its network latency sit outside the gate entirely. A weekly job reads the advisory index instead, on a schedule rather than on every push. `summary.audited` in the gate's own record therefore reads 19 against the 20 `canon audits run` reaches with no filter.
+## See also
 
-The stage reads `summary`, a flat object of scalars published beside the nested arrays. Every key in it is unique across the whole record, so a shell stage greps one out without a JSON parser. The three verbs the gating stages already ran walk their trees a second time here, which is the 0.8 seconds measured above and the reason the scoped set runs rather than only the part those stages skip: one verdict over the corpora describing this tree is the value, and a stage measuring a narrower subset would report a health nobody took.
+- `markdown-audit.md`: the markdown audit
+- `context-audit.md`: the context audit