@erclx/canon 4.63.0 → 4.64.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.63.0",
+  "version": "4.64.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -0,0 +1,34 @@
+---
+name: canon-record
+description: Why compiling and running a screencast draft needs a routed skill rather than an operator typing two verbs by hand, and why the unresolved-field refusal cannot be a suggestion
+---
+
+# Canon record requirement
+
+## Gap
+
+Without this skill, `canon-screencast` writes a draft and names `canon demo compile` as the next step, and nothing after that routes a session there or to `canon demo run`. An operator has to know both verbs, type them in order, and read the compile record for unresolved fields by hand. A session that fills one in on its own reproduces the exact failure `canon demo run`'s `plan-unresolved` reason exists to catch, one layer up where nothing enforces it.
+
+## Must
+
+- Resolve the default plan path the same way `canon demo compile` does, so a caller passing only the draft path reaches the plan without naming it
+- Skip compiling when a plan already exists at that path, since its timing may be tuned by hand and a draft cannot reproduce that
+- Report every unresolved field from the compile or run record and stop rather than filling one in
+- Report every path a run wrote, video, mp4, gif, still, skipping any the record carries as null
+
+## Must not
+
+- Pass `--force` to compile
+- Guess or fill a target, a URL, or any other unresolved field
+- Drive the application through anything other than `canon demo run`
+- Assume this skill's own invocation frequency needs no check. `canon-screencast`'s closing block names it by hand, but whether anything else reaches for it beyond that pointer or an operator typing its name has no answer at creation time, so a review pass some months in should read that back rather than take it on faith.
+
+## Guards
+
+- No draft path given: stop rather than guessing what to compile
+
+## Out of scope
+
+- Drafting the beats, which `canon-screencast` owns
+- Filling an existing plan's target or URL, which is the operator's own edit
+- Verifying a recording beyond its own caption, which nothing in the toolkit does yet

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

@@ -0,0 +1,54 @@
+---
+name: canon-record
+description: Drives a screencast draft through to a recording. Compiles it with `canon demo compile` when no plan exists yet at the default path, skipping compile when one is already there, then runs `canon demo run` once nothing is unresolved. Reports every unresolved field from the compile or run record and stops rather than guessing one. Use when asked to "record the screencast", "run the demo", "compile and record this draft", or right after `canon-screencast` prints its next-step line. Do NOT use to draft the beats, which is `canon-screencast`, or to fill in a plan's target or URL, which is the operator's own edit.
+---
+
+# Canon record
+
+## Guards
+
+- If no draft path is given, stop: `❌ No draft path. Pass the path canon-screencast printed.`
+- Never guess or fill an unresolved field, a target, a URL, or anything else the compile or run record names. Report it and stop. Filling one in reproduces the failure `canon demo run`'s `plan-unresolved` reason exists to catch, one layer up where nothing enforces it.
+- Never pass `--force` to compile. A plan already at the default output path may carry timing tuned by hand, and the draft cannot reproduce that, so leave it untouched.
+- Drive the application through `canon demo run` alone. Never open a browser, click through the app, or write to the output paths some other way.
+
+## Step 1: resolve the plan path
+
+Derive the default plan path the same way `canon demo compile` does: `<out>/<slug>.json`, where `<out>` defaults to `demos` and `<slug>` defaults to the draft's filename with its extension stripped. `.canon/tmp/screencast/inline-edit.md` resolves to `demos/inline-edit.json`.
+
+## Step 2: compile only when no plan exists yet
+
+Check whether the resolved plan path already exists.
+
+- **It exists.** A person may have tuned it by hand since compiling. Skip compiling and go to Step 3 with this path.
+- **It does not exist.** Run:
+
+  ```bash
+  canon demo compile <draft> --json
+  ```
+
+  Branch on the record rather than the exit code:
+  - `reason: draft-missing` or `reason: draft-unreadable`: report the reason, plus the record's `message` when it carries one, and stop.
+  - No `reason` key, meaning the plan was written: read `unresolved` off the record.
+    - Non-empty: report the plan path and every field the array names, one per line, and stop. Do not proceed to Step 3.
+    - Empty: continue to Step 3 with the record's `plan` path.
+
+## Step 3: run
+
+Run:
+
+```bash
+canon demo run <plan> --json
+```
+
+Branch on the record's `reason`:
+
+- `plan-unresolved`: report every field in `unresolved`, one per line, and stop. This is the path a pre-existing plan takes, since Step 2 skipped compiling and never read its fields.
+- Any other reason (`plan-missing`, `plan-unreadable`, `no-output-requested`, `cursor-unreadable`, `engine-missing`, `browser-missing`): report the reason, plus the record's `message` or `install` line when it carries one, and stop.
+- No `reason` key, meaning the run wrote its output: continue to Step 4.
+
+## Step 4: output
+
+The record carries `video`, `mp4`, `gif`, and `still`, each a path or `null`. Report each one that is not `null`, one per line, skipping the rest.
+
+Say so plainly if `canon demo compile` or `canon demo run` is not available, rather than driving the application some other way. Both ship with the CLI and this skill ships with the plugin, so a project carrying one and not the other is a real state.

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

@@ -33,7 +33,7 @@ A draft that names the recording software, the editing software, or the window m
 
 ## Out of scope
 
-- Producing the recording, which stops at the script by design
+- Producing the recording, which `canon-record` owns
 - Refining an existing draft, which is a direct edit of the file
 - Slide decks, which `canon-slides-draft` owns
 - Where the recording ships, which the draft lists and the user decides

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

@@ -8,7 +8,7 @@ description: Drafts a screencast script with pre-seeded beats, defaults, and dec
 ## Guards
 
 - If no topic is provided, stop: `❌ No screencast topic. Describe what you are recording.`
-- Draft, then hand off. Do not edit video or generate captions, and do not drive the application. A recording is another command's job rather than something forbidden: write the draft, name `canon demo compile` as the next step, and stop.
+- Draft, then hand off. Do not edit video or generate captions, and do not drive the application. A recording is another skill's job rather than something forbidden: write the draft, name `canon-record` as the next step, and stop.
 - Stack-agnostic in the draft. Never name a recording tool, an editing tool, a font, or a window manager. Keep selectors, URLs, wait conditions, and timings out of the beats too, since those four are exactly what the compiler adds in a plan of its own. A beat carrying them stops being a document a person can read and edit down.
 
 ## Step 1: read the project context
@@ -159,9 +159,9 @@ Print the file path on its own line and a one-line summary. Do not paraphrase th
 Draft has 5 beats and pre-seeded defaults. Edit the beats and the resolved decisions.
 
 To record it rather than shoot it by hand:
