@erclx/canon 5.43.0 → 5.44.0

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

@@ -0,0 +1,59 @@
+---
+name: draw-figure
+description: Why a figure decides between Mermaid, an architecture view, and freehand SVG before drawing, and why the Mermaid path carries a render-verification loop
+---
+
+# Draw figure requirement
+
+## Gap
+
+Without this skill, a session asked for a figure reaches for whichever path it thought of first. A graph-shaped subject gets model-authored SVG coordinates nobody checked against a render, drifting from the hand-drawn look every other figure in the project carries. A subject that is not graph-shaped gets forced through Mermaid's node-and-edge model, producing a diagram that answers a different question than the one asked. Either failure ships a figure a reader cannot trust, and a figure exists only to be trusted at a glance.
+
+A teach lesson breaks the Mermaid path outright. The lesson letters its figures in a hand font the renderer cannot load, so the render sizes every label in a narrower fallback face and the lesson clips the text it actually shows. The check then reads the standalone image, rendered in that same fallback, and passes a figure the reader sees clipped. Both happened on one lesson, where every group title clipped mid-word and only a capture taken inside the lesson showed it.
+
+An architecture view asked for one at a time fails its own way. A session asked to refresh one view redraws every view beside it, so pictures nobody checked change in the same commit and the reviewer cannot tell which one the pass was about. It reaches for C4, state, or class diagrams that render differently in every viewer. A Mermaid source can satisfy every rule in the standard and still render as a picture asserting something false about the system, so a session that judges the source and calls it verified has spent the only signal a reader has on a picture nobody looked at.
+
+The color failure is the quiet one. Mermaid's own theme writes literal hex values, and a figure carrying one stops re-coloring itself the moment the host page switches its palette, which the figure standard's own accessibility bar rules out.
+
+## Must
+
+- Apply the standard's earn-its-place bar before drawing anything
+- Decide between the Mermaid path and the freehand path by whether the subject reduces to a graph, not by which is faster to produce
+- Draw an architecture view from its named source signal, inside `flowchart` and `sequenceDiagram`, and render it through the Mermaid path
+- Draw only the view the request names, leaving every other figure in the destination untouched
+- Draw a figure bound for a teach lesson freehand whatever its shape, since the lesson's hand font is one the renderer cannot measure
+- Verify a figure bound for a rendered page by capturing it inside that page, and fall back to the standalone render only where the destination has no page to load
+- Keep the scoped overflow style as the documented fallback for a clipped group title wherever the Mermaid path still runs
+- Render the Mermaid path with the hand-drawn look and the figure font stack, never with Mermaid's default look
+- Rewrite every literal color the renderer wrote into the custom property the host stylesheet defines
+- Read the Mermaid render back and judge it against what the figure means to say, rather than judging the source
+- Read the node labels by hand, since no hook checks inside a fence
+- Cite only code paths that exist in an architecture view's caption or prose
+- Wrap either path in a `<figure>` and `<figcaption>` and give it an accessible name
+
+## Must not
+
+- Force a non-graph-shaped subject through Mermaid, or route a graph-shaped one through freehand SVG coordinates a model authored by hand outside a teach lesson
+- Report a figure bound for a rendered page as verified from the standalone render alone
+- Ship a literal hex color on either path
+- Report a clean verification when the Mermaid render was skipped or a defect survived
+- Loop past two correction passes on a surviving defect
+- Commit a scratch render. Only the SVG that ships in the destination document survives
+- Redraw a figure the request did not name, or report one as drawn when it was left alone
+- Leave an architecture view as an unrendered fence
+
+## Guards
+
+- No subject given: stop, since nothing states what the figure has to show
+- No destination document given: stop, since the figure has nowhere to land
+- Subject does not clear the earn-its-place bar: stop rather than drawing decoration
+- An architecture view with no planning file and no folder structure to scan: stop, because nothing anchors it
+- Render fails for any reason: continue to the output and name the skipped check. A missing renderer degrades the loop rather than failing it.
+
+## Out of scope
+
+- Mermaid's own layout, budgets, and label rules for the fence itself: the mermaid standard, cited rather than restated here
+- A UI screen mockup: `canvas-board`
+- Design tokens and the visual system: `canvas-board`, which carries a picked direction into the design document
+- Implementation detail behind an architecture view, which belongs in a context entry the caption points at
+- Which lesson needs a figure and where it sits among the lesson's blocks: `teach-workspace`, which calls this skill to draw one

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

