explico 0.14.0 → 0.15.0

package/src/compiler/cli-main.ts

@@ -12,8 +12,10 @@
  * so every verb reaches every course with the package and no course forks
  * the router. Each verb's logic lives in `./cli`; this module only parses
  * argv, prints (`--json` = data only, no stack traces), and returns the exit
- * code. Everything except `new` is read-only; `move`, `rename` and `fix`
- * print a diff and change nothing without `--write`.
+ * code. Everything except `new` and `verify` is read-only; `move`, `rename`,
+ * `fix` and `init-agent` print a diff and change nothing without `--write`.
+ * Each verb's row — usage, flags, what it writes, the type its `--json`
+ * prints — is in `./cli-verbs`; `content help <verb>` prints it.
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -44,7 +46,7 @@ import {
   formatSymbolReport,
   ownerTag,
   parseRulesFilter,
-  planFix,
+  planFixMany,
   planInitAgent,
   planMove,
   planRename,
@@ -53,31 +55,45 @@ import {
   scaffoldLesson,
   scaffoldTerm,
   summarizeDiagnostics,
+  type ContentCliCode,
+  type EditPlan,
+  type RulesReport,
   type Scaffold,
 } from './cli';
+import { formatVerbHelp, loadCliReference, verbHelp, type HelpJson } from './cli-reference';
+import { CONTENT_USAGE } from './cli-verbs';
+import { planContentRelease } from './content-release';
+import { formatVerifyReport, formatVerifyStep, runVerify, type VerifyReport } from './cli-verify';
 import type { CourseConfig } from './course-config';
-import { compileManifest } from './manifest';
-
-/** The usage text `content help` prints; `scripts/agent/gen-map.mjs` lists the verbs from it. */
-export 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>… [--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]`;
+import { compileManifest, type Manifest } from './manifest';
+
+export { CONTENT_USAGE };
+
+/** `--json` of `rules`: the report without its Markdown page. */
+export type RulesJson = Pick<RulesReport, 'filter' | 'count' | 'rules'>;
+
+/** `--json` of `move`, `rename`, `fix` and `init-agent`: the plan, and whether `--write` applied it. */
+export 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`. */
+export 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. */
+export interface ErrorJson {
+  readonly ok: false;
+  readonly error: {
+    /** `internal` for an unexpected throw; every other code is stable. */
+    readonly code: ContentCliCode | 'internal';
+    readonly message: string;
+  };
+}
 
 export interface ContentArgs {
   readonly command: string;
@@ -101,6 +117,10 @@ export 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;
 }
 
 const VALUED_FLAGS = ['element', 'enforcement', 'edition', 'code', 'lesson', 'from', 'to'] as const;
@@ -112,6 +132,8 @@ export function parseContentArgs(argv: readonly string[]): ContentArgs {
   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]!;
@@ -120,6 +142,8 @@ export function parseContentArgs(argv: readonly string[]): ContentArgs {
     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] as (typeof VALUED_FLAGS)[number]] = match[2] ?? argv[(i += 1)] ?? '';
     else positionals.push(arg);
   }
@@ -130,10 +154,22 @@ export function parseContentArgs(argv: readonly string[]): ContentArgs {
     changed,
     all,
     write,
+    e2e,
+    force,
     ...values,
   };
 }
 
+/**
+ * A lesson's diagnostics include the shared cards it shows (a fault in one is
+ * the page's too), so `context` says how many sit in the lesson's own file —
+ * the number `diagnostics --lesson` lists.
+ */
+function diagnosticsWhere(diagnostics: readonly { readonly file?: string }[], file: string): string {
+  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)`;
+}
+
 /** Where a run prints; the process streams by default, a buffer in a test. */
 export interface ContentIo {
   readonly out: (text: string) => void;
@@ -148,14 +184,14 @@ const PROCESS_IO: ContentIo = {
 /** A usage or input mistake, reported like a `ContentCliError` and ending the run with 1. */
 class Usage extends Error {
   constructor(
-    readonly code: string,
+    readonly code: ContentCliCode,
     message: string,
   ) {
     super(message);
   }
 }
 
-function usage(code: string, message: string): never {
+function usage(code: ContentCliCode, message: string): never {
   throw new Usage(code, message);
 }
 
@@ -179,16 +215,18 @@ export async function runContentCli(
   courseConfig: CourseConfig,
   argv: readonly string[] = process.argv.slice(2),
   io: ContentIo = PROCESS_IO,
+  /** A manifest already compiled for this course, reused instead of compiling one: a test running many verbs compiles once. */
+  compiled?: Manifest,
 ): Promise<number> {
   const args = parseContentArgs(argv);
   const json = (value: unknown) => io.out(`${JSON.stringify(value, null, 2)}\n`);
   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);
-    if (args.json) json({ ok: false, error: { code, message } });
+    if (args.json) json({ ok: false, error: { code, message } } satisfies ErrorJson);
     else io.err(`Error [${code}]: ${message}\n`);
     return 1;
   }
@@ -199,13 +237,43 @@ async function dispatch(
   args: ContentArgs,
   io: ContentIo,
   json: (value: unknown) => void,
+  compiled: Manifest | undefined,
 ): Promise<number> {
   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}\n`);
     return 0;
   }
 
