explico 0.7.0 → 0.11.0

package/docs/authoring/migrating.md

@@ -33,6 +33,1328 @@ required config block throws with the section of this file to read.
 
 ---
 
+## 0.10.0 → 0.11.0
+
+**Course changes are required.** Figures and diagrams no longer compact.
+`disclosure.diagrams`, `<Diagram defaultOpen>` and `<Diagram rememberState>`
+are removed, and each one fails the build until you delete it (steps 2–3).
+The rest is additive or affects only readers: `<Fold>`, a lab's `tools`
+slot and live caption end, the short caption shown in the caption line (rule
+S9, a guide), the "Figures and tables" page, unnumbered `[card=meta]`
+sections, and explanation cards that pin, dock, drag and are remembered.
+Nothing in `astro.config.mjs` changes. The manifest schema moves from v23 to
+v24.
+
+**Coming from 0.8.0, the last version on npm before this one.** 0.9.0 and
+0.10.0 were tagged but never published to npm, so a course that installs
+from npm goes from 0.8.0 straight to 0.11.0. Install 0.11.0 once (step 1).
+Then apply the course changes of "0.8.0 → 0.9.0" and "0.9.0 → 0.10.0" below,
+oldest first, and skip their "Update the dependency" steps. Finish with this
+section. Three steps of the 0.10.0 section read differently at 0.11.0. Apply
+them in this form:
+
+- Its step 3 puts `diagrams: { defaultOpen: true }` in `disclosure`, and its
+  step 4 adds `diagrams` to the settings schema. Leave `diagrams` out: it now
+  fails the build (step 2 below). `disclosure.figures` now sets whether a
+  lab's tools start open, not whether a figure starts compacted.
+- Its step 14 describes the compaction markup of a figure and a diagram
+  (`.float-caption__toggle`, "a compacted float keeps the caption line").
+  That markup is gone (step 9 below).
+- Its step 5 lists the diagnostic groups for `compile-manifest.ts`. Add
+  `folds` to them as well (step 4 below).
+
+Work in this order: steps 1–5 fix the wiring, so that `pnpm validate:content`
+runs; steps 6–8 are content, and steps 7–8 are conditional; steps 9–11 apply
+only to a course whose own CSS, tests, code or stored keys reach into the
+engine; step 12 is optional; step 13 records the content changes; step 15 is
+the check.
+
+### 1. Update the dependency
+
+```bash
+pnpm add -D explico@0.11.0
+```
+
+### 2. Delete `disclosure.diagrams` (the build fails until you do)
+
+A diagram no longer folds by itself, so it has no default. `normalizeDisclosure`
+throws on the key and names the edit to make, which stops both
+`pnpm validate:content` and `astro build`. Delete `diagrams` from the
+`disclosure` block of `content/course.settings.json`, or from
+`CourseConfig.disclosure` in `content/course.config.ts`, wherever the course
+keeps it.
+
+`disclosure.figures` stays, but it now means something else: whether a
+**lab's tools** start open (the `tools` slot, step 12). A figure's picture
+and caption always show. A course that set `figures: { defaultOpen: false }`
+to start its figures compacted now starts every lab's tools folded instead.
+Delete the setting unless that is what you want. To let a reader fold a
+figure away, put it in a `<Fold>` (step 12) or a collapsible section.
+
+New and optional: `disclosure.folds: { defaultOpen }`, whether a `<Fold>`
+starts open. The default is closed.
+
+**Only if the course describes its settings in a JSON Schema** (the
+playground's `course.settings.schema.json`, where `disclosure` has
+`additionalProperties: false`), remove `diagrams`, add `folds` and
+re-describe `figures`:
+
+```json
+"folds": {
+  "title": "Folds",
+  "description": "A `<Fold>` folds like a memo, with no marker, letter or frame: a stretch of content — most often a figure or diagram — a reader can fold away. Default: closed.",
+  "$ref": "#/definitions/initialState"
+},
+"figures": {
+  "title": "A lab's tools",
+  "description": "Whether a lab's tools (the sliders, fields and live equation after a `<Figure>`'s caption) start open. The figure's picture and caption always show. Default: open.",
+  "$ref": "#/definitions/initialState"
+}
+```
+
+The `rules` and `courseRules` properties `$ref` the schemas in
+`node_modules/explico/dist/rules/`, so rule S9 (step 6) needs no edit there.
+
+### 3. Delete `defaultOpen` / `rememberState` from every `<Diagram>`
+
+```bash
+rg -n -U '<Diagram\b[^>]*\b(defaultOpen|rememberState)\b' content src
+```
+
+Both props are removed. In a lesson, each one fails `pnpm validate:content`
+(`dia-removed-prop`). A `<Diagram>` rendered by a wrapper component throws
+when its page builds, and the manifest scan cannot see inside the wrapper.
+Check every wrapper `.astro` file, including one that passes its own props
+through to `<Diagram>`. To let a reader fold a diagram away, put it in a
+`<Fold>` (step 12) or a collapsible section.
+
+`<Figure defaultOpen>` and `<Figure rememberState>` stay. They now set that
+figure's lab tools (step 12), and they do nothing on a figure without a
+`tools` slot.
+
+### 4. `scripts/compile-manifest.ts`: add the `folds` group
+
+The manifest has a new diagnostics group, `diagnostics.folds`
+(`fold-unnamed`, step 12). Add it to both the warnings loop and the errors
+loop, next to `examples`:
+
+```ts
+const { /* … */ examples, folds, knowledge, rawFloats, config, waivers } =
+  manifest.diagnostics;
+
+// In BOTH loops over [['equations', equations], …]:
+  ['examples', examples],
+  ['folds', folds],
+  ['rawFloats', rawFloats],
+```
+
+Without it, a `<Fold>` with nothing to name its bar does not fail
+`validate:content`, though the page build still fails on it. `content check`,
+`content diagnostics` and `content status` read the group already.
+
+### 5. The manifest schema is now v24
+
+It was v23 in 0.10.0. `pnpm validate:content` rewrites `build/manifest.json`,
+so this step matters only for code that reads the manifest or pins its
+version:
+
+- **v24**: `disclosure` loses `diagrams` and gains `folds`, and
+  `diagnostics.folds` is new. When the course has a top-level
+  `content/docs/figures-and-tables.mdx`, the Reference group in `sidebar` also
+  lists "Figures and tables". The item has the same shape as the others.
+
+### 6. Captions: rule S9, and the short caption that now shows
+
+A float's `short` caption now opens its caption line as a bold title:
+"**Sampled flight data.** Position, velocity, …". It also names the float in
+a folded section's "Hidden here" line, in a copied link, and on the "Figures
+and tables" page. Nothing fails, but two kinds of float now read badly:
+
+1. **A long `caption` that restates the `short` one reads twice**, for
+   example "**Sampled flight data.** Sampled flight data: position, …". Rule
+   S9 (`structure-rules.md#s9`) says the long caption continues from the
+   short caption's name. It says what the float shows — its subject, its
+   marks and symbols, the case shown — and at most the one thing to notice.
+2. **A figure, table or diagram without `short`** has no title, and the
+   "Figures and tables" page lists it by its long caption, greyed out. Rule
+   S9 and `components.md` now ask for a `short` on every one. Find them:
+
+   ```bash
+   rg -n -U --pcre2 '<(Figure|Table|Diagram)\b(?![^>]*\bshort=)[^>]*>' content/docs
+   ```
+
+Rule S9 also moves text out of figures. A figure holds no running text. The
+argument drawn from a figure is lesson text after it, and a lab's
+instructions are the first line of its tools (step 12). Rule S9 is a guide:
+review-only, on `build/rules-in-effect.md` and `pnpm content rules`. Switch it
+off with `rules.S9.enabled: false` if it does not fit the course.
+
+### 7. Only if a lesson has a `[card=meta]` section: section numbers change
+
+```bash
+rg -n '^#{2,6} .*\[card=meta\]' content/docs
+```
+
+A `[card=meta]` section is now unnumbered, like References, and so is every
+heading inside it. The sections after it no longer count it: in a chapter
+that opens with one, § 1.2.2 becomes § 1.2.1. Float, check and example
+numbers do not change.
+
+- `[[sec-…]]` references print from the manifest and need no edit. A
+  reference to the meta section itself now prints its title in quotes
+  ("What this chapter uses"), since the section has no number.
+- Prose, captions and tests that type a section number, and number-form
+  fragments (`#sec-1.2.2`) past the meta section, now point at a different
+  section. Cite the section by key, or update the number.
+- If the section should keep its number, drop the `=meta` (a plain `[card]`
+  accent card is numbered) or make it an aside (`:::note[Title]`).
+
+Record the renumbering in `content/CHANGELOG.md` (step 13), because readers
+see new numbers.
+
+### 8. Only if the course has its own `Fold` component or a `figures-and-tables` page
+
+```bash
+rg -n '<Fold\b|import Fold\b' content src
+ls content/docs/figures-and-tables.* 2>/dev/null
+```
+
+- **`<Fold>` is now an engine name.** A hit that imports
+  `explico/components/fold/Fold.astro` is the engine's own component; any
+  other `Fold` is the course's. The manifest reads every `<Fold>` in a
+  lesson as the engine's, whatever it is imported from. The equations and
+  floats inside it are numbered in the lesson's sequence, and a `<Fold>` with
+  no `label` and no numbered float inside fails `fold-unnamed`. To keep the
+  old behaviour, import the course's own component under another name
+  (`import CourseFold from …`, `<CourseFold>`).
+- **A top-level `content/docs/figures-and-tables.mdx`** (or `.md`) now adds
+  "Figures and tables" to the sidebar's Reference group. If the course
+  already has a page at that path for something else, rename it, or make it
+  the float index (step 12).
+
+### 9. Only if your course CSS, browser tests or scripts reach into engine markup
+
+```bash
+rg -n 'float-caption__toggle|keyed-figure__details|diagram__details|float-compact|--float-toggle-|diagram-toolbar|diagram-(expand|shrink)-(button|icon)|data-diagram-(details|body|toolbar)|block-badge__icon|table-overflow-expand-btn|keyed-table__caption--paginated|data-panel-pin|citation-panel-pin|notation-popup-close|[0-9] questions|Link copied|Hidden here' src content tests
+```
+
+- **Figure and diagram.** Neither one compacts. `.float-caption__toggle`,
+  `.keyed-figure__details`, `.diagram__details`, `.float-compact`,
+  `.float-compact__summary` and the `--float-toggle-size`,
+  `--float-toggle-gutter` and `--float-toggle-room` tokens are gone. A
+  figure's picture is `.keyed-figure > .keyed-figure__body`. The caption line
+  can open with `b.float-caption__title` (the short caption) and end with a
+  `.float-tools` row of boxed `.float-tool` buttons. A `<Figure>`'s caption
+  line ends with `span.float-caption__state[data-figure-state]`, outside
+  `.float-caption__text`. Print shows a figure's picture and caption, never
+  a lab's tools, and never a "compacted" note.
+- **A diagram's widen button** is now
+  `figcaption .float-tools > [data-diagram-expand]`, and shows only while the
+  graph is wider than the column. `.diagram-toolbar`, `.diagram-expand-button`,
+  `.diagram-expand-icon` and `.diagram-shrink-icon` are gone.
+- **Table.** The widen button ↔ and the fold button sit together in the
+  caption line's `.float-tools`. The fold toggle reads ⌃ / ⌄ (it read ▴ / ▾),
+  keeps `.keyed-table__pagination-toggle`, and is no longer a
+  `.table-overflow-expand-btn`. `.keyed-table__caption--paginated` is gone.
+  The "… N more rows …" label is centred on the part of the table on screen.
+- **Knowledge check and example set.** The icon is `.block-heading__icon`,
+  before `.block-heading__title` (it was `.block-badge__icon`, inside the
+  badge). The badge (`.block-badge`: the word and `.block-heading__number`)
+  sits in the card's top-right corner. A check's score is empty until the
+  first answer, then reads "2 of 3 correct" under the questions. The
+  "3 questions" line is gone.
+- **Explanation cards** (notation, `[[key]]` terms, citations,
+  abbreviations, and equation, table, figure, diagram and section
+  references) are all clones of `HoverPanel.astro`'s `<template>`, run by one
+  card manager. The header row holds the grip `[data-card-grip]` ("Move
+  card"), Side `[data-card-side]`, Pin `[data-card-pin]` (`aria-pressed`) and
+  × `[data-card-close]`. A note line `[data-card-note]` sits under it. A
+  dragged card has `data-card-mode="moved"`. `[data-panel-pin]`,
+  `.citation-panel-pin` and `.notation-popup-close` are gone.
+  `.notation-popup[data-popup-key="…"]` still finds a notation card. For
+  behaviour tests:
+  - A click or tap on a trigger pins its card and never navigates. The
+    card's "Go to …" link navigates, and ends in ↑ / ↓ (same page), → (another
+    page) or ↗ (a citation's source); every one used to end in ↗. A reference
+    whose target is already fully on screen still highlights it and
+    navigates.
+  - A click inside a card never closes it. A hovered card no longer closes a
+    pinned one, and several cards can be open at once. Escape closes the
+    newest card first. A `[[key]]` term shows no browser tooltip.
+  - A page restores the cards a reader kept on it, from local storage. A
+    fresh browser context starts empty, but a test that pins a card and then
+    reloads or goes back sees the card again.
+- **Copy link and "Hidden here".** The confirmation names what was copied:
+  "Link copied · Figure 2.1.1 · Projectile trajectory explorer", or a
+  section's, check's or example set's title. Where the browser has
+  `ClipboardItem`, a `text/html` link goes on the clipboard next to the URL. A
+  folded section's line names its floats first: "Hidden here: **Figure
+  2.1.1** Projectile trajectory explorer, 2 paragraphs". A heading's chain
+  icon has the title "Copy link" where a click copies.
+- **Layout.** The header is 3rem tall at every width (`--sl-nav-height`), with
+  a 2rem search box. Check course header content sized for 3.5rem or 4rem.
+  Headings are smaller: `global.css` sets `--sl-text-h1`…`--sl-text-h5`, and
+  course CSS that sets them wins. The navigation and "On this page" rail
+  cover a card that reaches them. Accent and meta cards have less padding, a
+  lesson's first block adds no top margin, and Previous / Next stay side by
+  side down to a 26rem column. The notation panel's help text is inside the
+  panel. Re-record screenshots.
+- **A figure's preview card** shows a still copy of its picture, a lab's
+  plot included (controls disabled, ids prefixed). A lab no longer needs
+  `previewable={false}`.
+
+### 10. Only if course code imports engine internals
+
+- `components/hover-panel.ts` (`createHoverPanel`, `claimActiveSurface`,
+  `releaseActiveSurface`), `components/popup-stack.ts` and
+  `components/disclosure/float-compaction.ts` are gone. A layer of the
+  course's own registers a `CardSource` with `registerCardSource`. An overlay
+  that must clear the hovered cards calls `closeTransientCards()`. Both come
+  from `explico/components/card-manager.ts`.
+- `countHiddenContent` in `components/starlight/section-summary.ts` is gone.
+  Use `collectHiddenContent`, then `hiddenContentParts`.
+- `PreferenceStore` gains an optional `remove(key)`. A course's own store
+  still fits the interface. Implement `remove` so that closing a page's last
+  card forgets the page.
+
+### 11. Reader-side state
+
+A figure's and a diagram's remembered compaction (`figure:<id>`,
+`diagram:<id>`) is no longer read, so a returning reader sees every figure
+and diagram open. The new keys are `figure-tools:<figure id>` (a lab's
+tools), `section:fold-…` (a `<Fold>`), `explico:cards:<page path>` (the cards
+kept on a page) and `explico:layout:keep-article-left`. You need to add them
+only if the course clears preference keys by name.
+
+### 12. Optional: features to adopt
+
+- **`<Fold>`** (`explico/components/fold/Fold.astro`) lets a reader fold away
+  a stretch of the lesson where it stands, most often one figure, diagram or
+  table. It has no heading, number, marker or frame:
+
+  ```mdx
+  import Fold from 'explico/components/fold/Fold.astro';
+
+  <Fold>
+  <Diagram id="launch-angle-dependency" short="Inputs to the launch-angle search" caption="…" />
+  </Fold>
+  ```
+
+  The bar is the `label`, or else the numbers and short captions of the
+  numbered floats inside. A fold with neither fails `fold-unnamed`. A float
+  the bar names drops its own bold caption title inside the fold. The fold's
+  first state comes from `defaultOpen`, or else `disclosure.folds` (closed);
+  `rememberState={false}` keeps the default on every visit. The equations
+  and floats inside keep their numbers.
+- **A lab's tools.** In a `<Figure>`, the default slot is the picture. Give the
+  controls island `slot="tools"`, or wrap the controls in
+  `<Fragment slot="tools">`. The tools render after the caption line in a
+  tray with a fold button. They start as `defaultOpen` says, or else as
+  `disclosure.figures` says, and they never print. The picture and the tools
+  are separate islands, so they share their values through the course's own
+  store (the playground's `content/labs/useStoredState.ts`). `global.css`
+  styles `.lab-tools`, `.lab-instruction` (the tools' first line, saying
+  what to do) and a `.lab-shell` in the tray. A figure without the slot
+  renders as before.
+
+  ```mdx
+  <Figure id="launch-angle-explorer" short="Range vs. launch angle explorer" caption="…">
+  <LaunchAnglePlot client:visible />
+  <LaunchAngleTools slot="tools" client:visible />
+  </Figure>
+  ```
+
+- **The caption's live end.** `setFigureState(element, runs)` from
+  `explico/components/figure/figure-state` writes the case the plot shows
+  at the end of the caption line. `element` is any element of the lab's
+  inside the figure. `runs` holds strings, `{ text, italic: true }` and
+  `{ sub }` items, never HTML:
+  `setFigureState(host, ['Shown for ', { text: 'v', italic: true }, { sub: '0' }, ' = 20 m/s'])`.
+  The clause prints with the caption.
+- **Drop `previewable={false}`** from labs. The preview card now copies the
+  plot as drawn, and falls back to the caption and number when the plot is
+  not drawn yet.
+- **The "Figures and tables" page** is LaTeX's `\listoffigures` and
+  `\listoftables` in one. Create `content/docs/figures-and-tables.mdx`:
+
+  ```mdx
+  ---
+  title: Figures and tables
+  description: Every numbered figure, table and diagram of the course, by part and chapter.
+  ---
+
+  import FloatIndex from 'explico/components/FloatIndex.astro';
+
+  <FloatIndex />
+  ```
+
+  It lists every numbered figure, table and diagram that has an `id`. A
+  diagram drawn by a wrapper component is listed when the lesson imports the
+  wrapper as `Diagram` and passes it `id`, `short` and `caption`
+  (`<Diagram id="…" short="…" caption="…" />`). That is also how the diagram
+  gets a number and a `[[dia-…]]` key.
+- **Cards beside the article, dragged cards and remembered cards** need no
+  wiring.
+
+### 13. Record the content changes (rules C1–C3)
+
+Steps 2, 6, 7 and 12 edit `content/`. A settings edit is a content change
+too. Add bullets under `## [Unreleased]` in `content/CHANGELOG.md` (rule C1):
+the dropped `disclosure.diagrams`, new and rewritten captions, renumbered
+sections, and new folds or pages. Bump `about.version` per rule C2 when you
+release, and keep it equal to the newest heading (rule C3).
+
+### 14. Fixes that need no action
+
+A section, memo or fold that the browser opens itself, for find-in-page or
+a linked fragment, now opens properly and stays open. A reference into a
+closed memo or folded section opens its preview card and marks the fold's
+bar. A figure's preview card shows an SVG sized only by its `viewBox`. A
+touch screen no longer draws a badge icon over its word. A worked example's
+closing display equation loses its stray bottom margin.
+
+### 15. Verify
+
+```bash
+pnpm validate:content        # run twice: the first run regenerates build/resolution/*
+pnpm content rules           # rule S9 is on the list now
+pnpm content warnings
+pnpm content check --changed
+astro check
+astro build
+```
+
+Then run the course's browser tests, if it has any, and update the selectors
+and texts from step 9. A course with its own gate script that runs these
+stages (explico's is `scripts/agent/verify`) runs that instead.
+
+## 0.9.0 → 0.10.0
+
+**Course changes are required.** This release carries four lines of work: the
+rule catalog (per-rule settings and switches, waivers, the rules-in-effect
+page, a course's own rules), the rule restructuring (six rules folded into
+four), accents and styled letters as symbols of their own, and titles and
+containers (outline numbering, one caption pair per float, one collapse
+model, heading discipline, kind badges). Several props are removed with no
+alias period, and several rules now fail the build where they did not.
+
+Work in this order: steps 1–6 fix the wiring, so that `pnpm validate:content`
+runs and reports; steps 7–13 clear what it reports; steps 14–16 are
+conditional or optional; step 17 is the check. Where a diagnostic code leads
+to a step, the step names it. The manifest schema moves from v16 to v23 in
+seven bumps (step 6).
+
+### 1. Update the dependency
+
+```bash
+pnpm add -D explico@0.10.0
+```
+
+0.10.0 was never published to npm. Coming from npm's 0.8.0, install 0.11.0
+instead, and read the "Coming from 0.8.0" note of "0.10.0 → 0.11.0" first.
+
+### 2. `astro.config.mjs`
+
+Make these edits; the result below shows all of them together.
+
+1. **Add `remarkAsides` last in `markdown.remarkPlugins`.** Starlight turns
+   `:::note` / `:::tip` / `:::caution` / `:::danger` into asides only under its
+   own `src/content/docs/`, so in a course's `content/docs/` they rendered as a
+   bare `<div>`. `remarkAsides` hands each one to Starlight's `<Aside>`. No
+   check fails without it; the asides just stay unstyled. Do **not** add
+   `content/docs/` to Starlight's `markdown.processedDirs` instead: every
+   heading would get two anchors.
+2. **Drop the `disclosureDefaults` mapping.** `CourseConfig.disclosureDefaults`
+   is gone (step 3). If the file builds a `resolvedCourseConfig = { ...courseConfig,
+   disclosureDefaults: { notation, references } }`, delete it and pass
+   `courseConfig` itself to both `loadManifest` and `explicoContentRefresh`.
+3. **Read the heading and References defaults from `courseConfig.disclosure`.**
+   `rehypeHeadingAnchors` takes `{ defaultCollapsible: courseConfig.disclosure }`
+   (it reads `sections` and `subsections`), and `remarkCitation` takes
+   `defaultOpen: courseConfig.disclosure?.references?.defaultOpen === true`.
+   A local `defaultCollapsible` object moves into the `disclosure` block of
+   step 3.
+4. **Wire `LayoutPageTitle.astro` as Starlight's `PageTitle` override.** It puts
+   the part's name, linked, above every chapter title. Optional, but it is the
+   one route to a part page (step 15) that does not depend on the sidebar.
+5. **Check that `PageSidebar` is `LayoutPageSidebar.astro`.** "On this page"
+   lists knowledge checks and worked-example sets only through it.
+6. **Only for a course deployed under a subpath** (an Astro `base`, such as a
+   GitHub Pages project site): pass `base` to `createRemarkNotationOptions` and
+   to `remarkAbbreviations`. Without it, the links these plugins write (a
+   symbol's glossary card, a cross-lesson reference, an abbreviation) are
+   root-relative and 404.
+
+```js
+import remarkAsides from 'explico/reference/remark-asides.mjs';
+import rehypeHeadingAnchors from 'explico/reference/rehype-heading-anchors.mjs';
+import { courseConfig } from './content/course.config.ts';
+
+const disclosure = courseConfig.disclosure ?? {};
+const manifest = await loadManifest(courseConfig);
+
+// … integrations:
+explicoContentRefresh(courseConfig, manifest),
+starlight({
+  // …
+  components: {
+    Footer: 'explico/components/starlight/LessonFooter.astro',
+    PageSidebar: 'explico/components/starlight/LayoutPageSidebar.astro',
+    PageTitle: 'explico/components/starlight/LayoutPageTitle.astro',
+    // … Header, Sidebar, SocialIcons as before
+  },
+}),
+
+// … markdown.remarkPlugins:
+[remarkNotation, createRemarkNotationOptions(manifest, { strict: true, base })],
+[remarkCitation, {
+  sources: manifest.sources,
+  defaultOpen: disclosure.references?.defaultOpen === true,
+}],
+[remarkAbbreviations, { abbreviations: manifest.abbreviations, base }],
+remarkAsides, // last
+
+// … markdown.rehypePlugins:
+[rehypeHeadingAnchors, { defaultCollapsible: disclosure }],
+```
+
+**Only if your course overrides `Footer` with its own component** instead of
+`LessonFooter.astro`: read the notation panel's first state from
+`manifest.disclosure.notation.defaultOpen` (it was
+`manifest.disclosureDefaults.notation`), pass `KeyedFloatEnhancer` its new
+`aliases` prop (`manifest.numbering.aliases`, step 11) and `NotationLayer` its
+new `suspended` prop (the page's `notation.suspend`, step 10), as
+`LessonFooter.astro` does.
+
+### 3. `CourseConfig` (`content/course.config.ts`)
+
+1. **`disclosureDefaults` → `disclosure`.** Every collapse default is now one
+   block, in the shape of the course settings' `disclosure` block. Move the
+   old `disclosureDefaults.notation` / `.references` booleans and the
+   `sections` / `subsections` objects from `astro.config.mjs` into it. Every
+   key is optional; the values below are the defaults, which match what each
+   kind had hardcoded before:
+
+   ```ts
+   disclosure: {
+     sections: { collapsible: false, defaultOpen: true },    // ## headings
+     subsections: { collapsible: false, defaultOpen: true }, // ### and deeper
+     notation: { defaultOpen: false },   // was disclosureDefaults.notation
+     references: { defaultOpen: false }, // was disclosureDefaults.references
+     knowledgeChecks: { collapsible: true, defaultOpen: true }, // new
+     memos: { defaultOpen: false },        // new
+     figures: { defaultOpen: true },       // new
+     diagrams: { defaultOpen: true },      // new
+     workedExamples: { defaultOpen: false }, // new
+     tables: { truncateAfter: 6 },         // new: rows shown, half from each end
+   },
+   ```
+
+   If the course keeps its settings in a JSON file and spreads it into
+   `CourseConfig`, stop splitting `disclosure` off: pass the block through as
+   it is. A course that calls `normalizeDisclosureDefaults` switches to
+   `normalizeDisclosure` (with `DISCLOSURE_DEFAULTS`); both are exported from
+   `explico/compiler/course-config`.
+2. **Move the deprecated top-level blocks into `rules`.** `operators`,
+   `romanLabels` and `abbreviations` still work with a `config-deprecated-key`
+   warning; move each `{ allow, deny }` block unchanged to `rules.N8`,
+   `rules.N10` and `rules.N14` (rule N8, rule N10, rule N14). Setting both
+   the old key and its replacement is an error. The old keys go away in a later
+   MINOR.
+3. **Only if you took `partPages` from `main` before this release:** it is
+   `rules.S2` now (`bridgeMinWords`, `bridgeMaxWords`, `scopeMinWords`,
+   `scopeMaxWords`), with no alias.
+4. **Optional new fields**, each with the default that applies when it is left
+   out:
+   - `numbering`: `{ sections: { show: true, depth: 4 }, floats: "chapter",
+     aliases: true }` (step 11).
+   - `blockLabels`: `"icon-word"`, or `"icon"` for a knowledge check's and an
+     example set's badge without its word (the word stays for a screen
+     reader).
+   - `rules`: per-rule switches and settings (step 12).
+   - `courseRules`: the course's own `X` rules (step 15).
+   - `CoursePart.overviewLabel`: renames a part's `Overview` sidebar row.
+
+### 4. Course settings schema (only if your course publishes one)
+
+A course that describes its settings in a JSON Schema (the playground's
+`course.settings.schema.json`) points two properties at the schemas
+`pnpm build` now ships, so the rule blocks never need a copy:
+
+```json
+"rules": { "$ref": "../node_modules/explico/dist/rules/rules.schema.json" },
+"courseRules": { "$ref": "../node_modules/explico/dist/rules/course-rules.schema.json" }
+```
+
+Add `numbering`, `blockLabels`, and the new `disclosure` keys
+(`knowledgeChecks`, `memos`, `figures`, `diagrams`, `workedExamples`,
+`tables.truncateAfter`) with the defaults in step 3; the playground's
+[`course.settings.schema.json`](https://github.com/danieltuzes/explico/blob/v0.10.0/playground/content/course.settings.schema.json)
+has each with a title and a description. If you use explico's settings form
+editor (`tools/vscode-settings-editor/` in the explico repository), reinstall
+it from a v0.10.0 checkout (`node tools/vscode-settings-editor/install.mjs`):
+an older build shows `rules` and `courseRules` as text fields reading
+`[object Object]`.
+
+### 5. Course scripts
+
+1. **`scripts/compile-manifest.ts`** — three new diagnostics groups, and the
+   rules-in-effect page. Without `examples` in the group lists, an `ex-…`
+   error does not fail `validate:content` (the page build still fails on it).
+
+   ```ts
+   import { createRunLog, diagnosticLine } from 'explico/compiler/logging';
+   import { writeRulesInEffect } from 'explico/rules/in-effect';
+
+   const { /* … */ checks, examples, knowledge, rawFloats, config, waivers } =
+     manifest.diagnostics;
+
+   // Add ['examples', examples] to BOTH the warnings loop and the errors loop
+   // over [['equations', equations], …, ['checks', checks], …].
+
+   // The course settings themselves: a deprecated block, a retired rule.
+   for (const warning of config) {
+     console.warn(log.warning('config', `[${warning.code}] ${warning.message}`));
+   }
+   // Per-place waivers: a stale one warns; a malformed or invalid one fails.
+   for (const warning of waivers.filter((d) => d.severity === 'warning')) {
+     console.warn(log.warning('waivers', diagnosticLine(warning)));
+   }
+   // … and next to the other failures:
+   for (const issue of waivers.filter((d) => d.severity === 'error')) {
+     fail('waivers', diagnosticLine(issue));
+   }
+
+   // Optional: format math findings with the owning rule's ID,
+   // `[N9 prose-notation] file:line: …`.
+   const formatMathIssue = (issue: (typeof math)[number]) => diagnosticLine(issue);
+
+   // The page an agent reads before drafting (step 12).
+   writeRulesInEffect(manifest);
+   ```
+
+2. **`scripts/content.ts`** — add the `rules` verb: `contentRules(manifest,
+   parseRulesFilter({ element, enforcement }))` from `explico/compiler/cli`,
+   taking `--element <e>[,<e>]`, `--enforcement script|partial|guide|locked`
+   and `--json`. `content status` can print the new `keyedExamples` count.
+3. **`.gitignore`** — `build/rules-in-effect.md` is regenerated on every run.
+   Ignore it unless `build/` is ignored already.
+4. **Tools that read `content … --json`.** Each diagnostic now carries its
+   owner as `rule`. A math finding's `code` is `math:<code>` for every finding
+   (`math:prose-notation`, `math:unresolved-glyph`, …), where it used to be
+   `math:prose` or `math:structure` for code-less ones.
+   `MathGateDiagnostic.code` is required in the type.
+5. **Code that imports engine internals.** `RuleEntry.retired` is gone
+   (`retiredRules()` / `retiredRule(id)` in `explico/rules/catalog`);
+   `proseOnly` takes `{ keepMath }`; `gateProseNotation` /
+   `gateProseNotationInAssessments` take `{ allowSpelledUnits }`;
+   `resolveMathGlyphs` takes `{ suspended }` as a third argument, and an
+   `unresolved` item may carry `suspended` or `font`. A lab island imports
+   `slotPlaceholder` / `RenderedLabMath` from `explico/reference/lab-math-slot`
+   (`render-lab-math` still re-exports both, but pulls the server-only KaTeX
+   chain into the browser graph and makes Vite warn about `node:fs`).
+
+### 6. The manifest schema is now v23
+
+It was v16 in 0.9.0. `pnpm validate:content` rewrites `build/manifest.json`,
+so this step is only for code that reads the manifest itself:
+
+- **v17** (additive): `parts` — every part with its chapters in reading order
+  and its overview page; `sidebar[].items` is one mixed list of lesson slugs
+  and `{ label, link, attrs? }` entries (`SidebarItem`), and `SidebarGroup` is
+  one interface instead of a union; `lessons[].studyMinutes`,
+  `parts[].studyMinutes`.
+- **v18** (additive): `rules` (`disabled`, each rule's effective settings);
+  `diagnostics.config`; `diagnostics.waivers`; every math-gate finding carries
+  a `code`.
+- **v19** (additive): `rules.course`, the course's own rules;
+  `MathGateDiagnostic.context` gains `'course'`.
+- **v20**: `numbering`; `lessons[].headings` (`slug`, `text`, `level`,
+  `number?`); `lessons[].numbering.prefix`. Under the default chapter scope,
+  the per-kind counts in `lessons[].numbering`, which used to carry a part's
+  running total, are all 0.
+- **v21**: `lessons[].equations` / `.tables` / `.figures` / `.diagrams` and the
+  kinds' `labels` carry `short` and, for a JSX float, `caption`
+  (`ManifestLessonFloat`).
+- **v22**: `disclosure` (every default applied) replaces
+  `disclosureDefaults`.
+- **v23**: `examples`, `lessons[].examples`, `lessons[].numbering.examples`,
+  `diagnostics.examples`; `lessons[].knowledgeChecks[].title`;
+  `lessons[].titledBlocks`; `blockLabels`.
+
+### 7. Rename the removed float props (the build fails until you do)
+
+Every float is named by one caption pair: a long `caption` and an optional
+`short` caption, LaTeX's `\caption[short]{long}`. The other name props are
+removed outright, and each fails with the edit to make. Find them:
+
+```bash
+rg -n -U '<(Figure|Diagram|Memo|CompactExamples)\b[^>]*\b(title|label|description|summary)=' content src
+```
+
+1. `<Figure title="X" caption="Y">` → `<Figure short="X" caption="Y">`, or
+   drop `title` when X only repeats the caption (`fig-removed-prop`).
+2. `<Diagram label="X">` → `<Diagram caption="X">`, plus `short` for a long
+   caption; `<Diagram title>` fails too (`dia-removed-prop`). Check wrapper
+   `.astro` components as well: the manifest scan cannot see inside them, but
+   the component throws when it renders.
+3. `<Memo title="X" description="Y">` → `<Memo short="X" caption="…">`.
+   `caption` is required and is now the memo's bar, so write it as bar text;
+   `short` is optional (the marker's tooltip). `remarkMemo` fails the old props.
+4. `<CompactExamples summary="X">` → `<CompactExamples id="…" short="X">`.
+   Both are required now (`ex-missing-prop`; `summary` is `ex-removed-prop`):
+   `id` is lowercase kebab-case and anchors the set as `#ex-‹id›`; `short` names
+   the set's topic ("Speeding up and braking"), since the engine draws the
+   "Example" badge and the number before it. `short` no longer defaults to
+   "Worked examples", and `hint` has no default.
+
+Rule S1 now measures the `short` caption (of a `Figure`, `Diagram`, `Table`,
+`Memo` and `CompactExamples`), a display equation's `\caption{…}` and a
+`ShortNote`'s `title`, and never a long `caption`; a heading's `[collapsed]`
+/ `[card]` markers no longer count toward it. A `Figure title` that passed rule
+S1 passes the same way as `short`.
+
+### 8. Assessment titles and labs
+
+1. **Assessment titles name the topic alone.** A knowledge check's heading is
+   now the engine's badge ("Knowledge check"), its number, then the assessment
+   file's `title`, so a title that repeats the kind reads twice ("Knowledge
+   check 1.1.1 Velocity check"). In each `content/assessments/*.json`, drop
+   "check" / "Knowledge check" from `title`.
+2. **A lab carries no title or caption of its own**; the `<Figure>` around it
+   names the whole. In a lab inside a `<Figure>`, delete its own heading and
+   the `aria-labelledby` that names it, and turn an inner
+   `<figure><figcaption>` into a plain element, moving the sentence into the
+   `<Figure caption>`. The engine's `.lab-chart-figure` styles are gone; draw
+   the chart in a plain `.lab-chart`.
+3. **Rule V3 is narrowed.** It keeps the hydrated island, the `labMathScope` /
+   `renderLabMath` / `\slot{}` seam and labelled controls, and no longer asks
+   for an accessible name or description (`ariaLabel` / `ariaDescription` /
+   `ariaHidden`) or a `<details>` text alternative: the `<Figure>` caption is
+   the name. Nothing in a build changes; keep or drop what you wrote for the
+   old rule V3.
+
+### 9. Headings: rule S6 and rule S7 (errors)
+
+Both read a lesson's outline, the same top-level headings the section numbers
+count. A heading inside a component and a memo's bar are not in it; a
+`<AssessmentSet />` and a `<CompactExamples>` are, as `##` headings.
+
+- **Rule S6** (`heading-skip`): headings descend one level at a time. A lesson
+  body starts at `##` (the frontmatter `title` is the page's one `#`, so a `#`
+  in the body fails), and `##` → `####` fails; going back up is free. A `###`
+  → example set → `####` is a skip too. Fix it by making the heading one level
+  deeper than the one before it.
+- **Rule S7** (`heading-adjacent`): a heading is followed by body content,
+  never directly by another heading, and a check or an example set counts as a
+  heading. Write a sentence between the two, or delete a heading that only
+  announces the block under it (`## Check yourself` above `<AssessmentSet />`,
+  `## Try it` above `<CompactExamples>`).
+
+Otherwise waive one place with `{/* explico-allow S6: reason */}` on the line
+above the heading, or switch a rule off with `rules.S6.enabled: false` /
+`rules.S7.enabled: false`. For parallel items deep in the outline,
+`docs/authoring/structure.md` § Structure from the bottom up recommends run-in
+labels or a description list instead of deeper headings.
+
+### 10. Math and prose: what now fails or warns
+
+Run `pnpm validate:content` and work through these by code.
+
+1. **Rule N9, `spelled-unit` (error).** A unit written as a word after a
+   number, around `per`, or with `square` / `cubic` / `squared` / `cubed`
+   fails, in lesson bodies and assessment `prompt` / `explanation`: "a time
+   of 4 seconds" → `$4\ \text{s}$`, "30 degrees above the horizontal" →
+   `$30^{\circ}$`, "$x = 3$ meters" → `$x = 3\ \text{m}$`. The message gives
+   the math. A unit named on its own ("measured in meters") passes, and rule
+   N9's old carve-out for a spelled-out unit in flowing prose is gone. Rewrite
+   it, waive a defining sentence with `{/* explico-allow N9: reason */}`, or
+   list unit words the course keeps in `rules.N9.allow`.
+2. **Rule N12, `math-trailing-punctuation` (error).** A `.`, `,`, `;` or `:` is
+   never the last visible thing in a `$…$` / `$$…$$` span, or in a row before
+   `\\`; move it out after the closing `$`. A trailing decimal point (`5.`) and
+   a typed `...` fail too; the decimal-point exception is gone. Dotted notation
+   abbreviations (`a.e.`, `i.i.d.`, …) pass; edit that list with
+   `rules.N12.allow` / `rules.N12.deny`, waive a place, or switch rule N12 off.
+3. **Rule N4, `unresolved-glyph` (error): a font-styled letter is its own
+   symbol.** `\mathbf{x}`, `\boldsymbol{\beta}`, `\bm{x}`, `\mathcal{N}`,
+   `\mathscr{L}`, `\mathfrak{g}`, `\mathbb{E}`, `\mathsf{x}` and `\mathtt{x}`
+   no longer borrow the plain letter's card, and `\mathbf{e}` /
+   `\boldsymbol{\pi}` no longer pass as Euler's number or π. Give each its own
+   entry (`latex: \mathbf{x}`) or an `\explain{key}{\mathbf{x}}` wrap — in
+   lessons, notation formulas, assessments and labs alike. `\mathit` /
+   `\mathnormal` still share the plain letter's card, and `\mathbb{N,Z,R,C}`
+   stay reserved.
+4. **Rule N22, `accent-explained` (warning): an accent or mark is an
+   operator.** A decoration (`\hat`, `\bar`, `\tilde`, `\dot`, `\vec`,
+   `\overline`, a superscript `'`, `^*`, `^\dagger`, …) needs one of: an entry
+   on `rules.N22.allow` (empty by default), an operator notation entry
+   (`latex: \hat{}`, `{}'`, `{}^{*}`), or a whole-form entry
+   (`latex: \hat{\beta}`). A page where a mark is not an operator declares it
+   in its frontmatter (`notation.suspend: [{ operator: "'", reason: … }]`);
+   every decorated form of it on that page then needs its own entry or a
+   whole-form `\explain`, or the build fails with
+   `suspended-operator-unresolved`. Two consequences for existing notation:
+   - A marked entry no longer lends its card to the bare letter: with only
+     `latex: b'` (or `\theta^{*}`), a bare `b` elsewhere on the page now needs
+     its own entry, or rule N4's gate fails with `unresolved-glyph`.
+   - A whole-form match now wraps the decoration too
+     (`\explain{k}{\hat{\beta}}`, not `\hat{\explain{k}{\beta}}`), and the wrap
+     for `\boldsymbol`, `\bm`, `\bold`, `\Bbb`, `\frak`, `\mathsf`, `\mathtt`
+     and `\mathnormal` lands around the command. Only snapshot tests of
+     rendered HTML notice.
+5. **Rule N8 and rule N10 now read labelled display equations**
+   (`operator-explained`, `roman-label-explained`, both warnings). A
+   `\label{eq:…}` used to hide the whole equation from both scans, so new
+   findings may appear. Explain the operator or label, or list it under
+   `rules.N8.allow` / `rules.N10.allow`.
+6. **Rule N5: hand-typed numbers are now wrong numbers.** Every float number
+   changed (step 11). Prose that types "Equation 2.4" instead of citing
+   `[[eq-…]]` now names the wrong equation; cite it by key.
+7. `x^\prime` no longer fails as an unresolved `\prime`.
+
+### 11. Numbering: every number a reader sees changed
+
+1. **Float numbers are chapter-scoped.** A display equation, table, figure,
+   diagram, knowledge check and example set is numbered
+   `‹part›.‹chapter›.‹n›`, and each kind restarts in every chapter:
+   `Figure 2.1` is now `Figure 2.2.1`. `[[…]]` references need no edit, since
+   they print from the manifest. `numbering.floats: "part"` keeps the old
+   `‹part›.‹n›` scheme.
+2. **The positional anchor of an unkeyed float changed** with its number
+   (`#eq-2-4` → `#eq-2-2-4`). Update links that point at one, or give the
+   float a key (`\label{eq:…}`, an `id`) so its anchor names its content.
+3. **Top-level headings are numbered** `1.1.2`, down to `####` by default
+   (`numbering.sections.depth`, `2`–`6`), on a wide screen, in print, and on a
+   folded section's bar. `numbering.sections.show: false` hides them, and a
+   knowledge check's and example set's numbers with them. The number is
+   generated content: the heading's text and anchor do not change.
+4. **A heading with inline math gets its anchor from its source**
+   (`## The range $R$` → `#the-range-r`), no longer from KaTeX's output.
+   Update links to such headings: `rg -n '^#{2,6} .*\$' content/docs`.
+5. **`sec-` and `ex-` are reserved reference prefixes.** `[[sec-…]]` cites a
+   section and `[[ex-…]]` an example set. Rename a notation key that starts
+   with either and is cited as `[[sec-…]]` or `[[ex-…]]`.
+6. **Number aliases** (`numbering.aliases`, on by default): a fragment a reader
+   types in number form (`#sec-1.1.2`, `#fig-2.2.1`, `#ex-1.1.1`) lands on the
+   element that shows that number. The site itself links and copies only
+   named anchors.
+7. Update prose, captions and tests that quote a number, and record the
+   renumbering in `content/CHANGELOG.md` (rule C1): readers see new numbers.
+
+### 12. Rules: retired IDs, settings, switches, waivers
+
+1. **Retired rules.** Rule N1 (the normal distribution is `\mathcal{N}`), rule
+   N6 (probability is `\mathbb{P}`) and rule N7 (the differential is
+   `\mathrm{d}`) are now lines of **rule N2**, whose table is the setting
+   `rules.N2.reserved`: by default the four number systems, `\mathbb{P}`,
+   `\mathcal{N}(\mu, \sigma^2)` and `\mathrm{d}`, one
+   `"<latex> — <meaning>"` string each. Replace the list to state the course's
+   own conventions: drop the probability lines in a course without
+   probability, or write `\mathcal{N}(\mu, \sigma)` for one that parameterises
+   the normal by standard deviation. Rule N3 (write a multi-letter label as
+   `\mathrm{…}`) is folded into **rule N10**, now `partial`. Rule N16
+   (alternate delimiter shapes to show nesting) is folded into **rule N17**,
+   and **reversed**: a delimiter's shape carries its meaning, and the engine
+   sizes a nest. Content that alternated shapes still builds, but the rule no
+   longer asks for it, and a `[` inside a grouping nest reads as an interval
+   first. Rule C4 (a release moves `[Unreleased]` and bumps `about.version`
+   together) is folded into **rule C3**, now `partial`. A `rules.N1` /
+   `rules.N3` / `rules.N6` / `rules.N7` / `rules.N16` / `rules.C4` block warns
+   `config-retired-rule`, naming the successor: delete it (only rule N2 takes
+   settings). A waiver naming a retired ID is `waiver-invalid`; name the
+   successor. `docs/authoring/retired.md` lists every retired rule.
+2. **Per-rule settings and switches: `rules`.** One block per rule ID, holding
+   only what differs from the defaults: rule S1's `maxLength` (65), rule
+   S2's `bridgeMinWords` / `bridgeMaxWords` / `scopeMinWords` /
+   `scopeMaxWords` (30 / 150), rule V5's `seeds` (10), rule V6's
+   `minLabels` (3), the `allow` / `deny` lists of rule N8, rule N10, rule
+   N12, rule N14 and rule N22, rule N9's `allow`, and rule N2's `reserved`.
+   With `rules.<ID>.enabled: false` a rule stops running and its diagnostics
+   are withheld. Switchable: N5, N8, N9, N10, N14, N17, N19, N20, N21, S1–S7, C3,
+   and every guide rule. The build fails on an unknown rule or key, a value
+   outside its spec, `enabled: false` on a locked rule (rule N4, rule N13,
+   rule N15), and `rules.X1` (course rules live in `courseRules`).
+3. **Per-place waivers.** `{/* explico-allow <ID>[, <ID>]: <reason> */}` on
+   its own line waives the named rules for the next block. A malformed waiver,
+   or one naming a locked rule, an invariant or an unknown ID, is an error
+   (`waiver-malformed`, `waiver-invalid`); one that silenced nothing warns
+   (`waiver-unused`). Record the reason: it is what a reviewer reads.
+4. **Read the rules in effect, not the rule set.** `pnpm validate:content`
+   writes `build/rules-in-effect.md`, and `pnpm content rules [--element …]
+   [--enforcement …]` prints it filtered: the rules this course has on, by
+   element, with codes and settings. An agent drafting for the course reads
+   that page; `docs/authoring/agents.md` now says so.
+5. **Rules that only gained a name.** Rule S3 (`raw-table-markdown`,
+   `raw-table-html`), rule S4 (`diagram-unkeyed`, `diagram-nested`), rule S5
+   (`convention-single-definition`), rule N19 (`notation-units`,
+   `units-vocab`), rule N20 (`notation-source-locator`) and rule N21
+   (`gloss-name-shape`) name checks that already ran. Nothing new fires; the
+   console line now carries the rule, `[S3 raw-table-markdown] …`.
+6. **New guide rules** — review-only, so nothing fails; switch one off with
+   `rules.<ID>.enabled: false` if it does not fit the course:
+   - rule N18: a multi-step derivation is one `aligned` chain, `&` before each
+     relation, a justification after `\qquad` as `\text{…}`.
+   - rule V6: every quantitative axis shows at least three labelled values.
+   - rule P2 (one canonical term per concept), rule P3 (one meaning per term),
+     rule P4 (the established term, defined where first needed), rule P5
+     (literal main text; analogies in an aside), rule P6 (industry jargon only
+     in an "Industry jargon" aside), rule P7 (one claim per sentence, links
+     stated), rule P8 (relation words match the math), rule P9 (a display
+     equation's lead-in says what it gives and where it comes from).
+   - rule S8: prefer `<Memo>` over a Starlight aside when the content needs an
+     anchor, a caption or collapsing.
+7. **Rule S2 applies only to a part page** (step 15). A course without
+   `content/docs/<dir>/index.mdx` is unaffected. With one, each needs a
+   `<PartScope>` paragraph and, for every part after the first, a
+   `<PartBridge>` paragraph before it, each within the `rules.S2` word range
+   (`part-page-paragraph`).
+
+### 13. Record the content changes (rules C1–C3)
+
+The steps above edit `content/`. Add bullets under `## [Unreleased]` in
+`content/CHANGELOG.md` (rule C1): renumbered floats and sections, retitled
+checks and example sets, renamed sections whose anchors changed. Bump
+`about.version` per rule C2 when you release (`pnpm release:content` in the
+playground's shape), keeping it equal to the newest heading (rule C3).
+
+### 14. Only if your course CSS, browser tests or scripts reach into engine markup
+
+```bash
+rg -n 'keyed-figure__(titlebar|summary|title-anchor)|diagram__(titlebar|summary|title-anchor)|lab-chart-figure|memo-block__summary|memo-preview__description|data-memo-(self|anchor)-link|compact-examples__(summary|title)|details\.compact-examples|assessment-heading-number' src content tests
+```
+
+- **Figure and diagram.** The number moved into a caption line below the body:
+  `figcaption.float-caption` with `.float-caption__toggle`,
+  `.float-caption__number`, `.float-caption__anchor` and
+  `.float-caption__text`. `.keyed-figure__titlebar`, `.keyed-figure__summary`,
+  `.keyed-figure__title-anchor`, `.diagram__titlebar`, `.diagram__summary` and
+  `.diagram__title-anchor` are gone; `.diagram__number` is a link. A compacted
+  float keeps the caption line and hides only its body. The `<details>` keeps a
+  native `<summary>` shown only under `(scripting: none)`.
+- **Table.** The caption line is the same `.float-caption` (caption size, a
+  chain icon after the number, no " — ").
+- **Memo.** `.memo-block` is the frame; the `<details>`,
+  `.memo-block__summary`, `[data-memo-self-link]`, `[data-memo-anchor-link]`
+  and `.memo-preview__description` are gone. Its bar is an `<h6 role="none">`
+  with the `#memo-…` anchor, folded by `CollapsibleSections`. The marker is a
+  superscript italic letter (`a`, `b`, …), not `[1]`; `data-memo-number`
+  carries the letter.
+- **Knowledge check.** The heading is `BlockHeading.astro`'s
+  `<h2 id="check-‹id›" class="block-heading">` (badge, number, title in
+  `.block-heading__title`), carrying `data-check-number`; its wrapper carries
+  `data-card="accent"`. `.assessment-heading-number` is gone, and
+  `.assessment-shell` draws no box.
+- **Example set.** `details.compact-examples`, `.compact-examples__summary`
+  and `.compact-examples__title` are gone; `<compact-examples
+  class="compact-examples">` is the card, `#ex-‹id›` its heading.
+- **Container tiers.** Every container is restyled from the tokens in
+  `explico/styles/surfaces.css` (`--ex-surface-*`, `--ex-edge-*`,
+  `--ex-depth-*`, `--ex-radius-*`; `.ex-tier-meta`, `.ex-tier-accent`,
+  `.ex-tier-aside`), which `global.css` imports — `customCss` needs no second
+  entry. A `<Figure>` and a `.lab-shell` lose their card; checks, example sets
+  and `[card]` sections are accent cards; the notation panel, part-page rail,
+  glossary entries, curriculum-map cards, About popover and a Starlight
+  `<Card>` are meta; a memo, an open `<ShortNote>` and Starlight asides are
+  asides. No container has a top rule. Override the tokens rather than the
+  old per-container rules.
+- **Screenshots and layout assertions.** Printed and displayed numbers
+  (step 11); a folded section's "Hidden here: …" line and, on a narrow screen,
+  its in-line chevron and "(tap to expand)"; the chain icon's "Link copied ·
+  § 1.1.2" confirmation; 0.25em more block padding on each display equation
+  (about 8px); the sidebar's leading part caret, filled hover rows, reading
+  progress, and `Overview` rows; print as shown (a closed disclosure prints
+  its title and a link, where print used to expand everything).
+- **Reader state.** A memo's open state moved from `memo:‹id›` to
+  `section:memo-‹id›`, so a returning reader's choice resets once. An example
+  set remembers its state under `section:ex-‹id›` (new). A course that clears
+  preference keys by name adds both.
+
+### 15. Optional: features to adopt
+
+- **Captions.** `\caption{…}` inside a display equation's `$$…$$` (next to its
+  `\label`) gives it a short caption: the `[[eq-…]]` preview card's heading
+  and the copy tooltip ("Copy LaTeX — Range formula"). `short` on a
+  `<Table>`, `<Figure>` or `<Diagram>` heads its preview card.
+- **References.** `[[sec-slug]]` prints `§ 1.1.2` with a preview card;
+  `[[ex-id]]` prints `Example 1.1.1`; `[[check-…]]` now previews the check.
+  `content context <lesson> --json` lists a lesson's `sections` and
+  `examples`, so a drafter need not derive a slug.
+- **Cards and asides.** `[card]` / `[card=meta]` after a heading
+  (`### Explore the range [collapsed] [card]`) cards its whole section.
+  `:::note` / `:::tip` / `:::caution` / `:::danger` render as asides (step 2);
+  `{icon="heart"}` names another Starlight icon and `icon=""` drops it, on a
+  directive or an `<Aside>`.
+- **Part pages.** `content/docs/<dir>/index.mdx` is a part's own page: render
+  it with `<PartOverview>` and state its argument with `<PartScope>` /
+  `<PartBridge>` (rule S2). `<CourseContents>` lists every part and chapter for
+  a landing page. `studyMinutes: 40` (or `[30, 40]`) in a lesson's frontmatter
+  feeds the per-part totals.
+- **Disclosure per instance.** `defaultOpen` is new on `<Memo>` and
+  `<CompactExamples>`, and `rememberState` on `<CompactExamples>`.
+- **Course rules.** `courseRules` in the settings is a list of the course's
+  own rules, `X1`…`X99` (the `X` area is never used by the engine), each
+  `{ id, title, summary?, elements?, enabled?, severity?, forbid?, unchecked?,
+  doc? }`. With `forbid` patterns a rule is enforced at its `severity`
+  (`error` or `warning`), and each finding's code is the rule's ID; without
+  one it is a guide. A bad definition fails the build with the setting's path.
+  See `docs/authoring/README.md` § Rules of your own.
+- **Accessibility** is the engine's job (`docs/authoring/README.md`
+  § Accessibility): nothing asks an author for an accessible name or a text
+  alternative.
+
+### 16. Fixes that need no action
+
+Grey boxes get a background in the dark theme; an equation's copy button keeps
+its "Copy LaTeX" tooltip; a collapsed section's chevron is on screen on a
+phone; the copy-link icon shows on touch screens; labs hydrate under
+`astro dev` again; a printed `\sqrt` keeps its radical sign; `<Diagram>`
+formulas render in Safari and iOS, on screen and in print; display equations
+are no longer clipped at the bottom; pointing at the letter under an accent
+shows the letter's card.
+
+### 17. Verify
+
+```bash
+pnpm validate:content        # run twice: the first run regenerates build/resolution/*
+pnpm content rules           # the rules this course now has on; read before drafting
+pnpm content warnings        # new warnings: rule N22, rule N8 / rule N10 in labelled equations
+pnpm content check --changed
+astro check
+astro build
+```
+
+Then run the course's browser tests, if it has any, and re-record the numbers
+and selectors of step 11 and step 14. A course with a gate script of its own
+that runs these stages (explico's is `scripts/agent/verify`) runs that
+instead of the list above.
+
+## 0.8.0 → 0.9.0
+
+**No course changes are required** beyond the dependency bump, unless your
+course's own CSS reaches into the layout chrome (step 2). Everything in this
+release is engine-side UI: the panel collapse controls, reader-set panel
+widths, and the compact-chapter tooltip. No authoring rule, manifest field,
+CLI command, `CourseConfig` field, or Astro wiring moved, and the manifest
+schema version is unchanged.
+
+### 1. Update the dependency
+
+```bash
+pnpm add -D explico@0.9.0
+```
+
+0.9.0 was never published to npm. Coming from npm's 0.8.0, install 0.11.0
+instead, and read the "Coming from 0.8.0" note of "0.10.0 → 0.11.0" first.
+
+Or set `"explico": "0.9.0"` in `package.json` and run `pnpm install`. Nothing
+in `astro.config.mjs`, `content/course.config.ts`, `content/`, or your course
+scripts needs to change for this release.
+
+### 2. Only if your course CSS targets the collapse control
+
+Two names in the layout chrome changed. Check your own stylesheets and
+components:
+
+```bash
+rg -n 'layout-edge-icon|--layout-edge-toggle-size' src content
+```
+
+- `--layout-edge-toggle-size` no longer exists. It was one square; the control
+  is now a rectangle, so set `--layout-edge-toggle-width` and
+  `--layout-edge-toggle-height` instead.
+- `svg.layout-edge-icon` / `.layout-edge-icon-hide` / `.layout-edge-icon-restore`
+  are now `span.layout-edge-glyph` / `.layout-edge-glyph-hide` /
+  `.layout-edge-glyph-restore`.
+
+No hit means nothing to do.
+
+### 3. Optional: retune the docked control
+
+The control docks into the corner the header and the panel's separator line
+make. One gap sets both of those edges, and the radius applies to the one
+corner free of them (bottom-left on the navigation panel, bottom-right on the
+contents panel, mirrored in RTL). Override any of these in your course CSS:
+
+```css
+:root {
+  --layout-edge-toggle-gap: 2px; /* under the header, and in from the line */
+  --layout-edge-toggle-width: 1.875rem;
+  --layout-edge-toggle-height: 1.125rem;
+  --layout-edge-toggle-radius: 0.4375rem;
+  --layout-peek-delay: 40ms; /* rest this long on a rail before it peeks */
+}
+```
+
+`--layout-peek-delay` is read by the script, not only by the stylesheet, so it
+accepts any CSS `<time>` (`40ms`, `0.04s`) and falls back to 40ms if it cannot
+be parsed. Set it to `0ms` for the previous behaviour, where crossing a
+collapsed rail opened it immediately.
+
+Widening or heightening the control also widens the strip each panel keeps
+clear at its top (`--layout-edge-toggle-reserve`), so the first chapter row
+stays out from under it; you do not set that one yourself.
+
+### 4. Reader-side state
+
+Layout preferences moved from `credit-playground:layout:*` to
+`explico:layout:*`, and two new keys join them
+(`explico:layout:navigation-width`, `explico:layout:contents-width`). The old
+keys are read once as a fallback, so a returning reader keeps the layout they
+left and there is nothing to migrate. Only if your course clears preference
+keys by name — few do — add the new names to that list.
+
+### 5. Only if your course has browser tests over the layout chrome
+
+A test that asserts the collapse control's size, shape, or position, or that
+clicks it by an `svg` selector, needs updating: it is a rectangle roughly
+30 × 18 px docked 2 px under the header and 2 px in from the separator line,
+both panels' controls share one block start, and its glyphs are text. While a
+collapsed panel peeks open on hover, its control also *grows* towards the
+separator — its outer edge stays put — so a test that hovers a rail sees a
+much wider control than the resting one. A peek also no longer opens the
+instant a rail is hovered: a test that hovers one and asserts immediately must
+poll, or set `--layout-peek-delay: 0ms` for the duration of that test. Panels also now carry
+`.layout-edge-resizer` handles, and a resized panel stamps
+`data-navigation-resized` / `data-contents-resized` on `<html>`.
+
+### 6. Verify
+
+```bash
+pnpm validate:content   # run twice: the first run regenerates build/resolution/*
+pnpm content check --changed
+astro check
+astro build
+```
+
+## 0.7.0 → 0.8.0
+
+### 1. Rule N17 is inverted: delimiters are sized by the engine (`\left`/`\right` everywhere)
+
+The engine now installs its own KaTeX delimiter sizing, so a `\left … \right`
+pair is always strictly taller than its content and a nest shows its depth
+without help. Hand-picking `\bigl` → `\Bigl` → `\biggl` → `\Biggl` outward —
+which rule N17 previously *required* — is now the thing the linter warns about.
+
+**There is no install step.** `astro.config.mjs` already imports
+`explico/reference/katex-options.mjs`, and that module now imports
+`explico/reference/katex-delimiters.mjs` for its side effect. Confirm the import
+is still there; a course that inlined its own KaTeX options object instead must
+add, as the **first** import in `astro.config.mjs`:
+
+```js
+import 'explico/reference/katex-delimiters.mjs';
+```
+
+Order matters: the installer moves KaTeX's render entry points onto the shared
+`katex` object, so anything that renders math before the import would keep stock
+spacing. It refuses to fail quietly — it renders a known nest at install time and
+throws if the sizes did not grow.
+
+Two course-side conditions make the build throw, both with an explicit message:
+
+- **A `patches/katex@*.patch` file that already applies a negative
+  `\delimitershortfall`.** Delete the patch and its `pnpm.patchedDependencies`
+  entry; the engine does this in code now, and a patch is project-local anyway
+  so it never reached a consumer.
+- **A `katex` whose bundle no longer holds the constant where the engine looks
+  for it.** The rewrite targets one line in KaTeX's ESM bundle, so keep `katex`
+  on the declared peer version (`0.16.47`). An upgrade that moves or reformats
+  that line fails the build asking you to re-derive the change against
+  [`../katex-bracket-scaling.md`](../katex-bracket-scaling.md), which is
+  shipped in the package. The failure is loud and immediate, not a silent
+  return to stock spacing.
+
+### 2. Diagnostic renamed: `delimiter-size-hierarchy` → `delimiter-manual-size`
+
+The old code string no longer exists. Update every place that names it:
+
+- `lint-ignore.yml` — a stale line is inert and silently stops suppressing.
+- Course scripts, tests, and type narrowings over the diagnostic union;
+  `astro check` flags a comparison against a non-member.
+
+Its payload changed shape too. A consumer reading the fields, rather than just
+the `code` and `message`, needs this edit:
+
+```diff
+-// outerSize / nestedSize described the mismatch between two levels
+-const found = diagnostic.outerSize;
+-const suggested = diagnostic.suggestion?.size;
++// `size` is the hand-picked size found; `suggestion` is always present and is
++// always a \left/\right pair, so it no longer carries a `size` of its own.
++const found = diagnostic.size;
++const suggested = diagnostic.suggestion.latex;
+```
+
+`DelimiterSizeSuggestion` keeps `open`, `close`, and `latex`, and drops `size`.
+`DelimiterSizeDiagnostic` drops `outerSize` and `nestedSize`, gains a required
+`size`, and `suggestion` is no longer optional.
+
+### 3. Content: hand-sized nests now warn
+
+Math that was N17-compliant under 0.7.0 reports one `delimiter-manual-size`
+finding per hand-sized level. This is a Tier-3 warning — it does not fail a
+build — so it can be worked through at your own pace, but the findings are real
+and the repair improves the rendering.
+
+Find them with:
+
+```
+pnpm content warnings --json
+```
+
+The repair is mechanical: replace the hand-picked pair with `\left`/`\right`,
+keeping the delimiter shapes.
+
+```diff
+-\Biggl[a+\biggl(b+\Bigl[c+\left(d+e\right)\Bigr]\biggr)\Biggr]
++\left[a+\left(b+\left[c+\left(d+e\right)\right]\right)\right]
+```
+
+A **lone** hand-sized pair that is not part of a nest — `\bigl(x,\ y\bigr)`
+around a tuple, for instance — is a single-level typographic choice with no
+hierarchy to get wrong, and is deliberately left alone. Do not convert those.
+
+Expect a small visual change everywhere a nest is rendered: each level is now
+strictly larger than the one inside it, so outer delimiters grow by roughly one
+size step. A course holding screenshot or bounding-box baselines over math
+should re-record them.
+
+### 4. Manifest schema is now v16: a math diagnostic can name its equation
+
+`MANIFEST_SCHEMA_VERSION` is 16 (v15 → v16). The bump is **additive** — nothing
+existing changed shape — so the only required edit is to a client that asserts
+the number by exact equality, which now expects 16.
+
+What was added: a finding the math gate reports from a `$$…$$` block carrying a
+`\label{eq:…}` gains an optional `equation` field, `{ key, href }`. `href` is
+the rendered page's anchor for that equation
+(`/l1-ar/ar1-basics/#eq-ar1-variance`). `CliDiagnostic` carries the same
+optional field, so a course's own `scripts/content.ts` picks it up with no
+change.
+
+`diagnosticLine()` now appends it, so console output, the run log, and
+`pnpm content diagnostics` read:
+
+```
+[code] file:line:column: message (eq:<key> -> <href>)
+```
+
+A course script that parses that line with an anchored regex must tolerate the
+optional trailing ` (eq:… -> …)`. One that just prints the string needs nothing.
+
+### 5. Diagnostic line numbers are corrected — re-record anything that stored them
+
+Every gate scans the lesson body, which Astro hands over with the frontmatter
+already stripped, but findings are reported against the lesson *file* — so every
+`file:line:column` the engine has emitted for a lesson was short by the height
+of that lesson's frontmatter. `gate-math` (every `delimiter-manual-size`
+column), `gate-prose-notation` (rule N9), `gate-abbreviations` (rule N14), and
+`gate-heading-length` (S1) are all corrected at once.
+
+Nothing to edit in content, but line numbers move, so:
+
+- Re-check any suppression, snapshot, or problem matcher keyed to a line number.
+  Line numbers were wrong before; they now point at the real line.
+- `pnpm validate:content` (twice) regenerates `build/resolution/*` with the
+  corrected positions. Commit the result.
+
+### 6. Malformed `\explain` / `\slot` keys now fail the build
+
+Previously a key that did not match the notation key pattern —
+`\explain{Not A Key}{\Omega}` — was not a KaTeX parse error: KaTeX rendered the
+command name in its error color and carried on, so the page shipped red
+`\htmlData` text with a green build. `renderNotationMath` now checks both marker
+macros before KaTeX runs and throws, naming the offending key.
+
+**This can newly fail a build that passed on 0.7.0.** If it does, the page was
+already broken for readers. Fix the key to match the notation key pattern
+(lower-case, hyphen-separated) and make sure it resolves to a real entry.
+`renderNotationFormula` still degrades to inert-but-correct math rather than
+costing a reader the equation.
+
+### 7. Glossary entry heading markup: the anchor is now a sibling of the `<h2>`
+
+The per-entry anchor link moved out of the `<h2>` and into a new
+`.glossary-heading` flex row wrapping both — the same shape
+`rehype-heading-anchors` gives a lesson heading. This restores the heading's
+accessible name (a screen reader was announcing "Velocity Link to Velocity").
+
+Nothing visual changed, but update course-owned CSS and end-to-end tests that
+assumed the nesting:
+
+```diff
+-h2:hover .glossary-anchor,
+-h2:focus-within .glossary-anchor {
++.glossary-heading:hover .glossary-anchor,
++.glossary-heading:focus-within .glossary-anchor {
+```
+
+A test locating the anchor as a descendant of the heading must target
+`.glossary-heading .glossary-anchor` instead. A check for the heading *by
+accessible name* now matches the term alone, which is the point of the fix — if
+such a test was written against the broken name ("Velocity Link to Velocity"),
+it needs the term.
+
+### 8. The About panel publishes its versions as data attributes
+
+Additive; no course edit is required. `details[data-about-panel]` now carries
+`data-knowledge-version`, `data-knowledge-date` (omitted when the content
+changelog has no date), and `data-engine-version`, and the rendered version line
+is marked `data-knowledge-line`.
+
+This exists so a build check does not have to match prose. A course asserting
+the panel's contents by text is pinned to one version string and turns every
+routine bump into a test edit — this repo's own `about.spec.ts` was asserting
+`0.4.0` against a playground long since past it. Prefer:
+
+```diff
+-await expect(panel).toContainText('0.6.0');
++await expect(panel).toHaveAttribute('data-knowledge-version', knowledgeVersion);
+```
+
+reading the expected value from `content/course.config.ts` rather than hard-coding
+it. A bare version substring is not scoped to the panel either — the engine
+version printed one row below can satisfy it.
+
+### 9. Fixes that need no action
+
+These remove build failures; they never require a content edit. Formulas you
+previously worked around may now be written directly.
+
+- **A notation `formula` can use a manual delimiter size, an accent, a box, or
+  a color.** `render-notation-math.ts`'s attribute allowlist is now KaTeX's
+  whole inert presentation surface, so `\Bigl`/`\biggl`/`\Biggl`,
+  `\xrightarrow`, `\boxed`, and `\colorbox` no longer throw
+  `Unexpected KaTeX property`. `alt`, `href`, `src`, and `title` are explicitly
+  denied; no attribute that can carry a URL is allowed through.
+- **`\vec` and every other accent renders.** The style sanitizer no longer
+  requires a trailing `;` on the last CSS declaration. `\mathbf` remains the
+  house style for a vector; `\vec` simply works now.
+- **A macro in a formula no longer invents a source span.** `\vdots`,
+  `\varSigma`, `\argmax`, `\bmod`, `\R`/`\N`/`\Z` and 79 of KaTeX's 282 macros
+  produce nodes whose `loc` indexes the macro body, which the glyph resolver
+  read as a span over unrelated text — failing with `Unresolved notation ""`,
+  or worse, silently splitting a formula mid-command. Fixed. An existing
+  explicit `\explain{key}{\varSigma}` annotation still works and is still the
+  way to bind a macro-expanded glyph, since it has no authored span for
+  canonical matching to see.
+- **`equationAnchorId({ key })` type-checks without a `number`.** Its JSDoc
+  required a property the function ignores when a `key` is given.
+
+### 10. Verify
+
+```
+pnpm add -D explico@0.8.0
+pnpm validate:content   # twice — the first run regenerates build/resolution/*
+pnpm content check --changed
+pnpm content warnings   # expect new delimiter-manual-size findings (item 3)
+astro check
+astro build
+```
+
+Commit the regenerated `build/resolution/*` (items 4 and 5 both change it).
+
 ## 0.6.0 → 0.7.0
 
 ### 1. Manifest schema is now v15: diagnostic severity has three levels
@@ -151,8 +1473,8 @@ 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).
+"sized". See [`notation.md#n17`](notation.md#n17) — and, for rule N16, which
+was later folded into N17, [`retired.md`](retired.md).
 
 ### 7. Rule P1: "or" never introduces a second name for the same thing