@erclx/canon 5.38.0 → 5.39.0

package/docs/agents/migrate.md

@@ -1,34 +1,59 @@
 ---
 title: Migrate
-description: What each canon migrate verb moves and rewrites, what it refuses, the markers that keep an old spelling, and the idempotence check a second run gives
+description: What each canon migrate verb moves, the markers that keep an old spelling, and what each one refuses
+kind: reference
 ---
 
 # Migrate
 
-`canon migrate <verb>` moves a project off a retired name or layout. Each verb reports its plan and writes nothing until `--write` is passed, and each takes `--json`. Every verb but `rename` takes `--root`.
+`canon migrate <verb>` moves a project off a retired name or layout. Each verb reports its plan and writes nothing until `--write`, takes `--json`, and, except `rename`, takes `--root`. A second run rewrites nothing, which confirms the exclusions and markers fired.
 
-`migrate rename` moves a project off the retired `aitk` name. It reports until `--write` is passed, and `--scope target` rewrites the toolkit-owned folders alone, reporting every other citation as one the project owns rather than editing prose somebody wrote. A project installing `canon` fresh never needs it.
+| Verb               | Moves                                                                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rename`           | The retired `aitk` name. `--scope target` rewrites toolkit-owned folders only.                                                              |
+| `skill-names`      | Plugin skills off their `claude-` prefix and other retired names, with every citation                                                       |
+| `records`          | Session records from `.claude/` to `.canon/`, with every tracked citation                                                                   |
+| `surface-roots`    | `context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the stamp folder from `.claude/` to `canon/`, by `git mv` |
+| `record-tree`      | Citations inside `.canon/` folders a session still follows: `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, `teach`          |
+| `rule-layout`      | A flat installed-rule layout onto the `canon/`-wrapped one                                                                                  |
+| `scratch-evidence` | A folder a durable record cites out of `.tmp/`, with its citations                                                                          |
+| `record-layout`    | Review receipts, memory archives, feedback, renders, picks, and evidence into their current folders                                         |
 
-`migrate skill-names` moves the plugin skills that carried a `claude-` prefix onto their two-word names and rewrites every citation of one. It carries two plain renames as well, where a skill carried no prefix and changed its name because the old one described a job it no longer does, landing on `ui-checklist` and `context-fold`, and one merge, where the five per-kind document drafters land on `draft-doc`. It carries one namespaced-only rename, `canvas` to `canvas-board`, keyed on `canon:canvas` and `skills/canvas` because a bare `canvas` key would rewrite the verb, its source folder, and its record folder. It leaves the pointer answering under the fold skill's old name in place. It shares its engine with `migrate rename` and differs in what it is scanning for: a skill name is a whole name rather than a word stem, so it matches only where the word ends, which is what keeps a longer word that merely opens with a skill name, such as `claude-worktrees`, out of it. It takes no `--scope`, since the skill folders it moves are authored in the toolkit and no target holds a copy of that catalog, which leaves a target's own citations of a renamed skill as the whole of what it rewrites there. The changelog and the eval transcripts are passed over on the argument the other sweep already carries, that each records what shipped or what a session ran under whatever name was current then. <!-- canon-keep-retired -->
+- `skill-names` takes no `--scope` and skips the changelog and eval transcripts
+- `surface-roots` leaves `rules/`, `skills/`, `hooks/`, and `settings.json` where Claude Code reads them
+- `rule-layout` classifies each flat file against the stamp as clean, edited, or unclaimed. Clean and edited files move untouched, and an unclaimed name stays.
+- `record-layout` labels each evidence folder `(pick)` or `(evidence)` in the dry run
 
-`migrate records` moves a project's session records from `.claude/` to `.canon/` and rewrites every tracked file that cites one. It reports until `--write` is passed, and refuses outright when the project does not already ignore `.canon/`, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Take the ignore entry with `canon tooling sync --write` first.
+## Output
 
-A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the nearest non-blank line below it, keeps the old spelling for prose that dates a decision. The records themselves are never swept: everything under `.canon/` and every `.claude/` record folder is passed over and reported as a count on its own line, which is what keeps the run that follows the ignore collapse touching the same files as one before it. Running it twice rewrites nothing, which is the check that the exclusions, the markers, and that skip all fired.
+- The plan lists every citation in scope by file, line number, and line text
+- `record-tree` reports closed groundwork and intake trails, the scratch folder, and backup history as counts and rewrites none
+- `records` reports skipped record folders as a count on its own line
+- A `record-tree` rewrite has no undo in version control, so read the report before `--write`
 
-`migrate surface-roots` moves the tracked surfaces from `.claude/` to `canon/`: `context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the install stamp folder, respelled `canon/config/` since a project under `canon/` reserves the bare `canon` name for the CLI's own install. Every path is tracked, so each file moves with `git mv` and its history follows it, and every tracked citation of one is rewritten in the same run. `rules/`, `skills/`, `hooks/`, and `settings.json` stay where Claude Code reads them. It reports until `--write` is passed, and a destination already present under `canon/` refuses the whole plan rather than splitting a surface across both roots.
+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`.
 
-A line carrying `canon-keep-surface-root`, or the nearest non-blank line above it, keeps the old spelling. A rule's frontmatter `paths:` glob, a citation shaped like a path into another repository, and one inside a dated paragraph are reported by file and line and left alone. Running it twice rewrites nothing, which is the idempotence check. A project that never runs it keeps resolving each surface under `.claude/`, since every reader takes whichever root holds the entry.
+| Marker                    | Keeps                                          |
+| ------------------------- | ---------------------------------------------- |
+| `canon-keep-record-root`  | The old record folder spelling                 |
+| `canon-keep-surface-root` | The old `.claude/` surface root                |
+| `canon-keep-retired`      | A retired name, for `rename` and `skill-names` |
 
-`migrate record-tree` is what reaches the records the sweep above passes over, and the two share no scope. That one enumerates through git, so it sees every tracked file and none of the records, which are gitignored by construction. This one walks `.canon/` itself and is scoped to the folders a session still follows a path into: `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`, each minus its own `archive/` subtree. A closed groundwork or intake trail, the scratch folder, and the backup history are reported as counts and never rewritten, because a path inside a closed trail sits in a sentence about work that already ended. Run it after the move, since there is no new root to walk before one.
+`surface-roots` also reports and leaves a rule's frontmatter `paths:` glob, a path into another repository, and a citation in a dated paragraph.
 
-Every citation in scope is reported with its file, its line number, and the line text. The record tree is untracked, so a wrong rewrite has no git undo, and that report is what a reader judges before passing `--write`. Marking a line that has to keep the old spelling uses the same `canon-keep-record-root` comment, and a second run rewriting nothing is the idempotence check.
+## Refusals
 
-`migrate rule-layout` moves a target still on the flat installed-rule layout onto the `canon/`-wrapped one. It classifies each flat file against the target's own recorded stamp: an unchanged hash is clean, a changed one is edited, and a name neither the stamp nor the current rule catalog can vouch for is unclaimed and left in place. Clean and edited files both relocate with their content untouched, since moving a rule is a different decision from re-syncing it. The one renumbered rule reads its destination from a table rather than from its own current name, so it never lands as a second copy under the retired number.
+| Verb               | Refuses when                                                                        |
+| ------------------ | ----------------------------------------------------------------------------------- |
+| `records`          | The project does not ignore `.canon/`. Run `canon tooling sync --write` first.      |
+| `records`          | A record folder already exists at the destination                                   |
+| `surface-roots`    | Any destination already exists under `canon/`, refusing the whole plan              |
+| `scratch-evidence` | A destination is occupied                                                           |
+| `record-layout`    | A destination already exists, each move refused on its own                          |
+| `rule-layout`      | A destination holds different bytes. Neither file is touched and other moves apply. |
 
-`migrate scratch-evidence` moves a folder out of `.tmp/` for good rather than repointing a citation in place. A promoted folder is one a durable record, live or archived, cites as its evidence, and no source file under `claude/`, `scripts/`, `src/`, or `governance/` names by path, which is what a script still writing into it fails. It walks every `canon records push` folder rather than the live ones alone, since most of what it repoints sits in `tasks/archive/`, `plans/archive/`, and `groundwork/`. A destination already occupied is a refusal, and a second run rewriting nothing is the same idempotence check `migrate record-tree` uses.
+A `rule-layout` destination holding the same bytes marks a duplicate, which `--write` deletes.
 
-A destination that already holds the same bytes marks the flat file a duplicate, which `--write` deletes rather than moves. One holding different bytes is a real collision: neither file is touched, it is reported by name, and every other planned move still applies independently. Run this before `canon gov install` or `canon gov sync` against a target still on the flat layout, since neither bootstrap verb detects or clears it on its own.
+## See also
 
-`migrate record-layout` folds two record folders under the memory pen: review receipts move from `.canon/review/memory/` to `.canon/memory/review/`, and retired entries move from `.canon/tmp/memory-archive/` to `.canon/memory/archive/`, backed for the first time since `memory/` is a folder `canon records push` carries and `tmp/` is not. Each move is refused independently when its destination already exists, and the citation repoint sweeps every folder `canon records push` carries, archives included, since an archived receipt still cites the row it retired. The same `canon-keep-record-root` marker and second-run idempotence check apply. A receipt sitting at the flat `review/` root, from before `.canon/review/memory/` existed, matches neither mapped move and is reported by name rather than moved.
-
-The same verb leaves `.canon/review/` holding only reviews. Feedback moves to `.canon/feedback/`, and the design, board, slides, and diagram renders move to `.canon/tmp/render/<kind>/`, off the records remote since the commands regenerate them. Reference images move to `.canon/picks/references/`. A branch report flattens from `review/branch/review-<slug>.md` to `review/branch-<slug>.md`, and a flat `review/ui-checklist-<slug>.md` moves into `.canon/tmp/handoff/ui-checklist/`. Each folder under `review/evidence/` is decided from what it holds: one directly carrying an `arm-<id>` capture or a `design-handoff.md` is a pick and moves to `.canon/picks/<slug>/`, and any other is evidence and moves to `.canon/evidence/<nn>-<slug>/`. Evidence folders are numbered by the oldest file each holds, continuing past any ordinal `evidence/` already carries. The dry run labels each derived destination `(pick)` or `(evidence)`, so a misfiled folder shows before `--write`, and one filed wrong moves back by hand. A bare mention of an emptied folder, such as `review/evidence/` with no slug or `review/branch/` with no report name, matches no row and stays as written.
+- `install-and-sync.md`: the drift report that names these verbs as remedies

package/docs/agents/output-shape.md

@@ -1,15 +1,13 @@
 ---
 title: Output shape
-description: Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
+description: The framed output shape every command renders into, the JSON and color modes, the exit discipline, the runtime catalogs, and a headless invocation per domain
 ---
 
 # Output shape
 
-Every CLI command renders into one of two framed shapes. Data goes to stdout. UI and logs go to stderr.
+Data goes to stdout. UI and logs go to stderr. Help is the exception and prints to stdout so it can be piped.
 
-Help output is the exception. It prints to stdout so it can be piped and grepped.
-
-## Data shape (lists, runs, errors)
+## Frame
 
 ```plaintext
 ┌
