@erclx/canon 4.6.1 → 4.8.0

package/claude/skills/git-ship/SKILL.md

@@ -23,7 +23,7 @@ Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If ou
 
 ## Sequence
 
-1. Invoke `canon:claude-memory-capture` to route what this session learned to the context entries that own it and write the residue to `.claude/memory/`
+1. Invoke `canon:claude-memory-capture` to route what this session learned to the context entries that own it and write the residue to `.canon/memory/`
 2. Invoke `canon:claude-docs` to sync internal planning docs against session decisions, folding in the routed facts
 3. Invoke `canon:docs-sync` to sync public docs against changes since main
 4. Run `git add -A` to stage any files the sync skills wrote
@@ -46,8 +46,8 @@ Output up to four lines:
 ```plaintext
 ✅ Shipped
 <N facts routed to context entries>
-<N memories captured in .claude/memory/>
-<Memory proposal at .claude/review/memory/memory-review-<slug>.md>
+<N memories captured in .canon/memory/>
+<Memory proposal at .canon/review/memory/memory-review-<slug>.md>
 ```
 
 Omit the second line if nothing routed. Omit the third and fourth if `claude-memory-capture` wrote no memory file this session, since an empty pen means no scoped review and no proposal.

package/claude/skills/git-split/REQUIREMENT.md

@@ -7,7 +7,7 @@ description: What branch splitting is for, the gaps it closes, and how it differ
 
 ## Gap
 
-Without this skill, a branch carrying unrelated commits ships as one pull request, which a reviewer reads by skimming because no single concern holds it together. Split by hand, commits get cherry-picked in an order that leaves a branch missing something it depends on. Merge order is the sharpest failure: merging the wrong branch first lands every other branch's content on main and leaves the remaining pull requests empty after rebase, with no signal that anything went wrong. Every body it writes stages under `.claude/.tmp/` and leaves through `gh`, neither of which the audit hook watches, so a banned character survives into a published pull request and has to be edited on the remote.
+Without this skill, a branch carrying unrelated commits ships as one pull request, which a reviewer reads by skimming because no single concern holds it together. Split by hand, commits get cherry-picked in an order that leaves a branch missing something it depends on. Merge order is the sharpest failure: merging the wrong branch first lands every other branch's content on main and leaves the remaining pull requests empty after rebase, with no signal that anything went wrong. Every body it writes stages under `.canon/tmp/` and leaves through `gh`, neither of which the audit hook watches, so a banned character survives into a published pull request and has to be edited on the remote.
 
 ## Must
 

package/claude/skills/git-split/SKILL.md

@@ -69,7 +69,7 @@ If Mode is Independent, append this line to the preview:
 
 After outputting the preview, execute the final commands immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
 
-Before running them, run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against every title and body. Each body stages under `.claude/.tmp/` and leaves through `gh`, so the hook sees neither and this scan is the only gate. Each resulting branch reaches the `pull_request` check the git-pr surface carries once its own pull request opens, but not before, so this scan is what catches a leak ahead of that.
+Before running them, run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against every title and body. Each body stages under `.canon/tmp/` and leaves through `gh`, so the hook sees neither and this scan is the only gate. Each resulting branch reaches the `pull_request` check the git-pr surface carries once its own pull request opens, but not before, so this scan is what catches a leak ahead of that.
 
 ### Final commands
 
@@ -80,25 +80,25 @@ For independent mode, base every branch on `main`:
 git branch -m <current_branch> <new_name>
 
 # Create, cherry-pick, push, and open PR for each secondary branch
-mkdir -p .claude/.tmp/pr-split
+mkdir -p .canon/tmp/pr-split
 git switch -c <branch> main && git cherry-pick <sha> <sha> \
   && git push -u origin <branch> \
-  && (cat <<'BODY' > .claude/.tmp/pr-split/<branch>.md
+  && (cat <<'BODY' > .canon/tmp/pr-split/<branch>.md
 <body following pr.md template, written from the cherry-picked commits>
 BODY
-) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<branch>.md \
-  && rm .claude/.tmp/pr-split/<branch>.md
+) && gh pr create --title "<title>" --body-file .canon/tmp/pr-split/<branch>.md \
+  && rm .canon/tmp/pr-split/<branch>.md
 
 # Return to primary branch, push, and open its PR
 git checkout <new_name> && git push -u origin <new_name> \
-  && (cat <<'BODY' > .claude/.tmp/pr-split/<new_name>.md
+  && (cat <<'BODY' > .canon/tmp/pr-split/<new_name>.md
 <body following pr.md template, written from the primary's commits>
 BODY
-) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<new_name>.md \
-  && rm .claude/.tmp/pr-split/<new_name>.md
+) && gh pr create --title "<title>" --body-file .canon/tmp/pr-split/<new_name>.md \
+  && rm .canon/tmp/pr-split/<new_name>.md
 
 # Clean up the body-file dir if all PRs succeeded (no-op when non-empty)
