@brandon_m_behring/book-scaffold-astro 4.15.0 → 4.17.0

package/CLAUDE.md

@@ -100,10 +100,12 @@ Two callout families coexist. Authors import what they need.
 
 **Pedagogy family** (v4.1.0+, any profile, 3 components): `Pitfall` (rose; "common mistake" — distinct from `WarnBox`'s preemptive warning), `WorkedExample` (plum; collapsible `<details>` block with `#worked-example-{id}` anchor for deep links), `YouWillLearn` (gold; chapter-opener with optional `prerequisites` prop). Slot bullets/code freely; render at any preset.
 
-**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginNote`, `Sidenote`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`, `PocLayout` (v4.1.0+; wraps slot in a per-`kind` layout shell — 5 closed-union kinds; see `recipes/15-defining-styles.md`).
+**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginNote`, `Sidenote`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`, `BookLink` (v4.16.0+; cross-book link — `<BookLink book="design" to="…"/>` resolves `book` against `defineBookConfig({ siblingBooks })` and throws on an unknown book; `<XRef>` is in-book only — #96), `PocLayout` (v4.1.0+; wraps slot in a per-`kind` layout shell — 5 closed-union kinds; see `recipes/15-defining-styles.md`).
 
 **Provenance** (v4.8.0, any profile, **auto-injected by the chapter route — not author-imported**): per-chapter "How this was made" audit-trail block, rendered from the optional `provenance` frontmatter (`ai_tools`, `prompts_archive`, `decisions_log`, `audit_history`, `citation_backstop`). **Opt-out**: a chapter with no `provenance` shows a fallback ("Audit history not yet recorded"). Distinct from `AICollaborationDisclosure` (book-level, manual model+role disclosure). Repo-relative path fields render as `<code>`; only `http(s)` values link.
 
+**Study-guide (v4.17.0+, #112; opt-in).** A schema-validated `questions` content collection drives an exam-prep "question bank". Author questions under `src/content/questions/**.{md,mdx}` — frontmatter `id` (unique, required) / `type` (`mcq`|`free`|`cloze`) / `chapter` / `domain` (+ optional `part`/`bloom_level`/`objective_id`/`difficulty`), MDX body = the stem. MCQ carries `options: [{ id, text, correct }]` (exactly one `correct: true`); free-response carries an `answer` (model answer). An MCQ must **not** set `answer` — its answer is the option marked `correct`, and explanations for any type go in a `<Rationale>` body block. Declare the per-book domain taxonomy in `defineBookConfig({ examDomains: ['…'] })` — a question whose `domain` isn't registered **throws at build** (fail-loud, like `<BookLink>`'s `siblingBooks`). Enable the static `/practice-exam` route with `defineBookConfig({ routes: { practiceExam: true } })` (renders the bank grouped by domain with answers behind a `<details>` reveal; `cloze` is reserved/render-deferred). `<ObjectiveMap />` renders the exam-domain → chapter coverage matrix auto-derived from the collection (no separate data file). `<Rationale>` is a collapsible answer/explanation marker for a question's MDX body. (Scoring + diagnostics + appendix + flashcards are later increments — see `docs/plans/active/study-guide-epic_*.md`.)
+
 Full reference in `recipes/04-component-library.md`.
 
 ### Theme-change event (v4.14.2)
@@ -168,6 +170,7 @@ For monorepo Astro projects (Astro project in subdir), prefix build + deploy com
 - Unknown `<XRef id>` — id not in `labels.json` (XRef silently renders `[?label]` otherwise)
 - Missing `<Figure src>` files under `public/`
 - Internal markdown links that don't resolve
+- Study-guide questions (v4.17.0, #112) — a question whose frontmatter `domain` isn't in `examDomains`, and duplicate question `id`s
 
 See `recipes/09-validation.md` to extend.
 

package/components/BookLink.astro

@@ -0,0 +1,32 @@
+---
+/**
+ * BookLink — cross-book link to a sibling scaffold book (#96).
+ *
+ * Each scaffold book is a separate Astro app with its own `labels.json` and
+ * deploy origin, so `<XRef>` can't reach a sibling — a cross-book ref resolves
+ * against the wrong labels and dies. `<BookLink book="design" to="…">` resolves
+ * `book` against the consumer's `siblingBooks` registry
+ * (`defineBookConfig({ siblingBooks })`) — the single place to update when a
+ * sibling redeploys or extracts to its own repo. An unknown `book` throws at
+ * build (fail-loud, see `src/lib/book-link`), never a dead cross-origin link.
+ *
+ * `to` is a path within the sibling book (its router shape), e.g.
+ * `chapters/<slug>/#<id>`. Phase 1 builds the href; Phase 2 (deferred) will
+ * validate `to` against a vendored sibling `labels.json`.
+ *
+ * Usage:
+ *   For design depth see
+ *   <BookLink book="design" to="chapters/patterns/#layered">the layered pattern</BookLink>.
+ */
+import bookConfig from 'virtual:book-scaffold/book-config';
+import { resolveBookHref } from '../src/lib/book-link';
+
+interface Props {
+  book: string;
+  to: string;
+}
+
+const { book, to } = Astro.props;
+const href = resolveBookHref(bookConfig.siblingBooks, book, to);
+---
+<a href={href} rel="external noopener" class="book-link"><slot /></a>

package/components/ObjectiveMap.astro

@@ -0,0 +1,113 @@
+---
+/**
+ * <ObjectiveMap> — exam-domain → chapter coverage matrix (v4.17.0, Tier 3 #117).
+ *
+ * The reader-facing twin of a CompTIA/Cisco objective-coverage table. AUTO-
+ * DERIVED from getCollection('questions'): for each configured exam domain
+ * (defineBookConfig({ examDomains })), it shows which chapters carry ≥1 question
+ * in that domain. There is no separate coverage data file — the matrix is
+ * computed from the question bank, so it cannot drift from reality (and it can't
+ * render at all unless the per-book examDomains taxonomy is populated and
+ * consistent, which is the cheapest proof that taxonomy pays off).
+ *
+ * A domain with no questions renders an honest "—" gap rather than being
+ * omitted, so the table never implies coverage the bank doesn't have (same
+ * coverage-honesty discipline as /convergence).
+ *
+ * Drop into a front-matter / intro page. Any profile. Twin-gated: with no
+ * questions collection, renders an honest note instead of touching the
+ * collection (which would throw when unregistered).
+ */
+import bookConfig from 'virtual:book-scaffold/book-config';
+import { getCollection } from 'astro:content';
+import { deriveObjectiveMap, distinctChaptersSorted } from '../src/lib/questions';
+import { assertKnownDomain } from '../src/lib/exam-domains';
+
+interface Props {
+  /** Heading above the table. Defaults to "Exam objective coverage". */
+  title?: string;
+}
+const { title = 'Exam objective coverage' } = Astro.props;
+
+// Presence-gate: only touch the collection when the directory holds files.
+const questionModules = import.meta.glob('/src/content/questions/**/*.{md,mdx}', {
+  query: '?raw',
+  import: 'default',
+  eager: true,
+});
+const hasQuestions = Object.keys(questionModules).length > 0;
+
+const entries = hasQuestions
+  ? await getCollection('questions', (e) => !e.data.draft)
+  : [];
+// Fail loud (like /practice-exam): a question with an unregistered / typo'd
+// domain must throw at build, not silently vanish from the coverage matrix.
+for (const e of entries) {
+  assertKnownDomain(bookConfig.examDomains, e.data.domain, { id: e.data.id });
+}
+const coverage = deriveObjectiveMap(entries);
+const domains = bookConfig.examDomains ?? [];
+// Column set: chapters that carry ≥1 question, in numeric-aware order
+// (distinctChaptersSorted — a bare .sort() would order "10" before "2").
+const chapters = distinctChaptersSorted(entries);
+---
+{domains.length === 0 ? (
+  <p class="objective-map-empty">
+    No <code>examDomains</code> configured. Declare them in
+    <code>defineBookConfig({'{'} examDomains: [&hellip;] {'}'})</code> to render the coverage map.
+  </p>
+) : chapters.length === 0 ? (
+  <p class="objective-map-empty">
+    No questions found under <code>src/content/questions/</code> yet — the coverage map
+    populates as you add questions tagged with these domains.
+  </p>
+) : (
+  <figure class="objective-map">
+    <figcaption class="objective-map-title">{title}</figcaption>
+    <table class="objective-map-table">
+      <thead>
+        <tr>
+          <th scope="col">Domain</th>
+          {chapters.map((c) => <th scope="col">{c}</th>)}
+        </tr>
+      </thead>
+      <tbody>
+        {domains.map((domain) => {
+          const covered = coverage.get(domain) ?? new Set();
+          const isGap = covered.size === 0;
+          return (
+            <tr class={isGap ? 'objective-map-gap' : undefined}>
+              <th scope="row">{domain}</th>
+              {chapters.map((c) => (
+                <td aria-label={covered.has(c) ? `${domain} covered in ${c}` : undefined}>
+                  {covered.has(c) ? '✓' : '—'}
+                </td>
+              ))}
+            </tr>
+          );
+        })}
+      </tbody>
+    </table>
+  </figure>
+)}
+
+<style>
+  .objective-map { margin-block: 1.5rem; overflow-x: auto; }
+  .objective-map-title { font-weight: 600; margin-block-end: 0.5rem; }
+  .objective-map-empty { color: var(--color-text-muted, #6b7280); }
+  .objective-map-table { border-collapse: collapse; width: 100%; font-size: 0.9rem; }
+  .objective-map-table th,
+  .objective-map-table td {
+    border: 1px solid var(--color-border, #e5e7eb);
+    padding: 0.35rem 0.55rem;
+    text-align: center;
+  }
+  .objective-map-table th[scope='row'] {
+    text-align: start;
+    text-transform: capitalize;
+    white-space: nowrap;
+  }
+  .objective-map-table td { color: var(--color-accent, #4f46e5); }
+  .objective-map-gap th[scope='row'] { color: var(--color-text-muted, #6b7280); }
+  .objective-map-gap td { color: var(--color-text-muted, #6b7280); }
+</style>

package/components/Rationale.astro

@@ -0,0 +1,38 @@
+---
+/**
+ * <Rationale> — collapsible answer/explanation for a study-guide question
+ * (v4.17.0, Tier 3). Renders its slot inside a <details> so the answer stays
+ * hidden until the reader chooses to reveal it (Bjork desirable-difficulties:
+ * delayed feedback aids retention). Authored in a question's MDX body; the
+ * answer-rationale back-appendix (#114) will later hoist these into an appendix
+ * using this same marker — so a rich, cited rationale has a stable home now.
+ *
+ * Any profile. Register it in src/mdx-components.ts (defineMdxComponents) to use
+ * inside src/content/questions/**.mdx. Slot freely: prose, math, <Cite>, code.
+ */
+interface Props {
+  /** Summary label for the reveal. Defaults to "Answer & rationale". */
+  title?: string;
+}
+const { title = 'Answer & rationale' } = Astro.props;
+---
+<details class="question-rationale">
+  <summary>{title}</summary>
+  <div class="question-rationale-body"><slot /></div>
+</details>
+
+<style>
+  .question-rationale {
+    margin-block: 0.75rem;
+    border-inline-start: 3px solid var(--color-accent, #4f46e5);
+    padding-inline-start: 0.75rem;
+  }
+  .question-rationale > summary {
+    cursor: pointer;
+    font-weight: 600;
+    color: var(--color-accent, #4f46e5);
+  }
+  .question-rationale-body {
+    margin-block-start: 0.5rem;
+  }
+</style>

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Y as volatilityLevels, h as ChaptersRenderer, r as academicParts, o as Style } from './types-CjOseOSG.js';
-export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, m as Provenance, R as ResearchPortfolioChapter, n as RouteToggles, S as StatusBadge, p as StyleInput, T as ToolsChapter, V as VolatilityBadge, q as academicChapterSchema, s as changeKinds, t as changelogSchema, u as chapterStatus, v as citationBackstops, w as composeStyles, x as courseNotesChapterSchema, y as defineProfile, z as defineStyle, D as minimalChapterSchema, E as normalizeFrontmatterConfig, G as patternCategories, H as patternsSchema, I as provenanceObject, J as provenanceSchema, K as researchPortfolioChapterSchema, L as resolvePreset, N as resolveProfile, O as sourceTiers, Q as sourceTiersResearch, U as sourcesSchema, W as toolSlugs, X as toolsChapterSchema } from './types-CjOseOSG.js';
+import { d as BookConfigOptions, g as BookScaffoldIntegrationOptions, a5 as volatilityLevels, i as ChaptersRenderer, t as academicParts, Q as Question, q as Style } from './types-CMPuyZGP.js';
+export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BloomLevel, c as BookConfigError, e as BookPreset, f as BookProfile, h as BookSchemasOptions, C as ChapterFor, j as CourseNotesChapter, F as FreshnessAffordance, k as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, l as PartialRouteToggles, m as ProfileDefinition, n as Provenance, o as QuestionType, R as ResearchPortfolioChapter, p as RouteToggles, S as StatusBadge, r as StyleInput, T as ToolsChapter, V as VolatilityBadge, s as academicChapterSchema, u as bloomLevels, v as changeKinds, w as changelogSchema, x as chapterStatus, y as citationBackstops, z as composeStyles, D as courseNotesChapterSchema, E as defineProfile, G as defineStyle, H as minimalChapterSchema, I as normalizeFrontmatterConfig, J as patternCategories, K as patternsSchema, L as provenanceObject, N as provenanceSchema, O as questionDifficulties, U as questionSchema, W as questionTypes, X as refineQuestion, Y as refinedQuestionSchema, Z as researchPortfolioChapterSchema, _ as resolvePreset, $ as resolveProfile, a0 as sourceTiers, a1 as sourceTiersResearch, a2 as sourcesSchema, a3 as toolSlugs, a4 as toolsChapterSchema } from './types-CMPuyZGP.js';
 import 'astro/zod';
 
 /**
@@ -320,6 +320,89 @@ declare function assertEnumProp<T extends string>(value: unknown, allowed: reado
     prop: string;
 }): T;
 
+/**
+ * book-link — resolve a cross-book `<BookLink>` href from the consumer's
+ * sibling-book registry (#96).
+ *
+ * Each scaffold book is a separate Astro app with its own `labels.json` and
+ * deploy origin, so `<XRef>` can't reach a sibling book — a cross-book ref
+ * resolves against the wrong labels and dies. `<BookLink book to>` instead
+ * resolves `book` against a per-consumer registry of sibling base URLs
+ * (`defineBookConfig({ siblingBooks })`) — the single place to update when a
+ * sibling redeploys or extracts to its own repo. An unknown `book` THROWS
+ * rather than emitting a dead cross-origin link (fail-loud, like #109).
+ *
+ * Phase 1 (this): registry-backed href + fail-loud on unknown book. Phase 2
+ * (deferred): validate the `to` id against a vendored sibling `labels.json`.
+ */
+declare function resolveBookHref(siblingBooks: Record<string, string> | null | undefined, book: string, to: string): string;
+
+/**
+ * exam-domains — validate a question's `domain` against the consumer's closed
+ * `examDomains` taxonomy (Tier 3, #112).
+ *
+ * Exam domains are PER-BOOK (Cisco security domains ≠ CompTIA objectives ≠ a
+ * math syllabus's topics), so they can't be a hardcoded `z.enum` in the schema.
+ * The consumer declares them once — `defineBookConfig({ examDomains: [...] })`,
+ * threaded through the `virtual:book-scaffold/book-config` module — and a
+ * question whose `domain` is not in that list THROWS at build rather than
+ * silently mis-weighting a blueprint or dropping a row from the objective-map.
+ *
+ * Membership can't be a Zod invariant: `questionSchema` is constructed at
+ * package-load time, outside any consumer context, so it can't see
+ * `examDomains` (the same constraint that put `siblingBooks` validation in
+ * lib/book-link.ts rather than the schema). So Zod checks `domain` is a
+ * non-empty string; THIS runs at the route/build layer where the resolved
+ * config is available. Mirrors `resolveBookHref` (lib/book-link.ts).
+ */
+declare function assertKnownDomain(examDomains: readonly string[] | null | undefined, domain: string, ctx: {
+    id: string;
+}): string;
+
+/**
+ * src/lib/questions-derive.ts — PURE grouping + objective-map derivation for the
+ * study-guide `questions` collection (Tier 3, #112).
+ *
+ * No `astro:content` import, so this is safe in the Node-loaded main entry and
+ * unit-tested directly from dist/ (tests/questions.test.mjs). The Astro-context
+ * `getCollection` wrapper lives in questions.ts — same split as
+ * chapter-sort.ts (pure) / chapters.ts (Astro wrapper).
+ */
+
+/** Stable string label for a chapter ref (number or academic-style string). */
+declare function chapterLabel(chapter: number | string): string;
+/** Sort questions by chapter then id (stable, deterministic). Pure. */
+declare function sortQuestions<T extends {
+    data: Pick<Question, 'chapter' | 'id'>;
+}>(entries: readonly T[]): T[];
+/** Group entries by `domain`, preserving input order within each bucket. */
+declare function groupByDomain<T extends {
+    data: Pick<Question, 'domain'>;
+}>(entries: readonly T[]): Map<string, T[]>;
+/** Group entries by `chapter` (string label), preserving input order. */
+declare function groupByChapter<T extends {
+    data: Pick<Question, 'chapter'>;
+}>(entries: readonly T[]): Map<string, T[]>;
+/**
+ * Domain → set of chapter labels that have ≥1 question in that domain. The data
+ * backbone of `<ObjectiveMap>` (#117): the coverage matrix is *derived* from the
+ * question bank, so it can't drift from a separately-maintained table — the
+ * cheapest proof the per-book `examDomains` taxonomy is populated + consistent.
+ */
+declare function deriveObjectiveMap<T extends {
+    data: Pick<Question, 'domain' | 'chapter'>;
+}>(entries: readonly T[]): Map<string, Set<string>>;
+/**
+ * Distinct chapter labels across the entries, in numeric-aware order (numeric
+ * chapters before string slugs, each ordered) — the column set for
+ * `<ObjectiveMap>`. Dedupes by label, sorts the underlying chapter values via
+ * the same `chapterOrder` as `sortQuestions`, then labels. A bare `.sort()` on
+ * the labels would put "10" before "2" (the chapter-column sort bug).
+ */
+declare function distinctChaptersSorted<T extends {
+    data: Pick<Question, 'chapter'>;
+}>(entries: readonly T[]): string[];
+
 /**
  * src/styles/built-in.ts — toolkit-shipped Styles, one per BookPreset (v4.0.0).
  *
@@ -421,4 +504,4 @@ type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVe
  */
 declare function defineTips(opts: TipsConfigInput): TipsConfig;
 
-export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, KIND_LABEL, type ResolvedTheoremLabel, Style, THEOREM_KINDS, type TheoremKind, type TheoremLabelProps, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, assertEnumProp, bookScaffoldIntegration, buildGithubUrl, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, originUrlFromGitConfig, parseRepoSlug, researchPortfolioStyle, resolveGithubRepo, theoremLabel, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, KIND_LABEL, Question, type ResolvedTheoremLabel, Style, THEOREM_KINDS, type TheoremKind, type TheoremLabelProps, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, assertEnumProp, assertKnownDomain, bookScaffoldIntegration, buildGithubUrl, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, minimalStyle, originUrlFromGitConfig, parseRepoSlug, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, sortQuestions, theoremLabel, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -358,6 +358,110 @@ var patternsSchema = z.object({
   category: z.enum(patternCategories).optional(),
   convergence_date: z.date().nullable().optional()
 });
+var questionTypes = ["mcq", "free", "cloze"];
+var bloomLevels = [
+  "remember",
+  "understand",
+  "apply",
+  "analyze",
+  "evaluate",
+  "create"
+];
+var questionDifficulties = ["1", "2", "3", "4"];
+var CHAPTER_SLUG = /^[a-z0-9][a-z0-9-]*$/;
+var mcqOptionObject = z.object({
+  id: z.string().min(1),
+  // stable per-option key (e.g. 'a') — anchors + future scoring
+  correct: z.boolean().default(false),
+  text: z.string().optional()
+  // short option prose inline; long ones via body
+}).strict();
+var questionSchema = z.object({
+  // ----- identity -----
+  id: z.string().trim().min(1),
+  // EXPLICIT cross-ref key (#114 appendix / #116 cards); distinct from file-derived entry.id. trim → whitespace-only fails loud.
+  type: z.enum(questionTypes),
+  // ----- placement (every surface keys on these) -----
+  chapter: z.union([z.number().int().min(0).max(99), z.string().regex(CHAPTER_SLUG)]),
+  // number OR a kebab-slug string
+  part: z.union([z.number().int().min(0).max(20), z.string().regex(CHAPTER_SLUG)]).optional(),
+  domain: z.string().trim().min(1),
+  // value validated at route/build (assertKnownDomain), NOT here; trim → whitespace-only fails loud
+  // ----- pedagogy metadata (used-when-present) -----
+  bloom_level: z.enum(bloomLevels).optional(),
+  // #112/#113/#116
+  objective_id: z.string().min(1).optional(),
+  // #117 objective-map rows + #116 cards
+  difficulty: z.enum(questionDifficulties).optional(),
+  // #112 blueprint, #113 routing
+  // ----- type-specific payloads (validated per-type in refineQuestion) -----
+  options: z.array(mcqOptionObject).optional(),
+  // MCQ only
+  answer: z.string().optional(),
+  // free-response model answer (prose)
+  // ----- lifecycle (mirrors chapter schemas) -----
+  draft: z.boolean().default(false),
+  tags: z.array(z.string()).default([])
+}).strict();
+function refineQuestion(q, ctx) {
+  if (q.type === "mcq") {
+    if (q.answer !== void 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["answer"],
+        message: `MCQ "${q.id}": the answer is the option marked correct: true \u2014 remove \`answer\` and put any explanation in a <Rationale> body block.`
+      });
+    }
+    if (!q.options || q.options.length < 2) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["options"],
+        message: `MCQ "${q.id}" needs \u22652 options (got ${q.options?.length ?? 0}).`
+      });
+      return;
+    }
+    const correct = q.options.filter((o) => o.correct).length;
+    if (correct !== 1) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["options"],
+        message: `MCQ "${q.id}" must have EXACTLY ONE option with correct: true (got ${correct}).`
+      });
+    }
+    const ids = q.options.map((o) => o.id);
+    if (new Set(ids).size !== ids.length) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["options"],
+        message: `MCQ "${q.id}" has duplicate option ids (${ids.join(", ")}).`
+      });
+    }
+  } else if (q.type === "free") {
+    if (q.options) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["options"],
+        message: `Free-response "${q.id}" must not define MCQ options.`
+      });
+    }
+    if (!q.answer || q.answer.trim() === "") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["answer"],
+        message: `Free-response "${q.id}" needs an "answer" (model answer) for the appendix.`
+      });
+    }
+  } else if (q.type === "cloze") {
+    if (q.options) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["options"],
+        message: `Cloze "${q.id}" must not define MCQ options.`
+      });
+    }
+  }
+}
+var refinedQuestionSchema = questionSchema.superRefine(refineQuestion);
 
 // src/lib/academic-parts.ts
 var ACADEMIC_PART_NAMES = {
@@ -449,6 +553,8 @@ var academicProfile = defineProfile({
     // v4.3.0 #70: opt-in per book; requires build-tips
     exercises: false,
     // v4.4.0: opt-in per book; requires build-exercises
+    practiceExam: false,
+    // v4.17.0 #112: opt-in per book; requires src/content/questions/
     landing: true
     // v4.5.0: auto-inject minimal root landing; consumers override via src/pages/index.astro
   },
@@ -572,6 +678,8 @@ var toolsProfile = defineProfile({
     // v4.3.0 #70: opt-in per book
     exercises: false,
     // v4.4.0: opt-in per book
+    practiceExam: false,
+    // v4.17.0 #112: opt-in per book; requires src/content/questions/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -657,6 +765,8 @@ var minimalProfile = defineProfile({
     // v4.3.0 #70: opt-in per book
     exercises: false,
     // v4.4.0: opt-in per book
+    practiceExam: false,
+    // v4.17.0 #112: opt-in per book; requires src/content/questions/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -682,6 +792,8 @@ var courseNotesProfile = defineProfile({
     // v4.3.0 #70: opt-in per book
     exercises: false,
     // v4.4.0: opt-in per book
+    practiceExam: false,
+    // v4.17.0 #112: opt-in per book; requires src/content/questions/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -711,6 +823,8 @@ var researchPortfolioProfile = defineProfile({
     // v4.3.0 #70: opt-in per book
     exercises: false,
     // v4.4.0: opt-in per book
+    practiceExam: false,
+    // v4.17.0 #112: opt-in per book; requires src/content/questions/
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
@@ -991,6 +1105,9 @@ var ROUTE_REGISTRY = {
   // v4.4.0: exercises index by chapter. Opt-in via routes.exercises: true;
   // pairs with build-exercises script + <ExerciseSolutions auto /> mode.
   exercises: { pattern: "/exercises", file: "exercises.astro" },
+  // v4.17.0 (Tier 3, #112): static practice question-bank. Opt-in via
+  // routes.practiceExam: true; reads the `questions` collection + examDomains.
+  practiceExam: { pattern: "/practice-exam", file: "practice-exam.astro" },
   // v4.5.0: minimal root landing page. Reads title/description/portfolio/routes
   // from vite.define-injected import.meta.env vars. Default-on per profile;
   // consumers with their own src/pages/index.astro override (file-system route
@@ -1028,7 +1145,11 @@ function bookScaffoldIntegration(opts) {
     seo,
     // v4.15.0 (#109): optional GitHub repo/branch override for CodeRef/CodeBlock.
     githubRepo,
-    githubBranch
+    githubBranch,
+    // v4.16.0 (#96): sibling-book registry for cross-book <BookLink>.
+    siblingBooks,
+    // v4.17.0 (#112): exam-domain taxonomy for the questions collection.
+    examDomains
   } = opts;
   const def = PROFILES[profile];
   const fmNormalized = normalizeFrontmatterConfig(userOverrides.frontmatter);
@@ -1088,7 +1209,9 @@ function bookScaffoldIntegration(opts) {
                   twitterHandle: seo?.twitterHandle ?? null
                 },
                 githubRepo: resolvedGithubRepo,
-                githubBranch: resolvedGithubBranch
+                githubBranch: resolvedGithubBranch,
+                siblingBooks: siblingBooks ?? {},
+                examDomains: examDomains ?? []
               })
             ],
             define: {
@@ -1224,7 +1347,11 @@ async function defineBookConfig(opts) {
       seo: opts.seo ? { ogImage: opts.seo.ogImage, twitterHandle: opts.seo.twitterHandle } : void 0,
       // v4.15.0 (#109): repo/branch override; integration auto-detects when undefined.
       githubRepo: opts.githubRepo,
-      githubBranch: opts.githubBranch
+      githubBranch: opts.githubBranch,
+      // v4.16.0 (#96): cross-book link registry.
+      siblingBooks: opts.siblingBooks,
+      // v4.17.0 (#112): per-book exam-domain taxonomy for the questions collection.
+      examDomains: opts.examDomains
     }),
     ...mergedExtraIntegrations
   ];
@@ -1269,6 +1396,10 @@ async function defineBookConfig(opts) {
     // v4.15.0: strip repo opts so they don't leak into AstroUserConfig.
     githubRepo: _githubRepo,
     githubBranch: _githubBranch,
+    // v4.16.0: strip cross-book registry.
+    siblingBooks: _siblingBooks,
+    // v4.17.0: strip exam-domain taxonomy.
+    examDomains: _examDomains,
     ...rest
   } = opts;
   void _styles;
@@ -1287,6 +1418,8 @@ async function defineBookConfig(opts) {
   void _seo;
   void _githubRepo;
   void _githubBranch;
+  void _siblingBooks;
+  void _examDomains;
   const katexExternals = wantsKatex ? [] : ["remark-math", "rehype-katex", "katex"];
   const restVite = rest.vite ?? {};
   const restSsr = restVite.ssr ?? {};
@@ -1377,6 +1510,84 @@ function assertEnumProp(value, allowed, ctx) {
   );
 }
 
+// src/lib/book-link.ts
+function resolveBookHref(siblingBooks, book, to) {
+  const base = siblingBooks?.[book];
+  if (!base) {
+    const known = siblingBooks ? Object.keys(siblingBooks) : [];
+    throw new Error(
+      `<BookLink book="${book}">: unknown sibling book. Register it in defineBookConfig({ siblingBooks: { "${book}": "https://\u2026" } })` + (known.length ? ` (known: ${known.join(", ")})` : "") + "."
+    );
+  }
+  return `${base.replace(/\/+$/, "")}/${to.replace(/^\/+/, "")}`;
+}
+
+// src/lib/exam-domains.ts
+function assertKnownDomain(examDomains, domain, ctx) {
+  if (!examDomains || !examDomains.includes(domain)) {
+    const known = examDomains ?? [];
+    throw new Error(
+      `question "${ctx.id}": unknown exam domain "${domain}". Register it in defineBookConfig({ examDomains: [${JSON.stringify(domain)}, \u2026] })` + (known.length ? ` (known: ${known.join(", ")})` : " (no examDomains configured)") + "."
+    );
+  }
+  return domain;
+}
+
+// src/lib/questions-derive.ts
+function chapterLabel(chapter) {
+  return String(chapter);
+}
+function chapterOrder(chapter) {
+  return typeof chapter === "number" ? [0, String(chapter).padStart(6, "0")] : [1, chapter];
+}
+function sortQuestions(entries) {
+  return [...entries].sort((a, b) => {
+    const [ar, as] = chapterOrder(a.data.chapter);
+    const [br, bs] = chapterOrder(b.data.chapter);
+    if (ar !== br) return ar - br;
+    if (as !== bs) return as < bs ? -1 : 1;
+    return a.data.id.localeCompare(b.data.id);
+  });
+}
+function groupByDomain(entries) {
+  const out = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const bucket = out.get(e.data.domain) ?? [];
+    bucket.push(e);
+    out.set(e.data.domain, bucket);
+  }
+  return out;
+}
+function groupByChapter(entries) {
+  const out = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const key = chapterLabel(e.data.chapter);
+    const bucket = out.get(key) ?? [];
+    bucket.push(e);
+    out.set(key, bucket);
+  }
+  return out;
+}
+function deriveObjectiveMap(entries) {
+  const out = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const set = out.get(e.data.domain) ?? /* @__PURE__ */ new Set();
+    set.add(chapterLabel(e.data.chapter));
+    out.set(e.data.domain, set);
+  }
+  return out;
+}
+function distinctChaptersSorted(entries) {
+  const byLabel = /* @__PURE__ */ new Map();
+  for (const e of entries) byLabel.set(chapterLabel(e.data.chapter), e.data.chapter);
+  return [...byLabel.values()].sort((a, b) => {
+    const [ar, as] = chapterOrder(a);
+    const [br, bs] = chapterOrder(b);
+    if (ar !== br) return ar - br;
+    return as < bs ? -1 : as > bs ? 1 : 0;
+  }).map(chapterLabel);
+}
+
 // src/styles/built-in.ts
 var academicStyle = defineStyle({
   name: "academic",
@@ -1435,10 +1646,13 @@ export {
   academicParts,
   academicStyle,
   assertEnumProp,
+  assertKnownDomain,
+  bloomLevels,
   bookScaffoldIntegration,
   buildGithubUrl,
   changeKinds,
   changelogSchema,
+  chapterLabel,
   chapterSortKey,
   chapterStatus,
   citationBackstops,
@@ -1450,9 +1664,13 @@ export {
   defineProfile,
   defineStyle,
   defineTips,
+  deriveObjectiveMap,
+  distinctChaptersSorted,
   fallbackChaptersRenderer,
   freshnessLabel,
   getFreshness,
+  groupByChapter,
+  groupByDomain,
   minimalChapterSchema,
   minimalStyle,
   normalizeFrontmatterConfig,
@@ -1462,11 +1680,18 @@ export {
   patternsSchema,
   provenanceObject,
   provenanceSchema,
+  questionDifficulties,
+  questionSchema,
+  questionTypes,
+  refineQuestion,
+  refinedQuestionSchema,
   researchPortfolioChapterSchema,
   researchPortfolioStyle,
+  resolveBookHref,
   resolveGithubRepo,
   resolvePreset,
   resolveProfile,
+  sortQuestions,
   sourceTiers,
   sourceTiersResearch,
   sourcesSchema,