@erclx/canon 4.102.0 → 4.103.0

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.102.0",
+  "version": "4.103.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -91,12 +91,15 @@ Run `canon tooling diff <stack> <target>` for the list resolved against a real t
 
 ### web
 
+- `.github/workflows/readme-screenshot.yml`
 - `.github/workflows/verify.yml`
 - `.vscode/extensions.json`
 - `.vscode/settings.json`
 - `e2e/home.spec.ts`
 - `e2e/screenshot.ts`
 - `eslint.config.js`
+- `scripts/lib/preview-server.sh`
+- `scripts/readme-screenshot.sh`
 - `scripts/screenshot.sh`
 - `scripts/verify.sh`
 - `scripts/worktree-port.sh`

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

@@ -88,7 +88,7 @@ Report each dispatch by naming the target, the clone, the branch, the model, and
 
 1. Address every finding whatever its severity. A minor is a finding, and a reviewer calling one non-blocking does not close the pass that raised it.
 2. Resolve who holds the branch before dispatching anybody. Run `canon sessions list --branch chore/agents --repository <clone> --json` and read the count rather than the first row.
-   - A live session holds it: send that session the findings and name `canon:review-address` for it to run, which is step 6 of `## The worker role` and the step that session already stands at. Never name this skill in that message. This body carries `disable-model-invocation: true`, which blocks the `Skill` tool rather than only suppressing an auto-trigger, and a session acting on an inbound message reaches a skill that way and no other, so a message naming this one halts the address leg with the branch built and the findings unread. A launch prompt is the one route to a flagged body, which is why the dispatch above names this skill and this message must not. Assuming the worker was gone is what one hand-driven pass got wrong. All four sessions that opened those pull requests were still alive holding their worktrees hours later, and of two fresh addressers sent over them, one refused on the worktree lock and one cut a second worktree on the same branch, which would have put two sessions pushing to one ref.
+   - A live session holds it: send that session the findings and name `canon:review-address` for it to run, which is step 7 of `## The worker role` and the step that session already stands at. Never name this skill in that message. This body carries `disable-model-invocation: true`, which blocks the `Skill` tool rather than only suppressing an auto-trigger, and a session acting on an inbound message reaches a skill that way and no other, so a message naming this one halts the address leg with the branch built and the findings unread. A launch prompt is the one route to a flagged body, which is why the dispatch above names this skill and this message must not. Assuming the worker was gone is what one hand-driven pass got wrong. All four sessions that opened those pull requests were still alive holding their worktrees hours later, and of two fresh addressers sent over them, one refused on the worktree lock and one cut a second worktree on the same branch, which would have put two sessions pushing to one ref.
    - No live session holds it: dispatch a fresh worker into that clone and brief it with the findings, since it holds none of the reasoning behind the diff.
    - More than one row: report the ambiguity and stop rather than picking among candidates.
 3. Re-review when the answer lands, scoped to the commits added since. A worker's reply never closes a target. One fix for two minor findings closed both and introduced four more, every one of them in prose that fix added, and a loop trusting the reply merges that.
@@ -101,11 +101,12 @@ One session, one target, from the worktree entry to the merge of the branch it o
 
 1. Confirm the clone is current. Fetch, then compare against the origin's default branch. Report a checkout that is behind and stop, rather than branching from a stale base.
 2. Enter a worktree. Invoke `canon:session-worktree chore/agents`, which takes the branch as its tier 0 argument and enters a linked worktree inside this target. Branching in the checkout itself is what this avoids, since the operator may be working in it.
-3. Diagnose and repair. Invoke `canon:canon-operator`, which reads `canon sync --check . --json` and routes each finding to the command or the skill that owns it. Do not restate that routing here and do not edit a managed file by hand.
-4. Commit and open the pull request through `canon:git-commit` and `canon:git-pr`, handing each the fixed shape above rather than taking the title the generator derives from the diff.
-5. Announce as the pull request opens, carrying its URL, its number, and the branch, to whoever dispatched this session. That transition is the one moment only this session can observe.
-6. Answer the review. Invoke `canon:review-address`, which pulls the findings and the CI state on this branch's open pull request, fixes each in the working tree, replies, and pushes. Answer every finding whatever its severity.
-7. Stop there. Do not mark the pull request ready, do not merge, and do not declare the review closed. A narrow re-review posts `## Review closed`.
+3. Check what this target holds. Invoke `canon:target-check`, which reports per domain what the target carries against what the toolkit ships and repairs nothing. It runs before any repair so the wave reads one stated set of domains per target rather than whatever each session decided to examine.
+4. Diagnose and repair. Invoke `canon:canon-operator`, which reads `canon sync --check . --json` and routes each finding to the command or the skill that owns it. Do not restate that routing here and do not edit a managed file by hand.
+5. Commit and open the pull request through `canon:git-commit` and `canon:git-pr`, handing each the fixed shape above rather than taking the title the generator derives from the diff.
+6. Announce as the pull request opens, carrying its URL, its number, and the branch, to whoever dispatched this session. That transition is the one moment only this session can observe.
+7. Answer the review. Invoke `canon:review-address`, which pulls the findings and the CI state on this branch's open pull request, fixes each in the working tree, replies, and pushes. Answer every finding whatever its severity.
+8. Stop there. Do not mark the pull request ready, do not merge, and do not declare the review closed. A narrow re-review posts `## Review closed`.
 
 Send a block out as a message before it becomes an interactive prompt. A session already waiting on input never reaches the tool round an inbound message drains at, so an answer relayed afterwards arrives under the open question and changes nothing.
 

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

@@ -16,6 +16,7 @@ A README whose real documentation lives in `canon/context/` or `docs/` was a sec
 - Read `standards/readme.md` before drafting, since its `## Voice` section is scoped to a repository-root README and yields to `write-human`'s reference voice everywhere else
 - Detect every project type the standard's `## Content` list applies to, from the manifest and the tree, rather than drafting against the closest single type
 - Treat an existing README with no H1, or with headings that name only the scaffold that wrote it, as unedited generator output to draft over rather than a page to sync section by section
+- Read the header block's slots off the repository, being the mark, the claim, the live link, and the product screenshot, and skip the link and the screenshot for a project with no page, so every element traces to a file or field the project holds
 - Verify a candidate badge by the value it would render rather than by a fetch's status code, since a badge service answers 200 for a query it cannot satisfy
 - Confirm the resolved path, the detected types, the badge candidates, and the full content with the user before writing, since project-type detection and badge selection are judgment calls with no diff to preview them against
 
@@ -23,6 +24,7 @@ A README whose real documentation lives in `canon/context/` or `docs/` was a sec
 
 - Rewrite an authored README. One carrying an H1 that names the project refuses toward `docs-sync`.
 - Offer to overwrite an authored README on the refusal path, or propose conforming it to what this skill would have drafted. A target project's own citations into its README are invisible from here, so the refusal reports rather than proposes.
+- Invent a screenshot or a mark the project does not hold, or write a placeholder path for one. An omitted slot is a correct page and an invented image is the failure.
 - Assume this skill's own invocation frequency needs no check. Whether anything reaches for it beyond an author typing its name has no answer at creation time, so a review pass some months in should read that back rather than take the assumption on faith.
 
 ## Guards

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

@@ -27,10 +27,16 @@ Read these files in parallel:
 - Read the project's manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, or equivalent) for a `bin` field or CLI entry point, an installable package name, and its declared dependencies.
 - Check for a `claude/skills/` or `.claude/skills/` folder, a `plugin.json`, or a marketplace manifest, each naming an agent-facing or marketplace-distributed surface.
 - A project is often several of these at once. Note every type that applies rather than stopping at the first match, since the Draft step covers each one the project actually is.
+- Check for a page. A dependency on a site framework or a site config file in the manifest or the tree marks a project as having one. Read a live URL separately, from a `homepage` field or a deploy config, since a project can have a page and no known URL.
+- A monorepo can carry a page in one package and a CLI in another, so both signals may fire. Report each rather than picking one.
+- Look for the mark and the screenshot among images the project already commits: scan the existing README for image references, then the asset and public folders.
 
 ## Draft
 
 - Draft the page against `${CLAUDE_SKILL_DIR}/../../standards/readme.md`: H1, a 2-3 sentence description in plain text, then the required sections, then whichever optional sections and per-type content the Detect step found.