@@ -17,54 +15,71 @@ Help output is the exception. It prints to stdout so it can be piped and grepped
 │
 ├ Section
 │ ✓ item
-│ ✓ item
 └
 ```
 
-Rules:
-
-- `┌` opens the frame on stderr
-- `│ canon <domain>` is the command banner, one per invocation
-- `├ Section` headers introduce groups of items. `log_step` produces the blank `│` spacer before each.
-- `└` closes the frame on stderr, wired via `trap close_timeline EXIT`
-- Errors render as `│ ✗ message` inside the same frame. Never emit a lone error line without a frame.
+- `┌` opens the frame, `│ canon <domain>` is the banner, and `├ Section` groups items
+- `└` closes the frame on stderr
+- An error renders as `│ ✗ message` inside the frame, never as a lone line
+- Help skips the banner and puts `Usage:` directly on `├`
 
-## Help shape
-
-```plaintext
-┌
-├ Usage: canon <domain> [command]
-│
-│  Commands:
-│    ...
-└
-```
+A help request naming an unknown subcommand, under a group taking no operand, writes its refusal to stderr and exits 1.
 
-Help skips the banner. The `Usage:` line sits directly on `├`. Help writes to stdout because `--help` is documentation, not runtime UI. `--help --all` on a command prints each block unframed, one after another, and a help request naming an unknown subcommand, under a group that takes no operand of its own, writes its refusal to stderr and exits 1.
+## JSON and names modes
 
-## JSON and `--names` modes
+`--json` and `--names` keep stdout pure data. The frame still renders on stderr, and diagnostics reach stderr in every mode. A JSON refusal carries an action and a reason, so branch on the record rather than on stderr.
 
-`--json` and `--names` keep stdout clean and machine-readable. The frame still renders on stderr (open, banner, close) so the stream discipline is consistent across modes. Consumers that only read stdout see pure data.
+A shell profile may wrap `canon` in a function that takes its status from a later command. Where a verb documents a record field, read the field rather than the exit.
 
 ## Color
 
-Escape sequences reach a destination that renders them and nowhere else. The question is asked per stream rather than once for the process, so a run piping its data while keeping a terminal on stderr still gets color on the frame.
-
-Either condition alone turns color off:
-
-- `NO_COLOR` is set to any non-empty value, whatever that value says
-- The destination is not a terminal, which covers a pipe, a file, and a captured session
-
-The frame survives both. `┌`, `│`, `├`, `└`, and the `✓ ! + - ✗` marks are structure rather than color, and they are what lets a captured run still read as one block. A caller wanting neither the frame nor the color reads `--json` instead.
-
-Terminal control is a separate question this section does not cover. The cursor and key sequences an interactive prompt writes run only where a terminal already exists.
-
-## Process exit
-
-A command action sets `process.exitCode` and returns. Calling `process.exit()` there ends the process before a stdout write drains, which truncates piped output at the 64K pipe buffer while still reporting the right exit code. Redirecting to a file hides the truncation, so it surfaces only through a pipe, which is what a check has to use to catch it.
-
-The rule reaches an error path that writes to stderr alone, where the truncation has nothing to cut. Scoping it to the stdout writers was the alternative and it makes the floor depend on a detail that moves, since an action grows a stdout write long after its error branches are written. An action always has a return path, so the requirement costs it a line.
-
-The exit belongs to a helper that has no caller to unwind through. A prompt inside a promise executor and a wrapper propagating a child process status both qualify, and neither can hand a value back to a caller expecting one. A validation helper called from an action does not: it throws from a `never` return, which keeps its caller exhaustive to the compiler while the action catches and owns the code.
+Escape sequences reach a destination that renders them and nowhere else, decided per stream. `NO_COLOR` set to any non-empty value turns color off, and so does a destination that is not a terminal. The frame glyphs and the `✓ ! + - ✗` marks survive both.
+
+## Exit discipline
+
+A command action sets `process.exitCode` and returns. Calling `process.exit()` in an action truncates piped output at the 64K buffer. A file redirect hides the truncation, so test through a pipe.
+
+## Runtime catalogs
+
+Discover names at runtime rather than hardcoding them.
+
+| Command                           | Returns                                                          |
+| --------------------------------- | ---------------------------------------------------------------- |
+| `canon tooling list --json`       | Stacks, extends chain, dep and script counts                     |
+| `canon gov list --json`           | Governance stacks, rule sets, evidence, and unreferenced rules   |
+| `canon gov detect --json`         | Opt-in rules a target's dependencies and paths propose           |
+| `canon claude seeds list --json`  | Seed doc sources with content                                    |
+| `canon claude skills list --json` | Plugin skills, descriptions, requirement flag, family vocabulary |
+| `canon docs list --json`          | Consumer docs plus per-domain context                            |
+| `canon audits list --json`        | Audits the set runs, the corpus each reads, and whether it gates |
+
+- `gov list` expands each stack to its rules and carries `unreferenced`, the rules no stack reaches, which install only through `--add`
+- `claude skills list` reports shipped skills only. Each carries `family` (or `null`) and `requirement`, and a `false` requirement is a gap to close. `--names` and `--by-family` change the render.
+- A skill with unparseable frontmatter returns an empty description rather than failing the listing
+
+## Headless invocation
+
+Set `CANON_NON_INTERACTIVE=1` to refuse every prompt.
+
+```bash
+CANON_NON_INTERACTIVE=1 canon init --stack node --skip wiki /path/to/project
+CANON_NON_INTERACTIVE=1 canon sync /path/to/project
+CANON_NON_INTERACTIVE=1 canon gov install node --add astro,shadcn /path/to/project
+CANON_NON_INTERACTIVE=1 canon gov sync /path/to/project
+CANON_NON_INTERACTIVE=1 canon gov build /path/to/project
+CANON_NON_INTERACTIVE=1 canon tooling diff astro /path/to/project
+CANON_NON_INTERACTIVE=1 canon tooling sync astro /path/to/project --write
+CANON_NON_INTERACTIVE=1 canon wiki init /path/to/project
+canon tooling inject base /path/to/project --configs --seeds
+canon tooling prune-gitignore base /path/to/project
+canon tooling verify vite-react
+canon audits run --json
+canon secrets scan --json
+canon deps audit --json
+```
 
-Diagnostics reach stderr in every mode, including `--json`. Name the file and the field that failed, because a JSON record carries an action and a reason and an operator reading stderr alone sees neither.
+- `canon tooling sync` needs `--check` or `--write` headlessly. With neither it reports and exits 1.
+- `--skip base` syncs a monorepo subtree without the layer the root owns
+- `canon audits run` exits 2 on a fact and 3 for an audit that did not report
+- `secrets scan` and `deps audit` exit 2 on findings. Only a credential fails `audits run`, and an advisory reports without moving the verdict.
+- Both refuse with a `reason` when they have no corpus, `no-manifest` for the scan and `no-lockfile` for the audit

package/docs/agents/overview.md

@@ -1,26 +1,50 @@
 ---
 title: Overview
-description: What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
+description: What this folder covers, the invocation rules every command inherits, and how canon docs resolves a topic name
 ---
 
 # Overview
 
-CLI catalog and invocation rules for an agent driving the `canon` CLI, in this repository or in any project that installed it.
+Reference for an agent driving the `canon` CLI, in this repository or in any project that installed it. It covers invocation and output contracts, not domain behavior. Read the project's own `CLAUDE.md` for that.
 
-This folder is an index of what an agent can run and how to run it cleanly from a script. It does not cover domain behavior. Read the project's own `CLAUDE.md` for that. The `.claude/skills/internal-*` skills carry the per-domain editing guidance and live in the toolkit checkout alone, so a reader who installed the package resolves none of them.
+`canon --help` is the command catalog. `canon <command> --help` lists subcommands, and `canon <command> <subcommand> --help` prints a leaf's flags, exit codes, and examples. `--help --all` prints both. A pipe gets the same text without the frame glyphs.
 
 ## Invocation rules
 
-`output-shape.md` holds the stream and exit contract. It applies to every command in this folder.
+`output-shape.md` holds the stream and exit contract every command follows. Every command has a non-interactive path, and data on stdout pipes clean.
 
-## Where to start
+## Reading a page by name
 
-- `output-shape.md`: the stream contract every command renders into and the exit discipline behind it, which is what a caller parsing stdout depends on
-- `commands.md`: the full command catalog, project-level and per-domain
-- `scripting.md`: the runtime catalogs that replace hardcoded names, plus headless invocation examples
+`canon docs list [--json]` lists the consumer docs, plus the per-domain context entries when the install carries `canon/context/`. A registry install carries `docs/` alone. A clone or a linked worktree carries both.
 
-## Related
+`canon docs <topic>` prints one doc to stdout, and an unknown topic names the available ones on stderr and exits 1. Three spellings are tried in order, each across both roots before the next, with `docs/` ahead of `canon/context/`.
 
-- `CLAUDE.md`: project behaviors
-- `.claude/skills/internal-*`: domain-scoped guidance for editing work, in the toolkit checkout only
-- `docs/index.md`: full docs directory
+- A sibling file, such as `docs/agents/indexes.md` for `indexes`
+- A folder of that name, which prints its generated `index.md`
+- A sub-area file one level down, such as `operating-model` reaching `docs/workflow/operating-model.md`
+
+A bare name carried by two folders of one root resolves to neither and exits 1. Toolkit-internal topics resolve by name and stay off the list.
+
+## Commands with no page
+
+`canon serve [dir]` binds loopback and prints the link that opens the directory.
+
+- Read `url` off `--json`, since a busy port walks forward to the next free one
+- `--entry` escaping the root refuses as `no-entry` before a port is taken
+- Any other bind failure refuses as `bind-failed` carrying the error code
+- `entryExists` reads true with no `--entry` and no root `index.html`
+
+`canon inventory [subject]` reads `inventory.toml` at the project root and never gates. A missing server and an unmatched query refuse rather than list nothing.
+
+```toml
+base-url = "http://localhost:4173"
+routes = ["/", "/pricing"]
+
+[subjects.focus]
+query = "button, a[href], input"
+```
+
+## See also
+
+- `output-shape.md`: the frame, `--json`, color, and exit discipline
+- `docs/index.md`: the full docs directory

package/docs/agents/routing.md

@@ -5,7 +5,7 @@ description: Reading per CLAUDE.md section how many bullets name a path, what co
 
 # Routing report
 
-`canon claude routing` reports, per `CLAUDE.md` section, how many top-level bullets name a path and how many of those a path-scoped rule already covers. It answers the firing axis of the tier test in `canon/context/context-model/overview.md`, whether a fact applies every session or fires on one path, and which until this verb existed was a judgment nothing counted. The tier test names two further axes, conditional presence and updatability, that this verb does not check.
+`canon claude routing` reports, per `CLAUDE.md` section, how many top-level bullets name a path and how many of those a path-scoped rule already covers. It answers the firing axis of the tier test in `canon/context/context-model.md`, whether a fact applies every session or fires on one path, and which until this verb existed was a judgment nothing counted. The tier test names two further axes, conditional presence and updatability, that this verb does not check.
 
 ```bash
 canon claude routing

