paperlint 13.6.0 → 14.0.0

package/skills/build-label-page/references/checklist.md

@@ -81,11 +81,11 @@ the text of an allowed field says.
 
 - Restrict the items to the languages and tools the labeller knows (`labeller_knows`). Items of
   other groups are not put on the page and get no id.
-- Add one question per group, "how well do you know this language / tool" (well / somewhat / not
-  really). It is an analysis filter: the study can report the labels with and without the groups
-  the labeller does not know well. An approval page asks none (`"familiarity": false` in
-  `items.json`): its question is about a drawn unit, not about repositories the author has seen,
-  and an answer to "how well do you know the projects of this group" there means nothing.
+- When the study filters on it, ask one question per group, "how well do you know this language /
+  tool" (well / somewhat / not really), with `"familiarity": true` in `items.json`: the study can
+  then report the labels with and without the groups the labeller does not know well. Left out, no
+  page asks it: on an approval page the question is about a drawn unit, not about repositories the
+  author has seen, and "how well do you know the projects of this group" there means nothing.
 - The per-item judgement "clear-cut or a real boundary case" is the labeller's. The study design
   does not decide it in advance and does not pre-fill it.
 
@@ -94,7 +94,7 @@ answer is the only way to find it afterwards. And a boundary case is boundary be
 person hesitates; a designer who tags it in advance has measured the design, not the item.
 
 **Check.** The build prints how many items were left out; the export has a familiarity value for
-every group, or the page was built with `"familiarity": false` and the export has no groups.
+every group, or the page was built without `"familiarity": true` and the export has no groups.
 
 ## 6. Export into the repository right away
 

package/skills/build-label-page/references/closed-choice-generator.md

