explico 0.8.0 → 0.11.0

package/README.md

@@ -1,3 +1,8 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="playground/src/assets/explico-mark-dark.svg">
+  <img src="playground/src/assets/explico-mark.svg" alt="" width="88" align="right">
+</picture>
+
 # explico
 
 A build-time engine for **prerequisite-aware, notation-rigorous course
@@ -23,6 +28,13 @@ What it gives a course:
 - **Equation identity** — `\label{eq:key}` gives a display equation a stable
   key, an appearance-order number, an anchor, and cross-lesson `[[eq-key]]`
   references.
+- **Outline numbering** — sections number `part.chapter.section` like a book
+  (`§ 1.1.2`), floats `part.chapter.n` (`Figure 2.2.1`); `[[sec-…]]` cites a
+  section, a heading's chain icon copies its link, and a typed number form
+  (`#sec-1.1.2`) lands on the named anchor. A knowledge check and a set of
+  worked examples are numbered sections of their own: the author writes the
+  topic, the engine the kind's badge and the number (`[[ex-…]]`,
+  `[[check-…]]`).
 - **A KaTeX trust boundary** — build-time HTML + MathML; the trust callback
   accepts exactly one validated `data-notation-key`. No runtime math, no CDN.
 - **A deterministic JSON manifest** — the MCP/LMS contract: lessons, notation,
@@ -78,8 +90,10 @@ import remarkNotation, {
 } from 'explico/reference/remark-notation.mjs';
 import remarkShortNote from 'explico/reference/remark-short-note.mjs';
 import remarkCitation from 'explico/reference/remark-citation.mjs';
+import remarkAsides from 'explico/reference/remark-asides.mjs';
 import { createNotationKatexOptions } from 'explico/reference/katex-options.mjs';
 import rehypeFailKatexErrors from 'explico/reference/rehype-fail-katex-errors.mjs';
+import rehypeHeadingAnchors from 'explico/reference/rehype-heading-anchors.mjs';
 import { courseConfig } from './content/course.config.ts';
 
 const manifest = await loadManifest(courseConfig);
@@ -93,14 +107,26 @@ const manifest = await loadManifest(courseConfig);
 //   // 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.
-//   [remarkNotation, createRemarkNotationOptions(manifest, { strict: true })],
-//   [remarkCitation, { sources: manifest.sources }],
+//   // `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,
 // ]
 // … 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]
+// … rehypePlugins: [[rehypeKatex, createNotationKatexOptions()], rehypeFailKatexErrors,
+//                   // Heading collapse defaults: the same `disclosure` block.
+//                   [rehypeHeadingAnchors, { defaultCollapsible: courseConfig.disclosure }]]
 ```
 
 `loadManifest(courseConfig)` always recompiles current content before Astro
@@ -109,18 +135,18 @@ and restarts the development server when any file under `content/` is added,
 changed, or removed, keeping Markdown transforms and UI components on the same
 model without an editor-specific task.
 
-A memo is a substantial optional derivation: it behaves like a collapsible,
-numbered subsection without adding a heading to the page outline. Cite it from
-earlier prose with `[[memo-id]]`, then place the block wherever it best fits.
-The citation, the block's own number, and its chain icon link to the same URL
-fragment:
+A memo is a substantial optional derivation: it folds like a `######`
+section without adding a heading to the page outline. Cite it from earlier
+prose with `[[memo-id]]` — a superscript letter — then place the block
+wherever it best fits. The citation and the chain icon on its bar link to the
+same URL fragment:
 
 ```mdx
 The omitted calculation is recorded in [[memo-full-check]].
 
 Several paragraphs may intervene.
 
-<Memo id="full-check" title="Full check" description="The omitted algebra and evidence.">
+<Memo id="full-check" short="Full check" caption="The omitted algebra and evidence">
 
 The longer derivation can contain paragraphs, equations, tables, and figures.
 
@@ -140,9 +166,24 @@ Differentiate the polynomial, set the result to zero, and solve.
 </ShortNote>. But symmetry is quicker.
 ```
 
