@erclx/canon 5.61.0 → 5.63.0

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

@@ -48,7 +48,7 @@ The checkbox stays `- [ ]` followed by the action and the result, since the evid
 
 ## 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:
+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 from the `ui-craft` references the changed surface reads, for each behavior below that it 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.

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

@@ -0,0 +1,29 @@
+---
+name: ui-craft
+description: Why the UI behavior practice lives in one skill every role reads by name, and where it stops beside design-taste and design-record
+---
+
+# UI craft requirement
+
+## Gap
+
+Without this skill, the UI behavior practice reaches a session only as path rules a target has to sync, so a project holding the plugin without governance builds a component with none of it. A role that plans, builds, or reviews a rendered change has no name to load the practice by, and each one restates the part it remembers.
+
+## Must
+
+- Every rule the retired ui practice rules carried sits in a reference, unchanged in wording, with its source row in a ledger beside the reference
+- A rendered change reaches accessibility, keyboard, and state coverage on every read, and the other references by the change that needs them
+- A rendered change that is about to be handed over reaches the capture reference
+- A planning, building, or reviewing role reaches the skill by name, with or without the governance pointer installed
+
+## Must not
+
+- Reword a moved rule in the move, since a wording change is a separate change with its own ledger row
+- Restate the look, being layout, type, color, or the layer order
+- Be reached only by an author typing its name, since the `craft` pointer rule and the planning, building, and reviewing skills are its callers
+
+## Out of scope
+
+- How a surface looks, which `design-taste` owns
+- The design folder, its references, and the comparison a pull request shows, which `design-record` and the `design-reference` rule own
+- The visual checklist a reviewer reads, which `ui-checklist` owns

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

@@ -0,0 +1,44 @@
+---
+name: ui-craft
+description: Carries the behavior practice for rendered UI, being accessibility, keyboard and pointer operation, forms, motion, controls, state coverage, interface copy, and the capture a rendered change owes, routed from the kind of change to the references it reads. Use before building or changing a component, a page, a form, or any rendered surface, when judging one in review, or when asked "is this accessible", "what states does this need", "how should this form validate", "what should the button say", or "what do I capture after this change". Do NOT use for how a surface looks, being layout, type, color, and the layer order, which is `design-taste`, or for the design folder and its references, which is `design-record`.
+metadata:
+  family: build
+---
+
+# UI craft
+
+A rendered change that skips this practice ships a control a keyboard cannot reach, a list with no empty state, or an error that names the fault and never the fix, and none of it fails a build. The references below carry the rules. This body routes a change to the ones it reads.
+
+Load this before building rather than after, since a missing state or a trapped focus is cheaper to design in than to retrofit.
+
+## Read by the change
+
+Read every reference on the always row for any rendered change, then each row the change matches.
+
+| The change                                                         | Read                                  |
+| ------------------------------------------------------------------ | ------------------------------------- |
+| Any rendered change                                                | `a11y.md`, `keyboard.md`, `states.md` |
+| A click, press, drag, gesture, or popover dismissal                | `pointer.md`                          |
+| A form, a field, validation, or a sign-in step                     | `forms.md`                            |
+| An animation, transition, autoplay, or carousel                    | `motion.md`                           |
+| A destructive action, an edit cancel, or a hover or disabled state | `controls.md`                         |
+| A rendered string, heading, label, or link                         | `copy.md`                             |
+| A rendered surface has changed and is about to be handed over      | `capture.md`                          |
+
+Each name sits under `${CLAUDE_SKILL_DIR}/references/`. A row's reference is read whole, since its sections name the cases a change reaches without saying so.
+
+## Hold the floor over taste
+
+The references state a floor, and no aesthetic choice trades against it. A contrast ratio, a focus ring, or a state the design leaves out is restored before the look is judged, and `design-taste` decides the look inside that floor.
+
+## Sources
+
+Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It names the authorities the references draw on and where each bullet's source row sits.
+
+## What this delegates
+
+- How a surface looks, being the layer order, the coherence locks, and the defaults a model reaches for: `design-taste`
+- The accepted designs under the design folder and how a reference lands there: `design-record`
+- The visual checklist a reviewer reads beside the screenshots: `ui-checklist`
+- Reading source for roughness a rule does not state: `ux-audit`
+- Prose on the surface beyond its interface copy: the `write-human` skill

package/{governance/rules/ui → claude/skills/ui-craft/references}/a11y.md