-canon demo compile .canon/tmp/screencast/<slug>.md
+canon-record .canon/tmp/screencast/<slug>.md
 ```
 
-Name the command and stop there. Do not compile the draft, do not run it, and do not generate captions. The operator edits the beats first, and the compiler reports which selectors and URLs they still owe it.
+Name the skill and stop there. Do not compile the draft, do not run it, and do not generate captions. The operator edits the beats first, and the compiler reports which selectors and URLs they still owe it.
 
 Say so plainly if `canon demo compile` is not available, rather than driving the application some other way. The command ships with the CLI and the skills ship with the plugin, so a project carrying one and not the other is a real state.

package/claude/skills/claude-autoship/REQUIREMENT.md

@@ -16,6 +16,7 @@ Review is the step that varies most. It gets skipped on a diff that needed one,
 - Take the approved plan for the branch as the scope, and implement only what it describes
 - Give every step a stop condition, and leave the code on the branch and the receipts on disk at each one
 - Classify the changed-file list by path as well as by extension, so informational prose skips a code review with no signal on it and executable prose still reaches one
+- Check the branch's committed history for a test-order violation between verify and review, and report any finding without gating on it, matching the verb's own contract
 - Split findings by origin, stopping on a critical or should-fix one the branch inherited and repairing one this run caused
 - Own the review receipt's lifetime, since this chain writes it, cites it in its own closing block, and is the only body that can read whether the step keeping it is still using it
 - Delegate the ship sequence to `git-ship` rather than restating it, and name only what this chain adds to it
@@ -34,6 +35,7 @@ Review is the step that varies most. It gets skipped on a diff that needed one,
 - Run the memory Apply phase. Promoting an entry changes how the agent operates and ships as its own change.
 - Read an empty changed-file list as prose-only. It satisfies that test vacuously and would route the branch past review instead of through it.
 - Read a markdown extension as evidence the change only informs. A skill body, a governance rule, and a standard are behavior written in prose.
+- Stop the chain or rewrite a commit over a test-order finding. The verb reports and never gates, and a commit already in history is a different act from the work this run is building.
 
 ## Guards
 
@@ -47,4 +49,4 @@ Review is the step that varies most. It gets skipped on a diff that needed one,
 
 - Writing the plan, which `claude-feature` owns. This chain starts from one already approved.
 - The behavior of each step, owned by the skill invoked. This skill owns the order and the stop conditions.
-- The ship sequence and the resume path after a stop, both of which `git-ship` owns. That skill is the tail of this chain, invoked at Step 7 rather than copied into it, so the overlap is one body reached two ways rather than two bodies stating one order.
+- The ship sequence and the resume path after a stop, both of which `git-ship` owns. That skill is the tail of this chain, invoked at Step 8 rather than copied into it, so the overlap is one body reached two ways rather than two bodies stating one order.

package/claude/skills/claude-autoship/SKILL.md

@@ -17,7 +17,7 @@ Chain the post-plan pipeline in a single run. Every step has a stop condition. S
 
 ## Diff baseline
 
-Step 5 classifies the changed-file list to decide whether review runs. Resolve the base ref once:
+Step 6 classifies the changed-file list to decide whether review runs. Resolve the base ref once:
 
 ```bash
 git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
@@ -27,7 +27,7 @@ Prefer `origin/main` over local `main`. A local `main` trailing the remote pulls
 
 The baseline is unusable when no merge base resolves against either ref. Stop: `❌ No diff baseline against main. Fetch origin, then re-run autoship.`
 
-The base equalling HEAD stays usable here, unlike in the four read-only siblings carrying this section. Step 5 runs before anything is committed, since `git-stage` commits at Step 7, so the base equals HEAD on every ordinary run. The classifier diffs the base against the working tree rather than against HEAD, which keeps the uncommitted work in the set at correct scope. Do not port the sibling `base == HEAD` stop into this skill.
+The base equalling HEAD stays usable here, unlike in the four read-only siblings carrying this section. Step 6 runs before anything is committed, since `git-stage` commits at Step 8, so the base equals HEAD on every ordinary run. The classifier diffs the base against the working tree rather than against HEAD, which keeps the uncommitted work in the set at correct scope. Do not port the sibling `base == HEAD` stop into this skill.
 
 ## Step 0: take the role, then enter a worktree
 
@@ -103,7 +103,21 @@ Run the verify commands defined in `CLAUDE.md` (lint, typecheck, tests). On fail
 
 Do not loop. Do not bypass hooks.
 
-## Step 4: UI test (conditional)
+## Step 4: test order
+
+Run `canon gov test-order --json` from the worktree this chain is building in, which is the one tree holding the branch's own commits. The Guards send a `.canon/plans/` and a `.canon/review/` read to the main worktree root and this is not one of those: that checkout sits on the trunk on an ordinary run, so the range closes on itself there and every finding the branch carries reads as clean.
+
+The verb reads git history rather than the working tree, so a branch with nothing committed yet reads as clean, and what it catches is a violation that already reached this branch's history in an earlier session or an earlier round of this chain. It reports and never gates, since nothing wires its exit into a push, so branch on the record's `kind` and its `findings` array rather than on the exit, which reads 2 on a finding and 1 on a refusal and which a shell function wrapping `canon` can flatten to zero either way.
+
+- `kind: 'measured'`, `findings` empty. Nothing on the branch reached history ahead of its test. Continue to Step 5.
+- `kind: 'measured'`, `findings` non-empty. Report each pair's `subject` and `reason` to the user and continue to Step 5. Do not stop the chain and do not attempt a fix: the commit already reached history, and rewriting it here rewrites what an earlier run shipped rather than what this run is building.
+- `kind: 'unreadable'`. Report the `message` and continue to Step 5. A shallow clone or a repository with no trunk is an ordinary state this check cannot read, not a reason to stop shipping.
+
+### When the verb is absent
+
+The verb ships with the CLI and this body ships with the plugin, matching Step 6's own fallback for the classify verb. Report that the check did not run rather than reading a missing subcommand as clean, and continue to Step 5.
+
+## Step 5: UI test (conditional)
 
 If the diff touches UI files (JSX, TSX, Vue, Svelte, HTML, or CSS under `src/`), invoke `canon:claude-ui-test`.
 
