explico 0.8.0 → 0.11.1

package/docs/authoring/visualizations.md

@@ -2,8 +2,8 @@
 
 `V` rules govern anything a lesson draws: diagrams, static charts, and hydrated
 interactive figures. The engine assumes no single plotting approach — these
-rules make the choice per figure predictable and keep every figure accessible
-and deterministic.
+rules make the choice per figure predictable, keep every figure's math
+gate-checked, and keep its drawing deterministic.
 
 See [README.md](README.md) for what "strong recommendation", "Build-enforced",
 and "Review-only" mean here, and how to amend a rule.
@@ -47,15 +47,21 @@ 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.
 
+A diagram is named like every float: a long `caption`, shown below the graph
+in the same caption line a figure has (`Diagram 2.1.1`, a chain icon that
+copies the diagram's link, the caption), and an optional `short` caption for
+the `[[dia-…]]` preview card
+([components.md § The caption pair](components.md#the-caption-pair)).
+
 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; this state is remembered per page by default
-(`defaultOpen` / `rememberState` configure it).
-The title also carries the same chain-link permalink treatment as headings.
+when the work area is narrower. Then a widen button ↔ at the end of the
+caption line — the boxed button a table's caption has — expands the original
+diagram toward the full in-page region and shrinks 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 button again,
+or Escape, restores its original width. A diagram never folds by itself: it
+is its graph and then its caption line, in every state. To let a reader fold
+it away, put it in a collapsible section.
 
 By default a laid-out width above `800px` emits a compile-time warning. Treat
 that warning as a prompt to try
@@ -103,8 +109,8 @@ _Exceptions._ None — this rule _is_ the exception process.
 
 ## V3
 
-**Interactive figures: a hydrated island, the `renderLabMath` seam for
-equations, and a text alternative.**
+**Interactive figures: a hydrated island and the `renderLabMath` seam for
+equations.**
 
 An interactive figure is a React island, hydrated `client:visible` (or
 `client:idle`). It carries:
@@ -119,18 +125,60 @@ An interactive figure is a React island, hydrated `client:visible` (or
   in this page's popup payload. See
   `playground/content/labs/ProjectileRangeExplorer.tsx` +
   `ProjectileRangeMath.astro`.
-- **An accessible name and description** — `ariaLabel` / `ariaDescription` on
-  the plot, marks that are decorative set `ariaHidden`.
-- **A text alternative.** A `<details>` block with the model's assumptions and a
-  small table of representative values, so the figure is usable with no JS and
-  by a screen reader.
-- **Labelled controls.** Every control is a labelled `<input>`; where precision
+- **Labelled controls.** Every control is a labelled `<input>` — the visible
+  label is how any reader knows what a slider sets; where precision
   matters, pair a `range` slider with a `number` field (see `RangeField` in
   `ProjectileRangeExplorer.tsx`).
+- **No title or caption of its own.** The island sits in a `<Figure>`, and the
+  figure's `caption` (with an optional `short`) names the whole lab. The lab
+  adds no heading, no inner `<figure>` / `<figcaption>`, and no
+  `aria-labelledby` pointing at one: one object has one name. A sentence
+  that describes the plot ("the dot marks the landing point") belongs in the
+  figure's caption.
+- **Picture, then caption, then tools.** A lab is laid out as a LaTeX figure
+  with its controls after it (docs/plans/figures-and-short-captions.md,
+  decision 3). The plot goes in the `<Figure>`'s default slot — its
+  picture — and the controls in its `tools` slot: an instruction line, the
+  sliders and fields, the live equation. The two are separate islands that
+  share their values. The tools render after the caption line, in a tray of
+  their own, and are the only part that folds: the fold button ⌃ / ⌄ ends the
+  caption line, and folded tools leave a "Hidden here: 2 sliders, 1
+  equation" line that unfolds them. Whether they start open is the course's
+  `disclosure.figures`, or `defaultOpen` on the one figure; the reader's
+  choice is remembered per page. Print and export show the picture and the
+  caption; the tools never print.
+- **A live end to the caption.** The caption ends with a clause stating the
+  case shown — "Shown for v₀ = 20 m/s and θ = 30°: range 35.3 m, time of
+  flight 2.04 s." The lab writes it with `setFigureState(element, runs)`
+  (`explico/components/figure/figure-state.ts`), `element` being any element
+  of its own inside the figure and `runs` plain text, `{ text, italic: true }`
+  or `{ sub }` — never HTML. The clause prints with the caption; a reader
+  of the long caption elsewhere (a preview card, a fold's bar) sees the
+  caption alone.
+- **Which text goes where.** The caption names the figure and says what it
+  shows — its subject, its marks and symbols, the case shown — and may state
+  the one thing to notice. The argument drawn from the figure is lesson
+  text, after the figure. Instructions for the controls belong to the
+  controls: the tools' first line, not the caption.
+- **A preview shows the plot.** A same-page `[[fig-…]]` reference to a lab
+  previews a still copy of its plot as drawn; the tools are never copied. A
+  plot not drawn yet — or one on another page, drawn only in the browser —
+  leaves the card to the caption and number, so a lab no longer needs
+  `previewable={false}`.
+
+The figure itself never hides; a lab that should fold away whole, with the
+prose around it, goes in a `<Fold>` or a collapsible section.
+
+The lab writes no accessible name, description or text alternative: the
+`<Figure>` renders a real `<figure>` and `<figcaption>`, so its caption is
+already the figure's accessible name
+([Accessibility](README.md#accessibility)). A plot option such as
+`ariaLabel` / `ariaDescription` / `ariaHidden` may stay where it is written;
+nothing asks for one.
 
 _Rationale._ The seam is the only reason interactive math is not a silent
-exception to the completeness gate. The text alternative and aria wiring are the
-difference between a figure and an inaccessible one.
+exception to the completeness gate. One name per object means the reader, a
+`[[fig-…]]` reference and a screen reader all call the lab the same thing.
 
 _How to apply._ Keep the island's job to "patch numbers and redraw". Domain
 math lives in a plain module (`playground/content/domain/motion.ts`), not in the
@@ -226,3 +274,77 @@ _Enforcement._ Review-only.
 _Exceptions._ A figure where the meaningful range is a known physical bound
 (a probability on `[0, 1]`, an angle on `[0°, 360°]`) uses that bound instead —
 state it in a comment.
+
+---
+
+## V6
+
+**Every quantitative axis of a chart shows at least three labelled values.**
+
+A chart that draws an x axis and a y axis — a hand-drawn SVG, an Observable
+Plot, an interactive island, a printed pgfplots figure — labels at least three
+tick values on each quantitative axis, as numbers at their positions. An axis
+_name_ (`feature x`, `density`) does not count, and neither does an annotation
+of one special point (`\mu`, `\bar{x}`, a threshold).
+
+_Rationale._ Values are what make a chart readable rather than decorative.
+One value pins a single point. Two values give a scale only if the reader
+already knows the axis is linear, and two labels on a log axis look exactly
+like two on a linear one. Three values show where the axis starts, how big a
+unit is, and whether the spacing is linear or logarithmic. Only then can a
+reader read a value off the curve, compare two panels, or check the figure
+against a number in the prose beside it.
+
+_How to apply._
+
+- Use round values: steps of 1, 2, 2.5, or 5 times a power of ten, inside the
+  axis domain. Let the library choose them where it can. Observable Plot's
+  automatic ticks satisfy the rule at any ordinary chart size; `ticks: 5`
+  pins a count. In pgfplots the automatic ticks satisfy it; never set
+  `xtick=\empty` or `ytick=\empty` on a quantitative axis.
+- A hand-drawn SVG computes its values from the domain and falls back to a
+  finer step until at least three fit:
+
+  ```ts
+  const NICE_STEPS = [1, 2, 2.5, 5];
+
+  function axisTicks([lo, hi]: readonly [number, number], target = 5): number[] {
+    let exponent = Math.floor(Math.log10((hi - lo) / target));
+    let index = NICE_STEPS.findIndex((n) => n * 10 ** exponent >= (hi - lo) / target);
+    if (index < 0) [index, exponent] = [0, exponent + 1];
+    for (;;) {
+      const step = NICE_STEPS[index] * 10 ** exponent;
+      const values: number[] = [];
+      for (let v = Math.ceil(lo / step - 1e-9) * step; v <= hi + step * 1e-9; v += step) {
+        values.push(Number(v.toFixed(10)));
+      }
+      if (values.length >= 3) return values;
+      if (--index < 0) [index, exponent] = [NICE_STEPS.length - 1, exponent - 1];
+    }
+  }
+  ```
+
+  Draw a short tick mark at each value and the number beside it.
+- The values follow the domain. When a control changes an axis range
+  ([V5](#v5)), recompute the values from the new range in the same step.
+- A density or likelihood axis gets values too. "The vertical scale does not
+  matter here" is a reason to say so in the caption, not to hide the scale.
+- A log axis labels its decades (`10`, `100`, `1000`).
+- Special-point annotations stay, next to the values rather than instead of
+  them.
+- Stacked panels that share an axis, aligned and said to be shared, may
+  label it once, on the panel nearest the axis. Every other axis of every
+  panel carries its own values.
+
+_Enforcement._ Review-only. The engine cannot tell a chart from any other
+drawing. A course can make it build-enforced in its own browser tests by
+marking each axis's value group and counting the values in it.
+
+_Exceptions._
+
+- A figure without axes has nothing to label: a node-edge diagram, a
+  bullseye target, an illustration.
+- A categorical axis shows its categories instead of numbers, even if there
+  are only two.
+- A sketch that draws axes is a chart. If the axes are worth drawing, their
+  scale is worth labelling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.8.0",
+  "version": "0.11.1",
   "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",
@@ -64,7 +64,7 @@
     "vitest": "4.1.11"
   },
   "scripts": {
-    "build": "tsup && node scripts/copy-assets.mjs && node scripts/fix-esm-extensions.mjs && tsc -p tsconfig.dts-mjs.json",
+    "build": "tsup && node scripts/copy-assets.mjs && node scripts/fix-esm-extensions.mjs && tsc -p tsconfig.dts-mjs.json && node scripts/gen-rules-schema.mjs",
     "check:release-migration": "node scripts/check-release-migration.mjs",
     "test": "vitest run",
     "test:watch": "vitest"

package/src/compiler/cli.ts

@@ -52,6 +52,13 @@ import type { DiagnosticSeverity } from '../reference/types';
 import type { EquationLink } from '../reference/gate-math';
 import type { Manifest, ManifestLesson } from './manifest';
 import { isLessonSlug, lessonIdFromSlug } from './lesson-derivation';
+import { isCourseRuleId, ownerOf, ELEMENTS, type Element, type Enforcement } from '../rules/catalog';
+import {
+  renderRulesInEffect,
+  rulesInEffect,
+  type RuleInEffect,
+  type RulesFilter,
+} from '../rules/in-effect';
 
 const REPOSITORY_ROOT = process.cwd();
 // Content and its course math are the top-level `content/` folder (Phase F).
@@ -86,6 +93,12 @@ export class ContentCliError extends Error {
 /** One normalized diagnostic. `code` is `<source>:<kind>` and always stable. */
 export interface CliDiagnostic {
   readonly code: 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.
+   */
+  readonly rule?: string;
   readonly severity: DiagnosticSeverity;
   readonly message: string;
   readonly file?: string;
@@ -104,6 +117,21 @@ function diagnosticSeverity(value: unknown): DiagnosticSeverity {
   return value === 'info' || value === 'warning' ? value : 'error';
 }
 
+/**
+ * `{ rule }` for a `<source>:<code>` (or bare) code the catalog owns — or for a
+ * course rule, whose code is its own ID (`X1`).
+ */
+function ownerFields(code: string): { readonly rule?: string } {
+  const bare = code.slice(code.indexOf(':') + 1);
+  const owner = ownerOf(bare);
+  if (owner !== undefined) return { rule: owner.id };
+  return isCourseRuleId(bare) ? { rule: bare } : {};
+}
+
+function withOwner(diagnostic: CliDiagnostic): CliDiagnostic {
+  return { ...diagnostic, ...ownerFields(diagnostic.code) };
+}
+
 function mentions(message: string, lessonId: string, file: string): boolean {
   return (
     message.includes(lessonId) ||
@@ -167,7 +195,7 @@ export function lessonDiagnostics(
         ));
     if (!forLesson) continue;
     out.push({
-      code: `math:${diagnostic.code ?? diagnostic.context}`,
+      code: `math:${diagnostic.code}`,
       severity: diagnostic.severity,
       message: diagnostic.message,
       file: diagnostic.file,
@@ -200,6 +228,8 @@ export function lessonDiagnostics(
     ...manifest.diagnostics.figures,
     ...manifest.diagnostics.diagrams,
     ...manifest.diagnostics.checks,
+    ...manifest.diagnostics.examples,
+    ...manifest.diagnostics.folds,
     ...manifest.diagnostics.rawFloats,
   ]) {
     if (
@@ -227,10 +257,12 @@ export function lessonDiagnostics(
     });
   }
 
-  return out.sort(
-    (a, b) =>
-      a.code.localeCompare(b.code) || a.message.localeCompare(b.message),
-  );
+  return out
+    .map(withOwner)
+    .sort(
+      (a, b) =>
+        a.code.localeCompare(b.code) || a.message.localeCompare(b.message),
+    );
 }
 
 // --- renderability -------------------------------------------------------
@@ -512,6 +544,7 @@ export interface StatusReport {
     readonly keyedTables: number;
     readonly keyedFigures: number;
     readonly keyedDiagrams: number;
+    readonly keyedExamples: number;
   };
   readonly draftDebt: {
     readonly lessons: readonly string[];
@@ -539,6 +572,7 @@ export function contentStatus(manifest: Manifest): StatusReport {
     .filter((diagnostic) => diagnostic.code === 'unused-definition')
     .map((diagnostic) => ({
       code: `notation:${diagnostic.code}`,
+      ...ownerFields(diagnostic.code),
       severity: diagnosticSeverity(diagnostic.severity),
       message: diagnostic.message,
       ...(diagnostic.source?.file === undefined
@@ -557,9 +591,13 @@ export function contentStatus(manifest: Manifest): StatusReport {
     ...manifest.diagnostics.figures.map((d) => d.severity),
     ...manifest.diagnostics.diagrams.map((d) => d.severity),
     ...manifest.diagnostics.checks.map((d) => d.severity),
+    ...manifest.diagnostics.examples.map((d) => d.severity),
+    ...manifest.diagnostics.folds.map((d) => d.severity),
     ...manifest.diagnostics.rawFloats.map((d) => d.severity),
     ...manifest.diagnostics.consistency.map((d) => d.severity),
     ...manifest.diagnostics.knowledge.map((d) => d.severity),
+    ...manifest.diagnostics.config.map((d) => d.severity),
+    ...manifest.diagnostics.waivers.map((d) => d.severity),
   ];
 
   const keyedEquations = manifest.lessons.reduce(
@@ -578,6 +616,10 @@ export function contentStatus(manifest: Manifest): StatusReport {
     (count, lesson) => count + lesson.diagrams.length,
     0,
   );
+  const keyedExamples = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.examples.length,
+    0,
+  );
   const assessments = new Set(
     manifest.lessons.flatMap((lesson) => lesson.assessments),
   ).size;
@@ -595,6 +637,7 @@ export function contentStatus(manifest: Manifest): StatusReport {
       keyedTables,
       keyedFigures,
       keyedDiagrams,
+      keyedExamples,
     },
     draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
@@ -709,6 +752,7 @@ export function contentDiagnostics(
       const equation = equationLink(diagnostic.equation);
       diagnostics.push({
         code: `${group}:${detail}`,
+        ...ownerFields(detail),
         severity,
         message: String(diagnostic.message ?? detail),
         ...(file === undefined ? {} : { file }),
@@ -742,6 +786,61 @@ export function contentWarnings(manifest: Manifest): WarningsReport {
   return { count: warnings.length, warnings };
 }
 
+// --- content rules -------------------------------------------------------
+
+export interface RulesReport {
+  readonly filter: RulesFilter;
+  readonly count: number;
+  readonly rules: readonly RuleInEffect[];
+  /** The same selection as the page `validate:content` writes. */
+  readonly markdown: string;
+}
+
+/**
+ * Parse `--element a,b` / `--enforcement script` into a filter, throwing a
+ * usage error on a value outside the vocabulary.
+ */
+export function parseRulesFilter(input: {
+  readonly element?: string;
+  readonly enforcement?: string;
+}): RulesFilter {
+  const filter: { elements?: Element[]; enforcement?: Enforcement | 'locked' } = {};
+  if (input.element !== undefined) {
+    const elements = input.element.split(',').map((e) => e.trim()).filter(Boolean);
+    for (const element of elements) {
+      if (!(ELEMENTS as readonly string[]).includes(element)) {
+        throw new ContentCliError(
+          'usage',
+          `--element ${element}: not an element. One of: ${ELEMENTS.join(', ')}.`,
+        );
+      }
+    }
+    filter.elements = elements as Element[];
+  }
+  if (input.enforcement !== undefined) {
+    const kinds = ['script', 'partial', 'guide', 'locked'];
+    if (!kinds.includes(input.enforcement)) {
+      throw new ContentCliError(
+        'usage',
+        `--enforcement ${input.enforcement}: one of ${kinds.join(', ')}.`,
+      );
+    }
+    filter.enforcement = input.enforcement as Enforcement | 'locked';
+  }
+  return filter;
+}
+
+/** The rules this course has in effect, optionally narrowed. */
+export function contentRules(manifest: Manifest, filter: RulesFilter = {}): RulesReport {
+  const rules = rulesInEffect(manifest, filter);
+  return {
+    filter,
+    count: rules.length,
+    rules,
+    markdown: renderRulesInEffect(manifest, filter),
+  };
+}
+
 // --- content context ---------------------------------------------------
 
 export interface ContextReport {
@@ -772,7 +871,16 @@ export interface ContextReport {
   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 }[];
+  /** Worked-example sets: `short` is the title `[[ex-key]]` names. */
+  readonly examples: readonly { key: string; number: string; short?: string }[];
+  readonly knowledgeChecks: readonly { key: string; number: string; title?: string }[];
+  /** The top-level headings: `slug` is what `[[sec-slug]]` names. */
+  readonly sections: readonly {
+    slug: string;
+    text: string;
+    level: number;
+    number?: string;
+  }[];
   readonly sources: readonly {
     id: string;
     title: string;
@@ -844,7 +952,9 @@ export function contentContext(
     tables: lesson.tables.map((table) => ({ ...table })),
     figures: lesson.figures.map((figure) => ({ ...figure })),
     diagrams: lesson.diagrams.map((diagram) => ({ ...diagram })),
+    examples: lesson.examples.map((example) => ({ ...example })),
     knowledgeChecks: lesson.knowledgeChecks.map((check) => ({ ...check })),
+    sections: lesson.headings.map((heading) => ({ ...heading })),
     sources: lesson.sources.map((id) => {
       const record = sourceById.get(id) as Record<string, unknown> | undefined;
       return {

package/src/compiler/collections.ts

@@ -31,15 +31,21 @@ import type {
   NotationLessonInput,
   NotationReferenceInput,
   NotationRegistryInput,
+  NotationSuspension,
   SharedNotationDefinitionInput,
   SourceSpan,
   NotationGlossEntry,
 } from '../reference/types';
 import { isSubstantiveMeaning } from '../reference/prose';
 import { parseEquationRef } from '../reference/equations.mjs';
+import {
+  DECORATION_NAMES,
+  decorationOfEntry,
+} from '../reference/math-glyphs.mjs';
 import { parseKeyedFloatRef } from '../reference/keyed-jsx-floats.mjs';
 import { parseKnowledgeCheckRef } from '../reference/knowledge-checks.mjs';
 import { parseMemoRef } from '../reference/remark-memo.mjs';
+import { parseSectionRef } from '../reference/sections.mjs';
 import { resolveLabel } from '../reference/label';
 import { resolveGlosses } from '../reference/gloss';
 import {
@@ -263,16 +269,19 @@ 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]]`/`[[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.
+      // `[[tab-key]]`/`[[fig-key]]`/`[[dia-key]]`/`[[ex-key]]` (and their
+      // cross-page forms) are keyed-float references, `[[check-key]]`
+      // targets a lesson's assessment list, `[[sec-slug]]` a heading, 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: 'dia' }) ||
+        parseKeyedFloatRef(key, { prefix: 'ex' }) ||
         parseKnowledgeCheckRef(key) ||
+        parseSectionRef(key) ||
         parseMemoRef(key)
       ) {
         continue;
@@ -323,6 +332,57 @@ function lessonCheckIds(lessonPath: string): string[] {
     : [];
 }
 
+/**
+ * One part's **overview page** — `content/docs/<dir>/index.mdx`, the page the
+ * part's own directory URL resolves to. `isLessonSlug` already excludes any
+ * `<dir>/index`, so this page is not a chapter: it carries no competencies, no
+ * knowledge check, and no float numbers, and nothing in the curriculum graph
+ * changes when a course adds one.
+ */
+export interface PartOverviewPage {
+  readonly dir: string;
+  readonly slug: string;
+  readonly file: string;
+  readonly title: string;
+  readonly description?: string;
+  /** MDX after the frontmatter — what the S2 gate (`gate-part-pages.ts`) reads. */
+  readonly body: string;
+  /** 1-based file line `body` starts on, for diagnostic locations. */
+  readonly bodyLine: number;
+}
+
+/**
+ * The overview page of every part that has one, keyed by the part's directory.
+ * A part without one is simply absent — overview pages are opt-in, one part at
+ * a time.
+ */
+export function loadPartOverviews(
+  parts: readonly { readonly dir: string }[],
+): PartOverviewPage[] {
+  const pages: PartOverviewPage[] = [];
+  for (const { dir } of parts) {
+    for (const extension of ['.mdx', '.md']) {
+      const path = join(CONTENT_ROOT, 'docs', dir, `index${extension}`);
+      if (!existsSync(path)) continue;
+      const { data, file, body, bodyLine } = parseDocument(path);
+      const title = typeof data.title === 'string' ? data.title : dir;
+      const description =
+        typeof data.description === 'string' ? data.description : undefined;
+      pages.push({
+        dir,
+        slug: `${dir}/index`,
+        file,
+        title,
+        ...(description === undefined ? {} : { description }),
+        body,
+        bodyLine,
+      });
+      break;
+    }
+  }
+  return pages;
+}
+
 function lessonEntries(
   prerequisitesById: ReadonlyMap<string, readonly string[]>,
 ): LessonDefinition[] {
@@ -508,6 +568,48 @@ export async function loadAbbreviationRegistryInput(): Promise<
   return abbreviationEntries();
 }
 
+/**
+ * A lesson's `notation.suspend` (rule N22): decorations that are not
+ * operators on this page. A name outside `DECORATION_NAMES`, a decoration
+ * suspended twice, and a `notation.local` operator entry for a suspended
+ * decoration (the page would contradict itself) each fail the load.
+ */
+export function notationSuspensions(
+  raw: unknown,
+  localDefinitions: readonly LocalNotationDefinitionInput[],
+  file: string,
+): NotationSuspension[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) {
+    throw new TypeError(`${file} notation.suspend must be an array`);
+  }
+  const seen = new Set<string>();
+  return raw.map((item, index) => {
+    const at = `${file} notation.suspend[${index}]`;
+    const data = record(item, at);
+    const operator = string(data.operator, `${at}.operator`).trim();
+    if (!DECORATION_NAMES.has(operator)) {
+      throw new Error(
+        `${at}.operator ${JSON.stringify(operator)} is not a decoration; use one of ${[...DECORATION_NAMES].join(', ')}`,
+      );
+    }
+    if (seen.has(operator)) {
+      throw new Error(`${at} suspends ${JSON.stringify(operator)} a second time`);
+    }
+    seen.add(operator);
+    const local = localDefinitions.find(
+      (definition) => decorationOfEntry(definition.notation) === operator,
+    );
+    if (local) {
+      throw new Error(
+        `${at} suspends ${JSON.stringify(operator)}, but notation.local entry ${local.key} explains it as an operator (latex ${JSON.stringify(local.notation)}); drop one of them`,
+      );
+    }
+    const reason = optionalString(data.reason, `${at}.reason`);
+    return reason === undefined ? { operator } : { operator, reason: reason.trim() };
+  });
+}
+
 function notationLessonEntries(): NotationLessonInput[] {
   const lessons: NotationLessonInput[] = [];
   for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {
@@ -516,12 +618,14 @@ function notationLessonEntries(): NotationLessonInput[] {
     const { file, data, body, bodyLine } = parseDocument(path);
     const notation = record(data.notation ?? {}, `${file} notation`);
     const local = Array.isArray(notation.local) ? notation.local : [];
+    const localDefinitions = local.map((entry, index) =>
+      localDefinition(entry, file, index),
+    );
     lessons.push({
       lessonId: lessonIdFromSlug(slug),
       status: status(data.editorialStatus, `${file} editorialStatus`),
-      localDefinitions: local.map((entry, index) =>
-        localDefinition(entry, file, index),
-      ),
+      localDefinitions,
+      suspended: notationSuspensions(notation.suspend, localDefinitions, file),
       references: extractNotationReferences(body, file, undefined),
       body,
       bodyLine,