package/docs/agents/rule-citations.md

@@ -34,7 +34,7 @@ A citation reaches a reader as a backticked path, reported under the form `path`
 
 A call to the retired standards verb is no form here. A rule holding one fails the shipped-references stage of `canon gate run`, which reads every shipped file for it.
 
-A `path` is anchored on the whole backticked span rather than on a trailing pattern inside it. Cutting `tooling-reference.md` out of `internal/standards/tooling-reference.md` and resolving that against the root alone reports a file that exists as missing, which is a mistake made by hand while measuring this corpus before the stage was written.
+A `path` is anchored on the whole backticked span rather than on a trailing pattern inside it. Cutting `tooling-reference.md` out of `.claude/skills/internal-tooling/references/tooling-reference.md` and resolving that against the root alone reports a file that exists as missing, which is a mistake made by hand while measuring this corpus before the stage was written.
 
 ## What is not a citation
 

package/docs/agents/skills-reach.md

@@ -52,7 +52,7 @@ A path a seed installs is disowned twice, under its own name and under the folde
 A correct citation and a defective one are the same string, and the sentence around it is the difference. A citation counts as decided when its line names the toolkit as the owner, matching the bodies that already spell it that way. The repair for a finding is to say whose copy the path is, never to delete the citation, since the paths name real documents a reader wants.
 
 ```markdown
-Read `canon/context/context-model/indexes.md` from the toolkit if context on the system is needed.
+Read `canon/context/context-model.md` from the toolkit if context on the system is needed.
 ```
 
 A line mentioning the toolkit for an unrelated reason exempts a citation on it. That is the accepted cost of a word over a notation every future body would have to learn.

package/docs/agents/targets.md

@@ -1,91 +1,39 @@
 ---
 title: Targets
-description: The projects this toolkit installed into, the record the install writes against the sweep that backs it, what bounds each answer, and the cross-target pull request read
+description: The projects this toolkit installed into, where each answer comes from, and the cross-target pull request read
+kind: reference
 ---
 
 # Targets
 
-## List
+`canon targets list` reports the projects this toolkit installed into. `canon targets pulls [paths…]` reports each target's open pull requests, or every target's when none is named. Both take `--json`. Read the record's fields, since a wrapping shell function can flatten the exit.
 
-`canon targets list` reports the projects this toolkit has installed into, with where each answer came from.
+- `list` takes `--sweep <path…>`, `--depth <n>` (default 4), and `--record`, which seeds the index from swept stamps and needs `--sweep`
+- Each stamping sync records its target in `$XDG_STATE_HOME/canon/targets.json`, and no row is removed
+- A sweep finds installs the index never held
 
-```bash
-canon targets list
-canon targets list --json
-canon targets list --sweep ~/repos --json
-canon targets list --sweep ~/repos --record
-```
+## Output
 
-| Option            | Behavior                                                                         |
-| ----------------- | -------------------------------------------------------------------------------- |
-| `--json`          | Add a machine-readable record on stdout                                          |
-| `--sweep <path…>` | Also walk these roots for targets the record never held                          |
-| `--depth <n>`     | How deep below each swept root to walk, defaulting to 4                          |
-| `--record`        | Seed the index from every swept checkout's own stamp, refusing without `--sweep` |
+- `bound` on a sweep names the roots walked, the depth, and what it skipped. Read it before trusting a count.
+- Clones sharing an `origin` share a row, and `pulls` reads one
+- `legacyPaths` is the `paths` on the retired stamp path
 