@@ -0,0 +1,85 @@
+---
+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`.
+metadata:
+  family: generate
+---
+
+# Draw figure
+
+Decide whether a requested figure reduces to a graph Mermaid can draw, is one of the architecture views, or needs freehand SVG, then draw it and verify what a reader will actually see.
+
+## Guards
+
+- If no subject is given, stop: `❌ No subject given. Name the relationship, boundary, path, or before-and-after this figure should show.`
+- If no destination document is given, stop: `❌ No destination given. Name the file this figure belongs in.`
+
+## Step 1: read sources
+
+Read these in parallel:
+
+- `${CLAUDE_SKILL_DIR}/references/figures.md`: when a figure earns its place, the render-first policy, wrapping and captioning, and the color and accessibility rules
+- `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`: formatting for the caption prose
+- The `write-human` skill: voice and rhythm for the caption prose
+
+## Step 2: does it earn its place
+
+Apply the standard's bar: a relationship, a boundary, a path, or a before-and-after that prose or a list cannot carry as well. Stop when it does not: `❌ <subject> reads fine as prose. A figure adds nothing here.`
+
+## Step 3: pick the path
+
+Take the first that matches, and state which path was picked and why in one sentence:
+
+1. **A teach lesson**, a page in a learning workspace's `lessons/` folder: the hand-drawn path, any shape. The renderer cannot load the lesson's hand font, so Mermaid labels measure narrow and clip.
+2. **An architecture view**, meaning the request names system context, components, request flow, data pipeline, or deployment: the architecture set, then the Mermaid path.
+3. **Graph-shaped**, meaning the relationship, boundary, or path is already what a flowchart or sequence diagram expresses: the Mermaid path.
+4. **Anything else**, a spatial or physical arrangement no flowchart reduces to: the hand-drawn path.
+
+The standard states this as a render-first policy rather than a ban on any tool-exported drawing, so outside a teach lesson a graph-shaped subject always routes through Mermaid even though that is itself an external renderer.
+
+## Step 4: draw
+
+Read the reference for the path Step 3 picked and follow it:
+
+- Architecture set: shape the view per `${CLAUDE_SKILL_DIR}/references/architecture-set.md`, then draw, render, and read back per `${CLAUDE_SKILL_DIR}/references/mermaid-path.md`
+- Mermaid path: read `${CLAUDE_SKILL_DIR}/references/mermaid-path.md`.
+- Hand-drawn path: read `${CLAUDE_SKILL_DIR}/references/hand-drawn.md`.
+
+## Step 5: wrap, caption, and verify
+
+- Wrap the drawing in a `<figure>` element with a `<figcaption>` naming what to take from the figure, never what it shows. Let it run wider than the surrounding prose column.
+- On the Mermaid path, run the read-back `mermaid-path.md` states before confirming.
+- On every path, confirm the figure still reads once every color and font it depends on is stripped to its fallback, per the standard's own working-figure bar.
+- On a rendered page, an HTML file a browser loads, the check that counts is the figure in the page, which Step 6 captures on either path. A markdown destination's whole check is the checks above.
+
+## Step 6: confirm and write
+
+Show the destination path, the decided path, and the full `<figure>` markup before writing. Confirm with the user, since the path decision and the render verdict are judgment calls with no diff to preview, then write the figure where the user named.
+
+When the destination is a rendered page, read the `## Capture in the page` section of `${CLAUDE_SKILL_DIR}/references/hand-drawn.md` and run it, on the Mermaid path as well as the hand-drawn one, within the same two correction passes the read-back allows.
+
+### Cleaning up
+
+Renders and captures under `.canon/tmp/figures/` are verification artifacts. Delete the scratch PNGs, the stamps beside them, and the JSON config once the checks confirm, since only the SVG ships, and keep the `.mmd` source a later refresh redraws from.
+
+## Output
+
+### Preview
+
+**Destination:** `<path>`
+**Render path:** `<mermaid | architecture | freehand>`, `<one-sentence reason>`
+
+```html
+<drafted figure markup></drafted>
+```
+
+### After confirmation
+
+Report the write in this shape.
+
+```plaintext
+✅ Drafted figure in <path>
+Render path: <mermaid | architecture | freehand>
+Verified <in page | as a standalone render>. <defect or skipped check, one line, omitted when clean>
+<Font not embedded: run `canon design css --figures` to ship Virgil and Excalifont. Omitted when the project already ran it.>
+```

