explico 0.1.1 → 0.3.0

package/dist/reference/remark-notation.d.mts

@@ -5,7 +5,16 @@
  *   unknown?: 'error' | 'warn' | 'ignore',
  *   base?: string,
  *   equations?: Record<string, Record<string, string>>,
+ *   tables?: Record<string, Record<string, string>>,
+ *   figures?: Record<string, Record<string, string>>,
+ *   chapters?: Record<string, number>,
  * }} [options]
+ *
+ * `chapters` maps a lesson slug to its 1-based course ordinal. When the
+ * current page has one, every display equation / `<Table>` / `<Figure>` is
+ * numbered `‹chapter›.‹n›` (`##` headings ignored); with no entry the legacy
+ * `##`-section scheme applies. It must agree with `manifest.lessons[].chapter`,
+ * which is what feeds `equations`/`tables`/`figures` above.
  */
 export default function remarkNotation(options?: {
     definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>);
@@ -13,6 +22,9 @@ export default function remarkNotation(options?: {
     unknown?: "error" | "warn" | "ignore";
     base?: string;
     equations?: Record<string, Record<string, string>>;
+    tables?: Record<string, Record<string, string>>;
+    figures?: Record<string, Record<string, string>>;
+    chapters?: Record<string, number>;
 }): (tree: any, file: any) => void;
 /**
  * Remark adapter for semantic notation references.

package/dist/reference/remark-notation.mjs

@@ -36,10 +36,17 @@ export const NOTATION_KEY_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
 import { GlyphResolutionError, resolveMathGlyphs } from './math-glyphs.mjs';
 import {
   EQ_LABEL_PATTERN,
+  collectDisplayEquations,
   collectEquationLabels,
+  equationAnchorId,
   parseEquationRef,
   stripEquationLabels,
 } from './equations.mjs';
+import {
+  collectKeyedJsxFloats,
+  keyedFloatAnchorId,
+  parseKeyedFloatRef,
+} from './keyed-jsx-floats.mjs';
 
 const PROSE_SKIP_TYPES = new Set([
   'code',
@@ -307,34 +314,39 @@ function defaultHref(definition, key, base = '') {
 }
 
 /**
- * Wrap a keyed `$$…$$` `math` node so the container survives `rehype-katex`
- * (which splices the inner `math-display` element out). The visible number is
- * a focusable `<a>` sibling — never authored, never inside KaTeX — so it
- * survives print and screen readers name it "Equation 2.4".
+ * Wrap a display `$$…$$` `math` node so the container survives `rehype-katex`
+ * (which splices the inner `math-display` element out). Every display equation
+ * in a lesson is numbered; a keyed one anchors at `#eq-<key>`, an unkeyed one
+ * at its positional `#eq-<section>-<index>`. The visible number is a focusable
+ * `<a>` sibling — never authored, never inside KaTeX — so it survives print and
+ * screen readers name it "Equation 2.4".
  */
-function keyedEquationNode(mathNode, key, number) {
+function equationNode(mathNode, { key, number }) {
+  const id = equationAnchorId({ key, number });
+  const hProperties = {
+    id,
+    className: ['keyed-equation'],
+    'data-eq-number': number,
+  };
+  if (key) hProperties['data-eq-key'] = key;
+  else hProperties['data-eq-auto'] = '';
+
   return {
     type: 'paragraph',
-    data: {
-      hName: 'div',
-      hProperties: {
-        id: `eq-${key}`,
-        className: ['keyed-equation'],
-        'data-eq-key': key,
-        'data-eq-number': number,
-      },
-    },
+    data: { hName: 'div', hProperties },
     children: [
       mathNode,
       {
         type: 'link',
-        url: `#eq-${key}`,
+        url: `#${id}`,
         children: [{ type: 'text', value: `(${number})` }],
         data: {
           hProperties: {
             className: ['keyed-equation__number'],
             'data-eq-number': number,
             'aria-label': `Equation ${number}`,
+            // Plain hover tooltip — the number is a permalink to this equation.
+            title: 'Anchor to this equation',
           },
         },
       },
@@ -342,6 +354,32 @@ function keyedEquationNode(mathNode, key, number) {
   };
 }
 
+/**
+ * Give a `<Table>`/`<Figure>` `mdxJsxFlowElement` its computed `number` and
+ * `anchorId` as real JSX attributes, so the actual Astro component (which
+ * renders the numbered anchor, unlike `equationNode`'s synthesized hast div)
+ * receives them as props. The compiler is the single source of truth for
+ * both — the component only renders what it's given.
+ */
+function injectFloatNumberAttributes(node, float, prefix) {
+  const anchorId = keyedFloatAnchorId({
+    key: float.key,
+    number: float.number,
+    prefix,
+  });
+  node.attributes = (node.attributes ?? []).filter(
+    (attribute) =>
+      !(
+        attribute?.type === 'mdxJsxAttribute' &&
+        (attribute.name === 'number' || attribute.name === 'anchorId')
+      ),
+  );
+  node.attributes.push(
+    { type: 'mdxJsxAttribute', name: 'number', value: float.number },
+    { type: 'mdxJsxAttribute', name: 'anchorId', value: anchorId },
+  );
+}
+
 /** Resolve a `[[eq-key]]` / `[[slug#eq-key]]` reference to `{ number, href }`. */
 function resolveEquationRef(eqRef, eqCtx, file, node) {
   if (eqRef.lesson) {
@@ -369,7 +407,47 @@ function resolveEquationRef(eqRef, eqCtx, file, node) {
   return { number, href: `#eq-${eqRef.key}` };
 }
 
-function proseNodes(value, resolve, file, node, references, eqCtx) {
+/**
+ * Resolve a `[[<prefix>-key]]` / `[[slug#<prefix>-key]]` reference (a
+ * `<Table>`/`<Figure>` float) to `{ number, href }` — the table/figure
+ * equivalent of `resolveEquationRef`.
+ */
+function resolveKeyedFloatRef(floatRef, ctx, { prefix, tagName }, file, node) {
+  if (floatRef.lesson) {
+    const number = ctx.crossPage?.[floatRef.lesson]?.[floatRef.key];
+    if (number === undefined) {
+      fail(
+        file,
+        `Unknown ${tagName} reference [[${floatRef.lesson}#${prefix}-${floatRef.key}]]: lesson ${floatRef.lesson} has no <${tagName}> with id="${floatRef.key}".`,
+        node,
+      );
+    }
+    return {
+      number,
+      href: `${ctx.base.replace(/\/$/, '')}/${floatRef.lesson}/#${prefix}-${floatRef.key}`,
+    };
+  }
+  const number = ctx.pageLabels.get(floatRef.key);
+  if (number === undefined) {
+    fail(
+      file,
+      `Unknown ${tagName} reference [[${prefix}-${floatRef.key}]]: no <${tagName}> on this page carries id="${floatRef.key}".`,
+      node,
+    );
+  }
+  return { number, href: `#${prefix}-${floatRef.key}` };
+}
+
+function proseNodes(
+  value,
+  resolve,
+  file,
+  node,
+  references,
+  eqCtx,
+  tableCtx,
+  figureCtx,
+) {
   const base = eqCtx?.base ?? '';
   const strayExplain = firstUnescaped(value, EXPLAIN);
   if (strayExplain !== -1) {
@@ -390,7 +468,18 @@ function proseNodes(value, resolve, file, node, references, eqCtx) {
 
     const key = match[1].trim();
     const eqRef = eqCtx ? parseEquationRef(key) : undefined;
-    if (!eqRef && !NOTATION_KEY_PATTERN.test(key)) {
+    const tableRef =
+      !eqRef && tableCtx ? parseKeyedFloatRef(key, { prefix: 'tab' }) : undefined;
+    const figureRef =
+      !eqRef && !tableRef && figureCtx
+        ? parseKeyedFloatRef(key, { prefix: 'fig' })
+        : undefined;
+    if (
+      !eqRef &&
+      !tableRef &&
+      !figureRef &&
+      !NOTATION_KEY_PATTERN.test(key)
+    ) {
       fail(file, `Invalid notation key "${key}" in [[...]].`, node);
     }
 
@@ -421,9 +510,46 @@ function proseNodes(value, resolve, file, node, references, eqCtx) {
       continue;
     }
 
+    const floatRef = tableRef ?? figureRef;
+    if (floatRef) {
+      const kind = tableRef ? 'table' : 'figure';
+      const prefix = tableRef ? 'tab' : 'fig';
+      const tagName = tableRef ? 'Table' : 'Figure';
+      const { number, href } = resolveKeyedFloatRef(
+        floatRef,
+        tableRef ? tableCtx : figureCtx,
+        { prefix, tagName },
+        file,
+        node,
+      );
+      output.push({
+        type: 'link',
+        url: href,
+        children: [{ type: 'text', value: `${tagName} ${number}` }],
+        data: {
+          hProperties: {
+            className: [`${kind}-ref`],
+            [`data-${prefix}-ref`]: floatRef.key,
+            ...(floatRef.lesson ? { [`data-${prefix}-lesson`]: floatRef.lesson } : {}),
+          },
+        },
+      });
+      references.push({
+        key: floatRef.key,
+        kind,
+        ...(floatRef.lesson ? { lesson: floatRef.lesson } : {}),
+      });
+      cursor = match.index + match[0].length;
+      continue;
+    }
+
     const definition = resolve(key, 'prose', node);
-    const title = definition?.title ?? key;
-    const summary = definition?.summary;
+    // `title`/`summary` are the pre-C1b field names, kept as the first
+    // fallback for a caller still supplying them; real content authors
+    // `label`/`meaning` (see `content-config.ts`), which raw frontmatter
+    // (`manifest.notation.raw`, a page's own `notation.local`) carries as-is.
+    const title = definition?.title ?? definition?.label ?? key;
+    const summary = definition?.summary ?? definition?.meaning;
     const href = defaultHref(definition, key, base);
 
     const properties = {
@@ -552,7 +678,16 @@ function inspectExplainCalls(value, resolve, file, node, references) {
  *   unknown?: 'error' | 'warn' | 'ignore',
  *   base?: string,
  *   equations?: Record<string, Record<string, string>>,
+ *   tables?: Record<string, Record<string, string>>,
+ *   figures?: Record<string, Record<string, string>>,
+ *   chapters?: Record<string, number>,
  * }} [options]
+ *
+ * `chapters` maps a lesson slug to its 1-based course ordinal. When the
+ * current page has one, every display equation / `<Table>` / `<Figure>` is
+ * numbered `‹chapter›.‹n›` (`##` headings ignored); with no entry the legacy
+ * `##`-section scheme applies. It must agree with `manifest.lessons[].chapter`,
+ * which is what feeds `equations`/`tables`/`figures` above.
  */
 export default function remarkNotation(options = {}) {
   const unknown = options.unknown ?? 'error';
@@ -568,6 +703,10 @@ export default function remarkNotation(options = {}) {
     );
     const localDefinitions = localDefinitionsFromFile(file);
     const lessonId = lessonIdFrom(file);
+    // The lesson's course ordinal (see the `chapters` option). Falsy / missing
+    // ⇒ the legacy `##`-section numbering, so `0` and `undefined` behave alike.
+    const chapter =
+      (lessonId && options.chapters?.[lessonId.replace(/\./g, '/')]) || undefined;
     const registryFile = isNotationRegistryFile(file);
     const mathScope = pageGlyphScope(
       localDefinitions,
@@ -577,10 +716,10 @@ export default function remarkNotation(options = {}) {
     const references = [];
     const resolved = new Map();
 
-    // Equation identity (D7): assign every `\label{eq:…}` its section-scoped
-    // number before any math node is rewritten, so a `[[eq-key]]` earlier in
-    // the page still resolves.
-    const equationLabels = collectEquationLabels(tree);
+    // Equation identity (D7): assign every `\label{eq:…}` its number before any
+    // math node is rewritten, so a `[[eq-key]]` earlier in the page still
+    // resolves. `chapter` picks the `‹chapter›.‹n›` vs `##`-section scheme.
+    const equationLabels = collectEquationLabels(tree, chapter);
     const pageLabels = new Map();
     for (const label of equationLabels) {
       if (pageLabels.has(label.key)) {
@@ -598,6 +737,53 @@ export default function remarkNotation(options = {}) {
       crossPage: options.equations ?? {},
     };
 
+    // Number and anchor every display equation on a lesson page, keyed or
+    // not (F3). Non-lesson pages (notation registry, stray docs) keep the
+    // keyed-only behaviour so their body math is left untouched.
+    const displayEquations = lessonId
+      ? collectDisplayEquations(tree, chapter)
+      : [];
+    const equationByNode = new Map(
+      displayEquations.map((equation) => [equation.node, equation]),
+    );
+
+    // Keyed floats (F-tables-figures): every `<Table>`/`<Figure>` on a lesson
+    // page is numbered and anchored, keyed or not — same rule as equations,
+    // via the shared engine in `keyed-jsx-floats.mjs`.
+    const makeFloatCtx = (tagName, crossPage) => {
+      const floats = lessonId
+        ? collectKeyedJsxFloats(tree, { tagName, chapter })
+        : [];
+      const pageFloatLabels = new Map();
+      for (const float of floats) {
+        if (float.key == null) continue;
+        if (pageFloatLabels.has(float.key)) {
+          fail(
+            file,
+            `Duplicate <${tagName} id="${float.key}"> on this page; an id is unique per lesson.`,
+            float.node,
+          );
+        }
+        pageFloatLabels.set(float.key, float.number);
+      }
+      return {
+        ctx: {
+          base: options.base ?? '',
+          pageLabels: pageFloatLabels,
+          crossPage: crossPage ?? {},
+        },
+        byNode: new Map(floats.map((float) => [float.node, float])),
+      };
+    };
+    const { ctx: tableCtx, byNode: tableByNode } = makeFloatCtx(
+      'Table',
+      options.tables,
+    );
+    const { ctx: figureCtx, byNode: figureByNode } = makeFloatCtx(
+      'Figure',
+      options.figures,
+    );
+
     const resolve = (key, kind, node) => {
       const context = {
         file,
@@ -647,7 +833,6 @@ export default function remarkNotation(options = {}) {
               node,
             );
           }
-          node.__eqKey = labelMatch[1];
           value = stripEquationLabels(value);
           replaceMathSource(node, value);
         }
@@ -717,6 +902,8 @@ export default function remarkNotation(options = {}) {
             child,
             references,
             eqCtx,
+            tableCtx,
+            figureCtx,
           );
           if (replacement) {
             node.children.splice(index, 1, ...replacement);
@@ -725,14 +912,12 @@ export default function remarkNotation(options = {}) {
           continue;
         }
         visit(child, false);
-        if (child && child.__eqKey) {
-          const key = child.__eqKey;
-          delete child.__eqKey;
-          node.children[index] = keyedEquationNode(
-            child,
-            key,
-            pageLabels.get(key),
-          );
+        if (child && child.type === 'math' && equationByNode.has(child)) {
+          node.children[index] = equationNode(child, equationByNode.get(child));
+        } else if (child?.type === 'mdxJsxFlowElement' && tableByNode.has(child)) {
+          injectFloatNumberAttributes(child, tableByNode.get(child), 'tab');
+        } else if (child?.type === 'mdxJsxFlowElement' && figureByNode.has(child)) {
+          injectFloatNumberAttributes(child, figureByNode.get(child), 'fig');
         }
       }
     };
@@ -749,5 +934,16 @@ export default function remarkNotation(options = {}) {
         indexInSection,
       }),
     );
+    const floatLabelData = (byNode) =>
+      [...byNode.values()]
+        .filter((float) => float.key != null)
+        .map(({ key, number, section, indexInSection }) => ({
+          key,
+          number,
+          section,
+          indexInSection,
+        }));
+    file.data.tableLabels = floatLabelData(tableByNode);
+    file.data.figureLabels = floatLabelData(figureByNode);
   };
 }

package/dist/reference/tables-validate.d.ts

@@ -0,0 +1,21 @@
+import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } from './keyed-float-validate.js';
+
+/** `validateKeyedFloats` for `<Table>` — see `keyed-float-validate.ts`. */
+
+type TableDiagnosticCode = 'tab-invalid-key' | 'tab-duplicate-key' | 'tab-ref-resolves' | 'tab-key-unused';
+interface TableDiagnostic {
+    readonly code: TableDiagnosticCode;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+    readonly key?: string;
+}
+type TableLabelRecord = KeyedFloatLabelRecord;
+type TableLessonInput = KeyedFloatLessonInput;
+interface TableValidation extends KeyedFloatValidation {
+    readonly diagnostics: readonly TableDiagnostic[];
+}
+declare function validateTables(lessons: readonly TableLessonInput[]): TableValidation;
+
+export { type TableDiagnostic, type TableDiagnosticCode, type TableLabelRecord, type TableLessonInput, type TableValidation, validateTables };

package/dist/reference/tables-validate.js

@@ -0,0 +1,13 @@
+import {
+  validateKeyedFloats
+} from "./keyed-float-validate.js";
+function validateTables(lessons) {
+  return validateKeyedFloats(lessons, {
+    tagName: "Table",
+    prefix: "tab",
+    noun: "table"
+  });
+}
+export {
+  validateTables
+};

package/dist/reference/types.d.ts

@@ -15,6 +15,19 @@ type NotationAlignment = {
     readonly rationale: string;
 };
 type NotationReferenceKind = 'prose' | 'math' | 'definition';
+/**
+ * A gloss resolved by the loader (D15). Declared on a card, keyed
+ * `<card key>.<slug(name)>`, and deliberately absent from the registry: a
+ * gloss is never a definition record, never a reference target, and never a
+ * curriculum node. See `reference/gloss.ts`.
+ */
+interface NotationGlossEntry {
+    readonly key: string;
+    readonly notation: string;
+    readonly label: string;
+    readonly units?: string;
+    readonly ownerKey: string;
+}
 interface NotationReferenceInput {
     readonly key: string;
     readonly kind: NotationReferenceKind;
@@ -37,6 +50,8 @@ interface SharedNotationDefinitionInput {
     readonly body: string;
     /** References harvested from the Markdown body. */
     readonly references: readonly NotationReferenceInput[];
+    /** Symbols this entry's `formula` names but does not make cards of. */
+    readonly glosses: readonly NotationGlossEntry[];
     readonly source: SourceSpan;
 }
 interface LocalNotationDefinitionInput {
@@ -51,6 +66,8 @@ interface LocalNotationDefinitionInput {
     readonly alignment: NotationAlignment;
     /** References harvested from summary content. */
     readonly references: readonly NotationReferenceInput[];
+    /** Symbols this entry's `formula` names but does not make cards of. */
+    readonly glosses: readonly NotationGlossEntry[];
     readonly source: SourceSpan;
 }
 interface NotationLessonInput {
@@ -67,7 +84,7 @@ interface NotationRegistryInput {
     readonly sharedDefinitions: readonly SharedNotationDefinitionInput[];
     readonly lessons: readonly NotationLessonInput[];
 }
-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';
+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 {
     readonly code: NotationDiagnosticCode;
@@ -95,6 +112,12 @@ interface ResolvedNotationReference {
 interface NotationDefinitionRecordBase {
     readonly id: string;
     readonly key: string;
+    /**
+     * Symbols this entry's `formula` names but does not make cards of (D15).
+     * Carried on the record so the manifest can build the entry-scoped formula
+     * table; deliberately **not** a definition, a reference target, or an edge.
+     */
+    readonly glosses: readonly NotationGlossEntry[];
     readonly scope: NotationDefinitionScope;
     readonly notation: string;
     readonly label: string;
@@ -148,4 +171,4 @@ interface NotationRegistry {
     readonly diagnostics: readonly NotationDiagnostic[];
 }
 
-export type { DiagnosticSeverity, EditorialStatus, LocalNotationDefinitionInput, LocalNotationDefinitionRecord, NotationAlignment, NotationBacklink, NotationBinding, NotationDefinitionRecord, NotationDefinitionScope, NotationDiagnostic, NotationDiagnosticCode, NotationLessonInput, NotationPageBundle, NotationReferenceInput, NotationReferenceKind, NotationRegistry, NotationRegistryInput, ResolvedNotationReference, SharedNotationDefinitionInput, SharedNotationDefinitionRecord, SourceSpan };
+export type { 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

@@ -97,7 +97,25 @@ const UNITS_VOCAB = /* @__PURE__ */ new Set([
   "quantity",
   "quoted",
   "explicitly",
-  "calculations"
+  "calculations",
+  // motion / physical quantities (playground corpus)
+  "meter",
+  "meters",
+  "second",
+  "seconds",
+  "speed",
+  "velocity",
+  "acceleration",
+  "gravitational",
+  "launch",
+  "angle",
+  "degrees",
+  "horizontal",
+  "vertical",
+  "level",
+  "ground",
+  "squared",
+  "above"
 ]);
 function unitsTokens(units) {
   return units.toLowerCase().split(/[\s]+/).flatMap((word) => word.split(/(?<=[a-z0-9])-(?=[a-z])/)).map((word) => word.replace(/^[^a-z0-9_]+|[^a-z0-9_]+$/g, "")).filter((word) => word.length > 0 && !/^\d+$/.test(word));

package/docs/VERSIONING.md

@@ -0,0 +1,66 @@
+# Versioning
+
+`explico` follows [Semantic Versioning](https://semver.org/). The installed
+`package.json` `version` is authoritative for what a consumer has;
+[`CHANGELOG.md`](../CHANGELOG.md) records what changed; this file defines what a
+bump *means*.
+
+There are two independent version streams. This document is about the **engine**.
+A course built on explico carries its own **knowledge version** over its
+content — see [`authoring/versioning.md`](authoring/versioning.md).
+
+## The public surface
+
+A change is "breaking" when it can break a consumer who followed the docs. The
+consumer-visible surface is:
+
+| Surface | Where |
+| --- | --- |
+| Published module entry points | `package.json` `publishConfig.exports` — the `explico/*` specifiers and their `.d.ts` |
+| Astro / React components | names + props of everything under `components/` that the README wires |
+| remark / rehype adapter options | the option objects of `reference/*.mjs` (`remarkNotation`, `remarkCitation`, `createNotationKatexOptions`, …) |
+| The compiler manifest | `MANIFEST_SCHEMA_VERSION` and the shape of `Manifest` |
+| The `content` CLI | the commands, their flags, and every diagnostic `code` string |
+| `CourseConfig` | the interface in `compiler/course-config.ts` |
+| Build-enforced authoring rules | the `N*` / `V*` / `C*` rules marked *Build-enforced* in `docs/authoring/` |
+
+## What each bump means
+
+**MAJOR** — an incompatible change to any surface above: removing or renaming an
+export, a component, a prop, or a CLI command; adding a required `CourseConfig`
+field; a breaking change to the manifest shape (which also bumps
+`MANIFEST_SCHEMA_VERSION`); tightening a build-enforced rule so content that
+passed now fails.
+
+**MINOR** — a backward-compatible addition: a new export, component, or optional
+`CourseConfig` field; a new opt-in authoring rule; a new manifest field
+(additive — still bump `MANIFEST_SCHEMA_VERSION`, note it additive in
+`CHANGELOG.md`).
+
+**PATCH** — a bug fix, a docs change, an internal refactor with no surface
+change, or a new **Tier-3 warning** (warnings never fail a build, so surfacing
+one does not break a consumer).
+
+### Pre-1.0
+
+While the version is `0.x`, a **MINOR** bump *may* include a breaking change —
+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.
+
+## 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
+   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`.
+
+## When you change the engine
+
+Every PR that touches the public surface adds a bullet under `## [Unreleased]`
+in `CHANGELOG.md`, in the right group (`Added` / `Changed` / `Fixed` /
+`Removed`, plus `Breaking` when it is). Pick the group by the rules above; the
+version number itself is set only at release time. See [`AGENTS.md`](../AGENTS.md).