explico 0.13.1 → 0.15.0

package/src/compiler/validate-content.ts

@@ -0,0 +1,215 @@
+/**
+ * `pnpm validate:content` — regenerate `build/manifest.json` and report its
+ * diagnostics, whole. A course's `scripts/compile-manifest.ts` is three lines:
+ *
+ *   import { runValidateContent } from 'explico/compiler/validate-content';
+ *   import { courseConfig } from '../content/course.config';
+ *   process.exitCode = await runValidateContent(courseConfig);
+ *
+ * It compiles the one manifest (the single walk of the content tree), writes
+ * it deterministically, prints the warnings, refreshes the per-lesson
+ * resolution reports, `content/versions.json` (rule C5) and the
+ * rules-in-effect page, and returns 1 if any blocking diagnostic is present.
+ * `pnpm build` runs it first, so `astro build` and every page component read a
+ * current manifest and never re-read the content tree.
+ *
+ * Every line printed is also recorded, in Python's `logging` format, to
+ * `build/logs/<timestamp>/{error,warning,info}.log` (`./logging`); `log.<level>()`
+ * returns its message so the printed line and the recorded one cannot drift.
+ */
+import { notationSourceLocatorGaps } from './collections';
+import type { CourseConfig } from './course-config';
+import { createRunLog, diagnosticLine } from './logging';
+import { compileManifest, MANIFEST_PATH, writeManifest } from './manifest';
+import { syncPageVersions } from './page-versions';
+import { syncResolutionReports } from './resolution-report';
+import { consistencyCounts } from '../reference/consistency';
+import { curriculumErrors } from '../curriculum/validation';
+import { writeRulesInEffect } from '../rules/in-effect';
+
+export async function runValidateContent(courseConfig: CourseConfig): Promise<number> {
+  const log = createRunLog();
+
+  let manifest;
+  try {
+    manifest = await compileManifest(courseConfig);
+  } catch (error) {
+    // The log keeps why the run ended; the console gets the message, not a stack.
+    const message = error instanceof Error ? error.message : String(error);
+    log.error('manifest', `Manifest compilation failed: ${message}`);
+    const summary = log.close();
+    console.error(`Manifest compilation failed: ${message}\nRun log: ${summary.relativeDirectory}.`);
+    return 1;
+  }
+  writeManifest(manifest);
+
+  const {
+    curriculum,
+    notation,
+    alignment,
+    math,
+    consistency,
+    equations,
+    tables,
+    figures,
+    diagrams,
+    checks,
+    examples,
+    folds,
+    knowledge,
+    rawFloats,
+    config,
+    waivers,
+  } = manifest.diagnostics;
+
+  for (const warning of curriculum.filter((issue) => issue.severity === 'warning')) {
+    console.warn(log.warning('curriculum', `[${warning.kind}] ${warning.message}`));
+  }
+  for (const warning of notation.filter((d) => d.severity === 'warning')) {
+    console.warn(log.warning('notation', `[${warning.code}] ${warning.message}`));
+  }
+  for (const warning of alignment.filter((d) => d.severity === 'warning')) {
+    console.warn(log.warning('alignment', `[${warning.code}] ${warning.message}`));
+  }
+  const floatGroups = [
+    ['equations', equations],
+    ['tables', tables],
+    ['figures', figures],
+    ['diagrams', diagrams],
+    ['checks', checks],
+    ['examples', examples],
+    ['folds', folds],
+    ['rawFloats', rawFloats],
+  ] as const;
+  for (const [source, group] of floatGroups) {
+    for (const warning of group.filter((d) => d.severity === 'warning')) {
+      console.warn(log.warning(source, `[${warning.code}] ${warning.message}`));
+    }
+  }
+  // `diagnosticLine` prefixes a code owned by a lettered rule with its ID
+  // (`[N9 prose-notation] file:line: …`), so the console names the rule page.
+  for (const issue of math.filter((item) => item.severity === 'warning')) {
+    console.warn(log.warning('math', diagnosticLine(issue)));
+  }
+  for (const warning of knowledge) {
+    console.warn(log.warning('knowledge', `[${warning.code}] ${warning.message}`));
+  }
+  // The course settings themselves: a deprecated top-level block, a retired rule.
+  for (const warning of config) {
+    console.warn(log.warning('config', `[${warning.code}] ${warning.message}`));
+  }
+  // Per-place waivers: a stale one is a warning; a malformed or invalid one
+  // fails below with the other errors.
+  for (const warning of waivers.filter((d) => d.severity === 'warning')) {
+    console.warn(log.warning('waivers', diagnosticLine(warning)));
+  }
+
+  const locatorGaps = notationSourceLocatorGaps();
+  if (locatorGaps.bare > 0) {
+    console.warn(
+      log.warning(
+        'consistency',
+        `[notation-source-locator] ${locatorGaps.bare} of ${locatorGaps.total} notation source citations lack a non-empty locator.`,
+      ),
+    );
+  }
+
+  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.info(
+        'consistency',
+        `[consistency] ${consistencyWarnings.length} Tier-3 finding(s): ` +
+          Object.entries(consistencyCounts(consistencyWarnings))
+            .filter(([, count]) => count > 0)
+            .map(([code, count]) => `${code}=${count}`)
+            .join(', '),
+      ),
+    );
+  }
+
+  // Every severity-`info` diagnostic goes to the log only.
+  log.infoDiagnostics(manifest.diagnostics);
+  for (const diagnostic of consistencyWarnings) {
+    log.warning('consistency', `[${diagnostic.code}] ${diagnostic.message}`);
+  }
+
+  const reports = syncResolutionReports(manifest);
+  console.log(
+    log.info(
+      'manifest',
+      `Resolution report: ${reports.written} file(s) under resolution/` +
+        (reports.refreshed.length > 0
+          ? ` (${reports.refreshed.length} refreshed; git does not track them, nothing to commit).`
+          : '.'),
+    ),
+  );
+  // Each page's own version (rule C5): rewritten here and committed with the
+  // change; in CI a record that would change fails below, like a lockfile.
+  const pageVersions = syncPageVersions(manifest);
+  if (pageVersions.written) {
+    console.log(
+      log.info(
+        'page-versions',
+        `content/versions.json ${
+          pageVersions.changed[0] === '*' ? 'written' : `updated for ${pageVersions.changed.length} page(s)`
+        } — commit it with the change (rule C5).`,
+      ),
+    );
+  }
+  // The page an agent reads before drafting. Regenerated every run, never committed.
+  writeRulesInEffect(manifest);
+  console.log(
+    log.info('manifest', `Rules in effect: build/rules-in-effect.md (${manifest.rules.disabled.length} rule(s) off).`),
+  );
+
+  const failures: string[] = [];
+  // `block(source, …)`: a blocking finding under its log source (not a diagnostic code).
+  const block = (source: string, message: string): void => {
+    failures.push(log.error(source, message));
+  };
+  for (const stalePath of reports.stale) {
+    block('resolution-report', `[resolution-report] ${stalePath} is out of date — commit the regenerated resolution/ files`);
+  }
+  if (pageVersions.diagnostic) block('page-versions', diagnosticLine(pageVersions.diagnostic));
+  for (const issue of curriculumErrors(curriculum)) block('curriculum', `[curriculum:${issue.kind}] ${issue.message}`);
+  for (const issue of notation.filter((d) => d.severity === 'error')) block('notation', `[notation:${issue.code}] ${issue.message}`);
+  for (const issue of alignment.filter((d) => d.severity === 'error')) block('alignment', `[alignment:${issue.code}] ${issue.message}`);
+  for (const issue of math.filter((item) => item.severity === 'error')) block('math', diagnosticLine(issue));
+  for (const issue of waivers.filter((d) => d.severity === 'error')) block('waivers', diagnosticLine(issue));
+  for (const [source, group] of floatGroups) {
+    for (const issue of group.filter((d) => d.severity === 'error')) block(source, `[${issue.code}] ${issue.message}`);
+  }
+
+  if (failures.length > 0) {
+    const summary = log.close();
+    console.error(
+      `Content manifest has ${failures.length} blocking diagnostic(s):\n${failures.map((line) => `- ${line}`).join('\n')}\n` +
+        `Run log: ${summary.relativeDirectory} (${summary.counts.ERROR} error(s), ${summary.counts.WARNING} warning(s)).`,
+    );
+    return 1;
+  }
+
+  const itemCount = manifest.lessons.reduce((count, lesson) => count + lesson.assessments.length, 0);
+  const relPath = MANIFEST_PATH.replace(`${process.cwd()}/`, '');
+  console.log(
+    log.info(
+      'manifest',
+      `Manifest written to ${relPath} (schema v${manifest.schemaVersion}, knowledge v${manifest.about.knowledge.version}): ` +
+        `${manifest.competencies.length} competencies, ${manifest.lessons.length} lessons, ` +
+        `${itemCount} lesson assessment links, ${manifest.notation.definitions.length} notation definitions, ` +
+        `${manifest.sources.length} sources, ${manifest.tracks.length} track(s). ` +
+        `Content fingerprint ${manifest.hashes.contentTree}.`,
+    ),
+  );
+
+  const summary = log.close();
+  console.log(
+    `Run log: ${summary.relativeDirectory} ` +
+      `(${summary.counts.ERROR} error(s), ${summary.counts.WARNING} warning(s), ${summary.counts.INFO} info).`,
+  );
+  return 0;
+}

