@erclx/canon 5.68.0 → 5.70.0

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

@@ -1,6 +1,6 @@
 ---
 name: design-identity
-description: Drafts a project's logo mark through pick-by-eye's render-and-pick loop, then composes the picked mark into an icon sequence and a 1200x630 social card. Use when asked to "make a logo", "design a logo mark", "create a favicon", "build the icon set", "generate a social card", "make an og:image", or "draft the logo and social card together". Do NOT use to mutate an existing logo file directly, which is a plain edit, or to record the mark's construction rules in DESIGN.md, which is out of scope.
+description: Drafts a project's logo mark through design-pick's render-and-pick loop, then composes the picked mark into an icon sequence and a 1200x630 social card. Use when asked to "make a logo", "design a logo mark", "create a favicon", "build the icon set", "generate a social card", "make an og:image", or "draft the logo and social card together". Do NOT use to mutate an existing logo file directly, which is a plain edit, or to record the mark's construction rules in DESIGN.md, which is out of scope.
 metadata:
   family: generate
 ---
@@ -60,7 +60,7 @@ Announce which tier decided, naming the tier rather than the path alone, so the
 
 ## Step 4: name the decision and the arms
 
-Follow `${CLAUDE_SKILL_DIR}/../pick-by-eye/SKILL.md` Step 1, with the decision fixed rather than derived: "the project's logo mark and its composition into the social card." Vary the mark's shape or style across arms, keeping the card's type and layout fixed, per that skill's one-property rule.
+Follow `${CLAUDE_SKILL_DIR}/../design-pick/SKILL.md` Step 1, with the decision fixed rather than derived: "the project's logo mark and its composition into the social card." Vary the mark's shape or style across arms, keeping the card's type and layout fixed, per that skill's one-property rule.
 
 - Draft each arm inside the 1200x630 card frame, mark and type together, and add it with `frameboard frame add <page>/arm-<id> --width 1200 --height 630`, so one pick settles shape and composition
 - Arm 0 is the current mark when the Step 3 folder already holds a logo file (`favicon.svg`, `favicon.ico`, `logo.svg`, or similar). Arms start at 1 otherwise.
@@ -68,13 +68,13 @@ Follow `${CLAUDE_SKILL_DIR}/../pick-by-eye/SKILL.md` Step 1, with the decision f
 
 ## Step 5: draft, render, pick, and loop
 
-Follow `${CLAUDE_SKILL_DIR}/../pick-by-eye/SKILL.md` Steps 2 through 5 against the arms from Step 4: draft the arms as frames on a Frameboard page, render and hand off, take the pick, and loop on it.
+Follow `${CLAUDE_SKILL_DIR}/../design-pick/SKILL.md` Steps 2 through 5 against the arms from Step 4: draft the arms as frames on a Frameboard page, render and hand off, take the pick, and loop on it.
 
-The final icon and card renders below are not arms, so they stay off the board. Call the folder they render from `<dest>`, being `.canon/tmp/<slug>/` under the slug `pick-by-eye` Step 1 derived, which is where this project puts every temporary write.
+The final icon and card renders below are not arms, so they stay off the board. Call the folder they render from `<dest>`, being `.canon/tmp/<slug>/` under the slug `design-pick` Step 1 derived, which is where this project puts every temporary write.
 
 ## Step 6: finalize the mark and the icons
 
-This step and Step 7 replace `pick-by-eye`'s own Step 6 items 1 and 2, since the pick here produces several final files rather than one applied surface. Its archive capture, its page delete, and its server stop still run, after Step 7.
+This step and Step 7 replace `design-pick`'s own Step 6 items 1 and 2, since the pick here produces several final files rather than one applied surface. Its archive capture, its page delete, and its server stop still run, after Step 7.
 
 1. Extract the picked arm's `.mark` markup as the final vector source. Write it to `<write-folder>/favicon.svg`.
 2. Under `<dest>/render/`, write one `icon-<w>x<h>.html` page per Step 2 size, carrying the picked `.mark` markup in an element with the shared class `.render`.
@@ -112,7 +112,7 @@ It takes its own call because Step 6's batch is already captured by the time thi
 
 ### Closing the scratch folder and the board
 
-Delete `<dest>` once both captures land, then close the board through `pick-by-eye` Step 6 items 3 to 8, which archive every arm and delete the pages the run added. The route is not a leftover variant, since it holds the arm the operator picked.
+Delete `<dest>` once both captures land, then close the board through `design-pick` Step 6 items 3 to 8, which archive every arm and delete the pages the run added. The route is not a leftover variant, since it holds the arm the operator picked.
 
 A project whose card was generated before this route existed keeps its PNG. Say so rather than regenerating it, since the pick loop spends attention on a file nobody complained about, and the next real edit picks up the route.
 
@@ -132,7 +132,7 @@ Card source: <the route, captured through the card server|a scratch page, since
 
 Cite these rather than restating them.
 
-- `pick-by-eye` owns Steps 1 through 5 of the render-and-pick loop, cited above
+- `design-pick` owns Steps 1 through 5 of the render-and-pick loop, cited above
 - `canon:design-record` carries a picked direction into `canon/DESIGN.md`. This skill only reads it.
 - `canon capture` owns the render mechanics, its font refusal, its fixed 2x scale, and its reported dimensions. It reads an `http(s)://` source, where `--out` names the PNG.
 - The `astro` tooling stack owns the card route's scaffold, its second config, and the exclusion check, read with `canon tooling reference astro`. This skill writes into the route and never reshapes it.

