@erclx/canon 4.43.0 → 4.45.0

package/README.md

@@ -59,19 +59,19 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 
 Those domains split on one line: some are copied into your project and become yours to edit, and some are never copied at all.
 
-![canon tooling list and canon standards list side by side, the first showing five stacks with their dependency and script counts, the second showing standards against the artifact each governs](assets/showcase-install-surface.png)
+![canon tooling list and canon standards list side by side, the first showing five stacks with their dependency and script counts, the second showing standards against the artifact each governs](assets/install-surface.png)
 
 A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A standard stays here and is opened by name, so there is no copy in your repo to drift from this one.
 
 Governance is the third shape, and it is worth seeing rather than reading about, because the glob beside each rule is what decides whether it reaches a session at all.
 
-![canon gov list, showing seven stacks with the rules each carries and a sample of rules beside the path glob that loads each one](assets/showcase-governance.png)
+![canon gov list, showing seven stacks with the rules each carries and a sample of rules beside the path glob that loads each one](assets/governance.png)
 
 Stacks compose, so a react project inherits node and node inherits base. A rule with a glob loads only when a matching path is edited, and a rule with none loads every session. Both counts and every row above are read from the catalogs when the image is built.
 
 The toolkit tracks its own work the same way, in a task board no catalog can read back.
 