-Both components require literal `id`, `title`, and `description` strings.
-Memos start collapsed and persist reader state unless `rememberState={false}`;
-short notes always start collapsed.
+A memo requires literal `id` and `caption` strings (`short` is optional); a
+short note requires `id`, `title` and `description`. Memos start as the
+course's `disclosure.memos` says (closed by default) and persist reader state
+unless `rememberState={false}`; short notes always start collapsed.
+
+A figure or a diagram never folds by itself. To let a reader fold one away
+where it stands — or any stretch of content — import
+`explico/components/fold/Fold.astro` and wrap it in `<Fold>`: no heading,
+number or letter, only a bar with the section chevron. The bar is its `label`
+or, without one, the numbers and short captions of the floats inside
+("Diagram 2.1.1 Steps of the derivation"). Folds start as the course's
+`disclosure.folds` says (closed by default), or as `defaultOpen` says:
+
+```mdx
+<Fold>
+<Diagram id="steps" caption="…" short="Steps of the derivation" nodes={…} edges={…} />
+</Fold>
+```
 
 ### Lesson exports
 
@@ -176,9 +217,13 @@ viewer’s system color scheme.
 
 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, expands disclosures and complete data surfaces without changing saved
-reader state, hides controls that have no paper equivalent while retaining their
-current visual result, and keeps linked text clickable with canonical destinations.
+chrome and prints every disclosure as the reader left it on screen: an open
+section, figure, memo, or question prints in full, and a closed one prints its
+title and a "(content collapsed — full text: …)" note with its permalink.
+Complete data surfaces (every table row, every worked example of an open set)
+still print in full. It does all this without changing saved reader state,
+hides controls that have no paper equivalent while retaining their current
+visual result, and keeps linked text clickable with canonical destinations.
 Paper size, margins, browser-added headers/footers, final filename, and the
 choice to save as PDF remain browser and reader settings.
 

package/dist/compiler/astro.d.ts

@@ -1,6 +1,8 @@
 import { AstroConfig, AstroIntegration } from 'astro';
-import { CourseConfig } from './course-config.js';
+import { C as CourseConfig } from '../course-config-Dsnri9Tk.js';
 import { Manifest } from './manifest.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
 import '../curriculum/validation.js';
 import '../reference/consistency.js';
 import './collections.js';
@@ -11,11 +13,14 @@ import '../reference/tables-validate.js';
 import '../reference/keyed-float-validate.js';
 import '../reference/figures-validate.js';
 import '../reference/diagrams-validate.js';
+import '../reference/examples-validate.js';
+import '../reference/folds-validate.js';
 import '../reference/knowledge-checks-validate.js';
 import '../reference/raw-floats-validate.js';
 import '../reference/gate-math.js';
 import '../reference/mixed-content.js';
 import '../reference/gloss.js';
+import '../rules/waivers.js';
 import './knowledge-version.js';
 import './lesson-derivation.js';
 

package/dist/compiler/cli.d.ts

@@ -1,9 +1,12 @@
 import { DiagnosticSeverity } from '../reference/types.js';
 import { EquationLink } from '../reference/gate-math.js';
 import { Manifest, ManifestLesson } from './manifest.js';
+import { RulesFilter, RuleInEffect } from '../rules/in-effect.js';
 import '../curriculum/validation.js';
 import '../reference/consistency.js';
-import './course-config.js';
+import '../course-config-Dsnri9Tk.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
 import './collections.js';
 import '../reference/lint-ignore.js';
 import '../reference/equations-validate.js';
@@ -11,10 +14,13 @@ import '../reference/tables-validate.js';
 import '../reference/keyed-float-validate.js';
 import '../reference/figures-validate.js';
 import '../reference/diagrams-validate.js';
+import '../reference/examples-validate.js';
+import '../reference/folds-validate.js';
 import '../reference/knowledge-checks-validate.js';
 import '../reference/raw-floats-validate.js';
 import '../reference/mixed-content.js';
 import '../reference/gloss.js';
+import '../rules/waivers.js';
 import './knowledge-version.js';
 import './lesson-derivation.js';
 
