explico 0.12.0 → 0.13.0

package/docs/authoring/migrating.md

@@ -33,6 +33,669 @@ required config block throws with the section of this file to read.
 
 ---
 
+## 0.12.0 → 0.13.0
+
+**Course changes are required.** A course still on 0.11.1 applies
+"0.11.1 → 0.12.0" below first. Each of these can fail a build that passed
+on 0.12.0:
+
+- the Astro, Starlight and `@astrojs/react` versions, which move with
+  explico (step 1);
+- `editorialStatus` in any content file, now `retired-key` (step 2), and a
+  course's `scripts/content.ts` that prints the draft counts it fed (step 3);
+- a course test that still passes rule S5's `conventions` (step 4);
+- `lessonExports.standaloneHtml` without `canonicalBaseUrl` (step 5);
+- faults that used to pass in silence and are now `validate:content`
+  errors, rule S6 among them (step 7);
+- rule N23, an index is part of the symbol, and rule N4, an indexed entry
+  lends its card to nothing (steps 8–14);
+- code a course owns that reads what was removed (step 15).
+
+The manifest schema is now v31, by way of v26, v27, v28, v29 and v30 (step
+15). Fix every finding in the same change as the upgrade. The steps are one
+pass, ordered so that no fix has to be redone. `rules.N23.enabled: false`
+exists, but a course that ships with it off shows its readers the cards this
+rule exists to fix, and the N4 failures of step 8 cannot be switched off.
+
+### 1. Update the dependencies together
+
+explico 0.13.0 pins a newer Astro stack in its `peerDependencies`. Set these
+five in the course's `package.json`, each in the block that declares it now,
+then run `pnpm install`:
+
+| Package | from | to |
+| --- | --- | --- |
+| `explico` | 0.12.0 | 0.13.0 |
+| `astro` | 7.2.7 | 7.3.5 |
+| `@astrojs/starlight` | 0.41.9 | 0.42.4 |
+| `@astrojs/react` | 6.0.4 | 7.0.0 |
+| `@astrojs/markdown-remark` | 7.2.4 | 7.3.1 |
+
+Move the four Astro packages together: Starlight 0.42 requires `astro`
+7.2.10 and `@astrojs/markdown-remark` 7.3.0 or later. `astro.config.mjs`
+needs no change unless it uses one of these:
+
+- `react({ babel: … })`. `@astrojs/react` 7 removes the option: move those
+  plugins to `@rolldown/plugin-babel` in `vite.plugins`.
+- Starlight's top-level `tagline`. It is removed, so delete it. A splash
+  page's `hero.tagline` is unaffected.
+
+Starlight's mobile menu is now a `#starlight__sidebar` popover, opened by a
+plain `button.sl-menu-button`. The `<starlight-menu-button>` element, its
+`aria-expanded` and `body[data-mobile-menu-expanded]` are gone. Course CSS,
+scripts or browser tests that target them match nothing; use
+`.sl-menu-button` and `body:has(#starlight__sidebar:popover-open)`:
+
+```bash
+rg -n 'starlight-menu-button|data-mobile-menu-expanded' src content tests
+```
+
+Starlight 0.42 supports Chrome 116, Safari 17 and Firefox 125 or later.
+`astro build` now prints `[WARN] [content] The collection "i18n" does not
+exist or is empty` twice. The warning is harmless.
+
+### 2. Delete `editorialStatus` from every content file
+
+The draft / in-review / reviewed flag is retired, and nothing reads or shows
+it. A page, notation entry, abbreviation, competency, assessment, source or
+track that still sets it fails `validate:content` with `retired-key`, once
+per file. Run this from the course root. It deletes the key from Markdown
+frontmatter and from JSON records, along with the comma left behind where
+the key was a record's last:
+
+```bash
+node --input-type=module <<'EOF'
+import { readFileSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+const files = execFileSync('grep', ['-rl', 'editorialStatus', 'content'], { encoding: 'utf8' })
+  .split('\n').filter(Boolean);
+for (const file of files) {
+  const out = [];
+  let fence = file.endsWith('.json') ? null : 0; // Markdown: only inside the frontmatter
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    if (fence !== null && line.trim() === '---') fence += 1;
+    const json = fence === null && /^\s*"editorialStatus"\s*:\s*"[^"]*"\s*,?\s*$/.test(line);
+    const yaml = fence === 1 && /^\s*editorialStatus\s*:/.test(line);
+    if (!json && !yaml) { out.push(line); continue; }
+    if (json && !line.trimEnd().endsWith(',')) {
+      // The key was the record's last: drop the comma the key before it left.
+      const i = out.findLastIndex((l) => l.trim() !== '');
+      out[i] = out[i].replace(/,(\s*)$/, '$1');
+    }
+  }
+  writeFileSync(file, out.join('\n'));
+  if (file.endsWith('.json')) JSON.parse(out.join('\n'));
+}
+console.log(`editorialStatus removed from ${files.length} files`);
+EOF
+grep -rn editorialStatus content
+```
+
+The final `grep` must print nothing. In `git diff`, each file loses one line,
+and a JSON record whose last key it was also loses one comma. A course test
+that builds notation, lesson or source inputs drops their `status` /
+`editorialStatus` too (step 15).
+
+### 3. The course's `scripts/content.ts`
+
+`tsx` does not type-check, so a field the engine no longer returns throws at
+run time. In the course's own `content` wrapper:
+
+- `content status`: drop the draft counts. `report.draftDebt` is gone, so
+  `report.draftDebt.lessons.length` and `report.draftDebt.notation.length`
+  throw.
+- `content context`: drop `report.lesson.status`.
+- `content check`: pass every id, `contentCheck(manifest, { lessons:
+  args.positionals, changed: args.changed })`. `lesson` still works, but it
+  checks only the first id: `content check a b` exits 0 having never
+  looked at `b`.
+
+Optionally, as explico's playground now does, fail on an argument a command
+does not take (`status`, `rules` and `warnings` take none; `context` and
+`new` take one).
+
+### 4. Rule S5 is retired: delete `conventions`
+
+Rule S5 (`convention-single-definition`) is gone, and so is the
+`conventions` setting it read (`signConventionKey`,
+`cashFlowPerspectiveCompetency`). Its check knew one finance course's wording
+and never fired in any course. A convention is a definition, so rule N4 now
+covers it: the convention's notation entry names the other choice in its
+`meaning` and says how to convert in its body (notation.md, rule N4, "A
+definition that is a convention").
+
+- Delete the `conventions` block from `content/course.config.ts`, or from
+  `course.settings.json` and its schema where the course keeps its settings
+  there. Until then it does nothing, and `validate:content` warns
+  `config-deprecated-key`. The type keeps it, as a deprecated `unknown`,
+  only until the next MINOR.
+- Delete a `rules.S5` block (it warns `config-retired-rule`) and any
+  `lint-ignore.yml` line for `convention-single-definition`, which now
+  silences nothing.
+- A course test that calls `runConsistencyChecks` drops `catalog` and
+  `conventions` from its input. The check that read them is gone, and an
+  object literal that still passes them is a type error.
+- Optional: on the entry that was the course's `signConventionKey`, and on
+  any other entry that is a convention, add the other choice to `meaning`
+  and the conversion to the body. That is a notation edit, so it gets a
+  `content/CHANGELOG.md` bullet like any other (rule C1).
+
+### 5. `lessonExports.canonicalBaseUrl` with standalone HTML
+
+With `lessonExports.standaloneHtml` on, each part and the whole course now
+also download as one offline HTML file: `downloads/part/<dir>.html` (the
+part's page, then its chapters) and `downloads/course.html` (the landing
+page, the curriculum map, the figures and tables, every part, the glossary).
+An exported page that links elsewhere in the course fails the build without
+a base URL, as a chapter always did, and a splash hero's actions always
+link. Such a course sets its deployed root:
+
+```json
+"lessonExports": {
+  "standaloneHtml": true,
+  "print": true,
+  "canonicalBaseUrl": "https://example.org/my-course/"
+}
+```
+
+A page that is not a chapter has no download of its own. Its content is in
+its part's file and the course's. A course link into `downloads/` points at
+`<slug>.html` for a chapter, `part/<dir>.html` or `course.html`.
+
+### 6. List the work
+
+```bash
+pnpm validate:content; pnpm validate:content
+pnpm content diagnostics error
+pnpm content warnings
+```
+
+Read the second `validate:content`; the first regenerates
+`build/resolution/`. Step 7 covers the new errors that are not about
+indices. Every N23 finding names its rule, the form, and the fix:
+`index-explained`, `index-swallowed`, `index-range`, `derived-key-taken`
+(errors), `accent-swallowed` (a rule N22 warning), and `unresolved-glyph`
+lines whose message names "an indexed entry". Lab and diagram math only
+exists as the page renders, so `astro build` reports it (step 13). Run that
+once the content checks pass. To see the list before upgrading, run the
+engine repository's dry run from its `playground/` directory in a checkout:
+`node_modules/.bin/tsx ../scripts/agent/index-dry-run.ts <course-dir>`. It
+leaves the course untouched (its report goes under the engine's
+`.agent/index-dry-run/`). It covers lesson bodies, notation formulas,
+assessments and `unresolved-glyph`, but not `accent-swallowed`, labs or
+diagrams.
+
+### 7. Faults that now fail `validate:content`
+
+Each of these used to pass and then show readers something wrong, or fail
+`astro build` with no file or line. Each error names its file and line. Most
+courses have few of them, or none:
+
+| Code | What fails | Fix |
+| --- | --- | --- |
+| `markup-in-prop` | `$…$`, `[[…]]` or `[@…]` in a quoted prop (`short="Speed $v$"`) | write the symbol in Unicode or words; reference or cite from the prose beside the component |
+| `mdx-expression` | `{a}` in prose, which MDX runs as JavaScript | `\{a\}`, or `$\{a\}$` for a set |
+| `eq-label-repeated` | a second `\label{eq:…}` in one `$$…$$` block | give each equation you refer to its own block |
+| `eq-latex-ref` | `\begin{align}`, `\begin{equation}`, `\tag`, an unprefixed `\label`, `\eqref` or `\ref` | `aligned` / `gathered` / `alignedat` inside the block, `\label{eq:key}`, `[[eq-key]]` |
+| `invalid-key` | a notation key starting `eq-`, `tab-`, `fig-`, `dia-`, `ex-`, `check-`, `sec-` or `memo-` | rename it: a MAJOR bump under rule C2 |
+| `heading-nested` | a worked-example set or a knowledge check inside a `<Memo>` or `<ShortNote>` (rule S6) | move it out, after the memo |
+| `tab-several-tables` | one `<Table>` holding two tables | one `<Table>` each |
+| `citation-in-link` | `[as measured in [@id]](https://…)` | cite after the link |
+| `heading-anchor-collision` | a heading whose anchor something else holds: `## References` on a page that cites, `## Tab totals` beside `<Table id="totals">` | reword the heading |
+| `currency-dollar` | `pay $5 ~ $6`, which remark-math reads as math | `\$5 to \$6` |
+| `malformed-reference` | an unclosed `[[` | close it |
+| `invalid-assessment` | a `[[…]]` or `[@…]` in a knowledge check's prompt, explanation or option, which reached students as typed | say it in words: a check renders text and math, not references or citations |
+| `unsupported-key` | `draft: true` on a lesson | keep an unfinished lesson outside `content/docs/` |
+
+Two more fail `astro build`: a `<Table>` or `<Figure>` inside a `:::`
+aside (the message names the aside; move the float out), and a `<Diagram>`
+edge from a node to itself (the message says how to draw the repetition).
+
+A knowledge check's option label now renders its math, so rule N4 checks
+it: a symbol in `"$30^{\circ}$"` needs a card, as in the prompt. Rule N9
+still does not apply to a label ("30 degrees" stays valid). A declared
+operator now binds only its own card (rule N8). A `\operatorname{Cov}` that
+silently opened the page's `\operatorname{Var}` card has no card now: give
+it one, or add it to `rules.N8.allow`. A name a course put on
+`rules.N8.allow` only because its card was refused can come off the list,
+with the card restored.
+
+New warnings, worth clearing in the same pass:
+
+- `local-shadows-shared`: a `notation.local` key equal to a shared one.
+  Rename the local key.
+- `fig-unread-prop` (and the `tab-`, `dia-` and `ex-` variants): a caption
+  prop written as an expression, `short={"…"}`. Quote it, `short="…"`.
+- `ignored-key`: a chapter's `sidebar.order`, which does nothing. Delete it.
+- `part-empty`: a part listed in `parts` before its directory exists. Fine
+  while the part is planned.
+- `lab-picture-undrawn` and `dia-too-wide` (step 13), and
+  `accent-swallowed` (step 14).
+
+### 8. A bare symbol that borrowed an indexed entry's card (rule N4)
+
+An entry with a subscript lends its card to no bare symbol now. A family
+(`\alpha_i`, "ARCH coefficient") gives it to its own instances only
+(`\alpha_1`, `\alpha_q`); a fixed label (`H_0`, `v_0`, `T_{\mathrm{opt}}`)
+to nothing. The bare symbol fails `unresolved-glyph`, and the message names
+the entry it shared its base with. For each (page, symbol):
+
+- **A different object** — the usual case: a learning rate `\alpha` beside
+  ARCH coefficients `\alpha_i`, an AR(1) coefficient `\beta` beside `\beta_i`,
+  a response `Y` beside observations `Y_i`. Give it its own entry, page-local
+  when only that page uses it:
+
+  ```yaml
+  notation:
+    local:
+      - key: learning-rate
+        latex: \alpha
+        label: Learning rate
+        meaning: The weight the newest observation gets in the exponentially weighted average.
+        dimensionless: true
+  ```
+
+- **Shorthand for the family**, the indexed symbol with the index left off:
+  wrap it, `\explain{arch-coefficient}{\alpha}`.
+
+- **Another member of a fixed-label set**: `H_1` borrowed the `H_0` card
+  ("Null hypothesis"). Give it its own entry, or introduce the one the course
+  has (`[[alternative-hypothesis]]`).
+
+A function form still lends by its head: `D(0,t)` explains a bare `D`, and
+`V_0(1_t)` explains `V_0(1_2)`, but no longer a bare `V`.
+
+### 9. `index-swallowed`: an `\explain` around an indexed symbol
+
+`\explain{motion.velocity}{v_x}` made the whole `v_x` one target with the
+velocity's card, which says nothing about `x`. Find them all:
+
+```bash
+rg -n '\\explain\{[^}]+\}\{\\?[A-Za-z]+(\{[^}]*\})?_' content
+```
+
+For each reported wrap, either drop it and explain the subscript the way
+step 10 does (an index entry `{}_x` turns `v_x` into one derived card,
+"Horizontal component of velocity"), or point the wrap at an entry for the
+indexed symbol itself. A wrap whose key's `latex` has an index
+(`\explain{launch-speed}{v_0}`) is fine.
+
+### 10. `index-explained`: whole form, family or index entry
+
+A subscript only the base's card covered — a digit, a `\mathrm{}` label, a
+base-library `i`, `e` or `d` used as an index — needs one of three, in this
+order of precedence:
+
+1. **Whole form**, for a named quantity: an entry with `latex:
+   \mathbf{v}_0`, "Initial velocity". It also wins under a power
+   (`\mathbf{v}_0^{2}`), so an `\explain{key}{v_0}^{2}` workaround can go.
+2. **Family**, for an index that runs: `latex: x_k`, "k-th component". It
+   explains every instance with the same number of comma-separated slots
+   (`x_1`, `x_{k+1}`, `x_N`), ahead of a plain `x` entry, but not a fixed
+   label (`x_{\mathrm{e}}`). Two families on one base that both fit an
+   instance fail `ambiguous-base-fallback`: keep one per page, or
+   `\explain` the instance. An entry like `v_x` whose index is a label is no
+   family: mark it `fixedIndex: true`.
+3. **Index entry**, for a subscript with one meaning on the page — usually
+   page-local, since `x_0` may be a starting point on one page and a centre
+   on another:
+
+   ```yaml
+   notation:
+     local:
+       - key: initial
+         latex: "{}_0"            # quoted: a bare {} starts a YAML mapping
+         label: Initial value
+         meaning: The value of a quantity at the start, when time is zero.
+         reads: "{base} evaluated at t = 0"            # optional
+         formula: "{base}_0 = {base}\\,(\\explain{time}{t} = 0)"   # optional
+   ```
+
+   Every symbol of the page that has a card of its own then shows `x_0` as
+   one derived card, titled from `reads` ("Velocity vector evaluated at
+   t = 0"; the default is "Initial value of velocity vector"), with the
+   index entry's meaning and the base's units. An index entry takes no
+   `units`, `dimensionless`, `range` or `fixedIndex` (the loader fails on
+   them), and rule N19 skips it. `reads` belongs to an index entry only; it
+   names the symbol with `{base}` and is plain prose, with no `$`, `\` or
+   backtick.
+
+An index letter with its own card explains its slot, arithmetic included
+(`X_{t-1}`); a base-library letter does not, so `x_i` needs an `i` card (an
+index letter, with `range`, step 11) or a family. A digit beside a carded
+letter in another slot (`F_{0,T}`) needs a family (`F_{t,T}`) or an index
+entry. When the message says the base has no card either (an indicator
+`\mathbf{1}_{\{k=n\}}`), give the base an entry.
+
+### 11. `index-range`: the set a running index runs over
+
+A running index is a lowercase letter in a subscript (`i`, `k`, `t`) that
+the page does not declare fixed. State its set once, in one of three ways:
+
+- `range` on the letter's card, or on the family entry over it — one edit
+  for every page that card is on:
+
+  ```yaml
+  key: time.index
+  latex: t
+  range: "1, \\dots, T"
+  ```
+
+- after a `\quad` on the first display line where the letter is an index,
+  for a set that belongs to the page: `x_i \sim \mathcal{N}(\mu, \sigma^2),
+  \quad i = 1, \dots, n` (not `\qquad`, which is rule N18's reason slot);
+- `fixedIndex: true` on the letter's card when the letter is a label there
+  (a component `x`, a group `g`), not a position in a range.
+
+Uppercase and Greek letters in a subscript (`X_N`, `p_\theta`) are sizes and
+parameters: they need a card, never a range.
+
+### 12. Notation formulas and assessments
+
+`validate:content` reports the same `index-explained` and `index-swallowed`
+in a `formula:` of `content/notation/*.md` or `notation.local`, and in an
+assessment's prompt, explanation or option. In an assessment, fix it as in
+a lesson: the assessment renders with its lesson's notation, derived cards
+included. A formula resolves against its own card's table, where an index
+entry does not compose; explain the indexed symbol there with a whole form —
+`\explain{launch-speed}{v_0}`, or a gloss on the entry:
+
+```yaml
+glosses:
+  - latex: y_{\mathrm{new}}
+    name: yield after the shift
+```
+
+— or wrap the subscript in the index entry's key,
+`\mathbf{v}_{\explain{initial}{0}}`, which gives the `0` that card.
+
+### 13. Labs and diagrams: index math, a drawn picture, a width
+
+**Rule N23 at render.** `astro build` fails with "Lab math has an index no
+card explains (rule N23, <context>)" or "Diagram … has an index no card
+explains (rule N23)", naming the form and the template. Fix the page's
+notation as in steps 8–11. An index entry on the page gives the lab's and
+the diagram's symbols their derived cards too, with no code change, as long
+as the lab passes the table `labMathScope` returned straight to
+`renderLabMath`. A wrapper that copies it (`[...scope]`) gets neither the
+cards nor the check, so pass it unchanged.
+
+**A lab's picture is in the built page (rule V3).** `astro build` warns
+`lab-picture-undrawn` for a figure whose picture is an island that draws
+nothing until the browser runs it. A card from another page, print without
+JavaScript, and the HTML, LaTeX and Markdown exports all show an empty box
+there. Draw the lab's default picture at build time in its `.astro` wrapper
+and pass it to the island as children. The island shows them until it has
+drawn into `.lab-chart-live`, and explico's stylesheet hides them from then
+on. With Observable Plot, add `linkedom` as a course devDependency and draw
+with the island's own options at its defaults:
+
+```ts
+// content/labs/still-plot.ts — import it only from .astro frontmatter,
+// so linkedom stays out of the island's bundle
+import * as Plot from '@observablehq/plot';
+import { parseHTML } from 'linkedom';
+
+export function stillPlot(options: Plot.PlotOptions): string {
+  const { document } = parseHTML('<!doctype html><html><head></head><body></body></html>');
+  return (Plot.plot({ ...options, document }) as unknown as Element).outerHTML;
+}
+```
+
+```astro
+---
+const still = stillPlot(rangePlotOptions(DEFAULTS.speed, DEFAULTS.angle));
+---
+<RangePlot client:visible><Fragment set:html={still} /></RangePlot>
+```
+
+```tsx
+// the island: show the build's copy until the live plot is in
+<div className="lab-chart">
+  {drawn ? null : children}
+  <div className="lab-chart-live" ref={chartRef} />
+</div>
+```
+
+Set `drawn` in the effect that puts the plot into `chartRef`.
+
+**A diagram's width (rule V8).** Diagram boxes are now sized from their
+label and formula, so a diagram can change size; re-shoot any screenshot of
+one. A diagram wider than the lesson column, 707px unless the course sets
+`rules.V8.columnWidth`, warns `dia-too-wide`. It used to be an untagged
+console line, above 800px. Shorten its labels, split it, or lay it out
+vertically. `warnAboveWidth={false}` still opts one diagram out, and a
+number there sets that diagram's own limit. A node's `width` alone now takes
+effect, with the height following, so a `height` that was there only to
+make `width` work can go.
+
+### 14. `accent-swallowed` and `derived-key-taken`
+
+`accent-swallowed` (rule N22, a warning) is the hat's twin of step 9:
+`\explain{beta}{\hat{\beta}}` names a card that says nothing about the hat.
+Wrap only the letter, `\hat{\explain{beta}{\beta}}`, and explain the hat
+(an operator entry `\hat{}`, or `rules.N22.allow`), or name an entry for
+`\hat{\beta}`. `derived-key-taken` means an authored key has the form
+`<entry>.sub.<index entry>`, which the build uses for derived cards: rename
+it (a MAJOR bump under rule C2, step 20).
+
+### 15. Code a course owns
+
+- **Manifest v31.** `MANIFEST_SCHEMA_VERSION` goes from 25 to 31, so a
+  course test that pins it by number moves to 31. Along the way:
+  - v26 adds `cards`, the course's card settings with defaults applied;
+  - v27 adds `lessonExports.latex` and `lessonExports.latexPaper`, and gives
+    every `assessmentContent` item its `type`, a choice item its `options`
+    and `correctOptionId`, and a numeric item its `answer`;
+  - v28 adds `lessonExports.markdown`;
+  - v29 removes `lessons[].status`, the `editorialStatus` of the notation
+    definitions under `lessons[]` and `pages[]`, and the `status` of
+    `notation.definitions[]` and `notation.bundles[]`;
+  - v30 makes `lessons[].headings[].text` the text a reader sees (a formula
+    as it reads, a `[[key]]` term as its label), marks a heading with math
+    `math: true`, and gives each choice option `labelSegments`;
+  - v31 adds `derived`, the page's derived cards, to `lessons[].notation`
+    and `pages[].notation`. A notation definition carries `reads`, `range`,
+    `fixedIndex` and `formulaTemplate` when set, and a bundle definition
+    carries `range`.
+- **Removed exports.** `EditorialStatus` and the `status` field of
+  `SharedNotationDefinitionInput`, `NotationLessonInput`, the notation
+  definition records and `NotationPageBundle` (`explico/reference/types`);
+  `LessonDefinition.status` and `SourceDefinition.editorialStatus`
+  (`explico/curriculum/validation`); `NotationLayer`'s per-definition
+  `editorialStatus`; `CourseConventions`. A course test that builds these
+  inputs drops `status`. `estimateBoxSize` is gone from
+  `explico/reference/diagram-layout`; size a node with
+  `nodeBoxSize({ text, formula: measureFormula(latex, fontPx) })`
+  (`measureFormula` from `explico/reference/katex-measure`).
+- **`runConsistencyChecks`** no longer takes `catalog` or `conventions`
+  (step 4).
+- **Diagnostic codes.** `review-state` and `alignment-review-state` are gone.
+  A lesson that `teaches` but declares no `assumptions` now reports
+  `missing-assumptions`. Rename either code where a course test or
+  `lint-ignore.yml` names it.
+- **`resolveMathGlyphs`** returns `indices` and `derived` and takes a
+  `derive` option. A course test that compares its whole result with
+  `toEqual` sees an unresolved item carry `lenders` and a decoration carry
+  `wholeFormExplicit`.
+- **The `content` CLI's JSON** loses `draftDebt` and `lesson.status` (step
+  3). Its lists now include the last build's render findings (from
+  `build/render-diagnostics.json`) under a `render:` source, such as
+  `render:dia-too-wide`.
+- **A card layer of the course's own** (rare) implements the new
+  `CardSource.build(item, page)` and `CardSource.awayItem(item, page)` from
+  `card-manager.ts`, which carried cards need.
+
+### 16. Course CSS and browser tests
+
+Selectors and accessible names that moved:
+
+```bash
+rg -n 'float-caption__anchor|keyed-equation__(controls|copy)|float-ref-panel-jump|explico-keep-left|(notation|glossary|citation|citation-panel)-status|Keep the article left|this lesson|Lesson exports|Go to (figure|equation|table|diagram) |data-card-key="notation:' src tests
+```
+
+- **A float's chain icon is gone**: `a.float-caption__anchor` no longer
+  exists on figures, diagrams or tables. Hover or focus the float's number,
+  then use `a.float-toolbar__link`, which carries the same
+  `data-copy-link`. An equation's `button.keyed-equation__copy` is now a
+  child of `.keyed-equation`, not of `.keyed-equation__controls`.
+- **A page-local symbol's card key is scoped to its page**:
+  `[data-card-key="notation:theta-star@projectiles/optimal-launch-angle"]`,
+  not `notation:theta-star`. A shared symbol's key is unchanged.
+- **A reference card names its float in the title**: "Equation (1.1.3)",
+  "Figure 2.2.1 · …". `[data-panel-number]` moved into the title; an
+  equation's now reads "Equation (1.1.3)" rather than "(1.1.3)". The
+  "Go to …" link drops the number ("Go to the equation in Position and
+  Coordinate Systems", "Go to the table") and sits in its own row,
+  `p.float-ref-panel-links`. CSS that placed `.float-ref-panel-jump` as a
+  grid item of `.float-ref-panel-body` targets the row instead.
+- **The side column's switches** share `.explico-side-switch` (knob
+  `.explico-side-switch-knob`) in place of `.explico-keep-left` and
+  `.explico-keep-left-switch`, inside a new row, `.explico-side-controls`,
+  which now holds the fixed position. "Keep the article left" reads
+  "Article left" (its tooltip is unchanged). `[data-keep-article-left]` is
+  unchanged, and "Carry cards" is `[data-carry-cards]`.
+- **Page exports.** The group "Lesson exports" is "Page exports", and the
+  print button is "Print or save this page as PDF". The download link
+  "Download this lesson as standalone HTML" is now a "Download this page"
+  button that opens a menu. Its links are named by scope and format,
+  "Download this chapter as standalone HTML" ("… this part …", "… the whole
+  course …"), with the file's size appended in parentheses.
+- **Status hooks are gone**: `.notation-status`, `.glossary-status`,
+  `.citation-status` and `.citation-panel-status`. A glossary entry's header
+  has two columns, not three.
+- **Starlight's mobile menu**: see step 1.
+
+Visual baselines move too: card text is 14px, a figure card's picture is 80%
+of its width in the article, and diagram boxes are measured (step 13).
+
+### 17. Rule V7: a test that each figure fits on one screen
+
+Rule V7 holds a `<Figure>`'s picture (plot, key and tables) to 80% of the
+viewport height, or `rules.V7.maxPercent`, so the reader sees it with its
+caption line. Only a laid-out page knows the height, so the check runs in
+the course's Playwright suite. Add it there, at each viewport the course
+supports:
+
+```ts
+import { readFileSync } from 'node:fs';
+import { expect, test } from '@playwright/test';
+import { checkFigureFit, lessonsWithFigures } from 'explico/reference/figure-fit';
+
+const manifest = JSON.parse(readFileSync('build/manifest.json', 'utf8'));
+
+for (const path of lessonsWithFigures(manifest)) {
+  test(`${path} figures fit on one screen (rule V7)`, async ({ page }) => {
+    await page.setViewportSize({ width: 1280, height: 800 });
+    await page.goto(path);
+    const findings = await checkFigureFit(page);
+    expect(findings.map((finding) => finding.message)).toEqual([]);
+  });
+}
+```
+
+Pass `{ maxPercent }` when the course sets `rules.V7.maxPercent`, and
+`{ allow: { 'fig-…': '<reason>' } }` for a picture meant to be scrolled.
+Shorten a figure that fails, or give a square or tall plot a fixed width
+(visualizations.md, rule V7).
+
+### 18. Optional: what a course can turn on
+
+- **LaTeX source and PDF** of every chapter, each part and the course:
+  `lessonExports.latex: true`, and `lessonExports.latexPaper: "a4"` for A4
+  (the default is `letter`). This needs TeX Live 2025 or later with
+  `latexmk` (LuaLaTeX by default; `EXPLICO_LATEX_ENGINE=pdflatex` switches
+  engines) and Playwright's Chromium for the figures a browser draws
+  (`pnpm exec playwright install chromium`). The TeX Live package list,
+  which includes `float` and an optional `cm-unicode`, ships at
+  `node_modules/explico/src/compiler/exports/latex/texlive-packages.txt`.
+  When `CI` is set, or with `EXPLICO_LATEX_STRICT=1`, a missing engine or
+  browser fails the build. Elsewhere the build warns, still writes the
+  source zips, and leaves placeholders for uncaptured figures.
+- **Markdown** of every chapter, each part and the course:
+  `lessonExports.markdown: true`.
+- **Carry cards from the start**: `cards.carry: true` starts every reader
+  with the switch on. A reader's own choice still wins.
+
+A course that keeps its settings in `course.settings.json` against a schema
+of its own with `additionalProperties: false` adds `cards`,
+`lessonExports.latex`, `lessonExports.latexPaper` and
+`lessonExports.markdown` to that schema first, each with a `title` and a
+`description`. `rules.V7.maxPercent` and `rules.V8.columnWidth` are in the
+engine's generated rules schema already.
+
+### 19. What readers see without a content edit
+
+None of this needs a course change, but the course's changelog says what
+readers now see (step 20):
+
+- **Cards.** Each float's number has a toolbar: Pin, Dock, Copy link. A
+  docked card can be widened, and a width menu sizes them all. "Carry cards"
+  keeps kept cards on screen and brings them to every page, each with an
+  "Opened at" link back. A symbol in a card from another lesson opens that
+  lesson's card. A reference card is titled by its number, a figure card's
+  picture is 80% of its width in the article, every card's text is 14px, and
+  footer links are outline buttons.
+- **Touch screens** get a text size control (100% to 70%), rendered by
+  `LayoutSocialIcons.astro`, which the course already wires as its
+  `SocialIcons`.
+- **Every page** has the print button and the Download menu, and Ctrl+P
+  loads the labs first.
+- **Heading anchors with math read as the heading**:
+  `#the-range-explainmotionranger-in-a-heading` is now
+  `#the-range-r-in-a-heading`. A heading whose math has no markup keeps its
+  anchor. `validate:content` names a `[[sec-…]]` that used the old one; a
+  link from outside the course needs updating by hand.
+- **Numbering.** An equation or a float in a list item or a `>` quote now
+  counts on the page as in the manifest, and one in a `:::` aside never
+  counts, so a later number can shift. `[@a; @b]` cites both sources, so a
+  reference list can gain an entry and renumber. A table one row over
+  `truncateAfter` shows whole.
+- **The rules read what a reader sees.** Rule S1 measures a heading's
+  readable text, so `\explain{…}{…}` no longer counts against the limit and
+  an `explico-allow S1` waiver kept for that reason can go. Rule N9 and rule
+  N14 no longer read a link's address, and rule N9 quotes a hand-typed
+  sub/superscript whole. A course's own rule (`courseRules`) now matches a
+  link's text rather than its address, and matches the text of a
+  `caption`, `short`, `title` or `label` prop as a paragraph of its own: a
+  `forbid` pattern can newly fail on a caption. A section reference to a
+  part's page says why it cannot resolve (rule S10).
+- **Notation.** Two notation formulas may name each other, local or shared;
+  a workaround for a local `reference-cycle` can go. A whole form survives a
+  power (`v_0^{2}`, step 10).
+- **The LaTeX book and PDF** grow nested `\left … \right` brackets outward
+  as the website does (rule N17), link a formula's notation markers to the
+  notation appendix, number citations as the page does, and set Greek,
+  Cyrillic, CJK and emoji prose from fallback fonts.
+- **Smaller fixes**: Copy LaTeX keeps a space after a control word, search
+  indexes a formula once, a wide equation fades at its cut edge, the splash
+  hero prints its light image, and a pinned card waits while its section is
+  folded.
+
+### 20. Record and check
+
+Cards changed without a content edit (an instance now opens its family's
+card, a power no longer breaks a whole form, a bare symbol lost a borrowed
+card), and so did what step 19 lists. Add a `content/CHANGELOG.md` bullet
+(rule C1) that says what readers now see, and bump `about.version` (rule C2:
+MINOR for new entries, MAJOR if a notation key was renamed, as in steps 7
+and 14). Then:
+
+```bash
+pnpm validate:content; pnpm validate:content
+pnpm content check --changed
+pnpm exec astro check
+pnpm exec astro build
+pnpm test          # unit tests (step 15)
+pnpm test:e2e      # browser tests, if the course has them (steps 16–17)
+```
+
+`validate:content` must report no `retired-key`, `index-*`,
+`derived-key-taken` or `unresolved-glyph` error, and no
+`config-deprecated-key` warning. `astro build` must report no lab or diagram
+N23 finding. Each `lab-picture-undrawn` and `dia-too-wide` it prints is
+either fixed or deliberate.
+
 ## 0.11.1 → 0.12.0
 
 **Course changes may be required.** Four changes can fail a build that