explico 0.6.0 → 0.7.0

package/docs/authoring/migrating.md

@@ -33,6 +33,282 @@ required config block throws with the section of this file to read.
 
 ---
 
+## 0.6.0 → 0.7.0
+
+### 1. Manifest schema is now v15: diagnostic severity has three levels
+
+`MANIFEST_SCHEMA_VERSION` is 15 (v14 → v15). Public diagnostic severity unions
+now include `info`, so a client that treated "not an error" as "a warning"
+needs three edits:
+
+1. A client asserting `MANIFEST_SCHEMA_VERSION` by exact equality expects 15.
+2. Widen any hand-written `'error' | 'warning'` type over manifest diagnostics
+   to `'error' | 'warning' | 'info'`. `ConsistencyDiagnostic.severity` is now
+   `'warning' | 'info'`.
+3. In `scripts/compile-manifest.ts` (and any other consumer), filter on
+   `severity === 'warning'` before printing or counting warnings. A script that
+   counts all of `manifest.diagnostics.consistency` as "Tier-3 findings" now
+   over-reports:
+
+```diff
+-const consistencyByCode = consistencyCounts(consistency);
+-const consistencyTotal = consistency.length;
++const consistencyWarnings = consistency.filter(
++  (diagnostic) => diagnostic.severity === 'warning',
++);
++const consistencyByCode = consistencyCounts(consistencyWarnings);
++const consistencyTotal = consistencyWarnings.length;
+```
+
+These codes moved from `warning` to `info`: `eq-key-unused`, every keyed-float
+`*-key-unused`, `unused-definition`, `weak-local`, `gloss-wants-promoting`, and
+`card-wants-demoting`. Their code strings and container fields did not change,
+the `lint-ignore.yml` lines that already worked for `weak-local`,
+`gloss-wants-promoting`, and `card-wants-demoting` still match, and nothing
+blocks the build. They no longer appear in `pnpm content warnings`; read them
+with `pnpm content diagnostics info`.
+
+Run `pnpm validate:content` twice. The committed `build/resolution/*` files
+(including `consistency-report.json`) change because those findings now carry
+`info` severity and `numerals-tagged` findings are gone (item 2); commit them.
+
+### 2. Retired diagnostic: `numerals-tagged`
+
+`ConsistencyCode` no longer contains `numerals-tagged`, and the engine never
+emits it. Delete every `numerals-tagged` line from `lint-ignore.yml` (a stale
+line is inert but misleads the next reader) and every course script, test, or
+type narrowing that names the code — `tsc`/`astro check` flags the latter as a
+comparison against a non-member of the union.
+
+### 3. `explicoContentRefresh()` fails the build on a missing remark plugin (rule N14 and its siblings)
+
+This is the enforcement half of rule N14's Astro wiring (see item 4 of the
+0.4.x → 0.5.0 section). Its `astro:config:setup` hook now compares the manifest
+against the configured remark plugins and throws, naming each gap, when a
+non-empty table has no matching plugin registered:
+
+| Manifest table is non-empty | Plugin that must be registered |
+| --- | --- |
+| `manifest.abbreviations` | `[remarkAbbreviations, { abbreviations: manifest.abbreviations }]` from `explico/reference/remark-abbreviations.mjs` |
+| `manifest.sources` | `[remarkCitation, { sources: manifest.sources }]` from `explico/reference/remark-citation.mjs` |
+| `manifest.notation.raw` | `[remarkNotation, createRemarkNotationOptions(manifest)]` from `explico/reference/remark-notation.mjs` |
+
+Check `astro.config.mjs` against that table. The check reads both wiring
+surfaces Astro offers — the flat `markdown.remarkPlugins` array and a
+`markdown.processor` such as `unified({ remarkPlugins: [...] })` — and accepts
+either the bare plugin or a `[plugin, options]` tuple. It compares by identity
+with the module the `explico/reference/*.mjs` specifier resolves to, so register
+the imported function itself rather than a local wrapper around it. A course
+that was already fully wired needs no edit; one that skipped a plugin was
+silently rendering triggers as plain text and now fails `astro build` /
+`astro dev` until it adds the missing registration.
+
+### 4. Removed markup: popup "Copy LaTeX", glossary `#` copy-link, formula scroll region
+
+None of these has a replacement selector; update course-owned CSS and
+end-to-end tests that target them:
+
+- `.notation-popup-copy` / `[data-popup-copy]` — the button in a notation
+  popup. Copying is now a click on the equation itself (item 8).
+- `[data-glossary-anchor]` and its "Link copied" flash — a glossary entry's `#`
+  button that wrote its URL to the clipboard. The entry title is now a link to
+  `#notation-<key>` (`.glossary-term-link`), and a hover-revealed link-icon
+  anchor (`.glossary-anchor`) simply navigates; nothing is copied.
+- `NotationFormula`'s `tabindex="0"` scroll region moved from
+  `.notation-formula-math` to a nested `.notation-formula-scroll`. A test that
+  focuses or scrolls `.notation-formula-math` must target the inner element.
+
+No source or config change is needed beyond selectors.
+
+### 5. Rule N14: every occurrence of a catalogued abbreviation is now wrapped
+
+Two changes ride under rule N14, neither of which needs a config edit:
+
+- **Rendered output changed.** `remarkAbbreviations` used to wrap only the first
+  occurrence of each catalogued abbreviation per page; it now wraps every
+  occurrence (`a.abbreviation-term[data-abbr-key]`). A course-owned e2e test or
+  snapshot that expected exactly one such link per term per page, or CSS that
+  assumed a page's later occurrences were plain text, must be updated.
+  `AbbreviationLayer.astro` already resolved markers independently by
+  `data-abbr-key`, so no island change is needed.
+- **The shipped baseline grew** (`base-abbreviations.mjs`): `AM`, `PM`, `A.M.`,
+  `P.M.`, and `e.t.c.` join `a.m.`, `p.m.`, `e.g.`, `i.e.`, and `etc.`. This only
+  loosens the gate. A now-redundant `abbreviations.allow` line or
+  `content/abbreviations/*.md` entry for one of them is harmless and can stay; a
+  course that wants one explained anyway lists it in `abbreviations.deny`.
+
+### 6. Rule N16 and rule N17: delimiter conventions and sizes
+
+Rule N16 (alternate `()`, `[]`, `\{\}` for purely stylistic nested grouping,
+never for conventional delimiters such as `f(x)`, `\mathbb{E}[X]`, or
+intervals) is **review-only**: nothing checks it and nothing needs to change to
+keep building. Rule N17 (every outer scalable pair in a nest grows strictly
+larger than the pairs inside it: `\left…\right` → `\Bigl…\Bigr` → `\biggl…\biggr`
+→ `\Biggl…\Biggr`) is a **Tier-3 warning**, `delimiter-size-hierarchy`, reported
+at the outer pair's line and column by the normal math gate for lesson math,
+notation formulas, and assessment math. It never fails a build, so no course
+needs to change to keep building. To clear the warnings, run
+`pnpm content diagnostics warning`, and enlarge each named outer pair to the
+next manual size without changing its delimiter shape. Rule N15's build-enforced
+behavior is unchanged — its documentation now also accepts an N17 manual pair as
+"sized". See [`notation.md#n16`](notation.md#n16) and
+[`notation.md#n17`](notation.md#n17).
+
+### 7. Rule P1: "or" never introduces a second name for the same thing
+
+Rule P1 opens the new `P` (prose) rule area and is **review-only**: nothing is
+checked at build time and no course change is required. When editing lessons,
+replace "the residual or error term" with "the residual (i.e., the error
+term)"-style wording. See [`prose.md#p1`](prose.md#p1).
+
+### 8. Optional: click-to-copy equations, glossary equation numbers, and live lab LaTeX
+
+Nothing to do for a course that wires `Footer` to `LessonFooter.astro`: a
+click on any `[data-notation-formula]` box now copies its `data-latex`, and every
+glossary formula gets a `G.<n>` number and copy button, automatically.
+
+Only a course with an interactive lab island that renders math through
+`renderLabMath()` can opt that equation into the gesture, and keep the copied
+LaTeX in step with the sliders, with `plainLatexTemplate` and the new
+`slotPlaceholder` export:
+
+```tsx
+import {
+  slotPlaceholder,
+  type RenderedLabMath,
+} from 'explico/reference/render-lab-math';
+
+// On the math root element:
+<div
+  className="lab-math"
+  data-notation-formula
+  data-latex={rendered.plainLatexTemplate}
+  /* … */
+/>
+
+// Where the island writes each slot's live value (`values`: slot name → text):
+let latex = rendered.plainLatexTemplate;
+for (const [name, value] of Object.entries(values)) {
+  latex = latex.split(slotPlaceholder(name)).join(value);
+}
+root.dataset.latex = latex;
+```
+
+Rebuild `latex` from the template on every update, not from the previous result.
+A lab that does not set these attributes is unchanged. `RenderedLabMath` gained
+the required `plainLatexTemplate` field; a course that constructs one by hand
+(a test double, for instance) must add it.
+
+### 9. Only if you override `Footer` yourself: mount `AnchorScrollEnhancer`
+
+The new smooth-scroll behavior for in-page anchor links ships in
+`AnchorScrollEnhancer.astro`, which `LessonFooter.astro` mounts. A course whose
+Starlight `components.Footer` is `explico/components/starlight/LessonFooter.astro`
+gets it with no change. A course that swapped in its own footer component must
+render it (`import AnchorScrollEnhancer from
+'explico/components/starlight/AnchorScrollEnhancer.astro'`, then
+`<AnchorScrollEnhancer />`) or its anchor links keep the browser's native jump.
+
+### 10. Optional: wire `rehypeBaseLinks` for a course deployed under a subpath
+
+Skip this for a course served from a domain root (`base` omitted or `'/'`); the
+plugin is a no-op there. For a course under a subpath (a GitHub Pages *project*
+site, `base: '/my-course'`), Starlight prefixes only its own navigation, so
+every root-relative link the Markdown pipeline produces — prose links,
+equation cross-references, citation links — 404s without this:
+
+```diff
++ import rehypeBaseLinks from 'explico/reference/rehype-base-links.mjs';
+  …
+  rehypePlugins: [
+    [rehypeKatex, createNotationKatexOptions()],
+    rehypeFailKatexErrors,
++   [rehypeBaseLinks, base],
+  ]
+```
+
+`base` is the same value passed to `defineConfig({ base })`. **Undo any manual
+workaround first:** the plugin prefixes every `href` beginning with a single
+`/`, so a lesson link already hand-written as `/my-course/other/` would become
+`/my-course/my-course/other/`. Write lesson links without the base. A lesson's
+Starlight frontmatter (`hero.actions[].link`) never passes through this
+pipeline; write those as paths relative to the current page.
+
+### 11. Optional: run logs for `pnpm validate:content`
+
+Route the course's `scripts/compile-manifest.ts` through `createRunLog()` to
+record every diagnostic to `build/logs/<timestamp>/{error,warning,info}.log`
+(Python `logging` format, `build/logs/latest` symlinks the newest run):
+
+```diff
++ import { createRunLog } from 'explico/compiler/logging';
+  …
++ const log = createRunLog();
+  const manifest = await compileManifest(courseConfig);
+  …
+- console.warn(`[${warning.code}] ${warning.message}`);
++ console.warn(log.warning('notation', `[${warning.code}] ${warning.message}`));
+  …
++ const summary = log.close();
++ console.log(
++   `Run log: ${summary.relativeDirectory} ` +
++     `(${summary.counts.ERROR} error(s), ${summary.counts.WARNING} warning(s), ${summary.counts.INFO} info).`,
++ );
+```
+
+Each `log.error/warning/info(source, message)` call returns its message, so
+printing and recording share one expression; `log.infoDiagnostics(manifest.diagnostics)`
+records the severity-`info` findings the console never showed. Call
+`log.close()` before any `throw` so a failing run's log is complete
+(`playground/scripts/compile-manifest.ts` is a full worked example). Add
+`build/logs/` to the course's `.gitignore` — a course commits
+`build/resolution/*`, and nothing prunes old runs.
+
+### 12. Optional: the `content diagnostics` / `content warnings` commands and VS Code tasks
+
+`content diagnostics [info|warning|error] [--json]` and `content warnings
+[--json]` are new, and `content status` now reports an `info` count
+(`report.diagnostics.infos`). The engine implements them in
+`explico/compiler/cli`, but a course's own `scripts/content.ts` dispatches
+commands, so it must route them:
+
+```diff
+  import {
+    ContentCliError,
+    contentCheck,
+    contentContext,
++   contentDiagnostics,
+    contentStatus,
++   contentWarnings,
+    …
+  } from 'explico/compiler/cli';
+```
+
+Add a `case 'warnings'` (`contentWarnings(manifest)`) and a `case 'diagnostics'`
+(validate the one positional as `info`/`warning`/`error`, default `info`, then
+`contentDiagnostics(manifest, severity)`) beside `case 'status'`, printing
+`file:line:column: severity code: message` lines — copy
+`playground/scripts/content.ts`. To surface findings in VS Code's Problems
+panel, copy the three **Explico: Show content diagnostics** tasks from the
+engine repository's `.vscode/tasks.json`, replacing the `--filter` package name
+and the problem matcher's `fileLocation` root with the course's own.
+
+### 13. No action: other changes in this release
+
+- Every `<a>` back-link (`↩`) in a page's References section now also carries a
+  `title` tooltip; `remark-citation.mjs` does this itself.
+- Standalone HTML export now inlines a `<link>` only when its `rel` is
+  `stylesheet` or an icon type, and leaves other `<link>`s (`canonical`,
+  `alternate`, `preload`, …) as authored.
+
+### Verification
+
+`pnpm validate:content` (run it **twice** — the first run regenerates
+`build/resolution/*`, item 1), then `pnpm content check --changed`, then
+`astro check`, then `astro build`. `astro build` is the step that reports item 3.
+
+---
+
 ## 0.5.0 → 0.6.0
 
 ### 1. Rule S1: no heading or float title runs past 65 characters
@@ -215,6 +491,16 @@ abbreviation needs its remark plugin wired in too:
   ]
 ```
 
+Skipping this second half is now **build-enforced**, not just documented:
+`explicoContentRefresh()`'s `astro:config:setup` hook checks
+`markdown.remarkPlugins` against the manifest and throws if a catalogued
+manifest table (`manifest.abbreviations`, `manifest.sources`, or
+`manifest.notation.raw`) has no matching plugin (`remarkAbbreviations`,
+`remarkCitation`, `remarkNotation` respectively) registered — so a
+half-completed migration like this one fails `astro build`/`astro dev`
+instead of silently rendering plain text with `pnpm validate:content` still
+green.
+
 ### 5. Optional: rule N10 warns on an unexplained `\mathrm{…}` label
 
 A `\mathrm{…}` multi-letter label (`\mathrm{KE}`, `\mathrm{PV}`) not on the

package/docs/authoring/notation.md

@@ -837,14 +837,15 @@ 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 a scalable sizing 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 either the auto-sizing form (`\left(`/`\right)`,
+`\left[`/`\right]`, `\left\{`/`\right\}`, `\left|`/`\right|`) or an explicit
+manual pair from [N17](#n17).
 
 ```text
 \sin(2(90\text{°}-\theta))                          ✗ two bare ( nested
@@ -873,10 +874,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, then
+  apply [N17](#n17)'s manual sizes where necessary. Sizing the outer pair does
+  not exempt an inner bare one; both levels of a two-level nest need a sizing
+  command.
 - 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 +910,134 @@ _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. Apply [N17](#n17)
+separately so the visual size still increases from the inside out; shape and
+size are independent decisions.
+
+```text
+\Biggl[
+  a+
+  \biggl(
+    b+
+    \Bigl[
+      c+
+      \left(d+e\right)
+    \Bigr]
+  \biggr)
+\Biggr]                                                   ✓
+```
+
+Semantic notation stays intact even when stylistic grouping surrounds it:
+
+```text
+\Biggl[
+  \mathbb{E}\!\Bigl[
+    f\!\left(X\right)
+  \Bigr]
+  +
+  \biggl(
+    a+b
+  \biggr)
+\Biggr]                                                   ✓
+```
+
+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 sizes 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
+
+**Every outer pair in a nest of scalable `()`, `[]`, or `\{\}` delimiters must
+be visibly larger than every pair inside it.**
+
+Use progressively larger standard manual sizes to make grouping depth visible
+without producing unnecessarily oversized marks:
+
+1. innermost baseline: `\left ... \right` (or `\bigl ... \bigr`);
+2. next: `\Bigl ... \Bigr`;
+3. next: `\biggl ... \biggr`;
+4. outermost: `\Biggl ... \Biggr`.
+
+The opening and closing commands change size only. Preserve each delimiter's
+shape: `[` remains `[`, `(` remains `(`, and `\{` remains `\{`.
+
+_Rationale._ Two nested `\left...\right` pairs around similarly short content
+can render at the same apparent size, hiding the nesting that scalable
+delimiters were meant to clarify. A strict inside-to-outside hierarchy makes
+the depth legible and has an objective syntax-level repair through the four
+standard manual size levels.
+
+_How to apply._ Start at the innermost scalable pair and assign each enclosing
+pair the next larger level. Four or fewer levels must have a strict increase at
+every level. If a valid expression needs more levels than the standard sizes
+can distinguish, restructure the expression rather than inventing a fifth
+size. This rule is independent of N16: semantic shapes stay semantic, but their
+sizes still increase when their scalable pairs are nested.
+
+_Enforcement._ Tier-3 warning `delimiter-size-hierarchy`, 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 `\{\}`. It reports the outer
+pair's source line and column and suggests the required larger manual size when
+one exists. Malformed pairs remain KaTeX syntax errors; the size linter does not
+guess at their structure.
+
+The automated check deliberately does **not** infer mathematical semantics or
+lint delimiter-type alternation. Its suggestion repeats the exact opening and
+closing delimiter shapes it found.
+
+_Exceptions._ None for a valid nest of scalable pairs with four or fewer
+levels. Beyond four levels, the warning remains but has no automatic size
+replacement; restructure the expression. 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.6.0",
+  "version": "0.7.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",

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 };
         }