@erclx/canon 5.24.0 → 5.26.0

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

@@ -1,6 +1,6 @@
 ---
 name: draft-figure
-description: Why a figure decides between Mermaid and freehand SVG before drawing, and why only the Mermaid path carries a render-verification loop
+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
 ---
 
 # Draft figure requirement
@@ -11,18 +11,24 @@ Without this skill, a session asked for a figure reaches for whichever path it t
 
 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, the same verification `draft-diagram` runs for the architecture surface
+- 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
@@ -33,16 +39,21 @@ The color failure is the quiet one. Mermaid's own theme writes literal hex value
 - 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
 
-- The toolkit's own `.canon/diagrams/` architecture surface, which shares no code, font, or visual language with this convention: `draft-diagram`
 - Mermaid's own layout, budgets, and label rules for the fence itself: the mermaid standard, cited rather than restated here
 - A UI wireframe or screen mockup: `draft-doc`
+- Design tokens and the visual system: `design-extract`
+- 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/draft-figure/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: draft-figure
-description: Drafts one hand-drawn figure for a document, deciding whether the subject is Mermaid-shaped 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 either 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", or "draw this relationship as a figure". Do NOT use for the toolkit's own `.canon/diagrams/` architecture surface, which is `draft-diagram`, or for a UI wireframe, which is `draft-doc`.
+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 wireframe, which is `draft-doc`, or for design tokens, which is `design-extract`.
 ---
 
 # Draft figure
 
-Decide whether a requested figure reduces to a graph Mermaid can draw, or needs freehand SVG, then draw it and verify what a reader will actually see.
+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
 
@@ -17,7 +17,6 @@ Decide whether a requested figure reduces to a graph Mermaid can draw, or needs
 Read these in parallel:
 
 - `${CLAUDE_SKILL_DIR}/../../standards/figures.md`: when a figure earns its place, the render-first policy, wrapping and captioning, and the color and accessibility rules
-- `${CLAUDE_SKILL_DIR}/../../standards/mermaid.md`: direction and layout, node and edge budgets, the accessibility fields, and how a render is verified, for the Mermaid path
 - `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: formatting for the caption prose
 - The `write-human` skill: voice and rhythm for the caption prose
 
@@ -25,74 +24,48 @@ Read these in parallel:
 
 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: decide the render path
+## Step 3: pick the path
 
-- **A teach lesson**, meaning the destination is a lesson page in a learning workspace's `lessons/` folder: draw it through Step 5 whatever its shape. The lesson letters its figures in a hand font the renderer cannot load, so a Mermaid render measures its labels in a narrower face and the lesson clips them.
-- **Graph-shaped**, meaning the relationship, boundary, or path is already what a flowchart or sequence diagram expresses: draw it through Step 4.
-- **Not graph-shaped**, meaning the subject is a spatial or physical arrangement no flowchart reduces to: draw it through Step 5.
+Take the first that matches, and state which path was picked and why in one sentence:
 
-Take the first that matches, and state which path was picked and why in one sentence. 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.
+1. **A teach lesson**, meaning the destination is a lesson page in a learning workspace's `lessons/` folder: the hand-drawn path, whatever the subject's shape, an architecture view included. The lesson letters its figures in a hand font the renderer cannot load, so a Mermaid render measures its labels in a narrower face and the lesson clips them.
+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.
 
-## Step 4: the Mermaid 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.
 
-- Draft the fence against `mermaid.md`: direction, node and edge budgets, `accTitle`/`accDescr`, and quoted labels.
-- Render it with the hand-drawn look and the figure font stack, writing scratch files under `.canon/tmp/figures/`:
+## Step 4: draw
 
-```bash
-mkdir -p .canon/tmp/figures
-cat <<'EOF' >.canon/tmp/figures/<slug>.json
-{"look": "handDrawn", "themeVariables": {"fontFamily": "Virgil, Excalifont, cursive"}}
-EOF
-bunx -y @mermaid-js/mermaid-cli -i .canon/tmp/figures/<slug>.mmd -o .canon/tmp/figures/<slug>.svg -c .canon/tmp/figures/<slug>.json
-bunx -y @mermaid-js/mermaid-cli -i .canon/tmp/figures/<slug>.mmd -o .canon/tmp/figures/<slug>.png -c .canon/tmp/figures/<slug>.json
-```
-
-Render both formats in one pass: the SVG is what ships inside the `<figure>`, and the PNG is what Step 6 reads back, since an SVG's markup carries no recoverable spatial meaning the way `draft-diagram` Step 5 already states for the architecture surface.
-
-Use `bunx` when bun is available, falling back to `npx -y @mermaid-js/mermaid-cli ...` otherwise.
-
-- Rewrite every stroke, fill, and text color the renderer wrote as a literal hex value into the custom property the host stylesheet defines, per the standard's color rule. Mermaid's own theme has no notion of a custom property, so this is a source edit made to the rendered SVG, not a config option.
-- Expect a group title or a long label to clip once the destination shows it in the hand font, since the renderer sized its box in a fallback face.
-- When the in-page check shows a clipped title, add a `<style>` inside the SVG, scoped to that SVG's own id, that sets `overflow: visible` on the clipped label's `foreignObject` and centers the label within it, so the wider text spills past both edges evenly. The style hides the mismatch for a title and does nothing for a node label crowding its box, which takes a shorter label instead.
-- Check whether the project ran `canon design css --figures`. The figure and figcaption styling ships unconditionally either way, but that flag alone embeds the Virgil and Excalifont font files. Without it, the figure falls back to the browser's own generic `cursive` face rather than the intended hand-drawn font, and Step 7's output names that gap when the flag was not passed.
-
-## Step 5: the freehand path
+Read the reference for the path Step 3 picked and follow it:
 
-- Author the SVG by hand: plain shapes and lines authored directly in the markup.
-- Follow the standard's `## Color and accessibility` section for every fill, stroke, and accessible name.
+- Architecture set: read `${CLAUDE_SKILL_DIR}/references/architecture-set.md` to shape the view, then `${CLAUDE_SKILL_DIR}/references/mermaid.md` to draw and render it. The architecture branch always renders and reads back. An unrendered fence is not a figure.
+- Mermaid path: read `${CLAUDE_SKILL_DIR}/references/mermaid.md`.
+- Hand-drawn path: read `${CLAUDE_SKILL_DIR}/references/hand-drawn.md`.
 
