@erclx/canon 5.39.0 → 5.40.0

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

package/docs/target/index.md

@@ -13,5 +13,4 @@ Scaffold, sync, and migrate a toolkit-managed project, with worked setups for th
 - [Target migrations](migrations.md): One-time moves a project scaffolded under an older toolkit runs before its next sync
 - [Target projects](projects.md): Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
 - [Target scenarios](scenarios.md): Worked setups for a markdown-heavy project, a web application, and a monorepo
-- [Target standards moved](standards-moved.md): Which skill owns each standard the retired standards verb used to serve, for a project that still calls it
 - [Target sync](sync.md): Check what drifted in a toolkit-managed project and pull it in, per domain or all at once

package/docs/target/migrations.md

@@ -6,13 +6,11 @@ category: Agent surface
 
 # Target migrations
 
-Each section below is a move a project runs once, when it was scaffolded before the change the section names. Run `canon upgrade` first, so the verb doing the move is the current one. For the recurring sync that follows, see [target sync](sync.md).
+Each section is a move a project runs once, when it was scaffolded before the change it names. Run `canon upgrade` first. The recurring sync that follows is in [target sync](sync.md).
 
 ## Move the records first, once
 
-Session records moved out of `.claude/` and into a root of their own. What is committed stays where it is, and everything gitignored, being the task board, the plans, the memory pen, the review reports, and the scratch folder, now lives under `.canon/`, which a single ignore entry covers.
-
-`4.7.0` carries `canon migrate records`, so run these three lines from inside the project. Run `canon upgrade` first regardless of what you hold, since the sweep learned to pass over the records themselves after that release and a `4.7.0` binary rewrites them.
+Gitignored session records, being the task board, plans, review reports, and scratch, moved from `.claude/` to `.canon/`. Run these from inside the project, and read the `ok` field of the `--json` record rather than the exit code.
 
 ```bash
 canon tooling sync claude . --write
@@ -20,61 +18,49 @@ canon migrate records --json
 canon migrate records --write --json
 ```
 
-The first line takes the `.canon/` ignore entry, and the verb refuses until the project has it, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. The second reports the plan and the third applies it, moving the folders and repointing every tracked file that cites one.
-
-Order matters between the first line and the two under it. The sync prunes the twelve old `.claude/` ignore entries down to the one `.canon/` line, which leaves every record still at the old root visible to git and therefore to the verb. The sweep passes over them on purpose, reporting a count of what it left alone rather than reading the memory pen and the groundwork trails as source.
-
-## Back records up off this machine, once
-
-Moving records under `.canon/` relocates them, and relocating them is not the same as backing them up. Run `canon records push` once a private repository exists for them, and it prints the one-time setup command when it finds none, since the task board, the memory pen, and the groundwork trails otherwise live on one disk with nothing pushing them off it. `canon init` prints the same reminder as a notice-only step rather than trying to run this non-interactively, since the private repository does not exist yet at scaffold time.
-
-Read the `ok` field out of the `--json` record rather than the exit code. A shell profile that wraps `canon` in a function takes its status from whatever the function runs last, so an absent subcommand and a clean run can both exit 0, and a reader watching the exit alone concludes the move happened.
+The first line takes the `.canon/` ignore entry the verb requires. The second reports the plan and the third applies it, repointing every tracked file that cites a moved folder. A line naming an old record path on purpose keeps it with `canon-keep-record-root` on that line or the nearest non-blank line above.
 
-A tracked file that names an old record path on purpose, such as prose dating a decision, keeps it by carrying `canon-keep-record-root` on that line or the nearest non-blank line above. The report pass prints every file it would rewrite, which is where to catch one before `--write` runs.
-
-Until the move runs, the project is exposed. The shipped ignore set no longer names the old record paths, so a project holding records at `.claude/` stops ignoring them on its next `canon tooling sync`, and the first sign is a memory file or a task board appearing in a commit. Every command reads either root, so nothing else breaks in the meantime, and running the move is what closes it.
-
-Then sweep the records themselves, which the three lines above never reach. They enumerate through git, and the records are gitignored by construction, so a task still naming its plan at the old root resolves nothing once the folders move.
+Then sweep the citations inside the records, which the verb above never reaches.
 
 ```bash
 canon migrate record-tree --json
 canon migrate record-tree --write --json
 ```
 
-This is a separate step rather than a fourth line in the block above because the move has to land before there is a new root to walk. The scope is the folders a session still follows a path into, being `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 counted and left alone, since a path inside one of those sits in a sentence about work that already ended.
+It covers `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. Read the report before `--write`. The record tree is untracked, and a wrong rewrite has no undo.
 
