@erclx/canon 4.82.0 → 4.84.0

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

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

package/claude/skills/docs-fold/REQUIREMENT.md

@@ -17,6 +17,8 @@ The receipt half of that sweep was missing entirely. A review receipt was delete
 
 The trigger side carries a gap of its own. "Sync the docs" names either corpus to the person saying it, so a description leaving its corpus to the opening clause alone competes with its public-facing sibling on nothing the routing field states, and the planning surface the request was about goes untouched.
 
+This skill writes canonical docs at the end of a long build and never reviews what it wrote. An appended figure or a branch-narrated re-measurement lands unchecked the same way a session's own edits do, so what the fold produces carries the exact defect the standards it cites already ban.
+
 ## Must
 
 - Name the `.claude/` corpus in a trigger phrase rather than in the opening clause alone, so a bare request to sync the docs separates this skill from `docs-sync` on something both descriptions state
@@ -34,6 +36,10 @@ The trigger side carries a gap of its own. "Sync the docs" names either corpus t
 - Leave the current branch's review receipt alone, since the chain that wrote it cites it in its own closing line and this skill cannot read whether that citation is still live
 - Land each block of a promotion handoff at the destination its heading names, then delete the file so a later run does not fold it twice
 - Take a promotion destination as already decided, since the operator confirmed it where the page was produced
+- Classify the fold's whole diff baseline through `canon context classify diff`, calling the verb rather than reimplementing its pattern or its prompt in the skill body, since an earlier commit on the branch carries a doc edit the fold is equally responsible for
+- Apply a `REPLACE` or `HISTORY` finding, and a regex-decided `MOVE` finding, against the quote it names, report a model-decided `MOVE` finding naming the surface it belongs on rather than cutting it, or keep a finding with a one-line reason, rather than leaving a finding unanswered
+- Rewrite a restated or superseded statement in place rather than appending the replacement beside it, on every canonical doc type this skill writes
+- Report a refusal or a missing `context classify` subcommand as one line and continue the fold either way, since a check that cannot run is not a reason to leave the fold's own output unshipped
 
 ## Must not
 
@@ -45,6 +51,13 @@ The trigger side carries a gap of its own. "Sync the docs" names either corpus t
 - Overwrite a file a promotion block routes to. A destination that already holds a page is a merge for a person, and folding over it discards work this skill never read.
 - Write an anchor onto a decision the run did not amend, or refresh one without re-reading the number. A date from a pass that measured nothing is the false confidence the marker exists to prevent.
 - Anchor an entry written before the rule, which dates it by blame rather than by a read
+- Pick or configure a classifier backend. The project setting decides it, and this skill reports the resolved `modelLayer` as returned.
+- Stop the fold on a classify finding, a refusal, or a missing subcommand. All three report and continue.
+- Apply a finding against a quote found more than once or not found at all. Report that it could not be located instead of guessing.
+- Re-run the classifier after applying a finding, which loops it over its own edit
+- Cut a model-decided `MOVE` finding. The model's own prompt defines `MOVE` more broadly than the regex layer does, for correct content sitting on the wrong surface rather than a deletion candidate, so cutting one can discard content that belongs elsewhere rather than removing detail that never belonged at all.
+- Paste a regex-decided `MOVE` finding's content into another canonical doc after cutting it. It never belonged on the wireframe surface at all, so cutting is the whole fix, not a relocation.
+- Scope Step 10 to the files Steps 3 and 7 wrote this run. An earlier commit on the branch carries a doc edit the fold is equally responsible for, and the verb's own extraction already answers whether anything in range qualifies.
 
 ## Guards
 

package/claude/skills/docs-fold/SKILL.md

@@ -108,6 +108,7 @@ Read `ok` and `reason` out of that record rather than the exit. An operator's sh
 
 - Update only the sections affected by session decisions.
 - Do not rewrite sections unrelated to what changed.
+- Rewrite a restated or superseded statement in place rather than appending the replacement beside it. State the fact that stands and keep the earlier reasoning only where it is the alternative that lost, per `${CLAUDE_SKILL_DIR}/../../standards/context.md` and `${CLAUDE_SKILL_DIR}/../../standards/architecture.md`.
 - Follow `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` and the `write-human` skill for all edits.
 - Close a decision entry in `canon/ARCHITECTURE.md` with its verification anchor whenever this run writes that entry or amends its reasoning and that reasoning cites a measured number. Re-read the number against the tree first, since the marker records the read rather than the edit. `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` fixes the sentence.
 - Leave every decision entry this run did not write alone, anchored or not. The rule is scoped forward, so an entry written before it is dated by blame rather than by a read. Step 5 reports a stale anchor and no step writes one on an entry it did not amend.
@@ -160,6 +161,7 @@ Reuse the diff from the baseline above, names and content both. For each domain
 
 - Map the entry's section headings, whether they sit in one flat file or spread across a nested domain's sibling files, to the changed files. An entry is relevant when its prose references files, modules, or decisions touched by the diff.
 - For each relevant entry, rewrite only the sections affected by the diff. Same pattern as `docs-sync`. Do not touch unrelated sections. Never rewrite a split domain's own `index.md` directly, since a regen overwrites it the same way it overwrites the top-level catalog. Rewrite the sibling file the affected section actually lives in instead.
+- Rewrite a restated or superseded statement in place rather than appending beside it, the same rule Step 3 applies to the other four canonical doc types.
 - Write a reference to another entry as the path that entry sits at, rather than as its bare filename. `${CLAUDE_SKILL_DIR}/../../standards/context.md` states the form, and a bare name strands the reference once a domain splits into subfolders.
 
 ### When the diff removes a capability
@@ -245,12 +247,30 @@ Output one line per file swept:
 
 If nothing qualifies, skip this step silently.
 
