@erclx/canon 4.103.0 → 4.104.0

package/claude/skills/{setup-indexes/SKILL.md → target-setup/references/indexes.md}

@@ -1,25 +1,32 @@
 ---
-name: setup-indexes
-description: Bootstraps the toolkit's `index.md` system in a target project. Scans for markdown-heavy folders, drafts `title` and `description` frontmatter, scaffolds `index.md` per chosen folder, and runs `canon indexes regen` to validate. Use when asked to "set up indexes", "bootstrap indexes", "add index.md to this project", or "install indexes". Assumes the `canon` CLI is on PATH.
+title: Indexes bootstrap
+description: The scan, frontmatter drafting, scaffold, validate, and convention seed phases that add the index.md system to a project
 ---
 
-# Indexes install
+# Indexes bootstrap
 
-Adds the index.md system to a project that does not have it. Operates in the active Claude session: Claude reads files, drafts frontmatter, confirms with the user, and writes. The CLI handles validation and regeneration only.
+Adds the `index.md` system to a project that does not have it. Operates in the
+active Claude session: Claude reads files, drafts frontmatter, confirms with the
+user, and writes. The CLI handles validation and regeneration only.
 
-Read `canon docs indexes` from the toolkit if context on the system is needed before scanning.
+Read `canon docs indexes` from the toolkit if context on the system is needed
+before scanning.
 
 ## Scope
 
 - Bootstrap un-indexed folders only. Skip folders that already contain an `index.md`.
 - All-or-nothing per chosen folder. Every `*.md` sibling in a chosen folder gets `title` and `description` injected, or none does. Partial migration creates folders that hard-error on regen.
-- This is where `setup-init` sends an install that wants the Claude layer without the tooling chain, once `canon claude init` has seeded the docs. The work is the same either way, since the scan below prunes `.claude` and reads the project's own documentation folders whichever route reached it.
+- This phase is where an install wanting the Claude layer without the tooling chain arrives, once `canon claude init` has seeded the docs. The work is the same either way, since the scan below prunes `.claude` and reads the project's own documentation folders whichever route reached it.
 
 ## Scan
 
-Walk the project root for folders containing three or more sibling `*.md` files. Prune `.git`, `node_modules`, `.claude`, `snippets`, anything matched by `.gitignore`, and any folder that already contains an `index.md`.
+Walk the project root for folders containing three or more sibling `*.md` files.
+Prune `.git`, `node_modules`, `.claude`, `snippets`, anything matched by
+`.gitignore`, and any folder that already contains an `index.md`.
 
-Skip `.claude/snippets/`. Snippets are invoked by reference (`@snippet-name`) rather than browsed, so they need neither `index.md` nor per-file frontmatter. Adding them creates noise that targets keep reporting.
+Skip `.claude/snippets/`. Snippets are invoked by reference (`@snippet-name`)
+rather than browsed, so they need neither `index.md` nor per-file frontmatter.
+Adding them creates noise that targets keep reporting.
 
 For each candidate, capture:
 
@@ -35,7 +42,9 @@ If the scan found no candidate, report the flat result and skip ahead:
 No folder has three or more markdown siblings without an index.md already. Nothing to bootstrap.
 ```
 
-Skip past the ask below and every step between it and the seed offer, straight to `## Offer the convention seed`. There is no candidate to ask about, so this stops rather than opening a prompt with nothing in it.
+Skip past the ask below and every step between it and the seed offer, straight
+to `## Offer the convention seed`. There is no candidate to ask about, so this
+stops rather than opening a prompt with nothing in it.
 
 Output one line per candidate:
 
@@ -45,7 +54,12 @@ Output one line per candidate:
 - references/   (3 files, 0/3 with frontmatter)
 ```
 
-Ask the user which to bootstrap. Accept folder paths, `all`, or `none`. The user can also force a folder with fewer than three siblings by naming it explicitly.
+Ask the user which to bootstrap. Accept folder paths, `all`, or `none`. The user
+can also force a folder with fewer than three siblings by naming it explicitly.
+
+`--all` and `--folders <a>,<b>` answer this ask ahead of time, which is what
+keeps the phase non-interactive. With neither, and with no TTY, report the
+candidate list and stop rather than choosing on the operator's behalf.
 
 ## Draft frontmatter
 
@@ -62,9 +76,13 @@ docs/architecture.md
   description: System boundaries, data flow, and module responsibilities
 ```
 
-The user accepts, edits, or rejects per file. Offer "accept all remaining" once the user confirms two in a row to keep the loop short.
+The user accepts, edits, or rejects per file. Offer "accept all remaining" once
+the user confirms two in a row to keep the loop short.
 
-Never write drafts before the user confirms. Drafted text is a proposal, not a commit.
+Never write drafts before the user confirms. Drafted text is a proposal, not a
+commit. A run that took `--all` or `--folders` confirmed the folder set rather
+than each draft, so surface the drafts as a batch and write them without a
+second ask.
 
 ## Scaffold the folder index
 
@@ -81,9 +99,12 @@ Surface the proposed `title` and `subtitle` and let the user edit before writing
 
 ## Inject
 
-After all confirmations, write frontmatter into each sibling and `index.md` into each folder. Use a single batched write per file.
+After all confirmations, write frontmatter into each sibling and `index.md` into
+each folder. Use a single batched write per file.
 
-Preserve existing content below the frontmatter block. If a sibling already has frontmatter without `title` or `description`, merge in the missing fields. Do not touch files the user rejected.
+Preserve existing content below the frontmatter block. If a sibling already has
+frontmatter without `title` or `description`, merge in the missing fields. Do not
+touch files the user rejected.
 
 ## Validate
 
@@ -93,22 +114,28 @@ Run from the project root:
 canon indexes regen --dry-run --json
 ```
 
-Parse the JSON. On any `error` action, surface the file and reason and stop. On `would-write` for the bootstrapped folders, the dry-run is healthy. Run for real:
+Parse the JSON. On any `error` action, surface the file and reason and stop. On
+`would-write` for the bootstrapped folders, the dry-run is healthy. Run for real:
 
 ```bash
 canon indexes regen --json
 ```
 
-Count the `written` actions in that record and report the number. Read the real run the same way the dry run is read, since the exit carries nothing reliable back to a session. An operator's shell profile may wrap `canon` in a function that runs the binary and then a second command and takes the second status, so a regen that errored on a sibling missing `title` arrives here as a clean pass.
+Count the `written` actions in that record and report the number. Read the real
+run the same way the dry run is read, since the exit carries nothing reliable
+back to a session. An operator's shell profile may wrap `canon` in a function
+that runs the binary and then a second command and takes the second status, so a
+regen that errored on a sibling missing `title` arrives here as a clean pass.
 
 ## Offer the convention seed
 
-First check whether `CLAUDE.md` exists in the project root. If absent, do not scaffold one. Skip the seed install with this exact message:
+First check whether `CLAUDE.md` exists in the project root. If absent, do not
+scaffold one. Skip the seed install with this exact message:
 
 ```plaintext
 No CLAUDE.md in the project. Skipping convention seed.
 To add the convention later, run `canon tooling sync` or `canon init`,
-then re-invoke this skill.
+then re-invoke this phase.
 ```
 
 If `CLAUDE.md` exists, check it for an existing `## Indexes` section:
@@ -119,7 +146,10 @@ grep -l '^## Indexes' CLAUDE.md 2>/dev/null
 
 If the section is present, skip the seed silently.
 
-If `CLAUDE.md` exists but has no `## Indexes` section, offer to install the canonical convention block. The text below is the source of truth and is mirrored in the toolkit's `tooling/claude/seeds/CLAUDE.md`. Paste it verbatim. Do not rewrite, paraphrase, condense, or add punctuation.
+If `CLAUDE.md` exists but has no `## Indexes` section, offer to install the
+canonical convention block. The text below is the source of truth and is
+mirrored in the toolkit's seed `CLAUDE.md`. Paste it verbatim. Do not rewrite,
+paraphrase, condense, or add punctuation.
 
 ```markdown
 - When a folder has an `index.md`, check it before reading individual files in that folder.
@@ -127,11 +157,16 @@ If `CLAUDE.md` exists but has no `## Indexes` section, offer to install the cano
 - Every `index.md` carries its own frontmatter (`title`, `subtitle`) that the walker preserves. To keep a folder's `index.md` hand-edited, add `auto: false` to its frontmatter.
 ```
 
-Append a new `## Indexes` section at the end of the file containing the three lines. Do not touch any other section.
+Append a new `## Indexes` section at the end of the file containing the three
+lines. Do not touch any other section.
 
 ## Closeout
 
-Always emit this block as the final message of the skill run. Do not skip it regardless of how the seed step concluded (installed, already present, declined, or skipped because no `CLAUDE.md` exists). Output exactly one closeout, even if the seed step paused for user input. Resume the flow after the user responds and emit the closeout next.
+Always emit this block as the final message of the phase. Do not skip it
+regardless of how the seed step concluded (installed, already present, declined,
+or skipped because no `CLAUDE.md` exists). Output exactly one closeout, even if
+the seed step paused for user input. Resume the flow after the user responds and
+emit the closeout next.
 
 Format:
 
@@ -144,14 +179,15 @@ Folders bootstrapped:
 Drafts: <n> accepted, <n> edited, <n> rejected
 Convention seed: <installed | already present | declined | skipped (no CLAUDE.md)>
 
