@erclx/canon 5.9.0 → 5.11.0

package/docs/agents/pr-evidence.md

@@ -1,6 +1,6 @@
 ---
 title: The pull request evidence comparison
-description: What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, and why the comparison anchors at the merge base rather than the previous push
+description: What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, what the --check read reports as owed, and why the comparison anchors at the merge base rather than the previous push
 ---
 
 # The pull request evidence comparison
@@ -58,6 +58,7 @@ image or marks the case new.
 | `no-base`              | GitHub reported no merge base for the pull request.                           |
 | `unreadable-changes`   | GitHub could not list what the pull request changed.                          |
 | `would-empty`          | The render holds no cases and the marked comment holds some. No body.         |
+| `check-writes`         | `--check` was passed with `--preview`, `--local`, or `--checklist`.           |
 
 `no-evidence` is not a refusal a caller reports. A project on a stack that
 carries no evidence path, such as `base` or `python`, hits this reason on
@@ -179,6 +180,52 @@ the checklist land in one comment rather than the checklist going out alone.
 `canon docs pr-local` covers where the address comes from and how the line is
 removed at close.
 
+## What a pull request is still owed
+
+`--check` reads the same changed set and the same thread, renders no body, and
+reports which steps of the ship chain that run after the pull request opens
+never landed on it. It reads the pull request rather than any session's account
+of what it ran, so a session that stopped after opening the pull request leaves
+a branch the check can tell apart from one that needed neither step.
+
+```bash
+canon pr evidence 1341 --check --json
+```
+
+| Reason    | What it means                                                      |
+| --------- | ------------------------------------------------------------------ |
+| `settled` | Nothing is owed. `owed` is empty.                                  |
+| `owed`    | `owed` lists `evidence`, `preview`, or both, always in that order. |
+
+- `evidence` is owed when the changed set carries an evidence image and no
+  comment carries the marker.
+- `preview` is owed when the pull request has a marked comment or an evidence
+  change, a deploy workflow resolves in the checkout the verb runs from, and
+  the marked comment's first line is no `**Preview:**` line. A
+  `**Local preview:**` line does not satisfy it. A project deploying nothing is
+  never owed a preview.
+
+The record carries `owed`, `commentId` when a marked comment exists, and the
+same `preview`, `local`, and `checklist` fields the other reasons carry, so a
+caller reads one shape. It never carries `body`, so a writer branching on `ok`
+and posting `body` cannot act on a check record. Passing `--preview`, `--local`,
+or `--checklist` with it refuses as `check-writes` before any `gh` call, since
+those ask a read to write.
+
+The thread cannot separate a skipped preview step from a failed one. A pull
+request whose deploy run failed or timed out reads as owing a preview, and the
+session that ran it holds the cause. A checklist posted on its own carries no
+marker, so a branch with a checklist and no evidence image never reads as
+owing a preview, though `git-pr` runs the preview step for it. The deploy
+workflow is read from the checkout rather than the pull request's head, so a
+pull request that adds or removes its own deploy workflow reads against trunk's.
+
+An unreadable thread refuses as `gh-failed` rather than reporting `settled` off
+a thread it never read. The check skips the merge base read, which only the
+render needs, so it never refuses `no-base`. The orchestrator's draft lift is
+the caller, and lifts only on `settled`, so a refusal holds it the same as
+`owed` does.
+
 ## What a collapsed comment still leaves to GitHub
 
 GitHub already draws its own before-and-after comparison on the Files Changed

package/docs/agents/scripting.md

@@ -79,9 +79,6 @@ surface is in `skills-audit.md`.
 ## Non-interactive examples
 
 ```bash
-# Create a new tooling stack
-CANON_NON_INTERACTIVE=1 canon tooling create astro
-
 # Report what a stack would change, writing nothing
 CANON_NON_INTERACTIVE=1 canon tooling diff astro /path/to/project
 

package/docs/agents/tasks-plans.md

@@ -135,15 +135,18 @@ canon tasks plan-link v28.1-trigger-escalation dispatch-answer-gate # canon-allo
 canon tasks plan-link v28.1-trigger-escalation .canon/plans/feature-dispatch-answer-gate.md --json
 ```
 