-rmdir .claude/.tmp/pr-split 2>/dev/null || true
+rmdir .canon/tmp/pr-split 2>/dev/null || true
 ```
 
 For stacked mode, base each branch on the previous and cherry-pick only that group's commits:
@@ -107,36 +107,36 @@ For stacked mode, base each branch on the previous and cherry-pick only that gro
 # Rename current branch to reflect primary concern
 git branch -m <current_branch> <new_name>
 
-mkdir -p .claude/.tmp/pr-split
+mkdir -p .canon/tmp/pr-split
 
 # Group 1: based on main
 git switch -c <branch-1> main && git cherry-pick <g1-sha> <g1-sha> \
   && git push -u origin <branch-1> \
-  && (cat <<'BODY' > .claude/.tmp/pr-split/<branch-1>.md
+  && (cat <<'BODY' > .canon/tmp/pr-split/<branch-1>.md
 <body following pr.md template, written from the cherry-picked commits>
 BODY
-) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<branch-1>.md \
-  && rm .claude/.tmp/pr-split/<branch-1>.md
+) && gh pr create --title "<title>" --body-file .canon/tmp/pr-split/<branch-1>.md \
+  && rm .canon/tmp/pr-split/<branch-1>.md
 
 # Group 2: based on <branch-1>, this group's commits only
 git checkout -b <branch-2> && git cherry-pick <g2-sha> <g2-sha> \
   && git push -u origin <branch-2> \
-  && (cat <<'BODY' > .claude/.tmp/pr-split/<branch-2>.md
+  && (cat <<'BODY' > .canon/tmp/pr-split/<branch-2>.md
 <body following pr.md template, written from the cherry-picked commits>
 BODY
-) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<branch-2>.md \
-  && rm .claude/.tmp/pr-split/<branch-2>.md
+) && gh pr create --title "<title>" --body-file .canon/tmp/pr-split/<branch-2>.md \
+  && rm .canon/tmp/pr-split/<branch-2>.md
 
 # Return to primary branch, push, and open its PR
 git checkout <new_name> && git push -u origin <new_name> \
-  && (cat <<'BODY' > .claude/.tmp/pr-split/<new_name>.md
+  && (cat <<'BODY' > .canon/tmp/pr-split/<new_name>.md
 <body following pr.md template, written from the primary's commits>
 BODY
-) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<new_name>.md \
-  && rm .claude/.tmp/pr-split/<new_name>.md
+) && gh pr create --title "<title>" --body-file .canon/tmp/pr-split/<new_name>.md \
+  && rm .canon/tmp/pr-split/<new_name>.md
 
 # Clean up the body-file dir if all PRs succeeded (no-op when non-empty)
-rmdir .claude/.tmp/pr-split 2>/dev/null || true
+rmdir .canon/tmp/pr-split 2>/dev/null || true
 ```
 
 ## After execution

package/claude/skills/migration-superseded/SKILL.md

@@ -35,7 +35,7 @@ No listing substitutes for the field. The pairing runs against the seed folder n
 
 Run `canon standards list --json` and match each entry's `replacedBy` against the `appliesTo` array the catalog declares. Resolve from the catalog rather than from the folder stem, so a seed folder the toolkit adds later resolves without an edit here.
 
-Compare on the folder rather than on the exact string. An `appliesTo` value matches when it equals `replacedBy` or begins with `replacedBy` followed by a slash. The report spells the folder `.claude/tasks` and the catalog spells it `.claude/tasks/`, and `memory` declares a filename pattern beneath its folder rather than the folder itself, so string equality matches nothing the catalog actually carries and sends every entry to a decline below.
+Compare on the folder rather than on the exact string. An `appliesTo` value matches when it equals `replacedBy` or begins with `replacedBy` followed by a slash. The report spells the folder `.canon/tasks` and the catalog spells it `.canon/tasks/`, and `memory` declares a filename pattern beneath its folder rather than the folder itself, so string equality matches nothing the catalog actually carries and sends every entry to a decline below.
 
 ### Read the standard through the verb
 
@@ -88,12 +88,12 @@ Print one block per superseded entry, then the shared reminder. Omit empty group
 ```markdown
 ## Split
 
-`.claude/TASKS.md` → `.claude/tasks/`, shaped by `canon standards tasks`
+`.claude/TASKS.md` → `.canon/tasks/`, shaped by `canon standards tasks`
 
 ## Proposed files
 
-- `.claude/tasks/vXX.Y-<slug>.md` ← the "<heading>" section
-- `.claude/tasks/vXX.Y-<slug>.md` ← the "<heading>" section
+- `.canon/tasks/vXX.Y-<slug>.md` ← the "<heading>" section
+- `.canon/tasks/vXX.Y-<slug>.md` ← the "<heading>" section
 
 Each carries `title` and `description` frontmatter, an `## Outcomes` heading, and a `## Findings` heading.
 

package/claude/skills/session-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: session-map
-description: Writes the session map, the pre-compaction handoff at `.claude/tasks/session-<slug>.md`, from any session whatever role it holds, running the skill-drift step the write procedure opens with. Use when asked to "write the handoff", "write the session map", "save the session before it compacts", "we are about to compact", "hand off to the next session", or "leave a note for whoever picks this up". Do NOT use to route session facts to a context entry or the memory folder, which is `claude-memory-capture` and writes a different artifact, and do NOT use to read a handoff back, which is `session-resume`.
+description: Writes the session map, the pre-compaction handoff at `.canon/tasks/session-<slug>.md`, from any session whatever role it holds, running the skill-drift step the write procedure opens with. Use when asked to "write the handoff", "write the session map", "save the session before it compacts", "we are about to compact", "hand off to the next session", or "leave a note for whoever picks this up". Do NOT use to route session facts to a context entry or the memory folder, which is `claude-memory-capture` and writes a different artifact, and do NOT use to read a handoff back, which is `session-resume`.
 ---
 
 # Session map
@@ -56,7 +56,7 @@ The file sits at the main worktree root, which the file-editing tools refuse fro
 ## Output
 
 ```plaintext
-✅ Session map written: .claude/tasks/session-<slug>.md
+✅ Session map written: .canon/tasks/session-<slug>.md
 <what the drift verb named, or the boundary it refused at>
 ```
 

