@erclx/canon 4.101.0 → 4.103.0

package/docs/workflow/ai-workflow.md

@@ -65,7 +65,9 @@ The routing test is whether the repository can answer an item today. A session g
 
 A groundwork track may run experiments to settle a question, writing a fixture it reads itself under `.canon/tmp/runs/groundwork-fixtures/<slug>/` and spawning up to three billed headless runs before it asks. A fixture a headless run is pointed at sits outside the repository, since a session started under the project root inherits that project's `CLAUDE.md` and rules and would measure them instead of the arm.
 
-What a spike produces goes somewhere else again. An input the run reads is re-runnable and cited by nothing, so the scratch path above is the right lifetime for it, while a recording or a render the track cites as evidence for a finding is what a later reader opens to check the claim. Evidence therefore lives in `evidence/` inside the track beside the file citing it, since the scratch tree holds only what can be deleted without loss.
+A spike starts against a sample, bounded on input size, duration, and spend, and scales up once the sample shows the method works. Nothing checks this, so it holds while a session reads the standard.
+
+What a spike leaves behind splits on whether a later reader needs the file to check a claim. Bulk input, such as a large fixture, is re-runnable and cited by nothing, so the scratch path above is the right lifetime for it. Everything a reader opens to verify a result lives inside the track in one of three folders: `evidence/` for a recording or a render, `scripts/` for the arm scripts, and `clones/` for checkouts and copies of outside material a claim rests on. The scratch tree holds only what can be deleted without loss, which none of those is.
 
 #### Session 2
 
@@ -166,7 +168,7 @@ The list stays written in the skill body as the fallback for a target whose inst
 
 Capture leads rather than trails because a routed fact edits a tracked file, which has to reach the branch before the commit steps run.
 
-If capture wrote at least one memory file, `memory-review` then proposes a decision-ready fix scoped to those entries while context is fresh, otherwise it is skipped. It stops at Propose. Review the receipt and run Apply yourself, on its own commit separate from the feature.
+The chain ends at capture, and review is run on its own.
 
 Run `memory-review` standalone to curate the whole pen. An entry it retires moves to `.canon/memory/archive/` rather than being deleted, since a bulk pass has no undo.
 
@@ -260,7 +262,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:git-commit`     | When the staged set is one concern, or was staged hunk by hand                        |
 | `canon:git-branch`     | When a branch name needs generating or renaming to conventional form                  |
 | `canon:git-pr`         | When a pull request needs a title and body written from the diff                      |
-| `canon:memory-review`  | After capture writes an entry, to propose where each one belongs                      |
+| `canon:memory-review`  | When the pen has grown, to propose where each entry belongs                           |
 
 ### After the pull request opens
 
@@ -287,16 +289,17 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Keep the project current with the toolkit
 
-| Skill                            | When to use                                                                        |
-| -------------------------------- | ---------------------------------------------------------------------------------- |
-| `canon:seed-sync`                | After a toolkit update, to reconcile installed seeds without losing customizations |
-| `canon:migration-claude-md`      | When `CLAUDE.md` grew past what always-load context should carry                   |
-| `canon:migration-context`        | When `docs/` holds agent-flavored files belonging in `canon/context/`              |
-| `canon:migration-superseded`     | When a drift report names a `.claude/` file a folder has replaced                  |
-| `canon:migration-standards-drop` | When the project still holds an installed `.claude/standards/` tree                |
-| `canon:canon-feedback-file`      | When something in the toolkit is broken, missing, or off                           |
-| `canon:canon-feedback-triage`    | In the toolkit repo, to work through the open feedback issues                      |
-| `canon:canon-rollout`            | In the toolkit repo, to take one change out to every consuming project at once     |
+| Skill                            | When to use                                                                            |
+| -------------------------------- | -------------------------------------------------------------------------------------- |
+| `canon:target-check`             | In a target project, to report per domain what it holds against what the toolkit ships |
+| `canon:seed-sync`                | After a toolkit update, to reconcile installed seeds without losing customizations     |
+| `canon:migration-claude-md`      | When `CLAUDE.md` grew past what always-load context should carry                       |
+| `canon:migration-context`        | When `docs/` holds agent-flavored files belonging in `canon/context/`                  |
+| `canon:migration-superseded`     | When a drift report names a `.claude/` file a folder has replaced                      |
+| `canon:migration-standards-drop` | When the project still holds an installed `.claude/standards/` tree                    |
+| `canon:canon-feedback-file`      | When something in the toolkit is broken, missing, or off                               |
+| `canon:canon-feedback-triage`    | In the toolkit repo, to work through the open feedback issues                          |
+| `canon:canon-rollout`            | In the toolkit repo, to take one change out to every consuming project at once         |
 
 ### Generate an artifact on demand
 

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

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

package/package.json

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

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

@@ -1,6 +1,6 @@
 /**
- * Writes web/public/favicon.svg from assets/brand/mark.svg and the design
- * source's two accent values.
+ * Writes web/public/favicon.svg from assets/brand/mark.svg and the favicon's
+ * 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`
@@ -17,6 +17,8 @@
  */
 import { writeFileSync } from 'node:fs'
 
+import { FAVICON_COLORS, renderFavicon } from '../../src/design/favicon'
+
 const root = new URL('../..', import.meta.url).pathname
 
 const mark = (await Bun.file(`${root}assets/brand/mark.svg`).text()).trim()
@@ -25,43 +27,10 @@ if (!mark) {
   process.exit(1)
 }
 
-const tokenCss = await Bun.file(`${root}web/src/styles/tokens.css`).text()
-const read = (name: string): string => {
-  const match = tokenCss.match(
-    new RegExp(`--color-${name}:\\s*(#[0-9a-fA-F]{3,8})`),
-  )
-  if (!match) {
-    console.error(
-      `regen-web-favicon: tokens.css carries no --color-${name}, refusing to write a colorless favicon`,
-    )
-    process.exit(1)
-  }
-  return match[1] as string
-}
-
-const dark = read('accent')
-const light = read('light-accent')
-
-// The shapes only, with the source's authoring comment dropped. Both fills are
-// replaced by a rule rather than an attribute so one branch can flip both.
-const shapes = mark
-  .replace(/<!--[\s\S]*?-->/, '')
-  .trim()
-  .replace(/^<svg[^>]*>/, '')
-  .replace(/<\/svg>$/, '')
-  .replaceAll(' fill="currentColor"', '')
-  .trim()
-
-const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 10 80 80">
-  <style>
-    path, rect { fill: ${light}; }
-    @media (prefers-color-scheme: dark) { path, rect { fill: ${dark}; } }
-  </style>
-  ${shapes.replace(/\n\s*/g, '\n  ')}
-</svg>
-`
-
-writeFileSync(`${root}web/public/favicon.svg`, svg)
+writeFileSync(
+  `${root}web/public/favicon.svg`,
+  renderFavicon(mark, FAVICON_COLORS),
+)
 console.log(
-  `regen-web-favicon: wrote web/public/favicon.svg (${light} / ${dark})`,
+  `regen-web-favicon: wrote web/public/favicon.svg (${FAVICON_COLORS.light} / ${FAVICON_COLORS.dark})`,
 )

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

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

package/src/claude/cases/setup.ts

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

package/src/commands/design.ts

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

package/src/commands/tooling.ts

@@ -39,6 +39,12 @@ interface SyncOptions {
   readonly skip?: string
   readonly check?: boolean
   readonly write?: boolean
+  readonly diff?: { readonly json: boolean }
+}
+
+interface DiffOptions {
+  readonly skip?: string
+  readonly json?: boolean
 }
 
 interface InjectOptions {
@@ -59,7 +65,7 @@ interface ListOptions {
 
 type Prepared =
   | { readonly ok: true; readonly chain: Manifest[]; readonly target: string }
-  | { readonly ok: false; readonly error: string }
+  | { readonly ok: false; readonly reason: string; readonly error: string }
 
 export function register(program: Command): void {
   const tooling = program
@@ -74,7 +80,10 @@ export function register(program: Command): void {
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
     .option('--skip <stack>', 'Drop a layer from the extends chain')
-    .option('--check', 'Report what would change and write nothing')
+    .option(
+      '--check',
+      'Report what would change and write nothing, always exiting 0. Prefer `canon tooling diff`',
+    )
     .option('--write', 'Apply every change without prompting')
     .addHelpText(
       'after',
@@ -98,6 +107,42 @@ export function register(program: Command): void {
       },
     )
 
+  tooling
+    .command('diff')
+    .description('Report how a target differs from a stack and write nothing')
+    .argument('[stack]', 'Tooling stack name (e.g. base, vite-react)')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--skip <stack>', 'Drop a layer from the extends chain')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'The comparison `canon tooling sync --check` reports, under a name that',
+        'says it only asks. Exit codes:',
+        '  0  the target matches the stack',
+        '  1  a file, script, dependency, or gitignore entry differs, or a refusal',
+        '',
+        '`sync --check` reports the same list and always exits 0. Use `diff` to',
+        'gate CI, and keep `--check` for scripts that already call it.',
+        '',
+        'Examples:',
+        '  canon tooling diff base',
+        '  canon tooling diff base --json',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (stack: string | undefined, target: string, opts: DiffOptions) => {
+        process.exitCode = await runSync(stack, target, {
+          skip: opts.skip,
+          check: true,
+          diff: { json: opts.json === true },
+        })
+      },
+    )
+
   tooling
     .command('inject')
     .description('Apply one stack to a target without scanning or prompting')
@@ -239,18 +284,27 @@ function prepare(stack: string, target: string, skip?: string): Prepared {
   if (mismatch !== undefined) logWarn(mismatch)
 
   if (!stackExists(PROJECT_ROOT, stack)) {
-    return { ok: false, error: `Stack not found: ${stack}` }
+    return {
+      ok: false,
+      reason: 'unknown-stack',
+      error: `Stack not found: ${stack}`,
+    }
   }
 
   if (skip !== undefined) {
     if (skip === stack) {
       return {
         ok: false,
+        reason: 'bad-skip',
         error: `Cannot --skip the stack being synced: ${skip}`,
       }
     }
     if (!stackExists(PROJECT_ROOT, skip)) {
-      return { ok: false, error: `Stack to skip not found: ${skip}` }
+      return {
+        ok: false,
+        reason: 'unknown-skip',
+        error: `Stack to skip not found: ${skip}`,
+      }
     }
   }
 
@@ -258,6 +312,7 @@ function prepare(stack: string, target: string, skip?: string): Prepared {
   if (resolved === PROJECT_ROOT) {
     return {
       ok: false,
+      reason: 'toolkit-root',
       error:
         'Cannot run against toolkit root. Files here are the source of truth.',
     }
@@ -275,40 +330,44 @@ async function runSync(
   target: string,
   opts: SyncOptions,
 ): Promise<number> {
-  intro('canon tooling sync')
+  intro(opts.diff === undefined ? 'canon tooling sync' : 'canon tooling diff')
 
   if (opts.check === true && opts.write === true) {
-    logWarn('Pass --check or --write, not both.')
-    outro()
-    return 1
+    return refuse(
+      opts,
+      'conflicting-flags',
+      'Pass --check or --write, not both.',
+    )
   }
 
   const selected = stack ?? (await promptForStack())
   if (selected === undefined) {
-    logWarn('No tooling stacks found')
-    outro()
-    return 1
+    return refuse(opts, 'no-stacks', 'No tooling stacks found')
   }
 
   if (isStackExcluded(selected)) {
-    logWarn(
+    return refuse(
+      opts,
+      'excluded-stack',
       'Claude is managed by `canon claude`, not `canon tooling`. Run `canon claude sync` instead.',
     )
-    outro()
-    return 1
   }
 
   const prepared = prepare(selected, target, opts.skip)
-  if (!prepared.ok) {
-    logWarn(prepared.error)
-    outro()
-    return 1
-  }
+  if (!prepared.ok) return refuse(opts, prepared.reason, prepared.error)
 
   const result = scan(prepared.chain, prepared.target)
 
   report(result)
 
+  if (opts.diff !== undefined) {
+    if (opts.diff.json) {
+      process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`)
+    }
+    outro()
+    return result.totalChanges === 0 ? 0 : 1
+  }
+
   const mode = resolveWriteMode(opts)
   const { GREEN, NC } = palette(process.stderr)
 
