explico 0.13.1 → 0.15.0

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;
+}

package/src/compiler/cli-verbs.ts

@@ -0,0 +1,270 @@
+/**
+ * Every `content` verb, as data: its arguments, what it is for, what it
+ * prints, what it writes, when it exits non-zero, and the exported type its
+ * `--json` prints. The one source for the usage text (`CONTENT_USAGE`),
+ * `content help <verb>`, `docs/authoring/cli.md` and
+ * `docs/authoring/cli-reference.json` — the last two generated by
+ * `scripts/agent/gen-cli.mjs`, which also turns each `json` type name into a
+ * JSON Schema from the TypeScript declaration (`--check` in verify and CI).
+ *
+ * A new verb is a row here, a `case` in `cli-main.ts`, and a regenerated
+ * reference; the `--json` contract test in the playground runs every
+ * read-only row against the course and validates its output.
+ */
+
+/** One flag a verb takes. */
+export interface ContentVerbFlag {
+  /** As typed: `--lesson <id>`, `--write`. */
+  readonly flag: string;
+  readonly description: string;
+}
+
+/** One verb's row. */
+export interface ContentVerb {
+  /** The command word(s): `symbol`, `new lesson`. */
+  readonly verb: string;
+  /** What follows the verb on the usage line, `--json` left out (every verb takes it). */
+  readonly args: string;
+  /** What you want to know or do when you reach for it. */
+  readonly when: string;
+  /** What it prints as text. */
+  readonly prints: string;
+  /** The flags, each once; a positional argument is described in `prints` or `when`. */
+  readonly flags: readonly ContentVerbFlag[];
+  /** What it changes on disk. */
+  readonly writes: string;
+  /** When it exits 1, beyond a usage error. */
+  readonly exit?: string;
+  /** The type its `--json` prints, by its exported name in `explico/compiler/cli`, `cli-main` or `cli-verify`. */
+  readonly json: string;
+}
+
+const WRITE: ContentVerbFlag = { flag: '--write', description: 'apply the edits; without it the diff is printed and nothing changes' };
+const READ_ONLY = 'nothing';
+
+export const CONTENT_VERBS: readonly ContentVerb[] = [
+  {
+    verb: 'status',
+    args: '',
+    when: 'how the course stands',
+    prints:
+      "counts, diagnostic totals, the knowledge and page versions, the agent surfaces' sizes, whether the course's AGENTS.md points at the engine's guide and the procedures are installed",
+    flags: [],
+    writes: READ_ONLY,
+    json: 'StatusReport',
+  },
+  {
+    verb: 'diagnostics',
+    args: '[info|warning|error] [--all | --code <c> | --lesson <id> | --changed]',
+    when: 'what is wrong, where',
+    prints:
+      'counts by code (with each code\'s rule) and by file, at the given severity or higher (info by default); a filter or --all lists the lines instead. --json always prints the lines',
+    flags: [
+      { flag: '--all', description: 'list every diagnostic instead of the counts' },
+      { flag: '--code <c>', description: 'only that diagnostic code' },
+      { flag: '--lesson <id>', description: "only that lesson's file" },
+      { flag: '--changed', description: 'only lessons whose .mdx or .checks.yml differs from git HEAD, tracked or not' },
+    ],
+    writes: READ_ONLY,
+    json: 'DiagnosticsReport',
+  },
+  {
+    verb: 'warnings',
+    args: '',
+    when: 'the warnings alone',
+    prints: 'every warning, one line each with its rule, then the count',
+    flags: [],
+    writes: READ_ONLY,
+    json: 'WarningsReport',
+  },
+  {
+    verb: 'context',
+    args: '<lesson>',
+    when: 'what a lesson draws on',
+    prints:
+      'its outcomes, notation, sources, diagnostics and token counts; --json adds the body, the floats it can reference, its sections and domain signatures',
+    flags: [],
+    writes: READ_ONLY,
+    json: 'ContextReport',
+  },
+  {
+    verb: 'equation',
+    args: '"<latex>" [--lesson <id>]',
+    when: 'will this expression build',
+    prints: "each glyph's card, unresolved glyphs with where they are defined",
+    flags: [{ flag: '--lesson <id>', description: "resolve against that lesson's local notation as well as the shared cards" }],
+    writes: READ_ONLY,
+    exit: 'when the build would refuse the expression',
+    json: 'EquationReport',
+  },
+  {
+    verb: 'bindings',
+    args: '<lesson>',
+    when: "what a lesson's math binds",
+    prints: 'every math span: its bindings, unresolved glyphs, redundant \\explain wraps',
+    flags: [],
+    writes: READ_ONLY,
+    json: 'BindingsReport',
+  },
+  {
+    verb: 'symbol',
+    args: '<latex | key>',
+    when: 'is this symbol defined already',
+    prints: 'the shared card, each local entry with its lesson, each gloss with its card, near misses',
+    flags: [],
+    writes: READ_ONLY,
+    json: 'SymbolReport',
+  },
+  {
+    verb: 'check',
+    args: '<lesson | deck>… [--changed]',
+    when: 'does it render',
+    prints: 'ok or FAIL per lesson: schema, references, MDX → KaTeX; each error and warning with its rule, the info counted by code',
+    flags: [{ flag: '--changed', description: 'the lessons whose .mdx or .checks.yml differs from git HEAD, tracked or not' }],
+    writes: READ_ONLY,
+    exit: 'when a lesson has an error',
+    json: 'CheckReport',
+  },
+  {
+    verb: 'rule',
+    args: '<ID>',
+    when: 'one rule, whole',
+    prints: "the entry as this course has it (enforcement, codes, settings in effect) and the rule page's section, example included",
+    flags: [],
+    writes: READ_ONLY,
+    exit: 'for an ID the catalog and the course rules do not know',
+    json: 'RuleReport',
+  },
+  {
+    verb: 'migrate',
+    args: '[--from <version>] [--to <version>]',
+    when: 'what an upgrade needs',
+    prints: "the migration guide's sections between the version package.json pins at git HEAD and the one installed, oldest first",
+    flags: [
+      { flag: '--from <version>', description: 'start here instead of the version pinned at HEAD' },
+      { flag: '--to <version>', description: 'stop here instead of the installed version' },
+    ],
+    writes: READ_ONLY,
+    exit: 'when a section between the two versions is missing',
+    json: 'MigrateReport',
+  },
+  {
+    verb: 'rules',
+    args: '[--element <e>[,<e>]] [--enforcement script|partial|guide|locked] [--edition chapter|deck]',
+    when: 'which rules apply',
+    prints: 'the rules this course has on, by element, with enforcement, codes, settings in effect and a one-line summary',
+    flags: [
+      { flag: '--element <e>[,<e>]', description: 'only rules about these elements (prose, table, notation, …)' },
+      { flag: '--enforcement <kind>', description: 'only script, partial, guide or locked rules' },
+      { flag: '--edition <edition>', description: "chapter (the default) or deck: the rules for that edition's pages" },
+    ],
+    writes: READ_ONLY,
+    json: 'RulesJson',
+  },
+  {
+    verb: 'move',
+    args: '<lesson>:<key> [--to <key>] [--write]',
+    when: 'a local entry becomes shared',
+    prints: 'the new card and every copy and reference that changes, as a diff',
+    flags: [{ flag: '--to <key>', description: 'the shared card\'s key, when it differs from the local one' }, WRITE],
+    writes: 'only with --write',
+    json: 'EditPlanJson',
+  },
+  {
+    verb: 'rename',
+    args: '<old> <new> [--write]',
+    when: 'rename a shared card',
+    prints: 'the card file and every reference, as a diff',
+    flags: [WRITE],
+    writes: 'only with --write',
+    json: 'EditPlanJson',
+  },
+  {
+    verb: 'fix',
+    args: '<lesson>… | --all [--write]',
+    when: 'the mechanical repairs',
+    prints: 'redundant \\explain wraps unwrapped, as a diff',
+    flags: [{ flag: '--all', description: 'every lesson; the ones with nothing to fix are counted' }, WRITE],
+    writes: 'only with --write',
+    json: 'EditPlanJson',
+  },
+  {
+    verb: 'new lesson',
+    args: '<id>',
+    when: 'a chapter to start from',
+    prints: 'the files it created: the .mdx and its .checks.yml',
+    flags: [],
+    writes: 'new files; never overwrites',
+    json: 'NewJson',
+  },
+  {
+    verb: 'new deck',
+    args: '<lesson | part>',
+    when: 'slides to start from',
+    prints: "the deck it drafted from the chapter (or the part's chapters)",
+    flags: [],
+    writes: 'new files; never overwrites',
+    json: 'NewJson',
+  },
+  {
+    verb: 'new term',
+    args: '<key>',
+    when: 'a shared notation card to start from',
+    prints: 'the card file it created',
+    flags: [],
+    writes: 'new files; never overwrites',
+    json: 'NewJson',
+  },
+  {
+    verb: 'init-agent',
+    args: '[--write]',
+    when: 'install the agent procedures',
+    prints:
+      "the skills and the rules-reviewer agent it would copy into .claude/, and a baseline AGENTS.md when the course has none; rerun after an upgrade",
+    flags: [WRITE],
+    writes: 'only with --write',
+    json: 'EditPlanJson',
+  },
+  {
+    verb: 'release',
+    args: '[major|minor|patch] [--write]',
+    when: 'cut a content release (rule C3)',
+    prints:
+      "## [Unreleased] in content/CHANGELOG.md becoming a dated ## [x.y.z] heading and about.version becoming x.y.z, as a diff; the bump defaults to what the section's headings imply (Breaking or Removed → major, Added → minor, else patch)",
+    flags: [WRITE],
+    writes: 'only with --write',
+    json: 'EditPlanJson',
+  },
+  {
+    verb: 'verify',
+    args: '[--e2e] [--force]',
+    when: 'is it ready to hand back',
+    prints:
+      "one line per step — validate:content, check --changed, astro check, the course's tests, astro build, and with --e2e the browser tests — and the tail of each failed step's log; a rerun on an unchanged tree answers from the last pass",
+    flags: [
+      { flag: '--e2e', description: "also run the browser tests (the course's test:e2e script, or playwright test when it has a config)" },
+      { flag: '--force', description: 'run even when nothing changed since the last pass' },
+    ],
+    writes: 'what validate:content and astro build write; logs and the pass record under node_modules/.cache/explico/verify/',
+    exit: 'when a step fails',
+    json: 'VerifyReport',
+  },
+  {
+    verb: 'help',
+    args: '[<verb>]',
+    when: "a verb's flags and its --json shape",
+    prints: "the usage; with a verb, its flags, what it writes, its exit code and the shape of its --json",
+    flags: [],
+    writes: READ_ONLY,
+    exit: 'for an unknown verb',
+    json: 'HelpJson',
+  },
+];
+
+/** One usage line: `pnpm content symbol <latex | key> [--json]`. */
+export function usageLine(verb: ContentVerb): string {
+  return `pnpm content ${verb.verb}${verb.args === '' ? '' : ` ${verb.args}`} [--json]`;
+}
+
+/** The usage text `content help` prints; `scripts/agent/gen-map.mjs` lists the verbs from the generated reference. */
+export const CONTENT_USAGE = `Usage:\n${CONTENT_VERBS.map((verb) => `  ${usageLine(verb)}`).join('\n')}`;