@erclx/canon 5.23.0 → 5.25.0

package/src/design/budget.ts

@@ -0,0 +1,149 @@
+/**
+ * The prose budget `standards/design.md` sets for a design record, and the
+ * counter the `design` gate stage reads it through.
+ *
+ * The limits live here and in the standard, never in the stage, so the stage
+ * names a failure without restating what it measured against.
+ *
+ * A row is excluded on the same test `table()` in `@/design/parse` reads one
+ * by, a line opening with a pipe, so a code span carrying a pipe or a cell
+ * carrying the uncertainty tag never reaches the count. A line opening with
+ * `<` is dropped the way `prose()` drops it, and so is a fenced block or an
+ * HTML comment spanning several lines, which `prose()` would read in part. A
+ * `###` subsection counts toward the `##` section holding it, since the
+ * standard fixes the sections and a subheading is no way past the cap.
+ */
+export const DESIGN_BUDGET = {
+  /** Words before the first `##` section, the title excluded. */
+  leadWords: 40,
+  /** Words in `## Personality`, held to one paragraph. */
+  personalityWords: 60,
+  personalityParagraphs: 1,
+  /** Bullets or paragraphs in any other section, beside its table. */
+  rules: 3,
+  /** Words in one of those rules, the proxy for one line. */
+  ruleWords: 25,
+} as const
+
+const PERSONALITY = 'Personality'
+
+/** A list item at any depth, which starts a rule of its own. */
+const BULLET = /^\s*(?:[-*+]|\d+[.)])\s+/
+
+interface Section {
+  readonly heading: string | undefined
+  readonly lines: readonly string[]
+}
+
+/**
+ * Every place the record exceeds the budget, one sentence each, in document
+ * order. An empty list is a record within budget, including an empty one.
+ */
+export function measureDesignProse(source: string): string[] {
+  const findings: string[] = []
+
+  for (const section of splitSections(source)) {
+    const rules = readRules(section.lines)
+    const total = rules.reduce((sum, rule) => sum + rule, 0)
+
+    if (section.heading === undefined) {
+      if (total > DESIGN_BUDGET.leadWords) {
+        findings.push(
+          `The lead holds ${total} words against a cap of ${DESIGN_BUDGET.leadWords}`,
+        )
+      }
+    } else if (section.heading === PERSONALITY) {
+      if (rules.length > DESIGN_BUDGET.personalityParagraphs) {
+        findings.push(
+          `${PERSONALITY} holds ${rules.length} paragraphs against a cap of ${DESIGN_BUDGET.personalityParagraphs}`,
+        )
+      }
+      if (total > DESIGN_BUDGET.personalityWords) {
+        findings.push(
+          `${PERSONALITY} holds ${total} words against a cap of ${DESIGN_BUDGET.personalityWords}`,
+        )
+      }
+    } else {
+      if (rules.length > DESIGN_BUDGET.rules) {
+        findings.push(
+          `${section.heading} holds ${rules.length} rules against a cap of ${DESIGN_BUDGET.rules}`,
+        )
+      }
+      rules.forEach((words, index) => {
+        if (words > DESIGN_BUDGET.ruleWords) {
+          findings.push(
+            `${section.heading} rule ${index + 1} holds ${words} words against a cap of ${DESIGN_BUDGET.ruleWords}`,
+          )
+        }
+      })
+    }
+  }
+
+  return findings
+}
+
+/** The lead under an undefined heading, then each `##` section in order. */
+function splitSections(source: string): Section[] {
+  const sections: { heading: string | undefined; lines: string[] }[] = [
+    { heading: undefined, lines: [] },
+  ]
+  for (const line of source.split('\n')) {
+    const match = line.match(/^##\s+(.+?)\s*$/)
+    if (match) {
+      sections.push({ heading: match[1], lines: [] })
+    } else if (!/^#\s/.test(line)) {
+      sections[sections.length - 1].lines.push(line)
+    }
+  }
+  return sections
+}
+
+/**
+ * The word count of each rule in a section. A rule opens on a bullet or on
+ * the first prose line after a break, and every following prose line joins it
+ * until a blank line, a table row, a heading, or the next bullet.
+ */
+function readRules(lines: readonly string[]): number[] {
+  const rules: number[] = []
+  let isOpen = false
+  let isFenced = false
+  let isCommented = false
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (isCommented) {
+      isCommented = !trimmed.includes('-->')
+      continue
+    }
+    if (trimmed.startsWith('<!--')) {
+      isCommented = !trimmed.includes('-->', 4)
+      isOpen = false
+      continue
+    }
+    if (trimmed.startsWith('```')) {
+      isFenced = !isFenced
+      isOpen = false
+      continue
+    }
+    if (
+      isFenced ||
+      trimmed === '' ||
+      trimmed.startsWith('|') ||
+      trimmed.startsWith('#') ||
+      trimmed.startsWith('<')
+    ) {
+      isOpen = false
+      continue
+    }
+    const text = trimmed.replace(BULLET, '')
+    const count = text.split(/\s+/).filter(Boolean).length
+    if (BULLET.test(line) || !isOpen) {
+      rules.push(count)
+      isOpen = true
+    } else {
+      rules[rules.length - 1] += count
+    }
+  }
+
+  return rules
+}