package/claude/skills/{draft-figure → draw-figure}/references/architecture-set.md

@@ -1,11 +1,11 @@
 ---
 title: Architecture set
-description: The five architecture views with each one's question, source signal, and diagram type, the code-scan fallback, cited paths, and what moves to canon/context/ instead, read by draft-figure when a request names an architecture view
+description: The five architecture views with each one's question, source signal, and diagram type, the code-scan fallback, cited paths, and what moves to canon/context/ instead, read by draw-figure when a request names an architecture view
 ---
 
 # Architecture set
 
-`draft-figure` reads this file when the request names an architecture view. It shapes the subject, then the figure goes through `${CLAUDE_SKILL_DIR}/references/mermaid-path.md` like any other graph-shaped figure. The destination stays the one the user named.
+`draw-figure` reads this file when the request names an architecture view. It shapes the subject, then the figure goes through `${CLAUDE_SKILL_DIR}/references/mermaid-path.md` like any other graph-shaped figure. The destination stays the one the user named.
 
 ## The five views
 

package/claude/skills/{draft-figure → draw-figure}/references/hand-drawn.md

@@ -1,11 +1,11 @@
 ---
 title: Hand-drawn path
-description: Authoring a freehand SVG, its color and accessibility audit, and the in-page capture loop a rendered destination takes, read by draft-figure once a figure is drawn by hand
+description: Authoring a freehand SVG, its color and accessibility audit, and the in-page capture loop a rendered destination takes, read by draw-figure once a figure is drawn by hand
 ---
 
 # Hand-drawn path
 
-`draft-figure` reads this file when Step 3 routes a figure to a freehand drawing: a teach lesson whatever its subject, or a subject no flowchart reduces to.
+`draw-figure` reads this file when Step 3 routes a figure to a freehand drawing: a teach lesson whatever its subject, or a subject no flowchart reduces to.
 
 ## Draw
 

package/claude/skills/{draft-figure → draw-figure}/references/mermaid-path.md

@@ -1,11 +1,11 @@
 ---
 title: Mermaid path
-description: The hand-drawn render config, the SVG and PNG pair, the hex rewrite, the scoped overflow fallback, the label check, and the PNG read-back with its two-pass stop, read by draft-figure once a figure routes through Mermaid
+description: The hand-drawn render config, the SVG and PNG pair, the hex rewrite, the scoped overflow fallback, the label check, and the PNG read-back with its two-pass stop, read by draw-figure once a figure routes through Mermaid
 ---
 
 # Mermaid path
 
-`draft-figure` reads this file when Step 3 routes a figure through Mermaid, whether the subject is graph-shaped or an architecture view the architecture set already shaped.
+`draw-figure` reads this file when Step 3 routes a figure through Mermaid, whether the subject is graph-shaped or an architecture view the architecture set already shaped.
 
 ## Draft the fence
 

package/claude/skills/{draft-figure → draw-figure}/references/mermaid.md

@@ -13,7 +13,7 @@ Governs the Mermaid attribute wherever a fence is written, being direction and l
 
 Does not govern:
 
-- Which architecture view a figure draws and what question it answers: the `draft-figure` skill's architecture set
+- Which architecture view a figure draws and what question it answers: the `draw-figure` skill's architecture set
 - Language, word choice, punctuation, and formatting in the prose around a fence: `markdown.md`
 - Voice, rhythm, and sentence construction in that prose: the `write-human` skill
 - The mechanism behind any component a diagram draws: `context.md`

package/claude/skills/make-deck/REQUIREMENT.md

