explico 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -14,6 +14,75 @@ under **Breaking** below; a PATCH never breaks.
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-09
+
+### Breaking
+
+- **Equation, table, and figure numbers are now `‹part›.‹n›`, not
+  `‹lesson›.‹n›`.** A *part* is a sidebar group; `n` counts that kind of float
+  across the whole part, running unbroken from one chapter into the next.
+  Previously the prefix was the lesson's ordinal down the entire course and `n`
+  restarted on every page, so a sixteen-lesson course had sixteen prefixes.
+  Every number in an existing course changes. Nothing an author wrote changes —
+  numbers were never hand-typed — but a published link of the form `#eq-2-4`
+  (the positional anchor of an *unkeyed* equation) moves; a keyed `#eq-<key>`
+  anchor is unaffected. Manifest schema is now **v7**: `lessons[].part` is new,
+  `lessons[].chapter` is redefined as the lesson's ordinal *within its part*,
+  and `lessons[].numbering` carries the per-kind running counts.
+- **`courseConfig.sections` is renamed `courseConfig.parts`.** "Section" now
+  only ever means an `##` heading inside a lesson. The old name still works and
+  is removed in the next MINOR release; `CourseSection` is a deprecated alias
+  for `CoursePart`.
+
+### Added
+
+- [`docs/authoring/structure.md`](docs/authoring/structure.md) — the structural
+  taxonomy the rest of the docs speak in: course → part → chapter → section →
+  subsection, which levels a number counts, and why the numbering invariant is
+  build-enforced. Two levels were previously both called "section", and two
+  were both called "chapter".
+- `remarkNotation` accepts a `manifest` option that supplies every numbering
+  input at once — `equations`, `tables`, `figures`, and the part/offset
+  placement map, all read off the same compiled manifest. This is now the recommended wiring in
+  `astro.config.mjs`; the individual options remain, and an explicit one still
+  wins over the manifest. `numberingFromManifest(manifest)` is exported for
+  callers that need the derived object on its own.
+- `explicoContentRefresh(courseConfig, manifest)` recompiles the manifest and
+  restarts Astro development after any `content/` change, independent of the
+  editor making it.
+
+### Fixed
+
+- **Equation, table, and figure numbers no longer disagree between a page and
+  the references to it (WERN).** A course that passed the manifest number tables
+  to `remarkNotation` without the placement map silently numbered every page by
+  `##` section — restarting at `1.1` on each page — while cross-page references
+  kept reading the manifest, so one equation was `(2.2)` on its own page and
+  `(4.5)` everywhere else. `remarkNotation` now cross-checks the number
+  it computes for each keyed equation / table / figure against the manifest
+  number for the same key and fails the build on any disagreement, naming the
+  key, both numbers, and the missing placement. The same omission was
+  present in `explico content check`, which therefore validated lessons under a
+  numbering scheme the real build never used; it now shares the manifest wiring.
+
+### Changed
+
+- Parts in the left sidebar now start collapsed, retain compact chapter icons
+  with hover/focus labels, and expand to the full chapter names when the part
+  title is opened. (Previously described as "chapter groups" with "subchapter"
+  icons — the same UI, named per the taxonomy.)
+
+### Fixed
+
+- `loadManifest(courseConfig)` now always compiles current course content, and
+  `LessonFooter` rejects local-notation key drift. Current math hover markers can
+  no longer be silently paired with stale cards from a persisted manifest.
+- Notation hover markers inside `\sqrt{…}` (and under an extensible arrow such
+  as `\xrightarrow`) are reachable again: KaTeX paints the radical/arrow SVG as
+  an absolutely-positioned overlay on top of the content it decorates, which
+  was swallowing the pointer. `NotationLayer` now sets `pointer-events: none`
+  on that overlay layer, matching the existing fraction/subscript workaround.
+
 ## [0.3.0] - 2026-09-05
 
 ### Breaking
@@ -96,7 +165,9 @@ under **Breaking** below; a PATCH never breaks.
   system with its completeness gate, the curriculum-graph validator, the
   Astro/Starlight UI, the LMS / session / analytics seams, and the `content` CLI.
 
-[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/danieltuzes/explico/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/danieltuzes/explico/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/danieltuzes/explico/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/danieltuzes/explico/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/danieltuzes/explico/releases/tag/v0.1.0

package/README.md

@@ -69,6 +69,7 @@ export { collections } from 'explico/content-config';
 
 ```js
 // astro.config.mjs
+import { explicoContentRefresh } from 'explico/compiler/astro.js';
 import { loadManifest } from 'explico/compiler/manifest.js';
 import remarkNotation from 'explico/reference/remark-notation.mjs';
 import remarkCitation from 'explico/reference/remark-citation.mjs';
@@ -77,12 +78,30 @@ import rehypeFailKatexErrors from 'explico/reference/rehype-fail-katex-errors.mj
 import { courseConfig } from './content/course.config.ts';
 
 const manifest = await loadManifest(courseConfig);
-// … starlight({ customCss: ['explico/styles/global.css'],
+// markdown.remarkPlugins: [
+//   remarkMath,
+//   // One `manifest` carries every numbering input — the equation / table /
+//   // figure number tables *and* the part each lesson sits in. Pass the
+//   // tables without the placement and the page numbers its equations by `##`
+//   // section while references to it read the part scheme, so the same
+//   // equation reads (2.2) at home and (4.5) abroad; the plugin rejects that
+//   // at build time rather than shipping it.
+//   [remarkNotation, { definitions: manifest.notation.raw, manifest }],
+//   [remarkCitation, { sources: manifest.sources }],
+// ]
+// … integrations: [explicoContentRefresh(courseConfig, manifest),
+//                  starlight({ customCss: ['explico/styles/global.css'],
 //               components: { Footer: 'explico/components/starlight/LessonFooter.astro',
 //                             SocialIcons: 'explico/components/starlight/LayoutSocialIcons.astro', … } })
-// … markdown.remarkPlugins / rehypePlugins from the manifest
+// … rehypePlugins: [[rehypeKatex, createNotationKatexOptions()], rehypeFailKatexErrors]
 ```
 
+`loadManifest(courseConfig)` always recompiles current content before Astro
+starts. `explicoContentRefresh(courseConfig, manifest)` recompiles the manifest
+and restarts the development server when any file under `content/` is added,
+changed, or removed, keeping Markdown transforms and UI components on the same
+model without an editor-specific task.
+
 ```jsonc
 // package.json — the read-side CLI
 "scripts": { "validate:content": "tsx scripts/compile-manifest.ts" }

package/dist/compiler/astro.d.ts

@@ -0,0 +1,30 @@
+import { AstroIntegration } from 'astro';
+import { CourseConfig } from './course-config.js';
+import { Manifest } from './manifest.js';
+import '../curriculum/validation.js';
+import '../reference/consistency.js';
+import './collections.js';
+import '../reference/types.js';
+import '../reference/lint-ignore.js';
+import '../reference/equations-validate.js';
+import '../reference/tables-validate.js';
+import '../reference/keyed-float-validate.js';
+import '../reference/figures-validate.js';
+import '../reference/gate-math.js';
+import '../reference/gloss.js';
+import './knowledge-version.js';
+import './lesson-derivation.js';
+
+/** Fail loudly instead of rendering math triggers whose local cards are stale. */
+declare function assertLocalNotationParity(lessonId: string, authoredKeys: readonly string[], renderedKeys: readonly string[]): void;
+/**
+ * Restart Astro when an authored content file changes. Astro reloads MDX on
+ * its own, but Explico's manifest is created by `astro.config.mjs`; a restart
+ * is what makes the remark plugins and page UI consume the same fresh model.
+ *
+ * Add this integration once to `integrations` in `astro.config.mjs`. The
+ * restart is automatic and editor-agnostic (change/add/unlink all work).
+ */
+declare function explicoContentRefresh(courseConfig: CourseConfig, manifest: Manifest): AstroIntegration;
+
+export { assertLocalNotationParity, explicoContentRefresh };

package/dist/compiler/astro.js

@@ -0,0 +1,79 @@
+import { resolve, sep } from "node:path";
+import {
+  compileManifest,
+  writeManifest
+} from "./manifest.js";
+const watchedServers = /* @__PURE__ */ new WeakSet();
+function assertLocalNotationParity(lessonId, authoredKeys, renderedKeys) {
+  const authored = [...new Set(authoredKeys)].sort();
+  const rendered = [...new Set(renderedKeys)].sort();
+  if (authored.length === rendered.length && authored.every((key, index) => key === rendered[index])) {
+    return;
+  }
+  throw new Error(
+    `Stale Explico manifest for ${lessonId}: lesson notation.local has [${authored.join(", ")}], but the page notation bundle has [${rendered.join(", ")}]. Pass courseConfig to loadManifest() and add explicoContentRefresh() to the Astro integrations.`
+  );
+}
+function replaceInPlace(target, source) {
+  if (Array.isArray(target) && Array.isArray(source)) {
+    target.splice(0, target.length, ...source);
+    return;
+  }
+  if (!target || !source || typeof target !== "object" || typeof source !== "object") {
+    return;
+  }
+  const mutable = target;
+  const fresh = source;
+  for (const key of Object.keys(mutable)) {
+    if (!(key in fresh)) delete mutable[key];
+  }
+  for (const [key, value] of Object.entries(fresh)) {
+    const current = mutable[key];
+    if (Array.isArray(current) && Array.isArray(value) || current && value && typeof current === "object" && typeof value === "object" && !Array.isArray(current) && !Array.isArray(value)) {
+      replaceInPlace(current, value);
+    } else {
+      mutable[key] = value;
+    }
+  }
+}
+function explicoContentRefresh(courseConfig, manifest) {
+  return {
+    name: "explico-content-refresh",
+    hooks: {
+      "astro:server:setup": ({ server }) => {
+        if (watchedServers.has(server)) return;
+        watchedServers.add(server);
+        const contentRoot = `${resolve(process.cwd(), "content")}${sep}`;
+        let timer;
+        let restarting = false;
+        const refresh = (path) => {
+          const absolute = resolve(path);
+          if (!absolute.startsWith(contentRoot) || restarting) return;
+          if (timer) clearTimeout(timer);
+          timer = setTimeout(async () => {
+            restarting = true;
+            try {
+              const fresh = await compileManifest(courseConfig);
+              writeManifest(fresh);
+              replaceInPlace(manifest, fresh);
+              await server.restart();
+            } catch (error) {
+              server.config.logger.error(
+                `Explico could not refresh the content manifest: ${error instanceof Error ? error.message : String(error)}`
+              );
+            } finally {
+              restarting = false;
+            }
+          }, 50);
+        };
+        server.watcher.on("add", refresh);
+        server.watcher.on("change", refresh);
+        server.watcher.on("unlink", refresh);
+      }
+    }
+  };
+}
+export {
+  assertLocalNotationParity,
+  explicoContentRefresh
+};

package/dist/compiler/cli.js

@@ -121,15 +121,11 @@ function processorFor(manifest) {
       // shape here that it does there (D7/F-tables-figures parity).
       remarkMdx,
       remarkMath,
-      [
-        remarkNotation,
-        {
-          definitions: manifest.notation.raw,
-          equations: manifest.equations.numbersBySlug,
-          tables: manifest.tables.numbersBySlug,
-          figures: manifest.figures.numbersBySlug
-        }
-      ],
+      // `manifest` carries the number tables *and* the part/offset placement
+      // together, so this check numbers a page exactly as the Astro build
+      // does. Passing the tables alone silently numbered pages by `##` section
+      // here while cross-page references read the part-scheme manifest.
+      [remarkNotation, { definitions: manifest.notation.raw, manifest }],
       [remarkCitation, { sources: manifest.sources }]
     ],
     rehypePlugins: [

package/dist/compiler/course-config.d.ts

@@ -6,12 +6,23 @@
  * data value and passes it here, typed against `CourseConfig`. A second course
  * supplies its own value of this shape.
  */
-interface CourseSection {
+/**
+ * One **part** — a sidebar group, holding the chapters (lessons) whose slugs
+ * start with `dir`. A part's 1-based position in `CourseConfig.parts` is the
+ * number before the dot in every equation, table, and figure number inside it.
+ * See `docs/authoring/structure.md` for the full level taxonomy.
+ */
+interface CoursePart {
     /** Lesson-slug prefix, e.g. `bonds` for `bonds/yield-to-maturity`. */
     readonly dir: string;
     /** Sidebar group heading. */
     readonly label: string;
 }
+/**
+ * @deprecated Renamed to {@link CoursePart}. "Section" now only ever means an
+ * `##` heading inside a lesson. Removed in the next MINOR release.
+ */
+type CourseSection = CoursePart;
 interface CourseConventions {
     /** Notation key a lesson's stated sign convention must resolve to. */
     readonly signConventionKey: string;
@@ -68,8 +79,16 @@ interface CourseAbout {
 interface CourseConfig {
     readonly title: string;
     readonly description: string;
-    /** Sidebar section groups, in order. */
-    readonly sections: readonly CourseSection[];
+    /**
+     * The course's parts (sidebar groups), in order. Exactly one of `parts` or
+     * the deprecated `sections` must be given.
+     */
+    readonly parts?: readonly CoursePart[];
+    /**
+     * @deprecated Renamed to {@link CourseConfig.parts}. Still honoured, so a
+     * course on the old name keeps building; removed in the next MINOR release.
+     */
+    readonly sections?: readonly CoursePart[];
     /** Namespaces used by competency / notation `domain` fields. */
     readonly domains: readonly string[];
     readonly conventions: CourseConventions;
@@ -78,5 +97,11 @@ interface CourseConfig {
     /** Edits to the shipped named-operator baseline (rule N8). Optional. */
     readonly operators?: CourseOperators;
 }
+/**
+ * The course's parts, from whichever field the config uses. Throws rather than
+ * silently producing a course with no sidebar groups — a config with neither
+ * field would otherwise number every float by the `##`-section fallback.
+ */
+declare function coursePartsOf(config: CourseConfig): readonly CoursePart[];
 
-export type { CourseAbout, CourseAuthor, CourseConfig, CourseConventions, CourseOperators, CourseSection };
+export { type CourseAbout, type CourseAuthor, type CourseConfig, type CourseConventions, type CourseOperators, type CoursePart, type CourseSection, coursePartsOf };

package/dist/compiler/course-config.js

@@ -0,0 +1,12 @@
+function coursePartsOf(config) {
+  const parts = config.parts ?? config.sections;
+  if (!parts || parts.length === 0) {
+    throw new Error(
+      "CourseConfig needs at least one entry in `parts` (a sidebar group: { dir, label }). The old name `sections` is still accepted."
+    );
+  }
+  return parts;
+}
+export {
+  coursePartsOf
+};

package/dist/compiler/lesson-derivation.d.ts

@@ -84,6 +84,6 @@ type SidebarGroup = {
  * merged track order (ties broken by slug), then the static Reference group.
  * Replaces seven `autogenerate` blocks that read an authored `sidebar.order`.
  */
-declare function buildSidebar(tracks: readonly TrackLike[], lessonSlugs: readonly string[], sections: readonly SidebarSection[]): SidebarGroup[];
+declare function buildSidebar(tracks: readonly TrackLike[], lessonSlugs: readonly string[], parts: readonly SidebarSection[]): SidebarGroup[];
 
 export { type SidebarGroup, type SidebarSection, buildSidebar, citedSourceIds, deriveRequires, deriveSources, isLessonSlug, lessonIdFromSlug, mergeTrackOrder, parseCheckList };

package/dist/compiler/lesson-derivation.js

@@ -59,12 +59,12 @@ function mergeTrackOrder(tracks) {
   }
   return ordered;
 }
-function buildSidebar(tracks, lessonSlugs, sections) {
+function buildSidebar(tracks, lessonSlugs, parts) {
   const rank = new Map(
     mergeTrackOrder(tracks).map((lessonId, index) => [lessonId, index])
   );
   const positionOf = (slug) => rank.get(lessonIdFromSlug(slug)) ?? Number.POSITIVE_INFINITY;
-  const groups = sections.map(({ dir, label }) => ({
+  const groups = parts.map(({ dir, label }) => ({
     label,
     items: lessonSlugs.filter((slug) => slug.startsWith(`${dir}/`)).sort(
       (left, right) => positionOf(left) - positionOf(right) || left.localeCompare(right)

package/dist/compiler/manifest.d.ts

@@ -57,8 +57,12 @@ import '../reference/keyed-float-validate.js';
  * against `content/CHANGELOG.md`) and `diagnostics.knowledge`.
  * v6 (chapter numbering): `lessons[].chapter` — the lesson's 1-based course
  * ordinal, the chapter in every equation/table/figure number (`(2.1)`).
+ * v7 (part numbering): `lessons[].part` (the sidebar group's 1-based ordinal,
+ * now the number before the dot), `lessons[].chapter` redefined as the
+ * lesson's ordinal *within its part*, and `lessons[].numbering` — the
+ * per-kind offsets that make `n` run continuously across a part.
  */
-declare const MANIFEST_SCHEMA_VERSION = 6;
+declare const MANIFEST_SCHEMA_VERSION = 7;
 declare const MANIFEST_PATH: string;
 interface ManifestCitation {
     readonly id: string;
@@ -108,11 +112,28 @@ interface ManifestLesson {
     /** Docs-loader slug, e.g. `bonds/price-yield-relationship`. */
     readonly slug: string;
     /**
-     * The lesson's 1-based ordinal in the course (merged track order, then any
-     * unranked lessons by slug). It is the chapter in every equation, table, and
-     * figure number on the page — `(2.1)` is the first equation of chapter 2.
+     * The 1-based ordinal of the **part** this lesson sits in — its sidebar
+     * group's position in `courseConfig.parts`. It is the number before the dot
+     * in every equation, table, and figure number on the page: `(2.1)` is the
+     * first equation of part 2. See `docs/authoring/structure.md`.
+     */
+    readonly part: number;
+    /**
+     * The lesson's 1-based ordinal **within its part** (merged track order, then
+     * any unranked lessons by slug) — its chapter number. This orders the
+     * sidebar and the reading path; it does not appear in a float's number.
      */
     readonly chapter: number;
+    /**
+     * How many floats of each kind the earlier lessons of this part already
+     * used. The lesson's own floats continue from here, so a part's sequence
+     * runs unbroken across its chapters instead of restarting on every page.
+     */
+    readonly numbering: {
+        readonly equations: number;
+        readonly tables: number;
+        readonly figures: number;
+    };
     readonly file: string;
     readonly title: string;
     readonly description: string;

package/dist/compiler/manifest.js

@@ -16,6 +16,8 @@ import {
   runConsistencyChecks
 } from "../reference/consistency.js";
 import { validateNotationAlignment } from "../reference/curriculum-alignment.js";
+import { countDisplayEquations } from "../reference/equations.mjs";
+import { countKeyedJsxFloats } from "../reference/keyed-jsx-floats.mjs";
 import {
   validateEquations
 } from "../reference/equations-validate.js";
@@ -32,6 +34,7 @@ import { loadLintIgnore } from "../reference/lint-ignore.js";
 import { buildNotationRegistry } from "../reference/registry.js";
 import { formulaGlyphScope } from "../reference/gloss.js";
 import { resolveReferenceId } from "../reference/references.js";
+import { coursePartsOf } from "./course-config.js";
 import {
   resolveKnowledgeVersion
 } from "./knowledge-version.js";
@@ -48,7 +51,7 @@ import {
   isLessonSlug,
   lessonIdFromSlug
 } from "./lesson-derivation.js";
-const MANIFEST_SCHEMA_VERSION = 6;
+const MANIFEST_SCHEMA_VERSION = 7;
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const MANIFEST_PATH = join(REPOSITORY_ROOT, "build", "manifest.json");
@@ -231,38 +234,61 @@ async function compileManifest(courseConfig) {
   const sidebar = buildSidebar(
     catalog.tracks.map((track) => ({ id: track.id, lessons: track.lessons })),
     lessonSlugs,
-    courseConfig.sections
+    coursePartsOf(courseConfig)
   );
-  const chapterByLessonId = /* @__PURE__ */ new Map();
-  let chapterCursor = 0;
+  const bodyByLessonId = new Map(
+    notationInput.lessons.map((lesson) => [lesson.lessonId, lesson.body])
+  );
+  const placementByLessonId = /* @__PURE__ */ new Map();
+  let partCursor = 0;
   for (const group of sidebar) {
-    for (const item of group.items) {
-      if (typeof item !== "string") continue;
-      chapterByLessonId.set(lessonIdFromSlug(item), ++chapterCursor);
+    const lessonIds = group.items.filter((item) => typeof item === "string").map(lessonIdFromSlug);
+    if (lessonIds.length === 0) continue;
+    partCursor += 1;
+    const used = { equations: 0, tables: 0, figures: 0 };
+    let chapterCursor = 0;
+    for (const lessonId of lessonIds) {
+      const body = bodyByLessonId.get(lessonId) ?? "";
+      placementByLessonId.set(lessonId, {
+        part: partCursor,
+        chapter: ++chapterCursor,
+        numbering: { ...used }
+      });
+      used.equations += countDisplayEquations(body);
+      used.tables += countKeyedJsxFloats(body, { tagName: "Table" });
+      used.figures += countKeyedJsxFloats(body, { tagName: "Figure" });
     }
   }
-  const keyedFloatLessonInputs = notationInput.lessons.map((lesson) => ({
-    lessonId: lesson.lessonId,
-    slug: lesson.lessonId.replace(/\./g, "/"),
-    file: lesson.source.file,
-    body: lesson.body,
-    chapter: chapterByLessonId.get(lesson.lessonId)
-  }));
-  const equationValidation = validateEquations(keyedFloatLessonInputs);
+  const floatInputs = (kind) => notationInput.lessons.map((lesson) => {
+    const placement = placementByLessonId.get(lesson.lessonId);
+    return {
+      lessonId: lesson.lessonId,
+      slug: lesson.lessonId.replace(/\./g, "/"),
+      file: lesson.source.file,
+      body: lesson.body,
+      ...placement ? {
+        numbering: {
+          prefix: placement.part,
+          offset: placement.numbering[kind]
+        }
+      } : {}
+    };
+  });
+  const equationValidation = validateEquations(floatInputs("equations"));
   const equationsBySlug = new Map(
     Object.entries(equationValidation.numbersBySlug).map(([slug, table]) => [
       slug,
       Object.entries(table).map(([key, number]) => ({ key, number }))
     ])
   );
-  const tableValidation = validateTables(keyedFloatLessonInputs);
+  const tableValidation = validateTables(floatInputs("tables"));
   const tablesBySlug = new Map(
     Object.entries(tableValidation.numbersBySlug).map(([slug, table]) => [
       slug,
       Object.entries(table).map(([key, number]) => ({ key, number }))
     ])
   );
-  const figureValidation = validateFigures(keyedFloatLessonInputs);
+  const figureValidation = validateFigures(floatInputs("figures"));
   const figuresBySlug = new Map(
     Object.entries(figureValidation.numbersBySlug).map(([slug, table]) => [
       slug,
@@ -282,10 +308,16 @@ async function compileManifest(courseConfig) {
     lessons.push({
       id,
       slug: id.replace(/\./g, "/"),
-      // 0 = the lesson is not placed in any configured section; a curriculum
+      // 0 = the lesson is not placed in any configured part; a curriculum
       // diagnostic covers that separately, and both numbering paths then fall
       // back to the legacy `##`-section scheme.
-      chapter: chapterByLessonId.get(id) ?? 0,
+      part: placementByLessonId.get(id)?.part ?? 0,
+      chapter: placementByLessonId.get(id)?.chapter ?? 0,
+      numbering: placementByLessonId.get(id)?.numbering ?? {
+        equations: 0,
+        tables: 0,
+        figures: 0
+      },
       file: notationLesson.source.file,
       title: frontmatter.title,
       description: frontmatter.description,
@@ -437,15 +469,15 @@ function readManifestSync() {
   return JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
 }
 async function loadManifest(courseConfig) {
-  if (existsSync(MANIFEST_PATH)) return readManifestSync();
-  if (!courseConfig) {
-    throw new Error(
-      `${relative(REPOSITORY_ROOT, MANIFEST_PATH)} not found. Run \`pnpm validate:content\` first.`
-    );
+  if (courseConfig) {
+    const manifest = await compileManifest(courseConfig);
+    writeManifest(manifest);
+    return manifest;
   }
-  const manifest = await compileManifest(courseConfig);
-  writeManifest(manifest);
-  return manifest;
+  if (existsSync(MANIFEST_PATH)) return readManifestSync();
+  throw new Error(
+    `${relative(REPOSITORY_ROOT, MANIFEST_PATH)} not found. Run \`pnpm validate:content\` first.`
+  );
 }
 export {
   MANIFEST_PATH,

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",