@erclx/canon 5.34.0 → 5.36.0

package/README.md

@@ -61,20 +61,19 @@ 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 |
-| Standards      | Authoring conventions for commits, branches, plans, tasks, and markdown                                                  | Opened by name, read by name with `canon standards <name>`      |
-| 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`                                                 |
-
-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 standard stays here and is opened by name, so there is no copy in your repo to drift from this one.
+| 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.
 
 Governance is the third shape. A rule with a path glob loads only when a matching path is edited, and a rule with none loads every session. Run `canon gov list` to see the glob beside each rule.
 
@@ -152,9 +151,9 @@ git init
 canon init
 ```
 
-`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/`. Each rule names the standard it answers to and reads it with `canon standards <name>`, so no corpus is copied into your project.
+`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the workflow and doc-authoring rules in `.claude/rules/`. Each rule names the skill it loads, so no corpus is copied into your project.
 
-Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. Run `canon tooling list --json` to see the catalog.
+Pass `--stack <name>` for a language stack such as `node` or `python`, or `--skip governance` to leave rules out. Run `canon tooling list --json` to see the catalog.
 
 For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target/projects.md).
 
@@ -164,7 +163,6 @@ Each domain carries an entry written for someone maintaining the toolkit rather
 
 - [Claude Code plugin](canon/context/claude-plugin/index.md)
 - [Governance rules](canon/context/governance/index.md)
-- [Standards](canon/context/standards/index.md)
 - [Tooling stacks](canon/context/tooling/index.md)
 - [Design system](canon/context/design/index.md)
 - [Slides](canon/context/features/slides.md)

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

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

@@ -9,7 +9,7 @@ description: Why a session changing what a caller can see needs stated rules on
 
 Without this skill, a session changing a surface a caller depends on has nothing in front of it about what that caller can see or how a change lands without breaking it. It works for the one caller it opened, renames a field in place, returns whatever record it had in hand, and nothing in the toolkit answers before the change ships.
 
-The absence is measured across the shipped corpus. No folder under `claude/skills/` matches `api`, `interface`, or `contract`, and no file across `claude/`, `governance/`, and `standards/` carries `hyrum` or a form of `idempotent`. The only related lines are the two error bullets in the core code rule, which state that errors are structured and hide internals and say nothing about exposure, versioning, or retries.
+The absence is measured across the shipped corpus. No folder under `claude/skills/` matches `api`, `interface`, or `contract`, and no file across `claude/` and `governance/` carries `hyrum` or a form of `idempotent`. The only related lines are the two error bullets in the core code rule, which state that errors are structured and hide internals and say nothing about exposure, versioning, or retries.
 
 The one skill nearest the subject leaves the pointer open. `codebase-layout` excludes shaping "a module's interface and seams" in its description and names no skill to take it, so a session routed away from layout on that question lands nowhere.
 

package/claude/skills/auto-ship/references/draft-mark.md

@@ -29,4 +29,4 @@ The number crosses from that step's output into a command this session types, wh
 
 Report what the read returned rather than what the command printed, since the exit says the call ran and says nothing about the state. A `true` reports a draft. A `false` reports the pull request as opened ready and unsupervised, and the chain stops there. Never re-issue the mark on a disagreeing read, which fights whoever readied it instead of guarding anything.
 
-Placement is why the call sits ahead of the watch rather than after it. Marking afterwards leaves the pull request unmarked for the whole CI run, which is the stretch an unattended worker's branch is least supervised. What the mark buys is a reader learning the pull request has had no review yet. It buys no bound on that stretch: readying a pull request to merge lifts the mark, GitHub requires it before a merge, and the act belongs to the operator or to the controlling session that closed the review, whichever it is, taken directly on the pull request rather than delegated to a worker. `role-worker` states the mirroring refusal.
+Placement is why the call sits ahead of the watch rather than after it. Marking afterwards leaves the pull request unmarked for the whole CI run, which is the stretch an unattended worker's branch is least supervised. What the mark buys is a reader learning the pull request has had no review yet. It buys no bound on that stretch: readying a pull request to merge lifts the mark, GitHub requires it before a merge, and the act runs through `canon pr lift`, which a reviewer runs on its close and the controlling session runs as the fallback, or through the operator directly. `role-worker` states the mirroring refusal of an instruction to ready the pull request directly, whoever sends it.

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
@@ -27,15 +28,14 @@ Consult to pick the `canon` verb for a job, and before running a verb that write
 
 ## Domains
 
-| Job                                                             | Verb              |
-| --------------------------------------------------------------- | ----------------- |
-| Install or sync governance rules                                | `canon gov`       |
-| Read an authoring standard by name                              | `canon standards` |
-| Sync a tooling stack's configs and seeds, or read its reference | `canon tooling`   |
-| Set up or sync the Claude workflow                              | `canon claude`    |
-| Scaffold a wiki                                                 | `canon wiki`      |
-| Regenerate the `index.md` files                                 | `canon indexes`   |
-| Read a toolkit reference doc                                    | `canon docs`      |
+| Job                                                             | Verb            |
+| --------------------------------------------------------------- | --------------- |
+| Install or sync governance rules                                | `canon gov`     |
+| Sync a tooling stack's configs and seeds, or read its reference | `canon tooling` |
+| Set up or sync the Claude workflow                              | `canon claude`  |
+| Scaffold a wiki                                                 | `canon wiki`    |
+| Regenerate the `index.md` files                                 | `canon indexes` |
+| Read a toolkit reference doc                                    | `canon docs`    |
 
 ## Author and render
 
@@ -84,12 +84,12 @@ Read the doc each line names before running one of these. `canon docs install-an
 
 - `canon sync` runs every installed domain's sync, so it carries each risk below.
 - `canon gov sync` replaces a rule you edited and deletes a rule the toolkit retired, edited or not.
