Add explanations

This commit is contained in:
2026-05-22 16:17:05 +02:00
parent 0d635a8587
commit 27988780cf
7 changed files with 933 additions and 18 deletions
+23
View File
@@ -632,6 +632,22 @@ byte-identical sha256 on each `.apkg`. Verified during review.
the card background. We inject a white `<rect>` as the first
painted element when packaging the SVG into the `.apkg`. The
on-disk extracted files are left untouched.
- **Explanations layer (optional).** `amateurfunk_anki.py` loads
`explanations.json` (CLI: `--explanations`) and, for any
question number found there, appends an English explanation
block to the back of the card. The block is styled distinctly
(serif italic body, sans-serif metadata, top border) and shows
a small "low confidence" badge when the entry's `confidence`
field is below `LOW_CONFIDENCE_THRESHOLD` (= 7). `revision` and
the raw `confidence` number are editorial-only and never
displayed. A missing file is treated as an empty database; a
malformed entry is a hard `AnkiBuildError`. The editorial
contract (schema, sourcing, agent workflows) lives in
`EXPLANATIONS.md`; this file documents only the wiring on the
build side. Note-GUID stability across explanation edits: the
GUID is keyed on `category.slug:number`, not on field content,
so adding/editing an entry updates the existing Anki note on
re-import rather than producing a duplicate.
### Testing focus
@@ -667,6 +683,13 @@ the embedded SQLite, and check structural invariants.
- Deterministic build: two consecutive builds against the same
catalog with a fixed `--epoch` produce byte-identical `.apkg`
files.
- Explanations layer: a present entry produces a styled
explanation block on the back card; a missing entry leaves the
card unchanged; `confidence < 7` surfaces the "low confidence"
badge; URL sources render as `<a>`, citation sources render as
escaped text; a missing `explanations.json` is silently empty;
a malformed entry (bad type, out-of-range confidence, missing
field) raises `AnkiBuildError`.
### What we deliberately do NOT do in Stage 2