+## Step 10: classify the fold's diff baseline
+
+Skip this step silently only when the Diff baseline section could not resolve a base ref at all, reporting `⚠ No diff to scope against. Skipped the classify check.` The verb needs a resolvable ref to run against, which is the one condition it cannot answer for itself.
+
+Otherwise resolve `<base>` the way the Diff baseline section already does for Steps 2, 4, 5, and 7, and reuse it rather than resolving a second time. Run the check over the fold's whole baseline rather than scoping it to what Steps 3 and 7 wrote this run: earlier commits on the branch carry doc edits the fold is equally responsible for, and the verb's own extraction already scopes to canonical doc types and reports nothing when the range carries none.
+
+The invocation is:
+
+```bash
+canon context classify diff --base <base> --json
+```
+
+Never substitute a different verb for it, such as `canon autoship classify` (a different check, over a different scope) or `canon docs <name>` (a documentation lookup, not a classification). Read `${CLAUDE_SKILL_DIR}/references/classify.md` for the record fields, applying a finding, the one-line keep reason, the unreachable and missing-subcommand lines, and the report shape. `${CLAUDE_SKILL_DIR}` names this skill's own directory, resolved once when the skill loaded, several steps before this one. If Step 10's memory of that path is uncertain, read the reference by that resolved path rather than guessing a `.claude/skills/docs-fold/references/classify.md` path from the toolkit's install-time layout, which is a different root than the one this skill's own files live under. The invocation above runs either way, whether or not that reference resolves.
+
+Findings never stop the fold. A refusal or a missing subcommand on an older installed binary reports one line, per that reference, and the fold continues either way.
+
 ## After completion
 
 Output one line per file updated:
 
 `✅ Updated: .claude/<filename>`
 
+Step 10 adds its own lines when it applied or reported a finding, in the exact shape `${CLAUDE_SKILL_DIR}/references/classify.md` gives them under its own Report section. Do not shorten or paraphrase those lines here or in the reply, since the quote and the reason are what a reader checks the finding against.
+
 If no files were updated and nothing was swept, output:
 
 `✅ No changes needed.`

package/claude/skills/docs-fold/references/classify.md

@@ -0,0 +1,78 @@
+---
+title: Classify the fold's diff baseline
+description: The classify diff invocation, the record fields to read, applying a finding, the one-line keep reason, the unreachable and missing-subcommand lines, and the report shape
+---
+
+# Classify the fold's diff baseline
+
+Mechanics for Step 10 of `docs-fold`. The body owns the skip condition and the shared baseline, and this file owns the invocation, what the record carries, and what applying a finding does.
+
+## Invocation
+
+Call the verb rather than reimplementing its pattern or prompt in this skill:
+
+```bash
+canon context classify diff --base <base> --json
+```
+
+Reuse the base the Diff baseline section already resolved. Never pick or configure a backend here. The project setting decides it, and this step reports `modelLayer` as the record returns it.
+
+## Reading the record
+
+Branch on the record's `decision` field, never on the exit code, which a shell function wrapping `canon` can flatten to zero.
+
+- `decision: 'refused'`: a bad range or a file the verb could not read. Report the record's `message` and continue. See "When the verb is absent or refused" below.
+- `decision: 'ok'`: the record carries `modelLayer` (`'off'`, `'ran'`, `'skipped-no-model'`, or `'skipped-unreachable'`) and `findings`.
+
+Each finding carries `file`, a `verdict` of `KEEP`, `REPLACE`, `HISTORY`, or `MOVE`, and `decidedBy` (`'regex'` or `'model'`) naming which layer's reading won. Take the `quote` and `reason` from whichever of the finding's `regex` or `model` fields `decidedBy` names. Skip every `KEEP` finding: nothing decided against that text.
+
+## Scope
+
+Answer every non-`KEEP` finding the verb returns, not only the files Step 3 or Step 7 wrote this run. A branch carrying earlier commits from a prior session has doc edits the fold is equally responsible for, and the verb's own extraction already scopes to canonical doc types and reports nothing when the range carries none, so there is no narrower check to add here.
+
+## Applying a finding
+
+Locate the finding by its `quote` in the file's current content. The quote is often a narrow fragment rather than the whole clause it sits in, since the regex layer's own match is a short pattern hit, so the edit below targets the sentence or bullet the quote sits in rather than the literal substring alone.
+
+- **Found exactly once.** Apply the verdict:
+  - `REPLACE`: rewrite the sentence or bullet carrying the quote in place with the fact that now stands, per Step 3 and Step 7's rewrite-in-place rule. State what is current and drop what the quote restated, in the one edit.
+  - `HISTORY`: rewrite the sentence or bullet carrying the quote to drop the narration and keep any current fact the same clause states. The quote narrates how the fact arrived rather than stating the fact, which a canonical doc excludes regardless of what wrote it, and a literal cut of the fragment alone would leave the rest of the clause grammatically stranded.
+  - `MOVE`, regex-decided (`decidedBy: 'regex'`): cut the sentence or bullet carrying the quote and stop there. Do not also paste it into another canonical doc, however close a match the current diff makes one look. The regex layer only ever returns `MOVE` inside `canon/wireframes/`, on prose naming a source-file path, which is implementation detail a wireframe surface does not carry, so a regex-decided `MOVE` is always safe to remove outright, and removing it is the whole fix.
+  - `MOVE`, model-decided (`decidedBy: 'model'`): do not cut. The model's own prompt defines `MOVE` more broadly, for correct content sitting on the wrong surface, such as domain mechanism written into `canon/ARCHITECTURE.md` that belongs in a context entry. Cutting would delete content a fold with no model configured would never have flagged at all. Report the finding instead, naming the surface the `reason` names as where the content belongs, and leave the file unedited.
+- **Found more than once, or not found at all.** Report that the finding could not be located rather than guessing which occurrence or rewriting nothing silently. A model verdict paraphrasing the quote it read is the ordinary way this happens.
+
+Run the classifier once per fold. Do not re-run it after applying a finding to check the edit, since a second pass over what this step wrote is the loop the verb's own reference already warns against.
+
+## Keeping a finding
+
+Keep a non-`KEEP` finding without applying it only when the quote is itself the alternative a nearby decision states and lost, or the file already carries the current fact elsewhere. State the reason in one line in the report. A keep costs one line, where an incorrect apply costs a rewrite of prose nobody asked to change.
+
+## When the verb is absent or refused
+
+The verb ships with the CLI and this skill ships with the plugin, so a target holding an older installed binary carries no `context classify` subcommand. Report:
+
+`⚠ Classify: canon context classify not available on the installed binary. Skipped.`
+
+and continue. Never read a missing subcommand as a clean pass, which would report a run that never checked anything as one that found nothing.
+
+A refused range reports the same way, naming the verb's own message:
+
+`⚠ Classify: <message>`
+
+Neither case stops the fold. This step checks what the fold wrote, and a check that cannot run is not a reason to leave the fold's own output unshipped.
+
+## Report
+
+One line naming what ran:
+
+`✅ Classify: <n> findings, regex ran, model <modelLayer>`
+
+Then one line per non-`KEEP` finding:
+
+- `✏ Rewrote: <file>, "<quote>" (<reason>)`
+- `✂ Cut: <file>, "<quote>" (<reason>)`
+- `➡ Move needed: <file>, "<quote>" (<reason>)`, for a model-decided `MOVE` this step reported rather than cut
+- `⏭ Kept: <file>, "<quote>", <reason for keeping>`
+- `⚠ Not located: <file>, "<quote>" not found or found more than once`
+
+When every finding reads `KEEP`, output `✅ Classify: <n> findings, all KEEP` and nothing further.