+  // `help` reads the generated reference beside the engine: no manifest.
+  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 === undefined) {
+      json(reference satisfies HelpJson);
+      return 0;
+    }
+    const help = verbHelp(reference, word);
+    if (args.json) json(help satisfies HelpJson);
+    else out(formatVerbHelp(reference, help));
+    return 0;
+  }
+
+  // `verify` runs the course's own scripts, each in its own process: no manifest here.
+  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/)\n`);
+    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 satisfies VerifyReport);
+    else out(report.cached ? formatVerifyReport(report) : `\n${formatVerifyReport(report)}`);
+    return report.ok ? 0 : 1;
+  }
+
   if (args.command === 'new') {
     const [kind, id] = args.positionals;
     if (kind !== 'lesson' && kind !== 'deck' && kind !== 'term') {
@@ -217,7 +285,7 @@ async function dispatch(
     }
     const scaffold = kind === 'lesson' ? scaffoldLesson(id) : kind === 'deck' ? scaffoldDeck(id) : scaffoldTerm(id);
     const written = writeScaffold(scaffold);
-    if (args.json) json({ ok: true, created: written });
+    if (args.json) json({ ok: true, created: written } satisfies NewJson);
     else out(`Created:\n${written.map((p) => `  ${p}`).join('\n')}\n`);
     return 0;
   }
@@ -228,17 +296,25 @@ async function dispatch(
     usage('usage', `content ${args.command} takes no <lesson>; got ${args.positionals.join(' ')}.`);
   }
 
-  // `init-agent` copies the engine's procedures into the course: no manifest.
-  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.json) json({ ...plan, written: args.write });
+  // `init-agent` copies the engine's procedures into the course, `release`
+  // edits the changelog and the config: no manifest for either.
+  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 } satisfies EditPlanJson);
     else out(renderEditPlan(plan));
     if (plan.edits.length === 0) return 0;
+    const next = plan.next.length > 0 ? plan.next.join(' · ') : '';
     if (args.write) {
       const touched = applyEditPlan(plan);
-      if (!args.json) out(`\nwritten: ${touched.join(', ')}\n`);
-    } else if (!args.json) out('\ndry run: nothing written. Add --write to install.\n');
+      if (!args.json) out(`\nwritten: ${touched.join(', ')}${next === '' ? '' : `\nnext: ${next}`}\n`);
+    } else if (!args.json) out(`\ndry run: nothing written. Add --write to apply${next === '' ? '' : `; then ${next}`}.\n`);
     return 0;
   }
 
@@ -264,7 +340,7 @@ async function dispatch(
     usage('unknown-command', `Unknown command "${args.command}".\n${CONTENT_USAGE}`);
   }
 
-  const manifest = await compileManifest(courseConfig);
+  const manifest = compiled ?? (await compileManifest(courseConfig));
 
   switch (args.command) {
     case 'status': {
@@ -275,11 +351,16 @@ async function dispatch(
       }
       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(', ')}, … ${unreleased.length - UNRELEASED_SHOWN} more in --json`;
       out(
         `Knowledge version ${report.knowledgeVersion}\n` +
           `Page versions: ${report.pageVersions.tracked} page(s) tracked, ` +
           `${unreleased.length} with changes not yet released` +
-          `${unreleased.length > 0 ? ` (${unreleased.join(', ')})` : ''}\n` +
+          `${unreleased.length > 0 ? ` (${unreleasedList})` : ''}\n` +
           `Lessons ${c.lessons} · competencies ${c.competencies} · assessments ${c.assessments} · ` +
           `sources ${c.sources} · tracks ${c.tracks} · notation ${c.notationDefinitions} · ` +
           `keyed equations ${c.keyedEquations} · tables ${c.keyedTables} · ` +
@@ -314,11 +395,10 @@ async function dispatch(
         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 });