@@ -111,7 +125,7 @@ If `claude-ui-test` produces a manual checklist, stop: `❌ UI requires visual v
 
 If all UI changes are covered by e2e tests, continue.
 
-## Step 5: review
+## Step 6: review
 
 Classify the diff first. Take the union of `git diff --name-only <base>` and `git ls-files --others --exclude-standard`, resolving `<base>` per Diff baseline, then hand that set to the verb rather than reading it against the list below yourself:
 
@@ -121,7 +135,7 @@ canon autoship classify --json <path>...
 
 The verb reads names only and touches git not at all, so the set stays the one this step already computed and no second baseline resolves to disagree with the first. Branch on the record's `decision` rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
 
-- `skip`. Every path reads as prose and none states agent behavior. Skip review entirely and continue to Step 7.
+- `skip`. Every path reads as prose and none states agent behavior. Skip review entirely and continue to Step 8.
 - `review`. Invoke `canon:claude-review`. The record names the `file` that decided it and the `test` it failed, `extension` for a path that is not prose and `behavior-path` for prose that states what an agent does.
 - `refused`, carrying reason `no-changes`. The changed set was empty, so take the stop below.
 
@@ -137,7 +151,7 @@ The verb ships with the CLI and this body ships with the plugin, so a target hol
 
 Never read an absent subcommand as a skip. Failing open is the exact defect the verb closes, and a shell that answers `command not found` reaching a body that skips on anything other than a `skip` record would ship every branch unreviewed.
 
-The skip needs both tests to pass: every changed file matches `*.md` or `*.txt`, and no changed file sits under a behavior path. On a pass, skip review entirely and continue to Step 7. Otherwise invoke `canon:claude-review`.
+The skip needs both tests to pass: every changed file matches `*.md` or `*.txt`, and no changed file sits under a behavior path. On a pass, skip review entirely and continue to Step 8. Otherwise invoke `canon:claude-review`.
 
 Behavior paths carry two spellings, the one a surface authors at and the one it reaches a session at, so the rule reads the same in a toolkit and in a project that consumed one:
 
@@ -156,9 +170,9 @@ The list covers this toolkit's authoring layout and the layout it installs, whic
 
 The verb reads the same set from `src/autoship/paths.ts`, so a path added here belongs there too and a path added there belongs here. Two copies is what the fallback costs, and it stands until a release retires the written half.
 
-## Step 6: evaluate findings
+## Step 7: evaluate findings
 
-Skip this step when Step 5 skipped review. Otherwise read `.canon/review/branch/review-<slug>.md` at the main worktree root. Split every finding by origin before parsing the summary line (`X critical, Y should-fix, Z minor`), since the stop exists for a defect the branch inherited rather than for one this run introduced.
+Skip this step when Step 6 skipped review. Otherwise read `.canon/review/branch/review-<slug>.md` at the main worktree root. Split every finding by origin before parsing the summary line (`X critical, Y should-fix, Z minor`), since the stop exists for a defect the branch inherited rather than for one this run introduced.
 
 - **This run caused it, at any severity.** Fix it, re-run the Step 3 verify commands, re-read the fixed file against what the finding claimed, and continue. Do not report it as a stop and do not offer the fix as a choice, which is the same stop wearing a proposal.
 - **It predates this run, critical or should-fix.** Stop: `❌ Review found non-minor issues that predate this run. See .canon/review/branch/review-<slug>.md. Fix and run /git-ship.`
@@ -168,9 +182,9 @@ Read origin as causation rather than authorship. Staleness this run induced in a
 
 Bound the repair at one pass, the way Step 3 bounds verify. When that re-read shows the finding still standing, stop: `❌ A self-introduced finding survived one fix pass. See .canon/review/branch/review-<slug>.md. Fix and run /git-ship.`
 
-This chain owns the receipt's lifetime, which is what makes the Output block's citation resolve on a run that reaches it. `claude-docs` used to delete the current slug's receipt while running under Step 7 below, so the closing line named a file the same run had already removed. That sweep now reaches only reports whose branch is gone, which collects this one a branch later rather than during the run that wrote it. The cost is one receipt per live branch left in `.canon/review/branch/`, bounded by the branch count rather than by the lifetime of the checkout.
+This chain owns the receipt's lifetime, which is what makes the Output block's citation resolve on a run that reaches it. `claude-docs` used to delete the current slug's receipt while running under Step 8 below, so the closing line named a file the same run had already removed. That sweep now reaches only reports whose branch is gone, which collects this one a branch later rather than during the run that wrote it. The cost is one receipt per live branch left in `.canon/review/branch/`, bounded by the branch count rather than by the lifetime of the checkout.
 
-## Step 7: ship
+## Step 8: ship
 
 Invoke `canon:git-ship`. That body owns the sequence, being the verify gate, memory capture, both doc syncs, staging, the commit grouping, the branch rename, the pull request, the CI watch, and the scoped memory review, along with the reason each step sits where it does. This step used to restate that list and the two drifted apart with nothing comparing them, so read the order there and never here.
 
@@ -201,11 +215,11 @@ Respond with up to five lines:
 <Memory proposal at .canon/review/memory/memory-review-<slug>.md>
 ```
 
-`<state>` is whatever the Step 7 read returned, being `draft` or `ready, unsupervised`, rather than the state the undo asked for. Writing the word `draft` there unconditionally is what this line used to do, and it named a state no step had read.
+`<state>` is whatever the Step 8 read returned, being `draft` or `ready, unsupervised`, rather than the state the undo asked for. Writing the word `draft` there unconditionally is what this line used to do, and it named a state no step had read.
 
 Omit the second line if there were no minor findings, and the third if nothing routed. Omit the fourth and fifth if `claude-memory-capture` wrote no memory file this session, since an empty pen means no scoped review and no proposal. A run that routes every fact and writes none is the shape to expect, and it reports three lines.
 
-This block replaces the one `git-ship` closes on rather than following it. The two carry the same three trailing lines and differ on the two above them, since the first names the state the read returned and the second reports the minor findings Step 6 kept, neither of which that body has a counterpart for. Emitting both reports one run twice and buries the state under a `✅ Shipped` that does not name it.
+This block replaces the one `git-ship` closes on rather than following it. The two carry the same three trailing lines and differ on the two above them, since the first names the state the read returned and the second reports the minor findings Step 7 kept, neither of which that body has a counterpart for. Emitting both reports one run twice and buries the state under a `✅ Shipped` that does not name it.
 
 ## Failure recovery
 

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