package/claude/skills/{pick-by-eye → design-pick}/REQUIREMENT.md

@@ -1,15 +1,15 @@
 ---
-name: pick-by-eye
+name: design-pick
 description: Why a decision settled by looking needs its own surface, and where its boundary against the planning, audit, measurement, and recording skills falls
 ---
 
-# Pick by eye requirement
+# Design pick requirement
 
 ## Gap
 
 Without this skill, a session facing a decision settled by looking describes the options in prose or ships one answer to a taste call. The operator never sees what they chose between. A drafted set varies several properties or the wrong layer, sits in the real surface, and mixes themes and widths, so no pick names what decided it.
 
-The evidence fails as well. Arms get reported without being rendered or judged, a driver finding reads as a verdict, and the pick question arrives with no address to look at. Renders land in scratch, each round overwrites the last, and the losing arms vanish with the run's pages.
+The evidence fails as well. Arms get reported unrendered or unjudged, a driver finding reads as a verdict, and the pick question arrives with no address to look at. Renders land in scratch, each round overwrites the last, and the losing arms vanish with the run's pages. Rounds drafted off the synced board need redrawing.
 
 ## Must
 
@@ -17,7 +17,7 @@ The evidence fails as well. Arms get reported without being rendered or judged,
 - Each round is one Frameboard page of frames at their judged widths, themed by the board toggle and captured once as a composite, with the link ahead of the first pick question
 - Every arm is rendered and judged against a stated bar before handover, and a missing browser or a board that will not start is reported as a refusal
 - The pick comes through the structured question surface with the recommendation first and every option's cost, and the winner lands in one change
-- Every round stays openable on its own page until the pick, and the picked round's arms are captured into the citing record at the main root before the run's pages go
+- Rounds sit on the board the design config names, each openable until the pick, and the picked arms are archived at the main root before the run's pages go
 
 ## Must not
 
@@ -30,6 +30,6 @@ The evidence fails as well. Arms get reported without being rendered or judged,
 ## Out of scope
 
 - Planning the work once the answer is settled, which `plan-feature` owns
-- Finding roughness by reading source, which `ux-audit` owns
-- Measuring what a running interface costs to paint, which `ux-measure` owns
+- Finding roughness by reading source, which `ui-audit` owns
+- Measuring what a running interface costs to paint, which `ui-measure` owns
 - Listing what to look at on a change already made, which `ui-checklist` owns

package/claude/skills/{pick-by-eye → design-pick}/SKILL.md

@@ -1,15 +1,15 @@
 ---
-name: pick-by-eye
-description: Drafts several candidates for a decision judged by looking, lays them out side by side as frames on one Frameboard page, hands the operator the address, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `plan-feature`. Do NOT use to read source for roughness, which is `ux-audit`, to measure what a running interface costs to paint, which is `ux-measure`, or to write what to look at on a change already made, which is `ui-checklist`.
+name: design-pick
+description: Drafts several candidates for a decision judged by looking, lays them out side by side as frames on one Frameboard page, hands the operator the address, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `plan-feature`. Do NOT use to read source for roughness, which is `ui-audit`, to measure what a running interface costs to paint, which is `ui-measure`, or to write what to look at on a change already made, which is `ui-checklist`.
 metadata:
   family: decide
 ---
 
-# Pick by eye
+# Design pick
 
 Some decisions are settled by looking rather than by reasoning, and no draft is wrong until one is picked. Every step here puts several candidates in front of the operator and keeps the real surface untouched until they have chosen.
 
-The candidates live on a Frameboard board at `.canon/canvas/`, in a project named `picks` so rounds never mix with an operator's project. Read `${CLAUDE_SKILL_DIR}/references/board.md` before the first `frameboard` verb, for the flags every verb carries and how a selection resolves.
+The candidates live on the Frameboard board the project names, in a project of their own so rounds never mix with the operator's frames. Read `${CLAUDE_SKILL_DIR}/references/board.md` before the first `frameboard` verb, for how `<board>` and `<project>` resolve, the flags every verb carries, and how a selection resolves.
 
 ## Guards
 
@@ -34,7 +34,7 @@ Inside a live `plan-groundwork` track, renders land in the track's own `evidence
 Every arm of a round sits as one frame on one board page, side by side. The operator judges that page, never a set of separate images compared from memory.
 
 1. Start the board the way `references/board.md` states, unless this run already has. Note whether this run started the server, read off `reused`, since Step 6 ends only a server this run started.
-2. Read `frameboard list --root <board> --json` with no `--project`, so it lists every project. Run `frameboard project add picks --root <board> --json` when it lists no `picks`.
+2. Read `frameboard list --root <board> --json` with no `--project`, so it lists every project. Run `frameboard project add <project> --root <board> --json` when it lists no `<project>`.
 3. Add the round's page with `frameboard page add <page>` and record its `ref` on the run's list of pages. A `name-taken` refusal means the name is somebody else's, so take the next free suffix.
 4. Add each arm with `frameboard frame add <page>/arm-<id> --width <px> --height <px> --x <px> --y <px>`, placing the frames in one row in arm order. Step 6's archive keys on the `arm-<id>` names.
 5. Write each arm's whole document to the `path` the add verb reported. From a linked worktree, take the heredoc route `session-worktree` gives for a main-root write.
