@erclx/canon 5.60.0 → 5.62.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [5.62.0](https://github.com/erclx/canon/compare/v5.61.0...v5.62.0) (2026-10-24)
+
+
+### Features
+
+* **governance:** cover more WCAG criteria in the ui rules ([#2677](https://github.com/erclx/canon/issues/2677)) ([25b6190](https://github.com/erclx/canon/commit/25b619039aa3656e239385713f796c5e34810485))
+* **governance:** name the partner of a split rule on sync ([#2681](https://github.com/erclx/canon/issues/2681)) ([1d6703e](https://github.com/erclx/canon/commit/1d6703e74deb7968b0121b5e3148e474ed836c89))
+* **tooling:** let a project decline or customize one golden file ([#2675](https://github.com/erclx/canon/issues/2675)) ([41c5ec0](https://github.com/erclx/canon/commit/41c5ec042a8d50b968e853a175f45eac5a59703c))
+
+## [5.61.0](https://github.com/erclx/canon/compare/v5.60.0...v5.61.0) (2026-10-24)
+
+
+### Features
+
+* **design:** check themes and add a review point ([#2673](https://github.com/erclx/canon/issues/2673)) ([8cdaa5c](https://github.com/erclx/canon/commit/8cdaa5c001b2d783108c5ce6d70da0b6cca0719c))
+* **driver:** add an axe probe that gates the UI review ([#2672](https://github.com/erclx/canon/issues/2672)) ([785e474](https://github.com/erclx/canon/commit/785e474b76eae4f41a55fd588df0b3691756742d))
+* **migrate:** drop a covered ignore line from the records sweep ([#2668](https://github.com/erclx/canon/issues/2668)) ([188bee8](https://github.com/erclx/canon/commit/188bee8c0061045e46e660da50422b5d5673cf14))
+
+
+### Bug Fixes
+
+* **markdown:** measure a bullet without its list marker ([#2670](https://github.com/erclx/canon/issues/2670)) ([c7b9d70](https://github.com/erclx/canon/commit/c7b9d70fc522a91dc9b2b058481d1eb984abd3ad))
+
 ## [5.60.0](https://github.com/erclx/canon/compare/v5.59.0...v5.60.0) (2026-10-24)
 
 

package/README.md

@@ -104,7 +104,7 @@ Working with an agent rather than reading this yourself? It loads `CLAUDE.md` at
 - [Operating model](docs/workflow/operating-model.md): orchestrator, planner, and worker roles for building across parallel sessions
 - [Skill map](docs/workflow/skill-map.md): plugin skills grouped by the moment a project meets them
 - [Skill map on request](docs/workflow/skill-map-on-request.md): plugin skills that serve a request rather than a moment
-- [Visual design workflow](docs/workflow/visual-design-workflow.md): tiered guide for design authoring
+- [Visual design workflow](docs/workflow/visual-design-workflow.md): how canon plans, builds, and reviews a UI
 - [Target projects](docs/target/projects.md): scaffold, add a domain later, sync upstream drift
 - [Agents](docs/agents/index.md): CLI flags, exit codes, and JSON output shapes
 - [Docs index](docs/index.md): every reference doc in this repo

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.60.0",
+  "version": "5.62.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canon-cli/SKILL.md

@@ -83,7 +83,8 @@ Read the doc each line names before running one of these. `canon docs install-an
 
 - `canon sync` runs every installed domain's sync, so it carries each risk below.
 - `canon gov sync` replaces a rule you edited and deletes a rule the toolkit retired, edited or not.
-- `canon tooling sync --write` replaces every golden config a stack ships. Seeds are copy-once. Nothing writes without the flag. See `canon docs sync`.
+- `canon tooling sync --write` replaces a golden config canon changed and holds one you edited until `--replace <path>` names it. Nothing writes without the flag. See `canon docs sync`.
+- `canon tooling inject` replaces every golden config a stack ships, skipping only a declined or customized path.
 
 ### Migrate and indexes
 

package/claude/skills/design-identity/references/card-route.md

@@ -21,11 +21,11 @@ Check for a `card.config.mjs` with a `card-src/pages/og-card.astro` beside it. W
 
 ```plaintext
 No card route installed, so the card shipped as a PNG this run.
-`canon tooling sync astro . --write` installs the route, and it replaces every other
-golden config in the astro stack, so run it when you mean to sync the stack.
+`canon tooling sync astro . --write` installs the route, and it writes the astro
+stack's new and stale configs, so run it when you mean to sync the stack.
 ```
 
-Never run that sync to obtain the route, since it copies the whole stack over the project's own framework, lint, typescript, and test configs. Never hand-write the scaffold either, since a copy written here drifts from the one the stack maintains.
+Never run that sync to obtain the route, since it writes the stack's configs beside the project's own framework, lint, typescript, and test configs, holding only the ones the project edited. Never hand-write the scaffold either, since a copy written here drifts from the one the stack maintains.
 
 ## Writing and capturing the route
 

package/claude/skills/design-record/references/design.md

@@ -14,6 +14,7 @@ Applies to `canon/DESIGN.md`. Captures visual intent and the decisions behind ho
 - [What goes in](#what-goes-in)
 - [What does not go in](#what-does-not-go-in)
 - [Format](#format)
+- [Frontmatter](#frontmatter)
 - [Prose budget](#prose-budget)
 - [Sections](#sections)
 - [The uncertainty tag](#the-uncertainty-tag)
@@ -56,6 +57,17 @@ Everything below applies to both shapes unless it names one.
 - Plain English over technical notation. If a section could be removed and the developer would still build correctly from the stylesheet and code alone, remove it.
 - Keep table headers and role names intact so the parser can read the tables.
 
+## Frontmatter
+
+Both fields are optional, and a record without them audits as it always did. Frontmatter never counts toward the prose budget.
+
+- `themes:` lists each theme as the stylesheet prelude that opens it, such as `:root` or `@media (prefers-color-scheme: dark)`.
+- `canon design audit` checks every color property `## Colors` names against each theme, and reports a theme that omits one or opens no block.
+- `reviewed:` is the day the record was last read whole, as `YYYY-MM-DD`. `canon records stale canonical` returns it with the releases tagged since.
+- No skill step sets `reviewed:`, so whoever reads the record whole updates it.
+
+Quote style and spacing may differ between the record and the stylesheet. A declaration inside a declared media query counts for the query alone, and `:root` never matches `:root[data-theme='dark']` by containment. A values record renders `reviewed:` from its token module and declares no `themes:`.
+
 ## Prose budget
 
 The record is a lookup, so its prose stays short enough to scan. Why a rule was chosen belongs in the project's context entry for design, never here.
@@ -113,6 +125,13 @@ A prose section takes its uncertainty inline instead, in a sentence saying what
 The template is the intent record. The column headers are read by exact key, so they stay verbatim. Row names are not, which leaves a project free to rename a role, add one, or drop one it has no use for.
 
 ```markdown
+---
+themes:
+  - ':root'
+  - ":root[data-theme='dark']"
+reviewed: YYYY-MM-DD
+---
+
 # Design
 
 Values live in `<path to the stylesheet>`. This record holds the intent behind them.

package/claude/skills/document-health/REQUIREMENT.md

@@ -17,7 +17,7 @@ Length, placement, and staleness answer to different evidence, and one list hand
 - Propose a split or an owner as a structure line for each overgrown entry and doubled or unnamed coverage finding, with the headings and the reason
 - Ship the staleness axis as a reading rather than cutting it for lacking a verb
 - Report a refusal, an absent key, or a missing subcommand as an unread axis naming the cause, and say which layer answered the classifier sweep
-- Run standalone, reading the requirements record for drift with its reminder, and the design record through `canon design audit --json`, routing its findings to `design-record`
+- Run standalone, reading the requirements record for drift with its reminder, and the design record through `canon design audit --json` and its review reminder, routing findings to `design-record`
 
 ## Must not
 

package/claude/skills/document-health/SKILL.md

@@ -68,7 +68,7 @@ A refusal, an absent key, and a subcommand the project's binary does not carry e
 canon design audit --json
 ```
 
-The record carries `prose`, the lines past the budget with their counts, and `tokens`, the custom properties the stylesheet does not declare. `${CLAUDE_SKILL_DIR}/references/axes.md` holds how each reads and where it routes. Skip the verb when the scope excludes the record or the record is `null`.
+The record carries `prose`, the lines past the budget, and `tokens`, the custom properties the stylesheet lacks. Where the record declares `themes:`, `tokens.themes` adds one cell per theme. `${CLAUDE_SKILL_DIR}/references/axes.md` holds how each reads and where it routes. Skip the verb when the scope excludes the record or the record is `null`.
 
 ## Step 3: read the staleness axis
 
@@ -76,15 +76,15 @@ No verb answers whether a document still describes the tree it was written about
 
 Mark every staleness finding as a reading. It is this session's judgment rather than a measurement, and a report that sets it beside two verb-backed axes without marking it implies evidence the axis does not carry.
 
-### The requirements record
+### The review points
 
-When the scope reaches `canon/REQUIREMENTS.md`, read it for identity drift as well as for stale paths, and take the review point from the verb:
+When the scope reaches `canon/REQUIREMENTS.md` or `canon/DESIGN.md`, take the review point for each record the scope reaches from the verb:
 
 ```bash
 canon records stale canonical --json
 ```
 
-The doc in the record carries `reviewed` and `releasesSince`. `${CLAUDE_SKILL_DIR}/references/axes.md` holds the identity claim shapes to test and how the record reads. Skip both the read and the verb when the scope excludes the doc.
+Each doc in the record carries `reviewed` and `releasesSince`. Skip the verb when the scope reaches neither record. When the scope reaches the requirements record, also read it for identity drift as well as stale paths, with the claim shapes in `${CLAUDE_SKILL_DIR}/references/axes.md`.
 
 Nothing triggers this review but a request. A finished review hands the rewrite to the operator, and its last edit sets `reviewed:` in the doc's frontmatter to the day the operator's answers landed. This run writes neither.
 
@@ -118,6 +118,7 @@ When Step 3 read the canonical records, add one reminder line per doc the verb r
 
 ```markdown
 `canon/REQUIREMENTS.md`: reviewed <date>, <n> releases since.
+`canon/DESIGN.md`: reviewed <date>, <n> releases since.
 ```
 
 Write `reviewed value is not a date: <value>` for a doc carrying `invalidReviewed`, and `no release tags to count` in place of the count when `tagged` is false. Name the unread cause instead when the verb refused or the binary carries no `canonical` kind.
@@ -136,7 +137,7 @@ Keep the evidence line under the table on every run. A table read without it fla
 
 When Step 2 read the design record, add a row for `canon/DESIGN.md`, with both findings `measured`.
 
-- Put the `prose` findings in the Length cell and the `tokens` findings in the Placement cell
+- Put the `prose` findings in the Length cell and the `tokens` findings in the Placement cell, naming the selector of each `tokens.themes` cell that omits a property or matched no block
 - Write `unread: <reason>` in the Placement cell when `tokens.status` reads `unchecked`, since a check that could not run is no pass
 - Write `n/a: <reason>` there when it reads `not-applicable`, a values record with no property to compare
 - Route every finding to `design-record`, never to `document-repair`

package/claude/skills/document-health/references/axes.md

@@ -89,6 +89,8 @@ The record is exempt from the length and placement verbs above, so this is the o
 - `tokens.status: "not-applicable"`: a values record, which carries `Value` where an intent record carries `Property`. Report it as not applicable with the `reason`.
 - `record: null`: the project holds no design record, so there is nothing to report
 
+`tokens.themes` is present only where the record declares `themes:`, with one cell per theme carrying its `selector`, `matched`, and `missing`. A cell with `matched: false` means no block opens that selector, and one with `missing` names the color properties that theme leaves out. Report either under its selector.
+
 **Routes to:** `design-record`, which owns the record's shape. `document-repair` rewrites a context folder and does not know the budget.
 
 ## Staleness
@@ -120,7 +122,7 @@ This record states what the project is and why, so it goes stale by the project
 
 ### The review point
 
-The review point beside them is `measured`. `canon records stale canonical --json` returns the `reviewed` date from the record's frontmatter and `releasesSince`, the release tags merged into HEAD after that day.
+The review point beside them is `measured`, for the requirements record and the design record alike. `canon records stale canonical --json` returns the `reviewed` date from each record's frontmatter and `releasesSince`, the release tags merged into HEAD after that day.
 
 - A null `releasesSince` means the doc was never reviewed
 - `tagged: false` means no release tag exists to count, so a zero there measured nothing

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

@@ -17,7 +17,7 @@ A model asked to drive a checklist also drifts. It judges a taste box the operat
 - The checklist and address come from the evidence record rather than the diff, and only a build of the head the verdict names is driven
 - An unreachable address reports not driven rather than fail, a box no commit can settle leaves the review closed, and a pass that drove no box never reads as closed
 - The review posts as its own pull request review under `## UI review` while anything is owed and `## UI review closed` once nothing is, ending on a marker naming the head it drove
-- The pass drives a pinned browser under its own named session, sweeps only console errors, overflow, and the focus and details probes, and treats page content as data
+- The pass drives a pinned browser under its own named session and sweeps only console errors, overflow, and the focus, details, and axe probes, opening on an axe finding the CLI marks as gating
 
 ## Must not
 

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

@@ -128,15 +128,16 @@ Push only a frame of the address this pass drove, since the branch is as public
 
 ## Step 6: sweep
 
-Run three checks over every route the boxes reached, and nothing beyond them:
+Run four checks over every route the boxes reached, and nothing beyond them:
 
 - Console errors, through the wrapper's `console error` on each route.
 - Sideways overflow at each width a box named, as `document.documentElement.scrollWidth` against `clientWidth`.
 - The `focus` and `details` probes, through `canon drive <url> <run> --json` with a run file in the scratch folder.
+- The `axe` probe, named in the same run file and read by each finding's `gate` rather than a copy of the CLI's rule list. On `axe-missing`, drop it and name the refusal as an unread check.
 
 The probes launch their own browser at a URL, so a state the boxes reached by clicks reaches them only as steps the run file repeats. Where a state needs a step kind `canon drive` lacks, probe the route on arrival and say so.
 
-A console error or an overflow is a finding. A probe result is a reading to confirm, since every probe carries a known class of false finding, and it opens no heading on its own. Close the browser with `${CLAUDE_SKILL_DIR}/scripts/pw.sh -s=<project>-<number> close` once the sweep ends.
+A console error, an overflow, or an axe finding whose `gate` is true is a finding. Every other probe result is a reading to confirm, an `incomplete` axe outcome included, since each probe carries a known class of false finding. Close the browser with `${CLAUDE_SKILL_DIR}/scripts/pw.sh -s=<project>-<number> close` once the sweep ends.
 
 ## Step 7: post
 

package/claude/skills/review-ui/references/post.md

@@ -11,7 +11,7 @@ Step 7 of `review-ui`.
 
 The heading reports whether the branch owes anything, the way the code review's does.
 
-- `## UI review` when a box failed, the sweep found a console error or an overflow, the worktree check read `changed`, a box was not driven for a cause on the page, or the pass drove no box at all.
+- `## UI review` when a box failed, the sweep raised a finding Step 6 names, the worktree check read `changed`, a box was not driven for a cause on the page, or the pass drove no box at all.
 - `## UI review closed` otherwise.
 
 A needs-eyes box leaves the review closed, and so does a box not driven for a cause off the page, such as an address that did not answer or a `(local only)` box on a hosted preview, as long as something else was driven.
@@ -77,7 +77,7 @@ Driven at `<short-sha>` on <address>, rendered by <renderer>.
 
 **Sweep**
 
-- <route>, <width>: <console error, overflow, or probe reading to confirm>
+- <route>, <width>: <console error, overflow, axe gate finding with its rule, or probe reading to confirm>
 
 **Guessed wording**
 

package/claude/skills/target-update/SKILL.md

@@ -68,6 +68,8 @@ Target update: `<path>`, canon `<installed>` to `<running>`.
 
 **Drift:** <each non-empty cause from sync --check, with its count and paths>
 
+**Tooling holds:** <each tooling config the write would hold, being a drifted entry whose `cause` is `edited` or `unattributed`, then each `dispositions` entry, declined ones by path and customized ones marked when `moved` is true, or omitted when none>
+
 **Where it lands:** <the linked worktree this run is already in, or the worktree `.claude/worktrees/<name>/` it will enter, or the branch it will create in place when the operator declines a worktree>
 
 **Calls for you:** <each judgment call below this run meets, with the default this skill takes>
@@ -122,7 +124,13 @@ The record tree is untracked, so a `record-tree` rewrite has no undo. Run `canon
 
 ## Step 5: sync
 
-Run `canon sync .`, then `canon tooling sync <stack> . --write` when the tooling diff named files to change. Treat each drift cause the way the preview stated:
+Run `canon sync .`, then `canon tooling sync <stack> . --write` when the tooling diff named files to change. The write holds every config the preview listed under tooling holds.
+
+- Add `--replace <path>` only for a held path the operator named in the reply, never for the whole list the write prints
+- Offer `canon tooling customize <path>` for a held path the operator wants kept, and `canon tooling lift <path>` for a moved customized one they want to take
+- Leave a declined path alone, since no write reaches it
+
+Treat each governance drift cause the way the preview stated:
 
 | Cause                       | This skill                                                                                       |
 | --------------------------- | ------------------------------------------------------------------------------------------------ |

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

@@ -13,7 +13,7 @@ A file under a gitignored folder is unreadable to a pull request reviewer, and a
 
 ## Must
 
-- Every change is split into visual-only and automatable before anything is written
+- Every change is split into visual-only and automatable before anything is written, and a behavior the review's engine cannot read, such as a keyboard trap, gets a box of its own
 - The checklist covers the visual-only half, each item an action and the result a person looks for, with its route, width, and a `(taste)` or `(local only)` marker where one applies
 - Every automatable change shipping with no test is named, with the layer `test-craft` would place it at, in the same file
 - The file is written to the `.canon/tmp/handoff/ui-checklist/<slug>.md` handoff at the main worktree root, overwriting

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

@@ -46,6 +46,18 @@ When the plan cites `canon/design/<surface>/` under `**Design references:**`, na
 
 The checkbox stays `- [ ]` followed by the action and the result, since the evidence comment reads boxes by that shape. Only the UI reviewer ticks a box, stamping it with the commit it passed at, and the comment carries that tick forward only while the head it names is current.
 
+## Boxes no engine reads
+
+The UI review runs axe over every route it reaches, so a box restating what axe checks, such as contrast, a missing name, or a page title, adds a drive and catches nothing. Derive a box instead for each behavior below that the changed surface carries:
+
+- **Hover content.** Content shown on hover or focus stays while the pointer moves onto it, and Escape dismisses it, per WCAG 1.4.13.
+- **Keyboard trap.** Tab and Shift+Tab leave every widget the change added, per WCAG 2.1.2.
+- **Outside press.** A menu, popover, or dialog the change added closes on a press outside it and when focus leaves it.
+- **Change on input.** Choosing an option or typing changes no route and moves no focus until the person submits, per WCAG 3.2.2.
+- **Clipped focus ring.** Tab to each control the change added and judge from the capture whether a parent clips its ring, per WCAG 2.4.7.
+
+Write each in the box shape above, naming the control. A surface carrying none of these behaviors takes no derived box.
+
 ## The missing-test list
 
 Name every automatable change this branch ships with no test, one per line, with the layer `test-craft` would place it at. Do not write the test or read the project's test config to write one against.

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

@@ -36,7 +36,7 @@ For each surface, look for:
 3. **Inconsistencies**: spacing, tone of voice, interaction patterns, icon use, keyboard affordances
 4. **Roughness in daily use**: friction, redundant steps, unclear affordances, ambiguous labels
 
-Use `canon/DESIGN.md` as ground truth for intent where it exists. Observations only, no implementation suggestions or fixes.
+Use `canon/DESIGN.md` as ground truth for intent where it exists. Observations only, no implementation suggestions or fixes. Take what consistent interaction means from the `ui` rules in `.claude/rules/`, and skip that when the project installed none.
 
 Where Step 1 found a committed capture for this surface, judge composed output (spacing, overlap, contrast, wrapping) against it rather than inferring layout from markup. Where none exists, judge from source and say so in that surface's findings, since a source read cannot see what only a render shows.
 

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

@@ -32,7 +32,7 @@ A flat installed-rule layout makes `gov sync` report "No governance surfaces fou
 - A retired `.claude/GOV.md` is removed
 - A binary older than the stamp holds every rule it has no source for and asks for an upgrade
 
-After a rename the new name shows as `missing` when the stamp records a stack, and `gov install <stack>` adds it.
+After a rename the new name shows as `missing` when the stamp records a stack, and `gov install <stack>` adds it. A partner `governance/splits.toml` names shows as `missing` when the tree holds the split rule and lacks the partner, and `gov install --add <partner>` adds it.
 
 `canon gov regen [--root <path>]` runs against the toolkit root alone. It rewrites `.claude/rules/canon/` and `.claude/rules/internal/` from `internal/`, and exits 1 when the record names something that does not resolve.
 
@@ -68,6 +68,40 @@ After a rename the new name shows as `missing` when the stamp records a stack, a
 - `present` marks a copy an earlier sync left, which is reported and never deleted
 - `canon tooling sync <stack> [target]` writes only under `--write`. `--check` reports and exits 0, and a headless run with neither flag exits 1.
 
+### Drift cause and the write hold
+
+A `drifted` entry in `configs` carries a `cause`, read against the golden hash the last write recorded for that path.
+
+- `stale`: the target still hashes to the record, so canon moved and the project did not. `--write` replaces it.
+- `edited`: the target no longer hashes to the record. `--write` holds it.
+- `unattributed`: no hash is recorded, as on every target synced before hashes existed. `--write` holds it.
+
+A config no stack in the recorded chain ships is a first install and is never held, so a fresh scaffold takes every golden config of a stack new to it, even after `canon init` recorded `base`.
+
+A held path stays drifted, so the next headless run still exits 1. Pass `--replace <path>` once per path to take the golden copy, as the command the write prints does. A `--replace` naming no config the chain writes refuses with `unknown-replace`.
+
+### Dispositions
+
+`decline <path> [target] [--reason <text>]`, `customize <path> [target]`, and `lift <path> [target]` set or clear one path's disposition, each with `--json`. The path is relative to the target and resolves against the recorded chain, never a stack argument.
+
+- A success answers `{ ok: true, action, path, entry? }`, where `entry` is the recorded `{ disposition, base?, reason? }` and is absent after a lift
+- A declined or customized path leaves `configs`, `seeds`, and `withheld` for `dispositions`, as `{ rel, stack, kind, disposition, present, moved? }`
+- `moved` is set on a customized config alone, and counts toward the exit once the golden copy no longer matches `base`
+- Sync and inject never write a path in `dispositions`, and nothing deletes one the project still holds
+
+A refusal answers `{ ok: false, reason, message }` with exit 1:
+
+| `reason`                | Meaning                                                   |
+| ----------------------- | --------------------------------------------------------- |
+| `no-chain`              | No tooling chain is recorded, so run `tooling sync` first |
+| `bad-path`              | The path leaves the target                                |
+| `not-golden`            | No stack in the recorded chain ships the path             |
+| `already-held`          | The path is already declined or customized, so lift it    |
+| `seed-not-customizable` | The path is a seed, which sync never overwrites           |
+| `missing-file`          | `customize` named a config the target does not hold       |
+| `not-held`              | `lift` named a path with no disposition                   |
+| `toolkit-root`          | The target is the toolkit checkout, the source of truth   |
+
 `canon tooling inject` and `prune-gitignore` apply one stack with no scan or prompt, and the latter prints the number removed on stdout. Use `sync` unless scripting provisioning, and pass `--nested` inside an open frame.
 
 ## Whole-project sync
@@ -78,16 +112,16 @@ After a rename the new name shows as `missing` when the stamp records a stack, a
 
 `canon sync --check` writes nothing and needs no clean tree. `--json` emits the record, `--exit-code` fails CI.
 
-| State        | Meaning                                                            |
-| ------------ | ------------------------------------------------------------------ |
-| `stale`      | Still matches what the toolkit installed                           |
-| `customized` | The project edited it                                              |
-| `stranded`   | Sits at a path the toolkit no longer installs to                   |
-| `orphaned`   | The project authored it                                            |
-| `drifted`    | No stamp covers it                                                 |
-| `missing`    | Governance only. The recorded stack lists it and the tree lacks it |
-| `retired`    | Governance only. The toolkit no longer ships it                    |
-| `renamed`    | Governance only. The toolkit ships it under a new name             |
+| State        | Meaning                                                                 |
+| ------------ | ----------------------------------------------------------------------- |
+| `stale`      | Still matches what the toolkit installed                                |
+| `customized` | The project edited it                                                   |
+| `stranded`   | Sits at a path the toolkit no longer installs to                        |
+| `orphaned`   | The project authored it                                                 |
+| `drifted`    | No stamp covers it                                                      |
+| `missing`    | Governance only. The recorded stack lists it, or a split rule leaves it |
+| `retired`    | Governance only. The toolkit no longer ships it                         |
+| `renamed`    | Governance only. The toolkit ships it under a new name                  |
 
 `retired` and `renamed` count toward `--exit-code`. `orphaned` and `missing` do not.
 

package/docs/agents/records.md

@@ -58,4 +58,4 @@ Branch on `reason` in the `--json` record, not the exit code.
 
 - `canon records ordinal <kind> <slug> --claim`: reserve the next intake or groundwork ordinal
 - `canon records validate <kind> [record] --help`: where a record disagrees with its standard, plus a `structure` report that never sets the exit
-- `canon records stale --help`: when the requirements record was last reviewed
+- `canon records stale --help`: when the requirements and design records were last reviewed

package/docs/index.md

@@ -9,4 +9,4 @@ One-line reference for each doc in this folder.
 
 - [Agents](agents/index.md): CLI catalog and invocation rules for agents, split by command domain. Start with overview.
 - [Target](target/index.md): Scaffold, sync, and migrate a toolkit-managed project, with worked setups for three project shapes.
-- [Workflow](workflow/index.md): How a person and their agents run a feature, from the design tier through the parallel-session loop to the shell that launches them.
+- [Workflow](workflow/index.md): How a person and their agents run a feature, from the design loop through the parallel-session loop to the shell that launches them.

package/docs/target/migrations.md

@@ -20,7 +20,7 @@ canon migrate records --json
 canon migrate records --write --json
 ```
 
-The first line takes the `.canon/` ignore entry the verb requires. The second reports the plan and the third applies it, repointing every tracked file that cites a moved folder. A line naming an old record path on purpose keeps it with `canon-keep-record-root` on that line or the nearest non-blank line above.
+The first line takes the `.canon/` ignore entry. The second reports and the third applies, repointing files that cite a moved folder and deleting a `.gitignore` line `.canon/` covers, as `dropped`. A line naming an old path keeps it via `canon-keep-record-root` on that line or the nearest non-blank one above.
 
 Then sweep the citations inside the records, which the verb above never reaches.
 
@@ -75,7 +75,7 @@ The `memory` record kind left `canon records`, so `canon records validate memory
 - `canon repo metadata`, `canon autoship`, and the `120-bash` rule are gone, and `canon gov sync` removes the rule <!-- canon-keep-retired -->
 - `memory-capture`, the `603-memory` rule, and the `memory` standard are gone, so send a lesson to the context entry that owns the fact <!-- canon-keep-retired -->
 
-Two held files run, `.husky/post-merge` and `.claude/hooks/pr-create-log.sh`, and a stale copy calls a missing binary or names a removed skill. Resync what the toolkit owns before sweeping what the project wrote, and run the second line once per stack.
+Two held files run, `.husky/post-merge` and `.claude/hooks/pr-create-log.sh`, and a stale copy calls a missing binary or names a removed skill. Resync what the toolkit owns before sweeping what the project wrote, and run the second line once per stack, naming a held hook with `--replace`.
 
 ```bash
 canon gov sync
@@ -181,20 +181,18 @@ The verb adds `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)` so a session ca
 
 ## Move the capture cases out of the harness, once
 
-A web project's `e2e/screenshot.ts` is a config, so sync overwrites it. It now loads `CASES` from a seeded `e2e/capture/cases.ts` that sync copies once and never overwrites. Cases edited in the old harness leave the working tree on the first sync and stay in git history.
+A web project's `e2e/screenshot.ts` is a config. It now loads `CASES` from a seeded `e2e/capture/cases.ts` that sync copies once and never overwrites. A harness you edited is held on `--write`, so the new one lands only once you pass `--replace e2e/screenshot.ts`.
 
-- Copy your cases from the old `e2e/screenshot.ts` into `e2e/capture/cases.ts` before the next sync.
+- Copy your cases from the old `e2e/screenshot.ts` into `e2e/capture/cases.ts`, then sync with `--replace e2e/screenshot.ts`.
 - Evidence now defaults to `e2e/evidence/`. Set `export const EVIDENCE_ROOT = 'evidence'` in `e2e/capture/cases.ts` to keep a committed baseline at the old path.
 - A run from a folder with no `e2e/capture/cases.ts` exits 1 and names the file.
 
-## Add the keyboard rule beside a held a11y rule, once
+## Add the rules a split left behind, once
 
-The `a11y` rule split in two. Focus styles, Escape and shortcuts, composite widgets, focus management, and pointer target size moved to a new `keyboard` rule. `canon gov sync` refreshes only the rules a project holds, so it rewrites `a11y.md` without those bullets and never adds `keyboard.md`.
-
-A project holding `.claude/rules/canon/ui/a11y.md` adds the new rule alone:
+The splits created `pointer` and `ux-controls`, and sync refreshes only held rules. `canon gov sync` now names the missing partner of `keyboard.md` and `ux-completeness.md` on every run and adds nothing itself. `a11y.md` gained two bullets and lost none, so it needs no partner.
 
 ```bash
-canon gov install --add keyboard --yes .
+canon gov install --add pointer,ux-controls --yes .
 ```
 
 ## Group a long paths section in `CLAUDE.md`, once

package/docs/target/sync.md

@@ -44,13 +44,32 @@ Add `--json` for a machine-readable report and `--exit-code` to fail CI when a t
 
 - Seed docs such as `CLAUDE.md` and `canon/REQUIREMENTS.md`: merge by hand, keeping the project's customizations
 - Installed governance rules: `canon gov sync <path>`, which adds no new rules and reports coverage afterward
-- Tooling configs and seeds: read differences with `canon tooling diff <stack> <path>`, then `canon tooling sync <stack> <path> --write`, which overwrites golden configs and copies each seed once
+- Tooling configs and seeds: read differences with `canon tooling diff <stack> <path>`, then `canon tooling sync <stack> <path> --write`, which holds an edited config and copies each seed once
 - Index regeneration: `canon indexes regen`
 
 After `canon gov sync` applies, it lists each rule it copied with its globs and how many project files match. A `ui/` rule adds a pointer to `/canon:ux-audit`. `--json` writes `{ "coverage": [{ "rule", "paths", "files", "ui" }] }` to stdout, empty when nothing was copied, with `files` null outside git. The report never changes the exit code.
 
 Try a scenario from [sandbox](../../canon/context/development/sandbox.md) before syncing a real project.
 
+### Held, declined, and customized golden files
+
+`--write` replaces a golden config only when canon changed it and the project did not. A config the project edited, or one no earlier write recorded, is held and listed with a `--replace` command that takes the golden copy. A config from a stack the target never synced is a first install and is never held.
+
+A project can also opt out of one golden file without leaving the stack. Each verb below takes the path relative to the target, as `canon tooling diff` lists it.
+
+```bash
+canon tooling decline .github/workflows/readme-screenshot.yml --reason "no screenshots here"
+canon tooling customize e2e/home.spec.ts
+canon tooling lift .github/workflows/readme-screenshot.yml
+```
+
+- `decline` keeps sync and inject from writing the file again, and leaves a copy the project still holds in place
+- `customize` keeps the project's copy of a config through every write, and `diff` exits 1 once the stack ships a newer golden copy
+- A seed cannot be customized, since sync never overwrites one
+- `lift` hands the file back, so the next sync writes it
+
+These verbs are the only writers of the record in `canon/config/config.json`, so never edit it there by hand.
+
 ## Running sync from an agent session
 
 `canon sync .` applies every domain sync, then offers a commit and pull request that needs a terminal. With no terminal on stdin the syncs apply, the git step is refused, and the command exits 0. Commit yourself. Sync refuses a dirty working tree, and `canon sync --check .` does not.

package/docs/workflow/ai-workflow.md

@@ -66,7 +66,7 @@ An independent session invokes `canon:review-pr` once the pull request is open,
 
 ### UI-heavy project
 
-Pick a design tier before the first feature session. See [visual design workflow](visual-design-workflow.md).
+A UI feature runs the same plan, build, and review loop at any size. See [visual design workflow](visual-design-workflow.md).
 
 ## Skills
 

package/docs/workflow/index.md

@@ -1,11 +1,11 @@
 ---
 title: Workflow
-subtitle: How a person and their agents run a feature, from the design tier through the parallel-session loop to the shell that launches them.
+subtitle: How a person and their agents run a feature, from the design loop through the parallel-session loop to the shell that launches them.
 ---
 
 # Workflow
 
-How a person and their agents run a feature, from the design tier through the parallel-session loop to the shell that launches them.
+How a person and their agents run a feature, from the design loop through the parallel-session loop to the shell that launches them.
 
 ## Agent surface
 
@@ -17,5 +17,5 @@ How a person and their agents run a feature, from the design tier through the pa
 - [Parallel features](parallel-features.md): Run independent features in parallel worktrees, with the records and board every session shares
 - [Skill map on request](skill-map-on-request.md): When to reach for the plugin skills that serve a request rather than a moment in a project's life
 - [Skill map](skill-map.md): When to reach for each plugin skill, grouped by the moment a project meets it
-- [Visual design workflow](visual-design-workflow.md): Tiered guide for design authoring with Claude Code
+- [Visual design workflow](visual-design-workflow.md): How canon plans, builds, and reviews a UI, from the design reference a plan cites to the browser pass that holds a pull request open
 - [Zshrc aliases for Claude Code](zshrc-aliases.md): Shell aliases that shorten common Claude Code invocations

package/docs/workflow/parallel-features.md

@@ -34,7 +34,7 @@ Assert the orchestrator role in one warm session with `canon:role-orchestrator`.
 
 - `canon records validate plans [plan]` reports a plan breaking its standard, plus `structure` misses that never set the exit, and takes `groundwork` and `intake`
 - `canon records push` and `canon records pull` carry `.canon/` to and from a private repository. See [records](../agents/records.md).
-- `canon records size`, `canon records prune-tmp`, and `canon records stale canonical` report folder size, idle scratch, and releases since the requirements review
+- `canon records size`, `canon records prune-tmp`, and `canon records stale canonical` report folder size, idle scratch, and releases since the requirements and design records were last read
 - `canon tasks archive` moves a shipped plan to `.canon/plans/archive/` and retargets the task's `Plan:` line
 
 ## Shipping a fan-out