@erclx/canon 5.35.0 → 5.36.0

package/README.md

@@ -61,17 +61,17 @@ bun install --global @erclx/canon
 
 Each domain has a canonical source in this repo and a thin install or sync CLI on your side. The domains split on one line: some are copied into your project and become yours to edit, and some are never copied at all.
 
-| Domain         | What it is                                                                                                               | How it reaches you                                              |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
-| Plugin skills  | Skills that plan a feature, review a diff, sync the planning docs, and run the ship chain                                | Loaded live from the plugin, never copied                       |
-| Governance     | Coding and authoring rules that load into a Claude session when a matching path is edited                                | Installed per project by `canon gov install`, refreshed by sync |
-| Tooling stacks | Golden configs, seeds, and a reference per framework                                                                     | Laid down by `canon init`, reconciled by `canon tooling sync`   |
-| Design system  | Ships a `DESIGN.md` token format, a skill that drafts one from an existing project or from scratch, and a render command | `canon design render`                                           |
-| Slides         | A folder of HTML slides per deck, drawn in the project's tokens and rebuilt as editable shapes                           | `canon slides render` writes PowerPoint                         |
-| Teach          | Lessons, sources, and a glossary in one workspace, rendered to a small site                                              | `canon teach`                                                   |
-| Canvas         | Pages of HTML frames on a local pan and zoom surface, each frame drawn with the project's tokens                         | `canon canvas serve`                                            |
-| Transcripts    | A YouTube transcript with metadata frontmatter                                                                           | `canon transcripts <url>` writes it into any repo               |
-| Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow                               | `canon sandbox`                                                 |
+| Domain         | What it is                                                                                                                                                                   | How it reaches you                                              |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Plugin skills  | Skills that plan a feature, review a diff, sync the planning docs, and run the ship chain                                                                                    | Loaded live from the plugin, never copied                       |
+| Governance     | Coding and authoring rules that load into a Claude session when a matching path is edited                                                                                    | Installed per project by `canon gov install`, refreshed by sync |
+| Tooling stacks | Golden configs, seeds, and a reference per framework                                                                                                                         | Laid down by `canon init`, reconciled by `canon tooling sync`   |
+| Design system  | Ships a `DESIGN.md` intent format that points at the project's stylesheet for values, a skill that drafts one from an existing project or from scratch, and a render command | `canon design render`                                           |
+| Slides         | A folder of HTML slides per deck, drawn in the project's tokens and rebuilt as editable shapes                                                                               | `canon slides render` writes PowerPoint                         |
+| Teach          | Lessons, sources, and a glossary in one workspace, rendered to a small site                                                                                                  | `canon teach`                                                   |
+| Canvas         | Pages of HTML frames on a local pan and zoom surface, each frame drawn with the project's tokens                                                                             | `canon canvas serve`                                            |
+| Transcripts    | A YouTube transcript with metadata frontmatter                                                                                                                               | `canon transcripts <url>` writes it into any repo               |
+| Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow                                                                                   | `canon sandbox`                                                 |
 
 Those domains reach you in three shapes. A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A plugin skill and the references it carries are never copied, so there is no copy in your repo to drift from this one.
 

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.35.0",
+  "version": "5.36.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -13,7 +13,7 @@ The damage lands on the files a project owns. A golden config carrying local edi
 
 The inverse failure is quieter. A session that assumes a sync will pick up a change edits a seed and waits for an update that never comes, because the seed is copy-once and no sync command writes it again. Both failures are one missing fact available before the command runs.
 
-A third gap is the route itself. `canon --help` lists every top-level verb with a partial hint, and a session with a job in hand pays a `--help` read per candidate to find the one that does it, or picks by name and lands on the wrong one. The job-to-verb mapping is the fact the session needs and no verb answers.
+A third gap is the route itself. `canon --help` lists every top-level verb by a one-line description, and a session with a job in hand pays a `--help` read per candidate to find the one that does it, or picks by name and lands on the wrong one. The job-to-verb mapping is the fact the session needs and no verb answers.
 
 Being reachable is a separate problem from being right. This is a pure reference whose moment happens inside another skill's run, so nothing brings it up unless a body names it. A route lives in a body or it does not exist, and a mention in a sibling's requirement file is not one.
 
@@ -23,7 +23,7 @@ Being reachable is a separate problem from being right. This is a pure reference
 - Route an author-and-render verb to the skill that owns it rather than describing it
 - Warn about a verb that can lose the project's edits before it runs, naming what it replaces
 - Point each destructive verb at `canon docs install-and-sync`, which owns the overwrite detail
-- Point to `canon <verb> --help` and `canon docs agents` for subcommands, flags, and the invocation contract
+- Point to `canon <verb> --help --all` and `canon docs agents` for subcommands, flags, and the invocation contract, and have the session read that help before running a verb no skill body spells out, a verb a skill pins in full being exempt
 - Defer to `canon docs install-and-sync` when it and this summary disagree, since the summary is a copy and the doc is the source
 
 ## Must not

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