@@ -48,6 +48,7 @@ Each frame carries its own label and follows the board theme, so the set reads a
 - Label each arm inside its frame with its id and its cost, since the composite capture draws no captions
 - Theme every arm off the `data-theme` attribute the board sets on each frame's root, so the theme toggle sets the whole set at once. A set spanning both themes cannot be compared.
 - Give no arm a script that stores a theme and reapplies it on load. It overwrites the toggle, and a fresh browser profile hides the fault.
+- Write each frame's headings, labels, and captions by `${CLAUDE_SKILL_DIR}/../ui-craft/references/copy.md`, since a candidate's copy is often the first draft of the shipped page's
 
 ### Default path and live app
 
@@ -72,7 +73,7 @@ Vary one property across the arms, since a pick cannot say which of three differ
 Render the page and look at what came back before handing anything over:
 
 ```bash
-frameboard capture --page <page> --composite --root <board> --project picks --json
+frameboard capture --page <page> --composite --root <board> --project <project> --json
 ```
 
 - Point `--out` at `evidence/<slug>/renders/` inside a live track, and leave the board's default elsewhere. Step 6 archives the picked round alone.
@@ -118,15 +119,23 @@ Read the selection when the answer points at the board, such as "the selected on
 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. Hand the winning frame's ref to `canon:design-record`, 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 `frameboard capture --page <page> --out <canon-dir>`, keeping the losing arms as a revert record. Report each image's `path` off the record.
-5. Resolve `<canon-dir>` as `.canon/` against the main worktree root, since shared session scratch resolves there. Frameboard appends the project and page, so the archive lands at `.canon/picks/<page>/`.
-6. Delete every page on the run's list with `frameboard page delete <page>`. Touch no page the run did not add, whatever its name, and never remove a page folder by hand.
+5. Resolve `<canon-dir>` as `.canon/` against the main worktree root, where shared session scratch resolves. Frameboard appends the project and page, so the archive lands at `.canon/<project>/<page>/`.
+6. Delete every page on the run's list with `frameboard page delete <page>`, except a picked page on a named board. Touch no page the run did not add, and never remove a page folder by hand.
 7. End the serve command if this run started it, since Frameboard carries no stop verb. Leave a server 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 its `ref` and the `error.code`. The pick is applied either way.
+9. Report each page or frame whose delete is refused, naming its `ref` and the `error.code`. 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 6 delete the winning arm with nothing kept, and a variant left on the board is a second design nobody maintains.
 
+### On a named board
+
+A board `canon/config/design.toml` names is the one the project's design sync reads, and once `design-record` lands the pick, the sync's mapping points at the winning frame. Deleting that page leaves a later redraw nothing to read.
+
+- Keep the picked round's page and its winning frame
+- Delete each losing arm on it with `frameboard frame delete <page>/arm-<id>`, after item 4's capture has archived it
+- Delete every other page on the run's list as item 6 states
+
 ## Reading a measurement
 
 A capture proves appearance and a measurement proves a relationship, so reach for the second whenever the claim is a number, such as a contrast ratio, a column width, or a tap target. `canon drive` runs the probes and ships the failure modes each one carries.
@@ -142,7 +151,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-record` lands the winning frame in the reference folder and its values in the design document, and runs before item 4's capture and item 6's deletes, which keep the picked page on named boards
 - `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/{pick-by-eye → design-pick}/references/board.md

@@ -1,12 +1,18 @@
 # The Frameboard board
 
-Read before the first `frameboard` verb a `pick-by-eye` run sends. It carries where the board sits, how the verbs are reached, how the server starts, and how a selection resolves to an answer.
+Read before the first `frameboard` verb a `design-pick` run sends. It carries where the board sits, how the verbs are reached, how the server starts, and how a selection resolves to an answer.
 
 ## Reaching the board
 
-Resolve `<board>` as `.canon/canvas/` against the main worktree root, the way `session-worktree` resolves it, since a linked worktree holds no copy of the gitignored folder.
+Resolve `<board>` and `<project>` from the `board` and `project` keys of `canon/config/design.toml`, read at the main worktree root per `${CLAUDE_SKILL_DIR}/references/design-config.md`. A missing file or key falls back to `.canon/board/` and `picks`.
 
-- Pass `--root <board> --project picks --json` to every verb unless the step says otherwise, so no verb relies on the only-project default
+- Stop before starting a board when `<board>` came from that fallback, `.canon/board/` is absent, and `.canon/canvas/` exists
+- Report `❌ The board is still at .canon/canvas/. Run canon migrate record-layout --write, then re-run.` on that stop
+- A board started there drafts on an empty page set and leaves the migration a standing collision
+
+Resolve `<board>` against the main worktree root, the way `session-worktree` resolves it, since a linked worktree holds no copy of the gitignored folder.
+
+- Pass `--root <board> --project <project> --json` to every verb unless the step says otherwise, so no verb relies on the only-project default
 - Where `frameboard` is not on PATH, run every verb as `bunx -y frameboard@0.6 <verb>`. Say so once and keep that form for the run.
 - The pin holds the minor, since record shapes move across a pre-1.0 minor
 
