explico 0.13.0 → 0.14.0

package/README.md

@@ -51,15 +51,39 @@ What it gives a course:
   tick-labeled axes, log scales, or several series sharing a scale; Observable
   Plot pays off once a course is authoring many charts per lecture. Pick per
   figure — nothing in the engine assumes one plotting approach.
+- **Slides from the same lesson** — a lesson's deck, `<lesson>.deck.mdx`, is
+  its slide edition: frames on a fixed canvas, steps that reveal, drive a lab
+  or light up a symbol, speaker notes, and the chapter's equations and figures
+  recalled with their numbers. The deck's page presents full screen, with a
+  presenter window, and as one offline HTML file; it exports to beamer slides
+  and a handout with every symbol linked to its entry, and to Marp's Markdown.
+  Rules D1–D10 keep frames short, and the build fails a frame that does not
+  fit. A lesson can also be slides only (`docs/authoring/deck.md`).
 - **LMS / analytics / identity seams** — framework-free interfaces shipped as
   no-ops; a host supplies real implementations without touching a component.
 - **A `content` CLI** — `status`, `diagnostics`, `warnings`, `context <lesson>`,
   `check <lesson>` (compiles MDX → remark → KaTeX and fails loudly),
-  `new lesson|term`.
+  `new lesson|term|deck`.
 
 The prerequisite graph itself is authored by the lecturer or an AI; the engine
 validates it (DAG, ordering, coverage, orphans) rather than inferring it.
 
