From 88e3de606c0cb7b3e4ad0e56a7a8b4059e402102 Mon Sep 17 00:00:00 2001
From: John O'Keefe <git@linuxhg.com>
Date: Mon, 2 Nov 2026 14:09:34 -0500
Subject: [PATCH] =?UTF-8?q?docs(admin):=20processing=20issues=20page=20?=
 =?UTF-8?q?=E2=80=94=20per-library=20scan-failure=20ledger?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Third admin page. Documents the severity stat cards (errors/warnings/
info, cards only appear when non-zero), the per-issue card fields, and
the three actions with their real semantics: Retry (per-item scanner
re-run — success closes the issue, failure surfaces the real error),
Retry all (sequential queue with done/total progress, deliberately not
a library-wide scan), Dismiss (warnings/info only, confirm-guarded;
errors cannot be dismissed). Links to scanning.md for the retry-vs-
library-scan distinction. Glossary gains Retry, Retry all, Dismiss.
---
 docs/admin/library-processing-issues.md | 61 +++++++++++++++++++++++++
 docs/developer/ui-controls.md           | 12 +++++
 2 files changed, 73 insertions(+)
 create mode 100644 docs/admin/library-processing-issues.md

diff --git a/docs/admin/library-processing-issues.md b/docs/admin/library-processing-issues.md
new file mode 100644
index 00000000..e1e0a5ad
--- /dev/null
+++ b/docs/admin/library-processing-issues.md
@@ -0,0 +1,61 @@
+<!-- Ground truth: templates/admin_processing_issues.templ (stats cards,
+     Retry all queue, per-issue Retry/Dismiss, severity badges),
+     internal/handlers/processing_issues.go (RetryProcessingIssue — success
+     closes the issue, failure returns the real error; resolve path),
+     internal/router/library.go (issue routes), the deliberately-not-a-
+     library-rescan design comment in the template. Re-verify against these
+     when the page changes. -->
+
+# Processing Issues
+
+Processing Issues is each library's ledger of items the scanner could not
+fully process — a corrupt file, an unsupported format, metadata that
+wouldn't parse. It is per-library: you reach it from that library's panel
+on the Libraries page (the link only appears when the library has issues).
+
+## What's on the page
+
+Three count cards — **Errors**, **Warnings**, **Info** — show how many
+open issues sit at each severity (a card only appears when that severity
+has issues). Below them, one card per issue showing:
+
+- the item's **title** and a plain-language **description** of what went
+  wrong
+- **Type**, **Format**, **File** (full path), and **Library** type
+- a severity badge: red for errors, amber for warnings, neutral for info
+
+## Fixing an issue
+
+### Retry
+
+Runs that one item back through the scanner. This is a per-item scan —
+the item's file is re-read and re-extracted exactly like a book-page
+[Rescan](scanning.md), not a pass over the library. If it succeeds, the
+issue closes itself; if it fails again, the page shows the *real* error,
+so you know why it still fails instead of staring at a stale complaint.
+
+### Retry all
+
+Queues every issue currently on the page and works through them **one at
+a time** — the button shows progress as "done / total" while the queue
+drains. This is deliberately not a whole-library scan: fixing a handful of
+bad files never re-reads the good ones. Per-issue **Retry** buttons are
+disabled while the queue is running.
+
+When the queue finishes, the page refreshes itself from the server —
+closed issues disappear, still-failing ones stay with fresh error text.
+
+### Dismiss
+
+Closes an issue without re-processing — for warnings and info items you've
+looked at and judged fine (a confirm dialog guards the click). **Errors
+cannot be dismissed**: they must be fixed and successfully retried. The
+Dismiss button simply doesn't exist on an error card.
+
+## How issues get here and leave
+
+The scanner creates an issue whenever it fails to process an item during a
+scan. Issues leave the page three ways: a successful **Retry** (or any
+later scan that processes the item cleanly), a **Dismiss** you chose for a
+warning or info item, or the file's problem being fixed on disk and the
+next scan handling the item cleanly.
diff --git a/docs/developer/ui-controls.md b/docs/developer/ui-controls.md
index a5415f75..29922f10 100644
--- a/docs/developer/ui-controls.md
+++ b/docs/developer/ui-controls.md
@@ -228,6 +228,18 @@ label: Scan this folder
 where: Admin → Libraries → a library's panel → a folder row
 does: Shallow-scans only that folder's subtree — unchanged files are skipped, and items in the library's other folders are never marked missing by a partial scan.
 
+label: Retry
+where: Admin → Libraries → a library's Processing Issues page → an issue card
+does: Re-runs that one item through the scanner (a per-item scan, not a library pass). Success closes the issue; failure shows the real error.
+
+label: Retry all
+where: Admin → Libraries → a library's Processing Issues page → beside the severity cards
+does: Queues every issue on the page and re-runs them one at a time, showing done/total progress. Deliberately not a whole-library scan.
+
+label: Dismiss
+where: Admin → Libraries → Processing Issues → warning and info cards only
+does: Closes the issue without re-processing, after a confirm. Error-severity issues cannot be dismissed.
+
 label: Resume rewind
 where: audio player → player settings; profile settings
 does: Rewinds playback a configured few seconds when you resume.