package/src/design/document.ts

@@ -88,6 +88,20 @@ function borderRows(tokens: readonly BorderToken[]): string[][] {
   })
 }
 
+/**
+ * The lead a reader meets before the first section. It points at the module
+ * and at the context entry, since the record carries values and one-line rules
+ * and every reason behind them lives in the entry.
+ */
+const LEAD = [
+  'Authoring guidance: `standards/design.md`. Rendered from `src/design/tokens.ts` by `canon design regen`, so edit the module and never this file.',
+  'Why each value was chosen lives in `canon/context/design/tokens.md`.',
+].join(' ')
+
+function bullets(rules: readonly string[]): string {
+  return rules.map((rule) => `- ${rule}`).join('\n')
+}
+
 function section(heading: string, ...blocks: string[]): string {
   return [`## ${heading}`, ...blocks.filter((block) => block !== '')].join(
     '\n\n',
@@ -98,21 +112,19 @@ export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
   const body = [
     '# Design',
     '',
-    'Authoring guidance: `standards/design.md`.',
-    '',
-    tokens.preamble,
+    LEAD,
     '',
     section('Personality', tokens.personality),
     '',
     section(
       'Color',
-      tokens.colorNote,
+      bullets(tokens.colorRules),
       formatTable(['Role', 'Intent', 'Value'], colorRows(tokens.color)),
     ),
     '',
     section(
       'Typography',
-      tokens.typographyNote,
+      bullets(tokens.typographyRules),
       formatTable(
         ['Role', 'Family', 'Weight', 'Size', 'Line height'],
         typeRows(tokens.typography),
@@ -121,24 +133,24 @@ export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
     '',
     section(
       'Spacing',
-      tokens.spacingNote,
+      bullets(tokens.spacingRules),
       formatTable(['Step', 'Multiplier', 'Value'], spaceRows(tokens.spacing)),
     ),
     '',
     section(
       'Borders',
-      tokens.bordersNote,
+      bullets(tokens.bordersRules),
       formatTable(
         ['Role', 'Radius', 'Width', 'When used'],
         borderRows(tokens.borders),
       ),
     ),
     '',
-    section('Layout', tokens.layout),
+    section('Layout', bullets(tokens.layout)),
     '',
-    section('Motion', tokens.motion),
+    section('Motion', bullets(tokens.motion)),
     '',
-    section('Iconography', tokens.iconography),
+    section('Iconography', bullets(tokens.iconography)),
   ]
 
   return `${body.join('\n')}\n`

package/src/design/render.ts

@@ -328,7 +328,17 @@ function sectionBorders(rows: Row[]): string {
   return `<h2>Borders</h2>\n<table><thead><tr><th>Role</th><th>Radius</th><th>Width</th><th>When used</th><th>Sample</th></tr></thead><tbody>${body}</tbody></table>`
 }
 
+/** A section the record writes as one-line rules draws them as a list. */
+const BULLET = /^[-*+]\s+/
+
 function sectionLine(title: string, text: string): string {
   if (!text) return ''
-  return `<h2>${title}</h2>\n<p>${escape(text)}</p>`
+  const lines = text.split('\n')
+  if (!lines.every((line) => BULLET.test(line))) {
+    return `<h2>${title}</h2>\n<p>${escape(text)}</p>`
+  }
+  const items = lines
+    .map((line) => `<li>${escape(line.replace(BULLET, ''))}</li>`)
+    .join('')
+  return `<h2>${title}</h2>\n<ul>${items}</ul>`
 }

package/src/design/tokens.ts

@@ -59,21 +59,25 @@ export interface BorderToken {
   readonly verify?: readonly ('radius' | 'width')[]
 }
 
+/**
+ * Every prose slot is a list of one-line rules rather than a string, so a
+ * bullet is the unit the renderer emits and the prose budget counts, and a
+ * value needing a paragraph of why goes to `canon/context/design/tokens.md`.
+ */
 export interface DesignTokens {
   readonly personality: string
   readonly color: readonly ColorToken[]
-  readonly colorNote: string
+  readonly colorRules: readonly string[]
   readonly typeScale: readonly TypeStep[]
   readonly typography: readonly TypeToken[]
-  readonly typographyNote: string
+  readonly typographyRules: readonly string[]
   readonly spacing: readonly SpaceToken[]
-  readonly spacingNote: string
+  readonly spacingRules: readonly string[]
   readonly borders: readonly BorderToken[]
-  readonly bordersNote: string
-  readonly layout: string
-  readonly motion: string
-  readonly iconography: string
-  readonly preamble: string
+  readonly bordersRules: readonly string[]
+  readonly layout: readonly string[]
+  readonly motion: readonly string[]
+  readonly iconography: readonly string[]
 }
 
 /** The monospace stack, taken by code and by the terminal frames a page embeds. */
@@ -94,35 +98,14 @@ const DARK_GROUNDS = ['background', 'surface'] as const
 const LIGHT_GROUNDS = ['light-background', 'light-surface'] as const
 
 export const TOKENS: DesignTokens = {
-  preamble: [
-    'This document is rendered from `src/design/tokens.ts` by `canon design regen`, and the `design` stage of `bun run check` fails when the two disagree. Edit the module, never this file.',
-    '',
-    'The values below are the system rather than a reading of one. Until 2026-09-01 this record transcribed two surfaces and agreed with nothing else, which is what made a change to it reach nobody. The slide theme, the token preview, and a teach workspace stylesheet now read the module this file is rendered from, so a value changed there changes what all three render.',
-    '',
-    'The two rendered captures read it as well. `scripts/core/regen-hero.ts` fills `assets/captures/hero.html.tmpl` and `assets/captures/install.html.tmpl` with what `canon design css --no-components` emits, so both frames now carry the custom properties rather than their own copies of the hex, and a value moved here moves what the next capture renders.',
-    '',
-    'The terminal framing is the one surface left holding its own values, and that is a decision rather than a gap. `scripts/lib/ui.sh` and `src/ui.ts` each spell six escape constants, and `canon/context/scripts/framing.md` records one color source per language with a check behind each, so generating a third spelling from here would break the rule those two checks enforce. What the record is still incomplete about is the other half of those six: `WHITE` and `GREY` name no role below, so the terminal palette is described here in part rather than in whole.',
-  ].join('\n'),
-
-  personality: [
-    'Warm neutrals carry the frame under a single rust accent, set in Geist. The subject is a toolkit for people who read documents and diffs as much as they run commands, so the voice is a proportional one and the page reads as prose. One accent carries every count, link, and primary action. Promoting a second and third into structural roles is what reads as a generated interface, so the palette stays at one.',
-    '',
-    'Monospace is a role the page uses rather than its voice. The `code` role takes it, and so does any terminal frame a surface embeds, since those show what the shell printed and matching the shell is what makes them legible. Every other role is Geist.',
-  ].join('\n'),
+  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.',
 
-  colorNote: [
-    'Every role clears WCAG AA at 4.5:1 against each ground it declares, asserted in `src/design/contrast.test.ts`.',
-    '',
-    'Warning and error hold ANSI codes because that is what `scripts/lib/ui.sh` writes and no rendered surface implements an equivalent. Giving either a hex value would invent a mapping no file has, so they carry no contrast reading either.',
-    '',
-    'Success is the one of the three that does have a rendered equivalent, which is why it carries a hex. `assets/captures/install.html` marks every confirmed step with it, and the shell writes `ANSI 32` for the same role, so the two are one role in two registers rather than one value in two spellings. The hex is what the rendered surface picked and no reading claims the terminal renders that value. It declares `background` alone as its ground, since that is the only role it is drawn on, where every other dark text role is drawn on both. It is the one role below that is not derived.',
-    '',
-    "Every other role is derived rather than picked, solved in OKLCH by binary search for the lightness that hits a target contrast against its ground, using this module's own anchors. Six anchors are the whole system: ground lightness 0.985 light and 0.165 dark, neutral chroma 0.003 light and 0.004 dark, neutral hue 90 both, accent hue 22 light and 28 dark, accent chroma 0.13 light and 0.12 dark for a mark and 0.095 light and 0.09 dark for a fill. Only the mark step is rendered below, in `accent`. That token already stands in for a fill in practice: `assets/captures/hero.html`'s `.cmd` rule paints its whole background with `var(--color-accent)` and sets text on top, which is a fill use rather than a mark one. The fill chroma step has no token of its own yet, so a lower-saturation `accent-fill` would recolor that button rather than introduce a new consumer. Targets, which are inputs rather than results: text 13.5, body 8.6, secondary 5.6, muted 4.6, accent 5.2. Dark is its own anchor set rather than an inversion of light, and every arm measured in the groundwork behind this landed on identical neutral ratios, which is what made the accent choice a question about hue alone.",
-    '',
-    '`muted` and `light-muted` solve against `surface` rather than `background`. Both declare two grounds and the groundwork solved its target against one, so the recorded hex cleared 4.6 against `background` and read 4.40 dark, 4.24 light against `surface`, the tighter of the two since surface sits a step closer to its text color. The values here are re-solved for the same 4.6 target read against `surface` instead, which clears both: 4.58 dark, 4.56 light against `surface`, and 4.80 dark, 4.95 light against `background`.',
-    '',
-    'The accent is a quiet red at hue 22 light, 28 dark, chosen over a vivid red that read as an error state against a page reporting success, over indigo which carries less distinctiveness at hue 280 in tooling already dominated by that hue, and over rust at hue 42, a larger temperature shift than the problem required. The debt this accepts: `error` and `warning` now share a register with the most repeated element on every rendered surface, so both need differentiating by lightness or by an icon rather than by hue, and that work is unscheduled.',
-  ].join('\n'),
+  colorRules: [
+    'One accent. Never promote a second color into a structural role.',
+    'Every text role clears WCAG AA at 4.5:1 against each ground it is drawn on.',
+    '`warning` and `error` exist only in the terminal, as ANSI codes.',
+  ],
 
   color: [
     {
@@ -242,15 +225,11 @@ export const TOKENS: DesignTokens = {
     },
   ],
 
-  typographyNote: [
-    'Seven sizes are on offer, named `t0` through `t6` and emitted as custom properties beside the roles. They are 3.175, 2.375, 1.375, 1.125, 0.9375, 0.8125 and 0.6875 rem, which paint at 50.8, 38, 22, 18, 15, 13 and 11 pixels, and each role takes one. A step answers what sizes exist and a role answers what a stylesheet asks for, so the two stay separate: a role whose step did not move renders as it did, and a role that moved is the only thing that changes what a surface paints. Two steps, `t3` at 18 pixels and `t6` at 11, are offered with no role pointing at them yet.',
-    '',
-    'Every role but `code` is Geist and `code` is monospace. The hero headline takes the largest step at 50.8 pixels, which no other role reaches, since a headline set at the display cap reads as an opening rather than as a section heading.',
-    '',
-    'A tagged cell is one no rendering surface exercises yet, which is a declaration the system has not tested rather than one it has.',
-    '',
-    'Two rules set tracking and no others touch it. The label role carries `0.05em`, and the display role tightens to `-0.01em`.',
-  ].join('\n'),
+  typographyRules: [
+    'Geist for every role except `code`, which is monospace.',
+    'Tracking: `label` at `0.05em`, `display` at `-0.01em`, nothing else.',
+    'Sizes come from seven steps, `t0` to `t6`. A role takes one step.',
+  ],
 
   typeScale: [
     { step: 't0', size: '3.175rem' },
@@ -312,11 +291,9 @@ export const TOKENS: DesignTokens = {
     },
   ],
 
-  spacingNote: [
-    'Seven steps run from a quarter rem to six, at 4, 8, 14, 24, 40, 64 and 96 pixels on a 16 pixel root. The scale is not a grid of one base, since the 14 between the 8 and the 24 is the step a control needs and no multiple of four supplies it, so the multiplier column counts quarter rems rather than claiming a unit.',
-    '',
-    'The outer window padding of the capture frames, which the previous record carried as a three-value frame register, is not part of the scale. Those frames set their own padding in the template and read no step, so the register is retired here rather than mapped onto steps no frame uses.',
-  ].join('\n'),
+  spacingRules: [
+    'Seven steps. `md` sits at 3.5 because a control needs 14 pixels.',
+  ],
 
   spacing: [
     { step: 'xs', multiplier: '1', value: '0.25rem' },
@@ -328,9 +305,9 @@ export const TOKENS: DesignTokens = {
     { step: '3xl', multiplier: '24', value: '6rem' },
   ],
 
-  bordersNote: [
-    'Every border is one pixel solid at the `border` role, and that value appears in no text role. Three radii appear, and the two blocks carrying the largest and smallest have no border at all, so radius and width are independent here rather than paired. Nothing renders a pill, so both of its cells stay tagged.',
-  ].join('\n'),
+  bordersRules: [
+    'Every border is one pixel solid in `border`. Radius and width are independent.',
+  ],
 
   borders: [
     {
@@ -372,17 +349,19 @@ export const TOKENS: DesignTokens = {
     },
   ],
 
-  layout:
-    'Capture widths are 320, 768, 1280 and 1536 pixels, declared once in `tooling/web/configs/e2e/screenshot.ts`, with 320 and 1280 committed as evidence. 320 is the reflow floor. Every range the width queries in the generated base and teach stylesheets lay out holds at least one of these widths, so a capture photographs every layout state those stylesheets have, and a design test fails when a query moves or is added so that it opens a range none of them reaches. The landing page under `web/` sets its own `max-width` media queries between 430 and 1100 pixels per component rather than from a shared scale.',
+  layout: [
+    'Capture widths: 320, 768, 1280, 1536. 320 is the reflow floor.',
+    'Every width query in the generated stylesheets opens a range one of these widths reaches.',
+  ],
 
-  motion:
-    'Motion is not used. No transition, animation, or keyframe declaration appears on any rendered surface, and the capture pipeline screenshots a static frame.',
+  motion: [
+    'None. No transition, animation, or keyframe on any rendered surface.',
+  ],
 
   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 in five 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`, which teach pages also take by rendering the live mark. Unifying them or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design/tokens.md` carries which file holds each copy.',
-  ].join('\n'),
+    'No icon library. `assets/brand/mark.svg` is the one authored icon.',
+    'The terminal draws glyphs: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯`.',
+  ],
 }
 
 /** A role's value, or `undefined` where the record declares no such role. */

package/src/gate/measures.ts

@@ -22,6 +22,8 @@ import {
   PRACTICE_SKILLS,
   SHIPPED_CORPUS,
 } from '@/claude/skills-audit'
+import { measureDesignProse } from '@/design/budget'
+import { DESIGN_DOCUMENT } from '@/design/regen'
 import { listRepositoryFiles } from '@/git-files'
 import { ceilingFindings } from '@/markdown/ceiling'
 import { resolveMarkdown } from '@/markdown/files'
@@ -325,6 +327,53 @@ export const canonicalRecords: Measure = async (ctx) => {
   return { emissions }
 }
 
+/**
+ * The design records this repository holds, each read against the prose
+ * budget in `@/design/budget`. The worked example is read beside the record,
+ * since it is the one a target copies its shape from.
+ */
+const DESIGN_RECORDS = [
+  DESIGN_DOCUMENT,
+  join('examples', 'design', 'DESIGN.md'),
+] as const
+
+export const designProse: Measure = async (ctx) => {
+  const failures: string[] = []
+  const emissions: Emission[] = []
+
+  for (const rel of DESIGN_RECORDS) {
+    const path = join(ctx.root, rel)
+    if (!existsSync(path)) continue
+    let source: string
+    try {
+      source = readFileSync(path, 'utf8')
+    } catch {
+      return {
+        emissions: [],
+        unmeasured: `${rel} could not be read, so its prose was not counted.`,
+      }
+    }
+    const findings = measureDesignProse(source)
+    if (findings.length > 0) {
+      failures.push(
+        `${findings.map((finding) => `${finding} in ${rel}`).join('. ')}.`,
+      )
+    } else {
+      emissions.push(info(`${rel} within the prose budget`))
+    }
+  }
+
+  if (failures.length > 0) {
+    return {
+      emissions: [],
+      failure: `${failures.join(' ')} Cut to the budget in standards/design.md, moving the why to the context entry.`,
+    }
+  }
+  if (emissions.length === 0)
+    emissions.push(info('No design record to measure'))
+  return { emissions }
+}
+
 /**
  * Every skill body and reference against the no-dated-provenance rule, across
  * both corpora `auditSkills` reads.

package/src/gate/stages.ts

@@ -10,6 +10,7 @@ import {
   auditSet,
   captureStamps,
   clientCommandCitations,
+  designProse,
   documentCeiling,
   folderEchoedNames,
   markdownBans,
@@ -234,7 +235,9 @@ export const STAGES: readonly Stage[] = [
     // from `src/design/tokens.ts`, the base stylesheet from
     // `src/design/neutral.ts`, and none is edited by hand. Four artifacts
     // from two token sources is the cost of the token move, and a render step that has to run is only safe while something fails
-    // when it did not, which is this.
+    // when it did not, which is this. The record and the worked example are
+    // then counted against the prose budget, which the drift asserts cannot
+    // see since a regenerated paragraph agrees with its source.
     id: 'design',
     label: 'Design',
     checks: [
@@ -277,6 +280,7 @@ 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: 'measure', measure: designProse },
     ],
     success: 'Design source clean',
   },

package/src/help.ts

@@ -36,7 +36,7 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
   {
     title: 'Author and render',
     rows: [
-      ['design [cmd]', 'Design system (render, board)'],
+      ['design [cmd]', 'Design system (render, regen)'],
       ['slides [cmd]', 'Slide decks (render, list)'],
       ['capture [source]', 'Render HTML capture sources to PNG'],
       ['serve [dir]', 'Serve a directory on localhost, print the link'],
@@ -102,7 +102,7 @@ const EXAMPLES = [
   'canon docs list --json',
   'canon docs agents',
   'canon design render',
-  'canon design board',
+  'canon canvas list --json',
   'canon slides render',
   'canon slides list --json',
   'canon capture assets/captures/install.html --selector .window --out assets/evidence',

package/src/migrate/skill-names.ts

@@ -40,6 +40,11 @@ import { defineRenameRules, type RenameRules } from '@/migrate/rename'
  * from where the document lands. Every retired name lands on the one skill, so
  * a target citing any of them resolves after a single sweep.
  *
+ * `draft-diagram` merged into `draft-figure` the same way, its architecture
+ * views becoming one reference the figure skill reads. `claude-diagram` is
+ * retargeted onto `draft-figure` rather than left on the retired name, for the
+ * same reason `claude-ui-test` was.
+ *
  * Every name takes two words. Ten of these would have landed as a bare single
  * word under a plain strip, and a bare word such as `review` or `docs` is a
  * substring of ordinary prose with no token left for a later sweep to find.
@@ -58,7 +63,7 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
   'claude-address-review': 'review-address',
   'claude-autoship': 'auto-ship',
   'claude-design-extract': 'design-extract',
-  'claude-diagram': 'draft-diagram',
+  'claude-diagram': 'draft-figure',
   'claude-docs': 'context-fold',
   'docs-fold': 'context-fold',
   'claude-feature': 'plan-feature',
@@ -91,6 +96,7 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
   'draft-wireframes': 'draft-doc',
   'draft-readme': 'draft-doc',
   'draft-wiki': 'draft-doc',
+  'draft-diagram': 'draft-figure',
 }
 
 /**

package/src/pr/evidence.ts

@@ -1,6 +1,12 @@
 /** The path segment that marks an image as evidence a pull request should compare. */
 const EVIDENCE_SEGMENT = 'evidence'
 
+/** The most images a comment carries and still opens its states, since past it the page is a wall of screenshots. */
+const EVIDENCE_OPEN_LIMIT = 6
+
+/** Length of the commit names the visible line shows, the width `git` abbreviates to. */
+const SHORT_SHA_LENGTH = 7
+
 /** Prefix of the trailing marker this module writes and reads back. */
 const MARKER_PREFIX = '<!-- pr-evidence:'
 
@@ -120,10 +126,14 @@ export function evidenceMarker(head: string): string {
 }
 
 /**
- * Renders the whole comment body: one collapsed `<details>` block per state,
- * a Base/Head row per case, and the trailing marker naming the head this body
- * describes. Every image URL is pinned to a commit sha rather than a branch,
- * so the comment keeps showing what it claimed even after the branch moves.
+ * Renders the whole comment body: one `<details>` block per state, a Base/Head
+ * row per case, and the trailing marker naming the head this body describes.
+ * Every state opens while the comment carries at most `EVIDENCE_OPEN_LIMIT`
+ * images, one per row for the head plus one per row not added, and every state
+ * closes past it, so a comment is never half open. A visible line under
+ * `## Evidence` names the base and head as short shas. Every image URL is
+ * pinned to a commit sha rather than a branch, so the comment keeps showing
+ * what it claimed even after the branch moves.
  *
  * A preview address opens the body, and with no states it is the whole body
  * apart from the marker, so a pull request whose screenshots did not change
@@ -157,6 +167,14 @@ export function renderEvidenceBody(
     return [...opening, ...closing, evidenceMarker(head)].join('\n')
   }
 
+  const imageCount = states.reduce(
+    (total, entry) =>
+      total + entry.items.reduce((sum, item) => sum + (item.added ? 1 : 2), 0),
+    0,
+  )
+  const opener =
+    imageCount <= EVIDENCE_OPEN_LIMIT ? '<details open>' : '<details>'
+
   const sections = states.map((entry) => {
     const rows = entry.items.map((item) => {
       const before = item.added
@@ -167,7 +185,7 @@ export function renderEvidenceBody(
     })
 
     return [
-      '<details>',
+      opener,
       `<summary>${entry.state === '' ? 'evidence' : entry.state} (${entry.items.length})</summary>`,
       '',
       '| Case | Base | Head |',
@@ -182,6 +200,8 @@ export function renderEvidenceBody(
     ...opening,
     '## Evidence',
     '',
+    `**Base:** \`${base.slice(0, SHORT_SHA_LENGTH)}\` · **Head:** \`${head.slice(0, SHORT_SHA_LENGTH)}\``,
+    '',
     ...sections,
     '',
     ...closing,