@@ -12,7 +12,8 @@ Consult to pick the `canon` verb for a job, and before running a verb that write
 ## Find the verb
 
 - Each row below names a verb by its job. Subcommands and flags are not listed here, so read them where they are kept.
-- Run `canon <verb> --help` for a verb's subcommands and flags.
+- Run `canon <verb> --help --all` for a verb's subcommands and every flag in one read, where `canon <verb> --help` alone stops at the subcommand list.
+- Read `canon <verb> --help --all` before running a verb no skill body spells out. A verb a skill gives in full runs as that skill wrote it.
 - Run `canon docs agents` for the invocation contract behind every verb, and `canon docs list` for every other reference doc, then `canon docs <topic>` by name.
 
 ## Project setup

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

@@ -25,7 +25,7 @@ When the operator picks a frame, the session leaves the decision on the canvas a
 - Read the operator's selection when they point at something, and treat a stale element pick as unknown
 - Read a frame's inline styles before restyling it, and say which operator edits were kept and which dropped
 - Capture once per finished frame or page rather than after every edit
-- Carry a picked value into the project's design document, and leave a picked layout on the canvas for the plan that builds it
+- Carry a picked value into the project's stylesheet and its intent into the design document, and leave a picked layout on the canvas for the plan that builds it
 
 ## Must not
 

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

@@ -105,7 +105,7 @@ The operator restyles elements from the inspector, and each edit lands as inline
 
 When the operator picks a frame, the decision leaves the canvas.
 
-- Carry visual values, being color, type, spacing, and radius, into the project's design document, editing its sections in place under the `design.md` standard. Leave structure and layout on the canvas, and name the frame in the plan that builds it.
+- Carry visual values, being color, type, spacing, and radius, into the stylesheet the design document's lead names, and the intent behind them into the document's sections under the `design.md` standard. A project with no stylesheet yet takes the values under `.claude/design/project/` after `canon design install`, and the lead names that path. Leave structure and layout on the canvas, and name the frame in the plan that builds it.
 - Name the frame the decision came from in the reply, and leave the frame on the canvas until the operator clears it.
 - Never cite a frame path from a tracked file. The folder is gitignored, so the citation resolves on this machine alone.
 
@@ -116,7 +116,7 @@ When the operator picks a frame, the decision leaves the canvas.
 Page:     <page>, <n> frames
 Selected: <page>/<frame>, element <index>, or none, or stale
 Capture:  <path of each capture written>
-Carried:  <the design document the pick went to, the plan that cites the frame, or not yet>
+Carried:  <the stylesheet and design document the pick went to, the plan that cites the frame, or not yet>
 ```
 
 Write the canvas line's URL as a markdown link. Omit the capture line when nothing was captured and the carried line when no direction was picked. Emit every path from the project root.

package/claude/skills/canvas-board/references/design.md

@@ -10,104 +10,121 @@ Applies to `canon/DESIGN.md`. Captures visual intent and the decisions behind ho
 ## Contents
 
 - [Scope](#scope)
+- [Two shapes](#two-shapes)
 - [What goes in](#what-goes-in)
 - [What does not go in](#what-does-not-go-in)
 - [Format](#format)
 - [Prose budget](#prose-budget)
-- [The uncertainty tag](#the-uncertainty-tag)
 - [Sections](#sections)
+- [The uncertainty tag](#the-uncertainty-tag)
 - [Template](#template)
 
 ## Scope
 
-Governs the visual-intent document at `canon/DESIGN.md`: tokens described as intent, layout constraints, and the omissions that keep visual scope closed.
+Governs the visual-intent document at `canon/DESIGN.md`, being the rules and omissions that keep visual scope closed, the intent behind each role, and the pointer to where the values live.
 
 Does not govern:
 
 - Per-domain implementation narrative: `context.md`
+- The token values themselves, which live in the project's stylesheet
+
+## Two shapes
+
+- **An intent record** is the shape a project writes by hand. It carries rules, omissions, and each role's intent, and its lead names the stylesheet the values live in. It carries no value, since a hand-typed copy of the stylesheet drifts from it.
+- **A values record** is generated from a token source and carries the value tables beside the rules. It is never edited by hand, and its lead names the module it is rendered from. The toolkit's own record is one.
+
+Everything below applies to both shapes unless it names one.
 
 ## What goes in
 
-- A token's exact value, anchored to the surface it was read from and tagged per `## The uncertainty tag` when unconfirmed. Fall back to intent language ("mid gray, muted text") only where no source exists yet to anchor from.
-- Layout constraints and sizing rules not obvious from the tokens and the code
+- In the lead, the stylesheet a reader takes values from, such as `src/styles/tokens.css` or a Tailwind `@theme` block
+- What each color role and each shape role is for, with the custom property that carries it
+- Layout constraints and sizing rules not obvious from the stylesheet and the code
 - Visual rules a developer could get wrong without guidance
 - Non-obvious omissions ("no motion", "no custom icons") that prevent scope creep
 
 ## What does not go in
 