-Read the report before `--write` here more carefully than above. The record tree is untracked, so a wrong rewrite has no git undo, and the report names every citation with its line number and the line text for exactly that reason. The same `canon-keep-record-root` marker protects a line that has to keep the old spelling.
+## Back records up off this machine, once
 
-## Move rules off the flat layout, once
+Run `canon records push` once a private repository exists. It prints the one-time setup command when it finds none, and `canon init` prints the same reminder.
 
-Installed rules moved from a flat `.claude/rules/<subdir>/` layout to `.claude/rules/canon/<subdir>/`. A project that installed governance before that release still holds the flat layout, and neither of the two governance verbs below notices: `canon gov sync` reports `No governance surfaces found in target` and exits 0, and `canon gov install` lands a second, wrapped copy beside the stale one rather than replacing it.
+## Move rules off the flat layout, once
 
-Run `canon upgrade` first if you have not, then run this from inside the project:
+Installed rules moved from `.claude/rules/<subdir>/` to `.claude/rules/canon/<subdir>/`. On the flat layout `canon gov sync` exits 0 reporting `No governance surfaces found in target`, and `canon gov install` lands a second copy.
 
 ```bash
 canon migrate rule-layout --json
 canon migrate rule-layout --write --json
 ```
 
-The first line reports the plan and the second applies it, relocating each rule and carrying an edited one's recorded hash forward so it still reports as edited on the next sync rather than reading clean. Run it once, ahead of `canon gov sync` or `canon gov install`, on any project scaffolded before this move landed.
+Run it once, ahead of `canon gov sync` or `canon gov install`.
 
 ## Rename the skill citations, once
 
-Twenty-five plugin skills dropped their `claude-` prefix for two-word names, so `canon:claude-docs` answers as `canon:context-fold` and `canon:claude-tasks` as `canon:task-board`. A project that installed governance or tooling before that release holds files naming the old ones, and the plugin answers to none of them. A later release renamed `docs-fold` to `context-fold`, since the skill folds a session into the context entries and the task board rather than into `docs/`, and the same sweep carries a project across that rename too. The pointer that answered under the old name no longer ships, so a citation the sweep has not reached names nothing. <!-- canon-keep-retired -->
+Plugin skills dropped their `claude-` prefix, so `canon:claude-docs` answers as `canon:context-fold` and `canon:claude-tasks` as `canon:task-board`. The five per-kind drafters merged into `draft-doc`, and no pointer under an old name ships. <!-- canon-keep-retired -->
 
-The same sweep carries the merge of the five per-kind document drafters into `draft-doc`, so a citation of any one of them lands on `canon:draft-doc`.
+- `canvas` is now `canvas-board`. The sweep rewrites only `canon:canvas` and `skills/canvas`, so replace a bare prose mention by hand. <!-- canon-keep-retired -->
+- `design-extract` and `sketch-design` are replaced by `canon:canvas-board`. <!-- canon-keep-retired -->
+- `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, and `canon-rollout` have no successor <!-- canon-keep-retired -->
+- `create-standard`, `markdown-propose`, `memory-review`, `project-commands`, `repo-metadata`, and `ux-walkthrough` have no successor <!-- canon-keep-retired -->
 
-The one skill that took a two-word name from a single word is `canvas`, now `canvas-board`. A bare `canvas` is ordinary prose and the name of a verb, so the sweep rewrites only the forms the skill alone spells, `canon:canvas` and `skills/canvas`. A prose mention of the skill by its bare name stays, so replace it by hand. <!-- canon-keep-retired -->
+Replace a citation of a skill with no successor by hand, or delete the sentence.
 
-Fourteen skills, one verb, and one rule were retired without a rename, so the sweep has nothing to map them to and leaves a citation of one as it stands. `design-extract` and `sketch-design` are replaced by `canon:canvas-board`, which carries a picked direction into `canon/DESIGN.md`. `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, `canon-rollout`, `create-standard`, `markdown-propose`, `memory-review`, `project-commands`, `repo-metadata`, and `ux-walkthrough` have no successor. `canon repo metadata` went with `repo-metadata`, and `canon autoship` went with `review-branch`, whose review step it served. The `120-bash` rule left the `base` stack, so `canon gov sync` removes its installed copy. Replace each citation by hand, or delete the sentence naming a skill that has no successor. <!-- canon-keep-retired -->
+- `canon repo metadata`, `canon autoship`, and the `120-bash` rule are gone, and `canon gov sync` removes the rule <!-- canon-keep-retired -->
+- `memory-capture`, the `603-memory` rule, and the `memory` standard are gone, so send a lesson to the context entry that owns the fact <!-- canon-keep-retired -->
 
