@erclx/canon 5.25.0 → 5.27.0

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

@@ -40,10 +40,4 @@ The layer a model is worst at, and the layer where rules are hardest to make fal
 
 ## Considered and declined
 
-Each failed the test in `REQUIREMENT.md`. Recorded so they are not argued again.
-
-- **Control sizing and proportion.** An unguided model produces reasonable controls without instruction, so it fails the first question.
-- **Specific ratios for a type scale**, such as a named musical interval. Falsifiable and arbitrary, and a project picking a different ratio is not wrong.
-- **Named palettes or banned hues.** A value ban, which belongs to the project's design document. This is where every external catalog of this kind ends up, and it is why theirs cannot be imported.
-- **A minimum contrast figure.** A threshold with a number, which the accessibility rules own.
-- **Imagery as a system.** There is no scale to establish. What a model gets wrong about images is using fake ones, which `tells.md` already covers, so the layer stays thin on purpose rather than by oversight.
+The items considered for this reference and declined sit in `adopted.md` beside this file, recorded so they are not argued again.

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

@@ -1,6 +1,6 @@
 ---
 title: Machine tells in design
-description: The visual defaults a model reaches for when nothing states a direction, each with what to do instead, plus the record of which external items were adopted, which were declined, and why
+description: The visual defaults a model reaches for when nothing states a direction, each with what to do instead, plus the countable composition limits and the first-screen budget
 ---
 
 # Machine tells in design
@@ -76,26 +76,4 @@ These are the rules with numbers, so they are checked by counting rather than by
 
 ## Adopted, declined, and why
 
-External catalogs were read and filtered rather than imported. This section is the record, and a later session extends it rather than re-deriving it.
-
-### Adopted
-
-**Adopted with no change.** The three equal cards, the centered hero over a wash, enumerated eyebrows, scroll cues, decorative status dots, atmospheric strips, the fake screenshot built from boxes, filler verbs, and placeholder that reads as placeholder. Each names a shape, each carries a replacement, and none depends on a stack.
-
-**Adopted with the stack removed.** Source items naming an icon set, a component library, a font by name, or an animation package were rewritten to state what the rule is about. "Do not use Inter" became one family doing every job, since the defensible claim is about pairing and role separation rather than about one typeface.
-
-### Declined
-
-**Banned fonts by name.** A font ban is a value ban, and a value belongs to the project's own design document rather than to a skill that loads everywhere. A project that wants a typeface ruled out rules it out there.
-
-**Numeric intensity dials.** Every external source carries a 1-to-10 scale for variance, motion and density. A session picks a middle value and reports compliance. That satisfies the rule, decides nothing, and leaves no trace a later reader could check it by. The declared read carries the same information in a sentence somebody can argue with.
-
-**The em dash ban as a design rule.** One source bans the character on a page as a visual tell. The markdown standard already bans it for prose reasons and `canon markdown audit` gates that from package data, so restating it here would put a second copy of an enforced rule behind an unenforced pointer.
-
-**The official-package map.** A table routing a brief to Fluent, Material, Carbon, Polaris, Primer or a government design system. It is real advice and it is a stack decision a project takes once, so it belongs in that project's own records rather than in a skill that loads on every design round.
-
-**Scoping out application UI.** The largest source covers landing pages, portfolios and redesigns, and excludes dashboards, data tables and multi-step product UI. Those exclusions are most of what software projects actually build, so the kinds reference carries application UI as a first-class kind.
-
-### Carried as a caution
-
-**Greeking.** Placeholder text is correct while judging space and wrong once an arm is judged on content, since real copy length is what breaks a composition. State which of the two a set is doing.
+The record of which external catalog items were adopted, which declined, and why sits in `adopted.md` beside this file.

package/claude/skills/docs-sync/REQUIREMENT.md

@@ -35,7 +35,8 @@ The quiet one is the baseline. A diff resolved against a bare local ref equals H
 
 ## Out of scope
 