@@ -1,13 +1,3 @@
----
-description: Semantics, text alternatives, contrast, and reflow for rendered UI
-paths:
-  - '**/*.tsx'
-  - '**/*.jsx'
-  - '**/*.astro'
-  - '**/*.html'
-  - '**/*.css'
----
-
 # Accessibility standards
 
 ## Semantics
@@ -16,6 +6,7 @@ paths:
 - Spell an attribute the way the file's syntax spells it, being `onclick` and `tabindex` in HTML and Astro markup and `onClick` and `tabIndex` in JSX.
 - Give a custom control the role its pattern names, such as `combobox` or `listbox`, and keep `aria-expanded`, `aria-selected`, and `aria-checked` in step with what it shows.
 - Give an interactive element with no visible text label a name through `aria-label` or `aria-labelledby`.
+- Put the visible text in the accessible name, first where you can (WCAG 2.5.3).
 
 ## Text alternatives
 
@@ -26,6 +17,7 @@ paths:
 
 - Give a control's visual boundary and every graphic that carries meaning at least 3:1 contrast against adjacent colors (WCAG 1.4.11).
 - Never make color the only carrier of a state, error, or distinction. Pair it with text, an icon, or a pattern (WCAG 1.4.1).
+- Give text 4.5:1 contrast, or 3:1 when large (WCAG 1.4.3).
 
 ## Reflow
 

package/claude/skills/ui-craft/references/adopted.md

