@erclx/canon 5.68.0 → 5.70.0

package/docs/index.md

@@ -8,5 +8,6 @@ subtitle: One-line reference for each doc in this folder.
 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 migrations](migrations/index.md): One-time moves a project scaffolded under an older toolkit makes before its next sync, split by whether a canon migrate verb runs them or a person makes them by hand.
 - [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 loop through the parallel-session loop to the shell that launches them.

package/docs/migrations/by-hand.md

@@ -0,0 +1,107 @@
+---
+title: Target migrations by hand
+description: One-time moves and keep-or-delete calls a person makes by hand, which no canon migrate verb runs or detects
+category: Agent surface
+---
+
+# Target migrations by hand
+
+Each section is a move a project scaffolded before the change it names makes by hand, since no `canon migrate` verb runs it and `canon migrate status` never lists it. The moves a verb runs, and the order to run them in, are in [target migrations by verb](by-verb.md).
+
+## Back records up off this machine, once
+
+Run `canon records push` once a private repository exists. It prints the one-time setup command when it finds none, and `canon init` prints the same reminder.
+
+## Rename the pull request template headings, once
+
+The template headings are now `## Key changes` and `## Technical context`, and `canon labels scan` compares case exactly. Rename them in `.github/pull_request_template.md`, or delete it and run `canon tooling sync base . --write`.
+
+## Delete the retired snippets, once
+
+A project scaffolded while snippets installed may hold `.claude/snippets/` or a root `snippets/`.
+
+```bash
+canon sync --check . --json | jq '.reverse'
+```
+
+- `dropped` is the toolkit's copy, unchanged, so delete it
+- `unattributed` is often an edited copy, so read what changed first
+- `project` is the project's own content, so leave it
+
+From the registry the walk reports `historyUnavailable`, so check both paths by hand.
+
+## Stop calling the standards verb, once
+
+`canon standards <name>` is gone, and a call now fails with a too-many-arguments error. Replace each call with the skill that owns the standard, at `references/<name>.md`. <!-- canon-allow-reference: verb retired -->
+
+| Skill             | Standards                                                     |
+| ----------------- | ------------------------------------------------------------- |
+| `task-board`      | `board`, `tasks`, `tasks-decline`                             |
+| `context-fold`    | `context`                                                     |
+| `canvas-board`    | `canvas`, `design` <!-- canon-keep-retired -->                |
+| `docs-sync`       | `docs`, `readme`                                              |
+| `draw-figure`     | `figures`, `mermaid`                                          |
+| `create-rule`     | `rule`                                                        |
+| `create-skill`    | `skill`, `skill-paths`, `skill-practice`, `skill-requirement` |
+| `git-branch`      | `branch`, `slug`                                              |
+| `git-commit`      | `commit`, `versioning`                                        |
+| `git-pr`          | `pr`, `publish`                                               |
+| `markdown-craft`  | `markdown`                                                    |
+| `teach-workspace` | `glossary`, `teach` <!-- canon-keep-retired -->               |
+| `plan-groundwork` | `groundwork`, `groundwork-spikes`                             |
+| `plan-intake`     | `intake`                                                      |
+| `plan-feature`    | `plan`, `plan-lifecycle`                                      |
+| `plan-ready`      | `ready` <!-- canon-keep-retired -->                           |
+| `write-doc`       | `requirements`, `wiki`                                        |
+| `session-map`     | `session`                                                     |
+
+The `standard` name became `skill-reference.md` in `create-skill`.
+
+## Keep or delete the wireframes folder, your call
+
+The wireframes record is retired, and nothing deletes what a project holds.
+
+- `canon/wireframes/` stays yours and unaudited. Keep it as notes or delete it.
+- Delete the `@canon/wireframes/index.md` line in your `CLAUDE.md` with the folder. `canon claude sync` does not rewrite it.
+- `canon gov sync` removes `.claude/rules/canon/standards/wireframes.md`
+
+## Keep or delete the retired product files, your call
+
+The learning workspace, deck renderer, app recorder, canvas, and design install are retired with their verbs, and nothing deletes what a project holds.
+
+- `.canon/teach/` holds HTML that opens as it is <!-- canon-keep-retired -->
+- `.canon/slides/` and a `demos/` folder hold sources nothing renders any more, so delete them once nothing cites them <!-- canon-keep-retired -->
+- Move the `.claude/design/project/` values, `fonts/`, and `fonts.css` to the stylesheet your `canon/DESIGN.md` lead names, then delete `.claude/design/`
+
+A reference to a retired skill takes a hand edit.
+
+- Replace a `canon:teach-workspace` reference with `canon:teach-craft` by hand, since `canon migrate skill-names` does not rewrite it <!-- canon-keep-retired -->
+- Delete a `canon:make-deck`, `canon:script-screencast`, `canon:record-screencast`, `canon:read-frames`, or `canon:video-craft` reference, since none has a successor <!-- canon-keep-retired -->
+- Delete a `canon:canvas-board` reference too. Frameboard, which `canon:design-pick` drives, reads each `.canon/canvas/` folder as a project, so move a kept page under one <!-- canon-keep-retired -->
+
+## Move decisions out of a held architecture record, once
+
+The toolkit no longer seeds `canon/ARCHITECTURE.md`, and a held file and its `CLAUDE.md` import stay. Move a trap a session would hit into that domain's `## Gotchas`, then delete the file and its `@canon/ARCHITECTURE.md` line.
+
+## Move the capture cases out of the harness, once
+
+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`, 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.
+
+## Fold the ui rules onto one pointer, once
+
+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 sync .
+```
+
+## Group a long paths section in `CLAUDE.md`, once
+
+The `## Key paths` section of `CLAUDE.md` now keeps to 5 bullets in a row, and every other section stays exempt. `canon claude sync` never rewrites a `CLAUDE.md` you hold, so it warns with the line of each longer run.
+
+- Regroup the section by hand under H3s, each opening on a one-sentence lead.
+- List `CLAUDE.md` in `canon/config/markdown.toml` to gate it from then on.

package/docs/migrations/by-verb.md

@@ -0,0 +1,118 @@
+---
+title: Target migrations by verb
+description: One-time moves a canon migrate verb runs, for a project scaffolded under an older toolkit, in the order canon migrate status lists them
+category: Agent surface
+---
+
+# Target migrations by verb
+
+Each section is a move a `canon migrate` verb runs once, for a project scaffolded before the change it names. Run `canon upgrade` first, then `canon migrate status --json` to list the moves still pending in the order to run them. A pending verb with no section here, such as `scratch-evidence` or `rename`, is in [migrate](../agents/migrate.md).
+
+`canon:target-update` is the guided path through both, running the moves in that order once you approve its preview. The moves no verb runs are in [target migrations by hand](by-hand.md), and the recurring sync that follows is in [target sync](../target/sync.md).
+
+## Move the records first, once
+
+Gitignored session records, being the task board, plans, review reports, and scratch, moved from `.claude/` to `.canon/`. Run these from inside the project, and read the `ok` field of the `--json` record rather than the exit code.
+
+```bash
+canon tooling sync claude . --write
+canon migrate records --json
+canon migrate records --write --json
+```
+
+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.
+
+```bash
+canon migrate record-tree --json
+canon migrate record-tree --write --json
+```
+
+It covers `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. Read the report before `--write`. The record tree is untracked, and a wrong rewrite has no undo.
+
+## Move the design board to `board/`, once
+
+A pick round with no board named now drafts in `.canon/board/`, the folder Frameboard reads, rather than `.canon/canvas/`. Stop any `frameboard serve` on the old folder first.
+
+```bash
+canon migrate record-layout --json
+canon migrate record-layout --write --json
+```
+
+A project holding both folders gets a collision, and neither moves. A `board` key in `design.toml` naming `.canon/canvas` stays as written, so update it by hand.
+
+## Move rules off the flat layout, once
+
+Installed rules moved from `.claude/rules/<subdir>/` to `.claude/rules/canon/<subdir>/`. On the flat layout `canon gov sync` exits 0 reporting `No governance surfaces found in target`, and `canon gov install` lands a second copy.
+
+```bash
+canon migrate rule-layout --json
+canon migrate rule-layout --write --json
+```
+
+Run it once, ahead of `canon gov sync` or `canon gov install`.
+
+## Rename the skill citations, once
+
+Plugin skills dropped their `claude-` prefix, so `canon:claude-docs` is now `canon:context-fold`. Five drafters merged into `write-doc`, seven `draft-` skills took verb-first names, and four joined their family. No old name keeps a pointer, and `canon migrate skill-names --write` moves a project. <!-- canon-keep-retired -->
+
+| Old name           | New name                                        |
+| ------------------ | ----------------------------------------------- |
+| `draft-doc`        | `write-doc` <!-- canon-keep-retired -->         |
+| `draft-figure`     | `draw-figure` <!-- canon-keep-retired -->       |
+| `draft-identity`   | `design-identity` <!-- canon-keep-retired -->   |
+| `draft-slides`     | `make-deck` <!-- canon-keep-retired -->         |
+| `draft-and-pick`   | `design-pick` <!-- canon-keep-retired -->       |
+| `draft-ready`      | `plan-ready` <!-- canon-keep-retired -->        |
+| `draft-screencast` | `script-screencast` <!-- canon-keep-retired --> |
+| `pick-by-eye`      | `design-pick` <!-- canon-keep-retired -->       |
+| `ui-record`        | `ui-film` <!-- canon-keep-retired -->           |
+| `ux-audit`         | `ui-audit` <!-- canon-keep-retired -->          |
+| `ux-measure`       | `ui-measure` <!-- canon-keep-retired -->        |
+
+Replace a citation of a skill with no successor by hand, or delete the sentence.
+
+- `canvas` is now `canvas-board`. The sweep rewrites only `canon:canvas` and `skills/canvas`, so replace a bare mention by hand. <!-- canon-keep-retired -->
+- `draft-ready` is rewritten only as `canon:draft-ready` and `skills/draft-ready`, since bare it also describes a pull request, so replace a bare mention by hand. <!-- canon-keep-retired -->
+- `design-extract` and `sketch-design` are replaced by `canon:canvas-board`. <!-- canon-keep-retired -->
+- `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, `canon-rollout`, and `canon-feedback-triage` have no successor <!-- canon-keep-retired -->
+- `create-standard`, `markdown-propose`, `memory-review`, `project-commands`, `repo-metadata`, `ux-walkthrough`, and `plan-ready` have no successor <!-- canon-keep-retired -->
+
+The `memory` record kind left `canon records`, so `canon records validate memory` refuses as an unknown kind and `canon records migrate` is gone.
+
+- `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, naming a held hook with `--replace`.
+
+```bash
+canon gov sync
+canon tooling sync <stack> . --write
+canon migrate skill-names --json
+canon migrate skill-names --write --json
+```
+
+## Move the surfaces off `.claude/`, once
+
+`context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the install stamp folder, now `canon/config/`, moved under `canon/`. `rules/`, `skills/`, `hooks/`, and `settings.json` stay where Claude Code reads them.
+
+```bash
+canon migrate surface-roots --json
+canon migrate surface-roots --write --json
+```
+
+It moves each surface with `git mv` and repoints every tracked citation. No other command notices a surface left at `.claude/`.
+
+## Deny subagents and merges, and turn auto memory off, once
+
+The seeded `.claude/settings.json` now denies the `Agent` and `Task` tools and both merge commands, and sets `autoMemoryEnabled` to `false`. `canon claude sync` never rewrites a settings file you hold, so it warns while the file holds no default or lacks a merge entry. Removing `Agent` and `Task` later draws no warning.
+
+```bash
+canon migrate session-defaults --json
+canon migrate session-defaults --write --json
+```
+
+The verb only adds a key that is absent. A person who wants auto memory back sets it in their own `.claude/settings.local.json`.
+
+The verb adds `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)` so a session cannot merge. A project migrated before them runs `--write` once more, which also restores `Agent` and `Task` for a person who removed them to allow subagents, so remove them again after.

package/docs/migrations/index.md

@@ -0,0 +1,14 @@
+---
+title: Target migrations
+subtitle: One-time moves a project scaffolded under an older toolkit makes before its next sync, split by whether a canon migrate verb runs them or a person makes them by hand.
+category: Agent surface
+---
+
+# Target migrations
+
+One-time moves a project scaffolded under an older toolkit makes before its next sync, split by whether a canon migrate verb runs them or a person makes them by hand.
+
+## Agent surface
+
+- [Target migrations by hand](by-hand.md): One-time moves and keep-or-delete calls a person makes by hand, which no canon migrate verb runs or detects
+- [Target migrations by verb](by-verb.md): One-time moves a canon migrate verb runs, for a project scaffolded under an older toolkit, in the order canon migrate status lists them

package/docs/target/index.md

@@ -10,7 +10,6 @@ Scaffold, sync, and migrate a toolkit-managed project, with worked setups for th
 
 ## Agent surface
 
-- [Target migrations](migrations.md): One-time moves a project scaffolded under an older toolkit runs before its next sync
 - [Target projects](projects.md): Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
 - [Target scenarios](scenarios.md): Worked setups for a markdown-heavy project, a web application, and a monorepo
-- [Target sync](sync.md): Check what drifted in a toolkit-managed project and pull it in, per domain or all at once
+- [Target sync](sync.md): Check what drifted in a toolkit-managed project and pull it in, per domain or all at once, and update canon itself

package/docs/target/projects.md

@@ -56,7 +56,7 @@ Keep the `## Scripts` table in `canon/context/development/local-loop.md` current
 Before the first feature session:
 
 1. Fill `canon/REQUIREMENTS.md` with the problem, goals, and non-goals. The seed's 600-word cap gates under `canon context audit`.
-2. For a UI project, write `canon/DESIGN.md` from the seed and name the stylesheet in its lead, or work the direction out with `canon:pick-by-eye`
+2. For a UI project, write `canon/DESIGN.md` from the seed and name the stylesheet in its lead, or work the direction out with `canon:design-pick`
 3. Optionally invoke `canon:draw-figure` for an architecture view. The Mermaid CLI downloads on first use.
 4. Start the feature loop in [AI workflow](../workflow/ai-workflow.md)
 
@@ -84,11 +84,11 @@ Install one domain without re-running `canon init`.
 - A project-specific rule: invoke `canon:create-rule`, which writes into `.claude/rules/project/`. A rule under `.claude/rules/canon/` is deleted on the next sync.
 - An `index.md` system for a markdown-heavy folder: invoke `canon:target-setup indexes`
 
-For a leftover `.claude/snippets/` see [target migrations](migrations.md).
+For a leftover `.claude/snippets/` see [target migrations by hand](../migrations/by-hand.md).
 
 ## Sync upstream drift
 
-A project scaffolded before a layout move runs the one-time moves in [target migrations](migrations.md) first. [Target sync](sync.md) covers reading drift and running a sync. [Target scenarios](scenarios.md) walks three worked setups.
+A project scaffolded before a layout move runs the one-time moves in [target migrations](../migrations/index.md) first. [Target sync](sync.md) covers reading drift and running a sync. [Target scenarios](scenarios.md) walks three worked setups.
 
 ## Related
 

package/docs/target/sync.md

@@ -1,12 +1,12 @@
 ---
 title: Target sync
-description: Check what drifted in a toolkit-managed project and pull it in, per domain or all at once
+description: Check what drifted in a toolkit-managed project and pull it in, per domain or all at once, and update canon itself
 category: Agent surface
 ---
 
 # Target sync
 
-A target pulls toolkit changes per domain, through one catch-all and several targeted entry points. A project scaffolded before a layout move runs [target migrations](migrations.md) first. See [install and sync](../agents/install-and-sync.md) for what each verb writes.
+A target pulls toolkit changes per domain, through one catch-all and several targeted entry points. A project scaffolded before a layout move runs [target migrations](../migrations/index.md) first. See [install and sync](../agents/install-and-sync.md) for what each verb writes.
 
 ## Check first
 
@@ -36,6 +36,26 @@ Attribution reads `canon/config/config.json`, falling back to `.claude/canon/con
 
 Add `--json` for a machine-readable report and `--exit-code` to fail CI when a target falls behind. Project-authored files, superseded artifacts, seed drift, tooling, and `reverse` never count toward that code, and an unmigrated domain does.
 
+## Update canon itself
+
+Nothing refreshes on its own. Claude Code ships auto-update off for third-party marketplaces, so an installed copy serves whatever version it was installed at until you refresh it.
+
+```bash
+claude plugin marketplace update canon
+claude plugin update canon@canon
+canon upgrade
+```
+
+The first two update the skills, the third updates the CLI, and they move independently. Restart Claude Code, or run `/reload-plugins`, to pick the skills up.
+
+`canon upgrade` reads the package manager off its own install path and reinstalls with that one. It names what it detected before it runs anything, and it refuses a source checkout rather than reinstalling over your clone.
+
+### Checking for drift
+
+`canon sync --check` and `canon claude skills drift` both report the installed version against the newest published one, and neither changes its exit code over it, so an offline machine reads unknown rather than red.
+
+To stop doing this by hand, turn auto-update on once under `/plugin` in the Marketplaces tab. Confirm what you are running with `canon --version` and `claude plugin list`.
+
 ## Catch-all
 
 `canon sync <path>` runs every installed domain's sync and never touches user-owned seeds.
@@ -48,7 +68,7 @@ Add `--json` for a machine-readable report and `--exit-code` to fail CI when a t
 - 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.
+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:ui-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.
 

package/docs/workflow/ai-workflow.md

@@ -27,7 +27,7 @@ canon/
 └── tmp/             ← deletable scratch
 ```
 
-A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root. See [target migrations](../target/migrations.md).
+A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root. See [target migrations by verb](../migrations/by-verb.md).
 
 Context loads always (`CLAUDE.md` and `canon/REQUIREMENTS.md`), by path (`.claude/rules/` with a `paths:` glob), or on demand (`canon/context/`, found through its `index.md`). Run `canon init` to seed `.claude/`, `CLAUDE.md`, and the rules.
 

package/docs/workflow/skill-map-on-request.md

@@ -15,11 +15,10 @@ These skills serve a request rather than a moment. With the [skill map](skill-ma
 | `canon:create-rule`     | A project rule the toolkit does not ship          |
 | `canon:create-skill`    | A new `SKILL.md`                                  |
 | `canon:write-doc`       | A new `docs/` page, context entry, or `README.md` |
-| `canon:plan-ready`      | Finished files a worker should copy               |
 | `canon:draw-figure`     | A figure or architecture view inside a doc        |
 | `canon:ci-workflow`     | A GitHub Actions workflow file                    |
 | `canon:design-identity` | A logo mark and social card                       |
-| `canon:ui-record`       | Real footage of the app for a video               |
+| `canon:ui-film`         | Real footage of the app for a video               |
 
 ## Answer a question at any point
 

package/docs/workflow/skill-map.md

@@ -24,7 +24,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | `canon:backlog-triage`     | The backlog needs pruning                          |
 | `canon:plan-groundwork`    | The state is unmeasured and approaches compete     |
 | `canon:decision-escalate`  | Open decisions turn on your preference             |
-| `canon:pick-by-eye`        | The call is taste, wanting candidates side by side |
+| `canon:design-pick`        | The call is taste, wanting candidates side by side |
 | `canon:task-board`         | A decided item needs a file on the board           |
 | `canon:plan-feature`       | The approach is settled and needs a plan           |
 | `canon:codebase-layout`    | A change adds a file and needs a folder            |
@@ -53,8 +53,8 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | Skill                   | When to use                                    |
 | ----------------------- | ---------------------------------------------- |
 | `canon:document-health` | Documents must answer for length and staleness |
-| `canon:ux-audit`        | To read UI source for missing states           |
-| `canon:ux-measure`      | To measure paint, processor, and layout cost   |
+| `canon:ui-audit`        | To read UI source for missing states           |
+| `canon:ui-measure`      | To measure paint, processor, and layout cost   |
 | `canon:app-drive`       | To drive a built app with the operator         |
 
 ## Ship it
@@ -100,10 +100,9 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 
 ## Keep the project current with the toolkit
 
-| Skill                         | When to use                                             |
-| ----------------------------- | ------------------------------------------------------- |
-| `canon:target-check`          | In a target, to compare each domain with the toolkit    |
-| `canon:target-update`         | After a release, to catch a target up to the toolkit    |
-| `canon:document-repair`       | Rewrite a failing docs folder to the limits and gate it |
-| `canon:canon-feedback`        | The toolkit is broken, missing, or off                  |
-| `canon:canon-feedback-triage` | In the toolkit repo, to file feedback issues            |
+| Skill                   | When to use                                             |
+| ----------------------- | ------------------------------------------------------- |
+| `canon:target-check`    | In a target, to compare each domain with the toolkit    |
+| `canon:target-update`   | After a release, to catch a target up to the toolkit    |
+| `canon:document-repair` | Rewrite a failing docs folder to the limits and gate it |
+| `canon:canon-feedback`  | The toolkit is broken, missing, or off                  |

package/docs/workflow/visual-design-workflow.md

@@ -72,7 +72,12 @@ A close posts as `## UI review closed`. The reviewers lift the draft mark on the
 
 ## Design authoring
 
-Most projects author design in the loop above and need nothing more. Start with `canon:pick-by-eye`, which drafts candidates as frames on a [Frameboard](https://www.npmjs.com/package/frameboard) board and takes your pick, then record the pick with `canon:design-record`. `canon:design-identity` drafts a logo mark and social card the same way.
+Most projects author design in the loop above and need nothing more. Start with `canon:design-pick`, which drafts candidates as frames on a [Frameboard](https://www.npmjs.com/package/frameboard) board and takes your pick, then record the pick with `canon:design-record`. `canon:design-identity` drafts a logo mark and social card the same way.
+
+A pick round drafts on `.canon/board/` unless the project names another board in `canon/config/design.toml`.
+
+- Set `board` when your design sync reads another Frameboard board, so the picked frame lands without a redraw.
+- Leave `project` unset to keep rounds in their own `picks` project on that board.
 
 A graphical tool earns its place when design is the product, a designer owns it, and it changes more often than code. Then the tool is the source of truth, and `canon/DESIGN.md` carries a top note naming the upstream project.
 

package/governance/ledger/claude/background.md

@@ -0,0 +1,26 @@
+---
+title: Background rule ledger
+description: Decisions behind governance/rules/claude/background.md, one row per bullet
+---
+
+# Background rule ledger
+
+The rule is a core rule, so every row is a house choice rather than a citation. Each names what goes wrong without its bullet and the option the bullet beat, with the date it was decided.
+
+## Slow commands
+
+| Bullet                            | Source                                                                                                                                                                                         | Read       |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Background past about a minute    | House choice: a foreground run holds the conversation, so the operator waits on a check they could have talked over. It beat a warning hook, which would only warn and still let the run block | 2026-10-26 |
+| Name the slow kinds               | House choice: a minute is a guess made before the run, and with no cases to match a session reads a full check as quick. It beat the threshold alone                                           | 2026-10-26 |
+| Keep a seconds command foreground | House choice: each wake costs a turn, so backgrounding a quick command spends two turns where one did. It beat backgrounding every command                                                     | 2026-10-26 |
+| End the turn on one status line   | House choice: a turn that stops silently leaves the operator unable to tell a wait from a stall. It beat ending on the tool call alone                                                         | 2026-10-26 |
+| Keep working beside a server      | House choice: a dev server or a watch never exits, so a session awaiting its wake waits forever. It beat treating every background command as awaited                                          | 2026-10-26 |
+
+## Waking
+
+| Bullet                            | Source                                                                                                                                                                                | Read       |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Act on the wake, never a guess    | House choice: a session guessing a command is done reads a partial output as the result. It beat checking the output file on a hunch                                                  | 2026-10-26 |
+| No sleep, poll, or scheduled wait | House choice: a foreground sleep or poll holds the conversation the rule freed, and a scheduled prompt spends a turn on every check. It beat all three as ways to wait on one command | 2026-10-26 |
+| Keep a skill's own wait           | House choice: a skill owns the verb and the timeout it waits on, such as a review-state wait, and one rule-wide wait would override it. It beat a single wait for every caller        | 2026-10-26 |

package/governance/ledger/skills/ui-craft/copy.md

@@ -13,10 +13,13 @@ The four casing sections rest on the GOV.UK style guide, which sets sentence cas
 
 ## Punctuation
 
-| Bullet                        | Source                                                                                                                                                                  | Read       |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| No em dash or semicolon       | House choice: both read as generated copy in an interface, and a comma, a period, or a split sentence carries the same meaning in a shorter line                        | 2026-10-18 |
-| No trailing label punctuation | [Button](https://design-system.service.gov.uk/components/button/): every example label, such as "Start now", "Sign in", and "Continue", carries no trailing punctuation | 2026-10-18 |
+| Bullet                                 | Source                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Read       |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| No em dash or semicolon                | House choice: both read as generated copy in an interface, and a comma, a period, or a split sentence carries the same meaning in a shorter line                                                                                                                                                                                                                                                                                                                                                                                                                                                  | 2026-10-18 |
+| No end punctuation but a question mark | [A to Z of GOV.UK style](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style): page titles should "not have a full stop at the end", and [Button](https://design-system.service.gov.uk/components/button/) labels such as "Start now" and "Continue" carry none. Every other kind in the list, from headings to taglines, is a house choice by analogy to the title and the button. [Question pages](https://design-system.service.gov.uk/patterns/question-pages/) keep the question mark, since "Page headings can be questions or statements", as in "What is your date of birth?". | 2026-10-27 |
+| One-sentence tagline                   | House choice: a period inside a tagline makes it prose, which the short-string rule then has to end with a period, so one sentence keeps it a title-like string                                                                                                                                                                                                                                                                                                                                                                                                                                   | 2026-10-27 |
+| One-sentence error, no period          | [Error message](https://design-system.service.gov.uk/components/error-message/): every example, such as "Enter how many hours you work a week" and "Name must be 35 characters or less", ends with no full stop                                                                                                                                                                                                                                                                                                                                                                                   | 2026-10-27 |
+| Prose keeps its period                 | House choice by analogy to [A to Z of GOV.UK style](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style), whose summaries should "end with a full stop". The reach to body copy, multi-sentence messages, and quoted text is canon's.                                                                                                                                                                                                                                                                                                                                                  | 2026-10-27 |
 
 ## Button copy
 
@@ -86,6 +89,7 @@ Every bullet the rewrite removed or reshaped, grouped by why.
 
 ### Merged or reworded
 
+- Widened the button-label punctuation bullet to every short rendered string, since board frames shipped tagline periods under the narrower wording.
 - Merged the imperative verb and padded phrasing bullets. The `Save` over `Save changes` example went, since GOV.UK adds words "to better describe the action".
 - Merged "keep messages short and actionable" and "one sentence maximum" into the plain language bullet.
 - Reworded the error example to `Enter an email address`, the instruction form GOV.UK prefers over a description.

package/governance/rules/claude/background.md

@@ -0,0 +1,19 @@
+---
+description: Run a command that may take more than about a minute in the background and resume on the harness wake, so the operator keeps the conversation
+---
+
+# Background standards
+
+## Slow commands
+
+- Start a command that may run past about a minute with `run_in_background: true`, since a foreground run holds the conversation. Revisit when a foreground Bash call stops blocking the turn.
+- Treat a full check, a sandbox run, a capture or render, a build, and a wait on another session as slow.
+- Keep a command expected to finish in seconds in the foreground, since each wake costs a turn.
+- End the turn on one line naming what runs, when the next step needs that command's result.
+- Keep working beside a server or a watch the session never waits on, since it never exits and its wake never comes.
+
+## Waking
+
+- Act on the wake the harness sends when an awaited command exits, never on a guess about when it is done. Revisit when a background Bash command stops waking the session at exit.
+- Never wait with a foreground `sleep`, a foreground poll loop, or a scheduled prompt for one wait. The background run and its wake replace all three.
+- Keep a skill's own wait as the skill states it, since the skill owns the verb and the timeout it waits on.

package/governance/stacks/base.toml

@@ -12,4 +12,5 @@ rules = [
   "tasks",
   "plan",
   "markdown",
+  "background",
 ]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.68.0",
+  "version": "5.70.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -25,9 +25,9 @@
     "access": "public"
   },
   "scripts": {
-    "format": "oxfmt . && prettier --write --log-level warn 'web/**/*.astro' && shfmt --write --indent 2 scripts/ tooling/ claude/",
-    "check:format": "oxfmt --check . && prettier --check --log-level warn 'web/**/*.astro' && shfmt --diff --indent 2 scripts/ tooling/ claude/",
-    "check:shell": "find scripts tooling claude .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} + && find .husky -maxdepth 1 -type f -exec shellcheck --severity=warning --shell=sh {} +",
+    "format": "oxfmt . && prettier --write --log-level warn 'web/**/*.astro' && shfmt --write --indent 2 scripts/ tooling/ claude/ src/",
+    "check:format": "oxfmt --check . && prettier --check --log-level warn 'web/**/*.astro' && shfmt --diff --indent 2 scripts/ tooling/ claude/ src/",
+    "check:shell": "find scripts tooling claude src .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} + && find .husky -maxdepth 1 -type f -exec shellcheck --severity=warning --shell=sh {} +",
     "check:lint": "oxlint --disable-nested-config --max-warnings 0",
     "check:types": "tsc --noEmit",
     "check:install": "bun scripts/core/install-check.ts",
@@ -42,6 +42,8 @@
     "canon:sandbox:reset": "canon sandbox reset",
     "web:tokens": "bun src/cli.ts design css --no-components > web/src/styles/tokens.css.new && (echo '/* Generated by `canon design css --no-components`. Regenerate with `bun run web:tokens`. Do not hand-edit. */'; cat web/src/styles/tokens.css.new) > web/src/styles/tokens.css && rm web/src/styles/tokens.css.new",
     "web:dev": "cd web && astro dev",
+    "film:render": "bun scripts/core/render-film.ts",
+    "design:sync": "bun scripts/core/design-sync.ts",
     "web:favicon": "bun scripts/core/regen-web-favicon.ts",
     "web:previews": "bun scripts/core/regen-web-previews.ts",
     "web:build": "bun run web:tokens && bun run web:favicon && bun run web:previews && cd web && astro check && astro build",

package/scripts/ci/install-playwright-deps.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Installs the Playwright system packages for the named browsers, killing an
+# attempt that outlives its bound and retrying it. A degraded apt mirror hangs
+# one connection rather than failing it, so a step timeout alone turns the
+# hang into a red check and never recovers it, while a fresh attempt usually
+# lands on a healthy backend.
+#
+# Usage: install-playwright-deps.sh [--package <spec>] <browser>...
+# Exits 0 on the first success, 2 when no browser is named, and the last
+# attempt's code when every attempt fails.
+set -e
+
+package=playwright
+if [ "$1" = "--package" ]; then
+  package=$2
+  shift 2
+fi
+
+if [ $# -eq 0 ]; then
+  echo "Usage: install-playwright-deps.sh [--package <spec>] <browser>..." >&2
+  exit 2
+fi
+
+attempts=3
+bound=${INSTALL_ATTEMPT_SECONDS:-150}
+
+# The runner image sets these, yet a stalled log shows gaps of minutes, so
+# print what apt actually reads to settle whether they took effect
+apt-config dump | grep -E '^Acquire::(Retries|http::Timeout) ' || true
+
+status=0
+for attempt in $(seq 1 "$attempts"); do
+  if [ "$attempt" -gt 1 ]; then
+    # timeout runs as the runner user, and Linux drops its signal to the root
+    # apt-get playwright spawns through sudo. sudo relays it only to its own
+    # child shell, so a root apt-get or dpkg can outlive the kill and hold the
+    # lock the next attempt needs.
+    sudo pkill -KILL -x 'apt-get|dpkg' || true
+    # A kill during unpack leaves dpkg interrupted, which refuses the next
+    # install. Its own failure must not end the loop.
+    sudo dpkg --configure -a || echo "dpkg --configure -a failed before attempt ${attempt}" >&2
+  fi
+
+  status=0
+  timeout --kill-after=10 "$bound" bunx "$package" install-deps "$@" || status=$?
+  if [ "$status" -eq 0 ]; then
+    exit 0
+  fi
+  echo "attempt ${attempt}/${attempts} failed with exit ${status}" >&2
+done
+
+exit "$status"