explico 0.12.0 → 0.13.1

package/docs/authoring/notation.md

@@ -77,6 +77,8 @@ _How to apply._
   (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).
+  The resolver still reads a bare `d` as the differential (the base library,
+  [N4](#n4)), so an italic one does not fail the build: a reviewer catches it.
   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
@@ -122,8 +124,8 @@ _Rationale._ This is the core contract the completeness gate enforces
 corpus-wide; the rule here is just its author-facing statement. A reader hovers
 any symbol and gets exactly one card.
 
-_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
+_How to apply._ See the `notation` collection schema
+(`src/compiler/content-schemas.ts`). 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
@@ -152,6 +154,12 @@ the body — otherwise the build fails with "Stale Explico manifest for
 […]." So every local entry still needs one `\explain{key}{…}` (or `[[key]]`)
 mention, even though the math gate alone wouldn't ask for it.
 
+A local entry's key is its own: one that equals a shared entry's key wins on
+its page, so `[[key]]` would mean one thing there and another in the
+glossary and on every other page. `pnpm validate:content` warns
+(`local-shadows-shared`); give the local entry a key of its own, or use the
+shared one.
+
 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
@@ -220,6 +228,42 @@ 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.
 
+**Indexed symbols.** How the resolver binds a symbol with a subscript is part
+of this rule and always on; [N23](#n23) builds on it. A whole form wins under
+a power or a mark (`v_0^{2}` is `v_0` squared). An instance takes its
+family's card ahead of a plain entry for its base (`x_1` opens the `x_k`
+card), and only from a family whose index has the same shape. An indexed
+entry lends its card to no bare symbol: a family (`\alpha_i`) explains its
+own instances only, and an entry with a fixed index (`v_0`, `H_0`) only
+itself. A bare `\alpha` that had a card only by borrowing one fails
+`unresolved-glyph`, and the message names the indexed entry with that base:
+give it its own entry, or `\explain{key}{\alpha}` where it really is the
+family's shorthand. A function form still lends by its head (`V_0(1_t)`
+explains `V_0(1_2)`), and an entry with only a superscript (`j^{(m)}`) still
+lends to its base.
+
+**A definition that is a convention.** Some definitions are one of several in
+use: the sign on a moving-average coefficient, kurtosis with or without the
+Gaussian 3 subtracted, information per observation or per sample, whom a cash
+flow is positive for. The mathematics is the same and only the choice differs,
+so a formula brought in from a source that chose the other way gives a wrong
+answer and no error. Such an entry is defined once and cited with `[[key]]`
+like any other, and it also says that it is a choice: its `meaning` names the
+other choice in a clause, so the card warns where the symbol is used, and its
+body says how to convert. A definition nobody writes differently (a residual
+as observed minus fitted) is not a convention and needs neither. This part is
+a guide; no check reads it.
+
+```md
+---
+key: ma.coefficient
+latex: \theta
+meaning: Weight on the lagged innovation, added to the current one; Box–Jenkins and statsmodels subtract it instead.
+---
+A formula from a source that subtracts the term holds for this course's
+$\theta$ after replacing $\theta$ with $-\theta$.
+```
+
 _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;
@@ -263,8 +307,17 @@ 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)).
 
+A `$$…$$` block is one numbered equation, so it takes one label: to refer to
+two rows, give each its own block. LaTeX's own numbering tools have no place
+in it — the block already is the display, and the engine numbers it — so
+`\begin{align}`, `\begin{equation}`, `\begin{gather}` and `\tag{…}` fail
+with what to write instead (the rows of an `align` go in `\begin{aligned}`),
+and so do `\eqref{…}`, `\ref{…}` and a `\label` without `eq:`: a reference
+is `[[eq-key]]` in the prose.
+
 _Enforcement._ Partial. The converse is checked: `equations-validate.ts`
-reports `eq-key-unused` (info) for a labelled equation nothing references.
+reports `eq-key-unused` (info) for a labelled equation nothing references,
+and `eq-label-repeated` (an error) for a second `\label` in one block.
 An unlabelled-but-referenced equation builds; a reviewer catches the
 hand-numbering.
 
