@erclx/canon 5.38.0 → 5.40.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/records.md

@@ -1,103 +1,61 @@
 ---
 title: Records
-description: The two roots a record folder resolves at, claiming the ordinal intake and groundwork share, reading each folder's size and growth, pruning stale scratch, and where validation, the canonical review count, and the private-remote backup are described
+description: Backing the record folders to a private remote, restoring them on a new machine, reading folder size, and pruning stale scratch
+kind: reference
 ---
 
 # Records
 
-## Record roots
-
-Every verb here resolves a record folder at two roots rather than one. `.canon/<folder>` is read first, `.claude/<folder>` second, and a folder neither root carries resolves to the creation default, which is `.canon/`. The scratch folder is the one name that differs by root, spelled `.canon/tmp` and `.claude/.tmp`, since inside a dotted root the leading dot hides nothing already hidden. <!-- canon-keep-record-root -->
-
-The read order and the creation default agree. While the record folders were moving to a root of their own, creation stayed at `.claude/` so no record landed under a root whose ignore line had yet to reach a project. The ignore line ships now, so a fresh project scaffolds `.canon/` alone, and `.claude/` stays as a read fallback for a project the move has not reached.
-
-A caller never spells a record root by hand for the same reason. A path written as `.canon/plans/...` resolves against one root and reports nothing when it is wrong, which is the quiet failure this ordering exists to prevent: a stale binary meeting a moved layout, writing to the old path, and reporting success. Read a folder through the verb that owns it, and where a skill needs the path itself, take it from that verb's record rather than composing one.
-
-A refusal names every root it looked at, so a message reading `no-folder` says where a write would land as well as where the read failed.
-
-## Validate
-
-`canon records validate <kind>` reports where a record folder disagrees with the standard governing it. Its flags, the per-kind checks, and the refusals are in `records-validate.md`.
-
-## Ordinal
-
-`canon records ordinal <kind> <slug>` reports the next ordinal `intake` and `groundwork` share, or claims it with `--claim`. The two kinds share one sequence, per `claude/skills/plan-intake/references/intake.md` and `claude/skills/plan-groundwork/references/groundwork.md`, so this reads both `.canon/intake/` and `.canon/groundwork/` regardless of which kind was asked for.
+`canon records` backs the record folders under `.canon/` to a private remote and reports on them. `canon hooks post-merge` runs `push` after every merge.
 
 ```bash
-canon records ordinal intake my-topic
-canon records ordinal groundwork my-topic --claim
-canon records ordinal groundwork my-topic --claim --json
-```
-
-| Option          | Behavior                                               |
-| --------------- | ------------------------------------------------------ |
-| `--json`        | Add a machine-readable record on stdout                |
-| `--claim`       | Create the folder atomically instead of only reporting |
-| `--root <path>` | Project root, defaulting to the main worktree          |
-
-Without `--claim` this only reports, so two sessions reading at once can still report the same number, which is what let two sessions open two different record folders under one ordinal on the same day. `--claim` closes that: it reserves the number at a path both an `intake` claim and a `groundwork` claim resolve to identically, whichever kind is asking, and only creates the kind's own `<nn>-<slug>/` folder once that reservation is won. A losing reservation is retried against a freshly read ordinal rather than reported as a collision, bounded to five attempts before refusing as `ordinal-contended`.
-
-Exit codes: `0` reported the next ordinal, or `--claim` created the folder. `1` refused, `unknown-kind` when the argument names neither `intake` nor `groundwork`. `2` `--claim` lost every retry to a collision.
-
-## Size
-
-`canon records size` reports what each record folder holds and how much of it is recent. It reads the same backed folders push carries, resolved the same way, plus the scratch folder, and it gates nothing.
-
-```bash
-canon records size
+canon records push
+canon records pull
 canon records size --json
+canon records prune-tmp --older-than 30
 ```
 
