explico 0.7.0 → 0.11.0

package/src/content-config.ts

@@ -124,19 +124,31 @@ const notationEntryShape = z.object({
 
 const localNotationDefinition = notationEntryShape;
 
+/**
+ * One `notation.suspend` item (rule N22): a decoration (`'`, `\hat`, …) that
+ * is not an operator on this page. The loader (`collections.ts`) checks the
+ * name against the decorations the resolver knows.
+ */
+const notationSuspension = z.object({
+  operator: z.string().min(1),
+  reason: z.string().min(1).optional(),
+});
+
 const lessonNotation = z
   .object({
     // `notation.uses` is retired (D3): a lesson pulls a shared key into scope
     // by referencing it in prose (`[[key]]`) or math (`\explain`).
     local: z.array(localNotationDefinition).default([]),
+    suspend: z.array(notationSuspension).default([]),
   })
-  .default({ local: [] });
+  .default({ local: [], suspend: [] });
 
 /**
  * Lesson frontmatter — reduced shape (Phase C1 schema, C2 codemod applied).
  *
  * Authored:  `title`, `description` (Starlight base), `teaches` (ordered — the
  *            curriculum contract, never derived), `assumptions`,
+ *            `studyMinutes` (optional reader-facing estimate),
  *            `notation.local` (page-local symbols only).
  * Artifact:  `editorialStatus` (human-set trust flag).
  * Derived (in `content/collections.ts` + `content/lesson-derivation.ts`, never
@@ -144,10 +156,33 @@ const lessonNotation = z
  *            prerequisites of `teaches`, minus `teaches`), `sources` (`[@…]`
  *            occurrences), `assessments` (colocated `<lesson>.checks.yml`),
  *            `sidebar` order (track order).
- * Dropped:   `aiAssisted`, `lastReviewed`, `riskTier`, `estimatedMinutes`
- *            (git history + `editorialStatus` + `NEEDS_SOURCE` carry provenance);
- *            `notation.uses` (D3 — a shared symbol is imported by using it).
+ * Dropped:   `aiAssisted`, `lastReviewed`, `riskTier` (git history +
+ *            `editorialStatus` + `NEEDS_SOURCE` carry provenance);
+ *            `estimatedMinutes`, whose reader-facing half returned as the
+ *            optional `studyMinutes` once part pages had somewhere to total
+ *            it; `notation.uses` (D3 — a shared symbol is imported by using
+ *            it).
+ */
+/**
+ * How long this chapter takes to study: `40`, or a `[low, high]` range in
+ * minutes. It is a reader-facing estimate the author makes, aggregated by
+ * `<PartOverview>` and `<CourseContents>` into a part and course total — not
+ * the provenance field `estimatedMinutes` used to be, and nothing derives it.
+ *
+ * A part only reports a total when every one of its chapters states one, so a
+ * half-annotated course shows the chapters it knows about and no misleading
+ * sum.
  */
+const studyMinutes = z
+  .union([
+    z.number().int().positive(),
+    z.tuple([z.number().int().positive(), z.number().int().positive()]),
+  ])
+  .refine((value) => !Array.isArray(value) || value[0] <= value[1], {
+    message:
+      'studyMinutes as a range is [low, high]; the low end cannot exceed the high end.',
+  });
+
 const docs = defineCollection({
   loader: docsGlob,
   schema: docsSchema({
@@ -155,6 +190,7 @@ const docs = defineCollection({
       editorialStatus: editorialStatus.default('draft'),
       teaches: z.array(id).default([]),
       assumptions: z.array(z.string().min(1)).default([]),
+      studyMinutes: studyMinutes.optional(),
       notation: lessonNotation,
     }),
   }),

package/src/reference/base-accents.mjs

@@ -0,0 +1,31 @@
+/**
+ * The base accent baseline: decorations every reader is assumed to know, so a
+ * lesson never has to explain them (rule N22). The named-operator counterpart
+ * is `base-operators.mjs` (rule N8).
+ *
+ * It ships **empty**, because no decoration has one meaning across fields:
+ * `\hat` can mean an estimator, a unit vector or a Fourier transform; `\bar`
+ * a mean, a conjugate or a closure; `'` a derivative or "another one". A
+ * course that uses one consistently says so with `rules.N22.allow` (a physics
+ * course might allow `\dot` and `\vec`); anything else is explained by an
+ * operator entry (`latex: \hat{}`) or a whole-form entry (`latex:
+ * \hat{\beta}`). Names are the canonical ones in `DECORATION_NAMES`
+ * (`math-glyphs.mjs`): `\hat`, `\overline`, `'`, `*`, `\dagger`, ….
+ */
+export const BASE_ACCENTS = Object.freeze(new Set());
+
+/**
+ * The decorations a course treats as universal, given its `rules.N22` block:
+ * the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} accents
+ * @returns {Set<string>}
+ */
+export function effectiveAccentAllowlist(accents) {
+  const allow = accents?.allow ?? [];
+  const deny = new Set(accents?.deny ?? []);
+  const effective = new Set(BASE_ACCENTS);
+  for (const name of allow) effective.add(name);
+  for (const name of deny) effective.delete(name);
+  return effective;
+}

package/src/reference/base-roman-labels.mjs

@@ -5,8 +5,8 @@
  * (rule N8); this is its `\mathrm{…}` twin (rule N10).
  *
  * Rationale: the completeness gate has no opinion about `\mathrm{…}` bodies —
- * they are a typographic label to KaTeX, not a bindable symbol, and N3
- * requires the format without asking whether the label is ever explained.
+ * they are a typographic label to KaTeX, not a bindable symbol, so the
+ * format half of rule N10 says nothing about whether the label is explained.
  * The `roman-label-explained` consistency check fills that gap: a label 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.

package/src/reference/consistency.ts

@@ -24,12 +24,21 @@
  *                                     uses is on the shipped/course roman-label
  *                                     allowlist or carries a notation entry
  *                                     (rule N10)
+ *   (j) accent-explained             a decoration a lesson composes (`\hat`,
+ *                                     `'`, `^*`, …) is on the course accent
+ *                                     allowlist, explained by an operator entry,
+ *                                     or part of a whole-form entry (rule N22)
+ *   (k) operator-suspended /         a `notation.suspend` item, with or without
+ *       operator-suspension-reason   its reason, and a whole-form entry that
+ *       / operator-shadowed          shadows an operator the page does not
+ *                                     suspend (rule N22)
  *
  * Check (d) — the committed per-lesson resolution report — lives in
  * `src/content/resolution-report.ts`.
  */
 
 import type {
+  CourseAccents,
   CourseConventions,
   CourseOperators,
   CourseRomanLabels,
@@ -37,9 +46,19 @@ import type {
 import type { CurriculumCatalog } from '../curriculum/validation';
 import type { NotationSpec } from '../compiler/collections';
 import type { LintIgnore } from './lint-ignore';
+import { effectiveAccentAllowlist } from './base-accents.mjs';
 import { effectiveOperatorAllowlist } from './base-operators.mjs';
 import { effectiveRomanLabelAllowlist } from './base-roman-labels.mjs';
-import { collectOperators, collectRomanLabels } from './math-glyphs.mjs';
+import { stripEquationLabels } from './equations.mjs';
+import { pageScope } from './gate-math';
+import {
+  collectDecorations,
+  collectOperators,
+  collectRomanLabels,
+  decorationOfEntry,
+  operatorEntryLatex,
+  resolveMathGlyphs,
+} from './math-glyphs.mjs';
 import { offVocabularyTokens } from './units-vocab';
 import type {
   NotationDefinitionRecord,
@@ -58,7 +77,11 @@ export type ConsistencyCode =
   | 'card-wants-demoting'
   | 'gloss-name-shape'
   | 'operator-explained'
-  | 'roman-label-explained';
+  | 'roman-label-explained'
+  | 'accent-explained'
+  | 'operator-suspended'
+  | 'operator-suspension-reason'
+  | 'operator-shadowed';
 
 export interface ConsistencyDiagnostic {
   readonly code: ConsistencyCode;
@@ -85,6 +108,8 @@ export interface ConsistencyInput {
   readonly operators?: CourseOperators;
   /** This course's edits to the roman-label baseline (rule N10). */
   readonly romanLabels?: CourseRomanLabels;
+  /** This course's edits to the (empty) accent baseline (rule N22). */
+  readonly accents?: CourseAccents;
 }
 
 const CONVENTION_RE =
@@ -102,11 +127,17 @@ interface MathSpan {
   readonly latex: string;
 }
 
+/**
+ * Every `$$…$$` then `$…$` span in `body`, outside code. A `\label{eq:…}`
+ * (D7) is stripped: it is an identity marker KaTeX cannot parse, and the
+ * scans below treat an unparseable span as having nothing in it — so left in,
+ * every labelled display equation was invisible to rules N8, N10 and N22.
+ */
 function mathSpans(body: string): MathSpan[] {
   const searchable = stripCode(body);
   const spans: MathSpan[] = [];
   for (const match of searchable.matchAll(/\$\$([\s\S]+?)\$\$/g)) {
-    spans.push({ latex: match[1] ?? '' });
+    spans.push({ latex: stripEquationLabels(match[1] ?? '') });
   }
   for (const match of searchable
     .replace(/\$\$([\s\S]+?)\$\$/g, (block) => block.replace(/[^\n]/g, ' '))
@@ -508,8 +539,8 @@ function checkOperatorExplained(
 
 /**
  * (i) roman-label-explained (rule N10) — the `\mathrm{…}` twin of (h)
- * above: N3 requires the *format* (`\mathrm{KE}`, never bare `KE`) but has
- * no opinion on whether the label is ever explained, because the glyph
+ * above: N10's format half (`\mathrm{KE}`, never bare `KE`) says nothing
+ * about whether the label is ever explained, because the glyph
  * resolver skips a `\mathrm{…}` body whole. This is the check that looks at
  * them; it reads `collectRomanLabels`, which parses with the same pinned
  * KaTeX as the completeness gate.
@@ -566,6 +597,140 @@ function checkRomanLabelExplained(
   }
 }
 
+function sharedScopeByKey(
+  input: ConsistencyInput,
+): Map<string, { key: string; notation: string }> {
+  return new Map(
+    input.notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      { key: definition.key, notation: definition.notation },
+    ]),
+  );
+}
+
+/**
+ * (j) accent-explained (rule N22) — the decoration twin of (h): an accent or
+ * superscript mark a lesson *composes* (`\hat{\beta}` read as "hat applied to
+ * β") is universal for the course (`rules.N22.allow`; the shipped list is
+ * empty), explained by an operator entry in the page's scope (`latex:
+ * \hat{}`), or not composing at all because a whole-form entry covers it
+ * (`latex: \hat{\beta}`). Only the resolver knows which whole form covered an
+ * occurrence (`\theta^*` and `\theta^{*}` are one form), so this runs it over
+ * each span with the same page scope as the completeness gate. A span that
+ * will not resolve is the gate's to report, not this check's.
+ */
+function checkAccentExplained(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const allowlist = effectiveAccentAllowlist(input.accents);
+  const sharedByKey = sharedScopeByKey(input);
+
+  for (const lesson of input.notationInput.lessons) {
+    const scope = pageScope(lesson, sharedByKey);
+    const suspended = (lesson.suspended ?? []).map((item) => item.operator);
+    const reported = new Set<string>();
+    for (const span of mathSpans(lesson.body)) {
+      let decorations;
+      try {
+        ({ decorations } = resolveMathGlyphs(span.latex, scope, { suspended }));
+      } catch {
+        continue;
+      }
+      for (const decoration of decorations) {
+        if (decoration.wholeForm !== null || decoration.operator !== null) continue;
+        // A suspended decoration never composes; the gate fails it instead.
+        if (suspended.includes(decoration.name)) continue;
+        if (allowlist.has(decoration.name)) continue;
+        if (reported.has(decoration.name)) continue;
+        reported.add(decoration.name);
+        if (input.lintIgnore.matches('accent-explained', decoration.name)) {
+          continue;
+        }
+        out.push({
+          code: 'accent-explained',
+          severity: 'warning',
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          glyph: decoration.name,
+          message: `${lesson.lessonId}: decoration ${JSON.stringify(decoration.name)} (in ${JSON.stringify(decoration.token)}) is an operator that is neither universal for this course nor explained; give it an operator entry (latex ${JSON.stringify(operatorEntryLatex(decoration.name))}) introduced with [[key]] or in notation.local, give the whole form its own entry (latex ${JSON.stringify(decoration.token)}), or add ${JSON.stringify(decoration.name)} to rules.N22.allow`,
+        });
+      }
+    }
+  }
+}
+
+/**
+ * (k) operator-suspended / operator-suspension-reason / operator-shadowed
+ * (rule N22). A `notation.suspend` item is a deliberate departure from N22 on
+ * one page: with its `reason` it is recorded (info), without one it is a
+ * warning — the reason is what a reviewer needs. And a whole-form entry whose
+ * decoration is explained or universal on its page, but not suspended there,
+ * is noted (info): the entry's card wins for that form, which is right for a
+ * refinement ("β̂ is the OLS estimate") and a smell when the decoration never
+ * means the operator on that page.
+ */
+function checkOperatorSuspension(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const allowlist = effectiveAccentAllowlist(input.accents);
+  const sharedByKey = sharedScopeByKey(input);
+
+  for (const lesson of input.notationInput.lessons) {
+    const suspensions = lesson.suspended ?? [];
+    for (const { operator, reason } of suspensions) {
+      const code =
+        reason === undefined ? 'operator-suspension-reason' : 'operator-suspended';
+      if (input.lintIgnore.matches(code, operator)) continue;
+      out.push({
+        code,
+        severity: reason === undefined ? 'warning' : 'info',
+        lessonId: lesson.lessonId,
+        file: lesson.source.file,
+        glyph: operator,
+        message:
+          reason === undefined
+            ? `${lesson.lessonId}: notation.suspend suspends ${JSON.stringify(operator)} with no reason; say why it is not an operator on this page (reason: …)`
+            : `${lesson.lessonId}: ${JSON.stringify(operator)} is not an operator on this page (notation.suspend): ${reason}`,
+      });
+    }
+
+    const suspended = new Set(suspensions.map((item) => item.operator));
+    const scope = pageScope(lesson, sharedByKey);
+    const explained = new Set(
+      scope
+        .map((entry) => decorationOfEntry(entry.notation))
+        .filter((name): name is string => name !== undefined),
+    );
+    for (const entry of scope) {
+      if (decorationOfEntry(entry.notation) !== undefined) continue;
+      const names = new Set(
+        collectDecorations(entry.notation).map((decoration) => decoration.name),
+      );
+      for (const name of names) {
+        if (suspended.has(name)) continue;
+        const how = explained.has(name)
+          ? 'explained by an operator entry'
+          : allowlist.has(name)
+            ? 'universal for this course'
+            : undefined;
+        if (how === undefined) continue;
+        if (input.lintIgnore.matches('operator-shadowed', entry.key)) continue;
+        out.push({
+          code: 'operator-shadowed',
+          severity: 'info',
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          key: entry.key,
+          glyph: name,
+          message: `${lesson.lessonId}: ${entry.key} (${entry.notation}) has its own entry, so its card wins over the ${JSON.stringify(name)} operator (${how}) for that form; if ${JSON.stringify(name)} never means the operator on this page, suspend it (notation.suspend)`,
+        });
+      }
+    }
+  }
+}
+
 const CHECKS: ((
   input: ConsistencyInput,
   out: ConsistencyDiagnostic[],
@@ -580,6 +745,8 @@ const CHECKS: ((
   checkGlossNameShape,
   checkOperatorExplained,
   checkRomanLabelExplained,
+  checkAccentExplained,
+  checkOperatorSuspension,
 ];
 
 /**
@@ -618,6 +785,10 @@ export function consistencyCounts(
     'gloss-name-shape': 0,
     'operator-explained': 0,
     'roman-label-explained': 0,
+    'accent-explained': 0,
+    'operator-suspended': 0,
+    'operator-suspension-reason': 0,
+    'operator-shadowed': 0,
   } satisfies Record<ConsistencyCode, number>;
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/src/reference/delimiter-size.ts

@@ -1,14 +1,20 @@
 /**
- * Rule N17: nested scalable delimiters must make their hierarchy visible.
+ * Rule N17: a nested scalable delimiter is sized by the engine, never by hand.
+ *
+ * The engine installs a KaTeX whose `\delimitershortfall` is `-1pt`
+ * (`katex-delimiters.mjs`), so a `\left`/`\right` pair is always
+ * strictly taller than what it wraps. Nesting depth therefore shows up on its
+ * own, and a hand-picked `\bigl`…`\Biggr` inside a nest only replaces a size
+ * that tracks the content with a fixed glyph that does not.
  *
  * This deliberately parses only sizing syntax. It does not decide whether a
  * parenthesis, bracket, or brace is semantic, and it never recommends changing
- * one delimiter shape into another. N16's alternating-shape preference remains
- * a review-only authoring concern.
+ * one delimiter shape into another — N17's other half, that a delimiter's shape
+ * is fixed by its meaning and never alternates to show depth, stays a
+ * review-only authoring concern (which is why N17 is `partial`).
  */
 
-export const DELIMITER_SIZE_DIAGNOSTIC_CODE =
-  'delimiter-size-hierarchy' as const;
+export const DELIMITER_SIZE_DIAGNOSTIC_CODE = 'delimiter-manual-size' as const;
 
 export type DelimiterSizeName =
   | 'automatic'
@@ -18,7 +24,6 @@ export type DelimiterSizeName =
   | 'Bigg';
 
 export interface DelimiterSizeSuggestion {
-  readonly size: Exclude<DelimiterSizeName, 'automatic' | 'big'>;
   readonly open: string;
   readonly close: string;
   readonly latex: string;
@@ -30,9 +35,9 @@ export interface DelimiterSizeDiagnostic {
   readonly offset: number;
   readonly line: number;
   readonly column: number;
-  readonly outerSize: DelimiterSizeName;
-  readonly nestedSize: DelimiterSizeName;
-  readonly suggestion?: DelimiterSizeSuggestion;
+  /** The hand-picked size that should become `\left`/`\right`. */
+  readonly size: Exclude<DelimiterSizeName, 'automatic'>;
+  readonly suggestion: DelimiterSizeSuggestion;
   readonly message: string;
 }
 
@@ -62,7 +67,6 @@ interface DelimiterPair {
   readonly open: DelimiterToken;
   close?: DelimiterToken;
   readonly children: DelimiterPair[];
-  requiredRank?: number;
 }
 
 const SIZE_SPECS: readonly SizeSpec[] = [
@@ -114,10 +118,6 @@ const COMMAND_SPECS: readonly CommandSpec[] = SIZE_SPECS.flatMap((spec) => [
   { ...spec, command: spec.closeCommand, tokenKind: 'close' as const },
 ]).sort((left, right) => right.command.length - left.command.length);
 
-const SUGGESTION_BY_RANK = new Map(
-  SIZE_SPECS.filter((spec) => spec.rank >= 2).map((spec) => [spec.rank, spec]),
-);
-
 function delimiterAt(
   latex: string,
   offset: number,
@@ -226,31 +226,22 @@ function lineAndColumn(
   };
 }
 
-function sizeName(rank: number): DelimiterSizeName {
-  return SUGGESTION_BY_RANK.get(rank)?.name ?? 'Bigg';
-}
+const SPEC_BY_SIZE = new Map(SIZE_SPECS.map((spec) => [spec.name, spec]));
 
-function suggestionFor(
-  pair: DelimiterPair,
-  requiredRank: number,
-): DelimiterSizeSuggestion | undefined {
-  const close = pair.close;
-  const spec = SUGGESTION_BY_RANK.get(requiredRank);
-  if (!close || !spec || spec.name === 'automatic' || spec.name === 'big') {
-    return undefined;
-  }
-  return {
-    size: spec.name,
-    open: `${spec.openCommand}${pair.open.delimiter}`,
-    close: `${spec.closeCommand}${close.delimiter}`,
-    latex: `${spec.openCommand}${pair.open.delimiter} ... ${spec.closeCommand}${close.delimiter}`,
-  };
+function suggestionFor(pair: DelimiterPair): DelimiterSizeSuggestion {
+  const open = `\\left${pair.open.delimiter}`;
+  const close = `\\right${pair.close?.delimiter ?? pair.open.delimiter}`;
+  return { open, close, latex: `${open} ... ${close}` };
 }
 
 /**
- * Warn when a scalable outer pair is not at least one manual size level above
- * everything nested inside it. `\left` and `\big` form the baseline level;
- * progressively larger levels are `\Big`, `\bigg`, and `\Bigg`.
+ * Warn when a pair that takes part in a nest of scalable delimiters is sized
+ * by hand instead of by `\left`/`\right`.
+ *
+ * A pair takes part in a nest when it contains, or sits inside, another pair
+ * this linter tracks. A lone hand-sized pair around otherwise bare content —
+ * `\bigl(x(t),\ y(t)\bigr)` for a tuple — is a deliberate typographic
+ * choice at a single level, has no hierarchy to get wrong, and is left alone.
  *
  * Only `()`, `[]`, and `\{\}` are parsed. Bare delimiters are intentionally
  * ignored: N15 owns that separate error, while ordinary semantic notation
@@ -261,41 +252,29 @@ export function lintDelimiterSizes(latex: string): DelimiterSizeDiagnostic[] {
   if (!roots) return [];
   const diagnostics: DelimiterSizeDiagnostic[] = [];
 
-  const assess = (pair: DelimiterPair): number => {
-    let largestNestedRequirement = 0;
-    let representativeNestedSize: DelimiterSizeName = 'automatic';
-    for (const child of pair.children) {
-      const childRequired = assess(child);
-      if (childRequired > largestNestedRequirement) {
-        largestNestedRequirement = childRequired;
-        representativeNestedSize = sizeName(childRequired);
-      }
-    }
-
-    const requiredRank =
-      largestNestedRequirement === 0
-        ? pair.open.rank
-        : largestNestedRequirement + 1;
-    pair.requiredRank = Math.max(pair.open.rank, requiredRank);
-    if (largestNestedRequirement > 0 && pair.open.rank < requiredRank) {
+  const visit = (pair: DelimiterPair, nested: boolean): void => {
+    const inNest = nested || pair.children.length > 0;
+    if (inNest && pair.open.pairKind === 'manual') {
       const location = lineAndColumn(latex, pair.open.offset);
-      const suggestion = suggestionFor(pair, requiredRank);
+      const suggestion = suggestionFor(pair);
       diagnostics.push({
         code: DELIMITER_SIZE_DIAGNOSTIC_CODE,
         severity: 'warning',
         offset: pair.open.offset,
         ...location,
-        outerSize: pair.open.size,
-        nestedSize: representativeNestedSize,
-        ...(suggestion ? { suggestion } : {}),
-        message: suggestion
-          ? `Outer delimiters are not larger than their nested pair. Use ${suggestion.latex}; preserve the original opening and closing delimiter shapes (rule N17).`
-          : `Outer delimiters are not larger than their nested pair, and no larger standard manual delimiter size remains. Preserve the original opening and closing shapes and restructure the expression if necessary (rule N17).`,
+        size: pair.open.size as Exclude<DelimiterSizeName, 'automatic'>,
+        suggestion,
+        message:
+          `A nested delimiter pair is sized by hand with ` +
+          `${SPEC_BY_SIZE.get(pair.open.size)?.openCommand ?? pair.open.size}` +
+          `${pair.open.delimiter}. Use ` +
+          `${suggestion.latex} and let the engine size the nest; preserve the ` +
+          `original opening and closing delimiter shapes (rule N17).`,
       });
     }
-    return pair.requiredRank;
+    for (const child of pair.children) visit(child, true);
   };
 
-  for (const root of roots) assess(root);
+  for (const root of roots) visit(root, false);
   return diagnostics.sort((left, right) => left.offset - right.offset);
 }

package/src/reference/diagrams-validate.ts

@@ -11,7 +11,8 @@ export type DiagramDiagnosticCode =
   | 'dia-invalid-key'
   | 'dia-duplicate-key'
   | 'dia-ref-resolves'
-  | 'dia-key-unused';
+  | 'dia-key-unused'
+  | 'dia-removed-prop';
 
 export interface DiagramDiagnostic {
   readonly code: DiagramDiagnosticCode;
@@ -29,6 +30,13 @@ export interface DiagramValidation extends KeyedFloatValidation {
   readonly diagnostics: readonly DiagramDiagnostic[];
 }
 
+/**
+ * The fix for a compaction prop: a diagram is always its graph and then its
+ * caption line (docs/plans/figures-and-short-captions.md, decision 7).
+ */
+export const DIAGRAM_NO_LONGER_FOLDS =
+  'a diagram no longer folds by itself — delete the prop. To let a reader fold it away, wrap it in a `<Fold>` or put it in a collapsible section.';
+
 export function validateDiagrams(
   lessons: readonly DiagramLessonInput[],
 ): DiagramValidation {
@@ -36,5 +44,13 @@ export function validateDiagrams(
     tagName: 'Diagram',
     prefix: 'dia',
     noun: 'diagram',
+    removedProps: {
+      label:
+        'rename it `caption` (shown below the diagram with its number), and add an optional `short` caption if the caption is long.',
+      title:
+        'a diagram is named by its `caption` (shown below it with its number) and an optional `short` caption.',
+      defaultOpen: DIAGRAM_NO_LONGER_FOLDS,
+      rememberState: DIAGRAM_NO_LONGER_FOLDS,
+    },
   }) as DiagramValidation;
 }

package/src/reference/equations-validate.ts

@@ -15,6 +15,8 @@ import { parseEquationRef, scanEquationLabels } from './equations.mjs';
 export interface EquationLabelRecord {
   readonly key: string;
   readonly number: string;
+  /** The equation's `\caption{…}` short caption, when it has one. */
+  readonly short?: string;
   readonly lessonId: string;
   readonly slug: string;
   readonly section: number;
@@ -54,12 +56,13 @@ export interface EquationLessonInput {
   readonly file: string;
   readonly body: string;
   /**
-   * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
-   * and how many display equations earlier lessons of that part already used.
-   * When set, equations are numbered `‹part›.‹offset + n›`; when omitted, the
-   * legacy `##`-section scheme. See `docs/authoring/structure.md`.
+   * `{ prefix, offset }` — the lesson's float-number prefix (`‹part›.‹chapter›`,
+   * or `‹part›` under `numbering.floats: "part"`) and how many display
+   * equations precede the lesson in that scope. When set, equations are
+   * numbered `‹prefix›.‹offset + n›`; when omitted, the legacy `##`-section
+   * scheme. See `docs/authoring/structure.md`.
    */
-  readonly numbering?: { readonly prefix: number; readonly offset: number };
+  readonly numbering?: { readonly prefix: number | string; readonly offset: number };
 }
 
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
@@ -100,6 +103,7 @@ export function validateEquations(
     for (const raw of scanEquationLabels(lesson.body, lesson.numbering) as {
       key: string;
       number: string;
+      short: string | null;
       section: number;
       indexInSection: number;
     }[]) {
@@ -119,6 +123,7 @@ export function validateEquations(
       labels.push({
         key: raw.key,
         number: raw.number,
+        ...(raw.short ? { short: raw.short } : {}),
         lessonId: lesson.lessonId,
         slug: lesson.slug,
         section: raw.section,