explico 0.13.1 → 0.14.0

package/docs/authoring/notation.md

@@ -128,6 +128,18 @@ _How to apply._ See the `notation` collection schema
 (`src/compiler/content-schemas.ts`). A letter that exists only so one entry's own `formula` can
 be stated is a **gloss**, not a card — it creates no curriculum edge.
 
+Which tier, in one question: *is this letter already defined?* Ask
+`pnpm content symbol <latex>` first. If a card with this meaning exists,
+reference it (`[[key]]` once in prose, bare math after). If the letter already
+carries another meaning in the course, declare it here: `notation.local` on a
+lesson, a gloss in a card's formula — that reuse is the one reason for the
+page tier, and it needs no acknowledgement. Otherwise make a shared card: the
+next lesson that needs it will reference it instead of copying it. Use count
+plays no part — a constant used on one page is vocabulary, a letter used on
+six pages with six meanings is a reused letter each time — and the sign that
+a meaning was not page-bound is that it got defined twice, which
+`definition-repeated` and `meaning-repeated` report.
+
 Do not satisfy this rule by dumping every `[[key]]` a page uses into one
 trailing "Notation used on this page" (or similarly named) section near the
 end of the lesson. `LessonFooter.astro` already injects an interactive
@@ -266,13 +278,21 @@ $\theta$ after replacing $\theta$ with $-\theta$.
 
 _Enforcement._ Build-enforced. The completeness gate (`gate-math.ts`, `pnpm
 validate:content`; `astro build` re-runs the same resolver) fails on an
-unresolved glyph (`unresolved-glyph`) in every rendered-math context;
+unresolved glyph (`unresolved-glyph`) in every rendered-math context,
+a notation entry's body included: it binds every shared entry, without
+`[[key]]`, and no `notation.local` (`registry-scope.mjs`), and the glossary
+fails `astro build` on an entry whose body did not render;
 `consistency.ts` adds the corpus-level lints `glyph-unique-in-corpus`
-(warning), `weak-local`, `gloss-wants-promoting`, `card-wants-demoting`
-(info); a final rendered-trigger/payload parity check backs it at render time,
+(warning: two shared cards on one glyph — a local entry or a gloss may reuse
+a letter), `definition-repeated` (warning: one local key declared in two
+lessons), `meaning-repeated` (info: one symbol and name defined at two sites,
+in any tier), `weak-local` and `card-wants-demoting` (info); the gate reports
+`explain-redundant` (info) for an `\explain` wrap whose bare symbol already
+resolves to the same card; a final rendered-trigger/payload parity check backs it at render time,
 and a last pass over every built page fails a symbol a figure shows that KaTeX
 drew outside a notation binding (`figure-symbols.ts`: a lab that called KaTeX
-itself — see [V3](visualizations.md#v3)).
+itself — see [V3](visualizations.md#v3)); a plain base-library letter is not
+one, here as in a lesson.
 This rule is **locked** — the notation layer is this rule, so a course cannot
 turn it off.
 
@@ -1253,7 +1273,7 @@ text where every other card shows a name.
 
 _How to apply._ Keep the name to a few words with no sentence punctuation or
 relative clause. If the symbol needs a description, promote the gloss to a
-notation entry (the `gloss-wants-promoting` hint under N4 says when).
+notation entry (the `meaning-repeated` hint under N4 says when).
 
 _Enforcement._ Build-enforced (`consistency.ts` `checkGlossNameShape`, `pnpm
 validate:content`) — warning `gloss-name-shape` for a name over the word
@@ -1415,7 +1435,11 @@ the same precedence [N22](#n22) uses for decorations:
    object (it needs its own entry, or an `\explain{key}{x}` where it really
    is shorthand). A digit fills a running slot, but a `\mathrm{…}` or
    `\text{…}` label never does: `x_{\mathrm{e}}` is not an instance of
-   `x_k`. Two families on one base that both fit an instance fail
+   `x_k`. A double index written as juxtaposed letters is one slot of that
+   many letters: the family `x_{ij}` (or `K_{ij}`) gives its card to `x_{i1}`,
+   `x_{12}` and `x_{ji}`, a run of as many letters and digits, but not to
+   `x_i`, `x_{ijk}` or `x_{i+1}`; `x_{i,j}` is the same family with two slots.
+   Two families on one base that both fit an instance fail
    `ambiguous-base-fallback`: keep one per page, or `\explain` the instance.
    An entry whose index is fixed (`v_0`, `H_1`, `T_{\mathrm{opt}}`, or one
    marked `fixedIndex: true`) is a single symbol and lends its card to
@@ -1457,6 +1481,10 @@ or `d` there needs a card too.
 
 A subscript on an operator or a bracket is not an index: `\sum_{i=1}`,
 `\lim_{t \to 0}`, `\log_{10}`, `\lVert x\rVert_2`, `\left.f\right\rvert_{x=0}`.
+Nor is a letter that belongs to a symbol with a card of its own inside the
+subscript (`b` of `b_n` in `\nabla_{b_n}`; the `b_n` is checked in its own
+right), or any letter of a subscript that states a condition with a relation
+(`Z \sim g` in `\mathbb{E}_{Z \sim g}`).
 A superscript is a power (`y^{(m)}` is out of scope). An entry whose `latex`
 has a superscript and no subscript (`j^{(m)}`) is a whole form for that
 symbol and, having no index, still lends its card to its bare base.
@@ -1491,6 +1519,13 @@ says `fixedIndex: true` (a component `x`, a label). An uppercase or Greek
 letter in a subscript (`X_N`, `p_\theta`) is a size or a symbol, not a
 running index, and needs no set.
 
+A letter is fixed everywhere on the page, so `fixedIndex: true` on the card of
+`m` also turns a family indexed by it (`r_m`) into a single symbol that lends
+its card to nothing, `r_2` included. A letter that is the index of a family
+runs over a set: give its card a `range` rather than `fixedIndex`. The
+`unresolved-glyph` message for an `r_2` that fails this way names the card
+that fixed the letter.
+
 ### `\explain` around an indexed symbol
 
 `\explain{key}{v_x}` makes the whole `v_x` one target with `key`'s card. If
@@ -1501,6 +1536,14 @@ or name an entry for the indexed symbol. An index inside a larger wrap
 (`\explain{survival-probability}{S(0,t_i)}`) is the wrap's, as every glyph
 inside one is.
 
+The wrap claims the indexed symbol, so its base takes no other entry's card:
+`\explain{component-sd}{\sigma_1}` under the family `\sigma_k` leaves the `\sigma`
+alone even when the page also has a plain `\sigma`. The other direction nests:
+an `\explain` inside an instance's own subscript,
+`\beta_{\explain{regressor-count}{K}}`, still finds the family `\beta_j`, and
+the instance's wrap goes around it, as
+`\explain{beta-j}{\beta_{\explain{regressor-count}{K}}}`.
+
 | Code | Severity | When |
 | --- | --- | --- |
 | `index-explained` | error | a subscript on a symbol has no whole form, family or index entry, and a slot has no letter with its own card — a digit, a label, a base-library letter — or the base itself has no card |

package/docs/authoring/structure.md

@@ -65,6 +65,19 @@ Consequences:
   is that same unit's position in the reading order. A file is a lesson; its
   ordinal is its chapter number.
 
+### A lesson's two editions
+
+A lesson can have two editions: its **chapter**, `<name>.mdx`, and its
+**deck**, `<name>.deck.mdx`, the slide edition ([deck.md](deck.md)). A deck
+beside its chapter is served at `<lesson>/slides/`, and the lesson's one
+sidebar row opens one edition and carries the other as an icon
+([deck.md](deck.md#in-the-sidebar)). It is not a level of its own and takes
+no chapter number. A
+lesson with a deck and no chapter is **slides-first**: the deck is the lesson,
+at the lesson's own URL, with a chapter number in its part, so the chapters
+after it keep theirs. Inside a deck, `##` opens a section of frames and `###` is
+a frame (rule D1), so levels 4 and 5 read as section and frame there.
+
 ## What the playground demonstrates
 
 The playground is the worked example for every level. It was deliberately
@@ -174,7 +187,9 @@ reading order with their descriptions, the competencies the part teaches, the
 parts it builds on and leads to — so the page cannot fall out of date with the
 content. Only the two paragraphs and the optional `chain` (the part's argument,
 one step per line, which no manifest field knows) are authored. `rail={false}` drops the
-side rail and keeps the reading list.
+side rail and keeps the reading list. In a course with a deck its reading list
+has the contents list's glyphs and slides column (below); `slides={false}`
+drops them.
 
 ### Study time
 
@@ -232,6 +247,70 @@ cannot leave a stale copy behind on the front page. `descriptions={false}`
 drops the one-line summaries; `headingLevel={3}` fits it under an existing
 `##`.
 
+**Slides.** When the course has a deck, the list says which lessons have
+slides, whatever the reader's sidebar controls show: it answers "what is in
+the course", and the controls only choose what a sidebar row opens.
+
+- Each title starts with the glyph of what it opens: a chapter's lined sheet,
+  or a slides-only lesson's slide frame. A part's heading starts with
+  Overview's two sheets.
+- The counts gain the decks ("4 slide decks"), and a key under them names the
+  glyphs the list uses: Chapter, Slides, and Slides for a whole part when a
+  part has a deck.
+- A slides column ends every row. A lesson's own deck is a tile on its title
+  line. A part's deck is one bar along the chapters it covers, from the first
+  covered title to the last, its first cell carrying the part deck's two
+  frames; each cell links to that chapter's section of the deck and is named
+  as the sidebar names it ("Slides: *chapter*", "Slides 17–25 of the part's
+  slides"). A part's deck that skips a chapter breaks into runs; one that
+  covers a chapter with a deck of its own runs in a second column. A
+  slides-only lesson's tile is out of the tab order, since its title opens the
+  same page.
+
+A course with no deck renders the list as before. `slides={false}` drops the
+column, the glyphs, the key and the count; `<PartOverview slides={false} />`
+does the same on a part's page.
+
+## When the path is not in the course
+
+Author `content/docs/404.mdx` as a splash page. Starlight serves that entry for
+an unknown URL; without it, the fallback page works but every build warns that
+the `docs` entry `404` was not found. A minimal page is:
+
+```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';
+
+<div style="display: flex; justify-content: center;">
+  <LinkButton href={import.meta.env.BASE_URL} icon="left-arrow" iconPlacement="start">
+    Return to the course
+  </LinkButton>
+</div>
+```
+
+Use `import.meta.env.BASE_URL` for a link to the course root: a relative `./`
+would resolve against the missing URL, not against `404.html`, while a bare `/`
+would escape a subpath deployment. In `astro.config.mjs`, set
+`disable404Route: process.env.NODE_ENV === 'production'` in `starlight({ … })`:
+Starlight catches arbitrary missing paths in development, while the docs entry
+owns `/404.html` in a static build without colliding with the injected route.
+The 404 is a utility page, not a chapter: it has no `teaches`, notation,
+knowledge check, numbering, sidebar row
+or lesson exports. Set Astro's top-level `site` to the published origin as well
+so Starlight can write its sitemap; `base` continues to hold any subpath.
+
 ## Where the reader is
 
 Two marks, both derived, neither authored:

package/docs/authoring/versioning.md

@@ -4,7 +4,9 @@
 learning-facing content, independent of the `explico` engine's own version. The
 declared value is `about.version` in `content/course.config.ts`; the history and
 the reader-facing notes are in `content/CHANGELOG.md`. Both are surfaced to
-readers by the About `[?]` panel.
+readers by the About `[?]` panel. Each chapter and part page also carries the
+version its own content last changed in ([C5](#c5)), kept in
+`content/versions.json`, which the build writes.
 
 See [README.md](README.md) for what "Build-enforced" and "Review-only" mean here.
 The engine's own versioning is a separate policy —
@@ -91,7 +93,9 @@ one commit:
 2. Rename the heading to `## [x.y.z] - <today>`; add a fresh empty
    `## [Unreleased]` above it.
 3. Set `about.version` in `content/course.config.ts` to `x.y.z`.
-4. `pnpm validate:content` — no `knowledge-*` warning.
+4. `pnpm validate:content` — no `knowledge-*` warning. It rewrites
+   `content/versions.json`, where every page changed since the last release
+   takes `x.y.z` ([C5](#c5)); commit it in the same commit.
 
 `pnpm release:content` does steps 2 and 3 for you.
 
@@ -106,3 +110,51 @@ edits landed in one commit — it warns until the second half lands.
 
 _Exceptions._ None.
 
+---
+
+## C5
+
+**Each chapter and part page carries the knowledge version its content last
+changed in, kept in `content/versions.json`, which `validate:content` writes
+and the course commits with the change.**
+
+Under a chapter's title, its PDF and Markdown say "unchanged since version
+0.2.0", the release its content last changed in, not the course's current
+version; a chapter changed since the last release says "with changes after
+version 0.4.0, not yet released". The `[?]` panel shows the same line for the
+page it is on, and a part's or the course's PDF carries the newest version
+among its pages. A document whose version did not move keeps its PDF's date
+and identifier, so a release recompiles only what it changed
+(`EXPLICO_LATEX_CACHE`).
+
+_Rationale._ The course's version moves at every release, whatever the release
+touched, so stamped on a chapter it only says "built after 0.4.0". A reader
+wants to know whether the chapter they printed is the one on the site. A build
+sees one commit and cannot tell what a page was at an earlier release, so the
+record is a committed file, kept like a lockfile: the build derives it, the
+course commits it.
+
+_How to apply._ Nothing by hand. `pnpm validate:content` writes
+`content/versions.json` from the committed one and the content; commit what it
+wrote with every content change, and with every release ([C3](#c3) step 4).
+What counts as the page: its own file, its `.checks.yml` and the assessments it
+lists, the shared notation entries its text uses, the sources it cites, and its
+numbers (`part.chapter` and the float offsets its earlier chapters leave it). A
+page changed while `## [Unreleased]` holds any bullet is "not yet released"
+until the next release; a change with no bullet (a fix [C1](#c1) lets go
+unlisted) keeps the current version. A lab, `content/domain/`, a part's label
+or the engine change a page's PDF without changing its version. Rule off
+(`rules.C5.enabled: false` in the course settings): the file is neither read
+nor written, and every page carries the course's version.
+
+_Enforcement._ Build-enforced (`page-versions.ts`). `pnpm validate:content` on
+a developer's machine rewrites a stale `content/versions.json` and says so; in
+CI (`CI` set) it fails with `page-versions-stale` (`syncPageVersions`), so a
+content change cannot land without its record. A file that is not a record
+`validate:content` wrote warns `page-versions-invalid` (`readPageVersions`) and
+is rebuilt, every page counting as new. Partial: which bullet of
+`## [Unreleased]` belongs to which page is not known, so every page changed
+while there is any bullet counts as not yet released.
+
+_Exceptions._ None. A course that does not want the stamp turns the rule off.
+

package/docs/authoring/visualizations.md

@@ -207,9 +207,14 @@ component.
 _Enforcement._ Partly build-enforced. `pnpm validate:content` follows each
 lesson's relative imports to the course's components and fails one that
 imports `katex` itself (`lab-katex-validate.ts`, `lab-katex-direct`, an
-error), naming the chain of imports that reaches it. `astro build` then reads
+error), naming the chain of imports that reaches it, once for every lesson that
+reaches the file; a lesson that reaches none is clean. `astro build` then reads
 every figure it rendered and fails a symbol KaTeX drew outside a notation
-binding (`figure-symbols.ts`, rule [N4](notation.md#n4)); a course's browser
+binding (`figure-symbols.ts`, rule [N4](notation.md#n4)), listing every page
+that has one rather than the first. A plain base-library `d`, `e`, `i` or `π`
+(`renderLabMath` leaves it without a card, as a lesson's math does) is not such
+a symbol, in a power too; a decorated or styled one is, and a library letter as
+an index is rule [N23](notation.md#n23)'s, checked as the lab renders. A course's browser
 test runs the same `unboundFigureSymbols` on a hydrated figure's
 `outerHTML`, which also holds what an island draws only in the browser, as
 the playground's `labs.spec.ts` does. The same build warns about a figure

package/docs/course-agent/AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md
+
+This course is built on [explico](https://www.npmjs.com/package/explico). Read
+`node_modules/explico/docs/authoring/agents.md` first: it is the engine's guide
+for an agent working on a course, and it ships with the version installed here.
+This file holds only what is particular to this course. Two complete courses to
+compare against — the playground, which the engine's docs cite as
+`playground/…`, and credit-and-derivatives — are downloadable from
+https://danieltuzes.github.io/explico/start/ ([`sources.json`](https://danieltuzes.github.io/explico/downloads/sources.json)).
+
+## The loop
+
+- `pnpm content help` lists the CLI. Start every task there, not with a file
+  hunt: `content context <lesson>` for a lesson's scope, `content rules
+  [--element …]` for the rules this course has on, `content rule <ID>` for one
+  of them whole, `content symbol <latex>` before declaring any notation.
+- While writing math: `content equation "<latex>" --lesson <id>`; after:
+  `content bindings <lesson>` and `content check <lesson>`.
+- Before handing back: `pnpm validate:content` (passes on its first run; commit
+  `content/versions.json` if it changed), `pnpm content check --changed`,
+  `astro check`, `astro build`.
+- Every content change adds a bullet under `## [Unreleased]` in
+  `content/CHANGELOG.md` (rule C1).
+- Upgrading `explico`: `pnpm content migrate` prints exactly the sections to
+  apply.
+
+The procedures above are project skills under `.claude/skills/` and the
+`rules-reviewer` agent under `.claude/agents/`, installed by
+`pnpm content init-agent --write` from the engine's `docs/course-agent/`;
+rerun it after an upgrade to refresh them.
+
+## This course
+
+<!-- What an agent needs that the engine's guide cannot know: the course's
+subject and audience, where its sources live, its own `X` rules and why,
+parts that are off limits, how it deploys. Keep it short; it is read on
+every turn. -->

package/docs/course-agent/agents/rules-reviewer.md

@@ -0,0 +1,33 @@
+---
+name: rules-reviewer
+description: Reviews one explico lesson against the guide-only authoring rules (the ones no script checks) in a fresh context, and returns findings with line numbers in at most a thousand tokens. Use before handing a drafted or revised lesson back; the draft-lesson skill invokes it. Give it the lesson id and, when the course is not the playground, the course package path.
+tools: Bash, Read, Grep, Glob
+model: inherit
+effort: medium
+---
+
+You review one lesson of an explico course against the rules a script cannot
+check. You are the second reader the drafter does not have: fresh context,
+only the rules and the lesson in it. Return findings, not a rewrite.
+
+Inputs: a lesson id such as `projectiles.projectile-range`, and the course
+package directory (the one whose `package.json` has the `content` script;
+`playground/` in the explico repository). Run the CLI from that directory
+with `pnpm -s content …`.
+
+1. `pnpm -s content check <lesson>`: if it fails, report the failure first and
+   stop — a build error outranks style.
+2. `pnpm -s content context <lesson> --json > /tmp/ctx.json` is too big to
+   read whole; instead `pnpm -s content context <lesson>` for the header, then
+   read the lesson file (`content/docs/<slug>.mdx`) with line numbers.
+3. `pnpm -s content rules --enforcement guide` lists the rules this course has
+   on that no script checks, by element, each with a one-line summary. Apply
+   only those; a rule absent from the list is off. Open `pnpm -s content rule
+   <ID>` only when a summary does not settle a doubt.
+4. Read the lesson once, rule list beside it, and note each place a guide-only
+   rule is not followed: the rule id, the line, what you saw, the fix in one
+   clause. A JSX prop string (`caption="…"`) is not prose for the math rules.
+5. Return at most twelve findings, highest impact first, as lines of the form
+   `L<line> <ID>: <what> — <fix>`, then one line `ok: <rules checked>` naming
+   the rule ids you applied and found satisfied. No preamble, no praise, no
+   restatement of the rules. Under a thousand tokens.

package/docs/course-agent/skills/draft-lesson/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: draft-lesson
+description: Draft or revise an explico lesson with the content CLI doing the lookups — context, rules in effect, symbol lookup before declaring notation, equation and bindings probes before a build, check, the content changelog. Use when asked to write, extend or fix a lesson, a notation entry or an assessment.
+---
+
+# Draft a lesson
+
+Read with the CLI, not by opening files; every verb prints a bounded digest
+and `--json` for the whole. Run them from the course package (the directory
+whose `package.json` has the `content` script); `pnpm content help` lists them.
+
+1. **Scope.** `pnpm content context <lesson>`: the lesson plus exactly its
+   notation, references, assumptions and sources (a new lesson:
+   `pnpm content new lesson <id>` scaffolds it).
+2. **Rules.** `pnpm content rules --element <prose,table,…>` lists only the
+   rules this course has on, with enforcement and codes; `pnpm content rule
+   <ID>` prints one whole, example included. A rule absent from the list is
+   off: neither apply it nor flag it.
+3. **Notation, one question per symbol: is it already defined?**
+   `pnpm content symbol <latex>`. A card with this meaning exists → reference
+   it: `[[key]]` once in prose, bare math after; `\explain{key}{…}` only for a
+   compound or a colliding glyph. The letter already means something else in
+   the course → `notation.local` on this lesson (a gloss, in a card's
+   formula). Neither → a shared card (`pnpm content new term <key>`), so the
+   next lesson references it instead of copying it. Use count plays no part.
+4. **Math, while writing.** `pnpm content equation "<latex>" --lesson <id>`
+   resolves one expression the way the gate will and exits 1 when the build
+   would refuse it; `pnpm content bindings <lesson>` shows every span's
+   bindings, unresolved glyphs and redundant wraps.
+5. **Check.** `pnpm content check <lesson>` (schema, references, MDX → KaTeX;
+   exits non-zero on an error), then `pnpm content diagnostics --lesson <id>`
+   for the rest; the counts come first, the lines on request.
+6. **Record.** A bullet under `## [Unreleased]` in `content/CHANGELOG.md`
+   (rule C1); `pnpm validate:content` rewrites `content/versions.json`, which
+   is committed with the change (rule C5). Guide-only rules (`enforcement
+   guide`) have no check: before handing back, have the `rules-reviewer`
+   agent review the lesson, or review the draft against them yourself.

package/docs/course-agent/skills/migrate-course/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: migrate-course
+description: Upgrade a downstream explico course to a newer engine version — record the old version, install the new one, apply exactly the migration sections between them with `content migrate`, verify. Use when asked to update, upgrade or migrate a course's explico dependency, including a PATCH.
+---
+
+# Upgrade a course's engine
+
+Every `explico` bump is a migration task, PATCH included: each release has a
+section in the shipped `docs/authoring/migrating.md` that either gives exact
+work or says no course changes are required.
+
+1. Record the installed version: `node -p "require('explico/package.json').version"`.
+2. `pnpm add explico@<version>` — without `-D`, so pnpm updates whichever block
+   already lists `explico`.
+3. `pnpm content migrate` prints exactly the sections to apply, from the
+   version `package.json` pinned at HEAD to the one now installed, oldest
+   first (`--from`/`--to` override either end), and refuses when a section is
+   missing. Apply every one: required and conditional changes across
+   `content/`, `content/course.config.ts`, Astro/source wiring, course scripts,
+   dependencies and generated files. Do not use `CHANGELOG.md` alone as the
+   procedure, and do not assume a release without a **Breaking** heading
+   needs no work. If `pnpm content migrate` is not a verb yet (a course
+   whose `scripts/content.ts` predates the shim), read the sections from
+   `node_modules/explico/docs/authoring/migrating.md`; the section that
+   introduced the shim says how to switch to it.
+4. The checks each section ends with, then: `pnpm validate:content` (passes on
+   its first run; commit `content/versions.json` if it changed),
+   `pnpm content check --changed`, `astro check`, `astro build`, and the
+   course's browser tests if it has any.
+5. Commit the dependency change, the migration edits and the generated files
+   together, naming the versions in the message.

package/docs/course-agent/skills/release-content/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: release-content
+description: Cut a course content release (rules C1–C3, C5) — move content/CHANGELOG.md's Unreleased section to a dated heading and bump about.version together. Use when asked to release or publish a course's content version.
+---
+
+# Cut a content release
+
+A course's content has its own version stream: `content/course.config.ts`
+`about.version` (shown to readers in the About `[?]` panel) and
+`content/CHANGELOG.md`, with rules C1–C3 in `docs/authoring/versioning.md` and
+each page's own version in `content/versions.json` (rule C5).
+
+1. Every change since the last release has a bullet under `## [Unreleased]`
+   in `content/CHANGELOG.md` (rule C1). If one is missing, add it first.
+2. Pick the bump (rule C2): MAJOR when a lesson, competency or notation key
+   was removed or renamed or a stated outcome changed; MINOR for something
+   new; PATCH for a fix or clarification.
+3. From the course package: `pnpm release:content [major|minor|patch]`. It
+   moves `[Unreleased]` to a dated `## [x.y.z]` heading and sets
+   `about.version` to match in the same change (rule C3).
+4. `pnpm validate:content`: no `knowledge-*` warning; it rewrites
+   `content/versions.json` — commit that file with the release, never edit it
+   by hand.
+5. Commit the changelog, the config and `versions.json` together.

package/docs/diagram-scaling.md

@@ -0,0 +1,148 @@
+# Diagram scaling on touch screens
+
+> **Status.** In `[Unreleased]` (see [`CHANGELOG.md`](../CHANGELOG.md)).
+> Checked in Chromium, in the end-to-end suite and by measurement. **Not
+> checked in WebKit** (Safari, every iOS browser): no WebKit build is available
+> to the agent sessions that wrote it. It uses the technique the print path
+> already uses for WebKit, but a person should look at a diagram on an iPhone
+> before a release ([Checking it](#checking-it)).
+
+A diagram is drawn in px at build time. On a phone, the reader's own text-size
+menu shrinks the whole drawing, boxes and text together, so that a wide diagram
+fits the screen instead of scrolling. This page says how, why it is built the
+way it is, and what an agent must not undo.
+
+## What a reader sees
+
+- On a touch screen (`@media (hover: none)`) the phone menu has a text-size
+  select beside the theme switch: **50, 59, 71, 84, 100%**, smallest first. The
+  steps are a geometric series, each 2^(1/4) (about 1.19) times the one below.
+  A screen with hover has the browser's zoom instead and shows no control.
+- The choice scales the root font size, so every `rem` follows: prose, math,
+  spacing, cards.
+- A diagram in the lesson shrinks by the same factor, **boxes and text
+  together**. The playground's `#dia-range-derivation` is 687 px wide; in a
+  390 px viewport it becomes 577, 488, 405 and 344 px at 84, 71, 59 and 50%.
+  The column is 358 to 374 px wide there, so at 50% it fits with no
+  scrolling, and the widen button ↔ goes away. At 59% it still scrolls a
+  little, and the button stays.
+- A diagram in a preview card (`[[dia-…]]`) keeps its size: a card never takes
+  its text under 12 px.
+- With no size chosen (100%), on a screen with hover, and in print, **nothing
+  changes**.
+
+## How it works
+
+| Piece | Where | Role |
+| --- | --- | --- |
+| The steps | `src/components/starlight/TextSizeControl.astro` | Builds the list from `round(100 · 2^((i−4)/4))`, `i = 0…4`. Saves the choice in `localStorage` (`explico:display:text-size`); an inline script copies it to `data-text-size` on `<html>` before first paint. 100% is no attribute. A saved value that is not a step (an earlier release's 90, 80, 70) is ignored. |
+| The scale | `src/styles/global.css`, `@media screen and (hover: none)` | One `:root[data-text-size='…']` rule per step below 100 sets `--explico-text-scale` (0.5 to 0.84). `:root[data-text-size]` sets the root `font-size` to `calc(var(--explico-text-scale, 1) * 100%)`. Outside that media query the variable is unset, so `var(…, 1)` is 1. |
+| The markup | `src/components/diagram/Diagram.astro` | `.diagram-scroll > .diagram-frame > .diagram-canvas > svg`. The frame carries `--diagram-width` and `--diagram-height` (the build-time layout size, unitless px; the canvas inherits them). The canvas keeps its inline `width`/`height` in px. |
+| The rules | `Diagram.astro` `<style>` | Under the same media query, inside `:root[data-text-size] .sl-markdown-content`: the **frame** gets `width/height = layout size × scale` and `overflow: hidden`; the **canvas** gets `transform: scale(var(--explico-text-scale))` with `transform-origin: 0 0`. |
+| The widen button | `src/components/starlight/DiagramEnhancer.astro` | Decides "does it overflow" from the scroller's `scrollWidth`. Its `ResizeObserver` watches the scroller **and the frame**, because a size change resizes the frame, not the scroller. |
+
+The node text stays `font-size: 13.6px` (`.diagram-node-content`) at every
+size. The scale comes from the transform, not from the font.
+
+## Why it is built this way
+
+- **Boxes are measured for 13.6 px text.** `src/reference/diagram-layout.ts`
+  (`NODE_FONT_PX`, the insets, the KaTeX formula measure) sizes each box from
+  the label and formula at build time. A box can only hold its text if both
+  keep their relationship, so the finished drawing is scaled as one thing.
+- **Shrinking only the font is not enough.** That was the first version here:
+  the text followed the menu and the boxes did not, so the diagram never got
+  narrower and did not fit the phone, which is the point of the menu.
+- **Never scale through the SVG.** Not the `viewBox`, not `width`/`height`
+  with a `viewBox`, not a `transform` on a `<g>` or on the `<svg>`. Nodes are
+  HTML in a `<foreignObject>`, and WebKit paints that HTML (every KaTeX
+  `position: relative` span has its own render layer) **without** the SVG's
+  internal transforms: formulas pile up at the SVG origin while their boxes
+  stay put. `tests/e2e/site.spec.ts` guards the markup for this. See also the
+  comments in `Diagram.astro` and in `global.css` (print).
+- **Scale the HTML canvas around the SVG instead.** The SVG stays at its
+  build-time size and the `div` around it takes a CSS `transform`. The print
+  path in `global.css` already does exactly this for WebKit, so this is not a
+  new technique, only a new trigger. CSS `zoom` was not tried: it is expected to
+  go through the SVG root's own scaling in WebKit, the thing being avoided, but
+  that is a reading of the engine, not a test.
+- **A frame takes the scaled size.** A transform moves no layout box, so the
+  canvas would still be its unscaled size in the flow (extra height, and a
+  scroll width of the unscaled width in an engine that counts the layout box).
+  The frame has the scaled `width` and `height`, which is what the scroller
+  measures, and `overflow: hidden` so the canvas's unscaled layout box adds
+  nothing. The scaled canvas exactly fills the frame, so nothing visible is
+  clipped.
+- **Only the lesson's own diagrams scale.** The rules are scoped to
+  `.sl-markdown-content`. That covers the article and an expanded diagram (the
+  enhancer moves the figure to `<body>` inside a `.sl-markdown-content`
+  wrapper, to keep every rule scoped that way) and leaves preview cards out.
+
+## Rules for changing it
+
+1. Do not set a `font-size` in `.diagram-node-content` that depends on
+   `--explico-text-scale`. That scales the text twice.
+2. Do not scale through the SVG (see above). A change that adds a `transform`
+   or a different `viewBox` to anything inside the `<svg>` breaks WebKit.
+3. Keep the frame's size and the canvas's transform driven by the same
+   variable, or the box and its content disagree.
+4. Keep `--diagram-width` and `--diagram-height` as unitless numbers on the
+   frame: the rules multiply them by `1px` and by the scale.
+5. A new consumer of a diagram's size (a script, a test) reads the **frame**
+   or the scroller's `scrollWidth`, not the canvas's `offsetWidth`, which is
+   the unscaled size.
+6. Course CSS or tests that selected `.diagram-scroll > .diagram-canvas` as a
+   child need a descendant selector now.
+7. Print and the exports must stay as they were: the scaling rules are inside
+   `@media screen and (hover: none)`, and the print rules in `global.css` set
+   the canvas's own size and transform. A change here must not leak out of
+   that media query.
+
+### Changing the steps
+
+The list is generated in `TextSizeControl.astro` (`STEPS` and the formula);
+the select and the saved-value check both read it. The CSS cannot be
+generated, so add or remove the matching `:root[data-text-size='…']` rule in
+`global.css`, and the `STEPS` constant in
+`playground/tests/e2e/text-size.spec.ts`. That spec fails if the select's
+values and the formula disagree, and its diagram test fails on a step whose
+CSS rule is missing.
+
+## Checking it
+
+```sh
+# unit tests, then the specs for this feature (Chromium)
+pnpm test
+pnpm --filter explico-playground exec playwright test \
+  tests/e2e/text-size.spec.ts tests/e2e/about.spec.ts tests/e2e/site.spec.ts \
+  tests/e2e/diagram-fit.spec.ts tests/e2e/print-export.spec.ts
+```
+
+`text-size.spec.ts` checks, at each step on a 390 px phone: the root size, the
+canvas transform (`matrix(s, 0, 0, s, 0, 0)`), the frame's width (`built × s`),
+the scroller's `scrollWidth`, that the node text is still 13.6 px and clipped
+nowhere, that at 50% the 687 px diagram fits and its widen button is hidden, and
+that a screen with hover ignores a saved size.
+
+**What Chromium cannot show is WebKit's paint.** Before a release, on an iPhone
+(or Safari's responsive mode, which uses the desktop engine and so is not
+enough on its own), open a lesson with a diagram that has formulas, pick each
+size in the phone menu and check that:
+
+- every formula sits inside its box (none at the top-left corner of the
+  diagram);
+- the arrows meet the boxes;
+- the widen button ↔ appears at 59% and 71% and goes at 50%;
+- a preview card for the diagram is full size;
+- printing the page (Share → Print) still shows the whole diagram.
+
+## Known limits
+
+- Text at 50% is 6.8 px on screen (13.6 × 0.5). That is the cost of the step,
+  and the reader's choice; there is no floor for a diagram.
+- A diagram wider than the column after scaling still scrolls, and the widen
+  button still applies. The expanded view is capped to the viewport as before.
+- Boxes and text shrink together, so the drawing keeps its proportions; the
+  layout is not recomputed at the smaller size.
+- A saved size from the earlier steps (90, 80, 70) is ignored once: the page
+  opens at 100% until the reader picks again.