@panaversity/ksor 0.0.28 → 0.0.30

package/templates/scaffold/knowledge/what-is-a-ksor.quiz.yaml

@@ -0,0 +1,90 @@
+# A quiz for what-is-a-ksor.md.
+#
+# Every question and every answer states only what its parent document states —
+# a quiz is a way of checking the record, never a second source. Ask your coding
+# agent to write one from a document, and to check each answer back against it.
+#
+# Two habits worth copying. The options are kept close in LENGTH, because if the
+# correct answer is reliably the longest one a reader passes by looking rather
+# than by reading. And the correct answer moves POSITION between questions: a
+# quiz whose answer is usually B is a quiz you can pass without the document.
+# `pnpm check` and `pnpm build` both refuse a quiz where either is true — the
+# first draft of this one was refused for putting four of five answers at B.
+quiz:
+  title: Check yourself
+  description: Five questions on what this record is, and what it is not.
+questions:
+  - question: A spreadsheet and the ledger disagree about a number. Which one is authoritative?
+    options:
+      - Whichever of the two was most recently edited
+      - The spreadsheet, being closer to the daily work
+      - The ledger, because it is the governing copy
+      - Neither, until a person reconciles the two
+    answer: 2
+    explanation: >
+      A system of record is the copy that governs, so the ledger wins by
+      definition rather than by being newer or closer to the work. Recency is
+      not authority: an edit made this morning in a spreadsheet nobody governs
+      is still ungoverned. Reconciliation is something a record makes possible,
+      not a precondition for having an answer at all.
+    source: The opening definition
+
+  - question: What does a KSoR settle that a traditional system of record does not?
+    options:
+      - The state of a business, such as its balances
+      - Which vendor an organization has chosen to use
+      - How much storage the organization is paying for
+      - What the organization knows and how it operates
+    answer: 3
+    explanation: >
+      A traditional system of record settles the state of a business — what is
+      owed, what is owned, what was transacted. A KSoR settles the layer above
+      it: which policies apply, which thresholds are approved, and what a term
+      means inside this organization. Vendor choice and storage cost are
+      consequences of running one, never what it is authoritative for.
+    source: What this record settles
+
+  - question: Why can an ordinary assistant not tell you which of its sentences were checked?
+    options:
+      - It answers from everything it has ever read
+      - It was not given enough context to work with
+      - Its answers are checked, but only in summary
+      - It lacks permission to reveal its own sources
+    answer: 0
+    explanation: >
+      It answers from everything it has ever read, and nothing in that process
+      separates a checked claim from an unchecked one. This is not a context
+      problem and not a permissions problem: more context cannot create a
+      distinction that was never recorded in the first place. The record closes
+      the gap by governing what gets read.
+    source: Why an assistant cannot answer that question
+
+  - question: What problem does a KSoR exist to solve?
+    options:
+      - Storage costs across a growing organization
+      - Scatter, with no authoritative copy to trust
+      - The speed at which an assistant can reply
+      - The difficulty of writing documentation well
+    answer: 1
+    explanation: >
+      The problem is scatter: knowledge spread across wikis, decks, PDFs,
+      prompts and somebody's memory, with no authoritative answer to which of
+      them an agent should trust. Speed and cost are not what the record
+      addresses, and writing well is valuable but does not by itself tell an
+      agent which of two documents governs.
+    source: The problem it solves
+
+  - question: Abstention — answering "not in this corpus" — is best described as what?
+    options:
+      - An error state the record should minimise
+      - A temporary gap, pending the next ingest
+      - A setting an operator turns on when ready
+      - A correct answer the record is meant to give
+    answer: 3
+    explanation: >
+      Abstention is a correct answer, never an error and never a licence to
+      fall back on general model knowledge. A record that answers everything
+      has stopped being a record of anything in particular. It is not a gap
+      waiting to be filled, and while the gate that enforces it is configured
+      deliberately, the honesty it expresses is the product itself.
+    source: What this record settles, and what it does not