@@ -0,0 +1,44 @@
+---
+name: make-deck
+description: Why the skill draws a deck as HTML in the project's tokens inside its own folder, why the CLI owns the conversion, and why one render is read back before the deck is called done
+---
+
+# Make deck requirement
+
+## Gap
+
+Without this skill, a deck request turns into hand-built output. The session writes a deck into whatever path occurs to it, so a second deck overwrites the first and nothing lists either. It writes pptxgenjs code or hex colors per deck, so the deck takes neither the project's design nor any other deck's, and it invents attributes the converter does not read, so a section, a chart, or an entrance silently goes missing. Every slide comes out as a title over bullets, which is the shape that needs no decision and reads as a document rather than a deck.
+
+A first render shipped unread hands the audience the overlap, the overflow, and every element the converter fell back to a picture for, since markup that looks correct says nothing about the file it produces.
+
+## Must
+
+- Read the existing decks and the slide format from the CLI before drawing, and pick a deck name no listed deck carries unless the request names one
+- Write each deck into its own folder under the slides record folder, one HTML file per slide in filename order
+- Draw with the project's custom properties so the deck takes the project's design
+- Vary the composition across the deck rather than repeating one shape
+- Size content to fit the slide frame, keeping titles short and lines tight
+- Shell out to the render command for the deck itself
+- Read every fallback and refusal the render reports, run one QA pass over the rendered images, and fix what both report
+
+## Must not
+
+- Hardcode a deck name, an attribute, or a chart type, which goes stale the moment the CLI changes
+- Reimplement the conversion, the master, or the packaging, which the CLI owns
+- Write a deck into the shared layouts folder, which is never listed as a deck
+- Invent token values when the project has no token stylesheet
+- Write centered body text or content that overflows a slide
+- Loop on aesthetics past a single fix pass
+
+## Guards
+
+- No token stylesheet: draw the deck anyway and say it renders unstyled.
+- Image conversion tools missing: skip the image pass and say so. Do not fail the render over a verification step.
+
+## Out of scope
+
+- Converting HTML to PowerPoint, which the CLI owns end to end
+- The project's palette and faces, which live in its token stylesheet rather than in the slides
+- Writing the content the deck is about, which the caller brings
+- Drafting a deck as a canvas page, which waits on a measurement of that authoring surface
+- Recording a demo, which `script-screencast` owns