-There is no external render to verify a freehand drawing against before it is written. The check here is the stroke-and-fill audit above and a read of the markup against what the subject means to show, done once rather than looped. Hand-placed coordinates can drift out of line where a layout engine would not, so a freehand figure bound for a rendered page also takes Step 7's in-page capture.
-
-## Step 6: wrap, caption, and verify
+## 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, read the rendered PNG back and judge it against what the figure means to say, the same check `draft-diagram` Steps 5 and 6 run for the architecture surface. Fix the mermaid source and re-render on a defect. Stop after two correction passes. When a defect survives, keep the figure and name the defect in the output rather than reporting a false verification.
-- On either 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.
-- When the render fails for any reason, no browser engine, no network, no package manager, continue to Step 7 and name the skipped check. A missing renderer degrades the loop rather than failing it.
-- When the destination is a rendered page, an HTML file a browser loads, the check that counts is the figure inside that page, which Step 7 runs once the figure is written. The standalone PNG is measured in the renderer's own fonts and can read clean while the page clips it. A markdown destination has no page to load, so the standalone check above is the whole check there.
+- On the Mermaid path, run the read-back `mermaid.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.
+- When the destination is a rendered page, an HTML file a browser loads, the check that counts is the figure inside that page, which Step 6 captures once the figure is written, on either path. A markdown destination has no page to load, so the checks above are the whole check there.
 
-## Step 7: confirm and write
+## Step 6: confirm and write
 
-Show the destination path, the decided render path, and the full `<figure>` markup before writing. Confirm with the user, since the graph-shaped decision and the render verdict are judgment calls with no diff to preview either against.
+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 either against.
 
 Write the figure into the destination document at the location the user named.
 
-When the destination is a rendered page, capture the figure inside it and read the capture against what the figure means to say:
-
-```bash
-canon capture <destination> --selector figure --out .canon/tmp/figures/
-```
-
-Narrow the selector to this figure, such as by an id on its `<figure>`, when the page carries more than one. Fix a clipped label, a misaligned shape, or an arrow that misses its target in the destination and capture again, within the same two correction passes Step 6 allows. A clipped group title on the Mermaid path takes the scoped overflow style Step 4 states. When the capture fails, keep the figure and name the skipped check in the output, the same way Step 6 treats a failed render.
+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.
 
-Renders and captures under `.canon/tmp/figures/` are verification artifacts, and the scratch PNGs, the stamps the capture writes beside them, and the JSON config are deleted once the checks confirm, since only the SVG ships.
+Renders and captures under `.canon/tmp/figures/` are verification artifacts, and the scratch PNGs, the stamps the capture writes beside them, and the JSON config are deleted once the checks confirm, since only the SVG ships. Keep the `.mmd` source, which is what a later refresh redraws from.
 
 ## Output
 
 ### Preview
 
 **Destination:** `<path>`
-**Render path:** `<mermaid | freehand>`, `<one-sentence reason>`
+**Render path:** `<mermaid | architecture | freehand>`, `<one-sentence reason>`
 
 ```html
 <drafted figure markup></drafted>
