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.

docs/admin/archived-items.md

@@ -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
 

docs/admin/libraries.md

@@ -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).

docs/admin/library-processing-issues.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
 

docs/developer/ui-controls.md

@@ -252,6 +252,38 @@ 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: Create Library
+where: Admin → Libraries → page header
+does: Opens the create-library modal (name, optional description, library type). Type is fixed at creation — it cannot be edited later.
+
+label: Manage
+where: Admin → Libraries → a library's card row
+does: Opens that library's panel: folders, user access, processing issues, edit/delete.
+
+label: Edit Details
+where: Admin → Libraries → a library's panel
+does: Edits the library's name and description. Library type is not editable.
+
+label: Delete Library
+where: Admin → Libraries → a library's panel
+does: Permanently deletes the library, its folder mappings, and all book records with reading progress, highlights, notes, bookmarks, and ratings. Files on disk are not touched.
+
+label: View Archived
+where: Admin → Libraries → the archived banner
+does: Opens the Archived Items page.
+
+label: Purge Archived Now
+where: Admin → Libraries → the archived banner
+does: Same permanent wipe as Purge All Archived on the Archived Items page, offered inline.
+
+label: Browse
+where: Admin → Libraries → a library's panel → folder form
+does: Opens the server-side folder browser: walk the filesystem, Select This Folder fills the path input.
+
+label: User Access
+where: Admin → Libraries → a library's panel → section heading
+does: Per-user visibility checkboxes — checked (default) shows the library to that user; unchecked hides it everywhere for them, enforced in the database.
+
 label: Resume rewind
 where: audio player → player settings; profile settings
 does: Rewinds playback a configured few seconds when you resume.