explico 0.13.1 → 0.15.0

package/docs/authoring/migrating.md

@@ -16,16 +16,26 @@ The pattern every time:
 
 1. Record the currently installed version before changing it:
    `node -p "require('explico/package.json').version"`.
-2. `pnpm add -D explico@<version>`.
-3. Read this file from the newly installed package and apply **every** section
+2. `pnpm add explico@<version>`, without `-D`: pnpm then updates the block that
+   already lists `explico`, `dependencies` or `devDependencies`. `-D` would move
+   the entry into `devDependencies`.
+3. `pnpm content migrate` prints exactly those sections: from the version
+   `package.json` pinned at HEAD to the one now installed, oldest first
+   (`--from` and `--to` override either end), and refuses when a section is
+   missing. Apply **every** section it prints. Reading this file whole instead
+   costs forty thousand tokens for the one or two sections an upgrade needs.
+   Without the verb, apply every section
    after the old version through the target version, oldest first. Do not skip a
    section merely because its changelog entry is not labelled **Breaking**.
 4. Make every required course-side change named by those sections, including
    changes under `content/`, Astro/source configuration, and course scripts; do
    not stop after changing the dependency declaration.
-5. `pnpm validate:content` (run it **twice** — the first run regenerates
-   `build/resolution/*` and reports it stale; the second is clean), then
-   `pnpm content check --changed`, then `astro check`, then `astro build`.
+5. `pnpm content verify` (0.15 and later), or by hand: `pnpm validate:content`
+   (it rewrites `build/resolution/*` and fails only on a report git tracks that
+   it had to rewrite: a course whose `build/` is git-ignored passes on the
+   first run, one that commits it commits the rewritten reports and runs it
+   again), then `pnpm content check --changed`, then `astro check`, then
+   `astro build`.
    Each stage names what it doesn't like; fix and re-run.
 
 The engine never fails silently on a migration it can detect: a missing
@@ -33,18 +43,1159 @@ required config block throws with the section of this file to read.
 
 ---
 