@@ -392,14 +445,14 @@ 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:
+  lesson already introduced, with its unit folded into the same span as a
+  `\text{}` suffix. A component takes its subscript the way [N23](#n23)
+  asks: an index entry `{}_x` makes `v_x` one derived card, "Horizontal
+  component of velocity". An `\explain{motion.velocity}{v_x}` wrap fails
+  `index-swallowed`, since that card describes the vector:
 
   ```text
-  | $t\ \text{(s)}$ | $\explain{motion.velocity}{v_x}\ \text{(m/s)}$ |
+  | $t\ \text{(s)}$ | $v_x\ \text{(m/s)}$ |
   ```
 
 - An absolute value or norm is `\lvert…\rvert`, never a literal `|` — a raw
@@ -477,6 +530,12 @@ 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.
 
+A currency amount is prose too, its dollar escaped: `\$5 to \$6`. remark-math
+pairs any two unescaped `$` on a line, so `$5 to $6` is one math span that
+shows "5 to", dollars gone; `pnpm validate:content` fails such a pair
+(`currency-dollar`, invariant `math-syntax`) — one whose content starts with
+a digit and ends in a space or runs into a digit.
+
 _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.
@@ -522,11 +581,13 @@ _How to apply._
   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`,
-  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.
+  `x_{\mathrm{opt}}`, an "optimal" reading with no quantity of its own —
+  needs no card of its own under this rule. The symbol it indexes still does
+  ([N23](#n23)): a whole form `x_{\mathrm{opt}}`, or an index entry
+  `{}_{\mathrm{opt}}`. 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`,
@@ -694,7 +755,7 @@ 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
+nothing there: spacing (`\,`, `\quad`), `\label{…}` / `\caption{…}`, 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.
@@ -1024,7 +1085,9 @@ 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{…}`:
+`\qquad` (or `\quad` when the line is tight), inside `\text{…}`. A `\quad`
+clause that names an index and its set, `\quad i = 1, \dots, n`, is
+[N23](#n23)'s set statement, not a reason:
 
 ```text
 $$
@@ -1134,7 +1197,9 @@ _Enforcement._ Build-enforced (`consistency.ts` `checkNotationUnits`,
 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.
+for a symbol whose unit is genuinely context-dependent. An index entry
+(`latex: "{}_0"`, [N23](#n23)) takes no units at all: a subscript has none,
+and the derived card it makes takes the indexed symbol's.
 
 ## N20
 
@@ -1168,33 +1233,33 @@ definition table) may cite the whole; say so in the locator (`"whole"`).
 
 **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.
+A gloss binds a symbol on one page with a `name` shown in the hover card. The
+name *names* the symbol; it does not explain it.
 
 ```yaml
 # A name.
-- key: launch-angle
-  label: launch angle
+- latex: \theta
+  name: 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
+# A description — belongs in a full notation entry's body, not a gloss name.
+- latex: \theta
+  name: 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
+name 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
+_How to apply._ Keep the name 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
+validate:content`) — warning `gloss-name-shape` for a name over the word
 limit or containing sentence punctuation / a relative clause.
 
-_Exceptions._ None — a label that cannot be short is a notation entry.
+_Exceptions._ None — a name that cannot be short is a notation entry.
 
 ---
 
@@ -1295,6 +1360,7 @@ operator on the page, and why.
 
 | Code | Severity | When |
 | --- | --- | --- |
+| `accent-swallowed` | warning | `\explain{key}{\hat{\beta}}` names a key whose own `latex` has no `\hat`, so its card cannot explain the hat |
 | `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` |
@@ -1308,7 +1374,12 @@ _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
+(`accent-explained:\hat — <reason>`). The same function warns
+`accent-swallowed` for an `\explain{key}{…}` around a decorated form whose
+key's `latex` lacks that decoration (`\explain{beta}{\hat{\beta}}`): the wrap
+counts as the whole form, but its card says nothing about the hat. Wrap only
+the letter (`\hat{\explain{beta}{\beta}}`) and explain the hat, or name an entry
+for `\hat{\beta}`. 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.
@@ -1316,3 +1387,184 @@ 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.
+
+## N23
+
+**An index is part of the symbol: a subscript is explained by the indexed
+symbol's entry, a family entry, or an index entry.**
+
+`\mathbf{v}_0` is the initial velocity, not the velocity: hovering it must
+say so. A subscript on a symbol is explained in one of three ways, and a card
+on the base alone does not count. If more than one applies, the first wins,
+the same precedence [N22](#n22) uses for decorations:
+
+1. **Whole form** — the indexed symbol is a quantity of its own. Give it its
+   own entry; that form gets that card, under a power too (`v_0^{2}` is `v_0`
+   squared):
+
+   ```yaml
+   key: initial-velocity
+   latex: \mathbf{v}_0
+   label: Initial velocity
+   ```
+
+2. **Family** — the entry's index is a running letter: `latex: x_k`, "k-th
+   iterate". It gives its card to every instance with the same shape — the
+   same base and number of comma-separated slots: `x_1`, `x_{k+1}`, `x_N` —
+   ahead of a plain `x` entry, and never to a bare `x`, which is a different
+   object (it needs its own entry, or an `\explain{key}{x}` where it really
+   is shorthand). A digit fills a running slot, but a `\mathrm{…}` or
+   `\text{…}` label never does: `x_{\mathrm{e}}` is not an instance of
+   `x_k`. Two families on one base that both fit an instance fail
+   `ambiguous-base-fallback`: keep one per page, or `\explain` the instance.
+   An entry whose index is fixed (`v_0`, `H_1`, `T_{\mathrm{opt}}`, or one
+   marked `fixedIndex: true`) is a single symbol and lends its card to
+   nothing. A function form still lends by its head: `V_0(1_t)` explains
+   `V_0(1_2)`.
+
+3. **Index entry** — the subscript means the same thing on every symbol of
+   the page. Give the subscript alone an entry: `latex` is the subscript on
+   an empty group, quoted, because a bare `{}` starts a YAML mapping.
+
+   ```yaml
+   key: motion.initial
+   latex: "{}_0"
+   label: Initial value
+   meaning: The value of a quantity at the start of the scenario, the instant when time is zero.
+   reads: "{base} evaluated at t = 0"
+   formula: "{base}_0 = {base}\\,(\\explain{motion.time}{t} = 0)"
+   ```
+
+   With the entry of the symbol it indexes, it makes a **derived card**: the
+   whole `\mathbf{v}_0` is one target, titled "Velocity vector evaluated at
+   t = 0". Its summary is the index entry's `meaning`, never the base's; its
+   formula is the index entry's `formula` with `{base}` bound to the base
+   symbol, so the reader opens the base's card from it; its units are the
+   base's. `reads` defaults to "`<label>` of `{base}`" ("Horizontal component
+   of velocity"); it names the symbol with `{base}` and is plain prose, with
+   no `$`, `\` or backtick. An index entry is listed with a square for the
+   symbol, `□₀`; a derived card is never listed. The loader rejects `units`,
+   `dimensionless`, `range` or `fixedIndex` on an index entry ([N19](#n19)
+   does not apply), and `reads` on any other entry. Two index entries for the
+   same subscript on one page fail `ambiguous-canonical-notation`: an index
+   has one meaning per page.
+
+Arithmetic on an index letter with its own card is explained already:
+`X_{t-1}` is `X`'s card, `t`'s card (`time.index`) and an offset, and every
+comma-separated slot needs such a letter (`F_{0,T}` needs the `0`
+explained). A letter in a subscript is an index, so a base-library `i`, `e`
+or `d` there needs a card too.
+
+A subscript on an operator or a bracket is not an index: `\sum_{i=1}`,
+`\lim_{t \to 0}`, `\log_{10}`, `\lVert x\rVert_2`, `\left.f\right\rvert_{x=0}`.
+A superscript is a power (`y^{(m)}` is out of scope). An entry whose `latex`
+has a superscript and no subscript (`j^{(m)}`) is a whole form for that
+symbol and, having no index, still lends its card to its bare base.
+
+### Running and fixed indices
+
+A **running** index is a lowercase letter (`i`, `k`, `t`) that ranges over a
+set; the rule asks for that set, in one of two places:
+
+- on the letter's card, or on the family entry that covers it, as `range`
+  (LaTeX, shown on the card as "Runs over …"):
+
+  ```yaml
+  key: time.index
+  latex: t
+  range: "1, \\dots, T"
+  ```
+
+- after a `\quad` on the first display line where the letter is an index,
+  for a set that belongs to the page:
+
+  ```latex
+  x_i \sim \mathcal{N}(\mu,\ \sigma^2), \quad i = 1, \dots, n
+  ```
+
+  The clause names the letter and a relation (`=`, `\in`, `\le`, `\dots`, …).
+  It is a different slot from [N18](#n18)'s `\qquad` reason.
+
+A **fixed** index names one member: digits, a `\mathrm{…}` or `\text{…}`
+label, a subscript an index entry declares (`{}_x`), or a letter whose card
+says `fixedIndex: true` (a component `x`, a label). An uppercase or Greek
+letter in a subscript (`X_N`, `p_\theta`) is a size or a symbol, not a
+running index, and needs no set.
+
+### `\explain` around an indexed symbol
+
+`\explain{key}{v_x}` makes the whole `v_x` one target with `key`'s card. If
+`key`'s own `latex` has no index (`motion.velocity` is `v(t)`), that card
+cannot explain the `x`, and the wrap hides the gap from the resolver: the
+rule reports it. Give the subscript an index entry (`{}_x`) and drop the wrap,
+or name an entry for the indexed symbol. An index inside a larger wrap
+(`\explain{survival-probability}{S(0,t_i)}`) is the wrap's, as every glyph
+inside one is.
+
+| Code | Severity | When |
+| --- | --- | --- |
+| `index-explained` | error | a subscript on a symbol has no whole form, family or index entry, and a slot has no letter with its own card — a digit, a label, a base-library letter — or the base itself has no card |
+| `index-swallowed` | error | `\explain{key}{X_i}` names a key whose `latex` has no index |
+| `index-range` | error | a running index letter's card (and the family entry over it) has no `range`, and the first display line where it is an index has no `\quad` clause stating its set |
+| `derived-key-taken` | error | an authored entry's key equals a derived card's, `<base>.sub.<index>` |
+
+In a lesson body each is reported once per indexed form (per letter, for
+`index-range`) per page, at its line; a `notation.local` formula counts with
+its page. An assessment counts on its own, and a shared entry's formula once
+per formula, with no line.
+
+**Where the rule applies.** Everywhere math is rendered:
+
+| Where | Derived cards | Checked by |
+| --- | --- | --- |
+| Lesson body (and a page that is not a chapter) | yes | `validate:content` (all four codes) |
+| Assessment prompt, explanation, option | yes | `validate:content` (`index-explained`, `index-swallowed`) |
+| Lab math (`renderLabMath` with a `labMathScope` table) | yes | `astro build`, as the lab renders |
+| `<Diagram>` node formula | yes | `astro build`, as the diagram renders |
+| Notation entry `formula:` | no | `validate:content` (`index-explained`, `index-swallowed`) |
+
+A notation formula resolves against its own card's table, so an index entry
+does not compose there. Explain an indexed symbol in a formula with a whole
+form instead: `\explain{motion.launch-speed}{v_0}`, or a gloss on the entry
+(`glosses:` with `latex: v_0` and its `name`, as in [N21](#n21)). Or wrap the subscript in the index entry's key,
+`\mathbf{v}_{\explain{motion.initial}{0}}`, which gives the `0` that card.
+`index-range` reads lesson bodies only: a letter's set is stated once, on its
+card or on the page.
+
+_Rationale._ The resolver binds a letter by its shape, so before this rule a
+subscript inherited whatever its base meant: `\mathbf{v}_0` opened "Velocity
+vector", with only the `v` highlighted and the `0` explained by nothing. An
+indexed entry also lent its card to symbols it is not: the family `\alpha_i`
+("ARCH coefficient") opened on a bare `\alpha` meaning a learning rate, and
+`H_0` ("Null hypothesis") on `H_1`. A printed book's list of symbols makes
+the same split this rule does: `v_0` when it is a named quantity, and a
+"Subscripts" group that gives `0` once when it means the same thing on many
+symbols. And a running index without its set is a familiar omission: the
+reader cannot tell whether `i` runs to `n` or to `N`.
+
+_How to apply._ For each reported form, pick the first that fits: a whole
+form for a named quantity, a family for a running index, an index entry for a
+subscript that recurs with one meaning. The same index on the same letter can
+mean different things on two pages (`x_0` as a starting point, a center, a
+first observation), so an index entry is often page-local
+(`notation.local`). Give each index letter's card a `range`, or state the set
+after a `\quad`.
+
+_Enforcement._ Partial (`gate-indices.ts` `gateIndices`, `pnpm
+validate:content`) — the four errors above, over lesson bodies, notation
+formulas and assessments. A lesson-body finding is located, so `{/*
+explico-allow N23: <reason> */}` waives one place. Lab math
+(`render-lab-math.ts`) and `<Diagram>` formulas fail `astro build` with the
+same findings as they render (`indexFindings`). A reviewer checks the rest:
+that a `\quad` clause states the right set, and that a lowercase index the
+build treats as running really runs. A course switches the rule
+off with `rules.N23.enabled: false`, which stops all of it; the derived cards
+are built either way. The resolver behaviors the rule rests on — whole forms
+under a power, families by shape, no lending from a fixed label or to a bare
+symbol — are part of [N4](#n4) and always on: a bare symbol that has no card
+of its own fails `unresolved-glyph`, and its message names the indexed
+entry with that base.
+
+_Exceptions._ A `\quad` clause the check misreads takes a waiver with its
+reason. A lab whose glyph table is not the one `labMathScope` returned (a
+copy) composes no derived card and is not checked.

package/docs/authoring/retired.md

@@ -31,5 +31,6 @@ fails when it is stale.
 | N7 | The differential `d` is upright `\mathrm{d}`. | 2026-09-26 | [N2](README.md#rule-index) | `\mathrm{d}` is a line in N2’s `reserved` table. |
 | N16 | In AI-generated mathematical content, alternate delimiter types for nested grouping when their shape is stylistic; preserve every conventional or semantic delimiter shape. | 2026-09-26 | [N17](README.md#rule-index) | Folded into N17 with the preference dropped: a delimiter’s shape carries its meaning, so depth is shown by size — which this engine handles automatically — not by alternating shapes. The rule also scoped itself to “AI-generated” content, which is not a property of the page. |
 | C4 | On a release, move `## [Unreleased]` to `## [x.y.z] - YYYY-MM-DD` and bump `about.version` in the same commit. | 2026-09-26 | [C3](README.md#rule-index) | The release procedure and the invariant it keeps are one rule, and `knowledge-changelog-missing` (owned by C3) was already the check that fired on a half-finished release. |
+| S5 | A sign or perspective convention is declared once and cited everywhere else. | 2026-10-07 | [N4](README.md#rule-index) | Its check knew one finance course’s phrasing and one key per course, and never fired in any course; the `conventions` setting it read is gone. A convention is a definition, so it is now N4’s: defined once on its notation entry, whose `meaning` names the other choice and whose body says how to convert. |
 
 <!-- RETIRED-RULES:END -->

package/docs/authoring/structure-rules.md

@@ -2,8 +2,8 @@
 
 `S` rules govern the shape of a lesson's headings, the short captions on its
 keyed floats, the paragraphs that open a part page, what a page that is not
-a chapter may carry, and how a table, a
-diagram, or a convention is declared so the rest of the course can reach it —
+a chapter may carry, and how a table or a
+diagram is declared so the rest of the course can reach it —
 the parts of a page a reader scans, links to, or cites. 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.
@@ -28,7 +28,9 @@ tooltip — the `[short]` half of LaTeX's `\caption[short]{long}`. The long
 `caption` is never measured: it is the full sentence shown with the float's
 number (see [components.md § The caption pair](components.md#the-caption-pair)).
 A heading is measured as the reader sees it: its markers (`[collapsed]`,
-`[card]`, …) never render, so they never count.
+`[card]`, …) never render, so they never count; a formula counts as its
+glyphs (`$\explain{motion.range}{R}$` is one character) and a `[[key]]` term
+as its label.
 
 A heading or short caption that runs long is usually doing a caption's job.
 Move the rest of the sentence into the paragraph right after a heading, or
@@ -230,43 +232,6 @@ fail the build.
 _Exceptions._ A purely decorative diagram that nothing will ever cite may stay
 unkeyed; say so in a comment next to it.
 
-## S5
-
-**A sign or perspective convention is declared once and cited everywhere
-else.**
-
-A course names one notation entry as its sign convention
-(`conventions.signConventionKey`) and one competency as its cash-flow /
-perspective convention (`conventions.cashFlowPerspectiveCompetency`). A lesson
-whose prose states such a convention — "outflows are negative", "angles are
-measured counter-clockwise from the horizontal" — resolves it to that single
-declaration rather than restating it.
-
-```mdx
-<!-- Restated: a second, drifting definition. -->
-In this chapter, an outflow is a negative cash flow.
-
-<!-- Resolved to the declaration. -->
-Cash flows follow the [[cash-flow.sign]] convention: an outflow is negative.
-```
-
-_Rationale._ A convention restated in several lessons drifts — one says
-"negative", another "shown in parentheses" — and a reader who learned it in
-one place cannot tell whether the other place means the same thing. One
-declaration, cited, keeps the meaning in one file.
-
-_How to apply._ Cite the convention's notation entry with `[[key]]` in the
-sentence that invokes it, or list the convention's competency in the lesson's
-`teaches` / `requires`. Either anchors the prose to the declaration.
-
-_Enforcement._ Build-enforced (`consistency.ts`
-`checkConventionSingleDefinition`, `pnpm validate:content`) — a warning
-(`convention-single-definition`) for a lesson whose prose matches the
-convention pattern and is anchored by neither the term nor the competency.
-
-_Exceptions._ The lesson that *is* the declaration — the one that teaches the
-convention's competency — is anchored by definition.
-
 ## S6
 
 **Headings descend one level at a time: a lesson body starts at `##` and
@@ -307,7 +272,11 @@ _Enforcement._ Build-enforced (`gate-heading-structure.ts`, `pnpm
 validate:content`, `heading-skip`) over a lesson's outline — the top-level
 headings the section numbers count. A heading inside a component's children
 (a `<Memo>`, a `<CompactExample>`) belongs to that component and is not part
-of the outline, and a memo's own bar is not a heading of the lesson.
+of the outline, and a memo's own bar is not a heading of the lesson. A
+`<CompactExamples>` or an `<AssessmentSet>` draws an `<h2>` of its own, so
+one inside a `<Memo>` or a `<ShortNote>` fails (`heading-nested`): its
+heading would land under the memo's `<h6>`, and "On this page" would never
+list it. Put it at the top level, after the memo.
 
 _Exceptions._ None in the rule; waive one place with
 `{/* explico-allow S6: reason */}` above the heading.

package/docs/authoring/structure.md

@@ -106,6 +106,13 @@ Part 2  Projectile motion
 
 ## Part pages
 
+A part is listed in `course.settings.json` → `parts` as `{ "dir", "label" }`
+and lives in `content/docs/<dir>/`. A part listed before anything is written
+in it — no chapter and no overview page yet — is left out of the sidebar and
+the numbering, with a `part-empty` warning, so the parts after it keep their
+numbers until it has content. A lesson in a directory no part lists fails
+`validate:content` (`lesson-outside-parts`).
+
 A part is a directory, so `/<part>/` is a URL a reader will eventually type,
 follow, or be handed by a search engine. Without a page it is a 404, and the
 part exists only as a sidebar heading that cannot be linked to.
@@ -309,7 +316,11 @@ punctuation dropped, so `## Two ways to name the same point` is
 `-1`, `-2`. A reference to a heading without a number (deeper than `depth`, or
 with `show: false`) prints the heading's title in quotes instead: a reader
 could not find the number. A reference that names no top-level heading fails
-`pnpm validate:content` (`sec-ref-resolves`) and the build.
+`pnpm validate:content` (`sec-ref-resolves`) and the build. So does a heading
+whose anchor the page already gives something else
+(`heading-anchor-collision`): `## References` on a page that cites a source
+(the References section is generated, at `#references`), or `## Tab totals`
+beside `<Table id="totals">` (`#tab-totals`).
 
 ### Structure from the bottom up
 
@@ -347,6 +358,13 @@ worked-example set (`<CompactExamples>`) is numbered **`‹part›.‹chapter›
 - **Keyed or not, everything counts.** An equation with no `\label{eq:…}` still
   takes a number and a positional anchor (`#eq-2-1-4`); it just cannot be
   referenced by name.
+- **The lesson's flow counts, a callout does not.** An equation or a float
+  in a list item or a `>` quote counts like one at the top level, and so
+  does one in a `<Memo>`, `<ShortNote>` or `<Fold>`. One in a `:::note`
+  aside (or `<Aside>`, or a worked example) is illustrative and takes no
+  number; a `<Table>` or `<Figure>` there fails the build. A display
+  equation is a `$$` block whose fences sit on lines of their own:
+  `$$x$$` inside a sentence, or on one line, is inline math.
 - **The number sits with the caption.** A figure or diagram prints it in the
   caption line below its picture, a table in the caption line above, and a
   display equation beside it. What names each
@@ -571,7 +589,9 @@ A block folds in one of two ways, and every default lives in one place, the
 `sections`, `subsections` and `knowledgeChecks` take `{ collapsible,
 defaultOpen }`; the others take `{ defaultOpen }`; `tables` takes
 `{ truncateAfter }` — a table with more rows shows that many, half from each
-end, and a "… N more rows …" line. There is no `disclosure.diagrams`: a
+end, and a "… N more rows …" line, unless that would hide a single row (the
+line is as tall as the row, so the table shows whole). There is no
+`disclosure.diagrams`: a
 diagram does not fold. Every collapsible remembers the reader's own choice,
 per page, over the default (`rememberState={false}` on a memo, a fold, a
 figure's tools or an example set opts that one out). A short note's in-place
@@ -646,3 +666,34 @@ While collapsed, the surrounding sentence remains one paragraph and only the
 point in the reading flow, and exposes a “Show less” control that restores the
 original sentence. Short notes are for a locally optional explanation, not for
 material that needs a number or citations elsewhere; use a memo for that.
+
+## Retired keys
+
+A key the engine has stopped reading fails the build wherever a content file
+still sets it, so a course cannot keep maintaining a field that does nothing.
+Each `retired-key` error names the file and the key's line; deleting the line
+clears it.
+
+| Key | Where it was set | Why it went |
+| --- | --- | --- |
+| `editorialStatus` | pages, notation entries, abbreviations, competencies, assessments, sources, tracks | Lessons are reviewed continuously, so no page ever earns a one-time "reviewed" stamp. The draft / in-review / reviewed labels it put on part pages, notation cards, glossary entries and citations are gone. |
+
+Two of Starlight's own keys do not work in a course, because the manifest,
+not Starlight, decides which chapters a course lists and in what order. A
+lesson's `draft: true` fails the build as `unsupported-key`: Starlight would
+leave the page out of a production build while the sidebar still names it.
+Keep an unfinished lesson outside `content/docs/` until it is ready. A
+chapter's `sidebar.order` warns as `ignored-key`: chapters follow the order of
+the tracks (`content/tracks/*.json`).
+
+## Content schemas
+
+Every content file is checked against its collection's schema — the same
+one `astro build` loads it with (`src/compiler/content-schemas.ts`) — by
+`pnpm validate:content` and `pnpm content check`, so a value the build would
+reject fails there first, at the key's line, as a `content-schema` error:
+a notation `meaning` with `$` or `\`, a source `type` outside `primary`,
+`official-guidance`, `paper`, `book` and `secondary`, or a `studyMinutes`
+range whose low end exceeds its high end. A lesson is checked for the fields
+explico adds (`teaches`, `assumptions`, `studyMinutes`, `notation`);
+Starlight checks its own (`title`, `description`, …) when the site builds.