explico 0.4.0 → 0.6.0

package/docs/authoring/notation.md

@@ -131,8 +131,87 @@ _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
+emit. A lab wrapper must pass its formula/template source and request context to
+`labMathScope`:
+
+```astro
+---
+const formula = String.raw`\explain{motion.launch-speed}{v_0}`;
+const scope = await labMathScope(undefined, formula, {
+  locals: Astro.locals,
+  context: 'LaunchSummary fixed-speed formula',
+});
+const math = renderLabMath(formula, scope);
+---
+```
+
+The registration is request-local: it adds only keys used by that component
+(and their normal definition dependencies) to that lesson's popup payload. It
+does not make the global registry page-wide. An unknown key fails with the
+lesson and supplied component/formula context; a final Astro build check also
+rejects any `data-notation-key` in generated HTML that has no matching
+`data-notation-entry` source.
+
 _Enforcement._ Build-enforced (completeness gate + one-meaning-per-glyph
-consistency check).
+consistency check + final rendered-trigger/payload parity check).
 
 _Exceptions._ None. Genuinely different meanings need different glyphs or
 different pages.
@@ -295,3 +374,538 @@ reviewed line in `lint-ignore.yml` (`operator-explained:Var — <reason>`). Like
 
 _Exceptions._ Quoting a source that uses an operator glyph **and** showing what
 it means in the same passage.
