@erclx/canon 5.49.0 → 5.51.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.49.0",
+  "version": "5.51.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/auto-ship/references/fan-in.md

@@ -48,12 +48,26 @@ Continue Step 2 with the integrator plan's own `**Files to touch:**`, then the r
 
 ### What the pull request carries
 
-Say in the pull request body that each member is one merge commit and name the members in merge order. Once the pull request merges, delete each member's branch on origin, its worktree, and its local branch:
+Say in the pull request body that each member is one merge commit, and name the members on one line in `## Summary`, backticked, in merge order:
 
-```bash
-git push origin --delete <member branch>
-git worktree remove <member worktree>
-git branch -D <member branch>
+```markdown
+Fan-in members: `feat/a`, `feat/b`, `feat/c`
 ```
 
-Read each member's worktree path off `git worktree list --porcelain` by its branch. The integrator holds the member list, so the deletion is its step rather than a sweep's. No member opens a pull request, so `canon worktrees reclaim` never reads a member's branch as merged and reports a leftover worktree as unmerged work on every run.
+The line names branches rather than plan stems, since the branch is what gets deleted. Nothing outside it is read, so a branch named in prose elsewhere in the body is never a candidate.
+
+### After the merge
+
+The post-merge hook runs `canon worktrees retire-members` for each merged pull request number, and the verb deletes each member's branch on origin, its worktree, and its local branch. No session runs a step.
+
+No member opens a pull request, so neither head-branch deletion nor `canon worktrees reclaim` ever reads one as merged. The member line is what reaches them.
+
+- A member half goes only when its tip is an ancestor of the integrator's merged head, so a commit added after the merge keeps that half
+- A worktree a live session holds, or one with uncommitted work, stays with its local branch
+- A line naming the trunk, the integrator's own branch, or a branch with an open pull request deletes nothing
+
+Run the verb by hand for a merge the hook missed, reading the dry run first:
+
+```bash
+canon worktrees retire-members --pull-request <number> --dry-run
+```

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

@@ -18,13 +18,15 @@ Consult to pick the `canon` verb for a job, and before running a verb that write
 
 ## Project setup
 
-| Job                                          | Verb            |
-| -------------------------------------------- | --------------- |
-| Bootstrap a project with toolkit domains     | `canon init`    |
-| Bring every installed domain current         | `canon sync`    |
-| Reinstall the CLI itself                     | `canon upgrade` |
-| Move a project off a retired name or layout  | `canon migrate` |
-| List the projects the toolkit installed into | `canon targets` |
+| Job                                          | Verb                   |
+| -------------------------------------------- | ---------------------- |
+| Bootstrap a project with toolkit domains     | `canon init`           |
+| Bring every installed domain current         | `canon sync`           |
+| Reinstall the CLI itself                     | `canon upgrade`        |
+| Move a project off a retired name or layout  | `canon migrate`        |
+| Read what a project still needs to migrate   | `canon migrate status` |
+| Read the releases since a target's install   | `canon changelog`      |
+| List the projects the toolkit installed into | `canon targets`        |
 
 ## Domains
 

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

@@ -9,7 +9,7 @@ description: Scope boundary for driving the local design canvas, and the line be
 
 Without this skill, a session asked to draw on the canvas writes frames nothing is serving and reports them drawn. It trusts a passing capture, though a blank shell passes every capture while the operator sees an empty tab. From a linked worktree it writes a copy the canvas never serves, and it captures after every edit.
 
-It reads "this one" from the conversation rather than the operator's selection, or acts on a stale element pick and edits the wrong element. It restyles through a class while the operator's inspector edit sits inline, so the change never shows. A picked frame stays on the canvas as the only record, and the design document never learns it.
+It reads "this one" from the conversation rather than the operator's selection, or acts on a stale element pick and edits the wrong element. It restyles through a class while the operator's inspector edit sits inline, so the change never shows. A picked frame stays on the canvas as the only record, and the project's design record never learns it.
 
 ## Must
 
@@ -17,7 +17,7 @@ It reads "this one" from the conversation rather than the operator's selection,
 - Pages and frames go through the verbs, so the session and the operator's drags share one writer, and a frame from a linked worktree takes the main-root route
 - The operator's selection decides what "this one" means, and a stale element pick reads as unknown
 - A frame's inline styles are read before a restyle, the run names which operator edits it kept and dropped, and capture runs once per finished frame or page
-- A picked value lands in the project's stylesheet and its intent in the design document, while a picked layout stays on the canvas for the plan that builds it
+- A picked frame is handed to `design-record` by page and frame, while a picked layout stays on the canvas for the plan that builds it
 
 ## Must not
 
@@ -31,4 +31,5 @@ It reads "this one" from the conversation rather than the operator's selection,
 - Drafting candidates for a taste decision and taking the pick, which `pick-by-eye` owns
 - What the canvas verbs do internally, which the CLI's own contract owns
 - The content format a frame and a layout take, which the canvas standard owns
-- Tracing reference images into design values, writing the design document from code, and backing up the canvas folder, which no skill owns
+- Landing a pick in the reference folder and carrying its values into the design document, which `design-record` owns
+- Tracing reference images into design values and backing up the canvas folder, which no skill owns

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

@@ -1,6 +1,6 @@
 ---
 name: canvas-board
-description: Drives the local design canvas, where pages hold HTML frames the operator sees, drags, selects, and edits in the browser. Starts the canvas when it is not running, confirms the live shell loads, makes pages and frames, edits a frame through its file, reads what the operator selected or restyled, captures finished frames, and carries a picked direction into the project's design document. Use when asked to "open the canvas", "put this on the canvas", "draw a frame for X", "change the one I selected", "what did I pick", "capture this frame", or "move that frame on the canvas". Do NOT use to draft candidates for a taste decision, which is `pick-by-eye`.
+description: Drives the local design canvas, where pages hold HTML frames the operator sees, drags, selects, and edits in the browser. Starts the canvas when it is not running, confirms the live shell loads, makes pages and frames, edits a frame through its file, reads what the operator selected or restyled, captures finished frames, and hands a picked frame to `design-record`. Use when asked to "open the canvas", "put this on the canvas", "draw a frame for X", "change the one I selected", "what did I pick", "capture this frame", or "move that frame on the canvas". Do NOT use to draft candidates for a taste decision, which is `pick-by-eye`.
 metadata:
   family: decide
 ---
@@ -16,7 +16,7 @@ Every verb below is `canon canvas`. Run `canon canvas --help` for the verbs and
 - If `canon` is not on PATH, stop: `❌ canon CLI not found.`
 - If `canon canvas --help` reports no such command, stop: `❌ The installed canon carries no canvas command. Update the CLI and re-run.`
 - Write no frame before the canvas is serving and the shell has loaded. A frame nobody can see is a draft reported as delivered.
-- Never present a frame as the project's design. The canvas is a drafting surface and the project's design document holds what was decided.
+- Never present a frame as the project's design. The canvas is a drafting surface and the project's design record holds what was decided.
 - Never promise the canvas survives a lost checkout. Its folder is gitignored and nothing backs it up.
 
 ## Step 1: start the canvas and confirm the shell
@@ -122,13 +122,12 @@ Capture once per finished frame or page, not after every edit. The live canvas i
 
 A capture refused because a font is not installed names the family it read off the frame's text. Set that text's `font-family` to a named family the machine has, never a generic keyword such as `sans-serif`, and capture again rather than reporting the frame as captured.
 
-## Step 7: carry a picked direction back
+## Step 7: hand a picked frame on
 
-When the operator picks a frame, the decision leaves the canvas. Leave structure and layout on the canvas, and name the frame in the plan that builds it.
+When the operator picks a frame, the decision leaves the canvas. Hand it to `canon:design-record`, which lands the frame in the project's reference folder and carries its values into the design document. Report it rather than proceeding silently when that skill does not resolve.
 
-- Carry color, type, spacing, and radius into the stylesheet the design document's lead names, and their intent into its sections under the `design.md` standard
-- A project with no stylesheet yet takes the values under `.claude/design/project/` after `canon design install`, and the lead names that path
-- Name the frame the decision came from in the reply, and leave the frame on the canvas until the operator clears it.
+- Name the page and frame the decision came from in the handoff and the reply, and leave the frame on the canvas until the operator clears it
+- Name the frame in the plan that builds a picked layout, since the layout reaches code through that plan
 - Never cite a frame path from a tracked file. The folder is gitignored, so the citation resolves on this machine alone.
 
 ## Output
@@ -138,7 +137,7 @@ When the operator picks a frame, the decision leaves the canvas. Leave structure
 Page:     <page>, <n> frames
 Selected: <page>/<frame>, element <index>, or none, or stale
 Capture:  <path of each capture written>
-Carried:  <the stylesheet and design document the pick went to, the plan that cites the frame, or not yet>
+Handed:   <the frame handed to design-record, the plan that cites it, or not yet>
 ```
 
