@erclx/canon 4.116.0 → 4.118.0

package/src/tooling/inject.ts

@@ -6,7 +6,12 @@ import { copyPreservingMode } from '@/copy'
 import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
 import { resolveSurfacePath } from '@/surface-root'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'
-import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
+import {
+  ancestorsFirst,
+  configPaths,
+  listFiles,
+  type Manifest,
+} from '@/tooling/manifest'
 import {
   applyScripts,
   collectDeps,
@@ -97,9 +102,14 @@ export async function injectSeeds(
   target: string,
 ): Promise<string[]> {
   const applied: string[] = []
+  const isSubfolder = isSubfolderTarget(target)
+  const shadowed = configPaths(chain)
 
   for (const manifest of ancestorsFirst(chain)) {
-    const files = listFiles(manifest.seedsDir)
+    const files = listFiles(manifest.seedsDir).filter(
+      (rel) =>
+        !shadowed.has(rel) && !(isSubfolder && isWithheldInSubfolder(rel)),
+    )
     if (files.length === 0) continue
 
     logStep(`Applying ${manifest.name} seeds`)
@@ -111,9 +121,7 @@ export async function injectSeeds(
     }
   }
 
-  const spellConfig = isSubfolderTarget(target)
-    ? subfolderSpellConfig(chain)
-    : undefined
+  const spellConfig = isSubfolder ? subfolderSpellConfig(chain) : undefined
   if (spellConfig !== undefined && !hasSpellConfig(target)) {
     logStep('Applying subfolder spell config')
     await writeFile(join(target, SUBFOLDER_SPELL_CONFIG), spellConfig)

package/src/tooling/manifest.ts

@@ -44,6 +44,15 @@ export function listFiles(dir: string): string[] {
   ].sort()
 }
 
+/**
+ * Every path any stack in the chain ships as a config. A seed at one of these
+ * paths is shadowed, since the config overwrites it on every sync. `scan` and
+ * `injectSeeds` both read this, so the report and the write cannot disagree.
+ */
+export function configPaths(chain: readonly Manifest[]): Set<string> {
+  return new Set(chain.flatMap((manifest) => listFiles(manifest.configsDir)))
+}
+
 /**
  * Reverses a chain so the furthest ancestor is applied first and nearer
  * stacks overwrite it.

package/src/tooling/scan.ts

@@ -2,7 +2,12 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { resolveSurfacePath } from '@/surface-root'
 import { mergeSections } from '@/tooling/gitignore'
-import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
+import {
+  ancestorsFirst,
+  configPaths,
+  listFiles,
+  type Manifest,
+} from '@/tooling/manifest'
 import {
   collectDeps,
   collectScripts,
@@ -63,10 +68,13 @@ function isIdentical(a: string, b: string): boolean {
  * stack first, while dependencies and gitignore entries resolve from the
  * furthest ancestor inward.
  *
- * A target below its git toplevel is scanned as a subfolder: a path GitHub
- * reads only at the root moves to `withheld` and counts as no change, and the
- * nested spell config joins the seeds. The scope is read here so every caller
- * of `scan` agrees without passing a flag.
+ * A seed at a path the chain also ships as a config is left to the config,
+ * so the path is reported once.
+ *
+ * A target below its git toplevel is scanned as a subfolder: a config or seed
+ * GitHub reads only at the root moves to `withheld` and counts as no change,
+ * and the nested spell config joins the seeds. The scope is read here so every
+ * caller of `scan` agrees without passing a flag.
  */
 export function scan(chain: readonly Manifest[], target: string): ScanResult {
   const isSubfolder = isSubfolderTarget(target)
@@ -98,13 +106,22 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
   }
 
   const seeds: SeedState[] = []
-  const seenSeeds = new Set<string>()
+  const seenSeeds = configPaths(chain)
 
   for (const manifest of chain) {
     for (const rel of listFiles(manifest.seedsDir)) {
       if (seenSeeds.has(rel)) continue
       seenSeeds.add(rel)
 
+      if (isSubfolder && isWithheldInSubfolder(rel)) {
+        withheld.push({
+          rel,
+          stack: manifest.name,
+          present: existsSync(join(target, rel)),
+        })
+        continue
+      }
+
       seeds.push({
         rel,
         state: existsSync(resolveSurfacePath(target, rel))

package/src/tooling/subfolder.ts

@@ -50,9 +50,9 @@ export function subfolderPath(target: string): string | undefined {
 
 /**
  * GitHub reads workflows only at the repository root, so a `.github/` copied
- * into a subfolder is a file nothing runs. `scan` and `injectConfigs` both
- * read this, so the set the diff withholds and the set the sync skips cannot
- * disagree.
+ * into a subfolder is a file nothing runs. `scan`, `injectConfigs`, and
+ * `injectSeeds` all read this, so the set the diff withholds and the set the
+ * sync skips cannot disagree, whether the path ships as a config or a seed.
  */
 export function isWithheldInSubfolder(rel: string): boolean {
   return rel.startsWith(WITHHELD_PREFIX)

package/standards/context.md

@@ -105,8 +105,8 @@ Only the `development` entry carries this section. It is not a general-purpose h
 
 ## Length
 
-- Aim for one entry per domain. There is no hard cap. Length is a symptom, not the defect.
-- Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number. Rendered lines count as `markdown.md` defines them.
+- Aim for one entry per domain. Length is a symptom, not the defect, and the one hard cap is the whole-document ceiling `markdown.md` states.
+- Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number. The 150 is a diagnostic checkpoint and never gates. Rendered lines count as `markdown.md` defines them.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
 - Retire a decision or gotcha once its subject is gone, rewriting the bullet to state the current design rather than leaving the narration of what it replaced beside it. A rejected alternative is not a retired one, so what was tried and why it lost stays whatever its age. The rule above protects content whose subject is live, and this one releases content whose subject is not.
 - Rewrite a decision a later one replaced rather than appending the replacement beside it. The subject is still live, so the rule above does not reach it, and two bullets on one subject leave a reader to work out which of them is current. State the design that stands and keep the superseded reasoning only where it is the alternative that lost.

package/standards/markdown.md

@@ -32,6 +32,8 @@ Does not govern:
 - Proper nouns and product names retain their casing in headings
 - Past roughly 40 rendered lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint, not a cap.
 - Count rendered lines rather than source lines, wrapping each source line at 80 columns and summing the heights. Source lines undercount a file authored one line per bullet, where a block of fifteen paragraph-bullets occupies fifteen lines and renders past sixty. A checkpoint another standard states counts the same unit, so a file measured one way never sits beside a run measured another.
+- Keep a whole document at or under 300 rendered lines, counted over the full source with frontmatter and fenced blocks included, since a session pays for every line it loads. This one is a ceiling rather than a checkpoint. `canon markdown audit` lists every document past it without failing the run, and a gate stage reads the same number, so whether a push fails on it is the project's gate to decide. Split the document at a seam rather than compressing it.
+- Exempt a file named `CHANGELOG.md`, which a release tool rewrites, and a document carrying `<!-- canon-length-exempt: <reason> -->` on a line of its own outside a fenced block. A marker naming no reason exempts nothing.
 - Exempt a block whose lines are all list items at one level averaging under roughly 130 characters. A flat list of short peers is already navigable, and a subheading dropped into it splits a set that belongs together. Bullet count says nothing on its own, since a catalog of one-liners and a stack of paragraphs reach the same count and read nothing alike, so weight is what decides.
 - Mixing prose with that list, or nesting levels inside it, ends the exemption at any weight.
 - Exempt a block whose lines are all table rows, at any length. The peer list above is exempt because it is already navigable, and a table because the remedy does not exist: a subheading dropped inside one splits the table rather than the run, so no edit short of rewriting it as a list clears the checkpoint.

package/standards/plan.md

@@ -31,6 +31,7 @@ A plan works when a session holding none of the conversation that produced it ca
 - Which decisions are already settled, and which are still open?
 - For each open decision, what happens when nobody answers it?
 - What is likely to go wrong, and where does the work collide with something already in flight?
+- How is each outcome proven, and which input would break it?
 
 A plan failing these is non-conforming even when it satisfies every shape rule below.
 
@@ -53,10 +54,12 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 | `## Summary`          | three to five one-line bullets: the goal, the deliverables, the trade-off | Always        |
 | `**Constraints:**`    | durable rules the work must respect                                       | When supplied |
 | `**Files to touch:**` | each file with a one-line reason                                          | Always        |
+| `**Verification:**`   | the test or command that proves each outcome                              | Always        |
 | `**Risks:**`          | conflicts, coupling, and the tricky spots                                 | Always        |
+| `**Review focus:**`   | the inputs or states that would break the change, for the reviewer        | Always        |
 | `**Questions:**`      | numbered open decisions, each with a suggestion and an answer slot        | Always        |
 
-- Write each marker as the table gives it. `Summary` opens the prose a reader scans, so it takes an H2, and the four that follow are labels over lists rather than sections of prose.
+- Write each marker as the table gives it. `Summary` opens the prose a reader scans, so it takes an H2, and the six that follow are labels over lists rather than sections of prose.
 - A section written in the other spelling is still that section. `## Risks` and `**Risks:**` name one thing, and a plan carrying either has stated its risks, so neither reads as an omission. Write the table's form in a new plan and leave an existing plan's spelling alone.
 - Both spellings break a depth run, so `canon markdown audit` reads either as the seam it is and reports a plan for a section that genuinely runs long rather than for its whole body. The markdown standard states the rule.
 - Write `None identified.` under a required section with nothing to report rather than dropping the marker. A dropped section and an unconsidered one read identically.
@@ -87,11 +90,23 @@ A dead constraint fails silently in the expensive direction. A session honoring
 
 A constraint naming a `.canon/ready/` folder is a third shape beside the two above. It makes that folder's files the verbatim source for the paths this plan's `**Files to touch:**` lists, per `ready.md`, so the executing session copies those paths rather than authoring them.
 
+### Verification
+
+- Name, for each outcome, the test or the command that proves it, as one bullet leading with the outcome and ending on the command in backticks.
+- Write a command a later session can run as given, from the project root. A description of what would be checked leaves the executing session to invent the check.
+- Name the visual check where no test reaches, and say it is visual, so a reader can tell a proof from a look.
+
 ### Risks
 
 - Name the collision rather than the category. A risk a reader cannot act on is padding.
 - Where the work establishes a resource with more than one consumer, list the consumers and mark each one read or write. A policy stated over that resource has to hold for the writers and not only for the consumer that prompted it.
 
+### Review focus
+
+- Name each input or state that would break the change if the implementation got it wrong, one bullet each, with what the change must do there.
+- Write it for the reviewer rather than the builder. The session writing the plan understood the risk before any diff existed, and this section is where that understanding reaches the review pass.
+- Keep it apart from `**Risks:**`. A risk is something the work might collide with, and a focus item is something the finished diff must be shown to handle, so a reviewer confirms the second and the executing session plans around the first.
+
 ## The suggested-and-answer contract
 
 Every question carries a `- Suggested:` line and an empty `- Answer:` slot below it.
@@ -165,10 +180,18 @@ This contract inverts the one an intake folder keeps, where an empty slot means
 
 - `<path/to/file>`: <reason>
 
+**Verification:**
+
+- <outcome>: `<test or command that proves it>`
+
 **Risks:**
 
 - <conflict, coupling, or tricky spot>
 
+**Review focus:**
+
+- <input or state that would break the change>: <what the change must do there>
+
 **Questions:**
 
 1. <question>

package/standards/skill.md

@@ -180,6 +180,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 - Contain only behavioral rules (what to do, what not to do) and pointers to reference docs. Narrative descriptions of what files are or how the system works belong in `docs/`, not in the skill body.
 - State rules, not inventories. Reference docs for lists that change, and phrase a rule as a ban on the forbidden shape rather than an enumeration of allowed options, so it stays stable as categories change.
 - Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
+- State the current rule only, in the body and in every file under `references/`. The incident and the date that earned a rule go in `REQUIREMENT.md` under `Gap`, or stay in git. A date inside a fence or a code span is example data and stays. `canon claude skills audit` names every other ISO date.
 - Group bullets under H2 headings by domain concern. Keep dos and don'ts together under the topic they belong to rather than splitting them into flat rules and constraints sections.
 - One actionable constraint per bullet. Prefer the `X over Y` form for preferences.
 - Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer.

package/tooling/base/reference.md

@@ -15,8 +15,6 @@ Golden config files live in `tooling/base/configs/` and are copied into the targ
 - `.editorconfig`: `root = true`, with an `[*.sh]` block setting `indent_style = space` and `indent_size = 2`.
 - `commitlint.config.js`: ESM default export extending `@commitlint/config-conventional`. Rules are `header-max-length: 72`, `scope-case: lower-case`, `subject-full-stop: never`, and `subject-case` disabled.
 - `.husky/`: `pre-commit`, `commit-msg`, `pre-push`, `post-merge`, `post-rewrite`.
-- `.github/workflows/verify.yml`: runs on pull requests targeting `main` and on `workflow_dispatch`.
-- `.github/pull_request_template.md`: `## Summary`, `## Key Changes`, `## Technical Context`, `## Testing`.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for Prettier, cspell, shfmt, and shellcheck.
 - `scripts/verify.sh`: the maintenance entry point behind `check`.
 
@@ -28,6 +26,8 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 - `.cspell/project-terms.txt` and `.cspell/tech-stack.txt`: one word per line, sorted alphabetically.
 - `.lintstagedrc`: the glob map below.
 - `.prettierignore`: created empty. Projects add their own entries.
+- `.github/workflows/verify.yml`: runs on pull requests targeting `main` and on `workflow_dispatch`. A project with more than one language root adds its own jobs here.
+- `.github/pull_request_template.md`: `## Summary`, `## Key Changes`, `## Technical Context`, `## Testing`. A project adds the checklist lines its own review needs.
 - `canon/context/`: extend the `ci` and `development` entries with project-specific commands, workflows, or deploy steps. Canonical rationale stays in this reference.
 
 ## Tool pairing

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

@@ -1,4 +1,4 @@
-import type { Page } from '@playwright/test'
+import type { Locator, Page } from '@playwright/test'
 import { chromium } from '@playwright/test'
 import { mkdir } from 'fs/promises'
 import path from 'path'
@@ -37,6 +37,8 @@ interface CaptureCase {
   /** Names of viewports this case skips, for a route that reflows rather than breaks at that width. */
   excludeViewports?: readonly string[]
   evidence?: boolean
+  /** Selectors painted over in every frame the case writes, for a value that moves between runs with no code change. */
+  mask?: readonly string[]
   sections?: CaptureSection[]
   setup?: (page: Page) => Promise<void>
 }
@@ -72,12 +74,14 @@ const CASES: CaptureCase[] = [
     theme: 'default',
     route: '/',
     evidence: true,
+    mask: ['.version'],
     sections: HOME_SECTIONS,
   },
   {
     section: 'home',
     theme: 'dark',
     route: '/',
+    mask: ['.version'],
     sections: HOME_SECTIONS,
     setup: (page) => page.emulateMedia({ colorScheme: 'dark' }),
   },
@@ -234,16 +238,47 @@ async function markFloatingChrome(page: Page) {
   }, FLOATING_ATTRIBUTE)
 }
 
-async function shoot(page: Page, dir: string, file: string, selector?: string) {
+/**
+ * Turns a case's mask selectors into the locators every frame paints over. A
+ * selector matching nothing is reported and kept out rather than raised, for
+ * the same template reason `settle` gives for a missing section.
+ */
+async function resolveMask(
+  page: Page,
+  label: string,
+  selectors: readonly string[],
+): Promise<Locator[]> {
+  const mask: Locator[] = []
+  for (const selector of selectors) {
+    const element = page.locator(selector)
+    if ((await element.count()) === 0) {
+      console.warn(
+        `${label}: no element matches ${selector}, named as a mask. Skipped.`,
+      )
+      continue
+    }
+    mask.push(element)
+  }
+  return mask
+}
+
+async function shoot(
+  page: Page,
+  dir: string,
+  file: string,
+  mask: Locator[],
+  selector?: string,
+) {
   await mkdir(dir, { recursive: true })
   const target = path.join(dir, file)
   if (selector === undefined) {
-    await page.screenshot({ path: target, fullPage: true })
+    await page.screenshot({ path: target, fullPage: true, mask })
   } else {
     // Floating chrome keeps the space it already occupies, so dropping it out
     // of its own layer moves nothing and leaves every box the size it was.
     await page.locator(selector).screenshot({
       path: target,
+      mask,
       style: `[${FLOATING_ATTRIBUTE}] { position: static !important; }`,
     })
   }
@@ -281,21 +316,22 @@ for (const { captureCase, viewport, label } of RUNS) {
   await page.waitForLoadState('networkidle')
 
   const sections = await settle(page, label, captureCase.sections ?? [])
+  const mask = await resolveMask(page, label, captureCase.mask ?? [])
 
   const sweepDir = path.join(OUT_DIR, captureCase.section)
   const evidenceDir = path.join('evidence', captureCase.section)
   const file = `${viewport.name}--${captureCase.theme}.png`
   const writesEvidence = captureCase.evidence && viewport.evidence
 
-  await shoot(page, sweepDir, file)
-  if (writesEvidence) await shoot(page, evidenceDir, file)
+  await shoot(page, sweepDir, file, mask)
+  if (writesEvidence) await shoot(page, evidenceDir, file, mask)
 
   if (sections.length > 0) await markFloatingChrome(page)
 
   for (const { name, selector } of sections) {
-    await shoot(page, path.join(sweepDir, name), file, selector)
+    await shoot(page, path.join(sweepDir, name), file, mask, selector)
     if (writesEvidence) {
-      await shoot(page, path.join(evidenceDir, name), file, selector)
+      await shoot(page, path.join(evidenceDir, name), file, mask, selector)
     }
   }
 

package/tooling/web/reference.md

@@ -12,7 +12,7 @@ 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, 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`.
+- `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. A case may also name `mask`, a list of selectors whose boxes are painted over in every frame the case writes, whole-page and section alike, for a value that moves between runs with no code change, so a double capture still compares everything else. A mask selector matching nothing is reported and skipped the same way. 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.

package/src/context/narration.ts

@@ -1,99 +0,0 @@
-import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
-
-/**
- * The headings a rule carries to publish the two sets.
- *
- * Discovery is anchored on these rather than on a filename for the reason
- * `src/comments/vocabulary.ts` anchors its own: governance rules are numbered,
- * and a renumber would empty the sets while the check kept reporting clean.
- * Both open with `Narration` so neither loader can read the other's list.
- */
-export const PRONOUN_HEADING = '## Narration pronouns'
-export const VERB_HEADING = '## Narration verbs'
-
-/**
- * Roots searched in order. The installed copy wins over the toolkit source, so
- * a target project measures against the rule it actually has rather than one
- * only the toolkit carries.
- */
-const RULE_ROOTS = ['.claude/rules', 'governance/rules']
-
-export interface NarrationTerms {
-  /** Back-reference openings, matched at the start of a bullet and cased. */
-  readonly pronouns: readonly string[]
-  /** Past-tense verbs, matched anywhere in the bullet and uncased. */
-  readonly verbs: readonly string[]
-}
-
-/**
- * Absent is a distinct state from empty, the split the comment vocabulary
- * draws for the same reason: a scan with no terms finds nothing, and reporting
- * that as zero findings claims the corpus is clean when nothing was looked for.
- */
-export type Narration =
-  | ({ readonly kind: 'loaded'; readonly source: string } & NarrationTerms)
-  | { readonly kind: 'absent' }
-
-/** Pulls the backticked terms out of the bullets under one heading. */
-export function parseTerms(
-  markdown: string,
-  heading: string,
-): string[] | undefined {
-  const lines = markdown.split('\n')
-  const start = lines.findIndex((line) => line.trim() === heading)
-  if (start === -1) return undefined
-
-  const terms: string[] = []
-
-  for (const line of lines.slice(start + 1)) {
-    if (line.startsWith('## ')) break
-    for (const match of line.matchAll(/`([^`]+)`/g)) {
-      const term = match[1].trim()
-      if (term && !terms.includes(term)) terms.push(term)
-    }
-  }
-
-  return terms
-}
-
-/**
- * Finds the rule publishing both sets under `root`.
- *
- * Both come from one file rather than from whichever rule carries each. A
- * pronoun set and a verb set are halves of one signal, and pairing them across
- * files would let a renumber recombine them into a signal nobody wrote.
- */
-export async function loadNarration(root: string): Promise<Narration> {
-  for (const ruleRoot of RULE_ROOTS) {
-    const dir = resolve(root, ruleRoot)
-    if (!existsSync(dir)) continue
-
-    const paths: string[] = []
-    for await (const rel of new Bun.Glob('**/*.md').scan({
-      cwd: dir,
-      onlyFiles: true,
-    })) {
-      paths.push(rel)
-    }
-    paths.sort()
-
-    for (const rel of paths) {
-      const source = await readFile(resolve(dir, rel), 'utf8')
-      const pronouns = parseTerms(source, PRONOUN_HEADING)
-      const verbs = parseTerms(source, VERB_HEADING)
-
-      if (pronouns && verbs && pronouns.length > 0 && verbs.length > 0) {
-        return {
-          kind: 'loaded',
-          source: `${ruleRoot}/${rel}`,
-          pronouns,
-          verbs,
-        }
-      }
-    }
-  }
-
-  return { kind: 'absent' }
-}