@@ -353,6 +412,20 @@ async function runSync(
   return 0
 }
 
+/**
+ * A diff caller branches on the record rather than the exit, since a shell
+ * wrapper can flatten the status. Every refusal therefore answers with a reason
+ * on stdout under `--json`, beside the exit 1 that keeps a gate failing.
+ */
+function refuse(opts: SyncOptions, reason: string, message: string): number {
+  logWarn(message)
+  if (opts.diff?.json) {
+    process.stdout.write(`${JSON.stringify({ ok: false, reason, message })}\n`)
+  }
+  outro()
+  return 1
+}
+
 type WriteMode = 'apply' | 'prompt' | 'report' | 'unauthorized'
 
 type ApplyDecision = 'apply' | 'cancelled' | 'reported' | 'unauthorized'

package/src/design/css.ts

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

package/src/design/favicon.ts

@@ -0,0 +1,33 @@
+export interface FaviconColors {
+  readonly light: string
+  readonly dark: string
+}
+
+/** The favicon's own fills, chosen for tab size and apart from the page accent tokens. */
+export const FAVICON_COLORS: FaviconColors = {
+  light: '#c42938',
+  dark: '#e54e40',
+}
+
+/**
+ * The shapes only, with the source's authoring comment dropped. Both fills are
+ * replaced by a rule rather than an attribute so one branch can flip both.
+ */
+export function renderFavicon(mark: string, colors: FaviconColors): string {
+  const shapes = mark
+    .replace(/<!--[\s\S]*?-->/, '')
+    .trim()
+    .replace(/^<svg[^>]*>/, '')
+    .replace(/<\/svg>$/, '')
+    .replaceAll(' fill="currentColor"', '')
+    .trim()
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 10 80 80">
+  <style>
+    path, rect { fill: ${colors.light}; }
+    @media (prefers-color-scheme: dark) { path, rect { fill: ${colors.dark}; } }
+  </style>
+  ${shapes.replace(/\n\s*/g, '\n  ')}
+</svg>
+`
+}

package/src/design/render.ts

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

package/src/design/tokens.ts

@@ -377,7 +377,7 @@ export const TOKENS: DesignTokens = {
   iconography: [
     'No icon library is installed. `assets/brand/mark.svg` is the one authored icon, embedded inline in the hero topbar, and the surfaces otherwise draw literal glyph characters: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing.',
     '',
-    'The same mark ships as a favicon on every rendered surface, as three independently-maintained copies that track different accents by design rather than by drift, colored to fit the chrome each renders on: the dark accent (`#e0724b`) for a dark-chrome surface and the light accent (`#a4471c`) for a light-chrome one. Unifying the three or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design.md` carries which file holds each copy.',
+    'The same mark ships in six independently-maintained copies that carry different colors by design rather than by drift, each fitted to the chrome it renders on: the dark accent for a dark-chrome surface, the light accent for a light-chrome one, and the pair the web favicon takes from `src/design/favicon.ts`. Unifying them or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design.md` carries which file holds each copy.',
   ].join('\n'),
 }
 

