explico 0.5.0 → 0.7.0

package/docs/VERSIONING.md

@@ -38,8 +38,8 @@ passed now fails.
 `CHANGELOG.md`).
 
 **PATCH** — a bug fix, a docs change, an internal refactor with no surface
-change, or a new **Tier-3 warning** (warnings never fail a build, so surfacing
-one does not break a consumer).
+change, or a new **Tier-3 warning/info diagnostic** (neither fails a build, so
+surfacing one does not break a consumer).
 
 ### Pre-1.0
 
@@ -66,6 +66,21 @@ whether the bump is MAJOR, MINOR, or PATCH. The section must do one of two thing
 - state explicitly that no course changes are required, followed by the normal
   verification commands.
 
+**Every build-enforced/authoring rule and every manifest-schema bump the
+release's `CHANGELOG.md` entry names gets its own migration coverage.** 0.5.0
+shipped with only rule N14 and the schema-version bump covered — N9, N10, N13,
+and N15 were all in the changelog and all missing from `migrating.md`, and the
+schema-chain statement itself skipped the v8 and v9 bumps. A migration section
+that has *some* ordered steps is not the same as a *complete* one: derive it by
+walking the release's complete changelog entry line by line, not just its
+headline items. `pnpm check:release-migration` now cross-checks this
+mechanically (see below) — it greps the changelog entry for `rule N9`-style
+mentions and `is now v9`-style schema bumps and fails if the matching version's
+`migrating.md` section doesn't name each one the same way (`rule N9`, `v9`).
+Keep both files' phrasing in that shape; a rule discussed without the word
+"rule" immediately before its ID, or a schema bump not written `is now vN`,
+won't be picked up by either side of the check.
+
 The changelog explains what changed and why; it is not a substitute for the
 migration section. The migration section, changelog entry, version bump, and
 package are one atomic release. An agent upgrading across several versions
@@ -77,12 +92,17 @@ applies every intervening section in order.
    section of `CHANGELOG.md`.
 2. Add the section for `x.y.z` to `docs/authoring/migrating.md`, derived from the
    complete release diff. Write explicit no-action instructions when nothing in
-   a downstream course needs to change.
+   a downstream course needs to change. Walk the `CHANGELOG.md` entry you're
+   about to finalize bullet by bullet and give every `rule N#` it names, and
+   every `is now vN` schema bump, its own coverage — not only the entry's
+   headline item.
 3. `CHANGELOG.md`: rename `## [Unreleased]` to `## [x.y.z] - YYYY-MM-DD`, add a
    fresh empty `## [Unreleased]`, and fix up the compare links at the bottom.
 4. Bump `package.json` `version` (`npm version x.y.z --no-git-tag-version`).
 5. Run `pnpm check:release-migration`. It fails when the new version has no
-   migration section or the shipped-file configuration excludes the guide.
+   migration section, the shipped-file configuration excludes the guide, or a
+   `rule N#` / `is now vN` mention in the `CHANGELOG.md` entry has no match in
+   the `migrating.md` section.
 6. Run `pnpm build && pnpm test`, then inspect `pnpm pack --dry-run` and confirm
    that `docs/authoring/migrating.md` and `docs/authoring/agents.md` are listed.
 7. Commit, then `git tag vx.y.z`.

package/docs/authoring/README.md

@@ -22,6 +22,12 @@ Two kinds of rule live here:
 - **Review-only** — nothing checks it automatically; a reviewer does. Breaking
   one is a review comment, not a broken build.
 
+Automated diagnostics use three severities. An **error** means the content is
+incorrect, ambiguous, unexplainable, or cannot render reliably and therefore
+blocks validation. A **warning** is non-blocking but marks a rule, readability,
+or maintenance problem that should be repaired. **Info** is optional advice;
+leaving it in place can be intentional and creates no repair debt.
+
 Every rule is written to be falsifiable: you can look at a lesson and say
 whether it complies.
 
@@ -43,7 +49,7 @@ speak in: what a part, a chapter, a section, and a subsection are, and which of
 them an equation number counts.
 
 Each rule has a stable ID — a letter for its area (`N` notation,
-`V` visualizations, `C` versioning) plus a number — and this shape:
+`V` visualizations, `C` versioning, `S` structure, `P` prose) plus a number — and this shape:
 
 > **N1 — One-line imperative.**
 > _Rationale._ Why the rule exists; the failure it prevents.
@@ -74,6 +80,8 @@ file table.
 | [notation.md](notation.md)       | `N`  | how math symbols are written and bound                     |
 | [visualizations.md](visualizations.md) | `V` | diagrams, charts, interactive figures, randomness      |
 | [versioning.md](versioning.md)   | `C`  | the knowledge version and `content/CHANGELOG.md`           |
