explico 0.5.0 → 0.7.0

package/docs/authoring/notation.md

@@ -131,6 +131,61 @@ _How to apply._ See the engine README's notation section and the `notation`
 collection schema. A letter that exists only so one entry's own `formula` can
 be stated is a **gloss**, not a card — it creates no curriculum edge.
 
+Do not satisfy this rule by dumping every `[[key]]` a page uses into one
+trailing "Notation used on this page" (or similarly named) section near the
+end of the lesson. `LessonFooter.astro` already injects an interactive
+"Page notation" panel — built from the page's actual notation manifest, with
+hover/click cards — into every lesson's footer automatically; a hand-written
+list repeats the same term set as flat, non-interactive prose immediately
+above it. Introduce each shared symbol inline, in the sentence where it is
+first defined or used, the way `[[eq-key]]` and other cross-references are
+already used inline elsewhere in these lessons. The completeness gate only
+checks that a `[[key]]`/`\explain{key}` appears *somewhere* in the page body
+(document order does not matter to it), but inline-at-first-use is what keeps
+the rendered page free of a redundant list — and matches what a reader
+actually wants: the symbol explained where it shows up, not gathered into an
+appendix.
+
+A page's own `notation.local` entries (declared in frontmatter) are already in
+scope everywhere on that page for the *math completeness gate* — a bare
+occurrence of a local symbol never trips "Unresolved notation" even with zero
+`[[key]]`/`\explain` references. But a **different** check,
+`assertLocalNotationParity` (run at `astro build`, not `pnpm validate:content`),
+still requires every `notation.local` entry to be *referenced* somewhere in
+the body — otherwise the build fails with "Stale Explico manifest for
+‹lesson›: lesson notation.local has […], but the page notation bundle has
+[…]." So every local entry still needs one `\explain{key}{…}` (or `[[key]]`)
+mention, even though the math gate alone wouldn't ask for it.
+
+The auto-annotator (`resolveMathGlyphs` in `math-glyphs.mjs`) re-derives every
+`\explain{…}` marker's insertion point from KaTeX's own parsed offsets, then
+re-applies those offsets to the raw source. Three shapes used to corrupt that
+offset math badly enough to either silently drop a symbol (no tooltip, no
+error) or emit unparseable output: a bare roman-label symbol (`\mathrm{SSR}`)
+could never auto-resolve at all regardless of where it sat on the page; a bare
+symbol immediately adjacent to an explicit `\explain{…}{…}` call could have
+its span swallow the whole following command; and a canonical whole-form
+match could be found _through_ an explicit call's own wrapping and extend
+past its span. All three are fixed at the resolver, not just detected — a
+bare `\mathrm{SST}`, `\epsilon\explain{feature-function}{h}`, and similar
+shapes now resolve correctly with no special authoring care required, and
+`gate-math.ts` exercises the same resolver at `pnpm validate:content` time
+(it reuses `resolveMathGlyphs` directly), so a regression here fails the
+build immediately rather than passing silently through to a render-time
+surprise.
+
+One related shape is still worth knowing, because it is a genuine authoring
+mistake rather than a resolver bug: a partial `\explain{key}{…}` wrap that
+covers only part of the key's declared `latex`. If `latex: Z_N` and you write
+`\explain{z-statistic}{Z}_N` (base wrapped, subscript left outside), the
+resolver no longer corrupts the output — but the uncovered remainder (`N`)
+has no binding of its own and correctly fails loudly as "Unresolved
+notation," at `pnpm validate:content` time. Wrap the whole declared form —
+`\explain{z-statistic}{Z_N}` — instead; bare `Z_N` elsewhere on the page then
+resolves automatically. The same applies to accent-wrapped forms
+(`latex: \widehat{\theta}`): wrap the accent and its argument together, not
+just the inner letter.
+
 Math authored inside a nested Astro component is outside the lesson MDX scan,
 so the component must declare the formula text at render time. `Diagram` and
 `NotationFormula` do this automatically from the notation keys they actually
@@ -782,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
@@ -818,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.
@@ -854,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/docs/authoring/structure-rules.md