-- `canon tooling sync --write` replaces every golden config a stack ships. Seeds are copy-once and dictionaries merge. Nothing writes without the flag. See `canon docs sync`.
+- `canon tooling sync --write` replaces every golden config a stack ships. Seeds are copy-once. Nothing writes without the flag. See `canon docs sync`.
 - `canon design sync` replaces the shipped design files and leaves `.claude/design/project/` alone.
 - `canon migrate --write` rewrites files that cite a retired name or layout. It reports and writes nothing without the flag. See `canon docs migrate`.
 - `canon indexes regen` rewrites each generated `index.md` from the folder's current state, so a hand edit there is lost. See `canon docs indexes`.
 
-No command writes a standard into a project, so `canon standards` is safe to run. `CLAUDE.md` and the other seed docs are copy-once, and no sync updates them. Merge those by hand against the toolkit copy.
+`CLAUDE.md` and the other seed docs are copy-once, and no sync updates them. Merge those by hand against the toolkit copy.
 
 ## Source of truth
 

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/SKILL.md

@@ -11,7 +11,8 @@ Read these files in parallel:
 
 - `${CLAUDE_SKILL_DIR}/references/skill.md`: skill structure, skill types, frontmatter fields, invocation rules
 - `${CLAUDE_SKILL_DIR}/references/skill-requirement.md`: what `REQUIREMENT.md` must answer, its sections, and its template
-- `${CLAUDE_SKILL_DIR}/references/skill-paths.md`: which root a path in the body resolves against, and how the body cites a standard
+- `${CLAUDE_SKILL_DIR}/references/skill-paths.md`: which root a path in the body resolves against, and how the body cites another skill's reference
+- `${CLAUDE_SKILL_DIR}/references/skill-reference.md`, when the skill carries a reference setting the shape of one artifact: its scope, success criterion, frontmatter, and rule phrasing
 - `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`: punctuation and formatting for skill body text
 - `${CLAUDE_SKILL_DIR}/references/skill-practice.md`, when the skill carries engineering practice: the closing sections a practice skill owes and the anatomy behind them
 - The `write-human` skill: voice, rhythm, and sentence construction for skill body text