+| [structure-rules.md](structure-rules.md) | `S` | heading and figure/diagram/memo/short-note title length |
+| [prose.md](prose.md)             | `P`  | how a lesson's sentences are worded                        |
 | [components.md](components.md)   | —    | _catalog_: inline/block features available in a lesson body — tooltips, tables, figures, diagrams, memos, abbreviations, citations |
 | [agents.md](agents.md)           | —    | _guide_: working on a course repo (with an AI agent)       |
 | [migrating.md](migrating.md)     | —    | _guide_: per-version steps when bumping the `explico` dep  |
@@ -96,7 +104,9 @@ file table.
 | [N12](notation.md#n12)          | Math syntax never carries the sentence's own trailing punctuation  | Review-only                                 |
 | [N13](notation.md#n13)          | A nonlinear function always takes a parenthesized argument         | Build-enforced (`resolveMathGlyphs`)        |
 | [N14](notation.md#n14)          | An abbreviation-shaped word in prose is universal, or explained    | Build-enforced (`gate-abbreviations.ts`)    |
-| [N15](notation.md#n15)          | A nested `(`, `[`, `{`, or `\|` must use `\left`/`\right` sizing    | Build-enforced (`resolveMathGlyphs`)        |
+| [N15](notation.md#n15)          | A nested `(`, `[`, `{`, or `\|` must use scalable sizing            | Build-enforced (`resolveMathGlyphs`)        |
+| [N16](notation.md#n16)          | AI-generated stylistic grouping alternates delimiter types           | Review-only                                 |
+| [N17](notation.md#n17)          | Nested scalable delimiters grow strictly from inside to outside      | Tier-3 warning (`delimiter-size-hierarchy`) |
 | [V1](visualizations.md#v1)      | Graphs and flowcharts use the `Diagram` component                 | Review-only                                 |
 | [V2](visualizations.md#v2)      | Static charts: SVG → D3 → Observable Plot, chosen per figure       | Review-only                                 |
 | [V3](visualizations.md#v3)      | Interactive figures: island + `renderLabMath` seam + text alt      | Review-only                                 |
@@ -106,3 +116,5 @@ file table.
 | [C2](versioning.md#c2)          | The knowledge version is semver over learning-facing content       | Review-only                                 |
 | [C3](versioning.md#c3)          | `about.version` equals the newest `content/CHANGELOG.md` heading   | Build-enforced (Tier-3 `knowledge-version-mismatch`) |
 | [C4](versioning.md#c4)          | On release, move `[Unreleased]` and bump `about.version` together  | Review-only                                 |
+| [S1](structure-rules.md#s1)     | No heading, or figure/diagram/memo/short-note title, over 65 characters | Build-enforced (`gate-heading-length.ts`) for body/floats + review for `frontmatter.title` |
+| [P1](prose.md#p1)              | "or" never introduces a second name for the same thing            | Review-only                                 |

package/docs/authoring/agents.md

@@ -7,7 +7,9 @@ particular to your layout.
 
 This is a guide, not a rule area. The enforceable rules are in
 [`notation.md`](notation.md) (`N`), [`visualizations.md`](visualizations.md)
-(`V`), and [`versioning.md`](versioning.md) (`C`). When the engine's behaviour
+(`V`), [`versioning.md`](versioning.md) (`C`),
+[`structure-rules.md`](structure-rules.md) (`S`), and [`prose.md`](prose.md)
+(`P`). When the engine's behaviour
 and a rule disagree, the engine wins — see [`README.md`](README.md).
 
 ## The loop
@@ -15,8 +17,10 @@ and a rule disagree, the engine wins — see [`README.md`](README.md).
 - **Start from the CLI, not a file hunt.** `pnpm --filter <course> content
   context <lesson>` prints a lesson plus exactly its notation, references, and
   assumptions. `pnpm content status` is the draft-debt overview. `pnpm content
-  check <lesson> | --changed` is schema + refs + MDX→KaTeX, exits non-zero on an
-  error. Read those before opening files.
+  diagnostics info` lists everything; `warning` and `error` raise the minimum
+  severity. `pnpm content warnings` lists warnings only.
+  `pnpm content check <lesson> | --changed` is schema + refs + MDX→KaTeX, exits
+  non-zero on an error. Read those before opening files.
 - **Validate, twice.** `pnpm --filter <course> validate:content` regenerates
   `build/resolution/*` and then fails on the same run that changed them. Run it
   again; the second run is clean. Commit the regenerated `build/` and

package/docs/authoring/components.md

@@ -92,7 +92,10 @@ Two naming traps worth flagging for an AI author:
 - **`<Figure title="…">` is a visible short label in the collapsible title
   bar, not the HTML `title` attribute's hover tooltip.** It always renders on
   the page; it is a different feature from the [native tooltip](#inline-zero-registration)
-  above even though it reuses the same prop name.
+  above even though it reuses the same prop name. Keep it short — the whole
+  caption sentence does not belong here; see [S1](structure-rules.md#s1). An
+  omitted `title` silently falls back to `caption` in full, which is exactly
+  the failure S1 exists to catch.
 - **A raw Markdown pipe table or a raw `<table>`, or a `<Diagram>` with no
   `id`,** renders fine but never enters keyed-float validation — no number,
   no `[[…]]` target. Wrap it (`<Table>`/`<Figure>`) or give the diagram an

package/docs/authoring/migrating.md

@@ -33,9 +33,417 @@ required config block throws with the section of this file to read.
 
 ---
 
+## 0.6.0 → 0.7.0
+
+### 1. Manifest schema is now v15: diagnostic severity has three levels
+
+`MANIFEST_SCHEMA_VERSION` is 15 (v14 → v15). Public diagnostic severity unions
+now include `info`, so a client that treated "not an error" as "a warning"
+needs three edits:
+
+1. A client asserting `MANIFEST_SCHEMA_VERSION` by exact equality expects 15.
+2. Widen any hand-written `'error' | 'warning'` type over manifest diagnostics
+   to `'error' | 'warning' | 'info'`. `ConsistencyDiagnostic.severity` is now
+   `'warning' | 'info'`.
+3. In `scripts/compile-manifest.ts` (and any other consumer), filter on
+   `severity === 'warning'` before printing or counting warnings. A script that
+   counts all of `manifest.diagnostics.consistency` as "Tier-3 findings" now
+   over-reports:
+
+```diff
+-const consistencyByCode = consistencyCounts(consistency);
+-const consistencyTotal = consistency.length;
++const consistencyWarnings = consistency.filter(
++  (diagnostic) => diagnostic.severity === 'warning',
++);
++const consistencyByCode = consistencyCounts(consistencyWarnings);
++const consistencyTotal = consistencyWarnings.length;
+```
+
+These codes moved from `warning` to `info`: `eq-key-unused`, every keyed-float
+`*-key-unused`, `unused-definition`, `weak-local`, `gloss-wants-promoting`, and
+`card-wants-demoting`. Their code strings and container fields did not change,
+the `lint-ignore.yml` lines that already worked for `weak-local`,
+`gloss-wants-promoting`, and `card-wants-demoting` still match, and nothing
+blocks the build. They no longer appear in `pnpm content warnings`; read them
+with `pnpm content diagnostics info`.
+
+Run `pnpm validate:content` twice. The committed `build/resolution/*` files
+(including `consistency-report.json`) change because those findings now carry
+`info` severity and `numerals-tagged` findings are gone (item 2); commit them.
+
+### 2. Retired diagnostic: `numerals-tagged`
+
+`ConsistencyCode` no longer contains `numerals-tagged`, and the engine never
+emits it. Delete every `numerals-tagged` line from `lint-ignore.yml` (a stale
+line is inert but misleads the next reader) and every course script, test, or
+type narrowing that names the code — `tsc`/`astro check` flags the latter as a
+comparison against a non-member of the union.
+
+### 3. `explicoContentRefresh()` fails the build on a missing remark plugin (rule N14 and its siblings)
+
+This is the enforcement half of rule N14's Astro wiring (see item 4 of the
+0.4.x → 0.5.0 section). Its `astro:config:setup` hook now compares the manifest
+against the configured remark plugins and throws, naming each gap, when a
+non-empty table has no matching plugin registered:
+
+| Manifest table is non-empty | Plugin that must be registered |
+| --- | --- |
+| `manifest.abbreviations` | `[remarkAbbreviations, { abbreviations: manifest.abbreviations }]` from `explico/reference/remark-abbreviations.mjs` |
+| `manifest.sources` | `[remarkCitation, { sources: manifest.sources }]` from `explico/reference/remark-citation.mjs` |
+| `manifest.notation.raw` | `[remarkNotation, createRemarkNotationOptions(manifest)]` from `explico/reference/remark-notation.mjs` |
+
+Check `astro.config.mjs` against that table. The check reads both wiring
+surfaces Astro offers — the flat `markdown.remarkPlugins` array and a
+`markdown.processor` such as `unified({ remarkPlugins: [...] })` — and accepts
+either the bare plugin or a `[plugin, options]` tuple. It compares by identity
+with the module the `explico/reference/*.mjs` specifier resolves to, so register
+the imported function itself rather than a local wrapper around it. A course
+that was already fully wired needs no edit; one that skipped a plugin was
+silently rendering triggers as plain text and now fails `astro build` /
+`astro dev` until it adds the missing registration.
+
+### 4. Removed markup: popup "Copy LaTeX", glossary `#` copy-link, formula scroll region
+
+None of these has a replacement selector; update course-owned CSS and
+end-to-end tests that target them:
+
+- `.notation-popup-copy` / `[data-popup-copy]` — the button in a notation
+  popup. Copying is now a click on the equation itself (item 8).
+- `[data-glossary-anchor]` and its "Link copied" flash — a glossary entry's `#`
+  button that wrote its URL to the clipboard. The entry title is now a link to
+  `#notation-<key>` (`.glossary-term-link`), and a hover-revealed link-icon
+  anchor (`.glossary-anchor`) simply navigates; nothing is copied.
+- `NotationFormula`'s `tabindex="0"` scroll region moved from
+  `.notation-formula-math` to a nested `.notation-formula-scroll`. A test that
+  focuses or scrolls `.notation-formula-math` must target the inner element.
+
+No source or config change is needed beyond selectors.
+
+### 5. Rule N14: every occurrence of a catalogued abbreviation is now wrapped
+
+Two changes ride under rule N14, neither of which needs a config edit:
+
+- **Rendered output changed.** `remarkAbbreviations` used to wrap only the first
+  occurrence of each catalogued abbreviation per page; it now wraps every
+  occurrence (`a.abbreviation-term[data-abbr-key]`). A course-owned e2e test or
+  snapshot that expected exactly one such link per term per page, or CSS that
+  assumed a page's later occurrences were plain text, must be updated.
+  `AbbreviationLayer.astro` already resolved markers independently by
+  `data-abbr-key`, so no island change is needed.
+- **The shipped baseline grew** (`base-abbreviations.mjs`): `AM`, `PM`, `A.M.`,
+  `P.M.`, and `e.t.c.` join `a.m.`, `p.m.`, `e.g.`, `i.e.`, and `etc.`. This only
+  loosens the gate. A now-redundant `abbreviations.allow` line or
+  `content/abbreviations/*.md` entry for one of them is harmless and can stay; a
+  course that wants one explained anyway lists it in `abbreviations.deny`.
+
+### 6. Rule N16 and rule N17: delimiter conventions and sizes
+
+Rule N16 (alternate `()`, `[]`, `\{\}` for purely stylistic nested grouping,
+never for conventional delimiters such as `f(x)`, `\mathbb{E}[X]`, or
+intervals) is **review-only**: nothing checks it and nothing needs to change to
+keep building. Rule N17 (every outer scalable pair in a nest grows strictly
+larger than the pairs inside it: `\left…\right` → `\Bigl…\Bigr` → `\biggl…\biggr`
+→ `\Biggl…\Biggr`) is a **Tier-3 warning**, `delimiter-size-hierarchy`, reported
+at the outer pair's line and column by the normal math gate for lesson math,
+notation formulas, and assessment math. It never fails a build, so no course
+needs to change to keep building. To clear the warnings, run
+`pnpm content diagnostics warning`, and enlarge each named outer pair to the
+next manual size without changing its delimiter shape. Rule N15's build-enforced
+behavior is unchanged — its documentation now also accepts an N17 manual pair as
+"sized". See [`notation.md#n16`](notation.md#n16) and
+[`notation.md#n17`](notation.md#n17).
+
+### 7. Rule P1: "or" never introduces a second name for the same thing
+
+Rule P1 opens the new `P` (prose) rule area and is **review-only**: nothing is
+checked at build time and no course change is required. When editing lessons,
+replace "the residual or error term" with "the residual (i.e., the error
+term)"-style wording. See [`prose.md#p1`](prose.md#p1).
+
+### 8. Optional: click-to-copy equations, glossary equation numbers, and live lab LaTeX
+
+Nothing to do for a course that wires `Footer` to `LessonFooter.astro`: a
+click on any `[data-notation-formula]` box now copies its `data-latex`, and every
+glossary formula gets a `G.<n>` number and copy button, automatically.
+
+Only a course with an interactive lab island that renders math through
+`renderLabMath()` can opt that equation into the gesture, and keep the copied
+LaTeX in step with the sliders, with `plainLatexTemplate` and the new
+`slotPlaceholder` export:
+
+```tsx
+import {
+  slotPlaceholder,
+  type RenderedLabMath,
+} from 'explico/reference/render-lab-math';
+
+// On the math root element:
+<div
+  className="lab-math"
+  data-notation-formula
+  data-latex={rendered.plainLatexTemplate}
+  /* … */
+/>
+
+// Where the island writes each slot's live value (`values`: slot name → text):
+let latex = rendered.plainLatexTemplate;
+for (const [name, value] of Object.entries(values)) {
+  latex = latex.split(slotPlaceholder(name)).join(value);
+}
+root.dataset.latex = latex;
+```
+
+Rebuild `latex` from the template on every update, not from the previous result.
+A lab that does not set these attributes is unchanged. `RenderedLabMath` gained
+the required `plainLatexTemplate` field; a course that constructs one by hand
+(a test double, for instance) must add it.
+
+### 9. Only if you override `Footer` yourself: mount `AnchorScrollEnhancer`
+
+The new smooth-scroll behavior for in-page anchor links ships in
+`AnchorScrollEnhancer.astro`, which `LessonFooter.astro` mounts. A course whose
+Starlight `components.Footer` is `explico/components/starlight/LessonFooter.astro`
+gets it with no change. A course that swapped in its own footer component must
+render it (`import AnchorScrollEnhancer from
+'explico/components/starlight/AnchorScrollEnhancer.astro'`, then
+`<AnchorScrollEnhancer />`) or its anchor links keep the browser's native jump.
+
+### 10. Optional: wire `rehypeBaseLinks` for a course deployed under a subpath
+
+Skip this for a course served from a domain root (`base` omitted or `'/'`); the
+plugin is a no-op there. For a course under a subpath (a GitHub Pages *project*
+site, `base: '/my-course'`), Starlight prefixes only its own navigation, so
+every root-relative link the Markdown pipeline produces — prose links,
+equation cross-references, citation links — 404s without this:
+
+```diff
++ import rehypeBaseLinks from 'explico/reference/rehype-base-links.mjs';
+  …
+  rehypePlugins: [
+    [rehypeKatex, createNotationKatexOptions()],
+    rehypeFailKatexErrors,
++   [rehypeBaseLinks, base],
+  ]
+```
+
+`base` is the same value passed to `defineConfig({ base })`. **Undo any manual
+workaround first:** the plugin prefixes every `href` beginning with a single
+`/`, so a lesson link already hand-written as `/my-course/other/` would become
+`/my-course/my-course/other/`. Write lesson links without the base. A lesson's
+Starlight frontmatter (`hero.actions[].link`) never passes through this
+pipeline; write those as paths relative to the current page.
+
+### 11. Optional: run logs for `pnpm validate:content`
+
+Route the course's `scripts/compile-manifest.ts` through `createRunLog()` to
+record every diagnostic to `build/logs/<timestamp>/{error,warning,info}.log`
+(Python `logging` format, `build/logs/latest` symlinks the newest run):
+
+```diff
++ import { createRunLog } from 'explico/compiler/logging';
+  …
++ const log = createRunLog();
+  const manifest = await compileManifest(courseConfig);
+  …
+- console.warn(`[${warning.code}] ${warning.message}`);
++ console.warn(log.warning('notation', `[${warning.code}] ${warning.message}`));
+  …
++ const summary = log.close();
++ console.log(
++   `Run log: ${summary.relativeDirectory} ` +
++     `(${summary.counts.ERROR} error(s), ${summary.counts.WARNING} warning(s), ${summary.counts.INFO} info).`,
++ );
+```
+
+Each `log.error/warning/info(source, message)` call returns its message, so
+printing and recording share one expression; `log.infoDiagnostics(manifest.diagnostics)`
+records the severity-`info` findings the console never showed. Call
+`log.close()` before any `throw` so a failing run's log is complete
+(`playground/scripts/compile-manifest.ts` is a full worked example). Add
+`build/logs/` to the course's `.gitignore` — a course commits
+`build/resolution/*`, and nothing prunes old runs.
+
+### 12. Optional: the `content diagnostics` / `content warnings` commands and VS Code tasks
+
+`content diagnostics [info|warning|error] [--json]` and `content warnings
+[--json]` are new, and `content status` now reports an `info` count
+(`report.diagnostics.infos`). The engine implements them in
+`explico/compiler/cli`, but a course's own `scripts/content.ts` dispatches
+commands, so it must route them:
+
+```diff
+  import {
+    ContentCliError,
+    contentCheck,
+    contentContext,
++   contentDiagnostics,
+    contentStatus,
++   contentWarnings,
+    …
+  } from 'explico/compiler/cli';
+```
+
+Add a `case 'warnings'` (`contentWarnings(manifest)`) and a `case 'diagnostics'`
+(validate the one positional as `info`/`warning`/`error`, default `info`, then
+`contentDiagnostics(manifest, severity)`) beside `case 'status'`, printing
+`file:line:column: severity code: message` lines — copy
+`playground/scripts/content.ts`. To surface findings in VS Code's Problems
+panel, copy the three **Explico: Show content diagnostics** tasks from the
+engine repository's `.vscode/tasks.json`, replacing the `--filter` package name
+and the problem matcher's `fileLocation` root with the course's own.
+
+### 13. No action: other changes in this release
+
+- Every `<a>` back-link (`↩`) in a page's References section now also carries a
+  `title` tooltip; `remark-citation.mjs` does this itself.
+- Standalone HTML export now inlines a `<link>` only when its `rel` is
+  `stylesheet` or an icon type, and leaves other `<link>`s (`canonical`,
+  `alternate`, `preload`, …) as authored.
+
+### Verification
+
+`pnpm validate:content` (run it **twice** — the first run regenerates
+`build/resolution/*`, item 1), then `pnpm content check --changed`, then
+`astro check`, then `astro build`. `astro build` is the step that reports item 3.
+
+---
+
+## 0.5.0 → 0.6.0
+
+### 1. Rule S1: no heading or float title runs past 65 characters
+
+Every Markdown heading (`##` through `######`), a lesson's own
+`frontmatter.title`, and the `title`/`label` prop on `Figure`, `Diagram`,
+`Memo`, and `ShortNote` is now capped at 65 characters; `Table` is exempt (it
+has only a `caption`). No wiring is required — the check runs as part of
+`pnpm validate:content` / `astro build` the same as N9/N13/N15. Audit for
+existing violations and shorten them, moving the rest of the sentence into
+the paragraph after a heading or into a float's `caption`. See
+[`docs/authoring/structure-rules.md#s1`](structure-rules.md#s1).
+
+### 2. Removed markup: `.notation-pin`, `[data-notation-control]`, `.notation-layer-heading`
+
+The "Page notation" panel's "Pin explanation" button (`.notation-pin`,
+`[data-notation-control]`) and its separate `<h2>` (`.notation-layer-heading`)
+are both gone from the rendered DOM. Pinning a card now works the same way an
+inline prose symbol always has — click its glyph — and the panel's
+`<summary>` is its only heading. Update any course-owned CSS or end-to-end
+test that targets these selectors; no other action is required.
+
+### 3. Removed prop: `<Diagram description>`
+
+`Diagram`'s `description` prop and its collapsed "Diagram description"
+fallback block (`.diagram-fallback`) no longer exist. `astro check` fails on
+an excess prop, so remove every `description="…"` passed to `<Diagram>`; fold
+that text into the diagram's `label` (caption) instead.
+
+### 4. Optional: collapsible "Page notation" panel and References section
+
+`NotationLayer` gains `defaultOpen`/`rememberState` props (mirroring
+`Figure`'s own), and `remark-citation.mjs`'s generated References heading now
+accepts a `defaultOpen` plugin option — both ride the same persisted,
+deep-linkable disclosure machinery `Figure`/`CollapsibleSections` already use,
+in place of the previous always-native-default `<details>`. No action is
+required to keep building: both default to closed, matching prior behavior,
+and the References option only takes effect on a course whose
+`astro.config.mjs` already wires `rehypeHeadingAnchors` into its rehype
+pipeline. To opt into a different default, set `CourseConfig.disclosureDefaults`:
+
+```ts
+disclosureDefaults: {
+  notation: true, // "Page notation" panel starts open for a reader with nothing saved yet
+  references: true, // generated References section starts open
+},
+```
+
+### 5. Manifest schema is now v14 (additive: v13 → v14)
+
+`CourseConfig.disclosureDefaults` is new and additive — nothing existing
+changed shape — but a client asserting on `MANIFEST_SCHEMA_VERSION` by exact
+equality needs the bump.
+
+### 6. Re-run `pnpm validate:content` — the notation auto-annotator's silent-failure bugs are fixed
+
+Several shapes that previously either dropped a symbol's tooltip silently (no
+build error) or produced malformed output are now fixed at the resolver
+(`resolveMathGlyphs`), not just documented as traps to avoid: a bare
+`\mathrm{…}`-only symbol (`\mathrm{SSR}`, `\mathrm{SST}`) can now auto-resolve
+at every later bare occurrence, a bare symbol immediately next to an
+`\explain{…}{…}` call no longer has its span corrupted, and a partial
+`\explain{key}{…}` wrap no longer produces unparseable doubled output. No
+course-side wiring changes, but re-running `pnpm validate:content` may surface
+two new classes of error that previously passed silently:
+
+- **"Unresolved notation"** for a symbol that was relying on one of the fixed
+  bugs to appear resolved when it was not (rare — the bugs mostly hid symbols
+  entirely rather than falsely resolving them) or for the uncovered remainder
+  of a partial `\explain{key}{…}` wrap. Fix by explaining the symbol, or by
+  wrapping the key's *entire* declared `latex`, not just its base glyph.
+- **"Page glyphs … have structurally identical LaTeX"** for two different
+  notation keys whose declared `latex` is the same `\operatorname{…}` or
+  `\mathrm{…}` form (e.g. two keys both `\operatorname{Var}`) — this check
+  previously silently skipped every such glyph and could not catch this. Give
+  the colliding keys distinct canonical forms, or reach for
+  `\explain{key}{…}` at every occurrence of whichever one keeps the shared
+  form.
+
 ## 0.4.x → 0.5.0
 
-### 1. Rule N14: catalogue every abbreviation used in lesson prose
+### 1. Rule N9: wrap every plain-text quantity, unit, and operator in `$…$`
+
+Every physical quantity, unit abbreviation, or math operator ever typed as
+plain text — in lesson prose, a table cell, or (new in 0.5.0) an assessment
+item's `prompt` / `explanation` string — must now be inside `$…$`. `45 m/s`,
+`t (s)`, `vx`, `\|v\|`, `KE/m` are all the same mistake. This is build-enforced
+with **no `lint-ignore.yml` escape hatch**: `pnpm validate:content` / `astro
+build` fails on every existing violation. Fix per
+[`docs/authoring/notation.md#n9`](notation.md#n9) — wrap the symbol in `$…$`
+and fold its unit into the *same* span as `\text{}` (`$t\ \text{(s)}$`, not two
+adjacent spans).
+
+Also wire the accessible-table-header plugin this rule ships with — the build
+works without it, but a table header that is now 100% KaTeX (a bare `$t$`
+column, since its unit moved inside `$…$` too) renders with no
+screen-reader-visible name until this is wired:
+
+```diff
++ import rehypeTableHeaderLabels from 'explico/reference/rehype-table-header-labels.mjs';
+  …
+  rehypePlugins: [
+    [rehypeKatex, createNotationKatexOptions()],
+    rehypeFailKatexErrors,
++   rehypeTableHeaderLabels,
+  ]
+```
+
+It reads the `\explain{key}{…}` key(s) a header's LaTeX names and backfills an
+`sr-only` label from that key's notation metadata — the one prerequisite is
+that the header's symbol resolves to a key at all, so a `\mathrm{…}` compound
+(`\mathrm{KE}/m`) needs each side explicitly `\explain{}`-wrapped.
+
+### 2. Rule N13: a nonlinear function always takes a parenthesized argument
+
+`\sin x`, `\log t`, `\exp\theta` — every trig/inverse-trig/hyperbolic function
+plus `exp`/`log`/`ln`/`lg` — is now a hard error unless its argument is
+parenthesized: `\sin(x)` or `\sin\left(x\right)` is required. Same enforcement
+shape as N9: build-enforced, no `lint-ignore.yml` escape. It fires on lesson
+body math, `notation.formula`, assessment `prompt`/`explanation`, `Diagram`
+formulas, and interactive lab math alike, since all of them resolve through
+the same glyph walker. Fix every occurrence; see
+[`docs/authoring/notation.md#n13`](notation.md#n13).
+
+### 3. Rule N15: size every level of a nested visible delimiter
+
+Once a `(`, `[`, `\{`, or `|` sits inside another one of those four — same
+type or mixed, e.g. `(a + [b])` — **every level of that nest** must switch to
+`\left`/`\right` sizing: `\sin(2(90°-\theta))` is now a hard error,
+`\sin\left(2\left(90°-\theta\right)\right)` is required. Same enforcement
+shape as N9/N13: build-enforced, no escape hatch. A single, non-nested bare
+delimiter (`(x)`) is untouched. Fix every nest; see
+[`docs/authoring/notation.md#n15`](notation.md#n15).
+
+### 4. Rule N14: catalogue every abbreviation used in lesson prose
 
 Every acronym (`OLS`, `MSE`) or dotted abbreviation (`w.r.t.`, `i.i.d.`) used in
 plain prose must now be on the shipped baseline
@@ -69,14 +477,75 @@ every `abbreviation-explained` diagnostic by adding a
 `content/abbreviations/<key>.md` entry or an `allow` entry in
 `course.config.ts`.
 
-### 2. Manifest schema is v13 (additive: v10 → v11 → v12 → v13)
+The catalog check above runs regardless of Astro wiring, but the inline
+hover/click card on a lesson page's first occurrence of a catalogued
+abbreviation needs its remark plugin wired in too:
 
-`lessons[].lessonExports`-derived fields (v11), `manifest.abbreviations` (v12),
-and `manifest.diagnostics.rawFloats` (v13) are new. A client asserting on
-`MANIFEST_SCHEMA_VERSION` by exact equality needs the bump; nothing existing
-changed shape.
+```diff
++ import remarkAbbreviations from 'explico/reference/remark-abbreviations.mjs';
+  …
+  remarkPlugins: [
+    …
+    [remarkCitation, { sources: manifest.sources }],
++   [remarkAbbreviations, { abbreviations: manifest.abbreviations }],
+  ]
+```
 
-### 3. Optional: enable standalone HTML / print lesson exports
+Skipping this second half is now **build-enforced**, not just documented:
+`explicoContentRefresh()`'s `astro:config:setup` hook checks
+`markdown.remarkPlugins` against the manifest and throws if a catalogued
+manifest table (`manifest.abbreviations`, `manifest.sources`, or
+`manifest.notation.raw`) has no matching plugin (`remarkAbbreviations`,
+`remarkCitation`, `remarkNotation` respectively) registered — so a
+half-completed migration like this one fails `astro build`/`astro dev`
+instead of silently rendering plain text with `pnpm validate:content` still
+green.
+
+### 5. Optional: rule N10 warns on an unexplained `\mathrm{…}` label
+
+A `\mathrm{…}` multi-letter label (`\mathrm{KE}`, `\mathrm{PV}`) not on the
+shipped roman-label baseline (`base-roman-labels.mjs`) or `course.config.ts`'s
+new `romanLabels.allow` now needs a notation entry the reader can hover — the
+`\mathrm{…}` counterpart to N8. Unlike N9/N13/N14/N15, this is a **Tier-3
+warning** (`roman-label-explained`), not a build failure: it never blocks
+`astro build`, and an existing violation can be silenced with a reviewed
+`lint-ignore.yml` line (`roman-label-explained:KE — <reason>`) while content is
+cleaned up. `pnpm validate:content` surfaces it. See
+[`docs/authoring/notation.md#n10`](notation.md#n10).
+
+### 6. Only if you render `AssessmentRunner` directly (bypassing `AssessmentSet.astro`)
+
+`AssessmentRunner`'s `Item` props changed shape: `prompt` / `explanation`
+(`string`) are now `promptContent` / `explanationContent`
+(`MixedContentNode[]`), rendered with the new `RenderedContent` component,
+because `AssessmentSet.astro` now pre-renders assessment math through the same
+KaTeX pipeline as lesson body math instead of handing `AssessmentRunner` a raw
+string. A course that only uses `<AssessmentSet>` needs no change here — this
+only applies to a course that imports and renders `AssessmentRunner` itself.
+
+### 7. Manifest schema is v13 (additive: v7 → v8 → v9 → v10 → v11 → v12 → v13)
+
+Every step is additive — nothing existing changed shape — but a client
+asserting on `MANIFEST_SCHEMA_VERSION` by exact equality needs the final
+number:
+
+- **v8** — `assessmentContent`: every assessment item's `prompt` /
+  `explanation`, pre-split and resolved for `AssessmentSet.astro` (see item 6
+  above).
+- **v9** — `diagrams`, `lessons[].diagrams`, `lessons[].numbering.diagrams`,
+  `diagnostics.diagrams`: `<Diagram>` becomes a first-class keyed float with
+  its own number stream and `[[dia-<id>]]` references.
+- **v10** — `checks`, `lessons[].knowledgeChecks`, `lessons[].numbering.checks`,
+  `diagnostics.checks`: numbered, referenceable knowledge checks.
+- **v11** — `lessons[].lessonExports`-derived fields: standalone HTML / print
+  export settings (item 8 below).
+- **v12** — `manifest.abbreviations` (rule N14, item 4 above).
+- **v13** — `manifest.diagnostics.rawFloats`: a raw Markdown/HTML table, an
+  unkeyed `<Diagram>`, or a `<Diagram>` nested outside
+  `<Memo>`/`<ShortNote>`/`<Table>`/`<Figure>` — none of these reach
+  keyed-float validation, so this diagnostic flags them separately.
+
+### 8. Optional: enable standalone HTML / print lesson exports
 
 No action required to keep building. To opt in, add to
 `content/course.config.ts`:
@@ -89,7 +558,7 @@ lessonExports: {
 canonicalBaseUrl: 'https://your-course.example.com',
 ```
 
-### 4. Optional: turn on strict numbering cross-checks
+### 9. Optional: turn on strict numbering cross-checks
 
 `remarkNotation`'s new `strict: true` option — recommended via
 `createRemarkNotationOptions(manifest, { strict: true })` — fails the build on