package/claude/skills/session-resume/SKILL.md

@@ -7,14 +7,14 @@ description: Resumes a previous session by reading the handoff it left behind, t
 
 ## Step 1: read tracked work
 
-Resolve `.claude/plans/`, `.claude/memory/`, and `.claude/tasks/` at the main worktree root per Worktrees in `CLAUDE.md`.
+Resolve `.canon/plans/`, `.canon/memory/`, and `.canon/tasks/` at the main worktree root per Worktrees in `CLAUDE.md`.
 
 Read these in parallel, skipping any that do not exist:
 
-- the newest `.claude/tasks/session-*.md`: the handoff a previous session wrote before a compaction, per `${CLAUDE_SKILL_DIR}/../../standards/session.md`. It leads the report rather than the reads.
-- `.claude/tasks/index.md`: the folder catalog. Read this before any individual task file, and take the task list from it by dropping the `index`, `priority`, `backlog`, and `session-` rows, which are siblings rather than tasks.
-- `.claude/plans/*.md`: execution detail for in-progress tasks
-- `.claude/memory/index.md` and any memory files relevant to the top backlog item
+- the newest `.canon/tasks/session-*.md`: the handoff a previous session wrote before a compaction, per `${CLAUDE_SKILL_DIR}/../../standards/session.md`. It leads the report rather than the reads.
+- `.canon/tasks/index.md`: the folder catalog. Read this before any individual task file, and take the task list from it by dropping the `index`, `priority`, `backlog`, and `session-` rows, which are siblings rather than tasks.
+- `.canon/plans/*.md`: execution detail for in-progress tasks
+- `.canon/memory/index.md` and any memory files relevant to the top backlog item
 
 Then read only the task files the summary needs, typically the top one. Do not read the whole folder.
 
@@ -28,9 +28,9 @@ Output these sections, omitting the first when no handoff was found:
 
 **Carried over:** the reasoning the handoff holds, as its writer stated it. Attribute it to the map rather than restating it as fact, and re-measure any count, size, or cost before acting on one.
 
-**Up next:** one line per task row in `.claude/tasks/index.md`, preserving order. A board carrying handoffs has a row per session that wrote one, so a report listing every row queues work nobody filed.
+**Up next:** one line per task row in `.canon/tasks/index.md`, preserving order. A board carrying handoffs has a row per session that wrote one, so a report listing every row queues work nobody filed.
 
-**Active plans:** one line per file in `.claude/plans/`, linking each to its task file in `.claude/tasks/`. Say "None" if empty.
+**Active plans:** one line per file in `.canon/plans/`, linking each to its task file in `.canon/tasks/`. Say "None" if empty.
 
 **Relevant context:** two or three memory entries that inform the top backlog item. Skip if none apply.
 
@@ -40,7 +40,7 @@ End with one line: `Start with: <first Up next item>` and note whether it has a
 
 When the board is empty and a handoff was found, name what the handoff leaves open instead: `Start with: <the open thread the handoff names>`. A recommendation slot filled with nothing reads as a failed run, and a handoff on an empty board is the shape a session leaves when it was reasoning rather than shipping.
 
-Do not offer to remove entries. A completed task is archived out of `.claude/tasks/` when work ships. The git log is the authoritative record of shipped work. Plan files are archived per the plan lifecycle rule in `CLAUDE.md`.
+Do not offer to remove entries. A completed task is archived out of `.canon/tasks/` when work ships. The git log is the authoritative record of shipped work. Plan files are archived per the plan lifecycle rule in `CLAUDE.md`.
 
 Memory is updated only when a recorded fact becomes wrong, never on resume. A domain fact reaches a session through `.claude/context/`, which `claude-memory-capture` routes to and the three-tier model loads on demand, so the memory folder read here is the residue no context entry owns.
 

package/docs/agents/capture.md

@@ -1,28 +1,30 @@
 ---
 title: Capture
-description: Rendering committed HTML sources to PNG, what the command asserts about fonts, and why it is toolkit-only
+description: Rendering HTML sources to PNG, what the command asserts about fonts, and why the selector has no default
 ---
 
 # Capture
 
-`canon capture [source]` renders HTML capture sources to PNG, which is how a committed documentation image regenerates from its committed source. The source defaults to `assets/`, where a directory expands to every `.html` directly inside it, so adding a capture means dropping a file beside the first one and running the same bare command.
+`canon capture [source] --selector <sel>` renders HTML sources to PNG, which is how a generated documentation image is rebuilt from the markup it was generated out of. The source defaults to `assets/`, where a directory expands to every `.html` directly inside it, so adding a capture means dropping a file beside the first one and running the same command.
 
 ```bash
-canon capture
-canon capture assets/install.html
-canon capture assets --out .claude/review/captures
+canon capture --selector .window
+canon capture assets/install.html --selector .window
+canon capture assets --selector .window --out .canon/review/captures
 ```
 
-`assets/` now holds two sources, so a bare `canon capture` rebuilds both. `install.html` is hand-authored and its text came from a real run. `hero.html` is generated by `scripts/core/regen-hero.sh` from the CLI catalogs and must not be edited by hand, since `bun run check` regenerates it and fails on the difference.
+`--selector` is required and every example above passes it. The element a capture crops to belongs to the page, not to the command, so there is no value that could be right for an arbitrary project's markup. `.window` is what this repository's own two sources declare, and a project renders its own pages by naming whatever theirs declare.
 
-Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `canon capture assets/hero.html` when the check reports the HTML changed.
+`assets/` here holds two sources, so one run over the folder rebuilds both. `install.html` is hand-authored and its text came from a real run. `hero.html` is generated by `scripts/core/regen-hero.sh` from the CLI catalogs and must not be edited by hand, since `bun run check` regenerates it and fails on the difference.
+
+Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `canon capture assets/hero.html --selector .window` when the check reports the HTML changed.
 
 Every render writes a stamp beside its PNG, `hero.png` next to `hero.stamp`, holding the source filename, a `source-sha256` over the markup bytes it read, and an `image-sha256` over the image bytes it wrote. Both digests are what `bun run check` compares, so a markup edit committed without a capture and a PNG swapped under unchanged markup each fail. The stamp is tracked and commits alongside the pair. Nothing hand-edits it, and a capture that cannot write it reports that source as failed and exits 1, so an image whose stamp never landed is reported rather than passed over.
 
 | Option             | Behavior                                          |
 | ------------------ | ------------------------------------------------- |
 | `--out <dir>`      | Write every PNG here instead of beside its source |
-| `--selector <sel>` | Element to capture (default: `.window`)           |
+| `--selector <sel>` | Element to capture, required and never defaulted  |
 
 ## What the command asserts
 
@@ -30,8 +32,12 @@ Each source renders at `deviceScaleFactor` 2 with a transparent background, and
 
 What is asserted is the font. The command reads the first family the captured element declares and fails when the browser did not resolve it, because a fallback face rewraps the block and silently changes the output. Sources therefore name a real font rather than relying on `monospace`. A source that cannot render reports its own line and exits 1 without dropping the rest of the batch.
 
-The browser binary installs separately from the package. A fresh clone runs `bunx playwright install chromium` once, and a run that cannot launch one reports the engine's own remediation inside the frame and exits 1 rather than escaping as a stack trace.
+A run refuses before it reads anything else when `--selector` is absent, naming the flag and pointing at `--help`. Ordering it first is what keeps the message about the invocation: the source defaults to `assets`, so checking that first would answer `assets not found` from whatever directory the caller happened to be in and say nothing about the flag that was actually missing.
+
+The browser binary installs separately from the package. A first run does `bunx playwright install chromium` once, and a run that cannot launch one reports the engine's own remediation inside the frame and exits 1 rather than escaping as a stack trace.
+
+The command ships to targets, alongside `demo`, `inventory`, and `drive`. It was held back while its only caller was this repository regenerating its own committed images, which described the caller rather than the render. A project has generated pages of its own, and the command that would show them rendering and prove their fonts resolved was the one it could not run.
 
-The command is toolkit-only. Its render module holds every browser reference capture makes and `files` in `package.json` excludes it, so an installed `canon` carries the command, reports it as absent on one line, and exits 1. Every other command is unaffected, which is the reason the browser import sits behind a dynamic import rather than at a command's top level.
+Shipping it also fixed what the exclusion was hiding. The render module imported the `@playwright/test` development dependency, which no published tarball carries. Every browser reference still sits behind a dynamic import, so a browser loads for this command rather than in front of every other one.
 
-`canon demo` is the other browser command and it ships, because the reason capture stays here is that it regenerates images committed to this repository and a target has nothing to regenerate. See `demo.md`.
+`demo.md` and `driver.md` cover two of the other three browser commands. What separates this one is that a capture renders a single state from a file on disk, where the rest drive a running application.

package/docs/agents/commands.md

@@ -24,7 +24,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon design render`         | Render `.claude/DESIGN.md` tokens to HTML and CSS                                                                                                                     |
 | `canon slides render`         | Render a `.claude/SLIDES.md` source into a PowerPoint deck, reporting any unrecognized layout name on stderr                                                          |
 | `canon slides list`           | List the available slide layouts (`--json` for the catalog)                                                                                                           |
-| `canon feedback`              | Write toolkit feedback from stdin to `.claude/review/feedback/`, or open a GitHub issue with `--github`                                                               |
+| `canon feedback`              | Write toolkit feedback from stdin to `.canon/review/feedback/`, or open a GitHub issue with `--github`                                                                |
 | `canon transcripts <url>`     | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                                                                                                 |
 | `canon tasks archive`         | Move a shipped task off the board, clear its ordering row, and regenerate the index                                                                                   |
 | `canon tasks pull-request`    | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                                                              |
@@ -42,6 +42,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon records push`          | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                                            |
 | `canon records pull`          | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                               |
 | `canon migrate rename`        | Rewrite every unprotected `aitk` token to `canon` and move the paths that carry the name, reporting the plan without `--write` (`--scope`, `--json`)                  |
+| `canon migrate records`       | Move the gitignored session records to `.canon/` and repoint every tracked citation, reporting the plan without `--write` (`--root`, `--json`)                        |
 | `canon sessions list`         | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                                        |
 | `canon worktrees list`        | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                            |
 | `canon comments scan`         | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                |
@@ -71,11 +72,11 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon gate run`              | Run every stage that guards a branch here, scoping shell, types, and tests to the changed set (`--all`, `--no-write`, `--nested`, `--json`)                           |
 | `canon inventory [subject]`   | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`)                                  |
 | `canon drive <url> <run>`     | Walk a page through named interactions and measure each state it reaches, reporting findings rather than gating (`--json`)                                            |