package/src/components/CourseContents.astro

@@ -9,6 +9,13 @@
  * each part heading linking its overview page where one exists, and study
  * times totalled per part and for the course when every chapter states one.
  *
+ * When the course has a deck, each title starts with the glyph of what it
+ * opens (a chapter's sheet, a slides-only lesson's frame), a key and a deck
+ * count join the counts, and a slides column ends every row: a lesson's own
+ * deck is a tile on its title line, a part's deck one bar along the chapters
+ * it covers (`deck-lane.ts`). It lists every edition whatever the sidebar's
+ * controls say: it answers "what is in the course".
+ *
  * Usage, on a splash page:
  *
  * ```mdx
@@ -18,15 +25,21 @@
  * ```
  */
 import { loadManifest } from '../compiler/manifest';
+import { contentsKey, deckLanes, laneLink, titleGlyph } from './deck-lane';
 
 interface Props {
   /** Heading level for each part's name. Defaults to `h2`. */
   readonly headingLevel?: 2 | 3;
   /** Set `false` to drop the per-chapter description column. */
   readonly descriptions?: boolean;
+  /**
+   * Set `false` to drop the slides column, the glyphs, the key and the deck
+   * count. They show only when the course has a deck.
+   */
+  readonly slides?: boolean;
 }
 