+
+---
+
+## N9
+
+**A physical quantity, unit, or math operator is typeset in `$…$`, never as
+plain text — in prose, a table cell, an assessment `prompt` / `explanation`,
+or a caption that itself lives outside math.**
+
+If it would be written in italics or a special symbol in a printed textbook —
+a variable, a subscript or superscript, a unit abbreviation, an absolute-value
+bar, a division of two symbols — it goes in `$…$` (or `$$…$$`), full stop, no
+matter where on the page it sits. `45 m/s`, `t (s)`, `vx`, `\|v\|`, `KE/m` are
+all the same mistake: notation typed as if the reader's browser were a plain
+text file instead of the KaTeX pipeline this engine already ships.
+
+A unit inside math is still upright roman, never italic — SI symbols are
+upright in every printed textbook too (`\text{m/s}`, not a bare italic `m/s`,
+which KaTeX would render as the product of two variables `m` and `s`). Wrap
+the unit portion in `\text{}` and fold it into the _same_ math span as the
+symbol it modifies (`$t\ \text{(s)}$`, not two adjacent spans `$t$
+$\text{(s)}$`) — and prefer the short symbol over the spelled-out word even
+inside `\text{}` (`\text{(s)}`, not `\text{(seconds)}`), the same way a
+variable is `v_0` and not "initial velocity" once it's introduced. This does
+**not** cover a fully spelled-out unit used as an ordinary English noun in a
+sentence — "the ball leaves at 10 m/s, 30 **degrees** above the horizontal"
+keeps "degrees" as a word; that carve-out is about flowing prose, not a
+compact data label like a table header or a computed answer.
+
+This also does not apply inside a JSX component prop (`<Figure caption="…">`,
+`<Table caption="…">`, `title="…"`) — a prop string is handed to the DOM as
+plain text with no math rendering at all, so `$…$` there would show up as
+broken literal dollar signs instead of rendering; write the unit as a word or
+the symbol as plain Unicode there instead ("peaks at 45°" in a caption is
+fine).
+
+_Rationale._ A reader who can hover `$v_0$` for its notation card gets nothing
+from the same quantity spelled `v0` in a table header — the two look
+interchangeable to a drafter but only one is inside the notation system this
+course is built on — hover cards, one meaning per glyph, the completeness
+gate. A table of sampled values is exactly where this slips in, because the
+completeness gate ([N4](#n4)) only ever looks _inside_ `$…$` — text sitting
+next to it was invisible to every check until this rule.
+
+_How to apply._
+
+- A table header cell that names a quantity uses the same bound symbol the
+  lesson already introduced, `\explain{key}{…}`-wrapped if the column needs a
+  component or a different style than the card's own notation (`v_x` for
+  `[[motion.velocity]]`'s `v(t)`, exactly as `motion.acceleration`'s own
+  `formula:` already does for `\explain{motion.velocity}{\mathbf{v}}`), with
+  its unit folded into the same span as a `\text{}` suffix:
+
+  ```text
+  | $t\ \text{(s)}$ | $\explain{motion.velocity}{v_x}\ \text{(m/s)}$ |
+  ```
+
+- An absolute value or norm is `\lvert…\rvert`, never a literal `|` — a raw
+  `|` inside a Markdown table cell also collides with the table's own column
+  delimiter, which is why it shows up escaped (`\|v\|`) instead of rendering
+  as anything.
+
+- A specific (per-unit) quantity like kinetic energy per unit mass is
+  `\mathrm{KE}/m`, not `KE/m` — multi-letter roman labels still take
+  `\mathrm{}` ([N3](#n3)) inside the math span.
+
+- A unit exponent is a real LaTeX superscript (`\text{m/s}^2`), never the
+  Unicode "²"/"³" character — KaTeX's strict mode rejects those as unknown
+  symbols (`src/reference/math-glyphs.mjs`'s `parseMath` calls
+  `katex.__parse(latex, { strict: 'error' })` on every math span the
+  completeness gate collects, table headers included), so this is already
+  build-enforced via [N4](#n4)'s existing gate, not a separate check N9 needs
+  of its own. This is exactly why a unit has to be _inside_ `$…$` in the
+  first place: outside math, nothing parses the LaTeX at all, so a stray "²"
+  typed as plain Unicode text would sail through unchecked.
+
+- A header cell with **no plain-language word next to its symbol** — a bare
+  `$t$`, `$x$`, `$v_x$` column, not `Launch speed $\text{(m/s)}$` — ends up
+  100% KaTeX output, which axe-core's `empty-table-header` check flags as
+  having no text "visible to screen readers" (it does not read into `<math>`
+  for the accessible-name computation, so a header that is entirely `$…$`
+  reads as empty to it even though a sighted or MathML-supporting reader sees
+  the symbol fine). This is handled automatically, not by writing anything
+  differently: `rehype-table-header-labels.mjs` (wired into
+  `playground/astro.config.mjs`'s `rehypePlugins`, right after
+  `rehypeKatex`) finds any `<th>` with no visible text, reads the
+  `\explain{key}{…}` key(s) its LaTeX names, and inserts a visually-hidden
+  (`sr-only`) text node from that key's own `label` / `units` notation
+  metadata — a fuller, more descriptive accessible name than the visible
+  abbreviation ever showed, generated for free from data already authored.
+  It has to be real (`sr-only`-clipped, not `display:none`) content, not
+  just an `aria-label` attribute: axe-core's `empty-table-header` check
+  specifically runs `has-visible-text` (real text content), with no
+  `aria-label`/`aria-labelledby` alternative the way most of its other
+  name-checking rules allow — confirmed by reading the rule itself in
+  `node_modules/axe-core/axe.js`. The one thing this means for an author: a
+  header's symbol has to actually resolve to a key for this to have anything
+  to work with. A bare `$t$`/`$x$` already does, via the ordinary `[[key]]`
+  intro + auto-resolution every other bound glyph on the page uses; the one
+  case that doesn't is a `\mathrm{…}` compound like `\mathrm{KE}/m`, because
+  the glyph resolver never looks inside a bare `\mathrm{}` body ([N3](#n3),
+  [N10](#n10)) — explicitly `\explain{}`-wrap each side there
+  (`\explain{kinetic-energy}{\mathrm{KE}}/\explain{mass}{m}`) so the plugin
+  has something to read; a header with more than one bound key composes them
+  joined by `" / "`.
+
+_Enforcement._ Build-enforced (`gate-prose-notation.ts`, wired into the same
+`pnpm validate:content` / `astro build` completeness gate as [N4](#n4), context
+`prose`). `gateProseNotation` scans lesson prose and table cells — with code
+spans, `$…$` math, `[[key]]` references, `import` lines, and JSX tags already
+blanked out; `gateProseNotationInAssessments` runs the same checks over every
+assessment item's `prompt` / `explanation` string, since `AssessmentRunner`
+renders both through the same KaTeX pipeline as lesson body math
+(`manifest.assessmentContent`, schema v8) — a plain-text quantity there is
+just as invisible to a hover card as one in a lesson. Both look for: an
+escaped `\|`; a numeral glued to an abbreviated unit (`45 m/s`); a bare unit
+in parens (`(s)`, `(m/s²)`); a hand-typed `_`/`^` between alphanumerics; and a
+`/` between two short alphabetic tokens that isn't on a small reviewed idiom
+allowlist (`and/or`, `his/her`, …) in the check's own source. Unlike every
+other build-enforced rule here, N9 ships as a hard error
+with no Tier-3 warming-up period and no `lint-ignore.yml` entry, because it
+landed in the same change that brought the whole corpus to zero — see the
+check's file for the exact patterns and the allowlist.
+
+_Exceptions._ None acknowledged through `lint-ignore.yml` — that registry is
+for corpus-level warnings a reviewer accepts, and N9 has no warning tier to
+accept into. A genuinely non-mathematical slash idiom (`input/output`, …) is
+added to the allowlist in `gate-prose-notation.ts` itself, reviewed like any
+other change to this file.
+
+---
+
+## N10
+
+**A `\mathrm{…}` multi-letter label is universal, or it is explained.**
+
+Every multi-letter roman label a lesson uses in math — `\mathrm{KE}`,
+`\mathrm{PV}`, `\mathrm{opt}` ([N3](#n3)) — is either on the shipped
+roman-label baseline (`src/reference/base-roman-labels.mjs` plus this
+course's `romanLabels.allow` in `course.config.ts`) or it carries a notation
+entry the reader can hover.
+
+_Rationale._ N3 fixes the _format_ (`\mathrm{}`, never bare letters) but is
+silent on whether the label is ever explained, because — same as an
+`\operatorname{}` body ([N8](#n8)) — the glyph resolver skips a `\mathrm{}`
+body whole; nothing about satisfying N3 requires a definition to exist. N9's
+enforcement fixed one direction of this exact page (`KE`/`PE` typed as plain
+text); this rule closes the other: `KE`/`PE` typed correctly as `\mathrm{}`
+but with no card at all, which N9 cannot see because the notation is already
+inside `$…$`.
+
+_How to apply._
+
+- A generic qualifier that functions like an operator's extremum subscript —
+  `x_{\mathrm{opt}}`, an "optimal" reading with no quantity of its own — just
+  works. The full baseline is the greppable set in `base-roman-labels.mjs`,
+  kept deliberately small: unlike a trig function, an upright label is almost
+  always a named quantity specific to one course, so it defaults to needing a
+  card rather than defaulting to universal.
+
+- A named quantity gets a notation entry, exactly like a glyph ([N4](#n4)) —
+  a shared card if the course teaches it broadly, otherwise `notation.local`,
+  same shape as [N9](#n9)'s `mass` example:
+
+  ```yaml
+  key: kinetic-energy
+  latex: \mathrm{KE}
+  label: Kinetic energy
+  meaning: The energy an object has from its motion.
+  ```
+
+  Then introduce it in prose with `[[kinetic-energy]]` before its first
+  appearance in math.
+
+- A course whose domain treats a label as common lists it once in
+  `course.config.ts` instead:
+
+  ```ts
+  romanLabels: { allow: ['PV', 'NPV'] }
+  ```
+
+  Names are the `\mathrm{…}` body. `romanLabels.deny` forces a baseline label
+  to be explained anyway.
+
+_Enforcement._ Tier-3 warning (`roman-label-explained`), surfaced by
+`pnpm validate:content`, recorded in the manifest, and silenced only by a
+reviewed line in `lint-ignore.yml` (`roman-label-explained:KE — <reason>`).
+Same rollout shape as [N8](#n8): the tier can be promoted once a corpus is
+clean.
+
+_Exceptions._ Quoting a source that uses a roman-label glyph **and** showing
+what it means in the same passage. A single-letter `\mathrm{…}` body (`d`,
+[N7](#n7)) is out of scope entirely — that is a fixed typographic operator,
+not a named quantity.
+
+---
+
+## N11
+
+**A worked example never drops a unit from a substituted value, and its
+result is dimensionally consistent.**
+
+The moment a symbol in an equation is replaced by a number — in a
+`CompactExample`, an assessment `explanation`, a derivation step, anywhere —
+that number keeps the unit its symbol carried. Never substitute bare numbers
+and attach a unit only to the final answer:
+
+```text
+v(4) = 5 + 2 \times 4 = 13\ \text{m/s}          ✗ 5 and 2 have silently lost their units
+v(4) = 5\ \text{m/s} + 2\ \text{m/s}^2 \times 4\ \text{s} = 13\ \text{m/s}   ✓
+```
+
+The mirror failure is a result whose unit does not actually follow from the
+arithmetic — copy-pasting the previous line's unit onto a different quantity.
+`v = s/t = 10/5 = 2\ \text{s}` is wrong twice over: the substitution dropped
+$s$'s and $t$'s units, which is what let `2` pick up `\text{s}` (a time unit)
+for what is actually a velocity — the arithmetic $10/5$ alone is just the
+number 2, and nothing about it says "seconds". Carried through, the units
+themselves catch the mistake: $10\ \text{m} / 5\ \text{s} = 2\ \text{m/s}$
+leaves no room to mislabel the answer, which is the entire point of the rule.
+
+_Rationale._ A worked example is the one place a reader checks their own
+understanding by redoing the arithmetic. If the displayed steps drop units,
+the example teaches "plug in the numbers" instead of "the units are part of
+the equation" — and it stops being able to catch the author's own dimensional
+mistakes, since a number has no unit to contradict. N9 already forces every
+quantity into `$…$` with its unit properly typeset; this rule is the
+complementary content requirement that the _substitution steps themselves_
+keep carrying those units all the way to the answer, not just the input
+values and the final line.
+
+_How to apply._
+
+- Attach each value's unit with `\text{}` at the moment it replaces its
+  symbol, exactly as [N9](#n9) already typesets a bound quantity — folded
+  into the same math term as its number, not a separate span
+  (`2\ \text{m/s}^2`, not `2` and `\text{m/s}^2` as two adjacent `$…$`).
+- Carry the units through every intermediate line a reader can see, not just
+  the first substitution and the last answer. If the full chain would be
+  unreasonably long, it is fine to skip straight from substitution to answer
+  for a single-step calculation — the rule is about not _losing_ units
+  mid-derivation, not about spelling out unit algebra for its own sake.
+- A ratio of two same-unit quantities (`\arctan(y/x)` for two lengths) is
+  dimensionless by cancellation; leaving it unitless is correct, not an
+  omission — write the units only where they actually survive to the result.
+- Squaring or otherwise combining a substituted value carries its unit
+  through the operation: `(3\ \text{m})^{2} = 9\ \text{m}^2`, not `3^2 =
+  9\ \text{m}^2` with the unit reattached after the fact.
+
+_Enforcement._ Review-only. Checking that a substitution step's units are
+_present_ is straightforward text matching, but checking that they are
+_dimensionally correct_ — that `m/s²` times `s` really does collapse to
+`m/s` — is a small computer-algebra problem, not a pattern match; no gate in
+this repo attempts it. A reviewer reads the worked example the way a student
+would: redo the substitution and confirm every number's unit, then confirm
+the arithmetic on the units themselves lands on the stated result's unit.
+
+_Exceptions._ A dimensionless ratio or angle carries no unit to begin with
+(see "how to apply" above) — that is not an exception, just correctly having
+nothing to attach.
+
+---
+
+## N12
+
+**Math syntax never carries the sentence's own trailing punctuation.**
+
+A period that ends a sentence, or a comma that joins it to the next clause,
+stays in the prose — outside `$…$` / `$$…$$` — even when the math is the last
+thing before it. Never let it drift inside the span, and never bury it inside
+a trailing `\text{}` unit:
+
+```text
+$$
+\rho = \sqrt{3^2 + 4^2} = 5\ \text{m,}      ✗ the comma is now part of the LaTeX
+$$
+
+$$
+\rho = \sqrt{3^2 + 4^2} = 5\ \text{m}       ✓ drop it — the next sentence needs no connector here
+$$
+```
+
+This is about the sentence's _own_ punctuation riding along with the math by
+accident, not about punctuation that is itself part of the mathematical
+notation — a comma separating two side-by-side equations in one display block
+(`x = \ldots, \qquad y = \ldots`) is a list separator inside the math, not
+prose leaking in, and is unaffected by this rule.
+
+_Rationale._ A trailing period or comma inside `$…$` becomes part of the
+LaTeX source: KaTeX renders it in math italic/spacing rather than as
+punctuation, it is included in whatever `\text{}` it landed inside (turning a
+unit label `\text{m}` into the unrelated string `\text{m,}`), and a reader
+who copies the equation out of the rendered page copies the stray mark with
+it. A display equation followed by a `\label{eq:…}` and then a fresh
+paragraph — the pattern most of this corpus already uses — never has this
+problem in the first place, which is the simplest fix in practice.
+
+_How to apply._ Omit the connector. A display equation does not need a
+trailing comma to link it to the sentence that continues below it — the
+paragraph break already does that job, and every rule-following equation in
+this corpus (see [N5](#n5)'s `\label{eq:…}` pattern) already ends bare. For
+inline math (`$x = 5$` mid-sentence), put the period or comma after the
+closing `$`, where it has always belonged.
+
+_Enforcement._ Review-only. A gate could, in principle, flag `.` or `,` as
+the last character before a closing `$`/`$$`, but it cannot tell a stray
+sentence-ending mark from a legitimate mathematical use of the same
+character (a decimal point, a `\ldots`, a matrix row separator) without
+false positives outweighing the catches — left to review, the same as
+[N5](#n5).
+
+_Exceptions._ A comma or period that is itself notation — a decimal point in
+a number, `\ldots`, a matrix/vector component separator — is not this rule's
+target and stays exactly where the math needs it.
+
+---
+
+## N13
+
+**A nonlinear function always takes a parenthesized argument, even a single
+symbol.**
+
+Every use of a trigonometric, inverse-trigonometric, or hyperbolic function,
+and every logarithm or exponential, wraps its argument in a visible
+parenthesis (or bracket) — never a bare symbol or number sitting directly
+after the function name:
+
+```text
+\sin x = \sin y        ✗
+\sin(x) = \sin(y)       ✓
+
+log x                  ✗
+\log(x)                 ✓
+
+\sin^2 x                ✗ — the exponent doesn't excuse the missing parens
+\sin^2(x)                ✓
+```
+
+_Rationale._ `\sin x` leaves how far the argument extends ambiguous the
+instant anything follows it — `\sin x + 1` visually reads as "sine of x,
+plus one" but a reader has to already know the convention to be sure it
+isn't "sine of (x + 1)". `\sin(x)` is unambiguous regardless of what
+surrounds it, at the cost of nothing when the argument really is a single
+symbol. Textbooks vary on this; this course picks the form that never
+requires the reader to know the convention.
+
+_How to apply._
+
+- Wrap the argument in `(...)`  — or `\left( ... \right)` when it needs to
+  grow with its contents, or `[...]`/`\left[ ... \right]` when an outer
+  pair of parentheses is already in use for something else on the same
+  line. A bare `{...}` does not count: LaTeX braces are invisible grouping,
+  so `\sin{x}` renders identically to the forbidden `\sin x`.
+- An exponent between the function and its argument does not exempt it —
+  `\sin^{2}(x)`, `\log_{2}(x)`, `\sin^{-1}(x)` all still need the
+  parenthesis after the modifier.
+- The function covered by this rule is exactly
+  [`PARENTHESIZED_FUNCTIONS`](../../src/reference/base-operators.mjs): the
+  six trigonometric functions, `arcsin`/`arccos`/`arctan`, the four
+  hyperbolic functions in the base operator library, and `exp`/`log`/`ln`/
+  `lg`. A different named operator ([N8](#n8)'s `\operatorname{Var}` and
+  friends) is unaffected — this rule is scoped to the functions whose
+  argument's extent is genuinely ambiguous without a mark, not every named
+  operator.
+
+_Enforcement._ Build-enforced, with no partial-corpus warm-up tier — like
+[N9](#n9), it ships as a hard error. `resolveMathGlyphs`
+(`src/reference/math-glyphs.mjs`) walks the parsed KaTeX tree for every
+rendered-math context this engine has — the same single resolver [N1](#n1)
+through [N10](#n10) already rely on — and fails the moment a
+`PARENTHESIZED_FUNCTIONS` name is not immediately followed by a visible
+opening delimiter. Because every context (lesson body, `notation.formula`,
+assessment `prompt`/`explanation`, a `Diagram` node's `formula`, interactive
+lab math) calls this one function, the check needs no separate wiring per
+content type: `pnpm validate:content` catches it in lesson body, formula, and
+assessment math; `astro build` catches a `Diagram` or lab-math violation
+(these are authored outside any manifest-scanned MDX body, in a component's
+own `nodes={[...]}` or lab template) as a hard render failure, since neither
+`Diagram` nor lab math has a code path that tolerates degrading a formula
+silently for this rule the way an ambiguous-glyph error can.
+
+_Exceptions._ None. A quoted source that uses `\sin x` still gets
+parenthesized in this course's rendering — the parenthesis is a typesetting
+choice, not a claim about the source's own notation, so quoting accurately
+does not require reproducing it.
+
+---
+
+## N14
+
+**An abbreviation-shaped word in prose is universal, or it is explained.**
+
+Every all-caps acronym (`OLS`, `MSE`, `SSR`) or dotted abbreviation (`w.r.t.`,
+`i.i.d.`) a lesson uses in ordinary prose — outside any `$…$` — is either on
+the shipped abbreviation baseline (`src/reference/base-abbreviations.mjs`
+plus this course's `abbreviations.allow` in `course.config.ts`), carries an
+entry in the `abbreviations` content collection
+(`content/abbreviations/*.md`), or is already explained as a math quantity on
+the same page ([N8](#n8) / [N10](#n10)). A term resolved by the table is not
+just build-checked: `remarkAbbreviations` wraps its first occurrence on the
+page in the same hover/click card the math-notation and citation systems
+already use, linking to its entry on the glossary page.
+
+_Rationale._ [N9](#n9) already forces a _math_ quantity or unit into `$…$` so
+it gets a hover card; this rule closes the parallel gap for a term that reads
+as English, not math — a reader who knows `\mathrm{MSE}` has a card two
+sections later gets nothing from "the MSE is minimized" if that sentence
+never binds to it. An abbreviation is exactly the kind of thing an
+experienced writer stops noticing they haven't defined.
+
+_How to apply._
+
+- An abbreviation that names no quantity of its own — `OLS`, `w.r.t.`,
+  `i.i.d.` — gets an entry in `content/abbreviations/*.md`:
+
+  ```yaml
+  key: ols
+  abbr: OLS
+  expansion: Ordinary least squares — the estimator that minimizes the sum of squared residuals.
+  ```
+
+  This is a lighter tier than a notation card: a name resolution only, no
+  `formula`, `units`, or curriculum `alignment`. It has no authoring syntax
+  of its own in prose (no `[[key]]` needed) — the gate below recognizes the
+  literal written form (`abbr`, or one of its `aliases`) anywhere on the
+  page.
+
+- An abbreviation that _is_ a math quantity — `MSE`, `SSR`, kinetic energy's
+  `KE` — is introduced the normal [N8](#n8)/[N10](#n10) way instead: a
+  notation entry whose `latex` is `\mathrm{MSE}` (or an `\operatorname{…}`),
+  bound with `[[key]]` or `\explain{key}{…}`. Once that entry is in scope on
+  a page, this rule already treats the bare word `MSE` in that page's prose
+  as explained — it does **not** also need an `abbreviations` table entry.
+
+- A course whose readers already know a term — `AI`, `GDP`, whatever the
+  domain treats as common — lists it once in `course.config.ts` instead:
+
+  ```ts
+  abbreviations: { allow: ['GDP', 'CPU'] }
+  ```
+
+  `abbreviations.deny` forces a shipped baseline entry (`e.g.`, `i.e.`, …) to
+  be explained anyway.
+
+_Enforcement._ Build-enforced (`gate-abbreviations.ts`), wired into the same
+`pnpm validate:content` pass as [N9](#n9), context `abbreviation`. It scans
+the exact same "prose-only" surface N9 does (code, math, `[[key]]`
+references, and JSX tags already blanked out), looking for an all-caps run of
+2+ letters or a run of 2+ single-letter-then-period groups. Like N9, it ships
+as a hard error with no Tier-3 warm-up period and no `lint-ignore.yml` entry
+— the corpus had no prior instances of either shape in prose when the check
+was added.
+
+_Exceptions._ None acknowledged through `lint-ignore.yml`. A genuinely
+universal abbreviation this course's readers cannot be expected to look up is
+added to `abbreviations.allow` in `course.config.ts`, reviewed like any other
+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.**
+
+`(`, `[`, `\{` (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|`.
+
+```text
+\sin(2(90\text{°}-\theta))                          ✗ two bare ( nested
+\sin\left(2\left(90\text{°}-\theta\right)\right)     ✓
+
+\left(1 - \sin^{2}(\theta)\right)                    ✗ bare ( one level inside \left(
+\left(1 - \sin^{2}\left(\theta\right)\right)         ✓ — sizing the outer pair
+                                                        does not size the inner one
+
+(a + [b - c])                                        ✗ nested across types too
+\left(a + \left[b - c\right]\right)                  ✓
+
+(x)                                                  ✓ — not nested, bare is fine
+```
+
+_Rationale._ A bare delimiter is a fixed-height glyph; `\left`/`\right` grows
+to match whatever it wraps. Two bare pairs nested inside each other render at
+the _same_ fixed size regardless of which one's content is actually taller,
+so the inner and outer marks visually collide or look like a typo the moment
+either side holds anything but a single short symbol. Requiring the sizing
+form at every level of a nest — rather than trying to judge, pair by pair,
+whether _this particular_ nesting happens to look fine — is the simplest rule
+that is actually checkable by machine and never leaves a judgment call to the
+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`.
+- 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.
+- A `|` has no distinct open/close glyph, so a lone pair — `\left|x\right|`,
+  or bare `|x|` when it is not nested in anything — reads as one absolute
+  value/norm, matched left to right. Conditional probability still prefers
+  `\mid` over a bare `|` regardless of nesting ([N6](#n6)).
+- A delimiter inside `\text{…}` is display text, not a sizing mark — a unit
+  written `\text{(s)}` ([N9](#n9)) is untouched by this rule even when the
+  math around it also uses `(`.
+- This is unrelated to [N13](#n13)'s requirement that a nonlinear function's
+  argument always be visibly parenthesized: N13 is satisfied by a bare
+  `\sin(x)` just as well as `\sin\left(x\right)`; N15 only fires once a
+  second one of these four glyphs nests inside the first.
+
+_Enforcement._ Build-enforced, with no partial-corpus warm-up tier — like
+[N9](#n9)/[N13](#n13), it ships as a hard error, and the corpus's two prior
+instances (`playground/content/docs/projectiles/optimal-launch-angle.mdx`)
+were fixed in the same change that added the check.
+`findNestedBareDelimiters` (`src/reference/math-glyphs.mjs`) walks the same
+parsed KaTeX tree `resolveMathGlyphs` and [N13](#n13) already build, carrying
+one stack through the whole walk: pushing a tracked bare or `\left`-sized
+delimiter, and flagging the enclosing entry (if bare) and the new one (if
+bare) the moment a second one opens while the first is still open. Because
+every rendered-math context calls `resolveMathGlyphs` — lesson body,
+`notation.formula`, assessment `prompt`/`explanation`, `Diagram`/lab math —
+the check needs no separate wiring per content type, the same story as N13.
+
+_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.