explico 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -14,6 +14,116 @@ under **Breaking** below; a PATCH never breaks.
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-12
+
+### Added
+
+- **Rule D11: a deck is flagged when its chapter changed after it did.**
+  `deck-stale`, an info diagnostic, names a lesson's own deck whose chapter's
+  rule C5 version is newer than the deck's — two files mean the chapter and
+  the deck can drift apart with nothing else to notice it. Scoped to a
+  lesson's own deck; a part's deck covers more than one chapter, so it has
+  none to compare against and is never flagged. `page-versions.ts` gains
+  `deckStaleDiagnostics`; the diagnostic joins `diagnostics.math` beside
+  D1–D10's frame codes. No manifest shape change.
+- **`content help <verb> [--json]`: each verb's contract, machine-readable.**
+  `content help symbol` prints the verb's usage, what it is for, its flags,
+  what it writes, when it exits 1, and the shape of its `--json` as a tree of
+  named types; `--json` prints the same with a self-contained JSON Schema
+  (draft 2020-12). `content help --json` prints the whole reference. The verb
+  table is one source, `src/compiler/cli-verbs.ts` (`CONTENT_VERBS`, from which
+  `CONTENT_USAGE` is now derived, every line ending in `[--json]`);
+  `scripts/agent/gen-cli.mjs` reads the TypeScript report types with the
+  compiler API and writes `docs/authoring/cli-reference.json` and
+  `docs/authoring/cli.md`, both shipped, `--check` in verify and CI. New
+  module `explico/compiler/cli-reference` (`loadCliReference`, `verbHelp`,
+  `schemaOf`, `formatVerbHelp`, `cliReferenceMarkdown`, and
+  `jsonShapeErrors`, which checks a value against one of the schemas).
+  `cli-main` exports the named `--json` types its verbs print beside the
+  reports: `RulesJson`, `EditPlanJson`, `NewJson`, `ErrorJson`.
+- **`content verify [--e2e] [--force]`: a course's one gate before handing
+  work back.** `validate:content` → `content check --changed` → `astro check`
+  (skipped, by name, when `@astrojs/check` is not installed) → the course's
+  `test` script → `astro build`, and with `--e2e` its `test:e2e` script (or
+  `playwright test`). Each step is its own process with its whole output in
+  `node_modules/.cache/explico/verify/<step>.log`; the run prints one line per
+  step, the tail of each failed step's log, and exits 1 on a failure. A pass
+  records the tree it left (git HEAD, the diff against it, the untracked
+  files), and a rerun on the same tree that asks for no more answers from the
+  record without running anything. New module `explico/compiler/cli-verify`
+  (`runVerify`, `VerifyReport`).
+- `runContentCli` takes an optional fifth argument, a manifest already
+  compiled for the course, so a test running many verbs compiles once.
+- **`content release [major|minor|patch] [--write]`: a content release in
+  every course.** `## [Unreleased]` in `content/CHANGELOG.md` becomes a dated
+  `## [x.y.z]` heading and `about.version` becomes `x.y.z` (rule C3), shown as
+  a diff and written with `--write`, like `move`, `rename` and `fix`; the bump
+  defaults to what the section's headings imply (rule C2), and the date is the
+  local one. It was the playground's own `scripts/release-content.ts`, which
+  the shipped `release-content` skill called as `pnpm release:content` in
+  courses that never had it. The playground's `release:content` script is now
+  `content release --write`. New module `explico/compiler/content-release`
+  (`releaseEdit`, `planContentRelease`); new error code `no-changelog`.
+
+### Changed
+
+- `content init-agent` says `new` or `differs from the engine's copy` for each
+  file, where a dry run used to say `installed`; after `--write` every edit
+  verb prints what to run next.
+- `content status` lists at most six of the pages with unreleased changes and
+  counts the rest; `content context` says how many of a lesson's diagnostics
+  sit in its own file and how many in the shared cards it shows (the first is
+  what `diagnostics --lesson` lists).
+- The shipped procedures (`docs/course-agent/`) survive a course's prettier:
+  no inline code span crosses a line break, which prettier re-indented out of
+  its list item. `gen-map --check` fails on one.
+- `migrating.md`, 0.13.1 → 0.14.0, corrected where upgrading
+  credit-and-derivatives found it wrong: the patch goes before `pnpm add`
+  (pnpm refuses with `ERR_PNPM_UNUSED_PATCH`) and its entry may sit in
+  `pnpm-workspace.yaml`; pnpm 11's `minimumReleaseAgeExclude`; a course that
+  commits `build/resolution/` fails its first run after the upgrade; stale
+  `lint-ignore.yml` lines and a course's own tier guidance (step 20); the 404
+  page without a raw `<div>` (step 24); tests comparing sidebar and page
+  colours (step 25). Upgrading time-series added two more: pnpm can instead
+  stop with `ERR_PNPM_NO_MATURE_MATCHING_VERSION` (step 1), and the first
+  `content/versions.json` goes in before the upgrade's own changelog bullet,
+  or every page reads "not yet released" (step 10).
+- `content fix` takes several lessons, or `--all`, as one plan: the lessons
+  with nothing to fix are counted, not listed. A course upgrading to 0.14.0
+  can have a thousand redundant `\explain` wraps (data-science-I: 1193).
+- `content check` lists a lesson's errors and warnings line by line and
+  counts its info by code, with the command that lists them; `--json` is
+  unchanged.
+- `definition-repeated` on a local entry whose glyph a shared card already
+  owns no longer says "move one copy to `content/notation/`": promoting it
+  would put two shared cards on one glyph. It says the entry is a reused
+  letter (rule N4) and how to acknowledge the copies; `content move` prints a
+  caution when the glyph is taken (time-series: 9 of its 34).
+- `dia-too-wide` on `<CurriculumMap>`'s competency graph names the map's own
+  props (`graph="per-part"`, `direction`, `warnAboveWidth`) instead of a node
+  `width` and a shorter label, which the author does not write there.
+- The rules-in-effect page says the course's `rules` and `courseRules` live
+  in `course.settings.json` or `course.config.ts`, not only the first.
+
+### Fixed
+
+- `content move` wrote the new card a placeholder body ("Extend this body
+  with what a glossary reader needs."), which the glossary would publish, and
+  `domain: general` for a key without a prefix. The card now has no body, its
+  domain is the key's prefix when the course has that domain, else the one
+  most of the lesson's cards have; the plan says that the body is the
+  author's to write, and when the entry had no `label`.
+- `validate:content`'s run log recorded each consistency warning
+  (`definition-repeated`, `glyph-unique-in-corpus`, …) at INFO and their
+  one-line digest as the only WARNING, so its `Run log: (… warning(s))` count
+  disagreed with `content status`. Each finding is recorded at WARNING now,
+  the digest at INFO.
+- `ContextReport`'s `equations`, `tables`, `figures` and `diagrams` are typed
+  `ManifestLessonFloat[]`: `content context --json` always printed each
+  float's `short` and `caption`, which the type left out. The playground's
+  new `--json` contract test runs every read-only verb against the schemas and
+  caught it.
+
 ## [0.14.0] - 2026-10-11
 
 ### Breaking
@@ -4323,7 +4433,8 @@ n starts its row, and the panel hung from the button's end,
   system with its completeness gate, the curriculum-graph validator, the
   Astro/Starlight UI, the LMS / session / analytics seams, and the `content` CLI.
 
-[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.14.0...HEAD
+[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/danieltuzes/explico/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/danieltuzes/explico/compare/v0.13.1...v0.14.0
 [0.13.1]: https://github.com/danieltuzes/explico/compare/v0.13.0...v0.13.1
 [0.13.0]: https://github.com/danieltuzes/explico/compare/v0.12.0...v0.13.0

package/dist/compiler/cli-main.d.ts

@@ -1,9 +1,60 @@
+import { EditPlan, ContentCliCode, RulesReport } from './cli.js';
+export { CONTENT_USAGE } from './cli-verbs.js';
 import { C as CourseConfig } from '../course-config-BLtIdkei.js';
+import { Manifest } from './manifest.js';
+import '../reference/types.js';
+import '../reference/gate-math.js';
+import './render-diagnostics.js';
 import '../rules/catalog.js';
+import '../rules/in-effect.js';
 import '../rules/course-rules.js';
+import '../curriculum/validation.js';
+import '../reference/consistency.js';
+import './collections.js';
+import '../reference/gate-retired-keys.js';
+import '../reference/lint-ignore.js';
+import '../reference/equations-validate.js';
+import '../reference/tables-validate.js';
+import '../reference/keyed-float-validate.js';
+import '../reference/figures-validate.js';
+import '../reference/diagrams-validate.js';
+import '../reference/examples-validate.js';
+import '../reference/folds-validate.js';
+import '../reference/knowledge-checks-validate.js';
+import '../reference/raw-floats-validate.js';
+import '../reference/lab-katex-validate.js';
+import '../reference/mixed-content.js';
+import '../reference/gloss.js';
+import '../rules/waivers.js';
+import './knowledge-version.js';
+import './page-versions.js';
+import './decks.js';
+import '../reference/decks-validate.js';
+import '../reference/deck-source.js';
+import './lesson-derivation.js';
 
-/** The usage text `content help` prints; `scripts/agent/gen-map.mjs` lists the verbs from it. */
-declare const CONTENT_USAGE = "Usage:\n  pnpm content status\n  pnpm content diagnostics [info|warning|error] [--all | --code <c> | --lesson <id> | --changed] [--json]\n  pnpm content warnings [--json]\n  pnpm content context <lesson> [--json]\n  pnpm content equation \"<latex>\" [--lesson <id>] [--json]\n  pnpm content bindings <lesson> [--json]\n  pnpm content symbol <latex | key> [--json]\n  pnpm content check <lesson | deck>\u2026 [--changed] [--json]\n  pnpm content rule <ID> [--json]\n  pnpm content migrate [--from <version>] [--to <version>] [--json]\n  pnpm content rules [--element <e>[,<e>]] [--enforcement script|partial|guide|locked] [--edition chapter|deck] [--json]\n  pnpm content move <lesson>:<key> [--to <key>] [--write]\n  pnpm content rename <old> <new> [--write]\n  pnpm content fix <lesson> [--write]\n  pnpm content new lesson <id>\n  pnpm content new deck <lesson | part>\n  pnpm content new term <key>\n  pnpm content init-agent [--write]";
+/** `--json` of `rules`: the report without its Markdown page. */
+type RulesJson = Pick<RulesReport, 'filter' | 'count' | 'rules'>;
+/** `--json` of `move`, `rename`, `fix` and `init-agent`: the plan, and whether `--write` applied it. */
+type EditPlanJson = EditPlan & {
+    /** True when `--write` applied the edits; false for a dry run. */
+    readonly written: boolean;
+};
+/** `--json` of `new lesson`, `new deck` and `new term`. */
+interface NewJson {
+    readonly ok: true;
+    /** Course-relative paths of the files it created. */
+    readonly created: readonly string[];
+}
+/** `--json` of any verb whose run failed: a stable code and a message, never a stack. */
+interface ErrorJson {
+    readonly ok: false;
+    readonly error: {
+        /** `internal` for an unexpected throw; every other code is stable. */
+        readonly code: ContentCliCode | 'internal';
+        readonly message: string;
+    };
+}
 interface ContentArgs {
     readonly command: string;
     readonly positionals: readonly string[];
@@ -26,6 +77,10 @@ interface ContentArgs {
     readonly to?: string;
     /** `--write`: apply a planned edit instead of only showing its diff. */
     readonly write: boolean;
+    /** `--e2e`: `verify` runs the browser tests too. */
+    readonly e2e: boolean;
+    /** `--force`: `verify` runs even on a tree its last pass covered. */
+    readonly force: boolean;
 }
 declare function parseContentArgs(argv: readonly string[]): ContentArgs;
 /** Where a run prints; the process streams by default, a buffer in a test. */
@@ -38,6 +93,8 @@ interface ContentIo {
  * success, 1 on a usage error, a `ContentCliError`, a check that failed, or
  * an unexpected throw (reported by message, never a stack).
  */
-declare function runContentCli(courseConfig: CourseConfig, argv?: readonly string[], io?: ContentIo): Promise<number>;
+declare function runContentCli(courseConfig: CourseConfig, argv?: readonly string[], io?: ContentIo, 
+/** A manifest already compiled for this course, reused instead of compiling one: a test running many verbs compiles once. */
+compiled?: Manifest): Promise<number>;
 
-export { CONTENT_USAGE, type ContentArgs, type ContentIo, parseContentArgs, runContentCli };
+export { type ContentArgs, type ContentIo, type EditPlanJson, type ErrorJson, type NewJson, type RulesJson, parseContentArgs, runContentCli };

package/dist/compiler/cli-main.js

@@ -26,7 +26,7 @@ import {
   formatSymbolReport,
   ownerTag,
   parseRulesFilter,
-  planFix,
+  planFixMany,
   planInitAgent,
   planMove,
   planRename,
@@ -36,26 +36,11 @@ import {
   scaffoldTerm,
   summarizeDiagnostics
 } from "./cli.js";
+import { formatVerbHelp, loadCliReference, verbHelp } from "./cli-reference.js";
+import { CONTENT_USAGE } from "./cli-verbs.js";
+import { planContentRelease } from "./content-release.js";
+import { formatVerifyReport, formatVerifyStep, runVerify } from "./cli-verify.js";
 import { compileManifest } from "./manifest.js";
-const CONTENT_USAGE = `Usage:
-  pnpm content status
-  pnpm content diagnostics [info|warning|error] [--all | --code <c> | --lesson <id> | --changed] [--json]
-  pnpm content warnings [--json]
-  pnpm content context <lesson> [--json]
-  pnpm content equation "<latex>" [--lesson <id>] [--json]
-  pnpm content bindings <lesson> [--json]
-  pnpm content symbol <latex | key> [--json]
-  pnpm content check <lesson | deck>\u2026 [--changed] [--json]
-  pnpm content rule <ID> [--json]
-  pnpm content migrate [--from <version>] [--to <version>] [--json]
-  pnpm content rules [--element <e>[,<e>]] [--enforcement script|partial|guide|locked] [--edition chapter|deck] [--json]
-  pnpm content move <lesson>:<key> [--to <key>] [--write]
-  pnpm content rename <old> <new> [--write]
-  pnpm content fix <lesson> [--write]
-  pnpm content new lesson <id>
-  pnpm content new deck <lesson | part>
-  pnpm content new term <key>
-  pnpm content init-agent [--write]`;
 const VALUED_FLAGS = ["element", "enforcement", "edition", "code", "lesson", "from", "to"];
 function parseContentArgs(argv) {
   const positionals = [];
@@ -64,6 +49,8 @@ function parseContentArgs(argv) {
   let changed = false;
   let all = false;
   let write = false;
+  let e2e = false;
+  let force = false;
   const valued = new RegExp(`^--(${VALUED_FLAGS.join("|")})(?:=(.*))?$`);
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
@@ -72,6 +59,8 @@ function parseContentArgs(argv) {
     else if (arg === "--changed") changed = true;
     else if (arg === "--all") all = true;
     else if (arg === "--write") write = true;
+    else if (arg === "--e2e") e2e = true;
+    else if (arg === "--force") force = true;
     else if (match) values[match[1]] = match[2] ?? argv[i += 1] ?? "";
     else positionals.push(arg);
   }
@@ -82,9 +71,15 @@ function parseContentArgs(argv) {
     changed,
     all,
     write,
+    e2e,
+    force,
     ...values
   };
 }
+function diagnosticsWhere(diagnostics, file) {
+  const own = diagnostics.filter((diagnostic) => diagnostic.file === file).length;
+  return own === diagnostics.length ? "" : ` (${own} in ${file}, ${diagnostics.length - own} in the shared cards it shows)`;
+}
 const PROCESS_IO = {
   out: (text) => process.stdout.write(text),
   err: (text) => process.stderr.write(text)
@@ -109,12 +104,12 @@ function writeScaffold(scaffold) {
   }
   return written;
 }
-async function runContentCli(courseConfig, argv = process.argv.slice(2), io = PROCESS_IO) {
+async function runContentCli(courseConfig, argv = process.argv.slice(2), io = PROCESS_IO, compiled) {
   const args = parseContentArgs(argv);
   const json = (value) => io.out(`${JSON.stringify(value, null, 2)}
 `);
   try {
-    return await dispatch(courseConfig, args, io, json);
+    return await dispatch(courseConfig, args, io, json, compiled);
   } catch (error) {
     const code = error instanceof Usage || error instanceof ContentCliError ? error.code : "internal";
     const message = error instanceof Error ? error.message : String(error);
@@ -124,13 +119,40 @@ async function runContentCli(courseConfig, argv = process.argv.slice(2), io = PR
     return 1;
   }
 }
-async function dispatch(courseConfig, args, io, json) {
+async function dispatch(courseConfig, args, io, json, compiled) {
   const out = io.out;
-  if (args.command === "" || args.command === "help" || args.command === "--help") {
+  if (args.command === "" || args.command === "--help" || args.command === "help" && args.positionals.length === 0 && !args.json) {
     out(`${CONTENT_USAGE}
 `);
     return 0;
   }
+  if (args.command === "help") {
+    if (args.positionals.length > 1) usage("usage", `content help takes one verb; got ${args.positionals.join(" ")}.`);
+    const reference = loadCliReference();
+    const [word] = args.positionals;
+    if (word === void 0) {
+      json(reference);
+      return 0;
+    }
+    const help = verbHelp(reference, word);
+    if (args.json) json(help);
+    else out(formatVerbHelp(reference, help));
+    return 0;
+  }
+  if (args.command === "verify") {
+    if (args.positionals.length > 0) usage("usage", `content verify takes no argument; got ${args.positionals.join(" ")}.`);
+    if (!args.json) out(`verify (${args.e2e ? "with" : "without"} e2e; whole output under node_modules/.cache/explico/verify/)
+`);
+    const report = runVerify({
+      e2e: args.e2e,
+      force: args.force,
+      ...args.json ? {} : { onStep: (event) => event.phase === "end" && out(formatVerifyStep(event.step)) }
+    });
+    if (args.json) json(report);
+    else out(report.cached ? formatVerifyReport(report) : `
+${formatVerifyReport(report)}`);
+    return report.ok ? 0 : 1;
+  }
   if (args.command === "new") {
     const [kind, id] = args.positionals;
     if (kind !== "lesson" && kind !== "deck" && kind !== "term") {
@@ -151,18 +173,28 @@ ${written.map((p) => `  ${p}`).join("\n")}
   if (["status", "rules", "warnings"].includes(args.command) && args.positionals.length > 0) {
     usage("usage", `content ${args.command} takes no <lesson>; got ${args.positionals.join(" ")}.`);
   }
-  if (args.command === "init-agent") {
-    if (args.positionals.length > 0) usage("usage", `content init-agent takes no argument; got ${args.positionals.join(" ")}.`);
-    const plan = planInitAgent();
+  if (args.command === "init-agent" || args.command === "release") {
+    let plan;
+    if (args.command === "init-agent") {
+      if (args.positionals.length > 0) usage("usage", `content init-agent takes no argument; got ${args.positionals.join(" ")}.`);
+      plan = planInitAgent();
+    } else {
+      if (args.positionals.length > 1) usage("usage", `content release takes one of major, minor, patch; got ${args.positionals.join(" ")}.`);
+      plan = planContentRelease(args.positionals[0]);
+    }
     if (args.json) json({ ...plan, written: args.write });
     else out(renderEditPlan(plan));
     if (plan.edits.length === 0) return 0;
+    const next = plan.next.length > 0 ? plan.next.join(" \xB7 ") : "";
     if (args.write) {
       const touched = applyEditPlan(plan);
       if (!args.json) out(`
-written: ${touched.join(", ")}
+written: ${touched.join(", ")}${next === "" ? "" : `
+next: ${next}`}
+`);
+    } else if (!args.json) out(`
+dry run: nothing written. Add --write to apply${next === "" ? "" : `; then ${next}`}.
 `);
-    } else if (!args.json) out("\ndry run: nothing written. Add --write to install.\n");
     return 0;
   }
   if (args.command === "migrate") {
@@ -196,7 +228,7 @@ written: ${touched.join(", ")}
     usage("unknown-command", `Unknown command "${args.command}".
 ${CONTENT_USAGE}`);
   }
-  const manifest = await compileManifest(courseConfig);
+  const manifest = compiled ?? await compileManifest(courseConfig);
   switch (args.command) {
     case "status": {
       const report = contentStatus(manifest);
@@ -206,9 +238,11 @@ ${CONTENT_USAGE}`);
       }
       const c = report.counts;
       const unreleased = report.pageVersions.unreleased;
+      const UNRELEASED_SHOWN = 6;
+      const unreleasedList = unreleased.length <= UNRELEASED_SHOWN ? unreleased.join(", ") : `${unreleased.slice(0, UNRELEASED_SHOWN).join(", ")}, \u2026 ${unreleased.length - UNRELEASED_SHOWN} more in --json`;
       out(
         `Knowledge version ${report.knowledgeVersion}
-Page versions: ${report.pageVersions.tracked} page(s) tracked, ${unreleased.length} with changes not yet released${unreleased.length > 0 ? ` (${unreleased.join(", ")})` : ""}
+Page versions: ${report.pageVersions.tracked} page(s) tracked, ${unreleased.length} with changes not yet released${unreleased.length > 0 ? ` (${unreleasedList})` : ""}
 Lessons ${c.lessons} \xB7 competencies ${c.competencies} \xB7 assessments ${c.assessments} \xB7 sources ${c.sources} \xB7 tracks ${c.tracks} \xB7 notation ${c.notationDefinitions} \xB7 keyed equations ${c.keyedEquations} \xB7 tables ${c.keyedTables} \xB7 figures ${c.keyedFigures} \xB7 diagrams ${c.keyedDiagrams} \xB7 example sets ${c.keyedExamples}
 Diagnostics: ${report.diagnostics.errors} error(s), ${report.diagnostics.warnings} warning(s), ${report.diagnostics.infos} info
 Orphans: ${report.orphans.length}
@@ -232,9 +266,8 @@ Agent guide: ${report.agentGuide.agentsFile === null ? "no AGENTS.md \u2014 `pnp
         if (!oldKey || !newKey || extra.length > 0) usage("usage", "content rename needs <old> <new>.");
         plan = planRename(manifest, oldKey, newKey);
       } else {
-        const [lesson, ...extra] = args.positionals;
-        if (!lesson || extra.length > 0) usage("usage", "content fix needs one <lesson> id.");
-        plan = planFix(manifest, lesson);
+        if (args.all === args.positionals.length > 0) usage("usage", "content fix needs <lesson> ids, or --all for every lesson.");
+        plan = planFixMany(manifest, args.all ? manifest.lessons.map((lesson) => lesson.id) : args.positionals);
       }
       if (args.json) json({ ...plan, written: args.write });
       else out(renderEditPlan(plan));
@@ -329,7 +362,7 @@ teaches: ${report.lesson.teaches.join(", ") || "(none)"}
 requires: ${report.lesson.requires.join(", ") || "(none)"}
 notation: ${report.notation.map((n) => n.key).join(", ") || "(none)"}
 sources: ${report.sources.map((s) => s.id).join(", ") || "(none)"}
-diagnostics: ${report.diagnostics.length}
+diagnostics: ${report.diagnostics.length}${diagnosticsWhere(report.diagnostics, report.lesson.file)}
 tokens: context ${t.context} vs doc set ${t.docSet} + corpus ${t.corpus} (${(t.ratio * 100).toFixed(2)}% of the baseline)
 `
       );
@@ -371,8 +404,16 @@ tokens: context ${t.context} vs doc set ${t.docSet} + corpus ${t.corpus} (${(t.r
         for (const entry of report.lessons) {
           out(`${entry.ok ? "ok  " : "FAIL"} ${entry.lesson}${entry.rendered ? "" : " (render failed)"}
 `);
+          const infos = /* @__PURE__ */ new Map();
           for (const diagnostic of entry.diagnostics) {
-            out(`     [${diagnostic.severity}] ${diagnostic.code}${ownerTag(diagnostic)}: ${diagnostic.message}
+            if (diagnostic.severity === "info") infos.set(diagnostic.code, (infos.get(diagnostic.code) ?? 0) + 1);
+            else out(`     [${diagnostic.severity}] ${diagnostic.code}${ownerTag(diagnostic)}: ${diagnostic.message}
+`);
+          }
+          if (infos.size > 0) {
+            const total = [...infos.values()].reduce((sum, n) => sum + n, 0);
+            const byCode = [...infos].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([code, n]) => `${code} ${n}`).join(", ");
+            out(`     + ${total} info (${byCode}); content diagnostics --lesson ${entry.lesson} lists them
 `);
           }
         }

package/dist/compiler/cli-reference.d.ts

@@ -0,0 +1,50 @@
+import { ContentVerb } from './cli-verbs.js';
+
+/** A JSON Schema (draft 2020-12), the subset the generator writes. */
+type JsonSchema = Readonly<Record<string, unknown>>;
+/** `docs/authoring/cli-reference.json`, whole: what `content help --json` prints. */
+interface CliReference {
+    /** Where it came from, and that it is generated. */
+    readonly generatedBy: string;
+    readonly verbs: readonly ContentVerb[];
+    /** The type every verb's `--json` prints when the run fails: a stable code and a message, never a stack. */
+    readonly error: string;
+    /** A JSON Schema of every type a verb's `--json` prints, and of every named type inside one, by name. */
+    readonly $defs: Readonly<Record<string, JsonSchema>>;
+}
+/** One verb's row, its usage line, and a self-contained JSON Schema of its `--json`. */
+interface VerbHelp extends ContentVerb {
+    readonly usage: string;
+    readonly schema: JsonSchema;
+}
+/** What `content help <verb> --json` prints: every verb the word names (`new` names three). */
+interface VerbHelpJson {
+    readonly verbs: readonly VerbHelp[];
+}
+/** `content help --json` prints the whole reference; `content help <verb> --json` that verb's rows. */
+type HelpJson = CliReference | VerbHelpJson;
+declare const CLI_REFERENCE_FILE = "cli-reference.json";
+/** The reference beside the engine (`node_modules/explico/docs/authoring/`, or this repository's). */
+declare function loadCliReference(): CliReference;
+/** The verbs a word names: `symbol` one, `new` the three `new …` verbs. */
+declare function verbsNamed(word: string): readonly ContentVerb[];
+/** A self-contained schema of one named type: a `$ref` and the `$defs` it reaches. */
+declare function schemaOf(reference: CliReference, name: string): JsonSchema;
+declare function verbHelp(reference: CliReference, word: string): VerbHelpJson;
+/** One line per property, `name?: type  — description`, nested objects indented under their property. */
+declare function shapeLines(schema: JsonSchema, indent?: string): string[];
+/** A named type as a block: its name and description, then its shape. */
+declare function defLines(name: string, schema: JsonSchema): string[];
+/** `content help <verb>` as text: the usage, what it is for, its flags, and the shape of its `--json`. */
+declare function formatVerbHelp(reference: CliReference, help: VerbHelpJson): string;
+/** `docs/authoring/cli.md`, generated: one section per verb, then every `--json` type. */
+declare function cliReferenceMarkdown(reference: CliReference): string;
+/**
+ * Where `value` departs from `schema`, one message per place (`$.hits[0].tier:
+ * expected one of …`); empty when it conforms. The subset the generator
+ * writes: `$ref`, `type`, `const`, `enum`, `anyOf`, `properties`, `required`,
+ * `additionalProperties`, `items`.
+ */
+declare function jsonShapeErrors(schema: JsonSchema, value: unknown, defs?: CliReference["$defs"], path?: string): string[];
+
+export { CLI_REFERENCE_FILE, type CliReference, type HelpJson, type JsonSchema, type VerbHelp, type VerbHelpJson, cliReferenceMarkdown, defLines, formatVerbHelp, jsonShapeErrors, loadCliReference, schemaOf, shapeLines, verbHelp, verbsNamed };