-The memory system retired the same way. `memory-capture`, the `603-memory` rule, and the `memory` standard have no successor, and a citation of any one is replaced by hand or deleted. Ship chains no longer capture a session's lessons, so a lesson goes to the context entry that owns the fact, or to a task's findings. The `memory` record kind left `canon records` with it, and so did `canon records migrate`, whose one transform repaired a memory record. `canon records validate memory` and `canon records stale memory` now refuse as an unknown kind, and `canon records migrate` is an unknown command. A target that upgrades the CLI while a pre-retirement plugin still runs `memory-review` gets that refusal, which is the intended outcome. A `.canon/memory/` folder a target holds is still backed up by `canon records push`. <!-- canon-keep-retired -->
+The `memory` record kind left `canon records`, so `canon records validate memory` refuses as an unknown kind and `canon records migrate` is gone.
 
-An installed target keeps its `.canon/memory/` folder and the memory arms of its seeded `records-index.sh` and `standards-audit.sh` hooks, since `canon claude sync` writes only a seed a target lacks. Both are inert: nothing writes the folder, and the hooks match no file. `canon gov sync` removes the installed `603-memory` rule and the generated `memory` standard rule.
-
-Two of those files run rather than sit there. `.husky/post-merge` runs the `canon hooks post-merge` verb, so a stale copy of the hook calls a binary that may lack it, and `.claude/hooks/pr-create-log.sh` hands a session a message naming a skill, so a stale copy tells someone to invoke something that no longer exists. A copy older than `git-pr`'s move to REST also matches only `gh pr create`, so it stays silent on every pull request `git-pr` opens. A rule under `.claude/rules/canon/core/` names skills too, though a rule is read rather than run.
-
-Resync what the toolkit owns, then sweep what the project wrote:
+Two held files run, `.husky/post-merge` and `.claude/hooks/pr-create-log.sh`, and a stale copy calls a missing binary or names a removed skill. Resync what the toolkit owns before sweeping what the project wrote, and run the second line once per stack.
 
 ```bash
 canon gov sync
@@ -83,65 +69,70 @@ canon migrate skill-names --json
 canon migrate skill-names --write --json
 ```
 
-Run the second line once per stack the project holds, since the two hooks above arrive from different ones. The third reports the plan and the fourth applies it.
-
-The order carries the reason. A sync replaces each toolkit-owned copy with one already carrying the new names, and the sweep afterwards reaches the prose the project wrote itself. Sweeping first rewrites those installed files in place, which moves them off the hash the install recorded, so the next sync reads them as edited by the project and leaves them alone.
-
 ## Rename the pull request template headings, once
 
-The pull request section headings moved to sentence case, so the template seeds `## Key changes` and `## Technical context`. `canon labels scan` now fails a body whose level-two heading is outside the closed list, and it compares case exactly, so a body written under the old `## Key Changes` heading fails the pull request gate.
-
-A project scaffolded earlier holds the old template at `.github/pull_request_template.md`, and a sync writes only a seed a target lacks. Rename the two headings in that file by hand, or delete it and run `canon tooling sync base . --write` to take the new seed. Do it ahead of the first pull request after `canon upgrade`. `canon pr key-changes` reads either casing, so a body already open keeps parsing, and only the scan needs the rename on its next edit.
+The template headings are now `## Key changes` and `## Technical context`, and `canon labels scan` compares case exactly. Rename them in `.github/pull_request_template.md`, or delete it and run `canon tooling sync base . --write`.
 
 ## Move the surfaces off `.claude/`, once
 
-Tracked surfaces moved out of `.claude/` and into a root of their own. `context/`, `wireframes/`, the three loose documents (`ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`), and the install stamp folder, respelled `canon/config/`, now live under `canon/`, and `rules/`, `skills/`, `hooks/`, and `settings.json` stay put since Claude Code reads those by path.
-
-Run `canon upgrade` first if you have not, then run this from inside the project:
+`context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the install stamp folder, now `canon/config/`, moved under `canon/`. `rules/`, `skills/`, `hooks/`, and `settings.json` stay where Claude Code reads them.
 
 ```bash
 canon migrate surface-roots --json
 canon migrate surface-roots --write --json
 ```
 
-The first line reports the plan and the second applies it, moving each surface with `git mv` so its history follows and repointing every tracked citation of one in the same run. See `canon docs agents` for the full file list rather than reading it here.
-
-Neither `canon sync --check` nor any other command notices a surface still sitting at `.claude/`, so running this is on you rather than on a prompt from the toolkit.
+It moves each surface with `git mv` and repoints every tracked citation. No other command notices a surface left at `.claude/`.
 
 ## Delete the retired snippets, once
 
-The toolkit retired snippets, deleting the catalog, the `canon snippets` verb, and the `create-snippet` skill. A project scaffolded while the domain still installed may hold a `.claude/snippets/` folder, which nothing reads any more. Find it with the reverse walk:
+A project scaffolded while snippets installed may hold `.claude/snippets/` or a root `snippets/`.
 
 ```bash
 canon sync --check . --json | jq '.reverse'
 ```
 
-The walk checks both `.claude/snippets` and a root `snippets/`, since a toolkit old enough installed at the project root. Act on each entry by its verdict, whichever path it sits at:
-
-- `dropped` is the toolkit's copy, unchanged, and deleting the folder is safe
-- `unattributed` holds files the toolkit shipped under those names with content it never published, which is usually a copy the project edited, so read what changed before deleting anything
-- `project` is content the project wrote under the same name, which the retirement does not reach, so leave it alone
+- `dropped` is the toolkit's copy, unchanged, so delete it
+- `unattributed` is often an edited copy, so read what changed first
+- `project` is the project's own content, so leave it
 
-The walk reads the toolkit's own history, so it needs a cloned toolkit. Installed from the registry it reports `historyUnavailable` and names nothing, so check for `.claude/snippets/` and a root `snippets/` by hand there, and treat what you find as `unattributed`.
+From the registry the walk reports `historyUnavailable`, so check both paths by hand.
 
 ## Stop calling the standards verb, once
 
-`canon standards` is gone. Replace each call with a skill reference from [target standards moved](standards-moved.md). <!-- canon-allow-reference: verb retired -->
+`canon standards <name>` is gone, and a call now fails with a too-many-arguments error. Replace each call with the skill that owns the standard, at `references/<name>.md`. <!-- canon-allow-reference: verb retired -->
+
+| Skill             | Standards                                                     |
+| ----------------- | ------------------------------------------------------------- |
+| `task-board`      | `board`, `tasks`, `tasks-decline`                             |
+| `context-fold`    | `context`                                                     |
+| `canvas-board`    | `canvas`, `design`                                            |
+| `docs-sync`       | `docs`, `readme`                                              |
+| `draft-figure`    | `figures`, `mermaid`                                          |
+| `create-rule`     | `rule`                                                        |
+| `create-skill`    | `skill`, `skill-paths`, `skill-practice`, `skill-requirement` |
+| `git-branch`      | `branch`, `slug`                                              |
+| `git-commit`      | `commit`, `versioning`                                        |
+| `git-pr`          | `pr`, `publish`                                               |
+| `markdown-craft`  | `markdown`                                                    |
+| `teach-workspace` | `glossary`, `teach`                                           |
+| `plan-groundwork` | `groundwork`, `groundwork-spikes`                             |
+| `plan-intake`     | `intake`                                                      |
+| `plan-feature`    | `plan`, `plan-lifecycle`                                      |
+| `draft-ready`     | `ready`                                                       |
+| `draft-doc`       | `requirements`, `wiki`                                        |
+| `session-map`     | `session`                                                     |
+
+The `standard` name became `skill-reference.md` in `create-skill`.
 
 ## Keep or delete the wireframes folder, your call
 
-The toolkit retired the wireframes record. Its standard, its generated rule, its seeded folder, and the `@canon/wireframes/index.md` import in the seed `CLAUDE.md` no longer ship, and no skill reads or writes `canon/wireframes/` any more. The canvas holds visual direction instead.
-
-A project scaffolded earlier keeps what it already holds, and nothing deletes it:
+The wireframes record is retired, and nothing deletes what a project holds.
 
-- `canon/wireframes/` stays yours, unaudited and unreferenced by any skill. Keep it as plain notes or delete it.
-- The `@canon/wireframes/index.md` line in your `CLAUDE.md` stays until you remove it, since `canon claude sync` reports the seed `CLAUDE.md` rather than rewriting a file you own. Delete the line when you delete the folder, because an import of a missing file reads as a broken pointer.
-- `.claude/rules/canon/standards/wireframes.md` leaves on the next `canon gov sync`, which deletes a held copy of a rule the toolkit no longer ships.
-
-A `## States` table under `canon/wireframes/` is no longer checked against evidence folders, so `canon context audit --gate` passes without reading the folder.
+- `canon/wireframes/` stays yours and unaudited. Keep it as notes or delete it.
+- Delete the `@canon/wireframes/index.md` line in your `CLAUDE.md` with the folder. `canon claude sync` does not rewrite it.
+- `canon gov sync` removes `.claude/rules/canon/standards/wireframes.md`
 
 ## Move decisions out of a held architecture record, once
 
