explico 0.14.0 → 0.15.0

package/src/compiler/cli.ts

@@ -63,7 +63,7 @@ import {
 } from '../reference/gate-math';
 import { resolveMathGlyphs } from '../reference/math-glyphs.mjs';
 import { stripEquationLabels } from '../reference/equations.mjs';
-import type { Manifest, ManifestLesson } from './manifest';
+import type { Manifest, ManifestLesson, ManifestLessonFloat } from './manifest';
 import { readRenderDiagnostics, type RenderDiagnostic } from './render-diagnostics';
 import { isLessonSlug, lessonIdFromSlug, mergeTrackOrder } from './lesson-derivation';
 import {
@@ -103,7 +103,8 @@ export type ContentCliCode =
   | 'no-git'
   | 'unknown-version'
   | 'migration-gap'
-  | 'unknown-key';
+  | 'unknown-key'
+  | 'no-changelog';
 
 /** A user-facing failure with a stable code and no stack in `--json` output. */
 export class ContentCliError extends Error {
@@ -1213,10 +1214,10 @@ export interface ContextReport {
     units?: string;
     formula?: string;
   }[];
-  readonly equations: readonly { key: string; number: string }[];
-  readonly tables: readonly { key: string; number: string }[];
-  readonly figures: readonly { key: string; number: string }[];
-  readonly diagrams: readonly { key: string; number: string }[];
+  readonly equations: readonly ManifestLessonFloat[];
+  readonly tables: readonly ManifestLessonFloat[];
+  readonly figures: readonly ManifestLessonFloat[];
+  readonly diagrams: readonly ManifestLessonFloat[];
   /** Worked-example sets: `short` is the title `[[ex-key]]` names. */
   readonly examples: readonly { key: string; number: string; short?: string }[];
   readonly knowledgeChecks: readonly { key: string; number: string; title?: string }[];
@@ -1241,7 +1242,7 @@ export interface ContextReport {
 
 // --- content migrate -------------------------------------------------
 
-/**
+/*
  * The migration guide, cut to the sections an upgrade needs: from the
  * version a course pins to the version it has installed, oldest first. The
  * guide is one newest-first file of every release; an upgrade reads one or
@@ -1441,7 +1442,7 @@ export function formatMigrateReport(report: MigrateReport): string {
 
 // --- content bindings ------------------------------------------------
 
-/**
+/*
  * What a lesson's math binds, span by span, before a build says so: each
  * glyph and the card it resolves to, how (`canonical`, `family`, `derived`,
  * `base`, `operator`, or an explicit `\explain` wrap), the wraps the bare
@@ -1787,7 +1788,7 @@ export function formatEquationReport(report: EquationReport): string {
 
 // --- content move / rename / fix: edits as a plan ----------------------
 
-/**
+/*
  * The refactors a model gets wrong most and reads most for, as deterministic
  * edits: every one is planned first (`FileEdit`s with the whole text before
  * and after), shown as a unified diff, and written only on `--write`.
@@ -1928,13 +1929,19 @@ function yamlBlock(value: unknown, indent: number): string[] {
   return [`${pad}${yamlScalar(value)}`];
 }
 
-/** A shared card's file from a page-local entry's fields, nothing invented. */
+/**
+ * A shared card's file from a page-local entry's fields, nothing invented: no
+ * body (the glossary shows the meaning; what a reader needs beyond it is the
+ * author's to write, and a placeholder would publish), and the label only
+ * when the entry has one. `domain` is the caller's pick, else the key's
+ * prefix, else `general`.
+ */
 export function sharedCardFromLocal(
   local: Record<string, unknown>,
-  options: { readonly key: string; readonly fromLesson: string },
+  options: { readonly key: string; readonly fromLesson: string; readonly domain?: string },
 ): string {
   const key = options.key;
-  const domain = key.includes('.') ? key.slice(0, key.indexOf('.')) : 'general';
+  const domain = options.domain ?? (key.includes('.') ? key.slice(0, key.indexOf('.')) : 'general');
   const front: Record<string, unknown> = {
     key,
     latex: local.latex,
@@ -1953,7 +1960,28 @@ export function sharedCardFromLocal(
     alignment: local.alignment ?? { kind: 'general', rationale: `Promoted from ${options.fromLesson}'s page-local entry.` },
     aiAssisted: true,
   };
-  return `---\n${yamlBlock(front, 0).join('\n')}\n---\n\nPromoted from \`${options.fromLesson}\`'s \`notation.local\`; the meaning above is what that page said. Extend this body with what a glossary reader needs.\n`;
+  return `---\n${yamlBlock(front, 0).join('\n')}\n---\n`;
+}
+
+/**
+ * The domain a card promoted under `key` belongs to: the key's prefix when the
+ * course already has that domain, else the one most of the lesson's shared
+ * cards have, else the course's most common, else the prefix or `general`.
+ */
+function promotedDomain(manifest: Manifest, lesson: ManifestLesson, key: string): string {
+  type Shared = Extract<Manifest['notation']['definitions'][number], { kind: 'shared' }>;
+  const shared = manifest.notation.definitions.filter((definition): definition is Shared => definition.kind === 'shared');
+  const prefix = key.includes('.') ? key.slice(0, key.indexOf('.')) : undefined;
+  if (prefix !== undefined && shared.some((definition) => definition.domain === prefix)) return prefix;
+  const mostCommon = (definitions: typeof shared): string | undefined => {
+    const counts = new Map<string, number>();
+    for (const definition of definitions) {
+      if (definition.domain) counts.set(definition.domain, (counts.get(definition.domain) ?? 0) + 1);
+    }
+    return [...counts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0];
+  };
+  const bound = new Set(lesson.notation.definitionIds);
+  return mostCommon(shared.filter((definition) => bound.has(definition.id))) ?? mostCommon(shared) ?? prefix ?? 'general';
 }
 
 function courseTextFiles(): string[] {
@@ -2014,8 +2042,23 @@ export function planMove(manifest: Manifest, lessonId: string, key: string, opti
   }
   const summary: string[] = [];
   const edits: FileEdit[] = [];
-  edits.push({ file: target, before: null, after: sharedCardFromLocal(source, { key: newKey, fromLesson: lesson.id }) });
-  summary.push(`${target}: new shared card from ${lesson.id}'s entry${newKey === key ? '' : ` (key ${key} → ${newKey})`}`);
+  const domain = promotedDomain(manifest, lesson, newKey);
+  const glyph = typeof source.latex === 'string' ? source.latex.trim() : '';
+  const owner = manifest.notation.definitions.find(
+    (definition) => definition.kind === 'shared' && definition.key !== newKey && definition.notation.trim() === glyph,
+  );
+  if (owner !== undefined) {
+    summary.push(
+      `CAUTION: ${glyph} is already shared card ${owner.key}'s — a second shared card on one glyph is a glyph-unique-in-corpus finding; ` +
+        'a reused letter stays local (rule N4). Write this only if the two cards are meant to share the glyph, and acknowledge the pair.',
+    );
+  }
+  edits.push({ file: target, before: null, after: sharedCardFromLocal(source, { key: newKey, fromLesson: lesson.id, domain }) });
+  summary.push(
+    `${target}: new shared card from ${lesson.id}'s entry${newKey === key ? '' : ` (key ${key} → ${newKey})`}, domain ${domain}` +
+      `; no body yet — add what a glossary reader needs beyond the meaning` +
+      (source.label === undefined ? '; no label in the entry — the card shows one made from the key until you add `label:`' : ''),
+  );
   const touched = new Set<string>();
   for (const other of manifest.lessons) {
     const copy = local(other);
@@ -2124,6 +2167,22 @@ export function planFix(manifest: Manifest, lessonId: string): EditPlan {
   };
 }
 
+/** `content fix` over several lessons (or every one, `--all`) as one plan: the lessons with nothing to fix are counted, not listed. */
+export function planFixMany(manifest: Manifest, lessonIds: readonly string[]): EditPlan {
+  if (lessonIds.length === 1) return planFix(manifest, lessonIds[0]!);
+  const plans = lessonIds.map((id) => planFix(manifest, id));
+  const fixing = plans.filter((plan) => plan.edits.length > 0);
+  const clean = plans.length - fixing.length;
+  return {
+    summary: [
+      ...fixing.flatMap((plan) => plan.summary),
+      ...(clean > 0 ? [`${clean} lesson(s) with nothing to fix`] : []),
+    ],
+    edits: fixing.flatMap((plan) => plan.edits),
+    next: ['pnpm content check --changed'],
+  };
+}
+
 /** The plan as a unified diff (git's), file by file, under its summary lines. */
 export function renderEditPlan(plan: EditPlan): string {
   const lines = plan.summary.map((line) => `  ${line}`);
@@ -2212,7 +2271,7 @@ export function planInitAgent(): EditPlan {
     const before = existsSync(target) ? readFileSync(target, 'utf8') : null;
     if (before === after) return;
     edits.push({ file: to, before, after });
-    summary.push(`${to}: ${before === null ? 'installed' : 'refreshed from the engine'}`);
+    summary.push(`${to}: ${before === null ? 'new' : "differs from the engine's copy"}`);
   };
   for (const file of filesUnder(join(source, 'skills'))) install(`skills/${file}`, `.claude/skills/${file}`);
   for (const file of filesUnder(join(source, 'agents'))) install(`agents/${file}`, `.claude/agents/${file}`);
@@ -2447,7 +2506,7 @@ export function contentContext(
 
 // --- content symbol --------------------------------------------------
 
-/**
+/*
  * Where a symbol is already defined, asked before an author declares it
  * again. Reads the registry the manifest holds: shared cards, page-local
  * entries (`notation.local`) and glosses (a card's `glosses:`), matched on
@@ -2456,6 +2515,7 @@ export function contentContext(
  * `v_0`), so a near miss is visible too. Read-only; every list is sorted,
  * so two runs print the same report.
  */
+/** Where a hit is defined: a shared card, a lesson's `notation.local`, or a card's gloss. */
 export type SymbolTier = 'shared' | 'local' | 'gloss';
 
 export interface SymbolHit {

package/src/compiler/content-release.ts

@@ -0,0 +1,91 @@
+/**
+ * `content release [major|minor|patch]` — cut a course content release (rule
+ * C3): `## [Unreleased]` in `content/CHANGELOG.md` becomes a dated
+ * `## [x.y.z]` heading and `content/course.config.ts` `about.version` becomes
+ * `x.y.z`, in one plan, shown as a diff and written only on `--write`, like
+ * the other edit verbs. The bump defaults to what the section's own headings
+ * imply (rule C2): `### Breaking` or `### Removed` a MAJOR, `### Added` a
+ * MINOR, anything else a PATCH.
+ *
+ * Each page's own version (rule C5) follows on the next `validate:content`,
+ * which records the release in `content/versions.json`; the release commit
+ * carries that file too.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ContentCliError, type EditPlan } from './cli';
+
+export type ReleaseBump = 'major' | 'minor' | 'patch';
+
+const CHANGELOG = 'content/CHANGELOG.md';
+const CONFIG = 'content/course.config.ts';
+
+export interface ReleaseEdit {
+  readonly from: string;
+  readonly to: string;
+  readonly bump: ReleaseBump;
+  /** True when the bump was read from the section's headings, not asked for. */
+  readonly inferred: boolean;
+  readonly changelog: string;
+  readonly config: string;
+}
+
+/** The release of these two files' text on `date` (`YYYY-MM-DD`); `null` when `[Unreleased]` has no entry. */
+export function releaseEdit(changelog: string, config: string, date: string, requested?: ReleaseBump): ReleaseEdit | null {
+  const unreleased = /^## \[Unreleased\]\r?$/m.exec(changelog);
+  if (!unreleased) throw new ContentCliError('no-changelog', `${CHANGELOG} has no "## [Unreleased]" heading.`);
+  const bodyStart = unreleased.index + unreleased[0].length;
+  const released = /^## \[\d+\.\d+\.\d+\](?: - .*?)?\r?$/m.exec(changelog.slice(bodyStart));
+  if (!released) throw new ContentCliError('no-changelog', `${CHANGELOG} has no released "## [x.y.z]" heading below "## [Unreleased]".`);
+  const bodyEnd = bodyStart + released.index;
+  const body = changelog.slice(bodyStart, bodyEnd);
+  if (!/^-\s+/m.test(body)) return null;
+
+  const version = /(about:\s*\{[\s\S]*?\bversion:\s*['"])(\d+)\.(\d+)\.(\d+)(['"])/.exec(config);
+  if (!version) throw new ContentCliError('unknown-version', `No about.version "x.y.z" in ${CONFIG}.`);
+  const [major, minor, patch] = version.slice(2, 5).map(Number) as [number, number, number];
+  const implied: ReleaseBump = /^### (Breaking|Removed)\s*$/m.test(body) ? 'major' : /^### Added\s*$/m.test(body) ? 'minor' : 'patch';
+  const bump = requested ?? implied;
+  const to = bump === 'major' ? `${major + 1}.0.0` : bump === 'minor' ? `${major}.${minor + 1}.0` : `${major}.${minor}.${patch + 1}`;
+  return {
+    from: `${major}.${minor}.${patch}`,
+    to,
+    bump,
+    inferred: requested === undefined,
+    changelog: `${changelog.slice(0, bodyStart)}\n\n## [${to}] - ${date}${body}${changelog.slice(bodyEnd)}`,
+    config: config.replace(version[0], `${version[1]}${to}${version[5]}`),
+  };
+}
+
+/** The release as an edit plan over the course in the working directory. */
+/** Today where the release is cut, `YYYY-MM-DD`: a release at 9 pm is dated that day, not the next one in UTC. */
+function localDate(now = new Date()): string {
+  return [now.getFullYear(), now.getMonth() + 1, now.getDate()].map((n, i) => String(n).padStart(i === 0 ? 4 : 2, '0')).join('-');
+}
+
+export function planContentRelease(requested?: string, date = localDate()): EditPlan {
+  if (requested !== undefined && requested !== 'major' && requested !== 'minor' && requested !== 'patch') {
+    throw new ContentCliError('usage', `content release takes major, minor or patch; got ${requested}.`);
+  }
+  for (const file of [CHANGELOG, CONFIG]) {
+    if (!existsSync(join(process.cwd(), file))) throw new ContentCliError('no-changelog', `No ${file} in this course.`);
+  }
+  const changelog = readFileSync(join(process.cwd(), CHANGELOG), 'utf8');
+  const config = readFileSync(join(process.cwd(), CONFIG), 'utf8');
+  const edit = releaseEdit(changelog, config, date, requested);
+  if (edit === null) {
+    return { summary: ['## [Unreleased] has no entries: nothing to release'], edits: [], next: [] };
+  }
+  return {
+    summary: [
+      `about.version ${edit.from} → ${edit.to} (${edit.bump}${edit.inferred ? ", from the section's headings" : ''})`,
+      `${CHANGELOG}: ## [Unreleased] → ## [${edit.to}] - ${date}, a fresh ## [Unreleased] above it`,
+    ],
+    edits: [
+      { file: CHANGELOG, before: changelog, after: edit.changelog },
+      { file: CONFIG, before: config, after: edit.config },
+    ],
+    next: ['pnpm validate:content (records the release in content/versions.json)', 'commit the changelog, the config and content/versions.json together'],
+  };
+}

package/src/compiler/manifest.ts

@@ -183,6 +183,7 @@ import {
   type KnowledgeVersionDiagnostic,
 } from './knowledge-version';
 import {
+  deckStaleDiagnostics,
   nextPageVersions,
   PAGE_VERSIONS_FILE,
   pageSourceDigest,
@@ -2329,6 +2330,37 @@ export async function compileManifest(
       : { changelogHref: courseConfig.about.changelogHref }),
   };
 
+  const lessonsWithSince = lessons.map((lesson) => ({ ...lesson, since: sinceOfPage(lesson.slug) }));
+  const decksWithSince = deckModel.decks.map((deck) => {
+    const page = pageInputById.get(deck.pageId);
+    return {
+      ...deck,
+      since: sinceOfPage(deck.slug),
+      notation: lessonNotationBundle(
+        bundlesByLesson.get(deck.pageId),
+        definitionsById,
+        page === undefined ? [] : lessonNotationResolution(page, definitionsById, availableDefinitionIds),
+        cardsByKey,
+        // A deck shows its lessons' symbols: the derived cards (rule N23)
+        // its chapters' bodies and checks use ship with it, as its bundle
+        // holds the chapters' entries.
+        [
+          ...(indexGate.derivedByLesson.get(deck.pageId) ?? []),
+          ...(page?.scopeLessonIds ?? []).flatMap((lessonId) => [
+            ...(indexGate.derivedByLesson.get(lessonId) ?? []),
+            ...(assessmentDerived.get(lessonId)?.values() ?? []),
+          ]),
+        ].filter((use, index, all) => all.findIndex((other) => other.key === use.key) === index),
+      ),
+    };
+  });
+  // Rule D11: a lesson's own deck whose chapter changed after the deck did.
+  // `since` is only known this late, so this runs after `mathIssues` (D1–D10's
+  // frame codes) is already waived; pushed in after, it joins `diagnostics.math`
+  // the same way, just outside the waiver pass — not a per-place finding to waive.
+  const chapterSince = new Map(lessonsWithSince.map((lesson) => [lesson.slug, lesson.since] as const));
+  mathIssues.push(...deckStaleDiagnostics(decksWithSince, chapterSince));
+
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
     lessonExports: normalizeLessonExports(courseConfig),
@@ -2341,29 +2373,7 @@ export async function compileManifest(
     readingMemory: normalizeReadingMemory(courseConfig),
     appearance: normalizeAppearance(courseConfig),
     deck: deckSettings,
-    decks: deckModel.decks.map((deck) => {
-      const page = pageInputById.get(deck.pageId);
-      return {
-        ...deck,
-        since: sinceOfPage(deck.slug),
-        notation: lessonNotationBundle(
-          bundlesByLesson.get(deck.pageId),
-          definitionsById,
-          page === undefined ? [] : lessonNotationResolution(page, definitionsById, availableDefinitionIds),
-          cardsByKey,
-          // A deck shows its lessons' symbols: the derived cards (rule N23)
-          // its chapters' bodies and checks use ship with it, as its bundle
-          // holds the chapters' entries.
-          [
-            ...(indexGate.derivedByLesson.get(deck.pageId) ?? []),
-            ...(page?.scopeLessonIds ?? []).flatMap((lessonId) => [
-              ...(indexGate.derivedByLesson.get(lessonId) ?? []),
-              ...(assessmentDerived.get(lessonId)?.values() ?? []),
-            ]),
-          ].filter((use, index, all) => all.findIndex((other) => other.key === use.key) === index),
-        ),
-      };
-    }),
+    decks: decksWithSince,
     about,
     notation: {
       definitions: registry.definitions,
@@ -2382,7 +2392,7 @@ export async function compileManifest(
         ? { ...part, overview: { ...overview, since: sinceOfPage(`${part.dir}/index`) } }
         : part,
     ),
-    lessons: lessons.map((lesson) => ({ ...lesson, since: sinceOfPage(lesson.slug) })),
+    lessons: lessonsWithSince,
     pageVersions,
     pages,
     prereqEdges,

package/src/compiler/page-versions.ts

@@ -357,3 +357,45 @@ export function syncPageVersions(
   writeFileSync(path, expected);
   return { path, stale: true, written: true, changed };
 }
+
+/**
+ * Rule D11, shaped like a `MathGateDiagnostic` (`src/reference/gate-math.ts`)
+ * so it can join `diagnostics.math` beside D1–D10's frame codes, without
+ * this module importing from `src/reference/`.
+ */
+export interface DeckStaleDiagnostic {
+  readonly context: 'structure';
+  readonly severity: 'info';
+  readonly code: 'deck-stale';
+  readonly file: string;
+  readonly message: string;
+}
+
+/**
+ * Rule D11: nothing else would notice a lesson's chapter and deck drifting
+ * apart, since two files keep each edition readable at the cost of that one
+ * check. Flags a deck whose chapter's `since` (rule C5) is newer than the
+ * deck's own. A part's deck has no one chapter to compare against, so a
+ * deck without a `chapter` (its `BuiltDeck.chapter`) is skipped.
+ */
+export function deckStaleDiagnostics(
+  decks: readonly { readonly file: string; readonly chapter?: string; readonly since: string | null }[],
+  chapterSince: ReadonlyMap<string, string | null>,
+): DeckStaleDiagnostic[] {
+  const out: DeckStaleDiagnostic[] = [];
+  for (const deck of decks) {
+    if (deck.chapter === undefined) continue;
+    const chapterVersion = chapterSince.get(deck.chapter);
+    if (chapterVersion === undefined) continue;
+    if (compareKnowledgeVersions(chapterVersion, deck.since) <= 0) continue;
+    const chapterChange = chapterVersion === null ? 'has unreleased changes' : `changed in version ${chapterVersion}`;
+    out.push({
+      context: 'structure',
+      severity: 'info',
+      code: 'deck-stale',
+      file: deck.file,
+      message: `The chapter ${chapterChange}; this deck is still from version ${deck.since}.`,
+    });
+  }
+  return out;
+}

package/src/compiler/validate-content.ts

@@ -116,8 +116,11 @@ export async function runValidateContent(courseConfig: CourseConfig): Promise<nu
 
   const consistencyWarnings = consistency.filter((diagnostic) => diagnostic.severity === 'warning');
   if (consistencyWarnings.length > 0) {
+    // The console gets one digest line; the log records each finding at
+    // WARNING (below), so its counts agree with `content status`, and the
+    // digest at INFO, so it is not counted as one more warning.
     console.warn(
-      log.warning(
+      log.info(
         'consistency',
         `[consistency] ${consistencyWarnings.length} Tier-3 finding(s): ` +
           Object.entries(consistencyCounts(consistencyWarnings))
@@ -131,7 +134,7 @@ export async function runValidateContent(courseConfig: CourseConfig): Promise<nu
   // Every severity-`info` diagnostic goes to the log only.
   log.infoDiagnostics(manifest.diagnostics);
   for (const diagnostic of consistencyWarnings) {
-    log.info('consistency', `[${diagnostic.code}] ${diagnostic.message}`);
+    log.warning('consistency', `[${diagnostic.code}] ${diagnostic.message}`);
   }
 
   const reports = syncResolutionReports(manifest);

package/src/reference/consistency.ts

@@ -308,7 +308,9 @@ function checkNotationSourceLocator(
  * it is one meaning, so it belongs in `content/notation/<key>.md` (every
  * `[[key]]` keeps working), or it is two, so one needs another key. A deck
  * inherits its chapters' entries rather than redeclaring them, so decks never
- * count.
+ * count. When a shared card already owns the glyph, the entry is a reused
+ * letter (N4) and promoting it would put two shared cards on one glyph, so
+ * the message says that instead of "move one copy".
  */
 function checkDefinitionRepeated(
   input: ConsistencyInput,
@@ -327,6 +329,10 @@ function checkDefinitionRepeated(
       byKey.set(definition.key, list);
     }
   }
+  const sharedByGlyph = new Map<string, string>();
+  for (const definition of input.notationInput.sharedDefinitions) {
+    if (!sharedByGlyph.has(definition.notation.trim())) sharedByGlyph.set(definition.notation.trim(), definition.key);
+  }
   for (const [key, copies] of [...byKey].sort(([a], [b]) => a.localeCompare(b))) {
     if (copies.length < 2) continue;
     if (input.lintIgnore.matches('definition-repeated', key)) continue;
@@ -335,6 +341,11 @@ function checkDefinitionRepeated(
       copies.some((copy) => JSON.stringify(copy.definition[field] ?? null) !== JSON.stringify(first.definition[field] ?? null)),
     );
     const lessons = copies.map((copy) => copy.lessonId).sort();
+    const owner = sharedByGlyph.get(first.definition.notation.trim());
+    const advice =
+      owner !== undefined && owner !== key
+        ? ` — its glyph is already shared card ${owner}'s, so it is a reused letter (rule N4) and promoting it would put two shared cards on one glyph (glyph-unique-in-corpus): keep the copies local and acknowledge them in lint-ignore.yml ("definition-repeated:${key} — <why>"), or, if they are two meanings, give one another key`
+        : ` — move one copy to content/notation/${key}.md and delete the others: every [[${key}]] and \\explain{${key}} keeps working; if they are two meanings, give one another key`;
     out.push({
       code: 'definition-repeated',
       severity: 'warning',
@@ -347,7 +358,7 @@ function checkDefinitionRepeated(
         (differing.length === 0
           ? 'the copies agree'
           : `the copies differ in ${differing.join(', ')}`) +
-        ` — move one copy to content/notation/${key}.md and delete the others: every [[${key}]] and \\explain{${key}} keeps working; if they are two meanings, give one another key`,
+        advice,
     });
   }
 }

package/src/reference/diagram-fit.ts

@@ -42,12 +42,26 @@ export function diagramWidthLimit(
   return typeof columnWidth === 'number' ? columnWidth : DEFAULT_COLUMN_WIDTH;
 }
 
-/** What to tell the author about one diagram wider than its limit. */
+/**
+ * What to tell the author about one diagram wider than its limit. The
+ * competency graph is `<CurriculumMap>`'s, whose nodes the author does not
+ * write, so its advice names the map's own props.
+ */
 export function diagramTooWideMessage(id: string, width: number, limit: number): string {
-  return (
+  const head =
     `Diagram "${id}" lays out ${Math.round(width)}px wide, wider than the ${limit}px it may ` +
-    `take (rule V8), so a reader has to scroll it or widen it to see it whole. Try ` +
-    `direction="TB", a shorter label, or a narrower node \`width\` (its label wraps inside ` +
+    `take (rule V8), so a reader has to scroll it or widen it to see it whole. `;
+  if (id.startsWith('competency-graph')) {
+    return (
+      head +
+      `It is <CurriculumMap>'s competency graph: try graph="per-part" (one graph per part) and ` +
+      `direction="LR" or "TB" on the map; set warnAboveWidth={false} there when no layout fits ` +
+      `and the graph is meant to scroll.`
+    );
+  }
+  return (
+    head +
+    `Try direction="TB", a shorter label, or a narrower node \`width\` (its label wraps inside ` +
     `it); set warnAboveWidth={false} only when the diagram is meant to scroll.`
   );
 }

package/src/rules/catalog.ts

@@ -1366,6 +1366,23 @@ const RULES: readonly RuleEntry[] = [
       'The title frame (the lesson, the course, its authors and version) and the closing frame (the outcomes of the competencies the lesson teaches, `deck.outcomesFrame`) are generated: do not write them. With `deck.outcomesFrame` off, end on a `###` frame that says what the student can now do.',
     checks: [],
   },
+  {
+    kind: 'rule',
+    id: 'D11',
+    editions: 'deck',
+    short: 'A deck is flagged when its chapter changed after it did',
+    title: 'A deck is flagged when its chapter changed, by rule C5’s version, after the deck itself last did.',
+    elements: ['slide', 'changelog'],
+    doc: 'deck.md#d11',
+    summary:
+      'No authoring action by itself: two files mean the chapter and the deck can drift apart with nothing to notice it. `deck-stale` is an info diagnostic naming a lesson’s own deck whose chapter’s rule C5 version is newer than the deck’s; read the chapter’s change and judge whether the deck needs it too. Scoped to a lesson’s own deck — a part’s deck covers more than one chapter, so it has none to compare against.',
+    checks: [
+      check('deck-stale', 'info', false, {
+        module: 'src/compiler/page-versions.ts',
+        fn: 'deckStaleDiagnostics',
+      }),
+    ],
+  },
 ];
 
 /**

package/src/rules/in-effect.ts

@@ -193,7 +193,8 @@ export function renderRulesInEffect(input: RulesInEffectInput, filter: RulesFilt
         ]
       : []),
     'Generated by `pnpm validate:content` (and `pnpm content rules`) from the rule',
-    'catalog and `rules` / `courseRules` in `course.settings.json`. Do not edit. Read this before',
+    "catalog and the course's `rules` / `courseRules` (`course.settings.json`, or",
+    '`course.config.ts`). Do not edit. Read this before',
     'drafting, and open a rule page only when it is listed here and you need the',
     'example: a rule absent from this page is either off for this course or does',
     'not exist, and is neither applied nor flagged in review.',
@@ -210,8 +211,8 @@ export function renderRulesInEffect(input: RulesInEffectInput, filter: RulesFilt
         : ''),
     '',
     'A line is `ID · enforcement · codes — what to do (settings in effect) → full',
-    'text`. **course**: this course wrote the rule in `courseRules` in',
-    '`course.settings.json`, where it can be edited; the `X` area is reserved for',
+    'text`. **course**: this course wrote the rule in `courseRules` (in',
+    '`course.settings.json` or `course.config.ts`), where it can be edited; the `X` area is reserved for',
     'them. **script**: the build reports every violation under those codes.',
     '**partial**: the build reports the codes; the rest is on you. **guide**: nothing',
     'runs; it is on you. **locked**: script, and the course cannot turn it off.',
@@ -245,7 +246,7 @@ export function renderRulesInEffect(input: RulesInEffectInput, filter: RulesFilt
   lines.push(
     offHere.length === 0
       ? '- Nothing — every rule is on.'
-      : `- ${offHere.join(', ')} — turned off in \`course.settings.json\` (\`rules\`, or \`courseRules\` for an \`X\` rule). Do not apply them; do not flag them in review.`,
+      : `- ${offHere.join(', ')} — turned off in the course's \`rules\` (or \`courseRules\` for an \`X\` rule), in \`course.settings.json\` or \`course.config.ts\`. Do not apply them; do not flag them in review.`,
   );
 
   lines.push('', '## Locked', '');