package/standards/groundwork.md

@@ -130,9 +130,15 @@ Each spike carries four things:
 
 Cost is a report rather than a limit, and it is what makes the next spike estimable before anyone commits to it. Record it even when it comes to a single read.
 
-A spike also leaves files behind, and they split on whether the track cites them rather than on whether they are markdown. An input the run reads, being a fixture page, an arm script, or a copied asset, is re-runnable and cited by nothing, so it stays outside the track wherever the surface driving the spike puts it. Evidence the record cites, being a recording, a render, or a frame pulled from one, is what a later reader opens to check a claim, so it lives in `evidence/` inside the track beside the file citing it. Name the split rather than the file types, which is what keeps this from going stale on the next kind of artifact a spike produces.
+Start a spike against a sample and scale up only once the sample shows the method works. Bound the sample on all three of input size, duration, and spend, since fifty minutes of audio is a runtime and a bill before it is a file size, and three minutes of it usually shows whether the pipeline runs at all. The same holds for a dataset, an image set, or a batch of queries. Record the sample's bounds and the figure for the full input in the spike, so a reader can tell what the result was measured on and what the scale-up costs. The rule reaches only a track, since that is the surface that reads this standard, and nothing checks that a spike ran small first, so it holds only while a session reads it.
 
-`evidence/` takes no number, since numbering is the read order over the files a reader opens in sequence and an artifact is reached from the claim that cites it instead.
+A spike also leaves files behind, and they split on whether a later reader needs the file to check a claim rather than on whether it is markdown or re-runnable. A file a reader opens to verify how a result was produced or what it showed lives inside the track. A file that is only bulk input, such as a large fixture or a copied asset, stays outside it wherever the surface driving the spike puts it. Three subfolders inside the track carry the first kind, and none takes a number, since numbering is the read order over the files a reader opens in sequence and these are reached from the claim that cites them instead:
+
+- `evidence/`: what a run produced and the record cites, being a recording, a render, or a frame pulled from one, beside the file citing it.
+- `scripts/`: the arm scripts and harnesses a spike ran. An arm script is re-runnable, and it is also what a reader opens to check the method, so this refines the earlier split, which sorted on re-runnable alone, and does not contradict it.
+- `clones/`: checkouts and copies of outside material a claim rests on, kept small enough to hold in the folder. A checkout too large to keep is cited by its address and commit instead.
+
+`spikes/`, `web/`, and `research/` were considered and folded into these, so do not reopen them. A spike's files sit under the three above, and a fetched page belongs in `clones/`. The `web/` case is the arguable one, since a screenshot of a reference site could sit apart, and it folds into `evidence/` because that is where a cited artifact already lives.
 
 Reach for a test harness the project already carries before building one. A track needing an experiment no existing harness can express has found a finding, and it belongs in the folder rather than in a new abstraction.
 

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.