@@ -30,13 +36,13 @@ frameboard serve --root <board> --no-open --tokens <stylesheet> --json
 
 Read `frameboard selection --root <board> --json` when the operator's answer points at the board, such as "the selected one". Resolve it against the record's `project` and `page` as well as its `frames`, since every round reuses the `arm-<id>` names.
 
-| Selection                                                     | Reading                                                  |
-| ------------------------------------------------------------- | -------------------------------------------------------- |
-| One frame in `frames`, on the current round's page in `picks` | The pick                                                 |
-| One frame in `frames`, on an earlier round's page             | A revert, so name the round back before acting           |
-| An `element` inside a picked frame                            | A correction the loop carries by its `index` and `hash`  |
-| Several entries in `frames`                                   | Ask which one rather than taking the first               |
-| Empty `frames`, another project, or a page the run never made | No answer, so ask again rather than guess                |
-| `tabs: 0`, or a `server-not-running` refusal                  | No board is open, so hand the address over and ask again |
+| Selection                                                         | Reading                                                  |
+| ----------------------------------------------------------------- | -------------------------------------------------------- |
+| One frame in `frames`, on the current round's page in `<project>` | The pick                                                 |
+| One frame in `frames`, on an earlier round's page                 | A revert, so name the round back before acting           |
+| An `element` inside a picked frame                                | A correction the loop carries by its `index` and `hash`  |
+| Several entries in `frames`                                       | Ask which one rather than taking the first               |
+| Empty `frames`, another project, or a page the run never made     | No answer, so ask again rather than guess                |
+| `tabs: 0`, or a `server-not-running` refusal                      | No board is open, so hand the address over and ask again |
 
 Pass the element's `hash` to `frameboard edit --hash` with its `index`. A frame rewritten since the operator picked refuses with `stale-address` rather than landing on another element, so ask for the pick again on that refusal.

package/claude/skills/design-pick/references/design-config.md

@@ -0,0 +1,33 @@
+---
+title: Design config
+description: The canon/config/design.toml keys board and project, their defaults, and how a design-pick run resolves the board it drafts on
+---
+
+# Design config
+
+Read before the first `frameboard` verb a `design-pick` run sends. A project names the Frameboard board its design sync reads in `canon/config/design.toml` at the main worktree root, and the run reads that file and never writes it.
+
+```toml
+board = ".canon/board"
+project = "picks"
+```
+
+## Keys
+
+| Key       | Holds                                                   | Default         |
+| --------- | ------------------------------------------------------- | --------------- |
+| `board`   | The board folder a round drafts on, under the main root | `.canon/board/` |
+| `project` | The Frameboard project a round's pages go in            | `picks`         |
+
+Each key falls back on its own, so a file naming `board` alone moves the board and keeps the project at `picks`.
+
+- Resolve `board` against the main worktree root even when the run sits in a linked worktree, since the board folder is gitignored and a linked worktree holds no copy of it
+- Leave `project` at `picks` on a named board unless the operator wants otherwise, so rounds sit on the board the sync reads and stay apart from the accepted frames
+- Stop on a file that does not parse or a key that is not a string, naming the file's path. Falling back there would draft the round where the sync never looks.
+- The archive lands at `.canon/<project>/<page>/`, so it follows `project`. Stop on a `project` naming a `.canon/` folder another record owns, such as `plans` or `tasks`.
+
+## When the file is absent
+
+The run drafts on `.canon/board/` in `picks`, the folder Frameboard keeps its design board in, and asks nothing.
+
+Set the file when the project's design sync reads a board other than `.canon/board/`. A round drafted there lands through `design-record` without a redraw, and Step 6 of the skill body keeps the winning page for the sync's mapping.

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

@@ -24,10 +24,10 @@ Each project invents its own grouping, and its index restates the file tree rath
 - 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 `pick-by-eye` should hand off to it
+- Be reached only by the author typing its name, since a pick from `design-pick` should hand off to it
 
 ## Out of scope
 
-- Drafting candidates and taking the pick, which `pick-by-eye` owns
+- Drafting candidates and taking the pick, which `design-pick` owns
 - Drawing, selecting, and capturing frames on a board, which Frameboard owns
 - Judging whether a design is good, which `design-taste` owns

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

@@ -1,6 +1,6 @@
 ---
 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 a board, which is Frameboard, or to judge a design, which is `design-taste`.
+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 `design-pick`, to draw frames on a board, which is Frameboard, or to judge a design, which is `design-taste`.
 metadata:
   family: ship
 ---

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

@@ -25,12 +25,12 @@ The output has no standard of quality either. A model with no stated direction d
 - Admit a rule an unguided model already gets right, another surface owns, a threshold settles, or no single line could violate
 - Restate the correctness floor or the banned characters, or trade accessibility and the state set against an aesthetic preference
 - Express intensity as a numeric scale, or claim a round follows these rules when nothing measures it
-- Be reached only by an author typing its name, since `pick-by-eye`'s declared read is the intended caller
+- Be reached only by an author typing its name, since `design-pick`'s declared read is the intended caller
 
 ## Out of scope
 
 - Accessibility, keyboard interaction, state coverage, forms, and rendered copy, which `ui-craft` owns
 - The focus ring's floors, which `ui-craft` owns, though its weight is this skill's