@@ -33,24 +33,45 @@ length.
   required `example`: a real case of the study, in a line, that takes that answer. `icon` (an
   emoji) is optional. Two labels that read the same, or two equal values, stop the build.
 - **`practice`**: 3 or more real cases whose answer you are sure of, each with `expected` (one answer
-  per question) and a one-line `why`. Never an item that is also on the page to be labelled.
+  per question) and a one-line `why`. Never an item that is also on the page to be labelled. A
+  practice card carries the same fields as the real cards it rehearses (`rules`, `unit`,
+  `readings`, `file`).
 - **`practice_round`**: raise it after rewording a question; the practice reopens and the answers of
   the earlier round are kept but not counted.
 - **`items`**: `source_id` (the study's own, never shown), `group`, `body`, and optionally `title`,
-  `code`, `context`, `rules`, `unit`. Nothing else: the allow-list is fixed in the generator, and a field outside it
-  is taken out of the item, not added to the list to make a build pass.
+  `code`, `context`, `rules`, `unit`, `readings`, `file`. Nothing else: the allow-list is fixed in
+  the generator, and a field outside it is taken out of the item, not added to the list to make a
+  build pass.
+- **`kind`** (required): what the page asks, and so which card fields every item and practice card
+  must carry. A card without one fails the schema, naming the field and why the kind needs it:
+
+  | kind       | the labeller decides                                 | required on every card                             |
+  | ---------- | ---------------------------------------------------- | -------------------------------------------------- |
+  | `approval` | keep or drop a drawn requirement                     | `unit` (the line, the requirement marked), `rules` |
+  | `witness`  | why two readings of a requirement disagree on a file | `rules`, `readings`, `file`                        |
+  | `labels`   | a gold label, a blind review                         | nothing beyond the item                            |
+
+  Nothing reads `context`: it stays free text. A rule, a line or two readings written there show
+  none of what their fields show, so on an `approval` or `witness` page they go in the fields.
+
 - **`rules`**: `[{linter, id}]` (`linter` is `eslint` or `ruff`) on an item read as a linter rule.
-  The card shows "Rule ruff TID253: Checks for module-level imports that should instead be imported
-  lazily…", the description taken at build time from the linter itself: `ruff rule <id>`'s "What it
-  does" paragraph, or the ESLint rule's `meta.docs.description` from the ESLint and plugins
-  installed where `items.json` is. The build refuses a rule the linter cannot describe; a
+  The card's "Rule" row shows "ruff `TID253` (flake8-tidy-imports): Checks for module-level
+  imports that should instead be imported lazily…", taken at build time from the linter itself:
+  `ruff rule <id>`'s "What it does" paragraph and family, or the ESLint rule's
+  `meta.docs.description` from the ESLint and plugins installed where `items.json` is (a plugin
+  rule's own name may hold a slash: `n/no-unsupported-features/node-builtins`). The build refuses a rule the linter cannot describe; a
   description is never typed into `items.json`.
-- **`unit`**: `{id, text, part, of}` on an item that is one requirement of a line holding several
-  ("TypeScript only (no JavaScript); top-level await is allowed" is two). Each requirement is its
-  own item with its own question, and its card shows "From the line (requirement 1 of 2):" and the
-  whole line beneath, so the labeller judges one requirement at a time and sees where it came from.
-  The build refuses a line whose parts do not add up (one missing, repeated, a different `of`, or
-  split across groups), naming the item. `id` names one occurrence of the line (a file and line
+- **`unit`**: `{id, text, mark, part, of}` on an item drawn from a source line: the whole line,
+  the requirement's own words in it (`mark`, shown highlighted), and which requirement of the line
+  it is ("TypeScript only (no JavaScript); top-level await is allowed" is two). The card's "Line"
+  row shows the line with the mark, and "part 1 of 2" when the line holds several. A drawn sample
+  may hold one part of a line and not the others; the build refuses a `mark` that is not in the
+  line, and parts of one line that disagree (another text or `of`, a part repeated, split across
+  groups), naming the item.
+- **`readings`**: `{a, b}` on an item that compares two readings of one requirement: two rows,
+  "Reading A" on a solid accent rule and "Reading B" on a dashed one, in the same place on every
+  card. **`file`**: the witness file (a path, a link, what each reading did with it), on its own
+  "File" row. `id` names one occurrence of the line (a file and line
   number, say) and is never shown: two files holding the same words are two lines, each judged in
   full. Splitting the line is the study's job, before the page.
 - **`seed`**: fixes the order. Rebuilding with the same seed keeps every id, and a new item gets the
@@ -89,9 +110,10 @@ drop, the drop carrying `ask_why`.
 }
 ```
 
-The page sets `"familiarity": false`: the author is judging drawn units, not repositories they
-have seen, so the per-group "how well do you know it" question is left out (and a
-`familiarity_question` beside it is refused).
+The page sets `"kind": "approval"`, so every card carries its `unit` and `rules`, and leaves
+`familiarity` out: the author is judging drawn units, not repositories they have
+seen, so no per-group "how well do you know it" question is asked. Only a page that sets
+`"familiarity": true` asks it (and a `familiarity_question` without it is refused).
 
 The items are the drawn units verbatim, in a language the author reads. Units in other languages
 are taken out before the draw, as a population rule the study's `plan.json` states ("English-language

package/skills/build-label-page/scripts/label-page-browser.test.ts

@@ -4,8 +4,13 @@
  * cannot show: focus, typing, and a page that is left without the box ever losing focus.
  */
 import assert from "node:assert/strict";
-import { chromium, type Page } from "playwright-core";
-import { test } from "vitest";
+import {
+  type Browser,
+  chromium,
+  type Locator,
+  type Page,
+} from "playwright-core";
+import { afterAll, test } from "vitest";
 import { z } from "zod";
 import { chromiumPath } from "../../../test/chromium.ts";
 import {
@@ -66,6 +71,20 @@ async function reasonStored(page: Page, text: string): Promise<void> {
   assert.equal(await storedReason(page), text);
 }
 
+/**
+ * One Chromium for the whole file, each test in a context of its own (`newPage` opens one): a launch
+ * per test cost about 5 s apiece on the macOS runner, and the file's wall time grew with every test.
+ */
+let launched: Browser | undefined;
+const sharedBrowser = async (): Promise<Browser> =>
+  (launched ??= await chromium.launch({
+    executablePath: chromiumPath(),
+    args: ["--no-sandbox"],
+  }));
+afterAll(async () => {
+  await launched?.close();
+});
+
 /** A browser test launches Chromium and types: far above vitest's 5 s default on a slow runner. */
 const BROWSER_TEST_MS = 60_000;
 
@@ -76,12 +95,9 @@ async function onApprovalPage(
   filter: "all" | "next" = "all",
 ): Promise<void> {
   const { page: html } = build(setup(name, approval()));
-  const browser = await chromium.launch({
-    executablePath: chromiumPath(),
-    args: ["--no-sandbox"],
-  });
+  const browser = await sharedBrowser();
+  const page = await browser.newPage();
   try {
-    const page = await browser.newPage();
     await page.addInitScript(STORE(PRACTICE_DONE, echoMs));
     await page.goto("about:blank");
     await page.setContent(html, { waitUntil: "domcontentloaded" });
@@ -90,7 +106,7 @@ async function onApprovalPage(
     await page.getByRole("button", { name: /Drop/ }).first().click();
     await steps(page);
   } finally {
-    await browser.close();
+    await page.context().close();
   }
 }
 
@@ -163,12 +179,9 @@ test(
   "a Keep needs no reason and writes none: the page stays quiet",
   async () => {
     const { page: html } = build(setup("browser-keep", approval()));
-    const browser = await chromium.launch({
-      executablePath: chromiumPath(),
-      args: ["--no-sandbox"],
-    });
+    const browser = await sharedBrowser();
+    const page = await browser.newPage();
     try {
-      const page = await browser.newPage();
       await page.addInitScript(STORE(PRACTICE_DONE, 20));
       await page.goto("about:blank");
       await page.setContent(html, { waitUntil: "domcontentloaded" });
@@ -180,7 +193,89 @@ test(
         [{}],
       );
     } finally {
-      await browser.close();
+      await page.context().close();
+    }
+  },
+  BROWSER_TEST_MS,
+);
+
+/** A two-reading card with a long URL and compact JSON: what pushed the page sideways on a phone. */
+const URL_LONG = `https://github.com/a/b/blob/${"0".repeat(40)}/src/a/long/path/to/witness.ts`;
+const WITNESS = {
+  source_id: "s1",
+  group: "python",
+  body: "Warn for unused variables, except those prefixed with `_`",
+  unit: {
+    id: "L",
+    text: "Warn for unused variables",
+    mark: "unused",
+    part: 1,
+    of: 1,
+  },
+  rules: [{ linter: "eslint", id: "no-console" }],
+  readings: {
+    a: `[{"argsIgnorePattern":"^_","varsIgnorePattern":"^_","caughtErrors":"all"}]`,
+    b: "[]",
+  },
+  file: URL_LONG,
+  context: URL_LONG,
+};
+
+/** Where the line, the rule, reading A, reading B and the question sit on a card, top to bottom. */
+const blocksOf = async (card: Locator) =>
+  Promise.all(
+    [
+      ".quote",
+      ".row:has(.lbl:text-is('Rule'))",
+      ".reading.a",
+      ".reading.b",
+      ".ask",
+    ].map(async (sel) => card.locator(sel).first().boundingBox()),
+  );
+
+test(
+  "🔴 at phone width the card reads by position: line, rule, reading A above reading B, then the question; nothing pushes the page sideways",
+  async () => {
+    const { page: html } = build(
+      setup("browser-layout", approval({ items: [WITNESS] })),
+    );
+    const page = await (
+      await sharedBrowser()
+    ).newPage({ viewport: { width: 400, height: 900 } });
+    try {
+      await page.addInitScript(STORE(PRACTICE_DONE, 20));
+      await page.setContent(html, { waitUntil: "domcontentloaded" });
+      const card = page.locator("article.item").last();
+      const boxes = await blocksOf(card);
+      const [line, rule, a, b, ask] = boxes;
+      assert.ok(line && rule && a && b && ask, "every block is on the card");
+      // Guards: each block below the one before, A and B in one column, a gap before the question.
+      assert.deepEqual(
+        boxes
+          .slice(1)
+          .map(
+            (x, i) =>
+              (x?.y ?? 0) >= (boxes[i]?.y ?? 0) + (boxes[i]?.height ?? 0),
+          ),
+        [true, true, true, true],
+      );
+      assert.equal(a.x, b.x);
+      assert.ok(ask.y - (b.y + b.height) >= 16, "space before the question");
+      assert.deepEqual(
+        await card
+          .locator(".reading")
+          .evaluateAll((els) =>
+            els.map((e) => getComputedStyle(e).borderLeftStyle),
+          ),
+        ["solid", "dashed"],
+      );
+      // Guards: a long URL or compact JSON wraps; the page itself never scrolls sideways.
+      assert.equal(
+        await page.evaluate(() => document.documentElement.scrollWidth),
+        400,
+      );
+    } finally {
+      await page.context().close();
     }
   },
   BROWSER_TEST_MS,

package/skills/build-label-page/scripts/label-page-core.js

@@ -8,7 +8,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { z } from "zod";
-import { describeRule } from "./rule-descriptions.js";
+import { describeRule, } from "./rule-descriptions.js";
 // ── refusals and output ───────────────────────────────────────────────────────────────────────
 export class Refusal extends Error {
     exitCode;
@@ -88,18 +88,22 @@ const readJson = (path) => {
 // stops the build: a blind page fails by what leaked in, and a field nobody listed is exactly the
 // one nobody thought of. A NEW FIELD IS ADDED HERE ON PURPOSE, after asking "does this tell the
 // labeller what the answer is, or where the item came from?" — never to make a build pass.
-const PAGE_FIELDS = ["group", "title", "body", "code", "context"];
+// prettier-ignore
+const PAGE_FIELDS = ["group", "title", "body", "code", "context", "file"];
 const PRIVATE_FIELDS = ["source_id"];
 // The linter rules an item names ("read as ruff `TID253`"): the page shows each with the linter's
 // own description, looked up at build time (rule-descriptions.ts), never typed into items.json.
 const RULES_FIELD = "rules";
-// One requirement of a line that holds several: the whole line and which part this item is. Shown on
-// the card beneath the item; the line is text the labeller may read, like `context`.
+// The source line an item was drawn from, with its requirement marked (`mark`, words of the line)
+// and which part of the line it is. Shown on the card; the line is text the labeller may read.
 const UNIT_FIELD = "unit";
+// Two readings of one requirement, shown as rows A and B (#374).
+const READINGS_FIELD = "readings";
 const ALLOWED_FIELDS = [
     ...PAGE_FIELDS,
     RULES_FIELD,
     UNIT_FIELD,
+    READINGS_FIELD,
     ...PRIVATE_FIELDS,
 ];
 const FAMILIARITY = [
@@ -128,9 +132,14 @@ const RESERVED_NAMES = [
 const NAME_PATTERN = `(?!(?:${RESERVED_NAMES.join("|")})$)[A-Za-z0-9_-]+`;
 const SOURCES = ["page", "chat"];
 const SOURCES_SHOWN = `(${SOURCES.map(quoted).join(", ")})`;
-const string = (required = true, pattern) => pattern === undefined
+const string = (required = true, pattern, why) => pattern === undefined
     ? { kind: "string", required }
-    : { kind: "string", required, pattern };
+    : {
+        kind: "string",
+        required,
+        pattern,
+        ...(why === undefined ? {} : { why }),
+    };
 const integer = (required = true) => ({
     kind: "integer",
     required,
@@ -153,13 +162,56 @@ const mapping = (values, keyPattern, min = 0) => ({
     values,
 });
 const obj = (fields, closed = true, required = true) => ({ kind: "object", required, closed, fields });
-const ITEM_SCHEMA = obj({
-    source_id: string(),
-    ...Object.fromEntries(PAGE_FIELDS.map((f) => [f, string(f === "group" || f === "body")])),
-    [RULES_FIELD]: array(obj({ linter: string(true, "eslint|ruff"), id: string() }), false, 1),
+// What an item and a practice item both may carry beyond text: a practice card looks like the real
+// cards it rehearses. Each is optional here; a page's `kind` makes some of them required (KINDS).
+const CARD_FIELDS = {
+    [RULES_FIELD]: array(obj({
+        linter: string(true, "eslint|ruff", "eslint or ruff"),
+        id: string(),
+    }), false, 1),
     [UNIT_FIELD]: obj(
     // `id` names one occurrence of the line (two files may hold the same words): never shown.
-    { id: string(), text: string(), part: integer(), of: integer() }, true, false),
+    {
+        id: string(),
+        text: string(),
+        mark: string(),
+        part: integer(),
+        of: integer(),
+    }, true, false),
+    [READINGS_FIELD]: obj({ a: string(), b: string() }, true, false),
+    file: string(false),
+};
+const KINDS = {
+    // keep or drop a drawn requirement: the line it came from, marked, and the rule read for it
+    approval: {
+        [UNIT_FIELD]: "an approval card shows the line its requirement was drawn from, the requirement marked",
+        [RULES_FIELD]: "an approval card shows the rule read for it, with the linter's own description",
+    },
+    // why two readings of one requirement disagree on a file
+    witness: {
+        [RULES_FIELD]: "a witness card shows the rule both readings configure, with the linter's description",
+        [READINGS_FIELD]: "a witness card shows the two readings, one row each",
+        file: "a witness card shows the file the readings disagree on, on its own row",
+    },
+    // gold labels, a blind review: the card is the item, nothing more is required
+    labels: {},
+};
+const KIND_NAMES = Object.keys(KINDS).join(", ");
+/** The card fields of a page of `kind`: those it needs, required and saying why. */
+const cardFields = (kind) => Object.fromEntries(Object.entries(CARD_FIELDS).map(([name, node]) => {
+    const why = KINDS[kind][name];
+    return [
+        name,
+        why === undefined ? node : { ...node, required: true, why },
+    ];
+}));
+const itemSchema = (kind) => obj({
+    source_id: string(),
+    ...Object.fromEntries(PAGE_FIELDS.filter((f) => f !== "file").map((f) => [
+        f,
+        string(f === "group" || f === "body"),
+    ])),
+    ...cardFields(kind),
 }, false);
 // `icon` (an emoji) tells the buttons apart at a glance. No coloured side stripe on a button: it
 // reads as decoration, not meaning (the build-label-page look test refuses one).
@@ -171,11 +223,12 @@ const OPTION_SCHEMA = obj({
     icon: string(false),
     ask_why: string(false),
 });
-const PRACTICE_SCHEMA = obj({
-    ...Object.fromEntries(PAGE_FIELDS.filter((f) => f !== "group").map((f) => [
+const practiceSchema = (kind) => obj({
+    ...Object.fromEntries(PAGE_FIELDS.filter((f) => f !== "group" && f !== "file").map((f) => [
         f,
         string(f === "body"),
     ])),
+    ...cardFields(kind),
     expected: mapping(string(), NAME_PATTERN, 1),
     why: string(),
 });
@@ -186,22 +239,25 @@ const QUESTION_SCHEMA = obj({
     short: string(false),
     options: array(OPTION_SCHEMA, true, 2),
 });
-export const CONFIG_SCHEMA = obj({
+const configSchema = (kind) => obj({
     study: string(true, NAME_PATTERN), // becomes a file name
+    kind: string(true, Object.keys(KINDS).join("|"), `one of ${KIND_NAMES}`),
     title: string(),
     intro: string(false),
     seed: integer(),
     groups: mapping(string(), NAME_PATTERN, 1), // ids become store document ids
     labeller_knows: array(string(true, NAME_PATTERN), false),
-    // false: no "how well do you know {group}" question (an approval page: the author has never seen
-    // these repositories, so its answer means nothing). Left out, every group is asked (rule 5).
+    // true: a "how well do you know {group}" question per group, for a study that filters on it
+    // (rule 5). Left out, none is asked: an approval page's author has never seen the repositories.
     familiarity: boolean(false),
     familiarity_question: string(false),
     questions: array(QUESTION_SCHEMA, true, 1),
-    practice: array(PRACTICE_SCHEMA, true, MIN_PRACTICE),
+    practice: array(practiceSchema(kind), true, MIN_PRACTICE),
     practice_round: integer(false),
-    items: array(ITEM_SCHEMA, true, 1),
+    items: array(itemSchema(kind), true, 1),
 });
+/** The declared schema (`schema` prints it): every field, those a kind requires left optional. */
+export const CONFIG_SCHEMA = configSchema("labels");
 // ── checking a value against the schema ──────────────────────────────────────────────────────
 const at = (path, name) => path ? `${path}.${name}` : name;
 const fullMatch = (pattern, s) => new RegExp(`^(?:${pattern})$`, "u").test(s);
@@ -211,7 +267,7 @@ function checkString(value, node, where) {
         fail(`${where}: must be a non-empty string, got ${repr(value)}`);
     }
     else if (node.pattern !== undefined && !fullMatch(node.pattern, value)) {
-        fail(`${where}: ${repr(value)} must be ${ID_RULE}`);
+        fail(`${where}: ${repr(value)} must be ${node.why ?? ID_RULE}`);
     }
 }
 const checkCount = (n, min, where) => {
@@ -243,7 +299,7 @@ function checkObject(value, node, path, where) {
         if (has(value, name))
             checkValue(value[name] ?? null, sub, at(path, name));
         else if (sub.required)
-            fail(`${at(path, name)}: is required and missing`);
+            fail(`${at(path, name)}: is required and missing${sub.why === undefined ? "" : ` — ${sub.why}`}`);
     }
     const unknown = Object.keys(value).find((name) => !has(node.fields, name));
     if (node.closed && unknown !== undefined) {
@@ -298,7 +354,7 @@ const allowedValues = (questions, asksFamiliarity) => ({
     // Empty when the page asks no familiarity: the export then expects no group document at all.
     familiarity: asksFamiliarity ? FAMILIARITY.map((o) => o.value) : [],
 });
-const asksFamiliarity = (cfg) => cfg.familiarity !== false;
+const asksFamiliarity = (cfg) => cfg.familiarity === true;
 /** Two values that read the same once case and surrounding space are gone. */
 const readsAs = (s) => s.trim().toLowerCase();
 /** The first entry whose reading repeats an earlier one, with the index of that earlier one. */
@@ -363,7 +419,7 @@ function checkPractice(cfg) {
 function checkConfig(cfg) {
     checkGroups(cfg);
     if (!asksFamiliarity(cfg) && cfg.familiarity_question !== undefined) {
-        fail(`familiarity_question: ${repr(cfg.familiarity_question)} is never asked, because \`familiarity\` is false — remove one of the two`);
+        fail(`familiarity_question: ${repr(cfg.familiarity_question)} is never asked, because \`familiarity\` is not true — remove it, or set "familiarity": true`);
     }
     cfg.questions.forEach((q, qn) => {
         checkQuestion(q, qn, cfg.questions.slice(0, qn).map((x) => x.id));
@@ -388,25 +444,36 @@ function checkPart({ item, unit, n }, parts) {
         fail(`${at}.unit.text: ${repr(unit.text)}, but items[${String(first.n)}] of line ${repr(unit.id)} says ${repr(first.unit.text)}`);
     if (unit.of !== first.unit.of)
         fail(`${at}.unit.of: ${String(unit.of)}, but items[${String(first.n)}].unit.of says ${String(first.unit.of)} for the same line`);
-    if (unit.part < 1 || unit.part > unit.of)
-        fail(`${at}.unit.part: ${String(unit.part)} is not between 1 and ${String(unit.of)}`);
     const earlier = parts.find((p) => p.n < n && p.unit.part === unit.part);
     if (earlier !== undefined)
         fail(`${at}.unit.part: ${String(unit.part)} repeats items[${String(earlier.n)}].unit.part`);
     if (item.group !== first.item.group)
         fail(`${at}.group: ${repr(item.group)}, but items[${String(first.n)}] of the same line is in ${repr(first.item.group)}`);
 }
+/** One unit on its own: its part in range, and its mark the requirement's words in the line. */
+function checkUnit(unit, at) {
+    if (unit === undefined)
+        return;
+    if (unit.part < 1 || unit.part > unit.of)
+        fail(`${at}.unit.part: ${String(unit.part)} is not between 1 and ${String(unit.of)}`);
+    if (!unit.text.includes(unit.mark))
+        fail(`${at}.unit.mark: ${repr(unit.mark)} is not in the line ${repr(unit.text)} — mark the requirement with the line's own words`);
+}
 function checkUnits(cfg) {
-    for (const [line, parts] of linesOf(cfg)) {
+    cardsOf(cfg).forEach(([at, card]) => {
+        checkUnit(card.unit, at);
+    });
+    for (const parts of linesOf(cfg).values()) {
         parts.forEach((p) => {
             checkPart(p, parts);
         });
-        const [first] = parts;
-        const missing = Array.from({ length: first.unit.of }, (_, k) => k + 1).find((k) => !parts.some((p) => p.unit.part === k));
-        if (missing !== undefined)
-            fail(`items[${String(first.n)}].unit: part ${String(missing)} of ${String(first.unit.of)} of line ${repr(line)} is not among the items`);
     }
 }
+/** Every card of the config, items then practice, by path. */
+const cardsOf = (cfg) => [
+    ...cfg.items.map((i, n) => [`items[${String(n)}]`, i]),
+    ...cfg.practice.map((p, n) => [`practice[${String(n)}]`, p]),
+];
 function checkItemFields(cfg) {
     const sids = [];
     cfg.items.forEach((item, n) => {
@@ -427,6 +494,7 @@ function checkItemFields(cfg) {
 const visibleTexts = (item) => [
     ...PAGE_FIELDS.map((f) => [f, item[f] ?? ""]),
     [UNIT_FIELD, item.unit?.text ?? ""],
+    [READINGS_FIELD, `${item.readings?.a ?? ""} ${item.readings?.b ?? ""}`],
 ];
 const escapeRegExp = (s) => s.replace(/[\\^$.*+?()[\]{}|/]/g, "\\$&");
 /**
@@ -491,28 +559,30 @@ const shownFields = (item) => ({
         : {
             [UNIT_FIELD]: {
                 text: item.unit.text,
+                mark: item.unit.mark,
                 part: item.unit.part,
                 of: item.unit.of,
             },
         }),
+    ...(item.readings === undefined ? {} : { [READINGS_FIELD]: item.readings }),
 });
 const ruleKey = (r) => `${r.linter} ${r.id}`;
 /** Ask the linter for every rule named; refuse, by path, a rule it cannot describe. */
 function describeRules(cfg, fromDir) {
-    return new Map(cfg.items.flatMap((item, n) => (item.rules ?? []).map((r, k) => {
+    return new Map(cardsOf(cfg).flatMap(([at, card]) => (card.rules ?? []).map((r, k) => {
         const text = describeRule(r, fromDir);
         return text === undefined
-            ? fail(`items[${String(n)}].rules[${String(k)}]: ${r.linter} ${repr(r.id)} has no description from the linter (${r.linter === "ruff" ? "`ruff rule` does not know it, or ruff is not on PATH" : "not a rule of the ESLint, or of a plugin, installed where items.json is"}) — check the id`)
+            ? fail(`${at}.rules[${String(k)}]: ${r.linter} ${repr(r.id)} has no description from the linter (${r.linter === "ruff" ? "`ruff rule` does not know it, or ruff is not on PATH" : "not a rule of the ESLint, or of a plugin, installed where items.json is"}) — check the id`)
             : [ruleKey(r), text];
     })));
 }
-const rulesShown = (item, described) => item.rules === undefined
+const rulesShown = (card, described) => card.rules === undefined
     ? {}
     : {
-        [RULES_FIELD]: item.rules.map((r) => ({
+        [RULES_FIELD]: card.rules.map((r) => ({
             linter: r.linter,
             id: r.id,
-            description: String(described.get(ruleKey(r))),
+            ...described.get(ruleKey(r)),
         })),
     };
 /** Only what the labeller can answer goes on the page, and only that gets an id, in id order. */
@@ -528,6 +598,14 @@ function itemsOnPage(cfg, keyPath) {
     return { items: sorted, ids, entries, idOf };
 }
 const practiceRound = (cfg) => cfg.practice_round ?? 1;
+/** The practice as its cards show it, with the answers the page checks against. */
+const practiceShown = (cfg, described) => practiceOf(cfg).map((p) => ({
+    id: p.id,
+    expected: p.expected,
+    why: p.why,
+    ...shownFields(p),
+    ...rulesShown(p, described),
+}));
 /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
 function payloadOf(cfg, page, described) {
     const used = Object.keys(cfg.groups).filter((g) => page.items.some((i) => i.group === g));
@@ -541,7 +619,10 @@ function payloadOf(cfg, page, described) {
         familiarity: asksFamiliarity(cfg) ? FAMILIARITY : [],
         allowed: allowedValues(cfg.questions, asksFamiliarity(cfg)),
         questions: cfg.questions,
-        practice: { round: practiceRound(cfg), items: practiceOf(cfg) },
+        practice: {
+            round: practiceRound(cfg),
+            items: practiceShown(cfg, described),
+        },
         items: page.items.map((i) => ({
             id: page.idOf(i),
             ...shownFields(i),
@@ -610,6 +691,8 @@ function keyOf(cfg, page, earlier) {
 export function prepareBuild(configPath, outDir) {
     const cfg = readJson(configPath);
     assertConfig(cfg);
+    // Once its `kind` is known to be one, the fields that kind needs on every card.
+    checkValue(cfg, configSchema(cfg.kind), "");
     checkConfig(cfg);
     checkItemFields(cfg);
     checkUnits(cfg);
@@ -774,7 +857,7 @@ function checkNoFamiliarity(dump, allowed) {
     const groups = isObject(dump["groups"]) ? dump["groups"] : {};
     const [first] = Object.keys(groups).sort(byText);
     if (allowed.familiarity.length === 0 && first !== undefined) {
-        fail(`groups/${first}: familiarity is off for this page (items.json \`familiarity: false\`), so no group document is expected — take it out of the dump`);
+        fail(`groups/${first}: familiarity is off for this page (items.json does not set \`"familiarity": true\`), so no group document is expected — take it out of the dump`);
     }
 }
 /** The key's `allowed` lists, or a refusal naming a key made by an older build. */