package/claude/skills/draft-and-pick/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: draft-and-pick
-description: Drafts several candidates for a decision judged by looking, renders them side by side on one page, hands the operator the addresses, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `plan-feature`. Do NOT use to read source for roughness, which is `ux-audit`, to measure what a running interface costs to paint, which is `ux-measure`, to write tests for a change already made, which is `ui-test`, or to script a recording, which is `draft-screencast`.
+description: Drafts several candidates for a decision judged by looking, renders them side by side on one page, hands the operator the addresses, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `plan-feature`. Do NOT use to read source for roughness, which is `ux-audit`, to measure what a running interface costs to paint, which is `ux-measure`, to write tests for a change already made, which is `ui-test`, to script a recording, which is `draft-screencast`, or to inspect a running app across many findings, which is `ux-walkthrough`.
 ---
 
 # Draft and pick

package/claude/skills/draft-slides/SKILL.md

@@ -50,7 +50,7 @@ Pass `--variant light` or `--variant dark` to override the source variant for a
 Run this once after the first render, then stop.
 
 1. Convert the deck to images: `soffice --headless --convert-to pdf <deck>.pptx` then `pdftoppm -r 90 -png <deck>.pdf slide`. If `soffice` or `pdftoppm` is missing, skip the image pass and say so. Do not fail the render.
-2. Inspect the images with fresh eyes. Spawn a subagent to check every slide for overlap, overflow, low contrast, and empty regions.
+2. Open and inspect every rendered image in this session, checking each slide for overlap, overflow, low contrast, and empty regions.
 3. Fix the reported issues in `SLIDES.md` once, re-render, and stop. Do not loop indefinitely on aesthetics.
 
 ## Response

package/claude/skills/draft-wireframes/REQUIREMENT.md

@@ -11,7 +11,7 @@ Without this skill, a session drafting a wireframe for a surface with no file ye
 
 ## Must
 
-- Read `standards/wireframes.md` before drafting, since the frontmatter contract, the layout and variant rules, and the Transcription-wireframes branch are what make the file arguable against a sibling
+- Read `standards/wireframes.md` before drafting, since the frontmatter contract, the regions list, the states table, the exclusions section, and the Transcription-wireframes branch are what make the file arguable against a sibling
 - Walk the whole `canon/wireframes/` tree, including a grouped surface's own subfolder, before drafting, since a top-level-only check misses a nested match
 - Detect an existing higher tier from `canon/DESIGN.md` and the wireframes tree and report it, never build a companion render for it, since no shipped mechanism produces one
 - Draft in transcription mode, citing the real source, when the surface names an already-built component. Draft in role-intent mode otherwise.

package/claude/skills/draft-wireframes/SKILL.md

@@ -11,7 +11,7 @@ A project the surface move has not reached keeps its wireframes folder under `.c
 
 Read these files in parallel:
 
-- `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`: the three questions a wireframe must answer, its frontmatter, layout and variant rules, the Transcription-wireframes branch, and what moves to a context entry instead
+- `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`: the four questions a wireframe must answer, its frontmatter, the regions list and states table, the exclusions section, the Transcription-wireframes branch, and what moves to a context entry instead
 - `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for the prose around the fences
 - The `write-human` skill: voice, rhythm, and sentence construction for the prose around the fences
 
@@ -25,15 +25,18 @@ This skill stays fully independent of `docs-fold`'s wireframe coverage sweep, wh
 ## Tier detection
 
 - Read `canon/DESIGN.md` and every existing `canon/wireframes/` file for a tier signal: a Stitch, Excalidraw, or Figma reference, or a marker naming one of them.
-- State the detected tier at the confirm step. Always draft the tier-0 ASCII file regardless of what is detected, since that is the only shape this skill or any other shipped mechanism produces. Report a higher tier rather than attempting a companion render for it.
+- State the detected tier at the confirm step. Always draft the regions-and-states shape regardless of what is detected, since that is the only shape this skill or any other shipped mechanism produces, adding the ASCII sketch fence only when the layout is not built yet. Report a higher tier rather than attempting a companion render for it.
 - Default silently to tier 0 when nothing is detected.
 
 ## Draft
 
 - Decide the mode before drafting. When the surface names an already-built component or file, open that source and draft in transcription mode, citing the render function, the stylesheet rule, or the built file each region and label traces to, per the standard's Transcription-wireframes section.
 - Draft in role-intent mode otherwise: label each region by its role, never by a class name or a token value.
-- Draft `title` and `description` frontmatter, then one `##` heading per layout variant, each holding its own ASCII `plaintext` fence with `←` role annotations, followed by `## Copy` and `## Behavior` sections against `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`'s template.
-- Add a second layout variant only when the layout itself changes across a breakpoint or state, never for a spacing difference alone.
+- Draft `title` and `description` frontmatter, then a lead paragraph naming what the surface is for and what it covers, then `## Regions` as a bullet list naming every region and where it sits relative to the others.
+- Draw an ASCII `plaintext` fence with `←` role annotations only when the layout is not built yet. Skip the fence in transcription mode, which already cites the built source instead.
+- Draft `## States` as a table listing every state a visitor can reach, what reaches it, what it shows in words, and its evidence folder, reading `not captured` in the evidence cell until a capture lands.
+- Follow with `## Copy`, `## Behavior`, and `## Not on this surface`, against `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`'s template.
+- Give a layout that changes across a breakpoint or state its own entry in the regions list, named by what triggers it, never for a spacing difference alone.
 - Leave out algorithms, event-handler code, framework prop or class names outside transcription mode, and anything else the standard sends to a context entry instead.
 
 ## Confirm

package/claude/skills/ux-walkthrough/REQUIREMENT.md

@@ -0,0 +1,53 @@
+---
+name: ux-walkthrough
+description: Why a multi-finding inspection walkthrough with the operator needs its own surface beside draft-and-pick, and where the boundary against building and auditing falls
+---
+
+# UX walkthrough requirement
+
+## Gap
+
+Without this skill, a session running an inspection walkthrough with the operator:
+
+- Files every round's evidence into one flat shared folder, so nothing shows which walkthrough a folder came from or in what order the rounds ran.
+- Hands over screenshots or file paths the operator cannot open, where a served localhost page is the one form that reaches them.
+- Asks the pick question before the operator has the page, so the answer is taken from a description.
+- Sends the link inside the same message as the question, where the structured question surface draws over it and the operator never sees the link.
+- Draws arms as hand-written mock-ups of the app, which drift a few pixels and a few words from what ships, rather than lifting the built page's own markup and stylesheet.
+- Measures the mark and not the text inside it, or the gap and not what shows above it, so a pick ships with half its condition unchecked.
+- Quotes figures in a pick question from memory, and records them without reading the computed values back.
+- Relays each pick as it is taken when the operator wants picks batched on their own call.
+- Serves a rebuilt export from a server whose working directory was deleted by the rebuild, and measures a page that is not there.
+- Applies a pick to the tracked tree, or deletes the candidate pages, because the single-decision loop it borrowed does both.
+- Leaves findings, numbers and build criteria in chat, so whoever files the work does it from a summary rather than from a record.
+
+## Must
+
+- Record conditions, findings with their measurements, picks with the arms they beat, evidence paths and build criteria in one walkthrough file under `.canon/walkthroughs/`.
+- Measure each finding off the built page before drafting any arm.
+- Build candidate pages from the app's rendered markup and built stylesheet, with a theme toggle, served on localhost.
+- Capture every arm in every theme the app ships to its walkthrough's own evidence folder, and look at the captures before handing the link over.
+- Number the walkthrough folder and each round's folders so they sort in the order they ran, and let a round's number match its finding's.
+- Send the localhost link in its own message, ending the turn, before every pick question is asked.
+- Hold picks and relay them only when the operator calls a batch, as one message, to the controller where one exists and to the operator otherwise.
+- Route a finding with no visible choice into the batch as a proposed row rather than drafting arms for it.
+
+## Must not
+
+- Change a tracked file, create a branch or commit, or file a task row.
+- Apply a winning arm or delete the evidence.
+- Draft arms for a finding the operator has not raised.
+- Restate `draft-and-pick`'s arm rules or the `canon capture` and `canon serve` mechanics.
+- Fire on a request naming one decision alone, which `draft-and-pick` covers.
+- Review criterion, not a gate: whether anything other than the operator or a controller's launch brief invokes this skill, and which lines a second project found in its way. Read both back after it has run outside the project it was written in.
+
+## Guards
+
+The refusal strings sit in the body. Two conditions stop a run: no build to measure against, and a request to change a tracked file.
+
+## Out of scope
+
+- `draft-and-pick` runs one decision end to end and applies it. This runs many decisions and applies none.
+- `ux-audit` reads source for roughness. This takes its findings from what the operator saw.
+- `plan-feature` and a worker build a pick. This stops at the record and the batch.
+- The controller, or the operator where none exists, decides rows, order and pull request boundaries. This proposes and does not file.

package/claude/skills/ux-walkthrough/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ux-walkthrough
+description: Runs an inspection walkthrough over a running app with the operator. Measures each finding off the built page, drafts arms as served HTML pages lifted from the app's own markup and stylesheet, hands over the localhost link before every pick question, records findings and picks with the arms they beat in one walkthrough file, and relays picks only in batches the operator calls. Use when asked to "run a first-use walkthrough", "do an operator walkthrough", "go through my findings one by one", "inspection walkthrough over the app", or "walk through everything I listed with me". Do NOT use for one decision on its own, which is `draft-and-pick`, to read source for roughness, which is `ux-audit`, or to build a pick, which is `plan-feature` and a worker.
+---
+
+# UX walkthrough
+
+A walkthrough turns what the operator sees in a running app into findings and picks a builder can act on without the conversation. The render is the decision and the record carries the measurements, so every pick here is taken by looking and written down with the numbers behind it.
+
+## Guards
+
+- If no running build or build command exists to measure against, stop: `❌ Nothing to inspect. A walkthrough measures a running build.`
+- If the session is asked to change a tracked file, stop and route it: `❌ A walkthrough records and does not build. Hand the pick to whoever dispatches the build.`
+- Draft no arm for a finding the operator has not raised or agreed to take up.
+
+## Posture
+
+- Write only under `.canon/`, never a tracked file, and create no branch, commit or task row.
+- Stay in the checkout the session started in. Enter no worktree for a walkthrough, since nothing it writes is tracked.
+- Read the `walkthrough.md` of every earlier walkthrough under `.canon/walkthroughs/` first, and raise nothing they already decided.
+- Name every folder a walkthrough writes with a two-digit prefix, per `${CLAUDE_SKILL_DIR}/references/record.md`, so the walkthrough and its rounds sort in the order they ran.
+- Put builds, generator scripts and logs in a scratch folder outside the tracked tree, and anything the operator opens under `.canon/tmp/`.
+
+## Steps
+
+1. **Bring up both builds and record the conditions.** Follow `${CLAUDE_SKILL_DIR}/references/builds.md`. Start the walkthrough file with the commit, the ports and the build commands before the first finding.
+2. **Take the operator's list in their order.** Name each item as a finding with the walkthrough letter and a number, such as T1, and confirm the order once rather than per item.
+3. **Measure before drafting.** Read the component behind the finding and pull the numbers off the built page, per `${CLAUDE_SKILL_DIR}/references/measuring.md`. Write the finding into the walkthrough file with those numbers before any arm exists.
+4. **Route a finding with no visible choice.** A parse defect, a stale figure or a broken invariant gets recorded as a finding with no draft and goes into the batch as a proposed row, not as a pick.
+5. **Draft three or four arms.** Follow `draft-and-pick` Steps 1 and 2 for the arms, with arm 0 the shipped state, one property varied and a cost on each. Build the page from the app's own rendered markup, per `${CLAUDE_SKILL_DIR}/references/candidate-pages.md`.
+6. **Look before handing anything over.** Capture every arm in every theme the app ships into `.canon/walkthroughs/<nn>-<slug>/evidence/<nn>-<slug>/`, with the finding's number as the prefix, open the captures, and fix what rendered wrong before the operator sees the page.
+7. **Hand the link, then ask.** Emit `http://localhost:<port>/<nn>-<slug>/candidates.html` in a message that ends the turn, confirmed with a `200`, carrying no question. Take any reply after that message as the operator having looked, an explicit "go" included, rather than holding for a stated confirmation, and only then put the choice through the structured question surface with the recommendation first.
+8. **Record the pick.** Write what won, what it beat and by which numbers, where the evidence is, and the build criteria, per `${CLAUDE_SKILL_DIR}/references/record.md`. Read every figure you quote back from the page or the data file first, and correct the record where the question quoted one wrong.
+9. **Hold picks for the batch.** Relay nothing per pick. When the operator calls the batch, send it once per `${CLAUDE_SKILL_DIR}/references/relay.md`.
+10. **Close on the operator's word.** Add the walkthrough summary table and the handoff, leave the evidence in place, and report every file written by its path.
+
+## Rules
+
+- Answer a question the operator asks mid-walkthrough in prose first, with a recommendation, and offer a draft rather than drafting unasked.
+- Say when a pick revises an earlier walkthrough's pick, and record it as a revision naming the pick it revises.
+- Check a claim against the code or the data before an arm makes it, since an arm drawn on a wrong fact is a pick on nothing.
+- Measure both halves of a pick whose condition has two, such as a gap and what shows above it.
+- Keep a finding's measured numbers and the pick's build criteria in the record, never only in chat.
+
+## What this delegates
+
+- `draft-and-pick` owns the arm discipline and the structured question. This walkthrough departs from its Step 2 inlining and its Step 6 apply and delete, for the reasons `${CLAUDE_SKILL_DIR}/references/candidate-pages.md` states.
+- `write-human` carries the voice of every recorded passage and any copy an arm puts in front of a reader.
+- `plan-feature` and whoever dispatches builds turn a batch into plans and code.
+- `canon capture`, `canon serve` and `canon sessions list` own the render, the address and the roster.

package/claude/skills/ux-walkthrough/references/builds.md

@@ -0,0 +1,15 @@
+# Builds and servers
+
+Read when bringing the app up at the start of a walkthrough, and whenever a measurement returns nothing it should.
+
+## Bring up
+
+- Run the live build and whatever service it calls from the checkout the session started in, and record the commit, ports and any state that changes a reading as the walkthrough file's conditions.
+- Build the artifact the deploy ships in a scratch folder outside the tracked tree, so a build never touches the project.
+- Serve that artifact the way the host resolves it. A plain file server can answer a clean route the host rewrites with a 404, such as `/about` for `about.html`.
+- Rebuild from the current main whenever main moves mid-walkthrough, and say so in the record. Measuring a stale build reports on code that no longer ships.
+
+## Traps
+
+- Restart a server after rebuilding what it serves. A server started inside an output folder the rebuild replaced keeps serving a deleted directory, and every selector comes back empty.
+- Note what a build cannot show, such as live timing a recorded build does not carry or recompile pauses a dev server adds. Neither is a finding.

package/claude/skills/ux-walkthrough/references/candidate-pages.md

