@erclx/canon 5.57.0 → 5.59.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* **governance:** widen design-taste paths to component files ([#2645](https://github.com/erclx/canon/issues/2645)) ([01b1445](https://github.com/erclx/canon/commit/01b144514eced1150c90b18acc78f0be33990a23))
+* **rules:** route interface changes to api-design ([#2647](https://github.com/erclx/canon/issues/2647)) ([09a073c](https://github.com/erclx/canon/commit/09a073ca38324a399de5c2c2e702fbcede6bb38c))
+* **skills:** offer a restructure before document-repair rewrites ([#2648](https://github.com/erclx/canon/issues/2648)) ([7c2776a](https://github.com/erclx/canon/commit/7c2776a95b86a6626c44e399056b9eaa22418d65))
+
+
+### Bug Fixes
+
+* **context:** count table rows toward no folder paragraph ([#2646](https://github.com/erclx/canon/issues/2646)) ([a99b020](https://github.com/erclx/canon/commit/a99b02064105b81bc3a4f6e4820c73198942785e))
+
 ## [5.57.0](https://github.com/erclx/canon/compare/v5.56.0...v5.57.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.57.0",
+  "version": "5.59.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/context-fold/references/context.md

@@ -71,7 +71,7 @@ An entry carries three H2 sections and no other, being `Overview`, `Layout`, and
 
 Layout gives each folder doing real work its own H3, titled with the folder path in a code span, such as ``### `src/design/` ``.
 
-- Open the H3 with a one-paragraph lead stating what the folder does, then at most five bullets on what it does now
+- Open the H3 with a one-paragraph lead stating what the folder does, then at most five bullets on what it does now. A table after the lead counts toward neither, with one sentence to lead the bullets
 - Put every trivial folder under `### Other folders` as a one-line bullet in owns-X form
 - Name folders only, never files, and write no decisions and no history under any H3
 - Give each folder under the code roots one H3 or `Other folders` line, since a second entry may cite it but never claims it

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

@@ -13,8 +13,8 @@ Length, placement, and staleness answer to different evidence, and one list hand
 
 ## Must
 
-- Report per document across the length, placement, and staleness axes, marking each finding with its evidence class
-- Read length and placement through the verb owning each measurement, and take every checkpoint from the record the verb returns
+- Report per document across the length, placement, and staleness axes, marking each finding with its evidence class, read through the verb owning each measurement and its record's checkpoints
+- 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

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

@@ -47,6 +47,12 @@ The first names the backend, the model, and the source that decided both. Report
 
 Take the checkpoints from the record each verb returns rather than from a number written here. A checkpoint the CLI moves reaches this report with no edit, and a number held in this body goes stale on its own cadence.
 
+### The structure line
+
+The context audit record already carries what a restructure needs, so the placement axis gains a structure line per area folder and runs no further verb. `${CLAUDE_SKILL_DIR}/references/axes.md` holds how to read `length` and `coverage` into a proposed split or owner.
+
+Emit the line only for a folder with an entry past the line checkpoint whose Layout headings group into two or more domains, or with a doubled or unnamed coverage finding. A folder with neither gets no line, and `document-repair` goes straight to its rewrite.
+
 ### An unread axis is not a healthy one
 
 A refusal, an absent key, and a subcommand the project's binary does not carry each leave an axis unread. Report it as unread against the documents it would have covered, name the read that could not be taken, and name the cause.
@@ -106,4 +112,12 @@ When Step 3 read the canonical records, add one reminder line per doc the verb r
 
 Write `reviewed value is not a date: <value>` for a doc carrying `invalidReviewed`, and `no release tags to count` in place of the count when `tagged` is false. Name the unread cause instead when the verb refused or the binary carries no `canonical` kind.
 
+Under the table, add one structure line per area folder that earned one, naming the entry and the split, or the finding and its owner:
+
+```markdown
+Structure `canon/context/surfaces/`: `cli.md` (300 lines) splits into `cli.md` taking <headings> and `cli-<domain>.md` taking <headings>, because <reason>.
+```
+
+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.

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

@@ -54,6 +54,18 @@ The sweep classifies each section as keep, replace or rewrite, history, or move.
 - A low-confidence `move` is a prompt to look rather than an instruction to cut
 - **Routes to:** the document the verdict names as the owner. Where the move crosses a tier rather than a file, the project's own content-ownership rules decide the destination.
 
+### The structure line
+
+The audit record's `length` array lists each entry past the line checkpoint, and `coverage.findings` lists the `doubled` and `unnamed` ones. The structure line reads both, so it carries the `measured` class for the finding and `read` for the proposal built on it.
+
+- **Overgrown entry:** read its `causes` in `length` first, since `history: yes` points at cutting provenance and one domain at a trim, so neither earns a split
+- **Split:** group the Layout headings by domain, one new entry per group beyond the first, naming each entry's headings and one reason
+- **Domain boundaries:** no verb measures one, so state the grouping as a judgment.
+- **Doubled coverage:** two entries describe one source area. Propose the one that owns it, from which entry already holds the area's traps, and the other points at it.
+- **Unnamed coverage:** no entry names the area. Propose an owner among the existing entries before a new one, since a new entry is the larger change.
+
+A proposal names headings and a reason, so an operator judges a concrete split. A split nobody can act on names none of those.
+
 ### When a verb resolves nothing
 
 Both verbs resolve their folders by surface root rather than by a path written into them, so a project laid out differently resolves nothing. The two degrade differently.

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

@@ -15,14 +15,19 @@ A folder repaired by hand also drifts back, since a target gates nothing until a
 
 - Each batch takes one folder and leaves it at zero findings or reports it ungated
 - A folder gates only through `canon markdown gated add`, which refuses one with a finding left
-- A rewrite keeps every stated reason, command, and path the original carried
+- A rewrite keeps every stated reason, command, and path the original carried, and leaves a context entry no more shape findings than it started with
 - The body names the verbs and states no limit number
 - A requirement gates by its own path, never through a folder prefix
 
+## Restructure first
+
+An overgrown context folder is offered the restructure `document-health` proposes before any rewrite, and the restructure applies only on the operator's word.
+
 ## Must not
 
 - Edit `canon/config/markdown.toml` by hand
 - Report a folder gated that the verb refused
+- Reach zero density findings by growing the context shape findings
 - Change what a document claims to pass the audit
 - Be reachable only by its name, since `document-health` names it for every length finding
 

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

@@ -18,6 +18,15 @@ The CLI holds every number. `canon markdown audit` measures, and `canon markdown
 - `gated add` refusing with `canon-checkout`: stop. Canon's own checkout gates through a constant in its source, which a code change edits.
 - Branch on each record's own fields rather than on an exit status a shell wrapper can flatten. A call with no terminal on stdin already runs headless, so no command takes a prefix.
 
+## Step 0: offer the restructure
+
+Restructure an overgrown context folder before rewriting it, so the effort is spent once. Run this step only when `canon/context/` is a candidate, meaning it is not yet listed in `canon/config/markdown.toml`, and skip it silently otherwise.
+
+- Take the structure line `document-health` reports for each area folder, or read it from `canon context audit --json` the way that skill does
+- A folder with no overgrown entry and no doubled or unnamed coverage finding has no line, so go straight to Step 1 with no prompt
+- Show the operator each proposal and ask before applying it, since a split moves files other entries cite. Re-run the audit afterward to confirm the citations still resolve.
+- Take a declined proposal as a decision and rewrite the entry as it stands
+
 ## Step 1: read the audit
 
 Run the audit over the whole tree and take the density and reference shape findings from its record:
@@ -26,6 +35,12 @@ Run the audit over the whole tree and take the density and reference shape findi
 canon markdown audit --json
 ```
 
+When `canon/context/` is a candidate, read the context shape beside it and keep each entry's `shapeFindings` issues as the baseline Step 3 holds the rewrite to:
+
+```bash
+canon context audit --json
+```
+
 Take the candidate folders from the order table in `${CLAUDE_SKILL_DIR}/references/batches.md` rather than from the findings, since a clean folder carries no finding and would never be gated. Drop every folder `canon/config/markdown.toml` already lists, since a listed folder already gates.
 
 Sort what is left in two. A candidate the findings never name needs no rewrite, so gate it through Step 4 before the first batch. Group the findings under the rest, which Steps 2 and 3 rewrite.
@@ -46,6 +61,12 @@ canon markdown audit <prefix> --json
 
 Read `${CLAUDE_SKILL_DIR}/references/batches.md` for what a rewrite may cut. A stated reason survives every rewrite, and the audit reaching zero cannot see one that went missing.
 
+### Hold the context shape
+
+For a file under a folder the context audit resolves, also re-run `canon context audit --json` and compare the entry's `shapeFindings` issues with the baseline. A density fix that splits a Layout paragraph into several can grow `layout-paragraphs`.
+
+A rewrite leaving the entry with more shape issues than it started with is not done. Undo it, or fold the split into a table or a linked page, and report the entry as stopped when neither reaches the baseline. Zero density findings reached by growing shape findings only moves the failure.
+
 ## Step 4: gate the folder
 
 ```bash

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

@@ -84,7 +84,7 @@ What this skill adds on top of the standard:
 Every `- Suggested:` line takes senior judgment, picking the best option in one line with its reason or main tradeoff, and naming alternatives only when they change the pick.
 
 - Suggest a real default when best practice, the codebase, or prior context points to one
-- Load `canon:codebase-layout` before `## Files to touch` when an entry names a path that does not exist yet, and give each new path its placement reason. Report it if it does not resolve.
+- Before `## Files to touch`, load `canon:codebase-layout` for a new path (its reason) and `canon:api-design` for a changed verb, flag, output, record shape, or endpoint. Report either if missing.
 - Fill `## Design references` with the `canon/design/<surface>/` folder for each surface a UI file in `## Files to touch` renders, and write `None identified.` in a project with no folder
 - Write `## Verification` as one bullet per outcome naming the test or command that proves it
 - Write `## Review focus` as the inputs or states that would break the change, carrying the risk you understood to the executor and the reviewer

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/context-audit.md

@@ -46,7 +46,7 @@ The shape kinds are `retired-section`, `gotcha-count`, `gotcha-heading`, `gotcha
 
 - A `## Decisions` H2, or a `Gotchas` section past five bullets or holding a heading or paragraph
 - A `Layout` H3 titled neither a code-spanned path nor `Other folders`, or a heading below H3 under `Layout`
-- A folder H3 past five bullets or its one-paragraph lead
+- A folder H3 past five bullets or its one-paragraph lead, where table rows and the sentence leading the bullets after a table count toward neither
 
 The development entry may carry a `Scripts` H3 exempt from both folder caps. `SHAPE_GATED_FOLDERS` lives in `src/context/shape-gated.ts`.
 

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/governance/rules/code/routing.md

@@ -1,5 +1,5 @@
 ---
-description: Routes code placement and shape decisions to the skills that carry them, and library calls to the official docs
+description: Routes code placement, shape, and interface decisions to the skills that carry them, and library calls to the official docs
 ---
 
 # Code standards
@@ -12,6 +12,10 @@ description: Routes code placement and shape decisions to the skills that carry
 
 - Load the `canon:code-craft` skill before deciding the shape of a new function, class, or module, and report it rather than proceeding silently when it does not resolve.
 
+## Interfaces
+
+- Load `canon:api-design` before shaping a public function, flag or output, record format, endpoint, or caller-handled error, and report it rather than proceeding silently when it does not resolve.
+
 ## Libraries
 
 - Before calling a library API the codebase does not already use, fetch the official docs for the installed version and match the call to them, since recall of an API goes stale.

package/governance/rules/ui/design-taste.md

@@ -1,6 +1,10 @@
 ---
 description: Route edits that decide how a surface looks to the design-taste skill for the layer ordering, the coherence locks, and the defaults a model reaches for
 paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
   - '**/*.css'
   - '**/*.scss'
   - 'canon/DESIGN.md'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.57.0",
+  "version": "5.59.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)