-| `canon capture [source]`      | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                                                 |
+| `canon capture [source]`      | Render HTML sources to PNG and prove the font each one declares resolved (`--selector` required, `--out`)                                                             |
 | `canon serve [dir]`           | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--json`)                               |
 | `canon upgrade`               | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                                                 |
 
-`canon serve` ships and drives no browser, which is what separates it from the two that do. A generated page loses its stylesheet and its script to an editor preview and to a `file://` open, so the link is the delivery rather than a convenience, and every generated surface here reaches a reader through one. It binds `127.0.0.1` and never a wildcard, because what it is pointed at is routinely a gitignored record tree. It sends `cache-control: no-store`, since a preview exists to be edited and reloaded and a cached stylesheet reads as a fix that did not work.
+`canon serve` drives no browser, which is what separates it from the four that do. All four ship now that `capture` does, so the line between them is the engine rather than the package. A generated page loses its stylesheet and its script to an editor preview and to a `file://` open, so the link is the delivery rather than a convenience, and every generated surface here reaches a reader through one. It binds `127.0.0.1` and never a wildcard, because what it is pointed at is routinely a gitignored record tree. It sends `cache-control: no-store`, since a preview exists to be edited and reloaded and a cached stylesheet reads as a fix that did not work.
 
 A port already in use is the ordinary case rather than a refusal, so it walks forward to the next free one and reports which it took. That is why a caller reads `url` off the `--json` record instead of composing one from the port it asked for. Only contention is walked past. Any other bind failure refuses as `bind-failed` carrying the error's code, rather than being retried twenty times and reported as a range being full, which names a cause nothing checked.
 
@@ -95,7 +96,7 @@ routes = ["/", "/pricing", "/docs"]
 query = "button, a[href], input, select, textarea, [tabindex]"
 ```
 
-`canon drive` is the fourth and ships for the same reason the two before it do. What separates it from all three is the axis rather than the destination: `capture` and `inventory` each answer about a page as it loads, and every defect that exists only after a menu opens or the page scrolls is invisible to both. It takes a JSON run file naming the viewport, the probes, and the interaction sequence, since a route catalog is state a project holds and an interaction sequence is a script written for one question. Viewport heights are never defaulted, because the heights a defect hides at belong to the layout rather than to this command. It reports findings and never gates, since every probe it ships carries a class of false finding a throwaway version already produced. See `driver.md`.
+`canon drive` is the fourth and ships for the same reason the three before it do. What separates it from all three is the axis rather than the destination: `capture` and `inventory` each answer about a page as it loads, and every defect that exists only after a menu opens or the page scrolls is invisible to both. It takes a JSON run file naming the viewport, the probes, and the interaction sequence, since a route catalog is state a project holds and an interaction sequence is a script written for one question. Viewport heights are never defaulted, because the heights a defect hides at belong to the layout rather than to this command. It reports findings and never gates, since every probe it ships carries a class of false finding a throwaway version already produced. See `driver.md`.
 
 ## Domain commands
 
@@ -122,7 +123,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `secrets`   | `scan`                                                                                                                                |
 | `deps`      | `audit`                                                                                                                               |
 | `labels`    | `audit`                                                                                                                               |
-| `migrate`   | `rename`                                                                                                                              |
+| `migrate`   | `rename`, `records`                                                                                                                   |
 | `autoship`  | `classify`                                                                                                                            |
 | `audits`    | `run`, `list`                                                                                                                         |
 | `gate`      | `run`                                                                                                                                 |
@@ -136,6 +137,8 @@ Common patterns:
 
 `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.
 
+`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. 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 line below it, keeps the old spelling for prose that dates a decision. Running it twice rewrites nothing, which is the check that the exclusions and the markers fired.
+
 ## Version skew
 
 `canon sync --check` and `canon claude skills drift` are the two moments a target

package/docs/agents/demo.md

@@ -10,7 +10,7 @@ description: Compiling a screencast draft into a runnable plan, driving a served
 Two verbs, and they are separate because the artifact between them is edited.
 
 ```bash
