explico 0.5.0 → 0.7.0

package/dist/reference/consistency.js

@@ -17,23 +17,6 @@ function mathSpans(body) {
   }
   return spans;
 }
-function tableRows(body) {
-  const rows = [];
-  for (const line of stripCode(body).split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith("|") || !trimmed.slice(1).includes("|")) continue;
-    if (/^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
-    rows.push(line);
-  }
-  return rows;
-}
-const NUMERAL_RE = /(?<![\w.])-?\d+(?:\.\d+)?/g;
-function numeralCount(text) {
-  return (text.replace(/\\[a-zA-Z]+/g, " ").match(NUMERAL_RE) ?? []).length;
-}
-function isTagged(text) {
-  return /\[@[a-z0-9]/i.test(text) || /<!--\s*domain:/i.test(text);
-}
 function glyphMatcher(latex) {
   const trimmed = latex.trim();
   if (trimmed === "") return void 0;
@@ -141,31 +124,6 @@ function checkConventionSingleDefinition(input, out) {
     });
   }
 }
-function checkNumeralsTagged(input, out) {
-  for (const lesson of input.notationInput.lessons) {
-    if (input.lintIgnore.matches("numerals-tagged", lesson.lessonId)) continue;
-    let math = 0;
-    for (const span of mathSpans(lesson.body)) {
-      if (isTagged(span.latex)) continue;
-      math += numeralCount(span.latex);
-    }
-    let table = 0;
-    for (const row of tableRows(lesson.body)) {
-      if (isTagged(row)) continue;
-      table += numeralCount(row.replace(/\$[^$\n]*\$/g, " "));
-    }
-    const count = math + table;
-    if (count === 0) continue;
-    out.push({
-      code: "numerals-tagged",
-      severity: "warning",
-      lessonId: lesson.lessonId,
-      file: lesson.source.file,
-      count,
-      message: `${lesson.lessonId}: ${count} numeral(s) in $\u2026$ / result tables (${math} in math, ${table} in tables) are not tagged to a src/domain/ call or a source locator`
-    });
-  }
-}
 function checkWeakLocal(input, out) {
   for (const lesson of input.notationInput.lessons) {
     const spans = mathSpans(lesson.body).map((span) => span.latex);
@@ -177,7 +135,7 @@ function checkWeakLocal(input, out) {
       if (uses > 1) continue;
       out.push({
         code: "weak-local",
-        severity: "warning",
+        severity: "info",
         lessonId: lesson.lessonId,
         file: lesson.source.file,
         key: definition.key,
@@ -228,7 +186,7 @@ function checkGlossWantsPromoting(input, out) {
     if (input.lintIgnore.matches("gloss-wants-promoting", glyph)) continue;
     out.push({
       code: "gloss-wants-promoting",
-      severity: "warning",
+      severity: "info",
       glyph,
       message: `gloss ${JSON.stringify(glyph)} (${label}) is declared on ${keys.size} entries (${[...keys].sort().join(", ")}); a meaning reused this widely wants promoting to a card`
     });
@@ -250,7 +208,7 @@ function checkCardWantsDemoting(input, out) {
     }
     out.push({
       code: "card-wants-demoting",
-      severity: "warning",
+      severity: "info",
       key: definition.key,
       file: definition.source.file,
       count: words,
@@ -381,7 +339,6 @@ const CHECKS = [
   checkGlyphUniqueness,
   checkNotationUnits,
   checkConventionSingleDefinition,
-  checkNumeralsTagged,
   checkWeakLocal,
   checkNotationSourceLocator,
   checkGlossWantsPromoting,
@@ -403,7 +360,6 @@ function consistencyCounts(diagnostics) {
     "notation-units": 0,
     "units-vocab": 0,
     "convention-single-definition": 0,
-    "numerals-tagged": 0,
     "weak-local": 0,
     "notation-source-locator": 0,
     "gloss-wants-promoting": 0,

package/dist/reference/delimiter-size.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Rule N17: nested scalable delimiters must make their hierarchy visible.
+ *
+ * This deliberately parses only sizing syntax. It does not decide whether a
+ * parenthesis, bracket, or brace is semantic, and it never recommends changing
+ * one delimiter shape into another. N16's alternating-shape preference remains
+ * a review-only authoring concern.
+ */
+declare const DELIMITER_SIZE_DIAGNOSTIC_CODE: "delimiter-size-hierarchy";
+type DelimiterSizeName = 'automatic' | 'big' | 'Big' | 'bigg' | 'Bigg';
+interface DelimiterSizeSuggestion {
+    readonly size: Exclude<DelimiterSizeName, 'automatic' | 'big'>;
+    readonly open: string;
+    readonly close: string;
+    readonly latex: string;
+}
+interface DelimiterSizeDiagnostic {
+    readonly code: typeof DELIMITER_SIZE_DIAGNOSTIC_CODE;
+    readonly severity: 'warning';
+    readonly offset: number;
+    readonly line: number;
+    readonly column: number;
+    readonly outerSize: DelimiterSizeName;
+    readonly nestedSize: DelimiterSizeName;
+    readonly suggestion?: DelimiterSizeSuggestion;
+    readonly message: string;
+}
+/**
+ * Warn when a scalable outer pair is not at least one manual size level above
+ * everything nested inside it. `\left` and `\big` form the baseline level;
+ * progressively larger levels are `\Big`, `\bigg`, and `\Bigg`.
+ *
+ * Only `()`, `[]`, and `\{\}` are parsed. Bare delimiters are intentionally
+ * ignored: N15 owns that separate error, while ordinary semantic notation
+ * such as `f(x)` and `\mathbb{E}[X]` must not trigger this size-only linter.
+ */
+declare function lintDelimiterSizes(latex: string): DelimiterSizeDiagnostic[];
+
+export { DELIMITER_SIZE_DIAGNOSTIC_CODE, type DelimiterSizeDiagnostic, type DelimiterSizeName, type DelimiterSizeSuggestion, lintDelimiterSizes };

package/dist/reference/delimiter-size.js

@@ -0,0 +1,177 @@
+const DELIMITER_SIZE_DIAGNOSTIC_CODE = "delimiter-size-hierarchy";
+const SIZE_SPECS = [
+  {
+    name: "automatic",
+    rank: 1,
+    openCommand: "\\left",
+    closeCommand: "\\right",
+    kind: "automatic"
+  },
+  {
+    name: "big",
+    rank: 1,
+    openCommand: "\\bigl",
+    closeCommand: "\\bigr",
+    kind: "manual"
+  },
+  {
+    name: "Big",
+    rank: 2,
+    openCommand: "\\Bigl",
+    closeCommand: "\\Bigr",
+    kind: "manual"
+  },
+  {
+    name: "bigg",
+    rank: 3,
+    openCommand: "\\biggl",
+    closeCommand: "\\biggr",
+    kind: "manual"
+  },
+  {
+    name: "Bigg",
+    rank: 4,
+    openCommand: "\\Biggl",
+    closeCommand: "\\Biggr",
+    kind: "manual"
+  }
+];
+const COMMAND_SPECS = SIZE_SPECS.flatMap((spec) => [
+  { ...spec, command: spec.openCommand, tokenKind: "open" },
+  { ...spec, command: spec.closeCommand, tokenKind: "close" }
+]).sort((left, right) => right.command.length - left.command.length);
+const SUGGESTION_BY_RANK = new Map(
+  SIZE_SPECS.filter((spec) => spec.rank >= 2).map((spec) => [spec.rank, spec])
+);
+function delimiterAt(latex, offset, kind) {
+  const candidates = kind === "open" ? ["\\{", "(", "["] : ["\\}", ")", "]"];
+  for (const delimiter of candidates) {
+    if (latex.startsWith(delimiter, offset)) {
+      return { delimiter, end: offset + delimiter.length };
+    }
+  }
+  return void 0;
+}
+function tokenAt(latex, offset) {
+  if (latex[offset] !== "\\") return void 0;
+  for (const spec of COMMAND_SPECS) {
+    if (!latex.startsWith(spec.command, offset)) continue;
+    const afterCommand = offset + spec.command.length;
+    if (/[A-Za-z]/.test(latex[afterCommand] ?? "")) continue;
+    let delimiterOffset = afterCommand;
+    while (/\s/.test(latex[delimiterOffset] ?? "")) delimiterOffset += 1;
+    const delimiter = delimiterAt(latex, delimiterOffset, spec.tokenKind);
+    if (!delimiter) continue;
+    return {
+      kind: spec.tokenKind,
+      pairKind: spec.kind,
+      rank: spec.rank,
+      size: spec.name,
+      delimiter: delimiter.delimiter,
+      offset,
+      end: delimiter.end
+    };
+  }
+  return void 0;
+}
+function pairMatches(open, close) {
+  return open.kind === "open" && close.kind === "close" && open.pairKind === close.pairKind && open.rank === close.rank;
+}
+function isEscaped(latex, offset) {
+  let slashes = 0;
+  for (let index = offset - 1; index >= 0 && latex[index] === "\\"; index -= 1) {
+    slashes += 1;
+  }
+  return slashes % 2 === 1;
+}
+function parseDelimiterPairs(latex) {
+  const roots = [];
+  const stack = [];
+  for (let offset = 0; offset < latex.length; offset += 1) {
+    if (latex[offset] === "%" && !isEscaped(latex, offset)) {
+      const newline = latex.indexOf("\n", offset + 1);
+      if (newline === -1) break;
+      offset = newline;
+      continue;
+    }
+    const token = isEscaped(latex, offset) ? void 0 : tokenAt(latex, offset);
+    if (!token) continue;
+    offset = token.end - 1;
+    if (token.kind === "open") {
+      const pair2 = { open: token, children: [] };
+      const parent = stack[stack.length - 1];
+      if (parent) parent.children.push(pair2);
+      else roots.push(pair2);
+      stack.push(pair2);
+      continue;
+    }
+    const pair = stack[stack.length - 1];
+    if (!pair || !pairMatches(pair.open, token)) return void 0;
+    pair.close = token;
+    stack.pop();
+  }
+  return stack.length === 0 ? roots : void 0;
+}
+function lineAndColumn(source, offset) {
+  const before = source.slice(0, offset);
+  const lastNewline = before.lastIndexOf("\n");
+  return {
+    line: before.split("\n").length,
+    column: offset - lastNewline
+  };
+}
+function sizeName(rank) {
+  return SUGGESTION_BY_RANK.get(rank)?.name ?? "Bigg";
+}
+function suggestionFor(pair, requiredRank) {
+  const close = pair.close;
+  const spec = SUGGESTION_BY_RANK.get(requiredRank);
+  if (!close || !spec || spec.name === "automatic" || spec.name === "big") {
+    return void 0;
+  }
+  return {
+    size: spec.name,
+    open: `${spec.openCommand}${pair.open.delimiter}`,
+    close: `${spec.closeCommand}${close.delimiter}`,
+    latex: `${spec.openCommand}${pair.open.delimiter} ... ${spec.closeCommand}${close.delimiter}`
+  };
+}
+function lintDelimiterSizes(latex) {
+  const roots = parseDelimiterPairs(latex);
+  if (!roots) return [];
+  const diagnostics = [];
+  const assess = (pair) => {
+    let largestNestedRequirement = 0;
+    let representativeNestedSize = "automatic";
+    for (const child of pair.children) {
+      const childRequired = assess(child);
+      if (childRequired > largestNestedRequirement) {
+        largestNestedRequirement = childRequired;
+        representativeNestedSize = sizeName(childRequired);
+      }
+    }
+    const requiredRank = largestNestedRequirement === 0 ? pair.open.rank : largestNestedRequirement + 1;
+    pair.requiredRank = Math.max(pair.open.rank, requiredRank);
+    if (largestNestedRequirement > 0 && pair.open.rank < requiredRank) {
+      const location = lineAndColumn(latex, pair.open.offset);
+      const suggestion = suggestionFor(pair, requiredRank);
+      diagnostics.push({
+        code: DELIMITER_SIZE_DIAGNOSTIC_CODE,
+        severity: "warning",
+        offset: pair.open.offset,
+        ...location,
+        outerSize: pair.open.size,
+        nestedSize: representativeNestedSize,
+        ...suggestion ? { suggestion } : {},
+        message: suggestion ? `Outer delimiters are not larger than their nested pair. Use ${suggestion.latex}; preserve the original opening and closing delimiter shapes (rule N17).` : `Outer delimiters are not larger than their nested pair, and no larger standard manual delimiter size remains. Preserve the original opening and closing shapes and restructure the expression if necessary (rule N17).`
+      });
+    }
+    return pair.requiredRank;
+  };
+  for (const root of roots) assess(root);
+  return diagnostics.sort((left, right) => left.offset - right.offset);
+}
+export {
+  DELIMITER_SIZE_DIAGNOSTIC_CODE,
+  lintDelimiterSizes
+};

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

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

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

@@ -4,7 +4,7 @@
  * - `eq-duplicate-key` (Tier 1, error): an `eq:` key is unique per lesson.
  * - `eq-ref-resolves` (Tier 1, error): every `[[eq-key]]` / `[[slug#eq-key]]`
  *   points at a display equation that carries `\label{eq:key}`.
- * - `eq-key-unused` (Tier 3, warning): a labelled equation never referenced.
+ * - `eq-key-unused` (info): a labelled equation is never referenced.
  *
  * The remark pass enforces the same rules on the render path; this gives the
  * fast `pnpm validate:content` the same coverage and feeds the manifest.
@@ -26,7 +26,7 @@ interface EquationRefRecord {
 type EquationDiagnosticCode = 'eq-duplicate-key' | 'eq-ref-resolves' | 'eq-key-unused';
 interface EquationDiagnostic {
     readonly code: EquationDiagnosticCode;
-    readonly severity: 'error' | 'warning';
+    readonly severity: 'error' | 'warning' | 'info';
     readonly message: string;
     readonly file?: string;
     readonly lessonId?: string;

package/dist/reference/equations-validate.js

@@ -73,7 +73,7 @@ function validateEquations(lessons) {
     if (referenced.has(`${label.slug}#${label.key}`)) continue;
     diagnostics.push({
       code: "eq-key-unused",
-      severity: "warning",
+      severity: "info",
       message: `${label.lessonId} labels eq:${label.key} (${label.number}) but nothing references it with [[eq-${label.key}]]`,
       file: label.slug,
       lessonId: label.lessonId,

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-heading-length.d.ts

@@ -0,0 +1,12 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import { NotationLessonInput } from './types.js';
+
+declare const HEADING_LENGTH_LIMIT = 65;
+/**
+ * Scan every lesson body for a heading or a keyed float's title running past
+ * `HEADING_LENGTH_LIMIT` characters. Returns one `MathGateDiagnostic`
+ * (context `'structure'`, always an error) per finding.
+ */
+declare function gateHeadingLength(lessons: readonly NotationLessonInput[]): MathGateDiagnostic[];
+
+export { HEADING_LENGTH_LIMIT, gateHeadingLength };

package/dist/reference/gate-heading-length.js

@@ -0,0 +1,79 @@
+import { stripFencedCode } from "./equations.mjs";
+import { lineOf } from "./gate-prose-notation.js";
+const HEADING_LENGTH_LIMIT = 65;
+const HEADING_LINE = /^[ \t]{0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/gm;
+const TITLE_ATTRIBUTE_BY_TAG = {
+  Figure: "title",
+  Diagram: "label",
+  Memo: "title",
+  ShortNote: "title"
+};
+function readAttribute(attributesSource, name) {
+  const pattern = new RegExp(`\\b${name}\\s*=\\s*(["'])([^"']*)\\1`);
+  const match = pattern.exec(attributesSource);
+  return match ? match[2] : void 0;
+}
+function overLimitMessage(kind, text) {
+  return `${kind} ${JSON.stringify(text)} is ${text.length} characters, over the ${HEADING_LENGTH_LIMIT}-character limit (rule S1). Shorten it and move the rest into the paragraph or caption that follows.`;
+}
+function headingFindings(text) {
+  const out = [];
+  const re = new RegExp(HEADING_LINE.source, HEADING_LINE.flags);
+  let match;
+  while (match = re.exec(text)) {
+    const level = match[1]?.length ?? 1;
+    const title = (match[2] ?? "").trim();
+    if (title.length > HEADING_LENGTH_LIMIT) {
+      out.push({
+        index: match.index,
+        token: title,
+        message: overLimitMessage(`${"#".repeat(level)} heading`, title)
+      });
+    }
+  }
+  return out;
+}
+function floatTitleFindings(text) {
+  const out = [];
+  for (const [tagName, attribute] of Object.entries(TITLE_ATTRIBUTE_BY_TAG)) {
+    const opening = new RegExp(`<${tagName}\\b([^>]*)>`, "g");
+    let match;
+    while (match = opening.exec(text)) {
+      const value = readAttribute(match[1] ?? "", attribute)?.trim();
+      if (value && value.length > HEADING_LENGTH_LIMIT) {
+        out.push({
+          index: match.index,
+          token: value,
+          message: overLimitMessage(`<${tagName} ${attribute}>`, value)
+        });
+      }
+    }
+  }
+  return out;
+}
+function findingsIn(text) {
+  return [...headingFindings(text), ...floatTitleFindings(text)].sort(
+    (a, b) => a.index - b.index
+  );
+}
+function gateHeadingLength(lessons) {
+  const diagnostics = [];
+  for (const lesson of lessons) {
+    const text = stripFencedCode(lesson.body);
+    for (const finding of findingsIn(text)) {
+      diagnostics.push({
+        context: "structure",
+        severity: "error",
+        file: lesson.source.file,
+        line: lineOf(lesson.body, finding.index),
+        token: finding.token,
+        message: finding.message
+      });
+    }
+  }
+  return diagnostics;
+}
+export {
+  HEADING_LENGTH_LIMIT,
+  gateHeadingLength
+};

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

@@ -1,7 +1,7 @@
 import { NotationRegistryInput, NotationLessonInput } from './types.js';
 
 interface MathGateDiagnostic {
-    readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation';
+    readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation' | 'structure';
     /**
      * Body / component-slot math blocks the build (the render path needs every
      * glyph resolved for the KaTeX trust callback). `formula` joined it at D15:
@@ -19,11 +19,17 @@ interface MathGateDiagnostic {
      * same change that introduced the check. `abbreviation` (N14,
      * `gate-abbreviations.ts`) is the same "ships straight as an error" story
      * for a different shape of plain-text token — an unexplained acronym or
-     * dotted abbreviation, rather than a mis-typed quantity/unit.
+     * dotted abbreviation, rather than a mis-typed quantity/unit. `structure`
+     * (S1, `gate-heading-length.ts`) is unrelated to notation — it caps how
+     * long a heading or a keyed float's title may run — but reuses this same
+     * diagnostic shape and the one `manifest.diagnostics.math` array rather
+     * 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,12 +1,14 @@
 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",
   formula: "error",
   assessment: "error",
   prose: "error",
-  abbreviation: "error"
+  abbreviation: "error",
+  structure: "error"
 };
 const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
 const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
@@ -25,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
       });
     }
   }
@@ -52,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,
@@ -144,6 +163,7 @@ function gateContentMath(input) {
         "body",
         file,
         span.line,
+        span.column,
         BODY_FIX,
         diagnostics
       );
@@ -162,6 +182,7 @@ function gateContentMath(input) {
         "formula",
         file,
         void 0,
+        void 0,
         FORMULA_FIX,
         diagnostics
       );
@@ -182,6 +203,7 @@ function gateContentMath(input) {
       "formula",
       definition.source.file,
       void 0,
+      void 0,
       SHARED_FORMULA_FIX,
       diagnostics
     );
@@ -208,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/math-glyphs.d.mts

@@ -42,6 +42,14 @@ export function resolveMathGlyphs(latex: string, definitions: Array<{
  * Used by the `operator-explained` consistency check (rule N8); the glyph
  * resolver still skips operator bodies whole.
  *
+ * The span handed in is raw lesson source, so it may still carry
+ * `\explain{key}{…}` / `\slot{key}{…}` markers around other symbols in the
+ * same expression — `\explain` is not valid KaTeX, so parsing it unstripped
+ * throws and this function used to swallow that as "no operators here" for
+ * the whole span, silently hiding any `\operatorname{…}` alongside the
+ * marker. `stripNotationMarkers` removes just the marker wrapper first so
+ * the scan sees plain, parseable math.
+ *
  * @param {string} latex
  * @returns {Array<{ name: string, source: 'named' | 'operatorname' }>}
  */
@@ -60,6 +68,10 @@ export function collectOperators(latex: string): Array<{
  * `roman-label-explained` consistency check (rule N10); the glyph resolver
  * still skips `\mathrm{…}` bodies whole ([N3](../../docs/authoring/notation.md#n3)).
  *
+ * Same `stripNotationMarkers` preprocessing as {@link collectOperators}, and
+ * for the same reason: an unstripped `\explain{…}{…}` elsewhere in the span
+ * fails the raw KaTeX parse and used to silently drop every label in it.
+ *
  * @param {string} latex
  * @returns {Array<{ name: string }>}
  */