package/claude/skills/make-deck/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: make-deck
+description: Draws a deck as HTML slides in the project's own design, one folder under `.canon/slides/` per deck, then renders it to an editable PowerPoint file via `canon slides render`. Use when asked to "draft slides", "make a deck", "build a presentation", "turn this into slides", or "render the deck". Holds the deck design rules. Do NOT reimplement the conversion. The CLI owns layout into PowerPoint shapes, the master, and packaging. Assumes the `canon` CLI is on PATH.
+metadata:
+  family: generate
+---
+
+# Make deck
+
+Draw each slide as an HTML file in a deck folder, then shell out to `canon slides render`. The CLI lays every slide out in a browser and rebuilds it as editable PowerPoint shapes. This skill owns the content, the slide markup, and the design choices the markup encodes.
+
+## Read the decks and the format
+
+Run the list first, then read the format. Never hardcode a deck name, an attribute, or a chart type.
+
+```bash
+canon slides list --json 2>/dev/null
+```
+
+The list returns one row per deck, carrying its `name`, `title`, slide count, and `path`. When the request names a deck the list holds, edit that folder. Otherwise pick a new kebab-case name no row carries.
+
+Read `${CLAUDE_SKILL_DIR}/references/deck.md`. It states what `deck.json` holds, what each slide declares on its `<body>`, the motion attributes, speaker notes, and charts. Each refusal prints as a `✗` line from the render.
+
+## Draw the deck
+
+A deck folder sits at `.canon/slides/<deck>/` from the project root, and holds:
+
+- One `.html` file per slide, rendered in filename order. Number them with a zero-padded prefix, such as `01-cover.html`, so a slide inserted later sorts where it belongs.
+- `deck.json`, optional, for the title, the header and footer bands, slide numbers, the mark, and embedded faces.
+- `assets/` for images the slides reference by a relative path.
+
+Never write a slide into `.canon/slides/layouts/`. That folder holds the project's shared layouts and is never listed as a deck.
+
+Each slide is a full HTML document laid out at 1280 by 720 CSS pixels. Position its blocks absolutely or with a flex or grid container sized to that frame, and keep every element inside it.
+
+## Design rules
+
+The render injects the project's token stylesheet ahead of each slide's own styles, so the deck takes the project's design rather than the toolkit's.
+
+- Use the project's custom properties, such as `var(--color-accent)`, for every color, face, and spacing value, read from `.claude/design/base.css` and overrides under `.claude/design/project/`
+- When neither exists, say the deck renders unstyled rather than inventing values to cover it
+- Leave the `--color-*` roles to the stylesheet. The master reads its colors off the first slide's `<html>`, so a slide computing its own `--color-text` is reported, since the bands keep the master's.
+- Vary the composition across slides. Never repeat a title over bullets on every slide. Reach for columns, a row of large numbers, a grid of cards, a chart, a pull quote, and section dividers.
+
+### Fit and shapes
+
+Text and shapes have to survive the conversion.
+
+- Keep titles short and lines tight, so text fits its box at the size the design sets rather than overflowing the frame.
+- Never write centered body text.
+- Prefer CSS the converter maps to native shapes. An unmappable property is drawn as a picture and reported on stderr, so a slide full of gradients and filters stops being editable.
+
+## Render
+
+Shell out to the CLI. It writes the deck and reports the path.
+
+```bash
+canon slides render <deck>
+```
+
+With one deck in the project the name can be left out. The render refuses with the deck list when there are several. Pass `--open` to open the deck, and `--mirror <dir>`, or set `CANON_SLIDES_MIRROR`, to copy it into a synced folder.
+
+Read every `✗` line the render prints. A picture fallback, a refused link, chart, or effect, and a missing token each leave the deck written with that piece degraded or left out.
+
+## QA loop
+
+Run this once after the first render, then stop.
+
+1. Convert the deck with `soffice --headless --convert-to pdf <deck>.pptx`, then `pdftoppm -r 90 -png <deck>.pdf slide`. If either is missing, skip the image pass and say so rather than fail the render.
+2. Open and inspect every rendered image in this session, checking each slide for overlap, overflow, low contrast, and empty regions.
+3. Fix the reported issues and the `✗` lines in the slide files once, re-render, and stop. Do not loop indefinitely on aesthetics.
+
+## Response
+
+After rendering, report:
+
+- The deck folder, the slide count, and the written `.pptx` path
+- Whether the project's token stylesheet was found
+- Each `✗` line the final render printed, or that it printed none
+- Any QA issues found and what changed, or that the deck passed clean

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

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

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

@@ -1,6 +1,6 @@
 ---
 name: markdown-craft
-description: Carries the format and structure rules for markdown, being headings, the density limits, paragraph and list shape, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording, and runs the audit after an edit. Use before a substantial markdown edit, when writing a README, a doc, a skill body, or any `.md` file, or when asked "what are the markdown rules" or "which characters are banned". Do NOT use for voice, rhythm, or word choice, which is `write-human`, or for a Mermaid fence or figure, which is `draft-figure`.
+description: Carries the format and structure rules for markdown, being headings, the density limits, paragraph and list shape, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording, and runs the audit after an edit. Use before a substantial markdown edit, when writing a README, a doc, a skill body, or any `.md` file, or when asked "what are the markdown rules" or "which characters are banned". Do NOT use for voice, rhythm, or word choice, which is `write-human`, or for a Mermaid fence or figure, which is `draw-figure`.
 metadata:
   family: answer
 ---
@@ -14,4 +14,4 @@ Run `canon markdown audit <path>` after the edit, and fix every ban and density
 ## Routes
 
 - Voice, rhythm, sentence construction, and information density: load `write-human`.
-- A Mermaid fence or a figure: load `draft-figure`, since the audit skips every line inside a fence.
+- A Mermaid fence or a figure: load `draw-figure`, since the audit skips every line inside a fence.

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

