explico 0.13.0 → 0.14.0

package/dist/compiler/cli.js

@@ -1,7 +1,7 @@
 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,
   parseFrontmatter
@@ -18,14 +18,27 @@ import remarkNotation, {
   createRemarkNotationOptions
 } from "../reference/remark-notation.mjs";
 import remarkShortNote from "../reference/remark-short-note.mjs";
+import {
+  explainCalls,
+  mathSpans,
+  redundantExplainWraps
+} from "../reference/gate-math.js";
+import { resolveMathGlyphs } from "../reference/math-glyphs.mjs";
+import { stripEquationLabels } from "../reference/equations.mjs";
 import { readRenderDiagnostics } from "./render-diagnostics.js";
-import { isLessonSlug, lessonIdFromSlug } from "./lesson-derivation.js";
-import { isCourseRuleId, ownerOf, ELEMENTS } from "../rules/catalog.js";
+import { isLessonSlug, lessonIdFromSlug, mergeTrackOrder } from "./lesson-derivation.js";
+import {
+  isCourseRuleId,
+  ownerOf,
+  retiredRule,
+  ELEMENTS
+} from "../rules/catalog.js";
 import {
   renderRulesInEffect,
   rulesInEffect
 } from "../rules/in-effect.js";
 import { RESERVED_KEY_PREFIXES, reservedKeyPrefix } from "../reference/references.js";
+import { glyphMatcher } from "../reference/consistency.js";
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const DOCS_ROOT = join(CONTENT_ROOT, "docs");
@@ -44,9 +57,17 @@ function diagnosticSeverity(value) {
 function ownerFields(code) {
   const bare = code.slice(code.indexOf(":") + 1);
   const owner = ownerOf(bare);
-  if (owner !== void 0) return { rule: owner.id };
+  if (owner !== void 0) return { rule: owner.id, doc: owner.doc };
   return isCourseRuleId(bare) ? { rule: bare } : {};
 }
+function ownerTag(diagnostic) {
+  if (!diagnostic.rule) return "";
+  return ` [${diagnostic.rule}${diagnostic.doc ? ` \xB7 ${diagnostic.doc}` : ""}]`;
+}
+function formatCliDiagnostic(diagnostic) {
+  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) {
   return { ...diagnostic, ...ownerFields(diagnostic.code) };
 }
@@ -378,6 +399,33 @@ function domainSignaturesForSection(section) {
     signatures: signaturesInFile(path)
   })).filter((entry) => entry.signatures.length > 0);
 }
