explico 0.4.0 → 0.5.0

package/docs/authoring/structure.md

@@ -105,12 +105,14 @@ Part 2  Projectile motion
 
 ## Numbering
 
-A display equation, `<Table>`, or `<Figure>` is numbered **`‹part›.‹n›`**:
+A display equation, `<Table>`, `<Figure>`, `<Diagram>`, or knowledge check is
+numbered **`‹part›.‹n›`**:
 
 - **`part`** is the part's 1-based position in `courseConfig.parts`.
-- **`n`** counts that kind of float across the *whole part*, in document order,
-  running unbroken from one chapter into the next. Each kind counts on its own,
-  so a `<Table>` never advances the `<Figure>` sequence.
+- **`n`** counts that kind of numbered item across the *whole part*, in document
+  order, running unbroken from one chapter into the next. Each kind counts on
+  its own, so a `<Table>` never advances the `<Figure>`, `<Diagram>`, or
+  knowledge-check sequence.
 - **Sections and subsections do not participate.** Neither `##` nor `###`
   resets `n` or appears in the number.
 - **Keyed or not, everything counts.** An equation with no `\label{eq:…}` still
@@ -121,8 +123,8 @@ In the playground: part 1 runs `1.1` … `1.7` through chapter 1 and continues
 `1.8` in chapter 2; part 2 opens at `2.1`.
 
 `manifest.lessons[]` carries what the render path needs to reproduce this:
-`part`, `chapter`, and `numbering.{equations,tables,figures}` — the running
-count each chapter starts from.
+`part`, `chapter`, and `numbering.{equations,tables,figures,diagrams,checks}` —
+the running count each chapter starts from.
 
 ### The invariant, and why it is build-enforced
 
@@ -135,5 +137,115 @@ This exists because the disagreement is otherwise silent and shipped: a course
 config that passed the manifest number tables without the placement map
 numbered its pages by `##` section while every reference to them read the
 manifest, so one equation was `(2.2)` on its own page and `(4.5)` everywhere
