explico 0.11.1 → 0.13.0

package/dist/reference/types.d.ts

@@ -1,4 +1,3 @@
-type EditorialStatus = 'draft' | 'in-review' | 'reviewed';
 interface SourceSpan {
     readonly file: string;
     readonly line?: number;
@@ -14,7 +13,13 @@ type NotationAlignment = {
     readonly kind: 'general';
     readonly rationale: string;
 };
-type NotationReferenceKind = 'prose' | 'math' | 'definition';
+/**
+ * Where a reference was written: in prose, in math, in a definition's meaning
+ * or body, or in its `formula`. A formula's references bring their cards onto
+ * the page but are no dependency: two formulas may name each other
+ * (γ = 1 − α, α = 1 − γ).
+ */
+type NotationReferenceKind = 'prose' | 'math' | 'definition' | 'formula';
 /**
  * A gloss resolved by the loader (D15). Declared on a card, keyed
  * `<card key>.<slug(name)>`, and deliberately absent from the registry: a
@@ -42,10 +47,17 @@ interface SharedNotationDefinitionInput {
     readonly domain: string;
     readonly formula?: string;
     readonly units?: string;
+    /** Rule N23: an index entry's title for what it indexes, `{base} …`. */
+    readonly reads?: string;
+    /** Rule N23: the set a running index letter runs over. */
+    readonly range?: string;
+    /** Rule N23: as an index, a fixed label rather than a running position. */
+    readonly fixedIndex?: true;
+    /** Rule N23: an index entry's `formula` as written, `{base}` unbound. */
+    readonly formulaTemplate?: string;
     readonly sources: readonly string[];
     readonly seeAlso: readonly string[];
     readonly alignment: NotationAlignment;
-    readonly status: EditorialStatus;
     readonly aiAssisted: boolean;
     readonly body: string;
     /** References harvested from the Markdown body. */
@@ -61,6 +73,14 @@ interface LocalNotationDefinitionInput {
     readonly summary: string;
     readonly formula?: string;
     readonly units?: string;
+    /** Rule N23: an index entry's title for what it indexes, `{base} …`. */
+    readonly reads?: string;
+    /** Rule N23: the set a running index letter runs over. */
+    readonly range?: string;
+    /** Rule N23: as an index, a fixed label rather than a running position. */
+    readonly fixedIndex?: true;
+    /** Rule N23: an index entry's `formula` as written, `{base}` unbound. */
+    readonly formulaTemplate?: string;
     readonly sources: readonly string[];
     readonly seeAlso: readonly string[];
     readonly alignment: NotationAlignment;
@@ -83,7 +103,6 @@ interface NotationSuspension {
 }
 interface NotationLessonInput {
     readonly lessonId: string;
-    readonly status: EditorialStatus;
     readonly localDefinitions: readonly LocalNotationDefinitionInput[];
     /**
      * Decorations this page suspends (`notation.suspend`, rule N22). Optional
@@ -122,7 +141,7 @@ interface AbbreviationDefinitionInput {
     readonly domain?: string;
     readonly source: SourceSpan;
 }
-type NotationDiagnosticCode = 'invalid-key' | 'duplicate-page' | 'duplicate-definition' | 'conflicting-definition' | 'undefined-reference' | 'reference-cycle' | 'unused-definition' | 'alignment-unknown-competency' | 'alignment-unknown-lesson' | 'alignment-introduction' | 'alignment-unavailable' | 'alignment-review-state' | 'gloss-collides-with-card';
+type NotationDiagnosticCode = 'invalid-key' | 'duplicate-page' | 'duplicate-definition' | 'conflicting-definition' | 'undefined-reference' | 'reference-cycle' | 'unused-definition' | 'local-shadows-shared' | 'malformed-reference' | 'alignment-unknown-competency' | 'alignment-unknown-lesson' | 'alignment-introduction' | 'alignment-unavailable' | 'gloss-collides-with-card';
 type DiagnosticSeverity = 'error' | 'warning' | 'info';
 interface NotationDiagnostic {
     readonly code: NotationDiagnosticCode;
@@ -159,9 +178,16 @@ interface NotationDefinitionRecordBase {
     readonly scope: NotationDefinitionScope;
     readonly notation: string;
     readonly label: string;
+    /** Rule N23: an index entry's title for what it indexes, `{base} …`. */
+    readonly reads?: string;
+    /** Rule N23: the set a running index letter runs over. */
+    readonly range?: string;
+    /** Rule N23: as an index, a fixed label rather than a running position. */
+    readonly fixedIndex?: true;
+    /** Rule N23: an index entry's `formula` as written, `{base}` unbound. */
+    readonly formulaTemplate?: string;
     readonly seeAlso: readonly string[];
     readonly alignment: NotationAlignment;
-    readonly status: EditorialStatus;
     readonly source: SourceSpan;
     readonly resolvedReferences: readonly ResolvedNotationReference[];
 }
@@ -191,7 +217,6 @@ interface NotationBinding {
 }
 interface NotationPageBundle {
     readonly lessonId: string;
-    readonly status: EditorialStatus;
     readonly source: SourceSpan;
     readonly bindings: readonly NotationBinding[];
     readonly definitionIds: readonly string[];
@@ -208,5 +233,36 @@ interface NotationRegistry {
     readonly backlinks: readonly NotationBacklink[];
     readonly diagnostics: readonly NotationDiagnostic[];
 }
+/** A derived card a math source uses (rule N23): `key` is `<base>.sub.<index>`. */
+interface DerivedUse {
+    readonly key: string;
+    readonly base: string;
+    readonly index: string;
+}
+/**
+ * How one symbol with a subscript is explained (rule N23), as
+ * `resolveMathGlyphs` reports it in `indices`.
+ */
+interface IndexedSymbol {
+    readonly token: string;
+    readonly start: number;
+    readonly end: number;
+    readonly base: string;
+    readonly index: string;
+    readonly how: 'whole-form' | 'family' | 'derived' | 'inside-form' | 'explicit' | 'swallowed' | 'inside-wrap' | 'composed' | 'unresolved';
+    readonly key: string | null;
+    readonly explained: boolean;
+    readonly baseExplained: boolean;
+    /** The parts no card explains: the base first, when it has none, then each slot. */
+    readonly unexplained: readonly string[];
+    /** Running index letters (`i`, `k`, `t`) in its slots, for the index-set check. */
+    readonly running: readonly {
+        readonly letter: string;
+        readonly start: number;
+        readonly end: number;
+        readonly key: string | null;
+        readonly cover: string | null;
+    }[];
+}
 
-export type { AbbreviationDefinitionInput, DiagnosticSeverity, EditorialStatus, LocalNotationDefinitionInput, LocalNotationDefinitionRecord, NotationAlignment, NotationBacklink, NotationBinding, NotationDefinitionRecord, NotationDefinitionScope, NotationDiagnostic, NotationDiagnosticCode, NotationGlossEntry, NotationLessonInput, NotationPageBundle, NotationReferenceInput, NotationReferenceKind, NotationRegistry, NotationRegistryInput, NotationSuspension, ResolvedNotationReference, SharedNotationDefinitionInput, SharedNotationDefinitionRecord, SourceSpan };
+export type { AbbreviationDefinitionInput, DerivedUse, DiagnosticSeverity, IndexedSymbol, LocalNotationDefinitionInput, LocalNotationDefinitionRecord, NotationAlignment, NotationBacklink, NotationBinding, NotationDefinitionRecord, NotationDefinitionScope, NotationDiagnostic, NotationDiagnosticCode, NotationGlossEntry, NotationLessonInput, NotationPageBundle, NotationReferenceInput, NotationReferenceKind, NotationRegistry, NotationRegistryInput, NotationSuspension, ResolvedNotationReference, SharedNotationDefinitionInput, SharedNotationDefinitionRecord, SourceSpan };

package/dist/rules/catalog.js

@@ -20,6 +20,7 @@ const GATE_MATH = { module: "src/reference/gate-math.ts", fn: "resolveInto" };
 const GLYPHS = { module: "src/reference/math-glyphs.mjs", fn: "resolveMathGlyphs" };
 const REGISTRY = { module: "src/reference/registry.ts", fn: "buildNotationRegistry" };
 const KEYED_FLOATS = { module: "src/reference/keyed-float-validate.ts", fn: "validateKeyedFloats" };
+const INDICES = { module: "src/reference/gate-indices.ts", fn: "gateIndices" };
 function consistency(fn) {
   return { module: "src/reference/consistency.ts", fn };
 }
@@ -35,10 +36,28 @@ function keyedFloatChecks() {
       check(`${prefix}-duplicate-key`, "error", false, emitter),
       check(`${prefix}-ref-resolves`, "error", false, emitter)
     );
+    if (prefix === "eq") {
+      out.push(
+        check("eq-label-repeated", "error", false, emitter),
+        // LaTeX's `\eqref{eq:key}` in prose, which MDX cannot parse.
+        check("eq-latex-ref", "error", false, emitter)
+      );
+    }
     if (prefix === "tab" || prefix === "fig" || prefix === "dia" || prefix === "ex") {
       out.push(check(`${prefix}-key-unused`, "info", false, emitter));
       out.push(check(`${prefix}-removed-prop`, "error", false, emitter));
     }
+    if (prefix !== "eq" && prefix !== "check") {
+      out.push(check(`${prefix}-unread-prop`, "warning", false, emitter));
+    }
+    if (prefix === "tab") {
+      out.push(
+        check("tab-several-tables", "error", false, {
+          module: "src/reference/tables-validate.ts",
+          fn: "validateTables"
+        })
+      );
+    }
   }
   out.push(
     check("ex-missing-prop", "error", false, {
@@ -50,6 +69,10 @@ function keyedFloatChecks() {
     check("sec-ref-resolves", "error", true, {
       module: "src/reference/sections-validate.ts",
       fn: "validateSectionRefs"
+    }),
+    check("heading-anchor-collision", "error", true, {
+      module: "src/reference/sections-validate.ts",
+      fn: "validateHeadingAnchors"
     })
   );
   out.push(
@@ -161,7 +184,7 @@ const RULES = [
     title: "A physical quantity, unit, or math operator is typeset in `$\u2026$`, never as plain text \u2014 in prose, a table cell, an assessment `prompt` / `explanation`, or a caption that itself lives outside math.",
     elements: ["prose", "assessment", "table"],
     doc: "notation.md#n9",
-    summary: 'Never write `45 m/s`, `t (s)`, `vx` or `KE/m` as plain text, and never spell a stated quantity\'s unit out: "4 seconds", "2 meters per second squared", "30 degrees", "$x = 3$ meters" are `$4\\ \\text{s}$`, `$2\\ \\text{m/s}^2$`, `$30^{\\circ}$`, `$x = 3\\ \\text{m}$`. A unit inside math is `\\text{}`-wrapped, short form, in the same span as its number or symbol. A unit named on its own ("measured in meters") stays a word; a sentence that defines a unit is waived. JSX prop strings (`caption="\u2026"`) and assessment choice labels render no math, so N9 does not apply there.',
+    summary: 'Never write `45 m/s`, `t (s)`, `vx` or `KE/m` as plain text, and never spell a stated quantity\'s unit out: "4 seconds", "2 meters per second squared", "30 degrees", "$x = 3$ meters" are `$4\\ \\text{s}$`, `$2\\ \\text{m/s}^2$`, `$30^{\\circ}$`, `$x = 3\\ \\text{m}$`. A unit inside math is `\\text{}`-wrapped, short form, in the same span as its number or symbol. A unit named on its own ("measured in meters") stays a word; a sentence that defines a unit is waived. JSX prop strings (`caption="\u2026"`) render no math, so N9 does not apply there; nor does it apply to an assessment choice label, which may still hold math (`$30^{\\circ}$`).',
     checks: [
       check(
         "prose-notation",
@@ -314,7 +337,7 @@ const RULES = [
     title: "A notation entry states its `units`, or declares itself `dimensionless`, using the units vocabulary.",
     elements: ["notation"],
     doc: "notation.md#n19",
-    summary: "Every notation entry has `units:` from `units-vocab.ts` (`m/s`, `s`, `kg`, \u2026) or `dimensionless: true`. A token outside the vocabulary is a warning.",
+    summary: 'Every notation entry has `units:` from `units-vocab.ts` (`m/s`, `s`, `kg`, \u2026) or `dimensionless: true`, except an index entry (`latex: "{}_0"`, N23), which takes neither. A token outside the vocabulary is a warning.',
     checks: [
       check("notation-units", "warning", false, consistency("checkNotationUnits")),
       check("units-vocab", "warning", false, consistency("checkNotationUnits"))
@@ -339,7 +362,7 @@ const RULES = [
     title: "A gloss is named by a short noun phrase, not described by a sentence.",
     elements: ["notation"],
     doc: "notation.md#n21",
-    summary: "A gloss `label` names the symbol in a few words (\u201Claunch angle\u201D); a clause, sentence punctuation, or a definition belongs in a full notation entry instead.",
+    summary: "A gloss `name` names the symbol in a few words (\u201Claunch angle\u201D); a clause, sentence punctuation, or a definition belongs in a full notation entry instead.",
     checks: [check("gloss-name-shape", "warning", false, consistency("checkGlossNameShape"))]
   },
   {
@@ -352,6 +375,7 @@ const RULES = [
     summary: "A decoration (`\\hat`, `\\bar`, `\\overline`, `'`, `^*`, `^\\dagger`, \u2026) is on the course\u2019s `allow` list (shipped empty), explained by an operator entry (`latex: \\hat{}`), or the decorated form has its own entry (`latex: \\hat{\\beta}`), which wins for that form. A page may suspend a decoration in `notation.suspend`, with a `reason`; every decorated form of it there then needs its own entry.",
     checks: [
       check("accent-explained", "warning", false, consistency("checkAccentExplained")),
+      check("accent-swallowed", "warning", false, consistency("checkAccentExplained")),
       check("suspended-operator-unresolved", "error", true, GATE_MATH),
       check("operator-suspension-reason", "warning", false, consistency("checkOperatorSuspension")),
       check("operator-suspended", "info", false, consistency("checkOperatorSuspension")),
@@ -359,6 +383,22 @@ const RULES = [
     ],
     settings: baselineEdits("Decorations")
   },
+  {
+    kind: "rule",
+    id: "N23",
+    short: "An index is part of the symbol: whole form, family or index entry",
+    title: "An index is part of the symbol: a subscript is explained by the indexed symbol\u2019s entry, a family entry, or an index entry.",
+    elements: ["math", "notation"],
+    doc: "notation.md#n23",
+    summary: 'A subscript on a symbol is explained by the indexed symbol\u2019s own entry (`latex: v_0`), a family entry whose index runs (`latex: x_k` explains `x_1`), or an index entry for the subscript (`latex: "{}_0"`, which composes a derived card); a card on the base alone does not explain it, and arithmetic on an index letter with its own card does (`X_{t-1}`). A running index \u2014 a lowercase letter not marked `fixedIndex` \u2014 states its set, as `range` on its card or after a `\\quad` on the first display line that uses it. Never wrap an indexed symbol in `\\explain` with a key whose `latex` has no index.',
+    checks: [
+      check("index-explained", "error", true, INDICES),
+      check("index-swallowed", "error", true, INDICES),
+      check("index-range", "error", true, INDICES),
+      check("derived-key-taken", "error", true, INDICES)
+    ],
+    unchecked: "whether a `\\quad` clause states the set correctly; whether a lowercase index is really running; lab math whose glyph table is a copy of the one `labMathScope` returned."
+  },
   // ---- V — visualizations -----------------------------------------------------
   {
     kind: "rule",
@@ -387,8 +427,18 @@ const RULES = [
     title: "Interactive figures: a hydrated island and the `renderLabMath` seam for equations.",
     elements: ["plot"],
     doc: "visualizations.md#v3",
-    summary: "An interactive figure is an island under `content/labs/` inside a `<Figure>`, renders its equations through `renderLabMath`, and labels its controls; the figure\u2019s caption is its name, so the lab writes no accessible name or text alternative of its own.",
-    checks: []
+    summary: "An interactive figure is an island under `content/labs/` inside a `<Figure>`, renders its equations through `renderLabMath` (`{ display: false }` for a legend, an axis title or a label; a `{ math }` run for the caption clause) and never KaTeX directly, and labels its controls; the figure\u2019s caption is its name, so the lab writes no accessible name or text alternative of its own. Its default picture is drawn at build time too and handed to the island as children, so the built page has it.",
+    checks: [
+      check("lab-katex-direct", "error", false, {
+        module: "src/reference/lab-katex-validate.ts",
+        fn: "validateLabKatexImports"
+      }),
+      check("lab-picture-undrawn", "warning", false, {
+        module: "src/reference/figure-pictures.ts",
+        fn: "undrawnFigurePictures"
+      })
+    ],
+    unchecked: "that a lab labels its controls and writes no name of its own, and math a lab draws without importing `katex` \u2014 the build\u2019s rendered check (`figure-symbols.ts`) covers the page it renders."
   },
   {
     kind: "rule",
@@ -436,6 +486,53 @@ const RULES = [
       }
     ]
   },
+  {
+    kind: "rule",
+    id: "V7",
+    short: "A figure\u2019s picture fits on one screen",
+    title: "A figure\u2019s picture takes at most `maxPercent` of the screen height.",
+    elements: ["plot"],
+    doc: "visualizations.md#v7",
+    summary: "The default slot of a `<Figure>` \u2014 plot, key and tables \u2014 stays within `maxPercent` of the viewport height, so the reader sees the picture and its caption line together. A square or tall plot gets a fixed width instead of the full column.",
+    checks: [
+      check("figure-too-tall", "warning", false, {
+        module: "src/reference/figure-fit.ts",
+        fn: "checkFigureFit"
+      })
+    ],
+    unchecked: "any page or viewport the course\u2019s Playwright suite does not open \u2014 the check runs in the browser, not in the build.",
+    settings: [
+      {
+        key: "maxPercent",
+        title: "Largest picture height (% of screen)",
+        description: "How much of the viewport height a figure\u2019s picture may take.",
+        schema: { type: "integer", minimum: 10, default: 80 }
+      }
+    ]
+  },
+  {
+    kind: "rule",
+    id: "V8",
+    short: "A diagram fits the lesson column",
+    title: "A diagram is no wider than the lesson column.",
+    elements: ["diagram"],
+    doc: "visualizations.md#v8",
+    summary: 'A `<Diagram>` lays out no wider than `columnWidth`, the lesson column at a 1366px-wide window, so the reader sees the whole graph without scrolling it. Narrow it with `direction="TB"`, a shorter label or a node `width` (its label wraps inside it); `warnAboveWidth={false}` marks a diagram meant to scroll.',
+    checks: [
+      check("dia-too-wide", "warning", false, {
+        module: "src/reference/diagram-fit.ts",
+        fn: "oversizedDiagrams"
+      })
+    ],
+    settings: [
+      {
+        key: "columnWidth",
+        title: "Column width (px)",
+        description: "The widest a diagram may lay out: the lesson column at the window width the course is read at most (707px at 1366px).",
+        schema: { type: "integer", minimum: 200, default: 707 }
+      }
+    ]
+  },
   // ---- C — versioning ---------------------------------------------------------
   {
     kind: "rule",
@@ -555,7 +652,7 @@ const RULES = [
     title: 'A table is a `<Table id="\u2026">`, never a raw Markdown or HTML table.',
     elements: ["table"],
     doc: "structure-rules.md#s3",
-    summary: 'Wrap every pipe table or `<table>` in `<Table id="\u2026" caption="\u2026">` so it gets a number and `[[tab-\u2026]]` can reach it.',
+    summary: 'Wrap every pipe table or `<table>` in `<Table id="\u2026" caption="\u2026">` so it gets a number and `[[tab-\u2026]]` can reach it; a table in a worked example stays plain.',
     checks: [
       check("raw-table-markdown", "warning", false, {
         module: "src/reference/raw-floats-validate.ts",
@@ -586,23 +683,6 @@ const RULES = [
       })
     ]
   },
-  {
-    kind: "rule",
-    id: "S5",
-    short: "A sign / perspective convention is declared once and cited elsewhere",
-    title: "A sign or perspective convention is declared once and cited everywhere else.",
-    elements: ["prose"],
-    doc: "structure-rules.md#s5",
-    summary: "Prose that states a sign / cash-flow-perspective convention resolves it to the single declaration \u2014 the `conventions.signConventionKey` notation entry (`[[key]]`) or the `conventions.cashFlowPerspectiveCompetency` competency \u2014 rather than restating it.",
-    checks: [
-      check(
-        "convention-single-definition",
-        "warning",
-        false,
-        consistency("checkConventionSingleDefinition")
-      )
-    ]
-  },
   {
     kind: "rule",
     id: "S6",
@@ -615,6 +695,12 @@ const RULES = [
       check("heading-skip", "error", true, {
         module: "src/reference/gate-heading-structure.ts",
         fn: "gateHeadingStructure"
+      }),
+      // A knowledge check or a worked-example set, which draws an `<h2>`,
+      // inside a memo or a short note.
+      check("heading-nested", "error", true, {
+        module: "src/reference/gate-heading-structure.ts",
+        fn: "gateHeadingStructure"
       })
     ]
   },
@@ -653,6 +739,30 @@ const RULES = [
     summary: 'Give each figure, table and diagram a `short` caption that names it: it opens the caption line in bold, and names the float in "Hidden here", a copied link and the "Figures and tables" page. The long `caption` goes on from that name to say what the float shows \u2014 its subject, its marks and symbols, the case shown \u2014 and at most the one thing to notice. The argument drawn from a figure is lesson text after it, and a lab\u2019s instructions are the first line of its `tools`.',
     checks: []
   },
+  {
+    kind: "rule",
+    id: "S10",
+    short: "A page that is not a chapter explains its symbols but numbers nothing: it links a chapter\u2019s float instead",
+    title: "A page that is not a chapter \u2014 the landing page, a part\u2019s overview page \u2014 explains its symbols like a chapter, but carries no numbered float: it links the chapter\u2019s float instead.",
+    elements: ["part-page", "plot", "table", "diagram", "equation", "notation"],
+    doc: "structure-rules.md#s10",
+    summary: "On `content/docs/index.mdx`, a `content/docs/<part>/index.mdx`, or any page outside a part: `[[key]]`, `\\explain`, math, citations and `[[chapter#tab-key]]` links work and open cards, and the math and prose gates apply. No `<Table>`, `<Figure>`, `<Diagram>`, `<CompactExamples>`, `<AssessmentSet>`, lab, `\\label{eq:\u2026}` or `notation.local`/`notation.suspend`; no `$\u2026$` or `[[\u2026]]` in `hero.title`, `hero.tagline` or a `<PartOverview chain>` step.",
+    checks: [
+      check("non-chapter-float", "error", true, {
+        module: "src/reference/gate-non-chapter-pages.ts",
+        fn: "gateNonChapterPages"
+      }),
+      check("non-chapter-local-notation", "error", false, {
+        module: "src/reference/gate-non-chapter-pages.ts",
+        fn: "gateNonChapterPages"
+      }),
+      check("non-chapter-plain-text", "error", false, {
+        module: "src/reference/gate-non-chapter-pages.ts",
+        fn: "gateNonChapterPages"
+      })
+    ],
+    locked: "a float needs a chapter number, and such a page has none \u2014 turning the rule off would not render one."
+  },
   // ---- P — prose --------------------------------------------------------------
   {
     kind: "rule",
@@ -787,6 +897,13 @@ const RETIRED = [
     date: "2026-09-26",
     into: "C3",
     why: "The release procedure and the invariant it keeps are one rule, and `knowledge-changelog-missing` (owned by C3) was already the check that fired on a half-finished release."
+  },
+  {
+    id: "S5",
+    title: "A sign or perspective convention is declared once and cited everywhere else.",
+    date: "2026-10-07",
+    into: "N4",
+    why: "Its check knew one finance course\u2019s phrasing and one key per course, and never fired in any course; the `conventions` setting it read is gone. A convention is a definition, so it is now N4\u2019s: defined once on its notation entry, whose `meaning` names the other choice and whose body says how to convert."
   }
 ];
 const INVARIANTS = [
@@ -796,7 +913,7 @@ const INVARIANTS = [
     title: "Notation keys are well-formed, unique, defined, and acyclic.",
     elements: ["notation", "math"],
     doc: "components.md#reference-systems",
-    summary: "A `[[key]]` or `\\explain{key}{\u2026}` names an existing entry; a key is kebab-case; a shared entry is defined once; formula references never form a cycle.",
+    summary: "A `[[key]]` or `\\explain{key}{\u2026}` names an existing entry; a key is kebab-case; a shared entry is defined once; references in meanings and bodies never form a cycle (formulas may name each other).",
     checks: [
       check("undefined-reference", "error", false, REGISTRY),
       check("invalid-key", "error", false, REGISTRY, GLYPHS),
@@ -811,7 +928,11 @@ const INVARIANTS = [
         fn: "reportUnknownScopeKeys"
       }),
       check("malformed-explicit-binding", "error", true, GLYPHS),
-      check("unused-definition", "info", false, REGISTRY)
+      check("unused-definition", "info", false, REGISTRY),
+      // A page-local entry under a shared key: two meanings for one key.
+      check("local-shadows-shared", "warning", false, REGISTRY),
+      // A `[[` that never closes, before the render fails on it.
+      check("malformed-reference", "error", false, REGISTRY)
     ]
   },
   {
@@ -830,7 +951,12 @@ const INVARIANTS = [
       check("ambiguous-span", "error", true, GLYPHS),
       check("ambiguous-base-fallback", "error", true, GLYPHS),
       check("ambiguous-canonical-notation", "error", false, GLYPHS),
-      check("math-compile-error", "error", true, GATE_MATH)
+      check("math-compile-error", "error", true, GATE_MATH),
+      // `$5 to $6`: money remark-math reads as one math span.
+      check("currency-dollar", "error", true, {
+        module: "src/reference/gate-math.ts",
+        fn: "gateContentMath"
+      })
     ]
   },
   {
@@ -848,7 +974,7 @@ const INVARIANTS = [
     title: "The course settings name real rules and current keys.",
     elements: ["changelog"],
     doc: "README.md#amending",
-    summary: "A `rules.<ID>` block names a live rule; a deprecated top-level key (`operators`, `romanLabels`, `abbreviations`) still works but warns until it is moved under `rules`.",
+    summary: "A `rules.<ID>` block names a live rule; a deprecated top-level key (`operators`, `romanLabels`, `abbreviations`) still works but warns until it is moved under `rules`; `conventions` is ignored and warns until it is deleted.",
     checks: [
       check("config-deprecated-key", "warning", false, {
         module: "src/rules/settings.ts",
@@ -892,8 +1018,10 @@ const INVARIANTS = [
         "track-order",
         "assessment-coverage",
         "invalid-assessment",
-        "review-state",
-        "teaches-support"
+        "missing-assumptions",
+        "teaches-support",
+        // `[text [@id]](url)`: a citation the page prints as typed.
+        "citation-in-link"
       ].map(
         (code) => check(code, "error", false, {
           module: "src/curriculum/validation.ts",
@@ -904,14 +1032,77 @@ const INVARIANTS = [
         "alignment-unknown-competency",
         "alignment-unknown-lesson",
         "alignment-introduction",
-        "alignment-unavailable",
-        "alignment-review-state"
+        "alignment-unavailable"
       ].map(
         (code) => check(code, "error", false, {
           module: "src/reference/curriculum-alignment.ts",
           fn: "validateNotationAlignment"
         })
-      )
+      ),
+      // A course's parts and the lessons in them (`compileManifest`): a
+      // lesson in a directory no part lists, and a part with nothing in it yet.
+      check("lesson-outside-parts", "error", false, {
+        module: "src/compiler/manifest.ts",
+        fn: "compileManifest"
+      }),
+      check("part-empty", "warning", false, {
+        module: "src/compiler/manifest.ts",
+        fn: "compileManifest"
+      })
+    ]
+  },
+  {
+    kind: "invariant",
+    id: "content-schema",
+    title: "Every content file satisfies its collection\u2019s schema.",
+    elements: ["notation", "assessment", "source", "changelog"],
+    doc: "structure.md#content-schemas",
+    summary: "A page\u2019s explico fields, a notation entry, an abbreviation, a competency, an assessment, a source and a track match the schema `astro build` loads them with (`compiler/content-schemas.ts`); `validate:content` reports the field and its line.",
+    checks: [
+      check("content-schema", "error", false, {
+        module: "src/compiler/content-schema.ts",
+        fn: "validateContentSchemas"
+      })
+    ]
+  },
+  {
+    kind: "invariant",
+    id: "retired-keys",
+    title: "No content file sets a key the engine has retired or cannot honour.",
+    elements: ["changelog"],
+    doc: "structure.md#retired-keys",
+    summary: "A frontmatter or JSON key explico no longer reads (`editorialStatus`) fails the build at every file that still sets it; delete the line. A lesson\u2019s `draft: true` fails it too (the sidebar would name a page the build drops), and its `sidebar.order` warns (chapters follow the tracks).",
+    checks: [
+      check("retired-key", "error", false, {
+        module: "src/reference/gate-retired-keys.ts",
+        fn: "findRetiredKeys"
+      }),
+      check("unsupported-key", "error", false, {
+        module: "src/reference/gate-retired-keys.ts",
+        fn: "findUnsupportedKeys"
+      }),
+      check("ignored-key", "warning", false, {
+        module: "src/reference/gate-retired-keys.ts",
+        fn: "findUnsupportedKeys"
+      })
+    ]
+  },
+  {
+    kind: "invariant",
+    id: "prop-text",
+    title: "A component\u2019s quoted prop holds plain text, and prose holds no `{\u2026}` expression.",
+    elements: ["math", "plot", "diagram", "table"],
+    doc: "components.md#props-are-plain-text",
+    summary: 'A quoted prop (`caption="\u2026"`, `short="\u2026"`, `title="\u2026"`, `label="\u2026"`) reaches the page as plain text: no KaTeX, reference or citation runs in it. `$\u2026$`, `[[\u2026]]` or `[@\u2026]` in one fails the build, since it would print as typed; write the symbol in Unicode or words, and reference or cite from the prose next to the component. MDX reads `{\u2026}` in prose as JavaScript (`{a}` fails the build, "a is not defined"): write `\\{a\\}`, or `$\\{a\\}$` for a set.',
+    checks: [
+      check("markup-in-prop", "error", false, {
+        module: "src/reference/gate-prop-text.ts",
+        fn: "findMarkupInProps"
+      }),
+      check("mdx-expression", "error", false, {
+        module: "src/reference/gate-mdx-expression.ts",
+        fn: "gateMdxExpressions"
+      })
     ]
   }
 ];

package/dist/rules/in-effect.d.ts

@@ -1,5 +1,5 @@
 import { Element, Enforcement } from './catalog.js';
-import { M as ManifestRules } from '../course-config-Dsnri9Tk.js';
+import { M as ManifestRules } from '../course-config-rRtME5UV.js';
 import './course-rules.js';
 
 /** The slice of a manifest the page needs. */