-Exit codes: `0` the population was read, `1` refused. A refusal carries a `reason` of `bad-depth` or, for `--record` given with no `--sweep`, `record-without-sweep`. An absent index reports as unknown rather than as no targets.
+| Field            | Holds                                                    |
+| ---------------- | -------------------------------------------------------- |
+| `checks`         | `passing`, `failing`, `pending`, or `null` when none ran |
+| `review`         | `open`, `closed`, or `null` when no pass has landed      |
+| `reviewReadable` | `false` when the review query failed                     |
 
-An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's fields rather than the exit when a skill consumes this.
+## Refusals
 
-## Where the answer comes from
+`list` exits 1 when refused. `pulls` exits 0 when one target was read and 1 when all refused. An absent index reads as unknown.
 
-Every sync that stamps a target records it in a machine-level index at `$XDG_STATE_HOME/canon/targets.json`, falling back to `~/.local/state/canon/targets.json`. A project installed into since that shipped is therefore known without anyone naming it, and each row carries `stampedAt` from the sync that last touched it.
+| Reason                 | Means                                   |
+| ---------------------- | --------------------------------------- |
+| `bad-depth`            | `--depth` is not a whole number         |
+| `record-without-sweep` | `--record` with no `--sweep`            |
+| `not-a-directory`      | A named path is no directory            |
+| `gh-unavailable`       | `gh` is not on the path                 |
+| `list-failed`          | The pull request list could not be read |
 
