explico 0.13.1 → 0.15.0

package/src/compiler/cli.ts

@@ -1,7 +1,8 @@
 /**
  * The `content` CLI core (Phase G1).
  *
- * `scripts/content.ts` is a thin argv wrapper; every command's logic lives here
+ * `./cli-main` is the router (`runContentCli`), a course's `scripts/content.ts`
+ * a three-line shim over it; every command's logic lives here
  * as a pure-ish function that takes a compiled {@link Manifest} and returns a
  * plain data object. The router is **read-only** — only `content new` touches
  * the filesystem, and even then `scaffoldLesson` / `scaffoldTerm` only return
@@ -31,9 +32,9 @@
  */
 
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join, relative } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import {
   createMarkdownProcessor,
@@ -53,11 +54,27 @@ import remarkNotation, {
 } from '../reference/remark-notation.mjs';
 import remarkShortNote from '../reference/remark-short-note.mjs';
 import type { DiagnosticSeverity } from '../reference/types';
-import type { EquationLink } from '../reference/gate-math';
-import type { Manifest, ManifestLesson } from './manifest';
+import {
+  explainCalls,
+  mathSpans,
+  redundantExplainWraps,
+  type EquationLink,
+  type ScopeEntry,
+} from '../reference/gate-math';
+import { resolveMathGlyphs } from '../reference/math-glyphs.mjs';
+import { stripEquationLabels } from '../reference/equations.mjs';
+import type { Manifest, ManifestLesson, ManifestLessonFloat } from './manifest';
 import { readRenderDiagnostics, type RenderDiagnostic } from './render-diagnostics';
-import { isLessonSlug, lessonIdFromSlug } from './lesson-derivation';
-import { isCourseRuleId, ownerOf, ELEMENTS, type Element, type Enforcement } from '../rules/catalog';
+import { isLessonSlug, lessonIdFromSlug, mergeTrackOrder } from './lesson-derivation';
+import {
+  isCourseRuleId,
+  ownerOf,
+  retiredRule,
+  ELEMENTS,
+  type Element,
+  type Enforcement,
+  type RetiredRule,
+} from '../rules/catalog';
 import {
   renderRulesInEffect,
   rulesInEffect,
@@ -65,6 +82,7 @@ import {
   type RulesFilter,
 } from '../rules/in-effect';
 import { RESERVED_KEY_PREFIXES, reservedKeyPrefix } from '../reference/references';
+import { glyphMatcher } from '../reference/consistency';
 
 const REPOSITORY_ROOT = process.cwd();
 // Content and its course math are the top-level `content/` folder (Phase F).
@@ -82,7 +100,11 @@ export type ContentCliCode =
   | 'invalid-id'
   | 'exists'
   | 'not-a-lesson'
-  | 'no-git';
+  | 'no-git'
+  | 'unknown-version'
+  | 'migration-gap'
+  | 'unknown-key'
+  | 'no-changelog';
 
 /** A user-facing failure with a stable code and no stack in `--json` output. */
 export class ContentCliError extends Error {
@@ -105,6 +127,8 @@ export interface CliDiagnostic {
    * which `tests/rules/catalog.test.ts` treats as a bug.
    */
   readonly rule?: string;
+  /** The owner's page and anchor under `docs/authoring/`, `notation.md#n4`. */
+  readonly doc?: string;
   readonly severity: DiagnosticSeverity;
   readonly message: string;
   readonly file?: string;
@@ -127,13 +151,33 @@ function diagnosticSeverity(value: unknown): DiagnosticSeverity {
  * `{ rule }` for a `<source>:<code>` (or bare) code the catalog owns — or for a
  * course rule, whose code is its own ID (`X1`).
  */
-function ownerFields(code: string): { readonly rule?: string } {
+function ownerFields(code: string): { readonly rule?: string; readonly doc?: string } {
   const bare = code.slice(code.indexOf(':') + 1);
   const owner = ownerOf(bare);
-  if (owner !== undefined) return { rule: owner.id };
+  if (owner !== undefined) return { rule: owner.id, doc: owner.doc };
   return isCourseRuleId(bare) ? { rule: bare } : {};
 }
 
+/** ` [N4 · notation.md#n4]` for a diagnostic the catalog owns; empty otherwise. */
+export function ownerTag(diagnostic: Pick<CliDiagnostic, 'rule' | 'doc'>): string {
+  if (!diagnostic.rule) return '';
+  return ` [${diagnostic.rule}${diagnostic.doc ? ` · ${diagnostic.doc}` : ''}]`;
+}
+
+/**
+ * One text line for a diagnostic, the shape every verb prints:
+ * `file:line:column: severity code [rule · doc]: message`. The location is
+ * left out when the diagnostic has no file, and reads `1:1` when the file is
+ * known but the position is not, so an editor opens the file. The rule and its page are on the
+ * line so a reader needs no second lookup to find what the code answers to.
+ */
+export function formatCliDiagnostic(diagnostic: CliDiagnostic): string {
+  const location = diagnostic.file
+    ? `${diagnostic.file}:${diagnostic.line ?? 1}:${diagnostic.column ?? 1}: `
+    : '';
+  return `${location}${diagnostic.severity} ${diagnostic.code}${ownerTag(diagnostic)}: ${diagnostic.message}`;
+}
+
 function withOwner(diagnostic: CliDiagnostic): CliDiagnostic {
   return { ...diagnostic, ...ownerFields(diagnostic.code) };
 }
@@ -165,7 +209,7 @@ function mentions(message: string, lessonId: string, file: string): boolean {
  */
 export function lessonDiagnostics(
   manifest: Manifest,
-  lesson: ManifestLesson,
+  lesson: CheckTarget,
   rendered: readonly RenderDiagnostic[] = readRenderDiagnostics(),
 ): CliDiagnostic[] {
   const out: CliDiagnostic[] = [];
@@ -523,7 +567,7 @@ export function findLesson(manifest: Manifest, rawId: string): ManifestLesson {
   return lesson;
 }
 
-function lessonAbsolutePath(lesson: ManifestLesson): string {
+function lessonAbsolutePath(lesson: Pick<ManifestLesson, 'file'>): string {
   return join(REPOSITORY_ROOT, lesson.file);
 }
 
@@ -628,6 +672,31 @@ function domainSignaturesForSection(section: string): DomainFileSignatures[] {
 export interface StatusReport {
   /** The course's published knowledge version (`about.version`). */
   readonly knowledgeVersion: string;
+  /**
+   * What an agent is told to read before working, in estimated tokens: the
+   * course's `AGENTS.md`, the repository's one level up when the course is a
+   * workspace package, and the rules-in-effect page. A budget to watch; the
+   * estimate is bytes over four.
+   */
+  readonly agentSurfaces: readonly { readonly name: string; readonly tokens: number }[];
+  /**
+   * Whether the course's own `AGENTS.md` points an agent at the engine's
+   * guide (`docs/authoring/agents.md`), and whether the procedures
+   * `content init-agent` installs are in `.claude/`.
+   */
+  readonly agentGuide: {
+    readonly agentsFile: string | null;
+    readonly linksGuide: boolean;
+    readonly skillsInstalled: boolean;
+  };
+  /**
+   * Rule C5: how many chapters and part pages carry a version of their own,
+   * and the slugs of those with a change `## [Unreleased]` has not released.
+   */
+  readonly pageVersions: {
+    readonly tracked: number;
+    readonly unreleased: readonly string[];
+  };
   readonly counts: {
     readonly lessons: number;
     readonly competencies: number;
@@ -649,6 +718,40 @@ export interface StatusReport {
   };
 }
 
+/** The engine guide's file name, which a course's `AGENTS.md` names to point at it. */
+const AGENT_GUIDE_MENTION = /docs\/authoring\/agents\.md/;
+
+function agentGuideState(): StatusReport['agentGuide'] {
+  const agentsFile = ['AGENTS.md', 'CLAUDE.md'].find((name) => existsSync(join(REPOSITORY_ROOT, name))) ?? null;
+  const linksGuide =
+    agentsFile !== null && AGENT_GUIDE_MENTION.test(readFileSync(join(REPOSITORY_ROOT, agentsFile), 'utf8'));
+  const skillsInstalled = existsSync(join(REPOSITORY_ROOT, '.claude', 'skills', 'draft-lesson', 'SKILL.md'));
+  return { agentsFile, linksGuide, skillsInstalled };
+}
+
+function agentSurfaces(manifest: Manifest): { readonly name: string; readonly tokens: number }[] {
+  const surfaces: { name: string; tokens: number }[] = [];
+  for (const rel of ['AGENTS.md', join('..', 'AGENTS.md')]) {
+    const path = join(REPOSITORY_ROOT, rel);
+    if (!existsSync(path)) continue;
+    surfaces.push({ name: rel, tokens: estimateTokens(readFileSync(path, 'utf8')) });
+  }
+  surfaces.push({
+    name: 'rules in effect',
+    tokens: estimateTokens(renderRulesInEffect(manifest)),
+  });
+  // The migration an upgrade would read, when the pin and the install differ.
+  try {
+    const migration = contentMigrate();
+    if (migration.sections.length > 0) {
+      surfaces.push({ name: `migration ${migration.from} → ${migration.to}`, tokens: migration.tokens });
+    }
+  } catch {
+    // no pin, no install, or no guide: nothing to size
+  }
+  return surfaces;
+}
+
 export function contentStatus(
   manifest: Manifest,
   rendered: readonly RenderDiagnostic[] = readRenderDiagnostics(),
@@ -710,8 +813,24 @@ export function contentStatus(
     manifest.lessons.flatMap((lesson) => lesson.assessments),
   ).size;
 
+  const trackedPages = [
+    ...manifest.lessons.map((lesson) => ({ slug: lesson.slug, since: lesson.since })),
+    ...manifest.parts.flatMap((part) =>
+      part.overview ? [{ slug: `${part.dir}/index`, since: part.overview.since }] : [],
+    ),
+  ];
+
   return {
     knowledgeVersion: manifest.about.knowledge.version,
+    agentSurfaces: agentSurfaces(manifest),
+    agentGuide: agentGuideState(),
+    pageVersions: {
+      tracked: manifest.pageVersions.enabled ? trackedPages.length : 0,
+      unreleased: trackedPages
+        .filter((page) => page.since === null)
+        .map((page) => page.slug)
+        .sort(),
+    },
     counts: {
       lessons: manifest.lessons.length,
       competencies: manifest.competencies.length,
@@ -745,6 +864,125 @@ export interface DiagnosticsReport {
   readonly diagnostics: readonly CliDiagnostic[];
 }
 
+/**
+ * The diagnostics list folded to what an agent decides from: how many, of
+ * what, and where. The default text output, since a course can have hundreds
+ * of lines of two codes and the list is what `--all` is for.
+ */
+export interface DiagnosticsSummary {
+  readonly minimumSeverity: DiagnosticThreshold;
+  readonly count: number;
+  readonly bySeverity: { readonly errors: number; readonly warnings: number; readonly infos: number };
+  /** One row per code and severity, most frequent first. */
+  readonly byCode: readonly {
+    readonly code: string;
+    readonly rule?: string;
+    readonly doc?: string;
+    readonly severity: DiagnosticSeverity;
+    readonly count: number;
+  }[];
+  /** One row per file, most diagnostics first; `(no file)` for the rest. */
+  readonly byFile: readonly {
+    readonly file: string;
+    readonly count: number;
+    readonly errors: number;
+    readonly warnings: number;
+    readonly infos: number;
+  }[];
+}
+
+function severityCounts(diagnostics: readonly CliDiagnostic[]) {
+  const counts = { errors: 0, warnings: 0, infos: 0 };
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.severity === 'error') counts.errors += 1;
+    else if (diagnostic.severity === 'warning') counts.warnings += 1;
+    else counts.infos += 1;
+  }
+  return counts;
+}
+
+export function summarizeDiagnostics(report: DiagnosticsReport): DiagnosticsSummary {
+  const byCode = new Map<string, DiagnosticsSummary['byCode'][number]>();
+  const byFile = new Map<string, CliDiagnostic[]>();
+  for (const diagnostic of report.diagnostics) {
+    const codeKey = `${diagnostic.code}\u0000${diagnostic.severity}`;
+    const row = byCode.get(codeKey);
+    if (row) byCode.set(codeKey, { ...row, count: row.count + 1 });
+    else {
+      byCode.set(codeKey, {
+        code: diagnostic.code,
+        ...(diagnostic.rule === undefined ? {} : { rule: diagnostic.rule }),
+        ...(diagnostic.doc === undefined ? {} : { doc: diagnostic.doc }),
+        severity: diagnostic.severity,
+        count: 1,
+      });
+    }
+    const file = diagnostic.file ?? '(no file)';
+    byFile.set(file, [...(byFile.get(file) ?? []), diagnostic]);
+  }
+  const byCount = <T extends { count: number }>(key: (row: T) => string) => (a: T, b: T) =>
+    b.count - a.count || key(a).localeCompare(key(b));
+  return {
+    minimumSeverity: report.minimumSeverity,
+    count: report.count,
+    bySeverity: severityCounts(report.diagnostics),
+    byCode: [...byCode.values()].sort(byCount((row) => row.code)),
+    byFile: [...byFile]
+      .map(([file, list]) => ({ file, count: list.length, ...severityCounts(list) }))
+      .sort(byCount((row) => row.file)),
+  };
+}
+
+/** The diagnostics of one code (with or without its `source:` prefix) or of some files. */
+export function filterDiagnostics(
+  report: DiagnosticsReport,
+  filter: { readonly code?: string; readonly files?: readonly string[] },
+): DiagnosticsReport {
+  const files = filter.files === undefined ? undefined : new Set(filter.files);
+  const diagnostics = report.diagnostics.filter((diagnostic) => {
+    if (
+      filter.code !== undefined &&
+      diagnostic.code !== filter.code &&
+      diagnostic.code.slice(diagnostic.code.indexOf(':') + 1) !== filter.code
+    ) {
+      return false;
+    }
+    return files === undefined || (diagnostic.file !== undefined && files.has(diagnostic.file));
+  });
+  return { minimumSeverity: report.minimumSeverity, count: diagnostics.length, diagnostics };
+}
+
+/** The summary as text: a severity line, then counts by code and by file, the file list capped. */
+export function formatDiagnosticsSummary(
+  summary: DiagnosticsSummary,
+  options: { readonly fileCap?: number } = {},
+): string {
+  const fileCap = options.fileCap ?? 25;
+  const s = summary.bySeverity;
+  const lines = [
+    `${summary.count} diagnostic(s) at ${summary.minimumSeverity} or higher: ${s.errors} error(s), ${s.warnings} warning(s), ${s.infos} info`,
+  ];
+  if (summary.count === 0) return `${lines[0]}\n`;
+  lines.push('by code');
+  for (const row of summary.byCode) {
+    lines.push(`  ${String(row.count).padStart(5)}  ${row.severity.padEnd(7)}  ${row.code}${ownerTag(row)}`);
+  }
+  lines.push('by file');
+  for (const row of summary.byFile.slice(0, fileCap)) {
+    const parts = [
+      row.errors > 0 ? `${row.errors} error(s)` : '',
+      row.warnings > 0 ? `${row.warnings} warning(s)` : '',
+      row.infos > 0 ? `${row.infos} info` : '',
+    ].filter((part) => part !== '');
+    lines.push(`  ${String(row.count).padStart(5)}  ${row.file}  (${parts.join(', ')})`);
+  }
+  if (summary.byFile.length > fileCap) {
+    lines.push(`         … and ${summary.byFile.length - fileCap} more file(s)`);
+  }
+  lines.push('List them: --all for every line; --code <code>, --lesson <id> or --changed for a part.');
+  return `${lines.join('\n')}\n`;
+}
+
 export interface WarningsReport {
   readonly count: number;
   readonly warnings: readonly CliDiagnostic[];
@@ -899,8 +1137,20 @@ export interface RulesReport {
 export function parseRulesFilter(input: {
   readonly element?: string;
   readonly enforcement?: string;
+  /** `chapter` (the default page) or `deck` (`<lesson>.deck.mdx`). */
+  readonly edition?: string;
 }): RulesFilter {
-  const filter: { elements?: Element[]; enforcement?: Enforcement | 'locked' } = {};
+  const filter: {
+    elements?: Element[];
+    enforcement?: Enforcement | 'locked';
+    edition?: 'chapter' | 'deck';
+  } = {};
+  if (input.edition !== undefined) {
+    if (input.edition !== 'chapter' && input.edition !== 'deck') {
+      throw new ContentCliError('usage', `--edition ${input.edition}: one of chapter, deck.`);
+    }
+    filter.edition = input.edition;
+  }
   if (input.element !== undefined) {
     const elements = input.element.split(',').map((e) => e.trim()).filter(Boolean);
     for (const element of elements) {
@@ -949,6 +1199,8 @@ export interface ContextReport {
     readonly teaches: readonly string[];
     readonly requires: readonly string[];
     readonly assumptions: readonly string[];
+    /** The version the page's content last changed in; `null` for a change not yet released (rule C5). */
+    readonly since: string | null;
     readonly notationLocal: unknown;
     readonly body: string;
   };
@@ -962,10 +1214,10 @@ export interface ContextReport {
     units?: string;
     formula?: string;
   }[];
-  readonly equations: readonly { key: string; number: string }[];
-  readonly tables: readonly { key: string; number: string }[];
-  readonly figures: readonly { key: string; number: string }[];
-  readonly diagrams: readonly { key: string; number: string }[];
+  readonly equations: readonly ManifestLessonFloat[];
+  readonly tables: readonly ManifestLessonFloat[];
+  readonly figures: readonly ManifestLessonFloat[];
+  readonly diagrams: readonly ManifestLessonFloat[];
   /** Worked-example sets: `short` is the title `[[ex-key]]` names. */
   readonly examples: readonly { key: string; number: string; short?: string }[];
   readonly knowledgeChecks: readonly { key: string; number: string; title?: string }[];
@@ -988,179 +1240,1602 @@ export interface ContextReport {
   readonly tokens: TokenCounts;
 }
 
-export function contentContext(
-  manifest: Manifest,
-  rawId: string,
-): ContextReport {
-  const lesson = findLesson(manifest, rawId);
-  const { frontmatter, body } = lessonRaw(lesson);
-
-  const outcomeById = new Map(
-    manifest.competencies.map((competency) => [
-      String(competency.id),
-      String(competency.outcome ?? ''),
-    ]),
-  );
-  const outcomesFor = (ids: readonly string[]) =>
-    ids
-      .filter((id) => outcomeById.has(id))
-      .map((id) => ({ id, outcome: outcomeById.get(id) ?? '' }));
+// --- content migrate -------------------------------------------------
 
-  const sourceById = new Map(
-    manifest.sources.map((source) => [String(source.id), source]),
-  );
-  const citedLocatorsById = new Map<string, string[]>();
-  for (const citation of lesson.citations) {
-    const list = citedLocatorsById.get(citation.id) ?? [];
-    if (citation.locator) list.push(citation.locator);
-    citedLocatorsById.set(citation.id, list);
-  }
+/*
+ * The migration guide, cut to the sections an upgrade needs: from the
+ * version a course pins to the version it has installed, oldest first. The
+ * guide is one newest-first file of every release; an upgrade reads one or
+ * two sections of it, and the heading grammar `## <from> → <to>` (a `0.4.x`
+ * range on the left, `Unreleased` allowed on the right) says which.
+ */
+export interface MigrationSection {
+  readonly from: string;
+  readonly to: string;
+  readonly heading: string;
+  readonly markdown: string;
+  readonly tokens: number;
+}
 
-  const contextWithoutTokens = {
-    lesson: {
-      id: lesson.id,
-      slug: lesson.slug,
-      file: lesson.file,
-      title: lesson.title,
-      description: lesson.description,
-      teaches: lesson.teaches,
-      requires: lesson.requires,
-      assumptions: lesson.assumptions,
-      notationLocal:
-        (frontmatter.notation as { local?: unknown } | undefined)?.local ?? [],
-      body,
-    },
-    taughtOutcomes: outcomesFor(lesson.teaches),
-    prerequisiteOutcomes: outcomesFor(lesson.requires),
-    notation: lesson.notation.definitions.map((definition) => ({
-      key: definition.key,
-      latex: definition.notation,
-      meaning: definition.summary,
-      scope: definition.scope,
-      ...(definition.units === undefined ? {} : { units: definition.units }),
-      ...(definition.formula === undefined
-        ? {}
-        : { formula: definition.formula }),
-    })),
-    equations: lesson.equations.map((equation) => ({ ...equation })),
-    tables: lesson.tables.map((table) => ({ ...table })),
-    figures: lesson.figures.map((figure) => ({ ...figure })),
-    diagrams: lesson.diagrams.map((diagram) => ({ ...diagram })),
-    examples: lesson.examples.map((example) => ({ ...example })),
-    knowledgeChecks: lesson.knowledgeChecks.map((check) => ({ ...check })),
-    sections: lesson.headings.map((heading) => ({ ...heading })),
-    sources: lesson.sources.map((id) => {
-      const record = sourceById.get(id) as Record<string, unknown> | undefined;
-      return {
-        id,
-        title: String(record?.title ?? id),
-        type: String(record?.type ?? 'unknown'),
-        ...(typeof record?.locator === 'string'
-          ? { recordLocator: record.locator }
-          : {}),
-        citedLocators: citedLocatorsById.get(id) ?? [],
-      };
-    }),
-    domainSignatures: domainSignaturesForSection(
-      lesson.slug.split('/')[0] ?? '',
-    ),
-    diagnostics: lessonDiagnostics(manifest, lesson),
-  };
+export interface MigrateReport {
+  readonly from: string;
+  readonly to: string;
+  readonly file: string;
+  readonly sections: readonly MigrationSection[];
+  readonly tokens: number;
+}
 
-  return {
-    ...contextWithoutTokens,
-    tokens: tokenCounts(contextWithoutTokens),
-  };
+const MIGRATION_HEADING = /^## ([^\n→]+?) → ([^\n]+?)[\t ]*$/;
+
+/** Every `## <from> → <to>` section of the guide, in file order (newest first). */
+export function parseMigrationSections(markdown: string): MigrationSection[] {
+  const lines = markdown.split('\n');
+  const starts = lines
+    .map((line, index) => ({ index, match: MIGRATION_HEADING.exec(line) }))
+    .filter((entry): entry is { index: number; match: RegExpExecArray } => entry.match !== null);
+  return starts.map(({ index, match }, position) => {
+    // A section runs to the next `## ` heading of any kind, so the trailing
+    // changelog-style block ends the last one.
+    let end = lines.findIndex((line, i) => i > index && line.startsWith('## '));
+    if (end < 0) end = lines.length;
+    const body = lines.slice(index, end);
+    while (body.length > 0 && /^(---)?\s*$/.test(body[body.length - 1]!)) body.pop();
+    const text = body.join('\n');
+    return {
+      from: match[1]!.trim(),
+      to: match[2]!.trim(),
+      heading: lines[index]!,
+      markdown: text,
+      tokens: estimateTokens(text),
+      ...(position === starts.length ? {} : {}),
+    };
+  });
 }
 
-// --- content check ---------------------------------------------------
+function versionParts(version: string): number[] | undefined {
+  if (version === 'Unreleased') return undefined;
+  const parts = version.split('.').map((part) => (part === 'x' ? -1 : Number(part)));
+  return parts.every((part) => Number.isInteger(part)) ? parts : undefined;
+}
 
-export interface CheckLessonResult {
-  readonly lesson: string;
-  readonly file: string;
-  readonly ok: boolean;
-  readonly rendered: boolean;
-  readonly diagnostics: readonly CliDiagnostic[];
+/** `0.4.x` matches any `0.4.*`; otherwise the versions are equal. */
+function versionMatches(pattern: string, version: string): boolean {
+  if (pattern === version) return true;
+  const p = versionParts(pattern);
+  const v = versionParts(version);
+  if (!p || !v) return false;
+  return p.every((part, index) => part === -1 || part === v[index]);
 }
 
-export interface CheckReport {
-  readonly ok: boolean;
-  readonly lessons: readonly CheckLessonResult[];
+function compareVersions(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a === 'Unreleased') return 1;
+  if (b === 'Unreleased') return -1;
+  const pa = versionParts(a) ?? [];
+  const pb = versionParts(b) ?? [];
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
 }
 
-async function checkOneLesson(
-  manifest: Manifest,
-  lesson: ManifestLesson,
-): Promise<CheckLessonResult> {
-  const manifestDiagnostics = lessonDiagnostics(manifest, lesson);
-  const { frontmatter, body } = lessonSource(
-    readFileSync(lessonAbsolutePath(lesson), 'utf8'),
-  );
-  const render = await renderLesson(manifest, {
-    body,
-    frontmatter,
-    path: lessonAbsolutePath(lesson),
-  });
+/**
+ * The sections that take a course from `from` to `to`, oldest first: each
+ * section's left side matches where the previous one ended. A hole in the
+ * chain is an error naming the version no section continues from, since a
+ * skipped section is a skipped migration.
+ */
+export function selectMigrationPath(
+  sections: readonly MigrationSection[],
+  from: string,
+  to: string,
+): MigrationSection[] {
+  if (compareVersions(from, to) > 0) {
+    throw new ContentCliError(
+      'unknown-version',
+      `--from ${from} is newer than --to ${to}; the guide only goes forward.`,
+    );
+  }
+  const path: MigrationSection[] = [];
+  let cursor = from;
+  while (compareVersions(cursor, to) < 0) {
+    const next = sections
+      .filter((section) => versionMatches(section.from, cursor) && compareVersions(section.to, to) <= 0)
+      .sort((a, b) => compareVersions(a.to, b.to))[0];
+    if (!next) {
+      throw new ContentCliError(
+        'migration-gap',
+        `No section continues from ${cursor} towards ${to}. Sections known: ${sections
+          .map((section) => `${section.from} → ${section.to}`)
+          .join(', ')}.`,
+      );
+    }
+    path.push(next);
+    cursor = next.to;
+  }
+  return path;
+}
 
-  const diagnostics = [...manifestDiagnostics, ...render.diagnostics].sort(
-    (a, b) =>
-      a.code.localeCompare(b.code) || a.message.localeCompare(b.message),
-  );
-  return {
-    lesson: lesson.id,
-    file: lesson.file,
-    ok: !diagnostics.some((diagnostic) => diagnostic.severity === 'error'),
-    rendered: render.rendered,
-    diagnostics,
-  };
+/** The engine version the course has installed: the package beside it, or this one. */
+export function installedEngineVersion(): string | undefined {
+  for (const path of [
+    join(REPOSITORY_ROOT, 'node_modules', 'explico', 'package.json'),
+    join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'),
+    join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'),
+  ]) {
+    if (!existsSync(path)) continue;
+    try {
+      const pkg = JSON.parse(readFileSync(path, 'utf8')) as { name?: string; version?: string };
+      if (pkg.name === 'explico' && typeof pkg.version === 'string') return pkg.version;
+    } catch {
+      // not this one
+    }
+  }
+  return undefined;
 }
 
-/** `.mdx` / `.checks.yml` paths that differ from `HEAD`, tracked or not. */
-export function changedLessonIds(): string[] {
-  let output: string;
+/**
+ * The engine version `package.json` pins at HEAD — what the course last
+ * migrated to, before the working tree bumped it. `workspace:*` or a range
+ * is no version, so the caller asks for `--from`.
+ */
+export function pinnedEngineVersion(): string | undefined {
+  let text: string;
   try {
-    const tracked = execFileSync(
-      'git',
-      ['diff', '--name-only', 'HEAD', '--', 'content/docs'],
-      { cwd: REPOSITORY_ROOT, encoding: 'utf8' },
-    );
-    const untracked = execFileSync(
-      'git',
-      ['ls-files', '--others', '--exclude-standard', '--', 'content/docs'],
-      { cwd: REPOSITORY_ROOT, encoding: 'utf8' },
-    );
-    output = `${tracked}\n${untracked}`;
+    text = execFileSync('git', ['show', 'HEAD:package.json'], {
+      cwd: REPOSITORY_ROOT,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch {
+    return undefined;
+  }
+  try {
+    const pkg = JSON.parse(text) as Record<string, Record<string, string> | undefined>;
+    const pinned = pkg.dependencies?.explico ?? pkg.devDependencies?.explico;
+    if (typeof pinned !== 'string') return undefined;
+    const exact = pinned.replace(/^[\^~=v]/, '');
+    return versionParts(exact) ? exact : undefined;
   } catch {
+    return undefined;
+  }
+}
+
+export function contentMigrate(options: { readonly from?: string; readonly to?: string } = {}): MigrateReport {
+  const dir = authoringDocsDir();
+  const file = dir === undefined ? undefined : join(dir, 'migrating.md');
+  if (file === undefined || !existsSync(file)) {
+    throw new ContentCliError('unknown-version', 'No migrating.md beside the engine (node_modules/explico/docs/authoring).');
+  }
+  const to = options.to ?? installedEngineVersion();
+  if (to === undefined) {
+    throw new ContentCliError('unknown-version', 'Could not read the installed engine version; pass --to <version>.');
+  }
+  const from = options.from ?? pinnedEngineVersion();
+  if (from === undefined) {
     throw new ContentCliError(
-      'no-git',
-      'Could not read git status for --changed. Run inside a git working tree.',
+      'unknown-version',
+      'package.json at HEAD pins no exact explico version (a workspace link or a range); pass --from <version>.',
     );
   }
+  const sections = selectMigrationPath(parseMigrationSections(readFileSync(file, 'utf8')), from, to);
+  return {
+    from,
+    to,
+    file: join('docs', 'authoring', 'migrating.md'),
+    sections,
+    tokens: sections.reduce((n, section) => n + section.tokens, 0),
+  };
+}
 
-  const ids = new Set<string>();
-  for (const line of output.split('\n')) {
-    const path = line.trim();
-    if (!path) continue;
-    const slug = path
-      .replace(/^content\/docs\//, '')
-      .replace(/\.checks\.yml$/, '.mdx')
-      .replace(/\.mdx?$/, '');
-    if (!isLessonSlug(slug)) continue;
-    ids.add(slug.replace(/\//g, '.'));
+/** The sections, oldest first, under one line that says how much is coming. */
+export function formatMigrateReport(report: MigrateReport): string {
+  if (report.sections.length === 0) {
+    return `Already at ${report.to}: nothing to migrate from ${report.from}.\n`;
   }
-  return [...ids].sort();
+  const head =
+    `Migrating ${report.from} → ${report.to}: ${report.sections.length} section(s) of ${report.file}, ` +
+    `≈${report.tokens} tokens, oldest first. Apply every one; each ends with the checks to run.\n`;
+  return `${head}\n${report.sections.map((section) => section.markdown).join('\n\n---\n\n')}\n`;
 }
 
-export async function contentCheck(
-  manifest: Manifest,
-  options: {
-    lesson?: string;
-    /** Several lessons, each checked; `lesson` is the one-lesson form. */
-    lessons?: readonly string[];
-    changed?: boolean;
-  },
-): Promise<CheckReport> {
-  let targets: ManifestLesson[];
+// --- content bindings ------------------------------------------------
+
+/*
+ * What a lesson's math binds, span by span, before a build says so: each
+ * glyph and the card it resolves to, how (`canonical`, `family`, `derived`,
+ * `base`, `operator`, or an explicit `\explain` wrap), the wraps the bare
+ * symbol would have resolved without, and every unresolved glyph with where
+ * `content symbol` finds it defined. The same resolver and scope the
+ * completeness gate uses, so what it prints is what the build will do.
+ */
+export interface SpanBinding {
+  readonly token: string;
+  readonly key: string;
+  /** The resolver's match kind; `explicit` for an `\explain` wrap. */
+  readonly how: string;
+}
+
+export interface ExplicitWrap {
+  readonly key: string;
+  readonly inner: string;
+  /** The bare `inner` resolves to exactly this card: the wrap costs tokens and binds nothing new. */
+  readonly redundant: boolean;
+}
+
+export interface UnresolvedGlyph {
+  readonly token: string;
+  readonly suspended?: string;
+  /** Rule N23: indexed entries whose base this bare letter is; none lends it a card. */
+  readonly lenders?: readonly string[];
+  /** Where `content symbol` finds the token defined: exact hits, then near misses. */
+  readonly defined: readonly { readonly tier: SymbolTier; readonly key: string; readonly where: string }[];
+  readonly near: readonly { readonly latex: string; readonly key: string }[];
+}
+
+export interface SpanBindings {
+  readonly bindings: readonly SpanBinding[];
+  readonly wraps: readonly ExplicitWrap[];
+  readonly unresolved: readonly Omit<UnresolvedGlyph, 'defined' | 'near'>[];
+  /** The resolver rejected the span (a KaTeX parse error or a rule it enforces, N13 say); its message. */
+  readonly error?: string;
+}
+
+export interface BindingsSpan extends Omit<SpanBindings, 'unresolved'> {
+  readonly line: number;
+  readonly column: number;
+  readonly display: boolean;
+  readonly latex: string;
+  readonly unresolved: readonly UnresolvedGlyph[];
+}
+
+export interface BindingsReport {
+  readonly lesson: string;
+  readonly file: string;
+  readonly scope: readonly { readonly key: string; readonly notation: string; readonly scope: 'shared' | 'local' }[];
+  readonly spans: readonly BindingsSpan[];
+  readonly counts: {
+    readonly spans: number;
+    readonly bindings: number;
+    readonly unresolved: number;
+    readonly wraps: number;
+    readonly redundantWraps: number;
+    readonly errors: number;
+  };
+}
+
+/**
+ * One span against a scope. Exported for tests and for a caller with a span
+ * of its own (`content equation`).
+ */
+export function spanBindings(
+  latex: string,
+  scope: readonly ScopeEntry[],
+  options: { readonly suspended?: readonly string[]; readonly derive?: boolean } = {},
+): SpanBindings {
+  // D7: `\label{eq:…}` and `\caption{…}` are identity markers, not math KaTeX
+  // parses; the gate strips them the same way.
+  const source = stripEquationLabels(latex);
+  const resolve = (expression: string) =>
+    resolveMathGlyphs(expression, [...scope], {
+      suspended: options.suspended ?? [],
+      derive: options.derive ?? true,
+    }) as {
+      bindings: readonly { key: string; level: string; match: string; token: string }[];
+      unresolved: readonly { token: string; suspended?: string; lenders?: readonly string[] }[];
+      /** Rule N22: a decoration with neither a whole-form card nor an operator entry is unexplained. */
+      decorations: readonly { wholeForm: string | null; operator: string | null }[];
+    };
+  let result: ReturnType<typeof resolve>;
+  try {
+    result = resolve(source);
+  } catch (error) {
+    return { bindings: [], wraps: [], unresolved: [], error: error instanceof Error ? error.message : String(error) };
+  }
+  // The gate's own rule for a wrap that binds nothing new (`explain-redundant`).
+  const redundant = new Set(
+    redundantExplainWraps(source, scope, { suspended: options.suspended ?? [], derive: options.derive ?? true }).map(
+      (wrap) => wrap.index,
+    ),
+  );
+  const wraps: ExplicitWrap[] = explainCalls(source).map((call) => ({
+    key: call.key,
+    inner: call.inner,
+    redundant: redundant.has(call.index),
+  }));
+  return {
+    bindings: result.bindings.map((binding) => ({
+      token: binding.token,
+      key: binding.key,
+      how: binding.level === 'explicit' ? 'explicit' : binding.match,
+    })),
+    wraps,
+    unresolved: result.unresolved.map((item) => ({
+      token: item.token,
+      ...(item.suspended === undefined ? {} : { suspended: item.suspended }),
+      ...(item.lenders === undefined || item.lenders.length === 0 ? {} : { lenders: [...item.lenders] }),
+    })),
+  };
+}
+
+/**
+ * The glyph table a lesson's math resolves against — its bundle: the
+ * `notation.local` entries and the shared cards it introduces — and the
+ * decorations it suspends (rule N22). The same table the completeness gate
+ * builds, read from the manifest instead of rebuilt.
+ */
+function lessonScope(
+  manifest: Manifest,
+  lesson: ManifestLesson,
+  frontmatter: Record<string, unknown>,
+): { readonly records: readonly DefinitionRecord[]; readonly scope: ScopeEntry[]; readonly suspended: string[] } {
+  const ids = new Set(lesson.notation.definitionIds);
+  const records = manifest.notation.definitions.filter((definition) => ids.has(definition.id));
+  const scope: ScopeEntry[] = records.map((definition) => ({
+    key: definition.key,
+    notation: definition.notation,
+    ...(definition.fixedIndex ? { fixedIndex: true as const } : {}),
+  }));
+  const suspend = (frontmatter.notation as { suspend?: { operator?: unknown }[] } | undefined)?.suspend ?? [];
+  const suspended = suspend
+    .map((entry) => entry.operator)
+    .filter((operator): operator is string => typeof operator === 'string');
+  return { records, scope, suspended };
+}
+
+/** Where `content symbol` finds a token defined, for an unresolved glyph; one lookup per token. */
+function symbolLookup(manifest: Manifest) {
+  const lookups = new Map<string, Pick<UnresolvedGlyph, 'defined' | 'near'>>();
+  return (token: string) => {
+    const cached = lookups.get(token);
+    if (cached) return cached;
+    const report = contentSymbol(manifest, token);
+    const found = {
+      defined: [...report.shared, ...report.local, ...report.glosses].map((hit) => ({
+        tier: hit.tier,
+        key: hit.key,
+        where: hit.where,
+      })),
+      near: report.contains.slice(0, 3).map((hit) => ({ latex: hit.latex, key: hit.key })),
+    };
+    lookups.set(token, found);
+    return found;
+  };
+}
+
+export function contentBindings(manifest: Manifest, rawId: string): BindingsReport {
+  const lesson = findLesson(manifest, rawId);
+  const { frontmatter, body } = lessonRaw(lesson);
+  const text = readFileSync(lessonAbsolutePath(lesson), 'utf8');
+  const bodyStart = Math.max(0, text.indexOf(body));
+  const bodyLine = text.slice(0, bodyStart).split('\n').length;
+
+  const { records: scopeRecords, scope, suspended } = lessonScope(manifest, lesson, frontmatter);
+  const lookup = symbolLookup(manifest);
+
+  const spans: BindingsSpan[] = mathSpans(body).map((span) => {
+    const resolved = spanBindings(span.latex, scope, { suspended, derive: true });
+    return {
+      line: bodyLine + span.line - 1,
+      column: span.column,
+      display: body.slice(Math.max(0, span.offset - 2), span.offset) === '$$',
+      latex: span.latex,
+      bindings: resolved.bindings,
+      wraps: resolved.wraps,
+      unresolved: resolved.unresolved.map((item) => ({ ...item, ...lookup(item.token) })),
+      ...(resolved.error === undefined ? {} : { error: resolved.error }),
+    };
+  });
+  spans.sort((a, b) => a.line - b.line || a.column - b.column);
+
+  return {
+    lesson: lesson.id,
+    file: lesson.file,
+    scope: scopeRecords
+      .map((definition) => ({ key: definition.key, notation: definition.notation, scope: definition.kind }))
+      .sort((a, b) => a.key.localeCompare(b.key)),
+    spans,
+    counts: {
+      spans: spans.length,
+      bindings: spans.reduce((n, span) => n + span.bindings.length, 0),
+      unresolved: spans.reduce((n, span) => n + span.unresolved.length, 0),
+      wraps: spans.reduce((n, span) => n + span.wraps.length, 0),
+      redundantWraps: spans.reduce((n, span) => n + span.wraps.filter((wrap) => wrap.redundant).length, 0),
+      errors: spans.filter((span) => span.error !== undefined).length,
+    },
+  };
+}
+
+function latexPreview(latex: string, width = 44): string {
+  const flat = latex.replace(/\s+/g, ' ').trim();
+  return flat.length > width ? `${flat.slice(0, width - 1)}…` : flat;
+}
+
+/** The text form: a counts line, the scope, then one line per span. */
+export function formatBindingsReport(report: BindingsReport): string {
+  const c = report.counts;
+  const lines = [
+    `${report.lesson} — ${report.file}`,
+    `${c.spans} math span(s) · ${c.bindings} binding(s) · ${c.unresolved} unresolved · ${c.wraps} explicit wrap(s)` +
+      (c.wraps > 0 ? `, ${c.redundantWraps} redundant (the bare symbol resolves to the same card)` : '') +
+      (c.errors > 0 ? ` · ${c.errors} span(s) the resolver rejects` : ''),
+    `scope (${report.scope.length}): ${report.scope
+      .map((entry) => `${entry.key} ${entry.notation}${entry.scope === 'local' ? ' (local)' : ''}`)
+      .join(', ') || '(none)'}`,
+  ];
+  for (const span of report.spans) {
+    const where = `L${span.line}:${span.column}`.padEnd(9);
+    const preview = (span.display ? '$$' : '$') + latexPreview(span.latex) + (span.display ? '$$' : '$');
+    const parts: string[] = [];
+    if (span.error !== undefined) parts.push(`REJECTED ${span.error}`);
+    for (const binding of span.bindings) {
+      const explicit = binding.how === 'explicit';
+      const wrap = explicit ? span.wraps.find((w) => w.key === binding.key) : undefined;
+      const note = explicit
+        ? ` [wrap${wrap?.redundant ? ', redundant' : ''}]`
+        : binding.how === 'canonical'
+          ? ''
+          : ` [${binding.how}]`;
+      parts.push(`${binding.token}${explicit ? '⇒' : '→'}${binding.key}${note}`);
+    }
+    for (const item of span.unresolved) {
+      const defined =
+        item.defined.length > 0
+          ? ` — defined: ${item.defined.map((d) => `${d.key} (${d.tier}, ${d.where})`).join('; ')}`
+          : item.near.length > 0
+            ? ` — not defined; near: ${item.near.map((n) => `${n.latex} ${n.key}`).join(', ')}`
+            : ' — not defined anywhere';
+      const why = item.suspended ? ` (suspended ${item.suspended})` : item.lenders ? ` (indexed entries ${item.lenders.join(', ')} lend no card to the bare letter)` : '';
+      parts.push(`${item.token} UNRESOLVED${why}${defined}`);
+    }
+    lines.push(`${where} ${preview.padEnd(48)} ${parts.join(' · ') || '(nothing to bind)'}`);
+  }
+  if (report.spans.length === 0) lines.push('(no math)');
+  return `${lines.join('\n')}\n`;
+}
+
+// --- content equation ------------------------------------------------
+
+/**
+ * One LaTeX string, resolved the way the gate will: against a lesson's
+ * scope, or against every shared card when no lesson is named (the table a
+ * notation entry's body and formula use). The inner loop while drafting:
+ * a few lines out, non-zero exit when the build would refuse the span.
+ */
+export interface EquationReport extends Omit<SpanBindings, 'unresolved'> {
+  readonly latex: string;
+  readonly against: { readonly kind: 'lesson'; readonly lesson: string; readonly cards: number } | { readonly kind: 'shared'; readonly cards: number };
+  readonly unresolved: readonly UnresolvedGlyph[];
+  readonly ok: boolean;
+}
+
+export function contentEquation(
+  manifest: Manifest,
+  latex: string,
+  options: { readonly lesson?: string } = {},
+): EquationReport {
+  const lookup = symbolLookup(manifest);
+  let resolved: SpanBindings;
+  let against: EquationReport['against'];
+  if (options.lesson !== undefined) {
+    const lesson = findLesson(manifest, options.lesson);
+    const { frontmatter } = lessonRaw(lesson);
+    const { scope, suspended } = lessonScope(manifest, lesson, frontmatter);
+    resolved = spanBindings(latex, scope, { suspended, derive: true });
+    against = { kind: 'lesson', lesson: lesson.id, cards: scope.length };
+  } else {
+    const scope: ScopeEntry[] = manifest.notation.definitions
+      .filter((definition) => definition.kind === 'shared')
+      .map((definition) => ({
+        key: definition.key,
+        notation: definition.notation,
+        ...(definition.fixedIndex ? { fixedIndex: true as const } : {}),
+      }));
+    resolved = spanBindings(latex, scope, { suspended: [], derive: false });
+    against = { kind: 'shared', cards: scope.length };
+  }
+  const unresolved = resolved.unresolved.map((item) => ({ ...item, ...lookup(item.token) }));
+  return {
+    latex,
+    against,
+    bindings: resolved.bindings,
+    wraps: resolved.wraps,
+    unresolved,
+    ...(resolved.error === undefined ? {} : { error: resolved.error }),
+    ok: resolved.error === undefined && unresolved.length === 0,
+  };
+}
+
+export function formatEquationReport(report: EquationReport): string {
+  const against =
+    report.against.kind === 'lesson'
+      ? `${report.against.lesson}'s scope (${report.against.cards} cards)`
+      : `every shared card (${report.against.cards})`;
+  const lines = [`$${latexPreview(report.latex, 80)}$   against ${against}`];
+  if (report.error !== undefined) lines.push(`  REJECTED ${report.error}`);
+  if (report.bindings.length > 0) {
+    lines.push(
+      `  ${report.bindings
+        .map((binding) => {
+          const explicit = binding.how === 'explicit';
+          const wrap = explicit ? report.wraps.find((w) => w.key === binding.key) : undefined;
+          const note = explicit ? ` [wrap${wrap?.redundant ? ', redundant' : ''}]` : binding.how === 'canonical' ? '' : ` [${binding.how}]`;
+          return `${binding.token}${explicit ? '⇒' : '→'}${binding.key}${note}`;
+        })
+        .join(' · ')}`,
+    );
+  }
+  for (const item of report.unresolved) {
+    const defined =
+      item.defined.length > 0
+        ? ` — defined: ${item.defined.map((d) => `${d.key} (${d.tier}, ${d.where})`).join('; ')}`
+        : item.near.length > 0
+          ? ` — not defined; near: ${item.near.map((n) => `${n.latex} ${n.key}`).join(', ')}`
+          : ' — not defined anywhere';
+    const why = item.suspended ? ` (suspended ${item.suspended})` : item.lenders ? ` (indexed entries ${item.lenders.join(', ')} lend no card to the bare letter)` : '';
+    lines.push(`  ${item.token} UNRESOLVED${why}${defined}`);
+  }
+  lines.push(
+    report.ok
+      ? 'ok: every glyph binds.'
+      : report.error !== undefined
+        ? 'The build would reject this span.'
+        : `${report.unresolved.length} unresolved glyph(s): the build would fail on this span.`,
+  );
+  return `${lines.join('\n')}\n`;
+}
+
+// --- content move / rename / fix: edits as a plan ----------------------
+
+/*
+ * The refactors a model gets wrong most and reads most for, as deterministic
+ * edits: every one is planned first (`FileEdit`s with the whole text before
+ * and after), shown as a unified diff, and written only on `--write`.
+ */
+export interface FileEdit {
+  /** Course-relative path. */
+  readonly file: string;
+  /** `null` when the file is created. */
+  readonly before: string | null;
+  /** `null` when the file is deleted. */
+  readonly after: string | null;
+}
+
+export interface EditPlan {
+  readonly summary: readonly string[];
+  readonly edits: readonly FileEdit[];
+  /** What to run after writing. */
+  readonly next: readonly string[];
+}
+
+const KEY_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+
+function assertNotationKey(key: string): void {
+  if (!KEY_PATTERN.test(key)) {
+    throw new ContentCliError('invalid-id', `A notation key is lower-case, dot/hyphen separated, got ${JSON.stringify(key)}.`);
+  }
+  const reserved = reservedKeyPrefix(key);
+  if (reserved !== undefined) {
+    throw new ContentCliError(
+      'invalid-id',
+      `A notation key may not start with ${RESERVED_KEY_PREFIXES.join(', ')}: [[${key}]] would be read as a reference to that kind of float.`,
+    );
+  }
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** `[[old]]` and `\explain{old}` become `new`; nothing else is touched. Returns the count. */
+export function rewriteKeyReferences(text: string, oldKey: string, newKey: string): { text: string; count: number } {
+  const k = escapeRegExp(oldKey);
+  let count = 0;
+  const out = text
+    .replace(new RegExp(`\\[\\[\\s*${k}\\s*\\]\\]`, 'g'), () => {
+      count += 1;
+      return `[[${newKey}]]`;
+    })
+    .replace(new RegExp(`\\\\explain(\\s*)\\{${k}\\}`, 'g'), (_m, space: string) => {
+      count += 1;
+      return `\\explain${space}{${newKey}}`;
+    });
+  return { text: out, count };
+}
+
+/** A `seeAlso:` item or a lint-ignore detail naming the key, in a notation file or lint-ignore.yml. */
+function rewriteKeyMentions(text: string, oldKey: string, newKey: string): { text: string; count: number } {
+  const k = escapeRegExp(oldKey);
+  let count = 0;
+  const out = text
+    .replace(new RegExp(`^(\\s*-\\s*)${k}[\\t ]*$`, 'gm'), (_m, lead: string) => {
+      count += 1;
+      return `${lead}${newKey}`;
+    })
+    .replace(new RegExp(`^(\\s*-\\s*[a-z-]+:)${k}(\\s+—)`, 'gm'), (_m, lead: string, tail: string) => {
+      count += 1;
+      return `${lead}${newKey}${tail}`;
+    });
+  return { text: out, count };
+}
+
+/**
+ * Remove one `notation.local` item from a lesson file's text, by key, keeping
+ * the rest of the frontmatter byte for byte. An item runs from its `- key:`
+ * line to the next line indented no deeper than the dash; an emptied list
+ * becomes `local: []`.
+ */
+export function removeLocalItem(text: string, key: string): { text: string; removed: boolean } {
+  const lines = text.split('\n');
+  const start = lines.findIndex((line) => new RegExp(`^(\\s*)-\\s*key:\\s*${escapeRegExp(key)}\\s*$`).test(line));
+  if (start < 0) return { text, removed: false };
+  const indent = /^(\s*)-/.exec(lines[start]!)![1]!.length;
+  let end = start + 1;
+  while (end < lines.length) {
+    const line = lines[end]!;
+    if (line.trim() !== '' && (line.length - line.trimStart().length) <= indent) break;
+    if (line === '---') break;
+    end += 1;
+  }
+  // Trailing blank lines inside the item belong to whatever follows.
+  while (end > start + 1 && lines[end - 1]!.trim() === '') end -= 1;
+  lines.splice(start, end - start);
+  // The list the item sat in: the nearest `local:` above with a smaller indent.
+  let listLine = start - 1;
+  while (listLine >= 0 && !/^\s*local:\s*$/.test(lines[listLine]!)) listLine -= 1;
+  if (listLine >= 0) {
+    const listIndent = lines[listLine]!.length - lines[listLine]!.trimStart().length;
+    let probe = listLine + 1;
+    while (probe < lines.length && lines[probe]!.trim() === '') probe += 1;
+    const nextIndent = probe < lines.length ? lines[probe]!.length - lines[probe]!.trimStart().length : 0;
+    if (probe >= lines.length || lines[probe] === '---' || nextIndent <= listIndent) {
+      lines[listLine] = `${' '.repeat(listIndent)}local: []`;
+    }
+  }
+  return { text: lines.join('\n'), removed: true };
+}
+
+function yamlScalar(value: unknown): string {
+  if (typeof value === 'string') {
+    return /^[A-Za-z0-9][A-Za-z0-9 ,.()/%^_-]*$/.test(value) && !/^(true|false|null|yes|no|on|off)$/i.test(value) && !/^\d/.test(value)
+      ? value
+      : JSON.stringify(value);
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return JSON.stringify(value);
+}
+
+function yamlBlock(value: unknown, indent: number): string[] {
+  const pad = ' '.repeat(indent);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return [`${pad}[]`];
+    return value.flatMap((item) => {
+      if (item !== null && typeof item === 'object') {
+        const inner = yamlBlock(item, indent + 2);
+        return [`${pad}- ${inner[0]!.trimStart()}`, ...inner.slice(1)];
+      }
+      return [`${pad}- ${yamlScalar(item)}`];
+    });
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.entries(value as Record<string, unknown>).flatMap(([k, v]) => {
+      if (v === undefined) return [];
+      if (Array.isArray(v) && v.length === 0) return [`${pad}${k}: []`];
+      if (v !== null && typeof v === 'object') return [`${pad}${k}:`, ...yamlBlock(v, indent + 2)];
+      return [`${pad}${k}: ${yamlScalar(v)}`];
+    });
+  }
+  return [`${pad}${yamlScalar(value)}`];
+}
+
+/**
+ * A shared card's file from a page-local entry's fields, nothing invented: no
+ * body (the glossary shows the meaning; what a reader needs beyond it is the
+ * author's to write, and a placeholder would publish), and the label only
+ * when the entry has one. `domain` is the caller's pick, else the key's
+ * prefix, else `general`.
+ */
+export function sharedCardFromLocal(
+  local: Record<string, unknown>,
+  options: { readonly key: string; readonly fromLesson: string; readonly domain?: string },
+): string {
+  const key = options.key;
+  const domain = options.domain ?? (key.includes('.') ? key.slice(0, key.indexOf('.')) : 'general');
+  const front: Record<string, unknown> = {
+    key,
+    latex: local.latex,
+    ...(local.label === undefined ? {} : { label: local.label }),
+    meaning: local.meaning,
+    ...(local.formula === undefined ? {} : { formula: local.formula }),
+    domain,
+    ...(local.units === undefined ? {} : { units: local.units }),
+    ...(local.dimensionless === undefined ? {} : { dimensionless: local.dimensionless }),
+    ...(local.range === undefined ? {} : { range: local.range }),
+    ...(local.fixedIndex === undefined ? {} : { fixedIndex: local.fixedIndex }),
+    ...(local.reads === undefined ? {} : { reads: local.reads }),
+    sources: local.sources ?? [],
+    seeAlso: local.seeAlso ?? [],
+    ...(local.glosses === undefined ? {} : { glosses: local.glosses }),
+    alignment: local.alignment ?? { kind: 'general', rationale: `Promoted from ${options.fromLesson}'s page-local entry.` },
+    aiAssisted: true,
+  };
+  return `---\n${yamlBlock(front, 0).join('\n')}\n---\n`;
+}
+
+/**
+ * The domain a card promoted under `key` belongs to: the key's prefix when the
+ * course already has that domain, else the one most of the lesson's shared
+ * cards have, else the course's most common, else the prefix or `general`.
+ */
+function promotedDomain(manifest: Manifest, lesson: ManifestLesson, key: string): string {
+  type Shared = Extract<Manifest['notation']['definitions'][number], { kind: 'shared' }>;
+  const shared = manifest.notation.definitions.filter((definition): definition is Shared => definition.kind === 'shared');
+  const prefix = key.includes('.') ? key.slice(0, key.indexOf('.')) : undefined;
+  if (prefix !== undefined && shared.some((definition) => definition.domain === prefix)) return prefix;
+  const mostCommon = (definitions: typeof shared): string | undefined => {
+    const counts = new Map<string, number>();
+    for (const definition of definitions) {
+      if (definition.domain) counts.set(definition.domain, (counts.get(definition.domain) ?? 0) + 1);
+    }
+    return [...counts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0];
+  };
+  const bound = new Set(lesson.notation.definitionIds);
+  return mostCommon(shared.filter((definition) => bound.has(definition.id))) ?? mostCommon(shared) ?? prefix ?? 'general';
+}
+
+function courseTextFiles(): string[] {
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(join(REPOSITORY_ROOT, dir), { withFileTypes: true })) {
+      const rel = `${dir}/${entry.name}`;
+      if (entry.isDirectory()) walk(rel);
+      else if (/\.(mdx?|ya?ml)$/.test(entry.name)) out.push(rel);
+    }
+  };
+  if (existsSync(join(REPOSITORY_ROOT, 'content'))) walk('content');
+  if (existsSync(join(REPOSITORY_ROOT, 'lint-ignore.yml'))) out.push('lint-ignore.yml');
+  return out.sort();
+}
+
+function referenceEdits(oldKey: string, newKey: string, skip: ReadonlySet<string>): { edits: FileEdit[]; count: number } {
+  const edits: FileEdit[] = [];
+  let count = 0;
+  for (const file of courseTextFiles()) {
+    if (skip.has(file)) continue;
+    const before = readFileSync(join(REPOSITORY_ROOT, file), 'utf8');
+    const refs = rewriteKeyReferences(before, oldKey, newKey);
+    const mentions = /^content\/notation\/|^lint-ignore\.yml$/.test(file)
+      ? rewriteKeyMentions(refs.text, oldKey, newKey)
+      : { text: refs.text, count: 0 };
+    const n = refs.count + mentions.count;
+    if (n > 0) {
+      edits.push({ file, before, after: mentions.text });
+      count += n;
+    }
+  }
+  return { edits, count };
+}
+
+/**
+ * `content move <lesson>:<key> [--to <key>]`: a page-local entry becomes a
+ * shared card. Every lesson that declares the key loses its copy (the card
+ * serves them all; copies that differ are reported, the named lesson's text
+ * wins), and with `--to` every `[[key]]` and `\explain{key}` follows.
+ */
+export function planMove(manifest: Manifest, lessonId: string, key: string, options: { readonly to?: string } = {}): EditPlan {
+  const lesson = findLesson(manifest, lessonId);
+  const newKey = options.to ?? key;
+  assertNotationKey(newKey);
+  const target = `content/notation/${newKey}.md`;
+  if (existsSync(join(REPOSITORY_ROOT, target))) {
+    throw new ContentCliError('exists', `${target} already exists; reference it with [[${newKey}]] instead, or move with --to another key.`);
+  }
+  const local = (lesson: ManifestLesson): Record<string, unknown> | undefined => {
+    const { frontmatter } = lessonRaw(lesson);
+    const list = (frontmatter.notation as { local?: Record<string, unknown>[] } | undefined)?.local ?? [];
+    return list.find((entry) => entry.key === key);
+  };
+  const source = local(lesson);
+  if (!source) {
+    throw new ContentCliError('unknown-key', `${lesson.id} declares no notation.local entry ${JSON.stringify(key)}.`);
+  }
+  const summary: string[] = [];
+  const edits: FileEdit[] = [];
+  const domain = promotedDomain(manifest, lesson, newKey);
+  const glyph = typeof source.latex === 'string' ? source.latex.trim() : '';
+  const owner = manifest.notation.definitions.find(
+    (definition) => definition.kind === 'shared' && definition.key !== newKey && definition.notation.trim() === glyph,
+  );
+  if (owner !== undefined) {
+    summary.push(
+      `CAUTION: ${glyph} is already shared card ${owner.key}'s — a second shared card on one glyph is a glyph-unique-in-corpus finding; ` +
+        'a reused letter stays local (rule N4). Write this only if the two cards are meant to share the glyph, and acknowledge the pair.',
+    );
+  }
+  edits.push({ file: target, before: null, after: sharedCardFromLocal(source, { key: newKey, fromLesson: lesson.id, domain }) });
+  summary.push(
+    `${target}: new shared card from ${lesson.id}'s entry${newKey === key ? '' : ` (key ${key} → ${newKey})`}, domain ${domain}` +
+      `; no body yet — add what a glossary reader needs beyond the meaning` +
+      (source.label === undefined ? '; no label in the entry — the card shows one made from the key until you add `label:`' : ''),
+  );
+  const touched = new Set<string>();
+  for (const other of manifest.lessons) {
+    const copy = local(other);
+    if (!copy) continue;
+    const before = readFileSync(lessonAbsolutePath(other), 'utf8');
+    const removed = removeLocalItem(before, key);
+    if (!removed.removed) continue;
+    let after = removed.text;
+    if (newKey !== key) after = rewriteKeyReferences(after, key, newKey).text;
+    edits.push({ file: other.file, before, after });
+    touched.add(other.file);
+    const same = ['latex', 'label', 'meaning', 'units'].every((field) => JSON.stringify(copy[field] ?? null) === JSON.stringify(source[field] ?? null));
+    summary.push(
+      `${other.file}: local entry ${key} removed` +
+        (other.id === lesson.id ? '' : same ? ' (a copy that agreed)' : ' (a copy that DIFFERED — the named lesson\'s text is the card\'s; check it)'),
+    );
+  }
+  if (newKey !== key) {
+    const refs = referenceEdits(key, newKey, touched);
+    edits.push(...refs.edits);
+    if (refs.count > 0) summary.push(`${refs.count} reference(s) to ${key} in ${refs.edits.length} other file(s) now name ${newKey}`);
+  }
+  return { summary, edits, next: ['pnpm validate:content', `pnpm content symbol ${newKey}`] };
+}
+
+/** `content rename <old> <new>`: a shared card's key, everywhere it is named. */
+export function planRename(manifest: Manifest, oldKey: string, newKey: string): EditPlan {
+  assertNotationKey(newKey);
+  const oldFile = `content/notation/${oldKey}.md`;
+  const newFile = `content/notation/${newKey}.md`;
+  if (!existsSync(join(REPOSITORY_ROOT, oldFile))) {
+    const local = manifest.lessons.find((lesson) => {
+      const { frontmatter } = lessonRaw(lesson);
+      return ((frontmatter.notation as { local?: { key?: string }[] } | undefined)?.local ?? []).some((e) => e.key === oldKey);
+    });
+    throw new ContentCliError(
+      'unknown-key',
+      local
+        ? `${oldKey} is a notation.local entry of ${local.id}, not a shared card; promote it with content move ${local.id}:${oldKey} --to ${newKey}.`
+        : `No shared card ${oldKey} (${oldFile}).`,
+    );
+  }
+  if (existsSync(join(REPOSITORY_ROOT, newFile))) throw new ContentCliError('exists', `${newFile} already exists.`);
+  const before = readFileSync(join(REPOSITORY_ROOT, oldFile), 'utf8');
+  const keyLine = /^key:\s*.*$/m.exec(before);
+  if (!keyLine) throw new ContentCliError('unknown-key', `${oldFile} has no key: line.`);
+  const moved = before.slice(0, keyLine.index) + `key: ${newKey}` + before.slice(keyLine.index + keyLine[0].length);
+  const edits: FileEdit[] = [
+    { file: oldFile, before, after: null },
+    { file: newFile, before: null, after: rewriteKeyReferences(moved, oldKey, newKey).text },
+  ];
+  const refs = referenceEdits(oldKey, newKey, new Set([oldFile]));
+  edits.push(...refs.edits);
+  return {
+    summary: [
+      `${oldFile} → ${newFile} (key: ${newKey})`,
+      `${refs.count} reference(s) in ${refs.edits.length} file(s) now name ${newKey}`,
+    ],
+    edits,
+    next: ['pnpm validate:content', `pnpm content symbol ${newKey}`],
+  };
+}
+
+/**
+ * `content fix <lesson>`: the diagnostics with one mechanical repair, applied.
+ * Today: every `\explain{key}{inner}` the gate reports as `explain-redundant`
+ * becomes `inner`.
+ */
+export function planFix(manifest: Manifest, lessonId: string): EditPlan {
+  const lesson = findLesson(manifest, lessonId);
+  const { frontmatter, body } = lessonRaw(lesson);
+  const text = readFileSync(lessonAbsolutePath(lesson), 'utf8');
+  const bodyStart = Math.max(0, text.indexOf(body));
+  const { scope, suspended } = lessonScope(manifest, lesson, frontmatter);
+  const replacements: { start: number; end: number; inner: string; key: string }[] = [];
+  for (const span of mathSpans(body)) {
+    const source = stripEquationLabels(span.latex);
+    // The stripped span keeps every offset of the original only when nothing
+    // was stripped before a wrap; locate each wrap in the original instead.
+    for (const wrap of redundantExplainWraps(source, scope, { suspended, derive: true })) {
+      const needle = `\\explain{${wrap.key}}{${wrap.inner}}`;
+      let at = span.latex.indexOf(needle);
+      while (at >= 0) {
+        replacements.push({ start: bodyStart + span.offset + at, end: bodyStart + span.offset + at + needle.length, inner: wrap.inner, key: wrap.key });
+        at = span.latex.indexOf(needle, at + needle.length);
+      }
+    }
+  }
+  const unique = [...new Map(replacements.map((r) => [r.start, r])).values()].sort((a, b) => b.start - a.start);
+  let after = text;
+  for (const r of unique) after = after.slice(0, r.start) + r.inner + after.slice(r.end);
+  const byKey = new Map<string, number>();
+  for (const r of unique) byKey.set(r.key, (byKey.get(r.key) ?? 0) + 1);
+  return {
+    summary:
+      unique.length === 0
+        ? [`${lesson.file}: nothing to fix`]
+        : [
+            `${lesson.file}: ${unique.length} redundant \\explain wrap(s) unwrapped — ${[...byKey]
+              .sort(([a], [b]) => a.localeCompare(b))
+              .map(([key, n]) => `${key} ×${n}`)
+              .join(', ')}`,
+          ],
+    edits: unique.length === 0 ? [] : [{ file: lesson.file, before: text, after }],
+    next: [`pnpm content check ${lesson.id}`],
+  };
+}
+
+/** `content fix` over several lessons (or every one, `--all`) as one plan: the lessons with nothing to fix are counted, not listed. */
+export function planFixMany(manifest: Manifest, lessonIds: readonly string[]): EditPlan {
+  if (lessonIds.length === 1) return planFix(manifest, lessonIds[0]!);
+  const plans = lessonIds.map((id) => planFix(manifest, id));
+  const fixing = plans.filter((plan) => plan.edits.length > 0);
+  const clean = plans.length - fixing.length;
+  return {
+    summary: [
+      ...fixing.flatMap((plan) => plan.summary),
+      ...(clean > 0 ? [`${clean} lesson(s) with nothing to fix`] : []),
+    ],
+    edits: fixing.flatMap((plan) => plan.edits),
+    next: ['pnpm content check --changed'],
+  };
+}
+
+/** The plan as a unified diff (git's), file by file, under its summary lines. */
+export function renderEditPlan(plan: EditPlan): string {
+  const lines = plan.summary.map((line) => `  ${line}`);
+  const scratch = join(REPOSITORY_ROOT, '.agent', 'content-edits');
+  mkdirSync(scratch, { recursive: true });
+  plan.edits.forEach((edit, index) => {
+    const a = join(scratch, `${index}.before`);
+    const b = join(scratch, `${index}.after`);
+    writeFileSync(a, edit.before ?? '');
+    writeFileSync(b, edit.after ?? '');
+    let diff = '';
+    try {
+      diff = execFileSync('git', ['diff', '--no-index', '--no-color', '--unified=2', '--', a, b], { encoding: 'utf8' });
+    } catch (error) {
+      diff = typeof (error as { stdout?: unknown }).stdout === 'string' ? ((error as { stdout: string }).stdout) : '';
+    }
+    const label = edit.before === null ? `${edit.file} (new file)` : edit.after === null ? `${edit.file} (deleted)` : edit.file;
+    const hunks = diff.split('\n').filter((line) => !/^(diff --git|index |--- |\+\+\+ )/.test(line)).join('\n').trim();
+    lines.push('', `--- ${label}`, hunks || '(no textual change)');
+    unlinkSync(a);
+    unlinkSync(b);
+  });
+  return `${lines.join('\n')}\n`;
+}
+
+/** Write a plan's edits. Returns the files touched. */
+export function applyEditPlan(plan: EditPlan): string[] {
+  const touched: string[] = [];
+  for (const edit of plan.edits) {
+    const path = join(REPOSITORY_ROOT, edit.file);
+    if (edit.after === null) {
+      if (existsSync(path)) unlinkSync(path);
+    } else {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, edit.after);
+    }
+    touched.push(edit.file);
+  }
+  return touched;
+}
+
+// --- content init-agent ----------------------------------------------
+
+/**
+ * The engine's course-facing agent procedures (`docs/course-agent/`): skills,
+ * the `rules-reviewer` agent and the `AGENTS.md` baseline, beside the
+ * installed package or above this module.
+ */
+export function courseAgentDir(): string | undefined {
+  const candidates = [join(REPOSITORY_ROOT, 'node_modules', 'explico', 'docs', 'course-agent')];
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let level = 0; level < 5; level += 1) {
+    candidates.push(join(dir, 'docs', 'course-agent'));
+    dir = dirname(dir);
+  }
+  return candidates.find((candidate) => existsSync(join(candidate, 'AGENTS.md')));
+}
+
+function filesUnder(root: string, rel = ''): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(join(root, rel), { withFileTypes: true })) {
+    const path = rel === '' ? entry.name : `${rel}/${entry.name}`;
+    if (entry.isDirectory()) out.push(...filesUnder(root, path));
+    else out.push(path);
+  }
+  return out.sort();
+}
+
+/**
+ * `content init-agent [--write]`: install or refresh the engine's agent
+ * procedures in this course — every skill under `.claude/skills/`, the
+ * reviewer under `.claude/agents/` — and, only when the course has no
+ * `AGENTS.md`, the baseline one. An existing `AGENTS.md` is never edited;
+ * when it does not point at the engine's guide, the plan says what to add.
+ */
+export function planInitAgent(): EditPlan {
+  const source = courseAgentDir();
+  if (source === undefined) {
+    throw new ContentCliError('unknown-key', 'No docs/course-agent/ beside the engine (node_modules/explico/docs/course-agent).');
+  }
+  const edits: FileEdit[] = [];
+  const summary: string[] = [];
+  const install = (from: string, to: string) => {
+    const after = readFileSync(join(source, from), 'utf8');
+    const target = join(REPOSITORY_ROOT, to);
+    const before = existsSync(target) ? readFileSync(target, 'utf8') : null;
+    if (before === after) return;
+    edits.push({ file: to, before, after });
+    summary.push(`${to}: ${before === null ? 'new' : "differs from the engine's copy"}`);
+  };
+  for (const file of filesUnder(join(source, 'skills'))) install(`skills/${file}`, `.claude/skills/${file}`);
+  for (const file of filesUnder(join(source, 'agents'))) install(`agents/${file}`, `.claude/agents/${file}`);
+  const agents = agentGuideState();
+  if (agents.agentsFile === null) {
+    install('AGENTS.md', 'AGENTS.md');
+  } else if (!agents.linksGuide) {
+    summary.push(
+      `${agents.agentsFile}: left as it is; it does not point at the engine's guide — add a first line such as ` +
+        '"Read node_modules/explico/docs/authoring/agents.md first; this file holds only what is particular to this course." ' +
+        `(the baseline is ${relative(REPOSITORY_ROOT, join(source, 'AGENTS.md'))})`,
+    );
+  }
+  if (edits.length === 0 && summary.length === 0) summary.push('the agent procedures are installed and current');
+  return { summary, edits, next: ['pnpm content status'] };
+}
+
+// --- content rule ----------------------------------------------------
+
+/**
+ * One rule, whole: the catalog entry as this course has it (enforcement,
+ * codes, settings in effect, whether it is on) and the rule page's own
+ * section, example included. About half a thousand tokens where opening the
+ * page costs twenty thousand.
+ */
+export interface RuleReport {
+  readonly id: string;
+  readonly status: 'in-effect' | 'retired' | 'unknown';
+  readonly rule?: RuleInEffect;
+  readonly retired?: RetiredRule;
+  /** The rule page's section for this rule, when the page is at hand. */
+  readonly section?: {
+    readonly file: string;
+    readonly markdown: string;
+    readonly tokens: number;
+  };
+  /** For `unknown`: the IDs this course has, so the caller can pick one. */
+  readonly known: readonly string[];
+}
+
+/**
+ * The engine's `docs/authoring/`: beside the installed package in a course
+ * (`node_modules/explico/docs/authoring`, the path the rules-in-effect page
+ * links), or above this module in the repository and in the package itself.
+ */
+export function authoringDocsDir(): string | undefined {
+  const candidates = [join(REPOSITORY_ROOT, 'node_modules', 'explico', 'docs', 'authoring')];
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let level = 0; level < 5; level += 1) {
+    candidates.push(join(dir, 'docs', 'authoring'));
+    dir = dirname(dir);
+  }
+  return candidates.find((candidate) => existsSync(join(candidate, 'README.md')));
+}
+
+function headingSlug(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/`/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/**
+ * The section of a rule page that `anchor` names: from the heading whose
+ * slug is the anchor (`## N4` → `n4`, `## Reference systems` →
+ * `reference-systems`) to the next heading of the same or a higher level,
+ * trailing rules and blank lines dropped.
+ */
+export function ruleSection(page: string, anchor: string): string | undefined {
+  const lines = page.split('\n');
+  const want = anchor.toLowerCase();
+  const start = lines.findIndex((line) => {
+    const match = /^(#{1,6})\s+(.*\S)\s*$/.exec(line);
+    return match !== null && headingSlug(match[2]!) === want;
+  });
+  if (start < 0) return undefined;
+  const level = /^#+/.exec(lines[start]!)![0].length;
+  let end = lines.findIndex((line, index) => {
+    if (index <= start) return false;
+    const match = /^(#{1,6})\s/.exec(line);
+    return match !== null && match[1]!.length <= level;
+  });
+  if (end < 0) end = lines.length;
+  const body = lines.slice(start, end);
+  while (body.length > 0 && /^(---)?\s*$/.test(body[body.length - 1]!)) body.pop();
+  return body.join('\n');
+}
+
+function ruleSectionFor(rule: RuleInEffect): RuleReport['section'] | undefined {
+  if (rule.source === 'course') return undefined;
+  const dir = authoringDocsDir();
+  if (dir === undefined) return undefined;
+  // `doc` is the link the rules-in-effect page prints (`../node_modules/…/notation.md#n4`);
+  // the pages are flat under docs/authoring, so the basename names the file.
+  const [link, anchor] = rule.doc.split('#');
+  if (!link || !anchor) return undefined;
+  const page = basename(link);
+  const file = join(dir, page);
+  if (!existsSync(file)) return undefined;
+  const markdown = ruleSection(readFileSync(file, 'utf8'), anchor);
+  if (markdown === undefined) return undefined;
+  return { file: join('docs', 'authoring', page), markdown, tokens: estimateTokens(markdown) };
+}
+
+export function contentRule(manifest: Manifest, rawId: string): RuleReport {
+  const id = rawId.trim();
+  const inEffect = rulesInEffect(manifest);
+  const rule = inEffect.find((entry) => entry.id.toLowerCase() === id.toLowerCase());
+  if (rule) {
+    const section = ruleSectionFor(rule);
+    return { id: rule.id, status: 'in-effect', rule, ...(section ? { section } : {}), known: [] };
+  }
+  const retired = retiredRule(id.toUpperCase());
+  if (retired) return { id: retired.id, status: 'retired', retired, known: [] };
+  return { id, status: 'unknown', known: inEffect.map((entry) => entry.id) };
+}
+
+/** The text form of a rule report: the entry's facts, then the page section. */
+export function formatRuleReport(report: RuleReport): string {
+  if (report.status === 'unknown') {
+    return `No rule ${JSON.stringify(report.id)} in this course. Rules in effect: ${report.known.join(', ')}.\n`;
+  }
+  if (report.status === 'retired') {
+    const r = report.retired!;
+    return (
+      `${r.id} · retired ${r.date}${r.into ? `, folded into ${r.into}` : ''}\n` +
+      `  was: ${r.title}\n  ${r.why}\n`
+    );
+  }
+  const rule = report.rule!;
+  const lines = [
+    `${rule.id} · ${rule.title}`,
+    `  ${rule.kind} · elements ${rule.elements.join(', ')} · enforcement ${rule.enforcement} · editions ${String(rule.editions)} · ${rule.enabled ? 'on' : 'off (course.settings.json rules)'}${rule.waivable ? ' · waivable with {/* explico-allow ' + rule.id + ': reason */}' : ''}`,
+    `  codes: ${rule.codes.length > 0 ? rule.codes.join(', ') : '(none)'}`,
+  ];
+  if (Object.keys(rule.settings).length > 0) lines.push(`  settings: ${JSON.stringify(rule.settings)}`);
+  lines.push(`  summary: ${rule.summary}`);
+  if (report.section) {
+    lines.push(`  page: ${report.section.file} (section below, ≈${report.section.tokens} tokens)`, '', report.section.markdown);
+  } else {
+    lines.push(`  page: ${rule.doc}${rule.source === 'course' ? ' (the course\'s own link)' : ' (page not found beside the engine)'}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export function contentContext(
+  manifest: Manifest,
+  rawId: string,
+): ContextReport {
+  const lesson = findLesson(manifest, rawId);
+  const { frontmatter, body } = lessonRaw(lesson);
+
+  const outcomeById = new Map(
+    manifest.competencies.map((competency) => [
+      String(competency.id),
+      String(competency.outcome ?? ''),
+    ]),
+  );
+  const outcomesFor = (ids: readonly string[]) =>
+    ids
+      .filter((id) => outcomeById.has(id))
+      .map((id) => ({ id, outcome: outcomeById.get(id) ?? '' }));
+
+  const sourceById = new Map(
+    manifest.sources.map((source) => [String(source.id), source]),
+  );
+  const citedLocatorsById = new Map<string, string[]>();
+  for (const citation of lesson.citations) {
+    const list = citedLocatorsById.get(citation.id) ?? [];
+    if (citation.locator) list.push(citation.locator);
+    citedLocatorsById.set(citation.id, list);
+  }
+
+  const contextWithoutTokens = {
+    lesson: {
+      id: lesson.id,
+      slug: lesson.slug,
+      file: lesson.file,
+      title: lesson.title,
+      description: lesson.description,
+      teaches: lesson.teaches,
+      requires: lesson.requires,
+      assumptions: lesson.assumptions,
+      since: lesson.since,
+      notationLocal:
+        (frontmatter.notation as { local?: unknown } | undefined)?.local ?? [],
+      body,
+    },
+    taughtOutcomes: outcomesFor(lesson.teaches),
+    prerequisiteOutcomes: outcomesFor(lesson.requires),
+    notation: lesson.notation.definitions.map((definition) => ({
+      key: definition.key,
+      latex: definition.notation,
+      meaning: definition.summary,
+      scope: definition.scope,
+      ...(definition.units === undefined ? {} : { units: definition.units }),
+      ...(definition.formula === undefined
+        ? {}
+        : { formula: definition.formula }),
+    })),
+    equations: lesson.equations.map((equation) => ({ ...equation })),
+    tables: lesson.tables.map((table) => ({ ...table })),
+    figures: lesson.figures.map((figure) => ({ ...figure })),
+    diagrams: lesson.diagrams.map((diagram) => ({ ...diagram })),
+    examples: lesson.examples.map((example) => ({ ...example })),
+    knowledgeChecks: lesson.knowledgeChecks.map((check) => ({ ...check })),
+    sections: lesson.headings.map((heading) => ({ ...heading })),
+    sources: lesson.sources.map((id) => {
+      const record = sourceById.get(id) as Record<string, unknown> | undefined;
+      return {
+        id,
+        title: String(record?.title ?? id),
+        type: String(record?.type ?? 'unknown'),
+        ...(typeof record?.locator === 'string'
+          ? { recordLocator: record.locator }
+          : {}),
+        citedLocators: citedLocatorsById.get(id) ?? [],
+      };
+    }),
+    domainSignatures: domainSignaturesForSection(
+      lesson.slug.split('/')[0] ?? '',
+    ),
+    diagnostics: lessonDiagnostics(manifest, lesson),
+  };
+
+  return {
+    ...contextWithoutTokens,
+    tokens: tokenCounts(contextWithoutTokens),
+  };
+}
+
+// --- content symbol --------------------------------------------------
+
+/*
+ * Where a symbol is already defined, asked before an author declares it
+ * again. Reads the registry the manifest holds: shared cards, page-local
+ * entries (`notation.local`) and glosses (a card's `glosses:`), matched on
+ * the latex as written, a shared card's `aliases`, or the key. A `contains`
+ * list follows for a letter that sits inside a longer notation (`v` in
+ * `v_0`), so a near miss is visible too. Read-only; every list is sorted,
+ * so two runs print the same report.
+ */
+/** Where a hit is defined: a shared card, a lesson's `notation.local`, or a card's gloss. */
+export type SymbolTier = 'shared' | 'local' | 'gloss';
+
+export interface SymbolHit {
+  readonly tier: SymbolTier;
+  readonly key: string;
+  readonly latex: string;
+  readonly label: string;
+  readonly meaning?: string;
+  readonly units?: string;
+  /** How the query matched: the latex as written, an alias, or the key. */
+  readonly matchedBy: 'latex' | 'alias' | 'key';
+  /** shared: the entry file; local: the lesson id; gloss: the owning card. */
+  readonly where: string;
+  /** shared only: the pages (lessons and overview pages) whose bundle binds the card. */
+  readonly boundIn?: readonly string[];
+}
+
+export interface SymbolReport {
+  readonly query: string;
+  readonly shared: readonly SymbolHit[];
+  readonly local: readonly SymbolHit[];
+  readonly glosses: readonly SymbolHit[];
+  /** Entries whose latex contains the query as a glyph, not matched above. */
+  readonly contains: readonly SymbolHit[];
+  /** How many `contains` candidates there were before the list was capped. */
+  readonly containsTotal: number;
+}
+
+const SYMBOL_CONTAINS_CAP = 12;
+
+type DefinitionRecord = Manifest['notation']['definitions'][number];
+
+function byKeyThenWhere(left: SymbolHit, right: SymbolHit): number {
+  return left.key.localeCompare(right.key) || left.where.localeCompare(right.where);
+}
+
+export function contentSymbol(manifest: Manifest, rawQuery: string): SymbolReport {
+  const query = rawQuery.trim();
+  const boundIn = new Map<string, string[]>();
+  for (const bundle of manifest.notation.bundles) {
+    for (const binding of bundle.bindings) {
+      const list = boundIn.get(binding.definitionId) ?? [];
+      if (!list.includes(bundle.lessonId)) list.push(bundle.lessonId);
+      boundIn.set(binding.definitionId, list);
+    }
+  }
+
+  // Every candidate, each with the way it would match, so the exact pass and
+  // the `contains` pass read one list.
+  interface Candidate {
+    readonly hit: Omit<SymbolHit, 'matchedBy'>;
+    readonly aliases: readonly string[];
+  }
+  const candidates: Candidate[] = [];
+  const push = (definition: DefinitionRecord): void => {
+    if (definition.kind === 'shared') {
+      candidates.push({
+        hit: {
+          tier: 'shared',
+          key: definition.key,
+          latex: definition.notation,
+          label: definition.label,
+          meaning: definition.summary,
+          ...(definition.units === undefined ? {} : { units: definition.units }),
+          where: definition.source.file,
+          boundIn: [...(boundIn.get(definition.id) ?? [])].sort(),
+        },
+        aliases: definition.aliases,
+      });
+      for (const gloss of definition.glosses) {
+        candidates.push({
+          hit: {
+            tier: 'gloss',
+            key: gloss.key,
+            latex: gloss.notation,
+            label: gloss.label,
+            ...(gloss.units === undefined ? {} : { units: gloss.units }),
+            where: gloss.ownerKey,
+          },
+          aliases: [],
+        });
+      }
+      return;
+    }
+    candidates.push({
+      hit: {
+        tier: 'local',
+        key: definition.key,
+        latex: definition.notation,
+        label: definition.label,
+        meaning: definition.summary,
+        ...(definition.units === undefined ? {} : { units: definition.units }),
+        where: definition.lessonId,
+      },
+      aliases: [],
+    });
+  };
+  for (const definition of manifest.notation.definitions) push(definition);
+
+  const exact: SymbolHit[] = [];
+  const rest: Candidate[] = [];
+  for (const candidate of candidates) {
+    const { hit, aliases } = candidate;
+    const matchedBy =
+      hit.latex.trim() === query
+        ? 'latex'
+        : aliases.some((alias) => alias.trim() === query)
+          ? 'alias'
+          : hit.key === query
+            ? 'key'
+            : undefined;
+    if (matchedBy) exact.push({ ...hit, matchedBy });
+    else rest.push(candidate);
+  }
+
+  const matcher = glyphMatcher(query);
+  const containsAll = matcher
+    ? rest
+        .filter(({ hit }) => matcher.test(hit.latex))
+        .map(({ hit }): SymbolHit => ({ ...hit, matchedBy: 'latex' }))
+        .sort(byKeyThenWhere)
+    : [];
+
+  const tier = (name: SymbolTier) =>
+    exact.filter((hit) => hit.tier === name).sort(byKeyThenWhere);
+  return {
+    query,
+    shared: tier('shared'),
+    local: tier('local'),
+    glosses: tier('gloss'),
+    contains: containsAll.slice(0, SYMBOL_CONTAINS_CAP),
+    containsTotal: containsAll.length,
+  };
+}
+
+function firstSentence(text: string, limit = 140): string {
+  const sentence = text.trim().split(/(?<=[.!?])\s/)[0] ?? '';
+  return sentence.length > limit ? `${sentence.slice(0, limit - 1)}…` : sentence;
+}
+
+function symbolHitLine(hit: SymbolHit): string {
+  const units = hit.units === undefined ? '' : ` (${hit.units})`;
+  const where =
+    hit.tier === 'shared'
+      ? `${hit.where}; bound on ${hit.boundIn?.length ?? 0} page(s)` +
+        (hit.boundIn && hit.boundIn.length > 0 ? `: ${hit.boundIn.join(', ')}` : '')
+      : hit.tier === 'local'
+        ? `lesson ${hit.where}`
+        : `gloss on ${hit.where}`;
+  const via = hit.matchedBy === 'latex' ? '' : ` [matched by ${hit.matchedBy}]`;
+  return `${hit.key} — ${hit.label}${units} — ${where}${via}`;
+}
+
+/**
+ * The text form of a symbol report: one block per tier, then the near
+ * misses, then one line that counts what was found, worded for the next
+ * step an author takes.
+ */
+export function formatSymbolReport(report: SymbolReport): string {
+  const lines: string[] = [report.query];
+  const section = (title: string, hits: readonly SymbolHit[]): void => {
+    if (hits.length === 0) {
+      lines.push(`  ${title.padEnd(7)} (none)`);
+      return;
+    }
+    for (const [index, hit] of hits.entries()) {
+      lines.push(`  ${(index === 0 ? title : '').padEnd(7)} ${symbolHitLine(hit)}`);
+      if (hit.meaning) lines.push(`          ${firstSentence(hit.meaning)}`);
+    }
+  };
+  section('shared', report.shared);
+  section('local', report.local);
+  section('gloss', report.glosses);
+  if (report.contains.length > 0) {
+    for (const [index, hit] of report.contains.entries()) {
+      lines.push(
+        `  ${(index === 0 ? 'also' : '').padEnd(7)} ${hit.latex} — ${symbolHitLine(hit)}`,
+      );
+    }
+    if (report.containsTotal > report.contains.length) {
+      lines.push(
+        `          … and ${report.containsTotal - report.contains.length} more; --json lists them all`,
+      );
+    }
+  }
+
+  const pageMeanings = report.local.length + report.glosses.length;
+  if (report.shared.length > 0) {
+    const bound = report.shared.reduce((n, hit) => n + (hit.boundIn?.length ?? 0), 0);
+    lines.push(
+      `${report.shared.length} shared card(s), bound on ${bound} page(s). Reference it with [[key]] before the first math use.`,
+    );
+  } else if (pageMeanings > 0) {
+    lines.push(
+      `No shared card. It is a page meaning ${pageMeanings} time(s): ${report.local.length} local, ${report.glosses.length} gloss. A second page that needs the same meaning wants a shared card.`,
+    );
+  } else {
+    lines.push(
+      `Not defined anywhere in this course${report.containsTotal > 0 ? ' (near misses above)' : ''}.`,
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+// --- content check ---------------------------------------------------
+
+/**
+ * A page `content check` checks: a lesson's (its chapter, or a slides-first
+ * lesson's deck), or a deck beside its chapter or a part's, by its page id.
+ */
+export type CheckTarget = Pick<ManifestLesson, 'id' | 'file' | 'assessments'> & {
+  readonly notation: Pick<ManifestLesson['notation'], 'definitionIds'>;
+};
+
+/**
+ * The lesson `rawId` names, or the deck whose page it names: a deck beside
+ * its chapter by its route (`motion/range/slides`), a part's deck by its own
+ * (`motion/slides`).
+ */
+export function findCheckTarget(manifest: Manifest, rawId: string): CheckTarget {
+  const id = normalizeLessonId(rawId);
+  const lesson = manifest.lessons.find((entry) => entry.id === id);
+  if (lesson) return lesson;
+  const deck = (manifest.decks ?? []).find((entry) => entry.pageId === id);
+  if (deck) return { id: deck.pageId, file: deck.file, assessments: [], notation: deck.notation };
+  throw new ContentCliError(
+    'unknown-lesson',
+    `No lesson or deck ${JSON.stringify(id)}. Known ids: ${[
+      ...manifest.lessons.map((entry) => entry.id),
+      ...(manifest.decks ?? []).filter((entry) => entry.chapter !== undefined || entry.part !== undefined).map((entry) => entry.pageId),
+    ].join(', ')}`,
+  );
+}
+
+export interface CheckLessonResult {
+  readonly lesson: string;
+  readonly file: string;
+  readonly ok: boolean;
+  readonly rendered: boolean;
+  readonly diagnostics: readonly CliDiagnostic[];
+}
+
+export interface CheckReport {
+  readonly ok: boolean;
+  readonly lessons: readonly CheckLessonResult[];
+}
+
+async function checkOneLesson(
+  manifest: Manifest,
+  lesson: CheckTarget,
+): Promise<CheckLessonResult> {
+  const manifestDiagnostics = lessonDiagnostics(manifest, lesson);
+  const { frontmatter, body } = lessonSource(
+    readFileSync(lessonAbsolutePath(lesson), 'utf8'),
+  );
+  const render = await renderLesson(manifest, {
+    body,
+    frontmatter,
+    path: lessonAbsolutePath(lesson),
+  });
+
+  const diagnostics = [...manifestDiagnostics, ...render.diagnostics].sort(
+    (a, b) =>
+      a.code.localeCompare(b.code) || a.message.localeCompare(b.message),
+  );
+  return {
+    lesson: lesson.id,
+    file: lesson.file,
+    ok: !diagnostics.some((diagnostic) => diagnostic.severity === 'error'),
+    rendered: render.rendered,
+    diagnostics,
+  };
+}
+
+/** `.mdx` / `.checks.yml` paths that differ from `HEAD`, tracked or not. */
+export function changedLessonIds(): string[] {
+  let output: string;
+  try {
+    const tracked = execFileSync(
+      'git',
+      ['diff', '--name-only', 'HEAD', '--', 'content/docs'],
+      { cwd: REPOSITORY_ROOT, encoding: 'utf8' },
+    );
+    const untracked = execFileSync(
+      'git',
+      ['ls-files', '--others', '--exclude-standard', '--', 'content/docs'],
+      { cwd: REPOSITORY_ROOT, encoding: 'utf8' },
+    );
+    output = `${tracked}\n${untracked}`;
+  } catch {
+    throw new ContentCliError(
+      'no-git',
+      'Could not read git status for --changed. Run inside a git working tree.',
+    );
+  }
+
+  const ids = new Set<string>();
+  for (const line of output.split('\n')) {
+    const path = line.trim();
+    if (!path) continue;
+    const slug = path
+      .replace(/^content\/docs\//, '')
+      .replace(/\.checks\.yml$/, '.mdx')
+      .replace(/\.mdx?$/, '');
+    if (!isLessonSlug(slug)) continue;
+    ids.add(slug.replace(/\//g, '.'));
+  }
+  return [...ids].sort();
+}
+
+export async function contentCheck(
+  manifest: Manifest,
+  options: {
+    lesson?: string;
+    /** Several lessons, each checked; `lesson` is the one-lesson form. */
+    lessons?: readonly string[];
+    changed?: boolean;
+  },
+): Promise<CheckReport> {
+  let targets: CheckTarget[];
   const named = [...(options.lesson ? [options.lesson] : []), ...(options.lessons ?? [])];
   if (options.changed) {
     const ids = changedLessonIds();
@@ -1172,7 +2847,7 @@ export async function contentCheck(
         'content check needs a <lesson> id or --changed.',
       );
     }
-    targets = named.map((id) => findLesson(manifest, id));
+    targets = named.map((id) => findCheckTarget(manifest, id));
   }
 
   const lessons = await Promise.all(
@@ -1265,6 +2940,280 @@ After this lesson, you should be able to:
   };
 }
 
+/** One heading of a chapter, as a deck draft starts from it. */
+interface OutlineDraft {
+  level: 2 | 3;
+  title: string;
+  /** The numbered floats under the heading, as `<Recall ref>` names them. */
+  recalls: string[];
+  /** The first sentence of its first paragraph: the frame's notes. */
+  note: string;
+}
+
+/**
+ * A chapter's `##` and `###` headings, each with the numbered equations,
+ * figures, tables and diagrams under it and its first sentence: what
+ * `content new deck` drafts frames from.
+ */
+function chapterOutline(content: string): OutlineDraft[] {
+  const lines = content.split('\n');
+  const drafts: OutlineDraft[] = [];
+  let fence = false;
+  let paragraph: string[] = [];
+  let pendingTag: string | undefined;
+  const flushParagraph = () => {
+    const current = drafts.at(-1);
+    if (current && current.note === '' && paragraph.length > 0) {
+      const text = paragraph.join(' ');
+      if (!/^\s*[<{:|]/.test(text)) current.note = firstSentence(text);
+    }
+    paragraph = [];
+  };
+  for (const line of lines) {
+    if (/^\s*(```|~~~)/.test(line)) fence = !fence;
+    if (fence) continue;
+    const heading = /^(#{2,3})[ \t]+(.+?)[ \t]*$/.exec(line);
+    if (heading) {
+      flushParagraph();
+      drafts.push({
+        level: heading[1]!.length as 2 | 3,
+        title: heading[2]!.replace(/(?:\s*\[[a-z=-]+\])+\s*$/i, ''),
+        recalls: [],
+        note: '',
+      });
+      continue;
+    }
+    const current = drafts.at(-1);
+    for (const match of line.matchAll(/\\label\{eq:([a-z0-9-]+)\}/g)) current?.recalls.push(`eq-${match[1]}`);
+    // A float's tag may run over several lines: it counts where it opens.
+    if (/<(Figure|Table|Diagram)\b/.test(line)) pendingTag = line;
+    else if (pendingTag !== undefined) pendingTag += ` ${line}`;
+    if (pendingTag !== undefined && pendingTag.includes('>')) {
+      const tag = /<(Figure|Table|Diagram)\b[^>]*?\bid=["']([a-z0-9-]+)["']/.exec(pendingTag);
+      if (tag) {
+        const prefix = tag[1] === 'Figure' ? 'fig' : tag[1] === 'Table' ? 'tab' : 'dia';
+        current?.recalls.push(`${prefix}-${tag[2]}`);
+      }
+      pendingTag = undefined;
+    }
+    if (line.trim() === '') flushParagraph();
+    else if (!/^\s*(import|export)\s/.test(line) && !/^\s*[-*$<{|>]/.test(line)) paragraph.push(line.trim());
+  }
+  flushParagraph();
+  return drafts;
+}
+
+/** A draft frame: its title, a `<Recall>` per float, and its notes. */
+function draftFrame(out: string[], draft: Pick<OutlineDraft, 'title' | 'recalls' | 'note'>): void {
+  out.push(`### ${draft.title}`, '');
+  for (const ref of draft.recalls) out.push(`<Recall ref="${ref}" />`, '');
+  out.push('<Notes>', draft.note || 'What you say on this frame.', '</Notes>', '');
+}
+
+/**
+ * `content new deck <lesson>`: the slide edition of a lesson, as a draft to
+ * rewrite (`docs/authoring/deck.md`). Beside an existing chapter it starts
+ * from the chapter: a `##` section per chapter section, a `###` frame per
+ * subsection (or one for a section without any), a `<Recall>` for each
+ * numbered equation, figure, table and diagram there, and the section's first
+ * sentence in the frame's notes. Without a chapter it is a slides-first
+ * lesson, with the lesson's frontmatter and a skeleton frame.
+ *
+ * `content new deck <part>`, for a part's directory with its page
+ * (`index.mdx`), drafts the part's deck (`<part>/index.deck.mdx`): a
+ * `## <chapter title> [chapter: <name>]` section per chapter, in the order
+ * the tracks read them, and a frame per section of the chapter, with a
+ * `<Recall>` for each float it numbers and its first sentence in the notes.
+ */
+export function scaffoldDeck(rawId: string): Scaffold {
+  const slug = rawId
+    .trim()
+    .replace(/(?:\.deck)?\.mdx?$/, '')
+    .replace(/\./g, '/')
+    .replace(/\/(?:index)?$/, '');
+  if (!slug.includes('/') && ID_PATTERN.test(slug) && partPagePath(slug) !== undefined) {
+    return scaffoldPartDeck(slug);
+  }
+  if (!slug.includes('/') || !isLessonSlug(slug) || slug.split('/').some((part) => !ID_PATTERN.test(part))) {
+    throw new ContentCliError(
+      'invalid-id',
+      `A deck is named by its lesson, <section>/<slug> (or <section>.<slug>), or by a part's directory ` +
+        `with its page (content/docs/<part>/index.mdx), got ${JSON.stringify(rawId)}.`,
+    );
+  }
+  const relPath = `content/docs/${slug}.deck.mdx`;
+  if (existsSync(join(REPOSITORY_ROOT, relPath))) {
+    throw new ContentCliError('exists', `${relPath} already exists; not overwriting.`);
+  }
+  const chapterPath = ['.mdx', '.md']
+    .map((extension) => `content/docs/${slug}${extension}`)
+    .find((path) => existsSync(join(REPOSITORY_ROOT, path)));
+  const titleCase = (slug.split('/').at(-1) ?? slug)
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+
+  if (chapterPath === undefined) {
+    return {
+      path: relPath,
+      contents: `---
+title: ${titleCase}
+description: One sentence on what the student can do after this lesson.
+teaches: []
+assumptions: []
+---
+
+{/* A slides-first lesson: this deck is the lesson. ## opens a section, ### is a frame
+    whose title is the claim it shows (rule D3); the title frame is generated. */}
+
+## The question
+
+### The claim this frame shows
+
+- One line per point the frame makes
+
+<Notes>
+What you say on this frame: the reasoning, the transition, the question to ask.
+</Notes>
+`,
+      companions: [
+        {
+          path: `content/docs/${slug}.checks.yml`,
+          contents: `# Assessment sets for this lesson. Ids resolve against content/assessments/.\n[]\n`,
+        },
+      ],
+    };
+  }
+
+  const raw = readFileSync(join(REPOSITORY_ROOT, chapterPath), 'utf8');
+  const { frontmatter, content } = parseFrontmatter(raw) as {
+    frontmatter?: Record<string, unknown>;
+    content: string;
+  };
+  const data = frontmatter ?? {};
+  const title = typeof data.title === 'string' ? data.title : titleCase;
+  const description = typeof data.description === 'string' ? data.description : '';
+  // The chapter's outline, with every numbered float under the heading it
+  // follows; the frame draft is one per subsection, or per section without one.
+  const drafts = chapterOutline(content);
+
+  const out: string[] = [
+    '---',
+    `title: ${JSON.stringify(title)}`,
+    ...(description ? [`description: ${JSON.stringify(description)}`] : []),
+    '---',
+    '',
+    `{/* Drafted by \`content new deck\` from ${chapterPath}. Rewrite each frame title as the claim it`,
+    '    shows (rule D3), keep to what fits the frame (rule D2), and put what you say in its Notes',
+    '    (rule D4). Each Recall shows the chapter\'s own float, with its number (rule D8). */}',
+    '',
+  ];
+  const frame = (draft: OutlineDraft) => draftFrame(out, draft);
+  drafts.forEach((draft, index) => {
+    if (draft.level === 2) {
+      out.push(`## ${draft.title}`, '');
+      // A section with no subsection is drafted as one frame of its own.
+      if (drafts[index + 1]?.level !== 3 || draft.recalls.length > 0) frame(draft);
+    } else {
+      frame(draft);
+    }
+  });
+  if (drafts.length === 0) {
+    out.push('## The question', '', '### The claim this frame shows', '', '<Notes>', 'What you say on this frame.', '</Notes>', '');
+  }
+  return { path: relPath, contents: `${out.join('\n').trimEnd()}\n`, companions: [] };
+}
+
+/** A part's page, `content/docs/<dir>/index.mdx` (or `.md`), repository-relative, if it has one. */
+function partPagePath(dir: string): string | undefined {
+  return ['.mdx', '.md']
+    .map((extension) => `content/docs/${dir}/index${extension}`)
+    .find((path) => existsSync(join(REPOSITORY_ROOT, path)));
+}
+
+/** The lessons in the order the course's tracks read them (`content/tracks/*.json`, merged). */
+function trackOrder(): string[] {
+  const directory = join(CONTENT_ROOT, 'tracks');
+  if (!existsSync(directory)) return [];
+  const tracks = readdirSync(directory)
+    .filter((name) => name.endsWith('.json'))
+    .sort()
+    .flatMap((name) => {
+      try {
+        const data = JSON.parse(readFileSync(join(directory, name), 'utf8')) as { id?: unknown; lessons?: unknown };
+        return typeof data.id === 'string' && Array.isArray(data.lessons)
+          ? [{ id: data.id, lessons: data.lessons.filter((lesson): lesson is string => typeof lesson === 'string') }]
+          : [];
+      } catch {
+        return [];
+      }
+    });
+  return mergeTrackOrder(tracks);
+}
+
+/** `content new deck <part>`: the part's deck, drafted from its chapters (see {@link scaffoldDeck}). */
+function scaffoldPartDeck(dir: string): Scaffold {
+  const relPath = `content/docs/${dir}/index.deck.mdx`;
+  if (existsSync(join(REPOSITORY_ROOT, relPath))) {
+    throw new ContentCliError('exists', `${relPath} already exists; not overwriting.`);
+  }
+  const pagePath = partPagePath(dir)!;
+  const page = (parseFrontmatter(readFileSync(join(REPOSITORY_ROOT, pagePath), 'utf8')).frontmatter ?? {}) as Record<
+    string,
+    unknown
+  >;
+  const title = typeof page.title === 'string' ? page.title : dir;
+  const description = typeof page.description === 'string' ? page.description : '';
+  // The part's chapters (not its slides-first lessons), as the tracks read them.
+  const rank = new Map(trackOrder().map((lessonId, index) => [lessonId, index]));
+  const chapters = readdirSync(join(DOCS_ROOT, dir))
+    .filter((name) => /\.mdx?$/.test(name) && !/\.deck\.mdx?$/.test(name) && !/^index\.mdx?$/.test(name))
+    .map((name) => ({ name: name.replace(/\.mdx?$/, ''), path: `content/docs/${dir}/${name}` }))
+    .sort(
+      (left, right) =>
+        (rank.get(`${dir}.${left.name}`) ?? Number.POSITIVE_INFINITY) -
+          (rank.get(`${dir}.${right.name}`) ?? Number.POSITIVE_INFINITY) || left.name.localeCompare(right.name),
+    );
+
+  const out: string[] = [
+    '---',
+    `title: ${JSON.stringify(title)}`,
+    ...(description ? [`description: ${JSON.stringify(description)}`] : []),
+    '---',
+    '',
+    `{/* Drafted by \`content new deck\` from the chapters of ${dir}. A section per chapter names it`,
+    '    with [chapter: <name>]: its divider is the chapter\'s address in this deck. Rewrite each frame',
+    '    title as the claim it shows (rule D3), keep to what fits the frame (rule D2), and put what you',
+    '    say in its Notes (rule D4). Each Recall shows the chapter\'s own float, with its number (rule D8). */}',
+    '',
+  ];
+  for (const chapter of chapters) {
+    const { frontmatter, content } = parseFrontmatter(readFileSync(join(REPOSITORY_ROOT, chapter.path), 'utf8')) as {
+      frontmatter?: Record<string, unknown>;
+      content: string;
+    };
+    const chapterTitle = typeof frontmatter?.title === 'string' ? frontmatter.title : chapter.name;
+    out.push(`## ${chapterTitle} [chapter: ${chapter.name}]`, '');
+    // A frame per section, with every float of the section and its subsections.
+    const sections: Pick<OutlineDraft, 'title' | 'recalls' | 'note'>[] = [];
+    for (const draft of chapterOutline(content)) {
+      const current = sections.at(-1);
+      if (draft.level === 2 || current === undefined) {
+        sections.push({ title: draft.title, recalls: [...draft.recalls], note: draft.note });
+      } else {
+        current.recalls.push(...draft.recalls);
+        if (current.note === '') current.note = draft.note;
+      }
+    }
+    if (sections.length === 0) sections.push({ title: 'The claim this frame shows', recalls: [], note: '' });
+    for (const section of sections) draftFrame(out, section);
+  }
+  if (chapters.length === 0) {
+    out.push('## The question', '', '### The claim this frame shows', '', '<Notes>', 'What you say on this frame.', '</Notes>', '');
+  }
+  return { path: relPath, contents: `${out.join('\n').trimEnd()}\n`, companions: [] };
+}
+
 export function scaffoldTerm(rawKey: string): Scaffold {
   const key = rawKey.trim();
   if (!ID_PATTERN.test(key)) {