@@ -56,6 +62,12 @@ declare class ContentCliError extends Error {
 /** One normalized diagnostic. `code` is `<source>:<kind>` and always stable. */
 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;
@@ -123,6 +135,7 @@ interface StatusReport {
         readonly keyedTables: number;
         readonly keyedFigures: number;
         readonly keyedDiagrams: number;
+        readonly keyedExamples: number;
     };
     readonly draftDebt: {
         readonly lessons: readonly string[];
@@ -150,6 +163,23 @@ interface WarningsReport {
 declare function contentDiagnostics(manifest: Manifest, minimumSeverity?: DiagnosticThreshold): DiagnosticsReport;
 /** Every warning exactly; errors and informational advice are excluded. */
 declare function contentWarnings(manifest: Manifest): WarningsReport;
+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.
+ */
+declare function parseRulesFilter(input: {
+    readonly element?: string;
+    readonly enforcement?: string;
+}): RulesFilter;
+/** The rules this course has in effect, optionally narrowed. */
+declare function contentRules(manifest: Manifest, filter?: RulesFilter): RulesReport;
 interface ContextReport {
     readonly lesson: {
         readonly id: string;
@@ -196,9 +226,23 @@ interface ContextReport {
         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;
@@ -242,4 +286,4 @@ interface Scaffold {
 declare function scaffoldLesson(rawId: string): Scaffold;
 declare function scaffoldTerm(rawKey: string): Scaffold;
 
-export { type CheckLessonResult, type CheckReport, type CliDiagnostic, type ContentCliCode, ContentCliError, type ContextReport, type DiagnosticThreshold, type DiagnosticsReport, type DomainFileSignatures, type RenderResult, type Scaffold, type StatusReport, type TokenCounts, type WarningsReport, changedLessonIds, contentCheck, contentContext, contentDiagnostics, contentStatus, contentWarnings, estimateTokens, findLesson, lessonDiagnostics, normalizeLessonId, renderLesson, scaffoldLesson, scaffoldTerm };
+export { type CheckLessonResult, type CheckReport, type CliDiagnostic, type ContentCliCode, ContentCliError, type ContextReport, type DiagnosticThreshold, type DiagnosticsReport, type DomainFileSignatures, type RenderResult, type RulesReport, type Scaffold, type StatusReport, type TokenCounts, type WarningsReport, changedLessonIds, contentCheck, contentContext, contentDiagnostics, contentRules, contentStatus, contentWarnings, estimateTokens, findLesson, lessonDiagnostics, normalizeLessonId, parseRulesFilter, renderLesson, scaffoldLesson, scaffoldTerm };

package/dist/compiler/cli.js

@@ -18,6 +18,11 @@ import remarkNotation, {
 } from "../reference/remark-notation.mjs";
 import remarkShortNote from "../reference/remark-short-note.mjs";
 import { isLessonSlug, lessonIdFromSlug } from "./lesson-derivation.js";
+import { isCourseRuleId, ownerOf, ELEMENTS } from "../rules/catalog.js";
+import {
+  renderRulesInEffect,
+  rulesInEffect
+} from "../rules/in-effect.js";
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const DOCS_ROOT = join(CONTENT_ROOT, "docs");
@@ -33,6 +38,15 @@ class ContentCliError extends Error {
 function diagnosticSeverity(value) {
   return value === "info" || value === "warning" ? value : "error";
 }
+function ownerFields(code) {
+  const bare = code.slice(code.indexOf(":") + 1);
+  const owner = ownerOf(bare);
+  if (owner !== void 0) return { rule: owner.id };
+  return isCourseRuleId(bare) ? { rule: bare } : {};
+}
+function withOwner(diagnostic) {
+  return { ...diagnostic, ...ownerFields(diagnostic.code) };
+}
 function mentions(message, lessonId, file) {
   return message.includes(lessonId) || message.includes(file) || message.includes(file.replace(/^content\/docs\//, ""));
 }
@@ -71,7 +85,7 @@ function lessonDiagnostics(manifest, lesson) {
     );
     if (!forLesson) continue;
     out.push({
-      code: `math:${diagnostic.code ?? diagnostic.context}`,
+      code: `math:${diagnostic.code}`,
       severity: diagnostic.severity,
       message: diagnostic.message,
       file: diagnostic.file,
@@ -96,6 +110,8 @@ function lessonDiagnostics(manifest, lesson) {
     ...manifest.diagnostics.figures,
     ...manifest.diagnostics.diagrams,
     ...manifest.diagnostics.checks,
+    ...manifest.diagnostics.examples,
+    ...manifest.diagnostics.folds,
     ...manifest.diagnostics.rawFloats
   ]) {
     if (diagnostic.lessonId !== id && diagnostic.file !== file && !mentions(diagnostic.message, id, file)) {
@@ -117,7 +133,7 @@ function lessonDiagnostics(manifest, lesson) {
       ...withFile(diagnostic.file)
     });
   }
-  return out.sort(
+  return out.map(withOwner).sort(
     (a, b) => a.code.localeCompare(b.code) || a.message.localeCompare(b.message)
   );
 }
@@ -306,6 +322,7 @@ function contentStatus(manifest) {
   const draftNotation = manifest.notation.definitions.filter((definition) => definition.status === "draft").map((definition) => definition.id).sort();
   const orphans = manifest.notation.diagnostics.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 === void 0 ? {} : { file: diagnostic.source.file }
@@ -320,9 +337,13 @@ function contentStatus(manifest) {
     ...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.knowledge.map((d) => d.severity),
+    ...manifest.diagnostics.config.map((d) => d.severity),
+    ...manifest.diagnostics.waivers.map((d) => d.severity)
   ];
   const keyedEquations = manifest.lessons.reduce(
     (count, lesson) => count + lesson.equations.length,
@@ -340,6 +361,10 @@ function contentStatus(manifest) {
     (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;
@@ -355,7 +380,8 @@ function contentStatus(manifest) {
       keyedEquations,
       keyedTables,
       keyedFigures,
-      keyedDiagrams
+      keyedDiagrams,
+      keyedExamples
     },
     draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
@@ -403,6 +429,7 @@ function contentDiagnostics(manifest, minimumSeverity = "info") {
       const equation = equationLink(diagnostic.equation);
       diagnostics.push({
         code: `${group}:${detail}`,
+        ...ownerFields(detail),
         severity,
         message: String(diagnostic.message ?? detail),
         ...file === void 0 ? {} : { file },
@@ -427,6 +454,41 @@ function contentWarnings(manifest) {
   );
   return { count: warnings.length, warnings };
 }
+function parseRulesFilter(input) {
+  const filter = {};
+  if (input.element !== void 0) {
+    const elements = input.element.split(",").map((e) => e.trim()).filter(Boolean);
+    for (const element of elements) {
+      if (!ELEMENTS.includes(element)) {
+        throw new ContentCliError(
+          "usage",
+          `--element ${element}: not an element. One of: ${ELEMENTS.join(", ")}.`
+        );
+      }
+    }
+    filter.elements = elements;
+  }
+  if (input.enforcement !== void 0) {
+    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;
+  }
+  return filter;
+}
+function contentRules(manifest, filter = {}) {
+  const rules = rulesInEffect(manifest, filter);
+  return {
+    filter,
+    count: rules.length,
+    rules,
+    markdown: renderRulesInEffect(manifest, filter)
+  };
+}
 function contentContext(manifest, rawId) {
   const lesson = findLesson(manifest, rawId);
   const { frontmatter, body } = lessonRaw(lesson);
@@ -474,7 +536,9 @@ function contentContext(manifest, rawId) {
     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);
       return {
@@ -667,12 +731,14 @@ export {
   contentCheck,
   contentContext,
   contentDiagnostics,
+  contentRules,
   contentStatus,
   contentWarnings,
   estimateTokens,
   findLesson,
   lessonDiagnostics,
   normalizeLessonId,
+  parseRulesFilter,
   renderLesson,
   scaffoldLesson,
   scaffoldTerm

package/dist/compiler/collections.d.ts

@@ -1,5 +1,5 @@
 import { CurriculumCatalog } from '../curriculum/validation.js';
-import { NotationReferenceInput, AbbreviationDefinitionInput, NotationRegistryInput } from '../reference/types.js';
+import { NotationReferenceInput, AbbreviationDefinitionInput, NotationRegistryInput, LocalNotationDefinitionInput, NotationSuspension } from '../reference/types.js';
 
 /**
  * The single path from content files to typed data.
@@ -19,8 +19,41 @@ import { NotationReferenceInput, AbbreviationDefinitionInput, NotationRegistryIn
  * ignoring code fences and inline code, sorted by position.
  */
 declare function extractNotationReferences(text: string, file: string, kind: NotationReferenceInput['kind'] | undefined): NotationReferenceInput[];
+/**
+ * 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.
+ */
+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.
+ */
+declare function loadPartOverviews(parts: readonly {
+    readonly dir: string;
+}[]): PartOverviewPage[];
 declare function loadCurriculumCatalog(): Promise<CurriculumCatalog>;
 declare function loadAbbreviationRegistryInput(): Promise<readonly AbbreviationDefinitionInput[]>;
+/**
+ * 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.
+ */
+declare function notationSuspensions(raw: unknown, localDefinitions: readonly LocalNotationDefinitionInput[], file: string): NotationSuspension[];
 declare function loadNotationRegistryInput(): Promise<NotationRegistryInput>;
 /**
  * Notation frontmatter objects for `remark-notation`'s `definitions` option.
@@ -68,4 +101,4 @@ declare function notationSourceLocatorGaps(): {
     total: number;
 };
 
-export { type NotationSpec, extractNotationReferences, loadAbbreviationRegistryInput, loadCurriculumCatalog, loadLessonChecks, loadNotationDefinitions, loadNotationRegistryInput, loadNotationSpecs, loadSourceRecords, notationSourceLocatorGaps };
+export { type NotationSpec, type PartOverviewPage, extractNotationReferences, loadAbbreviationRegistryInput, loadCurriculumCatalog, loadLessonChecks, loadNotationDefinitions, loadNotationRegistryInput, loadNotationSpecs, loadPartOverviews, loadSourceRecords, notationSourceLocatorGaps, notationSuspensions };

package/dist/compiler/collections.js

@@ -3,9 +3,14 @@ import { basename, join, relative } from "node:path";
 import { parseFrontmatter } from "@astrojs/markdown-remark";
 import { isSubstantiveMeaning } from "../reference/prose.js";
 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.js";
 import { resolveGlosses } from "../reference/gloss.js";
 import {
@@ -151,7 +156,7 @@ function extractNotationReferences(text, file, kind) {
   for (const [pattern, referenceKind] of patterns) {
     for (const match of searchable.matchAll(pattern)) {
       const key = (match[1] ?? "").trim();
-      if (parseEquationRef(key) || parseKeyedFloatRef(key, { prefix: "tab" }) || parseKeyedFloatRef(key, { prefix: "fig" }) || parseKeyedFloatRef(key, { prefix: "dia" }) || parseKnowledgeCheckRef(key) || parseMemoRef(key)) {
+      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;
       }
       references.push({
@@ -184,6 +189,29 @@ function lessonCheckIds(lessonPath) {
   const checksPath = lessonPath.replace(/\.mdx?$/, ".checks.yml");
   return existsSync(checksPath) ? parseCheckList(readFileSync(checksPath, "utf8")) : [];
 }
+function loadPartOverviews(parts) {
+  const pages = [];
+  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 : void 0;
+      pages.push({
+        dir,
+        slug: `${dir}/index`,
+        file,
+        title,
+        ...description === void 0 ? {} : { description },
+        body,
+        bodyLine
+      });
+      break;
+    }
+  }
+  return pages;
+}
 function lessonEntries(prerequisitesById) {
   const lessons = [];
   for (const path of filesBelow(join(CONTENT_ROOT, "docs"), [".md", ".mdx"])) {
@@ -329,6 +357,37 @@ function abbreviationEntries() {
 async function loadAbbreviationRegistryInput() {
   return abbreviationEntries();
 }
+function notationSuspensions(raw, localDefinitions, file) {
+  if (raw === void 0) return [];
+  if (!Array.isArray(raw)) {
+    throw new TypeError(`${file} notation.suspend must be an array`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  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 === void 0 ? { operator } : { operator, reason: reason.trim() };
+  });
+}
 function notationLessonEntries() {
   const lessons = [];
   for (const path of filesBelow(join(CONTENT_ROOT, "docs"), [".md", ".mdx"])) {
@@ -337,12 +396,14 @@ function notationLessonEntries() {
     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, void 0),
       body,
       bodyLine,
@@ -448,6 +509,8 @@ export {
   loadNotationDefinitions,
   loadNotationRegistryInput,
   loadNotationSpecs,
+  loadPartOverviews,
   loadSourceRecords,
-  notationSourceLocatorGaps
+  notationSourceLocatorGaps,
+  notationSuspensions
 };