@@ -0,0 +1,26 @@
+# Candidate pages
+
+Read when drafting arms for a finding. Skip it for a finding with no visible choice.
+
+## Build from the app
+
+- Dump the rendered markup of the surface under test from the built page, after it has loaded, into a JSON file in scratch. Strip scripts from the dump.
+- Copy the built stylesheet and font files under `.canon/tmp/`, at the path the dumped markup links them from, so a candidate page renders with the stylesheet the app ships. Every arm then differs from the shipped page only by what the arm names.
+- Trim a large dump to the part the finding needs, and keep the wrapper classes intact so layout rules keyed to them still resolve.
+- Size each frame to the content width the finding names rather than the window width, since a container query reads the frame.
+- Write copy an arm introduces with `write-human`, and take every other word from the dump.
+
+## The page
+
+- Generate the page with a short script, one per round, so a shared change is one edit and a rerun.
+- Put a theme button on the page that flips the app's own theme switch on the root, rather than drawing each frame once per theme. Read `?arm=<id>&theme=<name>` to strip every other arm and the button for capture. Skip the button for an app that ships one theme.
+- Print each frame's measurement under it from a script in the page, so the numbers the operator reads are the browser's.
+- Write an index page linking one page per arm when an arm is a whole page or a route rather than a frame, with thumbnails copied beside it.
+- Name anything the preview cannot reproduce, such as an asset whose colors follow the browser rather than the page's theme button, rather than fixing the page around it.
+
+## Where this departs from draft-and-pick
+
+- Capture into the walkthrough's own numbered evidence folder instead of the folder `draft-and-pick` Step 6 archives arms into, per `${CLAUDE_SKILL_DIR}/references/record.md`.
+- Link the app's built stylesheet instead of inlining every asset. Lifted markup needs the real stylesheet, and an inlined copy is the drift this avoids.
+- Keep `candidates.html` and never apply the winning arm. The walkthrough records and a build applies.
+- Leave `.canon/tmp/<nn>-<slug>/` in place until the picks are built, and never delete the round's evidence folder.

package/claude/skills/ux-walkthrough/references/measuring.md

@@ -0,0 +1,22 @@
+# Measuring
+
+Read before writing a finding and before recording a pick.
+
+## Off the page
+
+- Measure on the built page in a real browser at the widths the finding names, in every theme the app ships, and record the viewport.
+- Read computed styles rather than class lists. A class list names intent, and the computed value is what paints.
+- Measure text contrast against the ground it sits on, and a mark's contrast against its own ground, as two numbers. A mark that sets a background and no text color inherits the browser default, and only the text reading catches it.
+- Measure empty space by text extent, the union of each text node's client rects, rather than by leaf element boxes. A block element spans its row whatever its text covers.
+- Measure a landing by the landed element's top against the bar's bottom edge and by whether the element before it is visible. A pick with a two-part condition needs both readings.
+- Reproduce the shipped value inside the candidate page before trusting an arm's numbers. Arm 0 reading the same as the live page is what shows the page matches.
+
+## Off the data
+
+- Re-derive a figure from the data file that produced it rather than from any document quoting it. Two documents can disagree, and neither is the source.
+- Count a defect across the whole corpus or tree before recording its size, and say whether it sits only at the end, only in one version, or throughout.
+- Test a proposed fix without editing code where the question is its effect, by patching the function in a throwaway script and comparing before and after on counts the fix could move.
+
+## Before quoting
+
+- Read every figure a pick question or a record quotes back from the page or the script that computed it. Correct the record in place when the question quoted one wrong, and say so.

package/claude/skills/ux-walkthrough/references/record.md

@@ -0,0 +1,36 @@
+# The walkthrough record
+
+Read when starting the walkthrough file, recording a finding, and recording a pick.
+
+## File
+
+- Write to `.canon/walkthroughs/<nn>-<slug>/walkthrough.md`, with `<nn>-<slug>` the walkthrough's own folder.
+- Open with one paragraph naming the walkthrough, the date, the commit and what landed since the last walkthrough, then `## Conditions`, `## Findings`, `## Picks`, `## Walkthrough summary` and `## Handoff`.
+- Number findings with one letter per walkthrough and a counter, and never reuse a number.
+
+## Folder names
+
+- With no earlier walkthrough on this topic, a fresh folder takes the next ordinal in `.canon/walkthroughs/`'s own sequence: list the folders present, take the highest `<nn>`, and increment it, starting at `01` when none exist.
+- Put a round's captures at `.canon/walkthroughs/<nn>-<slug>/evidence/<nn>-<slug>/` and its candidate pages at `.canon/tmp/<nn>-<slug>/`, where the inner `<nn>` is the finding's own number, so T1's folders start `01-`.
+- Leave a gap where a finding has no draft. The missing number is what maps each folder to its entry in the record.
+- Take `<slug>` from the decision sentence the way `draft-and-pick` Step 1 derives it, and add only the prefix.
+- Rename no folder from a walkthrough that predates this rule. Tracked documents cite those paths, and a rename breaks every citation.
+
+## A finding
+
+- Head it `### T<n>: <what is wrong, as a claim>`.
+- State what the operator saw, the code behind it by path and line, and the measurement in a table when it has more than two readings.
+- Name an earlier pick the finding revises, and a collision with work in flight.
+
+## A pick
+
+- Head it `### Pick <n>, T<n>: arm <id>, <what won>`.
+- One paragraph on what the arm does and its measured result, then `It beat:` with one bullet per losing arm and the number that lost it.
+- One `Evidence:` line naming the evidence folder and its file set.
+- `Build criteria:` as bullets a builder checks against the built page, each measurable, including what the render shows that the prose does not.
+- An answer to a question the operator asked with the pick goes under the criteria, stated as a decision with its reason.
+
+## Close
+
+- `## Walkthrough summary` is one table row per finding: the finding, the pick, and the arms it beat.
+- `## Handoff` proposes how the picks split into pull requests by the files each writes, and names shared files and the order they force.

package/claude/skills/ux-walkthrough/references/relay.md

@@ -0,0 +1,25 @@
+# Relaying picks
+
+Read when the operator calls a batch, and at the start of the walkthrough when a launch brief asks for collisions.
+
+## Where the batch goes
+
+- Send it to the controller where the session was dispatched by one, resolved per the Channel rule, matched by name through `canon gov list --rules --json` rather than a path a target may not have installed.
+- Give it to the operator as one list in the conversation where no controller exists. The walkthrough file is the handoff either way.
+
+## When
+
+- Relay nothing per pick. Relay once when the operator calls the batch, covering every pick held since the last one.
+- Put a finding with no visible choice in the same batch, as a proposed row.
+
+## The message
+
+- Open with one line saying what the batch holds and where the record is.
+- Give each pick its finding, the arm, the numbers that decided it, the arms beaten, and the files it writes.
+- Close with overlaps and order: files two picks share, picks that must follow another, and collisions with open pull requests or unmerged branches.
+- Name anything the operator holds that is not a row, such as a repository setting.
+
+## Collisions
+
+- List open pull requests with their files, and unmerged remote branches with `git diff --stat origin/main...origin/<branch>`, and compare file sets rather than descriptions.
+- Stamp an overlap with the commit it was measured against.