-canon demo compile .claude/.tmp/screencast/inline-edit.md
+canon demo compile .canon/tmp/screencast/inline-edit.md
 canon demo run demos/inline-edit.json
 canon demo run demos/inline-edit.json --cursor ~/cursors/theme --out assets
 ```
@@ -75,7 +75,7 @@ Every refusal exits 1 and names its reason in the `--json` record, so a skill br
 
 ## The browser reaches every target
 
-Unlike `canon capture`, this command ships. Capture is toolkit-only because it regenerates images committed to this repository, and that reason does not transfer to a command whose whole purpose is running in someone else's project.
+This command was the first browser command to ship, and `canon capture` has since joined it. Capture was held back because its only caller was this repository regenerating its own committed images, which was a fact about that caller rather than about the render.
 
 The cost is stated rather than hidden: the browser binary installs separately, so a target runs `bunx playwright install chromium` once before a recording works at all. A run that cannot launch reports that command inside the frame and exits 1.
 

package/docs/agents/driver.md

@@ -49,7 +49,7 @@ Every step names what it did, and that name is carried onto each finding it prod
 
 Probes run after a step and never on arrival, so a run reaches the load state by opening with a `wait` step of its own, as the example above does. Nothing probes before the first step runs, which makes that leading step the only way to measure the page as it first painted, and naming it is what puts the load state on its own findings rather than under whatever ran next.
 
-Write one in any project that does not have `canon capture`, which is toolkit-only and renders a single state from a committed source. Where capture runs, it already answers about arrival and a leading `wait` duplicates it. Where it does not, this command is the only thing measuring the page at all, and a run without that step reports every driven state and nothing about the one a visitor sees first.
+Write one wherever no capture runs against the page. `canon capture` renders a single state from a source on disk, so where it runs it already answers about arrival and a leading `wait` duplicates it. Where it does not, this command is the only thing measuring the page at all, and a run without that step reports every driven state and nothing about the one a visitor sees first.
 
 Each height is driven in a context of its own from a fresh navigation, rather than by resizing the page the previous height already drove, since a sweep asks the same question of each height rather than a later question of an already-driven page.
 
@@ -98,6 +98,6 @@ It reports findings and never gates, and the exit code says only whether the dri
 
 An unreachable page refuses rather than returning an empty report, since nothing measured and nothing found read the same to anything counting findings.
 
-The browser binary installs separately from the package, once, with `bunx playwright install chromium`. The command ships to targets like `demo` and `inventory` rather than staying toolkit-only like `capture`, because its whole purpose is measuring a page inside someone else's project. It reaches nothing under `src/capture/`, which the package excludes, so the two surfaces move independently.
+The browser binary installs separately from the package, once, with `bunx playwright install chromium`. The command ships to targets like `demo`, `inventory`, and `capture`, because its whole purpose is measuring a page inside someone else's project. It reaches nothing under `src/capture/`, so the two surfaces move independently.
 
 See `commands.md` for where this sits among the browser commands, and `capture.md` for the single-state render it adds an axis to.

package/docs/agents/index.md

@@ -9,7 +9,7 @@ category: Agent surface
 CLI catalog and invocation rules for agents, split by command domain. Start with overview.
 
 - [Audits](audits.md): Running every health check as one set, what the single verdict means, the exit code each outcome takes, the retained baseline and the delta it reports, and which corpora are kept out of the record
-- [Capture](capture.md): Rendering committed HTML sources to PNG, what the command asserts about fonts, and why it is toolkit-only
+- [Capture](capture.md): Rendering HTML sources to PNG, what the command asserts about fonts, and why the selector has no default
 - [Census](census.md): Tracked-plus-untracked file count, a breakdown by extension, and a line total that skips whatever reads as binary
 - [Command catalog](commands.md): Every project-level command and every domain subcommand, plus the shape each domain exposes
 - [Comments](comments.md): Comment density by language and kind, the two structural exclusions, and how the degradation sweep finds its vocabulary

package/docs/agents/indexes.md

@@ -9,7 +9,7 @@ description: Flags, exit codes, and JSON shape for canon indexes regen, plus whe
 
 Duplicates dedupe. The whole-repo walk prunes `.git`, `node_modules`, and anything `.gitignore` covers via `git check-ignore`.
 
-A positional path is not filtered that way, because the walk-up resolves on the filesystem and never consults git. That is the only way to regenerate an index inside a gitignored folder, and it is how `.claude/tasks/` and `.claude/memory/` both stay current.
+A positional path is not filtered that way, because the walk-up resolves on the filesystem and never consults git. That is the only way to regenerate an index inside a gitignored folder, and it is how `.canon/tasks/` and `.canon/memory/` both stay current.
 
 Each is driven by a `PostToolUse` hook matching `Write|Edit|MultiEdit`, so a file moved by a shell `mv` fires nothing. A caller that relocates an entry runs the command itself once the last move is done.
 

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

@@ -205,7 +205,7 @@ target never touched still reports `matching`. Every other seed copies byte for
 byte.
 
 `superseded` names a file a newer seed folder replaced, such as `.claude/TASKS.md`
-against the `.claude/tasks/` that now ships. The entry carries `replacedBy` and
+against the `.canon/tasks/` that now ships. The entry carries `replacedBy` and
 nothing else, and the file is never deleted, since the content belongs to the
 project and only its author can decide where it moves. The list derives from the
 seed tree rather than from a fixed set of filenames, so a folder added later is

package/docs/agents/intake.md

@@ -7,7 +7,7 @@ description: Reading intake folder counts and items, the three read states an it
 
 ## List
 
-`canon intake list` reports the intake folders under `.claude/intake/`, or the items one folder holds. It reads and never writes, because an answer belongs to the operator and a verb that filled one would decide what the folder exists to ask.
+`canon intake list` reports the intake folders under `.canon/intake/`, or the items one folder holds. It reads and never writes, because an answer belongs to the operator and a verb that filled one would decide what the folder exists to ask.
 
 A folder carries a two-digit ordinal ahead of its slug, as in `21-toolkit-overview`, so a listing sorts by when each opened. A bare slug still resolves: passing `toolkit-overview` matches the one folder whose name is an ordinal ahead of it, and the folder's real name is what every command reports back.
 

package/docs/agents/key-changes.md

@@ -10,7 +10,7 @@ description: Comparing the files a pull request body's Key Changes names against
 ```bash
 canon pr key-changes
 canon pr key-changes 1265 --json
-canon pr key-changes --body .claude/.tmp/pr/body.md --base origin/main
+canon pr key-changes --body .canon/tmp/pr/body.md --base origin/main
 ```
 
 The positional is the pull request to read, defaulting to the one open on this branch.

package/docs/agents/records.md

@@ -7,11 +7,11 @@ description: The two roots a record folder resolves at, validating the session r
 
 ## 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 `.claude/`. The scratch folder is the one name that differs by root, spelled `.claude/.tmp` and `.canon/tmp`, since inside a dotted root the leading dot hides nothing already hidden.
+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 `.claude/`. The scratch folder is the one name that differs by root, spelled `.canon/tmp` and `.canon/tmp`, since inside a dotted root the leading dot hides nothing already hidden.
 
 The read order and the creation default disagree deliberately. The gitignored record folders are moving to a root of their own, and the CLI learns to read both roots in a release that ships ahead of the move, so the binary a session already holds knows where to look by the time a tree relocates. Creating under the new root before then would write records to a root whose ignore line may not have reached a project yet, and it would split one project's records across two roots with no verb able to reconcile them. The move flips the default and nothing else.
 
-A caller never spells a record root by hand for the same reason. A path written as `.claude/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 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.
 
