@erclx/canon 5.53.0 → 5.55.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [5.55.0](https://github.com/erclx/canon/compare/v5.54.0...v5.55.0) (2026-10-21)
+
+
+### Features
+
+* **cli:** decide headless from a missing terminal on stdin ([#2600](https://github.com/erclx/canon/issues/2600)) ([63e9af6](https://github.com/erclx/canon/commit/63e9af6fcd2b23c1aa4abe45e0fb818519b0e314))
+* **cli:** quiet stderr on --json runs and drop the frame off a terminal ([#2599](https://github.com/erclx/canon/issues/2599)) ([824861b](https://github.com/erclx/canon/commit/824861b55ce9a1c92227b3b8c96f541684d2da8b))
+
+## [5.54.0](https://github.com/erclx/canon/compare/v5.53.0...v5.54.0) (2026-10-21)
+
+
+### Features
+
+* **canvas:** move the design board to Frameboard and retire the canvas ([#2593](https://github.com/erclx/canon/issues/2593)) ([19e0d4f](https://github.com/erclx/canon/commit/19e0d4f4c0022f02bdc94253a743ef757ec44bcc))
+* **ci:** prove canon on macOS with the stock bash ([#2591](https://github.com/erclx/canon/issues/2591)) ([0220169](https://github.com/erclx/canon/commit/0220169cf6f10fb45ff07ffba7fb58a708ade5e2))
+* **design:** retire the canvas-only design verbs and sync domain ([#2598](https://github.com/erclx/canon/issues/2598)) ([ed15567](https://github.com/erclx/canon/commit/ed1556768df49a015b8c9a921df41382e2d19e89))
+* **skills:** give teach-craft a cited source ledger ([#2592](https://github.com/erclx/canon/issues/2592)) ([d67d18c](https://github.com/erclx/canon/commit/d67d18ccf6de3a04963fc20c0ff0624ea7b479f4))
+
 ## [5.53.0](https://github.com/erclx/canon/compare/v5.52.0...v5.53.0) (2026-10-21)
 
 

package/README.md

@@ -66,15 +66,16 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 
 ### Domain catalog
 
-| Domain         | What it is                                                                                                              | How it reaches you                                              |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| Plugin skills  | Skills that plan a feature, review a diff, sync the planning docs, and run the ship chain                               | Loaded live from the plugin, never copied                       |
-| Governance     | Coding and authoring rules that load into a Claude session when a matching path is edited                               | Installed per project by `canon gov install`, refreshed by sync |
-| Tooling stacks | Golden configs, seeds, and a reference per framework                                                                    | Laid down by `canon init`, reconciled by `canon tooling sync`   |
-| Design system  | Ships a `DESIGN.md` intent format pointing at your stylesheet for values, a skill that drafts one, and a render command | `canon design render`                                           |
-| Canvas         | Pages of HTML frames on a local pan and zoom surface, each frame drawn with the project's tokens                        | `canon canvas serve`                                            |
-| Transcripts    | A YouTube transcript with metadata frontmatter                                                                          | `canon transcripts <url>` writes it into any repo               |
-| Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow                              | `canon sandbox`                                                 |
+| Domain         | What it is                                                                                            | How it reaches you                                              |
+| -------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Plugin skills  | Skills that plan a feature, review a diff, sync the planning docs, and run the ship chain             | Loaded live from the plugin, never copied                       |
+| Governance     | Coding and authoring rules that load into a Claude session when a matching path is edited             | Installed per project by `canon gov install`, refreshed by sync |
+| Tooling stacks | Golden configs, seeds, and a reference per framework                                                  | Laid down by `canon init`, reconciled by `canon tooling sync`   |
+| Design system  | Ships a `DESIGN.md` intent format pointing at your stylesheet for values, and a skill that drafts one | `canon:design-record` drafts it in your repo                    |
+| Transcripts    | A YouTube transcript with metadata frontmatter                                                        | `canon transcripts <url>` writes it into any repo               |
+| Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow            | `canon sandbox`                                                 |
+
+The design board lives outside canon in [Frameboard](https://www.npmjs.com/package/frameboard), which `canon:pick-by-eye` drives for each round of candidates.
 
 ### How domains reach you
 

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.53.0",
+  "version": "5.55.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -1,6 +1,6 @@
 ---
 name: canon-cli
-description: Routes a job to the `canon` verb that does it, and warns which verbs can lose a project's edits before one runs. Use when asked "which canon command does X", "is there a verb for X", "which command tells me if X", "will this overwrite my changes", or before running `canon sync`, `canon gov sync`, `canon tooling sync`, `canon design sync`, `canon migrate`, or `canon indexes regen`. Do NOT use to execute a verb, only to pick one and know what it costs.
+description: Routes a job to the `canon` verb that does it, and warns which verbs can lose a project's edits before one runs. Use when asked "which canon command does X", "is there a verb for X", "which command tells me if X", "will this overwrite my changes", or before running `canon sync`, `canon gov sync`, `canon tooling sync`, `canon migrate`, or `canon indexes regen`. Do NOT use to execute a verb, only to pick one and know what it costs.
 metadata:
   family: answer
 ---
@@ -50,7 +50,8 @@ Each verb here has a skill that owns the job. Load the skill rather than driving
 | Report one computed property across routes   | `canon inventory`   | `canon:target-check`        |
 | Walk a page through interactions and measure | `canon drive`       | `canon:ux-measure`          |
 | Fetch a YouTube transcript                   | `canon transcripts` | `canon:youtube-transcripts` |
-| Work on the local canvas                     | `canon canvas`      | `canon:canvas-board`        |
+
+The design board is Frameboard, a separate CLI outside canon, so a board job runs a `frameboard` verb rather than a `canon` one.
 
 ## Session and ship
 
@@ -84,11 +85,10 @@ Read the doc each line names before running one of these. `canon docs install-an
 - `canon gov sync` replaces a rule you edited and deletes a rule the toolkit retired, edited or not.
 - `canon tooling sync --write` replaces every golden config a stack ships. Seeds are copy-once. Nothing writes without the flag. See `canon docs sync`.
 
-### Design, migrate, and indexes
+### Migrate and indexes
 
-Three more verbs rewrite files in place.
+Two more verbs rewrite files in place.
 
-- `canon design sync` replaces the shipped design files and leaves `.claude/design/project/` alone.
 - `canon migrate --write` rewrites files that cite a retired name or layout. It reports and writes nothing without the flag. See `canon docs migrate`.
 - `canon indexes regen` rewrites each generated `index.md` from the folder's current state, so a hand edit there is lost. See `canon docs indexes`.
 

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

@@ -42,7 +42,7 @@ Read these in the same pass:
 3. Draft the sibling `REQUIREMENT.md` from what the skill is for, in the shape the requirement standard states.
    - Write the gaps from the user's description rather than from the drafted body, since a requirement derived from the body records whatever the draft overfitted to.
 4. Confirm the skill name and both files with the user before writing, when a person can answer.
-   - Skip the confirmation when `CANON_NON_INTERACTIVE=1` is set or another skill's run invoked this one, such as `auto-ship` or a dispatched worker.
+   - Skip the confirmation when another skill's run invoked this one, such as `auto-ship`, or when a dispatched worker runs it.
    - Then put the three Step 1 answers and the two drafted paths in the output and continue to Step 5, since a question nobody reads parks the chain.
 
 ### Write and check

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

@@ -23,12 +23,12 @@ A session building this alone restates the render-and-pick loop from scratch, wh
 
 - Draft a mark the operator did not ask for, or mutate an existing logo file, which is a plain edit
 - Add a logo section to the design document's fixed section set, which its parser reads as a fixed key set
-- Modify `pick-by-eye`, `canon capture`, or `canon design render`, which this skill composes
+- Modify `pick-by-eye` or `canon capture`, which this skill composes
 - Be taken as reached by more than an operator typing its name, which a later review reads back rather than assumes
 
 ## Out of scope
 
 - The render, hand-off, pick, and loop mechanics, which `pick-by-eye` owns
-- Carrying a picked direction into the design document, which `canvas-board` owns
+- Carrying a picked direction into the design document, which `design-record` owns
 - Auditing an implemented UI against its tokens, which `ux-audit` owns
 - Wiring the produced files into the project's head or manifest, which the operator owns

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

@@ -62,15 +62,15 @@ Announce which tier decided, naming the tier rather than the path alone, so the
 
 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.
 
-- Draft each arm inside the full 1200x630 card frame, mark and type together, and add its canvas frame at `--width 1200 --height 630`, so one pick settles shape and composition
+- 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.
 - Structure every arm as a `.mark` element, the inline SVG alone, nested inside a `.card` element, the full composition, so Step 6 can address either
 
 ## 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 canvas page, render and hand off, take the pick, and loop on it.
+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.
 
-The final icon and card renders below are not arms, so they stay off the canvas. 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 `pick-by-eye` Step 1 derived, which is where this project puts every temporary write.
 
 ## Step 6: finalize the mark and the icons
 
@@ -110,9 +110,9 @@ canon capture <dest>/render/og-image.html --selector .render --out <write-folder
 
 It takes its own call because Step 6's batch is already captured by the time this step picks a path. Say that the card shipped as a PNG with no source, and that the project gains one when it grows a route to hold the composition.
 
-### Closing the scratch folder and the canvas
+### Closing the scratch folder and the board
 
-Delete `<dest>` once both captures land, then close the canvas 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 `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.
 
 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.
 
@@ -133,6 +133,6 @@ 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
-- `canon:canvas-board` carries a picked direction into `canon/DESIGN.md`. This skill only reads it.
+- `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/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 the picking or canvas skill should hand off to it
+- Be reached only by the author typing its name, since a pick from `pick-by-eye` 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
+- 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 the canvas, which is `canvas-board`, 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 `pick-by-eye`, to draw frames on a board, which is Frameboard, or to judge a design, which is `design-taste`.
 metadata:
   family: ship
 ---
@@ -19,7 +19,7 @@ The document holds the rules and each role's intent, and the folder holds the pi
 ## 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.
+- Never land a candidate the operator has not picked. The folder holds accepted designs, and a draft lives on the board.
 
 ## Step 1: read the record
 
@@ -66,10 +66,10 @@ Retire a reference in the change that removes its surface from the app.
 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 project with no stylesheet yet writes one of its own for the values, and the lead names its 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.
+Never cite a board frame path from the document or the index. The board folder is gitignored, so the citation resolves on one machine alone.
 
 ## Output
 

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

@@ -15,7 +15,7 @@ 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
+- The content format a frame is drawn in, which Frameboard owns and `frameboard docs --json` prints
 
 ## What a working folder looks like
 

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

@@ -31,5 +31,5 @@ The output has no standard of quality either. A model with no stated direction d
 
 - Accessibility, keyboard interaction, state coverage, forms, and rendered copy, which the `a11y`, `keyboard`, `ux-completeness`, `forms`, and `copy` rules own
 - The candidate loop and the pick, which `pick-by-eye` owns
-- The shape of the project's design document, which `canvas-board`'s design reference governs
+- 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/document-health/SKILL.md

@@ -15,7 +15,7 @@ Three axes carry the report. Two answer from a verb and the third answers from a
 
 - `canon` absent from the path: stop. `❌ canon is not on PATH, so neither measured axis can be read.`
 - `git ls-files '*.md'` listing nothing: stop. `❌ No tracked markdown here, so there is no corpus to read.`
-- Run every command under `CANON_NON_INTERACTIVE=1` and prompt at no point. A caller reaching this from a rollout wave has nobody present to answer.
+- Prompt at no point, since a caller reaching this from a rollout wave has nobody present to answer. A call with no terminal on stdin already runs headless, so no command takes a prefix.
 - Branch on each record's own fields rather than on an exit status, since a shell profile may wrap `canon` in a function whose trailing command reports every refusal as success
 - Repair nothing, write no file in the project, and open no pull request. Whoever read the report decides what to fix.
 
@@ -30,8 +30,8 @@ Drop what nobody hand-authors before reporting a finding against it: a generated
 Run these from the project root, in parallel:
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon markdown audit --json
-CANON_NON_INTERACTIVE=1 canon context audit --json
+canon markdown audit --json
+canon context audit --json
 ```
 
 The first answers length, carrying the bullet, paragraph, and depth checkpoints and the per-file weights read against them. The second answers placement for the folders it resolves, carrying entry length, reference form, and index drift.
@@ -39,8 +39,8 @@ The first answers length, carrying the bullet, paragraph, and depth checkpoints
 Then read which classifier would run, and deepen placement with the verdicts per section:
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon context classifier show
-CANON_NON_INTERACTIVE=1 canon context classify sweep --json
+canon context classifier show
+canon context classify sweep --json
 ```
 
 The first names the backend, the model, and the source that decided both. Report which layer answered, since a project with the model layer off reads from the regex layer alone and the sweep says nothing about which one it used.
@@ -65,7 +65,7 @@ Mark every staleness finding as a reading. It is this session's judgment rather
 When the scope reaches `canon/REQUIREMENTS.md`, read it for identity drift as well as for stale paths, and take the review point from the verb:
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon records stale canonical --json
+canon records stale canonical --json
 ```
 
 The doc in the record carries `reviewed` and `releasesSince`. `${CLAUDE_SKILL_DIR}/references/axes.md` holds the identity claim shapes to test and how the record reads. Skip both the read and the verb when the scope excludes the doc.

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

@@ -16,14 +16,14 @@ The CLI holds every number. `canon markdown audit` measures, and `canon markdown
 - `canon` absent from the path: stop. `❌ canon is not on PATH, so nothing can be measured or gated.`
 - The audit refusing: stop and name its `reason`. A `malformed-config` refusal names the file to fix by hand, since the verb will not append to a file it cannot read.
 - `gated add` refusing with `canon-checkout`: stop. Canon's own checkout gates through a constant in its source, which a code change edits.
-- Run every command under `CANON_NON_INTERACTIVE=1`, and branch on each record's own fields rather than on an exit status a shell wrapper can flatten
+- Branch on each record's own fields rather than on an exit status a shell wrapper can flatten. A call with no terminal on stdin already runs headless, so no command takes a prefix.
 
 ## Step 1: read the audit
 
 Run the audit over the whole tree and take the density and reference shape findings from its record:
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon markdown audit --json
+canon markdown audit --json
 ```
 
 Take the candidate folders from the order table in `${CLAUDE_SKILL_DIR}/references/batches.md` rather than from the findings, since a clean folder carries no finding and would never be gated. Drop every folder `canon/config/markdown.toml` already lists, since a listed folder already gates.
@@ -41,7 +41,7 @@ Load `markdown-craft` and `write-human`, then rewrite each failing block by its
 Re-run the audit on the folder alone after each file:
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon markdown audit <prefix> --json
+canon markdown audit <prefix> --json
 ```
 
 Read `${CLAUDE_SKILL_DIR}/references/batches.md` for what a rewrite may cut. A stated reason survives every rewrite, and the audit reaching zero cannot see one that went missing.
@@ -49,7 +49,7 @@ Read `${CLAUDE_SKILL_DIR}/references/batches.md` for what a rewrite may cut. A s
 ## Step 4: gate the folder
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon markdown gated add <prefix> --json
+canon markdown gated add <prefix> --json
 ```
 
 Pass the prefix exactly as the batch named it: a folder with its one trailing slash, such as `docs/`, and a file by its bare path, such as `README.md`. The verb refuses a doubled slash and a slash after a file, since either matches nothing and would gate nothing.
@@ -61,7 +61,7 @@ Branch on the record. `action: appended` or `present` means the folder gates now
 A skill's `REQUIREMENT.md` gates only on its own path, never through a folder prefix, so gating `.claude/skills/` leaves each requirement reporting. Gate each one that reaches zero by its path:
 
 ```bash
-CANON_NON_INTERACTIVE=1 canon markdown gated add .claude/skills/<name>/REQUIREMENT.md --json
+canon markdown gated add .claude/skills/<name>/REQUIREMENT.md --json
 ```
 
 ## Output

package/claude/skills/draw-figure/REQUIREMENT.md

@@ -30,5 +30,5 @@ Asked to refresh one architecture view, it redraws every view beside it. It judg
 ## Out of scope
 
 - Mermaid's layout, budgets, and label rules inside the fence, which the mermaid standard owns
-- A UI screen mockup, and design tokens or the visual system, which `canvas-board` owns
+- A UI screen mockup, which belongs on a Frameboard board, and design tokens or the visual system, which `design-record` owns
 - Implementation detail behind an architecture view, which the context entry the caption points at owns

package/claude/skills/draw-figure/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: draw-figure
-description: Drafts one hand-drawn figure for a document, deciding whether the subject is Mermaid-shaped, an architecture view, or needs freehand SVG, then draws it. Renders the Mermaid path through Mermaid's own hand-drawn look, reads the render back, and fixes what it exposes. Wraps every path in the figure standard's caption, color, and accessibility rules. Use when asked to "draw a figure", "add a hand-drawn diagram", "draft a figure for this doc", "draw this relationship as a figure", "draw the architecture", "diagram the system", or "show the components". Do NOT use for a UI screen mockup, which is `canvas-board`.
+description: Drafts one hand-drawn figure for a document, deciding whether the subject is Mermaid-shaped, an architecture view, or needs freehand SVG, then draws it. Renders the Mermaid path through Mermaid's own hand-drawn look, reads the render back, and fixes what it exposes. Wraps every path in the figure standard's caption, color, and accessibility rules. Use when asked to "draw a figure", "add a hand-drawn diagram", "draft a figure for this doc", "draw this relationship as a figure", "draw the architecture", "diagram the system", or "show the components". Do NOT use for a UI screen mockup, which belongs on a Frameboard board.
 metadata:
   family: generate
 ---

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

@@ -14,8 +14,8 @@ The evidence fails as well. Arms get reported without being rendered or judged,
 ## Must
 
 - Three to five arms, the shipping state among them, each carry an id, a label, and a cost, and vary only at a layer named from the `design-taste` catalog
-- Each round is one canvas page of frames at their judged widths, themed by the canvas 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 canvas that will not start is reported as a refusal
+- 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
 
@@ -24,8 +24,8 @@ The evidence fails as well. Arms get reported without being rendered or judged,
 - Take the pick where two arms are defensible and the difference is taste
 - Draft candidates for a decision the operator has not asked to make, or for a request that already names one answer
 - Write into the real surface before the pick is final
-- Restate the mechanics `canon canvas` and `canon drive` own, or read a drive finding as a gate over the arms
-- Delete a canvas page or stop a server the run did not start
+- Restate the mechanics Frameboard and `canon drive` own, or read a drive finding as a gate over the arms
+- Delete a board page or stop a server the run did not start, or remove a page by any route but a `frameboard` verb
 
 ## Out of scope
 

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

@@ -1,6 +1,6 @@
 ---
 name: pick-by-eye
-description: Drafts several candidates for a decision judged by looking, lays them out side by side as frames on one canvas 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`.
+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`.
 metadata:
   family: decide
 ---
@@ -9,13 +9,14 @@ metadata:
 
 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 the local design canvas, the surface `canon:canvas-board` drives. Every verb below is `canon canvas`, and `${CLAUDE_SKILL_DIR}/../canvas-board/references/canvas.md` fixes the content format a frame takes. Read that reference before writing the first frame.
+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.
 
 ## Guards
 
 - If the request names one answer and asks for it to be built, stop: `❌ This names one answer, so there is nothing to pick between. Use /canon:plan-feature.`
 - If the decision has no visible form, stop: `❌ Nothing to look at. Drafting candidates needs a decision a render can show.`
 - Draft no candidate for a decision the operator has not asked to make, since options everywhere spend their attention rather than saving it
+- If neither `frameboard` nor `bunx` is on PATH, stop: `❌ Frameboard not found. Install frameboard or bun and re-run.`
 
 ## Step 1: name the decision and the arms
 
@@ -28,26 +29,24 @@ The candidates live on the local design canvas, the surface `canon:canvas-board`
 
 Inside a live `plan-groundwork` track, renders land in the track's own `evidence/<slug>/renders/`, since a candidate render is evidence its decision file cites. Everywhere else they land in session scratch.
 
-## Step 2: draft the arms as frames on one canvas page
+## Step 2: draft the arms as frames on one page
 
-Every arm of a round sits as one frame on one canvas page, side by side. The operator judges that page, never a set of separate images compared from memory.
+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 canvas the way `canon:canvas-board` Step 1 states, unless this run already has. Note whether this run started the server, since Step 6 stops only a server this run started.
-2. Add the round's page with `canon canvas page add <page> --json` and record it on the run's list of pages. A name `canvas list` already shows is somebody else's, so take the next free suffix.
-3. Add each arm with `canon canvas frame add <page> arm-<id> --width <px> --height <px> --json`. Step 6's archive keys on the `arm-<id>` names.
-4. Write each arm's whole document to the `path` the add verb reported. From a linked worktree, take the heredoc route `canon:canvas-board` Step 3 gives for a main-root write.
-5. Lay the frames out in one row, in arm order, with `canon canvas frame move <page> arm-<id> --x <px> --y <px> --json`.
+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`.
+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.
 
-The `canvas-board` start reads `canon canvas list --json`, serves with `canon canvas serve --json` in the background unless the operator named an address that answers, and checks the shell's body holds a `<script` tag. A refused serve or a blank shell stops the run with its `reason`, and no file stands in for a canvas.
-
-Set each frame's width to the one the arm is judged at. A frame renders at its own layout width on the canvas and in a capture alike, so a layout decision needs no device toolbar.
+Set each frame's width to the one the arm is judged at. A frame renders at its own layout width on the board and in a capture alike, so a layout decision needs no device toolbar.
 
 ### What every frame carries
 
-Each frame carries its own label and follows the canvas theme, so the set reads as one comparison.
+Each frame carries its own label and follows the board theme, so the set reads as one comparison.
 
 - 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 canvas sets on each frame's root, so the theme toggle sets the whole set at once. A set spanning both themes cannot be compared.
+- 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.
 
 ### Default path and live app
@@ -55,8 +54,8 @@ Each frame carries its own label and follows the canvas theme, so the set reads
 A running app under decision takes the live-app branch, and every other decision takes the default path.
 
 - Live app: lift the rendered markup and link a copy of the built stylesheet rather than inlining, per `${CLAUDE_SKILL_DIR}/references/live-arms.md`
-- Default path: inline every style, script, and asset. A frame resolves nothing outside its own page folder, so a build step or network font silently drops out.
-- Default path: name a real font first in the stack, one the machine has or the frame embeds, such as the project's own family. A generic keyword such as `system-ui` resolves differently per machine.
+- Default path: inline every style, script, and asset. A frame resolves nothing outside its page folder and its project's `assets/`, so a build step or network font silently drops out.
+- Default path: name a real font first in the stack, one the board serves, the machine has, or the frame embeds. A generic keyword such as `system-ui` resolves differently per machine.
 
 The capture refuses a frame that would rewrap against a substitute font rather than ship a false comparison. A frame naming no font is refused on whatever the default resolves to.
 
@@ -73,18 +72,18 @@ 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
-canon canvas capture <page> --composite --json
+frameboard capture --page <page> --composite --root <board> --project picks --json
 ```
 
-- Point `--out` at `evidence/<slug>/renders/<page>.png` inside a live track, and leave the scratch default elsewhere. Step 6 archives the picked round alone.
-- Read the PNG's `path` off the record. The composite shows each frame in its default theme, so check the other theme on the live canvas.
-- A capture refusing on a font names the family it read. Take the repair `canon:canvas-board` Step 6 gives and capture again.
+- Point `--out` at `evidence/<slug>/renders/` inside a live track, and leave the board's default elsewhere. Step 6 archives the picked round alone.
+- Read each image's `path` off the record's `images`. The composite lands once per theme, so look at both.
+- A `font-missing` refusal names the family it read. Set that text's `font-family` to a named family the board serves or the machine has, never a generic keyword, and capture again.
 
-When `canon canvas capture` refuses for a missing browser binary, report it and name `bunx playwright install chromium` as the repair. Stop the canvas server if this run started it, then stop rather than describe an arm nobody has seen.
+When the capture refuses with `browser-not-found`, report it and name `bunx playwright install chromium` as the repair. End the serve command if this run started it, then stop rather than describe an arm nobody has seen.
 
 ### Handing over
 
-Hand over the address rather than a description. Emit the canvas link first on its own line, naming the page, then the PNG path on its own line.
+Hand over the address rather than a description. Emit the board link first on its own line, naming the page, then each PNG path on its own line.
 
 - A still answers how a thing looks and none of a hover, a scroll-linked position, or a pace, which the live frame does
 - Never report a visual result you have not looked at, since a claim about appearance with no render behind it is a guess
@@ -103,14 +102,7 @@ Put the choice to the operator through the structured question surface, since a
 
 Take no pick on the operator's behalf when two arms are both defensible and the difference is taste. That call is theirs, and a silent one is the failure this skill exists to prevent.
 
-Read `canon canvas selection --json` when the answer points at the canvas, such as "the selected one". Resolve it against the record's `page` as well as its `frame`, since every round reuses the `arm-<id>` names.
-
-| Selection                                                        | Reading                                        |
-| ---------------------------------------------------------------- | ---------------------------------------------- |
-| A frame on the current round's page                              | The pick                                       |
-| A frame on an earlier round's page                               | A revert, so name the round back before acting |
-| A fresh element inside a picked frame                            | A correction Step 5 carries by its `index`     |
-| `selection: null`, a page this run did not add, or `stale: true` | No answer, so ask again rather than guess      |
+Read the selection when the answer points at the board, such as "the selected one". `references/board.md` maps each record to a pick, a revert, a correction, or no answer.
 
 ## Step 5: loop on the pick
 
@@ -118,22 +110,22 @@ Read `canon canvas selection --json` when the answer points at the canvas, such
 2. Write fresh arms off the pick and return to Step 2 where the correction opens a new question. Revise the one arm's frame where it does not.
 3. Re-render, hand off again, and take the next answer.
 4. Repeat until the operator says it is right. A run stopping because the arms stopped differing has stopped early.
-5. Hold the real surface untouched across every iteration. Nothing outside the run's own canvas pages changes until the pick is final.
+5. Hold the real surface untouched across every iteration. Nothing outside the run's own board pages changes until the pick is final.
 
 ## Step 6: close
 
 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. 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.
+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.
+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 the path for the operator to remove. The pick is applied either way.
+9. Report each page 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 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 board is a second design nobody maintains.
 
 ## Reading a measurement
 
@@ -154,10 +146,11 @@ Cite these rather than restating them. A step reimplemented here rots against th
 - `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
 
-### Git and review
+### Git, review, and the board
 
-Commits, review, and the canvas mechanics each have an owner.
+Commits, review, and the board mechanics each have an owner.
 
 - `git-stage`, `git-pr`, and `git-followup` carry the commits and the pull request
 - `review-pr` and `review-address` run the review pass
-- `canon:canvas-board` carries the canvas start-and-check sequence, the main-root write route for a frame, and the selection and capture refusals
+- `session-worktree` carries the main-root write route for a frame written from a linked worktree
+- Frameboard carries the board itself, and `frameboard docs --json` prints its verbs, record shapes, content format, and refusals

package/claude/skills/pick-by-eye/references/board.md

@@ -0,0 +1,42 @@
+# 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.
+
+## 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.
+
+- Pass `--root <board> --project picks --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
+
+Run `frameboard docs --json` before writing the first frame. Its `contentFormat` fixes what a frame may hold and link, and its `exitCodes` name every refusal a verb can return.
+
+## Starting the board
+
+Serve in the background unless the operator named an address that answers, since the server runs until its command ends:
+
+```bash
+frameboard serve --root <board> --no-open --tokens <stylesheet> --json
+```
+
+- Take `<stylesheet>` from the lead of `canon/DESIGN.md`, which names it in a hand-written record
+- A lead naming a module, or no design document at all, means serving without `--tokens`. Say the frames render on the board's own tokens.
+- Read `url` and `reused` off the record rather than composing an address
+- `reused: true` means a server was already up, so this run did not start it and its close leaves it running
+- Report a refusal's `error.code` and stop, since no file stands in for a board
+
+## Reading the selection
+
+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 |
+
+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/pick-by-eye/references/live-arms.md

@@ -5,7 +5,7 @@ Read when the surface under decision is a running app rather than a static mocku
 ## Lift from the app
 
 - Dump the rendered markup of the surface under decision from the built page, after it has loaded, into a scratch file the run reads from. Strip scripts from the dump.
-- Copy the built stylesheet and fonts to the canvas page folder at the path each frame links, since a frame resolves only its own page. Each arm then differs from the shipped page only in what it names.
+- Copy the built stylesheet and fonts into the page folder or the project's `assets/`, since a frame resolves nothing else. Each arm then differs from the shipped page only in what it names.
 - Trim a large dump to the part the decision needs, and keep the wrapper classes intact so layout rules keyed to them still resolve.
 - Set each frame's `--width` to the content width the decision names rather than the window width, since a container query reads the frame.
 - Write copy an arm introduces with `write-human`, and take every other word from the dump.
@@ -13,7 +13,7 @@ Read when the surface under decision is a running app rather than a static mocku
 ## The frames
 
 - Generate the frames with a short script, one per round, so a shared change is one edit and a rerun.
-- Leave the theme to the canvas toggle, which sets the app's own `data-theme` switch on every frame's root. Name the attribute the stylesheet reads where it differs, as the toggle sets that one alone.
+- Leave the theme to the board toggle, which sets the app's own `data-theme` switch on every frame's root. Name the attribute the stylesheet reads where it differs, as the toggle sets that one alone.
 - Print each frame's measurement under it from a script in the frame, so the numbers the operator reads are the browser's.
 - Draw an arm that is a whole page or a route as one frame at that page's width, so it still sits beside the other arms on the round's page.
-- Name anything the canvas cannot reproduce, such as an asset whose colors follow the browser rather than the frame's theme, rather than fixing the frame around it.
+- Name anything the board cannot reproduce, such as an asset whose colors follow the browser rather than the frame's theme, rather than fixing the frame around it.