explico 0.11.1 → 0.13.0

package/src/components/starlight/section-summary.ts

@@ -97,6 +97,13 @@ export function describeHiddenContent(
 const CONTAINERS =
   '.keyed-figure, .keyed-table, .diagram, .memo-block, .compact-examples, .compact-example, .assessment-shell, .short-note';
 
+/**
+ * A short note's prose belongs to the paragraph it opens in, but a numbered
+ * float or equation inside it is numbered like any other, and hidden with
+ * the section: those count, and a float is named, as in a `<Fold>`.
+ */
+const FLOAT_CONTAINERS = CONTAINERS.replace(', .short-note', '');
+
 /** Whether any ancestor of `element` strictly between it and `root` matches `selector`. */
 function hasAncestorWithin(element: Element, root: Element, selector: string): boolean {
   for (
@@ -127,25 +134,26 @@ export function collectHiddenContent(
   headings: string,
   { nameFloats = true }: { readonly nameFloats?: boolean } = {},
 ): HiddenContent {
-  const outside = (selector: string, alsoExclude = '') =>
+  const outside = (selector: string, alsoExclude = '', containers = CONTAINERS) =>
     Array.from(body.querySelectorAll(selector)).filter(
       (element) =>
-        !hasAncestorWithin(element, body, CONTAINERS) &&
+        !hasAncestorWithin(element, body, containers) &&
         !(alsoExclude && hasAncestorWithin(element, body, alsoExclude)),
     );
+  const numbered = (selector: string) => outside(selector, '', FLOAT_CONTAINERS);
   const itemsIn = (container: string, item: string) =>
     outside(container).reduce(
       (total, element) => total + element.querySelectorAll(item).length,
       0,
     );
   const named = nameFloats
-    ? outside('.keyed-figure, .keyed-table, .diagram').flatMap((element) => {
+    ? numbered('.keyed-figure, .keyed-table, .diagram').flatMap((element) => {
         const float = floatOf(element);
         return float?.short ? [float] : [];
       })
     : [];
   const unnamed = (selector: string) =>
-    outside(selector).filter(
+    numbered(selector).filter(
       (element) => !named.some((float) => float.anchorId === element.id),
     ).length;
 
@@ -161,7 +169,7 @@ export function collectHiddenContent(
     ).length,
     // A loose list's `<li><p>` is part of the list, not a paragraph of its own.
     paragraphs: outside('p', 'ul, ol').length,
-    equations: outside('.katex-display').length,
+    equations: numbered('.katex-display').length,
     figures: unnamed('.keyed-figure'),
     // Keyed tables, plus any raw Markdown table (warned about, but possible).
     tables: unnamed('.keyed-table') + outside('table').length,

package/src/components/table/Table.astro

@@ -49,7 +49,7 @@ if (short !== undefined && (typeof short !== 'string' || !short.trim())) {
 }
 if (!number || !anchorId) {
   throw new Error(
-    'Table is missing its computed `number`/`anchorId` — this page must run remark-notation with a `tables` cross-page table configured (see astro.config.mjs).',
+    `Table is missing its computed \`number\`/\`anchorId\`. remark-notation numbers a <Table> only on a lesson page, at its top level or in a <Memo>, <ShortNote> or <Fold>: elsewhere (a worked example) write a plain Markdown table, and on a page that is not a chapter (rule S10) link the chapter's table. At a lesson's top level, this page is not running remark-notation with the manifest's \`tables\` (see astro.config.mjs).`,
   );
 }
 ---
@@ -68,19 +68,6 @@ if (!number || !anchorId) {
       href={`#${anchorId}`}
       aria-label={`Table ${number}`}>Table {number}</a
     >
-    <a
-      class="float-caption__anchor"
-      href={`#${anchorId}`}
-      aria-label={`Copy the link to Table ${number}`}
-      title="Copy link"
-      data-copy-link={`Table ${number}`}
-    >
-      <svg aria-hidden="true" width="16" height="16" viewBox="0 0 24 24" fill="currentColor"
-        ><path
-          d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 1 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 0 0-1.42-1.42m8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 1 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0l3.88-3.89a4.49 4.49 0 0 0 0-6.33M8.83 15.17a1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.92-4.92a1 1 0 1 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42"
-        ></path></svg
-      >
-    </a>
     {short && <b class="float-caption__title">{captionTitle(short)}</b>}{short && ' '}<span
       class="keyed-table__caption-text float-caption__text">{caption}</span
     >
@@ -201,6 +188,8 @@ if (!number || !anchorId) {
 </style>
 
 <script>
+  import { tableTruncation } from './table-truncation';
+
   /**
    * Table row show/hide pagination
    * (docs/plans/collapsible-disclosure.md Part 5) — three states per table,
@@ -274,12 +263,15 @@ if (!number || !anchorId) {
     if (totalRows === 0) return;
 
     // Long enough to also need truncation, on top of the minimize toggle
-    // every table gets below: more rows than the course's
-    // `disclosure.tables.truncateAfter`. A truncated table shows up to that
-    // many rows, half from each end.
-    const truncateAfter = Number(figure.dataset.truncateAfter) || 6;
-    const keepEachEnd = Math.floor(truncateAfter / 2);
-    const paginated = totalRows > truncateAfter;
+    // every table gets below (`tableTruncation`): more rows than the
+    // course's `disclosure.tables.truncateAfter`, and at least two to hide.
+    // A truncated table shows up to that many rows, half from each end.
+    const truncation = tableTruncation(
+      totalRows,
+      Number(figure.dataset.truncateAfter) || 6,
+    );
+    const paginated = truncation !== undefined;
+    const keepEachEnd = truncation?.keepEachEnd ?? 0;
 
     const caption = figure.querySelector<HTMLElement>(
       ':scope > .keyed-table__caption',
@@ -295,7 +287,7 @@ if (!number || !anchorId) {
     let minimizeAll: HTMLButtonElement | null = null;
 
     if (paginated) {
-      const hiddenCount = totalRows - keepEachEnd * 2;
+      const hiddenCount = truncation.hidden;
       const headerCells = table.tHead?.rows[0]?.cells ?? rows[0].cells;
       const colCount =
         Array.from(headerCells).reduce(
@@ -321,7 +313,7 @@ if (!number || !anchorId) {
       const moreLabel = document.createElement('span');
       moreLabel.className = 'keyed-table__more-label';
       moreLabel.textContent =
-        hiddenCount === 1 ? '… 1 more row …' : `… ${hiddenCount} more rows …`;
+        `… ${hiddenCount} more rows …`;
       moreCell.append(moreLabel);
       moreRow.append(moreCell);
       tbody.insertBefore(moreRow, rows[keepEachEnd]);

package/src/components/table/table-truncation.ts

@@ -0,0 +1,15 @@
+/**
+ * How a long table starts (`disclosure.tables.truncateAfter`): the rows kept
+ * at each end and how many the "… N more rows …" line stands for, or
+ * `undefined` when the table shows whole — it has no more rows than the
+ * setting, or truncating it would hide a single row, which the line is as
+ * tall as and would cost the reader a click to see.
+ */
+export function tableTruncation(
+  totalRows: number,
+  truncateAfter: number,
+): { readonly keepEachEnd: number; readonly hidden: number } | undefined {
+  const keepEachEnd = Math.floor(truncateAfter / 2);
+  const hidden = totalRows - keepEachEnd * 2;
+  return totalRows > truncateAfter && hidden >= 2 ? { keepEachEnd, hidden } : undefined;
+}

package/src/content-config.ts

@@ -1,9 +1,19 @@
 import { defineCollection } from 'astro:content';
 import { glob } from 'astro/loaders';
-import { z } from 'astro/zod';
 import { docsSchema } from '@astrojs/starlight/schema';
-import { isSubstantiveMeaning } from './reference/prose';
-import { glossKeySegment } from './reference/gloss';
+import {
+  abbreviationSchema,
+  assessmentSchema,
+  competencySchema,
+  lessonFrontmatterSchema,
+  notationSchema,
+  sourceSchema,
+  trackSchema,
+} from './compiler/content-schemas';
+
+// The schemas live in `compiler/content-schemas.ts`, where the manifest walk
+// checks every record against them too (`validate:content` rejects what this
+// build would). This file only wires them to Astro's loaders.
 
 // Phase F: content lives in the top-level `content/` folder, not `src/content/`.
 // `docsLoader()` is hard-wired to `<srcDir>/content/docs`, so the `docs`
@@ -14,186 +24,9 @@ const docsGlob = glob({
   pattern: '**/[^_]*.{md,mdx}',
 });
 
-const editorialStatus = z.enum(['draft', 'in-review', 'reviewed']);
-const id = z.string().regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/);
-
-/**
- * Notation `meaning` / `summary`: plain prose (no `$`, `\`, backticks), and —
- * the C1b safeguard — substantive, not a placeholder. A short or blocklisted
- * phrase fails the build so a local symbol cannot get a glossary-style panel
- * for a throwaway definition.
- */
-const notationProse = z
-  .string()
-  .min(1)
-  .refine((value) => !/[\\$`]/.test(value), {
-    message:
-      'Notation meaning/summary must be plain prose; render the symbol or formula in its dedicated field.',
-  })
-  .refine(isSubstantiveMeaning, {
-    message:
-      'Notation meaning must be substantive prose (at least four words, not a placeholder).',
-  });
-
-const notationAlignment = z.discriminatedUnion('kind', [
-  z.object({
-    kind: z.literal('competency'),
-    introducedByCompetency: id,
-    introducedInLesson: id,
-  }),
-  z.object({
-    kind: z.literal('general'),
-    rationale: z.string().min(1),
-  }),
-]);
-const notationAlignmentDefault = notationAlignment.default({
-  kind: 'general',
-  rationale: 'General notation.',
-});
-
-/**
- * A citation on a notation definition: a bare id (locator pending, see D6/g) or
- * `{id, locator}` — a per-claim locator verified against the cited text.
- */
-const notationSource = z.union([
-  id,
-  z.object({ id, locator: z.string().min(1) }),
-]);
-
-/**
- * One notation entry shape (Phase C1b), shared by page-local `notation.local`
- * and the standalone `notation` collection.
- *
- * Authored: `key`, `latex`, `meaning`, optional `formula`, optional `units`
- * (or `dimensionless: true`), `seeAlso`, `sources` (`{id, locator}`),
- * optional `alignment` (defaults to `general`), optional `label`.
- *
- * The display label defaults to the humanized `key` (see `reference/label.ts`);
- * `label` is authored only where that reads wrong. The `notationProse`
- * refinement rejects an under-specified `meaning`.
- */
-/**
- * A **gloss** on a notation card: a symbol the card's own `formula` needs in
- * order to be written down, carrying a name and nothing else (D15).
- *
- * A gloss is deliberately cheaper than a card. It has no description, no
- * sources, no curriculum alignment, no review state, and no glossary card of
- * its own; it is not a node in the curriculum graph and never creates a
- * reference edge. Its key is derived, not authored — `<card key>.<slug(name)>`
- * — so a gloss is scoped to the card that declares it and two cards may each
- * gloss `T`. Because a formula spells LaTeX and never a key, **promoting** a
- * gloss is exactly: delete this line, add `content/notation/<key>.md`.
- *
- * `units` is optional and stays a bare unit string: "T — time" is ambiguous in
- * a corpus with several `T`s, "T — time, years from valuation" is not, and it
- * is still one line. Prose belongs on a card.
- */
-const notationGloss = z.object({
-  latex: z.string().min(1),
-  name: z
-    .string()
-    .min(1)
-    .refine((value) => glossKeySegment(value) !== undefined, {
-      message:
-        'A gloss name must contain letters or digits so a key can be derived from it.',
-    })
-    // The symbol goes in `latex`, the name names it. A name carrying LaTeX is
-    // the one unambiguous way to get this field wrong, so it blocks; a name
-    // that is merely long is a Tier-3 `gloss-name-shape` warning instead,
-    // because a complicated quantity may honestly need several words.
-    .refine((value) => !/[\\$`\n]/.test(value), {
-      message:
-        'A gloss name is a plain noun phrase; put the symbol in `latex`, not in the name.',
-    }),
-  units: z.string().min(1).optional(),
-});
-
-const notationEntryShape = z.object({
-  key: id,
-  latex: z.string().min(1),
-  meaning: notationProse,
-  formula: z.string().min(1).optional(),
-  units: z.string().min(1).optional(),
-  dimensionless: z.literal(true).optional(),
-  seeAlso: z.array(id).default([]),
-  sources: z.array(notationSource).default([]),
-  alignment: notationAlignmentDefault,
-  label: z.string().min(1).optional(),
-  glosses: z.array(notationGloss).default([]),
-});
-
-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: [], 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
- *            authored): `lessonId` (doc slug), `requires` (direct competency-DAG
- *            prerequisites of `teaches`, minus `teaches`), `sources` (`[@…]`
- *            occurrences), `assessments` (colocated `<lesson>.checks.yml`),
- *            `sidebar` order (track order).
- * 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({
-    extend: z.object({
-      editorialStatus: editorialStatus.default('draft'),
-      teaches: z.array(id).default([]),
-      assumptions: z.array(z.string().min(1)).default([]),
-      studyMinutes: studyMinutes.optional(),
-      notation: lessonNotation,
-    }),
-  }),
+  schema: docsSchema({ extend: lessonFrontmatterSchema }),
 });
 
 const competencies = defineCollection({
@@ -201,160 +34,35 @@ const competencies = defineCollection({
     pattern: '**/*.json',
     base: './content/competencies',
   }),
-  schema: z.object({
-    id,
-    title: z.string().min(1),
-    domain: id,
-    facet: z.enum([
-      'knowledge',
-      'calculation',
-      'interpretation',
-      'convention',
-      'risk',
-    ]),
-    outcome: z.string().min(1),
-    prerequisites: z.array(id).default([]),
-    evidence: z.object({
-      minimumIndependentItems: z.number().int().min(1),
-      requiresTransfer: z.boolean(),
-      requiresUnassistedPass: z.boolean(),
-    }),
-    misconceptions: z.array(z.string().min(1)).default([]),
-    editorialStatus,
-  }),
-});
-
-const assessmentItemBase = z.object({
-  id,
-  competencyId: id,
-  evidenceKind: z.enum(['direct', 'transfer']),
-  prompt: z.string().min(1),
-  explanation: z.string().min(1),
+  schema: competencySchema,
 });
 
-/**
- * `AssessmentSet.astro` renders the numbered heading itself — `<h2>Knowledge
- * check {number} — {title}</h2>` — so `title` must be just the topic. A title
- * that repeats the "Knowledge check" label duplicates it on every page that
- * uses `AssessmentSet` (the standalone `AssessmentRunner` heading fallback
- * reads fine either way, so this only bites the common path).
- */
-const assessmentTitle = z
-  .string()
-  .min(1)
-  .refine((value) => !/^knowledge check\b/i.test(value), {
-    message:
-      'Assessment title must not start with "Knowledge check" — AssessmentSet already renders "Knowledge check {number} — {title}", so a title with the same prefix duplicates it. Use just the topic, e.g. "AIC and KL risk".',
-  });
-
 const assessments = defineCollection({
   loader: glob({
     pattern: '**/*.json',
     base: './content/assessments',
   }),
-  schema: z.object({
-    id,
-    title: assessmentTitle,
-    editorialStatus,
-    items: z
-      .array(
-        z.discriminatedUnion('type', [
-          assessmentItemBase.extend({
-            type: z.literal('numeric'),
-            answer: z.object({
-              value: z.number(),
-              tolerance: z.number().positive(),
-            }),
-          }),
-          assessmentItemBase.extend({
-            type: z.literal('single-choice'),
-            options: z
-              .array(
-                z.object({
-                  id,
-                  label: z.string().min(1),
-                }),
-              )
-              .min(2),
-            correctOptionId: id,
-          }),
-        ]),
-      )
-      .min(1),
-  }),
+  schema: assessmentSchema,
 });
 
 const tracks = defineCollection({
   loader: glob({ pattern: '**/*.json', base: './content/tracks' }),
-  schema: z.object({
-    id,
-    title: z.string().min(1),
-    description: z.string().min(1),
-    audience: z.string().min(1),
-    entryAssumptions: z.array(z.string().min(1)),
-    lessons: z.array(id).min(1),
-    editorialStatus,
-  }),
+  schema: trackSchema,
 });
 
 const sources = defineCollection({
   loader: glob({ pattern: '**/*.json', base: './content/sources' }),
-  schema: z.object({
-    id,
-    type: z.enum([
-      'primary',
-      'official-guidance',
-      'paper',
-      'book',
-      'secondary',
-    ]),
-    title: z.string().min(1),
-    authors: z.array(z.string().min(1)).optional(),
-    organization: z.string().min(1).optional(),
-    edition: z.string().optional(),
-    publisher: z.string().optional(),
-    year: z.number().int().optional(),
-    isbn: z.string().optional(),
-    url: z.url().optional(),
-    locator: z.string().optional(),
-    accessed: z.coerce.date().optional(),
-    licenseNotes: z.string().optional(),
-    editorialStatus,
-  }),
+  schema: sourceSchema,
 });
 
-/**
- * Standalone notation collection — the one `notationEntry` shape plus the
- * shared-only extras: `domain`, `aliases`, its own `editorialStatus`, and a
- * Markdown body.
- */
 const notation = defineCollection({
   loader: glob({ pattern: '**/*.md', base: './content/notation' }),
-  schema: notationEntryShape.extend({
-    domain: id,
-    aliases: z.array(z.string().min(1)).default([]),
-    editorialStatus,
-    aiAssisted: z.boolean().default(false),
-  }),
+  schema: notationSchema,
 });
 
-/**
- * Abbreviations table (rule N14) — deliberately a lighter tier than a
- * `notation` card: just a name resolution, no `formula`, `units`, or
- * curriculum `alignment`. `abbr` is the canonical written form (`OLS`);
- * `aliases` are other written forms of the same abbreviation that should
- * resolve the same way (`w.r.t.` might alias `wrt`).
- */
 const abbreviations = defineCollection({
   loader: glob({ pattern: '**/*.md', base: './content/abbreviations' }),
-  schema: z.object({
-    key: id,
-    abbr: z.string().min(1),
-    expansion: notationProse,
-    aliases: z.array(z.string().min(1)).default([]),
-    domain: id.optional(),
-    editorialStatus: editorialStatus.default('draft'),
-  }),
+  schema: abbreviationSchema,
 });
 
 export const collections = {

package/src/curriculum/validation.ts

@@ -1,3 +1,5 @@
+import { citationsInLinks, citedIds, withoutLinkCitations } from '../reference/citation-format.mjs';
+
 export interface CompetencyDefinition {
   readonly id: string;
   readonly title: string;
@@ -11,7 +13,6 @@ export interface CompetencyDefinition {
 
 export interface LessonDefinition {
   readonly id: string;
-  readonly status: 'draft' | 'in-review' | 'reviewed';
   readonly requires: readonly string[];
   readonly teaches: readonly string[];
   readonly assessments: readonly string[];
@@ -25,8 +26,17 @@ interface AssessmentItemBase {
   readonly id: string;
   readonly competencyId: string;
   readonly evidenceKind: 'direct' | 'transfer';
+  readonly prompt?: string;
+  readonly explanation?: string;
 }
 
+/**
+ * A `[[…]]` reference or an `[@…]` citation in a check's text. A knowledge
+ * check renders its prompt, explanation and option labels as text and math
+ * only, so either would reach the reader exactly as written.
+ */
+const CHECK_TEXT_REFERENCE = /\[\[[^\]\n]*\]\]|\[@[^\]\n]*\]/;
+
 export interface NumericAssessmentItem extends AssessmentItemBase {
   readonly type: 'numeric';
   readonly answer: { readonly value: number; readonly tolerance: number };
@@ -45,7 +55,6 @@ export interface AssessmentDefinition {
 
 export interface SourceDefinition {
   readonly id: string;
-  readonly editorialStatus: 'draft' | 'in-review' | 'reviewed';
 }
 
 export interface TrackDefinition {
@@ -73,9 +82,23 @@ export interface CurriculumIssue {
     | 'track-order'
     | 'assessment-coverage'
     | 'invalid-assessment'
-    | 'review-state'
-    | 'teaches-support';
+    | 'missing-assumptions'
+    | 'teaches-support'
+    | 'retired-key'
+    | 'content-schema'
+    | 'part-empty'
+    | 'lesson-outside-parts'
+    | 'unsupported-key'
+    | 'ignored-key'
+    | 'markup-in-prop'
+    | 'citation-in-link';
   readonly message: string;
+  /**
+   * The content file the issue is about, when it is about one file rather
+   * than the graph (`retired-key`, `content-schema`), and the 1-based line in it.
+   */
+  readonly file?: string;
+  readonly line?: number;
   /**
    * `error` (default) blocks the build; `warning` is reported but non-blocking.
    * New checks enter as warnings and are promoted once they run clean on real
@@ -122,13 +145,8 @@ function citedSourceIds(body: string | undefined): Set<string> {
   const withoutCode = body
     .replace(/```[\s\S]*?```/g, '')
     .replace(/`[^`\n]*`/g, '');
-  const ids = new Set<string>();
-  for (const match of withoutCode.matchAll(
-    /\[@([a-z0-9][a-z0-9.-]*)(?:;[^\]]*)?\]/g,
-  )) {
-    ids.add((match[1] ?? '').trim());
-  }
-  return ids;
+  // A citation in a link's text renders as typed, so it cites nothing.
+  return citedIds(withoutLinkCitations(withoutCode)) as Set<string>;
 }
 
 function findDuplicates(values: readonly string[]): readonly string[] {
@@ -314,21 +332,24 @@ export function validateCurriculum(
       }
     }
     const cited = citedSourceIds(lesson.body);
+    if (lesson.body !== undefined) {
+      const blank = (code: string) => code.replace(/[^\n]/g, ' ');
+      const prose = lesson.body.replace(/```[\s\S]*?```/g, blank).replace(/`[^`\n]*`/g, blank);
+      for (const { text } of citationsInLinks(prose)) {
+        issues.push({
+          kind: 'citation-in-link',
+          message:
+            `${lesson.id} puts the citation ${text} inside a link's text, where it prints as typed: ` +
+            `a link cannot hold the citation's own link. Cite after the link: [the words](https://…) ${text}.`,
+        });
+      }
+    }
     for (const sourceId of lesson.sources) {
-      const source = sources.get(sourceId);
-      if (!source) {
+      if (!sources.has(sourceId)) {
         issues.push({
           kind: 'unknown-reference',
           message: `${lesson.id} references unknown source ${sourceId}`,
         });
-      } else if (
-        lesson.status === 'reviewed' &&
-        source.editorialStatus !== 'reviewed'
-      ) {
-        issues.push({
-          kind: 'review-state',
-          message: `${lesson.id} is reviewed but source ${sourceId} is ${source.editorialStatus}`,
-        });
       }
       if (lesson.body !== undefined && !cited.has(sourceId)) {
         issues.push({
@@ -347,7 +368,7 @@ export function validateCurriculum(
     }
     if (lesson.teaches.length > 0 && lesson.assumptions.length === 0) {
       issues.push({
-        kind: 'review-state',
+        kind: 'missing-assumptions',
         message: `${lesson.id} teaches quantitative content but declares no assumptions`,
       });
     }
@@ -385,14 +406,41 @@ export function validateCurriculum(
             message: `${assessment.id}/${item.id} has unknown correct option ${item.correctOptionId}`,
           });
         }
+      } else if (!Number.isFinite(item.answer.value)) {
+        issues.push({
+          kind: 'invalid-assessment',
+          message: `${assessment.id}/${item.id} answer.value must be a number`,
+        });
       } else if (
-        !Number.isFinite(item.answer.value) ||
         !Number.isFinite(item.answer.tolerance) ||
         item.answer.tolerance <= 0
       ) {
         issues.push({
           kind: 'invalid-assessment',
-          message: `${assessment.id}/${item.id} has an invalid numeric answer or tolerance`,
+          message:
+            `${assessment.id}/${item.id} answer.tolerance must be a number greater than 0, ` +
+            `not ${String(item.answer.tolerance)}: an answer within it of answer.value is correct. ` +
+            'For an exact whole-number answer, use a tolerance below one half, such as 0.4.',
+        });
+      }
+
+      const texts: [string, string | undefined][] = [
+        ['prompt', item.prompt],
+        ['explanation', item.explanation],
+        ...(item.type === 'single-choice'
+          ? item.options.map((option): [string, string] => [`option ${option.id}`, option.label])
+          : []),
+      ];
+      for (const [field, text] of texts) {
+        const found = text === undefined ? null : CHECK_TEXT_REFERENCE.exec(text);
+        if (!found) continue;
+        issues.push({
+          kind: 'invalid-assessment',
+          message:
+            `${assessment.id}/${item.id} ${field} contains ${found[0]}, which a knowledge ` +
+            'check shows exactly as written: its text renders math, not references or ' +
+            'citations. Name the equation, section or source in words, or cite it in the ' +
+            'lesson text the check follows.',
         });
       }