@erclx/canon 5.40.0 → 5.42.0

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

@@ -5,6 +5,8 @@ description: Skill structure and authoring rules for Claude Code
 
 # Claude skill reference
 
+Checked against the [Claude Code skills](https://code.claude.com/docs/en/skills) and [skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) pages on `2026-10-18`.
+
 ## Contents
 
 - [Overview](#overview)
@@ -26,7 +28,7 @@ Skills give Claude Code domain-specific constraints and rules inline, so it can
 
 ## Scope
 
-Governs a skill folder under `skills/` as one artifact: `SKILL.md`, its siblings `REQUIREMENT.md` and `EVAL.md`, and the bundled reference, script, and asset folders beside them.
+Governs a skill folder under `skills/` as one artifact, being `SKILL.md`, its siblings `REQUIREMENT.md` and `EVAL.md`, and the bundled reference, script, and asset folders beside them.
 
 Does not govern:
 
@@ -37,7 +39,7 @@ Does not govern:
 - **`rule.md`**: path-scoped coding rules, which load on a file match rather than on a request match
 - **the `write-human` skill**: voice, rhythm, and sentence construction in a skill body
 - **`markdown.md`**: punctuation, formatting, and word choice in a skill body
-- **`slug.md`**: the transform from a branch name to a slug a skill carries in a filename
+- **`slug.md`**: the transform from a branch name to a filename slug
 - **the `create-skill` skill and the creation-time bullet in the `skill` governance rule**: whether a new skill earns its place, by the three-question test
 
 ## Changing a skill
@@ -51,11 +53,13 @@ Answer all four before editing, and carry the answers into wherever the change i
 
 ## Whether a rule belongs beside the skill
 
-A skill fires when a session invokes it or its description matches the request. A path-scoped rule fires when a session reads or writes a file matching its glob, with no decision from the session at all. The rule is the floor and the skill is the depth.
+A skill fires when a session invokes it or its description matches the request. A path-scoped rule fires when a session reads or writes a file matching its glob, with no session decision. The rule is the floor and the skill is the depth.
 
-Run the two-part test over what the body states before calling the skill finished. Does the invariant fire when a specific path is edited, and does violating it ship silently? An invariant passing both halves belongs in a rule as well, since a session that never invoked the skill still edits that path. An invariant failing either half stays here, which is most of a body.
+- Run the two-part test over the body before calling the skill done. Does the invariant fire when a specific path is edited, and does violating it ship silently?
+- An invariant passing both halves moves to a rule, since a session that never invoked the skill still edits that path. It stays here when this skill creates the file the rule globs.
+- An invariant failing either half stays here, which is most of a body
 
-Write that rule to the shape `rule.md` sets and leave the procedure here, since the two carry one invariant at two depths rather than two copies of it. Nothing checks the split.
+Write that rule to the shape `rule.md` sets, keeping one copy of each invariant. A skill that only edits existing files points at the rule.
 
 ## Skill types
 
@@ -89,87 +93,102 @@ allowed-tools: <tools required>
 
 ## Structure
 
-- Skill is a folder named in kebab-case containing `SKILL.md` (required), `REQUIREMENT.md` (required), `EVAL.md` (optional), `scripts/` (optional), `references/` (optional), `assets/` (optional)
-- Create a new skill with its `REQUIREMENT.md` beside it, even where nobody contests its scope. A requirement present for some skills and absent for others cannot be scanned, since an absence reads as a gap rather than as a verdict
-- Name a file sitting directly in the skill folder in capitals and a bundled folder in lowercase, so the parts a reader opens are distinct from the ones a skill loads
+A skill is a folder named in kebab-case. It holds `SKILL.md` and `REQUIREMENT.md`, both required, and maybe `EVAL.md`, `scripts/`, `references/`, and `assets/`.
+
+- Create a new skill with its `REQUIREMENT.md` beside it, even where nobody contests its scope, since an absence reads as a gap rather than as a verdict
+- Name a file sitting directly in the skill folder in capitals and a bundled folder in lowercase, so the parts a reader opens differ from the ones a skill loads
 - `EVAL.md` holds prompts and a judging rubric a person runs by hand, since the automated `claude plugin eval` runner is gated in early access
 
 ### Folder and file rules
 
+The loader reads the folder name as the skill name, so the name follows the same casing everywhere.
+
 - `SKILL.md` must start with YAML frontmatter between `---` delimiters
 - No `README.md` inside the skill folder
 - No spaces, capitals, or underscores in folder or skill name
 
 ## Frontmatter
 
-- **`name`** (required): kebab-case, matches folder name, no spaces or capitals
-- **`description`** (required): what it does + when to use it, under 1024 chars, no XML tags
-- **`disable-model-invocation: true`**: user-invoked only, Claude will not auto-trigger. Set it on a skill that starts a process the operator owns, never on one reachable by a matched trigger.
-- **`allowed-tools`**: restrict tool access when the skill is active
-- **`metadata`**: optional key-value pairs (`author`, `version`, `mcp-server`)
-- **`metadata.family`** (required on a skill under `claude/skills/`): the skill map group the skill's row sits under, as one key from `families` in `canon claude skills list --json`. A skill under `.claude/skills/` takes none.
+Read `skill-frontmatter.md` for the required and optional fields, their limits, and which keys an upload accepts.
 
 ## Description
 
 - Structure: `[What it does] + [When to use it] + [Key trigger phrases]`, quoting phrases users would say
 - Be specific, not vague. Claude routes based on this field alone.
-- Add negative triggers if skill is over-triggering: `Do NOT use for X`
+- Write in the third person, since the description is injected into the system prompt. Write "Reviews code" over "I review code".
+- Add negative triggers if skill is over-triggering: `Do NOT use for X`. That form is canon's own, and Anthropic's pages do not mention it.
 
 ## Body
 
 ### Rule content and scope
 
+A body holds behavioral rules and pointers to reference docs, front-loading the critical ones. Narrative about what files are or how the system works belongs in `docs/`.
+
 - Use imperative voice throughout, and sentence case for every heading
-- Front-load critical instructions
-- Contain only behavioral rules (what to do, what not to do) and pointers to reference docs. Narrative descriptions of what files are or how the system works belong in `docs/`, not in the skill body.
-- State rules, not inventories. Reference docs for lists that change, and phrase a rule as a ban on the forbidden shape rather than an enumeration of allowed options, so it stays stable as categories change.
+- State rules, not inventories. Reference docs for lists that change.
+- Phrase a rule as a ban on the forbidden shape rather than an enumeration of allowed options, so it stays stable as categories change
+- When referencing project files, include "from the project root" in the read instruction
+- Run independent operations, such as file reads and shell commands, in parallel to reduce latency
 
-#### Current rule and grouping
+### 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.
 
 - Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
-- 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. A date inside a fence or a code span is example data and stays.
-- Group bullets under H2 headings by domain concern. Keep dos and don'ts together under the topic they belong to rather than splitting them into flat rules and constraints sections.
+- Group bullets under H2 headings by concern, keeping dos and don'ts together rather than in flat rules and constraints sections
 - One actionable constraint per bullet. Prefer the `X over Y` form for preferences.
 
-#### Examples and density
+### Examples and density
+
+Every statement in a body costs a read on each invocation.
 
-- Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer.
-- Keep a statement only when removing it would change what the agent does, naming a principle as a few-word handle rather than explaining it. Revisit when a run shows the model ignoring a principle named only as a handle.
+- Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer
+- Keep a statement only when removing it would change what the agent does, naming a principle as a few-word handle rather than explaining it
+- Revisit when a run shows the model ignoring a principle named only as a handle
 
 ### Progressive disclosure
 
 Keeping a body and its references under the ceiling, what moves to `references/` and what stays, and how a body names a reference are in `skill-disclosure.md`.
 
-### Reading and running commands
-
-- When referencing project files, include "from the project root" in the read instruction
-- When executing multiple independent operations (file reads, shell commands), run them in parallel to reduce latency
-
 ### Anti-patterns to avoid
 
-- Avoid flags that dispatch between alternate flows. The model misreads them and runs the vanilla path. Dry-run-style toggles are fine. For alternate flows, prefer a separate skill or manual invocation of two skills in sequence.
+Avoid flags that dispatch between alternate flows, since the model misreads them and runs the vanilla path. Dry-run-style toggles are fine, and an alternate flow takes a separate skill or two skills invoked in sequence.
+
 - When a skill should fire from multiple callers, rely on description matching with strong trigger phrases. Do not hardcode `Skill` calls in sibling skills that could trigger it naturally.
-- Before collapsing a manual multi-step flow into a skill, ask what the manual pauses do. Where a pause carries external timing, error-surfacing, or judgment weight, prefer explicit per-step confirmation.
+- Before collapsing a manual multi-step flow into a skill, ask what the manual pauses do
+- Where a pause carries external timing, error-surfacing, or judgment weight, prefer explicit per-step confirmation
+
+### Output paths
+
+A success line emits the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted, since a bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so the body states which path and leaves the form to that section.
+
+### Where output lands
+
+Before writing, decide whether the output is a deliverable, which lands among the project's tracked files, or a session record. A session record lands under `.canon/` in the named subfolder for its kind, never in a folder the body invents.
 
-### Output and tuning
+- Kinds: `tasks/`, `plans/`, `review/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, `teach/`, `ready/`, `feedback/`, `picks/`, `evidence/`, `transcripts/`, `walkthroughs/`
+- `tmp/` takes scratch nothing else claims
+- A `review/` writer names its file `<kind>-<slug>.md` and writes it flat
+- An `evidence/` folder takes the next two-digit ordinal as `<nn>-<slug>/`, numbered in the order the folders first appeared
 
-- Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. A bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so a skill body states which path is emitted and leaves the form to that section.
-- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, `teach/`, `ready/`, `feedback/`, `picks/`, `evidence/`, `transcripts/`, or `walkthroughs/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. A `review/` writer names its file `<kind>-<slug>.md` and writes it flat, and an `evidence/` folder takes the next two-digit ordinal as `<nn>-<slug>/`, numbered in the order the folders first appeared.
-- Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
-- When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
-- Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions, never turning a soft cap hard for aesthetic drift.
+### Templates, input, and tuning
+
+Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
+
+- When a skill gathers input or pre-seeds a template, attach a proposed default derived from project context to every question. Accept "use defaults" as a bulk-confirm.
+- Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill
+- Tighten only on correctness regressions, never turning a soft cap hard for aesthetic drift
 
 ## Scripts
 
-- Use `scripts/` for operations that must be deterministic or repetitive
-- Ask whether a CLI verb the project already has does the job before writing a script. A verb is already installed and tested, and a script beside it is a second copy that drifts
-- Write a script in TypeScript and run it as `bun ${CLAUDE_SKILL_DIR}/scripts/<name>.ts`. Keep bash for a few lines that start one command. The rule governs a new script, so bash kept by decision is no breach and is not ported unasked, such as `review-ui`'s `scripts/pw.sh` as glue and the shell scripts the web tooling stacks ship, whose port was deferred
-- Import no package. A plugin loads from a cache that carries no `node_modules`, so only `node:` built-ins and the CLIs the skill already requires resolve
-- Use XML tags in script output for reliable parsing: `<SECTION>content</SECTION>`
+Use `scripts/` for operations that must be deterministic or repetitive. First ask whether a CLI verb the project already has does the job, since a verb is installed and tested and a script beside it is a second copy that drifts.
 
-### Inline commands
+- Write a script in TypeScript and run it as `bun ${CLAUDE_SKILL_DIR}/scripts/<name>.ts`. Keep bash for a few lines that start one command.
+- Import no package. A plugin loads from a cache that carries no `node_modules`, so only `node:` built-ins and the CLIs the skill already requires resolve.
+- Use XML tags in script output for parsing: `<SECTION>content</SECTION>`
+- Guard a git or shell command a body runs inline with `2>/dev/null || echo "FALLBACK"`. A TypeScript script uses try and catch instead.
 
-- Always include `2>/dev/null || echo "FALLBACK"` guards on git and shell commands a skill body runs inline. A TypeScript script handles failure with try and catch instead
+The TypeScript rule governs a new script, so bash kept by decision is no breach and is not ported unasked. Examples are `review-ui`'s `scripts/pw.sh` as glue and the shell scripts the web tooling stacks ship, whose port was deferred.
 
 ## Invocation
 
@@ -180,10 +199,14 @@ Keeping a body and its references under the ceiling, what moves to `references/`
 
 ### Correct
 
+Each line names its reason after the `#`.
+
 - `description: Reviews code for bugs and clarity. Use when asked to "review this" or "check the PR".` # names the action, then the trigger phrases
 - `Read ${CLAUDE_SKILL_DIR}/references/post.md on reaching this step.` # a moved step keeps its heading and one load line
 
 ### Incorrect
 
+Each line names its fault after the `#`.
+
 - `description: Handles all code tasks in scripts/, src/, and lib/, and any file ending in .ts .js .py .sh.` # path-focused and keyword-stuffed
 - `A good review checks bugs, performance, security, style, naming, coverage, docs, and SOLID...` # dumps everything inline instead of citing a standard

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

@@ -41,4 +41,4 @@ The opposite failure is the one that ships silently. A session that takes a pref
 
 - Making the ordinary judgment call, which is a pick plus a one-sentence tradeoff and needs no surface
 - Writing the decision into a plan, task, or context entry, which each owning standard governs and this skill only routes to
-- Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so escalating is the operator's call rather than a description match.
+- Deciding when to fire. The description states `Do NOT auto-trigger`, so escalating is the operator's call rather than a description match.

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

@@ -1,7 +1,6 @@
 ---
 name: decision-escalate
-description: Collects every open decision whose answer turns on the operator's preference, since only they know what they need, puts them as one batch of questions each carrying options and a recommended default, then waits. Use when asked to "escalate this", "ask me the open questions", "batch the open decisions", "what do you need from me", or "stop and ask before you pick". Do NOT use for a judgment call the session can settle, which is a pick with the tradeoff stated in one sentence.
-disable-model-invocation: true
+description: Collects every open decision whose answer turns on the operator's preference, since only they know what they need, puts them as one batch of questions each carrying options and a recommended default, then waits. Use when asked to "escalate this", "ask me the open questions", "batch the open decisions", "what do you need from me", or "stop and ask before you pick". Do NOT use for a judgment call the session can settle, which is a pick with the tradeoff stated in one sentence. Do NOT auto-trigger.
 metadata:
   family: decide
 ---

package/claude/skills/deploy-app/references/vercel.md

@@ -10,7 +10,8 @@ Run these steps once the body's Pick step resolves to Vercel. Read `vercel <comm
 ## Guard
 
 - If `vercel whoami` fails, stop: `❌ vercel is not authenticated. Run vercel login, then re-invoke.`
-- If `command -v jq` fails, stop: `❌ jq is not installed. Install it, then re-invoke.` Step 3 pipes its output into a secret, and a missing reader would set that secret empty while `gh secret list` still lists its name.
+- If `command -v jq` fails, stop: `❌ jq is not installed. Install it, then re-invoke.`
+- Step 3 pipes jq's output into a secret, and without jq the secret is set empty while `gh secret list` still lists its name
 
 ## Step 1: create and link the project
 

package/claude/skills/deprecation-migration/references/adopted.md

@@ -5,49 +5,68 @@ description: Which external sources on deprecation and migration this skill adop
 
 # Adopted and declined
 
-External sources were read and filtered rather than imported. This file is the record. A later session extending the skill adds to it rather than re-arguing an item already settled here.
+External sources were read and filtered rather than imported. This file is the record, and a later session extending the skill adds to it rather than re-arguing an item settled here.
 
-## Adopted
+## Adopted from the default shelf
 
-### From the default shelf
+### Deprecation
 
-**Deprecation.** [Software Engineering at Google, chapter 15](https://abseil.io/resources/swe-book/html/ch15.html). Adopted from it:
+[Software Engineering at Google, chapter 15](https://abseil.io/resources/swe-book/html/ch15.html) supplies four positions the body states.
 
-- Advisory and compulsory deprecation as the two types, with compulsory carrying a removal date. The body allows compulsory only once a replacement has shipped, which the chapter implies and the four questions make explicit.
-- Warnings that are actionable and relevant: a warning names what the caller does, and surfaces where the caller uses the old surface.
-- Deprecation as a process with an owner, since the chapter observes that unowned deprecation work makes no progress. Adopted as the fourth decision question and the rule against an advisory deprecation left open with no owner.
-- Finding consumers before removal, which the chapter does with static analysis across one repository. Generalized into the zero-consumers check across caller kinds, since a target project rarely has a whole-company code index and its callers often live outside the repository.
+- **Two types.** Advisory and compulsory, the second carrying a removal date. The body allows compulsory only once a replacement ships, which the chapter implies and the four questions make explicit.
+- **Actionable, relevant warnings.** A warning names what the caller does, and surfaces where the caller uses the old surface.
+- **An owner.** The chapter observes that unowned deprecation work makes no progress. Adopted as the fourth decision question and the rule against an ownerless advisory deprecation left open.
+- **Finding consumers before removal.** The chapter's static analysis over one repository becomes the zero-consumers check across caller kinds, since a target's callers often live outside it.
 
-**The Churn Rule.** [Software Engineering at Google, chapter 1](https://abseil.io/resources/swe-book/html/ch01.html), under "Policies That Don't Scale": infrastructure teams move their internal users to new versions themselves, or update in place in a backward-compatible way. Adopted as the group on migrating callers yourself, with the backward-compatible path kept for callers the owner cannot edit.
+### Migrating callers yourself
 
-### The decision and the bridges
+[Software Engineering at Google, chapter 1](https://abseil.io/resources/swe-book/html/ch01.html), under "Policies That Don't Scale", has infrastructure teams move their internal users to new versions themselves, or update in place in a backward-compatible way.
 
-**Deprecation and migration.** Addy Osmani's `agent-skills`, pinned at addyosmani/agent-skills@2686b620, [`skills/deprecation-and-migration/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/deprecation-and-migration/SKILL.md). Adopted from it:
+Adopted as the group on migrating callers yourself, with the backward-compatible path kept for callers the owner cannot edit.
 
-- The five-question deprecation decision, cut to four. Its unique-value and maintenance-cost questions merge into one question about what keeping the surface costs. Its per-consumer migration-cost question drops, since the Churn Rule puts that cost on the owner rather than weighing it per caller. The owner question from the book takes the freed place.
-- The rule never to deprecate without a replacement, as the third decision question.
-- The strangler and adapter patterns, stated as when each fits rather than as worked code tied to one stack.
+## Adopted for the decision and the bridges
 
-#### Migration, zombie code, and red flags
+Addy Osmani's `agent-skills`, pinned at addyosmani/agent-skills@2686b620, [`skills/deprecation-and-migration/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/deprecation-and-migration/SKILL.md), supplies the decision and the bridge patterns.
 
-- Expand, migrate, contract, lifted out of its schema section and stated for any surface as three separate changes.
-- Zombie code, narrowed to code that is unowned, uncalled, and still built, and settled by the same zero-consumers check rather than a list of staleness signals.
-- The rationalizations and red flags that carry across stacks, reworded for any surface rather than a service or a column. Two excuse rows come from here:
-  - The row on a search that found nothing, from its red flag against removing code without verifying zero active consumers.
-  - The row on adding the new one and dropping the old one now, generalized from its rationalization about adding a column and dropping the old one in the same migration.
+### The decision
+
+Its five-question deprecation decision is cut to four. The unique-value and maintenance-cost questions merge into one about what keeping the surface costs, and the per-consumer migration-cost question drops, since the Churn Rule puts that cost on the owner.
+
+- The owner question from the book takes the freed place
+- The rule never to deprecate without a replacement is the third decision question
+- The strangler and adapter patterns are stated as when each fits rather than as worked code tied to one stack
+
+### Migration, zombie code, and red flags
+
+The migration shape and the excuse rows carry across stacks once reworded for any surface rather than a service or a column.
+
+- Expand, migrate, contract, lifted out of its schema section and stated for any surface as three separate changes
+- Zombie code, narrowed to code that is unowned, uncalled, and still built, and settled by the zero-consumers check rather than a list of staleness signals
+- The excuse row on a search that found nothing, from its red flag against removing code without verifying zero active consumers
+- The excuse row on adding the new one and dropping the old one now, generalized from its rationalization about a column added and dropped in one migration
 
 ## Declined
 
-**Its database schema section.** The column rename worked example, the tested down path, batched backfills, and concurrent index builds. Declined because a project's persistence rule owns schema changes, and restating them here puts two owners on one rule. Only the expand, migrate, contract shape was lifted, generalized beyond schemas.
+Each item below was read and left out, with the reason it changes nothing a session does here.
+
+### The schema section and its mechanisms
+
+**Its database schema section.** The column rename worked example, the tested down path, batched backfills, and concurrent index builds. A project's persistence rule owns schema changes, so only the expand, migrate, contract shape was lifted, generalized beyond schemas.
 
 **Feature flag migration.** Declined because it is one way to run a strangler, and naming a flag mechanism ties the body to a runtime a target may not have.
 
-**The traffic percentages in its strangler phases.** Declined because they describe a service behind a router, and most surfaces a session retires, such as a function, a flag, or a file, have callers rather than traffic.
+### Numbers that fit one project
+
+**The traffic percentages in its strangler phases.** They describe a service behind a router, and most surfaces a session retires, such as a function, a flag, or a file, have callers rather than traffic.
+
+**The thresholds in its zombie signs and rebuttals.** No commits in six months, and comparing costs over two or three years. Declined for the reason the body states no deprecation window, since a number fits one project's cadence and not another's.
+
+### Defaults and framing
 
-**"Default to advisory" as a standing default with no exit.** Kept advisory as the starting state, and declined leaving it open, since an advisory deprecation with no date and no owner is the stalled case the body exists to prevent.
+**"Default to advisory" as a standing default with no exit.** Advisory is kept as the starting state and leaving it open is declined, since an advisory deprecation with no date and no owner is the stalled case the body exists to prevent.
 
-**The thresholds in its zombie signs and rebuttals.** No commits in six months, and comparing costs over two or three years. Declined for the same reason the body states no deprecation window: a number fits one project's cadence and not another's.
+**"Code is a liability" and design-time deprecation planning as sections.** Framing a session already accepts by loading the skill. The cost question carries the first, and designing a new surface for removal belongs to the skill shaping that surface.
 
-**"Code is a liability" and design-time deprecation planning as sections.** Declined as framing a session already accepts by loading the skill. The cost question carries the first, and designing a new surface for removal belongs to the skill shaping that surface.
+### Ceremony
 
 **The celebration step and the deprecation notice template.** Declined because neither changes what a session does, and the template's example names a package runner and a migration script tied to one stack.

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

@@ -15,14 +15,22 @@ External catalogs were read and filtered rather than imported. This file is the
 
 ## Declined from the catalogs
 
+Each item below is real advice placed in the wrong surface, or a rule that decides nothing.
+
+### Values and dials
+
 **Banned fonts by name.** A font ban is a value ban, and a value belongs to the project's own design document rather than to a skill that loads everywhere. A project that wants a typeface ruled out rules it out there.
 
 **Numeric intensity dials.** Every external source carries a 1-to-10 scale for variance, motion and density. A session picks a middle value and reports compliance. That satisfies the rule, decides nothing, and leaves no trace a later reader could check it by. The declared read carries the same information in a sentence somebody can argue with.
 
+### Rules owned elsewhere
+
 **The em dash ban as a design rule.** One source bans the character on a page as a visual tell. The markdown standard already bans it for prose reasons and `canon markdown audit` gates that from package data, so restating it here would put a second copy of an enforced rule behind an unenforced pointer.
 
 **The official-package map.** A table routing a brief to Fluent, Material, Carbon, Polaris, Primer or a government design system. It is real advice and it is a stack decision a project takes once, so it belongs in that project's own records rather than in a skill that loads on every design round.
 
+### Scope
+
 **Scoping out application UI.** The largest source covers landing pages, portfolios and redesigns, and excludes dashboards, data tables and multi-step product UI. Those exclusions are most of what software projects actually build, so the kinds reference carries application UI as a first-class kind.
 
 ## Declined from the systems reference
@@ -33,7 +41,7 @@ Each failed the test in `REQUIREMENT.md`. Recorded so they are not argued again.
 - **Specific ratios for a type scale**, such as a named musical interval. Falsifiable and arbitrary, and a project picking a different ratio is not wrong.
 - **Named palettes or banned hues.** A value ban, which belongs to the project's design document. This is where every external catalog of this kind ends up, and it is why theirs cannot be imported.
 - **A minimum contrast figure.** A threshold with a number, which the accessibility rules own.
-- **Imagery as a system.** There is no scale to establish. What a model gets wrong about images is using fake ones, which `tells.md` already covers, so the layer stays thin on purpose rather than by oversight.
+- **Imagery as a system.** There is no scale to establish. What a model gets wrong about images is using fake ones, which `tells.md` covers, so the layer stays thin on purpose.
 
 ## Carried as a caution
 

package/claude/skills/design-taste/references/craft.md

@@ -11,7 +11,7 @@ Read this when a layout satisfies the ordering, the locks and the tells, and sti
 
 The eye and the arithmetic disagree, and the eye is the one being served.
 
-- **Centering by the numbers is not centering.** A triangle inside a circle, an icon beside a label, a glyph inside a round button all sit visually left or low when centered by their bounding box. Nudge until it looks right, usually a pixel or two.
+- **Centering by the numbers is not centering.** A triangle in a circle, an icon beside a label, or a glyph in a round button sits left or low when centered by its box. Nudge it, usually a pixel or two.
 - **Equal vertical padding reads bottom-heavy.** A block with matching top and bottom padding looks like it is sinking. Give the bottom slightly more.
 - **Optical size beats declared size.** A circle and a square at the same declared size do not read as the same size. The circle needs to be larger.
 - **Type alignment follows the letterform, not the box.** A quotation mark, a bullet or an opening parenthesis at the start of a line should hang outside the text edge so the text itself lines up.
@@ -56,6 +56,8 @@ Reaching for size is the first instinct and the weakest tool.
 
 ### Content and copy
 
+Copy reads unfinished in the same way.
+
 - Every item dated identically, which no real collection ever is.
 - An exclamation mark in a success message. Confidence is quieter than that.
 - An error opening on an apology rather than on what to do next.

package/claude/skills/design-taste/references/kinds.md

@@ -12,8 +12,8 @@ Read this once the declared read names a kind. The body's rules hold on every ki
 Landing pages, campaign pages, portfolios. The reader has never used the thing and owes it no attention.
 
 - **Optimizes for** comprehension in the first screen, then one clear next action.
-- **Composition carries the weight.** A marketing page is judged on section order and variation before anything else, which is why a palette round against a flat composition changes nothing a reader notices.
-- **Vary the section shape.** Alternate alignment, container width and the ratio between sections. A page where every section is a centered heading over centered body reads as a template regardless of its values.
+- **Composition carries the weight.** A marketing page is judged on section order and variation first, so a palette round against a flat composition changes nothing a reader notices.
+- **Vary the section shape.** Alternate alignment, container width and the ratio between sections. Every section a centered heading over centered body reads as a template whatever its values.
 - **Low density.** Whitespace is the argument that the thing is considered. This is the one kind where less information on screen is usually better.
 - **Every claim names a real thing.** A page asserting what a tool does, illustrated by something the tool did not produce, breaks its own thesis in the place it is making it.
 - **Motion is permitted and rationed.** Entrance motion for what genuinely leads the eye, nothing looping forever.
@@ -25,8 +25,9 @@ Dashboards, tools, admin surfaces, agentic and assistant interfaces. The reader
 
 - **Optimizes for** throughput and state legibility. How fast can the reader see what is happening and act on it.
 - **High density is correct.** Cramming is a failure and spaciousness is also a failure, since a surface that shows six rows where thirty fit costs the reader a scroll per glance.
-- **The states carry the design weight.** Loading, empty, error, partial and stale are not edge cases on this kind, they are most of what the reader sees, so they are composed rather than handled. Whether each exists at all is the `ui` rules' question and not this one.
-- **An agentic surface adds three states of its own:** work in progress with something to read while it runs, work that needs the person before it continues, and work that finished with a result to inspect. Each needs a visible resting place and none should be a spinner.
+- **The states carry the design weight.** Loading, empty, error, partial and stale are most of what the reader sees on this kind, so they are composed rather than handled.
+- **Whether each state exists** is the `ui` rules' question, not this file's.
+- **An agentic surface adds three states.** Work running with something to read, work that needs the person, and work finished with a result to inspect. Each rests visibly, never as a spinner.
 - **Chrome is persistent and quiet.** Navigation, status and context stay put and stay recessive, since they are read constantly and looked at rarely.
 - **Motion is feedback, not entrance.** A thing moving should be reporting that something changed.
 - **Where a rule from another kind is wrong here:** generous whitespace, entrance animation on every panel, and hero-scale typography all read as a marketing page wearing a product's clothes.
@@ -41,12 +42,12 @@ Documentation, articles, reference pages, learning material. The reader arrived
 - **Navigation is a map.** A reader who cannot see where they are in the whole cannot judge whether to keep going, which is what a scrollspy or a persistent outline buys.
 - **Code, tables and figures are first-class.** They are what the reader scans for, so they are styled as content rather than as interruptions.
 - **Motion is almost always wrong.** Movement during reading competes with reading.
-- **Where a rule from another kind is wrong here:** density tuned for an application surface makes long prose unreadable, and marketing whitespace between every paragraph breaks a section into unrelated fragments.
+- **Where a rule from another kind is wrong here:** application density makes long prose unreadable, and marketing whitespace between every paragraph breaks a section into unrelated fragments.
 
 ## Kinds this file does not cover
 
-- **Transactional flows** such as checkout, sign-up and settings are read as application UI. Their distinctive rules are state coverage and error recovery, which the `ui` governance rules already carry.
-- **Presentation surfaces** such as slide decks are drafted by `draft-slides`, which carries the deck's own design rules. Take the layer ordering and the floor from the body and the rest from that skill.
+- **Transactional flows** such as checkout, sign-up and settings are read as application UI. Their distinctive rules, state coverage and error recovery, sit in the `ui` governance rules.
+- **Presentation surfaces** such as slide decks are drafted by `draft-slides`, which carries the deck's design rules. Take the layer ordering and the floor from the body and the rest from it.
 - **Terminal and text-mode surfaces** have no layout engine and their own color rules, stated where the writing surface is decided rather than here.
 
 A read naming any of the three above takes the body's rules and says it has no per-kind guidance, naming the surface that governs it. A read naming a kind this file does not list at all says so rather than borrowing the nearest section.

package/claude/skills/design-taste/references/preflight.md

@@ -28,6 +28,8 @@ Skip nothing on the ground that it is obviously fine. A rule is on this list bec
 
 ### Section rhythm
 
+Each box here is a count from `tells.md`.
+
 - [ ] No layout family used twice. Eight sections carry at least four families
 - [ ] No three consecutive sections sharing the image-and-text split
 - [ ] Small uppercase labels above headings number no more than one per three sections, per `interface-casing`
@@ -35,6 +37,8 @@ Skip nothing on the ground that it is obviously fine. A rule is on this list bec
 
 ### Content and first screen
 
+The grid and the first screen are shaped to the content counted.
+
 - [ ] Grid cells equal content items, with no blank tile filling a gap
 - [ ] Lists over five items use something other than a longer list
 - [ ] The first screen carries the point and the primary action without scrolling
@@ -46,12 +50,16 @@ Skip this group where the surface draws on a system already settled.
 
 ### Space and type
 
+The scales come from `systems.md`.
+
 - [ ] Every gap comes from one scale, and the distinct spacing values number under about eight
 - [ ] Space between groups exceeds space within them
 - [ ] The type scale carries five to seven steps, each visibly different from its neighbors
 
 ### Color
 
+Each box is a relationship, never a value.
+
 - [ ] The accent is rare enough to read as an accent
 - [ ] Neutrals sit in one family at one temperature
 - [ ] Adjacent surfaces separate by a little and content separates from ground by a lot
@@ -64,6 +72,8 @@ Skip this group where the surface draws on a system already settled.
 
 ### Type detail
 
+The detail boxes come from `craft.md`.
+
 - [ ] No orphaned word closing a heading
 - [ ] Body text measure is capped
 - [ ] Changing numbers set in tabular figures
@@ -77,6 +87,8 @@ Skip this group where the surface draws on a system already settled.
 
 ### Wording
 
+Every word on the surface states what is true of it.
+
 - [ ] No filler verbs
 - [ ] Sentence case throughout, with exceptions per `interface-casing`
 - [ ] Every claim about what the product does is a thing it does

package/claude/skills/design-taste/references/systems.md

@@ -14,8 +14,9 @@ Nothing below states a value. A value belongs to the project's own design docume
 An unguided model reaches for whatever number looks right at each point, which produces a surface with thirty spacing values and no rhythm.
 
 - **Every gap comes from one scale.** Count the distinct spacing values on a finished surface. More than about eight means there is no scale, only arithmetic.
-- **The steps grow, they do not add.** A scale stepping 4, 8, 12, 16, 24, 32, 48, 64 gives usable distinctions at both ends. One stepping 10, 20, 30, 40 gives four values that all read the same at large sizes and none that work at small.
-- **Space between groups exceeds space within them.** This is the one spacing rule carrying real meaning, since proximity is what tells a reader which things belong together. A surface with one gap everywhere has told the reader nothing, and it is the most common spacing failure in generated output.
+- **The steps grow, they do not add.** A scale stepping 4, 8, 12, 16, 24, 32, 48, 64 gives usable distinctions at both ends. One stepping 10, 20, 30, 40 reads alike at large sizes and fails at small.
+- **Space between groups exceeds space within them.** The one spacing rule carrying meaning, since proximity tells a reader which things belong together.
+- **One gap everywhere** tells the reader nothing, and it is the most common spacing failure in generated output.
 - **Section rhythm is two or three tiers, not a value per section.** Pick the tiers, then assign each section to one.
 - **Space responds to viewport, type mostly does not.** A layout that scales every value together arrives at a phone reading like a shrunken desktop.
 
@@ -31,12 +32,12 @@ An unguided model reaches for whatever number looks right at each point, which p
 
 The layer a model is worst at, and the layer where rules are hardest to make falsifiable. Everything below is a relationship, since a rule naming a value is a value ban and values belong to the project.
 
-- **An accent is defined by rarity, not by hue.** A color used on a third of the surface is a ground, whatever it was chosen as. If the accent appears more than a handful of times per screen, there is no accent.
+- **An accent is defined by rarity, not by hue.** A color on a third of the surface is a ground, whatever it was chosen as. An accent seen more than a handful of times per screen is none.
 - **Neutrals are one family at one temperature.** Warm grays beside cool grays read as a mistake rather than as a decision, and it is a mistake a model makes by pulling neutrals from different sources.
 - **Adjacent surfaces separate by a little, content separates from ground by a lot.** Generated output routinely inverts this: cards that shout against the page, and text that does not.
-- **A semantic color is not the accent.** Error, success and warning carry meaning. Borrowing the accent for one of them makes the accent mean something, and it stops being available for anything else.
-- **Dark mode is re-derived, not inverted.** The relationships above are what carry across, and the values are settled again. A palette flipped by algorithm gets the relationships wrong in both directions.
-- **Saturation has a budget across the surface, not per color.** Several colors each individually reasonable produce a surface that reads loud, which is why the rule is about the total rather than about any one value.
+- **A semantic color is not the accent.** Error, success and warning carry meaning. Borrowing the accent for one makes the accent mean something, and it stops being available for anything else.
+- **Dark mode is re-derived, not inverted.** The relationships above carry across and the values are settled again. A palette flipped by algorithm gets the relationships wrong in both directions.
+- **Saturation has a budget across the surface, not per color.** Several colors each reasonable alone produce a surface that reads loud, so the rule is about the total rather than any one value.
 
 ## Considered and declined