@@ -0,0 +1,86 @@
+---
+name: pick-by-eye
+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
+
+## Gap
+
+Without this skill, a session facing a decision nobody can settle from a diff:
+
+- Describes two options in prose and asks the operator to choose. The operator decides by looking, so a described option is not an option and the answer that comes back is arbitrary.
+- Produces one answer for a decision that was taste, so the operator never sees what they were choosing between and the call is taken silently by whoever wrote the code.
+- Reports that a candidate reads well without rendering it, so the claim rests on the markup having been written rather than on the page having been seen.
+- Hands over one image per arm, which asks the operator to hold the differences in memory rather than showing them. The comparison is the artifact and a set of separate files is not one.
+- Varies three properties at once across the arms, so the pick cannot say which difference decided it and the next iteration guesses.
+- Writes the candidates into the real surface, so the losing arms have to be unpicked out of a tree the operator has not judged yet, and a variant left behind a flag becomes a second design nobody maintains.
+- Stops the loop when the arms stop differing rather than when the operator says the pick is right, which ends the run on the session's own patience.
+- Reads a driver record as a verdict and drops an arm on it. `canon drive` reports findings and never gates, so a run filtering the arms on a probe reading has made a claim the probe catalog has not earned.
+- Reads a color without compositing its alpha, samples a round control at the corner of its bounding box, or confirms a panel's dimensions while it sits above the viewport. Each reads as a passing measurement about something no reader sees.
+- Meets a machine with no browser binary and reports on the arms anyway, since nothing in the default flow separates a render that failed from one that was never attempted.
+- Hand-writes a mockup of a surface a running app already serves, which drifts from what ships by a few pixels and a few words the moment the app's own markup or stylesheet moves on.
+- Varies a property the decision is not about, which satisfies the one-property rule and produces a set differing in the layer a reader notices least. Five palettes over one identical page read as five skins of one design, and the operator rejected the whole set on sight.
+- Renders each arm in whatever theme it happens to carry, so a set spanning both themes cannot be compared without the operator toggling every arm and holding the earlier ones in memory.
+- Looks at a render to confirm it came out rather than to judge whether it is worth showing, which satisfies the rule against reporting an unseen result and still hands over weak work.
+- Writes the run's renders to a scratch path outside the record that cites them, leaving the folder holding source markup and none of the images, so the judgment is unreachable to everyone except the session that made it.
+- Narrows the page onto the picked arm in place on each iteration, so every earlier round is overwritten and a later pass cannot see what was already rejected.
+- Names no layer at all, since the instruction to name one carries no catalog to name from and nothing reports the omission. Four consecutive rounds against one page each varied a property at the top layer while the defect sat two below it, and three of the four changed nothing the operator could see.
+- Judges a lower layer through a finished higher one, so an operator asked about composition looks at the palette instead and answers about that.
+- Hands over the combined page alone for a decision about layout, where every arm sits in a column while the media queries answer to the whole window, so no arm is ever seen at its own viewport and a fault that appears only narrower survives the pick.
+- Rebuilds a navigation harness by hand on a run with several rounds, since each round writes its own folder and nothing reaches all of them from one address. Two design tracks hand-wrote the same page picker and theme toggle.
+- Meets a session with no canvas server and drafts into a file instead, which leaves the operator a second surface to open and the run a second close to remember. The canvas is the one drafting surface, so a run without one starts it rather than falling back.
+- Puts the pick question with no address in its output, after capturing the page and reading the image back. The operator then has to ask for a served page before they can look, so the question goes unanswered or gets answered blind.
+- Sets the theme on an arm that persists its own and reads it back on load, so the control reports one theme while the arm renders the other and the set is compared across two.
+
+## Must
+
+- Produce three to five arms with the shipping state among them, each carrying an id, a label, and what the arm costs.
+- Draft every arm of a round as one self-contained frame on one canvas page and capture that page once as a composite, so the comparison arrives as one image, except where the surface under decision is a running app: there each frame links a copy of the built stylesheet inside the page folder rather than inlining it, per `references/live-arms.md`.
+- Start the canvas when none is serving, and stop on a canvas that refuses to start or answers with a blank shell, rather than drafting into a file.
+- Emit the layer in the run's own output, drawn from the catalog `design-taste` fixes rather than from a word invented per run, and vary the arms at that layer alone. A layer held privately is one nothing can report missing, which is how the instruction went unfollowed while every round passed its own rules.
+- Grey-box the set when the declared layer sits below typography, and say the set is grey-boxed when handing it over, so the operator reads a flat page as the question rather than as unfinished work.
+- Theme every arm off the attribute the canvas toggle sets on each frame, so one control sets the whole set and the comparison holds still while the operator reads it, and give no arm a script that reads a stored preference back on load over the toggle.
+- Give each frame the width the arm is judged at, since a frame renders at its own layout width and answers how an arm behaves at a width where a column on a shared page could not.
+- Judge each render against a stated bar before handing it over, name the weakest thing on the page, and fix it where that sentence would embarrass the work.
+- Write each iteration to its own canvas page rather than narrowing the previous one in place, so every earlier round stays openable from the canvas page list.
+- Write the run's renders inside the record that cites them wherever one exists, and reserve the scratch path for inputs that are re-runnable and cited by nothing.
+- Render before reporting on any arm, and report a missing browser binary as a refusal naming the repair rather than describing an arm nobody has seen.
+- Take the pick through the structured question surface, with the recommendation ranked first and marked, and every option carrying its cost. Read the canvas selection only to resolve an answer that points at it, and treat an empty or stale selection as no answer.
+- Keep every write inside the run's own canvas pages until the pick is final.
+- Apply the winning arm in one change.
+- Capture every arm from the round the pick came from, whichever round that is, as an image named for its frame before deleting the run's pages, rather than discarding the losing arms with them.
+- Delete only the canvas pages the run itself added, recorded as it adds them, and stop only a canvas server the run itself started.
+- Resolve the archival capture's destination against the main worktree root, never against a linked worktree the run happens to be building in.
+- Put the candidates on the canvas on every run, whatever the decision's layer, and emit the canvas link ahead of the first pick question, so the operator can open the page the question is about and a still is never the only address.
+
+## Must not
+
+- Take the pick where two arms are both defensible and the difference is taste. That call is the operator's, and taking it silently is the failure this skill exists to prevent.
+- Draft candidates for a decision the operator has not asked to make. Each arm costs a render, and a run offering options everywhere spends their attention rather than saving it.
+- Restate the mechanics of the canvas, the render, or the probes. `canon canvas` and `canon drive` own those and their help text is the source, so a second copy here hands one case two answers.
+- Read a `canon drive` finding as a gate over the arms.
+- Fire on a request that already names one answer.
+
+## Guards
+
+The refusal strings sit in the body, since the runtime loads that file and ignores this one. Two conditions stop a run: a request naming one answer and asking for it to be built, and a decision with no visible form for a render to show.
+
+## Out of scope
+
+- `plan-feature` plans the work once the answer is settled, and declares the pull request boundary its plan carries. This produces the answer to pick from and stops before the plan.
+- `ux-audit` reads source to find roughness and reports it. This takes its input from the operator and changes nothing until they pick.
+- `ux-measure` measures what a running interface costs to paint. This measures whatever a visual claim depends on, which is usually geometry or contrast rather than cost.
+- `ui-checklist` writes what to look at on a change already made. This runs before there is a change to look at.
+- `script-screencast` scripts a recording of something already built. This has nothing built yet.
+- `canon canvas` owns the page, the frames, the selection, the address, and the render, and `canon drive` owns the probes. Both are invoked rather than reimplemented.
+
+### What did not travel
+
+This descends from a project-local skill whose interactive half was written against one repository. Three of its capabilities do not travel, and the two verbs above are what stands in their place:
+
+- An arm switcher compiled into the project's own page, driven by a query parameter. A canvas page of frames replaces it, which puts the arms on the canvas rather than in the source and removes the call site a run had to remember to delete.
+- A copy cycle keyed to canonical page text held in a second repository. No toolkit surface has that shape, so a project holding one owns the second edit and this skill states nothing about it.
+- A walker that reads every control on every page and groups them by treatment. `canon drive` probes one page and reports findings, so a sweep across every surface of a site is out of reach here and a run needing one measures by hand.
+
+The capture mechanics traveled with a change of owner rather than being lost. They sat in a project-local path-scoped rule that fired whether or not the skill ran, and `canon canvas capture` owns them here, which is why this file bars restating them rather than naming a rule to defer to.

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

