@erclx/canon 5.32.0 → 5.34.0

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.32.0",
+  "version": "5.34.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/api-design/REQUIREMENT.md

@@ -19,7 +19,7 @@ The one skill nearest the subject leaves the pointer open. `codebase-layout` exc
 
 - State Hyrum's Law as design rules a session can act on: decide what is observable, and expose no storage type, internal identifier, ordering, or timing by accident
 - Tell the session to write the contract, being the signature, flags, output shape, or schema, before the body
-- State one error shape per surface with a stable code a caller can branch on, pointing at the core code rule for structured errors and hidden internals rather than restating it
+- State one error shape per surface with a stable code a caller can branch on, and own the hidden-internals clause in the body, since no project rule carries it for every code stack
 - State validation at the boundary, once, with the value trusted inside
 - State additive change as the default: new fields and flags optional, nothing renamed or removed in place, no change of meaning under an existing name, and the One-Version Rule for a caller that cannot pin
 - State the four idempotency rules: store and honor a caller's key, claim it in one atomic step under a unique constraint, fail loudly on a reused key with a different body, and keep a key past the longest retry window
@@ -30,7 +30,6 @@ The one skill nearest the subject leaves the pointer open. `codebase-layout` exc
 ## Must not
 
 - Name a framework, a protocol style, or a language in the body. Status codes, verbs, pagination, and schema languages stay out, so the body holds for a function, a command, a file format, and an endpoint alike.
-- Restate the two error bullets of the core code rule
 - Restate the consumer-listing axis `review-craft` carries for a finished change
 - Cover interface depth or the internals behind a boundary, which govern what sits behind a surface rather than what crosses it
 - Import an external skill's tone, such as a law stated as absolute, or an excuse row rebutting an objection no session has raised

package/claude/skills/api-design/SKILL.md

@@ -31,8 +31,8 @@ Every observable behavior becomes a dependency once there are enough callers, wh
 
 ## Keep one error shape per surface
 
-- Give every failure on one surface the same shape, carrying a stable code a caller can branch on and a message for the person reading it. Branching on message text breaks the first time the message is reworded.
-- Follow the project's own rule on structured errors and hidden internals where it states one, rather than inventing a second error convention beside it.
+- Give every failure on one surface the same shape, carrying a stable code a caller can branch on and a message for the person reading it. Branching on message text breaks the first time the message is reworded. Keep internal implementation details out of the message, since a caller reads it and cannot act on a stack frame.
+- Reuse the error type the project already throws or returns where one exists, rather than inventing a second error convention beside it.
 
 ## Validate at the boundary
 
@@ -98,7 +98,6 @@ Check each line against the surface the change produced. A line answering no is
 ## What this delegates
 
 - Where the file holding a surface sits on disk: `codebase-layout`
-- The structured error rule and hidden internals floor every code stack loads: `000-code`
 - Listing the consumers a finished change breaks, and the docs it made false, during review: `review-craft`
 - A visual interface, its layout, and its look: `design-taste`
 - Interface depth and the internals behind a boundary: `code-craft`

package/claude/skills/api-design/references/adopted.md

