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

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

@@ -1,6 +1,6 @@
 ---
 name: canon-cli
-description: Why the overwrite contract is stated before a sync runs, and why the skill reads rather than executes
+description: Why a session is pointed at the verb catalog, the reference docs, and the overwrite contract from one place, and why the skill reads rather than writes
 ---
 
 # Canon cli requirement
@@ -17,17 +17,20 @@ Being reachable is a separate problem from being right. This is a pure reference
 
 The two bodies now carrying an inline pointer are `claude-seed-sync` and `canon-operator`, each at the point it runs or prints an overwriting command.
 
+A third gap sits beside the first two, aimed at a different question. `canon --help` lists every top-level verb and `canon docs` emits the toolkit's own reference corpus, but no reference skill pointed a session at either. The one skill that does, `canon-operator`, is user-invoked only and reaches them as a side effect of its own orientation step. A session guessing at a verb's name, or restating what a doc already answers, is the same missing-fact failure the overwrite gap names.
+
 ## Must
 
 - State per surface and per command whether an existing file is overwritten, merged, written once, or left alone
 - Warn about a destructive run before it happens, naming the surface that will be lost
 - Name the section-preserving path for a standard or seed the project has customized
 - Defer to the toolkit's own context docs when they and this summary disagree, since the summary is a copy and they are the source
+- Point to `canon docs agents` for the verb catalog and to `canon docs` for the reference corpus, rather than restating either
 
 ## Must not
 
-- Run any `canon` command. The skill is read before acting.
-- Restate the full semantics. It is a target-session summary and the detail lives with its owner.
+- Run, or send the session to run, a `canon` command that writes or installs. The skill is read before acting on a sync.
+- Restate the verb catalog or a reference doc's content. Point to `canon docs agents` or `canon docs <topic>` instead. The overwrite table is this skill's one authored exception, and it too is a target-session summary, with the detail living with its owner.
 - Take a mention in a sibling's requirement file as an inbound route. The three bodies named in the gap above carry the pointer, and adding a fourth means editing that body rather than its requirement.
 
 ## Guards