-| Option          | Behavior                                      |
-| --------------- | --------------------------------------------- |
-| `--json`        | Add a machine-readable record on stdout       |
-| `--root <path>` | Project root, defaulting to the main worktree |
-
-The table carries one row per folder that exists, heaviest first, with the file count, the bytes, a count for each growth window, and the dates of the least and most recently written file. Those dates render in the machine's local time, which is the calendar day whoever wrote the file was living in, and the reading is per-machine already. Folders that do not exist are named on one line below it rather than printed as rows of zeros. At the legacy `.claude` root, the record a `--json` call emits carries every folder in the fixed list either way, each with a `present` flag, so a caller reading the record gets a stable set of keys and can tell an absent folder from one the reading skipped. At a `.canon` root, the folder set is read off the directory itself rather than off a fixed list, so an absent folder is not listed at all: nothing enumerates a name nobody has created yet.
-
-Ordering by weight is what makes the reading worth taking. A folder listed alphabetically hides behind its neighbors, and the row a reader came for is the one that grew.
-
-The reading carries two windows rather than one, at 7 and 30 days. A single window cannot separate a folder growing steadily from one that took a single batch: a folder whose 7-day count is most of its 30-day count moved in one pass, and one where the two are proportional is growing at a rate.
+Run `canon records <verb> --help` for every flag.
 
-Nothing fails on a number here. A record folder has no correct size, so the reading is a number to notice rather than a threshold to gate, and the point of the verb is that the next reading is taken by a command instead of by someone remembering to count the folder. A pen went from 44 entries to 236 between two readings taken by hand two weeks apart, which is the measurement this replaces.
+## Output
 
-The scratch folder is read here and skipped by a backup, because deletable without loss is not the same as empty. The routing handoffs and a retired entry archive both sit there and both accumulate. `.canon/.records.git` stays out because it is the backup history rather than a record, and `.claude/worktrees/` stays out because each entry is a checkout of the project with its own removal verb, and one of them outweighs every record folder combined.
-
-The window counts read `mtime`, so what they report is a file written inside the window rather than one created there. An entry edited long after it landed reads as recent, which overstates growth and never understates it, and these folders are append-mostly so the two readings agree on nearly every file. The one reading that is wrong rather than early is a machine restored by `canon records pull`, which resets the work tree hard and re-dates every file it writes, so a window taken there counts the restore. Nothing on the filesystem separates the two, since a restored file is new by every stamp it carries.
-
-Exit codes: `0` the reading completed, `1` refused. The one refusal is `no-folder`, raised when the project holds neither record root. A project holding a root and no records is empty rather than absent: at the legacy `.claude` root each folder's own `present` flag says which ones it carries, and at a `.canon` root the folder list itself is already the answer, since nothing absent is named.
-
-## Prune
-
-`canon records prune-tmp` reports scratch nobody has touched inside an age window, and deletes it only with `--write`. Nothing removed an abandoned scratch folder before this, so a spike folder from months ago sat beside the ones a session still needs.
+Set the history up once per machine, pointed at a private repository that is not a remote of the project.
 
 ```bash
-canon records prune-tmp
-canon records prune-tmp --write
-canon records prune-tmp --older-than 30 --json
+git --git-dir=.canon/.records.git init
+git --git-dir=.canon/.records.git remote add origin <private-repo-url>
+printf '.canon/\n' >> .gitignore
 ```
 
