@erclx/canon 5.42.0 → 5.44.0

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

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

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

@@ -65,9 +65,9 @@ If neither form is present, stop: `❌ <path> carries no plan sections. A plan l
 
 ### Unanswered questions
 
-The plan's sections and answer contract are fixed by `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`. A blank `- Answer:` accepts the `- Suggested:` line above it, so an unanswered question is a decision this run executes rather than a reason to stop.
+Read `## The suggested-and-answer contract` in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md` before acting on a question, for what it resolves to and the form an override takes. A question left open is a decision this run executes rather than a reason to stop.
 
-When this run decides against a suggestion, rewrite its line as `overridden at execution to <pick>,` plus the measurement, leaving `- Answer:` blank. Put the same deviation in one line under the open task's `## Findings`, opening with the bold source-and-date label `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
+Open the task's `## Findings` line for an override with the bold source-and-date label `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
 
 ## Step 2: implement
 
@@ -107,7 +107,7 @@ When the plan's `**Constraints:**` carry a `Fan-in member of` bullet, push the b
 
 If the diff touches UI files (JSX, TSX, Vue, Svelte, HTML, or CSS under `src/`), invoke `canon:ui-checklist`, then continue to Step 6 whatever it returns, in every run. The Step 6 draft mark holds the merge, so a stop here protects nothing.
 
-When it produces a checklist, read `${CLAUDE_SKILL_DIR}/references/ui-checklist.md` for the counts to hold before `pr-evidence` removes the file.
+When it produces a checklist, read `${CLAUDE_SKILL_DIR}/references/ui-checklist.md` for the counts to hold before `pr-evidence` removes the file. A diff passing this test also owes the preview server `role-worker` states, started before Step 6.
 
 ## Step 6: ship
 

package/claude/skills/backlog-triage/references/apply.md

@@ -25,12 +25,12 @@ An item already applied, by the test in the skill's Step 1, is skipped silently,
 
 Take the task stem from the item heading. Every verdict leaves the folder slug on its task, which is how Step 1 and `task-board`'s unlinked-origin scan both see the folder as acted on.
 
-| Verdict | Command and board write                                                                                                                                 |
-| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| decline | `canon tasks decline <stem> --reason "<reason>, backlog triage <slug> item <cluster>#<n>" --json`, which clears the backlog line                        |
-| archive | `canon tasks outcome <stem> --close <p> ... --json` for the named positions, then `canon tasks archive <stem> --json`                                   |
-| keep    | Append the `## Findings` line naming what reproduced, leaving the backlog line                                                                          |
-| promote | Move the backlog line to the bottom of `## Needs a plan` in `.canon/tasks/priority.md`, its `Waiting on` cell stating what cleared and ending in `last` |
+| Verdict | Command and board write                                                                                                          |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| decline | `canon tasks decline <stem> --reason "<reason>, backlog triage <slug> item <cluster>#<n>" --json`, which clears the backlog line |
+| archive | `canon tasks outcome <stem> --close <p> ... --json` for the named positions, then `canon tasks archive <stem> --json`            |
+| keep    | Append the `## Findings` line naming what reproduced, leaving the backlog line                                                   |
+| promote | `canon tasks place <stem> --group needs-a-plan --bottom --waiting "<what cleared>. Last" --json`, which clears the backlog line  |
 
 ### Archive and missing files
 

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

@@ -43,11 +43,11 @@ Each verb here has a skill that owns the job. Load the skill rather than driving
 
 | Job                                          | Verb                | Skill                       |
 | -------------------------------------------- | ------------------- | --------------------------- |
-| Render the design system                     | `canon design`      | `canon:draft-figure`        |
-| Render a slide deck                          | `canon slides`      | `canon:draft-slides`        |
-| Render an HTML source to a PNG               | `canon capture`     | `canon:draft-identity`      |
+| Render the design system                     | `canon design`      | `canon:draw-figure`         |
+| Render a slide deck                          | `canon slides`      | `canon:make-deck`           |
+| Render an HTML source to a PNG               | `canon capture`     | `canon:design-identity`     |
 | Serve a directory and print the link         | `canon serve`       | none                        |