-| Option          | Behavior                                    |
-| --------------- | ------------------------------------------- |
-| `--json`        | Emit a machine-readable record on stdout    |
-| `--root <path>` | Board root, defaulting to the main worktree |
+| Option          | Behavior                                                  |
+| --------------- | --------------------------------------------------------- |
+| `--add`         | Append the plan to the line instead of replacing the link |
+| `--json`        | Emit a machine-readable record on stdout                  |
+| `--root <path>` | Board root, defaulting to the main worktree               |
 
 The plan resolves the same way `canon tasks plan-answers` resolves one, against the project root first and `.canon/tasks/` second, so a bare slug and a board-relative path both work. A reference resolving to no file refuses as `no-plan`, naming every base it looked under.
 
-The write adds the line when it is absent and corrects the target in place when it exists, anchored on the H1 rather than on the last origin line, since `Plan:` is the first origin line a task carries rather than the last. A `Plan:` line inside a fenced sample is skipped. The `action` field reports `added`, `corrected`, or `unchanged`, which makes a rerun against the same plan safe, and `replaced` names the target the line carried before when it differed.
+The write adds the line when it is absent and corrects the target in place when it exists, anchored on the H1 rather than on the last origin line, since `Plan:` is the first origin line a task carries rather than the last. A `Plan:` line inside a fenced sample is skipped. The `action` field reports `added`, `appended`, `corrected`, or `unchanged`, which makes a rerun against the same plan safe, and `replaced` names the target the line carried before when it differed.
 
 A line already linking several plans is refused as `several-plans` and left unchanged, with `detail` listing each link, even when one of them is the plan named. The verb cannot tell which link to drop, and reporting `unchanged` would hide a line that breaks the one-plan rule.
 
+A sliced task ships one plan per slice, so `--add` appends the plan to the line rather than replacing the link. It keeps every link in its order, writes a bare-path target as a link so it stays readable, leaves trailing prose and the line ending where they were, adds the line when the task carries none, reports `unchanged` and writes nothing when the plan is already listed, and is allowed on a line already holding several. Without the flag the replace behavior and the `several-plans` refusal above hold.
+
 Exit codes: `0` recorded, `1` refused. The `reason` field carries `no-board`, `no-match`, `no-plan`, `several-plans`, or `bad-input`.

package/docs/agents/worktrees.md

@@ -1,6 +1,6 @@
 ---
 title: Worktrees
-description: Reporting which worktrees are reclaimable, removing the ones that are, the record a hook reads back, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
+description: Reporting which worktrees are reclaimable, removing the ones that are, the hidden verb that clears a stranded bare flag, the record a hook reads back, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
 ---
 
 # Worktrees
@@ -24,6 +24,21 @@ Exit codes: `0` every worktree was read, `1` refused. The refusal carries a `rea
 
 An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `reason` rather than the exit when a skill consumes this.
 
+## Repair the bare flag
+
+`canon worktrees repair-bare-flag` clears a `core.bare` flag that Claude Code's worktree entry left set in the shared config. It is hidden, so no help listing shows it, because its one caller is a hook rather than a person.
+
+```bash
+canon worktrees repair-bare-flag --root <path> --json
+```
+
+| Option          | Behavior                              |
+| --------------- | ------------------------------------- |
+| `--root <path>` | Repository to repair, default the cwd |
+| `--json`        | Print the record on stdout            |
+
+`--json` writes `{repaired, reason, message}` on stdout, once, whether or not anything was written. `reason` is `flag-unset`, `common-dir-unreadable`, `genuinely-bare`, or `write-failed` when `repaired` is false. `message` carries text when the flag is repaired and when the write failed, and is null on the three quiet skips. A `write-failed` record means the flag is still set, which a lock file or a read-only config causes. A repository whose common dir is not named `.git` keeps its flag. The exit code is always `0`, so a hook never fails a tool call. Without `--json`, a record carrying a message prints it on stderr and any other prints nothing.
+
 ## Reclaim
 
 `canon worktrees reclaim` removes every worktree the reading above called reclaimable, and the branch behind each one.

package/docs/workflow/skill-map.md

@@ -8,7 +8,7 @@ category: Workflow
 
 Groups run in the order a project meets them, so a reader at a known point scans to that group and reads across. The set reconciles the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target/projects.md) describes, rather than inventing a third vocabulary beside those two, so a group name matches neither source exactly and every moment either one names has a group. Each row says when to reach for the skill. What it does is the skill's own description.
 
-This page is the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row here. A skill serving two moments sits at the earlier one, and a mention on any other page is prose rather than routing.
+This page is the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row here. A skill serving two moments sits at the earlier one, and a mention on any other page is prose rather than routing. The landing page's skills field renders from this page, so its build refuses a skill with no row and a row naming no skill.
 
 ## Set up a project
 
@@ -45,6 +45,7 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:project-commands`     | When the project's own command needs running                                                               |
 | `canon:test-first`           | Before implementing a planned change, to run its test red, green, then refactor                            |
 | `canon:test-craft`           | When writing or changing any test, to pick its layer and filter what it asserts                            |
