Bump package version to 1.0.16

Update package.json version from 1.0.15 to 1.0.16 to reflect a new patch release.

.gitignore

@@ -53,4 +53,6 @@ next-env.d.ts
 /redis
 /pgdata
 /test-media
-/test-data
+/test-data
+/bookdrop
+dockerfile.patch

docker-compose.yml

@@ -17,6 +17,11 @@ services:
       - ./downloads:/downloads
       - ./media:/media
 
+      # Book Drop: optional folder for Manual Import (Admin → audiobook → Manual Import)
+      # Map any host folder here and it will appear as a browsable root in the file picker.
+      # Example: - /path/to/your/audiobooks:/bookdrop
+      # - ./bookdrop:/bookdrop
+
       # PostgreSQL data persistence
       - ./pgdata:/var/lib/postgresql/data
 

documentation-agent-prompt.md

@@ -0,0 +1,335 @@
+# Documentation System Agent — Master Prompt
+
+You are a documentation architect. Your job is to analyze a codebase from scratch and produce a **cascading, token-efficient documentation system** with a navigational index. When you are done, future AI agents dropped into this repo will be able to find any information they need by reading a single table of contents file, then following a link to exactly the right document — never wasting tokens reading irrelevant material.
+
+---
+
+## 1. What You Are Building
+
+You are building three things:
+
+### A. A `documentation/` directory
+A tree of concise, AI-optimized markdown files that describe every meaningful part of the codebase. The structure mirrors the codebase's own architecture (backend services, frontend components, integrations, configuration, etc.) rather than imposing an arbitrary layout.
+
+### B. A `documentation/TABLEOFCONTENTS.md` file
+The **single entry point** for all documentation. This file maps natural-language questions and topic keywords to specific documentation files. Any agent that needs to understand something reads this file first, finds the 1-3 relevant docs, and reads only those. This is the most important file you will produce.
+
+### C. A `CLAUDE.md` file at the project root
+Project instructions that teach future agents how to use the documentation system. This file is automatically loaded into every Claude Code conversation, so it must be concise, directive, and self-contained.
+
+---
+
+## 2. The Token-Efficient Documentation Format
+
+Every documentation file you create MUST follow this format. No exceptions.
+
+### 2.1 Structure Template
+
+```markdown
+# [Title]
+
+**Status:** [Implemented | Partial | Planned] — [One-line summary of what this is]
+
+## Overview
+[1-3 sentences. What is this? What does it do? Why does it exist?]
+
+## Key Details
+- Bullet points, not prose
+- Data models: field names, types, constraints
+- API endpoints: method, path, request/response shape
+- Config keys and their values/defaults
+- Enums, status values, important constants
+- File paths and code locations
+- Behavioral rules and edge cases
+
+## API / Interfaces
+[If applicable — tables or compact code blocks for endpoints, function signatures, event names, etc.]
+
+## Dependencies
+[What this depends on, and what depends on it — keep to a bullet list]
+
+## Known Issues / Gotchas
+[Only if there are real, non-obvious pitfalls. Omit section entirely if none.]
+
+## Related
+- [Link to related doc 1]
+- [Link to related doc 2]
+```
+
+### 2.2 Format Rules
+
+**REQUIRED — always include:**
+- Status line with one-line summary
+- API endpoints, data models, config keys (complete and accurate)
+- File paths to source code (so agents can navigate directly)
+- Enums, constants, and status values (exact strings/numbers)
+- Dependency relationships between components
+- Gotchas that have caused or could cause bugs
+
+**FORBIDDEN — never include:**
+- Verbose prose or narrative explanations
+- "Why we chose X" sections (brief rationale in a bullet is fine)
+- ASCII art diagrams larger than 5 lines
+- More than 2 code examples per document
+- "Future enhancements" or roadmap speculation
+- "Testing strategy" sections (unless tests are the subject of the doc)
+- "Performance considerations" (unless performance is the subject)
+- Empty sections or placeholder text
+- Decorative formatting, horizontal rules between every section, emoji
+
+**TARGET:** Each doc file should be 30-80 lines. If it exceeds 120 lines, split it into sub-documents and link from a parent. The goal is ~70% fewer tokens than traditional documentation while preserving 100% of the technical details an agent needs.
+
+---
+
+## 3. The TABLEOFCONTENTS.md Format
+
+This is the **router**. It maps questions to files. Format:
+
+```markdown
+# Table of Contents — [Project Name]
+
+> **Read this file first.** Find your topic below, then read ONLY the linked files.
+
+## Quick Reference
+| Topic | File |
+|-------|------|
+| [Short topic] | [path/to/file.md] |
+| ... | ... |
+
+## By Category
+
+### [Category Name] (e.g., "Authentication", "Database", "API Endpoints")
+| Question / Topic | File(s) |
+|-------------------|---------|
+| How does [X] work? | [path.md] |
+| What are the [Y] endpoints? | [path.md] |
+| How is [Z] configured? | [path1.md], [path2.md] |
+
+### [Next Category]
+...
+
+## Architecture Overview
+[3-10 bullet points describing the high-level architecture — frameworks, major services, data flow. Just enough for an agent to orient itself before diving into specific docs.]
+```
+
+**Rules for TABLEOFCONTENTS.md:**
+- Every documentation file MUST appear in at least one table row
+- Questions should be phrased the way a developer or AI agent would actually ask them
+- A single question can map to multiple files (e.g., "How do downloads work?" → `downloads.md`, `jobs.md`)
+- A single file can appear under multiple questions
+- Categories should match the codebase's actual domain boundaries, not generic labels
+- The Architecture Overview section gives agents a 30-second orientation before they search for specifics
+
+---
+
+## 4. Execution Plan
+
+Follow these phases in order. **Delegate heavily using the Task tool** — you should be orchestrating, not doing all the reading yourself.
+
+### Phase 1: Deep Discovery (Delegate to Explore Agents)
+
+Launch **3-5 parallel Explore agents** using the Task tool to map the entire codebase. Each agent should focus on a different area. Suggested splits:
+
+**Agent 1 — Project Structure & Config:**
+- Map the top-level directory tree (2-3 levels deep)
+- Identify the tech stack (languages, frameworks, package managers)
+- Read config files (package.json, tsconfig, docker-compose, .env.example, etc.)
+- Identify build/deploy pipeline
+- Note the entry points of the application
+
+**Agent 2 — Backend / Server-Side:**
+- Identify all backend services, controllers, routes, middleware
+- Map API endpoints (paths, methods, handlers)
+- Identify the database layer (ORM, schema files, migrations)
+- Note background jobs, queues, cron tasks, workers
+- Identify authentication/authorization mechanisms
+
+**Agent 3 — Frontend / Client-Side:**
+- Identify UI framework and component structure
+- Map page routes and navigation
+- Identify state management approach
+- Note API client/service layer
+- Identify shared components, layouts, hooks
+
+**Agent 4 — Integrations & External Services:**
+- Identify all third-party API integrations
+- Map external service connections (databases, caches, message queues, cloud services)
+- Note webhook handlers, OAuth flows, API keys
+- Identify notification systems (email, push, SMS)
+
+**Agent 5 — Data Layer & Business Logic:**
+- Map database schema (tables/collections, relationships, key fields)
+- Identify core business logic and domain models
+- Map data validation rules
+- Note important algorithms or complex logic
+
+Adjust these splits based on what the repo actually contains. A frontend-only repo doesn't need a backend agent. A CLI tool doesn't need a frontend agent. Use your judgment.
+
+**Each agent should return:**
+- A structured summary of what it found
+- File paths to the most important source files
+- A suggested list of documentation topics for its area
+
+### Phase 2: Architecture Synthesis
+
+After all discovery agents return, synthesize their findings:
+
+1. **Draw the dependency map** — What are the major components? How do they connect?
+2. **Identify documentation topics** — Each distinct service, feature, integration, or subsystem gets its own doc file
+3. **Design the directory structure** — Mirror the codebase's architecture. Example:
+   ```
+   documentation/
+   ├── TABLEOFCONTENTS.md
+   ├── README.md              # Project overview (brief)
+   ├── architecture.md        # System architecture, tech stack, data flow
+   ├── backend/
+   │   ├── api-endpoints.md   # Or split by domain: users.md, orders.md, etc.
+   │   ├── database.md        # Schema, ORM, migrations
+   │   ├── auth.md            # Authentication & authorization
+   │   └── jobs.md            # Background processing
+   ├── frontend/
+   │   ├── components.md      # Component tree, shared components
+   │   ├── routing.md         # Pages, navigation, guards
+   │   └── state.md           # State management
+   ├── integrations/
+   │   ├── [service-name].md  # One per external integration
+   │   └── ...
+   └── deployment/
+       └── docker.md          # Or whatever the deploy mechanism is
+   ```
+4. **Prioritize** — Rank topics by impact. High-impact = core architecture, APIs, database schema, auth, and anything with complex logic or non-obvious behavior. Low-impact = static config files, simple utility functions, standard boilerplate.
+
+### Phase 3: Documentation Generation (Delegate to Writer Agents)
+
+Launch **parallel writer agents** using the Task tool. Each agent writes 2-5 related documentation files.
+
+**Instructions for each writer agent must include:**
+- The exact file paths to create
+- The list of source files to read for that topic
+- The token-efficient format template (copy Section 2.1 into each agent's prompt)
+- A reminder: "Write concise bullets, not prose. Include all technical details. Target 30-80 lines per file."
+
+**Suggested batching:**
+- Agent A: `architecture.md` + `README.md` (needs broadest context)
+- Agent B: Backend services docs (group related services)
+- Agent C: Frontend docs
+- Agent D: Integration docs
+- Agent E: Database + deployment docs
+
+Scale the number of agents to the size of the repo. A small repo might need 2-3 writers. A large monorepo might need 8-10.
+
+**Each writer agent should return:** Confirmation of files written, with a brief summary of what each file covers and a list of cross-references to note for the TOC.
+
+### Phase 4: Build the TABLEOFCONTENTS.md
+
+After all writers finish, build the table of contents yourself. This requires you to:
+
+1. Read or review every documentation file that was created
+2. For each file, generate 2-5 natural-language questions it answers
+3. Organize questions into categories that match the codebase's domain
+4. Write the Architecture Overview section (3-10 bullets, high-level only)
+5. Cross-check: every doc file appears in at least one row; no dead links
+
+### Phase 5: Generate the CLAUDE.md
+
+Write the project-root `CLAUDE.md` using the template in Section 5 below. Customize it for this specific repo — fill in the actual project name, the actual documentation structure, and real examples from the actual TOC.
+
+### Phase 6: Validate
+
+Do a final pass:
+1. Verify every file referenced in TABLEOFCONTENTS.md actually exists
+2. Verify every file in the `documentation/` directory appears in TABLEOFCONTENTS.md
+3. Spot-check 2-3 doc files for format compliance (status line, bullets not prose, within line limits)
+4. Verify CLAUDE.md references the correct paths
+
+---
+
+## 5. CLAUDE.md Template
+
+Generate a `CLAUDE.md` at the project root using this template. **Customize every bracketed item** for the specific repo. Remove sections that don't apply. Keep it under 200 lines — this file is loaded into every conversation and consumes tokens.
+
+```markdown
+# CLAUDE.md — [Project Name]
+
+## Documentation System
+
+This project uses a cascading, token-efficient documentation system optimized for AI agent consumption.
+
+### How to Find Information
+
+1. **Read `documentation/TABLEOFCONTENTS.md` FIRST** — this is the navigation index
+2. Find your topic in the question-to-file mapping tables
+3. Read ONLY the 1-3 files relevant to your task
+4. **Never read all documentation files** — this wastes token budget
+
+### Documentation Structure
+[Insert the actual directory tree of documentation/ here]
+
+### Example Lookups
+- "[Example question 1]" → `[actual-path-1.md]`
+- "[Example question 2]" → `[actual-path-2.md]`, `[actual-path-3.md]`
+- "[Example question 3]" → `[actual-path-4.md]`
+
+## Token Budget Rules
+
+- **20-30% of tokens:** Reading documentation (via TABLEOFCONTENTS.md targeting)
+- **70-80% of tokens:** Implementation and problem-solving
+
+**Do:**
+- Use TABLEOFCONTENTS.md to target specific files
+- Read only "Key Details" and "API/Interfaces" sections
+- Skip code examples unless implementing similar functionality
+
+**Don't:**
+- Read all documentation files sequentially
+- Read verbose examples when not needed
+- Re-read the same docs multiple times in one session
+
+## Documentation Maintenance
+
+When you modify code that changes behavior documented in `documentation/`:
+1. Read TABLEOFCONTENTS.md to find the relevant doc(s)
+2. Update those docs to reflect your changes
+3. Use the token-efficient format: bullets, tables, compact code blocks — no prose
+4. If you create a new doc, add it to TABLEOFCONTENTS.md
+
+### Token-Efficient Format Reference
+- **Status line:** `**Status:** [Implemented | Partial | Planned] — [one-line summary]`
+- **Bullets, not paragraphs** — every detail as a dash-prefixed list item
+- **Tables for APIs** — method, path, request, response
+- **Code blocks only for schemas/configs** — max 2 per document
+- **30-80 lines per file** — split if over 120
+- **No:** prose explanations, future plans, testing strategy, empty sections
+```
+
+---
+
+## 6. Quality Standards
+
+Your output will be evaluated on:
+
+1. **TABLEOFCONTENTS.md completeness** — Can an agent find any topic by searching this one file?
+2. **Question quality** — Are the TOC questions phrased the way someone would actually ask them?
+3. **Format compliance** — Do all docs follow the token-efficient format? No prose, no fluff?
+4. **Accuracy** — Do the docs match what's actually in the code? Are file paths correct?
+5. **Coverage** — Are all high-impact areas documented? Are low-impact areas at least listed?
+6. **CLAUDE.md clarity** — Could a brand-new agent read CLAUDE.md and immediately know how to navigate the docs?
+7. **Cross-referencing** — Do Related sections link to the right companion docs?
+
+---
+
+## 7. Important Reminders
+
+- **You are writing for AI agents, not humans.** Optimize for parseability and token efficiency, not readability or visual appeal.
+- **Accuracy over completeness.** It's better to document 80% of the codebase accurately than 100% with errors. If a discovery agent can't determine something with confidence, note it as `**Status:** Partial` and move on.
+- **Mirror the codebase's language.** Use the same names for things that the code uses. If the code calls it a "processor," don't call it a "handler" in the docs.
+- **File paths are critical.** Every doc should reference the actual source files it describes. Agents will use these paths to navigate directly to code.
+- **The TOC is the product.** The individual doc files are supporting material. If the TOC is excellent, the whole system works. If the TOC is poor, nothing else matters.
+- **Delegate aggressively.** You have access to the Task tool with sub-agents. Use it. The discovery phase should be 3-5 parallel agents. The writing phase should be 2-10 parallel agents depending on repo size. Your job is to orchestrate, synthesize, and build the TOC — not to read every file yourself.
+- **Do not add headers or comments to source code files.** Your output is documentation files only. Do not modify any existing source code.
+
+---
+
+## Now Begin
+
+Start with Phase 1. Launch your discovery agents in parallel. Once they report back, proceed through the remaining phases. When complete, report what you've created and provide the full TABLEOFCONTENTS.md for review.

documentation/features/manual-import.md

@@ -0,0 +1,87 @@
+# Manual Import Feature — Acceptance Criteria
+
+**Status:** ⏳ In Progress
+
+## Overview
+Allow admins to manually import audiobook files from the server filesystem into RMAB's processing pipeline for a specific book.
+
+## Acceptance Criteria
+
+### AC-1: Manual Import Button (Frontend)
+- [ ] "Manual Import" button visible on `AudiobookDetailsModal` for admin users only
+- [ ] Button hidden when book is in active processing states: `downloading`, `processing`, `searching`
+- [ ] Button uses `FolderArrowDownIcon` from Heroicons
+- [ ] Clicking opens the file browser modal
+
+### AC-2: File Browser Modal — Phase 1 (Browse)
+- [ ] Modal opens at `max-w-2xl`, rounded-2xl, with header/breadcrumb/listing/footer regions
+- [ ] Root view shows two entry tiles: Downloads and Media Library (paths from `download_dir` and `media_dir` config)
+- [ ] Each folder row shows: folder icon, name, metadata line (audio file count, subfolder count, total size)
+- [ ] Blue `♪ N` badge on folders containing audio files
+- [ ] Folder icon swaps to `FolderOpenIcon` on hover (150ms transition)
+- [ ] Single-click selects folder (only if it has audio files); double-click navigates into it
+- [ ] Folders without audio files shown at reduced opacity, still navigable but not selectable
+- [ ] Breadcrumb navigation with clickable segments, home icon for root, ellipsis collapse for deep paths
+- [ ] Footer shows selected path (monospace), file stats, "Review Import →" button (only when valid selection)
+- [ ] Directional slide animations: right when going deeper, left when going back
+- [ ] Loading skeletons during directory fetch
+- [ ] Empty state for empty directories
+- [ ] Error state with "Try Again" for failed directory reads
+- [ ] Dark mode support throughout
+
+### AC-3: File Browser Modal — Phase 2 (Confirm)
+- [ ] Slide transition from browse to confirm phase
+- [ ] Shows book context: cover thumbnail + title + author
+- [ ] Shows selected folder: path (monospace) + stats in inset block
+- [ ] Numbered "What will happen" list: (1) copy to media library, (2) tag metadata, (3) download cover art, (4) scan library
+- [ ] "Back" button returns to browse phase
+- [ ] "Start Import" primary button triggers the import
+- [ ] Button shows loading state during API call
+- [ ] Success: close modal, show success toast, trigger request list refresh
+- [ ] Error: show error toast, stay on confirm screen
+
+### AC-4: Filesystem Browse API
+- [ ] `GET /api/admin/filesystem/browse?path=...` — admin-only endpoint
+- [ ] Returns directory listing: `{ entries: [{ name, type, audioFileCount, subfolderCount, totalSize }] }`
+- [ ] If no `path` param, returns root directories (download_dir, media_dir from config)
+- [ ] Path validation: must be within allowed root directories (prevent directory traversal)
+- [ ] Handles permission errors gracefully
+- [ ] Sorts: folders first, then alphabetical
+
+### AC-5: Manual Import API
+- [ ] `POST /api/admin/manual-import` — admin-only endpoint
+- [ ] Request body: `{ audiobookId: string, folderPath: string }`
+- [ ] Path validation: folderPath must be within allowed roots
+- [ ] Validates folder exists and contains audio files
+- [ ] If no existing request: creates request (status: `processing`) + queues `organize_files` job
+- [ ] If existing request (non-active state): updates status to `processing` + queues `organize_files` job
+- [ ] Returns: `{ success: true, requestId: string }`
+- [ ] Proper error responses for: invalid path, no audio files, already processing, book not found
+
+### AC-6: Integration with Existing Pipeline
+- [ ] The `organize_files` job processes the manual import folder identically to download-client-delivered folders
+- [ ] Files are copied (not moved) to the media library
+- [ ] Metadata tagging, cover art download, file hash generation all work as normal
+- [ ] Library scan triggered after organization (if configured)
+- [ ] Request status progresses: processing → downloaded → available (via scheduled scan)
+
+### AC-7: Docker Build
+- [ ] `docker compose build readmeabook` succeeds with no errors
+
+## Non-Goals
+- No "move" option (copy only, matching existing pipeline)
+- No file-level selection (folder only)
+- No drag-and-drop upload
+- No non-admin access
+
+## Technical Notes
+- Audio extensions: `.m4b`, `.m4a`, `.mp3`, `.mp4`, `.aa`, `.aax`, `.flac`, `.ogg` (from `src/lib/constants/audio-formats.ts`)
+- Config keys: `download_dir` (database), `media_dir` (database)
+- Existing file organizer: `src/lib/utils/file-organizer.ts`
+- Organize processor: `src/lib/processors/organize-files.processor.ts`
+- Job queue service: `src/lib/services/job-queue.service.ts`
+- Auth middleware: `requireAuth()`, `requireAdmin()` from `src/lib/middleware/auth.ts`
+- Frontend API pattern: `fetchWithAuth()` from `src/lib/utils/api.ts`
+- Modal base: `src/components/ui/Modal.tsx`
+- Audiobook details modal: `src/components/audiobooks/AudiobookDetailsModal.tsx`
+- Toast: `useToast()` from toast context

documentation/integrations/audible.md

@@ -33,6 +33,7 @@ Configurable Audible region for accurate metadata matching across different inte
 - India (`in`) - `audible.in` (English)
 - Germany (`de`) - `audible.de` (non-English)
 - Spain (`es`) - `audible.es` (non-English)
+- French (`fr`) - `audible.fr` (non-English)
 
 **`isEnglish` Flag:**
 - Each region has `isEnglish: boolean` in `AudibleRegionConfig`

documentation/phase3/qbittorrent.md

@@ -243,7 +243,7 @@ type TorrentState =
    - `forcedUP` → `seeding`/`completed` enables monitor to trigger import
    - `stoppedDL` → `paused` ensures qBittorrent v5.x compatibility
 
-**16. pausedUP/stoppedUP mapped as paused instead of completed** - RDT-Client (and qBittorrent after ratio limits) transitions directly to `pausedUP`/`stoppedUP` without passing through `uploading`/`stalledUP`. The `*UP` suffix means the download phase is complete and the torrent is on the upload side. Both states were incorrectly mapped to `'paused'`, causing the monitor to re-schedule checks indefinitely instead of triggering file organization. Fixed by:
+**16. pausedUP/stoppedUP mapped as paused instead of completed** - qBittorrent (after ratio limits) transitions directly to `pausedUP`/`stoppedUP` without passing through `uploading`/`stalledUP`. The `*UP` suffix means the download phase is complete and the torrent is on the upload side. Both states were incorrectly mapped to `'paused'`, causing the monitor to re-schedule checks indefinitely instead of triggering file organization. Fixed by:
    - `pausedUP` → `seeding` (unified) / `completed` (legacy) — triggers completion in monitor
    - `stoppedUP` → `seeding` (unified) / `completed` (legacy) — same fix for qBittorrent v5.x
    - `pausedDL`/`stoppedDL` remain `paused` — download phase genuinely paused

documentation/settings-pages.md

@@ -271,7 +271,7 @@ src/app/admin/settings/
 
 **PUT /api/admin/settings/audible**
 - Updates Audible region
-- Body: `{ region: string }` (one of: us, ca, uk, au, in, es)
+- Body: `{ region: string }` (one of: us, ca, uk, au, in, es, fr)
 - No validation required
 
 **PUT /api/admin/settings/prowlarr/indexers**

package.json

@@ -1,6 +1,6 @@
 {
   "name": "readmeabook",
-  "version": "1.0.9",
+  "version": "1.0.16",
   "private": true,
   "scripts": {
     "dev": "next dev",
@@ -18,7 +18,9 @@
   "dependencies": {
     "@heroicons/react": "^2.2.0",
     "@prisma/client": "^6.19.0",
+    "@types/archiver": "^7.0.0",
     "adm-zip": "^0.5.16",
+    "archiver": "^7.0.1",
     "axios": "^1.7.2",
     "bcrypt": "^5.1.1",
     "bull": "^4.12.0",
@@ -43,9 +45,9 @@
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
     "@testing-library/jest-dom": "^6.9.1",
-    "@types/adm-zip": "^0.5.6",
     "@testing-library/react": "^16.3.1",
     "@testing-library/user-event": "^14.6.1",
+    "@types/adm-zip": "^0.5.6",
     "@types/bcrypt": "^5.0.2",
     "@types/bull": "^4.10.0",
     "@types/jsonwebtoken": "^9.0.6",

prisma/migrations/20260212000000_add_download_access_permission/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "users" ADD COLUMN "download_access" BOOLEAN;

prisma/migrations/20260302000000_add_custom_search_terms/migration.sql

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

prisma/schema.prisma

@@ -55,6 +55,7 @@ model User {
 
   // Fine-grained permissions
   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
 
   // Soft delete support
   deletedAt DateTime? @map("deleted_at")
@@ -231,6 +232,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")
@@ -390,7 +392,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)

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/RecentRequestsTable.tsx

@@ -28,6 +28,8 @@ interface RecentRequest {
   completedAt: Date | null;
   errorMessage: string | null;
   torrentUrl?: string | null;
+  downloadAttempts?: number;
+  customSearchTerms?: string | null;
 }
 
 interface User {
@@ -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/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,8 +42,10 @@ export function RequestActionsDropdown({
   onDelete,
   onManualSearch,
   onCancel,
+  onRetryDownload,
   onViewDetails,
   onFetchEbook,
+  onSearchTermsUpdated,
   ebookSidecarEnabled = false,
   annasArchiveBaseUrl = 'https://annas-archive.li',
   isLoading = false,
@@ -46,6 +53,7 @@ export function RequestActionsDropdown({
   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
@@ -57,6 +65,8 @@ export function RequestActionsDropdown({
   // 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 canAdjustSearchTerms = !isEbook && ['pending', 'failed', 'awaiting_search', 'searching'].includes(request.status);
+  const canRetryDownload = request.status === 'failed' && (request.downloadAttempts ?? 0) > 0 && !!onRetryDownload;
   const canCancel = ['pending', 'searching', 'downloading'].includes(request.status);
   const canDelete = true; // Admins can always delete
 
@@ -123,11 +133,27 @@ export function RequestActionsDropdown({
     setShowInteractiveSearch(true);
   };
 
+  const handleAdjustSearchTerms = () => {
+    setIsOpen(false);
+    setShowAdjustSearchTerms(true);
+  };
+
   const handleInteractiveSearchEbook = () => {
     setIsOpen(false);
     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 +279,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 +383,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 +437,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 +500,7 @@ export function RequestActionsDropdown({
           title: request.title,
           author: request.author,
         }}
+        customSearchTerms={request.customSearchTerms}
       />
 
       {/* Interactive Search Modal (Ebook) */}
@@ -434,6 +514,17 @@ export function RequestActionsDropdown({
         }}
         searchMode="ebook"
       />
+
+      {/* 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/jobs/page.tsx

@@ -78,13 +78,11 @@ function AdminJobsPageContent() {
   const showEditDialog = (job: ScheduledJob) => {
     setEditForm({ schedule: job.schedule, enabled: job.enabled });
 
-    // Check if it's a preset
     const preset = SCHEDULE_PRESETS.find(p => p.cron === job.schedule);
     if (preset) {
       setScheduleMode('preset');
       setSelectedPreset(preset.cron);
     } else {
-      // Try to parse as custom schedule
       const parsed = cronToCustomSchedule(job.schedule);
       if (parsed.type === 'custom') {
         setScheduleMode('advanced');
@@ -111,7 +109,7 @@ function AdminJobsPageContent() {
         method: 'POST',
       });
       toast.success(`Job "${jobName}" triggered successfully`);
-      fetchJobs(); // Refresh list
+      fetchJobs();
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : 'Failed to trigger job';
       toast.error(errorMsg);
@@ -124,7 +122,6 @@ function AdminJobsPageContent() {
   const saveJobSchedule = async () => {
     if (!editDialog.job) return;
 
-    // Calculate final cron expression based on mode
     let finalCron: string;
     if (scheduleMode === 'preset') {
       finalCron = selectedPreset;
@@ -134,7 +131,6 @@ function AdminJobsPageContent() {
       finalCron = editForm.schedule;
     }
 
-    // Validate cron expression
     if (!isValidCron(finalCron)) {
       toast.error('Invalid cron expression. Please check your schedule.');
       return;
@@ -151,7 +147,7 @@ function AdminJobsPageContent() {
       });
       toast.success(`Job "${editDialog.job.name}" updated successfully`);
       hideEditDialog();
-      fetchJobs(); // Refresh list
+      fetchJobs();
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : 'Failed to update job';
       toast.error(errorMsg);
@@ -173,36 +169,131 @@ function AdminJobsPageContent() {
 
   return (
     <div className="min-h-screen bg-gray-50 dark:bg-gray-900">
-      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
-        {/* Header */}
-        <div className="sticky top-0 z-10 mb-8 flex items-center justify-between bg-gray-50 dark:bg-gray-900 py-4 -mx-4 px-4 sm:-mx-6 sm:px-6 lg:-mx-8 lg:px-8 border-b border-gray-200 dark:border-gray-800">
-          <div>
-            <h1 className="text-3xl font-bold text-gray-900 dark:text-gray-100">
-              Scheduled Jobs
-            </h1>
-            <p className="text-gray-600 dark:text-gray-400 mt-2">
-              Manage recurring tasks and automated jobs
-            </p>
+      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-6 sm:py-8">
+
+        {/* Header — stacks on mobile, row on sm+ */}
+        <div className="sticky top-0 z-10 mb-6 sm:mb-8 bg-gray-50 dark:bg-gray-900 py-4 -mx-4 px-4 sm:-mx-6 sm:px-6 lg:-mx-8 lg:px-8 border-b border-gray-200 dark:border-gray-800">
+          <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+            <div>
+              <h1 className="text-2xl sm:text-3xl font-bold text-gray-900 dark:text-gray-100">
+                Scheduled Jobs
+              </h1>
+              <p className="text-sm text-gray-600 dark:text-gray-400 mt-1">
+                Manage recurring tasks and automated jobs
+              </p>
+            </div>
+            <Link
+              href="/admin"
+              className="inline-flex items-center gap-2 px-4 py-2.5 bg-gray-200 dark:bg-gray-700 hover:bg-gray-300 dark:hover:bg-gray-600 text-gray-900 dark:text-gray-100 rounded-lg transition-colors text-sm font-medium self-start sm:self-auto flex-shrink-0"
+            >
+              <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 19l-7-7m0 0l7-7m-7 7h18" />
+              </svg>
+              <span>Back to Dashboard</span>
+            </Link>
           </div>
-          <Link
-            href="/admin"
-            className="inline-flex items-center gap-2 px-4 py-2 bg-gray-200 dark:bg-gray-700 hover:bg-gray-300 dark:hover:bg-gray-600 text-gray-900 dark:text-gray-100 rounded-lg transition-colors"
-          >
-            <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 19l-7-7m0 0l7-7m-7 7h18" />
-            </svg>
-            <span>Back to Dashboard</span>
-          </Link>
         </div>
 
         {error && (
           <div className="mb-6 p-4 bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg">
-            <p className="text-red-800 dark:text-red-200">{error}</p>
+            <p className="text-red-800 dark:text-red-200 text-sm">{error}</p>
           </div>
         )}
 
-        {/* Jobs Table */}
-        <div className="bg-white dark:bg-gray-800 rounded-lg shadow overflow-hidden">
+        {/* Jobs — Card layout on mobile, Table on sm+ */}
+        <div className="space-y-3 sm:hidden">
+          {jobs.map((job) => (
+            <div
+              key={job.id}
+              className="bg-white dark:bg-gray-800 rounded-xl border border-gray-200 dark:border-gray-700 overflow-hidden"
+            >
+              {/* Card header */}
+              <div className="px-4 py-3 flex items-start justify-between gap-3">
+                <div className="min-w-0">
+                  <div className="font-semibold text-gray-900 dark:text-gray-100 text-sm leading-snug">
+                    {job.name}
+                  </div>
+                  <div className="text-xs text-gray-500 dark:text-gray-400 mt-0.5">
+                    {job.type}
+                  </div>
+                </div>
+                <span
+                  className={`flex-shrink-0 mt-0.5 px-2.5 py-0.5 inline-flex text-xs font-medium rounded-full ${
+                    job.enabled
+                      ? 'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400'
+                      : 'bg-gray-100 text-gray-600 dark:bg-gray-700 dark:text-gray-400'
+                  }`}
+                >
+                  {job.enabled ? 'Enabled' : 'Disabled'}
+                </span>
+              </div>
+
+              {/* Card body */}
+              <div className="px-4 pb-3 space-y-2 border-t border-gray-100 dark:border-gray-700/60 pt-3">
+                <div>
+                  <div className="text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-0.5">
+                    Schedule
+                  </div>
+                  <div className="text-sm text-gray-900 dark:text-gray-100">
+                    {cronToHuman(job.schedule)}
+                  </div>
+                  <div className="text-xs text-gray-400 dark:text-gray-500 font-mono mt-0.5">
+                    {job.schedule}
+                  </div>
+                </div>
+                <div>
+                  <div className="text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-0.5">
+                    Last Run
+                  </div>
+                  <div className="text-sm text-gray-700 dark:text-gray-300">
+                    {job.lastRun ? new Date(job.lastRun).toLocaleString() : 'Never'}
+                  </div>
+                </div>
+              </div>
+
+              {/* Card actions */}
+              <div className="px-4 py-3 border-t border-gray-100 dark:border-gray-700/60 flex gap-2">
+                <button
+                  onClick={() => showEditDialog(job)}
+                  className="flex-1 inline-flex items-center justify-center gap-2 px-3 py-2.5 bg-gray-100 dark:bg-gray-700 hover:bg-gray-200 dark:hover:bg-gray-600 text-gray-700 dark:text-gray-200 rounded-lg text-sm font-medium 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="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>
+                  Edit
+                </button>
+                <button
+                  onClick={() => showConfirmDialog(job.id, job.name)}
+                  disabled={triggering === job.id}
+                  className="flex-1 inline-flex items-center justify-center gap-2 px-3 py-2.5 bg-blue-50 dark:bg-blue-900/20 hover:bg-blue-100 dark:hover:bg-blue-900/40 text-blue-700 dark:text-blue-400 rounded-lg text-sm font-medium transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+                >
+                  {triggering === job.id ? (
+                    <>
+                      <div className="animate-spin rounded-full h-4 w-4 border-b-2 border-blue-600"></div>
+                      Running...
+                    </>
+                  ) : (
+                    <>
+                      <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M14.752 11.168l-3.197-2.132A1 1 0 0010 9.87v4.263a1 1 0 001.555.832l3.197-2.132a1 1 0 000-1.664z" />
+                        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+                      </svg>
+                      Trigger
+                    </>
+                  )}
+                </button>
+              </div>
+            </div>
+          ))}
+          {jobs.length === 0 && (
+            <div className="text-center py-12">
+              <p className="text-gray-500 dark:text-gray-400">No scheduled jobs found</p>
+            </div>
+          )}
+        </div>
+
+        {/* Jobs Table — hidden on mobile, visible on sm+ */}
+        <div className="hidden sm:block bg-white dark:bg-gray-800 rounded-lg shadow overflow-hidden">
           <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-700">
             <thead className="bg-gray-50 dark:bg-gray-900">
               <tr>
@@ -312,31 +403,31 @@ function AdminJobsPageContent() {
           <ul className="text-sm text-blue-700 dark:text-blue-300 space-y-1">
             <li>• <strong>Library Scan:</strong> Automatically scans your media library for new audiobooks</li>
             <li>• <strong>Audible Data Refresh:</strong> Caches popular and new release audiobooks from Audible</li>
-            <li>• Trigger jobs manually using the "Trigger Now" button</li>
+            <li>• Trigger jobs manually using the &quot;Trigger Now&quot; button</li>
             <li>• Schedule format follows cron syntax (minute hour day month weekday)</li>
           </ul>
         </div>
 
         {/* Confirmation Dialog */}
         {confirmDialog.isOpen && (
-          <div className="fixed inset-0 z-50 flex items-center justify-center bg-black bg-opacity-50 p-4">
-            <div className="bg-white dark:bg-gray-800 rounded-lg shadow-xl max-w-md w-full p-6">
-              <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-4">
+          <div className="fixed inset-0 z-50 flex items-end sm:items-center justify-center bg-black bg-opacity-50 p-4">
+            <div className="bg-white dark:bg-gray-800 rounded-2xl sm:rounded-lg shadow-xl w-full max-w-md p-6">
+              <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-3">
                 Confirm Job Trigger
               </h3>
-              <p className="text-gray-600 dark:text-gray-400 mb-6">
+              <p className="text-gray-600 dark:text-gray-400 text-sm mb-6">
                 Are you sure you want to trigger &quot;{confirmDialog.jobName}&quot; now?
               </p>
-              <div className="flex justify-end gap-3">
+              <div className="flex gap-3">
                 <button
                   onClick={hideConfirmDialog}
-                  className="px-4 py-2 text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 hover:bg-gray-200 dark:hover:bg-gray-600 rounded-lg transition-colors"
+                  className="flex-1 px-4 py-2.5 text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 hover:bg-gray-200 dark:hover:bg-gray-600 rounded-lg transition-colors text-sm font-medium"
                 >
                   Cancel
                 </button>
                 <button
                   onClick={triggerJob}
-                  className="px-4 py-2 text-white bg-blue-600 hover:bg-blue-700 rounded-lg transition-colors"
+                  className="flex-1 px-4 py-2.5 text-white bg-blue-600 hover:bg-blue-700 rounded-lg transition-colors text-sm font-medium"
                 >
                   Trigger Job
                 </button>
@@ -347,12 +438,27 @@ function AdminJobsPageContent() {
 
         {/* Edit Job Dialog */}
         {editDialog.isOpen && editDialog.job && (
-          <div className="fixed inset-0 z-50 flex items-center justify-center bg-black bg-opacity-50 p-4">
-            <div className="bg-white dark:bg-gray-800 rounded-lg shadow-xl max-w-2xl w-full p-6 max-h-[90vh] overflow-y-auto">
-              <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-4">
-                Edit Job Schedule
-              </h3>
-              <div className="space-y-4 mb-6">
+          <div className="fixed inset-0 z-50 flex items-end sm:items-center justify-center bg-black bg-opacity-50 p-0 sm:p-4">
+            <div className="bg-white dark:bg-gray-800 rounded-t-2xl sm:rounded-2xl shadow-xl w-full sm:max-w-2xl max-h-[92vh] sm:max-h-[90vh] overflow-y-auto">
+              {/* Dialog header */}
+              <div className="sticky top-0 bg-white dark:bg-gray-800 px-5 py-4 border-b border-gray-200 dark:border-gray-700 rounded-t-2xl">
+                <div className="flex items-center justify-between">
+                  <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100">
+                    Edit Job Schedule
+                  </h3>
+                  <button
+                    onClick={hideEditDialog}
+                    className="p-2 -mr-1 text-gray-400 hover:text-gray-600 dark:hover:text-gray-200 rounded-lg hover:bg-gray-100 dark:hover:bg-gray-700 transition-colors"
+                    aria-label="Close dialog"
+                  >
+                    <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>
+
+              <div className="px-5 py-5 space-y-5">
                 {/* Job Name */}
                 <div>
                   <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">
@@ -362,46 +468,29 @@ function AdminJobsPageContent() {
                     type="text"
                     value={editDialog.job.name}
                     disabled
-                    className="w-full px-3 py-2 bg-gray-100 dark:bg-gray-700 text-gray-500 dark:text-gray-400 border border-gray-300 dark:border-gray-600 rounded-lg cursor-not-allowed"
+                    className="w-full px-3 py-2 bg-gray-100 dark:bg-gray-700 text-gray-500 dark:text-gray-400 border border-gray-300 dark:border-gray-600 rounded-lg cursor-not-allowed text-sm"
                   />
                 </div>
 
-                {/* Schedule Mode Tabs */}
+                {/* Schedule Mode Tabs — grid on mobile to avoid overflow */}
                 <div>
                   <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
                     Schedule Type
                   </label>
-                  <div className="flex gap-2 mb-3">
-                    <button
-                      onClick={() => setScheduleMode('preset')}
-                      className={`px-4 py-2 rounded-lg text-sm font-medium transition-colors ${
-                        scheduleMode === 'preset'
-                          ? 'bg-blue-600 text-white'
-                          : 'bg-gray-100 dark:bg-gray-700 text-gray-700 dark:text-gray-300 hover:bg-gray-200 dark:hover:bg-gray-600'
-                      }`}
-                    >
-                      Common Schedules
-                    </button>
-                    <button
-                      onClick={() => setScheduleMode('custom')}
-                      className={`px-4 py-2 rounded-lg text-sm font-medium transition-colors ${
-                        scheduleMode === 'custom'
-                          ? 'bg-blue-600 text-white'
-                          : 'bg-gray-100 dark:bg-gray-700 text-gray-700 dark:text-gray-300 hover:bg-gray-200 dark:hover:bg-gray-600'
-                      }`}
-                    >
-                      Custom Schedule
-                    </button>
-                    <button
-                      onClick={() => setScheduleMode('advanced')}
-                      className={`px-4 py-2 rounded-lg text-sm font-medium transition-colors ${
-                        scheduleMode === 'advanced'
-                          ? 'bg-blue-600 text-white'
-                          : 'bg-gray-100 dark:bg-gray-700 text-gray-700 dark:text-gray-300 hover:bg-gray-200 dark:hover:bg-gray-600'
-                      }`}
-                    >
-                      Advanced (Cron)
-                    </button>
+                  <div className="grid grid-cols-3 gap-1 p-1 bg-gray-100 dark:bg-gray-700/60 rounded-xl mb-4">
+                    {(['preset', 'custom', 'advanced'] as const).map((mode) => (
+                      <button
+                        key={mode}
+                        onClick={() => setScheduleMode(mode)}
+                        className={`px-2 py-2 rounded-lg text-xs font-medium transition-colors ${
+                          scheduleMode === mode
+                            ? 'bg-white dark:bg-gray-600 text-gray-900 dark:text-white shadow-sm'
+                            : 'text-gray-600 dark:text-gray-400 hover:text-gray-800 dark:hover:text-gray-200'
+                        }`}
+                      >
+                        {mode === 'preset' ? 'Common' : mode === 'custom' ? 'Custom' : 'Advanced'}
+                      </button>
+                    ))}
                   </div>
 
                   {/* Preset Mode */}
@@ -418,16 +507,16 @@ function AdminJobsPageContent() {
                             value={preset.cron}
                             checked={selectedPreset === preset.cron}
                             onChange={(e) => setSelectedPreset(e.target.value)}
-                            className="mt-1 w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 focus:ring-blue-500 dark:bg-gray-700 dark:border-gray-600"
+                            className="mt-1 w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 focus:ring-blue-500 dark:bg-gray-700 dark:border-gray-600 flex-shrink-0"
                           />
-                          <div className="flex-1">
+                          <div className="flex-1 min-w-0">
                             <div className="text-sm font-medium text-gray-900 dark:text-gray-100">
                               {preset.label}
                             </div>
-                            <div className="text-xs text-gray-500 dark:text-gray-400 mt-1">
+                            <div className="text-xs text-gray-500 dark:text-gray-400 mt-0.5">
                               {preset.description}
                             </div>
-                            <div className="text-xs text-gray-400 dark:text-gray-500 font-mono mt-1">
+                            <div className="text-xs text-gray-400 dark:text-gray-500 font-mono mt-0.5">
                               {preset.cron}
                             </div>
                           </div>
@@ -445,8 +534,8 @@ function AdminJobsPageContent() {
                         </label>
                         <select
                           value={customSchedule.type}
-                          onChange={(e) => setCustomSchedule({ ...customSchedule, type: e.target.value as any })}
-                          className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500"
+                          onChange={(e) => setCustomSchedule({ ...customSchedule, type: e.target.value as CustomSchedule['type'] })}
+                          className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500 text-sm"
                         >
                           <option value="minutes">Every X minutes</option>
                           <option value="hours">Every X hours</option>
@@ -456,7 +545,6 @@ function AdminJobsPageContent() {
                         </select>
                       </div>
 
-                      {/* Minutes/Hours Interval */}
                       {(customSchedule.type === 'minutes' || customSchedule.type === 'hours') && (
                         <div>
                           <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
@@ -468,7 +556,7 @@ function AdminJobsPageContent() {
                             max={customSchedule.type === 'minutes' ? 59 : 23}
                             value={customSchedule.interval || 1}
                             onChange={(e) => setCustomSchedule({ ...customSchedule, interval: parseInt(e.target.value, 10) })}
-                            className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500"
+                            className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500 text-sm"
                           />
                           <p className="text-xs text-gray-500 dark:text-gray-400 mt-1">
                             Run every {customSchedule.interval || 1} {customSchedule.type}
@@ -476,12 +564,11 @@ function AdminJobsPageContent() {
                         </div>
                       )}
 
-                      {/* Daily/Weekly/Monthly Time */}
                       {(customSchedule.type === 'daily' || customSchedule.type === 'weekly' || customSchedule.type === 'monthly') && (
                         <div className="grid grid-cols-2 gap-4">
                           <div>
                             <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
-                              Hour (0-23)
+                              Hour (0–23)
                             </label>
                             <input
                               type="number"
@@ -494,12 +581,12 @@ function AdminJobsPageContent() {
                                   time: { hour: parseInt(e.target.value, 10), minute: customSchedule.time?.minute || 0 },
                                 })
                               }
-                              className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500"
+                              className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500 text-sm"
                             />
                           </div>
                           <div>
                             <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
-                              Minute (0-59)
+                              Minute (0–59)
                             </label>
                             <input
                               type="number"
@@ -512,13 +599,12 @@ function AdminJobsPageContent() {
                                   time: { hour: customSchedule.time?.hour || 0, minute: parseInt(e.target.value, 10) },
                                 })
                               }
-                              className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500"
+                              className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500 text-sm"
                             />
                           </div>
                         </div>
                       )}
 
-                      {/* Weekly Day Selection */}
                       {customSchedule.type === 'weekly' && (
                         <div>
                           <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
@@ -527,7 +613,7 @@ function AdminJobsPageContent() {
                           <select
                             value={customSchedule.dayOfWeek || 0}
                             onChange={(e) => setCustomSchedule({ ...customSchedule, dayOfWeek: parseInt(e.target.value, 10) })}
-                            className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500"
+                            className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500 text-sm"
                           >
                             <option value="0">Sunday</option>
                             <option value="1">Monday</option>
@@ -540,11 +626,10 @@ function AdminJobsPageContent() {
                         </div>
                       )}
 
-                      {/* Monthly Day Selection */}
                       {customSchedule.type === 'monthly' && (
                         <div>
                           <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
-                            Day of Month (1-31)
+                            Day of Month (1–31)
                           </label>
                           <input
                             type="number"
@@ -552,12 +637,11 @@ function AdminJobsPageContent() {
                             max="31"
                             value={customSchedule.dayOfMonth || 1}
                             onChange={(e) => setCustomSchedule({ ...customSchedule, dayOfMonth: parseInt(e.target.value, 10) })}
-                            className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500"
+                            className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500 text-sm"
                           />
                         </div>
                       )}
 
-                      {/* Preview */}
                       <div className="p-3 bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-lg">
                         <div className="text-sm font-medium text-blue-900 dark:text-blue-200">
                           Preview: {cronToHuman(customScheduleToCron(customSchedule))}
@@ -571,30 +655,32 @@ function AdminJobsPageContent() {
 
                   {/* Advanced Mode */}
                   {scheduleMode === 'advanced' && (
-                    <div>
-                      <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
-                        Cron Expression
-                      </label>
-                      <input
-                        type="text"
-                        value={editForm.schedule}
-                        onChange={(e) => setEditForm({ ...editForm, schedule: e.target.value })}
-                        placeholder="0 */6 * * *"
-                        className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500 font-mono"
-                      />
-                      <p className="text-xs text-gray-500 dark:text-gray-400 mt-1">
-                        Format: minute hour day month weekday
-                      </p>
-                      <div className="mt-2 p-3 bg-gray-50 dark:bg-gray-700 rounded-lg">
-                        <div className="text-xs text-gray-600 dark:text-gray-400 space-y-1">
-                          <div>• */15 * * * * = Every 15 minutes</div>
-                          <div>• 0 */6 * * * = Every 6 hours</div>
-                          <div>• 0 0 * * * = Daily at midnight</div>
-                          <div>• 0 0 * * 0 = Weekly on Sunday</div>
+                    <div className="space-y-3">
+                      <div>
+                        <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
+                          Cron Expression
+                        </label>
+                        <input
+                          type="text"
+                          value={editForm.schedule}
+                          onChange={(e) => setEditForm({ ...editForm, schedule: e.target.value })}
+                          placeholder="0 */6 * * *"
+                          className="w-full px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500 font-mono text-sm"
+                        />
+                        <p className="text-xs text-gray-500 dark:text-gray-400 mt-1">
+                          Format: minute hour day month weekday
+                        </p>
+                      </div>
+                      <div className="p-3 bg-gray-50 dark:bg-gray-700 rounded-lg">
+                        <div className="text-xs text-gray-600 dark:text-gray-400 space-y-1 font-mono">
+                          <div>*/15 * * * * = Every 15 minutes</div>
+                          <div>0 */6 * * * = Every 6 hours</div>
+                          <div>0 0 * * * = Daily at midnight</div>
+                          <div>0 0 * * 0 = Weekly on Sunday</div>
                         </div>
                       </div>
                       {editForm.schedule && (
-                        <div className="mt-2 p-3 bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-lg">
+                        <div className="p-3 bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-lg">
                           <div className="text-sm font-medium text-blue-900 dark:text-blue-200">
                             Preview: {cronToHuman(editForm.schedule)}
                           </div>
@@ -604,34 +690,34 @@ function AdminJobsPageContent() {
                   )}
                 </div>
 
-                {/* Enabled Checkbox */}
-                <div className="flex items-center gap-2 pt-4 border-t border-gray-200 dark:border-gray-700">
+                {/* Enabled toggle */}
+                <div className="flex items-center gap-3 pt-4 border-t border-gray-200 dark:border-gray-700">
                   <input
                     type="checkbox"
                     id="enabled"
                     checked={editForm.enabled}
                     onChange={(e) => setEditForm({ ...editForm, enabled: e.target.checked })}
-                    className="w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:bg-gray-700 dark:border-gray-600"
+                    className="w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 rounded focus:ring-blue-500 dark:bg-gray-700 dark:border-gray-600 flex-shrink-0"
                   />
-                  <label htmlFor="enabled" className="text-sm font-medium text-gray-700 dark:text-gray-300">
+                  <label htmlFor="enabled" className="text-sm font-medium text-gray-700 dark:text-gray-300 cursor-pointer">
                     Enable this job
                   </label>
                 </div>
               </div>
 
-              {/* Actions */}
-              <div className="flex justify-end gap-3">
+              {/* Dialog footer */}
+              <div className="sticky bottom-0 bg-white dark:bg-gray-800 px-5 py-4 border-t border-gray-200 dark:border-gray-700 flex gap-3">
                 <button
                   onClick={hideEditDialog}
                   disabled={saving}
-                  className="px-4 py-2 text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 hover:bg-gray-200 dark:hover:bg-gray-600 rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+                  className="flex-1 sm:flex-none px-4 py-2.5 text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 hover:bg-gray-200 dark:hover:bg-gray-600 rounded-lg transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed"
                 >
                   Cancel
                 </button>
                 <button
                   onClick={saveJobSchedule}
                   disabled={saving}
-                  className="px-4 py-2 text-white bg-blue-600 hover:bg-blue-700 rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+                  className="flex-1 sm:flex-none px-4 py-2.5 text-white bg-blue-600 hover:bg-blue-700 rounded-lg transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed"
                 >
                   {saving ? 'Saving...' : 'Save Changes'}
                 </button>

src/app/admin/logs/page.tsx

@@ -56,6 +56,119 @@ interface LogsData {
   };
 }
 
+function StatusBadge({ status }: { status: string }) {
+  const config: Record<string, { dot: string; text: string; bg: string }> = {
+    completed: { dot: 'bg-emerald-500', text: 'text-emerald-700 dark:text-emerald-400', bg: 'bg-emerald-500/10' },
+    failed: { dot: 'bg-red-500', text: 'text-red-700 dark:text-red-400', bg: 'bg-red-500/10' },
+    active: { dot: 'bg-blue-500', text: 'text-blue-700 dark:text-blue-400', bg: 'bg-blue-500/10' },
+    pending: { dot: 'bg-amber-500', text: 'text-amber-700 dark:text-amber-400', bg: 'bg-amber-500/10' },
+    delayed: { dot: 'bg-orange-500', text: 'text-orange-700 dark:text-orange-400', bg: 'bg-orange-500/10' },
+    stuck: { dot: 'bg-purple-500', text: 'text-purple-700 dark:text-purple-400', bg: 'bg-purple-500/10' },
+  };
+  const c = config[status] ?? { dot: 'bg-gray-400', text: 'text-gray-600 dark:text-gray-400', bg: 'bg-gray-500/10' };
+
+  return (
+    <span className={`inline-flex items-center gap-1.5 px-2.5 py-0.5 rounded-full text-xs font-medium ${c.bg} ${c.text}`}>
+      <span className={`w-1.5 h-1.5 rounded-full flex-shrink-0 ${c.dot}`} />
+      {status.charAt(0).toUpperCase() + status.slice(1)}
+    </span>
+  );
+}
+
+function LogDetails({ log }: { log: Log }) {
+  return (
+    <div className="space-y-4">
+      {log.bullJobId && (
+        <div className="flex flex-wrap gap-1.5 items-baseline">
+          <span className="text-xs font-medium text-gray-500 dark:text-gray-400">Bull Job ID:</span>
+          <span className="text-xs text-gray-700 dark:text-gray-300 font-mono break-all">{log.bullJobId}</span>
+        </div>
+      )}
+
+      {log.events.length > 0 && (
+        <div>
+          <h4 className="text-xs font-semibold text-gray-700 dark:text-gray-300 uppercase tracking-wide mb-2">
+            Event Log
+          </h4>
+          <div className="space-y-px max-h-72 sm:max-h-96 overflow-y-auto bg-gray-950 dark:bg-black/60 rounded-xl p-3 font-mono text-xs">
+            {log.events.map((event) => {
+              const timestamp = new Date(event.createdAt).toISOString().split('T')[1].split('.')[0];
+              const levelColor = event.level === 'error'
+                ? 'text-red-400'
+                : event.level === 'warn'
+                ? 'text-amber-400'
+                : 'text-emerald-400';
+
+              return (
+                <div key={event.id} className="text-gray-300 leading-relaxed">
+                  <span className={levelColor}>[{event.context}]</span>
+                  {' '}
+                  <span className="break-words">{event.message}</span>
+                  <span className="text-gray-500 ml-2">{timestamp}</span>
+                  {event.metadata && Object.keys(event.metadata).length > 0 && (
+                    <pre className="ml-4 mt-1 text-gray-400 text-xs overflow-x-auto">
+                      {JSON.stringify(event.metadata, null, 2)}
+                    </pre>
+                  )}
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      )}
+
+      {log.result && Object.keys(log.result).length > 0 && (
+        <div>
+          <h4 className="text-xs font-semibold text-gray-700 dark:text-gray-300 uppercase tracking-wide mb-2">
+            Job Result
+          </h4>
+          <pre className="p-3 bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-xl text-xs text-blue-900 dark:text-blue-300 font-mono overflow-x-auto max-h-48">
+            {JSON.stringify(log.result, null, 2)}
+          </pre>
+        </div>
+      )}
+
+      {log.errorMessage && (
+        <div>
+          <h4 className="text-xs font-semibold text-gray-700 dark:text-gray-300 uppercase tracking-wide mb-2">
+            Error
+          </h4>
+          <div className="p-3 bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-xl text-xs text-red-700 dark:text-red-300 font-mono whitespace-pre-wrap break-words">
+            {log.errorMessage}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function formatDuration(startedAt: string | null, completedAt: string | null) {
+  if (!startedAt) return 'N/A';
+  if (!completedAt) return 'Running…';
+  const durationMs = new Date(completedAt).getTime() - new Date(startedAt).getTime();
+  const seconds = Math.floor(durationMs / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  if (hours > 0) return `${hours}h ${minutes % 60}m`;
+  if (minutes > 0) return `${minutes}m ${seconds % 60}s`;
+  return `${seconds}s`;
+}
+
+function formatType(type: string) {
+  return type.replace(/_/g, ' ').replace(/\b\w/g, (l) => l.toUpperCase());
+}
+
+function formatDateShort(dateStr: string) {
+  const d = new Date(dateStr);
+  const now = new Date();
+  const isToday = d.toDateString() === now.toDateString();
+  if (isToday) {
+    return d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' });
+  }
+  return d.toLocaleDateString([], { month: 'short', day: 'numeric' }) + ' ' +
+    d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+}
+
 export default function AdminLogsPage() {
   const [page, setPage] = useState(1);
   const [statusFilter, setStatusFilter] = useState('all');
@@ -65,9 +178,7 @@ export default function AdminLogsPage() {
   const { data, error } = useSWR<LogsData>(
     `/api/admin/logs?page=${page}&limit=50&status=${statusFilter}&type=${typeFilter}`,
     authenticatedFetcher,
-    {
-      refreshInterval: 10000, // Refresh every 10 seconds
-    }
+    { refreshInterval: 10000 }
   );
 
   const isLoading = !data && !error;
@@ -87,9 +198,7 @@ export default function AdminLogsPage() {
       <div className="min-h-screen bg-gray-50 dark:bg-gray-900 p-8">
         <div className="max-w-7xl mx-auto">
           <div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg p-4">
-            <h3 className="text-sm font-medium text-red-800 dark:text-red-200">
-              Error Loading Logs
-            </h3>
+            <h3 className="text-sm font-medium text-red-800 dark:text-red-200">Error Loading Logs</h3>
             <p className="text-sm text-red-700 dark:text-red-300 mt-1">
               {error?.message || 'Failed to load system logs'}
             </p>
@@ -101,80 +210,45 @@ export default function AdminLogsPage() {
 
   const logs = data?.logs || [];
   const pagination = data?.pagination;
-
-  const getStatusBadgeColor = (status: string) => {
-    switch (status) {
-      case 'completed':
-        return 'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400';
-      case 'failed':
-        return 'bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400';
-      case 'active':
-        return 'bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400';
-      case 'pending':
-        return 'bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-400';
-      case 'delayed':
-        return 'bg-orange-100 text-orange-800 dark:bg-orange-900/30 dark:text-orange-400';
-      case 'stuck':
-        return 'bg-purple-100 text-purple-800 dark:bg-purple-900/30 dark:text-purple-400';
-      default:
-        return 'bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-400';
-    }
-  };
-
-  const formatDuration = (startedAt: string | null, completedAt: string | null) => {
-    if (!startedAt) return 'N/A';
-    if (!completedAt) return 'Running...';
-
-    const start = new Date(startedAt).getTime();
-    const end = new Date(completedAt).getTime();
-    const durationMs = end - start;
-
-    const seconds = Math.floor(durationMs / 1000);
-    const minutes = Math.floor(seconds / 60);
-    const hours = Math.floor(minutes / 60);
-
-    if (hours > 0) return `${hours}h ${minutes % 60}m`;
-    if (minutes > 0) return `${minutes}m ${seconds % 60}s`;
-    return `${seconds}s`;
-  };
+  const hasDetails = (log: Log) => log.events.length > 0 || !!log.errorMessage || !!log.bullJobId || (log.result && Object.keys(log.result).length > 0);
 
   return (
     <div className="min-h-screen bg-gray-50 dark:bg-gray-900">
-      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
-        {/* Header */}
-        <div className="sticky top-0 z-10 mb-8 flex items-center justify-between bg-gray-50 dark:bg-gray-900 py-4 -mx-4 px-4 sm:-mx-6 sm:px-6 lg:-mx-8 lg:px-8 border-b border-gray-200 dark:border-gray-800">
-          <div>
-            <h1 className="text-3xl font-bold text-gray-900 dark:text-gray-100">
-              System Logs
-            </h1>
-            <p className="text-gray-600 dark:text-gray-400 mt-2">
-              View background jobs and system activity
-            </p>
+      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-6 sm:py-8">
+
+        {/* Header — stacks on mobile, row on sm+ */}
+        <div className="sticky top-0 z-10 mb-6 sm:mb-8 bg-gray-50 dark:bg-gray-900 py-4 -mx-4 px-4 sm:-mx-6 sm:px-6 lg:-mx-8 lg:px-8 border-b border-gray-200 dark:border-gray-800">
+          <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+            <div>
+              <h1 className="text-2xl sm:text-3xl font-bold text-gray-900 dark:text-gray-100">
+                System Logs
+              </h1>
+              <p className="text-sm text-gray-600 dark:text-gray-400 mt-1">
+                View background jobs and system activity
+              </p>
+            </div>
+            <Link
+              href="/admin"
+              className="inline-flex items-center gap-2 px-4 py-2.5 bg-gray-200 dark:bg-gray-700 hover:bg-gray-300 dark:hover:bg-gray-600 text-gray-900 dark:text-gray-100 rounded-lg transition-colors text-sm font-medium self-start sm:self-auto flex-shrink-0"
+            >
+              <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 19l-7-7m0 0l7-7m-7 7h18" />
+              </svg>
+              <span>Back to Dashboard</span>
+            </Link>
           </div>
-          <Link
-            href="/admin"
-            className="inline-flex items-center gap-2 px-4 py-2 bg-gray-200 dark:bg-gray-700 hover:bg-gray-300 dark:hover:bg-gray-600 text-gray-900 dark:text-gray-100 rounded-lg transition-colors"
-          >
-            <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 19l-7-7m0 0l7-7m-7 7h18" />
-            </svg>
-            <span>Back to Dashboard</span>
-          </Link>
         </div>
 
-        {/* Filters */}
-        <div className="mb-6 flex flex-wrap gap-4">
+        {/* Filters — full-width stacked on mobile */}
+        <div className="mb-6 grid grid-cols-1 sm:grid-cols-2 gap-3 sm:gap-4">
           <div>
-            <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
+            <label className="block text-xs font-semibold text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-1.5">
               Status
             </label>
             <select
               value={statusFilter}
-              onChange={(e) => {
-                setStatusFilter(e.target.value);
-                setPage(1);
-              }}
-              className="px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500"
+              onChange={(e) => { setStatusFilter(e.target.value); setPage(1); }}
+              className="w-full px-3 py-2.5 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500 text-sm"
             >
               <option value="all">All Statuses</option>
               <option value="pending">Pending</option>
@@ -186,16 +260,13 @@ export default function AdminLogsPage() {
             </select>
           </div>
           <div>
-            <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
+            <label className="block text-xs font-semibold text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-1.5">
               Job Type
             </label>
             <select
               value={typeFilter}
-              onChange={(e) => {
-                setTypeFilter(e.target.value);
-                setPage(1);
-              }}
-              className="px-3 py-2 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500"
+              onChange={(e) => { setTypeFilter(e.target.value); setPage(1); }}
+              className="w-full px-3 py-2.5 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500 text-sm"
             >
               <option value="all">All Types</option>
               <option value="search_indexers">Search Indexers</option>
@@ -215,8 +286,77 @@ export default function AdminLogsPage() {
           </div>
         </div>
 
-        {/* Logs Table */}
-        <div className="bg-white dark:bg-gray-800 rounded-lg shadow overflow-hidden">
+        {/* Mobile card list — hidden on sm+ */}
+        <div className="space-y-3 sm:hidden">
+          {logs.map((log) => (
+            <div
+              key={log.id}
+              className="bg-white dark:bg-gray-800 rounded-xl border border-gray-200 dark:border-gray-700 overflow-hidden"
+            >
+              {/* Card header */}
+              <div className="px-4 py-3">
+                <div className="flex items-start justify-between gap-3 mb-2">
+                  <div className="font-semibold text-gray-900 dark:text-gray-100 text-sm leading-snug">
+                    {formatType(log.type)}
+                  </div>
+                  <StatusBadge status={log.status} />
+                </div>
+
+                {/* Related item */}
+                {log.request?.audiobook ? (
+                  <div className="text-sm mb-2">
+                    <div className="text-gray-700 dark:text-gray-300 font-medium leading-snug">
+                      {log.request.audiobook.title}
+                    </div>
+                    <div className="text-gray-500 dark:text-gray-400 text-xs">
+                      by {log.request.audiobook.author} &middot; {log.request.user.plexUsername}
+                    </div>
+                  </div>
+                ) : (
+                  <div className="text-xs text-gray-500 dark:text-gray-400 mb-2">System job</div>
+                )}
+
+                {/* Meta row */}
+                <div className="flex flex-wrap gap-x-4 gap-y-1 text-xs text-gray-500 dark:text-gray-400">
+                  <span>{formatDateShort(log.createdAt)}</span>
+                  <span>Duration: {formatDuration(log.startedAt, log.completedAt)}</span>
+                  <span>Attempts: {log.attempts}/{log.maxAttempts}</span>
+                </div>
+              </div>
+
+              {/* Expandable details */}
+              {hasDetails(log) && (
+                <>
+                  <button
+                    onClick={() => setExpandedLog(expandedLog === log.id ? null : log.id)}
+                    className="w-full flex items-center justify-between px-4 py-2.5 border-t border-gray-100 dark:border-gray-700/60 text-xs font-medium text-blue-600 dark:text-blue-400 hover:bg-gray-50 dark:hover:bg-gray-700/40 transition-colors"
+                  >
+                    <span>{expandedLog === log.id ? 'Hide Details' : 'Show Details'}</span>
+                    <svg
+                      className={`w-4 h-4 transition-transform duration-200 ${expandedLog === log.id ? 'rotate-180' : ''}`}
+                      fill="none" stroke="currentColor" viewBox="0 0 24 24"
+                    >
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
+                    </svg>
+                  </button>
+                  {expandedLog === log.id && (
+                    <div className="px-4 pb-4 pt-3 bg-gray-50 dark:bg-gray-900/50 border-t border-gray-100 dark:border-gray-700/60">
+                      <LogDetails log={log} />
+                    </div>
+                  )}
+                </>
+              )}
+            </div>
+          ))}
+          {logs.length === 0 && (
+            <div className="text-center py-12">
+              <p className="text-gray-500 dark:text-gray-400">No logs found</p>
+            </div>
+          )}
+        </div>
+
+        {/* Desktop table — hidden on mobile */}
+        <div className="hidden sm:block bg-white dark:bg-gray-800 rounded-lg shadow overflow-hidden">
           <div className="overflow-x-auto">
             <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-700">
               <thead className="bg-gray-50 dark:bg-gray-900">
@@ -253,13 +393,11 @@ export default function AdminLogsPage() {
                       </td>
                       <td className="px-6 py-4 whitespace-nowrap">
                         <div className="text-sm font-medium text-gray-900 dark:text-gray-100">
-                          {log.type.replace(/_/g, ' ').replace(/\b\w/g, (l) => l.toUpperCase())}
+                          {formatType(log.type)}
                         </div>
                       </td>
                       <td className="px-6 py-4 whitespace-nowrap">
-                        <span className={`px-2 inline-flex text-xs leading-5 font-semibold rounded-full ${getStatusBadgeColor(log.status)}`}>
-                          {log.status.toUpperCase()}
-                        </span>
+                        <StatusBadge status={log.status} />
                       </td>
                       <td className="px-6 py-4">
                         {log.request?.audiobook ? (
@@ -285,7 +423,7 @@ export default function AdminLogsPage() {
                         {log.attempts}/{log.maxAttempts}
                       </td>
                       <td className="px-6 py-4 whitespace-nowrap text-right text-sm font-medium">
-                        {(log.events.length > 0 || log.errorMessage || log.bullJobId || log.result) && (
+                        {hasDetails(log) && (
                           <button
                             onClick={() => setExpandedLog(expandedLog === log.id ? null : log.id)}
                             className="text-blue-600 hover:text-blue-900 dark:text-blue-400 dark:hover:text-blue-300"
@@ -298,63 +436,7 @@ export default function AdminLogsPage() {
                     {expandedLog === log.id && (
                       <tr>
                         <td colSpan={7} className="px-6 py-4 bg-gray-50 dark:bg-gray-900">
-                          <div className="space-y-4">
-                            {log.bullJobId && (
-                              <div>
-                                <span className="text-sm font-medium text-gray-700 dark:text-gray-300">Bull Job ID: </span>
-                                <span className="text-sm text-gray-600 dark:text-gray-400 font-mono">{log.bullJobId}</span>
-                              </div>
-                            )}
-
-                            {/* Event Logs */}
-                            {log.events.length > 0 && (
-                              <div>
-                                <h4 className="text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">Event Log</h4>
-                                <div className="space-y-1 max-h-96 overflow-y-auto bg-black/5 dark:bg-black/30 rounded p-3 font-mono text-xs">
-                                  {log.events.map((event) => {
-                                    const timestamp = new Date(event.createdAt).toISOString().split('T')[1].split('.')[0];
-                                    const levelColor = event.level === 'error'
-                                      ? 'text-red-500'
-                                      : event.level === 'warn'
-                                      ? 'text-yellow-500'
-                                      : 'text-green-500';
-
-                                    return (
-                                      <div key={event.id} className="text-gray-800 dark:text-gray-200">
-                                        <span className={levelColor}>[{event.context}]</span> {event.message}
-                                        <span className="text-gray-500 dark:text-gray-400 ml-2">{timestamp}</span>
-                                        {event.metadata && Object.keys(event.metadata).length > 0 && (
-                                          <pre className="ml-4 mt-1 text-gray-600 dark:text-gray-400 text-xs">
-                                            {JSON.stringify(event.metadata, null, 2)}
-                                          </pre>
-                                        )}
-                                      </div>
-                                    );
-                                  })}
-                                </div>
-                              </div>
-                            )}
-
-                            {/* Result Data */}
-                            {log.result && Object.keys(log.result).length > 0 && (
-                              <div>
-                                <h4 className="text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">Job Result</h4>
-                                <pre className="p-3 bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded text-xs text-blue-900 dark:text-blue-300 font-mono overflow-x-auto">
-                                  {JSON.stringify(log.result, null, 2)}
-                                </pre>
-                              </div>
-                            )}
-
-                            {/* Error Message */}
-                            {log.errorMessage && (
-                              <div>
-                                <h4 className="text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">Error</h4>
-                                <div className="p-3 bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded text-sm text-red-700 dark:text-red-300 font-mono whitespace-pre-wrap">
-                                  {log.errorMessage}
-                                </div>
-                              </div>
-                            )}
-                          </div>
+                          <LogDetails log={log} />
                         </td>
                       </tr>
                     )}
@@ -373,24 +455,31 @@ export default function AdminLogsPage() {
 
         {/* Pagination */}
         {pagination && pagination.totalPages > 1 && (
-          <div className="mt-6 flex items-center justify-between">
-            <div className="text-sm text-gray-700 dark:text-gray-300">
-              Page {pagination.page} of {pagination.totalPages} ({pagination.total} total logs)
+          <div className="mt-6 flex flex-col sm:flex-row items-center gap-3 sm:justify-between">
+            <div className="text-sm text-gray-600 dark:text-gray-400 order-2 sm:order-1">
+              Page {pagination.page} of {pagination.totalPages}
+              <span className="hidden sm:inline"> ({pagination.total} total logs)</span>
             </div>
-            <div className="flex gap-2">
+            <div className="flex gap-2 order-1 sm:order-2">
               <button
                 onClick={() => setPage(page - 1)}
                 disabled={page === 1}
-                className="px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-700 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-600 disabled:opacity-50 disabled:cursor-not-allowed"
+                className="flex items-center gap-1.5 px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-700 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-600 disabled:opacity-50 disabled:cursor-not-allowed 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 19l-7-7 7-7" />
+                </svg>
                 Previous
               </button>
               <button
                 onClick={() => setPage(page + 1)}
                 disabled={page === pagination.totalPages}
-                className="px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-700 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-600 disabled:opacity-50 disabled:cursor-not-allowed"
+                className="flex items-center gap-1.5 px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-700 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-600 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
               >
                 Next
+                <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+                </svg>
               </button>
             </div>
           </div>
@@ -403,11 +492,10 @@ export default function AdminLogsPage() {
           </h3>
           <ul className="text-sm text-blue-700 dark:text-blue-300 space-y-1">
             <li>• Logs are automatically refreshed every 10 seconds</li>
-            <li>• Click "Show Details" to view detailed event logs, job results, and error messages</li>
-            <li>• Event logs show all internal operations with timestamps (similar to Docker logs)</li>
+            <li>• Tap &quot;Show Details&quot; to view event logs, job results, and errors</li>
+            <li>• Event logs show all internal operations with timestamps</li>
             <li>• Jobs are retried automatically based on their max attempts setting</li>
             <li>• Use filters to find specific job types or statuses</li>
-            <li>• All job types are tracked: searches, downloads, file organization, library scans, RSS monitoring, and more</li>
           </ul>
         </div>
       </div>

src/app/admin/page.tsx

@@ -13,17 +13,34 @@ import { ActiveDownloadsTable } from './components/ActiveDownloadsTable';
 import { RecentRequestsTable } from './components/RecentRequestsTable';
 import { ToastProvider, useToast } from '@/components/ui/Toast';
 import { ReportedIssuesSection } from './components/ReportedIssuesSection';
+import { InteractiveTorrentSearchModal } from '@/components/requests/InteractiveTorrentSearchModal';
+import { TorrentResult } from '@/lib/utils/ranking-algorithm';
 import { formatDistanceToNow } from 'date-fns';
 import { useState } from 'react';
 
+interface SelectedTorrentData {
+  title?: string;
+  indexer?: string;
+  size?: number;
+  format?: string;
+  ebookFormat?: string;
+  seeders?: number;
+  infoUrl?: string;
+  source?: string;
+  protocol?: string;
+  score?: number;
+}
+
 interface PendingApprovalRequest {
   id: string;
   createdAt: string;
   type: 'audiobook' | 'ebook';
+  selectedTorrent: SelectedTorrentData | null;
   audiobook: {
     title: string;
     author: string;
     coverArtUrl: string | null;
+    audibleAsin: string | null;
   };
   user: {
     id: string;
@@ -32,9 +49,20 @@ interface PendingApprovalRequest {
   };
 }
 
+function formatTorrentSize(bytes: number): string {
+  const gb = bytes / (1024 ** 3);
+  const mb = bytes / (1024 ** 2);
+  return gb >= 1 ? `${gb.toFixed(1)} GB` : `${mb.toFixed(0)} MB`;
+}
+
 function PendingApprovalSection({ requests }: { requests: PendingApprovalRequest[] }) {
   const toast = useToast();
   const [loadingStates, setLoadingStates] = useState<Record<string, boolean>>({});
+  const [searchModalRequestId, setSearchModalRequestId] = useState<string | null>(null);
+
+  const searchModalRequest = searchModalRequestId
+    ? requests.find((r) => r.id === searchModalRequestId)
+    : null;
 
   const handleApproveRequest = async (requestId: string) => {
     setLoadingStates((prev) => ({ ...prev, [requestId]: true }));
@@ -47,7 +75,6 @@ function PendingApprovalSection({ requests }: { requests: PendingApprovalRequest
 
       toast.success('Request approved');
 
-      // Mutate both pending requests and recent requests caches
       await mutate('/api/admin/requests/pending-approval');
       await mutate('/api/admin/requests/recent');
       await mutate('/api/admin/metrics');
@@ -72,7 +99,6 @@ function PendingApprovalSection({ requests }: { requests: PendingApprovalRequest
 
       toast.success('Request denied');
 
-      // Mutate pending requests cache
       await mutate('/api/admin/requests/pending-approval');
       await mutate('/api/admin/metrics');
     } catch (error) {
@@ -85,6 +111,26 @@ function PendingApprovalSection({ requests }: { requests: PendingApprovalRequest
     }
   };
 
+  const handleApproveWithTorrent = async (requestId: string, torrent: TorrentResult) => {
+    await fetchJSON(`/api/admin/requests/${requestId}/approve`, {
+      method: 'POST',
+      body: JSON.stringify({ action: 'approve', selectedTorrent: torrent }),
+    });
+
+    toast.success('Request approved and download started');
+
+    await mutate('/api/admin/requests/pending-approval');
+    await mutate('/api/admin/requests/recent');
+    await mutate('/api/admin/metrics');
+  };
+
+  const LoadingSpinner = () => (
+    <svg className="animate-spin h-4 w-4" fill="none" viewBox="0 0 24 24">
+      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+      <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+    </svg>
+  );
+
   return (
     <div className="mb-8">
       {/* Section Header */}
@@ -116,6 +162,9 @@ function PendingApprovalSection({ requests }: { requests: PendingApprovalRequest
       <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
         {requests.map((request) => {
           const isLoading = loadingStates[request.id] || false;
+          const torrent = request.selectedTorrent;
+          const displayFormat = torrent?.format || torrent?.ebookFormat;
+          const isAnnasArchive = torrent?.source === 'annas_archive';
 
           return (
             <div
@@ -205,89 +254,107 @@ function PendingApprovalSection({ requests }: { requests: PendingApprovalRequest
                 </div>
               </div>
 
+              {/* Pre-Selected Release */}
+              {torrent && torrent.title && (
+                <div className="mx-4 mb-3 px-3 py-2.5 bg-gray-50 dark:bg-gray-900/60 rounded-lg border border-gray-200 dark:border-gray-700/60">
+                  <div className="flex items-center gap-1.5 mb-1">
+                    <svg className="w-3 h-3 text-gray-400 dark:text-gray-500 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13.828 10.172a4 4 0 00-5.656 0l-4 4a4 4 0 105.656 5.656l1.102-1.101m-.758-4.899a4 4 0 005.656 0l4-4a4 4 0 00-5.656-5.656l-1.1 1.1" />
+                    </svg>
+                    <span className="text-[10px] font-semibold uppercase tracking-wider text-gray-400 dark:text-gray-500">
+                      User-Selected Release
+                    </span>
+                  </div>
+                  {torrent.infoUrl ? (
+                    <a
+                      href={torrent.infoUrl}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      className="text-xs font-medium text-blue-600 dark:text-blue-400 hover:text-blue-700 dark:hover:text-blue-300 transition-colors line-clamp-2 leading-snug"
+                      title={torrent.title}
+                    >
+                      {torrent.title}
+                    </a>
+                  ) : (
+                    <p className="text-xs font-medium text-gray-700 dark:text-gray-300 line-clamp-2 leading-snug" title={torrent.title}>
+                      {torrent.title}
+                    </p>
+                  )}
+                  <div className="flex items-center gap-1 mt-1.5 text-[11px] text-gray-500 dark:text-gray-400 flex-wrap">
+                    {isAnnasArchive ? (
+                      <span className="text-orange-600 dark:text-orange-400 font-medium">Anna&apos;s Archive</span>
+                    ) : torrent.indexer ? (
+                      <span>{torrent.indexer}</span>
+                    ) : null}
+                    {torrent.size && torrent.size > 0 ? (
+                      <>
+                        <span className="text-gray-300 dark:text-gray-600 select-none">&middot;</span>
+                        <span>{formatTorrentSize(torrent.size)}</span>
+                      </>
+                    ) : null}
+                    {displayFormat ? (
+                      <>
+                        <span className="text-gray-300 dark:text-gray-600 select-none">&middot;</span>
+                        <span className="px-1 py-px text-[10px] font-semibold uppercase tracking-wide rounded bg-purple-100 dark:bg-purple-500/15 text-purple-700 dark:text-purple-300">
+                          {displayFormat}
+                        </span>
+                      </>
+                    ) : null}
+                    {torrent.protocol === 'usenet' ? (
+                      <>
+                        <span className="text-gray-300 dark:text-gray-600 select-none">&middot;</span>
+                        <span className="text-sky-600 dark:text-sky-400 font-medium">NZB</span>
+                      </>
+                    ) : torrent.seeders !== undefined && torrent.seeders !== null ? (
+                      <>
+                        <span className="text-gray-300 dark:text-gray-600 select-none">&middot;</span>
+                        <span className="text-emerald-600 dark:text-emerald-400">{torrent.seeders} seeds</span>
+                      </>
+                    ) : null}
+                    {torrent.score !== undefined && torrent.score !== null ? (
+                      <>
+                        <span className="text-gray-300 dark:text-gray-600 select-none">&middot;</span>
+                        <span className="font-medium">Score {Math.round(torrent.score)}</span>
+                      </>
+                    ) : null}
+                  </div>
+                </div>
+              )}
+
               {/* Action Buttons */}
               <div className="border-t border-amber-200 dark:border-amber-800 bg-gray-50 dark:bg-gray-900/50 px-4 py-3 flex gap-2">
                 <button
                   onClick={() => handleApproveRequest(request.id)}
                   disabled={isLoading}
-                  className="flex-1 inline-flex items-center justify-center gap-2 px-3 py-2 bg-green-600 hover:bg-green-700 disabled:bg-green-400 disabled:cursor-not-allowed text-white text-sm font-medium rounded-lg transition-colors"
+                  className="flex-1 inline-flex items-center justify-center gap-1.5 px-3 py-2 bg-green-600 hover:bg-green-700 disabled:bg-green-400 disabled:cursor-not-allowed text-white text-sm font-medium rounded-lg transition-colors"
                 >
-                  {isLoading ? (
-                    <svg
-                      className="animate-spin h-4 w-4"
-                      fill="none"
-                      viewBox="0 0 24 24"
-                    >
-                      <circle
-                        className="opacity-25"
-                        cx="12"
-                        cy="12"
-                        r="10"
-                        stroke="currentColor"
-                        strokeWidth="4"
-                      />
-                      <path
-                        className="opacity-75"
-                        fill="currentColor"
-                        d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
-                      />
-                    </svg>
-                  ) : (
-                    <svg
-                      className="w-4 h-4"
-                      fill="none"
-                      stroke="currentColor"
-                      viewBox="0 0 24 24"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={2}
-                        d="M5 13l4 4L19 7"
-                      />
+                  {isLoading ? <LoadingSpinner /> : (
+                    <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
                     </svg>
                   )}
                   <span>Approve</span>
                 </button>
 
+                <button
+                  onClick={() => setSearchModalRequestId(request.id)}
+                  disabled={isLoading}
+                  className="flex-1 inline-flex items-center justify-center gap-1.5 px-3 py-2 bg-blue-600 hover:bg-blue-700 disabled:bg-blue-400 disabled:cursor-not-allowed text-white text-sm font-medium rounded-lg 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="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+                  </svg>
+                  <span>Search</span>
+                </button>
+
                 <button
                   onClick={() => handleDenyRequest(request.id)}
                   disabled={isLoading}
-                  className="flex-1 inline-flex items-center justify-center gap-2 px-3 py-2 bg-red-600 hover:bg-red-700 disabled:bg-red-400 disabled:cursor-not-allowed text-white text-sm font-medium rounded-lg transition-colors"
+                  className="flex-1 inline-flex items-center justify-center gap-1.5 px-3 py-2 bg-red-600 hover:bg-red-700 disabled:bg-red-400 disabled:cursor-not-allowed text-white text-sm font-medium rounded-lg transition-colors"
                 >
-                  {isLoading ? (
-                    <svg
-                      className="animate-spin h-4 w-4"
-                      fill="none"
-                      viewBox="0 0 24 24"
-                    >
-                      <circle
-                        className="opacity-25"
-                        cx="12"
-                        cy="12"
-                        r="10"
-                        stroke="currentColor"
-                        strokeWidth="4"
-                      />
-                      <path
-                        className="opacity-75"
-                        fill="currentColor"
-                        d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
-                      />
-                    </svg>
-                  ) : (
-                    <svg
-                      className="w-4 h-4"
-                      fill="none"
-                      stroke="currentColor"
-                      viewBox="0 0 24 24"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={2}
-                        d="M6 18L18 6M6 6l12 12"
-                      />
+                  {isLoading ? <LoadingSpinner /> : (
+                    <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
                     </svg>
                   )}
                   <span>Deny</span>
@@ -297,6 +364,26 @@ function PendingApprovalSection({ requests }: { requests: PendingApprovalRequest
           );
         })}
       </div>
+
+      {/* Interactive Search Modal */}
+      {searchModalRequest && (
+        <InteractiveTorrentSearchModal
+          isOpen={!!searchModalRequestId}
+          onClose={() => setSearchModalRequestId(null)}
+          requestId={searchModalRequest.id}
+          audiobook={{
+            title: searchModalRequest.audiobook.title,
+            author: searchModalRequest.audiobook.author,
+          }}
+          searchMode={searchModalRequest.type === 'ebook' ? 'ebook' : 'audiobook'}
+          onConfirm={async (torrent) => {
+            await handleApproveWithTorrent(searchModalRequest.id, torrent);
+          }}
+          onSuccess={() => {
+            setSearchModalRequestId(null);
+          }}
+        />
+      )}
     </div>
   );
 }

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

@@ -100,6 +100,8 @@ export interface PathsSettings {
   ebookPathTemplate?: string;
   metadataTaggingEnabled: boolean;
   chapterMergingEnabled: boolean;
+  fileRenameEnabled: boolean;
+  fileRenameTemplate?: string;
 }
 
 /**

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/PathsTab/PathsTab.tsx

@@ -10,7 +10,7 @@ import { Button } from '@/components/ui/Button';
 import { Input } from '@/components/ui/Input';
 import { usePathsSettings } from './usePathsSettings';
 import type { PathsSettings } from '../../lib/types';
-import { validateTemplate, generateMockPreviews } from '@/lib/utils/path-template.util';
+import { validateTemplate, generateMockPreviews, validateFilenameTemplate, generateMockFilenamePreviews } from '@/lib/utils/path-template.util';
 
 interface PathsTabProps {
   paths: PathsSettings;
@@ -24,6 +24,13 @@ interface TemplatePreview {
   previewPaths?: string[];
 }
 
+interface FilenamePreview {
+  isValid: boolean;
+  error?: string;
+  single?: string[];
+  multi?: string[];
+}
+
 export function PathsTab({ paths, onChange, onValidationChange }: PathsTabProps) {
   const { testing, testResult, updatePath, testPaths } = usePathsSettings({
     paths,
@@ -73,6 +80,34 @@ export function PathsTab({ paths, onChange, onValidationChange }: PathsTabProps)
     }
   }, [paths.ebookPathTemplate]);
 
+  // Live preview state for filename template
+  const [filenamePreview, setFilenamePreview] = useState<FilenamePreview | null>(null);
+
+  // Update filename live preview whenever template changes
+  useEffect(() => {
+    if (!paths.fileRenameEnabled) {
+      setFilenamePreview(null);
+      return;
+    }
+
+    const template = paths.fileRenameTemplate || '{title}';
+    const validation = validateFilenameTemplate(template);
+
+    if (validation.valid) {
+      const previews = generateMockFilenamePreviews(template);
+      setFilenamePreview({
+        isValid: true,
+        single: previews.single,
+        multi: previews.multi,
+      });
+    } else {
+      setFilenamePreview({
+        isValid: false,
+        error: validation.error,
+      });
+    }
+  }, [paths.fileRenameTemplate, paths.fileRenameEnabled]);
+
   const audiobookTemplate = paths.audiobookPathTemplate || '{author}/{title} {asin}';
   const ebookTemplate = paths.ebookPathTemplate || '{author}/{title} {asin}';
   const ebookMatchesAudiobook = ebookTemplate === audiobookTemplate;
@@ -218,6 +253,83 @@ export function PathsTab({ paths, onChange, onValidationChange }: PathsTabProps)
         )}
       </div>
 
+      {/* File Rename Toggle */}
+      <div className="bg-gray-50 dark:bg-gray-800 rounded-lg p-4 border border-gray-200 dark:border-gray-700">
+        <div className="flex items-start gap-4">
+          <input
+            type="checkbox"
+            id="file-rename-settings"
+            checked={paths.fileRenameEnabled}
+            onChange={(e) => updatePath('fileRenameEnabled', e.target.checked)}
+            className="mt-1 h-5 w-5 rounded border-gray-300 text-blue-600 focus:ring-blue-500"
+          />
+          <div className="flex-1">
+            <label
+              htmlFor="file-rename-settings"
+              className="block text-sm font-medium text-gray-900 dark:text-gray-100 cursor-pointer"
+            >
+              Rename files during organization
+            </label>
+            <p className="text-sm text-gray-600 dark:text-gray-400 mt-1">
+              Rename audio and ebook files using a custom naming template when organizing into the media
+              library. When multiple files exist (e.g. chapterized MP3s), an index number is appended.
+            </p>
+          </div>
+        </div>
+
+        {/* File Naming Template (shown when enabled) */}
+        {paths.fileRenameEnabled && (
+          <div className="mt-4 pl-9">
+            <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
+              File Naming Template
+            </label>
+            <Input
+              type="text"
+              value={paths.fileRenameTemplate || '{title}'}
+              onChange={(e) => updatePath('fileRenameTemplate', e.target.value)}
+              placeholder="{title}"
+              className="font-mono"
+            />
+            <p className="text-sm text-gray-500 dark:text-gray-400 mt-1">
+              Uses the same variables as the organization template. Do not include the file extension.
+            </p>
+
+            {/* Filename Validation Error */}
+            {filenamePreview && !filenamePreview.isValid && (
+              <div className="mt-3 p-3 rounded-lg text-sm flex items-start gap-2 bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 text-red-800 dark:text-red-200">
+                <span className="flex-shrink-0 mt-0.5">✗</span>
+                <div className="flex-1">
+                  <span>{filenamePreview.error || 'Invalid filename template'}</span>
+                </div>
+              </div>
+            )}
+
+            {/* Filename Preview */}
+            {filenamePreview && filenamePreview.isValid && (
+              <div className="mt-3 bg-gray-50 dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg p-4">
+                <h4 className="text-sm font-semibold text-gray-900 dark:text-gray-100 mb-2">
+                  Single File
+                </h4>
+                <div className="space-y-1.5 text-sm font-mono text-gray-700 dark:text-gray-300">
+                  {filenamePreview.single?.map((preview, index) => (
+                    <div key={index} className="text-xs">{preview}</div>
+                  ))}
+                </div>
+
+                <h4 className="text-sm font-semibold text-gray-900 dark:text-gray-100 mt-3 mb-2">
+                  Multiple Files (chapterized)
+                </h4>
+                <div className="space-y-1.5 text-sm font-mono text-gray-700 dark:text-gray-300">
+                  {filenamePreview.multi?.map((preview, index) => (
+                    <div key={index} className="text-xs">{preview}</div>
+                  ))}
+                </div>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+
       {/* Variable Reference Panel (shared for both templates) */}
       <div className="bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-lg p-4">
         <h3 className="text-sm font-semibold text-blue-900 dark:text-blue-100 mb-3">
@@ -255,6 +367,27 @@ export function PathsTab({ paths, onChange, onValidationChange }: PathsTabProps)
         </div>
       </div>
 
+      {/* Conditional Syntax Help */}
+      <div className="bg-amber-50 dark:bg-amber-900/20 border border-amber-200 dark:border-amber-800 rounded-lg p-4">
+        <h3 className="text-sm font-semibold text-amber-900 dark:text-amber-100 mb-2">
+          Conditional Syntax
+        </h3>
+        <p className="text-sm text-gray-600 dark:text-gray-400 mb-2">
+          Wrap text around a variable in <code className="text-amber-700 dark:text-amber-300 font-mono">{'{ }'}</code> to
+          include that text only when the variable has a value. If the variable is empty, the entire block is removed.
+        </p>
+        <div className="text-sm font-mono bg-white dark:bg-gray-900 rounded px-3 py-2 border border-amber-100 dark:border-amber-900">
+          <div className="text-gray-700 dark:text-gray-300">
+            <code className="text-amber-700 dark:text-amber-300">{'{Book seriesPart - }'}</code>
+          </div>
+          <div className="text-xs text-gray-500 dark:text-gray-400 mt-1">
+            With value: <span className="text-green-700 dark:text-green-400">Book 1 - </span>
+            &nbsp;&bull;&nbsp;
+            Without value: <span className="text-red-700 dark:text-red-400">(removed)</span>
+          </div>
+        </div>
+      </div>
+
       {/* Metadata Tagging Toggle */}
       <div className="bg-gray-50 dark:bg-gray-800 rounded-lg p-4 border border-gray-200 dark:border-gray-700">
         <div className="flex items-start gap-4">

src/app/admin/users/page.tsx

@@ -28,6 +28,7 @@ interface User {
   lastLoginAt: string | null;
   autoApproveRequests: boolean | null;
   interactiveSearchAccess: boolean | null;
+  downloadAccess: boolean | null;
   _count: {
     requests: number;
   };
@@ -41,6 +42,144 @@ interface PendingUser {
   createdAt: string;
 }
 
+// Tinted-dot status badge following admin design system
+function RoleBadge({ role, isSetupAdmin }: { role: 'user' | 'admin'; isSetupAdmin: boolean }) {
+  if (isSetupAdmin) {
+    return (
+      <span className="inline-flex items-center gap-1.5 px-2.5 py-0.5 rounded-full text-xs font-medium bg-blue-500/10 text-blue-700 dark:text-blue-400">
+        <span className="w-1.5 h-1.5 rounded-full flex-shrink-0 bg-blue-500" />
+        Setup Admin
+      </span>
+    );
+  }
+  if (role === 'admin') {
+    return (
+      <span className="inline-flex items-center gap-1.5 px-2.5 py-0.5 rounded-full text-xs font-medium bg-purple-500/10 text-purple-700 dark:text-purple-400">
+        <span className="w-1.5 h-1.5 rounded-full flex-shrink-0 bg-purple-500" />
+        Admin
+      </span>
+    );
+  }
+  return (
+    <span className="inline-flex items-center gap-1.5 px-2.5 py-0.5 rounded-full text-xs font-medium bg-gray-500/10 text-gray-600 dark:text-gray-400">
+      <span className="w-1.5 h-1.5 rounded-full flex-shrink-0 bg-gray-400" />
+      User
+    </span>
+  );
+}
+
+function PermissionBadge({
+  user,
+  globalAutoApprove,
+  onClick,
+}: {
+  user: User;
+  globalAutoApprove: boolean;
+  onClick: () => void;
+}) {
+  let badge: React.ReactNode;
+  if (user.role === 'admin') {
+    badge = (
+      <span className="inline-flex items-center gap-1 px-2 py-0.5 text-xs font-medium rounded-full bg-purple-500/10 text-purple-700 dark:text-purple-400">
+        <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
+        </svg>
+        Full Access
+      </span>
+    );
+  } else if (globalAutoApprove) {
+    badge = (
+      <span className="inline-flex items-center gap-1 px-2 py-0.5 text-xs font-medium rounded-full bg-blue-500/10 text-blue-700 dark:text-blue-400">
+        Global Default
+      </span>
+    );
+  } else if (user.autoApproveRequests ?? false) {
+    badge = (
+      <span className="inline-flex items-center gap-1 px-2 py-0.5 text-xs font-medium rounded-full bg-emerald-500/10 text-emerald-700 dark:text-emerald-400">
+        Auto-Approve
+      </span>
+    );
+  } else {
+    badge = (
+      <span className="inline-flex items-center gap-1 px-2 py-0.5 text-xs font-medium rounded-full bg-gray-500/10 text-gray-600 dark:text-gray-400">
+        Manual
+      </span>
+    );
+  }
+
+  return (
+    <button
+      onClick={onClick}
+      className="inline-flex items-center gap-1.5 text-sm transition-opacity hover:opacity-70"
+    >
+      {badge}
+      <svg className="w-3.5 h-3.5 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+      </svg>
+    </button>
+  );
+}
+
+function UserActionsCell({ user, onEdit, onDelete }: { user: User; onEdit: (u: User) => void; onDelete: (u: User) => void }) {
+  if (user.isSetupAdmin) {
+    return (
+      <span className="inline-flex items-center gap-1 text-gray-400 dark:text-gray-600 cursor-not-allowed" title="Setup admin role cannot be changed">
+        <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
+        </svg>
+        <span>Protected</span>
+      </span>
+    );
+  }
+  if (user.authProvider === 'oidc') {
+    return (
+      <span className="inline-flex items-center gap-1 text-gray-400 dark:text-gray-600 cursor-not-allowed" title="OIDC user roles are managed by the identity provider">
+        <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+        </svg>
+        <span>OIDC Managed</span>
+      </span>
+    );
+  }
+  if (user.authProvider === 'local') {
+    return (
+      <div className="flex items-center gap-3">
+        <button
+          onClick={() => onEdit(user)}
+          className="inline-flex items-center gap-1 text-blue-600 hover:text-blue-900 dark:text-blue-400 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="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>Edit Role</span>
+        </button>
+        <button
+          onClick={() => onDelete(user)}
+          className="inline-flex items-center gap-1 text-red-600 hover:text-red-900 dark:text-red-400 dark:hover:text-red-300 transition-colors"
+          title="Delete user and all their requests"
+        >
+          <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16" />
+          </svg>
+          <span>Delete</span>
+        </button>
+      </div>
+    );
+  }
+  // plex or other
+  return (
+    <button
+      onClick={() => onEdit(user)}
+      className="inline-flex items-center gap-1 text-blue-600 hover:text-blue-900 dark:text-blue-400 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="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>Edit Role</span>
+    </button>
+  );
+}
+
 function AdminUsersPageContent() {
   const { data, error, mutate } = useSWR('/api/admin/users', authenticatedFetcher);
   const { data: pendingData, error: pendingError, mutate: mutatePending } = useSWR(
@@ -55,6 +194,10 @@ function AdminUsersPageContent() {
     '/api/admin/settings/interactive-search',
     authenticatedFetcher
   );
+  const { data: globalDownloadAccessData, mutate: mutateGlobalDownloadAccess } = useSWR(
+    '/api/admin/settings/download-access',
+    authenticatedFetcher
+  );
   const [editDialog, setEditDialog] = useState<{
     isOpen: boolean;
     user: User | null;
@@ -74,6 +217,7 @@ function AdminUsersPageContent() {
   const [deleting, setDeleting] = useState(false);
   const [globalAutoApprove, setGlobalAutoApprove] = useState<boolean>(false);
   const [globalInteractiveSearch, setGlobalInteractiveSearch] = useState<boolean>(true);
+  const [globalDownloadAccess, setGlobalDownloadAccess] = useState<boolean>(true);
   const [globalSettingsOpen, setGlobalSettingsOpen] = useState(false);
   const [permissionsUserId, setPermissionsUserId] = useState<string | null>(null);
   const toast = useToast();
@@ -86,7 +230,6 @@ function AdminUsersPageContent() {
     if (globalAutoApproveData?.autoApproveRequests !== undefined) {
       setGlobalAutoApprove(globalAutoApproveData.autoApproveRequests);
     } else if (globalAutoApproveData !== undefined && globalAutoApproveData.autoApproveRequests === undefined) {
-      // API returned but no value - default to true
       setGlobalAutoApprove(true);
     }
   }, [globalAutoApproveData]);
@@ -100,10 +243,17 @@ function AdminUsersPageContent() {
     }
   }, [globalInteractiveSearchData]);
 
-  const handleGlobalAutoApproveToggle = async (newValue: boolean) => {
-    // Optimistic update
-    setGlobalAutoApprove(newValue);
+  // Sync global download access state (default to true if not set)
+  useEffect(() => {
+    if (globalDownloadAccessData?.downloadAccess !== undefined) {
+      setGlobalDownloadAccess(globalDownloadAccessData.downloadAccess);
+    } else if (globalDownloadAccessData !== undefined && globalDownloadAccessData.downloadAccess === undefined) {
+      setGlobalDownloadAccess(true);
+    }
+  }, [globalDownloadAccessData]);
 
+  const handleGlobalAutoApproveToggle = async (newValue: boolean) => {
+    setGlobalAutoApprove(newValue);
     try {
       await fetchJSON('/api/admin/settings/auto-approve', {
         method: 'PATCH',
@@ -111,20 +261,16 @@ function AdminUsersPageContent() {
       });
       toast.success(`Global auto-approve ${newValue ? 'enabled' : 'disabled'}`);
       mutateGlobalAutoApprove();
-      mutate(); // Refresh users list to show updated state
+      mutate();
     } catch (err) {
-      // Revert on error
       setGlobalAutoApprove(!newValue);
       const errorMsg = err instanceof Error ? err.message : 'Failed to update auto-approve setting';
       toast.error(errorMsg);
-      console.error(err);
     }
   };
 
   const handleGlobalInteractiveSearchToggle = async (newValue: boolean) => {
-    // Optimistic update
     setGlobalInteractiveSearch(newValue);
-
     try {
       await fetchJSON('/api/admin/settings/interactive-search', {
         method: 'PATCH',
@@ -132,74 +278,88 @@ function AdminUsersPageContent() {
       });
       toast.success(`Global interactive search ${newValue ? 'enabled' : 'disabled'}`);
       mutateGlobalInteractiveSearch();
-      mutate(); // Refresh users list to show updated state
+      mutate();
     } catch (err) {
-      // Revert on error
       setGlobalInteractiveSearch(!newValue);
       const errorMsg = err instanceof Error ? err.message : 'Failed to update interactive search setting';
       toast.error(errorMsg);
-      console.error(err);
     }
   };
 
   const handleUserAutoApproveToggle = async (user: User, newValue: boolean) => {
-    console.log('[AutoApprove] Toggle clicked:', { userId: user.id, username: user.plexUsername, newValue });
-
-    // Optimistic update
     const previousUsers = data?.users || [];
     const optimisticUsers = previousUsers.map((u: User) =>
       u.id === user.id ? { ...u, autoApproveRequests: newValue } : u
     );
-    console.log('[AutoApprove] Applying optimistic update');
     mutate({ users: optimisticUsers }, false);
-
     try {
-      console.log('[AutoApprove] Sending API request...');
-      const response = await fetchJSON(`/api/admin/users/${user.id}`, {
+      await fetchJSON(`/api/admin/users/${user.id}`, {
         method: 'PUT',
-        body: JSON.stringify({
-          role: user.role,
-          autoApproveRequests: newValue
-        }),
+        body: JSON.stringify({ role: user.role, autoApproveRequests: newValue }),
       });
-      console.log('[AutoApprove] API response received:', response);
       toast.success(`Auto-approve ${newValue ? 'enabled' : 'disabled'} for ${user.plexUsername}`);
-      console.log('[AutoApprove] Triggering cache revalidation...');
-      mutate(); // Refresh users list
+      mutate();
     } catch (err) {
-      // Revert on error
-      console.error('[AutoApprove] Error occurred, reverting:', err);
       mutate({ users: previousUsers }, false);
       const errorMsg = err instanceof Error ? err.message : 'Failed to update user auto-approve setting';
       toast.error(errorMsg);
-      console.error(err);
     }
   };
 
   const handleUserInteractiveSearchToggle = async (user: User, newValue: boolean) => {
-    // Optimistic update
     const previousUsers = data?.users || [];
     const optimisticUsers = previousUsers.map((u: User) =>
       u.id === user.id ? { ...u, interactiveSearchAccess: newValue } : u
     );
     mutate({ users: optimisticUsers }, false);
-
     try {
       await fetchJSON(`/api/admin/users/${user.id}`, {
         method: 'PUT',
-        body: JSON.stringify({
-          role: user.role,
-          interactiveSearchAccess: newValue
-        }),
+        body: JSON.stringify({ role: user.role, interactiveSearchAccess: newValue }),
       });
       toast.success(`Interactive search ${newValue ? 'enabled' : 'disabled'} for ${user.plexUsername}`);
-      mutate(); // Refresh users list
+      mutate();
     } catch (err) {
-      // Revert on error
       mutate({ users: previousUsers }, false);
       const errorMsg = err instanceof Error ? err.message : 'Failed to update user interactive search setting';
       toast.error(errorMsg);
-      console.error(err);
+    }
+  };
+
+  const handleGlobalDownloadAccessToggle = async (newValue: boolean) => {
+    setGlobalDownloadAccess(newValue);
+    try {
+      await fetchJSON('/api/admin/settings/download-access', {
+        method: 'PATCH',
+        body: JSON.stringify({ downloadAccess: newValue }),
+      });
+      toast.success(`Global download access ${newValue ? 'enabled' : 'disabled'}`);
+      mutateGlobalDownloadAccess();
+      mutate();
+    } catch (err) {
+      setGlobalDownloadAccess(!newValue);
+      const errorMsg = err instanceof Error ? err.message : 'Failed to update download access setting';
+      toast.error(errorMsg);
+    }
+  };
+
+  const handleUserDownloadAccessToggle = async (user: User, newValue: boolean) => {
+    const previousUsers = data?.users || [];
+    const optimisticUsers = previousUsers.map((u: User) =>
+      u.id === user.id ? { ...u, downloadAccess: newValue } : u
+    );
+    mutate({ users: optimisticUsers }, false);
+    try {
+      await fetchJSON(`/api/admin/users/${user.id}`, {
+        method: 'PUT',
+        body: JSON.stringify({ role: user.role, downloadAccess: newValue }),
+      });
+      toast.success(`Download access ${newValue ? 'enabled' : 'disabled'} for ${user.plexUsername}`);
+      mutate();
+    } catch (err) {
+      mutate({ users: previousUsers }, false);
+      const errorMsg = err instanceof Error ? err.message : 'Failed to update user download access setting';
+      toast.error(errorMsg);
     }
   };
 
@@ -214,7 +374,6 @@ function AdminUsersPageContent() {
 
   const saveUserRole = async () => {
     if (!editDialog.user) return;
-
     try {
       setSaving(true);
       await fetchJSON(`/api/admin/users/${editDialog.user.id}`, {
@@ -223,11 +382,10 @@ function AdminUsersPageContent() {
       });
       toast.success(`User "${editDialog.user.plexUsername}" updated successfully`);
       hideEditDialog();
-      mutate(); // Refresh users list
+      mutate();
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : 'Failed to update user';
       toast.error(errorMsg);
-      console.error(err);
     } finally {
       setSaving(false);
     }
@@ -242,13 +400,12 @@ function AdminUsersPageContent() {
   };
 
   const closeConfirmDialog = () => {
-    if (processingUserId) return; // Don't close while processing
+    if (processingUserId) return;
     setConfirmDialog({ isOpen: false, type: null, user: null });
   };
 
   const handleConfirmAction = async () => {
     if (!confirmDialog.user) return;
-
     const isApprove = confirmDialog.type === 'approve';
     try {
       setProcessingUserId(confirmDialog.user.id);
@@ -261,13 +418,12 @@ function AdminUsersPageContent() {
           ? `User "${confirmDialog.user.plexUsername}" has been approved`
           : `User "${confirmDialog.user.plexUsername}" has been rejected`
       );
-      mutatePending(); // Refresh pending users list
-      if (isApprove) mutate(); // Refresh approved users list
+      mutatePending();
+      if (isApprove) mutate();
       closeConfirmDialog();
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : `Failed to ${isApprove ? 'approve' : 'reject'} user`;
       toast.error(errorMsg);
-      console.error(err);
     } finally {
       setProcessingUserId(null);
     }
@@ -278,25 +434,23 @@ function AdminUsersPageContent() {
   };
 
   const closeDeleteDialog = () => {
-    if (deleting) return; // Don't close while processing
+    if (deleting) return;
     setDeleteDialog({ isOpen: false, user: null });
   };
 
   const handleDeleteUser = async () => {
     if (!deleteDialog.user) return;
-
     try {
       setDeleting(true);
       const response = await fetchJSON(`/api/admin/users/${deleteDialog.user.id}`, {
         method: 'DELETE',
       });
       toast.success(response.message || `User "${deleteDialog.user.plexUsername}" has been deleted`);
-      mutate(); // Refresh users list
+      mutate();
       closeDeleteDialog();
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : 'Failed to delete user';
       toast.error(errorMsg);
-      console.error(err);
     } finally {
       setDeleting(false);
     }
@@ -307,7 +461,6 @@ function AdminUsersPageContent() {
       await navigator.clipboard.writeText(text);
       toast.success(`${label} copied to clipboard`);
     } catch (err) {
-      console.error('Failed to copy to clipboard:', err);
       toast.error('Failed to copy to clipboard');
     }
   };
@@ -327,9 +480,7 @@ function AdminUsersPageContent() {
       <div className="min-h-screen bg-gray-50 dark:bg-gray-900 p-8">
         <div className="max-w-7xl mx-auto">
           <div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg p-4">
-            <h3 className="text-sm font-medium text-red-800 dark:text-red-200">
-              Error Loading Users
-            </h3>
+            <h3 className="text-sm font-medium text-red-800 dark:text-red-200">Error Loading Users</h3>
             <p className="text-sm text-red-700 dark:text-red-300 mt-1">
               {error?.message || 'Failed to load users'}
             </p>
@@ -344,80 +495,81 @@ function AdminUsersPageContent() {
 
   return (
     <div className="min-h-screen bg-gray-50 dark:bg-gray-900">
-      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
-        {/* Header */}
-        <div className="sticky top-0 z-10 mb-8 flex items-center justify-between bg-gray-50 dark:bg-gray-900 py-4 -mx-4 px-4 sm:-mx-6 sm:px-6 lg:-mx-8 lg:px-8 border-b border-gray-200 dark:border-gray-800">
-          <div>
-            <h1 className="text-3xl font-bold text-gray-900 dark:text-gray-100">
-              User Management
-            </h1>
-            <p className="text-gray-600 dark:text-gray-400 mt-2">
-              Manage user roles and permissions
-            </p>
-          </div>
-          <div className="flex items-center gap-3">
-            <button
-              onClick={() => setGlobalSettingsOpen(true)}
-              className="inline-flex items-center gap-2 px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white rounded-lg transition-colors"
-            >
-              <svg className="w-5 h-5" 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>
-              <span>Global User Permissions</span>
-            </button>
-            <Link
-              href="/admin"
-              className="inline-flex items-center gap-2 px-4 py-2 bg-gray-200 dark:bg-gray-700 hover:bg-gray-300 dark:hover:bg-gray-600 text-gray-900 dark:text-gray-100 rounded-lg transition-colors"
-            >
-              <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 19l-7-7m0 0l7-7m-7 7h18" />
-              </svg>
-              <span>Back to Dashboard</span>
-            </Link>
+      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-6 sm:py-8">
+
+        {/* Header — stacks on mobile, row on sm+ */}
+        <div className="sticky top-0 z-10 mb-6 sm:mb-8 bg-gray-50 dark:bg-gray-900 py-4 -mx-4 px-4 sm:-mx-6 sm:px-6 lg:-mx-8 lg:px-8 border-b border-gray-200 dark:border-gray-800">
+          <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+            <div>
+              <h1 className="text-2xl sm:text-3xl font-bold text-gray-900 dark:text-gray-100">
+                User Management
+              </h1>
+              <p className="text-sm text-gray-600 dark:text-gray-400 mt-1">
+                Manage user roles and permissions
+              </p>
+            </div>
+            <div className="flex items-center gap-2 self-start sm:self-auto flex-shrink-0">
+              <button
+                onClick={() => setGlobalSettingsOpen(true)}
+                className="inline-flex items-center gap-2 px-3 sm:px-4 py-2.5 bg-blue-600 hover:bg-blue-700 text-white rounded-lg transition-colors text-sm font-medium"
+              >
+                <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>
+                <span className="hidden sm:inline">Global User Permissions</span>
+                <span className="sm:hidden">Permissions</span>
+              </button>
+              <Link
+                href="/admin"
+                className="inline-flex items-center gap-2 px-3 sm:px-4 py-2.5 bg-gray-200 dark:bg-gray-700 hover:bg-gray-300 dark:hover:bg-gray-600 text-gray-900 dark:text-gray-100 rounded-lg transition-colors text-sm font-medium"
+              >
+                <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 19l-7-7m0 0l7-7m-7 7h18" />
+                </svg>
+                <span>Back</span>
+              </Link>
+            </div>
           </div>
         </div>
 
         {/* Pending Users Section */}
         {pendingUsers.length > 0 && (
-          <div className="mb-8">
-            <div className="bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 rounded-lg p-4 mb-4">
-              <h2 className="text-lg font-semibold text-yellow-900 dark:text-yellow-200 mb-4 flex items-center gap-2">
-                <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <div className="mb-6 sm:mb-8">
+            <div className="bg-amber-50 dark:bg-amber-900/10 border border-amber-200 dark:border-amber-800/60 rounded-xl p-4">
+              <h2 className="text-base font-semibold text-amber-900 dark:text-amber-200 mb-1 flex items-center gap-2">
+                <svg className="w-4 h-4 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                   <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
                 </svg>
                 Pending Registrations ({pendingUsers.length})
               </h2>
-              <p className="text-sm text-yellow-800 dark:text-yellow-300 mb-4">
+              <p className="text-xs text-amber-700 dark:text-amber-300/80 mb-4">
                 The following users are awaiting approval to access the system.
               </p>
               <div className="space-y-3">
                 {pendingUsers.map((user) => (
                   <div
                     key={user.id}
-                    className="bg-white dark:bg-gray-800 border border-yellow-200 dark:border-yellow-800 rounded-lg p-4 flex items-center justify-between"
+                    className="bg-white dark:bg-gray-800 border border-amber-200 dark:border-amber-800/40 rounded-xl overflow-hidden"
                   >
-                    <div className="flex-1">
-                      <div className="flex items-center gap-3">
-                        <div>
-                          <div className="font-medium text-gray-900 dark:text-gray-100">
-                            {user.plexUsername}
-                          </div>
-                          <div className="text-sm text-gray-500 dark:text-gray-400">
-                            {user.plexEmail || 'No email'}
-                          </div>
-                          <div className="text-xs text-gray-400 dark:text-gray-500 mt-1">
-                            Registered: {new Date(user.createdAt).toLocaleString()} •
-                            Provider: {user.authProvider}
-                          </div>
-                        </div>
+                    {/* Pending card — info */}
+                    <div className="px-4 py-3">
+                      <div className="font-medium text-gray-900 dark:text-gray-100 text-sm">
+                        {user.plexUsername}
+                      </div>
+                      <div className="text-sm text-gray-500 dark:text-gray-400">
+                        {user.plexEmail || 'No email'}
+                      </div>
+                      <div className="text-xs text-gray-400 dark:text-gray-500 mt-1">
+                        Registered: {new Date(user.createdAt).toLocaleString()} &middot; Provider: {user.authProvider}
                       </div>
                     </div>
-                    <div className="flex items-center gap-2">
+                    {/* Pending card — actions, full-width on mobile */}
+                    <div className="px-4 py-3 border-t border-amber-100 dark:border-amber-800/30 flex gap-2">
                       <button
                         onClick={() => showApproveDialog(user)}
                         disabled={processingUserId === user.id}
-                        className="px-4 py-2 bg-green-600 hover:bg-green-700 text-white text-sm font-medium rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed flex items-center gap-2"
+                        className="flex-1 inline-flex items-center justify-center gap-2 px-3 py-2.5 bg-emerald-50 dark:bg-emerald-500/10 hover:bg-emerald-100 dark:hover:bg-emerald-500/20 text-emerald-700 dark:text-emerald-400 border border-emerald-200/60 dark:border-emerald-500/20 rounded-xl text-sm font-medium transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
                       >
                         <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                           <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
@@ -427,7 +579,7 @@ function AdminUsersPageContent() {
                       <button
                         onClick={() => showRejectDialog(user)}
                         disabled={processingUserId === user.id}
-                        className="px-4 py-2 bg-red-600 hover:bg-red-700 text-white text-sm font-medium rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed flex items-center gap-2"
+                        className="flex-1 inline-flex items-center justify-center gap-2 px-3 py-2.5 bg-red-50 dark:bg-red-500/10 hover:bg-red-100 dark:hover:bg-red-500/20 text-red-700 dark:text-red-400 border border-red-200/60 dark:border-red-500/20 rounded-xl text-sm font-medium transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
                       >
                         <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                           <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
@@ -442,8 +594,104 @@ function AdminUsersPageContent() {
           </div>
         )}
 
-        {/* Users Table */}
-        <div className="bg-white dark:bg-gray-800 rounded-lg shadow overflow-x-auto">
+        {/* Users — Mobile card list (sm:hidden) */}
+        <div className="space-y-3 sm:hidden">
+          {users.map((user) => (
+            <div
+              key={user.id}
+              className="bg-white dark:bg-gray-800 rounded-xl border border-gray-200 dark:border-gray-700 overflow-hidden"
+            >
+              {/* Card header — avatar + name + role badge */}
+              <div className="px-4 py-3 flex items-start gap-3">
+                {user.avatarUrl ? (
+                  <img
+                    src={user.avatarUrl}
+                    alt={user.plexUsername}
+                    className="h-10 w-10 rounded-full flex-shrink-0 mt-0.5"
+                  />
+                ) : (
+                  <div className="h-10 w-10 rounded-full flex-shrink-0 mt-0.5 bg-gray-200 dark:bg-gray-700 flex items-center justify-center">
+                    <svg className="w-5 h-5 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z" />
+                    </svg>
+                  </div>
+                )}
+                <div className="flex-1 min-w-0">
+                  <div className="flex items-start justify-between gap-2">
+                    <div className="font-semibold text-gray-900 dark:text-gray-100 text-sm leading-snug truncate">
+                      {user.plexUsername}
+                    </div>
+                    <RoleBadge role={user.role} isSetupAdmin={user.isSetupAdmin} />
+                  </div>
+                  <div className="text-xs text-gray-500 dark:text-gray-400 mt-0.5 truncate">
+                    {user.plexEmail || 'No email'}
+                  </div>
+                </div>
+              </div>
+
+              {/* Card body — labeled fields */}
+              <div className="px-4 pb-3 pt-2 space-y-2 border-t border-gray-100 dark:border-gray-700/60">
+                <div className="grid grid-cols-2 gap-2">
+                  <div>
+                    <div className="text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-0.5">
+                      Permissions
+                    </div>
+                    <PermissionBadge
+                      user={user}
+                      globalAutoApprove={globalAutoApprove}
+                      onClick={() => setPermissionsUserId(user.id)}
+                    />
+                  </div>
+                  <div>
+                    <div className="text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-0.5">
+                      Requests
+                    </div>
+                    <div className="text-sm text-gray-900 dark:text-gray-100">
+                      {user._count.requests}
+                    </div>
+                  </div>
+                </div>
+                <div>
+                  <div className="text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-0.5">
+                    Last Login
+                  </div>
+                  <div className="text-sm text-gray-700 dark:text-gray-300">
+                    {user.lastLoginAt
+                      ? new Date(user.lastLoginAt).toLocaleDateString()
+                      : 'Never'}
+                  </div>
+                </div>
+                <div>
+                  <div className="text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-0.5">
+                    User ID
+                  </div>
+                  <button
+                    onClick={() => copyToClipboard(user.plexId, 'User ID')}
+                    className="text-xs text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-300 transition-colors inline-flex items-center gap-1"
+                  >
+                    <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+                    </svg>
+                    {user.plexId.length > 16 ? `${user.plexId.substring(0, 16)}…` : user.plexId}
+                  </button>
+                </div>
+              </div>
+
+              {/* Card actions */}
+              <div className="px-4 py-3 border-t border-gray-100 dark:border-gray-700/60">
+                <UserActionsCell user={user} onEdit={showEditDialog} onDelete={showDeleteDialog} />
+              </div>
+            </div>
+          ))}
+          {users.length === 0 && (
+            <div className="text-center py-12">
+              <p className="text-gray-500 dark:text-gray-400">No users found</p>
+            </div>
+          )}
+        </div>
+
+        {/* Users Table — hidden on mobile, visible on sm+ */}
+        <div className="hidden sm:block bg-white dark:bg-gray-800 rounded-lg shadow overflow-x-auto">
           <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-700">
             <thead className="bg-gray-50 dark:bg-gray-900">
               <tr>
@@ -472,15 +720,21 @@ function AdminUsersPageContent() {
             </thead>
             <tbody className="bg-white dark:bg-gray-800 divide-y divide-gray-200 dark:divide-gray-700">
               {users.map((user) => (
-                <tr key={user.id}>
+                <tr key={user.id} className="hover:bg-gray-50 dark:hover:bg-gray-700/40 transition-colors">
                   <td className="px-6 py-4 whitespace-nowrap">
                     <div className="flex items-center">
-                      {user.avatarUrl && (
+                      {user.avatarUrl ? (
                         <img
                           src={user.avatarUrl}
                           alt={user.plexUsername}
-                          className="h-10 w-10 rounded-full mr-3"
+                          className="h-10 w-10 rounded-full mr-3 flex-shrink-0"
                         />
+                      ) : (
+                        <div className="h-10 w-10 rounded-full mr-3 flex-shrink-0 bg-gray-200 dark:bg-gray-700 flex items-center justify-center">
+                          <svg className="w-5 h-5 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z" />
+                          </svg>
+                        </div>
                       )}
                       <div>
                         <div className="text-sm font-medium text-gray-900 dark:text-gray-100">
@@ -507,52 +761,14 @@ function AdminUsersPageContent() {
                     </div>
                   </td>
                   <td className="px-6 py-4 whitespace-nowrap">
-                    <div className="flex items-center gap-2">
-                      <span
-                        className={`px-2 inline-flex text-xs leading-5 font-semibold rounded-full ${
-                          user.role === 'admin'
-                            ? 'bg-purple-100 text-purple-800 dark:bg-purple-900/30 dark:text-purple-400'
-                            : 'bg-gray-100 text-gray-800 dark:bg-gray-700 dark:text-gray-400'
-                        }`}
-                      >
-                        {user.role.toUpperCase()}
-                      </span>
-                      {user.isSetupAdmin && (
-                        <span className="px-2 inline-flex text-xs leading-5 font-semibold rounded-full bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400">
-                          SETUP ADMIN
-                        </span>
-                      )}
-                    </div>
+                    <RoleBadge role={user.role} isSetupAdmin={user.isSetupAdmin} />
                   </td>
                   <td className="px-6 py-4 whitespace-nowrap">
-                    <button
+                    <PermissionBadge
+                      user={user}
+                      globalAutoApprove={globalAutoApprove}
                       onClick={() => setPermissionsUserId(user.id)}
-                      className="inline-flex items-center gap-1.5 text-sm text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-300 transition-colors"
-                    >
-                      {user.role === 'admin' ? (
-                        <span className="inline-flex items-center gap-1 px-2 py-0.5 text-xs font-medium rounded-full bg-purple-100 text-purple-700 dark:bg-purple-900/30 dark:text-purple-400">
-                          <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
-                          </svg>
-                          Full Access
-                        </span>
-                      ) : globalAutoApprove ? (
-                        <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/30 dark:text-blue-400">
-                          Global Default
-                        </span>
-                      ) : (user.autoApproveRequests ?? false) ? (
-                        <span className="inline-flex items-center gap-1 px-2 py-0.5 text-xs font-medium rounded-full bg-green-100 text-green-700 dark:bg-green-900/30 dark:text-green-400">
-                          Auto-Approve
-                        </span>
-                      ) : (
-                        <span className="inline-flex items-center gap-1 px-2 py-0.5 text-xs font-medium rounded-full bg-gray-100 text-gray-600 dark:bg-gray-700 dark:text-gray-400">
-                          Manual
-                        </span>
-                      )}
-                      <svg className="w-3.5 h-3.5 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
-                      </svg>
-                    </button>
+                    />
                   </td>
                   <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-500 dark:text-gray-400">
                     {user._count.requests}
@@ -563,65 +779,7 @@ function AdminUsersPageContent() {
                       : 'Never'}
                   </td>
                   <td className="px-6 py-4 whitespace-nowrap text-right text-sm font-medium">
-                    <div className="flex items-center justify-end gap-3">
-                      {user.isSetupAdmin ? (
-                        <span className="inline-flex items-center gap-1 text-gray-400 dark:text-gray-600 cursor-not-allowed" title="Setup admin role cannot be changed">
-                          <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
-                          </svg>
-                          <span>Protected</span>
-                        </span>
-                      ) : user.authProvider === 'oidc' ? (
-                        <span className="inline-flex items-center gap-1 text-gray-400 dark:text-gray-600 cursor-not-allowed" title="OIDC user roles are managed by the identity provider (use admin role mapping in settings)">
-                          <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
-                          </svg>
-                          <span>OIDC Managed</span>
-                        </span>
-                      ) : user.authProvider === 'plex' ? (
-                        <button
-                          onClick={() => showEditDialog(user)}
-                          className="inline-flex items-center gap-1 text-blue-600 hover:text-blue-900 dark:text-blue-400 dark:hover:text-blue-300"
-                        >
-                          <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>Edit Role</span>
-                        </button>
-                      ) : user.authProvider === 'local' ? (
-                        <>
-                          <button
-                            onClick={() => showEditDialog(user)}
-                            className="inline-flex items-center gap-1 text-blue-600 hover:text-blue-900 dark:text-blue-400 dark:hover:text-blue-300"
-                          >
-                            <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>Edit Role</span>
-                          </button>
-                          <button
-                            onClick={() => showDeleteDialog(user)}
-                            className="inline-flex items-center gap-1 text-red-600 hover:text-red-900 dark:text-red-400 dark:hover:text-red-300"
-                            title="Delete user and all their requests"
-                          >
-                            <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16" />
-                            </svg>
-                            <span>Delete</span>
-                          </button>
-                        </>
-                      ) : (
-                        <button
-                          onClick={() => showEditDialog(user)}
-                          className="inline-flex items-center gap-1 text-blue-600 hover:text-blue-900 dark:text-blue-400 dark:hover:text-blue-300"
-                        >
-                          <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>Edit Role</span>
-                        </button>
-                      )}
-                    </div>
+                    <UserActionsCell user={user} onEdit={showEditDialog} onDelete={showDeleteDialog} />
                   </td>
                 </tr>
               ))}
@@ -643,31 +801,50 @@ function AdminUsersPageContent() {
           <ul className="text-sm text-blue-700 dark:text-blue-300 space-y-1">
             <li>• <strong>User:</strong> Can request audiobooks, view own requests, and search the catalog</li>
             <li>• <strong>Admin:</strong> Full system access including settings, user management, and all requests</li>
-            <li>• <strong>Setup Admin:</strong> The initial admin account created during setup - this account is protected and cannot be changed or deleted</li>
-            <li>• <strong>Permissions:</strong> Click a user&apos;s permission badge to manage individual settings (auto-approve, interactive search). Use Global User Permissions to control system-wide defaults. Admins always have full access.</li>
-            <li>• <strong>OIDC Users:</strong> Role management is handled by the identity provider - use admin role mapping in OIDC settings. Cannot be deleted as access is managed externally.</li>
-            <li>• <strong>Plex Users:</strong> Can have their roles changed, but cannot be deleted as access is managed by Plex.</li>
-            <li>• <strong>Local Users:</strong> Can be freely assigned user or admin roles (except setup admin). Can be deleted (their requests are preserved for historical records).</li>
+            <li>• <strong>Setup Admin:</strong> The initial admin account — protected, cannot be changed or deleted</li>
+            <li>• <strong>Permissions:</strong> Click a user&apos;s permission badge to manage individual settings. Use Global User Permissions for system-wide defaults. Admins always have full access.</li>
+            <li>• <strong>OIDC Users:</strong> Role management is handled by the identity provider. Cannot be deleted.</li>
+            <li>• <strong>Plex Users:</strong> Role can be changed, but cannot be deleted (access managed by Plex).</li>
+            <li>• <strong>Local Users:</strong> Can have roles freely assigned. Can be deleted (requests are preserved).</li>
             <li>• You cannot change your own role or delete yourself for security reasons</li>
           </ul>
         </div>
 
-        {/* Edit User Dialog */}
+        {/* Edit User Dialog — bottom sheet on mobile */}
         {editDialog.isOpen && editDialog.user && (
-          <div className="fixed inset-0 z-50 flex items-center justify-center bg-black bg-opacity-50 p-4">
-            <div className="bg-white dark:bg-gray-800 rounded-lg shadow-xl max-w-md w-full p-6">
-              <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-4">
-                Edit User Role
-              </h3>
-              <div className="space-y-4 mb-6">
+          <div className="fixed inset-0 z-50 flex items-end sm:items-center justify-center bg-black bg-opacity-50 p-0 sm:p-4">
+            <div className="bg-white dark:bg-gray-800 rounded-t-2xl sm:rounded-2xl shadow-xl w-full sm:max-w-md">
+              {/* Dialog header */}
+              <div className="sticky top-0 bg-white dark:bg-gray-800 px-5 py-4 border-b border-gray-200 dark:border-gray-700 rounded-t-2xl flex items-center justify-between">
+                <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100">
+                  Edit User Role
+                </h3>
+                <button
+                  onClick={hideEditDialog}
+                  className="p-2 -mr-1 text-gray-400 hover:text-gray-600 dark:hover:text-gray-200 rounded-lg hover:bg-gray-100 dark:hover:bg-gray-700 transition-colors"
+                  aria-label="Close dialog"
+                >
+                  <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 className="px-5 py-5 space-y-4">
                 {/* User Info */}
-                <div className="flex items-center gap-3 p-3 bg-gray-50 dark:bg-gray-700 rounded-lg">
-                  {editDialog.user.avatarUrl && (
+                <div className="flex items-center gap-3 p-3 bg-gray-50 dark:bg-gray-700 rounded-xl">
+                  {editDialog.user.avatarUrl ? (
                     <img
                       src={editDialog.user.avatarUrl}
                       alt={editDialog.user.plexUsername}
-                      className="h-12 w-12 rounded-full"
+                      className="h-12 w-12 rounded-full flex-shrink-0"
                     />
+                  ) : (
+                    <div className="h-12 w-12 rounded-full flex-shrink-0 bg-gray-200 dark:bg-gray-600 flex items-center justify-center">
+                      <svg className="w-6 h-6 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z" />
+                      </svg>
+                    </div>
                   )}
                   <div>
                     <div className="text-sm font-medium text-gray-900 dark:text-gray-100">
@@ -685,38 +862,34 @@ function AdminUsersPageContent() {
                     Role
                   </label>
                   <div className="space-y-2">
-                    <label className="flex items-start gap-3 p-3 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-700 cursor-pointer">
+                    <label className="flex items-start gap-3 p-3 border border-gray-300 dark:border-gray-600 rounded-xl hover:bg-gray-50 dark:hover:bg-gray-700 cursor-pointer transition-colors">
                       <input
                         type="radio"
                         name="role"
                         value="user"
                         checked={editRole === 'user'}
                         onChange={(e) => setEditRole(e.target.value as 'user' | 'admin')}
-                        className="mt-1 w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 focus:ring-blue-500 dark:bg-gray-700 dark:border-gray-600"
+                        className="mt-1 w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 focus:ring-blue-500 dark:bg-gray-700 dark:border-gray-600 flex-shrink-0"
                       />
                       <div className="flex-1">
-                        <div className="text-sm font-medium text-gray-900 dark:text-gray-100">
-                          User
-                        </div>
-                        <div className="text-xs text-gray-500 dark:text-gray-400 mt-1">
+                        <div className="text-sm font-medium text-gray-900 dark:text-gray-100">User</div>
+                        <div className="text-xs text-gray-500 dark:text-gray-400 mt-0.5">
                           Can request audiobooks and view own requests
                         </div>
                       </div>
                     </label>
-                    <label className="flex items-start gap-3 p-3 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-700 cursor-pointer">
+                    <label className="flex items-start gap-3 p-3 border border-gray-300 dark:border-gray-600 rounded-xl hover:bg-gray-50 dark:hover:bg-gray-700 cursor-pointer transition-colors">
                       <input
                         type="radio"
                         name="role"
                         value="admin"
                         checked={editRole === 'admin'}
                         onChange={(e) => setEditRole(e.target.value as 'user' | 'admin')}
-                        className="mt-1 w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 focus:ring-blue-500 dark:bg-gray-700 dark:border-gray-600"
+                        className="mt-1 w-4 h-4 text-blue-600 bg-gray-100 border-gray-300 focus:ring-blue-500 dark:bg-gray-700 dark:border-gray-600 flex-shrink-0"
                       />
                       <div className="flex-1">
-                        <div className="text-sm font-medium text-gray-900 dark:text-gray-100">
-                          Admin
-                        </div>
-                        <div className="text-xs text-gray-500 dark:text-gray-400 mt-1">
+                        <div className="text-sm font-medium text-gray-900 dark:text-gray-100">Admin</div>
+                        <div className="text-xs text-gray-500 dark:text-gray-400 mt-0.5">
                           Full system access including settings and user management
                         </div>
                       </div>
@@ -725,19 +898,19 @@ function AdminUsersPageContent() {
                 </div>
               </div>
 
-              {/* Actions */}
-              <div className="flex justify-end gap-3">
+              {/* Dialog footer */}
+              <div className="sticky bottom-0 bg-white dark:bg-gray-800 px-5 py-4 border-t border-gray-200 dark:border-gray-700 flex gap-3">
                 <button
                   onClick={hideEditDialog}
                   disabled={saving}
-                  className="px-4 py-2 text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 hover:bg-gray-200 dark:hover:bg-gray-600 rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+                  className="flex-1 px-4 py-2.5 text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 hover:bg-gray-200 dark:hover:bg-gray-600 rounded-lg transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed"
                 >
                   Cancel
                 </button>
                 <button
                   onClick={saveUserRole}
                   disabled={saving}
-                  className="px-4 py-2 text-white bg-blue-600 hover:bg-blue-700 rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+                  className="flex-1 px-4 py-2.5 text-white bg-blue-600 hover:bg-blue-700 rounded-lg transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed"
                 >
                   {saving ? 'Saving...' : 'Save Changes'}
                 </button>
@@ -788,6 +961,8 @@ function AdminUsersPageContent() {
           onToggleAutoApprove={handleGlobalAutoApproveToggle}
           globalInteractiveSearch={globalInteractiveSearch}
           onToggleInteractiveSearch={handleGlobalInteractiveSearchToggle}
+          globalDownloadAccess={globalDownloadAccess}
+          onToggleDownloadAccess={handleGlobalDownloadAccessToggle}
         />
 
         {/* User Permissions Modal */}
@@ -797,12 +972,16 @@ function AdminUsersPageContent() {
           user={permissionsUser}
           globalAutoApprove={globalAutoApprove}
           globalInteractiveSearch={globalInteractiveSearch}
+          globalDownloadAccess={globalDownloadAccess}
           onToggleAutoApprove={(user, newValue) => {
             handleUserAutoApproveToggle(user as User, newValue);
           }}
           onToggleInteractiveSearch={(user, newValue) => {
             handleUserInteractiveSearchToggle(user as User, newValue);
           }}
+          onToggleDownloadAccess={(user, newValue) => {
+            handleUserDownloadAccessToggle(user as User, newValue);
+          }}
         />
       </div>
     </div>

src/app/api/admin/filesystem/browse/route.ts

@@ -0,0 +1,208 @@
+/**
+ * Component: Admin Filesystem Browse API
+ * Documentation: documentation/features/manual-import.md
+ *
+ * Lets admins browse server directories for manual audiobook import.
+ * Restricted to download_dir and media_dir roots only.
+ */
+
+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 { AUDIO_EXTENSIONS } from '@/lib/constants/audio-formats';
+
+const logger = RMABLogger.create('API.Admin.Filesystem.Browse');
+
+interface DirectoryEntry {
+  name: string;
+  type: 'directory';
+  audioFileCount: number;
+  subfolderCount: number;
+  totalSize: number;
+}
+
+/**
+ * Scan immediate children of a directory to gather audio file and subfolder stats.
+ */
+async function getDirectoryStats(
+  dirPath: string
+): Promise<{ audioFileCount: number; subfolderCount: number; totalSize: number }> {
+  const fs = await import('fs/promises');
+  const pathModule = await import('path');
+
+  let audioFileCount = 0;
+  let subfolderCount = 0;
+  let totalSize = 0;
+
+  try {
+    const children = await fs.readdir(dirPath, { withFileTypes: true });
+    for (const child of children) {
+      if (child.isDirectory()) {
+        subfolderCount++;
+      } else if (child.isFile()) {
+        const ext = pathModule.extname(child.name).toLowerCase();
+        if ((AUDIO_EXTENSIONS as readonly string[]).includes(ext)) {
+          audioFileCount++;
+          try {
+            const stat = await fs.stat(pathModule.join(dirPath, child.name));
+            totalSize += stat.size;
+          } catch {
+            /* skip unreadable files */
+          }
+        }
+      }
+    }
+  } catch {
+    /* directory not readable */
+  }
+
+  return { audioFileCount, subfolderCount, totalSize };
+}
+
+/**
+ * Load allowed root directories from Configuration table.
+ */
+const BOOKDROP_PATH = '/bookdrop';
+
+async function getAllowedRoots(): Promise<{ downloadDir: string | null; mediaDir: string | null; bookdropExists: boolean }> {
+  const downloadDirConfig = await prisma.configuration.findUnique({
+    where: { key: 'download_dir' },
+  });
+  const mediaDirConfig = await prisma.configuration.findUnique({
+    where: { key: 'media_dir' },
+  });
+
+  let bookdropExists = false;
+  try {
+    const fs = await import('fs/promises');
+    const stat = await fs.stat(BOOKDROP_PATH);
+    bookdropExists = stat.isDirectory();
+  } catch {
+    /* not mounted */
+  }
+
+  return {
+    downloadDir: downloadDirConfig?.value || null,
+    mediaDir: mediaDirConfig?.value || null,
+    bookdropExists,
+  };
+}
+
+/**
+ * Check if a normalized path is within one of the allowed roots.
+ */
+function isPathAllowed(normalizedPath: string, roots: string[]): boolean {
+  return roots.some(
+    (root) => normalizedPath === root || normalizedPath.startsWith(root + '/')
+  );
+}
+
+export async function GET(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 { downloadDir, mediaDir, bookdropExists } = await getAllowedRoots();
+        const requestedPath = request.nextUrl.searchParams.get('path');
+
+        // No path param: return root directories
+        if (!requestedPath) {
+          const roots: Array<{ name: string; path: string; icon: string }> = [];
+          if (downloadDir) {
+            roots.push({ name: 'Downloads', path: downloadDir, icon: 'download' });
+          }
+          if (mediaDir) {
+            roots.push({ name: 'Media Library', path: mediaDir, icon: 'library' });
+          }
+          if (bookdropExists) {
+            roots.push({ name: 'Book Drop', path: BOOKDROP_PATH, icon: 'bookdrop' });
+          }
+
+          if (roots.length === 0) {
+            return NextResponse.json(
+              { error: 'No browsable directories available' },
+              { status: 400 }
+            );
+          }
+
+          return NextResponse.json({ roots });
+        }
+
+        // Path param provided: browse that directory
+        // Normalize to forward slashes and resolve
+        const normalizedPath = pathModule.resolve(requestedPath).replace(/\\/g, '/');
+
+        // Build list of allowed roots (normalized)
+        const allowedRoots: string[] = [];
+        if (downloadDir) allowedRoots.push(pathModule.resolve(downloadDir).replace(/\\/g, '/'));
+        if (mediaDir) allowedRoots.push(pathModule.resolve(mediaDir).replace(/\\/g, '/'));
+        if (bookdropExists) allowedRoots.push(pathModule.resolve(BOOKDROP_PATH).replace(/\\/g, '/'));
+
+        if (!isPathAllowed(normalizedPath, allowedRoots)) {
+          logger.warn(`Access denied: ${normalizedPath} is outside allowed directories`);
+          return NextResponse.json(
+            { error: 'Access denied: path outside allowed directories' },
+            { status: 403 }
+          );
+        }
+
+        // Read directory entries
+        const dirEntries = await fs.readdir(normalizedPath, { withFileTypes: true });
+
+        // Gather stats for each subdirectory (parallel for performance)
+        const directoryEntries = dirEntries.filter((e) => e.isDirectory());
+        const statsPromises = directoryEntries.map(async (entry): Promise<DirectoryEntry> => {
+          const fullPath = pathModule.join(normalizedPath, entry.name);
+          const stats = await getDirectoryStats(fullPath);
+          return {
+            name: entry.name,
+            type: 'directory',
+            ...stats,
+          };
+        });
+
+        const entries = await Promise.all(statsPromises);
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+
+        // Gather audio files in the current directory
+        const audioFiles: Array<{ name: string; size: number }> = [];
+        for (const entry of dirEntries) {
+          if (entry.isFile()) {
+            const ext = pathModule.extname(entry.name).toLowerCase();
+            if ((AUDIO_EXTENSIONS as readonly string[]).includes(ext)) {
+              try {
+                const stat = await fs.stat(pathModule.join(normalizedPath, entry.name));
+                audioFiles.push({ name: entry.name, size: stat.size });
+              } catch {
+                audioFiles.push({ name: entry.name, size: 0 });
+              }
+            }
+          }
+        }
+        audioFiles.sort((a, b) => a.name.localeCompare(b.name));
+
+        return NextResponse.json({ path: normalizedPath, entries, audioFiles });
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+
+        if (code === 'ENOENT') {
+          return NextResponse.json({ error: 'Directory not found' }, { status: 404 });
+        }
+        if (code === 'EACCES' || code === 'EPERM') {
+          return NextResponse.json({ error: 'Permission denied' }, { status: 403 });
+        }
+
+        logger.error('Failed to browse directory', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return NextResponse.json(
+          { error: 'Failed to browse directory' },
+          { status: 500 }
+        );
+      }
+    });
+  });
+}

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

@@ -0,0 +1,265 @@
+/**
+ * Component: Admin Manual Import API
+ * Documentation: documentation/features/manual-import.md
+ *
+ * Triggers the organize_files pipeline for a manually-selected folder.
+ * Creates or recycles a request, then queues the organize job.
+ */
+
+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';
+
+const logger = RMABLogger.create('API.Admin.ManualImport');
+
+/** 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'];
+
+/**
+ * Check if a directory contains at least one audio file (immediate children only).
+ */
+async function hasAudioFiles(dirPath: string): Promise<{ found: boolean; count: number }> {
+  const fs = await import('fs/promises');
+  const pathModule = await import('path');
+
+  let count = 0;
+  try {
+    const children = await fs.readdir(dirPath, { withFileTypes: true });
+    for (const child of children) {
+      if (child.isFile()) {
+        const ext = pathModule.extname(child.name).toLowerCase();
+        if ((AUDIO_EXTENSIONS as readonly string[]).includes(ext)) {
+          count++;
+        }
+      }
+    }
+  } catch {
+    /* directory not readable */
+  }
+
+  return { found: count > 0, count };
+}
+
+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 { folderPath, asin, cleanupSource } = body;
+        let { audiobookId } = body;
+
+        // Validate required fields
+        if ((!audiobookId && !asin) || !folderPath) {
+          return NextResponse.json(
+            { error: 'folderPath and either audiobookId or asin are required' },
+            { status: 400 }
+          );
+        }
+
+        // Load allowed roots
+        const BOOKDROP_PATH = '/bookdrop';
+        const downloadDirConfig = await prisma.configuration.findUnique({
+          where: { key: 'download_dir' },
+        });
+        const mediaDirConfig = await 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 */
+        }
+
+        // Normalize and validate path
+        const normalizedPath = pathModule.resolve(folderPath).replace(/\\/g, '/');
+        const isAllowed = allowedRoots.some(
+          (root) => normalizedPath === root || normalizedPath.startsWith(root + '/')
+        );
+
+        if (!isAllowed) {
+          return NextResponse.json(
+            { error: 'Access denied: path outside allowed directories' },
+            { status: 403 }
+          );
+        }
+
+        // Verify folder exists and is a directory
+        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 }
+          );
+        }
+
+        // Verify folder contains audio files
+        const audioCheck = await hasAudioFiles(normalizedPath);
+        if (!audioCheck.found) {
+          return NextResponse.json(
+            { error: 'No audio files found in the selected directory' },
+            { status: 400 }
+          );
+        }
+
+        // Resolve audiobook by ASIN if audiobookId not provided
+        if (!audiobookId && asin) {
+          const byAsin = await prisma.audiobook.findFirst({
+            where: { audibleAsin: asin },
+          });
+          if (byAsin) {
+            audiobookId = byAsin.id;
+          } else {
+            // Create audiobook record from Audible cache if available
+            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;
+              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 }
+              );
+            }
+          }
+        }
+
+        // Verify audiobook exists
+        const audiobook = await prisma.audiobook.findUnique({
+          where: { id: audiobookId },
+        });
+
+        if (!audiobook) {
+          return NextResponse.json(
+            { error: 'Audiobook not found' },
+            { status: 404 }
+          );
+        }
+
+        // Check for existing requests
+        const existingRequest = await prisma.request.findFirst({
+          where: {
+            audiobookId,
+            type: 'audiobook',
+            deletedAt: null,
+          },
+          orderBy: { createdAt: 'desc' },
+        });
+
+        let requestId: string;
+
+        if (existingRequest) {
+          // Check if already in an active state
+          if (ACTIVE_STATUSES.includes(existingRequest.status)) {
+            return NextResponse.json(
+              { error: 'This audiobook is already being processed' },
+              { status: 409 }
+            );
+          }
+
+          // Recycle the existing request
+          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;
+            logger.info(`Recycled existing request ${requestId} for manual import`);
+          } else {
+            // Unknown status - create new
+            const newRequest = await prisma.request.create({
+              data: {
+                userId: req.user!.id,
+                audiobookId,
+                type: 'audiobook',
+                status: 'processing',
+                progress: 100,
+              },
+            });
+            requestId = newRequest.id;
+            logger.info(`Created new request ${requestId} (existing had status: ${existingRequest.status})`);
+          }
+        } else {
+          // No existing request - create one
+          const newRequest = await prisma.request.create({
+            data: {
+              userId: req.user!.id,
+              audiobookId,
+              type: 'audiobook',
+              status: 'processing',
+              progress: 100,
+            },
+          });
+          requestId = newRequest.id;
+          logger.info(`Created new request ${requestId} for manual import`);
+        }
+
+        // Queue organize_files job
+        const jobQueue = getJobQueueService();
+        await jobQueue.addOrganizeJob(requestId, audiobookId, normalizedPath, undefined, cleanupSource === true);
+
+        logger.info(`Manual import queued: request=${requestId}, path=${normalizedPath}, audioFiles=${audioCheck.count}`);
+
+        return NextResponse.json({
+          success: true,
+          requestId,
+          message: `Import started for ${audiobook.title}`,
+        });
+      } catch (error) {
+        logger.error('Manual import failed', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return NextResponse.json(
+          { error: error instanceof Error ? error.message : 'Manual import failed' },
+          { status: 500 }
+        );
+      }
+    });
+  });
+}

src/app/api/admin/requests/[id]/approve/route.ts

@@ -14,6 +14,7 @@ const logger = RMABLogger.create('API.Admin.Requests.Approve');
 
 const ApprovalActionSchema = z.object({
   action: z.enum(['approve', 'deny']),
+  selectedTorrent: z.any().optional(),
 });
 
 /**
@@ -37,8 +38,8 @@ export async function POST(
         const { id } = await params;
         const body = await request.json();
 
-        // Validate action
-        const { action } = ApprovalActionSchema.parse(body);
+        // Validate action and optional admin-selected torrent
+        const { action, selectedTorrent: adminSelectedTorrent } = ApprovalActionSchema.parse(body);
 
         // Fetch the request
         const existingRequest = await prisma.request.findUnique({
@@ -78,12 +79,15 @@ export async function POST(
           const jobQueue = getJobQueueService();
           const isEbookRequest = existingRequest.type === 'ebook';
 
-          // Check if request has a pre-selected torrent (from interactive search)
-          if (existingRequest.selectedTorrent) {
-            const selectedTorrent = existingRequest.selectedTorrent as any;
+          // Use admin-provided torrent (from admin interactive search) or fall back to user's pre-selected torrent
+          const effectiveTorrent = adminSelectedTorrent || existingRequest.selectedTorrent;
 
-            // User pre-selected a specific torrent - download that torrent directly
-            logger.info(`Request ${id} has pre-selected torrent, starting download`, {
+          if (effectiveTorrent) {
+            const selectedTorrent = effectiveTorrent as any;
+            const torrentSource = adminSelectedTorrent ? 'admin' : 'user';
+
+            // Download the selected torrent directly
+            logger.info(`Request ${id} has ${torrentSource}-selected torrent, starting download`, {
               requestId: id,
               userId: existingRequest.userId,
               adminId: req.user.sub,
@@ -167,17 +171,20 @@ export async function POST(
               logger.error('Failed to queue notification', { error: error instanceof Error ? error.message : String(error) });
             });
 
-            logger.info(`Request ${id} approved by admin ${req.user.sub}, downloading pre-selected torrent`, {
+            logger.info(`Request ${id} approved by admin ${req.user.sub}, downloading ${torrentSource}-selected torrent`, {
               requestId: id,
               userId: updatedRequest.userId,
               audiobookTitle: existingRequest.audiobook.title,
               adminId: req.user.sub,
               type: existingRequest.type,
+              torrentSource,
             });
 
             return NextResponse.json({
               success: true,
-              message: 'Request approved and download started with pre-selected torrent',
+              message: adminSelectedTorrent
+                ? 'Request approved and download started with admin-selected torrent'
+                : 'Request approved and download started with pre-selected torrent',
               request: updatedRequest,
             });
           } else {

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,133 @@
+/**
+ * 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
+          const { getJobQueueService } = await import('@/lib/services/job-queue.service');
+          const jobQueue = getJobQueueService();
+          await jobQueue.addSearchJob(id, {
+            id: existingRequest.audiobook.id,
+            title: existingRequest.audiobook.title,
+            author: existingRequest.audiobook.author,
+            asin: existingRequest.audiobook.audibleAsin || undefined,
+          });
+
+          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/download-access/route.ts

@@ -0,0 +1,91 @@
+/**
+ * Component: Admin Download Access Settings API
+ * Documentation: documentation/settings-pages.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.Settings.DownloadAccess');
+
+const CONFIG_KEY = 'download_access';
+
+/**
+ * GET /api/admin/settings/download-access
+ * Get current global download access setting
+ */
+export async function GET(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    return requireAdmin(req, async () => {
+      try {
+        const config = await prisma.configuration.findUnique({
+          where: { key: CONFIG_KEY },
+        });
+
+        // Default to true if not configured (backward compatibility)
+        const downloadAccess = config === null ? true : config.value === 'true';
+
+        return NextResponse.json({ downloadAccess });
+      } catch (error) {
+        logger.error('Failed to fetch download access setting', {
+          error: error instanceof Error ? error.message : String(error)
+        });
+        return NextResponse.json(
+          { error: 'Failed to fetch download access setting' },
+          { status: 500 }
+        );
+      }
+    });
+  });
+}
+
+/**
+ * PATCH /api/admin/settings/download-access
+ * Update global download access setting
+ */
+export async function PATCH(request: NextRequest) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    return requireAdmin(req, async () => {
+      try {
+        const body = await request.json();
+        const { downloadAccess } = body;
+
+        // Validate input
+        if (typeof downloadAccess !== 'boolean') {
+          return NextResponse.json(
+            { error: 'Invalid input. downloadAccess must be a boolean' },
+            { status: 400 }
+          );
+        }
+
+        // Update configuration
+        await prisma.configuration.upsert({
+          where: { key: CONFIG_KEY },
+          create: {
+            key: CONFIG_KEY,
+            value: downloadAccess.toString(),
+          },
+          update: {
+            value: downloadAccess.toString(),
+          },
+        });
+
+        logger.info(`Download access setting updated to: ${downloadAccess}`, {
+          userId: req.user?.sub,
+        });
+
+        return NextResponse.json({ downloadAccess });
+      } catch (error) {
+        logger.error('Failed to update download access setting', {
+          error: error instanceof Error ? error.message : String(error)
+        });
+        return NextResponse.json(
+          { error: 'Failed to update download access setting' },
+          { status: 500 }
+        );
+      }
+    });
+  });
+}

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 } = await request.json();
+        const { downloadDir, mediaDir, audiobookPathTemplate, ebookPathTemplate, metadataTaggingEnabled, chapterMergingEnabled, fileRenameEnabled, fileRenameTemplate } = await request.json();
 
         if (!downloadDir || !mediaDir) {
           return NextResponse.json(
@@ -97,6 +97,32 @@ export async function PUT(request: NextRequest) {
           },
         });
 
+        // Update file rename setting
+        await prisma.configuration.upsert({
+          where: { key: 'file_rename_enabled' },
+          update: { value: String(fileRenameEnabled ?? false) },
+          create: {
+            key: 'file_rename_enabled',
+            value: String(fileRenameEnabled ?? false),
+            category: 'automation',
+            description: 'Rename audio and ebook files using a custom naming template during organization',
+          },
+        });
+
+        // Update file rename template
+        if (fileRenameTemplate !== undefined) {
+          await prisma.configuration.upsert({
+            where: { key: 'file_rename_template' },
+            update: { value: fileRenameTemplate },
+            create: {
+              key: 'file_rename_template',
+              value: fileRenameTemplate,
+              category: 'automation',
+              description: 'Template for renaming audio and ebook files during organization',
+            },
+          });
+        }
+
         logger.info('Paths settings updated');
 
         // Clear config cache for all updated keys so services get fresh values
@@ -107,6 +133,8 @@ export async function PUT(request: NextRequest) {
         configService.clearCache('ebook_path_template');
         configService.clearCache('metadata_tagging_enabled');
         configService.clearCache('chapter_merging_enabled');
+        configService.clearCache('file_rename_enabled');
+        configService.clearCache('file_rename_template');
 
         // 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

@@ -128,6 +128,8 @@ export async function GET(request: NextRequest) {
         ebookPathTemplate: configMap.get('ebook_path_template') || configMap.get('audiobook_path_template') || '{author}/{title} {asin}',
         metadataTaggingEnabled: configMap.get('metadata_tagging_enabled') === 'true',
         chapterMergingEnabled: configMap.get('chapter_merging_enabled') === 'true',
+        fileRenameEnabled: configMap.get('file_rename_enabled') === 'true',
+        fileRenameTemplate: configMap.get('file_rename_template') || '{title}',
       },
       ebook: {
         // New granular source toggles (with migration from legacy ebook_sidecar_enabled)

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

@@ -19,7 +19,7 @@ export async function PUT(
       try {
         const { id } = await params;
         const body = await request.json();
-        const { role, autoApproveRequests, interactiveSearchAccess } = body;
+        const { role, autoApproveRequests, interactiveSearchAccess, downloadAccess } = body;
 
         // Validate role
         if (!role || (role !== 'user' && role !== 'admin')) {
@@ -45,6 +45,14 @@ export async function PUT(
           );
         }
 
+        // Validate downloadAccess (optional)
+        if (downloadAccess !== undefined && downloadAccess !== null && typeof downloadAccess !== 'boolean') {
+          return NextResponse.json(
+            { error: 'Invalid downloadAccess. Must be a boolean or null' },
+            { status: 400 }
+          );
+        }
+
         // Prevent user from demoting themselves
         if (req.user && id === req.user.sub) {
           return NextResponse.json(
@@ -112,15 +120,24 @@ export async function PUT(
             { status: 400 }
           );
         }
+        if (role === 'admin' && downloadAccess === false) {
+          return NextResponse.json(
+            { error: 'Admins always have download access. Cannot set downloadAccess to false for admin users.' },
+            { status: 400 }
+          );
+        }
 
         // Prepare update data
-        const updateData: { role: string; autoApproveRequests?: boolean | null; interactiveSearchAccess?: boolean | null } = { role };
+        const updateData: { role: string; autoApproveRequests?: boolean | null; interactiveSearchAccess?: boolean | null; downloadAccess?: boolean | null } = { role };
         if (autoApproveRequests !== undefined) {
           updateData.autoApproveRequests = autoApproveRequests;
         }
         if (interactiveSearchAccess !== undefined) {
           updateData.interactiveSearchAccess = interactiveSearchAccess;
         }
+        if (downloadAccess !== undefined) {
+          updateData.downloadAccess = downloadAccess;
+        }
 
         // Update user
         const updatedUser = await prisma.user.update({
@@ -132,6 +149,7 @@ export async function PUT(
             role: true,
             autoApproveRequests: true,
             interactiveSearchAccess: true,
+            downloadAccess: true,
           },
         });
 

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

@@ -32,6 +32,7 @@ export async function GET(request: NextRequest) {
             lastLoginAt: true,
             autoApproveRequests: true,
             interactiveSearchAccess: true,
+            downloadAccess: true,
             _count: {
               select: {
                 requests: true,

src/app/api/audiobooks/[asin]/download-status/route.ts

@@ -0,0 +1,70 @@
+/**
+ * Component: Audiobook Download Status API Route
+ * Documentation: documentation/backend/api.md
+ *
+ * Returns whether a downloadable file exists for this audiobook (by ASIN).
+ * Used by AudiobookDetailsModal to show the download link regardless of context.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { COMPLETED_STATUSES } from '@/lib/constants/request-statuses';
+import { resolveDownloadAccess } from '@/lib/utils/permissions';
+
+/**
+ * GET /api/audiobooks/[asin]/download-status
+ * Returns { downloadAvailable, requestId } for the current user's completed request.
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ asin: string }> }
+) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    if (!req.user) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    // Check download permission - if denied, don't reveal file existence
+    const userRecord = await prisma.user.findUnique({
+      where: { id: req.user.id },
+      select: { role: true, downloadAccess: true },
+    });
+    const hasDownloadAccess = await resolveDownloadAccess(
+      userRecord?.role ?? 'user',
+      userRecord?.downloadAccess ?? null
+    );
+    if (!hasDownloadAccess) {
+      return NextResponse.json({ downloadAvailable: false, requestId: null });
+    }
+
+    const { asin } = await params;
+
+    const audiobook = await prisma.audiobook.findFirst({
+      where: { audibleAsin: asin },
+      select: { id: true, filePath: true },
+    });
+
+    if (!audiobook) {
+      return NextResponse.json({ downloadAvailable: false, requestId: null });
+    }
+
+    // Find any completed request for this audiobook that has a file
+    const completedRequest = await prisma.request.findFirst({
+      where: {
+        audiobookId: audiobook.id,
+        status: { in: [...COMPLETED_STATUSES] },
+        deletedAt: null,
+      },
+      select: { id: true },
+      orderBy: { createdAt: 'desc' },
+    });
+
+    const downloadAvailable = !!completedRequest && !!audiobook.filePath;
+
+    return NextResponse.json({
+      downloadAvailable,
+      requestId: downloadAvailable ? completedRequest!.id : null,
+    });
+  });
+}

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

@@ -39,6 +39,7 @@ export async function GET(request: NextRequest) {
         createdAt: true,
         lastLoginAt: true,
         interactiveSearchAccess: true,
+        downloadAccess: true,
       },
     });
 
@@ -63,6 +64,13 @@ export async function GET(request: NextRequest) {
       globalInteractiveSearch
     );
 
+    const globalDownload = await getGlobalBooleanSetting('download_access', true);
+    const effectiveDownload = resolvePermission(
+      user.role,
+      user.downloadAccess,
+      globalDownload
+    );
+
     return NextResponse.json({
       user: {
         id: user.id,
@@ -77,6 +85,7 @@ export async function GET(request: NextRequest) {
         lastLoginAt: user.lastLoginAt,
         permissions: {
           interactiveSearch: effectiveInteractiveSearch,
+          download: effectiveDownload,
         },
       },
     });

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

@@ -46,23 +46,27 @@ 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);
 
     // Enrich with library availability and request status
     const userId = currentUser.sub || undefined;
-    const enrichedBooks = await enrichAudiobooksWithMatches(books, userId);
+    const enrichedBooks = await enrichAudiobooksWithMatches(result.books, userId);
 
-    logger.info(`Author books complete: "${authorName}" → ${enrichedBooks.length} books`);
+    logger.info(`Author books complete: "${authorName}" → ${enrichedBooks.length} books (page ${page})`);
 
     return NextResponse.json({
       success: true,
       books: enrichedBooks,
       authorName: authorName.trim(),
       authorAsin: asin,
-      totalBooks: enrichedBooks.length,
+      totalBooks: result.totalResults || 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/config/[category]/route.ts

@@ -1,38 +0,0 @@
-/**
- * Component: Configuration API Routes (by category)
- * Documentation: documentation/backend/services/config.md
- */
-
-import { NextRequest, NextResponse } from 'next/server';
-import { getConfigService } from '@/lib/services/config.service';
-import { RMABLogger } from '@/lib/utils/logger';
-
-const logger = RMABLogger.create('API.Config.Category');
-
-// GET /api/config/:category - Get all config for a category
-export async function GET(
-  request: NextRequest,
-  { params }: { params: Promise<{ category: string }> }
-) {
-  try {
-    // TODO: Add authentication middleware - admin only
-    const { category } = await params;
-    const configService = getConfigService();
-
-    const config = await configService.getCategory(category);
-
-    return NextResponse.json({
-      category,
-      config,
-    });
-  } catch (error) {
-    logger.error('Failed to get config for category', { error: error instanceof Error ? error.message : String(error) });
-    return NextResponse.json(
-      {
-        error: 'Failed to get configuration',
-        message: error instanceof Error ? error.message : 'Unknown error',
-      },
-      { status: 500 }
-    );
-  }
-}

src/app/api/config/route.ts

@@ -1,84 +0,0 @@
-/**
- * Component: Configuration API Routes
- * Documentation: documentation/backend/services/config.md
- */
-
-import { NextRequest, NextResponse } from 'next/server';
-import { getConfigService, ConfigUpdate } from '@/lib/services/config.service';
-import { z } from 'zod';
-import { RMABLogger } from '@/lib/utils/logger';
-
-const logger = RMABLogger.create('API.Config');
-
-const ConfigUpdateSchema = z.object({
-  updates: z.array(
-    z.object({
-      key: z.string(),
-      value: z.string(),
-      encrypted: z.boolean().optional(),
-      category: z.string().optional(),
-      description: z.string().optional(),
-    })
-  ),
-});
-
-// PUT /api/config - Update multiple configuration values
-export async function PUT(request: NextRequest) {
-  try {
-    // TODO: Add authentication middleware - admin only
-
-    const body = await request.json();
-    const { updates } = ConfigUpdateSchema.parse(body);
-
-    const configService = getConfigService();
-    await configService.setMany(updates as ConfigUpdate[]);
-
-    return NextResponse.json({
-      success: true,
-      updated: updates.length,
-    });
-  } catch (error) {
-    logger.error('Failed to update configuration', { 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 update configuration',
-        message: error instanceof Error ? error.message : 'Unknown error',
-      },
-      { status: 500 }
-    );
-  }
-}
-
-// GET /api/config - Get all configuration (masked sensitive values)
-export async function GET() {
-  try {
-    // TODO: Add authentication middleware - admin only
-
-    const configService = getConfigService();
-    const allConfig = await configService.getAll();
-
-    return NextResponse.json({
-      config: allConfig,
-    });
-  } catch (error) {
-    logger.error('Failed to get all configuration', { error: error instanceof Error ? error.message : String(error) });
-    return NextResponse.json(
-      {
-        error: 'Failed to get configuration',
-        message: error instanceof Error ? error.message : 'Unknown error',
-      },
-      { status: 500 }
-    );
-  }
-}

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

@@ -0,0 +1,89 @@
+/**
+ * Component: On-Demand Download Token Generator
+ * Documentation: documentation/backend/api.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
+import { prisma } from '@/lib/db';
+import { generateDownloadToken } from '@/lib/utils/jwt';
+import { COMPLETED_STATUSES } from '@/lib/constants/request-statuses';
+import { resolveDownloadAccess } from '@/lib/utils/permissions';
+import { RMABLogger } from '@/lib/utils/logger';
+
+const logger = RMABLogger.create('API.DownloadToken');
+
+/**
+ * POST /api/requests/[id]/download-token
+ * Generate a signed download token on demand (lazy token generation).
+ */
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  return requireAuth(request, async (req: AuthenticatedRequest) => {
+    try {
+      if (!req.user) {
+        return NextResponse.json(
+          { error: 'Unauthorized', message: 'User not authenticated' },
+          { status: 401 }
+        );
+      }
+
+      // Check download permission
+      const userRecord = await prisma.user.findUnique({
+        where: { id: req.user.id },
+        select: { role: true, downloadAccess: true },
+      });
+      const hasDownloadAccess = await resolveDownloadAccess(
+        userRecord?.role ?? 'user',
+        userRecord?.downloadAccess ?? null
+      );
+      if (!hasDownloadAccess) {
+        return NextResponse.json(
+          { error: 'Forbidden', message: 'You do not have download access' },
+          { status: 403 }
+        );
+      }
+
+      const { id } = await params;
+
+      const requestRecord = await prisma.request.findFirst({
+        where: { id, deletedAt: null },
+        include: { audiobook: true },
+      });
+
+      if (!requestRecord) {
+        return NextResponse.json(
+          { error: 'NotFound', message: 'Request not found' },
+          { status: 404 }
+        );
+      }
+
+      if (!COMPLETED_STATUSES.includes(requestRecord.status as typeof COMPLETED_STATUSES[number])) {
+        return NextResponse.json(
+          { error: 'BadRequest', message: 'Request is not yet completed' },
+          { status: 400 }
+        );
+      }
+
+      if (!requestRecord.audiobook?.filePath) {
+        return NextResponse.json(
+          { error: 'NotFound', message: 'No file available for this request' },
+          { status: 404 }
+        );
+      }
+
+      const token = generateDownloadToken(req.user.id, id);
+      const downloadUrl = `/api/requests/${id}/download?token=${token}`;
+
+      return NextResponse.json({ downloadUrl });
+    } catch (error) {
+      logger.error('Failed to generate download token', { error: error instanceof Error ? error.message : String(error) });
+      return NextResponse.json(
+        { error: 'TokenError', message: 'Failed to generate download token' },
+        { status: 500 }
+      );
+    }
+  });
+}

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

@@ -0,0 +1,152 @@
+/**
+ * Component: Request File Download Endpoint
+ * Documentation: documentation/backend/api.md
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { prisma } from '@/lib/db';
+import { verifyDownloadToken } from '@/lib/utils/jwt';
+import { RMABLogger } from '@/lib/utils/logger';
+import { AUDIO_EXTENSIONS, EBOOK_EXTENSIONS } from '@/lib/constants/audio-formats';
+import { COMPLETED_STATUSES } from '@/lib/constants/request-statuses';
+import fs from 'fs';
+import path from 'path';
+import archiver from 'archiver';
+import { PassThrough } from 'stream';
+
+const logger = RMABLogger.create('API.Download');
+
+function sanitizeFilename(name: string): string {
+  return name
+    .replace(/[<>:"/\\|?*]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 200);
+}
+
+/**
+ * GET /api/requests/[id]/download?token=<JWT>
+ * Token-authenticated file download — no session cookie required.
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    const token = request.nextUrl.searchParams.get('token');
+
+    if (!token) {
+      return NextResponse.json({ error: 'Unauthorized', message: 'Missing download token' }, { status: 401 });
+    }
+
+    const payload = verifyDownloadToken(token);
+    if (!payload) {
+      return NextResponse.json({ error: 'Unauthorized', message: 'Invalid or expired download token' }, { status: 401 });
+    }
+
+    if (payload.requestId !== id) {
+      return NextResponse.json({ error: 'Unauthorized', message: 'Token does not match request' }, { status: 401 });
+    }
+
+    const requestRecord = await prisma.request.findFirst({
+      where: { id, deletedAt: null },
+      include: { audiobook: true },
+    });
+
+    if (!requestRecord) {
+      return NextResponse.json({ error: 'NotFound', message: 'Request not found' }, { status: 404 });
+    }
+
+    if (!COMPLETED_STATUSES.includes(requestRecord.status as typeof COMPLETED_STATUSES[number])) {
+      return NextResponse.json({ error: 'BadRequest', message: 'Request is not yet completed' }, { status: 400 });
+    }
+
+    if (!requestRecord.audiobook?.filePath) {
+      return NextResponse.json({ error: 'NotFound', message: 'No file path available for this request' }, { status: 404 });
+    }
+
+    const resolvedDir = path.resolve(requestRecord.audiobook.filePath);
+
+    if (!fs.existsSync(resolvedDir)) {
+      logger.error('Download directory does not exist', { path: resolvedDir });
+      return NextResponse.json({ error: 'NotFound', message: 'File directory not found on disk' }, { status: 404 });
+    }
+
+    const requestType = requestRecord.type || 'audiobook';
+    const allowedExtensions: readonly string[] = requestType === 'ebook' ? EBOOK_EXTENSIONS : AUDIO_EXTENSIONS;
+
+    const allEntries = fs.readdirSync(resolvedDir);
+    const matchingFiles = allEntries
+      .filter(name => allowedExtensions.includes(path.extname(name).toLowerCase()))
+      .map(name => path.join(resolvedDir, name));
+
+    if (matchingFiles.length === 0) {
+      return NextResponse.json({ error: 'NotFound', message: 'No matching files found in directory' }, { status: 404 });
+    }
+
+    const sanitizedTitle = sanitizeFilename(requestRecord.audiobook.title || 'download');
+
+    if (matchingFiles.length === 1) {
+      const filePath = matchingFiles[0];
+      const ext = path.extname(filePath);
+      const stat = fs.statSync(filePath);
+      const fileStream = fs.createReadStream(filePath);
+
+      const readableStream = new ReadableStream({
+        start(controller) {
+          fileStream.on('data', chunk => controller.enqueue(chunk));
+          fileStream.on('end', () => controller.close());
+          fileStream.on('error', err => {
+            logger.error('File stream error', { error: err.message });
+            controller.error(err);
+          });
+        },
+        cancel() {
+          fileStream.destroy();
+        },
+      });
+
+      return new NextResponse(readableStream, {
+        headers: {
+          'Content-Type': 'application/octet-stream',
+          'Content-Disposition': `attachment; filename="${sanitizedTitle}${ext}"`,
+          'Content-Length': String(stat.size),
+        },
+      });
+    }
+
+    // Multiple files — stream zip via archiver (avoids loading all files into memory)
+    const passThrough = new PassThrough();
+    const archive = archiver('zip', { zlib: { level: 6 } });
+    archive.pipe(passThrough);
+    for (const filePath of matchingFiles) {
+      archive.file(filePath, { name: path.basename(filePath) });
+    }
+    archive.finalize();
+
+    const zipReadable = new ReadableStream({
+      start(controller) {
+        passThrough.on('data', chunk => controller.enqueue(new Uint8Array(chunk)));
+        passThrough.on('end', () => controller.close());
+        passThrough.on('error', err => {
+          logger.error('Zip stream error', { error: err.message });
+          controller.error(err);
+        });
+      },
+      cancel() {
+        archive.abort();
+      },
+    });
+
+    return new NextResponse(zipReadable, {
+      headers: {
+        'Content-Type': 'application/zip',
+        'Content-Disposition': `attachment; filename="${sanitizedTitle}.zip"`,
+      },
+    });
+  } catch (error) {
+    logger.error('Download failed', { error: error instanceof Error ? error.message : String(error) });
+    return NextResponse.json({ error: 'DownloadError', message: 'Failed to serve file' }, { status: 500 });
+  }
+}

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

@@ -67,8 +67,8 @@ export async function POST(
         );
       }
 
-      // Check if request is awaiting approval
-      if (requestRecord.status === 'awaiting_approval') {
+      // Check if request is awaiting approval (admins can still search to override the user's selection)
+      if (requestRecord.status === 'awaiting_approval' && req.user.role !== 'admin') {
         return NextResponse.json(
           { error: 'AwaitingApproval', message: 'This request is awaiting admin approval. You cannot search for torrents until it is approved.' },
           { status: 403 }
@@ -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 });

src/app/api/requests/route.ts

@@ -9,6 +9,7 @@ import { prisma } from '@/lib/db';
 import { z } from 'zod';
 import { RMABLogger } from '@/lib/utils/logger';
 import { createRequestForUser } from '@/lib/services/request-creator.service';
+import { COMPLETED_STATUSES } from '@/lib/constants/request-statuses';
 
 const logger = RMABLogger.create('API.Requests');
 
@@ -146,10 +147,18 @@ export async function GET(request: NextRequest) {
         take: limit,
       });
 
+      const enriched = requests.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 };
+      });
+
       return NextResponse.json({
         success: true,
-        requests,
-        count: requests.length,
+        requests: enriched,
+        count: enriched.length,
       });
     } catch (error) {
       logger.error('Failed to get requests', { error: error instanceof Error ? error.message : String(error) });

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

@@ -37,9 +37,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' },
@@ -51,7 +53,7 @@ export async function GET(
     const userId = currentUser.sub || undefined;
     const enrichedBooks = await enrichAudiobooksWithMatches(detail.books, userId);
 
-    logger.info(`Series detail complete: "${detail.title}" (${enrichedBooks.length} books)`);
+    logger.info(`Series detail complete: "${detail.title}" (${enrichedBooks.length} books, page ${page})`);
 
     return NextResponse.json({
       success: true,
@@ -59,6 +61,8 @@ export async function GET(
         ...detail,
         books: enrichedBooks,
       },
+      hasMore: detail.hasMore,
+      page: detail.page,
     });
   } catch (error) {
     logger.error('Failed to fetch series detail', {

src/app/authors/[asin]/page.tsx

@@ -5,16 +5,17 @@
 
 'use client';
 
-import { use, useCallback } from 'react';
+import { use, useCallback, useMemo } from 'react';
 import { useRouter, useSearchParams } from 'next/navigation';
 import { Header } from '@/components/layout/Header';
 import { AudiobookGrid } from '@/components/audiobooks/AudiobookGrid';
+import { LoadMoreBar } from '@/components/ui/LoadMoreBar';
 import { AuthorDetailCard, AuthorDetailSkeleton } from '@/components/authors/AuthorDetailCard';
 import { SimilarAuthorsRow, SimilarAuthorsSkeleton } from '@/components/authors/SimilarAuthorsRow';
 import { useAuthorDetail, useAuthorBooks } from '@/lib/hooks/useAuthors';
+import { Audiobook } from '@/lib/hooks/useAudiobooks';
 import { ProtectedRoute } from '@/components/auth/ProtectedRoute';
-import { CardSizeControls } from '@/components/ui/CardSizeControls';
-import { SquareCoversToggle } from '@/components/ui/SquareCoversToggle';
+import { SectionToolbar } from '@/components/ui/SectionToolbar';
 import { usePreferences } from '@/contexts/PreferencesContext';
 
 export default function AuthorDetailPage({
@@ -27,11 +28,11 @@ export default function AuthorDetailPage({
   const searchParams = useSearchParams();
   const fromAuthorName = searchParams.get('from');
   const { author, isLoading: authorLoading } = useAuthorDetail(asin);
-  const { books, totalBooks, isLoading: booksLoading } = useAuthorBooks(
+  const { books, totalBooks, hasMore, isLoading: booksLoading, isLoadingMore, loadMore } = useAuthorBooks(
     asin,
     author?.name || null
   );
-  const { cardSize, setCardSize, squareCovers, setSquareCovers } = usePreferences();
+  const { cardSize, setCardSize, squareCovers, setSquareCovers, hideAvailable, setHideAvailable } = usePreferences();
 
   const handleBack = useCallback(() => {
     // Use browser back if we came from within the app, otherwise fallback to /authors
@@ -42,6 +43,20 @@ export default function AuthorDetailPage({
     }
   }, [router]);
 
+  // Filter out available titles when hideAvailable is enabled
+  const filteredBooks = useMemo(
+    () => hideAvailable ? books.filter((b: Audiobook) => !b.isAvailable && b.requestStatus !== 'completed') : books,
+    [books, hideAvailable]
+  );
+
+  // Header count text: reflects filtered counts
+  const visibleCount = filteredBooks.length;
+  const booksCountText = hasMore && totalBooks > books.length
+    ? `${visibleCount.toLocaleString()} of ${totalBooks.toLocaleString()} title${totalBooks !== 1 ? 's' : ''}`
+    : visibleCount > 0
+      ? `${visibleCount.toLocaleString()} title${visibleCount !== 1 ? 's' : ''}`
+      : '';
+
   return (
     <ProtectedRoute>
       <div className="min-h-screen">
@@ -91,27 +106,42 @@ export default function AuthorDetailPage({
                     <h2 className="text-xl sm:text-2xl font-bold text-gray-900 dark:text-gray-100 truncate">
                       Books
                     </h2>
-                    {!booksLoading && totalBooks > 0 && (
+                    {!booksLoading && booksCountText && (
                       <span className="text-sm text-gray-600 dark:text-gray-400 hidden sm:inline whitespace-nowrap">
-                        ({totalBooks} title{totalBooks !== 1 ? 's' : ''})
+                        ({booksCountText})
                       </span>
                     )}
-                    <div className="ml-auto flex items-center gap-1">
-                      <SquareCoversToggle enabled={squareCovers} onToggle={setSquareCovers} />
-                      <CardSizeControls size={cardSize} onSizeChange={setCardSize} />
-                    </div>
+                    <SectionToolbar
+                      hideAvailable={hideAvailable}
+                      onToggleHideAvailable={setHideAvailable}
+                      squareCovers={squareCovers}
+                      onToggleSquareCovers={setSquareCovers}
+                      cardSize={cardSize}
+                      onCardSizeChange={setCardSize}
+                    />
                   </div>
                 </div>
               </div>
 
               {/* Books Grid */}
               <AudiobookGrid
-                audiobooks={books}
+                audiobooks={filteredBooks}
                 isLoading={booksLoading}
                 emptyMessage={`No books found for ${author.name}`}
                 cardSize={cardSize}
                 squareCovers={squareCovers}
               />
+
+              {/* Load More Bar */}
+              {filteredBooks.length > 0 && (
+                <LoadMoreBar
+                  loadedCount={filteredBooks.length}
+                  totalCount={totalBooks > 0 ? totalBooks : undefined}
+                  hasMore={hasMore}
+                  isLoading={isLoadingMore}
+                  onLoadMore={loadMore}
+                />
+              )}
             </div>
           )}
         </main>

src/app/page.tsx

@@ -5,20 +5,19 @@
 
 'use client';
 
-import { useState, useRef } from 'react';
+import { useState, useRef, useMemo } from 'react';
 import { Header } from '@/components/layout/Header';
 import { AudiobookGrid } from '@/components/audiobooks/AudiobookGrid';
-import { useAudiobooks } from '@/lib/hooks/useAudiobooks';
+import { useAudiobooks, Audiobook } from '@/lib/hooks/useAudiobooks';
 import { ProtectedRoute } from '@/components/auth/ProtectedRoute';
 import { StickyPagination } from '@/components/ui/StickyPagination';
-import { CardSizeControls } from '@/components/ui/CardSizeControls';
-import { SquareCoversToggle } from '@/components/ui/SquareCoversToggle';
+import { SectionToolbar } from '@/components/ui/SectionToolbar';
 import { usePreferences } from '@/contexts/PreferencesContext';
 
 export default function HomePage() {
   const [popularPage, setPopularPage] = useState(1);
   const [newReleasesPage, setNewReleasesPage] = useState(1);
-  const { cardSize, setCardSize, squareCovers, setSquareCovers } = usePreferences();
+  const { cardSize, setCardSize, squareCovers, setSquareCovers, hideAvailable, setHideAvailable } = usePreferences();
 
   // Refs for auto-scrolling to section tops
   const popularSectionRef = useRef<HTMLElement>(null);
@@ -39,6 +38,16 @@ export default function HomePage() {
     message: newReleasesMessage,
   } = useAudiobooks('new-releases', 20, newReleasesPage);
 
+  // Filter out available titles when hideAvailable is enabled
+  const filteredPopular = useMemo(
+    () => hideAvailable ? popular.filter((b: Audiobook) => !b.isAvailable && b.requestStatus !== 'completed') : popular,
+    [popular, hideAvailable]
+  );
+  const filteredNewReleases = useMemo(
+    () => hideAvailable ? newReleases.filter((b: Audiobook) => !b.isAvailable && b.requestStatus !== 'completed') : newReleases,
+    [newReleases, hideAvailable]
+  );
+
   // Handle page changes with auto-scroll to section top
   const handlePopularPageChange = (page: number) => {
     setPopularPage(page);
@@ -66,10 +75,14 @@ export default function HomePage() {
                 <h2 className="text-xl sm:text-2xl md:text-3xl font-bold text-gray-900 dark:text-gray-100 truncate">
                   Popular Audiobooks
                 </h2>
-                <div className="ml-auto flex items-center gap-1">
-                  <SquareCoversToggle enabled={squareCovers} onToggle={setSquareCovers} />
-                  <CardSizeControls size={cardSize} onSizeChange={setCardSize} />
-                </div>
+                <SectionToolbar
+                  hideAvailable={hideAvailable}
+                  onToggleHideAvailable={setHideAvailable}
+                  squareCovers={squareCovers}
+                  onToggleSquareCovers={setSquareCovers}
+                  cardSize={cardSize}
+                  onCardSizeChange={setCardSize}
+                />
               </div>
             </div>
           </div>
@@ -87,7 +100,7 @@ export default function HomePage() {
               </div>
             ) : (
               <AudiobookGrid
-                audiobooks={popular}
+                audiobooks={filteredPopular}
                 isLoading={loadingPopular}
                 emptyMessage="No popular audiobooks available"
                 cardSize={cardSize}
@@ -107,10 +120,14 @@ export default function HomePage() {
                 <h2 className="text-xl sm:text-2xl md:text-3xl font-bold text-gray-900 dark:text-gray-100 truncate">
                   New Releases
                 </h2>
-                <div className="ml-auto flex items-center gap-1">
-                  <SquareCoversToggle enabled={squareCovers} onToggle={setSquareCovers} />
-                  <CardSizeControls size={cardSize} onSizeChange={setCardSize} />
-                </div>
+                <SectionToolbar
+                  hideAvailable={hideAvailable}
+                  onToggleHideAvailable={setHideAvailable}
+                  squareCovers={squareCovers}
+                  onToggleSquareCovers={setSquareCovers}
+                  cardSize={cardSize}
+                  onCardSizeChange={setCardSize}
+                />
               </div>
             </div>
           </div>
@@ -128,7 +145,7 @@ export default function HomePage() {
               </div>
             ) : (
               <AudiobookGrid
-                audiobooks={newReleases}
+                audiobooks={filteredNewReleases}
                 isLoading={loadingNewReleases}
                 emptyMessage="No new releases available"
                 cardSize={cardSize}

src/app/search/page.tsx

@@ -5,41 +5,48 @@
 
 'use client';
 
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback, useMemo } from 'react';
 import { Header } from '@/components/layout/Header';
 import { AudiobookGrid } from '@/components/audiobooks/AudiobookGrid';
-import { useSearch } from '@/lib/hooks/useAudiobooks';
+import { LoadMoreBar } from '@/components/ui/LoadMoreBar';
+import { useSearch, Audiobook } from '@/lib/hooks/useAudiobooks';
 import { ProtectedRoute } from '@/components/auth/ProtectedRoute';
-import { CardSizeControls } from '@/components/ui/CardSizeControls';
-import { SquareCoversToggle } from '@/components/ui/SquareCoversToggle';
+import { SectionToolbar } from '@/components/ui/SectionToolbar';
 import { usePreferences } from '@/contexts/PreferencesContext';
 
 export default function SearchPage() {
   const [query, setQuery] = useState('');
   const [debouncedQuery, setDebouncedQuery] = useState('');
-  const [page, setPage] = useState(1);
-  const { cardSize, setCardSize, squareCovers, setSquareCovers } = usePreferences();
+  const { cardSize, setCardSize, squareCovers, setSquareCovers, hideAvailable, setHideAvailable } = usePreferences();
 
   // Debounce search query
   useEffect(() => {
     const timer = setTimeout(() => {
       setDebouncedQuery(query);
-      setPage(1); // Reset to first page on new search
     }, 500);
 
     return () => clearTimeout(timer);
   }, [query]);
 
-  const { results, totalResults, hasMore, isLoading } = useSearch(debouncedQuery, page);
+  const { results, totalResults, hasMore, isLoading, isLoadingMore, loadMore } = useSearch(debouncedQuery);
+
+  // Filter out available titles when hideAvailable is enabled
+  const filteredResults = useMemo(
+    () => hideAvailable ? results.filter((b: Audiobook) => !b.isAvailable && b.requestStatus !== 'completed') : results,
+    [results, hideAvailable]
+  );
 
   const handleSearch = useCallback((e: React.FormEvent) => {
     e.preventDefault();
-    setPage(1);
   }, []);
 
-  const handleLoadMore = useCallback(() => {
-    setPage((prev) => prev + 1);
-  }, []);
+  // Header count text: reflects filtered counts
+  const visibleCount = filteredResults.length;
+  const countText = hasMore && totalResults > 0
+    ? `${visibleCount.toLocaleString()} of ${totalResults.toLocaleString()} result${totalResults !== 1 ? 's' : ''}`
+    : visibleCount > 0
+      ? `${visibleCount.toLocaleString()} result${visibleCount !== 1 ? 's' : ''}`
+      : '';
 
   return (
     <ProtectedRoute>
@@ -113,45 +120,42 @@ export default function SearchPage() {
                   <h2 className="text-xl sm:text-2xl font-bold text-gray-900 dark:text-gray-100 truncate">
                     Search Results
                   </h2>
-                  {!isLoading && totalResults > 0 && (
+                  {!isLoading && countText && (
                     <span className="text-sm text-gray-600 dark:text-gray-400 hidden sm:inline whitespace-nowrap">
-                      ({totalResults.toLocaleString()} result{totalResults !== 1 ? 's' : ''})
+                      ({countText})
                     </span>
                   )}
-                  <div className="ml-auto flex items-center gap-1">
-                    <SquareCoversToggle enabled={squareCovers} onToggle={setSquareCovers} />
-                    <CardSizeControls size={cardSize} onSizeChange={setCardSize} />
-                  </div>
+                  <SectionToolbar
+                    hideAvailable={hideAvailable}
+                    onToggleHideAvailable={setHideAvailable}
+                    squareCovers={squareCovers}
+                    onToggleSquareCovers={setSquareCovers}
+                    cardSize={cardSize}
+                    onCardSizeChange={setCardSize}
+                  />
                 </div>
               </div>
             </div>
 
             {/* Results Grid */}
             <AudiobookGrid
-              audiobooks={results}
-              isLoading={!!(isLoading && page === 1)}
+              audiobooks={filteredResults}
+              isLoading={isLoading}
               emptyMessage={`No results found for "${debouncedQuery}"`}
               cardSize={cardSize}
               squareCovers={squareCovers}
             />
 
-            {/* Load More */}
-            {hasMore && !isLoading && (
-              <div className="flex justify-center">
-                <button
-                  onClick={handleLoadMore}
-                  className="px-6 py-3 bg-blue-600 text-white font-medium rounded-lg hover:bg-blue-700 transition-colors"
-                >
-                  Load More Results
-                </button>
-              </div>
-            )}
-
-            {/* Loading More Indicator */}
-            {isLoading && page > 1 && (
-              <div className="flex justify-center">
-                <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600"></div>
-              </div>
+            {/* Load More Bar */}
+            {filteredResults.length > 0 && (
+              <LoadMoreBar
+                loadedCount={filteredResults.length}
+                totalCount={totalResults}
+                hasMore={hasMore}
+                isLoading={isLoadingMore}
+                onLoadMore={loadMore}
+                itemLabel="results"
+              />
             )}
           </div>
         ) : (

src/app/series/[asin]/page.tsx

@@ -5,16 +5,17 @@
 
 'use client';
 
-import { use, useCallback } from 'react';
+import { use, useCallback, useMemo } from 'react';
 import { useRouter, useSearchParams } from 'next/navigation';
 import { Header } from '@/components/layout/Header';
 import { AudiobookGrid } from '@/components/audiobooks/AudiobookGrid';
+import { LoadMoreBar } from '@/components/ui/LoadMoreBar';
 import { SeriesDetailCard, SeriesDetailSkeleton } from '@/components/series/SeriesDetailCard';
 import { SimilarSeriesRow, SimilarSeriesSkeleton } from '@/components/series/SimilarSeriesRow';
 import { useSeriesDetail } from '@/lib/hooks/useSeries';
+import { Audiobook } from '@/lib/hooks/useAudiobooks';
 import { ProtectedRoute } from '@/components/auth/ProtectedRoute';
-import { CardSizeControls } from '@/components/ui/CardSizeControls';
-import { SquareCoversToggle } from '@/components/ui/SquareCoversToggle';
+import { SectionToolbar } from '@/components/ui/SectionToolbar';
 import { usePreferences } from '@/contexts/PreferencesContext';
 
 export default function SeriesDetailPage({
@@ -26,8 +27,8 @@ export default function SeriesDetailPage({
   const router = useRouter();
   const searchParams = useSearchParams();
   const fromSeriesTitle = searchParams.get('from');
-  const { series, isLoading: seriesLoading } = useSeriesDetail(asin);
-  const { cardSize, setCardSize, squareCovers, setSquareCovers } = usePreferences();
+  const { series, hasMore, isLoading: seriesLoading, isLoadingMore, loadMore } = useSeriesDetail(asin);
+  const { cardSize, setCardSize, squareCovers, setSquareCovers, hideAvailable, setHideAvailable } = usePreferences();
 
   const handleBack = useCallback(() => {
     // Use browser back if we came from within the app, otherwise fallback to /series
@@ -38,6 +39,24 @@ export default function SeriesDetailPage({
     }
   }, [router]);
 
+  // Filter out available titles when hideAvailable is enabled
+  const filteredBooks = useMemo(
+    () => series && hideAvailable
+      ? series.books.filter((b: Audiobook) => !b.isAvailable && b.requestStatus !== 'completed')
+      : series?.books ?? [],
+    [series, hideAvailable]
+  );
+
+  // Header count text: reflects filtered counts
+  const visibleCount = filteredBooks.length;
+  const booksCountText = series
+    ? hasMore && series.bookCount > series.books.length
+      ? `${visibleCount.toLocaleString()} of ${series.bookCount.toLocaleString()} title${series.bookCount !== 1 ? 's' : ''}`
+      : visibleCount > 0
+        ? `${visibleCount.toLocaleString()} title${visibleCount !== 1 ? 's' : ''}`
+        : ''
+    : '';
+
   return (
     <ProtectedRoute>
       <div className="min-h-screen">
@@ -87,27 +106,42 @@ export default function SeriesDetailPage({
                     <h2 className="text-xl sm:text-2xl font-bold text-gray-900 dark:text-gray-100 truncate">
                       Books in Series
                     </h2>
-                    {series.books.length > 0 && (
+                    {booksCountText && (
                       <span className="text-sm text-gray-600 dark:text-gray-400 hidden sm:inline whitespace-nowrap">
-                        ({series.books.length} title{series.books.length !== 1 ? 's' : ''})
+                        ({booksCountText})
                       </span>
                     )}
-                    <div className="ml-auto flex items-center gap-1">
-                      <SquareCoversToggle enabled={squareCovers} onToggle={setSquareCovers} />
-                      <CardSizeControls size={cardSize} onSizeChange={setCardSize} />
-                    </div>
+                    <SectionToolbar
+                      hideAvailable={hideAvailable}
+                      onToggleHideAvailable={setHideAvailable}
+                      squareCovers={squareCovers}
+                      onToggleSquareCovers={setSquareCovers}
+                      cardSize={cardSize}
+                      onCardSizeChange={setCardSize}
+                    />
                   </div>
                 </div>
               </div>
 
               {/* Books Grid */}
               <AudiobookGrid
-                audiobooks={series.books}
+                audiobooks={filteredBooks}
                 isLoading={seriesLoading}
                 emptyMessage={`No books found for ${series.title}`}
                 cardSize={cardSize}
                 squareCovers={squareCovers}
               />
+
+              {/* Load More Bar */}
+              {filteredBooks.length > 0 && (
+                <LoadMoreBar
+                  loadedCount={filteredBooks.length}
+                  totalCount={series.bookCount > 0 ? series.bookCount : undefined}
+                  hasMore={hasMore}
+                  isLoading={isLoadingMore}
+                  onLoadMore={loadMore}
+                />
+              )}
             </div>
           )}
         </main>

src/app/setup/steps/BookDateStep.tsx

@@ -134,6 +134,7 @@ export function BookDateStep({
         >
           <option value="openai">OpenAI</option>
           <option value="claude">Claude (Anthropic)</option>
+          <option value="gemini">Google Gemini</option>
         </select>
       </div>
 
@@ -152,7 +153,7 @@ export function BookDateStep({
             onUpdate('bookdateConfigured', false);
             onUpdate('bookdateModels', []);
           }}
-          placeholder={bookdateProvider === 'openai' ? 'sk-...' : 'sk-ant-...'}
+          placeholder={bookdateProvider === 'openai' ? 'sk-...' : bookdateProvider === 'gemini' ? 'AIza...' : 'sk-ant-...'}
           className="w-full px-4 py-2 border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-800 text-gray-900 dark:text-white focus:ring-2 focus:ring-blue-500"
         />
         <p className="text-xs text-gray-500 dark:text-gray-400 mt-1">

src/components/admin/download-clients/DownloadClientCard.tsx

@@ -29,6 +29,7 @@ export function DownloadClientCard({ client, onEdit, onDelete }: DownloadClientC
     transmission: 'bg-green-100 dark:bg-green-900/30 text-green-700 dark:text-green-300',
     sabnzbd: 'bg-purple-100 dark:bg-purple-900/30 text-purple-700 dark:text-purple-300',
     nzbget: 'bg-orange-100 dark:bg-orange-900/30 text-orange-700 dark:text-orange-300',
+    deluge: 'bg-teal-100 dark:bg-teal-900/30 text-teal-700 dark:text-teal-300',
   };
   const typeColor = typeColorMap[client.type] || typeColorMap.qbittorrent;
 

src/components/admin/download-clients/DownloadClientManagement.tsx

@@ -253,7 +253,7 @@ export function DownloadClientManagement({
         <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-3">
           Add Download Client
         </h3>
-        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-5 gap-4">
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-5 gap-4">
           {/* qBittorrent Card */}
           <div className={`bg-white dark:bg-gray-800 rounded-lg shadow-md border border-gray-200 dark:border-gray-700 p-6${hasTorrentClient ? ' opacity-50' : ''}`}>
             <div className="flex items-start justify-between mb-3">
@@ -316,15 +316,15 @@ export function DownloadClientManagement({
             )}
           </div>
 
-          {/* RDT-Client Card */}
+          {/* Deluge Card */}
           <div className={`bg-white dark:bg-gray-800 rounded-lg shadow-md border border-gray-200 dark:border-gray-700 p-6${hasTorrentClient ? ' opacity-50' : ''}`}>
             <div className="flex items-start justify-between mb-3">
               <div>
                 <h4 className="text-base font-semibold text-gray-900 dark:text-gray-100 mb-1">
-                  RDT-Client
+                  Deluge
                 </h4>
                 <p className="text-sm text-gray-600 dark:text-gray-400">
-                  Torrent / Debrid
+                  Torrent downloads
                 </p>
               </div>
               <span className="inline-block text-xs px-2 py-1 rounded bg-teal-100 dark:bg-teal-900/30 text-teal-700 dark:text-teal-300 font-medium">
@@ -337,12 +337,12 @@ export function DownloadClientManagement({
               </div>
             ) : (
               <Button
-                onClick={() => handleAddClient('rdtclient')}
+                onClick={() => handleAddClient('deluge')}
                 variant="primary"
                 size="sm"
                 disabled={loading}
               >
-                Add RDT-Client
+                Add Deluge
               </Button>
             )}
           </div>

src/components/admin/download-clients/DownloadClientModal.tsx

@@ -278,7 +278,7 @@ export function DownloadClientModal({
         type,
         name,
         url,
-        username: type !== 'sabnzbd' ? username : undefined,
+        username: type !== 'sabnzbd' && type !== 'deluge' ? username : undefined,
         password: password === '********' ? undefined : password, // Don't send masked password on edit
         enabled,
         disableSSLVerify,
@@ -338,7 +338,7 @@ export function DownloadClientModal({
           <Input
             value={url}
             onChange={(e) => setUrl(e.target.value)}
-            placeholder={type === 'rdtclient' ? 'http://localhost:6500' : type === 'transmission' ? 'http://localhost:9091' : type === 'qbittorrent' ? 'http://localhost:8080' : type === 'nzbget' ? 'http://localhost:6789' : 'http://localhost:8081'}
+            placeholder={type === 'transmission' ? 'http://localhost:9091' : type === 'qbittorrent' ? 'http://localhost:8080' : type === 'deluge' ? 'http://localhost:8112' : type === 'nzbget' ? 'http://localhost:6789' : 'http://localhost:8081'}
             error={errors.url}
           />
           <p className="mt-1 text-xs text-gray-500 dark:text-gray-400">
@@ -346,8 +346,8 @@ export function DownloadClientModal({
           </p>
         </div>
 
-        {/* Username (qBittorrent and Transmission) */}
-        {type !== 'sabnzbd' && (
+        {/* Username (qBittorrent, Transmission, NZBGet — not SABnzbd or Deluge) */}
+        {type !== 'sabnzbd' && type !== 'deluge' && (
           <div>
             <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">
               Username
@@ -383,6 +383,11 @@ export function DownloadClientModal({
               Configured in NZBGet under Settings → Security → ControlPassword
             </p>
           )}
+          {type === 'deluge' && (
+            <p className="mt-1 text-xs text-gray-500 dark:text-gray-400">
+              Web UI password configured in Deluge under Preferences → Interface
+            </p>
+          )}
         </div>
 
         {/* SSL Verification */}
@@ -448,7 +453,7 @@ export function DownloadClientModal({
             <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">
               Post-Import Category
             </label>
-            {type === 'qbittorrent' && availableCategories.length > 0 ? (
+            {(type === 'qbittorrent' || type === 'deluge') && availableCategories.length > 0 ? (
               <select
                 value={postImportCategory}
                 onChange={(e) => setPostImportCategory(e.target.value)}

src/components/admin/users/GlobalUserSettingsModal.tsx

@@ -14,6 +14,8 @@ interface GlobalUserSettingsModalProps {
   onToggleAutoApprove: (newValue: boolean) => void;
   globalInteractiveSearch: boolean;
   onToggleInteractiveSearch: (newValue: boolean) => void;
+  globalDownloadAccess: boolean;
+  onToggleDownloadAccess: (newValue: boolean) => void;
 }
 
 export function GlobalUserSettingsModal({
@@ -23,6 +25,8 @@ export function GlobalUserSettingsModal({
   onToggleAutoApprove,
   globalInteractiveSearch,
   onToggleInteractiveSearch,
+  globalDownloadAccess,
+  onToggleDownloadAccess,
 }: GlobalUserSettingsModalProps) {
   return (
     <Modal isOpen={isOpen} onClose={onClose} title="Global User Settings" size="sm">
@@ -84,6 +88,35 @@ export function GlobalUserSettingsModal({
             </p>
           </div>
         </div>
+
+        {/* Download Access Setting */}
+        <div className="flex items-start gap-4">
+          <button
+            onClick={() => onToggleDownloadAccess(!globalDownloadAccess)}
+            className="relative inline-flex h-6 w-11 flex-shrink-0 items-center rounded-full transition-colors focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:focus:ring-offset-gray-800 mt-0.5"
+            style={{ backgroundColor: globalDownloadAccess ? '#3b82f6' : '#d1d5db' }}
+            role="switch"
+            aria-checked={globalDownloadAccess}
+            aria-label="Download Access"
+          >
+            <span
+              className={`inline-block h-4 w-4 transform rounded-full bg-white transition-transform ${
+                globalDownloadAccess ? 'translate-x-6' : 'translate-x-1'
+              }`}
+            />
+          </button>
+          <div className="flex-1">
+            <label
+              onClick={() => onToggleDownloadAccess(!globalDownloadAccess)}
+              className="block text-sm font-semibold text-gray-900 dark:text-gray-100 cursor-pointer"
+            >
+              Download Access
+            </label>
+            <p className="text-sm text-gray-500 dark:text-gray-400 mt-1">
+              When enabled, all users can download audiobook files. When disabled, you can grant access per-user from the users table.
+            </p>
+          </div>
+        </div>
       </div>
     </Modal>
   );

src/components/admin/users/UserPermissionsModal.tsx

@@ -15,6 +15,7 @@ interface UserPermissionsUser {
   role: 'user' | 'admin';
   autoApproveRequests: boolean | null;
   interactiveSearchAccess: boolean | null;
+  downloadAccess: boolean | null;
 }
 
 interface UserPermissionsModalProps {
@@ -23,8 +24,10 @@ interface UserPermissionsModalProps {
   user: UserPermissionsUser | null;
   globalAutoApprove: boolean;
   globalInteractiveSearch: boolean;
+  globalDownloadAccess: boolean;
   onToggleAutoApprove: (user: UserPermissionsUser, newValue: boolean) => void;
   onToggleInteractiveSearch: (user: UserPermissionsUser, newValue: boolean) => void;
+  onToggleDownloadAccess: (user: UserPermissionsUser, newValue: boolean) => void;
 }
 
 interface PermissionToggleProps {
@@ -86,8 +89,10 @@ export function UserPermissionsModal({
   user,
   globalAutoApprove,
   globalInteractiveSearch,
+  globalDownloadAccess,
   onToggleAutoApprove,
   onToggleInteractiveSearch,
+  onToggleDownloadAccess,
 }: UserPermissionsModalProps) {
   if (!user) return null;
 
@@ -103,6 +108,11 @@ export function UserPermissionsModal({
   const isSearchDisabled = isAdmin || isSearchGlobalOverride;
   const searchValue = isAdmin ? true : isSearchGlobalOverride ? true : (user.interactiveSearchAccess ?? false);
 
+  // Download Access resolution
+  const isDownloadGlobalOverride = !isAdmin && globalDownloadAccess;
+  const isDownloadDisabled = isAdmin || isDownloadGlobalOverride;
+  const downloadValue = isAdmin ? true : isDownloadGlobalOverride ? true : (user.downloadAccess ?? false);
+
   const getDisabledMessage = (isAdminUser: boolean, isGlobalOverride: boolean, adminMessage: string, globalMessage: string): string | undefined => {
     if (isAdminUser) return adminMessage;
     if (isGlobalOverride) return globalMessage;
@@ -176,6 +186,21 @@ export function UserPermissionsModal({
               description="When enabled, this user can manually search and select torrents and ebooks"
               onToggle={() => onToggleInteractiveSearch(user, !searchValue)}
             />
+
+            {/* Download Access Permission */}
+            <PermissionToggle
+              label="Download Access"
+              ariaLabel="Download Access"
+              value={downloadValue}
+              disabled={isDownloadDisabled}
+              disabledMessage={getDisabledMessage(
+                isAdmin, isDownloadGlobalOverride,
+                'Admins always have download access',
+                'Controlled by global download access setting'
+              )}
+              description="When enabled, this user can download audiobook files directly"
+              onToggle={() => onToggleDownloadAccess(user, !downloadValue)}
+            />
           </div>
         </div>
       </div>

src/components/audiobooks/AudiobookCard.tsx

@@ -56,8 +56,13 @@ export function AudiobookCard({
   const [showToast, setShowToast] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [showModal, setShowModal] = useState(false);
+  const [localRequestStatus, setLocalRequestStatus] = useState<string | undefined>(undefined);
 
-  const status = getStatusConfig(audiobook);
+  // Build a display-only audiobook with the local status override
+  const displayAudiobook = localRequestStatus !== undefined
+    ? { ...audiobook, requestStatus: localRequestStatus }
+    : audiobook;
+  const status = getStatusConfig(displayAudiobook);
 
   const handleRequest = async (e: React.MouseEvent) => {
     e.stopPropagation();
@@ -69,6 +74,7 @@ export function AudiobookCard({
 
     try {
       await createRequest(audiobook);
+      setLocalRequestStatus('pending');
       setShowToast(true);
       setTimeout(() => setShowToast(false), 2500);
       onRequestSuccess?.();
@@ -240,8 +246,9 @@ export function AudiobookCard({
         isOpen={showModal}
         onClose={() => setShowModal(false)}
         onRequestSuccess={onRequestSuccess}
-        isRequested={audiobook.isRequested}
-        requestStatus={audiobook.requestStatus}
+        onStatusChange={(newStatus) => setLocalRequestStatus(newStatus)}
+        isRequested={audiobook.isRequested || localRequestStatus !== undefined}
+        requestStatus={displayAudiobook.requestStatus}
         isAvailable={audiobook.isAvailable}
         requestedByUsername={audiobook.requestedByUsername}
         hasReportedIssue={audiobook.hasReportedIssue}

src/components/audiobooks/AudiobookDetailsModal.tsx

@@ -13,17 +13,21 @@ import Image from 'next/image';
 import Link from 'next/link';
 import { createPortal } from 'react-dom';
 import { useAudiobookDetails } from '@/lib/hooks/useAudiobooks';
-import { useCreateRequest, useEbookStatus, useFetchEbookByAsin } from '@/lib/hooks/useRequests';
+import { useCreateRequest, useEbookStatus, useDownloadStatus, useFetchEbookByAsin } from '@/lib/hooks/useRequests';
 import { useAuth } from '@/contexts/AuthContext';
 import { usePreferences } from '@/contexts/PreferencesContext';
 import { InteractiveTorrentSearchModal } from '@/components/requests/InteractiveTorrentSearchModal';
 import { ReportIssueModal } from '@/components/audiobooks/ReportIssueModal';
+import { ManualImportBrowser } from '@/components/audiobooks/ManualImportBrowser';
+import { FolderArrowDownIcon } from '@heroicons/react/24/outline';
+import { fetchWithAuth } from '@/lib/utils/api';
 
 interface AudiobookDetailsModalProps {
   asin: string;
   isOpen: boolean;
   onClose: () => void;
   onRequestSuccess?: () => void;
+  onStatusChange?: (newStatus: string) => void;
   isRequested?: boolean;
   requestStatus?: string | null;
   isAvailable?: boolean;
@@ -63,6 +67,7 @@ export function AudiobookDetailsModal({
   isOpen,
   onClose,
   onRequestSuccess,
+  onStatusChange,
   isRequested = false,
   requestStatus = null,
   isAvailable = false,
@@ -75,6 +80,7 @@ export function AudiobookDetailsModal({
   const { audiobook, audibleBaseUrl, isLoading, error } = useAudiobookDetails(isOpen ? asin : null);
   const { createRequest, isLoading: isRequesting } = useCreateRequest();
   const { ebookStatus, revalidate: revalidateEbookStatus } = useEbookStatus(isOpen && isAvailable ? asin : null);
+  const { downloadAvailable, requestId } = useDownloadStatus(isOpen ? asin : null);
   const { fetchEbook, isLoading: isFetchingEbook } = useFetchEbookByAsin();
 
   const [showToast, setShowToast] = useState(false);
@@ -84,9 +90,18 @@ export function AudiobookDetailsModal({
   const [showInteractiveSearch, setShowInteractiveSearch] = useState(false);
   const [showInteractiveSearchEbook, setShowInteractiveSearchEbook] = useState(false);
   const [showReportIssue, setShowReportIssue] = useState(false);
+  const [showManualImport, setShowManualImport] = useState(false);
   const [asinCopied, setAsinCopied] = useState(false);
+  const [localRequestStatus, setLocalRequestStatus] = useState<string | null>(requestStatus ?? null);
+  const [isDownloading, setIsDownloading] = useState(false);
 
-  const status = getStatusInfo(isAvailable, requestStatus, requestedByUsername);
+  // Sync local status when the prop changes (e.g. page data refreshes)
+  useEffect(() => {
+    setLocalRequestStatus(requestStatus ?? null);
+  }, [requestStatus]);
+
+  const effectiveStatus = localRequestStatus;
+  const status = getStatusInfo(isAvailable, effectiveStatus, requestedByUsername);
   const canShowEbookButtons = isAvailable && ebookStatus?.ebookSourcesEnabled && !ebookStatus?.hasActiveEbookRequest;
 
   useEffect(() => {
@@ -119,6 +134,8 @@ export function AudiobookDetailsModal({
 
     try {
       await createRequest(audiobook);
+      setLocalRequestStatus('pending');
+      onStatusChange?.('pending');
       showNotification('Request created!');
       setTimeout(onClose, 1500);
       onRequestSuccess?.();
@@ -160,6 +177,22 @@ export function AudiobookDetailsModal({
     }
   };
 
+  const handleDownload = async () => {
+    if (!requestId) return;
+    setIsDownloading(true);
+    try {
+      const res = await fetchWithAuth(`/api/requests/${requestId}/download-token`, { method: 'POST' });
+      if (!res.ok) throw new Error('Failed to get download link');
+      const { downloadUrl } = await res.json();
+      window.location.href = downloadUrl;
+    } catch (err) {
+      console.error('Failed to initiate download:', err);
+      showNotification('Failed to start download. Please try again.', 'error');
+    } finally {
+      setIsDownloading(false);
+    }
+  };
+
   const formatDuration = (minutes?: number) => {
     if (!minutes) return null;
     const hours = Math.floor(minutes / 60);
@@ -461,6 +494,36 @@ export function AudiobookDetailsModal({
                       </svg>
                     </a>
                   </div>
+
+                  {/* Download Link - subtle utility, visible from any context */}
+                  {isAvailable && downloadAvailable && requestId && user?.permissions?.download !== false && (
+                    <div>
+                      <p className="text-gray-500 dark:text-gray-400">Download</p>
+                      <button
+                        onClick={handleDownload}
+                        disabled={isDownloading}
+                        className="inline-flex items-center gap-1 text-blue-600 dark:text-blue-400 hover:underline disabled:opacity-50 disabled:cursor-not-allowed transition-opacity"
+                        aria-label={isDownloading ? 'Preparing download...' : 'Download audiobook files'}
+                      >
+                        {isDownloading ? (
+                          <>
+                            <svg className="w-3.5 h-3.5 animate-spin flex-shrink-0" viewBox="0 0 24 24" fill="none">
+                              <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="3" />
+                              <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
+                            </svg>
+                            <span>Preparing...</span>
+                          </>
+                        ) : (
+                          <>
+                            <svg className="w-3.5 h-3.5 flex-shrink-0" 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>
+                            <span>Download files</span>
+                          </>
+                        )}
+                      </button>
+                    </div>
+                  )}
                 </div>
               </div>
 
@@ -485,7 +548,8 @@ export function AudiobookDetailsModal({
           )}
         </div>
 
-        {/* Sticky Action Bar - hidden when opened from bookdate */}
+
+        {/* Sticky Action Bar - hidden when opened from read-only contexts */}
         {audiobook && !isLoading && !hideRequestActions && (
           <div
             className="sticky bottom-0 z-20 p-4 bg-white/80 dark:bg-gray-900/80 backdrop-blur-md border-t border-gray-200/50 dark:border-gray-700/50"
@@ -556,6 +620,17 @@ export function AudiobookDetailsModal({
                 </button>
               )}
 
+              {/* Manual Import - admin only, hidden during active processing and completed states */}
+              {user?.role === 'admin' && !isAvailable && !['downloading', 'processing', 'searching', 'downloaded', 'completed', 'available'].includes(effectiveStatus || '') && (
+                <button
+                  onClick={() => setShowManualImport(true)}
+                  className="p-3 rounded-xl bg-teal-100 dark:bg-teal-900/30 text-teal-600 dark:text-teal-400 hover:bg-teal-200 dark:hover:bg-teal-900/50 transition-colors"
+                  title="Manual Import"
+                >
+                  <FolderArrowDownIcon className="w-6 h-6" />
+                </button>
+              )}
+
               {/* Ebook Buttons - only when available and enabled */}
               {canShowEbookButtons && user && (
                 <>
@@ -674,6 +749,26 @@ export function AudiobookDetailsModal({
           coverArtUrl={audiobook.coverArtUrl}
         />
       )}
+
+      {/* Manual Import Browser */}
+      {showManualImport && audiobook && (
+        <ManualImportBrowser
+          isOpen={showManualImport}
+          onClose={() => setShowManualImport(false)}
+          onSuccess={() => {
+            setLocalRequestStatus('processing');
+            onStatusChange?.('processing');
+            showNotification('Import started — files are being processed');
+            onRequestSuccess?.();
+          }}
+          audiobook={{
+            asin: audiobook.asin,
+            title: audiobook.title,
+            author: audiobook.author,
+            coverArtUrl: audiobook.coverArtUrl,
+          }}
+        />
+      )}
     </>
   );
 }

src/components/audiobooks/ManualImportBrowser.tsx

@@ -0,0 +1,308 @@
+/**
+ * Component: Manual Import File Browser
+ * Documentation: documentation/features/manual-import.md
+ *
+ * Two-phase modal for browsing server directories and importing audiobook files.
+ * Phase 1 (BrowsePhase): Directory navigation with audio file detection.
+ * Phase 2 (ConfirmPhase): Review and start import.
+ *
+ * Sub-components: manual-import/BrowsePhase.tsx, manual-import/ConfirmPhase.tsx
+ */
+
+'use client';
+
+import React, { useState, useEffect, useCallback } from 'react';
+import { createPortal } from 'react-dom';
+import { fetchWithAuth } from '@/lib/utils/api';
+import { FolderArrowDownIcon, XMarkIcon } from '@heroicons/react/24/outline';
+import { RootEntry, DirectoryEntry, AudioFileEntry, SlideDirection } from './manual-import/types';
+import { BrowsePhase } from './manual-import/BrowsePhase';
+import { ConfirmPhase } from './manual-import/ConfirmPhase';
+
+interface ManualImportBrowserProps {
+  isOpen: boolean;
+  onClose: () => void;
+  onSuccess: () => void;
+  audiobook: {
+    asin: string;
+    title: string;
+    author: string;
+    coverArtUrl?: string;
+  };
+}
+
+type Phase = 'browse' | 'confirm';
+
+export function ManualImportBrowser({
+  isOpen,
+  onClose,
+  onSuccess,
+  audiobook,
+}: ManualImportBrowserProps) {
+  const [phase, setPhase] = useState<Phase>('browse');
+  const [slideDirection, setSlideDirection] = useState<SlideDirection>('right');
+
+  // Browse state
+  const [roots, setRoots] = useState<RootEntry[]>([]);
+  const [currentPath, setCurrentPath] = useState<string | null>(null);
+  const [entries, setEntries] = useState<DirectoryEntry[]>([]);
+  const [selectedPath, setSelectedPath] = useState<string | null>(null);
+  const [selectedAudioCount, setSelectedAudioCount] = useState(0);
+  const [selectedSize, setSelectedSize] = useState(0);
+  const [selectedAudioFiles, setSelectedAudioFiles] = useState<AudioFileEntry[]>([]);
+  const [currentAudioFiles, setCurrentAudioFiles] = useState<AudioFileEntry[]>([]);
+  const [pathHistory, setPathHistory] = useState<string[]>([]);
+
+  // Loading/error state
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [isImporting, setIsImporting] = useState(false);
+  const [importError, setImportError] = useState<string | null>(null);
+
+  // Cleanup source toggle
+  const [cleanupSource, setCleanupSource] = useState(false);
+
+  // Hover state for folder icon swap
+  const [hoveredFolder, setHoveredFolder] = useState<string | null>(null);
+
+  // Fetch roots on open
+  useEffect(() => {
+    if (!isOpen) return;
+    setPhase('browse');
+    setCurrentPath(null);
+    setSelectedPath(null);
+    setPathHistory([]);
+    fetchRoots();
+  }, [isOpen]);
+
+  const fetchRoots = async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const res = await fetchWithAuth('/api/admin/filesystem/browse');
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({ error: 'Failed to load' }));
+        throw new Error(data.error || 'Failed to load directories');
+      }
+      const data = await res.json();
+      setRoots(data.roots || []);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load directories');
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  const fetchDirectory = useCallback(async (dirPath: string) => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const res = await fetchWithAuth(
+        `/api/admin/filesystem/browse?path=${encodeURIComponent(dirPath)}`
+      );
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({ error: 'Failed to load' }));
+        throw new Error(data.error || 'Failed to browse directory');
+      }
+      const data = await res.json();
+      setEntries(data.entries || []);
+      setCurrentAudioFiles(data.audioFiles || []);
+      setCurrentPath(data.path || dirPath);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to browse directory');
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  const navigateInto = (dirPath: string) => {
+    setSlideDirection('right');
+    if (currentPath) {
+      setPathHistory((prev) => [...prev, currentPath]);
+    }
+    setSelectedPath(null);
+    fetchDirectory(dirPath);
+  };
+
+  const navigateBack = () => {
+    setSlideDirection('left');
+    setSelectedPath(null);
+    if (pathHistory.length > 0) {
+      const prevPath = pathHistory[pathHistory.length - 1];
+      setPathHistory((prev) => prev.slice(0, -1));
+      fetchDirectory(prevPath);
+    } else {
+      setCurrentPath(null);
+      setEntries([]);
+    }
+  };
+
+  const navigateToRoot = () => {
+    setSlideDirection('left');
+    setSelectedPath(null);
+    setCurrentPath(null);
+    setEntries([]);
+    setCurrentAudioFiles([]);
+    setPathHistory([]);
+  };
+
+  const navigateToBreadcrumb = (index: number) => {
+    if (!currentPath) return;
+    setSlideDirection('left');
+    setSelectedPath(null);
+    const allPaths = [...pathHistory, currentPath];
+    const targetPath = allPaths[index];
+    if (targetPath) {
+      setPathHistory(allPaths.slice(0, index));
+      fetchDirectory(targetPath);
+    } else {
+      navigateToRoot();
+    }
+  };
+
+  const handleFolderClick = (entry: DirectoryEntry) => {
+    const fullPath = currentPath + '/' + entry.name;
+    navigateInto(fullPath);
+  };
+
+  const handleSelectCurrentFolder = () => {
+    if (!currentPath || currentAudioFiles.length === 0) return;
+    setSelectedPath(currentPath);
+    setSelectedAudioCount(currentAudioFiles.length);
+    setSelectedSize(currentAudioFiles.reduce((sum, f) => sum + f.size, 0));
+    setSelectedAudioFiles(currentAudioFiles);
+    setSlideDirection('right');
+    setPhase('confirm');
+  };
+
+  const handleBackToBrowse = () => {
+    setSlideDirection('left');
+    setPhase('browse');
+  };
+
+  const handleStartImport = async () => {
+    if (!selectedPath) return;
+    setIsImporting(true);
+    setImportError(null);
+    try {
+      const res = await fetchWithAuth('/api/admin/manual-import', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          asin: audiobook.asin,
+          folderPath: selectedPath,
+          cleanupSource,
+        }),
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        throw new Error(data.error || 'Import failed');
+      }
+      onSuccess();
+      onClose();
+    } catch (err) {
+      setImportError(err instanceof Error ? err.message : 'Import failed');
+    } finally {
+      setIsImporting(false);
+    }
+  };
+
+  // Build breadcrumb segments
+  const breadcrumbs = (() => {
+    if (!currentPath) return [];
+    const allPaths = [...pathHistory, currentPath];
+    return allPaths.map((p) => {
+      const parts = p.replace(/\\/g, '/').split('/');
+      return parts[parts.length - 1] || p;
+    });
+  })();
+
+  const visibleBreadcrumbs = (() => {
+    if (breadcrumbs.length <= 3) return breadcrumbs.map((b, i) => ({ label: b, index: i }));
+    return [
+      { label: breadcrumbs[0], index: 0 },
+      { label: '...', index: -1 },
+      { label: breadcrumbs[breadcrumbs.length - 1], index: breadcrumbs.length - 1 },
+    ];
+  })();
+
+  if (!isOpen) return null;
+
+  const slideClass =
+    slideDirection === 'right'
+      ? 'animate-[slideRight_200ms_ease-out]'
+      : 'animate-[slideLeft_200ms_ease-out]';
+
+  const modalContent = (
+    <div
+      className="fixed inset-0 z-[60] flex items-center justify-center bg-black/60 backdrop-blur-sm"
+      style={{ height: '100dvh' }}
+      onClick={onClose}
+    >
+      <div
+        className="relative w-full max-w-2xl bg-white dark:bg-gray-900 rounded-2xl shadow-2xl overflow-hidden flex flex-col"
+        style={{ height: 'min(640px, 85vh)' }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between px-5 py-4 border-b border-gray-200 dark:border-gray-700/50">
+          <div className="flex items-center gap-2.5">
+            <FolderArrowDownIcon className="w-5 h-5 text-blue-600 dark:text-blue-400" />
+            <h2 className="text-lg font-semibold text-gray-900 dark:text-gray-100">
+              {phase === 'browse' ? 'Manual Import' : 'Confirm Import'}
+            </h2>
+          </div>
+          <button
+            onClick={onClose}
+            className="p-1.5 rounded-lg hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors"
+          >
+            <XMarkIcon className="w-5 h-5 text-gray-500 dark:text-gray-400" />
+          </button>
+        </div>
+
+        {/* Content */}
+        <div className="flex-1 min-h-0 overflow-hidden">
+          {phase === 'browse' ? (
+            <BrowsePhase
+              roots={roots}
+              currentPath={currentPath}
+              entries={entries}
+              currentAudioFiles={currentAudioFiles}
+              isLoading={isLoading}
+              error={error}
+              hoveredFolder={hoveredFolder}
+              breadcrumbs={visibleBreadcrumbs}
+              slideClass={slideClass}
+              onNavigateInto={navigateInto}
+              onNavigateBack={navigateBack}
+              onNavigateToRoot={navigateToRoot}
+              onNavigateToBreadcrumb={navigateToBreadcrumb}
+              onFolderClick={handleFolderClick}
+              onSelectCurrentFolder={handleSelectCurrentFolder}
+              onHoverFolder={setHoveredFolder}
+              onRetry={currentPath ? () => fetchDirectory(currentPath) : fetchRoots}
+            />
+          ) : (
+            <ConfirmPhase
+              audiobook={audiobook}
+              selectedPath={selectedPath!}
+              audioFileCount={selectedAudioCount}
+              totalSize={selectedSize}
+              audioFiles={selectedAudioFiles}
+              isImporting={isImporting}
+              importError={importError}
+              slideClass={slideClass}
+              cleanupSource={cleanupSource}
+              onCleanupSourceChange={setCleanupSource}
+              onBack={handleBackToBrowse}
+              onStartImport={handleStartImport}
+            />
+          )}
+        </div>
+
+      </div>
+    </div>
+  );
+
+  return createPortal(modalContent, document.body);
+}

src/components/audiobooks/manual-import/BrowsePhase.tsx

@@ -0,0 +1,278 @@
+/**
+ * Component: Manual Import Browse Phase
+ * Documentation: documentation/features/manual-import.md
+ *
+ * Directory listing with root tiles, breadcrumb navigation,
+ * folder metadata, audio file badges, and selection state.
+ */
+
+'use client';
+
+import React from 'react';
+import {
+  FolderIcon,
+  FolderOpenIcon,
+  FolderArrowDownIcon,
+  InboxArrowDownIcon,
+  HomeIcon,
+  ChevronRightIcon,
+  ArrowLeftIcon,
+  MusicalNoteIcon,
+  ExclamationTriangleIcon,
+  ArrowPathIcon,
+} from '@heroicons/react/24/outline';
+import { RootEntry, DirectoryEntry, AudioFileEntry, formatBytes } from './types';
+
+function SkeletonRow() {
+  return (
+    <div className="flex items-center gap-3 px-4 py-3 animate-pulse">
+      <div className="w-5 h-5 bg-gray-200 dark:bg-gray-700 rounded" />
+      <div className="flex-1 space-y-1.5">
+        <div className="h-4 bg-gray-200 dark:bg-gray-700 rounded w-48" />
+        <div className="h-3 bg-gray-100 dark:bg-gray-800 rounded w-32" />
+      </div>
+    </div>
+  );
+}
+
+interface BrowsePhaseProps {
+  roots: RootEntry[];
+  currentPath: string | null;
+  entries: DirectoryEntry[];
+  currentAudioFiles: AudioFileEntry[];
+  isLoading: boolean;
+  error: string | null;
+  hoveredFolder: string | null;
+  breadcrumbs: Array<{ label: string; index: number }>;
+  slideClass: string;
+  onNavigateInto: (path: string) => void;
+  onNavigateBack: () => void;
+  onNavigateToRoot: () => void;
+  onNavigateToBreadcrumb: (index: number) => void;
+  onFolderClick: (entry: DirectoryEntry) => void;
+  onSelectCurrentFolder: () => void;
+  onHoverFolder: (name: string | null) => void;
+  onRetry: () => void;
+}
+
+export function BrowsePhase({
+  roots,
+  currentPath,
+  entries,
+  currentAudioFiles,
+  isLoading,
+  error,
+  hoveredFolder,
+  breadcrumbs,
+  slideClass,
+  onNavigateInto,
+  onNavigateBack,
+  onNavigateToRoot,
+  onNavigateToBreadcrumb,
+  onFolderClick,
+  onSelectCurrentFolder,
+  onHoverFolder,
+  onRetry,
+}: BrowsePhaseProps) {
+  return (
+    <div className="flex flex-col h-full">
+      {/* Breadcrumb bar */}
+      {currentPath && (
+        <div className="flex items-center gap-1 px-5 py-2.5 bg-gray-50 dark:bg-gray-800/50 border-b border-gray-100 dark:border-gray-800 text-sm overflow-x-auto">
+          <button
+            onClick={onNavigateToRoot}
+            className="flex-shrink-0 p-1 rounded hover:bg-gray-200 dark:hover:bg-gray-700 transition-colors"
+          >
+            <HomeIcon className="w-4 h-4 text-gray-500 dark:text-gray-400" />
+          </button>
+          {breadcrumbs.map((crumb, i) => (
+            <React.Fragment key={i}>
+              <ChevronRightIcon className="w-3.5 h-3.5 text-gray-400 flex-shrink-0" />
+              {crumb.index === -1 ? (
+                <span className="text-gray-400 px-1">...</span>
+              ) : i === breadcrumbs.length - 1 ? (
+                <span className="font-medium text-gray-900 dark:text-gray-100 truncate">
+                  {crumb.label}
+                </span>
+              ) : (
+                <button
+                  onClick={() => onNavigateToBreadcrumb(crumb.index)}
+                  className="text-gray-600 dark:text-gray-300 hover:text-blue-600 dark:hover:text-blue-400 truncate transition-colors"
+                >
+                  {crumb.label}
+                </button>
+              )}
+            </React.Fragment>
+          ))}
+        </div>
+      )}
+
+      {/* Listing */}
+      <div className={`flex-1 overflow-y-auto ${slideClass}`}>
+        {/* Loading */}
+        {isLoading && (
+          <div className="py-2">
+            {[...Array(5)].map((_, i) => (
+              <SkeletonRow key={i} />
+            ))}
+          </div>
+        )}
+
+        {/* Error */}
+        {error && !isLoading && (
+          <div className="flex flex-col items-center justify-center py-16 px-6">
+            <ExclamationTriangleIcon className="w-10 h-10 text-red-400 mb-3" />
+            <p className="text-gray-900 dark:text-gray-100 font-medium text-center">{error}</p>
+            <button
+              onClick={onRetry}
+              className="mt-4 flex items-center gap-2 px-4 py-2 text-sm font-medium text-blue-600 dark:text-blue-400 hover:bg-blue-50 dark:hover:bg-blue-900/20 rounded-lg transition-colors"
+            >
+              <ArrowPathIcon className="w-4 h-4" />
+              Try Again
+            </button>
+          </div>
+        )}
+
+        {/* Root view */}
+        {!currentPath && !isLoading && !error && (
+          <div className="p-5 grid grid-cols-2 gap-3">
+            {roots.map((root) => (
+              <button
+                key={root.path}
+                onClick={() => onNavigateInto(root.path)}
+                className="flex flex-col items-center gap-3 p-6 rounded-xl border border-gray-200 dark:border-gray-700 hover:border-blue-300 dark:hover:border-blue-700 hover:bg-blue-50/50 dark:hover:bg-blue-900/10 transition-all group"
+              >
+                {root.icon === 'download' ? (
+                  <FolderArrowDownIcon className="w-10 h-10 text-blue-500 group-hover:text-blue-600 transition-colors" />
+                ) : root.icon === 'bookdrop' ? (
+                  <InboxArrowDownIcon className="w-10 h-10 text-amber-500 group-hover:text-amber-600 transition-colors" />
+                ) : (
+                  <FolderIcon className="w-10 h-10 text-emerald-500 group-hover:text-emerald-600 transition-colors" />
+                )}
+                <span className="text-sm font-medium text-gray-900 dark:text-gray-100">
+                  {root.name}
+                </span>
+                <span className="text-xs text-gray-500 dark:text-gray-400 font-mono truncate max-w-full">
+                  {root.path}
+                </span>
+              </button>
+            ))}
+          </div>
+        )}
+
+        {/* Directory + audio file listing */}
+        {currentPath && !isLoading && !error && (entries.length > 0 || currentAudioFiles.length > 0) && (
+          <div className="divide-y divide-gray-100 dark:divide-gray-800">
+            {/* Subdirectories */}
+            {entries.map((entry) => {
+              const hasAudio = entry.audioFileCount > 0;
+              const isHovered = hoveredFolder === entry.name;
+
+              return (
+                <button
+                  key={`dir-${entry.name}`}
+                  onClick={() => onFolderClick(entry)}
+                  onMouseEnter={() => onHoverFolder(entry.name)}
+                  onMouseLeave={() => onHoverFolder(null)}
+                  className="w-full flex items-center gap-3 px-4 py-3 text-left transition-all duration-150 hover:bg-gray-50 dark:hover:bg-gray-800/50"
+                >
+                  <div className="flex-shrink-0 w-5 h-5 text-gray-400 dark:text-gray-500 transition-all duration-150">
+                    {isHovered ? (
+                      <FolderOpenIcon className="w-5 h-5 text-blue-500" />
+                    ) : (
+                      <FolderIcon className="w-5 h-5" />
+                    )}
+                  </div>
+
+                  <div className="flex-1 min-w-0">
+                    <p className="text-sm font-medium text-gray-900 dark:text-gray-100 truncate">
+                      {entry.name}
+                    </p>
+                    <p className="text-xs text-gray-500 dark:text-gray-400">
+                      {entry.subfolderCount > 0 && (
+                        <span>{entry.subfolderCount} folder{entry.subfolderCount !== 1 ? 's' : ''}</span>
+                      )}
+                      {entry.subfolderCount > 0 && entry.audioFileCount > 0 && <span> &middot; </span>}
+                      {entry.audioFileCount > 0 && (
+                        <span>{entry.audioFileCount} audio file{entry.audioFileCount !== 1 ? 's' : ''}</span>
+                      )}
+                      {entry.totalSize > 0 && (
+                        <span> &middot; {formatBytes(entry.totalSize)}</span>
+                      )}
+                      {entry.subfolderCount === 0 && entry.audioFileCount === 0 && (
+                        <span className="italic">Empty</span>
+                      )}
+                    </p>
+                  </div>
+
+                  {hasAudio && (
+                    <span className="flex-shrink-0 inline-flex items-center gap-1 px-2 py-0.5 rounded-full bg-blue-100 dark:bg-blue-900/30 text-blue-700 dark:text-blue-300 text-xs font-medium">
+                      <MusicalNoteIcon className="w-3 h-3" />
+                      {entry.audioFileCount}
+                    </span>
+                  )}
+
+                  <ChevronRightIcon className="w-4 h-4 text-gray-300 dark:text-gray-600 flex-shrink-0" />
+                </button>
+              );
+            })}
+
+            {/* Audio files in current directory */}
+            {currentAudioFiles.length > 0 && entries.length > 0 && (
+              <div className="px-4 py-2 bg-gray-50/50 dark:bg-gray-800/20">
+                <p className="text-xs font-medium text-gray-400 dark:text-gray-500 uppercase tracking-wider">
+                  Audio Files
+                </p>
+              </div>
+            )}
+            {currentAudioFiles.map((file) => (
+              <div
+                key={`file-${file.name}`}
+                className="flex items-center gap-3 px-4 py-2.5"
+              >
+                <MusicalNoteIcon className="w-4 h-4 text-blue-500 dark:text-blue-400 flex-shrink-0" />
+                <span className="flex-1 min-w-0 text-sm text-gray-700 dark:text-gray-300 truncate">
+                  {file.name}
+                </span>
+                <span className="text-xs text-gray-400 dark:text-gray-500 flex-shrink-0">
+                  {formatBytes(file.size)}
+                </span>
+              </div>
+            ))}
+          </div>
+        )}
+
+        {/* Empty state */}
+        {currentPath && !isLoading && !error && entries.length === 0 && currentAudioFiles.length === 0 && (
+          <div className="flex flex-col items-center justify-center py-16 px-6 text-center">
+            <FolderOpenIcon className="w-10 h-10 text-gray-300 dark:text-gray-600 mb-3" />
+            <p className="text-gray-500 dark:text-gray-400 font-medium">This folder is empty</p>
+            <button
+              onClick={onNavigateBack}
+              className="mt-4 flex items-center gap-2 text-sm text-blue-600 dark:text-blue-400 hover:underline"
+            >
+              <ArrowLeftIcon className="w-4 h-4" />
+              Go back
+            </button>
+          </div>
+        )}
+      </div>
+
+      {/* Footer: Select this folder */}
+      {currentPath && !isLoading && currentAudioFiles.length > 0 && (
+        <div className="px-5 py-3.5 border-t border-gray-200 dark:border-gray-700/50 bg-gray-50/50 dark:bg-gray-800/30 flex items-center justify-between gap-4">
+          <p className="text-sm text-gray-600 dark:text-gray-400">
+            <span className="font-medium text-gray-900 dark:text-gray-100">{currentAudioFiles.length}</span>
+            {' '}audio file{currentAudioFiles.length !== 1 ? 's' : ''} in this folder
+          </p>
+          <button
+            onClick={onSelectCurrentFolder}
+            className="flex-shrink-0 px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium rounded-xl transition-colors"
+          >
+            Select This Folder &rarr;
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

src/components/audiobooks/manual-import/ConfirmPhase.tsx

@@ -0,0 +1,170 @@
+/**
+ * Component: Manual Import Confirm Phase
+ * Documentation: documentation/features/manual-import.md
+ *
+ * Shows book context, selected folder, pipeline steps summary,
+ * and start import / back actions.
+ */
+
+'use client';
+
+import React from 'react';
+import Image from 'next/image';
+import { ArrowLeftIcon, ExclamationCircleIcon, MusicalNoteIcon } from '@heroicons/react/24/outline';
+import { AudioFileEntry, formatBytes } from './types';
+
+interface ConfirmPhaseProps {
+  audiobook: { asin: string; title: string; author: string; coverArtUrl?: string };
+  selectedPath: string;
+  audioFileCount: number;
+  totalSize: number;
+  audioFiles: AudioFileEntry[];
+  isImporting: boolean;
+  importError: string | null;
+  slideClass: string;
+  cleanupSource: boolean;
+  onCleanupSourceChange: (value: boolean) => void;
+  onBack: () => void;
+  onStartImport: () => void;
+}
+
+export function ConfirmPhase({
+  audiobook,
+  selectedPath,
+  audioFileCount,
+  totalSize,
+  audioFiles,
+  isImporting,
+  importError,
+  slideClass,
+  cleanupSource,
+  onCleanupSourceChange,
+  onBack,
+  onStartImport,
+}: ConfirmPhaseProps) {
+  return (
+    <div className={`flex flex-col h-full ${slideClass}`}>
+      <div className="flex-1 overflow-y-auto p-6 space-y-6">
+        {/* Book context */}
+        <div className="flex items-start gap-4">
+          <div className="w-16 h-16 rounded-xl overflow-hidden flex-shrink-0 bg-gray-100 dark:bg-gray-800">
+            {audiobook.coverArtUrl ? (
+              <Image
+                src={audiobook.coverArtUrl}
+                alt=""
+                width={64}
+                height={64}
+                className="w-full h-full object-cover"
+              />
+            ) : (
+              <div className="w-full h-full flex items-center justify-center">
+                <MusicalNoteIcon className="w-6 h-6 text-gray-400" />
+              </div>
+            )}
+          </div>
+          <div className="min-w-0">
+            <h3 className="font-semibold text-gray-900 dark:text-gray-100 truncate">
+              {audiobook.title}
+            </h3>
+            <p className="text-sm text-gray-500 dark:text-gray-400">{audiobook.author}</p>
+          </div>
+        </div>
+
+        {/* Selected folder info */}
+        <div className="p-4 rounded-xl bg-gray-50 dark:bg-gray-800/50 border border-gray-200 dark:border-gray-700">
+          <p className="text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider mb-1.5">
+            Import from
+          </p>
+          <p className="text-sm font-mono text-gray-900 dark:text-gray-100 break-all">
+            {selectedPath}
+          </p>
+          <p className="text-xs text-gray-500 dark:text-gray-400 mt-1.5">
+            {audioFileCount} audio file{audioFileCount !== 1 ? 's' : ''}
+            {totalSize > 0 ? ` \u00B7 ${formatBytes(totalSize)}` : ''}
+          </p>
+        </div>
+
+        {/* Audio files to import */}
+        <div>
+          <h4 className="text-sm font-semibold text-gray-900 dark:text-gray-100 mb-3">
+            Files to import
+          </h4>
+          <div className="rounded-xl border border-gray-200 dark:border-gray-700 divide-y divide-gray-100 dark:divide-gray-800 overflow-hidden">
+            {audioFiles.map((file) => (
+              <div key={file.name} className="flex items-center gap-3 px-3.5 py-2.5">
+                <MusicalNoteIcon className="w-4 h-4 text-blue-500 dark:text-blue-400 flex-shrink-0" />
+                <span className="flex-1 min-w-0 text-sm text-gray-700 dark:text-gray-300 truncate">
+                  {file.name}
+                </span>
+                <span className="text-xs text-gray-400 dark:text-gray-500 flex-shrink-0">
+                  {formatBytes(file.size)}
+                </span>
+              </div>
+            ))}
+          </div>
+        </div>
+
+        {/* Cleanup source toggle */}
+        <div className="p-4 rounded-xl bg-gray-50 dark:bg-gray-800/50 border border-gray-200 dark:border-gray-700">
+          <div className="flex items-center justify-between">
+            <div>
+              <p className="text-sm font-medium text-gray-900 dark:text-gray-100">
+                Cleanup source files
+              </p>
+              <p className="text-xs text-gray-500 dark:text-gray-400 mt-0.5">
+                Delete original files after successful import
+              </p>
+            </div>
+            <label className="relative inline-flex items-center cursor-pointer">
+              <input
+                type="checkbox"
+                checked={cleanupSource}
+                onChange={(e) => onCleanupSourceChange(e.target.checked)}
+                disabled={isImporting}
+                className="sr-only peer"
+              />
+              <div className="w-11 h-6 bg-gray-200 peer-focus:outline-none peer-focus:ring-4 peer-focus:ring-blue-300 dark:peer-focus:ring-blue-800 rounded-full peer dark:bg-gray-700 peer-checked:after:translate-x-full rtl:peer-checked:after:-translate-x-full peer-checked:after:border-white after:content-[''] after:absolute after:top-[2px] after:start-[2px] after:bg-white after:border-gray-300 after:border after:rounded-full after:h-5 after:w-5 after:transition-all dark:border-gray-600 peer-checked:bg-blue-600"></div>
+            </label>
+          </div>
+        </div>
+      </div>
+
+      {/* Error display */}
+      {importError && (
+        <div className="mx-5 mb-2 p-3 rounded-xl bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800/50 flex items-start gap-2.5">
+          <ExclamationCircleIcon className="w-5 h-5 text-red-500 dark:text-red-400 flex-shrink-0 mt-0.5" />
+          <p className="text-sm text-red-700 dark:text-red-300">{importError}</p>
+        </div>
+      )}
+
+      {/* Footer */}
+      <div className="px-5 py-3.5 border-t border-gray-200 dark:border-gray-700/50 bg-gray-50/50 dark:bg-gray-800/30 flex items-center justify-between gap-3">
+        <button
+          onClick={onBack}
+          disabled={isImporting}
+          className="flex items-center gap-1.5 px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 rounded-xl transition-colors disabled:opacity-50"
+        >
+          <ArrowLeftIcon className="w-4 h-4" />
+          Back
+        </button>
+        <button
+          onClick={onStartImport}
+          disabled={isImporting}
+          className="px-5 py-2 bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium rounded-xl transition-colors disabled:opacity-70 flex items-center gap-2"
+        >
+          {isImporting ? (
+            <>
+              <svg className="w-4 h-4 animate-spin" viewBox="0 0 24 24" fill="none">
+                <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="3" />
+                <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
+              </svg>
+              Importing...
+            </>
+          ) : (
+            'Start Import'
+          )}
+        </button>
+      </div>
+    </div>
+  );
+}

src/components/audiobooks/manual-import/types.ts

@@ -0,0 +1,33 @@
+/**
+ * Component: Manual Import Shared Types
+ * Documentation: documentation/features/manual-import.md
+ */
+
+export interface RootEntry {
+  name: string;
+  path: string;
+  icon: string;
+}
+
+export interface DirectoryEntry {
+  name: string;
+  type: 'directory';
+  audioFileCount: number;
+  subfolderCount: number;
+  totalSize: number;
+}
+
+export interface AudioFileEntry {
+  name: string;
+  size: number;
+}
+
+export type SlideDirection = 'left' | 'right';
+
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+}

src/components/requests/InteractiveTorrentSearchModal.tsx

@@ -34,10 +34,12 @@ interface InteractiveTorrentSearchModalProps {
     title: string;
     author: string;
   };
+  customSearchTerms?: string | null; // Optional - admin-set custom search terms override
   fullAudiobook?: Audiobook; // Optional - only provided when called from details modal
   onSuccess?: () => void;
   searchMode?: 'audiobook' | 'ebook'; // Search mode - defaults to audiobook
   replaceIssueId?: string; // Optional - when set, confirm handler calls replace endpoint instead
+  onConfirm?: (torrent: TorrentResult) => Promise<void>; // Optional - overrides default confirm handler
 }
 
 // Format relative time from publish date
@@ -86,10 +88,12 @@ export function InteractiveTorrentSearchModal({
   requestId,
   asin,
   audiobook,
+  customSearchTerms,
   fullAudiobook,
   onSuccess,
   searchMode = 'audiobook',
   replaceIssueId,
+  onConfirm,
 }: InteractiveTorrentSearchModalProps) {
   // Hooks for existing audiobook request flow
   const { searchTorrents: searchByRequestId, isLoading: isSearchingByRequest, error: searchByRequestError } = useInteractiveSearch();
@@ -112,7 +116,8 @@ export function InteractiveTorrentSearchModal({
 
   const [results, setResults] = useState<(RankedTorrent & { qualityScore?: number; source?: string; ebookFormat?: string })[]>([]);
   const [confirmTorrent, setConfirmTorrent] = useState<TorrentResult | null>(null);
-  const [searchTitle, setSearchTitle] = useState(audiobook.title);
+  const [searchTitle, setSearchTitle] = useState(customSearchTerms || audiobook.title);
+  const [isCustomConfirming, setIsCustomConfirming] = useState(false);
   const [mounted, setMounted] = useState(false);
 
   // Stable close handler via ref
@@ -130,11 +135,13 @@ export function InteractiveTorrentSearchModal({
   const isSearching = isEbookMode
     ? (useAsinMode ? isSearchingEbooksByAsin : isSearchingEbooks)
     : (hasRequestId ? isSearchingByRequest : isSearchingByAudiobook);
-  const isDownloading = replaceIssueId
-    ? isReplacing
-    : isEbookMode
-      ? (useAsinMode ? isSelectingEbookByAsin : isSelectingEbook)
-      : (hasRequestId ? isSelectingTorrent : isRequestingWithTorrent);
+  const isDownloading = isCustomConfirming
+    ? true
+    : replaceIssueId
+      ? isReplacing
+      : isEbookMode
+        ? (useAsinMode ? isSelectingEbookByAsin : isSelectingEbook)
+        : (hasRequestId ? isSelectingTorrent : isRequestingWithTorrent);
   const error = replaceIssueId
     ? (replaceError || (hasRequestId ? searchByRequestError : searchByAudiobookError))
     : isEbookMode
@@ -148,9 +155,9 @@ export function InteractiveTorrentSearchModal({
 
   // Reset search title when modal opens/closes or audiobook changes
   useEffect(() => {
-    setSearchTitle(audiobook.title);
+    setSearchTitle(customSearchTerms || audiobook.title);
     setResults([]);
-  }, [isOpen, audiobook.title]);
+  }, [isOpen, audiobook.title, customSearchTerms]);
 
   // Perform search when modal opens
   useEffect(() => {
@@ -218,7 +225,11 @@ export function InteractiveTorrentSearchModal({
   const handleConfirmDownload = async () => {
     if (!confirmTorrent) return;
     try {
-      if (replaceIssueId) {
+      if (onConfirm) {
+        // Custom confirm handler (e.g., admin approve-with-torrent flow)
+        setIsCustomConfirming(true);
+        await onConfirm(confirmTorrent);
+      } else if (replaceIssueId) {
         // Reported issue replacement flow
         await replaceWithTorrent(replaceIssueId, confirmTorrent);
       } else if (isEbookMode) {
@@ -241,6 +252,8 @@ export function InteractiveTorrentSearchModal({
     } catch (err) {
       console.error('Failed to download:', err);
       setConfirmTorrent(null);
+    } finally {
+      setIsCustomConfirming(false);
     }
   };
 

src/components/requests/RequestCard.tsx

@@ -15,6 +15,7 @@ import { usePreferences } from '@/contexts/PreferencesContext';
 import { useAuth } from '@/contexts/AuthContext';
 import { InteractiveTorrentSearchModal } from './InteractiveTorrentSearchModal';
 import { AudiobookDetailsModal } from '@/components/audiobooks/AudiobookDetailsModal';
+import { COMPLETED_STATUSES } from '@/lib/constants/request-statuses';
 
 interface RequestCardProps {
   request: {
@@ -26,12 +27,15 @@ interface RequestCardProps {
     createdAt: string;
     updatedAt: string;
     completedAt?: string;
+    downloadAvailable?: boolean;
     audiobook: {
       id: string;
       audibleAsin?: string;
       title: string;
       author: string;
       coverArtUrl?: string;
+      filePath?: string | null;
+      fileFormat?: string | null;
     };
   };
   showActions?: boolean;
@@ -49,6 +53,7 @@ export function RequestCard({ request, showActions = true }: RequestCardProps) {
   const requestType = request.type || 'audiobook';
   const isEbook = requestType === 'ebook';
 
+  const isCompleted = COMPLETED_STATUSES.includes(request.status as typeof COMPLETED_STATUSES[number]);
   const canCancel = ['pending', 'searching', 'downloading'].includes(request.status);
   const isActive = ['searching', 'downloading', 'processing'].includes(request.status);
   const isFailed = request.status === 'failed';
@@ -306,7 +311,7 @@ export function RequestCard({ request, showActions = true }: RequestCardProps) {
           isOpen={showDetailsModal}
           onClose={() => setShowDetailsModal(false)}
           requestStatus={request.status}
-          isAvailable={['available', 'downloaded'].includes(request.status)}
+          isAvailable={COMPLETED_STATUSES.includes(request.status as typeof COMPLETED_STATUSES[number])}
           hideRequestActions
         />
       )}

src/components/ui/HideAvailableToggle.tsx

@@ -0,0 +1,81 @@
+/**
+ * Component: Hide Available Toggle
+ * Documentation: UI toggle for hiding titles already in the user's library
+ */
+
+'use client';
+
+import React from 'react';
+
+interface HideAvailableToggleProps {
+  enabled: boolean;
+  onToggle: (enabled: boolean) => void;
+}
+
+export function HideAvailableToggle({ enabled, onToggle }: HideAvailableToggleProps) {
+  return (
+    <button
+      onClick={() => onToggle(!enabled)}
+      aria-label={enabled ? 'Show available titles' : 'Hide available titles'}
+      aria-pressed={enabled}
+      title={enabled ? 'Hide available (on)' : 'Hide available (off)'}
+      className={`
+        p-1.5 rounded-md transition-all duration-200
+        ${enabled
+          ? 'bg-blue-500/20 dark:bg-blue-400/20 text-blue-600 dark:text-blue-400 ring-1 ring-blue-500/30 dark:ring-blue-400/30 shadow-inner'
+          : 'text-gray-600 dark:text-gray-400 hover:bg-white/20 dark:hover:bg-gray-700/50'
+        }
+      `}
+    >
+      <svg
+        className="w-5 h-5"
+        fill="none"
+        stroke="currentColor"
+        viewBox="0 0 24 24"
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        {enabled ? (
+          <>
+            {/* Eye with slash — hidden state */}
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M3 3l18 18"
+            />
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M10.5 10.677a2 2 0 002.823 2.823"
+            />
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M7.362 7.561C5.68 8.74 4.279 10.42 3 12c1.889 2.991 5.282 6 9 6 1.55 0 3.043-.523 4.395-1.35M12 6c3.718 0 7.111 3.009 9 6-.947 1.498-2.057 2.876-3.362 3.939"
+            />
+          </>
+        ) : (
+          <>
+            {/* Open eye — visible state */}
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M12 6c3.718 0 7.111 3.009 9 6-1.889 2.991-5.282 6-9 6s-7.111-3.009-9-6c1.889-2.991 5.282-6 9-6z"
+            />
+            <circle
+              cx="12"
+              cy="12"
+              r="2"
+              strokeWidth={2}
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </>
+        )}
+      </svg>
+    </button>
+  );
+}

src/components/ui/LoadMoreBar.tsx

@@ -0,0 +1,82 @@
+/**
+ * Component: LoadMoreBar
+ * Documentation: documentation/frontend/components.md
+ */
+
+'use client';
+
+import { CheckCircleIcon } from '@heroicons/react/24/outline';
+
+interface LoadMoreBarProps {
+  loadedCount: number;
+  totalCount?: number;
+  hasMore: boolean;
+  isLoading: boolean;
+  onLoadMore: () => void;
+  itemLabel?: string;
+}
+
+export function LoadMoreBar({
+  loadedCount,
+  totalCount,
+  hasMore,
+  isLoading,
+  onLoadMore,
+  itemLabel = 'books',
+}: LoadMoreBarProps) {
+  if (loadedCount === 0) return null;
+
+  const allLoaded = !hasMore && !isLoading;
+
+  // Count text
+  let countText: string;
+  if (allLoaded) {
+    countText = `All ${loadedCount.toLocaleString()} ${itemLabel} loaded`;
+  } else if (totalCount && totalCount > loadedCount) {
+    countText = `Showing ${loadedCount.toLocaleString()} of ${totalCount.toLocaleString()} ${itemLabel}`;
+  } else {
+    countText = `${loadedCount.toLocaleString()} ${itemLabel} loaded`;
+  }
+
+  return (
+    <div className="bg-white/90 dark:bg-gray-800/90 backdrop-blur-md rounded-2xl px-4 sm:px-6 py-3 border border-gray-200/50 dark:border-gray-700/50 shadow-sm">
+      <div className="flex items-center justify-between">
+        {/* Left: Count */}
+        <span className="text-sm text-gray-600 dark:text-gray-400">
+          {countText}
+        </span>
+
+        {/* Right: Action */}
+        {allLoaded ? (
+          <span className="inline-flex items-center gap-1.5 text-sm text-green-600 dark:text-green-400">
+            <CheckCircleIcon className="w-4 h-4" />
+            Complete
+          </span>
+        ) : (
+          <button
+            onClick={onLoadMore}
+            disabled={isLoading}
+            className="inline-flex items-center gap-2 px-4 py-1.5 text-sm font-medium
+                     text-gray-700 dark:text-gray-300
+                     border border-gray-300 dark:border-gray-600 rounded-lg
+                     hover:bg-gray-100 dark:hover:bg-gray-700
+                     disabled:opacity-50 disabled:cursor-not-allowed
+                     transition-colors"
+          >
+            {isLoading ? (
+              <>
+                <svg className="animate-spin h-4 w-4" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+                  <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+                  <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+                </svg>
+                Loading...
+              </>
+            ) : (
+              'Load more'
+            )}
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

src/components/ui/SectionToolbar.tsx

@@ -0,0 +1,175 @@
+/**
+ * Component: Section Toolbar
+ * Documentation: Responsive toolbar that shows inline controls on sm+ and collapses to popover on mobile
+ */
+
+'use client';
+
+import React, { useState, useEffect } from 'react';
+import { createPortal } from 'react-dom';
+import { useSmartDropdownPosition } from '@/hooks/useSmartDropdownPosition';
+import { HideAvailableToggle } from '@/components/ui/HideAvailableToggle';
+import { SquareCoversToggle } from '@/components/ui/SquareCoversToggle';
+import { CardSizeControls } from '@/components/ui/CardSizeControls';
+
+interface SectionToolbarProps {
+  hideAvailable: boolean;
+  onToggleHideAvailable: (v: boolean) => void;
+  squareCovers: boolean;
+  onToggleSquareCovers: (v: boolean) => void;
+  cardSize: number;
+  onCardSizeChange: (v: number) => void;
+}
+
+export function SectionToolbar({
+  hideAvailable,
+  onToggleHideAvailable,
+  squareCovers,
+  onToggleSquareCovers,
+  cardSize,
+  onCardSizeChange,
+}: SectionToolbarProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const { containerRef, dropdownRef, style } = useSmartDropdownPosition(isOpen);
+
+  // Close on Escape
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setIsOpen(false);
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isOpen]);
+
+  // Close on click outside
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleMouseDown = (e: MouseEvent) => {
+      const target = e.target as Node;
+      if (
+        containerRef.current && !containerRef.current.contains(target) &&
+        dropdownRef.current && !dropdownRef.current.contains(target)
+      ) {
+        setIsOpen(false);
+      }
+    };
+    document.addEventListener('mousedown', handleMouseDown);
+    return () => document.removeEventListener('mousedown', handleMouseDown);
+  }, [isOpen, containerRef, dropdownRef]);
+
+  return (
+    <div className="ml-auto flex items-center gap-1">
+      {/* Inline controls — visible at sm and above */}
+      <div className="hidden sm:flex items-center gap-1">
+        <HideAvailableToggle enabled={hideAvailable} onToggle={onToggleHideAvailable} />
+        <SquareCoversToggle enabled={squareCovers} onToggle={onToggleSquareCovers} />
+        <CardSizeControls size={cardSize} onSizeChange={onCardSizeChange} />
+      </div>
+
+      {/* Collapsed ellipsis trigger — visible below sm */}
+      <div className="sm:hidden" ref={containerRef}>
+        <button
+          onClick={() => setIsOpen(!isOpen)}
+          aria-label="View options"
+          aria-expanded={isOpen}
+          className={`
+            p-1.5 rounded-md transition-all duration-200
+            ${isOpen
+              ? 'bg-blue-500/20 dark:bg-blue-400/20 text-blue-600 dark:text-blue-400 ring-1 ring-blue-500/30 dark:ring-blue-400/30'
+              : 'text-gray-600 dark:text-gray-400 hover:bg-white/20 dark:hover:bg-gray-700/50'
+            }
+          `}
+        >
+          <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+            <circle cx="5" cy="12" r="2" />
+            <circle cx="12" cy="12" r="2" />
+            <circle cx="19" cy="12" r="2" />
+          </svg>
+        </button>
+
+        {/* Portal dropdown */}
+        {isOpen && typeof document !== 'undefined' && style && createPortal(
+          <div
+            ref={dropdownRef}
+            style={style}
+            className="bg-white dark:bg-gray-800 rounded-lg shadow-lg ring-1 ring-black/5 dark:ring-white/10 z-50 py-1 min-w-[220px] animate-in fade-in duration-150"
+          >
+            {/* Hide Available */}
+            <button
+              onClick={() => onToggleHideAvailable(!hideAvailable)}
+              className="w-full flex items-center gap-3 px-3 py-2.5 text-sm hover:bg-gray-100 dark:hover:bg-gray-700/50 transition-colors"
+            >
+              <span className={`
+                p-1 rounded-md transition-all duration-200
+                ${hideAvailable
+                  ? 'bg-blue-500/20 dark:bg-blue-400/20 text-blue-600 dark:text-blue-400 ring-1 ring-blue-500/30 dark:ring-blue-400/30 shadow-inner'
+                  : 'text-gray-500 dark:text-gray-400'
+                }
+              `}>
+                <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  {hideAvailable ? (
+                    <>
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M3 3l18 18" />
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10.5 10.677a2 2 0 002.823 2.823" />
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M7.362 7.561C5.68 8.74 4.279 10.42 3 12c1.889 2.991 5.282 6 9 6 1.55 0 3.043-.523 4.395-1.35M12 6c3.718 0 7.111 3.009 9 6-.947 1.498-2.057 2.876-3.362 3.939" />
+                    </>
+                  ) : (
+                    <>
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 6c3.718 0 7.111 3.009 9 6-1.889 2.991-5.282 6-9 6s-7.111-3.009-9-6c1.889-2.991 5.282-6 9-6z" />
+                      <circle cx="12" cy="12" r="2" strokeWidth={2} />
+                    </>
+                  )}
+                </svg>
+              </span>
+              <span className="text-gray-700 dark:text-gray-300">Hide Available</span>
+              {hideAvailable && (
+                <span className="ml-auto text-xs text-blue-600 dark:text-blue-400 font-medium">On</span>
+              )}
+            </button>
+
+            {/* Square Covers */}
+            <button
+              onClick={() => onToggleSquareCovers(!squareCovers)}
+              className="w-full flex items-center gap-3 px-3 py-2.5 text-sm hover:bg-gray-100 dark:hover:bg-gray-700/50 transition-colors"
+            >
+              <span className={`
+                p-1 rounded-md transition-all duration-200
+                ${squareCovers
+                  ? 'bg-blue-500/20 dark:bg-blue-400/20 text-blue-600 dark:text-blue-400 ring-1 ring-blue-500/30 dark:ring-blue-400/30 shadow-inner'
+                  : 'text-gray-500 dark:text-gray-400'
+                }
+              `}>
+                <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  <rect x="3" y="3" width="18" height="18" rx="2" strokeWidth={2} />
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M3 9h4M3 15h4M21 9h-4M21 15h-4" opacity={squareCovers ? 1 : 0.4} />
+                </svg>
+              </span>
+              <span className="text-gray-700 dark:text-gray-300">Square Covers</span>
+              {squareCovers && (
+                <span className="ml-auto text-xs text-blue-600 dark:text-blue-400 font-medium">On</span>
+              )}
+            </button>
+
+            {/* Divider */}
+            <div className="border-t border-gray-200 dark:border-gray-700 my-1" />
+
+            {/* Card Size */}
+            <div className="flex items-center gap-3 px-3 py-2.5 text-sm">
+              <span className="p-1 text-gray-500 dark:text-gray-400">
+                <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+                </svg>
+              </span>
+              <span className="text-gray-700 dark:text-gray-300">Card Size</span>
+              <div className="ml-auto">
+                <CardSizeControls size={cardSize} onSizeChange={onCardSizeChange} />
+              </div>
+            </div>
+          </div>,
+          document.body
+        )}
+      </div>
+    </div>
+  );
+}

src/contexts/AuthContext.tsx

@@ -10,6 +10,7 @@ import { isTokenExpired, getRefreshTimeMs } from '@/lib/utils/jwt-client';
 
 interface UserPermissions {
   interactiveSearch: boolean;
+  download: boolean;
 }
 
 interface User {

src/contexts/PreferencesContext.tsx

@@ -10,6 +10,7 @@ import React, { createContext, useContext, useState, useEffect, ReactNode } from
 interface Preferences {
   cardSize: number; // 1-9, default 5
   squareCovers: boolean; // true = square (1:1), false = rectangle (2:3)
+  hideAvailable: boolean; // true = hide "In Your Library" titles
 }
 
 interface PreferencesContextType {
@@ -17,6 +18,8 @@ interface PreferencesContextType {
   setCardSize: (size: number) => void;
   squareCovers: boolean;
   setSquareCovers: (enabled: boolean) => void;
+  hideAvailable: boolean;
+  setHideAvailable: (enabled: boolean) => void;
 }
 
 const PreferencesContext = createContext<PreferencesContextType | undefined>(undefined);
@@ -24,6 +27,7 @@ const PreferencesContext = createContext<PreferencesContextType | undefined>(und
 const DEFAULT_PREFERENCES: Preferences = {
   cardSize: 5,
   squareCovers: true,
+  hideAvailable: false,
 };
 
 const STORAGE_KEY = 'preferences';
@@ -31,6 +35,7 @@ const STORAGE_KEY = 'preferences';
 export function PreferencesProvider({ children }: { children: ReactNode }) {
   const [cardSize, setCardSizeState] = useState<number>(DEFAULT_PREFERENCES.cardSize);
   const [squareCovers, setSquareCoversState] = useState<boolean>(DEFAULT_PREFERENCES.squareCovers);
+  const [hideAvailable, setHideAvailableState] = useState<boolean>(DEFAULT_PREFERENCES.hideAvailable);
 
   // Load preferences from localStorage on mount
   useEffect(() => {
@@ -49,11 +54,14 @@ export function PreferencesProvider({ children }: { children: ReactNode }) {
         }
         // Load squareCovers preference (defaults to false if not set)
         setSquareCoversState(preferences.squareCovers ?? DEFAULT_PREFERENCES.squareCovers);
+        // Load hideAvailable preference
+        setHideAvailableState(preferences.hideAvailable ?? DEFAULT_PREFERENCES.hideAvailable);
       }
     } catch (error) {
       console.error('Failed to load preferences from localStorage:', error);
       setCardSizeState(DEFAULT_PREFERENCES.cardSize);
       setSquareCoversState(DEFAULT_PREFERENCES.squareCovers);
+      setHideAvailableState(DEFAULT_PREFERENCES.hideAvailable);
     }
   }, []);
 
@@ -92,6 +100,22 @@ export function PreferencesProvider({ children }: { children: ReactNode }) {
     }
   };
 
+  // Update hideAvailable preference in state and localStorage
+  const setHideAvailable = (enabled: boolean) => {
+    if (typeof window === 'undefined') return;
+
+    setHideAvailableState(enabled);
+
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      const preferences: Preferences = stored ? JSON.parse(stored) : { ...DEFAULT_PREFERENCES };
+      preferences.hideAvailable = enabled;
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(preferences));
+    } catch (error) {
+      console.error('Failed to save preferences to localStorage:', error);
+    }
+  };
+
   // Listen for storage changes in other tabs (cross-tab sync)
   useEffect(() => {
     if (typeof window === 'undefined') return;
@@ -106,6 +130,8 @@ export function PreferencesProvider({ children }: { children: ReactNode }) {
           }
           // Sync squareCovers preference
           setSquareCoversState(preferences.squareCovers ?? DEFAULT_PREFERENCES.squareCovers);
+          // Sync hideAvailable preference
+          setHideAvailableState(preferences.hideAvailable ?? DEFAULT_PREFERENCES.hideAvailable);
         } catch (error) {
           console.error('Failed to parse preferences from storage event:', error);
         }
@@ -119,7 +145,7 @@ export function PreferencesProvider({ children }: { children: ReactNode }) {
   }, []);
 
   return (
-    <PreferencesContext.Provider value={{ cardSize, setCardSize, squareCovers, setSquareCovers }}>
+    <PreferencesContext.Provider value={{ cardSize, setCardSize, squareCovers, setSquareCovers, hideAvailable, setHideAvailable }}>
       {children}
     </PreferencesContext.Provider>
   );

src/lib/bookdate/helpers.ts

@@ -547,7 +547,7 @@ export async function buildAIPrompt(
 
 /**
  * Call AI API to get recommendations
- * @param provider - 'openai' | 'claude'
+ * @param provider - 'openai' | 'claude' | 'gemini' | 'custom'
  * @param model - Model ID
  * @param encryptedApiKey - Encrypted API key
  * @param prompt - JSON prompt string
@@ -691,6 +691,74 @@ export async function callAI(
     logger.debug('Claude cleaned response:', { cleanedContent });
     return JSON.parse(cleanedContent);
 
+  } else if (provider === 'gemini') {
+    const requestBody = {
+      systemInstruction: {
+        parts: [{ text: systemMessage }],
+      },
+      contents: [
+        {
+          parts: [{ text: prompt }],
+        },
+      ],
+      generationConfig: {
+        responseMimeType: "application/json",
+        responseSchema: {
+          type: "OBJECT",
+          properties: {
+            recommendations: {
+              type: "ARRAY",
+              items: {
+                type: "OBJECT",
+                properties: {
+                  title: { type: "STRING" },
+                  author: { type: "STRING" },
+                  reason: { type: "STRING" },
+                },
+                required: ["title", "author", "reason"],
+              },
+            },
+          },
+          required: ["recommendations"],
+        },
+      },
+    };
+
+    logger.debug('Gemini request body:', { requestBody });
+
+    const response = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-goog-api-key': apiKey,
+      },
+      body: JSON.stringify(requestBody),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      logger.error('Gemini API error', { status: response.status, error: errorText });
+      throw new Error(`Gemini API error: ${response.status} ${errorText}`);
+    }
+
+    const data = await response.json();
+    const content = data.candidates?.[0]?.content?.parts?.[0]?.text;
+
+    if (!content) {
+      throw new Error('Invalid response format from Gemini API');
+    }
+
+    logger.debug('Gemini raw response:', { content });
+
+    // Clean potential markdown wrapping
+    const cleanedContent = content
+      .replace(/^```(?:json)?\s*/i, '')
+      .replace(/\s*```$/i, '')
+      .trim();
+
+    logger.debug('Gemini cleaned response:', { cleanedContent });
+    return JSON.parse(cleanedContent);
+
   } else if (provider === 'custom') {
     if (!baseUrl) {
       throw new Error('Base URL is required for custom provider');

src/lib/constants/audio-formats.ts

@@ -67,3 +67,16 @@ export type TorrentTitleFormat = (typeof TORRENT_TITLE_FORMATS)[number];
  * 'OTHER' is used when no recognized format is detected in the title.
  */
 export type AudioFormat = TorrentTitleFormat | 'OTHER';
+
+/**
+ * All supported ebook file extensions for ebook detection and file serving.
+ */
+export const EBOOK_EXTENSIONS = [
+  '.epub',
+  '.pdf',
+  '.mobi',
+  '.azw3',
+  '.fb2',
+  '.cbz',
+  '.cbr',
+] as const;

src/lib/constants/download-timeouts.ts

@@ -0,0 +1,10 @@
+/**
+ * Component: Download Client Timeout Constants
+ * Documentation: documentation/phase3/download-clients.md
+ *
+ * Some indexers (e.g. YGGtorrent) enforce a ~30s wait before allowing
+ * .torrent file downloads. 60s gives sufficient headroom.
+ */
+
+/** Timeout for download client API calls and .torrent file fetches (ms) */
+export const DOWNLOAD_CLIENT_TIMEOUT = 60000;

src/lib/constants/language-config.ts

@@ -16,7 +16,7 @@ import type { AudibleRegion } from '../types/audible';
 // Types
 // ---------------------------------------------------------------------------
 
-export type SupportedLanguage = 'en' | 'de' | 'es';
+export type SupportedLanguage = 'en' | 'de' | 'es' | 'fr';
 
 export interface ScrapingConfig {
   /** Audible locale query-param value (e.g. 'english', 'deutsch') */
@@ -170,6 +170,38 @@ const SPANISH_CONFIG: LanguageConfig = {
   },
 };
 
+const FRENCH_CONFIG: LanguageConfig = {
+  code: 'fr',
+  annasArchiveLang: 'fr',
+  epubCode: 'fr',
+  stopWords: ['le', 'la', 'les', 'un', 'une', 'de', 'des', 'sur', 'dans', '\u00e0', 'et', 'par', 'pour'],
+  characterReplacements: {},
+  scraping: {
+    audibleLocaleParam: 'français',
+    authorPrefixes: ['De :', '\u00c9crit par :', 'Auteur :'],
+    narratorPrefixes: ['Lu par :'],
+    lengthLabels: ['Dur\u00e9e :'],
+    languageLabels: ['Langue :'],
+    releaseDateLabels: ['Date de publication :'],
+    seriesLabels: ['S\u00e9rie :'],
+    acceptedLanguageValues: ['français', 'french'],
+    runtimeHourPatterns: [/(\d+)\s*h\b/i, /(\d+)\s*heures?/i],
+    runtimeMinutePatterns: [/(\d+)\s*min/i, /(\d+)\s*minutes?/i],
+    ratingPatterns: [/(\d+[.,]?\d*)\s*de\s*5/i],
+    releaseDatePatterns: [/Date de publication:\s*(.+)/i],
+    descriptionExcludePatterns: [
+      /\$\d+\.\d+/,
+      /\d+,\d+\s*\u20ac/,
+      /Essayer pour/i,
+      /R\u00e9siliez \u00e0 tout moment/i,
+      /Acheter pour/i,
+      /^\s*de\s+[\w\s,]+$/i,
+    ],
+    durationDetectionPattern: /\d+\s*(h|heures?)\s*\d*\s*(min|minutes?)?/i,
+    ratingTextSelector: 'sur 5 étoiles',
+  },
+};
+
 // ---------------------------------------------------------------------------
 // Lookup Maps
 // ---------------------------------------------------------------------------
@@ -178,6 +210,7 @@ export const LANGUAGE_CONFIGS: Record<SupportedLanguage, LanguageConfig> = {
   en: ENGLISH_CONFIG,
   de: GERMAN_CONFIG,
   es: SPANISH_CONFIG,
+  fr: FRENCH_CONFIG,
 };
 
 /**
@@ -192,6 +225,7 @@ export const REGION_LANGUAGE_MAP: Record<AudibleRegion, SupportedLanguage> = {
   in: 'en',
   de: 'de',
   es: 'es',
+  fr: 'fr',
 };
 
 // ---------------------------------------------------------------------------

src/lib/constants/request-statuses.ts

@@ -0,0 +1,7 @@
+/**
+ * Component: Request Status Constants
+ * Documentation: documentation/backend/database.md
+ */
+
+/** Terminal statuses indicating a request has been fulfilled and files are ready */
+export const COMPLETED_STATUSES = ['available', 'downloaded'] as const;

src/lib/hooks/useAudiobooks.ts

@@ -5,7 +5,9 @@
 
 'use client';
 
+import { useRef, useEffect, useCallback } from 'react';
 import useSWR from 'swr';
+import useSWRInfinite from 'swr/infinite';
 import { authenticatedFetcher } from '@/lib/utils/api';
 
 export interface Audiobook {
@@ -57,20 +59,58 @@ export function useAudiobooks(type: 'popular' | 'new-releases', limit: number =
   };
 }
 
-export function useSearch(query: string, page: number = 1) {
-  const shouldFetch = query && query.length > 0;
-  const endpoint = shouldFetch ? `/api/audiobooks/search?q=${encodeURIComponent(query)}&page=${page}` : null;
-
-  const { data, error, isLoading } = useSWR(endpoint, authenticatedFetcher, {
-    revalidateOnFocus: false,
-    dedupingInterval: 30000, // Cache for 30 seconds
+function dedupeByAsin<T extends { asin: string }>(items: T[]): T[] {
+  const seen = new Set<string>();
+  return items.filter(item => {
+    if (seen.has(item.asin)) return false;
+    seen.add(item.asin);
+    return true;
   });
+}
+
+export function useSearch(query: string) {
+  const prevQueryRef = useRef(query);
+
+  const { data, error, size, setSize, isLoading, isValidating } = useSWRInfinite(
+    (pageIndex, prevPageData) => {
+      if (!query || query.length === 0) return null;
+      if (pageIndex === 0) return `/api/audiobooks/search?q=${encodeURIComponent(query)}&page=1`;
+      if (!prevPageData?.hasMore) return null;
+      return `/api/audiobooks/search?q=${encodeURIComponent(query)}&page=${pageIndex + 1}`;
+    },
+    authenticatedFetcher,
+    {
+      revalidateOnFocus: false,
+      dedupingInterval: 30000,
+      revalidateFirstPage: false,
+    }
+  );
+
+  // Reset to page 1 when query changes
+  useEffect(() => {
+    if (query !== prevQueryRef.current) {
+      prevQueryRef.current = query;
+      setSize(1);
+    }
+  }, [query, setSize]);
+
+  const results = data ? dedupeByAsin(data.flatMap(page => page?.results || [])) : [];
+  const totalResults = data?.[0]?.totalResults || 0;
+  const hasMore = !!(data && data.length > 0 && data[data.length - 1]?.hasMore);
+  const isLoadingInitial = !data && !error && !!query;
+  const isLoadingMore = !!(data && typeof data[size - 1] === 'undefined' && isValidating);
+
+  const loadMore = useCallback(() => {
+    setSize(prev => prev + 1);
+  }, [setSize]);
 
   return {
-    results: data?.results || [],
-    totalResults: data?.totalResults || 0,
-    hasMore: data?.hasMore || false,
-    isLoading: shouldFetch && isLoading,
+    results,
+    totalResults,
+    hasMore,
+    isLoading: isLoadingInitial,
+    isLoadingMore,
+    loadMore,
     error,
   };
 }

src/lib/hooks/useAuthors.ts

@@ -5,7 +5,9 @@
 
 'use client';
 
+import { useRef, useEffect, useCallback } from 'react';
 import useSWR from 'swr';
+import useSWRInfinite from 'swr/infinite';
 import { authenticatedFetcher } from '@/lib/utils/api';
 import { Audiobook } from './useAudiobooks';
 
@@ -68,21 +70,59 @@ export function useAuthorDetail(asin: string | null) {
   };
 }
 
-export function useAuthorBooks(asin: string | null, authorName: string | null) {
-  const shouldFetch = asin && authorName;
-  const endpoint = shouldFetch
-    ? `/api/authors/${asin}/books?name=${encodeURIComponent(authorName)}`
-    : null;
-
-  const { data, error, isLoading } = useSWR(endpoint, authenticatedFetcher, {
-    revalidateOnFocus: false,
-    dedupingInterval: 60000, // Cache for 1 minute
+function dedupeByAsin<T extends { asin: string }>(items: T[]): T[] {
+  const seen = new Set<string>();
+  return items.filter(item => {
+    if (seen.has(item.asin)) return false;
+    seen.add(item.asin);
+    return true;
   });
+}
+
+export function useAuthorBooks(asin: string | null, authorName: string | null) {
+  const prevIdentityRef = useRef<string | null>(null);
+  const identity = asin && authorName ? `${asin}:${authorName}` : null;
+
+  const { data, error, size, setSize, isLoading, isValidating } = useSWRInfinite(
+    (pageIndex, prevPageData) => {
+      if (!asin || !authorName) return null;
+      if (pageIndex === 0) return `/api/authors/${asin}/books?name=${encodeURIComponent(authorName)}&page=1`;
+      if (!prevPageData?.hasMore) return null;
+      return `/api/authors/${asin}/books?name=${encodeURIComponent(authorName)}&page=${pageIndex + 1}`;
+    },
+    authenticatedFetcher,
+    {
+      revalidateOnFocus: false,
+      dedupingInterval: 60000,
+      revalidateFirstPage: false,
+    }
+  );
+
+  // Reset when author changes
+  useEffect(() => {
+    if (identity !== prevIdentityRef.current) {
+      prevIdentityRef.current = identity;
+      setSize(1);
+    }
+  }, [identity, setSize]);
+
+  const books = (data ? dedupeByAsin(data.flatMap(page => page?.books || [])) : []) as Audiobook[];
+  const totalBooks = data?.[0]?.totalBooks || 0;
+  const hasMore = !!(data && data.length > 0 && data[data.length - 1]?.hasMore);
+  const isLoadingInitial = !data && !error && !!identity;
+  const isLoadingMore = !!(data && typeof data[size - 1] === 'undefined' && isValidating);
+
+  const loadMore = useCallback(() => {
+    setSize(prev => prev + 1);
+  }, [setSize]);
 
   return {
-    books: (data?.books || []) as Audiobook[],
-    totalBooks: data?.totalBooks || 0,
-    isLoading: !!shouldFetch && isLoading,
+    books,
+    totalBooks,
+    hasMore,
+    isLoading: isLoadingInitial || (!!identity && isLoading),
+    isLoadingMore,
+    loadMore,
     error,
   };
 }

src/lib/hooks/useRequests.ts

@@ -515,6 +515,25 @@ export function useEbookStatus(asin: string | null) {
   };
 }
 
+interface DownloadStatus {
+  downloadAvailable: boolean;
+  requestId: string | null;
+}
+
+export function useDownloadStatus(asin: string | null) {
+  const { accessToken } = useAuth();
+
+  const endpoint = accessToken && asin ? `/api/audiobooks/${asin}/download-status` : null;
+
+  const { data, isLoading } = useSWR<DownloadStatus>(endpoint, fetcher);
+
+  return {
+    downloadAvailable: data?.downloadAvailable ?? false,
+    requestId: data?.requestId ?? null,
+    isLoading,
+  };
+}
+
 export function useFetchEbookByAsin() {
   const { accessToken } = useAuth();
   const [isLoading, setIsLoading] = useState(false);

src/lib/hooks/useSeries.ts

@@ -5,7 +5,9 @@
 
 'use client';
 
+import { useRef, useEffect, useCallback } from 'react';
 import useSWR from 'swr';
+import useSWRInfinite from 'swr/infinite';
 import { authenticatedFetcher } from '@/lib/utils/api';
 import { Audiobook } from './useAudiobooks';
 
@@ -59,17 +61,63 @@ export function useSeriesSearch(query: string) {
   };
 }
 
-export function useSeriesDetail(asin: string | null) {
-  const endpoint = asin ? `/api/series/${asin}` : null;
-
-  const { data, error, isLoading } = useSWR(endpoint, authenticatedFetcher, {
-    revalidateOnFocus: false,
-    dedupingInterval: 300000, // Cache for 5 minutes
+function dedupeByAsin<T extends { asin: string }>(items: T[]): T[] {
+  const seen = new Set<string>();
+  return items.filter(item => {
+    if (seen.has(item.asin)) return false;
+    seen.add(item.asin);
+    return true;
   });
+}
+
+export function useSeriesDetail(asin: string | null) {
+  const prevAsinRef = useRef<string | null>(null);
+
+  const { data, error, size, setSize, isLoading, isValidating } = useSWRInfinite(
+    (pageIndex, prevPageData) => {
+      if (!asin) return null;
+      if (pageIndex === 0) return `/api/series/${asin}?page=1`;
+      if (!prevPageData?.hasMore) return null;
+      return `/api/series/${asin}?page=${pageIndex + 1}`;
+    },
+    authenticatedFetcher,
+    {
+      revalidateOnFocus: false,
+      dedupingInterval: 300000,
+      revalidateFirstPage: false,
+    }
+  );
+
+  // Reset when series changes
+  useEffect(() => {
+    if (asin !== prevAsinRef.current) {
+      prevAsinRef.current = asin;
+      setSize(1);
+    }
+  }, [asin, setSize]);
+
+  // Merge pages: use first page's metadata, accumulate all books
+  const firstPageSeries = data?.[0]?.series as SeriesDetail | undefined;
+  const allBooks = (data ? dedupeByAsin(data.flatMap(page => page?.series?.books || [])) : []) as Audiobook[];
+
+  const series: SeriesDetail | null = firstPageSeries
+    ? { ...firstPageSeries, books: allBooks }
+    : null;
+
+  const hasMore = !!(data && data.length > 0 && data[data.length - 1]?.hasMore);
+  const isLoadingInitial = !data && !error && !!asin;
+  const isLoadingMore = !!(data && typeof data[size - 1] === 'undefined' && isValidating);
+
+  const loadMore = useCallback(() => {
+    setSize(prev => prev + 1);
+  }, [setSize]);
 
   return {
-    series: (data?.series || null) as SeriesDetail | null,
-    isLoading,
+    series,
+    hasMore,
+    isLoading: isLoadingInitial || (!!asin && isLoading),
+    isLoadingMore,
+    loadMore,
     error,
   };
 }

src/lib/integrations/audible-series.ts

@@ -288,17 +288,17 @@ function parseSeriesPageSummary(
  * Scrape a series page for full detail data including books and similar series.
  * Used by the detail API endpoint.
  */
-export async function scrapeSeriesPage(asin: string): Promise<SeriesDetail | null> {
+export async function scrapeSeriesPage(asin: string, page: number = 1): Promise<(SeriesDetail & { hasMore: boolean; page: number }) | null> {
   const service = getAudibleService();
   const region = service.getRegion();
   const baseUrl = service.getBaseUrl();
   const langConfig = getLanguageForRegion(region);
 
-  logger.info(`Scraping series detail page: ${asin}`);
+  logger.info(`Scraping series detail page: ${asin}, page ${page}`);
 
   try {
     const { data: response } = await service.fetch(`/series/${asin}`, {
-      params: { ipRedirectOverride: 'true', pageSize: AUDIBLE_PAGE_SIZE },
+      params: { ipRedirectOverride: 'true', pageSize: AUDIBLE_PAGE_SIZE, page },
     });
     const $ = cheerio.load(response.data);
 
@@ -316,10 +316,15 @@ export async function scrapeSeriesPage(asin: string): Promise<SeriesDetail | nul
     // Use actual book count if we got more from scraping
     const bookCount = Math.max(summary.bookCount, books.length);
 
+    // Calculate hasMore: use header bookCount if available, otherwise check if full page
+    const hasMore = bookCount > 0
+      ? page * AUDIBLE_PAGE_SIZE < bookCount
+      : books.length >= AUDIBLE_PAGE_SIZE;
+
     // Parse similar series ("Listeners also enjoyed" or similar section)
     const similarSeries = parseSimilarSeries($);
 
-    logger.info(`Series detail complete: "${summary.title}" (${books.length} books, ${similarSeries.length} similar)`);
+    logger.info(`Series detail complete: "${summary.title}" (${books.length} books, page ${page}, hasMore: ${hasMore})`);
 
     return {
       asin,
@@ -332,6 +337,8 @@ export async function scrapeSeriesPage(asin: string): Promise<SeriesDetail | nul
       books,
       similarSeries,
       audibleUrl: `${baseUrl}/series/${asin}`,
+      hasMore,
+      page,
     };
   } catch (error) {
     logger.error(`Failed to scrape series detail ${asin}`, {
@@ -414,10 +421,12 @@ function parseSeriesBooks(
     if (!bookAsin || seenAsins.has(bookAsin)) return;
     seenAsins.add(bookAsin);
 
-    // Title
-    const title = $el.find('h2').first().text().trim() ||
-      $el.find('h3 a').first().text().trim() ||
+    // Title: h3 a / .bc-heading a hold the real book title;
+    // h2 on series pages is the position label ("Book 1"), so try it last.
+    const title = $el.find('h3 a').first().text().trim() ||
       $el.find('.bc-heading a').first().text().trim() ||
+      $el.find('h2 a').first().text().trim() ||
+      $el.find('h2').first().text().trim() ||
       '';
 
     if (!title) return;

src/lib/integrations/audible.service.ts

@@ -59,6 +59,13 @@ export interface AudibleSearchResult {
   hasMore: boolean;
 }
 
+export interface AuthorBooksResult {
+  books: AudibleAudiobook[];
+  hasMore: boolean;
+  page: number;
+  totalResults: number;
+}
+
 export class AudibleService {
   private client!: AxiosInstance;
   private baseUrl: string = 'https://www.audible.com';
@@ -564,7 +571,9 @@ export class AudibleService {
         results: audiobooks,
         totalResults,
         page,
-        hasMore: audiobooks.length > 0 && totalResults > page * AUDIBLE_PAGE_SIZE,
+        hasMore: audiobooks.length > 0 && (totalResults > 0
+          ? totalResults > page * AUDIBLE_PAGE_SIZE
+          : audiobooks.length >= AUDIBLE_PAGE_SIZE),
       };
     } catch (error) {
       logger.error('Search failed', { error: error instanceof Error ? error.message : String(error) });
@@ -583,123 +592,111 @@ export class AudibleService {
    * Uses Audible's searchAuthor parameter and paginates through all results.
    * Filters: (1) author link must contain the target ASIN, (2) language must be English.
    */
-  async searchByAuthorAsin(authorName: string, authorAsin: string): Promise<AudibleAudiobook[]> {
+  async searchByAuthorAsin(authorName: string, authorAsin: string, page: number = 1): Promise<AuthorBooksResult> {
     await this.initialize();
 
-    const MAX_PAGES = 10;
-    const allBooks: AudibleAudiobook[] = [];
+    const books: AudibleAudiobook[] = [];
     const seenAsins = new Set<string>();
 
     try {
-      logger.info(`Searching books by author "${authorName}" (ASIN: ${authorAsin})...`);
+      logger.info(`Searching books by author "${authorName}" (ASIN: ${authorAsin}), page ${page}...`);
 
-      for (let page = 1; page <= MAX_PAGES; page++) {
-        const { data: response, meta } = await this.fetchWithRetry('/search', {
-          params: {
-            ipRedirectOverride: 'true',
-            searchAuthor: authorName,
-            pageSize: AUDIBLE_PAGE_SIZE,
-            page,
-          },
+      const { data: response } = await this.fetchWithRetry('/search', {
+        params: {
+          ipRedirectOverride: 'true',
+          searchAuthor: authorName,
+          pageSize: AUDIBLE_PAGE_SIZE,
+          page,
+        },
+      });
+
+      const $ = cheerio.load(response.data);
+
+      // Count raw items on page before filtering (for hasMore fallback)
+      const pageItemCount = $('.s-result-item, .productListItem').length;
+
+      $('.s-result-item, .productListItem').each((_index, element) => {
+        const $el = $(element);
+
+        // --- Language filter: require matching language for region ---
+        const langConfig = this.getLangConfig();
+        const langText = $el.find(buildContainsSelector('span', langConfig.scraping.languageLabels)).text().trim() ||
+                         $el.find('.languageLabel').text().trim();
+        const langLabelPattern = new RegExp(`(?:${langConfig.scraping.languageLabels.map(l => l.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})\\s*(.+)`, 'i');
+        const langMatch = langText.match(langLabelPattern);
+        const language = langMatch?.[1]?.trim();
+        if (!language || !isAcceptedLanguage(language, langConfig)) return;
+
+        // --- Author ASIN filter: verify target ASIN in author links ---
+        const authorLinks = $el.find('a[href*="/author/"]');
+        let hasMatchingAuthor = false;
+        authorLinks.each((_i, link) => {
+          const href = $(link).attr('href') || '';
+          const asinMatch = href.match(/\/author\/[^\/]+\/([A-Z0-9]{10})/);
+          if (asinMatch && asinMatch[1] === authorAsin) {
+            hasMatchingAuthor = true;
+            return false; // break .each()
+          }
         });
+        if (!hasMatchingAuthor) return;
 
-        const $ = cheerio.load(response.data);
-        let pageResults = 0;
+        // --- Extract book ASIN ---
+        const bookAsin = $el.find('li').attr('data-asin') ||
+                         $el.find('a[href*="/pd/"]').attr('href')?.match(/\/pd\/[^\/]+\/([A-Z0-9]{10})/)?.[1] ||
+                         $el.find('a[href*="/ac/"]').attr('href')?.match(/\/ac\/[^\/]+\/([A-Z0-9]{10})/)?.[1] ||
+                         $el.find('a').attr('href')?.match(/\/(?:pd|ac)\/[^\/]+\/([A-Z0-9]{10})/)?.[1] || '';
+        if (!bookAsin || seenAsins.has(bookAsin)) return;
+        seenAsins.add(bookAsin);
 
-        $('.s-result-item, .productListItem').each((_index, element) => {
-          const $el = $(element);
+        // --- Parse book details ---
+        const title = $el.find('h2').first().text().trim() ||
+                      $el.find('h3 a').text().trim() ||
+                      $el.find('.bc-heading a').text().trim();
 
-          // --- Language filter: require matching language for region ---
-          const langConfig = this.getLangConfig();
-          const langText = $el.find(buildContainsSelector('span', langConfig.scraping.languageLabels)).text().trim() ||
-                           $el.find('.languageLabel').text().trim();
-          // Extract language value (e.g. "Language: English" -> "English", "Sprache: Deutsch" -> "Deutsch")
-          const langLabelPattern = new RegExp(`(?:${langConfig.scraping.languageLabels.map(l => l.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})\\s*(.+)`, 'i');
-          const langMatch = langText.match(langLabelPattern);
-          const language = langMatch?.[1]?.trim();
-          if (!language || !isAcceptedLanguage(language, langConfig)) return;
+        const authorText = $el.find('a[href*="/author/"]').first().text().trim() ||
+                           $el.find('.authorLabel').text().trim() ||
+                           $el.find('.bc-size-small .bc-text-bold').first().text().trim();
 
-          // --- Author ASIN filter: verify target ASIN in author links ---
-          const authorLinks = $el.find('a[href*="/author/"]');
-          let hasMatchingAuthor = false;
-          authorLinks.each((_i, link) => {
-            const href = $(link).attr('href') || '';
-            const asinMatch = href.match(/\/author\/[^\/]+\/([A-Z0-9]{10})/);
-            if (asinMatch && asinMatch[1] === authorAsin) {
-              hasMatchingAuthor = true;
-              return false; // break .each()
-            }
-          });
-          if (!hasMatchingAuthor) return;
+        const narratorText = $el.find('a[href*="searchNarrator="]').first().text().trim() ||
+                             $el.find('.narratorLabel').text().trim();
 
-          // --- Extract book ASIN ---
-          const bookAsin = $el.find('li').attr('data-asin') ||
-                           $el.find('a[href*="/pd/"]').attr('href')?.match(/\/pd\/[^\/]+\/([A-Z0-9]{10})/)?.[1] ||
-                           $el.find('a[href*="/ac/"]').attr('href')?.match(/\/ac\/[^\/]+\/([A-Z0-9]{10})/)?.[1] ||
-                           $el.find('a').attr('href')?.match(/\/(?:pd|ac)\/[^\/]+\/([A-Z0-9]{10})/)?.[1] || '';
-          if (!bookAsin || seenAsins.has(bookAsin)) return;
-          seenAsins.add(bookAsin);
+        const coverArtUrl = $el.find('img').attr('src') || '';
 
-          // --- Parse book details ---
-          const title = $el.find('h2').first().text().trim() ||
-                        $el.find('h3 a').text().trim() ||
-                        $el.find('.bc-heading a').text().trim();
+        const runtimeText = $el.find('.runtimeLabel').text().trim() ||
+                            $el.find(buildContainsSelector('span', langConfig.scraping.lengthLabels)).text().trim();
+        const durationMinutes = this.parseRuntime(runtimeText);
 
-          const authorText = $el.find('a[href*="/author/"]').first().text().trim() ||
-                             $el.find('.authorLabel').text().trim() ||
-                             $el.find('.bc-size-small .bc-text-bold').first().text().trim();
+        const ratingText = $el.find('.ratingsLabel').text().trim() ||
+                           $el.find('.a-icon-star span').first().text().trim();
+        const rating = ratingText ? parseFloat(ratingText.split(' ')[0]) : undefined;
 
-          const narratorText = $el.find('a[href*="searchNarrator="]').first().text().trim() ||
-                               $el.find('.narratorLabel').text().trim();
-
-          const coverArtUrl = $el.find('img').attr('src') || '';
-
-          const runtimeText = $el.find('.runtimeLabel').text().trim() ||
-                              $el.find(buildContainsSelector('span', langConfig.scraping.lengthLabels)).text().trim();
-          const durationMinutes = this.parseRuntime(runtimeText);
-
-          const ratingText = $el.find('.ratingsLabel').text().trim() ||
-                             $el.find('.a-icon-star span').first().text().trim();
-          const rating = ratingText ? parseFloat(ratingText.split(' ')[0]) : undefined;
-
-          allBooks.push({
-            asin: bookAsin,
-            title,
-            author: stripPrefixes(authorText, langConfig.scraping.authorPrefixes),
-            authorAsin,
-            narrator: stripPrefixes(narratorText, langConfig.scraping.narratorPrefixes),
-            coverArtUrl: coverArtUrl.replace(/\._.*_\./, '._SL500_.'),
-            durationMinutes,
-            rating,
-          });
-
-          pageResults++;
+        books.push({
+          asin: bookAsin,
+          title,
+          author: stripPrefixes(authorText, langConfig.scraping.authorPrefixes),
+          authorAsin,
+          narrator: stripPrefixes(narratorText, langConfig.scraping.narratorPrefixes),
+          coverArtUrl: coverArtUrl.replace(/\._.*_\./, '._SL500_.'),
+          durationMinutes,
+          rating,
         });
+      });
 
-        // Check if there are more pages
-        const resultsText = $('.resultsInfo').text().trim();
-        const totalResults = parseInt(resultsText.match(/of ([\d,]+)/)?.[1]?.replace(/,/g, '') || '0');
-        const hasMore = totalResults > page * AUDIBLE_PAGE_SIZE;
+      // Check total results for pagination
+      const resultsText = $('.resultsInfo').text().trim();
+      const totalResults = parseInt(resultsText.match(/of ([\d,]+)/)?.[1]?.replace(/,/g, '') || '0');
+      // Use totalResults if available; otherwise fall back to whether Audible returned a full page
+      const hasMore = books.length > 0 && (totalResults > 0
+        ? totalResults > page * AUDIBLE_PAGE_SIZE
+        : pageItemCount >= AUDIBLE_PAGE_SIZE);
 
-        logger.info(`Author books page ${page}: ${pageResults} valid results (${allBooks.length} total, ${totalResults} Audible total)`);
-
-        if (!hasMore || pageResults === 0) break;
-
-        // Pace between pages
-        if (page < MAX_PAGES) {
-          await this.delay(this.pacer.reportPageResult(meta));
-        }
-      }
-
-      logger.info(`Author books search complete: "${authorName}" → ${allBooks.length} books`);
-      return allBooks;
+      logger.info(`Author books page ${page}: ${books.length} valid results (${totalResults} Audible total)`);
+      return { books, hasMore, page, totalResults };
     } catch (error) {
       logger.error(`Author books search failed for "${authorName}"`, {
         error: error instanceof Error ? error.message : String(error),
-        collectedSoFar: allBooks.length,
       });
-      // Return what we collected before the error
-      return allBooks;
+      return { books, hasMore: false, page, totalResults: 0 };
     }
   }
 

src/lib/integrations/deluge.service.ts

@@ -0,0 +1,386 @@
+/**
+ * Component: Deluge Integration Service
+ * Documentation: documentation/phase3/download-clients.md
+ */
+
+import axios, { AxiosInstance } from 'axios';
+import https from 'https';
+import path from 'path';
+import { DOWNLOAD_CLIENT_TIMEOUT } from '../constants/download-timeouts';
+import * as parseTorrentModule from 'parse-torrent';
+import { RMABLogger } from '../utils/logger';
+import { PathMapper, PathMappingConfig } from '../utils/path-mapper';
+import {
+  IDownloadClient, DownloadClientType, ProtocolType,
+  DownloadInfo, DownloadStatus, AddDownloadOptions, ConnectionTestResult,
+} from '../interfaces/download-client.interface';
+
+const parseTorrent = (parseTorrentModule as any).default || parseTorrentModule;
+const logger = RMABLogger.create('Deluge');
+
+export class DelugeService implements IDownloadClient {
+  readonly clientType: DownloadClientType = 'deluge';
+  readonly protocol: ProtocolType = 'torrent';
+
+  private client: AxiosInstance;
+  private baseUrl: string;
+  private password: string;
+  private defaultSavePath: string;
+  private defaultCategory: string;
+  private pathMappingConfig: PathMappingConfig;
+  private sessionCookie: string = '';
+  private requestId: number = 0;
+
+  constructor(
+    baseUrl: string,
+    _username: string, // Unused — Deluge uses password-only auth; kept for consistent signature
+    password: string,
+    defaultSavePath: string = '/downloads',
+    defaultCategory: string = 'readmeabook',
+    disableSSLVerify: boolean = false,
+    pathMappingConfig?: PathMappingConfig
+  ) {
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.password = password;
+    this.defaultSavePath = defaultSavePath;
+    this.defaultCategory = defaultCategory;
+    this.pathMappingConfig = pathMappingConfig || { enabled: false, remotePath: '', localPath: '' };
+
+    const httpsAgent = disableSSLVerify && this.baseUrl.startsWith('https')
+      ? new https.Agent({ rejectUnauthorized: false }) : undefined;
+    if (httpsAgent) logger.info('[Deluge] SSL certificate verification disabled');
+
+    this.client = axios.create({ baseURL: this.baseUrl, timeout: DOWNLOAD_CLIENT_TIMEOUT, httpsAgent });
+  }
+
+  /** JSON-RPC call with automatic re-authentication on auth failure */
+  private async rpc(method: string, params: any[] = [], retried = false): Promise<any> {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (this.sessionCookie) headers['Cookie'] = this.sessionCookie;
+
+    try {
+      const reqId = ++this.requestId;
+      const { data } = await this.client.post('/json', { method, params, id: reqId }, { headers });
+      // Deluge error.code === 1: "Not authenticated" — re-login then retry
+      if (data.error?.code === 1 && !retried) {
+        await this.login();
+        return this.rpc(method, params, true);
+      }
+      // Deluge error.code === 2: "Unknown method" — daemon disconnected, force reconnect
+      // Only retry for core.* methods — plugin methods (label.*) fail because the plugin
+      // isn't enabled, not because the daemon is disconnected.
+      if (data.error?.code === 2 && !retried && method.startsWith('core.')) {
+        await this.login(true);
+        return this.rpc(method, params, true);
+      }
+      return data;
+    } catch (error) {
+      if (!retried) { await this.login(); return this.rpc(method, params, true); }
+      throw error;
+    }
+  }
+
+  private async login(forceReconnect: boolean = false): Promise<void> {
+    const { data, headers } = await this.client.post(
+      '/json',
+      { method: 'auth.login', params: [this.password], id: ++this.requestId },
+      { headers: { 'Content-Type': 'application/json' } }
+    );
+    if (!data?.result) throw new Error('Failed to authenticate with Deluge — check your password');
+    const cookies = headers['set-cookie'];
+    if (cookies?.length) this.sessionCookie = cookies[0].split(';')[0];
+    logger.info('Successfully authenticated with Deluge');
+
+    // Deluge Web UI requires a daemon connection before core.* methods work.
+    // When forceReconnect is true, skip the web.connected check and force a fresh connection.
+    await this.ensureDaemonConnected(forceReconnect);
+  }
+
+  /**
+   * Ensure the Web UI is connected to a deluged daemon host.
+   * Uses web.connected (returns boolean) as the check — daemon.info is NOT a valid
+   * method through the Deluge Web UI JSON-RPC; only web.* and core.* methods work.
+   */
+  private async ensureDaemonConnected(force: boolean = false): Promise<void> {
+    if (!force) {
+      const test = await this.rpc('web.connected', [], true);
+      if (test.result === true) return;
+    }
+
+    logger.info('Connecting to daemon...');
+
+    const hostsData = await this.rpc('web.get_hosts', [], true);
+    const hosts: any[] = hostsData.result || [];
+
+    if (hosts.length === 0) {
+      throw new Error('Deluge has no daemon hosts configured. Add a host in the Deluge Web UI under Connection Manager.');
+    }
+
+    const hostId = hosts[0][0];
+    const connectResult = await this.rpc('web.connect', [hostId], true);
+    if (connectResult.error) {
+      throw new Error(`Failed to connect to Deluge daemon: ${connectResult.error.message}`);
+    }
+
+    // Verify connection is established
+    const verify = await this.rpc('web.connected', [], true);
+    if (verify.result !== true) {
+      throw new Error('Deluge daemon failed to respond after web.connect. Check that deluged is running.');
+    }
+
+    logger.info('Connected to Deluge daemon');
+  }
+
+  // =========================================================================
+  // IDownloadClient Implementation
+  // =========================================================================
+
+  async testConnection(): Promise<ConnectionTestResult> {
+    try {
+      await this.login();
+      return { success: true, message: 'Connected to Deluge' };
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : 'Connection failed';
+      if (axios.isAxiosError(error)) {
+        const c = error.code;
+        if (c?.includes('CERT') || c?.includes('SSL')) return { success: false, message: `SSL verification failed (${c}). Enable "Disable SSL Verification".` };
+        if (c === 'ECONNREFUSED') return { success: false, message: `Connection refused at: ${this.baseUrl}` };
+        if (c === 'ETIMEDOUT' || c === 'ECONNABORTED') return { success: false, message: `Connection timeout: ${this.baseUrl}` };
+        if (c === 'ENOTFOUND') return { success: false, message: `Host not found: ${this.baseUrl}` };
+        if (error.response?.status === 401) return { success: false, message: 'Authentication failed. Check your password.' };
+      }
+      logger.error('Connection test failed', { error: msg });
+      return { success: false, message: msg };
+    }
+  }
+
+  async addDownload(url: string, options?: AddDownloadOptions): Promise<string> {
+    if (!url || typeof url !== 'string' || url.trim() === '') {
+      throw new Error('Invalid download URL: URL is required and must be a non-empty string');
+    }
+    const category = options?.category || this.defaultCategory;
+    return url.startsWith('magnet:')
+      ? this.addMagnetLink(url, category, options)
+      : this.addTorrentFile(url, category, options);
+  }
+
+  private async addMagnetLink(magnetUrl: string, category: string, options?: AddDownloadOptions): Promise<string> {
+    const infoHash = this.extractHashFromMagnet(magnetUrl);
+    if (!infoHash) throw new Error('Invalid magnet link - could not extract info_hash');
+    logger.info(`Extracted info_hash from magnet: ${infoHash}`);
+
+    const existing = await this.rpc('core.get_torrent_status', [infoHash, ['name']]);
+    if (existing.result && Object.keys(existing.result).length > 0) {
+      logger.info(`Torrent ${infoHash} already exists (duplicate)`);
+      return infoHash;
+    }
+
+    const opts = this.buildTorrentOptions(options?.paused);
+    const data = await this.rpc('core.add_torrent_magnet', [magnetUrl, opts]);
+    if (!data.result) throw new Error(`Deluge rejected magnet link: ${data.error?.message || 'unknown error'}`);
+
+    await this.postAddSetup(data.result, category);
+    logger.info(`Successfully added magnet link: ${infoHash}`);
+    return infoHash;
+  }
+
+  private async addTorrentFile(torrentUrl: string, category: string, options?: AddDownloadOptions): Promise<string> {
+    logger.info(`Downloading .torrent file from: ${torrentUrl}`);
+
+    let torrentResponse;
+    try {
+      torrentResponse = await axios.get(torrentUrl, {
+        responseType: 'arraybuffer', maxRedirects: 0,
+        validateStatus: (s) => s >= 200 && s < 300, timeout: DOWNLOAD_CLIENT_TIMEOUT,
+      });
+      if (torrentResponse.data.length > 0) {
+        const magnetMatch = torrentResponse.data.toString().match(/^magnet:\?[^\s]+$/);
+        if (magnetMatch) return this.addMagnetLink(magnetMatch[0], category, options);
+      }
+    } catch (error) {
+      if (!axios.isAxiosError(error) || !error.response) throw error;
+      const status = error.response.status;
+      if (status >= 300 && status < 400) {
+        const loc = error.response.headers['location'];
+        if (loc?.startsWith('magnet:')) return this.addMagnetLink(loc, category, options);
+        if (loc?.startsWith('http://') || loc?.startsWith('https://')) {
+          try { torrentResponse = await axios.get(loc, { responseType: 'arraybuffer', timeout: DOWNLOAD_CLIENT_TIMEOUT, maxRedirects: 5 }); }
+          catch { throw new Error('Failed to download torrent file after redirect'); }
+        } else { throw new Error(`Invalid redirect location: ${loc}`); }
+      } else { throw new Error(`Failed to download torrent: HTTP ${status}`); }
+    }
+
+    const torrentBuffer = Buffer.from(torrentResponse.data);
+    let parsed: any;
+    try { parsed = await parseTorrent(torrentBuffer); }
+    catch { throw new Error('Invalid .torrent file - failed to parse'); }
+
+    const infoHash = parsed.infoHash;
+    if (!infoHash) throw new Error('Failed to extract info_hash from .torrent file');
+    logger.info(`Extracted info_hash: ${infoHash}`);
+
+    const existing = await this.rpc('core.get_torrent_status', [infoHash, ['name']]);
+    if (existing.result && Object.keys(existing.result).length > 0) {
+      logger.info(`Torrent ${infoHash} already exists (duplicate)`);
+      return infoHash;
+    }
+
+    const filename = parsed.name ? `${parsed.name}.torrent` : 'torrent.torrent';
+    const opts = this.buildTorrentOptions(options?.paused);
+    const data = await this.rpc('core.add_torrent_file', [filename, torrentBuffer.toString('base64'), opts]);
+    if (!data.result) throw new Error(`Deluge rejected .torrent file: ${data.error?.message || 'unknown error'}`);
+
+    await this.postAddSetup(infoHash, category);
+    logger.info(`Successfully added torrent: ${infoHash}`);
+    return infoHash;
+  }
+
+  async getDownload(id: string): Promise<DownloadInfo | null> {
+    const fields = ['name', 'total_size', 'total_done', 'progress', 'state',
+      'download_payload_rate', 'eta', 'label', 'save_path',
+      'time_added', 'is_finished', 'seeding_time', 'ratio', 'message'];
+
+    for (let attempt = 0; attempt <= 3; attempt++) {
+      const { result } = await this.rpc('core.get_torrent_status', [id, fields]);
+      if (result && Object.keys(result).length > 0) return this.mapToDownloadInfo(id, result);
+      if (attempt === 3) return null;
+      const delay = 500 * Math.pow(2, attempt);
+      logger.warn(`Torrent ${id} not found, retrying in ${delay}ms (${attempt + 1}/3)`);
+      await new Promise(r => setTimeout(r, delay));
+    }
+    return null;
+  }
+
+  async pauseDownload(id: string): Promise<void> {
+    await this.rpc('core.pause_torrent', [[id]]);
+    logger.info(`Paused torrent: ${id}`);
+  }
+
+  async resumeDownload(id: string): Promise<void> {
+    await this.rpc('core.resume_torrent', [[id]]);
+    logger.info(`Resumed torrent: ${id}`);
+  }
+
+  async deleteDownload(id: string, deleteFiles: boolean = false): Promise<void> {
+    await this.rpc('core.remove_torrent', [id, deleteFiles]);
+    logger.info(`Deleted torrent: ${id}`);
+  }
+
+  async postProcess(_id: string): Promise<void> {} // No-op: seeding cleanup scheduler manages lifecycle
+
+  async getCategories(): Promise<string[]> {
+    try { const { result } = await this.rpc('label.get_labels'); return Array.isArray(result) ? result : []; }
+    catch { return []; }
+  }
+
+  async setCategory(id: string, category: string): Promise<void> {
+    await this.applyLabel(id, category);
+    logger.info(`Set label for torrent ${id}: ${category}`);
+  }
+
+  // =========================================================================
+  // Internal Helpers
+  // =========================================================================
+
+  private buildTorrentOptions(paused?: boolean): Record<string, any> {
+    const remoteSavePath = PathMapper.reverseTransform(this.defaultSavePath, this.pathMappingConfig);
+    const opts: Record<string, any> = { download_location: remoteSavePath, move_completed: false, move_completed_path: '' };
+    if (paused) opts.add_paused = true;
+    return opts;
+  }
+
+  private async postAddSetup(hash: string, category: string): Promise<void> {
+    await this.disableSeedLimits(hash);
+    await this.applyLabel(hash, category);
+  }
+
+  private async applyLabel(hash: string, label: string): Promise<void> {
+    try {
+      try { await this.rpc('label.add', [label]); } catch { /* may already exist */ }
+      await this.rpc('label.set_torrent', [hash, label]);
+    } catch (error) {
+      logger.warn(`Failed to apply label "${label}" to ${hash}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  private async disableSeedLimits(hash: string): Promise<void> {
+    try {
+      await this.rpc('core.set_torrent_options', [[hash], { stop_at_ratio: false, seed_time_limit: -1 }]);
+    } catch (error) {
+      logger.warn(`Failed to disable seed limits for ${hash}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  private mapToDownloadInfo(hash: string, t: Record<string, any>): DownloadInfo {
+    return {
+      id: hash, name: t.name || '', size: t.total_size || 0,
+      bytesDownloaded: t.total_done || 0, progress: (t.progress || 0) / 100,
+      status: this.mapStatus(t.state), downloadSpeed: t.download_payload_rate || 0,
+      eta: t.eta > 0 ? t.eta : 0, category: t.label || '',
+      downloadPath: t.save_path ? path.join(t.save_path, t.name || '') : undefined,
+      completedAt: t.is_finished && t.time_added ? new Date(t.time_added * 1000) : undefined,
+      errorMessage: t.message || undefined, seedingTime: t.seeding_time,
+      ratio: t.ratio >= 0 ? t.ratio : undefined,
+    };
+  }
+
+  private mapStatus(state: string): DownloadStatus {
+    const map: Record<string, DownloadStatus> = {
+      'Downloading': 'downloading', 'Seeding': 'seeding', 'Paused': 'paused',
+      'Checking': 'checking', 'Queued': 'queued', 'Error': 'failed', 'Moving': 'downloading',
+    };
+    return map[state] || 'downloading';
+  }
+
+  private extractHashFromMagnet(magnetUrl: string): string | null {
+    const match = magnetUrl.match(/xt=urn:btih:([a-fA-F0-9]{40}|[a-zA-Z0-9]{32})/i);
+    return match ? match[1].toLowerCase() : null;
+  }
+}
+
+// Singleton factory (matches Transmission/qBittorrent pattern)
+let delugeServiceInstance: DelugeService | null = null;
+let configLoaded = false;
+
+export async function getDelugeService(): Promise<DelugeService> {
+  if (delugeServiceInstance && configLoaded) return delugeServiceInstance;
+
+  try {
+    const { getConfigService } = await import('../services/config.service');
+    const { getDownloadClientManager } = await import('../services/download-client-manager.service');
+    const configService = await getConfigService();
+    const manager = getDownloadClientManager(configService);
+
+    const clientConfig = await manager.getClientForProtocol('torrent');
+    if (!clientConfig) throw new Error('Deluge is not configured. Please configure a Deluge client in admin settings.');
+    if (clientConfig.type !== 'deluge') throw new Error(`Expected Deluge client but found ${clientConfig.type}`);
+    if (!clientConfig.url) throw new Error('Deluge is not fully configured. Check your configuration in admin settings.');
+
+    const baseDir = await configService.get('download_dir') || '/downloads';
+    const downloadDir = clientConfig.customPath ? require('path').join(baseDir, clientConfig.customPath) : baseDir;
+
+    delugeServiceInstance = new DelugeService(
+      clientConfig.url, clientConfig.username || '', clientConfig.password || '',
+      downloadDir, clientConfig.category || 'readmeabook', clientConfig.disableSSLVerify,
+      { enabled: clientConfig.remotePathMappingEnabled || false, remotePath: clientConfig.remotePath || '', localPath: clientConfig.localPath || '' }
+    );
+
+    const result = await delugeServiceInstance.testConnection();
+    if (!result.success) throw new Error(result.message || 'Deluge connection test failed.');
+
+    logger.info('[Deluge] Connection test successful');
+    configLoaded = true;
+    return delugeServiceInstance;
+  } catch (error) {
+    logger.error('[Deluge] Failed to initialize service', { error: error instanceof Error ? error.message : String(error) });
+    delugeServiceInstance = null;
+    configLoaded = false;
+    throw error;
+  }
+}
+
+export function invalidateDelugeService(): void {
+  delugeServiceInstance = null;
+  configLoaded = false;
+  logger.info('[Deluge] Service singleton invalidated');
+}

src/lib/integrations/prowlarr.service.ts

@@ -5,6 +5,7 @@
 
 import axios, { AxiosInstance } from 'axios';
 import { XMLParser } from 'fast-xml-parser';
+import { DOWNLOAD_CLIENT_TIMEOUT } from '../constants/download-timeouts';
 import { TorrentResult } from '../utils/ranking-algorithm';
 import { RMABLogger } from '../utils/logger';
 
@@ -87,7 +88,7 @@ export class ProwlarrService {
       headers: {
         'X-Api-Key': this.apiKey,
       },
-      timeout: 60000, // 60 seconds - some indexers (e.g. yggtorrent) enforce a 30s wait before download
+      timeout: DOWNLOAD_CLIENT_TIMEOUT,
       paramsSerializer: {
         serialize: (params) => {
           // Custom serializer to handle arrays correctly for Prowlarr API
@@ -314,7 +315,7 @@ export class ProwlarrService {
           limit: 100,
           extended: 1,
         },
-        timeout: 60000,
+        timeout: DOWNLOAD_CLIENT_TIMEOUT,
         responseType: 'text', // Get XML as text
       });
 

src/lib/integrations/qbittorrent.service.ts

@@ -6,6 +6,7 @@
 import axios, { AxiosInstance } from 'axios';
 import https from 'https';
 import path from 'path';
+import { DOWNLOAD_CLIENT_TIMEOUT } from '../constants/download-timeouts';
 import * as parseTorrentModule from 'parse-torrent';
 import FormData from 'form-data';
 import { RMABLogger } from '../utils/logger';
@@ -140,7 +141,7 @@ export class QBittorrentService implements IDownloadClient {
 
     this.client = axios.create({
       baseURL: `${this.baseUrl}/api/v2`,
-      timeout: 30000,
+      timeout: DOWNLOAD_CLIENT_TIMEOUT,
       httpsAgent: this.httpsAgent,
       // Support nginx/Apache reverse proxy with HTTP Basic Auth
       auth: {
@@ -352,7 +353,7 @@ export class QBittorrentService implements IDownloadClient {
         responseType: 'arraybuffer',
         maxRedirects: 0,
         validateStatus: (status) => status >= 200 && status < 300, // Only 2xx is success
-        timeout: 30000, // 30 seconds - public indexers can be slow
+        timeout: DOWNLOAD_CLIENT_TIMEOUT,
       });
 
       logger.info(` Got 2xx response, size=${torrentResponse.data.length} bytes`);
@@ -394,7 +395,7 @@ export class QBittorrentService implements IDownloadClient {
           try {
             torrentResponse = await axios.get(location, {
               responseType: 'arraybuffer',
-              timeout: 30000,
+              timeout: DOWNLOAD_CLIENT_TIMEOUT,
               maxRedirects: 5,
             });
             logger.info(` After following redirect: size=${torrentResponse.data.length} bytes`);
@@ -586,7 +587,19 @@ export class QBittorrentService implements IDownloadClient {
         throw new Error(`Torrent ${hash} not found`);
       }
 
-      return torrents[0];
+      // Find the torrent with the exact matching hash.
+      // Some qBittorrent-compatible clients (e.g. RDTClient) ignore the hashes
+      // filter and return all torrents, so we must verify the hash ourselves.
+      const normalizedHash = hash.toLowerCase();
+      const match = torrents.find(
+        (t: TorrentInfo) => t.hash?.toLowerCase() === normalizedHash
+      );
+
+      if (!match) {
+        throw new Error(`Torrent ${hash} not found`);
+      }
+
+      return match;
     } catch (error) {
       // Don't log error here - caller handles it (e.g., duplicate checking)
       throw error;
@@ -1076,17 +1089,27 @@ export class QBittorrentService implements IDownloadClient {
    * Map a TorrentInfo object to the unified DownloadInfo format.
    */
   protected mapTorrentToDownloadInfo(torrent: TorrentInfo): DownloadInfo {
+    const status = this.mapStateToDownloadStatus(torrent.state);
+
+    // content_path is the canonical path from qBittorrent — always use it directly.
+    // It correctly handles all torrent structures (multi-file folders, single files,
+    // single files in wrapper folders, name mismatches).
+    // For TempPathEnabled race detection, we expose save_path so the monitor can
+    // compare and wait for files to relocate before triggering file organization.
+    const downloadPath = torrent.content_path || path.join(torrent.save_path, torrent.name);
+
     return {
       id: torrent.hash,
       name: torrent.name,
       size: torrent.size,
       bytesDownloaded: torrent.downloaded,
       progress: torrent.progress,
-      status: this.mapStateToDownloadStatus(torrent.state),
+      status,
       downloadSpeed: torrent.dlspeed,
       eta: torrent.eta,
       category: torrent.category,
-      downloadPath: torrent.content_path || path.join(torrent.save_path, torrent.name),
+      downloadPath,
+      savePath: torrent.save_path,
       completedAt: torrent.completion_on > 0 ? new Date(torrent.completion_on * 1000) : undefined,
       seedingTime: torrent.seeding_time,
       ratio: torrent.ratio,
@@ -1103,7 +1126,7 @@ export class QBittorrentService implements IDownloadClient {
       stalledDL: 'downloading',
       stalledUP: 'seeding',
       pausedDL: 'paused',
-      // pausedUP = download finished, paused on upload side (e.g. RDT-Client, ratio met)
+      // pausedUP = download finished, paused on upload side (e.g. ratio met)
       pausedUP: 'seeding',
       queuedDL: 'queued',
       queuedUP: 'seeding',
@@ -1158,7 +1181,7 @@ export class QBittorrentService implements IDownloadClient {
       stalledDL: 'downloading',
       stalledUP: 'completed',
       pausedDL: 'paused',
-      // pausedUP = download finished, paused on upload side (e.g. RDT-Client, ratio met)
+      // pausedUP = download finished, paused on upload side (e.g. ratio met)
       pausedUP: 'completed',
       queuedDL: 'queued',
       queuedUP: 'completed',

src/lib/integrations/rdtclient.service.ts

@@ -1,105 +0,0 @@
-/**
- * Component: RDT-Client Integration Service
- * Documentation: documentation/phase3/download-clients.md
- *
- * RDT-Client is a Real-Debrid torrent proxy that emulates the qBittorrent API.
- * Extends QBittorrentService and overrides behavioral differences:
- * - Duplicate detection: deletes stale torrent before adding fresh (no false matches)
- * - postProcess: removes torrent entry from client after files are organized
- * - ensureCategory: no-op (RDT-Client doesn't support categories)
- */
-
-import { RMABLogger } from '../utils/logger';
-import { DownloadClientType } from '../interfaces/download-client.interface';
-import { QBittorrentService, AddTorrentOptions } from './qbittorrent.service';
-
-const logger = RMABLogger.create('RDTClient');
-
-export class RDTClientService extends QBittorrentService {
-  override readonly clientType: DownloadClientType = 'rdtclient';
-
-  /**
-   * Override: Delete any existing torrent with the same hash before adding.
-   * RDT-Client can have stale entries from previous requests that cause
-   * false duplicate detection — always start fresh.
-   */
-  protected override async addMagnetLink(
-    magnetUrl: string,
-    category: string,
-    options?: AddTorrentOptions
-  ): Promise<string> {
-    const infoHash = this.extractHashFromMagnet(magnetUrl);
-
-    if (infoHash) {
-      await this.deleteStaleIfExists(infoHash);
-    }
-
-    return super.addMagnetLink(magnetUrl, category, options);
-  }
-
-  /**
-   * Override: Delete any existing torrent with the same hash before adding.
-   * Same rationale as addMagnetLink — prevent false duplicate short-circuits.
-   */
-  protected override async addTorrentFile(
-    torrentUrl: string,
-    category: string,
-    options?: AddTorrentOptions
-  ): Promise<string> {
-    // We can't pre-extract the hash from a .torrent URL without downloading it,
-    // so we let the parent handle the full flow. The parent's duplicate check
-    // calls getTorrent which will find any stale entry — but the parent
-    // short-circuits on duplicates. To handle this, we override addTorrentFile
-    // to intercept after the parent downloads and parses the torrent.
-    //
-    // The parent's addTorrentFile downloads the .torrent, parses it, checks for
-    // duplicates, then uploads. Since we can't hook into the middle of that flow
-    // without duplicating the download logic, we accept that .torrent file adds
-    // may encounter a stale duplicate. The primary use case (magnet links from
-    // indexers) is handled by the addMagnetLink override above.
-    //
-    // For .torrent files, the parent will return the existing hash if a duplicate
-    // is found. The postProcess cleanup after organize will still clean it up.
-    return super.addTorrentFile(torrentUrl, category, options);
-  }
-
-  /**
-   * Override: Remove torrent entry from RDT-Client after files are organized.
-   * Unlike qBittorrent (which seeds), RDT-Client torrents should be cleaned up
-   * immediately — Real-Debrid handles seeding on their infrastructure.
-   */
-  override async postProcess(id: string): Promise<void> {
-    try {
-      logger.info(`Removing torrent ${id} from RDT-Client (post-organize cleanup)`);
-      await this.deleteTorrent(id, false);
-      logger.info(`Successfully removed torrent ${id} from RDT-Client`);
-    } catch (error) {
-      // Non-fatal: torrent may already have been removed
-      logger.warn(
-        `Failed to remove torrent ${id} from RDT-Client: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
-  }
-
-  /**
-   * Override: No-op. RDT-Client doesn't support qBittorrent categories.
-   * Avoids 404 errors that appear in logs when the parent tries to create/update categories.
-   */
-  protected override async ensureCategory(_category: string): Promise<void> {
-    // No-op: RDT-Client does not support categories
-  }
-
-  /**
-   * Delete a stale torrent if it exists, so a fresh add doesn't short-circuit.
-   */
-  private async deleteStaleIfExists(hash: string): Promise<void> {
-    try {
-      await this.getTorrent(hash);
-      // If we get here, torrent exists — delete it
-      logger.info(`Deleting stale torrent ${hash} from RDT-Client before fresh add`);
-      await this.deleteTorrent(hash, false);
-    } catch {
-      // Torrent doesn't exist — nothing to clean up
-    }
-  }
-}

src/lib/integrations/transmission.service.ts

@@ -6,6 +6,7 @@
 import axios, { AxiosInstance } from 'axios';
 import https from 'https';
 import path from 'path';
+import { DOWNLOAD_CLIENT_TIMEOUT } from '../constants/download-timeouts';
 import * as parseTorrentModule from 'parse-torrent';
 import { RMABLogger } from '../utils/logger';
 import { PathMapper, PathMappingConfig } from '../utils/path-mapper';
@@ -106,7 +107,7 @@ export class TransmissionService implements IDownloadClient {
 
     this.client = axios.create({
       baseURL: this.baseUrl,
-      timeout: 30000,
+      timeout: DOWNLOAD_CLIENT_TIMEOUT,
       httpsAgent: this.httpsAgent,
     });
   }
@@ -274,7 +275,7 @@ export class TransmissionService implements IDownloadClient {
         responseType: 'arraybuffer',
         maxRedirects: 0,
         validateStatus: (status) => status >= 200 && status < 300,
-        timeout: 30000,
+        timeout: DOWNLOAD_CLIENT_TIMEOUT,
       });
 
       // Check if response body is a magnet link
@@ -302,7 +303,7 @@ export class TransmissionService implements IDownloadClient {
           try {
             torrentResponse = await axios.get(location, {
               responseType: 'arraybuffer',
-              timeout: 30000,
+              timeout: DOWNLOAD_CLIENT_TIMEOUT,
               maxRedirects: 5,
             });
           } catch {

src/lib/interfaces/download-client.interface.ts

@@ -11,7 +11,7 @@
 // =========================================================================
 
 /** Supported download client types — single source of truth */
-export const SUPPORTED_CLIENT_TYPES = ['qbittorrent', 'sabnzbd', 'nzbget', 'transmission', 'rdtclient'] as const;
+export const SUPPORTED_CLIENT_TYPES = ['qbittorrent', 'sabnzbd', 'nzbget', 'transmission', 'deluge'] as const;
 
 /** Identifies the specific download client software */
 export type DownloadClientType = (typeof SUPPORTED_CLIENT_TYPES)[number];
@@ -22,7 +22,7 @@ export const CLIENT_DISPLAY_NAMES: Record<DownloadClientType, string> = {
   sabnzbd: 'SABnzbd',
   nzbget: 'NZBGet',
   transmission: 'Transmission',
-  rdtclient: 'RDT-Client',
+  deluge: 'Deluge',
 };
 
 /** Get display name for a client type, falling back to the raw type */
@@ -39,7 +39,7 @@ export const CLIENT_PROTOCOL_MAP: Record<DownloadClientType, ProtocolType> = {
   sabnzbd: 'usenet',
   nzbget: 'usenet',
   transmission: 'torrent',
-  rdtclient: 'torrent',
+  deluge: 'torrent',
 };
 
 /** Unified download status across all clients */
@@ -82,6 +82,8 @@ export interface DownloadInfo {
   category: string;
   /** Filesystem path where download is stored (available after completion) */
   downloadPath?: string;
+  /** Configured save directory (torrent clients only, used for path readiness detection) */
+  savePath?: string;
   /** When the download completed */
   completedAt?: Date;
   /** Error message if download failed */

src/lib/processors/download-torrent.processor.ts

@@ -9,6 +9,7 @@ import { getConfigService } from '../services/config.service';
 import { getDownloadClientManager } from '../services/download-client-manager.service';
 import { ProwlarrService } from '../integrations/prowlarr.service';
 import { RMABLogger } from '../utils/logger';
+import { isTransientConnectionError } from '../utils/connection-errors';
 
 /**
  * Process download job
@@ -121,15 +122,22 @@ export async function processDownloadTorrent(payload: DownloadTorrentPayload): P
   } catch (error) {
     logger.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
 
-    // Update request status to failed
-    await prisma.request.update({
-      where: { id: requestId },
-      data: {
-        status: 'failed',
-        errorMessage: error instanceof Error ? error.message : 'Failed to add download to client',
-        updatedAt: new Date(),
-      },
-    });
+    if (isTransientConnectionError(error)) {
+      // Connection error — don't mark request as failed yet.
+      // Bull will retry this job (3 attempts with exponential backoff).
+      // If all retries are exhausted, the global failed handler marks it failed.
+      logger.warn(`Download client unreachable for request ${requestId}, allowing Bull to retry`);
+    } else {
+      // Permanent error — mark request as failed immediately
+      await prisma.request.update({
+        where: { id: requestId },
+        data: {
+          status: 'failed',
+          errorMessage: error instanceof Error ? error.message : 'Failed to add download to client',
+          updatedAt: new Date(),
+        },
+      });
+    }
 
     throw error;
   }

src/lib/processors/monitor-download.processor.ts

@@ -10,6 +10,7 @@ import { PathMapper, PathMappingConfig } from '../utils/path-mapper';
 import { getConfigService } from '../services/config.service';
 import { getDownloadClientManager } from '../services/download-client-manager.service';
 import { CLIENT_PROTOCOL_MAP, DownloadClientType } from '../interfaces/download-client.interface';
+import { isTransientConnectionError } from '../utils/connection-errors';
 
 /**
  * Process monitor download job
@@ -20,6 +21,12 @@ import { CLIENT_PROTOCOL_MAP, DownloadClientType } from '../interfaces/download-
 const BASE_POLL_INTERVAL = 10;
 /** Maximum polling interval in seconds (5 minutes) */
 const MAX_POLL_INTERVAL = 300;
+/**
+ * Maximum consecutive connection failures before permanently failing the download.
+ * With exponential backoff (10s base, 300s cap), 30 failures spans roughly 30-45 minutes —
+ * enough to survive a Docker restart, service update, or transient network outage.
+ */
+const MAX_CONNECTION_FAILURES = 30;
 
 /**
  * Compute next poll delay with exponential backoff for stalled downloads.
@@ -32,7 +39,8 @@ function getBackoffDelay(stallCount: number): number {
 
 export async function processMonitorDownload(payload: MonitorDownloadPayload): Promise<any> {
   const { requestId, downloadHistoryId, downloadClientId, downloadClient, jobId,
-          lastProgress: prevProgress, stallCount: prevStallCount } = payload;
+          lastProgress: prevProgress, stallCount: prevStallCount, pathWaitCount: prevPathWaitCount,
+          connectionFailureCount: prevConnectionFailures } = payload;
 
   const logger = RMABLogger.forJob(jobId, 'MonitorDownload');
 
@@ -95,6 +103,32 @@ export async function processMonitorDownload(payload: MonitorDownloadPayload): P
         throw new Error('Download path not available from download client');
       }
 
+      // Detect TempPathEnabled race: content_path hasn't been relocated to save_path yet
+      if (info.savePath && downloadPath) {
+        const normalizedSave = info.savePath.endsWith('/') ? info.savePath : info.savePath + '/';
+        if (!downloadPath.startsWith(normalizedSave)) {
+          const waitCount = (prevPathWaitCount ?? 0) + 1;
+          const MAX_PATH_WAIT = 30; // Give up after ~5 minutes
+
+          if (waitCount < MAX_PATH_WAIT) {
+            const delay = Math.min(10, waitCount * 2); // 2s, 4s, 6s... up to 10s
+            logger.info(`Download path still in temp location, waiting for relocation (${waitCount}/${MAX_PATH_WAIT})`, {
+              downloadPath, savePath: info.savePath,
+            });
+
+            const jobQueue = getJobQueueService();
+            await jobQueue.addMonitorJob(
+              requestId, downloadHistoryId, downloadClientId, downloadClient,
+              delay, 100, 0, waitCount
+            );
+
+            return { success: true, completed: false, message: 'Waiting for file relocation', pathWaitCount: waitCount };
+          }
+
+          logger.warn(`Download path still in temp location after ${waitCount} checks, proceeding with organization`);
+        }
+      }
+
       // Get path mapping configuration from the specific download client
       const clientConfig = await manager.getClientForProtocol(protocol);
 
@@ -262,51 +296,99 @@ export async function processMonitorDownload(payload: MonitorDownloadPayload): P
   } catch (error) {
     logger.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
 
-    // Check if this is a transient "not found" error
     const errorMessage = error instanceof Error ? error.message : '';
     const isNotFound = errorMessage.includes('not found');
+    const isConnectionError = isTransientConnectionError(error);
 
     if (isNotFound) {
-      // Transient error - don't mark request as failed, let Bull retry
-      // The request stays in 'downloading' status until Bull exhausts all retries
+      // PATH 1: "Not found" — transient race condition.
+      // Don't mark request as failed; let Bull retry the same job.
       logger.warn(`Transient error for request ${requestId}, allowing Bull to retry`);
-    } else {
-      // Permanent error - mark request as failed immediately
-      const failureMessage = errorMessage || 'Monitor download failed';
-      await prisma.request.update({
-        where: { id: requestId },
-        data: {
-          status: 'failed',
-          errorMessage: failureMessage,
-          updatedAt: new Date(),
-        },
-      });
+      throw error;
+    }
 
-      // Send notification for request failure
-      const request = await prisma.request.findUnique({
-        where: { id: requestId },
-        include: {
-          audiobook: true,
-          user: { select: { plexUsername: true } },
-        },
-      });
+    if (isConnectionError) {
+      // PATH 2: Connection failure — download client is temporarily unreachable.
+      // Instead of failing the download, self-schedule the next poll with backoff.
+      // This reuses the same adaptive backoff as stalled downloads, giving the
+      // client time to recover (restart, network blip, update, etc.).
+      const failureCount = (prevConnectionFailures ?? 0) + 1;
+
+      if (failureCount >= MAX_CONNECTION_FAILURES) {
+        // Exhausted patience — treat as permanent failure
+        logger.error(
+          `Download client unreachable for ${failureCount} consecutive checks, giving up on request ${requestId}`
+        );
+        // Fall through to permanent failure handling below
+      } else {
+        const delay = getBackoffDelay(failureCount);
+        logger.warn(
+          `Download client unreachable (${failureCount}/${MAX_CONNECTION_FAILURES}), ` +
+          `retrying in ${delay}s for request ${requestId}`,
+          { error: errorMessage }
+        );
 
-      if (request) {
         const jobQueue = getJobQueueService();
-        await jobQueue.addNotificationJob(
-          'request_error',
-          request.id,
-          request.audiobook.title,
-          request.audiobook.author,
-          request.user.plexUsername || 'Unknown User',
-          failureMessage
-        ).catch((error) => {
-          logger.error('Failed to queue notification', { error: error instanceof Error ? error.message : String(error) });
-        });
+        await jobQueue.addMonitorJob(
+          requestId,
+          downloadHistoryId,
+          downloadClientId,
+          downloadClient,
+          delay,
+          prevProgress,
+          prevStallCount ?? 0,
+          prevPathWaitCount,
+          failureCount
+        );
+
+        // Return success — the monitoring loop continues via the new job.
+        // Do NOT throw: that would trigger Bull's retry on this job as well.
+        return {
+          success: true,
+          completed: false,
+          message: `Download client unreachable, will retry in ${delay}s`,
+          requestId,
+          connectionFailureCount: failureCount,
+        };
       }
     }
 
-    // Rethrow to trigger Bull's retry mechanism
+    // PATH 3: Permanent error (or connection failures exhausted).
+    // Mark request as failed immediately.
+    const failureMessage = errorMessage || 'Monitor download failed';
+    await prisma.request.update({
+      where: { id: requestId },
+      data: {
+        status: 'failed',
+        errorMessage: failureMessage,
+        updatedAt: new Date(),
+      },
+    });
+
+    // Send notification for request failure
+    const request = await prisma.request.findUnique({
+      where: { id: requestId },
+      include: {
+        audiobook: true,
+        user: { select: { plexUsername: true } },
+      },
+    });
+
+    if (request) {
+      const jobQueue = getJobQueueService();
+      await jobQueue.addNotificationJob(
+        'request_error',
+        request.id,
+        request.audiobook.title,
+        request.audiobook.author,
+        request.user.plexUsername || 'Unknown User',
+        failureMessage
+      ).catch((notifError) => {
+        logger.error('Failed to queue notification', { error: notifError instanceof Error ? notifError.message : String(notifError) });
+      });
+    }
+
+    // Rethrow to trigger Bull's retry mechanism as a safety net
     throw error;
   }
 }

src/lib/processors/organize-files.processor.ts

@@ -11,6 +11,7 @@ import { getLibraryService } from '../services/library';
 import { getConfigService } from '../services/config.service';
 import { getDownloadClientManager } from '../services/download-client-manager.service';
 import { CLIENT_PROTOCOL_MAP, DownloadClientType } from '../interfaces/download-client.interface';
+import { PathMapper, PathMappingConfig } from '../utils/path-mapper';
 import { generateFilesHash } from '../utils/files-hash';
 import { fixEpubForKindle, cleanupFixedEpub } from '../utils/epub-fixer';
 import { removeEmptyParentDirectories } from '../utils/cleanup-helpers';
@@ -21,7 +22,7 @@ import { removeEmptyParentDirectories } from '../utils/cleanup-helpers';
  * Handles both audiobook and ebook request types with appropriate branching
  */
 export async function processOrganizeFiles(payload: OrganizeFilesPayload): Promise<any> {
-  const { requestId, audiobookId, downloadPath, jobId } = payload;
+  const { requestId, audiobookId, downloadPath, jobId, cleanupSource } = payload;
 
   const logger = RMABLogger.forJob(jobId, 'OrganizeFiles');
 
@@ -128,7 +129,19 @@ export async function processOrganizeFiles(payload: OrganizeFilesPayload): Promi
     });
     const template = templateConfig?.value || '{author}/{title} {asin}';
 
-    // Organize files (pass template and logger to file organizer)
+    // Read file rename configuration
+    const fileRenameEnabledConfig = await prisma.configuration.findUnique({
+      where: { key: 'file_rename_enabled' },
+    });
+    const fileRenameTemplateConfig = await prisma.configuration.findUnique({
+      where: { key: 'file_rename_template' },
+    });
+    const renameConfig = {
+      enabled: fileRenameEnabledConfig?.value === 'true',
+      template: fileRenameTemplateConfig?.value || '{title}',
+    };
+
+    // Organize files (pass template, logger, and rename config to file organizer)
     const result = await organizer.organize(
       downloadPath,
       {
@@ -142,7 +155,8 @@ export async function processOrganizeFiles(payload: OrganizeFilesPayload): Promi
         seriesPart: audiobook.seriesPart || undefined,
       },
       template,
-      jobId ? { jobId, context: 'FileOrganizer' } : undefined
+      jobId ? { jobId, context: 'FileOrganizer' } : undefined,
+      renameConfig
     );
 
     if (!result.success) {
@@ -250,6 +264,11 @@ export async function processOrganizeFiles(payload: OrganizeFilesPayload): Promi
     // Cleanup downloads if configured (uses IDownloadClient.postProcess for client-specific cleanup)
     await cleanupDownloadAfterOrganize(requestId, downloadPath, configService, jobId, logger);
 
+    // Cleanup source files if requested (manual import feature)
+    if (cleanupSource) {
+      await cleanupSourceAfterOrganize(downloadPath, configService, jobId, logger);
+    }
+
     return {
       success: true,
       message: 'Files organized successfully',
@@ -296,6 +315,43 @@ export async function processOrganizeFiles(payload: OrganizeFilesPayload): Promi
         // Still have retries left - queue for re-import
         logger.warn(`Retryable error for request ${requestId}, queueing for retry (attempt ${newAttempts}/${currentRequest.maxImportRetries})`);
 
+        // Re-query download client for fresh path (content_path may have been updated since handoff)
+        try {
+          const downloadHistory = await prisma.downloadHistory.findFirst({
+            where: { requestId },
+            orderBy: { createdAt: 'desc' },
+          });
+
+          if (downloadHistory?.downloadClientId && downloadHistory?.downloadClient && downloadHistory.downloadClient !== 'direct') {
+            const configService = getConfigService();
+            const dlManager = getDownloadClientManager(configService);
+            const dlProtocol = CLIENT_PROTOCOL_MAP[downloadHistory.downloadClient as DownloadClientType];
+
+            if (dlProtocol) {
+              const dlClient = await dlManager.getClientServiceForProtocol(dlProtocol);
+              if (dlClient) {
+                const freshInfo = await dlClient.getDownload(downloadHistory.downloadClientId);
+                if (freshInfo?.downloadPath && freshInfo.downloadPath !== downloadPath) {
+                  // Apply path mapping and update stored path
+                  const clientConfig = await dlManager.getClientForProtocol(dlProtocol);
+                  const pathMappingConfig: PathMappingConfig = clientConfig?.remotePathMappingEnabled
+                    ? { enabled: true, remotePath: clientConfig.remotePath || '', localPath: clientConfig.localPath || '' }
+                    : { enabled: false, remotePath: '', localPath: '' };
+                  const freshPath = PathMapper.transform(freshInfo.downloadPath, pathMappingConfig);
+
+                  logger.info(`Download client returned updated path: ${freshPath} (was: ${downloadPath})`);
+                  await prisma.downloadHistory.update({
+                    where: { id: downloadHistory.id },
+                    data: { downloadPath: freshPath },
+                  });
+                }
+              }
+            }
+          }
+        } catch (refreshError) {
+          logger.warn(`Failed to refresh download path: ${refreshError instanceof Error ? refreshError.message : String(refreshError)}`);
+        }
+
         await prisma.request.update({
           where: { id: requestId },
           data: {
@@ -416,7 +472,7 @@ async function processEbookOrganization(
   request: { id: string; userId: string; type: string; user: { plexUsername: string | null } },
   logger: RMABLogger
 ): Promise<any> {
-  const { requestId, audiobookId, downloadPath, jobId } = payload;
+  const { requestId, audiobookId, downloadPath, jobId, cleanupSource } = payload;
 
   logger.info(`Processing ebook organization for request ${requestId}`);
 
@@ -556,6 +612,18 @@ async function processEbookOrganization(
     }
   }
 
+  // Read file rename configuration
+  const fileRenameEnabledConfig = await prisma.configuration.findUnique({
+    where: { key: 'file_rename_enabled' },
+  });
+  const fileRenameTemplateConfig = await prisma.configuration.findUnique({
+    where: { key: 'file_rename_template' },
+  });
+  const ebookRenameConfig = {
+    enabled: fileRenameEnabledConfig?.value === 'true',
+    template: fileRenameTemplateConfig?.value || '{title}',
+  };
+
   // Organize ebook files (organizer will detect ebook type and skip audio-specific processing)
   // Pass all metadata that could be used in path templates (same as audiobooks)
   const result = await organizer.organizeEbook(
@@ -571,7 +639,8 @@ async function processEbookOrganization(
     },
     template,
     jobId ? { jobId, context: 'FileOrganizer.Ebook' } : undefined,
-    isIndexerDownload
+    isIndexerDownload,
+    ebookRenameConfig
   );
 
   // Clean up fixed EPUB temp file after organization (regardless of success)
@@ -662,6 +731,11 @@ async function processEbookOrganization(
   // Cleanup downloads if configured (uses IDownloadClient.postProcess for client-specific cleanup)
   await cleanupDownloadAfterOrganize(requestId, downloadPath, configService, jobId, logger);
 
+  // Cleanup source files if requested (manual import feature)
+  if (cleanupSource) {
+    await cleanupSourceAfterOrganize(downloadPath, configService, jobId, logger);
+  }
+
   return {
     success: true,
     message: 'Ebook organized successfully',
@@ -865,12 +939,9 @@ async function cleanupDownloadAfterOrganize(
     });
 
     // Check if this is a non-torrent indexer with cleanup enabled.
-    // RDT-Client is an exception: even though it's torrent protocol, it needs cleanup
-    // because Real-Debrid handles seeding — local torrent entries should be removed.
-    const isRDTClient = downloadHistory.downloadClient === 'rdtclient';
     const isTorrentProtocol = indexer?.protocol?.toLowerCase() === 'torrent';
 
-    if (!indexer || (!isRDTClient && isTorrentProtocol) || !indexer.removeAfterProcessing) {
+    if (!indexer || isTorrentProtocol || !indexer.removeAfterProcessing) {
       return;
     }
 
@@ -942,6 +1013,68 @@ async function cleanupDownloadAfterOrganize(
   }
 }
 
+// =========================================================================
+// SOURCE FILE CLEANUP (MANUAL IMPORT)
+// =========================================================================
+
+/**
+ * Delete source files after successful manual import.
+ * Non-fatal: logs a warning on failure but does not fail the job.
+ * Files are already safely copied to the media library at this point.
+ */
+async function cleanupSourceAfterOrganize(
+  downloadPath: string,
+  configService: any,
+  jobId: string | undefined,
+  logger: RMABLogger
+): Promise<void> {
+  try {
+    const fs = await import('fs/promises');
+
+    logger.info(`Cleaning up source files: ${downloadPath}`);
+
+    const stats = await fs.stat(downloadPath);
+    if (stats.isDirectory()) {
+      await fs.rm(downloadPath, { recursive: true, force: true });
+      logger.info(`Removed source directory: ${downloadPath}`);
+    } else {
+      await fs.unlink(downloadPath);
+      logger.info(`Removed source file: ${downloadPath}`);
+    }
+
+    // Determine boundary path based on download path prefix
+    const BOOKDROP_PATH = '/bookdrop';
+    const downloadDir = await configService.get('download_dir') || '/downloads';
+    const mediaDir = await configService.get('media_dir') || '/media';
+
+    let boundaryPath = downloadDir;
+    if (downloadPath.startsWith(BOOKDROP_PATH)) {
+      boundaryPath = BOOKDROP_PATH;
+    } else if (downloadPath.startsWith(mediaDir)) {
+      boundaryPath = mediaDir;
+    }
+
+    const cleanupResult = await removeEmptyParentDirectories(downloadPath, {
+      boundaryPath,
+      logContext: jobId ? { jobId, context: 'CleanupSourceParents' } : undefined,
+    });
+
+    if (cleanupResult.removedDirectories.length > 0) {
+      logger.info(`Cleaned up ${cleanupResult.removedDirectories.length} empty parent directories`);
+    }
+  } catch (error) {
+    // Non-fatal - files are already safely in the media library
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      logger.info(`Source path already deleted: ${downloadPath}`);
+    } else {
+      logger.warn(
+        `Failed to cleanup source files: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        { error: error instanceof Error ? error.stack : undefined }
+      );
+    }
+  }
+}
+
 // =========================================================================
 // HELPER FUNCTIONS
 // =========================================================================

src/lib/processors/search-indexers.processor.ts

@@ -34,6 +34,13 @@ export async function processSearchIndexers(payload: SearchIndexersPayload): Pro
       },
     });
 
+    // Check for custom search terms override
+    const requestRecord = await prisma.request.findUnique({
+      where: { id: requestId },
+      select: { customSearchTerms: true },
+    });
+    const effectiveSearchTitle = requestRecord?.customSearchTerms || audiobook.title;
+
     // Get enabled indexers from configuration
     const { getConfigService } = await import('../services/config.service');
     const configService = getConfigService();
@@ -77,7 +84,11 @@ export async function processSearchIndexers(payload: SearchIndexersPayload): Pro
     // Get Prowlarr service
     const prowlarr = await getProwlarrService();
 
-    logger.info(`Searching for: "${audiobook.title}" by "${audiobook.author}"`);
+    if (requestRecord?.customSearchTerms) {
+      logger.info(`Searching with custom terms: "${effectiveSearchTitle}" (original: "${audiobook.title}") by "${audiobook.author}"`);
+    } else {
+      logger.info(`Searching for: "${audiobook.title}" by "${audiobook.author}"`);
+    }
 
     // Search Prowlarr for each group and combine results
     const allResults = [];
@@ -87,7 +98,7 @@ export async function processSearchIndexers(payload: SearchIndexersPayload): Pro
       logger.info(`Searching group ${i + 1}/${groups.length}: ${getGroupDescription(group)}`);
 
       try {
-        const groupResults = await prowlarr.searchWithVariations(audiobook.title, audiobook.author, {
+        const groupResults = await prowlarr.searchWithVariations(effectiveSearchTitle, audiobook.author, {
           categories: group.categories,
           indexerIds: group.indexerIds,
           minSeeders: 1, // Only torrents with at least 1 seeder

src/lib/services/download-client-manager.service.ts

@@ -2,7 +2,7 @@
  * Component: Download Client Manager Service
  * Documentation: documentation/phase3/download-clients.md
  *
- * Manages multiple download clients (qBittorrent, Transmission, SABnzbd, NZBGet) with protocol-based routing.
+ * Manages multiple download clients (qBittorrent, Transmission, Deluge, SABnzbd, NZBGet) with protocol-based routing.
  * Supports migration from legacy single-client config to multi-client JSON array format.
  */
 
@@ -16,7 +16,7 @@ import { QBittorrentService } from '@/lib/integrations/qbittorrent.service';
 import { SABnzbdService } from '@/lib/integrations/sabnzbd.service';
 import { NZBGetService } from '@/lib/integrations/nzbget.service';
 import { TransmissionService } from '@/lib/integrations/transmission.service';
-import { RDTClientService } from '@/lib/integrations/rdtclient.service';
+import { DelugeService } from '@/lib/integrations/deluge.service';
 import { PathMappingConfig } from '@/lib/utils/path-mapper';
 import { IDownloadClient, DownloadClientType, ProtocolType, CLIENT_PROTOCOL_MAP, getClientDisplayName } from '@/lib/interfaces/download-client.interface';
 
@@ -194,8 +194,8 @@ export class DownloadClientManager {
         return this.createNZBGetService(config, downloadDir);
       case 'transmission':
         return this.createTransmissionService(config, downloadDir);
-      case 'rdtclient':
-        return this.createRDTClientService(config, downloadDir);
+      case 'deluge':
+        return this.createDelugeService(config, downloadDir);
       default:
         throw new Error(`Unsupported download client type: ${config.type}`);
     }
@@ -339,9 +339,9 @@ export class DownloadClientManager {
   }
 
   /**
-   * Create RDT-Client service instance (same constructor as qBittorrent — identical API)
+   * Create Deluge service instance
    */
-  private createRDTClientService(config: DownloadClientConfig, downloadDir: string): RDTClientService {
+  private createDelugeService(config: DownloadClientConfig, downloadDir: string): DelugeService {
     const pathMapping: PathMappingConfig | undefined = config.remotePathMappingEnabled && config.remotePath && config.localPath
       ? {
           enabled: true,
@@ -350,7 +350,7 @@ export class DownloadClientManager {
         }
       : undefined;
 
-    return new RDTClientService(
+    return new DelugeService(
       config.url,
       config.username || '',
       config.password || '',

src/lib/services/job-queue.service.ts

@@ -65,6 +65,8 @@ export interface MonitorDownloadPayload extends JobPayload {
   downloadClient: DownloadClientType;
   lastProgress?: number;  // Previous poll's progress (0-100) for stall detection
   stallCount?: number;    // Consecutive polls with no progress change (drives backoff)
+  pathWaitCount?: number; // Consecutive polls waiting for content_path to relocate to save_path
+  connectionFailureCount?: number; // Consecutive polls where the download client was unreachable
 }
 
 export interface OrganizeFilesPayload extends JobPayload {
@@ -72,6 +74,7 @@ export interface OrganizeFilesPayload extends JobPayload {
   audiobookId: string;
   downloadPath: string;
   targetPath?: string; // Optional - not used by processor (reads from database config)
+  cleanupSource?: boolean; // If true, delete source files after successful import
 }
 
 export interface ScanPlexPayload extends JobPayload {
@@ -258,6 +261,29 @@ export class JobQueueService {
           logger.error('Failed to update request/download status', { error: updateError instanceof Error ? updateError.message : String(updateError) });
         }
       }
+
+      // Safety net for download_torrent: if the processor skipped marking the
+      // request as failed (e.g. connection error with Bull retries), ensure the
+      // request is marked failed after all retries are exhausted.
+      if (job.name === 'download_torrent' && job.data) {
+        const payload = job.data as DownloadTorrentPayload;
+        logger.error(`DownloadTorrent job permanently failed for request ${payload.requestId} after ${job.attemptsMade} attempts`);
+
+        try {
+          await prisma.request.update({
+            where: { id: payload.requestId },
+            data: {
+              status: 'failed',
+              errorMessage: error.message || 'Failed to add download after multiple retries',
+              updatedAt: new Date(),
+            },
+          });
+        } catch (updateError) {
+          logger.error('Failed to update request status after download_torrent failure', {
+            error: updateError instanceof Error ? updateError.message : String(updateError),
+          });
+        }
+      }
     });
 
     this.queue.on('stalled', async (job: BullJob) => {
@@ -567,7 +593,9 @@ export class JobQueueService {
     downloadClient: DownloadClientType,
     delaySeconds: number = 0,
     lastProgress?: number,
-    stallCount?: number
+    stallCount?: number,
+    pathWaitCount?: number,
+    connectionFailureCount?: number
   ): Promise<string> {
     return await this.addJob(
       'monitor_download',
@@ -578,6 +606,8 @@ export class JobQueueService {
         downloadClient,
         lastProgress,
         stallCount,
+        pathWaitCount,
+        connectionFailureCount,
       } as MonitorDownloadPayload,
       {
         priority: 5, // Medium priority
@@ -594,7 +624,8 @@ export class JobQueueService {
     requestId: string,
     audiobookId: string,
     downloadPath: string,
-    targetPath?: string
+    targetPath?: string,
+    cleanupSource?: boolean
   ): Promise<string> {
     return await this.addJob(
       'organize_files',
@@ -603,6 +634,7 @@ export class JobQueueService {
         audiobookId,
         downloadPath,
         targetPath, // Not used by processor
+        cleanupSource,
       } as OrganizeFilesPayload,
       {
         priority: 8,

src/lib/services/notification/providers/apprise.provider.ts

@@ -45,13 +45,31 @@ export class AppriseProvider implements INotificationProvider {
     const meta = getEventMeta(payload.event);
     const { title, body } = this.formatMessage(payload);
 
-    const serverUrl = appriseConfig.serverUrl.replace(/\/+$/, '');
-    const notificationType = SEVERITY_TYPES[meta.severity];
-
+    // Parse URL to extract embedded HTTP Basic Auth credentials (e.g. https://user:pass@host/)
+    let serverUrl: string;
     const headers: Record<string, string> = {
       'Content-Type': 'application/json',
     };
 
+    try {
+      const parsed = new URL(appriseConfig.serverUrl);
+      if (parsed.username) {
+        const username = decodeURIComponent(parsed.username);
+        const password = decodeURIComponent(parsed.password);
+        headers['Authorization'] = `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+        parsed.username = '';
+        parsed.password = '';
+        serverUrl = parsed.toString().replace(/\/+$/, '');
+      } else {
+        serverUrl = appriseConfig.serverUrl.replace(/\/+$/, '');
+      }
+    } catch {
+      serverUrl = appriseConfig.serverUrl.replace(/\/+$/, '');
+    }
+
+    const notificationType = SEVERITY_TYPES[meta.severity];
+
+    // Explicit authToken (Bearer) takes precedence over URL-embedded credentials
     if (appriseConfig.authToken) {
       headers['Authorization'] = `Bearer ${appriseConfig.authToken}`;
     }

src/lib/types/audible.ts

@@ -5,7 +5,7 @@
 
 import type { SupportedLanguage } from '../constants/language-config';
 
-export type AudibleRegion = 'us' | 'ca' | 'uk' | 'au' | 'in' | 'de' | 'es';
+export type AudibleRegion = 'us' | 'ca' | 'uk' | 'au' | 'in' | 'de' | 'es' | 'fr';
 
 export interface AudibleRegionConfig {
   code: AudibleRegion;
@@ -64,6 +64,13 @@ export const AUDIBLE_REGIONS: Record<AudibleRegion, AudibleRegionConfig> = {
     baseUrl: 'https://www.audible.es',
     audnexusParam: 'es',
     language: 'es',
+  },
+  fr: {
+    code: 'fr',
+    name: 'France',
+    baseUrl: 'https://www.audible.fr',
+    audnexusParam: 'fr',
+    language: 'fr',
   }
 };
 

src/lib/utils/connection-errors.ts

@@ -0,0 +1,80 @@
+/**
+ * Component: Connection Error Classification Utility
+ * Documentation: documentation/phase3/README.md
+ *
+ * Classifies errors as transient connection failures (e.g. download client
+ * restarting, network blip) vs permanent failures.  Used by download
+ * processors to decide whether to retry with backoff or fail immediately.
+ */
+
+/** Node/Axios error codes that indicate the remote service is temporarily unreachable. */
+const TRANSIENT_ERROR_CODES = new Set([
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'ECONNABORTED',
+  'ETIMEDOUT',
+  'ENOTFOUND',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'EPIPE',
+  'EAI_AGAIN',
+]);
+
+/** HTTP status codes that indicate a gateway / upstream service issue. */
+const TRANSIENT_HTTP_STATUSES = new Set([502, 503, 504]);
+
+/**
+ * Substrings in error messages that strongly indicate a connection-level
+ * failure.  Checked as a fallback when structured error properties are
+ * unavailable (e.g. errors re-thrown as plain Error with a message string).
+ */
+const TRANSIENT_MESSAGE_PATTERNS = [
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'ECONNABORTED',
+  'ETIMEDOUT',
+  'ENOTFOUND',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'EPIPE',
+  'EAI_AGAIN',
+  'connect ECONNREFUSED',
+  'socket hang up',
+  'network error',
+  'Client network socket disconnected',
+] as const;
+
+/**
+ * Returns `true` when the error looks like a transient connection failure
+ * rather than a permanent / logical error.
+ *
+ * Checks (in order):
+ *  1. `error.code`  — Node.js / Axios error codes
+ *  2. `error.response.status` — HTTP gateway errors (502/503/504)
+ *  3. `error.message` — fallback substring matching
+ */
+export function isTransientConnectionError(error: unknown): boolean {
+  if (!error) return false;
+
+  // 1. Structured error code (Node.js / Axios)
+  const code = (error as any)?.code;
+  if (typeof code === 'string' && TRANSIENT_ERROR_CODES.has(code)) {
+    return true;
+  }
+
+  // 2. HTTP gateway status from Axios response
+  const status = (error as any)?.response?.status;
+  if (typeof status === 'number' && TRANSIENT_HTTP_STATUSES.has(status)) {
+    return true;
+  }
+
+  // 3. Fallback: substring match on the error message
+  const message = (error instanceof Error ? error.message : String(error)).toUpperCase();
+  for (const pattern of TRANSIENT_MESSAGE_PATTERNS) {
+    if (message.includes(pattern.toUpperCase())) {
+      return true;
+    }
+  }
+
+  return false;
+}

src/lib/utils/file-organizer.ts

@@ -20,7 +20,7 @@ import {
   checkDiskSpace,
 } from './chapter-merger';
 import { prisma } from '../db';
-import { substituteTemplate, type TemplateVariables } from './path-template.util';
+import { substituteTemplate, buildRenamedFilename, type TemplateVariables } from './path-template.util';
 import { AUDIO_EXTENSIONS } from '../constants/audio-formats';
 
 export interface AudiobookMetadata {
@@ -77,7 +77,8 @@ export class FileOrganizer {
     downloadPath: string,
     audiobook: AudiobookMetadata,
     template: string,
-    loggerConfig?: LoggerConfig
+    loggerConfig?: LoggerConfig,
+    renameConfig?: { enabled: boolean; template: string }
   ): Promise<OrganizationResult> {
     // Create logger if config provided
     const logger = loggerConfig ? RMABLogger.forJob(loggerConfig.jobId, loggerConfig.context) : null;
@@ -294,8 +295,21 @@ export class FileOrganizer {
       // Create target directory
       await fs.mkdir(targetPath, { recursive: true });
 
+      // Determine if file renaming should be applied
+      const shouldRename = renameConfig?.enabled && renameConfig.template;
+      const isMultiFile = audioFiles.length > 1;
+      const duplicateBasenames = this.findDuplicateBasenames(audioFiles);
+      const usedTargetFilenames = new Set<string>();
+
+      if (shouldRename) {
+        await logger?.info(`File renaming enabled with template: ${renameConfig.template}${isMultiFile ? ` (${audioFiles.length} files, indices will be appended)` : ''}`);
+      } else if (duplicateBasenames.size > 0) {
+        await logger?.info(`Detected ${duplicateBasenames.size} duplicate source filename(s); applying folder-aware naming to avoid collisions`);
+      }
+
       // Copy audio files (do NOT delete originals - needed for seeding)
-      for (const audioFile of audioFiles) {
+      for (let i = 0; i < audioFiles.length; i++) {
+        const audioFile = audioFiles[i];
         // Handle merged files (absolute paths) vs original files (relative paths)
         const isAbsolutePath = path.isAbsolute(audioFile);
         const originalSourcePath = isAbsolutePath
@@ -303,7 +317,35 @@ export class FileOrganizer {
           : isFile
             ? downloadPath
             : path.join(downloadPath, audioFile);
-        const filename = path.basename(audioFile);
+
+        // Determine target filename (apply rename template if enabled)
+        let filename: string;
+        if (shouldRename) {
+          const ext = path.extname(audioFile);
+          const variables: TemplateVariables = {
+            author: audiobook.author,
+            title: audiobook.title,
+            narrator: audiobook.narrator,
+            asin: audiobook.asin,
+            year: audiobook.year,
+            series: audiobook.series,
+            seriesPart: audiobook.seriesPart,
+          };
+          filename = buildRenamedFilename(
+            renameConfig.template,
+            variables,
+            ext,
+            isMultiFile ? i + 1 : undefined,
+          );
+          filename = this.makeUniqueFilename(filename, usedTargetFilenames);
+        } else {
+          filename = this.buildSourceAwareFilename(
+            audioFile,
+            duplicateBasenames,
+            usedTargetFilenames
+          );
+        }
+
         const targetFilePath = path.join(targetPath, filename);
 
         // Check if we have a tagged version of this file
@@ -595,6 +637,72 @@ export class FileOrganizer {
     );
   }
 
+  private findDuplicateBasenames(files: string[]): Set<string> {
+    const counts = new Map<string, number>();
+
+    for (const file of files) {
+      const basename = path.basename(file);
+      counts.set(basename, (counts.get(basename) || 0) + 1);
+    }
+
+    return new Set(
+      Array.from(counts.entries())
+        .filter(([, count]) => count > 1)
+        .map(([basename]) => basename)
+    );
+  }
+
+  private buildSourceAwareFilename(
+    sourcePath: string,
+    duplicateBasenames: Set<string>,
+    usedFilenames: Set<string>
+  ): string {
+    const basename = path.basename(sourcePath);
+    const ext = path.extname(basename);
+    const stem = path.basename(basename, ext);
+
+    let candidate = basename;
+
+    // Preserve folder context for duplicate track names (e.g. CD1/Track01.mp3,
+    // CD2/Track01.mp3) so each file keeps a unique target name.
+    if (duplicateBasenames.has(basename) && !path.isAbsolute(sourcePath)) {
+      const folder = path.dirname(sourcePath);
+      if (folder !== '.') {
+        const folderPrefix = folder
+          .split(path.sep)
+          .filter(Boolean)
+          .map((segment) => this.sanitizePath(segment))
+          .join('-');
+
+        if (folderPrefix) {
+          candidate = `${folderPrefix}-${stem}${ext}`;
+        }
+      }
+    }
+
+    return this.makeUniqueFilename(candidate, usedFilenames);
+  }
+
+  private makeUniqueFilename(filename: string, usedFilenames: Set<string>): string {
+    if (!usedFilenames.has(filename)) {
+      usedFilenames.add(filename);
+      return filename;
+    }
+
+    const ext = path.extname(filename);
+    const stem = path.basename(filename, ext);
+    let suffix = 2;
+
+    while (true) {
+      const candidate = `${stem} (${suffix})${ext}`;
+      if (!usedFilenames.has(candidate)) {
+        usedFilenames.add(candidate);
+        return candidate;
+      }
+      suffix++;
+    }
+  }
+
   /**
    * Download cover art from URL or copy from local cache
    */
@@ -690,7 +798,8 @@ export class FileOrganizer {
     metadata: { title: string; author: string; narrator?: string; asin?: string; year?: number; series?: string; seriesPart?: string },
     template: string,
     loggerConfig?: LoggerConfig,
-    isIndexerDownload: boolean = false
+    isIndexerDownload: boolean = false,
+    renameConfig?: { enabled: boolean; template: string }
   ): Promise<EbookOrganizationResult> {
     const logger = loggerConfig ? RMABLogger.forJob(loggerConfig.jobId, loggerConfig.context) : null;
 
@@ -739,9 +848,25 @@ export class FileOrganizer {
       // Create target directory
       await fs.mkdir(targetDir, { recursive: true });
 
-      // Build target filename (sanitize source filename)
+      // Build target filename (apply rename template if enabled, otherwise sanitize source filename)
       const sourceFilename = path.basename(ebookFile);
-      const targetFilename = this.sanitizePath(sourceFilename);
+      let targetFilename: string;
+      if (renameConfig?.enabled && renameConfig.template) {
+        const originalExt = path.extname(ebookFile);
+        const variables: TemplateVariables = {
+          author: metadata.author,
+          title: metadata.title,
+          narrator: metadata.narrator,
+          asin: metadata.asin,
+          year: metadata.year,
+          series: metadata.series,
+          seriesPart: metadata.seriesPart,
+        };
+        targetFilename = buildRenamedFilename(renameConfig.template, variables, originalExt);
+        await logger?.info(`Renamed ebook file: ${sourceFilename} -> ${targetFilename}`);
+      } else {
+        targetFilename = this.sanitizePath(sourceFilename);
+      }
       const targetPath = path.join(targetDir, targetFilename);
 
       // Check if target already exists

src/lib/utils/jwt.ts

@@ -10,6 +10,7 @@ const logger = RMABLogger.create('JWT');
 
 const JWT_SECRET = process.env.JWT_SECRET || 'change-this-to-a-random-secret-key';
 const JWT_REFRESH_SECRET = process.env.JWT_REFRESH_SECRET || 'change-this-to-another-random-secret-key';
+const JWT_DOWNLOAD_SECRET = process.env.JWT_DOWNLOAD_SECRET || JWT_SECRET + '-download';
 
 const ACCESS_TOKEN_EXPIRY = '1h'; // 1 hour
 const REFRESH_TOKEN_EXPIRY = '7d'; // 7 days
@@ -78,6 +79,35 @@ export function verifyRefreshToken(token: string): RefreshTokenPayload | null {
   }
 }
 
+const DOWNLOAD_TOKEN_EXPIRY = '30d';
+
+export interface DownloadTokenPayload {
+  sub: string; // userId
+  requestId: string;
+  type: 'download';
+}
+
+/**
+ * Generate download token (30-day, stateless, URL-embeddable)
+ */
+export function generateDownloadToken(userId: string, requestId: string): string {
+  const payload: DownloadTokenPayload = { sub: userId, requestId, type: 'download' };
+  return jwt.sign(payload, JWT_DOWNLOAD_SECRET, { expiresIn: DOWNLOAD_TOKEN_EXPIRY });
+}
+
+/**
+ * Verify download token
+ */
+export function verifyDownloadToken(token: string): DownloadTokenPayload | null {
+  try {
+    const decoded = jwt.verify(token, JWT_DOWNLOAD_SECRET) as DownloadTokenPayload;
+    if (decoded.type !== 'download') return null;
+    return decoded;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Decode token without verification (for debugging)
  */

src/lib/utils/path-template.util.ts

@@ -68,6 +68,81 @@ function sanitizePath(name: string): string {
   );
 }
 
+/**
+ * Find valid template variable names within arbitrary content text.
+ * Sorts by length descending to prevent substring false matches
+ * (e.g., 'seriesPart' matched before 'series').
+ * Uses word-boundary detection to avoid matching variable names
+ * that are substrings of other words.
+ */
+function findVariablesInContent(content: string): string[] {
+  const sortedVars = [...VALID_VARIABLES].sort((a, b) => b.length - a.length);
+  const found: string[] = [];
+
+  for (const varName of sortedVars) {
+    const regex = new RegExp(`(?<![a-zA-Z0-9])${varName}(?![a-zA-Z0-9])`);
+    if (regex.test(content)) {
+      found.push(varName);
+    }
+  }
+
+  return found;
+}
+
+/**
+ * Resolve conditional blocks in the template.
+ * A conditional block is {literal text varName more text} where the entire
+ * content is rendered only if ALL variables inside have non-empty values.
+ * If any variable is empty/missing, the entire block is removed.
+ *
+ * Simple variable references like {author} are left untouched for the
+ * existing substitution logic to handle.
+ *
+ * Must run after escaped-brace replacement and before simple variable substitution.
+ */
+function resolveConditionalBlocks(
+  template: string,
+  variables: TemplateVariables
+): string {
+  return template.replace(/\{([^}]+)\}/g, (match, content: string) => {
+    // If content is exactly a valid variable name, skip (leave for simple substitution)
+    if (VALID_VARIABLES.includes(content)) {
+      return match;
+    }
+
+    // Find variables in the content
+    const foundVars = findVariablesInContent(content);
+
+    // If no variables found, leave as-is (validation will catch it)
+    if (foundVars.length === 0) {
+      return match;
+    }
+
+    // Check if all found variables have non-empty values
+    const allPresent = foundVars.every(varName => {
+      const value = variables[varName as keyof TemplateVariables];
+      return value !== undefined && value !== null && String(value).trim() !== '';
+    });
+
+    if (!allPresent) {
+      return '';
+    }
+
+    // Substitute variables within the content, output rest as literal text
+    // Sort by length descending to prevent substring false matches
+    let result = content;
+    const sortedVars = [...foundVars].sort((a, b) => b.length - a.length);
+    for (const varName of sortedVars) {
+      const value = variables[varName as keyof TemplateVariables];
+      const sanitizedValue = sanitizePath(String(value).trim());
+      const regex = new RegExp(`(?<![a-zA-Z0-9])${varName}(?![a-zA-Z0-9])`, 'g');
+      result = result.replace(regex, sanitizedValue);
+    }
+
+    return result;
+  });
+}
+
 /**
  * Substitute template variables with actual values
  *
@@ -99,6 +174,9 @@ export function substituteTemplate(
   // so they survive the variable substitution and path cleanup steps
   result = result.replace(/\\\{/g, LBRACE_PLACEHOLDER).replace(/\\\}/g, RBRACE_PLACEHOLDER);
 
+  // Resolve conditional blocks before simple variable substitution
+  result = resolveConditionalBlocks(result, variables);
+
   // Substitute each variable
   for (const key of VALID_VARIABLES) {
     const value = variables[key as keyof TemplateVariables];
@@ -187,21 +265,47 @@ export function validateTemplate(template: string): ValidationResult {
 
   if (variableMatches) {
     for (const match of variableMatches) {
-      const varName = match.slice(1, -1); // Remove { and }
+      const content = match.slice(1, -1); // Remove { and }
 
-      if (!VALID_VARIABLES.includes(varName)) {
+      // Simple variable — exact match to a valid variable name
+      if (VALID_VARIABLES.includes(content)) {
+        continue;
+      }
+
+      // Conditional block — must contain at least one valid variable
+      const foundVars = findVariablesInContent(content);
+      if (foundVars.length === 0) {
         return {
           valid: false,
-          error: `Unknown variable: {${varName}}. Valid variables are: ${VALID_VARIABLES.map(v => `{${v}}`).join(', ')}`
+          error: `No valid variable found in conditional block: {${content}}. Valid variables are: ${VALID_VARIABLES.map(v => `{${v}}`).join(', ')}`
+        };
+      }
+
+      // Check literal text inside conditional block for invalid path chars
+      let literalText = content;
+      const sortedVars = [...foundVars].sort((a, b) => b.length - a.length);
+      for (const varName of sortedVars) {
+        literalText = literalText.replace(
+          new RegExp(`(?<![a-zA-Z0-9])${varName}(?![a-zA-Z0-9])`, 'g'),
+          ''
+        );
+      }
+      const invalidCharsInBlock = literalText.match(INVALID_PATH_CHARS);
+      if (invalidCharsInBlock) {
+        return {
+          valid: false,
+          error: `Invalid characters found: ${[...new Set(invalidCharsInBlock)].join(', ')}. These characters are not allowed in path templates.`
         };
       }
     }
   }
 
-  // Remove valid variables temporarily to check for invalid characters
+  // Remove valid variables and conditional blocks to check remaining text for invalid chars
   let templateWithoutVars = templateWithoutEscapedBraces;
-  for (const varName of VALID_VARIABLES) {
-    templateWithoutVars = templateWithoutVars.replace(new RegExp(`\\{${varName}\\}`, 'g'), '');
+  if (variableMatches) {
+    for (const match of variableMatches) {
+      templateWithoutVars = templateWithoutVars.replace(match, '');
+    }
   }
 
   // Check for invalid characters outside of variables
@@ -286,3 +390,192 @@ export function generateMockPreviews(template: string): string[] {
 export function getValidVariables(): string[] {
   return [...VALID_VARIABLES];
 }
+
+/**
+ * Validate a filename template string
+ *
+ * Similar to validateTemplate but for filenames (not paths):
+ * - Disallows forward slashes (no directory separators in filenames)
+ * - Does not require relative path structure
+ * - Must contain at least one variable
+ *
+ * @param template - Filename template string to validate
+ * @returns Validation result with error message if invalid
+ */
+export function validateFilenameTemplate(template: string): ValidationResult {
+  if (!template || template.trim().length === 0) {
+    return {
+      valid: false,
+      error: 'Filename template cannot be empty',
+    };
+  }
+
+  // Disallow forward slashes — filenames cannot contain directory separators
+  if (template.includes('/')) {
+    return {
+      valid: false,
+      error: 'Filename template cannot contain "/" (directory separators). Use the organization template for directory structure.',
+    };
+  }
+
+  // Disallow backslashes that aren't brace escapes
+  if (/\\(?![{}])/.test(template)) {
+    return {
+      valid: false,
+      error: 'Filename template cannot contain backslashes. Use the organization template for directory structure.',
+    };
+  }
+
+  // Strip escaped braces before parsing
+  const templateWithoutEscapedBraces = template.replace(/\\[{}]/g, '');
+
+  // Extract all variables from the stripped template
+  const variableMatches = templateWithoutEscapedBraces.match(/\{[^}]+\}/g);
+
+  if (variableMatches) {
+    for (const match of variableMatches) {
+      const content = match.slice(1, -1);
+
+      // Simple variable
+      if (VALID_VARIABLES.includes(content)) {
+        continue;
+      }
+
+      // Conditional block — must contain at least one valid variable
+      const foundVars = findVariablesInContent(content);
+      if (foundVars.length === 0) {
+        return {
+          valid: false,
+          error: `No valid variable found in: {${content}}. Valid variables are: ${VALID_VARIABLES.map(v => `{${v}}`).join(', ')}`,
+        };
+      }
+
+      // Check literal text inside conditional block for invalid filename chars
+      let literalText = content;
+      const sortedVars = [...foundVars].sort((a, b) => b.length - a.length);
+      for (const varName of sortedVars) {
+        literalText = literalText.replace(
+          new RegExp(`(?<![a-zA-Z0-9])${varName}(?![a-zA-Z0-9])`, 'g'),
+          ''
+        );
+      }
+      const invalidCharsInBlock = literalText.match(INVALID_PATH_CHARS);
+      if (invalidCharsInBlock) {
+        return {
+          valid: false,
+          error: `Invalid characters found: ${[...new Set(invalidCharsInBlock)].join(', ')}. These characters are not allowed in filenames.`,
+        };
+      }
+    }
+  }
+
+  // Remove valid variables and conditional blocks to check remaining text
+  let templateWithoutVars = templateWithoutEscapedBraces;
+  if (variableMatches) {
+    for (const match of variableMatches) {
+      templateWithoutVars = templateWithoutVars.replace(match, '');
+    }
+  }
+
+  // Check for invalid characters outside of variables
+  const invalidChars = templateWithoutVars.match(INVALID_PATH_CHARS);
+  if (invalidChars) {
+    return {
+      valid: false,
+      error: `Invalid characters found: ${[...new Set(invalidChars)].join(', ')}. These characters are not allowed in filenames.`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Generate mock filename previews using sample audiobook data
+ *
+ * Creates example filenames with extensions to demonstrate how the template will look.
+ * Shows both single-file and multi-file (with index) examples.
+ *
+ * @param template - Filename template string
+ * @returns Object with single and multi-file preview arrays
+ */
+export function generateMockFilenamePreviews(template: string): {
+  single: string[];
+  multi: string[];
+} {
+  const mockData: TemplateVariables[] = [
+    {
+      author: 'Brandon Sanderson',
+      title: 'Mistborn: The Final Empire',
+      narrator: 'Michael Kramer',
+      asin: 'B002UZMLXM',
+      year: 2006,
+      series: 'The Mistborn Saga',
+      seriesPart: '1',
+    },
+    {
+      author: 'Douglas Adams',
+      title: "The Hitchhiker's Guide to the Galaxy",
+      narrator: 'Stephen Fry',
+      asin: 'B0009JKV9W',
+      year: 2005,
+      series: "Hitchhiker's Guide",
+      seriesPart: '1',
+    },
+  ];
+
+  const single = mockData.map((variables) => {
+    const name = substituteTemplate(template, variables);
+    return `${name}.m4b`;
+  });
+
+  // Show multi-file example with first mock data only
+  const multiName = substituteTemplate(template, mockData[0]);
+  const multi = [
+    `${multiName} - 1.mp3`,
+    `${multiName} - 2.mp3`,
+    `${multiName} - 3.mp3`,
+  ];
+
+  return { single, multi };
+}
+
+/**
+ * Build a renamed filename from a template, metadata variables, and original extension.
+ * Optionally appends a 1-based index for multi-file scenarios.
+ *
+ * @param template - Filename template string (e.g., "{title}")
+ * @param variables - Template variables with metadata values
+ * @param originalExtension - File extension including dot (e.g., ".m4b")
+ * @param index - Optional 1-based index for multi-file scenarios
+ * @returns Sanitized filename with extension
+ */
+export function buildRenamedFilename(
+  template: string,
+  variables: TemplateVariables,
+  originalExtension: string,
+  index?: number,
+): string {
+  let baseName = substituteTemplate(template, variables);
+
+  // substituteTemplate cleans up slashes for paths — but since this is a filename,
+  // remove any residual slashes that conditional blocks might have introduced
+  baseName = baseName.replace(/[/\\]/g, '');
+
+  // Sanitize again for filename safety
+  baseName = baseName
+    .replace(/[<>:"/\\|?*]/g, '')
+    .trim()
+    .replace(/^\.+/, '')
+    .replace(/\.+$/, '')
+    .replace(/\s+/g, ' ')
+    .slice(0, 200);
+
+  if (index !== undefined) {
+    baseName = `${baseName} - ${index}`;
+  }
+
+  // Ensure extension starts with a dot
+  const ext = originalExtension.startsWith('.') ? originalExtension : `.${originalExtension}`;
+
+  return `${baseName}${ext}`;
+}

src/lib/utils/permissions.ts

@@ -55,3 +55,16 @@ export async function resolveInteractiveSearchAccess(
   if (userInteractiveSearchAccess === false) return false;
   return getGlobalBooleanSetting('interactive_search_access', true);
 }
+
+/**
+ * Resolve a user's effective download access permission.
+ */
+export async function resolveDownloadAccess(
+  userRole: string,
+  userDownloadAccess: boolean | null
+): Promise<boolean> {
+  if (userRole === 'admin') return true;
+  if (userDownloadAccess === true) return true;
+  if (userDownloadAccess === false) return false;
+  return getGlobalBooleanSetting('download_access', true);
+}

tests/api/admin-settings-core.routes.test.ts

@@ -152,8 +152,8 @@ describe('Admin settings core routes', () => {
   it('rejects invalid download client types', async () => {
     const request = {
       json: vi.fn().mockResolvedValue({
-        type: 'deluge',
-        url: 'http://deluge',
+        type: 'rtorrent',
+        url: 'http://rtorrent',
       }),
     };
 

tests/api/config.routes.test.ts

@@ -1,104 +0,0 @@
-/**
- * Component: Config API Route Tests
- * Documentation: documentation/testing.md
- */
-
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-
-const configServiceMock = vi.hoisted(() => ({
-  setMany: vi.fn(),
-  getAll: vi.fn(),
-  getCategory: vi.fn(),
-}));
-
-vi.mock('@/lib/services/config.service', () => ({
-  getConfigService: () => configServiceMock,
-}));
-
-describe('Config API routes', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('returns full configuration', async () => {
-    configServiceMock.getAll.mockResolvedValue({ plex_url: 'http://plex' });
-    const { GET } = await import('@/app/api/config/route');
-
-    const response = await GET();
-    const payload = await response.json();
-
-    expect(payload.config.plex_url).toBe('http://plex');
-  });
-
-  it('updates configuration values', async () => {
-    const { PUT } = await import('@/app/api/config/route');
-    const response = await PUT({
-      json: vi.fn().mockResolvedValue({
-        updates: [{ key: 'plex_url', value: 'http://plex' }],
-      }),
-    } as any);
-    const payload = await response.json();
-
-    expect(response.status).toBe(200);
-    expect(payload.updated).toBe(1);
-    expect(configServiceMock.setMany).toHaveBeenCalled();
-  });
-
-  it('returns 400 when configuration update payload is invalid', async () => {
-    const { PUT } = await import('@/app/api/config/route');
-    const response = await PUT({ json: vi.fn().mockResolvedValue({}) } as any);
-    const payload = await response.json();
-
-    expect(response.status).toBe(400);
-    expect(payload.error).toMatch(/Validation error/);
-  });
-
-  it('returns 500 when configuration update fails', async () => {
-    configServiceMock.setMany.mockRejectedValueOnce(new Error('db down'));
-    const { PUT } = await import('@/app/api/config/route');
-    const response = await PUT({
-      json: vi.fn().mockResolvedValue({
-        updates: [{ key: 'plex_url', value: 'http://plex' }],
-      }),
-    } as any);
-    const payload = await response.json();
-
-    expect(response.status).toBe(500);
-    expect(payload.error).toMatch(/Failed to update configuration/);
-  });
-
-  it('returns 500 when configuration lookup fails', async () => {
-    configServiceMock.getAll.mockRejectedValueOnce(new Error('db down'));
-    const { GET } = await import('@/app/api/config/route');
-
-    const response = await GET();
-    const payload = await response.json();
-
-    expect(response.status).toBe(500);
-    expect(payload.error).toMatch(/Failed to get configuration/);
-  });
-
-  it('returns category configuration', async () => {
-    configServiceMock.getCategory.mockResolvedValue({ plex_url: 'http://plex' });
-    const { GET } = await import('@/app/api/config/[category]/route');
-
-    const response = await GET({} as any, { params: Promise.resolve({ category: 'plex' }) });
-    const payload = await response.json();
-
-    expect(payload.category).toBe('plex');
-    expect(payload.config.plex_url).toBe('http://plex');
-  });
-
-  it('returns 500 when category configuration lookup fails', async () => {
-    configServiceMock.getCategory.mockRejectedValueOnce(new Error('db down'));
-    const { GET } = await import('@/app/api/config/[category]/route');
-
-    const response = await GET({} as any, { params: Promise.resolve({ category: 'plex' }) });
-    const payload = await response.json();
-
-    expect(response.status).toBe(500);
-    expect(payload.error).toMatch(/Failed to get configuration/);
-  });
-});
-
-