@erclx/canon 4.103.0 → 4.104.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.103.0",
+  "version": "4.104.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canon-cli/SKILL.md

@@ -17,7 +17,7 @@ Consult before running an unfamiliar `canon` verb, before a sync or install, or
 
 | Surface                                                  | Command              | Effect on existing files                                                    |
 | -------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------- |
-| Golden configs, listed in full below                     | `canon tooling sync` | Overwritten once `--write` is passed. Local edits are lost.                 |
+| Golden configs                                           | `canon tooling sync` | Overwritten once `--write` is passed. Local edits are lost.                 |
 | Dictionary seeds (`.cspell/*.txt`)                       | `canon tooling sync` | Merged and sorted. Existing terms preserved.                                |
 | Other seeds (`cspell.json`, `.lintstagedrc`, state docs) | `canon tooling sync` | Copy-once. Dropped on first install, untouched after.                       |
 | Standards                                                | none                 | Nothing installs. `canon standards <name>` reads and never writes.          |
@@ -31,86 +31,12 @@ Consult before running an unfamiliar `canon` verb, before a sync or install, or
 
 A golden config is any file a stack ships under `configs/`, and the category is wider than its name suggests. It carries the CI workflow, the git hooks, the end-to-end harness, the shell scripts under `scripts/`, and the editor settings, alongside the linters and compilers a reader expects. A stack inherits its parent's configs, so syncing `astro` also writes everything `web` and `base` hold.
 
-Run `canon tooling diff <stack> <target>` for the list resolved against a real target. It reports every path, writes nothing, and exits 1 when any differs. The list below is what the stacks hold as shipped, before any chain resolution.
-
-<!-- generated:tooling-paths -->
-
-### astro
-
-- `astro.config.mjs`
-- `eslint.config.js`
-- `playwright.config.ts`
-- `src/components/dev/scenarios.astro`
-- `tsconfig.json`
-- `vitest.config.ts`
-
-### base
-
-- `.editorconfig`
-- `.github/pull_request_template.md`
-- `.github/workflows/phase-label-gate.yml`
-- `.github/workflows/verify.yml`
-- `.husky/commit-msg`
-- `.husky/post-merge`
-- `.husky/post-rewrite`
-- `.husky/pre-commit`
-- `.husky/pre-push`
-- `.prettierrc`
-- `.shellcheckrc`
-- `.vscode/extensions.json`
-- `.vscode/settings.json`
-- `commitlint.config.js`
-- `scripts/verify.sh`
-
-### cloudflare
-
-- `.github/workflows/deploy.yml`
-
-### nextjs
-
-- `eslint.config.js`
-- `next.config.ts`
-- `playwright.config.ts`
-- `vitest.config.ts`
-
-### python
-
-- `.coveragerc`
-- `.python-version`
-- `mypy.ini`
-- `pytest.ini`
-- `ruff.toml`
-- `scripts/verify.sh`
-
-### vite-react
-
-- `playwright.config.ts`
-- `tsconfig.json`
-- `vite.config.ts`
-- `vitest.config.ts`
-
-### web
-
-- `.github/workflows/readme-screenshot.yml`
-- `.github/workflows/verify.yml`
-- `.vscode/extensions.json`
-- `.vscode/settings.json`
-- `e2e/home.spec.ts`
-- `e2e/screenshot.ts`
-- `eslint.config.js`
-- `scripts/lib/preview-server.sh`
-- `scripts/readme-screenshot.sh`
-- `scripts/screenshot.sh`
-- `scripts/verify.sh`
-- `scripts/worktree-port.sh`
-- `src/test/setup.ts`
-
-<!-- /generated:tooling-paths -->
+No list of those paths ships in this body, since a copy would go stale on a different cadence than the stacks. Run `canon tooling diff <stack> <target>` for the list resolved against a real target. It reports every path, writes nothing, and exits 1 when any differs. A binary older than that verb answers the same question through `canon tooling sync <stack> <target> --check`, which names each file it would replace.
 
 ## Rules
 
 - `canon tooling sync` writes nothing until `--write` is passed. A headless run without it reports and exits 1, so a script that forgets the flag fails rather than silently skipping the sync.
-- Run `--check` first when the project carries local edits to any path above. The report names each file it would replace, which is the warning the user needs before the write.
+- Run `--check` first when the project carries local edits to a config the stack ships. The report names each file it would replace, which is the warning the user needs before the write.
 - An interactive run still prompts. `--write` skips the prompt, and `--check` refuses to write even with a TTY.
 - Seeds are user-owned. Dictionary `.txt` files merge and sort. Other seeds are copy-once, so re-seeding a structured file means deleting it and syncing again.
 - No command writes a standard into a project. A `.claude/standards/` folder from an older toolkit is inert, and deleting it costs nothing.

package/claude/skills/canon-operator/REQUIREMENT.md

@@ -53,9 +53,9 @@ The last failure is a section no route reaches. `## Route` maps an intent or a d
 
 ## Out of scope
 
-- First-time scaffold of a fresh project: `setup-init`
+- First-time scaffold of a fresh project: `target-setup`
 - Seed and preamble drift in installed files: `seed-sync`
-- Governance rule install and index bootstrap: `setup-gov` and `setup-indexes`
+- Governance rule install and index bootstrap: `target-setup`, on its `gov` and `indexes` phases
 - What a given sync overwrites once it runs: `canon-cli`
 
 That last contract carries no row for the governance install this skill routes to, so the overwrite `Must` above reads nothing at one of its own destinations. The row belongs to the skill owning the table. This file records the silence rather than answering it, since a rule written here for a silent contract teaches a session that silence means safe.

package/claude/skills/canon-operator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: canon-operator
-description: Front door to the toolkit in a target project. Orients on the toolkit's own docs and live `canon` catalogs, then runs or routes any toolkit operation from a plain-language intent. Use when you want one entry point instead of picking a specific setup or sync skill, or when asked to "use the toolkit", "what can the toolkit do", "sync my standards", "install rules", or "help me set up this project". User-invoked only. Defers first-time scaffold to setup-init and seed drift to seed-sync.
+description: Front door to the toolkit in a target project. Orients on the toolkit's own docs and live `canon` catalogs, then runs or routes any toolkit operation from a plain-language intent. Use when you want one entry point instead of picking a specific setup or sync skill, or when asked to "use the toolkit", "what can the toolkit do", "sync my standards", "install rules", or "help me set up this project". User-invoked only. Defers first-time scaffold to setup and seed drift to seed-sync.
 disable-model-invocation: true
 ---
 
@@ -47,9 +47,9 @@ The two can name different rows, and a reply answers both rather than picking on
 - Anything in `superseded`: name which files and what replaced them, then hand off to `migration-superseded`. Both skills propose, so neither moves nor deletes the file
 - A folder in `unclaimed`: name it and the attribution it carries. No command moves it and the content may be the project's own, so the decision is the user's
 
-- First-time scaffold of a fresh project: hand off to `setup-init`
-- Governance rules for the project stack: hand off to `setup-gov`
-- Bootstrap the `index.md` system: hand off to `setup-indexes`
+- First-time scaffold of a fresh project: hand off to `target-setup`
+- Governance rules for the project stack: hand off to `target-setup`, which installs them alone on its `gov` phase
+- Bootstrap the `index.md` system: hand off to `target-setup`, which bootstraps it on its `indexes` phase
 - Seed or standards drift in `CLAUDE.md` or `.claude/` preambles: hand off to `seed-sync`
 - Install one snippet, standard, or rule: run the domain `install` command
 - Sync one domain or every installed domain: run `canon <domain> sync` or `canon sync`
@@ -104,5 +104,5 @@ The comparison needs the earlier report. When `## Diagnose` was skipped because
 ## Boundaries
 
 - Run `canon`. Never reimplement its install or sync logic, and never edit managed files like rules, configs, or seeds by hand.
-- Hand off the deep flows. Do not duplicate `setup-init` detection or `seed-sync` part-diffing inline.
+- Hand off the deep flows. Do not duplicate `target-setup` detection or `seed-sync` part-diffing inline.
 - Resolve names from catalogs at runtime. A hardcoded name is a bug.

package/claude/skills/design-taste/references/craft.md

@@ -39,7 +39,7 @@ Reaching for size is the first instinct and the weakest tool.
 - **Measure.** Body text running the full width of a wide container is unreadable however good the type is.
 - **Figures in columns.** Numbers that change, in a table, a price or a timer, need tabular figures or the column jitters.
 - **Tracking by size.** Large type wants tighter letter spacing, small uppercase labels want looser. Body text wants whatever the face was drawn with.
-- **Casing.** Sentence case for headings and labels. Title case on every heading reads as a template.
+- **Casing.** Sentence case for headings and labels. `465-interface-casing` states the rule and its exceptions.
 
 ## Depth and texture
 

package/claude/skills/design-taste/references/preflight.md

@@ -28,7 +28,7 @@ Skip nothing on the ground that it is obviously fine. A rule is on this list bec
 
 - [ ] No layout family used twice. Eight sections carry at least four families
 - [ ] No three consecutive sections sharing the image-and-text split
-- [ ] Small uppercase labels above headings number no more than one per three sections
+- [ ] Small uppercase labels above headings number no more than one per three sections, per `465-interface-casing`
 - [ ] At most one horizontal marquee
 - [ ] Grid cells equal content items, with no blank tile filling a gap
 - [ ] Lists over five items use something other than a longer list
@@ -62,7 +62,7 @@ Skip this group where the surface draws on a system already settled.
 - [ ] Every number either real, labeled as sample, or removed
 - [ ] No placeholder that reads as placeholder: generic names, generic company names, reused portraits, identical dates
 - [ ] No filler verbs
-- [ ] Sentence case throughout
+- [ ] Sentence case throughout, with exceptions per `465-interface-casing`
 - [ ] Every claim about what the product does is a thing it does
 
 ## Motion

package/claude/skills/design-taste/references/tells.md

@@ -61,7 +61,7 @@ These are the rules with numbers, so they are checked by counting rather than by
 
 - **A layout family appears once.** Once a section uses a shape, no other section on the surface uses it. Eight sections need at least four distinct families.
 - **Two consecutive splits, never three.** Alternating image-left and image-right reads as considered twice and as filler by the third. Break it with a full-width section, a vertical stack, a grid, or anything else.
-- **One small uppercase label per three sections.** The tiny wide-tracked line above a heading is the single most over-reached default in model output. Count them: more than `ceil(sections / 3)` is too many, and the first screen counts as one. The fix is usually to delete it, since a section's position already says what it is.
+- **One small uppercase label per three sections.** The tiny wide-tracked line above a heading is the single most over-reached default in model output. `465-interface-casing` carries the count. The fix is usually to delete it, since a section's position already says what it is.
 - **One marquee.** Two sliding strips on one surface read as filler rather than as a device.
 - **Cells equal items.** A grid with a hole in it, or a blank tile at the end, means the grid was shaped before the content was counted. Reshape it.
 - **Over five items wants a different component.** A longer list is the lazy answer. Group into clusters, split into columns, give each item a card, make them scrollable, or collapse the tail behind a disclosure.

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

@@ -31,7 +31,7 @@ A missing tracking ref is no longer a guard. An open pull request proves the bra
 
 5. Post the evidence comparison, on every invocation including `reply-owned`, since this comment is not the reply step 8 owns. Run `canon pr evidence <number> --json`, resolving `<number>` from `gh pr view --json number`, and read `reason` on the record rather than the exit code.
    - `no-evidence`: nothing changed under an `evidence/` segment this push. Say nothing and move on.
-   - `ok`: write `body` to `.canon/tmp/pr/evidence/body-<number>.md` at the main worktree root (resolved the way `session-worktree` does), then post the comment with `gh pr comment <number> --body-file <main-root>/.canon/tmp/pr/evidence/body-<number>.md` when the record carries no `commentId`, or edit the existing one in place with `gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -f body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md` when it does. Clean up the tmp file only after the call reports success.
+   - `ok`: write `body` to `.canon/tmp/pr/evidence/body-<number>.md` at the main worktree root (resolved the way `session-worktree` does), then post the comment with `gh pr comment <number> --body-file <main-root>/.canon/tmp/pr/evidence/body-<number>.md` when the record carries no `commentId`, or edit the existing one in place with `gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -F body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md` when it does. Clean up the tmp file only after the call reports success.
    - Any other reason is one of the mirrored git refusals (`gh-missing`, `gh-failed`, `no-base`, `unreadable-tree`, `unreadable-changes`). Report it and continue without stopping the chain.
 6. Check for existing review comments: `gh api 'repos/{owner}/{repo}/pulls/<number>/comments' --jq 'length'`, resolving `<number>` from `gh pr view --json number`.
 7. Sync the body and title on every invocation, before the routing below decides on the reply.

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

@@ -11,7 +11,7 @@ Format an issue from session context following the issue standard, then file it
 
 Read these in parallel:
 
-- `${CLAUDE_SKILL_DIR}/../../standards/issue.md`: issue title, labels, body sections, and banned phrases
+- `${CLAUDE_SKILL_DIR}/references/issue.md`: issue title, labels, body sections, and banned phrases
 - `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for all generated text
 - The `write-human` skill: voice, rhythm, and sentence construction for all generated text
 
@@ -39,7 +39,7 @@ After outputting the preview, execute the final command immediately. Claude Code
 
 ### Pre-publish scan
 
-Before running the final command, run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against the title and body. The title and body go straight to the remote with nothing checking them on the way, so this scan is the only gate. It covers the phase-label check as well as the characters, since both go to a reader who has no task board. It applies on top of the banned phrases in `${CLAUDE_SKILL_DIR}/../../standards/issue.md`.
+Before running the final command, run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against the title and body. The title and body go straight to the remote with nothing checking them on the way, so this scan is the only gate. It covers the phase-label check as well as the characters, since both go to a reader who has no task board. It applies on top of the banned phrases in `${CLAUDE_SKILL_DIR}/references/issue.md`.
 
 The `pull_request` check the git-pr surface carries reads a pull request's own title and body alone, so an issue reaches no check behind this scan either.
 

package/{standards → claude/skills/git-issue/references}/issue.md

@@ -1,8 +1,3 @@
----
-title: Issue reference
-description: GitHub issue title, labels, and body conventions
----
-
 # Issue reference
 
 ## Scope
@@ -11,10 +6,10 @@ Governs a tracker issue: its title, its labels, and the sections its body carrie
 
 Does not govern:
 
-- Pull request title and body: `pr.md`
-- Whether a phase label may appear in issue text: `versioning.md`
+- Pull request title and body: the pull request standard
+- Whether a phase label may appear in issue text: the versioning standard
 - Voice, rhythm, and sentence construction in issue prose: the `write-human` skill
-- Punctuation, formatting, and banned words in issue prose: `markdown.md`
+- Punctuation, formatting, and banned words in issue prose: the markdown standard
 
 ## Title
 

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

@@ -181,10 +181,10 @@ Read `reason` on the record rather than the exit code.
 gh pr comment <number> --body-file <main-root>/.canon/tmp/pr/evidence/body-<number>.md
 ```
 
-When the record carries a `commentId`, edit that comment in place instead of posting a second one, reading the body field from the tmp file with `@`:
+When the record carries a `commentId`, edit that comment in place instead of posting a second one, reading the body field from the tmp file with `@`, which needs the typed-field flag `-F` because the raw-string flag `-f` posts the path itself as the body:
 
 ```bash
-gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -f body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md
+gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -F body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md
 ```
 
 Delete the handoff file once that call reports success, per the cleanup below, since the checklist now lives on the pull request. Clean up the tmp body file the same way.

package/claude/skills/index-lookup/REQUIREMENT.md

@@ -30,6 +30,6 @@ Without this skill, `canon indexes list --json` exists as a verb with nobody wra
 
 ## Out of scope
 
-- Regenerating or scaffolding an index, which `canon indexes regen` and the `setup-indexes` skill own
+- Regenerating or scaffolding an index, which `canon indexes regen` and the `target-setup` skill's `indexes` phase own
 - Reading a folder's contents once a hit names it, which is an ordinary file read rather than part of the lookup
-- Chaining this skill into `setup-indexes`'s bootstrap flow as a verification step. Left independent: `setup-indexes` already validates through `canon indexes regen --dry-run`, and a second skill call inside a bootstrap flow duplicates a check that already runs.
+- Chaining this skill into the `target-setup` skill's `indexes` phase as a verification step. Left independent: that phase already validates through `canon indexes regen --dry-run`, and a second skill call inside a bootstrap flow duplicates a check that already runs.

package/claude/skills/project-commands/REQUIREMENT.md

@@ -38,5 +38,5 @@ Two more failures are mechanical. A command that stays up run in the foreground
 
 - Confirming a change works in the running app, which is a verification request and needs the steps this skill refuses
 - Deploying, publishing, releasing, migrating, and resetting
-- Running the scaffold verification chain against `package.json` scripts: `setup-verify`
+- Running the scaffold verification chain against `package.json` scripts: the `target-setup` skill's `verify` phase
 - Writing the entry it reads, which belongs to the project's own development docs

package/claude/skills/seed-sync/REQUIREMENT.md