-The toolkit stopped seeding a `canon/ARCHITECTURE.md`, stopped gating its caps, and retired the `architecture` standard and the rule generated from it. A project scaffolded earlier may hold the file and import it from `CLAUDE.md`. Both stay, since the record is project prose now and nothing syncs or deletes it. `canon gov sync` removes the generated rule, and `canon context audit` no longer reports the record or its caps.
-
-Decide what to do with the file yourself, since where a decision belongs takes judgment no sync has. A decision about how one domain is built is recorded by the pull request that made it, and a context entry carries no decisions. Move a trap a session would hit into that domain's `## Gotchas`. Once the file is empty, delete it and its `@canon/ARCHITECTURE.md` line in `CLAUDE.md`.
+The toolkit no longer seeds `canon/ARCHITECTURE.md`, and a held file and its `CLAUDE.md` import stay. Move a trap a session would hit into that domain's `## Gotchas`, then delete the file and its `@canon/ARCHITECTURE.md` line.

package/docs/target/projects.md

@@ -6,24 +6,18 @@ category: Agent surface
 
 # Target projects
 
-How a project outside this repo consumes the toolkit across its lifecycle. Three phases: scaffold once, add a domain later when a new need appears, and sync when the upstream toolkit moves.
-
-This doc stays at the narrative layer. For command flags and JSON shapes, see [agents](../agents/index.md). For per-domain mechanics, see each `canon/context/<domain>.md`.
+A project outside this repo scaffolds once, adds a domain later, and syncs when the upstream moves. For flags and JSON shapes see [agents](../agents/index.md).
 
 ## Getting the skills
 
-The skills reach a session through a marketplace install, once per machine. Every session on that machine carries them afterward, and the installed copy stays at the version it was installed at. Claude Code ships auto-update off for third-party marketplaces, so neither a push nor a release reaches that copy until someone refreshes it with `claude plugin marketplace update canon` followed by `claude plugin update canon@canon`, or turns auto-update on once under `/plugin`. The `canon` CLI moves on its own schedule through the registry, so a machine can hold current skills against a stale CLI or the reverse.
+Install the plugin once per machine. The installed copy stays at its version until you refresh it with `claude plugin marketplace update canon` and `claude plugin update canon@canon`, or turn on auto-update under `/plugin`. The URL form clones over HTTPS, and the `erclx/canon` shorthand resolves to SSH.
 
 ```bash
 claude plugin marketplace add https://github.com/erclx/canon
 claude plugin install canon@canon
 ```
 
-The URL form clones over HTTPS. The `erclx/canon` shorthand resolves to SSH and fails on a machine with no key configured.
-
-A machine that installed the plugin under its previous name re-registers by hand, once. The marketplace and the plugin both moved, so the old `enabledPlugins` entry and the old marketplace key name things that no longer resolve, and the plugin stops loading without reporting anything. `canon migrate rename` does not reach this: it takes a `--root` and rewrites inside one project, where the plugin registration is machine-level state outside every project.
-
-Both stale keys come out explicitly, since installing under the new name writes a new entry and leaves the old one sitting there. Uninstall before removing the marketplace, so the plugin is cleared while the marketplace it came from still resolves.
+A machine that installed the plugin under its previous name re-registers once, uninstalling before removing the marketplace.
 
 ```bash
 claude plugin uninstall aitk@aitk
@@ -32,107 +26,71 @@ claude plugin marketplace add https://github.com/erclx/canon
 claude plugin install canon@canon
 ```
 
-The `canon` CLI is separate. Twenty skills invoke it in a command position, and a marketplace install does not put it on `PATH`, so it installs from the registry as its own step.
+Skills invoke the `canon` CLI, which the marketplace install does not put on `PATH`.
 
 ```bash
 bun install --global @erclx/canon
 ```
 