+- Open the page with the standard's header block, filling each slot from what Detect found: mark, title, badges, a one-line claim from the manifest description, the live link, then the product screenshot.
+- Fill the screenshot slot only with an image the project already commits, referenced with alt text naming what it depicts. This skill cannot capture one. Omit the slot when no such image exists and say so in the preview. Never write a placeholder path.
+- Omit the link and the screenshot for a project with no page, and the mark for a project with none, without a note in the drafted page. A project with a page and no known URL gets the screenshot slot, and the Confirm step asks for the link.
 - Cover every applicable project type from the standard's `## Content` list rather than picking the closest one.
 - Candidate badges: check for a published package (a registry field in the manifest), a CI workflow, and a `LICENSE` file.
 - State each candidate's rendered value in the preview rather than trusting a fetch's status code, since a badge service answers 200 for a query it cannot satisfy.
@@ -38,7 +44,8 @@ Read these files in parallel:
 
 ## Confirm
 
-- Show the resolved path, the detected project types, the badge candidates and what backs each one, and the full drafted content before writing.
+- Show the resolved path, the detected project types, the header slots filled or skipped with the reason for each, the badge candidates and what backs each one, and the full drafted content before writing.
+- The skill can confirm that an image file exists and is referenced, and it cannot verify the picture shows the product. Ask the user to look at it in the preview.
 - Confirm with the user. This skill waits for that answer rather than treating the tool permission dialog as the gate, since project-type detection and badge selection are judgment calls with no diff to preview them against.
 
 ## Write
@@ -52,6 +59,7 @@ Read these files in parallel:
 
 **Target:** `<path>` (root | nested)
 **Detected:** `<project types>`
+**Header:** `<each slot as filled (source) or skipped (reason)>`
 **Badges:** `<candidates, or none>`
 
 ```markdown

package/claude/skills/target-check/REQUIREMENT.md

@@ -0,0 +1,42 @@
+---
+name: target-check
+description: What the target check is for, the gap it closes, and the repairing it refuses
+---
+
+# Target check requirement
+
+## Gap
+
+Without this skill, a session landing in a target project decides for itself what to look at. `canon-rollout` dispatches a worker into each target and gets a pull request out, and nothing told that worker what a target holds against what the toolkit ships, so a wave is only as good as whatever each session happened to examine. Four hand-driven repairs across two waves examined four different sets of surfaces and none of them read the same domain twice.
+
+The second half of the gap is silence. A session that runs a verb the target's binary does not carry, or reads a report key that is absent, has no instruction telling it apart from a clean answer, so an unexamined domain reaches the reader as a domain that passed.
+
+## Must
+
+- Report one section per domain, so a reader can tell which surface a finding came from
+- Read each domain through the verb that already owns that comparison, rather than inspecting the same files by hand, since the verb is the surface under test
+- Take the installed domains from the catalog the report returns rather than from a list in the body, so a domain the toolkit adds later needs no edit here
+- Report a refusal, an absent key, and a missing subcommand as unread, naming the cause, so an unexamined domain never reads as a passing one
+- Report the Claude harness as unchecked on every run while no verb answers for it, as a row rather than an omission
+- Report the toolkit version first, since a target behind on the binary explains every unread section under it
+- Run every read non-interactively by default, because every caller in the near term is a dispatched worker with nobody present to answer a prompt
+
+## Must not
+
+- Repair a finding, write a file in the target, or open a pull request. A check that repaired as it read leaves the reader unable to tell a finding from a fix, and the wave decides what to fix.
+- Emit a verdict across the domains. Five answer from verbs and one answers from nothing, so any roll-up is a figure that lies about the sixth.
+- Answer the harness domain by file inspection. A section reaching a verdict from a hand-rolled read is exactly what the other five sections avoid, and a hole a reader can see is worth more than a number nobody can trace.
+- Hardcode a stack, rule, or domain name. A name written into the body goes stale on its own cadence.
+
+## Guards
+
+- `canon` absent from the path: stop, since no domain can be read
+- No `.claude/` at the working root: stop and name the scaffold command, since nothing is installed to check
+- The working root is the toolkit itself: stop and name `canon-rollout`, since this skill reads what the toolkit installed into rather than the source
+
+## Out of scope
+
+- Document health, which asks a content question rather than a structural one and takes its own surface
+- Repairing anything a section names. Each routes to the command or skill that owns it.
+- A target's own routes, which `canon inventory` reports as a listing rather than a verdict and which is a fact about the project rather than about what the toolkit ships
+- First-time scaffold, which is `setup-init`, and per-intent routing of a single toolkit operation, which is `canon-operator`

package/claude/skills/target-check/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: target-check
+description: Reports what a target project holds against what the toolkit currently ships, one section per domain, reading through `canon` verbs rather than inspecting files. Use when asked to "check this target", "what has this project fallen behind on", "is this project current with the toolkit", "run the target check", or as the first thing a rollout worker runs after entering a target. Do NOT use to repair a finding, which the owning command or skill does, and do NOT use in the toolkit repository itself.
+---
+
+# Target check
+
+Reports, per domain, what this target holds against what the toolkit currently ships. It reports and never repairs, so whoever read the report decides what to fix.
+
+Six domains carry the report. Five answer from a verb that already exists and the sixth answers from nothing, which it says rather than omitting. `${CLAUDE_SKILL_DIR}/references/domains.md` holds what each one reads, what current looks like, and where a finding routes. This body holds the order, the guards, and the report shape.
+
+## Guards
+
+- `canon` absent from the path: stop. `❌ canon is not on PATH, so no domain can be read.`
+- No `.claude/` directory at the working root: stop. `❌ No .claude/ here, so nothing is installed to check. Run canon init first.`
+- A `claude/skills/` folder at the working root, with no leading dot: stop. `❌ This is the toolkit itself rather than a target. canon-rollout takes a change out to the targets.` A target receives skills at `.claude/skills/` and authors none, so the spelling without the dot separates the source from what it installs into.
+- Run every command under `CANON_NON_INTERACTIVE=1` and prompt at no point. Every caller in the near term is a worker a wave dispatched, with nobody present to answer, so the non-interactive path is the only path rather than a flag a caller remembers.
+- Branch on each record's own fields rather than on an exit status. An operator's shell profile may wrap `canon` in a function whose status comes from a trailing command, which reports every refusal as success.
+
+## Step 1: read the reports
+
+Run these from the target root, in parallel:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon sync --check . --json
+CANON_NON_INTERACTIVE=1 canon context audit --json
+```
+
+The first answers five domains from one read, being `skew`, `domains`, `seeds`, `tooling`, and the layout fields `unmigrated`, `superseded`, and `reverse`. The second deepens a domain that first read only counts.
+
+Then run `CANON_NON_INTERACTIVE=1 canon records validate <kind> --json` once per record folder the target carries, taking `<kind>` from what is present under the record root rather than from a list held here.
+
+### The tooling read takes a stack, always
+
+The tooling comparison runs last, because it needs a value the first read returns. Take `<stack>` from the first name in the report's `tooling.chain`, which records the stack nearest the target, and pass it:
+
+```bash
+CANON_NON_INTERACTIVE=1 canon tooling sync --check <stack>
+```
+
+Refuse the domain and report it unread when `chain` names nothing, rather than running the command bare. A bare call reaches the stack prompt, and the non-interactive variable this skill's Guards make mandatory resolves that prompt to the first option in the catalog instead of refusing it. The domain would then compare every target against whichever stack sorts first, and report drift that is an artifact of the wrong comparison rather than anything the target did. It would fire on every run rather than on an edge, since nothing about the target is read on the way to that default.
+
+Read every installed domain from the catalog the report returns rather than from a name written into this body. `domains` enumerates what the target actually stamped, so a domain the toolkit adds later reaches this report with no edit here, and a name hardcoded here is a bug.
+
+## Step 2: report each domain
+
+Report the six in this order, one section each, per `${CLAUDE_SKILL_DIR}/references/domains.md`:
+
+1. Toolkit version
+2. The `canon/` folder
+3. Governance rules
+4. Tooling
+5. Seeds
+6. The Claude harness
+
+Give each section three things and nothing else: the state, the evidence the state was read from, and the command or skill that repairs it. Naming the repair is not running it.
+
+### Unread is not current
+
+A refused command, an absent key, or a subcommand the target's binary does not carry leaves a domain unread. Report it as unread, name which read could not be taken, and name the cause. Reading an absent key as an empty answer reports a clean target to a project nothing looked at, which is the failure this report exists to replace.
+
+The version domain is what makes that case legible rather than mysterious. A target a release behind is missing verbs the other five sections call, so the version section is read first and its state explains every unread section under it.
+
+### No verdict across the six
+
+Report a state per domain and no number over them. Five sections answer from verbs and the sixth answers from nothing, so any roll-up is a figure that lies about the sixth. `canon inventory` reports a listing rather than a verdict for the same reason, and it is absent from the six here because its subject is a target's own routes rather than what the toolkit ships.
+
+## Step 3: stop at the report
+
+Repair nothing, write no file in the target, and open no pull request. A wave decides what to fix after reading this, and a check that repaired as it read would leave the reader unable to tell a finding from a fix.
+
+## Output
+
+Lead with the table, then one detail block per domain that is not current:
+
+```markdown
+Target check: `<path>`, against canon `<version>`.
+
+| Domain           | State                     | Evidence                          |
+| ---------------- | ------------------------- | --------------------------------- |
+| Toolkit version  | current / behind / unread | `skew.installed` against `latest` |
+| `canon/` folder  | current / behind / unread | what the layout fields named      |
+| Governance rules | current / behind / unread | the per-state counts              |
+| Tooling          | current / behind / unread | what a sync would change          |
+| Seeds            | current / behind / unread | the per-state counts              |
+| Claude harness   | unchecked                 | no verb reads it                  |
+
+No overall verdict. The harness row is unchecked rather than passing.
+```
+
+Keep the harness row `unchecked` on every run until a verb reads it. A domain left out of the table reads as a domain that passed, which is the one shape the row exists to prevent.

package/claude/skills/target-check/references/domains.md

@@ -0,0 +1,88 @@
+---
+title: Target check domains
+description: What each of the six domains reads, what counts as current, and where a finding routes
+---
+
+# Target check domains
+
+One section per domain, in the order the body reports them. Each names the read, what current looks like, what the states mean, and the command or skill a finding routes to. Naming a repair is not running one.
+
+## 1. Toolkit version
+
+Read `skew` off `canon sync --check . --json`. It carries `state`, `installed`, and `latest`.
+
+- Current: `state` reads `current`, or `installed` equals `latest`.
+- Behind: `installed` trails `latest`. Name both versions.
+- Unread: no `skew` key, or the whole report refused. Say the version could not be read and treat every section under it as read against an unknown binary.
+
+Routes to `canon upgrade`, which reinstalls with the manager that installed it.
+
+This domain is first because it conditions the other five. A target a release behind carries an older verb surface, so a section reporting unread below may be reporting a missing subcommand rather than a missing surface, and the version state is what separates those two readings.
+
+## 2. The `canon/` folder
+
+Read three fields off the same report, then two verbs:
+
+- `unmigrated`: a domain still at the root layout with nothing under `.claude/`. The most urgent finding, because such a domain reports no drift of its own while being entirely behind.
+- `superseded`: a file a newer seed folder replaced. No command moves it, since the content is the project's own.
+- `reverse`: `unclaimed` names folders at roots the toolkit stopped shipping, each with an `attribution` of `dropped`, `unattributed`, or `project`. `migrations` names a proposal-only skill with a live case here and the `reason` behind it.
+- `canon context audit --json`: required sections, entry length, citations, and index drift across the context folder.
+- `canon records validate <kind> --json`, once per record folder the target carries.
+
+- Current: `unmigrated` and `superseded` both empty, `reverse.unclaimed` carrying nothing outside `project` attribution, and both verbs finding nothing.
+- Behind: any of those carrying an entry. Name the entry and its attribution.
+- Unread: `historyUnavailable` set on `reverse`, a `reverse` key the report does not carry at all, or either verb refusing. A missing `reverse` key is a binary predating the field rather than a target with nothing unclaimed.
+
+Routes by finding. `unmigrated` routes to a relocation the user runs, since no command moves it. `superseded` routes to `migration-superseded`. A `migrations` entry routes to the skill its `skill` field names, spelled as the report spells it. An `unclaimed` folder carrying `project` attribution routes nowhere, since history proved the project owns it.
+
+## 3. Governance rules
+
+Read `domains` off the report and take every entry it carries rather than naming governance here. Each entry carries `stamped`, per-state `counts`, and `entries` with a `state` and a `rel` path.
+
+The states are `matching`, `stale`, `customized`, `drifted`, `orphaned`, `stranded`, and `missing`.
+
+- Current: every count but `matching` reads zero.
+- Behind: any other count is non-zero. Report the counts and name the paths behind `stale` and `missing`, which a sync repairs, separately from `customized` and `drifted`, which the project wrote and a sync would overwrite.
+- Unread: `stamped` false with no entries, or the domain absent from the array while the target carries installed rules.
+
+Routes to `canon <domain> sync`, or to `canon sync` for every installed domain at once. Read the `canon-cli` skill before naming either, since a command name says nothing about what it does to a file already there, and a `customized` entry is exactly the file a sync takes back.
+
+## 4. Tooling
+
+Read the `tooling` block off the report first, because the comparison command needs a value it carries.
+
+Read `measured` before anything under it. Every count is zero when `measured` is false, which is an absence of measurement rather than a measured zero.
+
+On a measured report, take `<stack>` from the first name in `chain` and run `canon tooling sync --check <stack>`. Never run it bare. The stack argument is what the target carries, and omitting it reaches a prompt that the non-interactive variable resolves to the catalog's first entry rather than refusing, which compares the target against a stack it does not use and reports the difference as drift.
+
+- Current: `measured` true, `chain` naming stacks the toolkit still ships, and `--check` reporting nothing it would change.
+- Behind: `--check` naming files it would replace, or `counts.gitignore` carrying missing managed entries.
+- Unread: `measured` false. It splits three ways, and each is reported as unmeasured with its cause named rather than as clean. An empty `chain` at a workspace root is by design, since a chain there would guess at what the packages hold. An empty `chain` anywhere else means no tooling install is recorded. A `chain` carrying names the toolkit no longer ships means injecting would write against a retired name.
+
+Routes to `canon tooling sync <stack>`, or to `canon tooling inject --gitignore <stack>` for ignore entries alone, taking `<stack>` the same way the comparison above does. An unmeasured report names no stack, so it routes to neither.
+
+`canon tooling diff` is the verb this section wants and it does not exist yet. `--check` answers the same question today and stays working as an alias by design, so the retarget when that verb lands is a change of name rather than of behavior.
+
+## 5. Seeds
+
+Read `seeds.entries` off the report. Each entry is `matching`, `stale`, `drifted`, or `missing`, and the set spans `CLAUDE.md`, the `canon/` records, the generated indexes, `.claude/settings.json`, and the hook scripts under `.claude/hooks/`.
+
+- Current: every entry reads `matching`.
+- Behind: anything else. Report `stale` and `missing` separately from `drifted`, which means the content matches no version the toolkit ever published, so the project wrote it.
+- Unread: `historyUnavailable` set on `seeds`, which leaves every difference unattributed. Say so rather than reporting a file as untouched.
+
+Routes to `seed-sync`, which proposes per-section edits without overwriting a customization. It is a proposal rather than a write, which is why a `drifted` `CLAUDE.md` routes there rather than to a sync.
+
+A seed entry matching says the file's bytes match the shipped seed. It says nothing about whether the harness those files configure is wired, which is the next domain.
+
+## 6. The Claude harness
+
+No verb reads this domain. Report it `unchecked` on every run and report it as a row rather than omitting it.
+
+What goes unread is whether the target's hooks fire, whether `.claude/settings.json` registers them, which plugin version the target's sessions actually load, and whether the marketplace cache matches what the toolkit ships.
+
+Confirm the gap against the live surface rather than against a list held here, by reading `canon claude --help` and the help of any subcommand under it that sounds like an answer. A list written into this file freezes on the day it was written and would report a gap a later release had closed. `canon claude skills drift` is the verb that comes nearest, and it reads the toolkit's own history against a ref, which says what moved upstream rather than what this target holds. Report the domain checked, with what the verb answered, on the run where a verb does answer one of the four questions above.
+
+Reading it by file inspection is the alternative and it is refused. Every other section here answers from the verb under test, and a section answering from a hand-rolled read of the same files reaches a verdict nothing else in the report is entitled to make. A hole a reader can see is worth more than a number nobody can trace.
+
+`canon claude plugin-update` is what an operator runs to bring a cache forward. Name it as the action available rather than as a repair for a finding, since no finding was taken.