@@ -102,7 +75,7 @@ Renders and captures under `.canon/tmp/figures/` are verification artifacts, and
 
 ```plaintext
 ✅ Drafted figure in <path>
-Render path: <mermaid | freehand>
+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/references/architecture-set.md

@@ -0,0 +1,35 @@
+---
+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
+---
+
+# 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.md` like any other graph-shaped figure. The destination stays the one the user named.
+
+## The five views
+
+Draw the view the request names. Each answers one question and is drawn from one source signal:
+
+| View           | Question it answers                                     | Source signal                                     | Diagram type                         |
+| -------------- | ------------------------------------------------------- | ------------------------------------------------- | ------------------------------------ |
+| System context | Who uses the system, what it talks to, where it ends    | `canon/REQUIREMENTS.md`                           | `flowchart TB`                       |
+| Components     | The layered structure inside the boundary               | `canon/ARCHITECTURE.md`                           | `flowchart TB` with `subgraph` lanes |
+| Request flow   | A request lifecycle, an agent loop, or an actor handoff | the entry point and its handlers                  | `sequenceDiagram`                    |
+| Data pipeline  | Retrieval, ranking, queues, or ETL                      | the pipeline's modules                            | `flowchart TB`                       |
+| Deployment     | Hosts, services, and infrastructure config              | deploy config, compose files, infrastructure code | `flowchart TB`                       |
+
+System context is the only view that draws the world outside the boundary, and the one a reader outside the team opens first, so assume no knowledge of the repository there.
+
+Stay inside `flowchart` and `sequenceDiagram`. C4, state, ER, and class diagrams render inconsistently across viewers.
+
+## Sources
+
+- Read `canon/REQUIREMENTS.md`, `canon/ARCHITECTURE.md`, `CLAUDE.md`, and the language manifest (`package.json`, `pyproject.toml`, `Cargo.toml`) when present, plus the top-level folder layout through `ls`. Do not recurse speculatively.
+- When neither planning file exists and no folder structure names a boundary, stop: `❌ No source signal for <view>. Add canon/ARCHITECTURE.md or run inside a project folder.`
+- When the view came from a code scan rather than planning prose, open the caption with `Source: code.` and add `Fidelity is lower than prose-driven figures. Verify against the project's intent.`
+
+## Caption and prose
+
+- Name one or two code paths a reader can open, in the caption or the prose beside the figure. Cite only paths that exist and spell each one exactly, since a reader deciding whether the figure still holds starts by opening them.
+- Keep implementation detail out of the figure: function names and call signatures, library versions, config keys and environment variable names, retry counts and timeouts, and workarounds needing more than a sentence. That detail belongs in a `canon/context/` entry, which the caption points at by path when a reader needs the mechanism.

package/claude/skills/draft-figure/references/hand-drawn.md

@@ -0,0 +1,31 @@
+---
+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
+---
+
+# 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
+
+- Author the SVG by hand: plain shapes and lines authored directly in the markup.
+- Follow the `## Color and accessibility` section of `${CLAUDE_SKILL_DIR}/../../standards/figures.md` for every fill, stroke, and accessible name.
+
+There is no external render to verify a freehand drawing against before it is written. The check here is the stroke-and-fill audit above and a read of the markup against what the subject means to show, done once rather than looped. Hand-placed coordinates can drift out of line where a layout engine would not, so a freehand figure bound for a rendered page also takes the in-page capture below.
+
+## Capture in the page
+
+When the destination is a rendered page, an HTML file a browser loads, capture the figure inside it once it is written and read the capture against what the figure means to say:
+
+```bash
+canon capture <destination> --selector figure --out .canon/tmp/figures/
+```
+
+- Narrow the selector to this figure, such as by an id on its `<figure>`, when the page carries more than one.
+- Fix a clipped label, a misaligned shape, or an arrow that misses its target in the destination and capture again. Stop after two correction passes.
+- When the capture fails, keep the figure and name the skipped check in the output.
+
+A Mermaid figure bound for a rendered page takes this same capture, since its standalone PNG is measured in the renderer's own fonts and can read clean while the page clips it. A clipped group title there takes the scoped overflow style `${CLAUDE_SKILL_DIR}/references/mermaid.md` states.
+
+A markdown destination has no page to load, so the read of the markup, or of the standalone render on the Mermaid path, is the whole check there.