-else. Wire the plugin by handing it the whole manifest — `[remarkNotation,
-{ definitions: manifest.notation.raw, manifest }]` — and the two cannot drift.
+else. Wire the plugin with `createRemarkNotationOptions`, which reads
+`definitions`, `manifest`, and every numbering input off one manifest in one
+call so they cannot drift apart:
+
+```js
+import remarkNotation, {
+  createRemarkNotationOptions,
+} from 'explico/reference/remark-notation.mjs';
+
+// [remarkNotation, createRemarkNotationOptions(manifest, { strict: true })]
+```
+
+That cross-check only ever caught a disagreement for a *keyed* equation or
+float — an unkeyed one still took a number, but nothing compared it against
+the manifest, so a lesson whose only equations/tables/figures were unkeyed
+could still silently fall back to `##`-section numbering with no error at all.
+`strict: true` closes that: it fails the build when a catalogued lesson
+contains any equation, `<Table>`, or `<Figure>` — keyed or not — but has no
+`numbering` placement or no cross-page number table entry for its slug.
+`<Diagram>` is exempt, since `Diagram.astro` already renders one without a
+number by design when it has none. `strict` defaults to `false`, so existing
+non-strict wiring keeps building unchanged; turn it on once a course's
+manifest covers every catalogued lesson.
+
+### Raw and unwrapped floats
+
+A raw Markdown pipe table or a raw HTML `<table>` written directly into a
+lesson — never wrapped in `<Table>` — renders fine but never enters keyed-float
+validation: it has no number and `[[tab-…]]` cannot reach it. The same is true
+of an `<Diagram>` with no `id`, and of a `<Diagram>` nested inside anything but
+`<Memo>`/`<ShortNote>`/`<Table>`/`<Figure>` — `keyed-jsx-floats.mjs` only scans
+top-level (and `<Memo>`/`<ShortNote>`-nested) occurrences, so a diagram buried
+inside e.g. `<CompactExample>` never reaches diagram numbering at all.
+
+The compiled manifest flags all four as warnings in `diagnostics.rawFloats`
+(`raw-table-markdown`, `raw-table-html`, `diagram-unkeyed`, `diagram-nested`),
+and `remarkNotation` reports the same at render time as a defense-in-depth
+check for content added since the manifest was last compiled. None of these
+fail the build — they are advisory, independent of `strict` — but a course
+that wants them addressed should wrap the table in `<Table id="…">`/
+`<Figure id="…">`, or give the diagram an `id` and move it to the top level (or
+inside `<Memo>`/`<ShortNote>`), or wrap it in `<Figure>`.
+
+### Knowledge checks
+
+An assessment title is authored once, in `content/assessments/<id>.json`. Put
+that id in the lesson's colocated `.checks.yml`, then render `<AssessmentSet />`;
+do not add a separate “Check yourself” heading. The component renders
+`Knowledge check ‹number› — ‹title›` as a permalinked, collapsible section at
+`#check-<id>`. Cite it on the same page with `[[check-<id>]]`, or from another
+lesson with `[[lesson/slug#check-<id>]]`. Single-choice options are shuffled
+when the browser views the check; option ids, correctness, and authored content
+remain unchanged.
+
+## Detailed memos and inline short notes
+
+Headings define the page's conceptual hierarchy: they belong in the outline and
+should help every reader navigate the main argument. A `<Memo>` instead holds
+optional depth — a long derivation, proof, robustness check, edge case, or
+alternative method — without pretending that material is another section of
+the lecture. It keeps the subsection-like card, background, and border, but is
+collapsed and independently numbered.
+
+Register `remarkShortNote` and then `remarkMemo` after `remarkMath` in
+`astro.config.mjs`. Import `explico/components/memo/Memo.astro`, cite a memo with
+`[[memo-id]]` wherever it is relevant, and place the flow block later:
+
+```mdx
+The full calculation is available in [[memo-supporting-check]].
+
+Several paragraphs may intervene before the detailed material.
+
+<Memo id="supporting-check" title="Supporting check" description="The detailed calculation behind the claim.">
+
+The body can contain ordinary Markdown, display equations, `<Table>`, and
+`<Figure>` components.
+
+</Memo>
+```
+
+`[[memo-supporting-check]]` renders as `[1]`. Clicking it opens and scrolls to
+the block and updates the URL to `#memo-supporting-check`; the `[1]` shown on
+the memo itself remains a numbered permalink, and the chain icon beside its
+title provides the same explicit anchor affordance used by headings and
+figures. `id`, `title`, and `description` are required literal strings. The
+block is collapsed on a reader's first visit and remembers later open/closed
+choices unless `rememberState={false}` is set. Memo numbering is independent
+of equation, table, figure, and diagram numbering. Those numbered items remain
+in their normal page/part streams inside a memo.
+
+For print and PDF export, the memo opens at its reading-order position. It does
+not move to the bottom of the page: browser support for CSS footnote floats is
+not reliable enough to make that layout portable.
+
+Use `<ShortNote>` for the smaller, genuinely inline interaction. Import
+`explico/components/memo/ShortNote.astro` and put it exactly where its collapsed
+link belongs:
+
+```mdx
+The derivative agrees <ShortNote id="derivative" title="(show how)" description="Show the full calculus calculation.">
+
+Take the derivative, set it to zero, and solve. The body may also contain
+display equations, figures, or other block Markdown.
+
+</ShortNote>. But symmetry is quicker.
+```
+
+While collapsed, the surrounding sentence remains one paragraph and only the
+`title` text is visible. Activating it hides that link, inserts the body at that
+point in the reading flow, and exposes a “Show less” control that restores the
+original sentence. Short notes are for a locally optional explanation, not for
+material that needs a number or citations elsewhere; use a memo for that.

package/docs/authoring/visualizations.md

@@ -31,11 +31,40 @@ identically in print and with JS off.
 _How to apply._ Pass `nodes` / `edges` and, if any node has a `formula`, a
 `scope` from `labMathScope` — see
 `playground/content/labs/DerivationDiagram.astro`. A `formula` node's symbols
-must resolve against the page glyph table, same as `NotationFormula`. If
+must resolve against the page glyph table, same as `NotationFormula`. Pass the
+component's formula source to `labMathScope`; when it names a shared key that
+the lesson MDX does not, also pass
+`{ locals: Astro.locals, context: '<ComponentName> <formula context>' }` so the
+key joins that page's notation payload. `Diagram` independently registers the
+keys it ultimately emits, which protects wrapper components and supplies a
+node-specific build diagnostic. If
 `Diagram` genuinely cannot express the picture, raise it as an engine gap
 rather than reaching for another library.
 
