explico 0.14.0 → 0.15.0

package/docs/authoring/cli.md

@@ -0,0 +1,887 @@
+<!-- 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" } }` ([`ErrorJson`](#errorjson)).
+
+| Verb | You want to know or do | Writes |
+| --- | --- | --- |
+| [`status`](#content-status) | how the course stands | nothing |
+| [`diagnostics`](#content-diagnostics) | what is wrong, where | nothing |
+| [`warnings`](#content-warnings) | the warnings alone | nothing |
+| [`context`](#content-context) | what a lesson draws on | nothing |
+| [`equation`](#content-equation) | will this expression build | nothing |
+| [`bindings`](#content-bindings) | what a lesson's math binds | nothing |
+| [`symbol`](#content-symbol) | is this symbol defined already | nothing |
+| [`check`](#content-check) | does it render | nothing |
+| [`rule`](#content-rule) | one rule, whole | nothing |
+| [`migrate`](#content-migrate) | what an upgrade needs | nothing |
+| [`rules`](#content-rules) | which rules apply | nothing |
+| [`move`](#content-move) | a local entry becomes shared | only with --write |
+| [`rename`](#content-rename) | rename a shared card | only with --write |
+| [`fix`](#content-fix) | the mechanical repairs | only with --write |
+| [`new lesson`](#content-new-lesson) | a chapter to start from | new files; never overwrites |
+| [`new deck`](#content-new-deck) | slides to start from | new files; never overwrites |
+| [`new term`](#content-new-term) | a shared notation card to start from | new files; never overwrites |
+| [`init-agent`](#content-init-agent) | install the agent procedures | only with --write |
+| [`release`](#content-release) | cut a content release (rule C3) | only with --write |
+| [`verify`](#content-verify) | is it ready to hand back | what validate:content and astro build write; logs and the pass record under node_modules/.cache/explico/verify/ |
+| [`help`](#content-help) | a verb's flags and its --json shape | nothing |
+
+## content status
+
+```text
+pnpm content status [--json]
+```
+
+- **For:** 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
+- **Writes:** nothing
+- **Exits 1:** on a usage error
+
+`--json`: [`StatusReport`](#statusreport)
+
+## content diagnostics
+
+```text
+pnpm content diagnostics [info|warning|error] [--all | --code <c> | --lesson <id> | --changed] [--json]
+```
+
+- **For:** 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
+- **Writes:** nothing
+- **Exits 1:** on a usage error
+
+| Flag | Effect |
+| --- | --- |
+| `--all` | list every diagnostic instead of the counts |
+| `--code <c>` | only that diagnostic code |
+| `--lesson <id>` | only that lesson's file |
+| `--changed` | only lessons whose .mdx or .checks.yml differs from git HEAD, tracked or not |
+
+`--json`: [`DiagnosticsReport`](#diagnosticsreport)
+
+## content warnings
+
+```text
+pnpm content warnings [--json]
+```
+
+- **For:** the warnings alone
+- **Prints:** every warning, one line each with its rule, then the count
+- **Writes:** nothing
+- **Exits 1:** on a usage error
+
+`--json`: [`WarningsReport`](#warningsreport)
+
+## content context
+
+```text
+pnpm content context <lesson> [--json]
+```
+
+- **For:** 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
+- **Writes:** nothing
+- **Exits 1:** on a usage error
+
+`--json`: [`ContextReport`](#contextreport)
+
+## content equation
+
+```text
+pnpm content equation "<latex>" [--lesson <id>] [--json]
+```
+
+- **For:** will this expression build
+- **Prints:** each glyph's card, unresolved glyphs with where they are defined
+- **Writes:** nothing
+- **Exits 1:** on a usage error, and when the build would refuse the expression
+
+| Flag | Effect |
+| --- | --- |
+| `--lesson <id>` | resolve against that lesson's local notation as well as the shared cards |
+
+`--json`: [`EquationReport`](#equationreport)
+
+## content bindings
+
+```text
+pnpm content bindings <lesson> [--json]
+```
+
+- **For:** what a lesson's math binds
+- **Prints:** every math span: its bindings, unresolved glyphs, redundant `\explain` wraps
+- **Writes:** nothing
+- **Exits 1:** on a usage error
+
+`--json`: [`BindingsReport`](#bindingsreport)
+
+## content symbol
+
+```text
+pnpm content symbol <latex | key> [--json]
+```
+
+- **For:** is this symbol defined already
+- **Prints:** the shared card, each local entry with its lesson, each gloss with its card, near misses
+- **Writes:** nothing
+- **Exits 1:** on a usage error
+
+`--json`: [`SymbolReport`](#symbolreport)
+
+## content check
+
+```text
+pnpm content check <lesson | deck>… [--changed] [--json]
+```
+
+- **For:** 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
+- **Writes:** nothing
+- **Exits 1:** on a usage error, and when a lesson has an error
+
+| Flag | Effect |
+| --- | --- |
+| `--changed` | the lessons whose .mdx or .checks.yml differs from git HEAD, tracked or not |
+
+`--json`: [`CheckReport`](#checkreport)
+
+## content rule
+
+```text
+pnpm content rule <ID> [--json]
+```
+
+- **For:** one rule, whole
+- **Prints:** the entry as this course has it (enforcement, codes, settings in effect) and the rule page's section, example included
+- **Writes:** nothing
+- **Exits 1:** on a usage error, and for an ID the catalog and the course rules do not know
+
+`--json`: [`RuleReport`](#rulereport)
+
+## content migrate
+
+```text
+pnpm content migrate [--from <version>] [--to <version>] [--json]
+```
+
+- **For:** 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
+- **Writes:** nothing
+- **Exits 1:** on a usage error, and when a section between the two versions is missing
+
+| Flag | Effect |
+| --- | --- |
+| `--from <version>` | start here instead of the version pinned at HEAD |
+| `--to <version>` | stop here instead of the installed version |
+
+`--json`: [`MigrateReport`](#migratereport)
+
+## content rules
+
+```text
+pnpm content rules [--element <e>[,<e>]] [--enforcement script|partial|guide|locked] [--edition chapter|deck] [--json]
+```
+
+- **For:** which rules apply
+- **Prints:** the rules this course has on, by element, with enforcement, codes, settings in effect and a one-line summary
+- **Writes:** nothing
+- **Exits 1:** on a usage error
+
+| Flag | Effect |
+| --- | --- |
+| `--element <e>[,<e>]` | only rules about these elements (prose, table, notation, …) |
+| `--enforcement <kind>` | only script, partial, guide or locked rules |
+| `--edition <edition>` | chapter (the default) or deck: the rules for that edition's pages |
+
+`--json`: [`RulesJson`](#rulesjson)
+
+## content move
+
+```text
+pnpm content move <lesson>:<key> [--to <key>] [--write] [--json]
+```
+
+- **For:** a local entry becomes shared
+- **Prints:** the new card and every copy and reference that changes, as a diff
+- **Writes:** only with --write
+- **Exits 1:** on a usage error
+
+| Flag | Effect |
+| --- | --- |
+| `--to <key>` | the shared card's key, when it differs from the local one |
+| `--write` | apply the edits; without it the diff is printed and nothing changes |
+
+`--json`: [`EditPlanJson`](#editplanjson)
+
+## content rename
+
+```text
+pnpm content rename <old> <new> [--write] [--json]
+```
+
+- **For:** rename a shared card
+- **Prints:** the card file and every reference, as a diff
+- **Writes:** only with --write
+- **Exits 1:** on a usage error
+
+| Flag | Effect |
+| --- | --- |
+| `--write` | apply the edits; without it the diff is printed and nothing changes |
+
+`--json`: [`EditPlanJson`](#editplanjson)
+
+## content fix
+
+```text
+pnpm content fix <lesson>… | --all [--write] [--json]
+```
+
+- **For:** the mechanical repairs
+- **Prints:** redundant `\explain` wraps unwrapped, as a diff
+- **Writes:** only with --write
+- **Exits 1:** on a usage error
+
+| Flag | Effect |
+| --- | --- |
+| `--all` | every lesson; the ones with nothing to fix are counted |
+| `--write` | apply the edits; without it the diff is printed and nothing changes |
+
+`--json`: [`EditPlanJson`](#editplanjson)
+
+## content new lesson
+
+```text
+pnpm content new lesson <id> [--json]
+```
+
+- **For:** a chapter to start from
+- **Prints:** the files it created: the .mdx and its .checks.yml
+- **Writes:** new files; never overwrites
+- **Exits 1:** on a usage error
+
+`--json`: [`NewJson`](#newjson)
+
+## content new deck
+
+```text
+pnpm content new deck <lesson | part> [--json]
+```
+
+- **For:** slides to start from
+- **Prints:** the deck it drafted from the chapter (or the part's chapters)
+- **Writes:** new files; never overwrites
+- **Exits 1:** on a usage error
+
+`--json`: [`NewJson`](#newjson)
+
+## content new term
+
+```text
+pnpm content new term <key> [--json]
+```
+
+- **For:** a shared notation card to start from
+- **Prints:** the card file it created
+- **Writes:** new files; never overwrites
+- **Exits 1:** on a usage error
+
+`--json`: [`NewJson`](#newjson)
+
+## content init-agent
+
+```text
+pnpm content init-agent [--write] [--json]
+```
+
+- **For:** 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
+- **Writes:** only with --write
+- **Exits 1:** on a usage error
+
+| Flag | Effect |
+| --- | --- |
+| `--write` | apply the edits; without it the diff is printed and nothing changes |
+
+`--json`: [`EditPlanJson`](#editplanjson)
+
+## content release
+
+```text
+pnpm content release [major|minor|patch] [--write] [--json]
+```
+
+- **For:** 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)
+- **Writes:** only with --write
+- **Exits 1:** on a usage error
+
+| Flag | Effect |
+| --- | --- |
+| `--write` | apply the edits; without it the diff is printed and nothing changes |
+
+`--json`: [`EditPlanJson`](#editplanjson)
+
+## content verify
+
+```text
+pnpm content verify [--e2e] [--force] [--json]
+```
+
+- **For:** 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
+- **Writes:** what validate:content and astro build write; logs and the pass record under node_modules/.cache/explico/verify/
+- **Exits 1:** on a usage error, and when a step fails
+
+| Flag | Effect |
+| --- | --- |
+| `--e2e` | also run the browser tests (the course's test:e2e script, or playwright test when it has a config) |
+| `--force` | run even when nothing changed since the last pass |
+
+`--json`: [`VerifyReport`](#verifyreport)
+
+## content help
+
+```text
+pnpm content help [<verb>] [--json]
+```
+
+- **For:** 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
+- **Writes:** nothing
+- **Exits 1:** on a usage error, and for an unknown verb
+
+`--json`: [`HelpJson`](#helpjson)
+
+## The `--json` types
+
+A `?` marks a property that may be absent.
+
+### BindingsReport
+
+```ts
+BindingsReport
+  lesson: string
+  file: string
+  scope: {…}[]
+    key: string
+    notation: string
+    scope: "shared" | "local"
+  spans: BindingsSpan[]
+  counts: {…}
+    spans: number
+    bindings: number
+    unresolved: number
+    wraps: number
+    redundantWraps: number
+    errors: number
+```
+
+### BindingsSpan
+
+```ts
+BindingsSpan
+  line: number
+  column: number
+  display: boolean
+  latex: string
+  unresolved: UnresolvedGlyph[]
+  error?: string  — The resolver rejected the span (a KaTeX parse error or a rule it enforces, N13 say); its message.
+  bindings: SpanBinding[]
+  wraps: ExplicitWrap[]
+```
+
+### CheckLessonResult
+
+```ts
+CheckLessonResult
+  lesson: string
+  file: string
+  ok: boolean
+  rendered: boolean
+  diagnostics: CliDiagnostic[]
+```
+
+### CheckReport
+
+```ts
+CheckReport
+  ok: boolean
+  lessons: CheckLessonResult[]
+```
+
+### CliDiagnostic
+
+```ts
+CliDiagnostic  — One normalized diagnostic. `code` is `<source>:<kind>` and always stable.
+  code: string
+  rule?: string  — The catalog entry that owns the code — a rule ID (`N9`) or an invariant slug (`keyed-floats`). Absent only for a code the catalog does not know, which `tests/rules/catalog.test.ts` treats as a bug.
+  doc?: string  — The owner's page and anchor under `docs/authoring/`, `notation.md#n4`.
+  severity: DiagnosticSeverity
+  message: string
+  file?: string
+  line?: number
+  column?: number
+  equation?: EquationLink  — The keyed equation the finding sits in, when the math carries a `\label{eq:…}` — `{ key, href }`, the href being the anchor on the rendered page. A size-only finding inside a long `aligned` block is otherwise anonymous.
+```
+
+### CliReference
+
+```ts
+CliReference  — `docs/authoring/cli-reference.json`, whole: what `content help --json` prints.
+  generatedBy: string  — Where it came from, and that it is generated.
+  verbs: ContentVerb[]
+  error: string  — The type every verb's `--json` prints when the run fails: a stable code and a message, never a stack.
+  $defs: Record<string, Record<string, unknown>>  — A JSON Schema of every type a verb's `--json` prints, and of every named type inside one, by name.
+```
+
+### ContentVerb
+
+```ts
+ContentVerb  — One verb's row.
+  verb: string  — The command word(s): `symbol`, `new lesson`.
+  args: string  — What follows the verb on the usage line, `--json` left out (every verb takes it).
+  when: string  — What you want to know or do when you reach for it.
+  prints: string  — What it prints as text.
+  flags: ContentVerbFlag[]  — The flags, each once; a positional argument is described in `prints` or `when`.
+  writes: string  — What it changes on disk.
+  exit?: string  — When it exits 1, beyond a usage error.
+  json: string  — The type its `--json` prints, by its exported name in `explico/compiler/cli`, `cli-main` or `cli-verify`.
+```
+
+### ContentVerbFlag
+
+```ts
+ContentVerbFlag  — One flag a verb takes.
+  flag: string  — As typed: `--lesson <id>`, `--write`.
+  description: string
+```
+
+### ContextReport
+
+```ts
+ContextReport
+  lesson: {…}
+    id: string
+    slug: string
+    file: string
+    title: string
+    description: string
+    teaches: string[]
+    requires: string[]
+    assumptions: string[]
+    since: null | string  — The version the page's content last changed in; `null` for a change not yet released (rule C5).
+    notationLocal: unknown
+    body: string
+  taughtOutcomes: {…}[]
+    id: string
+    outcome: string
+  prerequisiteOutcomes: {…}[]
+    id: string
+    outcome: string
+  notation: {…}[]
+    key: string
+    latex: string
+    meaning: string
+    scope: string
+    units?: string
+    formula?: string
+  equations: ManifestLessonFloat[]
+  tables: ManifestLessonFloat[]
+  figures: ManifestLessonFloat[]
+  diagrams: ManifestLessonFloat[]
+  examples: {…}[]  — Worked-example sets: `short` is the title `[[ex-key]]` names.
+    key: string
+    number: string
+    short?: string
+  knowledgeChecks: {…}[]
+    key: string
+    number: string
+    title?: string
+  sections: {…}[]  — The top-level headings: `slug` is what `[[sec-slug]]` names.
+    slug: string
+    text: string
+    level: number
+    number?: string
+  sources: {…}[]
+    id: string
+    title: string
+    type: string
+    recordLocator?: string
+    citedLocators: string[]
+  domainSignatures: DomainFileSignatures[]
+  diagnostics: CliDiagnostic[]
+  tokens: TokenCounts
+```
+
+### DiagnosticSeverity
+
+```ts
+DiagnosticSeverity = "error" | "warning" | "info"
+```
+
+### DiagnosticsReport
+
+```ts
+DiagnosticsReport
+  minimumSeverity: DiagnosticSeverity
+  count: number
+  diagnostics: CliDiagnostic[]
+```
+
+### DomainFileSignatures
+
+```ts
+DomainFileSignatures
+  file: string
+  signatures: string[]
+```
+
+### EditPlanJson
+
+```ts
+EditPlanJson  — `--json` of `move`, `rename`, `fix` and `init-agent`: the plan, and whether `--write` applied it.
+  summary: string[]
+  edits: FileEdit[]
+  next: string[]  — What to run after writing.
+  written: boolean  — True when `--write` applied the edits; false for a dry run.
+```
+
+### Editions
+
+```ts
+Editions = "chapter" | "deck" | "both"
+```
+
+### Element
+
+```ts
+Element = "slide" | "prose" | "math" | "equation" | "notation" | "heading" | "part-page" | "plot" | "diagram" | "table" | "assessment" | "source" | "changelog"  — The part of a page a rule is about. The first tag on an entry is primary.
+```
+
+### EquationLink
+
+```ts
+EquationLink  — The equation a finding sits in, when its math carries a `\label{eq:…}`. A location tells you where to edit; this tells you *what you are looking at*. A size-only N17 finding inside a six-line `aligned` block is otherwise anonymous — the message names delimiters, not the result they belong to — so the key and the rendered page's anchor both travel with the diagnostic.
+  key: string  — The label's key, without the `eq:` prefix.
+  href: string  — Where the reader sees it, e.g. `/l1-ar/ar1-basics/#eq-ar1-variance`.
+```
+
+### EquationReport
+
+```ts
+EquationReport  — One LaTeX string, resolved the way the gate will: against a lesson's scope, or against every shared card when no lesson is named (the table a notation entry's body and formula use). The inner loop while drafting: a few lines out, non-zero exit when the build would refuse the span.
+  latex: string
+  against: {…} | {…}
+  unresolved: UnresolvedGlyph[]
+  ok: boolean
+  error?: string  — The resolver rejected the span (a KaTeX parse error or a rule it enforces, N13 say); its message.
+  bindings: SpanBinding[]
+  wraps: ExplicitWrap[]
+```
+
+### ErrorJson
+
+```ts
+ErrorJson  — `--json` of any verb whose run failed: a stable code and a message, never a stack.
+  ok: false
+  error: {…}
+    code: "unknown-command" | "usage" | "unknown-lesson" | "unknown-kind" | "invalid-id" | "exists" | "not-a-lesson" | "no-git" | "unknown-version" | "migration-gap" | "unknown-key" | "no-changelog" | "internal"  — `internal` for an unexpected throw; every other code is stable.
+    message: string
+```
+
+### ExplicitWrap
+
+```ts
+ExplicitWrap
+  key: string
+  inner: string
+  redundant: boolean  — The bare `inner` resolves to exactly this card: the wrap costs tokens and binds nothing new.
+```
+
+### FileEdit
+
+```ts
+FileEdit
+  file: string  — Course-relative path.
+  before: null | string  — `null` when the file is created.
+  after: null | string  — `null` when the file is deleted.
+```
+
+### HelpJson
+
+```ts
+HelpJson = CliReference | VerbHelpJson  — `content help --json` prints the whole reference; `content help <verb> --json` that verb's rows.
+```
+
+### ManifestLessonFloat
+
+```ts
+ManifestLessonFloat  — One keyed float of a lesson (v21): its key and number, and its caption pair — `short` (an equation's `\caption{…}`, or the `short` prop) and, for a `<Table>` / `<Figure>` / `<Diagram>`, the long `caption`. Each is present only when the source states it as a literal.
+  key: string
+  number: string
+  short?: string
+  caption?: string
+```
+
+### MigrateReport
+
+```ts
+MigrateReport
+  from: string
+  to: string
+  file: string
+  sections: MigrationSection[]
+  tokens: number
+```
+
+### MigrationSection
+
+```ts
+MigrationSection
+  from: string
+  to: string
+  heading: string
+  markdown: string
+  tokens: number
+```
+
+### NewJson
+
+```ts
+NewJson  — `--json` of `new lesson`, `new deck` and `new term`.
+  ok: true
+  created: string[]  — Course-relative paths of the files it created.
+```
+
+### RetiredRule
+
+```ts
+RetiredRule  — A rule that is no longer in force. It keeps its ID forever — an old commit message, review comment or waiver naming `N3` must stay unambiguous — but it is deliberately *not* a {@link RuleEntry}: nothing iterates it as a rule, it has no page in `docs/authoring/`, it is absent from the settings schema and from `build/rules-in-effect.md`, and an agent never reads it while drafting. The one place it is written out is the generated table in `docs/authoring/retired.md`, which is where a migration guide links.
+  id: unknown | unknown | unknown | unknown | unknown | unknown | unknown
+  title: string  — The sentence the rule had, so an old reference to it still resolves.
+  date: string  — `YYYY-MM-DD`.
+  into?: unknown | unknown | unknown | unknown | unknown | unknown | unknown  — The rule it was folded into, when it was folded into one.
+  why: string  — Why, and what changed for an author — one or two sentences.
+```
+
+### RuleInEffect
+
+```ts
+RuleInEffect  — One rule as `content rules --json` reports it.
+  id: string
+  kind: "rule" | "invariant"
+  source: "engine" | "course"  — `course` for one of this course's own `X` rules; `engine` for the rest.
+  title: string
+  elements: Element[]
+  enforcement: "script" | "partial" | "guide" | "locked"
+  enabled: boolean
+  waivable: boolean  — May be waived at one place with `{/* explico-allow <ID>: reason *\/}`.
+  codes: string[]
+  settings: Record<string, unknown>
+  summary: string
+  doc: string
+  editions: Editions  — The edition it is about: `chapter`, `deck`, or `both`.
+```
+
+### RuleReport
+
+```ts
+RuleReport  — One rule, whole: the catalog entry as this course has it (enforcement, codes, settings in effect, whether it is on) and the rule page's own section, example included. About half a thousand tokens where opening the page costs twenty thousand.
+  id: string
+  status: "in-effect" | "retired" | "unknown"
+  rule?: RuleInEffect
+  retired?: RetiredRule
+  section?: {…}  — The rule page's section for this rule, when the page is at hand.
+    file: string
+    markdown: string
+    tokens: number
+  known: string[]  — For `unknown`: the IDs this course has, so the caller can pick one.
+```
+
+### RulesFilter
+
+```ts
+RulesFilter
+  elements?: Element[]  — Keep a rule whose elements (any, not just primary) include one of these.
+  enforcement?: "script" | "partial" | "guide" | "locked"
+  edition?: "chapter" | "deck"  — The edition the page is for: `chapter` (the default) or `deck`.
+```
+
+### RulesJson
+
+```ts
+RulesJson  — `--json` of `rules`: the report without its Markdown page.
+  filter: RulesFilter
+  count: number
+  rules: RuleInEffect[]
+```
+
+### SpanBinding
+
+```ts
+SpanBinding
+  token: string
+  key: string
+  how: string  — The resolver's match kind; `explicit` for an `\explain` wrap.
+```
+
+### StatusReport
+
+```ts
+StatusReport
+  knowledgeVersion: string  — The course's published knowledge version (`about.version`).
+  agentSurfaces: {…}[]  — What an agent is told to read before working, in estimated tokens: the course's `AGENTS.md`, the repository's one level up when the course is a workspace package, and the rules-in-effect page. A budget to watch; the estimate is bytes over four.
+    name: string
+    tokens: number
+  agentGuide: {…}  — Whether the course's own `AGENTS.md` points an agent at the engine's guide (`docs/authoring/agents.md`), and whether the procedures `content init-agent` installs are in `.claude/`.
+    agentsFile: null | string
+    linksGuide: boolean
+    skillsInstalled: boolean
+  pageVersions: {…}  — Rule C5: how many chapters and part pages carry a version of their own, and the slugs of those with a change `## [Unreleased]` has not released.
+    tracked: number
+    unreleased: string[]
+  counts: {…}
+    lessons: number
+    competencies: number
+    assessments: number
+    sources: number
+    tracks: number
+    notationDefinitions: number
+    keyedEquations: number
+    keyedTables: number
+    keyedFigures: number
+    keyedDiagrams: number
+    keyedExamples: number
+  orphans: CliDiagnostic[]
+  diagnostics: {…}
+    errors: number
+    warnings: number
+    infos: number
+```
+
+### SymbolHit
+
+```ts
+SymbolHit
+  tier: SymbolTier
+  key: string
+  latex: string
+  label: string
+  meaning?: string
+  units?: string
+  matchedBy: "latex" | "alias" | "key"  — How the query matched: the latex as written, an alias, or the key.
+  where: string  — shared: the entry file; local: the lesson id; gloss: the owning card.
+  boundIn?: string[]  — shared only: the pages (lessons and overview pages) whose bundle binds the card.
+```
+
+### SymbolReport
+
+```ts
+SymbolReport
+  query: string
+  shared: SymbolHit[]
+  local: SymbolHit[]
+  glosses: SymbolHit[]
+  contains: SymbolHit[]  — Entries whose latex contains the query as a glyph, not matched above.
+  containsTotal: number  — How many `contains` candidates there were before the list was capped.
+```
+
+### SymbolTier
+
+```ts
+SymbolTier = "shared" | "local" | "gloss"  — Where a hit is defined: a shared card, a lesson's `notation.local`, or a card's gloss.
+```
+
+### TokenCounts
+
+```ts
+TokenCounts
+  context: number  — Tokens in the serialized `content context` payload.
+  docSet: number  — `README.md` + `AGENTS.md` + `docs/architecture.md`.
+  corpus: number  — Every file under `content/`.
+  ratio: number  — `context / (docSet + corpus)`, rounded to 4 dp.
+```
+
+### UnresolvedGlyph
+
+```ts
+UnresolvedGlyph
+  token: string
+  suspended?: string
+  lenders?: string[]  — Rule N23: indexed entries whose base this bare letter is; none lends it a card.
+  defined: {…}[]  — Where `content symbol` finds the token defined: exact hits, then near misses.
+    tier: SymbolTier
+    key: string
+    where: string
+  near: {…}[]
+    latex: string
+    key: string
+```
+
+### VerbHelp
+
+```ts
+VerbHelp  — One verb's row, its usage line, and a self-contained JSON Schema of its `--json`.
+  usage: string
+  schema: Record<string, unknown>
+  verb: string  — The command word(s): `symbol`, `new lesson`.
+  args: string  — What follows the verb on the usage line, `--json` left out (every verb takes it).
+  when: string  — What you want to know or do when you reach for it.
+  prints: string  — What it prints as text.
+  flags: ContentVerbFlag[]  — The flags, each once; a positional argument is described in `prints` or `when`.
+  writes: string  — What it changes on disk.
+  exit?: string  — When it exits 1, beyond a usage error.
+  json: string  — The type its `--json` prints, by its exported name in `explico/compiler/cli`, `cli-main` or `cli-verify`.
+```
+
+### VerbHelpJson
+
+```ts
+VerbHelpJson  — What `content help <verb> --json` prints: every verb the word names (`new` names three).
+  verbs: VerbHelp[]
+```
+
+### VerifyReport
+
+```ts
+VerifyReport
+  ok: boolean
+  cached: boolean  — True when the tree is unchanged since a pass that covered as much: nothing ran, `steps` are that pass's.
+  since?: string  — When the recorded pass ran, for a cached answer (ISO 8601).
+  tree: null | string  — The hash of the tree the run left, or `null` outside a git repository (then nothing is recorded).
+  e2e: boolean  — Whether the browser tests were part of the run.
+  steps: VerifyStep[]
+```
+
+### VerifyStep
+
+```ts
+VerifyStep
+  name: VerifyStepName
+  status: "pass" | "fail" | "skipped"
+  command?: string  — The command it ran, as it would be typed; absent for a skipped step.
+  reason?: string  — Why it was skipped, or why it could not start.
+  seconds?: number
+  log?: string  — Course-relative path of its whole output.
+  tail?: string[]  — The last lines of the output of a failed step.
+```
+
+### VerifyStepName
+
+```ts
+VerifyStepName = "validate:content" | "check --changed" | "astro check" | "tests" | "astro build" | "e2e"
+```
+
+### WarningsReport
+
+```ts
+WarningsReport
+  count: number
+  warnings: CliDiagnostic[]
+```