-Optional maintenance (opt in, the skill does not configure these):
+Optional maintenance (opt in, the phase does not configure these):
 - lint-staged entry in .lintstagedrc.json:
     "**/*.md": "canon indexes regen"
 - Claude Code PostToolUse hook on Edit and Write matching **/*.md running:
     canon indexes regen
 ```
 
-Replace bracketed values with the values from this run. Drop the "Folders bootstrapped" line if zero folders were chosen.
+Replace bracketed values with the values from this run. Drop the "Folders
+bootstrapped" line if zero folders were chosen.
 
 ## Reference
 

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

@@ -0,0 +1,95 @@
+---
+title: Verify depths
+description: The two verification depths and the script chain each runs against a freshly scaffolded project
+---
+
+# Verify depths
+
+Runs the local verification chain against a freshly scaffolded project. Catches
+config typos, missing deps, and wiring mistakes before the user ever sees them.
+
+Two depths over one contract. Both read the `scripts` block from the project's
+own `package.json` and run what is declared there, so neither hardcodes a script
+name and a stack exposing a different set is covered without an edit here.
+
+## Guards
+
+- If `package.json` does not exist at the project root, stop: `❌ No package.json found. Cannot verify.`
+- If `node_modules/` does not exist, run `bun install` first, then proceed.
+
+## Step 1: read scripts
+
+Read `package.json` from the project root and extract the `scripts` block. Do
+not hardcode script names. Different stacks expose different scripts.
+
+## Step 2: run the chain
+
+Run the scripts for the requested depth in order. Stop on the first failure and
+surface the error. Skip any script not present in `package.json`. Do not invent
+a fallback command. Run each as `bun run <script>` from the project root.
+
+### Default depth
+
+Every script is a leaf command, so failures point at the exact break and the
+exit code is the whole verdict.
+
+| Order | Script      | Skip if                     |
+| ----- | ----------- | --------------------------- |
+| 1     | `lint:fix`  | absent                      |
+| 2     | `typecheck` | absent                      |
+| 3     | `check`     | absent                      |
+| 4     | `test:run`  | absent, fall back to `test` |
+| 5     | `build`     | absent                      |
+
+Do not run composite scripts like `check:full`. Do not run `dev`, `preview`,
+`test:e2e`, `test:ui`, or `screenshot` at this depth. They belong to `deep`
+below.
+
+### Deep depth
+
+The checks a scaffold's leaf scripts cannot cover: whether the dev and preview
+servers actually start, whether the end-to-end suite passes against a real
+server, and whether the screenshot harness produces output.
+
+| Order | Script       | Skip if | How judged              |
+| ----- | ------------ | ------- | ----------------------- |
+| 1     | `dev`        | absent  | server smoke, see below |
+| 2     | `preview`    | absent  | server smoke, see below |
+| 3     | `test:e2e`   | absent  | leaf script: exit code  |
+| 4     | `screenshot` | absent  | leaf script: exit code  |
+
+`deep` runs the four above and not the five leaf scripts, which the default
+depth already covers. The two sets are disjoint, so running both depths runs
+every declared script exactly once.
+
+Take `deep` on request rather than by default. A dev server that starts slowly
+reads as a failure here, which is too flaky to fail an unattended scaffold check
+on, and the end-to-end stage needs a browser install the chain does not make.
+
+### Server smoke
+
+`dev` and `preview` run until stopped, so there is no exit code to read. Start
+the script backgrounded, wait 5 seconds, then check two things: the process is
+still running, and its captured output carries no string matching `error`,
+`Error`, or `fatal`. Kill the process either way once judged. Report a failure
+on either check failing.
+
+This is weaker than a real readiness probe. No manifest key exposes a generic
+port to poll across stacks, so port-probing is out of reach here.
+
+## Step 3: report
+
+For each script run, report one of:
+
+- `✅ <script>`
+- `❌ <script>` followed by the failing output (last 40 lines) or, for a server script, the reason judged (process died, or a fatal string in its output)
+
+End with a summary line naming the depth that ran:
+
+- On pass: `✅ Scaffold verified at <depth> (<n> scripts passed).`
+- On fail: `❌ Scaffold failed at <script>. Fix the error and re-run the verify phase.`
+
+## Out of scope
+
+- Generating the configs these scripts drive, which the tooling stack reference owns.
+- CI workflow validation. It runs in GitHub Actions on a pull request rather than locally. The `deep` depth runs the same end-to-end and screenshot stages locally, as the closest proxy.

package/docs/agents/sandbox.md

@@ -65,7 +65,7 @@ The record carries every scenario with the arms that declare, plus `totalScenari
 
 `--skills` answers what the scenario count cannot, which is whether anything can fail a given skill. It adds `skills`, `totalSkills`, `asserted`, `shouldBeAsserted`, `exempt`, `staleExemptions`, and `supersededExemptions` to the record, and keeps the scenario view rather than replacing it. The two denominators disagree on purpose: an armed scenario under `infra/` or `tooling/` exercises a CLI domain and pairs with no skill at all.
 
-A skill pairs to a scenario by filename, `<category>-<command>` first and bare `<command>` second, so `claude/setup-init.sh` reaches the `setup-init` skill. `should-be-asserted` is the default rather than a queue to drain, and which of those skills earns an arm is a project decision the census does not make.
+A skill pairs to a scenario by filename, `<category>-<command>` first and bare `<command>` second, so `claude/target-setup.sh` reaches the `target-setup` skill. `should-be-asserted` is the default rather than a queue to drain, and which of those skills earns an arm is a project decision the census does not make.
 
 `exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
 

package/docs/agents/scripting.md

@@ -145,5 +145,6 @@ overwrites every golden config a stack ships, which reaches the CI workflow, the
 git hooks, the end-to-end harness, and the shell scripts under `scripts/`, so a
 headless run carrying neither `--check` nor `--write` reports what it would
 replace and exits 1 rather than applying it. Run `--check` first to read the
-list, then `--write` to apply it. `canon tooling sync --help` names both, and the
-full per-stack path list sits in the `canon-cli` skill.
+list, then `--write` to apply it. `canon tooling sync --help` names both, and
+`canon tooling diff <stack> <target>` reports the per-stack path list resolved
+against a real target.

package/docs/target-projects.md

@@ -51,19 +51,19 @@ claude --plugin-dir <toolkit>/claude
 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:setup-init` in Claude Code. The skill detects the stack, resolves flags, previews the full chain, and runs it end-to-end.
+2. Invoke `canon:target-setup` in Claude Code. The skill detects the stack, resolves flags, previews the full chain, and runs it end-to-end.
 
 The chain is:
 
 - `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 eslint, 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/development.md -->
-- `setup-verify` runs the installed `package.json` scripts (lint, typecheck, check, test, build) and reports pass or fail
-- `setup-indexes` bootstraps the `index.md` system over the project's own documentation folders, confirming candidate folders with the operator rather than running unattended
+- 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 stops at the project edge. `repo-metadata` and `git-commit` also ship, reaching a remote and the project's history respectively, and neither runs 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:canon-operator`, which reads what the project already carries before naming a per-domain command. An install wanting the Claude layer without the tooling chain runs `canon claude init` for the seed docs and then `canon: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.
+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 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:canon-operator`, which reads what the project already carries before naming a per-domain command. 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.
 
-Run `canon:setup-smoke` by hand once `setup-verify` passes, for the heavier server smoke, end-to-end, and screenshot pass, since the same flakiness reasons that excluded those stages from `setup-verify` keep it out of this unattended chain too.
+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.
 
 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. `project-commands` reads it to start the app or run a check on request, so a command missing from the table cannot be run 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 -->
 
@@ -86,13 +86,13 @@ Each diagram entry records the commit and date it was last verified against, and
 
 The default path is `base`. `canon init` on `base` installs base tooling configs, Claude seeds, and governance core rules, and scaffolds an empty `.claude/wiki/`. Most projects need nothing more.
 
-Escalate only for real web apps. The `setup-init` skill reads `package.json` and root configs, then picks the matching tooling stack (`canon tooling list --json` names the current set) and the matching governance stack (`react`, `astro`, `node`).
+Escalate only for real web apps. The `target-setup` skill reads `package.json` and root configs, then picks the matching tooling stack (`canon tooling list --json` names the current set) and the matching governance stack (`react`, `astro`, `node`).
 
 `node-server` is named rather than detected. It carries the server-side security and persistence rules for a project writing request handlers or a persistence layer in TypeScript, and the detect step matches a runtime or a framework against stack names, so nothing there marks a project as a backend. Pass it deliberately with `canon init --stack node-server` or `canon gov install node-server <target>`.
 
 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:setup-gov` for the governance layer alone, which is language-neutral.
+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.
 
 Run `canon tooling list --json` and `canon gov list --json` to see the current catalogs. Never hardcode stack names.
 
@@ -115,9 +115,9 @@ The plugin corpus carries runtime behavior rather than reference prose alone, be
 
 When a new need appears after scaffold, install the one domain without re-running `canon init`.
 
-- Governance rule for a newly adopted library: invoke `canon:setup-gov`, or run `canon gov install <stack> --add <rule> <path>`
+- Governance rule for a newly adopted library: invoke `canon:target-setup gov`, or run `canon gov install <stack> --add <rule> <path>`
 - Project-specific rule the toolkit does not ship: invoke `canon:create-rule`. It scaffolds a rule into `.claude/rules/` with a non-colliding number, and `canon gov sync` leaves it untouched.
-- Index.md system for a markdown-heavy folder that emerged: invoke `canon:setup-indexes`
+- Index.md system for a markdown-heavy folder that emerged: invoke `canon:target-setup indexes`
 
 Standards and snippets are not on that list, and there is nothing to add for either. Neither installs into a project, by default or by flag, so a session reads a standard with `canon standards <name>` and a snippet through its `@` reference off the live plugin symlink, both resolving against the toolkit rather than a project copy. A project holding a `.claude/standards/` or `.claude/snippets/` folder from an older toolkit is carrying a stale artifact nothing reads, and deleting it is safe.
 
@@ -300,7 +300,7 @@ cd <your-project>
 claude
 ```
 
-In the session, invoke `canon:setup-init`. The skill detects no framework and resolves tooling to `base` and governance to `base`. The preview marks both stacks as fallbacks, since neither came from a match, then the chain runs `canon init`.
+In the session, invoke `canon:target-setup`. The skill detects no framework and resolves tooling to `base` and governance to `base`. The preview marks both stacks as fallbacks, since neither came from a match, then the chain runs `canon init`.
 
 Ongoing: run `canon sync --check .` to see what has drifted, then invoke `canon:seed-sync` for seed drift or `canon sync .` for a catch-all refresh.
 
@@ -311,7 +311,7 @@ bun create vite my-app && cd my-app
 claude
 ```
 
-Invoke `canon:setup-init`. The skill reads `package.json` and the Vite config, resolves tooling to `vite-react` and governance to `react`, and runs `canon init` with the resolved flags.
+Invoke `canon:target-setup`. The skill reads `package.json` and the Vite config, resolves tooling to `vite-react` and governance to `react`, and runs `canon init` with the resolved flags.
 
 Ongoing maintenance:
 

package/docs/workflow/ai-workflow.md

@@ -200,19 +200,14 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Set up a project
 
-| Skill                  | When to use                                                                                                     |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `canon:setup-init`     | On a fresh scaffold, to detect the stack and run the whole install chain in one pass                            |
-| `canon:canon-operator` | On a project that already exists, to read what it carries before an install is picked                           |
-| `canon:setup-gov`      | When the governance rules are wanted without the tooling chain                                                  |
-| `canon:setup-indexes`  | When a markdown-heavy folder needs an `index.md` a session can browse                                           |
-| `canon:setup-plugins`  | On a new machine, to install the community and official plugins user-scoped                                     |
-| `canon:setup-verify`   | After the agent generates configs, to run the installed scripts and report pass or fail                         |
-| `canon:setup-smoke`    | After `setup-verify` passes, to check the dev and preview servers, end-to-end tests, and the screenshot harness |
-| `canon:sketch-design`  | Before `design-extract`'s greenfield path, to trace a design direction from reference images or URLs            |
-| `canon:design-extract` | Before the first UI feature, to draft `canon/DESIGN.md`                                                         |
-| `canon:draft-diagram`  | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                            |
-| `canon:repo-metadata`  | When the GitHub About text, homepage, or topics may have drifted, to reconcile them against the README          |
+| Skill                  | When to use                                                                                            |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ |
+| `canon:target-setup`   | On a fresh scaffold, to detect the stack and run the install chain, or to reach one phase of it alone  |
+| `canon:canon-operator` | On a project that already exists, to read what it carries before an install is picked                  |
+| `canon:sketch-design`  | Before `design-extract`'s greenfield path, to trace a design direction from reference images or URLs   |
+| `canon:design-extract` | Before the first UI feature, to draft `canon/DESIGN.md`                                                |
+| `canon:draft-diagram`  | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                   |
+| `canon:repo-metadata`  | When the GitHub About text, homepage, or topics may have drifted, to reconcile them against the README |
 
 ### Decide what to build
 

package/governance/rules/ui/400-ui.md

@@ -9,11 +9,6 @@ paths:
 
 # UI copy standards
 
-## Casing
-
-- Use sentence case for all rendered UI text: headings, labels, nav items, tab titles, and dialog titles.
-- Retain original casing for proper nouns and product names: `GitHub`, `macOS`, `TypeScript`.
-
 ## Punctuation
 
 - Do not use em dashes (`—`). Use a comma or period, or restructure the sentence.

package/governance/rules/ui/460-design-taste.md

@@ -25,5 +25,5 @@ paths:
 
 - Accessibility, keyboard interaction and ARIA are a separate topic. `410-a11y` routes them, on every rendered path.
 - States, empty and loading coverage, and destructive confirmation are a separate topic. `430-ux-completeness` routes them.
-- Rendered copy casing, button labels and error wording are a separate topic. `400-ui` routes them.
+- Rendered copy casing is a separate topic. `465-interface-casing` routes it. Button labels and error wording are separate too, and `400-ui` routes them.
 - The floor those three carry is not restated in the skill, and it is not traded against a preference where the two collide.

package/governance/rules/ui/465-interface-casing.md

@@ -0,0 +1,31 @@
+---
+description: Enforce casing for interface text in markup, MDX, and content modules, where copy lives in a content folder
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
+  - '**/*.mdx'
+  - '**/content/**/*.ts'
+---
+
+# Interface casing standards
+
+## Sentence case
+
+- Use sentence case for all rendered interface text: headings, labels, nav items, tab titles, and dialog titles.
+- Retain original casing for proper nouns and product names: `GitHub`, `macOS`, `TypeScript`.
+- Treat title case on every heading as a template tell, since it reads as a default rather than a choice.
+
+## Uppercase labels
+
+- Keep small uppercase labels above headings to one per three sections, with the first screen counting as one. More than `ceil(sections / 3)` is too many, and the fix is usually to delete the label, since a section's position already says what it is.
+- Treat the count as a judgment, since a glob cannot check it.
+
+## Where it applies
+
+- The rule covers markup, MDX, and content modules under a `content/` folder. Copy kept elsewhere, such as a locale file, is not reached, so apply the same casing there without the rule firing.
+
+## Overriding
+
+- Depart from sentence case where the case needs it, such as an acronym, a brand mark, or a set-in-caps identity the design chose on purpose.