@@ -0,0 +1,69 @@
+# Structure rules
+
+`S` rules govern the shape of a lesson's headings and the short titles on its
+keyed floats — the parts of a page a reader scans before reading prose. This
+is not [structure.md](structure.md), which is the taxonomy these rules (and
+the rest of the engine) speak in, not a rule set itself.
+
+See [README.md](README.md) for what "strong recommendation", "Build-enforced",
+and "Review-only" mean here, and how to amend a rule.
+
+---
+
+## S1
+
+**No heading, and no figure/diagram/memo/short-note title, runs past 65
+characters.**
+
+This caps every Markdown heading (`##` through `######`), a lesson's own
+`frontmatter.title` (rendered as the page's `<h1>`), and the short `title` /
+`label` prop on `Figure`, `Diagram`, `Memo`, and `ShortNote` — the text shown
+on a collapsed title bar, a diagram's caption line, or a chapter's sidebar
+entry. `Table` is exempt: it has only a `caption`, no separate `title`, and
+that caption is the LaTeX-convention full sentence shown above the table.
+
+A heading or float title that runs long is usually doing a caption's job. Move
+the rest of the sentence into the paragraph right after a heading, or into the
+float's own `caption`.
+
+```mdx
+<!-- Over the limit: the title carries the whole explanation. -->
+<Figure
+  id="ar1-forecast-fan"
+  caption="Multi-step AR(1) forecast: the conditional mean (teal) decays geometrically to the unconditional mean while the Gaussian 95% band (shaded) widens toward the stationary dispersion Γ₀; the coral line is one seeded future path."
+>
+
+<!-- At the limit: a short label, the rest moved into `caption`. -->
+<Figure
+  id="ar1-forecast-fan"
+  title="Multi-step AR(1) forecast"
+  caption="The conditional mean (teal) decays geometrically to the unconditional mean while the Gaussian 95% band (shaded) widens toward the stationary dispersion Γ₀; the coral line is one seeded future path."
+>
+```
+
+_Rationale._ A `Figure`'s `title` falls back to `caption` when omitted (see
+`Figure.astro`), so an unset `title` on a long-captioned figure silently
+becomes the text on the always-visible collapsible title bar — the reader
+sees the entire caption twice, once as the "heading" and once again in
+`<figcaption>` once they expand it. The same abuse happens with a heading
+authored as a full sentence instead of a label: the sidebar, the table of
+contents, and every anchor link now carry a paragraph instead of a title.
+Sixty-five characters is roughly one sidebar line at normal zoom before
+Starlight starts wrapping or truncating it.
+
+_How to apply._ Write the heading or `title` as a short noun phrase (a topic,
+not a claim about it); put the claim in the prose or the `caption`. If a
+`Figure` needs no distinct title beyond its caption's own first clause,
+extract that clause into `title` explicitly rather than omitting the prop and
+relying on the fallback — an omitted `title` on a long caption is exactly the
+failure this rule exists to catch.
+
+_Enforcement._ Build-enforced (`gate-heading-length.ts`, `pnpm
+validate:content`) for every Markdown heading in a lesson body and every
+`Figure`/`Diagram`/`Memo`/`ShortNote` `title`/`label` prop. Review-only for a
+lesson's `frontmatter.title` — the gate scans lesson body text and cannot see
+frontmatter, so a long page title (`<h1>`) is caught by a reviewer, not the
+build.
+
+_Exceptions._ None — a heading or float title that must exceed the limit
+should not be a heading or a float title; find the shorter label first.

package/docs/authoring/visualizations.md

@@ -53,8 +53,8 @@ the original diagram toward the full in-page region and shrink it back; it is
 not modal, follows the diagram's document position while the page scrolls, and
 adds internal vertical scrolling when the viewport is too short. The shrink
 control or Escape restores its original width. Clicking the title minimizes/
-restores the diagram and its text description; this state is remembered per
-page by default (`defaultOpen` / `rememberState` configure it).
+restores the diagram; this state is remembered per page by default
+(`defaultOpen` / `rememberState` configure it).
 The title also carries the same chain-link permalink treatment as headings.
 
 By default a laid-out width above `800px` emits a compile-time warning. Treat

package/package.json

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