explico 0.3.0 → 0.5.0

package/docs/authoring/migrating.md

@@ -1,15 +1,29 @@
 # 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.
+This is the agent-readable migration artifact shipped with `explico`. It lives
+at `node_modules/explico/docs/authoring/migrating.md` in an installed course, so
+the instructions always accompany the engine version they describe.
+
+There is one newest-first section for **every** published version, not only for a
+version whose changelog contains **Breaking** notes. A section contains the
+concrete work for consumer-owned content, configuration, source wiring, scripts,
+dependencies, and generated artifacts. When a release needs none of those, its
+section says **No course changes required** explicitly. The matching
+`CHANGELOG.md` entry (also shipped in the package) remains the full list of what
+moved and why; it is context, not a replacement for these steps.
 
 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
+1. Record the currently installed version before changing it:
+   `node -p "require('explico/package.json').version"`.
+2. `pnpm add -D explico@<version>`.
+3. Read this file from the newly installed package and apply **every** section
+   after the old version through the target version, oldest first. Do not skip a
+   section merely because its changelog entry is not labelled **Breaking**.
+4. Make every required course-side change named by those sections, including
+   changes under `content/`, Astro/source configuration, and course scripts; do
+   not stop after changing the dependency declaration.
+5. `pnpm validate:content` (run it **twice** — the first run regenerates
    `build/resolution/*` and reports it stale; the second is clean), then
    `pnpm content check --changed`, then `astro check`, then `astro build`.
    Each stage names what it doesn't like; fix and re-run.
@@ -19,6 +33,139 @@ required config block throws with the section of this file to read.
 
 ---
 
+## 0.4.x → 0.5.0
+
+### 1. Rule N14: catalogue every abbreviation used in lesson prose
+
+Every acronym (`OLS`, `MSE`) or dotted abbreviation (`w.r.t.`, `i.i.d.`) used in
+plain prose must now be on the shipped baseline
+(`base-abbreviations.mjs`), listed in `course.config.ts`'s new
+`abbreviations.allow` / `abbreviations.deny`, given an entry in the new
+`content/abbreviations/*.md` collection, or already explained as a math
+quantity via N8/N10. This is build-enforced, same error-severity and
+no-`lint-ignore.yml`-escape-hatch shape as N9.
+
+```ts
+export const courseConfig = {
+  // …existing fields…
+  abbreviations: {
+    allow: ['GDP'],   // treat as universal, skip the check
+    deny: ['ETA'],    // demote a baseline entry back to "must be explained"
+  },
+} satisfies CourseConfig;
+```
+
+```markdown
+---
+key: ols
+abbr: OLS
+expansion: Ordinary least squares
+aliases: []
+---
+```
+
+Run `pnpm validate:content` (twice) and `pnpm content check --changed`. Fix
+every `abbreviation-explained` diagnostic by adding a
+`content/abbreviations/<key>.md` entry or an `allow` entry in
+`course.config.ts`.
+
+### 2. Manifest schema is v13 (additive: v10 → v11 → v12 → v13)
+
+`lessons[].lessonExports`-derived fields (v11), `manifest.abbreviations` (v12),
+and `manifest.diagnostics.rawFloats` (v13) are new. A client asserting on
+`MANIFEST_SCHEMA_VERSION` by exact equality needs the bump; nothing existing
+changed shape.
+
+### 3. Optional: enable standalone HTML / print lesson exports
+
+No action required to keep building. To opt in, add to
+`content/course.config.ts`:
+
+```ts
+lessonExports: {
+  standaloneHtml: true,
+  print: true,
+},
+canonicalBaseUrl: 'https://your-course.example.com',
+```
+
+### 4. Optional: turn on strict numbering cross-checks
+
+`remarkNotation`'s new `strict: true` option — recommended via
+`createRemarkNotationOptions(manifest, { strict: true })` — fails the build on
+any catalogued lesson that has an equation, `<Table>`, or `<Figure>` (keyed or
+not) with no placement, instead of silently falling back to legacy `##`-section
+numbering. Off by default; turn it on once existing content is clean.
+
+### Verification
+
+`pnpm validate:content` (run it twice), then `pnpm content check --changed`,
+then `astro check`, then `astro build`.
+
+---
+
+## 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`