bookhoard/docs/admin/libraries.md

Libraries

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.

Creating a library

Create Library opens a modal with three fields:

• 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

A library with no folders can't scan — add at least one folder (below) before expecting anything to appear in it.

The library card

Each library renders as a card: name, description, a type chip, a folder count, and two controls:

• 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 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.

The library panel

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