+- A token's value in an intent record, whether a hex, a font stack, a size, a step, or a radius. The stylesheet the lead names carries it.
 - CSS classes and prop names. Those live in code.
 - Anything that needs updating every time the code is refactored
-- The history of how a value or a mark was chosen: the candidates, the rounds, the date of a pick. State the rule and the current value, and cut the trail. Git keeps it.
+- The history of how a value or a mark was chosen, being the candidates, the rounds, and the date of a pick. State the rule and cut the trail, since version control keeps it.
 
 ## Format
 
-- Use tables for token systems, one row per token. Write every other rule as a short bullet, one decision per line, within `## Prose budget`.
-- Plain English over technical notation. If a section could be removed and the developer would still build correctly from the tokens and code alone, remove it.
-- Keep table headers and role names intact so the render tooling can parse the token tables.
+- Write every rule as a short bullet, one decision per line, within `## Prose budget`.
+- Plain English over technical notation. If a section could be removed and the developer would still build correctly from the stylesheet and code alone, remove it.
+- Keep table headers and role names intact so the parser can read the tables.
 
 ## Prose budget
 
-The record is a lookup, so its prose stays short enough to scan beside the tables. Why a value was chosen belongs in the project's context entry for design, never here.
+The record is a lookup, so its prose stays short enough to scan. Why a rule was chosen belongs in the project's context entry for design, never here.
 
-- Personality: one paragraph of at most 60 words
+- Overview: one paragraph of at most 60 words
 - Any other section: at most 3 rules beside its table, each at most 25 words. A bullet is one rule, and so is a paragraph.
 - The lead before the first section: at most 40 words
 
 Headings and table rows are never counted, and a section holding a table and no rules is within budget. A bullet wrapping over several lines counts as one rule, and a nested bullet counts as its own.
 
-## The uncertainty tag
+## Sections
 
-A cell no source anchors ends in ` ? verify`, written inside the cell rather than as a trailing column, since a trailing marker breaks the table parse. A cell wrapping itself in a code span carries the tag inside the span, as in `` `#ffffff ? verify` ``. Both spellings parse.
+Use `## Overview`, `## Colors`, `## Typography`, `## Spacing`, `## Shapes`, `## Motion`, and `## Iconography`, in that order, which follows Google's DESIGN.md for the sections the two share. An optional `## Layout` sits between Spacing and Shapes. The parser still reads a record written under the earlier names, `## Personality`, `## Color`, and `## Borders`, as the sections they became.
 
-The renderer splits the tag off the value, so a swatch and a font sample are built from the value alone and the marker shows beside it. The preview also reports how many cells are anchored against how many are tagged, which is the reading a reviewer takes the record's overall confidence from.
+In an intent record, `## Colors` carries a `Role | Property | Intent` table and `## Shapes` a `Role | Property | When used` table. Each row names the custom property the stylesheet declares for that role, such as `--color-accent`. Typography and Spacing carry rules alone.
 
-Which columns that ratio reads is fixed by the table rather than by the record. The first column of each table names its row, and `Multiplier` and `When used` restate what the row already carries, so none of them is something a source could anchor and none is counted. That leaves `Intent` and `Value` in Color, `Family`, `Weight`, `Size`, and `Line height` in Typography, `Value` in Spacing, and `Radius` and `Width` in Borders. A cell tagged outside that set counts anyway, so a marker the preview draws is never missing from the ratio beside it.
+Add either optional section when the project has content for it:
 
-A prose section takes its uncertainty inline instead, in a sentence saying what is proposed and what has yet to confirm it. A tag appended to a paragraph renders verbatim.
+- `## Layout`: page width, breakpoints, and grid rules, as current constraints. The surface-capture rule reads the breakpoints from here, so a project with none declared here is captured at the 320 reflow floor alone.
+- `## Mark`: the logo's construction rules and the files that carry it
 
-## Sections
+## The uncertainty tag
 
-Use `## Personality`, `## Color`, `## Typography`, `## Spacing`, `## Borders`, `## Motion`, and `## Iconography`. The token tables carry fixed headers the renderer reads.
+Applies to a values record alone. An intent record carries no value to tag, and a guessed value is marked where it is written, in the stylesheet.
 
-Add either optional section when the project has content for it:
+A cell no source anchors ends in ` ? verify`, written inside the cell rather than as a trailing column, since a trailing marker breaks the table parse. A cell wrapping itself in a code span carries the tag inside the span, as in `` `#ffffff ? verify` ``. Both spellings parse.
 
-- `## Layout`: page width, breakpoints, and grid rules, as current constraints. The surface-capture rule reads the breakpoints from here, so a project with none declared here is captured at the 320 reflow floor alone.
-- `## Mark`: the logo's construction rules and the files that carry it
+The renderer splits the tag off the value, so a swatch and a font sample are built from the value alone and the marker shows beside it. The preview also reports how many cells are anchored against how many are tagged, which is the reading a reviewer takes the record's overall confidence from.
+
+Which columns that ratio reads is fixed by the table rather than by the record. The first column of each table names its row, and `Multiplier` and `When used` restate what the row already carries, so none of them is something a source could anchor and none is counted. That leaves `Intent` and `Value` in Colors, `Family`, `Weight`, `Size`, and `Line height` in Typography, `Value` in Spacing, and `Radius` and `Width` in Shapes. A cell tagged outside that set counts anyway, so a marker the preview draws is never missing from the ratio beside it.
+
+A prose section takes its uncertainty inline instead, in a sentence saying what is proposed and what has yet to confirm it. A tag appended to a paragraph renders verbatim.
 
 ## Template
 
