@erclx/canon 5.36.0 → 5.38.0

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.36.0",
+  "version": "5.38.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/auto-ship/SKILL.md

@@ -50,7 +50,7 @@ Check for a `**Files to touch:**` or `## Files to touch` marker per `${CLAUDE_SK
 
 Read `<plan>` at the main worktree root. This file is the scope for this run.
 
-Its sections and its answer contract are fixed by `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`. A blank `- Answer:` accepts the `- Suggested:` line above it, so an unanswered question is a decision this run executes rather than a reason to stop. When this run decides against that suggestion, rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement, leaving the `- Answer:` slot blank, and put the same deviation in one line under the open task's `## Findings`, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
+Its sections and its answer contract are fixed by `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`. A blank `- Answer:` accepts the `- Suggested:` line above it, so an unanswered question is a decision this run executes rather than a reason to stop. When this run decides against that suggestion, rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement, leaving the `- Answer:` slot blank, and put the same deviation in one line under the open task's `## Findings`, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`, opening with the bold source-and-date label that `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
 
 ## Step 2: implement
 

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.
 
@@ -112,7 +112,7 @@ Take the task stem from the item heading. Every verdict leaves the folder slug o
 - **keep**: append the `## Findings` line naming what reproduced. The backlog line stays.
 - **promote**: move the backlog line to the bottom of `## Needs a plan` in `.canon/tasks/priority.md`, with a `Waiting on` cell stating what cleared and ending in `last`, then append the `## Findings` line.
 
-Write the `## Findings` line as `- <YYYY-MM-DD>, backlog triage <slug>: <verdict>, <evidence>`. It is the last write on every verdict with a task file behind it, since Step 1 reads it as applied and a line written ahead of a refused move would mark a row done that never moved.
+Write the `## Findings` line as `- **<YYYY-MM-DD>, backlog triage <slug>:** <verdict>, <evidence>`, the bold label form `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes. It is the last write on every verdict with a task file behind it, since Step 1 reads it as applied and a line written ahead of a refused move would mark a row done that never moved.
 
 Before any promote, check the roster the way `task-board` step 4 does: a live session in this repository whose name starts with `orchestrator-` and whose `sessionId` is not this one. When one is found, write the `## Findings` line but not `priority.md` or `backlog.md`, and message that session with the row and its cell so it places the row itself.
 

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

@@ -40,7 +40,7 @@ Leave the build passing at every commit. A slice that cannot pass on its own is
 
 A defect outside the plan that turns up mid-build is a finding, not a slice. Fixing it on this branch widens a diff the plan scoped and hides the fix inside an unrelated review.
 
-- Write it in one line under the open task's `## Findings`, naming the file and what is wrong, when the build is closing a task.
+- Write it in one line under the open task's `## Findings`, naming the file and what is wrong, when the build is closing a task. Open the line with the bold source-and-date label from `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`.
 - Carry it in the handover message instead when no task exists, and never create a file to hold it.
 - Leave the file as it is, even when the fix is one line.
 - Fix it here only when the plan's own change cannot pass without it, and then say so in the commit that does.
@@ -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/SKILL.md

@@ -85,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/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.

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/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/context-fold/references/context.md

@@ -13,10 +13,7 @@ Applies to per-domain narrative entries under `canon/context/`. Skip for `index.
 - [Organizing principle](#organizing-principle)
 - [What a working entry looks like](#what-a-working-entry-looks-like)
 - [Frontmatter](#frontmatter)
-- [Required sections](#required-sections)
-- [Expected sections](#expected-sections)
-- [Optional sections](#optional-sections)
-- [Ordering](#ordering)
+- [The closed set](#the-closed-set)
 - [The development entry](#the-development-entry)
 - [What goes in](#what-goes-in)
 - [What does not go in](#what-does-not-go-in)
@@ -59,40 +56,33 @@ An entry that fails these is non-conforming regardless of whether it satisfies e
 
 Both fields feed `canon/context/index.md` when regenerated.
 
-## Required sections
+## The closed set
 
-- `## Overview`: two to four lines. What the domain owns and where its boundary sits.
-- `## Layout`: one line per folder in owns-X form. Folders only, never files.
-  - Form: ``- `scripts/lib/` owns shared bash functions sourced by domain scripts``. Do not list every file under that folder with a description each.
-  - Implementation detail moves to `## Decisions`, `## Hidden contracts`, or `## Gotchas`.
-  - Omit the section when the domain owns no paths in the repo, as with a domain covering external tools. Inventing a line to satisfy the heading is the padding banned below.
+An entry carries four H2 sections and no other, in this order: `Overview`, `Layout`, `Decisions`, `Gotchas`. `canon context audit` reports any other H2 and `--gate` fails it. A topic of the domain's own, such as `Cache` or `Workflow`, is an H3 under one of the four, which is where a reader scanning the entry looks for it.
 
