paperlint 13.6.1 → 14.1.0

package/dist/skills/build-label-page/scripts/label-page-core.d.ts

@@ -1,4 +1,4 @@
-import { type RuleRef } from "./rule-descriptions.ts";
+import { type Described as RuleText, type RuleRef } from "./rule-descriptions.ts";
 export declare class Refusal extends Error {
     readonly exitCode: number;
     constructor(exitCode: number, message: string);
@@ -13,11 +13,14 @@ type Json = null | boolean | number | string | readonly Json[] | {
 type JsonObject = {
     readonly [key: string]: Json;
 };
-declare const PAGE_FIELDS: readonly ["group", "title", "body", "code", "context"];
-type SchemaNode = {
+declare const PAGE_FIELDS: readonly ["group", "title", "body", "code", "context", "file"];
+type SchemaNode = ({
     kind: "string";
     required: boolean;
     pattern?: string;
+} | {
+    kind: "text";
+    required: boolean;
 } | {
     kind: "integer";
     required: boolean;
@@ -40,7 +43,16 @@ type SchemaNode = {
     required: boolean;
     closed: boolean;
     fields: Readonly<Record<string, SchemaNode>>;
+}) & {
+    why?: string;
 };
+/**
+ * THE PAGE KINDS, and the card fields each requires on every item and practice card (#373). A fix to
+ * a card is a field; a kind that needs it makes it required, so a page built without it fails the
+ * schema with the field named instead of shipping the old card.
+ */
+type Kind = "approval" | "witness" | "labels";
+/** The declared schema (`schema` prints it): every field, those a kind requires left optional. */
 export declare const CONFIG_SCHEMA: SchemaNode;
 interface Option {
     readonly value: string;
@@ -58,28 +70,90 @@ interface Question {
 interface Unit {
     readonly id: string;
     readonly text: string;
+    readonly mark: string;
     readonly part: number;
     readonly of: number;
 }
-type Item = {
+interface TextField {
+    readonly label?: string;
+    readonly text: string;
+    readonly style?: string;
+}
+interface CodeLine {
+    readonly n: number;
+    readonly text: string;
+    readonly mark: boolean;
+}
+/** The content blocks (#380), each optional on any kind. */
+interface Blocks {
+    readonly situation?: {
+        readonly summary: string;
+        readonly question: string;
+    };
+    readonly excerpt?: {
+        readonly file?: string;
+        readonly url?: string;
+        readonly lines: readonly CodeLine[];
+        readonly caption?: string;
+        readonly mark_label?: string;
+    };
+    readonly references?: {
+        readonly summary: string;
+        readonly entries: readonly {
+            readonly label?: string;
+            readonly title: string;
+            readonly fields: readonly TextField[];
+            readonly url?: string;
+            readonly url_label?: string;
+        }[];
+    };
+    readonly more?: {
+        readonly summary: string;
+        readonly items: readonly string[];
+        readonly rest?: string;
+    };
+    readonly table?: {
+        readonly summary: string;
+        readonly note?: string;
+        readonly rows: readonly {
+            readonly label: string;
+            readonly value: string;
+            readonly plain?: string;
+            readonly mark?: {
+                readonly tone: string;
+                readonly text: string;
+            };
+        }[];
+    };
+    readonly repeat?: {
+        readonly group: string;
+        readonly index: number;
+        readonly of: number;
+    };
+}
+/** What a card shows, on an item and on a practice item alike. */
+type Card = {
     readonly [F in (typeof PAGE_FIELDS)[number]]?: string;
-} & {
-    readonly source_id: string;
-    readonly group: string;
+} & Blocks & {
     readonly body: string;
     readonly rules?: readonly RuleRef[];
     readonly unit?: Unit;
+    readonly readings?: {
+        readonly a: string;
+        readonly b: string;
+    };
 };
-interface Practice {
-    readonly title?: string;
-    readonly body: string;
-    readonly code?: string;
-    readonly context?: string;
+type Item = Card & {
+    readonly source_id: string;
+    readonly group: string;
+};
+type Practice = Card & {
     readonly expected: Readonly<Record<string, string>>;
     readonly why: string;
-}
+};
 interface Config {
     readonly study: string;
+    readonly kind: Kind;
     readonly title: string;
     readonly intro?: string;
     readonly seed: number;
@@ -90,6 +164,7 @@ interface Config {
     readonly questions: readonly Question[];
     readonly practice: readonly Practice[];
     readonly practice_round?: number;
+    readonly labels?: Readonly<Record<string, string>>;
     readonly items: readonly Item[];
 }
 interface KeyEntry {
@@ -97,8 +172,8 @@ interface KeyEntry {
     readonly group: string;
     readonly on_page: boolean;
 }
-/** Rule → the linter's description, for every rule an item on the page names. */
-type Described = ReadonlyMap<string, string>;
+/** Rule → the linter's description (and a ruff rule's family), for every rule a card names. */
+type Described = ReadonlyMap<string, RuleText>;
 /** Only what the labeller can answer goes on the page, and only that gets an id, in id order. */
 declare function itemsOnPage(cfg: Config, keyPath: string): {
     items: Item[];
@@ -110,6 +185,9 @@ declare function itemsOnPage(cfg: Config, keyPath: string): {
 declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, described: Described): {
     title: string;
     intro: string;
+    labels: {
+        [x: string]: string;
+    };
     groups: {
         id: string;
         label: string;
@@ -123,8 +201,21 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
     questions: readonly Question[];
     practice: {
         round: number;
-        items: readonly (Practice & {
-            readonly id: string;
+        items: ({
+            rules?: never;
+            id: string;
+            expected: Readonly<Record<string, string>>;
+            why: string;
+        } | {
+            rules: {
+                description?: string;
+                family?: string;
+                linter: "eslint" | "ruff";
+                id: string;
+            }[];
+            id: string;
+            expected: Readonly<Record<string, string>>;
+            why: string;
         })[];
     };
     items: ({
@@ -132,9 +223,10 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
         id: string;
     } | {
         rules: {
+            description?: string;
+            family?: string;
             linter: "eslint" | "ruff";
             id: string;
-            description: string;
         }[];
         id: string;
     })[];
@@ -149,6 +241,9 @@ export declare function prepareBuild(configPath: string, outDir: string): {
     payload: {
         title: string;
         intro: string;
+        labels: {
+            [x: string]: string;
+        };
         groups: {
             id: string;
             label: string;
@@ -162,8 +257,21 @@ export declare function prepareBuild(configPath: string, outDir: string): {
         questions: readonly Question[];
         practice: {
             round: number;
-            items: readonly (Practice & {
-                readonly id: string;
+            items: ({
+                rules?: never;
+                id: string;
+                expected: Readonly<Record<string, string>>;
+                why: string;
+            } | {
+                rules: {
+                    description?: string;
+                    family?: string;
+                    linter: "eslint" | "ruff";
+                    id: string;
+                }[];
+                id: string;
+                expected: Readonly<Record<string, string>>;
+                why: string;
             })[];
         };
         items: ({
@@ -171,9 +279,10 @@ export declare function prepareBuild(configPath: string, outDir: string): {
             id: string;
         } | {
             rules: {
+                description?: string;
+                family?: string;
                 linter: "eslint" | "ruff";
                 id: string;
-                description: string;
             }[];
             id: string;
         })[];

package/dist/skills/build-label-page/scripts/label-page-presets.d.ts

@@ -0,0 +1,10 @@
+/** A preset's result: the config in the generic shape, or why it cannot be made. */
+export type Preset = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** The config with its preset applied; a config without `preset` comes back as it was. */
+export declare function applyPreset(raw: unknown): Preset;

package/dist/skills/build-label-page/scripts/rule-descriptions.d.ts

@@ -2,6 +2,11 @@ export interface RuleRef {
     readonly linter: "eslint" | "ruff";
     readonly id: string;
 }
+/** What the linter says a rule does; a ruff rule also names the family it comes from. */
+export interface Described {
+    readonly description: string;
+    readonly family?: string;
+}
 /** A process run to its end: the exit status and what it printed. */
 export type RunProcess = (cmd: string, args: readonly string[]) => {
     readonly status: number | null;
@@ -9,4 +14,4 @@ export type RunProcess = (cmd: string, args: readonly string[]) => {
 };
 export declare const runProcess: RunProcess;
 /** The linter's own one-line description of `ref`, or undefined when it has none. */
-export declare function describeRule(ref: RuleRef, fromDir: string, run?: RunProcess): string | undefined;
+export declare function describeRule(ref: RuleRef, fromDir: string, run?: RunProcess): Described | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "13.6.1",
+  "version": "14.1.0",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",

package/skills/build-label-page/SKILL.md

@@ -4,7 +4,7 @@ description: Build a phone labelling page published as a claude.ai Artifact with
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Artifact, ArtifactData]
 ---
 
-<!-- vigiles:sha256:bd616b2694831fa1 compiled from skills/build-label-page/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:64e09e4a829be441 compiled from skills/build-label-page/SKILL.md.spec.ts -->
 
 # build-label-page — a page the person labels on a phone, and the labels back in the repo
 
@@ -63,8 +63,8 @@ building. In one line each:
    source labels on the page. The generator refuses to build when an item carries a field outside an
    allow-list; a page written by hand checks its items against the same list.
 5. **Ask only what the labeller can answer.** Only the languages and tools they know; one "how well do
-   you know it" question per group, used later as an analysis filter (off on an approval page,
-   `"familiarity": false`: the author has not seen those repositories); "clear-cut or real boundary"
+   you know it" question per group when the study filters on it (`"familiarity": true`; left
+   out, none is asked, as on an approval page, whose author has not seen those repositories); "clear-cut or real boundary"
    is the labeller's judgement, not the designer's.
 6. **Export into the repository right away**, one JSON per page into the study's `data/` with the
    export date, commit it, and record answers given in chat with `source: "chat"`. If the page fails,
@@ -104,7 +104,12 @@ building. In one line each:
    ```
 
    It writes `label-page/page.html` and `label-page/key.json` (the only link from `G001` to the
-   source id; it never goes on the page). Written by hand, the page meets the requirements above.
+   source id; it never goes on the page). `kind` (`approval`, `witness`, `labels`) is required,
+   and each kind requires its card fields on every item and practice card. Any card may also carry
+   the generic content blocks (a code excerpt with a marked line, references, a list, a table), every
+   word on them from `items.json`, with the question right under the excerpt. `"preset":
+   "linter-config-witness"` is a narrow preset for comparing linter configs; the blocks underneath
+   are generic. Written by hand, the page meets the requirements above.
 4. **Read it as the labeller, then look at it.** Read the page text once as a person who knows
    nothing about the source: if anything on it tells the answer, take it out. Read each question as
    someone who did not design the study: can they tell what each answer means from the question, its

package/skills/build-label-page/SKILL.md.spec.ts

@@ -74,8 +74,8 @@ building. In one line each:
    source labels on the page. The generator refuses to build when an item carries a field outside an
    allow-list; a page written by hand checks its items against the same list.
 5. **Ask only what the labeller can answer.** Only the languages and tools they know; one "how well do
-   you know it" question per group, used later as an analysis filter (off on an approval page,
-   \`"familiarity": false\`: the author has not seen those repositories); "clear-cut or real boundary"
+   you know it" question per group when the study filters on it (\`"familiarity": true\`; left
+   out, none is asked, as on an approval page, whose author has not seen those repositories); "clear-cut or real boundary"
    is the labeller's judgement, not the designer's.
 6. **Export into the repository right away**, one JSON per page into the study's \`data/\` with the
    export date, commit it, and record answers given in chat with \`source: "chat"\`. If the page fails,
@@ -115,7 +115,12 @@ building. In one line each:
    \`\`\`
 
    It writes \`label-page/page.html\` and \`label-page/key.json\` (the only link from \`G001\` to the
-   source id; it never goes on the page). Written by hand, the page meets the requirements above.
+   source id; it never goes on the page). \`kind\` (\`approval\`, \`witness\`, \`labels\`) is required,
+   and each kind requires its card fields on every item and practice card. Any card may also carry
+   the generic content blocks (a code excerpt with a marked line, references, a list, a table), every
+   word on them from \`items.json\`, with the question right under the excerpt. \`"preset":
+   "linter-config-witness"\` is a narrow preset for comparing linter configs; the blocks underneath
+   are generic. Written by hand, the page meets the requirements above.
 4. **Read it as the labeller, then look at it.** Read the page text once as a person who knows
    nothing about the source: if anything on it tells the answer, take it out. Read each question as
    someone who did not design the study: can they tell what each answer means from the question, its

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

@@ -21,7 +21,11 @@ with the core's payload. Another page shape would be another template on the sam
 Rules 2 to 5, 7 and the page half of 8 of [`checklist.md`](checklist.md): a filter instead of
 scrolling, complete-item counting, neutral ids in a seeded order, the leak guard (an item field
 outside the allow-list stops the build), save on click with a time, the store-unavailable banner,
-the "How to answer" screen, the practice before the real items, one question per screen. Its look:
+the "How to answer" screen (folded into a toggle once the practice is done), the practice before
+the real items, one question per screen, each card's place (`labels.place`, by default
+"G007 · 7 of 20"), the card just
+answered kept under "Next unanswered" until the next answer (so a mis-tap can be changed), and a
+closing line once every item is complete. Its look:
 one dark palette, one column, answer buttons as full-width rows with space between them, an optional
 icon per answer and never a coloured side stripe, `backticks` and the `code` field shown as code,
 code blocks that show leading and trailing whitespace (a space as ·, a tab as →) and each line's
@@ -33,32 +37,173 @@ 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
   next one; a different seed is refused once a key exists.
-- **`ask_why`** on an option: a prompt. That answer is incomplete, on the page and in the export,
-  until a reason is saved. The reason saves as it is typed (after a pause, and when the page is
-  left), so a labeller who closes the page from inside the box does not leave a drop without its
-  reason; a store echo while typing keeps the box and its focus.
+- **`ask_why`** on an option: a prompt. The page does not write that answer to the store until its
+  reason box holds text: the card says «Not saved yet», and the store keeps what it had. The reason
+  then saves with the answer as it is typed (after a pause, and when the page is left); a store echo
+  while typing keeps the box and its focus. An answer stored without its reason (by an older page,
+  or merged from chat) still counts as incomplete, on the page and in the export.
+
+## Content blocks
+
+Any card may carry these blocks, on any `kind`, and each one is optional. The page knows only the shape of each block. Every label and sentence on it comes from `items.json`, so a code review, a prose check or a configuration study each write their own words. A practice card carries the same blocks as the real cards it rehearses. `scripts/fixtures/blocks-items.json` is a whole page of them: a code review, with no preset.
+
+```jsonc
+{
+  "situation": {
+    "summary": "Reviewer A asked for a change at {line}; reviewer B approved it.",
+    "question": "Does «Every query is parameterised» cover {line}?",
+  },
+  "excerpt": {
+    "file": "app/report.py", // optional; with `url`, the name is a link
+    "url": "https://example.com/app/report.py#L12", // optional
+    "lines": [
+      { "n": 11, "text": "def monthly(month):", "mark": false },
+      {
+        "n": 12,
+        "text": "    rows = db.raw(\"SELECT … m=\" + month)",
+        "mark": true,
+      },
+    ],
+    "caption": "Reviewer A wrote: concatenated SQL.", // optional, under the code
+    "mark_label": "◀ the line in question", // optional; default «◀ this line»
+  },
+  "references": {
+    "summary": "What the guideline says", // the folded block's toggle
+    "entries": [
+      {
+        "label": "Guideline", // optional row label
+        "title": "Security guide `SQL-1`",
+        "fields": [
+          { "text": "Build every query with parameters." },
+          { "label": "Why", "text": "Input becomes part of the query." }, // «Why: …»
+          {
+            "style": "note",
+            "text": "The examples below are the guide's own.",
+          },
+          {
+            "label": "Not like this",
+            "style": "code",
+            "text": "db.raw(\"… id=\" + id)",
+          },
+        ],
+        "url": "https://example.com/guide#sql-1", // optional
+        "url_label": "Security guide", // optional; the link text
+      },
+    ],
+  },
+  "more": {
+    "summary": "3 more lines like this",
+    "items": ["`app/export.py`", "`app/admin.py`"],
+    "rest": "and 1 more", // optional, after the items
+  },
+  "table": {
+    "summary": "What each reviewer wrote",
+    "note": "Reviewer A asked for the change; reviewer B approved.", // optional
+    "rows": [
+      {
+        "label": "A only · Comment",
+        "value": "use parameters", // shown as code
+        "plain": "asks for a parameterised query", // optional
+        "mark": { "tone": "yes", "text": "✓ about this line" }, // optional; tone yes or no
+      },
+    ],
+  },
+  "repeat": { "group": "guide-sql", "index": 1, "of": 2 }, // `group` never reaches the page
+}
+```
+
+- **Order on the card.** The card shows, in this order:
+  1. its place (`labels.place`);
+  2. the body, on a `labels.body` row when that label is set;
+  3. the repeat sentence;
+  4. the older fields (`code`, `unit`, `rules`, `readings`, `file`, `context`);
+  5. the situation's summary;
+  6. the excerpt;
+  7. **the question and its answers**;
+  8. `references`, `more` and `table`, each folded and closed.
+
+  The question therefore sits right under the code it names.
+
+- **`situation`**: `{summary, question}`.
+  - `summary` is one sentence above the excerpt.
+  - `question` replaces the text of the page's first question on this card. Other questions keep their own text.
+  - In either text, `{line}` stands for the excerpt's first marked line. The page writes «line N: », then the line's code as code, without its indent. A code line holding a backtick reads as it is.
+  - `{line}` on a card without an `excerpt` is refused by path.
+- **`excerpt`**: at least one line is marked (`mark: true`). The marked line gets a `▶` in the gutter and `mark_label` after its code, and keeps its background, so it reads as marked even without its colour. A line's `text` may be empty, for a blank line.
+- **`references.entries[].fields`**:
+  - A field without `style` is a paragraph («label: text» when it has a label). A long one shows three lines and a «more».
+  - `style: "code"` is a code block on a `label` row.
+  - `style: "note"` is a quiet line.
+- **`table.rows`**: shown in the order given. Each row shows its `label`, then `value` as code, `plain` under it, and `mark` last.
+- **`repeat`**: shows the sentence `labels.repeat` when `of` is more than 1. `index` must lie between 1 and `of`.
+- **`labels`** sits at page level, and every key in it is optional:
+
+  | key                | what it is                                                      | default                        |
+  | ------------------ | --------------------------------------------------------------- | ------------------------------ |
+  | `place`            | the card's place                                                | `{id} · {n} of {total}`        |
+  | `body`             | a row label for the body                                        | none                           |
+  | `line`             | the label of the `unit` row                                     | `Line`                         |
+  | `line_part`        | the `unit` row's label when the line holds several requirements | `{line} · part {part} of {of}` |
+  | `repeat`           | the repeat sentence                                             | `Card {index} of {of}`         |
+  | `practice_example` | text before each answer's example on a practice button          | empty                          |
+
+- The leak guard reads every string these blocks render, one string at a time.
+
+### Presets: named words for a narrow use
+
+A preset is opt-in. An items file names it with `"preset": "<name>"`. The preset maps its own compact card fields onto the blocks above and supplies `labels`. The file's own `labels` override the preset's. The page and the core know nothing of any preset: each one lives in `scripts/label-page-presets.ts`.
+
+- **`linter-config-witness`** is narrow: two linter configs of one requirement disagree on a line of code. The blocks underneath are generic.
+  - **Input fields on a card:**
+    - `example: {file, url?, lines, message, caught_by}`, which becomes the excerpt, with the caption «The linter says: …».
+    - `rules: [{linter, id, explanation}]`, whose explanation has `source` (`ruff rule`, `eslint docs`, `plugin docs`, `config message` or `none`), plus `what`, `why`, `example_bad`, `example_good` and `url`. These become the references, folded under «What the linter rule does (official docs)».
+    - `more_like_this: {count, files}`, which becomes the list «N more file(s) with the same situation».
+    - `details: {a, b}`: rows of `{key, raw, plain, matches_example}`. They become the table «Settings behind this card», with «A only / B only / A and B» rows.
+  - **Its labels**: «Card {n} of {total}», «Requirement», «Card {index} of {of} for this requirement», and «Example of this answer, about other code: ».
+  - `scripts/fixtures/linter-config-witness-items.json` is a whole page of it.
 
 ## The approval page
 
@@ -89,9 +234,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