From 0d4698c0def585d3572110c56d0db550c51c7f36 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 2 Nov 2026 14:17:13 -0500 Subject: [PATCH] docs(admin): admin-guide front door + Administration area in the portal The tenth and final page: the section directory with one-line coverage per page, the fresh-instance quick path (libraries -> scan -> Base URL -> users -> devices), and the when-something-looks-wrong triage table mapping symptoms to pages. The portal (index.md) gains a For Administrators area listing all nine admin pages; the user guide's 'being expanded separately' line becomes the done-state sentence. Every control name quoted here exists in the glossary. --- docs/admin/admin-guide.md | 58 ++++++++++++++++++++++++++++++++------- docs/index.md | 16 ++++++++++- docs/user/user-guide.md | 4 +-- 3 files changed, 65 insertions(+), 13 deletions(-) diff --git a/docs/admin/admin-guide.md b/docs/admin/admin-guide.md index 2bb187fa..4bad139b 100644 --- a/docs/admin/admin-guide.md +++ b/docs/admin/admin-guide.md @@ -1,16 +1,54 @@ + + # Admin Guide -**Coming Soon** +Everything an instance administrator runs lives in this section. Like the +rest of Bookhoard's docs, pages tell you what to click — but admin pages +add the layer users don't need: **what each control actually does** before +you click it, what it costs, and what it changes. (The calibration, if +you're curious: *user docs = what you see, admin docs = what it does, +developer docs = how it works*.) -This guide will cover: +## The Administration section -- User management -- Library management -- System monitoring -- Analytics and reporting -- Security settings -- Backup and restore +| Page | What it covers | +| --- | --- | +| [Dashboard](dashboard.md) | The `/admin` landing page: stats, file-watcher status, **Force Rescan All Libraries**, live scan progress | +| [Libraries](libraries.md) | Creating libraries, folders, per-user visibility, per-library scans, deletion semantics | +| [Processing Issues](library-processing-issues.md) | Per-library ledger of items the scanner couldn't process — Retry, Retry all, Dismiss | +| [Archived Items](archived-items.md) | The missing-file lifecycle: two-strikes archiving, Merge/Restore/Delete, retention | +| [Podcasts](podcasts.md) | The all-feeds maintenance view: disk usage, refresh, delete files, remove for everyone | +| [Hash Conflicts](hash-conflicts.md) | Byte-identical duplicates and their resolution (merge reading data or keep both) | +| [Users](users.md) | Accounts, roles, password resets, the last-admin guards | +| [Settings](settings.md) | Every server-wide setting: key, default, range, what it does, restart or live | +| [Scanning](scanning.md) | The deep-dive: shallow vs. force, and what every scan button actually does | ---- +The app's own sidebar shows the first six as the **Administration** group; +Processing Issues and Archived Items hang off the Libraries page. -_In the meantime, check out our [Operations Portal](../operations/operations.md)_ +## If you're setting up a fresh instance + +The shortest sane path, in order: + +1. **[Libraries](libraries.md)** → Create Library, add its folders +2. Let the initial scan populate it (or **Force Rescan** to be sure) +3. **[Settings](settings.md)** → set the **Base URL** to the address other + devices will use, and check **Auto-Scan** is on +4. **[Users](users.md)** → create accounts (or leave public registration + on), set roles +5. Point devices at the server — the [device guides](../user/user-guide.md) + walk each one + +## When something looks wrong + +- Books vanished from the library? [Archived Items](archived-items.md) — + they're almost certainly there, history intact. +- A book's metadata is stale or wrong? Open the book → **Rescan** + (re-extracts that one item, sidecars included). +- Duplicates? [Hash Conflicts](hash-conflicts.md). +- A scan didn't pick up your changes? [Scanning](scanning.md) explains + which scans skip unchanged files — and which never do. diff --git a/docs/index.md b/docs/index.md index 240dae1d..5feca6d2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -32,7 +32,21 @@ Complete guide to Bookhoard documentation. Find what you need quickly. - [Themes](user/themes.md) - [Calibre Integration](user/calibre-integration.md) - [Profile Guide](user/profile-guide.md) - - [Admin Guide](admin/admin-guide.md) + +### 🛡 For Administrators + +**[Admin Guide](admin/admin-guide.md)** - running a Bookhoard instance: every admin page, what each control actually does + +- **Administration** + - [Admin Dashboard](admin/dashboard.md) - stats, Force Rescan All Libraries, scan progress + - [Libraries](admin/libraries.md) - create libraries, folders, user access, scanning + - [Processing Issues](admin/library-processing-issues.md) - items the scanner couldn't process + - [Archived Items](admin/archived-items.md) - missing files, history-preserving archive + - [All Podcasts](admin/podcasts.md) - the maintenance view for every feed + - [Hash Conflicts](admin/hash-conflicts.md) - duplicate content resolution + - [Users](admin/users.md) - accounts, roles, password resets + - [System Settings](admin/settings.md) - every setting: key, default, range, meaning + - [Scanning](admin/scanning.md) - shallow vs. force: what every scan button does ### 👨‍💻 For Developers diff --git a/docs/user/user-guide.md b/docs/user/user-guide.md index d6ba55c4..32e69ef4 100644 --- a/docs/user/user-guide.md +++ b/docs/user/user-guide.md @@ -40,8 +40,8 @@ comes when you add a [device](devices/android-app.md). ## A note on admins Some screens (user management, server settings, library folders) are admin -territory; [Admin Guide](../admin/admin-guide.md) is the door, and the admin docs are -being expanded separately. +territory; [Admin Guide](../admin/admin-guide.md) is the door, and the +Administration docs section covers every admin page. **Looking for developer documentation?** See the [Developer Portal](../developer/development.md).