-Write the canvas line's URL as a markdown link. Omit the capture line when nothing was captured and the carried line when no direction was picked. Emit every path from the project root.
+Write the canvas line's URL as a markdown link. Omit the capture line when nothing was captured and the handed line when no frame was picked. Emit every path from the project root.

package/claude/skills/ci-workflow/REQUIREMENT.md

@@ -9,15 +9,15 @@ description: Scope boundary for pipeline structure against job contents, and the
 
 Without this skill, a session chains jobs with `needs` to express reading order rather than a data dependency, so the pipeline costs the sum of its jobs. The same session splits a one-minute gate into parallel jobs, each repaying checkout, install, and toolchain setup, so the gate gets slower while reporting no earlier.
 
-The rest surface as flakes. An action pinned to a moving ref changes under the project, a cache keyed on a static string serves a stale toolchain after a bump, artifacts upload on every run and never expire, a broad default token grants writes nobody needed, and a workflow with no manual trigger reproduces only by pushing a commit.
+The rest surface as flakes. A moving action ref changes under the project, a static cache key serves a stale toolchain, artifacts never expire, a broad default token grants unneeded writes, and a missing manual trigger leaves a run reproducible only by pushing a commit. A Linux-only pin also flags a supported macOS job as a departure.
 
 ## Must
 
 - A job is gated only on a data dependency or a cost that justifies the wait, and checks sharing setup stay in one job until a run log puts the gate past roughly two minutes
 - Every action is pinned to a tag that cannot cross a major version, and every cache is keyed on the version of what it caches
 - Every workflow carries a manual trigger beside its primary one, except one that commits back
-- The token defaults to read-only, with a write scope granted only on the job that needs it
-- Artifact upload is bounded to failures and expires
+- The token defaults to read-only, with a write scope granted only on the job that needs it, and artifact upload is bounded to failures and expires
+- A job runs on Linux unless the project states a platform for a layer that differs by platform
 
 ## Must not
 

package/claude/skills/ci-workflow/SKILL.md

@@ -20,7 +20,17 @@ Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job ex
 - Include `workflow_dispatch` alongside the primary trigger, except on a commit-back workflow, where a manual run has no branch to commit onto and would pass while doing nothing.
 - Set `permissions: contents: read` at the top level, and grant a write scope only on the job that needs it.
 - Pin all actions to major version tags (`@v4`, never `@latest` or `@main`).
-- Use `runs-on: ubuntu-latest` for all jobs.
+- Use `runs-on: ubuntu-latest` for every job, except one the runner platform rules below move to another platform.
+
+## Runner platform
+
+Linux stays the default. A job leaves it only for a layer whose result differs by platform, and only on a platform the project states.
+
+- Read the stated platforms from the project's requirements record or README. A platform stated in neither keeps every job on Linux.
+- Keep lint, build, and browser jobs on Linux, since their result does not differ by platform. Name the layers that may leave it and never the steps they run.
+- Name another runner by its `-latest` label, such as `macos-latest`, matching the `ubuntu-latest` convention above.
+- Resolve a macOS `$TMPDIR` or `mktemp` path with `realpath` before comparing it with a tool's output, since the `/var` to `/private/var` symlink hides the target. Treat `$RUNNER_TEMP` alike.
+- Expect a macOS job to cost more per minute than a Linux one. GitHub bills the two differently, so read the rate from its billing page rather than quoting a multiplier.
 
 ## Job naming
 
@@ -59,6 +69,14 @@ A workflow that pushes a regenerated file onto the pull request branch takes the
 - Set `HUSKY: 0` on the commit step when the runner lacks a tool a hook shells out to.
 - Fail a template's first step while a path list still holds its placeholder, so an unfinished install fails loudly rather than never firing.
 
+## Steps
+
+- Keep an inline `run:` step to five lines and one guard that exits or writes an output. Move other branching, a loop, trap, or function to a script, which runs on a laptop and under shellcheck.
+- Put the script at `scripts/<name>.sh`, or a `.ts` file for a Bun project, and call it after `actions/checkout`, since the runner holds no copy before that.
+- Pass inputs as arguments or `env`, never spliced into the script text, so a branch name with a quote or `$(...)` in it cannot run.
+- Keep `permissions` and secrets on the workflow step, with the script reading its token from `env`.
+- Open the script with `set -e` at least, since the runner gives a `run:` step `bash -e` and a script called directly gets no flags.
+
 ## Template
 
 Load `${CLAUDE_SKILL_DIR}/references/workflows.md` for the base workflow template. Adapt it to the project's stack, test commands, and build output. Add or remove jobs as needed. The template already carries the folded shape, and the split beside it applies once the granularity rule above calls for it.
@@ -79,5 +97,12 @@ Before responding, also verify:
 
 - Artifacts upload on `if: failure()` only with `retention-days: 7`.
 - Job names use emoji + title format.
+- Every job runs on `ubuntu-latest`, except one that targets a platform the project states and runs a layer that differs by platform.
 - Deploy, publish, and release jobs carry a placeholder step and a named handoff, never a guessed deploy command.
 - Bun projects use `oven-sh/setup-bun@v2` with `bun install --frozen-lockfile`.
+
+### Steps
+
+Before responding, also verify:
+
+- No `run:` step passes five lines or carries more than one exit-or-output guard, a loop, a trap, or a function. A step that does calls a script, with its inputs as arguments or `env`.

package/claude/skills/ci-workflow/references/workflows.md

@@ -1,5 +1,13 @@
 # CI workflow template
 