@@ -126,7 +126,7 @@ The reading carries two windows rather than one, at 7 and 30 days. A single wind
 
 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. The memory pen went from 44 entries to 236 between two readings taken by hand two weeks apart, which is the measurement this replaces.
 
-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 the memory archive both sit there and both accumulate. `.claude/.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 scratch folder is read here and skipped by a backup, because deletable without loss is not the same as empty. The routing handoffs and the memory 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.
 
@@ -142,7 +142,7 @@ canon records push --json
 canon records pull
 ```
 
-The backed folders are `diagrams`, `groundwork`, `intake`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`, all under whichever record root the project carries. Eight of them are the Claude ignore group the claude manifest ships, minus three entries: `.claude/.tmp`, which is deletable without loss, `.claude/worktrees/`, whose contents belong to the project repository already, and `.claude/.records.git/`, which is the history the rest are pushed into. `diagrams` is the one that group does not carry at all, since a target still tracks its own copies, which is why the list is spelled out rather than derived. Each name is a top-level record folder and every archive sits inside the one it archives, so the list stays at one entry per surface however many archives appear. It is a constant rather than configuration, and it deliberately does not match the six record kinds `validate` hardcodes.
+The backed folders are `diagrams`, `groundwork`, `intake`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`, all under whichever record root the project carries. They are the record root's own entries less three: `tmp`, which is deletable without loss, `.claude/worktrees/`, whose contents belong to the project repository already, and `.records.git/`, which is the history the rest are pushed into. Nothing bounds the list from outside any more, since the claude manifest ships one `.canon/` root entry and names no folder, so spelling the nine out is what keeps a record folder added later from silently entering the payload. Each name is a top-level record folder and every archive sits inside the one it archives, so the list stays at one entry per surface however many archives appear. It is a constant rather than configuration, and it deliberately does not match the six record kinds `validate` hardcodes.
 
 Records are gitignored by design, so the history lives in a second git directory at `.records.git` inside the record root, with that root as its work tree. Both resolve off the root together rather than folder by folder, since a history opened at one root beside a work tree at the other would stage the deletion of every folder a move relocated. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the nine folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched. Each pathspec is a bare folder name and git reads it against the current directory rather than against the work tree the same call names, so the invocation carries `-C` at the work tree beside the other two flags. That is what lets either verb run from a linked worktree under `.claude/worktrees/`, which sits inside the records work tree and would otherwise prefix every name with its own path.
 
@@ -151,12 +151,12 @@ Records are gitignored by design, so the history lives in a second git directory
 A person creates the records repository once per machine, and the verbs refuse with the commands when it is absent:
 
 ```bash
-git --git-dir=.claude/.records.git init
-git --git-dir=.claude/.records.git remote add origin <private-repo-url>
-printf '.claude/.records.git/\n' >> .gitignore
+git --git-dir=.canon/.records.git init
+git --git-dir=.canon/.records.git remote add origin <private-repo-url>
+printf '.canon/\n' >> .gitignore
 ```
 
-The ignore line is repeated here rather than left to the install, because the person running these commands is the one who creates the directory and the rule is worth reading beside the command that needs it. The claude manifest ships `.claude/.records.git/` as the first entry of its group, so a project that ran `canon claude sync` already carries it and this line is a no-op there. What the group buys is the project that never sets records up: it holds a rule for a directory it will never create, which costs nothing, and the backed-folder derivation above subtracts that entry from the group rather than from a list it does not sit in.
+The ignore line is repeated here rather than left to the install, because the person running these commands is the one who creates the directory and the rule is worth reading beside the command that needs it. The claude manifest ships `.canon/` too, so a project that ran `canon tooling sync` already carries it and this line is a no-op there. One root entry covers the history and every record beside it, which is what makes the rule worth stating once rather than per folder.
 
 Point it at a private repository, and at one that is not a remote of the project. Records carry the memory pen, the review reports, and the groundwork trails, so a public project publishes all of it to anyone who fetches all refs. `push` compares the configured origin against every remote of the project and refuses on a match. A read of that list which fails refuses as well, since an empty list clears the comparison for every origin and a gate that passes on its own failure is no gate.
 
@@ -164,7 +164,8 @@ Point it at a private repository, and at one that is not a remote of the project
 
 | Reason              | What fired                                                                           |
 | ------------------- | ------------------------------------------------------------------------------------ |
-| `no-repository`     | No `.claude/.records.git`, answered with the two setup commands                      |
+| `split-roots`       | Record folders sit under both roots, so the resolved work tree is not the whole set  |
+| `no-repository`     | No `.canon/.records.git`, answered with the two setup commands                       |
 | `no-remote`         | The records history has no `origin`                                                  |
 | `remote-unreadable` | The project's own remotes could not be read, so the shared-origin gate could not run |
 | `remote-shared`     | The records origin is also a remote of the project                                   |
@@ -173,6 +174,8 @@ Point it at a private repository, and at one that is not a remote of the project
 | `local-ahead`       | `pull` found local commits that never reached the origin                             |
 | `git-failed`        | A git call failed, with its stderr in the message                                    |
 