@@ -39,3 +42,4 @@ The two bodies now carrying an inline pointer are `claude-seed-sync` and `canon-
 - Executing the sync, which the user runs or `canon-operator` routes
 - Reconciling a customized seed section by section: `claude-seed-sync`
 - Deciding which stack, rule, or standard a project should install, which the setup skills resolve from live catalogs
+- Diagnosing what a project is behind on, or executing the fix: `canon-operator`

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

@@ -1,11 +1,17 @@
 ---
 name: canon-cli
-description: Reference for what canon sync and install commands overwrite, merge, or leave untouched in a target project. Use before running `canon tooling`, `canon standards`, `canon claude sync`, or `canon init`, or when asked "will this overwrite my changes". Do NOT use to run the commands, only to know their effect.
+description: Reference for what a canon verb does before you run it. Run `canon docs agents` for the full command catalog, `canon docs` for any other reference doc, and read this skill's own table for what a sync or install command overwrites, merges, or leaves untouched in a target project. Use when asked "which canon command do I run", "is there a doc for X", "will this overwrite my changes", or before running `canon tooling`, `canon standards`, `canon claude sync`, or `canon init`. Do NOT use to execute a sync, an install, or a docs lookup, only to know which command answers the question.
 ---
 
 # Toolkit CLI contract
 
-What each `canon` sync or install command does to existing files in a target project. Consult before running one, then warn the user about anything destructive. This skill is reference only. It does not run commands.
+Consult before running an unfamiliar `canon` verb, before a sync or install, or when asked "will this overwrite my changes". This skill is reference only. It never runs a sync or an install.
+
+## Verb catalog and reference docs
+
+- Run `canon docs agents` for the full command catalog and invocation contract, rather than guessing at a verb from its name.
+- Run `canon docs list` for every other reference doc, then `canon docs <topic>` by name.
+- State neither list here. Both read live off the CLI, and a copy in this body ships on a different cadence than the commands it names.
 
 ## Overwrite contract
 

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/{context-draft → draft-context}/REQUIREMENT.md

@@ -1,5 +1,5 @@
 ---
-name: context-draft
+name: draft-context
 description: Why a brand-new .claude/context/<domain>.md entry needs a catalog collision check and a confirm step, not the refresh path claude-docs already owns
 ---
 
@@ -32,6 +32,6 @@ Without this skill, a session documenting a domain that has no context entry yet
 ## Out of scope
 
 - Refreshing an existing `.claude/context/<domain>.md` entry against a diff: `claude-docs`
-- Drafting a `.claude/wireframes/<surface>.md` file: `wireframe-draft`
-- Drafting a `docs/*.md` page: `docs-draft`
+- Drafting a `.claude/wireframes/<surface>.md` file: `draft-wireframes`
+- Drafting a `docs/*.md` page: `draft-docs`
 - Drafting a standard, a snippet, or a governance rule: `create-standard`, `create-snippet`, `create-rule`

package/claude/skills/{context-draft → draft-context}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: context-draft
+name: draft-context
 description: Drafts a brand-new `.claude/context/<domain>.md` entry against the context standard, checks the catalog for a name-or-topic collision, decides flat-file placement, confirms with the user, then writes. Use when asked to "write a context entry for X", "document the X domain", "add a context entry for X", or "create a .claude/context page for X" where no existing entry covers the domain. Do NOT use to refresh an existing entry against a diff, which is `claude-docs`.
 ---
 

package/claude/skills/{docs-draft → draft-docs}/REQUIREMENT.md

@@ -1,5 +1,5 @@
 ---
-name: docs-draft
+name: draft-docs
 description: Why a brand-new docs/*.md page needs a placement decision and a confirm step, not the rewrite path docs-sync already owns
 ---
 

package/claude/skills/{docs-draft → draft-docs}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: docs-draft
+name: draft-docs
 description: Drafts a brand-new `docs/*.md` page against the docs standard, decides its placement in the existing catalog, confirms with the user, then writes. Use when asked to "add a docs page for X", "write a new doc for X", "document X under docs/", or "create a docs page for X" where no existing page covers the topic. Do NOT use to rewrite or sync an existing `docs/*.md` section against a diff, which is `docs-sync`.
 ---
 

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/{wireframe-draft → draft-wireframes}/REQUIREMENT.md

@@ -1,5 +1,5 @@
 ---
-name: wireframe-draft
+name: draft-wireframes
 description: Why a brand-new .claude/wireframes/<surface>.md file needs a real draft and a tier-detect step, not the stub the wireframe-sweep already writes
 ---
 
@@ -32,7 +32,7 @@ Without this skill, a session drafting a wireframe for a surface with no file ye
 ## Out of scope
 
 - Stubbing a surface a diff touched, or reporting drift in an existing wireframe against a diff: `claude/skills/claude-docs/references/wireframe-sweep.md`
-- Drafting a `.claude/context/<domain>.md` entry: `context-draft`
-- Drafting a `docs/*.md` page: `docs-draft`
+- Drafting a `.claude/context/<domain>.md` entry: `draft-context`
+- Drafting a `docs/*.md` page: `draft-docs`
 - Drafting a standard, a snippet, or a governance rule: `create-standard`, `create-snippet`, `create-rule`
 - Building or wiring an actual tier-1 or tier-2 rendering pipeline: the visual design workflow's own tier guidance, out of reach of a hand-drafting skill

package/claude/skills/{wireframe-draft → draft-wireframes}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wireframe-draft
+name: draft-wireframes
 description: Drafts a brand-new `.claude/wireframes/<surface>.md` file against the wireframes standard, walks the tree for a name collision, detects an existing higher visual-design tier without building one, confirms with the user, then writes. Use when asked to "draft a wireframe for X", "write the wireframe for this surface", "add a .claude/wireframes entry for X", or "wireframe this screen" where no surface file covers it yet. Do NOT use to fix a stale TODO stub or report wireframe drift against a diff, which is `claude-docs`'s wireframe-sweep step.
 ---
 

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