explico 0.3.0 → 0.5.0

package/dist/reference/base-abbreviations.mjs

@@ -0,0 +1,60 @@
+/**
+ * The base abbreviation baseline: acronyms and dotted abbreviations every
+ * reader is assumed to know, so a lesson never has to introduce them with an
+ * abbreviations-table entry. The `\operatorname{…}` / `\mathrm{…}` twins are
+ * `base-operators.mjs` (rule N8) / `base-roman-labels.mjs` (rule N10); this is
+ * the plain-prose equivalent for rule N14.
+ *
+ * Kept intentionally small, same rationale as `BASE_ROMAN_LABELS`: a
+ * course-specific acronym (`OLS`, `SSR`, `MSE`) is exactly the thing a reader
+ * benefits from having spelled out, so it belongs in the course's own
+ * `content/abbreviations/*.md` table, not here. This baseline only holds
+ * abbreviations so common in ordinary English/academic writing that spelling
+ * them out on every course would be noise, not help. A course adds a real
+ * one via `abbreviations.allow` in `course.config.ts`, the same shape as
+ * `operators.allow` / `romanLabels.allow`.
+ */
+export const BASE_ABBREVIATIONS = Object.freeze(
+  new Set([
+    // dotted Latin/English abbreviations
+    'e.g.',
+    'i.e.',
+    'etc.',
+    'cf.',
+    'vs.',
+    'a.m.',
+    'p.m.',
+    'a.k.a.',
+    'et al.',
+    // generic acronyms with no domain-specific meaning in this engine
+    'AI',
+    'ID',
+    'OK',
+    'URL',
+    'FAQ',
+    'US',
+    'UK',
+    'EU',
+  ]),
+);
+
+/**
+ * The abbreviations a course treats as common, given its `course.config.ts`
+ * `abbreviations` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} abbreviations
+ * @returns {Set<string>}
+ */
+export function effectiveAbbreviationAllowlist(abbreviations) {
+  const allow = abbreviations?.allow ?? [];
+  const deny = new Set(abbreviations?.deny ?? []);
+  const effective = new Set(BASE_ABBREVIATIONS);
+  for (const name of allow) effective.add(name);
+  for (const name of deny) effective.delete(name);
+  return effective;
+}
+
+/** True when `token` needs no abbreviations-table entry for this course. */
+export function isBaseAbbreviation(token, abbreviations) {
+  return effectiveAbbreviationAllowlist(abbreviations).has(token);
+}

package/dist/reference/base-operators.d.mts

@@ -36,3 +36,18 @@ export function isBaseOperator(name: any, operators: any): boolean;
  * Matching is case-sensitive.
  */
 export const BASE_OPERATORS: Readonly<Set<string>>;
+/**
+ * The subset of {@link BASE_OPERATORS} that must never appear with a bare
+ * (unparenthesized) argument: every trigonometric, inverse-trigonometric, and
+ * hyperbolic function, plus the exponential and logarithms (N13). `\sin x`
+ * leaves how far the argument extends ambiguous the moment anything follows
+ * it (`\sin x + 1` — is the `+1` inside or outside the sine?); `\sin(x)`
+ * never does, even for a single-symbol argument. Kept separate from
+ * `BASE_OPERATORS`: this is a formatting rule layered on top of the "does it
+ * need a notation card" question that set answers, so an operator can be
+ * universal (N8) and still owe a parenthesized argument. Enforced by
+ * `resolveMathGlyphs` in `math-glyphs.mjs`, which every rendered-math context
+ * (lesson body, notation `formula`, assessments, `Diagram` nodes, lab math)
+ * already calls.
+ */
+export const PARENTHESIZED_FUNCTIONS: Readonly<Set<string>>;

package/dist/reference/base-operators.mjs

@@ -81,6 +81,46 @@ export const BASE_OPERATORS = Object.freeze(
   ]),
 );
 
+/**
+ * The subset of {@link BASE_OPERATORS} that must never appear with a bare
+ * (unparenthesized) argument: every trigonometric, inverse-trigonometric, and
+ * hyperbolic function, plus the exponential and logarithms (N13). `\sin x`
+ * leaves how far the argument extends ambiguous the moment anything follows
+ * it (`\sin x + 1` — is the `+1` inside or outside the sine?); `\sin(x)`
+ * never does, even for a single-symbol argument. Kept separate from
+ * `BASE_OPERATORS`: this is a formatting rule layered on top of the "does it
+ * need a notation card" question that set answers, so an operator can be
+ * universal (N8) and still owe a parenthesized argument. Enforced by
+ * `resolveMathGlyphs` in `math-glyphs.mjs`, which every rendered-math context
+ * (lesson body, notation `formula`, assessments, `Diagram` nodes, lab math)
+ * already calls.
+ */
+export const PARENTHESIZED_FUNCTIONS = Object.freeze(
+  new Set([
+    // exponential / logarithms
+    'exp',
+    'log',
+    'ln',
+    'lg',
+    // trigonometric
+    'sin',
+    'cos',
+    'tan',
+    'cot',
+    'sec',
+    'csc',
+    // inverse trigonometric
+    'arcsin',
+    'arccos',
+    'arctan',
+    // hyperbolic
+    'sinh',
+    'cosh',
+    'tanh',
+    'coth',
+  ]),
+);
+
 /**
  * The operators a course treats as common, given its `course.config.ts`
  * `operators` block: the shipped baseline, plus `allow`, minus `deny`.

package/dist/reference/base-roman-labels.d.mts

@@ -0,0 +1,35 @@
+/**
+ * The roman labels a course treats as common, given its `course.config.ts`
+ * `romanLabels` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} romanLabels
+ * @returns {Set<string>}
+ */
+export function effectiveRomanLabelAllowlist(romanLabels: {
+    allow?: readonly string[];
+    deny?: readonly string[];
+} | undefined): Set<string>;
+/** True when `name` needs no notation entry for this course. */
+export function isBaseRomanLabel(name: any, romanLabels: any): boolean;
+/**
+ * The base roman-label baseline: `\mathrm{…}` multi-letter labels every
+ * reader is assumed to know, so a lesson never has to introduce them with a
+ * notation entry. The `\operatorname{…}` counterpart is `base-operators.mjs`
+ * (rule N8); this is its `\mathrm{…}` twin (rule N10).
+ *
+ * Rationale: the completeness gate has no opinion about `\mathrm{…}` bodies —
+ * they are a typographic label to KaTeX, not a bindable symbol, and N3
+ * requires the format without asking whether the label is ever explained.
+ * The `roman-label-explained` consistency check fills that gap: a label a
+ * lesson uses is either on this list (or the course's additions to it) or it
+ * carries a notation entry the reader can hover.
+ *
+ * Kept intentionally small — unlike `sin`/`exp`, an upright label is almost
+ * always a course-specific named quantity (`KE`, `PV`, `Var`-as-a-label) that
+ * genuinely benefits from a hover card, so the shipped baseline holds only
+ * the qualifiers that function like an operator's extremum subscript
+ * (`x_{\mathrm{opt}}`) rather than naming a quantity of their own. A course
+ * adds a real one via `romanLabels.allow` in `course.config.ts`, the same
+ * shape as `operators.allow`.
+ */
+export const BASE_ROMAN_LABELS: Readonly<Set<string>>;

package/dist/reference/base-roman-labels.mjs

@@ -0,0 +1,43 @@
+/**
+ * The base roman-label baseline: `\mathrm{…}` multi-letter labels every
+ * reader is assumed to know, so a lesson never has to introduce them with a
+ * notation entry. The `\operatorname{…}` counterpart is `base-operators.mjs`
+ * (rule N8); this is its `\mathrm{…}` twin (rule N10).
+ *
+ * Rationale: the completeness gate has no opinion about `\mathrm{…}` bodies —
+ * they are a typographic label to KaTeX, not a bindable symbol, and N3
+ * requires the format without asking whether the label is ever explained.
+ * The `roman-label-explained` consistency check fills that gap: a label a
+ * lesson uses is either on this list (or the course's additions to it) or it
+ * carries a notation entry the reader can hover.
+ *
+ * Kept intentionally small — unlike `sin`/`exp`, an upright label is almost
+ * always a course-specific named quantity (`KE`, `PV`, `Var`-as-a-label) that
+ * genuinely benefits from a hover card, so the shipped baseline holds only
+ * the qualifiers that function like an operator's extremum subscript
+ * (`x_{\mathrm{opt}}`) rather than naming a quantity of their own. A course
+ * adds a real one via `romanLabels.allow` in `course.config.ts`, the same
+ * shape as `operators.allow`.
+ */
+export const BASE_ROMAN_LABELS = Object.freeze(new Set(['opt']));
+
+/**
+ * The roman labels a course treats as common, given its `course.config.ts`
+ * `romanLabels` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} romanLabels
+ * @returns {Set<string>}
+ */
+export function effectiveRomanLabelAllowlist(romanLabels) {
+  const allow = romanLabels?.allow ?? [];
+  const deny = new Set(romanLabels?.deny ?? []);
+  const effective = new Set(BASE_ROMAN_LABELS);
+  for (const name of allow) effective.add(name);
+  for (const name of deny) effective.delete(name);
+  return effective;
+}
+
+/** True when `name` needs no notation entry for this course. */
+export function isBaseRomanLabel(name, romanLabels) {
+  return effectiveRomanLabelAllowlist(romanLabels).has(name);
+}

package/dist/reference/consistency.d.ts

@@ -1,4 +1,4 @@
-import { CourseConventions, CourseOperators } from '../compiler/course-config.js';
+import { CourseConventions, CourseOperators, CourseRomanLabels } from '../compiler/course-config.js';
 import { CurriculumCatalog } from '../curriculum/validation.js';
 import { NotationSpec } from '../compiler/collections.js';
 import { LintIgnore } from './lint-ignore.js';
@@ -28,12 +28,16 @@ import { NotationRegistry, NotationRegistryInput } from './types.js';
  *   (h) operator-explained           a named operator a lesson uses is on the
  *                                     shipped/course operator allowlist or
  *                                     carries a notation entry (rule N8)
+ *   (i) roman-label-explained        a `\mathrm{…}` multi-letter label a lesson
+ *                                     uses is on the shipped/course roman-label
+ *                                     allowlist or carries a notation entry
+ *                                     (rule N10)
  *
  * Check (d) — the committed per-lesson resolution report — lives in
  * `src/content/resolution-report.ts`.
  */
 
-type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'numerals-tagged' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape' | 'operator-explained';
+type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'numerals-tagged' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape' | 'operator-explained' | 'roman-label-explained';
 interface ConsistencyDiagnostic {
     readonly code: ConsistencyCode;
     /** Tier 3 — every finding here is a warning until content is brought clean. */
@@ -56,6 +60,8 @@ interface ConsistencyInput {
     readonly conventions: CourseConventions;
     /** This course's edits to the named-operator baseline (rule N8). */
     readonly operators?: CourseOperators;
+    /** This course's edits to the roman-label baseline (rule N10). */
+    readonly romanLabels?: CourseRomanLabels;
 }
 /**
  * Run every consistency check. The result is sorted deterministically (code,

package/dist/reference/consistency.js

@@ -1,5 +1,6 @@
 import { effectiveOperatorAllowlist } from "./base-operators.mjs";
-import { collectOperators } from "./math-glyphs.mjs";
+import { effectiveRomanLabelAllowlist } from "./base-roman-labels.mjs";
+import { collectOperators, collectRomanLabels } from "./math-glyphs.mjs";
 import { offVocabularyTokens } from "./units-vocab.js";
 const CONVENTION_RE = /\bsign convention\b|\bcash-flow perspective\b|\bholder(?:'s)?(?:\s+\w+){0,2}\s+perspective\b|\bfrom (?:a|one|the|its)(?:\s+\w+){0,3}\s+perspective\b|\breverses? every sign\b|\bpositive (?:means|amounts?)\b/i;
 function stripCode(text) {
@@ -332,6 +333,50 @@ function checkOperatorExplained(input, out) {
     }
   }
 }
+function checkRomanLabelExplained(input, out) {
+  const allowlist = effectiveRomanLabelAllowlist(input.romanLabels);
+  const byId = new Map(
+    input.registry.definitions.map((definition) => [definition.id, definition])
+  );
+  const bindingsByLesson = new Map(
+    input.registry.bundles.map((bundle) => [bundle.lessonId, bundle.bindings])
+  );
+  for (const lesson of input.notationInput.lessons) {
+    const explained = /* @__PURE__ */ new Set();
+    const noteEntryLabels = (latex) => {
+      for (const label of collectRomanLabels(latex)) {
+        explained.add(label.name);
+      }
+    };
+    for (const definition of lesson.localDefinitions) {
+      noteEntryLabels(definition.notation);
+    }
+    for (const binding of bindingsByLesson.get(lesson.lessonId) ?? []) {
+      const definition = byId.get(binding.definitionId);
+      if (definition) noteEntryLabels(definition.notation);
+    }
+    const reported = /* @__PURE__ */ new Set();
+    for (const span of mathSpans(lesson.body)) {
+      for (const label of collectRomanLabels(span.latex)) {
+        if (allowlist.has(label.name)) continue;
+        if (explained.has(label.name)) continue;
+        if (reported.has(label.name)) continue;
+        reported.add(label.name);
+        if (input.lintIgnore.matches("roman-label-explained", label.name)) {
+          continue;
+        }
+        out.push({
+          code: "roman-label-explained",
+          severity: "warning",
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          glyph: label.name,
+          message: `${lesson.lessonId}: roman label ${JSON.stringify(`\\mathrm{${label.name}}`)} is neither on the course roman-label allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(`\\mathrm{${label.name}}`)}) introduced with [[key]], or add ${JSON.stringify(label.name)} to romanLabels.allow in course.config.ts`
+        });
+      }
+    }
+  }
+}
 const CHECKS = [
   checkGlyphUniqueness,
   checkNotationUnits,
@@ -342,7 +387,8 @@ const CHECKS = [
   checkGlossWantsPromoting,
   checkCardWantsDemoting,
   checkGlossNameShape,
-  checkOperatorExplained
+  checkOperatorExplained,
+  checkRomanLabelExplained
 ];
 function runConsistencyChecks(input) {
   const diagnostics = [];
@@ -363,7 +409,8 @@ function consistencyCounts(diagnostics) {
     "gloss-wants-promoting": 0,
     "card-wants-demoting": 0,
     "gloss-name-shape": 0,
-    "operator-explained": 0
+    "operator-explained": 0,
+    "roman-label-explained": 0
   };
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

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

@@ -0,0 +1,21 @@
+import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } from './keyed-float-validate.js';
+
+/** `validateKeyedFloats` for `<Diagram>` — see `keyed-float-validate.ts`. */
+
+type DiagramDiagnosticCode = 'dia-invalid-key' | 'dia-duplicate-key' | 'dia-ref-resolves' | 'dia-key-unused';
+interface DiagramDiagnostic {
+    readonly code: DiagramDiagnosticCode;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+    readonly key?: string;
+}
+type DiagramLabelRecord = KeyedFloatLabelRecord;
+type DiagramLessonInput = KeyedFloatLessonInput;
+interface DiagramValidation extends KeyedFloatValidation {
+    readonly diagnostics: readonly DiagramDiagnostic[];
+}
+declare function validateDiagrams(lessons: readonly DiagramLessonInput[]): DiagramValidation;
+
+export { type DiagramDiagnostic, type DiagramDiagnosticCode, type DiagramLabelRecord, type DiagramLessonInput, type DiagramValidation, validateDiagrams };

package/dist/reference/diagrams-validate.js

@@ -0,0 +1,13 @@
+import {
+  validateKeyedFloats
+} from "./keyed-float-validate.js";
+function validateDiagrams(lessons) {
+  return validateKeyedFloats(lessons, {
+    tagName: "Diagram",
+    prefix: "dia",
+    noun: "diagram"
+  });
+}
+export {
+  validateDiagrams
+};

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

@@ -45,10 +45,15 @@ interface EquationLessonInput {
     readonly file: string;
     readonly body: string;
     /**
-     * The lesson's 1-based ordinal in the course. When set, equations are
-     * numbered `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+     * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
+     * and how many display equations earlier lessons of that part already used.
+     * When set, equations are numbered `‹part›.‹offset + n›`; when omitted, the
+     * legacy `##`-section scheme. See `docs/authoring/structure.md`.
      */
-    readonly chapter?: number;
+    readonly numbering?: {
+        readonly prefix: number;
+        readonly offset: number;
+    };
 }
 declare function validateEquations(lessons: readonly EquationLessonInput[]): EquationValidation;
 

package/dist/reference/equations-validate.js

@@ -25,7 +25,7 @@ function validateEquations(lessons) {
   )) {
     const seen = /* @__PURE__ */ new Set();
     const table = {};
-    for (const raw of scanEquationLabels(lesson.body, lesson.chapter)) {
+    for (const raw of scanEquationLabels(lesson.body, lesson.numbering)) {
       if (seen.has(raw.key)) {
         diagnostics.push({
           code: "eq-duplicate-key",

package/dist/reference/equations.d.mts

@@ -9,12 +9,28 @@ export function parseEquationRef(raw: any): {
 /** Remove every `\label{eq:…}` (and the whitespace it leaves) from a math source. */
 export function stripEquationLabels(latex: any): string;
 /**
- * The visible number for one display equation. With `chapter` (the lesson's
- * course ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings
+ * Normalise the numbering input to `{ prefix, offset }`.
+ *
+ * `prefix` is the number before the dot — the **part**'s ordinal (its position
+ * among the sidebar groups). `offset` is how many display equations already
+ * appeared in earlier lessons of that same part, so `n` runs continuously
+ * across a part instead of restarting on every page. A bare number is the
+ * legacy per-lesson form (`prefix = n`, `offset = 0`) and is still accepted so
+ * hand-built trees and unit tests keep working. `undefined`/`null`/`0` ⇒ the
+ * `##`-section fallback for non-lesson pages.
+ */
+export function resolveNumbering(input: any): {
+    prefix: any;
+    offset: number;
+};
+/**
+ * The visible number for one display equation. With a `prefix` (the part's
+ * ordinal) the scheme is `‹part›.‹offset + indexInLesson›` and `##` headings
  * are ignored; without it, the legacy `##`-section scheme.
  */
-export function displayEquationNumber({ chapter, section, indexInSection, indexInLesson, }: {
-    chapter: any;
+export function displayEquationNumber({ prefix, offset, section, indexInSection, indexInLesson, }: {
+    prefix: any;
+    offset?: number | undefined;
     section: any;
     indexInSection: any;
     indexInLesson: any;
@@ -35,58 +51,73 @@ export function stripFencedCode(markdown: any): string;
  * `keep`, when given, leaves a component of that name untouched instead of
  * blanking it — `keyed-jsx-floats.mjs` uses this to blank every *other*
  * component while still finding `<Table>`/`<Figure>` tags at the top level.
+ *
+ * `transparent`, when given, removes only those components' opening/closing
+ * tags and exposes their body to the later blanking pass. `<Memo>` and
+ * `<ShortNote>` are intentional uses: unlike a worked-example/presentation
+ * wrapper, their bodies are details in the lesson's reading order, so numbered
+ * equations/floats in them stay in the official sequence. Section headings in
+ * a transparent body do not change the surrounding page's section counter.
  */
-export function stripJsxComponents(markdown: any, keep: any): string;
+export function stripJsxComponents(markdown: any, keep: any, transparent?: any[]): string;
 /**
- * Every keyed display equation in a Markdown body, in appearance order, with
- * its assigned number. `$$…$$` blocks only. With `chapter` (the lesson's
- * course ordinal) the number is `‹chapter›.‹n›`, `n` sequential over every
- * display block in the lesson; without it, `##` headings advance a section
- * counter and the number is `‹section›.‹indexInSection›`. Either way every
- * display block advances the index, so a keyed equation's number reflects its
- * position among *all* display equations, not only the keyed ones.
+ * Every display equation in a Markdown body, keyed or not, in appearance order
+ * with its assigned number. `$$…$$` blocks only. With `numbering`
+ * (`{ prefix, offset }`, the part's ordinal and the count of display equations
+ * in earlier lessons of that part) the number is `‹part›.‹offset + n›`, `n`
+ * sequential over every display block in the lesson; without it, `##` headings
+ * advance a section counter and the number is `‹section›.‹indexInSection›`.
+ * Either way every display block advances the index, so a keyed equation's
+ * number reflects its position among *all* display equations, not only the
+ * keyed ones.
  */
-export function scanEquationLabels(markdown: any, chapter: any): {
-    key: string;
+export function scanDisplayEquations(markdown: any, numbering: any): {
+    key: string | null | undefined;
+    number: string;
+    section: number;
+    indexInSection: number;
+}[];
+/** The keyed subset of `scanDisplayEquations` — the manifest builder's view. */
+export function scanEquationLabels(markdown: any, numbering: any): {
+    key: string | null | undefined;
     number: string;
     section: number;
     indexInSection: number;
 }[];
+/**
+ * How many display equations a lesson body holds. This is what makes `n` run
+ * continuously across a part: a lesson's `offset` is the sum of this over every
+ * earlier lesson in the same part.
+ */
+export function countDisplayEquations(markdown: any): number;
 /**
  * The mdast equivalent of `scanEquationLabels` for *every* display equation:
  * walk the tree in document order, advancing the section counter on every
  * depth-2 heading and emitting a record for every `math` node. `key` is the
- * `\label{eq:…}` payload when present, else `null`. `chapter` is threaded the
+ * `\label{eq:…}` payload when present, else `null`. `numbering` is threaded the
  * same way as in `scanEquationLabels`.
  */
-export function collectDisplayEquations(tree: any, chapter: any): {
-    key: string | null;
-    number: string;
-    section: number;
-    indexInSection: number;
-    node: any;
-}[];
+export function collectDisplayEquations(tree: any, numbering: any): any[];
 /**
  * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
  * `scanEquationLabels`. Numbers reflect position among all display equations.
  */
-export function collectEquationLabels(tree: any, chapter: any): {
-    key: string | null;
-    number: string;
-    section: number;
-    indexInSection: number;
-    node: any;
-}[];
+export function collectEquationLabels(tree: any, numbering: any): any[];
 /**
  * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
  *
  * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
- * from appearance order. When the caller supplies a `chapter` (the lesson's
- * ordinal position in the course), the number is `‹chapter›.‹n›` — `n` counts
- * every display equation in the lesson and `##` headings do not affect it
- * (`(2.4)` = fourth display equation of the second lesson). With no `chapter`
- * the number falls back to the `##`-section scheme `‹section›.‹indexInSection›`
- * (used by hand-built test trees and non-lesson pages). An author additionally
+ * from appearance order. When the caller supplies `numbering`
+ * (`{ prefix, offset }` — see `resolveNumbering`), the number is
+ * `‹part›.‹offset + n›`: the prefix is the **part**'s ordinal among the sidebar
+ * groups, `n` counts every display equation in the lesson, and `offset` carries
+ * the count from earlier lessons of the same part so the sequence runs
+ * continuously across a part rather than restarting on every page. `##` and
+ * `###` headings never affect it — `(2.4)` is the fourth display equation of
+ * part 2, wherever in that part it sits. See `docs/authoring/structure.md` for
+ * the level names. With no `numbering` the number falls back to the
+ * `##`-section scheme `‹section›.‹indexInSection›` (used by hand-built test
+ * trees and non-lesson pages). An author additionally
  * marks an equation with a trailing `\label{eq:<key>}` inside its `$$…$$`
  * block (inside math, so the `:` is safe and the form matches amsmath) when
  * they want a *stable* anchor that survives edits and cross-page references: