@erclx/canon 4.102.0 → 4.104.0

package/src/shipped/references.ts

@@ -210,7 +210,7 @@ const PHASE_LABEL = /\bv\d+\.\d+(?!\.\d)\b/g
  *
  * Anchored on the trailing `\d{3}-[\w-]+\.md` rather than on the bare
  * `.claude/rules/` prefix, which is what keeps a folder mention carrying no
- * number, such as `create-rule`, `memory-review`, and `setup-gov` already
+ * number, such as `create-rule`, `memory-review`, and `target-setup` already
  * write correctly, from matching. The segment group between `rules/` and the
  * numbered file admits both a governance-namespace path
  * (`canon/core/055-scratch.md`) and a project-namespace one

package/standards/index.md

@@ -19,7 +19,6 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
 - [Groundwork reference](groundwork.md): Folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
-- [Issue reference](issue.md): GitHub issue title, labels, and body conventions
 - [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, banned words, and frontmatter wording
 - [Memory reference](memory.md): Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
 - [Mermaid reference](mermaid.md): Direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram

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.

package/claude/skills/setup-gov/REQUIREMENT.md

@@ -1,37 +0,0 @@
----
-name: setup-gov
-description: Scope boundary for governance rule install and the authoring it refuses to do in a target
----
-
-# Setup gov requirement
-
-## Gap
-
-Without this skill, a session picks a stack name from memory and installs rules written for a framework the project does not use, passes an extra the catalog does not carry so the install warns on a file it cannot resolve, and adds a rule the picked stack already pulls in.
-
-The two costly failures are quieter. An unmatched technology gets the nearest rule instead of a stop, so the project carries governance authored for something adjacent and nothing marks it as a guess. A rule written directly into the target lands where no sync will ever reach it, so it drifts from the toolkit copy that owns it.
-
-The last failure sits at a boundary rather than inside a run. `setup-init` turns away a project whose language it carries no stack for and sends it here, and a body stating only what this skill does not cover leaves that route running one way, so a person arriving on it reads a skill that never says it is the destination.
-
-## Must
-
-- Read the catalog at run time and resolve both the stack and every extra against it
-- Name the evidence file behind each detected technology in the preview, so a wrong match is visible before the install rather than after
-- Dedupe extras against the rules the picked stack already resolves
-- Run the install non-interactively, since the CLI picker blocks where no terminal is attached
-- State the inbound route from `setup-init`, so a project sent here for the language-neutral rule layer can tell it landed at the destination the chain named
-
-## Must not
-
-- Author a rule inside the target project. Rules are authored in the toolkit and reach a project by install or sync.
-- Install a stack or extra whose name did not come from the catalog read
-
-## Guards
-
-- An unmatched technology stops and presents the options rather than resolving to a nearby rule. Authoring the missing rule in the toolkit, installing the matching layers without the technology-specific one, and aborting are the three, and this skill picks none of them.
-
-## Out of scope
-
-- The rest of the onboarding chain. This skill installs governance and nothing else, and `setup-init` is the one-shot path that installs governance beside tooling, snippets, and the seeds.
-- Scaffolding the rule file an unmatched technology needs. `create-rule` writes one into a target project, and a rule the toolkit should ship is authored under `governance/rules/` against `canon standards rule`.
-- Updating rules a project already has, which `canon gov sync` owns

package/claude/skills/setup-gov/SKILL.md

@@ -1,77 +0,0 @@
----
-name: setup-gov
-description: Detects a project's stack from its files and installs matching toolkit governance rules into `.claude/rules/`. Use after scaffolding a new project, when asked to "install gov rules", "install governance", "set up governance", or when a target project has no `.claude/rules/` yet. Assumes the `canon` CLI is on PATH.
----
-
-# Gov install
-
-Automates `canon gov install` by inferring the stack and extras from the current project, then shelling out to the CLI with the resolved arguments.
-
-## Scope
-
-- Governance rules and nothing else. `setup-init` is the one-shot chain that installs governance beside tooling, standards, snippets, and the seeds.
-- This is where `setup-init` sends a project whose language the toolkit carries no stack for. Rules install without the `base` development dependencies the tooling layer would drop on it. Resolve and stop exactly as below, since a language with no stack is the unmatched case `## Gap handling` already owns and arriving by that route changes none of it.
-
-## Read the catalog
-
-Run this first to load the current stacks and rules. Never hardcode names. The catalog is the source of truth.
-
-```bash
-canon gov list --json 2>/dev/null
-```
-
-## Detect the stack
-
-Read these from the project root in parallel:
-
-- `package.json`: dependencies and devDependencies
-- Root config files: `astro.config.*`, `next.config.*`, `vite.config.*`, `tailwind.config.*`, `tsconfig.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`
-- `canon/REQUIREMENTS.md` and `canon/ARCHITECTURE.md` if present
-- Directory structure via `ls -1` of the project root and `src/` if present
-
-## Match
-
-Match the detected evidence to the catalog:
-
-- Pick the closest stack. Match detected runtime or framework against stack names in the catalog.
-- Identify additional technologies not already covered by the picked stack. For each, find a rule whose `description` or `paths` points at that technology, then add it via `--add`.
-- Dedupe extras against stack rules. Do not add a rule the stack already pulls in.
-
-## Gap handling
-
-If a detected technology has no matching rule, stop and surface the gap. Do not guess.
-
-Present four options:
-
-1. Author a new rule in the toolkit at `governance/rules/<domain>/<num>-<name>.md` following `${CLAUDE_SKILL_DIR}/../../standards/rule.md`, commit, then re-run install. Take this route when the toolkit should ship the rule to every project.
-2. Invoke `create-rule`, which scaffolds the file into the target project at a non-colliding number. Take this route when the rule is specific to this project and no sync should ever overwrite it.
-3. Install the matching non-<tech> rules and skip the tech-specific layer.
-4. Abort.
-
-This skill authors no rule itself. Option 1 writes in the toolkit repository, and option 2 hands the project-local file to `create-rule`.
-
-## Preview
-
-Before executing, output:
-
-- **Detected:** each technology with the file that evidenced it
-- **Stack:** picked stack name and total resolved rule count
-- **Extras:** each `--add` rule with a one-line reason
-- **Target:** resolved target path
-- **Command:** the exact shell command to run
-
-## Execute
-
-Run with `CANON_NON_INTERACTIVE=1` so no CLI picker prompts appear. Claude Code's tool permission dialog is the confirmation gate.
-
-```bash
-CANON_NON_INTERACTIVE=1 canon gov install <stack> --add <extras> <target>
-```
-
-## Response
-
-After execution, report:
-
-- Rule count installed
-- Target path
-- Any rules that failed to resolve (the CLI warns on missing rule files)