package/claude/skills/ui-checklist/SKILL.md

@@ -31,6 +31,23 @@ Group visual items by feature area. Use `- [ ]` checkbox syntax, and write each
 - [ ] <action> → <expected visual result>
 ```
 
+## The widths block
+
+A screenshot shows one width, so a reviewer cannot tell from the picture alone whether any other width was looked at. When a change touches layout, spacing, or anything responsive, put this block above the visual items, since it frames what the screenshots beside it can support:
+
+```markdown
+**Widths:**
+
+Seen at: <the widths the reviewer looked at>
+Not seen at: <the widths nobody looked at, or "none">
+```
+
+Leave both lines for the reviewer to complete. This session cannot verify a width, so the block asks what was seen and never asserts coverage. Fix no width list in the block, since which widths matter belongs to the project.
+
+Keep the `Not seen at:` line even when the answer is "none", so an omission reads as a claim rather than a gap.
+
+Omit the block when the change cannot differ by width, such as copy, color, or a state that renders the same everywhere, the way the missing-test heading is omitted below.
+
 ## The missing-test list
 
 Name every automatable change this branch ships with no test, one per line, with the layer `test-craft` would place it at. Do not write the test and do not read the project's test config to write one against.

package/docs/agents/commands.md

@@ -22,7 +22,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon indexes regen`            | Regenerate `index.md` files from sibling frontmatter                                                                                                                                                                                                                                                                         |
 | `canon indexes list [path]`      | Flatten every folder index under a path into one `{path, title, description}` catalog (`--json`)                                                                                                                                                                                                                             |
 | `canon docs [topic]`             | Emit toolkit reference docs (`list`, or a topic by name)                                                                                                                                                                                                                                                                     |
-| `canon design render`            | Render `canon/DESIGN.md` tokens to HTML and CSS                                                                                                                                                                                                                                                                              |
+| `canon design render`            | Render `canon/DESIGN.md` tokens to HTML and CSS, declaring each vendored face the typography table names with `--embed-fonts`                                                                                                                                                                                                |
 | `canon design regen`             | Rewrite this repository's `canon/DESIGN.md` and `src/design/base.css` from `src/design/tokens.ts`                                                                                                                                                                                                                            |
 | `canon design board`             | Generate a static page set indexing tokens, surfaces, wireframes, past candidates, components, and references against a caller-resolved `--root` (`--out`), defaulting to the main worktree                                                                                                                                  |
 | `canon design css`               | Emit the design tokens and components as CSS on stdout (`--no-components` for properties alone)                                                                                                                                                                                                                              |

package/docs/target-projects.md

@@ -215,6 +215,8 @@ Neither `canon sync --check` nor any other command notices a surface still sitti
 
 `canon sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next.
 
+`canon:target-check` is the same reading grouped by domain rather than by cause, run from inside the project. It reports the toolkit version, the `canon/` folder, governance rules, tooling, and seeds from the verbs that own each comparison, and reports the Claude harness as unchecked because no verb reads it. It repairs nothing, so it is what to run before deciding rather than instead of deciding.
+
 #### The binary first
 
 The report opens by naming the binary running it. The installed version reads against the newest published one, and a version behind that points you at `canon upgrade`, since every section under it is a reading taken by whichever toolkit you happen to have. An unreachable registry reports unknown with its reason rather than failing, so `--exit-code` still gates on the drift the check measured locally and an offline machine stays green.

package/docs/workflow/ai-workflow.md

@@ -289,16 +289,17 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Keep the project current with the toolkit
 
-| Skill                            | When to use                                                                        |
-| -------------------------------- | ---------------------------------------------------------------------------------- |
-| `canon:seed-sync`                | After a toolkit update, to reconcile installed seeds without losing customizations |
-| `canon:migration-claude-md`      | When `CLAUDE.md` grew past what always-load context should carry                   |
-| `canon:migration-context`        | When `docs/` holds agent-flavored files belonging in `canon/context/`              |
-| `canon:migration-superseded`     | When a drift report names a `.claude/` file a folder has replaced                  |
-| `canon:migration-standards-drop` | When the project still holds an installed `.claude/standards/` tree                |
-| `canon:canon-feedback-file`      | When something in the toolkit is broken, missing, or off                           |
-| `canon:canon-feedback-triage`    | In the toolkit repo, to work through the open feedback issues                      |
-| `canon:canon-rollout`            | In the toolkit repo, to take one change out to every consuming project at once     |
+| Skill                            | When to use                                                                            |
+| -------------------------------- | -------------------------------------------------------------------------------------- |
+| `canon:target-check`             | In a target project, to report per domain what it holds against what the toolkit ships |
+| `canon:seed-sync`                | After a toolkit update, to reconcile installed seeds without losing customizations     |
+| `canon:migration-claude-md`      | When `CLAUDE.md` grew past what always-load context should carry                       |
+| `canon:migration-context`        | When `docs/` holds agent-flavored files belonging in `canon/context/`                  |
+| `canon:migration-superseded`     | When a drift report names a `.claude/` file a folder has replaced                      |
+| `canon:migration-standards-drop` | When the project still holds an installed `.claude/standards/` tree                    |
+| `canon:canon-feedback-file`      | When something in the toolkit is broken, missing, or off                               |
+| `canon:canon-feedback-triage`    | In the toolkit repo, to work through the open feedback issues                          |
+| `canon:canon-rollout`            | In the toolkit repo, to take one change out to every consuming project at once         |
 
 ### Generate an artifact on demand
 

package/governance/rules/ci/700-ci-workflow.md

@@ -39,6 +39,17 @@ paths:
 - Install with `bun install --frozen-lockfile`.
 - Key the Playwright browser cache on the Playwright version string, never a static key.
 
+## Commit-back
+
+- Commit a refreshed file back to the pull request branch only when the branch's own change moved it. Report the diff without committing when something outside the branch can move it, such as a count read at build time or a font that renders differently per machine, since that commit lands on a branch that never asked for it.
+- Commit only what a deterministic step regenerates from source, and run the diff check before the commit step so an unchanged capture pushes nothing.
+- Skip a pull request from a fork with `github.event.pull_request.head.repo.full_name == github.repository`, since the default token cannot push to a fork's branch.
+- Set the concurrency group on the ref so a newer push cancels the run committing onto a stale head.
+- Set `HUSKY: 0` on the commit step when the runner lacks a tool a hook shells out to.
+- Never commit back to the trunk. A commit with no pull request and no reviewer needs an operator's decision, not a workflow's.
+- Leave `workflow_dispatch` off a commit-back workflow. A manual run has no branch to commit onto, so the trigger would pass and do nothing.
+- Fail a template's first step while a path list still holds its placeholder, so an unfinished install fails loudly rather than never firing.
+
 ## Authority
 
 - Load the `canon:ci-workflow` skill for the workflow template and the per-project adaptation. Report it rather than proceeding silently when the skill does not resolve.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.102.0",
+  "version": "4.103.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-web-previews.ts

@@ -21,6 +21,7 @@ const root = new URL('../..', import.meta.url).pathname
 const { cssPath } = renderDesignDoc(
   `${root}${DESIGN_DOCUMENT}`,
   `${root}web/public/previews/design-tokens`,
+  { embedFonts: true },
 )
 
 const css = readFileSync(cssPath, 'utf8')

package/src/claude/cases/setup.ts

@@ -91,6 +91,14 @@ export const SETUP_CASES: readonly SkillCase[] = [
       'Take this change out to every project that installed the toolkit and get each one to a pull request.',
     expect: 'canon-rollout',
   },
+  // Reporting per domain is what separates this from canon-operator, which
+  // diagnoses on the way to running the operation an intent named. This answers
+  // one fixed question across a fixed domain list and repairs nothing.
+  {
+    prompt:
+      'Report what this project has fallen behind the toolkit on, domain by domain, and fix nothing.',
+    expect: 'target-check',
+  },
   {
     prompt:
       "This project needs its own coding rule that the toolkit doesn't ship.",

package/src/commands/design.ts

@@ -119,7 +119,11 @@ export function register(program: Command): void {
       'Output directory',
       creationRel(process.cwd(), SCRATCH, 'render', 'design'),
     )
-    .action((opts: { source: string; out: string }) => {
+    .option(
+      '--embed-fonts',
+      'Declare each vendored face the typography table names, and set the page body in the body stack',
+    )
+    .action((opts: { source: string; out: string; embedFonts?: boolean }) => {
       const sourcePath = resolve(process.cwd(), opts.source)
       const outDir = resolve(process.cwd(), opts.out)
       const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
@@ -133,7 +137,9 @@ export function register(program: Command): void {
       process.stderr.write(
         `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}Render design tokens${NC}\n`,
       )
-      const result = renderDesignDoc(sourcePath, outDir)
+      const result = renderDesignDoc(sourcePath, outDir, {
+        embedFonts: opts.embedFonts,
+      })
       process.stderr.write(
         `${GREY}│${NC} ${GREEN}✓${NC} ${result.htmlPath}\n${GREY}│${NC} ${GREEN}✓${NC} ${result.cssPath}\n${GREY}└${NC}\n`,
       )

package/src/design/css.ts

@@ -136,14 +136,17 @@ ${component.rules}`,
  * installed. Defaults to the mono stack's primary family; teach passes its own
  * three faces instead of widening this default for every consumer.
  */