package/templates/scaffold/system/site/app/docs/[[...slug]]/page.tsx

@@ -17,8 +17,9 @@ import { showGovernance } from "@/lib/shared";
 import { RecordToc, TocItems } from "@/components/record-toc";
 import { RecordViews } from "@/components/record-views";
 import { Flashcards } from "@/components/flashcards";
+import { Quiz } from "@/components/quiz";
 import { StudyAids } from "@/components/study-aids";
-import { deckFor, summaryFor } from "@/lib/attachments";
+import { deckFor, quizFor, summaryFor } from "@/lib/attachments";
 import { readingMinutes } from "@/lib/reading-time";
 
 export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
@@ -32,6 +33,7 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
   const summary = summaryFor(page.path);
   const Summary = summary?.body ?? null;
   const deck = deckFor(page.path);
+  const quiz = quizFor(page.path);
   // Counted at BUILD time from the document's own markdown, so the figure is in
   // the shipped HTML for a reader with a failed bundle, a crawler and an agent
   // alike. The predecessor measured the rendered DOM after paint, which put it
@@ -157,7 +159,12 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
           region, so the quiz that will sit beside the deck is a child here and
           not a new argument about where it goes. Renders nothing at all when
           the document has no study aids. */}
-        <StudyAids>{deck === null ? null : <Flashcards deck={deck} />}</StudyAids>
+        {/* Recall first, then the check on it — and each renders only if the
+            document carries one, so a page with just a quiz shows just a quiz. */}
+        <StudyAids>
+          {deck === null ? null : <Flashcards deck={deck} />}
+          {quiz === null ? null : <Quiz quiz={quiz} />}
+        </StudyAids>
         {/* A folder's index page lists what the folder holds. Without it the
           page ended at its own sentence and the documents below it were
           reachable only from the sidebar (research/site-design.md F5). Empty

package/templates/scaffold/system/site/app/global.css

@@ -274,6 +274,74 @@ html > body[data-scroll-locked] {
   --ksor-caution: #e0906e;
 }
 
+/* Right and wrong, for the quiz — the ONE place this record spends green and
+   red, and it earns them: a reader checking an answer is asking a true/false
+   question, and the accent cannot say "this is correct" while also saying
+   "this is what you picked". Both are needed at once when you answer wrongly.
+
+   Colour is never the only channel: the correct option also carries a check,
+   the wrong one a cross, and the line above states the verdict in words — so
+   the pair works for a reader who cannot distinguish them. Declared as
+   light/dark pairs on the root for the reason `--ksor-caution` above records.
+
+   Deliberately NOT `--ksor-caution`, which means "the record withdrew this".
+   A wrong answer is not a governance state. */
+:root {
+  --ksor-correct: #1a7f4b;
+  --ksor-incorrect: #b3261e;
+}
+
+.dark {
+  --ksor-correct: #6edaa0;
+  --ksor-incorrect: #f2897f;
+}
+
+/* The three states an answered question shows at once. Written as CLASSES,
+   the way `.ksor-caution` below is, rather than as Tailwind arbitrary values:
+   `border-[color:var(--x)]` emits a rule whose `var()` did not resolve on the
+   element in a real build (found live 2026-08-23 — the class was present, the
+   rule was in the stylesheet, the token computed correctly on the element, and
+   the border still painted the default hairline). A plain class has none of
+   that ambiguity, and this file is already where this record's semantic colour
+   lives. */
+.ksor-answer-correct {
+  border-color: var(--ksor-correct);
+  background-color: color-mix(in oklab, var(--ksor-correct) 10%, transparent);
+}
+
+.ksor-answer-wrong {
+  border-color: var(--ksor-incorrect);
+  background-color: color-mix(in oklab, var(--ksor-incorrect) 10%, transparent);
+}
+
+/* "This is the one you picked" — kept in the accent, and kept SEPARATE from
+   right/wrong, because after a wrong answer a reader needs all three facts. */
+.ksor-answer-mine {
+  outline: 2px solid var(--color-fd-primary);
+  outline-offset: 1px;
+}
+
+.ksor-answer-correct-text {
+  color: var(--ksor-correct);
+}
+
+.ksor-answer-wrong-text {
+  color: var(--ksor-incorrect);
+}
+
+.dark .ksor-answer-correct,
+.dark .ksor-answer-wrong {
+  background-color: color-mix(in oklab, currentColor 0%, transparent);
+}
+
+.dark .ksor-answer-correct {
+  background-color: color-mix(in oklab, var(--ksor-correct) 14%, transparent);
+}
+
+.dark .ksor-answer-wrong {
+  background-color: color-mix(in oklab, var(--ksor-incorrect) 14%, transparent);
+}
+
 .ksor-caution {
   border-color: color-mix(in oklab, var(--ksor-caution) 32%, transparent);
   border-left-color: var(--ksor-caution);

package/templates/scaffold/system/site/components/quiz.tsx

@@ -0,0 +1,321 @@
+"use client";
+
+import { Check, RotateCcw, X } from "lucide-react";
+import { useCallback, useEffect, useMemo, useState, type ReactElement } from "react";
+
+import { StudyAidHeader } from "@/components/study-aids";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent } from "@/components/ui/card";
+import { Progress } from "@/components/ui/progress";
+import type { QuizEntry, QuizQuestion } from "@/lib/attachments";
+import { hasMoreRounds, roundOf } from "@/lib/quiz-round";
+
+/**
+ * Taking a quiz on the document you just read.
+ *
+ * The interaction model is the predecessor's and is the good part of it:
+ * answer, see IMMEDIATELY whether you were right, and read the explanation
+ * before moving on. Its own usage guide is explicit that this teaches through
+ * the mistake, which has more effect than a score revealed at the end — so the
+ * explanation is the point of the component and the score is a footnote.
+ *
+ * What is deliberately absent is everything the predecessor's `GatedQuiz`
+ * wrapper added: a sign-in gate, an XP modal, and a POST of the score to a
+ * progress API. The site is a static export with no backend, and decision 7
+ * fixes it as preview and review rather than an editor. A score here is the
+ * reader's, stays in their browser, and is sent nowhere.
+ */
+
+const STORAGE_VERSION = 1;
+
+interface Persisted {
+  readonly version: number;
+  /** questionHash -> the option index this reader chose. */
+  readonly answers: Record<string, number>;
+}
+
+function storageKey(quizPath: string): string {
+  return `ksor:quiz:${quizPath}`;
+}
+
+function readPersisted(quizPath: string): Record<string, number> {
+  try {
+    const raw = window.localStorage.getItem(storageKey(quizPath));
+    if (raw === null) return {};
+    const record = JSON.parse(raw) as Persisted;
+    // A version bump discards rather than migrates: the only thing lost is
+    // which options a reader clicked, and guessing at an old shape is how a
+    // reader ends up with someone else's answers against their questions.
+    if (record.version !== STORAGE_VERSION) return {};
+    return record.answers ?? {};
+  } catch {
+    // A private window, cleared site data, or storage disabled entirely. An
+    // unanswered quiz is a correct starting state, so this is not an error.
+    return {};
+  }
+}
+
+function writePersisted(quizPath: string, answers: Record<string, number>): void {
+  try {
+    window.localStorage.setItem(
+      storageKey(quizPath),
+      JSON.stringify({ version: STORAGE_VERSION, answers } satisfies Persisted),
+    );
+  } catch {
+    // Storage is a convenience here, never the record. Losing it costs the
+    // reader their place and nothing else.
+  }
+}
+
+/** The letter an author and a reader both use for an option index. */
+function letterOf(index: number): string {
+  return String.fromCharCode(65 + index);
+}
+
+export function Quiz({ quiz }: { quiz: QuizEntry }): ReactElement {
+  const size = quiz.questionsPerRound;
+  const banked = quiz.questions.length;
+  const canRedraw = hasMoreRounds(banked, size);
+
+  // Round zero is the authored order, chosen on the server AND the client so
+  // the first paint matches: `roundOf` returns the bank untouched when it fits
+  // in one round, and for a larger bank the shuffle happens only after mount
+  // (see the effect below). Sampling during render would differ between the
+  // server HTML and the first client render and would hydrate mismatched.
+  const [round, setRound] = useState<readonly QuizQuestion[]>(() =>
+    roundOf(quiz.questions, size, () => 0),
+  );
+  const [answers, setAnswers] = useState<Record<string, number>>({});
+  const [hydrated, setHydrated] = useState(false);
+  const [index, setIndex] = useState(0);
+  const [done, setDone] = useState(false);
+
+  useEffect(() => {
+    setAnswers(readPersisted(quiz.path));
+    if (canRedraw) setRound(roundOf(quiz.questions, size, Math.random));
+    setHydrated(true);
+  }, [quiz.path, quiz.questions, size, canRedraw]);
+
+  const current = round[index];
+  const chosen = current === undefined ? undefined : answers[current.hash];
+  const answered = chosen !== undefined;
+
+  const answeredCount = useMemo(
+    () => round.filter((q) => answers[q.hash] !== undefined).length,
+    [round, answers],
+  );
+  const correctCount = useMemo(
+    () => round.filter((q) => answers[q.hash] === q.answer).length,
+    [round, answers],
+  );
+
+  const choose = useCallback(
+    (option: number) => {
+      if (current === undefined || answers[current.hash] !== undefined) return;
+      const next = { ...answers, [current.hash]: option };
+      setAnswers(next);
+      writePersisted(quiz.path, next);
+    },
+    [answers, current, quiz.path],
+  );
+
+  const newRound = useCallback(() => {
+    setRound(roundOf(quiz.questions, size, Math.random));
+    setAnswers({});
+    writePersisted(quiz.path, {});
+    setIndex(0);
+    setDone(false);
+  }, [quiz.questions, size, quiz.path]);
+
+  const retry = useCallback(() => {
+    setAnswers({});
+    writePersisted(quiz.path, {});
+    setIndex(0);
+    setDone(false);
+  }, [quiz.path]);
+
+  if (current === undefined) return <></>;
+
+  if (done) {
+    return (
+      <section aria-label="Quiz results">
+        <StudyAidHeader title={quiz.title} description={quiz.description} />
+        <Card className="mx-auto max-w-2xl">
+          <CardContent className="flex flex-col items-center gap-6 py-12 text-center">
+            <p className="font-(family-name:--font-display) text-5xl font-semibold tabular-nums text-fd-foreground">
+              {correctCount}
+              <span className="text-fd-muted-foreground">/{round.length}</span>
+            </p>
+            <p className="max-w-sm text-sm text-fd-muted-foreground">
+              {/* No pass mark, deliberately: this checks understanding of a
+                  document, it does not certify anybody. */}
+              Answers are kept in this browser only.
+            </p>
+            <div className="flex flex-wrap justify-center gap-3">
+              <Button variant="outline" onClick={() => setIndex(0)}>
+                Review answers
+              </Button>
+              {canRedraw ? (
+                <Button onClick={newRound}>
+                  <RotateCcw aria-hidden className="size-4" />
+                  Another round
+                </Button>
+              ) : (
+                <Button onClick={retry}>
+                  <RotateCcw aria-hidden className="size-4" />
+                  Start again
+                </Button>
+              )}
+            </div>
+          </CardContent>
+        </Card>
+      </section>
+    );
+  }
+
+  return (
+    <section aria-label="Quiz">
+      <StudyAidHeader title={quiz.title} description={quiz.description} />
+
+      <div className="mx-auto max-w-2xl">
+        <div className="mb-4 flex items-baseline justify-between gap-4">
+          <p className="font-mono text-xs tracking-wide text-fd-muted-foreground uppercase">
+            Question {index + 1} / {round.length}
+            {canRedraw ? <span> · drawn from {banked}</span> : null}
+          </p>
+          <p className="font-mono text-xs tabular-nums text-fd-muted-foreground">
+            {answeredCount} answered
+          </p>
+        </div>
+        <Progress value={(answeredCount / round.length) * 100} className="mb-8 h-1" />
+
+        <Card>
+          <CardContent className="flex flex-col gap-6 py-8">
+            <h3 className="text-lg leading-snug font-medium text-balance text-fd-foreground">
+              {current.question}
+            </h3>
+
+            <ul className="flex flex-col gap-2">
+              {current.options.map((option, i) => {
+                const isAnswer = i === current.answer;
+                const isChoice = i === chosen;
+                // Three things have to be legible at once after a wrong
+                // answer, and they are three different facts: which option is
+                // RIGHT (green), which one is WRONG (red), and which one YOU
+                // picked (the accent ring). The accent alone cannot carry two
+                // of those, which is what it was doing — the correct option
+                // wore the same colour as a selection, so choosing wrongly
+                // looked like the page had answered for you.
+                //
+                // Colour is never the only channel: the check and cross icons
+                // and the verdict line below say the same thing in shape and
+                // in words.
+                //
+                // Plain CSS classes, not Tailwind arbitrary values: a
+                // `border-[color:var(--x)]` utility did not paint in a real
+                // build even with the rule in the stylesheet and the token
+                // resolving on the element. `app/global.css` is where this
+                // record's semantic colour already lives.
+                const tone = !answered
+                  ? "border-fd-border hover:border-fd-primary/60 hover:bg-fd-accent"
+                  : isAnswer
+                    ? "ksor-answer-correct"
+                    : isChoice
+                      ? "ksor-answer-wrong"
+                      : "border-fd-border opacity-60";
+                // Your own pick keeps the accent, whether it was right or
+                // wrong, so "what I chose" is never in doubt.
+                const mine = answered && isChoice ? " ksor-answer-mine" : "";
+                return (
+                  <li key={option}>
+                    <button
+                      type="button"
+                      disabled={answered}
+                      onClick={() => choose(i)}
+                      aria-pressed={isChoice}
+                      className={`flex w-full items-start gap-3 rounded-lg border px-4 py-3 text-left text-sm transition-colors motion-safe:duration-150 ${tone}${mine} ${answered ? "cursor-default" : "cursor-pointer"}`}
+                    >
+                      <span className="mt-px font-mono text-xs text-fd-muted-foreground">
+                        {letterOf(i)}
+                      </span>
+                      <span className="flex-1 text-fd-foreground">{option}</span>
+                      {answered && isAnswer ? (
+                        <Check
+                          aria-label="correct answer"
+                          className="ksor-answer-correct-text size-4 shrink-0"
+                        />
+                      ) : null}
+                      {answered && isChoice && !isAnswer ? (
+                        <X
+                          aria-label="your answer, which is wrong"
+                          className="ksor-answer-wrong-text size-4 shrink-0"
+                        />
+                      ) : null}
+                    </button>
+                  </li>
+                );
+              })}
+            </ul>
+
+            {answered ? (
+              <div
+                // Announced, because the whole value of the immediate-feedback
+                // model is this text, and a reader using a screen reader gets
+                // it only if the region says it changed.
+                role="status"
+                className="motion-safe:animate-in motion-safe:fade-in flex flex-col gap-3 border-t border-fd-border pt-5 text-sm"
+              >
+                <p className="font-mono text-xs tracking-wide uppercase">
+                  {chosen === current.answer ? (
+                    <span className="ksor-answer-correct-text">Correct</span>
+                  ) : (
+                    <span className="ksor-answer-wrong-text">
+                      Not quite — the answer is {letterOf(current.answer)}
+                    </span>
+                  )}
+                </p>
+                <p className="leading-relaxed text-fd-muted-foreground">{current.explanation}</p>
+                {current.source === undefined ? null : (
+                  // "In the document", never "Source": a citation in this
+                  // product carries a generation, and an attachment has no id
+                  // to pin — calling this a source would sell provenance that
+                  // is not here (spec §3).
+                  <p className="font-mono text-xs text-fd-muted-foreground">
+                    In the document: {current.source}
+                  </p>
+                )}
+              </div>
+            ) : null}
+          </CardContent>
+        </Card>
+
+        <div className="mt-6 flex items-center justify-between gap-4">
+          <Button
+            variant="ghost"
+            disabled={index === 0}
+            onClick={() => setIndex((i) => Math.max(0, i - 1))}
+          >
+            Back
+          </Button>
+          {index === round.length - 1 ? (
+            <Button disabled={!answered} onClick={() => setDone(true)}>
+              Finish
+            </Button>
+          ) : (
+            <Button disabled={!answered} onClick={() => setIndex((i) => i + 1)}>
+              Next
+            </Button>
+          )}
+        </div>
+
+        {/* Rendered only once the reader's own answers are in, so the server
+            HTML never claims a state this reader is not in. */}
+        {hydrated && answeredCount > 0 && !done ? (
+          <p className="mt-4 text-center font-mono text-xs text-fd-muted-foreground">
+            {correctCount} of {answeredCount} correct so far
+          </p>
+        ) : null}
+      </div>
+    </section>
+  );
+}

package/templates/scaffold/system/site/components/study-aids.tsx

@@ -4,7 +4,7 @@ import type { ReactElement, ReactNode } from "react";
  * The end-of-document region: what a reader DOES with a document once they
  * have read it.
  *
- * The deck lives here, and the quiz will sit beside it. Deliberately not a tab:
+ * The deck and the quiz live here, in that order. Deliberately not a tab:
  * a study aid is used AFTER the document, and a tab would hide the document
  * while you used it. Deliberately one region rather than each aid finding its
  * own spot on the page, so a second aid is a child here and not a new layout

package/templates/scaffold/system/site/lib/attachment-rule.ts

@@ -21,6 +21,7 @@ export const ATTACHMENT_SUFFIXES = [
   { suffix: ".summary.md", kind: "summary" },
   { suffix: ".summary.mdx", kind: "summary" },
   { suffix: ".flashcards.yaml", kind: "deck" },
+  { suffix: ".quiz.yaml", kind: "quiz" },
 ] as const;
 
 export type AttachmentKind = (typeof ATTACHMENT_SUFFIXES)[number]["kind"];
@@ -37,6 +38,8 @@ export const ATTACHMENT_NEAR_MISSES = [
   { suffix: ".flashcards.yml", want: ".flashcards.yaml" },
   { suffix: ".flashcards.json", want: ".flashcards.yaml" },
   { suffix: ".summary.markdown", want: ".summary.md" },
+  { suffix: ".quiz.yml", want: ".quiz.yaml" },
+  { suffix: ".quiz.json", want: ".quiz.yaml" },
 ] as const;
 
 /**
@@ -102,6 +105,7 @@ export function nearMissOf(
 export const ATTACHMENT_CASES = [
   { name: "returns.summary.md", kind: "summary", parent: "returns.md" },
   { name: "returns.flashcards.yaml", kind: "deck", parent: "returns.md" },
+  { name: "returns.quiz.yaml", kind: "quiz", parent: "returns.md" },
   { name: "index.summary.md", kind: "summary", parent: "index.md" },
   // A stem containing dots keeps every one of them: the parent is the same
   // name with the attachment suffix removed, never "up to the first dot".
@@ -110,15 +114,18 @@ export const ATTACHMENT_CASES = [
   { name: "returns.md", kind: null, parent: null },
   { name: "summary.md", kind: null, parent: null },
   { name: "flashcards.yaml", kind: null, parent: null },
+  { name: "quiz.yaml", kind: null, parent: null },
   { name: "my-summary.md", kind: null, parent: null },
   // A dotfile with no stem attaches to nothing — refused as an attachment so
   // it is refused as an unexpected file instead, which is the honest error.
   { name: ".summary.md", kind: null, parent: null },
   { name: ".flashcards.yaml", kind: null, parent: null },
+  { name: ".quiz.yaml", kind: null, parent: null },
   // Case matters: the record already refuses two names differing only in case,
   // so an uppercase suffix is a different file, not the same rule.
   { name: "returns.SUMMARY.md", kind: null, parent: null },
   // Not attachments — near misses, which get their own refusal.
   { name: "returns.flashcards.yml", kind: null, parent: null },
   { name: "returns.flashcards.json", kind: null, parent: null },
+  { name: "returns.quiz.yml", kind: null, parent: null },
 ] as const;

package/templates/scaffold/system/site/lib/attachments.ts

@@ -1,8 +1,11 @@
-import { decks, summaries } from "collections/server";
+import { decks, quizzes, summaries } from "collections/server";
 
 import { ATTACHMENT_SUFFIXES } from "./attachment-rule";
 import { cardHash, type Card, type Deck } from "./deck";
 import { newCard, type CardSchedule } from "./srs";
+import { type Question, type Quiz } from "./quiz";
+import { DEFAULT_QUESTIONS_PER_ROUND } from "./quiz-round";
+import { questionHash } from "./identity";
 
 /**
  * Finding a document's study attachments.
@@ -83,9 +86,44 @@ export function deckFor(documentPath: string): DeckEntry | null {
   };
 }
 
-/** True when a document has either attachment — the presence gate for the UI. */
+/** One question as the quiz UI consumes it: authored text plus its identity. */
+export interface QuizQuestion extends Question {
+  /** Identity: a hash of the question's own text, so an edit resets only this one. */
+  readonly hash: string;
+}
+
+export interface QuizEntry {
+  readonly title: string;
+  readonly description?: string;
+  readonly questionsPerRound: number;
+  readonly questions: readonly QuizQuestion[];
+  /** The record-relative path — the quiz's identity, used to key saved answers. */
+  readonly path: string;
+}
+
+/** The quiz for a document, or null when it has none. */
+export function quizFor(documentPath: string): QuizEntry | null {
+  const wanted = attachmentPath(documentPath, ".quiz.yaml");
+  const hit = quizzes.find((entry) => entry.info.path === wanted);
+  if (hit === undefined) return null;
+
+  const parsed = hit as unknown as Quiz & { readonly info: { readonly path: string } };
+  return {
+    title: parsed.quiz.title,
+    description: parsed.quiz.description,
+    questionsPerRound: parsed.quiz.questionsPerRound ?? DEFAULT_QUESTIONS_PER_ROUND,
+    path: parsed.info.path,
+    questions: parsed.questions.map((q) => ({ ...q, hash: questionHash(q) })),
+  };
+}
+
+/** True when a document has ANY attachment — the presence gate for the UI. */
 export function hasAttachments(documentPath: string): boolean {
-  return summaryFor(documentPath) !== null || deckFor(documentPath) !== null;
+  return (
+    summaryFor(documentPath) !== null ||
+    deckFor(documentPath) !== null ||
+    quizFor(documentPath) !== null
+  );
 }
 
 /**

package/templates/scaffold/system/site/lib/deck.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+import { textHash } from "./identity";
+
 /**
  * The shape of a `<doc>.flashcards.yaml` deck.
  *
@@ -44,16 +46,5 @@ export type Card = z.infer<typeof CardSchema>;
  * and rewording it should not throw away a learner's history with the card.
  */
 export function cardHash(card: Card): string {
-  // NUL as the separator, written as an escape rather than embedded: a raw
-  // NUL in the source makes git treat this file as binary. It has to be a
-  // separator of some kind — without one, front "ab"/back "c" hashes the same
-  // as front "a"/back "bc" — and NUL is the one character authored card text
-  // cannot contain.
-  const text = `${card.front}\u0000${card.back}`;
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < text.length; i += 1) {
-    hash ^= text.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193) >>> 0;
-  }
-  return hash.toString(16).padStart(8, "0");
+  return textHash([card.front, card.back]);
 }