package/claude/skills/youtube-transcripts/SKILL.md

@@ -25,7 +25,7 @@ canon transcripts <url>
 ```
 
 - Pass `--keep-timestamps` when the user wants `[mm:ss]` markers per line instead of prose.
-- Pass `--out <dir>` to override the output directory. The default is `transcripts/` in the current directory.
+- Pass `--out <dir>` to override the output directory, resolved against the current directory. The default is the backed `.canon/transcripts/` folder at the main worktree root, under a filename shaped `<fetch-date>--<title-slug>--<video-id>.md`.
 - The written file path prints to stdout. Surface it back to the user as a full relative path, in the form the project's instruction file sets under `## Output`.
 
 ## After the fetch

package/docs/agents/commands.md

@@ -66,7 +66,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon worktrees list`           | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                                                                                                                                                                             |
 | `canon worktrees reclaim`        | Remove every reclaimable worktree and the branch behind it, reporting without acting under `--dry-run` (`--json`)                                                                                                                                                                                                      |
 | `canon comments scan`            | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                                                                                                                                                                 |
-| `canon context audit`            | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift                                                                                                                                                                              |
+| `canon context audit`            | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, index drift, the architecture record's word weight, and wireframe states against their evidence folders                                                                                      |
 | `canon context classify diff`    | Classify the chunks a git range changed, each with its enclosing section, as keep, replace, history, or move (`--base`, `--doc-types`, `--json`)                                                                                                                                                                       |
 | `canon context classify sweep`   | Classify every section of the five canonical doc types, split at H3, as keep, rewrite, or move (`--doc-types`, `--json`)                                                                                                                                                                                               |
 | `canon context classifier show`  | Report the resolved classifier backend and model and which source decided them (`--json`)                                                                                                                                                                                                                              |

package/docs/agents/context-audit-checks.md

@@ -55,6 +55,8 @@ The table check reports a catalog that grows a row per shipped thing, not a tabl
 
 The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open.
 
+A change number matches at any digit count, so `PR #7` and `#49` report alongside a four-digit number. Displayed spans are masked before the match runs, which is what keeps a heading's own auto-derived link destination, `(#7-open-questions)`, and a hex color in a code span, `` `#000` ``, from reading as a change reference: both are text an entry shows rather than a claim it makes. <!-- canon-allow-reference: illustrates the input shape the rule reads -->
+
 A date stamping a measurement is excluded, because the standard cuts a date attached to a change and permits one dating a figure. The check reads the clause in front of the date, back to the nearest sentence boundary, for one of five verbs: measured, verified, driven, passed, and fired. The noun `run` counts only where it sits against the date, so `A run on 2026-08-14` is excluded and `Runs on erclx/canon#632 and erclx/canon#634 landed 2026-08-02` reports. The set is closed, and a date it cannot place reports as a change marker rather than as a state of its own, which names one date too many rather than clearing one the rule cuts. <!-- canon-allow-reference: illustrates the input shape the rule reads -->
 
 A release label reports with or without its leading `v` at three segments, since the rule cuts the label rather than a spelling of it. Two segments still need the `v`, which keeps a dollar cost and a duration out. Another tool's version reports too, and the check cannot tell one from a release, so treat a version beside a tool name as a line to read rather than one to cut.
@@ -89,7 +91,7 @@ The JSON record carries the findings per entry as `entries[].narration` and the
 
 ## The architecture record
 
-Two findings read `canon/ARCHITECTURE.md` rather than a folder, and only the first is a fact.
+Three findings read `canon/ARCHITECTURE.md` rather than a folder, and only the first is a fact.
 
 The length check compares the record against the ceiling it derives for itself, and only a record that states its own allowances has one. No standard sets a length rule for this document, so the numbers belong to whichever record declares them. The check reads a frame allowance and an allowance per decision out of the record's own prose and puts the ceiling at the frame plus the allowance times the decision count. The JSON record carries what it read as `architecture.allowances` and the reading as `architecture.lines` against `architecture.ceiling`.
 
@@ -103,9 +105,27 @@ Three limits are stated on every run rather than hidden. The countable signal re
 
 The report gates nothing. Deciding whether a sentence states a claim is a judgment no parser settles, so the output names candidates for a reader. This answers a different question from the verification anchors `standards/architecture.md` describes, which record that one cited number was re-read. That mechanism says whether a marked figure held, and this one says how much of the record could be checked at all.
 
