@erclx/canon 5.25.0 → 5.26.0

package/README.md

@@ -68,7 +68,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 | Standards      | Authoring conventions for commits, branches, plans, tasks, and markdown                                                  | Opened by name, read by name with `canon standards <name>`      |
 | Tooling stacks | Golden configs, seeds, and a reference per framework                                                                     | Laid down by `canon init`, reconciled by `canon tooling sync`   |
 | Design system  | Ships a `DESIGN.md` token format, a skill that drafts one from an existing project or from scratch, and a render command | `canon design render`                                           |
-| Slides         | A `SLIDES.md` source format with a layout catalog, or a folder of HTML slides rebuilt as editable shapes                 | `canon slides render` writes PowerPoint                         |
+| Slides         | A folder of HTML slides per deck, drawn in the project's tokens and rebuilt as editable shapes                           | `canon slides render` writes PowerPoint                         |
 | Teach          | Lessons, sources, and a glossary in one workspace, rendered to a small site                                              | `canon teach`                                                   |
 | Canvas         | Pages of HTML frames on a local pan and zoom surface, each frame drawn with the project's tokens                         | `canon canvas serve`                                            |
 | Transcripts    | A YouTube transcript with metadata frontmatter                                                                           | `canon transcripts <url>` writes it into any repo               |