+      if (args.json) json({ ...plan, written: args.write } satisfies EditPlanJson);
       else out(renderEditPlan(plan));
       if (plan.edits.length === 0) return 0;
       if (args.write) {
@@ -347,7 +427,7 @@ async function dispatch(
         ...(args.edition === undefined ? {} : { edition: args.edition }),
       });
       const report = contentRules(manifest, filter);
-      if (args.json) json({ filter: report.filter, count: report.count, rules: report.rules });
+      if (args.json) json({ filter: report.filter, count: report.count, rules: report.rules } satisfies RulesJson);
       else out(report.markdown);
       return 0;
     }
@@ -408,7 +488,7 @@ async function dispatch(
           `requires: ${report.lesson.requires.join(', ') || '(none)'}\n` +
           `notation: ${report.notation.map((n) => n.key).join(', ') || '(none)'}\n` +
           `sources: ${report.sources.map((s) => s.id).join(', ') || '(none)'}\n` +
-          `diagnostics: ${report.diagnostics.length}\n` +
+          `diagnostics: ${report.diagnostics.length}${diagnosticsWhere(report.diagnostics, report.lesson.file)}\n` +
           `tokens: context ${t.context} vs doc set ${t.docSet} + corpus ${t.corpus} ` +
           `(${(t.ratio * 100).toFixed(2)}% of the baseline)\n`,
       );
