explico 0.5.0 → 0.7.0

package/src/compiler/cli.ts

@@ -18,6 +18,9 @@
  *     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
@@ -45,6 +48,7 @@ import remarkNotation, {
   createRemarkNotationOptions,
 } from '../reference/remark-notation.mjs';
 import remarkShortNote from '../reference/remark-short-note.mjs';
+import type { DiagnosticSeverity } from '../reference/types';
 import type { Manifest, ManifestLesson } from './manifest';
 import { isLessonSlug, lessonIdFromSlug } from './lesson-derivation';
 
@@ -81,10 +85,15 @@ export class ContentCliError extends Error {
 /** One normalized diagnostic. `code` is `<source>:<kind>` and always stable. */
 export interface CliDiagnostic {
   readonly code: string;
-  readonly severity: 'error' | 'warning';
+  readonly severity: DiagnosticSeverity;
   readonly message: string;
   readonly file?: string;
   readonly line?: number;
+  readonly column?: number;
+}
+
+function diagnosticSeverity(value: unknown): DiagnosticSeverity {
+  return value === 'info' || value === 'warning' ? value : 'error';
 }
 
 function mentions(message: string, lessonId: string, file: string): boolean {
@@ -115,7 +124,7 @@ export function lessonDiagnostics(
     if (!mentions(issue.message, id, file)) continue;
     out.push({
       code: `curriculum:${issue.kind}`,
-      severity: issue.severity === 'warning' ? 'warning' : 'error',
+      severity: diagnosticSeverity(issue.severity),
       message: issue.message,
     });
   }
@@ -135,7 +144,7 @@ export function lessonDiagnostics(
     }
     out.push({
       code: `${group}:${entry.code}`,
-      severity: entry.severity === 'warning' ? 'warning' : 'error',
+      severity: diagnosticSeverity(entry.severity),
       message: entry.message,
       ...withFile(entryFile),
     });
@@ -150,11 +159,12 @@ export function lessonDiagnostics(
         ));
     if (!forLesson) continue;
     out.push({
-      code: `math:${diagnostic.context}`,
+      code: `math:${diagnostic.code ?? diagnostic.context}`,
       severity: diagnostic.severity,
       message: diagnostic.message,
       file: diagnostic.file,
       ...(diagnostic.line === undefined ? {} : { line: diagnostic.line }),
+      ...(diagnostic.column === undefined ? {} : { column: diagnostic.column }),
     });
   }
 
@@ -168,7 +178,7 @@ export function lessonDiagnostics(
     }
     out.push({
       code: `equations:${diagnostic.code}`,
-      severity: diagnostic.severity === 'warning' ? 'warning' : 'error',
+      severity: diagnosticSeverity(diagnostic.severity),
       message: diagnostic.message,
       ...withFile(diagnostic.file),
     });
@@ -190,7 +200,7 @@ export function lessonDiagnostics(
     }
     out.push({
       code: diagnostic.code,
-      severity: diagnostic.severity === 'warning' ? 'warning' : 'error',
+      severity: diagnosticSeverity(diagnostic.severity),
       message: diagnostic.message,
       ...withFile(diagnostic.file),
     });
