@erclx/canon 5.58.0 → 5.60.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [5.60.0](https://github.com/erclx/canon/compare/v5.59.0...v5.60.0) (2026-10-24)
+
+
+### Features
+
+* **design:** add canon design audit verb ([#2661](https://github.com/erclx/canon/issues/2661)) ([303a52a](https://github.com/erclx/canon/commit/303a52ada294d9740205885336b6f1ce006ddbba))
+* **skills:** reach design-taste in planner and later review passes ([#2657](https://github.com/erclx/canon/issues/2657)) ([dedc351](https://github.com/erclx/canon/commit/dedc35132a57cf8f82e9a25603e6128e0c77d6ed))
+* **tooling:** bound the dev dependency install ([#2666](https://github.com/erclx/canon/issues/2666)) ([09017a6](https://github.com/erclx/canon/commit/09017a6bfcf11d3feffa1eccfa1ec99f8a0ff3ae))
+
+
+### Bug Fixes
+
+* **sync:** drop retired domains when reading the stamp ([#2664](https://github.com/erclx/canon/issues/2664)) ([21e0a1c](https://github.com/erclx/canon/commit/21e0a1cccfcab13dba5e50e3a55ea620d0d77907))
+
+## [5.59.0](https://github.com/erclx/canon/compare/v5.58.0...v5.59.0) (2026-10-24)
+
+
+### Features
+
+* **cli:** name the release that retired a verb and find its callers ([#2662](https://github.com/erclx/canon/issues/2662)) ([32fddb5](https://github.com/erclx/canon/commit/32fddb5f8c363441fc18ffb4243c08a65a863a67))
+* **gov:** report rule coverage after gov sync ([#2660](https://github.com/erclx/canon/issues/2660)) ([c087965](https://github.com/erclx/canon/commit/c087965acd64249f8dfbe9ca1d98a7857621d380))
+* **pr:** compose bot pull request merge messages ([#2659](https://github.com/erclx/canon/issues/2659)) ([698991c](https://github.com/erclx/canon/commit/698991c71b6423279756f023c86cd2537ae46017))
+* **sandbox:** add a canon-feedback-triage anchor scenario ([#2656](https://github.com/erclx/canon/issues/2656)) ([ae45573](https://github.com/erclx/canon/commit/ae45573e2b385b97cdfbf300b4d1f9bb0f3db839))
+
+
+### Bug Fixes
+
+* **sync:** write the stamp in the formatter shape ([#2655](https://github.com/erclx/canon/issues/2655)) ([a34c5fb](https://github.com/erclx/canon/commit/a34c5fb2d18314ec31d83640be387057b68638a7))
+
 ## [5.58.0](https://github.com/erclx/canon/compare/v5.57.0...v5.58.0) (2026-10-24)
 
 

package/README.md

@@ -140,7 +140,7 @@ Bun, Git, and a shell are required, and the GitHub CLI is optional.
 - [Bun](https://bun.sh) for the CLI runtime and scripts
 - [Git](https://git-scm.com) with worktree support
 - [GitHub CLI](https://cli.github.com) (optional) for ship flows
-- Shell: `zsh` or bash 4+ (`brew install bash` on macOS).
+- Shell: `zsh`, since bootstrap appends its aliases to `~/.zshrc`.
 
 Clone the repo, then run the bootstrap script. It installs dependencies, links the CLI globally, and appends a marked block of Claude Code shell aliases to your `~/.zshrc`.
 

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

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, read the requirements record for identity drift when the scope reaches it, and print the `canon records stale canonical` reminder
+- 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`
 
 ## Must not
 

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

@@ -60,6 +60,16 @@ A refusal, an absent key, and a subcommand the project's binary does not carry e
 - `canon context audit` refuses with `reason: "no-folders"` where the layout is not the expected one. Reading that honest refusal as an empty finding set reports a healthy corpus nothing looked at.
 - A narrower read is not an unread one. The sweep running on its regex layer alone still answered, so report it with the layer named.
 
+### The design record
+
+`canon/DESIGN.md` reads outside both verbs above, since neither measures its prose budget or its tokens. When the scope reaches it, read it through its own verb:
+
+```bash
+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`.
+
 ## Step 3: read the staleness axis
 
 No verb answers whether a document still describes the tree it was written about. Read each document against the surfaces it names and report where the two have parted, taking the file paths, commands, and counts it states as the claims to test.
@@ -121,3 +131,12 @@ Structure `canon/context/surfaces/`: `cli.md` (300 lines) splits into `cli.md` t
 The line is a proposal for the operator, with the headings each entry takes and why. Health applies nothing, and `document-repair` offers the proposal before it rewrites.
 
 Keep the evidence line under the table on every run. A table read without it flattens a judgment into a measurement, which is the one shape the three classes exist to prevent.
+
+### The design record row
+
+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
+- 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

@@ -73,6 +73,24 @@ Both verbs resolve their folders by surface root rather than by a path written i
 - The audit refuses with `reason: "no-folders"`, naming the folders it looked for. Report that refusal as an unread axis.
 - The sweep with the model layer off answers from its regex layer alone, a narrower read rather than a refusal, so say which layer answered
 
+## The design record
+
+| Field          | Value                                                                                            |
+| -------------- | ------------------------------------------------------------------------------------------------ |
+| Measures       | Whether the design record holds to its prose budget and names only properties its stylesheet has |
+| Verb           | `canon design audit --json`                                                                      |
+| Evidence class | `measured`                                                                                       |
+
+The record is exempt from the length and placement verbs above, so this is the only measured read it gets.
+
+- `prose`: each place the record passes the budget, with the count and the cap it was read against. Take the caps from the finding rather than from a number written here.
+- `tokens.missing`: a custom property a table names that the stylesheet the lead names does not declare
+- `tokens.status: "unchecked"`: the lead names no stylesheet, or the one it names does not resolve. Report the axis as unread with the `reason`, since nothing was compared.
+- `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
+
+**Routes to:** `design-record`, which owns the record's shape. `document-repair` rewrites a context folder and does not know the budget.
+
 ## Staleness
 
 | Field          | Value                                                            |

package/claude/skills/plan-feature/SKILL.md

@@ -38,7 +38,7 @@ Read these in parallel from the project root, skipping any that do not exist:
 
 Also read `canon/DESIGN.md` when the feature touches code or UI, for visual intent and component rules, with values read from the stylesheet its lead names. Skip it for prose, docs, catalog, or config-only changes. For a UI feature, read `canon/design/index.md` too, if it exists, for the surfaces with an accepted design.
 
-Coding standards live in `.claude/rules/`. Claude Code loads them automatically, and path-scoped rules apply to the files they match.
+Coding standards live in `.claude/rules/`. Claude Code loads them automatically, and path-scoped rules apply to the files they match. For a UI feature, load `canon:design-taste` whether or not `canon/DESIGN.md` exists.
 
 ### Read the domain's context entry
 

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

@@ -78,7 +78,7 @@ Read these in parallel from the project root, skipping any that do not exist:
 - `.canon/tasks/priority.md`: where this feature sits on the board and what each neighbor waits on, resolved at the main root the way `session-worktree` does, since a linked worktree holds no copy
 - `.canon/plans/feature-<slug>.md` for the branch, when present: the intent the PR should satisfy, and its `**Review focus:**` section as the inputs this pass must confirm the diff handles
 
-Coding standards from `.claude/rules/` are auto-loaded by Claude Code.
+Coding standards from `.claude/rules/` are auto-loaded by Claude Code for the files a first pass reads. A path-scoped rule loads only when a session reads a matching file, so a later pass opens each changed file through the Read tool per `references/scope.md`, which loads the rules its trunk path matches and names the gap for an added file.
 
 ## Step 2: scope the read
 

package/claude/skills/review-pr/references/scope.md

@@ -117,3 +117,13 @@ Carry `<prior-heading>` into Step 4 and run Step 3 unchanged. This guard turns o
 ## The read
 
 Read each changed file in scope. Skip deleted files. Run reads in parallel.
+
+### Load the path-scoped rules on a later pass
+
+A path-scoped rule loads when a session uses the Read tool on a matching file, and a Bash call such as `git show` loads none. A later pass reads only `<prior-oid>..<headRefOid>`, so the head copy of each changed file has to reach the Read tool.
+
+- Open the trunk path with the Read tool when it exists, as the trigger, and take the content from `git show <headRefOid>:<path>`, since trunk content is stale
+- For an added file, write its head blob to `.canon/tmp/pr/review/head-read/<number>-<short-sha>/<path>`, in the review body folder, then open that copy with the Read tool
+- The copy loads only `**/` globs, since a root-anchored glob such as `canon/design/**` misses its prefix, so an added file under one loads no rule
+- Read only files the range changed, never the whole tree, so the cost stays bounded by the range
+- A range whose only change is a deletion has no file to read, so skip it and carry on

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

@@ -64,6 +64,8 @@ Target update: `<path>`, canon `<installed>` to `<running>`.
 
 **Migrations, in run order:** <each pending or refused entry from migrate status, with its verb>
 
+**Retired calls:** <each `retiredCallers` entry from migrate status, with its file, line, the release that retired the verb, and where the work went, or omitted when the list is empty>
+
 **Drift:** <each non-empty cause from sync --check, with its count and paths>
 
 **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>
@@ -73,11 +75,13 @@ Target update: `<path>`, canon `<installed>` to `<running>`.
 **Commands, in order:** <the exact commands Steps 4 to 6 will run>
 ```
 
+A retired call is no migration, so no step here fixes it. Name it in the preview and leave the edit to the operator, who owns the script.
+
 Summarize the changelog for this project, not for the toolkit. Drop an entry that touches nothing the target holds, and lead with anything a migration or a sync will change.
 
 ### Nothing pending
 
-When the changelog range is empty, `migrate status` lists nothing pending or refused, and the drift lines hold nothing a step here would take, write nothing. Invoke `canon:target-check` and report the target current with its table.
+When the changelog range is empty, `migrate status` lists nothing pending or refused and no `retiredCallers`, and the drift lines hold nothing a step here would take, write nothing. Invoke `canon:target-check` and report the target current with its table.
 
 ### Take a branch after the go-ahead
 

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

@@ -24,7 +24,7 @@ A flat installed-rule layout makes `gov sync` report "No governance surfaces fou
 
 ## Governance sync
 
-`canon gov sync [target]` updates what `.claude/rules/canon/` holds and adds nothing. `.claude/rules/project/` is never read, so put project rules there.
+`canon gov sync [target]` updates what `.claude/rules/canon/` holds and adds nothing. `.claude/rules/project/` is never read, so put project rules there. After an apply it lists each copied rule with its globs and matching file count, and `--json` puts `{ "coverage": [...] }` on stdout.
 
 - A rule the toolkit no longer ships is deleted, edited or not
 - A rule renamed in `governance/renames.toml` moves, and its local edits are dropped

package/docs/agents/migrate.md

@@ -38,6 +38,12 @@ kind: reference
 
 `status` runs each verb as a dry run and exits 2 while any is pending, with a refusal outranking that. Each entry's `verb` carries the flags its dry run used, so append `--write` to it. A clean entry can turn pending once an earlier one applies, so run it again after each `--write`.
 
+`status --json` also carries `retiredCallers`, the project calls to a verb a release retired.
+
+- Each entry has `file`, `line`, `verb`, `release`, and `movedTo`
+- The scan reads the workflow folder, the `package.json` scripts, `scripts/`, and the files those name, matching a command line or an argument list and never prose
+- A caller changes no exit code, since no `--write` fixes one, so edit the script by hand
+
 Three markers keep an old spelling on a line. Each also covers the nearest non-blank line, below it for `canon-keep-record-root` and above it for `canon-keep-surface-root`.
 
 | Marker                    | Keeps                                          |

package/docs/target/sync.md

@@ -43,10 +43,12 @@ Add `--json` for a machine-readable report and `--exit-code` to fail CI when a t
 ## Targeted
 
 - 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
+- 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
 - 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.
 
 ## Running sync from an agent session

package/docs/workflow/operating-model.md

@@ -36,7 +36,7 @@ Each role keeps to its own writes, and five rules cover how the roles meet.
 7. A pass posts `## Review` while anything is open and `## Review closed` when nothing is. The reviewer then runs `canon pr lift`.
 8. The human merges with `canon pr merge <number>`. The orchestrator tells any trailing worker whose files the merge touched to run `review-address`, which rebases.
 
-Each worker halts at the PR, and the merge stays a human gate. `canon pr merge` squashes with the body's Summary, Key changes, and Technical context as the message, and the seeded deny rule covers the forms an agent writes by default. The merge button stays for a bot's pull request, such as a dependency bump or a release.
+Each worker halts at the PR, and the merge stays a human gate. `canon pr merge` squashes with the body's Summary, Key changes, and Technical context as the message, and the seeded deny rule covers the forms an agent writes by default. A release-please or Dependabot pull request merges the same way, from the bot's own body.
 
 ## The review layer
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.58.0",
+  "version": "5.60.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -30,14 +30,14 @@
     "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 {} +",
     "check:lint": "oxlint --disable-nested-config --max-warnings 0",
     "check:types": "tsc --noEmit",
-    "check:install": "./scripts/core/install-check.sh",
+    "check:install": "bun scripts/core/install-check.ts",
     "test": "bun --bun vitest run",
     "prepare": "husky",
     "check": "bun src/cli.ts gate run",
     "check:ci": "bun src/cli.ts gate run --all",
     "update": "bun update --interactive && bun run check",
     "clean": "rm -rf node_modules && bun pm cache rm && bun install",
-    "bootstrap": "./scripts/core/bootstrap.sh",
+    "bootstrap": "bun scripts/core/bootstrap.ts",
     "canon:sandbox": "canon sandbox",
     "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",

package/scripts/core/bootstrap.ts

@@ -0,0 +1,120 @@
+/**
+ * Installs dependencies, links the canon CLI globally, and appends the marked
+ * alias block to the user's `.zshrc`, the only file this writes outside the
+ * repository. Runs on Bun alone, so a stock macOS bash 3.2 never enters it.
+ */
+import { appendFileSync, existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  intro,
+  logAdd,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+} from '../../src/cli/ui'
+
+const root = fileURLToPath(new URL('../..', import.meta.url)).replace(/\/$/, '')
+
+const MARKER_OPEN = '# >>> canon aliases >>>'
+const MARKER_CLOSE = '# <<< canon aliases <<<'
+
+function zshrcPath(): string {
+  const dir = process.env.ZDOTDIR
+  return join(dir !== undefined && dir !== '' ? dir : homedir(), '.zshrc')
+}
+
+/** `$TOOLKIT` stays a literal in the block, so the shell expands it on load. */
+function aliasBlock(): string {
+  return `${MARKER_OPEN}
+TOOLKIT="${root}"
+export CLAUDE_CODE_ENABLE_TODO_TOOLS=1
+
+alias cl='claude'
+alias clr='cl -r'
+alias clc='cl -c'
+alias clw='cl -w'
+alias cls='cl --model sonnet'
+
+alias clp='claude --plugin-dir $TOOLKIT/claude'
+alias clpc='clp -c'
+alias clps='clp --model sonnet'
+alias clpa='clp agents'
+alias clpac='clpa --cwd .'
+${MARKER_CLOSE}`
+}
+
+function run(step: string, cmd: string[]): void {
+  const result = Bun.spawnSync(cmd, {
+    cwd: root,
+    stdout: 'ignore',
+    stderr: 'pipe',
+  })
+  if (result.exitCode !== 0) {
+    throw new Error(`${step} failed: ${result.stderr.toString().trim()}`)
+  }
+}
+
+function installCli(): void {
+  logStep('Installing the canon CLI')
+  run('bun install', ['bun', 'install', '--cwd', root])
+  run('bun link', ['bun', 'link', '--cwd', root])
+  logInfo('Dependencies installed and canon linked')
+}
+
+function installAliases(): void {
+  const zshrc = zshrcPath()
+  logStep('Installing Claude Code shell aliases')
+  logInfo(
+    `This step manages a marked alias block in ${zshrc}, the only file outside the repo this script writes.`,
+  )
+  logInfo(
+    'Delete the block and its two marker comments to remove the aliases. Re-running never adds a second copy.',
+  )
+
+  const existing = existsSync(zshrc) ? readFileSync(zshrc, 'utf8') : ''
+  if (existing.includes(MARKER_OPEN)) {
+    logInfo(`Aliases already present in ${zshrc}, skipping`)
+    return
+  }
+  if (/^alias clp=/m.test(existing)) {
+    logWarn(
+      `An unmanaged clp alias is already in ${zshrc}. Leaving it untouched.`,
+    )
+    logWarn('Remove it and re-run to switch to the managed block.')
+    return
+  }
+
+  appendFileSync(zshrc, `\n${aliasBlock()}\n`)
+  logAdd(`Appended canon alias block to ${zshrc}`)
+  logInfo(`Run 'source ${zshrc}' or open a new shell to load them`)
+}
+
+function verifyCli(): void {
+  logStep('Verifying the install')
+  if (Bun.which('canon') !== null) {
+    logInfo('canon resolves on PATH')
+  } else {
+    logWarn(
+      'canon not on PATH yet. Ensure $BUN_INSTALL/bin is exported, then re-open your shell.',
+    )
+  }
+}
+
+intro('canon bootstrap')
+let failed = false
+try {
+  installCli()
+  installAliases()
+  verifyCli()
+} catch (error) {
+  failed = true
+  logError(error instanceof Error ? error.message : String(error))
+} finally {
+  outro()
+}
+process.exit(failed ? 1 : 0)

package/scripts/core/install-check.ts

@@ -0,0 +1,193 @@
+/**
+ * Verifies the published install path end to end: packs this repo, installs
+ * the tarball for production, and runs `canon init` from it into a fresh
+ * project. Runs on Bun alone.
+ */
+import { existsSync, mkdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  intro,
+  logError,
+  logInfo,
+  logStep,
+  outro,
+  pipeOutput,
+} from '../../src/cli/ui'
+
+const root = fileURLToPath(new URL('../..', import.meta.url)).replace(/\/$/, '')
+const tmpRoot = join(root, '.canon/tmp/install-check')
+const packDir = join(tmpRoot, 'pack')
+const extractDir = join(tmpRoot, 'extract')
+const targetDir = join(tmpRoot, 'target')
+
+const HELP = `Usage: scripts/core/install-check.ts [--keep]
+
+Verifies the published install path end to end:
+  1. Packs this repo into a tarball at .canon/tmp/install-check/pack
+  2. Extracts it and asserts sandbox is absent from the tree
+  3. Runs bun install --production in the extracted tree
+  4. Runs the CLI with --help from the extracted tree to confirm it resolves
+  5. Scaffolds a fresh project in .canon/tmp/install-check/target
+  6. Runs canon init from the extracted package and asserts a scaffold landed
+
+Flags:
+  --keep    Keep the tmp tree on exit for inspection
+`
+
+/**
+ * Every domain canon init installs needs at least one path here. A domain with
+ * no assertion can truncate silently: init still exits 0 because run_domain
+ * catches a failed domain, and the gate stays green while the target is
+ * missing everything that domain provides.
+ *
+ * Authoring references name no path because they ship inside the plugin's
+ * skills rather than installing into a target. The two rule paths stand for
+ * the `claude` and `canon` groups `base` takes whole.
+ */
+const SCAFFOLD_PATHS = [
+  'CLAUDE.md',
+  '.claude',
+  'canon/context/index.md',
+  '.oxfmtrc.json',
+  '.lintstagedrc',
+  '.husky/pre-commit',
+  '.github/workflows/verify.yml',
+  'scripts/verify.ts',
+  '.claude/rules/canon/claude/output.md',
+  '.claude/rules/canon/canon/scratch.md',
+]
+
+const args = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(HELP)
+  process.exit(0)
+}
+const keep = args.includes('--keep')
+
+/** Runs a command to completion, showing its output inside the frame. */
+function run(
+  failure: string,
+  cmd: string[],
+  opts: { cwd?: string; show?: boolean } = {},
+): string {
+  const result = Bun.spawnSync(cmd, {
+    cwd: opts.cwd ?? root,
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const stdout = result.stdout.toString()
+  const output = `${stdout}${result.stderr.toString()}`.trim()
+  if (opts.show && output !== '') pipeOutput(output)
+  if (result.exitCode !== 0) {
+    if (!opts.show && output !== '') pipeOutput(output)
+    throw new Error(failure)
+  }
+  return stdout
+}
+
+function check(): void {
+  logStep('Assert excluded path exists in source')
+  // An absence check over a path the source tree no longer holds passes on
+  // nothing, so the excluded tree has to exist here before its absence below
+  // can mean the publish left it out.
+  if (!existsSync(join(root, 'sandbox/exempt.toml'))) {
+    throw new Error(
+      'sandbox/exempt.toml is missing from the source tree, so the absence check below would pass on nothing',
+    )
+  }
+  logInfo('Present: sandbox/exempt.toml')
+
+  logStep('Pack')
+  const packed = run('bun pm pack failed', [
+    'bun',
+    'pm',
+    'pack',
+    '--quiet',
+    '--ignore-scripts',
+    '--destination',
+    packDir,
+  ])
+  const tarball = packed.trim().split('\n').pop() ?? ''
+  logInfo(`Packed to ${tarball}`)
+
+  logStep('Extract')
+  run('tar extract failed', [
+    'tar',
+    '-xzf',
+    tarball,
+    '-C',
+    extractDir,
+    '--strip-components=1',
+  ])
+  logInfo(`Extracted to ${extractDir}`)
+
+  logStep('Assert excluded path is absent')
+  if (existsSync(join(extractDir, 'sandbox'))) {
+    throw new Error(
+      'sandbox shipped in the tarball, and the files field in package.json leaves it out',
+    )
+  }
+  logInfo('Absent: sandbox')
+
+  logStep('Install dependencies (production)')
+  run(
+    'bun install --production failed',
+    ['bun', 'install', '--production', '--ignore-scripts', '--silent'],
+    { cwd: extractDir, show: true },
+  )
+  logInfo('Dependencies installed without devDependencies')
+
+  logStep('Confirm CLI runs')
+  run('canon --help failed', ['bun', 'run', 'src/cli.ts', '--help'], {
+    cwd: extractDir,
+  })
+  logInfo('canon --help ran clean from the extracted package')
+
+  logStep('Scaffold fresh project')
+  mkdirSync(targetDir, { recursive: true })
+  run('git init failed', ['git', 'init', '--quiet'], { cwd: targetDir })
+  logInfo(`Initialized git in ${targetDir}`)
+
+  logStep('Run canon init')
+  run(
+    'canon init failed',
+    ['bun', 'run', join(extractDir, 'src/cli.ts'), 'init', '--stack', 'base'],
+    { cwd: targetDir, show: true },
+  )
+  logInfo('canon init completed')
+
+  logStep('Assert scaffold')
+  for (const path of SCAFFOLD_PATHS) {
+    if (!existsSync(join(targetDir, path))) {
+      throw new Error(`Missing after canon init: ${path}`)
+    }
+    logInfo(`Found: ${path}`)
+  }
+
+  logStep('Verification passed')
+  logInfo('Manual check still needed: bun link and global canon invocation')
+}
+
+rmSync(tmpRoot, { recursive: true, force: true })
+mkdirSync(packDir, { recursive: true })
+mkdirSync(extractDir, { recursive: true })
+
+intro('Install verification')
+let failed = false
+try {
+  check()
+} catch (error) {
+  failed = true
+  logError(error instanceof Error ? error.message : String(error))
+} finally {
+  if (keep) {
+    logInfo(`Kept artifacts at ${tmpRoot}`)
+  } else {
+    rmSync(tmpRoot, { recursive: true, force: true })
+  }
+  outro()
+}
+process.exit(failed ? 1 : 0)

package/src/cli/retired.ts

@@ -0,0 +1,63 @@
+export interface RetiredVerb {
+  /** The words a caller types after `canon`, one for a group and two for a subcommand. */
+  readonly path: readonly string[]
+  /** The release that dropped the verb, from the changelog. */
+  readonly release: string
+  readonly movedTo: string
+}
+
+const DESIGN_MOVED =
+  'the design values now live in the stylesheet your canon/DESIGN.md lead names'
+
+/**
+ * Every verb a release dropped, with the release and where the work went. The
+ * router reads this ahead of the parser, and `canon migrate status` reads it to
+ * find project calls. A verb that returns leaves this table in the same change.
+ */
+export const RETIRED_VERBS: readonly RetiredVerb[] = [
+  {
+    path: ['canvas'],
+    release: '5.54.0',
+    movedTo: 'Frameboard, which carries the design board in its own repository',
+  },
+  { path: ['design', 'render'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'install'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'sync'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'fonts'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'list'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'add'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  {
+    path: ['teach'],
+    release: '5.53.0',
+    movedTo: 'the canon:teach-craft skill',
+  },
+  {
+    path: ['slides'],
+    release: '5.53.0',
+    movedTo: 'the canon:teach-craft skill',
+  },
+  {
+    path: ['demo'],
+    release: '5.53.0',
+    movedTo: 'a tool built for composed video',
+  },
+]
+
+/**
+ * Matches the leading words of argv, stopping at the first option so a flag's
+ * value is never read as a verb name.
+ */
+export function findRetired(args: readonly string[]): RetiredVerb | undefined {
+  const words: string[] = []
+  for (const arg of args) {
+    if (arg.startsWith('-')) break
+    words.push(arg)
+  }
+  return RETIRED_VERBS.find((verb) =>
+    verb.path.every((word, index) => words[index] === word),
+  )
+}
+
+export function retiredMessage(verb: RetiredVerb): string {
+  return `error: 'canon ${verb.path.join(' ')}' was retired in v${verb.release}. The work moved to ${verb.movedTo}.`
+}