explico 0.6.0 → 0.8.0

package/docs/authoring/notation.md

@@ -837,14 +837,16 @@ change to that file.
 ## N15
 
 **A nested visible delimiter — `(`, `[`, `\{`, or `|` inside another one of
-them — must use its `\left`/`\right` sizing form, not the bare character.**
+them — must use the scalable `\left`/`\right` form, not the bare
+character.**
 
 `(`, `[`, `\{` (an escaped, visible brace — bare `{`/`}` is invisible LaTeX
 grouping and out of scope here), and `|` may be written bare only when they
 are not nested — not inside one another, and not inside a second instance of
 themselves. The moment one of them sits inside another, **every level of that
-nest** switches to the auto-sizing form: `\left(`/`\right)`, `\left[`/`\right]`,
-`\left\{`/`\right\}`, `\left|`/`\right|`.
+nest** uses the auto-sizing form (`\left(`/`\right)`, `\left[`/`\right]`,
+`\left\{`/`\right\}`, `\left|`/`\right|`) — and, per [N17](#n17), only
+that form.
 
 ```text
 \sin(2(90\text{°}-\theta))                          ✗ two bare ( nested
@@ -873,10 +875,10 @@ author on a case that can render invisibly wrong.
 _How to apply._
 
 - Reach for `\left(`/`\right)` (or the bracket/brace/pipe equivalents) the
-  moment a second one of these four glyphs would end up inside the first —
-  regardless of which of the four it is, and regardless of whether the outer
-  one is already sized. Sizing the outer pair does not exempt an inner bare
-  one; both levels of a two-level nest need their own `\left`/`\right`.
+  moment a second one of these four glyphs would end up inside the first.
+  Sizing the outer pair does not exempt an inner bare one; both levels of a
+  two-level nest need a sizing command. [N17](#n17) then leaves every size to
+  the engine.
 - Mixing types counts as nesting too: `(a + [b])`, `\{a \mid (b)\}`, and
   `(|a|)` all need every level sized, exactly like nesting the same character
   twice.
@@ -909,3 +911,151 @@ _Exceptions._ None. A quoted source nesting bare delimiters still renders
 sized in this course, the same way N13 reparenthesizes a quoted `\sin x` —
 the sizing is a typesetting choice, not a claim about the source's own
 notation.
+
+---
+
+## N16
+
+**In AI-generated mathematical content, alternate delimiter types for nested
+grouping when their shape is stylistic; preserve every conventional or
+semantic delimiter shape.**
+
+For a nest whose delimiters do nothing except group an expression, prefer this
+cycle from the inside out:
+
+1. `( ... )`
+2. `[ ... ]`
+3. `\{ ... \}`
+4. repeat the cycle if another grouping level is genuinely necessary.
+
+This is a preference for generated notation, not a mechanical rewrite. Do not
+change or alternate a delimiter whose type is part of the mathematical
+notation. Preserve, among other conventional forms:
+
+- function application such as `f(x)`;
+- expectation notation such as `\mathbb{E}[X]`;
+- intervals such as `[a,b]` and `(a,b]`;
+- sets and set-builder notation;
+- tuples and coordinates;
+- commutators and probability notation;
+- matrices, vectors, indexing, norms, and absolute values.
+
+When there is doubt about whether the delimiter is semantic, keep the
+conventional notation. Do not alternate merely to complete the cycle.
+
+_Rationale._ Repeating the same shape at every purely stylistic grouping level
+makes the boundaries harder to scan. Alternation can expose the grouping
+structure, but only mathematical context can distinguish a disposable grouping
+mark from notation whose shape carries meaning. That judgment belongs to the
+authoring agent or reviewer, not a syntax linter.
+
+_How to apply._ Decide whether each pair is stylistic before choosing its
+shape. Alternate only the pairs that pass that test. Sizes are not your
+concern: [N17](#n17) hands every nested pair to the engine, which grows each
+level automatically. Shape is an authoring decision; size is not.
+
+```text
+\left[
+  a+
+  \left(
+    b+
+    \left[
+      c+
+      \left(d+e\right)
+    \right]
+  \right)
+\right]                                                   ✓
+```
+
+Semantic notation stays intact even when stylistic grouping surrounds it:
+
+```text
+\left[
+  \mathbb{E}\!\left[
+    f\!\left(X\right)
+  \right]
+  +
+  \left(
+    a+b
+  \right)
+\right]                                                   ✓
+```
+
+In particular, never turn `\mathbb{E}[X]` into another delimiter type merely
+to alternate shapes.
+
+_Enforcement._ Review-only. Delimiter semantics cannot be inferred reliably
+from LaTeX syntax, so no automated check enforces alternation. The N17 linter
+checks sizing syntax only and never recommends changing a delimiter type.
+
+_Exceptions._ Every conventional or semantically meaningful delimiter is
+outside the alternation preference. Preserving established mathematical
+notation takes precedence over the stylistic cycle.
+
+---
+
+## N17
+
+**A nest of scalable `()`, `[]`, or `\{\}` delimiters is sized by the engine:
+use `\left ... \right` at every level, and never hand-size a pair inside a nest
+with `\bigl`, `\Bigl`, `\biggl`, or `\Biggl`.**
+
+```text
+\left[a+\left(b+\left[c+\left(d+e\right)\right]\right)\right]     ✓
+\Biggl[a+\biggl(b+\Bigl[c+\left(d+e\right)\Bigr]\biggr)\Biggr]    ✗ hand-sized
+```
+
+_Rationale._ In stock TeX and stock KaTeX a `\left ... \right` pair is allowed
+to fall up to `\delimitershortfall` (5pt) short of its content, so two pairs at
+different depths around similar content round to the *same* glyph and the
+nesting disappears. The historical repair was to hand-pick a larger size at
+each level, which trades one defect for another: `\bigl`–`\Biggl` are
+*fixed* glyphs, so they stop tracking the content they wrap, they run out after
+four levels, and an edit to the inner expression silently invalidates every
+size above it.
+
+This engine removes the cause instead. `src/reference/katex-delimiters.mjs`
+installs a KaTeX whose `\delimitershortfall` is `-1pt` — the same one-constant
+change an author would make in a LaTeX preamble — see
+[`docs/katex-bracket-scaling.md`](../katex-bracket-scaling.md) for the
+derivation. A pair is then always *strictly* taller than what it wraps, so each
+enclosing level grows on its own, by exactly as much as its content needs, at
+any depth. Hand-sizing is no longer a repair; it is an override that throws the
+automatic hierarchy away.
+
+_How to apply._
+
+- Write `\left ... \right` at every level of a nest and leave the sizes alone.
+  With the patched engine there is nothing further to do.
+- Do not "help" the engine with a manual size. If a nest still looks wrong,
+  the expression is too deep to read — restructure it, or pull an inner group
+  into its own display, rather than hand-sizing it.
+- This rule is independent of [N16](#n16): shapes still alternate where they
+  are stylistic, and semantic shapes are still preserved. Only the *size*
+  decision moved to the engine.
+- A *lone* hand-sized pair that is not part of a nest is untouched — a tuple
+  written `\bigl(x(t),\ y(t)\bigr)` has no hierarchy to get wrong and stays a
+  deliberate typographic choice.
+- Nothing to install. The sizing rides along with the engine: a course's
+  `astro.config.mjs` already imports `explico/reference/katex-options.mjs`,
+  which installs it before anything renders. If it ever fails to install, the
+  build stops with an explicit error rather than quietly falling back to stock
+  KaTeX.
+
+_Enforcement._ Tier-3 warning `delimiter-manual-size`, emitted by
+`lintDelimiterSizes` (`src/reference/delimiter-size.ts`) through the normal
+math gate for lesson math, notation formulas, and assessment math. The linter
+uses a stack to parse arbitrarily deep `\left...\right`, `\bigl...\bigr`,
+`\Bigl...\Bigr`, `\biggl...\biggr`, and `\Biggl...\Biggr` pairs for `()`, `[]`,
+and `\{\}`, and warns for each hand-sized pair that contains, or sits inside,
+another pair it tracks. It reports that pair's source line and column and
+suggests the `\left`/`\right` replacement, repeating the exact opening and
+closing delimiter shapes it found. Malformed pairs remain KaTeX syntax errors;
+the linter does not guess at their structure.
+
+The automated check deliberately does **not** infer mathematical semantics or
+lint delimiter-type alternation.
+
+_Exceptions._ None inside a nest. Bare, non-nested semantic notation such as
+`f(x)` or `\mathbb{E}[X]` is outside this linter and remains governed by the
+mathematical convention and [N15](#n15)'s separate bare-nesting rule.

package/docs/authoring/prose.md

@@ -0,0 +1,64 @@
+# Prose rules
+
+`P` rules govern how a lesson's sentences are worded — choices a reader
+meets in running text rather than in a symbol, a figure, or a heading.
+
+See [README.md](README.md) for what "strong recommendation", "Build-enforced",
+and "Review-only" mean here, and how to amend a rule.
+
+---
+
+## P1
+
+**Never use "or" to give a thing a second name.**
+
+When a sentence introduces an alternative name, synonym, or equivalent
+expression for something, do not join the two with "or". Use "i.e.,", "also
+called", "also known as", or parentheses, whichever fits the sentence.
+
+```md
+<!-- "or" reads as a choice between two different things. -->
+
+The residual or error term is what the model leaves unexplained.
+Fit the model by ordinary least squares or OLS.
+
+<!-- Each names one thing, and says so. -->
+
+The residual (also called the error term) is what the model leaves unexplained.
+Fit the model by ordinary least squares (OLS).
+```
+
+_Rationale._ "Or" has two jobs in English: it separates alternatives ("a
+sample or a population"), and it introduces a second name for the same thing.
+Nothing in the sentence says which job it is doing, so a reader can take "the
+residual or error term" as two different quantities to choose between. In a
+statistics course that misreading is expensive, because many pairs that look
+like synonyms are not ("variance or standard deviation", "estimate or
+estimator"). A reader who takes a real distinction for a synonym, or the
+reverse, learns the wrong thing without noticing.
+
+_How to apply._ Decide whether the two expressions name the same thing or
+different things.
+
+- **Same thing** — rewrite with one of:
+  - _i.e.,_ when the second expression restates or defines the first: "the
+    estimator is unbiased, i.e., its expected value equals the parameter".
+  - _also called_ / _also known as_ when it is a second name in use: "the
+    coefficient of determination, also known as $R^2$".
+  - _parentheses_ when the second name is short and the sentence carries
+    on: "the mean squared error (MSE)".
+- **Different things** — "or" is correct, and stays. If the sentence could
+  still be read as a synonym, name the choice: "either a sample or a
+  population", "whether the variance or the standard deviation is reported".
+
+An abbreviation introduced in parentheses is still subject to
+[N14](notation.md#n14): it has to be catalogued or explained.
+
+_Enforcement._ Review-only. Whether "or" is a logical alternative or a
+second name depends on what the sentence means, so no gate can decide it; a
+reviewer does. An automated "or" scan would flag every legitimate
+alternative.
+
+_Exceptions._ A quotation, a source title, or a code identifier that contains
+"or" is left as written. So is "or" inside an assessment answer choice that
+really offers alternatives.

package/docs/katex-bracket-scaling.md

@@ -0,0 +1,191 @@
+# Auto-scaling brackets in KaTeX (and MathJax)
+
+> **Status in this repo.** Solution 2 is implemented, but as *code* rather than
+> as a `patches/` file: [`src/reference/katex-delimiters.mjs`](../src/reference/katex-delimiters.mjs)
+> applies the same one-constant change at import time, so it ships inside the
+> published `explico` package and a downstream course inherits it with no
+> install step. Rule [N17](authoring/notation.md#n17) depends on it. The
+> sections below are the derivation; see
+> [How this repo applies it](#how-this-repo-applies-it).
+
+## The problem
+
+In LaTeX, `\left[ ... \right]` sizes a bracket to fit its content — but nested brackets often come out **the same size**, because the sizing rule only requires the delimiter to be *close enough* to the content's height, not strictly bigger.
+
+Example:
+
+```latex
+$$\left[ \left[ \sqrt{\frac{\int\limits_0^{10}\sqrt{a^2+b^2}}{2}} \right] + 1 \right]$$
+```
+
+The outer `[` and inner `[` render at the same size, even though the outer one wraps strictly more content. The alternative — manually choosing `\bigl`, `\Bigl`, `\biggl`, `\Biggl` — fixes the sizing but abandons `\left`/`\right`'s automatic "match the height of everything inside" behavior, since those are fixed-size delimiters that don't adapt to content.
+
+So there are two properties you want simultaneously, and the two standard tools each give you only one:
+
+1. **Strict growth outward** — each nesting level's bracket must be visibly bigger than the one inside it.
+2. **Full coverage** — every bracket must span the full height of its content, with no gap.
+
+`\bigl`/`\Bigl`/`\biggl`/`\Biggl` give you (1) but not (2) (fixed sizes don't track arbitrary content). `\left`/`\right` give you (2) but not (1) (the sizing rule allows equal-looking sizes at different nesting depths).
+
+## Why it happens: the underlying rule
+
+TeX sizes a `\left`/`\right` pair using this rule (TeXbook, Appendix G, rule 19):
+
+```
+s_min = max( 2·δ₀ · f / 1000 , 2·δ₀ − l )
+```
+
+TeX then picks the smallest available delimiter glyph whose total size `s` satisfies `s ≥ s_min`.
+
+| Symbol | Meaning |
+|---|---|
+| `h` | height of the content: how far it reaches above the baseline |
+| `d` | depth of the content: how far it reaches below the baseline |
+| `a` | axis height — the line fraction bars and minus signs sit on; delimiters are centered on this line |
+| `δ₀` | `max(h − a, d + a)` — how far the content reaches from the axis, on whichever side is farther |
+| `f` | `\delimiterfactor`, default **901** |
+| `l` | `\delimitershortfall`, default **5pt** |
+| `s_min` | the smallest total bracket size TeX will accept |
+| `s` | the size of the delimiter TeX actually picks |
+
+With the default `l = 5pt`, `s_min` can be *smaller* than the content's own height (since `901/1000 ≈ 0.9`), so a delimiter that already matches the inner bracket's height passes the test for the outer bracket too — no forced growth. The same slack also means a delimiter can legally fall up to 5pt short of the content, i.e. requirement (2) isn't fully guaranteed by default either.
+
+**The fix in real LaTeX:** set `\delimitershortfall` to a *negative* value (e.g. `-1pt`). Then `s_min = 2δ₀ + 1pt`, which is always larger than the content's own extent — forcing outward growth at every level, automatically, with no per-formula work. This is a document-wide setting, not something you write per equation:
+
+```latex
+\delimitershortfall=-1pt
+\left[ \left[ \sqrt{\frac{\int\limits_0^{10}\sqrt{a^2+b^2}}{2}} \right] + 1 \right]
+```
+
+Verified by rendering with `pdflatex`: default nesting produces equal-sized brackets; the same source with `\delimitershortfall=-1pt` produces strictly increasing sizes at every depth, and small content (`(x)`, `((x))`, `(((x)))`) is unaffected since the correction is tiny relative to normal delimiter jumps.
+
+## Why it doesn't carry over to the web
+
+`\delimitershortfall` is a TeX engine primitive. **Neither KaTeX nor MathJax expose it or honor it** — I tested both directly:
+
+- KaTeX: `\delimitershortfall=-1pt` throws `ParseError: Expected group after '\delimitershortfall'` (undefined control sequence).
+- MathJax v3: the command is silently dropped/renders as an error span; no effect on sizing.
+
+So the web renderers need a different fix.
+
+## Solution 1: a `\grow` macro (portable, works in *any* KaTeX/MathJax page)
+
+Since neither engine's *rule* can be changed from user-level TeX, the workaround changes the **content** being measured instead. Wrap everything inside a bracket pair (except the innermost level) in an invisible padding macro that makes the content measure as slightly taller and deeper than it visually is. Then the normal `\left`/`\right` sizing — which *does* work correctly in both engines — is forced to pick a bigger glyph at each level, because the content it measures really is bigger.
+
+**Mechanism:** for content `#1`, stack a raised zero-width phantom copy 0.5em above it and a lowered zero-width phantom copy 0.5em below it. `\vphantom{#1}` takes zero horizontal space and is invisible, but claims the same height/depth as `#1`. Raising and lowering copies of it extends the *measured* bounding box by 0.5em on each side — 1em of forced growth per wrap — without changing what's visually drawn.
+
+**KaTeX** (verified — `\raisebox` only accepts a text-mode argument, so the phantom must be re-entered as math and forced to `\displaystyle`; without that it silently shrinks to inline size and the trick does nothing):
+
+```latex
+\newcommand{\grow}[1]{#1\raisebox{0.5em}{$\displaystyle\vphantom{#1}$}\raisebox{-0.5em}{$\displaystyle\vphantom{#1}$}}
+```
+
+**MathJax** (verified — `\raisebox` doesn't exist here; plain-TeX `\raise`/`\lower` take a math argument directly and preserve the current style):
+
+```latex
+\newcommand{\grow}[1]{#1\raise{0.5em}{\vphantom{#1}}\lower{0.5em}{\vphantom{#1}}}
+```
+
+**Usage** — wrap the content of every bracket pair except the innermost:
+
+```latex
+\left[ \grow{ \left[ \sqrt{\frac{\int\limits_0^{10}\sqrt{a^2+b^2}}{2}} \right] + 1 } \right]
+```
+
+Verified by rendering with real KaTeX 0.18.7 and MathJax 3.2.2 (headless Chromium screenshots): both show strictly increasing bracket sizes across 2–3 nesting levels, matching the pdfLaTeX reference.
+
+**Trade-offs:**
+- Manual — you place `\grow{}` yourself at each level; it isn't automatic like the LaTeX-engine setting.
+- The two spellings aren't interchangeable: `\raisebox` errors out in MathJax, `\raise`/`\lower` don't exist in KaTeX. Pick the one matching your renderer.
+- Can be defined once (in MathJax's `tex.macros` config, or KaTeX's `macros` render option) so you only write `\grow{...}` per formula, not the full definition each time.
+
+## Solution 2: patch KaTeX directly (better fit for a site you build/host yourself)
+
+Since you control the build (an Astro site rendering KaTeX server-side), you don't need the macro workaround at all — you can restore the actual `\delimitershortfall` behavior by editing the one place KaTeX hard-codes it.
+
+**The code.** KaTeX's delimiter-sizing function (`makeLeftRightDelim`, in the compiled bundle since no per-file TS source ships in the npm package) contains:
+
+```js
+const delimiterFactor = 901;                                   // TeX's \delimiterfactor
+const delimiterExtend = 5.0 / options.fontMetrics().ptPerEm;   // TeX's \delimitershortfall = 5pt
+```
+
+This is the exact same formula from the TeXbook rule above, with the same two constants. Changing `5.0` to `-1.0` is precisely `\delimitershortfall=-1pt` — `delimiterFactor` doesn't need to change, since a negative shortfall always makes the second term of the `max(...)` dominate anyway.
+
+**Verified:** I applied this one-line edit to the installed `katex` package and rendered plain, unmodified `\left[...\right]` source (no `\grow` macro anywhere) through the patched build. Result: strict growth across 4 nesting levels, small content (`(x)`, `((x))`, `(((x)))`) unaffected, and — critically — the LaTeX source embedded in KaTeX's output for copy/paste (`<annotation encoding="application/x-tex">`) stays exactly what you typed, since only the *sizing*, not the *content*, is touched.
+
+**Where the line lives** (npm package, KaTeX 0.16.47):
+
+| File | Used by | Patched here |
+|---|---|---|
+| `src/delimiter.ts` | the readable source the bundles are built from | yes |
+| `dist/katex.mjs` | ESM import — what an Astro/Vite build resolves to | yes |
+| `dist/katex.js` | CJS `require` | yes |
+| `dist/katex.min.js` | only if KaTeX is also loaded client-side via `<script>` | **no** — see below |
+
+`dist/katex.min.js` is left alone on purpose. explico renders every formula at
+build time and ships only `katex.min.css` plus fonts to the browser, so nothing
+here loads that bundle — and because it is a single ~270 KB line, including it
+turns a 2 KB patch into a 550 KB one that no reviewer can read and no KaTeX
+upgrade can rebase. A course that *does* render KaTeX in the browser has to
+patch it too; the minified form of the same line is
+`l=5/n.fontMetrics().ptPerEm` inside `makeLeftRightDelim`.
+
+## How this repo applies it
+
+A `pnpm patch` would work, and is what the section above describes, but it is
+**project-local**: pnpm records it in the consuming repo's
+`pnpm-workspace.yaml`, so it cannot travel inside the published `explico`
+package. Every downstream course would have to reapply it, and a course that
+forgot would render flat nests while its linter told authors the engine handled
+sizing. Documenting that in a migration guide only narrows the window for the
+mistake; it does not close it.
+
+So the engine does the same edit in code, at import time, in
+[`src/reference/katex-delimiters.mjs`](../src/reference/katex-delimiters.mjs):
+
+1. read KaTeX's own ESM bundle off disk (`katex/dist/katex.mjs`);
+2. rewrite that one constant, throwing if it is not found verbatim;
+3. `import()` the rewritten source as a `data:` URL — the bundle has no imports
+   of its own, so it needs no base to resolve against;
+4. move `render`, `renderToString`, `__renderToDomTree` and
+   `__renderToHTMLTree` onto the shared `katex` object every consumer in the
+   process already imported;
+5. render a known nest and throw unless the sizes actually grew.
+
+Step 4 is what makes it reach lesson-body math. `rehype-katex` does its own
+`import katex from 'katex'`, but it calls `katex.renderToString(...)` — a
+property read at call time — and KaTeX's default export is a plain mutable
+object. Replacing the function on that object is therefore enough; the plugin
+does not have to be forked or aliased.
+
+**A course inherits this with no changes.** `astro.config.mjs` already imports
+`createNotationKatexOptions` from `explico/reference/katex-options.mjs`, and
+that module imports the installer for its side effect, so the sizing is in
+place before Astro renders anything. The engine's own non-Astro paths
+(`math-glyphs.mjs`, `render-lab-math.ts`, and therefore `validate:content`)
+import it directly.
+
+**It cannot fail quietly.** Steps 2 and 5 throw. A KaTeX upgrade that moves the
+constant, or anything that renders before the installer runs, stops the build
+with an explicit message instead of silently reverting to stock spacing — which
+is the failure mode a patch file plus a migration note could not rule out.
+
+**Trade-offs.** It is a monkey-patch of a third-party module object, so it
+rests on three upstream properties: the constant is a literal in the shipped
+bundle, the bundle is self-contained, and the default export is mutable. All
+three are asserted at install time rather than assumed. It also holds a second
+copy of the KaTeX module in memory (~600 KB of source, ~50 ms to load) for the
+duration of a build, which is not worth optimising away.
+
+## Why the patch is the better fit here
+
+Your original idea — keep writing `\left[` everywhere, run a build-time preprocessing step that inserts `\grow{}` at each nesting level, then swap in the original source for a "copy" button — would work, but has two costs the patch avoids:
+
+1. **The preprocessor needs a real TeX parser**, not a regex. It has to track bracket nesting depth correctly across `\text{...}`, comments, `\right.` (null right delimiters), and — critically — macros. If you ever define something like `\norm{...}` that *expands* to `\left\lVert...\right\rVert`, a source-level preprocessor can't see the nesting hidden inside the macro and will miscount levels. The patch operates after macro expansion, inside KaTeX's own layout engine, so it can't miss anything.
+2. **The copy-button problem disappears.** KaTeX already embeds your literal input in the hidden MathML `<annotation>` tag — that's what the standard `copy-tex` extension reads. With preprocessing, that annotation would contain the `\grow`-polluted string, so you'd have to intercept the copy handler and substitute the original text yourself. With the patch, the *displayed* math and the *embedded source* never diverge in the first place, because nothing was ever inserted into the source.
+
+## Caveats
+
+- If your pipeline actually renders to **SVG** rather than HTML+CSS, you're using MathJax's `tex-svg` output, not KaTeX (KaTeX renders to HTML spans, not SVG). MathJax's stretchy-delimiter logic lives in the output stage rather than one constants block, so the equivalent patch would be far more invasive there — the `\grow` macro is the practical option for MathJax.
+- On an Astro build, KaTeX runs at build time (via `remark-math`/`rehype-katex` or similar) and only sends finished HTML + `katex.css` + fonts to the browser — the patched JS never ships to visitors, it only needs to be present in your build environment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Build-time engine for prerequisite-aware, notation-rigorous course content: one validated content model, a semantic notation/citation/equation system with a completeness gate, and a deterministic JSON manifest.",
   "type": "module",
   "license": "UNLICENSED",
@@ -30,6 +30,7 @@
     "README.md",
     "CHANGELOG.md",
     "docs/VERSIONING.md",
+    "docs/katex-bracket-scaling.md",
     "docs/authoring"
   ],
   "dependencies": {

package/src/compiler/astro.ts

@@ -13,6 +13,9 @@ import {
 } from './manifest';
 import { missingNotationPayloadKeys } from '../reference/page-notation';
 import { writeStandaloneLessonExports } from './exports/standalone-html';
+import remarkAbbreviations from '../reference/remark-abbreviations.mjs';
+import remarkCitation from '../reference/remark-citation.mjs';
+import remarkNotation from '../reference/remark-notation.mjs';
 
 // Vite keeps its server object across a restart. Do not accumulate watcher
 // callbacks each time Astro reloads its configuration.
@@ -132,6 +135,91 @@ export function assertNotationPayloadHtml(page: string, html: string): void {
   );
 }
 
+type MarkdownConfig = AstroConfig['markdown'];
+
+/**
+ * Every configured remark plugin, regardless of which of Astro's two
+ * mutually-exclusive wiring surfaces a course uses: the deprecated flat
+ * `markdown.remarkPlugins` array, or a `markdown.processor` (e.g.
+ * `unified({ remarkPlugins })`) whose own `options.remarkPlugins` a
+ * non-`unified` processor (e.g. `satteri()`) may not have at all.
+ */
+function configuredRemarkPlugins(markdown: MarkdownConfig): readonly unknown[] {
+  const direct = markdown?.remarkPlugins ?? [];
+  const processorOptions = markdown?.processor?.options as
+    | { remarkPlugins?: unknown[] }
+    | undefined;
+  return [...direct, ...(processorOptions?.remarkPlugins ?? [])];
+}
+
+function remarkPluginIsWired(remarkPlugins: readonly unknown[], plugin: unknown): boolean {
+  return remarkPlugins.some(
+    (entry) => entry === plugin || (Array.isArray(entry) && entry[0] === plugin),
+  );
+}
+
+/**
+ * Fail the build when a manifest-driven remark plugin has catalogued content
+ * but was never registered in Astro's markdown config — the "half-migrated"
+ * failure mode `docs/authoring/migrating.md` documents but, until now, never
+ * checked: `pnpm validate:content` stays green because the content-side gate
+ * (e.g. `gate-abbreviations.ts`'s N14 check) only scans prose, not Astro
+ * config, so a skipped plugin registration renders every trigger as plain
+ * text with no signal anywhere.
+ */
+export function assertRemarkPluginsWired(
+  manifest: Pick<Manifest, 'abbreviations' | 'sources' | 'notation'>,
+  markdown: MarkdownConfig,
+): void {
+  const remarkPlugins = configuredRemarkPlugins(markdown);
+  const missing: string[] = [];
+
+  if (
+    manifest.abbreviations.length > 0 &&
+    !remarkPluginIsWired(remarkPlugins, remarkAbbreviations)
+  ) {
+    missing.push(
+      `remarkAbbreviations is missing from markdown.remarkPlugins, but ` +
+        `manifest.abbreviations has ${manifest.abbreviations.length} ` +
+        `entr${manifest.abbreviations.length === 1 ? 'y' : 'ies'}. Import it from ` +
+        `'explico/reference/remark-abbreviations.mjs' and add ` +
+        `[remarkAbbreviations, { abbreviations: manifest.abbreviations }] to ` +
+        `markdown.remarkPlugins — see docs/authoring/migrating.md#4-rule-n14.`,
+    );
+  }
+
+  if (manifest.sources.length > 0 && !remarkPluginIsWired(remarkPlugins, remarkCitation)) {
+    missing.push(
+      `remarkCitation is missing from markdown.remarkPlugins, but ` +
+        `manifest.sources has ${manifest.sources.length} ` +
+        `entr${manifest.sources.length === 1 ? 'y' : 'ies'}. Import it from ` +
+        `'explico/reference/remark-citation.mjs' and add ` +
+        `[remarkCitation, { sources: manifest.sources }] to markdown.remarkPlugins.`,
+    );
+  }
+
+  if (
+    manifest.notation.raw.length > 0 &&
+    !remarkPluginIsWired(remarkPlugins, remarkNotation)
+  ) {
+    missing.push(
+      `remarkNotation is missing from markdown.remarkPlugins, but ` +
+        `manifest.notation.raw has ${manifest.notation.raw.length} ` +
+        `entr${manifest.notation.raw.length === 1 ? 'y' : 'ies'}. Import it from ` +
+        `'explico/reference/remark-notation.mjs' and add ` +
+        `[remarkNotation, createRemarkNotationOptions(manifest)] to markdown.remarkPlugins.`,
+    );
+  }
+
+  if (missing.length === 0) return;
+  throw new Error(
+    `Explico manifest-driven remark plugin${missing.length === 1 ? ' is' : 's are'} ` +
+      `not wired into Astro's markdown config:\n${missing
+        .map((line) => `  - ${line}`)
+        .join('\n')}`,
+  );
+}
+
 async function validateGeneratedNotationPayloads(directory: URL): Promise<void> {
   const root = fileURLToPath(directory);
   const walk = async (path: string): Promise<void> => {
@@ -200,6 +288,7 @@ export function explicoContentRefresh(
     name: 'explico-content-refresh',
     hooks: {
       'astro:config:setup': ({ command, config }) => {
+        assertRemarkPluginsWired(manifest, config.markdown);
         if (command === 'dev') {
           developmentConfig = { root: config.root, base: config.base };
         }