+| `canon:api-design`           | When changing what a caller sees, being an export, a flag, an output shape, or a retried write             |
 | `canon:review-craft`         | When reviewing a change, for what to look for and how much evidence a finding needs                        |
 | `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first                                             |
 | `canon:design-taste`         | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.9.0",
+  "version": "5.11.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-agent-fixture.sh

@@ -91,9 +91,9 @@ if [ -z "$SESSIONS_JSON" ]; then
 fi
 
 # The listing crosses into the eval as a file rather than an environment entry,
-# for the reason regen-hero.sh records: Linux caps a single env string at 128KB
-# and a machine running many sessions can cross it, which fails the exec with
-# E2BIG before any check can report a thing.
+# since Linux caps a single env string at 128KB and a machine running many
+# sessions can cross it, which fails the exec with E2BIG before any check can
+# report a thing.
 SESSIONS_FILE="$(mktemp)"
 trap 'rm -f "$SESSIONS_FILE"' EXIT
 printf '%s' "$SESSIONS_JSON" >"$SESSIONS_FILE"

package/scripts/core/regen-hero.ts

@@ -0,0 +1,119 @@
+/**
+ * Fills every assets/captures/*.html.tmpl from the catalogs and the design
+ * source, writing the .html beside each one.
+ *
+ * The name says hero because the hero was the only template when it was written
+ * and every citation of it across docs/, canon/context/, and src/ spells that
+ * name. The loop below covers whatever templates the folder holds.
+ *
+ * Each catalog is read through the module its `canon` verb calls, so no child
+ * process runs and no stderr is discarded. The palette arrives from
+ * `buildDesignCss` without the component half, which is a scrollbar and a
+ * status marker a static capture frame renders neither of. The value builder
+ * and every guard live in `src/capture/frame-values.ts`, where tsc and vitest
+ * reach them.
+ *
+ * `--check` fills every template into a temp folder and discards it, so a
+ * renamed featured skill, an empty catalog, or an unresolved placeholder still
+ * fails a branch while no frame file changes. Frames are refreshed after a
+ * merge rather than committed by each branch.
+ *
+ * Only the HTML regenerates here. The PNG beside it is a chromium render whose
+ * bytes move with the browser version. Rebuild the images with
+ * `canon capture assets/captures --selector .window --out assets/evidence`
+ * after this script reports a change. That capture writes a .stamp beside each
+ * PNG, which records the digest of the markup it rendered and is what the Hero
+ * stage compares, so a frame's three files commit together. The frame carries
+ * no version, since `package.json` is bumped on main by the release tooling and
+ * embedding it would drift every open branch on the next release.
+ *
+ * Clone-only. This script reads the repository's own catalogs and
+ * `assets/captures`, which a registry install does not carry.
+ */
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  buildFrameValues,
+  FrameError,
+  fillTemplate,
+} from '../../src/capture/frame-values'
+import { listSkills } from '../../src/claude/skills-list'
+import { countCommands } from '../../src/counts/catalogs'
+import { buildDesignCss } from '../../src/design/css'
+import { buildGovCatalog } from '../../src/gov/list'
+import { listStandardEntries } from '../../src/standards/list'
+import { buildStackSummaries } from '../../src/tooling/list'
+
+const root = new URL('../..', import.meta.url).pathname
+const assetDir = join(root, 'assets', 'captures')
+
+const [flag, ...extra] = process.argv.slice(2)
+if (flag !== undefined && flag !== '--check') {
+  console.error(`regen-hero: unknown argument ${flag}`)
+  process.exit(1)
+}
+if (extra.length > 0) {
+  console.error(`regen-hero: unknown argument ${extra[0]}`)
+  process.exit(1)
+}
+
+const outDir =
+  flag === '--check' ? mkdtempSync(join(tmpdir(), 'regen-hero-')) : assetDir
+
+function run(): void {
+  const templates = readdirSync(assetDir)
+    .filter((name) => name.endsWith('.html.tmpl'))
+    .sort()
+  if (templates.length === 0) {
+    throw new FrameError(`no templates under ${assetDir}`)
+  }
+
+  const tokenCss = buildDesignCss(undefined, { components: false })
+  if (!tokenCss.trim()) {
+    throw new FrameError(
+      'the design source emitted nothing, refusing to write an unstyled frame',
+    )
+  }
+
+  const { values, frames } = buildFrameValues({
+    skills: listSkills(root).map((entry) => entry.name),
+    gov: buildGovCatalog(root),
+    // The toolkit root only: a project-local standard would put a row in the
+    // hero the toolkit does not ship.
+    standards: listStandardEntries(root).filter((entry) =>
+      entry.source.startsWith('standards/'),
+    ),
+    toolingStacks: buildStackSummaries(root),
+    commandCount: countCommands(root) ?? 0,
+    tokenCss,
+    markSvg: readFileSync(join(root, 'assets', 'brand', 'mark.svg'), 'utf8'),
+  })
+
+  mkdirSync(outDir, { recursive: true })
+  for (const { template, out, tokens } of frames(templates)) {
+    const source = readFileSync(join(assetDir, template), 'utf8')
+    writeFileSync(
+      join(outDir, out),
+      fillTemplate(template, source, values, tokens),
+    )
+  }
+}
+
+try {
+  run()
+} catch (error) {
+  if (!(error instanceof FrameError)) throw error
+  console.error(`regen-hero: ${error.message}`)
+  process.exitCode = 1
+} finally {
+  if (outDir !== assetDir) rmSync(outDir, { recursive: true, force: true })
+}

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

@@ -3,7 +3,7 @@
  * own colors in src/design/favicon.ts, apart from the page accent tokens.
  *
  * The page is the fourth surface to carry the mark as a favicon and the only
- * one that can answer for itself. `regen-hero.sh` and `src/design/render.ts`
+ * one that can answer for itself. `regen-hero.ts` and `src/design/render.ts`
  * each bake a single literal, because both embed the mark as a data URI and a
  * data URI has no CSS context. A file served at its own URL does have one, so
  * this copy carries a `prefers-color-scheme` branch and tracks the reader's

package/src/capture/frame-values.ts

@@ -0,0 +1,359 @@
+import type { GovCatalog } from '@/gov/list'
+import type { StackSummary } from '@/tooling/list'
+
+export const LISTED = 10
+
+/**
+ * The first seven are the method and exist nowhere else. The last three are
+ * recognizable on sight and are what keeps a column of chosen names from
+ * reading as an all-`claude-` catalog, which is the failure the sampler was
+ * written against.
+ */
+export const FEATURED_SKILLS = [
+  'plan-feature',
+  'plan-groundwork',
+  'plan-intake',
+  'role-orchestrator',
+  'auto-ship',
+  'review-pr',
+  'task-board',
+  'git-ship',
+  'target-setup',
+  'systematic-debugging',
+]
+
+/**
+ * A terminal frame sets `white-space: pre` at a fixed window width, so an
+ * overlong cell is clipped by the window edge rather than wrapped.
+ */
+const GLOB_WIDTH = 44
+
+/** A refusal the script prints as `regen-hero: <message>` and exits 1 on. */
+export class FrameError extends Error {}
+
+export interface StandardRow {
+  readonly name: string
+  readonly appliesTo?: readonly string[]
+}
+
+export interface FrameCatalogs {
+  readonly skills: readonly string[]
+  readonly gov: GovCatalog
+  readonly standards: readonly StandardRow[]
+  readonly toolingStacks: readonly StackSummary[]
+  readonly commandCount: number
+  readonly tokenCss: string
+  readonly markSvg: string
+}
+
+export interface Frame {
+  readonly template: string
+  readonly out: string
+  readonly tokens: string
+}
+
+export interface FrameValues {
+  readonly values: Readonly<Record<string, string>>
+  readonly frames: (templates: readonly string[]) => Frame[]
+}
+
+const escape = (value: string): string =>
+  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+/**
+ * Even spacing across the sorted catalog rather than its first N, so a column
+ * whose names share a prefix does not read as a narrower catalog than the one
+ * that ships. Rules and standards sample. Skills do not, because the even step
+ * lands on the entries closest to commodity and on none of the workflow the
+ * toolkit exists to carry.
+ */
+export function sample<T>(items: readonly T[], listed = LISTED): T[] {
+  if (items.length <= listed) return [...items]
+  const step = items.length / listed
+  return Array.from({ length: listed }, (_, i) => items[Math.floor(i * step)])
+}
+
+/**
+ * A chosen name is maintained by hand where a sample never goes stale, so a
+ * rename has to fail the run rather than quietly shrink the column. The length
+ * is asserted because the `+N more` figure counts down from `LISTED` rather
+ * than from what this returns.
+ */
+export function featured(
+  names: readonly string[],
+  chosen: readonly string[],
+  listed = LISTED,
+): string[] {
+  if (chosen.length !== listed) {
+    throw new FrameError(`${chosen.length} featured skills, expected ${listed}`)
+  }
+  const catalog = new Set(names)
+  const missing = chosen.filter((name) => !catalog.has(name))
+  if (missing.length > 0) {
+    throw new FrameError(
+      `featured skills missing from the catalog: ${missing.join(', ')}`,
+    )
+  }
+  return [...chosen]
+}
+
+/**
+ * Truncating keeps the longest row inside the capture, and the ellipsis stops a
+ * clipped value from reading as the whole value.
+ */
+export function clip(value: string, width: number): string {
+  return value.length <= width ? value : `${value.slice(0, width - 1)}…`
+}
+
+/**
+ * Padding happens before escaping, since an entity is longer than the
+ * character it replaces and would push a column out of line.
+ */
+export function pad(value: string, width: number): string {
+  return value + ' '.repeat(Math.max(0, width - value.length))
+}
+
+const markup = (names: readonly string[]): string =>
+  names
+    .map((name) => `            <div class="entry">${escape(name)}</div>`)
+    .join('\n')
+
+const remaining = (names: readonly unknown[], listed = LISTED): string =>
+  String(Math.max(0, names.length - listed))
+
+const plural = (count: number, noun: string): string =>
+  `${count} ${noun}${count === 1 ? '' : 's'}`
+
+const frameRow = (cells: string): string =>
+  `<span class="frame">│</span> <span class="ok">✓</span> ${cells}`
+
+/** Rule names carry a numeric prefix that orders the load, not the identity. */
+const slug = (name: string): string => name.replace(/^\d+-/, '')
+
+/** Indented to the depth a rule inside the `<style>` block sits at. */
+const indentTokens = (css: string): string =>
+  css
+    .trimEnd()
+    .split('\n')
+    .map((line) => (line === '' ? '' : `      ${line}`))
+    .join('\n')
+
+/**
+ * The frames a README serves in both themes. The hero is a landing-page frame
+ * no README shows, so it stays dark.
+ */
+const LIGHT_TEMPLATES = new Set(['install.html.tmpl'])
+
+function lightTokens(tokenCss: string): string {
+  const roles = [...tokenCss.matchAll(/--color-light-([a-z-]+):/g)].map(
+    (match) => match[1],
+  )
+  if (roles.length === 0) {
+    throw new FrameError(
+      'token css carries no --color-light-* roles, refusing to write a light frame',
+    )
+  }
+  return [
+    tokenCss,
+    '',
+    '      :root {',
+    ...roles.map(
+      (role) => `        --color-${role}: var(--color-light-${role});`,
+    ),
+    '        --frame-shadow: rgb(0 0 0 / 16%);',
+    '      }',
+  ].join('\n')
+}
+
+function faviconUri(markSvg: string, tokenCss: string): string {
+  const accent = tokenCss.match(/--color-accent:\s*(#[0-9a-fA-F]{3,8})/)
+  if (!accent) {
+    throw new FrameError(
+      'token css carries no --color-accent value, refusing to write a colorless favicon',
+    )
+  }
+  const svg = markSvg
+    .replace(/<!--[\s\S]*?-->/, '')
+    .trim()
+    .replaceAll('currentColor', accent[1])
+  return `data:image/svg+xml,${encodeURIComponent(svg)}`
+}
+
+/**
+ * Builds the value map every template takes and the frame list a template set
+ * expands to. An empty array is well-formed, and the in-process readers return
+ * one quietly for a missing tree, so every catalog is refused when empty
+ * rather than shipping a frame claiming the domain has nothing in it.
+ */
+export function buildFrameValues(catalogs: FrameCatalogs): FrameValues {
+  const { gov, toolingStacks, standards, skills } = catalogs
+  const markSvg = catalogs.markSvg.trim()
+  if (!markSvg) {
+    throw new FrameError(
+      'assets/brand/mark.svg read empty, refusing to write a hero with no mark',
+    )
+  }
+  if (!catalogs.commandCount) {
+    throw new FrameError(
+      'the commands catalog read no commands, refusing to write a zeroed hero',
+    )
+  }
+
+  const tokenCss = indentTokens(catalogs.tokenCss)
+  const rules = gov.rules.map((entry) => slug(entry.name))
+  // A rule no stack names is opt-in behind `--add`, so featuring one advertises
+  // an entry no ordinary `canon gov install` delivers. The column samples the
+  // stack-reached subset while its count and remainder describe the whole.
+  const stacked = new Set(gov.stacks.flatMap((stack) => stack.rules))
+  const deliveredEntries = gov.rules.filter((entry) => stacked.has(entry.name))
+  const deliveredRules = deliveredEntries.map((entry) => slug(entry.name))
+  const standardNames = standards.map((entry) => entry.name)
+
+  for (const [label, list] of [
+    ['skills', skills],
+    ['rules', rules],
+    ['standards', standardNames],
+    ['tooling stacks', toolingStacks],
+    ['gov stacks', gov.stacks],
+    ['stack-delivered rules', deliveredRules],
+  ] as const) {
+    if (list.length === 0) {
+      throw new FrameError(
+        `the ${label} catalog is empty, refusing to write a zeroed hero`,
+      )
+    }
+  }
+
+  const govStackRows = gov.stacks
+    .map((stack) =>
+      frameRow(
+        `<span class="name">${escape(pad(stack.name, 17))}</span>` +
+          `<span class="muted">${escape(pad(plural(stack.rules.length, 'rule'), 11))}</span>` +
+          `<span class="muted">${escape(stack.extends ? `extends ${stack.extends}` : '')}</span>`,
+      ),
+    )
+    .join('\n')
+
+  // Each rule sits beside the glob that loads it rather than its description,
+  // since the glob is the mechanism a reader cannot otherwise see. A rule
+  // carrying no glob is not unscoped, it loads every session, and saying so is
+  // the contrast that makes the column mean anything.
+  const govRuleRows = sample(deliveredEntries)
+    .map((entry) => {
+      const globs = entry.paths ?? []
+      const scope =
+        globs.length > 0 ? clip(globs.join(' '), GLOB_WIDTH) : 'every session'
+      return frameRow(
+        `<span class="name">${escape(pad(slug(entry.name), 24))}</span>` +
+          `<span class="domain">${escape(pad(`[${entry.domain}]`, 12))}</span>` +
+          `<span class="muted">${escape(scope)}</span>`,
+      )
+    })
+    .join('\n')
+
+  // A standard either governs an artifact by path or is opened by name when a
+  // session decides it needs it. Naming the second is the contrast, since
+  // nothing else tells a reader the corpus installs into no project.
+  const standardRows = sample(standards)
+    .map((entry) => {
+      const applies = entry.appliesTo ?? []
+      const governs =
+        applies.length > 0
+          ? clip(applies.join(' '), GLOB_WIDTH)
+          : 'read by name'
+      return frameRow(
+        `<span class="name">${escape(pad(entry.name, 18))}</span>` +
+          `<span class="muted">${escape(governs)}</span>`,
+      )
+    })
+    .join('\n')
+
+  // A tooling stack is counted rather than listed, because what it lays down is
+  // dev dependencies, run scripts, and ignore groups rather than named entries.
+  // The inheritance is the part worth showing, since it is why a stack carrying
+  // two of its own arrives with far more than two.
+  const toolingStackRows = toolingStacks
+    .map((stack) =>
+      frameRow(
+        `<span class="name">${escape(pad(stack.name, 14))}</span>` +
+          `<span class="muted">${escape(pad(plural(stack.devDeps, 'dep'), 10))}</span>` +
+          `<span class="muted">${escape(pad(plural(stack.scripts, 'script'), 12))}</span>` +
+          `<span class="muted">${escape(stack.extends ? `extends ${stack.extends}` : '')}</span>`,
+      ),
+    )
+    .join('\n')
+
+  for (const [label, rows] of [
+    ['governance stack rows', govStackRows],
+    ['governance rule rows', govRuleRows],
+    ['standard rows', standardRows],
+    ['tooling stack rows', toolingStackRows],
+  ] as const) {
+    if (rows === '') {
+      throw new FrameError(
+        `the ${label} rendered empty, refusing to write a blank frame`,
+      )
+    }
+  }
+
+  const values: Record<string, string> = {
+    TOKENS: tokenCss,
+    GOV_STACK_ROWS: govStackRows,
+    GOV_RULE_ROWS: govRuleRows,
+    STANDARD_ROWS: standardRows,
+    TOOLING_STACK_ROWS: toolingStackRows,
+    SKILL_COUNT: String(skills.length),
+    RULE_COUNT: String(rules.length),
+    STANDARD_COUNT: String(standardNames.length),
+    GOV_STACK_COUNT: String(gov.stacks.length),
+    TOOLING_STACK_COUNT: String(toolingStacks.length),
+    COMMAND_COUNT: String(catalogs.commandCount),
+    MARK_SVG: markSvg,
+    FAVICON: faviconUri(markSvg, tokenCss),
+    SKILL_ENTRIES: markup(featured(skills, FEATURED_SKILLS)),
+    RULE_ENTRIES: markup(sample(deliveredRules)),
+    STANDARD_ENTRIES: markup(sample(standardNames)),
+    SKILL_MORE: remaining(skills),
+    RULE_MORE: remaining(rules),
+    STANDARD_MORE: remaining(standardNames),
+  }
+
+  const light = lightTokens(tokenCss)
+
+  return {
+    values,
+    frames: (templates) =>
+      templates.flatMap((template) => {
+        const base = template.replace(/\.html\.tmpl$/, '')
+        const dark = { template, out: `${base}.html`, tokens: tokenCss }
+        return LIGHT_TEMPLATES.has(template)
+          ? [dark, { template, out: `${base}-light.html`, tokens: light }]
+          : [dark]
+      }),
+  }
+}
+
+/**
+ * Every template takes the same value map, so one carrying no count
+ * placeholder simply resolves none of them. What a template must not do is name
+ * a placeholder nothing fills.
+ */
+export function fillTemplate(
+  template: string,
+  source: string,
+  values: Readonly<Record<string, string>>,
+  tokens: string,
+): string {
+  let html = source
+  for (const [key, value] of Object.entries({ ...values, TOKENS: tokens })) {
+    html = html.replaceAll(`{{${key}}}`, value)
+  }
+
+  const unresolved = html.match(/{{[A-Z_]+}}/g)
+  if (unresolved) {
+    throw new FrameError(
+      `${template} carries unresolved placeholders ${[...new Set(unresolved)].join(', ')}`,
+    )
+  }
+  return html
+}