@erclx/canon 5.38.0 → 5.40.0

package/docs/agents/targets.md

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

package/docs/target/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 goes to the `canon/context/` entry of the domain it constrains, under that entry's `## Decisions`. Once the file is empty, delete it and its `@canon/ARCHITECTURE.md` line in `CLAUDE.md`.
+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 goes in the `canon/context/` entry of the domain it constrains.
-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/indexes.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