From ecb6a7385a022819f6306f9fb438be6c9a2a38c9 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 2 Nov 2026 14:10:16 -0500 Subject: [PATCH] =?UTF-8?q?docs(admin):=20archived=20items=20page=20?= =?UTF-8?q?=E2=80=94=20the=20missing-file=20lifecycle?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 53 +++++++++++++++++++++++++++++++++++ docs/developer/ui-controls.md | 12 ++++++++ 2 files changed, 65 insertions(+) create mode 100644 docs/admin/archived-items.md diff --git a/docs/admin/archived-items.md b/docs/admin/archived-items.md new file mode 100644 index 00000000..dbc88b73 --- /dev/null +++ b/docs/admin/archived-items.md @@ -0,0 +1,53 @@ + + +# 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. diff --git a/docs/developer/ui-controls.md b/docs/developer/ui-controls.md index 29922f10..c41cb48f 100644 --- a/docs/developer/ui-controls.md +++ b/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.