@@ -98,6 +98,7 @@ Working with an agent rather than reading this yourself? It loads `CLAUDE.md` at
 - [AI workflow](docs/workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [Operating model](docs/workflow/operating-model.md): orchestrator, planner, and worker roles for building across parallel sessions
 - [Skill map](docs/workflow/skill-map.md): plugin skills grouped by the moment a project meets them
+- [Skill map on request](docs/workflow/skill-map-on-request.md): plugin skills that serve a request rather than a moment
 - [Visual design workflow](docs/workflow/visual-design-workflow.md): tiered guide for design and wireframe authoring
 - [Target projects](docs/target/projects.md): scaffold, add a domain later, sync upstream drift
 - [Agents](docs/agents/index.md): CLI flags, exit codes, and JSON output shapes

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.25.0",
+  "version": "5.26.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canvas/SKILL.md

@@ -83,7 +83,7 @@ The operator restyles elements from the inspector, and each edit lands as inline
 - Capture a whole page once its frames are finished: `canon canvas capture <page> --composite --json`. The image shows each frame clipped to its box at its layout position.
 - Capture once per finished frame or page, not after every edit. The live canvas is the working view, and a capture is the record handed on.
 - Read each `path` off the record rather than composing one.
-- A capture refused because a font is not installed names the family it read off the frame's `html` element. Set that element's `font-family` to a family the machine has and capture again, rather than reporting the frame as captured.
+- A capture refused because a font is not installed names the family it read off the frame's text. Set that text's `font-family` to a named family the machine has, never a generic keyword such as `sans-serif`, and capture again, rather than reporting the frame as captured.
 
 ## Step 7: carry a picked direction back
 

package/claude/skills/context-fold/REQUIREMENT.md

@@ -7,7 +7,7 @@ description: What the planning-doc reconcile is for, the gaps it closes, and why
 
 ## Gap
 
-Without this skill, the planning docs describe the scope the session opened with. An outcome the diff shipped stays unchecked, so the board reports finished work as open and the next session re-plans it. A requirement or architecture decision that changed mid-cycle lives only in the conversation and dies with it. Plans for closed tasks accumulate in the live folder, so the folder stops indicating what is in flight.
+Without this skill, the planning docs describe the scope the session opened with. An outcome the diff shipped stays unchecked, so the board reports finished work as open and the next session re-plans it. An architecture decision a plan settled mid-cycle lives only in the conversation and dies with it. Plans for closed tasks accumulate in the live folder, so the folder stops indicating what is in flight.
 
 A decision's verification anchor has the same shape of gap in the other direction. The reasoning keeps reading as current while the number it cites moves underneath, and an amendment written without an anchor leaves nothing recording which numbers were checked and which nobody has read since.
 
@@ -17,6 +17,8 @@ The receipt half of that sweep was missing entirely. A review receipt was delete
 
 The trigger side carries a gap of its own. "Sync the docs" names either corpus to the person saying it, so a description leaving its corpus to the opening clause alone competes with its public-facing sibling on nothing the routing field states, and the planning surface the request was about goes untouched.
 
+The opposite gap opened from the same write. A fold allowed to touch the requirements and architecture records on every ship rewrote both one reasonable edit at a time, and nothing read either for whether it still stated the project's identity. Each ship looked correct and the sum drifted.
+
 This skill writes canonical docs at the end of a long build and never reviews what it wrote. An appended figure or a branch-narrated re-measurement lands unchecked the same way a session's own edits do, so what the fold produces carries the exact defect the standards it cites already ban.
 
 ## Must
@@ -28,7 +30,8 @@ This skill writes canonical docs at the end of a long build and never reviews wh
 - Write tracked docs at the current worktree root and the task board at the main root, since only the first commits with the branch
 - Count every other citation before archiving a plan, comparing resolved targets rather than raw strings or bare filenames
 - Retarget a closed task at the archived plan, so the reasoning behind finished work stays reachable
-- Write a decision to the domain context entry it constrains unless it fills an architecture slot, since reach admits nearly every decision to an always-loaded file
+- Write a decision to the domain context entry it constrains unless a plan this run folds states it and it fills an architecture slot, since reach admits nearly every decision to an always-loaded file and a slot decision only the conversation carries was never reviewed
+- Report a requirements or direction change in one line naming `document-health`, rather than writing it, so the identity record changes only when the operator reviews it
 - Merge or retire an architecture entry before adding one at the record's stated cap, and name which in the report, so the cap never turns into compressed prose or two decisions packed under one heading
 - Anchor a decision entry this run writes or amends whose reasoning cites a measured number, re-reading the number against the tree before writing the marker
 - Report an anchored decision whose cited path the diff touched, since the number was read before the branch moved what it counted
@@ -48,6 +51,7 @@ This skill writes canonical docs at the end of a long build and never reviews wh
 - Infer a new task from the diff. Only outcomes already on the board get marked.
 - Touch task files the session did not change
 - Widen what a writing step reads when the baseline is unusable. Widening a read is safe and widening a write stubs a surface for every file in the repository.
+- Write the requirements record. It states identity, and a fold reads one session where a review reads the whole project.
 - Edit `CLAUDE.md` inline. Every change there goes through a diff-and-approve gate, so this skill only flags.
 - Create a context entry, or move or delete a plan. A plan is settled by the merge, and `canon tasks archive` carries it.
 - Overwrite a file a promotion block routes to. A destination that already holds a page is a merge for a person, and folding over it discards work this skill never read.

package/claude/skills/context-fold/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: context-fold
-description: Folds a session into the project's context entries, requirements, architecture, and wireframes, marks the outcomes the diff shipped `[x]` on the task board, and archives the plans those tasks cite. Use when asked to "fold the session into context", "update the context entries", "sync the planning records", when design or requirements changed mid-cycle, after a pivot, or before shipping. Do NOT use for `README.md` or `docs/`, which is `docs-sync`, or to create or archive a task file, which is `task-board`.
+description: Folds a session into the project's context entries, architecture, and wireframes, marks the outcomes the diff shipped `[x]` on the task board, and archives the plans those tasks cite. Use when asked to "fold the session into context", "update the context entries", "sync the planning records", when design or requirements changed mid-cycle, after a pivot, or before shipping. Do NOT use for `README.md` or `docs/`, which is `docs-sync`, or to create or archive a task file, which is `task-board`.
 ---
 
 # Context fold
@@ -82,13 +82,15 @@ The verb resolves the board at the main worktree root in-process, which is the r
 
 Read `ok` and `reason` out of that record rather than the exit. An operator's shell profile may wrap `canon` in a function that runs the binary and then a second command and takes the second status, which flattens every non-zero exit to zero. A refusal arriving as success leaves the outcome unmarked while the chain moves on, so the board reports shipped work as open and the next session re-plans it.
 
-**REQUIREMENTS.md, ARCHITECTURE.md, DESIGN.md, a wireframe surface file (flat or nested)**
+**ARCHITECTURE.md, DESIGN.md, a wireframe surface file (flat or nested)**
 
+- Never write `canon/REQUIREMENTS.md`. Report a requirements change in After completion.
 - Update only the sections affected by session decisions.
 - Do not rewrite sections unrelated to what changed.
 - Rewrite a restated or superseded statement in place rather than appending the replacement beside it. State the fact that stands and keep the earlier reasoning only where it is the alternative that lost, per `${CLAUDE_SKILL_DIR}/../../standards/context.md` and `${CLAUDE_SKILL_DIR}/../../standards/architecture.md`.
 - Follow `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` and the `write-human` skill for all edits.
-- Write a session decision into the `canon/context/` entry for the domain it constrains, under that entry's `## Decisions`, by default. Touch `canon/ARCHITECTURE.md` only for a decision that fills one of the slots `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` names, however many domains its reasoning reaches.
+- Write a session decision into the `canon/context/` entry for the domain it constrains, under that entry's `## Decisions`, by default.
+- Touch `canon/ARCHITECTURE.md` only when a plan a matched task's `Plan:` line names states a decision filling a slot `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` names. A slot decision no plan carries goes to the domain entry.
 - Read the entry cap the record states before adding a decision to it. At the cap, merge two decisions or retire one to the domain entry it constrains, and name which in the report. Never compress a decision's prose to fit, and never pack two decisions under one heading.
 - Close a decision entry in `canon/ARCHITECTURE.md` with its verification anchor whenever this run writes that entry or amends its reasoning and that reasoning cites a measured number. Re-read the number against the tree first, since the marker records the read rather than the edit. `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` fixes the sentence.
 - Leave every decision entry this run did not write alone, anchored or not. The rule is scoped forward, so an entry written before it is dated by blame rather than by a read. Step 5 reports a stale anchor and no step writes one on an entry it did not amend.
@@ -107,9 +109,7 @@ Skip silently when the filter leaves nothing, which is every branch touching no
 
 Skip this step silently when `canon/ARCHITECTURE.md` does not exist at `pwd` or carries no decision entry with a verification anchor. A record written before the rule holds none, and a project is not told on every ship that nothing has been checked when the standard calls that state correct. When the baseline is unusable, scope the sweep to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the anchor sweep.`
 
-This step reports and never writes. The record carries no frontmatter, so an anchor is a sentence sharing a paragraph with the claim it marks, and a pass editing prose to mark prose has no structural guard against editing the claim beside it. A surface whose marker sits in YAML gets that separation for free and this one cannot.
-
-Step 3 holds the writer, and the two never meet. Anchoring fires when this run amends a decision, and this sweep fires when the diff moves a path under one, so a single step covering both would gate the anchor obligation on a signal that has nothing to do with it.
+This step reports and never writes. An anchor is a sentence sharing a paragraph with the claim it marks rather than a frontmatter field, and a pass editing prose to mark prose has no structural guard against editing the claim beside it. A surface whose marker sits in YAML gets that separation for free and this one cannot.
 
 Follow `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` for the anchor sentence this step matches on.
 
@@ -153,6 +153,8 @@ When Step 3 met the architecture record's cap, add one line naming what it did t
 
 `↪ Architecture at cap: merged <heading> into <heading>` or `↪ Architecture at cap: retired <heading> to <context entry>`
 
+When Step 2 noted a requirements change: `↪ Direction changed this session: run document-health on canon/REQUIREMENTS.md`
+
 Step 10 adds its own lines when it applied or reported a finding, in the exact shape `${CLAUDE_SKILL_DIR}/references/classify.md` gives them under its own Report section. Do not shorten or paraphrase those lines here or in the reply, since the quote and the reason are what a reader checks the finding against.
 
 If no files were updated and nothing was swept, output:

package/claude/skills/context-fold/references/anchor-sweep.md

@@ -43,11 +43,11 @@ What this misses is a claim whose number moved with no matching citation in the
 
 ## What the sweep never does
 
-- Write into the entry. The record carries no frontmatter, so the marker and the claim share one paragraph and an edit reaching one reaches the other.
+- Write into the entry. The anchor is a sentence rather than a frontmatter field, so the marker and the claim share one paragraph and an edit reaching one reaches the other.
 - Refresh an anchor. Re-reading the number is the act the marker records, so a date written by a pass that measured nothing is the false confidence the marker exists to prevent.
 - Flag an unanchored entry. The standard scopes the rule forward, and an entry written before it is dated by blame rather than by a read.
 
-The session amending a decision writes its anchor, which Step 3 already requires.
+The session amending a decision writes its anchor, which Step 3 already requires. Step 3 holds the writer, and the two never meet. Anchoring fires when this run amends a decision, and this sweep fires when the diff moves a path under one, so a single step covering both would gate the anchor obligation on a signal that has nothing to do with it.
 
 ## Output
 

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

@@ -46,7 +46,7 @@ A rule belongs in this skill only when all four hold. Three of the four reject m
 3. **It is judgment rather than a threshold.** A contrast ratio has a number and belongs to the floor. Whether a palette reads cheap has no number and belongs here.
 4. **One line states it, and something could violate that line.** "Use whitespace intentionally" fails, since nothing could break it. "No three consecutive image-and-text splits" passes, since it can be counted.
 
-A rule failing any of the four is recorded as considered and declined rather than argued again, in the reference where it would have gone.
+A rule failing any of the four is recorded as considered and declined rather than argued again, in `references/adopted.md`, under the reference where it would have gone.
 
 ## Must not
 

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

@@ -115,9 +115,11 @@ It states no values. A value belongs to the project's own design document.
 
 ## The rest of the catalog
 
-Read `${CLAUDE_SKILL_DIR}/references/tells.md` before handing over anything a model drafted, and whenever output satisfies every rule here and still reads generic. The ten above are the common cases. It holds the rest, plus the countable composition limits, the first-screen budget, and the record of which external items were adopted, which declined, and why.
+Read `${CLAUDE_SKILL_DIR}/references/tells.md` before handing over anything a model drafted, and whenever output satisfies every rule here and still reads generic. The ten above are the common cases. It holds the rest, plus the countable composition limits and the first-screen budget.
 
-Skip it on a small change to a surface with a settled direction. The catalog is a diagnostic and costs a read on every invocation that does not need one.
+Skip `tells.md` on a small change to a surface with a settled direction. The catalog is a diagnostic and costs a read on every invocation that does not need one.
+
+Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It records which external catalog items were adopted, which declined, and why.
 
 ## When it reads almost right
 

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

@@ -0,0 +1,40 @@
+---
+title: Adopted and declined
+description: Which external design catalogs this skill adopted from, which items it declined, and why, so a later session extends the position instead of re-deriving it
+---
+
+# Adopted and declined
+
+External catalogs were read and filtered rather than imported. This file 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 from the catalogs
+
+**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.
+
+## Declined from the systems reference
+
+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.
+
+## 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.

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

@@ -46,7 +46,7 @@ Documentation, articles, reference pages, learning material. The reader arrived
 ## Kinds this file does not cover
 
 - **Transactional flows** such as checkout, sign-up and settings are read as application UI. Their distinctive rules are state coverage and error recovery, which the `ui` governance rules already carry.
-- **Presentation surfaces** such as slide decks are governed by `${CLAUDE_SKILL_DIR}/../../standards/slides.md` and drafted by `draft-slides`. Take the layer ordering and the floor from the body and the rest from there.
+- **Presentation surfaces** such as slide decks are drafted by `draft-slides`, which carries the deck's own design rules. Take the layer ordering and the floor from the body and the rest from that skill.
 - **Terminal and text-mode surfaces** have no layout engine and their own color rules, stated where the writing surface is decided rather than here.
 
 A read naming any of the three above takes the body's rules and says it has no per-kind guidance, naming the surface that governs it. A read naming a kind this file does not list at all says so rather than borrowing the nearest section.

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/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

@@ -59,6 +59,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 +97,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

@@ -35,7 +35,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-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