-const { headingLevel = 2, descriptions = true } = Astro.props;
+const { headingLevel = 2, descriptions = true, slides = true } = Astro.props;
 const Heading = `h${headingLevel}` as 'h2' | 'h3';
 
 const manifest = await loadManifest();
@@ -44,7 +57,24 @@ const parts = manifest.parts
         (lesson): lesson is NonNullable<typeof lesson> => lesson !== undefined,
       ),
   }))
-  .filter((part) => part.chapters.length > 0);
+  .filter((part) => part.chapters.length > 0)
+  .map((part) => ({
+    ...part,
+    lanes: slides ? deckLanes({ lessons: part.chapters, decks: manifest.decks, part }) : [],
+  }));
+
+// The glyphs, the key and the count say which lessons have slides: in a
+// course with no deck they would explain one glyph, so the list stays as it
+// was. The column is as wide as the part that needs most lanes, so it lines
+// up across parts.
+const key = slides ? contentsKey(manifest.lessons, manifest.decks) : [];
+const glyphs = key.length > 0;
+const laneCount = Math.max(0, ...parts.map((part) => part.lanes.length));
+const keyLabel = {
+  chapter: 'Chapter',
+  deck: 'Slides',
+  'part-deck': 'Slides for a whole part',
+} as const;
 
 const chapterCount = parts.reduce(
   (total, part) => total + part.chapters.length,
@@ -74,19 +104,42 @@ const hours = (range: { min: number; max: number }) => {
 };
 ---
 
-<div class="course-contents not-content">
+<div
+  class="course-contents not-content"
+  data-deck-lanes={laneCount > 0 ? laneCount : undefined}
+  style={laneCount > 0 ? `--deck-lanes: ${laneCount}` : undefined}
+>
   <p class="course-meta">
     <span>{parts.length} parts</span>
     <span>{chapterCount} chapters</span>
+    {
+      glyphs && (
+        <span>
+          {manifest.decks.length} {manifest.decks.length === 1 ? 'slide deck' : 'slide decks'}
+        </span>
+      )
+    }
     {courseMinutes && <span>{hours(courseMinutes)} of study</span>}
   </p>
+  {
+    glyphs && (
+      <ul class="contents-key" aria-label="Key">
+        {key.map((glyph) => (
+          <li>
+            <span class={`contents-glyph contents-glyph--${glyph}`} aria-hidden="true" />
+            {keyLabel[glyph]}
+          </li>
+        ))}
+      </ul>
+    )
+  }
 
   {
     parts.map((part) => (
       <section class="course-part">
         <Heading id={`contents-${part.dir}`}>
           {part.overview ? (
-            <a href={`${base}${part.link}`}>{part.label}</a>
+            <a href={`${base}${part.link}`}>{glyphs && <span class="contents-glyph contents-glyph--part" aria-hidden="true" />}{part.label}</a>
           ) : (
             part.label
           )}
@@ -99,13 +152,23 @@ const hours = (range: { min: number; max: number }) => {
           {part.studyMinutes && <span>{minutes(part.studyMinutes)}</span>}
         </p>
         <ol aria-labelledby={`contents-${part.dir}`}>
-          {part.chapters.map((lesson) => (
+          {part.chapters.map((lesson, row) => (
             <li>
-              <a href={`${base}/${lesson.slug}/`}>{lesson.title}</a>
+              <a href={`${base}/${lesson.slug}/`}>{glyphs && <span class={`contents-glyph contents-glyph--${titleGlyph(lesson)}`} aria-hidden="true" />}{lesson.title}</a>
               {lesson.studyMinutes && (
                 <span class="chapter-time">{minutes(lesson.studyMinutes)}</span>
               )}
               {descriptions && <p>{lesson.description}</p>}
+              {part.lanes.map((lane, index) => {
+                const cell = lane[row];
+                return (
+                  cell && (
+                    <a {...laneLink(cell, index, laneCount, base)}>
+                      <span class="sr-only">{cell.name}</span>
+                    </a>
+                  )
+                );
+              })}
             </li>
           ))}
         </ol>
@@ -224,4 +287,59 @@ const hours = (range: { min: number; max: number }) => {
       text-align: start;
     }
   }
+
+  /* The key under the counts: the glyphs the list uses, in the accent. */
+  .contents-key {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem 1.25rem;
+    margin: -1.1rem 0 0;
+    padding: 0;
+    list-style: none;
+    color: var(--sl-color-gray-2);
+    font-size: var(--sl-text-sm);
+  }
+
+  .contents-key li {
+    margin: 0;
+  }
+
+  .contents-key :global(.contents-glyph) {
+    color: var(--sl-color-text-accent);
+  }
+
+  /* The slides column (`global.css`): one 1.7rem column per lane at the
+     row's end. The description keeps to the title's and time's columns. A
+     bar's cell spans a row's title and description, and reaches the line
+     between two rows: the row's bottom padding and the list's gap below it,
+     the next row's top border and padding above. */
+  .course-contents[data-deck-lanes] {
+    --deck-lane-rows: 2;
+    --deck-lane-down: 0.5rem;
+    --deck-lane-up: calc(0.4rem + 1px);
+  }
+
+  .course-contents[data-deck-lanes] .course-part li {
+    grid-template-columns: 1.9rem minmax(0, 1fr) auto repeat(var(--deck-lanes), 1.7rem);
+  }
+
+  .course-contents[data-deck-lanes] .course-part li > p {
+    grid-column: 2 / 4;
+  }
+
+  /* On a phone the time goes under the title, and the cells span the three
+     rows. */
+  @media (max-width: 40rem) {
+    .course-contents[data-deck-lanes] {
+      --deck-lane-rows: 3;
+    }
+
+    .course-contents[data-deck-lanes] .course-part li {
+      grid-template-columns: 1.9rem minmax(0, 1fr) repeat(var(--deck-lanes), 1.7rem);
+    }
+
+    .course-contents[data-deck-lanes] .course-part li > p {
+      grid-column: 2;
+    }
+  }
 </style>

package/src/components/CurriculumMap.astro

@@ -2,8 +2,29 @@
 import { getCollection } from 'astro:content';
 import { loadManifest } from '../compiler/manifest';
 import { isLessonSlug, lessonIdFromSlug } from '../compiler/lesson-derivation';
+import { competencyGraphsByPart } from '../curriculum/competency-graph';
 import Diagram, { type DiagramEdge, type DiagramNode } from './diagram/Diagram.astro';
 
+export interface Props {
+  /**
+   * `'whole'` (the default) draws the competency graph as one diagram;
+   * `'per-part'` draws one diagram per part, in sidebar order, holding the
+   * competencies its lessons teach first and, labelled with their part, the
+   * earlier competencies they build on. A graph too wide for the column as
+   * one diagram (rule V8) usually fits as one per part.
+   */
+  graph?: 'whole' | 'per-part';
+  /** The layout direction of every competency diagram; `Diagram`'s default is `'TB'`. */
+  direction?: 'TB' | 'LR';
+  /**
+   * Passed to every competency diagram: the width, in px, above which rule V8
+   * warns, or `false` to let a whole-course graph scroll without a warning.
+   */
+  warnAboveWidth?: number | false;
+}
+
+const { graph = 'whole', direction, warnAboveWidth } = Astro.props;
+
 const [tracks, docs, competencies, manifest] = await Promise.all([
   getCollection('tracks'),
   getCollection('docs'),
@@ -37,6 +58,15 @@ const competencyEdges: DiagramEdge[] = competencies.flatMap(({ data }) =>
     to: data.id,
   })),
 );
+
+const partGraphs =
+  graph === 'per-part'
+    ? competencyGraphsByPart(
+        manifest.parts,
+        new Map(manifest.lessons.map((lesson) => [lesson.id, lesson.teaches])),
+        competencies.map(({ data }) => data),
+      )
+    : [];
 ---
 
 {
@@ -127,12 +157,30 @@ const competencyEdges: DiagramEdge[] = competencies.flatMap(({ data }) =>
   </p>
 
   {
-    competencyNodes.length > 0 && (
+    partGraphs.map((partGraph) => (
+      <>
+        <h3 id={`${partGraph.id}-heading`}>{partGraph.title}</h3>
+        <Diagram
+          id={partGraph.id}
+          caption={`The competencies taught in ${partGraph.title}: an arrow runs from a prerequisite to the competency that builds on it, and a box labelled with an earlier part is a competency taught there`}
+          nodes={partGraph.nodes}
+          edges={partGraph.edges}
+          direction={direction}
+          warnAboveWidth={warnAboveWidth}
+        />
+      </>
+    ))
+  }
+
+  {
+    graph === 'whole' && competencyNodes.length > 0 && (
       <Diagram
         id="competency-graph"
         caption="The competency dependency graph: an arrow runs from a prerequisite to the competency that builds on it"
         nodes={competencyNodes}
         edges={competencyEdges}
+        direction={direction}
+        warnAboveWidth={warnAboveWidth}
       />
     )
   }

package/src/components/FloatIndex.astro

@@ -27,7 +27,7 @@
  * ```
  */
 import { loadManifest, type ManifestLessonFloat } from '../compiler/manifest';
-import { FLOAT_KIND_WORDS, type FloatKind } from './float-name';
+import { FLOAT_KIND_WORDS, type FloatKind } from '../reference/float-name';
 
 interface Props {
   /** Heading level for each part's name; a chapter's is one below. Defaults to `h2`. */

package/src/components/PartOverview.astro

@@ -7,7 +7,9 @@
  * collection — chapter order, titles, descriptions, float counts, and which
  * parts this one builds on or feeds. A course authors the page's prose; it
  * never re-types the list, so a renamed chapter or a new prerequisite cannot
- * leave a stale copy behind on the part page.
+ * leave a stale copy behind on the part page. When the course has a deck, the
+ * list has the contents list's glyphs and slides column (`deck-lane.ts`,
+ * `CourseContents.astro`).
  *
  * Usage, in `content/docs/<part>/index.mdx`:
  *
@@ -38,6 +40,7 @@
  */
 import { getCollection } from 'astro:content';
 import { loadManifest, type ManifestPart } from '../compiler/manifest';
+import { deckLanes, laneLink, titleGlyph } from './deck-lane';
 
 interface Props {
   /**
@@ -53,9 +56,14 @@ interface Props {
   readonly chain?: readonly string[];
   /** Set `false` to drop the rail and keep only the reading list. */
   readonly rail?: boolean;
+  /**
+   * Set `false` to drop the slides column and the glyphs before the titles.
+   * They show only when the course has a deck.
+   */
+  readonly slides?: boolean;
 }
 
-const { part: partProp, chain = [], rail = true } = Astro.props;
+const { part: partProp, chain = [], rail = true, slides = true } = Astro.props;
 
 const routeSlug = Astro.locals.starlightRoute.entry.id;
 const partDir = partProp ?? routeSlug.replace(/\/index$/, '').split('/')[0];
@@ -82,6 +90,11 @@ const chapters = part.lessons
   .map((id) => lessonById.get(id))
   .filter((lesson): lesson is NonNullable<typeof lesson> => lesson !== undefined);
 
+// As in the contents list: glyphs only in a course with a deck, and the
+// column only when this part has one.
+const glyphs = slides && manifest.decks.length > 0;
+const lanes = glyphs ? deckLanes({ lessons: chapters, decks: manifest.decks, part }) : [];
+
 const competencyById = new Map(
   competencyEntries.map(({ data }) => [data.id, data]),
 );
@@ -169,11 +182,15 @@ const hasRail =
   </ul>
 
   <div class="part-body">
-    <ol class="part-chapters">
+    <ol
+      class="part-chapters"
+      data-deck-lanes={lanes.length > 0 ? lanes.length : undefined}
+      style={lanes.length > 0 ? `--deck-lanes: ${lanes.length}` : undefined}
+    >
       {
-        chapters.map((lesson) => (
+        chapters.map((lesson, row) => (
           <li>
-            <a href={`${base}/${lesson.slug}/`}>{lesson.title}</a>
+            <a href={`${base}/${lesson.slug}/`}>{glyphs && <span class={`contents-glyph contents-glyph--${titleGlyph(lesson)}`} aria-hidden="true" />}{lesson.title}</a>
             <p>{lesson.description}</p>
             <p class="chapter-meta">
               {lesson.studyMinutes && (
@@ -192,6 +209,16 @@ const hasRail =
                 </span>
               )}
             </p>
+            {lanes.map((lane, index) => {
+              const cell = lane[row];
+              return (
+                cell && (
+                  <a {...laneLink(cell, index, lanes.length, base)}>
+                    <span class="sr-only">{cell.name}</span>
+                  </a>
+                )
+              );
+            })}
           </li>
         ))
       }
@@ -342,6 +369,25 @@ const hasRail =
     line-height: 1.5;
   }
 
+  /* The slides column (`global.css`): one 1.7rem column per lane at the
+     row's end, the title, description and meta line kept to the second
+     column. A bar's cell spans the three, and reaches the line under its
+     row: the row's bottom padding, then the next row's top padding and the
+     line itself above. */
+  .part-chapters[data-deck-lanes] {
+    --deck-lane-rows: 3;
+    --deck-lane-down: 0.85rem;
+    --deck-lane-up: calc(0.85rem + 1px);
+  }
+
+  .part-chapters[data-deck-lanes] > li {
+    grid-template-columns: 2.25rem minmax(0, 1fr) repeat(var(--deck-lanes), 1.7rem);
+  }
+
+  .part-chapters[data-deck-lanes] > li > :not(.deck-lane) {
+    grid-column: 2;
+  }
+
   .chapter-meta {
     display: flex;
     flex-wrap: wrap;

package/src/components/assessments/AssessmentSet.astro

@@ -7,6 +7,8 @@ import { renderNotationMath } from '../notation/render-notation-math';
 import type { MixedContentNode } from '../notation/render-notation-math';
 import { knowledgeCheckAnchorId } from '../../reference/knowledge-checks.mjs';
 import BlockHeading from '../BlockHeading.astro';
+import { deckOfRoute } from '../deck/deck-context';
+import { routeIdFromLocals } from '../../reference/page-notation';
 import AssessmentRunner from './AssessmentRunner';
 
 interface Props {
@@ -17,17 +19,29 @@ interface Props {
    * `[[check-…]]` references; undeclared legacy embeds keep a local fallback.
    */
   id?: string;
+  /**
+   * The lesson whose checks the set asks, by its id. Set by the engine on a
+   * part's deck (`deck-remark.mjs`): the chapter the frame's section covers.
+   * Elsewhere the page's own lesson.
+   */
+  lesson?: string;
 }
 
 const explicitId = Astro.props.id;
 
 const base = import.meta.env.BASE_URL.replace(/\/$/, '');
-const lessonId = Astro.url.pathname
-  .replace(new RegExp(`^${base}/`), '')
-  .replace(/\/$/, '')
-  .replace(/\//g, '.');
-
 const manifest = await loadManifest();
+// On a deck (docs/authoring/deck.md) the checks are its lesson's, and a check
+// is a question frame: its label, not a heading of its own. On a part's deck
+// they are the chapter's whose section the frame is in.
+const deck = deckOfRoute(manifest, routeIdFromLocals(Astro.locals));
+const lessonId =
+  Astro.props.lesson ??
+  deck?.lessonId ??
+  Astro.url.pathname
+    .replace(new RegExp(`^${base}/`), '')
+    .replace(/\/$/, '')
+    .replace(/\//g, '.');
 // A check folds like a section, by the course's `disclosure.knowledgeChecks`
 // (collapsible and open unless the course says otherwise).
 const { knowledgeChecks } = manifest.disclosure ?? DISCLOSURE_DEFAULTS;
@@ -101,16 +115,28 @@ function renderedContent(
 {
   entries.map(({ entry, number, anchorId }) => (
     <>
-      <BlockHeading
-        kind="check"
-        anchorId={anchorId}
-        title={entry.data.title}
-        number={number}
-        collapsible={knowledgeChecks.collapsible}
-        defaultOpen={knowledgeChecks.defaultOpen}
-        card="accent"
-        class="assessment-heading-wrapper"
-      />
+      {deck ? (
+        <p
+          class="deck-check__label"
+          id={anchorId}
+          data-block-kind="check"
+          data-check-number={number}
+          data-check-title={entry.data.title}
+        >
+          <span class="deck-check__kind">Knowledge check {number}</span> {entry.data.title}
+        </p>
+      ) : (
+        <BlockHeading
+          kind="check"
+          anchorId={anchorId}
+          title={entry.data.title}
+          number={number}
+          collapsible={knowledgeChecks.collapsible}
+          defaultOpen={knowledgeChecks.defaultOpen}
+          card="accent"
+          class="assessment-heading-wrapper"
+        />
+      )}
       <AssessmentRunner
         client:visible
         assessmentId={entry.data.id}