explico 0.6.0 → 0.8.0

package/dist/reference/katex-delimiters.mjs

@@ -0,0 +1,125 @@
+/**
+ * Rule N17's engine half: make `\left`/`\right` grow strictly outward.
+ *
+ * Importing this module for its side effect installs a KaTeX whose
+ * `\delimitershortfall` is `-1pt` instead of the stock `5pt`, so a scalable
+ * delimiter pair is always *strictly* taller than what it wraps and nesting
+ * depth shows up on its own. See `docs/katex-bracket-scaling.md` for the
+ * derivation and `docs/authoring/notation.md#n17` for the authoring rule.
+ *
+ * ## Why this is not a `patches/` file
+ *
+ * `delimiterExtend` is a function-local `const` inside `makeLeftRightDelim`.
+ * Nothing KaTeX exports reaches it — `__defineMacro`, `__defineFunction`,
+ * `__defineSymbol`, `__setFontMetrics` and the settings schema all sit above
+ * the layout engine — so the constant can only be changed in the module's own
+ * source. A `pnpm patch` does that, but a patch is project-local: it cannot
+ * travel inside the published `explico` artifact, so every downstream course
+ * would have to reapply it or silently render flat nests.
+ *
+ * So the engine does it in code instead. It reads KaTeX's own ESM bundle,
+ * rewrites that one constant, imports the result as a module, and moves the
+ * rendering entry points onto the shared `katex` object every consumer in the
+ * process already imported. KaTeX's default export is a plain mutable object
+ * and `rehype-katex` reads `katex.renderToString` at call time, so the swap
+ * reaches lesson-body math without forking the plugin.
+ *
+ * ## Why this is safe to rely on
+ *
+ * The assumptions above (a matching constant, a mutable export, a bundle with
+ * no imports of its own) are all checked here, and `assertDelimiterGrowth()`
+ * renders a known nest afterwards and throws when the sizes do not actually
+ * increase. A course therefore either renders with engine-sized delimiters or
+ * fails its build saying so — it cannot quietly get the stock behaviour.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import katex from 'katex';
+
+/** TeX's `\delimitershortfall`, in points, as KaTeX hard-codes it. */
+const STOCK_SHORTFALL = '5.0';
+/** The negative shortfall that forces strict outward growth. */
+const GROWN_SHORTFALL = '-1.0';
+
+const needle = (points) =>
+  `var delimiterExtend = ${points} / options.fontMetrics().ptPerEm;`;
+
+/** The entry points that build a delimiter and must come from the rewrite. */
+const RENDER_EXPORTS = [
+  'render',
+  'renderToString',
+  '__renderToDomTree',
+  '__renderToHTMLTree',
+];
+
+/**
+ * Exported for the test that pins both failure messages — a KaTeX upgrade that
+ * moves the constant, and a leftover `patches/` file, are the two ways this
+ * stops being able to install itself.
+ */
+export function rewriteBundle(source) {
+  const stock = needle(STOCK_SHORTFALL);
+  if (!source.includes(stock)) {
+    // Either the constant moved or someone already rewrote it. Both mean the
+    // assumption this module rests on no longer holds for this KaTeX build.
+    const alreadyGrown = source.includes(needle(GROWN_SHORTFALL));
+    throw new Error(
+      alreadyGrown
+        ? `explico: katex ${katex.version} already carries the -1pt delimiter ` +
+          'shortfall (a patches/ file?). Remove that patch — the engine ' +
+          'installs it in code (src/reference/katex-delimiters.mjs).'
+        : `explico: cannot install the N17 delimiter sizing into katex ` +
+          `${katex.version}: the \\delimitershortfall constant ` +
+          `(${stock}) is not in its ESM bundle. Re-derive the one-line ` +
+          'change against the new bundle — see docs/katex-bracket-scaling.md.',
+    );
+  }
+  return source.replace(stock, needle(GROWN_SHORTFALL));
+}
+
+async function loadGrownKatex() {
+  const require = createRequire(import.meta.url);
+  const source = readFileSync(require.resolve('katex/dist/katex.mjs'), 'utf8');
+  // The bundle is self-contained, so it can be re-imported from a data URL
+  // with no base to resolve relative specifiers against.
+  const rewritten = rewriteBundle(source);
+  const module = await import(
+    `data:text/javascript;base64,${Buffer.from(rewritten).toString('base64')}`
+  );
+  return module.default;
+}
+
+/**
+ * Render a known nest and confirm the outer pair really is larger than the
+ * inner one. Cheap, and it turns every way this could go wrong — an upstream
+ * refactor, a frozen export, an import that beat us to it — into one loud
+ * failure at the point of installation.
+ */
+export function assertDelimiterGrowth(instance = katex) {
+  const html = instance.renderToString(
+    String.raw`\left[1+\left(\frac{a}{b}\right)\right]`,
+    { displayMode: true, output: 'html' },
+  );
+  const sizes = [...html.matchAll(/delimsizing size(\d)/g)].map((m) =>
+    Number(m[1]),
+  );
+  // Two pairs, so four glyphs: outer, inner, inner, outer.
+  const grew = sizes.length === 4 && sizes[0] > sizes[1];
+  if (!grew) {
+    throw new Error(
+      'explico: the N17 delimiter sizing did not take effect — a nested ' +
+        `\\left…\\right pair rendered as [${sizes.join(', ')}] instead of ` +
+        'growing outward. Something rendered math before ' +
+        "'explico/reference/katex-delimiters.mjs' was imported, or katex " +
+        'changed shape. See docs/katex-bracket-scaling.md.',
+    );
+  }
+}
+
+const grown = await loadGrownKatex();
+for (const name of RENDER_EXPORTS) {
+  if (typeof grown[name] === 'function') katex[name] = grown[name];
+}
+assertDelimiterGrowth();
+
+export default katex;