-The package ships the catalogs the CLI reads, not only `src/`, so `canon init` resolves governance, tooling, and the seeds from wherever the package landed.
-
-Pointing Claude Code at a checkout stays the development path, where a local skill edit overrides the installed copy for that session.
-
-```bash
-claude --plugin-dir <toolkit>/claude
-```
+To develop against a checkout, run `claude --plugin-dir <toolkit>/claude`.
 
 ## Scaffold
 
-Two steps, in order:
-
-1. Run the framework's own scaffold if the project needs one, such as `bun init`, `npm create vite`, or `npm create astro`. The toolkit does not wrap framework scaffolding.
-2. Invoke `canon:target-setup` in Claude Code. The skill detects the stack, asks `canon gov detect` which opt-in rules the project's evidence proposes, previews the full chain with those proposals for you to confirm, and runs it end-to-end.
-
-The chain is:
+1. Run the framework's own scaffold if the project needs one, such as `bun init` or `npm create vite`
+2. Invoke `canon:target-setup` in Claude Code. It detects the stack, previews the chain with the opt-in rules `canon gov detect` proposes, and runs it on your confirmation.
 
-- `canon init` installs base tooling, Claude seeds, and governance rules into `.claude/rules/` in the same pass
-- `canon tooling sync <stack> --write` adds stack-specific deps, scripts, and gitignore entries
-- The agent reads `canon tooling reference <stack>` (plus parents) as its audit context, follows it to generate oxlint, vitest, playwright configs and the stack's setup script, and extends `canon/context/ci.md` and `canon/context/development.md` per the reference's extend sections <!-- audit-ignore-citations: canon/context/ci.md, canon/context/development.md -->
-- The `verify` phase runs the installed `package.json` scripts (lint, typecheck, check, test, build) and reports pass or fail
-- The `indexes` phase bootstraps the `index.md` system over the project's own documentation folders, confirming candidate folders with the operator rather than running unattended
+The chain runs these phases:
 
-The chain stops at the project edge. `git-commit` also ships, reaching the project's history, and does not run as part of it. The chain serves a fresh scaffold and names a destination for the three states it does not. An existing project goes to `canon:target-check`, which reports what the project already carries against what the toolkit ships before anything is repaired. An install wanting the Claude layer without the tooling chain runs `canon claude init` for the seed docs and then `canon:target-setup indexes` for the index system. A language the toolkit ships no stack for is the one of the three the chain still runs for, on `base`, with the fallback marked in the preview so it can be declined there.
+- `canon init` installs base tooling, Claude seeds, and governance rules into `.claude/rules/`
+- `canon tooling sync <stack> --write` adds stack dependencies, scripts, and gitignore entries
+- The agent follows `canon tooling reference <stack>` and extends `canon/context/development/ci.md` and `canon/context/development/local-loop.md` <!-- audit-ignore-citations -->
+- The `verify` phase runs the installed `package.json` scripts and reports pass or fail
+- The `indexes` phase bootstraps `index.md` over the project's documentation folders, confirming candidates with you
 
-Run `canon:target-setup verify deep` by hand once the default depth passes, for the heavier server smoke, end-to-end, and screenshot pass, since the same flakiness reasons that keep those stages out of the default depth keep them out of this unattended chain too.
+An existing project goes to `canon:target-check` first. For the Claude layer alone, run `canon claude init` and then `canon:target-setup indexes`. Run `canon:target-setup verify deep` by hand for the heavier smoke and screenshot pass.
 
-Keep the `## Scripts` table in `canon/context/development.md` current as scripts are added. Base tooling seeds that entry with the commands it installs, and each stack reference extends the table. A session reads it to start the app or run a check on request, so a command missing from the table cannot be found that way. A project whose entry outgrew one file and split into `canon/context/development/` keeps the table in `overview.md`, which is where the skill looks next. <!-- audit-ignore-citations: canon/context/development.md -->
+Keep the `## Scripts` table in `canon/context/development/local-loop.md` current as scripts are added. A split entry keeps it in `overview.md`. <!-- audit-ignore-citations: canon/context/development/local-loop.md -->
 
 ### From scaffold to first feature
 
-Scaffold installs tooling and seeds. It does not fill the planning docs or the design system. Complete those before the first feature session:
-
-1. Fill `canon/REQUIREMENTS.md`. The seed asks for the problem in one line, then goals and non-goals, and the scope is yours to write. The seed states its own cap of 600 words, and `canon context audit` gates on it. Edit the number in the record to loosen it. A decision about how the project is built lives in the pull request that made it, and a `canon/context/` entry carries the domain's folders and traps.
-2. For a UI project, write `canon/DESIGN.md` from the seed template and name the project's stylesheet in its lead, or work the direction out with `canon:canvas-board` and carry the pick in. Skip for non-UI projects.
-3. Optionally invoke `canon:draft-figure` naming an architecture view, such as system context or components, and the document it belongs in. It draws the view from the context index, the folder layout, and the requirements and renders it to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
-4. Start the feature loop. See [AI workflow](../workflow/ai-workflow.md) for the per-feature sequence.
-
-A machine without a renderer still gets the figure and is told which check was skipped.
+Before the first feature session:
 
