explico 0.8.0 → 0.11.0

package/docs/authoring/notation.md

@@ -11,105 +11,100 @@ and "Review-only" mean here, and how to amend a rule.
 
 ---
 
-## N1
-
-**The normal distribution is `\mathcal{N}`.**
-
-Write a Gaussian as `\mathcal{N}(\mu, \sigma^2)` — calligraphic `N`,
-parameterised by **mean and variance**. Name any other named distribution the
-same way: a calligraphic letter through `\mathcal{…}`.
-
-Do not use `N(\mu, \sigma^2)`, `\mathrm{N}`, `Norm(...)`, or `\mathbb{N}` — the
-last is the natural numbers ([N2](#n2)) and a build-reserved token.
+## N2
 
-_Rationale._ One corpus-wide spelling makes the symbol searchable, lets it bind
-to a single notation card, and keeps it clear of `N` used as a count and
-`\mathbb{N}` used as a set. Mean/variance is the form the standard-normal CDF
-`\Phi` and PDF `\varphi` compose with cleanly.
+**A reserved spelling means only what it is reserved for, and every other styled
+letter is a symbol of its own.**
+
+A course keeps a short table of spellings that are fixed to one meaning: nothing
+else may use them. Whether a reserved spelling *also* needs a notation entry is a
+separate question, and rule [N4](#n4)'s gate answers it — reserving a spelling is
+a convention, not an exemption. The shipped table (`rules.N2.reserved` in
+`course.settings.json`) is:
+
+| Spelling | Means | Notation entry |
+| --- | --- | --- |
+| `\mathbb{N}`, `\mathbb{Z}`, `\mathbb{R}`, `\mathbb{C}` | the naturals, integers, reals, complexes | not needed — the only four tokens the resolver treats as universal (`IGNORED_MATH_TOKENS`) |
+| `\mathbb{P}` | probability | yes, like any other identifier |
+| `\mathcal{N}(\mu, \sigma^2)` | the normal distribution, by mean and variance | yes |
+| `\mathrm{d}` | the differential | not needed — a `\mathrm{…}` body is skipped whole ([N10](#n10)) |
+
+Every _other_ styled letter — `\mathbb{E}`, `\mathbb{Q}`, `\mathbb{1}`,
+`\mathcal{L}`, `\mathbf{v}`, an italic `d` used as a variable — is an ordinary
+symbol that resolves to a notation entry of its own, even when the plain letter
+already has one ([N4](#n4)).
+
+_Rationale._ Two facts, one rule. A reserved spelling is genuinely universal, so
+a per-page definition of `\mathbb{R}` would be noise — and reserving it stops a
+second meaning ("`\mathbb{N}` for the sample size") from colliding with the
+first. Everything outside the table is domain-specific and earns a card: a
+styled letter is a different glyph from its plain letter, and a reader who sees
+`\mathbb{E}` hovers it expecting the expectation, not an energy `E`.
 
 _How to apply._
 
-- Define it once. Add a notation entry — a shared card if the course teaches
-  probability, otherwise `notation.local` on the first lesson that needs it:
+- **The number systems** need nothing: write `\mathbb{R}^n`, `x \in \mathbb{Z}`.
+  Need the rationals as a set on one lesson? `\mathbb{Q}` is not reserved, so
+  give it an entry (or `\explain{...}{\mathbb{Q}}`) and note it in the domain
+  vocabulary.
+
+- **Probability** is `\mathbb{P}(A)` — never a bare `P` (a price, a power, a
+  point), never `\Pr`, never `\text{Prob}`. Conditional probability is
+  `\mathbb{P}(A \mid B)`, with `\mid`, not a bare `|` ([N15](#n15)).
+  Expectation is the same family, `\mathbb{E}[X]`, and — being outside the
+  table — takes an entry:
 
   ```yaml
-  key: prob.normal
-  latex: \mathcal{N}
-  label: Normal distribution
-  meaning: Gaussian distribution with mean μ and variance σ².
+  key: prob.p
+  latex: \mathbb{P}
+  label: Probability
+  meaning: Probability of an event.
   ```
 
-  Then introduce it in prose with `[[prob.normal]]` before its first appearance
-  in math, exactly like any other shared glyph ([N4](#n4)).
-
-- In a one-off context where a full entry is overkill, use the escape hatch:
-  `\explain{prob.normal}{\mathcal{N}}(\mu, \sigma^2)`. Prefer the entry.
-
-- If a course standardises on standard deviation rather than variance, state
-  that once in the domain notes, then write `\mathcal{N}(\mu, \sigma)`
-  consistently. Never mix the two forms in one corpus.
-
-- Compose consistently: `X \sim \mathcal{N}(\mu, \sigma^2)`,
-  `\Phi` for its CDF, `\varphi` for its PDF. Pick the CDF/PDF glyphs once per
-  course.
-
-_Enforcement._ Build-enforced that the symbol resolves to a key — `\mathcal{N}`
-is a bindable identifier atom to the glyph resolver, so an undefined one fails
-the completeness gate at `file:line:token`. The choice of `\mathcal{N}` over
-`N` / `\mathrm{N}` / `Norm` is convention, checked in review.
+  Introduce it in prose with `[[prob.p]]` before its first appearance in math
+  ([N4](#n4)). A course doing measure theory may add `\mathbb{Q}` as the
+  risk-neutral measure to its own `reserved` list, and state the split once in
+  the domain notes.
+
+- **The normal distribution** is `\mathcal{N}(\mu, \sigma^2)` — calligraphic
+  `N`, parameterised by mean and variance; not `N(\mu, \sigma^2)`,
+  `\mathrm{N}`, `Norm(...)`, or `\mathbb{N}`. Name any other distribution the
+  same way, with a calligraphic letter. `\mathcal{N}` needs an entry of its own
+  even on a page that defines a plain `N` as a count, and it composes with `\Phi`
+  for its CDF and `\varphi` for its PDF — pick those two once per course.
+
+- **The differential** is upright `\mathrm{d}`: `\int_a^b f(x)\,\mathrm{d}x`
+  (thin space, then `\mathrm{d}x`), `\dfrac{\mathrm{d}f}{\mathrm{d}x}`,
+  `\dfrac{\mathrm{d}^2 f}{\mathrm{d}x^2}`, `\mathrm{d}s`, `\mathrm{d}A`,
+  `\mathrm{d}t`. An italic `d` is always a variable (a distance, a day count).
+  This is the ISO 80000-2 convention, and it keeps the differential clear of a
+  lesson that binds `d`. A partial derivative uses `\partial` bare —
+  `\dfrac{\partial f}{\partial x}` — which is already distinct; do not wrap
+  it. `\mathrm{d}` is a typographic label, not a bindable atom, so it needs no
+  key of its own ([N10](#n10)); only the variable of integration still has to
+  resolve.
+
+- **Changing the table** is a course decision, made in one place:
+  `rules.N2.reserved` in `course.settings.json`, which the settings form editor
+  renders as a list. A course with no probability drops those two lines; a
+  course that parameterises the normal by standard deviation writes
+  `\mathcal{N}(\mu, \sigma)` there and then uses that form everywhere. The
+  effective table is printed on `build/rules-in-effect.md`, so an agent reads it
+  without opening this page.
+
+_Enforcement._ Review-only. The completeness gate ([N4](#n4)) forces every
+styled letter but the four number systems to resolve — to its own entry, since a
+styled letter never falls back to the plain letter's card and the base library
+has no card for it — and an unresolved one fails at `file:line:token`. But
+*which* spelling was chosen for a meaning, and whether a reserved one was reused
+for something else, is convention, caught in review. The two lists are
+deliberately different things: `IGNORED_MATH_TOKENS`
+(`src/reference/math-glyphs.mjs`) is what needs no key, `rules.N2.reserved` is
+what may not mean anything else.
 
 _Exceptions._ Quoting a source that uses a different glyph **and** showing the
-mapping to `\mathcal{N}` in the same passage.
-
----
-
-## N2
-
-**`\mathbb{N}`, `\mathbb{Z}`, `\mathbb{R}`, `\mathbb{C}` are reserved for the
-number systems.**
-
-These four blackboard-bold tokens mean the naturals, integers, reals, and
-complexes, always, and need no notation key. Every _other_ `\mathbb{…}` —
-`\mathbb{E}`, `\mathbb{P}`, `\mathbb{Q}`, `\mathbb{1}` — is an ordinary
-identifier that must resolve to a semantic key.
-
-_Rationale._ The universal sets are genuinely universal; forcing a per-page
-definition of `\mathbb{R}` would be noise. Everything else in blackboard bold
-is domain-specific (an expectation, a probability measure, an indicator) and
-earns a card.
-
-_How to apply._ Need the rationals as a set on one lesson? That collides with a
-reserved token — reach for `\explain{...}{\mathbb{Q}}` or a differently-styled
-glyph, and note it in the domain vocabulary.
-
-_Enforcement._ Partial. The gate forces every non-reserved `\mathbb{…}` to
-resolve; keeping `N/Z/R/C` for the number systems (not, say, `\mathbb{N}` for a
-sample size) is convention.
-
-_Exceptions._ None for the four reserved tokens.
-
----
-
-## N3
-
-**Multi-letter roman labels use `\mathrm{…}`.**
-
-An upright multi-letter name — `\mathrm{PV}`, `\mathrm{opt}`, `\mathrm{max}`
-where no built-in operator exists — is wrapped in `\mathrm{}`. Never write it as
-a run of bare italic letters (`PV`), which reads as a product `P \cdot V`.
-
-_Rationale._ `\mathrm{}` is a typographic label, not a bindable atom — the glyph
-resolver skips its body whole. Bare letter runs are parsed as identifier atoms,
-so `PV` asks the gate to resolve `P` and `V` separately: a build failure at
-best, a wrong binding at worst.
-
-_How to apply._ Subscripts too: `v_{\mathrm{max}}`, not `v_{max}`.
-
-_Enforcement._ Build-enforced indirectly — bare multi-letter runs hit the
-completeness gate as unresolved identifiers.
-
-_Exceptions._ Genuine products, and single-letter subscripts that are
-themselves notation keys.
+mapping to the reserved spelling in the same passage. None for the four number
+systems.
 
 ---
 
@@ -184,7 +179,22 @@ 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.
+just the inner letter. A whole-form entry like that is one of three ways to
+satisfy [N22](#n22), which treats every accent or mark as an operator.
+
+A **font-styled letter is its own glyph.** `\mathbf{x}`, `\boldsymbol{\beta}`,
+`\bm{x}`, `\mathcal{N}`, `\mathscr{L}`, `\mathfrak{g}`, `\mathbb{E}`,
+`\mathsf{x}` and `\mathtt{x}` never borrow the card of the plain letter on the
+same page: a bold vector is not the scalar, and an expectation is not an
+energy. Each needs its own entry (`latex: \mathbf{x}`) or an
+`\explain{key}{\mathbf{x}}` wrap, or it fails as `unresolved-glyph`, with a
+hint that it is a different symbol. A styled base-library letter
+(`\mathbf{e}`, `\boldsymbol{\pi}`) is not Euler's number or π either. The
+exceptions are `\mathit{x}` and `\mathnormal{x}`, which render the plain
+italic letter and so share its card, and the four reserved number systems
+([N2](#n2)). The leak ran one way only: a `\mathcal{N}` entry never bound a
+plain `N`. This applies to every rendered-math context — lesson body,
+formulas, assessments and labs.
 
 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
@@ -210,8 +220,14 @@ 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 + final rendered-trigger/payload parity check).
+_Enforcement._ Build-enforced. The completeness gate (`gate-math.ts`, `pnpm
+validate:content`; `astro build` re-runs the same resolver) fails on an
+unresolved glyph (`unresolved-glyph`) in every rendered-math context;
+`consistency.ts` adds the corpus-level lints `glyph-unique-in-corpus`
+(warning), `weak-local`, `gloss-wants-promoting`, `card-wants-demoting`
+(info); a final rendered-trigger/payload parity check backs it at render time.
+This rule is **locked** — the notation layer is this rule, so a course cannot
+turn it off.
 
 _Exceptions._ None. Genuinely different meanings need different glyphs or
 different pages.
@@ -226,98 +242,33 @@ If prose points back at a display equation — this page or another — the equa
 has `\label{eq:key}` and the reference is `[[eq-key]]`. Do not hand-number
 equations in the text.
 
-_Rationale._ The engine numbers every display equation `‹part›.‹n›` — the part
-is the sidebar group's position in `courseConfig.parts`, `n` counts the display
-equations across that whole part in appearance order, continuing from one
-chapter into the next (`##` and `###` headings do not affect it; see
-[`structure.md`](structure.md)) — and derives the anchor and any cross-lesson
-link from the label. A hand-typed "(3)" goes stale the moment an equation is
-inserted above it, or the chapter moves within its part. `<Table>` and
-`<Figure>` are numbered the same way, each with its own counter.
+_Rationale._ The engine numbers every display equation
+`‹part›.‹chapter›.‹n›` — the part is the sidebar group's position in
+`courseConfig.parts`, the chapter the lesson's position in its part, and `n`
+counts the chapter's display equations in appearance order (`##` and `###`
+headings do not affect it; a course may count across the whole part instead,
+see [`structure.md` § Numbering](structure.md#numbering)) — and derives the
+anchor and any cross-lesson link from the label. A hand-typed "(3)" goes stale
+the moment an equation is inserted above it, or the chapter moves within its
+part. `<Table>` and `<Figure>` are numbered the same way, each with its own
+counter.
 
 _How to apply._ Only label equations you actually reference; an unlabelled
-display equation is still fine.
+display equation is still fine. An equation may also carry a short caption,
+`\caption{Range formula}`, next to its label inside the `$$…$$`: it is
+stripped before KaTeX like the label, heads the `[[eq-…]]` preview card and
+names the copy action ("Copy LaTeX — Range formula"). An equation takes no
+long caption ([components.md § The caption pair](components.md#the-caption-pair)).
 
-_Enforcement._ Review-only — an unlabelled-but-referenced equation builds; a
-reviewer catches the hand-numbering.
+_Enforcement._ Partial. The converse is checked: `equations-validate.ts`
+reports `eq-key-unused` (info) for a labelled equation nothing references.
+An unlabelled-but-referenced equation builds; a reviewer catches the
+hand-numbering.
 
 _Exceptions._ None worth stating.
 
 ---
 
-## N6
-
-**Probability is `\mathbb{P}` — double-struck `P`.**
-
-Write a probability as `\mathbb{P}(A)` — blackboard-bold `P`. Not `P(A)` (a bare
-`P` is a variable — a price, a power, a point), not `\Pr`, not `\text{Prob}`.
-Expectation is the same family: `\mathbb{E}[X]`.
-
-_Rationale._ `\mathbb{P}` is unmistakably the probability functional, never a
-quantity. It reads next to `\mathbb{E}` and `\mathbb{Q}` as one notation family
-and never collides with a `P` the lesson uses for something physical.
-
-_How to apply._
-
-- Define it once, like [N1](#n1):
-
-  ```yaml
-  key: prob.p
-  latex: \mathbb{P}
-  label: Probability
-  meaning: Probability of an event.
-  ```
-
-  Introduce it in prose with `[[prob.p]]` before its first appearance in math.
-
-- Conditional probability is `\mathbb{P}(A \mid B)` — `\mid`, not a bare `|`.
-
-- A course doing measure theory may define `\mathbb{P}` as the real-world
-  measure and `\mathbb{Q}` as a risk-neutral one, consistent with the reserved
-  reading of `\mathbb{Q}` ([N2](#n2)). State that split once in the domain
-  notes.
-
-_Enforcement._ Build-enforced that the symbol resolves to a key — `\mathbb{P}`
-is a non-reserved `\mathbb{…}` and the completeness gate demands a binding
-([N2](#n2)). The choice of `\mathbb{P}` over `P` / `\Pr` is convention.
-
-_Exceptions._ Quoting a source that writes `\Pr` or `P` **and** showing the
-mapping to `\mathbb{P}` in the same passage.
-
----
-
-## N7
-
-**The differential `d` is upright `\mathrm{d}`.**
-
-The `d` of an integrand and the `d` of a derivative are the same operator and
-get the same upright form — distinct from an italic `d`, which is always a
-variable (a distance, a day count, a dimension):
-
-- `\int_a^b f(x)\,\mathrm{d}x` — thin space `\,`, then `\mathrm{d}x`.
-- `\dfrac{\mathrm{d}f}{\mathrm{d}x}`, `\dfrac{\mathrm{d}^2 f}{\mathrm{d}x^2}`.
-- `\mathrm{d}s`, `\mathrm{d}A`, `\mathrm{d}V`, `\mathrm{d}t` — same rule for
-  every differential.
-
-A partial derivative uses `\partial` bare — `\dfrac{\partial f}{\partial x}` —
-which is already distinct; do not wrap it in anything.
-
-_Rationale._ This is the ISO 80000-2 convention. Upright `\mathrm{d}` cannot be
-read as a factor `d \cdot x`, and it stays clear of a notation key `d` on a
-lesson that happens to have one.
-
-_How to apply._ `\mathrm{d}` is a typographic operator, not a bindable atom —
-the glyph resolver skips its body like any `\mathrm{…}` label ([N3](#n3)), so it
-needs no notation key. Only the variable of integration (`x`, `t`) still has to
-resolve.
-
-_Enforcement._ Build-enforced indirectly — a bare `\int f(x) dx` puts an
-unresolved identifier `d` in front of the completeness gate ([N3](#n3)).
-
-_Exceptions._ A verbatim quotation of a source in a blockquote.
-
----
-
 ## N8
 
 **A named operator is universal, or it is explained.**
@@ -325,12 +276,12 @@ _Exceptions._ A verbatim quotation of a source in a blockquote.
 Every named operator a lesson uses — `\exp`, `\int`, `\sin`, … as built-ins,
 `\operatorname{Var}`, `\operatorname{Cov}`, `\operatorname{E}` as declared ones
 — is either on the shipped operator baseline (`src/reference/base-operators.mjs`
-plus this course's `operators.allow` in `course.config.ts`) or it carries a
+plus this course's `rules.N8.allow` in `course.settings.json`) or it carries a
 notation entry the reader can hover.
 
 _Rationale._ The completeness gate has no opinion about operators: KaTeX parses
 `\exp` as an operator node and `\operatorname{Var}` as an `operatorname` node,
-and the glyph resolver skips both whole ([N3](#n3)). So `\operatorname{Var}`
+and the glyph resolver skips both whole ([N10](#n10)). So `\operatorname{Var}`
 renders fine while the reader is never told what "Var" means. `\exp` and `\int`
 need no such help — everyone knows them — but a domain operator does, and the
 line between the two is a course decision, made once, not per lesson.
@@ -353,7 +304,7 @@ _How to apply._
 
   Then introduce it in prose with `[[stats.variance]]` before its first
   appearance in math, and write it `\operatorname{Var}(X)` — never `Var(X)`
-  (bare letters, [N3](#n3)) and never `\mathrm{Var}` (a label, not an operator).
+  (bare letters, [N10](#n10)) and never `\mathrm{Var}` (a label, not an operator).
 
 - A course whose domain treats an operator as common — `\operatorname{Var}`,
   `\operatorname{Cov}`, `\operatorname{Corr}`, `\operatorname{sgn}` in a
@@ -364,13 +315,17 @@ _How to apply._
   ```
 
   Names are the `\operatorname{…}` body, or the command without its backslash
-  for a built-in. `operators.deny` forces a baseline operator to be explained
+  for a built-in. `rules.N8.deny` forces a baseline operator to be explained
   anyway.
 
-_Enforcement._ Tier-3 warning (`operator-explained`), surfaced by
-`pnpm validate:content`, recorded in the manifest, and silenced only by a
-reviewed line in `lint-ignore.yml` (`operator-explained:Var — <reason>`). Like
-`formula` before it (D15), the tier can be promoted once a corpus is clean.
+- Decorations (`\hat`, `'`, `^*`) are operators too, with a rule of their
+  own: [N22](#n22).
+
+_Enforcement._ Tier-3 warning (`operator-explained`, `consistency.ts`
+`checkOperatorExplained`), surfaced by `pnpm validate:content`, recorded in
+the manifest, and silenced only by a reviewed line in `lint-ignore.yml`
+(`operator-explained:Var — <reason>`). Like `formula` before it (D15), the
+tier can be promoted once a corpus is clean.
 
 _Exceptions._ Quoting a source that uses an operator glyph **and** showing what
 it means in the same passage.
@@ -397,18 +352,31 @@ 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.
+variable is `v_0` and not "initial velocity" once it's introduced.
+
+That holds in flowing prose too: a unit that quantifies something is a symbol,
+not a word. "A time of 4 seconds" is `a time of $4\ \text{s}$`; "2 meters per
+second squared" is `$2\ \text{m/s}^2$`; "30 degrees above the horizontal" is
+`$30^{\circ}$ above the horizontal`; "$x = 3$ meters" is `$x = 3\ \text{m}$` —
+the number and its unit share one span. A unit **named** without a quantity
+stays a word ("a position measured in meters", "what is its range, in
+meters?"), and so does a non-unit use of the same word ("the second
+derivative", "three degrees of freedom"). Where a sentence _defines_ a unit
+("one meter per second is the speed that covers one meter each second"),
+waive that block rather than contort it:
+
+```mdx
+{/* explico-allow N9: this sentence defines the unit */}
+One meter per second is the speed that covers one meter each second.
+```
 
 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).
+fine). The same goes for an assessment's choice `label`, which renders as
+plain text too.
 
 _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
@@ -438,7 +406,7 @@ _How to apply._
 
 - 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.
+  `\mathrm{}` ([N10](#n10)) 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
@@ -474,8 +442,7 @@ _How to apply._
   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
+  the glyph resolver never looks inside a bare `\mathrm{}` body ([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 `" / "`.
@@ -492,14 +459,29 @@ 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
+allowlist (`and/or`, `his/her`, …) in the check's own source — all reported
+as `prose-notation`. A unit written as a word is reported as `spelled-unit`
+(`unit-words.ts`, called from both entry points): an SI-style unit word
+(meter, second, minute, hour, gram, newton, joule, watt, hertz, pascal,
+volt, ampere, kelvin, mole, liter, radian, degree, and their common
+prefixed forms) after a number in digits or words (`4 seconds`, `two-meter`)
+or after a typeset number (`$x = 3$ meters`), before or after `per`, or with
+`square` / `cubic` / `squared` / `cubed`. The message spells out the math to
+write instead. "Degrees of freedom", a hyphenated compound (`second-order`)
+and a unit word standing alone are not flagged; calendar time and currency
+are not in the list. 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 each part landed in the same change that brought the whole
+corpus to zero — see the two files for the exact patterns.
+
+_Settings._ `rules.N9.allow` in the course settings lists unit words the
+course lets prose spell out (`["hour", "minute"]`), singular or plural; a
+phrase is skipped only when every unit word in it is allowed.
+
+_Exceptions._ One place is excused with a waiver on the line above its block,
+`{/* explico-allow N9: reason */}` — a sentence that defines a unit, or quotes
+a source verbatim. 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.
@@ -508,25 +490,34 @@ other change to this file.
 
 ## N10
 
-**A `\mathrm{…}` multi-letter label is universal, or it is explained.**
+**A multi-letter roman label is written `\mathrm{…}`, and it 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.
+A word-like name inside math — `KE`, `PV`, `opt`, `max` where no built-in
+operator exists — is wrapped in `\mathrm{}`: `\mathrm{KE}`,
+`v_{\mathrm{max}}`, never a bare run of italic letters. And the label itself is
+either on the shipped roman-label baseline
+(`src/reference/base-roman-labels.mjs` plus this course's `rules.N10.allow` in
+`course.settings.json`) 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
+_Rationale._ Two halves of one mistake. `\mathrm{}` is a typographic label, not
+a bindable atom: a bare `PV` is parsed as identifier atoms, so it asks the gate
+to resolve `P` and `V` separately — a build failure at best, a wrong binding at
+worst. Wrapping it fixes the parse but not the reader, 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
+body whole, so nothing about the wrap 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 `$…$`.
+text); this rule closes the other two: `KE` typed as bare italics, and
+`\mathrm{KE}` typed correctly but with no card at all, which N9 cannot see
+because the notation is already inside `$…$`.
 
 _How to apply._
 
+- **Write the label upright.** `\mathrm{PV}`, `\mathrm{opt}`,
+  `v_{\mathrm{max}}` — subscripts too, `v_{\mathrm{max}}` and never `v_{max}`.
+  A genuine product stays bare letters, and a single-letter subscript that is
+  itself a notation key stays a key.
+
 - 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`,
@@ -555,18 +546,22 @@ _How to apply._
   romanLabels: { allow: ['PV', 'NPV'] }
   ```
 
-  Names are the `\mathrm{…}` body. `romanLabels.deny` forces a baseline label
+  Names are the `\mathrm{…}` body. `rules.N10.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>`).
+_Enforcement._ Tier-3 warning (`roman-label-explained`, `consistency.ts`
+`checkRomanLabelExplained`), 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.
+clean. Partial, because the first half has no check of its own: a bare
+multi-letter run is reported by [N4](#n4)'s completeness gate as unresolved
+one-letter symbols, which is a different message for the same mistake, and a
+run whose letters all happen to be bound slips through.
 
 _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,
+the differential, [N2](#n2)) is out of scope entirely — that is a fixed typographic operator,
 not a named quantity.
 
 ---
@@ -662,6 +657,16 @@ 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.
 
+The same holds for each row of a multi-line block: a row of an `aligned` or
+`cases` block never ends in a comma or full stop before its `\\`. The comma
+between a `cases` value and its condition (`1, & x > 0`) is notation and
+stays.
+
+Two endings that look like notation are not allowed either. A trailing
+decimal point (`\hat{\beta} = 5.`) is sometimes used to say "exactly this
+precision", but a reader cannot tell it from the full stop. Write `5`, or
+`5.0` when the precision matters. A typed `...` is `\ldots`.
+
 _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
@@ -678,16 +683,26 @@ 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.
+_Enforcement._ Build-enforced (`gate-math-punctuation.ts`, wired into the
+same `pnpm validate:content` pass as [N9](#n9), code
+`math-trailing-punctuation`, an error). `gateMathPunctuation` reads every
+`$…$` / `$$…$$` span in a lesson body — the same spans the completeness gate
+resolves, table cells and component slots included — and
+`gateMathPunctuationInAssessments` every assessment `prompt` /
+`explanation`. It flags a `.`, `,`, `;` or `:` that is the last visible
+thing in the span, or in a row before a `\\`. It looks through what renders
+nothing there: spacing (`\,`, `\quad`), `\label{…}` / `\tag{…}`, a row
+break, `\end{…}`, the null delimiter `\right.`. It looks into a closing
+`\text{…}` / `\mathrm{…}`, so `5\ \text{m,}` is caught. A finding is located
+at the mark, so a per-place waiver can cover it.
+
+_Exceptions._ An upright dotted abbreviation that is itself notation may end
+the math: `+ \text{h.c.}`, `+ \text{c.c.}`, `X_n \to X\ \text{a.s.}`. The
+shipped list is `a.e.`, `a.s.`, `c.c.`, `const.`, `h.c.`, `i.i.d.`; a course
+adds one with `rules.N12.allow` and drops one with `rules.N12.deny` in
+`course.settings.json`. Set in math italic (`h.c.` without `\text{}`), it is
+not on the list. Anything else is waived in place with
+`{/* explico-allow N12: reason */}`.
 
 ---
 
@@ -742,7 +757,7 @@ _How to apply._
 _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)
+rendered-math context this engine has — the same single resolver [N2](#n2)
 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`,
@@ -769,7 +784,7 @@ does not require reproducing it.
 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
+plus this course's `rules.N14.allow` in `course.settings.json`), 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
@@ -815,7 +830,7 @@ _How to apply._
   abbreviations: { allow: ['GDP', 'CPU'] }
   ```
 
-  `abbreviations.deny` forces a shipped baseline entry (`e.g.`, `i.e.`, …) to
+  `rules.N14.deny` forces a shipped baseline entry (`e.g.`, `i.e.`, …) to
   be explained anyway.
 
 _Enforcement._ Build-enforced (`gate-abbreviations.ts`), wired into the same
@@ -829,7 +844,7 @@ 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
+added to `rules.N14.allow` in `course.settings.json`, reviewed like any other
 change to that file.
 
 ---
@@ -885,7 +900,7 @@ _How to apply._
 - 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)).
+  `\mid` over a bare `|` regardless of nesting ([N2](#n2)).
 - 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 `(`.
@@ -914,91 +929,14 @@ 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`.**
+**A delimiter's shape carries its meaning and never changes to show nesting: a
+nest is sized by the engine — `\left ... \right` at every level, never
+`\bigl`, `\Bigl`, `\biggl`, or `\Biggl` inside it.**
+
+Two decisions, one rule, and neither is the author's to improvise. *Shape* is
+fixed by what the delimiter means; *size* belongs to the engine.
 
 ```text
 \left[a+\left(b+\left[c+\left(d+e\right)\right]\right)\right]     ✓
@@ -1030,9 +968,17 @@ _How to apply._
 - 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.
+- **Keep every shape as its meaning requires it.** Function application
+  `f(x)`, expectation `\mathbb{E}[X]`, an interval `[a, b)`, a set or
+  set-builder `\{…\}`, a tuple, a commutator, a matrix, an index, a norm
+  `\|·\|`, an absolute value — the shape is part of the notation and never
+  changes. A plain parenthesis is the shape for grouping.
+- **Never alternate shapes to mark depth.** `( [ \{ … \} ] )` for a nest whose
+  delimiters only group is not this house's style: with the sizing below, depth
+  is already visible, and a reader who meets `[` inside a grouping nest has to
+  rule out an interval, an expectation and a matrix first. When in doubt about
+  whether a pair is semantic, keep the conventional notation — which is the
+  same answer as "do not alternate".
 - 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.
@@ -1053,9 +999,317 @@ 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.
+The automated check deliberately does **not** infer mathematical semantics, so
+the shape half of this rule is review-only: `delimiter-manual-size` parses
+sizing syntax and never decides whether a bracket is semantic or suggests
+turning one shape into another. A bare nested delimiter is [N15](#n15)'s error
+rather than this rule's warning.
 
 _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.
+
+---
+
+## N18
+
+**Write a multi-step derivation as one chain: one step per line, aligned at
+the relation sign, with any justification on the same line after `\qquad`.**
+
+When a display takes an expression through two or more steps — `a = b = c`,
+or `a = b \le c` — write it as an `aligned` block. The first line carries the
+left-hand side. Every later line starts with `&` directly before its relation
+(`&=`, `&\le`, `&\approx`, `&\propto`), so the relation signs stand in one
+column. A step that needs a reason gets it at the end of its own line, after
+`\qquad` (or `\quad` when the line is tight), inside `\text{…}`:
+
+```text
+$$
+\begin{aligned}
+\operatorname{Var}(Y)
+&=\mathbb{E}\left[\left(Y-\mathbb{E}[Y]\right)^2\right]
+  \qquad\text{definition of the variance}\\
+&=\mathbb{E}\left[Y^2\right]-\mathbb{E}[Y]^2
+  \qquad\text{linearity of }\mathbb{E}
+\end{aligned}
+\label{eq:variance-shortcut}
+$$                                                          ✓
+```
+
+```text
+$$
+\operatorname{Var}(Y)=\mathbb{E}\left[\left(Y-\mathbb{E}[Y]\right)^2\right]=\mathbb{E}\left[Y^2\right]-\mathbb{E}[Y]^2
+$$                                    ✗ one line: grows sideways, no room for reasons
+
+$$\operatorname{Var}(Y)=\mathbb{E}\left[\left(Y-\mathbb{E}[Y]\right)^2\right]$$
+which, by linearity of the expectation, equals
+$$\mathbb{E}\left[Y^2\right]-\mathbb{E}[Y]^2$$    ✗ one chain split by prose
+```
+
+_Rationale._ A chain written on one line grows sideways with every step and
+soon runs past the reading column, where it scrolls or spills; an aligned
+chain grows downward and is only as wide as its widest step. Relation signs
+in one column let a reader compare consecutive right-hand sides and check
+each step on its own. A reason on the step's own line sits next to what it
+justifies, where a reason in the following paragraph ("the second equality
+holds because …") has to be matched back to a position by counting. And the
+whole derivation stays one display equation: one number ([N5](#n5)), one
+link target, one copy-LaTeX unit.
+
+_How to apply._
+
+- Use `aligned` inside `$$…$$`. End every line but the last with `\\`.
+- Put `&` directly before the relation, never after it, so the relation signs
+  line up; a continuation line starts with `&=` (or its own relation).
+- A justification goes after the step's math and before its `\\`, separated
+  by `\qquad`, as `\text{…}`. Math inside a justification leaves the text
+  group: `\text{linearity of }\mathbb{E}`.
+- A justification names the fact it uses — a definition, a property, an
+  assumption, a named result ("independence of the errors", "Jensen's
+  inequality"). Never type another equation's number into the math:
+  [N5](#n5) forbids hand numbering, and the engine cannot link from inside
+  math. When a step rests on another display equation, link that equation
+  with `[[eq-key]]` in the sentence that introduces the chain ("Substituting
+  [[eq-mean]] gives"), and name it in the step if the reader needs the
+  reminder there.
+- Label the chain once, if prose refers to it ([N5](#n5)). It gets one
+  number. If later prose must cite a single line of it, end the chain before
+  that line and give the rest its own display and label.
+- A step whose explanation needs more than a short phrase belongs in prose:
+  end the chain, explain, and continue with a new chain.
+- Keep the sentence's own punctuation out of the chain ([N12](#n12)).
+
+_Enforcement._ Review-only. It could be surfaced as an info-level
+diagnostic — a display with two or more top-level relation signs outside an
+`aligned` block — but no such check exists yet.
+
+_Exceptions._
+
+- A chain of short relations that fits comfortably on one line —
+  `0 \le p \le 1`, `a = b = 0` — may stay on one line.
+- Side-by-side results that are not steps of one derivation
+  (`x = \ldots, \qquad y = \ldots`) are a list, not a chain.
+- Quoting a source whose layout carries meaning, with the passage saying so.
+
+## N19
+
+**A notation entry states its `units`, or declares itself `dimensionless`,
+using the units vocabulary.**
+
+Every entry in `content/notation/` and every `notation.local` definition
+carries either a `units:` string built from the tokens in
+`src/reference/units-vocab.ts` (`m`, `s`, `kg`, `m/s`, `m/s^2`, `rad`, `1`,
+…) or `dimensionless: true`.
+
+```yaml
+# content/notation/motion.velocity.md
+key: motion.velocity
+label: velocity
+units: m/s
+
+# content/notation/motion.launch-angle.md
+key: motion.launch-angle
+label: launch angle
+units: rad
+
+# a pure count or ratio
+dimensionless: true
+```
+
+_Rationale._ The hover card, the table-header label
+(`rehype-table-header-labels.mjs`), and a worked example's dimensional check
+(N11) all read `units` from the entry. An entry without it renders a card with
+no unit, and a unit spelled outside the vocabulary (`meters/sec`) cannot be
+matched against the one in the prose.
+
+_How to apply._ Add `units:` from the vocabulary, or `dimensionless: true`.
+Compose with `/` and `^`: `kg·m/s^2` is `kg*m/s^2`. If the vocabulary lacks a
+unit the course needs, add it to `units-vocab.ts` in the engine first.
+
+_Enforcement._ Build-enforced (`consistency.ts` `checkNotationUnits`,
+`pnpm validate:content`) — warnings `notation-units` (neither field present)
+and `units-vocab` (a token outside the vocabulary).
+
+_Exceptions._ A `lint-ignore.yml` entry (`- notation-units:<key> — <reason>`)
+for a symbol whose unit is genuinely context-dependent.
+
+## N20
+
+**A notation entry's source citation carries a locator.**
+
+Each item under an entry's `sources:` names *where* in the source the symbol is
+defined — a section, a page, an equation number — not just which source.
+
+```yaml
+sources:
+  - id: halliday-fundamentals
+    locator: "§4.3, eq. (4-12)"
+```
+
+_Rationale._ A bare source id says "this book somewhere". The hover card shows
+the locator, so a reader can open the source at the right page; a reviewer can
+check the definition against it without re-reading the chapter.
+
+_How to apply._ Fill `locator:` with the smallest unit the source has:
+`"§3.2"`, `"p. 41"`, `"eq. (2.7)"`, `"Table 4"`. Never leave it empty or
+omit it.
+
+_Enforcement._ Build-enforced (`consistency.ts` `checkNotationSourceLocator`,
+`pnpm validate:content`) — warning `notation-source-locator` per source item
+without a non-empty locator.
+
+_Exceptions._ A source that is one page long (a datasheet, a standard's
+definition table) may cite the whole; say so in the locator (`"whole"`).
+
+## N21
+
+**A gloss is named by a short noun phrase, not described by a sentence.**
+
+A gloss binds a symbol on one page with a `label` shown in the hover card. The
+label *names* the symbol; it does not explain it.
+
+```yaml
+# A name.
+- key: launch-angle
+  label: launch angle
+
+# A description — belongs in a full notation entry's body, not a gloss label.
+- key: launch-angle
+  label: the angle between the launch velocity and the horizontal, which we vary
+```
+
+_Rationale._ A gloss is the lightweight form: a name and a glyph. Once the
+label grows a clause or a sentence it is doing a notation entry's job without
+that entry's units, sources, or shared identity — and the card shows a wall of
+text where every other card shows a name.
+
+_How to apply._ Keep the label to a few words with no sentence punctuation or
+relative clause. If the symbol needs a description, promote the gloss to a
+notation entry (the `gloss-wants-promoting` hint under N4 says when).
+
+_Enforcement._ Build-enforced (`consistency.ts` `checkGlossNameShape`, `pnpm
+validate:content`) — warning `gloss-name-shape` for a label over the word
+limit or containing sentence punctuation / a relative clause.
+
+_Exceptions._ None — a label that cannot be short is a notation entry.
+
+---
+
+## N22
+
+**An accent or mark on a symbol is an operator: universal, explained, or part
+of the symbol's own entry.**
+
+`\hat{\beta}` reads as "hat applied to β". β keeps its own card, and the hat is
+either universal for this course (`rules.N22.allow`; the shipped list is
+empty), explained by an operator entry (`latex: \hat{}`, meaning "estimate
+of"), or the decorated form has its own entry (`latex: \hat{\beta}`), which
+wins for that exact form. Decorations are accents (`\hat`, `\widehat`, `\bar`,
+`\tilde`, `\dot`, `\vec`, …), `\overline` / `\underline`, and the superscript
+marks `'` (any run of primes), `*` (or `\ast`) and `\dagger`. `\widehat` and
+`\hat` are different operators. `^\top`, `^{-1}`, powers, subscripts and fonts
+are not decorations; a font makes a different symbol ([N4](#n4)).
+
+_Rationale._ The glyph resolver binds a letter by its own shape, so before this
+rule it walked straight through a hat: `\hat{\beta}` got β's card, and the hat
+was never explained. That is the same gap [N8](#n8) closes for named
+operators — `\operatorname{Var}(X)` gives `Var` and `X` a card each. A
+decoration means different things in different fields: `\hat` is an
+estimator, a unit vector or a Fourier transform; `\bar` a mean, a conjugate or
+a closure; `'` a derivative or "another one". So none is universal by default.
+
+_How to apply._ Pick one of three, in this order of precedence:
+
+1. **Whole form** — the decorated symbol is a quantity in its own right, with
+   its own formula or distribution. Give it its own entry; that exact form gets
+   that card, hat included:
+
+   ```yaml
+   key: coef-estimate
+   latex: \hat{\beta}
+   label: Estimated coefficient
+   ```
+
+2. **Operator entry** — the decoration means the same thing wherever it
+   appears on the page. Give the decoration over an empty group its own
+   entry — `\hat{}`, `\overline{}`, `{}'`, `{}^{*}`, `{}^{\dagger}` — as a
+   shared card introduced with `[[key]]` or a `notation.local` entry, like an
+   N8 operator. The reader then hovers the hat for its card, and the letter
+   under it for the letter's:
+
+   ```yaml
+   key: stats.estimate
+   latex: \hat{}
+   label: Estimate
+   meaning: The value of a quantity computed from a sample, as opposed to its true value.
+   ```
+
+3. **Universal for the course** — a course that uses a decoration one way
+   throughout lists it once in `course.settings.json`:
+
+   ```json
+   "rules": { "N22": { "allow": ["\\dot", "\\vec"] } }
+   ```
+
+   `rules.N22.deny` exists for symmetry with N8; the shipped list is empty.
+
+A letter under a decoration still needs its own card ([N4](#n4)); the
+decoration adds a card, it never replaces one.
+
+### Suspending an operator on one page
+
+Sometimes a decoration is not an operator on one page: `b'`, `b''`, `b'''` are
+successive versions of `b`, not derivatives. Say so in the lesson's
+frontmatter, with the reason:
+
+```yaml
+notation:
+  suspend:
+    - operator: "'"
+      reason: marks successive versions of b, not derivatives
+  local:
+    - key: b-v1
+      latex: b'
+      # …
+```
+
+On that page the decoration never composes: every decorated symbol that uses
+it must be a whole form — its own entry, or an `\explain{key}{b''}` wrap around
+the whole of it — or the build fails. That catches a forgotten `b''''`, and an
+`f'(x)` that still means a derivative. An `\explain{key}{b}''` around the letter
+alone is not a whole form. Other pages keep the operator reading.
+
+`operator` takes the same names as `rules.N22.allow` (`"'"`, `\hat`, `*`, …).
+A name that is not a decoration, a decoration suspended twice, and a
+`notation.local` operator entry for a decoration the same page suspends each
+fail the load. A shared operator card may still be cited on a suspending page
+with `[[key]]`, to explain the difference.
+
+Suspension covers lesson-body math only — the same scope as `notation.local`.
+A notation formula, an assessment prompt and a lab keep the operator reading.
+The Page notation panel tells the reader that the decoration is not an
+operator on the page, and why.
+
+| Code | Severity | When |
+| --- | --- | --- |
+| `suspended-operator-unresolved` | error | a decorated form of a suspended decoration has no whole form |
+| `operator-suspended` | info | a suspension with a `reason` — recorded, nothing to fix |
+| `operator-suspension-reason` | warning | a suspension without a `reason` |
+| `operator-shadowed` | info | a whole-form entry decorates with an operator that is explained or universal on its page, and the page does not suspend it |
+
+`operator-shadowed` is a note, not a fault: "β̂ is the OLS estimate" under a
+course-wide `\hat` = "estimate of" card is a legitimate refinement. It
+suggests suspension in case the decoration never means the operator there.
+
+_Enforcement._ Tier-3 warning `accent-explained` (`consistency.ts`
+`checkAccentExplained`) for a decoration that composes with no operator entry
+and is not on the allow list, one per decoration per lesson, surfaced by `pnpm
+validate:content` and silenced only by a reviewed line in `lint-ignore.yml`
+(`accent-explained:\hat — <reason>`). Suspension is build-enforced: the
+completeness gate (`gate-math.ts`) and the render path (`remark-notation.mjs`)
+both fail `suspended-operator-unresolved`; `checkOperatorSuspension` emits the
+other three codes.
+
+_Exceptions._ Suspension (above) is the sanctioned way to give a decoration a
+different meaning on one page. Quoting a source that uses a decoration
+differently **and** showing what it means in the same passage.