-## Expected sections
+- `## Overview`: two to four lines. What the domain owns and where its boundary sits. Required.
+- `## Layout`: one line per folder in owns-X form, folders only and never files. Required, and omitted where the domain owns no paths in the repo, as with a domain covering external tools. Inventing a line to satisfy the heading is the padding banned below.
+- `## Decisions`: non-obvious choices and the reasoning behind them, each as an H3 or a bullet. The highest-value section in the folder and the one most often missing. A decision resting on how an outside tool, an installer, or the model behaves may close with one `Revisit when <finding>.` sentence naming the harm the decision prevents, and a decision resting on the project's own code takes none.
+- `## Gotchas`: workarounds, things tried and rejected, and invariants the code does not self-document, such as shape constraints, skip rules, and header semantics. Use `## Decisions` when the reader needs the reasoning rather than the invariant itself.
 
-Include whenever the domain has content for them. Never pad an entry with an empty heading.
+Include `Decisions` and `Gotchas` whenever the domain has content for them, and never pad an entry with an empty heading.
 
-- `## Decisions`: non-obvious choices and the reasoning behind them. The highest-value section in the folder and the one most often missing. A decision resting on how an outside tool, an installer, or the model behaves may close with one `Revisit when <finding>.` sentence naming the harm the decision prevents, and a decision resting on the project's own code takes none.
-- `## Gotchas`: workarounds, things tried and rejected, scar tissue worth preserving.
+### Where an extra topic goes
 
-## Optional sections
+- A command surface goes under `## Layout` as an H3, only when the domain has one, and only as a list of what each verb does. Flags and JSON shapes stay in the CLI reference under `docs/`, linked rather than restated.
+- The procedure for the domain's most common task goes under `## Layout` as an H3 such as `### Adding a <thing>`, since most sessions arrive asking how to add one more of the thing the domain holds.
+- Implementation detail that the one-line owns-X form cannot carry moves to `## Decisions` or `## Gotchas`.
 
-Pick by what the domain is. Add domain-specific headings as needed.
+### Ordering and headings
 
-- `## CLI`: the command surface, only when the domain has one, and only as a list of what each verb does. Flags and JSON shapes stay in the CLI reference under `docs/`, linked rather than restated.
-- `## Workflow` or `## Adding a <thing>`: the procedure for the domain's most common task. Most sessions arrive asking how to add one more of the thing the domain holds.
-- `## Hidden contracts`: invariants the code does not self-document (shape constraints, skip rules, header semantics). Use `## Decisions` when the reader needs the reasoning rather than the invariant itself.
-
-## Ordering
-
-- Order sections `Overview`, `Layout`, `Decisions`, `Gotchas`, then everything else.
-- Name a heading for its subject as it stands (`## Cache`), never for the event that shaped it (`## The cache was the untested part, and the test moved it`). A heading is what a scan reads, so a narrating heading turns the table of contents into a changelog.
+- Name a heading for its subject as it stands (`### Cache`), never for the event that shaped it (`### The cache was the untested part, and the test moved it`). A heading is what a scan reads, so a narrating heading turns the table of contents into a changelog.
 - Entries get read top-down and often partially, so irreducible content sits above recoverable content.
 
 ## The development entry
 
-Only the `development` entry carries this section. It is not a general-purpose heading for other domains.
+Only the `development` entry carries this section, as an H3 under `## Layout`. It is not a general-purpose heading for other domains.
 
-- `## Scripts`: a table of run commands (command plus purpose). The single discoverable surface for how to run the project. Keep run commands here, not scattered across `CLAUDE.md`.
+- `### Scripts`: a table of run commands (command plus purpose). The single discoverable surface for how to run the project. Keep run commands here, not scattered across `CLAUDE.md`.
 
 ## What goes in
 
@@ -100,6 +90,9 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Decisions that constrain the domain, whether or not their reasoning touches another one. A decision lives in the entry of the domain it constrains.
 - Constraints, gotchas, things tried and rejected
 - Domain-specific conventions that do not fit a `paths:`-scoped rule
+
+### Figures and references
+
 - A measured figure, closed with a trailing `Measured at <short-sha> on <YYYY-MM-DD>.` naming a commit rather than a pull request number or a branch. Carry one anchor per figure and rewrite it in place when the number is re-read, whether or not it moved. An absent anchor reads as unchecked.
 - A reference to another entry, spelled as the path that entry sits at rather than as its bare filename. A bare name resolves against whichever folder the reader is already in, so a domain that splits into subfolders strands every inbound reference and the break surfaces nowhere. A reference to a seed, a standard, or a file the project owns elsewhere keeps the form its own surface uses.
 
@@ -109,10 +102,16 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Restated `--help` output, flag tables, or JSON shapes.
 - A catalog a `list` command already returns. Link the command instead, so the entry cannot drift from it.
 - Function-level documentation for implementation modules. Read the code. The exception is the public surface of a shared utility module, where the entry is how a session finds an existing helper instead of duplicating it.
+
+### Elsewhere
+
 - Rules. Those go in `.claude/rules/<scope>.md` with a `paths:` glob.
 - Tutorials or human onboarding. Those go in `docs/` if a public audience exists.
 - Generated content (API references). Generate, do not write by hand.
 - Anything already in `canon/REQUIREMENTS.md`.
+
+### History and results
+
 - The history of how the domain reached its current shape. An entry describes the repository as it stands, so a change number, release label, or date attached to a change goes wherever the project tracks work.
 - A rejected alternative's provenance, which is the same rule at the one place the section above admits history. Keep what was tried and why it lost. Cut who tried it and when.
 - The route to a decision: the rounds of candidates, the tuning steps a threshold passed through, the review pass that caught a miss. State the decision, what lost, and why, once and in the present tense. Cut the route. Git and the change that introduced it keep it.
@@ -122,9 +121,15 @@ Only the `development` entry carries this section. It is not a general-purpose h
 
 - Aim for one entry per domain. Length is a symptom, not the defect, and the one hard cap is the whole-document ceiling `markdown.md` states.
 - Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number. The 150 is a diagnostic checkpoint and never gates. Rendered lines count as `markdown.md` defines them.
-- Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
+- Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` section or an H3 under it instead.
+
+### Retiring and rewriting
+
 - Retire a decision or gotcha once its subject is gone, rewriting the bullet to state the current design rather than leaving the narration of what it replaced beside it. A rejected alternative is not a retired one, so what was tried and why it lost stays whatever its age. The rule above protects content whose subject is live, and this one releases content whose subject is not.
 - Rewrite a decision a later one replaced rather than appending the replacement beside it. The subject is still live, so the rule above does not reach it, and two bullets on one subject leave a reader to work out which of them is current. State the design that stands and keep the superseded reasoning only where it is the alternative that lost.
+
+### Splitting and naming
+
 - Split into a folder (`canon/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
 - Group whole single-file entries of two or more small domains into one folder when they share a kind, such as small feature domains that each own a verb. Each entry still covers one domain, and the folder's generated `index.md` carries a `subtitle` naming the kind. It names an entry to start with only when that entry frames the others. A grouping folder is not a split, so no entry inside it is a sub-area of another.
 - Name an entry inside a split or grouping folder per the `codebase-layout` skill, which never repeats the folder's name as the entry's stem or prefix.
@@ -157,16 +162,25 @@ never the reverse.
 
 ## Decisions
 
-- Validation happens at the route boundary using a schema library. Services trust their inputs.
-- Pagination uses opaque cursor tokens, never offset+limit. Cursor format stays opaque to clients.
+### Validation at the route boundary
+
+Validation happens at the route boundary using a schema library. Services trust their inputs.
+
+### Opaque pagination cursors
+
+Pagination uses opaque cursor tokens, never offset+limit. Cursor format stays opaque to clients, which is why any handler that issues a cursor uses the shared encoder.
 
 ## Gotchas
 
-- The `/health` endpoint skips auth middleware. Liveness probes from the orchestrator do not carry tokens.
-- Database connection pool caps at 50. Concurrent requests over that block until a connection frees.
+### The health endpoint skips auth
+
+The `/health` endpoint skips auth middleware. Liveness probes from the orchestrator do not carry tokens.
+
+### The connection pool caps at 50
+
+Concurrent requests over that block until a connection frees.
 
