explico 0.8.0 → 0.11.0

package/src/compiler/manifest.ts

@@ -69,6 +69,12 @@ import {
   type DiagramDiagnostic,
   type DiagramLabelRecord,
 } from '../reference/diagrams-validate';
+import {
+  validateExamples,
+  type ExampleDiagnostic,
+  type ExampleLabelRecord,
+} from '../reference/examples-validate';
+import { validateFolds, type FoldDiagnostic } from '../reference/folds-validate';
 import {
   validateKnowledgeChecks,
   type KnowledgeCheckDiagnostic,
@@ -87,8 +93,21 @@ import {
   gateProseNotation,
   gateProseNotationInAssessments,
 } from '../reference/gate-prose-notation';
+import {
+  gateMathPunctuation,
+  gateMathPunctuationInAssessments,
+} from '../reference/gate-math-punctuation';
 import { gateAbbreviations } from '../reference/gate-abbreviations';
+import { gateCourseRules } from '../reference/gate-course-rules';
 import { gateHeadingLength } from '../reference/gate-heading-length';
+import { gateHeadingStructure } from '../reference/gate-heading-structure';
+import { gatePartPages } from '../reference/gate-part-pages';
+import {
+  scanSectionHeadings,
+  scanTitledBlocks,
+} from '../reference/sections.mjs';
+import { knowledgeCheckAnchorId } from '../reference/knowledge-checks.mjs';
+import { validateSectionRefs } from '../reference/sections-validate';
 import {
   splitMixedContent,
   type ContentSegment,
@@ -109,12 +128,30 @@ import type {
 } from '../reference/types';
 import {
   coursePartsOf,
+  normalizeBlockLabels,
   normalizeLessonExports,
-  normalizeDisclosureDefaults,
+  normalizeDisclosure,
+  normalizeNumbering,
+  type BlockLabels,
   type CourseConfig,
   type NormalizedLessonExports,
-  type NormalizedDisclosureDefaults,
+  type NormalizedDisclosure,
+  type NormalizedNumbering,
 } from './course-config';
+import {
+  disabledCodes,
+  dropDisabled,
+  partPageLimits,
+  resolveRules,
+  rulesSnapshot,
+  type ConfigDiagnostic,
+  type ManifestRules,
+} from '../rules/settings';
+import {
+  applyWaivers,
+  collectWaivers,
+  type WaiverDiagnostic,
+} from '../rules/waivers';
 import {
   resolveKnowledgeVersion,
   type KnowledgeVersionDiagnostic,
@@ -125,6 +162,7 @@ import {
   loadNotationDefinitions,
   loadNotationRegistryInput,
   loadNotationSpecs,
+  loadPartOverviews,
   loadSourceRecords,
 } from './collections';
 import {
@@ -190,8 +228,70 @@ import {
  * optional advice. Unused keys/definitions and restructuring candidates move
  * from `warning` to `info`; their diagnostic codes and container fields stay
  * unchanged.
+ * v17 (part pages, additive): `parts` — every part with its chapters in
+ * reading order and, where the course authored one, its overview page. A part
+ * with an overview page also gains a leading `Overview` item in its
+ * `sidebar` group, so `sidebar[].items` is now a mixed list of lesson slugs
+ * and `{ label, link, attrs? }` entries rather than one kind per group.
+ * Also `lessons[].studyMinutes` from the optional frontmatter field, and
+ * `parts[].studyMinutes` totalling it across a part whose chapters all
+ * state one.
+ *
+ * v18 (rule settings, additive): `rules` — the course's rule switches
+ * (`disabled`) and every rule's effective settings; `diagnostics.config` —
+ * findings about the course settings themselves (a deprecated top-level
+ * `operators` / `romanLabels` / `abbreviations` block, a block for a retired
+ * rule), from `resolveRules`. A diagnostic owned by a disabled rule is not
+ * published at all; one covered by a per-place waiver
+ * (`{/* explico-allow N9: reason *\/}`) is dropped too, and
+ * `diagnostics.waivers` reports the waivers themselves (malformed, invalid,
+ * unused). Every math-gate finding now carries a `code`
+ * (`prose-notation`, `abbreviation-unexplained`, `title-length`,
+ * `unresolved-glyph`, `math-compile-error`, or the resolver's own).
+ *
+ * v19 (course rules, additive): `rules.course` — the course's own `X` rules
+ * from `courseRules` in the settings, validated, in file order, so
+ * `build/rules-in-effect.md` and `content rules` list them beside the engine's.
+ * A finding from one is in `diagnostics.math` with the rule's ID as its `code`.
+ *
+ * v20 (outline numbering): `numbering` — the course's resolved
+ * `numbering` settings; `lessons[].headings` — every top-level heading with
+ * its anchor, text, level and, down to `numbering.sections.depth`, its
+ * `‹part›.‹chapter›.‹section›…` number; `lessons[].numbering.prefix` — the
+ * float-number prefix. Under the default `numbering.floats: "chapter"` that
+ * prefix is `‹part›.‹chapter›` and every per-kind offset is 0, so a float
+ * number is `2.2.1` where it used to be `2.1`. A `[[sec-…]]` that names no
+ * heading is a `sec-ref-resolves` error in `diagnostics.math`.
+ *
+ * v21 (one caption pair): `lessons[].equations` / `.tables` / `.figures` /
+ * `.diagrams` entries, and the `labels` of `equations` / `tables` / `figures`
+ * / `diagrams`, carry the float's `short` caption (an equation's
+ * `\caption{…}`, or the `short` prop) and, for a JSX float, its long
+ * `caption`, each when stated as a literal. `diagnostics.figures` /
+ * `diagnostics.diagrams` gain `fig-removed-prop` / `dia-removed-prop`.
+ *
+ * v22 (one collapse model): `disclosure` replaces `disclosureDefaults` — the
+ * course's whole `disclosure` settings block with the engine defaults applied
+ * (`NormalizedDisclosure`): `sections` / `subsections` / `knowledgeChecks`
+ * as `{ collapsible, defaultOpen }`, `notation` / `references` / `memos` /
+ * `figures` / `diagrams` / `workedExamples` as `{ defaultOpen }`, and
+ * `tables.truncateAfter`.
+ *
+ * v23 (kind badges): a worked-example set is a numbered kind of its own —
+ * `examples` (same shape as `figures`), `lessons[].examples`,
+ * `lessons[].numbering.examples` and `diagnostics.examples` (`ex-…` codes,
+ * `ex-missing-prop` among them). `lessons[].knowledgeChecks` entries carry
+ * the check's `title`; `lessons[].titledBlocks` lists every check and example
+ * set with the anchor and title of the `<h2>` it draws and the heading it
+ * follows; `blockLabels` is the course's resolved badge form.
+ *
+ * v24 (figures stop compacting; `<Fold>`): `disclosure` loses `diagrams` —
+ * a diagram no longer folds by itself — and gains `folds`, the first-visit
+ * state of a `<Fold>`; `disclosure.figures` now says whether a lab's tools
+ * start open; `diagnostics.folds` holds `fold-unnamed`
+ * (docs/plans/figures-and-short-captions.md, Parts 1–2).
  */
-export const MANIFEST_SCHEMA_VERSION = 16;
+export const MANIFEST_SCHEMA_VERSION = 24;
 
 const REPOSITORY_ROOT = process.cwd();
 // Content is the top-level `content/` folder; the build output is `build/`
@@ -275,74 +375,121 @@ export interface ManifestLessonNotation {
   readonly formulaScope: readonly GlyphScopeEntry[];
 }
 
+/**
+ * One keyed float of a lesson (v21): its key and number, and its caption pair
+ * — `short` (an equation's `\caption{…}`, or the `short` prop) and, for a
+ * `<Table>` / `<Figure>` / `<Diagram>`, the long `caption`. Each is present
+ * only when the source states it as a literal.
+ */
+export interface ManifestLessonFloat {
+  readonly key: string;
+  readonly number: string;
+  readonly short?: string;
+  readonly caption?: string;
+}
+
+/**
+ * A block that draws a heading of its own where its tag stands (v23): a
+ * knowledge check (`<AssessmentSet />`) or a worked-example set
+ * (`<CompactExamples>`). `anchor` is the heading's id, `title` the author's
+ * topical title, `after` the slug of the top-level heading it follows.
+ */
+export interface ManifestTitledBlock {
+  readonly kind: 'check' | 'example';
+  readonly key: string;
+  readonly anchor: string;
+  readonly title: string;
+  readonly after?: string;
+}
+
 export interface ManifestLesson {
   readonly id: string;
   /** Docs-loader slug, e.g. `bonds/price-yield-relationship`. */
   readonly slug: string;
   /**
    * The 1-based ordinal of the **part** this lesson sits in — its sidebar
-   * group's position in `courseConfig.parts`. It is the number before the dot
-   * in every equation, table, figure, diagram, and knowledge-check number on
-   * the page: `(2.1)` is the first equation of part 2. See
-   * `docs/authoring/structure.md`.
+   * group's position in `courseConfig.parts`. It is the first number of every
+   * section, equation, table, figure, diagram, and knowledge-check number on
+   * the page. See `docs/authoring/structure.md`.
    */
   readonly part: number;
   /**
    * The lesson's 1-based ordinal **within its part** (merged track order, then
-   * any unranked lessons by slug) — its chapter number. This orders the
-   * sidebar and the reading path; it does not appear in a float's number.
+   * any unranked lessons by slug) — its chapter number, the second number of
+   * every section number (`1.2.3`) and, under the default
+   * `numbering.floats: "chapter"`, of every float number (`(1.2.1)`).
    */
   readonly chapter: number;
   /**
-   * How many floats of each kind the earlier lessons of this part already
-   * used. The lesson's own floats continue from here, so a part's sequence
-   * runs unbroken across its chapters instead of restarting on every page.
+   * The float numbers' `prefix` — `‹part›.‹chapter›` under
+   * `numbering.floats: "chapter"`, `‹part›` under `"part"` — and, per kind,
+   * how many floats of that kind precede this lesson in that scope: always 0
+   * for `chapter`, the earlier chapters' count for `part`, whose sequence
+   * runs unbroken across the part. A float is `‹prefix›.‹offset + n›`.
    */
   readonly numbering: {
+    readonly prefix: string;
     readonly equations: number;
     readonly tables: number;
     readonly figures: number;
     readonly diagrams: number;
     readonly checks: number;
+    readonly examples: number;
   };
+  /**
+   * Every top-level heading in document order (`sections.mjs`): its anchor
+   * (`slug`, which the page's heading is given, and which `[[sec-slug]]`
+   * names), its text and level, and — for a `##` to the course's
+   * `numbering.sections.depth` — its outline number, `‹part›.‹chapter›.‹s›…`.
+   */
+  readonly headings: readonly {
+    readonly slug: string;
+    readonly text: string;
+    readonly level: number;
+    readonly number?: string;
+  }[];
   readonly file: string;
   readonly title: string;
   readonly description: string;
+  /** Authored reader-facing estimate; `40` and `[30, 40]` both land here. */
+  readonly studyMinutes?: { readonly min: number; readonly max: number };
   readonly status: EditorialStatus;
   /** Ordered — the curriculum contract. */
   readonly teaches: readonly string[];
   readonly requires: readonly string[];
   readonly assumptions: readonly string[];
   readonly assessments: readonly string[];
-  /** Numbered knowledge checks from `assessments`, in `.checks.yml` order. */
+  /**
+   * Numbered knowledge checks from `assessments`, in `.checks.yml` order,
+   * each with the `title` its assessment file gives it (v23) — the topic its
+   * heading shows after the engine's badge.
+   */
   readonly knowledgeChecks: readonly {
     readonly key: string;
     readonly number: string;
+    readonly title?: string;
   }[];
+  /**
+   * The blocks that draw an `<h2>` of their own (v23): each knowledge check
+   * and worked-example set, in document order, with that heading's `anchor`
+   * and `title` and `after`, the slug of the top-level heading it follows
+   * (absent before the first) — where "On this page" lists it.
+   */
+  readonly titledBlocks: readonly ManifestTitledBlock[];
   readonly sources: readonly string[];
   readonly citations: readonly ManifestCitation[];
   /** Competency prerequisite edges this lesson introduces. */
   readonly prereqEdges: readonly PrereqEdge[];
   /** Labelled display equations in appearance order (D7). */
-  readonly equations: readonly {
-    readonly key: string;
-    readonly number: string;
-  }[];
+  readonly equations: readonly ManifestLessonFloat[];
   /** Keyed `<Table>` elements in appearance order. */
-  readonly tables: readonly {
-    readonly key: string;
-    readonly number: string;
-  }[];
+  readonly tables: readonly ManifestLessonFloat[];
   /** Keyed `<Figure>` elements in appearance order. */
-  readonly figures: readonly {
-    readonly key: string;
-    readonly number: string;
-  }[];
+  readonly figures: readonly ManifestLessonFloat[];
   /** Keyed `<Diagram>` elements in appearance order. */
-  readonly diagrams: readonly {
-    readonly key: string;
-    readonly number: string;
-  }[];
+  readonly diagrams: readonly ManifestLessonFloat[];
+  /** Keyed `<CompactExamples>` sets in appearance order; `short` is the set's title (v23). */
+  readonly examples: readonly ManifestLessonFloat[];
   readonly notation: {
     readonly bindings: readonly {
       readonly key: string;
@@ -391,12 +538,46 @@ export interface ManifestAssessmentItemContent {
   readonly explanationSegments: readonly ContentSegment[];
 }
 
+/**
+ * One **part** (v17) — a sidebar group and the directory its chapters live in,
+ * with its chapters in reading order and its overview page when the course
+ * authored one at `content/docs/<dir>/index.mdx`.
+ *
+ * `link` is where the directory URL resolves; without an `overview` that URL
+ * has no page behind it, which is exactly the 404 a part-level page removes.
+ */
+export interface ManifestPart {
+  readonly dir: string;
+  readonly label: string;
+  /** 1-based position in `courseConfig.parts` — the float-number prefix. */
+  readonly ordinal: number;
+  /** Base-relative href of the part's own page, `/<dir>/`. */
+  readonly link: string;
+  /** Lesson ids in chapter order. */
+  readonly lessons: readonly string[];
+  /**
+   * The part's total study time — present only when **every** chapter in it
+   * states one, so a half-annotated part reports the chapters it knows and no
+   * misleading sum.
+   */
+  readonly studyMinutes?: { readonly min: number; readonly max: number };
+  readonly overview?: {
+    readonly title: string;
+    readonly file: string;
+    readonly description?: string;
+  };
+}
+
 export interface Manifest {
   readonly schemaVersion: number;
   /** Normalized build/UI settings for opt-in per-lesson exports. */
   readonly lessonExports: NormalizedLessonExports;
-  /** Initial open/closed state for "Page notation" and "References". */
-  readonly disclosureDefaults: NormalizedDisclosureDefaults;
+  /** Every collapse default, engine defaults applied (`CourseConfig.disclosure`). */
+  readonly disclosure: NormalizedDisclosure;
+  /** Outline and float numbering, defaults applied (`CourseConfig.numbering`). */
+  readonly numbering: NormalizedNumbering;
+  /** How a check's and an example set's heading names its kind (`CourseConfig.blockLabels`). */
+  readonly blockLabels: BlockLabels;
   /** Reader-facing identity + versions (the `[?]` About panel). */
   readonly about: ManifestAbout;
   readonly notation: {
@@ -413,6 +594,8 @@ export interface Manifest {
   /** Abbreviations table (N14), for `remarkAbbreviations`. Ordered by key. */
   readonly abbreviations: readonly Record<string, unknown>[];
   readonly sidebar: readonly SidebarGroup[];
+  /** The course's parts in config order, with their chapters and overview pages. */
+  readonly parts: readonly ManifestPart[];
   readonly lessons: readonly ManifestLesson[];
   /** Full competency prerequisite graph. */
   readonly prereqEdges: readonly PrereqEdge[];
@@ -442,6 +625,11 @@ export interface Manifest {
     readonly labels: readonly KnowledgeCheckLabelRecord[];
     readonly numbersBySlug: Record<string, Record<string, string>>;
   };
+  /** Keyed-float identity for `<CompactExamples>` — same shape as `figures` (v23). */
+  readonly examples: {
+    readonly labels: readonly ExampleLabelRecord[];
+    readonly numbersBySlug: Record<string, Record<string, string>>;
+  };
   /**
    * Every assessment item's `prompt` / `explanation`, pre-split into
    * text/math segments (v8). `AssessmentSet.astro` filters this by
@@ -452,6 +640,13 @@ export interface Manifest {
    * lesson's scope can resolve its glyphs differently.
    */
   readonly assessmentContent: readonly ManifestAssessmentItemContent[];
+  /**
+   * The course's rule switches and settings (`CourseConfig.rules`, resolved
+   * against `src/rules/catalog.ts`). `disabled` names the rules whose
+   * diagnostics are withheld below; `settings` is every rule's effective
+   * values, defaults applied.
+   */
+  readonly rules: ManifestRules;
   readonly diagnostics: {
     readonly curriculum: readonly CurriculumIssue[];
     readonly notation: readonly NotationDiagnostic[];
@@ -471,12 +666,20 @@ export interface Manifest {
     readonly diagrams: readonly DiagramDiagnostic[];
     /** Knowledge-check identity and `[[check-…]]` reference checks. */
     readonly checks: readonly KnowledgeCheckDiagnostic[];
+    /** `<CompactExamples>` identity checks — the keyed-float codes, `ex-` prefixed, plus `ex-missing-prop`. */
+    readonly examples: readonly ExampleDiagnostic[];
+    /** `<Fold>` checks: `fold-unnamed`, a fold with no `label` and no numbered float to name its bar by. */
+    readonly folds: readonly FoldDiagnostic[];
     /**
      * A raw Markdown table, a raw HTML `<table>`, or an Explico `<Diagram>`
      * that is unkeyed or nested outside `<Table>`/`<Figure>` — invisible to
      * keyed-float validation above. Warnings only.
      */
     readonly rawFloats: readonly RawFloatDiagnostic[];
+    /** Findings about `CourseConfig.rules` and the deprecated blocks it replaces. Warnings only. */
+    readonly config: readonly ConfigDiagnostic[];
+    /** Per-place waivers that are malformed, name an unwaivable rule, or silenced nothing. */
+    readonly waivers: readonly WaiverDiagnostic[];
   };
   readonly hashes: {
     /** `sha256` of every content source file, keyed by repo-relative path. */
@@ -617,13 +820,45 @@ function lessonNotationBundle(
   };
 }
 
-/** `title` / `description` from a lesson's raw docs frontmatter, keyed by id. */
+/**
+ * `studyMinutes: 40` and `studyMinutes: [30, 40]` are the same estimate; the
+ * manifest carries one shape so a total is a sum of two numbers.
+ */
+function studyMinutesRange(
+  value: unknown,
+): { min: number; max: number } | undefined {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    return { min: value, max: value };
+  }
+  if (
+    Array.isArray(value) &&
+    value.length === 2 &&
+    value.every((entry) => typeof entry === 'number' && entry > 0)
+  ) {
+    const [min, max] = value as [number, number];
+    return min <= max ? { min, max } : { min: max, max: min };
+  }
+  return undefined;
+}
+
+/** `title` / `description` / `studyMinutes` from a lesson's raw docs frontmatter. */
 function lessonFrontmatterById(): Map<
   string,
-  { title: string; description: string }
+  {
+    title: string;
+    description: string;
+    studyMinutes?: { min: number; max: number };
+  }
 > {
   const base = join(CONTENT_ROOT, 'docs');
-  const result = new Map<string, { title: string; description: string }>();
+  const result = new Map<
+    string,
+    {
+      title: string;
+      description: string;
+      studyMinutes?: { min: number; max: number };
+    }
+  >();
   const walk = (directory: string): void => {
     for (const entry of readdirSync(directory, { withFileTypes: true })) {
       const path = join(directory, entry.name);
@@ -637,10 +872,12 @@ function lessonFrontmatterById(): Map<
       const id = slug.replace(/\.(md|mdx)$/, '').replace(/\//g, '.');
       const data = (parseFrontmatter(readFileSync(path, 'utf8')).frontmatter ??
         {}) as Record<string, unknown>;
+      const studyMinutes = studyMinutesRange(data.studyMinutes);
       result.set(id, {
         title: typeof data.title === 'string' ? data.title : id,
         description:
           typeof data.description === 'string' ? data.description : '',
+        ...(studyMinutes === undefined ? {} : { studyMinutes }),
       });
     }
   };
@@ -672,6 +909,16 @@ export async function compileManifest(
     );
   }
 
+  // Every rule switch and setting, validated against the catalog. Throws on
+  // a wrong ID, key, or value — before any gate runs with it.
+  const rules = resolveRules(courseConfig);
+  // Codes a disabled rule owns — filtered out of every diagnostics group
+  // below; the whole-rule gates are skipped at their call site as well.
+  const off = disabledCodes(rules);
+  // Throws on a bad `numbering` or `blockLabels` value, like `resolveRules` above.
+  const numberingSettings = normalizeNumbering(courseConfig);
+  const blockLabels = normalizeBlockLabels(courseConfig);
+
   const [catalog, notationInput, abbreviationsInput] = await Promise.all([
     loadCurriculumCatalog(),
     loadNotationRegistryInput(),
@@ -697,11 +944,16 @@ export async function compileManifest(
 
   const assessmentsInput = catalog.assessments as unknown as {
     id: string;
+    title?: string;
     items?: { id?: string; prompt?: string; explanation?: string }[];
   }[];
 
   const curriculumIssues = validateCurriculum(catalog);
   const alignmentIssues = validateNotationAlignment(registry, catalog);
+  const mathEndAbbreviations = {
+    allow: rules.strings('N12', 'allow'),
+    deny: rules.strings('N12', 'deny'),
+  };
   const mathIssues = [
     ...gateContentMath({
       notationInput,
@@ -711,14 +963,42 @@ export async function compileManifest(
         assessmentIds: lesson.assessments,
       })),
     }),
-    ...gateProseNotation(notationInput.lessons),
-    ...gateProseNotationInAssessments(assessmentsInput),
-    ...gateAbbreviations({
-      notationInput,
-      abbreviations: abbreviationsInput,
-      courseAbbreviations: courseConfig.abbreviations,
+    ...(rules.isEnabled('N9')
+      ? [
+          ...gateProseNotation(notationInput.lessons, {
+            allowSpelledUnits: rules.strings('N9', 'allow'),
+          }),
+          ...gateProseNotationInAssessments(assessmentsInput, {
+            allowSpelledUnits: rules.strings('N9', 'allow'),
+          }),
+        ]
+      : []),
+    ...(rules.isEnabled('N12')
+      ? [
+          ...gateMathPunctuation(notationInput.lessons, mathEndAbbreviations),
+          ...gateMathPunctuationInAssessments(assessmentsInput, mathEndAbbreviations),
+        ]
+      : []),
+    ...(rules.isEnabled('N14')
+      ? gateAbbreviations({
+          notationInput,
+          abbreviations: abbreviationsInput,
+          courseAbbreviations: rules.settings('N14'),
+        })
+      : []),
+    ...(rules.isEnabled('S1')
+      ? gateHeadingLength(notationInput.lessons, {
+          maxLength: rules.number('S1', 'maxLength'),
+        })
+      : []),
+    ...gateHeadingStructure(notationInput.lessons, {
+      levels: rules.isEnabled('S6'),
+      adjacency: rules.isEnabled('S7'),
     }),
-    ...gateHeadingLength(notationInput.lessons),
+    // The course's own rules (`courseRules`): one pass for every enabled `X`
+    // rule that carries a `forbid` pattern. A disabled one, and a guide rule
+    // with no pattern, do no work here.
+    ...gateCourseRules(notationInput.lessons, rules.course),
   ];
 
   // Pre-render every assessment `prompt` / `explanation` into text/math
@@ -780,20 +1060,60 @@ export async function compileManifest(
   const lessonSlugs = [...notationInput.lessons]
     .map((lesson) => lesson.lessonId.replace(/\./g, '/'))
     .sort();
+  const configuredParts = coursePartsOf(courseConfig);
+  const overviewPages = loadPartOverviews(configuredParts);
+  const overviewByDir = new Map(overviewPages.map((page) => [page.dir, page]));
+  // S2: every authored part page carries its bridge and scope paragraphs.
+  if (rules.isEnabled('S2')) {
+    mathIssues.push(
+      ...gatePartPages(
+        overviewPages.map((page) => ({
+          ...page,
+          ordinal: configuredParts.findIndex((part) => part.dir === page.dir) + 1,
+        })),
+        partPageLimits(rules),
+      ),
+    );
+  }
+  // Per-place waivers: drop the located findings each one covers, and
+  // report the waivers themselves — a stale one is a warning, a bad one an
+  // error. Only lesson bodies are scanned; a part page has no waivable rule.
+  const waiverDiagnostics: WaiverDiagnostic[] = [];
+  const waiverRules = { courseRules: rules.course };
+  const waivers = notationInput.lessons.flatMap((lesson) => {
+    const collected = collectWaivers(lesson, waiverRules);
+    waiverDiagnostics.push(...collected.diagnostics);
+    return collected.waivers;
+  });
+  const waived = applyWaivers(mathIssues, waivers, waiverRules);
+  mathIssues.splice(0, mathIssues.length, ...waived.kept);
+  waiverDiagnostics.push(...waived.unused);
+
   const sidebar = buildSidebar(
     catalog.tracks.map((track) => ({ id: track.id, lessons: track.lessons })),
     lessonSlugs,
-    coursePartsOf(courseConfig),
+    configuredParts.map((part) => ({
+      ...part,
+      ...(overviewByDir.has(part.dir)
+        ? { overviewLink: `/${part.dir}/` }
+        : {}),
+    })),
+    {
+      floatIndex: ['.mdx', '.md'].some((extension) =>
+        existsSync(join(CONTENT_ROOT, 'docs', `figures-and-tables${extension}`)),
+      ),
+    },
   );
 
   // Part and chapter, read straight off the sidebar so there is one
   // lesson-ordering source and not two: a part is a sidebar group (parts in
   // config order), a chapter is a lesson's position inside its part (merged
-  // track order, then slug). The part is what prefixes every numbered item —
-  // `(2.1)` is the first item of one independent kind in part 2 — while `n`
-  // continues across the part's chapters rather than restarting on each page,
-  // so every lesson also needs the running count that precedes it.
-  // See `docs/authoring/structure.md`.
+  // track order, then slug). Both prefix every section number (`1.2.3`).
+  // A float number is `‹prefix›.‹n›`, each kind counting on its own: under
+  // `numbering.floats: "chapter"` the prefix is `‹part›.‹chapter›` and `n`
+  // restarts in every chapter; under `"part"` the prefix is the part alone
+  // and `n` runs on across its chapters, so every lesson also needs the
+  // running count that precedes it. See `docs/authoring/structure.md`.
   const bodyByLessonId = new Map(
     notationInput.lessons.map((lesson) => [lesson.lessonId, lesson.body]),
   );
@@ -802,15 +1122,10 @@ export async function compileManifest(
     {
       part: number;
       chapter: number;
-      numbering: {
-        equations: number;
-        tables: number;
-        figures: number;
-        diagrams: number;
-        checks: number;
-      };
+      numbering: ManifestLesson['numbering'];
     }
   >();
+  const chapterScoped = numberingSettings.floats === 'chapter';
   let partCursor = 0;
   for (const group of sidebar) {
     const lessonIds = group.items
@@ -818,32 +1133,122 @@ export async function compileManifest(
       .map(lessonIdFromSlug);
     if (lessonIds.length === 0) continue; // the static Reference group
     partCursor += 1;
-    // Running totals for this part, advanced one chapter at a time.
+    // Running totals for this part, advanced one chapter at a time; they
+    // only reach a number under the part scope.
     const used = {
       equations: 0,
       tables: 0,
       figures: 0,
       diagrams: 0,
       checks: 0,
+      examples: 0,
     };
     let chapterCursor = 0;
     for (const lessonId of lessonIds) {
       const body = bodyByLessonId.get(lessonId) ?? '';
+      const chapter = ++chapterCursor;
       placementByLessonId.set(lessonId, {
         part: partCursor,
-        chapter: ++chapterCursor,
-        numbering: { ...used },
+        chapter,
+        numbering: chapterScoped
+          ? {
+              prefix: `${partCursor}.${chapter}`,
+              equations: 0,
+              tables: 0,
+              figures: 0,
+              diagrams: 0,
+              checks: 0,
+              examples: 0,
+            }
+          : { prefix: String(partCursor), ...used },
       });
       used.equations += countDisplayEquations(body);
       used.tables += countKeyedJsxFloats(body, { tagName: 'Table' });
       used.figures += countKeyedJsxFloats(body, { tagName: 'Figure' });
       used.diagrams += countKeyedJsxFloats(body, { tagName: 'Diagram' });
       used.checks += lessonMetaById.get(lessonId)?.assessments.length ?? 0;
+      used.examples += countKeyedJsxFloats(body, { tagName: 'CompactExamples' });
     }
   }
 
+  // The outline: every lesson's top-level headings with their anchors and,
+  // for a placed lesson, their `‹part›.‹chapter›.‹s›…` numbers. A `[[sec-…]]`
+  // must name one of them.
+  const headingsByLessonId = new Map(
+    notationInput.lessons.map((lesson) => {
+      const placement = placementByLessonId.get(lesson.lessonId);
+      return [
+        lesson.lessonId,
+        scanSectionHeadings(lesson.body, {
+          ...(placement
+            ? { prefix: `${placement.part}.${placement.chapter}` }
+            : {}),
+          depth: numberingSettings.sections.depth,
+        }) as ManifestLesson['headings'],
+      ];
+    }),
+  );
+  mathIssues.push(
+    ...validateSectionRefs(
+      notationInput.lessons.map((lesson) => ({
+        slug: lesson.lessonId.replace(/\./g, '/'),
+        file: lesson.source.file,
+        body: lesson.body,
+        ...(lesson.bodyLine === undefined ? {} : { bodyLine: lesson.bodyLine }),
+        headingSlugs: (headingsByLessonId.get(lesson.lessonId) ?? []).map(
+          (heading) => heading.slug,
+        ),
+      })),
+    ),
+  );
+
+  // The parts themselves, in config order, with their chapters in reading
+  // order — the one place a part-level page or a breadcrumb reads, so neither
+  // has to re-derive a part from lesson slugs.
+  const manifestParts: ManifestPart[] = configuredParts.map((part, index) => {
+    const overview = overviewByDir.get(part.dir);
+    const lessonIds = [...placementByLessonId]
+      .filter(([lessonId]) => lessonId.startsWith(`${part.dir}.`))
+      .sort(([, a], [, b]) => a.chapter - b.chapter)
+      .map(([lessonId]) => lessonId);
+    const chapterMinutes = lessonIds.map(
+      (lessonId) => frontmatterById.get(lessonId)?.studyMinutes,
+    );
+    // A total only means something when no chapter is missing from it.
+    const studyMinutes =
+      chapterMinutes.length > 0 &&
+      chapterMinutes.every((range) => range !== undefined)
+        ? chapterMinutes.reduce(
+            (total, range) => ({
+              min: total.min + range!.min,
+              max: total.max + range!.max,
+            }),
+            { min: 0, max: 0 },
+          )
+        : undefined;
+    return {
+      dir: part.dir,
+      label: part.label,
+      ordinal: index + 1,
+      link: `/${part.dir}/`,
+      lessons: lessonIds,
+      ...(studyMinutes === undefined ? {} : { studyMinutes }),
+      ...(overview
+        ? {
+            overview: {
+              title: overview.title,
+              file: overview.file,
+              ...(overview.description === undefined
+                ? {}
+                : { description: overview.description }),
+            },
+          }
+        : {}),
+    };
+  });
+
   const floatInputs = (
-    kind: 'equations' | 'tables' | 'figures' | 'diagrams',
+    kind: 'equations' | 'tables' | 'figures' | 'diagrams' | 'examples',
   ) =>
     notationInput.lessons.map((lesson) => {
       const placement = placementByLessonId.get(lesson.lessonId);
@@ -855,41 +1260,49 @@ export async function compileManifest(
         ...(placement
           ? {
               numbering: {
-                prefix: placement.part,
+                prefix: placement.numbering.prefix,
                 offset: placement.numbering[kind],
               },
             }
           : {}),
       };
     });
+  // `lessons[].equations` / `.tables` / `.figures` / `.diagrams` /
+  // `.examples`: each keyed float of the lesson in appearance order, with its
+  // caption pair (v21) — an example set's `short` is its title.
+  const floatsBySlug = (
+    labels: readonly {
+      readonly slug: string;
+      readonly key: string;
+      readonly number: string;
+      readonly short?: string;
+      readonly caption?: string;
+    }[],
+  ): Map<string, ManifestLessonFloat[]> => {
+    const bySlug = new Map<string, ManifestLessonFloat[]>();
+    for (const { slug, key, number, short, caption } of labels) {
+      const list = bySlug.get(slug) ?? [];
+      list.push({
+        key,
+        number,
+        ...(short === undefined ? {} : { short }),
+        ...(caption === undefined ? {} : { caption }),
+      });
+      bySlug.set(slug, list);
+    }
+    return bySlug;
+  };
   const equationValidation = validateEquations(floatInputs('equations'));
-  const equationsBySlug = new Map(
-    Object.entries(equationValidation.numbersBySlug).map(([slug, table]) => [
-      slug,
-      Object.entries(table).map(([key, number]) => ({ key, number })),
-    ]),
-  );
+  const equationsBySlug = floatsBySlug(equationValidation.labels);
   const tableValidation = validateTables(floatInputs('tables'));
-  const tablesBySlug = new Map(
-    Object.entries(tableValidation.numbersBySlug).map(([slug, table]) => [
-      slug,
-      Object.entries(table).map(([key, number]) => ({ key, number })),
-    ]),
-  );
+  const tablesBySlug = floatsBySlug(tableValidation.labels);
   const figureValidation = validateFigures(floatInputs('figures'));
-  const figuresBySlug = new Map(
-    Object.entries(figureValidation.numbersBySlug).map(([slug, table]) => [
-      slug,
-      Object.entries(table).map(([key, number]) => ({ key, number })),
-    ]),
-  );
+  const figuresBySlug = floatsBySlug(figureValidation.labels);
   const diagramValidation = validateDiagrams(floatInputs('diagrams'));
-  const diagramsBySlug = new Map(
-    Object.entries(diagramValidation.numbersBySlug).map(([slug, table]) => [
-      slug,
-      Object.entries(table).map(([key, number]) => ({ key, number })),
-    ]),
-  );
+  const diagramsBySlug = floatsBySlug(diagramValidation.labels);
+  const exampleValidation = validateExamples(floatInputs('examples'));
+  const examplesBySlug = floatsBySlug(exampleValidation.labels);
+  const foldValidation = validateFolds(floatInputs('figures'));
   const checkValidation = validateKnowledgeChecks(
     notationInput.lessons.map((lesson) => {
       const placement = placementByLessonId.get(lesson.lessonId);
@@ -903,7 +1316,7 @@ export async function compileManifest(
         ...(placement
           ? {
               numbering: {
-                prefix: placement.part,
+                prefix: placement.numbering.prefix,
                 offset: placement.numbering.checks,
               },
             }
@@ -911,12 +1324,51 @@ export async function compileManifest(
       };
     }),
   );
+  // Each check with the title its heading shows after the badge (v23).
+  const checkTitleById = new Map(
+    assessmentsInput.map((assessment) => [assessment.id, assessment.title]),
+  );
   const checksBySlug = new Map(
     Object.entries(checkValidation.numbersBySlug).map(([slug, table]) => [
       slug,
-      Object.entries(table).map(([key, number]) => ({ key, number })),
+      Object.entries(table).map(([key, number]) => {
+        const title = checkTitleById.get(key);
+        return { key, number, ...(title === undefined ? {} : { title }) };
+      }),
     ]),
   );
+  // The blocks that draw an `<h2>` where their tag stands, placed after the
+  // outline heading they follow — "On this page" lists them there (v23).
+  // `<AssessmentSet />` draws every check of the lesson, or the one its `id`
+  // names; `<CompactExamples>` draws its own set.
+  const titledBlocksFor = (lessonId: string): ManifestTitledBlock[] => {
+    const slug = lessonId.replace(/\./g, '/');
+    const body = bodyByLessonId.get(lessonId) ?? '';
+    const headings = headingsByLessonId.get(lessonId) ?? [];
+    const checks = checksBySlug.get(slug) ?? [];
+    const examples = examplesBySlug.get(slug) ?? [];
+    return scanTitledBlocks(body, ['AssessmentSet', 'CompactExamples']).flatMap(
+      (block: { name: string; heading: number; id?: string }): ManifestTitledBlock[] => {
+        const after = headings[block.heading]?.slug;
+        const place = after === undefined ? {} : { after };
+        if (block.name === 'CompactExamples') {
+          const set = examples.find((example) => example.key === block.id);
+          return set?.short
+            ? [{ kind: 'example' as const, key: set.key, anchor: `ex-${set.key}`, title: set.short, ...place }]
+            : [];
+        }
+        return checks
+          .filter((check) => block.id === undefined || check.key === block.id)
+          .map((check) => ({
+            kind: 'check' as const,
+            key: check.key,
+            anchor: knowledgeCheckAnchorId(check.key),
+            title: check.title ?? check.key,
+            ...place,
+          }));
+      },
+    );
+  };
   const rawFloatDiagnostics = validateRawFloats(
     notationInput.lessons.map((lesson) => ({
       lessonId: lesson.lessonId,
@@ -945,27 +1397,35 @@ export async function compileManifest(
       part: placementByLessonId.get(id)?.part ?? 0,
       chapter: placementByLessonId.get(id)?.chapter ?? 0,
       numbering: placementByLessonId.get(id)?.numbering ?? {
+        prefix: '',
         equations: 0,
         tables: 0,
         figures: 0,
         diagrams: 0,
         checks: 0,
+        examples: 0,
       },
+      headings: headingsByLessonId.get(id) ?? [],
       file: notationLesson.source.file,
       title: frontmatter.title,
       description: frontmatter.description,
+      ...(frontmatter.studyMinutes === undefined
+        ? {}
+        : { studyMinutes: frontmatter.studyMinutes }),
       status: meta.status,
       teaches: [...teaches],
       requires: [...meta.requires],
       assumptions: [...meta.assumptions],
       assessments: [...meta.assessments],
       knowledgeChecks: checksBySlug.get(id.replace(/\./g, '/')) ?? [],
+      titledBlocks: titledBlocksFor(id),
       sources: deriveSources(notationLesson.body),
       citations: lessonCitations(notationLesson.body),
       equations: equationsBySlug.get(id.replace(/\./g, '/')) ?? [],
       tables: tablesBySlug.get(id.replace(/\./g, '/')) ?? [],
       figures: figuresBySlug.get(id.replace(/\./g, '/')) ?? [],
       diagrams: diagramsBySlug.get(id.replace(/\./g, '/')) ?? [],
+      examples: examplesBySlug.get(id.replace(/\./g, '/')) ?? [],
       prereqEdges: sortEdges(
         teaches.flatMap((to) =>
           (prerequisitesById.get(to) ?? [])
@@ -994,12 +1454,9 @@ export async function compileManifest(
     catalog,
     lintIgnore: loadLintIgnore(),
     conventions: courseConfig.conventions,
-    ...(courseConfig.operators === undefined
-      ? {}
-      : { operators: courseConfig.operators }),
-    ...(courseConfig.romanLabels === undefined
-      ? {}
-      : { romanLabels: courseConfig.romanLabels }),
+    operators: rules.settings('N8'),
+    romanLabels: rules.settings('N10'),
+    accents: rules.settings('N22'),
   });
 
   const rawNotation = [...loadNotationDefinitions()].sort((a, b) =>
@@ -1068,7 +1525,9 @@ export async function compileManifest(
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
     lessonExports: normalizeLessonExports(courseConfig),
-    disclosureDefaults: normalizeDisclosureDefaults(courseConfig),
+    disclosure: normalizeDisclosure(courseConfig),
+    numbering: numberingSettings,
+    blockLabels,
     about,
     notation: {
       definitions: registry.definitions,
@@ -1082,6 +1541,7 @@ export async function compileManifest(
     tracks,
     abbreviations,
     sidebar,
+    parts: manifestParts,
     lessons,
     prereqEdges,
     equations: {
@@ -1104,20 +1564,29 @@ export async function compileManifest(
       labels: checkValidation.labels,
       numbersBySlug: checkValidation.numbersBySlug,
     },
+    examples: {
+      labels: exampleValidation.labels,
+      numbersBySlug: exampleValidation.numbersBySlug,
+    },
     assessmentContent,
+    rules: rulesSnapshot(rules),
     diagnostics: {
-      curriculum: curriculumIssues,
-      notation: registry.diagnostics,
-      alignment: alignmentIssues,
-      math: mathIssues,
-      consistency: consistencyIssues,
-      equations: equationValidation.diagnostics,
-      tables: tableValidation.diagnostics,
-      figures: figureValidation.diagnostics,
-      diagrams: diagramValidation.diagnostics,
-      checks: checkValidation.diagnostics,
-      knowledge: knowledge.diagnostics,
-      rawFloats: rawFloatDiagnostics,
+      curriculum: dropDisabled(curriculumIssues, off),
+      notation: dropDisabled(registry.diagnostics, off),
+      alignment: dropDisabled(alignmentIssues, off),
+      math: dropDisabled(mathIssues, off),
+      consistency: dropDisabled(consistencyIssues, off),
+      equations: dropDisabled(equationValidation.diagnostics, off),
+      tables: dropDisabled(tableValidation.diagnostics, off),
+      figures: dropDisabled(figureValidation.diagnostics, off),
+      diagrams: dropDisabled(diagramValidation.diagnostics, off),
+      checks: dropDisabled(checkValidation.diagnostics, off),
+      examples: dropDisabled(exampleValidation.diagnostics, off),
+      folds: dropDisabled(foldValidation.diagnostics, off),
+      knowledge: dropDisabled(knowledge.diagnostics, off),
+      rawFloats: dropDisabled(rawFloatDiagnostics, off),
+      config: rules.diagnostics,
+      waivers: waiverDiagnostics,
     },
     hashes,
   };