@@ -0,0 +1,36 @@
+---
+name: draft-readme
+description: Why a README needs a project-type read and a confirm step, not the rewrite path docs-sync already owns
+---
+
+# Readme draft requirement
+
+## Gap
+
+Without this skill, a session drafting a README either copies the generic template from memory or reaches for `docs-sync`, which has nothing to diff a nonexistent page against and reports the topic as unrelated to any change. A scaffold-written stub meets the same dead end, since no diff touches it either. Either way the page ships with no read of `standards/readme.md`, no read of what the project actually is, and no badge chosen against its rendered value rather than its service name.
+
+A README whose real documentation lives in `.claude/context/` or `docs/` was a second gap the standard itself carried until this build: nothing named a pointer page as complete, so a session drafting one either padded the page or read the required list as unsatisfied.
+
+## Must
+
+- Read `standards/readme.md` before drafting, since its `## Voice` section is scoped to a repository-root README and yields to `write-human`'s reference voice everywhere else
+- Detect every project type the standard's `## Content` list applies to, from the manifest and the tree, rather than drafting against the closest single type
+- Treat an existing README with no H1, or with headings that name only the scaffold that wrote it, as unedited generator output to draft over rather than a page to sync section by section
+- Verify a candidate badge by the value it would render rather than by a fetch's status code, since a badge service answers 200 for a query it cannot satisfy
+- Confirm the resolved path, the detected types, the badge candidates, and the full content with the user before writing, since project-type detection and badge selection are judgment calls with no diff to preview them against
+
+## Must not
+
+- Rewrite an authored README. One carrying an H1 that names the project refuses toward `docs-sync`.
+- Offer to overwrite an authored README on the refusal path, or propose conforming it to what this skill would have drafted. A target project's own citations into its README are invisible from here, so the refusal reports rather than proposes.
+- Assume this skill's own invocation frequency needs no check. Whether anything reaches for it beyond an author typing its name has no answer at creation time, so a review pass some months in should read that back rather than take the assumption on faith.
+
+## Guards
+
+- The target already exists and is authored, carrying an H1 that names the project: stop and point at `docs-sync` instead.
+
+## Out of scope
+
+- Rewriting or syncing an existing authored `README.md` against a diff since main: `docs-sync`
+- The consumer-facing reference under `docs/`: `draft-docs`
+- Product scope and goals, and every other surface `standards/readme.md` already scopes out of its own governance

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

@@ -0,0 +1,65 @@
+---
+name: draft-readme
+description: Drafts a project's README.md against the readme standard, detecting project type and badge candidates, and confirming with the user before write. Use when asked to "write a README", "draft a README for this project", "add a README", or "create a README.md" where none exists yet or the existing one is unedited scaffold output. Do NOT use to rewrite or resync an existing authored README against a diff, which is `docs-sync`.
+---
+
+# Readme draft
+
+Drafts a project's `README.md` end to end: read the standard, detect the project's shape, confirm the draft with the user, then write.
+
+Read these files in parallel:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/readme.md`: voice, structure, required and optional sections, badge selection, and what to link out to rather than carry. Voice is claimed here for a repository-root README, and `write-human` yields it there while keeping rhythm, density, and the machine-tell catalog everywhere, root README included.
+- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: rhythm, density, and sentence construction for all generated text
+
+## Guards
+
+- Default the target to `README.md` at the repository root when no path is given. A caller naming a path under a folder, a harness, or an internal tool is drafting a nested README instead, which keeps the reference voice per the standard's `## Voice` section rather than the root voice below.
+- Read the target if it exists.
+  - It carries an H1 naming the project: it is authored. Stop: `❌ <path> already exists and covers the project. Run canon:docs-sync instead.`
+  - It carries no H1, or its only headings restate the tool that scaffolded it rather than the project: it is unedited generator output. Continue, drafting over it rather than syncing its sections.
+  - It does not exist: continue.
+- A hand-authored README opening with a badge block, or a title in some other form the H1 test misses, falls into the no-H1 branch the same as a scaffold page. The Confirm step below is what catches that case before the write happens, so treat it as load-bearing rather than a courtesy: never skip it on the reasoning that the guard already decided.
+
+## Detect
+
+- Read the project's manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, or equivalent) for a `bin` field or CLI entry point, an installable package name, and its declared dependencies.
+- Check for a `claude/skills/` or `.claude/skills/` folder, a `plugin.json`, or a marketplace manifest, each naming an agent-facing or marketplace-distributed surface.
+- A project is often several of these at once. Note every type that applies rather than stopping at the first match, since the Draft step covers each one the project actually is.
+
+## Draft
+
+- Draft the page against `${CLAUDE_SKILL_DIR}/../../standards/readme.md`: H1, a 2-3 sentence description in plain text, then the required sections, then whichever optional sections and per-type content the Detect step found.
+- Cover every applicable project type from the standard's `## Content` list rather than picking the closest one.
+- Candidate badges: check for a published package (a registry field in the manifest), a CI workflow, and a `LICENSE` file.
+- State each candidate's rendered value in the preview rather than trusting a fetch's status code, since a badge service answers 200 for a query it cannot satisfy.
+- Pin a status badge to the branch the standard names and confirm the workflow actually triggers on that branch before offering it. Zero badges is a correct answer when nothing passes the test.
+
+## Confirm
+
+- Show the resolved path, the detected project types, the badge candidates and what backs each one, and the full drafted content before writing.
+- Confirm with the user. This skill waits for that answer rather than treating the tool permission dialog as the gate, since project-type detection and badge selection are judgment calls with no diff to preview them against.
+
+## Write
+
+- Write the file at the confirmed path, creating the folder when it is absent.
+- Run `canon markdown audit <path>`.
+
+## Response format
+
+### Preview
+
+**Target:** `<path>` (root | nested)
+**Detected:** `<project types>`
+**Badges:** `<candidates, or none>`
+
+```markdown
+<drafted H1 and body>
+```
+
+### After confirmation
+
+```plaintext
+✅ Drafted: <path>
+```