@@ -200,7 +210,7 @@ export function lessonDiagnostics(
     if (diagnostic.file !== file && diagnostic.lessonId !== id) continue;
     out.push({
       code: `consistency:${diagnostic.code}`,
-      severity: 'warning',
+      severity: diagnostic.severity,
       message: diagnostic.message,
       ...withFile(diagnostic.file),
     });
@@ -500,6 +510,7 @@ export interface StatusReport {
   readonly diagnostics: {
     readonly errors: number;
     readonly warnings: number;
+    readonly infos: number;
   };
 }
 
@@ -517,10 +528,7 @@ export function contentStatus(manifest: Manifest): StatusReport {
     .filter((diagnostic) => diagnostic.code === 'unused-definition')
     .map((diagnostic) => ({
       code: `notation:${diagnostic.code}`,
-      severity:
-        diagnostic.severity === 'warning'
-          ? ('warning' as const)
-          : ('error' as const),
+      severity: diagnosticSeverity(diagnostic.severity),
       message: diagnostic.message,
       ...(diagnostic.source?.file === undefined
         ? {}
@@ -539,7 +547,7 @@ export function contentStatus(manifest: Manifest): StatusReport {
     ...manifest.diagnostics.diagrams.map((d) => d.severity),
     ...manifest.diagnostics.checks.map((d) => d.severity),
     ...manifest.diagnostics.rawFloats.map((d) => d.severity),
-    ...manifest.diagnostics.consistency.map(() => 'warning' as const),
+    ...manifest.diagnostics.consistency.map((d) => d.severity),
     ...manifest.diagnostics.knowledge.map((d) => d.severity),
   ];
 
@@ -583,10 +591,134 @@ export function contentStatus(manifest: Manifest): StatusReport {
       errors: allDiagnostics.filter((severity) => severity === 'error').length,
       warnings: allDiagnostics.filter((severity) => severity === 'warning')
         .length,
+      infos: allDiagnostics.filter((severity) => severity === 'info').length,
     },
   };
 }
 
+// --- content diagnostics -------------------------------------------------
+
+export type DiagnosticThreshold = DiagnosticSeverity;
+
+export interface DiagnosticsReport {
+  readonly minimumSeverity: DiagnosticThreshold;
+  readonly count: number;
+  readonly diagnostics: readonly CliDiagnostic[];
+}
+
+export interface WarningsReport {
+  readonly count: number;
+  readonly warnings: readonly CliDiagnostic[];
+}
+
+type DiagnosticRecord = Record<string, unknown> & {
+  readonly code?: unknown;
+  readonly kind?: unknown;
+  readonly severity?: unknown;
+  readonly message?: unknown;
+  readonly file?: unknown;
+  readonly lessonId?: unknown;
+  readonly line?: unknown;
+  readonly column?: unknown;
+  readonly source?: unknown;
+};
+
+function numericLocation(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0
+    ? value
+    : undefined;
+}
+
+const SEVERITY_RANK: Readonly<Record<DiagnosticSeverity, number>> = {
+  info: 0,
+  warning: 1,
+  error: 2,
+};
+
+/** Manifest diagnostics at or above a severity, normalized for tooling. */
+export function contentDiagnostics(
+  manifest: Manifest,
+  minimumSeverity: DiagnosticThreshold = 'info',
+): DiagnosticsReport {
+  const lessonFileByHint = new Map<string, string>();
+  for (const lesson of manifest.lessons) {
+    lessonFileByHint.set(lesson.id, lesson.file);
+    lessonFileByHint.set(lesson.slug, lesson.file);
+    lessonFileByHint.set(lesson.file, lesson.file);
+  }
+
+  const groups = Object.entries(manifest.diagnostics) as readonly [
+    string,
+    readonly unknown[],
+  ][];
+  const diagnostics: CliDiagnostic[] = [];
+  for (const [group, values] of groups) {
+    for (const value of values) {
+      const diagnostic = value as DiagnosticRecord;
+      const severity = diagnosticSeverity(diagnostic.severity);
+      if (SEVERITY_RANK[severity] < SEVERITY_RANK[minimumSeverity]) continue;
+      const source =
+        diagnostic.source !== null && typeof diagnostic.source === 'object'
+          ? (diagnostic.source as Record<string, unknown>)
+          : undefined;
+      const rawFile =
+        typeof diagnostic.file === 'string'
+          ? diagnostic.file
+          : typeof source?.file === 'string'
+            ? source.file
+            : undefined;
+      const lessonId =
+        typeof diagnostic.lessonId === 'string'
+          ? diagnostic.lessonId
+          : undefined;
+      const file =
+        (rawFile === undefined ? undefined : lessonFileByHint.get(rawFile)) ??
+        (lessonId === undefined ? undefined : lessonFileByHint.get(lessonId)) ??
+        rawFile;
+      const line =
+        numericLocation(diagnostic.line) ?? numericLocation(source?.line);
+      const column =
+        numericLocation(diagnostic.column) ?? numericLocation(source?.column);
+      const detail =
+        typeof diagnostic.code === 'string'
+          ? diagnostic.code
+          : typeof diagnostic.kind === 'string'
+            ? diagnostic.kind
+            : 'diagnostic';
+      diagnostics.push({
+        code: `${group}:${detail}`,
+        severity,
+        message: String(diagnostic.message ?? detail),
+        ...(file === undefined ? {} : { file }),
+        ...(line === undefined ? {} : { line }),
+        ...(column === undefined ? {} : { column }),
+      });
+    }
+  }
+
+  diagnostics.sort(
+    (left, right) =>
+      (left.file ?? '').localeCompare(right.file ?? '') ||
+      (left.line ?? 0) - (right.line ?? 0) ||
+      (left.column ?? 0) - (right.column ?? 0) ||
+      left.code.localeCompare(right.code) ||
+      left.message.localeCompare(right.message),
+  );
+  return {
+    minimumSeverity,
+    count: diagnostics.length,
+    diagnostics,
+  };
+}
+
+/** Every warning exactly; errors and informational advice are excluded. */
+export function contentWarnings(manifest: Manifest): WarningsReport {
+  const warnings = contentDiagnostics(manifest, 'warning').diagnostics.filter(
+    (diagnostic) => diagnostic.severity === 'warning',
+  );
+  return { count: warnings.length, warnings };
+}
+
 // --- content context ---------------------------------------------------
 
 export interface ContextReport {

package/src/compiler/course-config.ts

@@ -116,6 +116,43 @@ export interface CourseAbout {
   readonly changelogHref?: string;
 }
 
+/**
+ * A course's chosen initial open/closed state for the engine's own built-in
+ * collapsible sections — the "Page notation" panel (`NotationLayer.astro`)
+ * and the generated "References" section (`remark-citation.mjs`). Each is
+ * independent of `defaultCollapsible.sections`/`.subsections` (an author's
+ * own `##` headings): both of these are engine-authored, not written by a
+ * lesson, so they need their own default rather than inheriting the site's
+ * general heading default.
+ *
+ * `true` starts open, `false` (or omitted) starts closed — the engine's own
+ * default is closed either way, matching a long panel a reader usually
+ * doesn't need open on arrival.
+ */
+export interface CourseDisclosureDefaults {
+  /** Initial state of the "Page notation" panel. Default: closed. */
+  readonly notation?: boolean;
+  /** Initial state of the generated "References" section. Default: closed. */
+  readonly references?: boolean;
+}
+
+/** The stable, non-optional form `NormalizedLessonExports` mirrors. */
+export interface NormalizedDisclosureDefaults {
+  readonly notation: boolean;
+  readonly references: boolean;
+}
+
+/** Validate and canonicalize `CourseConfig.disclosureDefaults`. Absent (or
+ *  an absent sub-field) resolves to closed, the engine's own default. */
+export function normalizeDisclosureDefaults(
+  config: CourseConfig,
+): NormalizedDisclosureDefaults {
+  return {
+    notation: config.disclosureDefaults?.notation === true,
+    references: config.disclosureDefaults?.references === true,
+  };
+}
+
 /** Optional, build-time lesson artifacts exposed to readers. */
 export interface LessonExportsConfig {
   /** Emit one self-contained, offline-capable HTML file per lesson. */
@@ -162,6 +199,9 @@ export interface CourseConfig {
   readonly abbreviations?: CourseAbbreviations;
   /** Per-lesson export actions and downloadable artifacts. Disabled when omitted. */
   readonly lessonExports?: LessonExportsConfig;
+  /** Initial open/closed state for the engine's own built-in collapsible
+   *  sections ("Page notation", "References"). Closed when omitted. */
+  readonly disclosureDefaults?: CourseDisclosureDefaults;
 }
 
 /** Validate and canonicalize the build-facing lesson-export configuration. */

package/src/compiler/exports/standalone-html.ts

@@ -722,6 +722,20 @@ async function inlineResourceAttribute(
   setAttribute(node, name, await assetDataUrl(path, context));
 }
 
+const INLINEABLE_LINK_RELS: ReadonlySet<string> = new Set([
+  'stylesheet',
+  'icon',
+  'shortcut icon',
+  'apple-touch-icon',
+  'apple-touch-icon-precomposed',
+  'mask-icon',
+]);
+
+function isInlineableLinkRel(node: HtmlElement): boolean {
+  const rel = attribute(node, 'rel');
+  return rel !== undefined && INLINEABLE_LINK_RELS.has(rel.trim().toLowerCase());
+}
+
 function parseSourceSet(value: string): readonly { url: string; descriptor: string }[] {
   const candidates = value.match(/(?:[^\s,]+)(?:\s+(?:\d+w|\d+(?:\.\d+)?x))?/gu) ?? [];
   return candidates.map((candidate) => {
@@ -748,6 +762,7 @@ async function inlineMedia(document: HtmlNode, context: ExportContext): Promise<
         'Standalone HTML does not support an iframe src; use self-contained semantic DOM instead.',
       );
     }
+    if (node.tagName === 'link' && !isInlineableLinkRel(node)) continue;
     const names = resources[node.tagName] ?? [];
     for (const name of names) await inlineResourceAttribute(node, name, context);
     if (node.tagName === 'use' || node.tagName === 'image') {

package/src/compiler/logging.ts

@@ -0,0 +1,248 @@
+/**
+ * Run logs for `pnpm validate:content`, in Python's `logging` format.
+ *
+ * The terminal keeps the compact `[code] message` lines it has always shown.
+ * This module is the second handler over the same records: it writes them to
+ * `build/logs/<timestamp>/` in the format Python's `logging` emits, so a run
+ * can be grepped by level and by subsystem long after the terminal scrolled
+ * away.
+ *
+ *     %(asctime)s %(levelname)s %(name)s: %(message)s
+ *
+ *     2026-09-18 03:22:47,482 WARNING explico.notation: [undefined-reference] …
+ *
+ * Three files per run, each a superset of the one above it, so you open the
+ * narrowest one that still answers the question:
+ *
+ *     build/logs/2026-09-18T03-22-47/
+ *       error.log     errors only
+ *       warning.log   errors + warnings
+ *       info.log      errors + warnings + info
+ *
+ * Nothing is pruned — `build/` is git-ignored, so old runs are yours to clean
+ * up — and `build/logs/latest` points at the newest run.
+ *
+ * Levels carry their Python meaning. `error` is a blocking diagnostic (the
+ * caller still throws; this module only records), `warning` is a non-blocking
+ * finding, and `info` is the run summary plus the severity-`info` diagnostics
+ * the engine has always produced but never printed.
+ *
+ * Each level method **returns its message**, so a call site can log and print
+ * in one expression without the two drifting apart:
+ *
+ *     console.warn(log.warning('notation', `[${d.code}] ${d.message}`));
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, relative } from 'node:path';
+
+const REPOSITORY_ROOT = process.cwd();
+/** Sits beside `build/manifest.json` and `build/resolution/` (Phase F). */
+export const LOGS_DIR = join(REPOSITORY_ROOT, 'build', 'logs');
+
+/** Python's levels, narrowed to the three the engine actually emits. */
+export type LogLevel = 'ERROR' | 'WARNING' | 'INFO';
+
+/** Ordered most severe first; a file at index `i` takes levels `0..i`. */
+const LEVELS: readonly LogLevel[] = ['ERROR', 'WARNING', 'INFO'];
+
+/** `error.log` holds `ERROR`, `warning.log` also `WARNING`, and so on. */
+const FILES: readonly { readonly name: string; readonly level: LogLevel }[] = [
+  { name: 'error.log', level: 'ERROR' },
+  { name: 'warning.log', level: 'WARNING' },
+  { name: 'info.log', level: 'INFO' },
+];
+
+/** `true` when a record at `record` belongs in a file whose floor is `file`. */
+function includes(file: LogLevel, record: LogLevel): boolean {
+  return LEVELS.indexOf(record) <= LEVELS.indexOf(file);
+}
+
+function pad(value: number, width = 2): string {
+  return String(value).padStart(width, '0');
+}
+
+/**
+ * Python's `%(asctime)s` — local time, with the comma before the milliseconds
+ * that `logging.Formatter` writes by default.
+ */
+export function formatTimestamp(date: Date): string {
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
+    `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+    `,${pad(date.getMilliseconds(), 3)}`
+  );
+}
+
+/** A filesystem-safe local-time stamp for the run directory's name. */
+export function formatRunStamp(date: Date): string {
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T` +
+    `${pad(date.getHours())}-${pad(date.getMinutes())}-${pad(date.getSeconds())}`
+  );
+}
+
+/**
+ * `explico.<source>` — the logger name is the diagnostic's subsystem, so
+ * filtering by name is filtering by subsystem. `rawFloats` becomes
+ * `explico.raw-floats`; anything already lowercase passes through.
+ */
+export function loggerName(source: string): string {
+  const normalized = source
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase();
+  return normalized.startsWith('explico.')
+    ? normalized
+    : `explico.${normalized}`;
+}
+
+/** One formatted line, without its trailing newline. */
+export function formatRecord(
+  level: LogLevel,
+  source: string,
+  message: string,
+  date: Date,
+): string {
+  return `${formatTimestamp(date)} ${level} ${loggerName(source)}: ${message}`;
+}
+
+export interface RunLogSummary {
+  /** Absolute path of this run's directory. */
+  readonly directory: string;
+  /** Repo-relative form, for printing. */
+  readonly relativeDirectory: string;
+  readonly counts: Readonly<Record<LogLevel, number>>;
+}
+
+/** One diagnostic, across every category's slightly different shape. */
+export interface AnyDiagnostic {
+  readonly severity?: string;
+  readonly message: string;
+  readonly code?: string;
+  readonly kind?: string;
+  readonly file?: string;
+  readonly line?: number;
+  readonly column?: number;
+}
+
+/** `manifest.diagnostics`, structurally — one array per subsystem. */
+export type DiagnosticGroups = Readonly<
+  Record<string, readonly AnyDiagnostic[]>
+>;
+
+export interface RunLog {
+  /** Absolute path of this run's directory. */
+  readonly directory: string;
+  /** Records at `ERROR` and returns `message`. */
+  error(source: string, message: string): string;
+  /** Records at `WARNING` and returns `message`. */
+  warning(source: string, message: string): string;
+  /** Records at `INFO` and returns `message`. */
+  info(source: string, message: string): string;
+  /**
+   * Sweeps every severity-`info` diagnostic in a manifest's `diagnostics` into
+   * `info.log`. Errors and warnings are deliberately **not** taken from here:
+   * they are recorded at the call site that also prints the console line, so
+   * the two can never drift.
+   */
+  infoDiagnostics(diagnostics: DiagnosticGroups): number;
+  /** Refreshes `latest` and reports what the run recorded. */
+  close(): RunLogSummary;
+}
+
+/** `[code] message`, matching what the console has always printed. */
+export function diagnosticLine(diagnostic: AnyDiagnostic): string {
+  const code = diagnostic.code ?? diagnostic.kind;
+  const at = [diagnostic.file, diagnostic.line, diagnostic.column]
+    .filter((part) => part !== undefined)
+    .join(':');
+  const prefix = code === undefined ? '' : `[${code}] `;
+  return at === ''
+    ? `${prefix}${diagnostic.message}`
+    : `${prefix}${at}: ${diagnostic.message}`;
+}
+
+export interface RunLogOptions {
+  /** Overridden in tests; defaults to `build/logs` under the repository root. */
+  readonly root?: string;
+  /** Overridden in tests so the directory name is deterministic. */
+  readonly now?: Date;
+  /** Set `false` to skip the `latest` symlink. */
+  readonly latest?: boolean;
+}
+
+/**
+ * Opens a run directory and returns its log. The directory and its three files
+ * are created up front, so a run that crashes before {@link RunLog.close} still
+ * leaves everything recorded up to that point on disk.
+ */
+export function createRunLog(options: RunLogOptions = {}): RunLog {
+  const root = options.root ?? LOGS_DIR;
+  const started = options.now ?? new Date();
+  const stamp = formatRunStamp(started);
+
+  // Two runs inside the same second get `…-2`, `…-3`, rather than collide.
+  let directory = join(root, stamp);
+  for (let suffix = 2; existsSync(directory); suffix += 1) {
+    directory = join(root, `${stamp}-${suffix}`);
+  }
+  mkdirSync(directory, { recursive: true });
+  for (const file of FILES) writeFileSync(join(directory, file.name), '');
+
+  const counts: Record<LogLevel, number> = { ERROR: 0, WARNING: 0, INFO: 0 };
+
+  const record = (level: LogLevel, source: string, message: string): string => {
+    counts[level] += 1;
+    const line = `${formatRecord(level, source, message, new Date())}\n`;
+    for (const file of FILES) {
+      if (includes(file.level, level)) {
+        appendFileSync(join(directory, file.name), line);
+      }
+    }
+    return message;
+  };
+
+  return {
+    directory,
+    error: (source, message) => record('ERROR', source, message),
+    warning: (source, message) => record('WARNING', source, message),
+    info: (source, message) => record('INFO', source, message),
+    infoDiagnostics(diagnostics) {
+      let written = 0;
+      for (const [source, group] of Object.entries(diagnostics)) {
+        if (!Array.isArray(group)) continue;
+        for (const diagnostic of group) {
+          if (diagnostic.severity !== 'info') continue;
+          record('INFO', source, diagnosticLine(diagnostic));
+          written += 1;
+        }
+      }
+      return written;
+    },
+    close() {
+      if (options.latest !== false) {
+        // Convenience only — a filesystem that refuses symlinks must not fail
+        // a content build that otherwise passed.
+        const link = join(root, 'latest');
+        try {
+          rmSync(link, { force: true });
+          symlinkSync(directory, link, 'dir');
+        } catch {
+          /* a missing `latest` is not worth failing a run over */
+        }
+      }
+      return {
+        directory,
+        relativeDirectory: relative(REPOSITORY_ROOT, directory),
+        counts: { ...counts },
+      };
+    },
+  };
+}

package/src/compiler/manifest.ts

@@ -88,6 +88,7 @@ import {
   gateProseNotationInAssessments,
 } from '../reference/gate-prose-notation';
 import { gateAbbreviations } from '../reference/gate-abbreviations';
+import { gateHeadingLength } from '../reference/gate-heading-length';
 import {
   splitMixedContent,
   type ContentSegment,
@@ -109,8 +110,10 @@ import type {
 import {
   coursePartsOf,
   normalizeLessonExports,
+  normalizeDisclosureDefaults,
   type CourseConfig,
   type NormalizedLessonExports,
+  type NormalizedDisclosureDefaults,
 } from './course-config';
 import {
   resolveKnowledgeVersion,
@@ -177,8 +180,18 @@ import {
  * validation and can never get a stable number or `[[…]]` reference; this
  * flags it (warning-only — the manifest shape a client already reads is
  * unchanged).
+ * v14 (disclosure defaults, additive): `disclosureDefaults` — the resolved
+ * initial open/closed state for the "Page notation" panel and the generated
+ * "References" section, from `CourseConfig.disclosureDefaults`. Both are
+ * engine-authored sections, not written by a lesson, so they get their own
+ * default independent of a course's `##` heading default; closed unless the
+ * course sets one.
+ * v15 (diagnostic severity): public diagnostic severity unions add `info` for
+ * optional advice. Unused keys/definitions and restructuring candidates move
+ * from `warning` to `info`; their diagnostic codes and container fields stay
+ * unchanged.
  */
-export const MANIFEST_SCHEMA_VERSION = 13;
+export const MANIFEST_SCHEMA_VERSION = 15;
 
 const REPOSITORY_ROOT = process.cwd();
 // Content is the top-level `content/` folder; the build output is `build/`
@@ -382,6 +395,8 @@ export interface Manifest {
   readonly schemaVersion: number;
   /** Normalized build/UI settings for opt-in per-lesson exports. */
   readonly lessonExports: NormalizedLessonExports;
+  /** Initial open/closed state for "Page notation" and "References". */
+  readonly disclosureDefaults: NormalizedDisclosureDefaults;
   /** Reader-facing identity + versions (the `[?]` About panel). */
   readonly about: ManifestAbout;
   readonly notation: {
@@ -442,11 +457,11 @@ export interface Manifest {
     readonly notation: readonly NotationDiagnostic[];
     readonly alignment: readonly NotationDiagnostic[];
     readonly math: readonly MathGateDiagnostic[];
-    /** Tier-3 corpus consistency checks (D6). Warnings only. */
+    /** Tier-3 corpus consistency checks (D6). Warnings and optional info. */
     readonly consistency: readonly ConsistencyDiagnostic[];
     /** Knowledge-version checks (C3): `about.version` vs `content/CHANGELOG.md`. Warnings only. */
     readonly knowledge: readonly KnowledgeVersionDiagnostic[];
-    /** Equation-identity checks (D7): `eq-duplicate-key`, `eq-ref-resolves` (error); `eq-key-unused` (warning). */
+    /** Equation identity: broken identities are errors; unused keys are info. */
     readonly equations: readonly EquationDiagnostic[];
     /** `<Table>` identity checks (F-tables-figures) — same codes, `tab-` prefixed. */
     readonly tables: readonly TableDiagnostic[];
@@ -703,6 +718,7 @@ export async function compileManifest(
       abbreviations: abbreviationsInput,
       courseAbbreviations: courseConfig.abbreviations,
     }),
+    ...gateHeadingLength(notationInput.lessons),
   ];
 
   // Pre-render every assessment `prompt` / `explanation` into text/math
@@ -1052,6 +1068,7 @@ export async function compileManifest(
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
     lessonExports: normalizeLessonExports(courseConfig),
+    disclosureDefaults: normalizeDisclosureDefaults(courseConfig),
     about,
     notation: {
       definitions: registry.definitions,