package/dist/reference/katex-options.mjs

@@ -1,3 +1,7 @@
+// Side-effect import: installs rule N17's delimiter sizing onto the shared
+// `katex` module before anything renders. A course wires this file into its
+// `astro.config.mjs`, so `rehype-katex` inherits it without a patch.
+import './katex-delimiters.mjs';
 import { NOTATION_KEY_PATTERN } from './remark-notation.mjs';
 
 export const EXPLAIN_MACRO = String.raw`\htmlData{notation-key=#1}{#2}`;

package/dist/reference/keyed-float-validate.d.ts

@@ -7,7 +7,7 @@
  * - `<prefix>-duplicate-key` (error): an `id` is unique per lesson.
  * - `<prefix>-ref-resolves` (error): every `[[<prefix>-key]]` /
  *   `[[slug#<prefix>-key]]` points at the matching keyed float with that `id`.
- * - `<prefix>-key-unused` (warning): a keyed float never referenced.
+ * - `<prefix>-key-unused` (info): a keyed float is never referenced.
  *
  * `tables-validate.ts`, `figures-validate.ts`, and `diagrams-validate.ts` are
  * thin wrappers over this so callers import a kind-specific validator with
@@ -38,7 +38,7 @@ interface KeyedFloatRefRecord {
 }
 interface KeyedFloatDiagnostic {
     readonly code: string;
-    readonly severity: 'error' | 'warning';
+    readonly severity: 'error' | 'warning' | 'info';
     readonly message: string;
     readonly file?: string;
     readonly lessonId?: string;

package/dist/reference/keyed-float-validate.js

@@ -93,7 +93,7 @@ function validateKeyedFloats(lessons, kind) {
     if (referenced.has(`${label.slug}#${label.key}`)) continue;
     diagnostics.push({
       code: `${prefix}-key-unused`,
-      severity: "warning",
+      severity: "info",
       message: `${label.lessonId} has a ${noun} id="${label.key}" (${label.number}) but nothing references it with [[${prefix}-${label.key}]]`,
       file: label.slug,
       lessonId: label.lessonId,

package/dist/reference/math-glyphs.mjs

@@ -1,4 +1,4 @@
-import katex from 'katex';
+import katex from './katex-delimiters.mjs';
 
 import { BASE_LIBRARY } from './base-library.mjs';
 import { PARENTHESIZED_FUNCTIONS } from './base-operators.mjs';
@@ -386,6 +386,19 @@ function trimTrailingWhitespace(latex, start, end) {
   return trimmed;
 }
 
+/**
+ * KaTeX gives a node it produced by expanding a macro a `loc` from the lexer
+ * over the *macro body*, not over the source being scanned: `\vdots` expands
+ * to `{\varvdots\rule{0pt}{15pt}}`, and its `\varvdots` atom arrives with
+ * `loc.start = 1`, `loc.end = 10` — offsets into that 27-character body.
+ * Those numbers are valid indices into any longer source, so they read as a
+ * real span pointing at unrelated text. Every `loc` therefore has to prove it
+ * belongs to the string this pass parsed before its offsets are believed.
+ */
+function isAuthoredLocation(loc, latex) {
+  return loc?.lexer?.input === latex;
+}
+
 function nodeSpan(node, latex) {
   let start = Number.POSITIVE_INFINITY;
   let end = Number.NEGATIVE_INFINITY;
@@ -397,7 +410,8 @@ function nodeSpan(node, latex) {
     if (
       value.loc &&
       Number.isInteger(value.loc.start) &&
-      Number.isInteger(value.loc.end)
+      Number.isInteger(value.loc.end) &&
+      isAuthoredLocation(value.loc, latex)
     ) {
       start = Math.min(start, value.loc.start);
       end = Math.max(end, value.loc.end);

package/dist/reference/references.js

@@ -28,7 +28,8 @@ function compareDiagnostics(left, right) {
   return severityRank(left.severity) - severityRank(right.severity) || left.code.localeCompare(right.code) || (left.lessonId ?? "").localeCompare(right.lessonId ?? "") || (left.key ?? "").localeCompare(right.key ?? "") || (left.definitionId ?? "").localeCompare(right.definitionId ?? "") || compareSourceSpans(left.source, right.source) || left.message.localeCompare(right.message);
 }
 function severityRank(severity) {
-  return severity === "error" ? 0 : 1;
+  if (severity === "error") return 0;
+  return severity === "warning" ? 1 : 2;
 }
 export {
   NOTATION_KEY_PATTERN,

package/dist/reference/registry.js

@@ -144,7 +144,7 @@ function buildNotationRegistry(rawInput) {
     if (!reachableDefinitions.has(candidate.id)) {
       diagnostics.push({
         code: "unused-definition",
-        severity: "warning",
+        severity: "info",
         message: `${candidate.id} is not reachable from any lesson reference`,
         key: candidate.input.key,
         lessonId: candidate.kind === "local" ? candidate.lesson.lessonId : void 0,

package/dist/reference/rehype-base-links.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Prefixes root-relative `<a href="/...">` links in rendered lesson content
+ * with the course's Astro `base` path.
+ *
+ * A course deployed under a subpath (any GitHub Pages *project* site, e.g.
+ * `base: '/my-course'`) gets that prefix applied automatically to Starlight's
+ * own generated navigation — sidebar, pagination, breadcrumbs — because those
+ * are rendered by Starlight's own `.astro` components, which call its
+ * internal `pathWithBase()` helper. They are **not** applied to anything
+ * produced by the Markdown/MDX → rehype pipeline: a lesson's own prose links
+ * (`[text](/other-lesson/)`), `remark-notation.mjs`'s equation cross-
+ * references, and `remark-citation.mjs`'s citation links are all root-
+ * relative absolute paths written or generated without the base in mind, so
+ * without this plugin every one of them 404s on a subpath deployment. A
+ * lesson's Starlight frontmatter (e.g. `hero.actions[].link`) is untouched
+ * either way — that YAML never enters this pipeline — so write those as
+ * paths relative to the current page instead.
+ *
+ * A no-op when the course has no base (`base` omitted or `'/'`, e.g. local
+ * dev or a GitHub *user/org* Pages site), so a course can wire this in
+ * unconditionally and it only does anything on the deployments that need it.
+ */
+export default function rehypeBaseLinks(base: any): (tree: any) => void;

package/dist/reference/rehype-base-links.mjs

@@ -0,0 +1,40 @@
+/**
+ * Prefixes root-relative `<a href="/...">` links in rendered lesson content
+ * with the course's Astro `base` path.
+ *
+ * A course deployed under a subpath (any GitHub Pages *project* site, e.g.
+ * `base: '/my-course'`) gets that prefix applied automatically to Starlight's
+ * own generated navigation — sidebar, pagination, breadcrumbs — because those
+ * are rendered by Starlight's own `.astro` components, which call its
+ * internal `pathWithBase()` helper. They are **not** applied to anything
+ * produced by the Markdown/MDX → rehype pipeline: a lesson's own prose links
+ * (`[text](/other-lesson/)`), `remark-notation.mjs`'s equation cross-
+ * references, and `remark-citation.mjs`'s citation links are all root-
+ * relative absolute paths written or generated without the base in mind, so
+ * without this plugin every one of them 404s on a subpath deployment. A
+ * lesson's Starlight frontmatter (e.g. `hero.actions[].link`) is untouched
+ * either way — that YAML never enters this pipeline — so write those as
+ * paths relative to the current page instead.
+ *
+ * A no-op when the course has no base (`base` omitted or `'/'`, e.g. local
+ * dev or a GitHub *user/org* Pages site), so a course can wire this in
+ * unconditionally and it only does anything on the deployments that need it.
+ */
+export default function rehypeBaseLinks(base) {
+  const prefix = base && base !== '/' ? base.replace(/\/+$/, '') : '';
+
+  return function transform(tree) {
+    if (!prefix) return;
+    visit(tree);
+  };
+
+  function visit(node) {
+    if (node.type === 'element' && node.tagName === 'a') {
+      const href = node.properties?.href;
+      if (typeof href === 'string' && href.startsWith('/') && !href.startsWith('//')) {
+        node.properties.href = prefix + href;
+      }
+    }
+    if (Array.isArray(node.children)) node.children.forEach(visit);
+  }
+}

package/dist/reference/remark-abbreviations.mjs

@@ -5,12 +5,15 @@
  * requires every abbreviation-shaped word in prose to either be universal or
  * carry a `content/abbreviations/*.md` entry, so the literal written form
  * (`abbr`, or one of its `aliases`) is itself the trigger. This plugin scans
- * ordinary prose for that literal text and wraps the **first** occurrence per
- * document in a real link (`/glossary/#abbr-<key>`, so it still navigates
- * with no JS) carrying the `data-abbr-key` an island script reads to render a
- * hover/click card, exactly the way `remarkCitation` wraps `[@id]` markers.
- * Later occurrences of the same term on the same page stay plain text, so a
- * common short word isn't turned into a link everywhere it appears.
+ * ordinary prose for that literal text and wraps **every** occurrence in a
+ * real link (`/glossary/#abbr-<key>`, so it still navigates with no JS)
+ * carrying the `data-abbr-key` an island script reads to render a hover/click
+ * card, exactly the way `remarkCitation` wraps `[@id]` markers. A reader who
+ * deep-links into a mid-page heading — the sidebar TOC, a heading anchor, an
+ * external link — sees the same hoverable cue no matter which occurrence they
+ * land on first, rather than only the earliest one in document order.
+ * `AbbreviationLayer.astro` already resolves every marker independently by
+ * `data-abbr-key`, so wrapping every occurrence needs no island-side change.
  *
  * Matches only ever come from the known table by construction, so unlike
  * citation's `[@id]` there is no "unknown id" failure path here.
@@ -118,10 +121,6 @@ export default function remarkAbbreviations(options = {}) {
     const { regex, keyByMatch } = buildMatcher(suppliedAbbreviations);
     if (!regex) return;
 
-    // Fresh per file, same lifetime as citation's own `pairs` Map: only the
-    // first occurrence of a given key on this page gets wrapped.
-    const usedKeys = new Set();
-
     const replaceText = (value) => {
       regex.lastIndex = 0;
       const output = [];
@@ -131,13 +130,12 @@ export default function remarkAbbreviations(options = {}) {
 
       while ((match = regex.exec(value))) {
         const key = keyByMatch.get(match[0]);
-        if (!key || usedKeys.has(key)) continue;
+        if (!key) continue;
 
         if (match.index > cursor) {
           output.push({ type: 'text', value: value.slice(cursor, match.index) });
         }
         output.push(termNode(key, match[0], base));
-        usedKeys.add(key);
         changed = true;
         cursor = match.index + match[0].length;
       }

package/dist/reference/render-lab-math.d.ts

@@ -9,7 +9,24 @@ interface RenderedLabMath {
     readonly slots: readonly string[];
     /** Notation keys the template resolved to, for diagnostics. */
     readonly keys: readonly string[];
+    /**
+     * Plain, copyable LaTeX — every explained glyph resolved to its bare
+     * symbol, every `\slot{name}{…}` replaced by `slotPlaceholder(name)` — so
+     * the island can substitute each slot's *current* live value in and keep
+     * `[data-notation-formula]`'s `data-latex` accurate as the reader drags a
+     * control, the same "click the equation to copy it" gesture a static
+     * lesson or glossary equation gets (`NotationLayer.astro`).
+     */
+    readonly plainLatexTemplate: string;
 }
+/**
+ * A slot's placeholder inside `plainLatexTemplate` — distinct from the
+ * numeric sentinel `sentinelFor` below uses internally (that one only has to
+ * survive a single notation-binding pass at build time; this one is the
+ * stable, name-keyed token an island substitutes with a live value at
+ * runtime, so it's exported for that purpose).
+ */
+declare function slotPlaceholder(name: string): string;
 /**
  * Compile a developer-authored lab math template the same way lesson `$$`
  * math is compiled: every identifier must resolve to a notation key in the
@@ -18,4 +35,4 @@ interface RenderedLabMath {
  */
 declare function renderLabMath(template: string, scope: readonly LabMathScopeDefinition[]): RenderedLabMath;
 
-export { type LabMathScopeDefinition, type RenderedLabMath, renderLabMath };
+export { type LabMathScopeDefinition, type RenderedLabMath, renderLabMath, slotPlaceholder };

package/dist/reference/render-lab-math.js

@@ -1,6 +1,9 @@
-import katex from "katex";
-import { resolveMathGlyphs } from "./math-glyphs.mjs";
+import katex from "./katex-delimiters.mjs";
+import { resolveMathGlyphs, stripNotationMarkers } from "./math-glyphs.mjs";
 import { createNotationKatexOptions } from "./katex-options.mjs";
+function slotPlaceholder(name) {
+  return `\u27E6${name}\u27E7`;
+}
 const SLOT_PATTERN = /\\slot\{([a-z][a-z0-9]*)\}\{((?:[^{}]|\{[^{}]*\})*)\}/g;
 const sentinelFor = (index) => `909909${index}.909909`;
 function renderLabMath(template, scope) {
@@ -30,6 +33,7 @@ function renderLabMath(template, scope) {
     );
   }
   let bound = result.latex;
+  let copyBound = result.latex;
   slots.forEach(({ name, fallback }, index) => {
     const sentinel = sentinelFor(index);
     if (!bound.includes(sentinel)) {
@@ -42,6 +46,7 @@ function renderLabMath(template, scope) {
       sentinel,
       `\\htmlData{lab-slot=${name}}{${fallback}}`
     );
+    copyBound = copyBound.replace(sentinel, slotPlaceholder(name));
   });
   const html = katex.renderToString(
     bound,
@@ -50,9 +55,11 @@ function renderLabMath(template, scope) {
   return {
     html,
     slots: slots.map(({ name }) => name),
-    keys: [...new Set(result.bindings.map(({ key }) => key))]
+    keys: [...new Set(result.bindings.map(({ key }) => key))],
+    plainLatexTemplate: stripNotationMarkers(copyBound)
   };
 }
 export {
-  renderLabMath
+  renderLabMath,
+  slotPlaceholder
 };

package/dist/reference/tables-validate.d.ts

@@ -5,7 +5,7 @@ import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } fr
 type TableDiagnosticCode = 'tab-invalid-key' | 'tab-duplicate-key' | 'tab-ref-resolves' | 'tab-key-unused';
 interface TableDiagnostic {
     readonly code: TableDiagnosticCode;
-    readonly severity: 'error' | 'warning';
+    readonly severity: 'error' | 'warning' | 'info';
     readonly message: string;
     readonly file?: string;
     readonly lessonId?: string;

package/dist/reference/types.d.ts

@@ -78,6 +78,13 @@ interface NotationLessonInput {
     readonly references: readonly NotationReferenceInput[];
     /** Original lesson body, retained for lossless loader adapters. */
     readonly body: string;
+    /**
+     * 1-based line in `source.file` where `body` starts. Gates scan the body, so
+     * every finding's index is body-relative; this is what turns one into a real
+     * location in the file. Optional so a hand-built input (a test, an adapter)
+     * stays valid — it then behaves as 1, the pre-0.7.1 behavior.
+     */
+    readonly bodyLine?: number;
     readonly source: SourceSpan;
 }
 interface NotationRegistryInput {
@@ -100,7 +107,7 @@ interface AbbreviationDefinitionInput {
     readonly source: SourceSpan;
 }
 type NotationDiagnosticCode = 'invalid-key' | 'duplicate-page' | 'duplicate-definition' | 'conflicting-definition' | 'undefined-reference' | 'reference-cycle' | 'unused-definition' | 'alignment-unknown-competency' | 'alignment-unknown-lesson' | 'alignment-introduction' | 'alignment-unavailable' | 'alignment-review-state' | 'gloss-collides-with-card';
-type DiagnosticSeverity = 'error' | 'warning';
+type DiagnosticSeverity = 'error' | 'warning' | 'info';
 interface NotationDiagnostic {
     readonly code: NotationDiagnosticCode;
     readonly severity: DiagnosticSeverity;

package/docs/VERSIONING.md

@@ -38,8 +38,8 @@ passed now fails.
 `CHANGELOG.md`).
 
 **PATCH** — a bug fix, a docs change, an internal refactor with no surface
-change, or a new **Tier-3 warning** (warnings never fail a build, so surfacing
-one does not break a consumer).
+change, or a new **Tier-3 warning/info diagnostic** (neither fails a build, so
+surfacing one does not break a consumer).
 
 ### Pre-1.0
 

package/docs/authoring/README.md

@@ -22,6 +22,12 @@ Two kinds of rule live here:
 - **Review-only** — nothing checks it automatically; a reviewer does. Breaking
   one is a review comment, not a broken build.
 
+Automated diagnostics use three severities. An **error** means the content is
+incorrect, ambiguous, unexplainable, or cannot render reliably and therefore
+blocks validation. A **warning** is non-blocking but marks a rule, readability,
+or maintenance problem that should be repaired. **Info** is optional advice;
+leaving it in place can be intentional and creates no repair debt.
+
 Every rule is written to be falsifiable: you can look at a lesson and say
 whether it complies.
 
@@ -43,7 +49,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) plus a number — and this shape:
+`V` visualizations, `C` versioning, `S` structure, `P` prose) plus a number — and this shape:
 
 > **N1 — One-line imperative.**
 > _Rationale._ Why the rule exists; the failure it prevents.
@@ -75,6 +81,7 @@ file table.
 | [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                        |
 | [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  |
@@ -97,7 +104,9 @@ file table.
 | [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 `\left`/`\right` sizing    | Build-enforced (`resolveMathGlyphs`)        |
+| [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)          | A nested delimiter is sized by the engine, never by hand             | Tier-3 warning (`delimiter-manual-size`)    |
 | [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                                 |
@@ -108,3 +117,4 @@ file table.
 | [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                                 |

package/docs/authoring/agents.md

@@ -7,7 +7,9 @@ particular to your layout.
 
 This is a guide, not a rule area. The enforceable rules are in
 [`notation.md`](notation.md) (`N`), [`visualizations.md`](visualizations.md)
-(`V`), and [`versioning.md`](versioning.md) (`C`). When the engine's behaviour
+(`V`), [`versioning.md`](versioning.md) (`C`),
+[`structure-rules.md`](structure-rules.md) (`S`), and [`prose.md`](prose.md)
+(`P`). When the engine's behaviour
 and a rule disagree, the engine wins — see [`README.md`](README.md).
 
 ## The loop
@@ -15,8 +17,10 @@ and a rule disagree, the engine wins — see [`README.md`](README.md).
 - **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
-  check <lesson> | --changed` is schema + refs + MDX→KaTeX, exits non-zero on an
-  error. Read those before opening files.
+  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. Commit the regenerated `build/` and