package/claude/skills/identity/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: identity
+description: Why the mark and the card are one pick rather than two, and where the size sequence and the write folder come from before either is drafted
+---
+
+# Identity requirement
+
+## Gap
+
+Without this skill, a session asked for a logo and a social card either invents shapes with nothing behind them, or drafts the mark and the card as two separate decisions that can land on shapes that do not compose, which is the failure the task filing this skill measured by hand on every project it touched. A search across every shipped skill and standard found zero hits for `logo`, `og:image`, `og-image`, or Open Graph, so nothing in the catalog reached either output.
+
+A session building this without a shared loop restates `draft-and-pick`'s render, hand-off, pick, and loop mechanics from scratch, which drifts from the shipped one with nothing comparing the two copies. It also guesses at the icon size sequence and the output folder rather than reading what the project already declares, and it produces one raster per size through a separate render call per size, which multiplies capture invocations for no reason `canon capture` cannot already batch.
+
+## Must
+
+- Detect the icon size sequence from the project's own HTML head or manifest before falling back to the stated default set
+- Detect the write folder from the project's own static-asset convention before falling back to the project root, and announce which one decided it
+- Draft every arm already composed inside the card frame, so one pick settles the mark's shape and its composition together
+- Follow `draft-and-pick`'s Steps 2 through 5 for the render, hand-off, pick, and loop, rather than restating them
+- Write the final mark as its own SVG source, not baked into a raster only
+- Render every final size and the card in one capture call, by sharing one selector class across pages, each declared at half its target dimension to land on the literal size once the render engine's fixed 2x scale factor is applied
+
+## Must not
+
+- Restate `draft-and-pick`'s render, hand-off, pick, or loop mechanics
+- Add a `## Logo` section to `standards/design.md`'s fixed section set. `src/design/parse.ts` reads a fixed key set, and no outcome behind this skill asks for a schema change.
+- Modify `draft-and-pick`, `claude-design-extract`, `canon capture`, or `canon design render`. This skill composes all four and extending any of them is a separate change.
+- Assume this skill's own invocation frequency needs no check. Whether anything reaches for it beyond an operator typing its name has no answer at creation time, so a review pass some months in should read that back rather than take it on faith.
+
+## Guards
+
+- `canon` not on PATH: stop, since the render loop and the finalize step both need it
+- Fires on a direct request only. A run offering a logo to a project that never asked for one spends a render nobody wanted.
+
+## Out of scope
+
+- Wiring the produced files into a project's own HTML head or manifest, which is a separate edit this skill leaves for the operator to make against their own markup
+- Recording the mark's construction rules in `standards/design.md`, which the task's own constraint keeps out of the fixed section set
+- Mutating an existing logo file directly, which is a direct edit rather than a skill
+- Auditing an implemented UI against its tokens, which `claude-ux-audit` owns

package/claude/skills/identity/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: identity
+description: Drafts a project's logo mark through draft-and-pick's render-and-pick loop, then composes the picked mark into an icon sequence and a 1200x630 social card. Use when asked to "make a logo", "design a logo mark", "create a favicon", "build the icon set", "generate a social card", "make an og:image", or "draft the logo and social card together". Do NOT use to mutate an existing logo file directly, which is a plain edit, or to record the mark's construction rules in DESIGN.md, which is out of scope.
+---
+
+# Identity
+
+One identity rendered twice: the same mark sized down to an icon sequence and composed with type into the social card sized up. Drafting both from one pick keeps the mark and its card composition from settling on shapes that do not match.
+
+## Guards
+
+- If `canon` is not on PATH, stop: `❌ canon CLI not found.`
+- Draft no candidate for a mark the operator has not asked to make. This skill fires on a direct request, never on the model's own read that a project could use one.
+
+## Step 1: read signal
+
+Read these in parallel, skipping any that do not exist:
+
+- `.claude/DESIGN.md`: the `## Personality`, `## Color`, and `## Typography` sections, the same three cells `claude-design-extract` Step 2 sources from
+- `.claude/REQUIREMENTS.md`: the `## Personality` paragraph, when `.claude/DESIGN.md` carries none
+- `CLAUDE.md`: the project's stated voice, when neither file above carries a personality signal
+
+No signal from any of the three is not a stop. Draft against a neutral default and tag the color and type choices `? verify` per `${CLAUDE_SKILL_DIR}/../../standards/design.md`'s uncertainty tag.
+
+## Step 2: detect the icon size sequence
+
+Check the project's HTML entry points (`index.html`, `public/index.html`, `src/index.html`) for a `<link rel="icon">` or `<link rel="apple-touch-icon">` tag carrying a `sizes` attribute, and any `manifest.json` or `site.webmanifest` for an `icons` array. Take the union of every size found.
+
+Fall back to the stated default when nothing is detected, since no `tooling/` stack scaffolds a `public/` folder, a favicon reference, or an `og:image` meta tag:
+
+- `16x16`, `32x32`, `48x48`
+- `180x180`
+- `192x192`, `512x512`
+
+This default set is raster-only. Step 6 already writes the vector source at `favicon.svg` regardless of which branch decided the sequence, so a project willing to reference an SVG favicon directly is covered either way.
+
+Announce which of the two decided the sequence.
+
+## Step 3: detect the write folder
+
+Check for `public/`, `static/`, or a stack-declared asset folder, taking the first that exists. Fall back to the project root when none is detected, mirroring `claude-design-extract`'s own source-versus-greenfield split. Announce the folder so the operator can move the files if the project's own convention differs.
+
+## Step 4: name the decision and the arms
+
+Follow `${CLAUDE_SKILL_DIR}/../draft-and-pick/SKILL.md` Step 1, with the decision fixed rather than derived: "the project's logo mark and its composition into the social card." Vary the mark's shape or style across arms, keeping the card's type and layout fixed, per that skill's one-property rule. Draft each arm already inside the full 1200x630 card frame, mark and type together, so the pick settles the shape and the composition in one choice. Arm 0 is the current mark when the folder from Step 3 already holds a logo file (`favicon.svg`, `favicon.ico`, `logo.svg`, or similar). Arms start at 1 otherwise.
+
+Structure every arm as a `.mark` element, the inline SVG alone, nested inside a `.card` element, the full composition, so Step 6 can address either without re-deriving them.
+
+## Step 5: draft, render, pick, and loop
+
+Follow `${CLAUDE_SKILL_DIR}/../draft-and-pick/SKILL.md` Steps 2 through 5 against the arms from Step 4: author the page, render and hand off, take the pick, and loop on it.
+
+## Step 6: finalize
+
+This step replaces `draft-and-pick`'s own Step 6, since the pick here produces several final files rather than one applied surface.
+
+1. Extract the picked arm's `.mark` markup as the final vector source. Write it to `<write-folder>/favicon.svg`.
+2. Under `<dest>/render/`, write one page per Step 2 size plus one for the card. Give every page's captured element the shared class `.render`, so one capture call renders the whole batch regardless of the size spread. `canon capture` opens every page at a fixed 2x device scale factor and screenshots the element at that scale, so declare each `.render` element at half its target dimension, `<w>/2` by `<h>/2`, to land the captured PNG on the literal target size rather than double it. Declare a machine-resolved font stack (`system-ui` behind a generic fallback) on each, since `canon capture` refuses a page naming no font at all.
+   - `icon-<w>x<h>.html`: the picked `.mark` markup, its `.render` wrapper sized `<w>/2` by `<h>/2`
+   - `og-image.html`: the picked `.card` markup, its `.render` wrapper sized 600x315 to capture at the native 1200x630
+3. Render the batch:
+
+   ```bash
+   canon capture <dest>/render --selector .render --out <write-folder>
+   ```
+
+4. Report each written file's path and the dimensions `canon capture` printed for it, confirming each equals its Step 2 target rather than half of it.
+5. Delete `<dest>`, per `draft-and-pick`'s own scratch-folder rule.
+
+## Response format
+
+```plaintext
+📝 Wrote <write-folder>/favicon.svg
+📝 Wrote <write-folder>/icon-16x16.png (16x16)
+📝 Wrote <write-folder>/og-image.png (1200x630)
+
+Write folder: <detected <path>|defaulted to project root>. Move the files if this project's own convention differs.
+```
+
+## What this delegates
+
+Cite these rather than restating them.
+
+- `draft-and-pick` owns Steps 1 through 5 of the render-and-pick loop, cited above
+- `claude-design-extract` owns building `.claude/DESIGN.md`. This skill only reads it.
+- `canon capture` owns the render mechanics, its font refusal, and its reported dimensions