-![the task board's Run now table, one row per task in flight, each naming the files it touches and the plan it runs under](assets/showcase-task-board.png)
+![the task board's Run now table, one row per task in flight, each naming the files it touches and the plan it runs under](assets/task-board.png)
 
 `.canon/tasks/` is gitignored session scratch, so unlike the two frames above, this one is a hand-taken snapshot rather than something the build reads live, and it goes stale the moment the board moves.
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.43.0",
+  "version": "4.45.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-docs/SKILL.md

@@ -47,7 +47,7 @@ Read these in parallel from the current worktree root (`pwd`), not the main work
 - `.claude/REQUIREMENTS.md`
 - `.claude/ARCHITECTURE.md`
 - `.claude/DESIGN.md`
-- `.claude/wireframes/index.md` and every `.claude/wireframes/<surface>.md`
+- `.claude/wireframes/index.md` and every surface file it links to, following a grouped surface's own `index.md` and the siblings it lists rather than stopping at the top-level folder
 
 Read the task board from the main worktree root instead, resolving that root the way `claude-worktree` does. It is gitignored scratch and never commits with the branch:
 
@@ -61,7 +61,7 @@ Review the session for decisions that diverged from the original plan:
 
 - Requirements added, removed, or changed scope
 - Architecture or technical decisions made or revised
-- Design or UX decisions that differ from DESIGN.md or any `.claude/wireframes/<surface>.md`
+- Design or UX decisions that differ from DESIGN.md or any wireframe surface file, flat or nested under its own subfolder
 - Tasks blocked or newly identified
 
 Then resolve the diff baseline and match it against the board. From `.canon/tasks/index.md` at the main worktree root, pick the task files whose title or description relates to the changed paths and read the ones Step 1 skipped.
@@ -104,7 +104,7 @@ The verb resolves the board at the main worktree root in-process, which is the r
 
 Read `ok` and `reason` out of that record rather than the exit. An operator's shell profile may wrap `canon` in a function that runs the binary and then a second command and takes the second status, which flattens every non-zero exit to zero. A refusal arriving as success leaves the outcome unmarked while the chain moves on, so the board reports shipped work as open and the next session re-plans it.
 
-**REQUIREMENTS.md, ARCHITECTURE.md, DESIGN.md, `.claude/wireframes/<surface>.md`**
+**REQUIREMENTS.md, ARCHITECTURE.md, DESIGN.md, a wireframe surface file (flat or nested)**
 
 - Update only the sections affected by session decisions.
 - Do not rewrite sections unrelated to what changed.

package/claude/skills/claude-docs/references/wireframe-sweep.md

@@ -9,7 +9,7 @@ Mechanics for Step 4 of `claude-docs`. The body owns the skip conditions and the
 
 ## Deriving a candidate slug
 
-For each UI-affecting path, derive a candidate surface slug from the file's basename and parent folder (e.g. `web/src/features/mock/MockDemoStrip.tsx` → `mock-demo-strip` or `mock`). Cross-reference against the surface files in `.claude/wireframes/`.
+For each UI-affecting path, derive a candidate surface slug from the file's basename and parent folder (e.g. `web/src/features/mock/MockDemoStrip.tsx` → `mock-demo-strip` or `mock`). Cross-reference against every surface file in `.claude/wireframes/`, including one nested inside a grouped surface's own subfolder (`.claude/wireframes/<group>/<surface>.md`), by walking the tree rather than globbing the top level alone.
 
 ## Findings
 
@@ -32,7 +32,7 @@ TODO: describe when and where this surface appears.
 - TODO
 ```
 
-Skip the write when the slug would collide with an existing file (different surface, same slug). Surface the collision in the report instead.
+Skip the write when the slug would collide with an existing file, flat or nested (different surface, same slug). Surface the collision in the report instead.
 
 ## Output
 

package/claude/skills/claude-feature/SKILL.md

@@ -23,7 +23,7 @@ Read these in parallel from the project root, skipping any that do not exist:
 Also read these when the feature touches code or UI. Skip them for prose, docs, catalog, or config-only changes:
 
 - `.claude/DESIGN.md`: tokens, typography, spacing, and component rules
-- `.claude/wireframes/index.md` + the surface files relevant to the feature: intended UI layout and behavior. Read `index.md` first, then load only the per-surface files (`.claude/wireframes/<surface>.md`) the feature actually touches. Do not read the whole folder speculatively.
+- `.claude/wireframes/index.md` + the surface files relevant to the feature: intended UI layout and behavior. Read `index.md` first, then follow only the links the feature actually touches, each a flat `.claude/wireframes/<surface>.md` or a grouped surface's own `.claude/wireframes/<surface>/index.md` and the siblings it lists. Do not read the whole folder speculatively.
 
 When the plan adds or revises a surface, the wireframe file follows `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`.
 

package/docs/agents/capture.md

@@ -5,27 +5,29 @@ description: Rendering HTML sources to PNG, what the command asserts about fonts
 
 # Capture
 
-`canon capture [source] --selector <sel>` renders HTML sources to PNG, which is how a generated documentation image is rebuilt from the markup it was generated out of. The source defaults to `assets/`, where a directory expands to every `.html` directly inside it, so adding a capture means dropping a file beside the first one and running the same command. That default names this repository's own folder rather than a convention every target shares, and it stays because a missing one still refuses loud, naming the argument, rather than failing silently.
+`canon capture [source] --selector <sel>` renders HTML sources to PNG, which is how a generated documentation image is rebuilt from the markup it was generated out of. The source defaults to `assets/`, where a directory expands to every `.html` directly inside it, so adding a capture means dropping a file beside the first one and running the same command. That default is a generic starting point rather than a convention every target shares, and it stays because a missing folder still refuses loud, naming the argument, rather than failing silently. This repository no longer takes it: its own sources moved to `assets/captures/` and its images stayed in `assets/`, so a run here names the source explicitly and sends the output where that run wants it, `--out assets` to rebuild the committed images and somewhere disposable to preview them.
 
 ```bash
 canon capture --selector .window
-canon capture assets/install.html --selector .window
-canon capture assets --selector .window --out .canon/review/captures
+canon capture assets/captures/install.html --selector .window --out assets
+canon capture assets/captures --selector .window --out .canon/review/captures
 ```
 
 `--selector` is required and every example above passes it. The element a capture crops to belongs to the page, not to the command, so there is no value that could be right for an arbitrary project's markup. `.window` is what this repository's own five sources declare, and a project renders its own pages by naming whatever theirs declare.
 
 ## What this repository captures
 
-`assets/` here holds five sources, so one run over the folder rebuilds every one. None is edited by hand. `scripts/core/regen-hero.sh` writes each from a template beside it, filling one shared value map into all of them, and `bun run check` regenerates them and fails on the difference.
+A capture set here spans two folders. `assets/captures/` holds five sources and the template each is written from, and `assets/` holds the five images a document points at with the stamp answering for each. One run over the source folder rebuilds every image, and it takes `--out assets` to put each PNG where its document points rather than beside the markup it rendered. None of the five is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them, and `bun run check` regenerates them and fails on the difference.
 
-Three of the five take catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` and `showcase-task-board.html` are the two exceptions: the first holds terminal text from a real run and the second holds a hand-frozen snapshot of a gitignored board, each in its template rather than derived from a live catalog at build time.
+Three of the five take catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` and `task-board.html` are the two exceptions: the first holds terminal text from a real run and the second holds a hand-frozen snapshot of a gitignored board, each in its template rather than derived from a live catalog at build time.
 
-The folder is read flat and never descends, by the regeneration script, by this command, and by the drift stage alike. A source in a subfolder is skipped by all three with nothing reported, so a new frame takes a name prefix rather than a folder of its own.
+`assets/captures/` is read flat and never descends, by the regeneration script, by this command, and by the drift stage alike. A source nested a further folder down is skipped by all three with nothing reported, so a new frame is a template dropped directly in rather than a folder of its own. The split is what retired the name prefix the flat layout used to need: a frame is named for itself now, since `assets/` no longer mixes markup in with the images.
 
-Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `canon capture assets --selector .window` when the check reports the HTML changed.
+Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `canon capture assets/captures --selector .window --out assets` when the check reports the HTML changed.
 
-Every render writes a stamp beside its PNG, `hero.png` next to `hero.stamp`, holding the source filename, a `source-sha256` over the markup bytes it read, and an `image-sha256` over the image bytes it wrote. Both digests are what `bun run check` compares, so a markup edit committed without a capture and a PNG swapped under unchanged markup each fail. The stamp is tracked and commits alongside the pair. Nothing hand-edits it, and a capture that cannot write it reports that source as failed and exits 1, so an image whose stamp never landed is reported rather than passed over.
+Every render writes a stamp beside its PNG, `hero.png` next to `hero.stamp`, holding the source filename, a `source-sha256` over the markup bytes it read, and an `image-sha256` over the image bytes it wrote. Both digests are what `bun run check` compares, so a markup edit committed without a capture and a PNG swapped under unchanged markup each fail. The stamp is tracked and commits alongside the pair. A capture that cannot write it reports that source as failed and exits 1, so an image whose stamp never landed is reported rather than passed over.
+
+Neither digest is ever written by hand. A digest is what the gate compares, so a hand-set one asserts agreement the tool never checked, and the way to move it is a capture. The `source:` line above them is the one field a rename may correct in place, since nothing reads it and the alternative is a stamp naming a file that no longer exists. Renaming a frame is the case that comes up, and the correction is the same basename the next capture would have written anyway.
 
 | Option             | Behavior                                          |
 | ------------------ | ------------------------------------------------- |

package/package.json

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

package/scripts/core/regen-hero.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
-# Fills every assets/*.html.tmpl from the CLI catalogs and the design source,
-# writing the .html beside each one.
+# Fills every assets/captures/*.html.tmpl from the CLI 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/, .claude/context/, and src/ spells that
@@ -18,10 +18,12 @@
 # Only the HTML regenerates here. The PNG beside it is a chromium render whose
 # bytes move with the browser version, so asserting it in verify.sh would fail
 # on a machine whose chromium differs rather than on a stale count. Rebuild the
-# images with `canon capture assets --selector .window` after this script
-# reports a change. The selector has no default, since the element a capture
-# crops to belongs to the page rather than to the command, and `.window` is the
-# class this repository's own two sources declare.
+# images with `canon capture assets/captures --selector .window --out assets`
+# after this script reports a change. The markup and the image sit in two
+# folders, so that run reads the sources here and sends every PNG and stamp back
+# up to assets/, where the documents point. The selector has no default, since
+# the element a capture crops to belongs to the page rather than to the command,
+# and `.window` is the class this repository's own sources declare.
 # That capture also 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. `package.json` is bumped on main by the release
@@ -36,7 +38,7 @@ set -o pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 
-ASSET_DIR="$PROJECT_ROOT/assets"
+ASSET_DIR="$PROJECT_ROOT/assets/captures"
 LISTED=10
 
 # `bun src/cli.ts` rather than `canon`, since a globally linked binary resolves to

package/src/cli.ts

@@ -120,7 +120,7 @@ function showHelp(): void {
     `${GREY}│${NC}    canon design render`,
     `${GREY}│${NC}    canon slides render`,
     `${GREY}│${NC}    canon slides list --json`,
-    `${GREY}│${NC}    canon capture assets/install.html --selector .window`,
+    `${GREY}│${NC}    canon capture assets/captures/install.html --selector .window --out assets`,
     `${GREY}│${NC}    canon serve .canon/teach`,
     `${GREY}│${NC}    canon inventory focus --json`,
     `${GREY}│${NC}    canon drive http://localhost:4173 run.json --json`,

package/src/commands/migrate.ts

@@ -281,6 +281,20 @@ function reportRecords(plan: RecordsPlan, records: number): void {
     )
     for (const path of plan.coupled) logInfo(`  ${path}`)
   }
+
+  // Named individually rather than counted. A rewritten glob stops matching
+  // silently, which is the failure this boundary exists to surface, so the
+  // report gives the reader the file and line to go and check by hand.
+  if (plan.frontmatterGlobs.length > 0) {
+    logInfo(
+      `${plural(plan.frontmatterGlobs.length, 'file')} carry a frontmatter paths: glob left alone:`,
+    )
+    for (const entry of plan.frontmatterGlobs) {
+      for (const line of entry.lines) {
+        logInfo(`  ${entry.path}:${line.line}  ${excerpt(line.text)}`)
+      }
+    }
+  }
 }
 
 function toRecordsRecord(
@@ -298,6 +312,8 @@ function toRecordsRecord(
     kept: plan.kept,
     excluded: plan.excluded.length,
     coupled: plan.coupled,
+    frontmatterGlobs: plan.frontmatterGlobs,
+    globs: plan.globs,
     records,
     paths: plan.entries.map((entry) => ({
       path: entry.path,
@@ -555,6 +571,10 @@ export function register(program: Command): void {
         'below it, keeps the old root. Prose that dates a decision needs it; a',
         'live path does not.',
         '',
+        'A rule frontmatter paths: glob naming a moved root is reported and left',
+        'alone rather than rewritten, since a rewritten glob stops matching',
+        'silently. No marker is needed; the YAML shape is enough.',
+        '',
         'The records themselves are never swept. Everything under .canon/ and',
         'every .claude/ record folder is left alone and reported as a count, so',
         'a run after the ignore entries collapse touches the same files as one',

package/src/design/tokens.ts

@@ -80,7 +80,7 @@ export const TOKENS: DesignTokens = {
     '',
     '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.sh` fills `assets/hero.html.tmpl` and `assets/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 two rendered captures read it as well. `scripts/core/regen-hero.sh` 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 `.claude/ARCHITECTURE.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'),
@@ -94,7 +94,7 @@ export const TOKENS: DesignTokens = {
     '',
     '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/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.',
+    '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.',
   ].join('\n'),
 
   color: [

package/src/gate/measures.ts

@@ -114,7 +114,7 @@ export const SANDBOX_UNDECLARED_CEILING = 47
 export const AUDITS_BASELINE = '.claude/canon/baseline.json'
 
 export const CAPTURE_STAMP_FAILURE =
-  'A capture set disagrees with the stamp written when its image was captured. Run canon capture assets --selector .window and commit each frame with its image and its stamp.'
+  'A capture set disagrees with the stamp written when its image was captured. Run canon capture assets/captures --selector .window --out assets and commit each frame with its image and its stamp.'
 
 function parseJson(payload: string): unknown {
   try {
@@ -861,19 +861,28 @@ async function collectPluginManifests(ctx: MeasureContext): Promise<string[]> {
   return [...seen].sort()
 }
 
-const CAPTURE_DIR = 'assets'
+/**
+ * A capture set spans two folders. The markup and the template beside it are
+ * the authored half and sit under `assets/captures/`, while the image a
+ * document points at and the stamp answering for it stay in `assets/`, which is
+ * where `--out assets` sends them.
+ */
+const CAPTURE_MARKUP_DIR = 'assets/captures'
+const CAPTURE_OUTPUT_DIR = 'assets'
 
 /**
- * Every capture under `assets/`, named by the base its three files share.
+ * Every capture under `assets/captures/`, named by the base its three files
+ * share.
  *
  * Read off the folder rather than listed, and off the markup specifically,
  * because that is how `resolveCaptureSources` decides what `canon capture
- * assets` renders. A list would fail open on the frame somebody adds next,
- * which is the one nobody thinks to add here, and driving off the PNGs instead
- * would report a missing set for any image in the folder that is not a capture.
+ * assets/captures` renders. A list would fail open on the frame somebody adds
+ * next, which is the one nobody thinks to add here, and driving off the PNGs
+ * instead would report a missing set for any image in `assets/` that is not a
+ * capture.
  */
 function captureBases(root: string): string[] {
-  const dir = join(root, CAPTURE_DIR)
+  const dir = join(root, CAPTURE_MARKUP_DIR)
   if (!existsSync(dir)) return []
 
   return readdirSync(dir)
@@ -898,7 +907,7 @@ function captureBases(root: string): string[] {
  * Both digests are checked because either file can move alone. The markup side
  * catches an edit committed with no capture, and the image side catches an
  * image replaced under markup that never changed. A tree carrying no markup
- * under `assets/` has no set to read and passes, which is correct.
+ * under `assets/captures/` has no set to read and passes, which is correct.
  */
 export const captureStamps: Measure = async (ctx) => {
   const lines = captureBases(ctx.root).flatMap((base) =>
@@ -912,11 +921,21 @@ export const captureStamps: Measure = async (ctx) => {
   }
 }
 
-/** One capture set, as the lines it has to report and none where it agrees. */
+/**
+ * One capture set, as the lines it has to report and none where it agrees.
+ *
+ * The markup resolves against the source folder and the two files a render
+ * writes resolve against the output folder, so the set spans both rather than
+ * hanging off one base directory. Sending any of the three to the wrong folder
+ * reports it as missing rather than failing loudly, since a missing file reads
+ * the same way whether the path is wrong or the file is.
+ */
 function readCaptureSet(root: string, base: string): string[] {
-  const set = (['html', 'png', 'stamp'] as const).map(
-    (extension) => `${CAPTURE_DIR}/${base}.${extension}`,
-  )
+  const set = [
+    `${CAPTURE_MARKUP_DIR}/${base}.html`,
+    `${CAPTURE_OUTPUT_DIR}/${base}.png`,
+    `${CAPTURE_OUTPUT_DIR}/${base}.stamp`,
+  ]
 
   const missing = set.filter((rel) => !existsSync(join(root, rel)))
   if (missing.length > 0) {

package/src/gate/stages.ts

@@ -186,18 +186,19 @@ export const STAGES: readonly Stage[] = [
     // would fail on a machine whose chromium differs rather than on a stale
     // count. The stamp measure below is what covers the image instead.
     //
-    // The stage covers both frames under `assets/` and keeps the narrower name,
-    // because the label is spelled across the context entries and the CI table
-    // and renaming it buys nothing the pathspec below does not already say.
+    // The stage covers every frame under `assets/captures/` and keeps the
+    // narrower name, because the label is spelled across the context entries and
+    // the CI table and renaming it buys nothing the pathspec below does not
+    // already say.
     id: 'hero',
     label: 'Hero',
     checks: [
       script('regen-hero.sh', 'Hero regen failed'),
       {
         kind: 'drift',
-        pathspec: 'assets/*.html',
+        pathspec: 'assets/captures/*.html',
         failure:
-          'A generated frame drifted from the catalogs or the design source. Run bun run check, then canon capture assets --selector .window, and commit each assets/*.html with its .png and .stamp.',
+          'A generated frame drifted from the catalogs or the design source. Run bun run check, then canon capture assets/captures --selector .window --out assets, and commit each assets/captures/*.html with its .png and .stamp.',
       },
       { kind: 'measure', measure: captureStamps },
     ],

package/src/migrate/record-tree.ts

@@ -15,7 +15,12 @@
 
 import { readdir, readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { RECORD_ONLY_ROOTS, rewriteText, scanText } from '@/migrate/records'
+import {
+  type CitationLine,
+  RECORD_ONLY_ROOTS,
+  rewriteText,
+  scanText,
+} from '@/migrate/records'
 
 /**
  * The folders inside the record root a session still follows a path into.
@@ -82,12 +87,6 @@ export interface RecordTreeSource {
   readonly text: string
 }
 
-/** Where a citation sits, so a reader can judge it before `--write` runs. */
-export interface CitationLine {
-  readonly line: number
-  readonly text: string
-}
-
 /** One record file whose citations move. */
 export interface RecordTreeEntry {
   readonly path: string

package/src/migrate/records.ts

@@ -223,43 +223,119 @@ function isKept(lines: readonly string[], index: number): boolean {
   return above >= 0 && (lines[above]?.includes(KEEP_MARKER) ?? false)
 }
 
-/** Rewrites every unmarked citation into a moved entry. */
+/**
+ * The line index where a leading YAML frontmatter block closes, or
+ * `undefined` when the file does not open with a bare `---` on line one.
+ */
+function frontmatterEnd(lines: readonly string[]): number | undefined {
+  if (lines[0] !== '---') return undefined
+  const end = lines.indexOf('---', 1)
+  return end === -1 ? undefined : end
+}
+
+/**
+ * Marks a line inside a rule's frontmatter `paths:` key: the key line itself,
+ * or an indented `- 'glob'` list item under it. Structural rather than
+ * marker-based, found by walking up to the nearest line starting at column 0
+ * and testing whether that line is the bare `paths:` key.
+ *
+ * Independent of `KEEP_MARKER`. A rewritten glob stops matching silently,
+ * where a rewritten sentence is at least visible to a reader, so this line is
+ * held whether or not anyone remembered the marker.
+ */
+function isFrontmatterPathsLine(
+  lines: readonly string[],
+  index: number,
+  frontmatterEndIndex: number | undefined,
+): boolean {
+  if (frontmatterEndIndex === undefined) return false
+  if (index <= 0 || index >= frontmatterEndIndex) return false
+
+  let top = index
+  while (top > 0 && /^\s/.test(lines[top] ?? '')) top -= 1
+
+  return lines[top]?.trim().startsWith('paths:') ?? false
+}
+
+type LineClass = 'live' | 'kept' | 'glob'
+
+function classifyLine(
+  lines: readonly string[],
+  index: number,
+  frontmatterEndIndex: number | undefined,
+): LineClass {
+  if (isFrontmatterPathsLine(lines, index, frontmatterEndIndex)) return 'glob'
+  if (isKept(lines, index)) return 'kept'
+  return 'live'
+}
+
+/** Rewrites every unmarked, non-glob citation into a moved entry. */
 export function rewriteText(text: string): string {
   const lines = text.split('\n')
+  const frontmatterEndIndex = frontmatterEnd(lines)
 
   return lines
     .map((line, index) =>
-      isKept(lines, index)
-        ? line
-        : line.replace(CITATION, (_match, entry: string) =>
+      classifyLine(lines, index, frontmatterEndIndex) === 'live'
+        ? line.replace(CITATION, (_match, entry: string) =>
             destinationPath(entry),
-          ),
+          )
+        : line,
     )
     .join('\n')
 }
 
 /**
- * How many citations `rewriteText` would rewrite, and how many marked lines it
- * left alone. The second number is what says the markers fired at all, which a
- * diff cannot show because a protected line does not appear in one.
+ * How many citations `rewriteText` would rewrite, how many marked lines it
+ * left alone, and how many sat inside a frontmatter `paths:` glob. The second
+ * and third numbers are what say the markers and the glob boundary fired at
+ * all, which a diff cannot show because a protected line does not appear in
+ * one.
  */
 export function scanText(text: string): {
   readonly rewritten: number
   readonly kept: number
+  readonly globs: number
 } {
   const lines = text.split('\n')
+  const frontmatterEndIndex = frontmatterEnd(lines)
   let rewritten = 0
   let kept = 0
+  let globs = 0
 
   for (const [index, line] of lines.entries()) {
     const matches = [...line.matchAll(CITATION)].length
     if (matches === 0) continue
 
-    if (isKept(lines, index)) kept += matches
+    const kind = classifyLine(lines, index, frontmatterEndIndex)
+    if (kind === 'glob') globs += matches
+    else if (kind === 'kept') kept += matches
     else rewritten += matches
   }
 
-  return { rewritten, kept }
+  return { rewritten, kept, globs }
+}
+
+/** Where a citation sits, so a reader can judge it before `--write` runs. */
+export interface CitationLine {
+  readonly line: number
+  readonly text: string
+}
+
+/** Every frontmatter `paths:` line in `text` carrying a citation. */
+function frontmatterGlobLines(text: string): CitationLine[] {
+  const lines = text.split('\n')
+  const frontmatterEndIndex = frontmatterEnd(lines)
+  const held: CitationLine[] = []
+
+  for (const [index, line] of lines.entries()) {
+    if (!isFrontmatterPathsLine(lines, index, frontmatterEndIndex)) continue
+    if ([...line.matchAll(CITATION)].length === 0) continue
+
+    held.push({ line: index + 1, text: line.trim() })
+  }
+
+  return held
 }
 
 export interface FolderMove {
@@ -320,14 +396,22 @@ export interface CitationEntry {
   readonly kept: number
 }
 
+/** One file whose frontmatter `paths:` glob names a moved root, held rather than rewritten. */
+export interface FrontmatterGlobEntry {
+  readonly path: string
+  readonly lines: readonly CitationLine[]
+}
+
 export interface RecordsPlan {
   readonly moves: readonly FolderMove[]
   readonly collisions: readonly string[]
   readonly entries: readonly CitationEntry[]
   readonly excluded: readonly string[]
   readonly coupled: readonly string[]
+  readonly frontmatterGlobs: readonly FrontmatterGlobEntry[]
   readonly rewritten: number
   readonly kept: number
+  readonly globs: number
 }
 
 /**
@@ -346,7 +430,9 @@ export function planRecordsMove(
   const entries: CitationEntry[] = []
   const excluded: string[] = []
   const coupled: string[] = []
+  const frontmatterGlobs: FrontmatterGlobEntry[] = []
   let kept = 0
+  let globs = 0
 
   for (const source of sources) {
     // Silently, and ahead of the exclusion test. The command boundary filters
@@ -365,6 +451,14 @@ export function planRecordsMove(
 
     const counts = scanText(source.text)
     kept += counts.kept
+    globs += counts.globs
+
+    // Ahead of the rewritten === 0 continue below: a file whose only citation
+    // sits in its paths: glob still needs to be reported.
+    const held = frontmatterGlobLines(source.text)
+    if (held.length > 0)
+      frontmatterGlobs.push({ path: source.path, lines: held })
+
     if (counts.rewritten === 0) continue
 
     if (referencesExcluded(source.text)) coupled.push(source.path)
@@ -383,7 +477,9 @@ export function planRecordsMove(
     entries,
     excluded,
     coupled,
+    frontmatterGlobs,
     rewritten: entries.reduce((sum, entry) => sum + entry.rewritten, 0),
     kept,
+    globs,
   }
 }