-Nothing watches a figure once it is drawn. Run `canon:draft-figure` again when the code a view is drawn from moves.
+1. Fill `canon/REQUIREMENTS.md` with the problem, goals, and non-goals. The seed's 600-word cap gates under `canon context audit`.
+2. For a UI project, write `canon/DESIGN.md` from the seed and name the stylesheet in its lead, or work the direction out with `canon:canvas-board`
+3. Optionally invoke `canon:draft-figure` for an architecture view. The Mermaid CLI downloads on first use.
+4. Start the feature loop in [AI workflow](../workflow/ai-workflow.md)
 
 ### Stack decision
 
-The default path is `base`. `canon init` on `base` installs base tooling configs, Claude seeds, and the ten `base` governance rules, and scaffolds an empty `.claude/wiki/`. Most projects need nothing more.
+The default is `base`. Escalate only for a project writing code, and `target-setup` picks the tooling stack from the manifest and framework configs, and the governance stack for the root's language. Run `canon tooling list --json` and `canon gov list --json` for the catalogs.
 
-Escalate for a project writing code. The `target-setup` skill reads `package.json` and the framework configs, then picks the matching tooling stack (`canon tooling list --json` names the current set) and the governance stack for the root's language (`node`, `python`, `go`, `php`). Framework rules arrive as extras `canon gov detect` proposes from the manifest, so a Next.js app lands on `node` with the App Router rule proposed, and a Vite React app gets no such proposal.
-
-In a monorepo the skill reads each folder holding a `package.json`, `pyproject.toml`, `go.mod`, `composer.json`, or `Cargo.toml` to depth two, skipping what git ignores. Each of those folders gets its own tooling stack and a `canon tooling sync <stack> <folder> --skip base` in the preview. Governance still installs once at the root, since a rule's `paths:` globs reach every subfolder, so a subfolder's language rules join the root install through `--add`.
-
-The server-side security and persistence rules belong to no stack. `canon gov detect` proposes both from a server framework or database client in the manifest, which you confirm in the preview, or add them by hand with `--add security-server,database`.
-
-Markdown-heavy projects, CLI tools, docs sites, research notebooks, and scripting repos stay on `base`. Escalation is a ceiling move, not a default.
-
-A project the toolkit ships no stack for lands on `base` the same way, and the skill marks that resolution as a fallback in its preview rather than reporting it as a match. Configs, seeds, and gitignore entries land either way, and the JavaScript development dependencies, scripts, and hook activation land only where a `package.json` exists to carry them. A project outside that ecosystem declines at the preview and takes `canon:target-setup gov` for the governance layer alone, which is language-neutral. Go and PHP ship a governance stack beside their tooling stack, so a project in either takes `go` or `php` for both.
-
-Run `canon tooling list --json` and `canon gov list --json` to see the current catalogs. Never hardcode stack names.
+- In a monorepo each manifest folder gets `canon tooling sync <stack> <folder> --skip base`. Governance installs once at the root, with subfolder languages through `--add`.
+- Server security and persistence rules come from `canon gov detect`, or `--add security-server,database`
+- A language with no stack lands on `base`, marked as a fallback in the preview. Decline it and run `canon:target-setup gov` for governance alone.
 
 ### Core domains and skips
 
-`canon init` installs base tooling, Claude workflow, and governance, and scaffolds `.claude/wiki/`. Governance defaults to the `base` stack, so a bare init carries the rules that route a project. Pass `--stack <name>` to install a language stack instead.
-
-No reference corpus is written into the project. Each governance rule carries its operative lines inline and names the plugin skill that owns the rest, and every toolkit skill reads the references in its own plugin root. A target that installs governance without the plugin gets the inline lines alone, since no verb answers for a skill's reference there. `canon markdown audit` needs no reference at all, its ban set and checkpoints shipping with the package as data.
+`canon init` installs base tooling, the Claude workflow, and governance, and scaffolds `.claude/wiki/`. Pass `--stack <name>` for a language stack.
 
-`governance` and `wiki` are skippable:
-
-- `--skip governance`: leave `.claude/rules/` empty, so no coding standard loads on a file match. The preview names any `--add` rules the skip drops, and the run prints the `canon gov install <stack> <path>` command to add rules afterward, carrying those extras so one paste restores what the skip declined.
-- `--skip wiki`: skip the `.claude/wiki/` scaffold. A target that already carries a root `wiki/` keeps it, since the verb reports that folder rather than migrating it.
-
-The plugin corpus carries runtime behavior rather than reference prose alone, because the pre-publish scan and the branch-slug transform each have a standard of their own, `publish.md` and `slug.md`, cited by the skills that run them.
+- `--skip governance` leaves `.claude/rules/` empty. The run prints the `canon gov install <stack> <path>` command that restores the rules it dropped.
+- `--skip wiki` skips the `.claude/wiki/` scaffold. A root `wiki/` is kept.
 
 ## Add a domain later
 
-When a new need appears after scaffold, install the one domain without re-running `canon init`.
-
-- Governance rule for a newly adopted library: run `canon gov detect <path> --json` to see what the project's evidence proposes, then `canon gov install --add <rule> <path>`, which installs the rule with no stack
-- Project-specific rule the toolkit does not ship: invoke `canon:create-rule`. It scaffolds a rule into `.claude/rules/project/` with a non-colliding number, and `canon gov sync` leaves it untouched. A rule placed under `.claude/rules/canon/` instead is deleted on the next sync, since that folder belongs to the toolkit.
-- Index.md system for a markdown-heavy folder that emerged: invoke `canon:target-setup indexes`
+Install one domain without re-running `canon init`.
 
-Skill references are not on that list, and there is nothing to add for them. They install into no project, by default or by flag, and a session reads one from the plugin that loaded the skill rather than from a project copy. A project holding a `standards` folder under `.claude/` from an older toolkit is carrying a stale artifact nothing reads, and deleting it is safe. The toolkit retired snippets entirely, and [target migrations](migrations.md) covers the `.claude/snippets/` folder an older one left behind.
+- A rule for a newly adopted library: run `canon gov detect <path> --json`, then `canon gov install --add <rule> <path>`
+- A project-specific rule: invoke `canon:create-rule`, which writes into `.claude/rules/project/`. A rule under `.claude/rules/canon/` is deleted on the next sync.
+- An `index.md` system for a markdown-heavy folder: invoke `canon:target-setup indexes`
 
-Per-domain mechanics live in the corresponding `docs/<domain>.md`. The skill body in `claude/skills/<skill>/SKILL.md` covers detection and preview.
+For a leftover `.claude/snippets/` see [target migrations](migrations.md).
 
 ## Sync upstream drift
 
-When the toolkit updates, a target pulls changes per domain. A project scaffolded before a layout move runs the one-time moves in [target migrations](migrations.md) first. [Target sync](sync.md) then covers reading what drifted, the catch-all and targeted entry points, verifying a sync in the sandbox, and running one from an agent session.
-
-## Scenarios
-
-[Target scenarios](scenarios.md) walks a markdown-heavy project, a web application, and a monorepo with several language roots from the first session through ongoing maintenance.
+A project scaffolded before a layout move runs the one-time moves in [target migrations](migrations.md) first. [Target sync](sync.md) covers reading drift and running a sync. [Target scenarios](scenarios.md) walks three worked setups.
 
 ## Related
 
-- [agents](../agents/index.md): CLI flags, exit codes, and JSON output shapes
-- [target migrations](migrations.md), [target sync](sync.md), [target scenarios](scenarios.md): the one-time moves, the recurring sync, and worked setups
-- [AI workflow](../workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
-- [tooling](../../canon/context/tooling/index.md), [governance](../../canon/context/governance/index.md), [claude plugin](../../canon/context/claude-plugin/index.md), [indexes](../../canon/context/context-model.md), [skill references](../../canon/context/claude-plugin/skill-references/index.md): per-domain mechanics
-- [sandbox](../../canon/context/sandbox/index.md): scenario catalog for verifying domain flows
+- [AI workflow](../workflow/ai-workflow.md): the feature loop inside a managed project
+- [tooling](../../canon/context/surfaces/tooling.md), [governance](../../canon/context/surfaces/governance.md), [claude plugin](../../canon/context/surfaces/plugin.md), [indexes](../../canon/context/context-model.md): per-domain mechanics
+- [sandbox](../../canon/context/development/sandbox.md): scenario catalog for verifying domain flows