+`split-roots` runs ahead of every gate below it and fires on a half-migrated tree, which is what a `canon migrate records` run that failed partway leaves. `recordRoot` answers for the whole tree on the first root that exists, so a folder left at the old root is absent from the work tree while the records index still names it, and an unguarded `add -A` would stage its deletion and drop it from the remote on the next push. Finish the move, or put the stranded folders back beside the others.
+
 The two `pull` refusals exist because the directions are not symmetric. A push only adds, while a pull onto a machine holding work that never left it would discard that work. Resolve either by running `push` first, or by moving the local folders aside. A machine holding none of the ten has nothing to lose, so a restore onto a fresh checkout runs straight through.
 
 ### When it runs

package/docs/agents/restated.md

@@ -38,9 +38,9 @@ A rule stated in two skill bodies and never in `CLAUDE.md` or another rule is ou
 
 Matching is recall-first and keyed on shared distinctive tokens rather than on a phrase two surfaces spell the same way. The case this exists for was one rule written three different ways, so a near-exact matcher would ship a cheap report blind to the defect it was built for.
 
-A token is distinctive when it appears in at most 20 of the corpus's statements, which is under one percent of them. `.claude/plans/` sits at 14 and is the anchor the motivating case turns on, while `file` sits at 371 and would match most of the tree.
+A token is distinctive when it appears in at most 20 of the corpus's statements, which is under one percent of them. `.canon/plans/` sits at 14 and is the anchor the motivating case turns on, while `file` sits at 371 and would match most of the tree.
 
-A backticked token counts double. An author marking a span as code named an identifier rather than describing one, so `.claude/plans/archive/` says more about what a statement governs than any two prose words do. Two statements are one rule when their shared anchors reach a weight of 3.
+A backticked token counts double. An author marking a span as code named an identifier rather than describing one, so `.canon/plans/archive/` says more about what a statement governs than any two prose words do. Two statements are one rule when their shared anchors reach a weight of 3.
 
 Every record names the anchors its match rested on, so a reader can weigh a finding instead of taking it.
 

package/docs/agents/rule-citations.md

@@ -63,7 +63,7 @@ Two classes resolve to nothing and are right to. Both are reported by name rathe
 
 Only an exact declaration exempts, never a glob match against one. A glob declares a shape, so a body path sitting inside it is still a citation and a stale one is still a defect. A rule scoped at `docs/**` citing a `docs/agents/renamed.md` that moved is exactly the class this stage exists to catch, and matching the glob would excuse it.
 
-**Ignored.** A path git ignores is session scratch no clone is expected to hold. `governance/rules/claude/555-tasks.md` cites `.claude/tasks/index.md`, which is real in a live project and absent from a fresh clone and from every linked worktree. Resolving against the filesystem alone would make the verdict depend on which tree the stage ran in, so the unresolved paths go to one batched `git check-ignore` and an ignored one is excused. A read git cannot answer refuses rather than reporting those paths dead.
+**Ignored.** A path git ignores is session scratch no clone is expected to hold. `governance/rules/claude/555-tasks.md` cites `.canon/tasks/index.md`, which is real in a live project and absent from a fresh clone and from every linked worktree. Resolving against the filesystem alone would make the verdict depend on which tree the stage ran in, so the unresolved paths go to one batched `git check-ignore` and an ignored one is excused. A read git cannot answer refuses rather than reporting those paths dead.
 
 ## Why the glob half reads one corpus
 

package/docs/agents/sandbox.md

@@ -68,6 +68,6 @@ A skill pairs to a scenario by filename, `<category>-<command>` first and bare `
 
 `exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
 
-`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.claude/.tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
+`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.canon/tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
 
 Two more fields ride alongside the verdict rather than inside it. `escapes` lists what the run wrote under a watched toolkit root, which the verdict cannot assert over because those files sit outside the sandbox tree. `sessions` reports the nested-dispatch bound, carrying `watched` for whether the client's session registry was there to read, `new` for the records that appeared while the run was in flight, and `reap` for what the run found in the session's process group afterwards. Neither field fails a run on its own.

package/docs/agents/state-scoped-risk.md

@@ -30,7 +30,7 @@ Three root files are read whether or not the field names them, being `package.js
 
 ### What the corpus leaves out
 
-The corpus answers what the package publishes, which is narrower than what the repository holds. Measured against this repository on 2026-08-21, the scan read 544 files and left 593 of the 1139 git lists unread. Those include everything under `.claude/`, `wiki/`, and `internal/`, the workflow definitions under `.github/`, and the trees the publish negations remove, being `scripts/sandbox/`, `scripts/eval/`, `src/capture/`, and every test file.
+The corpus answers what the package publishes, which is narrower than what the repository holds. Measured against this repository on 2026-08-21, the scan read 544 files and left 593 of the 1139 git lists unread. Those include everything under `.claude/`, `wiki/`, and `internal/`, the workflow definitions under `.github/`, and the trees the publish negations remove, being `scripts/sandbox/`, `scripts/eval/`, and every test file. `src/capture/` was a fourth negation when that reading was taken and is not one now. The folder holds 5 tracked files, 2 of them tests the publish still excludes, so the corpus is 3 wider than the numbers above describe and the unread count is 3 smaller.
 
 A public repository makes that gap readable by anyone, so a clean run means no credential in the published tree rather than none in the repository. The run states the number on every pass, including a clean one, so the bound travels with the verdict. Widening the corpus to every tracked file is a separate decision, since the row this implements puts the shipped tree first on the record's rule that content leaving the repository gates harder than content that stays.