-## Hidden contracts
+### Handlers never wrap their return
 
-- Route handlers return a plain object. The serializer wraps it in `{ data, meta }`. Handlers never wrap manually.
-- Cursor tokens are base64-encoded JSON of `{ id, sort }`. Any handler that issues a cursor must use the shared encoder.
+Route handlers return a plain object, and the serializer wraps it in `{ data, meta }`.
 ```

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

@@ -25,15 +25,17 @@ Resolve both from the request, and ask only for what is missing. Attach a propos
 
 Pick the subdir from the topic. It sits under `.claude/rules/project/` and names the rule's domain:
 
-- `code/`: code placement, errors, naming, testing.
-- `lang/`: one programming language.
-- `framework/`: one framework.
-- `lib/`: one library or tool.
-- `ui/`: UI copy, accessibility, forms.
-- `claude/`: session conduct and `.claude/` authoring surfaces.
-- `canon/`: the toolkit workflow and its record folders.
-- `tooling/`: dev setup, such as CI workflows, dependencies, and config.
-- `writing/`: prose and document shape.
+| Subdir        | Holds                                                      |
+| ------------- | ---------------------------------------------------------- |
+| `code/`:      | code placement, errors, naming, testing.                   |
+| `lang/`:      | one programming language.                                  |
+| `framework/`: | one framework.                                             |
+| `lib/`:       | one library or tool.                                       |
+| `ui/`:        | UI copy, accessibility, forms.                             |
+| `claude/`:    | session conduct and `.claude/` authoring surfaces.         |
+| `canon/`:     | the toolkit workflow and its record folders.               |
+| `tooling/`:   | dev setup, such as CI workflows, dependencies, and config. |
+| `writing/`:   | prose and document shape.                                  |
 
 ## Step 3: pick a free slug
 

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

@@ -81,9 +81,15 @@ paths:
 - Use imperative voice for every rule (`Prefix booleans with is`, not `Booleans should be prefixed`)
 - State one rule per bullet as a single directive line
 - State what to do and what not to do. Do not explain the reasoning behind a rule.
+
+### Phrasing
+
 - End the directive line of a ban asserting how the model or a tool behaves with one `Revisit when <finding>.` sentence, which states a condition rather than the reasoning. A style, safety, or consistency ban takes none.
 - Phrase a rule as a ban on the forbidden shape when it could otherwise enumerate allowed options, so it stays stable as categories grow
 - Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
+
+### Scope of a rule file
+
 - Keep the file to one topic. A second topic is a second rule file.
 - Do not restate a rule that a sibling rule or `CLAUDE.md` already owns. Point once, never duplicate.
 - Name the current layout only, in a glob and in the body alike. A layout change ships a migration verb, as `canon migrate surface-roots` and `canon migrate records` did, rather than a rule line or a glob that keeps the old spelling loading.

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

@@ -12,11 +12,20 @@ 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 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}/references/skill-disclosure.md`: the rules that bind a skill of any size, being where each reference is named, the contents block, the trigger and guard that stay in the body, and what moves to `references/`
+
+### Writing standards
+
+Read these in the same pass:
+
 - `${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
 
+## Further references
+
+- `${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}/references/skill-practice.md`, when the skill carries engineering practice: the closing sections a practice skill owes and the anatomy behind them
+
 ## Guards
 
 - If `${CLAUDE_SKILL_DIR}/references/skill.md` is not present, stop: `❌ skill.md standard not found. Reinstall the canon plugin.`

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

@@ -0,0 +1,26 @@
+---
+title: Skill disclosure reference
+description: Keeping a skill body and its references under the ceiling, what moves to references and what stays in the body, and how the body names a reference
+---
+
+# Skill disclosure reference
+
+Applies to the size and split of every `SKILL.md` and every file under a skill's `references/`.
+
+## Rules
+
+- Keep `SKILL.md` and each file under `references/` at or under the 300 rendered line ceiling `markdown.md` sets for a whole document. The ceiling binds procedure as much as reference material.
+- Look at a body once it passes 150 lines. That number prompts a look and gates nothing.
+- Move a catalog, a table of cases, or a format spec running past roughly 15 lines to `references/` at any body length.
+- Below the ceiling, name the branch that skips a block before moving it. A block every run dereferences costs a read and saves nothing.
+
+### Moving a step
+
+- Past the ceiling, move a whole step to a reference, preferring a step a named branch skips. Keep the step heading in the body with one line naming the file to read on reaching it, so the body still shows every step in order.
+- Name every file under `references/` in the body at the point a session reads it, since an unnamed reference is never loaded.
+
+### Contents, triggers, and citations
+
+- 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.
+- 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.

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

@@ -43,6 +43,9 @@ A reference shared across skills lives in the `references/` of the skill that ow
 - Cite another skill's reference as `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`. 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.
 - State the path once per body, at the site that reads the reference. A later mention of a reference the body already read stays bare, since repeating the path at every mention is noise rather than instruction.
 - A guard on a reference's presence names the file rather than the folder holding it, since a folder test answers for a sibling that happens to be there.
+
+### Form and ownership
+
 - Use `${CLAUDE_SKILL_DIR}`, never a bare `../../` and never `${CLAUDE_PLUGIN_ROOT}`, since only the first expands before the body reaches the model.
 - Cite a shared procedure, never restate it. A procedure two or more skills execute gets one definition in its owner's reference and a citation in each body.
 - Keep the trigger in the body and the procedure in the reference. The citing skill states when the procedure runs and what it runs against, since that varies per skill and the reference cannot know it.

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

@@ -50,10 +50,16 @@ A reference failing these questions is non-conforming even when it satisfies eve
 - Govern one document type per reference, or one attribute across every document. Split unrelated conventions into separate files.
 - Open with a `## Scope` section stating what the reference governs and what it does not, placed above the shape rules. A reference that specifies shape exhaustively and jurisdiction nowhere cannot refuse a rule, so the rule with no obvious owner lands in whichever reference sits nearest.
 - Write it as one line naming the artifact or attribute and where it applies, then a `Does not govern:` list. Give each entry the excluded concern and the owner it goes to.
