explico 0.2.0 → 0.4.0

package/docs/authoring/README.md

@@ -0,0 +1,100 @@
+# 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
+
+[`structure.md`](structure.md) is not a rule set — it is the taxonomy the rules
+speak in: what a part, a chapter, a section, and a subsection are, and which of
+them an equation number counts.
+
+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,169 @@
+# 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.3.x → 0.4.0
+
+### 1. Rename `sections` to `parts` in `content/course.config.ts`
+
+A sidebar group is now a **part** — "section" only ever means an `##` heading
+inside a lesson. See [`structure.md`](structure.md) for the full taxonomy.
+
+```diff
+-  sections: [
++  parts: [
+     { dir: 'foundations', label: 'Foundations' },
+     { dir: 'bonds', label: 'Bonds' },
+   ],
+```
+
+`sections` is still read, so this is not urgent; it is removed in the next
+MINOR release.
+
+### 2. Pass the manifest to `remarkNotation`
+
+Replace the individual numbering options with the manifest itself. This is what
+guarantees the number a page prints and the number a reference to it prints are
+computed from the same inputs — supplying one without the other is what made an
+equation read `(2.2)` on its own page and `(4.5)` everywhere else.
+
+```diff
+   [remarkNotation, {
+     definitions: manifest.notation.raw,
+-    equations: manifest.equations.numbersBySlug,
++    manifest,
+     base: publicBase,
+   }],
+```
+
+The engine now cross-checks the two and **fails the build** when they disagree,
+so a config left half-wired errors instead of shipping wrong numbers.
+
+### 3. Expect every equation, table, and figure number to change
+
+Numbers are now `‹part›.‹n›`: the prefix is the part's ordinal, and `n` runs
+across the whole part rather than restarting on each page. A course whose
+lessons were chapters 1…16 now has as many prefixes as it has sidebar groups.
+
+Nothing in `content/` needs editing — numbers were never hand-typed, and every
+`[[eq-key]]` / `[[slug#eq-key]]` reference keeps resolving. Two things to check:
+
+- **Prose that spells a number out** ("as equation 4.5 showed") was already
+  against rule N-references; find it with `grep -rnE '\((1?[0-9])\.[0-9]+\)'
+  content/` and convert it to a `[[eq-key]]` reference.
+- **External links to a positional anchor** (`#eq-2-4`, an *unkeyed* equation)
+  now point elsewhere. Keyed anchors (`#eq-<key>`) are stable and unaffected —
+  give an equation a `\label{eq:…}` if you need to link to it from outside.
+
+### 4. Manifest schema is v7
+
+`lessons[].part` is new; `lessons[].chapter` now means the lesson's ordinal
+*within its part*, not down the whole course; `lessons[].numbering` carries the
+running float counts each chapter starts from. A client asserting on
+`MANIFEST_SCHEMA_VERSION` needs the bump.
+
+---
+
+## 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,297 @@
+# 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 `‹part›.‹n›` — the part
+is the sidebar group's position in `courseConfig.parts`, `n` counts the display
+equations across that whole part in appearance order, continuing from one
+chapter into the next (`##` and `###` headings do not affect it; see
+[`structure.md`](structure.md)) — 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 chapter moves within its part. `<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.