explico 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -14,6 +14,275 @@ under **Breaking** below; a PATCH never breaks.
 
 ## [Unreleased]
 
+## [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
+
+- **New build-enforced authoring rule S1: no Markdown heading (`##` through
+  `######`) and no `<Figure title>` / `<Diagram label>` / `<Memo title>` /
+  `<ShortNote title>` may run past 65 characters.** A `<Figure>` with a long
+  `caption` and no explicit `title` was silently using the whole caption as
+  its always-visible collapsible title-bar text — the reader saw the full
+  sentence twice. `gate-heading-length.ts` scans every lesson body; a course
+  with an over-limit heading or float title anywhere will now fail
+  `pnpm validate:content` / `astro build`. `<Table>` is exempt — it has only
+  a `caption`, not a separate `title`. A lesson's own `frontmatter.title`
+  (the page `<h1>`) is Review-only, not build-enforced — the gate scans body
+  text and cannot see frontmatter. See
+  `docs/authoring/structure-rules.md#s1`.
+
+- **Removed the "Pin explanation" button from the "Page notation" panel**
+  (`.notation-pin`, `[data-notation-control]` — both gone from the DOM). Pin
+  a card from the list the same way an inline prose symbol always has: click
+  its glyph, now also Tab + Enter/Space-operable (`role="button"`,
+  `tabindex="0"`, `aria-pressed`) since it was the button's only remaining
+  job. A course's own CSS or tests targeting either selector need updating.
+
+- **`NotationLayer.astro`'s separate "Page notation" `<h2>` is gone** —
+  the panel had two headings back to back ("Page notation" over "Notation
+  used on this page (N)"), saying the same thing twice. The panel's
+  `<summary>` is now the only heading, and `.notation-layer-heading` no
+  longer exists.
+
+- **`Diagram`'s `description` prop and its collapsed "Diagram description"
+  fallback block are gone** (`.diagram-fallback` no longer exists in the
+  DOM). The caption (`label`) is the diagram's one authored piece of text,
+  matching how a LaTeX figure/table caption already tells the whole story —
+  a separate always-present description block was inventing a second text
+  category most courses never wanted and that only added visible chrome
+  under every diagram. Drop any `description="…"` passed to `<Diagram>`;
+  the build no longer accepts it (`astro check` fails on an excess prop).
+
+### Added
+
+- **`NotationLayer.astro`'s "Page notation" panel and `remark-citation.mjs`'s
+  generated "References" section are both properly collapsible now** — same
+  native, persisted, deep-linkable disclosure `Figure`/`CollapsibleSections`
+  already use, not the always-native-default `<details>` "Page notation" had
+  before (no persistence, no course-configurable default, no anchor).
+  - `NotationLayer` gains `defaultOpen`/`rememberState` props (mirroring
+    `Figure`'s) and a hover-reveal permalink anchor next to its title bar
+    (`#page-notation` by default).
+  - `remark-citation.mjs`'s generated References heading now carries the
+    same `[collapsible]`/`[collapsed]` marker an authored `##` heading uses,
+    via a new `defaultOpen` plugin option — so it rides the *same*
+    `rehypeHeadingAnchors` / `CollapsibleSections` machinery every other
+    heading does, with no engine changes needed on that side. This only
+    takes visible effect on a course whose `astro.config.mjs` wires
+    `rehypeHeadingAnchors` into its rehype pipeline.
+  - New `CourseConfig.disclosureDefaults` (the manifest schema is now v14,
+    additive):
+    `{ notation?, references? }`, each `true` = open, closed (the engine's
+    own default) when omitted or the whole block is absent. Both are
+    engine-authored sections, not written by a lesson, so they get their own
+    default independent of `defaultCollapsible.sections`/`.subsections` (an
+    author's own `##` headings). See `docs/authoring`,
+    `playground/astro.config.mjs` for the wiring convention.
+
+### Fixed
+
+- **A symbol explained once via `\explain{key}{…}` can now auto-resolve at
+  every later bare occurrence of the same declared `latex` on the page — this
+  previously failed silently (no tooltip, no build error) for several common
+  shapes.** A definition whose whole canonical form is a roman label
+  (`\mathrm{SSR}`, `\mathrm{SST}`) never entered the auto-annotator's
+  signature index at all, so a bare occurrence of such a symbol could never
+  resolve, anywhere on the page, independent of position. Also fixed: a bare
+  symbol sitting immediately next to an `\explain{…}{…}` call, a canonical
+  match found by seeing through an already-explicit call's own wrapping, and
+  a partial `\explain{key}{…}` wrap covering only part of a declared
+  multi-token form — all three previously either dropped the symbol silently
+  or produced malformed, unparseable output. All of these now resolve
+  correctly, or fail loudly as "Unresolved notation" (`resolveMathGlyphs`,
+  shared by lesson-body rendering and `gate-math.ts`'s `pnpm validate:content`
+  check — so a regression here fails the build immediately rather than
+  passing silently through to a render-time surprise). One side effect: the
+  fix also restores the `ambiguous-canonical-notation` check for
+  `\operatorname{…}`/`\mathrm{…}`-only glyphs, which the same bug had
+  silently disabled — a course with two different notation keys declaring
+  structurally identical LaTeX (e.g. two keys both `\operatorname{Var}`) will
+  now correctly fail `pnpm validate:content` where it previously built with a
+  silent, unresolvable ambiguity. See
+  [`docs/authoring/notation.md`](docs/authoring/notation.md).
+
 ## [0.5.0] - 2026-09-15
 
 ### Added
@@ -137,13 +406,16 @@ under **Breaking** below; a PATCH never breaks.
   UI. The change is additive, but consumers that validate
   `MANIFEST_SCHEMA_VERSION` must accept the new version.
 
-- **The compiler manifest schema is now v10.** Diagrams are first-class keyed
+- **The compiler manifest schema is now v10.** Numbered knowledge checks add
+  `manifest.checks`, `lessons[].knowledgeChecks`, `lessons[].numbering.checks`,
+  and `diagnostics.checks`. The change is additive, but consumers that
+  validate `MANIFEST_SCHEMA_VERSION` must accept the new version.
+
+- **The compiler manifest schema is now v9.** Diagrams are first-class keyed
   floats with their own `manifest.diagrams`, `lessons[].diagrams`,
-  `lessons[].numbering.diagrams`, and `diagnostics.diagrams` fields. Numbered
-  knowledge checks add `manifest.checks`, `lessons[].knowledgeChecks`,
-  `lessons[].numbering.checks`, and `diagnostics.checks`. The changes are
-  additive, but consumers that validate `MANIFEST_SCHEMA_VERSION` must accept
-  the new version.
+  `lessons[].numbering.diagrams`, and `diagnostics.diagrams` fields. The
+  change is additive, but consumers that validate `MANIFEST_SCHEMA_VERSION`
+  must accept the new version.
 
 - **New build-enforced authoring rule N9: a physical quantity, unit, or math
   operator must be typeset in `$…$`, never as plain text, anywhere on a
@@ -217,6 +489,20 @@ under **Breaking** below; a PATCH never breaks.
   with `\sin\theta`, `\log x`, `\exp t`, etc. anywhere in rendered math will
   now fail the build; see `docs/authoring/notation.md#n13`.
 
+- **New build-enforced authoring rule N15: a nested visible delimiter — `(`,
+  `[`, `\{`, or `|` inside another one of them — must use its `\left`/`\right`
+  sizing form, not the bare character.** The moment a second one of these four
+  glyphs sits inside the first — same type or mixed, e.g. `(a + [b])` — every
+  level of that nest switches to the sizing form: `\sin(2(90°-\theta))` is now
+  a hard error, `\sin\left(2\left(90°-\theta\right)\right)` is required.
+  `findNestedBareDelimiters` (`math-glyphs.mjs`) walks the same parsed KaTeX
+  tree `resolveMathGlyphs` and N13 already build; a violation fails
+  `pnpm validate:content` / `astro build` with no `lint-ignore.yml` escape
+  hatch, like N9/N13. A single, non-nested bare delimiter (`(x)`) is
+  untouched, and a delimiter inside `\text{…}` (a unit per N9) is unaffected.
+  A downstream course with a nested bare delimiter anywhere in rendered math
+  will now fail the build; see `docs/authoring/notation.md#n15`.
+
 ### Added
 
 - **Numbered, referenceable, collapsible knowledge checks.** Assessment ids in
@@ -436,7 +722,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.5.0...HEAD
+[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.7.0...HEAD
+[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
 [0.3.0]: https://github.com/danieltuzes/explico/compare/v0.2.0...v0.3.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,9 @@
+import { DiagnosticSeverity } from '../reference/types.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';
@@ -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,11 @@ 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;
 }
 /**
  * Every manifest diagnostic that names this lesson (by id or file), normalized
@@ -121,9 +125,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 +235,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 };