package/claude/skills/draft-figure/references/mermaid.md

@@ -0,0 +1,55 @@
+---
+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
+---
+
+# 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.
+
+## Draft the fence
+
+- Draft the fence against `${CLAUDE_SKILL_DIR}/../../standards/mermaid.md` for direction, node and edge budgets, `accTitle` and `accDescr`, and quoted labels. Do not work the layout or the budgets from memory.
+- Read every node and subgraph label against the banned characters `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` lists. The audit hook skips every line inside a fence, so a label carrying a banned character passes silently while the same character in the caption is caught. Reading the labels is the only gate they have. A colon works as a replacement inside a label.
+
+## Render
+
+Render with the hand-drawn look and the figure font stack, writing scratch files under `.canon/tmp/figures/`:
+
+```bash
+mkdir -p .canon/tmp/figures
+cat <<'EOF' >.canon/tmp/figures/<slug>.json
+{"look": "handDrawn", "themeVariables": {"fontFamily": "Virgil, Excalifont, cursive"}}
+EOF
+bunx -y @mermaid-js/mermaid-cli -i .canon/tmp/figures/<slug>.mmd -o .canon/tmp/figures/<slug>.svg -c .canon/tmp/figures/<slug>.json
+bunx -y @mermaid-js/mermaid-cli -i .canon/tmp/figures/<slug>.mmd -o .canon/tmp/figures/<slug>.png -c .canon/tmp/figures/<slug>.json
+```
+
+Render both formats in one pass. The SVG is what ships inside the `<figure>`, and the PNG is what the read-back below judges, since an SVG's markup carries no recoverable spatial meaning.
+
+Use `bunx` when bun is available, falling back to `npx -y @mermaid-js/mermaid-cli ...` otherwise.
+
+Before the first render in a project, say what is about to block:
+
+```plaintext
+Rendering to verify layout. The first run downloads the Mermaid CLI and takes about 15 seconds.
+```
+
+## Rewrite the colors
+
+Rewrite every stroke, fill, and text color the renderer wrote as a literal hex value into the custom property the host stylesheet defines, per the color rule in `${CLAUDE_SKILL_DIR}/../../standards/figures.md`. Mermaid's own theme has no notion of a custom property, so this is a source edit made to the rendered SVG, not a config option.
+
+## Clipped titles
+
+- Expect a group title or a long label to clip once the destination shows it in the hand font, since the renderer sized its box in a fallback face.
+- When the in-page check shows a clipped title, add a `<style>` inside the SVG, scoped to that SVG's own id, that sets `overflow: visible` on the clipped label's `foreignObject` and centers the label within it, so the wider text spills past both edges evenly. The style hides the mismatch for a title and does nothing for a node label crowding its box, which takes a shorter label instead.
+
+## Fonts
+
+Check whether the project ran `canon design css --figures`. The figure and figcaption styling ships unconditionally either way, but that flag alone embeds the Virgil and Excalifont font files. Without it, the figure falls back to the browser's own generic `cursive` face rather than the intended hand-drawn font, and the output names that gap when the flag was not passed.
+
+## Read the render back
+
+- Read the rendered PNG and judge it against what the figure means to say, applying the verification properties in the mermaid standard. A source satisfying every rule there can still render as a picture asserting something false, so the image is what gets judged.
+- Fix the Mermaid source and re-render on a defect. Stop after two correction passes. When a defect survives, keep the figure and name the defect in the output rather than reporting a false verification.
+- When the render fails for any reason, no browser engine, no network, no package manager, continue to the confirm step and name the skipped check. A missing renderer degrades the loop rather than failing it.

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

@@ -72,7 +72,7 @@ Follow `${CLAUDE_SKILL_DIR}/../draft-and-pick/SKILL.md` Steps 2 through 5 agains
 This step and Step 7 replace `draft-and-pick`'s own Step 6, since the pick here produces several final files rather than one applied surface.
 
 1. Extract the picked arm's `.mark` markup as the final vector source. Write it to `<write-folder>/favicon.svg`.