+const AGENT_GUIDE_MENTION = /docs\/authoring\/agents\.md/;
+function agentGuideState() {
+  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) {
+  const surfaces = [];
+  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))
+  });
+  try {
+    const migration = contentMigrate();
+    if (migration.sections.length > 0) {
+      surfaces.push({ name: `migration ${migration.from} \u2192 ${migration.to}`, tokens: migration.tokens });
+    }
+  } catch {
+  }
+  return surfaces;
+}
 function contentStatus(manifest, rendered = readRenderDiagnostics()) {
   const orphans = manifest.notation.diagnostics.filter((diagnostic) => diagnostic.code === "unused-definition").map((diagnostic) => ({
     code: `notation:${diagnostic.code}`,
@@ -428,8 +476,20 @@ function contentStatus(manifest, rendered = readRenderDiagnostics()) {
   const assessments = new Set(
     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,
@@ -451,6 +511,81 @@ function contentStatus(manifest, rendered = readRenderDiagnostics()) {
     }
   };
 }
+function severityCounts(diagnostics) {
+  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;
+}
+function summarizeDiagnostics(report) {
+  const byCode = /* @__PURE__ */ new Map();
+  const byFile = /* @__PURE__ */ new Map();
+  for (const diagnostic of report.diagnostics) {
+    const codeKey = `${diagnostic.code}\0${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 === void 0 ? {} : { rule: diagnostic.rule },
+        ...diagnostic.doc === void 0 ? {} : { doc: diagnostic.doc },
+        severity: diagnostic.severity,
+        count: 1
+      });
+    }
+    const file = diagnostic.file ?? "(no file)";
+    byFile.set(file, [...byFile.get(file) ?? [], diagnostic]);
+  }
+  const byCount = (key) => (a, b) => 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))
+  };
+}
+function filterDiagnostics(report, filter) {
+  const files = filter.files === void 0 ? void 0 : new Set(filter.files);
+  const diagnostics = report.diagnostics.filter((diagnostic) => {
+    if (filter.code !== void 0 && diagnostic.code !== filter.code && diagnostic.code.slice(diagnostic.code.indexOf(":") + 1) !== filter.code) {
+      return false;
+    }
+    return files === void 0 || diagnostic.file !== void 0 && files.has(diagnostic.file);
+  });
+  return { minimumSeverity: report.minimumSeverity, count: diagnostics.length, diagnostics };
+}
+function formatDiagnosticsSummary(summary, options = {}) {
+  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]}
+`;
+  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(`         \u2026 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")}
+`;
+}
 function equationLink(value) {
   if (value === null || typeof value !== "object") return void 0;
   const { key, href } = value;
@@ -519,6 +654,12 @@ function contentWarnings(manifest, rendered = readRenderDiagnostics()) {
 }
 function parseRulesFilter(input) {
   const filter = {};
+  if (input.edition !== void 0) {
+    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 !== void 0) {
     const elements = input.element.split(",").map((e) => e.trim()).filter(Boolean);
     for (const element of elements) {
@@ -552,6 +693,766 @@ function contentRules(manifest, filter = {}) {
     markdown: renderRulesInEffect(manifest, filter)
   };
 }
+const MIGRATION_HEADING = /^## ([^\n→]+?) → ([^\n]+?)[\t ]*$/;
+function parseMigrationSections(markdown) {
+  const lines = markdown.split("\n");
+  const starts = lines.map((line, index) => ({ index, match: MIGRATION_HEADING.exec(line) })).filter((entry) => entry.match !== null);
+  return starts.map(({ index, match }, position) => {
+    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 ? {} : {}
+    };
+  });
+}
+function versionParts(version) {
+  if (version === "Unreleased") return void 0;
+  const parts = version.split(".").map((part) => part === "x" ? -1 : Number(part));
+  return parts.every((part) => Number.isInteger(part)) ? parts : void 0;
+}
+function versionMatches(pattern, version) {
+  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]);
+}
+function compareVersions(a, b) {
+  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;
+}
+function selectMigrationPath(sections, from, to) {
+  if (compareVersions(from, to) > 0) {
+    throw new ContentCliError(
+      "unknown-version",
+      `--from ${from} is newer than --to ${to}; the guide only goes forward.`
+    );
+  }
+  const path = [];
+  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} \u2192 ${section.to}`).join(", ")}.`
+      );
+    }
+    path.push(next);
+    cursor = next.to;
+  }
+  return path;
+}
+function installedEngineVersion() {
+  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"));
+      if (pkg.name === "explico" && typeof pkg.version === "string") return pkg.version;
+    } catch {
+    }
+  }
+  return void 0;
+}
+function pinnedEngineVersion() {
+  let text;
+  try {
+    text = execFileSync("git", ["show", "HEAD:package.json"], {
+      cwd: REPOSITORY_ROOT,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return void 0;
+  }
+  try {
+    const pkg = JSON.parse(text);
+    const pinned = pkg.dependencies?.explico ?? pkg.devDependencies?.explico;
+    if (typeof pinned !== "string") return void 0;
+    const exact = pinned.replace(/^[\^~=v]/, "");
+    return versionParts(exact) ? exact : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function contentMigrate(options = {}) {
+  const dir = authoringDocsDir();
+  const file = dir === void 0 ? void 0 : join(dir, "migrating.md");
+  if (file === void 0 || !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 === void 0) {
+    throw new ContentCliError("unknown-version", "Could not read the installed engine version; pass --to <version>.");
+  }
+  const from = options.from ?? pinnedEngineVersion();
+  if (from === void 0) {
+    throw new ContentCliError(
+      "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)
+  };
+}
+function formatMigrateReport(report) {
+  if (report.sections.length === 0) {
+    return `Already at ${report.to}: nothing to migrate from ${report.from}.
+`;
+  }
+  const head = `Migrating ${report.from} \u2192 ${report.to}: ${report.sections.length} section(s) of ${report.file}, \u2248${report.tokens} tokens, oldest first. Apply every one; each ends with the checks to run.
+`;
+  return `${head}
+${report.sections.map((section) => section.markdown).join("\n\n---\n\n")}
+`;
+}
+function spanBindings(latex, scope, options = {}) {
+  const source = stripEquationLabels(latex);
+  const resolve = (expression) => resolveMathGlyphs(expression, [...scope], {
+    suspended: options.suspended ?? [],
+    derive: options.derive ?? true
+  });
+  let result;
+  try {
+    result = resolve(source);
+  } catch (error) {
+    return { bindings: [], wraps: [], unresolved: [], error: error instanceof Error ? error.message : String(error) };
+  }
+  const redundant = new Set(
+    redundantExplainWraps(source, scope, { suspended: options.suspended ?? [], derive: options.derive ?? true }).map(
+      (wrap) => wrap.index
+    )
+  );
+  const wraps = 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 === void 0 ? {} : { suspended: item.suspended },
+      ...item.lenders === void 0 || item.lenders.length === 0 ? {} : { lenders: [...item.lenders] }
+    }))
+  };
+}
+function lessonScope(manifest, lesson, frontmatter) {
+  const ids = new Set(lesson.notation.definitionIds);
+  const records = manifest.notation.definitions.filter((definition) => ids.has(definition.id));
+  const scope = records.map((definition) => ({
+    key: definition.key,
+    notation: definition.notation,
+    ...definition.fixedIndex ? { fixedIndex: true } : {}
+  }));
+  const suspend = frontmatter.notation?.suspend ?? [];
+  const suspended = suspend.map((entry) => entry.operator).filter((operator) => typeof operator === "string");
+  return { records, scope, suspended };
+}
+function symbolLookup(manifest) {
+  const lookups = /* @__PURE__ */ new Map();
+  return (token) => {
+    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;
+  };
+}
+function contentBindings(manifest, rawId) {
+  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 = 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 === void 0 ? {} : { 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 !== void 0).length
+    }
+  };
+}
+function latexPreview(latex, width = 44) {
+  const flat = latex.replace(/\s+/g, " ").trim();
+  return flat.length > width ? `${flat.slice(0, width - 1)}\u2026` : flat;
+}
+function formatBindingsReport(report) {
+  const c = report.counts;
+  const lines = [
+    `${report.lesson} \u2014 ${report.file}`,
+    `${c.spans} math span(s) \xB7 ${c.bindings} binding(s) \xB7 ${c.unresolved} unresolved \xB7 ${c.wraps} explicit wrap(s)` + (c.wraps > 0 ? `, ${c.redundantWraps} redundant (the bare symbol resolves to the same card)` : "") + (c.errors > 0 ? ` \xB7 ${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 = [];
+    if (span.error !== void 0) 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) : void 0;
+      const note = explicit ? ` [wrap${wrap?.redundant ? ", redundant" : ""}]` : binding.how === "canonical" ? "" : ` [${binding.how}]`;
+      parts.push(`${binding.token}${explicit ? "\u21D2" : "\u2192"}${binding.key}${note}`);
+    }
+    for (const item of span.unresolved) {
+      const defined = item.defined.length > 0 ? ` \u2014 defined: ${item.defined.map((d) => `${d.key} (${d.tier}, ${d.where})`).join("; ")}` : item.near.length > 0 ? ` \u2014 not defined; near: ${item.near.map((n) => `${n.latex} ${n.key}`).join(", ")}` : " \u2014 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(" \xB7 ") || "(nothing to bind)"}`);
+  }
+  if (report.spans.length === 0) lines.push("(no math)");
+  return `${lines.join("\n")}
+`;
+}
+function contentEquation(manifest, latex, options = {}) {
+  const lookup = symbolLookup(manifest);
+  let resolved;
+  let against;
+  if (options.lesson !== void 0) {
+    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 = manifest.notation.definitions.filter((definition) => definition.kind === "shared").map((definition) => ({
+      key: definition.key,
+      notation: definition.notation,
+      ...definition.fixedIndex ? { fixedIndex: true } : {}
+    }));
+    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 === void 0 ? {} : { error: resolved.error },
+    ok: resolved.error === void 0 && unresolved.length === 0
+  };
+}
+function formatEquationReport(report) {
+  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 !== void 0) 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) : void 0;
+        const note = explicit ? ` [wrap${wrap?.redundant ? ", redundant" : ""}]` : binding.how === "canonical" ? "" : ` [${binding.how}]`;
+        return `${binding.token}${explicit ? "\u21D2" : "\u2192"}${binding.key}${note}`;
+      }).join(" \xB7 ")}`
+    );
+  }
+  for (const item of report.unresolved) {
+    const defined = item.defined.length > 0 ? ` \u2014 defined: ${item.defined.map((d) => `${d.key} (${d.tier}, ${d.where})`).join("; ")}` : item.near.length > 0 ? ` \u2014 not defined; near: ${item.near.map((n) => `${n.latex} ${n.key}`).join(", ")}` : " \u2014 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 !== void 0 ? "The build would reject this span." : `${report.unresolved.length} unresolved glyph(s): the build would fail on this span.`
+  );
+  return `${lines.join("\n")}
+`;
+}
+const KEY_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+function assertNotationKey(key) {
+  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 !== void 0) {
+    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) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function rewriteKeyReferences(text, oldKey, newKey) {
+  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) => {
+    count += 1;
+    return `\\explain${space}{${newKey}}`;
+  });
+  return { text: out, count };
+}
+function rewriteKeyMentions(text, oldKey, newKey) {
+  const k = escapeRegExp(oldKey);
+  let count = 0;
+  const out = text.replace(new RegExp(`^(\\s*-\\s*)${k}[\\t ]*$`, "gm"), (_m, lead) => {
+    count += 1;
+    return `${lead}${newKey}`;
+  }).replace(new RegExp(`^(\\s*-\\s*[a-z-]+:)${k}(\\s+\u2014)`, "gm"), (_m, lead, tail) => {
+    count += 1;
+    return `${lead}${newKey}${tail}`;
+  });
+  return { text: out, count };
+}
+function removeLocalItem(text, key) {
+  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;
+  }
+  while (end > start + 1 && lines[end - 1].trim() === "") end -= 1;
+  lines.splice(start, end - start);
+  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) {
+  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, indent) {
+  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).flatMap(([k, v]) => {
+      if (v === void 0) 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)}`];
+}
+function sharedCardFromLocal(local, options) {
+  const key = options.key;
+  const domain = key.includes(".") ? key.slice(0, key.indexOf(".")) : "general";
+  const front = {
+    key,
+    latex: local.latex,
+    ...local.label === void 0 ? {} : { label: local.label },
+    meaning: local.meaning,
+    ...local.formula === void 0 ? {} : { formula: local.formula },
+    domain,
+    ...local.units === void 0 ? {} : { units: local.units },
+    ...local.dimensionless === void 0 ? {} : { dimensionless: local.dimensionless },
+    ...local.range === void 0 ? {} : { range: local.range },
+    ...local.fixedIndex === void 0 ? {} : { fixedIndex: local.fixedIndex },
+    ...local.reads === void 0 ? {} : { reads: local.reads },
+    sources: local.sources ?? [],
+    seeAlso: local.seeAlso ?? [],
+    ...local.glosses === void 0 ? {} : { glosses: local.glosses },
+    alignment: local.alignment ?? { kind: "general", rationale: `Promoted from ${options.fromLesson}'s page-local entry.` },
+    aiAssisted: true
+  };
+  return `---
+${yamlBlock(front, 0).join("\n")}
+---
+
+Promoted from \`${options.fromLesson}\`'s \`notation.local\`; the meaning above is what that page said. Extend this body with what a glossary reader needs.
+`;
+}
+function courseTextFiles() {
+  const out = [];
+  const walk = (dir) => {
+    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, newKey, skip) {
+  const edits = [];
+  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 mentions2 = /^content\/notation\/|^lint-ignore\.yml$/.test(file) ? rewriteKeyMentions(refs.text, oldKey, newKey) : { text: refs.text, count: 0 };
+    const n = refs.count + mentions2.count;
+    if (n > 0) {
+      edits.push({ file, before, after: mentions2.text });
+      count += n;
+    }
+  }
+  return { edits, count };
+}
+function planMove(manifest, lessonId, key, options = {}) {
+  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 = (lesson2) => {
+    const { frontmatter } = lessonRaw(lesson2);
+    const list = frontmatter.notation?.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 = [];
+  const edits = [];
+  edits.push({ file: target, before: null, after: sharedCardFromLocal(source, { key: newKey, fromLesson: lesson.id }) });
+  summary.push(`${target}: new shared card from ${lesson.id}'s entry${newKey === key ? "" : ` (key ${key} \u2192 ${newKey})`}`);
+  const touched = /* @__PURE__ */ new Set();
+  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 \u2014 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}`] };
+}
+function planRename(manifest, oldKey, newKey) {
+  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?.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 = [
+    { file: oldFile, before, after: null },
+    { file: newFile, before: null, after: rewriteKeyReferences(moved, oldKey, newKey).text }
+  ];
+  const refs = referenceEdits(oldKey, newKey, /* @__PURE__ */ new Set([oldFile]));
+  edits.push(...refs.edits);
+  return {
+    summary: [
+      `${oldFile} \u2192 ${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}`]
+  };
+}
+function planFix(manifest, lessonId) {
+  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 = [];
+  for (const span of mathSpans(body)) {
+    const source = stripEquationLabels(span.latex);
+    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 = /* @__PURE__ */ new Map();
+  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 \u2014 ${[...byKey].sort(([a], [b]) => a.localeCompare(b)).map(([key, n]) => `${key} \xD7${n}`).join(", ")}`
+    ],
+    edits: unique.length === 0 ? [] : [{ file: lesson.file, before: text, after }],
+    next: [`pnpm content check ${lesson.id}`]
+  };
+}
+function renderEditPlan(plan) {
+  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.stdout === "string" ? error.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")}
+`;
+}
+function applyEditPlan(plan) {
+  const touched = [];
+  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;
+}
+function courseAgentDir() {
+  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, rel = "") {
+  const out = [];
+  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();
+}
+function planInitAgent() {
+  const source = courseAgentDir();
+  if (source === void 0) {
+    throw new ContentCliError("unknown-key", "No docs/course-agent/ beside the engine (node_modules/explico/docs/course-agent).");
+  }
+  const edits = [];
+  const summary = [];
+  const install = (from, to) => {
+    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 ? "installed" : "refreshed from the engine"}`);
+  };
+  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 \u2014 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"] };
+}
+function authoringDocsDir() {
+  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) {
+  return text.toLowerCase().replace(/`/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function ruleSection(page, anchor) {
+  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 void 0;
+  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) {
+  if (rule.source === "course") return void 0;
+  const dir = authoringDocsDir();
+  if (dir === void 0) return void 0;
+  const [link, anchor] = rule.doc.split("#");
+  if (!link || !anchor) return void 0;
+  const page = basename(link);
+  const file = join(dir, page);
+  if (!existsSync(file)) return void 0;
+  const markdown = ruleSection(readFileSync(file, "utf8"), anchor);
+  if (markdown === void 0) return void 0;
+  return { file: join("docs", "authoring", page), markdown, tokens: estimateTokens(markdown) };
+}
+function contentRule(manifest, rawId) {
+  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) };
+}
+function formatRuleReport(report) {
+  if (report.status === "unknown") {
+    return `No rule ${JSON.stringify(report.id)} in this course. Rules in effect: ${report.known.join(", ")}.
+`;
+  }
+  if (report.status === "retired") {
+    const r = report.retired;
+    return `${r.id} \xB7 retired ${r.date}${r.into ? `, folded into ${r.into}` : ""}
+  was: ${r.title}
+  ${r.why}
+`;
+  }
+  const rule = report.rule;
+  const lines = [
+    `${rule.id} \xB7 ${rule.title}`,
+    `  ${rule.kind} \xB7 elements ${rule.elements.join(", ")} \xB7 enforcement ${rule.enforcement} \xB7 editions ${String(rule.editions)} \xB7 ${rule.enabled ? "on" : "off (course.settings.json rules)"}${rule.waivable ? " \xB7 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, \u2248${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")}
+`;
+}
 function contentContext(manifest, rawId) {
   const lesson = findLesson(manifest, rawId);
   const { frontmatter, body } = lessonRaw(lesson);
@@ -581,6 +1482,7 @@ function contentContext(manifest, rawId) {
       teaches: lesson.teaches,
       requires: lesson.requires,
       assumptions: lesson.assumptions,
+      since: lesson.since,
       notationLocal: frontmatter.notation?.local ?? [],
       body
     },
@@ -621,6 +1523,154 @@ function contentContext(manifest, rawId) {
     tokens: tokenCounts(contextWithoutTokens)
   };
 }
+const SYMBOL_CONTAINS_CAP = 12;
+function byKeyThenWhere(left, right) {
+  return left.key.localeCompare(right.key) || left.where.localeCompare(right.where);
+}
+function contentSymbol(manifest, rawQuery) {
+  const query = rawQuery.trim();
+  const boundIn = /* @__PURE__ */ new Map();
+  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);
+    }
+  }
+  const candidates = [];
+  const push = (definition) => {
+    if (definition.kind === "shared") {
+      candidates.push({
+        hit: {
+          tier: "shared",
+          key: definition.key,
+          latex: definition.notation,
+          label: definition.label,
+          meaning: definition.summary,
+          ...definition.units === void 0 ? {} : { 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 === void 0 ? {} : { 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 === void 0 ? {} : { units: definition.units },
+        where: definition.lessonId
+      },
+      aliases: []
+    });
+  };
+  for (const definition of manifest.notation.definitions) push(definition);
+  const exact = [];
+  const rest = [];
+  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" : void 0;
+    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 }) => ({ ...hit, matchedBy: "latex" })).sort(byKeyThenWhere) : [];
+  const tier = (name) => 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, limit = 140) {
+  const sentence = text.trim().split(/(?<=[.!?])\s/)[0] ?? "";
+  return sentence.length > limit ? `${sentence.slice(0, limit - 1)}\u2026` : sentence;
+}
+function symbolHitLine(hit) {
+  const units = hit.units === void 0 ? "" : ` (${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} \u2014 ${hit.label}${units} \u2014 ${where}${via}`;
+}
+function formatSymbolReport(report) {
+  const lines = [report.query];
+  const section = (title, hits) => {
+    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} \u2014 ${symbolHitLine(hit)}`
+      );
+    }
+    if (report.containsTotal > report.contains.length) {
+      lines.push(
+        `          \u2026 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")}
+`;
+}
+function findCheckTarget(manifest, rawId) {
+  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 !== void 0 || entry.part !== void 0).map((entry) => entry.pageId)
+    ].join(", ")}`
+  );
+}
 async function checkOneLesson(manifest, lesson) {
   const manifestDiagnostics = lessonDiagnostics(manifest, lesson);
   const { frontmatter, body } = lessonSource(
@@ -686,7 +1736,7 @@ async function contentCheck(manifest, options) {
         "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(
     targets.map((lesson) => checkOneLesson(manifest, lesson))
@@ -754,6 +1804,203 @@ After this lesson, you should be able to:
     ]
   };
 }
+function chapterOutline(content) {
+  const lines = content.split("\n");
+  const drafts = [];
+  let fence = false;
+  let paragraph = [];
+  let pendingTag;
+  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,
+        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]}`);
+    if (/<(Figure|Table|Diagram)\b/.test(line)) pendingTag = line;
+    else if (pendingTag !== void 0) pendingTag += ` ${line}`;
+    if (pendingTag !== void 0 && 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 = void 0;
+    }
+    if (line.trim() === "") flushParagraph();
+    else if (!/^\s*(import|export)\s/.test(line) && !/^\s*[-*$<{|>]/.test(line)) paragraph.push(line.trim());
+  }
+  flushParagraph();
+  return drafts;
+}
+function draftFrame(out, draft) {
+  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>", "");
+}
+function scaffoldDeck(rawId) {
+  const slug = rawId.trim().replace(/(?:\.deck)?\.mdx?$/, "").replace(/\./g, "/").replace(/\/(?:index)?$/, "");
+  if (!slug.includes("/") && ID_PATTERN.test(slug) && partPagePath(slug) !== void 0) {
+    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 === void 0) {
+    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/.
+[]
+`
+        }
+      ]
+    };
+  }
+  const raw = readFileSync(join(REPOSITORY_ROOT, chapterPath), "utf8");
+  const { frontmatter, content } = parseFrontmatter(raw);
+  const data = frontmatter ?? {};
+  const title = typeof data.title === "string" ? data.title : titleCase;
+  const description = typeof data.description === "string" ? data.description : "";
+  const drafts = chapterOutline(content);
+  const out = [
+    "---",
+    `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) => draftFrame(out, draft);
+  drafts.forEach((draft, index) => {
+    if (draft.level === 2) {
+      out.push(`## ${draft.title}`, "");
+      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()}
+`, companions: [] };
+}
+function partPagePath(dir) {
+  return [".mdx", ".md"].map((extension) => `content/docs/${dir}/index${extension}`).find((path) => existsSync(join(REPOSITORY_ROOT, path)));
+}
+function trackOrder() {
+  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"));
+      return typeof data.id === "string" && Array.isArray(data.lessons) ? [{ id: data.id, lessons: data.lessons.filter((lesson) => typeof lesson === "string") }] : [];
+    } catch {
+      return [];
+    }
+  });
+  return mergeTrackOrder(tracks);
+}
+function scaffoldPartDeck(dir) {
+  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 ?? {};
+  const title = typeof page.title === "string" ? page.title : dir;
+  const description = typeof page.description === "string" ? page.description : "";
+  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 = [
+    "---",
+    `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"));
+    const chapterTitle = typeof frontmatter?.title === "string" ? frontmatter.title : chapter.name;
+    out.push(`## ${chapterTitle} [chapter: ${chapter.name}]`, "");
+    const sections = [];
+    for (const draft of chapterOutline(content)) {
+      const current = sections.at(-1);
+      if (draft.level === 2 || current === void 0) {
+        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()}
+`, companions: [] };
+}
 function scaffoldTerm(rawKey) {
   const key = rawKey.trim();
   if (!ID_PATTERN.test(key)) {
@@ -797,20 +2044,54 @@ frontmatter.
 }
 export {
   ContentCliError,
+  applyEditPlan,
+  authoringDocsDir,
   changedLessonIds,
+  contentBindings,
   contentCheck,
   contentContext,
   contentDiagnostics,
+  contentEquation,
+  contentMigrate,
+  contentRule,
   contentRules,
   contentStatus,
+  contentSymbol,
   contentWarnings,
+  courseAgentDir,
   estimateTokens,
+  filterDiagnostics,
+  findCheckTarget,
   findLesson,
+  formatBindingsReport,
+  formatCliDiagnostic,
+  formatDiagnosticsSummary,
+  formatEquationReport,
+  formatMigrateReport,
+  formatRuleReport,
+  formatSymbolReport,
+  installedEngineVersion,
   lessonDiagnostics,
   lessonSource,
   normalizeLessonId,
+  ownerTag,
+  parseMigrationSections,
   parseRulesFilter,
+  pinnedEngineVersion,
+  planFix,
+  planInitAgent,
+  planMove,
+  planRename,
+  removeLocalItem,
+  renderEditPlan,
   renderLesson,
+  rewriteKeyReferences,
+  ruleSection,
+  scaffoldDeck,
   scaffoldLesson,
-  scaffoldTerm
+  scaffoldTerm,
+  selectMigrationPath,
+  sharedCardFromLocal,
+  spanBindings,
+  summarizeDiagnostics
 };