explico 0.6.0 → 0.7.0

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

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

package/dist/reference/gate-math.d.ts

@@ -26,8 +26,10 @@ interface MathGateDiagnostic {
      * than adding a second array the CLI has to know about.
      */
     readonly severity: 'error' | 'warning';
+    readonly code?: string;
     readonly file: string;
     readonly line?: number;
+    readonly column?: number;
     readonly token?: string;
     readonly message: string;
 }

package/dist/reference/gate-math.js

@@ -1,5 +1,6 @@
 import { resolveMathGlyphs, GlyphResolutionError } from "./math-glyphs.mjs";
 import { stripEquationLabels } from "./equations.mjs";
+import { lintDelimiterSizes } from "./delimiter-size.js";
 import { formulaGlyphScope, unknownFormulaScopeKeys } from "./gloss.js";
 const SEVERITY = {
   body: "error",
@@ -26,10 +27,14 @@ function mathSpans(body) {
     pattern.lastIndex = 0;
     let match;
     while (match = pattern.exec(searchable)) {
+      const latex = match[1] ?? "";
+      const latexOffset = match.index + match[0].indexOf(latex);
+      const before = body.slice(0, latexOffset);
+      const lastNewline = before.lastIndexOf("\n");
       spans.push({
-        // D7: `\label{eq:…}` is an identity marker, not math KaTeX parses.
-        latex: stripEquationLabels(match[1] ?? ""),
-        line: lineOf(body, match.index)
+        latex,
+        line: lineOf(body, latexOffset),
+        column: latexOffset - lastNewline
       });
     }
   }
@@ -53,10 +58,23 @@ function pageScope(lesson, sharedByKey) {
   }
   return scope;
 }
-function resolveInto(latex, scope, context, file, line, fix, out) {
+function resolveInto(latex, scope, context, file, line, column, fix, out) {
+  for (const diagnostic of lintDelimiterSizes(latex)) {
+    const locatedLine = line === void 0 ? void 0 : line + diagnostic.line - 1;
+    const locatedColumn = column === void 0 ? void 0 : diagnostic.line === 1 ? column + diagnostic.column - 1 : diagnostic.column;
+    out.push({
+      context,
+      code: diagnostic.code,
+      severity: "warning",
+      file,
+      ...locatedLine === void 0 ? {} : { line: locatedLine },
+      ...locatedColumn === void 0 ? {} : { column: locatedColumn },
+      message: diagnostic.message
+    });
+  }
   let result;
   try {
-    result = resolveMathGlyphs(latex, [...scope]);
+    result = resolveMathGlyphs(stripEquationLabels(latex), [...scope]);
   } catch (error) {
     out.push({
       context,
@@ -145,6 +163,7 @@ function gateContentMath(input) {
         "body",
         file,
         span.line,
+        span.column,
         BODY_FIX,
         diagnostics
       );
@@ -163,6 +182,7 @@ function gateContentMath(input) {
         "formula",
         file,
         void 0,
+        void 0,
         FORMULA_FIX,
         diagnostics
       );
@@ -183,6 +203,7 @@ function gateContentMath(input) {
       "formula",
       definition.source.file,
       void 0,
+      void 0,
       SHARED_FORMULA_FIX,
       diagnostics
     );
@@ -209,7 +230,8 @@ function gateContentMath(input) {
               scope,
               "assessment",
               `${assessmentId} (${item.id ?? "?"})`,
-              void 0,
+              span.line,
+              span.column,
               ASSESSMENT_FIX,
               diagnostics
             );

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/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 { 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

@@ -100,7 +100,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)          | 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                                 |
@@ -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