@erclx/canon 5.35.0 → 5.37.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.37.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -79,6 +79,9 @@ Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidan
 - A function returns the object it read from storage, or a type defined beside the storage code.
 - The same input check appears both at the entry point and inside a function it calls.
 - A caller matches on the text of an error message.
+
+### Changes, retries, and order
+
 - An existing field is changing type or meaning under the same name.
 - A write that a client could retry carries no key, or checks for one with a read before the insert.
 - Output order follows whatever the underlying data returned, and nothing states whether it is sorted.
@@ -91,6 +94,9 @@ Check each line against the surface the change produced. A line answering no is
 - Every new field, flag, or parameter is optional and defaults to the old behavior.
 - No storage type, internal identifier, or bookkeeping field appears in what the surface returns.
 - Every failure on the surface carries the same shape with a stable code.
+
+### Input, writes, and contract
+
 - Input is checked once, at the boundary, and nowhere deeper.
 - Every write a caller could retry takes a key, claims it atomically, and refuses a reused key with a different body.
 - The contract states what the surface returns and what it refuses.

package/claude/skills/backlog-triage/SKILL.md

@@ -77,13 +77,13 @@ Age is evidence in neither direction. A row untouched for months is not more dec
 
 Write one item per row in the intake item format, one cluster file per domain the task touches, numbered in read order. Head each item `### N. <task stem>` so apply can find the task from the heading alone.
 
-- `Problem:` states what this pass measured, with the count, path, or commit behind it
-- `Fix:` states what applying the verdict does to the board
-- `Worth it:` names the cost or the reach the verdict rests on in one clause, or says the row names neither. A `yes` or a `later` carries no verdict on its own, so a decline can follow either word
-- `Open:` reads `decline, archive, keep, or promote?` on every item
-- `Suggested:` opens with exactly one of the four verdict tokens, then the reason. An archive suggestion lists every outcome position it closes, as `archive 1, 3: shipped in #NNN`
-- `Overlaps:` names a live board task that already carries the work, where one does
-- `You:` ships empty
+- **`Problem:`** states what this pass measured, with the count, path, or commit behind it
+- **`Fix:`** states what applying the verdict does to the board
+- **`Worth it:`** names the cost or the reach the verdict rests on in one clause, or says the row names neither. A `yes` or a `later` carries no verdict on its own, so a decline can follow either word
+- **`Open:`** reads `decline, archive, keep, or promote?` on every item
+- **`Suggested:`** opens with exactly one of the four verdict tokens, then the reason. An archive suggestion lists every outcome position it closes, as `archive 1, 3: shipped in #NNN`
+- **`Overlaps:`** names a live board task that already carries the work, where one does
+- **`You:`** ships empty
 
 Write `00-overview.md` last, per the intake standard, with the verdict counts by token and an open-questions list linking each item. Where the pass runs out of context before the index, write `99-next-session.md` naming the last row filed, since a compaction drops the rest.
 

package/claude/skills/build-in-slices/SKILL.md

@@ -71,6 +71,9 @@ Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidan
 - The next commit message needs "and" to say what it does.
 - A slice has been implemented and its tests have not run yet.
 - The build or a test is failing and the next slice has already started.
+
+### Scope and ordering
+
 - You opened a file the plan does not name and are about to edit it.
 - A commit deletes code and adds its replacement in the same change.
 - You are about to stage a test in a commit after the one that added its code.
@@ -83,6 +86,9 @@ Check each line against the branch the build produced. A line answering no is fi
 - Every commit on the branch carries one logical change and passed the checks it could affect.
 - No commit adds code whose test lands in a later commit.
 - No commit deletes something and adds its replacement together.
+
+### Tree and scope
+
 - The working tree holds no uncommitted implementation work.
 - Every file changed is in the plan's scope, or its commit says why the plan needed it.
 - Every defect noticed outside the plan is written in the task's findings or the handover, and its file is unchanged.

package/claude/skills/build-in-slices/references/adopted.md

@@ -21,6 +21,9 @@ External sources were read and filtered rather than imported. This file is the r
 - Vertical, risk-first, and contract-first slicing, stated as rules for choosing the next slice rather than as worked examples tied to one stack.
 - Rule 1, one thing at a time, as one logical change per commit.
 - Rule 2, keep it compilable, as a build left passing at every commit.
+
+#### Rollback and the notes
+
 - Rule 5, rollback-friendly, as the group on keeping each commit safe to revert and the rule against deleting and replacing in one commit.
 - The "noticed but not touching" list from its scope section, routed to the open task's findings or the handover rather than offered as new tasks, since a worker may not add a row to the board.
 - The note against re-running a command on unchanged code, scoped to a session's own repeats so it never reads as permission to skip a chain's verify step.

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
@@ -84,6 +85,9 @@ 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. Nothing writes without the flag. See `canon docs sync`.
+
+### Design, migrate, and indexes
+
 - `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`.

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

@@ -22,6 +22,11 @@ From the conversation so far, identify:
 - Target project name or kind, never its full path. The path names a folder on one machine and says nothing a triage session can route on, where the project's own name does. Name a private project by its kind instead, such as `a Next.js app`, since the report leaves the machine.
 - Toolkit surface and its type (plugin skill, tooling config, governance rule, seed, or CLI). The type leads the `### Surface` field, ahead of the first comma, because the CLI picks the issue's domain labels from that text alone.
 - Specific toolkit file or name when the session cites one
+
+### Behavior and fix
+
+From the same conversation, identify:
+
 - Observed behavior
 - Expected behavior, or `unclear`
 - Repro details already in context (commands run, files touched), or `none`

package/claude/skills/canon-feedback-triage/SKILL.md

@@ -19,6 +19,9 @@ Run from the toolkit repo root. This skill reads GitHub issues and writes only i
 - If `gh` is not on PATH, stop: `❌ gh CLI not found. Install it to read feedback issues.`
 - If `gh auth status` fails, stop: `❌ gh is not authenticated. Run gh auth login.`
 - If no open `feedback` issues exist, stop: `✅ No open feedback issues.`
+
+### Slots and records
+
 - Never fill a `You:` slot, and never read an empty one as agreement. Answering runs through `plan-intake-answer` or the operator's own edit.
 - Branch on each `canon` record's `ok` and `reason` rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
 

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

@@ -49,6 +49,9 @@ Hand the operator the address as a markdown link carrying the URL as its text an
 - Add a page for each decision being drafted: `canon canvas page add <page> --json`.
 - Follow the house style in `${CLAUDE_SKILL_DIR}/references/canvas.md` before drafting an explanation frame.
 - Add each frame through the verb, which writes the starting file and its box in one locked step: `canon canvas frame add <page> <frame> --width <px> --height <px> --json`. Give the width the frame should render at, since a capture and the canvas both render at it. The verb places the frame after the last one, and a position the operator asks for goes through `frame move`.
+
+### Layout and naming
+
 - Lay frames out with `canon canvas frame move <page> <frame> --x <px> --y <px> --json` rather than writing `layout.json` by hand, since the operator's drags write the same file under a lock.
 - Name pages and frames for what they hold, such as `pricing` and `pricing-dense`, so the operator can say which one by name.
 - After an insert or a resize, re-lay the page with `canon canvas arrange <page> --json`. It keeps the rows the operator dragged, places each on the standard gap, and drops layout entries whose frame file is gone. `--check` reports without writing.
@@ -105,7 +108,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 +119,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/canvas.md

@@ -58,6 +58,9 @@ A canvas failing these is non-conforming even when it satisfies every shape rule
 - Write a frame as a whole document or as a fragment. The server writes in the `html`, `head`, and `body` a fragment leaves out, marked so a pick still matches the file.
 - State a `body` whenever the frame states a `head`. The browser builds one the file leaves out, and an address the operator picks inside the frame can no longer be matched to the file.
 - Write every table with its `tbody` stated, for the same reason. A browser adds one the file leaves out.
+
+### Content and edits
+
 - Keep a frame self-contained. Inline its own styles and scripts, or link a file inside the same page folder, since a frame is served from its page and nothing outside the canvas resolves.
 - Use the project's custom properties, `var(--<name>)`, for every value the token stylesheet defines. A literal copied from it shows the right color today and the wrong one after the next token change.
 - Edit a frame by rewriting its file. The file is the frame, and nothing else holds a copy of its markup.
@@ -70,6 +73,9 @@ Applies to an explanation frame only. A mockup of the project's interface render
 - Keep lines short, one fact a line.
 - Set body text at 20px or larger and headings at 44px or larger. Set nothing under 16px.
 - Render an explanation frame about 1100px wide.
