docs(admin): archived items page — the missing-file lifecycle

Fourth admin page. Documents the two-consecutive-scans archive rule,
the history-preserving rationale, ARCHIVE_RETENTION_DAYS (default 90,
0 = manual-purge-only, verified in config.go), and the four actions with
verified semantics: Merge (progress/annotations/collections folded into
the active copy, per-user collisions keep the active copy — mirrors
hash-conflict resolution), Restore (immediate; re-archives if the file
is truly still gone), Delete (item + history, permanent), Purge All
Archived (the clean-slate button, confirm text quoted). Links to
scanning.md for why only library-wide scans archive. Glossary gains
Purge All Archived, Merge, and a scoped generic Delete entry.

docs/admin/archived-items.md

@@ -0,0 +1,53 @@
+<!-- Ground truth: templates/admin_archived.templ (page copy, Merge/
+     Restore/Delete row actions, Purge All Archived, retention sentence),
+     internal/config/config.go (ARCHIVE_RETENTION_DAYS, default 90, 0 =
+     manual purge only), internal/handlers/media.go (MergeArchivedMediaItem
+     — reading progress/annotations/collections merge, per-user collisions
+     keep the active copy), templates/admin_library.templ (entry banner).
+     Re-verify against these when the page changes. -->
+
+# Archived Items
+
+Archived items are books whose files went missing from disk. Bookhoard
+doesn't delete them on the first absence: a library-wide scan that can't
+find a file marks the item missing, and only when the file is still absent
+for **two consecutive scans** does the item move to the archive. Until
+then — or after — the reader's history is preserved, so a file that comes
+back (or a move the scanner detects automatically) restores the item with
+its reading data intact.
+
+You reach this page from the Libraries page, which shows an **Archived
+items** banner with the count whenever anything is archived.
+
+## What the page shows
+
+A table of every archived item: book title and author, the file path that
+went missing, its library, and a status column. When the list is empty you
+get the good news instead: "Nothing is archived or missing. All clear."
+
+## Retention
+
+By default archived items are **permanently deleted after 90 days**
+(configured with the `ARCHIVE_RETENTION_DAYS` environment variable; set it
+to `0` to keep archived items until you purge them by hand). The page
+header states your instance's current rule.
+
+## Actions
+
+| Action | What it actually does |
+| --- | --- |
+| **Merge** (only when a matching active book exists) | Folds this archived copy's reading data — progress, annotations, collections — into the active copy and removes the archived entry. If the same user has reading data on both copies, the active copy's data wins. This is the right choice when the duplicate is a leftover twin and the real book lives on. |
+| **Restore** | Puts the item back into the libraries immediately. If the file is genuinely still gone, the next scan archives it again — useful when you know the file just came back or is about to. |
+| **Delete** | Deletes the item **and its reading history** permanently. No archive, no undo. |
+
+### Purge All Archived
+
+The header button wipes every archived item at once — permanently, reading
+history included (a confirm dialog says exactly that). It exists for the
+"clean slate" moments; per-item **Delete** is the scalpel.
+
+## Related
+
+- [Scanning](scanning.md) — how scans decide what's missing, and why only
+  library-wide scans (shallow or force) archive; a single-folder scan
+  never marks its sibling folders' items missing.

docs/developer/ui-controls.md

@@ -240,6 +240,18 @@ 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: Purge All Archived
+where: Admin → Archived Items → page header
+does: Permanently deletes every archived item and its reading history, after a confirm. The per-item alternative is Delete.
+
+label: Merge
+where: Admin → Archived Items → rows with a matching active book
+does: Folds the archived copy's reading data (progress, annotations, collections) into the active copy and removes the archived entry; per-user collisions keep the active copy's data.
+
+label: Delete
+where: Admin → Archived Items rows, and other admin destructive rows
+does: Permanently removes the item and its reading history — no archive, no undo. Every Delete is confirm-guarded and states the scope.
+
 label: Resume rewind
 where: audio player → player settings; profile settings
 does: Rewinds playback a configured few seconds when you resume.