-| Record a running app                         | `canon demo`        | `canon:draft-screencast`    |
+| Record a running app                         | `canon demo`        | `canon:script-screencast`   |
 | Report one computed property across routes   | `canon inventory`   | `canon:target-check`        |
 | Walk a page through interactions and measure | `canon drive`       | `canon:ux-measure`          |
 | Fetch a YouTube transcript                   | `canon transcripts` | `canon:youtube-transcripts` |

package/claude/skills/canvas-board/REQUIREMENT.md

@@ -43,6 +43,6 @@ When the operator picks a frame, the session leaves the decision on the canvas a
 
 - What the canvas verbs do internally, which is the CLI's own contract
 - The content format a frame and a layout take, which the canvas standard fixes
-- Drafting candidates for a taste decision and taking the pick, which `draft-and-pick` runs on this canvas through the same verbs
+- Drafting candidates for a taste decision and taking the pick, which `pick-by-eye` runs on this canvas through the same verbs
 - Tracing reference images into design values or writing the design document from code, which no skill owns now
 - Backing up the canvas folder off one disk

package/claude/skills/canvas-board/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: canvas-board
-description: Drives the local design canvas, where pages hold HTML frames the operator sees, drags, selects, and edits in the browser. Starts the canvas when it is not running, confirms the live shell loads, makes pages and frames, edits a frame through its file, reads what the operator selected or restyled, captures finished frames, and carries a picked direction into the project's design document. Use when asked to "open the canvas", "put this on the canvas", "draw a frame for X", "change the one I selected", "what did I pick", "capture this frame", or "move that frame on the canvas". Do NOT use to draft candidates for a taste decision, which is `draft-and-pick`.
+description: Drives the local design canvas, where pages hold HTML frames the operator sees, drags, selects, and edits in the browser. Starts the canvas when it is not running, confirms the live shell loads, makes pages and frames, edits a frame through its file, reads what the operator selected or restyled, captures finished frames, and carries a picked direction into the project's design document. Use when asked to "open the canvas", "put this on the canvas", "draw a frame for X", "change the one I selected", "what did I pick", "capture this frame", or "move that frame on the canvas". Do NOT use to draft candidates for a taste decision, which is `pick-by-eye`.
 metadata:
   family: decide
 ---

package/claude/skills/ci-workflow/REQUIREMENT.md

@@ -21,7 +21,8 @@ A cache keyed on a static string serves a stale browser or toolchain after a ver
 - Start the checks that share setup in one job and split them only once a run log puts the gate past roughly two minutes
 - Pin every action to a tag that cannot cross a major version
 - Key a cache on the version string of the thing it caches
-- Give every workflow a manual trigger beside its primary one
+- Give every workflow a manual trigger beside its primary one, except one that commits back, where a manual run has no branch to land on
+- Default the token to read-only and grant a write scope only on the job that needs it
 - Bound artifact upload to failures and set an expiry on it
 
 ## Must not

package/claude/skills/ci-workflow/SKILL.md

@@ -17,7 +17,8 @@ Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job ex
 
 ## Workflow setup
 
-- Include `workflow_dispatch` on every workflow alongside the primary trigger.
+- Include `workflow_dispatch` alongside the primary trigger, except on a commit-back workflow, where a manual run has no branch to commit onto and would pass while doing nothing.
+- Set `permissions: contents: read` at the top level, and grant a write scope only on the job that needs it.
 - Pin all actions to major version tags (`@v4`, never `@latest` or `@main`).
 - Use `runs-on: ubuntu-latest` for all jobs.
 
@@ -50,6 +51,14 @@ Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job ex
 - Install with `bun install --frozen-lockfile`.
 - Cache Playwright browsers keyed on the Playwright version string, never a static key.
 