+
+#### The path and owners
+
 - Name an owner in the same `references/` folder by bare filename and one in another skill by its sibling path, `../<skill>/references/<name>.md`. Name the surface instead where the owner is one, such as a coding rule, a project policy, or the code.
 - Put the governed path in backticks inside the first sentence of that line, anchored deep enough to resolve from a project root. A bare folder name matches a same-named folder elsewhere in the tree, and a path held back until a later sentence sits beside every other path the statement mentions, including the ones it excludes.
 - Say in that same sentence when the reference governs an attribute rather than a document type. An attribute is written across every document and has no path to name, so the silence reads as an omission unless the sentence claims it.
 - Cut an entry that names no owner at all. It is either excluding something nothing was going to claim, or it is a content exclusion, which the rule below sends to the shape rules instead.
+
+#### Boundaries
+
 - Declare a boundary from both sides. A yield, an exemption, or a handoff stated in one reference alone is never checked against the reference on the other side of it, which is how two files come to claim the same rule or neither does.
 - Separate a jurisdiction exclusion from a content exclusion. The first names a concern another reference owns and belongs in `## Scope`. The second names what does not belong inside the document and stays with the shape rules. Merging them puts a boundary claim where no sibling will read it.
 - Stay silent on a section the reference holds today but should not own. Claiming it makes the scope statement false the moment it moves, and the mismatch is the evidence that moves it.
@@ -125,9 +131,15 @@ Answer all four before editing, and carry the answers into wherever the change i
 - Carry one fenced template of the document the reference governs, so an author copies a shape instead of reconstructing it from prose.
 - Bind this to a reference governing a document type. An attribute reference governs a scan, a string, or a label rather than a file, so it has no document to template and carries none. State that exemption in the sentence declaring it an attribute reference.
 - Place the template below the rules it satisfies, under a `## Template` heading or inside the section holding those rules.
+
+### What the template shows
+
 - Show the skeleton alone: every required section, one placeholder line for what each holds. A full worked document is a second document to maintain.
 - Write placeholders in angle brackets rather than copying a real document. A copied file goes stale, and its backticked filenames read as citations to anything parsing the reference.
 - Switch to a bare word where the fenced language reads `<` as syntax of its own, as Mermaid and HTML do, and say in the line above the fence that the names are placeholders.
+
+### Load-bearing text
+
 - Carry any header, key, or label a consuming tool parses verbatim. The template is the only place an author learns which strings are load-bearing.
 - Treat the template as authoritative where it and the prose disagree. An author copies the block, so a contradiction ships as the block.