explico 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -14,6 +14,353 @@ under **Breaking** below; a PATCH never breaks.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-19
+
+### Breaking
+
+- **Rule N17 is inverted: a nested delimiter is sized by the engine, never by
+  hand.** The engine now installs its own KaTeX delimiter sizing
+  (`src/reference/katex-delimiters.mjs`), changing one constant in
+  `makeLeftRightDelim` — `delimiterExtend`, TeX's `\delimitershortfall`, from
+  `5.0` to `-1.0` points.
+  Stock TeX and stock KaTeX let a `\left … \right` pair fall up to 5pt short of
+  its content, so two pairs at different depths around similar content round to
+  the same glyph and the nesting vanishes; N17 used to repair that by making
+  authors hand-pick `\bigl` → `\Bigl` → `\biggl` → `\Biggl` outward. Those are
+  *fixed* glyphs: they stop tracking the content they wrap, they run out after
+  four levels, and editing an inner expression silently invalidates every size
+  above it. With a negative shortfall a pair is always strictly taller than its
+  content, so each enclosing level grows on its own, at any depth, by exactly
+  what it needs. `\left … \right` at every level is now the rule, and
+  hand-sizing a pair inside a nest is the warning.
+
+  Consequences for a course:
+  - The Tier-3 diagnostic code is renamed `delimiter-size-hierarchy` →
+    **`delimiter-manual-size`**; a `lint-ignore.yml` entry or a script matching
+    the old code must be updated. Its diagnostic shape changed too: the
+    `outerSize`/`nestedSize` fields are replaced by a single `size` (the
+    hand-picked size found), and `suggestion` is now always present and always
+    a `\left`/`\right` pair — it no longer carries a `size` field.
+  - Math that was N17-compliant now warns. A ladder such as
+    `\Biggl[a+\biggl(b+\Bigl[c+\left(d+e\right)\Bigr]\biggr)\Biggr]` reports one
+    finding per hand-sized level; the repair is `\left`/`\right` at every level.
+    A *lone* hand-sized pair that is not part of a nest — `\bigl(x,\ y\bigr)`
+    for a tuple — is deliberately left alone.
+  - **A course needs no install step for this.** `delimiterExtend` is a
+    function-local `const`, so nothing KaTeX exports reaches it and the change
+    has to happen in the module's own source. Rather than a `patches/` file —
+    which pnpm records per project and so cannot travel inside the npm artifact
+    — the engine reads KaTeX's ESM bundle, rewrites that constant, and moves
+    the render entry points onto the shared `katex` object. `rehype-katex`
+    reads `katex.renderToString` at call time and KaTeX's default export is
+    mutable, so lesson-body math inherits it without the plugin being forked or
+    aliased. `astro.config.mjs` already imports
+    `explico/reference/katex-options.mjs`, which installs it, so an existing
+    course picks this up on upgrade with no edit. The installer verifies itself
+    — a KaTeX upgrade that moves the constant, or anything that renders first,
+    fails the build with an explicit message instead of silently reverting to
+    stock spacing. [`docs/katex-bracket-scaling.md`](docs/katex-bracket-scaling.md)
+    derives the change and documents the mechanism and its trade-offs.
+
+### Added
+
+- **A math diagnostic now names the equation it belongs to.** Every finding
+  the math gate reports from a `$$…$$` block that carries a `\label{eq:…}`
+  gains an `equation` field — `{ key, href }`, where `href` is the anchor the
+  rendered page gives that equation (`/l1-ar/ar1-basics/#eq-ar1-variance`) —
+  and `diagnosticLine()` appends it, so the console line, the run log, and
+  `pnpm content diagnostics` all read
+  `[code] file:line:column: message (eq:<key> -> <href>)`. A size-only
+  `delimiter-manual-size` finding inside a six-line `aligned` block was
+  otherwise anonymous: the message names delimiters, never the result they
+  belong to, so an author had to reconstruct which equation was meant from a
+  line number alone. `CliDiagnostic` carries the same optional field, so a
+  course's own `scripts/content.ts` gets it without change. The manifest
+  schema is now **v16** (additive: v15 → v16); nothing existing changed shape.
+
+- **The About panel publishes the identity it shows.** `AboutPanel.astro` now
+  stamps `data-knowledge-version`, `data-knowledge-date` (omitted when the
+  content changelog has no date) and `data-engine-version` on its
+  `details[data-about-panel]` element, and marks the rendered version line with
+  `data-knowledge-line`. The two versions the panel exists to publish were
+  readable only as prose — and as a `version · date` join — so a course's build
+  check had to match that text, which pins the check to one version string and
+  turns every routine bump into a test edit; this repo's own
+  `playground/tests/e2e/about.spec.ts` was asserting `0.4.0` against a
+  playground long since at `0.5.2`. A bare version substring is not scoped to
+  the panel either, so the engine version printed one row below can satisfy it.
+  The attributes are additive: nothing rendered changed, and the existing
+  `data-about-panel` hook is untouched.
+
+### Fixed
+
+- **A glossary heading's accessible name is the term again.** The notation
+  glossary's per-entry anchor link moved *inside* its `<h2>` when the entry
+  header was rebuilt for smooth scrolling, so the `aria-label` on that link
+  ("Link to “Velocity”") joined the heading's accessible name — a screen reader
+  announced "Velocity Link to Velocity", and any check for the heading by name
+  stopped matching. `NotationGlossary.astro` now wraps the heading and its
+  anchor in a `.glossary-heading` flex row, the shape
+  `rehype-heading-anchors` already gives a lesson heading (`<h2>` and
+  `a.sl-anchor-link` as siblings). Nothing visual changed; the anchor still
+  reveals on hover and focus.
+
+- **A diagnostic's `line` now addresses the file it names.** Every gate scans
+  `lesson.body`, which Astro's `parseFrontmatter` hands over with the
+  frontmatter already removed, but each finding is reported against
+  `lesson.source.file` — so every `file:line:column` the engine has ever
+  emitted for a lesson was short by the height of that lesson's frontmatter.
+  It failed silently in the worst way: the number stayed plausible, so an
+  editor, a VS Code problem matcher, or an author following
+  `pnpm content diagnostics` jumped confidently to the wrong line, and a
+  size-only N17 finding could not be located at all. `parseDocument` now
+  records the body's start line, `NotationLessonInput` carries it as an
+  optional `bodyLine`, and the new `lessonLine()` helper applies it — so
+  `gate-math` (including every `delimiter-manual-size` column),
+  `gate-prose-notation` (N9), `gate-abbreviations` (N14), and
+  `gate-heading-length` (S1) are all corrected at once. A hand-built lesson
+  input that omits `bodyLine` behaves exactly as before.
+
+- **`equationAnchorId({ key })` type-checks without a `number`.** Its JSDoc
+  required both properties although `number` is read only when there is no
+  `key`, so a keyed caller had to pass a value the function ignores.
+
+- **A notation `formula` can use a manual delimiter size, an accent, a box, or
+  a color without failing the build.** `render-notation-math.ts` sanitizes
+  KaTeX's output against an attribute allowlist that had only ever grown to
+  cover what the corpus happened to use, so ordinary math threw
+  `Unexpected KaTeX property` with no author-side workaround: `\Bigl`/`\biggl`/
+  `\Biggl` (`minsize`, `maxsize`), `\xrightarrow` (`minsize`), `\boxed`
+  (`notation`), and `\colorbox` (`voffset`, `mathbackground`). Rule N17 asks
+  authors for exactly those delimiter commands, so a card that followed the
+  engine's own advice could not build. The allowlist is now KaTeX's whole inert
+  presentation surface — `columnlines`, `depth`, `display`, `largeop`,
+  `linebreak`, `linethickness`, `mathbackground`, `mathcolor`, `mathsize`,
+  `maxsize`, `minsize`, `notation`, `rowlines`, `valign`, and `voffset` join the
+  set — with `alt`, `href`, `src`, and `title` explicitly denied, and a new test
+  scans KaTeX's own `setAttribute` calls so a KaTeX upgrade that adds an
+  attribute fails here instead of in a downstream course. Hex colors are
+  accepted in an attribute or style value; no attribute that can carry a URL is
+  allowed through.
+
+- **`\vec` (and every other accent) renders again.** The style sanitizer
+  required each CSS declaration to end in `;`, but KaTeX does not always
+  terminate the last one — `\vec` emits `style="width:0.471em"` — and the
+  rejection then fell through to the misleading
+  `Unexpected KaTeX property: style`. Declarations are now validated one at a
+  time, and an unsafe `style` or `d` value says so instead of reporting an
+  unknown property.
+
+- **A macro in a formula no longer invents a source span.** KaTeX gives a node
+  it produced by expanding a macro a `loc` from the lexer over the *macro
+  body*, so those offsets index that body and not the source being scanned —
+  and they are still valid indices into a longer source, so the glyph resolver
+  read them as a real span over unrelated text. `\vdots` expands to
+  `{\varvdots\rule{0pt}{15pt}}`, whose atom claims characters 1–10: in
+  `M=\begin{pmatrix}…` that is `"=\begin{p"`, and because no author can wrap
+  that slice in an `\explain`, a matrix showing a column ellipsis failed the
+  build with `Unresolved notation ""`. Where the stray span instead collided
+  with a glyph in scope, the binding was injected at the macro body's offsets
+  and split the source mid-command — `\varSigma=\operatorname{Cov}(X)` became
+  `\varSigm\explain{cov-matrix}{a=\ope}ratorname{Cov}(X)`, a corrupt formula no
+  gate rejected. `nodeSpan` now believes a `loc` only when it belongs to the
+  string this pass parsed. 79 of KaTeX's 282 macros emit such a node, among
+  them `\argmax`, `\argmin`, `\plim`, `\limsup`, `\liminf`, `\bmod`, `\pmod`,
+  `\R`, `\N`, `\Z` and every upright `\varGamma`-style capital. A macro's
+  *argument* keeps the author's own locs and still binds normally. One limit
+  remains: a macro-expanded glyph has no authored span, so canonical matching
+  and the completeness gate cannot see it — annotate it with an explicit
+  `\explain{key}{\varSigma}`, which works and is unaffected by this change.
+
+- **A malformed `\explain` / `\slot` key fails the build instead of reaching
+  the reader.** KaTeX does not treat a denied `trust` callback as a parse
+  error: it renders the command name in `errorColor` and continues, so
+  `\explain{Not A Key}{\Omega}` produced red `\htmlData` text on the page with
+  the build green. (Until now this was masked by `mathcolor` — the attribute
+  KaTeX's error rendering carries — not being in the allowlist.)
+  `renderNotationMath` now checks both marker macros against
+  `trustNotationMarker` before KaTeX runs and throws naming the offending key.
+  `renderNotationFormula` still degrades to inert-but-correct math rather than
+  costing a reader the equation.
+
+## [0.7.0] - 2026-09-18
+
+### Breaking
+
+- **The compiler manifest schema is now v15 and diagnostic severity has three
+  levels.** Public diagnostic severity unions now include `info`, whose findings
+  are optional advice rather than repair debt. `eq-key-unused`, every keyed-float
+  `*-key-unused`, `unused-definition`, `weak-local`, `gloss-wants-promoting`, and
+  `card-wants-demoting` now emit `info` instead of `warning`. Consumers must stop
+  treating every non-error as a warning and accept schema v15.
+
+- **`explicoContentRefresh()` now fails the build when a manifest-driven
+  remark plugin is missing from `markdown.remarkPlugins`.** Its
+  `astro:config:setup` hook checks `manifest.abbreviations`,
+  `manifest.sources`, and `manifest.notation.raw` against the configured
+  plugins and throws if a non-empty table has no matching
+  `remarkAbbreviations`, `remarkCitation`, or `remarkNotation` registration.
+  Previously this "half-migrated" shape — content catalogued, plugin wiring
+  skipped — passed `pnpm validate:content` and `astro build` with no signal
+  anywhere, silently rendering triggers as plain text (see
+  [`docs/authoring/migrating.md`, rule N14](docs/authoring/migrating.md#4-rule-n14)).
+  A course with this exact gap will now fail its next build until the
+  missing plugin is registered.
+
+- **Retired the `numerals-tagged` Tier-3 consistency diagnostic.** It counted
+  every numeral in an untagged math span or table row—including unit exponents,
+  transparent worked-example arithmetic, and repeated table values—while
+  reporting only a lesson-level aggregate. `ConsistencyCode` no longer includes
+  `numerals-tagged`; remove any consumer logic or `lint-ignore.yml` entry for
+  that code. Numerical provenance should be enforced only by a future rule with
+  an explicit authoring surface and occurrence-level diagnostics.
+
+- **Removed the notation popup's "Copy LaTeX" button and the glossary's `#`
+  copy-link button** (`.notation-popup-copy`, `[data-popup-copy]`, and
+  `[data-glossary-anchor]` with its "Link copied" flash are gone from the
+  DOM). Copying a formula's LaTeX is now a click on the equation itself (see
+  **Added**); a glossary entry's title is now a link to its own
+  `#notation-<key>` anchor, with a hover-revealed link-icon anchor beside it
+  that navigates like any heading permalink instead of writing to the
+  clipboard. `NotationFormula`'s keyboard-focusable scroll region also moved
+  from `.notation-formula-math` to a new nested `.notation-formula-scroll`.
+  A course's own CSS or end-to-end tests targeting any of these selectors
+  need updating.
+
+### Added
+
+- **Click any rendered equation to copy its LaTeX, and every glossary formula
+  is numbered.** `NotationLayer.astro` (loaded on every page through the
+  Footer override) now handles clicks on any `[data-notation-formula]` box —
+  a glossary formula, an `\explain{}` formula inside a popup or `Diagram`, or
+  an interactive lab equation — copying its `data-latex` and flashing
+  "Copied!"; a hover tooltip names the gesture, and a click on an explained
+  symbol or an equation number keeps its own meaning. A glossary entry's
+  formula gets a `G.<n>` number (page order) that links to its entry, plus a
+  copy button; `NotationFormula` gains optional `number` / `numberHref` props
+  and renders neither when they are omitted. For interactive labs,
+  `renderLabMath()` now also returns `plainLatexTemplate` (bare symbols, each
+  `\slot{name}{…}` replaced by `slotPlaceholder(name)`), and the new
+  `slotPlaceholder` export lets an island substitute each slot's live value
+  so `data-latex` tracks the sliders. A lab that sets `data-notation-formula`
+  and `data-latex` on its math root joins the gesture; one that does not is
+  unchanged.
+
+- **Smooth, eased scrolling for in-page anchor links.** The new
+  `AnchorScrollEnhancer.astro`, mounted by `LessonFooter.astro`, catches every
+  same-page `<a href="#…">` — headings, equation/table/figure numbers,
+  footnote and memo markers, the glossary's links, the table of contents —
+  animates to the target with the shared `animatedScrollIntoView` helper, then
+  performs a real fragment navigation on arrival so `:target` styling and
+  `hashchange` behave as for a plain click. `prefers-reduced-motion` is
+  honored, and scrolling away mid-animation just updates the URL.
+  `HeadingAnchorEnhancer`, `KeyedFloatEnhancer`, `Memo`, and `ShortNote` now
+  share that helper. A course that overrides `Footer` with its own component
+  instead of `LessonFooter.astro` must render `<AnchorScrollEnhancer />` itself
+  to get it.
+
+- **New review-only authoring rule P1 and a new `P` (prose) rule area: "or"
+  never introduces a second name for the same thing.** Write "i.e.,", "also
+  called", "also known as", or parentheses instead, because "or" also
+  separates real alternatives and a reader cannot tell which is meant ("the
+  residual or error term"). Nothing is checked at build time, so no course
+  needs to change to keep building. See `docs/authoring/prose.md#p1`.
+
+- **The shipped abbreviation baseline (rule N14) now covers every common
+  time-of-day and "and so on" spelling.** `AM`, `PM`, `A.M.`, `P.M.`, and
+  `e.t.c.` join `a.m.`, `p.m.`, `e.g.`, `i.e.`, and `etc.`, so a lesson can
+  write "9 AM" or "e.g." without a `content/abbreviations/*.md` entry or an
+  `abbreviations.allow` line. This only loosens the gate — no course needs to
+  change to keep building; a course that wants one of them explained anyway
+  lists it in `abbreviations.deny`. See `docs/authoring/notation.md#n14`.
+
+- **Run logs for `pnpm validate:content`, in Python's `logging` format.** The
+  new `explico/compiler/logging` export (`createRunLog()`) records every
+  diagnostic a validate run reports to `build/logs/<timestamp>/`, formatted as
+  `%(asctime)s %(levelname)s %(name)s: %(message)s` so the lines filter with
+  the same tooling a Python log does. Three cumulative files per run —
+  `error.log` (errors), `warning.log` (errors + warnings), and `info.log`
+  (everything) — let you open the narrowest one that still answers the
+  question, and `build/logs/latest` symlinks to the newest run. Logger names
+  are `explico.<subsystem>` (`explico.notation`, `explico.curriculum`,
+  `explico.raw-floats`, …), derived from the diagnostic category, so filtering
+  by name is filtering by subsystem. Nothing is pruned; `build/` is
+  git-ignored. `info.log` also captures the severity-`info` diagnostics the
+  engine has always produced but never printed, plus the run summary lines.
+  The terminal output is deliberately unchanged — the compact `[code] message`
+  lines stay exactly as they were, with one added pointer line naming the run's
+  log directory and its counts. Blocking diagnostics still throw and still exit
+  non-zero; logging is purely additive. A course picks this up by routing its
+  own `scripts/compile-manifest.ts` through `createRunLog()`.
+
+- **New severity-filtered content diagnostics and VS Code actions.** `pnpm
+  content diagnostics [info|warning|error] [--json]` flattens manifest findings
+  into stable, source-aware `group:code` diagnostics at or above the requested
+  severity; the new `content warnings` is the warning-only view, and
+  `content status` now also counts `info` findings. Both commands are exported
+  from `explico/compiler/cli` (`contentDiagnostics`, `contentWarnings`), so a
+  course's own `scripts/content.ts` must route them to expose the commands. The
+  playground provides **Explico: Show content diagnostics (info+)**,
+  **(warning+)**, and **(errors)** tasks, which feed locatable findings into
+  VS Code's Problems panel.
+
+- **New delimiter authoring rules N16 and N17, with warning-level size
+  linting.** Rule N16 tells AI authors to alternate `()`, `[]`, and `\{\}` for
+  purely stylistic nested grouping while preserving function calls,
+  expectations, intervals, sets, tuples, probability, indexing, norms, and
+  every other semantically meaningful conventional delimiter. It is
+  review-only. Rule N17 independently requires nested scalable delimiter pairs
+  to grow from inside to outside. The new stack-based
+  `lintDelimiterSizes` parser handles multiline and arbitrarily deep
+  `\left...\right` plus `\big`/`\Big`/`\bigg`/`\Bigg` pairs, emits the
+  non-blocking `delimiter-size-hierarchy` diagnostic at the outer pair's line
+  and column, and suggests a larger manual size without changing delimiter
+  shape. It deliberately does not lint type alternation or infer mathematical
+  semantics.
+
+- **New `explico/reference/rehype-base-links.mjs`.** Wire `[rehypeBaseLinks, base]`
+  into `markdown.rehypePlugins` and it prefixes every root-relative
+  `<a href="/...">` a lesson's Markdown/MDX body produces — a lesson's own
+  prose links, `remark-notation.mjs`'s equation cross-references, and
+  `remark-citation.mjs`'s citation links — with the course's Astro `base`.
+  Starlight only applies `base` to its own generated navigation (sidebar,
+  pagination, breadcrumbs); it never touches anything the Markdown/MDX →
+  rehype pipeline produces, so on any course deployed under a subpath (a
+  GitHub Pages *project* site, e.g. `base: '/my-course'`) every one of those
+  links 404s without this. No-op when the course has no base, so it's safe
+  to wire in unconditionally. A lesson's Starlight frontmatter (e.g.
+  `hero.actions[].link`) never enters this pipeline either — write those as
+  paths relative to the current page instead.
+
+- **The `↩` link at the end of each entry in a page's References section now
+  has a hover tooltip.** `remark-citation.mjs` already gave that back-link an
+  `aria-label` ("Back to the citation in the text"); it now sets the same text
+  as `title`, so a mouse user hovering the bare arrow sees what it does. No
+  course wiring or config change needed.
+
+### Changed
+
+- **`remarkAbbreviations` (rule N14) now wraps every occurrence of a
+  catalogued abbreviation in a lesson, not just the first per page.** A
+  reader who deep-links into a mid-page section — the sidebar TOC, a heading
+  anchor, an external link — used to land on plain, unlinked text with no
+  visual cue that a hover/click glossary card existed elsewhere on the page,
+  because only the earliest occurrence in document order was ever wrapped.
+  `AbbreviationLayer.astro` already resolved every marker independently by
+  `data-abbr-key`, so no island-side change was needed. This changes rendered
+  output for every existing course using this plugin: abbreviation-dense
+  prose that repeats the same term many times in one passage will now show a
+  dotted-underline link on each instance.
+
+### Fixed
+
+- **Standalone HTML export no longer runs every `<link>` through the asset
+  inliner.** Only a `<link>` whose `rel` is `stylesheet` or an icon type
+  (`icon`, `shortcut icon`, `apple-touch-icon`,
+  `apple-touch-icon-precomposed`, `mask-icon`) is inlined; any other `rel`
+  (`canonical`, `alternate`, `preload`, …) is left as authored. No course
+  change is needed.
+
 ## [0.6.0] - 2026-09-16
 
 ### Breaking
@@ -544,7 +891,9 @@ under **Breaking** below; a PATCH never breaks.
   system with its completeness gate, the curriculum-graph validator, the
   Astro/Starlight UI, the LMS / session / analytics seams, and the `content` CLI.
 
-[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/danieltuzes/explico/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/danieltuzes/explico/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/danieltuzes/explico/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/danieltuzes/explico/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/danieltuzes/explico/compare/v0.3.0...v0.4.0

package/README.md

@@ -41,8 +41,9 @@ What it gives a course:
   figure — nothing in the engine assumes one plotting approach.
 - **LMS / analytics / identity seams** — framework-free interfaces shipped as
   no-ops; a host supplies real implementations without touching a component.
-- **A `content` CLI** — `status`, `context <lesson>`, `check <lesson>` (compiles
-  MDX → remark → KaTeX and fails loudly), `new lesson|term`.
+- **A `content` CLI** — `status`, `diagnostics`, `warnings`, `context <lesson>`,
+  `check <lesson>` (compiles MDX → remark → KaTeX and fails loudly),
+  `new lesson|term`.
 
 The prerequisite graph itself is authored by the lecturer or an AI; the engine
 validates it (DAG, ordering, coverage, orphans) rather than inferring it.
@@ -192,6 +193,19 @@ URL likewise fails the standalone export audit.
 "scripts": { "validate:content": "tsx scripts/compile-manifest.ts" }
 ```
 
+Diagnostics have three distinct severities: an `error` blocks validation because
+content is incorrect, ambiguous, unexplainable, or cannot render reliably; a
+`warning` is non-blocking but identifies a rule or usability problem that should
+be repaired; `info` is optional advice that may be intentionally left as-is.
+
+Run `pnpm --filter explico-playground content diagnostics info` to print every
+diagnostic. Replace `info` with `warning` to show warnings and errors, or `error`
+to show blockers only. `content warnings` remains the warning-only view, and
+`--json` returns normalized data for tooling. VS Code exposes matching
+**Explico: Show content diagnostics (info+)**, **(warning+)**, and **(errors)**
+tasks; locatable findings populate the Problems panel at the reported line and
+column.
+
 The reference course is
 [**credit-and-derivatives**](https://github.com/danieltuzes/credit-and-derivatives):
 discounting → bonds → credit/CDS → derivatives and options.

package/dist/compiler/astro.d.ts

@@ -1,4 +1,4 @@
-import { AstroIntegration } from 'astro';
+import { AstroConfig, AstroIntegration } from 'astro';
 import { CourseConfig } from './course-config.js';
 import { Manifest } from './manifest.js';
 import '../curriculum/validation.js';
@@ -25,6 +25,17 @@ declare function matchStandaloneDownload(pathname: string, base: string, lessonS
 declare function assertLocalNotationParity(lessonId: string, authoredKeys: readonly string[], renderedKeys: readonly string[]): void;
 /** Fail an Astro build if final rendered HTML contains an unusable trigger. */
 declare function assertNotationPayloadHtml(page: string, html: string): void;
+type MarkdownConfig = AstroConfig['markdown'];
+/**
+ * Fail the build when a manifest-driven remark plugin has catalogued content
+ * but was never registered in Astro's markdown config — the "half-migrated"
+ * failure mode `docs/authoring/migrating.md` documents but, until now, never
+ * checked: `pnpm validate:content` stays green because the content-side gate
+ * (e.g. `gate-abbreviations.ts`'s N14 check) only scans prose, not Astro
+ * config, so a skipped plugin registration renders every trigger as plain
+ * text with no signal anywhere.
+ */
+declare function assertRemarkPluginsWired(manifest: Pick<Manifest, 'abbreviations' | 'sources' | 'notation'>, markdown: MarkdownConfig): void;
 /**
  * Restart Astro when an authored content file changes. Astro reloads MDX on
  * its own, but Explico's manifest is created by `astro.config.mjs`; a restart
@@ -35,4 +46,4 @@ declare function assertNotationPayloadHtml(page: string, html: string): void;
  */
 declare function explicoContentRefresh(courseConfig: CourseConfig, manifest: Manifest): AstroIntegration;
 
-export { assertLocalNotationParity, assertNotationPayloadHtml, explicoContentRefresh, matchStandaloneDownload };
+export { assertLocalNotationParity, assertNotationPayloadHtml, assertRemarkPluginsWired, explicoContentRefresh, matchStandaloneDownload };

package/dist/compiler/astro.js

@@ -9,6 +9,9 @@ import {
 } from "./manifest.js";
 import { missingNotationPayloadKeys } from "../reference/page-notation.js";
 import { writeStandaloneLessonExports } from "./exports/standalone-html.js";
+import remarkAbbreviations from "../reference/remark-abbreviations.mjs";
+import remarkCitation from "../reference/remark-citation.mjs";
+import remarkNotation from "../reference/remark-notation.mjs";
 const watchedServers = /* @__PURE__ */ new WeakSet();
 function normalizedBasePath(base) {
   const segment = base.replace(/^\/+|\/+$/gu, "");
@@ -94,6 +97,40 @@ function assertNotationPayloadHtml(page, html) {
     `Explico notation payload invariant failed for rendered page "${page}": ${missing.map((key) => `data-notation-key="${key}"`).join(", ")} ${missing.length === 1 ? "has" : "have"} no matching \`data-notation-entry\` popup definition. A nested Astro component that emits notation must register its formula dependencies; use Diagram, NotationFormula, or labMathScope(..., { locals: Astro.locals, context }).`
   );
 }
+function configuredRemarkPlugins(markdown) {
+  const direct = markdown?.remarkPlugins ?? [];
+  const processorOptions = markdown?.processor?.options;
+  return [...direct, ...processorOptions?.remarkPlugins ?? []];
+}
+function remarkPluginIsWired(remarkPlugins, plugin) {
+  return remarkPlugins.some(
+    (entry) => entry === plugin || Array.isArray(entry) && entry[0] === plugin
+  );
+}
+function assertRemarkPluginsWired(manifest, markdown) {
+  const remarkPlugins = configuredRemarkPlugins(markdown);
+  const missing = [];
+  if (manifest.abbreviations.length > 0 && !remarkPluginIsWired(remarkPlugins, remarkAbbreviations)) {
+    missing.push(
+      `remarkAbbreviations is missing from markdown.remarkPlugins, but manifest.abbreviations has ${manifest.abbreviations.length} entr${manifest.abbreviations.length === 1 ? "y" : "ies"}. Import it from 'explico/reference/remark-abbreviations.mjs' and add [remarkAbbreviations, { abbreviations: manifest.abbreviations }] to markdown.remarkPlugins \u2014 see docs/authoring/migrating.md#4-rule-n14.`
+    );
+  }
+  if (manifest.sources.length > 0 && !remarkPluginIsWired(remarkPlugins, remarkCitation)) {
+    missing.push(
+      `remarkCitation is missing from markdown.remarkPlugins, but manifest.sources has ${manifest.sources.length} entr${manifest.sources.length === 1 ? "y" : "ies"}. Import it from 'explico/reference/remark-citation.mjs' and add [remarkCitation, { sources: manifest.sources }] to markdown.remarkPlugins.`
+    );
+  }
+  if (manifest.notation.raw.length > 0 && !remarkPluginIsWired(remarkPlugins, remarkNotation)) {
+    missing.push(
+      `remarkNotation is missing from markdown.remarkPlugins, but manifest.notation.raw has ${manifest.notation.raw.length} entr${manifest.notation.raw.length === 1 ? "y" : "ies"}. Import it from 'explico/reference/remark-notation.mjs' and add [remarkNotation, createRemarkNotationOptions(manifest)] to markdown.remarkPlugins.`
+    );
+  }
+  if (missing.length === 0) return;
+  throw new Error(
+    `Explico manifest-driven remark plugin${missing.length === 1 ? " is" : "s are"} not wired into Astro's markdown config:
+${missing.map((line) => `  - ${line}`).join("\n")}`
+  );
+}
 async function validateGeneratedNotationPayloads(directory) {
   const root = fileURLToPath(directory);
   const walk = async (path) => {
@@ -136,6 +173,7 @@ function explicoContentRefresh(courseConfig, manifest) {
     name: "explico-content-refresh",
     hooks: {
       "astro:config:setup": ({ command, config }) => {
+        assertRemarkPluginsWired(manifest, config.markdown);
         if (command === "dev") {
           developmentConfig = { root: config.root, base: config.base };
         }
@@ -253,6 +291,7 @@ ${message}
 export {
   assertLocalNotationParity,
   assertNotationPayloadHtml,
+  assertRemarkPluginsWired,
   explicoContentRefresh,
   matchStandaloneDownload
 };

package/dist/compiler/cli.d.ts

@@ -1,9 +1,10 @@
+import { DiagnosticSeverity } from '../reference/types.js';
+import { EquationLink } from '../reference/gate-math.js';
 import { Manifest, ManifestLesson } from './manifest.js';
 import '../curriculum/validation.js';
 import '../reference/consistency.js';
 import './course-config.js';
 import './collections.js';
-import '../reference/types.js';
 import '../reference/lint-ignore.js';
 import '../reference/equations-validate.js';
 import '../reference/tables-validate.js';
@@ -12,7 +13,6 @@ import '../reference/figures-validate.js';
 import '../reference/diagrams-validate.js';
 import '../reference/knowledge-checks-validate.js';
 import '../reference/raw-floats-validate.js';
-import '../reference/gate-math.js';
 import '../reference/mixed-content.js';
 import '../reference/gloss.js';
 import './knowledge-version.js';
@@ -38,6 +38,9 @@ import './lesson-derivation.js';
  *     source metadata + locators, the section's domain signatures, and the
  *     lesson's current diagnostics — and reports token counts against the doc
  *     set + corpus so the size win is visible.
+ *   - `content diagnostics [severity]` flattens every diagnostic category at
+ *     or above a threshold into one stable, source-aware list for editors.
+ *   - `content warnings` is the warning-only compatibility view.
  *   - `content check` compiles the lesson MDX → remark → KaTeX → HTML and fails
  *     on any renderability error (unparseable MDX, KaTeX error, unresolved
  *     notation, unknown `[[key]]`, unknown citation), on top of the manifest's
@@ -53,10 +56,18 @@ declare class ContentCliError extends Error {
 /** One normalized diagnostic. `code` is `<source>:<kind>` and always stable. */
 interface CliDiagnostic {
     readonly code: string;
-    readonly severity: 'error' | 'warning';
+    readonly severity: DiagnosticSeverity;
     readonly message: string;
     readonly file?: string;
     readonly line?: number;
+    readonly column?: number;
+    /**
+     * The keyed equation the finding sits in, when the math carries a
+     * `\label{eq:…}` — `{ key, href }`, the href being the anchor on the
+     * rendered page. A size-only finding inside a long `aligned` block is
+     * otherwise anonymous.
+     */
+    readonly equation?: EquationLink;
 }
 /**
  * Every manifest diagnostic that names this lesson (by id or file), normalized
@@ -121,9 +132,24 @@ interface StatusReport {
     readonly diagnostics: {
         readonly errors: number;
         readonly warnings: number;
+        readonly infos: number;
     };
 }
 declare function contentStatus(manifest: Manifest): StatusReport;
+type DiagnosticThreshold = DiagnosticSeverity;
+interface DiagnosticsReport {
+    readonly minimumSeverity: DiagnosticThreshold;
+    readonly count: number;
+    readonly diagnostics: readonly CliDiagnostic[];
+}
+interface WarningsReport {
+    readonly count: number;
+    readonly warnings: readonly CliDiagnostic[];
+}
+/** Manifest diagnostics at or above a severity, normalized for tooling. */
+declare function contentDiagnostics(manifest: Manifest, minimumSeverity?: DiagnosticThreshold): DiagnosticsReport;
+/** Every warning exactly; errors and informational advice are excluded. */
+declare function contentWarnings(manifest: Manifest): WarningsReport;
 interface ContextReport {
     readonly lesson: {
         readonly id: string;
@@ -216,4 +242,4 @@ interface Scaffold {
 declare function scaffoldLesson(rawId: string): Scaffold;
 declare function scaffoldTerm(rawKey: string): Scaffold;
 
-export { type CheckLessonResult, type CheckReport, type CliDiagnostic, type ContentCliCode, ContentCliError, type ContextReport, type DomainFileSignatures, type RenderResult, type Scaffold, type StatusReport, type TokenCounts, changedLessonIds, contentCheck, contentContext, contentStatus, estimateTokens, findLesson, lessonDiagnostics, normalizeLessonId, renderLesson, scaffoldLesson, scaffoldTerm };
+export { type CheckLessonResult, type CheckReport, type CliDiagnostic, type ContentCliCode, ContentCliError, type ContextReport, type DiagnosticThreshold, type DiagnosticsReport, type DomainFileSignatures, type RenderResult, type Scaffold, type StatusReport, type TokenCounts, type WarningsReport, changedLessonIds, contentCheck, contentContext, contentDiagnostics, contentStatus, contentWarnings, estimateTokens, findLesson, lessonDiagnostics, normalizeLessonId, renderLesson, scaffoldLesson, scaffoldTerm };