package/claude/skills/test-first/REQUIREMENT.md

@@ -0,0 +1,34 @@
+---
+name: test-first
+description: Why the loop exists and where it stops short of a debugging session or a visual check
+---
+
+# Test first requirement
+
+## Gap
+
+Without this skill, a session implementing a planned change writes the test after the code, or writes both in one motion and never runs the test against the code as it stood before. Either way, nothing showed that the test would have caught the defect it exists to catch, so a test added after the fact protects nothing beyond what the author was already confident about.
+
+## Must
+
+- Write or extend the test before the implementation it covers, for any behavior whose shape is already known
+- Run the test before implementing and confirm it fails for the missing behavior, not for an unrelated mistake in the test itself
+- Implement the minimum the current test demands, and start a new test before extending past it
+- Re-run the test after implementing and confirm the pass is the one the test was written to prove
+
+## Must not
+
+- Write the implementation and the test together with the test never run red first
+- Treat a test that already passes before any code change as evidence for the new behavior
+- Restate the reproducing-test step `canon:systematic-debugging` already owns for a failure with no known cause
+- Decide whether a change looks right visually, which runs after implementation as a separate check
+
+## Guards
+
+- A test failing for a reason other than the missing behavior blocks moving to implementation. Fix the test first.
+
+## Out of scope
+
+- Finding the cause of an unexplained failure: `canon:systematic-debugging`
+- Confirming visual output after a change lands: `070-planning.md` states the order and `claude-ui-test` covers it
+- The mechanical audit of whether an implementation reached history ahead of its test: `canon gov test-order`, invoked from `claude-autoship`

package/claude/skills/test-first/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: test-first
+description: Write the failing test for a behavior before writing the code that satisfies it, confirm it fails for the right reason, then implement the smallest change that turns it green. Auto-triggers before implementing a planned feature, adding a function or an endpoint, or extending existing behavior whose new shape is already decided. Do NOT use for a failure with no known cause, which is canon:systematic-debugging, or when the test for the behavior already exists and already passes.
+---
+
+# Test first
+
+## The loop
+
+1. Find or write the test for the behavior before touching the code it covers. Follow the pairing convention the project already uses, which is commonly a test sitting beside its subject under one name, so that `foo.ts` takes `foo.test.ts` beside it.
+2. Write the test against the behavior as it should exist once the change lands, naming the case for what it proves rather than for the function it calls.
+3. Run only that test and read the failure. Confirm it fails because the behavior is missing, not because of a typo, a missing import, or a signature the test itself got wrong. A test failing for the wrong reason still reads green the moment any code exists to satisfy that wrong reason, so treat any other failure as a defect in the test and fix the test before moving on.
+4. Implement the smallest change that turns the failure into a pass. Do not add behavior the test does not ask for. A second behavior wants its own test written first, not a shortcut folded into the change already open.
+5. Run the test again and confirm it passes for the reason it was written for, not by accident. Then run the surrounding suite so a change made to satisfy this test has not broken another.
+
+## Extending existing behavior
+
+- Changing what a function already does starts with changing what its test asserts. Run that changed test once before touching the implementation, and confirm it fails against the code as it stands today.
+- A test that already passes before any code changes proves nothing about the new behavior. Widen the assertion or add a case until the suite fails against the current implementation.
+
+## What this skill does not cover
+
+- A failure with no known cause. Route through `canon:systematic-debugging` first, whose own fix phase already writes the reproducing test as part of finding the cause. This skill starts once the shape of the fix or the feature is already decided.
+- Confirming a change looks right once it has landed, which is a separate concern from whether the test passed and runs after implementation rather than before it.

package/docs/agents/demo.md

@@ -23,6 +23,8 @@ So `canon demo compile` writes a second artifact rather than adding fields to a
 
 The plan is committed, not scratch. Its timing is a starting point tuned by watching a recording, and the draft cannot reproduce a tuned value, so a recompile over an existing plan refuses and names `--force`.
 
+`canon-record` is the routed way to run both verbs from a draft path: it compiles only when no plan exists yet, then runs, stopping to report any field still unresolved rather than guessing one.
+
 | Option          | Behavior                                                          |
 | --------------- | ----------------------------------------------------------------- |
 | `--out <dir>`   | Directory the plan and its output paths point at, default `demos` |

package/docs/agents/review-classification.md

@@ -64,13 +64,13 @@ An empty set refuses with `no-changes` rather than skipping. Both tests are univ
 
 ## Why it is a verb
 
-The decision was three sentences in `claude-autoship` Step 5, applied by a session reading a bulleted list of paths. It failed three times. A driven arm on 2026-08-30 staged `.claude/skills/deploy-check/SKILL.md`, which that list names, and the chain skipped review and opened a draft pull request anyway. The rule was correct and the session did not apply it, and the two fixes before that one were each a rewrite of the same prose.
+The decision was three sentences in `claude-autoship`'s review step, applied by a session reading a bulleted list of paths. It failed three times. A driven arm on 2026-08-30 staged `.claude/skills/deploy-check/SKILL.md`, which that list names, and the chain skipped review and opened a draft pull request anyway. The rule was correct and the session did not apply it, and the two fixes before that one were each a rewrite of the same prose.
 
 A rule a session can talk itself out of moves into a verb. That is the same argument the quiz-order draw in `canon teach lesson` was decided on: an instruction is a hope where a verb is a check.
 
 ## The written fallback
 
