explico 0.2.0 → 0.3.0

package/dist/compiler/manifest.d.ts

@@ -1,13 +1,17 @@
 import { CurriculumIssue } from '../curriculum/validation.js';
 import { ConsistencyDiagnostic } from '../reference/consistency.js';
 import { EquationLabelRecord, EquationDiagnostic } from '../reference/equations-validate.js';
+import { TableLabelRecord, TableDiagnostic } from '../reference/tables-validate.js';
+import { FigureLabelRecord, FigureDiagnostic } from '../reference/figures-validate.js';
 import { MathGateDiagnostic } from '../reference/gate-math.js';
 import { GlyphScopeEntry } from '../reference/gloss.js';
 import { NotationDefinitionRecord, NotationPageBundle, NotationBacklink, NotationDiagnostic, EditorialStatus, NotationGlossEntry } from '../reference/types.js';
 import { CourseConfig } from './course-config.js';
+import { KnowledgeVersionDiagnostic } from './knowledge-version.js';
 import { SidebarGroup } from './lesson-derivation.js';
 import './collections.js';
 import '../reference/lint-ignore.js';
+import '../reference/keyed-float-validate.js';
 
 /**
  * The one compiler manifest (Phase D5).
@@ -45,8 +49,16 @@ import '../reference/lint-ignore.js';
  * `diagnostics.consistency` (Tier-3 corpus checks).
  * v3 (D7): `equations` (labelled display equations + cross-page number table),
  * `lessons[].equations`, and `diagnostics.equations`.
+ * v4 (F-tables-figures): `tables`/`figures` (same shape as `equations`, for
+ * `<Table>`/`<Figure>`), `lessons[].tables`/`lessons[].figures`, and
+ * `diagnostics.tables`/`diagnostics.figures`.
+ * v5 (about): `about` (engine identity from `explico`'s `package.json`, the
+ * course's reader-facing `about` block, and the knowledge version resolved
+ * against `content/CHANGELOG.md`) and `diagnostics.knowledge`.
+ * v6 (chapter numbering): `lessons[].chapter` — the lesson's 1-based course
+ * ordinal, the chapter in every equation/table/figure number (`(2.1)`).
  */