-The column headers are the strings the renderer parses, read by exact key, so they stay verbatim. Row names are not. Each is slugged into the variable name it emits, which leaves a project free to rename a row, add one, or drop one it has no use for.
+The template is the intent record. The column headers are read by exact key, so they stay verbatim. Row names are not, which leaves a project free to rename a role, add one, or drop one it has no use for.
 
 ```markdown
 # Design
 
-## Personality
+Values live in `<path to the stylesheet>`. This record holds the intent behind them.
+
+## Overview
 
 <one paragraph on voice, tone, and the feeling a user should have>
 
-## Color
+## Colors
+
+- <a rule a developer could get wrong>
 
-| Role   | Intent           | Value   |
-| ------ | ---------------- | ------- |
-| <role> | <what it is for> | <value> |
+| Role   | Property         | Intent           |
+| ------ | ---------------- | ---------------- |
+| <role> | `--color-<role>` | <what it is for> |
 
 ## Typography
 
-| Role   | Family   | Weight   | Size   | Line height |
-| ------ | -------- | -------- | ------ | ----------- |
-| <role> | <family> | <weight> | <size> | <height>    |
+- <how the roles divide between families, and any role that breaks the pattern>
 
 ## Spacing
 
-| Step   | Multiplier   | Value   |
-| ------ | ------------ | ------- |
-| <step> | <multiplier> | <value> |
+- <the base unit and how the scale steps>
+
+## Shapes
 
-## Borders
+- <a rule about radius or border a developer could get wrong>
 
-| Role   | Radius   | Width   | When used   |
-| ------ | -------- | ------- | ----------- |
-| <role> | <radius> | <width> | <when used> |
+| Role   | Property          | When used   |
+| ------ | ----------------- | ----------- |
+| <role> | `--radius-<role>` | <when used> |
 
 ## Motion
 

package/claude/skills/codebase-layout/REQUIREMENT.md

@@ -34,7 +34,7 @@ A placement rule in front of the session is also one it can argue past. Each fla
 - Carry a hard file-count threshold. A command folder holding sixty files of one role reads fine flat, and a number would fail it.
 - Restate the layer rule, the layer table, or the final filter `test-craft` owns
 - Mandate one layout across projects, such as a `features/` tree, over the project's own strategy
-- Restate the pointer in `000-code`, which loads in code stacks only. The rule points here and this body carries the depth.
+- Restate the pointer in `routing`, which loads in code stacks only. The rule points here and this body carries the depth.
 
 ## Guards
 

package/claude/skills/codebase-layout/SKILL.md

@@ -90,5 +90,5 @@ Check every new path the plan or the change names against each line, and fix the
 - Which layer a test belongs at: `test-craft`. This skill decides where the test file sits once its layer is chosen.
 - What a module exposes across its boundary, being its exports, flags, output, and errors: `api-design`. This skill decides where the file holding it sits.
 - Where a new path gets written into a plan, and the plan's shape: `plan-feature` and the plan standard
-- The pointer here that every session of a code stack loads: `000-code`
-- Runner, suffix, and top-level test folder conventions per language: `300-testing-ts`, `330-testing-py`, `335-testing-go`, and `336-testing-php`
+- The pointer here that every session of a code stack loads: `routing`
+- Runner, suffix, and top-level test folder conventions per language: `testing-ts`, `testing-py`, `testing-go`, and `testing-php`

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

@@ -1,15 +1,13 @@
 ---
 name: create-rule
-description: Why a project-local rule needs a subdir, a number from the band reserved for one, and a scope key that decides when it fires
+description: Why a project-local rule needs a subdir, a slug free in it, and a scope key that decides when it fires
 ---
 
 # Create rule requirement
 
 ## Gap
 
-Without this skill, a project rule is written straight into the rules folder on a number already taken, so two rules collide and one loses. The subtler collision was with the toolkit itself: a number free in the target today could be the number a shipped rule landed on tomorrow, and the next install double-booked it, so a rule the project wrote got overwritten by one it never chose. Writing under `.claude/rules/project/` closes that half regardless of the number, since the sync engine orphans the file by location before it ever compares names.
-
-Numbering in `900-999` closes the other half. A number scanned against today's toolkit catalog goes stale on the next release, and a reserved band does not.
+Without this skill, a project rule is written straight into the rules folder under a name already taken, so two rules collide and one loses. The subtler collision was with the toolkit itself: a name free in the target today could be the name a shipped rule landed on tomorrow, so a rule the project wrote got overwritten by one it never chose. Writing under `.claude/rules/project/` closes that collision whatever the name, since the sync engine orphans the file by location before it ever compares names, and leaves only a slug taken in the same project subdir to check.
 
 The subdir gets picked by feel, so a UI copy rule lands in the always-on folder and loads on every session for the rest of the project's life. The scope key fails in both directions. An always-on rule carrying a path scope fires only on files it was never about, and a path-scoped rule missing it loads constantly. Written from memory rather than from the rule standard, the body comes out in a shape the rest of the catalog does not share.
 
@@ -18,24 +16,24 @@ The subdir gets picked by feel, so a UI copy rule lands in the always-on folder
 - Resolve what the rule enforces and where it applies, asking only for what the request leaves missing
 - Pick the subdir from the topic and take the folder from that choice
 - Write under `.claude/rules/project/`, the subfolder the sync engine reads as project-authored by location
-- Take the lowest free number at or above `900`, scanning every project subdir the target holds rather than one
+- Take a slug no rule in the chosen project subdir uses and that equals no subdir name
 - Read the rule standard before writing the body
 - Emit the path scope for a path-scoped rule and omit the key entirely for an always-on one
-- Preview the resolved path, subdir, number, and frontmatter, then write without pausing
+- Preview the resolved path, subdir, slug, and frontmatter, then write without pausing
 - Say when the rule loads, since path-scoped and always-on rules behave differently
 
 ## Must not
 
 - Edit a toolkit source rule, which is authored in the toolkit and would be overwritten here
 - Work the body shape or the frontmatter from memory
-- Take a number below `900`, which a later toolkit release can ship into
+- Overwrite a project rule already holding the slug
 - Write more than one topic into a single rule
 
 ## Guards
 
 - No project Claude directory: stop, since there is nowhere for the rule to live
 - The request names no behavior to enforce: stop rather than inventing one
-- The reserved band holds no free number: stop rather than reaching below `900`
+- The topic's slug is taken in the chosen subdir: stop and propose a narrower one
 
 ## Out of scope
 

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

@@ -1,6 +1,6 @@
 ---
 name: create-rule
-description: Scaffolds a project-specific governance rule into `.claude/rules/project/<subdir>/<n>-<slug>.md` with correct frontmatter and a non-colliding number. Use when asked to "add a rule", "create a governance rule", "write a project rule", or when a project needs a coding rule the toolkit does not ship. Do NOT use to edit toolkit source rules under `governance/rules/`.
+description: Scaffolds a project-specific governance rule into `.claude/rules/project/<subdir>/<slug>.md` with correct frontmatter and a slug no other rule in that subdir takes. Use when asked to "add a rule", "create a governance rule", "write a project rule", or when a project needs a coding rule the toolkit does not ship. Do NOT use to edit toolkit source rules under `governance/rules/`.
 metadata:
   family: generate
 ---
@@ -35,19 +35,19 @@ Pick the subdir from the topic. It sits under `.claude/rules/project/` and names
 - `tooling/`: dev setup, such as CI workflows, dependencies, and config.
 - `writing/`: prose and document shape.
 
-## Step 3: pick a free number
+## Step 3: pick a free slug
 
-A project-authored rule numbers in `900-999`, the band reserved for one. `000-899` belongs to the toolkit, so a number free in the target today is one a later release can ship into.
+A rule's filename is its slug alone, a one-to-three-word kebab topic with no number in front. A slug the toolkit ships is no collision, since `canon/` and `project/` install side by side and a sync never reads the second.
 
-- Scan every `.claude/rules/project/<subdir>/` in the target for used prefixes, not only the subdir this rule lands in. The band runs as one sequence across all of them.
-- Take the lowest unused number at or above `900`.
-- Stop and say so if the band is full, rather than reaching below `900`.
+- Take a slug no file in the chosen `.claude/rules/project/<subdir>/` already uses.
+- Never take a slug equal to a subdir name from Step 2, since a stack entry naming that word reads it as the folder.
+- Stop and say so when the topic's natural slug is taken, and propose a narrower one rather than overwriting the file.
 
 ## Step 4: write the rule
 
 Read `${CLAUDE_SKILL_DIR}/references/rule.md` for frontmatter, body shape, and voice before writing the body. Do not work the shape from memory.
 
-Write `.claude/rules/project/<subdir>/<n>-<slug>.md` where `<slug>` is a 1-to-3-word kebab topic. Preview the resolved path, subdir, number, and frontmatter, then write immediately. The tool permission dialog is the confirmation gate.
+Write `.claude/rules/project/<subdir>/<slug>.md`. Preview the resolved path, subdir, slug, and frontmatter, then write immediately. The tool permission dialog is the confirmation gate.
 
 Frontmatter carries the Claude shape. Path-scoped rules emit one `paths:` entry per glob. Always-on rules omit `paths:` entirely.
 
@@ -70,4 +70,4 @@ Title casing is sentence case, with proper nouns keeping their own casing (`# Ty
 
 ## After writing
 
-Emit the full path on its own line: `.claude/rules/project/<subdir>/<n>-<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads or writes a matching file, and always-on rules every session.
+Emit the full path on its own line: `.claude/rules/project/<subdir>/<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads or writes a matching file, and always-on rules every session.

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

@@ -11,8 +11,7 @@ description: Rule frontmatter, body shape, and voice for .claude/rules files
 - [Scope](#scope)
 - [Whether a skill belongs behind the rule](#whether-a-skill-belongs-behind-the-rule)
 - [Location](#location)
-- [Reserved numbers](#reserved-numbers)
-- [Two sources numbering into one folder](#two-sources-numbering-into-one-folder)
+- [Names](#names)
 - [Frontmatter](#frontmatter)
 - [Body](#body)
 - [Examples](#examples)
@@ -27,7 +26,7 @@ A rule with `paths:` loads on a read or a write of a matching file, inside a lin
 
 ## Scope
 
-Governs governance rules under `.claude/rules/`: their location, numbering, frontmatter, and body shape.
+Governs governance rules under `.claude/rules/`: their location, names, frontmatter, and body shape.
 
 Does not govern:
 
@@ -45,33 +44,22 @@ Write both when both apply. A rule stating the directive and a skill stating how
 
 ## Location
 
-- A toolkit-shipped rule lives at `.claude/rules/canon/<subdirectory>/<n>-<slug>.md`. The wrapper marks the file as toolkit-owned and replaced on sync, so a reader unfamiliar with the numbering convention still knows not to edit it.
+- A toolkit-shipped rule lives at `.claude/rules/canon/<subdirectory>/<slug>.md`. The wrapper marks the file as toolkit-owned and replaced on sync, so a reader still knows not to edit it.
 - Subdirectories group by domain or audience: `code/`, `lang/`, `framework/`, `lib/`, `ui/`, `claude/`, `canon/`, `tooling/`, `writing/`
-- `<n>` is a number from the band reserved for the rule's source and `<slug>` is a one-to-three-word kebab topic
-- A rule the project authored itself lives at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`, a sibling of `canon/` rather than nested inside it, keeping the same subdirectory names
-- This repository's own toolkit-only rules, which never ship to a target, live at `.claude/rules/internal/<subdirectory>/<n>-<slug>.md`, a second sibling of `canon/`. See "Two sources numbering into one folder" below.
-- Give every authored rule a numeric prefix. A bare-word filename reads as a folder name where a stack names its rules, so a rule without one is unreachable from a stack entry.
+- `<slug>` is a one-to-three-word kebab topic
+- A rule the project authored itself lives at `.claude/rules/project/<subdirectory>/<slug>.md`, a sibling of `canon/` rather than nested inside it, keeping the same subdirectory names
+- This repository's own toolkit-only rules, which never ship to a target, live at `.claude/rules/internal/<subdirectory>/<slug>.md`, a second sibling of `canon/`.
 
-## Reserved numbers
+## Names
 
-`000-899` is reserved for a rule set that ships to targets, and the nine subdirectories above divide it at 100 per subdirectory, in the order listed. No band is left over, so a subdirectory a shipped set adds later joins an existing band or takes one a retired subdirectory freed.
+A rule's filename is its slug, with no number in front. Nothing orders rules at load, and the folder already names the domain.
 
-A project-authored rule takes `900-999`, one sequence across every subdirectory under `.claude/rules/project/`. Scanning for a free number instead is what fails, because a shipped set fills its own band release by release, so what reads as free today is what a later release lands on. One target authored `claude/561-self-check.md` on a day nothing shipped at 561, met the shipped teach rule, then numbered 561, on its next install, and now reads two numbers differently from everywhere else.
-
-The cost is that a project-authored rule's leading digit stops naming its domain. Its subdirectory names it instead, and install preserves that either way. What a shared band costs is worse: a session that loads two rules reading as one number, with nothing in the folder to say which is which.
+- Keep every basename unique across a rule set, internal rules included, since `canon gov` resolves a stack entry and a rename by basename alone.
+- Never name a rule after a subdirectory. A stack entry naming that word expands to the whole folder, so the rule becomes unreachable on its own.
+- A project-authored rule needs its slug free only inside its own subdirectory under `.claude/rules/project/`. A slug the toolkit ships collides with nothing there, since `canon/` and `project/` install side by side.
 
 `canon gov sync` walks only `.claude/rules/canon/`, so `.claude/rules/project/` sits outside the walk by location and is never matched, read, or reported on. A file under `.claude/rules/canon/` itself that no toolkit source names is still reported orphaned, but with no destination offered: the toolkit cannot tell a rule the project dropped there from one it shipped and later renamed, and a destination nested inside `canon/` would be wrong for the first case regardless, since that folder is toolkit-owned and replaced on sync. Nothing is moved either way, since a rule's installed path is one the project's own rules, skills, and docs may cite.
 
-## Two sources numbering into one folder
-
-The reservation above divides one pair, being a shipped set against the rules a project wrote for itself. A third source, a rule set held back from targets and installed only where it was authored, needs its own division too. This repository is the one place all three sources exist at once, and it divides the third pair two ways at once rather than one: `canon/` and `internal/` separate a shipped rule from an internal one by location, the same way `project/` separates a project-authored one, and within each subdirectory the numbering still divides by source as well, one source taking the top of the band and the other the gaps between the tens.
-
-The numbering half stays because location alone does not carry to a reader who only sees the number, such as one comparing `claude/566-output.md` against a citation written before the rules moved into `canon/`.
-
-The collision this prevents is silent. Two rules that resolve to the same `<n>-<slug>` path leave one file in the installed folder, and neither the install nor the session that reads it reports which source lost. Nothing checks a division outside the reserved bands, so it holds only while both sources follow it. Separating `canon/` from `internal/` by folder removes the filename-collision case specifically, since the two no longer install to the same directory, but the number still carries the source signal for a reader who has only the number in view.
-
-State that division where the rule sources are described, not inside the rules it divides. A rule states its own topic, and a numbering convention spanning two sources belongs to whatever documents the pair.
-
 ## Frontmatter
 
 - `description` (required): one line naming what the rule enforces and where

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

@@ -162,7 +162,7 @@ allowed-tools: <tools required>
 
 - 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
+- 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>`
 

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

@@ -27,7 +27,7 @@ A session handed either one unfiltered adopts a stack the project does not use,
 - Enumerate the layers in settle order, so an instruction to name one has a catalog behind it
 - State that a round varies one layer, and that a complaint is worked at the lowest layer it reaches rather than the cheapest one to change
 - Carry grey-boxing as the operational form of the ordering rule, since removing the higher layers from view is what makes a lower one judgeable
-- Cite the correctness floor rather than restating it. `400-ui`, `410-a11y`, `420-forms` and `430-ux-completeness` already carry accessibility, keyboard, forms, states and rendered copy on the rendered paths, and a second copy here drifts with nothing comparing the two.
+- Cite the correctness floor rather than restating it. `copy`, `a11y`, `forms` and `ux-completeness` already carry accessibility, keyboard, forms, states and rendered copy on the rendered paths, and a second copy here drifts with nothing comparing the two.
 - Hold in the body what every design moment pays for, being the read, the layers, the ordering, grey-boxing and the locks, and defer everything a single moment needs.
 - State what has to stay constant across a whole surface, since coherence is a property of the whole and each of those is broken one section at a time.
 - Detect the mode before reading anything when a surface already exists, and name what cannot change silently, since a slug, a field name or an analytics event breaks something outside the surface.
@@ -66,11 +66,11 @@ A rule failing any of the four is recorded as considered and declined rather tha
 
 ## Out of scope
 
-- Accessibility, keyboard interaction, ARIA and alt text, which `410-a11y` owns on every rendered path
-- State coverage, empty and loading treatment, destructive confirmation and truncation, which `430-ux-completeness` owns
-- Validation timing, error placement and save blocking, which `420-forms` owns
-- Rendered copy casing, button labels and error wording, which `400-ui` owns
+- Accessibility, keyboard interaction, ARIA and alt text, which `a11y` owns on every rendered path
+- State coverage, empty and loading treatment, destructive confirmation and truncation, which `ux-completeness` owns
+- Validation timing, error placement and save blocking, which `forms` owns
+- Rendered copy casing, button labels and error wording, which `copy` owns
 - The candidate loop, the arm set, the render and the pick, which `draft-and-pick` owns and which this skill is loaded alongside rather than inside
-- The shape of the project's design document, its sections and its token tables, which `claude/skills/canvas-board/references/design.md` governs
+- The shape of the project's design document, its sections and its role tables, which `claude/skills/canvas-board/references/design.md` governs
 - Prose on the surface being designed, which `write-human` and `markdown.md` govern between them
 - Measuring whether finished output followed these rules, which needs a check this skill does not carry and which no command reaches while a render is an image rather than a parse

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

@@ -113,7 +113,7 @@ Never change these without saying so and getting agreement, because each one bre
 
 Read `${CLAUDE_SKILL_DIR}/references/systems.md` when establishing or revising what a surface draws from, being the space scale, the type scale, and the relationships a palette holds. Every other reference here is read against a draft. That one is read before there is one, so a project reaches for it at the start and on a system revision rather than on an ordinary round.
 
-It states no values. A value belongs to the project's own design document.
+It states no values. A value belongs to the project's own stylesheet, and its intent to the design document.
 
 ## The rest of the catalog
 
@@ -145,6 +145,6 @@ Run `${CLAUDE_SKILL_DIR}/references/preflight.md` against the output. It is the
 - States, empty and loading coverage, destructive confirmation, truncation: the same rules
 - Rendered copy casing, button labels, error message shape: the same rules
 - The candidate loop, the arm set, the render, and the pick: `draft-and-pick`
-- The shape of the project's design document and its token tables: `${CLAUDE_SKILL_DIR}/../canvas-board/references/design.md`
+- The shape of the project's design document and where its values live: `${CLAUDE_SKILL_DIR}/../canvas-board/references/design.md`
 - Reading source for roughness: `ux-audit`. Measuring what a running interface costs to paint: `ux-measure`
 - Prose on the surface being designed: the `write-human` skill

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

@@ -39,7 +39,7 @@ Reaching for size is the first instinct and the weakest tool.
 - **Measure.** Body text running the full width of a wide container is unreadable however good the type is.
 - **Figures in columns.** Numbers that change, in a table, a price or a timer, need tabular figures or the column jitters.
 - **Tracking by size.** Large type wants tighter letter spacing, small uppercase labels want looser. Body text wants whatever the face was drawn with.
-- **Casing.** Sentence case for headings and labels. `465-interface-casing` states the rule and its exceptions.
+- **Casing.** Sentence case for headings and labels. `interface-casing` states the rule and its exceptions.
 
 ## Depth and texture
 

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

@@ -28,7 +28,7 @@ Skip nothing on the ground that it is obviously fine. A rule is on this list bec
 
 - [ ] 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 `465-interface-casing`
+- [ ] Small uppercase labels above headings number no more than one per three sections, per `interface-casing`
 - [ ] At most one horizontal marquee
 - [ ] Grid cells equal content items, with no blank tile filling a gap
 - [ ] Lists over five items use something other than a longer list
@@ -62,7 +62,7 @@ Skip this group where the surface draws on a system already settled.
 - [ ] Every number either real, labeled as sample, or removed
 - [ ] No placeholder that reads as placeholder: generic names, generic company names, reused portraits, identical dates
 - [ ] No filler verbs
-- [ ] Sentence case throughout, with exceptions per `465-interface-casing`
+- [ ] Sentence case throughout, with exceptions per `interface-casing`
 - [ ] Every claim about what the product does is a thing it does
 
 ## Motion

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

@@ -61,7 +61,7 @@ These are the rules with numbers, so they are checked by counting rather than by
 
 - **A layout family appears once.** Once a section uses a shape, no other section on the surface uses it. Eight sections need at least four distinct families.
 - **Two consecutive splits, never three.** Alternating image-left and image-right reads as considered twice and as filler by the third. Break it with a full-width section, a vertical stack, a grid, or anything else.
-- **One small uppercase label per three sections.** The tiny wide-tracked line above a heading is the single most over-reached default in model output. `465-interface-casing` carries the count. The fix is usually to delete it, since a section's position already says what it is.
+- **One small uppercase label per three sections.** The tiny wide-tracked line above a heading is the single most over-reached default in model output. `interface-casing` carries the count. The fix is usually to delete it, since a section's position already says what it is.
 - **One marquee.** Two sliding strips on one surface read as filler rather than as a device.
 - **Cells equal items.** A grid with a hole in it, or a blank tile at the end, means the grid was shaped before the content was counted. Reshape it.
 - **Over five items wants a different component.** A longer list is the lazy answer. Group into clusters, split into columns, give each item a card, make them scrollable, or collapse the tail behind a disclosure.

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

@@ -18,11 +18,12 @@ One identity rendered twice: the same mark sized down to an icon sequence and co
 
 Read these in parallel, skipping any that do not exist:
 
-- `canon/DESIGN.md`: the `## Personality`, `## Color`, and `## Typography` sections
+- `canon/DESIGN.md`: the `## Overview` paragraph and the role intents under `## Colors` and `## Typography`, read under their earlier names `## 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 the three is not a stop. Draft against a neutral default and tag the color and type choices `? verify` per `${CLAUDE_SKILL_DIR}/../canvas-board/references/design.md`'s uncertainty tag.
+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 this run writes, since the design document carries no value to tag.
 
 ## Step 2: detect the icon size sequence
 

package/claude/skills/markdown-craft/references/markdown.md

@@ -42,7 +42,7 @@ Does not govern:
 ## Headings
 
 - H1 for document title, H2 for main sections, H3 for subsections
-- Use sentence case for all headings (H1, H2, H3)
+- Use sentence case for all headings (H1, H2, H3). The audit reports a heading or a frontmatter `title` with a capitalized word after the first, and a proper noun it reports stays as it is.
 - Proper nouns and product names retain their casing in headings
 - Past roughly 40 rendered lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint, not a cap.
 - Count rendered lines rather than source lines, wrapping each source line at 80 columns and summing the heights. Source lines undercount a file authored one line per bullet, where a block of fifteen paragraph-bullets occupies fifteen lines and renders past sixty. A checkpoint another standard states counts the same unit, so a file measured one way never sits beside a run measured another.
@@ -80,7 +80,8 @@ Does not govern:
 
 ## Punctuation
 
-- Do not use em dashes (`—`) or semicolons (`;`). Rewrite or restructure the sentence to avoid them.
+- Do not use em dashes (`—`) or semicolons (`;`). Rewrite or restructure the sentence to avoid them. A colon or a comma standing where the dash was is the same sentence, so split it or rewrite it.
+- Do not use a colon to join two clauses in the middle of a sentence. A colon belongs after a label or at the end of a line introducing a list.
 - Do not use parenthetical asides in prose (`the config (which is optional) controls...`). Split into its own sentence or drop it. Parentheses in rule definitions for grouping examples are fine.
 
 ## Language