explico 0.4.0 → 0.5.0

package/dist/reference/remark-short-note.mjs

@@ -0,0 +1,237 @@
+/**
+ * Remark adapter for reveal-in-place short notes.
+ *
+ * A `<ShortNote>` may sit inside a sentence while its body contains block
+ * Markdown. Before mdast parsing, the adapter extracts that body and leaves an
+ * ordinary inline link placeholder behind. After parsing, it inserts the real
+ * flow component immediately after the intact paragraph. The browser enhancer
+ * can then split/rejoin that paragraph only while the note is open, preserving
+ * valid and genuinely inline collapsed markup.
+ */
+
+import { stripFencedCode } from './equations.mjs';
+import { KEYED_FLOAT_KEY_PATTERN } from './keyed-jsx-floats.mjs';
+import {
+  injectMdxStringAttributes,
+  mdxAttributesNamed,
+  removeMdxAttribute,
+} from './mdx-attributes.mjs';
+
+const BLOCK_ATTRIBUTE = 'data-explico-short-note-block';
+const BLOCKS_DATA = 'explicoShortNoteBlocks';
+const MARKER_URL_PREFIX = '#explico-internal-short-note-marker-';
+const ATTRIBUTE_SOURCE = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+const SHORT_NOTE_PAIR = new RegExp(
+  String.raw`<ShortNote\b(${ATTRIBUTE_SOURCE})>([\s\S]*?)<\/ShortNote\s*>`,
+  'g',
+);
+
+function maskBlock(block) {
+  return block.replace(/[^\n]/g, ' ');
+}
+
+function searchableSource(source) {
+  return stripFencedCode(source)
+    .replace(/<!--[\s\S]*?-->/g, maskBlock)
+    .replace(/\{\/\*[\s\S]*?\*\/\}/g, maskBlock);
+}
+
+function extractShortNotes(source) {
+  const input = String(source);
+  const searchable = searchableSource(input);
+  const matches = [...searchable.matchAll(SHORT_NOTE_PAIR)];
+  if (matches.length === 0) return { source: input, notes: [] };
+
+  const notes = [];
+  let cursor = 0;
+  let output = '';
+  for (let index = 0; index < matches.length; index++) {
+    const match = matches[index];
+    const start = match.index ?? 0;
+    if (start < cursor) continue;
+
+    const whole = match[0];
+    const maskedAttributes = match[1] ?? '';
+    const openLength = '<ShortNote'.length + maskedAttributes.length + 1;
+    const bodyStart = start + openLength;
+    const closeStart = start + whole.lastIndexOf('</ShortNote');
+    const searchableBody = searchable.slice(bodyStart, closeStart);
+    if (/<ShortNote\b/.test(searchableBody)) {
+      throw new Error('A <ShortNote> cannot be nested inside another <ShortNote>.');
+    }
+
+    notes.push({
+      token: String(index),
+      attributes: input.slice(start + '<ShortNote'.length, bodyStart - 1),
+      body: input.slice(bodyStart, closeStart),
+    });
+    output += input.slice(cursor, start);
+    output += `[short note](${MARKER_URL_PREFIX}${index})`;
+    cursor = start + whole.length;
+  }
+  output += input.slice(cursor);
+  return { source: output, notes };
+}
+
+/** Return the parseable source form, primarily for adapter tests. */
+export function preprocessShortNotes(source) {
+  return extractShortNotes(source).source;
+}
+
+function fail(file, message, node) {
+  if (typeof file?.fail === 'function') file.fail(message, node);
+  const location = file?.path ? `${file.path}: ` : '';
+  throw new Error(`${location}${message}`);
+}
+
+function literalAttribute(node, name, file) {
+  const matches = mdxAttributesNamed(node, name);
+  if (matches.length > 1) {
+    fail(file, `<ShortNote> has more than one \`${name}\` prop.`, node);
+  }
+  if (matches.length === 0) {
+    fail(file, `<ShortNote> requires a non-empty literal \`${name}\` prop.`, node);
+  }
+  const value = matches[0]?.value;
+  if (typeof value !== 'string' || !value.trim()) {
+    fail(
+      file,
+      `<ShortNote> \`${name}\` must be a non-empty literal string; expressions are not supported for inline note triggers.`,
+      matches[0] ?? node,
+    );
+  }
+  return value;
+}
+
+function markerNode(note) {
+  return {
+    type: 'link',
+    url: `#${note.anchorId}`,
+    children: [{ type: 'text', value: note.title }],
+    data: {
+      hProperties: {
+        className: ['short-note-marker'],
+        'data-short-note-key': note.id,
+        'aria-controls': note.anchorId,
+        'aria-expanded': 'false',
+        'aria-label': `${note.title}: ${note.description}`,
+        title: note.description,
+      },
+    },
+  };
+}
+
+function visit(node, callback, parent) {
+  if (!node || typeof node !== 'object') return;
+  callback(node, parent);
+  if (!Array.isArray(node.children)) return;
+  for (const child of node.children) visit(child, callback, node);
+}
+
+/** @this {any} */
+export default function remarkShortNote() {
+  const processor = this;
+  const parse = processor.parser;
+  if (typeof parse !== 'function') {
+    throw new Error(
+      'remarkShortNote must be registered after the Markdown parser (and after remark-mdx when configured explicitly).',
+    );
+  }
+
+  Reflect.set(processor, 'parser', (document, file) => {
+    const extracted = extractShortNotes(document);
+    const tree = parse(extracted.source, file);
+    if (extracted.notes.length === 0) return tree;
+
+    const blocks = extracted.notes.map((note) => {
+      const source = `<ShortNote ${BLOCK_ATTRIBUTE}="${note.token}"${note.attributes}>\n\n${note.body}\n\n</ShortNote>`;
+      const parsed = parse(source, file);
+      const block = parsed.children?.find((node) => node?.name === 'ShortNote');
+      if (!block) {
+        fail(file, 'Unable to parse the extracted <ShortNote> body.', parsed);
+      }
+      return block;
+    });
+    tree.data ??= {};
+    tree.data[BLOCKS_DATA] = blocks;
+    return tree;
+  });
+
+  return function transform(tree, file) {
+    const blocks = tree.data?.[BLOCKS_DATA] ?? [];
+    if (blocks.length === 0) return;
+
+    const markers = new Map();
+    const parents = new Map();
+    visit(tree, (node, parent) => {
+      if (parent) parents.set(node, parent);
+      if (
+        node.type === 'link' &&
+        typeof node.url === 'string' &&
+        node.url.startsWith(MARKER_URL_PREFIX)
+      ) {
+        const token = node.url.slice(MARKER_URL_PREFIX.length);
+        if (markers.has(token)) fail(file, 'Internal short-note marker collision.', node);
+        markers.set(token, { node, parent });
+      }
+    });
+
+    if (blocks.length !== markers.size) {
+      fail(file, 'Internal short-note marker/block pairing failed.', tree);
+    }
+
+    const seenIds = new Set();
+    const insertions = new Map();
+    for (const block of blocks) {
+      const token = literalAttribute(block, BLOCK_ATTRIBUTE, file);
+      const marker = markers.get(token);
+      if (!marker?.parent || marker.parent.type !== 'paragraph') {
+        fail(file, '<ShortNote> must be placed in ordinary prose.', marker?.node ?? block);
+      }
+      const container = parents.get(marker.parent);
+      if (!container || !Array.isArray(container.children)) {
+        fail(file, 'A <ShortNote> paragraph has no flow parent.', marker.parent);
+      }
+      if (block.type !== 'mdxJsxFlowElement') {
+        fail(file, '<ShortNote> did not become a block-level MDX element.', block);
+      }
+
+      const id = literalAttribute(block, 'id', file);
+      const title = literalAttribute(block, 'title', file);
+      const description = literalAttribute(block, 'description', file);
+      if (!KEYED_FLOAT_KEY_PATTERN.test(id)) {
+        fail(
+          file,
+          `Invalid <ShortNote id="${id}">; use lowercase letters/numbers separated by single hyphens.`,
+          block,
+        );
+      }
+      if (seenIds.has(id)) {
+        fail(file, `Duplicate <ShortNote id="${id}"> on this page.`, block);
+      }
+      seenIds.add(id);
+
+      const anchorId = `short-note-${id}`;
+      removeMdxAttribute(block, BLOCK_ATTRIBUTE);
+      injectMdxStringAttributes(block, { anchorId });
+
+      const markerIndex = marker.parent.children.indexOf(marker.node);
+      marker.parent.children[markerIndex] = markerNode({
+        id,
+        title,
+        description,
+        anchorId,
+      });
+
+      const existing = insertions.get(marker.parent) ?? { container, blocks: [] };
+      existing.blocks.push(block);
+      insertions.set(marker.parent, existing);
+    }
+
+    for (const [paragraph, insertion] of insertions) {
+      const paragraphIndex = insertion.container.children.indexOf(paragraph);
+      insertion.container.children.splice(paragraphIndex + 1, 0, ...insertion.blocks);
+    }
+    delete tree.data[BLOCKS_DATA];
+  };
+}

package/dist/reference/types.d.ts

@@ -84,6 +84,21 @@ interface NotationRegistryInput {
     readonly sharedDefinitions: readonly SharedNotationDefinitionInput[];
     readonly lessons: readonly NotationLessonInput[];
 }
+/**
+ * One entry in the abbreviations table (N14) — deliberately a lighter tier
+ * than {@link SharedNotationDefinitionInput}: a name resolution only, no
+ * `formula`, `units`, `alignment`, or `sources`. `abbr` is the canonical
+ * written form (`OLS`); `aliases` are other written forms of the same
+ * abbreviation (`w.r.t.` might alias `wrt`) that should resolve the same way.
+ */
+interface AbbreviationDefinitionInput {
+    readonly key: string;
+    readonly abbr: string;
+    readonly expansion: string;
+    readonly aliases: readonly string[];
+    readonly domain?: string;
+    readonly source: SourceSpan;
+}
 type NotationDiagnosticCode = 'invalid-key' | 'duplicate-page' | 'duplicate-definition' | 'conflicting-definition' | 'undefined-reference' | 'reference-cycle' | 'unused-definition' | 'alignment-unknown-competency' | 'alignment-unknown-lesson' | 'alignment-introduction' | 'alignment-unavailable' | 'alignment-review-state' | 'gloss-collides-with-card';
 type DiagnosticSeverity = 'error' | 'warning';
 interface NotationDiagnostic {
@@ -171,4 +186,4 @@ interface NotationRegistry {
     readonly diagnostics: readonly NotationDiagnostic[];
 }
 
-export type { DiagnosticSeverity, EditorialStatus, LocalNotationDefinitionInput, LocalNotationDefinitionRecord, NotationAlignment, NotationBacklink, NotationBinding, NotationDefinitionRecord, NotationDefinitionScope, NotationDiagnostic, NotationDiagnosticCode, NotationGlossEntry, NotationLessonInput, NotationPageBundle, NotationReferenceInput, NotationReferenceKind, NotationRegistry, NotationRegistryInput, ResolvedNotationReference, SharedNotationDefinitionInput, SharedNotationDefinitionRecord, SourceSpan };
+export type { AbbreviationDefinitionInput, DiagnosticSeverity, EditorialStatus, LocalNotationDefinitionInput, LocalNotationDefinitionRecord, NotationAlignment, NotationBacklink, NotationBinding, NotationDefinitionRecord, NotationDefinitionScope, NotationDiagnostic, NotationDiagnosticCode, NotationGlossEntry, NotationLessonInput, NotationPageBundle, NotationReferenceInput, NotationReferenceKind, NotationRegistry, NotationRegistryInput, ResolvedNotationReference, SharedNotationDefinitionInput, SharedNotationDefinitionRecord, SourceSpan };

package/dist/reference/units-vocab.js

@@ -103,6 +103,10 @@ const UNITS_VOCAB = /* @__PURE__ */ new Set([
   "meters",
   "second",
   "seconds",
+  "kilogram",
+  "kilograms",
+  "joule",
+  "joules",
   "speed",
   "velocity",
   "acceleration",

package/docs/VERSIONING.md

@@ -48,15 +48,44 @@ every one is listed under a `### Breaking` heading in `CHANGELOG.md` for that
 version. A **PATCH** never breaks. Once the API settles this clause is dropped
 and normal semver applies.
 
+## The migration artifact
+
+Every published engine version carries agent-readable upgrade instructions in
+[`authoring/migrating.md`](authoring/migrating.md). That file is part of the npm
+package, so the instructions travel with the exact implementation they describe
+and remain available at
+`node_modules/explico/docs/authoring/migrating.md` after installation.
+
+A release must add a newest-first `## <previous range> → <new version>` section,
+whether the bump is MAJOR, MINOR, or PATCH. The section must do one of two things:
+
+- give concrete, ordered changes for every affected consumer-owned surface —
+  dependency declarations, `content/`, `content/course.config.ts`, Astro/source
+  wiring, course scripts, and generated artifacts — including conditional cases
+  and verification commands; or
+- state explicitly that no course changes are required, followed by the normal
+  verification commands.
+
+The changelog explains what changed and why; it is not a substitute for the
+migration section. The migration section, changelog entry, version bump, and
+package are one atomic release. An agent upgrading across several versions
+applies every intervening section in order.
+
 ## Cutting a release
 
 1. Decide the next version from the rules above and the `## [Unreleased]`
    section of `CHANGELOG.md`.
-2. `CHANGELOG.md`: rename `## [Unreleased]` to `## [x.y.z] - YYYY-MM-DD`, add a
+2. Add the section for `x.y.z` to `docs/authoring/migrating.md`, derived from the
+   complete release diff. Write explicit no-action instructions when nothing in
+   a downstream course needs to change.
+3. `CHANGELOG.md`: rename `## [Unreleased]` to `## [x.y.z] - YYYY-MM-DD`, add a
    fresh empty `## [Unreleased]`, and fix up the compare links at the bottom.
-3. Bump `package.json` `version` (`npm version x.y.z --no-git-tag-version`).
-4. `pnpm build && pnpm test`.
-5. Commit, then `git tag vx.y.z`.
+4. Bump `package.json` `version` (`npm version x.y.z --no-git-tag-version`).
+5. Run `pnpm check:release-migration`. It fails when the new version has no
+   migration section or the shipped-file configuration excludes the guide.
+6. Run `pnpm build && pnpm test`, then inspect `pnpm pack --dry-run` and confirm
+   that `docs/authoring/migrating.md` and `docs/authoring/agents.md` are listed.
+7. Commit, then `git tag vx.y.z`.
 
 ## When you change the engine
 

package/docs/authoring/README.md

@@ -74,6 +74,7 @@ file table.
 | [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`           |
+| [components.md](components.md)   | —    | _catalog_: inline/block features available in a lesson body — tooltips, tables, figures, diagrams, memos, abbreviations, citations |
 | [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  |
 
@@ -89,6 +90,13 @@ file table.
 | [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`)       |
+| [N9](notation.md#n9)            | A quantity/unit/operator is typeset in `$…$`, never as plain text  | Build-enforced (`gate-prose-notation.ts`)   |
+| [N10](notation.md#n10)          | A `\mathrm{…}` multi-letter label is universal, or it is explained | Tier-3 warning (`roman-label-explained`)    |
+| [N11](notation.md#n11)          | A worked example never drops a unit from a substituted value       | Review-only                                 |
+| [N12](notation.md#n12)          | Math syntax never carries the sentence's own trailing punctuation  | Review-only                                 |
+| [N13](notation.md#n13)          | A nonlinear function always takes a parenthesized argument         | Build-enforced (`resolveMathGlyphs`)        |
+| [N14](notation.md#n14)          | An abbreviation-shaped word in prose is universal, or explained    | Build-enforced (`gate-abbreviations.ts`)    |
+| [N15](notation.md#n15)          | A nested `(`, `[`, `{`, or `\|` must use `\left`/`\right` sizing    | Build-enforced (`resolveMathGlyphs`)        |
 | [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                                 |

package/docs/authoring/agents.md

@@ -30,6 +30,9 @@ and a rule disagree, the engine wins — see [`README.md`](README.md).
 - 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.
+- Not sure what's available to put in a lesson body — a tooltip, a table, a
+  diagram, an aside? [`components.md`](components.md) is a syntax-first
+  catalog, not another rule file to read cover to cover.
 - 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.
@@ -59,5 +62,17 @@ sets `about.version` to match, in the same commit. Rules C1–C4,
 
 ## Upgrading the engine
 
-[`migrating.md`](migrating.md) — the per-version steps when you bump the
-`explico` dependency across a **Breaking** entry in `CHANGELOG.md`.
+Treat every `explico` dependency bump as a migration task, including PATCH
+updates. Before changing the dependency, record the installed version with
+`node -p "require('explico/package.json').version"`. Install the target version,
+then read the target package's
+`node_modules/explico/docs/authoring/migrating.md`; the migration instructions
+ship with the code they describe.
+
+Apply every version section after the old version through the installed version,
+oldest first. Follow 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 that a release without a **Breaking** heading needs no work; each migration
+section either gives exact work or explicitly says no course changes are
+required. Finish with the validation sequence in [`migrating.md`](migrating.md).

package/docs/authoring/components.md

@@ -0,0 +1,135 @@
+# Inline & block features — a catalog
+
+A fast index of what can go in a lesson body, for an AI (or a person) drafting
+content without reading every rule file first. This file is not a rule area —
+nothing here is build-enforced by *this* file. Where a feature has a rule
+area (`N`, `V`, `C`), the enforcement and the rationale live there; this file
+only says what exists, its minimal syntax, and which of several
+similar-looking options to reach for.
+
+See [README.md](README.md) for what "Build-enforced" / "Review-only" means,
+[structure.md](structure.md) for the five structural levels and how floats
+are numbered, and [agents.md](agents.md) for the day-to-day workflow (CLI,
+validation loop).
+
+## Inline, zero-registration
+
+**A native browser tooltip: `title="…"` on any element.**
+
+```mdx
+The fit uses <span title="Ordinary least squares run on the demeaned series">OLS</span> here.
+```
+
+This is plain HTML passed straight through MDX/JSX to the DOM — no `id`, no
+content-collection entry, no build-time registration, no hover-card styling,
+no click-to-pin behaviour. The browser renders its own default tooltip on
+hover/focus, exactly like a native `<abbr title="…">` or an image `alt`
+tooltip would. Use it for a throwaway aside that doesn't deserve a citable,
+numbered, or glossary-linked definition — a wording nudge, a "why this value"
+note, a translation of a variable name.
+
+_How to apply._ Any element takes `title`; `<span>` is the usual wrapper for
+bare prose text that has no other markup reason to exist. `title` is a plain
+DOM string: no `$…$` math rendering happens inside it (same carve-out
+[N9](notation.md#n9) documents for `<Figure caption="…">` / `<Table
+caption="…">`) — write a unit as a word or plain Unicode, not LaTeX.
+
+_What it does **not** replace:_
+
+- **An abbreviation-shaped word in visible prose still has to satisfy
+  [N14](notation.md#n14).** The completeness gates blank out JSX *tags*
+  (`<span title="…">…</span>` → the `<span …>` and `</span>` markup) but not
+  the *text a reader sees between them* — so wrapping `OLS` in a tooltip span
+  does not exempt that visible `OLS` from needing a real
+  `content/abbreviations/*.md` entry, a notation binding, or a
+  `course.config.ts` allowlist entry. `title="…"` adds a hover hint on top of
+  an otherwise-explained term; it is not itself an explanation the gate
+  recognizes. If the word only ever needs to exist inside the tooltip string
+  (never as the visible text), the gate never sees it and there is nothing to
+  satisfy.
+- **A math quantity still goes in `$…$`, not a `title`.** A hover *card* with
+  the definition, one per glyph, page-wide — that's `[[key]]` / notation
+  entries ([N4](notation.md#n4)), unrelated machinery.
+- **A citable, reusable, or numbered explanation** — something another page
+  should be able to link to, or that belongs in the glossary — is a
+  [`<ShortNote>`/`<Memo>`](#short-asides-and-detours) or an
+  [abbreviation entry](#reference-systems), not a tooltip. A `title` string
+  is invisible to search, screen-reader users relying on non-hover
+  interaction, and print/PDF export.
+
+_Enforcement._ None — this is unregistered, ungated HTML. The only thing that
+still applies is N9/N14 against the *visible* text, as above.
+
+## Short asides and detours
+
+| Component | Import | What it's for | Doc |
+| --- | --- | --- | --- |
+| `<ShortNote id="…" title="…" description="…">` | `explico/components/memo/ShortNote.astro` | An inline, click-to-expand aside that replaces its own trigger text in place — "the smaller, genuinely inline interaction." No number, no cross-page reference. | [structure.md](structure.md#detailed-memos-and-inline-short-notes) |
+| `<Memo id="…" title="…" description="…">` | `explico/components/memo/Memo.astro` | A collapsible, independently-numbered card for optional depth (derivation, proof, edge case) that would otherwise bloat the main argument. Cited with `[[memo-id]]`. | [structure.md](structure.md#detailed-memos-and-inline-short-notes) |
+
+Both differ from a bare `title` tooltip in the same way: they hold real,
+possibly multi-paragraph Markdown content (including equations, tables,
+figures), are addressable (`id`, a permalink), and are meant to be found
+again — a `title` tooltip is disposable and invisible outside a hover/focus
+event.
+
+## Numbered floats
+
+Each of these gets a `‹part›.‹n›` number (its own counter, independent of the
+others — see [structure.md § Numbering](structure.md#numbering)), a stable
+`#anchor`, and same-page/cross-page reference syntax `[[prefix-id]]` /
+`[[lesson/slug#prefix-id]]`.
+
+| Component | Import | Prefix | Doc |
+| --- | --- | --- | --- |
+| `<Table id="…" caption="…">` | `explico/components/table/Table.astro` | `tab-` | [structure.md](structure.md#numbering), [V rules](visualizations.md) |
+| `<Figure id="…" title="…" caption="…" previewable>` | `explico/components/figure/Figure.astro` | `fig-` | [structure.md](structure.md#numbering), [V2](visualizations.md#v2)/[V3](visualizations.md#v3) |
+| `<Diagram id="…" label="…" nodes={…} edges={…}>` | `explico/components/diagram/Diagram.astro` | `dia-` | [V1](visualizations.md#v1) |
+| A display equation with `\label{eq:key}` | `remark-math` (built in) | `eq-` | [N5](notation.md#n5), [structure.md](structure.md#numbering) |
+
+Two naming traps worth flagging for an AI author:
+
+- **`<Figure title="…">` is a visible short label in the collapsible title
+  bar, not the HTML `title` attribute's hover tooltip.** It always renders on
+  the page; it is a different feature from the [native tooltip](#inline-zero-registration)
+  above even though it reuses the same prop name.
+- **A raw Markdown pipe table or a raw `<table>`, or a `<Diagram>` with no
+  `id`,** renders fine but never enters keyed-float validation — no number,
+  no `[[…]]` target. Wrap it (`<Table>`/`<Figure>`) or give the diagram an
+  `id` if it needs to be referenced. See [structure.md § Raw and unwrapped
+  floats](structure.md#raw-and-unwrapped-floats).
+
+## Reference systems
+
+These bind a term to a definition that a reader can hover *and* look up
+elsewhere — the machinery a bare `title` tooltip deliberately skips.
+
+| Syntax | Registers where | Gives | Doc |
+| --- | --- | --- | --- |
+| `[[key]]` in prose, before first math use | `content/notation/*.md` entry | One-meaning-per-glyph hover card everywhere `$key$`-bound math appears on the page | [N4](notation.md#n4) |
+| `\explain{key}{latex}` inside `$…$` | Same notation entry | Escape hatch for a compound/colliding symbol only, not the default bind | [N4](notation.md#n4) |
+| A bare all-caps/dotted term (`OLS`, `w.r.t.`) in prose | `content/abbreviations/*.md`, or `course.config.ts` `abbreviations.allow` | Hover/click card on first occurrence, linked to the glossary page | [N14](notation.md#n14) |
+| `[@source-id]` or `[@source-id; §1.2]` | `content/sources/*.json` | Numbered `[n]` superscript linking to a References section, with a hover/pin panel | `src/reference/remark-citation.mjs` |
+
+## Knowledge checks and worked examples
+
+| Component | Import | Notes | Doc |
+| --- | --- | --- | --- |
+| `<AssessmentSet />` | `explico/components/assessments/AssessmentSet.astro` | Renders every check listed in the lesson's colocated `.checks.yml`; do not add a separate heading for it | [structure.md § Knowledge checks](structure.md#knowledge-checks) |
+| `<CompactExample>` / `<CompactExamples>` | `explico/components/examples/CompactExample.astro` | Worked-example cards; a `<Diagram>` nested inside one is invisible to diagram numbering (see the raw/unwrapped note above) | [structure.md](structure.md#raw-and-unwrapped-floats) |
+
+## Choosing between the "explain a term" options
+
+From lightest to heaviest — pick the first one that's actually enough:
+
+1. **Native `title="…"` tooltip** — disposable, hover-only, nothing to
+   register. Use when the aside doesn't need to be found again.
+2. **`<ShortNote>`** — inline, click-to-expand, can hold Markdown, no number.
+   Use when the aside is worth more than a one-line hover but still belongs
+   inline, not as its own citable unit.
+3. **Abbreviation entry / notation `[[key]]`** — page-wide hover card, build
+   gated (N14/N4), listed in the glossary. Use when the term recurs, is
+   acronym-shaped, or is genuine math notation.
+4. **`<Memo>`** — numbered, permalinked, holds real sub-content (proofs,
+   figures, tables). Use when the aside is long enough to be its own small
+   section.

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,77 @@ 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`