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

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/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
+
+Keep a reference while its surface exists. Redraw it only on an intentional design change, and remove its folder or files and its index row in the change that removes the surface.

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

@@ -157,6 +157,6 @@ Run `${CLAUDE_SKILL_DIR}/references/preflight.md` against the output. It is the
 Four 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`
 - 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/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

package/claude/skills/pick-by-eye/SKILL.md

@@ -124,15 +124,16 @@ Read `canon canvas selection --json` when the answer points at the canvas, such
 
 1. Apply the winning arm to the real surface, in one change.
 2. Close out any document stating the decision as open, in the same change, naming the winner and the arms that stayed defensible. Skip this where nothing stated the decision.
-3. Capture the picked round's frames with `canon canvas capture <page> --out <archive-dir> --json`. Each lands as `arm-<id>.png`, keeping the losing arms as a revert record.
-4. Resolve `<archive-dir>` as `.canon/picks/<slug>/` against the main worktree root, since shared session scratch resolves there rather than in a linked worktree.
-5. Delete every page folder on the run's list from under the `content` folder `canon canvas list --json` reports. Touch no page the run did not add, whatever its name.
-6. Stop the canvas server if this run started it, and leave one the operator started running.
-7. Leave the renders in a live track's `evidence/<slug>/renders/`, since `plan-groundwork` treats evidence as durable.
-8. Report each page whose delete is refused, naming the path for the operator to remove. The pick is applied either way.
-9. Report every surface that changed, each on its own line, name the winning arm by its id and its cost, and report the archive path.
+3. Hand the winning frame to `canon:design-record` by its page and frame, which lands it in the project's design record. Report it rather than proceeding silently when that skill does not resolve.
+4. Capture the picked round's frames with `canon canvas capture <page> --out <archive-dir> --json`. Each lands as `arm-<id>.png`, keeping the losing arms as a revert record.
+5. Resolve `<archive-dir>` as `.canon/picks/<slug>/` against the main worktree root, since shared session scratch resolves there rather than in a linked worktree.
+6. Delete every page folder on the run's list from under the `content` folder `canon canvas list --json` reports. Touch no page the run did not add, whatever its name.
+7. Stop the canvas server if this run started it, and leave one the operator started running.
+8. Leave the renders in a live track's `evidence/<slug>/renders/`, since `plan-groundwork` treats evidence as durable.
+9. Report each page whose delete is refused, naming the path for the operator to remove. The pick is applied either way.
+10. Report every surface that changed, each on its own line, name the winning arm by its id and its cost, and report the archive path.
 
-The picked round is the final one unless Step 4 resolved a revert. Archiving any other page lets item 5 delete the winning arm with nothing kept, and a variant left on the canvas is a second design nobody maintains.
+The picked round is the final one unless Step 4 resolved a revert. Archiving any other page lets item 6 delete the winning arm with nothing kept, and a variant left on the canvas is a second design nobody maintains.
 
 ## Reading a measurement
 
@@ -149,6 +150,7 @@ A capture proves appearance and a measurement proves a relationship, so reach fo
 Cite these rather than restating them. A step reimplemented here rots against the skill that owns it.
 
 - `plan-feature` plans the work once the pick is made, and declares the pull request boundary that plan carries
+- `design-record` lands the winning frame in the reference folder and its values in the design document, and runs before item 6 deletes the page its sync reads
 - `design-taste` carries the layer catalog, the ordering, grey-boxing, and the defaults an arm should reach past
 - `write-human` carries the voice for any copy an arm puts in front of a reader
 

package/claude/skills/plan-feature/SKILL.md

@@ -152,9 +152,21 @@ Then output in chat:
 1. <question>
    - Suggested: <pick>, <reason or tradeoff>
 
-Next: /session-worktree
+Next: <line from the table below>
 ```
 
+Pick the `Next:` line from the roster check `${CLAUDE_SKILL_DIR}/../task-board/SKILL.md` states under `### Check for a live orchestrator`, read there rather than restated here.
+
+| Roster read                                                                | `Next:` line                                                                                         |
+| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| **Found**                                                                  | `<name> places and dispatches <task>`, naming the orchestrator row the check matched                 |
+| **Not found**, and this session's name starts with `worker-` or `planner-` | `Hand <task> to a worker`, naming no session, since none is live and the operator dispatches by hand |
+| **Not found otherwise**, or the read fails                                 | `/session-worktree`                                                                                  |
+
+- With a live orchestrator and no planner role held, send the plan path to it through `canon:session-relay`, resolved from its `sessionId`
+- A session holding `canon:role-planner` already owes that announcement through its own channel, so it sends none
+- Say which row fired in one clause, since a line with no stated reason is one the next reader re-derives.
+
 Show only the path line and the `Next:` line when there are no questions. The `.canon/plans/` directory is gitignored, so do not stage or commit the file.
 
 Do not proceed to implementation until the user explicitly says to continue.