-- The context entries, requirements, architecture, wireframes, and task board: `context-fold`, which runs immediately before this skill in the ship chain and resolves the same baseline. The split is by audience, so a file's location decides which skill owns it rather than its subject.
+- The context entries, architecture, wireframes, and task board: `context-fold`, which runs immediately before this skill in the ship chain and resolves the same baseline. The split is by audience, so a file's location decides which skill owns it rather than its subject.
+- The requirements record: `document-health` reads it when asked, and `markdown-propose` rewrites it from the answers
 - `CLAUDE.md` and the installed seed docs: `seed-sync`, which reconciles them per section against the toolkit source
 - Changelog entries, which release tooling generates from commit messages
 - Whether the prose conforms to its standards. `canon markdown audit` reports violations and fixes none, and this skill writes prose it does not audit.

package/claude/skills/docs-sync/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: docs-sync
 description: Rewrites stale `README.md` and `docs/*.md` sections based on changes since main. Use before staging, or when asked to "sync the public docs", "update the docs in docs/", or "update the README". Do NOT use for the context entries, planning records, or task board, which `context-fold` owns, or for changelog and `CLAUDE.md` updates.
+metadata:
+  family: ship
 ---
 
 # Docs sync

package/claude/skills/document-health/REQUIREMENT.md

@@ -23,6 +23,7 @@ The third is silence on an unread axis. Both measured verbs resolve their folder
 - Say which layer answered the classifier sweep, since its model layer being off narrows the read without refusing it
 - Take every checkpoint from the record the verb returns rather than from a number written into the skill
 - Run standalone, and stay callable from the structural check rather than reachable only through it
+- Read the requirements and architecture records for identity drift when the scope reaches them, and print one reminder line per doc from `canon records stale canonical`, since the fold no longer writes the first and only writes the second for a planned slot decision, so nothing else reads either whole
 
 ## Must not
 
@@ -30,6 +31,7 @@ The third is silence on an unread axis. Both measured verbs resolve their folder
 - Emit a verdict across the three axes, or a score across the documents. Two axes answer from verbs and one answers from a reading, so any roll-up is a figure that lies about the third.
 - Report a finding against a file nobody hand-authors. A generated index, a gitignored file, and a copied reference each name a file an author cannot fix.
 - Answer an axis by file inspection where a verb answers it. The verb is the surface under test and a hand-rolled read of the same files is not.
+- Trigger itself, or ask a hook, a gate stage, or CI to trigger the canonical review. The operator settled that it runs only when asked.
 - Read a document's modification time as its staleness. A file untouched beside code untouched is current, and the timestamp answers a different question.
 
 ## Guards

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

@@ -1,6 +1,8 @@
 ---
 name: document-health
 description: Reports which of a project's documents have rotted, one section per document, across length, placement, and staleness. Reads each axis through the verb that owns it and marks the evidence class each answer carries. Use when asked to "check document health", "which docs have gone stale", "audit the docs for rot", "are these documents still accurate", "which docs are too long", or after a target check reports the structural side. Do NOT use to repair a finding, which the owning command or skill does, and do NOT use to check whether a document exists or holds the right sections, which is `target-check`.
+metadata:
+  family: check
 ---
 
 # Document health
@@ -59,6 +61,18 @@ No verb answers whether a document still describes the tree it was written about
 
 Mark every staleness finding as a reading. It is this session's judgment rather than a measurement, and a report that sets it beside two verb-backed axes without marking it implies evidence the axis does not carry.
 