-_Enforcement._ Review-only.
+A top-level lesson diagram must expose an authored `id` on an MDX element named
+`Diagram` (a wrapper component may be imported under that name). It then receives
+an independent diagram number, a `#dia-<id>` anchor, and references of the form
+`[[dia-<id>]]` or `[[lesson/slug#dia-<id>]]`. Diagram numbers do not advance the
+equation, table, or figure sequences.
+
+The component preserves the build-time canvas size and scrolls horizontally
+when the work area is narrower. A compact control on the title line can expand
+the original diagram toward the full in-page region and shrink it back; it is
+not modal, follows the diagram's document position while the page scrolls, and
+adds internal vertical scrolling when the viewport is too short. The shrink
+control or Escape restores its original width. Clicking the title minimizes/
+restores the diagram and its text description; this state is remembered per
+page by default (`defaultOpen` / `rememberState` configure it).
+The title also carries the same chain-link permalink treatment as headings.
+
+By default a laid-out width above `800px` emits a compile-time warning. Treat
+that warning as a prompt to try
+`direction="TB"`, shorter labels, or explicit node sizes before accepting the
+wide layout. Set `warnAboveWidth={false}` only when horizontal overflow is
+intentional, or set a positive pixel value when the course needs a different
+review threshold.
+
+_Enforcement._ Review-only, with a compile-time width warning from `Diagram`.
 
 _Exceptions._ A one-off illustrative schematic that is not a graph (a labelled
 photo, a geometric figure) is a [V2](#v2) figure, not a `Diagram`.
@@ -83,7 +112,11 @@ An interactive figure is a React island, hydrated `client:visible` (or
 - **Gate-checked math.** Any equation shown in the figure goes through the
   `labMathScope` / `renderLabMath` / `\slot{}` seam so its symbols are resolved
   against the page's real notation at build time and the island only patches
-  numbers into pre-rendered KaTeX. See
+  numbers into pre-rendered KaTeX. A wrapper whose template names notation not
+  otherwise present in lesson MDX passes
+  `{ locals: Astro.locals, context: '<ComponentName> <template>' }` as the third
+  `labMathScope` argument; that is the declaration that ships those definitions
+  in this page's popup payload. See
   `playground/content/labs/ProjectileRangeExplorer.tsx` +
   `ProjectileRangeMath.astro`.
 - **An accessible name and description** — `ariaLabel` / `ariaDescription` on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Build-time engine for prerequisite-aware, notation-rigorous course content: one validated content model, a semantic notation/citation/equation system with a completeness gate, and a deterministic JSON manifest.",
   "type": "module",
   "license": "UNLICENSED",
@@ -33,7 +33,9 @@
     "docs/authoring"
   ],
   "dependencies": {
-    "@dagrejs/dagre": "3.1.1"
+    "@dagrejs/dagre": "3.1.1",
+    "esbuild": "0.27.7",
+    "parse5": "7.3.0"
   },
   "peerDependencies": {
     "@astrojs/markdown-remark": "7.2.4",
@@ -62,6 +64,7 @@
   },
   "scripts": {
     "build": "tsup && node scripts/copy-assets.mjs && node scripts/fix-esm-extensions.mjs && tsc -p tsconfig.dts-mjs.json",
+    "check:release-migration": "node scripts/check-release-migration.mjs",
     "test": "vitest run",
     "test:watch": "vitest"
   }

package/src/compiler/astro.ts

@@ -1,17 +1,101 @@
-import { resolve, sep } from 'node:path';
+import { mkdtemp, readdir, readFile, rm } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawn } from 'node:child_process';
 
-import type { AstroIntegration } from 'astro';
+import type { AstroConfig, AstroIntegration } from 'astro';
 import type { CourseConfig } from './course-config';
 import {
   compileManifest,
   type Manifest,
   writeManifest,
 } from './manifest';
+import { missingNotationPayloadKeys } from '../reference/page-notation';
+import { writeStandaloneLessonExports } from './exports/standalone-html';
 
 // Vite keeps its server object across a restart. Do not accumulate watcher
 // callbacks each time Astro reloads its configuration.
 const watchedServers = new WeakSet<object>();
 