@@ -41,5 +41,5 @@ Two failures belong to the audit rather than to the diff. A decision taken in ch
 - Bulk install and sync of a whole domain, which `canon <domain> install` and `canon <domain> sync` own and `canon-cli` documents. Reach for this skill when the target holds edits worth keeping, and for those commands when it does not.
 - Golden configs, which overwrite by design and carry no section structure to diff
 - Governance rules: `canon gov sync`
-- First-time scaffold of a project that has installed nothing yet: `setup-init`
+- First-time scaffold of a project that has installed nothing yet: `target-setup`
 - Public `README.md` and `docs/` prose: `docs-sync`

package/claude/skills/target-check/REQUIREMENT.md

@@ -39,4 +39,4 @@ The second half of the gap is silence. A session that runs a verb the target's b
 - Document health, which asks a content question rather than a structural one and takes its own surface
 - Repairing anything a section names. Each routes to the command or skill that owns it.
 - A target's own routes, which `canon inventory` reports as a listing rather than a verdict and which is a fact about the project rather than about what the toolkit ships
-- First-time scaffold, which is `setup-init`, and per-intent routing of a single toolkit operation, which is `canon-operator`
+- First-time scaffold, which is `target-setup`, and per-intent routing of a single toolkit operation, which is `canon-operator`

package/claude/skills/target-setup/REQUIREMENT.md

@@ -0,0 +1,56 @@
+---
+name: target-setup
+description: Why getting a project onto the toolkit is one skill with phases rather than a family a session has to pick among
+---
+
+# Setup requirement
+
+## Gap
+
+Without this skill, a session facing a project that does not carry the toolkit
+resolves the stack by hand, picks per-domain install commands from the CLI
+surface, and runs them in an order nothing states. The install logic lives in
+`canon init`, so what is missing is not the writing but the reading: which stack
+matches this project, which extras it needs beyond the stack, and what the
+commands will do before they run.
+
+The naive shape is one skill per phase, and it failed on discrimination rather
+than on content. Six descriptions covering one job made the model pick among
+them on wording, and the two that split on how heavy their checks are gave a
+session no way to tell from the catalog which one a scaffold wanted. A phase
+argument answers the same question by naming the depth rather than by choosing
+between two bodies that differ in a table.
+
+Merging also closes a class of drift the family carried. Detection was stated
+twice, once for the full chain and once for the governance-only route, and the
+two copies could disagree with nothing comparing them.
+
+## Must
+
+- Read the toolkit catalogs before resolving, and hardcode no stack, rule, or snippet name
+- Preview the resolved arguments and the exact commands before the first write
+- Mark a fallback resolution as a fallback in the preview, where it can still be declined
+- Run every phase without a TTY, and carry an argument for each prompt a phase would otherwise open
+- Reach each phase alone, so a caller wanting one layer does not run the chain to get it
+- Name a destination for each state the chain declines rather than ending on the refusal
+
+## Must not
+
+- Guard against clobbering an existing project's configs, which routes to `canon-operator` instead
+- Author a rule or a stack in the target project on the fly
+- Generate a config the tooling stack ships as a golden file
+- Install Claude Code plugins, which provision a machine rather than a project
+- Fail an unattended scaffold on a server start, which is flaky enough to be a depth the operator asks for
+- Survive as a skill nothing invokes but a person typing its name. `canon-operator` hands first-time scaffold here and the target-projects page names it as the scaffold step, so a later read finding no caller but the author has found a body that should have stayed a verb
+
+## Guards
+
+- No `package.json` at the project root stops the verify phase, since there are no declared scripts to read
+- A missing dependency folder installs first rather than letting every script fail on the same cause
+- A detected technology with no matching rule surfaces rather than resolving to a guess
+
+## Out of scope
+
+- An existing project's per-domain drift, which `canon-operator` diagnoses and `target-check` reports
+- Reaching a remote or the project's history, which `repo-metadata` and `git-commit` own
+- Provisioning Claude Code plugins on a machine, which the `claude plugin` CLI does directly

