@erclx/canon 4.102.0 → 4.104.0

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.

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/claude/skills/ui-checklist/SKILL.md

@@ -31,6 +31,23 @@ Group visual items by feature area. Use `- [ ]` checkbox syntax, and write each
 - [ ] <action> → <expected visual result>
 ```
 
+## The widths block
+
+A screenshot shows one width, so a reviewer cannot tell from the picture alone whether any other width was looked at. When a change touches layout, spacing, or anything responsive, put this block above the visual items, since it frames what the screenshots beside it can support:
+
+```markdown
+**Widths:**
+
+Seen at: <the widths the reviewer looked at>
+Not seen at: <the widths nobody looked at, or "none">
+```
+
+Leave both lines for the reviewer to complete. This session cannot verify a width, so the block asks what was seen and never asserts coverage. Fix no width list in the block, since which widths matter belongs to the project.
+
+Keep the `Not seen at:` line even when the answer is "none", so an omission reads as a claim rather than a gap.
+
+Omit the block when the change cannot differ by width, such as copy, color, or a state that renders the same everywhere, the way the missing-test heading is omitted below.
+
 ## The missing-test list
 
 Name every automatable change this branch ships with no test, one per line, with the layer `test-craft` would place it at. Do not write the test and do not read the project's test config to write one against.

package/docs/agents/commands.md

@@ -22,7 +22,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon indexes regen`            | Regenerate `index.md` files from sibling frontmatter                                                                                                                                                                                                                                                                         |
 | `canon indexes list [path]`      | Flatten every folder index under a path into one `{path, title, description}` catalog (`--json`)                                                                                                                                                                                                                             |
 | `canon docs [topic]`             | Emit toolkit reference docs (`list`, or a topic by name)                                                                                                                                                                                                                                                                     |
-| `canon design render`            | Render `canon/DESIGN.md` tokens to HTML and CSS                                                                                                                                                                                                                                                                              |
+| `canon design render`            | Render `canon/DESIGN.md` tokens to HTML and CSS, declaring each vendored face the typography table names with `--embed-fonts`                                                                                                                                                                                                |
 | `canon design regen`             | Rewrite this repository's `canon/DESIGN.md` and `src/design/base.css` from `src/design/tokens.ts`                                                                                                                                                                                                                            |
 | `canon design board`             | Generate a static page set indexing tokens, surfaces, wireframes, past candidates, components, and references against a caller-resolved `--root` (`--out`), defaulting to the main worktree                                                                                                                                  |
 | `canon design css`               | Emit the design tokens and components as CSS on stdout (`--no-components` for properties alone)                                                                                                                                                                                                                              |

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.