explico 0.13.1 → 0.15.0

package/dist/session/reading-memory.d.ts

@@ -0,0 +1,96 @@
+import { PreferenceStore } from './PreferenceStore.js';
+
+/**
+ * The one question explico asks a reader: may this course remember their
+ * reading in this browser? (`readingMemory` in the course settings.)
+ *
+ * **Reading memory** is what records what the reader did, across visits:
+ * which chapters they opened (the sidebar marks and the "changed since you
+ * last opened it" note, `page-marks.ts`), the cards they kept open on a page
+ * (`card-memory.ts`), the cards they carry from page to page
+ * (`card-carry.ts`), and where each deck stopped and which slides Present
+ * mode showed them (`deck-memory.ts`). It is kept only with the reader's yes.
+ * Without it — before they answer, after a no, or when the course turns the
+ * question off — nothing of their reading outlives the tab: no visit is
+ * recorded and no page is marked, and kept and carried cards and where a deck
+ * stopped live in the tab's session storage, so they still work until the tab
+ * is closed. The slides Present mode showed live there too before an answer,
+ * marked on the deck's page; a no clears them, and none is recorded after it.
+ *
+ * **Settings** are not reading memory: the theme, the text size, the panels'
+ * layout, a folded section or sidebar part, which edition a lesson's sidebar
+ * row opens, the "Carry cards" switch. The
+ * reader sets each of them, and they are kept because the reader set them,
+ * the exemption the ePrivacy rules give a preference the user asked for. They
+ * need no answer. Nothing explico stores is a cookie, and nothing leaves the
+ * browser.
+ *
+ * The answer itself is kept (storing a consent choice needs no consent), per
+ * course, for 13 months, after which the course asks again. A no deletes
+ * whatever reading memory the course had; "Forget what this course stored"
+ * (the `[?]` panel) deletes everything, the answer included.
+ *
+ * Storage goes through the `PreferenceStore` only. The pure half
+ * (`decodeAnswer`, `courseKeys`, …) is checked in Node by
+ * `tests/unit/reading-memory.test.ts`.
+ */
+
+/** The reader's answer: yes, no, or not asked yet (or asked too long ago). */
+type ReadingAnswer = 'yes' | 'no' | 'unasked';
+/** The course's `readingMemory` setting: ask the reader, or never keep reading memory. */
+type ReadingMemoryMode = 'ask' | 'off';
+/** How long an answer stands before the course asks again: 13 months. */
+declare const ANSWER_LIFETIME_DAYS = 396;
+/** The event every part of the page listens to when the reader answers or forgets. */
+declare const READING_MEMORY_EVENT = "explico:reading-memory";
+interface ReadingMemoryChange {
+    readonly base: string;
+    readonly answer: ReadingAnswer;
+}
+/** Where a course keeps the reader's answer. */
+declare function answerKey(base: string): string;
+/** The stored answer's text. */
+declare function encodeAnswer(yes: boolean, now: Date): string;
+/** The answer a stored text holds on `now`: anything unreadable, or older than its lifetime, is not asked. */
+declare function decodeAnswer(raw: string | null, now: Date): ReadingAnswer;
+/**
+ * Where a course keeps, for each of its decks, the frame Present mode last
+ * stood on and the frames it showed (`deck-memory.ts`, `deck-controller.ts`).
+ */
+declare function deckPositionsKey(base: string): string;
+/**
+ * A key that is this course's reading memory: its visits, its kept and its
+ * carried cards, where its decks stopped and the slides they showed.
+ */
+declare function isReadingMemoryKey(key: string, base: string): boolean;
+/**
+ * Every key this course stored, of the keys a store holds: its reading
+ * memory, its answer, its sections' and cards' per-page state, and the
+ * settings every explico course on this site shares, which forgetting this
+ * course resets too. Starlight's own theme key goes with them.
+ */
+declare function courseKeys(keys: readonly string[], base: string): string[];
+/** The course's setting, from the element `ReadingMemoryNotice.astro` renders on every page. */
+declare function readingMemoryMode(): ReadingMemoryMode;
+/** The reader's answer for the course at `base`. */
+declare function readingAnswer(base: string, now?: Date): ReadingAnswer;
+/** Whether the course may keep the reader's reading memory: they said yes, and the course asks. */
+declare function rememberReading(base: string): boolean;
+/**
+ * Where reading memory goes: kept in the browser with the reader's yes, else
+ * the tab's session only. Read the session copy too when kept, so the cards
+ * of a visit that started before the yes are not lost.
+ */
+declare function readingMemoryStore(base: string): PreferenceStore;
+/** Delete the course's reading memory from the browser (the tab's session copy stays). */
+declare function forgetReadingMemory(base: string): void;
+/**
+ * Record the reader's answer. A yes keeps the slides the tab recorded before
+ * it; a no deletes the course's reading memory, and those slides. Everything
+ * on the page is told.
+ */
+declare function answerReadingMemory(base: string, yes: boolean, now?: Date): void;
+/** "Forget what this course stored": every key of the course, in the browser and the tab; the course asks again. */
+declare function forgetCourse(base: string): void;
+
+export { ANSWER_LIFETIME_DAYS, READING_MEMORY_EVENT, type ReadingAnswer, type ReadingMemoryChange, type ReadingMemoryMode, answerKey, answerReadingMemory, courseKeys, deckPositionsKey, decodeAnswer, encodeAnswer, forgetCourse, forgetReadingMemory, isReadingMemoryKey, readingAnswer, readingMemoryMode, readingMemoryStore, rememberReading };

package/dist/session/reading-memory.js

@@ -0,0 +1,133 @@
+import {
+  createBrowserPreferenceStore,
+  createSessionPreferenceStore
+} from "./PreferenceStore.js";
+import {
+  decodeDeckMemory,
+  encodeDeckMemory,
+  mergeDeckMemory,
+  withEveryDeckUnseen
+} from "./deck-memory.js";
+const ANSWER_LIFETIME_DAYS = 396;
+const VERSION = 1;
+const DAY = 24 * 60 * 60 * 1e3;
+const READING_MEMORY_EVENT = "explico:reading-memory";
+function answerKey(base) {
+  return `explico-reading-memory:${base}`;
+}
+function encodeAnswer(yes, now) {
+  return JSON.stringify({ v: VERSION, remember: yes, at: now.toISOString().slice(0, 10) });
+}
+function decodeAnswer(raw, now) {
+  if (!raw) return "unasked";
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return "unasked";
+  }
+  if (!parsed || typeof parsed !== "object") return "unasked";
+  const { v, remember, at } = parsed;
+  if (v !== VERSION || typeof remember !== "boolean" || typeof at !== "string") return "unasked";
+  const given = Date.parse(`${at}T00:00:00Z`);
+  if (!Number.isFinite(given) || now.getTime() - given > ANSWER_LIFETIME_DAYS * DAY || given - now.getTime() > DAY) {
+    return "unasked";
+  }
+  return remember ? "yes" : "no";
+}
+const SHARED_SETTINGS = [
+  /^explico:display:/u,
+  /^explico:layout:/u,
+  /^explico-sidebar-groups$/u,
+  /^explico-sidebar-editions$/u,
+  /^explico:cards:carry$/u
+];
+function deckPositionsKey(base) {
+  return `explico:decks:${base}`;
+}
+function isReadingMemoryKey(key, base) {
+  return key === `explico-page-marks:${base}` || key === `explico:cards:carried:${base}` || key === deckPositionsKey(base) || key.startsWith(`explico:cards:${base}`) && !key.startsWith("explico:cards:carried:");
+}
+function courseKeys(keys, base) {
+  return keys.filter(
+    (key) => isReadingMemoryKey(key, base) || key === answerKey(base) || key.startsWith(`disclosure:${base}`) || key === "explico:cards:opened-at" || key === "starlight-theme" || key === "sl-sidebar-state" || SHARED_SETTINGS.some((pattern) => pattern.test(key))
+  );
+}
+const local = createBrowserPreferenceStore();
+const session = createSessionPreferenceStore();
+function remove(store, key) {
+  if (store.remove) store.remove(key);
+  else store.set(key, "");
+}
+function readingMemoryMode() {
+  const element = document.querySelector("[data-explico-reading-memory]");
+  return element?.dataset.explicoReadingMemory === "off" ? "off" : "ask";
+}
+function readingAnswer(base, now = /* @__PURE__ */ new Date()) {
+  return decodeAnswer(local.get(answerKey(base)), now);
+}
+function rememberReading(base) {
+  return readingMemoryMode() === "ask" && readingAnswer(base) === "yes";
+}
+function readingMemoryStore(base) {
+  if (!rememberReading(base)) return session;
+  return {
+    get: (key) => local.get(key) ?? session.get(key),
+    set: (key, value) => local.set(key, value),
+    remove: (key) => {
+      remove(local, key);
+      remove(session, key);
+    }
+  };
+}
+function forgetReadingMemory(base) {
+  for (const key of local.keys?.() ?? []) if (isReadingMemoryKey(key, base)) remove(local, key);
+}
+function announce(base) {
+  window.dispatchEvent(
+    new CustomEvent(READING_MEMORY_EVENT, { detail: { base, answer: readingAnswer(base) } })
+  );
+}
+function keepShownSlides(base) {
+  const raw = session.get(deckPositionsKey(base));
+  if (!raw) return;
+  const kept = mergeDeckMemory(decodeDeckMemory(local.get(deckPositionsKey(base))), decodeDeckMemory(raw));
+  local.set(deckPositionsKey(base), encodeDeckMemory(kept));
+}
+function forgetShownSlides(base) {
+  const raw = session.get(deckPositionsKey(base));
+  if (raw) session.set(deckPositionsKey(base), encodeDeckMemory(withEveryDeckUnseen(decodeDeckMemory(raw))));
+}
+function answerReadingMemory(base, yes, now = /* @__PURE__ */ new Date()) {
+  local.set(answerKey(base), encodeAnswer(yes, now));
+  if (yes) {
+    keepShownSlides(base);
+  } else {
+    forgetReadingMemory(base);
+    forgetShownSlides(base);
+  }
+  announce(base);
+}
+function forgetCourse(base) {
+  for (const store of [local, session]) {
+    for (const key of courseKeys(store.keys?.() ?? [], base)) remove(store, key);
+  }
+  announce(base);
+}
+export {
+  ANSWER_LIFETIME_DAYS,
+  READING_MEMORY_EVENT,
+  answerKey,
+  answerReadingMemory,
+  courseKeys,
+  deckPositionsKey,
+  decodeAnswer,
+  encodeAnswer,
+  forgetCourse,
+  forgetReadingMemory,
+  isReadingMemoryKey,
+  readingAnswer,
+  readingMemoryMode,
+  readingMemoryStore,
+  rememberReading
+};

package/docs/VERSIONING.md

@@ -88,26 +88,29 @@ applies every intervening section in order.
 
 ## Cutting a release
 
+Two judgment steps, then one command.
+
 1. Decide the next version from the rules above and the `## [Unreleased]`
    section of `CHANGELOG.md`.
-2. Add the section for `x.y.z` to `docs/authoring/migrating.md`, derived from the
-   complete release diff. Write explicit no-action instructions when nothing in
-   a downstream course needs to change. Walk the `CHANGELOG.md` entry you're
-   about to finalize bullet by bullet and give every `rule N#` it names, and
-   every `is now vN` schema bump, its own coverage — not only the entry's
-   headline item.
-3. `CHANGELOG.md`: rename `## [Unreleased]` to `## [x.y.z] - YYYY-MM-DD`, add a
-   fresh empty `## [Unreleased]`, and fix up the compare links at the bottom.
-4. Bump `package.json` `version` (`npm version x.y.z --no-git-tag-version`).
-5. Run `pnpm check:release-migration`. It fails when the new version has no
-   migration section, the shipped-file configuration excludes the guide, or a
-   `rule N#` / `is now vN` mention in the `CHANGELOG.md` entry has no match in
-   the `migrating.md` section.
-6. Run `pnpm build && pnpm test`, then inspect `pnpm pack --dry-run` and confirm
-   that `docs/authoring/migrating.md` and `docs/authoring/agents.md` are listed.
-7. Commit, then tag it annotated: `git tag -a vx.y.z -m "explico x.y.z"`. With
-   `push.followTags` on, a plain `git push` sends an annotated tag with its
-   commit; a lightweight tag never travels that way.
+2. Complete the `## <previous> → Unreleased` section at the top of
+   `docs/authoring/migrating.md`, derived from the complete changelog entry you
+   are about to finalize: every consumer-owned surface that moved, exact edits
+   or commands, conditional steps, the checks to run; write explicit no-action
+   instructions when nothing in a downstream course needs to change. Give every
+   `rule N#` the entry names and every `is now vN` schema bump its own
+   coverage, in that phrasing — `check:release-migration` matches them
+   mechanically.
+3. `pnpm release <x.y.z>` (`scripts/release.mjs`) does the rest: it refuses a
+   dirty tree, an empty `[Unreleased]` or a guide without the draft, then
+   renames the draft's heading to the version, dates the changelog entry and
+   fixes the compare links, bumps `package.json`, and runs
+   `check:release-migration`, the build, the tests and `pnpm pack --dry-run`
+   (the two shipped guides must be listed); a failed check puts the files back.
+   It stops at the diff; `--commit` commits and tags `v<x.y.z>` annotated
+   (with `push.followTags` on, a plain `git push` carries the tag; a
+   lightweight one never travels); `--dry-run` rehearses and restores.
+4. Publish with the VS Code task **Explico: Publish to npm**: the maintainer's
+   step, behind the account's security key.
 
 ## When you change the engine
 

package/docs/authoring/README.md

@@ -3,6 +3,11 @@
 Content rules for explico courses — strong recommendations for the people and
 agents who write lessons, notation entries, and interactive figures.
 
+A path these pages cite that starts with `playground/` is a file of the
+playground course, which is not in the npm package: its source, at the engine's
+latest release, is [downloadable](https://danieltuzes.github.io/explico/downloads/explico-playground-latest.zip) from https://danieltuzes.github.io/explico/start/, together with a full
+course, credit-and-derivatives.
+
 ## What these are
 
 A course built on explico is authored by many hands — lecturers, TAs, AI
@@ -102,7 +107,7 @@ speak in: what a part, a chapter, a section, and a subsection are, and which of
 them an equation number counts.
 
 Each rule has a stable ID — a letter for its area (`N` notation,
-`V` visualizations, `C` versioning, `S` structure, `P` prose) plus a number — and this shape.
+`V` visualizations, `C` versioning, `S` structure, `P` prose, `D` decks) plus a number — and this shape.
 `X` is not one of them: it is reserved for the rules a course writes for itself
 ([Rules of your own](#rules-of-your-own)), so the engine never ships an `X`
 rule and a course can number its own without waiting for a release.
@@ -230,11 +235,13 @@ of to the settings file.
 | -------------------------------- | ---- | --------------------------------------------------------- |
 | [notation.md](notation.md)       | `N`  | how math symbols are written and bound                     |
 | [visualizations.md](visualizations.md) | `V` | diagrams, charts, interactive figures, randomness      |
-| [versioning.md](versioning.md)   | `C`  | the knowledge version and `content/CHANGELOG.md`           |
+| [versioning.md](versioning.md)   | `C`  | the knowledge version, `content/CHANGELOG.md`, each page's own version |
 | [structure-rules.md](structure-rules.md) | `S` | heading and float title length; part page paragraphs; tables and diagrams declared so they can be cited |
 | [prose.md](prose.md)             | `P`  | how a lesson's sentences, terms, and equation lead-ins are worded |
+| [deck.md](deck.md)               | `D`  | a lesson's deck: its frames, steps, notes and recalls, and what fits a frame |
 | [components.md](components.md)   | —    | _catalog_: inline/block features available in a lesson body — tooltips, tables, figures, diagrams, memos, abbreviations, citations |
 | [agents.md](agents.md)           | —    | _guide_: working on a course repo (with an AI agent)       |
+| [cli.md](cli.md)                 | —    | _reference_, generated: every `content` verb, its flags, what it writes, and the shape of its `--json` ([cli-reference.json](cli-reference.json) as JSON Schema) |
 | [migrating.md](migrating.md)     | —    | _guide_: per-version steps when bumping the `explico` dep  |
 | [retired.md](retired.md)         | —    | _history_: one generated row per rule no longer in force, and its successor |
 
@@ -245,7 +252,7 @@ of to the settings file.
 | ID | Element | Rule | Enforcement |
 | --- | --- | --- | --- |
 | [N2](notation.md#n2) | math | A reserved spelling is used only for its reserved meaning — settings: `reserved` = `["\\mathbb{N} — the natural numbers","\\mathbb{Z} — the integers","\\mathbb{R} — the reals","\\mathbb{C} — the complex numbers","\\mathbb{P} — probability","\\mathcal{N}(\\mu, \\sigma^2) — the normal distribution (mean, variance)","\\mathrm{d} — the differential"]` | Guide |
-| [N4](notation.md#n4) | math, notation | One meaning per glyph; define once; `[[key]]` before first math | **Locked** — the notation layer is this rule — an unresolved glyph has no hover card and the render path needs every glyph bound. Script — `unresolved-glyph`, `glyph-unique-in-corpus` (warning), `weak-local` (info), `gloss-wants-promoting` (info), `card-wants-demoting` (info) in [`gate-math.ts`](../../src/reference/gate-math.ts) `resolveInto`; [`consistency.ts`](../../src/reference/consistency.ts) `checkGlyphUniqueness`, `checkWeakLocal`, `checkGlossWantsPromoting`, `checkCardWantsDemoting` |
+| [N4](notation.md#n4) | math, notation | One meaning per glyph; define once; `[[key]]` before first math | **Locked** — the notation layer is this rule — an unresolved glyph has no hover card and the render path needs every glyph bound. Script — `unresolved-glyph`, `glyph-unique-in-corpus` (warning), `weak-local` (info), `definition-repeated` (warning), `meaning-repeated` (info), `explain-redundant` (info), `card-wants-demoting` (info) in [`gate-math.ts`](../../src/reference/gate-math.ts) `resolveInto`; [`consistency.ts`](../../src/reference/consistency.ts) `checkGlyphUniqueness`, `checkWeakLocal`, `checkDefinitionRepeated`, `checkMeaningRepeated`, `checkCardWantsDemoting` |
 | [N5](notation.md#n5) | equation | Referenced display equations carry `\label{eq:key}` | Partial — `eq-key-unused` (info) in [`equations-validate.ts`](../../src/reference/equations-validate.ts) `validateEquations`. review: that a referenced-in-prose equation actually carries a label |
 | [N8](notation.md#n8) | math, notation | A named operator is universal (shipped/course list) or explained — settings: `allow` = `[]`, `deny` = `[]` | Script — `operator-explained` (warning) in [`consistency.ts`](../../src/reference/consistency.ts) `checkOperatorExplained` |
 | [N9](notation.md#n9) | prose, assessment, table | A quantity/unit/operator is typeset in `$…$`, never as plain text — settings: `allow` = `[]` | Script — `prose-notation`, `spelled-unit` in [`gate-prose-notation.ts`](../../src/reference/gate-prose-notation.ts) `gateProseNotation`, `gateProseNotationInAssessments` |
@@ -268,17 +275,18 @@ of to the settings file.
 | [V4](visualizations.md#v4) | plot | Randomised figures expose an adjustable, deterministic seed | Guide |
 | [V5](visualizations.md#v5) | plot | Axis ranges span the first 10 seeds at the current control values — settings: `seeds` = `10` | Guide |
 | [V6](visualizations.md#v6) | plot | Every quantitative axis shows at least three labelled values — settings: `minLabels` = `3` | Guide |
-| [V7](visualizations.md#v7) | plot | A figure’s picture fits on one screen — settings: `maxPercent` = `80` | Partial — `figure-too-tall` (warning) in [`figure-fit.ts`](../../src/reference/figure-fit.ts) `checkFigureFit`. review: any page or viewport the course’s Playwright suite does not open — the check runs in the browser, not in the build |
-| [V8](visualizations.md#v8) | diagram | A diagram fits the lesson column — settings: `columnWidth` = `707` | Script — `dia-too-wide` (warning) in [`diagram-fit.ts`](../../src/reference/diagram-fit.ts) `oversizedDiagrams` |
+| [V7](visualizations.md#v7) | plot | A figure’s picture fits on one screen _(chapter only)_ — settings: `maxPercent` = `80` | Partial — `figure-too-tall` (warning) in [`figure-fit.ts`](../../src/reference/figure-fit.ts) `checkFigureFit`. review: any page or viewport the course’s Playwright suite does not open — the check runs in the browser, not in the build |
+| [V8](visualizations.md#v8) | diagram | A diagram fits the lesson column _(chapter only)_ — settings: `columnWidth` = `707` | Script — `dia-too-wide` (warning) in [`diagram-fit.ts`](../../src/reference/diagram-fit.ts) `oversizedDiagrams` |
 | [C1](versioning.md#c1) | changelog | Every content change lands with a `content/CHANGELOG.md` entry | Guide |
 | [C2](versioning.md#c2) | changelog | The knowledge version is semver over learning-facing content | Guide |
 | [C3](versioning.md#c3) | changelog | `about.version` equals the newest changelog heading; a release moves both | Partial — `knowledge-version-mismatch` (warning), `knowledge-version-invalid` (warning), `knowledge-changelog-missing` (warning) in [`knowledge-version.ts`](../../src/compiler/knowledge-version.ts) `resolveKnowledgeVersion`. review: 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 |
-| [S1](structure-rules.md#s1) | heading | No heading, short caption or short-note title over 65 characters — settings: `maxLength` = `65` | Partial — `title-length` in [`gate-heading-length.ts`](../../src/reference/gate-heading-length.ts) `gateHeadingLength`. review: a lesson’s `frontmatter.title` — the gate scans the body only |
+| [C5](versioning.md#c5) | changelog | Each chapter and part page carries the release its content last changed in; `content/versions.json` is generated and committed | Partial — `page-versions-stale`, `page-versions-invalid` (warning) in [`page-versions.ts`](../../src/compiler/page-versions.ts) `syncPageVersions`, `readPageVersions`. review: 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 |
+| [S1](structure-rules.md#s1) | heading | No heading, short caption or short-note title over 65 characters _(chapter only)_ — settings: `maxLength` = `65` | Partial — `title-length` in [`gate-heading-length.ts`](../../src/reference/gate-heading-length.ts) `gateHeadingLength`. review: a lesson’s `frontmatter.title` — the gate scans the body only |
 | [S2](structure-rules.md#s2) | part-page | A part page carries a `<PartBridge>` (earlier parts → this one) and a `<PartScope>` paragraph — settings: `bridgeMinWords` = `30`, `bridgeMaxWords` = `150`, `scopeMinWords` = `30`, `scopeMaxWords` = `150` | Partial — `part-page-paragraph` in [`gate-part-pages.ts`](../../src/reference/gate-part-pages.ts) `gatePartPages`. review: what each paragraph says — the gate cannot tell a bridge that links the parts from one that does not |
 | [S3](structure-rules.md#s3) | table | A table is a `<Table id="…">`, never a raw Markdown/HTML table | Script — `raw-table-markdown` (warning), `raw-table-html` (warning) in [`raw-floats-validate.ts`](../../src/reference/raw-floats-validate.ts) `validateRawFloats` |
 | [S4](structure-rules.md#s4) | diagram | A `<Diagram>` carries an `id` and sits where numbering can see it | Script — `diagram-unkeyed` (warning), `diagram-nested` (warning) in [`raw-floats-validate.ts`](../../src/reference/raw-floats-validate.ts) `validateRawFloats` |
-| [S6](structure-rules.md#s6) | heading | Headings descend one level at a time, from `##` | Script — `heading-skip`, `heading-nested` in [`gate-heading-structure.ts`](../../src/reference/gate-heading-structure.ts) `gateHeadingStructure` |
-| [S7](structure-rules.md#s7) | heading | A heading is followed by body content, never by another heading | Script — `heading-adjacent` in [`gate-heading-structure.ts`](../../src/reference/gate-heading-structure.ts) `gateHeadingStructure` |
+| [S6](structure-rules.md#s6) | heading | Headings descend one level at a time, from `##` _(chapter only)_ | Script — `heading-skip`, `heading-nested` in [`gate-heading-structure.ts`](../../src/reference/gate-heading-structure.ts) `gateHeadingStructure` |
+| [S7](structure-rules.md#s7) | heading | A heading is followed by body content, never by another heading _(chapter only)_ | Script — `heading-adjacent` in [`gate-heading-structure.ts`](../../src/reference/gate-heading-structure.ts) `gateHeadingStructure` |
 | [S8](structure-rules.md#s8) | prose | Prefer `<Memo>` over a Starlight aside when the content needs an anchor, a caption or collapsing | Guide |
 | [S9](structure-rules.md#s9) | plot, table, diagram | A float’s short caption names it; the long caption goes on from that name | Guide |
 | [S10](structure-rules.md#s10) | part-page, plot, table, diagram, equation, notation | A page that is not a chapter explains its symbols but numbers nothing: it links a chapter’s float instead | **Locked** — a float needs a chapter number, and such a page has none — turning the rule off would not render one. Script — `non-chapter-float`, `non-chapter-local-notation`, `non-chapter-plain-text` in [`gate-non-chapter-pages.ts`](../../src/reference/gate-non-chapter-pages.ts) `gateNonChapterPages` |
@@ -291,6 +299,17 @@ of to the settings file.
 | [P7](prose.md#p7) | prose | One claim per sentence; every logical link stated | Guide |
 | [P8](prose.md#p8) | prose, math | Words for a relation match the math exactly ("proportional to") | Guide |
 | [P9](prose.md#p9) | prose, equation | A display equation's lead-in says what it gives and where it comes from | Guide |
+| [D1](deck.md#d1) | slide, heading | A deck is sections of frames: `##` a section, `###` a frame _(deck only)_ | **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. Script — `frame-depth`, `deck-loose-content`, `deck-empty` in [`decks-validate.ts`](../../src/reference/decks-validate.ts) `validateDecks` |
+| [D2](deck.md#d2) | slide | A frame fits its canvas in every step _(deck only)_ — settings: `maxWords` = `70`, `maxBullets` = `7` | Partial — `frame-dense` (warning), `frame-overflow` in [`decks-validate.ts`](../../src/reference/decks-validate.ts) `validateDecks`; [`deck-fit.ts`](../../src/compiler/exports/deck-fit.ts) `checkFrameFit`. review: 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 |
+| [D3](deck.md#d3) | slide, prose | A frame makes one claim, and its title states it _(deck only)_ | Guide |
+| [D4](deck.md#d4) | slide, prose | A frame with text carries speaker notes _(deck only)_ | Script — `frame-notes-missing` (warning) in [`decks-validate.ts`](../../src/reference/decks-validate.ts) `validateDecks` |
+| [D5](deck.md#d5) | slide, heading | A frame title fits one line _(deck only)_ — settings: `maxLength` = `50` | Script — `frame-title-length` in [`decks-validate.ts`](../../src/reference/decks-validate.ts) `validateDecks` |
+| [D6](deck.md#d6) | slide | A frame shows in at most `maxSteps` steps, each adding to the last _(deck only)_ — settings: `maxSteps` = `4` | Partial — `frame-steps` (warning) in [`decks-validate.ts`](../../src/reference/decks-validate.ts) `validateDecks`. review: that a later step contradicts nothing already shown |
+| [D7](deck.md#d7) | slide, plot, table, diagram | A frame holds one figure, table or diagram _(deck only)_ | Script — `frame-floats` (warning) in [`decks-validate.ts`](../../src/reference/decks-validate.ts) `validateDecks` |
+| [D8](deck.md#d8) | slide, equation | Recall a chapter’s result; never retype it _(deck only)_ | Script — `frame-retyped` (warning) in [`decks-validate.ts`](../../src/reference/decks-validate.ts) `validateDecks` |
+| [D9](deck.md#d9) | slide, math, notation | A frame introduces at most `maxNewSymbols` symbols _(deck only)_ — settings: `maxNewSymbols` = `4` | Script — `frame-new-symbols` (info) in [`decks-validate.ts`](../../src/reference/decks-validate.ts) `validateDecks` |
+| [D10](deck.md#d10) | slide | A deck opens on its title and closes on what the student can now do _(deck only)_ | Guide |
+| [D11](deck.md#d11) | slide, changelog | A deck is flagged when its chapter changed after it did _(deck only)_ | Script — `deck-stale` (info) in [`page-versions.ts`](../../src/compiler/page-versions.ts) `deckStaleDiagnostics` |
 
 _Element_ is what the rule is about; the first tag is primary. _Enforcement_ is
 derived from the catalog: **Script** — every violation a check can see is
@@ -299,7 +318,9 @@ reported; **Partial** — checks exist and the rule says what they miss;
 enforcement; **Locked** — the engine cannot run without it, so it has no
 checkbox in the course settings. A `(warning)` / `(info)` code does not fail
 the build. A rule with _settings_ takes them from `rules.<ID>` in the course
-settings; the value shown is the default.
+settings; the value shown is the default. A rule marked _chapter only_ or _deck
+only_ is about one edition of a lesson ([deck.md](deck.md)); every other rule
+holds for both.
 
 A rule that has been retired is not listed here at all — see
 [retired.md](retired.md).
@@ -320,5 +341,6 @@ next to the syntax it belongs to.
 | [`content-schema`](structure.md#content-schemas) | notation, assessment, source, changelog | Every content file satisfies its collection’s schema. | `content-schema` in [`content-schema.ts`](../../src/compiler/content-schema.ts) `validateContentSchemas` |
 | [`retired-keys`](structure.md#retired-keys) | changelog | No content file sets a key the engine has retired or cannot honour. | `retired-key`, `unsupported-key`, `ignored-key` (warning) in [`gate-retired-keys.ts`](../../src/reference/gate-retired-keys.ts) `findRetiredKeys`, `findUnsupportedKeys` |
 | [`prop-text`](components.md#props-are-plain-text) | math, plot, diagram, table | A component’s quoted prop holds plain text, and prose holds no `{…}` expression. | `markup-in-prop`, `mdx-expression` in [`gate-prop-text.ts`](../../src/reference/gate-prop-text.ts) `findMarkupInProps`; [`gate-mdx-expression.ts`](../../src/reference/gate-mdx-expression.ts) `gateMdxExpressions` |
+| [`decks`](deck.md#the-deck-file) | slide | A deck belongs to a lesson or a part, and recalls what its chapters number. _(deck only)_ | `deck-frontmatter`, `deck-outside-part`, `recall-unresolved`, `pause-invalid`, `deck-chapter-unknown`, `deck-chapter-repeated`, `deck-chapter-outside-part`, `deck-marker-misplaced`, `deck-check-no-chapter`, `deck-route-taken` in [`decks-validate.ts`](../../src/reference/decks-validate.ts) `validateDecks` |
 
 <!-- RULES-INDEX:END -->

package/docs/authoring/agents.md

@@ -5,6 +5,13 @@ Guidance for an AI agent — or a person — editing a course repo built on
 a repo-specific `AGENTS.md` at your course root for anything below that is
 particular to your layout.
 
+**Examples to start from.** Two working courses — the playground, which every
+`playground/…` path in these docs refers to, and credit-and-derivatives, a full
+course — are downloadable at their newest version from https://danieltuzes.github.io/explico/start/
+(the playground at https://danieltuzes.github.io/explico/downloads/explico-playground-latest.zip;
+[`sources.json`](https://danieltuzes.github.io/explico/downloads/sources.json) lists both, machine-readably). Download the
+playground to see how a feature is wired before writing your own.
+
 This is a guide, not a rule area. The enforceable rules are in
 [`notation.md`](notation.md) (`N`), [`visualizations.md`](visualizations.md)
 (`V`), [`versioning.md`](versioning.md) (`C`),
@@ -14,7 +21,10 @@ and a rule disagree, the engine wins — see [`README.md`](README.md).
 
 ## The loop
 
-- **Read the rules in effect first.** `pnpm --filter <course> content rules`
+- **Read the rules in effect first, one rule at a time after that.**
+  `pnpm content rule <ID>` prints one rule whole: the entry as this course
+  has it and the page's own section with its example, about half a thousand
+  tokens (N4, the largest, about three thousand). `pnpm --filter <course> content rules`
   (or `build/rules-in-effect.md` after a `validate:content`) lists every rule
   this course has *on*, grouped by the element it is about — prose, math,
   equation, notation, heading, part-page, plot, diagram, table, assessment,
@@ -24,6 +34,9 @@ and a rule disagree, the engine wins — see [`README.md`](README.md).
   checks and is therefore on you. Open a rule's page only when it is listed
   there and you need the example. A rule that is not on the page is off for
   this course (or does not exist): do not apply it, do not flag it in review.
+  For a deck, `content rules --edition deck` (or
+  `build/rules-in-effect-deck.md`) is the page: the `D` rules for frames, then
+  every rule a deck shares with a chapter ([deck.md](deck.md)).
   A rule marked `waivable` there can be broken at one place with
   `{/* explico-allow <ID>: <reason> */}` above the block — that is where the
   reason for breaking a rule goes ([README.md § Waiving](README.md#waiving-a-rule-at-one-place)).
@@ -32,21 +45,59 @@ and a rule disagree, the engine wins — see [`README.md`](README.md).
   and it is the one kind you may be asked to *add*
   ([README.md § Rules of your own](README.md#rules-of-your-own)) — never by
   editing this folder.
-- **Start from the CLI, not a file hunt.** `pnpm --filter <course> content
-  context <lesson>` prints a lesson plus exactly its notation, references, and
-  assumptions. `pnpm content status` is the overview: counts, diagnostic
-  totals and orphans. `pnpm content diagnostics info` lists everything;
-  `warning` and `error` raise the minimum severity. `pnpm content warnings`
-  lists warnings only.
-  `pnpm content check <lesson> | --changed` is schema + refs + MDX→KaTeX, exits
-  non-zero on an error. Read those before opening files.
-- **Validate, twice.** `pnpm --filter <course> validate:content` regenerates
-  `build/resolution/*` and then fails on the same run that changed them. Run it
-  again; the second run is clean. `build/` is git-ignored — there is nothing
-  to commit from it.
-- **Before handing work back:** `validate:content` (×2) → `astro check` →
-  `astro build`. `astro build` is the only step that runs every gate the CI
-  does.
+- **Start from the CLI, not a file hunt.** Run it from the course package;
+  `pnpm content help` lists every verb, `pnpm content help <verb>` prints one
+  verb's flags and the shape of its `--json` ([`cli.md`](cli.md) has them all),
+  and every verb takes `--json` for the whole report. Read what it prints
+  before opening files. The table under "The CLI" says which verb answers which
+  question.
+- **Validate once.** `pnpm --filter <course> validate:content` rewrites
+  `build/resolution/*` and fails only on a report git tracks that it had to
+  rewrite. A course whose `build/` is git-ignored passes on the first run; one
+  that commits `build/resolution/` commits the rewritten reports with the
+  change and runs it again (after an engine upgrade every report is
+  rewritten).
+- **Before handing work back:** `pnpm content verify` runs `validate:content`
+  → `content check --changed` → `astro check` → the course's tests →
+  `astro build` (`--e2e` adds the browser tests), one line per step and the
+  tail of a failed step's log; a rerun on an unchanged tree answers from its
+  last pass. `astro build` is the only step that runs every gate the CI does.
+
+## The CLI
+
+The `content` CLI ships in the engine (`explico/compiler/cli-main`); a course's
+`scripts/content.ts` is a three-line shim over it (migration step 14 of the
+release that introduced it). Read-only except `new` and `init-agent`, and
+`move`, `rename` and `fix`, which print a diff and change nothing without
+`--write`.
+
+| You want to know or do | Verb | It prints |
+| --- | --- | --- |
+| how the course stands | `status` | counts, diagnostic totals, the agent surfaces' sizes, whether this file's procedures are installed |
+| what is wrong, where | `diagnostics [info\|warning\|error]` | counts by code (with each code's rule) and by file; `--all`, `--code <c>`, `--lesson <id>`, `--changed` list the lines |
+| what a lesson draws on | `context <lesson>` | its outcomes, notation, sources, diagnostics |
+| which rules apply | `rules [--element …] [--enforcement guide]` | the rules this course has on, by element |
+| one rule, whole | `rule <ID>` | the entry as this course has it and the page's section, example included |
+| is this symbol defined already | `symbol <latex \| key>` | the shared card, each local entry with its lesson, each gloss with its card, near misses |
+| will this expression build | `equation "<latex>" [--lesson <id>]` | each glyph's card, unresolved glyphs with where they are defined; exit 1 if the build would refuse it |
+| what a lesson's math binds | `bindings <lesson>` | every span: bindings, unresolved glyphs, redundant `\explain` wraps |
+| does it render | `check <lesson \| deck>… \| --changed` | schema, references, MDX → KaTeX; exit 1 on an error |
+| what an upgrade needs | `migrate [--from <v>] [--to <v>]` | the migration guide's sections between two versions, oldest first |
+| a local entry becomes shared | `move <lesson>:<key> [--to <key>] [--write]` | the new card and every copy and reference that changes, as a diff |
+| rename a shared card | `rename <old> <new> [--write]` | the file and every reference, as a diff |
+| the mechanical repairs | `fix <lesson> [--write]` | redundant `\explain` wraps unwrapped, as a diff |
+| a draft to start from | `new lesson <id>`, `new deck <lesson \| part>`, `new term <key>` | the files it created; never overwrites |
+| install these procedures | `init-agent [--write]` | the skills and the `rules-reviewer` agent copied into `.claude/`, a baseline `AGENTS.md` when the course has none |
+| is it ready to hand back | `verify [--e2e] [--force]` | one line per step — validate, check, `astro check`, tests, `astro build` — and a failed step's log tail; exit 1 if one failed |
+| a verb's flags and `--json` | `help [<verb>]` | the usage; with a verb, its flags, what it writes, its exit code and its `--json` type |
+
+The procedures — drafting a lesson, upgrading the engine, releasing the
+course's content, reviewing a lesson against the guide-only rules — ship in
+`node_modules/explico/docs/course-agent/`. `pnpm content init-agent --write`
+installs them as project skills and a sub-agent; rerun it after an upgrade.
+A course's own `AGENTS.md` should open by pointing here and then hold only
+what is particular to the course; the shipped `docs/course-agent/AGENTS.md` is
+that baseline, and `content status` says when the course file does not.
 
 ## Reading and running
 
@@ -150,8 +201,11 @@ then read the target package's
 `node_modules/explico/docs/authoring/migrating.md`; the migration instructions
 ship with the code they describe.
 
-Apply every version section after the old version through the installed version,
-oldest first. Follow required and conditional changes across `content/`,
+`pnpm content migrate` prints exactly the sections to apply, from the version
+`package.json` pinned at HEAD to the one now installed, oldest first (`--from`
+and `--to` override either end), and refuses when a section is missing; it is
+the one or two sections an upgrade needs, not the whole forty-thousand-token
+guide. Apply every section it prints. Follow required and conditional changes across `content/`,
 `content/course.config.ts`, Astro/source wiring, course scripts, dependencies,
 and generated files. Do not use `CHANGELOG.md` alone as the procedure and do not
 assume that a release without a **Breaking** heading needs no work; each migration