+
+### Colors, faces, and fit
+
 - Take colors from the project's custom properties. A frame that defines colors of its own sets the dark values on `:root` and the light ones under `[data-theme="light"]`, since the shell sets `data-theme` on each frame's root.
 - Name only the faces the canvas serves into every frame: `Geist Variable` for text, `Noto Sans Mono` for code, and `Excalifont` for a hand-drawn look. They render the same in a capture and in any browser, so a height fitted against them holds.
 - Make each box tall enough to show all its content, with no scrollbar and no clipped line. Run `canon canvas fit <page>/<frame>` rather than estimating, since it measures the content in the capture browser and sets the height.
@@ -80,6 +86,9 @@ Applies to an explanation frame only. A mockup of the project's interface render
 - Keep one `layout.json` per page, beside its frames. It holds each frame's box and nothing else, so moving a frame never rewrites its markup.
 - Key each box by the frame's name, under one top-level `frames` object.
 - Give every box four finite numbers in pixels: `x` and `y` for its top-left corner on the page, `width` for the width the frame renders at, and `height` for the height it shows on the canvas.
+
+### Missing boxes and writes
+
 - Leave a frame out of the layout only when its position does not matter yet. A reader places an unnamed frame in a row after the others, at the default size of 1440 by 900.
 - Never write the file while a writer holds its lock, which is the same name with `.lock` appended. Two writers each replacing the whole file lose one of the two edits.
 - Treat a layout that does not parse as a defect to repair, never as an empty one to overwrite. Writing over it erases every box it held.
@@ -106,6 +115,9 @@ The keys below are the ones a reader parses. The frame names are placeholders.
 - Do not assume a viewport. A frame renders at its layout width on the canvas and in a capture alike, so size it with media queries against that width rather than against the operator's window.
 - Do not assume the theme. The canvas theme toggle is the operator's own state, and a capture shows each frame in its default theme.
 - Do not assume a network. Name a served face, or ship the font beside the frame, since a capture refuses a frame naming a font it cannot find.
+
+### Font, source, and checkout
+
 - Do not assume a default font. Set `font-family` with a served face first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines. A frame naming a machine family such as `DejaVu Sans` renders at another height in another browser, which `canon canvas fit` reports.
 - Do not assume the frame is the source. A picked direction is carried into the project's design document or a plan, and the operator clears the frame once it has been carried.
 - Do not assume the canvas survives the checkout. The folder is gitignored, so a lost checkout loses every page in it.

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

@@ -61,6 +61,11 @@ Before responding, verify:
 - All actions pinned to major version tags, no `@latest` or `@main`.
 - A new pipeline folds static, unit, and build into one job, and a gate a run log put past two minutes gives them no `needs` so they run in parallel.
 - Every name in a `needs` matches a job declared in the same file. E2E names the artifact producer, release and deploy name E2E.
+
+### Artifacts, names, and deploys
+
+Before responding, also verify:
+
 - Artifacts upload on `if: failure()` only with `retention-days: 7`.
 - Job names use emoji + title format.
 - Deploy, publish, and release jobs carry a placeholder step and a named handoff, never a guessed deploy command.

package/claude/skills/code-craft/SKILL.md

@@ -83,6 +83,9 @@ Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidan
 - A new class has one method, or a new function's body is one call with the same arguments.
 - The change you are making opens a third file to adjust one rule.
 - You are writing an interface, a factory, or a registry with one implementation behind it.
+
+### Defaults and fixes
+
 - You wrote a default value, a threshold, or a fallback the task never named.
 - A fix is adding a special case, a catch, or a disabled check rather than changing the code that misbehaved.
 - The code reads the current time, an environment variable, or a global from inside a rule.
@@ -95,6 +98,9 @@ Check each line against the code the change produced. A line answering no is fix
 - Every new function or class hides more than its interface asks a caller to learn, with no pass-through left.
 - No rule the change wrote exists in a second place, and nothing was merged that changes for a different reason.
 - Every pattern in the diff solves a problem present now, with more than one case behind it.
+
+### Inputs, scope, and fixes
+
 - Clock, environment, and global reads are passed in rather than taken inside a rule.
 - The diff holds no feature, option, or default the task did not ask for or state.
 - Every fix changes the code that misbehaved rather than silencing it.

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`