explico 0.7.0 → 0.11.0

package/docs/authoring/README.md

@@ -39,8 +39,59 @@ whether it complies.
 3. Author discretion, recorded in the diff.
 
 A course may add its own rules on top — a house style for prose, a domain glyph
-table. It must not silently relax one of these; loosening a rule is a change to
-this folder, reviewed like any other change.
+table — in `courseRules` in its `course.settings.json` (see
+[Rules of your own](#rules-of-your-own)). It must not silently relax one of
+these; loosening a rule is a change to this folder, reviewed like any other
+change. Turning a rule off, or tuning it, for one course is a different thing
+and a visible one: `rules.<ID>` in the course settings
+(`course.settings.json`), which every `validate:content` reflects in
+`build/rules-in-effect.md` — the page an agent reads instead of this folder.
+
+## Accessibility
+
+Accessibility is the engine's job, not the author's: no rule here asks a course
+author to write an accessible name, a description, `alt` text or a text
+alternative. Every float renders a real `<figure>` and `<figcaption>`, so its
+caption is its accessible name; a table header that is all math gets a hidden
+text label from its notation entries; and every button and link the engine
+draws names itself. The engine's own markup is held to that by axe in explico's
+end-to-end tests. What an author writes anyway — a lab's `ariaLabel`, an
+`aria-label` on an inline `<svg role="img">` — is welcome and never required.
+
+## Waiving a rule at one place
+
+A rule is a strong recommendation, and the diff must state the reason when
+one is broken. The in-source form of that reason is a waiver — an MDX comment
+on its own line, above the block it is for:
+
+```mdx
+{/* explico-allow N9: the unit is being defined here, not used */}
+The unit of acceleration is written m/s² …
+```
+
+It covers the next block — from the first non-blank line after the comment to
+the line before the next blank line — and may name several rules
+(`explico-allow N9, N14: reason`). The reason is mandatory. What a waiver does
+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.
+- **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.
+  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
+  page would not render. Naming one is a `waiver-invalid` error.
+
+A waiver comment is not prose: the `N9` / `N14` scans blank it, so the reason
+may quote the very text it excuses.
 
 ## How a rule is written
 
@@ -49,21 +100,39 @@ 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) 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.
 
 > **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 (which gate) or Review-only.
+> _Enforcement._ Build-enforced (naming the gate module) or Review-only.
 > _Exceptions._ The stateable reasons that override it, if any.
 
-IDs are permanent. A retired rule keeps its number, is struck through in the
-index below, and gains a one-line `Retired <date>: <why>` note — so a `N3` in an
-old commit message never goes ambiguous.
+IDs are permanent, so a `N3` in an old commit message never goes ambiguous — but
+a retired rule leaves this folder entirely. Its section goes, its row leaves the
+index, and one line (ID, the sentence it had, the date, its successor, why) lands
+in the generated table on [retired.md](retired.md). Nothing an author or an agent
+reads while drafting mentions it. Two rules that turn out to be one idea are
+merged that way: the text moves into the rule that keeps its ID, the other
+becomes a row on that page.
+
+The catalog entry adds what a machine needs and the page does not repeat: the
+element(s) the rule is about, the diagnostic codes it owns and the module and
+function that emit them, its course settings, and whether it is locked. The
+page's `_Enforcement._` paragraph must name every module the entry lists;
+`gen-rules.mjs --check` holds the two together.
 
 ## Amending
 
-1. Open a PR that touches exactly one area file plus the index table below.
+1. Open a PR that touches exactly one area file plus its entry in
+   `src/rules/catalog.ts` (ID, title, elements, checks, settings). The index
+   table below is generated from the catalog — run
+   `node scripts/agent/gen-rules.mjs` after `pnpm build`; `--check` runs in
+   `scripts/agent/verify` and CI and fails when the table or a rule page
+   disagrees with the catalog.
 2. Give a new rule the next unused number in its area. Never renumber.
 3. Write the four parts above. If the rule could be build-enforced but is not
    yet, say so and link the engine issue.
@@ -73,6 +142,82 @@ old commit message never goes ambiguous.
 A new area — a new letter and file — is the same PR shape plus a row in the
 file table.
 
+## Rules of your own
+
+A classroom has house style the engine does not ship — a phrase this cohort must
+not use, a paragraph shape a department agreed on, a convention that holds for
+one course and nowhere else. Those are the course's own rules, and they live in
+its `course.settings.json`, next to every other course setting and editable in
+the same form editor (`tools/vscode-settings-editor/`). No engine change, no
+fork, no waiting for a release.
+
+They are numbered in the **`X` area**, which is reserved for them: `X1`…`X99`.
+The engine never ships an `X` rule, so a course can add one today and upgrade
+`explico` tomorrow without a collision, and one ID works everywhere an engine
+rule's does — a diagnostic, a waiver, a commit message, the rules-in-effect
+page.
+
+```json
+"courseRules": [
+  {
+    "id": "X1",
+    "title": "A paragraph never ends in an exclamation.",
+    "summary": "End a paragraph on the statement it argues for. Move the emphasis into the sentence, or drop it.",
+    "elements": ["prose"],
+    "severity": "error",
+    "forbid": [
+      {
+        "scope": "paragraph",
+        "pattern": "Ni!$",
+        "message": "a paragraph ends in “Ni!” — end it on the statement instead."
+      }
+    ]
+  },
+  {
+    "id": "X2",
+    "title": "Every fifth paragraph is four sentences in Object–Subject–Verb order.",
+    "summary": "Count the paragraphs of the lesson body; the fifth, tenth, … is exactly four sentences, each in OSV order.",
+    "elements": ["prose"],
+    "enabled": false,
+    "unchecked": "everything — the rule is a guide, and sentence order is not something a pattern can see."
+  }
+]
+```
+
+**Enforced or guide, from one field.** A rule with a `forbid` pattern is
+enforced: the build matches it and reports every hit at the rule's `severity`
+(`error` fails `pnpm validate:content`, `warning` does not), with the rule's ID
+as the diagnostic code — `[X1] content/docs/…:42: a paragraph ends in "Ni!" …`.
+A rule with no pattern is a guide: it appears on the rules-in-effect page for an
+author or an agent to follow, and nothing runs. Both kinds are real rules on
+that page, which is what an agent reads before drafting.
+
+**`enabled: false` parks a rule.** It stays in the file, with its text, and moves
+to the page's "Off" list — where an agent is told not to apply it *and* not to
+flag it in review. That is how a rule that is drafted, or agreed for next term,
+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
+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.
+
+**Waiving one.** `{/* explico-allow X1: the sentence quotes the chant */}`
+above a block, exactly like an engine rule, reason mandatory; a waiver that
+silences nothing is reported so it gets removed.
+
+**Where the text lives.** `summary` is what the rules-in-effect page prints, so
+write it as an instruction, not a rationale. For a rule that needs a page of its
+own, put it under the course's `content/docs/` (or anywhere), and name it in
+`doc` — a path relative to `build/`, or a URL — and the page links there instead
+of to the settings file.
+
 ## Files
 
 | File                             | Area | Covers                                                     |
@@ -80,41 +225,88 @@ file table.
 | [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 figure/diagram/memo/short-note title length |
-| [prose.md](prose.md)             | `P`  | how a lesson's sentences are worded                        |
+| [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 |
+| [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)       |
 | [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 |
 
 ## Rule index
 
-| ID                              | Rule                                                              | Enforcement                                  |
-| ------------------------------- | ---------------------------------------------------------------- | ------------------------------------------- |
-| [N1](notation.md#n1)            | The normal distribution is `\mathcal{N}`                          | Build-enforced (completeness gate) + review |
-| [N2](notation.md#n2)            | `\mathbb{N,Z,R,C}` are reserved for the number systems            | Partial — gate forces every other `\mathbb{}` to resolve |
-| [N3](notation.md#n3)            | Multi-letter roman labels use `\mathrm{…}`                        | Build-enforced (completeness gate)          |
-| [N4](notation.md#n4)            | One meaning per glyph; define once; `[[key]]` before first math   | Build-enforced (completeness gate)          |
-| [N5](notation.md#n5)            | Referenced display equations carry `\label{eq:key}`               | Review-only                                 |
-| [N6](notation.md#n6)            | Probability is `\mathbb{P}` (double-struck `P`)                   | Build-enforced (completeness gate) + review |
-| [N7](notation.md#n7)            | The differential `d` is upright `\mathrm{d}`                       | Build-enforced (completeness gate)          |
-| [N8](notation.md#n8)            | A named operator is universal (shipped/course list) or explained  | Tier-3 warning (`operator-explained`)       |
-| [N9](notation.md#n9)            | A quantity/unit/operator is typeset in `$…$`, never as plain text  | Build-enforced (`gate-prose-notation.ts`)   |
-| [N10](notation.md#n10)          | A `\mathrm{…}` multi-letter label is universal, or it is explained | Tier-3 warning (`roman-label-explained`)    |
-| [N11](notation.md#n11)          | A worked example never drops a unit from a substituted value       | Review-only                                 |
-| [N12](notation.md#n12)          | Math syntax never carries the sentence's own trailing punctuation  | Review-only                                 |
-| [N13](notation.md#n13)          | A nonlinear function always takes a parenthesized argument         | Build-enforced (`resolveMathGlyphs`)        |
-| [N14](notation.md#n14)          | An abbreviation-shaped word in prose is universal, or explained    | Build-enforced (`gate-abbreviations.ts`)    |
-| [N15](notation.md#n15)          | A nested `(`, `[`, `{`, or `\|` must use scalable sizing            | Build-enforced (`resolveMathGlyphs`)        |
-| [N16](notation.md#n16)          | AI-generated stylistic grouping alternates delimiter types           | Review-only                                 |
-| [N17](notation.md#n17)          | Nested scalable delimiters grow strictly from inside to outside      | Tier-3 warning (`delimiter-size-hierarchy`) |
-| [V1](visualizations.md#v1)      | Graphs and flowcharts use the `Diagram` component                 | Review-only                                 |
-| [V2](visualizations.md#v2)      | Static charts: SVG → D3 → Observable Plot, chosen per figure       | Review-only                                 |
-| [V3](visualizations.md#v3)      | Interactive figures: island + `renderLabMath` seam + text alt      | Review-only                                 |
-| [V4](visualizations.md#v4)      | Randomised figures expose an adjustable, deterministic seed        | Review-only                                 |
-| [V5](visualizations.md#v5)      | Axis ranges span the first 10 seeds at the current control values  | Review-only                                 |
-| [C1](versioning.md#c1)          | Every content change lands with a `content/CHANGELOG.md` entry     | Review-only                                 |
-| [C2](versioning.md#c2)          | The knowledge version is semver over learning-facing content       | Review-only                                 |
-| [C3](versioning.md#c3)          | `about.version` equals the newest `content/CHANGELOG.md` heading   | Build-enforced (Tier-3 `knowledge-version-mismatch`) |
-| [C4](versioning.md#c4)          | On release, move `[Unreleased]` and bump `about.version` together  | Review-only                                 |
-| [S1](structure-rules.md#s1)     | No heading, or figure/diagram/memo/short-note title, over 65 characters | Build-enforced (`gate-heading-length.ts`) for body/floats + review for `frontmatter.title` |
-| [P1](prose.md#p1)              | "or" never introduces a second name for the same thing            | Review-only                                 |
+<!-- RULES-INDEX:BEGIN (generated by scripts/agent/gen-rules.mjs from src/rules/catalog.ts — do not edit inside) -->
+
+| 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` |
+| [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` |
+| [N10](notation.md#n10) | math, notation | A multi-letter label is `\mathrm{…}`, and universal or explained — settings: `allow` = `[]`, `deny` = `[]` | Partial — `roman-label-explained` (warning) in [`consistency.ts`](../../src/reference/consistency.ts) `checkRomanLabelExplained`. review: that a bare multi-letter run was wrapped in `\mathrm{…}` at all — rule N4’s gate reports it as unresolved one-letter symbols, which is a different message for the same mistake |
+| [N11](notation.md#n11) | math, prose | A worked example never drops a unit from a substituted value | Guide |
+| [N12](notation.md#n12) | math, prose, assessment | Math syntax never carries the sentence's own trailing punctuation — settings: `allow` = `[]`, `deny` = `[]` | Script — `math-trailing-punctuation` in [`gate-math-punctuation.ts`](../../src/reference/gate-math-punctuation.ts) `gateMathPunctuation`, `gateMathPunctuationInAssessments` |
+| [N13](notation.md#n13) | math | A nonlinear function always takes a parenthesized argument | **Locked** — the glyph resolver cannot tell where an unparenthesized argument ends, so it cannot bind the symbols inside it. Script — `unparenthesized-function` in [`math-glyphs.mjs`](../../src/reference/math-glyphs.mjs) `resolveMathGlyphs` |
+| [N14](notation.md#n14) | prose | An abbreviation-shaped word in prose is universal, or explained — settings: `allow` = `[]`, `deny` = `[]` | Script — `abbreviation-unexplained` in [`gate-abbreviations.ts`](../../src/reference/gate-abbreviations.ts) `gateAbbreviations` |
+| [N15](notation.md#n15) | math | A nested `(`, `[`, `{`, or `\|` must use scalable sizing | **Locked** — a bare `\|` is both an opener and a closer; nested, the resolver cannot pair it, so the rule is a parsing precondition. Script — `nested-bare-delimiter` in [`math-glyphs.mjs`](../../src/reference/math-glyphs.mjs) `resolveMathGlyphs` |
+| [N17](notation.md#n17) | math | A delimiter’s shape is semantic; a nest is engine-sized, not hand-sized | Partial — `delimiter-manual-size` (warning) in [`delimiter-size.ts`](../../src/reference/delimiter-size.ts) `lintDelimiterSizes`. review: the shape half — `delimiter-manual-size` parses sizing syntax only, and never decides whether a bracket is semantic. A bare nested delimiter is rule N15’s error instead |
+| [N18](notation.md#n18) | equation | A multi-step derivation is one aligned chain; reasons follow `\qquad` | Guide |
+| [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` |
+| [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 | Guide |
+| [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 |
+| [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 |
+| [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` |
+| [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 |
+| [P1](prose.md#p1) | prose | "or" never introduces a second name for the same thing | Guide |
+| [P2](prose.md#p2) | prose | One term for each concept, repeated — no synonyms for variety | Guide |
+| [P3](prose.md#p3) | prose | One meaning for each term; no technical term in its everyday sense | Guide |
+| [P4](prose.md#p4) | prose | Use the established term; define it where the argument first needs it | Guide |
+| [P5](prose.md#p5) | prose | Main text is literal: no idioms, metaphors, buzzwords, entertainment | Guide |
+| [P6](prose.md#p6) | prose | Industry jargon only in an optional "Industry jargon" aside | Guide |
+| [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 |
+
+_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
+reported; **Partial** — checks exist and the rule says what they miss;
+**Guide** — nothing runs, a reviewer (or the agent's own reading) is the
+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.
+
+A rule that has been retired is not listed here at all — see
+[retired.md](retired.md).
+
+### Always enforced (invariants)
+
+Not rules — what the syntax means. One entry per feature, always on, documented
+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` |
+| [`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` |
+
+<!-- RULES-INDEX:END -->

package/docs/authoring/agents.md

@@ -14,6 +14,24 @@ 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`
+  (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,
+  source, changelog — with its enforcement, its diagnostic codes, its
+  settings in effect, and a one-line summary. `--element table,prose` narrows
+  it to what you are editing; `--enforcement guide` shows what no script
+  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.
+  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)).
+  A line tagged `course` with an `X` ID is this course's own rule, written in
+  `course.settings.json` `courseRules`: it binds exactly like an engine rule,
+  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 draft-debt overview. `pnpm content
@@ -23,8 +41,8 @@ and a rule disagree, the engine wins — see [`README.md`](README.md).
   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. Commit the regenerated `build/` and
-  `resolution/` files.
+  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.
@@ -45,23 +63,51 @@ and a rule disagree, the engine wins — see [`README.md`](README.md).
 - Pipe long command output to `| tail -n 40`. One-off probes and fetched pages
   go to a scratch file you then grep — not into the conversation whole.
 
+## Prose
+
+Clarity comes before variety and entertainment, in lecture notes and
+documentation alike. The `P` rules say how; which of them this course has on
+is on the rules-in-effect page (`content rules --element prose`), so check a
+draft against that list — not against a remembered version of
+[`prose.md`](prose.md) — before handing it back. No script checks a `P` rule:
+they are all `guide`, and the review is yours.
+
 ## Notation `formula:` fields (the sharp edges)
 
-- Every glyph in a `formula:` must resolve: 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.
+- 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).
-- Use `\mathbf` for a vector, not `\vec`: `\vec` currently trips the KaTeX
-  sanitizer in `render-notation-math`. (Engine bug, not a rule — but `\mathbf`
-  is what builds today.)
+- `\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
+  same holds for `\boldsymbol`, `\bm`, `\mathcal`, `\mathbb`, `\mathscr`,
+  `\mathfrak`, `\mathsf` and `\mathtt`. `\vec` renders, but it is a decoration
+  (rule N22), not a font.
+
+## Decorations: `\hat`, `\bar`, `'`, `^*` (rule N22)
+
+- A decoration is an operator. Before drafting, decide per decoration which of
+  the three it is on this page: a **whole form** with its own entry
+  (`latex: \hat{\beta}`) when the decorated symbol is a quantity in its own
+  right; an **operator entry** (`latex: \hat{}`, `{}'`, `{}^{*}`) when the
+  decoration means the same thing everywhere it appears; or on the course's
+  `rules.N22.allow` list. An unexplained one is an `accent-explained` warning.
+- Reach for **suspension** (`notation.suspend` in the lesson frontmatter, with
+  a `reason`) only when the decoration is *not* its usual operator on that
+  page — primes that number versions (`b'`, `b''`) rather than
+  differentiate. Suspension makes every decorated form on the page need its
+  own entry, so it is stricter, not a shortcut; one whole-form entry is enough
+  when a single decorated symbol is special.
 
 ## Versioning
 
 Every content change adds a bullet under `## [Unreleased]` in
 `content/CHANGELOG.md`; a release moves it to a dated `## [x.y.z]` heading and
-sets `about.version` to match, in the same commit. Rules C1–C4,
+sets `about.version` to match, in the same commit. Rules C1–C3,
 [`versioning.md`](versioning.md).
 
 ## Upgrading the engine