+## Start from a working course
+
+Two complete courses built on explico are downloadable, always at their newest
+version, from **[https://danieltuzes.github.io/explico/start/](https://danieltuzes.github.io/explico/start/)**:
+
+- [the playground](https://danieltuzes.github.io/explico/downloads/explico-playground-latest.zip) — every engine feature on a short physics course, at
+  the engine's latest release, standalone (`pnpm install && pnpm
+  validate:content && pnpm dev`). A path in these docs that starts with
+  `playground/` is a file in it.
+- [credit-and-derivatives](https://danieltuzes.github.io/explico/downloads/credit-and-derivatives-latest.zip) — a full course as it is taught
+  ([repository](https://github.com/danieltuzes/credit-and-derivatives)).
+
+[`sources.json`](https://danieltuzes.github.io/explico/downloads/sources.json) lists both with the engine version, source commit and
+checksum. An agent reads [`docs/authoring/agents.md`](https://cdn.jsdelivr.net/npm/explico@latest/docs/authoring/agents.md) first
+(`node_modules/explico/docs/authoring/agents.md` once installed).
+
 ## Install
 
 ```bash
@@ -72,7 +96,7 @@ Peer dependencies (the course provides them, pinned): `astro`,
 
 ## Use
 
-A course provides `content/` (the six collections + `content/domain/` +
+A course provides `content/` (the engine collections + `content/domain/` +
 `content/course.config.ts`) and wires the engine in three places:
 
 ```ts
@@ -97,36 +121,49 @@ import rehypeHeadingAnchors from 'explico/reference/rehype-heading-anchors.mjs';
 import { courseConfig } from './content/course.config.ts';
 
 const manifest = await loadManifest(courseConfig);
-// markdown.remarkPlugins: [
-//   remarkMath,
-//   remarkShortNote,
-//   remarkMemo,
-//   // `createRemarkNotationOptions` reads every numbering input off one
-//   // manifest — the equation / table / figure number tables *and* the part
-//   // each lesson sits in — so they can't drift apart. `strict: true` fails
-//   // the build when a catalogued lesson has equations/tables/figures but no
-//   // numbering or cross-page entry, instead of silently numbering it by
-//   // `##` section while references to it read the part scheme.
-//   // `base` is the Astro `base` of a subpath deployment (e.g. a GitHub
-//   // Pages project site); the links these plugins write 404 without it.
-//   [remarkNotation, createRemarkNotationOptions(manifest, { strict: true, base })],
-//   // The generated References section's first state, from the course's
-//   // `disclosure` settings block (`CourseConfig.disclosure`).
-//   [remarkCitation, {
-//     sources: manifest.sources,
-//     defaultOpen: courseConfig.disclosure?.references?.defaultOpen === true,
-//   }],
-//   // Last: renders `:::note` / `:::tip` / `:::caution` / `:::danger` as
-//   // Starlight's `<Aside>` (Starlight's own pass skips `content/docs/`).
-//   remarkAsides,
-// ]
+// import { unified } from '@astrojs/markdown-remark';
+// import remarkMath from 'remark-math';
+// import rehypeKatex from 'rehype-katex';
+//
+// markdown: {
+//   // Astro 7.3 deprecates the flat `markdown.remarkPlugins` / `rehypePlugins`
+//   // lists; the plugins go to `unified()` instead.
+//   processor: unified({
+//     remarkPlugins: [
+//       remarkMath,
+//       remarkShortNote,
+//       remarkMemo,
+//       // `createRemarkNotationOptions` reads every numbering input off one
+//       // manifest — the equation / table / figure number tables *and* the part
+//       // each lesson sits in — so they can't drift apart. `strict: true` fails
+//       // the build when a catalogued lesson has equations/tables/figures but no
+//       // numbering or cross-page entry, instead of silently numbering it by
+//       // `##` section while references to it read the part scheme.
+//       // `base` is the Astro `base` of a subpath deployment (e.g. a GitHub
+//       // Pages project site); the links these plugins write 404 without it.
+//       [remarkNotation, createRemarkNotationOptions(manifest, { strict: true, base })],
+//       // The generated References section's first state, from the course's
+//       // `disclosure` settings block (`CourseConfig.disclosure`).
+//       [remarkCitation, {
+//         sources: manifest.sources,
+//         defaultOpen: courseConfig.disclosure?.references?.defaultOpen === true,
+//       }],
+//       // Last: renders `:::note` / `:::tip` / `:::caution` / `:::danger` as
+//       // Starlight's `<Aside>` (Starlight's own pass skips `content/docs/`).
+//       remarkAsides,
+//     ],
+//     rehypePlugins: [
+//       [rehypeKatex, createNotationKatexOptions()],
+//       rehypeFailKatexErrors,
+//       // Heading collapse defaults: the same `disclosure` block.
+//       [rehypeHeadingAnchors, { defaultCollapsible: courseConfig.disclosure }],
+//     ],
+//   }),
+// },
 // … integrations: [explicoContentRefresh(courseConfig, manifest),
 //                  starlight({ customCss: ['explico/styles/global.css'],
 //               components: { Footer: 'explico/components/starlight/LessonFooter.astro',
 //                             SocialIcons: 'explico/components/starlight/LayoutSocialIcons.astro', … } })
-// … rehypePlugins: [[rehypeKatex, createNotationKatexOptions()], rehypeFailKatexErrors,
-//                   // Heading collapse defaults: the same `disclosure` block.
-//                   [rehypeHeadingAnchors, { defaultCollapsible: courseConfig.disclosure }]]
 ```
 
 `loadManifest(courseConfig)` always recompiles current content before Astro
@@ -185,6 +222,68 @@ or, without one, the numbers and short captions of the floats inside
 </Fold>
 ```
 
+### A page for paths that miss
+
+Starlight looks for a docs entry named `404` on every build. Give the course a
+`content/docs/404.mdx`; without it, Astro falls back correctly but prints
+`Entry docs → 404 was not found`. This small page uses Astro's `BASE_URL`, so
+its links work both at `/` and below a deployment `base`:
+
+```mdx
+---
+title: "404: Page outside the syllabus"
+description: The requested course page could not be found.
+template: splash
+hero:
+  title: "404"
+  tagline: We followed this URL as far as the course map goes. It does not land on a page.
+pagefind: false
+sidebar:
+  hidden: true
+editUrl: false
+---
+
+import { LinkButton } from '@astrojs/starlight/components';
+
+<div style="display: flex; justify-content: center;">
+  <LinkButton href={import.meta.env.BASE_URL} icon="left-arrow" iconPlacement="start">
+    Return to the course
+  </LinkButton>
+</div>
+```
+
+Let the docs entry own `/404.html` by turning off Starlight's otherwise
+duplicate special route:
+
+```js
+starlight({
+  disable404Route: process.env.NODE_ENV === 'production',
+  // …the course's other Starlight settings
+})
+```
+
+That keeps Starlight's catch-all page during development. In a static build,
+the authored docs entry supplies `/404.html`; disabling the duplicate injected
+route there prevents a route-collision warning.
+
+Set Astro's `site` to the published origin too; Starlight's sitemap integration
+skips itself, with a warning, when it is missing. Keep a subpath in `base`, not
+in `site`:
+
+```js
+export default defineConfig({
+  site: 'https://example.edu',
+  base: '/course/',
+  // …
+});
+```
+
+`explico/content-config` also exports Starlight's `i18n` collection. It supplies
+an empty English fallback for a course with no translations, avoiding Astro's
+empty-collection warning. To translate the interface, add
+`content/i18n/<locale>.json` (or `.yml` / `.yaml`); those authored entries are
+loaded instead.
+
 ### Lesson exports
 
 A course can opt into self-contained HTML downloads of each chapter, each part
@@ -233,6 +332,12 @@ the same file becomes a link into it, whose hover preview works offline. Each
 page is a section with `content-visibility: auto`, which keeps a long course
 responsive, and starts a new sheet when printed.
 
+A lesson's deck (`docs/authoring/deck.md`) has a row of its own in the menu, on
+its page and on its chapter's: `downloads/<lesson>-slides.html` presents
+offline, with its notes, labs and checks; with `latex`, `-slides.pdf` and the
+handout `-slides-notes.pdf` compile in beamer from `-slides-latex.zip`; with
+`markdown`, `-slides-markdown.zip` holds the deck in Marp's dialect.
+
 The **Print / save as PDF** action calls the browser's native print dialog; it
 does not download or build a `.pdf` file itself. The print layout removes site
 chrome and prints every disclosure as the reader left it on screen: an open
@@ -311,9 +416,74 @@ and still writes the source zips. On GitHub Actions:
 - run: pnpm build
 ```
 
+A course sets no cookies and loads nothing from another site. It asks each
+reader once, at the bottom of the window, whether it may remember their
+reading in their browser (the chapters they opened, the cards they keep or
+carry), and keeps nothing of it beyond the tab without a yes; settings the
+reader chooses are kept either way, and the `[?]` panel changes the answer or
+forgets everything. `readingMemory: "off"` in the course settings never asks.
+[`docs/privacy.md`](docs/privacy.md) lists every key and when it is written,
+for a course's own privacy notice.
+
+Each part of the page has a colour of its own, so a reader can tell the
+course's tools, its contents, the page's outline and the text apart:
+`appearance.zones` in the course settings is `tonal` (the default, neutral
+grey steps), `accent-header` (the header in the course's accent), `paper`
+(the text as a sheet on a desk) or `none`, and `appearance.slides` gives each
+slide on a deck's page an edge and a shadow (`lifted`, `edge` or `sorter`).
+
+Every document says which version its content is at (rule C5): "From
+*Course*, unchanged since version 0.2.0." under a chapter's title, the release
+its content last changed in, or "with changes after version 0.4.0, not yet
+released" while `content/CHANGELOG.md`'s `## [Unreleased]` holds a change to
+it; a part's and the course's PDF carry the newest among their pages, and the
+`[?]` panel shows the same line on the page. The record behind it is
+`content/versions.json`, which `pnpm validate:content` writes and the course
+commits with each content change, like a lockfile; in CI a stale record fails
+the build.
+
+Every build compiles every document, one LuaLaTeX run per chapter, part and
+the course. `EXPLICO_LATEX_CACHE=<directory>` keeps each compile there, keyed
+by every file of the document's folder, the TeX installation and the
+document's date, and reuses it while they are unchanged: a push that changes
+one chapter compiles that chapter, its part and the course, and so does a
+release, since an unchanged document keeps its version line and its date. The build's summary line says
+how many it compiled and reused. `EXPLICO_LATEX_CACHE_SALT` is the escape
+hatch for what the key cannot see, such as a package updated with `tlmgr`.
+Entries no build has used for a week are deleted. In CI, restore the
+directory before the build and save it under a new key after:
+
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: .cache/explico-latex
+    key: explico-latex-${{ github.sha }}
+    restore-keys: explico-latex-
+- run: pnpm build
+  env:
+    EXPLICO_LATEX_CACHE: .cache/explico-latex
+```
+
 ```jsonc
-// package.json — the read-side CLI
-"scripts": { "validate:content": "tsx scripts/compile-manifest.ts" }
+// package.json
+"scripts": {
+  "validate:content": "tsx scripts/compile-manifest.ts",
+  "content": "tsx scripts/content.ts"
+}
+```
+
+Both scripts are three lines; the engine owns what they run:
+
+```ts
+// scripts/compile-manifest.ts
+import { runValidateContent } from 'explico/compiler/validate-content';
+import { courseConfig } from '../content/course.config';
+process.exitCode = await runValidateContent(courseConfig);
+
+// scripts/content.ts — `pnpm content help` lists every verb
+import { runContentCli } from 'explico/compiler/cli-main';
+import { courseConfig } from '../content/course.config';
+process.exitCode = await runContentCli(courseConfig);
 ```
 
 Diagnostics have three distinct severities: an `error` blocks validation because

package/dist/compiler/astro.d.ts

@@ -1,6 +1,7 @@
 import { AstroConfig, AstroIntegration } from 'astro';
-import { C as CourseConfig } from '../course-config-rRtME5UV.js';
+import { C as CourseConfig } from '../course-config-BLtIdkei.js';
 import { Manifest } from './manifest.js';
+import { RenderDiagnostic } from './render-diagnostics.js';
 import '../rules/catalog.js';
 import '../rules/course-rules.js';
 import '../curriculum/validation.js';
@@ -24,6 +25,10 @@ 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';
 
 /** Match only a configured page artifact below Astro's deployment base. */
@@ -48,6 +53,14 @@ type MarkdownConfig = AstroConfig['markdown'];
  * text with no signal anywhere.
  */
 declare function assertRemarkPluginsWired(manifest: Pick<Manifest, 'abbreviations' | 'sources' | 'notation'>, markdown: MarkdownConfig): void;
+/**
+ * Check every built page, and return the findings only a rendered page gives
+ * (`render-diagnostics.ts`) for `content warnings`. A page that fails a check
+ * does not stop the walk: every page is read first, then the build throws once
+ * with the whole list, so it reports each page at once and not one per run.
+ * Exported for the test.
+ */
+declare function validateGeneratedPages(directory: URL, manifest: Pick<Manifest, 'lessons'>, warn: (message: string) => void): Promise<RenderDiagnostic[]>;
 /**
  * Restart Astro when an authored content file changes. Astro reloads MDX on
  * its own, but Explico's manifest is created by `astro.config.mjs`; a restart
@@ -58,4 +71,4 @@ declare function assertRemarkPluginsWired(manifest: Pick<Manifest, 'abbreviation
  */
 declare function explicoContentRefresh(courseConfig: CourseConfig, manifest: Manifest): AstroIntegration;
 
-export { assertLocalNotationParity, assertNotationPayloadHtml, assertRemarkPluginsWired, explicoContentRefresh, matchStandaloneDownload };
+export { assertLocalNotationParity, assertNotationPayloadHtml, assertRemarkPluginsWired, explicoContentRefresh, matchStandaloneDownload, validateGeneratedPages };

package/dist/compiler/astro.js

@@ -8,7 +8,10 @@ import {
   writeManifest
 } from "./manifest.js";
 import { missingNotationPayloadKeys } from "../reference/page-notation.js";
-import { assertFigureSymbolsBound } from "../reference/figure-symbols.js";
+import {
+  assertNoUnboundFigureSymbols,
+  unboundFigureSymbols
+} from "../reference/figure-symbols.js";
 import { undrawnFigurePictures, undrawnFigureWarning } from "../reference/figure-pictures.js";
 import {
   pageRenderDiagnostics,
@@ -20,7 +23,8 @@ import { writeLatexExports } from "./exports/latex-export.js";
 import { writeMarkdownExports } from "./exports/markdown-export.js";
 import { prepareChapters } from "./exports/export-chapters.js";
 import { writeDownloadIndex } from "./exports/download-index.js";
-import { standaloneFilename, standalonePageSlugs } from "./exports/export-pages.js";
+import { checkFrameFit } from "./exports/deck-fit.js";
+import { standaloneDownloads, standaloneFilename } from "./exports/export-pages.js";
 import remarkAbbreviations from "../reference/remark-abbreviations.mjs";
 import remarkCitation from "../reference/remark-citation.mjs";
 import remarkNotation from "../reference/remark-notation.mjs";
@@ -124,17 +128,17 @@ function assertRemarkPluginsWired(manifest, markdown) {
   const missing = [];
   if (manifest.abbreviations.length > 0 && !remarkPluginIsWired(remarkPlugins, remarkAbbreviations)) {
     missing.push(
-      `remarkAbbreviations is missing from markdown.remarkPlugins, but manifest.abbreviations has ${manifest.abbreviations.length} entr${manifest.abbreviations.length === 1 ? "y" : "ies"}. Import it from 'explico/reference/remark-abbreviations.mjs' and add [remarkAbbreviations, { abbreviations: manifest.abbreviations }] to markdown.remarkPlugins \u2014 see docs/authoring/migrating.md#4-rule-n14.`
+      `remarkAbbreviations is missing from the remark plugins of astro.config.mjs, but manifest.abbreviations has ${manifest.abbreviations.length} entr${manifest.abbreviations.length === 1 ? "y" : "ies"}. Import it from 'explico/reference/remark-abbreviations.mjs' and add [remarkAbbreviations, { abbreviations: manifest.abbreviations }] to the \`remarkPlugins\` of \`markdown.processor: unified({ \u2026 })\` \u2014 see docs/authoring/migrating.md#4-rule-n14.`
     );
   }
   if (manifest.sources.length > 0 && !remarkPluginIsWired(remarkPlugins, remarkCitation)) {
     missing.push(
-      `remarkCitation is missing from markdown.remarkPlugins, but manifest.sources has ${manifest.sources.length} entr${manifest.sources.length === 1 ? "y" : "ies"}. Import it from 'explico/reference/remark-citation.mjs' and add [remarkCitation, { sources: manifest.sources }] to markdown.remarkPlugins.`
+      `remarkCitation is missing from the remark plugins of astro.config.mjs, but manifest.sources has ${manifest.sources.length} entr${manifest.sources.length === 1 ? "y" : "ies"}. Import it from 'explico/reference/remark-citation.mjs' and add [remarkCitation, { sources: manifest.sources }] to the \`remarkPlugins\` of \`markdown.processor: unified({ \u2026 })\`.`
     );
   }
   if (manifest.notation.raw.length > 0 && !remarkPluginIsWired(remarkPlugins, remarkNotation)) {
     missing.push(
-      `remarkNotation is missing from markdown.remarkPlugins, but manifest.notation.raw has ${manifest.notation.raw.length} entr${manifest.notation.raw.length === 1 ? "y" : "ies"}. Import it from 'explico/reference/remark-notation.mjs' and add [remarkNotation, createRemarkNotationOptions(manifest)] to markdown.remarkPlugins.`
+      `remarkNotation is missing from the remark plugins of astro.config.mjs, but manifest.notation.raw has ${manifest.notation.raw.length} entr${manifest.notation.raw.length === 1 ? "y" : "ies"}. Import it from 'explico/reference/remark-notation.mjs' and add [remarkNotation, createRemarkNotationOptions(manifest)] to the \`remarkPlugins\` of \`markdown.processor: unified({ \u2026 })\`.`
     );
   }
   if (missing.length === 0) return;
@@ -146,16 +150,27 @@ ${missing.map((line) => `  - ${line}`).join("\n")}`
 async function validateGeneratedPages(directory, manifest, warn) {
   const root = fileURLToPath(directory);
   const rendered = [];
+  const failures = [];
+  const unbound = [];
+  const messageOf = (error) => error instanceof Error ? error.message : String(error);
   const walk = async (path) => {
-    for (const entry of await readdir(path, { withFileTypes: true })) {
+    const entries = (await readdir(path, { withFileTypes: true })).sort(
+      (a, b) => a.name.localeCompare(b.name)
+    );
+    for (const entry of entries) {
       const child = join(path, entry.name);
       if (entry.isDirectory()) {
         await walk(child);
       } else if (entry.isFile() && entry.name.endsWith(".html")) {
         const html = await readFile(child, "utf8");
         const page = relative(root, child);
-        assertNotationPayloadHtml(page, html);
-        assertFigureSymbolsBound(page, html);
+        try {
+          assertNotationPayloadHtml(page, html);
+        } catch (error) {
+          failures.push(messageOf(error));
+        }
+        const figures = unboundFigureSymbols(html);
+        if (figures.length > 0) unbound.push({ page, figures });
         const undrawn = undrawnFigurePictures(html);
         if (undrawn.length > 0) warn(undrawnFigureWarning(page, undrawn));
         rendered.push(...pageRenderDiagnostics(manifest, page, html));
@@ -163,6 +178,12 @@ async function validateGeneratedPages(directory, manifest, warn) {
     }
   };
   await walk(root);
+  try {
+    assertNoUnboundFigureSymbols(unbound);
+  } catch (error) {
+    failures.push(messageOf(error));
+  }
+  if (failures.length > 0) throw new Error(failures.join("\n\n"));
   return rendered;
 }
 function replaceInPlace(target, source) {
@@ -260,7 +281,7 @@ function explicoContentRefresh(courseConfig, manifest) {
             const slug = matchStandaloneDownload(
               pathname,
               configuredDevelopment.base,
-              standalonePageSlugs(manifest)
+              standaloneDownloads(manifest).map(({ download }) => download)
             );
             if (!slug) return next();
             try {
@@ -269,7 +290,7 @@ function explicoContentRefresh(courseConfig, manifest) {
               );
               developmentDownloads ??= buildDevelopmentDownloads(
                 configuredDevelopment,
-                standalonePageSlugs(manifest)
+                standaloneDownloads(manifest).map(({ download }) => download)
               );
               const currentDownloads = developmentDownloads;
               currentDownloads.catch(() => {
@@ -310,6 +331,13 @@ ${message}
         for (const diagnostic of writeRenderDiagnostics(rendered)) {
           logger.warn(`[${diagnostic.code}] ${diagnostic.file}: ${diagnostic.message}`);
         }
+        const overflowing = await checkFrameFit(fileURLToPath(dir), manifest, { logger });
+        if (overflowing.length > 0) {
+          throw new Error(
+            `${overflowing.length} deck frame(s) do not fit their canvas (rule D2, frame-overflow):
+` + overflowing.map((finding) => `  - ${finding.message}`).join("\n")
+          );
+        }
         await writeStandaloneLessonExports(dir, manifest);
         await writeCombinedExports(dir, manifest);
         const { latex, markdown } = manifest.lessonExports;
@@ -326,5 +354,6 @@ export {
   assertNotationPayloadHtml,
   assertRemarkPluginsWired,
   explicoContentRefresh,
-  matchStandaloneDownload
+  matchStandaloneDownload,
+  validateGeneratedPages
 };

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

@@ -0,0 +1,43 @@
+import { C as CourseConfig } from '../course-config-BLtIdkei.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.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]";
+interface ContentArgs {
+    readonly command: string;
+    readonly positionals: readonly string[];
+    readonly json: boolean;
+    readonly changed: boolean;
+    /** `--element a,b` — a value-taking flag; also `--element=a,b`. */
+    readonly element?: string;
+    /** `--enforcement script` — a value-taking flag; also `--enforcement=script`. */
+    readonly enforcement?: string;
+    /** `--edition deck` — a value-taking flag; also `--edition=deck`. */
+    readonly edition?: string;
+    /** `--all`: list every diagnostic instead of the counts. */
+    readonly all: boolean;
+    /** `--code <code>`: only that diagnostic code. */
+    readonly code?: string;
+    /** `--lesson <id>`: only that lesson's diagnostics; the scope for `equation`. */
+    readonly lesson?: string;
+    /** `--from <version>` / `--to <version>` for `migrate`; `--to <key>` for `move`. */
+    readonly from?: string;
+    readonly to?: string;
+    /** `--write`: apply a planned edit instead of only showing its diff. */
+    readonly write: boolean;
+}
+declare function parseContentArgs(argv: readonly string[]): ContentArgs;
+/** Where a run prints; the process streams by default, a buffer in a test. */
+interface ContentIo {
+    readonly out: (text: string) => void;
+    readonly err: (text: string) => void;
+}
+/**
+ * Run one `content` command for this course and return its exit code: 0 on
+ * 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>;
+
+export { CONTENT_USAGE, type ContentArgs, type ContentIo, parseContentArgs, runContentCli };