@@ -0,0 +1,161 @@
+---
+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`, to write what to look at on a change already made, which is `ui-checklist`, or to script a recording, which is `script-screencast`.
+metadata:
+  family: decide
+---
+
+# Pick by eye
+
+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.
+
+## 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
+
+## Step 1: name the decision and the arms
+
+1. State the decision in one sentence, naming what changes between arms and what stays fixed.
+2. Emit the design read in the run's output, in the form `design-taste` fixes, taking the layer from its ordered catalog. The arms differ at that layer, and a missing read is visible.
+3. Derive a kebab slug from that sentence. The first round's page is `<slug>`, and Step 5 names later rounds `<slug>-2`, `<slug>-3`, and so on.
+4. Write one arm per candidate, each carrying an id, a label, and what the arm costs. An arm with no stated cost is not an option.
+5. Make the current state arm `0`, so the baseline is a candidate rather than an absence. A decision with nothing shipped yet says so and starts at arm `1`.
+6. Stop at three to five arms. Two is a comparison the operator can hold in prose, and past five the pick stops being a look and becomes a sort.
+
+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
+
+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.
+
+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`.
+
+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.
+
+### What every frame carries
+
+Each frame carries its own label and follows the canvas 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.
+- 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
+
+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.
+
+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.
+
+### What varies
+
+Vary one property across the arms, since a pick cannot say which of three differences decided it.
+
+- Vary the property the decision is about. Holding composition fixed and varying color produces five skins of one design, and a palette cannot be picked ahead of the composition it serves.
+- Grey-box the arms when the declared layer sits below typography, per `design-taste`, and say the set is grey-boxed when handing it over
+- Do not grey-box a set judged at composition that carries a finished palette, since the operator looks at the higher layers instead of the question
+
+## Step 3: render and hand off
+
+Render the page and look at what came back before handing anything over:
+
+```bash
+canon canvas capture <page> --composite --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.
+
+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.
+
+### 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.
+
+- 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
+- Look to judge rather than to confirm. Name the weakest thing on the page in a sentence, fix it where that sentence would embarrass the work, and say what remains.
+
+## Step 4: take the pick
+
+Put the choice to the operator through the structured question surface, since a call the operator's preference decides always routes through it rather than through prose.
+
+- Emit the link ahead of the question call and again in the question's text, since some surfaces render the card alone
+- One option per arm, labeled with the arm's id and carrying its cost as the description
+- Rank the recommendation first and mark it `(Recommended)`
+- Author the real arms only. The surface appends its own free-text and reopen escapes, and a duplicate is rejected.
+
+### Taking the answer
+
+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      |
+
+## Step 5: loop on the pick
+
+1. Add each iteration as its own page, recorded on the run's list. An overwritten page cannot be reopened, and the losing round stops a correction re-proposing a rejected arm.
+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.
+
+## 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. Capture the picked round's frames with `canon canvas capture <page> --out <archive-dir> --json`. Each lands as `arm-<id>.png`, keeping the losing arms as a revert record.
+4. Resolve `<archive-dir>` as `.canon/picks/<slug>/` against the main worktree root, since shared session scratch resolves there rather than in a linked worktree.
+5. Delete every page folder on the run's list from under the `content` folder `canon canvas list --json` reports. Touch no page the run did not add, whatever its name.
+6. Stop the canvas server if this run started it, and leave one the operator started running.
+7. Leave the renders in a live track's `evidence/<slug>/renders/`, since `plan-groundwork` treats evidence as durable.
+8. Report each page whose delete is refused, naming the path for the operator to remove. The pick is applied either way.
+9. Report every surface that changed, each on its own line, name the winning arm by its id and its cost, and report the archive path.
+
+The picked round is the final one unless Step 4 resolved a revert. Archiving any other page lets item 5 delete the winning arm with nothing kept, and a variant left on the canvas is a second design nobody maintains.
+
+## 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.
+
+- Composite alpha before reading a color. A `color-mix` toward transparent resolves to channels plus an alpha, and reading them as opaque reports a color nobody sees.
+- Sample inside the shape. A patch at a bounding box corner misses a round control and reads the page behind it.
+- Ask whether a reader would see the thing. A panel sized a healthy 1517 by 639 passed every size check while sitting 1868px above the viewport.
+
+`canon drive` reports findings and never gates. Read its record as evidence for the operator rather than as a filter over the arms, since the probe catalog has not earned the right to drop one.
+
+## What this delegates
+
+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-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
+
+Commits, review, and the canvas 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