explico 0.13.1 → 0.15.0

package/src/compiler/manifest.ts

@@ -92,6 +92,8 @@ import {
   gateContentMath,
   pageScope,
   scopeEntry,
+  scopeLocals,
+  suspendedOperators,
   type MathGateDiagnostic,
 } from '../reference/gate-math';
 import { gateIndices, type DerivedUse } from '../reference/gate-indices';
@@ -129,7 +131,7 @@ import { loadLintIgnore } from '../reference/lint-ignore';
 import { buildNotationRegistry } from '../reference/registry';
 import { formulaGlyphScope } from '../reference/gloss';
 import type { GlyphScopeEntry } from '../reference/gloss';
-import { resolveReferenceId } from '../reference/references';
+import { pageScopeLessonIds, resolvePageReferenceId } from '../reference/references';
 import type { NotationGlossEntry } from '../reference/types';
 import type {
   NotationBacklink,
@@ -142,12 +144,22 @@ import {
   coursePartsOf,
   normalizeBlockLabels,
   normalizeCards,
+  normalizeSidebarMarks,
+  normalizeSidebarEditions,
+  normalizeReadingMemory,
+  normalizeAppearance,
   normalizeLessonExports,
   normalizeDisclosure,
   normalizeNumbering,
+  normalizeDeck,
   type BlockLabels,
   type CourseConfig,
+  type NormalizedDeck,
   type NormalizedCards,
+  type NormalizedSidebarMarks,
+  type NormalizedSidebarEditions,
+  type ReadingMemorySetting,
+  type NormalizedAppearance,
   type NormalizedLessonExports,
   type NormalizedDisclosure,
   type NormalizedNumbering,
@@ -170,6 +182,15 @@ import {
   resolveKnowledgeVersion,
   type KnowledgeVersionDiagnostic,
 } from './knowledge-version';
+import {
+  deckStaleDiagnostics,
+  nextPageVersions,
+  PAGE_VERSIONS_FILE,
+  pageSourceDigest,
+  readPageVersions,
+  sinceOf,
+  type ManifestPageVersions,
+} from './page-versions';
 import {
   loadAbbreviationRegistryInput,
   loadContentRecords,
@@ -180,12 +201,23 @@ import {
   loadNotationSpecs,
   loadPartOverviews,
   loadSourceRecords,
+  loadDeckFiles,
+  loadDeckNotationPages,
+  loadLessonFiles,
+  type LessonDeckFile,
+  type PartDeckFile,
 } from './collections';
+import { buildDecks, chapterEquationLatex, type BuiltDeck, type DeckPartFacts } from './decks';
+import { readDeckSource } from '../reference/deck-source';
+import { coveredSections, type ChapterFloats } from '../reference/decks-validate';
 import {
   buildSidebar,
   deriveSources,
   isLessonSlug,
   lessonIdFromSlug,
+  mergeTrackOrder,
+  sidebarLessonSlug,
+  withPartDeckFrames,
   type SidebarGroup,
 } from './lesson-derivation';
 
@@ -346,8 +378,65 @@ import {
  * `formulaTemplate` when its entry sets them, and a bundle definition its
  * `range`. `diagnostics.math` carries `index-explained`, `index-swallowed`,
  * `index-range` and `derived-key-taken`.
+ *
+ * v32 (a page's own version, rule C5): `lessons[].since` and
+ * `parts[].overview.since` carry the knowledge version each chapter's and
+ * part page's content last changed in (`null` for a change not yet
+ * released), read from the committed `content/versions.json` through
+ * `pageVersions` — the record as `validate:content` writes it.
+ * `about.knowledge` gains `releases` (every released entry with its date)
+ * and `unreleased` (whether `## [Unreleased]` holds bullets).
+ * `diagnostics.knowledge` can carry `page-versions-invalid`.
+ * `sidebarMarks` carries the course's `sidebarMarks` setting, defaults
+ * applied: whether the sidebar marks a page the reader has not opened yet,
+ * and one whose content changed since they last did. `readingMemory` says
+ * whether the course asks the reader to keep that memory (`ask`) or never
+ * keeps it (`off`).
+ * v33 (decks, additive): `decks` lists each lesson's slide edition
+ * (`<lesson>.deck.mdx`) with its frames, numbered as the deck shows them;
+ * `deck` carries the course's `deck` settings, defaults applied, and the
+ * canvas; `lessons[].editions` says which editions a lesson has
+ * (`chapter`, `deck`). A slides-first lesson (a deck with no chapter) is a
+ * lesson like any other, with `editions: ["deck"]`. `decks[].since` is the
+ * version a deck's page last changed in (rule C5), as a chapter's `since`.
+ * In `sidebar`, a deck beside its chapter follows the chapter's slug as
+ * `{ slug, label: "Slides", attrs: { class: "explico-deck-row" } }`, and a
+ * slides-first lesson is `{ slug, attrs: { class: "explico-deck-lesson" } }`
+ * in place of its slug (`sidebarLessonSlug` reads either kind of lesson).
+ *
+ * v34 (editions in the sidebar): `sidebarEditions` carries the course's
+ * `sidebarEditions` setting, defaults applied: the edition a lesson's row
+ * opens (`lead`: `chapter` or `slides`) and whether the row lists the other
+ * (`other`: `listed` or `hidden`). In `sidebar`, every item of a lesson
+ * carries `data-edition` (`chapter` or `slides`), `data-lesson` (the
+ * lesson's slug) and `data-title` (its title) in `attrs`, so a chapter is
+ * `{ slug, attrs }` where it was a bare slug. An item lists its lesson when
+ * it is served at the lesson's own URL, `data-lesson` equal to its `slug`:
+ * a chapter, or a slides-first lesson's deck; a chapter's slides row
+ * follows it as before.
+ *
+ * v35 (the slides a reader has seen): every frame of `decks[].frames`
+ * carries `id`, 12 hex digits of a SHA-256 over what it shows, which a
+ * reader's record of the frames shown in Present mode keeps
+ * (`ManifestDeckFrame.id`).
+ *
+ * v36 (a part's deck): `decks` lists each part's deck
+ * (`<part>/index.deck.mdx`, at `<part>/slides`) too, with `part` (its
+ * directory) and no `lessonId`, which is now optional. Every deck carries
+ * `covers`, the chapters a part's deck covers with the frame each one's
+ * section opens on (empty on a lesson's deck); a part's deck carries
+ * `recalledFrom`, the chapter of each float it recalls, and each frame of
+ * a covered section `chapter`. In `sidebar`, a part's deck follows the
+ * part's Overview as `{ slug, label: "Slides", attrs: { class:
+ * "explico-deck-row explico-part-deck", "data-edition": "slides",
+ * "data-part" } }`, and a chapter it covers that has no deck of its own
+ * carries `data-deck-href`, the address of its section.
+ *
+ * v37 (the page's zones and slide edges): `appearance` carries the course's
+ * `appearance` setting, defaults applied: `zones` (`tonal`, `accent-header`,
+ * `paper` or `none`) and `slides` (`lifted`, `edge` or `sorter`).
  */
-export const MANIFEST_SCHEMA_VERSION = 31;
+export const MANIFEST_SCHEMA_VERSION = 37;
 
 const REPOSITORY_ROOT = process.cwd();
 // Content is the top-level `content/` folder; the build output is `build/`
@@ -453,6 +542,17 @@ export interface ManifestDerivedNotation {
   readonly formulaScope: readonly GlyphScopeEntry[];
 }
 
+/**
+ * One lesson's deck (v33), or a part's (v36): its frames as `decks.ts` reads
+ * them, and the notation its page shows — its own bundle, which holds its
+ * chapters'.
+ */
+export interface ManifestDeck extends BuiltDeck {
+  readonly notation: ManifestLesson['notation'];
+  /** The version the deck's page last changed in (rule C5), as a chapter's `since`. */
+  readonly since: string | null;
+}
+
 /**
  * One keyed float of a lesson (v21): its key and number, and its caption pair
  * — `short` (an equation's `\caption{…}`, or the `short` prop) and, for a
@@ -484,6 +584,12 @@ export interface ManifestLesson {
   readonly id: string;
   /** Docs-loader slug, e.g. `bonds/price-yield-relationship`. */
   readonly slug: string;
+  /**
+   * The lesson's editions (v33): `chapter` (its `.mdx`), `deck` (its
+   * `.deck.mdx`, listed in `manifest.decks`), or both. A slides-first lesson
+   * is `["deck"]`: its slug is its deck's route and its floats are unnumbered.
+   */
+  readonly editions: readonly ('chapter' | 'deck')[];
   /**
    * The 1-based ordinal of the **part** this lesson sits in — its sidebar
    * group's position in `courseConfig.parts`. It is the first number of every
@@ -532,6 +638,15 @@ export interface ManifestLesson {
   readonly file: string;
   readonly title: string;
   readonly description: string;
+  /**
+   * The knowledge version this chapter's content last changed in (v32, rule
+   * C5): its file, its checks and assessments, the shared notation it uses,
+   * the sources it cites and its numbers, against `content/versions.json`.
+   * `null` while it has a change `## [Unreleased]` has not released. What
+   * the exports and the `[?]` panel print for the page; with rule C5 off,
+   * the course's own version.
+   */
+  readonly since: string | null;
   /** Authored reader-facing estimate; `40` and `[30, 40]` both land here. */
   readonly studyMinutes?: { readonly min: number; readonly max: number };
   /** Ordered — the curriculum contract. */
@@ -614,6 +729,13 @@ export interface ManifestAbout {
     readonly date?: string;
     /** Bullet notes from that entry. */
     readonly notes: readonly string[];
+    /**
+     * Every released entry, newest first, with its date (v32): what dates a
+     * document whose content last changed in an earlier release (rule C5).
+     */
+    readonly releases: readonly { readonly version: string; readonly date?: string }[];
+    /** `## [Unreleased]` holds bullets: a change is waiting for a release (v32). */
+    readonly unreleased: boolean;
     /** Content fingerprint at compile time — ties the shown version to a build. */
     readonly contentTree: string;
   };
@@ -677,6 +799,8 @@ export interface ManifestPart {
     readonly title: string;
     readonly file: string;
     readonly description?: string;
+    /** The version the page's content last changed in (v32, rule C5), as a chapter's `since`. */
+    readonly since: string | null;
   };
 }
 
@@ -692,6 +816,30 @@ export interface Manifest {
   readonly blockLabels: BlockLabels;
   /** How the explanation cards start for a reader, defaults applied (`CourseConfig.cards`). */
   readonly cards: NormalizedCards;
+  /**
+   * Which marks the sidebar shows a reader beside a chapter or part page
+   * (v32, `CourseConfig.sidebarMarks`): not opened yet, changed since opened.
+   */
+  readonly sidebarMarks: NormalizedSidebarMarks;
+  /**
+   * Which edition a lesson's sidebar row opens for a reader who has not
+   * chosen, and whether it lists the other (v34, `CourseConfig.sidebarEditions`).
+   */
+  readonly sidebarEditions: NormalizedSidebarEditions;
+  /**
+   * Whether the course asks the reader to keep their reading memory (v32,
+   * `CourseConfig.readingMemory`): `ask` or `off`.
+   */
+  readonly readingMemory: ReadingMemorySetting;
+  /**
+   * How the page tells its zones apart and how slides sit on it, defaults
+   * applied (v37, `CourseConfig.appearance`).
+   */
+  readonly appearance: NormalizedAppearance;
+  /** The course's `deck` settings, defaults applied, and its canvas (v33). */
+  readonly deck: NormalizedDeck;
+  /** Each lesson's deck, by route (v33). */
+  readonly decks: readonly ManifestDeck[];
   /** Reader-facing identity + versions (the `[?]` About panel). */
   readonly about: ManifestAbout;
   readonly notation: {
@@ -711,6 +859,13 @@ export interface Manifest {
   /** The course's parts in config order, with their chapters and overview pages. */
   readonly parts: readonly ManifestPart[];
   readonly lessons: readonly ManifestLesson[];
+  /**
+   * The record of every chapter's and part page's own version (v32, rule
+   * C5), as `validate:content` writes it to `content/versions.json`
+   * (`syncPageVersions`); `lessons[].since` and `parts[].overview.since`
+   * are read from it.
+   */
+  readonly pageVersions: ManifestPageVersions;
   /** Every docs page that is not a chapter, by id (v25). */
   readonly pages: readonly ManifestPage[];
   /** Full competency prerequisite graph. */
@@ -872,11 +1027,12 @@ function lessonNotationResolution(
   definitionsById: ReadonlyMap<string, NotationDefinitionRecord>,
   availableDefinitionIds: ReadonlySet<string>,
 ): ManifestNotationResolution[] {
-  const scope = { kind: 'page' as const, lessonId: lesson.lessonId };
+  // A deck's references resolve in its lessons' scopes, as the registry resolves them.
+  const scopes = pageScopeLessonIds(lesson);
   return lesson.references.map((reference) => {
-    const definitionId = resolveReferenceId(
+    const definitionId = resolvePageReferenceId(
       reference.key,
-      scope,
+      scopes,
       availableDefinitionIds,
     );
     const definition =
@@ -982,7 +1138,6 @@ function lessonFrontmatterById(): Map<
     studyMinutes?: { min: number; max: number };
   }
 > {
-  const base = join(CONTENT_ROOT, 'docs');
   const result = new Map<
     string,
     {
@@ -991,29 +1146,18 @@ function lessonFrontmatterById(): Map<
       studyMinutes?: { min: number; max: number };
     }
   >();
-  const walk = (directory: string): void => {
-    for (const entry of readdirSync(directory, { withFileTypes: true })) {
-      const path = join(directory, entry.name);
-      if (entry.isDirectory()) {
-        walk(path);
-        continue;
-      }
-      if (!entry.isFile() || !/\.mdx?$/.test(entry.name)) continue;
-      const slug = relative(base, path).replace(/\\/g, '/');
-      if (!isLessonSlug(slug)) continue;
-      const id = slug.replace(/\.(md|mdx)$/, '').replace(/\//g, '.');
-      const data = (parseFrontmatter(readFileSync(path, 'utf8')).frontmatter ??
-        {}) as Record<string, unknown>;
-      const studyMinutes = studyMinutesRange(data.studyMinutes);
-      result.set(id, {
-        title: typeof data.title === 'string' ? data.title : id,
-        description:
-          typeof data.description === 'string' ? data.description : '',
-        ...(studyMinutes === undefined ? {} : { studyMinutes }),
-      });
-    }
-  };
-  walk(base);
+  // Every lesson's defining file: its chapter, or the deck of a slides-first lesson.
+  for (const { path, lessonId: id } of loadLessonFiles()) {
+    const data = (parseFrontmatter(readFileSync(path, 'utf8')).frontmatter ??
+      {}) as Record<string, unknown>;
+    const studyMinutes = studyMinutesRange(data.studyMinutes);
+    result.set(id, {
+      title: typeof data.title === 'string' ? data.title : id,
+      description:
+        typeof data.description === 'string' ? data.description : '',
+      ...(studyMinutes === undefined ? {} : { studyMinutes }),
+    });
+  }
   return result;
 }
 
@@ -1050,6 +1194,7 @@ export async function compileManifest(
   // Throws on a bad `numbering` or `blockLabels` value, like `resolveRules` above.
   const numberingSettings = normalizeNumbering(courseConfig);
   const blockLabels = normalizeBlockLabels(courseConfig);
+  const deckSettings = normalizeDeck(courseConfig);
 
   const [catalog, notationInput, abbreviationsInput] = await Promise.all([
     loadCurriculumCatalog(),
@@ -1062,11 +1207,41 @@ export async function compileManifest(
   // text and math pass the same gates. It stays out of `notationInput.lessons`,
   // which is the chapter list every numbering and curriculum pass reads.
   const nonChapterPages = loadNonChapterPages();
+  // A deck beside its chapter is a page of its own with its chapter's scope
+  // (`loadDeckNotationPages`), and a part's deck one with its chapters': its
+  // text and math pass the same gates. A slides-first lesson's deck is the
+  // lesson itself, already in `notationInput.lessons`; it numbers nothing,
+  // so the chapter-only passes below (`chapterInputs`) leave it out.
+  const deckFiles = loadDeckFiles();
+  const lessonDeckFiles = deckFiles.filter((deck): deck is LessonDeckFile => deck.scope === 'lesson');
+  // A part's lessons in the order the tracks read them, as the sidebar
+  // lists them: a part's deck binds a key its chapters define to the first.
+  const trackRank = new Map(
+    mergeTrackOrder(catalog.tracks.map((track) => ({ id: track.id, lessons: track.lessons }))).map(
+      (lessonId, index) => [lessonId, index],
+    ),
+  );
+  const readingOrder = (lessonIds: readonly string[]): string[] =>
+    [...lessonIds].sort(
+      (left, right) =>
+        (trackRank.get(left) ?? Number.POSITIVE_INFINITY) - (trackRank.get(right) ?? Number.POSITIVE_INFINITY) ||
+        left.localeCompare(right),
+    );
+  const deckPages = loadDeckNotationPages(deckFiles, { order: readingOrder });
+  const deckLessonIds = new Set(
+    loadLessonFiles()
+      .filter((file) => file.edition === 'deck')
+      .map((file) => file.lessonId),
+  );
+  const isChapter = (lessonId: string): boolean => !deckLessonIds.has(lessonId);
+  const deckPageIds = new Set(deckPages.map((page) => page.notation.lessonId));
+  const chapterInputs = notationInput.lessons.filter((lesson) => isChapter(lesson.lessonId));
   const withPages: typeof notationInput = {
     ...notationInput,
     lessons: [
       ...notationInput.lessons,
       ...nonChapterPages.map((page) => page.notation),
+      ...deckPages.map((page) => page.notation),
     ],
   };
   const registry = buildNotationRegistry(withPages);
@@ -1120,9 +1295,9 @@ export async function compileManifest(
     notationInput.sharedDefinitions.map((definition) => [definition.key, definition.label]),
   );
   const localLabelsByLesson = new Map(
-    notationInput.lessons.map((lesson) => [
+    withPages.lessons.map((lesson) => [
       lesson.lessonId,
-      new Map(lesson.localDefinitions.map((definition) => [definition.key, definition.label])),
+      new Map(scopeLocals(lesson).map((definition) => [definition.key, definition.label])),
     ]),
   );
   const termLabel = (lessonId: string, key: string): string | undefined =>
@@ -1178,19 +1353,27 @@ export async function compileManifest(
         })
       : []),
     ...(rules.isEnabled('S1')
-      ? gateHeadingLength(notationInput.lessons, {
+      ? gateHeadingLength(chapterInputs, {
           maxLength: rules.number('S1', 'maxLength'),
           labelFor: termLabel,
         })
       : []),
-    ...gateHeadingStructure(notationInput.lessons, {
+    ...gateHeadingStructure(chapterInputs, {
       levels: rules.isEnabled('S6'),
       adjacency: rules.isEnabled('S7'),
     }),
     // The course's own rules (`courseRules`): one pass for every enabled `X`
     // rule that carries a `forbid` pattern. A disabled one, and a guide rule
     // with no pattern, do no work here.
-    ...gateCourseRules(withPages.lessons, rules.course),
+    // A course rule about one edition is checked on that edition's pages.
+    ...gateCourseRules(
+      withPages.lessons.filter((lesson) => isChapter(lesson.lessonId) && !deckPageIds.has(lesson.lessonId)),
+      rules.course.filter((rule) => rule.editions !== 'deck'),
+    ),
+    ...gateCourseRules(
+      withPages.lessons.filter((lesson) => !isChapter(lesson.lessonId) || deckPageIds.has(lesson.lessonId)),
+      rules.course.filter((rule) => rule.editions !== 'chapter'),
+    ),
     // S10 is locked: a float on a non-chapter page has no number to render.
     ...gateNonChapterPages(nonChapterPages),
   ];
@@ -1311,6 +1494,17 @@ export async function compileManifest(
         'is left out of the sidebar and the numbering until it has one.',
     });
   }
+  // A part's deck, of a part the sidebar lists: one in a directory no part
+  // lists is `deck-outside-part` (`decks-validate.ts`).
+  const configuredDirs = new Set(configuredParts.map((part) => part.dir));
+  const partDeckFiles = deckFiles.filter(
+    (deck): deck is PartDeckFile => deck.scope === 'part' && configuredDirs.has(deck.partDir),
+  );
+  /** A part's chapters, by their names in its directory (what `[chapter: <name>]` writes). */
+  const partChapterNames = (dir: string): string[] =>
+    lessonSlugs
+      .filter((slug) => slug.startsWith(`${dir}/`) && isChapter(lessonIdFromSlug(slug)))
+      .map((slug) => slug.slice(dir.length + 1));
   // A lesson whose directory no part lists has no part, no chapter number and
   // no place in the sidebar.
   const partDirs = new Set(listedParts.map((part) => part.dir));
@@ -1339,21 +1533,6 @@ export async function compileManifest(
       ),
     );
   }
-  // Per-place waivers: drop the located findings each one covers, and
-  // report the waivers themselves — a stale one is a warning, a bad one an
-  // error. Chapters and non-chapter pages are scanned alike, since the text
-  // and math gates run on both; S2 and S10 are per-file or locked, so no
-  // waiver reaches them.
-  const waiverDiagnostics: WaiverDiagnostic[] = [];
-  const waiverRules = { courseRules: rules.course };
-  const waivers = withPages.lessons.flatMap((lesson) => {
-    const collected = collectWaivers(lesson, waiverRules);
-    waiverDiagnostics.push(...collected.diagnostics);
-    return collected.waivers;
-  });
-  const waived = applyWaivers(mathIssues, waivers, waiverRules);
-  mathIssues.splice(0, mathIssues.length, ...waived.kept);
-  waiverDiagnostics.push(...waived.unused);
 
   const sidebar = buildSidebar(
     catalog.tracks.map((track) => ({ id: track.id, lessons: track.lessons })),
@@ -1368,6 +1547,34 @@ export async function compileManifest(
       floatIndex: ['.mdx', '.md'].some((extension) =>
         existsSync(join(CONTENT_ROOT, 'docs', `figures-and-tables${extension}`)),
       ),
+      // A deck beside its chapter is listed right under it.
+      decks: new Map(
+        lessonDeckFiles
+          .filter((deck) => deck.chapterPath !== undefined && deck.inPart)
+          .map((deck) => [deck.lessonSlug, deck.route]),
+      ),
+      // A deck with no chapter is the lesson: its row carries the deck's glyph.
+      slidesFirst: new Set(
+        lessonDeckFiles
+          .filter((deck) => deck.chapterPath === undefined && deck.inPart)
+          .map((deck) => deck.lessonSlug),
+      ),
+      // A part's deck follows the part's Overview; a chapter it covers that
+      // has no deck of its own links into it, at its section's divider.
+      partDecks: new Map(
+        partDeckFiles.map((deck) => {
+          const { covered } = coveredSections(readDeckSource(deck.body), new Set(partChapterNames(deck.partDir)));
+          return [
+            deck.partDir,
+            {
+              route: deck.route,
+              covers: new Map(covered.map(({ name, position }) => [`${deck.partDir}/${name}`, position + 2])),
+            },
+          ];
+        }),
+      ),
+      // Each edition's row names its lesson, which the sidebar's own row shows.
+      titleOf: (slug) => frontmatterById.get(lessonIdFromSlug(slug))?.title,
     },
   );
 
@@ -1397,9 +1604,10 @@ export async function compileManifest(
   // after them is no part. An overview-only part counts, as `parts[]` does.
   for (const group of sidebar.slice(0, configuredParts.length)) {
     partCursor += 1;
-    const lessonIds = group.items
-      .filter((item): item is string => typeof item === 'string')
-      .map(lessonIdFromSlug);
+    const lessonIds = group.items.flatMap((item) => {
+      const slug = sidebarLessonSlug(item);
+      return slug === undefined ? [] : [lessonIdFromSlug(slug)];
+    });
     if (lessonIds.length === 0) continue;
     // Running totals for this part, advanced one chapter at a time; they
     // only reach a number under the part scope.
@@ -1413,7 +1621,8 @@ export async function compileManifest(
     };
     let chapterCursor = 0;
     for (const lessonId of lessonIds) {
-      const body = bodyByLessonId.get(lessonId) ?? '';
+      // A slides-first lesson's floats are unnumbered (rule D8): it adds none.
+      const body = isChapter(lessonId) ? (bodyByLessonId.get(lessonId) ?? '') : '';
       const chapter = ++chapterCursor;
       placementByLessonId.set(lessonId, {
         part: partCursor,
@@ -1448,7 +1657,8 @@ export async function compileManifest(
       return [
         lesson.lessonId,
         scanSectionHeadings(lesson.body, {
-          ...(placement
+          // A deck's headings are sections and frames, numbered as frames.
+          ...(placement && isChapter(lesson.lessonId)
             ? { prefix: `${placement.part}.${placement.chapter}` }
             : {}),
           depth: numberingSettings.sections.depth,
@@ -1475,7 +1685,11 @@ export async function compileManifest(
   // The parts themselves, in config order, with their chapters in reading
   // order — the one place a part-level page or a breadcrumb reads, so neither
   // has to re-derive a part from lesson slugs.
-  const manifestParts: ManifestPart[] = configuredParts.map((part, index) => {
+  // A part's overview page gets its `since` with the lessons, below.
+  type PartBeforeVersions = Omit<ManifestPart, 'overview'> & {
+    readonly overview?: Omit<NonNullable<ManifestPart['overview']>, 'since'>;
+  };
+  const manifestParts: PartBeforeVersions[] = configuredParts.map((part, index) => {
     const overview = overviewByDir.get(part.dir);
     const lessonIds = [...placementByLessonId]
       .filter(([lessonId]) => lessonId.startsWith(`${part.dir}.`))
@@ -1520,7 +1734,7 @@ export async function compileManifest(
   const floatInputs = (
     kind: 'equations' | 'tables' | 'figures' | 'diagrams' | 'examples',
   ) =>
-    notationInput.lessons.map((lesson) => {
+    chapterInputs.map((lesson) => {
       const placement = placementByLessonId.get(lesson.lessonId);
       return {
         lessonId: lesson.lessonId,
@@ -1658,6 +1872,8 @@ export async function compileManifest(
   // `<AssessmentSet />` draws every check of the lesson, or the one its `id`
   // names; `<CompactExamples>` draws its own set.
   const titledBlocksFor = (lessonId: string): ManifestTitledBlock[] => {
+    // A deck's question and example frames are frames, listed as frames.
+    if (!isChapter(lessonId)) return [];
     const slug = lessonId.replace(/\./g, '/');
     const body = bodyByLessonId.get(lessonId) ?? '';
     const headings = headingsByLessonId.get(lessonId) ?? [];
@@ -1688,7 +1904,7 @@ export async function compileManifest(
   // Rule V3: the course files a lesson's imports reach draw math through
   // `renderLabMath`, never KaTeX itself.
   const labKatexDiagnostics = validateLabKatexImports(
-    notationInput.lessons.map((lesson) => ({
+    [...notationInput.lessons, ...deckPages.map((page) => page.notation)].map((lesson) => ({
       lessonId: lesson.lessonId,
       file: lesson.source.file,
       body: lesson.body,
@@ -1696,7 +1912,7 @@ export async function compileManifest(
     REPOSITORY_ROOT,
   );
   const rawFloatDiagnostics = validateRawFloats(
-    notationInput.lessons.map((lesson) => ({
+    [...notationInput.lessons, ...deckPages.map((page) => page.notation)].map((lesson) => ({
       lessonId: lesson.lessonId,
       slug: lesson.lessonId.replace(/\./g, '/'),
       file: lesson.source.file,
@@ -1704,7 +1920,124 @@ export async function compileManifest(
     })),
   );
 
-  const lessons: ManifestLesson[] = [];
+  // The decks (rules D1–D10 and the `decks` invariant): each read as frames,
+  // against its page's scope and its chapter's numbers.
+  const pageInputById = new Map(withPages.lessons.map((lesson) => [lesson.lessonId, lesson]));
+  const chapterBodyById = new Map(chapterInputs.map((lesson) => [lesson.lessonId, lesson.body]));
+  const floatNumbers = (floats: readonly { readonly key: string; readonly number: string }[] | undefined) =>
+    new Map((floats ?? []).map((float) => [float.key, float.number]));
+  // A competency's `outcome` (`content-schemas.ts`), which the outcomes frame lists.
+  const outcomeById = new Map(
+    catalog.competencies.flatMap((competency): [string, string][] => {
+      const outcome = (competency as { readonly outcome?: unknown }).outcome;
+      return typeof outcome === 'string' ? [[competency.id, outcome]] : [];
+    }),
+  );
+  /** What a chapter numbers, which a deck may recall: each float's number, an equation's LaTeX. */
+  const chapterFloatsOf = (lessonId: string): ChapterFloats => {
+    const slug = lessonId.replace(/\./g, '/');
+    const chapterBody = chapterBodyById.get(lessonId);
+    const latex = chapterBody === undefined ? new Map<string, string>() : chapterEquationLatex(chapterBody);
+    return {
+      equations: new Map(
+        (equationsBySlug.get(slug) ?? []).map((equation) => [
+          equation.key,
+          { number: equation.number, ...(latex.has(equation.key) ? { latex: latex.get(equation.key) } : {}) },
+        ]),
+      ),
+      figures: floatNumbers(figuresBySlug.get(slug)),
+      tables: floatNumbers(tablesBySlug.get(slug)),
+      diagrams: floatNumbers(diagramsBySlug.get(slug)),
+    };
+  };
+  const outcomesOf = (lessonId: string): string[] =>
+    (lessonMetaById.get(lessonId)?.teaches ?? []).flatMap((id) => {
+      const outcome = outcomeById.get(id);
+      return outcome ? [outcome] : [];
+    });
+  // Each part with a deck: its chapters in reading order, what each numbers
+  // and teaches; its slides-first lessons, which no section can cover.
+  const deckParts = new Map<string, DeckPartFacts>(
+    partDeckFiles.map((deck) => {
+      const part = manifestParts.find((entry) => entry.dir === deck.partDir);
+      const lessonIds = part?.lessons ?? [];
+      const nameOf = (lessonId: string) => lessonId.replace(/\./g, '/').slice(deck.partDir.length + 1);
+      return [
+        deck.partDir,
+        {
+          label: part?.label ?? deck.partDir,
+          chapters: lessonIds.filter(isChapter).map((lessonId) => ({
+            name: nameOf(lessonId),
+            slug: lessonId.replace(/\./g, '/'),
+            teaches: lessonMetaById.get(lessonId)?.teaches ?? [],
+            outcomes: outcomesOf(lessonId),
+            floats: chapterFloatsOf(lessonId),
+          })),
+          slidesFirst: lessonIds.filter((lessonId) => !isChapter(lessonId)).map(nameOf),
+        },
+      ];
+    }),
+  );
+  const deckModel = buildDecks({
+    decks: deckFiles,
+    settings: deckSettings,
+    rules: {
+      maxWords: rules.number('D2', 'maxWords'),
+      maxBullets: rules.number('D2', 'maxBullets'),
+      maxTitleLength: rules.number('D5', 'maxLength'),
+      maxSteps: rules.number('D6', 'maxSteps'),
+      maxNewSymbols: rules.number('D9', 'maxNewSymbols'),
+    },
+    lessons: new Map(
+      lessonDeckFiles.map((deck) => [
+        deck.lessonId,
+        {
+          title: frontmatterById.get(deck.lessonId)?.title ?? deck.lessonId,
+          teaches: lessonMetaById.get(deck.lessonId)?.teaches ?? [],
+          outcomes: outcomesOf(deck.lessonId),
+          ...(deck.chapterPath === undefined ? {} : { chapterFloats: chapterFloatsOf(deck.lessonId) }),
+        },
+      ]),
+    ),
+    parts: deckParts,
+    // As the title frame shows them (`titleFrameNode` in `deck-remark.mjs`).
+    course: {
+      name: courseConfig.about.materialName ?? courseConfig.title,
+      authors: courseConfig.about.authors.map((author) => author.name),
+    },
+    scopeOf: (pageId) => {
+      const page = pageInputById.get(pageId);
+      return page === undefined ? [] : pageScope(page, cardsByKey);
+    },
+    suspendedOf: (pageId) => {
+      const page = pageInputById.get(pageId);
+      return page === undefined ? [] : suspendedOperators(page);
+    },
+    labelFor: termLabel,
+  });
+  mathIssues.push(...deckModel.diagnostics);
+  // The part's deck and each chapter's section of it, as the decks number their frames.
+  const sidebarWithFrames = withPartDeckFrames(sidebar, deckModel.decks);
+
+  // Per-place waivers: drop the located findings each one covers, and
+  // report the waivers themselves — a stale one is a warning, a bad one an
+  // error. Chapters, decks and non-chapter pages are scanned alike, since the
+  // text and math gates run on all of them; S2 and S10 are per-file or
+  // locked, so no waiver reaches them. Applied once every located finding is
+  // in, the deck rules' included.
+  const waiverDiagnostics: WaiverDiagnostic[] = [];
+  const waiverRules = { courseRules: rules.course };
+  const waivers = withPages.lessons.flatMap((lesson) => {
+    const collected = collectWaivers(lesson, waiverRules);
+    waiverDiagnostics.push(...collected.diagnostics);
+    return collected.waivers;
+  });
+  const waived = applyWaivers(mathIssues, waivers, waiverRules);
+  mathIssues.splice(0, mathIssues.length, ...waived.kept);
+  waiverDiagnostics.push(...waived.unused);
+
+  // Each lesson gets its `since` below, once every page's inputs are known.
+  const lessons: Omit<ManifestLesson, 'since'>[] = [];
   for (const notationLesson of notationInput.lessons) {
     const id = notationLesson.lessonId;
     const meta = lessonMetaById.get(id);
@@ -1717,6 +2050,10 @@ export async function compileManifest(
     lessons.push({
       id,
       slug: id.replace(/\./g, '/'),
+      editions: [
+        ...(isChapter(id) ? (['chapter'] as const) : []),
+        ...(lessonDeckFiles.some((deck) => deck.lessonId === id) ? (['deck'] as const) : []),
+      ],
       // 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.
@@ -1836,6 +2173,127 @@ export async function compileManifest(
     file: relative(REPOSITORY_ROOT, knowledgeChangelogPath).replace(/\\/g, '/'),
   });
 
+  // Each chapter's and part page's own version (rule C5): the committed
+  // `content/versions.json`, brought to the pages' inputs as they are now —
+  // the page's file, its checks and assessments, the shared notation entries
+  // it uses, the sources it cites, and its numbers. With C5 off, nothing is
+  // read or tracked and every page carries the course's version.
+  const trackPageVersions = !rules.disabled.includes('C5');
+  const previousVersions = trackPageVersions
+    ? readPageVersions(join(CONTENT_ROOT, 'versions.json'), PAGE_VERSIONS_FILE)
+    : { record: undefined, diagnostics: [] };
+  const digestOf = (file: string): string => hashes.content[file] ?? 'missing';
+  const presentFiles = (files: readonly string[]) => files.filter((file) => hashes.content[file] !== undefined);
+  const sourceFileById = new Map<string, string>();
+  for (const record of contentRecords) {
+    const file = record.file.replace(/\\/g, '/');
+    if (file.startsWith('content/sources/') && typeof record.data.id === 'string') {
+      sourceFileById.set(record.data.id, file);
+    }
+  }
+  const sharedEntryInputs = (definitionIds: readonly string[]) =>
+    definitionIds.flatMap((definitionId) => {
+      const definition = definitionsById.get(definitionId);
+      return definition?.kind === 'shared'
+        ? [{ label: `notation ${definition.source.file}`, digest: digestOf(definition.source.file) }]
+        : [];
+    });
+  /** Each float a part's deck recalls, by ref, as its chapter numbers, captions and (an equation) writes it. */
+  const recalledFloatFacts = (recalledFrom: Readonly<Record<string, string>>) =>
+    Object.fromEntries(
+      Object.entries(recalledFrom).map(([ref, chapter]) => {
+        const [, prefix, key] = /^(eq|fig|tab|dia)-(.+)$/u.exec(ref) ?? [];
+        const floats =
+          prefix === 'eq'
+            ? equationsBySlug
+            : prefix === 'fig'
+              ? figuresBySlug
+              : prefix === 'tab'
+                ? tablesBySlug
+                : diagramsBySlug;
+        const float = floats.get(chapter)?.find((entry) => entry.key === key);
+        const latex = prefix === 'eq' ? chapterFloatsOf(chapter.replace(/\//g, '.')).equations.get(key ?? '')?.latex : undefined;
+        return [ref, { chapter, ...float, ...(latex === undefined ? {} : { latex }) }];
+      }),
+    );
+  const trackedPages = [
+    ...lessons.map((lesson) => ({
+      slug: lesson.slug,
+      source: pageSourceDigest(
+        [
+          { label: `page ${lesson.file}`, digest: digestOf(lesson.file) },
+          ...presentFiles([lesson.file.replace(/\.mdx?$/u, '.checks.yml')]).map((file) => ({
+            label: `checks ${file}`,
+            digest: digestOf(file),
+          })),
+          ...presentFiles(lesson.assessments.map((id) => `content/assessments/${id}.json`)).map((file) => ({
+            label: `assessment ${file}`,
+            digest: digestOf(file),
+          })),
+          ...sharedEntryInputs(lesson.notation.definitionIds),
+          ...lesson.sources.map((id) => {
+            const file = sourceFileById.get(id);
+            return { label: `source ${id}`, digest: file === undefined ? 'missing' : digestOf(file) };
+          }),
+        ],
+        { part: lesson.part, chapter: lesson.chapter, numbering: lesson.numbering },
+      ),
+    })),
+    // A deck beside its chapter has a version of its own, by its route, and
+    // so has a part's deck; a slides-first lesson's deck is the lesson, above.
+    ...deckModel.decks.flatMap((deck) => {
+      if (deck.chapter === undefined && deck.part === undefined) return [];
+      const page = deckPages.find((entry) => entry.deck.route === deck.slug);
+      return [
+        {
+          slug: deck.slug,
+          source: pageSourceDigest(
+            [
+              { label: `page ${deck.file}`, digest: digestOf(deck.file) },
+              ...sharedEntryInputs(bundlesByLesson.get(deck.pageId)?.definitionIds ?? []),
+              ...(page === undefined ? [] : deriveSources(page.notation.body)).map((id) => {
+                const file = sourceFileById.get(id);
+                return { label: `source ${id}`, digest: file === undefined ? 'missing' : digestOf(file) };
+              }),
+            ],
+            // A part's deck shows each float it recalls as its chapter
+            // numbers and captions it: those count as the page's too.
+            deck.recalledFrom === undefined ? {} : { recalls: recalledFloatFacts(deck.recalledFrom) },
+          ),
+        },
+      ];
+    }),
+    ...manifestParts.flatMap((part) => {
+      if (!part.overview) return [];
+      const slug = `${part.dir}/index`;
+      const page = pages.find((entry) => entry.slug === slug);
+      return [
+        {
+          slug,
+          source: pageSourceDigest([
+            { label: `page ${part.overview.file}`, digest: digestOf(part.overview.file) },
+            ...sharedEntryInputs(page?.notation.definitionIds ?? []),
+          ]),
+        },
+      ];
+    }),
+  ];
+  const pageVersionsRecord = nextPageVersions({
+    previous: previousVersions.record,
+    version: knowledge.version,
+    unreleased: knowledge.unreleased.length > 0,
+    pages: trackedPages,
+  });
+  const pageVersions: ManifestPageVersions = {
+    enabled: trackPageVersions,
+    file: PAGE_VERSIONS_FILE,
+    record: pageVersionsRecord,
+  };
+  const sinceOfPage = (slug: string): string | null => {
+    const entry = pageVersionsRecord.pages[slug];
+    return trackPageVersions && entry !== undefined ? sinceOf(entry) : knowledge.version;
+  };
+
   const enginePkg = readEnginePackage();
   const about: ManifestAbout = {
     engine: {
@@ -1855,6 +2313,11 @@ export async function compileManifest(
         ? {}
         : { date: knowledge.latest.date }),
       notes: knowledge.latest?.notes ?? [],
+      releases: knowledge.entries.map((entry) => ({
+        version: entry.version,
+        ...(entry.date === undefined ? {} : { date: entry.date }),
+      })),
+      unreleased: knowledge.unreleased.length > 0,
       contentTree: hashes.contentTree,
     },
     authors: courseConfig.about.authors.map((author) => ({
@@ -1867,6 +2330,37 @@ export async function compileManifest(
       : { changelogHref: courseConfig.about.changelogHref }),
   };
 
+  const lessonsWithSince = lessons.map((lesson) => ({ ...lesson, since: sinceOfPage(lesson.slug) }));
+  const decksWithSince = deckModel.decks.map((deck) => {
+    const page = pageInputById.get(deck.pageId);
+    return {
+      ...deck,
+      since: sinceOfPage(deck.slug),
+      notation: lessonNotationBundle(
+        bundlesByLesson.get(deck.pageId),
+        definitionsById,
+        page === undefined ? [] : lessonNotationResolution(page, definitionsById, availableDefinitionIds),
+        cardsByKey,
+        // A deck shows its lessons' symbols: the derived cards (rule N23)
+        // its chapters' bodies and checks use ship with it, as its bundle
+        // holds the chapters' entries.
+        [
+          ...(indexGate.derivedByLesson.get(deck.pageId) ?? []),
+          ...(page?.scopeLessonIds ?? []).flatMap((lessonId) => [
+            ...(indexGate.derivedByLesson.get(lessonId) ?? []),
+            ...(assessmentDerived.get(lessonId)?.values() ?? []),
+          ]),
+        ].filter((use, index, all) => all.findIndex((other) => other.key === use.key) === index),
+      ),
+    };
+  });
+  // Rule D11: a lesson's own deck whose chapter changed after the deck did.
+  // `since` is only known this late, so this runs after `mathIssues` (D1–D10's
+  // frame codes) is already waived; pushed in after, it joins `diagnostics.math`
+  // the same way, just outside the waiver pass — not a per-place finding to waive.
+  const chapterSince = new Map(lessonsWithSince.map((lesson) => [lesson.slug, lesson.since] as const));
+  mathIssues.push(...deckStaleDiagnostics(decksWithSince, chapterSince));
+
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
     lessonExports: normalizeLessonExports(courseConfig),
@@ -1874,6 +2368,12 @@ export async function compileManifest(
     numbering: numberingSettings,
     blockLabels,
     cards: normalizeCards(courseConfig),
+    sidebarMarks: normalizeSidebarMarks(courseConfig),
+    sidebarEditions: normalizeSidebarEditions(courseConfig),
+    readingMemory: normalizeReadingMemory(courseConfig),
+    appearance: normalizeAppearance(courseConfig),
+    deck: deckSettings,
+    decks: decksWithSince,
     about,
     notation: {
       definitions: registry.definitions,
@@ -1886,9 +2386,14 @@ export async function compileManifest(
     sources,
     tracks,
     abbreviations,
-    sidebar,
-    parts: manifestParts,
-    lessons,
+    sidebar: sidebarWithFrames,
+    parts: manifestParts.map(({ overview, ...part }) =>
+      overview
+        ? { ...part, overview: { ...overview, since: sinceOfPage(`${part.dir}/index`) } }
+        : part,
+    ),
+    lessons: lessonsWithSince,
+    pageVersions,
     pages,
     prereqEdges,
     equations: {
@@ -1930,7 +2435,7 @@ export async function compileManifest(
       checks: dropDisabled(checkValidation.diagnostics, off),
       examples: dropDisabled(exampleValidation.diagnostics, off),
       folds: dropDisabled(foldValidation.diagnostics, off),
-      knowledge: dropDisabled(knowledge.diagnostics, off),
+      knowledge: dropDisabled([...knowledge.diagnostics, ...previousVersions.diagnostics], off),
       rawFloats: dropDisabled(rawFloatDiagnostics, off),
       config: rules.diagnostics,
       waivers: waiverDiagnostics,