explico 0.1.1 → 0.3.0

package/docs/authoring/README.md

@@ -0,0 +1,96 @@
+# Authoring rules
+
+Content rules for explico courses — strong recommendations for the people and
+agents who write lessons, notation entries, and interactive figures.
+
+## What these are
+
+A course built on explico is authored by many hands — lecturers, TAs, AI
+drafters — over a long time. These files fix the decisions that should not be
+re-litigated per lesson: how a symbol is written, which library draws a graph,
+how a randomised figure picks its axes.
+
+Follow a rule unless you have a concrete, stateable reason not to — and then
+leave that reason in the diff or the PR description. "I preferred it" is not a
+reason; "the cited source writes it this way and the passage shows the mapping"
+is.
+
+Two kinds of rule live here:
+
+- **Build-enforced** — the engine already fails the build when the rule is
+  broken. The rule text tells you _how_ to satisfy the gate, not whether to.
+- **Review-only** — nothing checks it automatically; a reviewer does. Breaking
+  one is a review comment, not a broken build.
+
+Every rule is written to be falsifiable: you can look at a lesson and say
+whether it complies.
+
+## Precedence
+
+1. Build-enforced engine behaviour. If a rule here contradicts what the engine
+   actually does, the engine wins and the rule is stale — fix the rule.
+2. These rules.
+3. Author discretion, recorded in the diff.
+
+A course may add its own rules on top — a house style for prose, a domain glyph
+table. It must not silently relax one of these; loosening a rule is a change to
+this folder, reviewed like any other change.
+
+## How a rule is written
+
+Each rule has a stable ID — a letter for its area (`N` notation,
+`V` visualizations, `C` versioning) plus a number — and this shape:
+
+> **N1 — One-line imperative.**
+> _Rationale._ Why the rule exists; the failure it prevents.
+> _How to apply._ Concrete steps, with the smallest example that shows it.
+> _Enforcement._ Build-enforced (which gate) or Review-only.
+> _Exceptions._ The stateable reasons that override it, if any.
+
+IDs are permanent. A retired rule keeps its number, is struck through in the
+index below, and gains a one-line `Retired <date>: <why>` note — so a `N3` in an
+old commit message never goes ambiguous.
+
+## Amending
+
+1. Open a PR that touches exactly one area file plus the index table below.
+2. Give a new rule the next unused number in its area. Never renumber.
+3. Write the four parts above. If the rule could be build-enforced but is not
+   yet, say so and link the engine issue.
+4. One maintainer review. The bar: is it falsifiable, is the rationale real, is
+   it not already covered by an existing rule or a schema.
+
+A new area — a new letter and file — is the same PR shape plus a row in the
+file table.
+
+## Files
+
+| File                             | Area | Covers                                                     |
+| -------------------------------- | ---- | --------------------------------------------------------- |
+| [notation.md](notation.md)       | `N`  | how math symbols are written and bound                     |
+| [visualizations.md](visualizations.md) | `V` | diagrams, charts, interactive figures, randomness      |
+| [versioning.md](versioning.md)   | `C`  | the knowledge version and `content/CHANGELOG.md`           |
+| [agents.md](agents.md)           | —    | _guide_: working on a course repo (with an AI agent)       |
+| [migrating.md](migrating.md)     | —    | _guide_: per-version steps when bumping the `explico` dep  |
+
+## Rule index
+
+| ID                              | Rule                                                              | Enforcement                                  |
+| ------------------------------- | ---------------------------------------------------------------- | ------------------------------------------- |
+| [N1](notation.md#n1)            | The normal distribution is `\mathcal{N}`                          | Build-enforced (completeness gate) + review |
+| [N2](notation.md#n2)            | `\mathbb{N,Z,R,C}` are reserved for the number systems            | Partial — gate forces every other `\mathbb{}` to resolve |
+| [N3](notation.md#n3)            | Multi-letter roman labels use `\mathrm{…}`                        | Build-enforced (completeness gate)          |
+| [N4](notation.md#n4)            | One meaning per glyph; define once; `[[key]]` before first math   | Build-enforced (completeness gate)          |
+| [N5](notation.md#n5)            | Referenced display equations carry `\label{eq:key}`               | Review-only                                 |
+| [N6](notation.md#n6)            | Probability is `\mathbb{P}` (double-struck `P`)                   | Build-enforced (completeness gate) + review |
+| [N7](notation.md#n7)            | The differential `d` is upright `\mathrm{d}`                       | Build-enforced (completeness gate)          |
+| [N8](notation.md#n8)            | A named operator is universal (shipped/course list) or explained  | Tier-3 warning (`operator-explained`)       |
+| [V1](visualizations.md#v1)      | Graphs and flowcharts use the `Diagram` component                 | Review-only                                 |
+| [V2](visualizations.md#v2)      | Static charts: SVG → D3 → Observable Plot, chosen per figure       | Review-only                                 |
+| [V3](visualizations.md#v3)      | Interactive figures: island + `renderLabMath` seam + text alt      | Review-only                                 |
+| [V4](visualizations.md#v4)      | Randomised figures expose an adjustable, deterministic seed        | Review-only                                 |
+| [V5](visualizations.md#v5)      | Axis ranges span the first 10 seeds at the current control values  | Review-only                                 |
+| [C1](versioning.md#c1)          | Every content change lands with a `content/CHANGELOG.md` entry     | Review-only                                 |
+| [C2](versioning.md#c2)          | The knowledge version is semver over learning-facing content       | Review-only                                 |
+| [C3](versioning.md#c3)          | `about.version` equals the newest `content/CHANGELOG.md` heading   | Build-enforced (Tier-3 `knowledge-version-mismatch`) |
+| [C4](versioning.md#c4)          | On release, move `[Unreleased]` and bump `about.version` together  | Review-only                                 |

package/docs/authoring/agents.md

@@ -0,0 +1,63 @@
+# Working on an explico course (with an agent)
+
+Guidance for an AI agent — or a person — editing a course repo built on
+`explico`. The engine ships this so a downstream course inherits a baseline; add
+a repo-specific `AGENTS.md` at your course root for anything below that is
+particular to your layout.
+
+This is a guide, not a rule area. The enforceable rules are in
+[`notation.md`](notation.md) (`N`), [`visualizations.md`](visualizations.md)
+(`V`), and [`versioning.md`](versioning.md) (`C`). When the engine's behaviour
+and a rule disagree, the engine wins — see [`README.md`](README.md).
+
+## The loop
+
+- **Start from the CLI, not a file hunt.** `pnpm --filter <course> content
+  context <lesson>` prints a lesson plus exactly its notation, references, and
+  assumptions. `pnpm content status` is the draft-debt overview. `pnpm content
+  check <lesson> | --changed` is schema + refs + MDX→KaTeX, exits non-zero on an
+  error. Read those before opening files.
+- **Validate, twice.** `pnpm --filter <course> validate:content` regenerates
+  `build/resolution/*` and then fails on the same run that changed them. Run it
+  again; the second run is clean. Commit the regenerated `build/` and
+  `resolution/` files.
+- **Before handing work back:** `validate:content` (×2) → `astro check` →
+  `astro build`. `astro build` is the only step that runs every gate the CI
+  does.
+
+## Reading and running
+
+- Grep for a symbol and open a line range; don't read a whole engine module out
+  of `node_modules/explico/`. The parts you actually need are
+  [`notation.md`](notation.md), this file, and the `content` CLI output.
+- If a page 500s or a change doesn't show, the dev server's content store is
+  stale — a **new file in a `content/` collection needs a dev-server restart**,
+  not just a save. Restart it; don't diagnose it with `ps` / `curl` scrapes.
+- Ad-hoc Node scripts run from the course package (workspace deps aren't at the
+  repo root); Playwright imports as `@playwright/test`.
+- Pipe long command output to `| tail -n 40`. One-off probes and fetched pages
+  go to a scratch file you then grep — not into the conversation whole.
+
+## Notation `formula:` fields (the sharp edges)
+
+- Every glyph in a `formula:` must resolve: to the entry itself, one of its
+  `glosses:`, a card named with `\explain{key}{latex}`, or the base library.
+  An unresolved bare letter fails the build with the entry name.
+- The notation reference graph must be **acyclic** — if `a`'s formula names `b`
+  and `b`'s names `a`, the build rejects it. Link only *down* a chain
+  (acceleration → velocity → position, not back up).
+- Use `\mathbf` for a vector, not `\vec`: `\vec` currently trips the KaTeX
+  sanitizer in `render-notation-math`. (Engine bug, not a rule — but `\mathbf`
+  is what builds today.)
+
+## Versioning
+
+Every content change adds a bullet under `## [Unreleased]` in
+`content/CHANGELOG.md`; a release moves it to a dated `## [x.y.z]` heading and
+sets `about.version` to match, in the same commit. Rules C1–C4,
+[`versioning.md`](versioning.md).
+
+## Upgrading the engine
+
+[`migrating.md`](migrating.md) — the per-version steps when you bump the
+`explico` dependency across a **Breaking** entry in `CHANGELOG.md`.

package/docs/authoring/migrating.md

@@ -0,0 +1,107 @@
+# Upgrading the explico engine
+
+What a course repo has to change when it bumps its `explico` dependency across a
+version that carries **Breaking** notes. Each section is the concrete work; the
+matching `CHANGELOG.md` entry (shipped in the installed package) is the full
+list of what moved and why.
+
+The pattern every time:
+
+1. `pnpm add -D explico@<version>`
+2. Do the per-version steps below.
+3. `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`.
+   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
+required config block throws with the section of this file to read.
+
+---
+
+## 0.2.x → 0.3.0
+
+### 1. Add the required `about` block to `content/course.config.ts`
+
+`CourseConfig` now requires an `about` block — the reader-facing identity behind
+the header `[?]` panel, and the course's **knowledge version**. Building without
+it throws `course.config.ts is missing a complete about block …`.
+
+```ts
+export const courseConfig = {
+  title: 'My Course',
+  description: '…',
+  // …existing fields…
+  about: {
+    // materialName and summary default to title / description
+    version: '0.1.0',                     // the knowledge version — semver
+    authors: [{ name: 'A. Lecturer', contact: 'a.lecturer@example.edu' }],
+    disclaimer:
+      'Draft study material. No warranty. Parts are AI-assisted and under review.',
+    changelogHref: 'https://…/content/CHANGELOG.md',   // optional
+  },
+} satisfies CourseConfig;
+```
+
+### 2. Add `content/CHANGELOG.md`
+
+The knowledge version (`about.version`) must equal the newest `## [x.y.z]`
+heading in `content/CHANGELOG.md`. A missing file or a mismatch is a Tier-3
+`knowledge-changelog-missing` / `knowledge-version-mismatch` warning (it does
+not fail the build). Governance: [`versioning.md`](versioning.md), rules C1–C4.
+
+```markdown
+# Knowledge changelog — <course>
+
+## [Unreleased]
+
+## [0.1.0] - 2026-01-01
+
+- Initial content.
+```
+
+### 3. Show the About panel
+
+The `[?]` panel renders through Starlight's `SocialIcons` slot. Add it to the
+`components` map in `astro.config.mjs` (alongside the `Footer` override you
+already have):
+
+```js
+starlight({
+  components: {
+    Footer: 'explico/components/starlight/LessonFooter.astro',
+    SocialIcons: 'explico/components/starlight/LayoutSocialIcons.astro',
+    // …
+  },
+})
+```
+
+The build still succeeds without this; the panel just won't appear.
+
+### 4. Only if you imported the equation-reference components directly
+
+`EquationEnhancer` and `EquationRefLayer` are gone, replaced by
+`KeyedFloatEnhancer` + `FloatRefLayer` (one hover/pin/jump engine now shared by
+equation, `Figure`, and `Table` references). **If you only wire
+`Footer: 'explico/components/starlight/LessonFooter.astro'`, there is nothing to
+do** — the swap is internal to that component. Only a course that forked
+`LessonFooter` or imported the old components by hand updates its imports:
+
+| Removed | Use |
+| --- | --- |
+| `explico/components/starlight/EquationEnhancer.astro` | `explico/components/starlight/KeyedFloatEnhancer.astro` |
+| `explico/components/equation/EquationRefLayer.astro` | `explico/components/reference/FloatRefLayer.astro` |
+
+### 5. Regenerate — the manifest schema bumped
+
+`MANIFEST_SCHEMA_VERSION` increased (additive: `manifest.about`,
+`manifest.diagnostics.knowledge`; existing fields unchanged). `pnpm
+validate:content` rewrites `build/manifest.json`; commit the result. An external
+consumer that pins the schema version needs to accept the new number.
+
+### New, no action required
+
+`Figure` / `Table` components with numbering and `[[fig-<id>]]` / `[[tab-<id>]]`
+references; `Diagram` gains `direction="LR"` and an optional `description`;
+`\explain{key}{latex}` works inside notation `formula:` fields; heading anchors
+and numbered equations are on by default.

package/docs/authoring/notation.md

@@ -0,0 +1,296 @@
+# Notation rules
+
+`N` rules govern how a mathematical symbol is written in any rendered-math
+context: lesson body, `notation.formula`, `checks.yml`, assessment prompts, and
+the `formula` slots of `Diagram` / lab components. The completeness gate scans
+all of these, so "the build passed" already means most of what follows holds —
+these rules pin the _choices_ the gate leaves open.
+
+See [README.md](README.md) for what "strong recommendation", "Build-enforced",
+and "Review-only" mean here, and how to amend a rule.
+
+---
+
+## N1
+
+**The normal distribution is `\mathcal{N}`.**
+
+Write a Gaussian as `\mathcal{N}(\mu, \sigma^2)` — calligraphic `N`,
+parameterised by **mean and variance**. Name any other named distribution the
+same way: a calligraphic letter through `\mathcal{…}`.
+
+Do not use `N(\mu, \sigma^2)`, `\mathrm{N}`, `Norm(...)`, or `\mathbb{N}` — the
+last is the natural numbers ([N2](#n2)) and a build-reserved token.
+
+_Rationale._ One corpus-wide spelling makes the symbol searchable, lets it bind
+to a single notation card, and keeps it clear of `N` used as a count and
+`\mathbb{N}` used as a set. Mean/variance is the form the standard-normal CDF
+`\Phi` and PDF `\varphi` compose with cleanly.
+
+_How to apply._
+
+- Define it once. Add a notation entry — a shared card if the course teaches
+  probability, otherwise `notation.local` on the first lesson that needs it:
+
+  ```yaml
+  key: prob.normal
+  latex: \mathcal{N}
+  label: Normal distribution
+  meaning: Gaussian distribution with mean μ and variance σ².
+  ```
+
+  Then introduce it in prose with `[[prob.normal]]` before its first appearance
+  in math, exactly like any other shared glyph ([N4](#n4)).
+
+- In a one-off context where a full entry is overkill, use the escape hatch:
+  `\explain{prob.normal}{\mathcal{N}}(\mu, \sigma^2)`. Prefer the entry.
+
+- If a course standardises on standard deviation rather than variance, state
+  that once in the domain notes, then write `\mathcal{N}(\mu, \sigma)`
+  consistently. Never mix the two forms in one corpus.
+
+- Compose consistently: `X \sim \mathcal{N}(\mu, \sigma^2)`,
+  `\Phi` for its CDF, `\varphi` for its PDF. Pick the CDF/PDF glyphs once per
+  course.
+
+_Enforcement._ Build-enforced that the symbol resolves to a key — `\mathcal{N}`
+is a bindable identifier atom to the glyph resolver, so an undefined one fails
+the completeness gate at `file:line:token`. The choice of `\mathcal{N}` over
+`N` / `\mathrm{N}` / `Norm` is convention, checked in review.
+
+_Exceptions._ Quoting a source that uses a different glyph **and** showing the
+mapping to `\mathcal{N}` in the same passage.
+
+---
+
+## N2
+
+**`\mathbb{N}`, `\mathbb{Z}`, `\mathbb{R}`, `\mathbb{C}` are reserved for the
+number systems.**
+
+These four blackboard-bold tokens mean the naturals, integers, reals, and
+complexes, always, and need no notation key. Every _other_ `\mathbb{…}` —
+`\mathbb{E}`, `\mathbb{P}`, `\mathbb{Q}`, `\mathbb{1}` — is an ordinary
+identifier that must resolve to a semantic key.
+
+_Rationale._ The universal sets are genuinely universal; forcing a per-page
+definition of `\mathbb{R}` would be noise. Everything else in blackboard bold
+is domain-specific (an expectation, a probability measure, an indicator) and
+earns a card.
+
+_How to apply._ Need the rationals as a set on one lesson? That collides with a
+reserved token — reach for `\explain{...}{\mathbb{Q}}` or a differently-styled
+glyph, and note it in the domain vocabulary.
+
+_Enforcement._ Partial. The gate forces every non-reserved `\mathbb{…}` to
+resolve; keeping `N/Z/R/C` for the number systems (not, say, `\mathbb{N}` for a
+sample size) is convention.
+
+_Exceptions._ None for the four reserved tokens.
+
+---
+
+## N3
+
+**Multi-letter roman labels use `\mathrm{…}`.**
+
+An upright multi-letter name — `\mathrm{PV}`, `\mathrm{opt}`, `\mathrm{max}`
+where no built-in operator exists — is wrapped in `\mathrm{}`. Never write it as
+a run of bare italic letters (`PV`), which reads as a product `P \cdot V`.
+
+_Rationale._ `\mathrm{}` is a typographic label, not a bindable atom — the glyph
+resolver skips its body whole. Bare letter runs are parsed as identifier atoms,
+so `PV` asks the gate to resolve `P` and `V` separately: a build failure at
+best, a wrong binding at worst.
+
+_How to apply._ Subscripts too: `v_{\mathrm{max}}`, not `v_{max}`.
+
+_Enforcement._ Build-enforced indirectly — bare multi-letter runs hit the
+completeness gate as unresolved identifiers.
+
+_Exceptions._ Genuine products, and single-letter subscripts that are
+themselves notation keys.
+
+---
+
+## N4
+
+**One meaning per glyph per page; define once; introduce with `[[key]]` before
+the first math use.**
+
+A glyph has exactly one meaning on a page. A shared symbol is introduced in
+prose with `[[key]]` before it appears in any equation. `\explain{key}{latex}`
+is the escape hatch for a compound or glyph-colliding symbol only — not the
+default way to bind.
+
+_Rationale._ This is the core contract the completeness gate enforces
+corpus-wide; the rule here is just its author-facing statement. A reader hovers
+any symbol and gets exactly one card.
+
+_How to apply._ See the engine README's notation section and the `notation`
+collection schema. 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.
+
+_Enforcement._ Build-enforced (completeness gate + one-meaning-per-glyph
+consistency check).
+
+_Exceptions._ None. Genuinely different meanings need different glyphs or
+different pages.
+
+---
+
+## N5
+
+**A display equation referenced later carries `\label{eq:key}`.**
+
+If prose points back at a display equation — this page or another — the equation
+has `\label{eq:key}` and the reference is `[[eq-key]]`. Do not hand-number
+equations in the text.
+
+_Rationale._ The engine numbers every display equation `‹chapter›.‹n›` — the
+chapter is the lesson's position in the course, `n` counts the display
+equations in the lesson in appearance order (`##` sub-headings do not affect
+it) — and derives the anchor and any cross-lesson link from the label. A
+hand-typed "(3)" goes stale the moment an equation is inserted above it, or the
+lesson moves in the course order. `<Table>` and `<Figure>` are numbered the
+same way, each with its own counter.
+
+_How to apply._ Only label equations you actually reference; an unlabelled
+display equation is still fine.
+
+_Enforcement._ Review-only — an unlabelled-but-referenced equation builds; a
+reviewer catches the hand-numbering.
+
+_Exceptions._ None worth stating.
+
+---
+
+## N6
+
+**Probability is `\mathbb{P}` — double-struck `P`.**
+
+Write a probability as `\mathbb{P}(A)` — blackboard-bold `P`. Not `P(A)` (a bare
+`P` is a variable — a price, a power, a point), not `\Pr`, not `\text{Prob}`.
+Expectation is the same family: `\mathbb{E}[X]`.
+
+_Rationale._ `\mathbb{P}` is unmistakably the probability functional, never a
+quantity. It reads next to `\mathbb{E}` and `\mathbb{Q}` as one notation family
+and never collides with a `P` the lesson uses for something physical.
+
+_How to apply._
+
+- Define it once, like [N1](#n1):
+
+  ```yaml
+  key: prob.p
+  latex: \mathbb{P}
+  label: Probability
+  meaning: Probability of an event.
+  ```
+
+  Introduce it in prose with `[[prob.p]]` before its first appearance in math.
+
+- Conditional probability is `\mathbb{P}(A \mid B)` — `\mid`, not a bare `|`.
+
+- A course doing measure theory may define `\mathbb{P}` as the real-world
+  measure and `\mathbb{Q}` as a risk-neutral one, consistent with the reserved
+  reading of `\mathbb{Q}` ([N2](#n2)). State that split once in the domain
+  notes.
+
+_Enforcement._ Build-enforced that the symbol resolves to a key — `\mathbb{P}`
+is a non-reserved `\mathbb{…}` and the completeness gate demands a binding
+([N2](#n2)). The choice of `\mathbb{P}` over `P` / `\Pr` is convention.
+
+_Exceptions._ Quoting a source that writes `\Pr` or `P` **and** showing the
+mapping to `\mathbb{P}` in the same passage.
+
+---
+
+## N7
+
+**The differential `d` is upright `\mathrm{d}`.**
+
+The `d` of an integrand and the `d` of a derivative are the same operator and
+get the same upright form — distinct from an italic `d`, which is always a
+variable (a distance, a day count, a dimension):
+
+- `\int_a^b f(x)\,\mathrm{d}x` — thin space `\,`, then `\mathrm{d}x`.
+- `\dfrac{\mathrm{d}f}{\mathrm{d}x}`, `\dfrac{\mathrm{d}^2 f}{\mathrm{d}x^2}`.
+- `\mathrm{d}s`, `\mathrm{d}A`, `\mathrm{d}V`, `\mathrm{d}t` — same rule for
+  every differential.
+
+A partial derivative uses `\partial` bare — `\dfrac{\partial f}{\partial x}` —
+which is already distinct; do not wrap it in anything.
+
+_Rationale._ This is the ISO 80000-2 convention. Upright `\mathrm{d}` cannot be
+read as a factor `d \cdot x`, and it stays clear of a notation key `d` on a
+lesson that happens to have one.
+
+_How to apply._ `\mathrm{d}` is a typographic operator, not a bindable atom —
+the glyph resolver skips its body like any `\mathrm{…}` label ([N3](#n3)), so it
+needs no notation key. Only the variable of integration (`x`, `t`) still has to
+resolve.
+
+_Enforcement._ Build-enforced indirectly — a bare `\int f(x) dx` puts an
+unresolved identifier `d` in front of the completeness gate ([N3](#n3)).
+
+_Exceptions._ A verbatim quotation of a source in a blockquote.
+
+---
+
+## N8
+
+**A named operator is universal, or it is explained.**
+
+Every named operator a lesson uses — `\exp`, `\int`, `\sin`, … as built-ins,
+`\operatorname{Var}`, `\operatorname{Cov}`, `\operatorname{E}` as declared ones
+— is either on the shipped operator baseline (`src/reference/base-operators.mjs`
+plus this course's `operators.allow` in `course.config.ts`) or it carries a
+notation entry the reader can hover.
+
+_Rationale._ The completeness gate has no opinion about operators: KaTeX parses
+`\exp` as an operator node and `\operatorname{Var}` as an `operatorname` node,
+and the glyph resolver skips both whole ([N3](#n3)). So `\operatorname{Var}`
+renders fine while the reader is never told what "Var" means. `\exp` and `\int`
+need no such help — everyone knows them — but a domain operator does, and the
+line between the two is a course decision, made once, not per lesson.
+
+_How to apply._
+
+- Universal operators — trig, `\exp` / `\ln` / `\log`, `\lim`, `\max` / `\min`
+  / `\sup` / `\inf`, `\sum` / `\prod` / `\int` — just work. The full baseline is
+  the greppable set in `base-operators.mjs`.
+
+- A domain operator gets a notation entry, exactly like a glyph ([N4](#n4)) — a
+  shared card if the course teaches it broadly, otherwise `notation.local`:
+
+  ```yaml
+  key: stats.variance
+  latex: \operatorname{Var}
+  label: Variance
+  meaning: Expected squared deviation of a random variable from its mean.
+  ```
+
+  Then introduce it in prose with `[[stats.variance]]` before its first
+  appearance in math, and write it `\operatorname{Var}(X)` — never `Var(X)`
+  (bare letters, [N3](#n3)) and never `\mathrm{Var}` (a label, not an operator).
+
+- A course whose domain treats an operator as common — `\operatorname{Var}`,
+  `\operatorname{Cov}`, `\operatorname{Corr}`, `\operatorname{sgn}` in a
+  statistics course — lists it once in `course.config.ts` instead:
+
+  ```ts
+  operators: { allow: ['Var', 'Cov', 'Corr', 'sgn'] }
+  ```
+
+  Names are the `\operatorname{…}` body, or the command without its backslash
+  for a built-in. `operators.deny` forces a baseline operator to be explained
+  anyway.
+
+_Enforcement._ Tier-3 warning (`operator-explained`), surfaced by
+`pnpm validate:content`, recorded in the manifest, and silenced only by a
+reviewed line in `lint-ignore.yml` (`operator-explained:Var — <reason>`). Like
+`formula` before it (D15), the tier can be promoted once a corpus is clean.
+
+_Exceptions._ Quoting a source that uses an operator glyph **and** showing what
+it means in the same passage.

package/docs/authoring/versioning.md

@@ -0,0 +1,116 @@
+# Versioning rules
+
+`C` rules govern the course's **knowledge version** — semver over the
+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.
+
+See [README.md](README.md) for what "Build-enforced" and "Review-only" mean here.
+The engine's own versioning is a separate policy —
+[`docs/VERSIONING.md`](../VERSIONING.md).
+
+---
+
+## C1
+
+**Every content change lands with a `content/CHANGELOG.md` entry under
+`## [Unreleased]`.**
+
+A change to any lesson `.mdx`, notation entry, assessment, competency, source,
+`content/domain/` file, or `course.config.ts` gets a bullet under
+`## [Unreleased]` in the same commit.
+
+_Rationale._ The knowledge version is meaningless without a record of what moved
+between two values of it. A reader who sees "knowledge v1.4.0" in the `[?]` panel
+can follow `changelogHref` to find out what 1.4.0 means.
+
+_How to apply._ Keep a Changelog shape. One bullet per user-visible change,
+written for a reader, not a commit log:
+
+```markdown
+## [Unreleased]
+
+- Reworked the "Optimal Launch Angle" derivation to use the identity
+  `sin(2θ) = 2 sinθ cosθ` explicitly.
+- New lesson: "Projectile Range with Drag" (motion.range-drag).
+```
+
+_Enforcement._ Review-only. Rule [C3](#c3) partially enforces it: a content
+change with no matching version bump eventually trips the mismatch warning.
+
+_Exceptions._ A pure typo fix in prose that changes no rendered symbol, no
+number, and no outcome. When in doubt, add the bullet.
+
+---
+
+## C2
+
+**The knowledge version is semver over learning-facing content.**
+
+Pick the bump by the largest change in the release:
+
+- **MAJOR** — a lesson, competency, or notation `key` is removed or renamed; a
+  stated learning outcome (`teaches`, a competency `outcome`) changes; a result
+  or convention a reader may have memorised changes.
+- **MINOR** — something new and backward-compatible: a new lesson, section,
+  notation entry, assessment, or worked example.
+- **PATCH** — a fix or clarification: corrected arithmetic, better prose, a added
+  or fixed `[@source]`, a non-semantic notation tweak.
+
+_Rationale._ A downstream consumer of the content (an LMS import, a printed
+reader, a course that forks this one) needs the same "did this break me?" signal
+from the knowledge version that a library gets from a package version.
+
+_How to apply._ Decide the bump when you move `## [Unreleased]` to a dated
+heading ([C4](#c4)); set `about.version` to match.
+
+_Enforcement._ Review-only.
+
+_Exceptions._ None. If a change does not fit a tier, it is PATCH.
+
+---
+
+## C3
+
+**`about.version` equals the newest `## [x.y.z]` heading in
+`content/CHANGELOG.md`.**
+
+_Rationale._ Two sources of the same fact must not drift. The manifest — and so
+the `[?]` panel — reads `about.version`; a reader chasing "what changed" reads
+the changelog. If they disagree, one is lying.
+
+_How to apply._ On a release, edit both in the same commit ([C4](#c4)). Between
+releases, `about.version` stays at the last released value while
+`## [Unreleased]` accumulates bullets.
+
+_Enforcement._ Build-enforced (Tier-3). `pnpm validate:content` emits
+`knowledge-version-mismatch` when they differ, `knowledge-changelog-missing`
+when there is no released heading, and `knowledge-version-invalid` when
+`about.version` is not `x.y.z`. All are warnings — they never fail the build, but
+CI may choose to.
+
+_Exceptions._ None.
+
+---
+
+## C4
+
+**On a release, move `## [Unreleased]` to `## [x.y.z] - YYYY-MM-DD` and bump
+`about.version` in the same commit.**
+
+_Rationale._ A release is the atomic moment the two records agree again
+([C3](#c3)). Splitting it across commits leaves a window where the build warns
+and the panel is wrong.
+
+_How to apply._
+
+1. Choose `x.y.z` from the accumulated `## [Unreleased]` bullets and [C2](#c2).
+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.
+
+_Enforcement._ Review-only (the end state is checked by [C3](#c3)).
+
+_Exceptions._ None.