+### The requirements and architecture records
+
+When the scope reaches `canon/REQUIREMENTS.md` or `canon/ARCHITECTURE.md`, read each for identity drift as well as for stale paths, and take the review point from the verb:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon records stale canonical --json
+```
+
+Each doc in the record carries `reviewed` and `releasesSince`. `${CLAUDE_SKILL_DIR}/references/axes.md` holds the identity claim shapes to test and how the record reads. Skip both the read and the verb when the scope excludes the two docs.
+
+Nothing triggers this review but a request. A finished review routes to `markdown-propose` for the rewrite, and its last edit sets `reviewed:` in the doc's frontmatter to the day the operator's answers landed. This run writes neither.
+
 ## Step 4: report per document
 
 Give each document its three axes, and give each axis three things: the state, the evidence class, and the command or skill that repairs it. Naming the repair is not running it.
@@ -85,4 +99,13 @@ Document health: `<scope>`, <n> documents read.
 Length and placement are measured. Staleness is a reading.
 ```
 
+When Step 3 read the canonical records, add one reminder line per doc the verb returned, under the evidence line:
+
+```markdown
+`canon/REQUIREMENTS.md`: reviewed <date>, <n> releases since.
+`canon/ARCHITECTURE.md`: never reviewed.
+```
+
+Write `reviewed value is not a date: <value>` for a doc carrying `invalidReviewed`, and `no release tags to count` in place of the count when `tagged` is false. Name the unread cause instead when the verb refused or the binary carries no `canonical` kind.
+
 Keep the evidence line under the table on every run. A table read without it flattens a judgment into a measurement, which is the one shape the three classes exist to prevent.

package/claude/skills/document-health/references/axes.md

@@ -67,6 +67,18 @@ Read each document against the surfaces it names. Four claim shapes are testable
 
 A claim resting on none of the four is unverifiable from here. Report it as unread rather than as passing, which is the same rule the measured axes take when a verb refuses.
 
+### Identity drift in the requirements and architecture records
+
+These two records state what the project is and why it is built the way it is, so they go stale by the project changing direction as well as by the tree moving. Test these claim shapes beside the four above:
+
+- A goal nobody pursues, read against the task board and the recent history
+- A non-goal the project has since shipped
+- A constraint the tree contradicts
+- A decision whose revisit sentence has fired
+- A risk or open question already fixed
+
+Each is a `read`. The review point beside them is `measured`: `canon records stale canonical --json` returns per doc the `reviewed` date from its frontmatter and `releasesSince`, the release tags merged into HEAD after that day. A null `releasesSince` means the doc was never reviewed, and `tagged: false` means no release tag exists to count, so a zero there measured nothing. The count is a reminder of how far the project has moved since someone last read the record whole, never a threshold.
+
 **Routes to:** the skill that rewrites a stale claim against an answer, rather than a direct edit from here. A document health run reports and never repairs.
 
 **Caveat:** a reading is the weakest evidence in the report and the most consequential finding in it, which is the tension this axis ships with. Marking the class is what keeps the two facts together in the reader's hands.

package/claude/skills/draft-and-pick/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: draft-and-pick
 description: Drafts several candidates for a decision judged by looking, renders them side by side on one page, hands the operator the addresses, 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`, to script a recording, which is `draft-screencast`, or to inspect a running app across many findings, which is `ux-walkthrough`.
+metadata:
+  family: decide
 ---
 
 # Draft and pick
@@ -35,7 +37,7 @@ Write every arm side by side on one self-contained HTML page at `<dest>/candidat
 - Hand over the per-arm file addresses beside the combined page where the declared layer is composition, layout or space, and say that an arm is judged at a width by opening its own file in the browser's device toolbar. The combined page cannot answer that question at all: every arm sits in a column there while the media queries answer to the whole window, so each one renders its widest layout in a narrow space no matter how the window is sized. Build no width control of your own, since the browser already has one.
 - Take the live-app branch instead when the surface under decision is a running app: lift the rendered markup and link a copy of the built stylesheet rather than inlining, per `${CLAUDE_SKILL_DIR}/references/live-arms.md`.
 - On the default path, inline every style, script, and asset the page needs. The render reads the file off disk, so a page reaching for a build step or a network font renders without it and the arms differ by something nobody chose.
-- On the default path, declare a font stack the machine resolves, such as `system-ui` behind a generic fallback. The render refuses a page that would rewrap against a substitute rather than shipping a false comparison, so a page naming no font at all is refused on whatever the default resolves to.
+- On the default path, name a real font first in the stack, one the machine has or the page embeds, such as the project's own family from its design tokens. A generic keyword such as `system-ui` or `sans-serif` is refused, since it resolves to a different font on each machine. The render refuses a page that would rewrap against a substitute rather than shipping a false comparison, so a page naming no font at all is refused on whatever the default resolves to.
 
 ### What varies
 

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

@@ -1,6 +1,8 @@
 ---
 name: draft-doc
 description: Drafts one brand-new project document from scratch against the standard for its kind, picking the kind from where it lands, a `docs/` page, a `canon/context/` entry, a `canon/wireframes/` surface, a wiki reference page, or a README.md. Checks the catalog for a name or topic collision, places it, confirms with the user, then writes. Use when asked to "write a new docs page for X", "write a context entry for X", "draft a wireframe for X", "write a wiki page for X", or "write a README" where none exists yet. Do NOT use to rewrite or sync an existing page or README against a diff, which is `docs-sync`, or to refresh a context entry or wireframe, which is `context-fold`.
+metadata:
+  family: generate
 ---
 
 # Doc draft

package/claude/skills/draft-doc/references/wiki.md

@@ -39,7 +39,7 @@ The standard forbids working from training knowledge, so the draft is built on a
 
 ## Draft
 
-- Draft `title` and `description` frontmatter against the standard's contract, then the intro paragraph closing on `Source:`, then the reference sections.
+- Draft `title` and `description` frontmatter against the standard's contract, then the intro paragraph closing on `Source:` as a short orientation, then the lesson sections. Let the read of the source decide what is a lesson: keep a fact only when the source page does not state it, and leave reference detail to the source.
 - Write what the fetch returned rather than what the subject is assumed to do.
 - Answer one question per section and stop. A reader arrives to settle something specific rather than to read the page through.
 - Mark a claim the fetch left unsettled rather than smoothing over it. An unmarked gap reads as a checked fact.

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

@@ -1,6 +1,8 @@
 ---
 name: draft-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 wireframe, which is `draft-doc`, or for design tokens, which is `design-extract`.
+metadata:
+  family: generate
 ---
 
 # Draft figure

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

@@ -1,6 +1,8 @@
 ---
 name: draft-identity
 description: Drafts a project's logo mark through draft-and-pick's render-and-pick loop, then composes the picked mark into an icon sequence and a 1200x630 social card. Use when asked to "make a logo", "design a logo mark", "create a favicon", "build the icon set", "generate a social card", "make an og:image", or "draft the logo and social card together". Do NOT use to mutate an existing logo file directly, which is a plain edit, or to record the mark's construction rules in DESIGN.md, which is out of scope.
+metadata:
+  family: generate
 ---
 
 # Draft identity
@@ -72,7 +74,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-ready/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: draft-ready
 description: Writes a ready folder for finished files, its `00-overview.md`, the thin plan that points at it, and the task with a board row placed, reported to an orchestrator, or left to the operator, in one invocation. Use when asked to "write a ready folder", "hand these files to a worker", "package these finished files for a worker", "make a ready handoff", or when a session already holds the exact text of a skill, rule, or doc and a worker should copy it rather than author it. Do NOT use to plan a change nobody has written yet, which is `plan-feature`, to copy a folder into a worktree and ship it, which is `role-worker`, or to file a task with no finished files behind it, which is `task-board`.
+metadata:
+  family: generate
 ---
 
 # Draft ready

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

@@ -1,6 +1,8 @@
 ---
 name: draft-screencast
 description: Drafts a screencast script with pre-seeded beats, defaults, and decisions to `demos/<slug>/beats.md`. Reads project context, asks four discovery questions with proposed defaults, then writes a shippable draft. Use when asked to "draft a screencast", "write a recording script", "plan a demo video", or "scaffold a screencast for X". Do NOT re-invoke to refine an existing draft. Re-running overwrites. Edit the draft file directly.
+metadata:
+  family: generate
 ---
 
 # Draft screencast
@@ -45,6 +47,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 +76,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 +108,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 +123,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,61 @@
 ---
 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.
+metadata:
+  family: generate
 ---
 
 # 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 +63,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

package/claude/skills/git-branch/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: git-branch
 description: Generates and validates conventional branch names. Use for any branch naming or renaming, such as when asked to "name this branch".
+metadata:
+  family: ship
 ---
 
 # Git branch

package/claude/skills/git-commit/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: git-commit
 description: Generates one conventional commit message from the staged changes and commits them exactly as staged, so a hunk-level selection survives. Use when asked to "commit this" or "commit the staged changes" and the staged set covers one concern, or whenever the selection was staged hunk by hand. Do NOT use when the staged changes span several concerns and need separate commits. That is `git-stage`.
+metadata:
+  family: ship
 ---
 
 # Git commit

package/claude/skills/git-followup/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: git-followup
 description: Ships a small self-review edit on the current PR branch by staging, committing, pushing, and syncing the open PR, replying on the PR when it carries review comments. Use when asked to "ship a followup", "push the PR fix", "followup", or "commit and push this small change". Do NOT use when there is no open PR for the branch (use git-ship instead).
+metadata:
+  family: after-pr
 ---
 
 # Git followup

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

@@ -1,6 +1,8 @@
 ---
 name: git-issue
 description: Format a bug or task from the current session into a GitHub issue and file it on the current repo via `gh issue create`. Use when asked to "file an issue", "open an issue", "log this bug", "raise an issue", or "track this as an issue". Do NOT use to report a toolkit defect from a target project (that is `canon-feedback`), or to open a pull request (that is `git-pr`).
+metadata:
+  family: after-pr
 ---
 
 # Git issue

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

@@ -1,5 +1,15 @@
 # Issue reference
 
+## Contents
+
+- [Scope](#scope)
+- [Title](#title)
+- [Labels](#labels)
+- [Content](#content)
+- [Sections](#sections)
+- [Formatting](#formatting)
+- [Examples](#examples)
+
 ## Scope
 
 Governs a tracker issue: its title, its labels, and the sections its body carries.

package/claude/skills/git-pr/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: git-pr
 description: Generates pull request titles and descriptions from git diffs. Use for any PR creation or update, such as when asked to "open a pull request".
+metadata:
+  family: ship
 ---
 
 # Git PR

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

@@ -7,6 +7,14 @@ description: How git-pr finds the UI checklist and the local server, posts the e
 
 The rendered-surface step of `git-pr`, reached after the final command printed the pull request number. The step runs on every pull request, with no test on the diff ahead of it. `no-evidence` is the silent branch, so a pull request that changes no rendered surface posts nothing.
 
+## Contents
+
+- [Find the UI checklist](#find-the-ui-checklist)
+- [Find the local server](#find-the-local-server)
+- [Post the evidence comparison](#post-the-evidence-comparison)
+- [Post the UI checklist alone](#post-the-ui-checklist-alone)
+- [Post the preview address](#post-the-preview-address)
+
 ## Find the UI checklist
 
 `ui-checklist` writes a visual checklist to `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root when a change needs visual verification, with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This skill is the file's sole consumer. Resolve the main root the way `session-worktree` does (`git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`) and check for the file there. A missing file means no checklist was produced, and the two steps below each skip their checklist half.
@@ -31,9 +39,9 @@ The verb reads the listening sockets on this machine, keeps those whose process
 
 Pass `--local` to the evidence step only on an `ok` here. The binary answering `ok` is the one carrying the flag, so a binary lacking the verb never meets a flag it would reject.
 
-With a checklist, a diff carrying no evidence image still renders `ok`, and a local link rides in the same comment above the checklist, so a reviewer gets both in one place. A local link with neither an evidence image nor a checklist still reports `no-evidence`, which keeps a branch that changed no rendered surface from getting a comment holding a link and nothing else.
+With a checklist, a diff carrying no evidence image still renders `ok`, and a local link rides in the same comment on the address line under `## Evidence`, above the checklist, so a reviewer gets both in one place. A local link with neither an evidence image nor a checklist still reports `no-evidence`, which keeps a branch that changed no rendered surface from getting a comment holding a link and nothing else.
 
-A seeded workflow replaces the line with a note once the pull request closes, so the link does not outlive the branch it points at.
+A seeded workflow drops the whole address line once the pull request closes, hosted and local segments together and with no note in their place, so neither link outlives the branch it points at.
 
 ## Post the evidence comparison
 
@@ -102,15 +110,15 @@ The evidence comment is already posted, so the reviewer has the screenshots whil
 canon pr preview <number> --json
 ```
 
-The verb dispatches the project's Pages deploy on the pull request's branch and waits on the run for up to 15 minutes. It refuses before dispatching anything when the deploy command passes no `--branch`, since that deploy would publish the branch to production. `canon docs pr-preview` states the contract. Read `reason` on the record rather than the exit code.
+The verb dispatches the project's Pages deploy on the pull request's branch and waits on the run for up to 15 minutes. It refuses before dispatching anything when the deploy command passes no `--branch`, since that deploy would publish the branch to production, and when the workflow's own push path filter matches no path the pull request changed, since a dispatch ignores that filter and the site it published would show none of the change. `canon docs pr-preview` states the contract. Read `reason` on the record rather than the exit code.
 
-- `ok`: re-render the evidence body with the address on its first line, then post or update it exactly as the evidence step does, through the same tmp file and the `commentId` the record carries:
+- `ok`: re-render the evidence body with the address on the line under `## Evidence`, then post or update it exactly as the evidence step does, through the same tmp file and the `commentId` the record carries:
 
 ```bash
 canon pr evidence <number> --preview <url> --json
 ```
 
-The hosted address takes the first line and a local link already on the comment moves to the second, carried forward with no flag.
+The hosted address opens the address line and a local link already on the comment follows it on the same line, carried forward with no flag.
 
-- `no-deploy`: the project deploys nothing a dispatch can start. Say nothing and move on.
+- `no-deploy` or `unserved`: the project deploys nothing a dispatch can start, or nothing this branch changed is something its site builds from. Say nothing and move on.
 - Any other `reason`, being `unfenced`, `no-alias`, `run-failed`, `timeout`, or a mirrored `gh` refusal: report it with the record's `message` and move on without stopping the chain. A missing link costs the reviewer a click, and a held ship costs the whole chain.

package/claude/skills/git-pr/references/labels.md

@@ -5,6 +5,18 @@ description: Path-to-label map format, prefix matching against the changed set,
 
 # Label reference
 
+## Contents
+
+- [Scope](#scope)
+- [Map format](#map-format)
+- [Paths a map declines to label](#paths-a-map-declines-to-label)
+- [Reporting a surface no row reaches](#reporting-a-surface-no-row-reaches)
+- [Matching](#matching)
+- [Applying](#applying)
+- [A label the remote does not carry](#a-label-the-remote-does-not-carry)
+- [Release pull requests](#release-pull-requests)
+- [Labels at run time](#labels-at-run-time)
+
 ## Scope
 
 Governs the labels a pull request carries: the map a project declares, how a changed path resolves to a label, and what a label missing from the remote costs.

package/claude/skills/git-ship/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: git-ship
 description: Runs the full post-feature workflow by syncing docs, staging commits, renaming the branch, and opening a PR. Use after implementing a feature, or when asked to "ship", "ship this", or "ship it". Do NOT auto-trigger. Shipping is a decision the user takes.
+metadata:
+  family: ship
 ---
 
 # Ship