-declare const MANIFEST_SCHEMA_VERSION = 3;
+declare const MANIFEST_SCHEMA_VERSION = 6;
 declare const MANIFEST_PATH: string;
 interface ManifestCitation {
     readonly id: string;
@@ -95,6 +107,12 @@ interface ManifestLesson {
     readonly id: string;
     /** Docs-loader slug, e.g. `bonds/price-yield-relationship`. */
     readonly slug: string;
+    /**
+     * The lesson's 1-based ordinal in the course (merged track order, then any
+     * unranked lessons by slug). It is the chapter in every equation, table, and
+     * figure number on the page — `(2.1)` is the first equation of chapter 2.
+     */
+    readonly chapter: number;
     readonly file: string;
     readonly title: string;
     readonly description: string;
@@ -113,6 +131,16 @@ interface ManifestLesson {
         readonly key: string;
         readonly number: string;
     }[];
+    /** Keyed `<Table>` elements in appearance order. */
+    readonly tables: readonly {
+        readonly key: string;
+        readonly number: string;
+    }[];
+    /** Keyed `<Figure>` elements in appearance order. */
+    readonly figures: readonly {
+        readonly key: string;
+        readonly number: string;
+    }[];
     readonly notation: {
         readonly bindings: readonly {
             readonly key: string;
@@ -124,8 +152,39 @@ interface ManifestLesson {
         readonly resolution: readonly ManifestNotationResolution[];
     };
 }
+/** The reader-facing "about this material" bundle — the `[?]` panel's data. */
+interface ManifestAbout {
+    /** `explico`'s own identity, from its `package.json` (the version's golden source). */
+    readonly engine: {
+        readonly name: string;
+        readonly version: string;
+        readonly homepage?: string;
+    };
+    readonly material: {
+        readonly name: string;
+        readonly summary: string;
+    };
+    /** The course's knowledge version — semver over the content, engine-independent. */
+    readonly knowledge: {
+        readonly version: string;
+        /** Date of the newest `content/CHANGELOG.md` entry, if it has one. */
+        readonly date?: string;
+        /** Bullet notes from that entry. */
+        readonly notes: readonly string[];
+        /** Content fingerprint at compile time — ties the shown version to a build. */
+        readonly contentTree: string;
+    };
+    readonly authors: readonly {
+        readonly name: string;
+        readonly contact?: string;
+    }[];
+    readonly disclaimer: string;
+    readonly changelogHref?: string;
+}
 interface Manifest {
     readonly schemaVersion: number;
+    /** Reader-facing identity + versions (the `[?]` About panel). */
+    readonly about: ManifestAbout;
     readonly notation: {
         readonly definitions: readonly NotationDefinitionRecord[];
         readonly bundles: readonly NotationPageBundle[];
@@ -147,6 +206,16 @@ interface Manifest {
         /** `slug -> { eqKey: number }` — passed to `remarkNotation` for `[[slug#eq:key]]`. */
         readonly numbersBySlug: Record<string, Record<string, string>>;
     };
+    /** Keyed-float identity for `<Table>` — same shape as `equations`. */
+    readonly tables: {
+        readonly labels: readonly TableLabelRecord[];
+        readonly numbersBySlug: Record<string, Record<string, string>>;
+    };
+    /** Keyed-float identity for `<Figure>` — same shape as `equations`. */
+    readonly figures: {
+        readonly labels: readonly FigureLabelRecord[];
+        readonly numbersBySlug: Record<string, Record<string, string>>;
+    };
     readonly diagnostics: {
         readonly curriculum: readonly CurriculumIssue[];
         readonly notation: readonly NotationDiagnostic[];
@@ -154,8 +223,14 @@ interface Manifest {
         readonly math: readonly MathGateDiagnostic[];
         /** Tier-3 corpus consistency checks (D6). Warnings only. */
         readonly consistency: readonly ConsistencyDiagnostic[];
+        /** Knowledge-version checks (C3): `about.version` vs `content/CHANGELOG.md`. Warnings only. */
+        readonly knowledge: readonly KnowledgeVersionDiagnostic[];
         /** Equation-identity checks (D7): `eq-duplicate-key`, `eq-ref-resolves` (error); `eq-key-unused` (warning). */
         readonly equations: readonly EquationDiagnostic[];
+        /** `<Table>` identity checks (F-tables-figures) — same codes, `tab-` prefixed. */
+        readonly tables: readonly TableDiagnostic[];
+        /** `<Figure>` identity checks (F-tables-figures) — same codes, `fig-` prefixed. */
+        readonly figures: readonly FigureDiagnostic[];
     };
     readonly hashes: {
         /** `sha256` of every content source file, keyed by repo-relative path. */
@@ -184,4 +259,4 @@ declare function readManifestSync(): Manifest;
  */
 declare function loadManifest(courseConfig?: CourseConfig): Promise<Manifest>;
 
-export { MANIFEST_PATH, MANIFEST_SCHEMA_VERSION, type Manifest, type ManifestCitation, type ManifestLesson, type ManifestLessonNotation, type ManifestNotationResolution, type PrereqEdge, compileManifest, loadManifest, readManifestSync, serializeManifest, writeManifest };
+export { MANIFEST_PATH, MANIFEST_SCHEMA_VERSION, type Manifest, type ManifestAbout, type ManifestCitation, type ManifestLesson, type ManifestLessonNotation, type ManifestNotationResolution, type PrereqEdge, compileManifest, loadManifest, readManifestSync, serializeManifest, writeManifest };

package/dist/compiler/manifest.js

@@ -6,6 +6,7 @@ import {
   readdirSync,
   writeFileSync
 } from "node:fs";
+import { createRequire } from "node:module";
 import { dirname, join, relative } from "node:path";
 import { parseFrontmatter } from "@astrojs/markdown-remark";
 import {
@@ -18,6 +19,12 @@ import { validateNotationAlignment } from "../reference/curriculum-alignment.js"
 import {
   validateEquations
 } from "../reference/equations-validate.js";
+import {
+  validateTables
+} from "../reference/tables-validate.js";
+import {
+  validateFigures
+} from "../reference/figures-validate.js";
 import {
   gateContentMath
 } from "../reference/gate-math.js";
@@ -25,6 +32,9 @@ import { loadLintIgnore } from "../reference/lint-ignore.js";
 import { buildNotationRegistry } from "../reference/registry.js";
 import { formulaGlyphScope } from "../reference/gloss.js";
 import { resolveReferenceId } from "../reference/references.js";
+import {
+  resolveKnowledgeVersion
+} from "./knowledge-version.js";
 import {
   loadCurriculumCatalog,
   loadNotationDefinitions,
@@ -35,12 +45,22 @@ import {
 import {
   buildSidebar,
   deriveSources,
-  isLessonSlug
+  isLessonSlug,
+  lessonIdFromSlug
 } from "./lesson-derivation.js";
-const MANIFEST_SCHEMA_VERSION = 3;
+const MANIFEST_SCHEMA_VERSION = 6;
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const MANIFEST_PATH = join(REPOSITORY_ROOT, "build", "manifest.json");
+let enginePackage;
+function readEnginePackage() {
+  if (!enginePackage) {
+    enginePackage = createRequire(import.meta.url)(
+      "explico/package.json"
+    );
+  }
+  return enginePackage;
+}
 const CITE_PATTERN = /\[@([a-z0-9][a-z0-9.-]*)(?:;[ \t\r\n]*([^\]]*))?\]/g;
 function lessonCitations(body) {
   const withoutCode = body.replace(/```[\s\S]*?```/g, "").replace(/`[^`\n]*`/g, "");
@@ -156,6 +176,11 @@ function lessonFrontmatterById() {
   return result;
 }
 async function compileManifest(courseConfig) {
+  if (courseConfig.about === void 0 || courseConfig.about.version === void 0 || courseConfig.about.authors === void 0 || courseConfig.about.disclaimer === void 0) {
+    throw new Error(
+      "course.config.ts is missing a complete `about` block (required since explico 0.3.0): `about: { version, authors: [{ name }], disclaimer, materialName?, summary?, changelogHref? }`. See docs/authoring/migrating.md (\xA7 0.2.x \u2192 0.3.0) in the installed package."
+    );
+  }
   const [catalog, notationInput] = await Promise.all([
     loadCurriculumCatalog(),
     loadNotationRegistryInput()
@@ -202,20 +227,48 @@ async function compileManifest(courseConfig) {
     catalog.lessons.map((lesson) => [lesson.id, lesson])
   );
   const frontmatterById = lessonFrontmatterById();
-  const equationValidation = validateEquations(
-    notationInput.lessons.map((lesson) => ({
-      lessonId: lesson.lessonId,
-      slug: lesson.lessonId.replace(/\./g, "/"),
-      file: lesson.source.file,
-      body: lesson.body
-    }))
+  const lessonSlugs = [...notationInput.lessons].map((lesson) => lesson.lessonId.replace(/\./g, "/")).sort();
+  const sidebar = buildSidebar(
+    catalog.tracks.map((track) => ({ id: track.id, lessons: track.lessons })),
+    lessonSlugs,
+    courseConfig.sections
   );
+  const chapterByLessonId = /* @__PURE__ */ new Map();
+  let chapterCursor = 0;
+  for (const group of sidebar) {
+    for (const item of group.items) {
+      if (typeof item !== "string") continue;
+      chapterByLessonId.set(lessonIdFromSlug(item), ++chapterCursor);
+    }
+  }
+  const keyedFloatLessonInputs = notationInput.lessons.map((lesson) => ({
+    lessonId: lesson.lessonId,
+    slug: lesson.lessonId.replace(/\./g, "/"),
+    file: lesson.source.file,
+    body: lesson.body,
+    chapter: chapterByLessonId.get(lesson.lessonId)
+  }));
+  const equationValidation = validateEquations(keyedFloatLessonInputs);
   const equationsBySlug = new Map(
     Object.entries(equationValidation.numbersBySlug).map(([slug, table]) => [
       slug,
       Object.entries(table).map(([key, number]) => ({ key, number }))
     ])
   );
+  const tableValidation = validateTables(keyedFloatLessonInputs);
+  const tablesBySlug = new Map(
+    Object.entries(tableValidation.numbersBySlug).map(([slug, table]) => [
+      slug,
+      Object.entries(table).map(([key, number]) => ({ key, number }))
+    ])
+  );
+  const figureValidation = validateFigures(keyedFloatLessonInputs);
+  const figuresBySlug = new Map(
+    Object.entries(figureValidation.numbersBySlug).map(([slug, table]) => [
+      slug,
+      Object.entries(table).map(([key, number]) => ({ key, number }))
+    ])
+  );
   const lessons = [];
   for (const notationLesson of notationInput.lessons) {
     const id = notationLesson.lessonId;
@@ -229,6 +282,10 @@ async function compileManifest(courseConfig) {
     lessons.push({
       id,
       slug: id.replace(/\./g, "/"),
+      // 0 = the lesson is not placed in any configured section; a curriculum
+      // diagnostic covers that separately, and both numbering paths then fall
+      // back to the legacy `##`-section scheme.
+      chapter: chapterByLessonId.get(id) ?? 0,
       file: notationLesson.source.file,
       title: frontmatter.title,
       description: frontmatter.description,
@@ -240,6 +297,8 @@ async function compileManifest(courseConfig) {
       sources: deriveSources(notationLesson.body),
       citations: lessonCitations(notationLesson.body),
       equations: equationsBySlug.get(id.replace(/\./g, "/")) ?? [],
+      tables: tablesBySlug.get(id.replace(/\./g, "/")) ?? [],
+      figures: figuresBySlug.get(id.replace(/\./g, "/")) ?? [],
       prereqEdges: sortEdges(
         teaches.flatMap(
           (to) => (prerequisitesById.get(to) ?? []).filter((from) => !teaches.includes(from)).map((from) => ({ from, to }))
@@ -264,7 +323,8 @@ async function compileManifest(courseConfig) {
     specs: loadNotationSpecs(),
     catalog,
     lintIgnore: loadLintIgnore(),
-    conventions: courseConfig.conventions
+    conventions: courseConfig.conventions,
+    ...courseConfig.operators === void 0 ? {} : { operators: courseConfig.operators }
   });
   const rawNotation = [...loadNotationDefinitions()].sort(
     (a, b) => String(a.key).localeCompare(String(b.key))
@@ -272,14 +332,40 @@ async function compileManifest(courseConfig) {
   const competencies = catalog.competencies.map((entry) => ({ ...entry })).sort(byId);
   const sources = [...loadSourceRecords()].sort(byId);
   const tracks = catalog.tracks.map((entry) => ({ ...entry })).sort(byId);
-  const lessonSlugs = [...notationInput.lessons].map((lesson) => lesson.lessonId.replace(/\./g, "/")).sort();
-  const sidebar = buildSidebar(
-    catalog.tracks.map((track) => ({ id: track.id, lessons: track.lessons })),
-    lessonSlugs,
-    courseConfig.sections
-  );
+  const hashes = contentHashes();
+  const knowledgeChangelogPath = join(CONTENT_ROOT, "CHANGELOG.md");
+  const knowledge = resolveKnowledgeVersion({
+    changelogText: existsSync(knowledgeChangelogPath) ? readFileSync(knowledgeChangelogPath, "utf8") : void 0,
+    declaredVersion: courseConfig.about.version,
+    file: relative(REPOSITORY_ROOT, knowledgeChangelogPath).replace(/\\/g, "/")
+  });
+  const enginePkg = readEnginePackage();
+  const about = {
+    engine: {
+      name: enginePkg.name,
+      version: enginePkg.version,
+      ...enginePkg.homepage === void 0 ? {} : { homepage: enginePkg.homepage }
+    },
+    material: {
+      name: courseConfig.about.materialName ?? courseConfig.title,
+      summary: courseConfig.about.summary ?? courseConfig.description
+    },
+    knowledge: {
+      version: knowledge.version,
+      ...knowledge.latest?.date === void 0 ? {} : { date: knowledge.latest.date },
+      notes: knowledge.latest?.notes ?? [],
+      contentTree: hashes.contentTree
+    },
+    authors: courseConfig.about.authors.map((author) => ({
+      name: author.name,
+      ...author.contact === void 0 ? {} : { contact: author.contact }
+    })),
+    disclaimer: courseConfig.about.disclaimer,
+    ...courseConfig.about.changelogHref === void 0 ? {} : { changelogHref: courseConfig.about.changelogHref }
+  };
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
+    about,
     notation: {
       definitions: registry.definitions,
       bundles: registry.bundles,
@@ -297,15 +383,26 @@ async function compileManifest(courseConfig) {
       labels: equationValidation.labels,
       numbersBySlug: equationValidation.numbersBySlug
     },
+    tables: {
+      labels: tableValidation.labels,
+      numbersBySlug: tableValidation.numbersBySlug
+    },
+    figures: {
+      labels: figureValidation.labels,
+      numbersBySlug: figureValidation.numbersBySlug
+    },
     diagnostics: {
       curriculum: curriculumIssues,
       notation: registry.diagnostics,
       alignment: alignmentIssues,
       math: mathIssues,
       consistency: consistencyIssues,
-      equations: equationValidation.diagnostics
+      equations: equationValidation.diagnostics,
+      tables: tableValidation.diagnostics,
+      figures: figureValidation.diagnostics,
+      knowledge: knowledge.diagnostics
     },
-    hashes: contentHashes()
+    hashes
   };
 }
 function byId(a, b) {

package/dist/compiler/resolution-report.d.ts

@@ -6,8 +6,12 @@ import './collections.js';
 import '../reference/types.js';
 import '../reference/lint-ignore.js';
 import '../reference/equations-validate.js';
+import '../reference/tables-validate.js';
+import '../reference/keyed-float-validate.js';
+import '../reference/figures-validate.js';
 import '../reference/gate-math.js';
 import '../reference/gloss.js';
+import './knowledge-version.js';
 import './lesson-derivation.js';
 
 /**

package/dist/reference/base-operators.d.mts

@@ -0,0 +1,38 @@
+/**
+ * The operators a course treats as common, given its `course.config.ts`
+ * `operators` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} operators
+ * @returns {Set<string>}
+ */
+export function effectiveOperatorAllowlist(operators: {
+    allow?: readonly string[];
+    deny?: readonly string[];
+} | undefined): Set<string>;
+/** True when `name` needs no notation entry for this course. */
+export function isBaseOperator(name: any, operators: any): boolean;
+/**
+ * The base operator library: the named mathematical operators every reader is
+ * assumed to know, so a lesson never has to introduce them with a notation
+ * entry.
+ *
+ * Rationale (parallel to `base-library.mjs`): the completeness gate has no
+ * opinion about operators — KaTeX parses `\exp`, `\int`, `\sin`, … as operator
+ * nodes, and `\operatorname{Var}` as an `operatorname` node, none of which the
+ * glyph resolver treats as a bindable symbol. The `operator-explained`
+ * consistency check (rule N8) fills that gap: an operator a lesson uses is
+ * either on this list (or the course's additions to it) or it carries a
+ * notation entry the reader can hover. This set is the "everyone knows these"
+ * baseline — trig, the exponential and logarithms, limits, extrema, and the
+ * big operators — kept greppable and small like the base library.
+ *
+ * A domain operator (`Var`, `Cov`, `Corr`, `sgn`, `erf`, `Tr`, `argmax`, …) is
+ * written `\operatorname{…}` and is NOT here: it earns a card, a
+ * `notation.local` entry, or an explicit line in `course.config.ts`
+ * (`operators.allow`).
+ *
+ * Entries are the KaTeX command without its backslash (`exp`, not `\exp`) for
+ * `op` nodes, and the verbatim body for `\operatorname{…}` nodes (`Var`).
+ * Matching is case-sensitive.
+ */
+export const BASE_OPERATORS: Readonly<Set<string>>;

package/dist/reference/base-operators.mjs

@@ -0,0 +1,103 @@
+/**
+ * The base operator library: the named mathematical operators every reader is
+ * assumed to know, so a lesson never has to introduce them with a notation
+ * entry.
+ *
+ * Rationale (parallel to `base-library.mjs`): the completeness gate has no
+ * opinion about operators — KaTeX parses `\exp`, `\int`, `\sin`, … as operator
+ * nodes, and `\operatorname{Var}` as an `operatorname` node, none of which the
+ * glyph resolver treats as a bindable symbol. The `operator-explained`
+ * consistency check (rule N8) fills that gap: an operator a lesson uses is
+ * either on this list (or the course's additions to it) or it carries a
+ * notation entry the reader can hover. This set is the "everyone knows these"
+ * baseline — trig, the exponential and logarithms, limits, extrema, and the
+ * big operators — kept greppable and small like the base library.
+ *
+ * A domain operator (`Var`, `Cov`, `Corr`, `sgn`, `erf`, `Tr`, `argmax`, …) is
+ * written `\operatorname{…}` and is NOT here: it earns a card, a
+ * `notation.local` entry, or an explicit line in `course.config.ts`
+ * (`operators.allow`).
+ *
+ * Entries are the KaTeX command without its backslash (`exp`, not `\exp`) for
+ * `op` nodes, and the verbatim body for `\operatorname{…}` nodes (`Var`).
+ * Matching is case-sensitive.
+ */
+export const BASE_OPERATORS = Object.freeze(
+  new Set([
+    // exponential / logarithms
+    'exp',
+    'log',
+    'ln',
+    'lg',
+    // trigonometric
+    'sin',
+    'cos',
+    'tan',
+    'cot',
+    'sec',
+    'csc',
+    // inverse trigonometric
+    'arcsin',
+    'arccos',
+    'arctan',
+    // hyperbolic
+    'sinh',
+    'cosh',
+    'tanh',
+    'coth',
+    // limits
+    'lim',
+    'limsup',
+    'liminf',
+    'injlim',
+    'projlim',
+    'varlimsup',
+    'varliminf',
+    'varinjlim',
+    'varprojlim',
+    // extrema
+    'max',
+    'min',
+    'sup',
+    'inf',
+    // linear algebra / number theory / misc
+    'arg',
+    'deg',
+    'det',
+    'dim',
+    'gcd',
+    'hom',
+    'ker',
+    'Pr',
+    'mod',
+    // big operators
+    'sum',
+    'prod',
+    'coprod',
+    'int',
+    'iint',
+    'iiint',
+    'oint',
+  ]),
+);
+
+/**
+ * The operators a course treats as common, given its `course.config.ts`
+ * `operators` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} operators
+ * @returns {Set<string>}
+ */
+export function effectiveOperatorAllowlist(operators) {
+  const allow = operators?.allow ?? [];
+  const deny = new Set(operators?.deny ?? []);
+  const effective = new Set(BASE_OPERATORS);
+  for (const name of allow) effective.add(name);
+  for (const name of deny) effective.delete(name);
+  return effective;
+}
+
+/** True when `name` needs no notation entry for this course. */
+export function isBaseOperator(name, operators) {
+  return effectiveOperatorAllowlist(operators).has(name);
+}

package/dist/reference/consistency.d.ts

@@ -1,4 +1,4 @@
-import { CourseConventions } from '../compiler/course-config.js';
+import { CourseConventions, CourseOperators } from '../compiler/course-config.js';
 import { CurriculumCatalog } from '../curriculum/validation.js';
 import { NotationSpec } from '../compiler/collections.js';
 import { LintIgnore } from './lint-ignore.js';
@@ -25,12 +25,15 @@ import { NotationRegistry, NotationRegistryInput } from './types.js';
  *   (f) weak-local                   a `notation.local` symbol used only in its
  *                                     own defining equation and prose
  *   (g) notation-source-locator      every notation `sources` entry has a locator
+ *   (h) operator-explained           a named operator a lesson uses is on the
+ *                                     shipped/course operator allowlist or
+ *                                     carries a notation entry (rule N8)
  *
  * Check (d) — the committed per-lesson resolution report — lives in
  * `src/content/resolution-report.ts`.
  */
 
-type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'numerals-tagged' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape';
+type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'numerals-tagged' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape' | 'operator-explained';
 interface ConsistencyDiagnostic {
     readonly code: ConsistencyCode;
     /** Tier 3 — every finding here is a warning until content is brought clean. */
@@ -51,6 +54,8 @@ interface ConsistencyInput {
     readonly lintIgnore: LintIgnore;
     /** Convention keys this course anchors on (from `content/course.config.ts`). */
     readonly conventions: CourseConventions;
+    /** This course's edits to the named-operator baseline (rule N8). */
+    readonly operators?: CourseOperators;
 }
 /**
  * Run every consistency check. The result is sorted deterministically (code,

package/dist/reference/consistency.js

@@ -1,3 +1,5 @@
+import { effectiveOperatorAllowlist } from "./base-operators.mjs";
+import { collectOperators } from "./math-glyphs.mjs";
 import { offVocabularyTokens } from "./units-vocab.js";
 const CONVENTION_RE = /\bsign convention\b|\bcash-flow perspective\b|\bholder(?:'s)?(?:\s+\w+){0,2}\s+perspective\b|\bfrom (?:a|one|the|its)(?:\s+\w+){0,3}\s+perspective\b|\breverses? every sign\b|\bpositive (?:means|amounts?)\b/i;
 function stripCode(text) {
@@ -285,6 +287,51 @@ function checkGlossNameShape(input, out) {
     }
   }
 }
+function checkOperatorExplained(input, out) {
+  const allowlist = effectiveOperatorAllowlist(input.operators);
+  const byId = new Map(
+    input.registry.definitions.map((definition) => [definition.id, definition])
+  );
+  const bindingsByLesson = new Map(
+    input.registry.bundles.map((bundle) => [bundle.lessonId, bundle.bindings])
+  );
+  for (const lesson of input.notationInput.lessons) {
+    const explained = /* @__PURE__ */ new Set();
+    const noteEntryOperators = (latex) => {
+      for (const operator of collectOperators(latex)) {
+        explained.add(operator.name);
+      }
+    };
+    for (const definition of lesson.localDefinitions) {
+      noteEntryOperators(definition.notation);
+    }
+    for (const binding of bindingsByLesson.get(lesson.lessonId) ?? []) {
+      const definition = byId.get(binding.definitionId);
+      if (definition) noteEntryOperators(definition.notation);
+    }
+    const reported = /* @__PURE__ */ new Set();
+    for (const span of mathSpans(lesson.body)) {
+      for (const operator of collectOperators(span.latex)) {
+        if (allowlist.has(operator.name)) continue;
+        if (explained.has(operator.name)) continue;
+        if (reported.has(operator.name)) continue;
+        reported.add(operator.name);
+        if (input.lintIgnore.matches("operator-explained", operator.name)) {
+          continue;
+        }
+        const display = operator.source === "operatorname" ? `\\operatorname{${operator.name}}` : `\\${operator.name}`;
+        out.push({
+          code: "operator-explained",
+          severity: "warning",
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          glyph: operator.name,
+          message: `${lesson.lessonId}: operator ${JSON.stringify(display)} is neither on the course operator allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(display)}) introduced with [[key]], or add ${JSON.stringify(operator.name)} to operators.allow in course.config.ts`
+        });
+      }
+    }
+  }
+}
 const CHECKS = [
   checkGlyphUniqueness,
   checkNotationUnits,
@@ -294,7 +341,8 @@ const CHECKS = [
   checkNotationSourceLocator,
   checkGlossWantsPromoting,
   checkCardWantsDemoting,
-  checkGlossNameShape
+  checkGlossNameShape,
+  checkOperatorExplained
 ];
 function runConsistencyChecks(input) {
   const diagnostics = [];
@@ -314,7 +362,8 @@ function consistencyCounts(diagnostics) {
     "notation-source-locator": 0,
     "gloss-wants-promoting": 0,
     "card-wants-demoting": 0,
-    "gloss-name-shape": 0
+    "gloss-name-shape": 0,
+    "operator-explained": 0
   };
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;