-| Option                | Behavior                                                       |
-| --------------------- | -------------------------------------------------------------- |
-| `--json`              | Add a machine-readable record on stdout                        |
-| `--write`             | Delete every candidate the report lists                        |
-| `--older-than <days>` | Age a unit's newest file must clear to be offered (default 14) |
-| `--root <path>`       | Project root, defaulting to the main worktree                  |
-
-A candidate is a unit whose newest file is older than the threshold: a `tmp/<slug>/` folder, a folder one level inside `runs/`, `render/`, or `pr/`, or a single marker file inside `hooks/<hook>/`. `pr/review/` groups its body files by pull request number rather than reporting as one folder, since a review pass leaves one file per pass and a folder holding thousands of them would otherwise report as a single row nobody can prune apart. A unit holding no files, empty subfolders included, is offered whatever its age.
-
-`tmp/handoff/` and `tmp/pr/poll/` are never offered. A reader deletes a handoff themselves once it has been read, and a poll baseline is live state rather than scratch. The pre-split names the reserved split replaced, `memory-routing/`, `teach-promotion/`, `ui-checklist/`, and `pr-poll/` at the scratch root, are skipped the same way on a project the rename never reached, naming the folder they moved to, rather than being offered as ordinary slugs. An unread handoff is the one thing a wrong delete here loses for good.
+- `push` commits every top-level folder under `.canon/` except `tmp`, `ordinal-locks`, and `.records.git`, then pushes. New folders list under `added`.
+- `pull` restores the folders on a new machine after the setup above. It refuses rather than overwrite records the history lacks.
+- `size` reports one row per folder, heaviest first, with file count, bytes, and growth over 7 and 30 days. After a `pull` every file reads as new.
+- `prune-tmp` lists scratch untouched for 14 days and deletes it only with `--write`. It never offers `tmp/handoff/` or `tmp/pr/poll/`.
 
-A scratch-root name `canon migrate record-layout` or `canon migrate scratch-evidence` moves out of scratch for good, such as `memory-archive`, is skipped the same way on a project that has not yet run that migration, naming the verb to run. The retired-entry archive `memory-archive` holds is never deleted, per the memory standard, so it stays skipped rather than aging into an offer.
+`push` blocks a file over 25 MB or one `canon secrets scan` would report, listing it under `blocked`. Move it out of the record folders, then push again.
 
-It writes nothing until `--write` is passed, since a session record has no history to undo a wrong delete from. It reads `mtime` the way `canon records size` does, so a machine restored by `canon records pull` reads its whole tree as new and fails safe by offering nothing.
+Every verb exits `0` when done and `1` when refused. `prune-tmp` exits `2` when candidates exist and `--write` was not passed.
 
-Exit codes: `0` nothing to prune, or `--write` deleted every candidate. `1` refused, sharing `no-folder` with `size`, or a delete failed. `2` candidates exist and `--write` was not passed.
+## Refusals
 
-## Stale
+Branch on `reason` in the `--json` record, not the exit code.
 
-`canon records stale canonical` reports when the requirements record was last reviewed and how many releases have shipped since. How the release count is taken and the refusals are in `records-stale.md`.
+| Reason              | Meaning                                                                        |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `no-folder`         | The project holds neither record root, from `size` or `prune-tmp`              |
+| `split-roots`       | Record folders sit under both roots. Finish the move or put them back together |
+| `no-repository`     | No `.canon/.records.git`. Run the setup above                                  |
+| `no-remote`         | The records history has no `origin`                                            |
+| `remote-unreadable` | The project's own remotes could not be read                                    |
+| `remote-shared`     | The records origin is also a remote of the project. Use a private repository   |
+| `no-remote-records` | `pull` found no branch on the records origin                                   |
+| `local-changes`     | `pull` found records on disk that the history lacks. Run `push` first          |
+| `local-ahead`       | `pull` found local commits that never reached the origin. Run `push` first     |
+| `unsafe-payload`    | `push` found a file over 25 MB or carrying a credential                        |
+| `git-failed`        | A git call failed, with its stderr in the message                              |
 
-## Push and pull
+## See also
 
-`canon records push` backs the record folders to a private remote and `canon records pull` restores them. The payload, the setup, and the refusals are in `records-push.md`.
+- `canon records ordinal <kind> <slug> --claim`: reserve the next intake or groundwork ordinal
+- `canon records validate <kind> --help`: where a record folder disagrees with its standard
+- `canon records stale --help`: when the requirements record was last reviewed

package/docs/agents/sessions-transfer.md

@@ -1,93 +1,49 @@
 ---
 title: Sessions transfer
-description: Moving a session to another machine, the export bundle and its manifest, placing it with import, the refusal reasons, and what a resume on the target depends on
+description: Moving a session to another machine with export and import, the manifest fields, the refusal reasons, and what a resume on the target depends on
+kind: reference
 ---
 
 # Sessions transfer
 