@@ -0,0 +1,27 @@
+---
+title: Adopted and declined
+description: The authorities the ui-craft references draw on, and where the per-bullet source rows for each reference sit
+---
+
+# Adopted and declined
+
+Every bullet in a reference has its own source row in a ledger outside the plugin, so this record names the authorities once and points at the rows. A reader arguing against one bullet opens its ledger, and a session extending a reference adds the row there in the same change.
+
+## Authorities
+
+Each field below names the source its references cite, and a house choice covers a threshold or a scope no source states.
+
+- **Web accessibility.** The W3C's [WCAG 2.2](https://www.w3.org/TR/WCAG22/) and the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) back the accessibility, keyboard, pointer, and motion references.
+- **CSS behavior.** [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS) and the CSS specifications back the focus ring, `color-scheme`, and overflow bullets.
+- **Native targets.** Apple's and Android's platform guidelines back the native touch target figures in `pointer.md`.
+- **Forms and copy.** The [GOV.UK Design System](https://design-system.service.gov.uk/) and its style guide back `forms.md` and the copy and casing sections of `copy.md`.
+- **Usability research.** The [Nielsen Norman Group](https://www.nngroup.com/articles/) backs most of `states.md`, part of `controls.md`, and the link sections of `copy.md`.
+- **Capture.** `capture.md` is a house procedure, with its reflow width taken from the WCAG reflow criterion `a11y.md` cites.
+
+## Where the rows sit
+
+The rows sit in the toolkit's own repository rather than the plugin, one ledger per reference and one table row per bullet under the H2 the bullet sits under. The toolkit's skill audit fails a reference whose bullets and rows disagree in count under any heading, and a target never carries the rows.
+
+## Declined
+
+Each ledger carries its own `## Declined` list, recording the bullets cut or reworded when the source rules were last rewritten. The move into this skill changed no bullet's wording, so it declined nothing.

package/{governance/rules/ui/surface-capture.md → claude/skills/ui-craft/references/capture.md}

@@ -1,32 +1,22 @@
----
-description: Require a capture against a running preview after a rendered surface changes
-paths:
-  - '**/routes/**/*.{tsx,jsx,vue,svelte,astro}'
-  - '**/pages/**/*.{tsx,jsx,vue,svelte,astro}'
-  - '**/app/**/page.{tsx,jsx}'
-  - '**/components/**/*.{tsx,jsx,vue,svelte,astro}'
-  - '**/*.html'
----
-
 # Surface capture standards
 
 ## What a surface is
 
-- Treat anything the project renders for a person as a surface, a generated page as much as a route.
+- Treat anything the project renders for a person as a surface, generated pages included.
 - Skip a component the production build strips out, such as a dev-only switcher.
 
 ## When to capture
 
-- Run the project's capture command against a preview server, never a dev server, after changing a surface. Report it when the project has none.
-- Capture every theme the surface ships, and again after fixing a defect a capture found.
+- Run the project's capture command against a preview server, never a dev server, after changing a surface. Report a project with none.
+- Capture every theme the surface ships, and again after fixing a defect found.
+- Read your capture against the `canon:ui-checklist` boxes before opening the pull request, reporting a skill that does not resolve.
 
 ## What a capture covers
 
 - Capture the full page, never a component in isolation.
 - Capture a layout case at 320, the reflow floor in `a11y`, plus each breakpoint in the `## Layout` section of `DESIGN.md`, or at 320 alone when there is none.
 - Capture resizable chrome at its narrowest and widest clamp, at the narrowest width keeping it persistent. Judge the content width beside it.
-- Capture a state case at one width rather than the full set.
-- Drive a state an initial render cannot reach, such as an open menu or a rail tracking scroll.
+- Capture a state case at one width, driving states a first render cannot reach, such as an open menu.
 - Add a surface's case with the surface, and remove it with the surface.
 
 ## Sharing a capture

package/claude/skills/ui-craft/references/controls.md

@@ -0,0 +1,18 @@
+# UX controls standards
+
+## Destructive actions
+
+- Confirm a destructive action, such as a delete, disconnect, or discard, before it runs, unless it can be undone afterward.
+- Restore the value from before an edit when the edit is cancelled. Never discard typed work on Escape or an outside click unasked, but confirm first when the person has typed something.
+
+## Element states
+
+- Give every interactive element distinct hover, active, focus, and disabled styles.
+- Never flash an intermediate state, such as a light frame before a dark theme or a layout jump before data arrives. Reserve the space or settle it first.
+- Say why a control is disabled, in text beside it or a tooltip, and keep it focusable through `aria-disabled` when the reason matters.
+- Declare `color-scheme` on `:root` to match each theme, so scrollbars and form controls follow the theme instead of staying light.
+
+## Hover and focus effects
+
+- Keep content shown on hover or focus dismissible without moving the pointer, hoverable, and visible until the trigger leaves or the person dismisses it (WCAG 1.4.13).
+- Change no context, such as navigating, submitting, or moving focus, when a control gains focus or changes value, unless the person was told first (WCAG 3.2.1, 3.2.2).

package/claude/skills/ui-craft/references/copy.md

@@ -0,0 +1,45 @@
+# UI copy standards
+
+## Punctuation
+
+- Write no em dash (`—`) or semicolon in rendered copy. Use a comma or a period, or restructure the sentence.
+- Add no trailing punctuation to a button label or a short action string.
+
+## Button copy
+
+- Label a button with the verb of the action it performs, such as `Save` or `Delete`, never with filler such as `Click to delete`.
+
+## Error messages
+
+- Tell the person how to fix the error, such as `Enter an email address` over `Email is invalid`.
+- Keep an error message to one short sentence in plain language, with no technical jargon or error codes.
+
+## Placeholder text
+
+- Never use placeholder text as a label, a hint, or an example. Put a format example such as `name@example.com` in hint text under the label.
+
+## Sentence case
+
+- Use sentence case for rendered headings, labels, nav items, tab titles, and dialog titles, since title case on every heading reads as a template default.
+- Keep the original casing of a proper noun or product name, such as `GitHub`, `macOS`, or `TypeScript`.
+
+## Uppercase labels
+
+- Keep small uppercase labels above headings to `ceil(sections / 3)`, the first screen counting as one. Delete the extra labels, since position already names a section.
+
+## Where it applies
+
+- Apply the same casing to interface copy kept outside the globs, such as a locale file, which this rule never fires on.
+
+## Overriding
+
+- Depart from sentence case only where the case needs it, such as an acronym, a brand mark, or a set-in-caps identity the design chose on purpose.
+
+## Default target
+
+- Open a link in the same tab. Reserve `target="_blank"` for a page the person must consult while finishing a task in the current one.
+- Never add `target="_blank"` as a default for every external link.
+
+## mailto: links
+
+- Open a `mailto:` link in the same tab. It hands off to the mail client rather than replacing the page, so a new tab leaves an empty tab behind.

package/{governance/rules/ui → claude/skills/ui-craft/references}/forms.md

@@ -1,12 +1,3 @@
----
-description: Form validation timing, submission, error placement, and derived state for rendered forms
-paths:
-  - '**/*.tsx'
-  - '**/*.jsx'
-  - '**/*.astro'
-  - '**/*.html'
----
-
 # Form standards
 
 ## Validation timing

package/{governance/rules/ui → claude/skills/ui-craft/references}/keyboard.md

@@ -1,13 +1,3 @@
----
-description: Focus styles, keyboard operation, focus management, and pointer targets for rendered UI
-paths:
-  - '**/*.tsx'
-  - '**/*.jsx'
-  - '**/*.astro'
-  - '**/*.html'
-  - '**/*.css'
----
-
 # Keyboard and focus standards
 
 ## Focus styles
@@ -15,24 +5,21 @@ paths:
 - Style focus through the project's one focus ring rather than a per-component focus style.
 - Never set `outline: none` or `outline-none` without a replacement focus indicator in the same rule.
 - Give the focus ring 3:1 contrast against its background in every theme the project ships.
+- Keep the focus ring whole. Where an ancestor's `overflow` would clip it, inset it with a negative `outline-offset` or pad the edge items of the list.
 
 ## Keyboard operation
 
 - Close a dialog, popover, menu, or inline confirmation on Escape, and cancel an in-progress edit the same way.
+- Never trap keyboard focus. A person who tabs into a component can leave it by keyboard alone, and a modal dialog leaves on Escape (WCAG 2.1.2).
 - Bind no single printable character as a shortcut unless a person can turn it off or remap it, or it fires only while its control has focus (WCAG 2.1.4).
-- Give every author-defined drag a single-pointer alternative and a keyboard path, such as move buttons or arrow-key reordering (WCAG 2.5.7).
 
 ## Composite widgets
 
 - Keep one item of a composite widget in the tab sequence, and move between its items with the arrow keys through roving `tabindex` or `aria-activedescendant`.
 - Open a combobox popup on Down Arrow, accept the focused option on Enter, and close the popup on Escape without changing the value.
+- Give a custom number input the spinbutton keys, Up and Down to step and Home and End for the limits. Take the keys of any other custom widget from its ARIA Authoring Practices Guide pattern.
 
 ## Focus management
 
 - Move focus into a dialog when it opens, and return it to the element that opened it when it closes.
 - Never let a sticky header, footer, or overlay fully cover the focused control. Scroll it clear of them (WCAG 2.4.11).
-
-## Pointer targets
-
-- Size a web pointer target at least 24 by 24 CSS pixels, or space it so a 24 pixel circle centered on it touches no other target (WCAG 2.5.8).
-- Size a native touch target at the platform figure, 44 points on iOS and 48 dp on Android, and never swap the web and native figures.

package/{governance/rules/ui → claude/skills/ui-craft/references}/motion.md

@@ -1,13 +1,3 @@
----
-description: Moving content controls and the reduced-motion preference for rendered UI
-paths:
-  - '**/*.tsx'
-  - '**/*.jsx'
-  - '**/*.astro'
-  - '**/*.html'
-  - '**/*.css'
----
-
 # Motion standards
 
 ## Moving content

package/claude/skills/ui-craft/references/pointer.md

@@ -0,0 +1,13 @@
+# Pointer standards
+
+## Pointer actions
+
+- Dismiss a popover or menu on a press outside it and when focus leaves it, as well as on Escape.
+- Run a pointer action on release rather than press, so a person can slide off the target to abort it (WCAG 2.5.2).
+- Give a path-based or multipoint gesture, such as a swipe or pinch, a single-pointer alternative with no path (WCAG 2.5.1).
+- Give every author-defined drag a single-pointer alternative and a keyboard path, such as move buttons or arrow-key reordering (WCAG 2.5.7).
+
+## Pointer targets
+
+- Size a web pointer target at least 24 by 24 CSS pixels, or space it so a 24 pixel circle centered on it touches no other target (WCAG 2.5.8).
+- Size a native touch target at the platform figure, 44 points on iOS and 48 dp on Android, and never swap the web and native figures.

package/{governance/rules/ui/ux-completeness.md → claude/skills/ui-craft/references/states.md}

@@ -1,19 +1,10 @@
----
-description: UX completeness checklist for interactive components and views
-paths:
-  - '**/*.tsx'
-  - '**/*.jsx'
-  - '**/*.astro'
-  - '**/*.html'
-  - '**/*.css'
----
-
 # UX completeness standards
 
 ## Feedback
 
 - Confirm every user-initiated mutation, such as a save, delete, or import, inline on success, and show an inline error when it fails.
 - Auto-dismiss a success message only when its outcome stays visible elsewhere. Keep a message carrying the only copy of its information until dismissed (WCAG 2.2.1).
+- Pause a timed message while it has pointer hover or keyboard focus, and take no focus for it. A person finishes reading it, and a status message never interrupts typing (WCAG 4.1.3).
 - Show no optimistic status, such as a green dot or "connected", while unsaved edits are pending.
 
 ## Empty states
@@ -26,17 +17,8 @@ paths:
 - Show a progress indicator for any operation a person waits on for longer than about one second.
 - Mark previous content as updating while new content loads, rather than showing it unmarked as current.
 
-## Destructive actions
-
-- Confirm a destructive action, such as a delete, disconnect, or discard, before it runs, unless it can be undone afterward.
-
-## Element states
-
-- Give every interactive element distinct hover, active, focus, and disabled styles.
-- Never flash an intermediate state, such as a light frame before a dark theme or a layout jump before data arrives. Reserve the space or settle it first.
-
 ## Overflow
 
 - Truncate long text in a constrained container with an ellipsis rather than letting it overflow.
 - Expose truncated text through an expand control or full text on focus, never through a `title` tooltip alone.
-- Keep focus rings and interactive borders clear of a parent's `overflow` clipping, padding the edge items of a scrollable list.
+- Keep interactive borders clear of a parent's `overflow` clipping, padding the edge items of a scrollable list.

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-craft` skill's references.
 
 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/claude/skills/write-human/references/adopted.md

@@ -5,7 +5,10 @@ description: Which external writing patterns this skill adopted, which it declin
 
 # Source material
 
-Two external writing skills were read as source material for this one. The first catalogs 31 patterns of machine-sounding prose. The second layers document mode, sentence construction, information density, and ambiguity prevention.
+Two external writing skills were read as source material for this one.
+
+- **[humanizer](https://github.com/blader/humanizer)** catalogs 31 patterns of machine-sounding prose
+- **An unidentified second skill** layers document mode, sentence construction, information density, and ambiguity prevention. No record of the read named it, so it carries no link.
 
 Neither was imported wholesale, and one measurement settles why. Read this before adding a rule from outside this corpus, and extend the position below rather than deriving a second one.
 

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.
 
@@ -62,11 +62,45 @@ After a rename the new name shows as `missing` when the stamp records a stack, a
 
 ## Tooling
 
-- `canon tooling diff <stack> [target]` is the read-only comparison, exiting 1 on any difference
+- `canon tooling diff <stack> [target]` is the read-only comparison, exiting 1 on any difference, and it reads a dependency on a later major than the stack pins as `ahead`, which counts as no change
 - A `--json` refusal answers `{ ok: false, reason, message }`, so branch on the record
 - `withheld` entries are `{ rel, stack, present }`, hold every `.github/` file below the git root, and count toward no exit
 - `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.
+- `canon tooling sync <stack> [target]` writes only under `--write`. `--check` reports and exits 0, and a headless run with neither flag exits 1. It never installs over an `ahead` dependency.
+
+### 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.
 
@@ -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/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

@@ -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
+## Fold the ui rules onto one pointer, 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:
+Eleven ui rules moved unchanged into the `ui-craft` skill, being `a11y`, `keyboard`, `pointer`, `forms`, `motion`, `ux-controls`, `ux-completeness`, `surface-capture`, `copy`, `interface-casing`, and `link-behavior`. Update the plugin, then sync, which folds each one you hold and `design-taste.md` onto one `craft.md` pointer without local edits.
 
 ```bash
-canon gov install --add keyboard --yes .
+canon gov sync .
 ```
 
 ## Group a long paths section in `CLAUDE.md`, once

package/docs/target/sync.md

@@ -44,13 +44,33 @@ 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
+- Tooling dependencies: a dependency on a later major than the stack pins reads as `ahead`, and sync leaves it
 - 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/screenshot.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, and the starter `e2e/home.spec.ts` is 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/skill-map.md

@@ -45,6 +45,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | `canon:search-craft`          | Before searching outside the project               |
 | `canon:systematic-debugging`  | A test fails or a bug surfaces                     |
 | `canon:design-taste`          | Drafting or judging an interface                   |
+| `canon:ui-craft`              | Building or judging a component's behavior         |
 | `canon:ui-checklist`          | After a UI change, to list what to check           |
 
 ## Check the work before it leaves the branch