+## Commit-back
+
+A workflow that pushes a regenerated file onto the pull request branch takes these on top of the setup above.
+
+- Set the concurrency group on the ref so a newer push cancels the run committing onto a stale head.
+- Set `HUSKY: 0` on the commit step when the runner lacks a tool a hook shells out to.
+- Fail a template's first step while a path list still holds its placeholder, so an unfinished install fails loudly rather than never firing.
+
 ## Template
 
 Load `${CLAUDE_SKILL_DIR}/references/workflows.md` for the base workflow template. Adapt it to the project's stack, test commands, and build output. Add or remove jobs as needed. The template already carries the folded shape, and the split beside it applies once the granularity rule above calls for it.
@@ -58,7 +67,8 @@ Load `${CLAUDE_SKILL_DIR}/references/workflows.md` for the base workflow templat
 
 Before responding, verify:
 
-- `workflow_dispatch` is present alongside the primary trigger.
+- `workflow_dispatch` is present alongside the primary trigger, and absent from a commit-back workflow.
+- The top-level `permissions` reads `contents: read`, and every write scope sits on a job.
 - All actions pinned to major version tags, no `@latest` or `@main`.
 - A new pipeline folds static, unit, and build into one job, and a gate a run log put past two minutes gives them no `needs` so they run in parallel.
 - Every name in a `needs` matches a job declared in the same file. E2E names the artifact producer, release and deploy name E2E.

package/claude/skills/ci-workflow/references/workflows.md

@@ -12,12 +12,15 @@ on:
     branches: [main]
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   checks:
     name: '🛡️ Checks'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
@@ -25,7 +28,7 @@ jobs:
       - run: bun run check
       - run: bun run test
       - run: bun run build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: build-output
           path: dist/
@@ -35,17 +38,17 @@ jobs:
     needs: checks
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
       - run: bun install --frozen-lockfile
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: build-output
           path: dist/
       - run: bun run test:e2e
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         if: failure()
         with:
           name: e2e-results
@@ -63,7 +66,7 @@ jobs:
     name: '🛡️ Static Checks'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
@@ -74,7 +77,7 @@ jobs:
     name: '🧪 Unit Tests'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
@@ -85,13 +88,13 @@ jobs:
     name: '📦 Build Check'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
       - run: bun install --frozen-lockfile
       - run: bun run build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: build-output
           path: dist/

package/claude/skills/context-fold/references/context.md

@@ -28,7 +28,7 @@ Does not govern:
 
 - Product scope, goals, and non-goals: `requirements.md`
 - Path-scoped coding rules: `rule.md`
-- Figures and architecture views, which answer structure questions an entry hands off: the `draft-figure` skill
+- Figures and architecture views, which answer structure questions an entry hands off: the `draw-figure` skill
 - The consumer-facing reference under `docs/`, whose reader is operating the project without the source open: `docs.md`
 
 ## Organizing principle

package/claude/skills/create-rule/SKILL.md