package/claude/skills/target-setup/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: target-setup
+description: Gets a project onto the toolkit. Detects the stack, resolves per-domain arguments, previews the chain, runs `canon init`, then verifies at a stated depth and bootstraps the `index.md` system. Use when asked to "set up this project", "init this project", "bootstrap the toolkit", "install governance", "install gov rules", "set up indexes", "verify the scaffold", "run the smoke tests", or "one-shot install". Assumes the `canon` CLI is on PATH. Do NOT use on a project that already carries the toolkit, which is `canon-operator`, or to report per-domain drift without repairing it, which is `target-check`.
+---
+
+# Setup
+
+Gets a project onto the toolkit. Detects project type, resolves per-domain
+arguments, previews the chain, runs `canon init`, then verifies what landed and
+bootstraps the `index.md` system over the project's own documentation folders.
+
+The CLI holds the install logic. This skill resolves, previews, and routes. It
+reimplements no verb and hardcodes no stack, rule, or snippet name.
+
+## Phases
+
+Five phases run in order on a bare invocation. Each is also reachable alone, so
+a caller wanting one layer does not run the chain to get it.
+
+| Phase     | What it does                                                | Reached alone by      |
+| --------- | ----------------------------------------------------------- | --------------------- |
+| `detect`  | Reads the project and resolves stack arguments              | `setup detect`        |
+| `install` | Runs `canon init` and the tooling sync                      | `setup install`       |
+| `gov`     | Installs governance rules and nothing else                  | `setup gov`           |
+| `verify`  | Runs the installed scripts at a stated depth                | `setup verify [deep]` |
+| `indexes` | Bootstraps the `index.md` system over documentation folders | `setup indexes`       |
+
+An argument naming a phase runs that phase and stops. A bare invocation runs
+`detect`, `install`, `verify`, then `indexes`. `gov` is a narrowing of `install`
+rather than a step within it, so the full chain never runs it separately.
+
+## Non-interactive path
+
+Every phase runs under `CANON_NON_INTERACTIVE=1` with no TTY. Two phases
+otherwise pause, and each takes an argument that answers its prompt ahead of
+time:
+
+- `indexes` confirms its folder list with the operator. `setup indexes --all`
+  takes every candidate the scan found, and `--folders <a>,<b>` takes a named
+  set. With neither, and with no TTY, the phase reports its candidates and stops
+  rather than choosing for the operator.
+- `gov` stops on a detected technology with no matching rule. `--skip-gaps`
+  proceeds with the matched layer and lists the gap in the report.
+
+Claude Code's tool permission dialog is the confirmation gate for everything
+else. Do not pause for a separate confirmation.
+
+## Scope
+
+- This skill and `canon init` run once on a fresh scaffold, never on an existing project. They do not guard against clobbering existing configs. When tempted to add guards, mode switches, or an existing-project branch, stop. Extend the per-domain `canon <domain> install` or `canon sync` paths instead.
+- The chain stops at the project edge. `repo-metadata` and `git-commit` also ship, reaching a remote and the project's history respectively, and neither runs here.
+- Claude Code plugins are a machine concern rather than a project one, so no phase here installs them. Install them with `claude plugin install <name> --scope user`, which applies in every project on the machine and is copied into none.
+
+## Declined states
+
+Three states reach this skill that the chain does not serve. Name the destination for each, so the refusal routes rather than ends. The first two stop the chain outright and the third runs it on a default the person may not want.
+
+- **An existing project.** Stop and hand off to `canon-operator`. It reads what the target already carries before it names a command, which this chain never does, so any per-domain install picked here is a guess against configs nobody read. The Scope bullet above names the same commands as the authoring alternative, and this is the destination a person takes.
+- **An install wanting the `.claude/` folder alone.** Stop. Run `canon claude init` for the seed docs, then run the `indexes` phase over the project's own documentation folders. Neither needs the tooling sync the `install` phase runs.
+- **A language the toolkit carries no stack for.** The chain still runs, on `base`, with the fallback marked in the preview. A project that wants none of what `base` carries declines there and takes the `gov` phase, which is language-neutral and installs rules without the `base` development dependencies the tooling layer would drop on it. Say so at the preview rather than resolving it here, since the fallback is a working default and only the person can say whether it fits.
+
+Do not add a stack, a mode switch, or an existing-project branch to satisfy one of these. Each destination already exists and routing to it costs a line.
+
+## Phase: detect
+
+Read `${CLAUDE_SKILL_DIR}/references/detect.md`. It holds the catalog reads, the
+evidence list, the argument resolution, the gap handling, and the preview, which
+the `install` and `gov` phases share rather than each stating.
+
+## Phase: install
+
+Run the chain in order, starting immediately after the preview. Run from the
+target project's current directory. Do not cd into the toolkit source tree. The
+`canon` CLI is global.
+
+Step 1: `canon init` installs base tooling, claude seeds, governance rules, and wiki.
+
+```bash
+CANON_NON_INTERACTIVE=1 canon init \
+  --stack <stack> \
+  --add <rules> \
+  <target>
+```
+
+Omit any flag whose resolved value is empty.
+
+Step 2: `canon tooling sync <tooling-stack> --write` installs stack deps, scripts, gitignore entries, seeds, golden configs, and drops the reference doc. The extends chain is walked, so syncing `vite-react` also pulls `web` and `base` configs. Skip if the tooling stack is `base` (already synced by `canon init`).
+
+`--write` is required. A headless run without it reports what it would replace and exits 1, since golden configs overwrite whatever the target holds at those paths. Scaffolding into a fresh target has nothing to lose, so pass it directly rather than reading a report first.
+
+```bash
+CANON_NON_INTERACTIVE=1 canon tooling sync <tooling-stack> <target> --write
+```
+
+Monorepo with multiple language roots: run `canon init` once at the repo root so `base` (husky, prettier, cspell, commitlint, CI) lands single, then sync each subtree with `--skip base` so the shared layer is not re-dropped.
+
+```bash
+CANON_NON_INTERACTIVE=1 canon tooling sync vite-react ./frontend --skip base --write
+CANON_NON_INTERACTIVE=1 canon tooling sync python ./backend --skip base --write
+```
+
+Without `--skip base`, each subtree re-drops husky, and git honors only one `core.hooksPath`, so the extra hook dirs silently break. Each subtree keeps its own framework configs, and its own stack reference reads through `canon tooling reference <stack>`.
+
+Step 3: post-sync fixups. Golden configs arrive from sync, so no config generation is required. But a few items may need a one-time touch:
+
+- **ESLint version pin.** If `bun create vite` installed `eslint@^10` and the manifest pins `eslint@^9`, sync does not override a present dep. Run `bun add -d eslint@^9` if `bun run lint:fix` fails with `Class extends value undefined`.
+- **File naming.** `bun create vite`'s `App.tsx` violates the `KEBAB_CASE` rule. Rename to `app.tsx` and update the import in `main.tsx`.
+- **Docs.** Run `canon tooling reference <tooling-stack>` and `canon tooling reference web` for any stack-specific follow-ups (Chrome extension overrides, setup script details).
+
+Do not generate ESLint, Vitest, or Playwright configs. They ship as golden files. Generating from prose duplicates what sync already installed.
+
+## Phase: gov
+
+Governance rules and nothing else, for a project declining the tooling layer.
+Resolve exactly as the detect reference states, then run:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon gov install <stack> --add <extras> <target>
+```
+
+Report the rule count installed, the target path, and any rules that failed to
+resolve, which the CLI warns on.
+
+## Phase: verify
+
+Read `${CLAUDE_SKILL_DIR}/references/verify.md`. It holds both depths and the
+script chain each runs. The default depth runs the leaf scripts and reports pass
+or fail per script. `deep` adds the dev and preview server smoke, the end-to-end
+suite, and the screenshot harness.
+
+The chain runs the default depth. `deep` is the operator's call rather than the
+chain's, since a slow server start reads as a failure and an unattended run
+should not fail a scaffold on that.
+
+## Phase: indexes
+
+Read `${CLAUDE_SKILL_DIR}/references/indexes.md`. It holds the scan, the
+frontmatter drafting, the scaffold, the validate step, and the convention seed
+offer.
+
+This phase confirms candidate folders with the operator rather than running
+unattended, which is the one phase in the chain that pauses for a conversation
+unless `--all` or `--folders` answered it ahead of time. A fresh scaffold usually
+has no markdown-heavy folder yet, so this phase frequently finds nothing to
+present, which its reference defines as its own outcome rather than a failure of
+the chain.
+
+## Report
+
+After the chain, report:
+
+- Domains installed, with a check per domain
+- Tooling stack synced, or skipped. Name the layers pulled via the extends chain.
+- Any post-sync fixups applied (ESLint pin, filename renames)
+- `verify` outcome, naming the depth it ran at
+- `indexes` outcome (folders bootstrapped, or none found)
+- Any domains or scripts that failed
+- Any detection gaps surfaced during resolve
+- Claude Code plugins as an onboarding step this chain does not cover, so a clean result does not read as onboarding complete
+
+A resolved name and a fallback read alike once written, so the preview marks the
+fallback rather than this report. The preview is the last point before the first
+write, and the report runs after the files have landed.

package/claude/skills/target-setup/references/detect.md

@@ -0,0 +1,80 @@
+---
+title: Detect and resolve
+description: The catalog reads, evidence list, argument resolution, gap handling, and preview the install and gov phases share
+---
+
+# Detect and resolve
+
+What the `install` and `gov` phases both do before they write anything. Stated
+once here rather than twice in the body, since the two phases differ in what
+they install rather than in how they read the project.
+
+## Read the catalogs
+
+Run in parallel. Never hardcode stack, rule, snippet, or standards names. The
+catalog is the source of truth.
+
+Run from the target project's current directory. Do not cd into the toolkit
+source tree. The `canon` CLI is global.
+
+```bash
+canon gov list --json 2>/dev/null
+canon tooling list --json 2>/dev/null
+```
+
+The `gov` phase needs only the first. Run both anyway on a bare invocation,
+since the chain reaches the tooling resolution a moment later.
+
+## Detect
+
+Read these from the project root in parallel, skipping any that do not exist:
+
+- `package.json`: `dependencies` and `devDependencies`
+- Root configs: `astro.config.*`, `next.config.*`, `vite.config.*`, `tailwind.config.*`, `tsconfig.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`
+- `canon/REQUIREMENTS.md` and `canon/ARCHITECTURE.md` if present
+- Directory structure via `ls -1` of the project root and `src/` if present
+
+## Resolve arguments
+
+- **Stack:** pick the closest governance stack by matching detected runtime or framework against stack names in the catalog. If nothing matches, fall back to `base` and carry the fallback into the preview.
+- **Tooling stack:** pick the closest tooling stack from `canon tooling list --json` (e.g. `vite-react`, `astro`, `nextjs`). Distinct from the governance stack. Fall back to `base` if no framework match, and carry that fallback into the preview too.
+- **Next.js:** map `next` in `package.json` dependencies, or a root `next.config.ts`/`.js`/`.mjs` file, to the `nextjs` tooling stack. The dependency name does not match the stack name by itself.
+- **Extras:** identify technologies not already covered by the picked stack. For each, find a rule whose `description` or `paths` points at that technology and pass it via `--add`. Dedupe against the stack's own rules. Do not add a rule the stack already pulls in.
+- **Skip (`--skip`):** `wiki` installs by default. Add `--skip wiki` only when the user explicitly wants it left out.
+
+## Gap handling
+
+If a detected technology has no matching rule or stack, do not guess. Surface
+the gap.
+
+On the full chain, either defer and author a rule in the toolkit before
+re-running, or proceed with the matched layer and list the gap in the final
+report. Rules and stacks are authored in the toolkit repository, never in the
+target project on the fly.
+
+On the `gov` phase, stop and present four options rather than picking:
+
+1. Author a new rule in the toolkit at `governance/rules/<domain>/<num>-<name>.md` following `${CLAUDE_SKILL_DIR}/../../standards/rule.md`, commit, then re-run install. Take this route when the toolkit should ship the rule to every project.
+2. Invoke `create-rule`, which scaffolds the file into the target project at a non-colliding number. Take this route when the rule is specific to this project and no sync should ever overwrite it.
+3. Install the matching non-`<tech>` rules and skip the tech-specific layer.
+4. Abort.
+
+`--skip-gaps` takes option 3 ahead of the prompt, which is what keeps the phase
+non-interactive. This skill authors no rule itself. Option 1 writes in the
+toolkit repository, and option 2 hands the project-local file to `create-rule`.
+
+## Preview
+
+Before executing, output:
+
+- **Detected:** each technology with its evidence file
+- **Stack:** picked governance stack and resolved rule count. Mark it `fallback` when no detected runtime or framework matched a catalog name.
+- **Tooling stack:** picked tooling stack. Mark it `fallback` on the same test, and name what `base` lands: configs, seeds, and gitignore entries in every case, plus the JavaScript development dependencies, scripts, and hook activation wherever a `package.json` exists to carry them. A project outside that ecosystem runs none of the second group and keeps the first. Omit this line entirely on the `gov` phase, which syncs no tooling.
+- **Extras:** each `--add` rule with a one-line reason
+- **Skip:** any `--skip` entries with reason
+- **Target:** resolved target path
+- **Commands:** the full chain that will run
+
+A resolved name and a fallback read alike once written, so mark the fallback
+here rather than in the report. The preview is the last point before the first
+write, and the report runs after the files have landed.