-2. Under `<dest>/render/`, write one `icon-<w>x<h>.html` page per Step 2 size, carrying the picked `.mark` markup. Give every page's captured element the shared class `.render`, so one capture call renders the whole batch regardless of the size spread. `canon capture` opens every page at a fixed 2x device scale factor and screenshots the element at that scale, so declare each `.render` element at half its target dimension, `<w>/2` by `<h>/2`, to land the captured PNG on the literal target size rather than double it. Declare a machine-resolved font stack (`system-ui` behind a generic fallback) on each, since `canon capture` refuses a page naming no font at all.
+2. Under `<dest>/render/`, write one `icon-<w>x<h>.html` page per Step 2 size, carrying the picked `.mark` markup. Give every page's captured element the shared class `.render`, so one capture call renders the whole batch regardless of the size spread. `canon capture` opens every page at a fixed 2x device scale factor and screenshots the element at that scale, so declare each `.render` element at half its target dimension, `<w>/2` by `<h>/2`, to land the captured PNG on the literal target size rather than double it. Declare no font on them, since each holds the mark alone and `canon capture` skips the font check on an element with no text. A generic family such as `system-ui` would be refused if text ever sat inside one.
 3. Render the batch:
 
    ```bash

package/claude/skills/draft-screencast/SKILL.md

@@ -45,6 +45,8 @@ Create `demos/<slug>/beats.md` at the project root, creating the folder if it do
 
 Write all nine sections. Pre-seed every section with concrete content so the draft is shippable as-is. The user edits down rather than fills blanks.
 
+Load `canon:video-craft` for every zoom and caption value the draft names, and report it rather than proceeding silently when it does not resolve. The template below states none, since each number there traces to a source that skill records.
+
 ```markdown
 # Screencast: <short title>
 
@@ -72,7 +74,7 @@ Five beats. Each uses five fields. Add a sixth `Transition out` only when non-de
 - On screen: <derived from hero moment>
 - Action: <one verb, derived>
 - Watch for:
-- Emphasis: zoom 1.4x
+- Emphasis: zoom onto the action, scale and speed per `canon:video-craft`
 - Caption:
 
 ### Beat 2: Setup
@@ -104,7 +106,7 @@ Five beats. Each uses five fields. Add a sixth `Transition out` only when non-de
 - On screen:
 - Action:
 - Watch for:
-- Emphasis: zoom 1.2x out
+- Emphasis: zoom out to full frame
 - Caption:
 
 ## 4. Sequencing notes
@@ -119,14 +121,14 @@ Five beats. Each uses five fields. Add a sixth `Transition out` only when non-de
 - Resolution: 1920x1080
 - Frame rate: 30fps
 - Container: mp4 H.264
-- Zoom: max 1.8x with always-zoom-out before cut
+- Zoom: only on an action too small to read at full frame, scale, speed, and dwell per `canon:video-craft`, zoomed out before every cut
 - Highlight overlay: ~1.5s soft glow
 
-## 6. Caption typography
+## 6. Captions
 
-- White text on dark scrim at ~60% opacity
-- ~200ms fade in and out
-- One line max per caption, split across beats if needed
+- Each caption names what its beat's frame shows, at most two lines of 42 characters, per `canon:video-craft`
+- Hold and reading rate per `canon:video-craft`, splitting a caption across beats rather than shortening its hold
+- Placed off the element the beat acts on
 
 ## 7. Distribution
 

package/claude/skills/draft-slides/REQUIREMENT.md

@@ -1,39 +1,44 @@
 ---
 name: draft-slides
-description: Why the skill owns deck content and the CLI owns layout, and why one render is read back before the deck is called done
+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
 ---
 
 # Draft slides requirement
 
 ## Gap
 
-Without this skill, a deck request turns into hand-built layout. The session invents layout names the renderer does not have, so the render falls back or fails, and it writes centered body text and bullet lines that overflow the slide because nothing told it the type scale is fixed. 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.
+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.
 
