@erclx/canon 5.31.0 → 5.33.0

package/{standards → claude/skills/create-rule/references}/rule.md

@@ -1,14 +1,22 @@
 ---
 title: Governance rule reference
 description: Rule frontmatter, body shape, and voice for .claude/rules files
-paths:
-  - '.claude/rules/**/*.md'
-rule:
-  - 'Read it before writing or editing a rule. Do not work the shape from memory.'
 ---
 
 # Governance rule reference
 
+## Contents
+
+- [Overview](#overview)
+- [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)
+- [Frontmatter](#frontmatter)
+- [Body](#body)
+- [Examples](#examples)
+
 ## Overview
 
 Rules give Claude Code coding constraints scoped to file paths. Claude Code discovers `.claude/rules/**/*.md` at session start.
@@ -41,7 +49,6 @@ Write both when both apply. A rule stating the directive and a skill stating how
 - 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.
-- A rule that only routes a path to a standard is generated, not authored. It lives at `governance/rules/standards/<standard>.md` under the standard's name, carries no number, and installs to `.claude/rules/canon/standards/`. Never hand-edit one. Change its globs and bullets in the standard's `paths` and `rule` frontmatter, and `canon gov regen` rewrites it. The generator refuses a standard named like a band folder, which keeps the bare-word name reachable.
 
 ## Reserved numbers
 

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

@@ -1,6 +1,6 @@
 ---
 name: create-skill
-description: What skill creation is for, the gaps it closes, and why it confirms before writing
+description: What skill creation is for, the gaps it closes, and why it confirms before writing where a person can answer
 ---
 
 # Create skill requirement
@@ -15,19 +15,21 @@ A third failure is a folder created for a moment a rule, a verb, or an existing
 
 A fourth failure is dated provenance in the body. A target asked for an edit citing a measurement taken that day, and the draft carried "measured on" and the date inline, with the authoring standard, the markdown audit, and this skill all passing it. A body collecting those notes reads as history rather than as the rule a session follows.
 
+A fifth failure is the confirmation itself. A worker running a plan that adds a skill reached Step 4, asked a person nobody had dispatched, and the chain parked on a question nobody read. The same description named only the `.claude/skills/` root, which is where a target authors and where a toolkit checkout keeps its `internal-*` skills, but not where its plugin skills live.
+
 ## Must
 
 - Read the authoring standard and the prose standard before drafting, so the draft starts conformant rather than getting corrected into shape
 - Answer, in writing, whether a rule, a verb, or an existing skill already reaches this moment, and whether the body carries a procedure a session would get wrong from first principles. A folder that fails either belongs to the surface that already covers it, not to a new skill.
 - Draft the sibling `REQUIREMENT.md` beside the body, from what the skill is for rather than from the drafted body
-- Confirm the name and both files with the user before writing. The name is the routing key and a folder that disagrees with its frontmatter fails silently.
-- Write to the conventional skills path, so discovery finds it without configuration
+- Confirm the name and both files with the user before writing, where a person is present to answer. The name is the routing key and a folder that disagrees with its frontmatter fails silently. Where nobody is present, record the three answers and both paths in the output and write.
+- Write to the conventional skills path, so discovery finds it without configuration. That is `.claude/skills/` in a target project. In the toolkit's own checkout, which the project root's `claude/.claude-plugin/plugin.json` marks, an `internal-*` skill goes under `.claude/skills/` and a plugin skill under `claude/skills/`
 - Leave the skills audit's dated-provenance check clean for the new folder before reporting it, with each incident moved to the requirement's `Gap`
 
 ## Must not
 
 - Auto-trigger. Creation is a deliberate act and a skill invented from an ambiguous request is worse than none.
-- Write either file before the user has seen it
+- Write either file before the user has seen it, where a user is present
 - Derive the requirement from the drafted body, which records the draft's overfitting as the requirement
 - Gate creation on whether anything will invoke the new skill beyond the author typing its name. That question has no answer yet.
 

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

@@ -1,6 +1,6 @@
 ---
 name: create-skill
-description: Creates a new `SKILL.md` in `.claude/skills/`. Use when asked to "create a skill", add a skill, or make a new skill.
+description: Creates a new `SKILL.md` in `.claude/skills/` in a target project, or in the toolkit's own checkout under `claude/skills/` for a plugin skill and `.claude/skills/` for an `internal-*` one. Use when asked to "create a skill", add a skill, or make a new skill.
 metadata:
   family: generate
 ---
@@ -9,27 +9,28 @@ metadata:
 
 Read these files in parallel:
 
-- `${CLAUDE_SKILL_DIR}/../../standards/skill.md`: skill structure, skill types, frontmatter fields, invocation rules
-- `${CLAUDE_SKILL_DIR}/../../standards/skill-requirement.md`: what `REQUIREMENT.md` must answer, its sections, and its template
-- `${CLAUDE_SKILL_DIR}/../../standards/skill-paths.md`: which root a path in the body resolves against, and how the body cites a standard
+- `${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}/../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
 
 ## Guards
 
-- If `${CLAUDE_SKILL_DIR}/../../standards/skill.md` is not present, stop: `❌ skill.md standard not found. Reinstall the canon plugin.`
+- If `${CLAUDE_SKILL_DIR}/references/skill.md` is not present, stop: `❌ skill.md standard not found. Reinstall the canon plugin.`
 
 ## Steps
 
-1. Answer three questions in writing before drafting anything. Tell the user and stop if a rule, a verb, or an existing skill already reaches this moment, or if the body carries no procedure a session would get wrong from first principles:
+1. Answer three questions in writing before drafting anything. Tell the user and stop if a rule, a verb, or an existing skill already reaches this moment, or if the body carries no procedure a session would get wrong from first principles. A non-interactive run stops on both too, reporting which question failed and writing no folder:
    - Does a rule, a verb, or an existing skill already reach this moment? A folder that only wraps something already reachable duplicates it rather than adding to the catalog.
    - Does the body carry a procedure a session would get wrong from first principles? A one-line wrapper around a single command needs no skill.
    - Will anything invoke it other than the author typing its name? Carry this one into the drafted `REQUIREMENT.md`'s `Must not` section as a review criterion instead, since nothing can answer it before the skill has run.
 2. Draft the full `SKILL.md` from the user's description, stating the current rule alone. An incident and the date it happened belong in the requirement's `Gap`, not in the body or a reference.
 3. Draft the sibling `REQUIREMENT.md` from what the skill is for, in the shape the requirement standard states. Write the gaps from the user's description rather than from the drafted body, since a requirement derived from the body records whatever the draft overfitted to.
-4. Confirm the skill name and both files with the user before writing
-5. Write to `.claude/skills/<name>/SKILL.md` and `.claude/skills/<name>/REQUIREMENT.md`
-6. Run `canon claude skills audit --json` and read `findings.datedProvenance` for rows under `.claude/skills/<name>/`. Move each row's incident into `REQUIREMENT.md` under `Gap`, cut the date from the file the row names, and re-run until no row names the folder.
+4. Confirm the skill name and both files with the user before writing, when a person can answer. Skip the confirmation when `CANON_NON_INTERACTIVE=1` is set or another skill's run invoked this one, such as `auto-ship` or a dispatched worker. Then put the three Step 1 answers and the two drafted paths in the output and continue to Step 5, since a question nobody reads parks the chain.
+5. Resolve the root, then write `<root>/<name>/SKILL.md` and `<root>/<name>/REQUIREMENT.md`. The root is `.claude/skills/` in a target project. Where the project root holds `claude/.claude-plugin/plugin.json`, which is the toolkit's own checkout, the name decides: an `internal-*` skill goes under `.claude/skills/` and every other skill goes under `claude/skills/`, since the plugin ships that tree.
+6. Run `canon claude skills audit --json` and read `findings.datedProvenance` for rows under `<root>/<name>/`. Move each row's incident into `REQUIREMENT.md` under `Gap`, cut the date from the file the row names, and re-run until no row names the folder.
    - When `canon` does not resolve or its record carries no `datedProvenance` key, say the check did not run rather than reporting the skill clean.
 
 Every skill carries a requirement. A skill created without one is a gap someone closes in a later sweep, and the sweep has to reconstruct what the skill was for from the body it already shipped.

package/{standards → claude/skills/create-skill/references}/skill-paths.md

@@ -41,6 +41,7 @@ Know which root a file lives under before referencing it.
 No standard installs into a project, so a body cites one place rather than choosing between two.
 
 - Cite `${CLAUDE_SKILL_DIR}/../../standards/X.md`. The plugin ships the whole standards folder beside `skills/`, so the path resolves in every install.
+- Cite another skill's reference as `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`. A standard that moved into the skill owning it lives there, and the plugin ships the skills side by side, so the sibling path resolves in every install. Name the owner skill rather than copying the file.
 - Never cite `.claude/standards/X.md` from a shipped body. A target holds no such folder. <!-- audit-ignore-citations: .claude/standards/X.md -->
 - Name `canon standards X` instead where the body wants the document rather than a path to open, such as a value it captures or reports. That verb resolves `standards/` at the project root and then the corpus inside the package.
 - State the path once per body, at the site that reads the standard. A later mention of a standard the body already read stays bare, since repeating the path at every mention is noise rather than instruction.

package/{standards → claude/skills/create-skill/references}/skill.md

@@ -1,22 +1,25 @@
 ---
 title: Claude skill reference
 description: Skill structure and authoring rules for Claude Code
-paths:
-  - '.claude/skills/**/SKILL.md'
-  - 'claude/skills/**/SKILL.md'
-  - '.claude/skills/**/REQUIREMENT.md'
-  - 'claude/skills/**/REQUIREMENT.md'
-rule:
-  - "Confirm `canon:create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whether drafted by hand, by another skill, or by `canon:create-skill` itself. Carry the third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate."
-  - 'Report it rather than proceeding silently when `canon:create-skill` does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.'
-  - 'Re-read a skill body this session edited before invoking that skill again in the same session'
-  - 'Do not read a resolved file path in a held body as evidence the body is current'
-  - 'Follow the skill requirement standard for the shape a `REQUIREMENT.md` states. Read it with `canon standards skill-requirement`.'
-  - 'Follow the skill path standard for which root a path in a body resolves against and how a body cites a standard. Read it with `canon standards skill-paths`.'
 ---
 
 # Claude skill reference
 
+## Contents
+
+- [Overview](#overview)
+- [Scope](#scope)
+- [Changing a skill](#changing-a-skill)
+- [Whether a rule belongs beside the skill](#whether-a-rule-belongs-beside-the-skill)
+- [Skill types](#skill-types)
+- [Structure](#structure)
+- [Frontmatter](#frontmatter)
+- [Description](#description)
+- [Body](#body)
+- [Scripts](#scripts)
+- [Invocation](#invocation)
+- [Examples](#examples)
+
 ## Overview
 
 Skills give Claude Code domain-specific constraints and rules inline, so it can act immediately without reading all docs.
@@ -34,7 +37,7 @@ Does not govern:
 - Voice, rhythm, and sentence construction in a skill body: the `write-human` skill
 - Punctuation, formatting, and word choice in a skill body: `markdown.md`
 - The transform from a branch name to a slug a skill carries in a filename: `slug.md`
-- Whether a new skill earns its place: the three-question test in the `create-skill` skill and the creation-time bullet in this standard's own `rule` frontmatter
+- Whether a new skill earns its place: the three-question test in the `create-skill` skill and the creation-time bullet in the `skill` governance rule
 
 ## Changing a skill
 
@@ -133,7 +136,7 @@ allowed-tools: <tools required>
 - Name every file under `references/` in the body at the point a session reads it, since an unnamed reference is never loaded.
 - Open a file under `references/` running over 100 lines with a `## Contents` H2 of anchor links after its H1 and intro, so a session that reads only the top of the file still sees everything it holds.
 - Keep the trigger, the skip condition, and the guard in the body. A run that never reaches the block has to decide that without opening the reference.
-- Never point one skill at a sibling skill's folder for a reference both read. Each skill carries its own copy under `references/`, generated rather than hand-copied by the rule in `## Path resolution`.
+- Point one skill at a sibling skill's reference by the form `skill-paths.md` states, `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`, and name the owner rather than copying the file.
 
 ### Reading and running commands
 
@@ -149,7 +152,7 @@ allowed-tools: <tools required>
 ### Output and tuning
 
 - Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. A bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so a skill body states which path is emitted and leaves the form to that section.
-- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `memory/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, `teach/`, `ready/`, `feedback/`, `picks/`, `evidence/`, `transcripts/`, or `walkthroughs/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. A `review/` writer names its file `<kind>-<slug>.md` and writes it flat, and an `evidence/` folder takes the next two-digit ordinal as `<nn>-<slug>/`, numbered in the order the folders first appeared.
+- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, `teach/`, `ready/`, `feedback/`, `picks/`, `evidence/`, `transcripts/`, or `walkthroughs/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. A `review/` writer names its file `<kind>-<slug>.md` and writes it flat, and an `evidence/` folder takes the next two-digit ordinal as `<nn>-<slug>/`, numbered in the order the folders first appeared.
 - Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
 - When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
 - Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions, never turning a soft cap hard for aesthetic drift.

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

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

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

@@ -69,7 +69,7 @@ An operator who answers some and not others has answered those. Continue on the
 
 Restate each pick in one line, then continue the work.
 
-A pick that changes a written artifact goes into that artifact under the rule its own standard sets. An answer to an open plan question rewrites that question's `- Suggested:` line to the pick and names the operator as its source, leaving the `- Answer:` slot blank, per `${CLAUDE_SKILL_DIR}/../../standards/plan.md`. The standard bars a session from filling that slot even when the operator supplied the pick, and the blank slot resolves to the rewritten suggestion, so the record carries the operator's decision either way. A pick that settles nothing written stays in the session.
+A pick that changes a written artifact goes into that artifact under the rule its own standard sets. An answer to an open plan question rewrites that question's `- Suggested:` line to the pick and names the operator as its source, leaving the `- Answer:` slot blank, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`. The standard bars a session from filling that slot even when the operator supplied the pick, and the blank slot resolves to the rewritten suggestion, so the record carries the operator's decision either way. A pick that settles nothing written stays in the session.
 
 Output after the answers land:
 

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

@@ -15,7 +15,7 @@ The instruction against that already existed. `draft-and-pick` Step 1 says to na
 
 The second half is the output itself. A model with no stated direction draws the population average of its training data, which produces interfaces that satisfy every craft rule and still read templated.
 
-Prose is already governed in two halves and design is governed in neither. The character bans ship as data a command reads, and the shapes no closed word set can match needed a skill of their own, because each is a pattern rather than a token. `standards/design.md` governs the shape of a project's design document and is silent on whether its values are any good.
+Prose is already governed in two halves and design is governed in neither. The character bans ship as data a command reads, and the shapes no closed word set can match needed a skill of their own, because each is a pattern rather than a token. `claude/skills/canvas-board/references/design.md` governs the shape of a project's design document and is silent on whether its values are any good.
 
 Importing an external catalog wholesale fails on what those catalogs turn out to carry. The largest is 1,206 lines in one file, pinned to one framework, one styling library and one animation package, and it scopes itself out of dashboards, data tables and multi-step product UI. A second bans default fonts by name and prescribes a component library.
 
@@ -56,7 +56,7 @@ A rule failing any of the four is recorded as considered and declined rather tha
 - Express intensity as a numeric scale. A session picks a middle value and reports compliance, which satisfies the rule and decides nothing.
 - Claim the reported failure is closed. Nothing measures whether a round follows these rules, so this skill states them and the measurement is owed separately.
 - Duplicate a rule a surface already states for itself, such as slide layout or terminal color, where pointing at that surface is the whole of the correct answer
-- Be reached only by an author typing its name. `standards/skill.md` makes this a review criterion rather than a check, since nothing answers it before the skill has run. The intended non-author caller is the declared read in `draft-and-pick`'s output. A round producing no read, with this skill never loaded, is the evidence that the description's triggers are too weak.
+- Be reached only by an author typing its name. `claude/skills/create-skill/references/skill.md` makes this a review criterion rather than a check, since nothing answers it before the skill has run. The intended non-author caller is the declared read in `draft-and-pick`'s output. A round producing no read, with this skill never loaded, is the evidence that the description's triggers are too weak.
 
 ## Guards
 
@@ -71,8 +71,6 @@ A rule failing any of the four is recorded as considered and declined rather tha
 - Validation timing, error placement and save blocking, which `420-forms` owns
 - Rendered copy casing, button labels and error wording, which `400-ui` 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
-- Tracing a reference's color, type and spacing values, which is `sketch-design`
-- The shape of the project's design document, its sections and its token tables, which `standards/design.md` governs
-- Spatial layout and interaction intent of one named surface, which `standards/wireframes.md` governs
+- The shape of the project's design document, its sections and its token 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

@@ -1,6 +1,6 @@
 ---
 name: design-taste
-description: Carries the layer model that decides which design decision settles first, the rules that keep a surface coherent across sections, and the catalog of defaults a model reaches for when nothing states a direction. Use when drafting or judging an interface, a page, or any rendered surface, when output reads generic or templated, when redesigning something that already exists, or when asked to "make this look designed", "why does this look like AI made it", "give it taste", "what layer is this decision at", or "grey-box this first". Do NOT use for accessibility, forms, or state coverage, which the `ui` governance rules carry, for the shape of the project's design document, which `design.md` governs, to run the candidate loop, which is `draft-and-pick`, or to trace a reference's values, which is `sketch-design`.
+description: Carries the layer model that decides which design decision settles first, the rules that keep a surface coherent across sections, and the catalog of defaults a model reaches for when nothing states a direction. Use when drafting or judging an interface, a page, or any rendered surface, when output reads generic or templated, when redesigning something that already exists, or when asked to "make this look designed", "why does this look like AI made it", "give it taste", "what layer is this decision at", or "grey-box this first". Do NOT use for accessibility, forms, or state coverage, which the `ui` governance rules carry, for the shape of the project's design document, which `design.md` governs, or to run the candidate loop, which is `draft-and-pick`.
 metadata:
   family: build
 ---
@@ -145,8 +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`
-- Tracing a reference's color, type and spacing values: `sketch-design`
-- The shape of the project's design document and its token tables: `${CLAUDE_SKILL_DIR}/../../standards/design.md`
-- Spatial layout and interaction intent of one surface: `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`
+- The shape of the project's design document and its token tables: `${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/vocabulary.md

@@ -54,7 +54,7 @@ How a draft is staged while unfinished.
 
 - **FPO**: a placeholder held at the true final size and marked as a placeholder, from print production where it abbreviates "for position only". Marking it is the point, since an unmarked stand-in gets read as a decision.
 - **Greeking**: standing text in for copy that does not exist yet, of which lorem ipsum is the common form. Correct while judging space and wrong once an arm is judged on content.
-- **Grey-box**: drawing every element as a flat neutral block so the layers above the one under judgment are removed from view. Avoid "wireframe", which names a committed document governed by `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md` rather than a drafting stage.
+- **Grey-box**: drawing every element as a flat neutral block so the layers above the one under judgment are removed from view. Avoid "wireframe", which reads as a deliverable rather than a drafting stage.
 
 ## Terms this vocabulary deliberately does not carry
 

package/claude/skills/docs-sync/REQUIREMENT.md

@@ -35,8 +35,8 @@ The quiet one is the baseline. A diff resolved against a bare local ref equals H
 
 ## Out of scope
 
-- The context entries, architecture, wireframes, and task board: `context-fold`, which runs immediately before this skill in the ship chain and resolves the same baseline. The split is by audience, so a file's location decides which skill owns it rather than its subject.
-- The requirements record: `document-health` reads it when asked, and `markdown-propose` rewrites it from the answers
-- `CLAUDE.md` and the installed seed docs: `seed-sync`, which reconciles them per section against the toolkit source
+- The context entries: `context-fold`, which runs ahead of this skill in the ship chain and resolves the same baseline. The task board: `task-complete`, which runs between the two. The split is by audience, so a file's location decides which skill owns it rather than its subject.
+- The requirements record: `document-health` reads it when asked
+- `CLAUDE.md` and the installed seed docs, which an operator reconciles by hand against the toolkit source
 - Changelog entries, which release tooling generates from commit messages
 - Whether the prose conforms to its standards. `canon markdown audit` reports violations and fixes none, and this skill writes prose it does not audit.

package/claude/skills/docs-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-sync
-description: Rewrites stale `README.md` and `docs/*.md` sections based on changes since main. Use before staging, or when asked to "sync the public docs", "update the docs in docs/", or "update the README". Do NOT use for the context entries, planning records, or task board, which `context-fold` owns, or for changelog and `CLAUDE.md` updates.
+description: Rewrites stale `README.md` and `docs/*.md` sections based on changes since main. Use before staging, or when asked to "sync the public docs", "update the docs in docs/", or "update the README". Do NOT use for the context entries, which `context-fold` owns, the task board, which `task-complete` owns, or for changelog and `CLAUDE.md` updates.
 metadata:
   family: ship
 ---
@@ -11,8 +11,8 @@ Read these files in parallel:
 
 - `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`: punctuation and formatting for all generated text
 - The `write-human` skill: voice, rhythm, and sentence construction for all generated text
-- `${CLAUDE_SKILL_DIR}/../../standards/readme.md`: README structure, required sections, and content rules
-- `${CLAUDE_SKILL_DIR}/../../standards/docs.md`: the reader a page under `docs/` serves, its frontmatter, structure, and what it links out rather than carrying
+- `${CLAUDE_SKILL_DIR}/references/readme.md`: README structure, required sections, and content rules
+- `${CLAUDE_SKILL_DIR}/references/docs.md`: the reader a page under `docs/` serves, its frontmatter, structure, and what it links out rather than carrying
 
 ## Diff baseline
 

package/{standards → claude/skills/docs-sync/references}/docs.md

@@ -7,6 +7,17 @@ description: Reader and jurisdiction, frontmatter, page structure, what a page l
 
 Applies to each authored reference page under `docs/`. Skip for `index.md` at any depth, which is generated rather than authored.
 
+## Contents
+
+- [Scope](#scope)
+- [What a working docs page looks like](#what-a-working-docs-page-looks-like)
+- [Frontmatter](#frontmatter)
+- [Structure](#structure)
+- [Content](#content)
+- [Diagrams](#diagrams)
+- [Splitting the folder](#splitting-the-folder)
+- [Template](#template)
+
 ## Scope
 
 Governs each authored reference page under `docs/`, whose reader is an operator running what the project ships rather than developing it, and an agent reading the page cold from a project that consumes it: the frontmatter a page carries, its structure, what it links out to rather than restating, whether it holds a diagram, and when a category earns a subfolder of its own.

package/{standards → claude/skills/docs-sync/references}/readme.md

@@ -1,8 +1,6 @@
 ---
 title: Readme reference
 description: Readme voice, structure, and content conventions
-paths:
-  - '**/README.md'
 ---
 
 # Readme reference
@@ -11,6 +9,15 @@ Applies to every `README.md`. The `## Voice` section states the voice for a repo
 
 The reader is what changes. Reference prose serves someone who already committed to the project and is scanning for a fact. A root README meets someone deciding whether to commit at all, and it is often the only file they read.
 
+## Contents
+
+- [Scope](#scope)
+- [Voice](#voice)
+- [Structure](#structure)
+- [Sections](#sections)
+- [Content](#content)
+- [Examples](#examples)
+
 ## Scope
 
 Governs every `README.md`: voice, heading structure, required and optional sections, the header block, badge selection, and what the page links out to instead of carrying.

package/claude/skills/document-health/REQUIREMENT.md

@@ -23,7 +23,7 @@ The third is silence on an unread axis. Both measured verbs resolve their folder
 - Say which layer answered the classifier sweep, since its model layer being off narrows the read without refusing it
 - Take every checkpoint from the record the verb returns rather than from a number written into the skill
 - Run standalone, and stay callable from the structural check rather than reachable only through it
-- Read the requirements and architecture records for identity drift when the scope reaches them, and print one reminder line per doc from `canon records stale canonical`, since the fold no longer writes the first and only writes the second for a planned slot decision, so nothing else reads either whole
+- Read the requirements record for identity drift when the scope reaches it, and print one reminder line from `canon records stale canonical`, since the fold never writes it, so nothing else reads it whole
 
 ## Must not
 
@@ -43,6 +43,6 @@ The third is silence on an unread axis. Both measured verbs resolve their folder
 
 - Whether a document exists or holds its required sections, which is the structural question `target-check` answers across six domains
 - Banned tokens and structural checkpoints in markdown, which `canon markdown audit` measures from package data. This skill reads rot a ban set cannot state.
-- Rewriting a stale claim once this run has named it, which is `markdown-propose`
+- Rewriting a stale claim once this run has named it, which the operator or the owning skill does
 - Running the toolkit's own checks as one gating set over its own corpus, which is `canon audits run`. That set gates a push and this reports to a reader.
 - Repairing anything an axis names. Each routes to the command or skill that owns it.

package/claude/skills/document-health/SKILL.md

@@ -61,17 +61,17 @@ No verb answers whether a document still describes the tree it was written about
 
 Mark every staleness finding as a reading. It is this session's judgment rather than a measurement, and a report that sets it beside two verb-backed axes without marking it implies evidence the axis does not carry.
 
-### The requirements and architecture records
+### The requirements record
 
-When the scope reaches `canon/REQUIREMENTS.md` or `canon/ARCHITECTURE.md`, read each for identity drift as well as for stale paths, and take the review point from the verb:
+When the scope reaches `canon/REQUIREMENTS.md`, read it for identity drift as well as for stale paths, and take the review point from the verb:
 
 ```bash
 CANON_NON_INTERACTIVE=1 canon records stale canonical --json
 ```
 
-Each doc in the record carries `reviewed` and `releasesSince`. `${CLAUDE_SKILL_DIR}/references/axes.md` holds the identity claim shapes to test and how the record reads. Skip both the read and the verb when the scope excludes the two docs.
+The doc in the record carries `reviewed` and `releasesSince`. `${CLAUDE_SKILL_DIR}/references/axes.md` holds the identity claim shapes to test and how the record reads. Skip both the read and the verb when the scope excludes the doc.
 
-Nothing triggers this review but a request. A finished review routes to `markdown-propose` for the rewrite, and its last edit sets `reviewed:` in the doc's frontmatter to the day the operator's answers landed. This run writes neither.
+Nothing triggers this review but a request. A finished review hands the rewrite to the operator, and its last edit sets `reviewed:` in the doc's frontmatter to the day the operator's answers landed. This run writes neither.
 
 ## Step 4: report per document
 
@@ -103,7 +103,6 @@ When Step 3 read the canonical records, add one reminder line per doc the verb r
 
 ```markdown
 `canon/REQUIREMENTS.md`: reviewed <date>, <n> releases since.
-`canon/ARCHITECTURE.md`: never reviewed.
 ```
 
 Write `reviewed value is not a date: <value>` for a doc carrying `invalidReviewed`, and `no release tags to count` in place of the count when `tagged` is false. Name the unread cause instead when the verb refused or the binary carries no `canonical` kind.

package/claude/skills/document-health/references/axes.md

@@ -40,7 +40,7 @@ Weight is a judgment a reader settles rather than a defect, which the verb state
 
 **Evidence class:** `measured` for the audit's findings, `classified` for the sweep's verdicts.
 
-The audit answers required sections, entry length, citation resolution, reference form, catalog tables, provenance, and index drift. Required sections reach wireframes as well as context entries, naming each wireframe short of the regions, states, copy, or exclusions section its standard requires, which is how a surface on an older wireframe shape reports rather than reading as clean. A citation resolving to nothing is a fact and gates. Entry length, reference form, table shape, and provenance are judgments under every flag.
+The audit answers required sections, entry length, citation resolution, reference form, catalog tables, provenance, and index drift. Required sections reach context entries. A citation resolving to nothing is a fact and gates. Entry length, reference form, table shape, and provenance are judgments under every flag.
 
 The sweep classifies each section as keep, replace or rewrite, history, or move. A `move` verdict is the placement finding proper, naming content sitting in the wrong document. Each verdict carries its own confidence, which is why the class is `classified` rather than `measured`, and a low-confidence `move` is a prompt to look rather than an instruction to cut.
 
@@ -67,17 +67,15 @@ Read each document against the surfaces it names. Four claim shapes are testable
 
 A claim resting on none of the four is unverifiable from here. Report it as unread rather than as passing, which is the same rule the measured axes take when a verb refuses.
 
-### Identity drift in the requirements and architecture records
+### Identity drift in the requirements record
 
-These two records state what the project is and why it is built the way it is, so they go stale by the project changing direction as well as by the tree moving. Test these claim shapes beside the four above:
+This record states what the project is and why it is built, so it goes stale by the project changing direction as well as by the tree moving. Test these claim shapes beside the four above:
 
 - A goal nobody pursues, read against the task board and the recent history
 - A non-goal the project has since shipped
 - A constraint the tree contradicts
-- A decision whose revisit sentence has fired
-- A risk or open question already fixed
 
-Each is a `read`. The review point beside them is `measured`: `canon records stale canonical --json` returns per doc the `reviewed` date from its frontmatter and `releasesSince`, the release tags merged into HEAD after that day. A null `releasesSince` means the doc was never reviewed, and `tagged: false` means no release tag exists to count, so a zero there measured nothing. The count is a reminder of how far the project has moved since someone last read the record whole, never a threshold.
+Each is a `read`. The review point beside them is `measured`: `canon records stale canonical --json` returns the `reviewed` date from its frontmatter and `releasesSince`, the release tags merged into HEAD after that day. A null `releasesSince` means the doc was never reviewed, and `tagged: false` means no release tag exists to count, so a zero there measured nothing. The count is a reminder of how far the project has moved since someone last read the record whole, never a threshold.
 
 **Routes to:** the skill that rewrites a stale claim against an answer, rather than a direct edit from here. A document health run reports and never repairs.
 

package/claude/skills/draft-and-pick/REQUIREMENT.md

@@ -29,34 +29,36 @@ Without this skill, a session facing a decision nobody can settle from a diff:
 - Judges a lower layer through a finished higher one, so an operator asked about composition looks at the palette instead and answers about that.
 - Hands over the combined page alone for a decision about layout, where every arm sits in a column while the media queries answer to the whole window, so no arm is ever seen at its own viewport and a fault that appears only narrower survives the pick.
 - Rebuilds a navigation harness by hand on a run with several rounds, since each round writes its own folder and nothing reaches all of them from one address. Two design tracks hand-wrote the same page picker and theme toggle.
+- Meets a session with no canvas server and drafts into a file instead, which leaves the operator a second surface to open and the run a second close to remember. The canvas is the one drafting surface, so a run without one starts it rather than falling back.
 - Puts the pick question with no address in its output, after capturing the page and reading the image back. The operator then has to ask for a served page before they can look, so the question goes unanswered or gets answered blind.
 - Sets the theme on an arm that persists its own and reads it back on load, so the control reports one theme while the arm renders the other and the set is compared across two.
 
 ## Must
 
 - Produce three to five arms with the shipping state among them, each carrying an id, a label, and what the arm costs.
-- Author the whole candidate set as one self-contained page and render it once, so the comparison arrives as one image, except where the surface under decision is a running app: there the page links a copy of the built stylesheet rather than inlining it, per `references/live-arms.md`.
+- Draft every arm of a round as one self-contained frame on one canvas page and capture that page once as a composite, so the comparison arrives as one image, except where the surface under decision is a running app: there each frame links a copy of the built stylesheet inside the page folder rather than inlining it, per `references/live-arms.md`.
+- Start the canvas when none is serving, and stop on a canvas that refuses to start or answers with a blank shell, rather than drafting into a file.
 - Emit the layer in the run's own output, drawn from the catalog `design-taste` fixes rather than from a word invented per run, and vary the arms at that layer alone. A layer held privately is one nothing can report missing, which is how the instruction went unfollowed while every round passed its own rules.
 - Grey-box the set when the declared layer sits below typography, and say the set is grey-boxed when handing it over, so the operator reads a flat page as the question rather than as unfinished work.
-- Render every arm in one theme at a time, with a control that sets the whole set, so the comparison holds still while the operator reads it, and set the theme in a way that survives an arm reading its own stored preference back on load.
-- Hand over the per-arm file addresses beside the combined page where the declared layer is composition, layout or space, since only a whole-page file at a real viewport answers how an arm behaves at a width, and the browser's own device toolbar is the control.
-- Write a frame from `references/frame.html` where the run has several rounds, so a picker reaches every round from one address. The frame carries no width control of its own.
+- Theme every arm off the attribute the canvas toggle sets on each frame, so one control sets the whole set and the comparison holds still while the operator reads it, and give no arm a script that reads a stored preference back on load over the toggle.
+- Give each frame the width the arm is judged at, since a frame renders at its own layout width and answers how an arm behaves at a width where a column on a shared page could not.
 - Judge each render against a stated bar before handing it over, name the weakest thing on the page, and fix it where that sentence would embarrass the work.
-- Write each iteration to its own folder rather than narrowing the previous one in place, so every earlier round stays openable.
+- Write each iteration to its own canvas page rather than narrowing the previous one in place, so every earlier round stays openable from the canvas page list.
 - Write the run's renders inside the record that cites them wherever one exists, and reserve the scratch path for inputs that are re-runnable and cited by nothing.
 - Render before reporting on any arm, and report a missing browser binary as a refusal naming the repair rather than describing an arm nobody has seen.
-- Take the pick through the structured question surface, with the recommendation ranked first and marked, and every option carrying its cost.
-- Keep every write inside the run's scratch folder until the pick is final.
+- Take the pick through the structured question surface, with the recommendation ranked first and marked, and every option carrying its cost. Read the canvas selection only to resolve an answer that points at it, and treat an empty or stale selection as no answer.
+- Keep every write inside the run's own canvas pages until the pick is final.
 - Apply the winning arm in one change.
-- Capture every arm from the final round as an image before deleting the run's scratch folder, rather than discarding the losing arms with it.
+- Capture every arm from the round the pick came from, whichever round that is, as an image named for its frame before deleting the run's pages, rather than discarding the losing arms with them.
+- Delete only the canvas pages the run itself added, recorded as it adds them, and stop only a canvas server the run itself started.
 - Resolve the archival capture's destination against the main worktree root, never against a linked worktree the run happens to be building in.
-- Serve the candidates on every run, whatever the decision's layer, and emit the local link ahead of the first pick question, so the operator can open the page the question is about and a still is never the only address.
+- Put the candidates on the canvas on every run, whatever the decision's layer, and emit the canvas link ahead of the first pick question, so the operator can open the page the question is about and a still is never the only address.
 
 ## Must not
 
 - Take the pick where two arms are both defensible and the difference is taste. That call is the operator's, and taking it silently is the failure this skill exists to prevent.
 - Draft candidates for a decision the operator has not asked to make. Each arm costs a render, and a run offering options everywhere spends their attention rather than saving it.
-- Restate the mechanics of the render, the address, or the probes. `canon capture`, `canon serve`, and `canon drive` own those and their help text is the source, so a second copy here hands one case two answers.
+- Restate the mechanics of the canvas, the render, or the probes. `canon canvas` and `canon drive` own those and their help text is the source, so a second copy here hands one case two answers.
 - Read a `canon drive` finding as a gate over the arms.
 - Fire on a request that already names one answer.
 
@@ -71,14 +73,14 @@ The refusal strings sit in the body, since the runtime loads that file and ignor
 - `ux-measure` measures what a running interface costs to paint. This measures whatever a visual claim depends on, which is usually geometry or contrast rather than cost.
 - `ui-checklist` writes what to look at on a change already made. This runs before there is a change to look at.
 - `draft-screencast` scripts a recording of something already built. This has nothing built yet.
-- `canon capture`, `canon serve`, and `canon drive` own the render, the address, and the probes, and are invoked rather than reimplemented.
+- `canon canvas` owns the page, the frames, the selection, the address, and the render, and `canon drive` owns the probes. Both are invoked rather than reimplemented.
 
 ### What did not travel
 
-This descends from a project-local skill whose interactive half was written against one repository. Three of its capabilities do not travel, and the three verbs above are what stands in their place:
+This descends from a project-local skill whose interactive half was written against one repository. Three of its capabilities do not travel, and the two verbs above are what stands in their place:
 
-- An arm switcher compiled into the project's own page, driven by a query parameter. `canon serve` over a self-contained scratch page replaces it, which puts the arms in scratch rather than in the source and removes the call site a run had to remember to delete.
+- An arm switcher compiled into the project's own page, driven by a query parameter. A canvas page of frames replaces it, which puts the arms on the canvas rather than in the source and removes the call site a run had to remember to delete.
 - A copy cycle keyed to canonical page text held in a second repository. No toolkit surface has that shape, so a project holding one owns the second edit and this skill states nothing about it.
 - A walker that reads every control on every page and groups them by treatment. `canon drive` probes one page and reports findings, so a sweep across every surface of a site is out of reach here and a run needing one measures by hand.
 
-The capture mechanics traveled with a change of owner rather than being lost. They sat in a project-local path-scoped rule that fired whether or not the skill ran, and `canon capture` owns them here, which is why this file bars restating them rather than naming a rule to defer to.
+The capture mechanics traveled with a change of owner rather than being lost. They sat in a project-local path-scoped rule that fired whether or not the skill ran, and `canon canvas capture` owns them here, which is why this file bars restating them rather than naming a rule to defer to.