+The third finding is a word count, measured in words rather than lines: one figure for the whole record and one per decision. `standards/architecture.md` asks a session to judge the file's weight by reading it rather than by counting it, and reads the word figure alongside that judgment when one is available. A paragraph written one source line to a paragraph passes the rendered-line measure other checks use while still reading heavy, which is the gap a word count closes without turning into a second cap.
+
+The `## Risks / open questions` section is weighed the same way, reported apart from the whole-record figure since the standard singles it out for holding only what is still open. This finding gates nothing under any mode. The JSON record carries the whole-record figure as `architecture.words`, the section figure as `architecture.risksWords` where the record carries the heading, and the per-decision figure as `architecture.decisions[].words`.
+
+## Wireframe states
+
+Every entry under `canon/wireframes/` carrying a `## States` table is checked against its evidence folders on disk. `State` and `Evidence` are matched by header text rather than column position, since the standard's own template could still move a column during its own review. An entry with no such table is out of scope and reports nothing.
+
+An evidence cell's path is read as written and resolved against the project root, since the standard puts the path in the cell rather than a state name a convention would have to guess at. A state whose cited path resolves to no directory is a missing folder, measured in states: one finding per row. A directory sitting under a root at least one row already cites, but named in no row itself, is an unlisted folder, measured in folders: one finding per directory.
+
+Both are counted rather than only listed, since a count is what a reader compares run to run. A `not captured` cell is the one value the standard exempts from having a folder, and it drops out of both counts.
+
+The third finding reads the whole entry rather than one row: whether it carries a `plaintext`-fenced sketch while a state's evidence already exists on disk. The standard asks the fence to come out the moment a layout has a capture to show instead, so a sketch surviving past that point is a boolean per entry rather than a count.
+
+The unit here is the entry rather than the layout the standard's own rule is stated against. A table names states, not the layouts a wireframe's `## Regions` section can split into at a breakpoint, so this finding has no narrower unit to match a sketch against the evidence for its own layout alone. An entry with a captured default layout and a sketch for a breakpoint layout that is not built yet is conforming, and this finding still reports it, which is why it stays advisory under every mode rather than joining the states-mismatch gate below.
+
+All three wireframe findings are printed under a bare run. The states-mismatch finding, missing and unlisted folders together, gates at `2` under `--gate`, alongside a missing required section and index drift. The sketch finding stays advisory under both modes, for the reason above. The JSON record carries them per entry under `wireframes[]`, as `rows`, `missingFolders`, `unlistedFolders`, and `sketchWithEvidence` alongside `sketchLine`.
+
 ## Which folders each check reaches
 
-The provenance, required-section, and narration checks cover `canon/context/` alone, the reference-form check covers the split folders inside it, and length and the table finding reach every audited folder.
+The provenance, required-section, and narration checks cover `canon/context/` alone, the reference-form check covers the split folders inside it, length and the table finding reach every audited folder, and the wireframe states check covers `canon/wireframes/` alone.
 
 What narrows the three is stated in `standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere, and a diagram entry carries a heading per kind rather than a run of bullets deciding anything. The split is between kinds of rule rather than kinds of folder, and what decides it is which tier states the rule rather than what the check measures.
 

package/docs/agents/context-audit.md

@@ -37,9 +37,11 @@ A run where no requested name resolves refuses, whichever list it read. Naming t
 
 ## Exit codes
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a gating finding. An unresolved citation gates under every mode. An architecture record that states its own line allowances gates when it is past the ceiling those derive, on any run that measures it, which is every mode except `--citations-only`, and a record stating none is reported and never gated. Entry length, reference form, table, provenance, narration, and the record's claim classification print and return `0` under every mode, because each is a judgment and failing a push on one would make the check something to route around. Narration is the weakest of the five, since whether two bullets share a subject is a call the measure approximates from structure alone, and one of the shapes it matches is the rejected alternative the standard asks an entry to keep.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a gating finding. An unresolved citation gates under every mode. An architecture record that states its own line allowances gates when it is past the ceiling those derive, on any run that measures it, which is every mode except `--citations-only`, and a record stating none is reported and never gated.
 
-Required-section and index findings sit between the two. Both are answerable from the file rather than weighed, so `--gate` promotes them to failing codes while a bare run leaves them advisory. The toolkit runs the bare form against itself and the widened form against the seed tree, described below.
+Entry length, reference form, table, provenance, narration, the record's claim classification, and every word figure print and return `0` under every mode, because each is a judgment or a weight read alongside one, and failing a push on either would make the check something to route around. Narration is the weakest of the printed measures, since whether two bullets share a subject is a call the measure approximates from structure alone, and one of the shapes it matches is the rejected alternative the standard asks an entry to keep.
+
+Required-section, index, and wireframe-states findings sit between the two. All three are answerable from the file rather than weighed, so `--gate` promotes them to failing codes while a bare run leaves them advisory. Sketch-with-evidence sits with the printed measures instead, for the reason `context-audit-checks.md` states: it reads a whole entry against whether any of its states has evidence, not one layout against its own evidence, so a conforming file can still trip it. The toolkit runs the bare form against itself and the widened form against the seed tree, described below.
 
 ## The seed gate
 
@@ -81,3 +83,11 @@ Append `<!-- audit-ignore-citations: <path> -->` to the source line in either ca
 The marker itself stays out of anything that installs. A seed, a plugin skill body, and a stack reference all reach a target, so a marker there lands as toolkit bookkeeping in someone else's tree. Reword those lines to drop the path instead, and where a stop message has to spell it, move that message into a fenced block, which this check already skips.
 
 The pattern spells both record-root prefixes, so a citation into a folder that has moved still resolves and a folder resolved at the project root is measured by every other check while contributing nothing here. A pattern fixed at one root matches nothing after a move and reports nothing, which is a stale reference passing the check written to find it. Widening it to a bare `docs/x.md` would match prose that references nothing, which is a separate decision from where entries come from. A run whose folders all resolved at the root says the check is out of scope rather than reporting that zero paths resolved, and the same run under `--citations-only` refuses, because a gate exiting clean on a scope it could not build is the failure the gate exists to catch.
+
+## The wireframe states gate
+
+Every entry under `canon/wireframes/` carrying a `## States` table is checked one-to-one against its evidence folders, matching the table's `State` and `Evidence` columns by header text rather than position, so a project reordering the template's own columns still resolves. An entry with no such table reports nothing, which is what leaves a project on an older wireframe shape silent until it adopts one.
+
+An evidence cell resolves as the literal path it names, taken from the project root. A state whose cited folder does not exist is a states mismatch, and so is a folder sitting under a cited evidence root that no row names. A `not captured` cell is the one exception the standard admits, and it excuses that row from both readings. A `plaintext` sketch still carried once a state's evidence exists on disk is a third finding this check adds, reading the entry as a whole rather than one row.
+
+The states mismatch is printed under a bare run and gates at `2` under `--gate`, alongside a missing required section and index drift. The sketch finding is printed and stays advisory under both modes: it has no way to pair a sketched layout with that layout's own evidence, only the entry with any evidence at all, so a conforming file, a captured default layout beside a sketch of a breakpoint layout nobody has built, can still trip it.