Bump package version to 1.1.6

Update package.json version from 1.1.5 to 1.1.6 to reflect a new release.

.gitignore

@@ -1,5 +1,6 @@
 # IDE
 .idea
+.vscode
 
 # Dependencies
 /node_modules
@@ -55,4 +56,4 @@ next-env.d.ts
 /test-media
 /test-data
 /bookdrop
-dockerfile.patch
+dockerfile.patch

CLAUDE.md

@@ -4,6 +4,14 @@
 
 **ALWAYS DO:** When you feel work is complete, use the docker compose build readmebook to confirm you have no errors. If the build succeeds, then you can tell me it is ready to be tested.
 
+**NEVER implement without approval.** When asked to assess, investigate, or fix a problem:
+1. **Research & analyze** — Read code, trace the issue, identify root cause.
+2. **Present a solution plan** — Explain the root cause, list the specific files and changes needed, and describe the approach clearly.
+3. **Wait for explicit approval** — Do NOT write any code until the user confirms the plan.
+4. Only after approval: implement, build, and report results.
+
+This applies to bug fixes, feature requests, and any code changes. Investigation and analysis are always fine — writing code is not until approved.
+
 ---
 
 ## 1. Token-Efficient Documentation System

docker-compose.yml

@@ -49,6 +49,15 @@ services:
       PUID: 1000
       PGID: 1000
 
+      # ========================================================================
+      # OPTIONAL: File Permission Mask
+      # ========================================================================
+      # Set a umask to control default file permissions for all files created
+      # by the application. Common values:
+      # - 002: Group-writable (files: 664, dirs: 775) - recommended for shared access
+      # - 022: Group-readable only (files: 644, dirs: 755) - more restrictive
+      # UMASK: "002"
+
       # ========================================================================
       # OPTIONAL: Secrets (auto-generated on first run if not provided)
       # ========================================================================

docker/unified/app-start.sh

@@ -22,6 +22,12 @@ PGID=${PGID:-$(id -g node)}
 echo "[App] Starting Next.js server..."
 echo "[App] Process will run as UID:GID = $PUID:$PGID"
 
+# Apply UMASK if set (controls default file permissions)
+if [ -n "$UMASK" ]; then
+    echo "[App] Applying umask: $UMASK"
+    umask "$UMASK"
+fi
+
 cd /app
 
 # =============================================================================

docker/unified/entrypoint.sh

@@ -387,6 +387,7 @@ PORT=$PORT
 HOSTNAME=$HOSTNAME
 PUID=${PUID:-}
 PGID=${PGID:-}
+UMASK=${UMASK:-}
 ROOTLESS_CONTAINER=${ROOTLESS_CONTAINER:-}
 EOF
 
@@ -403,6 +404,29 @@ echo "🔄 Running Prisma migrations..."
 cd /app
 su - node -c "cd /app && DATABASE_URL='$DATABASE_URL' npx prisma db push --skip-generate --accept-data-loss" || echo "⚠️  Migrations may have failed, continuing..."
 
+# Run data migrations (run-once SQL scripts tracked in _data_migrations table)
+echo "🔄 Running data migrations..."
+
+for sql_file in /app/prisma/data-migrations/*.sql; do
+    if [ -f "$sql_file" ]; then
+        migration_name=$(basename "$sql_file")
+
+        already_run=$(psql "$DATABASE_URL" -tA -c "SELECT 1 FROM _data_migrations WHERE name = '$migration_name' LIMIT 1;")
+        if [ "$already_run" = "1" ]; then
+            echo "   Skipping $migration_name (already executed)"
+            continue
+        fi
+
+        echo "   Running $migration_name..."
+        if su - node -c "cd /app && DATABASE_URL='$DATABASE_URL' npx prisma db execute --schema prisma/schema.prisma --file '$sql_file'"; then
+            psql "$DATABASE_URL" -c "INSERT INTO _data_migrations (name) VALUES ('$migration_name');"
+            echo "   ✅ $migration_name completed"
+        else
+            echo "⚠️  Data migration $migration_name failed, will retry on next start"
+        fi
+    fi
+done
+
 # Stop internal PostgreSQL (supervisord will restart it via wrapper)
 if [ "$USE_EXTERNAL_POSTGRES" = "false" ]; then
     echo "🔧 Stopping temporary PostgreSQL instance..."

dockerfile.unified

@@ -24,14 +24,26 @@ RUN apt-get update && apt-get install -y \
     supervisor \
     curl \
     openssl \
-    ffmpeg \
     locales \
     gosu \
+    xz-utils \
     && sed -i 's/^# \(en_US.UTF-8 UTF-8\)/\1/' /etc/locale.gen \
     && locale-gen en_US.UTF-8 \
     && update-locale LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 \
     && rm -rf /var/lib/apt/lists/*
 
+# Install static ffmpeg (no transitive dependencies like imagemagick)
+ADD https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz /tmp/ffmpeg.tar.xz
+RUN cd /tmp && tar xf ffmpeg.tar.xz && \
+    cp ffmpeg-*-static/ffmpeg ffmpeg-*-static/ffprobe /usr/local/bin/ && \
+    rm -rf /tmp/ffmpeg*
+
+# Remove imagemagick (pre-installed in node:20-bookworm base image, not needed)
+RUN apt-get purge -y imagemagick imagemagick-6-common 'imagemagick-6*' \
+    'libmagickcore*' 'libmagickwand*' && \
+    apt-get autoremove -y --purge && \
+    rm -rf /var/lib/apt/lists/*
+
 ENV LANG=en_US.UTF-8
 ENV LC_ALL=en_US.UTF-8
 

documentation/TABLEOFCONTENTS.md

@@ -5,6 +5,7 @@
 ## Authentication & Users
 - **Plex OAuth, JWT sessions, RBAC** → [backend/services/auth.md](backend/services/auth.md)
 - **Local admin authentication, password change** → [backend/services/auth.md](backend/services/auth.md)
+- **Admin-generated login token per user (URL-login)** → [backend/services/auth.md](backend/services/auth.md)
 - **Route protection, auth guards** → [frontend/routing-auth.md](frontend/routing-auth.md)
 - **Login page UI/UX** → [frontend/pages/login.md](frontend/pages/login.md)
 
@@ -32,6 +33,14 @@
 - **File hash matching for accurate ASIN** → [fixes/file-hash-matching.md](fixes/file-hash-matching.md)
 - **OIDC authentication** → [backend/services/auth.md](backend/services/auth.md)
 
+## Reading Shelves (Goodreads, Hardcover)
+- **Goodreads shelf sync (RSS feeds)** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md)
+- **Hardcover shelf sync (GraphQL API)** → [backend/services/hardcover-sync.md](backend/services/hardcover-sync.md)
+- **Shared sync core (Audible lookup, request creation)** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md#shared-sync-core)
+- **Combined shelves API, GenericShelf** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md)
+- **Hook factory (createShelfHooks)** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md#hook-factory)
+- **Adding a new shelf provider** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md#adding-a-new-provider)
+
 ## Audible Integration
 - **Web scraping (popular, new releases)** → [integrations/audible.md](integrations/audible.md)
 - **Database caching, real-time matching** → [integrations/audible.md](integrations/audible.md)
@@ -77,6 +86,7 @@
 - **Component catalog (cards, badges, forms)** → [frontend/components.md](frontend/components.md)
 - **RequestCard, StatusBadge, ProgressBar** → [frontend/components.md](frontend/components.md)
 - **Pages: home, search, requests, profile** → [frontend/components.md](frontend/components.md)
+- **Home page sections (per-user, configurable)** → [features/home-sections.md](features/home-sections.md)
 
 ## BookDate (AI Recommendations)
 - **AI-powered recommendations, swipe interface** → [features/bookdate.md](features/bookdate.md)
@@ -89,6 +99,7 @@
 
 ## Admin Features
 - **Dashboard (metrics, downloads, requests)** → [admin-dashboard.md](admin-dashboard.md)
+- **Bulk import (scan folders, match Audible, batch import)** → [features/bulk-import.md](features/bulk-import.md)
 - **Jobs management UI** → [backend/services/scheduler.md](backend/services/scheduler.md)
 - **Request deletion (soft delete, seeding awareness)** → [admin-features/request-deletion.md](admin-features/request-deletion.md)
 - **Request approval system, auto-approve settings** → [admin-features/request-approval.md](admin-features/request-approval.md)
@@ -150,3 +161,13 @@
 **"Why do BookDate library books show placeholders?"** → [features/library-thumbnail-cache.md](features/library-thumbnail-cache.md)
 **"How does file hash matching work?"** → [fixes/file-hash-matching.md](fixes/file-hash-matching.md)
 **"Why is ABS matching the wrong book?"** → [fixes/file-hash-matching.md](fixes/file-hash-matching.md) (file hash prevents false positives)
+**"How do I customize my home page?"** → [features/home-sections.md](features/home-sections.md)
+**"How do Audible categories work?"** → [features/home-sections.md](features/home-sections.md)
+**"How do I add category sections to the home page?"** → [features/home-sections.md](features/home-sections.md)
+**"How do Goodreads shelves work?"** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md)
+**"How do Hardcover shelves work?"** → [backend/services/hardcover-sync.md](backend/services/hardcover-sync.md)
+**"How do I add a new shelf provider?"** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md#adding-a-new-provider)
+**"How does the shelf sync core work?"** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md#shared-sync-core)
+**"How does bulk import work?"** → [features/bulk-import.md](features/bulk-import.md)
+**"How do I import multiple audiobooks at once?"** → [features/bulk-import.md](features/bulk-import.md)
+**"How does the bulk import scanner detect audiobooks?"** → [features/bulk-import.md](features/bulk-import.md)

documentation/backend/services/auth.md

@@ -249,6 +249,14 @@ oidc.admin_claim_value       = 'readmeabook-admin'
 - **Admin Settings:** OIDC section in `/admin/settings` (auth tab)
 - **Library:** `openid-client` (OIDC discovery, token exchange, PKCE)
 
+## Admin-Generated Login Token
+
+- Login token stored as SHA-256 hash in `User.loginTokenHash`
+- Admin generates/revokes via user permissions modal
+- User navigates to `/auth/token/login?token=rmab_...` → page POSTs token to API in request body
+- API: `POST /api/auth/token/login` with `{ token }` in JSON body
+- Invalid token redirects to `/login`
+
 ## Security
 
 - Never log tokens

documentation/backend/services/goodreads-sync.md

@@ -0,0 +1,75 @@
+# Goodreads & Shelf Sync
+
+**Status:** ✅ Implemented | RSS feed parsing, shared sync core, extensible provider architecture
+
+## Overview
+Syncs user-subscribed Goodreads shelves via RSS feeds, resolves books to Audible ASINs, and creates requests. Also documents the shared shelf sync core used by all providers.
+
+## Architecture
+
+### Files
+- `src/lib/services/goodreads-sync.service.ts` — RSS fetch/parse, delegates to shared core
+- `src/lib/services/shelf-sync-core.service.ts` — Shared sync logic (Audible lookup, cover enrichment, request creation)
+- `src/lib/utils/shelf-helpers.ts` — Shared `processBooks()` utility for cover URL parsing
+- `src/lib/hooks/createShelfHooks.ts` — Generic hook factory for shelf CRUD operations
+- `src/app/api/user/goodreads-shelves/route.ts` — GET (list) + POST (add) routes
+- `src/app/api/user/goodreads-shelves/[id]/route.ts` — DELETE + PATCH routes
+- `src/app/api/user/shelves/route.ts` — Combined GET for all providers (GenericShelf shape)
+- `src/lib/hooks/useGoodreadsShelves.ts` — Frontend hooks (via `createShelfHooks` factory)
+
+### Database Models
+- **GoodreadsShelf** — Per-user shelf subscription (`userId`, `rssUrl`, `name`, `lastSyncAt`, `bookCount`, `coverUrls`)
+- **BookMapping** — Shared table for all providers. Keyed by `provider` + `externalBookId`. Caches Audible ASIN lookups.
+
+## Goodreads RSS Feed
+- **Format:** `https://www.goodreads.com/review/list_rss/{userId}?shelf={shelfName}`
+- **Auth:** None required (public RSS)
+- **Parsing:** `fast-xml-parser` extracts `item` entries with `book_id`, `title`, `author_name`, `book_image_url`
+
+## Shared Sync Core
+
+`shelf-sync-core.service.ts` contains all provider-agnostic sync logic:
+
+### Interface: `ShelfBook`
+```typescript
+{ bookId: string; title: string; author: string; coverUrl?: string }
+```
+
+### Function: `processShelfBooks()`
+Accepts provider-agnostic book list + context, performs:
+1. **BookMapping lookup** — Check if book already resolved (`provider` + `externalBookId`)
+2. **Audible search** — Full query (`title author`), fallback with cleaned title (strips parenthetical series info)
+3. **noMatch retry** — Re-searches after `NO_MATCH_RETRY_DAYS` (7 days)
+4. **Request creation** — Calls `createRequestForUser()` for matched ASINs
+5. **Cover enrichment** — Queries `audibleCache` for cached covers, builds `/api/cache/thumbnails/` URLs
+6. **Shelf metadata update** — Writes `lastSyncAt`, `bookCount`, top 8 books as JSON to `coverUrls`
+
+### Constants
+- `DEFAULT_MAX_LOOKUPS_PER_SHELF` = 10 (per scheduled cycle; 0 = unlimited for manual triggers)
+- `NO_MATCH_RETRY_DAYS` = 7
+
+### Hook Factory: `createShelfHooks(endpoint)`
+Returns `{ useList, useAdd, useDelete, useUpdate }` — all with SWR caching, optimistic updates, and automatic revalidation of the combined `/api/user/shelves` endpoint.
+
+## API Endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/user/goodreads-shelves` | List user's Goodreads shelves |
+| POST | `/api/user/goodreads-shelves` | Add shelf (validates RSS feed, triggers sync) |
+| DELETE | `/api/user/goodreads-shelves/[id]` | Remove shelf (ownership check) |
+| PATCH | `/api/user/goodreads-shelves/[id]` | Update RSS URL (triggers re-sync) |
+| GET | `/api/user/shelves` | Combined endpoint — merges all providers into `GenericShelf` |
+
+## Adding a New Provider
+1. Create Prisma shelf model + migration (BookMapping table is already shared)
+2. Create API client service for the external data source
+3. Create thin sync service (~50-80 lines) that fetches books and calls `processShelfBooks()`
+4. Create API routes (or use a generic route handler)
+5. Create hook file (~40 lines) using `createShelfHooks(endpoint)`
+6. Add tab in `AddShelfModal` with provider-specific form fields
+
+## Related
+- [Hardcover sync](hardcover-sync.md)
+- [Background jobs](jobs.md)
+- [Scheduler](scheduler.md)

documentation/backend/services/hardcover-sync.md

@@ -0,0 +1,66 @@
+# Hardcover Shelf Sync
+
+**Status:** ✅ Implemented | GraphQL API integration, Audible ASIN resolution, automated request creation
+
+## Overview
+Syncs user-subscribed Hardcover lists via their GraphQL API, resolves books to Audible ASINs, and creates audiobook requests automatically.
+
+## Architecture
+
+### Files
+- `src/lib/services/hardcover-api.service.ts` — GraphQL queries, `fetchHardcoverList()`
+- `src/lib/services/hardcover-sync.service.ts` — Provider-specific orchestration, delegates to shared core
+- `src/lib/services/shelf-sync-core.service.ts` — Shared sync logic (Audible lookup, cover enrichment, request creation)
+- `src/app/api/user/hardcover-shelves/route.ts` — GET (list) + POST (add) routes
+- `src/app/api/user/hardcover-shelves/[id]/route.ts` — DELETE + PATCH routes
+- `src/lib/hooks/useHardcoverShelves.ts` — Frontend hooks (via `createShelfHooks` factory)
+
+### Database Models
+- **HardcoverShelf** — Per-user list subscription (`userId`, `listId`, encrypted `apiToken`, `name`, `lastSyncAt`, `bookCount`, `coverUrls`)
+- **BookMapping** — Shared across all providers. Keyed by `provider` + `externalBookId`. Caches Audible ASIN resolution (`audibleAsin`, `noMatch`, `lastSearchAt`)
+
+## Hardcover API
+
+- **Endpoint:** `https://api.hardcover.app/v1/graphql` (Hasura-based)
+- **Auth:** Bearer token in Authorization header
+- **Username type:** `citext` (case-insensitive text) — use `$username: citext!` in GraphQL variables
+
+### Query Strategies (custom lists)
+| Input | Strategy | Query root |
+|---|---|---|
+| URL with `@username` | Scoped to that user | `users(where: {username: {_eq: $username}}) { lists(...) }` |
+| Bare slug (no username) | Authenticated user's own list | `me { lists(where: {slug: {_eq: $slug}}) }` |
+| Numeric ID | Global lookup (IDs are unique) | `lists(where: {id: {_eq: $listId}})` |
+
+### Status Lists
+- Prefix: `status-{id}` (e.g., `status-1`)
+- Query: `me { user_books(where: {status_id: {_eq: $statusId}}) }`
+- Status IDs: 1=Want to Read, 2=Currently Reading, 3=Read, 4=Did Not Finish
+
+## Sync Flow
+1. Fetch shelves from DB (all or specific `shelfId`)
+2. Decrypt API token (encryption service)
+3. Fetch books from Hardcover GraphQL API
+4. Delegate to `processShelfBooks()` in shelf-sync-core (Audible lookup, request creation, cover enrichment)
+5. Update shelf metadata (`lastSyncAt`, `bookCount`, `coverUrls`)
+
+## API Endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/user/hardcover-shelves` | List user's shelves with book counts/covers |
+| POST | `/api/user/hardcover-shelves` | Add new shelf (validates via API fetch, encrypts token, triggers sync) |
+| DELETE | `/api/user/hardcover-shelves/[id]` | Remove shelf (ownership check) |
+| PATCH | `/api/user/hardcover-shelves/[id]` | Update listId/apiToken (triggers re-sync on change) |
+
+## Key Details
+- **Token cleanup:** Strips `Bearer ` prefix if user pastes it
+- **Duplicate check:** Unique constraint on `(userId, listId)`
+- **Immediate sync:** POST and PATCH trigger `addSyncShelvesJob()` with unlimited lookups
+- **Scheduled sync:** Runs via `sync_reading_shelves` job (default: max 10 lookups/shelf/cycle)
+- **Cover data:** Stores top 8 books as JSON in `coverUrls` field for shelf card display
+
+## Related
+- [Shelf sync core (shared logic)](goodreads-sync.md#shared-sync-core)
+- [Background jobs](jobs.md)
+- [Scheduler](scheduler.md)

documentation/backend/services/scheduler.md

@@ -129,10 +129,10 @@ interface ScheduledJob {
 ## Audible Refresh Processor
 
 **Implementation:**
-1. Clear previous `isPopular`/`isNewRelease` flags
-2. Fetch 200 popular + 200 new releases (multi-page scraping)
-3. Download and cache cover thumbnails locally (stored in `/app/cache/thumbnails`)
-4. Store/update in DB with category flags, rankings (`popularRank`, `newReleaseRank`), and cached cover paths
+1. Fetch 200 popular + 200 new releases (multi-page scraping)
+2. Download and cache cover thumbnails locally (stored in `/app/cache/thumbnails`)
+3. Wipe and re-populate `AudibleCacheCategory` entries with reserved IDs (`__popular__`, `__new_releases__`) and user-configured category IDs
+4. Upsert book metadata in `AudibleCache`, ranked entries in `AudibleCacheCategory`
 5. Record sync timestamp (`lastAudibleSync`)
 6. Clean up unused thumbnails (removes covers for audiobooks no longer in cache)
 7. Perform fuzzy matching (70% threshold) against Plex library

documentation/features/bulk-import.md

@@ -0,0 +1,82 @@
+# Bulk Import Feature
+
+**Status:** ✅ Implemented | Admin-only | Multi-step wizard modal
+
+## Overview
+Lets admins scan a server folder recursively, discover audiobook subfolders, match against Audible, review matches, and import selected books via the existing manual import pipeline.
+
+## Flow
+1. **Select Folder** — Browse base folders (Downloads, Media Library, Book Drop), pick scan root
+2. **Scan & Match** — Recursively discover audiobook folders (max 10 levels), read metadata via ffprobe, search Audible per book (1.5s rate limit)
+3. **Review & Import** — Scrollable list with skip toggles, library status, confidence badges; Start Import queues organize_files jobs
+
+## Key Details
+- **Access:** Admin-only, modal opened from admin dashboard Quick Actions
+- **Audio detection:** Uses `AUDIO_EXTENSIONS` from `src/lib/constants/audio-formats.ts`
+- **Audiobook boundary:** A folder containing audio files = one audiobook; subfolders not scanned further
+- **Metadata extraction:** ffprobe reads `album` (title), `album_artist` (author), `composer` (narrator) from first audio file
+- **Fallback:** If metadata tags are empty, folder name used as search term; "Low Confidence" badge shown
+- **Author/narrator dedup:** Splits on `,;& ` delimiters, removes names appearing in both fields
+- **Scan depth:** Max 10 levels recursion
+- **Rate limiting:** 1.5s delay between Audible searches (same as existing scraping rate limit)
+- **Library check:** Uses `findPlexMatch()` for ASIN-based availability detection
+- **Import:** Reuses existing `organize_files` job queue (same as manual import)
+- **No new database tables** — all state is ephemeral during wizard session
+
+## API Endpoints
+
+**POST /api/admin/bulk-import/scan** (SSE stream)
+- Body: `{ rootPath: string }`
+- Path validation: must be within download_dir, media_dir, or /bookdrop
+- Streams events: `progress`, `discovery_complete`, `matching`, `book_matched`, `complete`, `error`
+- Each `book_matched` event includes: folderPath, match (Audible data), inLibrary, hasActiveRequest, metadataSource
+
+**POST /api/admin/bulk-import/execute**
+- Body: `{ imports: Array<{ folderPath: string, asin: string }> }`
+- Creates audiobook records + requests, queues organize_files jobs
+- Returns: `{ success, results[], summary: { total, succeeded, failed } }`
+
+## SSE Event Types
+
+| Event | Data | When |
+|---|---|---|
+| `progress` | `{ phase, foldersScanned, audiobooksFound, currentFolder }` | During folder discovery |
+| `discovery_complete` | `{ totalFound, message }` | All folders scanned |
+| `matching` | `{ current, total, folderName, searchTerm }` | Before each Audible search |
+| `book_matched` | Full book result with match data | After each Audible search |
+| `complete` | `{ audiobooks[], totalFound, matched, inLibrary }` | All matching done |
+| `error` | `{ message }` | On failure |
+
+## UI States
+
+| State | Visual |
+|---|---|
+| Normal (will import) | Full opacity, blue toggle ON |
+| Skipped by user | 40% opacity, gray toggle OFF |
+| Already in library | 40% opacity, green "In Library" badge, toggle disabled |
+| Active request exists | 40% opacity, purple "Requested" badge, toggle disabled |
+| No Audible match | Red "No Match" badge, folder name shown, pre-skipped |
+| Low confidence (folder name fallback) | Amber "Low Confidence" badge |
+
+## Files
+
+**Backend:**
+- `src/lib/utils/bulk-import-scanner.ts` — Folder discovery + ffprobe metadata
+- `src/app/api/admin/bulk-import/scan/route.ts` — SSE scan endpoint
+- `src/app/api/admin/bulk-import/execute/route.ts` — Batch import endpoint
+
+**Frontend:**
+- `src/components/admin/BulkImportWizard.tsx` — Modal orchestrator
+- `src/components/admin/bulk-import/types.ts` — Shared types
+- `src/components/admin/bulk-import/ScanFolderStep.tsx` — Folder browser
+- `src/components/admin/bulk-import/ScanProgressStep.tsx` — Progress display
+- `src/components/admin/bulk-import/MatchReviewStep.tsx` — Review list + import
+
+**Modified:**
+- `src/app/admin/page.tsx` — Added Bulk Import quick action + modal
+
+## Related
+- [Manual Import](manual-import.md) — Single-book import (reused pipeline)
+- [File Organization](../phase3/file-organization.md) — organize_files job
+- [Audible Integration](../integrations/audible.md) — Search/scraping
+- [Background Jobs](../backend/services/jobs.md) — Job queue system

documentation/features/home-sections.md

@@ -0,0 +1,64 @@
+# Home Page Sections (Per-User Configurable)
+
+**Status:** Implemented | Per-user home page with configurable sections (popular, new releases, Audible categories)
+
+## Overview
+Users customize their home page by adding/removing/reordering sections. Each section displays audiobooks from a specific source: built-in Popular, New Releases, or scraped Audible categories.
+
+## Data Models
+
+**UserHomeSection** (`user_home_sections`):
+- `id`, `userId` (FK User), `sectionType` ('popular'|'new_releases'|'category'), `categoryId` (nullable), `categoryName` (nullable), `sortOrder` (int)
+- Unique: `(userId, sectionType, categoryId)`
+- Default: Popular (0) + New Releases (1) created on first access
+
+**AudibleCacheCategory** (`audible_cache_categories`):
+- `id`, `asin`, `categoryId`, `rank`, `lastSyncedAt`
+- Unique: `(asin, categoryId)`, Indexes: `categoryId`, `(categoryId, rank)`
+
+## API Endpoints
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/api/user/home-sections` | user | Returns sections + nextRefresh |
+| PUT | `/api/user/home-sections` | user | Save full config (delete-recreate), max 10 |
+| GET | `/api/audible/categories` | user | Live scrape top-level categories |
+| GET | `/api/audiobooks/category/[categoryId]` | public | Paginated category books from cache |
+
+## Refresh Processor (Unified Storage)
+- All section data stored in `AudibleCacheCategory` with reserved IDs: `__popular__` and `__new_releases__` for built-in sections
+- Popular/new-releases use same wipe-and-populate pattern as user categories
+- After built-in sections, queries DISTINCT categoryIds from `UserHomeSection`
+- Per section: wipe `AudibleCacheCategory` rows, scrape, upsert `AudibleCache` metadata, insert ranked category entries
+- Batch cooldown between sections (10-20s random)
+- Constants exported from `audible-refresh.processor.ts`: `POPULAR_CATEGORY_ID`, `NEW_RELEASES_CATEGORY_ID`
+
+## AudibleService Methods
+- `getCategories()`: Scrapes `{baseUrl}/categories`, returns `{id, name}[]`
+- `getCategoryBooks(categoryId, limit)`: Scrapes `/search?node={id}&pageSize=50&sort=popularity-rank`, up to 200 results
+
+## Frontend
+- **Hooks:** `useHomeSections()`, `useCategoryAudiobooks()`, `useAudibleCategories()` in `src/lib/hooks/useHomeSections.ts`
+- **Config Modal:** `src/components/home/HomeSectionConfigModal.tsx` — drag-and-drop (desktop), up/down arrows (mobile), auto-save with debounce
+- **Section Component:** `src/components/home/HomeSection.tsx` — renders individual section with color-coded header
+- **Home Page:** `src/app/page.tsx` — dynamic sections from user config, gear icon for customize
+- **Pagination:** `src/components/ui/UnifiedPagination.tsx` — updated to support 1-12 dynamic sections
+
+## Key Decisions
+- 10 section limit per user (total)
+- Category picker scraped live (no categories table)
+- Top-level categories only (v1)
+- Wipe-and-re-scrape per category during refresh
+- Deduplication of categories across users before scraping
+- If category disappears, user sees empty section
+- 10-color palette assigned by sort order
+
+## Files
+- Schema: `prisma/schema.prisma` (UserHomeSection, AudibleCacheCategory)
+- Migration: `prisma/migrations/20260306000000_add_home_sections/migration.sql`
+- Service: `src/lib/integrations/audible.service.ts` (getCategories, getCategoryBooks)
+- Processor: `src/lib/processors/audible-refresh.processor.ts`
+- API Routes: `src/app/api/user/home-sections/route.ts`, `src/app/api/audible/categories/route.ts`, `src/app/api/audiobooks/category/[categoryId]/route.ts`
+- Hooks: `src/lib/hooks/useHomeSections.ts`
+- Components: `src/components/home/HomeSectionConfigModal.tsx`, `src/components/home/HomeSection.tsx`
+- Tests: `tests/api/home-sections.routes.test.ts`, `tests/processors/audible-refresh.processor.test.ts`

documentation/integrations/audible.md

@@ -128,11 +128,11 @@ Single matching algorithm used everywhere (search, popular, new-releases, jobs).
 Discovery APIs serve cached data from DB with real-time matching.
 
 **Flow:**
-1. `audible_refresh` job runs daily → fetches 200 popular + 200 new releases
+1. `audible_refresh` job runs daily → fetches 200 popular + 200 new releases + user-configured categories
 2. Downloads and caches cover thumbnails locally (reduces Audible load)
-3. Stores in DB with flags (`isPopular`, `isNewRelease`) and rankings
+3. Stores metadata in `audible_cache`, ranked entries in `audible_cache_categories` with reserved IDs (`__popular__`, `__new_releases__`) and user category IDs
 4. Cleans up unused thumbnails after sync
-5. API routes query DB → apply real-time matching → return enriched results
+5. API routes query `AudibleCacheCategory` by categoryId → join with `AudibleCache` metadata → apply real-time matching → return enriched results
 6. Homepage loads instantly (no Audible API hits)
 
 ## Thumbnail Caching

documentation/integrations/ebook-sidecar.md

@@ -51,7 +51,7 @@ Ebooks are first-class citizens in RMAB, with their own request type, tracking,
 | Key | Default | Description |
 |-----|---------|-------------|
 | `ebook_annas_archive_enabled` | `false` | Enable Anna's Archive downloads |
-| `ebook_sidecar_base_url` | `https://annas-archive.li` | Base URL for mirror |
+| `ebook_sidecar_base_url` | `https://annas-archive.gl` | Base URL for mirror |
 | `ebook_sidecar_flaresolverr_url` | `` (empty) | FlareSolverr proxy URL (optional) |
 
 #### Section 2: Indexer Search
@@ -180,18 +180,18 @@ Configure URL in Admin Settings → E-book Sidecar: `http://localhost:8191`
 
 ### Method 1: ASIN Search (exact match)
 ```
-Search: https://annas-archive.li/search?ext=epub&lang=en&q="asin:B09TWSRMCB"
+Search: https://annas-archive.gl/search?ext=epub&lang=en&q="asin:B09TWSRMCB"
   ↓
-MD5 Page: https://annas-archive.li/md5/[md5]
+MD5 Page: https://annas-archive.gl/md5/[md5]
   ↓
-Slow Download: https://annas-archive.li/slow_download/[md5]/0/5
+Slow Download: https://annas-archive.gl/slow_download/[md5]/0/5
   ↓
 File Server: http://[server]/path/to/file.epub
 ```
 
 ### Method 2: Title + Author (fallback)
 ```
-Search: https://annas-archive.li/search?q=Title+Author&ext=epub&lang=en
+Search: https://annas-archive.gl/search?q=Title+Author&ext=epub&lang=en
   ↓ (Same flow from MD5 page)
 ```
 

documentation/settings-pages.md

@@ -81,7 +81,7 @@ src/app/admin/settings/
 
 1. **Anna's Archive Section**
    - Enable toggle for Anna's Archive downloads
-   - Base URL (default: `https://annas-archive.li`)
+   - Base URL (default: `https://annas-archive.gl`)
    - FlareSolverr URL (optional, for Cloudflare bypass)
 
 2. **Indexer Search Section**
@@ -101,7 +101,7 @@ src/app/admin/settings/
 | `ebook_sidecar_preferred_format` | `epub` | Preferred format |
 | `ebook_auto_grab_enabled` | `true` | Auto-create ebook requests after audiobook downloads |
 | `ebook_kindle_fix_enabled` | `false` | Apply Kindle compatibility fixes to EPUB files |
-| `ebook_sidecar_base_url` | `https://annas-archive.li` | Anna's Archive mirror |
+| `ebook_sidecar_base_url` | `https://annas-archive.gl` | Anna's Archive mirror |
 | `ebook_sidecar_flaresolverr_url` | `` | FlareSolverr URL |
 
 **Behavior:**

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "readmeabook",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "readmeabook",
-      "version": "1.0.14",
+      "version": "1.0.15",
       "dependencies": {
         "@heroicons/react": "^2.2.0",
         "@prisma/client": "^6.19.0",
@@ -299,7 +299,7 @@
       "version": "7.27.1",
       "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz",
       "integrity": "sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=6.9.0"
@@ -309,7 +309,7 @@
       "version": "7.28.5",
       "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz",
       "integrity": "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=6.9.0"
@@ -343,7 +343,7 @@
       "version": "7.28.5",
       "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.28.5.tgz",
       "integrity": "sha512-KKBU1VGYR7ORr3At5HAtUQ+TV3SzRCXmA/8OdDZiLDBIZxVyzXuztPjfLd3BV1PRAQGCMWWSHYhL0F8d5uHBDQ==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@babel/types": "^7.28.5"
@@ -403,7 +403,7 @@
       "version": "7.28.5",
       "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.28.5.tgz",
       "integrity": "sha512-qQ5m48eI/MFLQ5PxQj4PFaprjyCTLI37ElWMmNs0K8Lk3dVeOdNpB3ks8jc7yM5CDmVC73eMVk/trk3fgmrUpA==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@babel/helper-string-parser": "^7.27.1",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "readmeabook",
-  "version": "1.0.15",
+  "version": "1.1.6",
   "private": true,
   "scripts": {
     "dev": "next dev",

prisma/data-migrations/normalize-local-usernames.sql

@@ -0,0 +1,7 @@
+-- Normalize existing local usernames to lowercase (idempotent - safe to run multiple times)
+-- Only affects local auth users, not Plex/OIDC users
+UPDATE users SET plex_username = LOWER(plex_username)
+  WHERE auth_provider = 'local' AND deleted_at IS NULL AND plex_username != LOWER(plex_username);
+
+UPDATE users SET plex_id = 'local-' || LOWER(SUBSTRING(plex_id FROM 7))
+  WHERE plex_id LIKE 'local-%' AND plex_id NOT LIKE 'local-%-deleted-%' AND plex_id != LOWER(plex_id);

prisma/data-migrations/reset-works-table.sql

@@ -0,0 +1,7 @@
+-- Reset works table to fix incorrect dedup groupings (v1.1.2)
+-- Books with "Series: Title" naming (e.g. "Eden's Gate: The Reborn" vs
+-- "Eden's Gate: The Spartan") were incorrectly merged into the same work
+-- because subtitle stripping collapsed them to the same base title.
+-- The works table auto-rebuilds from dedup logic as users browse.
+DELETE FROM work_asins;
+DELETE FROM works;

prisma/migrations/20260302000000_add_custom_search_terms/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "requests" ADD COLUMN "custom_search_terms" TEXT;

prisma/migrations/20260303000000_add_works_table/migration.sql

@@ -0,0 +1,42 @@
+-- CreateTable
+CREATE TABLE "works" (
+    "id" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "author" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "works_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "work_asins" (
+    "id" TEXT NOT NULL,
+    "work_id" TEXT NOT NULL,
+    "asin" TEXT NOT NULL,
+    "narrator" TEXT,
+    "duration_minutes" INTEGER,
+    "is_canonical" BOOLEAN NOT NULL DEFAULT false,
+    "source" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "work_asins_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "works_title_idx" ON "works"("title");
+
+-- CreateIndex
+CREATE INDEX "works_author_idx" ON "works"("author");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "work_asins_asin_key" ON "work_asins"("asin");
+
+-- CreateIndex
+CREATE INDEX "work_asins_work_id_idx" ON "work_asins"("work_id");
+
+-- CreateIndex
+CREATE INDEX "work_asins_asin_idx" ON "work_asins"("asin");
+
+-- AddForeignKey
+ALTER TABLE "work_asins" ADD CONSTRAINT "work_asins_work_id_fkey" FOREIGN KEY ("work_id") REFERENCES "works"("id") ON DELETE CASCADE ON UPDATE CASCADE;

prisma/migrations/20260303100000_add_watched_series_authors/migration.sql

@@ -0,0 +1,51 @@
+-- CreateTable
+CREATE TABLE "watched_series" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "series_asin" TEXT NOT NULL,
+    "series_title" TEXT NOT NULL,
+    "cover_art_url" TEXT,
+    "last_checked_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "watched_series_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "watched_authors" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "author_asin" TEXT NOT NULL,
+    "author_name" TEXT NOT NULL,
+    "cover_art_url" TEXT,
+    "last_checked_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "watched_authors_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "watched_series_user_id_idx" ON "watched_series"("user_id");
+
+-- CreateIndex
+CREATE INDEX "watched_series_series_asin_idx" ON "watched_series"("series_asin");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "watched_series_user_id_series_asin_key" ON "watched_series"("user_id", "series_asin");
+
+-- CreateIndex
+CREATE INDEX "watched_authors_user_id_idx" ON "watched_authors"("user_id");
+
+-- CreateIndex
+CREATE INDEX "watched_authors_author_asin_idx" ON "watched_authors"("author_asin");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "watched_authors_user_id_author_asin_key" ON "watched_authors"("user_id", "author_asin");
+
+-- AddForeignKey
+ALTER TABLE "watched_series" ADD CONSTRAINT "watched_series_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "watched_authors" ADD CONSTRAINT "watched_authors_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;

prisma/migrations/20260303200000_add_hardcover_shelves/migration.sql

@@ -0,0 +1,49 @@
+-- CreateTable
+CREATE TABLE "hardcover_shelves" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "list_id" TEXT NOT NULL,
+    "api_token" TEXT NOT NULL,
+    "last_sync_at" TIMESTAMP(3),
+    "book_count" INTEGER,
+    "cover_urls" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "hardcover_shelves_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "hardcover_book_mappings" (
+    "id" TEXT NOT NULL,
+    "hardcover_book_id" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "author" TEXT NOT NULL,
+    "audible_asin" TEXT,
+    "cover_url" TEXT,
+    "no_match" BOOLEAN NOT NULL DEFAULT false,
+    "last_search_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "hardcover_book_mappings_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "hardcover_shelves_user_id_idx" ON "hardcover_shelves"("user_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "hardcover_shelves_user_id_list_id_key" ON "hardcover_shelves"("user_id", "list_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "hardcover_book_mappings_hardcover_book_id_key" ON "hardcover_book_mappings"("hardcover_book_id");
+
+-- CreateIndex
+CREATE INDEX "hardcover_book_mappings_hardcover_book_id_idx" ON "hardcover_book_mappings"("hardcover_book_id");
+
+-- CreateIndex
+CREATE INDEX "hardcover_book_mappings_audible_asin_idx" ON "hardcover_book_mappings"("audible_asin");
+
+-- AddForeignKey
+ALTER TABLE "hardcover_shelves" ADD CONSTRAINT "hardcover_shelves_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;

prisma/migrations/20260304000000_normalize_local_usernames/migration.sql

@@ -0,0 +1,3 @@
+-- Normalize existing local usernames to lowercase
+UPDATE users SET plex_username = LOWER(plex_username) WHERE auth_provider = 'local' AND deleted_at IS NULL;
+UPDATE users SET plex_id = 'local-' || LOWER(SUBSTRING(plex_id FROM 7)) WHERE plex_id LIKE 'local-%' AND plex_id NOT LIKE 'local-%-deleted-%';

prisma/migrations/20260304000000_unify_book_mappings/migration.sql

@@ -0,0 +1,41 @@
+-- CreateTable
+CREATE TABLE "book_mappings" (
+    "id" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "external_book_id" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "author" TEXT NOT NULL,
+    "audible_asin" TEXT,
+    "cover_url" TEXT,
+    "no_match" BOOLEAN NOT NULL DEFAULT false,
+    "last_search_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "book_mappings_pkey" PRIMARY KEY ("id")
+);
+
+-- Migrate data from goodreads_book_mappings
+INSERT INTO "book_mappings" ("id", "provider", "external_book_id", "title", "author", "audible_asin", "cover_url", "no_match", "last_search_at", "created_at", "updated_at")
+SELECT "id", 'goodreads', "goodreads_book_id", "title", "author", "audible_asin", "cover_url", "no_match", "last_search_at", "created_at", "updated_at"
+FROM "goodreads_book_mappings";
+
+-- Migrate data from hardcover_book_mappings
+INSERT INTO "book_mappings" ("id", "provider", "external_book_id", "title", "author", "audible_asin", "cover_url", "no_match", "last_search_at", "created_at", "updated_at")
+SELECT "id", 'hardcover', "hardcover_book_id", "title", "author", "audible_asin", "cover_url", "no_match", "last_search_at", "created_at", "updated_at"
+FROM "hardcover_book_mappings";
+
+-- DropTable
+DROP TABLE "goodreads_book_mappings";
+
+-- DropTable
+DROP TABLE "hardcover_book_mappings";
+
+-- CreateIndex
+CREATE UNIQUE INDEX "book_mappings_provider_external_book_id_key" ON "book_mappings"("provider", "external_book_id");
+
+-- CreateIndex
+CREATE INDEX "book_mappings_provider_external_book_id_idx" ON "book_mappings"("provider", "external_book_id");
+
+-- CreateIndex
+CREATE INDEX "book_mappings_audible_asin_idx" ON "book_mappings"("audible_asin");

prisma/migrations/20260305000000_add_api_tokens_table/migration.sql

@@ -0,0 +1,33 @@
+-- CreateTable
+CREATE TABLE "api_tokens" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "token_hash" TEXT NOT NULL,
+    "token_prefix" TEXT NOT NULL,
+    "role" TEXT NOT NULL DEFAULT 'user',
+    "created_by_id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "last_used_at" TIMESTAMP(3),
+    "expires_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "api_tokens_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "api_tokens_token_hash_key" ON "api_tokens"("token_hash");
+
+-- CreateIndex
+CREATE INDEX "api_tokens_token_hash_idx" ON "api_tokens"("token_hash");
+
+-- CreateIndex
+CREATE INDEX "api_tokens_created_by_id_idx" ON "api_tokens"("created_by_id");
+
+-- CreateIndex
+CREATE INDEX "api_tokens_user_id_idx" ON "api_tokens"("user_id");
+
+-- AddForeignKey
+ALTER TABLE "api_tokens" ADD CONSTRAINT "api_tokens_created_by_id_fkey" FOREIGN KEY ("created_by_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "api_tokens" ADD CONSTRAINT "api_tokens_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;

prisma/migrations/20260306000000_add_home_sections/migration.sql

@@ -0,0 +1,49 @@
+-- CreateTable
+CREATE TABLE "user_home_sections" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "section_type" TEXT NOT NULL,
+    "category_id" TEXT,
+    "category_name" TEXT,
+    "sort_order" INTEGER NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "user_home_sections_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "audible_cache_categories" (
+    "id" TEXT NOT NULL,
+    "asin" TEXT NOT NULL,
+    "category_id" TEXT NOT NULL,
+    "rank" INTEGER NOT NULL,
+    "last_synced_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "audible_cache_categories_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "user_home_sections_user_id_idx" ON "user_home_sections"("user_id");
+
+-- CreateIndex
+CREATE INDEX "user_home_sections_sort_order_idx" ON "user_home_sections"("sort_order");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "user_home_sections_user_id_section_type_category_id_key" ON "user_home_sections"("user_id", "section_type", "category_id");
+
+-- CreateIndex
+CREATE INDEX "audible_cache_categories_category_id_idx" ON "audible_cache_categories"("category_id");
+
+-- CreateIndex
+CREATE INDEX "audible_cache_categories_asin_idx" ON "audible_cache_categories"("asin");
+
+-- CreateIndex
+CREATE INDEX "audible_cache_categories_category_id_rank_idx" ON "audible_cache_categories"("category_id", "rank");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "audible_cache_categories_asin_category_id_key" ON "audible_cache_categories"("asin", "category_id");
+
+-- AddForeignKey
+ALTER TABLE "user_home_sections" ADD CONSTRAINT "user_home_sections_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;

prisma/migrations/20260307000000_remove_popular_newrelease_flags/migration.sql

@@ -0,0 +1,17 @@
+-- DropIndex
+DROP INDEX IF EXISTS "audible_cache_is_popular_idx";
+
+-- DropIndex
+DROP INDEX IF EXISTS "audible_cache_is_new_release_idx";
+
+-- DropIndex
+DROP INDEX IF EXISTS "audible_cache_popular_rank_idx";
+
+-- DropIndex
+DROP INDEX IF EXISTS "audible_cache_new_release_rank_idx";
+
+-- AlterTable - Remove legacy discovery flag columns (now stored in audible_cache_categories)
+ALTER TABLE "audible_cache" DROP COLUMN "is_popular",
+DROP COLUMN "is_new_release",
+DROP COLUMN "popular_rank",
+DROP COLUMN "new_release_rank";

prisma/migrations/20260311000000_add_ignored_audiobooks/migration.sql

@@ -0,0 +1,24 @@
+-- CreateTable
+CREATE TABLE "ignored_audiobooks" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "asin" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "author" TEXT NOT NULL,
+    "cover_art_url" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "ignored_audiobooks_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "ignored_audiobooks_user_id_idx" ON "ignored_audiobooks"("user_id");
+
+-- CreateIndex
+CREATE INDEX "ignored_audiobooks_asin_idx" ON "ignored_audiobooks"("asin");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "ignored_audiobooks_user_id_asin_key" ON "ignored_audiobooks"("user_id", "asin");
+
+-- AddForeignKey
+ALTER TABLE "ignored_audiobooks" ADD CONSTRAINT "ignored_audiobooks_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;

prisma/migrations/20260312000000_add_login_token_hash/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable - Add login_token_hash column for admin-generated login tokens
+ALTER TABLE "users" ADD COLUMN "login_token_hash" TEXT;

prisma/migrations/20260313000000_add_sessions_invalidated_at/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable - Add sessions_invalidated_at column for immediate session revocation
+ALTER TABLE "users" ADD COLUMN "sessions_invalidated_at" TIMESTAMPTZ;

prisma/schema.prisma

@@ -57,6 +57,12 @@ model User {
   interactiveSearchAccess Boolean? @map("interactive_search_access") // null = use global setting, true = allow, false = deny
   downloadAccess          Boolean? @map("download_access")           // null = use global setting, true = allow, false = deny
 
+  // Login token (admin-generated, for direct URL login)
+  loginTokenHash String? @map("login_token_hash") // SHA-256 hash of the login token (never store plaintext)
+
+  // Session invalidation (set when login token is revoked to force-logout active sessions)
+  sessionsInvalidatedAt DateTime? @map("sessions_invalidated_at")
+
   // Soft delete support
   deletedAt DateTime? @map("deleted_at")
   deletedBy String?   @map("deleted_by") // Admin user ID who deleted this user
@@ -66,8 +72,15 @@ model User {
   bookDateRecommendations BookDateRecommendation[]
   bookDateSwipes          BookDateSwipe[]
   goodreadsShelves        GoodreadsShelf[]
+  hardcoverShelves        HardcoverShelf[]
   reportedIssues          ReportedIssue[]          @relation("Reporter")
   resolvedIssues          ReportedIssue[]          @relation("Resolver")
+  createdApiTokens        ApiToken[]  @relation("CreatedApiTokens")
+  apiTokens               ApiToken[]  @relation("UserApiTokens")
+  watchedSeries           WatchedSeries[]
+  watchedAuthors          WatchedAuthor[]
+  homeSections            UserHomeSection[]
+  ignoredAudiobooks       IgnoredAudiobook[]
 
   @@index([plexId])
   @@index([role])
@@ -94,12 +107,6 @@ model AudibleCache {
   rating          Decimal?  @db.Decimal(3, 2)
   genres          Json      @default("[]")
 
-  // Discovery categories
-  isPopular      Boolean @default(false) @map("is_popular")
-  isNewRelease   Boolean @default(false) @map("is_new_release")
-  popularRank    Int?    @map("popular_rank")
-  newReleaseRank Int?    @map("new_release_rank")
-
   lastSyncedAt DateTime @default(now()) @map("last_synced_at")
   createdAt    DateTime @default(now()) @map("created_at")
   updatedAt    DateTime @updatedAt @map("updated_at")
@@ -107,10 +114,6 @@ model AudibleCache {
   @@index([asin])
   @@index([title])
   @@index([author])
-  @@index([isPopular])
-  @@index([isNewRelease])
-  @@index([popularRank])
-  @@index([newReleaseRank])
   @@map("audible_cache")
 }
 
@@ -232,6 +235,7 @@ model Request {
   importAttempts   Int       @default(0) @map("import_attempts")
   maxImportRetries Int       @default(5) @map("max_import_retries")
   lastSearchAt     DateTime? @map("last_search_at")
+  customSearchTerms String?  @map("custom_search_terms") @db.Text
   lastImportAt     DateTime? @map("last_import_at")
   createdAt        DateTime  @default(now()) @map("created_at")
   updatedAt        DateTime  @updatedAt @map("updated_at")
@@ -391,7 +395,7 @@ model ScheduledJob {
 
 model BookDateConfig {
   id           String   @id @default(uuid())
-  provider     String // 'openai' | 'claude' | 'custom'
+  provider     String // 'openai' | 'claude' | 'gemini' | 'custom'
   apiKey       String   @map("api_key") @db.Text // Encrypted at rest (AES-256)
   model        String // e.g., 'gpt-4o', 'claude-sonnet-4-5-20250929'
   baseUrl      String?  @map("base_url") @db.Text // Base URL for custom provider (OpenAI-compatible endpoints)
@@ -495,6 +499,34 @@ model ReportedIssue {
 // Per-user Goodreads shelf subscriptions + global book-to-ASIN mapping cache
 // ============================================================================
 
+// ============================================================================
+// API TOKEN TABLE
+// Static API tokens for programmatic access (alternative to JWT)
+// Documentation: documentation/backend/services/api-tokens.md
+// ============================================================================
+
+model ApiToken {
+  id          String    @id @default(uuid())
+  name        String // User-friendly label (e.g., "Home Assistant", "Webhook")
+  tokenHash   String    @unique @map("token_hash") // SHA-256 hash of the token (never store plaintext)
+  tokenPrefix String    @map("token_prefix") // First 8 chars for display (e.g., "rmab_a1b2")
+  role        String    @default("user") // Token role: 'admin' or 'user'
+  createdById String    @map("created_by_id") // Who created the token (may differ from userId for admin-created tokens)
+  userId      String    @map("user_id") // The user identity this token acts as
+  lastUsedAt  DateTime? @map("last_used_at")
+  expiresAt   DateTime? @map("expires_at") // null = never expires
+  createdAt   DateTime  @default(now()) @map("created_at")
+
+  // Relations
+  createdBy User @relation("CreatedApiTokens", fields: [createdById], references: [id], onDelete: Cascade)
+  tokenUser User @relation("UserApiTokens", fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([tokenHash])
+  @@index([createdById])
+  @@index([userId])
+  @@map("api_tokens")
+}
+
 model GoodreadsShelf {
   id         String    @id @default(uuid())
   userId     String    @map("user_id")
@@ -502,9 +534,10 @@ model GoodreadsShelf {
   rssUrl     String    @map("rss_url") @db.Text
   lastSyncAt DateTime? @map("last_sync_at")
   bookCount  Int?      @map("book_count")
-  coverUrls  String?   @map("cover_urls") @db.Text // JSON array of cover image URLs
-  createdAt  DateTime  @default(now()) @map("created_at")
-  updatedAt  DateTime  @updatedAt @map("updated_at")
+  coverUrls   String?   @map("cover_urls") @db.Text // JSON array of cover image URLs
+  autoRequest Boolean   @default(true) @map("auto_request") // Whether to auto-create requests for books on this shelf
+  createdAt   DateTime  @default(now()) @map("created_at")
+  updatedAt   DateTime  @updatedAt @map("updated_at")
 
   // Relations
   user User @relation(fields: [userId], references: [id], onDelete: Cascade)
@@ -514,19 +547,221 @@ model GoodreadsShelf {
   @@map("goodreads_shelves")
 }
 
-model GoodreadsBookMapping {
-  id              String    @id @default(uuid())
-  goodreadsBookId String    @unique @map("goodreads_book_id")
-  title           String
-  author          String
-  audibleAsin     String?   @map("audible_asin")
-  coverUrl        String?   @map("cover_url") @db.Text
-  noMatch         Boolean   @default(false) @map("no_match")
-  lastSearchAt    DateTime? @map("last_search_at")
-  createdAt       DateTime  @default(now()) @map("created_at")
-  updatedAt       DateTime  @updatedAt @map("updated_at")
+// ============================================================================
+// UNIFIED BOOK MAPPING TABLE
+// Global book-to-ASIN mapping cache shared across all shelf providers.
+// Uses provider + externalBookId composite key for cross-provider dedup.
+// ============================================================================
 
-  @@index([goodreadsBookId])
+model BookMapping {
+  id             String    @id @default(uuid())
+  provider       String    // "goodreads", "hardcover", etc.
+  externalBookId String    @map("external_book_id")
+  title          String
+  author         String
+  audibleAsin    String?   @map("audible_asin")
+  coverUrl       String?   @map("cover_url") @db.Text
+  noMatch        Boolean   @default(false) @map("no_match")
+  lastSearchAt   DateTime? @map("last_search_at")
+  createdAt      DateTime  @default(now()) @map("created_at")
+  updatedAt      DateTime  @updatedAt @map("updated_at")
+
+  @@unique([provider, externalBookId])
+  @@index([provider, externalBookId])
   @@index([audibleAsin])
-  @@map("goodreads_book_mappings")
+  @@map("book_mappings")
+}
+
+// ============================================================================
+// HARDCOVER SYNC TABLES
+// Per-user Hardcover list subscriptions
+// ============================================================================
+
+model HardcoverShelf {
+  id         String    @id @default(uuid())
+  userId     String    @map("user_id")
+  name       String    // Extracted from Hardcover API list name or status
+  listId     String    @map("list_id") // Hardcover List ID or Status ID
+  apiToken   String    @map("api_token") @db.Text // User's personal access token for hardcover api
+  lastSyncAt DateTime? @map("last_sync_at")
+  bookCount  Int?      @map("book_count")
+  coverUrls   String?   @map("cover_urls") @db.Text // JSON array of cover image URLs
+  autoRequest Boolean   @default(true) @map("auto_request") // Whether to auto-create requests for books on this shelf
+  createdAt   DateTime  @default(now()) @map("created_at")
+  updatedAt   DateTime  @updatedAt @map("updated_at")
+
+  // Relations
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, listId])
+  @@index([userId])
+  @@map("hardcover_shelves")
+}
+
+// ============================================================================
+// WORKS TABLE
+// Cross-ASIN audiobook identity mapping — links multiple Audible ASINs
+// to a single logical work for library matching across editions.
+// Documentation: documentation/integrations/audible.md
+// ============================================================================
+
+model Work {
+  id        String     @id @default(uuid())
+  title     String
+  author    String
+  createdAt DateTime   @default(now()) @map("created_at")
+  updatedAt DateTime   @updatedAt @map("updated_at")
+
+  // Relations
+  asins WorkAsin[]
+
+  @@index([title])
+  @@index([author])
+  @@map("works")
+}
+
+model WorkAsin {
+  id              String   @id @default(uuid())
+  workId          String   @map("work_id")
+  asin            String   @unique
+  narrator        String?
+  durationMinutes Int?     @map("duration_minutes")
+  isCanonical     Boolean  @default(false) @map("is_canonical")
+  source          String   // 'dedup_auto' | 'admin_manual'
+  createdAt       DateTime @default(now()) @map("created_at")
+
+  // Relations
+  work Work @relation(fields: [workId], references: [id], onDelete: Cascade)
+
+  @@index([workId])
+  @@index([asin])
+  @@map("work_asins")
+}
+
+// ============================================================================
+// WATCHED LISTS TABLES
+// Per-user series and author subscriptions for automatic new-release requests.
+// Documentation: documentation/features/watched-lists.md
+// ============================================================================
+
+model WatchedSeries {
+  id            String    @id @default(uuid())
+  userId        String    @map("user_id")
+  seriesAsin    String    @map("series_asin")
+  seriesTitle   String    @map("series_title")
+  coverArtUrl   String?   @map("cover_art_url") @db.Text
+  lastCheckedAt DateTime? @map("last_checked_at")
+  createdAt     DateTime  @default(now()) @map("created_at")
+  updatedAt     DateTime  @updatedAt @map("updated_at")
+
+  // Relations
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, seriesAsin])
+  @@index([userId])
+  @@index([seriesAsin])
+  @@map("watched_series")
+}
+
+model WatchedAuthor {
+  id            String    @id @default(uuid())
+  userId        String    @map("user_id")
+  authorAsin    String    @map("author_asin")
+  authorName    String    @map("author_name")
+  coverArtUrl   String?   @map("cover_art_url") @db.Text
+  lastCheckedAt DateTime? @map("last_checked_at")
+  createdAt     DateTime  @default(now()) @map("created_at")
+  updatedAt     DateTime  @updatedAt @map("updated_at")
+
+  // Relations
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, authorAsin])
+  @@index([userId])
+  @@index([authorAsin])
+  @@map("watched_authors")
+}
+
+// ============================================================================
+// IGNORED AUDIOBOOK TABLE
+// Per-user ignore list for auto-request suppression.
+// Stores the ASIN the user clicked ignore on; works-system expansion
+// happens at check-time in request-creator.service.ts.
+// Documentation: documentation/features/ignored-audiobooks.md
+// ============================================================================
+
+model IgnoredAudiobook {
+  id          String   @id @default(uuid())
+  userId      String   @map("user_id")
+  asin        String   // Audible ASIN that was explicitly ignored
+  title       String   // Display only — snapshot at ignore time
+  author      String   // Display only — snapshot at ignore time
+  coverArtUrl String?  @map("cover_art_url") @db.Text
+  createdAt   DateTime @default(now()) @map("created_at")
+
+  // Relations
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, asin])
+  @@index([userId])
+  @@index([asin])
+  @@map("ignored_audiobooks")
+}
+
+// ============================================================================
+// USER HOME SECTION TABLE
+// Per-user configurable home page sections (popular, new_releases, category)
+// Documentation: documentation/features/home-sections.md
+// ============================================================================
+
+model UserHomeSection {
+  id           String   @id @default(uuid())
+  userId       String   @map("user_id")
+  sectionType  String   @map("section_type") // 'popular' | 'new_releases' | 'category'
+  categoryId   String?  @map("category_id") // Audible category node ID (only for type 'category')
+  categoryName String?  @map("category_name") // Display name (only for type 'category')
+  sortOrder    Int      @map("sort_order")
+  createdAt    DateTime @default(now()) @map("created_at")
+  updatedAt    DateTime @updatedAt @map("updated_at")
+
+  // Relations
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, sectionType, categoryId])
+  @@index([userId])
+  @@index([sortOrder])
+  @@map("user_home_sections")
+}
+
+// ============================================================================
+// AUDIBLE CACHE CATEGORY TABLE
+// Join table linking AudibleCache entries to Audible categories with ranking
+// Documentation: documentation/features/home-sections.md
+// ============================================================================
+
+model AudibleCacheCategory {
+  id           String   @id @default(uuid())
+  asin         String
+  categoryId   String   @map("category_id")
+  rank         Int
+  lastSyncedAt DateTime @default(now()) @map("last_synced_at")
+  createdAt    DateTime @default(now()) @map("created_at")
+
+  @@unique([asin, categoryId])
+  @@index([categoryId])
+  @@index([asin])
+  @@index([categoryId, rank])
+  @@map("audible_cache_categories")
+}
+
+// ============================================================================
+// DATA MIGRATION TRACKING
+// Tracks which data migration SQL scripts have been executed (run-once).
+// ============================================================================
+
+model DataMigration {
+  name       String   @id
+  executedAt DateTime @default(now()) @map("executed_at")
+
+  @@map("_data_migrations")
 }

public/hardcover-icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" class="w-9 group-hover:rotate-12 transition-all duration-300" fill="none" viewBox="0 0 40 40"><path d="M12.8889 32.5982C12.666 31.7661 13.1598 30.9108 13.9919 30.6879L30.2971 26.3189C31.1292 26.096 31.9845 26.5898 32.2075 27.4219L32.8739 29.9089C33.1711 31.0183 32.5127 32.1587 31.4033 32.456L18.1113 36.0176C15.8924 36.6121 13.6116 35.2953 13.0171 33.0764L12.8889 32.5982Z" fill="#4F46E5"></path><path d="M7.62314 12.946C7.05137 10.8121 8.3177 8.61876 10.4516 8.04699L16.8851 32.0571L13.0214 33.0924L7.62314 12.946Z" fill="#4F46E5"></path><path d="M29.3358 24.432L31.2677 23.9144L32.3584 27.985C32.6443 29.052 32.0111 30.1486 30.9442 30.4345L29.3358 24.432Z" fill="#4338CA"></path><path d="M26.4446 5.91475C26.1474 4.80529 25.007 4.14688 23.8975 4.44416L10.5286 8.02636C9.41911 8.32364 8.7607 9.46403 9.05798 10.5735L14.9532 32.5748L22.6461 30.5135C23.1986 30.3654 23.5265 29.7975 23.3785 29.245C23.2304 28.6925 23.5583 28.1245 24.1108 27.9765L29.7949 26.4535C30.9043 26.1562 31.5628 25.0158 31.2655 23.9063L26.4446 5.91475Z" fill="#6366F1"></path><path d="M21.0947 11.2811C21.145 10.6645 21.9408 10.4512 22.2927 10.9601L22.442 11.1761C22.5512 11.3341 22.724 11.4365 22.9151 11.4565L23.2375 11.4902C23.838 11.553 24.0445 12.3235 23.5558 12.6781L23.2935 12.8685C23.138 12.9813 23.0395 13.1564 23.0239 13.3479L23.0026 13.6096C22.9523 14.2262 22.1564 14.4394 21.8046 13.9306L21.6553 13.7146C21.546 13.5566 21.3732 13.4542 21.1821 13.4342L20.8598 13.4005C20.2592 13.3377 20.0528 12.5672 20.5415 12.2126L20.8038 12.0222C20.9593 11.9094 21.0577 11.7343 21.0734 11.5428L21.0947 11.2811Z" fill="#312E81"></path><path d="M18.3031 16.3181C18.3533 15.7015 19.1492 15.4882 19.501 15.9971L20.5634 17.5337C20.6727 17.6917 20.8455 17.7941 21.0366 17.8141L22.9139 18.0104C23.5144 18.0732 23.7208 18.8436 23.2321 19.1983L21.7045 20.3069C21.549 20.4197 21.4506 20.5949 21.435 20.7863L21.2832 22.6482C21.2329 23.2649 20.4371 23.4781 20.0852 22.9692L19.0228 21.4327C18.9136 21.2747 18.7407 21.1722 18.5497 21.1522L16.6724 20.956C16.0719 20.8932 15.8654 20.1227 16.3541 19.7681L17.8817 18.6594C18.0372 18.5466 18.1357 18.3715 18.1513 18.18L18.3031 16.3181Z" fill="#312E81"></path><path d="M14.9532 32.5748C14.6571 31.4697 15.3129 30.3339 16.4179 30.0378L29.8719 26.4328L30.9441 30.4345L17.4902 34.0395C16.3851 34.3356 15.2493 33.6798 14.9532 32.5748Z" fill="#EEF2FF"></path></svg>

public/placeholder_cover.svg

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg width="500px" height="500px" viewBox="0 0 500 500" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <!-- Generator: Sketch 41.2 (35397) - http://www.bohemiancoding.com/sketch -->
+    <title>img-coverart</title>
+    <desc>Created with Sketch.</desc>
+    <defs>
+        <rect id="path-1" x="0" y="0" width="500" height="500"></rect>
+    </defs>
+    <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="Account-details:-membership-asin-doc" transform="translate(-87.000000, -867.000000)">
+            <g id="Group" transform="translate(65.000000, 780.000000)">
+                <g id="img-coverart" transform="translate(22.000000, 87.000000)">
+                    <mask id="mask-2" fill="white">
+                        <use xlink:href="#path-1"></use>
+                    </mask>
+                    <use id="mask" fill="#BBBBBB" xlink:href="#path-1"></use>
+                    <path d="M251.314605,307.191176 L126.315789,229.090627 L126.315789,250.186562 L251.314605,328.289474 L376.315789,250.186562 L376.315789,229.090627 L251.314605,307.191176 Z M300.338486,257.198698 L318.743522,245.697622 L318.757695,245.697622 C304.238718,223.902504 279.436447,209.540923 251.277279,209.540923 C223.146464,209.540923 198.363093,223.878883 183.839389,245.643293 L183.952782,245.655104 C184.933157,244.762229 185.930063,243.885889 186.955321,243.03317 C222.033803,213.960416 272.668324,220.342816 300.338486,257.198698 Z M214.370819,264.53208 C220.980666,259.892912 228.629944,257.226098 236.796575,257.226098 C250.228874,257.226098 262.283922,264.413975 270.556862,275.811119 L288.30989,264.716324 L288.319343,264.716324 C280.157438,253.040453 266.61174,245.39669 251.277753,245.39669 C236.026448,245.39669 222.549266,252.95778 214.370819,264.53208 Z M166.789394,213.901363 C218.255462,173.164548 291.088955,184.079823 329.878678,238.171964 L330.136173,238.568797 L349.186133,226.701596 C328.31953,194.777784 292.263042,173.684211 251.278701,173.684211 C210.866048,173.684211 174.47174,194.572281 153.416152,226.633095 C157.283311,222.56083 162.29621,217.458689 166.789394,213.901363 Z" id="icn-audible" fill="#FFFFFF" mask="url(#mask-2)"></path>
+                </g>
+            </g>
+        </g>
+    </g>
+</svg>

src/app/admin/components/AdjustSearchTermsModal.tsx

@@ -0,0 +1,154 @@
+/**
+ * Component: Adjust Search Terms Modal
+ * Documentation: documentation/admin-dashboard.md
+ */
+
+'use client';
+
+import { useState } from 'react';
+import { Modal } from '@/components/ui/Modal';
+import { fetchWithAuth } from '@/lib/utils/api';
+import { useToast } from '@/components/ui/Toast';
+
+interface AdjustSearchTermsModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  requestId: string;
+  title: string;
+  author: string;
+  currentSearchTerms?: string | null;
+  onSuccess?: () => void;
+}
+
+export function AdjustSearchTermsModal({
+  isOpen,
+  onClose,
+  requestId,
+  title,
+  author,
+  currentSearchTerms,
+  onSuccess,
+}: AdjustSearchTermsModalProps) {
+  const toast = useToast();
+  const [searchTerms, setSearchTerms] = useState(currentSearchTerms || title);
+  const [isSaving, setIsSaving] = useState(false);
+  const [isSavingAndSearching, setIsSavingAndSearching] = useState(false);
+
+  // Reset state when modal opens
+  const handleClose = () => {
+    setSearchTerms(currentSearchTerms || title);
+    onClose();
+  };
+
+  const save = async (triggerSearch: boolean) => {
+    const setter = triggerSearch ? setIsSavingAndSearching : setIsSaving;
+    setter(true);
+
+    try {
+      // If terms match the original title, clear the override
+      const termsToSave = searchTerms.trim() === title ? null : searchTerms.trim() || null;
+
+      const response = await fetchWithAuth(`/api/admin/requests/${requestId}/search-terms`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ searchTerms: termsToSave, triggerSearch }),
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json();
+        throw new Error(errorData.message || 'Failed to update search terms');
+      }
+
+      const data = await response.json();
+
+      if (data.searchTriggered) {
+        toast.success('Search terms saved and search triggered');
+      } else {
+        toast.success('Search terms saved');
+      }
+
+      onSuccess?.();
+      onClose();
+    } catch (error) {
+      toast.error(`Failed to save: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    } finally {
+      setter(false);
+    }
+  };
+
+  const handleReset = () => {
+    setSearchTerms(title);
+  };
+
+  const isLoading = isSaving || isSavingAndSearching;
+  const hasChanges = searchTerms.trim() !== (currentSearchTerms || title);
+  const isCustom = searchTerms.trim() !== title;
+
+  return (
+    <Modal isOpen={isOpen} onClose={handleClose} title="Adjust Search Terms" size="sm">
+      <div className="space-y-4">
+        {/* Original info */}
+        <div className="bg-gray-50 dark:bg-gray-900/50 rounded-lg p-3 space-y-1">
+          <div className="text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
+            Original Title
+          </div>
+          <div className="text-sm text-gray-900 dark:text-gray-100 font-medium">{title}</div>
+          <div className="text-xs text-gray-500 dark:text-gray-400">by {author}</div>
+        </div>
+
+        {/* Search terms input */}
+        <div>
+          <label
+            htmlFor="search-terms"
+            className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1.5"
+          >
+            Search Terms
+          </label>
+          <input
+            id="search-terms"
+            type="text"
+            value={searchTerms}
+            onChange={(e) => setSearchTerms(e.target.value)}
+            disabled={isLoading}
+            className="w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100 text-sm focus:ring-2 focus:ring-blue-500 focus:border-transparent disabled:opacity-50"
+            placeholder="Enter custom search terms..."
+          />
+          {isCustom && (
+            <button
+              onClick={handleReset}
+              disabled={isLoading}
+              className="mt-1.5 text-xs text-blue-600 dark:text-blue-400 hover:text-blue-700 dark:hover:text-blue-300 transition-colors disabled:opacity-50"
+            >
+              Reset to original title
+            </button>
+          )}
+        </div>
+
+        {/* Actions */}
+        <div className="flex items-center justify-end gap-2 pt-2 border-t border-gray-200 dark:border-gray-700">
+          <button
+            onClick={handleClose}
+            disabled={isLoading}
+            className="px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-800 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-700 transition-colors disabled:opacity-50"
+          >
+            Cancel
+          </button>
+          <button
+            onClick={() => save(false)}
+            disabled={isLoading || !searchTerms.trim()}
+            className="px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-800 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-700 transition-colors disabled:opacity-50"
+          >
+            {isSaving ? 'Saving...' : 'Save'}
+          </button>
+          <button
+            onClick={() => save(true)}
+            disabled={isLoading || !searchTerms.trim()}
+            className="px-4 py-2 text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 rounded-lg transition-colors disabled:opacity-50"
+          >
+            {isSavingAndSearching ? 'Saving...' : 'Save & Search'}
+          </button>
+        </div>
+      </div>
+    </Modal>
+  );
+}

src/app/admin/components/ConfirmDialog.tsx

@@ -2,12 +2,13 @@
  * Component: Confirm Dialog
  * Documentation: documentation/frontend/components.md
  *
- * Reusable confirmation dialog for destructive actions
+ * Reusable confirmation dialog for destructive actions.
+ * Features: backdrop blur, smooth enter animation, Escape to close, focus trap, ARIA.
  */
 
 'use client';
 
-import { Fragment } from 'react';
+import React, { useEffect, useRef } from 'react';
 
 export interface ConfirmDialogProps {
   isOpen: boolean;
@@ -30,99 +31,177 @@ export function ConfirmDialog({
   onConfirm,
   onCancel,
 }: ConfirmDialogProps) {
+  const cancelRef = useRef<HTMLButtonElement>(null);
+  const confirmRef = useRef<HTMLButtonElement>(null);
+  const dialogRef = useRef<HTMLDivElement>(null);
+
+  // Focus the cancel button on open (safer default for destructive dialogs)
+  useEffect(() => {
+    if (isOpen) {
+      // Small delay to let animation start before stealing focus
+      const t = setTimeout(() => cancelRef.current?.focus(), 50);
+      return () => clearTimeout(t);
+    }
+  }, [isOpen]);
+
+  // Escape to close + focus trap
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        onCancel();
+        return;
+      }
+
+      // Focus trap: tab cycles only within dialog
+      if (e.key === 'Tab') {
+        const focusable = dialogRef.current?.querySelectorAll<HTMLElement>(
+          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        );
+        if (!focusable || focusable.length === 0) return;
+
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+
+        if (e.shiftKey) {
+          if (document.activeElement === first) {
+            e.preventDefault();
+            last.focus();
+          }
+        } else {
+          if (document.activeElement === last) {
+            e.preventDefault();
+            first.focus();
+          }
+        }
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isOpen, onCancel]);
+
+  // Prevent body scroll while open
+  useEffect(() => {
+    if (isOpen) {
+      document.body.style.overflow = 'hidden';
+      return () => { document.body.style.overflow = ''; };
+    }
+  }, [isOpen]);
+
   if (!isOpen) return null;
 
-  const confirmButtonClasses =
-    confirmVariant === 'danger'
-      ? 'bg-red-600 hover:bg-red-700 text-white'
-      : 'bg-blue-600 hover:bg-blue-700 text-white';
+  const isDestructive = confirmVariant === 'danger';
 
   return (
-    <div className="fixed inset-0 z-50 overflow-y-auto">
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="confirm-dialog-title"
+      aria-describedby="confirm-dialog-desc"
+      className="fixed inset-0 z-50 flex items-center justify-center p-4"
+    >
       {/* Backdrop */}
       <div
-        className="fixed inset-0 bg-black bg-opacity-50 transition-opacity"
+        className="animate-dialog-backdrop fixed inset-0 bg-black/40 backdrop-blur-sm"
         onClick={onCancel}
         aria-hidden="true"
       />
 
-      {/* Dialog */}
-      <div className="flex min-h-full items-center justify-center p-4 text-center sm:p-0">
-        <div className="relative transform overflow-hidden rounded-lg bg-white dark:bg-gray-800 text-left shadow-xl transition-all sm:my-8 sm:w-full sm:max-w-lg">
-          <div className="bg-white dark:bg-gray-800 px-4 pb-4 pt-5 sm:p-6 sm:pb-4">
-            <div className="sm:flex sm:items-start">
-              {/* Icon */}
-              <div
-                className={`mx-auto flex h-12 w-12 flex-shrink-0 items-center justify-center rounded-full ${
-                  confirmVariant === 'danger'
-                    ? 'bg-red-100 dark:bg-red-900'
-                    : 'bg-blue-100 dark:bg-blue-900'
-                } sm:mx-0 sm:h-10 sm:w-10`}
-              >
+      {/* Panel */}
+      <div
+        ref={dialogRef}
+        className="animate-dialog-panel relative w-full max-w-sm rounded-2xl overflow-hidden bg-white dark:bg-gray-900 shadow-2xl ring-1 ring-black/10 dark:ring-white/10"
+      >
+        {/* Header */}
+        <div className="px-6 pt-6 pb-4">
+          <div className="flex items-start gap-4">
+            {/* Icon well */}
+            <div className={`flex-shrink-0 flex items-center justify-center w-10 h-10 rounded-full ${
+              isDestructive
+                ? 'bg-red-50 dark:bg-red-500/10'
+                : 'bg-blue-50 dark:bg-blue-500/10'
+            }`}>
+              {isDestructive ? (
                 <svg
-                  className={`h-6 w-6 ${
-                    confirmVariant === 'danger'
-                      ? 'text-red-600 dark:text-red-400'
-                      : 'text-blue-600 dark:text-blue-400'
-                  }`}
+                  className="w-5 h-5 text-red-500 dark:text-red-400"
                   fill="none"
                   viewBox="0 0 24 24"
-                  strokeWidth="1.5"
+                  strokeWidth="1.75"
                   stroke="currentColor"
+                  aria-hidden="true"
                 >
-                  {confirmVariant === 'danger' ? (
-                    <path
-                      strokeLinecap="round"
-                      strokeLinejoin="round"
-                      d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z"
-                    />
-                  ) : (
-                    <path
-                      strokeLinecap="round"
-                      strokeLinejoin="round"
-                      d="M9.879 7.519c1.171-1.025 3.071-1.025 4.242 0 1.172 1.025 1.172 2.687 0 3.712-.203.179-.43.326-.67.442-.745.361-1.45.999-1.45 1.827v.75M21 12a9 9 0 11-18 0 9 9 0 0118 0zm-9 5.25h.008v.008H12v-.008z"
-                    />
-                  )}
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z"
+                  />
                 </svg>
-              </div>
+              ) : (
+                <svg
+                  className="w-5 h-5 text-blue-500 dark:text-blue-400"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                  strokeWidth="1.75"
+                  stroke="currentColor"
+                  aria-hidden="true"
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    d="M9.879 7.519c1.171-1.025 3.071-1.025 4.242 0 1.172 1.025 1.172 2.687 0 3.712-.203.179-.43.326-.67.442-.745.361-1.45.999-1.45 1.827v.75M21 12a9 9 0 11-18 0 9 9 0 0118 0zm-9 5.25h.008v.008H12v-.008z"
+                  />
+                </svg>
+              )}
+            </div>
 
-              {/* Content */}
-              <div className="mt-3 text-center sm:ml-4 sm:mt-0 sm:text-left flex-1">
-                <h3 className="text-lg font-semibold leading-6 text-gray-900 dark:text-gray-100">
-                  {title}
-                </h3>
-                <div className="mt-2">
-                  {typeof message === 'string' ? (
-                    <p className="text-sm text-gray-500 dark:text-gray-400 whitespace-pre-line">
-                      {message}
-                    </p>
-                  ) : (
-                    <div className="text-sm text-gray-500 dark:text-gray-400">
-                      {message}
-                    </div>
-                  )}
-                </div>
+            {/* Text */}
+            <div className="flex-1 min-w-0 pt-0.5">
+              <h3
+                id="confirm-dialog-title"
+                className="text-base font-semibold leading-6 text-gray-900 dark:text-gray-50"
+              >
+                {title}
+              </h3>
+              <div id="confirm-dialog-desc" className="mt-1.5">
+                {typeof message === 'string' ? (
+                  <p className="text-sm text-gray-500 dark:text-gray-400 leading-relaxed">
+                    {message}
+                  </p>
+                ) : (
+                  <div className="text-sm text-gray-500 dark:text-gray-400 leading-relaxed">
+                    {message}
+                  </div>
+                )}
               </div>
             </div>
           </div>
+        </div>
 
-          {/* Actions */}
-          <div className="bg-gray-50 dark:bg-gray-900 px-4 py-3 sm:flex sm:flex-row-reverse sm:px-6 gap-2">
-            <button
-              type="button"
-              onClick={onConfirm}
-              className={`inline-flex w-full justify-center rounded-lg px-4 py-2 text-sm font-semibold shadow-sm sm:w-auto transition-colors ${confirmButtonClasses}`}
-            >
-              {confirmLabel}
-            </button>
-            <button
-              type="button"
-              onClick={onCancel}
-              className="mt-3 inline-flex w-full justify-center rounded-lg bg-white dark:bg-gray-700 px-4 py-2 text-sm font-semibold text-gray-900 dark:text-gray-100 shadow-sm ring-1 ring-inset ring-gray-300 dark:ring-gray-600 hover:bg-gray-50 dark:hover:bg-gray-600 sm:mt-0 sm:w-auto transition-colors"
-            >
-              {cancelLabel}
-            </button>
-          </div>
+        {/* Action bar */}
+        <div className="flex items-center justify-end gap-2 px-6 py-4 bg-gray-50/80 dark:bg-white/[0.03] border-t border-gray-100 dark:border-white/[0.06]">
+          <button
+            ref={cancelRef}
+            type="button"
+            onClick={onCancel}
+            className="px-4 py-2 text-sm font-medium rounded-xl text-gray-700 dark:text-gray-300 bg-white dark:bg-white/[0.06] hover:bg-gray-100 dark:hover:bg-white/[0.1] border border-gray-200 dark:border-white/[0.1] transition-all duration-150 focus:outline-none focus-visible:ring-2 focus-visible:ring-gray-400 focus-visible:ring-offset-2 dark:focus-visible:ring-offset-gray-900"
+          >
+            {cancelLabel}
+          </button>
+          <button
+            ref={confirmRef}
+            type="button"
+            onClick={onConfirm}
+            className={`px-4 py-2 text-sm font-medium rounded-xl text-white transition-all duration-150 focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 dark:focus-visible:ring-offset-gray-900 active:scale-[0.97] ${
+              isDestructive
+                ? 'bg-red-600 hover:bg-red-700 focus-visible:ring-red-500'
+                : 'bg-blue-600 hover:bg-blue-700 focus-visible:ring-blue-500'
+            }`}
+          >
+            {confirmLabel}
+          </button>
         </div>
       </div>
     </div>

src/app/admin/components/RecentRequestsTable.tsx

@@ -28,6 +28,8 @@ interface RecentRequest {
   completedAt: Date | null;
   errorMessage: string | null;
   torrentUrl?: string | null;
+  downloadAttempts?: number;
+  customSearchTerms?: string | null;
 }
 
 interface User {
@@ -161,7 +163,7 @@ function getInitialParams(): {
   };
 }
 
-export function RecentRequestsTable({ ebookSidecarEnabled = false, annasArchiveBaseUrl = 'https://annas-archive.li' }: RecentRequestsTableProps) {
+export function RecentRequestsTable({ ebookSidecarEnabled = false, annasArchiveBaseUrl = 'https://annas-archive.gl' }: RecentRequestsTableProps) {
   const toast = useToast();
 
   // Get initial filter state from URL (only evaluated once due to lazy init)
@@ -444,6 +446,29 @@ export function RecentRequestsTable({ ebookSidecarEnabled = false, annasArchiveB
     }
   };
 
+  const handleRetryDownload = async (requestId: string) => {
+    try {
+      const response = await fetchWithAuth(`/api/admin/requests/${requestId}/retry-download`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+
+      const responseData = await response.json();
+
+      if (!response.ok) {
+        throw new Error(responseData.message || 'Failed to retry download');
+      }
+
+      toast.success(responseData.message || 'Download retry initiated');
+      await mutate(apiUrl);
+    } catch (error) {
+      console.error('[Admin] Failed to retry download:', error);
+      toast.error(`Failed to retry download: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  };
+
   // Render loading state
   if (isLoading && !data) {
     return (
@@ -638,6 +663,17 @@ export function RecentRequestsTable({ ebookSidecarEnabled = false, annasArchiveB
                               Ebook
                             </span>
                           )}
+                          {request.customSearchTerms && (
+                            <span
+                              className="inline-flex items-center gap-1 px-2 py-0.5 text-xs font-medium rounded-full bg-blue-100 text-blue-700 dark:bg-blue-900 dark:text-blue-200"
+                              title={`Custom search: ${request.customSearchTerms}`}
+                            >
+                              <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z" />
+                              </svg>
+                              Custom Search
+                            </span>
+                          )}
                         </div>
                         <div className="text-sm text-gray-500 dark:text-gray-400">
                           {request.author}
@@ -673,12 +709,16 @@ export function RecentRequestsTable({ ebookSidecarEnabled = false, annasArchiveB
                           type: request.type,
                           asin: request.asin,
                           torrentUrl: request.torrentUrl,
+                          downloadAttempts: request.downloadAttempts,
+                          customSearchTerms: request.customSearchTerms,
                         }}
                         onDelete={handleDeleteClick}
                         onManualSearch={handleManualSearch}
                         onCancel={handleCancel}
+                        onRetryDownload={handleRetryDownload}
                         onViewDetails={(asin) => handleViewDetails(asin, request.status)}
                         onFetchEbook={handleFetchEbook}
+                        onSearchTermsUpdated={() => mutate(apiUrl)}
                         ebookSidecarEnabled={ebookSidecarEnabled}
                         annasArchiveBaseUrl={annasArchiveBaseUrl}
                         isLoading={isDeleting || isFetchingEbook}
@@ -835,7 +875,6 @@ export function RecentRequestsTable({ ebookSidecarEnabled = false, annasArchiveB
           }}
           isAvailable={viewDetailsStatus === 'available' || viewDetailsStatus === 'completed'}
           requestStatus={viewDetailsStatus}
-          hideRequestActions
         />
       )}
     </div>

src/app/admin/components/ReportedIssuesSection.tsx

@@ -114,23 +114,13 @@ export function ReportedIssuesSection({ issues }: ReportedIssuesSectionProps) {
                   <div className="flex gap-3">
                     {/* Cover Image */}
                     <div className="flex-shrink-0">
-                      {issue.audiobook.coverArtUrl ? (
-                        <img
-                          src={issue.audiobook.coverArtUrl}
-                          alt={issue.audiobook.title}
-                          className="w-16 h-16 rounded object-cover"
-                        />
-                      ) : (
-                        <div className="w-16 h-16 rounded bg-gray-200 dark:bg-gray-700 flex items-center justify-center">
-                          <svg
-                            className="w-8 h-8 text-gray-400 dark:text-gray-600"
-                            fill="currentColor"
-                            viewBox="0 0 20 20"
-                          >
-                            <path d="M9 4.804A7.968 7.968 0 005.5 4c-1.255 0-2.443.29-3.5.804v10A7.969 7.969 0 015.5 14c1.669 0 3.218.51 4.5 1.385A7.962 7.962 0 0114.5 14c1.255 0 2.443.29 3.5.804v-10A7.968 7.968 0 0014.5 4c-1.255 0-2.443.29-3.5.804V12a1 1 0 11-2 0V4.804z" />
-                          </svg>
-                        </div>
-                      )}
+                      {/* eslint-disable-next-line @next/next/no-img-element */}
+                      <img
+                        src={issue.audiobook.coverArtUrl || '/placeholder_cover.svg'}
+                        alt={issue.audiobook.title}
+                        className="w-16 h-16 rounded object-cover"
+                        onError={(e) => { (e.target as HTMLImageElement).src = '/placeholder_cover.svg'; }}
+                      />
                     </div>
 
                     {/* Info */}

src/app/admin/components/RequestActionsDropdown.tsx

@@ -10,6 +10,7 @@
 import { useState, useRef, useEffect } from 'react';
 import { createPortal } from 'react-dom';
 import { InteractiveTorrentSearchModal } from '@/components/requests/InteractiveTorrentSearchModal';
+import { AdjustSearchTermsModal } from './AdjustSearchTermsModal';
 import { useSmartDropdownPosition } from '@/hooks/useSmartDropdownPosition';
 
 export interface RequestActionsDropdownProps {
@@ -21,12 +22,16 @@ export interface RequestActionsDropdownProps {
     type?: 'audiobook' | 'ebook';
     asin?: string | null;
     torrentUrl?: string | null;
+    downloadAttempts?: number;
+    customSearchTerms?: string | null;
   };
   onDelete: (requestId: string, title: string) => void;
   onManualSearch: (requestId: string) => Promise<void>;
   onCancel: (requestId: string) => Promise<void>;
+  onRetryDownload?: (requestId: string) => Promise<void>;
   onViewDetails?: (asin: string) => void;
   onFetchEbook?: (requestId: string) => Promise<void>;
+  onSearchTermsUpdated?: () => void;
   ebookSidecarEnabled?: boolean;
   annasArchiveBaseUrl?: string;
   isLoading?: boolean;
@@ -37,15 +42,18 @@ export function RequestActionsDropdown({
   onDelete,
   onManualSearch,
   onCancel,
+  onRetryDownload,
   onViewDetails,
   onFetchEbook,
+  onSearchTermsUpdated,
   ebookSidecarEnabled = false,
-  annasArchiveBaseUrl = 'https://annas-archive.li',
+  annasArchiveBaseUrl = 'https://annas-archive.gl',
   isLoading = false,
 }: RequestActionsDropdownProps) {
   const [isOpen, setIsOpen] = useState(false);
   const [showInteractiveSearch, setShowInteractiveSearch] = useState(false);
   const [showInteractiveSearchEbook, setShowInteractiveSearchEbook] = useState(false);
+  const [showAdjustSearchTerms, setShowAdjustSearchTerms] = useState(false);
   const { containerRef, dropdownRef, positionAbove, style } = useSmartDropdownPosition(isOpen);
 
   // Determine request type
@@ -54,10 +62,11 @@ export function RequestActionsDropdown({
   // View Details: available when ASIN exists (audiobook requests only)
   const canViewDetails = !isEbook && !!request.asin && !!onViewDetails;
 
-  // Determine available actions based on status and type
-  // Ebooks don't support manual/interactive search (Anna's Archive only)
-  const canSearch = !isEbook && ['pending', 'failed', 'awaiting_search'].includes(request.status);
-  const canCancel = ['pending', 'searching', 'downloading'].includes(request.status);
+  // Determine available actions based on status
+  const canSearch = ['pending', 'failed', 'awaiting_search'].includes(request.status);
+  const canAdjustSearchTerms = ['pending', 'failed', 'awaiting_search', 'searching'].includes(request.status);
+  const canRetryDownload = request.status === 'failed' && (request.downloadAttempts ?? 0) > 0 && !!onRetryDownload;
+  const canCancel = ['pending', 'searching', 'downloading', 'awaiting_search'].includes(request.status);
   const canDelete = true; // Admins can always delete
 
   // View Source: For ebooks, extract MD5 from slow download URL and link to Anna's Archive
@@ -120,7 +129,16 @@ export function RequestActionsDropdown({
 
   const handleInteractiveSearch = () => {
     setIsOpen(false);
-    setShowInteractiveSearch(true);
+    if (isEbook) {
+      setShowInteractiveSearchEbook(true);
+    } else {
+      setShowInteractiveSearch(true);
+    }
+  };
+
+  const handleAdjustSearchTerms = () => {
+    setIsOpen(false);
+    setShowAdjustSearchTerms(true);
   };
 
   const handleInteractiveSearchEbook = () => {
@@ -128,6 +146,17 @@ export function RequestActionsDropdown({
     setShowInteractiveSearchEbook(true);
   };
 
+  const handleRetryDownload = async () => {
+    setIsOpen(false);
+    if (onRetryDownload) {
+      try {
+        await onRetryDownload(request.requestId);
+      } catch (error) {
+        console.error('Failed to retry download:', error);
+      }
+    }
+  };
+
   const handleCancel = async () => {
     setIsOpen(false);
     if (window.confirm(`Are you sure you want to cancel the request for "${request.title}"?`)) {
@@ -253,6 +282,35 @@ export function RequestActionsDropdown({
               </button>
             )}
 
+            {/* Adjust Search Terms */}
+            {canAdjustSearchTerms && (
+              <button
+                onClick={handleAdjustSearchTerms}
+                className="w-full text-left px-4 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 flex items-center gap-2 transition-colors"
+                role="menuitem"
+              >
+                <svg
+                  className="w-4 h-4"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={2}
+                    d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z"
+                  />
+                </svg>
+                <span className="flex items-center gap-1.5">
+                  Adjust Search Terms
+                  {request.customSearchTerms && (
+                    <span className="w-1.5 h-1.5 rounded-full bg-blue-500 flex-shrink-0" />
+                  )}
+                </span>
+              </button>
+            )}
+
             {/* View Source */}
             {canViewSource && viewSourceUrl && (
               <a
@@ -328,8 +386,32 @@ export function RequestActionsDropdown({
               </button>
             )}
 
-            {/* Divider if we have search/view actions and other actions */}
-            {(canSearch || canViewSource || canFetchEbook) && (canCancel || canDelete) && (
+            {/* Retry Download */}
+            {canRetryDownload && (
+              <button
+                onClick={handleRetryDownload}
+                className="w-full text-left px-4 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 flex items-center gap-2 transition-colors"
+                role="menuitem"
+              >
+                <svg
+                  className="w-4 h-4"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={2}
+                    d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4"
+                  />
+                </svg>
+                Retry Download
+              </button>
+            )}
+
+            {/* Divider if we have search/view/retry actions and other actions */}
+            {(canSearch || canViewSource || canFetchEbook || canRetryDownload) && (canCancel || canDelete) && (
               <div className="border-t border-gray-200 dark:border-gray-700 my-1" />
             )}
 
@@ -358,7 +440,7 @@ export function RequestActionsDropdown({
             )}
 
             {/* Divider before delete */}
-            {canDelete && (canSearch || canCancel) && (
+            {canDelete && (canSearch || canRetryDownload || canCancel) && (
               <div className="border-t border-gray-200 dark:border-gray-700 my-1" />
             )}
 
@@ -421,6 +503,7 @@ export function RequestActionsDropdown({
           title: request.title,
           author: request.author,
         }}
+        customSearchTerms={request.customSearchTerms}
       />
 
       {/* Interactive Search Modal (Ebook) */}
@@ -433,6 +516,18 @@ export function RequestActionsDropdown({
           author: request.author,
         }}
         searchMode="ebook"
+        customSearchTerms={request.customSearchTerms}
+      />
+
+      {/* Adjust Search Terms Modal */}
+      <AdjustSearchTermsModal
+        isOpen={showAdjustSearchTerms}
+        onClose={() => setShowAdjustSearchTerms(false)}
+        requestId={request.requestId}
+        title={request.title}
+        author={request.author}
+        currentSearchTerms={request.customSearchTerms}
+        onSuccess={onSearchTermsUpdated}
       />
     </>
   );

src/app/admin/page.tsx

@@ -14,6 +14,7 @@ import { RecentRequestsTable } from './components/RecentRequestsTable';
 import { ToastProvider, useToast } from '@/components/ui/Toast';
 import { ReportedIssuesSection } from './components/ReportedIssuesSection';
 import { InteractiveTorrentSearchModal } from '@/components/requests/InteractiveTorrentSearchModal';
+import { BulkImportWizard } from '@/components/admin/BulkImportWizard';
 import { TorrentResult } from '@/lib/utils/ranking-algorithm';
 import { formatDistanceToNow } from 'date-fns';
 import { useState } from 'react';
@@ -176,23 +177,13 @@ function PendingApprovalSection({ requests }: { requests: PendingApprovalRequest
                 <div className="flex gap-3">
                   {/* Cover Image */}
                   <div className="flex-shrink-0">
-                    {request.audiobook.coverArtUrl ? (
-                      <img
-                        src={request.audiobook.coverArtUrl}
-                        alt={request.audiobook.title}
-                        className="w-16 h-16 rounded object-cover"
-                      />
-                    ) : (
-                      <div className="w-16 h-16 rounded bg-gray-200 dark:bg-gray-700 flex items-center justify-center">
-                        <svg
-                          className="w-8 h-8 text-gray-400 dark:text-gray-600"
-                          fill="currentColor"
-                          viewBox="0 0 20 20"
-                        >
-                          <path d="M9 4.804A7.968 7.968 0 005.5 4c-1.255 0-2.443.29-3.5.804v10A7.969 7.969 0 015.5 14c1.669 0 3.218.51 4.5 1.385A7.962 7.962 0 0114.5 14c1.255 0 2.443.29 3.5.804v-10A7.968 7.968 0 0014.5 4c-1.255 0-2.443.29-3.5.804V12a1 1 0 11-2 0V4.804z" />
-                        </svg>
-                      </div>
-                    )}
+                    {/* eslint-disable-next-line @next/next/no-img-element */}
+                    <img
+                      src={request.audiobook.coverArtUrl || '/placeholder_cover.svg'}
+                      alt={request.audiobook.title}
+                      className="w-16 h-16 rounded object-cover"
+                      onError={(e) => { (e.target as HTMLImageElement).src = '/placeholder_cover.svg'; }}
+                    />
                   </div>
 
                   {/* Book Info */}
@@ -389,6 +380,8 @@ function PendingApprovalSection({ requests }: { requests: PendingApprovalRequest
 }
 
 function AdminDashboardContent() {
+  const [isBulkImportOpen, setIsBulkImportOpen] = useState(false);
+
   // Fetch data with auto-refresh every 10 seconds
   const { data: metrics, error: metricsError } = useSWR(
     '/api/admin/metrics',
@@ -582,7 +575,7 @@ function AdminDashboardContent() {
             </div>
 
             {/* Quick Actions */}
-            <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 mb-8">
+            <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-5 gap-4 mb-8">
               <Link
                 href="/admin/settings"
                 className="block p-6 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg hover:shadow-md transition-all"
@@ -667,8 +660,38 @@ function AdminDashboardContent() {
                   </span>
                 </div>
               </Link>
+
+              <button
+                onClick={() => setIsBulkImportOpen(true)}
+                className="block p-6 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg hover:shadow-md transition-all text-left"
+              >
+                <div className="flex items-center gap-3">
+                  <svg
+                    className="w-6 h-6 text-gray-600 dark:text-gray-400"
+                    fill="none"
+                    stroke="currentColor"
+                    viewBox="0 0 24 24"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M12 10v6m0 0l-3-3m3 3l3-3m2 8H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
+                    />
+                  </svg>
+                  <span className="font-medium text-gray-900 dark:text-gray-100">
+                    Bulk Import
+                  </span>
+                </div>
+              </button>
             </div>
 
+            {/* Bulk Import Wizard Modal */}
+            <BulkImportWizard
+              isOpen={isBulkImportOpen}
+              onClose={() => setIsBulkImportOpen(false)}
+            />
+
             {/* Requests Awaiting Approval */}
             {pendingApprovalData?.requests && pendingApprovalData.requests.length > 0 && (
               <PendingApprovalSection requests={pendingApprovalData.requests} />

src/app/admin/settings/lib/helpers.ts

@@ -210,6 +210,7 @@ export const getTabValidation = (
       return validated.paths;
     case 'ebook':
     case 'bookdate':
+    case 'api':
       return true; // These tabs handle their own saving
     default:
       return false;
@@ -228,4 +229,5 @@ export const getTabs = (backendMode: 'plex' | 'audiobookshelf') => [
   { id: 'ebook' as const, label: 'E-book Sidecar', icon: '📖' },
   { id: 'bookdate' as const, label: 'BookDate', icon: '📚' },
   { id: 'notifications' as const, label: 'Notifications', icon: '🔔' },
+  { id: 'api' as const, label: 'API', icon: '🔑' },
 ];

src/app/admin/settings/lib/types.ts

@@ -102,6 +102,8 @@ export interface PathsSettings {
   chapterMergingEnabled: boolean;
   fileRenameEnabled: boolean;
   fileRenameTemplate?: string;
+  fileChmod?: string;
+  dirChmod?: string;
 }
 
 /**
@@ -243,4 +245,4 @@ export interface BookDateModel {
 /**
  * Tab identifier type
  */
-export type SettingsTab = 'library' | 'auth' | 'prowlarr' | 'download' | 'paths' | 'ebook' | 'bookdate' | 'notifications';
+export type SettingsTab = 'library' | 'auth' | 'prowlarr' | 'download' | 'paths' | 'ebook' | 'bookdate' | 'notifications' | 'api';

src/app/admin/settings/page.tsx

@@ -23,6 +23,7 @@ import { PathsTab } from './tabs/PathsTab/PathsTab';
 import { EbookTab } from './tabs/EbookTab/EbookTab';
 import { BookDateTab } from './tabs/BookDateTab/BookDateTab';
 import { NotificationsTab } from './tabs/NotificationsTab';
+import { ApiTab } from './tabs/ApiTab/ApiTab';
 
 // Types and Helpers
 import type { Settings, SettingsTab, IndexerConfig, SavedIndexerConfig, Message } from './lib/types';
@@ -346,8 +347,11 @@ export default function AdminSettings() {
           {/* Notifications Tab */}
           {activeTab === 'notifications' && <NotificationsTab />}
 
+          {/* API Tab */}
+          {activeTab === 'api' && <ApiTab />}
+
           {/* Save Button (only for tabs that save through main page) */}
-          {activeTab !== 'ebook' && activeTab !== 'bookdate' && activeTab !== 'notifications' && (
+          {activeTab !== 'ebook' && activeTab !== 'bookdate' && activeTab !== 'notifications' && activeTab !== 'api' && (
             <div className="mt-8 flex gap-4">
               <Button
                 onClick={saveSettings}

src/app/admin/settings/tabs/ApiTab/ApiTab.tsx

@@ -0,0 +1,307 @@
+/**
+ * Component: API Token Management Tab (Admin)
+ * Documentation: documentation/backend/services/api-tokens.md
+ */
+
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+import { fetchWithAuth } from '@/lib/utils/api';
+import { ConfirmDialog } from '@/app/admin/components/ConfirmDialog';
+import { useApiTokens } from '@/lib/hooks/useApiTokens';
+import { getInstanceUrl } from '@/lib/utils/client-url';
+import Link from 'next/link';
+import type { AdminApiToken } from '@/lib/types/api-tokens';
+
+interface UserOption {
+  id: string;
+  plexUsername: string;
+  role: string;
+}
+
+export function ApiTab() {
+  const api = useApiTokens<AdminApiToken>({ basePath: '/api/admin/api-tokens' });
+
+  // Admin-specific state
+  const [users, setUsers] = useState<UserOption[]>([]);
+  const [newTokenUserId, setNewTokenUserId] = useState('');
+
+  const fetchUsers = useCallback(async () => {
+    try {
+      const response = await fetchWithAuth('/api/admin/users');
+      if (response.ok) {
+        const data = await response.json();
+        setUsers(data.users.map((u: any) => ({ id: u.id, plexUsername: u.plexUsername, role: u.role })));
+      }
+    } catch {
+      // Non-critical, user selector just won't populate
+    }
+  }, []);
+
+  useEffect(() => {
+    fetchUsers();
+  }, [fetchUsers]);
+
+  const handleCreate = async () => {
+    const extraBody: Record<string, string> = {};
+    if (newTokenUserId) extraBody.userId = newTokenUserId;
+    const created = await api.handleCreate(extraBody);
+    // Reset admin-specific fields only when create succeeds
+    if (created) {
+      setNewTokenUserId('');
+    }
+  };
+
+  const handleCancel = () => {
+    api.resetForm();
+    setNewTokenUserId('');
+  };
+
+  if (api.loading) {
+    return (
+      <div className="flex items-center justify-center py-12">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600"></div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-6">
+      <div>
+        <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100">API Tokens</h2>
+        <p className="text-sm text-gray-500 dark:text-gray-400 mt-1">
+          Manage API tokens for all users. Create tokens for any user for programmatic access.{' '}
+          <Link href="/api-docs" className="text-blue-600 dark:text-blue-400 hover:underline">
+            View API documentation
+          </Link>
+        </p>
+      </div>
+
+      {/* Error display */}
+      {api.error && (
+        <div className="p-3 rounded-lg bg-red-50 dark:bg-red-900/20 text-red-800 dark:text-red-200 text-sm">
+          {api.error}
+        </div>
+      )}
+
+      {/* Newly created token banner */}
+      {api.createdToken && (
+        <div className="p-4 rounded-lg bg-green-50 dark:bg-green-900/20 border border-green-200 dark:border-green-800">
+          <div className="flex items-start gap-3">
+            <svg className="w-5 h-5 text-green-600 dark:text-green-400 mt-0.5 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+            </svg>
+            <div className="flex-1 min-w-0">
+              <p className="text-sm font-medium text-green-800 dark:text-green-200">
+                Token created successfully! Copy it now — it won&apos;t be shown again.
+              </p>
+              <div className="mt-2 flex items-center gap-2">
+                <code className="flex-1 text-sm bg-white dark:bg-gray-900 px-3 py-2 rounded border border-green-300 dark:border-green-700 text-gray-900 dark:text-gray-100 font-mono break-all">
+                  {api.createdToken}
+                </code>
+                <button
+                  onClick={api.handleCopy}
+                  className="flex-shrink-0 px-3 py-2 text-sm font-medium rounded-lg bg-green-600 hover:bg-green-700 text-white transition-colors"
+                >
+                  {api.copied ? 'Copied!' : 'Copy'}
+                </button>
+              </div>
+            </div>
+                <button
+                  type="button"
+                  aria-label="Dismiss token banner"
+                  onClick={api.dismissCreatedToken}
+                  className="flex-shrink-0 text-green-600 dark:text-green-400 hover:text-green-800 dark:hover:text-green-200"
+                >
+              <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+              </svg>
+            </button>
+          </div>
+        </div>
+      )}
+
+      {/* Create token form */}
+      {api.showCreateForm ? (
+        <div className="p-4 rounded-lg border border-gray-200 dark:border-gray-700 bg-gray-50 dark:bg-gray-900/50 space-y-4">
+          <h3 className="text-sm font-medium text-gray-900 dark:text-gray-100">Create New Token</h3>
+          <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+            <div>
+              <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">
+                Name
+              </label>
+              <input
+                type="text"
+                value={api.newTokenName}
+                onChange={(e) => api.setNewTokenName(e.target.value)}
+                placeholder="e.g., Home Assistant, Webhook"
+                className="w-full rounded-lg border border-gray-300 dark:border-gray-600 bg-white dark:bg-gray-800 px-3 py-2 text-sm text-gray-900 dark:text-gray-100 focus:border-blue-500 focus:ring-1 focus:ring-blue-500"
+                onKeyDown={(e) => e.key === 'Enter' && handleCreate()}
+              />
+            </div>
+            <div>
+              <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">
+                Expiration
+              </label>
+              <select
+                value={api.newTokenExpiry}
+                onChange={(e) => api.setNewTokenExpiry(e.target.value)}
+                className="w-full rounded-lg border border-gray-300 dark:border-gray-600 bg-white dark:bg-gray-800 px-3 py-2 text-sm text-gray-900 dark:text-gray-100 focus:border-blue-500 focus:ring-1 focus:ring-blue-500"
+              >
+                <option value="never">Never</option>
+                <option value="30d">30 days</option>
+                <option value="90d">90 days</option>
+                <option value="1y">1 year</option>
+              </select>
+            </div>
+            <div>
+              <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">
+                User (acts as)
+              </label>
+              <select
+                value={newTokenUserId}
+                onChange={(e) => setNewTokenUserId(e.target.value)}
+                className="w-full rounded-lg border border-gray-300 dark:border-gray-600 bg-white dark:bg-gray-800 px-3 py-2 text-sm text-gray-900 dark:text-gray-100 focus:border-blue-500 focus:ring-1 focus:ring-blue-500"
+              >
+                <option value="">Current user (default)</option>
+                {users.map((u) => (
+                  <option key={u.id} value={u.id}>
+                    {u.plexUsername} ({u.role})
+                  </option>
+                ))}
+              </select>
+              <p className="mt-1 text-xs text-gray-500 dark:text-gray-400">
+                Token will inherit the selected user&apos;s role
+              </p>
+            </div>
+          </div>
+          <div className="flex gap-2">
+            <button
+              onClick={handleCreate}
+              disabled={api.creating || !api.newTokenName.trim()}
+              className="px-4 py-2 text-sm font-medium rounded-lg bg-blue-600 hover:bg-blue-700 disabled:bg-blue-400 text-white transition-colors"
+            >
+              {api.creating ? 'Creating...' : 'Create Token'}
+            </button>
+            <button
+              onClick={handleCancel}
+              className="px-4 py-2 text-sm font-medium rounded-lg bg-gray-200 dark:bg-gray-700 hover:bg-gray-300 dark:hover:bg-gray-600 text-gray-900 dark:text-gray-100 transition-colors"
+            >
+              Cancel
+            </button>
+          </div>
+        </div>
+      ) : (
+        <button
+          onClick={() => api.setShowCreateForm(true)}
+          className="px-4 py-2 text-sm font-medium rounded-lg bg-blue-600 hover:bg-blue-700 text-white transition-colors"
+        >
+          Create New Token
+        </button>
+      )}
+
+      {/* Token list */}
+      {api.tokens.length === 0 ? (
+        <div className="text-center py-8 text-gray-500 dark:text-gray-400">
+          <svg className="mx-auto h-12 w-12 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M15 7a2 2 0 012 2m4 0a6 6 0 01-7.743 5.743L11 17H9v2H7v2H4a1 1 0 01-1-1v-2.586a1 1 0 01.293-.707l5.964-5.964A6 6 0 1121 9z" />
+          </svg>
+          <p className="mt-2 text-sm">No API tokens yet</p>
+          <p className="text-xs mt-1">Create a token to enable programmatic API access</p>
+        </div>
+      ) : (
+        <div className="overflow-x-auto">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-gray-200 dark:border-gray-700">
+                <th className="text-left py-3 px-2 font-medium text-gray-500 dark:text-gray-400">Name</th>
+                <th className="text-left py-3 px-2 font-medium text-gray-500 dark:text-gray-400">Token</th>
+                <th className="text-left py-3 px-2 font-medium text-gray-500 dark:text-gray-400">Acts As</th>
+                <th className="text-left py-3 px-2 font-medium text-gray-500 dark:text-gray-400">Role</th>
+                <th className="text-left py-3 px-2 font-medium text-gray-500 dark:text-gray-400">Created By</th>
+                <th className="text-left py-3 px-2 font-medium text-gray-500 dark:text-gray-400">Last Used</th>
+                <th className="text-left py-3 px-2 font-medium text-gray-500 dark:text-gray-400">Expires</th>
+                <th className="text-right py-3 px-2 font-medium text-gray-500 dark:text-gray-400">Actions</th>
+              </tr>
+            </thead>
+            <tbody>
+              {api.tokens.map((token) => (
+                <tr key={token.id} className="border-b border-gray-100 dark:border-gray-800">
+                  <td className="py-3 px-2 text-gray-900 dark:text-gray-100 font-medium">{token.name}</td>
+                  <td className="py-3 px-2">
+                    <code className="text-xs bg-gray-100 dark:bg-gray-900 px-2 py-1 rounded text-gray-600 dark:text-gray-400 font-mono">
+                      {token.tokenPrefix}...
+                    </code>
+                  </td>
+                  <td className="py-3 px-2 text-gray-500 dark:text-gray-400">{token.tokenUser}</td>
+                  <td className="py-3 px-2">
+                    <span className={`inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium ${
+                      token.role === 'admin'
+                        ? 'bg-purple-100 dark:bg-purple-900/30 text-purple-700 dark:text-purple-300'
+                        : 'bg-gray-100 dark:bg-gray-700 text-gray-600 dark:text-gray-400'
+                    }`}>
+                      {token.role}
+                    </span>
+                  </td>
+                  <td className="py-3 px-2 text-gray-500 dark:text-gray-400">{token.createdBy}</td>
+                  <td className="py-3 px-2 text-gray-500 dark:text-gray-400">{api.formatDate(token.lastUsedAt)}</td>
+                  <td className="py-3 px-2 text-gray-500 dark:text-gray-400">
+                    {token.expiresAt ? (
+                      <span className={new Date(token.expiresAt) < new Date() ? 'text-red-500' : ''}>
+                        {api.formatDate(token.expiresAt)}
+                        {new Date(token.expiresAt) < new Date() && ' (expired)'}
+                      </span>
+                    ) : (
+                      'Never'
+                    )}
+                  </td>
+                  <td className="py-3 px-2 text-right">
+                    <button
+                      onClick={() => api.setConfirmRevokeId(token.id)}
+                      disabled={api.deletingId === token.id}
+                      className="px-3 py-1 text-xs font-medium rounded-lg bg-red-100 dark:bg-red-900/30 hover:bg-red-200 dark:hover:bg-red-900/50 text-red-700 dark:text-red-300 transition-colors disabled:opacity-50"
+                    >
+                      {api.deletingId === token.id ? 'Revoking...' : 'Revoke'}
+                    </button>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+
+      {/* Usage instructions */}
+      <div className="p-4 rounded-lg bg-gray-50 dark:bg-gray-900/50 border border-gray-200 dark:border-gray-700">
+        <h3 className="text-sm font-medium text-gray-900 dark:text-gray-100 mb-2">Usage</h3>
+        <p className="text-sm text-gray-600 dark:text-gray-400 mb-2">
+          Include the token in the <code className="px-1 py-0.5 bg-gray-200 dark:bg-gray-800 rounded text-xs">Authorization</code> header:
+        </p>
+        <pre className="text-xs bg-gray-900 dark:bg-black text-gray-100 p-3 rounded-lg overflow-x-auto">
+{`curl -H "Authorization: Bearer rmab_your_token_here" \\
+  ${getInstanceUrl()}/api/requests`}
+        </pre>
+      </div>
+
+      {/* Revoke confirmation dialog */}
+      <ConfirmDialog
+        isOpen={api.confirmRevokeId !== null}
+        title="Revoke API token"
+        message={
+          <>
+            Are you sure you want to revoke{' '}
+            <span className="font-medium text-gray-700 dark:text-gray-200">
+              &ldquo;{api.tokens.find((t) => t.id === api.confirmRevokeId)?.name ?? 'this token'}&rdquo;
+            </span>
+            ? Any integrations using this token will immediately lose access. This cannot be undone.
+          </>
+        }
+        confirmLabel="Revoke token"
+        cancelLabel="Cancel"
+        confirmVariant="danger"
+        onConfirm={api.handleDeleteConfirmed}
+        onCancel={() => api.setConfirmRevokeId(null)}
+      />
+    </div>
+  );
+}

src/app/admin/settings/tabs/BookDateTab/BookDateTab.tsx

@@ -90,6 +90,7 @@ export function BookDateTab({ onSuccess, onError }: BookDateTabProps) {
         >
           <option value="openai">OpenAI</option>
           <option value="claude">Claude (Anthropic)</option>
+          <option value="gemini">Google Gemini</option>
           <option value="custom">Custom (OpenAI-compatible)</option>
         </select>
       </div>
@@ -136,7 +137,7 @@ export function BookDateTab({ onSuccess, onError }: BookDateTabProps) {
               ? 'Leave blank for local models'
               : configured
                 ? '••••••••••••••••'
-                : (provider === 'openai' ? 'sk-...' : 'sk-ant-...')
+                : (provider === 'openai' ? 'sk-...' : provider === 'gemini' ? 'AIza...' : 'sk-ant-...')
           }
         />
         <p className="text-sm text-gray-500 dark:text-gray-400 mt-1">

src/app/admin/settings/tabs/EbookTab/EbookTab.tsx

@@ -90,9 +90,9 @@ export function EbookTab({ ebook, onChange, onSuccess, onError, markAsSaved }: E
                 </label>
                 <Input
                   type="text"
-                  value={ebook.baseUrl || 'https://annas-archive.li'}
+                  value={ebook.baseUrl || 'https://annas-archive.gl'}
                   onChange={(e) => updateEbook('baseUrl', e.target.value)}
-                  placeholder="https://annas-archive.li"
+                  placeholder="https://annas-archive.gl"
                   className="font-mono"
                 />
                 <p className="text-sm text-gray-500 dark:text-gray-400 mt-1">

src/app/admin/settings/tabs/EbookTab/useEbookSettings.ts

@@ -53,7 +53,7 @@ export function useEbookSettings({ ebook, onChange, onSuccess, onError, markAsSa
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
           url: ebook.flaresolverrUrl,
-          baseUrl: ebook.baseUrl || 'https://annas-archive.li',
+          baseUrl: ebook.baseUrl || 'https://annas-archive.gl',
         }),
       });
 
@@ -83,7 +83,7 @@ export function useEbookSettings({ ebook, onChange, onSuccess, onError, markAsSa
           annasArchiveEnabled: ebook.annasArchiveEnabled || false,
           indexerSearchEnabled: ebook.indexerSearchEnabled || false,
           format: ebook.preferredFormat || 'epub',
-          baseUrl: ebook.baseUrl || 'https://annas-archive.li',
+          baseUrl: ebook.baseUrl || 'https://annas-archive.gl',
           flaresolverrUrl: ebook.flaresolverrUrl || '',
           autoGrabEnabled: ebook.autoGrabEnabled ?? true,
           kindleFixEnabled: ebook.kindleFixEnabled ?? false,

src/app/admin/settings/tabs/PathsTab/PathsTab.tsx

@@ -439,6 +439,54 @@ export function PathsTab({ paths, onChange, onValidationChange }: PathsTabProps)
         </div>
       </div>
 
+      {/* File Permissions */}
+      <div className="bg-gray-50 dark:bg-gray-800 rounded-lg p-4 border border-gray-200 dark:border-gray-700">
+        <h3 className="text-sm font-semibold text-gray-900 dark:text-gray-100 mb-3">
+          File Permissions
+        </h3>
+        <p className="text-sm text-gray-600 dark:text-gray-400 mb-4">
+          Octal permissions applied when organizing files into the media library. These may be further restricted by the container&apos;s UMASK setting.
+        </p>
+        <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+          <div>
+            <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
+              File Permissions
+            </label>
+            <Input
+              type="text"
+              value={paths.fileChmod || '664'}
+              onChange={(e) => updatePath('fileChmod', e.target.value)}
+              placeholder="664"
+              className={`font-mono max-w-32 ${paths.fileChmod && !/^[0-7]{3,4}$/.test(paths.fileChmod) ? 'border-red-500 dark:border-red-500' : ''}`}
+            />
+            {paths.fileChmod && !/^[0-7]{3,4}$/.test(paths.fileChmod) && (
+              <p className="text-xs text-red-600 dark:text-red-400 mt-1">Must be 3-4 octal digits (0-7)</p>
+            )}
+            <p className="text-xs text-gray-500 dark:text-gray-400 mt-1">
+              e.g. 664 = owner/group read-write, others read
+            </p>
+          </div>
+          <div>
+            <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
+              Directory Permissions
+            </label>
+            <Input
+              type="text"
+              value={paths.dirChmod || '775'}
+              onChange={(e) => updatePath('dirChmod', e.target.value)}
+              placeholder="775"
+              className={`font-mono max-w-32 ${paths.dirChmod && !/^[0-7]{3,4}$/.test(paths.dirChmod) ? 'border-red-500 dark:border-red-500' : ''}`}
+            />
+            {paths.dirChmod && !/^[0-7]{3,4}$/.test(paths.dirChmod) && (
+              <p className="text-xs text-red-600 dark:text-red-400 mt-1">Must be 3-4 octal digits (0-7)</p>
+            )}
+            <p className="text-xs text-gray-500 dark:text-gray-400 mt-1">
+              e.g. 775 = owner/group full access, others read-execute
+            </p>
+          </div>
+        </div>
+      </div>
+
       {/* Test Paths Button */}
       <div className="border-t border-gray-200 dark:border-gray-700 pt-6">
         <Button

src/app/admin/users/page.tsx

@@ -29,6 +29,7 @@ interface User {
   autoApproveRequests: boolean | null;
   interactiveSearchAccess: boolean | null;
   downloadAccess: boolean | null;
+  hasLoginToken: boolean;
   _count: {
     requests: number;
   };
@@ -220,6 +221,7 @@ function AdminUsersPageContent() {
   const [globalDownloadAccess, setGlobalDownloadAccess] = useState<boolean>(true);
   const [globalSettingsOpen, setGlobalSettingsOpen] = useState(false);
   const [permissionsUserId, setPermissionsUserId] = useState<string | null>(null);
+  const [generatedToken, setGeneratedToken] = useState<string | null>(null);
   const toast = useToast();
 
   const isLoading = !data && !error;
@@ -363,6 +365,24 @@ function AdminUsersPageContent() {
     }
   };
 
+  const handleToggleToken = async (user: { id: string; plexUsername: string }, newValue: boolean) => {
+    try {
+      if (newValue) {
+        const result = await fetchJSON(`/api/admin/users/${user.id}/login-token`, { method: 'POST' });
+        setGeneratedToken(result.fullToken);
+        toast.success(`Login token generated for ${user.plexUsername}`);
+      } else {
+        await fetchJSON(`/api/admin/users/${user.id}/login-token`, { method: 'DELETE' });
+        setGeneratedToken(null);
+        toast.success(`Login token revoked for ${user.plexUsername}`);
+      }
+      mutate();
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : 'Failed to update login token';
+      toast.error(errorMsg);
+    }
+  };
+
   const showEditDialog = (user: User) => {
     setEditRole(user.role);
     setEditDialog({ isOpen: true, user });
@@ -968,11 +988,15 @@ function AdminUsersPageContent() {
         {/* User Permissions Modal */}
         <UserPermissionsModal
           isOpen={permissionsUser !== null}
-          onClose={() => setPermissionsUserId(null)}
+          onClose={() => {
+            setPermissionsUserId(null);
+            setGeneratedToken(null);
+          }}
           user={permissionsUser}
           globalAutoApprove={globalAutoApprove}
           globalInteractiveSearch={globalInteractiveSearch}
           globalDownloadAccess={globalDownloadAccess}
+          generatedToken={generatedToken}
           onToggleAutoApprove={(user, newValue) => {
             handleUserAutoApproveToggle(user as User, newValue);
           }}
@@ -982,6 +1006,9 @@ function AdminUsersPageContent() {
           onToggleDownloadAccess={(user, newValue) => {
             handleUserDownloadAccessToggle(user as User, newValue);
           }}
+          onToggleToken={(user, newValue) => {
+            handleToggleToken(user, newValue);
+          }}
         />
       </div>
     </div>

src/app/api-docs/page.tsx

@@ -0,0 +1,142 @@
+/**
+ * Component: Interactive API Documentation Page
+ * Documentation: documentation/backend/services/api-tokens.md
+ *
+ * Lists all API token-accessible endpoints with "Try it out" functionality.
+ * Users can test with a custom API token or their current browser session.
+ */
+
+'use client';
+
+import { useState } from 'react';
+import { Header } from '@/components/layout/Header';
+import { ProtectedRoute } from '@/components/auth/ProtectedRoute';
+import { TokenInput } from '@/components/api-docs/TokenInput';
+import { EndpointCard } from '@/components/api-docs/EndpointCard';
+import { API_TOKEN_ENDPOINT_DOCS } from '@/lib/constants/api-tokens';
+import { useAuth } from '@/contexts/AuthContext';
+import { getInstanceUrl } from '@/lib/utils/client-url';
+import Link from 'next/link';
+
+export default function ApiDocsPage() {
+  const { user } = useAuth();
+  const [token, setToken] = useState('');
+  const [useSession, setUseSession] = useState(false);
+  const isAdmin = user?.role === 'admin';
+
+  return (
+    <ProtectedRoute>
+      <div className="min-h-screen bg-gray-50 dark:bg-gray-950">
+        <Header />
+
+        <main className="max-w-4xl mx-auto px-4 sm:px-6 pt-8 pb-16">
+          {/* Page header */}
+          <div className="mb-8">
+            <div className="flex items-center gap-2 text-sm text-gray-500 dark:text-gray-400 mb-4">
+              <Link
+                href="/profile"
+                className="hover:text-gray-700 dark:hover:text-gray-200 transition-colors"
+              >
+                Profile
+              </Link>
+              <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+              </svg>
+              <span className="text-gray-900 dark:text-white font-medium">API Documentation</span>
+            </div>
+
+            <h1 className="text-3xl font-bold text-gray-900 dark:text-white tracking-tight">
+              API Reference
+            </h1>
+            <p className="mt-2 text-base text-gray-500 dark:text-gray-400 leading-relaxed max-w-2xl">
+              Interact with ReadMeABook programmatically using API tokens. These endpoints are
+              available for external integrations, dashboards, and automation tools.
+            </p>
+
+            {/* Quick links */}
+            <div className="flex flex-wrap gap-3 mt-4">
+              <Link
+                href="/profile"
+                className="inline-flex items-center gap-1.5 text-sm font-medium text-blue-600 dark:text-blue-400 hover:text-blue-700 dark:hover:text-blue-300 transition-colors"
+              >
+                <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 7a2 2 0 012 2m4 0a6 6 0 01-7.743 5.743L11 17H9v2H7v2H4a1 1 0 01-1-1v-2.586a1 1 0 01.293-.707l5.964-5.964A6 6 0 1121 9z" />
+                </svg>
+                Manage your tokens
+              </Link>
+              {isAdmin && (
+                <>
+                  <span className="text-gray-300 dark:text-gray-600">|</span>
+                  <Link
+                    href="/admin/settings"
+                    className="inline-flex items-center gap-1.5 text-sm font-medium text-blue-600 dark:text-blue-400 hover:text-blue-700 dark:hover:text-blue-300 transition-colors"
+                  >
+                    <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.066 2.573c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.573 1.066c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.066-2.573c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z" />
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
+                    </svg>
+                    Admin token management
+                  </Link>
+                </>
+              )}
+            </div>
+          </div>
+
+          {/* Authentication section */}
+          <div className="mb-8">
+            <TokenInput
+              token={token}
+              onTokenChange={setToken}
+              useSession={useSession}
+              onUseSessionChange={setUseSession}
+            />
+          </div>
+
+          {/* Usage instructions card */}
+          <div className="mb-8 rounded-2xl border border-gray-200 dark:border-gray-700/50 bg-white dark:bg-gray-800 p-5 shadow-sm">
+            <h3 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">
+              Quick Start
+            </h3>
+            <p className="text-sm text-gray-500 dark:text-gray-400 mb-3">
+              Include your API token in the <code className="px-1.5 py-0.5 bg-gray-100 dark:bg-gray-900 rounded text-xs font-mono">Authorization</code> header as a Bearer token:
+            </p>
+            <pre className="text-xs bg-gray-900 dark:bg-black text-gray-100 p-4 rounded-xl overflow-x-auto font-mono leading-relaxed">
+{`curl -H "Authorization: Bearer rmab_your_token_here" \\
+  ${getInstanceUrl()}/api/requests`}
+            </pre>
+          </div>
+
+          {/* Endpoints section header */}
+          <div className="flex items-center gap-3 mb-5">
+            <h2 className="text-lg font-semibold text-gray-900 dark:text-white">
+              Available Endpoints
+            </h2>
+            <span className="inline-flex items-center px-2 py-0.5 rounded-md text-xs font-medium bg-gray-100 dark:bg-gray-800 text-gray-600 dark:text-gray-400">
+              {API_TOKEN_ENDPOINT_DOCS.length} endpoints
+            </span>
+          </div>
+
+          {/* Endpoint cards */}
+          <div className="space-y-4">
+            {API_TOKEN_ENDPOINT_DOCS.map((endpoint) => (
+              <EndpointCard
+                key={`${endpoint.method}:${endpoint.path}`}
+                endpoint={endpoint}
+                token={token}
+                useSession={useSession}
+              />
+            ))}
+          </div>
+
+          {/* Footer note */}
+          <div className="mt-10 text-center">
+            <p className="text-xs text-gray-400 dark:text-gray-500">
+              API tokens are restricted to the endpoints listed above.
+              JWT session authentication has access to all endpoints.
+            </p>
+          </div>
+        </main>
+      </div>
+    </ProtectedRoute>
+  );
+}

src/app/api/admin/api-tokens/[id]/route.ts

@@ -0,0 +1,56 @@
+/**
+ * Component: API Token Delete Route
+ * Documentation: documentation/backend/services/api-tokens.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { RMABLogger } from '@/lib/utils/logger';
+import { checkApiTokenRevokeRateLimit } from '@/lib/utils/rateLimit';
+
+const logger = RMABLogger.create('API.Admin.ApiTokens');
+
+/**
+ * DELETE /api/admin/api-tokens/[id]
+ * Revoke (delete) an API token
+ */
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  return requireAuth(request, (req: AuthenticatedRequest) =>
+    requireAdmin(req, async () => {
+      try {
+        const rateLimit = checkApiTokenRevokeRateLimit(req.user!.id);
+        if (!rateLimit.allowed) {
+          return NextResponse.json(
+            { error: 'Too many API token revoke attempts. Please try again later.' },
+            {
+              status: 429,
+              headers: {
+                'Retry-After': String(rateLimit.retryAfterSeconds),
+              },
+            }
+          );
+        }
+
+        const { id } = await params;
+
+        const token = await prisma.apiToken.findUnique({ where: { id } });
+        if (!token) {
+          return NextResponse.json({ error: 'Token not found' }, { status: 404 });
+        }
+
+        await prisma.apiToken.delete({ where: { id } });
+
+        logger.info('API token revoked', { tokenId: id, name: token.name, revokedBy: req.user!.username });
+
+        return NextResponse.json({ success: true });
+      } catch (error) {
+        logger.error('Failed to revoke API token', { error: error instanceof Error ? error.message : String(error) });
+        return NextResponse.json({ error: 'Failed to revoke API token' }, { status: 500 });
+      }
+    })
+  );
+}

src/app/api/admin/api-tokens/route.ts

@@ -0,0 +1,190 @@
+/**
+ * Component: Admin API Token Management Routes
+ * Documentation: documentation/backend/services/api-tokens.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { RMABLogger } from '@/lib/utils/logger';
+import { checkApiTokenCreateRateLimit } from '@/lib/utils/rateLimit';
+import { MAX_TOKENS_PER_USER } from '@/lib/constants/api-tokens';
+import { generateApiToken } from '@/lib/utils/api-token';
+import { z } from 'zod';
+
+const logger = RMABLogger.create('API.Admin.ApiTokens');
+
+const CreateTokenSchema = z.object({
+  name: z.string().min(1).max(100),
+  expiresAt: z.string().datetime().nullable().optional(),
+  userId: z.string().uuid().optional(), // Admin can specify which user the token acts as
+  role: z.enum(['admin', 'user']).optional(), // Accepted for compatibility, but cannot differ from target user role
+});
+
+/**
+ * GET /api/admin/api-tokens
+ * List ALL API tokens across all users
+ */
+export async function GET(request: NextRequest) {
+  return requireAuth(request, (req: AuthenticatedRequest) =>
+    requireAdmin(req, async () => {
+      try {
+        const tokens = await prisma.apiToken.findMany({
+          include: {
+            createdBy: {
+              select: { id: true, plexUsername: true },
+            },
+            tokenUser: {
+              select: { id: true, plexUsername: true, role: true },
+            },
+          },
+          orderBy: { createdAt: 'desc' },
+        });
+
+        const sanitized = tokens.map((t) => ({
+          id: t.id,
+          name: t.name,
+          tokenPrefix: t.tokenPrefix,
+          role: t.role,
+          createdBy: t.createdBy.plexUsername,
+          createdById: t.createdBy.id,
+          tokenUser: t.tokenUser.plexUsername,
+          tokenUserId: t.tokenUser.id,
+          lastUsedAt: t.lastUsedAt,
+          expiresAt: t.expiresAt,
+          createdAt: t.createdAt,
+        }));
+
+        return NextResponse.json({ tokens: sanitized });
+      } catch (error) {
+        logger.error('Failed to list API tokens', { error: error instanceof Error ? error.message : String(error) });
+        return NextResponse.json({ error: 'Failed to list API tokens' }, { status: 500 });
+      }
+    })
+  );
+}
+
+/**
+ * POST /api/admin/api-tokens
+ * Create a new API token. Admin can optionally specify userId.
+ * Token role is always derived from the target user's current role.
+ * Returns the full token ONCE.
+ */
+export async function POST(request: NextRequest) {
+  return requireAuth(request, (req: AuthenticatedRequest) =>
+    requireAdmin(req, async () => {
+      try {
+        const rateLimit = checkApiTokenCreateRateLimit(req.user!.id);
+        if (!rateLimit.allowed) {
+          return NextResponse.json(
+            { error: 'Too many API token create attempts. Please try again later.' },
+            {
+              status: 429,
+              headers: {
+                'Retry-After': String(rateLimit.retryAfterSeconds),
+              },
+            }
+          );
+        }
+
+        const body = await req.json();
+        const { name, expiresAt, userId, role } = CreateTokenSchema.parse(body);
+
+        // Determine target user (defaults to the admin themselves)
+        const targetUserId = userId || req.user!.id;
+
+        // Verify the target user exists
+        const targetUser = await prisma.user.findUnique({
+          where: { id: targetUserId },
+          select: { id: true, role: true, plexUsername: true },
+        });
+
+        if (!targetUser) {
+          return NextResponse.json({ error: 'Target user not found' }, { status: 404 });
+        }
+
+        // Enforce per-user token cap (count only active, non-expired tokens)
+        const activeTokenCount = await prisma.apiToken.count({
+          where: {
+            userId: targetUserId,
+            OR: [
+              { expiresAt: null },
+              { expiresAt: { gt: new Date() } },
+            ],
+          },
+        });
+
+        if (activeTokenCount >= MAX_TOKENS_PER_USER) {
+          return NextResponse.json(
+            { error: `Token limit reached. Users may have at most ${MAX_TOKENS_PER_USER} active API tokens.` },
+            { status: 403 }
+          );
+        }
+
+        // Security guard: token role must always match the target user's persisted role.
+        // This avoids role/identity mismatch (for example: acting as user A with admin role).
+        if (role && role !== targetUser.role) {
+          logger.warn('Admin attempted token role override that differs from target user role', {
+            requestedRole: role,
+            userActualRole: targetUser.role,
+            targetUser: targetUser.plexUsername,
+            createdBy: req.user!.username,
+          });
+
+          return NextResponse.json(
+            {
+              error: `Token role must match target user's role (${targetUser.role}).`,
+            },
+            { status: 400 }
+          );
+        }
+
+        const tokenRole = targetUser.role;
+
+        // Generate the token
+        const { fullToken, tokenHash, tokenPrefix } = generateApiToken();
+
+        const apiToken = await prisma.apiToken.create({
+          data: {
+            name,
+            tokenHash,
+            tokenPrefix,
+            role: tokenRole,
+            createdById: req.user!.id,
+            userId: targetUserId,
+            expiresAt: expiresAt ? new Date(expiresAt) : null,
+          },
+        });
+
+        logger.info('Admin API token created', {
+          tokenId: apiToken.id,
+          name,
+          createdBy: req.user!.username,
+          targetUser: targetUser.plexUsername,
+          role: tokenRole,
+        });
+
+        return NextResponse.json({
+          token: {
+            id: apiToken.id,
+            name: apiToken.name,
+            tokenPrefix: apiToken.tokenPrefix,
+            role: apiToken.role,
+            expiresAt: apiToken.expiresAt,
+            createdAt: apiToken.createdAt,
+          },
+          // Full token is returned ONLY on creation
+          fullToken,
+        }, { status: 201 });
+      } catch (error) {
+        logger.error('Failed to create API token', { error: error instanceof Error ? error.message : String(error) });
+
+        if (error instanceof z.ZodError) {
+          return NextResponse.json({ error: 'Validation error', details: error.errors }, { status: 400 });
+        }
+
+        return NextResponse.json({ error: 'Failed to create API token' }, { status: 500 });
+      }
+    })
+  );
+}

src/app/api/admin/bulk-import/execute/route.ts

@@ -0,0 +1,292 @@
+/**
+ * Component: Bulk Import Execute API
+ * Documentation: documentation/features/bulk-import.md
+ *
+ * Queues manual imports for multiple audiobooks at once.
+ * Reuses the same logic as the single manual import endpoint.
+ * Admin-only.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { getJobQueueService } from '@/lib/services/job-queue.service';
+import { RMABLogger } from '@/lib/utils/logger';
+import { AUDIO_EXTENSIONS } from '@/lib/constants/audio-formats';
+import { getAudibleService } from '@/lib/integrations/audible.service';
+
+const logger = RMABLogger.create('API.Admin.BulkImport.Execute');
+
+const BOOKDROP_PATH = '/bookdrop';
+
+/** Statuses that indicate the request is actively being worked on. */
+const ACTIVE_STATUSES = ['searching', 'downloading', 'processing', 'awaiting_import'];
+
+/** Statuses that can be recycled for a new manual import. */
+const RECYCLABLE_STATUSES = [
+  'failed', 'warn', 'cancelled', 'denied', 'pending',
+  'awaiting_search', 'awaiting_approval',
+];
+
+interface ImportItem {
+  folderPath: string;
+  asin: string;
+}
+
+interface ImportResult {
+  folderPath: string;
+  asin: string;
+  success: boolean;
+  requestId?: string;
+  error?: string;
+}
+
+/** Check if a directory contains audio files. */
+async function hasAudioFiles(dirPath: string): Promise<boolean> {
+  const fs = await import('fs/promises');
+  const pathModule = await import('path');
+
+  try {
+    const children = await fs.readdir(dirPath, { withFileTypes: true });
+    return children.some(
+      (child) =>
+        child.isFile() &&
+        (AUDIO_EXTENSIONS as readonly string[]).includes(
+          pathModule.extname(child.name).toLowerCase()
+        )
+    );
+  } catch {
+    return false;
+  }
+}
+
+export async function POST(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    return requireAdmin(req, async () => {
+      try {
+        const pathModule = await import('path');
+        const fs = await import('fs/promises');
+
+        const body = await request.json();
+        const { imports } = body as { imports: ImportItem[] };
+
+        if (!imports || !Array.isArray(imports) || imports.length === 0) {
+          return NextResponse.json(
+            { error: 'imports array is required and must not be empty' },
+            { status: 400 }
+          );
+        }
+
+        // Load allowed roots
+        const [downloadDirConfig, mediaDirConfig] = await Promise.all([
+          prisma.configuration.findUnique({ where: { key: 'download_dir' } }),
+          prisma.configuration.findUnique({ where: { key: 'media_dir' } }),
+        ]);
+
+        const allowedRoots: string[] = [];
+        if (downloadDirConfig?.value) {
+          allowedRoots.push(pathModule.resolve(downloadDirConfig.value).replace(/\\/g, '/'));
+        }
+        if (mediaDirConfig?.value) {
+          allowedRoots.push(pathModule.resolve(mediaDirConfig.value).replace(/\\/g, '/'));
+        }
+        try {
+          const bookdropStat = await fs.stat(BOOKDROP_PATH);
+          if (bookdropStat.isDirectory()) {
+            allowedRoots.push(pathModule.resolve(BOOKDROP_PATH).replace(/\\/g, '/'));
+          }
+        } catch {
+          /* not mounted */
+        }
+
+        const userId = req.user!.id;
+        const audibleService = getAudibleService();
+        const jobQueue = getJobQueueService();
+        const results: ImportResult[] = [];
+
+        for (const item of imports) {
+          const { folderPath, asin } = item;
+
+          try {
+            // Validate path
+            const normalizedPath = pathModule.resolve(folderPath).replace(/\\/g, '/');
+            const isAllowed = allowedRoots.some(
+              (root) => normalizedPath === root || normalizedPath.startsWith(root + '/')
+            );
+
+            if (!isAllowed) {
+              results.push({ folderPath, asin, success: false, error: 'Path outside allowed directories' });
+              continue;
+            }
+
+            // Verify directory exists and has audio files
+            try {
+              const stat = await fs.stat(normalizedPath);
+              if (!stat.isDirectory()) {
+                results.push({ folderPath, asin, success: false, error: 'Not a directory' });
+                continue;
+              }
+            } catch {
+              results.push({ folderPath, asin, success: false, error: 'Directory not found' });
+              continue;
+            }
+
+            const hasAudio = await hasAudioFiles(normalizedPath);
+            if (!hasAudio) {
+              results.push({ folderPath, asin, success: false, error: 'No audio files' });
+              continue;
+            }
+
+            // Resolve or create audiobook record
+            let audiobookId: string;
+            let existingBook = await prisma.audiobook.findFirst({
+              where: { audibleAsin: asin },
+            });
+
+            if (existingBook) {
+              audiobookId = existingBook.id;
+            } else {
+              // Try Audible cache, then Audnexus
+              const cached = await prisma.audibleCache.findUnique({ where: { asin } });
+              if (cached) {
+                const newBook = await prisma.audiobook.create({
+                  data: {
+                    audibleAsin: asin,
+                    title: cached.title,
+                    author: cached.author,
+                    coverArtUrl: cached.coverArtUrl,
+                    narrator: cached.narrator,
+                    status: 'pending',
+                  },
+                });
+                audiobookId = newBook.id;
+              } else {
+                try {
+                  const liveData = await audibleService.getAudiobookDetails(asin);
+                  if (!liveData) {
+                    results.push({ folderPath, asin, success: false, error: 'Audiobook not found' });
+                    continue;
+                  }
+                  const newBook = await prisma.audiobook.create({
+                    data: {
+                      audibleAsin: asin,
+                      title: liveData.title,
+                      author: liveData.author,
+                      coverArtUrl: liveData.coverArtUrl,
+                      narrator: liveData.narrator,
+                      series: liveData.series,
+                      seriesPart: liveData.seriesPart,
+                      seriesAsin: liveData.seriesAsin,
+                      year: liveData.releaseDate
+                        ? new Date(liveData.releaseDate).getFullYear() || undefined
+                        : undefined,
+                      status: 'pending',
+                    },
+                  });
+                  audiobookId = newBook.id;
+                } catch {
+                  results.push({ folderPath, asin, success: false, error: 'Failed to fetch audiobook details' });
+                  continue;
+                }
+              }
+            }
+
+            // Check for existing request and recycle or create
+            const existingRequest = await prisma.request.findFirst({
+              where: {
+                audiobookId,
+                type: 'audiobook',
+                deletedAt: null,
+              },
+              orderBy: { createdAt: 'desc' },
+            });
+
+            let requestId: string;
+
+            if (existingRequest) {
+              if (ACTIVE_STATUSES.includes(existingRequest.status)) {
+                results.push({ folderPath, asin, success: false, error: 'Already being processed' });
+                continue;
+              }
+
+              if (
+                RECYCLABLE_STATUSES.includes(existingRequest.status) ||
+                existingRequest.status === 'downloaded' ||
+                existingRequest.status === 'available'
+              ) {
+                await prisma.request.update({
+                  where: { id: existingRequest.id },
+                  data: {
+                    status: 'processing',
+                    progress: 100,
+                    errorMessage: null,
+                    importAttempts: 0,
+                    updatedAt: new Date(),
+                  },
+                });
+                requestId = existingRequest.id;
+              } else {
+                const newReq = await prisma.request.create({
+                  data: {
+                    userId,
+                    audiobookId,
+                    type: 'audiobook',
+                    status: 'processing',
+                    progress: 100,
+                  },
+                });
+                requestId = newReq.id;
+              }
+            } else {
+              const newReq = await prisma.request.create({
+                data: {
+                  userId,
+                  audiobookId,
+                  type: 'audiobook',
+                  status: 'processing',
+                  progress: 100,
+                },
+              });
+              requestId = newReq.id;
+            }
+
+            // Queue organize_files job
+            await jobQueue.addOrganizeJob(requestId, audiobookId, normalizedPath);
+
+            results.push({ folderPath, asin, success: true, requestId });
+            logger.info(`Bulk import queued: asin=${asin}, path=${normalizedPath}, request=${requestId}`);
+          } catch (itemError) {
+            logger.error(`Bulk import item failed: asin=${asin}, path=${folderPath}`, {
+              error: itemError instanceof Error ? itemError.message : String(itemError),
+            });
+            results.push({
+              folderPath,
+              asin,
+              success: false,
+              error: itemError instanceof Error ? itemError.message : 'Import failed',
+            });
+          }
+        }
+
+        const succeeded = results.filter((r) => r.success).length;
+        const failed = results.filter((r) => !r.success).length;
+
+        logger.info(`Bulk import execute complete: ${succeeded} queued, ${failed} failed`);
+
+        return NextResponse.json({
+          success: true,
+          results,
+          summary: { total: results.length, succeeded, failed },
+        });
+      } catch (error) {
+        logger.error('Bulk import execute failed', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return NextResponse.json(
+          { error: error instanceof Error ? error.message : 'Bulk import failed' },
+          { status: 500 }
+        );
+      }
+    });
+  });
+}

src/app/api/admin/bulk-import/scan/route.ts

@@ -0,0 +1,271 @@
+/**
+ * Component: Bulk Import Scan API (SSE)
+ * Documentation: documentation/features/bulk-import.md
+ *
+ * Streams audiobook discovery and Audible matching results via Server-Sent Events.
+ * Admin-only. Validates path is within allowed roots.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { RMABLogger } from '@/lib/utils/logger';
+import { discoverAudiobooks } from '@/lib/utils/bulk-import-scanner';
+import { getAudibleService } from '@/lib/integrations/audible.service';
+import { findPlexMatch } from '@/lib/utils/audiobook-matcher';
+
+const logger = RMABLogger.create('API.Admin.BulkImport.Scan');
+
+const BOOKDROP_PATH = '/bookdrop';
+const AUDIBLE_SEARCH_DELAY_MS = 1500;
+
+/** Load allowed root directories from configuration. */
+async function getAllowedRoots(): Promise<string[]> {
+  const pathModule = await import('path');
+  const fs = await import('fs/promises');
+
+  const [downloadDirConfig, mediaDirConfig] = await Promise.all([
+    prisma.configuration.findUnique({ where: { key: 'download_dir' } }),
+    prisma.configuration.findUnique({ where: { key: 'media_dir' } }),
+  ]);
+
+  const roots: string[] = [];
+  if (downloadDirConfig?.value) {
+    roots.push(pathModule.resolve(downloadDirConfig.value).replace(/\\/g, '/'));
+  }
+  if (mediaDirConfig?.value) {
+    roots.push(pathModule.resolve(mediaDirConfig.value).replace(/\\/g, '/'));
+  }
+  try {
+    const stat = await fs.stat(BOOKDROP_PATH);
+    if (stat.isDirectory()) {
+      roots.push(pathModule.resolve(BOOKDROP_PATH).replace(/\\/g, '/'));
+    }
+  } catch {
+    /* not mounted */
+  }
+
+  return roots;
+}
+
+/** Check if a path is within allowed roots. */
+function isPathAllowed(normalizedPath: string, roots: string[]): boolean {
+  return roots.some(
+    (root) => normalizedPath === root || normalizedPath.startsWith(root + '/')
+  );
+}
+
+/** Delay helper for rate limiting. */
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function POST(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    return requireAdmin(req, async () => {
+      const pathModule = await import('path');
+      const fs = await import('fs/promises');
+
+      let body: any;
+      try {
+        body = await request.json();
+      } catch {
+        return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 });
+      }
+
+      const { rootPath } = body;
+      if (!rootPath) {
+        return NextResponse.json({ error: 'rootPath is required' }, { status: 400 });
+      }
+
+      // Validate path
+      const allowedRoots = await getAllowedRoots();
+      const normalizedPath = pathModule.resolve(rootPath).replace(/\\/g, '/');
+
+      if (!isPathAllowed(normalizedPath, allowedRoots)) {
+        return NextResponse.json(
+          { error: 'Access denied: path outside allowed directories' },
+          { status: 403 }
+        );
+      }
+
+      // Verify directory exists
+      try {
+        const stat = await fs.stat(normalizedPath);
+        if (!stat.isDirectory()) {
+          return NextResponse.json({ error: 'Path is not a directory' }, { status: 400 });
+        }
+      } catch {
+        return NextResponse.json({ error: 'Directory not found' }, { status: 404 });
+      }
+
+      logger.info(`Bulk import scan started: ${normalizedPath}`);
+
+      // Create SSE stream
+      const encoder = new TextEncoder();
+      const abortController = new AbortController();
+
+      const stream = new ReadableStream({
+        async start(controller) {
+          const send = (event: string, data: any) => {
+            try {
+              controller.enqueue(
+                encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
+              );
+            } catch {
+              /* stream closed */
+            }
+          };
+
+          try {
+            // Phase 1: Discover audiobook folders
+            const audiobooks = await discoverAudiobooks(
+              normalizedPath,
+              (progress) => {
+                send('progress', progress);
+              },
+              abortController.signal
+            );
+
+            if (audiobooks.length === 0) {
+              send('complete', { audiobooks: [], message: 'No audiobooks found' });
+              controller.close();
+              return;
+            }
+
+            send('discovery_complete', {
+              totalFound: audiobooks.length,
+              message: `Found ${audiobooks.length} audiobook folders`,
+            });
+
+            // Phase 2: Match each audiobook against Audible
+            const audibleService = getAudibleService();
+            const results: any[] = [];
+
+            for (let i = 0; i < audiobooks.length; i++) {
+              if (abortController.signal.aborted) break;
+
+              const book = audiobooks[i];
+
+              send('matching', {
+                current: i + 1,
+                total: audiobooks.length,
+                folderName: book.folderName,
+                searchTerm: book.searchTerm,
+              });
+
+              let match: any = null;
+              let inLibrary = false;
+              let hasActiveRequest = false;
+
+              try {
+                const searchResult = await audibleService.search(book.searchTerm);
+
+                if (searchResult.results.length > 0) {
+                  match = searchResult.results[0];
+
+                  // Check library availability
+                  const plexMatch = await findPlexMatch({
+                    asin: match.asin,
+                    title: match.title,
+                    author: match.author,
+                    narrator: match.narrator,
+                  });
+                  inLibrary = plexMatch !== null;
+
+                  // Check for active requests
+                  if (!inLibrary) {
+                    const activeRequest = await prisma.request.findFirst({
+                      where: {
+                        audiobook: { audibleAsin: match.asin },
+                        type: 'audiobook',
+                        status: {
+                          in: [
+                            'pending', 'searching', 'downloading', 'processing',
+                            'awaiting_search', 'awaiting_import', 'awaiting_approval',
+                            'downloaded', 'available',
+                          ],
+                        },
+                        deletedAt: null,
+                      },
+                    });
+                    hasActiveRequest = activeRequest !== null;
+                  }
+                }
+              } catch (searchError) {
+                logger.warn(
+                  `Audible search failed for "${book.searchTerm}": ${
+                    searchError instanceof Error ? searchError.message : String(searchError)
+                  }`
+                );
+              }
+
+              const result = {
+                index: i,
+                folderPath: book.folderPath,
+                folderName: book.folderName,
+                relativePath: book.relativePath,
+                audioFileCount: book.audioFileCount,
+                totalSizeBytes: book.totalSizeBytes,
+                metadataSource: book.metadataSource,
+                searchTerm: book.searchTerm,
+                match: match
+                  ? {
+                      asin: match.asin,
+                      title: match.title,
+                      author: match.author,
+                      narrator: match.narrator,
+                      coverArtUrl: match.coverArtUrl,
+                      durationMinutes: match.durationMinutes,
+                    }
+                  : null,
+                inLibrary,
+                hasActiveRequest,
+              };
+
+              results.push(result);
+              send('book_matched', result);
+
+              // Rate limit: wait between Audible searches (except after last)
+              if (i < audiobooks.length - 1) {
+                await delay(AUDIBLE_SEARCH_DELAY_MS);
+              }
+            }
+
+            send('complete', {
+              totalFound: results.length,
+              matched: results.filter((r) => r.match !== null).length,
+              inLibrary: results.filter((r) => r.inLibrary).length,
+            });
+          } catch (error) {
+            logger.error('Bulk import scan failed', {
+              error: error instanceof Error ? error.message : String(error),
+            });
+            send('error', {
+              message: error instanceof Error ? error.message : 'Scan failed',
+            });
+          } finally {
+            try {
+              controller.close();
+            } catch {
+              /* already closed */
+            }
+          }
+        },
+        cancel() {
+          abortController.abort();
+        },
+      });
+
+      // Cast to NextResponse: SSE streams require raw Response constructor,
+      // but requireAdmin types expect NextResponse. The Response is valid at runtime.
+      return new Response(stream, {
+        headers: {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          Connection: 'keep-alive',
+        },
+      }) as unknown as NextResponse;
+    });
+  });
+}

src/app/api/admin/manual-import/route.ts

@@ -12,6 +12,7 @@ import { prisma } from '@/lib/db';
 import { getJobQueueService } from '@/lib/services/job-queue.service';
 import { RMABLogger } from '@/lib/utils/logger';
 import { AUDIO_EXTENSIONS } from '@/lib/constants/audio-formats';
+import { getAudibleService } from '@/lib/integrations/audible.service';
 
 const logger = RMABLogger.create('API.Admin.ManualImport');
 
@@ -54,7 +55,7 @@ export async function POST(request: NextRequest) {
         const fs = await import('fs/promises');
 
         const body = await request.json();
-        const { folderPath, asin } = body;
+        const { folderPath, asin, cleanupSource } = body;
         let { audiobookId } = body;
 
         // Validate required fields
@@ -154,10 +155,42 @@ export async function POST(request: NextRequest) {
               audiobookId = newBook.id;
               logger.info(`Created audiobook record from cache for ASIN ${asin}: ${newBook.id}`);
             } else {
-              return NextResponse.json(
-                { error: 'Audiobook not found for the given ASIN' },
-                { status: 404 }
-              );
+              // Not in DB — fetch live from Audnexus and create a record
+              try {
+                const audibleService = getAudibleService();
+                const liveData = await audibleService.getAudiobookDetails(asin);
+                if (liveData) {
+                  const newBook = await prisma.audiobook.create({
+                    data: {
+                      audibleAsin: asin,
+                      title: liveData.title,
+                      author: liveData.author,
+                      coverArtUrl: liveData.coverArtUrl,
+                      narrator: liveData.narrator,
+                      series: liveData.series,
+                      seriesPart: liveData.seriesPart,
+                      seriesAsin: liveData.seriesAsin,
+                      year: liveData.releaseDate
+                        ? new Date(liveData.releaseDate).getFullYear() || undefined
+                        : undefined,
+                      status: 'pending',
+                    },
+                  });
+                  audiobookId = newBook.id;
+                  logger.info(`Created audiobook record from Audnexus for ASIN ${asin}: ${newBook.id}`);
+                } else {
+                  return NextResponse.json(
+                    { error: 'Audiobook not found for the given ASIN' },
+                    { status: 404 }
+                  );
+                }
+              } catch (audnexusError) {
+                logger.error(`Failed to fetch ASIN ${asin} from Audnexus: ${audnexusError instanceof Error ? audnexusError.message : String(audnexusError)}`);
+                return NextResponse.json(
+                  { error: 'Audiobook not found for the given ASIN' },
+                  { status: 404 }
+                );
+              }
             }
           }
         }
@@ -174,6 +207,48 @@ export async function POST(request: NextRequest) {
           );
         }
 
+        // Enrich missing series/year data from Audnexus (mirrors request-creator.service.ts)
+        if (audiobook.audibleAsin && (!audiobook.series || !audiobook.year)) {
+          try {
+            const audibleService = getAudibleService();
+            const audnexusData = await audibleService.getAudiobookDetails(audiobook.audibleAsin);
+
+            if (audnexusData) {
+              const updates: Record<string, any> = {};
+
+              if (!audiobook.series && audnexusData.series) {
+                updates.series = audnexusData.series;
+              }
+              if (!audiobook.seriesPart && audnexusData.seriesPart) {
+                updates.seriesPart = audnexusData.seriesPart;
+              }
+              if (!audiobook.seriesAsin && audnexusData.seriesAsin) {
+                updates.seriesAsin = audnexusData.seriesAsin;
+              }
+              if (!audiobook.year && audnexusData.releaseDate) {
+                const releaseYear = new Date(audnexusData.releaseDate).getFullYear();
+                if (!isNaN(releaseYear)) {
+                  updates.year = releaseYear;
+                }
+              }
+              if (!audiobook.narrator && audnexusData.narrator) {
+                updates.narrator = audnexusData.narrator;
+              }
+
+              if (Object.keys(updates).length > 0) {
+                await prisma.audiobook.update({
+                  where: { id: audiobook.id },
+                  data: updates,
+                });
+                logger.info(`Enriched audiobook metadata from Audnexus for ASIN ${audiobook.audibleAsin}`, updates);
+              }
+            }
+          } catch (error) {
+            // Non-fatal: series enrichment failure should never block the import
+            logger.warn(`Failed to enrich metadata from Audnexus for ASIN ${audiobook.audibleAsin}: ${error instanceof Error ? error.message : String(error)}`);
+          }
+        }
+
         // Check for existing requests
         const existingRequest = await prisma.request.findFirst({
           where: {
@@ -242,7 +317,7 @@ export async function POST(request: NextRequest) {
 
         // Queue organize_files job
         const jobQueue = getJobQueueService();
-        await jobQueue.addOrganizeJob(requestId, audiobookId, normalizedPath);
+        await jobQueue.addOrganizeJob(requestId, audiobookId, normalizedPath, undefined, cleanupSource === true);
 
         logger.info(`Manual import queued: request=${requestId}, path=${normalizedPath}, audioFiles=${audioCheck.count}`);
 

src/app/api/admin/requests/[id]/retry-download/route.ts

@@ -0,0 +1,271 @@
+/**
+ * Component: Admin Retry Download API
+ * Documentation: documentation/admin-dashboard.md
+ *
+ * Retries a failed download by either resuming monitoring of a still-alive
+ * download in the client, or re-adding the download using metadata from the
+ * most recent selected DownloadHistory record.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { getJobQueueService } from '@/lib/services/job-queue.service';
+import { getConfigService } from '@/lib/services/config.service';
+import { getDownloadClientManager } from '@/lib/services/download-client-manager.service';
+import { CLIENT_PROTOCOL_MAP, DownloadClientType } from '@/lib/interfaces/download-client.interface';
+import { TorrentResult } from '@/lib/utils/ranking-algorithm';
+import { RMABLogger } from '@/lib/utils/logger';
+
+const logger = RMABLogger.create('API.Admin.Requests.RetryDownload');
+
+/** Download statuses considered "alive" — monitoring can be resumed */
+const ALIVE_STATUSES = new Set([
+  'downloading',
+  'queued',
+  'paused',
+  'checking',
+  'seeding',
+  'completed',
+]);
+
+/**
+ * POST /api/admin/requests/[id]/retry-download
+ * Retry a failed download for an admin request.
+ */
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    return requireAdmin(req, async () => {
+      try {
+        if (!req.user) {
+          return NextResponse.json(
+            { error: 'Unauthorized', message: 'User not authenticated' },
+            { status: 401 }
+          );
+        }
+
+        const { id } = await params;
+
+        // Fetch the request with audiobook info
+        const existingRequest = await prisma.request.findFirst({
+          where: { id, deletedAt: null },
+          include: {
+            audiobook: true,
+          },
+        });
+
+        if (!existingRequest) {
+          return NextResponse.json(
+            { error: 'NotFound', message: 'Request not found' },
+            { status: 404 }
+          );
+        }
+
+        if (existingRequest.status !== 'failed') {
+          return NextResponse.json(
+            {
+              error: 'InvalidStatus',
+              message: `Request is not in a failed state (current status: ${existingRequest.status})`,
+              currentStatus: existingRequest.status,
+            },
+            { status: 400 }
+          );
+        }
+
+        // Find the most recent selected DownloadHistory record
+        const downloadHistory = await prisma.downloadHistory.findFirst({
+          where: { requestId: id, selected: true },
+          orderBy: { createdAt: 'desc' },
+        });
+
+        if (!downloadHistory) {
+          return NextResponse.json(
+            {
+              error: 'NoHistory',
+              message: 'No previous download attempt found to retry',
+            },
+            { status: 400 }
+          );
+        }
+
+        // Require a download URL to be able to re-add
+        if (!downloadHistory.magnetLink) {
+          return NextResponse.json(
+            {
+              error: 'NoDownloadUrl',
+              message: 'No download URL available in history to retry',
+            },
+            { status: 400 }
+          );
+        }
+
+        const jobQueue = getJobQueueService();
+        let retryPath: 'resumed_monitoring' | 're_added';
+
+        // Determine if we can attempt to resume monitoring.
+        // downloadClient is stored as a plain string in the DB (can be 'qbittorrent', 'sabnzbd',
+        // 'nzbget', 'transmission', 'deluge', 'direct', or null).
+        const rawClientType: string | null = downloadHistory.downloadClient;
+        const clientId = downloadHistory.downloadClientId;
+        const isDirect = rawClientType === 'direct';
+
+        // Only attempt to query the download client if we have a known DownloadClientType,
+        // a clientId, and it is not a direct (HTTP) download.
+        const canCheckClient = !isDirect && !!rawClientType && !!clientId;
+        // Safe to cast here: we have already confirmed rawClientType is non-null and non-direct
+        const clientType = rawClientType as DownloadClientType | null;
+
+        if (canCheckClient) {
+          // Try to look up the download in the client
+          try {
+            const protocol = CLIENT_PROTOCOL_MAP[clientType as DownloadClientType];
+            const configService = getConfigService();
+            const manager = getDownloadClientManager(configService);
+            const client = await manager.getClientServiceForProtocol(protocol);
+
+            if (client) {
+              const downloadInfo = await client.getDownload(clientId!);
+
+              if (downloadInfo && ALIVE_STATUSES.has(downloadInfo.status)) {
+                // Download is still alive — restart monitoring
+                logger.info(`Retry download: resuming monitoring for request ${id}`, {
+                  requestId: id,
+                  downloadClientId: clientId,
+                  downloadStatus: downloadInfo.status,
+                  adminId: req.user.sub,
+                });
+
+                await jobQueue.addMonitorJob(
+                  id,
+                  downloadHistory.id,
+                  clientId!, // canCheckClient guard ensures clientId is non-null
+                  clientType as DownloadClientType,
+                  0 // no delay — start immediately
+                );
+
+                retryPath = 'resumed_monitoring';
+              } else {
+                // Download not found or is failed — re-add
+                logger.info(`Retry download: download not alive (status: ${downloadInfo?.status ?? 'not found'}), re-adding for request ${id}`, {
+                  requestId: id,
+                  adminId: req.user.sub,
+                });
+
+                await reAddDownload(jobQueue, id, existingRequest.audiobook, downloadHistory);
+                retryPath = 're_added';
+              }
+            } else {
+              // No client configured for that protocol — fall through to re-add
+              logger.warn(`Retry download: no ${protocol} client configured, re-adding for request ${id}`, {
+                requestId: id,
+                adminId: req.user.sub,
+              });
+
+              await reAddDownload(jobQueue, id, existingRequest.audiobook, downloadHistory);
+              retryPath = 're_added';
+            }
+          } catch (clientError) {
+            // Client lookup failed (connection error etc.) — re-add to be safe
+            logger.warn(`Retry download: client check failed, re-adding for request ${id}`, {
+              requestId: id,
+              error: clientError instanceof Error ? clientError.message : String(clientError),
+              adminId: req.user.sub,
+            });
+
+            await reAddDownload(jobQueue, id, existingRequest.audiobook, downloadHistory);
+            retryPath = 're_added';
+          }
+        } else {
+          // Direct download (ebook), no clientId, or no clientType — re-add
+          logger.info(`Retry download: re-adding for request ${id} (direct=${isDirect}, hasClientId=${!!clientId})`, {
+            requestId: id,
+            adminId: req.user.sub,
+          });
+
+          await reAddDownload(jobQueue, id, existingRequest.audiobook, downloadHistory);
+          retryPath = 're_added';
+        }
+
+        // Increment downloadAttempts, clear errorMessage, set status to downloading
+        await prisma.request.update({
+          where: { id },
+          data: {
+            status: 'downloading',
+            errorMessage: null,
+            downloadAttempts: { increment: 1 },
+            updatedAt: new Date(),
+          },
+        });
+
+        const message =
+          retryPath === 'resumed_monitoring'
+            ? 'Download monitoring resumed'
+            : 'Download re-added to client';
+
+        logger.info(`Retry download completed for request ${id} via ${retryPath}`, {
+          requestId: id,
+          adminId: req.user.sub,
+          path: retryPath,
+        });
+
+        return NextResponse.json({
+          success: true,
+          message,
+          path: retryPath,
+        });
+      } catch (error) {
+        logger.error('Failed to retry download', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+
+        return NextResponse.json(
+          {
+            error: 'RetryError',
+            message: 'Failed to retry download',
+          },
+          { status: 500 }
+        );
+      }
+    });
+  });
+}
+
+/**
+ * Re-add the download to the queue using metadata from DownloadHistory.
+ * Reconstructs a TorrentResult from the stored history fields.
+ */
+async function reAddDownload(
+  jobQueue: ReturnType<typeof getJobQueueService>,
+  requestId: string,
+  audiobook: { id: string; title: string; author: string },
+  history: {
+    torrentName: string | null;
+    magnetLink: string | null;
+    indexerName: string;
+    indexerId: number | null;
+    torrentSizeBytes: bigint | null;
+    seeders: number | null;
+    leechers: number | null;
+    torrentHash: string | null;
+    torrentUrl: string | null;
+  }
+): Promise<void> {
+  const torrent: TorrentResult = {
+    title: history.torrentName ?? audiobook.title,
+    downloadUrl: history.magnetLink!, // Validated non-null before calling this function
+    indexer: history.indexerName,
+    indexerId: history.indexerId ?? undefined,
+    size: history.torrentSizeBytes !== null ? Number(history.torrentSizeBytes) : 0,
+    seeders: history.seeders ?? undefined,
+    leechers: history.leechers ?? undefined,
+    infoHash: history.torrentHash ?? undefined,
+    infoUrl: history.torrentUrl ?? undefined,
+    guid: history.torrentUrl ?? history.magnetLink!,
+    publishDate: new Date(), // Not stored; use current date as a safe default
+  };
+
+  await jobQueue.addDownloadJob(requestId, audiobook, torrent);
+}

src/app/api/admin/requests/[id]/search-terms/route.ts

@@ -0,0 +1,139 @@
+/**
+ * Component: Admin Custom Search Terms API
+ * Documentation: documentation/admin-dashboard.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { RMABLogger } from '@/lib/utils/logger';
+
+const logger = RMABLogger.create('API.Admin.SearchTerms');
+
+/**
+ * PATCH /api/admin/requests/[id]/search-terms
+ * Update custom search terms for a request (admin only)
+ * Body: { searchTerms: string | null, triggerSearch?: boolean }
+ */
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    return requireAdmin(req, async () => {
+      try {
+        if (!req.user) {
+          return NextResponse.json(
+            { error: 'Unauthorized', message: 'User not authenticated' },
+            { status: 401 }
+          );
+        }
+
+        const { id } = await params;
+
+        // Parse body
+        let body;
+        try {
+          body = await req.json();
+        } catch {
+          return NextResponse.json(
+            { error: 'BadRequest', message: 'Invalid JSON body' },
+            { status: 400 }
+          );
+        }
+
+        const { searchTerms, triggerSearch } = body;
+
+        // Validate searchTerms is string or null
+        if (searchTerms !== null && searchTerms !== undefined && typeof searchTerms !== 'string') {
+          return NextResponse.json(
+            { error: 'BadRequest', message: 'searchTerms must be a string or null' },
+            { status: 400 }
+          );
+        }
+
+        // Trim and normalize
+        const normalizedTerms = typeof searchTerms === 'string' ? searchTerms.trim() || null : null;
+
+        // Find the request
+        const existingRequest = await prisma.request.findUnique({
+          where: { id },
+          include: {
+            audiobook: {
+              select: { id: true, title: true, author: true, audibleAsin: true },
+            },
+          },
+        });
+
+        if (!existingRequest || existingRequest.deletedAt) {
+          return NextResponse.json(
+            { error: 'NotFound', message: 'Request not found' },
+            { status: 404 }
+          );
+        }
+
+        // Update custom search terms
+        await prisma.request.update({
+          where: { id },
+          data: {
+            customSearchTerms: normalizedTerms,
+            updatedAt: new Date(),
+          },
+        });
+
+        logger.info(`Custom search terms ${normalizedTerms ? 'set' : 'cleared'} for request ${id}`, {
+          requestId: id,
+          customSearchTerms: normalizedTerms,
+          adminId: req.user.id,
+        });
+
+        // Optionally trigger a new search
+        let searchTriggered = false;
+        if (triggerSearch && ['pending', 'failed', 'awaiting_search'].includes(existingRequest.status)) {
+          // Reset status to pending and clear error
+          await prisma.request.update({
+            where: { id },
+            data: {
+              status: 'pending',
+              errorMessage: null,
+              updatedAt: new Date(),
+            },
+          });
+
+          // Queue search job based on request type
+          const { getJobQueueService } = await import('@/lib/services/job-queue.service');
+          const jobQueue = getJobQueueService();
+          const audiobookData = {
+            id: existingRequest.audiobook.id,
+            title: existingRequest.audiobook.title,
+            author: existingRequest.audiobook.author,
+            asin: existingRequest.audiobook.audibleAsin || undefined,
+          };
+
+          if (existingRequest.type === 'ebook') {
+            await jobQueue.addSearchEbookJob(id, audiobookData);
+          } else {
+            await jobQueue.addSearchJob(id, audiobookData);
+          }
+
+          searchTriggered = true;
+          logger.info(`Search triggered for request ${id} with custom terms`, { requestId: id });
+        }
+
+        return NextResponse.json({
+          success: true,
+          customSearchTerms: normalizedTerms,
+          searchTriggered,
+        });
+      } catch (error) {
+        logger.error('Failed to update search terms', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return NextResponse.json(
+          { error: 'ServerError', message: 'Failed to update search terms' },
+          { status: 500 }
+        );
+      }
+    });
+  });
+}

src/app/api/admin/requests/route.ts

@@ -139,6 +139,8 @@ export async function GET(request: NextRequest) {
           completedAt: request.completedAt,
           errorMessage: request.errorMessage,
           torrentUrl: request.downloadHistory[0]?.torrentUrl || null,
+          downloadAttempts: request.downloadAttempts,
+          customSearchTerms: request.customSearchTerms || null,
         }));
 
         return NextResponse.json({

src/app/api/admin/settings/ebook/route.ts

@@ -78,7 +78,7 @@ export async function PUT(request: NextRequest) {
           // Anna's Archive specific settings
           {
             key: 'ebook_sidecar_base_url',
-            value: baseUrl || 'https://annas-archive.li',
+            value: baseUrl || 'https://annas-archive.gl',
             category: 'ebook',
             description: 'Base URL for Anna\'s Archive',
           },

src/app/api/admin/settings/paths/route.ts

@@ -15,7 +15,7 @@ export async function PUT(request: NextRequest) {
   return requireAuth(request, async (req: AuthenticatedRequest) => {
     return requireAdmin(req, async () => {
       try {
-        const { downloadDir, mediaDir, audiobookPathTemplate, ebookPathTemplate, metadataTaggingEnabled, chapterMergingEnabled, fileRenameEnabled, fileRenameTemplate } = await request.json();
+        const { downloadDir, mediaDir, audiobookPathTemplate, ebookPathTemplate, metadataTaggingEnabled, chapterMergingEnabled, fileRenameEnabled, fileRenameTemplate, fileChmod, dirChmod } = await request.json();
 
         if (!downloadDir || !mediaDir) {
           return NextResponse.json(
@@ -32,6 +32,21 @@ export async function PUT(request: NextRequest) {
           );
         }
 
+        // Validate octal permission strings (3-4 digits, each 0-7)
+        const octalRegex = /^[0-7]{3,4}$/;
+        if (fileChmod !== undefined && !octalRegex.test(fileChmod)) {
+          return NextResponse.json(
+            { error: 'File permissions must be 3-4 octal digits (0-7), e.g. 664' },
+            { status: 400 }
+          );
+        }
+        if (dirChmod !== undefined && !octalRegex.test(dirChmod)) {
+          return NextResponse.json(
+            { error: 'Directory permissions must be 3-4 octal digits (0-7), e.g. 775' },
+            { status: 400 }
+          );
+        }
+
         // Update configuration
         await prisma.configuration.upsert({
           where: { key: 'download_dir' },
@@ -123,6 +138,34 @@ export async function PUT(request: NextRequest) {
           });
         }
 
+        // Update file permissions (octal chmod)
+        if (fileChmod !== undefined) {
+          await prisma.configuration.upsert({
+            where: { key: 'file_chmod' },
+            update: { value: fileChmod },
+            create: {
+              key: 'file_chmod',
+              value: fileChmod,
+              category: 'automation',
+              description: 'Octal permissions applied to organized files',
+            },
+          });
+        }
+
+        // Update directory permissions (octal chmod)
+        if (dirChmod !== undefined) {
+          await prisma.configuration.upsert({
+            where: { key: 'dir_chmod' },
+            update: { value: dirChmod },
+            create: {
+              key: 'dir_chmod',
+              value: dirChmod,
+              category: 'automation',
+              description: 'Octal permissions applied to created directories',
+            },
+          });
+        }
+
         logger.info('Paths settings updated');
 
         // Clear config cache for all updated keys so services get fresh values
@@ -135,6 +178,8 @@ export async function PUT(request: NextRequest) {
         configService.clearCache('chapter_merging_enabled');
         configService.clearCache('file_rename_enabled');
         configService.clearCache('file_rename_template');
+        configService.clearCache('file_chmod');
+        configService.clearCache('dir_chmod');
 
         // Invalidate all download client singletons to force reload of download_dir
         const { invalidateDownloadClientManager } = await import('@/lib/services/download-client-manager.service');

src/app/api/admin/settings/route.ts

@@ -130,6 +130,8 @@ export async function GET(request: NextRequest) {
         chapterMergingEnabled: configMap.get('chapter_merging_enabled') === 'true',
         fileRenameEnabled: configMap.get('file_rename_enabled') === 'true',
         fileRenameTemplate: configMap.get('file_rename_template') || '{title}',
+        fileChmod: configMap.get('file_chmod') || '664',
+        dirChmod: configMap.get('dir_chmod') || '775',
       },
       ebook: {
         // New granular source toggles (with migration from legacy ebook_sidecar_enabled)
@@ -138,7 +140,7 @@ export async function GET(request: NextRequest) {
           (configMap.get('ebook_annas_archive_enabled') === undefined && configMap.get('ebook_sidecar_enabled') === 'true'),
         indexerSearchEnabled: configMap.get('ebook_indexer_search_enabled') === 'true',
         // Anna's Archive specific settings
-        baseUrl: configMap.get('ebook_sidecar_base_url') || 'https://annas-archive.li',
+        baseUrl: configMap.get('ebook_sidecar_base_url') || 'https://annas-archive.gl',
         flaresolverrUrl: configMap.get('ebook_sidecar_flaresolverr_url') || '',
         // General settings
         preferredFormat: configMap.get('ebook_sidecar_preferred_format') || 'epub',

src/app/api/admin/users/[id]/login-token/route.ts

@@ -0,0 +1,99 @@
+/**
+ * Component: Admin User Login Token
+ * Documentation: documentation/backend/services/auth.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { RMABLogger } from '@/lib/utils/logger';
+import { generateApiToken } from '@/lib/utils/api-token';
+
+const logger = RMABLogger.create('API.Admin.Users.LoginToken');
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    return requireAdmin(req, async () => {
+      try {
+        const { id } = await params;
+
+        const targetUser = await prisma.user.findUnique({
+          where: { id },
+          select: { plexUsername: true, deletedAt: true },
+        });
+
+        if (!targetUser) {
+          return NextResponse.json({ error: 'User not found' }, { status: 404 });
+        }
+
+        if (targetUser.deletedAt) {
+          return NextResponse.json(
+            { error: 'Cannot generate token for deleted user' },
+            { status: 403 }
+          );
+        }
+
+        const { fullToken, tokenHash } = generateApiToken();
+
+        await prisma.user.update({
+          where: { id },
+          data: { loginTokenHash: tokenHash },
+        });
+
+        logger.info('Admin generated login token for user', {
+          targetUser: targetUser.plexUsername,
+          createdBy: req.user!.username,
+        });
+
+        return NextResponse.json({ fullToken }, { status: 201 });
+      } catch (error) {
+        logger.error('Failed to generate login token', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return NextResponse.json({ error: 'Failed to generate login token' }, { status: 500 });
+      }
+    });
+  });
+}
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    return requireAdmin(req, async () => {
+      try {
+        const { id } = await params;
+
+        const targetUser = await prisma.user.findUnique({
+          where: { id },
+          select: { plexUsername: true },
+        });
+
+        if (!targetUser) {
+          return NextResponse.json({ error: 'User not found' }, { status: 404 });
+        }
+
+        await prisma.user.update({
+          where: { id },
+          data: { loginTokenHash: null, sessionsInvalidatedAt: new Date() },
+        });
+
+        logger.info('Admin revoked login token for user', {
+          targetUser: targetUser.plexUsername,
+          revokedBy: req.user!.username,
+        });
+
+        return NextResponse.json({ success: true });
+      } catch (error) {
+        logger.error('Failed to revoke login token', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return NextResponse.json({ error: 'Failed to revoke login token' }, { status: 500 });
+      }
+    });
+  });
+}

src/app/api/admin/users/route.ts

@@ -33,6 +33,7 @@ export async function GET(request: NextRequest) {
             autoApproveRequests: true,
             interactiveSearchAccess: true,
             downloadAccess: true,
+            loginTokenHash: true,
             _count: {
               select: {
                 requests: true,
@@ -44,7 +45,12 @@ export async function GET(request: NextRequest) {
           },
         });
 
-        return NextResponse.json({ users });
+        return NextResponse.json({
+          users: users.map(({ loginTokenHash, ...u }) => ({
+            ...u,
+            hasLoginToken: loginTokenHash !== null,
+          })),
+        });
       } catch (error) {
         logger.error('Failed to fetch users', { error: error instanceof Error ? error.message : String(error) });
         return NextResponse.json(

src/app/api/audible/categories/route.ts

@@ -0,0 +1,39 @@
+/**
+ * Component: Audible Categories API Route
+ * Documentation: documentation/features/home-sections.md
+ *
+ * Live scrape of top-level Audible categories for the home section config modal.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { RMABLogger } from '@/lib/utils/logger';
+
+const logger = RMABLogger.create('API.Audible.Categories');
+
+/**
+ * GET /api/audible/categories
+ * Returns top-level Audible categories scraped live from audible.com/categories
+ */
+export async function GET(request: NextRequest) {
+  return requireAuth(request, async (_req: AuthenticatedRequest) => {
+    try {
+      const { getAudibleService } = await import('@/lib/integrations/audible.service');
+      const audibleService = getAudibleService();
+      const categories = await audibleService.getCategories();
+
+      return NextResponse.json({
+        success: true,
+        categories,
+      });
+    } catch (error) {
+      logger.error('Failed to fetch categories', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return NextResponse.json(
+        { error: 'FetchError', message: 'Failed to fetch Audible categories' },
+        { status: 500 }
+      );
+    }
+  });
+}

src/app/api/audiobooks/[asin]/fetch-ebook/route.ts

@@ -260,6 +260,7 @@ export async function POST(
             parentRequestId: availableRequest?.id || null, // Link to parent if exists
             status: 'awaiting_approval',
             progress: 0,
+            customSearchTerms: availableRequest?.customSearchTerms || null,
           },
         });
 
@@ -292,6 +293,7 @@ export async function POST(
             parentRequestId: availableRequest?.id || null,
             status: 'pending',
             progress: 0,
+            customSearchTerms: availableRequest?.customSearchTerms || null,
           },
         });
 

src/app/api/audiobooks/[asin]/interactive-search-ebook/route.ts

@@ -227,7 +227,7 @@ export async function POST(
       const isAnnasArchiveEnabled = annasArchiveEnabled === 'true';
       const isIndexerSearchEnabled = indexerSearchEnabled === 'true';
       const format = preferredFormat || 'epub';
-      const annasBaseUrl = baseUrl || 'https://annas-archive.li';
+      const annasBaseUrl = baseUrl || 'https://annas-archive.gl';
 
       // Get language code from Audible region config
       const region = await configService.getAudibleRegion() as AudibleRegion;

src/app/api/audiobooks/[asin]/select-ebook/route.ts

@@ -252,6 +252,7 @@ export async function POST(
               status: 'awaiting_approval',
               progress: 0,
               selectedTorrent: selectedEbook as any,
+              customSearchTerms: availableRequest?.customSearchTerms || null,
             },
           });
           logger.info(`Created ebook request ${ebookRequest.id}, awaiting approval`);
@@ -296,6 +297,7 @@ export async function POST(
               parentRequestId: availableRequest?.id || null,
               status: 'searching',
               progress: 0,
+              customSearchTerms: availableRequest?.customSearchTerms || null,
             },
           });
           logger.info(`Created new ebook request ${ebookRequest.id}`);

src/app/api/audiobooks/category/[categoryId]/route.ts

@@ -0,0 +1,158 @@
+/**
+ * Component: Category Audiobooks API Route
+ * Documentation: documentation/features/home-sections.md
+ *
+ * Serves audiobooks for a specific Audible category from AudibleCacheCategory,
+ * with the same enrichment pattern as popular/new-releases routes.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { prisma } from '@/lib/db';
+import { enrichAudiobooksWithMatches, getAvailableAsins } from '@/lib/utils/audiobook-matcher';
+import { getCurrentUser } from '@/lib/middleware/auth';
+import { RMABLogger } from '@/lib/utils/logger';
+import { annotateWithIgnoreStatus } from '@/lib/utils/ignored-audiobooks';
+
+const logger = RMABLogger.create('API.Audiobooks.Category');
+
+/**
+ * GET /api/audiobooks/category/[categoryId]?page=1&limit=20&hideAvailable=false
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ categoryId: string }> }
+) {
+  try {
+    const { categoryId } = await params;
+    const searchParams = request.nextUrl.searchParams;
+    const page = parseInt(searchParams.get('page') || '1', 10);
+    const limit = parseInt(searchParams.get('limit') || '20', 10);
+    const hideAvailable = searchParams.get('hideAvailable') === 'true';
+
+    if (page < 1 || limit < 1 || limit > 100) {
+      return NextResponse.json(
+        { error: 'ValidationError', message: 'Invalid pagination parameters.' },
+        { status: 400 }
+      );
+    }
+
+    const skip = (page - 1) * limit;
+
+    // Get excluded ASINs when hideAvailable
+    let excludedAsins: string[] = [];
+    if (hideAvailable) {
+      const availableSet = await getAvailableAsins();
+      excludedAsins = [...availableSet];
+    }
+
+    // Query AudibleCacheCategory joined with AudibleCache
+    const whereClause: any = { categoryId };
+    if (excludedAsins.length > 0) {
+      whereClause.asin = { notIn: excludedAsins };
+    }
+
+    const [categoryEntries, totalCount] = await Promise.all([
+      prisma.audibleCacheCategory.findMany({
+        where: whereClause,
+        orderBy: { rank: 'asc' },
+        skip,
+        take: limit,
+        select: { asin: true, rank: true },
+      }),
+      prisma.audibleCacheCategory.count({ where: whereClause }),
+    ]);
+
+    if (totalCount === 0) {
+      return NextResponse.json({
+        success: true,
+        audiobooks: [],
+        count: 0,
+        totalCount: 0,
+        page,
+        totalPages: 0,
+        hasMore: false,
+        message: 'No audiobooks found for this category. Data may not have been refreshed yet.',
+      });
+    }
+
+    // Fetch full metadata from AudibleCache for these ASINs
+    const asins = categoryEntries.map((e) => e.asin);
+    const cacheEntries = await prisma.audibleCache.findMany({
+      where: { asin: { in: asins } },
+      select: {
+        asin: true,
+        title: true,
+        author: true,
+        narrator: true,
+        description: true,
+        coverArtUrl: true,
+        cachedCoverPath: true,
+        durationMinutes: true,
+        releaseDate: true,
+        rating: true,
+        genres: true,
+        lastSyncedAt: true,
+      },
+    });
+
+    // Build a map for ordering by rank
+    const cacheMap = new Map(cacheEntries.map((e) => [e.asin, e]));
+
+    // Transform to matcher input format, preserving rank order
+    const audibleBooks = categoryEntries
+      .map((entry) => {
+        const book = cacheMap.get(entry.asin);
+        if (!book) return null;
+
+        let coverUrl = book.coverArtUrl || undefined;
+        if (book.cachedCoverPath) {
+          const filename = book.cachedCoverPath.split('/').pop();
+          coverUrl = `/api/cache/thumbnails/${filename}`;
+        }
+
+        return {
+          asin: book.asin,
+          title: book.title,
+          author: book.author,
+          narrator: book.narrator || undefined,
+          description: book.description || undefined,
+          coverArtUrl: coverUrl,
+          durationMinutes: book.durationMinutes || undefined,
+          releaseDate: book.releaseDate?.toISOString() || undefined,
+          rating: book.rating ? parseFloat(book.rating.toString()) : undefined,
+          genres: (book.genres as string[]) || [],
+        };
+      })
+      .filter(Boolean) as any[];
+
+    // Enrich with library matching and request status
+    const currentUser = getCurrentUser(request);
+    const userId = currentUser?.sub || undefined;
+    const enrichedAudiobooks = await enrichAudiobooksWithMatches(audibleBooks, userId);
+
+    // Annotate with per-user ignore status
+    const annotatedAudiobooks = await annotateWithIgnoreStatus(enrichedAudiobooks, userId);
+
+    const totalPages = Math.ceil(totalCount / limit);
+    const hasMore = page < totalPages;
+
+    return NextResponse.json({
+      success: true,
+      audiobooks: annotatedAudiobooks,
+      count: enrichedAudiobooks.length,
+      totalCount,
+      page,
+      totalPages,
+      hasMore,
+      lastSync: cacheEntries[0]?.lastSyncedAt?.toISOString() || null,
+    });
+  } catch (error) {
+    logger.error('Failed to get category audiobooks', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return NextResponse.json(
+      { error: 'FetchError', message: 'Failed to fetch category audiobooks' },
+      { status: 500 }
+    );
+  }
+}

src/app/api/audiobooks/covers/route.ts

@@ -2,12 +2,14 @@
  * Component: Audiobook Covers API Route
  * Documentation: documentation/frontend/pages/login.md
  *
- * Serves random popular audiobook covers for login page floating animations
+ * Serves random popular audiobook covers for login page floating animations.
+ * Queries AudibleCacheCategory with '__popular__' categoryId for cover sources.
  */
 
 import { NextResponse } from 'next/server';
 import { prisma } from '@/lib/db';
 import { RMABLogger } from '@/lib/utils/logger';
+import { POPULAR_CATEGORY_ID } from '@/lib/processors/audible-refresh.processor';
 
 const logger = RMABLogger.create('API.Audiobooks.Covers');
 
@@ -20,18 +22,22 @@ const logger = RMABLogger.create('API.Audiobooks.Covers');
  */
 export async function GET() {
   try {
-    // Fetch all popular audiobooks with covers (up to 200)
+    // Get popular ASINs from category table (up to 200)
+    const categoryEntries = await prisma.audibleCacheCategory.findMany({
+      where: { categoryId: POPULAR_CATEGORY_ID },
+      orderBy: { rank: 'asc' },
+      take: 200,
+      select: { asin: true },
+    });
+
+    const asins = categoryEntries.map((e) => e.asin);
+
+    // Fetch cover data from AudibleCache for popular ASINs with cached covers
     const audiobooks = await prisma.audibleCache.findMany({
       where: {
-        isPopular: true,
-        cachedCoverPath: {
-          not: null,
-        },
+        asin: { in: asins },
+        cachedCoverPath: { not: null },
       },
-      orderBy: {
-        popularRank: 'asc',
-      },
-      take: 200,
       select: {
         asin: true,
         title: true,

src/app/api/audiobooks/new-releases/route.ts

@@ -2,20 +2,23 @@
  * Component: New Releases API Route
  * Documentation: documentation/integrations/audible.md
  *
- * Serves new release audiobooks from audible_cache with real-time Plex matching
+ * Serves new release audiobooks from AudibleCacheCategory with real-time library matching.
+ * New releases are stored with categoryId '__new_releases__' in the unified category table.
  */
 
 import { NextRequest, NextResponse } from 'next/server';
 import { prisma } from '@/lib/db';
-import { enrichAudiobooksWithMatches } from '@/lib/utils/audiobook-matcher';
+import { enrichAudiobooksWithMatches, getAvailableAsins } from '@/lib/utils/audiobook-matcher';
 import { getCurrentUser } from '@/lib/middleware/auth';
 import { RMABLogger } from '@/lib/utils/logger';
+import { annotateWithIgnoreStatus } from '@/lib/utils/ignored-audiobooks';
+import { NEW_RELEASES_CATEGORY_ID } from '@/lib/processors/audible-refresh.processor';
 
 const logger = RMABLogger.create('API.Audiobooks.NewReleases');
 
 /**
  * GET /api/audiobooks/new-releases?page=1&limit=20
- * Get new release audiobooks from audible_cache with pagination
+ * Get new release audiobooks from AudibleCacheCategory with pagination
  *
  * Real-time matching against plex_library determines availability.
  */
@@ -24,6 +27,7 @@ export async function GET(request: NextRequest) {
     const searchParams = request.nextUrl.searchParams;
     const page = parseInt(searchParams.get('page') || '1', 10);
     const limit = parseInt(searchParams.get('limit') || '20', 10);
+    const hideAvailable = searchParams.get('hideAvailable') === 'true';
 
     // Validate pagination parameters
     if (page < 1 || limit < 1 || limit > 100) {
@@ -38,38 +42,28 @@ export async function GET(request: NextRequest) {
 
     const skip = (page - 1) * limit;
 
-    // Query audible_cache for new release audiobooks
-    const [audiobooks, totalCount] = await Promise.all([
-      prisma.audibleCache.findMany({
-        where: {
-          isNewRelease: true,
-        },
-        orderBy: {
-          newReleaseRank: 'asc',
-        },
+    // When hideAvailable is enabled, exclude ASINs that are in the library or have completed requests
+    let excludedAsins: string[] = [];
+    if (hideAvailable) {
+      const availableSet = await getAvailableAsins();
+      excludedAsins = [...availableSet];
+    }
+
+    const whereClause: any = { categoryId: NEW_RELEASES_CATEGORY_ID };
+    if (excludedAsins.length > 0) {
+      whereClause.asin = { notIn: excludedAsins };
+    }
+
+    // Query AudibleCacheCategory for new release audiobooks
+    const [categoryEntries, totalCount] = await Promise.all([
+      prisma.audibleCacheCategory.findMany({
+        where: whereClause,
+        orderBy: { rank: 'asc' },
         skip,
         take: limit,
-        select: {
-          id: true,
-          asin: true,
-          title: true,
-          author: true,
-          narrator: true,
-          description: true,
-          coverArtUrl: true,
-          cachedCoverPath: true,
-          durationMinutes: true,
-          releaseDate: true,
-          rating: true,
-          genres: true,
-          lastSyncedAt: true,
-        },
-      }),
-      prisma.audibleCache.count({
-        where: {
-          isNewRelease: true,
-        },
+        select: { asin: true, rank: true },
       }),
+      prisma.audibleCacheCategory.count({ where: whereClause }),
     ]);
 
     // If no data found, return helpful message
@@ -86,30 +80,56 @@ export async function GET(request: NextRequest) {
       });
     }
 
-    // Transform to matcher input format (uses ASIN as required field)
-    // Use cached cover path when available, otherwise fall back to coverArtUrl
-    const audibleBooks = audiobooks.map((book) => {
-      // Convert cached path to API URL if it exists
-      let coverUrl = book.coverArtUrl || undefined;
-      if (book.cachedCoverPath) {
-        const filename = book.cachedCoverPath.split('/').pop();
-        coverUrl = `/api/cache/thumbnails/${filename}`;
-      }
-
-      return {
-        asin: book.asin,
-        title: book.title,
-        author: book.author,
-        narrator: book.narrator || undefined,
-        description: book.description || undefined,
-        coverArtUrl: coverUrl,
-        durationMinutes: book.durationMinutes || undefined,
-        releaseDate: book.releaseDate?.toISOString() || undefined,
-        rating: book.rating ? parseFloat(book.rating.toString()) : undefined,
-        genres: (book.genres as string[]) || [],
-      };
+    // Fetch full metadata from AudibleCache for these ASINs
+    const asins = categoryEntries.map((e) => e.asin);
+    const cacheEntries = await prisma.audibleCache.findMany({
+      where: { asin: { in: asins } },
+      select: {
+        asin: true,
+        title: true,
+        author: true,
+        narrator: true,
+        description: true,
+        coverArtUrl: true,
+        cachedCoverPath: true,
+        durationMinutes: true,
+        releaseDate: true,
+        rating: true,
+        genres: true,
+        lastSyncedAt: true,
+      },
     });
 
+    // Build a map for ordering by rank
+    const cacheMap = new Map(cacheEntries.map((e) => [e.asin, e]));
+
+    // Transform to matcher input format, preserving rank order
+    const audibleBooks = categoryEntries
+      .map((entry) => {
+        const book = cacheMap.get(entry.asin);
+        if (!book) return null;
+
+        let coverUrl = book.coverArtUrl || undefined;
+        if (book.cachedCoverPath) {
+          const filename = book.cachedCoverPath.split('/').pop();
+          coverUrl = `/api/cache/thumbnails/${filename}`;
+        }
+
+        return {
+          asin: book.asin,
+          title: book.title,
+          author: book.author,
+          narrator: book.narrator || undefined,
+          description: book.description || undefined,
+          coverArtUrl: coverUrl,
+          durationMinutes: book.durationMinutes || undefined,
+          releaseDate: book.releaseDate?.toISOString() || undefined,
+          rating: book.rating ? parseFloat(book.rating.toString()) : undefined,
+          genres: (book.genres as string[]) || [],
+        };
+      })
+      .filter(Boolean) as any[];
+
     // Get current user (optional - for request status enrichment)
     const currentUser = getCurrentUser(request);
     const userId = currentUser?.sub || undefined;
@@ -117,18 +137,21 @@ export async function GET(request: NextRequest) {
     // Enrich with real-time Plex library matching and request status
     const enrichedAudiobooks = await enrichAudiobooksWithMatches(audibleBooks, userId);
 
+    // Annotate with per-user ignore status
+    const annotatedAudiobooks = await annotateWithIgnoreStatus(enrichedAudiobooks, userId);
+
     const totalPages = Math.ceil(totalCount / limit);
     const hasMore = page < totalPages;
 
     return NextResponse.json({
       success: true,
-      audiobooks: enrichedAudiobooks,
+      audiobooks: annotatedAudiobooks,
       count: enrichedAudiobooks.length,
       totalCount,
       page,
       totalPages,
       hasMore,
-      lastSync: audiobooks[0]?.lastSyncedAt?.toISOString() || null,
+      lastSync: cacheEntries[0]?.lastSyncedAt?.toISOString() || null,
     });
   } catch (error) {
     logger.error('Failed to get new releases', { error: error instanceof Error ? error.message : String(error) });

src/app/api/audiobooks/popular/route.ts

@@ -2,20 +2,23 @@
  * Component: Popular Audiobooks API Route
  * Documentation: documentation/integrations/audible.md
  *
- * Serves popular audiobooks from audible_cache with real-time Plex matching
+ * Serves popular audiobooks from AudibleCacheCategory with real-time library matching.
+ * Popular books are stored with categoryId '__popular__' in the unified category table.
  */
 
 import { NextRequest, NextResponse } from 'next/server';
 import { prisma } from '@/lib/db';
-import { enrichAudiobooksWithMatches } from '@/lib/utils/audiobook-matcher';
+import { enrichAudiobooksWithMatches, getAvailableAsins } from '@/lib/utils/audiobook-matcher';
 import { getCurrentUser } from '@/lib/middleware/auth';
 import { RMABLogger } from '@/lib/utils/logger';
+import { annotateWithIgnoreStatus } from '@/lib/utils/ignored-audiobooks';
+import { POPULAR_CATEGORY_ID } from '@/lib/processors/audible-refresh.processor';
 
 const logger = RMABLogger.create('API.Audiobooks.Popular');
 
 /**
  * GET /api/audiobooks/popular?page=1&limit=20
- * Get popular audiobooks from audible_cache with pagination
+ * Get popular audiobooks from AudibleCacheCategory with pagination
  *
  * Real-time matching against plex_library determines availability.
  */
@@ -24,6 +27,7 @@ export async function GET(request: NextRequest) {
     const searchParams = request.nextUrl.searchParams;
     const page = parseInt(searchParams.get('page') || '1', 10);
     const limit = parseInt(searchParams.get('limit') || '20', 10);
+    const hideAvailable = searchParams.get('hideAvailable') === 'true';
 
     // Validate pagination parameters
     if (page < 1 || limit < 1 || limit > 100) {
@@ -38,38 +42,28 @@ export async function GET(request: NextRequest) {
 
     const skip = (page - 1) * limit;
 
-    // Query audible_cache for popular audiobooks
-    const [audiobooks, totalCount] = await Promise.all([
-      prisma.audibleCache.findMany({
-        where: {
-          isPopular: true,
-        },
-        orderBy: {
-          popularRank: 'asc',
-        },
+    // When hideAvailable is enabled, exclude ASINs that are in the library or have completed requests
+    let excludedAsins: string[] = [];
+    if (hideAvailable) {
+      const availableSet = await getAvailableAsins();
+      excludedAsins = [...availableSet];
+    }
+
+    const whereClause: any = { categoryId: POPULAR_CATEGORY_ID };
+    if (excludedAsins.length > 0) {
+      whereClause.asin = { notIn: excludedAsins };
+    }
+
+    // Query AudibleCacheCategory for popular audiobooks
+    const [categoryEntries, totalCount] = await Promise.all([
+      prisma.audibleCacheCategory.findMany({
+        where: whereClause,
+        orderBy: { rank: 'asc' },
         skip,
         take: limit,
-        select: {
-          id: true,
-          asin: true,
-          title: true,
-          author: true,
-          narrator: true,
-          description: true,
-          coverArtUrl: true,
-          cachedCoverPath: true,
-          durationMinutes: true,
-          releaseDate: true,
-          rating: true,
-          genres: true,
-          lastSyncedAt: true,
-        },
-      }),
-      prisma.audibleCache.count({
-        where: {
-          isPopular: true,
-        },
+        select: { asin: true, rank: true },
       }),
+      prisma.audibleCacheCategory.count({ where: whereClause }),
     ]);
 
     // If no data found, return helpful message
@@ -86,30 +80,56 @@ export async function GET(request: NextRequest) {
       });
     }
 
-    // Transform to matcher input format (uses ASIN as required field)
-    // Use cached cover path when available, otherwise fall back to coverArtUrl
-    const audibleBooks = audiobooks.map((book) => {
-      // Convert cached path to API URL if it exists
-      let coverUrl = book.coverArtUrl || undefined;
-      if (book.cachedCoverPath) {
-        const filename = book.cachedCoverPath.split('/').pop();
-        coverUrl = `/api/cache/thumbnails/${filename}`;
-      }
-
-      return {
-        asin: book.asin,
-        title: book.title,
-        author: book.author,
-        narrator: book.narrator || undefined,
-        description: book.description || undefined,
-        coverArtUrl: coverUrl,
-        durationMinutes: book.durationMinutes || undefined,
-        releaseDate: book.releaseDate?.toISOString() || undefined,
-        rating: book.rating ? parseFloat(book.rating.toString()) : undefined,
-        genres: (book.genres as string[]) || [],
-      };
+    // Fetch full metadata from AudibleCache for these ASINs
+    const asins = categoryEntries.map((e) => e.asin);
+    const cacheEntries = await prisma.audibleCache.findMany({
+      where: { asin: { in: asins } },
+      select: {
+        asin: true,
+        title: true,
+        author: true,
+        narrator: true,
+        description: true,
+        coverArtUrl: true,
+        cachedCoverPath: true,
+        durationMinutes: true,
+        releaseDate: true,
+        rating: true,
+        genres: true,
+        lastSyncedAt: true,
+      },
     });
 
+    // Build a map for ordering by rank
+    const cacheMap = new Map(cacheEntries.map((e) => [e.asin, e]));
+
+    // Transform to matcher input format, preserving rank order
+    const audibleBooks = categoryEntries
+      .map((entry) => {
+        const book = cacheMap.get(entry.asin);
+        if (!book) return null;
+
+        let coverUrl = book.coverArtUrl || undefined;
+        if (book.cachedCoverPath) {
+          const filename = book.cachedCoverPath.split('/').pop();
+          coverUrl = `/api/cache/thumbnails/${filename}`;
+        }
+
+        return {
+          asin: book.asin,
+          title: book.title,
+          author: book.author,
+          narrator: book.narrator || undefined,
+          description: book.description || undefined,
+          coverArtUrl: coverUrl,
+          durationMinutes: book.durationMinutes || undefined,
+          releaseDate: book.releaseDate?.toISOString() || undefined,
+          rating: book.rating ? parseFloat(book.rating.toString()) : undefined,
+          genres: (book.genres as string[]) || [],
+        };
+      })
+      .filter(Boolean) as any[];
+
     // Get current user (optional - for request status enrichment)
     const currentUser = getCurrentUser(request);
     const userId = currentUser?.sub || undefined;
@@ -117,18 +137,21 @@ export async function GET(request: NextRequest) {
     // Enrich with real-time Plex library matching and request status
     const enrichedAudiobooks = await enrichAudiobooksWithMatches(audibleBooks, userId);
 
+    // Annotate with per-user ignore status
+    const annotatedAudiobooks = await annotateWithIgnoreStatus(enrichedAudiobooks, userId);
+
     const totalPages = Math.ceil(totalCount / limit);
     const hasMore = page < totalPages;
 
     return NextResponse.json({
       success: true,
-      audiobooks: enrichedAudiobooks,
+      audiobooks: annotatedAudiobooks,
       count: enrichedAudiobooks.length,
       totalCount,
       page,
       totalPages,
       hasMore,
-      lastSync: audiobooks[0]?.lastSyncedAt?.toISOString() || null,
+      lastSync: cacheEntries[0]?.lastSyncedAt?.toISOString() || null,
     });
   } catch (error) {
     logger.error('Failed to get popular audiobooks', { error: error instanceof Error ? error.message : String(error) });

src/app/api/audiobooks/search/route.ts

@@ -6,8 +6,11 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getAudibleService } from '@/lib/integrations/audible.service';
 import { enrichAudiobooksWithMatches } from '@/lib/utils/audiobook-matcher';
+import { deduplicateAndCollectGroups } from '@/lib/utils/deduplicate-audiobooks';
+import { persistDedupGroups } from '@/lib/services/works.service';
 import { getCurrentUser } from '@/lib/middleware/auth';
 import { RMABLogger } from '@/lib/utils/logger';
+import { annotateWithIgnoreStatus } from '@/lib/utils/ignored-audiobooks';
 
 const logger = RMABLogger.create('API.Audiobooks.Search');
 
@@ -38,14 +41,25 @@ export async function GET(request: NextRequest) {
     const currentUser = getCurrentUser(request);
     const userId = currentUser?.sub || undefined;
 
+    // Deduplicate before enrichment to avoid wasted DB queries on duplicate entries
+    const { books: dedupedResults, groups } = deduplicateAndCollectGroups(results.results);
+
+    // Fire-and-forget: persist dedup groups to works table for cross-ASIN matching
+    if (groups.length > 0) {
+      persistDedupGroups(groups).catch(() => {});
+    }
+
     // Enrich search results with availability and request status information
-    const enrichedResults = await enrichAudiobooksWithMatches(results.results, userId);
+    const enrichedResults = await enrichAudiobooksWithMatches(dedupedResults, userId);
+
+    // Annotate with per-user ignore status
+    const annotatedResults = await annotateWithIgnoreStatus(enrichedResults, userId);
 
     return NextResponse.json({
       success: true,
       query: results.query,
-      results: enrichedResults,
-      totalResults: results.totalResults,
+      results: annotatedResults,
+      totalResults: enrichedResults.length,
       page: results.page,
       hasMore: results.hasMore,
     });

src/app/api/auth/admin/login/route.ts

@@ -38,9 +38,11 @@ export async function POST(request: NextRequest) {
       );
     }
 
+    const normalizedUsername = username.trim().toLowerCase();
+
     // Find user by local admin identifier
     const user = await prisma.user.findUnique({
-      where: { plexId: `local-${username}` },
+      where: { plexId: `local-${normalizedUsername}` },
     });
 
     if (!user) {

src/app/api/auth/refresh/route.ts

@@ -45,9 +45,17 @@ export async function POST(request: NextRequest) {
     // Get user from database
     const user = await prisma.user.findUnique({
       where: { id: payload.sub },
+      select: {
+        id: true,
+        plexId: true,
+        plexUsername: true,
+        role: true,
+        deletedAt: true,
+        sessionsInvalidatedAt: true,
+      },
     });
 
-    if (!user) {
+    if (!user || user.deletedAt) {
       return NextResponse.json(
         {
           error: 'Unauthorized',
@@ -57,6 +65,19 @@ export async function POST(request: NextRequest) {
       );
     }
 
+    // Check if session was invalidated after this refresh token was issued
+    if (user.sessionsInvalidatedAt && payload.iat &&
+        payload.iat < Math.floor(user.sessionsInvalidatedAt.getTime() / 1000)) {
+      logger.warn('Refresh token issued before session invalidation', { userId: payload.sub });
+      return NextResponse.json(
+        {
+          error: 'Unauthorized',
+          message: 'Session has been revoked',
+        },
+        { status: 401 }
+      );
+    }
+
     // Generate new access token
     const accessToken = generateAccessToken({
       sub: user.id,

src/app/api/auth/token/login/route.ts

@@ -0,0 +1,90 @@
+/**
+ * Component: Token Login Route
+ * Documentation: documentation/backend/services/auth.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { prisma } from '@/lib/db';
+import { generateAccessToken, generateRefreshToken } from '@/lib/utils/jwt';
+import { RMABLogger } from '@/lib/utils/logger';
+import { checkTokenLoginRateLimit } from '@/lib/utils/rateLimit';
+import crypto from 'crypto';
+
+const logger = RMABLogger.create('API.Auth.TokenLogin');
+
+export async function POST(request: NextRequest) {
+  try {
+    const ip = request.headers.get('x-forwarded-for') ?? 'unknown';
+    const rateLimit = checkTokenLoginRateLimit(ip);
+    if (!rateLimit.allowed) {
+      return NextResponse.json(
+        { error: 'Too many login attempts. Please try again later.' },
+        {
+          status: 429,
+          headers: { 'Retry-After': String(rateLimit.retryAfterSeconds) },
+        }
+      );
+    }
+
+    const { token } = await request.json();
+
+    if (!token) {
+      return NextResponse.json({ error: 'Missing token parameter' }, { status: 400 });
+    }
+
+    const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
+
+    const user = await prisma.user.findFirst({
+      where: {
+        loginTokenHash: tokenHash,
+        deletedAt: null,
+      },
+      select: {
+        id: true,
+        plexId: true,
+        plexUsername: true,
+        plexEmail: true,
+        avatarUrl: true,
+        role: true,
+      },
+    });
+
+    if (!user) {
+      logger.warn('Token login failed - not found or user deleted');
+      return NextResponse.json({ error: 'Invalid token' }, { status: 401 });
+    }
+
+    await prisma.user.update({
+      where: { id: user.id },
+      data: { lastLoginAt: new Date() },
+    });
+
+    const accessToken = generateAccessToken({
+      sub: user.id,
+      plexId: user.plexId,
+      username: user.plexUsername,
+      role: user.role,
+    });
+
+    const refreshToken = generateRefreshToken(user.id);
+
+    logger.info('Token login successful', { username: user.plexUsername });
+
+    return NextResponse.json({
+      accessToken,
+      refreshToken,
+      user: {
+        id: user.id,
+        username: user.plexUsername,
+        email: user.plexEmail,
+        avatarUrl: user.avatarUrl,
+        role: user.role,
+      },
+    });
+  } catch (error) {
+    logger.error('Token login error', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return NextResponse.json({ error: 'Authentication failed' }, { status: 500 });
+  }
+}

src/app/api/authors/[asin]/books/route.ts

@@ -6,8 +6,11 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getAudibleService } from '@/lib/integrations/audible.service';
 import { enrichAudiobooksWithMatches } from '@/lib/utils/audiobook-matcher';
+import { deduplicateAndCollectGroups } from '@/lib/utils/deduplicate-audiobooks';
+import { persistDedupGroups } from '@/lib/services/works.service';
 import { getCurrentUser } from '@/lib/middleware/auth';
 import { RMABLogger } from '@/lib/utils/logger';
+import { annotateWithIgnoreStatus } from '@/lib/utils/ignored-audiobooks';
 
 const logger = RMABLogger.create('API.Authors.Books');
 
@@ -46,23 +49,38 @@ export async function GET(
       );
     }
 
-    logger.info(`Fetching books for author "${authorName}" (ASIN: ${asin})`);
+    const page = parseInt(request.nextUrl.searchParams.get('page') || '1', 10);
+
+    logger.info(`Fetching books for author "${authorName}" (ASIN: ${asin}), page ${page}`);
 
     const audibleService = getAudibleService();
-    const books = await audibleService.searchByAuthorAsin(authorName.trim(), asin);
+    const result = await audibleService.searchByAuthorAsin(authorName.trim(), asin, page);
+
+    // Deduplicate before enrichment to avoid wasted DB queries on duplicate entries
+    const { books: dedupedBooks, groups } = deduplicateAndCollectGroups(result.books);
+
+    // Fire-and-forget: persist dedup groups to works table for cross-ASIN matching
+    if (groups.length > 0) {
+      persistDedupGroups(groups).catch(() => {});
+    }
 
     // Enrich with library availability and request status
     const userId = currentUser.sub || undefined;
-    const enrichedBooks = await enrichAudiobooksWithMatches(books, userId);
+    const enrichedBooks = await enrichAudiobooksWithMatches(dedupedBooks, userId);
 
-    logger.info(`Author books complete: "${authorName}" → ${enrichedBooks.length} books`);
+    // Annotate with per-user ignore status
+    const annotatedBooks = await annotateWithIgnoreStatus(enrichedBooks, userId);
+
+    logger.info(`Author books complete: "${authorName}" → ${annotatedBooks.length} books (page ${page})`);
 
     return NextResponse.json({
       success: true,
-      books: enrichedBooks,
+      books: annotatedBooks,
       authorName: authorName.trim(),
       authorAsin: asin,
       totalBooks: enrichedBooks.length,
+      hasMore: result.hasMore,
+      page: result.page,
     });
   } catch (error) {
     logger.error('Failed to fetch author books', { error: error instanceof Error ? error.message : String(error) });

src/app/api/bookdate/config/route.ts

@@ -59,9 +59,9 @@ async function saveConfig(req: AuthenticatedRequest) {
       );
     }
 
-    if (!['openai', 'claude', 'custom'].includes(provider)) {
+    if (!['openai', 'claude', 'custom', 'gemini'].includes(provider)) {
       return NextResponse.json(
-        { error: 'Invalid provider. Must be "openai", "claude", or "custom"' },
+        { error: 'Invalid provider. Must be "openai", "claude", "custom", or "gemini"' },
         { status: 400 }
       );
     }
@@ -107,7 +107,7 @@ async function saveConfig(req: AuthenticatedRequest) {
       // No new API key, use existing one
       encryptedApiKeyToUse = existingConfig.apiKey;
     } else {
-      // API key required for OpenAI/Claude
+      // API key required for OpenAI/Claude/Gemini
       return NextResponse.json(
         { error: 'API key is required' },
         { status: 400 }

src/app/api/bookdate/test-connection/route.ts

@@ -52,6 +52,30 @@ async function fetchClaudeModels(apiKey: string): Promise<{ id: string; name: st
   return allModels;
 }
 
+// Fetch available Gemini models from the Google API
+async function fetchGeminiModels(apiKey: string): Promise<{ id: string; name: string }[]> {
+  const response = await fetch(
+    'https://generativelanguage.googleapis.com/v1beta/models',
+    { headers: { 'x-goog-api-key': apiKey } }
+  );
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    logger.error('Gemini API error', { error: errorText });
+    throw new Error('Invalid Gemini API key or connection failed');
+  }
+
+  const data = await response.json();
+
+  return (data.models || [])
+    .filter((m: any) => m.name?.startsWith('models/gemini-') && m.supportedGenerationMethods?.includes('generateContent'))
+    .map((m: any) => ({
+      id: m.name.replace('models/', ''),
+      name: m.displayName || m.name.replace('models/', ''),
+    }))
+    .sort((a: any, b: any) => a.name.localeCompare(b.name));
+}
+
 // Helper functions for custom provider
 function isValidBaseUrl(url: string): boolean {
   try {
@@ -79,9 +103,9 @@ async function authenticatedHandler(req: AuthenticatedRequest) {
       );
     }
 
-    if (!['openai', 'claude', 'custom'].includes(provider)) {
+    if (!['openai', 'claude', 'custom', 'gemini'].includes(provider)) {
       return NextResponse.json(
-        { error: 'Invalid provider. Must be "openai", "claude", or "custom"' },
+        { error: 'Invalid provider. Must be "openai", "claude", "custom", or "gemini"' },
         { status: 400 }
       );
     }
@@ -193,6 +217,16 @@ async function authenticatedHandler(req: AuthenticatedRequest) {
           { status: 400 }
         );
       }
+    } else if (provider === 'gemini') {
+      // Gemini: Fetch models dynamically from the Google API
+      try {
+        models = await fetchGeminiModels(testApiKey);
+      } catch {
+        return NextResponse.json(
+          { error: 'Invalid Gemini API key or connection failed' },
+          { status: 400 }
+        );
+      }
     } else if (provider === 'custom') {
       // Custom: Fetch models from custom OpenAI-compatible endpoint
       const normalizedUrl = normalizeBaseUrl(testBaseUrl);
@@ -291,9 +325,9 @@ async function unauthenticatedHandler(req: NextRequest) {
       );
     }
 
-    if (!['openai', 'claude', 'custom'].includes(provider)) {
+    if (!['openai', 'claude', 'custom', 'gemini'].includes(provider)) {
       return NextResponse.json(
-        { error: 'Invalid provider. Must be "openai", "claude", or "custom"' },
+        { error: 'Invalid provider. Must be "openai", "claude", "custom", or "gemini"' },
         { status: 400 }
       );
     }
@@ -363,6 +397,16 @@ async function unauthenticatedHandler(req: NextRequest) {
           { status: 400 }
         );
       }
+    } else if (provider === 'gemini') {
+      // Gemini: Fetch models dynamically
+      try {
+        models = await fetchGeminiModels(apiKey);
+      } catch {
+        return NextResponse.json(
+          { error: 'Invalid Gemini API key or connection failed' },
+          { status: 400 }
+        );
+      }
     } else if (provider === 'custom') {
       // Custom: Fetch models from custom OpenAI-compatible endpoint
       const normalizedUrl = normalizeBaseUrl(baseUrl);

src/app/api/requests/[id]/fetch-ebook/route.ts

@@ -123,6 +123,7 @@ export async function POST(
             parentRequestId,
             status: 'pending',
             progress: 0,
+            customSearchTerms: parentRequest.customSearchTerms,
           },
         });
 

src/app/api/requests/[id]/interactive-search-ebook/route.ts

@@ -71,41 +71,56 @@ export async function POST(
         const body = await request.json().catch(() => ({}));
         const customTitle = body.customTitle as string | undefined;
 
-        // Get the parent audiobook request
-        const parentRequest = await prisma.request.findUnique({
+        // Get the request (can be audiobook parent or direct ebook request)
+        const requestRecord = await prisma.request.findUnique({
           where: { id: parentRequestId },
           include: { audiobook: true },
         });
 
-        if (!parentRequest) {
+        if (!requestRecord) {
           return NextResponse.json({ error: 'Request not found' }, { status: 404 });
         }
 
-        if (parentRequest.type !== 'audiobook') {
-          return NextResponse.json({ error: 'Can only search ebooks for audiobook requests' }, { status: 400 });
+        // Support two flows:
+        // Flow A (sidecar): Audiobook request in downloaded/available state
+        // Flow B (direct):  Ebook request in pending/failed/awaiting_search state
+        const isDirectEbookSearch = requestRecord.type === 'ebook';
+        const isAudiobookSidecar = requestRecord.type === 'audiobook';
+
+        if (!isDirectEbookSearch && !isAudiobookSidecar) {
+          return NextResponse.json({ error: 'Invalid request type' }, { status: 400 });
         }
 
-        if (!['downloaded', 'available'].includes(parentRequest.status)) {
+        if (isAudiobookSidecar && !['downloaded', 'available'].includes(requestRecord.status)) {
           return NextResponse.json(
-            { error: `Cannot search ebooks for request in ${parentRequest.status} status` },
+            { error: `Cannot search ebooks for audiobook request in ${requestRecord.status} status` },
             { status: 400 }
           );
         }
 
-        // Check for existing non-retryable ebook request
-        const existingEbookRequest = await prisma.request.findFirst({
-          where: {
-            parentRequestId,
-            type: 'ebook',
-            deletedAt: null,
-          },
-        });
+        if (isDirectEbookSearch && !['pending', 'failed', 'awaiting_search'].includes(requestRecord.status)) {
+          return NextResponse.json(
+            { error: `Cannot search for ebook request in ${requestRecord.status} status` },
+            { status: 400 }
+          );
+        }
 
-        if (existingEbookRequest && !['failed', 'awaiting_search'].includes(existingEbookRequest.status)) {
-          return NextResponse.json({
-            error: `E-book request already exists (status: ${existingEbookRequest.status})`,
-            existingRequestId: existingEbookRequest.id,
-          }, { status: 400 });
+        // Check for existing child ebook requests (sidecar mode only)
+        if (isAudiobookSidecar) {
+          const existingEbookRequest = await prisma.request.findFirst({
+            where: {
+              parentRequestId,
+              type: 'ebook',
+              deletedAt: null,
+            },
+          });
+
+          if (existingEbookRequest && !['failed', 'awaiting_search'].includes(existingEbookRequest.status)) {
+            return NextResponse.json({
+              error: `E-book request already exists (status: ${existingEbookRequest.status})`,
+              existingRequestId: existingEbookRequest.id,
+            }, { status: 400 });
+          }
         }
 
         // Get ebook configuration
@@ -121,7 +136,7 @@ export async function POST(
         const isAnnasArchiveEnabled = annasArchiveEnabled === 'true';
         const isIndexerSearchEnabled = indexerSearchEnabled === 'true';
         const format = preferredFormat || 'epub';
-        const annasBaseUrl = baseUrl || 'https://annas-archive.li';
+        const annasBaseUrl = baseUrl || 'https://annas-archive.gl';
 
         // Get language code from Audible region config
         const region = await configService.getAudibleRegion() as AudibleRegion;
@@ -135,10 +150,10 @@ export async function POST(
           );
         }
 
-        const audiobook = parentRequest.audiobook;
+        const audiobook = requestRecord.audiobook;
         const searchTitle = customTitle || audiobook.title;
 
-        logger.info(`Interactive ebook search for "${searchTitle}" by ${audiobook.author}`);
+        logger.info(`Interactive ebook search for "${searchTitle}" by ${audiobook.author} (${isDirectEbookSearch ? 'direct' : 'sidecar'})`);
         logger.info(`Sources: Anna's Archive=${isAnnasArchiveEnabled}, Indexer=${isIndexerSearchEnabled}`);
 
         // Search both sources in parallel

src/app/api/requests/[id]/interactive-search/route.ts

@@ -125,8 +125,8 @@ export async function POST(
         logger.info(`Skipping ${skippedIndexers.length} indexer(s) with no audiobook categories: ${skippedNames}`);
       }
 
-      // Use custom title if provided, otherwise use audiobook's title
-      const searchTitle = customTitle || requestRecord.audiobook.title;
+      // Use custom title if provided, then custom search terms, then audiobook's title
+      const searchTitle = customTitle || requestRecord.customSearchTerms || requestRecord.audiobook.title;
       const searchAuthor = requestRecord.audiobook.author;
 
       logger.info(`Searching ${indexersConfig.length - skippedIndexers.length} enabled indexers in ${groups.length} group${groups.length > 1 ? 's' : ''}`, { searchTitle });
@@ -196,10 +196,10 @@ export async function POST(
       const langConfig = getLanguageForRegion(region);
 
       // Rank torrents using the ranking algorithm with indexer priorities and flag configs
-      // Always use the audiobook's title/author for ranking (not custom search query)
+      // Use searchTitle for ranking so custom search terms and search bar overrides are respected
       // requireAuthor: false - interactive mode, show all results for user decision
       const rankedResults = rankTorrents(results, {
-        title: requestRecord.audiobook.title,
+        title: searchTitle,
         author: requestRecord.audiobook.author,
         durationMinutes,
       }, {
@@ -218,7 +218,7 @@ export async function POST(
       const top3 = rankedResults.slice(0, 3);
       if (top3.length > 0) {
         logger.debug('==================== RANKING DEBUG ====================');
-        logger.debug('Search parameters', { searchTitle, requestedTitle: requestRecord.audiobook.title, requestedAuthor: requestRecord.audiobook.author });
+        logger.debug('Search parameters', { searchTitle, rankingTitle: searchTitle, audiobookTitle: requestRecord.audiobook.title, requestedAuthor: requestRecord.audiobook.author });
         logger.debug(`Top ${top3.length} results (out of ${rankedResults.length} total)`);
         logger.debug('--------------------------------------------------------');
         top3.forEach((result, index) => {

src/app/api/requests/[id]/manual-search/route.ts

@@ -64,14 +64,20 @@ export async function POST(
         );
       }
 
-      // Trigger search job
+      // Trigger appropriate search job based on request type
       const jobQueue = getJobQueueService();
-      await jobQueue.addSearchJob(id, {
+      const audiobookData = {
         id: requestRecord.audiobook.id,
         title: requestRecord.audiobook.title,
         author: requestRecord.audiobook.author,
         asin: requestRecord.audiobook.audibleAsin || undefined,
-      });
+      };
+
+      if (requestRecord.type === 'ebook') {
+        await jobQueue.addSearchEbookJob(id, audiobookData);
+      } else {
+        await jobQueue.addSearchJob(id, audiobookData);
+      }
 
       // Update request status
       const updated = await prisma.request.update({

src/app/api/requests/[id]/select-ebook/route.ts

@@ -52,17 +52,32 @@ export async function POST(
           return NextResponse.json({ error: 'Ebook source not specified' }, { status: 400 });
         }
 
-        // Get the parent audiobook request
-        const parentRequest = await prisma.request.findUnique({
+        // Get the request - could be an audiobook request or an existing ebook request
+        const foundRequest = await prisma.request.findUnique({
           where: { id: parentRequestId },
           include: { audiobook: true },
         });
 
-        if (!parentRequest) {
+        if (!foundRequest) {
           return NextResponse.json({ error: 'Request not found' }, { status: 404 });
         }
 
-        if (parentRequest.type !== 'audiobook') {
+        // If this is an ebook request, find the parent audiobook request
+        let parentRequest;
+        if (foundRequest.type === 'ebook') {
+          if (!foundRequest.parentRequestId) {
+            return NextResponse.json({ error: 'Ebook request has no parent audiobook request' }, { status: 400 });
+          }
+          parentRequest = await prisma.request.findUnique({
+            where: { id: foundRequest.parentRequestId },
+            include: { audiobook: true },
+          });
+          if (!parentRequest) {
+            return NextResponse.json({ error: 'Parent audiobook request not found' }, { status: 404 });
+          }
+        } else if (foundRequest.type === 'audiobook') {
+          parentRequest = foundRequest;
+        } else {
           return NextResponse.json({ error: 'Can only select ebooks for audiobook requests' }, { status: 400 });
         }
 
@@ -74,13 +89,16 @@ export async function POST(
         }
 
         // Check for existing ebook request
-        let ebookRequest = await prisma.request.findFirst({
-          where: {
-            parentRequestId,
-            type: 'ebook',
-            deletedAt: null,
-          },
-        });
+        // If we were given an ebook request ID directly, use that; otherwise search by parent
+        let ebookRequest = foundRequest.type === 'ebook'
+          ? foundRequest
+          : await prisma.request.findFirst({
+              where: {
+                parentRequestId: parentRequest.id,
+                type: 'ebook',
+                deletedAt: null,
+              },
+            });
 
         if (ebookRequest && !['failed', 'awaiting_search', 'pending'].includes(ebookRequest.status)) {
           return NextResponse.json({
@@ -109,9 +127,10 @@ export async function POST(
               userId: parentRequest.userId,
               audiobookId: parentRequest.audiobookId,
               type: 'ebook',
-              parentRequestId,
+              parentRequestId: parentRequest.id,
               status: 'searching',
               progress: 0,
+              customSearchTerms: parentRequest.customSearchTerms,
             },
           });
           logger.info(`Created new ebook request ${ebookRequest.id}`);

src/app/api/requests/route.ts

@@ -53,7 +53,7 @@ export async function POST(request: NextRequest) {
         narrator: audiobook.narrator,
         description: audiobook.description,
         coverArtUrl: audiobook.coverArtUrl,
-      }, { skipAutoSearch });
+      }, { skipAutoSearch, bypassIgnore: true });
 
       if (!result.success) {
         const statusMap: Record<string, { error: string; status: number }> = {
@@ -61,6 +61,7 @@ export async function POST(request: NextRequest) {
           being_processed: { error: 'BeingProcessed', status: 409 },
           duplicate: { error: 'DuplicateRequest', status: 409 },
           user_not_found: { error: 'UserNotFound', status: 404 },
+          ignored: { error: 'Ignored', status: 409 },
         };
         const mapped = statusMap[result.reason] || { error: 'RequestError', status: 500 };
         return NextResponse.json(
@@ -97,9 +98,27 @@ export async function POST(request: NextRequest) {
   });
 }
 
+// Status groups for server-side filtering and count aggregation
+const STATUS_GROUPS: Record<string, string[]> = {
+  active:    ['pending', 'searching', 'downloading', 'processing'],
+  waiting:   ['awaiting_search', 'awaiting_import', 'awaiting_approval'],
+  completed: ['available', 'downloaded'],
+  failed:    ['failed'],
+  cancelled: ['cancelled', 'denied'],
+};
+
 /**
- * GET /api/requests?status=pending&limit=50
- * Get user's audiobook requests (or all requests for admins)
+ * GET /api/requests
+ * Get user's audiobook requests with cursor-based pagination and accurate counts.
+ *
+ * Query params:
+ *   status   - filter group: 'active'|'waiting'|'completed'|'failed'|'cancelled'|specific status
+ *   cursor   - request ID for cursor-based pagination (exclusive start)
+ *   take     - page size (default 20, max 100)
+ *   myOnly   - 'true' to restrict to current user even for admins
+ *   type     - 'audiobook'|'ebook'
+ *
+ * Response: { requests, nextCursor, counts: { all, active, waiting, completed, failed, cancelled } }
  */
 export async function GET(request: NextRequest) {
   return requireAuth(request, async (req: AuthenticatedRequest) => {
@@ -112,61 +131,102 @@ export async function GET(request: NextRequest) {
       }
 
       const searchParams = req.nextUrl.searchParams;
-      const status = searchParams.get('status');
-      const limit = parseInt(searchParams.get('limit') || '50', 10);
+      const statusParam = searchParams.get('status');
+      const cursor = searchParams.get('cursor');
+      const take = Math.min(parseInt(searchParams.get('take') || '20', 10), 100);
+      // Legacy support: honour `limit` if `take` not supplied
+      const limit = searchParams.has('take')
+        ? take
+        : Math.min(parseInt(searchParams.get('limit') || '20', 10), 100);
       const myOnly = searchParams.get('myOnly') === 'true';
-      const type = searchParams.get('type'); // 'audiobook', 'ebook', or null for all
+      const type = searchParams.get('type');
       const isAdmin = req.user.role === 'admin';
 
-      // Build query
-      // If myOnly=true, always filter by current user (even for admins)
-      // Otherwise, admins see all requests, users see only their own
-      const where: any = myOnly || !isAdmin ? { userId: req.user.id } : {};
-      if (status) {
-        where.status = status;
-      }
-      // Filter by type if specified (otherwise returns all types)
-      if (type && ['audiobook', 'ebook'].includes(type)) {
-        where.type = type;
-      }
-      // Only show active (non-deleted) requests
-      where.deletedAt = null;
+      // Base ownership filter
+      const baseWhere: any = myOnly || !isAdmin ? { userId: req.user.id } : {};
+      baseWhere.deletedAt = null;
 
+      if (type && ['audiobook', 'ebook'].includes(type)) {
+        baseWhere.type = type;
+      }
+
+      // Resolve status filter
+      const statusFilter: any = {};
+      if (statusParam) {
+        const group = STATUS_GROUPS[statusParam];
+        if (group) {
+          statusFilter.status = { in: group };
+        } else {
+          // Treat as a specific status literal
+          statusFilter.status = statusParam;
+        }
+      }
+
+      const where = { ...baseWhere, ...statusFilter };
+
+      // ── Paginated request fetch ──────────────────────────────────────────
       const requests = await prisma.request.findMany({
         where,
         include: {
           audiobook: true,
           user: {
-            select: {
-              id: true,
-              plexUsername: true,
-            },
+            select: { id: true, plexUsername: true },
           },
         },
         orderBy: { createdAt: 'desc' },
-        take: limit,
+        take: limit + 1, // fetch one extra to determine if there's a next page
+        ...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
       });
 
-      const enriched = requests.map(r => {
+      const hasNextPage = requests.length > limit;
+      const page = hasNextPage ? requests.slice(0, limit) : requests;
+      const nextCursor = hasNextPage ? page[page.length - 1].id : null;
+
+      const enriched = page.map(r => {
         const isCompleted = COMPLETED_STATUSES.includes(r.status as typeof COMPLETED_STATUSES[number]);
         const downloadAvailable = isCompleted && !!r.audiobook?.filePath;
-        // Strip server-side absolute path from client response
         const audiobook = r.audiobook ? { ...r.audiobook, filePath: undefined } : r.audiobook;
         return { ...r, audiobook, downloadAvailable };
       });
 
+      // ── Accurate counts per group (always scoped to ownership/type filter) ──
+      const countWhere = { ...baseWhere };
+
+      const [
+        totalAll,
+        totalActive,
+        totalWaiting,
+        totalCompleted,
+        totalFailed,
+        totalCancelled,
+      ] = await Promise.all([
+        prisma.request.count({ where: countWhere }),
+        prisma.request.count({ where: { ...countWhere, status: { in: STATUS_GROUPS.active } } }),
+        prisma.request.count({ where: { ...countWhere, status: { in: STATUS_GROUPS.waiting } } }),
+        prisma.request.count({ where: { ...countWhere, status: { in: STATUS_GROUPS.completed } } }),
+        prisma.request.count({ where: { ...countWhere, status: { in: STATUS_GROUPS.failed } } }),
+        prisma.request.count({ where: { ...countWhere, status: { in: STATUS_GROUPS.cancelled } } }),
+      ]);
+
       return NextResponse.json({
         success: true,
         requests: enriched,
+        nextCursor,
+        counts: {
+          all:       totalAll,
+          active:    totalActive,
+          waiting:   totalWaiting,
+          completed: totalCompleted,
+          failed:    totalFailed,
+          cancelled: totalCancelled,
+        },
+        // Legacy field for callers that still read `count`
         count: enriched.length,
       });
     } catch (error) {
       logger.error('Failed to get requests', { error: error instanceof Error ? error.message : String(error) });
       return NextResponse.json(
-        {
-          error: 'FetchError',
-          message: 'Failed to fetch requests',
-        },
+        { error: 'FetchError', message: 'Failed to fetch requests' },
         { status: 500 }
       );
     }

src/app/api/series/[asin]/route.ts

@@ -8,6 +8,9 @@ import { getCurrentUser } from '@/lib/middleware/auth';
 import { RMABLogger } from '@/lib/utils/logger';
 import { scrapeSeriesPage } from '@/lib/integrations/audible-series';
 import { enrichAudiobooksWithMatches } from '@/lib/utils/audiobook-matcher';
+import { deduplicateAndCollectGroups } from '@/lib/utils/deduplicate-audiobooks';
+import { persistDedupGroups } from '@/lib/services/works.service';
+import { annotateWithIgnoreStatus } from '@/lib/utils/ignored-audiobooks';
 
 const logger = RMABLogger.create('API.Series.Detail');
 
@@ -37,9 +40,11 @@ export async function GET(
       );
     }
 
-    logger.info(`Fetching series detail: ${asin}`);
+    const page = parseInt(request.nextUrl.searchParams.get('page') || '1', 10);
 
-    const detail = await scrapeSeriesPage(asin);
+    logger.info(`Fetching series detail: ${asin}, page ${page}`);
+
+    const detail = await scrapeSeriesPage(asin, page);
     if (!detail) {
       return NextResponse.json(
         { error: 'NotFound', message: 'Series not found' },
@@ -47,18 +52,31 @@ export async function GET(
       );
     }
 
+    // Deduplicate before enrichment to avoid wasted DB queries on duplicate entries
+    const { books: dedupedBooks, groups } = deduplicateAndCollectGroups(detail.books);
+
+    // Fire-and-forget: persist dedup groups to works table for cross-ASIN matching
+    if (groups.length > 0) {
+      persistDedupGroups(groups).catch(() => {});
+    }
+
     // Enrich books with library availability and request status
     const userId = currentUser.sub || undefined;
-    const enrichedBooks = await enrichAudiobooksWithMatches(detail.books, userId);
+    const enrichedBooks = await enrichAudiobooksWithMatches(dedupedBooks, userId);
 
-    logger.info(`Series detail complete: "${detail.title}" (${enrichedBooks.length} books)`);
+    // Annotate with per-user ignore status
+    const annotatedBooks = await annotateWithIgnoreStatus(enrichedBooks, userId);
+
+    logger.info(`Series detail complete: "${detail.title}" (${annotatedBooks.length} books, page ${page})`);
 
     return NextResponse.json({
       success: true,
       series: {
         ...detail,
-        books: enrichedBooks,
+        books: annotatedBooks,
       },
+      hasMore: detail.hasMore,
+      page: detail.page,
     });
   } catch (error) {
     logger.error('Failed to fetch series detail', {

src/app/api/setup/complete/route.ts

@@ -140,14 +140,15 @@ export async function POST(request: NextRequest) {
         );
       }
 
+      const normalizedAdminUsername = admin.username.trim().toLowerCase();
       const hashedPassword = await bcrypt.hash(admin.password, 10);
       const encryptionService = getEncryptionService();
       const encryptedPassword = encryptionService.encrypt(hashedPassword);
 
       adminUser = await prisma.user.create({
         data: {
-          plexId: `local-${admin.username}`,
-          plexUsername: admin.username,
+          plexId: `local-${normalizedAdminUsername}`,
+          plexUsername: normalizedAdminUsername,
           plexEmail: null,
           role: 'admin',
           isSetupAdmin: true, // Mark as setup admin - role cannot be changed

src/app/api/user/api-tokens/[id]/route.ts

@@ -0,0 +1,59 @@
+/**
+ * Component: User API Token Delete Route (self-service)
+ * Documentation: documentation/backend/services/api-tokens.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { RMABLogger } from '@/lib/utils/logger';
+import { checkApiTokenRevokeRateLimit } from '@/lib/utils/rateLimit';
+
+const logger = RMABLogger.create('API.User.ApiTokens');
+
+/**
+ * DELETE /api/user/api-tokens/[id]
+ * Revoke (delete) one of the current user's own API tokens
+ */
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      const rateLimit = checkApiTokenRevokeRateLimit(req.user!.id);
+      if (!rateLimit.allowed) {
+        return NextResponse.json(
+          { error: 'Too many API token revoke attempts. Please try again later.' },
+          {
+            status: 429,
+            headers: {
+              'Retry-After': String(rateLimit.retryAfterSeconds),
+            },
+          }
+        );
+      }
+
+      const { id } = await params;
+
+      const token = await prisma.apiToken.findUnique({ where: { id } });
+      if (!token) {
+        return NextResponse.json({ error: 'Token not found' }, { status: 404 });
+      }
+
+      // Only allow deleting own tokens
+      if (token.userId !== req.user!.id) {
+        return NextResponse.json({ error: 'Token not found' }, { status: 404 });
+      }
+
+      await prisma.apiToken.delete({ where: { id } });
+
+      logger.info('User API token revoked', { tokenId: id, name: token.name, userId: req.user!.id });
+
+      return NextResponse.json({ success: true });
+    } catch (error) {
+      logger.error('Failed to revoke user API token', { error: error instanceof Error ? error.message : String(error) });
+      return NextResponse.json({ error: 'Failed to revoke API token' }, { status: 500 });
+    }
+  });
+}

src/app/api/user/api-tokens/route.ts

@@ -0,0 +1,141 @@
+/**
+ * Component: User API Token Routes (self-service)
+ * Documentation: documentation/backend/services/api-tokens.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { RMABLogger } from '@/lib/utils/logger';
+import { checkApiTokenCreateRateLimit } from '@/lib/utils/rateLimit';
+import { MAX_TOKENS_PER_USER } from '@/lib/constants/api-tokens';
+import { generateApiToken } from '@/lib/utils/api-token';
+import { z } from 'zod';
+
+const logger = RMABLogger.create('API.User.ApiTokens');
+
+const CreateTokenSchema = z.object({
+  name: z.string().min(1).max(100),
+  expiresAt: z.string().datetime().nullable().optional(),
+});
+
+/**
+ * GET /api/user/api-tokens
+ * List the current user's own API tokens
+ */
+export async function GET(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      const tokens = await prisma.apiToken.findMany({
+        where: { userId: req.user!.id },
+        orderBy: { createdAt: 'desc' },
+      });
+
+      const sanitized = tokens.map((t) => ({
+        id: t.id,
+        name: t.name,
+        tokenPrefix: t.tokenPrefix,
+        role: t.role,
+        lastUsedAt: t.lastUsedAt,
+        expiresAt: t.expiresAt,
+        createdAt: t.createdAt,
+      }));
+
+      return NextResponse.json({ tokens: sanitized });
+    } catch (error) {
+      logger.error('Failed to list user API tokens', { error: error instanceof Error ? error.message : String(error) });
+      return NextResponse.json({ error: 'Failed to list API tokens' }, { status: 500 });
+    }
+  });
+}
+
+/**
+ * POST /api/user/api-tokens
+ * Create a token for the current user with their own role. Returns full token ONCE.
+ */
+export async function POST(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      const rateLimit = checkApiTokenCreateRateLimit(req.user!.id);
+      if (!rateLimit.allowed) {
+        return NextResponse.json(
+          { error: 'Too many API token create attempts. Please try again later.' },
+          {
+            status: 429,
+            headers: {
+              'Retry-After': String(rateLimit.retryAfterSeconds),
+            },
+          }
+        );
+      }
+
+      const body = await req.json();
+      const { name, expiresAt } = CreateTokenSchema.parse(body);
+
+      // Look up the user's actual role from the database
+      const user = await prisma.user.findUnique({
+        where: { id: req.user!.id },
+        select: { role: true },
+      });
+
+      if (!user) {
+        return NextResponse.json({ error: 'User not found' }, { status: 404 });
+      }
+
+      // Enforce per-user token cap (count only active, non-expired tokens)
+      const activeTokenCount = await prisma.apiToken.count({
+        where: {
+          userId: req.user!.id,
+          OR: [
+            { expiresAt: null },
+            { expiresAt: { gt: new Date() } },
+          ],
+        },
+      });
+
+      if (activeTokenCount >= MAX_TOKENS_PER_USER) {
+        return NextResponse.json(
+          { error: `Token limit reached. Users may have at most ${MAX_TOKENS_PER_USER} active API tokens.` },
+          { status: 403 }
+        );
+      }
+
+      // Generate the token
+      const { fullToken, tokenHash, tokenPrefix } = generateApiToken();
+
+      const apiToken = await prisma.apiToken.create({
+        data: {
+          name,
+          tokenHash,
+          tokenPrefix,
+          role: user.role, // Always the user's own role
+          createdById: req.user!.id,
+          userId: req.user!.id, // Token acts as the current user
+          expiresAt: expiresAt ? new Date(expiresAt) : null,
+        },
+      });
+
+      logger.info('User API token created', { tokenId: apiToken.id, name, userId: req.user!.id });
+
+      return NextResponse.json({
+        token: {
+          id: apiToken.id,
+          name: apiToken.name,
+          tokenPrefix: apiToken.tokenPrefix,
+          role: apiToken.role,
+          expiresAt: apiToken.expiresAt,
+          createdAt: apiToken.createdAt,
+        },
+        fullToken,
+      }, { status: 201 });
+    } catch (error) {
+      logger.error('Failed to create user API token', { error: error instanceof Error ? error.message : String(error) });
+
+      if (error instanceof z.ZodError) {
+        return NextResponse.json({ error: 'Validation error', details: error.errors }, { status: 400 });
+      }
+
+      return NextResponse.json({ error: 'Failed to create API token' }, { status: 500 });
+    }
+  });
+}

src/app/api/user/goodreads-shelves/[id]/route.ts

@@ -7,9 +7,16 @@ import { NextRequest, NextResponse } from 'next/server';
 import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
 import { prisma } from '@/lib/db';
 import { RMABLogger } from '@/lib/utils/logger';
+import { getJobQueueService } from '@/lib/services/job-queue.service';
+import { z } from 'zod';
 
 const logger = RMABLogger.create('API.GoodreadsShelves');
 
+const UpdateGoodreadsSchema = z.object({
+  rssUrl: z.string().url('Must be a valid URL').optional(),
+  autoRequest: z.boolean().optional(),
+});
+
 /**
  * DELETE /api/user/goodreads-shelves/[id]
  * Remove a Goodreads shelf subscription (ownership check)
@@ -48,3 +55,73 @@ export async function DELETE(
     }
   });
 }
+
+/**
+ * PATCH /api/user/goodreads-shelves/[id]
+ * Update a Goodreads shelf subscription
+ */
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      const { id } = await params;
+      const shelf = await prisma.goodreadsShelf.findUnique({ where: { id } });
+
+      if (!shelf) {
+        return NextResponse.json({ error: 'Shelf not found' }, { status: 404 });
+      }
+
+      if (shelf.userId !== req.user.id) {
+        return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+      }
+
+      const body = await request.json();
+      const { rssUrl, autoRequest } = UpdateGoodreadsSchema.parse(body);
+
+      const updateData: Record<string, unknown> = {};
+      let needsResync = false;
+
+      if (rssUrl !== undefined) {
+        updateData.rssUrl = rssUrl;
+        updateData.lastSyncAt = null;
+        updateData.bookCount = null;
+        updateData.coverUrls = null;
+        needsResync = true;
+      }
+
+      if (autoRequest !== undefined) {
+        updateData.autoRequest = autoRequest;
+      }
+
+      const updated = await prisma.goodreadsShelf.update({
+        where: { id },
+        data: updateData,
+      });
+
+      if (needsResync) {
+        try {
+          const jobQueue = getJobQueueService();
+          await jobQueue.addSyncShelvesJob(undefined, updated.id, 'goodreads', 0, req.user.id);
+        } catch (error) {
+          logger.error('Failed to trigger immediate list sync', {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+
+      return NextResponse.json({ success: true, shelf: updated });
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return NextResponse.json({ error: 'ValidationError', details: error.errors }, { status: 400 });
+      }
+      logger.error('Failed to update shelf', { error: error instanceof Error ? error.message : String(error) });
+      return NextResponse.json({ error: 'Failed to update shelf' }, { status: 500 });
+    }
+  });
+}

src/app/api/user/goodreads-shelves/route.ts

@@ -20,6 +20,7 @@ const AddShelfSchema = z.object({
     (url) => GOODREADS_RSS_PATTERN.test(url),
     { message: 'URL must be a Goodreads shelf RSS URL (goodreads.com/review/list_rss/...)' }
   ),
+  autoRequest: z.boolean().optional().default(true),
 });
 
 /**
@@ -66,6 +67,7 @@ export async function GET(request: NextRequest) {
           lastSyncAt: shelf.lastSyncAt,
           createdAt: shelf.createdAt,
           bookCount: shelf.bookCount ?? null,
+          autoRequest: shelf.autoRequest,
           books,
         };
       });
@@ -90,7 +92,7 @@ export async function POST(request: NextRequest) {
       }
 
       const body = await req.json();
-      const { rssUrl } = AddShelfSchema.parse(body);
+      const { rssUrl, autoRequest } = AddShelfSchema.parse(body);
 
       // Check for duplicate
       const existing = await prisma.goodreadsShelf.findUnique({
@@ -132,6 +134,7 @@ export async function POST(request: NextRequest) {
           name: shelfName,
           rssUrl,
           bookCount,
+          autoRequest,
           coverUrls: initialBooks.length > 0 ? JSON.stringify(initialBooks) : null,
         },
       });
@@ -139,8 +142,8 @@ export async function POST(request: NextRequest) {
       // Trigger immediate sync for this shelf (unlimited lookups, process all books)
       try {
         const jobQueue = getJobQueueService();
-        await jobQueue.addSyncGoodreadsShelvesJob(undefined, shelf.id, 0);
-        logger.info(`Triggered immediate sync for shelf "${shelfName}" (${shelf.id})`);
+        await jobQueue.addSyncShelvesJob(undefined, shelf.id, 'goodreads', 0, req.user.id);
+        logger.info(`Triggered immediate sync for Goodreads shelf "${shelfName}" (${shelf.id})`);
       } catch (error) {
         logger.error('Failed to trigger immediate shelf sync', { error: error instanceof Error ? error.message : String(error) });
       }
@@ -154,6 +157,7 @@ export async function POST(request: NextRequest) {
           lastSyncAt: shelf.lastSyncAt,
           createdAt: shelf.createdAt,
           bookCount: shelf.bookCount,
+          autoRequest: shelf.autoRequest,
           books: initialBooks,
         },
         bookCount,

src/app/api/user/hardcover-shelves/[id]/route.ts

@@ -0,0 +1,183 @@
+/**
+ * Component: Hardcover Shelf Delete Route
+ * Documentation: documentation/backend/services/hardcover-sync.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { RMABLogger } from '@/lib/utils/logger';
+import { getJobQueueService } from '@/lib/services/job-queue.service';
+import { getEncryptionService } from '@/lib/services/encryption.service';
+import { fetchHardcoverList } from '@/lib/services/hardcover-api.service';
+import { z } from 'zod';
+
+const logger = RMABLogger.create('API.HardcoverShelves');
+
+const UpdateHardcoverSchema = z.object({
+  listId: z.string().min(1, 'List ID is required').optional(),
+  apiToken: z.string().optional(),
+  forceSync: z.boolean().optional(),
+  autoRequest: z.boolean().optional(),
+});
+
+/**
+ * DELETE /api/user/hardcover-shelves/[id]
+ * Remove a Hardcover shelf subscription (ownership check)
+ */
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      const { id } = await params;
+
+      const shelf = await prisma.hardcoverShelf.findUnique({
+        where: { id },
+      });
+
+      if (!shelf) {
+        return NextResponse.json({ error: 'List not found' }, { status: 404 });
+      }
+
+      // Ownership check
+      if (shelf.userId !== req.user.id) {
+        return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+      }
+
+      await prisma.hardcoverShelf.delete({ where: { id } });
+
+      return NextResponse.json({ success: true });
+    } catch (error) {
+      logger.error('Failed to delete list', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return NextResponse.json(
+        { error: 'Failed to delete list' },
+        { status: 500 },
+      );
+    }
+  });
+}
+
+/**
+ * PATCH /api/user/hardcover-shelves/[id]
+ * Update a Hardcover shelf subscription
+ */
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      const { id } = await params;
+      const shelf = await prisma.hardcoverShelf.findUnique({ where: { id } });
+
+      if (!shelf) {
+        return NextResponse.json({ error: 'List not found' }, { status: 404 });
+      }
+
+      if (shelf.userId !== req.user.id) {
+        return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+      }
+
+      const body = await request.json();
+      const { listId, apiToken, forceSync, autoRequest } = UpdateHardcoverSchema.parse(body);
+
+      const updateData: { listId?: string; apiToken?: string; autoRequest?: boolean; lastSyncAt?: null; bookCount?: null; coverUrls?: null } = {};
+
+      if (autoRequest !== undefined) {
+        updateData.autoRequest = autoRequest;
+      }
+      let needsResync = !!forceSync;
+
+      let cleanedToken: string | undefined;
+      if (apiToken && apiToken.trim() !== '') {
+        cleanedToken = apiToken.trim().toLowerCase().startsWith('bearer ')
+          ? apiToken.trim().slice(7).trim()
+          : apiToken.trim();
+      }
+
+      const newListId = (listId && listId !== shelf.listId) ? listId : undefined;
+
+      // Validate token/listId by fetching the list before saving
+      if (cleanedToken || newListId) {
+        const encryptionService = getEncryptionService();
+        let tokenToTest = cleanedToken || shelf.apiToken;
+        if (!cleanedToken) {
+          try {
+            if (encryptionService.isEncryptedFormat(shelf.apiToken)) {
+              tokenToTest = encryptionService.decrypt(shelf.apiToken);
+            }
+          } catch {
+            // Decryption failed, fall back to raw token
+          }
+        }
+        const listIdToTest = newListId || shelf.listId;
+
+        try {
+          await fetchHardcoverList(tokenToTest, listIdToTest);
+        } catch (error) {
+          return NextResponse.json(
+            {
+              error: 'InvalidHardcoverList',
+              message: `Could not fetch the Hardcover list. Check your Token and List ID: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            },
+            { status: 400 },
+          );
+        }
+
+        if (newListId) {
+          updateData.listId = newListId;
+          needsResync = true;
+        }
+        if (cleanedToken) {
+          updateData.apiToken = encryptionService.encrypt(cleanedToken);
+          needsResync = true;
+        }
+      }
+
+      // If we are forcing a resync due to a change, clear metadata
+      if (needsResync) {
+        updateData.lastSyncAt = null;
+        updateData.bookCount = null;
+        updateData.coverUrls = null;
+      }
+
+      const updated = await prisma.hardcoverShelf.update({
+        where: { id },
+        data: updateData,
+      });
+
+      if (needsResync) {
+        try {
+          const jobQueue = getJobQueueService();
+          await jobQueue.addSyncShelvesJob(undefined, updated.id, 'hardcover', 0, req.user.id);
+        } catch (error) {
+          logger.error('Failed to trigger immediate list sync', {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+
+      return NextResponse.json({ success: true, shelf: updated });
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return NextResponse.json({ error: 'ValidationError', details: error.errors }, { status: 400 });
+      }
+      logger.error('Failed to update list', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return NextResponse.json({ error: 'Failed to update list' }, { status: 500 });
+    }
+  });
+}

src/app/api/user/hardcover-shelves/route.ts

@@ -0,0 +1,201 @@
+/**
+ * Component: Hardcover Shelves API Routes
+ * Documentation: documentation/backend/services/hardcover-sync.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { fetchHardcoverList } from '@/lib/services/hardcover-api.service';
+import { getJobQueueService } from '@/lib/services/job-queue.service';
+import { getEncryptionService } from '@/lib/services/encryption.service';
+import { z } from 'zod';
+import { RMABLogger } from '@/lib/utils/logger';
+import { processBooks } from '@/lib/utils/shelf-helpers';
+
+const logger = RMABLogger.create('API.HardcoverShelves');
+
+const AddShelfSchema = z.object({
+  listId: z.string().min(1, { message: 'List ID is required' }),
+  apiToken: z.string().min(1, { message: 'API Token is required' }),
+  autoRequest: z.boolean().optional().default(true),
+});
+
+/**
+ * GET /api/user/hardcover-shelves
+ * List the current user's Hardcover lists with book counts and covers
+ */
+export async function GET(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      const shelves = await prisma.hardcoverShelf.findMany({
+        where: { userId: req.user.id },
+        orderBy: { createdAt: 'desc' },
+      });
+
+      const shelvesWithMeta = shelves.map((shelf) => {
+        const books = processBooks(shelf.coverUrls);
+
+        return {
+          id: shelf.id,
+          name: shelf.name,
+          listId: shelf.listId,
+          lastSyncAt: shelf.lastSyncAt,
+          createdAt: shelf.createdAt,
+          bookCount: shelf.bookCount ?? null,
+          autoRequest: shelf.autoRequest,
+          books,
+        };
+      });
+
+      return NextResponse.json({ success: true, shelves: shelvesWithMeta });
+    } catch (error) {
+      logger.error('Failed to list Hardcover lists', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return NextResponse.json(
+        { error: 'Failed to list Hardcover lists' },
+        { status: 500 },
+      );
+    }
+  });
+}
+
+/**
+ * POST /api/user/hardcover-shelves
+ * Add a new Hardcover list subscription
+ */
+export async function POST(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      const body = await req.json();
+      const parsed = AddShelfSchema.parse(body);
+      let { listId, apiToken } = parsed;
+      const { autoRequest } = parsed;
+
+      // Clean up token in case user pasted "Bearer " prefix
+      apiToken = apiToken.trim();
+      if (apiToken.toLowerCase().startsWith('bearer ')) {
+        apiToken = apiToken.slice(7).trim();
+      }
+
+      // Check for duplicate
+      const existing = await prisma.hardcoverShelf.findUnique({
+        where: { userId_listId: { userId: req.user.id, listId } },
+      });
+
+      if (existing) {
+        return NextResponse.json(
+          {
+            error: 'DuplicateShelf',
+            message: 'You have already added this list',
+          },
+          { status: 409 },
+        );
+      }
+
+      // Validate by fetching the Hardcover GraphQL feed
+      let listName: string;
+      let bookCount: number;
+      let initialBooks: {
+        coverUrl: string;
+        asin: null;
+        title: string;
+        author: string;
+      }[] = [];
+      try {
+        const fetchedData = await fetchHardcoverList(apiToken, listId);
+        listName = fetchedData.listName;
+        bookCount = fetchedData.books.length;
+        initialBooks = fetchedData.books
+          .filter((b) => b.coverUrl)
+          .slice(0, 8)
+          .map((b) => ({
+            coverUrl: b.coverUrl!,
+            asin: null,
+            title: b.title,
+            author: b.author,
+          }));
+      } catch (error) {
+        return NextResponse.json(
+          {
+            error: 'InvalidHardcoverList',
+            message: `Could not fetch the Hardcover list. Check your Token and List ID: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          },
+          { status: 400 },
+        );
+      }
+
+      const encryptionService = getEncryptionService();
+      const encryptedToken = encryptionService.encrypt(apiToken);
+
+      const shelf = await prisma.hardcoverShelf.create({
+        data: {
+          userId: req.user.id,
+          name: listName,
+          listId,
+          apiToken: encryptedToken,
+          autoRequest,
+          bookCount,
+          coverUrls:
+            initialBooks.length > 0 ? JSON.stringify(initialBooks) : null,
+        },
+      });
+
+      // Trigger immediate sync for this shelf (unlimited lookups, process all books)
+      try {
+        const jobQueue = getJobQueueService();
+        await jobQueue.addSyncShelvesJob(undefined, shelf.id, 'hardcover', 0, req.user.id);
+        logger.info(
+          `Triggered immediate sync for Hardcover list "${listName}" (${shelf.id})`,
+        );
+      } catch (error) {
+        logger.error('Failed to trigger immediate list sync', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+
+      return NextResponse.json(
+        {
+          success: true,
+          shelf: {
+            id: shelf.id,
+            name: shelf.name,
+            listId: shelf.listId,
+            lastSyncAt: shelf.lastSyncAt,
+            createdAt: shelf.createdAt,
+            bookCount: shelf.bookCount,
+            autoRequest: shelf.autoRequest,
+            books: initialBooks,
+          },
+          bookCount,
+        },
+        { status: 201 },
+      );
+    } catch (error) {
+      logger.error('Failed to add Hardcover list', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      if (error instanceof z.ZodError) {
+        return NextResponse.json(
+          { error: 'ValidationError', details: error.errors },
+          { status: 400 },
+        );
+      }
+
+      return NextResponse.json(
+        { error: 'Failed to add Hardcover list' },
+        { status: 500 },
+      );
+    }
+  });
+}

src/app/api/user/home-sections/route.ts

@@ -0,0 +1,202 @@
+/**
+ * Component: User Home Sections API Route
+ * Documentation: documentation/features/home-sections.md
+ *
+ * Per-user configurable home page sections.
+ * GET returns sections + next refresh time.
+ * PUT saves full section config (delete-and-recreate in transaction).
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { z } from 'zod';
+import { RMABLogger } from '@/lib/utils/logger';
+
+const logger = RMABLogger.create('API.User.HomeSections');
+
+const MAX_SECTIONS = 10;
+
+const VALID_SECTION_TYPES = ['popular', 'new_releases', 'category'] as const;
+
+const SectionSchema = z.object({
+  sectionType: z.enum(VALID_SECTION_TYPES),
+  categoryId: z.string().optional().nullable(),
+  categoryName: z.string().optional().nullable(),
+  sortOrder: z.number().int().min(0),
+});
+
+const PutBodySchema = z.object({
+  sections: z.array(SectionSchema).max(MAX_SECTIONS),
+});
+
+/**
+ * Create default home sections for a new user (Popular + New Releases).
+ */
+async function ensureDefaultSections(userId: string) {
+  const existing = await prisma.userHomeSection.findMany({
+    where: { userId },
+    select: { id: true },
+    take: 1,
+  });
+
+  if (existing.length > 0) return;
+
+  await prisma.userHomeSection.createMany({
+    data: [
+      { userId, sectionType: 'popular', sortOrder: 0 },
+      { userId, sectionType: 'new_releases', sortOrder: 1 },
+    ],
+  });
+}
+
+/**
+ * GET /api/user/home-sections
+ * Returns the user's configured home sections + next scheduled refresh time.
+ */
+export async function GET(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      await ensureDefaultSections(req.user.id);
+
+      const sections = await prisma.userHomeSection.findMany({
+        where: { userId: req.user.id },
+        orderBy: { sortOrder: 'asc' },
+      });
+
+      // Get next refresh time from scheduled jobs
+      let nextRefresh: string | null = null;
+      try {
+        const scheduledJob = await prisma.scheduledJob.findFirst({
+          where: { type: 'audible_refresh', enabled: true },
+          select: { nextRun: true },
+        });
+        nextRefresh = scheduledJob?.nextRun?.toISOString() || null;
+      } catch {
+        // Non-critical — just omit nextRefresh
+      }
+
+      return NextResponse.json({
+        success: true,
+        sections: sections.map((s) => ({
+          id: s.id,
+          sectionType: s.sectionType,
+          categoryId: s.categoryId,
+          categoryName: s.categoryName,
+          sortOrder: s.sortOrder,
+        })),
+        nextRefresh,
+      });
+    } catch (error) {
+      logger.error('Failed to get home sections', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return NextResponse.json(
+        { error: 'FetchError', message: 'Failed to fetch home sections' },
+        { status: 500 }
+      );
+    }
+  });
+}
+
+/**
+ * PUT /api/user/home-sections
+ * Replaces all home sections for the user (delete-and-recreate in transaction).
+ * Validates: max 10 sections, no duplicate sections, category sections need categoryId.
+ */
+export async function PUT(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      const body = await req.json();
+      const { sections } = PutBodySchema.parse(body);
+
+      // Validate category sections have categoryId
+      for (const section of sections) {
+        if (section.sectionType === 'category' && !section.categoryId) {
+          return NextResponse.json(
+            { error: 'ValidationError', message: 'Category sections require a categoryId' },
+            { status: 400 }
+          );
+        }
+      }
+
+      // Check for duplicate section types (only one popular, one new_releases, unique categories)
+      const seen = new Set<string>();
+      for (const section of sections) {
+        const key =
+          section.sectionType === 'category'
+            ? `category:${section.categoryId}`
+            : section.sectionType;
+        if (seen.has(key)) {
+          return NextResponse.json(
+            { error: 'ValidationError', message: `Duplicate section: ${key}` },
+            { status: 400 }
+          );
+        }
+        seen.add(key);
+      }
+
+      const userId = req.user.id;
+
+      // Delete-and-recreate in a transaction
+      await prisma.$transaction(async (tx) => {
+        await tx.userHomeSection.deleteMany({ where: { userId } });
+
+        if (sections.length > 0) {
+          await tx.userHomeSection.createMany({
+            data: sections.map((s, idx) => ({
+              userId,
+              sectionType: s.sectionType,
+              categoryId: s.sectionType === 'category' ? s.categoryId : null,
+              categoryName: s.sectionType === 'category' ? s.categoryName : null,
+              sortOrder: idx,
+            })),
+          });
+        }
+      });
+
+      // Return the saved sections
+      const saved = await prisma.userHomeSection.findMany({
+        where: { userId },
+        orderBy: { sortOrder: 'asc' },
+      });
+
+      logger.info(`User ${userId} updated home sections (${saved.length} sections)`);
+
+      return NextResponse.json({
+        success: true,
+        sections: saved.map((s) => ({
+          id: s.id,
+          sectionType: s.sectionType,
+          categoryId: s.categoryId,
+          categoryName: s.categoryName,
+          sortOrder: s.sortOrder,
+        })),
+      });
+    } catch (error) {
+      logger.error('Failed to save home sections', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      if (error instanceof z.ZodError) {
+        return NextResponse.json(
+          { error: 'ValidationError', details: error.errors },
+          { status: 400 }
+        );
+      }
+
+      return NextResponse.json(
+        { error: 'SaveError', message: 'Failed to save home sections' },
+        { status: 500 }
+      );
+    }
+  });
+}

src/app/api/user/ignored-audiobooks/[id]/route.ts

@@ -0,0 +1,65 @@
+/**
+ * Component: Ignored Audiobook Delete Route
+ * Documentation: documentation/features/ignored-audiobooks.md
+ *
+ * DELETE removes a single entry from the user's ignore list (un-ignore).
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { RMABLogger } from '@/lib/utils/logger';
+
+const logger = RMABLogger.create('API.IgnoredAudiobooks');
+
+/**
+ * DELETE /api/user/ignored-audiobooks/[id]
+ * Remove an audiobook from the user's ignore list
+ */
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      const { id } = await params;
+
+      // Verify ownership before deleting
+      const existing = await prisma.ignoredAudiobook.findUnique({
+        where: { id },
+      });
+
+      if (!existing) {
+        return NextResponse.json(
+          { error: 'NotFound', message: 'Ignored audiobook entry not found' },
+          { status: 404 }
+        );
+      }
+
+      if (existing.userId !== req.user.id) {
+        return NextResponse.json(
+          { error: 'Forbidden', message: 'Cannot modify another user\'s ignore list' },
+          { status: 403 }
+        );
+      }
+
+      await prisma.ignoredAudiobook.delete({ where: { id } });
+
+      logger.info(`User ${req.user.id} un-ignored ASIN ${existing.asin} ("${existing.title}")`);
+
+      return NextResponse.json({ success: true });
+    } catch (error) {
+      logger.error('Failed to remove ignored audiobook', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return NextResponse.json(
+        { error: 'DeleteError', message: 'Failed to remove ignored audiobook' },
+        { status: 500 }
+      );
+    }
+  });
+}

src/app/api/user/ignored-audiobooks/check/[asin]/route.ts

@@ -0,0 +1,79 @@
+/**
+ * Component: Ignored Audiobook Check Route
+ * Documentation: documentation/features/ignored-audiobooks.md
+ *
+ * Quick check whether a specific ASIN is ignored by the current user.
+ * Includes works-system expansion to catch sibling ASINs.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { getSiblingAsins } from '@/lib/services/works.service';
+import { RMABLogger } from '@/lib/utils/logger';
+
+const logger = RMABLogger.create('API.IgnoredAudiobooks.Check');
+
+/**
+ * GET /api/user/ignored-audiobooks/check/[asin]
+ * Returns { ignored: boolean, ignoredId?: string } for the given ASIN.
+ * ignoredId is the ID of the matching IgnoredAudiobook record (for un-ignore).
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ asin: string }> }
+) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      const { asin } = await params;
+
+      // Direct check
+      const directIgnore = await prisma.ignoredAudiobook.findUnique({
+        where: { userId_asin: { userId: req.user.id, asin } },
+      });
+
+      if (directIgnore) {
+        return NextResponse.json({
+          ignored: true,
+          ignoredId: directIgnore.id,
+        });
+      }
+
+      // Works-system expansion: check sibling ASINs
+      try {
+        const siblingMap = await getSiblingAsins([asin]);
+        const siblings = siblingMap.get(asin);
+        if (siblings && siblings.length > 0) {
+          const siblingIgnore = await prisma.ignoredAudiobook.findFirst({
+            where: {
+              userId: req.user.id,
+              asin: { in: siblings },
+            },
+          });
+          if (siblingIgnore) {
+            return NextResponse.json({
+              ignored: true,
+              ignoredId: siblingIgnore.id,
+            });
+          }
+        }
+      } catch {
+        // Works expansion is best-effort
+      }
+
+      return NextResponse.json({ ignored: false });
+    } catch (error) {
+      logger.error('Failed to check ignored status', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return NextResponse.json(
+        { error: 'CheckError', message: 'Failed to check ignored status' },
+        { status: 500 }
+      );
+    }
+  });
+}

src/app/api/user/ignored-audiobooks/route.ts

@@ -0,0 +1,123 @@
+/**
+ * Component: Ignored Audiobooks API Routes
+ * Documentation: documentation/features/ignored-audiobooks.md
+ *
+ * Per-user ignore list for auto-request suppression.
+ * GET returns the user's full ignore list; POST adds a new entry.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { z } from 'zod';
+import { RMABLogger } from '@/lib/utils/logger';
+
+const logger = RMABLogger.create('API.IgnoredAudiobooks');
+
+const AddIgnoredSchema = z.object({
+  asin: z.string().min(1).max(20),
+  title: z.string().min(1).max(500),
+  author: z.string().min(1).max(500),
+  coverArtUrl: z.string().optional(),
+});
+
+/**
+ * GET /api/user/ignored-audiobooks
+ * List the current user's ignored audiobooks
+ */
+export async function GET(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      const ignored = await prisma.ignoredAudiobook.findMany({
+        where: { userId: req.user.id },
+        orderBy: { createdAt: 'desc' },
+      });
+
+      return NextResponse.json({
+        success: true,
+        ignoredAudiobooks: ignored.map((item) => ({
+          id: item.id,
+          asin: item.asin,
+          title: item.title,
+          author: item.author,
+          coverArtUrl: item.coverArtUrl,
+          createdAt: item.createdAt.toISOString(),
+        })),
+      });
+    } catch (error) {
+      logger.error('Failed to list ignored audiobooks', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return NextResponse.json(
+        { error: 'FetchError', message: 'Failed to fetch ignored audiobooks' },
+        { status: 500 }
+      );
+    }
+  });
+}
+
+/**
+ * POST /api/user/ignored-audiobooks
+ * Add an audiobook to the user's ignore list
+ */
+export async function POST(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      const body = await req.json();
+      const data = AddIgnoredSchema.parse(body);
+
+      // Upsert to handle duplicate gracefully
+      const ignored = await prisma.ignoredAudiobook.upsert({
+        where: {
+          userId_asin: { userId: req.user.id, asin: data.asin },
+        },
+        update: {}, // Already exists — no-op
+        create: {
+          userId: req.user.id,
+          asin: data.asin,
+          title: data.title,
+          author: data.author,
+          coverArtUrl: data.coverArtUrl,
+        },
+      });
+
+      logger.info(`User ${req.user.id} ignored ASIN ${data.asin} ("${data.title}")`);
+
+      return NextResponse.json({
+        success: true,
+        ignoredAudiobook: {
+          id: ignored.id,
+          asin: ignored.asin,
+          title: ignored.title,
+          author: ignored.author,
+          coverArtUrl: ignored.coverArtUrl,
+          createdAt: ignored.createdAt.toISOString(),
+        },
+      }, { status: 201 });
+    } catch (error) {
+      logger.error('Failed to add ignored audiobook', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      if (error instanceof z.ZodError) {
+        return NextResponse.json(
+          { error: 'ValidationError', details: error.errors },
+          { status: 400 }
+        );
+      }
+
+      return NextResponse.json(
+        { error: 'CreateError', message: 'Failed to ignore audiobook' },
+        { status: 500 }
+      );
+    }
+  });
+}

src/app/api/user/shelves/route.ts

@@ -0,0 +1,75 @@
+/**
+ * Component: Combined Shelves API Routes
+ * Documentation: documentation/backend/services/goodreads-sync.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { RMABLogger } from '@/lib/utils/logger';
+import { processBooks } from '@/lib/utils/shelf-helpers';
+
+const logger = RMABLogger.create('API.Shelves');
+
+/**
+ * GET /api/user/shelves
+ * List the current user's shelves (Goodreads, Hardcover) with book counts and covers
+ */
+export async function GET(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      const [goodreads, hardcover] = await Promise.all([
+        prisma.goodreadsShelf.findMany({
+          where: { userId: req.user.id },
+          orderBy: { createdAt: 'desc' },
+        }),
+        prisma.hardcoverShelf.findMany({
+          where: { userId: req.user.id },
+          orderBy: { createdAt: 'desc' },
+        }),
+      ]);
+
+      const combined = [
+        ...goodreads.map((s) => ({
+          id: s.id,
+          type: 'goodreads',
+          name: s.name,
+          sourceId: s.rssUrl,
+          lastSyncAt: s.lastSyncAt,
+          createdAt: s.createdAt,
+          bookCount: s.bookCount ?? null,
+          autoRequest: s.autoRequest,
+          books: processBooks(s.coverUrls),
+        })),
+        ...hardcover.map((s) => ({
+          id: s.id,
+          type: 'hardcover',
+          name: s.name,
+          sourceId: s.listId,
+          lastSyncAt: s.lastSyncAt,
+          createdAt: s.createdAt,
+          bookCount: s.bookCount ?? null,
+          autoRequest: s.autoRequest,
+          books: processBooks(s.coverUrls),
+        })),
+      ].sort(
+        (a, b) =>
+          new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
+      );
+
+      return NextResponse.json({ success: true, shelves: combined });
+    } catch (error) {
+      logger.error('Failed to list shelves', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return NextResponse.json(
+        { error: 'Failed to list shelves' },
+        { status: 500 },
+      );
+    }
+  });
+}

src/app/api/user/shelves/sync/route.ts

@@ -0,0 +1,79 @@
+/**
+ * Component: Manual Shelf Sync API Route
+ * Documentation: documentation/backend/services/goodreads-sync.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { getJobQueueService } from '@/lib/services/job-queue.service';
+import { RMABLogger } from '@/lib/utils/logger';
+import { z } from 'zod';
+
+const logger = RMABLogger.create('API.ShelvesSync');
+
+const SyncSchema = z.object({
+  shelfId: z.string().optional(),
+  shelfType: z.enum(['goodreads', 'hardcover']).optional(),
+});
+
+/**
+ * POST /api/user/shelves/sync
+ * Trigger a manual sync for all or a specific shelf belonging to the user.
+ */
+export async function POST(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+
+      const body = await request.json().catch(() => ({}));
+      const { shelfId, shelfType } = SyncSchema.parse(body);
+
+      // Set lastSyncAt to null so the frontend SWR refresh catches the "Syncing..." state immediately
+      if (!shelfType || shelfType === 'goodreads') {
+        await prisma.goodreadsShelf.updateMany({
+          where: { userId: req.user.id, ...(shelfId ? { id: shelfId } : {}) },
+          data: { lastSyncAt: null },
+        });
+      }
+
+      if (!shelfType || shelfType === 'hardcover') {
+        await prisma.hardcoverShelf.updateMany({
+          where: { userId: req.user.id, ...(shelfId ? { id: shelfId } : {}) },
+          data: { lastSyncAt: null },
+        });
+      }
+
+      const jobQueue = getJobQueueService();
+
+      // Trigger sync job with userId filter
+      await jobQueue.addSyncShelvesJob(
+        undefined,
+        shelfId,
+        shelfType,
+        0, // unlimited lookups for manual trigger
+        req.user.id
+      );
+
+      logger.info(`Manual sync triggered for user ${req.user.id}${shelfId ? ` (shelf: ${shelfId})` : ' (all shelves)'}`);
+
+      return NextResponse.json({
+        success: true,
+        message: shelfId ? 'Shelf sync triggered' : 'All shelves sync triggered'
+      });
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return NextResponse.json({ error: 'ValidationError', details: error.errors }, { status: 400 });
+      }
+      logger.error('Failed to trigger manual sync', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return NextResponse.json(
+        { error: 'Failed to trigger manual sync' },
+        { status: 500 },
+      );
+    }
+  });
+}