@@ -454,8 +534,16 @@ async function dispatch(
       else {
         for (const entry of report.lessons) {
           out(`${entry.ok ? 'ok  ' : 'FAIL'} ${entry.lesson}${entry.rendered ? '' : ' (render failed)'}\n`);
+          // Errors and warnings line by line; info, which never fails a check, counted by code.
+          const infos = new Map<string, number>();
           for (const diagnostic of entry.diagnostics) {
-            out(`     [${diagnostic.severity}] ${diagnostic.code}${ownerTag(diagnostic)}: ${diagnostic.message}\n`);
+            if (diagnostic.severity === 'info') infos.set(diagnostic.code, (infos.get(diagnostic.code) ?? 0) + 1);
+            else out(`     [${diagnostic.severity}] ${diagnostic.code}${ownerTag(diagnostic)}: ${diagnostic.message}\n`);
+          }
+          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\n`);
           }
         }
         if (report.lessons.length === 0) out('No changed lessons.\n');

package/src/compiler/cli-reference.ts

@@ -0,0 +1,285 @@
+/**
+ * The `content` CLI's machine-readable reference: every verb's row from
+ * `./cli-verbs`, and a JSON Schema of every type a verb's `--json` prints.
+ *
+ * TypeScript types are gone at run time, so `scripts/agent/gen-cli.mjs`
+ * reads them from the source with the compiler API and writes the schemas
+ * into `docs/authoring/cli-reference.json` beside the rule pages, where the
+ * CLI finds them in the workspace and in an installed package alike; it
+ * writes `docs/authoring/cli.md` from the same data with `cliReferenceMarkdown`.
+ * `--check` holds both to the source in verify and CI.
+ *
+ * `content help <verb>` prints a verb's row and the shape of its `--json`
+ * (`formatVerbHelp`); `--json` prints the row with a self-contained schema.
+ * `jsonShapeErrors` checks a value against a schema — the playground's
+ * contract test runs every read-only verb through it.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ContentCliError, authoringDocsDir } from './cli';
+import { CONTENT_VERBS, usageLine, type ContentVerb } from './cli-verbs';
+
+/** A JSON Schema (draft 2020-12), the subset the generator writes. */
+export type JsonSchema = Readonly<Record<string, unknown>>;
+
+/** `docs/authoring/cli-reference.json`, whole: what `content help --json` prints. */
+export 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`. */
+export interface VerbHelp extends ContentVerb {
+  readonly usage: string;
+  readonly schema: JsonSchema;
+}
+
+/** What `content help <verb> --json` prints: every verb the word names (`new` names three). */
+export interface VerbHelpJson {
+  readonly verbs: readonly VerbHelp[];
+}
+
+/** `content help --json` prints the whole reference; `content help <verb> --json` that verb's rows. */
+export type HelpJson = CliReference | VerbHelpJson;
+
+export const CLI_REFERENCE_FILE = 'cli-reference.json';
+
+/** The reference beside the engine (`node_modules/explico/docs/authoring/`, or this repository's). */
+export function loadCliReference(): CliReference {
+  const dir = authoringDocsDir();
+  const file = dir === undefined ? undefined : join(dir, CLI_REFERENCE_FILE);
+  if (file === undefined || !existsSync(file)) {
+    throw new ContentCliError('unknown-command', `No ${CLI_REFERENCE_FILE} beside the engine (node_modules/explico/docs/authoring).`);
+  }
+  return JSON.parse(readFileSync(file, 'utf8')) as CliReference;
+}
+
+/** The verbs a word names: `symbol` one, `new` the three `new …` verbs. */
+export function verbsNamed(word: string): readonly ContentVerb[] {
+  const hits = CONTENT_VERBS.filter((verb) => verb.verb === word || verb.verb.startsWith(`${word} `));
+  if (hits.length === 0) {
+    throw new ContentCliError(
+      'unknown-command',
+      `Unknown verb "${word}". The verbs: ${[...new Set(CONTENT_VERBS.map((verb) => verb.verb.split(' ')[0]))].join(', ')}.`,
+    );
+  }
+  return hits;
+}
+
+/** The names a schema refers to, itself and transitively. */
+function reachableDefs(name: string, defs: CliReference['$defs'], seen = new Set<string>()): Set<string> {
+  if (seen.has(name) || defs[name] === undefined) return seen;
+  seen.add(name);
+  for (const match of JSON.stringify(defs[name]).matchAll(/"#\/\$defs\/([^"]+)"/g)) reachableDefs(match[1]!, defs, seen);
+  return seen;
+}
+
+/** A self-contained schema of one named type: a `$ref` and the `$defs` it reaches. */
+export function schemaOf(reference: CliReference, name: string): JsonSchema {
+  const names = [...reachableDefs(name, reference.$defs)].sort();
+  return {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $ref: `#/$defs/${name}`,
+    $defs: Object.fromEntries(names.map((n) => [n, reference.$defs[n]])),
+  };
+}
+
+export function verbHelp(reference: CliReference, word: string): VerbHelpJson {
+  return {
+    verbs: verbsNamed(word).map((verb) => ({ ...verb, usage: usageLine(verb), schema: schemaOf(reference, verb.json) })),
+  };
+}
+
+// --- rendering a schema as a TypeScript-like shape -------------------------
+
+function oneLine(text: unknown): string {
+  return typeof text === 'string' ? text.replace(/\s+/g, ' ').trim() : '';
+}
+
+function refName(ref: string): string {
+  return ref.replace('#/$defs/', '');
+}
+
+function isObjectShape(schema: JsonSchema): boolean {
+  return schema.type === 'object' && schema.properties !== undefined;
+}
+
+/** A schema's type as one TypeScript-like expression; an object with properties is `{…}` here and expanded by `shapeLines`. */
+function typeExpression(schema: JsonSchema): string {
+  if (typeof schema.$ref === 'string') return refName(schema.$ref);
+  if ('const' in schema) return JSON.stringify(schema.const);
+  if (Array.isArray(schema.enum)) return schema.enum.map((value) => JSON.stringify(value)).join(' | ');
+  if (Array.isArray(schema.anyOf)) return (schema.anyOf as JsonSchema[]).map(typeExpression).join(' | ');
+  if (schema.type === 'array') {
+    const items = typeExpression((schema.items ?? {}) as JsonSchema);
+    return / \| /.test(items) ? `(${items})[]` : `${items}[]`;
+  }
+  if (schema.type === 'object') {
+    if (schema.properties !== undefined) return '{…}';
+    const value = schema.additionalProperties;
+    return `Record<string, ${typeof value === 'object' && value !== null ? typeExpression(value as JsonSchema) : 'unknown'}>`;
+  }
+  if (schema.type === 'integer') return 'number';
+  if (typeof schema.type === 'string') return schema.type;
+  return 'unknown';
+}
+
+/** The object a property's type expands to, when it has one: `{…}`, `{…}[]`, `{…} | null`. */
+function expandable(schema: JsonSchema): JsonSchema | undefined {
+  if (isObjectShape(schema)) return schema;
+  if (schema.type === 'array') return expandable((schema.items ?? {}) as JsonSchema);
+  if (Array.isArray(schema.anyOf)) {
+    const objects = (schema.anyOf as JsonSchema[]).map(expandable).filter((s): s is JsonSchema => s !== undefined);
+    return objects.length === 1 ? objects[0] : undefined;
+  }
+  return undefined;
+}
+
+/** One line per property, `name?: type  — description`, nested objects indented under their property. */
+export function shapeLines(schema: JsonSchema, indent = '  '): string[] {
+  const lines: string[] = [];
+  const required = new Set((schema.required ?? []) as string[]);
+  for (const [name, raw] of Object.entries((schema.properties ?? {}) as Record<string, JsonSchema>)) {
+    const description = oneLine(raw.description);
+    lines.push(`${indent}${name}${required.has(name) ? '' : '?'}: ${typeExpression(raw)}${description === '' ? '' : `  — ${description}`}`);
+    const nested = expandable(raw);
+    if (nested !== undefined) lines.push(...shapeLines(nested, `${indent}  `));
+  }
+  return lines;
+}
+
+/** A named type as a block: its name and description, then its shape. */
+export function defLines(name: string, schema: JsonSchema): string[] {
+  const description = oneLine(schema.description);
+  const head = `${name}${isObjectShape(schema) ? '' : ` = ${typeExpression(schema)}`}`;
+  return [description === '' ? head : `${head}  — ${description}`, ...(isObjectShape(schema) ? shapeLines(schema) : [])];
+}
+
+/** A verb's row as labelled lines: what it is for, what it prints and writes, when it exits 1. */
+function verbFacts(verb: ContentVerb): (readonly [string, string])[] {
+  return [
+    ['For', verb.when],
+    ['Prints', verb.prints],
+    ['Writes', verb.writes],
+    ['Exits 1', `on a usage error${verb.exit === undefined ? '' : `, and ${verb.exit}`}`],
+  ];
+}
+
+/** The verb's own type first, then the types it reaches, by name. */
+function typeOrder(verb: VerbHelp): string[] {
+  return [verb.json, ...Object.keys(verb.schema.$defs as object).filter((name) => name !== verb.json).sort()];
+}
+
+/** `content help <verb>` as text: the usage, what it is for, its flags, and the shape of its `--json`. */
+export function formatVerbHelp(reference: CliReference, help: VerbHelpJson): string {
+  const blocks = help.verbs.map((verb) => {
+    const lines = [verb.usage, '', ...verbFacts(verb).map(([label, text]) => `  ${`${label}:`.padEnd(9)}${text}`)];
+    if (verb.flags.length > 0) {
+      lines.push('', 'Flags:');
+      const width = Math.max(...verb.flags.map((flag) => flag.flag.length));
+      for (const flag of verb.flags) lines.push(`  ${flag.flag.padEnd(width)}  ${flag.description}`);
+    }
+    lines.push('', `--json prints ${verb.json}:`);
+    for (const name of typeOrder(verb)) lines.push(...defLines(name, reference.$defs[name]!).map((line) => `  ${line}`), '');
+    return lines.join('\n').trimEnd();
+  });
+  return `${blocks.join('\n\n')}\n\nOn a failure --json prints ${reference.error}: { "ok": false, "error": { "code", "message" } }.\n`;
+}
+
+// --- docs/authoring/cli.md ---------------------------------------------------
+
+function anchor(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+}
+
+/** `docs/authoring/cli.md`, generated: one section per verb, then every `--json` type. */
+export function cliReferenceMarkdown(reference: CliReference): string {
+  const out = [
+    '<!-- generated by scripts/agent/gen-cli.mjs from src/compiler/cli-verbs.ts and the report types — do not edit; `node scripts/agent/gen-cli.mjs` rewrites it, `--check` gates it -->',
+    '',
+    '# The `content` CLI',
+    '',
+    'Every verb of `pnpm content`, what it writes, when it exits 1, and the shape',
+    'of its `--json`. The same data, with a JSON Schema per type, is',
+    '[`cli-reference.json`](cli-reference.json); `pnpm content help <verb> [--json]`',
+    'prints one verb of it. Every verb takes `--json`: data only on stdout, and on',
+    `a failure \`{ "ok": false, "error": { "code", "message" } }\` ([\`${reference.error}\`](#${anchor(reference.error)})).`,
+    '',
+    '| Verb | You want to know or do | Writes |',
+    '| --- | --- | --- |',
+    ...reference.verbs.map((verb) => `| [\`${verb.verb}\`](#${anchor(`content ${verb.verb}`)}) | ${verb.when} | ${verb.writes} |`),
+    '',
+  ];
+  for (const verb of reference.verbs) {
+    out.push(`## content ${verb.verb}`, '', '```text', usageLine(verb), '```', '');
+    for (const [label, text] of verbFacts(verb)) out.push(`- **${label}:** ${text.replace(/\\explain/g, '`\\explain`')}`);
+    out.push('');
+    if (verb.flags.length > 0) {
+      out.push('| Flag | Effect |', '| --- | --- |');
+      for (const flag of verb.flags) out.push(`| \`${flag.flag}\` | ${flag.description} |`);
+      out.push('');
+    }
+    out.push(`\`--json\`: [\`${verb.json}\`](#${anchor(verb.json)})`, '');
+  }
+  out.push('## The `--json` types', '', 'A `?` marks a property that may be absent.', '');
+  for (const name of Object.keys(reference.$defs).sort()) {
+    out.push(`### ${name}`, '', '```ts', ...defLines(name, reference.$defs[name]!), '```', '');
+  }
+  return `${out.join('\n').trimEnd()}\n`;
+}
+
+// --- checking a value against a schema ---------------------------------------
+
+/**
+ * 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`.
+ */
+export function jsonShapeErrors(schema: JsonSchema, value: unknown, defs = (schema.$defs ?? {}) as CliReference['$defs'], path = '$'): string[] {
+  if (typeof schema.$ref === 'string') {
+    const target = defs[refName(schema.$ref)];
+    return target === undefined ? [`${path}: unknown ${schema.$ref}`] : jsonShapeErrors(target, value, defs, path);
+  }
+  if ('const' in schema) return value === schema.const ? [] : [`${path}: expected ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`];
+  if (Array.isArray(schema.enum)) {
+    return schema.enum.includes(value) ? [] : [`${path}: expected one of ${schema.enum.map((v) => JSON.stringify(v)).join(', ')}, got ${JSON.stringify(value)}`];
+  }
+  if (Array.isArray(schema.anyOf)) {
+    const branches = (schema.anyOf as JsonSchema[]).map((branch) => jsonShapeErrors(branch, value, defs, path));
+    if (branches.some((errors) => errors.length === 0)) return [];
+    return [`${path}: matches none of ${typeExpression(schema)} (${branches.map((errors) => errors[0]).join('; ')})`];
+  }
+  const type = schema.type;
+  if (type === undefined) return [];
+  const actual = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+  const ok = type === 'integer' ? Number.isInteger(value) : type === actual;
+  if (!ok) return [`${path}: expected ${type}, got ${actual}`];
+  if (type === 'array') {
+    const items = (schema.items ?? {}) as JsonSchema;
+    return (value as unknown[]).flatMap((item, index) => jsonShapeErrors(items, item, defs, `${path}[${index}]`));
+  }
+  if (type !== 'object') return [];
+  const record = value as Record<string, unknown>;
+  const properties = (schema.properties ?? {}) as Record<string, JsonSchema>;
+  const errors: string[] = [];
+  for (const name of (schema.required ?? []) as string[]) {
+    if (!(name in record)) errors.push(`${path}.${name}: missing`);
+  }
+  for (const [name, item] of Object.entries(record)) {
+    if (item === undefined) continue;
+    const declared = properties[name];
+    if (declared !== undefined) errors.push(...jsonShapeErrors(declared, item, defs, `${path}.${name}`));
+    else if (schema.additionalProperties === false) errors.push(`${path}.${name}: not in the type`);
+    else if (typeof schema.additionalProperties === 'object') {
+      errors.push(...jsonShapeErrors(schema.additionalProperties as JsonSchema, item, defs, `${path}.${name}`));
+    }
+  }
+  return errors;
+}