package/governance/stacks/astro.toml

@@ -1,2 +1,2 @@
 extends = "node"
-rules = ["210-astro", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior", "460-design-taste", "470-motion"]
+rules = ["210-astro", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior", "460-design-taste", "465-interface-casing","470-motion"]

package/governance/stacks/react.toml

@@ -1,2 +1,2 @@
 extends = "node"
-rules = ["200-react", "230-nextjs", "250-tailwind", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "310-zod", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior", "460-design-taste", "470-motion"]
+rules = ["200-react", "230-nextjs", "250-tailwind", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "310-zod", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior", "460-design-taste", "465-interface-casing","470-motion"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.103.0",
+  "version": "4.104.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.sh

@@ -197,7 +197,7 @@ const FEATURED_SKILLS = [
   "review-pr",
   "task-board",
   "git-ship",
-  "setup-init",
+  "target-setup",
   "systematic-debugging",
 ]
 

package/src/claude/cases/setup.ts

@@ -1,39 +1,40 @@
 import type { SkillCase } from '@/claude/skills-rank'
 
 /**
- * `setup-*`, `migration-*`, `canon-*`, and `create-rule`: scaffolding,
+ * `target-setup`, `migration-*`, `canon-*`, and `create-rule`: scaffolding,
  * proposal-only migrations, and the toolkit's own reference and feedback
  * surfaces.
+ *
+ * The five `target-setup` cases are one skill read through five entry phrasings
+ * rather than five rows that collapsed to a duplicate. Each names a different
+ * phase, and the merged description has to carry every one of them, which is
+ * the discrimination the six-skill family failed at from the other direction.
  */
 export const SETUP_CASES: readonly SkillCase[] = [
   {
     prompt:
       'This project has no rules installed yet, get the right governance in place.',
-    expect: 'setup-gov',
+    expect: 'target-setup',
   },
   {
     prompt:
       "Get the index.md system bootstrapped across this project's folders.",
-    expect: 'setup-indexes',
+    expect: 'target-setup',
   },
   {
     prompt:
       'This is a brand-new project, get the toolkit bootstrapped in one shot.',
-    expect: 'setup-init',
-  },
-  {
-    prompt: 'Get the usual Claude Code plugins provisioned on this machine.',
-    expect: 'setup-plugins',
+    expect: 'target-setup',
   },
   {
     prompt:
       "Run through the generated scaffold's scripts and confirm each one passes.",
-    expect: 'setup-verify',
+    expect: 'target-setup',
   },
   {
     prompt:
       'Check that the dev server actually starts and the end-to-end suite passes against the scaffold.',
-    expect: 'setup-smoke',
+    expect: 'target-setup',
   },
   {
     prompt:
@@ -76,7 +77,7 @@ export const SETUP_CASES: readonly SkillCase[] = [
   {
     prompt:
       "Whatever the right toolkit command is, get this project's rules installed.",
-    expect: 'setup-gov',
+    expect: 'target-setup',
   },
   {
     prompt:

package/src/commands/sync.ts

@@ -109,7 +109,7 @@ function renderCheck(report: CheckReport): void {
     logStep('Not a toolkit project')
     logWarn('No .claude/ directory and no CLAUDE.md at the target.')
     logInfo(
-      'Run `canon init` to install, or /canon:setup-init to resolve a stack.',
+      'Run `canon init` to install, or /canon:target-setup to resolve a stack.',
     )
     outro()
     return

package/src/gate/measures.ts

@@ -629,6 +629,63 @@ export const shippedReferences: Measure = async (ctx) => {
   }
 }
 
+const RAW_FIELD_FILE_REFERENCE = /(?:^|\s)(?:-f|--raw-field)[ =]\S+=@/
+
+/**
+ * A `gh api` raw-string flag carrying a file reference, over the seven shipped
+ * corpora.
+ *
+ * `-f body=@<path>` sends the literal path as the field value, so a comment
+ * edited that way is overwritten with the path itself and loses the marker a
+ * later read resolves it by. `-F` is the flag that reads the file. The pattern
+ * requires `=@`, so `-F`, `--field`, and a raw string such as `-f body="text"`
+ * all pass.
+ *
+ * It scans prose rather than parsing a command, so a body quoting the wrong
+ * spelling to explain it fails too. Reword it rather than exempting it, since an
+ * exemption is what lets a real occurrence hide.
+ */
+export const rawFieldFileReference: Measure = async (ctx) => {
+  const files = shippedCorpusFiles(ctx.root)
+
+  if (files.length === 0) {
+    return {
+      emissions: [],
+      unmeasured: `No corpus under ${SHIPPED_CORPORA.join(', ')} is present, so no shipped file was read.`,
+    }
+  }
+
+  const found = files.flatMap((file) =>
+    readFileSync(join(ctx.root, file), 'utf8')
+      .split('\n')
+      .flatMap((text, index) =>
+        RAW_FIELD_FILE_REFERENCE.test(text) ? [`${file}:${index + 1}`] : [],
+      ),
+  )
+
+  if (found.length === 0) {
+    return {
+      emissions: [
+        info(
+          `No raw-field file reference across ${files.length} files in ${SHIPPED_CORPORA.length} shipped corpora`,
+        ),
+      ],
+    }
+  }
+
+  return {
+    emissions: found.map((location) =>
+      warn(
+        `${location} passes a file reference through a raw-string flag, which posts the path as the field value. Use -F instead`,
+      ),
+    ),
+    failure:
+      found.length === 1
+        ? 'One raw-field file reference in the shipped corpora. Change -f or --raw-field to -F or --field where the value reads a file with @, or reword a prose line quoting the wrong spelling.'
+        : `${found.length} raw-field file references in the shipped corpora. Change -f or --raw-field to -F or --field where the value reads a file with @, or reword a prose line quoting the wrong spelling.`,
+  }
+}
+
 /**
  * Every git-tracked file quoting a listed client command with the wrong
  * argument, over the whole tree rather than one corpus, since a wrong