-function fontFaceBlock(faces: readonly FontFace[]): string {
+export function fontFaceBlock(
+  faces: readonly FontFace[],
+  display: 'swap' | 'block' = 'swap',
+): string {
   return faces
     .map(
       (face) => `@font-face {
   font-family: '${face.family}';
   font-weight: ${face.weight};
   font-style: normal;
-  font-display: swap;
+  font-display: ${display};
   src: url(data:font/woff2;base64,${face.base64}) format('woff2');
 }`,
     )

package/src/design/render.ts

@@ -2,6 +2,9 @@ import { mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Cell, DesignDoc, Row } from '@/design/parse'
 import { parseDesignDoc } from '@/design/parse'
+import { fontFaceBlock } from '@/design/css'
+import type { FontFace } from '@/design/fonts'
+import { FONT_FACES } from '@/design/fonts'
 import { colorValue } from '@/design/tokens'
 
 export interface RenderResult {
@@ -19,19 +22,55 @@ const FAVICON_HREF = `data:image/svg+xml,${encodeURIComponent(
   `<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 10 80 80"><path d="M34,20 L15,28 L15,72 L34,80 Z M66,20 L85,28 L85,72 L66,80 Z" fill="${FAVICON_COLOR}" /><rect x="44" y="15" width="12" height="70" rx="2" fill="${FAVICON_COLOR}" /></svg>`,
 )}`
 
+export interface RenderOptions {
+  /**
+   * Declare each vendored face the typography table names, and let the page
+   * body take the body role's stack. Off by default, since a face is a large
+   * base64 block a target's render would otherwise grow by unasked.
+   */
+  readonly embedFonts?: boolean
+}
+
 export function renderDesignDoc(
   sourcePath: string,
   outDir: string,
+  options: RenderOptions = {},
 ): RenderResult {
   const doc = parseDesignDoc(sourcePath)
   mkdirSync(outDir, { recursive: true })
   const cssPath = join(outDir, 'design.css')
   const htmlPath = join(outDir, 'index.html')
-  writeFileSync(cssPath, buildCss(doc))
-  writeFileSync(htmlPath, buildHtml(doc))
+  const faces = options.embedFonts ? namedFaces(doc) : []
+  writeFileSync(cssPath, buildCss(doc, faces))
+  writeFileSync(htmlPath, buildHtml(doc, bodyFamily(doc, faces)))
   return { htmlPath, cssPath }
 }
 
+/** The vendored faces whose family appears in a typography `Family` cell. */
+function namedFaces(doc: DesignDoc): FontFace[] {
+  const named = new Set(
+    doc.typography.flatMap((row) =>
+      val(row, 'Family')
+        .split(',')
+        .map((family) => family.trim().replace(/^['"]|['"]$/g, '')),
+    ),
+  )
+  return FONT_FACES.filter((face) => named.has(face.family))
+}
+
+/** A stack lands raw in a `<style>` block, where HTML escaping does nothing. */
+const SAFE_STACK = /^[\w\s,'"-]+$/
+
+/** The stack the body role names, once a face for it is embedded. */
+function bodyFamily(doc: DesignDoc, faces: readonly FontFace[]): string {
+  if (!faces.length) return 'system-ui, sans-serif'
+  const row =
+    doc.typography.find((r) => slug(val(r, 'Role')) === 'body') ??
+    doc.typography[0]
+  const family = val(row, 'Family')
+  return SAFE_STACK.test(family) ? family : 'system-ui, sans-serif'
+}
+
 function slug(s: string): string {
   return s
     .toLowerCase()
@@ -105,7 +144,7 @@ function confidence(doc: DesignDoc): Confidence {
   return { tagged, total }
 }
 
-function buildCss(doc: DesignDoc): string {
+function buildCss(doc: DesignDoc, faces: readonly FontFace[]): string {
   const lines: string[] = [':root {']
   for (const row of doc.color) {
     if (val(row, 'Value')) {
@@ -135,7 +174,8 @@ function buildCss(doc: DesignDoc): string {
     }
   }
   lines.push('}')
-  return lines.join('\n') + '\n'
+  const root = lines.join('\n') + '\n'
+  return faces.length ? `${fontFaceBlock(faces, 'block')}\n\n${root}` : root
 }
 
 function escape(s: string): string {
@@ -178,7 +218,7 @@ function previewChrome(): string {
   return ['  :root {', ...lines, '  }'].join('\n')
 }
 
-function buildHtml(doc: DesignDoc): string {
+function buildHtml(doc: DesignDoc, bodyStack: string): string {
   const sections = [
     sectionPersonality(doc.personality),
     sectionColor(doc.color),
@@ -205,7 +245,7 @@ function buildHtml(doc: DesignDoc): string {
 <link rel="stylesheet" href="design.css">
 <style>
 ${previewChrome()}
-  body { font-family: system-ui, sans-serif; margin: 2rem; max-width: 960px; color: var(--preview-ink); background: var(--preview-paper); }
+  body { font-family: ${bodyStack}; margin: 2rem; max-width: 960px; color: var(--preview-ink); background: var(--preview-paper); }
   h1 { margin-top: 0; }
   h2 { margin-top: 2rem; border-bottom: 1px solid var(--preview-rule); padding-bottom: 0.25rem; }
   table { border-collapse: collapse; width: 100%; margin-top: 0.5rem; }

package/standards/readme.md

@@ -11,7 +11,7 @@ The reader is what changes. Reference prose serves someone who already committed
 
 ## Scope
 
-Governs every `README.md`: voice, heading structure, required and optional sections, badge selection, and what the page links out to instead of carrying.
+Governs every `README.md`: voice, heading structure, required and optional sections, the header block, badge selection, and what the page links out to instead of carrying.
 
 Does not govern:
 
@@ -34,14 +34,14 @@ Scoped to the README at a repository root. A nested README documenting a folder,
 
 - H1 title, H2 major sections, H3 subsections. Maintain proper hierarchy for GitHub's auto-generated table of contents.
 - Use sentence case for all headings (proper nouns and product names retain their casing)
-- Project description in plain text directly under H1. Keep it to 2-3 sentences.
+- Project description in plain text below the header block, or directly under the H1 when the block holds nothing beneath the title. Keep it to 2-3 sentences.
 - Do not create deeply nested heading structures that harm scannability
 - Do not use horizontal rules or dividers (`---`)
 
 ## Sections
 
 - Required: project description, installation/setup, usage examples, support/help resources
-- Optional: badges (at top, before description), features, contributing (link to `CONTRIBUTING.md`), license (link to `LICENSE`)
+- Optional: the header block below, features, contributing (link to `CONTRIBUTING.md`), license (link to `LICENSE`)
 - Do not include full API documentation. Link to separate docs instead.
 - Do not include license text. Reference the `LICENSE` file.
 - Do not include detailed contribution guidelines. Reference `CONTRIBUTING.md`.
@@ -49,6 +49,25 @@ Scoped to the README at a repository root. A nested README documenting a folder,
 - A README that points to the project's own context entries instead of restating them satisfies the required list by routing rather than carrying. A repository documented in `docs/` or `canon/context/` names the entry point and the listing command, then stops. The reader is one hop away, the same way `## Badges` treats zero as complete.
 - A README missing an H1, or whose headings restate the tool that scaffolded it rather than the project, is unedited generator output rather than a page anyone wrote. Draft over it. Nothing here asks a session to preserve a section a scaffold wrote and nobody replaced.
 
+### Header block
+
+The opening of a root README is a block of up to six elements in a fixed order. Every element is read off the repository rather than written from scratch, and each one is a slot: a project that holds nothing for it leaves it out.
+
+1. Mark: the project's logo or icon, from an image the repository already commits. Omit it when the project has none.
+2. Title: the H1, naming the project.
+3. Badges: the block `### Badges` below governs, placed directly under the title.
+4. Claim: one line saying what the project does, taken from the manifest description or the repository description.
+5. Live link: the URL of the running surface, from a `homepage` field or a deploy config. Omit it when the project has no page or no known URL.
+6. Product screenshot: an image the project already commits and references, shown with alt text naming what it depicts. Present only when the project has a page. Omit it when no such image exists rather than writing a placeholder path.
+
+The description of 2-3 sentences follows the block and expands the claim rather than repeating it.
+
+- A project with no page omits the link and the screenshot. A library or a CLI reads as a complete block with a title, badges, and a claim.
+- The order is the block's rather than the page's. The screenshot sits last inside the block, which puts it in the first row of content a reader meets below the title, badges, and claim.
+- A themed light and dark pair counts as one element in the slot rather than two. The block does not require a pair and leaves the handling of themes to the project.
+- Centering the block in an HTML wrapper is optional. Plain markdown reaches every host a README renders on, and a wrapper is styling a project can add.
+- Never invent an element. A mark or a screenshot the project does not hold stays out of the page.
+
 ### Badges
 
 A badge earns its place by carrying a fact the reader cannot get from the page they are already on. Three classes pass that test.

package/tooling/astro/manifest.toml

@@ -24,6 +24,7 @@ packages = [
 
 [scripts.override]
 "screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) && export PREVIEW_PORT && bash scripts/screenshot.sh"
+"readme-screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) && export PREVIEW_PORT && bash scripts/readme-screenshot.sh"
 "dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro dev"
 "preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro preview"
 

package/tooling/nextjs/manifest.toml

@@ -17,6 +17,7 @@ packages = [
 [scripts.override]
 "dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && next dev --port $((3000 + WORKTREE_PORT_OFFSET))"
 "screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 3000) && export PREVIEW_PORT && bash scripts/screenshot.sh"
+"readme-screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 3000) && export PREVIEW_PORT && bash scripts/readme-screenshot.sh"
 
 [gitignore]
 "# Next" = [".next/"]

package/tooling/web/configs/.github/workflows/readme-screenshot.yml

@@ -0,0 +1,110 @@
+name: README Screenshot
+# canon-no-seed: a stack-specific workflow with no root counterpart by design, since this repository reports its own capture in pr-visual-checks.yml and never commits it.
+
+# No `workflow_dispatch`: the job commits onto a pull request's head branch,
+# and a manual run has no pull request to commit onto.
+on:
+  pull_request:
+    paths:
+      # Project-specific. Replace the placeholder with the paths whose change
+      # moves the README frame, such as the component and styles it renders.
+      # The three entries below the placeholder keep the job firing on this
+      # file's own installation, which is what lets the first step refuse an
+      # unfilled template instead of the job never running.
+      - 'REPLACE_WITH_PROJECT_PATHS'
+      - 'scripts/readme-screenshot.sh'
+      - 'scripts/lib/preview-server.sh'
+      - '.github/workflows/readme-screenshot.yml'
+
+concurrency:
+  group: readme-screenshot-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  capture:
+    name: 🖼️ Refresh README Screenshot
+    runs-on: ubuntu-latest
+    # The default GITHUB_TOKEN cannot push to a fork's branch, so a PR from
+    # outside this repository is skipped rather than left to fail on the push
+    # step below.
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+
+      - name: Refuse An Unfilled Template
+        # A path list left at its placeholder never fires on the pages it was
+        # installed to watch, and that failure leaves no run, no diff, and no
+        # complaint. Failing here is what tells the project it has not
+        # finished installing.
+        run: |
+          if grep -q "^ *- 'REPLACE_WITH_PROJECT_PATHS'" .github/workflows/readme-screenshot.yml; then
+            echo "::error file=.github/workflows/readme-screenshot.yml::The paths list still holds REPLACE_WITH_PROJECT_PATHS. Replace it with the paths that move the README frame."
+            exit 1
+          fi
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Cache Playwright Browser
+        id: playwright-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-chromium-${{ hashFiles('**/package.json') }}
+
+      - name: Install Playwright System Dependencies
+        # Unconditional: the cache holds browser binaries and nothing apt
+        # wrote, so gating this on a cache hit leaves a warm run launching
+        # chromium without the libraries it needs.
+        run: bunx playwright install-deps chromium
+
+      - name: Install Playwright Browser
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: bunx playwright install chromium
+
+      - name: Capture README Screenshot
+        run: bun run readme-screenshot
+
+      - name: Check For Changes
+        id: diff
+        run: |
+          if git status --porcelain assets/evidence/readme | grep -q .; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Commit And Push
+        # Self-terminating: this push retriggers this same workflow on the PR,
+        # which captures again, finds no diff against what was just pushed,
+        # and stops here without pushing a second time.
+        if: steps.diff.outputs.changed == 'true'
+        # The hooks are off because this commit carries nothing they can read.
+        # `pre-push` runs the full verify, whose format step shells out to
+        # `shfmt`, which the runner does not install, so a push through them
+        # exits 127. The jobs in verify.yml already run those checks against
+        # the source, and what this step pushes is PNG bytes a capture
+        # produced.
+        env:
+          HUSKY: 0
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add assets/evidence/readme
+          git commit -m "chore(readme): refresh README screenshot"
+          git push origin "HEAD:${{ github.head_ref }}"

package/tooling/web/configs/e2e/screenshot.ts

@@ -9,12 +9,33 @@ interface CaptureSection {
   selector: string
 }
 
+interface Viewport {
+  readonly name: string
+  readonly width: number
+  readonly height: number
+  /** Whether a case flagged `evidence: true` also writes its frames at this width. */
+  readonly evidence: boolean
+}
+
+/**
+ * The breakpoint buckets every case is crossed with, named by width. 320 is
+ * the base a page has to hold without wrapping or clipping. Committing every
+ * width multiplies the tracked frames by the width count, so only the base and
+ * the desktop width carry `evidence`.
+ */
+const VIEWPORTS: readonly Viewport[] = [
+  { name: '320', width: 320, height: 800, evidence: true },
+  { name: '768', width: 768, height: 800, evidence: false },
+  { name: '1280', width: 1280, height: 800, evidence: true },
+  { name: '1536', width: 1536, height: 800, evidence: false },
+]
+
 interface CaptureCase {
   section: string
   theme: string
   route: string
-  width: number
-  height: number
+  /** Names of viewports this case skips, for a route that reflows rather than breaks at that width. */
+  excludeViewports?: readonly string[]
   evidence?: boolean
   sections?: CaptureSection[]
   setup?: (page: Page) => Promise<void>
@@ -50,8 +71,6 @@ const CASES: CaptureCase[] = [
     section: 'home',
     theme: 'default',
     route: '/',
-    width: 1280,
-    height: 800,
     evidence: true,
     sections: HOME_SECTIONS,
   },
@@ -59,13 +78,28 @@ const CASES: CaptureCase[] = [
     section: 'home',
     theme: 'dark',
     route: '/',
-    width: 1280,
-    height: 800,
     sections: HOME_SECTIONS,
     setup: (page) => page.emulateMedia({ colorScheme: 'dark' }),
   },
 ]
 
+/** One case at one viewport, which is the unit a filter selects and a context is built for. */
+interface CaptureRun {
+  readonly captureCase: CaptureCase
+  readonly viewport: Viewport
+  readonly label: string
+}
+
+const ALL_RUNS: readonly CaptureRun[] = CASES.flatMap((captureCase) =>
+  VIEWPORTS.filter(
+    (viewport) => !captureCase.excludeViewports?.includes(viewport.name),
+  ).map((viewport) => ({
+    captureCase,
+    viewport,
+    label: `${captureCase.section}/${viewport.name}--${captureCase.theme}`,
+  })),
+)
+
 const args = process.argv.slice(2)
 const checkConsoleClean = args.includes('--check-console-clean')
 const requireBaseUrl = args.includes('--require-base-url')
@@ -87,6 +121,28 @@ try {
 
 const OUT_DIR = path.join('screenshots', hostname)
 
+const SCREENSHOT_FILTER = process.env.SCREENSHOT_FILTER?.trim() ?? ''
+
+const filterTerms = SCREENSHOT_FILTER.split(',')
+  .map((term) => term.trim())
+  .filter(Boolean)
+
+const RUNS =
+  filterTerms.length > 0
+    ? ALL_RUNS.filter((run) =>
+        filterTerms.some((term) => run.label.includes(term)),
+      )
+    : ALL_RUNS
+
+if (filterTerms.length > 0 && RUNS.length === 0) {
+  console.error(
+    `No cases matched SCREENSHOT_FILTER=${SCREENSHOT_FILTER}. Available labels:\n${ALL_RUNS.map(
+      (run) => `  ${run.label}`,
+    ).join('\n')}`,
+  )
+  process.exit(1)
+}
+
 /** Every wait on a lazy load is bounded explicitly. */
 const SETTLE_TIMEOUT = 15_000
 
@@ -198,12 +254,12 @@ const browser = await chromium.launch()
 const consoleErrors: string[] = []
 let ranCases = 0
 
-for (const captureCase of CASES) {
+for (const { captureCase, viewport, label } of RUNS) {
   if (captureCase.evidence && requireBaseUrl) continue
 
   ranCases++
   const context = await browser.newContext({
-    viewport: { width: captureCase.width, height: captureCase.height },
+    viewport: { width: viewport.width, height: viewport.height },
     // A page honoring the preference lands its own motion at the end state,
     // which is what a still frame has to show. Playwright reads it as a
     // context option, so it reaches no page written beside `viewport` above.
@@ -214,9 +270,7 @@ for (const captureCase of CASES) {
   if (checkConsoleClean) {
     page.on('console', (msg) => {
       if (msg.type() === 'error') {
-        consoleErrors.push(
-          `${captureCase.section}/${captureCase.theme}: ${msg.text()}`,
-        )
+        consoleErrors.push(`${label}: ${msg.text()}`)
       }
     })
   }
@@ -226,21 +280,21 @@ for (const captureCase of CASES) {
   await page.goto(`${BASE_URL}${captureCase.route}`)
   await page.waitForLoadState('networkidle')
 
-  const label = `${captureCase.section}/${captureCase.theme}`
   const sections = await settle(page, label, captureCase.sections ?? [])
 
   const sweepDir = path.join(OUT_DIR, captureCase.section)
   const evidenceDir = path.join('evidence', captureCase.section)
-  const file = `${captureCase.theme}.png`
+  const file = `${viewport.name}--${captureCase.theme}.png`
+  const writesEvidence = captureCase.evidence && viewport.evidence
 
   await shoot(page, sweepDir, file)
-  if (captureCase.evidence) await shoot(page, evidenceDir, file)
+  if (writesEvidence) await shoot(page, evidenceDir, file)
 
   if (sections.length > 0) await markFloatingChrome(page)
 
   for (const { name, selector } of sections) {
     await shoot(page, path.join(sweepDir, name), file, selector)
-    if (captureCase.evidence) {
+    if (writesEvidence) {
       await shoot(page, path.join(evidenceDir, name), file, selector)
     }
   }

package/tooling/web/configs/scripts/lib/preview-server.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Sourced, not executed. Builds the site, serves it in the background on
+# PREVIEW_PORT, and blocks until it answers or exits with an error. Shared by
+# scripts/screenshot.sh and scripts/readme-screenshot.sh so the two don't
+# carry two copies of the same startup boilerplate.
+set -euo pipefail
+
+: "${PREVIEW_PORT:=4173}"
+
+if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
+  echo "Port $PREVIEW_PORT already in use. Stop the listening process or set PREVIEW_PORT." >&2
+  exit 1
+fi
+
+bun run build
+bun run preview >/dev/null 2>&1 &
+PREVIEW_PID=$!
+# shellcheck disable=SC2154 # pid is bound by the for loop inside the single-quoted trap body, which shellcheck does not track there
+trap 'kill "$PREVIEW_PID" 2>/dev/null || true; if command -v lsof >/dev/null 2>&1; then for pid in $(lsof -ti tcp:"$PREVIEW_PORT" 2>/dev/null); do kill "$pid" 2>/dev/null || true; done; else echo "lsof not found on PATH; cannot confirm the preview port is clear of a detached grandchild." >&2; fi; wait "$PREVIEW_PID" 2>/dev/null || true' EXIT
+
+for _ in $(seq 1 40); do
+  if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
+    break
+  fi
+  sleep 0.25
+done
+
+if ! curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
+  echo "Preview server not responding on port $PREVIEW_PORT after 10s." >&2
+  exit 1
+fi

package/tooling/web/configs/scripts/readme-screenshot.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Project-specific. Both are placeholders the project fills in, and the script
+# refuses to run until it does, since a shipped default would capture the wrong
+# part of the page in every project but the one it was written for.
+README_FILTER='' # case label to capture, such as header/1280
+README_EVIDENCE_DIR='assets/evidence/readme'
+
+if [[ -z "$README_FILTER" ]]; then
+  echo "README_FILTER is unset in scripts/readme-screenshot.sh. Name the case label the README frame is captured from, such as header/1280." >&2
+  exit 1
+fi
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib/preview-server.sh"
+
+SCREENSHOT_BASE_URL="http://localhost:$PREVIEW_PORT" SCREENSHOT_FILTER="$README_FILTER" bun e2e/screenshot.ts
+
+# The filter's section and viewport name the folder and the file prefix the
+# capture wrote under screenshots/<hostname>/.
+frame_dir="screenshots/localhost/$(dirname "$README_FILTER")"
+frame_prefix="$(basename "$README_FILTER")"
+
+mkdir -p "$README_EVIDENCE_DIR"
+cp "$frame_dir/$frame_prefix--default.png" "$README_EVIDENCE_DIR/light.png"
+cp "$frame_dir/$frame_prefix--dark.png" "$README_EVIDENCE_DIR/dark.png"

package/tooling/web/configs/scripts/screenshot.sh

@@ -1,29 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-: "${PREVIEW_PORT:=4173}"
-
-if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
-  echo "Port $PREVIEW_PORT already in use. Stop the listening process or set PREVIEW_PORT." >&2
-  exit 1
-fi
-
-bun run build
-bun run preview >/dev/null 2>&1 &
-PREVIEW_PID=$!
-# shellcheck disable=SC2154 # pid is bound by the for loop inside the single-quoted trap body, which shellcheck does not track there
-trap 'kill "$PREVIEW_PID" 2>/dev/null || true; if command -v lsof >/dev/null 2>&1; then for pid in $(lsof -ti tcp:"$PREVIEW_PORT" 2>/dev/null); do kill "$pid" 2>/dev/null || true; done; else echo "lsof not found on PATH; cannot confirm the preview port is clear of a detached grandchild." >&2; fi; wait "$PREVIEW_PID" 2>/dev/null || true' EXIT
-
-for _ in $(seq 1 40); do
-  if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
-    break
-  fi
-  sleep 0.25
-done
-
-if ! curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
-  echo "Preview server not responding on port $PREVIEW_PORT after 10s." >&2
-  exit 1
-fi
+source "$(dirname "${BASH_SOURCE[0]}")/lib/preview-server.sh"
 
 SCREENSHOT_BASE_URL="http://localhost:$PREVIEW_PORT" bun e2e/screenshot.ts

package/tooling/web/manifest.toml

@@ -52,6 +52,7 @@ packages = [
 [scripts.override]
 "lint" = "eslint . --max-warnings 0"
 "screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) && export PREVIEW_PORT && bash scripts/screenshot.sh"
+"readme-screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) && export PREVIEW_PORT && bash scripts/readme-screenshot.sh"
 
 [gitignore]
 "# Build" = ["dist/"]

package/tooling/web/reference.md

@@ -12,7 +12,11 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 
 - `eslint.config.js`: flat config with `@eslint/js`, `typescript-eslint`, React hooks, import sort, check-file, vitest rules scoped to test files, `eslint-config-prettier` last.
 - `src/test/setup.ts`: `@testing-library/jest-dom` import, `cleanup` after each test.
-- `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, a route, and its own viewport, and the loop below writes `screenshots/<hostname>/<section>/<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. A case flagged `evidence: true` additionally writes `evidence/<section>/<theme>.png`, with no hostname segment. `--require-base-url` skips a flagged case entirely, so a production smoke run neither writes to the committed path nor counts an evidence route in its console-clean check, and exits 1 when that leaves zero cases run, so flagging every case cannot silence the production check without saying so. Per-project cases extend the one record. A route's themes sit together under its section folder, so the filename carries the theme alone. A case may also name `sections`, one `{ name, selector }` per addressable part of the route, and each writes its own frame at `screenshots/<hostname>/<section>/<name>/<theme>.png` beside the whole-page one, plus `evidence/<section>/<name>/<theme>.png` where the case is flagged. The field is optional, so a case that names none captures the page alone as before, and a selector matching nothing is reported and skipped rather than raised, since `CASES` is a template a project rewrites and a target that syncs this file before editing its own list would otherwise capture nothing at all. Testing that every named section resolves belongs to the project that owns the selectors, beside its own page. Every case settles before anything is shot: the context is created with `reducedMotion: 'reduce'`, each named section is scrolled into view so an `IntersectionObserver` fires and a frame marked `loading="lazy"` loads, the page returns to the top, and fonts, images and same-origin frames are waited out on a bounded condition rather than on a second `networkidle`, which is a lifecycle event of the navigation and does not re-arm for a load a scroll started. A section frame drops the page's floating chrome, being whatever computes to `position: sticky` or `fixed`, because a section taller than the viewport is scrolled into view to be cut and a sticky bar otherwise rides that scroll into the middle of the frame. The whole-page frame is shot first and keeps its chrome. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
+- `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, and a route, and the loop below crosses every case with the `VIEWPORTS` array and writes `screenshots/<hostname>/<section>/<width>--<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. `VIEWPORTS` holds four breakpoint buckets named by width, 320, 768, 1280 and 1536, with 320 as the base a page has to hold without wrapping or clipping. A case flagged `evidence: true` additionally writes `evidence/<section>/<width>--<theme>.png`, with no hostname segment, at the viewports flagged `evidence` alone, which are 320 and 1280. Committing all four multiplies the tracked frames by the width count, so the flag is what keeps the tracked set at twice the sections rather than four times. A case may name `excludeViewports` to skip a width, for a route whose long-form prose reflows at 320 instead of breaking. `SCREENSHOT_FILTER` narrows a run to the cases whose label, `<section>/<width>--<theme>`, contains any comma-separated term, exits 1 when nothing matches and lists the labels that exist, and leaves the rest of the sweep alone. `--require-base-url` skips a flagged case entirely, so a production smoke run neither writes to the committed path nor counts an evidence route in its console-clean check, and exits 1 when that leaves zero cases run, so flagging every case cannot silence the production check without saying so. Per-project cases extend the one record. A route's widths and themes sit together under its section folder, so the filename carries both. A case may also name `sections`, one `{ name, selector }` per addressable part of the route, and each writes its own frame at `screenshots/<hostname>/<section>/<name>/<width>--<theme>.png` beside the whole-page one, plus `evidence/<section>/<name>/<width>--<theme>.png` where the case is flagged and the width carries `evidence`. The field is optional, so a case that names none captures the page alone as before, and a selector matching nothing is reported and skipped rather than raised, since `CASES` is a template a project rewrites and a target that syncs this file before editing its own list would otherwise capture nothing at all. Testing that every named section resolves belongs to the project that owns the selectors, beside its own page. Every case settles before anything is shot: the context is created with `reducedMotion: 'reduce'`, each named section is scrolled into view so an `IntersectionObserver` fires and a frame marked `loading="lazy"` loads, the page returns to the top, and fonts, images and same-origin frames are waited out on a bounded condition rather than on a second `networkidle`, which is a lifecycle event of the navigation and does not re-arm for a load a scroll started. A section frame drops the page's floating chrome, being whatever computes to `position: sticky` or `fixed`, because a section taller than the viewport is scrolled into view to be cut and a sticky bar otherwise rides that scroll into the middle of the frame. The whole-page frame is shot first and keeps its chrome. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
+- `scripts/screenshot.sh`: sources `scripts/lib/preview-server.sh`, then runs the capture against the served preview.
+- `scripts/lib/preview-server.sh`: sourced, never executed. Builds, serves on `PREVIEW_PORT`, blocks until the port answers, and traps the whole process group on exit, including the detached grandchild `lsof` finds. Both capture scripts source it so the startup lives once.
+- `scripts/readme-screenshot.sh`: captures one case under `SCREENSHOT_FILTER` and copies its light and dark frames to `assets/evidence/readme/`. `README_FILTER` ships empty with `header/1280` as its example, and the script exits 1 until a project fills it, since a shipped default would capture the wrong part of the page in every project but one. Its copy reads from `screenshots/<hostname>/`, which is where the harness writes.
+- `.github/workflows/readme-screenshot.yml`: refreshes that frame on a pull request and commits it back to the branch. The path list ships as `REPLACE_WITH_PROJECT_PATHS`, and the job's first step after checkout exits 1 while it stays, since a job that never fires leaves no run and no diff to notice. The workflow's own path is in the list so the installing pull request reaches that step. When a commit-back is right and when a report is, `governance/rules/ci/700-ci-workflow.md` states the test.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order.
@@ -106,6 +110,7 @@ Append rows:
 | `bun run test:e2e` | Run Playwright E2E tests. |
 | `bun run test:e2e:changed` | Run Playwright E2E tests for specs the import graph reaches from the current diff. |
 | `bun run screenshot` | Build, preview, then capture screenshots. |
+| `bun run readme-screenshot` | Build, preview, then capture the README frame into `assets/evidence/readme/`. |
 | `bun run smoke:prod` | Capture against `SCREENSHOT_BASE_URL`, requiring it set and failing on any console error. |
 
 `canon tooling verify <stack>` is the only automated caller of `bun run screenshot`, running it for any stack whose `package.json` declares the script and asserting that PNG files land under `screenshots/`. It counts them with a recursive find carrying no depth limit, so the section folders the seed writes satisfy the assertion without a change to it. Do not flatten the layout to protect that check. No ship chain captures a screenshot, so the output path the seed writes is a contract that one verifier reads rather than a default a ship step depends on.