-The verb ships with the CLI and Step 5 ships with the plugin, so a target holding an older binary meets a missing subcommand. The skill body keeps the written list and applies it by hand there, naming which of the two decided the run.
+The verb ships with the CLI and Step 6 ships with the plugin, so a target holding an older binary meets a missing subcommand. The skill body keeps the written list and applies it by hand there, naming which of the two decided the run.
 
 The fallback is never a skip. Failing open is the exact defect the verb closes, so a body that skips on anything other than a `skip` record would ship every branch unreviewed the moment the subcommand went absent.
 

package/docs/workflow/ai-workflow.md

@@ -157,7 +157,7 @@ The list stays written in the skill body as the fallback for a target whose inst
 
 #### Memory in the chain
 
-`git-ship` runs its verify gate and then opens on `claude-memory-capture`, which sends what the session learned to the surface that owns it. `autoship` reaches the same step by invoking that skill at its Step 7 rather than restating the order. A fact about a domain carrying an entry in `.claude/context/index.md` is routed to that entry, and `claude-docs` folds it in on the next step, so it ships in the same pull request. Anything no entry owns stays a file in `.canon/memory/`.
+`git-ship` runs its verify gate and then opens on `claude-memory-capture`, which sends what the session learned to the surface that owns it. `autoship` reaches the same step by invoking that skill at its Step 8 rather than restating the order. A fact about a domain carrying an entry in `.claude/context/index.md` is routed to that entry, and `claude-docs` folds it in on the next step, so it ships in the same pull request. Anything no entry owns stays a file in `.canon/memory/`.
 
 Capture leads rather than trails because a routed fact edits a tracked file, which has to reach the branch before the commit steps run.
 
@@ -219,13 +219,14 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Build the feature
 
-| Skill                        | When to use                                                         |
-| ---------------------------- | ------------------------------------------------------------------- |
-| `canon:claude-worktree`      | At the plan-to-execute boundary, to get an isolated tree and branch |
-| `canon:claude-autoship`      | After plan approval, to chain implement, verify, review, draft PR   |
-| `canon:project-commands`     | When the project's own command needs running                        |
-| `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first      |
-| `canon:claude-ui-test`       | After a UI change, to generate e2e tests and a visual checklist     |
+| Skill                        | When to use                                                               |
+| ---------------------------- | ------------------------------------------------------------------------- |
+| `canon:claude-worktree`      | At the plan-to-execute boundary, to get an isolated tree and branch       |
+| `canon:claude-autoship`      | After plan approval, to chain implement, verify, review, draft PR         |
+| `canon:project-commands`     | When the project's own command needs running                              |
+| `canon:test-first`           | Before implementing a planned change, to write and run its test red first |
+| `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first            |
+| `canon:claude-ui-test`       | After a UI change, to generate e2e tests and a visual checklist           |
 
 ### Check the work before it leaves the branch
 
@@ -294,11 +295,14 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:draft-docs`         | For a brand-new `docs/*.md` page, drafted against `standards/docs.md`                             |
 | `canon:draft-context`      | For a brand-new `.claude/context/<domain>.md` entry, drafted against `standards/context.md`       |
 | `canon:draft-wireframes`   | For a brand-new `.claude/wireframes/<surface>.md` file, drafted against `standards/wireframes.md` |
+| `canon:draft-readme`       | For a project's `README.md`, drafted against `standards/readme.md`                                |
 | `canon:bash-script`        | For an interactive, human-facing shell tool                                                       |
 | `canon:bash-cli-script`    | For a non-interactive automation, CI, or pipeline script                                          |
 | `canon:ci-workflow`        | For a GitHub Actions workflow file                                                                |
 | `canon:canon-slides-draft` | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                             |
 | `canon:canon-screencast`   | For a recording script with beats and defaults already seeded                                     |
+| `canon:canon-record`       | For compiling and running a screencast draft into a recording and a still                         |
+| `canon:identity`           | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop       |
 
 ### Answer a question at any point
 

package/docs/workflow/visual-design-workflow.md

@@ -40,6 +40,7 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 - `canon:claude-ux-audit` for UX gap detection on existing surfaces
 - `canon:claude-ux-measure` for what a running surface costs to paint, read against published thresholds
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates onto one page and taking your pick
+- `canon:identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop
 - Anthropic's `frontend-design` plugin optional for light visual steering
 
 ### When to pick

package/governance/rules/core/070-planning.md

@@ -13,6 +13,7 @@ description: Enforce planning standards before implementation
 - Propose the simplest solution that satisfies the requirement before implementing complex patterns.
 - Write or update tests as part of every implementation plan.
 - Write the test for a behavior before the code that implements it. Confirm visual output after implementing it, not before.
+- Load the `canon:test-first` skill before writing the implementation for a behavior whose test does not exist yet, and report it rather than proceeding silently when the skill does not resolve.
 - Run `canon gov test-order` before shipping a branch. Fix what it names as reaching history ahead of its test.
 - Load the `canon:systematic-debugging` skill before proposing a fix for a failing test, a surfaced bug, or behavior nobody has explained yet, and report it rather than proceeding silently when the skill does not resolve.
 - Do not modify code without a confirmed plan.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.63.0",
+  "version": "4.64.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -62,9 +62,11 @@
     "@tailwindcss/vite": "^4.2.4",
     "@testing-library/jest-dom": "^6.9.1",
     "@types/bun": "^1.2.10",
+    "@types/micromatch": "^4.0.10",
     "astro": "^6.1.9",
     "cspell": "^8.17.1",
     "husky": "^9.1.7",
+    "micromatch": "^4.0.8",
     "prettier": "^3.8.1",
     "prettier-plugin-astro": "^0.14.1",
     "prettier-plugin-tailwindcss": "^0.7.2",

package/scripts/core/regen-agent-fixture.sh

@@ -202,7 +202,7 @@ const summary = {
 }
 
 const fixture = {
-  // Read by web/src/components/AgentView.astro. Every field below is either a
+  // Read by web/src/components/agent-view.astro. Every field below is either a
   // live read or a hand transcription, and this header is what says which.
   generatedBy: "scripts/core/regen-agent-fixture.sh",
   readAt: READ_AT,

package/src/claude/cases/authoring.ts

@@ -42,6 +42,10 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
       'Write a brand-new docs page for the capture command, nothing under docs/ covers it yet.',
     expect: 'draft-docs',
   },
+  {
+    prompt: 'This project has no README.md at all, write one from scratch.',
+    expect: 'draft-readme',
+  },
   {
     prompt:
       'Write a context entry for the payments domain, there is no .claude/context page for it yet.',

package/src/claude/cases/claude-workflow.ts

@@ -79,6 +79,11 @@ export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
     prompt: 'Post a formal review with findings on that open pull request.',
     expect: 'claude-pr-review',
   },
+  {
+    prompt:
+      'The screencast draft is finished. Turn it into an actual video now.',
+    expect: 'canon-record',
+  },
   {
     prompt:
       'Look over everything that changed on this branch for bugs and edge cases.',

package/src/claude/cases/misc.ts

@@ -12,6 +12,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Show me a few different treatments for this callout so I can pick one by looking.',
     expect: 'draft-and-pick',
   },
+  {
+    prompt:
+      'This project has no logo yet. Draft one and give me a social card to go with it.',
+    expect: 'identity',
+  },
   {
     prompt: 'Fire up the dev server the way this project documents it.',
     expect: 'project-commands',
@@ -29,6 +34,11 @@ export const MISC_CASES: readonly SkillCase[] = [
     prompt: "This test just started failing and I don't know why yet.",
     expect: 'systematic-debugging',
   },
+  {
+    prompt:
+      "I'm about to write the retry helper we settled on and nothing covers it yet, so get the failing case in first.",
+    expect: 'test-first',
+  },
   {
     prompt: 'Does our github about text still match what the readme says?',
     expect: 'repo-metadata',

package/standards/readme.md

@@ -46,6 +46,8 @@ Scoped to the README at a repository root. A nested README documenting a folder,
 - Do not include license text. Reference the `LICENSE` file.
 - Do not include detailed contribution guidelines. Reference `CONTRIBUTING.md`.
 - Do not include extensive troubleshooting guides. Use a wiki or separate documentation.
+- A README that points to the project's own context entries instead of restating them satisfies the required list by routing rather than carrying. A repository documented in `docs/` or `.claude/context/` names the entry point and the listing command, then stops. The reader is one hop away, the same way `## Badges` treats zero as complete.
+- A README missing an H1, or whose headings restate the tool that scaffolded it rather than the project, is unedited generator output rather than a page anyone wrote. Draft over it. Nothing here asks a session to preserve a section a scaffold wrote and nobody replaced.
 
 ### Badges
 

package/tooling/astro/configs/eslint.config.js

@@ -50,10 +50,16 @@ export default defineConfig([
       ],
       'check-file/folder-naming-convention': [
         'error',
-        { 'src/**/!(__tests__|pages)': 'KEBAB_CASE' },
+        { 'src/**/!(__tests__)/': 'KEBAB_CASE' },
       ],
     },
   },