+function normalizedBasePath(base: string): string {
+  const segment = base.replace(/^\/+|\/+$/gu, '');
+  return segment ? `/${segment}/` : '/';
+}
+
+/** Match only a configured lesson artifact below Astro's deployment base. */
+export function matchStandaloneDownload(
+  pathname: string,
+  base: string,
+  lessonSlugs: readonly string[],
+): string | undefined {
+  const prefix = `${normalizedBasePath(base)}downloads/`;
+  if (!pathname.startsWith(prefix) || !pathname.endsWith('.html')) return undefined;
+  const slug = pathname.slice(prefix.length, -'.html'.length);
+  return lessonSlugs.includes(slug) ? slug : undefined;
+}
+
+async function buildDevelopmentDownloads(
+  config: Pick<AstroConfig, 'root'>,
+  lessonSlugs: readonly string[],
+): Promise<ReadonlyMap<string, Buffer>> {
+  const temporaryRoot = await mkdtemp(join(tmpdir(), 'explico-standalone-'));
+  const outputRoot = join(temporaryRoot, 'dist');
+  try {
+    const projectRoot = fileURLToPath(config.root);
+    const astroEntry = fileURLToPath(import.meta.resolve('astro'));
+    const astroCli = resolve(dirname(astroEntry), '..', 'bin', 'astro.mjs');
+    await new Promise<void>((resolveBuild, rejectBuild) => {
+      const child = spawn(
+        process.execPath,
+        [
+          astroCli,
+          'build',
+          '--root',
+          projectRoot,
+          '--outDir',
+          outputRoot,
+          '--silent',
+        ],
+        {
+          cwd: projectRoot,
+          env: { ...process.env, NODE_ENV: 'production' },
+          stdio: ['ignore', 'pipe', 'pipe'],
+        },
+      );
+      let diagnostic = '';
+      const capture = (chunk: Buffer) => {
+        if (diagnostic.length < 16_000) diagnostic += chunk.toString('utf8');
+      };
+      child.stdout.on('data', capture);
+      child.stderr.on('data', capture);
+      child.once('error', rejectBuild);
+      child.once('close', (code) => {
+        if (code === 0) {
+          resolveBuild();
+          return;
+        }
+        rejectBuild(
+          new Error(
+            `Astro's standalone development build exited with code ${code}.` +
+              (diagnostic.trim() ? `\n${diagnostic.trim()}` : ''),
+          ),
+        );
+      });
+    });
+    return new Map(
+      await Promise.all(
+        lessonSlugs.map(async (slug) => [
+          slug,
+          await readFile(join(outputRoot, 'downloads', `${slug}.html`)),
+        ] as const),
+      ),
+    );
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
 /** Fail loudly instead of rendering math triggers whose local cards are stale. */
 export function assertLocalNotationParity(
   lessonId: string,
@@ -34,6 +118,35 @@ export function assertLocalNotationParity(
   );
 }
 
+/** Fail an Astro build if final rendered HTML contains an unusable trigger. */
+export function assertNotationPayloadHtml(page: string, html: string): void {
+  const missing = missingNotationPayloadKeys(html);
+  if (missing.length === 0) return;
+  throw new Error(
+    `Explico notation payload invariant failed for rendered page "${page}": ` +
+      `${missing.map((key) => `data-notation-key="${key}"`).join(', ')} ` +
+      `${missing.length === 1 ? 'has' : 'have'} no matching ` +
+      '`data-notation-entry` popup definition. A nested Astro component that ' +
+      'emits notation must register its formula dependencies; use Diagram, ' +
+      'NotationFormula, or labMathScope(..., { locals: Astro.locals, context }).',
+  );
+}
+
+async function validateGeneratedNotationPayloads(directory: URL): Promise<void> {
+  const root = fileURLToPath(directory);
+  const walk = async (path: string): Promise<void> => {
+    for (const entry of await readdir(path, { withFileTypes: true })) {
+      const child = join(path, entry.name);
+      if (entry.isDirectory()) {
+        await walk(child);
+      } else if (entry.isFile() && entry.name.endsWith('.html')) {
+        assertNotationPayloadHtml(relative(root, child), await readFile(child, 'utf8'));
+      }
+    }
+  };
+  await walk(root);
+}
+
 function replaceInPlace(target: unknown, source: unknown): void {
   if (Array.isArray(target) && Array.isArray(source)) {
     target.splice(0, target.length, ...source);
@@ -82,15 +195,43 @@ export function explicoContentRefresh(
   courseConfig: CourseConfig,
   manifest: Manifest,
 ): AstroIntegration {
+  let developmentConfig: Pick<AstroConfig, 'root' | 'base'> | undefined;
   return {
     name: 'explico-content-refresh',
     hooks: {
-      'astro:server:setup': ({ server }) => {
+      'astro:config:setup': ({ command, config }) => {
+        if (command === 'dev') {
+          developmentConfig = { root: config.root, base: config.base };
+        }
+      },
+      'astro:server:setup': ({ server, logger }) => {
         if (watchedServers.has(server)) return;
         watchedServers.add(server);
         const contentRoot = `${resolve(process.cwd(), 'content')}${sep}`;
         let timer: ReturnType<typeof setTimeout> | undefined;
         let restarting = false;
+        let developmentDownloads:
+          | Promise<ReadonlyMap<string, Buffer>>
+          | undefined;
+        const developmentRoot = developmentConfig
+          ? fileURLToPath(developmentConfig.root)
+          : process.cwd();
+        const generatedDevelopmentRoots = [
+          '.astro',
+          'build',
+          'dist',
+          'node_modules',
+        ].map((directory) => `${resolve(developmentRoot, directory)}${sep}`);
+
+        const invalidateDevelopmentDownloads = (path: string) => {
+          const absolute = resolve(path);
+          if (
+            generatedDevelopmentRoots.some((root) => absolute.startsWith(root))
+          ) {
+            return;
+          }
+          developmentDownloads = undefined;
+        };
 
         const refresh = (path: string) => {
           const absolute = resolve(path);
@@ -121,6 +262,70 @@ export function explicoContentRefresh(
         server.watcher.on('add', refresh);
         server.watcher.on('change', refresh);
         server.watcher.on('unlink', refresh);
+
+        const configuredDevelopment = developmentConfig;
+        if (manifest.lessonExports?.standaloneHtml && configuredDevelopment) {
+          server.watcher.on('add', invalidateDevelopmentDownloads);
+          server.watcher.on('change', invalidateDevelopmentDownloads);
+          server.watcher.on('unlink', invalidateDevelopmentDownloads);
+          server.middlewares.use(async (request, response, next) => {
+            if (request.method !== 'GET' && request.method !== 'HEAD') return next();
+            let pathname: string;
+            try {
+              pathname = decodeURIComponent(
+                new URL(request.url ?? '/', 'http://localhost').pathname,
+              );
+            } catch {
+              return next();
+            }
+            const slug = matchStandaloneDownload(
+              pathname,
+              configuredDevelopment.base,
+              manifest.lessons.map((lesson) => lesson.slug),
+            );
+            if (!slug) return next();
+
+            try {
+              logger.info(
+                developmentDownloads
+                  ? `Serving cached standalone lesson ${slug}.html`
+                  : 'Building standalone lesson downloads for local development…',
+              );
+              developmentDownloads ??= buildDevelopmentDownloads(
+                configuredDevelopment,
+                manifest.lessons.map((lesson) => lesson.slug),
+              );
+              const currentDownloads = developmentDownloads;
+              currentDownloads.catch(() => {
+                if (developmentDownloads === currentDownloads) {
+                  developmentDownloads = undefined;
+                }
+              });
+              const artifact = (await currentDownloads).get(slug);
+              if (!artifact) return next();
+              const filename = `${slug.split('/').at(-1) ?? 'lesson'}.html`;
+              response.statusCode = 200;
+              response.setHeader('Content-Type', 'text/html; charset=utf-8');
+              response.setHeader('Content-Length', artifact.byteLength);
+              response.setHeader(
+                'Content-Disposition',
+                `attachment; filename="${filename}"`,
+              );
+              response.setHeader('Cache-Control', 'no-store');
+              response.end(request.method === 'HEAD' ? undefined : artifact);
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              logger.error(`Could not build standalone lesson downloads: ${message}`);
+              response.statusCode = 500;
+              response.setHeader('Content-Type', 'text/plain; charset=utf-8');
+              response.end(`Could not build standalone lesson download.\n${message}\n`);
+            }
+          });
+        }
+      },
+      'astro:build:done': async ({ dir }) => {
+        await validateGeneratedNotationPayloads(dir);
+        await writeStandaloneLessonExports(dir, manifest);
       },
     },
   };

package/src/compiler/cli.ts

@@ -40,7 +40,11 @@ import remarkMdx from 'remark-mdx';
 import { createNotationKatexOptions } from '../reference/katex-options.mjs';
 import rehypeFailKatexErrors from '../reference/rehype-fail-katex-errors.mjs';
 import remarkCitation from '../reference/remark-citation.mjs';
-import remarkNotation from '../reference/remark-notation.mjs';
+import remarkMemo from '../reference/remark-memo.mjs';
+import remarkNotation, {
+  createRemarkNotationOptions,
+} from '../reference/remark-notation.mjs';
+import remarkShortNote from '../reference/remark-short-note.mjs';
 import type { Manifest, ManifestLesson } from './manifest';
 import { isLessonSlug, lessonIdFromSlug } from './lesson-derivation';
 
@@ -173,6 +177,9 @@ export function lessonDiagnostics(
   for (const diagnostic of [
     ...manifest.diagnostics.tables,
     ...manifest.diagnostics.figures,
+    ...manifest.diagnostics.diagrams,
+    ...manifest.diagnostics.checks,
+    ...manifest.diagnostics.rawFloats,
   ]) {
     if (
       diagnostic.lessonId !== id &&
@@ -221,11 +228,18 @@ function processorFor(manifest: Manifest) {
       // shape here that it does there (D7/F-tables-figures parity).
       remarkMdx,
       remarkMath,
+      remarkShortNote,
+      remarkMemo,
       // `manifest` carries the number tables *and* the part/offset placement
       // together, so this check numbers a page exactly as the Astro build
       // does. Passing the tables alone silently numbered pages by `##` section
       // here while cross-page references read the part-scheme manifest.
-      [remarkNotation, { definitions: manifest.notation.raw, manifest }],
+      // No `strict: true` here: `renderLesson()` below is also called
+      // directly with a synthetic path/body that has no manifest entry at all
+      // (fixture renderability checks — see its own doc comment), which
+      // strict mode would reject as "catalogued lesson with no numbering",
+      // even though it was never meant to be catalogued in the first place.
+      [remarkNotation, createRemarkNotationOptions(manifest)],
       [remarkCitation, { sources: manifest.sources }],
     ],
     rehypePlugins: [
@@ -476,6 +490,7 @@ export interface StatusReport {
     readonly keyedEquations: number;
     readonly keyedTables: number;
     readonly keyedFigures: number;
+    readonly keyedDiagrams: number;
   };
   readonly draftDebt: {
     readonly lessons: readonly string[];
@@ -521,6 +536,9 @@ export function contentStatus(manifest: Manifest): StatusReport {
     ...manifest.diagnostics.equations.map((d) => d.severity),
     ...manifest.diagnostics.tables.map((d) => d.severity),
     ...manifest.diagnostics.figures.map((d) => d.severity),
+    ...manifest.diagnostics.diagrams.map((d) => d.severity),
+    ...manifest.diagnostics.checks.map((d) => d.severity),
+    ...manifest.diagnostics.rawFloats.map((d) => d.severity),
     ...manifest.diagnostics.consistency.map(() => 'warning' as const),
     ...manifest.diagnostics.knowledge.map((d) => d.severity),
   ];
@@ -537,6 +555,10 @@ export function contentStatus(manifest: Manifest): StatusReport {
     (count, lesson) => count + lesson.figures.length,
     0,
   );
+  const keyedDiagrams = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.diagrams.length,
+    0,
+  );
   const assessments = new Set(
     manifest.lessons.flatMap((lesson) => lesson.assessments),
   ).size;
@@ -553,6 +575,7 @@ export function contentStatus(manifest: Manifest): StatusReport {
       keyedEquations,
       keyedTables,
       keyedFigures,
+      keyedDiagrams,
     },
     draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
@@ -593,6 +616,8 @@ export interface ContextReport {
   readonly equations: readonly { key: string; number: string }[];
   readonly tables: readonly { key: string; number: string }[];
   readonly figures: readonly { key: string; number: string }[];
+  readonly diagrams: readonly { key: string; number: string }[];
+  readonly knowledgeChecks: readonly { key: string; number: string }[];
   readonly sources: readonly {
     id: string;
     title: string;
@@ -663,6 +688,8 @@ export function contentContext(
     equations: lesson.equations.map((equation) => ({ ...equation })),
     tables: lesson.tables.map((table) => ({ ...table })),
     figures: lesson.figures.map((figure) => ({ ...figure })),
+    diagrams: lesson.diagrams.map((diagram) => ({ ...diagram })),
+    knowledgeChecks: lesson.knowledgeChecks.map((check) => ({ ...check })),
     sources: lesson.sources.map((id) => {
       const record = sourceById.get(id) as Record<string, unknown> | undefined;
       return {

package/src/compiler/collections.ts

@@ -24,6 +24,7 @@ import type {
   TrackDefinition,
 } from '../curriculum/validation';
 import type {
+  AbbreviationDefinitionInput,
   EditorialStatus,
   LocalNotationDefinitionInput,
   NotationAlignment,
@@ -37,6 +38,8 @@ import type {
 import { isSubstantiveMeaning } from '../reference/prose';
 import { parseEquationRef } from '../reference/equations.mjs';
 import { parseKeyedFloatRef } from '../reference/keyed-jsx-floats.mjs';
+import { parseKnowledgeCheckRef } from '../reference/knowledge-checks.mjs';
+import { parseMemoRef } from '../reference/remark-memo.mjs';
 import { resolveLabel } from '../reference/label';
 import { resolveGlosses } from '../reference/gloss';
 import {
@@ -231,13 +234,17 @@ export function extractNotationReferences(
     for (const match of searchable.matchAll(pattern)) {
       const key = (match[1] ?? '').trim();
       // `[[eq-key]]` / `[[slug#eq-key]]` are equation references (D7), and
-      // `[[tab-key]]`/`[[fig-key]]` (and their cross-page forms) are
-      // `<Table>`/`<Figure>` references (F-tables-figures) — all resolved by
-      // the remark pass and the manifest, not notation keys.
+      // `[[tab-key]]`/`[[fig-key]]`/`[[dia-key]]` (and their cross-page forms)
+      // are keyed-float references, `[[check-key]]` targets a lesson's
+      // assessment list, and `[[memo-key]]` is a page-local memo reference —
+      // all resolved by the remark pass and the manifest, not notation keys.
       if (
         parseEquationRef(key) ||
         parseKeyedFloatRef(key, { prefix: 'tab' }) ||
-        parseKeyedFloatRef(key, { prefix: 'fig' })
+        parseKeyedFloatRef(key, { prefix: 'fig' }) ||
+        parseKeyedFloatRef(key, { prefix: 'dia' }) ||
+        parseKnowledgeCheckRef(key) ||
+        parseMemoRef(key)
       ) {
         continue;
       }
@@ -438,6 +445,40 @@ function sharedNotationEntries(): SharedNotationDefinitionInput[] {
   });
 }
 
+/**
+ * Abbreviations table (rule N14) — a lighter tier than a notation card, read
+ * straight off disk the same way `sharedNotationEntries` reads `notation/`.
+ * The directory is optional: a course that never uses this feature need not
+ * create an empty `content/abbreviations/`.
+ */
+function abbreviationEntries(): AbbreviationDefinitionInput[] {
+  const directory = join(CONTENT_ROOT, 'abbreviations');
+  if (!existsSync(directory)) return [];
+  return filesBelow(directory, ['.md']).map((path) => {
+    const { file, data } = parseDocument(path);
+    const key = string(data.key, `${file} key`);
+    const filenameKey = basename(path, '.md');
+    if (key !== filenameKey) {
+      throw new Error(`${file} declares key ${key}; expected ${filenameKey}`);
+    }
+    const domain = optionalString(data.domain, `${file} domain`);
+    return {
+      key,
+      abbr: string(data.abbr, `${file} abbr`),
+      expansion: meaningText(data.expansion, `${file} expansion`),
+      aliases: strings(data.aliases, `${file} aliases`),
+      source: { file },
+      ...(domain === undefined ? {} : { domain }),
+    };
+  });
+}
+
+export async function loadAbbreviationRegistryInput(): Promise<
+  readonly AbbreviationDefinitionInput[]
+> {
+  return abbreviationEntries();
+}
+
 function notationLessonEntries(): NotationLessonInput[] {
   const lessons: NotationLessonInput[] = [];
   for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {