explico 0.12.0 → 0.13.1

package/dist/rules/rules.schema.json

@@ -8,7 +8,7 @@
   "properties": {
     "N9": {
       "title": "N9 — A quantity/unit/operator is typeset in `$…$`, never as plain text",
-      "description": "Never write `45 m/s`, `t (s)`, `vx` or `KE/m` as plain text, and never spell a stated quantity's unit out: \"4 seconds\", \"2 meters per second squared\", \"30 degrees\", \"$x = 3$ meters\" are `$4\\ \\text{s}$`, `$2\\ \\text{m/s}^2$`, `$30^{\\circ}$`, `$x = 3\\ \\text{m}$`. A unit inside math is `\\text{}`-wrapped, short form, in the same span as its number or symbol. A unit named on its own (\"measured in meters\") stays a word; a sentence that defines a unit is waived. JSX prop strings (`caption=\"…\"`) and assessment choice labels render no math, so N9 does not apply there.",
+      "description": "Never write `45 m/s`, `t (s)`, `vx` or `KE/m` as plain text, and never spell a stated quantity's unit out: \"4 seconds\", \"2 meters per second squared\", \"30 degrees\", \"$x = 3$ meters\" are `$4\\ \\text{s}$`, `$2\\ \\text{m/s}^2$`, `$30^{\\circ}$`, `$x = 3\\ \\text{m}$`. A unit inside math is `\\text{}`-wrapped, short form, in the same span as its number or symbol. A unit named on its own (\"measured in meters\") stays a word; a sentence that defines a unit is waived. JSX prop strings (`caption=\"…\"`) render no math, so N9 does not apply there; nor does it apply to an assessment choice label, which may still hold math (`$30^{\\circ}$`).",
       "x-element": "prose",
       "x-elements": [
         "prose",
@@ -81,26 +81,6 @@
         }
       }
     },
-    "S5": {
-      "title": "S5 — A sign / perspective convention is declared once and cited elsewhere",
-      "description": "Prose that states a sign / cash-flow-perspective convention resolves it to the single declaration — the `conventions.signConventionKey` notation entry (`[[key]]`) or the `conventions.cashFlowPerspectiveCompetency` competency — rather than restating it.",
-      "x-element": "prose",
-      "x-elements": [
-        "prose"
-      ],
-      "x-enforcement": "script",
-      "x-doc": "docs/authoring/structure-rules.md#s5",
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "enabled": {
-          "title": "Enabled",
-          "description": "Off: the check does not run, and the rule leaves the rules-in-effect page.",
-          "type": "boolean",
-          "default": true
-        }
-      }
-    },
     "S8": {
       "title": "S8 — Prefer `<Memo>` over a Starlight aside when the content needs an anchor, a caption or collapsing",
       "description": "A `:::note`/`:::tip`/`:::caution`/`:::danger` (or `<Aside>`) is a short callout read in passing: no number, no link, never folded. Anything a reader may want to cite, skip or come back to is a `<Memo id=\"…\">`.",
@@ -596,6 +576,27 @@
         }
       }
     },
+    "N23": {
+      "title": "N23 — An index is part of the symbol: whole form, family or index entry",
+      "description": "A subscript on a symbol is explained by the indexed symbol’s own entry (`latex: v_0`), a family entry whose index runs (`latex: x_k` explains `x_1`), or an index entry for the subscript (`latex: \"{}_0\"`, which composes a derived card); a card on the base alone does not explain it, and arithmetic on an index letter with its own card does (`X_{t-1}`). A running index — a lowercase letter not marked `fixedIndex` — states its set, as `range` on its card or after a `\\quad` on the first display line that uses it. Never wrap an indexed symbol in `\\explain` with a key whose `latex` has no index. Not checked by the build: whether a `\\quad` clause states the set correctly; whether a lowercase index is really running; lab math whose glyph table is a copy of the one `labMathScope` returned.",
+      "x-element": "math",
+      "x-elements": [
+        "math",
+        "notation"
+      ],
+      "x-enforcement": "partial",
+      "x-doc": "docs/authoring/notation.md#n23",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "title": "Enabled",
+          "description": "Off: the check does not run, and the rule leaves the rules-in-effect page.",
+          "type": "boolean",
+          "default": true
+        }
+      }
+    },
     "N5": {
       "title": "N5 — Referenced display equations carry `\\label{eq:key}`",
       "description": "Label a display equation with `\\label{eq:key}` when — and only when — prose refers back to it with `[[eq-key]]`. A label nothing references is noise. Not checked by the build: that a referenced-in-prose equation actually carries a label.",
@@ -638,7 +639,7 @@
     },
     "N19": {
       "title": "N19 — A notation entry states `units` from the vocabulary, or `dimensionless`",
-      "description": "Every notation entry has `units:` from `units-vocab.ts` (`m/s`, `s`, `kg`, …) or `dimensionless: true`. A token outside the vocabulary is a warning.",
+      "description": "Every notation entry has `units:` from `units-vocab.ts` (`m/s`, `s`, `kg`, …) or `dimensionless: true`, except an index entry (`latex: \"{}_0\"`, N23), which takes neither. A token outside the vocabulary is a warning.",
       "x-element": "notation",
       "x-elements": [
         "notation"
@@ -679,7 +680,7 @@
     },
     "N21": {
       "title": "N21 — A gloss is named by a short noun phrase, not a sentence",
-      "description": "A gloss `label` names the symbol in a few words (“launch angle”); a clause, sentence punctuation, or a definition belongs in a full notation entry instead.",
+      "description": "A gloss `name` names the symbol in a few words (“launch angle”); a clause, sentence punctuation, or a definition belongs in a full notation entry instead.",
       "x-element": "notation",
       "x-elements": [
         "notation"
@@ -852,7 +853,7 @@
     },
     "V3": {
       "title": "V3 — Interactive figures: a hydrated island + the `renderLabMath` seam",
-      "description": "An interactive figure is an island under `content/labs/` inside a `<Figure>`, renders its equations through `renderLabMath` (`{ display: false }` for a legend, an axis title or a label; a `{ math }` run for the caption clause) and never KaTeX directly, and labels its controls; the figure’s caption is its name, so the lab writes no accessible name or text alternative of its own. Not checked by the build: that a lab labels its controls and writes no name of its own, and math a lab draws without importing `katex` — the build’s rendered check (`figure-symbols.ts`) covers the page it renders.",
+      "description": "An interactive figure is an island under `content/labs/` inside a `<Figure>`, renders its equations through `renderLabMath` (`{ display: false }` for a legend, an axis title or a label; a `{ math }` run for the caption clause) and never KaTeX directly, and labels its controls; the figure’s caption is its name, so the lab writes no accessible name or text alternative of its own. Its default picture is drawn at build time too and handed to the island as children, so the built page has it. Not checked by the build: that a lab labels its controls and writes no name of its own, and math a lab draws without importing `katex` — the build’s rendered check (`figure-symbols.ts`) covers the page it renders.",
       "x-element": "plot",
       "x-elements": [
         "plot"
@@ -944,6 +945,33 @@
         }
       }
     },
+    "V7": {
+      "title": "V7 — A figure’s picture fits on one screen",
+      "description": "The default slot of a `<Figure>` — plot, key and tables — stays within `maxPercent` of the viewport height, so the reader sees the picture and its caption line together. A square or tall plot gets a fixed width instead of the full column. Not checked by the build: any page or viewport the course’s Playwright suite does not open — the check runs in the browser, not in the build.",
+      "x-element": "plot",
+      "x-elements": [
+        "plot"
+      ],
+      "x-enforcement": "partial",
+      "x-doc": "docs/authoring/visualizations.md#v7",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "title": "Enabled",
+          "description": "Off: the check does not run, and the rule leaves the rules-in-effect page.",
+          "type": "boolean",
+          "default": true
+        },
+        "maxPercent": {
+          "title": "Largest picture height (% of screen)",
+          "description": "How much of the viewport height a figure’s picture may take.",
+          "type": "integer",
+          "minimum": 10,
+          "default": 80
+        }
+      }
+    },
     "S9": {
       "title": "S9 — A float’s short caption names it; the long caption goes on from that name",
       "description": "Give each figure, table and diagram a `short` caption that names it: it opens the caption line in bold, and names the float in \"Hidden here\", a copied link and the \"Figures and tables\" page. The long `caption` goes on from that name to say what the float shows — its subject, its marks and symbols, the case shown — and at most the one thing to notice. The argument drawn from a figure is lesson text after it, and a lab’s instructions are the first line of its `tools`.",
@@ -986,6 +1014,33 @@
         }
       }
     },
+    "V8": {
+      "title": "V8 — A diagram fits the lesson column",
+      "description": "A `<Diagram>` lays out no wider than `columnWidth`, the lesson column at a 1366px-wide window, so the reader sees the whole graph without scrolling it. Narrow it with `direction=\"TB\"`, a shorter label or a node `width` (its label wraps inside it); `warnAboveWidth={false}` marks a diagram meant to scroll.",
+      "x-element": "diagram",
+      "x-elements": [
+        "diagram"
+      ],
+      "x-enforcement": "script",
+      "x-doc": "docs/authoring/visualizations.md#v8",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "title": "Enabled",
+          "description": "Off: the check does not run, and the rule leaves the rules-in-effect page.",
+          "type": "boolean",
+          "default": true
+        },
+        "columnWidth": {
+          "title": "Column width (px)",
+          "description": "The widest a diagram may lay out: the lesson column at the window width the course is read at most (707px at 1366px).",
+          "type": "integer",
+          "minimum": 200,
+          "default": 707
+        }
+      }
+    },
     "S4": {
       "title": "S4 — A `<Diagram>` carries an `id` and sits where numbering can see it",
       "description": "Give every `<Diagram>` an `id`, and place it at the top level or inside `<Memo>`/`<ShortNote>`/`<Table>`/`<Figure>` — a diagram nested elsewhere (e.g. in `<CompactExample>`) is never numbered.",

package/dist/rules/settings.d.ts

@@ -1,3 +1,3 @@
 import './catalog.js';
 import './course-rules.js';
-export { e as ConfigDiagnostic, j as CourseRulesConfig, M as ManifestRules, R as ResolvedRules, k as RuleSettingsInput, l as catalogIds, m as disabledCodes, n as dropDisabled, p as partPageLimits, r as resolveRules, o as rulesJsonSchema, q as rulesSnapshot } from '../course-config-Dsnri9Tk.js';
+export { d as ConfigDiagnostic, j as CourseRulesConfig, M as ManifestRules, R as ResolvedRules, k as RuleSettingsInput, l as catalogIds, m as disabledCodes, n as dropDisabled, p as partPageLimits, r as resolveRules, o as rulesJsonSchema, q as rulesSnapshot } from '../course-config-rRtME5UV.js';

package/dist/rules/settings.js

@@ -84,6 +84,13 @@ function resolveRules(config) {
       message: `CourseConfig \`${legacyKey}\` is deprecated \u2014 move it to \`rules.${id}\` (same \`allow\` / \`deny\` shape). The old key is honoured for now.`
     });
   }
+  if (config.conventions !== void 0) {
+    diagnostics.push({
+      code: "config-deprecated-key",
+      severity: "warning",
+      message: "CourseConfig `conventions` is no longer read: rule S5, its only reader, was retired into rule N4. Delete the block. See docs/authoring/retired.md."
+    });
+  }
   const enabled = /* @__PURE__ */ new Map();
   const settings = /* @__PURE__ */ new Map();
   for (const rule of catalogRules()) {

package/dist/session/PreferenceStore.d.ts

@@ -11,6 +11,8 @@
  * cookie-backed store) and nothing else changes. `createBrowserPreferenceStore`
  * is the "versioned local-storage adapter" the architecture doc anticipates —
  * kept deliberately tiny, and the only place `git grep localStorage` matches.
+ * `createSessionPreferenceStore` is its per-tab twin, for state one tab keeps
+ * of its own (the cards it carries, `card-carry.ts`).
  */
 interface PreferenceStore {
     get(key: string): string | null;
@@ -27,7 +29,22 @@ interface PreferenceStore {
  * controls still work, they just do not persist.
  */
 declare function createBrowserPreferenceStore(): PreferenceStore;
+/**
+ * A `sessionStorage`-backed store: one tab's own state, which a reload, Back
+ * and Forward keep and another tab never sees. Wrapped like the local one.
+ */
+declare function createSessionPreferenceStore(): PreferenceStore;
+/**
+ * The store's one inline twin: the source of a script that copies a stored
+ * preference onto the root element as `attribute` before the page first
+ * paints. Every other reader of a preference is a module script, which runs
+ * after that paint: fine for a panel's state, but a page drawn at one text
+ * size and then redrawn at another visibly jumps. Only a value in `values`
+ * is copied; anything else stored is ignored. It is built here so that
+ * browser storage is still touched in this file alone.
+ */
+declare function inlineRootAttributeScript(key: string, attribute: string, values: readonly string[]): string;
 /** An in-memory store — the no-op-equivalent seam for SSR or tests. */
 declare function createMemoryPreferenceStore(): PreferenceStore;
 
-export { type PreferenceStore, createBrowserPreferenceStore, createMemoryPreferenceStore };
+export { type PreferenceStore, createBrowserPreferenceStore, createMemoryPreferenceStore, createSessionPreferenceStore, inlineRootAttributeScript };

package/dist/session/PreferenceStore.js

@@ -21,6 +21,32 @@ function createBrowserPreferenceStore() {
     }
   };
 }
+function createSessionPreferenceStore() {
+  return {
+    get(key) {
+      try {
+        return window.sessionStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    set(key, value) {
+      try {
+        window.sessionStorage.setItem(key, value);
+      } catch {
+      }
+    },
+    remove(key) {
+      try {
+        window.sessionStorage.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+function inlineRootAttributeScript(key, attribute, values) {
+  return `try{var v=window.localStorage.getItem(${JSON.stringify(key)});if(${JSON.stringify(values)}.indexOf(v)>=0)document.documentElement.setAttribute(${JSON.stringify(attribute)},v)}catch(e){}`;
+}
 function createMemoryPreferenceStore() {
   const map = /* @__PURE__ */ new Map();
   return {
@@ -35,5 +61,7 @@ function createMemoryPreferenceStore() {
 }
 export {
   createBrowserPreferenceStore,
-  createMemoryPreferenceStore
+  createMemoryPreferenceStore,
+  createSessionPreferenceStore,
+  inlineRootAttributeScript
 };

package/docs/authoring/README.md

@@ -15,10 +15,12 @@ leave that reason in the diff or the PR description. "I preferred it" is not a
 reason; "the cited source writes it this way and the passage shows the mapping"
 is.
 
-Two kinds of rule live here:
+Three kinds of rule live here:
 
 - **Build-enforced** — the engine already fails the build when the rule is
   broken. The rule text tells you _how_ to satisfy the gate, not whether to.
+- **Partial** — the build checks part of the rule and a reviewer the rest;
+  the rule index says which part is which.
 - **Review-only** — nothing checks it automatically; a reviewer does. Breaking
   one is a review comment, not a broken build.
 
@@ -75,16 +77,16 @@ the line before the next blank line — and may name several rules
 depends on the rule:
 
 - **A rule with a check that reports a line** (`waivable` on the rules-in-effect
-  page: N9, N14, S1, N17) — the build drops the findings the waiver covers. A
-  waiver that silences nothing is a `waiver-unused` warning, so a stale one
-  gets removed.
+  page, such as N9, N14, N23 and S1) — the build drops the findings the waiver
+  covers. A waiver that silences nothing is a `waiver-unused` warning, so a
+  stale one gets removed.
 - **A guide rule** (every `P` and `V` rule, N2, N11, …) — nothing to silence;
   the waiver is the reason on record, next to the sentence it is about, and a
   reviewer reads it as such.
 - **One of the course's own rules** (`X1`, …) — always waivable inline: an
   enforced one reports a line, and a guide one has nothing to silence.
 - **A rule whose check has no line** — a notation entry (N8, N10, N19–N21), a
-  per-lesson count (S3, S4, S5), the changelog (C3) — cannot be waived inline.
+  per-lesson count (S3, S4), the changelog (C3) — cannot be waived inline.
   Silence one finding per key in `lint-ignore.yml`
   (`- <code>:<key> — <reason>`), or turn the rule off in `rules.<ID>`.
 - **A locked rule** (N4, N13, N15) and an invariant cannot be waived: the
@@ -108,7 +110,8 @@ rule and a course can number its own without waiting for a release.
 > **N1 — One-line imperative.**
 > _Rationale._ Why the rule exists; the failure it prevents.
 > _How to apply._ Concrete steps, with the smallest example that shows it.
-> _Enforcement._ Build-enforced (naming the gate module) or Review-only.
+> _Enforcement._ Build-enforced or Partial (naming the gate module), or
+> Review-only.
 > _Exceptions._ The stateable reasons that override it, if any.
 
 IDs are permanent, so a `N3` in an old commit message never goes ambiguous — but
@@ -199,12 +202,15 @@ waits without affecting this term's lessons.
 
 **What a pattern sees.** A JavaScript regular expression, matched against the
 lesson's prose with code fences, inline code, `$…$` and `$$…$$`, `[[key]]`
-references, `import` lines, JSX tags and MDX comments blanked out first —
-exactly the surface rule N9 scans, so a pattern never trips over LaTeX or a
-component prop. `scope` picks the unit: `paragraph` (the default — a block
-between blank lines, right-trimmed, so `^` and `$` are its ends), `prose` (the
-whole lesson, so a pattern may span paragraphs), or `heading` (the text of each
-Markdown heading). `flags` takes `i`, `m`, `s`, `u`; `g` is always applied. A
+references, link addresses (a link is read by its text), `import` lines, JSX
+tags and MDX comments blanked out first — exactly the surface rule N9 scans,
+so a pattern never trips over LaTeX or a component's syntax. The text a reader
+sees in a prop (`caption`, `short`, `title`, `label`) is read too, each as a
+paragraph of its own. `scope` picks the unit: `paragraph` (the default — a
+block between blank lines, right-trimmed, so `^` and `$` are its ends, or a
+visible prop's text), `prose` (the whole lesson, so a pattern may span
+paragraphs, and each visible prop), or `heading` (the text of each Markdown
+heading). `flags` takes `i`, `m`, `s`, `u`; `g` is always applied. A
 pattern that does not compile, or that matches the empty string, fails the build
 with the path of the setting — the rule never silently does nothing.
 
@@ -225,7 +231,7 @@ 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`           |
-| [structure-rules.md](structure-rules.md) | `S` | heading and float title length; part page paragraphs; tables, diagrams and conventions declared so they can be cited |
+| [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 |
 | [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)       |
@@ -254,13 +260,16 @@ of to the settings file.
 | [N19](notation.md#n19) | notation | A notation entry states `units` from the vocabulary, or `dimensionless` | Script — `notation-units` (warning), `units-vocab` (warning) in [`consistency.ts`](../../src/reference/consistency.ts) `checkNotationUnits` |
 | [N20](notation.md#n20) | notation, source | A notation entry's source citation carries a locator | Script — `notation-source-locator` (warning) in [`consistency.ts`](../../src/reference/consistency.ts) `checkNotationSourceLocator` |
 | [N21](notation.md#n21) | notation | A gloss is named by a short noun phrase, not a sentence | Script — `gloss-name-shape` (warning) in [`consistency.ts`](../../src/reference/consistency.ts) `checkGlossNameShape` |
-| [N22](notation.md#n22) | math, notation | An accent or mark is an operator: universal, explained, or a whole form — settings: `allow` = `[]`, `deny` = `[]` | Script — `accent-explained` (warning), `suspended-operator-unresolved`, `operator-suspension-reason` (warning), `operator-suspended` (info), `operator-shadowed` (info) in [`consistency.ts`](../../src/reference/consistency.ts) `checkAccentExplained`, `checkOperatorSuspension`; [`gate-math.ts`](../../src/reference/gate-math.ts) `resolveInto` |
+| [N22](notation.md#n22) | math, notation | An accent or mark is an operator: universal, explained, or a whole form — settings: `allow` = `[]`, `deny` = `[]` | Script — `accent-explained` (warning), `accent-swallowed` (warning), `suspended-operator-unresolved`, `operator-suspension-reason` (warning), `operator-suspended` (info), `operator-shadowed` (info) in [`consistency.ts`](../../src/reference/consistency.ts) `checkAccentExplained`, `checkOperatorSuspension`; [`gate-math.ts`](../../src/reference/gate-math.ts) `resolveInto` |
+| [N23](notation.md#n23) | math, notation | An index is part of the symbol: whole form, family or index entry | Partial — `index-explained`, `index-swallowed`, `index-range`, `derived-key-taken` in [`gate-indices.ts`](../../src/reference/gate-indices.ts) `gateIndices`. review: whether a `\quad` clause states the set correctly; whether a lowercase index is really running; lab math whose glyph table is a copy of the one `labMathScope` returned |
 | [V1](visualizations.md#v1) | diagram | Graphs and flowcharts use the `Diagram` component | Guide |
 | [V2](visualizations.md#v2) | plot | Static charts: SVG → D3 → Observable Plot, chosen per figure | Guide |
-| [V3](visualizations.md#v3) | plot | Interactive figures: a hydrated island + the `renderLabMath` seam | Partial — `lab-katex-direct` in [`lab-katex-validate.ts`](../../src/reference/lab-katex-validate.ts) `validateLabKatexImports`. review: that a lab labels its controls and writes no name of its own, and math a lab draws without importing `katex` — the build’s rendered check (`figure-symbols.ts`) covers the page it renders |
+| [V3](visualizations.md#v3) | plot | Interactive figures: a hydrated island + the `renderLabMath` seam | Partial — `lab-katex-direct`, `lab-picture-undrawn` (warning) in [`lab-katex-validate.ts`](../../src/reference/lab-katex-validate.ts) `validateLabKatexImports`; [`figure-pictures.ts`](../../src/reference/figure-pictures.ts) `undrawnFigurePictures`. review: that a lab labels its controls and writes no name of its own, and math a lab draws without importing `katex` — the build’s rendered check (`figure-symbols.ts`) covers the page it renders |
 | [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` |
 | [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 |
@@ -268,8 +277,7 @@ of to the settings file.
 | [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` |
-| [S5](structure-rules.md#s5) | prose | A sign / perspective convention is declared once and cited elsewhere | Script — `convention-single-definition` (warning) in [`consistency.ts`](../../src/reference/consistency.ts) `checkConventionSingleDefinition` |
-| [S6](structure-rules.md#s6) | heading | Headings descend one level at a time, from `##` | Script — `heading-skip` 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 `##` | 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` |
 | [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 |
@@ -303,11 +311,14 @@ next to the syntax it belongs to.
 
 | Invariant | Element | Holds that | Codes |
 | --- | --- | --- | --- |
-| [`notation-references`](components.md#reference-systems) | notation, math | Notation keys are well-formed, unique, defined, and acyclic. | `undefined-reference`, `invalid-key`, `duplicate-key`, `duplicate-page`, `duplicate-definition`, `conflicting-definition`, `reference-cycle`, `gloss-collides-with-card`, `unknown-explicit-key`, `malformed-explicit-binding`, `unused-definition` (info) in [`registry.ts`](../../src/reference/registry.ts) `buildNotationRegistry`; [`math-glyphs.mjs`](../../src/reference/math-glyphs.mjs) `resolveMathGlyphs`; [`gate-math.ts`](../../src/reference/gate-math.ts) `reportUnknownScopeKeys` |
-| [`math-syntax`](notation.md) | math | Every math span parses and resolves unambiguously. | `invalid-latex`, `invalid-latex-input`, `invalid-notation`, `invalid-definitions`, `unsupported-katex-version`, `ambiguous-span`, `ambiguous-base-fallback`, `ambiguous-canonical-notation`, `math-compile-error` in [`math-glyphs.mjs`](../../src/reference/math-glyphs.mjs) `resolveMathGlyphs`; [`gate-math.ts`](../../src/reference/gate-math.ts) `resolveInto` |
-| [`keyed-floats`](structure.md#the-invariant-and-why-it-is-build-enforced) | equation, table, plot, diagram, assessment, heading | A keyed float’s `id` is well-formed and unique, it is named by its caption pair, and every `[[…]]` to it or to a section resolves. | `eq-duplicate-key`, `eq-ref-resolves`, `tab-invalid-key`, `tab-duplicate-key`, `tab-ref-resolves`, `tab-key-unused` (info), `tab-removed-prop`, `fig-invalid-key`, `fig-duplicate-key`, `fig-ref-resolves`, `fig-key-unused` (info), `fig-removed-prop`, `dia-invalid-key`, `dia-duplicate-key`, `dia-ref-resolves`, `dia-key-unused` (info), `dia-removed-prop`, `ex-invalid-key`, `ex-duplicate-key`, `ex-ref-resolves`, `ex-key-unused` (info), `ex-removed-prop`, `check-invalid-key`, `check-duplicate-key`, `check-ref-resolves`, `ex-missing-prop`, `sec-ref-resolves`, `fold-unnamed` in [`equations-validate.ts`](../../src/reference/equations-validate.ts) `validateEquations`; [`keyed-float-validate.ts`](../../src/reference/keyed-float-validate.ts) `validateKeyedFloats`; [`knowledge-checks-validate.ts`](../../src/reference/knowledge-checks-validate.ts) `validateKnowledgeChecks`; [`examples-validate.ts`](../../src/reference/examples-validate.ts) `validateExamples`; [`sections-validate.ts`](../../src/reference/sections-validate.ts) `validateSectionRefs`; [`folds-validate.ts`](../../src/reference/folds-validate.ts) `validateFolds` |
+| [`notation-references`](components.md#reference-systems) | notation, math | Notation keys are well-formed, unique, defined, and acyclic. | `undefined-reference`, `invalid-key`, `duplicate-key`, `duplicate-page`, `duplicate-definition`, `conflicting-definition`, `reference-cycle`, `gloss-collides-with-card`, `unknown-explicit-key`, `malformed-explicit-binding`, `unused-definition` (info), `local-shadows-shared` (warning), `malformed-reference` in [`registry.ts`](../../src/reference/registry.ts) `buildNotationRegistry`; [`math-glyphs.mjs`](../../src/reference/math-glyphs.mjs) `resolveMathGlyphs`; [`gate-math.ts`](../../src/reference/gate-math.ts) `reportUnknownScopeKeys` |
+| [`math-syntax`](notation.md) | math | Every math span parses and resolves unambiguously. | `invalid-latex`, `invalid-latex-input`, `invalid-notation`, `invalid-definitions`, `unsupported-katex-version`, `ambiguous-span`, `ambiguous-base-fallback`, `ambiguous-canonical-notation`, `math-compile-error`, `currency-dollar` in [`math-glyphs.mjs`](../../src/reference/math-glyphs.mjs) `resolveMathGlyphs`; [`gate-math.ts`](../../src/reference/gate-math.ts) `resolveInto`, `gateContentMath` |
+| [`keyed-floats`](structure.md#the-invariant-and-why-it-is-build-enforced) | equation, table, plot, diagram, assessment, heading | A keyed float’s `id` is well-formed and unique, it is named by its caption pair, and every `[[…]]` to it or to a section resolves. | `eq-duplicate-key`, `eq-ref-resolves`, `eq-label-repeated`, `eq-latex-ref`, `tab-invalid-key`, `tab-duplicate-key`, `tab-ref-resolves`, `tab-key-unused` (info), `tab-removed-prop`, `tab-unread-prop` (warning), `tab-several-tables`, `fig-invalid-key`, `fig-duplicate-key`, `fig-ref-resolves`, `fig-key-unused` (info), `fig-removed-prop`, `fig-unread-prop` (warning), `dia-invalid-key`, `dia-duplicate-key`, `dia-ref-resolves`, `dia-key-unused` (info), `dia-removed-prop`, `dia-unread-prop` (warning), `ex-invalid-key`, `ex-duplicate-key`, `ex-ref-resolves`, `ex-key-unused` (info), `ex-removed-prop`, `ex-unread-prop` (warning), `check-invalid-key`, `check-duplicate-key`, `check-ref-resolves`, `ex-missing-prop`, `sec-ref-resolves`, `heading-anchor-collision`, `fold-unnamed` in [`equations-validate.ts`](../../src/reference/equations-validate.ts) `validateEquations`; [`keyed-float-validate.ts`](../../src/reference/keyed-float-validate.ts) `validateKeyedFloats`; [`tables-validate.ts`](../../src/reference/tables-validate.ts) `validateTables`; [`knowledge-checks-validate.ts`](../../src/reference/knowledge-checks-validate.ts) `validateKnowledgeChecks`; [`examples-validate.ts`](../../src/reference/examples-validate.ts) `validateExamples`; [`sections-validate.ts`](../../src/reference/sections-validate.ts) `validateSectionRefs`, `validateHeadingAnchors`; [`folds-validate.ts`](../../src/reference/folds-validate.ts) `validateFolds` |
 | [`course-settings`](README.md#amending) | changelog | The course settings name real rules and current keys. | `config-deprecated-key` (warning), `config-retired-rule` (warning) in [`settings.ts`](../../src/rules/settings.ts) `resolveRules` |
 | [`waivers`](README.md#waiving-a-rule-at-one-place) | prose | A per-place waiver names a waivable rule, gives a reason, and covers something. | `waiver-malformed`, `waiver-invalid`, `waiver-unused` (warning) in [`waivers.ts`](../../src/rules/waivers.ts) `collectWaivers`, `applyWaivers` |
-| [`curriculum`](structure.md#the-names) | changelog | The curriculum graph is well-formed. | `invalid-id`, `duplicate-id`, `unknown-reference`, `duplicate-reference`, `self-prerequisite`, `cycle`, `lesson-order`, `track-order`, `assessment-coverage`, `invalid-assessment`, `review-state`, `teaches-support`, `alignment-unknown-competency`, `alignment-unknown-lesson`, `alignment-introduction`, `alignment-unavailable`, `alignment-review-state` in [`validation.ts`](../../src/curriculum/validation.ts) `validateCurriculum`; [`curriculum-alignment.ts`](../../src/reference/curriculum-alignment.ts) `validateNotationAlignment` |
+| [`curriculum`](structure.md#the-names) | changelog | The curriculum graph is well-formed. | `invalid-id`, `duplicate-id`, `unknown-reference`, `duplicate-reference`, `self-prerequisite`, `cycle`, `lesson-order`, `track-order`, `assessment-coverage`, `invalid-assessment`, `missing-assumptions`, `teaches-support`, `citation-in-link`, `alignment-unknown-competency`, `alignment-unknown-lesson`, `alignment-introduction`, `alignment-unavailable`, `lesson-outside-parts`, `part-empty` (warning) in [`validation.ts`](../../src/curriculum/validation.ts) `validateCurriculum`; [`curriculum-alignment.ts`](../../src/reference/curriculum-alignment.ts) `validateNotationAlignment`; [`manifest.ts`](../../src/compiler/manifest.ts) `compileManifest` |
+| [`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` |
 
 <!-- RULES-INDEX:END -->

package/docs/authoring/agents.md

@@ -34,9 +34,10 @@ and a rule disagree, the engine wins — see [`README.md`](README.md).
   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 draft-debt overview. `pnpm content
-  diagnostics info` lists everything; `warning` and `error` raise the minimum
-  severity. `pnpm content warnings` lists warnings only.
+  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
@@ -77,10 +78,17 @@ they are all `guide`, and the review is yours.
 - Every glyph in a `formula:` must resolve (rule N4, locked): to the entry
   itself, one of its `glosses:`, a card named with `\explain{key}{latex}`, or
   the base library. An unresolved bare letter fails the build with the entry
-  name.
-- The notation reference graph must be **acyclic** — if `a`'s formula names `b`
-  and `b`'s names `a`, the build rejects it. Link only *down* a chain
-  (acceleration → velocity → position, not back up).
+  name. A formula resolves against its own card's table, so an index entry
+  (`{}_0`, rule N23) does not compose there: explain `v_0` with a whole form
+  (`\explain{motion.launch-speed}{v_0}`), a gloss, or by wrapping the
+  subscript in the index entry's key,
+  `\mathbf{v}_{\explain{motion.initial}{0}}`.
+- The notation reference graph must be **acyclic** through meanings and
+  bodies: if `a`'s meaning names `b` and `b`'s names `a`, the build rejects
+  it. Link only *down* a chain (acceleration → velocity → position, not back
+  up). A `formula` may name any card, even one whose formula names it back:
+  `confidence-level` (γ = 1 − α) and `significance-level` (α = 1 − γ), or
+  three entries that each show the one model equation they appear in.
 - `\mathbf` is the house style for a vector, and a bold letter is its own
   symbol (rule N4): `\mathbf{v}` needs an entry (`latex: \mathbf{v}`) or an
   `\explain{key}{\mathbf{v}}` wrap even when a scalar `v` is on the page. The
@@ -103,6 +111,29 @@ they are all `guide`, and the review is yours.
   own entry, so it is stricter, not a shortcut; one whole-form entry is enough
   when a single decorated symbol is special.
 
+## Indices: `x_0`, `v_x`, `x_i` (rule N23)
+
+- A subscript on a symbol is part of the symbol, and a card on the base alone
+  does not explain it. Before drafting, decide per indexed symbol which of the
+  three it is: a **whole form** with its own entry (`latex: v_0`, "Launch
+  speed") for a named quantity; a **family** (`latex: x_k`) for an index that
+  runs, which explains `x_1`, `x_{k+1}`, `x_N`; or an **index entry**
+  (`latex: "{}_0"`, quoted) for a subscript with one meaning on the page,
+  which makes every carded symbol it indexes one derived card. An index entry
+  takes no `units`; its title for the symbol comes from `reads`.
+- A base-library `i`, `e` or `d`, a digit or a `\mathrm{…}` label in a
+  subscript needs one of the three; an index letter with its own card
+  (`X_{t-1}`) explains its slot. A running index (lowercase, not marked
+  `fixedIndex: true`) states its set once: `range` on its card, or after a
+  `\quad` on the first display line that uses it (`\quad i = 1, \dots, n`).
+- Do not wrap an indexed symbol in a card that has no index:
+  `\explain{motion.velocity}{v_x}` fails `index-swallowed`. An indexed entry
+  lends its card to no bare symbol (rule N4): a bare `\alpha` beside a family
+  `\alpha_i` needs its own entry.
+- Lab and `<Diagram>` math is checked as it renders, at `astro build`. A lab
+  passes the table `labMathScope` returned to `renderLabMath` unchanged; a
+  copy gets no derived cards and no check.
+
 ## Versioning
 
 Every content change adds a bullet under `## [Unreleased]` in