explico 0.13.0 → 0.14.0

package/src/rules/catalog.ts

@@ -28,6 +28,7 @@
 
 /** The part of a page a rule is about. The first tag on an entry is primary. */
 export type Element =
+  | 'slide'
   | 'prose'
   | 'math'
   | 'equation'
@@ -43,6 +44,7 @@ export type Element =
 
 /** Every element, in the order the rules-in-effect page lists them. */
 export const ELEMENTS: readonly Element[] = [
+  'slide',
   'prose',
   'math',
   'equation',
@@ -58,10 +60,20 @@ export const ELEMENTS: readonly Element[] = [
 ];
 
 /**
- * The five areas the engine ships, plus `X` — reserved for a course's own rules
+ * The six areas the engine ships, plus `X` — reserved for a course's own rules
  * and never used by an engine rule (see {@link CourseRuleId}).
  */
-export type RuleArea = 'N' | 'V' | 'C' | 'S' | 'P' | 'X';
+export type RuleArea = 'N' | 'V' | 'C' | 'S' | 'P' | 'D' | 'X';
+
+/**
+ * Which edition of a lesson a rule is about (`docs/authoring/deck.md`): its
+ * chapter, its deck (`<lesson>.deck.mdx`), or `both`. A rule without one is
+ * `both`. The rules-in-effect page is written per edition, so an author of
+ * either reads one list: a chapter-only rule is off on a deck, where a `D`
+ * rule says the same thing about a frame.
+ */
+export type Edition = 'chapter' | 'deck';
+export type Editions = Edition | 'both';
 export type RuleId = `${RuleArea}${number}`;
 
 /**
@@ -145,6 +157,8 @@ export interface RuleEntry {
    * absent means "shipped with the engine".
    */
   readonly source?: 'course';
+  /** The edition the rule is about; absent is `both` ({@link Editions}). */
+  readonly editions?: Editions;
 }
 
 export interface InvariantEntry {
@@ -156,10 +170,18 @@ export interface InvariantEntry {
   readonly doc: string;
   readonly summary: string;
   readonly checks: readonly [RuleCheck, ...RuleCheck[]];
+  /** The edition the invariant is about; absent is `both` ({@link Editions}). */
+  readonly editions?: Editions;
 }
 
 export type CatalogEntry = RuleEntry | InvariantEntry;
 
+/** True when `entry` is in force for `edition` ({@link Editions}). */
+export function appliesTo(entry: { readonly editions?: Editions }, edition: Edition): boolean {
+  const editions = entry.editions ?? 'both';
+  return editions === 'both' || editions === edition;
+}
+
 export type Enforcement = 'script' | 'partial' | 'guide';
 
 // --- emitters ------------------------------------------------------------
@@ -169,6 +191,7 @@ const GLYPHS: Emitter = { module: 'src/reference/math-glyphs.mjs', fn: 'resolveM
 const REGISTRY: Emitter = { module: 'src/reference/registry.ts', fn: 'buildNotationRegistry' };
 const KEYED_FLOATS: Emitter = { module: 'src/reference/keyed-float-validate.ts', fn: 'validateKeyedFloats' };
 const INDICES: Emitter = { module: 'src/reference/gate-indices.ts', fn: 'gateIndices' };
+const DECKS: Emitter = { module: 'src/reference/decks-validate.ts', fn: 'validateDecks' };
 
 function consistency(fn: string): Emitter {
   return { module: 'src/reference/consistency.ts', fn };
@@ -334,12 +357,14 @@ const RULES: readonly RuleEntry[] = [
     elements: ['math', 'notation'],
     doc: 'notation.md#n4',
     summary:
-      'Every glyph in rendered math resolves to exactly one notation entry on the page: introduce it with `[[key]]` in prose before its first `$…$`, define a page-local one in `notation.local`, or bind a compound with `\\explain{key}{latex}`. Do not reuse a glyph for a second meaning on the same page.',
+      'Every glyph in rendered math resolves to exactly one notation entry on the page: introduce it with `[[key]]` in prose before its first `$…$`, define a page-local one in `notation.local`, or bind a compound with `\\explain{key}{latex}`. Do not reuse a glyph for a second meaning on the same page. Declare a meaning once — a shared card unless the letter already means something else in the course, and only then `notation.local` or a gloss — and reference it everywhere else.',
     checks: [
       check('unresolved-glyph', 'error', true, GATE_MATH),
       check('glyph-unique-in-corpus', 'warning', false, consistency('checkGlyphUniqueness')),
       check('weak-local', 'info', false, consistency('checkWeakLocal')),
-      check('gloss-wants-promoting', 'info', false, consistency('checkGlossWantsPromoting')),
+      check('definition-repeated', 'warning', false, consistency('checkDefinitionRepeated')),
+      check('meaning-repeated', 'info', false, consistency('checkMeaningRepeated')),
+      check('explain-redundant', 'info', true, GATE_MATH),
       check('card-wants-demoting', 'info', false, consistency('checkCardWantsDemoting')),
     ],
     locked:
@@ -729,6 +754,8 @@ const RULES: readonly RuleEntry[] = [
   {
     kind: 'rule',
     id: 'V7',
+    // Chapter-only: on a deck, rule D2 (a frame fits its canvas) says it of a frame.
+    editions: 'chapter',
     short: 'A figure’s picture fits on one screen',
     title: 'A figure’s picture takes at most `maxPercent` of the screen height.',
     elements: ['plot'],
@@ -755,6 +782,8 @@ const RULES: readonly RuleEntry[] = [
   {
     kind: 'rule',
     id: 'V8',
+    // Chapter-only: on a deck, rule D7 (a float is the frame) says it of a frame.
+    editions: 'chapter',
     short: 'A diagram fits the lesson column',
     title: 'A diagram is no wider than the lesson column.',
     elements: ['diagram'],
@@ -829,11 +858,36 @@ const RULES: readonly RuleEntry[] = [
     unchecked:
       'that the two edits landed in one commit — the build only ever sees the end state, so a release split across commits warns until the second half lands.',
   },
+  {
+    kind: 'rule',
+    id: 'C5',
+    short: 'Each chapter and part page carries the release its content last changed in; `content/versions.json` is generated and committed',
+    title:
+      'Each chapter and part page carries the knowledge version its content last changed in, kept in `content/versions.json`, which `validate:content` writes and the course commits with the change.',
+    elements: ['changelog'],
+    doc: 'versioning.md#c5',
+    summary:
+      'A page’s PDF, Markdown and `[?]` panel say "unchanged since version 0.2.0", the release its content last changed in, or "with changes after version 0.4.0, not yet released" while `## [Unreleased]` holds its change. The record is `content/versions.json`: `validate:content` works it out from the committed file and the content, writes it on a developer’s machine, and in CI fails when the committed file is not the one it would write. Never edit it by hand; commit what `validate:content` wrote with the content change, and with a release.',
+    checks: [
+      check('page-versions-stale', 'error', false, {
+        module: 'src/compiler/page-versions.ts',
+        fn: 'syncPageVersions',
+      }),
+      check('page-versions-invalid', 'warning', false, {
+        module: 'src/compiler/page-versions.ts',
+        fn: 'readPageVersions',
+      }),
+    ],
+    unchecked:
+      'which bullet of `## [Unreleased]` belongs to which page — every page changed while there is any bullet counts as not yet released; and a change to a lab, `content/domain/` or a part’s label, which changes the page’s PDF without changing its version.',
+  },
 
   // ---- S — structure ----------------------------------------------------------
   {
     kind: 'rule',
     id: 'S1',
+    // Chapter-only: on a deck, rule D5 (a frame title fits one line) says it of a frame.
+    editions: 'chapter',
     short: 'No heading, short caption or short-note title over 65 characters',
     title:
       'No heading, no short caption (`short`, an equation’s `\\caption{}`) and no short-note title runs past 65 characters.',
@@ -945,6 +999,8 @@ const RULES: readonly RuleEntry[] = [
   {
     kind: 'rule',
     id: 'S6',
+    // Chapter-only: on a deck, rule D1 (sections of frames) says it of a frame.
+    editions: 'chapter',
     short: 'Headings descend one level at a time, from `##`',
     title:
       'Headings descend one level at a time: a lesson body starts at `##` and never skips a level on the way down.',
@@ -968,6 +1024,8 @@ const RULES: readonly RuleEntry[] = [
   {
     kind: 'rule',
     id: 'S7',
+    // Chapter-only: on a deck, rule D1 (sections of frames) says it of a frame.
+    editions: 'chapter',
     short: 'A heading is followed by body content, never by another heading',
     title: 'A heading is followed by body content, never directly by another heading.',
     elements: ['heading'],
@@ -1135,6 +1193,179 @@ const RULES: readonly RuleEntry[] = [
       'The sentence before a display equation names the quantity it yields and the step or law it follows from — not “we have:”.',
     checks: [],
   },
+  // ---- D — decks --------------------------------------------------------------
+  {
+    kind: 'rule',
+    id: 'D1',
+    editions: 'deck',
+    short: 'A deck is sections of frames: `##` a section, `###` a frame',
+    title:
+      'A deck is sections of frames: `##` opens a section, `###` is a frame, and nothing is deeper or outside a frame.',
+    elements: ['slide', 'heading'],
+    doc: 'deck.md#d1',
+    summary:
+      'In a `<lesson>.deck.mdx`, `##` opens a section, a divider frame that shows only its title, and `###` is a frame whose title is the heading. Write every line of content inside a `###` frame: no `#`, no `####` or deeper, nothing before the first heading and nothing between a `##` and its first `###`.',
+    checks: [
+      check('frame-depth', 'error', true, DECKS),
+      check('deck-loose-content', 'error', true, DECKS),
+      check('deck-empty', 'error', false, DECKS),
+    ],
+    locked:
+      'a frame is the unit the deck page, Present mode and the PDF are built from — content outside one has no frame to show in.',
+  },
+  {
+    kind: 'rule',
+    id: 'D2',
+    editions: 'deck',
+    short: 'A frame fits its canvas in every step',
+    title: 'A frame fits its canvas in every step, and never continues on the next frame.',
+    elements: ['slide'],
+    doc: 'deck.md#d2',
+    summary:
+      'Everything a frame shows — title, body, legend line, at its last step — fits the course’s canvas (`deck.aspectRatio`). `content check` warns when a frame passes `maxWords` words or `maxBullets` list items. A frame that does not fit is two frames; never shrink its type.',
+    checks: [
+      check('frame-dense', 'warning', true, DECKS),
+      check('frame-overflow', 'error', false, { module: 'src/compiler/exports/deck-fit.ts', fn: 'checkFrameFit' }),
+    ],
+    unchecked:
+      'the paper: a frame that fits its canvas on the web can still run over in the PDF, which the export reports as a warning naming the frame.',
+    settings: [
+      {
+        key: 'maxWords',
+        title: 'Most words on a frame',
+        description: 'Words a frame may show (its prose, not its math or notes) before `content check` warns.',
+        schema: { type: 'integer', minimum: 10, default: 70 },
+      },
+      {
+        key: 'maxBullets',
+        title: 'Most list items on a frame',
+        description: 'List items a frame may show before `content check` warns.',
+        schema: { type: 'integer', minimum: 1, default: 7 },
+      },
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'D3',
+    editions: 'deck',
+    short: 'A frame makes one claim, and its title states it',
+    title: 'A frame makes one claim, and its title states the claim.',
+    elements: ['slide', 'prose'],
+    doc: 'deck.md#d3',
+    summary:
+      'Title a frame with the sentence it shows to be true — “Range is largest at a 45° launch angle”, not “Range”. Everything on the frame serves that one claim; a second claim is a second frame.',
+    checks: [],
+  },
+  {
+    kind: 'rule',
+    id: 'D4',
+    editions: 'deck',
+    short: 'A frame with text carries speaker notes',
+    title: 'A frame with text carries speaker notes: the argument is in `<Notes>`, the frame shows its claims.',
+    elements: ['slide', 'prose'],
+    doc: 'deck.md#d4',
+    summary:
+      'A `###` frame whose body has words carries a `<Notes>…</Notes>` block with what the speaker says: the reasoning, the transitions, the question to ask the room. A frame that shows only a picture, an equation or a question needs none. The prose rules hold for the notes.',
+    checks: [check('frame-notes-missing', 'warning', true, DECKS)],
+  },
+  {
+    kind: 'rule',
+    id: 'D5',
+    editions: 'deck',
+    short: 'A frame title fits one line',
+    title: 'A frame title fits one line: at most `maxLength` characters.',
+    elements: ['slide', 'heading'],
+    doc: 'deck.md#d5',
+    summary:
+      'A `##` or `###` heading in a deck runs to at most `maxLength` characters as the reader sees it (math as it reads, a `[[key]]` term as its label), so it stays on one line of the canvas. Move the rest into the frame.',
+    checks: [check('frame-title-length', 'error', true, DECKS)],
+    settings: [
+      {
+        key: 'maxLength',
+        title: 'Longest frame title',
+        description: 'Characters a frame or section title may run to.',
+        schema: { type: 'integer', minimum: 10, default: 50 },
+      },
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'D6',
+    editions: 'deck',
+    short: 'A frame shows in at most `maxSteps` steps, each adding to the last',
+    title: 'A frame shows in at most `maxSteps` steps, and each step adds to what is shown.',
+    elements: ['slide'],
+    doc: 'deck.md#d6',
+    summary:
+      '`<Pause />` is the one step mark: what follows it appears on the next key press, and nothing shown earlier changes or goes, so the last step is the whole frame — what the scroll view, the print and the PDF show. Keep to `maxSteps` steps; more is a second frame.',
+    checks: [check('frame-steps', 'warning', true, DECKS)],
+    unchecked: 'that a later step contradicts nothing already shown.',
+    settings: [
+      {
+        key: 'maxSteps',
+        title: 'Most steps in a frame',
+        description: 'Steps a frame may show in (one more than its `<Pause />` marks).',
+        schema: { type: 'integer', minimum: 1, default: 4 },
+      },
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'D7',
+    editions: 'deck',
+    short: 'A frame holds one figure, table or diagram',
+    title: 'A frame holds at most one figure, table or diagram, and it is the frame’s picture.',
+    elements: ['slide', 'plot', 'table', 'diagram'],
+    doc: 'deck.md#d7',
+    summary:
+      'One `<Figure>`, `<Table>`, `<Diagram>` or recalled float per frame, laid out at the canvas width; a lab’s controls are the frame’s tools, live in Present mode. A second picture is a second frame.',
+    checks: [check('frame-floats', 'warning', true, DECKS)],
+  },
+  {
+    kind: 'rule',
+    id: 'D8',
+    editions: 'deck',
+    short: 'Recall a chapter’s result; never retype it',
+    title:
+      'A result the chapter numbers is recalled with `<Recall>`, never retyped; the deck’s own floats carry no number.',
+    elements: ['slide', 'equation'],
+    doc: 'deck.md#d8',
+    summary:
+      'Show the chapter’s equation, figure, table or diagram with `<Recall ref="eq-range" />` (`fig-`, `tab-`, `dia-`): it renders as in the chapter, with the chapter’s number, and links back to it. A display equation retyped from the chapter is a warning. An equation the deck labels itself numbers (1), (2) within the deck; the deck’s figures, tables and diagrams are unnumbered.',
+    checks: [check('frame-retyped', 'warning', true, DECKS)],
+  },
+  {
+    kind: 'rule',
+    id: 'D9',
+    editions: 'deck',
+    short: 'A frame introduces at most `maxNewSymbols` symbols',
+    title: 'A frame introduces at most `maxNewSymbols` symbols the deck has not shown before.',
+    elements: ['slide', 'math', 'notation'],
+    doc: 'deck.md#d9',
+    summary:
+      'The room reads a frame once. Count the symbols it shows for the first time in the deck and keep them to `maxNewSymbols`; the legend line under the frame names them. More than that is a frame of its own.',
+    checks: [check('frame-new-symbols', 'info', true, DECKS)],
+    settings: [
+      {
+        key: 'maxNewSymbols',
+        title: 'Most new symbols on a frame',
+        description: 'Symbols a frame may show for the first time in its deck.',
+        schema: { type: 'integer', minimum: 1, default: 4 },
+      },
+    ],
+  },
+  {
+    kind: 'rule',
+    id: 'D10',
+    editions: 'deck',
+    short: 'A deck opens on its title and closes on what the student can now do',
+    title: 'A deck opens on its title frame and closes on what the student can now do.',
+    elements: ['slide'],
+    doc: 'deck.md#d10',
+    summary:
+      'The title frame (the lesson, the course, its authors and version) and the closing frame (the outcomes of the competencies the lesson teaches, `deck.outcomesFrame`) are generated: do not write them. With `deck.outcomesFrame` off, end on a `###` frame that says what the student can now do.',
+    checks: [],
+  },
 ];
 
 /**
@@ -1424,6 +1655,28 @@ const INVARIANTS: readonly InvariantEntry[] = [
       }),
     ],
   },
+  {
+    kind: 'invariant',
+    id: 'decks',
+    editions: 'deck',
+    title: 'A deck belongs to a lesson or a part, and recalls what its chapters number.',
+    elements: ['slide'],
+    doc: 'deck.md#the-deck-file',
+    summary:
+      'A deck is `content/docs/<part>/<lesson>.deck.mdx`, or a part’s `content/docs/<part>/index.deck.mdx`. Beside a chapter, and as a part’s, it sets only `title` and `description` — the chapter holds the lesson’s `teaches`, `assumptions`, `studyMinutes` and `notation`; alone, it is the lesson and carries them. On a part’s deck, `## Title [chapter: <name>]` names the chapter a section covers: a chapter of the part, once, and only on a `##` of a part’s deck. `<Recall ref>` names an equation, figure, table or diagram of the deck’s own chapter, or of a chapter a part’s deck covers; `<AssessmentSet>` on a part’s deck sits in a section that names a chapter; `<Pause>` takes only `control`, `from`, `to`, `seconds` (a driven figure) or `highlight` (a spotlight).',
+    checks: [
+      check('deck-frontmatter', 'error', false, DECKS),
+      check('deck-outside-part', 'error', false, DECKS),
+      check('recall-unresolved', 'error', true, DECKS),
+      check('pause-invalid', 'error', true, DECKS),
+      check('deck-chapter-unknown', 'error', true, DECKS),
+      check('deck-chapter-repeated', 'error', true, DECKS),
+      check('deck-chapter-outside-part', 'error', true, DECKS),
+      check('deck-marker-misplaced', 'error', true, DECKS),
+      check('deck-check-no-chapter', 'error', true, DECKS),
+      check('deck-route-taken', 'error', false, DECKS),
+    ],
+  },
 ];
 
 export const CATALOG: readonly CatalogEntry[] = [...RULES, ...INVARIANTS];

package/src/rules/course-rules.ts

@@ -42,6 +42,7 @@ import {
   type Element,
   type RuleCheck,
   type RuleEntry,
+  type Editions,
 } from './catalog';
 
 /** Where a `forbid` pattern is matched. */
@@ -77,6 +78,8 @@ export interface CourseRuleInput {
   readonly forbid?: readonly CourseRulePatternInput[];
   readonly unchecked?: string;
   readonly doc?: string;
+  /** `chapter`, `deck` or `both` (the default): the edition of a lesson the rule is about. */
+  readonly editions?: string;
 }
 
 /** `CourseConfig.courseRules` — an array, so the settings form can add and remove one. */
@@ -100,6 +103,8 @@ export interface CourseRule {
   readonly forbid: readonly CourseRulePattern[];
   readonly unchecked?: string;
   readonly doc?: string;
+  /** The edition of a lesson the rule is about (`docs/authoring/deck.md`). */
+  readonly editions: Editions;
 }
 
 /**
@@ -225,7 +230,7 @@ export function resolveCourseRules(config: {
       );
     }
     const raw = input as Record<string, unknown>;
-    const known = ['id', 'title', 'summary', 'elements', 'enabled', 'severity', 'forbid', 'unchecked', 'doc'];
+    const known = ['id', 'title', 'summary', 'elements', 'enabled', 'severity', 'forbid', 'unchecked', 'doc', 'editions'];
     for (const key of Object.keys(raw)) {
       if (!known.includes(key)) {
         throw new Error(`${at(index)}: unknown key \`${key}\`. Takes: ${known.join(', ')}.`);
@@ -259,6 +264,11 @@ export function resolveCourseRules(config: {
         `${where}.severity must be "error" or "warning"; received ${describe(raw.severity)}.`,
       );
     }
+    if (raw.editions !== undefined && raw.editions !== 'both' && raw.editions !== 'chapter' && raw.editions !== 'deck') {
+      throw new Error(
+        `${where}.editions must be "both", "chapter" or "deck"; received ${describe(raw.editions)}.`,
+      );
+    }
     const forbidInput = raw.forbid;
     if (forbidInput !== undefined && !Array.isArray(forbidInput)) {
       throw new Error(`${where}.forbid must be an array of patterns; received ${describe(forbidInput)}.`);
@@ -283,6 +293,7 @@ export function resolveCourseRules(config: {
       forbid,
       ...(raw.unchecked === undefined ? {} : { unchecked: requireString(raw.unchecked, `${where}.unchecked`) }),
       ...(raw.doc === undefined ? {} : { doc: requireString(raw.doc, `${where}.doc`) }),
+      editions: (raw.editions as Editions | undefined) ?? 'both',
     });
   });
 
@@ -319,6 +330,7 @@ export function courseRuleEntry(rule: CourseRule): RuleEntry {
     checks,
     ...(rule.unchecked === undefined ? {} : { unchecked: rule.unchecked }),
     source: 'course',
+    ...(rule.editions === 'both' ? {} : { editions: rule.editions }),
   };
 }
 
@@ -377,6 +389,14 @@ export function courseRulesJsonSchema(): JsonSchema {
           default: ['prose'],
           items: { title: 'Element', type: 'string', enum: [...ELEMENTS] },
         },
+        editions: {
+          title: 'Editions',
+          description:
+            'The edition of a lesson the rule is about: its chapter, its deck (`<lesson>.deck.mdx`), or both. A rule about one edition is checked there only, and listed on that edition’s rules-in-effect page.',
+          type: 'string',
+          enum: ['both', 'chapter', 'deck'],
+          default: 'both',
+        },
         enabled: {
           title: 'Enabled',
           description:

package/src/rules/in-effect.ts

@@ -11,15 +11,24 @@
  * `pnpm validate:content` writes it to `build/rules-in-effect.md` (git-ignored,
  * like the manifest — regenerated every run); `pnpm content rules` prints it,
  * optionally filtered to an element or an enforcement kind.
+ *
+ * The page is per edition of a lesson (`docs/authoring/deck.md`): the default
+ * is the chapter's, which lists no deck rule, so a course without decks reads
+ * the page it always did. A course with decks also gets
+ * `build/rules-in-effect-deck.md` (`content rules --edition deck`), where the
+ * `D` rules lead and a chapter-only rule is listed as such.
  */
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import {
   ELEMENTS,
+  appliesTo,
   enforcementOf,
   invariants,
   rules as catalogRules,
   type CatalogEntry,
+  type Edition,
+  type Editions,
   type Element,
   type Enforcement,
   type RuleEntry,
@@ -36,12 +45,16 @@ export interface RulesInEffectInput {
     readonly material: { readonly name: string };
     readonly knowledge: { readonly version: string };
   };
+  /** The course's decks (`manifest.decks`): with any, the deck page is written too. */
+  readonly decks?: readonly unknown[];
 }
 
 export interface RulesFilter {
   /** Keep a rule whose elements (any, not just primary) include one of these. */
   readonly elements?: readonly Element[];
   readonly enforcement?: Enforcement | 'locked';
+  /** The edition the page is for: `chapter` (the default) or `deck`. */
+  readonly edition?: Edition;
 }
 
 /** One rule as `content rules --json` reports it. */
@@ -60,6 +73,8 @@ export interface RuleInEffect {
   readonly settings: Readonly<Record<string, unknown>>;
   readonly summary: string;
   readonly doc: string;
+  /** The edition it is about: `chapter`, `deck`, or `both`. */
+  readonly editions: Editions;
 }
 
 /** Where a course's copy of the rule text lives, relative to `build/`. */
@@ -84,6 +99,7 @@ function enforcementLabel(entry: CatalogEntry): Enforcement | 'locked' {
 }
 
 function matches(entry: CatalogEntry, filter: RulesFilter): boolean {
+  if (!appliesTo(entry, filter.edition ?? 'chapter')) return false;
   if (filter.elements && !entry.elements.some((e) => filter.elements!.includes(e))) return false;
   if (filter.enforcement && enforcementLabel(entry) !== filter.enforcement) return false;
   return true;
@@ -105,6 +121,7 @@ export function rulesInEffect(input: RulesInEffectInput, filter: RulesFilter = {
     settings: entry.kind === 'rule' ? (input.rules.settings[entry.id] ?? {}) : {},
     summary: entry.summary,
     doc: docLink(entry),
+    editions: entry.editions ?? 'both',
   }));
 }
 
@@ -152,17 +169,29 @@ function ruleLine(rule: RuleEntry, settings: Readonly<Record<string, unknown>>):
  * the reader knows what was left out on purpose.
  */
 export function renderRulesInEffect(input: RulesInEffectInput, filter: RulesFilter = {}): string {
+  const edition = filter.edition ?? 'chapter';
   const off = new Set<string>(input.rules.disabled);
-  const on = liveRules(input).filter((r) => !off.has(r.id));
+  const live = liveRules(input).filter((r) => appliesTo(r, edition));
+  const on = live.filter((r) => !off.has(r.id));
+  const offHere = [...off].filter((id) => live.some((r) => r.id === id));
   const ours = on.filter((r) => r.source === 'course').length;
   const locked = on.filter((r) => r.locked !== undefined).map((r) => r.id);
   const filtered = filter.elements || filter.enforcement;
   const visible = on.filter((r) => matches(r, filter));
+  const editionInvariants = invariants().filter((i) => appliesTo(i, edition));
 
   const lines: string[] = [];
   lines.push(
-    `# Rules in effect — ${input.about.material.name} (knowledge ${input.about.knowledge.version}, ${input.about.engine.name} ${input.about.engine.version})`,
+    `# Rules in effect${edition === 'deck' ? ' for decks' : ''} — ${input.about.material.name} (knowledge ${input.about.knowledge.version}, ${input.about.engine.name} ${input.about.engine.version})`,
     '',
+    ...(edition === 'deck'
+      ? [
+          'For a lesson’s deck, `<lesson>.deck.mdx` (`docs/authoring/deck.md`): the `D` rules',
+          'lead, then every rule that holds for a deck as for a chapter. A chapter-only rule is',
+          'listed under "Chapter only" at the end; on a frame, a `D` rule says it instead.',
+          '',
+        ]
+      : []),
     'Generated by `pnpm validate:content` (and `pnpm content rules`) from the rule',
     'catalog and `rules` / `courseRules` in `course.settings.json`. Do not edit. Read this before',
     'drafting, and open a rule page only when it is listed here and you need the',
@@ -170,7 +199,7 @@ export function renderRulesInEffect(input: RulesInEffectInput, filter: RulesFilt
     'not exist, and is neither applied nor flagged in review.',
     '',
     `${on.length} rules on (${locked.length} locked${ours === 0 ? '' : `, ${ours} this course's own`}), ` +
-      `${off.size} off, ${invariants().length} invariants always on.` +
+      `${offHere.length} off, ${editionInvariants.length} invariants always on.` +
       (filtered
         ? ` Filtered: ${[
             filter.elements ? `element ${filter.elements.join(', ')}` : '',
@@ -200,7 +229,7 @@ export function renderRulesInEffect(input: RulesInEffectInput, filter: RulesFilt
     for (const rule of here) lines.push(ruleLine(rule, input.rules.settings[rule.id] ?? {}));
   }
 
-  const visibleInvariants = invariants().filter((i) => matches(i, filter));
+  const visibleInvariants = editionInvariants.filter((i) => matches(i, filter));
   lines.push('', '## Always on (invariants)', '');
   if (visibleInvariants.length === 0) {
     lines.push('- (none match the filter)');
@@ -214,22 +243,39 @@ export function renderRulesInEffect(input: RulesInEffectInput, filter: RulesFilt
 
   lines.push('', '## Off', '');
   lines.push(
-    off.size === 0
+    offHere.length === 0
       ? '- Nothing — every rule is on.'
-      : `- ${[...off].join(', ')} — turned off in \`course.settings.json\` (\`rules\`, or \`courseRules\` for an \`X\` rule). Do not apply them; do not flag them in review.`,
+      : `- ${offHere.join(', ')} — turned off in \`course.settings.json\` (\`rules\`, or \`courseRules\` for an \`X\` rule). Do not apply them; do not flag them in review.`,
   );
 
   lines.push('', '## Locked', '');
   lines.push(`- ${locked.join(', ')} — cannot be turned off; listed above under their element.`);
 
+  if (edition === 'deck') {
+    const chapterOnly = liveRules(input).filter((r) => !appliesTo(r, 'deck')).map((r) => r.id);
+    lines.push('', '## Chapter only', '');
+    lines.push(
+      chapterOnly.length === 0
+        ? '- Nothing — every rule holds for a deck too.'
+        : `- ${chapterOnly.join(', ')} — about a chapter’s page, not a frame. On a deck, neither apply them nor flag them; the \`D\` rules above say the same of a frame.`,
+    );
+  }
+
   return `${lines.join('\n')}\n`;
 }
 
-/** Write `build/rules-in-effect.md` under `root` (the course package). Returns the path. */
+/**
+ * Write `build/rules-in-effect.md` under `root` (the course package), and
+ * `build/rules-in-effect-deck.md` when the course has a deck (a stale one goes
+ * when it has none). Returns the chapter page's path.
+ */
 export function writeRulesInEffect(input: RulesInEffectInput, root = process.cwd()): string {
   const dir = join(root, 'build');
   mkdirSync(dir, { recursive: true });
   const path = join(dir, 'rules-in-effect.md');
   writeFileSync(path, renderRulesInEffect(input));
+  const deckPath = join(dir, 'rules-in-effect-deck.md');
+  if ((input.decks?.length ?? 0) > 0) writeFileSync(deckPath, renderRulesInEffect(input, { edition: 'deck' }));
+  else if (existsSync(deckPath)) rmSync(deckPath);
   return path;
 }

package/src/session/PreferenceStore.ts

@@ -23,6 +23,12 @@ export interface PreferenceStore {
    * fits; a caller without it writes an empty value instead.
    */
   remove?(key: string): void;
+  /**
+   * Every key the store holds. Optional like `remove`; the reading-memory
+   * question (`reading-memory.ts`) uses it to forget a course's per-page
+   * entries, whose names it cannot list otherwise.
+   */
+  keys?(): string[];
 }
 
 /**
@@ -53,6 +59,14 @@ export function createBrowserPreferenceStore(): PreferenceStore {
         // Storage unavailable — there is nothing stored to forget.
       }
     },
+    keys() {
+      try {
+        const storage = window.localStorage;
+        return Array.from({ length: storage.length }, (_, index) => storage.key(index) ?? '').filter(Boolean);
+      } catch {
+        return [];
+      }
+    },
   };
 }
 
@@ -83,6 +97,14 @@ export function createSessionPreferenceStore(): PreferenceStore {
         // Storage unavailable — there is nothing stored to forget.
       }
     },
+    keys() {
+      try {
+        const storage = window.sessionStorage;
+        return Array.from({ length: storage.length }, (_, index) => storage.key(index) ?? '').filter(Boolean);
+      } catch {
+        return [];
+      }
+    },
   };
 }
 
@@ -118,5 +140,6 @@ export function createMemoryPreferenceStore(): PreferenceStore {
     remove: (key) => {
       map.delete(key);
     },
+    keys: () => [...map.keys()],
   };
 }