package/claude/skills/session-worktree/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: session-worktree
-description: Enters a Claude Code worktree at `.claude/worktrees/<name>/` with a name derived from the active plan or branch. Use when asked to "enter a worktree", "start a worktree", "work in a worktree", or at the plan-to-execute boundary after `/plan-feature`. Also use when an `Edit` or `Write` to a main-root file such as a plan, a task, or a review report was refused for session isolation. Do NOT use to list, clean up, or rotate worktrees (use `git-worktree`).
+description: Enters a Claude Code worktree at `.claude/worktrees/<name>/` with a name derived from the active plan or branch. Use when asked to "enter a worktree", "start a worktree", "work in a worktree", or before building an approved plan in this session. Also use when an `Edit` or `Write` to a main-root file such as a plan, a task, or a review report was refused for session isolation. Do NOT use to list, clean up, or rotate worktrees (use `git-worktree`).
 metadata:
   family: build
 ---

package/docs/agents/index.md

@@ -12,7 +12,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Context audit](context-audit.md): Running the context audit, its folder scope, the exit codes, every check with the folders it reaches and whether it gates, the seed gate, and the citation exclusions
 - [Indexes](indexes.md): How canon indexes regen and canon indexes list resolve paths, what they stage, and the record and exit codes each emits
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, the drift report and its seven side sections, the rule detection record, and version skew states
-- [Markdown audit](markdown-audit.md): Running the markdown audit over any path, each finding it reports with whether it gates, the six density limits, the advisory measures, the exit codes, and where the audit runs
+- [Markdown audit](markdown-audit.md): Running the markdown audit over any path, each finding with whether it gates, the density and table limits, the advisory measures, the exit codes, and where the audit runs
 - [Migrate](migrate.md): What each canon migrate verb moves, the markers that keep an old spelling, and what each one refuses
 - [Output shape](output-shape.md): The framed output shape every command renders into, the JSON and color modes, the exit discipline, the runtime catalogs, and a headless invocation per domain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and how canon docs resolves a topic name

package/docs/agents/markdown-audit.md

@@ -1,6 +1,6 @@
 ---
 title: Markdown audit
-description: Running the markdown audit over any path, each finding it reports with whether it gates, the six density limits, the advisory measures, the exit codes, and where the audit runs
+description: Running the markdown audit over any path, each finding with whether it gates, the density and table limits, the advisory measures, the exit codes, and where the audit runs
 kind: reference
 ---
 
@@ -28,11 +28,14 @@ The ban set and checkpoints ship in `src/markdown/bans.ts` and `src/markdown/str
 | Links           | A relative link resolving to nothing on disk                                         | Always            |
 | Density         | The six limits below, under `density`                                                | On a gated prefix |
 | Reference shape | A `kind: reference` page breaking its shape, under `referenceShape`                  | On a gated prefix |
+| Tables          | The four table limits below, under `tables`                                          | Never             |
 | Colons          | A colon followed by more text in a prose line, under `colons`                        | Never             |
 | Heading case    | A capital after the first word of a heading or `title`, under `headingCase`          | Never             |
 
 A page marked `kind: reference` holds its opening, then `Output`, `Refusals`, and `See also` as H2s, each at most once and in that order. It takes no H3 and no table headed `Flag` or `Option`. An unmarked page is never measured.
 
+Tables take the four limits in the `markdown-craft` skill's `tables.md`, on the density paths but never `CLAUDE.md`. A cell past 120 visible characters reports as `table-cell`, more than 8 body rows as `table-rows`, a list after a table as `table-then-list`, and a code span with a run past 30 characters as `table-token`. None sets the exit code.
+
 | Density limit       | Finding                                                    |
 | ------------------- | ---------------------------------------------------------- |
 | Paragraph length    | A prose paragraph past 350 characters                      |
@@ -45,7 +48,7 @@ A page marked `kind: reference` holds its opening, then `Output`, `Refusals`, an
 - A paragraph under a list item counts toward that bullet, never as a paragraph
 - A table, fence, list, heading, or bold section marker ends a run of paragraphs
 - A run whose every item opens with a bold label or a link is exempt, and numbered items never count
-- Only context entries, docs, skill bodies, references, and requirements, tooling seeds and stack references, the wiki, `README.md`, and `CONTRIBUTING.md` take a finding
+- Only context entries, docs, skills, tooling seeds and references, the wiki, `README.md`, and `CONTRIBUTING.md` take a finding, plus the Key paths of `CLAUDE.md` on the run and H3 limits
 - A requirement gates only once the gated list below names its own file, never through its skill's prefix and never on a bullet run alone
 
 | Root              | A density or reference shape finding gates                                                                 |

package/docs/target/migrations.md

@@ -180,3 +180,10 @@ A project holding `.claude/rules/canon/ui/a11y.md` adds the new rule alone:
 ```bash
 canon gov install --add keyboard --yes .
 ```
+
+## Group a long paths section in `CLAUDE.md`, once
+
+The `## Key paths` section of `CLAUDE.md` now keeps to 5 bullets in a row, and every other section stays exempt. `canon claude sync` never rewrites a `CLAUDE.md` you hold, so it warns with the line of each longer run.
+
+- Regroup the section by hand under H3s, each opening on a one-sentence lead.
+- List `CLAUDE.md` in `canon/config/markdown.toml` to gate it from then on.