-The roster these verbs check an id against is in `sessions.md`.
-
-## Export
-
-`canon sessions export <id>` packs one session into a single gzip tarball so it can resume on another machine. The bundle holds the transcript, its side folder with every path kept, and a manifest.
+`canon sessions export` packs one session into a gzip tarball, and `canon sessions import` places it under this machine's configuration directory so `claude` can resume it.
 
 ```bash
-canon sessions export <id>
 canon sessions export <id> --out ~/session.tar.gz --json
-```
-
-| Option         | Behavior                                                   |
-| -------------- | ---------------------------------------------------------- |
-| `--out <path>` | Write the bundle here rather than under the scratch folder |
-| `--json`       | Add a machine-readable record on stdout                    |
-
-Without `--out` the bundle lands at `.canon/tmp/session-export/<id>.tar.gz` under the main worktree root, which is gitignored and reclaimed by `canon records prune-tmp`. It writes locally and never uploads. A transcript holds whatever tool output passed through the session, credentials included where one was printed, so treat the bundle as private.
-
-Exit codes: `0` the bundle was written, `1` refused. The refusal carries a `reason` of `not-found`, where no project folder holds a transcript for the id, or `no-archive`, where the running Bun predates `Bun.Archive`.
-
-The lookup walks every folder under the configuration directory's `projects/`, so a transcript filed under any encoding is found. The transcript is read up to its last newline and never rewritten, so a session exporting itself mid-append drops at most the half line it was writing.
-
-Export runs no skill. Write a handoff with `canon:session-compact` and push it with `canon records push` first where one is wanted. The manifest reports whether a handoff exists and whether it reached the records history, and whatever calls the verb owns that order.
-
-### The manifest
-
-| Field              | Holds                                                                        |
-| ------------------ | ---------------------------------------------------------------------------- |
-| `format`           | The bundle format version, `1`                                               |
-| `sessionId`        | The exported id                                                              |
-| `title`            | The last custom title the transcript recorded, or `null`                     |
-| `cwd`              | The last working directory the transcript recorded, or `null`                |
-| `root`             | The main worktree root of the repository the export read                     |
-| `origin`           | The `origin` remote reduced to `host/path`, or `null`                        |
-| `branch`, `head`   | The branch and commit of the checkout the export ran in                      |
-| `recordsHead`      | The records history `HEAD`, or `null` where no records history exists        |
-| `compacted`        | Whether the transcript carries a compaction boundary                         |
-| `live`             | Whether the id was live in the roster at export                              |
-| `handoff`          | The newest `.canon/compact/` note written since the session began, or `null` |
-| `handoffCommitted` | Whether that note is committed in the records history                        |
-| `recommend`        | `handoff` where a handoff exists, `transcript` otherwise                     |
-
-`recommend` prefers the handoff even though the transcript resumes in full. A resumed transcript carries the source machine's absolute paths into a session working somewhere else, and a handoff states the work without them.
-
-## Import
-
-`canon sessions import <bundle>` places an exported session under this machine's configuration directory so `claude` can resume it.
-
-```bash
-canon sessions import session.tar.gz
 canon sessions import session.tar.gz --root ~/repos/canon --json
 ```
 
-| Option          | Behavior                                                   |
-| --------------- | ---------------------------------------------------------- |
-| `--root <path>` | The repository to resume in. Defaults to the main worktree |
-| `--json`        | Add a machine-readable record on stdout                    |
+Run `canon sessions export --help` and `canon sessions import --help` for every flag.
 
-The transcript and side folder land under `projects/<encoding>/`, where the encoding is the root with every character outside `[A-Za-z0-9]` turned into a dash. Import writes new files only and never overwrites.
+## Output
 
-Exit codes: `0` the session was placed, `1` refused. The refusal carries one of these reasons:
+Export writes the transcript, its side folder, and a manifest to `.canon/tmp/session-export/<id>.tar.gz` unless `--out` says otherwise. It never uploads. A transcript can hold credentials printed in the session, so treat the bundle as private.
 
-| Reason             | Meaning                                                                                                                                                           |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `not-a-bundle`     | the file is no gzip tarball, carries no manifest at format `1`, or names a path outside its own session, such as one climbing out with `..` or an absolute one    |
-| `other-repository` | the local `origin` differs from the one the bundle recorded                                                                                                       |
-| `exists`           | the target transcript or side folder is already there, or any other project folder already holds a transcript for the id, which `--resume <id>` could reach first |
-| `live-here`        | the id is live in the local roster, so a second copy would fork it                                                                                                |
-| `write-failed`     | a write failed partway for a reason other than a copy appearing, such as a bundle carrying a file where it also needs a folder                                    |
-| `no-archive`       | the running Bun predates `Bun.Archive`                                                                                                                            |
+The manifest names the session, its `branch` and `head`, and these fields:
 
-A write that fails partway removes every file this run placed and every folder it created before refusing, so a retry of the same bundle does not refuse on its own leftovers. Any path it could not remove is named in the message. A copy that appears between the existence check and the write refuses as `exists` on the same terms.
+- `live`: whether the id was live in the roster at export
+- `handoff` and `handoffCommitted`: the newest `.canon/compact/` note since the session began, and whether the records history holds it
+- `recommend`: `handoff` where one exists, `transcript` otherwise, since a transcript carries the source machine's absolute paths
 
-A placed session can still lag the source. The record's `behind` list carries `repository-behind` when this checkout lacks the exported `HEAD`, and `records-behind` when the records history lacks the exported records commit, which `canon records pull` brings. Neither refuses, since each has a remedy the reader runs before resuming.
+Import writes new files only. The record's `behind` list carries `repository-behind` when this checkout lacks the exported `HEAD`, and `records-behind` when `canon records pull` has records to bring. Neither refuses. Its two `routes` are `claude --resume <id>` and a fresh `claude` running `/canon:session-resume`.
 
-On success the record carries two `routes`. One runs `claude --resume <id>` from the root, and the other starts `claude` there and runs `/canon:session-resume` bare against the handoff.
+Resuming while the source keeps running forks the conversation, and only `live` warns of it.
 
-### What resume depends on
+## Refusals
 
-Measured on `claude` 2.1.281 on 2026-09-24, `--resume <id>` found a copied transcript in any folder under `projects/` and chained the next turn onto its full history, run from a repository path the transcript never recorded. `--continue` found it only under the local encoding, which is why import derives the folder rather than keeping the source machine's.
+Branch on `reason` in the record, not the exit code.
 
-The encoding is inferred from observed folders rather than read from a published rule, and how a client shortens a path past its length limit was never observed. A client changing the rule leaves `--continue` looking elsewhere while `--resume <id>` still works. The framed report names the derived folder so a reader can compare.
+| Reason             | Meaning                                                                               |
+| ------------------ | ------------------------------------------------------------------------------------- |
+| `not-found`        | Export found no transcript for the id                                                 |
+| `not-a-bundle`     | No gzip tarball, no manifest at format `1`, or a path outside itself                  |
+| `other-repository` | The local `origin` differs from the one the bundle recorded                           |
+| `exists`           | The transcript or side folder is already here, or another project folder holds the id |
+| `live-here`        | The id is live in the local roster, so a second copy would fork it                    |
+| `write-failed`     | A write failed partway. The run removes what it placed before refusing                |
+| `no-archive`       | The running Bun predates `Bun.Archive`                                                |
 
-The side folder did not change the conversation sent. What it carries is `tool-results/`, which a `persisted-output` pointer in the transcript names by the source machine's absolute path, and `subagents/`, which holds background agent transcripts. On a machine whose path matches, those pointers resolve. On one whose path differs, they dangle.
+## See also
 
-Resuming on the target while the source session keeps running forks the conversation, and nothing detects that across machines. The manifest's `live` field and the printed routes are the only warning.
+- `canon sessions list --help`: the roster these verbs check an id against
+- `canon:session-compact` and [records push](records.md): write and back up a handoff before export