-`--sweep` walks the roots given and finds what the record never held, which is every target installed before the index existed. A row says which of the two found it, and a row the record knows keeps that source even when the sweep reaches it too.
-
-The record is the primary source and the sweep is the fallback, because they fail in opposite directions. A record only knows an install that ran after it shipped. A walk only knows the paths someone thought to name, which is how a hand census of this population was wrong in both directions at once: it counted two folders that had never been targets, counted one clone of a target already counted, and missed the clone a repair had actually run in.
-
-## What bounds a sweep
-
-A `--sweep` run carries a `bound` object naming the roots walked, the depth, the folders the walk stopped at on reaching the cap, the roots it could not read, and the directory symlinks it did not follow. Read it before treating a count as the population.
-
-The bound a sweep can never state is the machine. It reads this one, so a target on another machine or under a path nobody named is outside every answer it gives. That is the same limit the hand census had, and the record above is what closes it going forward rather than the sweep.
-
-`--depth` refuses anything that is not a whole number rather than falling back to the default. A value that is not one leaves every depth test false, so the walk runs to the bottom of its root while the bound claims a cap it never applied.
-
-## A project held in more than one clone
-
-A target cloned twice is one target. The sweep reads each checkout's `origin`, trims it to a form an ssh URL and an https URL of one repository agree on, and reports a single row holding every path.
-
-The row leads with the clone the record knows, because the record only names one a sync actually ran in. Every caller reading a single path takes the first, and picking that by sort order is the shape behind a repair that ran in one clone while a count was taken against another, leaving the target reported as untouched.
-
-Nothing removes a row. A project deleted, moved, or that dropped the toolkit stays in the index, so a count drifts upward over time. It surfaces on use rather than silently, since the read below refuses a path it cannot open.
-
-## The retired stamp path
-
-Each row names the subset of its checkouts still carrying the install stamp at the retired path: `legacyPaths` in the JSON, a subset of `paths` in the same order. The render says `legacy stamp` plain when every checkout carries it and `legacy stamp (1 of 2 checkouts)` when only some do, which is the common case rather than the rare one.
-
-`--record` backfills the index from a sweep rather than from a sync, for a target the record never held. It seeds one row per checkout from that checkout's own installed stamp, taking `stampedAt` from the stamp itself rather than from the moment the backfill ran, so a backfilled row never claims a sync that did not happen. A checkout whose stamp cannot be read is skipped rather than dated by the backfill. It refuses without `--sweep` naming what to walk.
-
-## Pulls
-
-`canon targets pulls` reports, per target, every open pull request with its checks and the heading its newest review pass carries.
-
-```bash
-canon targets pulls
-canon targets pulls ../caret ../stackr --json
-```
-
-Naming paths reads those and looks up nothing. Naming none reads every target `canon targets list` reports. One clone per project is read, since two checkouts sharing an origin answer the same query and reading both spends the rate limit to print one answer twice.
-
-Exit codes: `0` at least one target was read, `1` refused or every target refused.
-
-| Field            | Holds                                                                   |
-| ---------------- | ----------------------------------------------------------------------- |
-| `checks`         | `passing`, `failing`, `pending`, or `null` when GitHub reported none    |
-| `review`         | `open`, `closed`, or `null` when no pass has landed                     |
-| `reviewReadable` | `false` when the review query failed, leaving `review` covering nothing |
-
-`checks` is `null` rather than `passing` when no check ran at all, which is not the same answer. A failure outranks a run still going, since a job that already failed cannot be cleared by one still in flight.
-
-`review` reads the first line of the newest pass carrying `## Review` or `## Review closed`, which `review-pr` owns and posts. A target leaves a wave on `closed` rather than on a worker's reply.
-
-A target that could not be read carries a `reason` rather than an empty pull list. Reading a failed query as no open work is what reports a target as done having read nothing, which is the failure mode of the hand-written shell loop this replaces.
-
-| Reason            | Means                                                  |
-| ----------------- | ------------------------------------------------------ |
-| `not-a-directory` | the path is not a directory, so nothing was read there |
-| `gh-unavailable`  | `gh` is not on the path                                |
-| `list-failed`     | the open pull request list could not be read           |
-
-The reads run one target at a time. They share one GitHub API quota, and a wave firing a dozen at once meets the secondary rate limit rather than an answer.
+The last three fail only that target's row.

package/docs/target/migrations.md

@@ -144,4 +144,4 @@ A `## States` table under `canon/wireframes/` is no longer checked against evide
 
 The toolkit stopped seeding a `canon/ARCHITECTURE.md`, stopped gating its caps, and retired the `architecture` standard and the rule generated from it. A project scaffolded earlier may hold the file and import it from `CLAUDE.md`. Both stay, since the record is project prose now and nothing syncs or deletes it. `canon gov sync` removes the generated rule, and `canon context audit` no longer reports the record or its caps.
 