@@ -80,6 +80,7 @@ Title casing is sentence case, with proper nouns keeping their own casing (`# Ty
 Read `${CLAUDE_SKILL_DIR}/references/checklist.md` and run every bullet of the written rule through it, along with the shape limits and the content test in `rule.md`.
 
 - Rewrite a bullet marked revise and cut one marked drop, then run the checklist again over what changed
+- Run `canon gov audit .claude/rules/project/<subdir>/<slug>.md` and fix every finding it reports, since the shape limits are counts the verb takes rather than a judgment
 - Report the verdict counts with the path, and name any bullet kept against a criterion with the reason
 
 ## After writing

package/claude/skills/create-skill/REQUIREMENT.md

@@ -24,7 +24,7 @@ A fifth failure is the confirmation itself. A worker running a plan that adds a
 - Draft the sibling `REQUIREMENT.md` beside the body, from what the skill is for rather than from the drafted body
 - Confirm the name and both files with the user before writing, where a person is present to answer. The name is the routing key and a folder that disagrees with its frontmatter fails silently. Where nobody is present, record the three answers and both paths in the output and write.
 - Write to the conventional skills path, so discovery finds it without configuration. That is `.claude/skills/` in a target project. In the toolkit's own checkout, which the project root's `claude/.claude-plugin/plugin.json` marks, an `internal-*` skill goes under `.claude/skills/` and a plugin skill under `claude/skills/`
-- Leave the skills audit's dated-provenance check clean for the new folder before reporting it, with each incident moved to the requirement's `Gap`
+- Leave the skills audit's dated-provenance check clean for the new folder before reporting it, with each incident cut and left to git
 
 ## Must not
 

package/claude/skills/create-skill/SKILL.md

@@ -38,7 +38,7 @@ Read these in the same pass:
    - Does the body carry a procedure a session would get wrong from first principles? A one-line wrapper around a single command needs no skill.
    - Will anything invoke it other than the author typing its name? Carry this one into the drafted `REQUIREMENT.md`'s `Must not` section as a review criterion instead, since nothing can answer it before the skill has run.
    - Tell the user and stop when the first answer is yes or the second is no. A non-interactive run stops on both too, reporting which question failed and writing no folder.
-2. Draft the full `SKILL.md` from the user's description, stating the current rule alone. An incident and the date it happened belong in the requirement's `Gap`, not in the body or a reference.
+2. Draft the full `SKILL.md` from the user's description, stating the current rule alone. An incident and the date it happened stay in git, never in the body, a reference, or the requirement.
 3. Draft the sibling `REQUIREMENT.md` from what the skill is for, in the shape the requirement standard states.
    - Write the gaps from the user's description rather than from the drafted body, since a requirement derived from the body records whatever the draft overfitted to.
 4. Confirm the skill name and both files with the user before writing, when a person can answer.
@@ -53,7 +53,7 @@ Steps 5 to 7 write the folder and check what landed before the run reports.
    - The root is `.claude/skills/` in a target project.
    - Where the project root holds `claude/.claude-plugin/plugin.json`, which is the toolkit's own checkout, an `internal-*` skill goes under `.claude/skills/` and every other skill under `claude/skills/`, since the plugin ships that tree.
 6. Run `canon claude skills audit --json` and read `findings.datedProvenance` for rows under `<root>/<name>/`.
-   - Move each row's incident into `REQUIREMENT.md` under `Gap`, cut the date from the file the row names, and re-run until no row names the folder.
+   - Cut each row's date and incident from the file the row names, leaving them to git, and re-run until no row names the folder.
    - When `canon` does not resolve or its record carries no `datedProvenance` key, say the check did not run rather than reporting the skill clean.
 7. Run `canon markdown audit <root>/<name>/` over the new body and any references, and fix every ban and density finding it reports.
    - Re-run it until it reports none, since every file in the folder is this run's draft.

package/claude/skills/create-skill/references/skill-requirement.md

@@ -35,12 +35,36 @@ A requirement that leaves any of the three open is non-conforming regardless of
 - Write the gaps from what the skill is for, then compare the body against them
 - A requirement derived from the body records the body's accidents as the requirement, and misinforms a reader who reads it in place of the body
 
+## Sections
+
+The file carries these H2s in this order and no others. `canon claude skills audit` reports a missing Gap or Must and a Guards heading.
+
+| Section        | When                                      | Holds                                                         |
+| -------------- | ----------------------------------------- | ------------------------------------------------------------- |
+| `Gap`          | Always                                    | The failures a session hits today without the skill, as prose |
+| `Must`         | Always                                    | The outcomes that close those failures, one per bullet        |
+| `Must not`     | When a behavior closes a gap and is wrong | That behavior, one per bullet                                 |
+| `Out of scope` | When a sibling owns an adjacent behavior  | The behavior and the skill that owns it                       |
+
+`Guards` is retired. A refusal condition is a `Must not` bullet, and the message it prints belongs to the body.
+
+## Caps
+
+The audit reports each cap it finds breached, and a rewrite batch turns the report into a gate for the files it brings under.
+
+- Each list holds at most 5 bullets. A sixth `Must` is a sign the skill does two jobs or the list restates its steps.
+- The file holds at most 400 words of body, frontmatter excluded
+- Gap carries no `YYYY-MM-DD` date and no `#NNN` issue or pull request number outside a code span
+
 ## Content
 
-- State each gap as an observed failure, not an intent. "Without this skill a session invents its own filename" can be shown wrong. "This skill helps manage tasks" cannot fail, so it constrains nothing.
-- Trace everything under `## Must` to a stated gap. A `Must` with no gap behind it is the padding the file exists to prevent.
-- Keep it high level. A requirement that outgrows one file has stopped being a requirement, and `references/` already holds detail.
-- Use `name` and `description` frontmatter, matching `SKILL.md` so the pair is consistent.
+- State each gap as a failure a session hits today, in the present tense. "Without this skill a session invents its own filename" can be shown wrong.
+- Never state a gap as an intent. "This skill helps manage tasks" cannot fail, so it constrains nothing.
+- Keep history out of Gap. The incident, its date, and the pull request that earned a rule stay in git, where `git log` on the file finds them.
+- Write each `Must` as an outcome a reader can check against the body, never as a step the body takes. "The committed set is exactly the staged set" is an outcome.
+- Trace every `Must` to a stated gap. A `Must` with no gap behind it is the padding the file exists to prevent.
+
+The frontmatter carries `name` and `description`, matching `SKILL.md` so the pair is consistent.
 
 ## Template
 
@@ -54,21 +78,56 @@ description: <one line, distinct from the SKILL.md description>
 
 ## Gap
 
-Without this skill, a session <observed failure>, <observed failure>.
+Without this skill, a session <failure it hits today>. <A second failure, when there is one>.
 
 ## Must
 
-- <behavior that closes a named gap>
+- <outcome that closes a named failure>
 
 ## Must not
 
 - <behavior that would be wrong even though it closes a gap>
 
-## Guards
+## Out of scope
+
+- <adjacent behavior>, which `<sibling-skill>` owns
+```
+
+### Worked example
+
+`git-commit`'s requirement in this shape, at 167 words as the audit counts them.
+
+```markdown
+---
+name: git-commit
+description: What commit generation is for, the gaps it closes, and where the family boundary sits
+---
+
+# Git commit requirement
+
+## Gap
+
+Without this skill, a commit message takes whatever shape the session picks. The type and scope drift from the history's convention, the subject runs past the log's width, and a lockfile diff crowds out the change the message should describe.
+
+A plain request to commit also reaches the grouping sibling, which restages whole files, so a hunk-level selection ships wider than the user reviewed.
+
+## Must
+
+- The message follows the commit format and versioning references
+- The message describes the staged diff with lockfiles excluded
+- The user sees the message and its length before the commit runs
+- The committed set is exactly the staged set
+- The description claims single-concern and hunk-level staged sets, and names `git-stage` for a mixed one
+
+## Must not
 
-- <the refusal condition and its message>
+- Stage or unstage anything
+- Commit when nothing is staged
+- Emit anything after the result line
 
 ## Out of scope
 
-- <the adjacent thing this deliberately does not cover, and what covers it>
+- Splitting a mixed diff into several commits, which `git-stage` owns
+- Naming a branch, which `git-branch` owns
+- Pushing or opening a pull request, which `git-pr` owns
 ```

package/claude/skills/create-skill/references/skill.md

@@ -132,7 +132,7 @@ A body holds behavioral rules and pointers to reference docs, front-loading the
 
 ### Current rule and grouping
 
-State the current rule only, in the body and in every file under `references/`. The incident and the date that earned a rule go in `REQUIREMENT.md` under `Gap`, or stay in git, and a date inside a fence or a code span is example data and stays.
+State the current rule only, in the body and in every file under `references/`. The incident and the date that earned a rule stay in git, and a date inside a fence or a code span is example data and stays.
 
 - Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
 - Group bullets under H2 headings by concern, keeping dos and don'ts together rather than in flat rules and constraints sections

package/claude/skills/decision-escalate/SKILL.md

@@ -70,8 +70,7 @@ Restate each pick in one line, then continue the work.
 
 A pick that changes a written artifact goes into it under the rule its own standard sets, and a pick that settles nothing written stays in the session.
 
-- An answer to an open plan question rewrites its `- Suggested:` line to the pick, naming the operator as source, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`
-- Leave the `- Answer:` slot blank, since the standard bars a session from filling it, and the blank resolves to the rewritten suggestion
+- Record an answer to an open plan question per `### Overrides and settled questions` in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`
 
 Output after the answers land:
 

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

@@ -0,0 +1,40 @@
+---
+name: design-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
+---
+
+# Design 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 `pick-by-eye`'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 `pick-by-eye`'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 `pick-by-eye`'s render, hand-off, pick, or loop mechanics
+- Add a `## Logo` section to `claude/skills/canvas-board/references/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 `pick-by-eye`, `canon capture`, or `canon design render`. This skill composes all three 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 `claude/skills/canvas-board/references/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 `ux-audit` owns

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

@@ -0,0 +1,138 @@
+---
+name: design-identity
+description: Drafts a project's logo mark through pick-by-eye'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.
+metadata:
+  family: generate
+---
+
+# Design 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:
+
+- `canon/DESIGN.md`: the `## Overview` paragraph and the role intents under `## Colors` and `## Typography`, read as `## Personality` and `## Color` in an older record
+- The stylesheet `canon/DESIGN.md`'s lead names: the color and type values behind those roles
+- `canon/REQUIREMENTS.md`: the `## Personality` paragraph, when `canon/DESIGN.md` carries none
+- `CLAUDE.md`: the project's stated voice, when neither file above carries a personality signal
+
+No signal from any of these is not a stop. Draft against a neutral default, and mark each guessed color and type value with a `/* ? verify */` comment beside its declaration in the `.mark` and `.card` markup, since the design document carries no value to 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, and Step 6 writes the vector source at `favicon.svg` on either branch. Announce which of the two decided the sequence.
+
+## Step 3: detect the write folder
+
+A root-only check misses a site kept in a subfolder, and a Next project keeps its favicon under the App Router with no `public/` at all. Both would fall through to the root while the announcement reads as detected, so walk one level down and know that convention.
+
+Read both, from the project root:
+
+```bash
+find . -maxdepth 3 \( -name node_modules -o -name .git -o -name dist -o -name .astro \) -prune -o -type d \( -name public -o -name static \) -print | sort
+find . -maxdepth 4 \( -name node_modules -o -name .git \) -prune -o -type d -path '*/src/app' -print | sort
+```
+
+Take the first tier that answers:
+
+1. A root `public/` or `static/`.
+2. A `public/` or `static/` one level down, such as `web/public/`. Of several, take the shallowest, then the one whose parent holds the project's framework config.
+3. A `src/app/` folder, at the root or one level down, which is the Next App Router convention. Take the folder itself, not a `public/` beside it.
+4. A stack-declared asset folder, where the project's own config names one.
+5. The project root, which is the fallback rather than a detection.
+
+Announce which tier decided, naming the tier rather than the path alone, so the operator can move the files where the project's convention differs. On tier 5 say the detection found nothing and the root is a fallback.
+
+## Step 4: name the decision and the arms
+
+Follow `${CLAUDE_SKILL_DIR}/../pick-by-eye/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 inside the full 1200x630 card frame, mark and type together, and add its canvas frame at `--width 1200 --height 630`, so one pick settles shape and composition
+- Arm 0 is the current mark when the Step 3 folder 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
+
+## Step 5: draft, render, pick, and loop
+
+Follow `${CLAUDE_SKILL_DIR}/../pick-by-eye/SKILL.md` Steps 2 through 5 against the arms from Step 4: draft the arms as frames on a canvas page, render and hand off, take the pick, and loop on it.
+
+The final icon and card renders below are not arms, so they stay off the canvas. Call the folder they render from `<dest>`, being `.canon/tmp/<slug>/` under the slug `pick-by-eye` Step 1 derived, which is where this project puts every temporary write.
+
+## Step 6: finalize the mark and the icons
+
+This step and Step 7 replace `pick-by-eye`'s own Step 6 items 1 and 2, since the pick here produces several final files rather than one applied surface. Its archive capture, its page delete, and its server stop still run, after Step 7.
+
+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 `icon-<w>x<h>.html` page per Step 2 size, carrying the picked `.mark` markup in an element with the shared class `.render`.
+3. Declare each `.render` element at `<w>/2` by `<h>/2`, since `canon capture` screenshots at a fixed 2x scale and the PNG then lands on the target size.
+4. Declare no font on them. Each holds the mark alone, and `canon capture` skips the font check on an element with no text, where `system-ui` would be refused.
+5. Render the batch:
+
+   ```bash
+   canon capture <dest>/render --selector .render --out <write-folder>
+   ```
+
+6. Report each written file's path and the dimensions `canon capture` printed, confirming each equals its Step 2 target rather than half of it.
+
+The card leaves this batch and takes Step 7 instead. An icon is the mark alone and a scratch page renders it faithfully, where the card composes the mark with the project's own type and color, which a scratch page can only copy.
+
+## Step 7: write the card as a route and capture it through the server
+
+A card captured from a page this run deletes leaves a PNG and nothing that produced it, so renaming the project means another pick loop to move one string. Write the composition into a route the project keeps, and capture it through a running server so it reads the real stylesheet, tokens, and fonts.
+
+This is Astro-shaped for now, because Astro is the one web stack whose config gives a route a structural build exclusion. A project already holding the card route scaffold takes the route path, and everything else takes the page path. Say which one decided, since the two leave the project different things.
+
+### The route path
+
+Read `${CLAUDE_SKILL_DIR}/references/card-route.md` on reaching this path, for the scaffold check, the message to give when it is missing, and the write, serve, and capture sequence. A project with no scaffold skips it.
+
+### The page path
+
+Where the project holds no route to write into, write `og-image.html` into `<dest>/render/` with its `.render` wrapper sized 600x315, then capture that one page:
+
+```bash
+canon capture <dest>/render/og-image.html --selector .render --out <write-folder>
+```
+
+It takes its own call because Step 6's batch is already captured by the time this step picks a path. Say that the card shipped as a PNG with no source, and that the project gains one when it grows a route to hold the composition.
+
+### Closing the scratch folder and the canvas
+
+Delete `<dest>` once both captures land, then close the canvas through `pick-by-eye` Step 6 items 3 to 8, which archive every arm and delete the pages the run added. The route is not a leftover variant, since it holds the arm the operator picked.
+
+A project whose card was generated before this route existed keeps its PNG. Say so rather than regenerating it, since the pick loop spends attention on a file nobody complained about, and the next real edit picks up the route.
+
+## Response format
+
+```plaintext
+📝 Wrote <write-folder>/favicon.svg
+📝 Wrote <write-folder>/icon-16x16.png (16x16)
+📝 Wrote card-src/pages/og-card.astro (route path only)
+📝 Wrote <write-folder>/og-image.png (1200x630)
+
+Write folder: <tier that decided>. Move the files if this project's own convention differs.
+Card source: <the route, captured through the card server|a scratch page, since this project holds no card route>.
+```
+
+## What this delegates
+
+Cite these rather than restating them.
+
+- `pick-by-eye` owns Steps 1 through 5 of the render-and-pick loop, cited above
+- `canon:canvas-board` carries a picked direction into `canon/DESIGN.md`. This skill only reads it.
+- `canon capture` owns the render mechanics, its font refusal, its fixed 2x scale, and its reported dimensions. It reads an `http(s)://` source, where `--out` names the PNG.
+- The `astro` tooling stack owns the card route's scaffold, its second config, and the exclusion check, read with `canon tooling reference astro`. This skill writes into the route and never reshapes it.

package/claude/skills/{draft-identity → design-identity}/references/card-route.md

@@ -1,11 +1,11 @@
 ---
 title: Card route path
-description: How draft-identity writes the picked card composition into a project's existing Astro card route and captures it through the card server
+description: How design-identity writes the picked card composition into a project's existing Astro card route and captures it through the card server
 ---
 
 # Card route path
 
-Applies to Step 7 of `draft-identity` when the project already holds the card route scaffold. A project without it takes the page path in the skill body instead.
+Applies to Step 7 of `design-identity` when the project already holds the card route scaffold. A project without it takes the page path in the skill body instead.
 
 ## The scaffold