+## 0.14.0 → 0.15.0
+
+**No course changes required.** This release adds verbs (`content help
+<verb>`, `content verify`, `content release`, `content fix --all`), rule D11's
+`deck-stale` info, and better messages; the manifest schema stays v37. Two
+steps are conditional: a course that ran `content move --write` on 0.14.0
+(step 4), and a course whose tests read the CLI's text output (step 6).
+
+### 1. Update the dependency
+
+```bash
+pnpm add explico@<this version>
+```
+
+pnpm 11 holds back a release younger than its `minimumReleaseAge`: either
+`pnpm add` stops with `ERR_PNPM_NO_MATURE_MATCHING_VERSION`, or pnpm adds an
+`explico@<version>` line to `minimumReleaseAgeExclude` in
+`pnpm-workspace.yaml` itself. Add that line when it does not, and commit it.
+
+### 2. Rule D11: a deck whose chapter moved on — nothing to do
+
+Rule D11 adds an info diagnostic, `deck-stale`, naming a lesson's own deck
+whose chapter changed, by rule C5's version, after the deck itself last did. A
+part's deck covers several chapters and is never flagged. Nothing to
+configure; a course without decks sees nothing.
+
+### 3. Optional: let `pnpm content verify` be the course's verification
+
+`pnpm content verify` runs `validate:content`, `content check --changed`,
+`astro check`, the course's `test` script and `astro build` (with `--e2e`, its
+`test:e2e` script too), and answers at once on a tree its last pass covered. It
+reaches a course through the `scripts/content.ts` shim of 0.14.0 step 14 and
+needs nothing else. Where the course's `AGENTS.md`, README or `package.json`
+spells that sequence out by hand, it can say `pnpm content verify` instead; a
+`verify` script becomes `"verify": "pnpm content verify"`. The pass record and
+the logs go to `node_modules/.cache/explico/verify/`, never into the tree.
+`astro check` is skipped, by name, when `@astrojs/check` is not installed.
+
+### 4. Only if you ran `content move --write` on 0.14.0: the card's placeholder body
+
+0.14.0's `content move` wrote every card it created a placeholder body,
+"Promoted from `<lesson>`'s `notation.local`; the meaning above is what that
+page said. Extend this body with what a glossary reader needs.", which the
+glossary publishes. Find them:
+
+```bash
+grep -rl "Extend this body with what a glossary reader needs" content/notation
+```
+
+Replace each with what a reader needs beyond the meaning, or delete the body
+(a card needs none). Check those cards' `domain:` too: 0.14.0 wrote `general`
+for a key without a prefix. From this release `move` writes no body, takes the
+domain the course's own cards use, and says what the author still owes.
+
+### 5. Rule N4's lints: better advice, and the run log counts them — nothing to do
+
+`definition-repeated` on a local entry whose glyph a shared card already owns
+no longer says "move one copy to `content/notation/`": the entry is a reused
+letter (rule N4), and promoting it would put two shared cards on one glyph. It
+says how to acknowledge the copies instead (`definition-repeated:<key> — <why>`
+in `lint-ignore.yml`), and `content move` cautions before writing such a card.
+`validate:content`'s run log records each consistency warning at WARNING now,
+so the `Run log: (… warning(s))` line it prints matches `pnpm content status`
+where it used to say 1; nothing fails on a warning.
+
+The `explain-redundant` infos an upgrade to 0.14.0 left (a thousand, in one
+course) clear in one plan: `pnpm content fix --all` shows the diff and
+`--write` applies it. It edits lessons, so it is a content change: a bullet in
+`content/CHANGELOG.md` (rule C1) and the version bump rule C2 asks for.
+
+### 6. Only if a course test reads the CLI's text output
+
+The `--json` reports did not change; a test that reads them keeps passing, and
+`pnpm content help <verb> --json` now prints each one's JSON Schema. The text
+did change:
+
+- `pnpm content help`: every usage line ends in `[--json]`; `release`,
+  `verify` and `help` are listed, and `fix` reads `<lesson>… | --all`.
+- `content check`: a lesson's info is one line counted by code
+  (`+ 28 info (…)`); errors and warnings are listed as before.
+- `content status`: at most six of the pages with unreleased changes, then
+  `… N more in --json`.
+- `content context`: `diagnostics: N (M in <file>, K in the shared cards it
+  shows)` when some come from the cards.
+- `content init-agent`: `new` or `differs from the engine's copy` where it
+  said `installed` or `refreshed from the engine`; after `--write` every edit
+  verb prints a `next:` line.
+- `dia-too-wide` on `<CurriculumMap>`'s graph (rule V8) names the map's props.
+
+Match the `--json` instead of the text.
+
+### 7. Optional: refresh the agent procedures; content releases with `content release`
+
+`pnpm content release [major|minor|patch]` cuts a content release (rule C3):
+`## [Unreleased]` in `content/CHANGELOG.md` becomes a dated `## [x.y.z]` and
+`about.version` becomes `x.y.z`, as a diff that `--write` applies. With no
+argument the bump is what the section's headings imply under rule C2
+(`### Breaking` or `### Removed` a MAJOR, `### Added` a MINOR, else a PATCH);
+check it against the rule. Then `pnpm validate:content` and commit the three
+files together. 0.14.0's `release-content` skill called
+`pnpm release:content`, a script only the playground had; a course that wrote
+its own can make it `"release:content": "pnpm content release --write"`.
+
+`pnpm content init-agent --write` refreshes the installed skills:
+`draft-lesson` and `migrate-course` now end on `pnpm content verify`, and
+`release-content` runs `pnpm content release`. It never edits an existing
+`AGENTS.md`; the shipped baseline
+(`node_modules/explico/docs/course-agent/AGENTS.md`) shows the two lines to
+copy: `pnpm content verify` before handing back (step 3), and
+`pnpm content help <verb>`, which prints a verb's flags and the shape of its
+`--json` ([`cli.md`](cli.md) has every verb).
+
+### 8. Verify
+
+```bash
+pnpm content verify          # add --e2e when the course has browser tests
+```
+
+The manifest schema did not move, so a course that commits
+`build/resolution/` sees no rewritten report, and `content/versions.json`
+changes only where step 4 or step 5 edited content.
+
+## 0.13.1 → 0.14.0
+
+**One course change is required, two are recommended, and a rare page needs
+one.** Required: run `pnpm validate:content` once and commit the
+`content/versions.json` it writes, the record of each page's own version
+(rule C5, step 10); in CI the build fails until it is committed. Recommended:
+`astro.config.mjs` keeps working as it is, but Astro 7.3 deprecates the flat
+`markdown.remarkPlugins`, `markdown.rehypePlugins` and `markdown.remarkRehype`
+(every `astro` command prints "Pass them to `unified({...})` from
+`@astrojs/markdown-remark` directly instead.", and `astro check` reports a
+`ts(6385)` hint wherever course code reads them), and its default processor is
+now Sätteri, which runs neither list. Until the lists are removed Astro moves
+them onto a `unified()` processor for the course. The manifest schema is now
+v32 (step 10). **One new error can appear:** rule N4 now reads the math in a notation
+entry's body, and the build fails on an entry whose body did not render
+(step 9); no known course has one. The rest is optional or rare: a package
+that now loads, a prop on `<CurriculumMap>`, four glyph-resolver fixes (step 4), one of which can turn
+an ambiguous `x_{12}` into an `ambiguous-base-fallback` error, lab fixes
+(step 5), and, only for a course whose CSS or browser tests reach into a
+diagram's markup, the phone's text size or the `[?]` panel, a diagram that now
+shrinks with the phone's text size inside a new frame element (step 6), a
+contrast fix for an active term link (step 7), and a new tooltip on the
+Download button (step 8). A course with the LaTeX export can turn on a
+compile cache (step 13); `scripts/content.ts` and `scripts/compile-manifest.ts`
+become three-line shims over the engine, which brings every new `content` verb
+and rule C5 to a course that skipped it (step 14); `validate:content` now passes on its
+first run and every diagnostic names its rule (step 15); rule N4's lints now
+follow the tier model, which retires the acknowledgements for reused letters
+and adds a warning and two infos to clear (step 20). The glossary page now
+lists page-bound meanings under its index and a formula's symbol list names
+every symbol (step 21): nothing to do unless course CSS or tests read them. A lesson can now have
+a deck, its slide edition; nothing changes until a course writes one (step 16),
+and the sidebar then lists its lesson once, with a setting and a reader's
+switch for which edition leads; the manifest schema is now v34 (step 17). A
+deck's page shows which slides Present mode has shown each reader, above each
+frame and on a slide map, and presents from any frame; the manifest schema is
+now v35 (step 18). A part can have a deck of its
+own, the lecture of the whole part; nothing changes until a course writes one,
+and the manifest schema is now v36 (step 19); in the sidebar it then shares
+its Overview's row (step 22). The sidebar now marks the pages a
+reader has not opened yet and those changed since (step 11), and every
+course now asks each reader before it keeps their reading in the browser
+(step 12); nothing to do unless a course wants either off, but a course's
+browser tests that expect kept cards to survive a restart need a setup line.
+Add a course-owned 404 page and an Astro `site` value to replace the fallback
+and clear its two build warnings (step 24). The header, the sidebars and a
+deck's slides now have colours and edges of their own, from a new
+`appearance` setting; nothing to do unless screenshot tests or course CSS
+read them, and the manifest schema is now v37 (step 25). The engine now supplies an empty
+English `i18n` entry when a course has no translations, so the old empty-`i18n`
+warning needs no course workaround.
+
+### 1. Update the dependency
+
+**A course on 0.13.0 or 0.13.1, first:** delete the downstream patch that
+added `dist/components/float-name.js` to the installed package
+(`patches/explico@0.13.1.patch`) and its `patchedDependencies` entry, in
+`pnpm-workspace.yaml` or under `pnpm` in `package.json`, and any test that
+pins the old path. This release compiles the module as
+`dist/reference/float-name.js`, which the export serializers import, and
+pnpm refuses the upgrade with `ERR_PNPM_UNUSED_PATCH` while an entry names a
+patch for a version no longer installed. Then:
+
+```bash
+pnpm add explico@<this version>
+```
+
+pnpm 11 holds back a release younger than its `minimumReleaseAge`: either
+`pnpm add` stops with `ERR_PNPM_NO_MATURE_MATCHING_VERSION`, or pnpm adds an
+`explico@<version>` line to `minimumReleaseAgeExclude` in
+`pnpm-workspace.yaml` itself. Add that line when it does not, and commit it
+with the upgrade.
+
+**Coming from 0.12.0 or earlier:** apply "0.13.0 → 0.13.1" and "0.12.0 →
+0.13.0" below first.
+
+### 2. Move the plugin lists into `markdown.processor`
+
+Only when `astro.config.mjs` still has `markdown.remarkPlugins`,
+`markdown.rehypePlugins` or `markdown.remarkRehype`:
+
+```bash
+rg -n 'remarkPlugins|rehypePlugins|remarkRehype' astro.config.mjs src scripts
+```
+
+Import `unified` and hand it the same lists:
+
+```js
+import { unified } from '@astrojs/markdown-remark';
+
+export default defineConfig({
+  // …
+  markdown: {
+    processor: unified({
+      remarkPlugins: [/* the entries markdown.remarkPlugins had, in order */],
+      rehypePlugins: [/* the entries markdown.rehypePlugins had, in order */],
+      // remarkRehype: { … }   // only when you set one
+    }),
+  },
+});
+```
+
+Keep the order: `remarkAsides` stays last in `remarkPlugins`. Nothing in
+explico needs the flat form: `explicoContentRefresh()` checks the
+manifest-driven plugins (`remarkAbbreviations`, `remarkCitation`,
+`remarkNotation`) on both surfaces, MDX extends `markdown.processor`, and
+Starlight 0.42 appends its own plugins to it. Course code that reads
+`markdown.remarkPlugins` (a test that asserts the wiring, a script) reads
+`markdown.processor.options.remarkPlugins` instead. The playground's
+`astro.config.mjs` is a worked example; the time-series course made this move
+and all 141 of its built pages came out byte-identical.
+
+### 3. Only if a competency graph warns `dia-too-wide`
+
+A course with many competencies gets `[dia-too-wide] curriculum-map/index.html:
+Diagram "competency-graph" …` (rule V8) on the curriculum map, because the
+graph is one diagram. `<CurriculumMap>` now takes three optional props, all
+forwarded to the competency diagram(s); with none of them the page is
+unchanged:
+
+```mdx
+<CurriculumMap graph="per-part" />
+```
+
+- `graph="per-part"` draws one diagram per part, in the order of
+  `course.settings.json` `parts`, under an `<h3>` with the part's overview
+  title (its label when it has none). A diagram holds the competencies the
+  part's lessons teach first and one box per earlier competency they build on,
+  labelled `<part>: <competency>`; competencies no lesson teaches form a last
+  group. The ids are `competency-graph-<part dir>` and
+  `competency-graph-untaught`. The default is `graph="whole"`.
+- `direction="LR"` lays the diagrams out left to right (`TB` is the default).
+- `warnAboveWidth={false}` (or a width in px) replaces rule V8's column width
+  for these diagrams, for a whole-course graph that is meant to scroll.
+
+### 4. Rule N23 and the glyph resolver: findings that go away, one that can appear
+
+Four resolver fixes change what `validate:content` reports, and one message is
+clearer; none needs an edit to pass. Look for the workarounds they make
+unnecessary, and for one new error:
+
+- **`index-range` for a letter that is not an index.** `b` in `\nabla_{b_n}`
+  (the base of a carded symbol in a subscript) and the letters of a subscript
+  with a relation (`\mathbb{E}_{Z \sim g}`) are no longer running indices. A
+  `range` you gave the card of `b_n` only to silence `b`, and a
+  `fixedIndex: true` on a density `g` that only appeared in a condition, can
+  be deleted. `n` of `b_n` still needs its set, once per page.
+- **A family of juxtaposed letters now reaches its instances.** `x_{ij}`,
+  `K_{ij}`, `r_{ik}` give their card to `x_{i1}`, `x_{12}`, `K_{ji}` (which
+  failed rule N4 as unresolved): a run of as many letters and digits. `\explain{responsibility}{r_{i1}}` wraps that you
+  added so an instance found its card are harmless and can stay or go. **A page
+  that has both `x_{ij}` and `x_k` as entries now fails
+  `ambiguous-base-fallback` on `x_{12}`**, which both fit: wrap that instance
+  in `\explain{key}{x_{12}}` for the one you mean.
+- **An `\explain` in an instance's subscript** (`\beta_{\explain{count}{K}}`)
+  keeps the family's card on the instance. The workaround `\explain{beta-j}{\beta_{\explain{count}{K}}}`
+  resolves to the same markup, so nothing needs to change.
+- **A wrapped instance is not re-bound inside.** `\explain{component-sd}{\sigma_1}`
+  no longer wraps the `\sigma` in a plain `\sigma` entry's card, so a page that
+  kept the wrap off to avoid that can add it back. Rendered pages that had the
+  inner card change: re-record screenshots of a hovered σ.
+- **A clearer `unresolved-glyph` for an instance of a family whose index a card
+  fixed.** Marking the card of `m` `fixedIndex: true` makes the family `r_m` a
+  single symbol, so `r_2` is no longer its instance. The error used to say
+  "never a bare r" and suggest `\explain{periodic-rate}{r}`; it now names the
+  card that fixed `m` and suggests a `range` on it. The same error, only its
+  text and two new fields on the unresolved item (`instance`, `fixedLenders`
+  of `resolveMathGlyphs`) change, so a test that matched the old sentence for
+  such a symbol moves. A course that cleared an `index-range` error with
+  `fixedIndex: true` on a letter that also indexes a family (`m` under `r_m`)
+  and then wrapped the instances can give that card a `range` instead and
+  delete the wraps.
+
+### 5. Lab math: workarounds you can drop
+
+Three fixes touch what a lab template and the build do with a figure. None
+needs an edit, and each makes an earlier workaround unnecessary:
+
+- **`e`, `\pi`, `i` and `d` in a lab template** no longer fail the figure check
+  ("figure symbols without a notation card"), so the notation cards a course
+  added only to bind Euler's number or the circle constant in a template can go
+  if nothing else uses them. An index (`e_i`, rule N23), a decorated letter
+  (rule N22) or a styled one still needs one.
+- **A key only a lab template binds** now reaches the page's card payload. A
+  course that also named every such key in the lesson's prose so the card
+  would ship can stop doing so.
+- **`lab-katex-direct` is one error per lesson that reaches a KaTeX-importing
+  helper**, not one per helper. A script that tallies the diagnostics by file
+  sees more of them, and `pnpm content check <lesson>` now answers for that
+  lesson alone. `astro build` reports every page with an unbound figure symbol
+  in one failure, not the first.
+
+### 6. Only if your course CSS or browser tests reach into a diagram, the text size or the `[?]` panel
+
+Nothing in `content/` or `course.config.ts` changes, and the manifest schema
+stays v31. These are changes to markup and behaviour that course CSS and
+browser tests can depend on:
+
+- **A diagram has a new frame element.** The markup is now
+  `.diagram-scroll > .diagram-frame > .diagram-canvas > svg`. A selector that
+  takes `.diagram-canvas` as a *child* of `.diagram-scroll`
+  (`.diagram-scroll > .diagram-canvas`) must become a descendant selector
+  (`.diagram-scroll .diagram-canvas`). `--diagram-width` and `--diagram-height`
+  moved from the canvas to the frame; the canvas inherits them, so
+  `getComputedStyle(canvas).getPropertyValue(…)` still reads them, but
+  `canvas.style.getPropertyValue(…)` no longer does.
+- **The phone's text size is 50, 59, 71, 84 and 100%** (it was 100, 90, 80 and
+  70%), smallest first. A reader's saved 90, 80 or 70 is ignored and the page
+  opens at 100% until they choose again; no action. A browser test that picks
+  a size or asserts the root font size must use the new values:
+  `data-text-size="84"` is 13.44 px, `71` is 11.36 px, `59` is 9.44 px, `50` is
+  8 px.
+- **A diagram shrinks with the text size as a whole**, boxes and text,
+  through `transform: scale(var(--explico-text-scale))` on `.diagram-canvas`
+  and a scaled `width`/`height` on `.diagram-frame`, on a touch screen with a
+  size chosen. A test that reads a node's `getBoundingClientRect()` then sees
+  scaled numbers, and `.diagram-canvas`'s `offsetWidth` stays the build-time
+  size (it ignores the transform): measure the frame or the scroller's
+  `scrollWidth`. Course CSS must not set `transform`, `width` or `height` on
+  `.diagram-canvas` or `.diagram-frame`. A diagram inside a preview card is not
+  scaled. Print is unchanged. `node_modules/explico/docs/diagram-scaling.md`
+  has the reasons and the rules for changing it.
+- **The `[?]` panel on a phone** is a sheet fixed under the header below 50rem
+  (`.about-body`), no longer an absolute box hanging from the button. Delete a
+  course override of `.about-body`'s position or width that worked around the
+  old placement, and any rule that restyled the `[?]` button's `summary`
+  inside `.layout-navigation-content`: the button is round there now.
+- **A hover peek no longer overwrites a collapsed section's saved state.** A
+  reader whose choice was already overwritten stays open until they collapse it
+  again. A browser test that collapses a section and reloads should move the
+  pointer away first (`page.mouse.move(0, 0)`): with the pointer left on the
+  heading, the section peeks (`data-state="peeking"`) after the reload, as it
+  should, and asserting `closed` at once races that.
+
+### 7. Only if your course CSS lifts the contrast of an active term link
+
+0.13.1 blended the highlight of every active notation target, a prose term
+link (`a.notation-term`) included, and in the light theme that took the
+engine's own link colour below 4.5:1 over a tinted panel (axe `color-contrast`
+in a glossary entry). This release blends a symbol inside `.katex-html` only;
+a prose link keeps the opaque `--sl-color-accent-low` tint it had on 0.13.0.
+
+```bash
+rg -n 'notation-term.*is-notation-active|is-notation-active.*notation-term' src content tests
+```
+
+A hit is the workaround for that fault, such as
+`a.notation-term.is-notation-active { color: var(--sl-color-accent-high); }`.
+Delete it; the link text is 4.75:1 on the tint without it. Run the course's
+axe checks over a glossary page with a hovered symbol to confirm.
+
+### 8. Only if a browser test reads the Download button's tooltip
+
+The header's Download button (`button.lesson-export-actions__download`) had
+`title="Download this page"` on every page. Its `title` now names the scopes
+the menu offers there: "Download this chapter, this part or the whole course"
+on a chapter, "Download this part or the whole course" on a part's page and
+"Download the whole course" on any other page. **Its accessible name is
+unchanged**, so `getByRole('button', { name: 'Download this page' })` still
+finds it.
+
+```bash
+rg -n "Download this page" tests src
+```
+
+A hit that selects the button by role and name needs nothing. One that matches
+`title`, `getByTitle` or `[title="Download this page"]` takes the new text, or
+better selects by role and name.
+
+### 9. Rule N4 now reads a notation entry's body
+
+`validate:content` resolves every `$…$` / `$$…$$` in the Markdown body of a
+`content/notation/*.md` entry, against every shared entry, as the glossary's
+render already did. Before, a symbol no entry binds there passed
+`validate:content`, `astro build` logged one `[ERROR] [glob-loader]` line and
+ended green, and the glossary showed the entry without its body. Now:
+
+- `validate:content` reports `[N4 unresolved-glyph] content/notation/<key>.md:<line>`
+  (or `invalid-latex`, `currency-dollar`, … for the other faults) at the
+  file's own line. Fix it in the entry: give the symbol an entry of its own in
+  `content/notation/`, or wrap it in `\explain{key}{latex}` with the entry it
+  stands for. `[[key]]` adds nothing here, since every shared entry is already
+  in scope, and an entry has no `notation.local`.
+- `astro build` fails at the glossary with "Notation entries whose body did not
+  render: …" for an entry whose body Astro could not render, whatever the
+  cause. The `[glob-loader]` error above it in the log says why.
+- `astro build` reports a notation entry's failure at the file's own line, and
+  an unresolved-glyph error ends its token list with `, in $…$`. A script or
+  test that parses `entry.md:<line>` from the build log no longer needs to add
+  the frontmatter's height.
+- An entry's body now honours `fixedIndex` (rule N23): `r_2` no longer takes
+  the card of the family `r_m` when `m` is marked `fixedIndex: true`. Give the
+  instance an entry or an `\explain` wrap, or the letter a `range` if it runs.
+
+A course test that resolves the entry bodies itself (credit-and-derivatives'
+`tests/notation/notation-entry-body-math.test.ts`) can be deleted once
+`validate:content` passes: the gate covers it, against the same table.
+
+### 10. Commit `content/versions.json`, each page's own version (rule C5)
+
+Each chapter and part page now carries the knowledge version its content last
+changed in, under the title of its PDF, in its source zip's README, under the
+title of its Markdown, and in the `[?]` panel's new "This page" row:
+"unchanged since version 0.2.0", or "with changes after version 0.4.0, not yet
+released" while `## [Unreleased]` holds a change. A part's and the course's
+PDF and Markdown carry the newest among their pages. The record is
+`content/versions.json`, which `validate:content` writes and the course
+commits like a lockfile; never edit it by hand. The manifest schema is now
+v32 (`lessons[].since`, `parts[].overview.since`, `about.knowledge.releases`
+and `unreleased`, `pageVersions`).
+
+```bash
+pnpm validate:content        # prints "content/versions.json written — commit it with the change (rule C5)"
+git add content/versions.json
+```
+
+Commit it with the upgrade. From then on `validate:content` rewrites the file
+after a content change and after a release (`pnpm release:content`, then
+`pnpm validate:content`), and the file goes in the same commit. In CI (`CI`
+set) `validate:content` does not write; a record that would change fails with
+`[C5 page-versions-stale] content/versions.json is out of date (N page(s): …)`
+until the commit carries the file. The first record has no history to draw
+on: while `## [Unreleased]` holds bullets, every page reads "with changes after
+version `x.y.z`, not yet released", `x.y.z` being `about.version`, until the
+next release stamps them all; with an empty `## [Unreleased]`, every page reads
+"unchanged since version `x.y.z`". Earlier releases are not reconstructed. So
+the order matters: write the first record before adding the upgrade's own
+bullet under `## [Unreleased]` (rule C1), or every page reads "not yet
+released" although none changed.
+
+What counts as a page's content: its file, its `.checks.yml` and the
+assessments it lists, the shared notation entries its text uses, the sources
+it cites, and its numbers. A lab, `content/domain/`, a part's label or the
+engine change the PDF but not the stamp.
+
+What else moves:
+
+- The downloads' version line. `From Course, version 0.4.0.` under a
+  chapter's title is now `From Course, unchanged since version 0.2.0.`; a
+  book's title page says `Content unchanged since version 0.2.0` where it
+  said `Content version 0.4.0`; the zips' READMEs `(unchanged since version
+  0.2.0)` where they said `(content version 0.4.0)`; Markdown the same. A
+  test that reads these lines reads the new ones.
+- A document unchanged since an earlier release keeps that release's date in
+  its PDF and figure PDFs (`SOURCE_DATE_EPOCH`) and its trailer `/ID`. With
+  `EXPLICO_LATEX_CACHE` (step 13) a release therefore recompiles only the
+  documents it changed.
+- A browser test that reads the `[?]` panel finds a `This page` row with
+  `[data-page-since="0.2.0"]` (`"unreleased"` for a change not yet released)
+  on chapters and part pages, none elsewhere.
+- `pnpm content status --json` reports `pageVersions: { tracked, unreleased }`
+  and `content context` a lesson's `since`. Optional: print them in the
+  course's `scripts/content.ts`, and end `scripts/release-content.ts` with a
+  reminder to run `validate:content`; the playground's copies show both.
+
+To opt out, turn the rule off in `course.settings.json`:
+`"rules": { "C5": { "enabled": false } }`. Every page then carries the
+course's version as before, and no file is read or written.
+
+### 11. The sidebar's marks: nothing to do, unless you want them off
+
+The sidebar now marks, for each reader, the chapters and part pages they
+have not opened yet (a quiet ring) and those whose content changed since they
+last opened them (an accent dot), with a line under the chapter list that
+says what the marks mean and offers "Mark all as seen" and "Mark all as
+unseen". "Changed" uses the
+page hashes of `content/versions.json` (step 10), so it needs nothing new
+from the course. Both marks are on by default.
+
+To turn either off, add the block to `content/course.settings.json`:
+
+```json
+"sidebarMarks": { "unopened": false, "changed": true }
+```
+
+and, when the course keeps a settings schema with
+`"additionalProperties": false` (the playground's
+`content/course.settings.schema.json` does), copy the playground's
+`sidebarMarks` property into it, or the settings form flags the block.
+
+Only if a course's CSS or browser tests reach into the sidebar:
+
+- A marked row's `<li>` carries `data-page-mark="unopened"` or `"changed"`,
+  and draws the mark with its `::after`; a `<details>` part carries
+  `data-page-marks`, and so does `.layout-navigation-panel`. Course CSS that
+  sets `li::after` in the sidebar competes with the mark.
+- A marked link gains `aria-describedby`, naming the mark ("Not opened yet",
+  "Changed since you last opened it"); its accessible name is unchanged.
+- The legend (`.explico-page-marks-legend`) follows the sidebar's list
+  whenever the reader's record is kept, with a mark on screen or none. It
+  holds the two buttons (`.explico-page-marks-legend__action`, `aria-disabled`
+  while one has nothing to change) and a `role="status"` paragraph,
+  empty until a button is used. A test that finds `getByRole('status')` on
+  the whole page sees one more wherever the legend is.
+- A compact part's chapter tile is one sheet, where it was two (its
+  `::before` has no `box-shadow`); the Overview tile keeps its two sheets.
+  Pointing at a part's `»`, or focusing it, lights the part's Overview row or
+  tile as a pointer on it would. No course change is required.
+- The marks are reading memory (step 12): a fresh browser profile shows none
+  until the reader says yes to the course remembering their reading. After
+  the yes, every chapter but the open one is "not opened yet".
+
+### 12. The reading-memory question: nothing to do, unless your tests or CSS need it
+
+Every course now asks each reader, once, whether it may remember their
+reading in this browser: a small card at the bottom of the window ("Remember
+your reading?", "Remember" / "Don't remember"), on every page until they
+answer. Reading memory is the chapters they opened (the sidebar marks, and
+the new line under a changed page's title) and the explanation cards they keep
+open or carry, across visits. Until a yes, and after a no, none of it
+outlives the tab; kept and carried cards still work within the tab, through
+its session storage. Settings the reader chooses (theme, text size, panel
+layout, folded sections, the "Carry cards" switch) are kept as before. The
+answer stands 13 months; the `[?]` panel's new "In this browser" section
+changes it or forgets everything. The site sets no cookies, and nothing leaves
+the browser.
+
+To never ask, and never keep reading memory (the sidebar marks are then off,
+and cards last as long as the tab), set it in `content/course.settings.json`:
+
+```json
+"readingMemory": "off"
+```
+
+and, with a settings schema that sets `"additionalProperties": false`, copy
+the playground's `readingMemory` property into it.
+
+Only if the course has browser tests, or CSS that reaches into the page:
+
+- **A test that expects kept or carried cards to come back after a browser
+  restart, or in a new tab**, starts from a browser without the answer, so the
+  cards stay in the old tab. Start such specs from a yes: in
+  `playwright.config.ts`, `use.storageState` with the localStorage entry
+  `explico-reading-memory:<base path>` set to
+  `{"v":1,"remember":true,"at":"<today, YYYY-MM-DD>"}`. The playground's
+  `tests/e2e/reading-memory-state.ts` builds it (`rememberReadingState(origin,
+  base)`), and its `playwright.config.ts` uses it. A context a spec opens itself
+  with `browser.newContext()` does not inherit `use`; pass the same
+  `storageState`, or copy the first context's (`await
+  context.storageState()`).
+- **A screenshot of a page from an empty browser** now shows the question
+  along the bottom of the window. The same `storageState` keeps it out.
+- **A test that counts `getByRole('status')`** finds one more per copy of the
+  `[?]` panel (its "Forgotten" line, empty until used).
+- **Course CSS**: the question is `.explico-reading-notice` (moved to the end
+  of `<body>` by its script), the panel's section `.about-browser`, the line
+  under a changed page's title `.page-changed`.
+- **Opening a page no longer writes its sections' open/closed state** to the
+  browser; a test that read `disclosure:<path>:<section>` keys right after a
+  page loaded finds none until the reader folds or opens a section.
+
+### 13. Optional: reuse the PDFs a build already compiled
+
+Only for a course with `lessonExports.latex: true`. Nothing changes until
+`EXPLICO_LATEX_CACHE` is set; then the LaTeX export compiles only the
+documents whose folder changed (a chapter, its part and the course, for a
+push that touches one chapter) and reuses the rest from that directory. Set
+it in the CI job that builds, and keep the directory between runs:
+
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: .cache/explico-latex
+    key: explico-latex-${{ github.sha }}
+    restore-keys: explico-latex-
+- run: pnpm build
+  env:
+    EXPLICO_LATEX_CACHE: .cache/explico-latex
+```
+
+Add the directory to `.gitignore`. The build's `LaTeX export:` line now says
+how many PDFs it compiled and reused. After a `tlmgr update` that the cache
+cannot see (a font or a package, not a TeX Live release), set
+`EXPLICO_LATEX_CACHE_SALT` to any new value once. With step 10 a document's
+version line and date are its own, so a content release (rule C3), too,
+recompiles only the documents whose pages it changed, their parts and the
+course.
+
+### 14. Replace `scripts/content.ts` and `scripts/compile-manifest.ts` with the engine's shims
+
+The `content` CLI and `validate:content` now live in the engine
+(`explico/compiler/cli-main`, `explico/compiler/validate-content`), so every
+verb reaches a course with the package instead of being ported by hand. Replace
+both files whole:
+
+```ts
+// scripts/content.ts
+import { runContentCli } from 'explico/compiler/cli-main';
+import { courseConfig } from '../content/course.config';
+
+process.exitCode = await runContentCli(courseConfig);
+```
+
+```ts
+// scripts/compile-manifest.ts
+import { runValidateContent } from 'explico/compiler/validate-content';
+import { courseConfig } from '../content/course.config';
+
+process.exitCode = await runValidateContent(courseConfig);
+```
+
+`package.json` keeps `"content": "tsx scripts/content.ts"` and
+`"validate:content": "tsx scripts/compile-manifest.ts"`. `pnpm content help`
+then lists every verb: `status`, `diagnostics`, `warnings`, `context`,
+`equation`, `bindings`, `symbol`, `check`, `rule`, `migrate`, `rules`, `move`,
+`rename`, `fix`, `new lesson | deck | term`.
+
+What a course gains or changes by the swap:
+
+- **New verbs:** `symbol` (where a symbol is already defined), `rule <ID>`
+  (one rule whole), `bindings <lesson>` and `equation "<latex>"` (what math
+  binds, before a build), `migrate` (this guide's sections between two
+  versions), and the write verbs `move`, `rename`, `fix` (a diff, applied only
+  with `--write`; `move` is how a `definition-repeated` warning, step 20, is
+  cleared in one command).
+- **`validate:content` refreshes `content/versions.json` (rule C5, step 10)
+  and the resolution reports.** A course whose script did not call
+  `syncPageVersions` or `syncResolutionReports` (data-science-I and
+  time-series did not) starts writing both: commit `content/versions.json` with
+  the swap. The run fails only on a resolution report git tracks that it had to
+  rewrite, so a course whose `build/` is git-ignored passes on its first run.
+- **Every diagnostic group gates.** Errors in curriculum, notation,
+  alignment, math, waivers, equations, tables, figures, diagrams, knowledge
+  checks, examples, folds and raw floats fail the run; warnings print; infos go
+  to `build/logs/`. A course script that added a check of its own keeps it by
+  running it after `runValidateContent` returns 0.
+- **The output is the engine's.** A course test that matched the old
+  wrapper's text should match `pnpm content help` and the `--json` shapes
+  instead; the JSON reports did not change.
+
+A course that keeps its own scripts loses only the new verbs; nothing else
+depends on them.
+
+Then, optionally, install the agent procedures that ship with the engine:
+`pnpm content init-agent` shows what it would write (the `draft-lesson`,
+`migrate-course` and `release-content` skills under `.claude/skills/`, the
+`rules-reviewer` agent under `.claude/agents/`, and a baseline `AGENTS.md`
+only when the course has none); `--write` writes it. An existing `AGENTS.md` is
+never edited: `pnpm content status` says when it does not point at
+`node_modules/explico/docs/authoring/agents.md`, and the course's file can then
+shrink to what is particular to the course — the engine's guide covers the CLI,
+the validate sequence and the notation rules.
+
+### 15. `validate:content` passes on its first run; diagnostics name their rule
+
+Nothing to do. `validate:content` still rewrites `build/resolution/*`, but it
+now fails only on a report git tracks that it had to rewrite, so a course whose
+`build/` is git-ignored passes on the first run; delete any "run it twice"
+instruction from the course's own AGENTS.md. A course that commits
+`build/resolution/` (credit-and-derivatives) keeps committing the rewritten
+files with the change, as before — and this upgrade rewrites every one (the
+schema version moved), so its first run fails with a `[resolution-report] …
+out of date` line per report. Commit them; the next run passes.
+
+Optional, in `scripts/content.ts`: print diagnostics through
+`formatCliDiagnostic` (and `ownerTag` in the `check` case), both exported from
+`explico/compiler/cli`, so every line names its rule and page
+(`[N4 · notation.md#n4]`), and add `report.agentSurfaces` to the `status`
+output. The JSON already carries `doc` and `agentSurfaces` with no wrapper
+change; the playground's wrapper is the reference.
+
+Also optional: make `content diagnostics` count by default. Pass the report
+through `summarizeDiagnostics` and print `formatDiagnosticsSummary` unless
+`--all`, `--code <code>`, `--lesson <id>` or `--changed` is given, in which
+case `filterDiagnostics` narrows it and the lines print as before (the
+playground's `diagnostics` case has the ten lines). On a course with hundreds
+of diagnostics of two codes this turns a 20 000-token dump into a 300-token
+table.
+
+### 16. Decks: nothing to do, unless the course writes one
+
+A lesson can now have a deck, its slide edition, in
+`content/docs/<part>/<lesson>.deck.mdx` (`docs/authoring/deck.md`). A course
+without one sees no change: the manifest schema is now v33, but only adds
+`decks`, `deck` and `lessons[].editions`; `build/rules-in-effect.md` lists the
+same rules as before, since the new area `D` is about decks only. Rules V7, V8,
+S1, S6 and S7 now say they are about a chapter's page.
+
+To write a deck:
+
+1. Add the verb to the course's `scripts/content.ts`, as the playground's does:
+   `new deck` beside `new lesson` (`scaffoldDeck` from `explico/compiler/cli`),
+   and the `--edition` flag on `rules` (passed to `parseRulesFilter`).
+2. If the course's `course.settings.schema.json` lists its properties with
+   `additionalProperties: false`, add the `deck` block (copy it from the
+   playground's schema) before setting `deck` in `course.settings.json`. The
+   defaults need no setting: a 16:9 canvas, a legend of first uses, notes shown
+   to readers, an outcomes frame and a handout PDF.
+3. `pnpm content new deck <part>/<lesson>` drafts the deck from the chapter.
+   Rewrite it to the deck rules before committing: rule D1 (sections of frames),
+   rule D2 (a frame fits its canvas), rule D3 (a frame makes one claim), rule D4
+   (notes on a frame with text), rule D5 (a frame title fits one line), rule D6
+   (at most `maxSteps` steps), rule D7 (one picture per frame), rule D8 (recall
+   the chapter's result, never retype it), rule D9 (few new symbols per frame)
+   and rule D10 (the engine writes the title and outcomes frames). Read
+   `pnpm content rules --edition deck` before drafting.
+4. `pnpm validate:content`, and commit `content/versions.json`: a deck beside
+   its chapter has a page version of its own (rule C5).
+
+A course wrapper around `<Figure>`, `<Table>` or `<Diagram>` and a lab that
+calls `labMathScope(…, { locals: Astro.locals, … })` need no change to be
+recalled onto a deck.
+
+In the sidebar, a deck is a play mark in a 16:9 frame, on its icon or tile and
+on a slides-first lesson's own row and tile (`a.explico-deck-lesson`); a
+lesson with a chapter and a deck is one row (step 17). The glyph is the link's
+`::before` and `::after`. On a deck's page, a reader who left Present mode
+past the first frame finds a "Continue at slide N" button
+(`[data-deck-resume]`) beside Present. No course change is required; only
+course CSS that styles the sidebar's links, or a browser test that counts the
+deck page's buttons, can notice.
+
+Once the course has a deck, its build needs a few more things:
+
+- **A browser, in CI.** After `astro build`, every deck page is laid out in
+  the course's Playwright Chromium, and a frame that runs past its canvas fails
+  the build (`frame-overflow`, rule D2). Without Chromium the build warns and
+  measures nothing, except under `CI` or `EXPLICO_LATEX_STRICT=1`, where it
+  fails. A course whose CI already captures figures for the LaTeX export has
+  the browser. Otherwise, install it in CI before the build:
+  `pnpm exec playwright install --with-deps chromium`.
+- **Beamer, with `lessonExports.latex`.** A deck compiles to slides and a
+  handout in beamer. A CI that installs TeX Live from
+  `node_modules/explico/src/compiler/exports/latex/texlive-packages.txt` gets
+  `beamer` and `translator` from the updated list. A CI with its own package
+  list adds those two.
+- **Tests of the Download menu.** A chapter with a deck has one more row,
+  "Its slides", and the deck's page has "These slides" and "Its chapter". The
+  Download button's tooltip names "the slides" too. Update a test that counts
+  the rows or reads the tooltip on such a page.
+
+### 17. A lesson is one row in the sidebar: nothing to do, unless your tests or CSS read it
+
+A lesson with a chapter and a deck is one sidebar row: it opens the **lead**
+edition under the lesson's title, and the other edition is an icon at the
+row's end (`a.layout-edition-other`, named "Slides: *title*" or "Chapter:
+*title*"), the second of two joined tiles in a compact part. A lesson with one
+edition is a row as before. Without scripts the sidebar lists each chapter,
+then its "Slides" row. The manifest schema is now v34: it adds
+`sidebarEditions`, and every item of a lesson in `sidebar` carries
+`data-edition`, `data-lesson` and `data-title` in `attrs`, so a chapter is
+`{ slug, attrs }` where it was a bare slug.
+
+No course change is required. The default leads with the chapter and lists
+the slides, and each reader can switch both in the sidebar's foot; their
+choice is a setting kept in their browser, `explico-sidebar-editions`, so a
+course privacy notice that copies `docs/privacy.md` gains that row. A course
+without a deck sees no change but the manifest's shape.
+
+- **To open lessons at their slides, or to leave the other edition out of the
+  sidebar**, set `sidebarEditions` in `course.settings.json`. If the course's
+  `course.settings.schema.json` lists its properties with
+  `additionalProperties: false`, copy the `sidebarEditions` block from the
+  playground's schema first.
+
+  ```json
+  "sidebarEditions": { "lead": "slides", "other": "listed" }
+  ```
+
+  `lead` is `chapter` (default) or `slides`; `other` is `listed` (default) or
+  `hidden`. Any other value fails the build, naming the field.
+- **A test that reads `manifest.sidebar`** and expects a chapter as a bare
+  slug reads the item's `slug`, or `sidebarLessonSlug(item)` from
+  `explico/compiler/lesson-derivation`, which gives a lesson's slug for its
+  own item and `undefined` for a slides row, an overview or a link.
+- **A browser test** that finds a sidebar link by a lesson's title adds
+  `exact: true`: the icon beside it is named "Slides: *title*". One that
+  counts the sidebar's `li` items counts one per lesson; one that clicks the
+  "Slides" row clicks the deck's `href` or `a.layout-edition-other`. A row's
+  mark is on its `li`, as before; the icon's is on the link,
+  `a.layout-edition-other[data-page-mark]`.
+- **Course CSS** that styles `a.explico-deck-row` in the sidebar: once the
+  script pairs the editions, the deck's link is `a.layout-edition-other` at
+  its chapter's row end, or carries no class while it leads; a compact tile
+  draws a deck's glyph from `a[data-edition="slides"]`. The marks' line no
+  longer draws the separator above it: the panel's foot,
+  `.explico-sidebar-foot`, holds the line and the two controls.
+- **Course CSS that redraws the sidebar's chapter or deck glyph** (the
+  `::before` or `::after` of a sidebar link or a compact tile): each glyph is
+  one SVG mask over the link's own colour, the chapter a sheet with lines of
+  text (`--explico-chapter-glyph`), the deck a filled slide frame with the
+  play mark cut out (`--explico-deck-glyph`). A border on `::before` no longer
+  shapes it, and `::after` draws nothing. To draw another glyph, set the
+  custom property on `:root` to another `url("data:image/svg+xml,…")`, black
+  where the glyph is.
+
+### 18. The slides a reader has seen: nothing to do, unless your tests or CSS read a deck's page
+
+A deck's page keeps each frame Present mode showed the reader and shows it
+frame by frame. A line above each frame says "Slide N" and "Shown", "Not shown
+yet" or "Changed since shown", and ends on a button: "Continue here" on the
+frame to continue at, "Present from here" on every other. Under the title, the
+slide map shows every frame as a numbered square, pinned under the header
+while the deck scrolls; a long deck's map leaves runs out, with a gap for
+each. A line under Present counts the marks and offers "Mark all as seen" and
+"Mark all as unseen"; the sidebar's two buttons cover every deck's frames too.
+"Continue at slide N" presents from the frame the reader stopped at, or from
+the one after it once they were shown its every step. Before the reader
+answers the reading-memory question the frames shown are kept, and marked,
+for the tab; "Remember" keeps them for later visits and "Don't remember"
+clears them. The manifest schema is now v35: every frame of `decks[].frames`
+carries `id`, 12 hex digits over what it shows, stamped on the frame as
+`data-frame-id`.
+
+No course change is required. The marks follow `sidebarMarks`, so a course
+that turned a sidebar mark off has it off on its decks too, and one with
+`readingMemory: "off"` shows none. A reader's record under
+`explico:decks:<base>` moves to its new shape on its own. The reading-memory
+question now names the slides it keeps. A course privacy notice that copies
+`docs/privacy.md` gains that row: where each deck stopped, and the frames
+Present mode showed, kept for the tab before an answer.
+
+- **A browser test** that finds the deck's Present button by name adds
+  `exact: true`: every frame's line has a button named "Present from here,
+  slide N", or "Continue here, slide N".
+
+  ```ts
+  await page.getByRole('button', { name: 'Present', exact: true }).click();
+  ```
+
+- **A browser test that reads the sidebar's status** after "Mark all as seen"
+  or "Mark all as unseen", in a course with a deck, expects "Every page and
+  slide is marked as seen." or "Every page is marked as not opened yet, and
+  every slide as not shown yet."
+- **A browser test that runs before an answer** and expected a deck's page
+  to mark nothing: it marks the frames Present mode showed in that tab, and
+  the tab's session storage holds them under `explico:decks:<base>`.
+- **A browser test that counts a deck page's links or buttons**: the slide
+  map (`nav.deck-map`) adds a link for each square and each gap, and each
+  frame's line (`.deck-frame__line`) a button.
+- **A browser test that seeds `explico:decks:<base>`**: the old shape,
+  `{ "<deck slug>": 3 }`, still reads, as a deck stopped at frame 3 with no
+  frame seen. To seed frames seen, write
+  `{ "v": 2, "decks": { "<deck slug>": { "at": 3, "step": 1, "seen": { "1": "<id>" } } } }`
+  with the ids of the frames' `data-frame-id`. `step` is the step of frame
+  `at` Present mode stood on: at that frame's last step, Continue goes on to
+  the next frame; without `step`, it stays at `at`.
+- **Course CSS** that styles a frame or the deck's actions row: a frame's
+  first child is now its line, `.deck-frame__line`, before `.deck-stage`; the
+  deck's first child is the slide map, `nav.deck-map`; "Present from here"
+  is in the line, not on the stage; the frame's number holds no mark; and the
+  actions row ends with the marks' line, `.deck-actions__marks`.
+
+### 19. A deck for a part: nothing to do, unless the course writes one
+
+A part can now have a deck, the lecture of the whole part:
+`content/docs/<part>/index.deck.mdx`, beside the part's page, served at
+`/<part>/slides/` (`docs/authoring/deck.md`, "A deck for a part"). A course
+without one sees no change but the manifest's shape: the schema is now v36,
+and every entry of `decks` gains `covers` (empty on a lesson's deck), while a
+part's deck carries `part` and `recalledFrom` and no `lessonId`. The `decks`
+invariant gains six codes, which only a part's deck or a deck's `[chapter: …]`
+or `[morph]` marker can raise: `deck-chapter-unknown`,
+`deck-chapter-repeated`, `deck-chapter-outside-part`, `deck-marker-misplaced`,
+`deck-check-no-chapter` and `deck-route-taken`.
+
+- **A course test or script that reads `manifest.decks`** and takes
+  `deck.lessonId` for granted skips or handles a part's deck: test
+  `deck.part !== undefined`.
+
+To write a part's deck:
+
+1. Update the course's `scripts/content.ts` usage line, as the playground's
+   does: `new deck <lesson | part>` (`scaffoldDeck` takes either), and
+   `check <lesson | deck>…` (a deck by its page, `<part>/slides`).
+2. `pnpm content new deck <part>` drafts it from the part's chapters: a
+   `## <chapter title> [chapter: <name>]` section per chapter in the order the
+   tracks read them, a frame per section of the chapter, a `<Recall>` for each
+   float it numbers. Keep the sections that cover a chapter; a section without
+   the marker is the deck's own. Rewrite it to the deck rules, as a lesson's
+   deck (step 16).
+   - **Or merge the chapters' own decks into it**, when one lecture covers
+     several chapters: move each chapter's deck's sections into the part's
+     deck in reading order, give every one of its `##` headings the chapter's
+     marker (`## Two coordinate systems [chapter: position-and-coordinates]`:
+     a chapter may run over several sections in a row), keep one `import`
+     line, and delete the chapter's `<lesson>.deck.mdx`. The chapter's address
+     in the part's deck is its first section's divider.
+3. A lesson's own deck wins over its part's: a chapter with a deck keeps its
+   sidebar icon and its "Slides for this chapter" link. Only a chapter the
+   part's deck covers and that has no deck of its own links into it, at its
+   first section's divider, and offers the part's deck as "Its slides" in its
+   Download menu. A chapter's deck merged into its part's (above) is gone from
+   the sidebar, from its chapter's title line and from `downloads/`: a link
+   to `/<part>/<lesson>/slides/` breaks, so point it at the part's deck.
+4. `pnpm validate:content` and `pnpm content check <part>/slides`, then commit
+   `content/versions.json`: the part's deck has a page version of its own
+   (rule C5).
+
+- **A browser test that counts a part's sidebar items or compact tiles** sees
+  the part's deck in its Overview's row (`a.explico-part-deck`, step 22), and
+  without scripts one more item, right after the Overview; one that lists
+  `downloads/` sees the part's deck's files, `<part>-slides.html`, `.pdf`,
+  `-notes.pdf`, `-latex.zip` and `-markdown.zip`.
+
+### 20. Rule N4's lints: delete acknowledgements, move the repeated local entries
+
+`validate:content` now reports these, all owned by rule N4:
+
+- `glyph-unique-in-corpus` fires only when two **shared** cards claim one
+  glyph. A `notation.local` entry or a gloss that reuses a letter is the
+  declared exception and is no longer reported, so every
+  `glyph-unique-in-corpus:<glyph> — …` line in `lint-ignore.yml` that
+  acknowledged a page-local reuse can be deleted (they are harmless if kept).
+  It can also report a pair 0.13.1 did not: two shared cards on one glyph
+  where one card is named only in the other's `formula:` (data-science-I's
+  `\pi`, a prior density and the circle constant). Give one a different glyph,
+  or acknowledge the pair.
+- `definition-repeated` (warning): one `notation.local` key declared in two
+  or more chapters (a deck beside its chapter never counts). Run
+  `pnpm content diagnostics warning --code definition-repeated`; each line
+  says whether the copies agree. Move one copy to `content/notation/<key>.md`
+  (`pnpm content new term <key>` scaffolds it; paste the block's fields) and
+  delete the other blocks: every `[[key]]` and `\explain{key}` keeps working.
+  Where the copies differ, keep the wording you want, or give the second
+  meaning its own key. A course with many such keys can clear them one lesson
+  at a time.
+- `meaning-repeated` (info): one symbol and name defined at two sites in any
+  tier. Promote it to a shared card, or bind the shared card the message names
+  instead of redeclaring it.
+- `explain-redundant` (info): an `\explain{key}{…}` in page math whose bare
+  symbol already resolves to the same card. Write the symbol bare; the wrap
+  is for a compound or a colliding glyph. Optional to clear.
+- `gloss-wants-promoting` is gone; delete any `lint-ignore.yml` line for it.
+
+Nothing reports a `lint-ignore.yml` line that no longer matches: search the
+file for `glyph-unique-in-corpus` and `gloss-wants-promoting` yourself. A
+course test that pins the list of consistency codes, or exercises
+`gloss-wants-promoting`, needs the new list. And reread the course's own
+notation guidance (its AGENTS.md, a style guide): advice such as "gloss
+first", or a local entry as the default for a new symbol, now contradicts N4 —
+one shared card per glyph, a local entry or a gloss only for a reused letter.
+
+### 21. The glossary: nothing to do, unless your CSS or tests read it
+
+The glossary page gains a section "On one page only" (`.glossary-page-meanings`)
+under its index, listing every `notation.local` entry with a link to its lesson
+and every gloss with a link to its card, and a formula's "Symbols" list
+(`.notation-gloss-list`) now holds the cards the formula names as well as its
+glosses, in formula order, a card's name linked (`a.notation-gloss-name`) and
+its row marked `data-notation-card`. A course that styles or asserts on either
+list adapts the selector; nothing else changes.
+
+### 22. A part's deck shares the Overview's row: nothing to do, unless your tests or CSS read it
+
+A part's deck is its Overview's other edition, as a lesson's deck is its
+chapter's (step 17): one row, the part's, that follows "Lessons open as" and
+"List the other edition too". With chapters leading the row is "Overview"
+and the deck is the icon at its end, `a.layout-edition-other`, named "Slides
+for this part: *part*"; with slides leading the row is "Slides for this
+part" and Overview is the icon, named "Overview: *part*". Unlisted, the other
+link is absent, unless it is the open page. In a compact part the two are
+one `li[data-editions="pair"]`. A part with no Overview keeps its deck as a
+row of its own. Without scripts the sidebar is as before: the Overview, then
+the deck's "Slides" row. A course with no part's deck sees no change.
+
+No course change is required. What moved, for a course whose tests or CSS
+read it:
+
+- **The deck's link** can be `a.layout-edition-other` inside the Overview's
+  `li[data-editions="pair"]`, or absent, and the script takes
+  `explico-deck-row` off it (it keeps `explico-part-deck`). A browser test
+  that found its row by `li:has(> a[href="/<part>/slides/"])` finds the part's
+  row by the Overview's `href`, and its mark on the link,
+  `a.explico-part-deck[data-page-mark]`. One that finds the part page's
+  "Slides for this part" link by name adds `exact: true`: the sidebar's icon
+  is named "Slides for this part: *part*".
+- **New attributes** in `manifest.sidebar` and on the links:
+  `data-part-edition` (`overview` or `slides`) and `data-part` on both,
+  `data-title`, `data-chapters` and `data-frames` on the deck's,
+  `data-deck-range` on each chapter that links into its section. A test that
+  compares those items whole adds them.
+- **A tooltip's second line**: the part's deck and a chapter's section carry
+  an `aria-description` ("Chapters 1–2 · 26 slides", "Slides 17–25 of the
+  part's slides"), drawn as `small.layout-edition-detail` inside the link's
+  `<span>`. A test that reads a tooltip's whole text (`toHaveText`) reads its
+  accessible name instead, or expects the second line after it.
+- **The lit section**: with the part's deck open, the section link of the
+  chapter on screen carries `aria-current="location"`, and the rail
+  (`li[data-covered]`) runs to its row. The part deck's frames carry
+  `data-chapter`, and `<html>` carries `data-deck-chapter`.
+- **Course CSS that redraws the part deck's glyph** sets
+  `--explico-part-deck-glyph` on `:root`, as the other glyphs (step 17).
+
+### 23. The contents list shows each lesson's slides: nothing to do, unless your tests or CSS read it
+
+`<CourseContents>` and `<PartOverview>` draw a slides column at each row's
+end, a glyph before each title and, on the contents list, a deck count and a
+key, when the course has a deck. **A course with no deck sees no change.**
+
+No course change is required. What moved, for a course with a deck:
+
+- **Each row gains links.** A deck's cell is an `a.deck-lane` inside the
+  row's `li`, after the title's link, so a browser test that counts or reads
+  `li > a` (`.course-contents li > a`, `.part-chapters > li > a`) narrows it
+  to the titles with `li > a:not(.deck-lane)`. A test that finds a title's
+  link by its name is unaffected: the glyph is an `aria-hidden` span with no
+  text.
+- **To keep the old lists**, pass `slides={false}`:
+  `<CourseContents slides={false} />` and `<PartOverview slides={false} />`.
+- **Course CSS that redraws the glyphs** sets `--explico-chapter-glyph`,
+  `--explico-deck-glyph`, `--explico-part-deck-glyph` and the new
+  `--explico-part-glyph` on `:root`, as in steps 17 and 22.
+
+### 24. Recommended: give missing paths a course page
+
+Starlight asks Astro for the docs entry `404` during every build. Its fallback
+works, but Astro warns `Entry docs → 404 was not found`. Add
+`content/docs/404.mdx`; adapt the title and tagline to the course:
+
+```mdx
+---
+title: "404: Page outside the syllabus"
+description: The requested course page could not be found.
+template: splash
+hero:
+  title: "404"
+  tagline: We followed this URL as far as the course map goes. It does not land on a page.
+pagefind: false
+sidebar:
+  hidden: true
+editUrl: false
+---
+
+import { LinkButton } from '@astrojs/starlight/components';
+
+<LinkButton href={import.meta.env.BASE_URL} icon="left-arrow" iconPlacement="start">
+  Return to the course
+</LinkButton>
+```
+
+`import.meta.env.BASE_URL` points home from the originally requested URL and
+survives a subpath deployment. Let the docs entry own
+`/404.html` rather than colliding with Starlight's injected route:
+
+```js
+starlight({
+  disable404Route: process.env.NODE_ENV === 'production',
+  // …
+})
+```
+
+The special route catches arbitrary missing URLs in development. The authored
+docs entry owns `/404.html` in a static build, without a duplicate route.
+
+Also give Astro the published
+origin so Starlight can build its sitemap without its `site` warning; leave the
+subpath in `base`:
+
+```js
+export default defineConfig({
+  site: 'https://example.edu',
+  base: '/course/',
+  // …
+});
+```
+
+No placeholder `content/i18n/en.json` is needed. The `i18n` collection exported
+by `explico/content-config` supplies an empty English entry only when the course
+has no authored translations; real files under `content/i18n/` replace it.
+
+### 25. The page's zones and slide edges: nothing to do, unless your CSS or screenshots read them
+
+Every page now tells its parts apart by colour: both sidebars take one step
+of a neutral grey and the header a step further (`appearance.zones:
+"tonal"`), and each slide on a deck's page has a visible edge and a drop
+shadow, a step lighter than the page in the dark theme (`appearance.slides:
+"lifted"`). A hovered row in either sidebar now fills in the dark theme too
+(it had no fill there), and the part holding the open page is tinted a step
+darker than before, so it stays visible on the grey. The manifest schema is
+now v37, with `appearance`.
+
+No course change is required, except in a browser test that compares a
+sidebar's background with the page's: they now differ by a step of grey (in
+the dark theme `rgb(32, 35, 42)` against `rgb(23, 24, 28)`), so the test reads
+the zone's own colour or the course sets `"zones": "none"`. To choose another
+look, add the block to `content/course.settings.json`:
+
+```json
+"appearance": { "zones": "paper", "slides": "edge" }
+```
+
+`zones`: `tonal` (default), `accent-header` (the header a deep band of the
+course accent; on it, a course with a mark for each theme shows its
+dark-theme mark), `paper` (header and sidebars a desk, the reading column a
+sheet on it) or `none` (Starlight's colours, as before). `slides`: `lifted`
+(default), `edge` (edge and shadow on the page's colour) or `sorter` (the
+deck on a tinted well). When the course keeps a settings schema with
+`"additionalProperties": false`, copy the playground's `appearance` property
+into it, or the settings form flags the block.
+
+Only if a course's CSS or browser tests read these:
+
+- **Screenshot tests** of any page see the new header and sidebar colours,
+  and of a deck's page the new slide edges: refresh their baselines, or set
+  `"zones": "none"` to keep the old frame.
+- **Course CSS that set `--sl-color-bg-sidebar` or the header's background**
+  now competes with `src/styles/zones.css`, which sets them from the
+  `--ex-zone-*` tokens. Set the tokens instead (`--ex-zone-header`,
+  `--ex-zone-rail`, `--ex-zone-toc`, their `-edge`s), on `:root` and
+  `:root[data-theme='light']`.
+- **Course CSS for a slide's border or shadow** sets `--deck-stage-edge`
+  and `--deck-stage-shadow`.
+
+### 26. Verify
+
+```bash
+pnpm validate:content        # passes on its first run; a tracked report it rewrote is the one failure
+pnpm content check --changed
+astro check
+astro build
+```
+
+`astro build` prints no deprecation line for the markdown plugin lists after
+step 2 and none of the missing-404, empty-`i18n`, or sitemap notices after step
+24. `validate:content` writes `content/versions.json` (step 10) on its
+first run and passes; commit the file. With step 13, a second `astro build` reports every
+PDF as reused.
+
 ## 0.13.0 → 0.13.1
 
 **No course changes required.** This release has one fix, in the engine's
 stylesheet: hovering a symbol in an equation, or in a card's formula, no longer
 paints its highlight over the glyph to its left. No authoring rule,
 `CourseConfig` field, Astro wiring, course script or CLI command changes. The
-manifest schema stays v29.
+manifest schema stays v31.
 
 ### 1. Update the dependency
 
 ```bash
-pnpm add -D explico@0.13.1
+pnpm add explico@0.13.1
 ```
 
 **Coming from 0.12.0 or earlier:** apply "0.12.0 → 0.13.0" below first, and
@@ -561,7 +1712,23 @@ it (a MAJOR bump under rule C2, step 20).
 - **`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`.
+  `wholeFormExplicit`. A bare symbol that two entries share only through
+  forms with a fixed label no longer throws `GlyphResolutionError`
+  ("is the base glyph of more than one page symbol"): with the entries `P_0`
+  and `P(y)`, `P` resolves to the card of `P(y)`. A test that expected the
+  throw moves.
+- **A display equation is a `$$` on lines of its own.** The helpers that read
+  a lesson's text (`scanEquationLabels`, `scanDisplayEquations`,
+  `countDisplayEquations`, `validateEquations`; `explico/reference/equations.mjs`
+  and `…/equations-validate`) follow remark-math. `$$ a=b \label{eq:x} $$` on
+  one line is inline math there: 0.12.0 counted it, this release returns
+  nothing for it. A course test whose fixture writes a display equation on one
+  line gets empty results; put `$$` on a line, the equation on the next, and
+  `$$` on a third, as `docs/authoring/structure.md` writes it.
+- **A test that compiles the whole course** with `compileManifest` renders
+  every lesson's math, so on a large course it can pass vitest's 5 s default
+  timeout. Give it an explicit one: `it('…', { timeout: 30_000 }, async () => {
+  … })`.
 - **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
@@ -618,8 +1785,11 @@ of its width in the article, and diagram boxes are measured (step 13).
 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:
+the course's Playwright suite. **Skip this step if no lesson has a `<Figure>`**
+(a lab that is not inside one is not checked): `lessonsWithFigures(manifest)` is
+then empty and the file defines no test, so running it alone, as
+`playwright test tests/e2e/figure-fit.spec.ts` does, fails with "No tests
+found". Otherwise add it there, at each viewport the course supports:
 
 ```ts
 import { readFileSync } from 'node:fs';
@@ -759,7 +1929,7 @@ or removed. The manifest schema is now v25 (step 8).
 ### 1. Update the dependency
 
 ```bash
-pnpm add -D explico@0.12.0
+pnpm add explico@0.12.0
 ```
 
 ### 2. A lab never calls KaTeX itself (rule V3, rule N4)
@@ -931,6 +2101,15 @@ helpers directly:
   a lesson id or a `manifest.pages[].id`. Its errors, and the local-notation
   parity error, are reworded ("on page …", "notation mismatch"). Update a
   test that matched the old text.
+- `remarkNotation` over a page that is not a chapter binds its math (step 5)
+  instead of leaving it alone. A test that fed it `src/content/docs/about.md`
+  and expected the text back unchanged now gets `Unresolved notation in page
+  math: … (rule S10)` for each symbol with no shared entry. Give the fixture a
+  shared entry for the symbol, or remove the math from it.
+- A page's own `notation.local` entries seed its bundle (step 7), so
+  `registry.bundles[n].definitionIds` and `manifest.notation.bundles` now list
+  them as `page:<lessonId>:<key>` next to the shared ids. A test that compares
+  a bundle's ids with `toEqual` adds those.
 - `.lab-math` no longer scrolls or pads; its `.katex-display` does. A
   float's caption line is at least `1.5rem` tall while it shows a tool
   button.
@@ -967,7 +2146,7 @@ v24.
 ### 1. Update the dependency
 
 ```bash
-pnpm add -D explico@0.11.1
+pnpm add explico@0.11.1
 ```
 
 **Coming from 0.8.0:** follow the "Coming from 0.8.0" note of "0.10.0 →
@@ -1050,7 +2229,7 @@ the check.
 ### 1. Update the dependency
 
 ```bash
-pnpm add -D explico@0.11.0
+pnpm add explico@0.11.0
 ```
 
 ### 2. Delete `disclosure.diagrams` (the build fails until you do)
@@ -1425,7 +2604,7 @@ seven bumps (step 6).
 ### 1. Update the dependency
 
 ```bash
-pnpm add -D explico@0.10.0
+pnpm add explico@0.10.0
 ```
 
 0.10.0 was never published to npm. Coming from npm's 0.8.0, install 0.11.0
@@ -2019,7 +3198,7 @@ schema version is unchanged.
 ### 1. Update the dependency
 
 ```bash
-pnpm add -D explico@0.9.0
+pnpm add explico@0.9.0
 ```
 
 0.9.0 was never published to npm. Coming from npm's 0.8.0, install 0.11.0
@@ -2323,7 +3502,7 @@ previously worked around may now be written directly.
 ### 10. Verify
 
 ```
-pnpm add -D explico@0.8.0
+pnpm add 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)