-Decide what to do with the file yourself, since where a decision belongs takes judgment no sync has. A decision about how one domain is built goes to the `canon/context/` entry of the domain it constrains, under that entry's `## Decisions`. Once the file is empty, delete it and its `@canon/ARCHITECTURE.md` line in `CLAUDE.md`.
+Decide what to do with the file yourself, since where a decision belongs takes judgment no sync has. A decision about how one domain is built is recorded by the pull request that made it, and a context entry carries no decisions. Move a trap a session would hit into that domain's `## Gotchas`. Once the file is empty, delete it and its `@canon/ARCHITECTURE.md` line in `CLAUDE.md`.

package/docs/target/projects.md

@@ -71,7 +71,7 @@ Keep the `## Scripts` table in `canon/context/development.md` current as scripts
 
 Scaffold installs tooling and seeds. It does not fill the planning docs or the design system. Complete those before the first feature session:
 
-1. Fill `canon/REQUIREMENTS.md`. The seed asks for the problem in one line, then goals and non-goals, and the scope is yours to write. The seed states its own cap of 600 words, and `canon context audit` gates on it. Edit the number in the record to loosen it. A decision about how the project is built goes in the `canon/context/` entry of the domain it constrains.
+1. Fill `canon/REQUIREMENTS.md`. The seed asks for the problem in one line, then goals and non-goals, and the scope is yours to write. The seed states its own cap of 600 words, and `canon context audit` gates on it. Edit the number in the record to loosen it. A decision about how the project is built lives in the pull request that made it, and a `canon/context/` entry carries the domain's folders and traps.
 2. For a UI project, write `canon/DESIGN.md` from the seed template and name the project's stylesheet in its lead, or work the direction out with `canon:canvas-board` and carry the pick in. Skip for non-UI projects.
 3. Optionally invoke `canon:draft-figure` naming an architecture view, such as system context or components, and the document it belongs in. It draws the view from the context index, the folder layout, and the requirements and renders it to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
 4. Start the feature loop. See [AI workflow](../workflow/ai-workflow.md) for the per-feature sequence.
@@ -134,5 +134,5 @@ When the toolkit updates, a target pulls changes per domain. A project scaffolde
 - [agents](../agents/index.md): CLI flags, exit codes, and JSON output shapes
 - [target migrations](migrations.md), [target sync](sync.md), [target scenarios](scenarios.md): the one-time moves, the recurring sync, and worked setups
 - [AI workflow](../workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
-- [tooling](../../canon/context/tooling/index.md), [governance](../../canon/context/governance/index.md), [claude plugin](../../canon/context/claude-plugin/index.md), [indexes](../../canon/context/context-model/indexes.md), [skill references](../../canon/context/claude-plugin/skill-references/index.md): per-domain mechanics
+- [tooling](../../canon/context/tooling/index.md), [governance](../../canon/context/governance/index.md), [claude plugin](../../canon/context/claude-plugin/index.md), [indexes](../../canon/context/context-model.md), [skill references](../../canon/context/claude-plugin/skill-references/index.md): per-domain mechanics
 - [sandbox](../../canon/context/sandbox/index.md): scenario catalog for verifying domain flows

package/docs/workflow/ai-workflow.md

@@ -31,7 +31,7 @@ canon/
 
 A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root. `canon migrate records` moves one project across and repoints what cites it, and `canon migrate record-tree` follows it to reach the citations inside the records themselves, which the first verb passes over because it enumerates through git. A project scaffolded before the surface move keeps its context and loose documents under `.claude/` the same way, and `canon migrate surface-roots` moves those to `canon/` with the history following each file.
 
-Three tiers of context load with different cost: always-loaded (root `CLAUDE.md` and `canon/REQUIREMENTS.md`), path-scoped lazy (`.claude/rules/<scope>.md` with `paths:` glob), and on-demand lookup (`canon/context/<domain>.md`, or `canon/context/<domain>/` once a domain outgrows one file, discovered via `canon/context/index.md`). See [the context model](../../canon/context/context-model/overview.md) for the full picture.
+Three tiers of context load with different cost: always-loaded (root `CLAUDE.md` and `canon/REQUIREMENTS.md`), path-scoped lazy (`.claude/rules/<scope>.md` with `paths:` glob), and on-demand lookup (`canon/context/<domain>.md`, or `canon/context/<domain>/` once a domain outgrows one file, discovered via `canon/context/index.md`). See [the context model](../../canon/context/context-model.md) for the full picture.
 
 Run `canon init` to seed the `.claude/` directory, a root `CLAUDE.md` file, and `.claude/rules/` in one pass. `canon init` chains claude init and governance install. Claude Code auto-loads every file in `.claude/rules/` at session start, applying always-on rules unconditionally and path-scoped rules to files matching their `paths:` glob.
 
@@ -58,7 +58,7 @@ Then plan and build:
 - Invoke `canon:plan-feature` to scan for code-level conflicts and ambiguities, confirm approach before proceeding
 - Implement the feature, then Claude Code runs the commands defined in `CLAUDE.md`, fixes failures, and iterates until all pass
 - For UI changes, invoke `canon:ui-checklist` to write what a reviewer has to look at and name any behavior shipping without a test
-  End the session once the feature works and tests pass. Invoke `canon:context-fold` to capture any decisions made during implementation before closing.
+  End the session once the feature works and tests pass. Invoke `canon:context-fold` before closing to refresh any context entry the diff left untrue.
 
 The routing test is whether the repository can answer an item today. A session grepping handles the yes, and a groundwork track handles the no.
 

package/docs/workflow/parallel-features.md

@@ -54,7 +54,7 @@ A plan that ships is archived, never deleted. `canon tasks archive` moves it to
 
 An older branch review report takes the other route and is swept rather than archived. It sits flat in `.canon/review/` as `branch-<slug>.md`, the session addressing it read it once, and the durable record of what a review found is the comment `review-pr` posts on the pull request, so `canon:task-complete` deletes any report whose branch is gone. The body that writes a report owns how long it lives, which leaves the shipping branch's own report on disk through the run that cites it and collects it a branch later. What that loses is a local-only review on a branch that never opened a pull request, which is why the report says so where a reader meets it.
 
-`canon:task-complete` decides which task closed by reading the diff rather than the conversation, as the ship-chain step after `canon:context-fold`. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. Decisions stay session-sourced, because a diff cannot carry a judgment, and `canon:context-fold` folds them into the context entries. The requirements record is never folded. A direction change gets one report line naming `canon:document-health`, which reviews that record only when asked.
+`canon:task-complete` decides which task closed by reading the diff rather than the conversation, as the ship-chain step after `canon:context-fold`. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. `canon:context-fold` reads the same diff and rewrites a context entry only where a folder moved or a bullet or gotcha went untrue, and the pull request records each decision. The requirements record is never folded. A direction change gets one report line naming `canon:document-health`, which reviews that record only when asked.
 
 ## Shipping a fan-out
 
@@ -64,7 +64,7 @@ A fan-out of N worktrees produces N pull requests. The order they merge in matte
 
 - `CLAUDE.md`, since cross-domain behavior lives there
 - `tooling/**`, since stack manifests, golden configs, and seeds are tightly coupled
-- `canon/context/context-model/overview.md` and `docs/agents/`, which several domains cross-reference
+- `canon/context/context-model.md` and `docs/agents/`, which several domains cross-reference
 - Any folder's `index.md`, since `canon indexes regen` rewrites it and two worktrees adding files to a regen-covered folder race on it. Resolve its conflict by running the regen over the rebased tree rather than by hand.
 
 Land any in-flight edit to a hotspot on `main` before fanning out where you can. A worktree on a stale `CLAUDE.md` costs more to rebase than it saved.

package/docs/workflow/skill-map.md

@@ -66,7 +66,7 @@ Each row sits under the group its skill's `metadata.family` names. The landing p
 | Skill                 | When to use                                                                                     |
 | --------------------- | ----------------------------------------------------------------------------------------------- |
 | `canon:git-ship`      | To run the whole post-feature chain from the verify gate through open PR                        |
-| `canon:context-fold`  | When decisions diverged from the plan, or the diff left a context entry stale                   |
+| `canon:context-fold`  | When the diff moved a folder or left a context entry's bullet or gotcha untrue                  |
 | `canon:task-complete` | After the fold, to mark the outcomes the diff shipped, or to archive a task the merge hook left |
 | `canon:docs-sync`     | When a change since main left `README.md` or `docs/` stale                                      |
 | `canon:git-stage`     | When the staged set spans several concerns and wants one commit each                            |

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

@@ -22,7 +22,7 @@ Claude Code reads it and writes the implementation. Works for CLI tools, interna
 
 The toolkit seed in `tooling/claude/seeds/canon/DESIGN.md` ships an intent template with a starting set of roles, each naming its custom property, and `claude/skills/canvas-board/references/design.md` carries the same tables under `## Template` with placeholder rows. The column headers are what the parser reads, so they stay verbatim in either, while the rows are the project's own. The seed's lead asks for the project's own stylesheet, such as `src/styles/tokens.css` or a Tailwind `@theme` block, and falls back to `.claude/design/project/` only when the project has none.
 
-`canon design render` writes an HTML plus CSS preview to `.canon/tmp/render/design/` for eyeballing the current system without leaving Claude Code. See `canon/context/design/index.md`.
+`canon design render` writes an HTML plus CSS preview to `.canon/tmp/render/design/` for eyeballing the current system without leaving Claude Code. See `canon/context/design.md`.
 
 A project wanting a neutral starting point to override runs `canon design install`, which copies one stylesheet to `.claude/design/base.css` carrying an achromatic token set as custom properties and two components built on them. Greys run from near-black to near-white and the accent is monochrome, so the only palette the project renders is one it writes itself. That file is toolkit-owned and `canon design sync` refreshes it, so a project overrides a value in `.claude/design/project/` instead, which sync never touches. Nothing arrives without that install, and the two channels are independent: a record the project wrote is its own, and the installed stylesheet is the toolkit's.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.38.0",
+  "version": "5.39.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/commands/claude.ts

@@ -320,7 +320,7 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '',
         'Reports rather than gates. Whether a bullet belongs in a rule is the',
-        'judgment canon/context/context-model/overview.md states, and naming a path is evidence for it',
+        'judgment canon/context/context-model.md states, and naming a path is evidence for it',
         'rather than the answer.',
         '',
         'Examples:',