package/docs/target/projects.md

@@ -49,7 +49,7 @@ The chain runs these phases:
 
 An existing project goes to `canon:target-check` first. For the Claude layer alone, run `canon claude init` and then `canon:target-setup indexes`. Run `canon:target-setup verify deep` by hand for the heavier smoke and screenshot pass.
 
-Keep the `## Scripts` table in `canon/context/development/local-loop.md` current as scripts are added. A split entry keeps it in `overview.md`. <!-- audit-ignore-citations: canon/context/development/local-loop.md -->
+Keep the `## Scripts` table in `canon/context/development/local-loop.md` current as scripts are added. A split entry keeps it in any entry directly under `development/`, grouping a long set into short tables under lead sentences. <!-- audit-ignore-citations: canon/context/development/local-loop.md -->
 
 ### From scaffold to first feature
 

package/docs/workflow/skill-map.md

@@ -35,7 +35,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 
 | Skill                         | When to use                                        |
 | ----------------------------- | -------------------------------------------------- |
-| `canon:session-worktree`      | At plan-to-execute, for an isolated tree           |
+| `canon:session-worktree`      | Before building a plan in this session             |
 | `canon:auto-ship`             | After plan approval, to chain implement through PR |
 | `canon:test-first`            | Before implementing a planned change               |
 | `canon:test-craft`            | Writing or changing a test                         |
@@ -64,6 +64,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | --------------------- | --------------------------------------------- |
 | `canon:git-ship`      | To run the post-feature chain through open PR |
 | `canon:context-fold`  | The diff left a context entry untrue          |
+| `canon:design-record` | A picked design needs landing in the record   |
 | `canon:task-complete` | After the fold, to mark shipped outcomes      |
 | `canon:docs-sync`     | A change left `README.md` or `docs/` stale    |
 | `canon:git-stage`     | Staged changes span several concerns          |

package/docs/workflow/visual-design-workflow.md

@@ -20,7 +20,8 @@ These skills cover the tier:
 
 - `canon:ui-checklist`, `canon:ux-audit`, and `canon:ux-measure` review and measure a UI
 - `canon:pick-by-eye` drafts candidates as frames on the canvas and takes your pick
-- `canon:canvas-board` works a direction out as HTML frames you edit in the browser. Only the pick moves into `canon/DESIGN.md`.
+- `canon:canvas-board` works a direction out as HTML frames you edit in the browser, and hands the pick on
+- `canon:design-record` lands a pick in `canon/design/` and carries its values into `canon/DESIGN.md`
 - `canon:design-identity` drafts a logo mark and social card
 
 Pick tier 0 when the UI is not the core product, decisions fit in sentences, and stakeholders review code.

package/governance/ledger/ui/design-reference.md

@@ -12,6 +12,7 @@ The rule states canon's own design handoff, generalized from Frameboard's projec
 | Bullet                         | Source                                                                                                                                                              | Read       |
 | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
 | Build against the tracked copy | House choice: a canvas changes under the build with no history, so a reviewer cannot tell which version a surface was built against                                 | 2026-10-18 |
+| Load the keeper skill          | House choice: the rule governs an edit and carries no procedure, so a session without the skill copies frames in by hand or skips the index row                     | 2026-10-21 |
 | Land a design first            | House choice: a design landing inside a feature pull request is reviewed as code, and a second feature building against it meanwhile reads a design nobody accepted | 2026-10-18 |
 | No hand edits                  | House choice: a reference edited by hand drifts from its canvas source, and the next sync overwrites the edit or reports it as a change nobody made                 | 2026-10-18 |
 | Index row before the sync      | House choice: the sync writes only the surfaces the index names, so a missing row drops the new surface's reference, and a stale row keeps a removed surface's      | 2026-10-18 |

package/governance/rules/ui/design-reference.md

@@ -17,6 +17,7 @@ paths:
 ## Where the design lives
 
 - Build UI against `canon/design/`, never against the canvas directly.
+- Load the `canon:design-record` skill before adding, redrawing, or removing a reference under `canon/design/`, and report it rather than proceeding silently when it does not resolve.
 - Land a picked or changed canvas design in `canon/design/` through the project's design sync, as its own pull request, before any feature builds against it.
 - Never copy, edit, or delete a reference file under `canon/design/` by hand.
 - Add a new surface's row to the index in `canon/design/` before running the sync, and remove it only in the change that removes the surface.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.49.0",
+  "version": "5.50.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/claude/cases/misc.ts

@@ -39,6 +39,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Draw the signup screen as a frame on the canvas, then restyle the element I just selected there.',
     expect: 'canvas-board',
   },
+  {
+    prompt:
+      'The operator picked the new settings panel, so land it in canon/design with an index row for it.',
+    expect: 'design-record',
+  },
   {
     prompt:
       "We're about to hit the context limit, write the handoff before we lose state.",