-- The candidate loop and the pick, which `pick-by-eye` owns
+- The candidate loop and the pick, which `design-pick` owns
 - The shape of the project's design document, which `design-record`'s design reference governs
 - Prose on the surface being designed, which `write-human` and `markdown-craft` own

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

@@ -1,6 +1,6 @@
 ---
 name: design-taste
-description: Carries the layer model that decides which design decision settles first, the rules that keep a surface coherent across sections, and the catalog of defaults a model reaches for when nothing states a direction. Use when drafting or judging an interface, a page, or any rendered surface, when output reads generic or templated, when redesigning something that already exists, or when asked to "make this look designed", "why does this look like AI made it", "give it taste", "what layer is this decision at", or "grey-box this first". Do NOT use for accessibility, forms, or state coverage, which `ui-craft` carries, for the shape of the project's design document, which `design.md` governs, or to run the candidate loop, which is `pick-by-eye`.
+description: Carries the layer model that decides which design decision settles first, the rules that keep a surface coherent across sections, and the catalog of defaults a model reaches for when nothing states a direction. Use when drafting or judging an interface, a page, or any rendered surface, when output reads generic or templated, when redesigning something that already exists, or when asked to "make this look designed", "why does this look like AI made it", "give it taste", "what layer is this decision at", or "grey-box this first". Do NOT use for accessibility, forms, or state coverage, which `ui-craft` carries, for the shape of the project's design document, which `design.md` governs, or to run the candidate loop, which is `design-pick`.
 metadata:
   family: build
 ---
@@ -157,8 +157,8 @@ Run `${CLAUDE_SKILL_DIR}/references/preflight.md` against the output. It is the
 
 Five neighbors own the rest.
 
-- The candidate loop, the arm set, the render, and the pick: `pick-by-eye`
+- The candidate loop, the arm set, the render, and the pick: `design-pick`
 - 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`
+- Reading source for roughness: `ui-audit`. Measuring what a running interface costs to paint: `ui-measure`
 - Prose on the surface being designed: the `write-human` skill

package/claude/skills/design-taste/references/preflight.md

@@ -101,5 +101,5 @@ Every word on the surface states what is true of it.
 
 ## Handover
 
-- [ ] The weakest thing on the surface is named out loud, per `pick-by-eye` Step 3, and fixed where naming it would embarrass the work
+- [ ] The weakest thing on the surface is named out loud, per `design-pick` Step 3, and fixed where naming it would embarrass the work
 - [ ] The floor the `ui-craft` skill carries has been applied, not assumed

package/claude/skills/git-issue/REQUIREMENT.md

@@ -28,5 +28,5 @@ Prose bans hold on files the hook watches and not on text leaving through `gh`,
 ## Out of scope
 
 - Reporting a toolkit defect from a target project, which `canon-feedback` owns
-- Triaging issues already filed, which `canon-feedback-triage` owns
+- Triaging the toolkit's feedback issues, which its maintainers do in its own repository
 - Opening a pull request, which `git-pr` owns

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

@@ -97,7 +97,7 @@ Fix the feedback CLI so it applies the `feedback` label.
 
 ## Details
 
-`canon feedback` opens an issue with no label, so `canon-feedback-triage` never lists it.
+`canon feedback` opens an issue with no label, so the toolkit's triage never lists it.
 
 ## Context
 

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

@@ -85,7 +85,7 @@ Every `- Suggested:` line takes senior judgment, picking the best option in one
 
 - Suggest a real default when best practice, the codebase, or prior context points to one
 - Before `## Files to touch`, load `canon:codebase-layout` for a new path (its reason) and `canon:api-design` for a changed verb, flag, output, record shape, or endpoint. Report either if missing.
-- Fill `## Design references` with the `canon/design/<surface>/` folder for each surface a UI file in `## Files to touch` renders, and write `None identified.` in a project with no folder
+- Fill `## Design references` with the `canon/design/<surface>/` folder per rendered surface, or `None identified.`, and `## Reference images` with each untracked image that shaped the plan
 - Write `## Verification` as one bullet per outcome naming the test or command that proves it, with a grep bullet per `## Verbatim` block of settled wording
 - Write `## Review focus` as the inputs or states that would break the change, carrying the risk you understood to the executor and the reviewer
 

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

@@ -75,8 +75,9 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 | `## Current behavior`  | each command run against the thing being changed and what it showed         | When the change touches something that runs       |
 | `## Constraints`       | durable rules the work must respect                                         | When supplied                                     |
 | `## Files to touch`    | each file with a one-line reason                                            | Always                                            |
-| `## Verbatim`          | settled wording that lands unchanged in an existing file, one H3 per block  | When wording is settled                           |
+| `## Verbatim`          | settled wording that lands unchanged in a file, one H3 per block            | When wording is settled                           |
 | `## Design references` | the tracked design folders the change builds against, each with its surface | When Files to touch names a rendered-surface file |
+| `## Reference images`  | the untracked images the plan was shaped against, each from the main root   | When an image shaped the plan                     |
 | `## Verification`      | the test or command that proves each outcome                                | Always                                            |
 | `## Risks`             | conflicts, coupling, and the tricky spots                                   | Always                                            |
 | `## Review focus`      | the inputs or states that would break the change, for the reviewer          | Always                                            |
@@ -166,22 +167,24 @@ Re-test a stamped constraint before honoring it, fetching and scoping the log in
 git fetch origin main --quiet && git log <commit>..origin/main --oneline -- <the paths the constraint names>
 ```
 
-### Fan-in and ready constraints
+### Fan-in constraints
 
 A batch in a fan-in set declares its side in a constraint bullet, ``Fan-in member of `feature-<integrator>` `` on a member and ``Fans in `feature-<a>`, `feature-<b>` `` on the integrator. `batches.md` holds when to fan in, and `canon records validate plans` reports `fan-in-unmatched` for a set whose two sides disagree.
 
-A constraint naming a `.canon/ready/` folder is a third shape beside the hold and the shared path. It makes that folder's files the verbatim source for the paths this plan's `## Files to touch` lists, per `ready.md`, so the executing session copies those paths rather than authoring them.
-
 ### Verbatim
 
-A `## Verbatim` section carries wording someone settled, landing in an existing file exactly as written. Wording the planner only proposes stays a `- Suggested:` question, and a whole new file goes in the ready folder per `ready.md`, so the two never describe the same file.
+A `## Verbatim` section carries wording someone settled, landing in a file exactly as written. Wording the planner only proposes stays a `- Suggested:` question, so the two never describe the same file.
 
 - Give each block an H3 naming it, then a lead sentence with the action, the full path, and the anchor, then a fenced `text` block holding the wording
-- Name the action as Add, Insert, or Replace. A Replace quotes the old line in the lead's code span.
+- Name the action as Add, Insert, Replace, or Create. A Replace quotes the old line in the lead's code span.
 - Write the block as the project's formatter leaves it, since a formatter that re-pads a table row or rewraps a line makes the grep fail on correct text
 - Name the outcome in a grep bullet and put a command past 200 characters in a fenced `bash` block under it, since `S4` reports a longer bullet
 - Give each block one `## Verification` bullet running `grep -cF -e` on its whole first line against its file, so a reworded line fails a check the reviewer already runs.
 
+A Create block makes a new file, so its lead names a path that does not exist yet and no anchor. Its grep bullet takes the first distinctive line, such as the `title:` line or the H1, since a markdown file opens on `---` and that line matches any file with frontmatter.
+
+Keep a Create block to 80 lines. A longer new file goes in `## Files to touch` for the executing session to write, since a plan carrying a whole skill body costs every session that reads it.
+
 ### Design references
 
 A plan whose `## Files to touch` names a rendered-surface file (`.tsx`, `.jsx`, `.astro`, `.vue`, `.svelte`, `.html`, or `.css`) carries this section. It tells the building session which accepted design to open before it writes a line.
@@ -191,6 +194,14 @@ A plan whose `## Files to touch` names a rendered-surface file (`.tsx`, `.jsx`,
 - Cite a tracked folder only, since the building session opens its light and dark images and its frame HTML from the working tree
 - `canon records validate plans` reports `section-missing` for a plan that names a rendered-surface file and omits the section
 
+### Reference images
+
+A plan shaped against an image no tracked folder holds carries this section, such as drive evidence, an image in an intake item, or a design board frame. It tells the building session which images to open before its first edit, and it stays apart from `## Design references`, which cites tracked folders alone.
+
+- Give each entry an image path and what the image shows, as one bullet
+- Write each path from the main worktree root, since these images are gitignored and a linked worktree holds no copy. A path relative to a linked worktree resolves nowhere.
+- Leave the section out when no image shaped the plan. It is optional, and `canon records validate plans` reports nothing on a plan without it.
+
 ### Verification
 
 Every outcome reaches the review with its proof named.
@@ -325,6 +336,10 @@ Add as <where> in `<path/to/file>`, after <anchor>.
 
 - `canon/design/<surface>/`: <the surface it governs>
 
+## Reference images
+
+- `.canon/intake/<nn>-<slug>/evidence/<name>.png`: <what the image shows>
+
 ## Verification
 
 ### <Outcome group>

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

@@ -37,7 +37,7 @@ Write only inside `.canon/groundwork/<nn>-<slug>/`. A feature plan, source chang
 
 What a spike produces stays inside the track, under `.canon/groundwork/<nn>-<slug>/evidence/`, which the first rule already permits. Mode detection matches only top-level entries, so a nested folder cannot be mistaken for a track, and scratch holds only what can be deleted without loss.
 
-A `pick-by-eye` run invoked from inside a live track follows its own branch for this. It writes its renders to `evidence/` here, and drafts its candidates as pages on the Frameboard board at `.canon/canvas/` that its close deletes.
+A `design-pick` run invoked from inside a live track follows its own branch for this. It writes its renders to `evidence/` here, and drafts its candidates as pages on the Frameboard board `design-pick` resolves, where its close removes the round. On a board `canon/config/design.toml` names, the close keeps the picked page.
 
 ### Reading and backing
 

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

@@ -63,9 +63,9 @@ canon pr evidence <number> --check --json
 - Skip filming when the record's `reel.head` is a prefix of the `tip` that `canon pr head <number> --json` reports, since the posted reel already shows this head
 - With no checklist from either source, skip silently, since nothing names an interaction to film
 
-Invoke `canon:ui-record` in pull request mode, passing the number, the local `url`, and the checklist. It films, checks each beat's closing still, pushes the reel to `canon/frames`, and hands back a `link` or a skip reason.
+Invoke `canon:ui-film` in pull request mode, passing the number, the local `url`, and the checklist. It films, checks each beat's closing still, pushes the reel to `canon/frames`, and hands back a `link` or a skip reason.
 
-Report it rather than proceeding silently when `canon:ui-record` does not resolve, and post the evidence without a reel.
+Report it rather than proceeding silently when `canon:ui-film` does not resolve, and post the evidence without a reel.
 
 - Hold a `link` for the evidence step, which embeds it under the addresses
 - Hold a skip's reason and message for the closing report. A skip never stops the chain, and a reel already on the comment carries forward under the older head it names.

package/claude/skills/role-orchestrator/references/orchestrator-launch.md

@@ -117,7 +117,7 @@ No branch and no worktree exist here and none is created. A planner writes one g
 claude --bg --model <model> -n "planner-<project>-<slug>" "Run /canon:role-planner, then /canon:plan-feature <task>. Your controller is the session whose sessionId is <dispatcher-id>. Resolve its current name from that id through canon sessions list --json, which carries sessionId per row, at the moment you send, and never resolve an addressee by name prefix. Message it when the plan lands, carrying the path and what the task file got wrong, and message it again if you stop on a question."
 ```
 
-`<task>` is the row's task file path and `<slug>` the slug its plan will take, resolved off the row. `<dispatcher-id>`, `<model>`, and `<project>` resolve as above, and the prefix reads `planner-` because it marks the role of the session it names.
+`<task>` is the row's task file path and `<slug>` the slug its plan will take, resolved off the row. `<dispatcher-id>`, `<model>`, and `<project>` resolve as above, and the prefix reads `planner-` because it marks the role of the session it names. Then wait per `orchestrator-planning-wait.md`.
 
 ### Which checks bind
 
@@ -131,9 +131,9 @@ What a planning dispatch owes instead is the reverse reading, since a row planne
 
 ### One row per dispatch
 
-A session reused across a batch pays the context load once and ages its picture of the tree while it works, which is why the in-flight read sits on the task rather than the batch. One that compacts mid-batch loses the reasoning behind its earlier plans with nothing reporting it.
+A reused session pays the context load once and ages its picture of the tree, which is why the in-flight read sits on each row. One that compacts loses the reasoning behind its earlier plans unreported, so `role-planner` stops it when the operator ends it or a compaction nears.
 
-Cap a reused session where the saving is worth it and say what the cap was.
+Hold all planning of a row any talk session has said by message it is planning, a drive session included, whether by a launch or by `plan-feature` here, unless the operator asks for a cold planner. That session holds what the operator said about the row, and plans a filed row only once it is named back to it.
 
 ## Dispatch a talk session
 

package/claude/skills/role-orchestrator/references/orchestrator-parked.md

@@ -95,7 +95,7 @@ A local formatter removing the shape on contact says nothing about a target runn
 
 ## The plan half
 
-Plan what the pass clears, and any `## Needs a plan` row whose only blocker is the missing plan. This pass runs while workers build and the session is idle, when planning costs the critical path nothing, and a row cleared with no plan is looked at again next pass.
+Plan what the pass clears, and any `## Needs a plan` row whose only blocker is the missing plan, skipping a row a talk session holds per `orchestrator-launch.md`. This pass runs while workers build and the session is idle, when planning costs the critical path nothing, and a row cleared with no plan is looked at again next pass.
 
 - Run `plan-feature` for each, carrying the constraint per in-flight track that `## The loop` in `role-orchestrator` requires
 - Verify each plan against the tree the way that step does, since several branches are already changing it

package/claude/skills/role-orchestrator/references/orchestrator-planning-wait.md

@@ -0,0 +1,24 @@
+---
+title: Orchestrator planning wait
+description: How the orchestrator waits in the background on a row whose plan a planner is still writing, through canon tasks launchable, and how it branches on the record the wait ends on
+---
+
+A row whose plan a planner is still writing has nothing to dispatch yet. Run the wait in the background rather than grepping the task file on a loop, and act on the wake:
+
+```bash
+canon tasks launchable <task> --wait --json
+```
+
+The verb resolves the task's `Plan:` line and runs the `plan-answers` gate on the plan it names, re-reading every 30 seconds for up to 1800 seconds by default. It keys on the line rather than the plan file. A planner links a plan only after it validates, so a half-written plan never wakes the loop.
+
+## Branch on the record
+
+Branch on the record's `reason` rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
+
+- `launchable`: the plan waits on nobody, so run `${CLAUDE_SKILL_DIR}/references/orchestrator-dispatch.md` from the candidate on, since the wait never reads the branch or the conflict check
+- `timeout`: read `plan` and `open` off the last reading, then act on which one held the row
+  - No `plan` means nothing was linked in time, so check the planner is still live and re-arm the wait
+  - A non-empty `open` names the questions holding the row, so report each label and reason to the operator, then re-arm the wait
+- A refusal such as `several-plans`, `archived`, or `no-match` means the row cannot launch as it stands, so name the reason and fall back to the human
+
+A one-shot read without `--wait` reports `reason: unlinked`, `open`, or `launchable` at once. It suits a pass that only needs the row's state now.

package/claude/skills/role-planner/SKILL.md

@@ -86,10 +86,11 @@ Each finding in that file opens with the bold source-and-date label that `${CLAU
 
 ## The channel
 
-The controlling session cannot watch this one read, so two messages are owed and nothing else.
+The controlling session cannot watch this one read, so the messages below are owed and nothing else.
 
 - Announce the record as the file lands, carrying its path and what the task file got wrong. Write no summary beside it, which is a second account of a document the reader is about to open.
 - Send a block out as a message before it becomes an interactive prompt.
+- Name the handed rows still unplanned when a reused session stops under `## Lifetime`
 - Send nothing on progress, which rebuilds on this side the poll the announcement retires on the other
 
 ### Addressing
@@ -120,5 +121,6 @@ The operator being present is an assumption the launch carries. A talk planner w
 ## Lifetime
 
 - The role runs from the launch to the record landing, and the operator closes a talk session. A session handed a second row works it under the same role and reads the tree again for it.
-- A reused session's picture of the tree ages, and it nears a compaction that silently drops the reasoning behind its earlier records. Cap a reused session rather than letting it run the board.
+- A reused session's picture of the tree ages, and a compaction silently drops the reasoning behind its earlier records
+- Run the in-flight read again before each handed row, and stop when the operator ends the session or a compaction nears, telling the controller which rows are still unplanned
 - Treat this body as possibly older than the branch under it. A plugin skill loads from the marketplace cache rather than from the working tree.

package/claude/skills/role-worker/SKILL.md

@@ -18,17 +18,16 @@ This body states the role, the boundaries, and the channel, and starts no step o
 
 ## Where the session stands
 
-- Resolve `.canon/plans/`, `.canon/tasks/`, `.canon/review/`, and `.canon/ready/` at the main worktree root, never the linked worktree. Being gitignored, they are absent there rather than empty.
+- Resolve `.canon/plans/`, `.canon/tasks/`, and `.canon/review/` at the main worktree root, never the linked worktree. Being gitignored, they are absent there rather than empty.
 - Report a plan that fails to resolve as unreadable from here, naming the main-root path. Reporting the task as having no plan is wrong about the world, and a reader cannot tell the two apart.
 - Build the plan the launch named. Never write a second one when the path fails to resolve, since a row citing a plan already has one.
 - Load `ui-craft` before editing a rendered surface, pointer rule or not
 - Keep a task list from launch, one item per slice, and tick each as its slice lands. Skip it on a host that offers no list tool, since the list is for the operator watching and not a gate.
 
-### Ready folders and the draft mark
+### The draft mark
 
-A ready folder and the draft mark each carry work another session already did, so this one preserves both.
+The draft mark holds the merge until the reviews close, so this session preserves it.
 
-- Copy a ready folder's files verbatim to the paths its plan's `**Constraints:**` block names, editing only what the gate or the overview's list requires, since a rewrite discards the handoff
 - The ship chain marks the pull request a draft, and only `canon pr lift` or the operator un-marks it
 - Report a flag reading ready once and leave it. It passed every gate the verb reads or a person readied it, which GitHub requires before a merge, so re-drafting fights them.
 - Leave the lift to the reviewers, who run `canon pr lift` on their close, with the controlling session as fallback
@@ -53,9 +52,9 @@ Run `canon pr drive-copy --json` before starting `dev`. On `copied`, start it wi
 
 A hand-run `git-ship` or `git-pr` starts no server, since only a worker has a lifetime to own one.
 
-### Building against a design reference
+### Building against design references and images
 
-A plan carrying a `**Design references:**` section names the accepted design for the surface it changes. Open it before building, since the build matches it and a worker that reads the dark image alone ships a light theme nobody saw.
+A plan's `## Design references` names the accepted design per surface, and `## Reference images` names images it was shaped against by main-root path. Either can appear alone. Open both before building, since a worker reading the dark image alone ships a light theme nobody saw.
 
 - Open each cited folder's light and dark images and its frame HTML before the first edit to that surface
 - Take sizes, spacing, and colors from the frame HTML rather than from the image

package/claude/skills/task-board/references/tasks.md

@@ -141,7 +141,7 @@ A task with no origin is lost context or work nobody decided to do. The reverse
 
 - Write the path relative to `.canon/tasks/`, as `../plans/`, `../groundwork/`, and `../intake/`. A path from the project root resolves to nothing in an editor rooted there.
 - `Issue:` stays a bare `#NNN`, since a full URL writes the remote into a gitignored file. Several issues list comma-separated, each getting a `git-pr` closing line.
-- `Ready:` links `../ready/<nn>-<slug>/`, the folder the plan copies from, only when it exists. `canon tasks archive` reads it to move the folder, falling back to a path in the plan.
+- `Ready:` is a line older tasks carry, linking `../ready/<nn>-<slug>/`. No new task gains one, and `canon tasks archive` still reads it to move and retarget the folder.
 
 ### The `Plan:` line
 

package/claude/skills/task-complete/references/receipt-sweep.md

@@ -37,7 +37,7 @@ A branch report is read once, by the session addressing it. The durable record i
 
 ### What stays
 
-Do not sweep `ux-audit-*.md` or `ux-measure-*.md`, which are standalone deliverables. They sit at `.canon/review/` itself rather than under a producer folder, so the glob never reaches them.
+Do not sweep `ui-audit-*.md` or `ui-measure-*.md`, which are standalone deliverables. They sit at `.canon/review/` itself rather than under a producer folder, so the glob never reaches them.
 
 Output one line per file swept: