docs(admin): libraries page — the definition surface, with backlinks

Fifth admin page and the section's hub. Documents library creation (name/description/type — type fixed at creation, verified in the edit modal), the card's Force Rescan + Manage controls, and the full panel: folders (add via Browse or manual path, shallow per-folder scan, removal-unregisters-only semantics verified in DeleteLibraryFolder — files and items untouched, archive lifecycle governs the rest; podcast roots refuse hand scans), User Access visibility checkboxes (default- allow, DB-enforced), the processing-issues link, and Delete Library's exact destructive scope (records + reading data gone, files on disk untouched). Ends with the at-a-glance scan table linking scanning.md. Adds the Libraries backlinks to the processing-issues and archived pages. Glossary gains Create Library, Manage, Edit Details, Delete Library, View Archived, Purge Archived Now, Browse, User Access.
2026-11-02 14:11:25 -05:00
1 parent ecb6a7385a
commit 3e55ddd88a
@@ -16,8 +16,8 @@ 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.
+You reach this page from the [Libraries](libraries.md) page, which shows
+an **Archived items** banner with the count whenever anything is archived.

 ## What the page shows

@@ -1,32 +1,108 @@
+<!-- Ground truth: templates/admin_library.templ (page, modals, panel,
+     delete-library warnings), internal/router/admin_library.go (create/
+     edit/delete, folders, browse, visibility endpoints), internal/router/
+     library.go (per-library scan route), internal/services/library_service.go
+     (DeleteLibraryFolder removes the mapping only; SetLibraryVisibility),
+     templates/utils.go (hxValsFolderScan), templates/admin_archived.templ.
+     Re-verify against these when the page changes. -->
+
 # Libraries

-## Adding Library Folders
+The Libraries page is where a Bookhoard instance is defined: what
+libraries exist, which folders on the server they read from, who can see
+them, and how they get scanned. Everything here is admin-only — regular
+users just see the result.

-When creating or managing a library, you can add folders containing your media files (ebooks, comics, manga).
+## Creating a library

-### Using the Folder Browser
+**Create Library** opens a modal with three fields:

-The admin library page includes a folder browser to help you select folders on the server:
+- **Library Name** (required) — what users see in their sidebar
+- **Description** (optional)
+- **Library Type** (required) — book, comic, audiobook, podcast; the type
+  drives how the scanner parses files and how the reader presents them

-1. Open the **Administration** panel in the sidebar (admins only) and go to **Libraries**
-2. Click a library in the list to expand its panel
-3. Find the **Folders** section
-4. Click **Browse** next to the folder path input — this opens the **Browse Folders** dialog
-5. Navigate through the server's filesystem
-6. Select a folder; it fills the path input, then click **Add**
+A library with no folders can't scan — add at least one folder (below)
+before expecting anything to appear in it.

-### Security
+## The library card

- The folder browser only shows directories (not files)
- Path traversal is protected (cannot access parent directories with `..`)
- Only admin users can browse the filesystem
+Each library renders as a card: name, description, a type chip, a folder
+count, and two controls:

-### Manual Entry
+- **Force Rescan** — starts a force scan of this one library: every file
+  re-read and re-extracted, hashes recomputed. This is the heavy,
+  thorough pass ([Scanning](scanning.md) explains force vs. shallow and
+  when each is worth it). If a scan is already running for the library,
+  the click tells you instead of stacking a second one.
+- **Manage** — opens the library's panel, where everything else lives.

-Alternatively, you can manually type the full server path if you know it:
+## The library panel

-```
-/home/user/books
-/media/external/ebooks
-/var/lib/manga
-```
+### Folders
+
+Folders are the server-side directories the scanner walks. Each one shows
+its path with two icon actions: **Scan this folder** (a shallow scan
+scoped to just that folder's subtree — the quick "I just dropped files
+here" button) and remove-from-library (confirm-guarded).
+
+Adding one: type a path, or click **Browse** to walk the server's
+filesystem in a modal (up with `..`, into a folder by clicking it,
+**Select This Folder** to fill the input), then **Add**.
+
+Two things worth knowing:
+
+- **Removing a folder only unregisters it.** The mapping is deleted;
+  files on disk and existing catalog items are untouched. If no remaining
+  folder covers those files, later library-wide scans will treat them as
+  missing — the [Archived Items](archived-items.md) lifecycle takes over,
+  history kept.
+- **Podcast download folders are feed-managed.** The scanner refuses to
+  scan them by hand; the podcast feed system owns their contents.
+
+### User Access
+
+One checkbox per user. Checked (the default) means the library is visible
+to them; unchecking hides it from their browsing, apps, and OPDS —
+enforced in the database, so every listing obeys. Hiding a library never
+destroys anything: the user simply can't see it.
+
+### Processing issues
+
+When the library has items the scanner couldn't process, a link here
+shows the count and leads to its
+[Processing Issues](library-processing-issues.md) page.
+
+### Edit Details and Delete Library
+
+**Edit Details** changes the name and description. The library type is
+fixed at creation — it can't be edited later.
+
+**Delete Library** is the destructive one, and its confirm dialog says
+precisely what it does:
+
+- **Permanently removed, no archive or undo:** the library, its folder
+  mappings, and all book records — with their reading progress,
+  highlights, notes, bookmarks, and ratings.
+- **Not touched:** media files on disk. Delete the library, keep the
+  files; re-create the library later and scan them fresh (with empty
+  reading history).
+
+## The archived banner
+
+When any library has archived (missing-file) items, this page shows a
+banner with the total count and two shortcuts: **View Archived** (the
+[Archived Items](archived-items.md) page) and **Purge Archived Now** (the
+same permanent wipe the archived page's Purge All Archived performs).
+
+## Every scan entry point, at a glance
+
+| Where | Control | Kind |
+| --- | --- | --- |
+| This page, library card | **Force Rescan** | Force, this library |
+| This page, folder row | **Scan this folder** | Shallow, that folder |
+| Admin dashboard | **Force Rescan All Libraries** | Force, everything |
+| Settings → Scanning | **Auto-Scan** | Shallow, automatic |
+| A book's page | **Rescan** | Force, that one item |
+
+Full semantics for each: [Scanning](scanning.md).
@@ -11,7 +11,8 @@
 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).
+on the [Libraries](libraries.md) page (the link only appears when the
+library has issues).

 ## What's on the page