@@ -21,7 +21,7 @@ From `addyosmani/agent-skills@2686b620`, [`skills/api-and-interface-design/SKILL
 
 **Contract first.** Write the interface before the body. Adopted as its own group, widened from an endpoint to a signature, a flag set, an output shape, and a schema.
 
-**One error shape.** Every failure on one surface carries the same structure. Adopted with a stable code added for the caller to branch on, and pointed at the core code rule for the structured-error floor rather than restating it.
+**One error shape.** Every failure on one surface carries the same structure. Adopted with a stable code added for the caller to branch on, and a clause keeping internal implementation details out of the message, since no project rule carries either for every code stack.
 
 **Validation at the boundary.** Check input where it enters and trust it inside. Adopted, with a value read back from a file or another service counted as input.
 

package/claude/skills/auto-ship/SKILL.md

@@ -12,7 +12,7 @@ Chain the post-plan pipeline in a single run. Every step but the UI checklist ha
 ## Guards
 
 - All `.canon/plans/` reads resolve at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does.
-- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.` This slug is provisional. It is superseded once `session-worktree` runs, whether at Step 0 or before this chain began. Every later step keys its output on the slug that run resolves, being the worktree and the branch, regardless of which plan Step 1 reads.
+- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.` This slug is provisional. It is superseded once `session-worktree` runs, whether at Step 0 or before this chain began. Every later step keys its output on the slug that run resolves, being the worktree and the branch, regardless of which plan Step 1 reads.
 - Resolve `<plan>` in Step 1, ahead of any other read.
 - If the working tree has uncommitted changes unrelated to the plan, stop: `❌ Uncommitted changes outside the plan. Commit or stash before autoshipping.`
 

package/claude/skills/auto-ship/references/worktree-name.md

@@ -14,7 +14,7 @@ canon tasks plan-branch <argument> --json
 ```
 
 - `conforms: true`: pass the record's `branch`, which is already `<type>/<slug>`, and invoke nothing else to derive a name.
-- `conforms: false`: the plan's own filename breaks a cap in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`. Pass `branch` anyway and say the cap it broke, since the alternative is a name this session shortened by hand, which is a second derivation and the thing this call exists to prevent. `git-branch` decides the rename at ship.
+- `conforms: false`: the plan's own filename breaks a cap in `${CLAUDE_SKILL_DIR}/../git-branch/references/branch.md`. Pass `branch` anyway and say the cap it broke, since the alternative is a name this session shortened by hand, which is a second derivation and the thing this call exists to prevent. `git-branch` decides the rename at ship.
 - Anything else, including a refusal, a record carrying no `branch` key, and an installed binary carrying no `plan-branch` subcommand: invoke `canon:session-worktree` bare and let its ladder derive the name. Say the verb did not answer, so a reader can tell a derived name from a fallback one.
 
 The dispatch runbook runs the same verb on the same plan to pick the branch its collision check clears, so calling it here is what makes the checked branch and the taken branch one string.

package/claude/skills/backlog-triage/REQUIREMENT.md

@@ -7,7 +7,7 @@ description: Why the backlog gets a measured verdict per row with a lean toward
 
 ## Gap
 
-Without this skill, the backlog only grows. `task-board` declines or archives one named task, and nothing reads the backlog as a whole, so a row stays until somebody happens to remember it and decides by hand. The orchestrator's backlog re-test only clears a row upward onto the board, so no sweep ever takes one off. A backlog past fifty rows had no surface that could say which of them still mattered.
+Without this skill, the backlog only grows. `task-board` declines one named task and `task-complete` archives one, and nothing reads the backlog as a whole, so a row stays until somebody happens to remember it and decides by hand. The orchestrator's backlog re-test only clears a row upward onto the board, so no sweep ever takes one off. A backlog past fifty rows had no surface that could say which of them still mattered.
 
 Four failure modes cost more than the rest. A pass that judges a row by what its task file says rather than by the tree keeps every row, since a task file reads as live the day it was written and every day after. A pass that applies its own verdicts decides rows on silence, which ships a decline nobody approved on a board with no history to restore it from. A keep that carries no measurement is the default nobody argues with, so a triage without a lean toward decline ends with the same backlog it started with. And a keep that measures only that the defect still exists keeps nearly everything, since a row filed against the tree almost always still reproduces. One pass suggested keeping 24 of 27 rows that way, where the operator kept 6 and promoted 1.
 
@@ -42,6 +42,6 @@ Four failure modes cost more than the rest. A pass that judges a row by what its
 
 - Filing a brain dump, which `plan-intake` owns
 - Answering the filed items, which `plan-intake-answer` owns
-- Creating a task, or archiving and declining one named task outside a triage, which `task-board` owns
+- Creating or declining one named task outside a triage, which `task-board` owns, and archiving one, which `task-complete` owns
 - Ordering the rows a promote lands under `## Needs a plan`, which the orchestrator's refill sweep owns
 - Skipping rows kept at a recent triage, which waits on a second triage measuring the re-read cost

package/claude/skills/backlog-triage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: backlog-triage
-description: Files a measured verdict for every backlog row into an intake folder, suggesting decline, archive, keep, or promote and leaning toward decline, then applies the verdicts the operator approved through the task verbs. Use when asked to "triage the backlog", "prune the backlog", "which backlog rows are still worth doing", "clear out the backlog", or "apply the backlog triage". Do NOT use to file a brain dump, which is `plan-intake`, to answer the filed items, which is `plan-intake-answer`, or to create, archive, or decline one named task, which is `task-board`.
+description: Files a measured verdict for every backlog row into an intake folder, suggesting decline, archive, keep, or promote and leaning toward decline, then applies the verdicts the operator approved through the task verbs. Use when asked to "triage the backlog", "prune the backlog", "which backlog rows are still worth doing", "clear out the backlog", or "apply the backlog triage". Do NOT use to file a brain dump, which is `plan-intake`, to answer the filed items, which is `plan-intake-answer`, or to create or decline one named task, which is `task-board`, or archive one, which is `task-complete`.
 metadata:
   family: decide
 ---

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

@@ -1,39 +1,42 @@
 ---
 name: canon-cli
-description: Why a session is pointed at the verb catalog, the reference docs, and the overwrite contract from one place, and why the skill reads rather than writes
+description: Why a session is routed from a job to its canon verb from one place, why the verbs that can lose its edits are flagged before they run, and why the skill reads rather than writes
 ---
 
 # Canon cli requirement
 
 ## Gap
 
-Without this skill, a session runs a `canon` sync and finds out afterward what it did. The command names give nothing away. `install` and `sync` differ per domain, some surfaces overwrite unconditionally, some merge, some are written once and never touched again, and none of that is visible from the command line the user typed.
+Without this skill, a session guesses at a verb from its name and runs a `canon` sync to find out afterward what it did. The command names give nothing away. `install` and `sync` differ per domain, some surfaces overwrite unconditionally, some merge, some are written once and never touched again, and none of that is visible from the command line the user typed.
 
-The damage lands on the files a project owns. A golden config carrying local edits is replaced without a warning anyone saw, and a standards install overwrites every standard in a project that only needed the two it had drifted on. The user learns which category a file was in by losing the edit.
+The damage lands on the files a project owns. A golden config carrying local edits is replaced without a warning anyone saw, and a governance sync takes back a rule the project had edited. The user learns which category a file was in by losing the edit.
 
 The inverse failure is quieter. A session that assumes a sync will pick up a change edits a seed and waits for an update that never comes, because the seed is copy-once and no sync command writes it again. Both failures are one missing fact available before the command runs.
 
-Being reachable is a separate problem from being right. This is a pure reference whose moment happens inside another skill's run, so nothing brings it up unless a body names it. Three sibling requirement files named it and routed nothing, because Claude Code loads `SKILL.md` as the entry and never opens the sibling. A route lives in a body or it does not exist, and a fourth requirement mention would repeat the same defect.
+A third gap is the route itself. `canon --help` lists every top-level verb with a partial hint, and a session with a job in hand pays a `--help` read per candidate to find the one that does it, or picks by name and lands on the wrong one. The job-to-verb mapping is the fact the session needs and no verb answers.
 
-A third gap sits beside the first two, aimed at a different question. `canon --help` lists every top-level verb and `canon docs` emits the toolkit's own reference corpus, but no reference skill pointed a session at either. No skill does now. A session guessing at a verb's name, or restating what a doc already answers, is the same missing-fact failure the overwrite gap names.
+Being reachable is a separate problem from being right. This is a pure reference whose moment happens inside another skill's run, so nothing brings it up unless a body names it. A route lives in a body or it does not exist, and a mention in a sibling's requirement file is not one.
 
 ## Must
 
-- State per surface and per command whether an existing file is overwritten, merged, written once, or left alone
-- Warn about a destructive run before it happens, naming the surface that will be lost
-- Name the section-preserving path for a standard or seed the project has customized
-- Defer to the toolkit's own context docs when they and this summary disagree, since the summary is a copy and they are the source
-- Point to `canon docs agents` for the verb catalog and to `canon docs` for the reference corpus, rather than restating either
+- Name each target-usable top-level verb by its job, never its subcommands or flags
+- Route an author-and-render verb to the skill that owns it rather than describing it
+- Warn about a verb that can lose the project's edits before it runs, naming what it replaces
+- Point each destructive verb at `canon docs install-and-sync`, which owns the overwrite detail
+- Point to `canon <verb> --help` and `canon docs agents` for subcommands, flags, and the invocation contract
+- Defer to `canon docs install-and-sync` when it and this summary disagree, since the summary is a copy and the doc is the source
 
 ## Must not
 
 - Run, or send the session to run, a `canon` command that writes or installs. The skill is read before acting on a sync.
-- Restate the verb catalog or a reference doc's content. Point to `canon docs agents` or `canon docs <topic>` instead. The overwrite table is this skill's one authored exception, and it too is a target-session summary, with the detail living with its owner.
-- Take a mention in a sibling's requirement file as an inbound route. The three bodies named in the gap above carry the pointer, and adding a fourth means editing that body rather than its requirement.
+- List a subcommand, a flag, or a JSON shape. That restates the docs and is the drift the one-name-per-verb rule removes.
+- List a verb that only works inside the toolkit repository. A named exemption set in the coverage test holds that boundary.
+- Take a mention in a sibling's requirement file as an inbound route. The pointer lives in the body that needs it.
 
 ## Guards
 
-- A surface or command the contract does not cover routes to the context docs rather than to an inference from a similar row
+- A test fails naming each top-level verb in `COMMAND_GROUPS` that the body neither carries as `canon <verb>` nor exempts, and fails again when an exemption names something that is no longer a verb
+- A verb or surface the skill does not cover routes to `canon docs` rather than to an inference from a similar row
 
 ## Out of scope
 

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

@@ -1,53 +1,96 @@
 ---
 name: canon-cli
-description: Reference for what a canon verb does before you run it. Run `canon docs agents` for the full command catalog, `canon docs` for any other reference doc, and read this skill's own table for what a sync or install command overwrites, merges, or leaves untouched in a target project. Use when asked "which canon command do I run", "is there a doc for X", "will this overwrite my changes", or before running `canon tooling`, `canon standards`, `canon claude sync`, or `canon init`. Do NOT use to execute a sync, an install, or a docs lookup, only to know which command answers the question.
+description: Routes a job to the `canon` verb that does it, and warns which verbs can lose a project's edits before one runs. Use when asked "which canon command does X", "is there a verb for X", "which command tells me if X", "will this overwrite my changes", or before running `canon sync`, `canon gov sync`, `canon tooling sync`, `canon design sync`, `canon migrate`, or `canon indexes regen`. Do NOT use to execute a verb, only to pick one and know what it costs.
 metadata:
   family: answer
 ---
 
-# Toolkit CLI contract
+# Toolkit CLI router
 
-Consult before running an unfamiliar `canon` verb, before a sync or install, or when asked "will this overwrite my changes". This skill is reference only. It never runs a sync or an install.
+Consult to pick the `canon` verb for a job, and before running a verb that writes. This skill is reference only. It never runs a verb.
 
-## Verb catalog and reference docs
+## Find the verb
 
-- Run `canon docs agents` for the full command catalog and invocation contract, rather than guessing at a verb from its name.
-- Run `canon docs list` for every other reference doc, then `canon docs <topic>` by name.
-- State neither list here. Both read live off the CLI, and a copy in this body ships on a different cadence than the commands it names.
+- Each row below names a verb by its job. Subcommands and flags are not listed here, so read them where they are kept.
+- Run `canon <verb> --help` for a verb's subcommands and flags.
+- Run `canon docs agents` for the invocation contract behind every verb, and `canon docs list` for every other reference doc, then `canon docs <topic>` by name.
 
-## Overwrite contract
+## Project setup
 
-| Surface                                                                                       | Command              | Effect on existing files                                                    |
-| --------------------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------- |
-| 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`, base's `verify.yml` and PR template, state docs) | `canon tooling sync` | Copy-once. Dropped on first install, untouched after.                       |
-| Standards                                                                                     | none                 | Nothing installs. `canon standards <name>` reads and never writes.          |
-| Seed docs and `CLAUDE.md`                                                                     | `canon claude init`  | Skipped when present. Never overwritten.                                    |
-| Seed docs                                                                                     | `canon claude sync`  | Never touched. Only `.gitignore` is written.                                |
-| Stack references                                                                              | none                 | Nothing installs. `canon tooling reference <stack>` reads and never writes. |
-| `.gitignore`, deps, scripts                                                                   | any sync             | Additive. Existing entries preserved. Deps re-pin on major skew.            |
-| Generated `index.md`                                                                          | any sync or regen    | Rewritten from target state. Hand edits are lost.                           |
+| Job                                          | Verb            |
+| -------------------------------------------- | --------------- |
+| Bootstrap a project with toolkit domains     | `canon init`    |
+| Bring every installed domain current         | `canon sync`    |
+| Reinstall the CLI itself                     | `canon upgrade` |
+| Move a project off a retired name or layout  | `canon migrate` |
+| List the projects the toolkit installed into | `canon targets` |
 
-## What a tooling sync can overwrite
+## Domains
 
-A golden config is any file a stack ships under `configs/`, and the category is wider than its name suggests. It carries the phase-label gate workflow, the web stack's 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.
+| Job                                                             | Verb              |
+| --------------------------------------------------------------- | ----------------- |
+| Install or sync governance rules                                | `canon gov`       |
+| Read an authoring standard by name                              | `canon standards` |
+| Sync a tooling stack's configs and seeds, or read its reference | `canon tooling`   |
+| Set up or sync the Claude workflow                              | `canon claude`    |
+| Scaffold a wiki                                                 | `canon wiki`      |
+| Regenerate the `index.md` files                                 | `canon indexes`   |
+| Read a toolkit reference doc                                    | `canon docs`      |
 
-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.
+## Author and render
 
-## Rules
+Each verb here has a skill that owns the job. Load the skill rather than driving the verb by hand.
 
-- `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 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.
-- For section-level customizations of a seed doc, merge by hand against the toolkit copy, not through `canon ... sync`.
+| Job                                          | Verb                | Skill                       |
+| -------------------------------------------- | ------------------- | --------------------------- |
+| Render the design system                     | `canon design`      | `canon:draft-figure`        |
+| Render a slide deck                          | `canon slides`      | `canon:draft-slides`        |
+| Render an HTML source to a PNG               | `canon capture`     | `canon:draft-identity`      |
+| Serve a directory and print the link         | `canon serve`       | none                        |
+| Record a running app                         | `canon demo`        | `canon:draft-screencast`    |
+| Report one computed property across routes   | `canon inventory`   | `canon:target-check`        |
+| Walk a page through interactions and measure | `canon drive`       | `canon:ux-measure`          |
+| Fetch a YouTube transcript                   | `canon transcripts` | `canon:youtube-transcripts` |
+| Open a learning workspace                    | `canon teach`       | `canon:teach-workspace`     |
+| Work on the local canvas                     | `canon canvas`      | `canon:canvas-board`        |
 
-## CLAUDE.md
+## Session and ship
 
-- `CLAUDE.md` is a copy-once seed. No `canon` sync command ever updates it. Merge it by hand against the toolkit copy, keeping the project's customizations.
+| Job                                            | Verb              |
+| ---------------------------------------------- | ----------------- |
+| Read and close tasks on the board              | `canon tasks`     |
+| Read and answer intake folders                 | `canon intake`    |
+| Validate, size, and move session records       | `canon records`   |
+| Resolve live sessions to a worktree and branch | `canon sessions`  |
+| Reclaim worktrees whose branches merged        | `canon worktrees` |
+| Read a pull request                            | `canon pr`        |
+| File toolkit feedback as an issue              | `canon feedback`  |
+
+## Reports
+
+| Job                                       | Verb             |
+| ----------------------------------------- | ---------------- |
+| Scan the tree for credentials             | `canon secrets`  |
+| Read the dependency set for advisories    | `canon deps`     |
+| Check a changed set against the label map | `canon labels`   |
+| Measure comment density                   | `canon comments` |
+| Report context folder health              | `canon context`  |
+| Check markdown against the standards      | `canon markdown` |
+| Count files, extensions, and lines        | `canon census`   |
+
+## Verbs that can lose your edits
+
+Read the doc each line names before running one of these. `canon docs install-and-sync` covers the governance and design verbs, `canon docs sync` covers tooling, `canon docs indexes` covers regeneration, and `canon docs migrate` covers the migrate verbs. Run the `--check` or `--dry-run` form first where the verb has one.
+
+- `canon sync` runs every installed domain's sync, so it carries each risk below.
+- `canon gov sync` replaces a rule you edited and deletes a rule the toolkit retired, edited or not.
+- `canon tooling sync --write` replaces every golden config a stack ships. Seeds are copy-once and dictionaries merge. Nothing writes without the flag. See `canon docs sync`.
+- `canon design sync` replaces the shipped design files and leaves `.claude/design/project/` alone.
+- `canon migrate --write` rewrites files that cite a retired name or layout. It reports and writes nothing without the flag. See `canon docs migrate`.
+- `canon indexes regen` rewrites each generated `index.md` from the folder's current state, so a hand edit there is lost. See `canon docs indexes`.
+
+No command writes a standard into a project, so `canon standards` is safe to run. `CLAUDE.md` and the other seed docs are copy-once, and no sync updates them. Merge those by hand against the toolkit copy.
 
 ## Source of truth
 
-- Full semantics live in the toolkit's own context entries. This skill is the target-session summary. When they disagree, the context docs win.
+- `canon docs install-and-sync` states what each install and sync verb writes, refuses, or leaves alone. `canon docs indexes` and `canon docs migrate` state the same for their verbs. When a doc and this skill disagree, the doc wins.

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

@@ -20,6 +20,7 @@ The last failure is the session's own effort. Asked to report, a session starts
 - Write the stated fallback for a field the session cannot fill, so an empty field reads as absent rather than as unreported
 - Open a GitHub issue on the toolkit repo through the CLI so the report lands where triage reads it, and print the returned URL on its own line
 - Surface the block and the reason when the issue call fails, since a failure that prints nothing leaves the report where nothing reads it
+- Carry the whole request in the issue body alone, since a comment is easy to miss and a body and a comment that differ leave triage choosing
 - Hold a report the operator marks sensitive, since the issue is public
 - Fall back to printing the block when the CLI is absent, so the report still exists
 

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

@@ -27,41 +27,23 @@ From the conversation so far, identify:
 - Repro details already in context (commands run, files touched), or `none`
 - Proposed fix, or `open` when the session settled on no direction
 
-Format as a single fenced markdown block, one `###` heading per field:
+**Fields the report omits when the session has none:**
 
-```markdown
-## Toolkit feedback
-
-### From project
-
-<name or kind>
-
-### Surface
-
-<type>, <file path or name>
-
-### Observed
-
-<one or two lines>
+- Suggested shape, when the session worked out what the change should look like, such as a template, a command's output, or a field list
+- Why, when the session has reasons for the fix beyond the observed failure
+- Links, when the session cites an issue, a pull request, or a document
 
-### Expected
+Format as a single fenced markdown block, one `###` heading per field. Read `${CLAUDE_SKILL_DIR}/references/template.md` on reaching this point for the block and each field's fallback.
 
-<one or two lines, or "unclear">
+`canon feedback` refuses a report missing `### Surface`, `### Observed`, or `### Proposed fix`, naming the one it did not find. `### From project`, `### Expected`, and `### Repro` are optional, so write the literal fallback the template shows rather than dropping the heading, which is what keeps a field the session cannot fill reading as absent instead of unreported.
 
-### Repro
-
-<commands or steps, or "none">
-
-### Proposed fix
-
-<one line, or "open">
-```
-
-`canon feedback` refuses a report missing `### Surface`, `### Observed`, or `### Proposed fix`, naming the one it did not find. The other three are optional, so write the literal fallback shown above rather than dropping the heading, which is what keeps a field the session cannot fill reading as absent instead of unreported.
+`### Suggested shape`, `### Why`, and `### Links` are optional the other way. Omit the heading when the session has nothing for it and write no fallback, since a report filed without them is complete and a placeholder would read as a reporter who had nothing to say.
 
 Headings rather than bold labels, because a GitHub issue form renders a submitted field as `### <label>`. One shape reaches the toolkit whichever route a report takes, and the CLI parses both with one parser. The retired `**Surface:**` form is refused rather than accepted, so a block carrying it has to be rewritten.
 
-Keep each field to one or two lines.
+Keep Observed and Expected to one or two lines each, so the report scans. Length belongs in Proposed fix, Suggested shape, and Why.
+
+The issue body is the request. Put everything the toolkit needs to act on it there, since a comment is easy to miss and a body and a comment that differ leave triage choosing. A comment carries only what happens after filing.
 
 ## Step 2: ship to the toolkit
 
@@ -73,7 +55,7 @@ command -v canon >/dev/null 2>&1
 
 The destination is a public GitHub issue on the toolkit repo, so the report leaves the machine. Hold it and ask when the operator has marked it sensitive, and never send it on a guess.
 
-Before the pipe below, run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against the composed block, phase-label half included. Nothing else checks what reaches the remote, so this scan is the only gate.
+Before the pipe below, run the scan in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` against the composed block, phase-label half included. Nothing else checks what reaches the remote, so this scan is the only gate.
 
 ```bash
 cat <<'EOF' | canon feedback

package/claude/skills/canon-feedback/references/template.md

@@ -0,0 +1,53 @@
+---
+title: Feedback report template
+description: The fenced block canon-feedback fills, one heading per field, with each field's stated fallback
+---
+
+# Feedback report template
+
+Step 1 of `canon-feedback`. The session reads this file on reaching the point where it formats the block.
+
+```markdown
+## Toolkit feedback
+
+### From project
+
+<name or kind>
+
+### Surface
+
+<type>, <file path or name>
+
+### Observed
+
+<one or two lines>
+
+### Expected
+
+<one or two lines, or "unclear">
+
+### Repro
+
+<commands or steps, or "none">
+
+### Proposed fix
+
+<the direction in as many lines as it takes, or "open">
+
+### Suggested shape
+
+<details>
+<summary>Shape</summary>
+
+<the template, output, or field list, in a fence one backtick longer than any fence it holds>
+
+</details>
+
+### Why
+
+- <one reason per bullet>
+
+### Links
+
+<one link per line>
+```

package/claude/skills/{canvas → canvas-board}/REQUIREMENT.md

@@ -1,9 +1,9 @@
 ---
-name: canvas
+name: canvas-board
 description: Scope boundary for driving the local design canvas, and the line between a drafted frame and the design it feeds
 ---
 
-# Canvas requirement
+# Canvas board requirement
 
 ## Gap
 

package/claude/skills/{canvas → canvas-board}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: canvas
+name: canvas-board
 description: Drives the local design canvas, where pages hold HTML frames the operator sees, drags, selects, and edits in the browser. Starts the canvas when it is not running, confirms the live shell loads, makes pages and frames, edits a frame through its file, reads what the operator selected or restyled, captures finished frames, and carries a picked direction into the project's design document. Use when asked to "open the canvas", "put this on the canvas", "draw a frame for X", "change the one I selected", "what did I pick", "capture this frame", or "move that frame on the canvas". Do NOT use to draft candidates for a taste decision, which is `draft-and-pick`.
 metadata:
   family: decide
 ---
 
-# Canvas
+# Canvas board
 
 Drive the canvas the operator is looking at. A page is a folder of HTML frames and a frame is one file, so a session draws by writing files and the operator sees each write land in the browser. The content format is fixed by `${CLAUDE_SKILL_DIR}/references/canvas.md`. Read it before writing a frame.
 
@@ -47,9 +47,11 @@ Hand the operator the address as a markdown link carrying the URL as its text an
 ## Step 2: make pages and frames
 
 - Add a page for each decision being drafted: `canon canvas page add <page> --json`.
-- Add each frame through the verb, which writes the starting file and its box in one locked step: `canon canvas frame add <page> <frame> --width <px> --height <px> --json`. Give the width the frame should render at, since a capture and the canvas both render at it.
+- Follow the house style in `${CLAUDE_SKILL_DIR}/references/canvas.md` before drafting an explanation frame.
+- Add each frame through the verb, which writes the starting file and its box in one locked step: `canon canvas frame add <page> <frame> --width <px> --height <px> --json`. Give the width the frame should render at, since a capture and the canvas both render at it. The verb places the frame after the last one, and a position the operator asks for goes through `frame move`.
 - Lay frames out with `canon canvas frame move <page> <frame> --x <px> --y <px> --json` rather than writing `layout.json` by hand, since the operator's drags write the same file under a lock.
 - Name pages and frames for what they hold, such as `pricing` and `pricing-dense`, so the operator can say which one by name.
+- After an insert or a resize, re-lay the page with `canon canvas arrange <page> --json`. It keeps the rows the operator dragged, places each on the standard gap, and drops layout entries whose frame file is gone. `--check` reports without writing.
 
 ## Step 3: edit a frame through its file
 
@@ -57,6 +59,7 @@ Write the frame's whole document to the `path` the add verb reported. The open c
 
 - From a linked worktree, `Edit` and `Write` refuse a main-root path. Write the whole file through one plain `Bash` heredoc instead, the route `session-worktree` states for a main-root write, and never take the redirect to a worktree copy.
 - Change one property of one element with `canon canvas edit <page>/<frame> --element <index> --set <property>=<value> --json` when the set it accepts covers the change, since it leaves every other byte as it was.
+- Fit the box to the content once the write lands: `canon canvas fit <page>/<frame> --json`. Read each row's `wide` and `font`. A `wide` frame needs its box widened, which fit never does, and a `font` frame names a family the canvas does not serve, so set its text to a served face and fit again. A fit that grew a frame leaves the rows below overlapped until `canvas arrange` runs.
 - Use the project's custom properties for every value the token stylesheet defines. The record from `serve` names the token source under `tokens`, and a `none` source means frames render unstyled, so say so rather than inventing values to cover it.
 
 Mark the frame before the first write, so the operator sees which frame is being worked on before anything lands, and clear the mark once the edits to it are done:

package/claude/skills/{canvas → canvas-board}/references/canvas.md

@@ -15,6 +15,7 @@ The folder is gitignored, so nothing in a repository checks its shape and nothin
 - [What a working canvas looks like](#what-a-working-canvas-looks-like)
 - [Pages](#pages)
 - [Frames](#frames)
+- [House style](#house-style)
 - [Layout](#layout)
 - [Tokens](#tokens)
 - [What a frame must not assume](#what-a-frame-must-not-assume)
@@ -24,9 +25,11 @@ The folder is gitignored, so nothing in a repository checks its shape and nothin
 
 Governs the canvas content under `.canon/canvas/`: page folder names, frame files, the `layout.json` shape, how tokens reach a frame, and what a frame must not assume about where it renders.
 
+Also governs the house style of an explanation frame, being a diagram, a board of notes, or a comparison. A mockup of the project's own interface is not an explanation frame, and it follows the project's design document for type, color, and layout.
+
 Does not govern:
 
-- The design decisions a frame is drafting, such as type, color, and layout taste: the project's own design document
+- The design decisions a mockup frame is drafting, such as type, color, and layout taste: the project's own design document
 - The project's design document and the token module it renders from, which a picked direction is carried into: `design.md`
 - The procedure that starts the canvas, reads the operator's selection, and carries a pick back, which belongs to the surface driving the canvas
 - Voice, rhythm, and sentence construction in any text a frame shows: the `write-human` skill
@@ -59,6 +62,19 @@ A canvas failing these is non-conforming even when it satisfies every shape rule
 - Use the project's custom properties, `var(--<name>)`, for every value the token stylesheet defines. A literal copied from it shows the right color today and the wrong one after the next token change.
 - Edit a frame by rewriting its file. The file is the frame, and nothing else holds a copy of its markup.
 
+## House style
+
+Applies to an explanation frame only. A mockup of the project's interface renders at the app's own sizes and follows the project's design document instead.
+
+- Write text in sentence case. Use no all-caps text and no `text-transform: uppercase`.
+- Keep lines short, one fact a line.
+- Set body text at 20px or larger and headings at 44px or larger. Set nothing under 16px.
+- Render an explanation frame about 1100px wide.
+- Take colors from the project's custom properties. A frame that defines colors of its own sets the dark values on `:root` and the light ones under `[data-theme="light"]`, since the shell sets `data-theme` on each frame's root.
+- Name only the faces the canvas serves into every frame: `Geist Variable` for text, `Noto Sans Mono` for code, and `Excalifont` for a hand-drawn look. They render the same in a capture and in any browser, so a height fitted against them holds.
+- Make each box tall enough to show all its content, with no scrollbar and no clipped line. Run `canon canvas fit <page>/<frame>` rather than estimating, since it measures the content in the capture browser and sets the height.
+- Read frames left to right in reading order. Let `frame add` place each frame after the last with the standard gap, and move one only when the operator asks for a position.
+
 ## Layout
 
 - Keep one `layout.json` per page, beside its frames. It holds each frame's box and nothing else, so moving a frame never rewrites its markup.
@@ -89,8 +105,8 @@ The keys below are the ones a reader parses. The frame names are placeholders.
 
 - Do not assume a viewport. A frame renders at its layout width on the canvas and in a capture alike, so size it with media queries against that width rather than against the operator's window.
 - Do not assume the theme. The canvas theme toggle is the operator's own state, and a capture shows each frame in its default theme.
-- Do not assume a network. Name only fonts the machine has, or ship the font beside the frame, since a capture refuses a frame naming a font it cannot find.
-- Do not assume a default font. Set `font-family` with an installed family first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines.
+- Do not assume a network. Name a served face, or ship the font beside the frame, since a capture refuses a frame naming a font it cannot find.
+- Do not assume a default font. Set `font-family` with a served face first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines. A frame naming a machine family such as `DejaVu Sans` renders at another height in another browser, which `canon canvas fit` reports.
 - Do not assume the frame is the source. A picked direction is carried into the project's design document or a plan, and the operator clears the frame once it has been carried.
 - Do not assume the canvas survives the checkout. The folder is gitignored, so a lost checkout loses every page in it.
 
@@ -113,6 +129,13 @@ A new frame starts from this skeleton. The names in it are placeholders.
         color: var(--color-text);
         background: var(--color-background);
       }
+      /* only a color the frame defines itself: dark on :root, light here */
+      :root {
+        --frame-accent: #7aa2ff;
+      }
+      [data-theme='light'] {
+        --frame-accent: #1f4fd8;
+      }
     </style>
   </head>
   <body>

package/{standards → claude/skills/canvas-board/references}/design.md

@@ -1,14 +1,23 @@
 ---
 title: Design reference
 description: Shape and content rules for canon/DESIGN.md
-paths:
-  - 'canon/DESIGN.md'
 ---
 
 # Design reference
 
 Applies to `canon/DESIGN.md`. Captures visual intent and the decisions behind how things look, not a style guide, component spec, or framework reference. Update when a visual decision is made or a rule changes.
 
+## Contents
+
+- [Scope](#scope)
+- [What goes in](#what-goes-in)
+- [What does not go in](#what-does-not-go-in)
+- [Format](#format)
+- [Prose budget](#prose-budget)
+- [The uncertainty tag](#the-uncertainty-tag)
+- [Sections](#sections)
+- [Template](#template)
+
 ## Scope
 
 Governs the visual-intent document at `canon/DESIGN.md`: tokens described as intent, layout constraints, and the omissions that keep visual scope closed.

package/claude/skills/code-craft/REQUIREMENT.md

@@ -30,7 +30,7 @@ Before this skill, two shipped pointers left interface depth unowned. `api-desig
 - State a tension as one side only, such as "never duplicate"
 - Name a language, a framework, or a type system feature in the body
 - Restate the red, green, refactor loop `test-first` runs, or the design review procedure `review-craft` carries for a finished diff
-- Restate the error and naming bullets of the core code rule
+- Restate error or naming bullets. The core code rule retired them on purpose, and the error shape lives in `api-design`.
 
 ## Guards
 

package/claude/skills/code-craft/SKILL.md

@@ -106,4 +106,3 @@ Check each line against the code the change produced. A line answering no is fix
 - Which layer a test belongs at: `test-craft`
 - The contract a caller depends on, being its exports, flags, output, and errors: `api-design`
 - Judging a finished diff, including a design review of it: `review-craft`
-- The error and naming floors every code stack loads: `000-code`