+## Contents
+
+- [Base template](#base-template)
+- [Splitting the check job](#splitting-the-check-job)
+- [Targeting another platform](#targeting-another-platform)
+
+## Base template
+
 Copy this base template and adapt it to the project's stack, test commands, and build output. It carries the shape a new pipeline starts in, with the checks that share setup in one job, per the granularity rule in the skill body. `e2e` and anything gated on it stay separate jobs at either size.
 
 ```yaml
@@ -99,3 +107,23 @@ jobs:
           name: build-output
           path: dist/
 ```
+
+## Targeting another platform
+
+Add this job beside the Linux ones only when the project states macOS as a supported platform, per the runner platform rules in the skill body. It runs the unit layer, since that layer differs by platform, and the rest stay on `ubuntu-latest`.
+
+```yaml
+jobs:
+  unit-macos:
+    name: '🧪 Unit Tests (macOS)'
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - name: Resolve the temp folder
+        run: echo "TMPDIR=$(realpath "$RUNNER_TEMP")" >> "$GITHUB_ENV"
+      - run: bun run test
+```

package/claude/skills/context-fold/references/context.md

@@ -88,9 +88,10 @@ Entries get read top-down and often partially, so the boundary sits above the fo
 
 ## The development entry
 
-Only the `development` entry carries this section, as an H3 under `## Layout`. It is not a general-purpose heading for other domains.
+Only the development entry carries this section, as an H3 under `## Layout`. That entry is the flat `development` entry or any entry directly under a `development/` folder, and the heading is not a general-purpose one 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`: run commands as tables of command plus purpose. The single discoverable surface for how to run the project. Keep run commands here, not scattered across `CLAUDE.md`.
+- Group a long set of commands into short tables, each under a lead sentence naming its group, since a table past 8 body rows breaks the table limits. This H3 alone may carry several lead paragraphs.
 
 ## What goes in
 
@@ -157,7 +158,7 @@ A domain outgrowing the ceiling splits into a folder, and small domains of one k
 - Name an entry inside either folder per the `codebase-layout` skill, which never repeats the folder's name as the entry's stem or prefix
 - Keep a split domain's `index.md` generated, since regen rewrites its body. The domain's own overview and layout go in a sibling file, which the `subtitle` names.
 
-Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and conflicts with any sibling branch.
+Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and conflicts with any sibling branch. The development entry's `### Scripts` is the one exception, kept small by grouping.
 
 ## Examples
 

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

@@ -0,0 +1,33 @@
+---
+name: design-record
+description: What keeping the design record is for, the gaps it closes, and where it stops against the skills that pick and judge a design
+---
+
+# Design record requirement
+
+## Gap
+
+Without this skill, no surface sets up the design reference folder or keeps it. A pick reaches the folder only when the operator remembers the sync, or a session copies frames in by hand and they drift. A reference outlives the surface it showed, since nothing removes it.
+
+Each project invents its own grouping, and its index restates the file tree rather than naming the code a group governs. A picked color reaches the stylesheet with no intent written down, or lands as a hand-typed value in the design document.
+
+## Must
+
+- The folder takes the groups, file names, support folder, and index row form the folder standard fixes, and a project without one gets it set up rather than refused
+- A pick lands through the design sync after its index row, and a project with no sync is told before any write and still gets the design document half
+- A redraw keeps the index row and leaves the files to the sync, and a retired surface takes its files and row out in the change that removes it
+- The run looks at each landed picture in both themes before reporting it landed
+- A picked value lands in the stylesheet and its intent in the design document under the design document standard, and a generated record changes through its module alone
+
+## Must not
+
+- Write, copy, or delete a reference file by hand, or capture frames in place of a missing sync
+- Land a candidate the operator has not picked
+- Restate when a pick lands against the build, which the design-reference rule states
+- Be reached only by the author typing its name, since a pick from the picking or canvas skill should hand off to it
+
+## Out of scope
+
+- Drafting candidates and taking the pick, which `pick-by-eye` owns
+- Drawing, selecting, and capturing frames on the canvas, which `canvas-board` owns
+- Judging whether a design is good, which `design-taste` owns

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

@@ -0,0 +1,84 @@
+---
+name: design-record
+description: Keeps the project's design record, being the design document at `canon/DESIGN.md` and the reference folder at `canon/design/` holding the accepted frames a build matches. Sets the folder up, lands a picked design through the project's design sync, keeps the index, redraws or retires a reference when its surface changes, and carries a pick's values into the stylesheet and its intent into the design document. Use whenever a picked frame or design moves into `canon/design/` or `canon/DESIGN.md`, before running the project's design sync or editing the index, including when asked to "land it in the design references", "add a design reference", "land this pick", "set up canon/design", "update the design index", "redraw the reference for X", "remove the reference for X", or "update DESIGN.md". Do NOT use to draft candidates or take a pick, which is `pick-by-eye`, to draw frames on the canvas, which is `canvas-board`, or to judge a design, which is `design-taste`.
+metadata:
+  family: ship
+---
+
+# Design record
+
+Keep the record of what the project's design is. The record has two halves, each with its own standard to read before writing it.
+
+| Half             | Path              | Standard                                   |
+| ---------------- | ----------------- | ------------------------------------------ |
+| Design document  | `canon/DESIGN.md` | `${CLAUDE_SKILL_DIR}/references/design.md` |
+| Reference folder | `canon/design/`   | `${CLAUDE_SKILL_DIR}/references/folder.md` |
+
+The document holds the rules and each role's intent, and the folder holds the pictures a build matches.
+
+## Guards
+
+- Write no reference file by hand, whether a copy, an edit, or a delete. The project's design sync writes the frames, so a hand-written file drifts from the frame it claims to show.
+- Never land a candidate the operator has not picked. The folder holds accepted designs, and a draft lives on the canvas.
+
+## Step 1: read the record
+
+Read `canon/design/index.md` from the project root, and list the group folders beside it.
+
+- A missing folder or index is set up at Step 3, once Step 2 has found the sync
+- An index carrying a file list or a canvas mapping is an older shape. Leave its rows in place, add new rows in the form `folder.md` gives, and say the index predates the standard.
+
+## Step 2: find the project's design sync
+
+Find the sync before writing anything, since every folder step runs through it. Read the project's scripts, such as the `scripts` block of `package.json`, for the command that writes frames into `canon/design/`. Run its `--help` when it offers one, for its mapping file and its check.
+
+When no sync resolves, skip Steps 3 to 5 and capture no frame in the sync's place. Report `⚠ No design sync found, so the pick did not land in canon/design/. Add one or name the command, then re-run.` and go on to Step 6, which needs no sync.
+
+## Step 3: set up the folder
+
+Skip this step when `canon/design/index.md` exists, even as a stub, since a stub the project's stack seeded is the setup.
+
+1. Write `canon/design/index.md` from the template in `folder.md`, with one row per group the first pick needs.
+2. Leave the group folders to the sync, since git tracks no empty folder and the sync creates each one as it writes.
+
+## Step 4: land a pick
+
+When the pick lands relative to the build is the design-reference rule's call, so follow it rather than choosing here.
+
+1. Name the group the surface belongs to, by where a user meets it in the app, per `folder.md`.
+2. Add or update the group's index row before running the sync, naming the code paths the surface governs and the states its frames show.
+3. Add the surface to the sync's mapping file, in the form the sync's own help gives.
+4. Run the sync, then its check, and report a missing or stray file the check names.
+5. Open each written PNG, light and dark, before reporting it landed, since a frame captured blank or in one theme passes the sync.
+
+## Step 5: redraw or retire a reference
+
+A redraw follows an intentional design change and nothing else. Keep the index row, change the sync's mapping only where the frame moved on the canvas, and run the sync so it rewrites the files.
+
+Retire a reference in the change that removes its surface from the app.
+
+- Drop the surface from the sync's mapping and run the sync, so the sync removes its files
+- Remove the group's index row when the group holds nothing else
+- When the sync leaves the files and its check reports them stray, name each path and ask the operator, since no session deletes a reference by hand
+
+## Step 6: carry a pick into the design document
+
+A pick that settles color, type, spacing, or radius changes the design document as well as the folder. Skip this step when the pick changed layout or structure alone, since the reference carries that.
+
+- Carry each value into the stylesheet the document's lead names, and its intent into the document's sections under `design.md`
+- A project with no stylesheet yet takes the values under `.claude/design/project/` after `canon design install`, and the lead names that path
+- A values record names in its lead the module it renders from and the command that renders it. Edit that module and run that command, never the document.
+
+Never cite a canvas frame path from the document or the index. The canvas folder is gitignored, so the citation resolves on one machine alone.
+
+## Output
+
+```plaintext
+✅ Design record: <landed, redrawn, retired, set up, or carried>
+Group:  <group>, <name>
+Files:  <each file the sync wrote or removed>
+Index:  <the row added, changed, or removed, or unchanged>
+Design: <the stylesheet and design document the values went to, or unchanged>
+```
+
+Emit every path from the project root. Omit the files line when nothing was written.

package/claude/skills/design-record/references/folder.md

@@ -0,0 +1,69 @@
+---
+title: Design reference folder
+description: Shape and content rules for canon/design, the tracked folder of accepted design frames a build matches
+---
+
+# Design reference folder
+
+Applies to `canon/design/`. Each file is an accepted design a build matches, kept as a picture for a reader and as frame HTML for exact values. The folder holds what was picked, never a draft.
+
+## Scope
+
+Governs the folder's groups, the file names inside them, the support folder, and the index at `canon/design/index.md`.
+
+Does not govern:
+
+- The design document at `canon/DESIGN.md`, which `design.md` beside this file governs
+- When a pick lands and how a build is held to a reference, which the design-reference governance rule states
+- The canvas content format a frame is drawn in, which the canvas standard owns
+
+## What a working folder looks like
+
+A folder works when a builder opening it finds the reference for the surface they are changing without asking anyone:
+
+- Does the group a surface sits in match where a user meets it in the app?
+- Does each reference carry both themes, as a picture and as frame HTML?
+- Does the index say which code each group governs?
+
+## Groups
+
+Group by app part, being the places a user sees, such as `home`, `inspector`, or `menus`. A component folder splits one screen across many folders, and a concern folder mixes surfaces a builder edits apart.
+
+- Give each app part one plain kebab-case folder directly under `canon/design/`
+- Put the inputs every app part draws on, such as tokens, colors, and the logo, under `foundations/`, so they read apart from places in the app
+- Gather a surface shown on several app parts, such as a toast, under the part a user meets it in first
+
+## Files
+
+Each reference is one name in two themes, with a PNG and its frame HTML per theme.
+
+- Name each file `<name>-dark` or `<name>-light`, as in `grid-dark.png` beside `grid-dark.html`
+- Keep one HTML file without a theme suffix only for a frame that switches theme itself, beside both PNGs
+- Put what every frame HTML loads, being its stylesheet, script, fonts, and vendored files, under `kit/`
+
+## The index
+
+`canon/design/index.md` is prose for a reader. It names the link a file listing lacks, from a group to the code it governs.
+
+- Write one row per group, carrying the group, what the user sees there, the code paths it governs, and the states its frames show
+- List no files, since the tree and the sync's own check already answer what exists
+- Keep the sync's canvas mapping out of the index, in a file the sync owns beside it
+
+### Template
+
+The column headers stay verbatim. A row per group, `foundations` included.
+
+```markdown
+# Design references
+
+Each group holds accepted frames a build matches, light and dark.
+
+| Group         | What the user sees | Code               | States           |
+| ------------- | ------------------ | ------------------ | ---------------- |
+| `home`        | <the surface>      | `<path in source>` | <states shown>   |
+| `foundations` | Tokens and colors  | `<stylesheet>`     | <themes covered> |
+```
+
+## Lifetime
+
+The design-reference governance rule states how long a reference stays, when it is redrawn, and when it goes with its surface.

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

@@ -154,9 +154,10 @@ Run `${CLAUDE_SKILL_DIR}/references/preflight.md` against the output. It is the
 
 ### Other skills
 
-Four neighbors own the rest.
+Five neighbors own the rest.
 
 - The candidate loop, the arm set, the render, and the pick: `pick-by-eye`
-- The shape of the project's design document and where its values live: `${CLAUDE_SKILL_DIR}/../canvas-board/references/design.md`
+- The shape of the project's design document and where its values live: `${CLAUDE_SKILL_DIR}/../design-record/references/design.md`
+- The folder holding the accepted designs and how a reference lands in it: `${CLAUDE_SKILL_DIR}/../design-record/references/folder.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/git-followup/SKILL.md

@@ -59,6 +59,7 @@ A missing tracking ref is not a guard, since an open pull request proves the bra
    - A fix commit answering a review changes what shipped exactly as much as an ordinary followup does, so the sync cannot wait on the invocation or the comment count below.
    - A body a person edited by hand between rounds gets no special handling: judge it against the tree the same way regardless of who wrote it last, since a hand-edit the fix commit has made stale is the exact drift this sync exists to close.
    - Carry a `UI pass` line marked `<!-- pr-ui-pass -->` into any rewritten body unchanged, since `canon pr tick` owns it and a dropped marker defeats the reset on a new head.
+   - Carry a `Fan-in members:` line into any rewritten body unchanged, since the post-merge hook reads it to delete the members and a dropped line deletes nothing and says nothing.
 8. Route on the invocation and the comment count for the reply alone.
    - When invoked with `reply-owned`, skip this step: the caller posts its own reply.
    - Otherwise, if the count is above zero, the followup addresses review feedback: write a one-line summary of the fix to `.canon/tmp/pr/followup/summary-<number>.md` in its own call, run `canon labels scan --body-file .canon/tmp/pr/followup/summary-<number>.md` against it, which applies the rule in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md`, then post it with `gh api -X POST repos/{owner}/{repo}/issues/<number>/comments -F body=@.canon/tmp/pr/followup/summary-<number>.md --silent`. A hook on `Bash` runs the same scan on that body file and denies the post on a hit, and it refuses an inline `-f body=` value, so the body goes through a file. The `pull_request` check the git-pr surface carries triggers on a push or an open rather than a plain edit, so neither this comment nor the title and body step 7 synced reaches it.

package/claude/skills/git-pr/references/pr.md

@@ -66,7 +66,7 @@ Past 5 bullets, group Key changes under bold labels, 5 bullets a group at most.
 
 ### Closing lines
 
-The closing lines end `## Summary`, one `Closes #NNN` per issue and no trailing period. A task shipped in slices carries them on its last slice only. `closing-issues.md` states how the list is decided, and `canon labels scan --closes` fails a body that disagrees with it.
+The closing lines end `## Summary`, one `Closes #NNN` per issue and no trailing period, and a sliced task carries them on its last slice. `closing-issues.md` decides the list. A fan-in member line sits above them, per `${CLAUDE_SKILL_DIR}/../auto-ship/references/fan-in.md`.
 
 ### Context section
 

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

@@ -14,6 +14,7 @@ The rules also have three carriers, a standard, a generated rule pointing at it,
 ## Must
 
 - Hold the format and structure reference in `references/markdown.md`, the one copy, read by sibling path from every skill that writes markdown
+- Hold the table limits in `references/tables.md`, the one copy, since `markdown.md` sits at the document ceiling and points at it
 - Send the session to `canon markdown audit` after an edit, since the audit reads the bans from the package and a restated list would drift
 - Route voice to `write-human` and a Mermaid fence to `draw-figure` rather than restating either
 

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

@@ -7,10 +7,15 @@ metadata:
 
 # Markdown craft
 
-Read `${CLAUDE_SKILL_DIR}/references/markdown.md` before a substantial markdown edit. Every rule in it is a fact a scan can settle, so do not work the banned characters from memory.
+Read the references below before a substantial markdown edit. Every rule in them is a fact a scan can settle, so do not work the banned characters from memory.
+
+- `${CLAUDE_SKILL_DIR}/references/markdown.md`: headings, density, code spans, punctuation, and every other format rule
+- `${CLAUDE_SKILL_DIR}/references/tables.md`: the four table limits and their fixes, read before writing a table or fixing a table finding
 
 Run `canon markdown audit <path>` after the edit, and fix every ban and density finding it reports before moving on. Rewrite the sentence carrying a ban hit rather than swapping the token for a near-synonym, and fix a density finding by its shape rather than trimming characters.
 
+A table finding reports without failing the run. Fix it the way `tables.md` gives for its limit.
+
 ## Routes
 
 - Voice, rhythm, sentence construction, and information density: load `write-human`.

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

@@ -63,7 +63,7 @@ Two kinds of block are exempt from the 40-line checkpoint, since a subheading dr
 - A block whose lines are all list items at one level averaging under roughly 130 characters, since a flat list of short peers is already navigable
 - Weight decides rather than count, since a catalog of one-liners and a stack of paragraphs reach one count and read nothing alike. The cap on a bullet run is a separate rule.
 - Mixing prose into that list, or nesting levels in it, ends the exemption at any weight
-- A block whose lines are all table rows, at any length, since a subheading inside one splits the table rather than the run
+- A block of table rows, since a heading splits the table rather than the run
 - Prose either side of the table ends that exemption, since the block has a seam and a heading breaks it there
 
 ### Bold section markers
@@ -77,7 +77,7 @@ A bold section marker holding its line alone breaks a run the way a heading does
 
 ## Density
 
-Six limits keep a file scannable on sight, each a fact `canon markdown audit` measures that fails the push wherever the surface's gate is on. Open an H3 with a lead sentence or a table, then a few bullets or a short paragraph, since monotone text is the defect whether all prose or all bullets.
+Six limits keep a file scannable on sight, each a fact `canon markdown audit` measures that fails the push where the surface's gate is on. A table takes four more, in `tables.md` beside this file. Open an H3 with a lead sentence or a table, then a few bullets or a short paragraph, since monotone text is the defect whether all prose or all bullets.
 
 | Rule                | Limit                                             |
 | ------------------- | ------------------------------------------------- |
@@ -88,7 +88,7 @@ Six limits keep a file scannable on sight, each a fact `canon markdown audit` me
 | Heading depth       | H3 at most, no H4                                 |
 | H3 opening          | First block under an H3 is a paragraph or a table |
 
-Rules, `CLAUDE.md`, a requirements or design record, a changelog, examples, and `.canon/` records take no density finding, since a rule is one imperative per bullet and each record keeps its own shape.
+Rules, a requirements or design record, a changelog, examples, and `.canon/` records take no density finding, since each keeps its own shape. `CLAUDE.md` takes the run limit and the H3 opening inside `## Key paths` alone.
 
 ### How each limit counts
 

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

@@ -0,0 +1,30 @@
+---
+title: Table limits
+description: The four limits a markdown table takes, being cell length, row count, a list after a table, and a wide code token, with the fix each one takes
+---
+
+# Table limits
+
+None of the density limits in `markdown.md` reads inside a table, so content too long for a bullet tends to move into a cell. Four table limits close that gap. `canon markdown audit` measures them on the paths density covers, outside fences, and reports each one without failing a push for now.
+
+## Limits
+
+Each limit is a count or a shape a scan settles, read the way a renderer draws the table. An escaped pipe stays inside its cell, and pipe lines with no delimiter row are not a table.
+
+| Rule             | Limit                                                 |
+| ---------------- | ----------------------------------------------------- |
+| Cell length      | 120 visible characters, counting a link by its label  |
+| Rows             | 8 body rows, not counting the header                  |
+| List after table | A list is never the next block after a table          |
+| Wide token       | No code span in a cell holds a run past 30 characters |
+
+A paragraph or a heading between a table and a list clears the third limit, and a blank line alone does not.
+
+## Fixes
+
+Each limit has its own fix, and none of them is trimming characters until the count passes.
+
+- Move a long cell's overflow into a bullet under the table's lead sentence, or under a lead of its own
+- Split a long table into groups, each under a lead sentence naming its group, since a heading inside a table splits it and H4 is banned
+- Give a list that follows a table a lead sentence of its own
+- Move a wide token out of the table into a bullet, since a preview either widens its column or splits it at a hyphen or a slash