+  {
+    files: ['src/pages/**/*.{ts,tsx,astro}'],
+    rules: {
+      'check-file/folder-naming-convention': 'off',
+    },
+  },
   {
     files: ['**/*.{jsx,tsx}'],
     plugins: {

package/tooling/astro/reference.md

@@ -21,7 +21,7 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 - `vitest.config.ts`: uses `getViteConfig` from `astro/config` (not `mergeConfig`). jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `**/*.astro` in coverage excludes.
 - `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`. `DIST_PREBUILT` set in the environment drops the `build` half, running `bun run preview` alone against a `dist/` a prior CI job already produced.
 - `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom` in types, `@/` paths.
-- `eslint.config.js`: overrides the web layer. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention`'s `src/**/!(__tests__|pages)` pattern reaches no folder under a real ESLint run, `.astro`-only or otherwise. See `.claude/context/tooling.md` for the measurement.
+- `eslint.config.js`: overrides the web layer. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the whole `pages/` subtree, which carries its own off-block for the bracket-named dynamic routes and nested slug folders Astro's file-based routing produces. See `.claude/context/tooling.md` for the measurement.
 
 ## Typecheck
 

package/tooling/nextjs/configs/eslint.config.js

@@ -59,15 +59,16 @@ export default defineConfig([
       ],
       'check-file/folder-naming-convention': [
         'error',
-        { 'src/**/!(__tests__)': 'KEBAB_CASE' },
+        { 'src/**/!(__tests__)/': 'KEBAB_CASE' },
       ],
     },
   },
   {
-    // App Router route and layout files export non-component values (metadata, route handlers), which this rule flags as violations.
+    // App Router route and layout files export non-component values (metadata, route handlers) and use bracket, paren, and at-sign folder syntax (dynamic segments, route groups, parallel slots), which these rules flag as violations.
     files: ['src/app/**/*.{ts,tsx}'],
     rules: {
       'react-refresh/only-export-components': 'off',
+      'check-file/folder-naming-convention': 'off',
     },
   },
   {

package/tooling/nextjs/reference.md

@@ -19,7 +19,7 @@ The nextjs stack covers Next.js + TypeScript projects using the App Router. It s
 - `next.config.ts`: `agentRules: false` stops Next from regenerating `AGENTS.md`/`CLAUDE.md` on every run, which would otherwise compete with the root `CLAUDE.md`. `turbopack.root: import.meta.dirname` pins the workspace root, silencing Next's multi-lockfile inference warning in any checkout carrying more than one lockfile above the project, a worktree included.
 - `vitest.config.ts`: plain `defineConfig`, no `mergeConfig` or `getViteConfig` since Next has no Vite config to merge from. jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `.next/**` in test excludes.
 - `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `3000` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. `DIST_PREBUILT` drops the `build` half, matching the astro stack's flag.
-- `eslint.config.js`: overrides the web layer with `.next` and `next-env.d.ts` added to `globalIgnores`, keeping `react-hooks`/`react-refresh` since this stack still ships React components. `react-refresh/only-export-components` is `off` for `src/app/**`, since route and layout files export non-component values the rule would otherwise flag.
+- `eslint.config.js`: overrides the web layer with `.next` and `next-env.d.ts` added to `globalIgnores`, keeping `react-hooks`/`react-refresh` since this stack still ships React components. `react-refresh/only-export-components` is `off` for `src/app/**`, since route and layout files export non-component values the rule would otherwise flag. `check-file/folder-naming-convention` is `off` for the same subtree, since App Router's bracket, paren, and at-sign folder syntax (dynamic segments, route groups, parallel slots) fails `KEBAB_CASE`.
 
 ## Port
 

package/tooling/web/configs/eslint.config.js

@@ -57,7 +57,7 @@ export default defineConfig([
       ],
       'check-file/folder-naming-convention': [
         'error',
-        { 'src/**/!(__tests__)': 'KEBAB_CASE' },
+        { 'src/**/!(__tests__)/': 'KEBAB_CASE' },
       ],
     },
   },