Fetcher

DESIGN.md

@@ -136,11 +136,20 @@ Question object (fields per the upstream README):
 | `picture_question` | Optional. Figure shown with the question stem.            |
 | `picture_a`..`_d`  | Optional. Per-choice figures.                             |
 
-The `picture_*` fields, when present, contain a filename (e.g.
-`AB404_q.svg`) that resolves into `svgs/`. Convention observed in the
-archive: `<number>_q.svg` for the question figure, `<number>_a.svg` ..
-`<number>_d.svg` for per-answer figures. A small number of entries also
-ship a `.png` next to the `.svg`.
+The `picture_*` fields, when present, contain a **basename without
+extension** (e.g. `AB404_q`, not `AB404_q.svg`). The consumer picks
+the extension. Convention observed in the archive:
+
+- `<number>_q` for the question figure (file `<number>_q.svg`),
+- `<number>_a` .. `<number>_d` for per-answer figures.
+
+Files live under `svgs/`. A small number of entries ship a `.png`
+alongside the `.svg` (display-problem fallback). Consumers should
+prefer `.svg` and fall back to `.png` by stem.
+
+This stem-only convention is why the soft picture-reference check
+matches stems, not full filenames; matching the literal value
+against directory listings would mark every reference missing.
 
 ### Important consumer-side conventions