-Reimplementing spacing and palette logic is the failure that survives the session. The CLI already owns both, so a deck that styles itself drifts from every other deck and stops being recognizable. And a first render shipped unread hands the audience the overlap and the overflow, since a source that looks correct says nothing about the picture it produces.
+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 layout catalog from the CLI before drafting and pick only from what it returns
-- Match the content shape to the layout, since each one parses a different body
-- Vary layouts across the deck rather than repeating one
-- Size content to fit the fixed type scale, keeping titles short and bullet lines tight
+- 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
-- Run one QA pass over the rendered images and fix what it reports
+- 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 layout name, which goes stale the moment the catalog changes
-- Reimplement layout, palette, or type scale, which the CLI owns
+- 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
 
-- Rendering, which the CLI owns end to end
-- The palette and the type scale, which live in the CLI rather than in the source
+- 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 `draft-screencast` owns

package/claude/skills/draft-slides/SKILL.md

@@ -1,49 +1,59 @@
 ---
 name: draft-slides
-description: Drafts a `.claude/SLIDES.md` source from a topic, picks a layout per slide, then renders it to PowerPoint via `canon slides render`. Use when asked to "draft slides", "make a deck", "build a presentation", "turn this into slides", or "render a SLIDES.md". Holds the deck design rules. Do NOT reimplement render logic. The CLI owns layout and styling. Assumes the `canon` CLI is on PATH.
+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.
 ---
 
 # Draft slides
 
-Author a `SLIDES.md` source, then shell out to `canon slides render`. The CLI owns all layout and styling. This skill owns content and the design choices encoded in the source.
+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 catalog
+## Read the decks and the format
 
-Run this first to load the available layouts. Never hardcode layout names. The catalog is the source of truth.
+Run both first. Never hardcode a deck name, an attribute, or a chart type. The CLI is the source of truth for each.
 
 ```bash
 canon slides list --json 2>/dev/null
+canon docs slides
 ```
 
-## Draft the source
+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.
 
-Write the deck to `.claude/SLIDES.md` from the project root. Structure:
+The docs page states what `deck.json` holds, what each slide declares on its `<body>`, the motion attributes, speaker notes, charts, and what each refusal reports.
 
-- Deck frontmatter between `---` delimiters: `title`, optional `subtitle`, `palette`, and `variant` (light or dark).
-- One slide per section, separated by a `---` rule. Each slide opens with a `# Title` and a `layout:` line naming a layout from the catalog, followed by its content.
+## Draw the deck
 
-Match content shape to the layout: bullet lists for list layouts, `## Heading` blocks for columns, `- value : caption` pairs for stats and cards, a quote with a `- attribution` line for quotes.
+A deck folder sits at `.canon/slides/<deck>/` from the project root, and holds:
 
-For a deck with chapters, add a `toc` slide near the front and mark each chapter opener with the `section` layout. The render fills the contents links and the per-slide footer automatically from the section slides. Leave the `toc` slide body empty.
+- 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 palette and type scale live in the CLI. Own the choices the source controls.
+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.
 
-- Pick the variant that fits the topic. Light is a paper background, dark is near black. Both carry the same rust accent.
-- Vary the layout across slides. Never repeat title-and-bullets on every slide. Reach for columns, stat callouts, grids, and section dividers.
-- The CLI enforces the type scale, so size content to fit rather than overflow. Keep titles short and bullet lines tight.
-- Never write centered body text or content that overflows a slide. Let the layouts place the elements.
+- Use the project's custom properties, such as `var(--color-accent)`, for every color, face, and spacing value the stylesheet defines. Read the names from `.claude/design/base.css` and any 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 rather than redefining them in a slide. The master reads its colors off the first slide's `<html>`, and a slide body computing its own `--color-text` is reported, since the bands keep the master's colors.
+- 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.
+- 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 element computing a property it cannot map is drawn as a picture of itself 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 --source .claude/SLIDES.md --out .canon/tmp/render/slides
+canon slides render <deck>
 ```
 
-Pass `--variant light` or `--variant dark` to override the source variant for a one-off render. Pass `--open` to open the deck, and `--mirror <dir>` (or set `CANON_SLIDES_MIRROR`) to copy it into a synced folder.
+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
 
@@ -51,12 +61,13 @@ Run this once after the first render, then stop.
 
 1. Convert the deck to images: `soffice --headless --convert-to pdf <deck>.pptx` then `pdftoppm -r 90 -png <deck>.pdf slide`. If `soffice` or `pdftoppm` is missing, skip the image pass and say so. Do not 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 in `SLIDES.md` once, re-render, and stop. Do not loop indefinitely on aesthetics.
+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:
 
-- Slide count and the deck path
-- The palette and variant used
+- 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