@erclx/canon 5.69.0 → 5.70.0

package/src/commands/take.ts

@@ -1,7 +1,9 @@
-import { readFileSync } from 'node:fs'
+import { readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
+import { cameraTrack, readRate } from '@/take/camera'
+import { readTakeLog } from '@/take/log'
 import { readTakePlan } from '@/take/plan'
 import type { TakePlanRefusal } from '@/take/plan'
 import type { TakeRefusal } from '@/take/film'
@@ -24,11 +26,17 @@ import {
 type Take = typeof import('@/take/film')
 
 interface RunOptions {
-  readonly out: string
+  readonly out?: string
   readonly reel?: string
   readonly json?: boolean
 }
 
+interface CameraOptions {
+  readonly out?: string
+  readonly rate?: string
+  readonly json?: boolean
+}
+
 const INSTALL_FFMPEG =
   'install FFmpeg from your package manager, such as apt install ffmpeg or brew install ffmpeg'
 
@@ -40,7 +48,8 @@ const PLAN_REFUSALS: Record<TakePlanRefusal, string> = {
   'bad-beat':
     'A beat is missing its name or carries a setup that is not a list.',
   'no-steps': 'A beat names no step, so its take would film nothing.',
-  'unknown-route': 'A beat names a route this build does not record on.',
+  'unknown-route':
+    'The plan or a beat names a route this build does not record on.',
   'bad-step': 'A step is missing something the take needs to perform it.',
 }
 
@@ -53,14 +62,19 @@ const TAKE_REFUSALS: Record<TakeRefusal, string> = {
 }
 
 export function register(program: Command): void {
-  program
+  const take = program
     .command('take')
     .description(
       'Film a web app beat by beat with a click log and camera track',
     )
     .argument('<url>', 'Address to film')
     .argument('<plan>', 'JSON file naming the beats and their steps')
-    .requiredOption('--out <dir>', 'Folder the clips, logs, and tracks land in')
+    // Checked in the action rather than required here, since commander checks
+    // a parent's required options on every subcommand, `camera` included.
+    .option('--out <dir>', 'Folder the clips, logs, and tracks land in')
+    // Keeps this command's options ahead of `camera`, which reuses --out and
+    // --json for its own.
+    .enablePositionalOptions()
     .helpOption('-h, --help', 'Show this help message')
     .option(
       '--reel <file>',
@@ -106,12 +120,33 @@ export function register(program: Command): void {
         'Step kinds:',
         '  move <target>|<x,y>    glide the pointer to a target or a point',
         '  click <target>         glide to the target and press it',
+        '  dblclick <target>      glide to the target and press it twice',
+        '  drag <from> <to>       press the from target, glide held, release on to',
+        '  key <keys>             press a combination such as Control+K',
         '  fill <target> <text>   press the target and type the text',
         '  scroll <target> <dy>   glide to the target and wheel dy pixels',
         '  wait <ms>              hold, for a state the page reaches on its own',
         '',
-        'A target is a CSS selector, or text=<words> for the innermost element',
-        'whose whole text is those words. Setup steps run before the first kept',
+        'click, dblclick, and drag take modifiers, a list of Alt, Control, Meta,',
+        'and Shift held through the press, as in "modifiers": ["Shift"]. keys',
+        'names those modifiers joined by + ahead of one character or a named key:',
+        'Enter, Tab, Escape, Backspace, Delete, Insert, Space, Home, End, PageUp,',
+        'PageDown, the four arrows as ArrowUp and the like, and F1 to F12. A key',
+        'moves no pointer, so the camera neither aims at it nor ends a zoom.',
+        '',
+        'drag drives pointer events, the kind a canvas board listens for. It',
+        'starts no native HTML5 drag of a draggable element on the stepped route,',
+        'so a beat needing one films the same only on the screencast route.',
+        '',
+        'A top-level route sets the route of every beat that names none of its',
+        'own. A beat carrying push: false keeps its camera on the whole page,',
+        'with the cursor and click ring still in the track, and its log.json',
+        'records push: false. Each log.json carries clip, the clip size in',
+        'pixels, which caps the zoom depth so a 1920-wide screencast stays sharp.',
+        '',
+        'A target is a CSS selector, or text=<words> for the first innermost',
+        'element with a size whose whole text is those words, so a hidden copy',
+        'earlier in the page is skipped. Setup steps run before the first kept',
         'frame. Every beat opens and closes on a 0.6 s hold.',
         '',
         'Needs a reachable page, FFmpeg, and the headless shell. Install with:',
@@ -123,7 +158,8 @@ export function register(program: Command): void {
         '  no-beats            the plan names no beat',
         '  bad-beat            a beat has no name or a setup that is not a list',
         '  no-steps            a beat names no step',
-        '  unknown-route       a beat names a route other than step or screencast',
+        '  unknown-route       the plan or a beat names a route other than step or',
+        '                      screencast',
         '  bad-step            a step is missing what the take needs to perform it',
         '  engine-missing      the browser engine is not installed in this project',
         '  ffmpeg-missing      FFmpeg is not on the PATH',
@@ -133,6 +169,13 @@ export function register(program: Command): void {
         '  take-failed         the take failed against a reachable page',
         '  reel-failed         every beat was filmed and the reel did not encode',
         '',
+        'A refusal in a beat carries beat. target-missing carries still when the',
+        "page answered a capture, the beat folder's still.jpg as the step met it. A",
+        'beat that fell back to the screencast before refusing carries fallback,',
+        'the reason it fell back. The screencast opens the address a second time,',
+        'so a single-use link is spent by then: check the access before the',
+        'selector.',
+        '',
         'Exit codes:',
         '  0  every beat was filmed, and the reel written when asked for',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -144,15 +187,113 @@ export function register(program: Command): void {
         '',
       ].join('\n'),
     )
-    .action(async (url: string, plan: string, opts: RunOptions) => {
-      process.exitCode = await runTake(url, plan, opts)
+    .action(
+      async (url: string, plan: string, opts: RunOptions, command: Command) => {
+        if (!opts.out)
+          command.error("error: required option '--out <dir>' not specified")
+        process.exitCode = await runTake(url, plan, { ...opts, out: opts.out })
+      },
+    )
+
+  take
+    .command('camera')
+    .description("Build a camera track from a take's log.json")
+    .argument('<log>', "A beat's log.json, as a take wrote it")
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--out <file>', 'Write the track to a file rather than stdout')
+    .option(
+      '--rate <n>',
+      'How many times faster the edit plays the clip, 1 by default',
+    )
+    .option('--json', 'Add a machine-readable record on stdout with --out')
+    .addHelpText(
+      'after',
+      [
+        '',
+        "Builds the same camera track a take writes beside each beat's clip, from",
+        'the log alone, so a track can be rebuilt for a clip the edit plays at',
+        'another speed. With no --out the track is the data on stdout, one line,',
+        'and a refusal under --json is the record there instead.',
+        '',
+        '--rate <n> builds the track on the playback clock of a clip sped up n',
+        'times, dividing every time in the log by n, so a zoom settles at the',
+        'speed a viewer sees rather than pumping several times a beat.',
+        '',
+        "The zoom depth is capped by the clip's resolution, read from the log's",
+        'clip field, or from its route on a log written before that field. A log',
+        'carrying push: false holds the whole page with the cursor and ring.',
+        '',
+        'Reasons:',
+        '  no-log-file     nothing readable at the log path',
+        "  unreadable-log  the file is not a take's log.json",
+        '  bad-rate        --rate is not a positive number',
+        '',
+        'Exit codes:',
+        '  0  the track was written',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        "  canon take camera takes/01-open/log.json | jq '.frames | length'",
+        '  canon take camera takes/01-open/log.json --rate 2 --out camera-2x.json',
+        '',
+      ].join('\n'),
+    )
+    .action((log: string, opts: CameraOptions) => {
+      process.exitCode = runCamera(log, opts)
     })
 }
 
+function runCamera(logPath: string, opts: CameraOptions): number {
+  const emitJson = opts.json ?? false
+  const path = resolve(logPath)
+  const refuseCamera = (reason: string, message: string): number => {
+    logWarn(message)
+    emit(emitJson, { log: path, reason, message })
+    return 1
+  }
+
+  const rate = opts.rate === undefined ? 1 : readRate(opts.rate)
+  if (rate === undefined) {
+    return refuseCamera(
+      'bad-rate',
+      `--rate ${opts.rate} is not a positive number, such as 1.5 or 2.`,
+    )
+  }
+
+  let source: string
+  try {
+    source = readFileSync(path, 'utf8')
+  } catch (error) {
+    return refuseCamera(
+      'no-log-file',
+      `No log file at ${path}. ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+  const read = readTakeLog(source)
+  if (read.kind === 'refused') {
+    return refuseCamera(
+      'unreadable-log',
+      `${path} is not a take's log.json, being the file beside a beat's clip.mp4. ${read.detail}`,
+    )
+  }
+
+  const track = cameraTrack(read.log, { rate })
+  const line = `${JSON.stringify(track)}\n`
+  if (!opts.out) {
+    process.stdout.write(line)
+    return 0
+  }
+  const out = resolve(opts.out)
+  writeFileSync(out, line)
+  logInfo(`${out}  ${plural(track.frames.length, 'frame')}  rate ${rate}`)
+  emit(emitJson, { log: path, out, frames: track.frames.length, rate })
+  return 0
+}
+
 async function runTake(
   url: string,
   planPath: string,
-  opts: RunOptions,
+  opts: RunOptions & { readonly out: string },
 ): Promise<number> {
   const emitJson = opts.json ?? false
   const path = resolve(planPath)
@@ -209,6 +350,11 @@ async function runTake(
     logStep('Refused')
     logWarn(TAKE_REFUSALS[result.reason])
     if (result.beat) logWarn(`in beat ${result.beat}`)
+    if (result.fallback) {
+      logWarn(
+        `after falling back to a screencast, which opened the address again: ${result.fallback}`,
+      )
+    }
     if (result.reason === 'server-unreachable') {
       logWarn(`Start whatever serves ${url}, then run this again.`)
     }
@@ -224,6 +370,8 @@ async function runTake(
       reason: result.reason,
       message: result.message,
       ...(result.beat ? { beat: result.beat } : {}),
+      ...(result.fallback ? { fallback: result.fallback } : {}),
+      ...(result.still ? { still: result.still } : {}),
       ...(result.reason === 'browser-missing'
         ? { install: INSTALL_BROWSER }
         : {}),

package/src/design/favicon.ts

@@ -1,37 +1,109 @@
-export interface FaviconColors {
+export interface ThemePair {
   readonly light: string
   readonly dark: string
 }
 
-/** The favicon's own fills, chosen for tab size and apart from the page accent tokens. */
+export interface FaviconColors {
+  /** The tile the mark sits on, dark wherever no theme applies. */
+  readonly tile: ThemePair
+  /** The tile's edge, drawn on light alone. */
+  readonly edge: string
+  /** The c, in the text ink of each theme. */
+  readonly c: ThemePair
+  /** The pip, in the brand pair rather than the page accent. */
+  readonly pip: ThemePair
+}
+
+/** The mark's own colors, picked on the board and kept apart from the page accent tokens. */
 export const FAVICON_COLORS: FaviconColors = {
-  light: '#c42938',
-  dark: '#e54e40',
+  tile: { light: '#fbfaf8', dark: '#1b1a18' },
+  edge: '#dcdad6',
+  c: { light: '#2c2c29', dark: '#d9d7d4' },
+  pip: { light: '#c2380e', dark: '#ff6b42' },
 }
 
-/**
- * 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
+/** The mark spans 96 of a 132 tile, with the tile's corner at 28% of its side. */
+const MARK_IN_TILE = 96 / 132
+const TILE_RADIUS = 0.28
+/** About one pixel at a 32 pixel tab icon, drawn inside the tile's bounds. */
+const EDGE_WIDTH = 4
+
+/** The source's shapes, with its authoring comment and `currentColor` fills dropped. */
+function markShapes(mark: string): string {
+  return 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">
+function markView(mark: string): [number, number, number, number] {
+  const view = /viewBox="([^"]+)"/
+    .exec(mark)?.[1]
+    .trim()
+    .split(/[\s,]+/)
+  const numbers = view?.map(Number) ?? []
+  if (numbers.length !== 4 || numbers.some((n) => !Number.isFinite(n))) {
+    throw new Error('the mark carries no viewBox of four numbers')
+  }
+  return numbers as [number, number, number, number]
+}
+
+const round = (n: number): number => Math.round(n * 100) / 100
+
+/**
+ * The mark on its tile. The base rules draw the dark set, which a renderer
+ * ignoring the media query shows, and a light preference swaps in the light
+ * set. A browser reports light when no scheme is set, so a tab there shows the
+ * light tile. Every fill is a rule rather than an attribute so the light branch
+ * can flip them all.
+ */
+export function renderFavicon(mark: string, colors: FaviconColors): string {
+  const [x, y, width, height] = markView(mark)
+  const side = Math.max(width, height) / MARK_IN_TILE
+  const left = round(x + width / 2 - side / 2)
+  const top = round(y + height / 2 - side / 2)
+  const inset = EDGE_WIDTH / 2
+  const shapes = markShapes(mark)
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${left} ${top} ${round(side)} ${round(side)}">
   <style>
-    path, rect { fill: ${colors.light}; }
-    @media (prefers-color-scheme: dark) { path, rect { fill: ${colors.dark}; } }
+    .tile { fill: ${colors.tile.dark}; stroke: ${colors.tile.dark}; }
+    .c { fill: ${colors.c.dark}; }
+    .pip { fill: ${colors.pip.dark}; }
+    @media (prefers-color-scheme: light) {
+      .tile { fill: ${colors.tile.light}; stroke: ${colors.edge}; }
+      .c { fill: ${colors.c.light}; }
+      .pip { fill: ${colors.pip.light}; }
+    }
   </style>
+  <rect class="tile" x="${round(left + inset)}" y="${round(top + inset)}" width="${round(side - EDGE_WIDTH)}" height="${round(side - EDGE_WIDTH)}" rx="${round(side * TILE_RADIUS - inset)}" stroke-width="${EDGE_WIDTH}" />
+  <g class="c">
   ${shapes.replace(/\n\s*/g, '\n  ')}
+  </g>
 </svg>
 `
 }
 
+/**
+ * The bare mark in fixed fills, for a surface that loads it as an image and
+ * so has neither a CSS context for `currentColor` nor a theme of its own.
+ */
+export function renderMark(
+  mark: string,
+  fills: { readonly c: string; readonly pip: string },
+): string {
+  const svg = mark.replace(/<!--[\s\S]*?-->/, '').trim()
+  const pipFill = /(<[a-z]+ [^>]*class="pip"[^>]*?) fill="[^"]*"/
+  if (!pipFill.test(svg)) {
+    throw new Error('the mark carries no filled .pip shape')
+  }
+  const pip = svg.replace(pipFill, `$1 fill="${fills.pip}"`)
+  return `${pip.replaceAll('currentColor', fills.c)}\n`
+}
+
 /**
  * The `<link rel="icon">` a page carries the rendered favicon in, inlined so a
  * generated page needs no sibling file and no href that varies with its depth.

package/src/design/reference.ts

@@ -0,0 +1,98 @@
+/**
+ * The pure half of `scripts/core/design-sync.ts`, ported from Frameboard's
+ * own sync. Frameboard frames load a shared kit, while this board's frames
+ * load their project's `../assets/`, so each project's assets land under
+ * `kit/<project>/assets/` in `canon/design/`, mirroring the board, and no two
+ * projects can overwrite one another's files of the same name.
+ */
+
+/** A `frames.json` entry the sync cannot capture, named so the file can be fixed. */
+export class MappingError extends Error {}
+
+const REFERENCE = /^[a-z0-9]+(-[a-z0-9]+)*\/[a-z0-9]+(-[a-z0-9]+)*$/
+const BOARD_REF = /^[^/\s]+\/[^/\s]+\/[^/\s]+$/
+// A link starts at a quote or `url(`, so `../../assets/` is left alone, and a
+// file name stops at `#` or `?`, which address a part of the file.
+const BOARD_LINK = /(["'(]\s*)\.\.\/assets\//g
+const BOARD_ASSET = /["'(]\s*\.\.\/assets\/([^"'()\s#?]+)/g
+
+/**
+ * Reads `frames.json`, mapping each reference, `<group>/<name>`, to the
+ * board frame `<project>/<page>/<frame>` it is captured from. An entry in
+ * any other shape throws rather than filing into the wrong folder.
+ */
+export function parseFrameMap(json: string): Map<string, string> {
+  const parsed: unknown = JSON.parse(json)
+  const frames =
+    typeof parsed === 'object' && parsed !== null && 'frames' in parsed
+      ? parsed.frames
+      : undefined
+  if (typeof frames !== 'object' || frames === null) {
+    throw new MappingError('frames.json needs a frames object.')
+  }
+  const map = new Map<string, string>()
+  for (const [reference, ref] of Object.entries(frames)) {
+    if (!REFERENCE.test(reference)) {
+      throw new MappingError(
+        `frames.json entry "${reference}" needs a kebab-case <group>/<name>.`,
+      )
+    }
+    if (typeof ref !== 'string' || !BOARD_REF.test(ref)) {
+      throw new MappingError(
+        `frames.json entry "${reference}" needs a board frame as <project>/<page>/<frame>.`,
+      )
+    }
+    map.set(reference, ref)
+  }
+  return map
+}
+
+/** The mapped board frames the board does not hold. */
+export function missingFrames(
+  map: ReadonlyMap<string, string>,
+  board: ReadonlySet<string>,
+): string[] {
+  return [...map.values()].filter((ref) => !board.has(ref))
+}
+
+/**
+ * What the folder holds of a board frame: its project asset links moved to
+ * the project's kit, every other link left as the frame wrote it. The HTML
+ * is not reformatted, since the formatter ignores the folder and the sync is
+ * its one writer.
+ */
+export function toReference(html: string, project: string): string {
+  return html.replaceAll(BOARD_LINK, `$1../kit/${project}/assets/`)
+}
+
+/** The project assets a frame loads, by their path under `assets/`, each once. */
+export function boardAssets(html: string): string[] {
+  return [...new Set([...html.matchAll(BOARD_ASSET)].map((match) => match[1]))]
+}
+
+export interface Drift {
+  readonly changed: readonly string[]
+  /** PNGs whose bytes differ, a warning since a PNG varies with the browser build. */
+  readonly pngDiffers: readonly string[]
+  readonly missing: readonly string[]
+  readonly stray: readonly string[]
+}
+
+/** Compares what a sync would write against the files the folder holds, the HTML as the source and a PNG as derived. */
+export function classifyDrift(
+  expected: ReadonlyMap<string, string | Uint8Array>,
+  tracked: ReadonlyMap<string, string | Uint8Array>,
+): Drift {
+  const changed: string[] = []
+  const pngDiffers: string[] = []
+  const missing: string[] = []
+  for (const [path, data] of expected) {
+    const copy = tracked.get(path)
+    if (copy === undefined) missing.push(path)
+    else if (!Buffer.from(copy).equals(Buffer.from(data))) {
+      ;(path.endsWith('.png') ? pngDiffers : changed).push(path)
+    }
+  }
+  const stray = [...tracked.keys()].filter((path) => !expected.has(path))
+  return { changed, pngDiffers, missing, stray }
+}

package/src/design/render.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 import type { Cell, DesignDoc, Row } from '@/design/parse'
 import { parseDesignDoc } from '@/design/parse'
 import { fontFaceBlock } from '@/design/css'
+import { faviconLink } from '@/design/favicon'
 import type { FontFace } from '@/design/fonts'
 import { FONT_FACES } from '@/design/fonts'
 import { colorValue } from '@/design/tokens'
@@ -12,16 +13,6 @@ export interface RenderResult {
   cssPath: string
 }
 
-/**
- * The same path data as `assets/brand/mark.svg`, colored via `colorValue`
- * since a data URI has no CSS context to resolve `currentColor` against and
- * this page renders on the light chrome `previewChrome()` sets up.
- */
-const FAVICON_COLOR = colorValue('light-accent') ?? '#a4471c'
-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
@@ -29,6 +20,11 @@ export interface RenderOptions {
    * base64 block a target's render would otherwise grow by unasked.
    */
   readonly embedFonts?: boolean
+  /**
+   * A rendered favicon SVG to inline in the head. The caller reads and renders
+   * the mark, so this module reads no brand file a target does not carry.
+   */
+  readonly favicon?: string
 }
 
 export function renderDesignDoc(
@@ -42,7 +38,10 @@ export function renderDesignDoc(
   const htmlPath = join(outDir, 'index.html')
   const faces = options.embedFonts ? namedFaces(doc) : []
   writeFileSync(cssPath, buildCss(doc, faces))
-  writeFileSync(htmlPath, buildHtml(doc, bodyFamily(doc, faces)))
+  writeFileSync(
+    htmlPath,
+    buildHtml(doc, bodyFamily(doc, faces), options.favicon),
+  )
   return { htmlPath, cssPath }
 }
 
@@ -218,7 +217,11 @@ function previewChrome(): string {
   return ['  :root {', ...lines, '  }'].join('\n')
 }
 
-function buildHtml(doc: DesignDoc, bodyStack: string): string {
+function buildHtml(
+  doc: DesignDoc,
+  bodyStack: string,
+  favicon: string | undefined,
+): string {
   const sections = [
     sectionPersonality(doc.personality),
     sectionColor(doc.color),
@@ -239,8 +242,7 @@ function buildHtml(doc: DesignDoc, bodyStack: string): string {
   return `<!doctype html>
 <html lang="en">
 <head>
-<meta charset="utf-8">
-<link rel="icon" href="${FAVICON_HREF}">
+<meta charset="utf-8">${favicon === undefined ? '' : `\n${faviconLink(favicon)}`}
 <title>Design tokens</title>
 <link rel="stylesheet" href="design.css">
 <style>

package/src/design/tokens.ts

@@ -100,7 +100,7 @@ export const REVIEWED = '2026-10-24'
 
 export const TOKENS: DesignTokens = {
   personality:
-    'Warm neutrals under one rust accent, set in Geist. The page reads as prose, and monospace appears only where a surface shows what a shell printed. One accent carries every count, link, and primary action.',
+    'Warm neutrals with actions in ink, set in Geist. The page reads as prose, and monospace appears only where a surface shows a path, a command, or what a shell printed. The rust accent marks a status the surface it shows would color, and the landing page carries none, leaving the vermilion pip of the mark as its one hue.',
 
   colorRules: [
     'One accent. Never promote a second color into a structural role.',
@@ -155,7 +155,7 @@ export const TOKENS: DesignTokens = {
     },
     {
       role: 'accent',
-      intent: 'install command, mark, primary action',
+      intent: 'a status the surface would color, such as an open pull request',
       value: '#c76b5f',
       grounds: DARK_GROUNDS,
     },
@@ -208,7 +208,7 @@ export const TOKENS: DesignTokens = {
     },
     {
       role: 'light-accent',
-      intent: 'links and primary action on light',
+      intent: 'a status the surface would color, on light',
       value: '#ad4a4b',
       grounds: LIGHT_GROUNDS,
     },
@@ -361,6 +361,7 @@ export const TOKENS: DesignTokens = {
 
   iconography: [
     'No icon library. `assets/brand/mark.svg` is the one authored icon.',
+    'The mark takes its own colors from `src/design/favicon.ts`, never the accent: the c in the text ink and the pip in a vermilion pair.',
     'The terminal draws glyphs: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯`.',
   ],
 }

package/src/gate/stages.ts

@@ -248,6 +248,12 @@ export const STAGES: readonly Stage[] = [
         failure:
           'The tab icon drifted from the token source. Run bun run check and commit web/public/favicon.svg.',
       },
+      {
+        kind: 'drift',
+        pathspec: 'assets/brand/mark-color*.svg',
+        failure:
+          'The README mark pair drifted from the mark source. Run bun run check and commit assets/brand/mark-color.svg and assets/brand/mark-color-light.svg.',
+      },
       { kind: 'measure', measure: designProse },
     ],
     success: 'Design source clean',

package/src/init/steps.ts

@@ -7,8 +7,8 @@ import { GATED_CONFIG_REL, gateScopeRoots } from '@/markdown/gated'
 export type RunFactory = (args: readonly string[]) => () => Promise<boolean>
 
 /**
- * States the same fact as `docs/target/migrations.md`'s backup section in its
- * own words. Keep the two in step by hand; nothing compares them.
+ * States the same fact as `docs/migrations/by-hand.md`'s backup section
+ * in its own words. Keep the two in step by hand; nothing compares them.
  */
 const RECORDS_SETUP_NOTICE =
   "No private repository to push to yet. Run 'canon records push' once one exists to print the one-time setup command, or --skip records to silence this."

package/src/migrate/status.ts

@@ -8,9 +8,9 @@ interface Migration {
 
 /**
  * Every `canon migrate` subcommand in the order a project runs them, records
- * first. This is the source for that order, and `docs/target/migrations.md`
- * cites the verb rather than keeping a second list. A new migration joins by
- * one line here.
+ * first. This is the source for that order, and
+ * `docs/migrations/by-verb.md` cites the verb rather than keeping a
+ * second list. A new migration joins by one line here.
  */
 export const MIGRATIONS: readonly Migration[] = [
   { name: 'records', flags: [] },

package/src/records/validate.ts

@@ -807,6 +807,13 @@ const STRUCTURE_FILES: Readonly<
   intake: (file) => file !== INTAKE_INDEX && file !== INTAKE_HANDOFF,
 }
 
+/**
+ * An app drive's log, which sits under an intake folder's `evidence/` and
+ * holds findings as headings and fields rather than items, so it reads on the
+ * plain criteria rather than the cluster exemptions.
+ */
+const DRIVE_LOG = 'evidence/drive-log.md'
+
 async function folderStructure(
   dir: string,
   kind: RecordKind,
@@ -817,9 +824,14 @@ async function folderStructure(
 
   const report = kind === 'intake' ? intakeStructure : structureFindings
   const files = (await listMarkdown(dir)).filter(reads)
+  const reports = files.map((file) => ({ file, read: report }))
+  if (kind === 'intake' && existsSync(join(dir, DRIVE_LOG))) {
+    reports.push({ file: DRIVE_LOG, read: structureFindings })
+  }
+
   const perFile = await Promise.all(
-    files.map(async (file) =>
-      report(await readFile(join(dir, file), 'utf8')).map((entry) => ({
+    reports.map(async ({ file, read }) =>
+      read(await readFile(join(dir, file), 'utf8')).map((entry) => ({
         ...entry,
         record: slug,
         subject: file,