Bump package version to 1.1.6

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

CLAUDE.md

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

docker-compose.yml

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

docker/unified/app-start.sh

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

docker/unified/entrypoint.sh

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

dockerfile.unified

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

documentation/TABLEOFCONTENTS.md

@@ -5,6 +5,7 @@
 ## Authentication & Users
 - **Plex OAuth, JWT sessions, RBAC** → [backend/services/auth.md](backend/services/auth.md)
 - **Local admin authentication, password change** → [backend/services/auth.md](backend/services/auth.md)
+- **Admin-generated login token per user (URL-login)** → [backend/services/auth.md](backend/services/auth.md)
 - **Route protection, auth guards** → [frontend/routing-auth.md](frontend/routing-auth.md)
 - **Login page UI/UX** → [frontend/pages/login.md](frontend/pages/login.md)
 
@@ -98,6 +99,7 @@
 
 ## Admin Features
 - **Dashboard (metrics, downloads, requests)** → [admin-dashboard.md](admin-dashboard.md)
+- **Bulk import (scan folders, match Audible, batch import)** → [features/bulk-import.md](features/bulk-import.md)
 - **Jobs management UI** → [backend/services/scheduler.md](backend/services/scheduler.md)
 - **Request deletion (soft delete, seeding awareness)** → [admin-features/request-deletion.md](admin-features/request-deletion.md)
 - **Request approval system, auto-approve settings** → [admin-features/request-approval.md](admin-features/request-approval.md)
@@ -166,3 +168,6 @@
 **"How do Hardcover shelves work?"** → [backend/services/hardcover-sync.md](backend/services/hardcover-sync.md)
 **"How do I add a new shelf provider?"** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md#adding-a-new-provider)
 **"How does the shelf sync core work?"** → [backend/services/goodreads-sync.md](backend/services/goodreads-sync.md#shared-sync-core)
+**"How does bulk import work?"** → [features/bulk-import.md](features/bulk-import.md)
+**"How do I import multiple audiobooks at once?"** → [features/bulk-import.md](features/bulk-import.md)
+**"How does the bulk import scanner detect audiobooks?"** → [features/bulk-import.md](features/bulk-import.md)

documentation/backend/services/auth.md

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

documentation/features/bulk-import.md

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

package.json

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

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

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

prisma/migrations/20260311000000_add_ignored_audiobooks/migration.sql

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

prisma/migrations/20260312000000_add_login_token_hash/migration.sql

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

prisma/migrations/20260313000000_add_sessions_invalidated_at/migration.sql

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

prisma/schema.prisma

@@ -57,6 +57,12 @@ model User {
   interactiveSearchAccess Boolean? @map("interactive_search_access") // null = use global setting, true = allow, false = deny
   downloadAccess          Boolean? @map("download_access")           // null = use global setting, true = allow, false = deny
 
+  // Login token (admin-generated, for direct URL login)
+  loginTokenHash String? @map("login_token_hash") // SHA-256 hash of the login token (never store plaintext)
+
+  // Session invalidation (set when login token is revoked to force-logout active sessions)
+  sessionsInvalidatedAt DateTime? @map("sessions_invalidated_at")
+
   // Soft delete support
   deletedAt DateTime? @map("deleted_at")
   deletedBy String?   @map("deleted_by") // Admin user ID who deleted this user
@@ -74,6 +80,7 @@ model User {
   watchedSeries           WatchedSeries[]
   watchedAuthors          WatchedAuthor[]
   homeSections            UserHomeSection[]
+  ignoredAudiobooks       IgnoredAudiobook[]
 
   @@index([plexId])
   @@index([role])
@@ -527,9 +534,10 @@ model GoodreadsShelf {
   rssUrl     String    @map("rss_url") @db.Text
   lastSyncAt DateTime? @map("last_sync_at")
   bookCount  Int?      @map("book_count")
-  coverUrls  String?   @map("cover_urls") @db.Text // JSON array of cover image URLs
-  createdAt  DateTime  @default(now()) @map("created_at")
-  updatedAt  DateTime  @updatedAt @map("updated_at")
+  coverUrls   String?   @map("cover_urls") @db.Text // JSON array of cover image URLs
+  autoRequest Boolean   @default(true) @map("auto_request") // Whether to auto-create requests for books on this shelf
+  createdAt   DateTime  @default(now()) @map("created_at")
+  updatedAt   DateTime  @updatedAt @map("updated_at")
 
   // Relations
   user User @relation(fields: [userId], references: [id], onDelete: Cascade)
@@ -577,9 +585,10 @@ model HardcoverShelf {
   apiToken   String    @map("api_token") @db.Text // User's personal access token for hardcover api
   lastSyncAt DateTime? @map("last_sync_at")
   bookCount  Int?      @map("book_count")
-  coverUrls  String?   @map("cover_urls") @db.Text // JSON array of cover image URLs
-  createdAt  DateTime  @default(now()) @map("created_at")
-  updatedAt  DateTime  @updatedAt @map("updated_at")
+  coverUrls   String?   @map("cover_urls") @db.Text // JSON array of cover image URLs
+  autoRequest Boolean   @default(true) @map("auto_request") // Whether to auto-create requests for books on this shelf
+  createdAt   DateTime  @default(now()) @map("created_at")
+  updatedAt   DateTime  @updatedAt @map("updated_at")
 
   // Relations
   user User @relation(fields: [userId], references: [id], onDelete: Cascade)
@@ -673,6 +682,32 @@ model WatchedAuthor {
   @@map("watched_authors")
 }
 
+// ============================================================================
+// IGNORED AUDIOBOOK TABLE
+// Per-user ignore list for auto-request suppression.
+// Stores the ASIN the user clicked ignore on; works-system expansion
+// happens at check-time in request-creator.service.ts.
+// Documentation: documentation/features/ignored-audiobooks.md
+// ============================================================================
+
+model IgnoredAudiobook {
+  id          String   @id @default(uuid())
+  userId      String   @map("user_id")
+  asin        String   // Audible ASIN that was explicitly ignored
+  title       String   // Display only — snapshot at ignore time
+  author      String   // Display only — snapshot at ignore time
+  coverArtUrl String?  @map("cover_art_url") @db.Text
+  createdAt   DateTime @default(now()) @map("created_at")
+
+  // Relations
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, asin])
+  @@index([userId])
+  @@index([asin])
+  @@map("ignored_audiobooks")
+}
+
 // ============================================================================
 // USER HOME SECTION TABLE
 // Per-user configurable home page sections (popular, new_releases, category)
@@ -718,3 +753,15 @@ model AudibleCacheCategory {
   @@index([categoryId, rank])
   @@map("audible_cache_categories")
 }
+
+// ============================================================================
+// DATA MIGRATION TRACKING
+// Tracks which data migration SQL scripts have been executed (run-once).
+// ============================================================================
+
+model DataMigration {
+  name       String   @id
+  executedAt DateTime @default(now()) @map("executed_at")
+
+  @@map("_data_migrations")
+}

src/app/admin/components/RequestActionsDropdown.tsx

@@ -66,7 +66,7 @@ export function RequestActionsDropdown({
   const canSearch = ['pending', 'failed', 'awaiting_search'].includes(request.status);
   const canAdjustSearchTerms = ['pending', 'failed', 'awaiting_search', 'searching'].includes(request.status);
   const canRetryDownload = request.status === 'failed' && (request.downloadAttempts ?? 0) > 0 && !!onRetryDownload;
-  const canCancel = ['pending', 'searching', 'downloading'].includes(request.status);
+  const canCancel = ['pending', 'searching', 'downloading', 'awaiting_search'].includes(request.status);
   const canDelete = true; // Admins can always delete
 
   // View Source: For ebooks, extract MD5 from slow download URL and link to Anna's Archive

src/app/admin/page.tsx

@@ -14,6 +14,7 @@ import { RecentRequestsTable } from './components/RecentRequestsTable';
 import { ToastProvider, useToast } from '@/components/ui/Toast';
 import { ReportedIssuesSection } from './components/ReportedIssuesSection';
 import { InteractiveTorrentSearchModal } from '@/components/requests/InteractiveTorrentSearchModal';
+import { BulkImportWizard } from '@/components/admin/BulkImportWizard';
 import { TorrentResult } from '@/lib/utils/ranking-algorithm';
 import { formatDistanceToNow } from 'date-fns';
 import { useState } from 'react';
@@ -379,6 +380,8 @@ function PendingApprovalSection({ requests }: { requests: PendingApprovalRequest
 }
 
 function AdminDashboardContent() {
+  const [isBulkImportOpen, setIsBulkImportOpen] = useState(false);
+
   // Fetch data with auto-refresh every 10 seconds
   const { data: metrics, error: metricsError } = useSWR(
     '/api/admin/metrics',
@@ -572,7 +575,7 @@ function AdminDashboardContent() {
             </div>
 
             {/* Quick Actions */}
-            <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 mb-8">
+            <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-5 gap-4 mb-8">
               <Link
                 href="/admin/settings"
                 className="block p-6 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg hover:shadow-md transition-all"
@@ -657,8 +660,38 @@ function AdminDashboardContent() {
                   </span>
                 </div>
               </Link>
+
+              <button
+                onClick={() => setIsBulkImportOpen(true)}
+                className="block p-6 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg hover:shadow-md transition-all text-left"
+              >
+                <div className="flex items-center gap-3">
+                  <svg
+                    className="w-6 h-6 text-gray-600 dark:text-gray-400"
+                    fill="none"
+                    stroke="currentColor"
+                    viewBox="0 0 24 24"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M12 10v6m0 0l-3-3m3 3l3-3m2 8H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
+                    />
+                  </svg>
+                  <span className="font-medium text-gray-900 dark:text-gray-100">
+                    Bulk Import
+                  </span>
+                </div>
+              </button>
             </div>
 
+            {/* Bulk Import Wizard Modal */}
+            <BulkImportWizard
+              isOpen={isBulkImportOpen}
+              onClose={() => setIsBulkImportOpen(false)}
+            />
+
             {/* Requests Awaiting Approval */}
             {pendingApprovalData?.requests && pendingApprovalData.requests.length > 0 && (
               <PendingApprovalSection requests={pendingApprovalData.requests} />

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

@@ -102,6 +102,8 @@ export interface PathsSettings {
   chapterMergingEnabled: boolean;
   fileRenameEnabled: boolean;
   fileRenameTemplate?: string;
+  fileChmod?: string;
+  dirChmod?: string;
 }
 
 /**

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

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

src/app/admin/users/page.tsx

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

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

@@ -7,7 +7,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
 import { prisma } from '@/lib/db';
 import { RMABLogger } from '@/lib/utils/logger';
-import { checkApiTokenRevokeRateLimit } from '@/lib/utils/apiTokenRateLimit';
+import { checkApiTokenRevokeRateLimit } from '@/lib/utils/rateLimit';
 
 const logger = RMABLogger.create('API.Admin.ApiTokens');
 

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

@@ -7,7 +7,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { requireAuth, requireAdmin, AuthenticatedRequest } from '@/lib/middleware/auth';
 import { prisma } from '@/lib/db';
 import { RMABLogger } from '@/lib/utils/logger';
-import { checkApiTokenCreateRateLimit } from '@/lib/utils/apiTokenRateLimit';
+import { checkApiTokenCreateRateLimit } from '@/lib/utils/rateLimit';
 import { MAX_TOKENS_PER_USER } from '@/lib/constants/api-tokens';
 import { generateApiToken } from '@/lib/utils/api-token';
 import { z } from 'zod';

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

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

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

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

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

@@ -100,15 +100,21 @@ export async function PATCH(
             },
           });
 
-          // Queue search job
+          // Queue search job based on request type
           const { getJobQueueService } = await import('@/lib/services/job-queue.service');
           const jobQueue = getJobQueueService();
-          await jobQueue.addSearchJob(id, {
+          const audiobookData = {
             id: existingRequest.audiobook.id,
             title: existingRequest.audiobook.title,
             author: existingRequest.audiobook.author,
             asin: existingRequest.audiobook.audibleAsin || undefined,
-          });
+          };
+
+          if (existingRequest.type === 'ebook') {
+            await jobQueue.addSearchEbookJob(id, audiobookData);
+          } else {
+            await jobQueue.addSearchJob(id, audiobookData);
+          }
 
           searchTriggered = true;
           logger.info(`Search triggered for request ${id} with custom terms`, { requestId: id });

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

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

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

@@ -130,6 +130,8 @@ export async function GET(request: NextRequest) {
         chapterMergingEnabled: configMap.get('chapter_merging_enabled') === 'true',
         fileRenameEnabled: configMap.get('file_rename_enabled') === 'true',
         fileRenameTemplate: configMap.get('file_rename_template') || '{title}',
+        fileChmod: configMap.get('file_chmod') || '664',
+        dirChmod: configMap.get('dir_chmod') || '775',
       },
       ebook: {
         // New granular source toggles (with migration from legacy ebook_sidecar_enabled)

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

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

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

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

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

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

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

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

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

@@ -11,6 +11,7 @@ import { prisma } from '@/lib/db';
 import { enrichAudiobooksWithMatches, getAvailableAsins } from '@/lib/utils/audiobook-matcher';
 import { getCurrentUser } from '@/lib/middleware/auth';
 import { RMABLogger } from '@/lib/utils/logger';
+import { annotateWithIgnoreStatus } from '@/lib/utils/ignored-audiobooks';
 
 const logger = RMABLogger.create('API.Audiobooks.Category');
 
@@ -129,12 +130,15 @@ export async function GET(
     const userId = currentUser?.sub || undefined;
     const enrichedAudiobooks = await enrichAudiobooksWithMatches(audibleBooks, userId);
 
+    // Annotate with per-user ignore status
+    const annotatedAudiobooks = await annotateWithIgnoreStatus(enrichedAudiobooks, userId);
+
     const totalPages = Math.ceil(totalCount / limit);
     const hasMore = page < totalPages;
 
     return NextResponse.json({
       success: true,
-      audiobooks: enrichedAudiobooks,
+      audiobooks: annotatedAudiobooks,
       count: enrichedAudiobooks.length,
       totalCount,
       page,

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

@@ -11,6 +11,7 @@ import { prisma } from '@/lib/db';
 import { enrichAudiobooksWithMatches, getAvailableAsins } from '@/lib/utils/audiobook-matcher';
 import { getCurrentUser } from '@/lib/middleware/auth';
 import { RMABLogger } from '@/lib/utils/logger';
+import { annotateWithIgnoreStatus } from '@/lib/utils/ignored-audiobooks';
 import { NEW_RELEASES_CATEGORY_ID } from '@/lib/processors/audible-refresh.processor';
 
 const logger = RMABLogger.create('API.Audiobooks.NewReleases');
@@ -136,12 +137,15 @@ export async function GET(request: NextRequest) {
     // Enrich with real-time Plex library matching and request status
     const enrichedAudiobooks = await enrichAudiobooksWithMatches(audibleBooks, userId);
 
+    // Annotate with per-user ignore status
+    const annotatedAudiobooks = await annotateWithIgnoreStatus(enrichedAudiobooks, userId);
+
     const totalPages = Math.ceil(totalCount / limit);
     const hasMore = page < totalPages;
 
     return NextResponse.json({
       success: true,
-      audiobooks: enrichedAudiobooks,
+      audiobooks: annotatedAudiobooks,
       count: enrichedAudiobooks.length,
       totalCount,
       page,

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

@@ -11,6 +11,7 @@ import { prisma } from '@/lib/db';
 import { enrichAudiobooksWithMatches, getAvailableAsins } from '@/lib/utils/audiobook-matcher';
 import { getCurrentUser } from '@/lib/middleware/auth';
 import { RMABLogger } from '@/lib/utils/logger';
+import { annotateWithIgnoreStatus } from '@/lib/utils/ignored-audiobooks';
 import { POPULAR_CATEGORY_ID } from '@/lib/processors/audible-refresh.processor';
 
 const logger = RMABLogger.create('API.Audiobooks.Popular');
@@ -136,12 +137,15 @@ export async function GET(request: NextRequest) {
     // Enrich with real-time Plex library matching and request status
     const enrichedAudiobooks = await enrichAudiobooksWithMatches(audibleBooks, userId);
 
+    // Annotate with per-user ignore status
+    const annotatedAudiobooks = await annotateWithIgnoreStatus(enrichedAudiobooks, userId);
+
     const totalPages = Math.ceil(totalCount / limit);
     const hasMore = page < totalPages;
 
     return NextResponse.json({
       success: true,
-      audiobooks: enrichedAudiobooks,
+      audiobooks: annotatedAudiobooks,
       count: enrichedAudiobooks.length,
       totalCount,
       page,

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

@@ -10,6 +10,7 @@ import { deduplicateAndCollectGroups } from '@/lib/utils/deduplicate-audiobooks'
 import { persistDedupGroups } from '@/lib/services/works.service';
 import { getCurrentUser } from '@/lib/middleware/auth';
 import { RMABLogger } from '@/lib/utils/logger';
+import { annotateWithIgnoreStatus } from '@/lib/utils/ignored-audiobooks';
 
 const logger = RMABLogger.create('API.Audiobooks.Search');
 
@@ -51,10 +52,13 @@ export async function GET(request: NextRequest) {
     // Enrich search results with availability and request status information
     const enrichedResults = await enrichAudiobooksWithMatches(dedupedResults, userId);
 
+    // Annotate with per-user ignore status
+    const annotatedResults = await annotateWithIgnoreStatus(enrichedResults, userId);
+
     return NextResponse.json({
       success: true,
       query: results.query,
-      results: enrichedResults,
+      results: annotatedResults,
       totalResults: enrichedResults.length,
       page: results.page,
       hasMore: results.hasMore,

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

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

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

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

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

@@ -10,6 +10,7 @@ import { deduplicateAndCollectGroups } from '@/lib/utils/deduplicate-audiobooks'
 import { persistDedupGroups } from '@/lib/services/works.service';
 import { getCurrentUser } from '@/lib/middleware/auth';
 import { RMABLogger } from '@/lib/utils/logger';
+import { annotateWithIgnoreStatus } from '@/lib/utils/ignored-audiobooks';
 
 const logger = RMABLogger.create('API.Authors.Books');
 
@@ -67,11 +68,14 @@ export async function GET(
     const userId = currentUser.sub || undefined;
     const enrichedBooks = await enrichAudiobooksWithMatches(dedupedBooks, userId);
 
-    logger.info(`Author books complete: "${authorName}" → ${enrichedBooks.length} books (page ${page})`);
+    // Annotate with per-user ignore status
+    const annotatedBooks = await annotateWithIgnoreStatus(enrichedBooks, userId);
+
+    logger.info(`Author books complete: "${authorName}" → ${annotatedBooks.length} books (page ${page})`);
 
     return NextResponse.json({
       success: true,
-      books: enrichedBooks,
+      books: annotatedBooks,
       authorName: authorName.trim(),
       authorAsin: asin,
       totalBooks: enrichedBooks.length,

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

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

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

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

src/app/api/requests/route.ts

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

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

@@ -10,6 +10,7 @@ import { scrapeSeriesPage } from '@/lib/integrations/audible-series';
 import { enrichAudiobooksWithMatches } from '@/lib/utils/audiobook-matcher';
 import { deduplicateAndCollectGroups } from '@/lib/utils/deduplicate-audiobooks';
 import { persistDedupGroups } from '@/lib/services/works.service';
+import { annotateWithIgnoreStatus } from '@/lib/utils/ignored-audiobooks';
 
 const logger = RMABLogger.create('API.Series.Detail');
 
@@ -63,13 +64,16 @@ export async function GET(
     const userId = currentUser.sub || undefined;
     const enrichedBooks = await enrichAudiobooksWithMatches(dedupedBooks, userId);
 
-    logger.info(`Series detail complete: "${detail.title}" (${enrichedBooks.length} books, page ${page})`);
+    // Annotate with per-user ignore status
+    const annotatedBooks = await annotateWithIgnoreStatus(enrichedBooks, userId);
+
+    logger.info(`Series detail complete: "${detail.title}" (${annotatedBooks.length} books, page ${page})`);
 
     return NextResponse.json({
       success: true,
       series: {
         ...detail,
-        books: enrichedBooks,
+        books: annotatedBooks,
       },
       hasMore: detail.hasMore,
       page: detail.page,

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

@@ -7,7 +7,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
 import { prisma } from '@/lib/db';
 import { RMABLogger } from '@/lib/utils/logger';
-import { checkApiTokenRevokeRateLimit } from '@/lib/utils/apiTokenRateLimit';
+import { checkApiTokenRevokeRateLimit } from '@/lib/utils/rateLimit';
 
 const logger = RMABLogger.create('API.User.ApiTokens');
 

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

@@ -7,7 +7,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { requireAuth, AuthenticatedRequest } from '@/lib/middleware/auth';
 import { prisma } from '@/lib/db';
 import { RMABLogger } from '@/lib/utils/logger';
-import { checkApiTokenCreateRateLimit } from '@/lib/utils/apiTokenRateLimit';
+import { checkApiTokenCreateRateLimit } from '@/lib/utils/rateLimit';
 import { MAX_TOKENS_PER_USER } from '@/lib/constants/api-tokens';
 import { generateApiToken } from '@/lib/utils/api-token';
 import { z } from 'zod';

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

@@ -13,7 +13,8 @@ import { z } from 'zod';
 const logger = RMABLogger.create('API.GoodreadsShelves');
 
 const UpdateGoodreadsSchema = z.object({
-  rssUrl: z.string().url('Must be a valid URL'),
+  rssUrl: z.string().url('Must be a valid URL').optional(),
+  autoRequest: z.boolean().optional(),
 });
 
 /**
@@ -81,21 +82,37 @@ export async function PATCH(
       }
 
       const body = await request.json();
-      const { rssUrl } = UpdateGoodreadsSchema.parse(body);
+      const { rssUrl, autoRequest } = UpdateGoodreadsSchema.parse(body);
+
+      const updateData: Record<string, unknown> = {};
+      let needsResync = false;
+
+      if (rssUrl !== undefined) {
+        updateData.rssUrl = rssUrl;
+        updateData.lastSyncAt = null;
+        updateData.bookCount = null;
+        updateData.coverUrls = null;
+        needsResync = true;
+      }
+
+      if (autoRequest !== undefined) {
+        updateData.autoRequest = autoRequest;
+      }
 
-      // Force re-fetch by clearing metadata
       const updated = await prisma.goodreadsShelf.update({
         where: { id },
-        data: { rssUrl, lastSyncAt: null, bookCount: null, coverUrls: null },
+        data: updateData,
       });
 
-      try {
-        const jobQueue = getJobQueueService();
-        await jobQueue.addSyncShelvesJob(undefined, updated.id, 'goodreads', 0);
-      } catch (error) {
-        logger.error('Failed to trigger immediate list sync', {
-          error: error instanceof Error ? error.message : String(error),
-        });
+      if (needsResync) {
+        try {
+          const jobQueue = getJobQueueService();
+          await jobQueue.addSyncShelvesJob(undefined, updated.id, 'goodreads', 0, req.user.id);
+        } catch (error) {
+          logger.error('Failed to trigger immediate list sync', {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
       }
 
       return NextResponse.json({ success: true, shelf: updated });

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

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

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

@@ -17,6 +17,8 @@ const logger = RMABLogger.create('API.HardcoverShelves');
 const UpdateHardcoverSchema = z.object({
   listId: z.string().min(1, 'List ID is required').optional(),
   apiToken: z.string().optional(),
+  forceSync: z.boolean().optional(),
+  autoRequest: z.boolean().optional(),
 });
 
 /**
@@ -89,10 +91,14 @@ export async function PATCH(
       }
 
       const body = await request.json();
-      const { listId, apiToken } = UpdateHardcoverSchema.parse(body);
+      const { listId, apiToken, forceSync, autoRequest } = UpdateHardcoverSchema.parse(body);
 
-      const updateData: { listId?: string; apiToken?: string; lastSyncAt?: null; bookCount?: null; coverUrls?: null } = {};
-      let needsResync = false;
+      const updateData: { listId?: string; apiToken?: string; autoRequest?: boolean; lastSyncAt?: null; bookCount?: null; coverUrls?: null } = {};
+
+      if (autoRequest !== undefined) {
+        updateData.autoRequest = autoRequest;
+      }
+      let needsResync = !!forceSync;
 
       let cleanedToken: string | undefined;
       if (apiToken && apiToken.trim() !== '') {
@@ -155,7 +161,7 @@ export async function PATCH(
       if (needsResync) {
         try {
           const jobQueue = getJobQueueService();
-          await jobQueue.addSyncShelvesJob(undefined, updated.id, 'hardcover', 0);
+          await jobQueue.addSyncShelvesJob(undefined, updated.id, 'hardcover', 0, req.user.id);
         } catch (error) {
           logger.error('Failed to trigger immediate list sync', {
             error: error instanceof Error ? error.message : String(error),

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

@@ -18,6 +18,7 @@ const logger = RMABLogger.create('API.HardcoverShelves');
 const AddShelfSchema = z.object({
   listId: z.string().min(1, { message: 'List ID is required' }),
   apiToken: z.string().min(1, { message: 'API Token is required' }),
+  autoRequest: z.boolean().optional().default(true),
 });
 
 /**
@@ -46,6 +47,7 @@ export async function GET(request: NextRequest) {
           lastSyncAt: shelf.lastSyncAt,
           createdAt: shelf.createdAt,
           bookCount: shelf.bookCount ?? null,
+          autoRequest: shelf.autoRequest,
           books,
         };
       });
@@ -75,7 +77,9 @@ export async function POST(request: NextRequest) {
       }
 
       const body = await req.json();
-      let { listId, apiToken } = AddShelfSchema.parse(body);
+      const parsed = AddShelfSchema.parse(body);
+      let { listId, apiToken } = parsed;
+      const { autoRequest } = parsed;
 
       // Clean up token in case user pasted "Bearer " prefix
       apiToken = apiToken.trim();
@@ -139,6 +143,7 @@ export async function POST(request: NextRequest) {
           name: listName,
           listId,
           apiToken: encryptedToken,
+          autoRequest,
           bookCount,
           coverUrls:
             initialBooks.length > 0 ? JSON.stringify(initialBooks) : null,
@@ -148,7 +153,7 @@ export async function POST(request: NextRequest) {
       // Trigger immediate sync for this shelf (unlimited lookups, process all books)
       try {
         const jobQueue = getJobQueueService();
-        await jobQueue.addSyncShelvesJob(undefined, shelf.id, 'hardcover', 0);
+        await jobQueue.addSyncShelvesJob(undefined, shelf.id, 'hardcover', 0, req.user.id);
         logger.info(
           `Triggered immediate sync for Hardcover list "${listName}" (${shelf.id})`,
         );
@@ -168,6 +173,7 @@ export async function POST(request: NextRequest) {
             lastSyncAt: shelf.lastSyncAt,
             createdAt: shelf.createdAt,
             bookCount: shelf.bookCount,
+            autoRequest: shelf.autoRequest,
             books: initialBooks,
           },
           bookCount,

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

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

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

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

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

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

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

@@ -42,6 +42,7 @@ export async function GET(request: NextRequest) {
           lastSyncAt: s.lastSyncAt,
           createdAt: s.createdAt,
           bookCount: s.bookCount ?? null,
+          autoRequest: s.autoRequest,
           books: processBooks(s.coverUrls),
         })),
         ...hardcover.map((s) => ({
@@ -52,6 +53,7 @@ export async function GET(request: NextRequest) {
           lastSyncAt: s.lastSyncAt,
           createdAt: s.createdAt,
           bookCount: s.bookCount ?? null,
+          autoRequest: s.autoRequest,
           books: processBooks(s.coverUrls),
         })),
       ].sort(

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

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

src/app/auth/token/login/page.tsx

@@ -0,0 +1,68 @@
+/**
+ * Component: Token Login Page
+ * Documentation: documentation/backend/services/auth.md
+ */
+
+'use client';
+
+import { Suspense, useEffect } from 'react';
+import { useRouter, useSearchParams } from 'next/navigation';
+import { useAuth } from '@/contexts/AuthContext';
+
+function TokenLoginContent() {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const { setAuthData } = useAuth();
+
+  useEffect(() => {
+    const token = searchParams.get('token');
+
+    if (!token) {
+      router.replace('/login');
+      return;
+    }
+
+    // Scrub token from browser URL/history immediately after extraction
+    window.history.replaceState({}, '', '/auth/token/login');
+
+    fetch('/api/auth/token/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token }),
+    })
+      .then((res) => res.json())
+      .then((data) => {
+        if (data.error) {
+          router.replace('/login');
+          return;
+        }
+
+        localStorage.setItem('accessToken', data.accessToken);
+        localStorage.setItem('refreshToken', data.refreshToken);
+        localStorage.setItem('user', JSON.stringify(data.user));
+
+        setAuthData(data.user, data.accessToken);
+        window.location.href = '/';
+      })
+      .catch(() => {
+        router.replace('/login');
+      });
+  }, [searchParams, router, setAuthData]);
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gray-900">
+      <div className="text-center">
+        <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-orange-500 mx-auto mb-4"></div>
+        <p className="text-gray-400 text-sm">Authenticating...</p>
+      </div>
+    </div>
+  );
+}
+
+export default function TokenLoginPage() {
+  return (
+    <Suspense>
+      <TokenLoginContent />
+    </Suspense>
+  );
+}

src/app/globals.css

@@ -197,6 +197,23 @@ body {
   animation: toast-slide-in 0.3s ease-out;
 }
 
+/* Requests page list entry animations */
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+
+@keyframes fadeInUp {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
 /* Confirmation Dialog */
 @keyframes dialog-backdrop-in {
   from { opacity: 0; }

src/app/requests/page.tsx

@@ -1,221 +1,405 @@
 /**
- * Component: Requests Page
+ * Component: My Requests Page
  * Documentation: documentation/frontend/components.md
  */
 
 'use client';
 
-import { useState } from 'react';
+import { useState, useRef, useEffect } from 'react';
 import { Header } from '@/components/layout/Header';
 import { RequestCard } from '@/components/requests/RequestCard';
-import { useRequests } from '@/lib/hooks/useRequests';
+import { useMyRequests, RequestFilterGroup, RequestCounts } from '@/lib/hooks/useRequests';
 import { useAuth } from '@/contexts/AuthContext';
-import { usePreferences } from '@/contexts/PreferencesContext';
 import { cn } from '@/lib/utils/cn';
 
-type FilterStatus = 'all' | 'active' | 'waiting' | 'completed' | 'failed' | 'cancelled';
+// ── Tab configuration ────────────────────────────────────────────────────────
+
+interface TabOption {
+  value: RequestFilterGroup;
+  label: string;
+  countKey: keyof RequestCounts;
+}
+
+const TABS: TabOption[] = [
+  { value: 'all',       label: 'All',       countKey: 'all'       },
+  { value: 'active',    label: 'Active',    countKey: 'active'    },
+  { value: 'waiting',   label: 'Waiting',   countKey: 'waiting'   },
+  { value: 'completed', label: 'Completed', countKey: 'completed' },
+  { value: 'failed',    label: 'Failed',    countKey: 'failed'    },
+  { value: 'cancelled', label: 'Cancelled', countKey: 'cancelled' },
+];
+
+// ── Count badge ──────────────────────────────────────────────────────────────
+
+function CountBadge({ count, active }: { count: number; active: boolean }) {
+  if (count === 0) return null;
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center justify-center min-w-[18px] h-[18px] px-1 rounded-full text-[10px] font-semibold tabular-nums transition-all duration-200',
+        active
+          ? 'bg-blue-500/20 text-blue-600 dark:bg-blue-400/20 dark:text-blue-400'
+          : 'bg-gray-200/80 text-gray-500 dark:bg-white/[0.07] dark:text-gray-400'
+      )}
+    >
+      {count > 999 ? '999+' : count}
+    </span>
+  );
+}
+
+// ── Skeleton card ────────────────────────────────────────────────────────────
+
+function SkeletonCard() {
+  return (
+    <div className="bg-white dark:bg-gray-800/60 rounded-xl overflow-hidden border border-gray-100 dark:border-white/[0.06]">
+      <div className="flex gap-3 sm:gap-4 p-3 sm:p-4">
+        {/* Cover placeholder */}
+        <div className="flex-shrink-0 w-16 sm:w-24 aspect-[2/3] rounded-lg bg-gray-200 dark:bg-white/[0.06] animate-pulse" />
+        {/* Content placeholder */}
+        <div className="flex-1 min-w-0 space-y-3 pt-1">
+          <div className="space-y-2">
+            <div className="h-4 bg-gray-200 dark:bg-white/[0.06] rounded-md animate-pulse w-3/4" />
+            <div className="h-3 bg-gray-200 dark:bg-white/[0.06] rounded-md animate-pulse w-1/2" />
+          </div>
+          <div className="h-5 bg-gray-200 dark:bg-white/[0.06] rounded-full animate-pulse w-20" />
+          <div className="pt-3 border-t border-gray-100 dark:border-white/[0.05]">
+            <div className="h-3 bg-gray-200 dark:bg-white/[0.06] rounded animate-pulse w-28" />
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ── Empty state ──────────────────────────────────────────────────────────────
+
+function EmptyState({ filter }: { filter: RequestFilterGroup }) {
+  const isAll = filter === 'all';
+  return (
+    <div className="flex flex-col items-center justify-center py-20 text-center space-y-5">
+      <div className="w-16 h-16 rounded-2xl bg-gray-100 dark:bg-white/[0.06] flex items-center justify-center">
+        <svg
+          className="w-8 h-8 text-gray-400 dark:text-gray-500"
+          fill="none"
+          stroke="currentColor"
+          viewBox="0 0 24 24"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            strokeWidth={1.5}
+            d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
+          />
+        </svg>
+      </div>
+      <div className="space-y-1.5">
+        <h2 className="text-base font-semibold text-gray-900 dark:text-gray-100">
+          {isAll ? 'No requests yet' : `No ${filter} requests`}
+        </h2>
+        <p className="text-sm text-gray-500 dark:text-gray-400 max-w-xs">
+          {isAll
+            ? 'Start by searching for audiobooks and requesting them'
+            : `You don't have any ${filter} requests right now`}
+        </p>
+      </div>
+      {isAll && (
+        <a
+          href="/search"
+          className="inline-flex items-center gap-2 px-5 py-2.5 bg-blue-600 hover:bg-blue-700 active:bg-blue-800 text-white text-sm font-medium rounded-xl transition-all duration-150 shadow-sm hover:shadow-md"
+        >
+          <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>
+          Browse Audiobooks
+        </a>
+      )}
+    </div>
+  );
+}
+
+// ── Load More button ─────────────────────────────────────────────────────────
+
+function LoadMoreButton({ onClick, isLoading }: { onClick: () => void; isLoading: boolean }) {
+  return (
+    <div className="flex justify-center pt-2 pb-4">
+      <button
+        onClick={onClick}
+        disabled={isLoading}
+        className={cn(
+          'inline-flex items-center gap-2 px-6 py-2.5 rounded-xl text-sm font-medium transition-all duration-150',
+          'border border-gray-200 dark:border-white/[0.1]',
+          'text-gray-700 dark:text-gray-300',
+          'bg-white dark:bg-white/[0.04]',
+          'hover:bg-gray-50 dark:hover:bg-white/[0.07]',
+          'active:scale-[0.98]',
+          'disabled:opacity-50 disabled:cursor-not-allowed disabled:active:scale-100',
+          'shadow-sm'
+        )}
+      >
+        {isLoading ? (
+          <>
+            <svg className="w-4 h-4 animate-spin text-gray-400" fill="none" viewBox="0 0 24 24">
+              <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>
+            Loading more...
+          </>
+        ) : (
+          <>
+            Load more
+            <svg className="w-4 h-4 text-gray-400" 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>
+    </div>
+  );
+}
+
+// ── Live indicator ───────────────────────────────────────────────────────────
+
+function LiveIndicator({ hasActive }: { hasActive: boolean }) {
+  if (!hasActive) return null;
+  return (
+    <div className="flex items-center gap-1.5 text-[11px] text-gray-400 dark:text-gray-500">
+      <span className="relative flex h-1.5 w-1.5">
+        <span className="animate-ping absolute inline-flex h-full w-full rounded-full bg-emerald-400 opacity-75" />
+        <span className="relative inline-flex rounded-full h-1.5 w-1.5 bg-emerald-500" />
+      </span>
+      Live
+    </div>
+  );
+}
+
+// ── Tab bar ──────────────────────────────────────────────────────────────────
+
+interface TabBarProps {
+  filter: RequestFilterGroup;
+  counts: RequestCounts;
+  countsLoaded: boolean;
+  onChange: (f: RequestFilterGroup) => void;
+}
+
+function TabBar({ filter, counts, countsLoaded, onChange }: TabBarProps) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  // Scroll active tab into view on mount/change
+  useEffect(() => {
+    const container = scrollRef.current;
+    if (!container) return;
+    const active = container.querySelector('[data-active="true"]') as HTMLElement | null;
+    if (active) {
+      const { offsetLeft, offsetWidth } = active;
+      const { scrollLeft, clientWidth } = container;
+      if (offsetLeft < scrollLeft || offsetLeft + offsetWidth > scrollLeft + clientWidth) {
+        container.scrollTo({ left: offsetLeft - 16, behavior: 'smooth' });
+      }
+    }
+  }, [filter]);
+
+  return (
+    <div className="relative -mx-4 sm:mx-0">
+      {/* Left fade */}
+      <div className="pointer-events-none absolute left-0 top-0 bottom-0 w-8 bg-gradient-to-r from-white dark:from-gray-950 to-transparent z-10 sm:hidden" />
+      {/* Right fade */}
+      <div className="pointer-events-none absolute right-0 top-0 bottom-0 w-8 bg-gradient-to-l from-white dark:from-gray-950 to-transparent z-10 sm:hidden" />
+
+      <div
+        ref={scrollRef}
+        className="flex gap-1 overflow-x-auto scrollbar-hide px-4 sm:px-0"
+        role="tablist"
+      >
+        {TABS.map((tab) => {
+          const isActive = filter === tab.value;
+          const count = counts[tab.countKey];
+          // Hide tabs with 0 count unless it's 'all' or currently active
+          if (!isActive && tab.value !== 'all' && countsLoaded && count === 0) return null;
+          return (
+            <button
+              key={tab.value}
+              role="tab"
+              aria-selected={isActive}
+              data-active={isActive}
+              onClick={() => onChange(tab.value)}
+              className={cn(
+                'flex items-center gap-1.5 px-3.5 py-2 rounded-xl text-sm font-medium whitespace-nowrap transition-all duration-150 outline-none flex-shrink-0',
+                'focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2',
+                isActive
+                  ? 'bg-white dark:bg-white/[0.08] text-gray-900 dark:text-white shadow-[0_1px_3px_rgba(0,0,0,0.08),0_1px_6px_rgba(0,0,0,0.05)] dark:shadow-[0_1px_3px_rgba(0,0,0,0.4)] border border-gray-200/80 dark:border-white/[0.1]'
+                  : 'text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-300 hover:bg-black/[0.03] dark:hover:bg-white/[0.04]'
+              )}
+            >
+              {tab.label}
+              {countsLoaded
+                ? <CountBadge count={count} active={isActive} />
+                : tab.value !== 'all' && (
+                    <span className="inline-block w-5 h-3.5 rounded bg-gray-200 dark:bg-white/[0.07] animate-pulse" />
+                  )
+              }
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+// ── Showing count bar ────────────────────────────────────────────────────────
+
+function ShowingBar({ showing, total, hasActive }: { showing: number; total: number; hasActive: boolean }) {
+  if (showing === 0) return null;
+  return (
+    <div className="flex items-center justify-between text-xs text-gray-400 dark:text-gray-500 px-0.5">
+      <span>
+        Showing <span className="text-gray-600 dark:text-gray-300 font-medium tabular-nums">{showing}</span>
+        {' of '}
+        <span className="text-gray-600 dark:text-gray-300 font-medium tabular-nums">{total}</span>
+        {total === 1 ? ' request' : ' requests'}
+      </span>
+      <LiveIndicator hasActive={hasActive} />
+    </div>
+  );
+}
+
+// ── Main page ────────────────────────────────────────────────────────────────
 
 export default function RequestsPage() {
   const { user } = useAuth();
-  const { squareCovers } = usePreferences();
-  const [filter, setFilter] = useState<FilterStatus>('all');
+  const [filter, setFilter] = useState<RequestFilterGroup>('all');
 
-  // Always fetch only the current user's requests (even for admins)
-  // This ensures "My Requests" truly shows only the user's own requests
-  // Admins can see all requests in the admin panel
-  const { requests, isLoading } = useRequests(undefined, 50, true);
+  const {
+    requests,
+    counts,
+    hasMore,
+    isLoading,
+    isLoadingMore,
+    isEmpty,
+    loadMore,
+  } = useMyRequests(filter);
 
-  // Filter requests client-side based on selected filter
-  const filteredRequests = filter === 'all'
-    ? requests
-    : filter === 'active'
-    ? requests.filter((r: any) => ['pending', 'searching', 'downloading', 'processing'].includes(r.status))
-    : filter === 'waiting'
-    ? requests.filter((r: any) => ['awaiting_search', 'awaiting_import'].includes(r.status))
-    : filter === 'completed'
-    ? requests.filter((r: any) => ['available', 'downloaded'].includes(r.status))
-    : requests.filter((r: any) => r.status === filter);
+  const countsLoaded = !isLoading || requests.length > 0;
+  const totalForFilter = counts[filter === 'all' ? 'all' : filter as keyof RequestCounts] ?? 0;
+  const hasActiveRequests = requests.some(r =>
+    ['pending', 'awaiting_search', 'awaiting_approval', 'searching', 'downloading', 'processing', 'awaiting_import'].includes(r.status)
+  );
 
-  const filterOptions: { value: FilterStatus; label: string }[] = [
-    { value: 'all', label: 'All' },
-    { value: 'active', label: 'Active' },
-    { value: 'waiting', label: 'Waiting' },
-    { value: 'completed', label: 'Completed' },
-    { value: 'failed', label: 'Failed' },
-    { value: 'cancelled', label: 'Cancelled' },
-  ];
+  const handleFilterChange = (f: RequestFilterGroup) => {
+    setFilter(f);
+  };
 
-  // Redirect to login if not authenticated
+  // ── Unauthenticated ────────────────────────────────────────────────────────
   if (!user) {
     return (
       <div className="min-h-screen">
         <Header />
-        <main className="container mx-auto px-4 py-8 max-w-7xl">
-          <div className="text-center py-16 space-y-4">
-            <svg
-              className="mx-auto h-16 w-16 text-gray-400"
-              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>
-            <h2 className="text-2xl font-bold text-gray-900 dark:text-gray-100">
-              Authentication Required
-            </h2>
-            <p className="text-gray-600 dark:text-gray-400">
-              Please log in to view your audiobook requests
-            </p>
+        <main className="container mx-auto px-4 py-8 max-w-4xl">
+          <div className="flex flex-col items-center justify-center py-20 text-center space-y-5">
+            <div className="w-16 h-16 rounded-2xl bg-gray-100 dark:bg-white/[0.06] flex items-center justify-center">
+              <svg className="w-8 h-8 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5}
+                  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>
+            </div>
+            <div className="space-y-1.5">
+              <h2 className="text-base font-semibold text-gray-900 dark:text-gray-100">Authentication Required</h2>
+              <p className="text-sm text-gray-500 dark:text-gray-400">Please log in to view your audiobook requests</p>
+            </div>
           </div>
         </main>
       </div>
     );
   }
 
+  // ── Authenticated ──────────────────────────────────────────────────────────
   return (
     <div className="min-h-screen">
       <Header />
 
-      <main className="container mx-auto px-4 py-6 sm:py-8 max-w-7xl space-y-6 sm:space-y-8">
-        {/* Page Header */}
-        <div className="space-y-2 sm:space-y-4">
-          <h1 className="text-2xl sm:text-3xl md:text-4xl font-bold text-gray-900 dark:text-gray-100">
+      <main className="container mx-auto px-4 py-6 sm:py-10 max-w-4xl">
+
+        {/* Page header */}
+        <div className="mb-6 sm:mb-8">
+          <h1 className="text-2xl sm:text-3xl font-bold tracking-tight text-gray-900 dark:text-gray-50">
             My Requests
           </h1>
-          <p className="text-sm sm:text-base text-gray-600 dark:text-gray-400">
+          <p className="mt-1 text-sm text-gray-500 dark:text-gray-400">
             Track the status of your audiobook requests in real-time
           </p>
         </div>
 
-        {/* Filter Tabs */}
-        <div className="border-b border-gray-200 dark:border-gray-700 -mx-4 px-4 sm:mx-0 sm:px-0">
-          <div className="flex gap-2 sm:gap-4 -mb-px overflow-x-auto scrollbar-hide">
-            {filterOptions.map((option) => (
-              <button
-                key={option.value}
-                onClick={() => setFilter(option.value)}
-                className={cn(
-                  'px-3 sm:px-4 py-2 sm:py-3 text-xs sm:text-sm font-medium border-b-2 transition-colors whitespace-nowrap',
-                  filter === option.value
-                    ? 'border-blue-600 text-blue-600 dark:text-blue-400'
-                    : 'border-transparent text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200 hover:border-gray-300'
-                )}
-              >
-                {option.label}
-                {!isLoading && (
-                  <span className="ml-2 text-xs">
-                    ({option.value === 'all'
-                      ? requests.length
-                      : option.value === 'active'
-                      ? requests.filter((r: any) => ['pending', 'searching', 'downloading', 'processing'].includes(r.status)).length
-                      : option.value === 'waiting'
-                      ? requests.filter((r: any) => ['awaiting_search', 'awaiting_import'].includes(r.status)).length
-                      : option.value === 'completed'
-                      ? requests.filter((r: any) => ['available', 'downloaded'].includes(r.status)).length
-                      : requests.filter((r: any) => r.status === option.value).length
-                    })
-                  </span>
-                )}
-              </button>
-            ))}
-          </div>
+        {/* Tab bar */}
+        <div className="mb-5">
+          <TabBar
+            filter={filter}
+            counts={counts}
+            countsLoaded={countsLoaded}
+            onChange={handleFilterChange}
+          />
         </div>
 
-        {/* Loading State */}
+        {/* Showing bar */}
+        {!isLoading && requests.length > 0 && (
+          <div className="mb-4">
+            <ShowingBar
+              showing={requests.length}
+              total={totalForFilter}
+              hasActive={hasActiveRequests}
+            />
+          </div>
+        )}
+
+        {/* Loading state — skeleton cards */}
         {isLoading && (
-          <div className="space-y-4">
-            {[1, 2, 3].map((i) => (
+          <div className="space-y-3">
+            {Array.from({ length: 4 }).map((_, i) => (
               <div
                 key={i}
-                className="bg-white dark:bg-gray-800 rounded-lg shadow-md p-4 animate-pulse"
+                style={{ animationDelay: `${i * 60}ms` }}
+                className="animate-[fadeIn_0.3s_ease-out_both]"
               >
-                <div className="flex gap-4">
-                  <div className={cn(
-                    'w-24 bg-gray-300 dark:bg-gray-700 rounded',
-                    squareCovers ? 'aspect-square' : 'aspect-[2/3]'
-                  )}></div>
-                  <div className="flex-1 space-y-3">
-                    <div className="h-6 bg-gray-300 dark:bg-gray-700 rounded w-3/4"></div>
-                    <div className="h-4 bg-gray-300 dark:bg-gray-700 rounded w-1/2"></div>
-                    <div className="h-6 bg-gray-300 dark:bg-gray-700 rounded w-24"></div>
-                  </div>
-                </div>
+                <SkeletonCard />
               </div>
             ))}
           </div>
         )}
 
-        {/* Requests List */}
-        {!isLoading && filteredRequests.length > 0 && (
-          <div className="space-y-4">
-            {filteredRequests.map((request: any) => (
-              <RequestCard key={request.id} request={request} showActions={true} />
+        {/* Request list */}
+        {!isLoading && requests.length > 0 && (
+          <div className="space-y-3">
+            {requests.map((request, i) => (
+              <div
+                key={request.id}
+                style={{ animationDelay: `${Math.min(i, 8) * 40}ms` }}
+                className="animate-[fadeInUp_0.25s_ease-out_both]"
+              >
+                <RequestCard request={request} showActions={true} />
+              </div>
             ))}
           </div>
         )}
 
-        {/* Empty State */}
-        {!isLoading && filteredRequests.length === 0 && (
-          <div className="text-center py-16 space-y-4">
-            <svg
-              className="mx-auto h-16 w-16 text-gray-400"
-              fill="none"
-              stroke="currentColor"
-              viewBox="0 0 24 24"
-            >
-              <path
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                strokeWidth={2}
-                d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
-              />
-            </svg>
-            <div className="space-y-2">
-              <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100">
-                {filter === 'all' ? 'No requests yet' : `No ${filter} requests`}
-              </h2>
-              <p className="text-gray-600 dark:text-gray-400">
-                {filter === 'all'
-                  ? 'Start by searching for audiobooks and requesting them'
-                  : `You don't have any ${filter} requests at the moment`
-                }
-              </p>
-            </div>
-            {filter === 'all' && (
-              <div className="pt-4">
-                <a
-                  href="/search"
-                  className="inline-flex items-center gap-2 px-6 py-3 bg-blue-600 text-white font-medium rounded-lg hover:bg-blue-700 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="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
-                    />
-                  </svg>
-                  Search Audiobooks
-                </a>
-              </div>
-            )}
+        {/* Empty state */}
+        {!isLoading && isEmpty && (
+          <EmptyState filter={filter} />
+        )}
+
+        {/* Load more */}
+        {!isLoading && hasMore && (
+          <div className="mt-4">
+            <LoadMoreButton onClick={loadMore} isLoading={isLoadingMore} />
           </div>
         )}
 
-        {/* Auto-refresh indicator */}
-        {!isLoading && filteredRequests.length > 0 && (
-          <div className="text-center text-xs text-gray-500 dark:text-gray-500 py-4">
-            <div className="flex items-center justify-center gap-2">
-              <div className="w-2 h-2 bg-green-500 rounded-full animate-pulse"></div>
-              <span>Auto-refreshing every 5 seconds</span>
-            </div>
+        {/* Load more skeleton (when fetching additional pages) */}
+        {isLoadingMore && (
+          <div className="mt-3 space-y-3">
+            {Array.from({ length: 2 }).map((_, i) => (
+              <SkeletonCard key={`more-${i}`} />
+            ))}
           </div>
         )}
+
       </main>
     </div>
   );

src/app/setup/steps/OIDCConfigStep.tsx

@@ -272,7 +272,7 @@ export function OIDCConfigStep({
               <ul className="text-sm text-blue-700 dark:text-blue-300 mt-1 space-y-1">
                 <li>• The redirect URI will be: {typeof window !== 'undefined' ? `${window.location.origin}/api/auth/oidc/callback` : '[Your Domain]/api/auth/oidc/callback'}</li>
                 <li>• Configure this redirect URI in your OIDC provider settings</li>
-                <li>• Required scopes: openid, profile, email, groups</li>
+                <li>• Required scopes: openid, profile, email (groups is added automatically when group-based access control is enabled)</li>
               </ul>
             </div>
           </div>

src/components/admin/BulkImportWizard.tsx

@@ -0,0 +1,348 @@
+/**
+ * Component: Bulk Import Wizard
+ * Documentation: documentation/features/bulk-import.md
+ *
+ * Multi-step modal wizard for bulk importing audiobooks from server folders.
+ * Step 1: Select root folder to scan.
+ * Step 2: Scanning/matching progress.
+ * Step 3: Review matches and start import.
+ */
+
+'use client';
+
+import React, { useState, useCallback, useRef } from 'react';
+import { createPortal } from 'react-dom';
+import { XMarkIcon, FolderArrowDownIcon } from '@heroicons/react/24/outline';
+import { ScanFolderStep } from './bulk-import/ScanFolderStep';
+import { ScanProgressStep } from './bulk-import/ScanProgressStep';
+import { MatchReviewStep } from './bulk-import/MatchReviewStep';
+import { WizardStep, ScannedBook, ScanProgressEvent, MatchingProgressEvent } from './bulk-import/types';
+import { fetchWithAuth } from '@/lib/utils/api';
+
+interface BulkImportWizardProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+const STEP_LABELS: Record<WizardStep, string> = {
+  select_folder: 'Select Folder',
+  scanning: 'Scanning',
+  review: 'Review & Import',
+};
+
+const STEP_ORDER: WizardStep[] = ['select_folder', 'scanning', 'review'];
+
+export function BulkImportWizard({ isOpen, onClose }: BulkImportWizardProps) {
+  const [step, setStep] = useState<WizardStep>('select_folder');
+  const [selectedRootPath, setSelectedRootPath] = useState<string | null>(null);
+
+  // Scanning state
+  const [scanProgress, setScanProgress] = useState<ScanProgressEvent | null>(null);
+  const [matchingProgress, setMatchingProgress] = useState<MatchingProgressEvent | null>(null);
+  const [scanPhase, setScanPhase] = useState<'discovering' | 'matching' | 'idle'>('idle');
+  const abortRef = useRef<AbortController | null>(null);
+
+  // Results state
+  const [scannedBooks, setScannedBooks] = useState<ScannedBook[]>([]);
+  const [scanError, setScanError] = useState<string | null>(null);
+
+  // Import state
+  const [isImporting, setIsImporting] = useState(false);
+  const [importResults, setImportResults] = useState<any>(null);
+
+  const resetWizard = useCallback(() => {
+    setStep('select_folder');
+    setSelectedRootPath(null);
+    setScanProgress(null);
+    setMatchingProgress(null);
+    setScanPhase('idle');
+    setScannedBooks([]);
+    setScanError(null);
+    setIsImporting(false);
+    setImportResults(null);
+    if (abortRef.current) {
+      abortRef.current.abort();
+      abortRef.current = null;
+    }
+  }, []);
+
+  const handleClose = useCallback(() => {
+    if (abortRef.current) {
+      abortRef.current.abort();
+      abortRef.current = null;
+    }
+    resetWizard();
+    onClose();
+  }, [onClose, resetWizard]);
+
+  const handleFolderSelected = useCallback(async (rootPath: string) => {
+    setSelectedRootPath(rootPath);
+    setStep('scanning');
+    setScanPhase('discovering');
+    setScanError(null);
+    setScannedBooks([]);
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    try {
+      const response = await fetchWithAuth('/api/admin/bulk-import/scan', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ rootPath }),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        const errData = await response.json().catch(() => ({ error: 'Scan failed' }));
+        throw new Error(errData.error || 'Scan failed');
+      }
+
+      const reader = response.body?.getReader();
+      if (!reader) throw new Error('No response stream');
+
+      const decoder = new TextDecoder();
+      let buffer = '';
+      let eventType = '';
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+
+        // Parse SSE events from buffer
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+
+        for (const line of lines) {
+          if (line.startsWith('event: ')) {
+            eventType = line.slice(7).trim();
+          } else if (line.startsWith('data: ') && eventType) {
+            try {
+              const data = JSON.parse(line.slice(6));
+              handleSSEEvent(eventType, data);
+            } catch {
+              /* ignore parse errors */
+            }
+            eventType = '';
+          }
+        }
+      }
+    } catch (error) {
+      if (controller.signal.aborted) return;
+      setScanError(error instanceof Error ? error.message : 'Scan failed');
+      setScanPhase('idle');
+    }
+  }, []);
+
+  const handleSSEEvent = useCallback((event: string, data: any) => {
+    switch (event) {
+      case 'progress':
+        setScanProgress(data);
+        break;
+
+      case 'discovery_complete':
+        setScanPhase('matching');
+        break;
+
+      case 'matching':
+        setMatchingProgress(data);
+        break;
+
+      case 'book_matched': {
+        const book: ScannedBook = {
+          ...data,
+          skipped: data.inLibrary || data.hasActiveRequest || data.match === null,
+        };
+        setScannedBooks((prev) => [...prev, book]);
+        break;
+      }
+
+      case 'complete':
+        setScanPhase('idle');
+        setStep('review');
+        break;
+
+      case 'error':
+        setScanError(data.message || 'Scan failed');
+        setScanPhase('idle');
+        break;
+    }
+  }, []);
+
+  const handleCancelScan = useCallback(() => {
+    if (abortRef.current) {
+      abortRef.current.abort();
+      abortRef.current = null;
+    }
+    setScanPhase('idle');
+    setStep('select_folder');
+  }, []);
+
+  const handleToggleSkip = useCallback((index: number) => {
+    setScannedBooks((prev) =>
+      prev.map((book) =>
+        book.index === index ? { ...book, skipped: !book.skipped } : book
+      )
+    );
+  }, []);
+
+  const handleStartImport = useCallback(async () => {
+    const booksToImport = scannedBooks.filter(
+      (b) => !b.skipped && b.match !== null
+    );
+
+    if (booksToImport.length === 0) return;
+
+    setIsImporting(true);
+
+    try {
+      const response = await fetchWithAuth('/api/admin/bulk-import/execute', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          imports: booksToImport.map((b) => ({
+            folderPath: b.folderPath,
+            asin: b.match!.asin,
+          })),
+        }),
+      });
+
+      const data = await response.json();
+
+      if (!response.ok) {
+        throw new Error(data.error || 'Import failed');
+      }
+
+      setImportResults(data);
+    } catch (error) {
+      setImportResults({
+        success: false,
+        error: error instanceof Error ? error.message : 'Import failed',
+      });
+    } finally {
+      setIsImporting(false);
+    }
+  }, [scannedBooks]);
+
+  const handleBackToFolderSelect = useCallback(() => {
+    setStep('select_folder');
+    setScanError(null);
+    setScannedBooks([]);
+    setScanPhase('idle');
+  }, []);
+
+  if (!isOpen) return null;
+
+  const currentStepIndex = STEP_ORDER.indexOf(step);
+
+  const modalContent = (
+    <div
+      className="fixed inset-0 z-[60] flex items-center justify-center bg-black/60 backdrop-blur-sm"
+      style={{ height: '100dvh' }}
+      onClick={handleClose}
+    >
+      <div
+        className="relative w-full max-w-4xl bg-white dark:bg-gray-900 rounded-2xl shadow-2xl overflow-hidden flex flex-col"
+        style={{ height: 'min(720px, 90vh)' }}
+        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">
+              Bulk Import
+            </h2>
+          </div>
+          <button
+            onClick={handleClose}
+            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>
+
+        {/* Step Indicator */}
+        <div className="flex items-center justify-center gap-2 px-5 py-3 bg-gray-50 dark:bg-gray-800/50 border-b border-gray-200 dark:border-gray-700/50">
+          {STEP_ORDER.map((s, i) => (
+            <React.Fragment key={s}>
+              {i > 0 && (
+                <div
+                  className={`w-8 h-px ${
+                    i <= currentStepIndex
+                      ? 'bg-blue-400 dark:bg-blue-500'
+                      : 'bg-gray-300 dark:bg-gray-600'
+                  }`}
+                />
+              )}
+              <div className="flex items-center gap-1.5">
+                <div
+                  className={`w-6 h-6 rounded-full flex items-center justify-center text-xs font-medium ${
+                    i < currentStepIndex
+                      ? 'bg-blue-600 text-white'
+                      : i === currentStepIndex
+                      ? 'bg-blue-600 text-white ring-2 ring-blue-200 dark:ring-blue-800'
+                      : 'bg-gray-200 dark:bg-gray-700 text-gray-500 dark:text-gray-400'
+                  }`}
+                >
+                  {i < currentStepIndex ? (
+                    <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5} d="M5 13l4 4L19 7" />
+                    </svg>
+                  ) : (
+                    i + 1
+                  )}
+                </div>
+                <span
+                  className={`text-xs font-medium hidden sm:inline ${
+                    i <= currentStepIndex
+                      ? 'text-gray-900 dark:text-gray-100'
+                      : 'text-gray-400 dark:text-gray-500'
+                  }`}
+                >
+                  {STEP_LABELS[s]}
+                </span>
+              </div>
+            </React.Fragment>
+          ))}
+        </div>
+
+        {/* Content */}
+        <div className="flex-1 min-h-0 overflow-hidden">
+          {step === 'select_folder' && (
+            <ScanFolderStep onFolderSelected={handleFolderSelected} />
+          )}
+
+          {step === 'scanning' && (
+            <ScanProgressStep
+              scanProgress={scanProgress}
+              matchingProgress={matchingProgress}
+              scanPhase={scanPhase}
+              error={scanError}
+              booksFound={scannedBooks.length}
+              onCancel={handleCancelScan}
+              onRetry={() => selectedRootPath && handleFolderSelected(selectedRootPath)}
+              onBack={handleBackToFolderSelect}
+            />
+          )}
+
+          {step === 'review' && (
+            <MatchReviewStep
+              books={scannedBooks}
+              onToggleSkip={handleToggleSkip}
+              onStartImport={handleStartImport}
+              isImporting={isImporting}
+              importResults={importResults}
+              onClose={handleClose}
+              onBack={handleBackToFolderSelect}
+            />
+          )}
+        </div>
+      </div>
+    </div>
+  );
+
+  return createPortal(modalContent, document.body);
+}

src/components/admin/bulk-import/MatchReviewStep.tsx

@@ -0,0 +1,344 @@
+/**
+ * Component: Bulk Import - Match Review Step
+ * Documentation: documentation/features/bulk-import.md
+ *
+ * Scrollable list of discovered audiobooks with Audible matches,
+ * skip toggles, library status badges, and import controls.
+ */
+
+'use client';
+
+import React from 'react';
+import {
+  ArrowLeftIcon,
+  CheckCircleIcon,
+  ExclamationTriangleIcon,
+  MusicalNoteIcon,
+  XCircleIcon,
+} from '@heroicons/react/24/outline';
+import { CheckCircleIcon as CheckCircleSolid } from '@heroicons/react/24/solid';
+import { ScannedBook, formatBytes } from './types';
+
+interface MatchReviewStepProps {
+  books: ScannedBook[];
+  onToggleSkip: (index: number) => void;
+  onStartImport: () => void;
+  isImporting: boolean;
+  importResults: any;
+  onClose: () => void;
+  onBack: () => void;
+}
+
+function BookRow({
+  book,
+  onToggleSkip,
+}: {
+  book: ScannedBook;
+  onToggleSkip: () => void;
+}) {
+  const isDisabled = book.inLibrary || book.hasActiveRequest;
+  const isSkipped = book.skipped;
+  const hasMatch = book.match !== null;
+  const isLowConfidence = book.metadataSource === 'file_name';
+
+  return (
+    <div
+      className={`flex items-center gap-3 px-4 py-3 transition-opacity ${
+        isSkipped ? 'opacity-40' : ''
+      }`}
+    >
+      {/* Cover Art */}
+      <div className="flex-shrink-0 w-12 h-12 rounded-lg overflow-hidden bg-gray-100 dark:bg-gray-800">
+        {hasMatch && book.match!.coverArtUrl ? (
+          /* eslint-disable-next-line @next/next/no-img-element */
+          <img
+            src={book.match!.coverArtUrl}
+            alt={book.match!.title}
+            className="w-12 h-12 object-cover"
+            onError={(e) => {
+              (e.target as HTMLImageElement).src = '/placeholder_cover.svg';
+            }}
+          />
+        ) : (
+          <div className="w-12 h-12 flex items-center justify-center">
+            <MusicalNoteIcon className="w-6 h-6 text-gray-400 dark:text-gray-600" />
+          </div>
+        )}
+      </div>
+
+      {/* Book Info */}
+      <div className="flex-1 min-w-0">
+        {hasMatch ? (
+          <>
+            <div className="flex items-center gap-2 flex-wrap">
+              <p className="text-sm font-semibold text-gray-900 dark:text-gray-100 truncate">
+                {book.match!.title}
+              </p>
+              {isLowConfidence && (
+                <span className="inline-flex items-center px-1.5 py-0.5 rounded text-[10px] font-medium bg-amber-100 dark:bg-amber-900/30 text-amber-700 dark:text-amber-300 flex-shrink-0">
+                  Low Confidence
+                </span>
+              )}
+            </div>
+            <p className="text-xs text-gray-600 dark:text-gray-400 truncate">
+              {book.match!.author}
+              {book.match!.narrator && (
+                <span className="text-gray-400 dark:text-gray-500">
+                  {' '}&middot; {book.match!.narrator}
+                </span>
+              )}
+            </p>
+          </>
+        ) : (
+          <>
+            <div className="flex items-center gap-2">
+              <p className="text-sm font-semibold text-gray-900 dark:text-gray-100 truncate">
+                {book.folderName}
+              </p>
+              <span className="inline-flex items-center px-1.5 py-0.5 rounded text-[10px] font-medium bg-red-100 dark:bg-red-900/30 text-red-700 dark:text-red-300 flex-shrink-0">
+                No Match
+              </span>
+            </div>
+            <p className="text-xs text-gray-500 dark:text-gray-400 italic">
+              Could not find this title on Audible
+            </p>
+          </>
+        )}
+        <p className="text-[11px] text-gray-400 dark:text-gray-500 font-mono truncate mt-0.5">
+          {book.relativePath}
+        </p>
+      </div>
+
+      {/* Badges */}
+      <div className="flex items-center gap-2 flex-shrink-0">
+        {/* Audio file count */}
+        <span className="inline-flex items-center gap-1 px-2 py-0.5 rounded-full bg-blue-50 dark:bg-blue-900/20 text-blue-700 dark:text-blue-300 text-xs font-medium">
+          <MusicalNoteIcon className="w-3 h-3" />
+          {book.audioFileCount}
+        </span>
+
+        {/* Status badges */}
+        {book.inLibrary && (
+          <span className="inline-flex items-center gap-1 px-2 py-0.5 rounded-full bg-green-100 dark:bg-green-900/30 text-green-700 dark:text-green-300 text-xs font-medium">
+            <CheckCircleSolid className="w-3 h-3" />
+            In Library
+          </span>
+        )}
+        {book.hasActiveRequest && !book.inLibrary && (
+          <span className="inline-flex items-center gap-1 px-2 py-0.5 rounded-full bg-purple-100 dark:bg-purple-900/30 text-purple-700 dark:text-purple-300 text-xs font-medium">
+            Requested
+          </span>
+        )}
+      </div>
+
+      {/* Skip Toggle */}
+      <button
+        onClick={onToggleSkip}
+        disabled={isDisabled}
+        className={`flex-shrink-0 relative inline-flex h-6 w-11 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-900 ${
+          isDisabled
+            ? 'cursor-not-allowed opacity-50'
+            : 'cursor-pointer'
+        } ${
+          isSkipped
+            ? 'bg-gray-200 dark:bg-gray-700'
+            : 'bg-blue-600'
+        }`}
+        title={
+          isDisabled
+            ? book.inLibrary
+              ? 'Already in your library'
+              : 'Already requested'
+            : isSkipped
+            ? 'Click to include in import'
+            : 'Click to skip this book'
+        }
+      >
+        <span
+          className={`inline-block h-4 w-4 transform rounded-full bg-white shadow-sm transition-transform ${
+            isSkipped ? 'translate-x-1' : 'translate-x-6'
+          }`}
+        />
+      </button>
+    </div>
+  );
+}
+
+export function MatchReviewStep({
+  books,
+  onToggleSkip,
+  onStartImport,
+  isImporting,
+  importResults,
+  onClose,
+  onBack,
+}: MatchReviewStepProps) {
+  const toImport = books.filter((b) => !b.skipped && b.match !== null);
+  const skippedCount = books.filter((b) => b.skipped).length;
+  const inLibraryCount = books.filter((b) => b.inLibrary).length;
+  const noMatchCount = books.filter((b) => b.match === null).length;
+  const matchedCount = books.filter((b) => b.match !== null).length;
+
+  // Import completed state
+  if (importResults) {
+    const succeeded = importResults.summary?.succeeded || 0;
+    const failed = importResults.summary?.failed || 0;
+
+    return (
+      <div className="flex flex-col items-center justify-center h-full px-6 py-16">
+        {importResults.success !== false ? (
+          <>
+            <CheckCircleSolid className="w-14 h-14 text-green-500 mb-4" />
+            <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-2">
+              Import Started
+            </h3>
+            <p className="text-sm text-gray-600 dark:text-gray-400 text-center mb-2">
+              {succeeded} audiobook{succeeded !== 1 ? 's' : ''} queued for import.
+            </p>
+            {failed > 0 && (
+              <p className="text-sm text-amber-600 dark:text-amber-400 text-center mb-2">
+                {failed} book{failed !== 1 ? 's' : ''} could not be queued.
+              </p>
+            )}
+            <p className="text-xs text-gray-500 dark:text-gray-400 text-center max-w-sm">
+              Files will be organized, tagged, and imported into your library. Check the admin
+              dashboard for progress.
+            </p>
+            <button
+              onClick={onClose}
+              className="mt-6 px-6 py-2.5 bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium rounded-xl transition-colors"
+            >
+              Done
+            </button>
+          </>
+        ) : (
+          <>
+            <XCircleIcon className="w-14 h-14 text-red-500 mb-4" />
+            <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-2">
+              Import Failed
+            </h3>
+            <p className="text-sm text-gray-600 dark:text-gray-400 text-center mb-6">
+              {importResults.error || 'An unexpected error occurred'}
+            </p>
+            <button
+              onClick={onClose}
+              className="px-6 py-2.5 bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 text-gray-900 dark:text-gray-100 text-sm font-medium rounded-xl transition-colors"
+            >
+              Close
+            </button>
+          </>
+        )}
+      </div>
+    );
+  }
+
+  // Empty state (no audiobooks found)
+  if (books.length === 0) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full px-6 py-16">
+        <ExclamationTriangleIcon className="w-12 h-12 text-gray-300 dark:text-gray-600 mb-4" />
+        <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-2">
+          No Audiobooks Found
+        </h3>
+        <p className="text-sm text-gray-500 dark:text-gray-400 text-center max-w-sm mb-6">
+          The selected folder does not contain any folders with audio files. Try selecting a
+          different folder.
+        </p>
+        <button
+          onClick={onBack}
+          className="flex items-center gap-2 px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-xl transition-colors"
+        >
+          <ArrowLeftIcon className="w-4 h-4" />
+          Select Different Folder
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Summary header */}
+      <div className="px-5 py-3 bg-gray-50 dark:bg-gray-800/50 border-b border-gray-200 dark:border-gray-700/50">
+        <div className="flex items-center gap-4 text-xs">
+          <span className="text-gray-500 dark:text-gray-400">
+            <span className="font-semibold text-gray-900 dark:text-gray-100">{books.length}</span> discovered
+          </span>
+          <span className="text-gray-300 dark:text-gray-600">&middot;</span>
+          <span className="text-gray-500 dark:text-gray-400">
+            <span className="font-semibold text-blue-600 dark:text-blue-400">{matchedCount}</span> matched
+          </span>
+          {noMatchCount > 0 && (
+            <>
+              <span className="text-gray-300 dark:text-gray-600">&middot;</span>
+              <span className="text-gray-500 dark:text-gray-400">
+                <span className="font-semibold text-red-600 dark:text-red-400">{noMatchCount}</span> unmatched
+              </span>
+            </>
+          )}
+          {inLibraryCount > 0 && (
+            <>
+              <span className="text-gray-300 dark:text-gray-600">&middot;</span>
+              <span className="text-gray-500 dark:text-gray-400">
+                <span className="font-semibold text-green-600 dark:text-green-400">{inLibraryCount}</span> in library
+              </span>
+            </>
+          )}
+        </div>
+      </div>
+
+      {/* Scrollable book list */}
+      <div className="flex-1 overflow-y-auto divide-y divide-gray-100 dark:divide-gray-800">
+        {books.map((book) => (
+          <BookRow
+            key={book.index}
+            book={book}
+            onToggleSkip={() => onToggleSkip(book.index)}
+          />
+        ))}
+      </div>
+
+      {/* Import 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-4">
+        <button
+          onClick={onBack}
+          className="flex items-center gap-2 px-4 py-2 text-sm font-medium text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 transition-colors"
+        >
+          <ArrowLeftIcon className="w-4 h-4" />
+          Back
+        </button>
+
+        <div className="flex items-center gap-3">
+          <span className="text-sm text-gray-600 dark:text-gray-400">
+            <span className="font-semibold text-gray-900 dark:text-gray-100">
+              {toImport.length}
+            </span>{' '}
+            book{toImport.length !== 1 ? 's' : ''} to import
+            {skippedCount > 0 && (
+              <span className="text-gray-400 dark:text-gray-500">
+                {' '}({skippedCount} skipped)
+              </span>
+            )}
+          </span>
+
+          <button
+            onClick={onStartImport}
+            disabled={toImport.length === 0 || isImporting}
+            className="flex items-center gap-2 px-5 py-2.5 bg-blue-600 hover:bg-blue-700 disabled:bg-blue-400 disabled:cursor-not-allowed text-white text-sm font-medium rounded-xl transition-colors"
+          >
+            {isImporting ? (
+              <>
+                <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>
+                Importing...
+              </>
+            ) : (
+              <>Start Import</>
+            )}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/admin/bulk-import/ScanFolderStep.tsx

@@ -0,0 +1,346 @@
+/**
+ * Component: Bulk Import - Folder Selection Step
+ * Documentation: documentation/features/bulk-import.md
+ *
+ * Filesystem browser for selecting a root folder to scan for audiobooks.
+ * Adapted from the manual import BrowsePhase patterns.
+ * Any folder is selectable (not just audio-containing folders).
+ */
+
+'use client';
+
+import React, { useState, useEffect, useCallback } from 'react';
+import {
+  FolderIcon,
+  FolderOpenIcon,
+  FolderArrowDownIcon,
+  InboxArrowDownIcon,
+  HomeIcon,
+  ChevronRightIcon,
+  ArrowLeftIcon,
+  MusicalNoteIcon,
+  ExclamationTriangleIcon,
+  ArrowPathIcon,
+  MagnifyingGlassIcon,
+} from '@heroicons/react/24/outline';
+import { fetchWithAuth } from '@/lib/utils/api';
+import { RootEntry, DirectoryEntry, 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 ScanFolderStepProps {
+  onFolderSelected: (rootPath: string) => void;
+}
+
+export function ScanFolderStep({ onFolderSelected }: ScanFolderStepProps) {
+  const [roots, setRoots] = useState<RootEntry[]>([]);
+  const [currentPath, setCurrentPath] = useState<string | null>(null);
+  const [entries, setEntries] = useState<DirectoryEntry[]>([]);
+  const [pathHistory, setPathHistory] = useState<string[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [hoveredFolder, setHoveredFolder] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetchRoots();
+  }, []);
+
+  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 || []);
+      setCurrentPath(data.path || dirPath);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to browse directory');
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  const navigateInto = (dirPath: string) => {
+    if (currentPath) {
+      setPathHistory((prev) => [...prev, currentPath]);
+    }
+    fetchDirectory(dirPath);
+  };
+
+  const navigateBack = () => {
+    if (pathHistory.length > 0) {
+      const prevPath = pathHistory[pathHistory.length - 1];
+      setPathHistory((prev) => prev.slice(0, -1));
+      fetchDirectory(prevPath);
+    } else {
+      setCurrentPath(null);
+      setEntries([]);
+    }
+  };
+
+  const navigateToRoot = () => {
+    setCurrentPath(null);
+    setEntries([]);
+    setPathHistory([]);
+  };
+
+  const navigateToBreadcrumb = (index: number) => {
+    if (!currentPath) return;
+    const allPaths = [...pathHistory, currentPath];
+    const targetPath = allPaths[index];
+    if (targetPath) {
+      setPathHistory(allPaths.slice(0, index));
+      fetchDirectory(targetPath);
+    } else {
+      navigateToRoot();
+    }
+  };
+
+  // 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 },
+    ];
+  })();
+
+  // Count total audio files and subfolders in current listing
+  const totalSubfolders = entries.reduce((sum, e) => sum + e.subfolderCount, 0);
+  const totalAudioInChildren = entries.reduce((sum, e) => sum + e.audioFileCount, 0);
+
+  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={navigateToRoot}
+            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>
+          {visibleBreadcrumbs.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 === visibleBreadcrumbs.length - 1 ? (
+                <span className="font-medium text-gray-900 dark:text-gray-100 truncate">
+                  {crumb.label}
+                </span>
+              ) : (
+                <button
+                  onClick={() => navigateToBreadcrumb(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">
+        {/* 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={currentPath ? () => fetchDirectory(currentPath) : fetchRoots}
+              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">
+            <p className="text-sm text-gray-500 dark:text-gray-400 mb-4">
+              Select a folder to scan for audiobooks. All subfolders will be searched recursively.
+            </p>
+            <div className="grid grid-cols-2 gap-3">
+              {roots.map((root) => (
+                <button
+                  key={root.path}
+                  onClick={() => navigateInto(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>
+          </div>
+        )}
+
+        {/* Directory listing */}
+        {currentPath && !isLoading && !error && entries.length > 0 && (
+          <div className="divide-y divide-gray-100 dark:divide-gray-800">
+            {entries.map((entry) => {
+              const hasAudio = entry.audioFileCount > 0;
+              const isHovered = hoveredFolder === entry.name;
+
+              return (
+                <button
+                  key={`dir-${entry.name}`}
+                  onClick={() => navigateInto(currentPath + '/' + entry.name)}
+                  onMouseEnter={() => setHoveredFolder(entry.name)}
+                  onMouseLeave={() => setHoveredFolder(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>
+              );
+            })}
+          </div>
+        )}
+
+        {/* Empty state */}
+        {currentPath && !isLoading && !error && entries.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={navigateBack}
+              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: Scan this folder */}
+      {currentPath && !isLoading && (
+        <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">
+          <div className="text-sm text-gray-600 dark:text-gray-400 min-w-0">
+            <p className="font-mono text-xs text-gray-500 dark:text-gray-500 truncate">{currentPath}</p>
+            {entries.length > 0 && (
+              <p className="mt-0.5">
+                {entries.length} subfolder{entries.length !== 1 ? 's' : ''}
+                {totalAudioInChildren > 0 && (
+                  <span> &middot; {totalAudioInChildren} audio files visible</span>
+                )}
+              </p>
+            )}
+          </div>
+          <button
+            onClick={() => onFolderSelected(currentPath)}
+            className="flex-shrink-0 flex items-center gap-2 px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium rounded-xl transition-colors"
+          >
+            <MagnifyingGlassIcon className="w-4 h-4" />
+            Scan for Audiobooks
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

src/components/admin/bulk-import/ScanProgressStep.tsx

@@ -0,0 +1,179 @@
+/**
+ * Component: Bulk Import - Scan Progress Step
+ * Documentation: documentation/features/bulk-import.md
+ *
+ * Displays progress during folder discovery and Audible matching phases.
+ * Shows animated indicators, counts, and cancel/retry controls.
+ */
+
+'use client';
+
+import React from 'react';
+import {
+  FolderIcon,
+  ExclamationTriangleIcon,
+  ArrowPathIcon,
+  ArrowLeftIcon,
+  XMarkIcon,
+} from '@heroicons/react/24/outline';
+import { ScanProgressEvent, MatchingProgressEvent } from './types';
+
+interface ScanProgressStepProps {
+  scanProgress: ScanProgressEvent | null;
+  matchingProgress: MatchingProgressEvent | null;
+  scanPhase: 'discovering' | 'matching' | 'idle';
+  error: string | null;
+  booksFound: number;
+  onCancel: () => void;
+  onRetry: () => void;
+  onBack: () => void;
+}
+
+export function ScanProgressStep({
+  scanProgress,
+  matchingProgress,
+  scanPhase,
+  error,
+  booksFound,
+  onCancel,
+  onRetry,
+  onBack,
+}: ScanProgressStepProps) {
+  // Error state
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full px-6 py-16">
+        <ExclamationTriangleIcon className="w-12 h-12 text-red-400 mb-4" />
+        <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-2">
+          Scan Failed
+        </h3>
+        <p className="text-sm text-gray-600 dark:text-gray-400 text-center max-w-md mb-6">
+          {error}
+        </p>
+        <div className="flex items-center gap-3">
+          <button
+            onClick={onBack}
+            className="flex items-center gap-2 px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-xl transition-colors"
+          >
+            <ArrowLeftIcon className="w-4 h-4" />
+            Go Back
+          </button>
+          <button
+            onClick={onRetry}
+            className="flex items-center gap-2 px-4 py-2 text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 rounded-xl transition-colors"
+          >
+            <ArrowPathIcon className="w-4 h-4" />
+            Retry Scan
+          </button>
+        </div>
+      </div>
+    );
+  }
+
+  const matchPercent = matchingProgress
+    ? Math.round((matchingProgress.current / matchingProgress.total) * 100)
+    : 0;
+
+  return (
+    <div className="flex flex-col items-center justify-center h-full px-6 py-16">
+      {/* Animated icon */}
+      <div className="relative mb-6">
+        <div className="w-16 h-16 rounded-full border-4 border-blue-200 dark:border-blue-800 flex items-center justify-center">
+          <FolderIcon className="w-8 h-8 text-blue-600 dark:text-blue-400" />
+        </div>
+        <div className="absolute inset-0 w-16 h-16 rounded-full border-4 border-transparent border-t-blue-600 dark:border-t-blue-400 animate-spin" />
+      </div>
+
+      {/* Phase-specific content */}
+      {scanPhase === 'discovering' && (
+        <>
+          <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-2">
+            Scanning Folders
+          </h3>
+          <p className="text-sm text-gray-600 dark:text-gray-400 text-center mb-4">
+            Searching for folders containing audiobook files...
+          </p>
+
+          {scanProgress && (
+            <div className="flex items-center gap-6 text-sm">
+              <div className="text-center">
+                <div className="text-2xl font-bold text-gray-900 dark:text-gray-100">
+                  {scanProgress.foldersScanned}
+                </div>
+                <div className="text-xs text-gray-500 dark:text-gray-400">
+                  Folders Scanned
+                </div>
+              </div>
+              <div className="w-px h-8 bg-gray-200 dark:bg-gray-700" />
+              <div className="text-center">
+                <div className="text-2xl font-bold text-blue-600 dark:text-blue-400">
+                  {scanProgress.audiobooksFound}
+                </div>
+                <div className="text-xs text-gray-500 dark:text-gray-400">
+                  Audiobooks Found
+                </div>
+              </div>
+            </div>
+          )}
+
+          {scanProgress?.currentFolder && (
+            <p className="mt-4 text-xs text-gray-400 dark:text-gray-500 font-mono truncate max-w-md">
+              {scanProgress.currentFolder}
+            </p>
+          )}
+        </>
+      )}
+
+      {scanPhase === 'matching' && (
+        <>
+          <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-2">
+            Matching Against Audible
+          </h3>
+          <p className="text-sm text-gray-600 dark:text-gray-400 text-center mb-6">
+            Searching Audible for each discovered audiobook...
+          </p>
+
+          {matchingProgress && (
+            <>
+              {/* Progress bar */}
+              <div className="w-full max-w-sm mb-3">
+                <div className="h-2 bg-gray-200 dark:bg-gray-700 rounded-full overflow-hidden">
+                  <div
+                    className="h-full bg-blue-600 dark:bg-blue-500 rounded-full transition-all duration-500"
+                    style={{ width: `${matchPercent}%` }}
+                  />
+                </div>
+              </div>
+
+              <div className="text-sm text-gray-700 dark:text-gray-300 font-medium">
+                {matchingProgress.current} / {matchingProgress.total}
+              </div>
+
+              {matchingProgress.folderName && (
+                <p className="mt-2 text-xs text-gray-400 dark:text-gray-500 truncate max-w-md">
+                  {matchingProgress.folderName}
+                </p>
+              )}
+
+              {/* Books matched so far count */}
+              {booksFound > 0 && (
+                <p className="mt-4 text-xs text-gray-500 dark:text-gray-400">
+                  {booksFound} book{booksFound !== 1 ? 's' : ''} matched so far
+                </p>
+              )}
+            </>
+          )}
+        </>
+      )}
+
+      {/* Cancel button */}
+      <button
+        onClick={onCancel}
+        className="mt-8 flex items-center gap-2 px-4 py-2 text-sm font-medium text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-xl transition-colors"
+      >
+        <XMarkIcon className="w-4 h-4" />
+        Cancel Scan
+      </button>
+    </div>
+  );
+}

src/components/admin/bulk-import/types.ts

@@ -0,0 +1,81 @@
+/**
+ * Component: Bulk Import Shared Types
+ * Documentation: documentation/features/bulk-import.md
+ */
+
+/** Root directory entry from the filesystem browse API. */
+export interface RootEntry {
+  name: string;
+  path: string;
+  icon: string;
+}
+
+/** Directory entry from the filesystem browse API. */
+export interface DirectoryEntry {
+  name: string;
+  type: 'directory';
+  audioFileCount: number;
+  subfolderCount: number;
+  totalSize: number;
+}
+
+/** Audible match data for a discovered audiobook. */
+export interface AudibleMatch {
+  asin: string;
+  title: string;
+  author: string;
+  narrator?: string;
+  coverArtUrl?: string;
+  durationMinutes?: number;
+}
+
+/** A scanned audiobook result with its Audible match status. */
+export interface ScannedBook {
+  index: number;
+  folderPath: string;
+  folderName: string;
+  relativePath: string;
+  audioFileCount: number;
+  totalSizeBytes: number;
+  metadataSource: 'tags' | 'file_name';
+  searchTerm: string;
+  match: AudibleMatch | null;
+  inLibrary: boolean;
+  hasActiveRequest: boolean;
+  /** User toggle: true = skip this book during import. */
+  skipped: boolean;
+}
+
+/** Progress event from the SSE scan stream. */
+export interface ScanProgressEvent {
+  phase: 'discovering' | 'reading_metadata';
+  foldersScanned: number;
+  audiobooksFound: number;
+  currentFolder?: string;
+}
+
+/** Matching progress event from the SSE scan stream. */
+export interface MatchingProgressEvent {
+  current: number;
+  total: number;
+  folderName: string;
+  searchTerm: string;
+}
+
+/** Discovery complete event from the SSE scan stream. */
+export interface DiscoveryCompleteEvent {
+  totalFound: number;
+  message: string;
+}
+
+/** Wizard step identifiers. */
+export type WizardStep = 'select_folder' | 'scanning' | 'review';
+
+/** Format bytes into a human-readable string. */
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+}

src/components/admin/users/UserPermissionsModal.tsx

@@ -6,6 +6,7 @@
 'use client';
 
 import { Modal } from '@/components/ui/Modal';
+import { useToast } from '@/components/ui/Toast';
 
 interface UserPermissionsUser {
   id: string;
@@ -16,6 +17,7 @@ interface UserPermissionsUser {
   autoApproveRequests: boolean | null;
   interactiveSearchAccess: boolean | null;
   downloadAccess: boolean | null;
+  hasLoginToken: boolean;
 }
 
 interface UserPermissionsModalProps {
@@ -25,9 +27,11 @@ interface UserPermissionsModalProps {
   globalAutoApprove: boolean;
   globalInteractiveSearch: boolean;
   globalDownloadAccess: boolean;
+  generatedToken: string | null;
   onToggleAutoApprove: (user: UserPermissionsUser, newValue: boolean) => void;
   onToggleInteractiveSearch: (user: UserPermissionsUser, newValue: boolean) => void;
   onToggleDownloadAccess: (user: UserPermissionsUser, newValue: boolean) => void;
+  onToggleToken: (user: UserPermissionsUser, newValue: boolean) => void;
 }
 
 interface PermissionToggleProps {
@@ -83,6 +87,79 @@ function PermissionToggle({ label, ariaLabel, value, disabled, disabledMessage,
   );
 }
 
+interface LoginTokenRowProps {
+  value: boolean;
+  generatedToken: string | null;
+  onToggle: () => void;
+}
+
+function LoginTokenRow({ value, generatedToken, onToggle }: LoginTokenRowProps) {
+  const toast = useToast();
+  const loginUrl = generatedToken
+      ? `${typeof window !== 'undefined' ? window.location.origin : ''}/auth/token/login?token=${generatedToken}`
+      : null;
+
+  const copyUrl = async () => {
+    if (!loginUrl) return;
+    try {
+      await navigator.clipboard.writeText(loginUrl);
+    } catch {
+      toast.error('Failed to copy to clipboard');
+    }
+  };
+
+  return (
+      <div className="flex flex-col gap-2 p-3 border border-gray-200 dark:border-gray-700 rounded-lg">
+        <div className="flex items-start gap-4">
+          <button
+              onClick={onToggle}
+              className="relative inline-flex h-5 w-10 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: value ? '#3b82f6' : '#d1d5db' }}
+              role="switch"
+              aria-checked={value}
+              aria-label="Login Token"
+          >
+          <span
+              className={`inline-block h-3 w-3 transform rounded-full bg-white transition-transform ${
+                  value ? 'translate-x-6' : 'translate-x-1'
+              }`}
+          />
+          </button>
+          <div className="flex-1">
+            <div className="text-sm font-medium text-gray-900 dark:text-gray-100">
+              Login Token
+            </div>
+            <p className="text-xs text-gray-500 dark:text-gray-400 mt-1">
+              When enabled, this user can log in via a direct URL without credentials
+            </p>
+          </div>
+        </div>
+
+        {loginUrl && (
+            <div className="mt-1 p-2 bg-amber-50 dark:bg-amber-900/20 border border-amber-200 dark:border-amber-700 rounded-md">
+              <p className="text-xs font-medium text-amber-800 dark:text-amber-300 mb-1">
+                Copy the login URL - it won&apos;t be shown again
+              </p>
+              <div className="flex items-center gap-2">
+                <code className="flex-1 text-xs font-mono text-amber-900 dark:text-amber-200 break-all select-all">
+                  {loginUrl}
+                </code>
+                <button
+                    onClick={copyUrl}
+                    className="flex-shrink-0 p-1.5 rounded text-amber-700 dark:text-amber-300 hover:bg-amber-100 dark:hover:bg-amber-800/50 transition-colors"
+                    aria-label="Copy login URL"
+                >
+                  <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="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>
+                </button>
+              </div>
+            </div>
+        )}
+      </div>
+  );
+}
+
 export function UserPermissionsModal({
   isOpen,
   onClose,
@@ -90,9 +167,11 @@ export function UserPermissionsModal({
   globalAutoApprove,
   globalInteractiveSearch,
   globalDownloadAccess,
+  generatedToken,
   onToggleAutoApprove,
   onToggleInteractiveSearch,
   onToggleDownloadAccess,
+  onToggleToken,
 }: UserPermissionsModalProps) {
   if (!user) return null;
 
@@ -201,6 +280,13 @@ export function UserPermissionsModal({
               description="When enabled, this user can download audiobook files directly"
               onToggle={() => onToggleDownloadAccess(user, !downloadValue)}
             />
+
+            {/* Login Token */}
+            <LoginTokenRow
+                value={user.hasLoginToken || generatedToken !== null}
+                generatedToken={generatedToken}
+                onToggle={() => onToggleToken(user, !(user.hasLoginToken || generatedToken !== null))}
+            />
           </div>
         </div>
       </div>

src/components/audiobooks/AudiobookCard.tsx

@@ -59,13 +59,15 @@ export function AudiobookCard({
   const [error, setError] = useState<string | null>(null);
   const [showModal, setShowModal] = useState(false);
   const [localRequestStatus, setLocalRequestStatus] = useState<string | undefined>(undefined);
+  const [localIsIgnored, setLocalIsIgnored] = useState<boolean | undefined>(undefined);
   const [coverError, setCoverError] = useState(false);
 
-  // Build a display-only audiobook with the local status override
+  // Build a display-only audiobook with local overrides
   const displayAudiobook = localRequestStatus !== undefined
     ? { ...audiobook, requestStatus: localRequestStatus }
     : audiobook;
   const status = getStatusConfig(displayAudiobook);
+  const isIgnored = localIsIgnored !== undefined ? localIsIgnored : audiobook.isIgnored;
 
   const handleRequest = async (e: React.MouseEvent) => {
     e.stopPropagation();
@@ -218,6 +220,19 @@ export function AudiobookCard({
                 <span>{audiobook.rating.toFixed(1)}</span>
               </div>
             )}
+
+            {/* Ignored Indicator - Bottom Left */}
+            {isIgnored && (
+              <div
+                className="absolute bottom-3 left-3 flex items-center gap-1 px-2 py-1 rounded-lg bg-black/50 backdrop-blur-md text-gray-300 text-xs font-medium transition-opacity duration-300 group-hover:opacity-0"
+                title="Ignored from auto-requests"
+              >
+                <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M3.98 8.223A10.477 10.477 0 001.934 12C3.226 16.338 7.244 19.5 12 19.5c.993 0 1.953-.138 2.863-.395M6.228 6.228A10.45 10.45 0 0112 4.5c4.756 0 8.773 3.162 10.065 7.498a10.523 10.523 0 01-4.293 5.774M6.228 6.228L3 3m3.228 3.228l3.65 3.65m7.894 7.894L21 21m-3.228-3.228l-3.65-3.65m0 0a3 3 0 10-4.243-4.243m4.242 4.242L9.88 9.88" />
+                </svg>
+                <span>Ignored</span>
+              </div>
+            )}
           </div>
         </div>
 
@@ -253,6 +268,7 @@ export function AudiobookCard({
         onClose={() => setShowModal(false)}
         onRequestSuccess={onRequestSuccess}
         onStatusChange={(newStatus) => setLocalRequestStatus(newStatus)}
+        onIgnoreChange={(ignored) => setLocalIsIgnored(ignored)}
         isRequested={audiobook.isRequested || localRequestStatus !== undefined}
         requestStatus={displayAudiobook.requestStatus}
         isAvailable={audiobook.isAvailable}

src/components/audiobooks/AudiobookDetailsModal.tsx

@@ -19,8 +19,10 @@ 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 { FolderArrowDownIcon, EyeSlashIcon } from '@heroicons/react/24/outline';
+import { EyeSlashIcon as EyeSlashSolidIcon } from '@heroicons/react/24/solid';
 import { fetchWithAuth } from '@/lib/utils/api';
+import { useIsIgnored, useToggleIgnore } from '@/lib/hooks/useIgnoredAudiobooks';
 
 interface AudiobookDetailsModalProps {
   asin: string;
@@ -28,6 +30,7 @@ interface AudiobookDetailsModalProps {
   onClose: () => void;
   onRequestSuccess?: () => void;
   onStatusChange?: (newStatus: string) => void;
+  onIgnoreChange?: (isIgnored: boolean) => void;
   isRequested?: boolean;
   requestStatus?: string | null;
   isAvailable?: boolean;
@@ -69,6 +72,7 @@ export function AudiobookDetailsModal({
   onClose,
   onRequestSuccess,
   onStatusChange,
+  onIgnoreChange,
   isRequested = false,
   requestStatus = null,
   isAvailable = false,
@@ -85,6 +89,9 @@ export function AudiobookDetailsModal({
   const { downloadAvailable, requestId } = useDownloadStatus(isOpen ? asin : null);
   const { fetchEbook, isLoading: isFetchingEbook } = useFetchEbookByAsin();
 
+  const { isIgnored, ignoredId, isLoading: isLoadingIgnore } = useIsIgnored(isOpen ? asin : null);
+  const { addIgnore, removeIgnore } = useToggleIgnore();
+
   const [showToast, setShowToast] = useState(false);
   const [toastMessage, setToastMessage] = useState('');
   const [toastType, setToastType] = useState<'success' | 'error'>('success');
@@ -97,6 +104,7 @@ export function AudiobookDetailsModal({
   const [localRequestStatus, setLocalRequestStatus] = useState<string | null>(requestStatus ?? null);
   const [isDownloading, setIsDownloading] = useState(false);
   const [coverError, setCoverError] = useState(false);
+  const [isTogglingIgnore, setIsTogglingIgnore] = useState(false);
 
   // Sync local status when the prop changes (e.g. page data refreshes)
   useEffect(() => {
@@ -196,6 +204,31 @@ export function AudiobookDetailsModal({
     }
   };
 
+  const handleToggleIgnore = async () => {
+    if (!user || !audiobook) return;
+    setIsTogglingIgnore(true);
+    try {
+      if (isIgnored && ignoredId) {
+        await removeIgnore(ignoredId, asin);
+        onIgnoreChange?.(false);
+        showNotification('Removed from ignore list');
+      } else {
+        await addIgnore({
+          asin,
+          title: audiobook.title,
+          author: audiobook.author,
+          coverArtUrl: audiobook.coverArtUrl,
+        });
+        onIgnoreChange?.(true);
+        showNotification('Added to ignore list — auto-requests will skip this book');
+      }
+    } catch (err) {
+      showNotification(err instanceof Error ? err.message : 'Failed to update ignore status', 'error');
+    } finally {
+      setIsTogglingIgnore(false);
+    }
+  };
+
   const formatDuration = (minutes?: number) => {
     if (!minutes) return null;
     const hours = Math.floor(minutes / 60);
@@ -685,6 +718,26 @@ export function AudiobookDetailsModal({
                 </>
               )}
 
+              {/* Ignore Toggle - always visible when user is logged in */}
+              {user && !isLoadingIgnore && (
+                <button
+                  onClick={handleToggleIgnore}
+                  disabled={isTogglingIgnore}
+                  className={`p-3 rounded-xl transition-colors disabled:opacity-50 ${
+                    isIgnored
+                      ? 'bg-gray-200 dark:bg-gray-700 text-gray-700 dark:text-gray-300'
+                      : 'bg-gray-100 dark:bg-gray-800/50 text-gray-400 dark:text-gray-500 hover:bg-gray-200 dark:hover:bg-gray-700'
+                  }`}
+                  title={isIgnored ? 'Stop Ignoring — auto-requests will resume for this book' : 'Ignore from Auto-Requests'}
+                >
+                  {isIgnored ? (
+                    <EyeSlashSolidIcon className="w-6 h-6" />
+                  ) : (
+                    <EyeSlashIcon className="w-6 h-6" />
+                  )}
+                </button>
+              )}
+
             </div>
           </div>
         )}

src/components/profile/ShelvesSection.tsx

@@ -6,9 +6,13 @@
 'use client';
 
 import React, { useState } from 'react';
-import { useShelves, GenericShelf } from '@/lib/hooks/useShelves';
-import { useDeleteGoodreadsShelf } from '@/lib/hooks/useGoodreadsShelves';
-import { useDeleteHardcoverShelf } from '@/lib/hooks/useHardcoverShelves';
+import {
+  useShelves,
+  GenericShelf,
+  useSyncShelves,
+} from '@/lib/hooks/useShelves';
+import { useDeleteGoodreadsShelf, useUpdateGoodreadsShelf } from '@/lib/hooks/useGoodreadsShelves';
+import { useDeleteHardcoverShelf, useUpdateHardcoverShelf } from '@/lib/hooks/useHardcoverShelves';
 import { AddShelfModal } from '@/components/ui/AddShelfModal';
 import { AudiobookDetailsModal } from '@/components/audiobooks/AudiobookDetailsModal';
 import { usePreferences } from '@/contexts/PreferencesContext';
@@ -37,6 +41,9 @@ export function ShelvesSection() {
     useDeleteGoodreadsShelf();
   const { deleteShelf: deleteHardcover, isLoading: isDeletingHardcover } =
     useDeleteHardcoverShelf();
+  const { syncShelves, isSyncing: isSyncingAll } = useSyncShelves();
+  const { updateShelf: updateGoodreads } = useUpdateGoodreadsShelf();
+  const { updateShelf: updateHardcover } = useUpdateHardcoverShelf();
   const { squareCovers } = usePreferences();
 
   const [confirmDeleteId, setConfirmDeleteId] = useState<string | null>(null);
@@ -57,6 +64,18 @@ export function ShelvesSection() {
     }
   };
 
+  const handleToggleAutoRequest = async (shelf: GenericShelf) => {
+    try {
+      if (shelf.type === 'goodreads') {
+        await updateGoodreads(shelf.id, { autoRequest: !shelf.autoRequest });
+      } else {
+        await updateHardcover(shelf.id, { autoRequest: !shelf.autoRequest });
+      }
+    } catch {
+      // Error handled by hook
+    }
+  };
+
   const isDeleting = isDeletingGoodreads || isDeletingHardcover;
 
   return (
@@ -93,25 +112,48 @@ export function ShelvesSection() {
         </div>
 
         {shelves.length > 0 && (
-          <button
-            onClick={() => setShowAddShelf(true)}
-            className="inline-flex items-center gap-1.5 px-3.5 py-2 text-sm font-medium text-gray-600 dark:text-gray-300 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-xl hover:bg-gray-50 dark:hover:bg-gray-700/70 hover:border-gray-300 dark:hover:border-gray-600 transition-all duration-200 shadow-sm"
-          >
-            <svg
-              className="w-4 h-4"
-              fill="none"
-              stroke="currentColor"
-              viewBox="0 0 24 24"
-              strokeWidth={2}
+          <div className="flex items-center gap-3">
+            <button
+              onClick={() => syncShelves()}
+              disabled={isSyncingAll}
+              className="inline-flex items-center gap-1.5 px-3.5 py-2 text-sm font-medium text-blue-600 dark:text-blue-400 bg-blue-50 dark:bg-blue-500/10 border border-blue-100 dark:border-blue-500/20 rounded-xl hover:bg-blue-100 dark:hover:bg-blue-500/20 transition-all duration-200 shadow-sm disabled:opacity-50"
+              title="Resync all shelves"
             >
-              <path
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                d="M12 4.5v15m7.5-7.5h-15"
-              />
-            </svg>
-            Add Shelf
-          </button>
+              <svg
+                className={cn('w-4 h-4', isSyncingAll && 'animate-spin')}
+                fill="none"
+                stroke="currentColor"
+                viewBox="0 0 24 24"
+                strokeWidth={2}
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  d="M16.023 9.348h4.992v-.001M2.985 19.644v-4.992m0 0h4.992m-4.993 0l3.181 3.183a8.25 8.25 0 0013.803-3.7M4.031 9.865a8.25 8.25 0 0113.803-3.7l3.181 3.182m0-4.991v4.99"
+                />
+              </svg>
+              {isSyncingAll ? 'Syncing...' : 'Resync All'}
+            </button>
+            <button
+              onClick={() => setShowAddShelf(true)}
+              className="inline-flex items-center gap-1.5 px-3.5 py-2 text-sm font-medium text-gray-600 dark:text-gray-300 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-xl hover:bg-gray-50 dark:hover:bg-gray-700/70 hover:border-gray-300 dark:hover:border-gray-600 transition-all duration-200 shadow-sm"
+            >
+              <svg
+                className="w-4 h-4"
+                fill="none"
+                stroke="currentColor"
+                viewBox="0 0 24 24"
+                strokeWidth={2}
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  d="M12 4.5v15m7.5-7.5h-15"
+                />
+              </svg>
+              Add Shelf
+            </button>
+          </div>
         )}
       </div>
 
@@ -131,6 +173,7 @@ export function ShelvesSection() {
               onConfirmDelete={() => setConfirmDeleteId(shelf.id)}
               onCancelDelete={() => setConfirmDeleteId(null)}
               onManage={() => setManageShelf(shelf)}
+              onToggleAutoRequest={() => handleToggleAutoRequest(shelf)}
               onBookClick={(asin) => setSelectedAsin(asin)}
             />
           ))}
@@ -254,6 +297,7 @@ interface ShelfCardProps {
   onConfirmDelete: () => void;
   onCancelDelete: () => void;
   onManage: () => void;
+  onToggleAutoRequest: () => void;
   onBookClick: (asin: string) => void;
 }
 
@@ -266,8 +310,10 @@ function ShelfCard({
   onConfirmDelete,
   onCancelDelete,
   onManage,
+  onToggleAutoRequest,
   onBookClick,
 }: ShelfCardProps) {
+  const { syncShelves, isSyncing: isManualSyncing } = useSyncShelves();
   const displayBooks = shelf.books.slice(0, 6);
   const hasCovers = displayBooks.length > 0;
   const remainingCount = Math.max(
@@ -292,7 +338,12 @@ function ShelfCard({
     );
 
   return (
-    <div className="group rounded-2xl bg-white dark:bg-gray-800 border border-gray-100 dark:border-gray-700/30 p-6 sm:p-7 transition-all duration-300 hover:shadow-lg hover:shadow-black/[0.04] dark:hover:shadow-black/20 hover:border-gray-200 dark:hover:border-gray-600/40">
+    <div className={cn(
+      'group rounded-2xl bg-white dark:bg-gray-800 border p-6 sm:p-7 transition-all duration-300',
+      shelf.autoRequest
+        ? 'border-gray-100 dark:border-gray-700/30 hover:shadow-lg hover:shadow-black/[0.04] dark:hover:shadow-black/20 hover:border-gray-200 dark:hover:border-gray-600/40'
+        : 'border-gray-200/60 dark:border-gray-700/20 bg-gray-50/50 dark:bg-gray-800/60',
+    )}>
       {/* Top: Shelf info + actions */}
       <div
         className={cn(
@@ -301,7 +352,12 @@ function ShelfCard({
         )}
       >
         <div className="min-w-0 flex-1">
-          <h3 className="font-semibold text-[15px] text-gray-900 dark:text-white truncate leading-snug flex items-center">
+          <h3 className={cn(
+            'font-semibold text-[15px] truncate leading-snug flex items-center',
+            shelf.autoRequest
+              ? 'text-gray-900 dark:text-white'
+              : 'text-gray-400 dark:text-gray-500',
+          )}>
             {shelf.name} {providerIcon}
           </h3>
           <div className="flex items-center gap-2 mt-2">
@@ -310,6 +366,14 @@ function ShelfCard({
                 {shelf.bookCount} {shelf.bookCount === 1 ? 'book' : 'books'}
               </span>
             )}
+            {!shelf.autoRequest && (
+              <span className="inline-flex items-center gap-1 px-2 py-0.5 rounded-md text-xs font-medium bg-amber-50 dark:bg-amber-500/10 text-amber-600 dark:text-amber-400 ring-1 ring-amber-200/50 dark:ring-amber-500/20">
+                <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M15.75 5.25v13.5m-7.5-13.5v13.5" />
+                </svg>
+                Paused
+              </span>
+            )}
             <span className="inline-flex items-center gap-1.5 text-xs text-gray-400 dark:text-gray-500">
               {isSyncing ? (
                 <>
@@ -352,6 +416,27 @@ function ShelfCard({
             </div>
           ) : (
             <div className="flex items-center gap-1">
+              <button
+                onClick={onToggleAutoRequest}
+                className={cn(
+                  'p-2 transition-all duration-200 rounded-xl outline-none',
+                  shelf.autoRequest
+                    ? 'text-gray-400 hover:text-amber-500 dark:text-gray-500 dark:hover:text-amber-400 hover:bg-amber-50 dark:hover:bg-amber-500/10 opacity-40 hover:opacity-100 focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-amber-500/40'
+                    : 'text-amber-500 dark:text-amber-400 bg-amber-50 dark:bg-amber-500/10 opacity-100',
+                )}
+                title={shelf.autoRequest ? 'Pause auto-requesting' : 'Resume auto-requesting'}
+                aria-label={shelf.autoRequest ? 'Pause auto-requesting' : 'Resume auto-requesting'}
+              >
+                {shelf.autoRequest ? (
+                  <svg className="w-[18px] h-[18px]" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={1.5}>
+                    <path strokeLinecap="round" strokeLinejoin="round" d="M15.75 5.25v13.5m-7.5-13.5v13.5" />
+                  </svg>
+                ) : (
+                  <svg className="w-[18px] h-[18px]" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={1.5}>
+                    <path strokeLinecap="round" strokeLinejoin="round" d="M5.25 5.653c0-.856.917-1.398 1.667-.986l11.54 6.348a1.125 1.125 0 010 1.971l-11.54 6.347a1.125 1.125 0 01-1.667-.985V5.653z" />
+                  </svg>
+                )}
+              </button>
               <button
                 onClick={onManage}
                 className="p-2 text-gray-400 hover:text-blue-500 dark:text-gray-500 dark:hover:text-blue-400 transition-all duration-200 rounded-xl hover:bg-blue-50 dark:hover:bg-blue-500/10 opacity-40 hover:opacity-100 focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-blue-500/40 outline-none"
@@ -372,6 +457,30 @@ function ShelfCard({
                   />
                 </svg>
               </button>
+              <button
+                onClick={() => syncShelves(shelf.id, shelf.type)}
+                disabled={isManualSyncing}
+                className="p-2 text-gray-400 hover:text-emerald-500 dark:text-gray-500 dark:hover:text-emerald-400 transition-all duration-200 rounded-xl hover:bg-emerald-50 dark:hover:bg-emerald-500/10 opacity-40 hover:opacity-100 focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-emerald-500/40 outline-none disabled:opacity-30"
+                title="Resync shelf"
+                aria-label="Resync shelf"
+              >
+                <svg
+                  className={cn(
+                    'w-[18px] h-[18px]',
+                    isManualSyncing && 'animate-spin',
+                  )}
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                  strokeWidth={1.5}
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    d="M16.023 9.348h4.992v-.001M2.985 19.644v-4.992m0 0h4.992m-4.993 0l3.181 3.183a8.25 8.25 0 0013.803-3.7M4.031 9.865a8.25 8.25 0 0113.803-3.7l3.181 3.182m0-4.991v4.99"
+                  />
+                </svg>
+              </button>
               <button
                 onClick={onConfirmDelete}
                 className="p-2 text-gray-400 hover:text-red-400 dark:text-gray-500 dark:hover:text-red-400 transition-all duration-200 rounded-xl hover:bg-red-50 dark:hover:bg-red-500/10 opacity-40 hover:opacity-100 focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-red-500/40 outline-none"
@@ -398,6 +507,7 @@ function ShelfCard({
       </div>
 
       {/* Bottom: Stacked book covers */}
+      <div className={cn(!shelf.autoRequest && 'opacity-50 grayscale-[30%]')}>
       {hasCovers ? (
         <CoverStack
           books={displayBooks}
@@ -419,6 +529,7 @@ function ShelfCard({
           ))}
         </div>
       ) : null}
+      </div>
     </div>
   );
 }

src/components/requests/RequestCard.tsx

@@ -50,7 +50,7 @@ export function RequestCard({ request, showActions = true }: RequestCardProps) {
   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 canCancel = ['pending', 'searching', 'downloading', 'awaiting_search'].includes(request.status);
   const isActive = ['searching', 'downloading', 'processing'].includes(request.status);
   const isFailed = request.status === 'failed';
 

src/components/ui/AddShelfModal.tsx

@@ -32,6 +32,8 @@ export function AddShelfModal({ isOpen, onClose }: AddShelfModalProps) {
   const [statusId, setStatusId] = useState('1');
   const [customListId, setCustomListId] = useState('');
 
+  // Shared State
+  const [autoRequest, setAutoRequest] = useState(true);
   const [validationError, setValidationError] = useState('');
   const [success, setSuccess] = useState(false);
   const [successMessage, setSuccessMessage] = useState('');
@@ -72,12 +74,12 @@ export function AddShelfModal({ isOpen, onClose }: AddShelfModalProps) {
 
     try {
       if (provider === 'goodreads') {
-        const shelf = await addGoodreads(rssUrl);
+        const shelf = await addGoodreads(rssUrl, autoRequest);
         setSuccessMessage(`Added shelf "${shelf.name}" successfully!`);
         setRssUrl('');
       } else {
         const finalId = listType === 'status' ? `status-${statusId}` : customListId.trim();
-        const shelf = await addHardcover(apiToken.trim(), finalId);
+        const shelf = await addHardcover(apiToken.trim(), finalId, autoRequest);
         setSuccessMessage(`Added list "${shelf.name}" successfully!`);
         setApiToken('');
         setCustomListId('');
@@ -98,6 +100,7 @@ export function AddShelfModal({ isOpen, onClose }: AddShelfModalProps) {
     setRssUrl('');
     setApiToken('');
     setCustomListId('');
+    setAutoRequest(true);
     setValidationError('');
     setSuccess(false);
     setSuccessMessage('');
@@ -215,6 +218,32 @@ export function AddShelfModal({ isOpen, onClose }: AddShelfModalProps) {
             />
           )}
 
+          {/* Auto-Request Toggle */}
+          <label className="flex items-center justify-between gap-3 p-3 rounded-xl bg-gray-50 dark:bg-gray-800/50 border border-gray-100 dark:border-gray-700/30 cursor-pointer select-none">
+            <div>
+              <span className="text-sm font-medium text-gray-700 dark:text-gray-300">Auto-request books</span>
+              <p className="text-xs text-gray-400 dark:text-gray-500 mt-0.5">
+                Automatically request audiobooks from this shelf
+              </p>
+            </div>
+            <button
+              type="button"
+              role="switch"
+              aria-checked={autoRequest}
+              onClick={() => setAutoRequest(!autoRequest)}
+              disabled={isLoading || success}
+              className={`relative inline-flex h-5 w-9 flex-shrink-0 rounded-full transition-colors duration-200 ease-in-out focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-500/40 ${
+                autoRequest ? 'bg-blue-600' : 'bg-gray-300 dark:bg-gray-600'
+              } ${(isLoading || success) ? 'opacity-50 cursor-not-allowed' : ''}`}
+            >
+              <span
+                className={`pointer-events-none inline-block h-4 w-4 transform rounded-full bg-white shadow-sm ring-0 transition duration-200 ease-in-out ${
+                  autoRequest ? 'translate-x-4' : 'translate-x-0.5'
+                } mt-0.5`}
+              />
+            </button>
+          </label>
+
           <div className="flex justify-end gap-3 pt-2">
             <Button type="button" variant="ghost" size="sm" onClick={handleClose} disabled={isLoading || success}>
               Cancel

src/components/ui/ManageShelfModal.tsx

@@ -45,12 +45,13 @@ export function ManageShelfModal({ shelf, isOpen, onClose }: ManageShelfModalPro
     try {
       if (shelf.type === 'goodreads') {
         if (!rssUrl.trim()) return;
-        await updateGoodreads(shelf.id, rssUrl.trim());
+        await updateGoodreads(shelf.id, { rssUrl: rssUrl.trim() });
       } else {
         if (!listId.trim()) return;
         await updateHardcover(shelf.id, {
           listId: listId.trim(),
           apiToken: apiToken.trim() || undefined,
+          forceSync: true,
         });
       }
       onClose();

src/lib/hooks/createShelfHooks.ts

@@ -46,7 +46,13 @@ export function createShelfHooks<TShelf>(endpoint: string) {
     const key = accessToken ? endpoint : null;
 
     const { data, error, isLoading } = useSWR(key, fetcher, {
-      refreshInterval: 30000,
+      refreshInterval: (latestData: { shelves: TShelf[] } | undefined) => {
+        const shelves = latestData?.shelves || [];
+        const hasSyncing = shelves.some(
+          (s) => !(s as Record<string, unknown>)['lastSyncAt'],
+        );
+        return hasSyncing ? 3000 : 30000;
+      },
     });
 
     return {

src/lib/hooks/useAudiobooks.ts

@@ -33,6 +33,7 @@ export interface Audiobook {
   requestId?: string | null;  // ID of request (if any)
   requestedByUsername?: string | null;  // Username who requested (only if not current user)
   hasReportedIssue?: boolean;  // True if an open issue exists for this audiobook
+  isIgnored?: boolean;  // True if this user has ignored this audiobook from auto-requests
 }
 
 export function useAudiobooks(type: 'popular' | 'new-releases', limit: number = 20, page: number = 1, hideAvailable: boolean = false) {

src/lib/hooks/useGoodreadsShelves.ts

@@ -16,6 +16,7 @@ export interface GoodreadsShelf {
   lastSyncAt: string | null;
   createdAt: string;
   bookCount: number | null;
+  autoRequest: boolean;
   books: ShelfBook[];
 }
 
@@ -27,8 +28,8 @@ export const useGoodreadsShelves = useList;
 export function useAddGoodreadsShelf() {
   const { addShelf: addGeneric, isLoading, error } = useAdd();
 
-  const addShelf = async (rssUrl: string) => {
-    return addGeneric({ rssUrl });
+  const addShelf = async (rssUrl: string, autoRequest: boolean = true) => {
+    return addGeneric({ rssUrl, autoRequest });
   };
 
   return { addShelf, isLoading, error };
@@ -39,8 +40,8 @@ export const useDeleteGoodreadsShelf = useDelete;
 export function useUpdateGoodreadsShelf() {
   const { updateShelf: updateGeneric, isLoading, error } = useUpdate();
 
-  const updateShelf = async (shelfId: string, rssUrl: string) => {
-    return updateGeneric(shelfId, { rssUrl });
+  const updateShelf = async (shelfId: string, updates: { rssUrl?: string; autoRequest?: boolean }) => {
+    return updateGeneric(shelfId, updates);
   };
 
   return { updateShelf, isLoading, error };

src/lib/hooks/useHardcoverShelves.ts

@@ -16,6 +16,7 @@ export interface HardcoverShelf {
   lastSyncAt: string | null;
   createdAt: string;
   bookCount: number | null;
+  autoRequest: boolean;
   books: ShelfBook[];
 }
 
@@ -27,8 +28,8 @@ export const useHardcoverShelves = useList;
 export function useAddHardcoverShelf() {
   const { addShelf: addGeneric, isLoading, error } = useAdd();
 
-  const addShelf = async (apiToken: string, listId: string) => {
-    return addGeneric({ apiToken, listId });
+  const addShelf = async (apiToken: string, listId: string, autoRequest: boolean = true) => {
+    return addGeneric({ apiToken, listId, autoRequest });
   };
 
   return { addShelf, isLoading, error };
@@ -41,7 +42,7 @@ export function useUpdateHardcoverShelf() {
 
   const updateShelf = async (
     shelfId: string,
-    updates: { listId?: string; apiToken?: string },
+    updates: { listId?: string; apiToken?: string; forceSync?: boolean; autoRequest?: boolean },
   ) => {
     return updateGeneric(shelfId, updates);
   };

src/lib/hooks/useIgnoredAudiobooks.ts

@@ -0,0 +1,123 @@
+/**
+ * Component: Ignored Audiobooks Hook
+ * Documentation: documentation/features/ignored-audiobooks.md
+ *
+ * Provides hooks for checking and toggling audiobook ignore status.
+ * - useIsIgnored(asin): check if a specific book is ignored
+ * - useToggleIgnore(): toggle ignore on/off for a book
+ * - useIgnoredList(): list all ignored books for the current user
+ */
+
+'use client';
+
+import useSWR, { mutate } from 'swr';
+import { authenticatedFetcher, fetchWithAuth } from '@/lib/utils/api';
+
+interface IgnoredAudiobook {
+  id: string;
+  asin: string;
+  title: string;
+  author: string;
+  coverArtUrl?: string;
+  createdAt: string;
+}
+
+interface IgnoreCheckResult {
+  ignored: boolean;
+  ignoredId?: string;
+}
+
+/**
+ * Check if a specific ASIN is ignored by the current user.
+ * Includes works-system expansion on the server side.
+ */
+export function useIsIgnored(asin: string | null) {
+  const endpoint = asin ? `/api/user/ignored-audiobooks/check/${asin}` : null;
+
+  const { data, error, isLoading } = useSWR<IgnoreCheckResult>(
+    endpoint,
+    authenticatedFetcher,
+    {
+      revalidateOnFocus: false,
+      dedupingInterval: 30000,
+    }
+  );
+
+  return {
+    isIgnored: data?.ignored ?? false,
+    ignoredId: data?.ignoredId ?? null,
+    isLoading,
+    error,
+  };
+}
+
+/**
+ * Toggle ignore status for an audiobook.
+ * Returns { addIgnore, removeIgnore } functions.
+ */
+export function useToggleIgnore() {
+  const addIgnore = async (book: {
+    asin: string;
+    title: string;
+    author: string;
+    coverArtUrl?: string;
+  }): Promise<IgnoredAudiobook> => {
+    const res = await fetchWithAuth('/api/user/ignored-audiobooks', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(book),
+    });
+
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(err.message || 'Failed to ignore audiobook');
+    }
+
+    const result = await res.json();
+
+    // Invalidate the check cache for this ASIN
+    mutate(`/api/user/ignored-audiobooks/check/${book.asin}`);
+    // Invalidate the full list
+    mutate('/api/user/ignored-audiobooks');
+
+    return result.ignoredAudiobook;
+  };
+
+  const removeIgnore = async (id: string, asin: string): Promise<void> => {
+    const res = await fetchWithAuth(`/api/user/ignored-audiobooks/${id}`, {
+      method: 'DELETE',
+    });
+
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(err.message || 'Failed to un-ignore audiobook');
+    }
+
+    // Invalidate the check cache for this ASIN
+    mutate(`/api/user/ignored-audiobooks/check/${asin}`);
+    // Invalidate the full list
+    mutate('/api/user/ignored-audiobooks');
+  };
+
+  return { addIgnore, removeIgnore };
+}
+
+/**
+ * List all ignored audiobooks for the current user.
+ */
+export function useIgnoredList() {
+  const { data, error, isLoading } = useSWR<{ ignoredAudiobooks: IgnoredAudiobook[] }>(
+    '/api/user/ignored-audiobooks',
+    authenticatedFetcher,
+    {
+      revalidateOnFocus: false,
+      dedupingInterval: 60000,
+    }
+  );
+
+  return {
+    ignoredAudiobooks: data?.ignoredAudiobooks ?? [],
+    isLoading,
+    error,
+  };
+}

src/lib/hooks/useRequests.ts

@@ -5,8 +5,9 @@
 
 'use client';
 
-import { useState } from 'react';
+import { useState, useMemo } from 'react';
 import useSWR, { mutate } from 'swr';
+import useSWRInfinite from 'swr/infinite';
 import { useAuth } from '@/contexts/AuthContext';
 import { fetchWithAuth } from '@/lib/utils/api';
 import { Audiobook } from './useAudiobooks';
@@ -59,6 +60,95 @@ export function useRequests(status?: string, limit: number = 50, myOnly: boolean
   };
 }
 
+// ── Active statuses that warrant live polling ────────────────────────────────
+const ACTIVE_STATUSES = new Set([
+  'pending', 'awaiting_search', 'awaiting_approval',
+  'searching', 'downloading', 'processing', 'awaiting_import',
+]);
+
+export type RequestFilterGroup = 'all' | 'active' | 'waiting' | 'completed' | 'failed' | 'cancelled';
+
+export interface RequestCounts {
+  all: number;
+  active: number;
+  waiting: number;
+  completed: number;
+  failed: number;
+  cancelled: number;
+}
+
+export interface RequestPage {
+  requests: Request[];
+  nextCursor: string | null;
+  counts: RequestCounts;
+}
+
+const PAGE_SIZE = 20;
+
+/**
+ * Paginated hook for "My Requests" page.
+ * Uses SWRInfinite for cursor-based pagination.
+ * Polls only when active requests are present.
+ */
+export function useMyRequests(filter: RequestFilterGroup) {
+  const { accessToken } = useAuth();
+
+  const getKey = (pageIndex: number, previousPage: RequestPage | null): string | null => {
+    if (!accessToken) return null;
+    if (previousPage && !previousPage.nextCursor) return null; // reached end
+
+    const params = new URLSearchParams();
+    params.set('myOnly', 'true');
+    params.set('take', String(PAGE_SIZE));
+    if (filter !== 'all') params.set('status', filter);
+    if (pageIndex > 0 && previousPage?.nextCursor) {
+      params.set('cursor', previousPage.nextCursor);
+    }
+    return `/api/requests?${params.toString()}`;
+  };
+
+  const { data, error, isLoading, isValidating, size, setSize, mutate: revalidate } =
+    useSWRInfinite<RequestPage>(getKey, fetcher, {
+      revalidateFirstPage: true,
+      revalidateOnFocus: false,
+      // Smart polling: refresh every 5s only when active requests exist
+      refreshInterval: (data) => {
+        if (!data) return 5000;
+        const hasActive = data.some(page =>
+          page.requests.some(r => ACTIVE_STATUSES.has(r.status))
+        );
+        return hasActive ? 5000 : 0;
+      },
+    });
+
+  const allRequests = useMemo(
+    () => data?.flatMap(page => page.requests) ?? [],
+    [data]
+  );
+
+  // Counts come from the first page (always the authoritative totals)
+  const counts: RequestCounts = data?.[0]?.counts ?? {
+    all: 0, active: 0, waiting: 0, completed: 0, failed: 0, cancelled: 0,
+  };
+
+  const hasMore = data ? !!data[data.length - 1]?.nextCursor : false;
+  const isLoadingMore = isValidating && size > 1 && !data?.[size - 1];
+  const isEmpty = !isLoading && allRequests.length === 0;
+
+  const loadMore = () => setSize(s => s + 1);
+
+  return {
+    requests: allRequests,
+    counts,
+    hasMore,
+    isLoading,
+    isLoadingMore,
+    isEmpty,
+    loadMore,
+    revalidate,
+  };
+}
+
 export function useRequest(requestId: string) {
   const { accessToken } = useAuth();
 

src/lib/hooks/useShelves.ts

@@ -2,10 +2,10 @@
  * Component: Shelves Hook
  * Documentation: documentation/frontend/components.md
  */
-
 'use client';
 
-import useSWR from 'swr';
+import { useState } from 'react';
+import useSWR, { mutate } from 'swr';
 import { useAuth } from '@/contexts/AuthContext';
 import { fetchWithAuth } from '@/lib/utils/api';
 import { ShelfBook } from './useGoodreadsShelves';
@@ -18,6 +18,7 @@ export interface GenericShelf {
   lastSyncAt: string | null;
   createdAt: string;
   bookCount: number | null;
+  autoRequest: boolean;
   books: ShelfBook[];
 }
 
@@ -29,7 +30,11 @@ export function useShelves() {
   const endpoint = accessToken ? '/api/user/shelves' : null;
 
   const { data, error, isLoading } = useSWR(endpoint, fetcher, {
-    refreshInterval: 30000,
+    refreshInterval: (latestData: { shelves: GenericShelf[] } | undefined) => {
+      const shelves = latestData?.shelves || [];
+      const hasSyncing = shelves.some((s) => !s.lastSyncAt);
+      return hasSyncing ? 3000 : 30000;
+    },
   });
 
   return {
@@ -38,3 +43,52 @@ export function useShelves() {
     error,
   };
 }
+
+export function useSyncShelves() {
+  const { accessToken } = useAuth();
+  const [isSyncing, setIsSyncing] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const syncShelves = async (
+    shelfId?: string,
+    shelfType?: 'goodreads' | 'hardcover',
+  ) => {
+    if (!accessToken) throw new Error('Not authenticated');
+
+    setIsSyncing(true);
+    setError(null);
+
+    try {
+      const response = await fetchWithAuth('/api/user/shelves/sync', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ shelfId, shelfType }),
+      });
+
+      const data = await response.json();
+
+      if (!response.ok) {
+        throw new Error(data.message || data.error || 'Failed to trigger sync');
+      }
+
+      // Invalidate both the provider-specific endpoints and the combined endpoint
+      mutate(
+        (key) =>
+          typeof key === 'string' &&
+          (key.includes('/api/user/shelves') ||
+            key.includes('/api/user/goodreads-shelves') ||
+            key.includes('/api/user/hardcover-shelves')),
+      );
+
+      return true;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Unknown error';
+      setError(message);
+      throw err;
+    } finally {
+      setIsSyncing(false);
+    }
+  };
+
+  return { syncShelves, isSyncing, error };
+}

src/lib/integrations/nzbget.service.ts

@@ -226,6 +226,7 @@ export class NZBGetService implements IDownloadClient {
         responseType: 'arraybuffer',
         timeout: 30000,
         maxRedirects: 5,
+        headers: options?.sourceHeaders,
         httpsAgent: url.startsWith('https') ? this.httpsAgent : undefined,
       });
 

src/lib/integrations/sabnzbd.service.ts

@@ -24,6 +24,8 @@ export interface AddNZBOptions {
   category?: string;
   priority?: 'low' | 'normal' | 'high' | 'force';
   paused?: boolean;
+  /** Headers to include when fetching the NZB from the source URL */
+  sourceHeaders?: Record<string, string>;
 }
 
 export interface NZBInfo {
@@ -492,6 +494,7 @@ export class SABnzbdService implements IDownloadClient {
         responseType: 'arraybuffer',
         timeout: 30000,
         maxRedirects: 5,
+        headers: options?.sourceHeaders,
         // Use the same SSL settings as the SABnzbd client if the NZB URL
         // happens to be served over HTTPS with a self-signed cert
         httpsAgent: url.startsWith('https') ? this.httpsAgent : undefined,
@@ -787,6 +790,7 @@ export class SABnzbdService implements IDownloadClient {
       category: options?.category,
       priority: options?.priority ? priorityMap[options.priority] || 'normal' : undefined,
       paused: options?.paused,
+      sourceHeaders: options?.sourceHeaders,
     });
   }
 

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

@@ -102,6 +102,8 @@ export interface AddDownloadOptions {
   priority?: string;
   /** Whether to add in paused state */
   paused?: boolean;
+  /** Headers to include when fetching the source file (e.g. Prowlarr API key for proxy URLs) */
+  sourceHeaders?: Record<string, string>;
 }
 
 /** Result of a connection test */

src/lib/middleware/auth.ts

@@ -172,6 +172,7 @@ export async function requireAuth(
     select: {
       id: true,
       deletedAt: true,
+      sessionsInvalidatedAt: true,
     },
   });
 
@@ -186,6 +187,19 @@ export async function requireAuth(
     );
   }
 
+  // Check if session was invalidated after this token was issued
+  if (user.sessionsInvalidatedAt && payload.iat &&
+      payload.iat < Math.floor(user.sessionsInvalidatedAt.getTime() / 1000)) {
+    logger.warn('Token issued before session invalidation', { userId: payload.sub });
+    return NextResponse.json(
+      {
+        error: 'Unauthorized',
+        message: 'Session has been revoked',
+      },
+      { status: 401 }
+    );
+  }
+
   // Add user to request
   const authenticatedRequest = request as AuthenticatedRequest;
   authenticatedRequest.user = {

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

@@ -289,8 +289,11 @@ async function downloadFileWithProgress(
   logger: RMABLogger
 ): Promise<boolean> {
   try {
-    // Ensure target directory exists
-    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    // Ensure target directory exists with configured permissions
+    const configService = getConfigService();
+    const dirChmodStr = await configService.get('dir_chmod') || '775';
+    const dirMode = parseInt(dirChmodStr, 8);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true, mode: dirMode });
 
     // Start download with axios streaming
     const response = await axios({

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

@@ -58,10 +58,19 @@ export async function processDownloadTorrent(payload: DownloadTorrentPayload): P
 
     logger.info(`Routing to ${client.clientType} (${client.protocol})`);
 
+    // Include Prowlarr API key as source header so NZB/torrent downloads from
+    // Prowlarr proxy URLs are authenticated (fixes 403 for indexers like NZBFinder)
+    const prowlarrApiKey = (await config.getMany(['prowlarr_api_key'])).prowlarr_api_key || process.env.PROWLARR_API_KEY;
+    const sourceHeaders: Record<string, string> = {};
+    if (prowlarrApiKey) {
+      sourceHeaders['X-Api-Key'] = prowlarrApiKey;
+    }
+
     // Add download via unified interface
     const downloadClientId = await client.addDownload(torrent.downloadUrl, {
       category,
       priority: 'normal',
+      sourceHeaders,
     });
 
     logger.info(`Download added with ID: ${downloadClientId}`);

src/lib/processors/plex-recently-added.processor.ts

@@ -254,7 +254,7 @@ export async function processPlexRecentlyAddedCheck(payload: PlexRecentlyAddedPa
     const matchableRequests = await prisma.request.findMany({
       where: {
         type: 'audiobook', // Only match audiobook requests (ebooks don't go to 'available')
-        status: { notIn: ['available', 'cancelled'] },
+        status: { notIn: ['available', 'cancelled', 'denied'] },
         deletedAt: null,
       },
       include: {
@@ -265,7 +265,7 @@ export async function processPlexRecentlyAddedCheck(payload: PlexRecentlyAddedPa
           },
         },
       },
-      take: 100,
+
     });
 
     if (matchableRequests.length > 0) {

src/lib/processors/scan-plex.processor.ts

@@ -439,7 +439,7 @@ export async function processScanPlex(payload: ScanPlexPayload): Promise<any> {
     const matchableRequests = await prisma.request.findMany({
       where: {
         type: 'audiobook', // Only match audiobook requests (ebooks don't go to 'available')
-        status: { notIn: ['available', 'cancelled'] },
+        status: { notIn: ['available', 'cancelled', 'denied'] },
         deletedAt: null,
       },
       include: {
@@ -450,7 +450,7 @@ export async function processScanPlex(payload: ScanPlexPayload): Promise<any> {
           },
         },
       },
-      take: 100, // Increased from 50 to handle more eligible requests
+
     });
 
     logger.info(`Found ${matchableRequests.length} matchable requests (all non-terminal statuses)`);

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

@@ -36,16 +36,25 @@ export async function processSearchEbook(payload: SearchEbookPayload): Promise<a
   logger.info(`Processing ebook request ${requestId} for "${audiobook.title}"`);
 
   try {
-    // Update request status to searching
-    await prisma.request.update({
+    // Update request status to searching and fetch custom search terms
+    const requestRecord = await prisma.request.update({
       where: { id: requestId },
       data: {
         status: 'searching',
         searchAttempts: { increment: 1 },
         updatedAt: new Date(),
       },
+      select: { customSearchTerms: true },
     });
 
+    // Use custom search terms if set, otherwise use audiobook title
+    const effectiveSearchTitle = requestRecord?.customSearchTerms || audiobook.title;
+    const searchAudiobook = { ...audiobook, title: effectiveSearchTitle };
+
+    if (requestRecord?.customSearchTerms) {
+      logger.info(`Using custom search terms: "${effectiveSearchTitle}" (original: "${audiobook.title}")`);
+    }
+
     // Get ebook configuration
     const configService = getConfigService();
     const preferredFormat = payloadFormat || await configService.get('ebook_sidecar_preferred_format') || 'epub';
@@ -62,7 +71,7 @@ export async function processSearchEbook(payload: SearchEbookPayload): Promise<a
     // ========== STEP 1: Try Anna's Archive (if enabled) ==========
     if (annasArchiveEnabled) {
       logger.info(`Searching Anna's Archive...`);
-      annasArchiveResult = await searchAnnasArchive(audiobook, preferredFormat, logger);
+      annasArchiveResult = await searchAnnasArchive(searchAudiobook, preferredFormat, logger);
 
       if (annasArchiveResult) {
         logger.info(`Found ebook via Anna's Archive (score: ${annasArchiveResult.score})`);
@@ -74,7 +83,7 @@ export async function processSearchEbook(payload: SearchEbookPayload): Promise<a
     // ========== STEP 2: Try Indexer Search (if enabled and no Anna's Archive result) ==========
     if (!annasArchiveResult && indexerSearchEnabled) {
       logger.info(`Searching indexers...`);
-      indexerResult = await searchIndexers(requestId, audiobook, preferredFormat, logger);
+      indexerResult = await searchIndexers(requestId, searchAudiobook, preferredFormat, logger);
 
       if (indexerResult) {
         logger.info(`Found ebook via indexer search (score: ${indexerResult.finalScore.toFixed(1)})`);

src/lib/processors/sync-shelves.processor.ts

@@ -15,6 +15,8 @@ export interface SyncShelvesPayload {
   shelfId?: string;
   /** The type of shelf, if shelfId is specified */
   shelfType?: 'goodreads' | 'hardcover';
+  /** If set, only process shelves for this user */
+  userId?: string;
   /** Max Audible lookups per shelf. 0 = unlimited. */
   maxLookupsPerShelf?: number;
 }
@@ -22,7 +24,7 @@ export interface SyncShelvesPayload {
 export async function processSyncShelves(
   payload: SyncShelvesPayload,
 ): Promise<any> {
-  const { jobId, shelfId, shelfType, maxLookupsPerShelf } = payload;
+  const { jobId, shelfId, shelfType, userId, maxLookupsPerShelf } = payload;
   const logger = RMABLogger.forJob(jobId, 'SyncShelves');
 
   const stats = {
@@ -48,6 +50,7 @@ export async function processSyncShelves(
         await import('../services/goodreads-sync.service');
       const grStats = await processGoodreadsShelves(logger, {
         shelfId: shelfType === 'goodreads' ? shelfId : undefined,
+        userId,
         maxLookupsPerShelf: maxLookupsPerShelf ?? (shelfId ? 0 : undefined),
       });
 
@@ -70,6 +73,7 @@ export async function processSyncShelves(
         await import('../services/hardcover-sync.service');
       const hcStats = await processHardcoverShelves(logger, {
         shelfId: shelfType === 'hardcover' ? shelfId : undefined,
+        userId,
         maxLookupsPerShelf: maxLookupsPerShelf ?? (shelfId ? 0 : undefined),
       });
 

src/lib/services/auth/OIDCAuthProvider.ts

@@ -98,9 +98,15 @@ export class OIDCAuthProvider implements IAuthProvider {
         timestamp: Date.now(),
       });
 
+      // Only request 'groups' scope when group-based features are configured
+      const accessMethod = await this.configService.get('oidc.access_control_method');
+      const adminClaimEnabled = await this.configService.get('oidc.admin_claim_enabled');
+      const needsGroups = accessMethod === 'group_claim' || adminClaimEnabled === 'true';
+      const scope = needsGroups ? 'openid profile email groups' : 'openid profile email';
+
       // Generate authorization URL
       const redirectUrl = client.authorizationUrl({
-        scope: 'openid profile email groups',
+        scope,
         state,
         nonce,
         code_challenge: codeChallenge,

src/lib/services/goodreads-sync.service.ts

@@ -9,6 +9,7 @@
 import axios from 'axios';
 import { XMLParser } from 'fast-xml-parser';
 import { prisma } from '@/lib/db';
+import { Prisma } from '@/generated/prisma/client';
 import { RMABLogger } from '@/lib/utils/logger';
 import {
   ShelfBook,
@@ -118,7 +119,10 @@ export async function processGoodreadsShelves(
   const stats = createEmptyStats();
   const maxLookups = resolveMaxLookups(options);
 
-  const whereClause = options.shelfId ? { id: options.shelfId } : {};
+  const whereClause: Prisma.GoodreadsShelfWhereInput = {};
+  if (options.shelfId) whereClause.id = options.shelfId;
+  if (options.userId) whereClause.userId = options.userId;
+
   const shelves = await prisma.goodreadsShelf.findMany({
     where: whereClause,
     include: { user: { select: { id: true, plexUsername: true } } },
@@ -144,10 +148,10 @@ export async function processGoodreadsShelves(
         continue;
       }
 
-      log.info(`Found ${rssData.books.length} books in shelf "${shelf.name}"`);
+      log.info(`Found ${rssData.books.length} books in shelf "${shelf.name}"${!shelf.autoRequest ? ' (auto-request disabled)' : ''}`);
 
       const bookData = await processShelfBooks(
-        'goodreads', rssData.books, shelf.user.id, shelf.id, stats, log, maxLookups,
+        'goodreads', rssData.books, shelf.user.id, shelf.id, stats, log, maxLookups, shelf.autoRequest,
       );
 
       await prisma.goodreadsShelf.update({

src/lib/services/hardcover-sync.service.ts

@@ -7,6 +7,7 @@
  */
 
 import { prisma } from '@/lib/db';
+import { Prisma } from '@/generated/prisma/client';
 import { getEncryptionService } from '@/lib/services/encryption.service';
 import { RMABLogger } from '@/lib/utils/logger';
 import { fetchHardcoverList, HardcoverApiBook } from '@/lib/services/hardcover-api.service';
@@ -38,8 +39,10 @@ export async function processHardcoverShelves(
   const log = jobLogger || logger;
   const stats = createEmptyStats();
   const maxLookups = resolveMaxLookups(options);
+  const whereClause: Prisma.HardcoverShelfWhereInput = {};
+  if (options.shelfId) whereClause.id = options.shelfId;
+  if (options.userId) whereClause.userId = options.userId;
 
-  const whereClause = options.shelfId ? { id: options.shelfId } : {};
   const shelves = await prisma.hardcoverShelf.findMany({
     where: whereClause,
     include: { user: { select: { id: true, plexUsername: true } } },
@@ -85,10 +88,10 @@ export async function processHardcoverShelves(
         continue;
       }
 
-      log.info(`Found ${fetchedData.books.length} books in list "${shelf.name}" (Hardcover API)`);
+      log.info(`Found ${fetchedData.books.length} books in list "${shelf.name}" (Hardcover API)${!shelf.autoRequest ? ' (auto-request disabled)' : ''}`);
 
       const bookData = await processShelfBooks(
-        'hardcover', fetchedData.books, shelf.user.id, shelf.id, stats, log, maxLookups,
+        'hardcover', fetchedData.books, shelf.user.id, shelf.id, stats, log, maxLookups, shelf.autoRequest,
       );
 
       const finalListName =

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

@@ -112,6 +112,7 @@ export interface SyncShelvesPayload extends JobPayload {
   scheduledJobId?: string;
   shelfId?: string;
   shelfType?: 'goodreads' | 'hardcover';
+  userId?: string;
   maxLookupsPerShelf?: number;
 }
 
@@ -770,7 +771,13 @@ export class JobQueueService {
   /**
    * Add sync reading shelves job
    */
-  async addSyncShelvesJob(scheduledJobId?: string, shelfId?: string, shelfType?: 'goodreads' | 'hardcover', maxLookupsPerShelf?: number): Promise<string> {
+  async addSyncShelvesJob(
+    scheduledJobId?: string,
+    shelfId?: string,
+    shelfType?: 'goodreads' | 'hardcover',
+    maxLookupsPerShelf?: number,
+    userId?: string
+  ): Promise<string> {
     return await this.addJob(
       'sync_reading_shelves',
       {
@@ -778,6 +785,7 @@ export class JobQueueService {
         shelfId,
         shelfType,
         maxLookupsPerShelf,
+        userId,
       } as SyncShelvesPayload,
       {
         priority: 7,

src/lib/services/request-creator.service.ts

@@ -12,7 +12,7 @@ import { getJobQueueService } from '@/lib/services/job-queue.service';
 import { findPlexMatch } from '@/lib/utils/audiobook-matcher';
 import { getAudibleService } from '@/lib/integrations/audible.service';
 import { RMABLogger } from '@/lib/utils/logger';
-import { seedAsin } from '@/lib/services/works.service';
+import { seedAsin, getSiblingAsins } from '@/lib/services/works.service';
 
 const logger = RMABLogger.create('RequestCreator');
 
@@ -27,11 +27,13 @@ export interface CreateRequestInput {
 
 export interface CreateRequestOptions {
   skipAutoSearch?: boolean;
+  /** When true, skip the per-user ignore list check (used for manual requests) */
+  bypassIgnore?: boolean;
 }
 
 export type CreateRequestResult =
   | { success: true; request: any }
-  | { success: false; reason: 'already_available' | 'being_processed' | 'duplicate' | 'user_not_found'; message: string };
+  | { success: false; reason: 'already_available' | 'being_processed' | 'duplicate' | 'user_not_found' | 'ignored'; message: string };
 
 /**
  * Create a request for a user, with full duplicate detection, library checks,
@@ -42,7 +44,7 @@ export async function createRequestForUser(
   audiobook: CreateRequestInput,
   options: CreateRequestOptions = {}
 ): Promise<CreateRequestResult> {
-  const { skipAutoSearch = false } = options;
+  const { skipAutoSearch = false, bypassIgnore = false } = options;
 
   // Check for existing active request (downloaded/available) for this ASIN
   const existingActiveRequest = await prisma.request.findFirst({
@@ -81,6 +83,18 @@ export async function createRequestForUser(
     };
   }
 
+  // Check per-user ignore list (skipped for manual requests via bypassIgnore)
+  if (!bypassIgnore) {
+    const isIgnored = await checkIgnoreList(userId, audiobook.asin);
+    if (isIgnored) {
+      return {
+        success: false,
+        reason: 'ignored',
+        message: 'This audiobook is on your ignore list',
+      };
+    }
+  }
+
   // Fetch full details from Audnexus for year/series
   let year: number | undefined;
   let series: string | undefined;
@@ -279,3 +293,34 @@ export async function createRequestForUser(
 
   return { success: true, request: newRequest };
 }
+
+/**
+ * Check if an ASIN (or any of its sibling ASINs via the works table)
+ * is on the user's ignore list. Returns true if the book should be blocked.
+ */
+async function checkIgnoreList(userId: string, asin: string): Promise<boolean> {
+  // Direct check: is this exact ASIN ignored?
+  const directIgnore = await prisma.ignoredAudiobook.findUnique({
+    where: { userId_asin: { userId, asin } },
+  });
+  if (directIgnore) return true;
+
+  // Works-system expansion: check sibling ASINs
+  try {
+    const siblingMap = await getSiblingAsins([asin]);
+    const siblings = siblingMap.get(asin);
+    if (siblings && siblings.length > 0) {
+      const siblingIgnore = await prisma.ignoredAudiobook.findFirst({
+        where: {
+          userId,
+          asin: { in: siblings },
+        },
+      });
+      if (siblingIgnore) return true;
+    }
+  } catch {
+    // Works expansion is best-effort — if it fails, only direct check applies
+  }
+
+  return false;
+}

src/lib/services/shelf-sync-core.service.ts

@@ -39,6 +39,7 @@ export interface ShelfSyncStats {
 /** Common sync options */
 export interface ShelfSyncOptions {
   shelfId?: string;
+  userId?: string;
   maxLookupsPerShelf?: number;
 }
 
@@ -72,6 +73,7 @@ export async function processShelfBooks(
   stats: ShelfSyncStats,
   log: LoggerType,
   maxLookups: number,
+  autoRequest: boolean = true,
 ): Promise<{ coverUrl: string; asin: string | null; title: string; author: string }[]> {
   stats.booksFound += books.length;
 
@@ -111,7 +113,7 @@ export async function processShelfBooks(
       }
     }
 
-    if (mapping.audibleAsin) {
+    if (mapping.audibleAsin && autoRequest) {
       try {
         const result = await createRequestForUser(userId, {
           asin: mapping.audibleAsin,

src/lib/utils/bulk-import-scanner.ts

@@ -0,0 +1,294 @@
+/**
+ * Component: Bulk Import Scanner Utility
+ * Documentation: documentation/features/bulk-import.md
+ *
+ * Recursively discovers audiobook folders, reads embedded metadata via ffprobe,
+ * and prepares search terms for Audible matching. Used by the bulk import API.
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+import fs from 'fs/promises';
+import { AUDIO_EXTENSIONS } from '../constants/audio-formats';
+
+const execPromise = promisify(exec);
+
+/** Maximum recursion depth for folder scanning. */
+export const MAX_SCAN_DEPTH = 10;
+
+/** Metadata extracted from an audio file via ffprobe. */
+export interface AudioFileMetadata {
+  title?: string;              // From 'album' tag (book title)
+  author?: string;             // From 'album_artist' tag
+  narrator?: string;           // From 'composer' tag
+  contributingArtists?: string; // From 'artist' tag (contributing artists)
+  trackTitle?: string;         // From 'title' tag (chapter/track name)
+}
+
+/** A discovered audiobook folder with its metadata and file info. */
+export interface DiscoveredAudiobook {
+  folderPath: string;
+  folderName: string;
+  relativePath: string;       // Relative to scan root
+  audioFileCount: number;
+  totalSizeBytes: number;
+  metadata: AudioFileMetadata;
+  searchTerm: string;         // Constructed search query for Audible
+  metadataSource: 'tags' | 'file_name';  // Where the search term came from
+}
+
+/** Progress callback for streaming updates to the caller. */
+export interface ScanProgress {
+  phase: 'discovering' | 'reading_metadata';
+  foldersScanned: number;
+  audiobooksFound: number;
+  currentFolder?: string;
+}
+
+/**
+ * Check if a file has a supported audio extension.
+ */
+function isAudioFile(filename: string): boolean {
+  const ext = path.extname(filename).toLowerCase();
+  return (AUDIO_EXTENSIONS as readonly string[]).includes(ext);
+}
+
+/**
+ * Read audio metadata from a file using ffprobe.
+ * Extracts album, album_artist, composer, and title tags.
+ * Returns empty metadata on any failure (non-blocking).
+ */
+export async function readAudioMetadata(filePath: string): Promise<AudioFileMetadata> {
+  try {
+    const command = `ffprobe -v quiet -print_format json -show_format "${filePath}"`;
+    const { stdout } = await execPromise(command, { timeout: 15000 });
+    const data = JSON.parse(stdout);
+
+    const tags = data?.format?.tags || {};
+
+    // ffprobe tag names can be case-insensitive; check common variants
+    const album = tags.album || tags.ALBUM || tags.Album || undefined;
+    const albumArtist = tags.album_artist || tags.ALBUM_ARTIST || tags['Album Artist']
+      || tags.albumartist || tags.ALBUMARTIST || undefined;
+    const composer = tags.composer || tags.COMPOSER || tags.Composer || undefined;
+    const artist = tags.artist || tags.ARTIST || tags.Artist
+      || tags['Contributing artists'] || tags['CONTRIBUTING ARTISTS'] || undefined;
+    const title = tags.title || tags.TITLE || tags.Title || undefined;
+
+    return {
+      title: album || undefined,
+      author: albumArtist || undefined,
+      narrator: composer || undefined,
+      contributingArtists: artist || undefined,
+      trackTitle: title || undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Deduplicate names across author, narrator, and contributing artists fields.
+ * Sometimes Album Artist contains "Author, Narrator" and Composer also has "Narrator",
+ * and Contributing Artists may overlap with both.
+ * We split on common delimiters and cross-reference to remove duplicates.
+ */
+export function deduplicateNames(
+  rawAuthor?: string,
+  rawNarrator?: string,
+  rawContributingArtists?: string
+): { author?: string; narrator?: string; contributingArtists?: string } {
+  const splitNames = (str: string): string[] =>
+    str.split(/[,;&]/).map((s) => s.trim()).filter(Boolean);
+
+  const normalize = (s: string) => s.toLowerCase().replace(/\s+/g, ' ').trim();
+
+  const authorNames = rawAuthor ? splitNames(rawAuthor) : [];
+  const narratorNames = rawNarrator ? splitNames(rawNarrator) : [];
+  const contributingNames = rawContributingArtists ? splitNames(rawContributingArtists) : [];
+
+  // Build sets for cross-referencing
+  const authorNormalized = new Set(authorNames.map(normalize));
+  const narratorNormalized = new Set(narratorNames.map(normalize));
+
+  // Remove from author list any name that appears in narrator list
+  const dedupedAuthors = authorNames.filter(
+    (name) => !narratorNormalized.has(normalize(name))
+  );
+
+  // Remove from contributing artists any name already in author or narrator
+  const allKnown = new Set([...authorNormalized, ...narratorNormalized]);
+  const dedupedContributing = contributingNames.filter(
+    (name) => !allKnown.has(normalize(name))
+  );
+
+  return {
+    author: dedupedAuthors.length > 0 ? dedupedAuthors.join(', ')
+      : rawAuthor || undefined,
+    narrator: rawNarrator || undefined,
+    contributingArtists: dedupedContributing.length > 0
+      ? dedupedContributing.join(', ')
+      : undefined,
+  };
+}
+
+/**
+ * Build a search term from metadata or file name.
+ * Returns the search term and the source it was derived from.
+ * When metadata tags are present, constructs "Title Author Narrator ContributingArtists".
+ * When tags are empty, falls back to the first audio file's name (cleaned).
+ */
+export function buildSearchTerm(
+  metadata: AudioFileMetadata,
+  firstFileName: string
+): { searchTerm: string; source: 'tags' | 'file_name' } {
+  const { author, narrator, contributingArtists } = deduplicateNames(
+    metadata.author,
+    metadata.narrator,
+    metadata.contributingArtists
+  );
+  const title = metadata.title;
+
+  // If we have at least a title from metadata, use tags
+  if (title) {
+    const parts = [title];
+    if (author) parts.push(author);
+    if (narrator) parts.push(narrator);
+    if (contributingArtists) parts.push(contributingArtists);
+    return { searchTerm: parts.join(' '), source: 'tags' };
+  }
+
+  // Fallback: clean up the first audio file name and use it as search term
+  const cleaned = firstFileName
+    .replace(/\.[^.]+$/, '')                       // Remove file extension
+    .replace(/[\[\(][A-Z0-9]{10}[\]\)]/g, '')     // Remove ASIN in brackets
+    .replace(/[\[\(]\d{4}[\]\)]/g, '')             // Remove year in brackets
+    .replace(/^\d+[\s._-]+/, '')                   // Remove leading track numbers
+    .replace(/[_]/g, ' ')                           // Underscores to spaces
+    .replace(/\s+/g, ' ')                           // Collapse whitespace
+    .trim();
+
+  return { searchTerm: cleaned || firstFileName, source: 'file_name' };
+}
+
+/**
+ * Scan a single directory for audio files.
+ * Returns audio file names and total size, or null if no audio files found.
+ */
+async function scanDirectoryForAudio(
+  dirPath: string
+): Promise<{ audioFiles: string[]; totalSize: number } | null> {
+  try {
+    const children = await fs.readdir(dirPath, { withFileTypes: true });
+    const audioFiles: string[] = [];
+    let totalSize = 0;
+
+    for (const child of children) {
+      if (child.isFile() && isAudioFile(child.name)) {
+        audioFiles.push(child.name);
+        try {
+          const stat = await fs.stat(path.join(dirPath, child.name));
+          totalSize += stat.size;
+        } catch {
+          /* skip unreadable files */
+        }
+      }
+    }
+
+    if (audioFiles.length === 0) return null;
+
+    audioFiles.sort((a, b) => a.localeCompare(b));
+    return { audioFiles, totalSize };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Recursively discover audiobook folders starting from a root path.
+ *
+ * A folder is classified as an "audiobook folder" if it contains audio files.
+ * Once a folder is classified as an audiobook, its subfolders are NOT scanned
+ * further (the audio-containing folder is the audiobook boundary).
+ *
+ * @param rootPath - The root directory to scan
+ * @param onProgress - Optional callback for progress updates
+ * @param abortSignal - Optional AbortSignal to cancel the scan
+ * @returns Array of discovered audiobook folders with metadata
+ */
+export async function discoverAudiobooks(
+  rootPath: string,
+  onProgress?: (progress: ScanProgress) => void,
+  abortSignal?: AbortSignal
+): Promise<DiscoveredAudiobook[]> {
+  const results: DiscoveredAudiobook[] = [];
+  let foldersScanned = 0;
+
+  async function walk(currentPath: string, depth: number): Promise<void> {
+    if (depth > MAX_SCAN_DEPTH) return;
+    if (abortSignal?.aborted) return;
+
+    foldersScanned++;
+
+    onProgress?.({
+      phase: 'discovering',
+      foldersScanned,
+      audiobooksFound: results.length,
+      currentFolder: path.basename(currentPath),
+    });
+
+    // Check if this folder contains audio files
+    const audioResult = await scanDirectoryForAudio(currentPath);
+
+    if (audioResult) {
+      // This is an audiobook folder — read metadata and add to results
+      const firstFile = path.join(currentPath, audioResult.audioFiles[0]);
+      const metadata = await readAudioMetadata(firstFile);
+
+      onProgress?.({
+        phase: 'reading_metadata',
+        foldersScanned,
+        audiobooksFound: results.length + 1,
+        currentFolder: path.basename(currentPath),
+      });
+
+      const folderName = path.basename(currentPath);
+      const relativePath = path.relative(rootPath, currentPath).replace(/\\/g, '/');
+      const firstFileName = audioResult.audioFiles[0];
+      const { searchTerm, source } = buildSearchTerm(metadata, firstFileName);
+
+      results.push({
+        folderPath: currentPath.replace(/\\/g, '/'),
+        folderName,
+        relativePath: relativePath || folderName,
+        audioFileCount: audioResult.audioFiles.length,
+        totalSizeBytes: audioResult.totalSize,
+        metadata,
+        searchTerm,
+        metadataSource: source,
+      });
+
+      // Do NOT recurse into subfolders of audiobook folders
+      return;
+    }
+
+    // No audio files here — recurse into subfolders
+    try {
+      const children = await fs.readdir(currentPath, { withFileTypes: true });
+      const subdirs = children
+        .filter((c) => c.isDirectory() && !c.name.startsWith('.'))
+        .sort((a, b) => a.name.localeCompare(b.name));
+
+      for (const subdir of subdirs) {
+        if (abortSignal?.aborted) return;
+        await walk(path.join(currentPath, subdir.name), depth + 1);
+      }
+    } catch {
+      /* directory not readable — skip */
+    }
+  }
+
+  await walk(rootPath, 0);
+  return results;
+}

src/lib/utils/chapter-merger.ts

@@ -62,6 +62,7 @@ export interface MergeOptions {
   year?: number;
   asin?: string;
   outputPath: string;
+  dirMode?: number;
 }
 
 export interface MergeResult {
@@ -616,7 +617,7 @@ export async function mergeChapters(
     await logger?.info(`✓ All ${chapters.length} source files validated`);
 
     // Ensure temp directory exists
-    await fs.mkdir(tempDir, { recursive: true });
+    await fs.mkdir(tempDir, { recursive: true, ...(options.dirMode !== undefined && { mode: options.dirMode }) });
 
     // Create concat file
     const concatContent = chapters

src/lib/utils/deduplicate-audiobooks.ts

@@ -6,7 +6,7 @@
  * under different ASINs (publisher re-listings, rights transfers, etc.).
  *
  * Dedup key: normalized title + normalized narrator
- * Duration tolerance: max(longerDuration * 0.01, 5) minutes
+ * Duration tolerance: max(longerDuration * 0.05, 10) minutes
  * Missing duration treated as compatible (graceful degradation).
  */
 
@@ -19,7 +19,7 @@ import type { AudibleAudiobook } from '../integrations/audible.service';
 /** Patterns in parentheses or brackets to strip (edition markers, format labels) */
 const EDITION_PAREN_RE = /[([][^)\]]*?(?:unabridged|abridged|edition|remaster(?:ed)?|anniversary|complete|original|version|narrat(?:ed|or)?|audio(?:book)?|full cast|dramatiz(?:ed|ation))[^)\]]*[)\]]/gi;
 
-/** Trailing subtitle after colon or long dash */
+/** Trailing subtitle after colon or long dash (used for extraction, not blind stripping) */
 const SUBTITLE_RE = /\s*[:]\s+.+$/;
 const LONG_DASH_SUBTITLE_RE = /\s+[-\u2013\u2014]\s+.+$/;
 
@@ -44,6 +44,44 @@ export function normalizeTitle(title: string): string {
   return t.replace(/\s+/g, ' ').trim();
 }
 
+/**
+ * Extract the subtitle portion from a title (part after colon or long dash).
+ * Returns empty string if no subtitle found.
+ * Used to prevent false dedup of series books like "Series: Book A" vs "Series: Book B".
+ */
+export function extractSubtitle(title: string): string {
+  let t = title.toLowerCase();
+  // Remove parenthesized/bracketed edition markers first (same as normalizeTitle)
+  t = t.replace(EDITION_PAREN_RE, '');
+  // Remove trailing descriptors
+  t = t.replace(TRAILING_DESCRIPTOR_RE, '');
+  t = t.replace(/\s+/g, ' ').trim();
+
+  // Try colon subtitle
+  const colonMatch = t.match(/\s*[:]\s+(.+)$/);
+  if (colonMatch) return colonMatch[1].trim();
+
+  // Try long dash subtitle
+  const dashMatch = t.match(/\s+[-\u2013\u2014]\s+(.+)$/);
+  if (dashMatch) return dashMatch[1].trim();
+
+  return '';
+}
+
+/**
+ * Check if two titles' subtitles are compatible for dedup purposes.
+ * - Both have no subtitle → compatible
+ * - One has a subtitle, other doesn't → compatible (re-listing with/without subtitle)
+ * - Both have the SAME subtitle → compatible
+ * - Both have DIFFERENT subtitles → NOT compatible (different books, e.g. series entries)
+ */
+function areSubtitlesCompatible(titleA: string, titleB: string): boolean {
+  const subA = extractSubtitle(titleA);
+  const subB = extractSubtitle(titleB);
+  if (!subA || !subB) return true; // one or both missing → compatible
+  return subA === subB;
+}
+
 /** Normalize narrator for comparison. Sorts individual names so order doesn't matter. */
 function normalizeNarrator(narrator?: string): string {
   const raw = (narrator || '').toLowerCase().trim();
@@ -57,13 +95,13 @@ function normalizeNarrator(narrator?: string): string {
 
 /**
  * Check if two durations are compatible (represent the same recording).
- * Tolerance: max(longerDuration * 0.01, 5) minutes.
+ * Tolerance: max(longerDuration * 0.05, 10) minutes.
  * Missing duration on either side is treated as compatible.
  */
 export function areDurationsCompatible(a?: number, b?: number): boolean {
   if (a == null || b == null) return true;
   const longer = Math.max(a, b);
-  const tolerance = Math.max(longer * 0.01, 5);
+  const tolerance = Math.max(longer * 0.05, 10);
   return Math.abs(a - b) <= tolerance;
 }
 
@@ -152,16 +190,20 @@ export function deduplicateAndCollectGroups(books: AudibleAudiobook[]): Deduplic
       continue;
     }
 
-    // Within a title+narrator group, further split by duration compatibility.
-    // Build sub-groups where all members are duration-compatible with the
-    // representative (first member). A book joins the first compatible sub-group.
+    // Within a title+narrator group, further split by duration AND subtitle
+    // compatibility. Build sub-groups where all members are compatible with
+    // the representative (first member). A book joins the first compatible sub-group.
+    // This prevents false dedup of series entries like "Series: Book A" vs "Series: Book B".
     const subGroups: AudibleAudiobook[][] = [];
 
     for (const book of group) {
       let placed = false;
       for (const sg of subGroups) {
-        // Check compatibility against the representative (first member)
-        if (areDurationsCompatible(sg[0].durationMinutes, book.durationMinutes)) {
+        // Check both duration and subtitle compatibility against the representative
+        if (
+          areDurationsCompatible(sg[0].durationMinutes, book.durationMinutes) &&
+          areSubtitlesCompatible(sg[0].title, book.title)
+        ) {
           sg.push(book);
           placed = true;
           break;

src/lib/utils/epub-fixer.ts

@@ -17,6 +17,7 @@ import * as cheerio from 'cheerio';
 import path from 'path';
 import fs from 'fs/promises';
 import { RMABLogger } from './logger';
+import { getConfigService } from '../services/config.service';
 
 const moduleLogger = RMABLogger.create('EpubFixer');
 
@@ -204,7 +205,10 @@ export async function fixEpubForKindle(
     // Create unique temp subdirectory to avoid filename conflicts
     // This preserves the original filename for the final organized file
     const uniqueDir = path.join(tempDir, `kindle-fix-${Date.now()}`);
-    await fs.mkdir(uniqueDir, { recursive: true });
+    const configService = getConfigService();
+    const dirChmodStr = await configService.get('dir_chmod') || '775';
+    const dirMode = parseInt(dirChmodStr, 8);
+    await fs.mkdir(uniqueDir, { recursive: true, mode: dirMode });
 
     // Keep original filename
     const sourceFilename = path.basename(sourcePath);

src/lib/utils/file-organizer.ts

@@ -64,10 +64,14 @@ export interface LoggerConfig {
 export class FileOrganizer {
   private mediaDir: string;
   private tempDir: string;
+  private fileMode: number;
+  private dirMode: number;
 
-  constructor(mediaDir: string = '/media/audiobooks', tempDir: string = '/tmp/readmeabook') {
+  constructor(mediaDir: string = '/media/audiobooks', tempDir: string = '/tmp/readmeabook', fileMode: number = 0o664, dirMode: number = 0o775) {
     this.mediaDir = mediaDir;
     this.tempDir = tempDir;
+    this.fileMode = fileMode;
+    this.dirMode = dirMode;
   }
 
   /**
@@ -166,6 +170,7 @@ export class FileOrganizer {
                       year: audiobook.year,
                       asin: audiobook.asin,
                       outputPath,
+                      dirMode: this.dirMode,
                     },
                     logger ?? undefined
                   );
@@ -293,7 +298,7 @@ export class FileOrganizer {
       await logger?.info(`Target path: ${targetPath}`);
 
       // Create target directory
-      await fs.mkdir(targetPath, { recursive: true });
+      await fs.mkdir(targetPath, { recursive: true, mode: this.dirMode });
 
       // Determine if file renaming should be applied
       const shouldRename = renameConfig?.enabled && renameConfig.template;
@@ -386,7 +391,7 @@ export class FileOrganizer {
           // Copy file via streams (avoids copy_file_range EPERM on NFS/FUSE)
           await copyFile(sourcePath, targetFilePath);
           // Set explicit permissions after copy
-          await fs.chmod(targetFilePath, 0o644);
+          await fs.chmod(targetFilePath, this.fileMode);
 
           result.audioFiles.push(targetFilePath);
           result.filesMovedCount++;
@@ -422,7 +427,7 @@ export class FileOrganizer {
             try {
               await fs.access(originalSourcePath, fs.constants.R_OK);
               await copyFile(originalSourcePath, targetFilePath);
-              await fs.chmod(targetFilePath, 0o644);
+              await fs.chmod(targetFilePath, this.fileMode);
               result.audioFiles.push(targetFilePath);
               result.filesMovedCount++;
               await logger?.info(`Fallback copy succeeded (without metadata tags): ${filename}`);
@@ -457,7 +462,7 @@ export class FileOrganizer {
         try {
           // Copy cover art (do NOT delete original)
           await copyFile(sourcePath, targetCoverPath);
-          await fs.chmod(targetCoverPath, 0o644);
+          await fs.chmod(targetCoverPath, this.fileMode);
           result.coverArtFile = targetCoverPath;
           result.filesMovedCount++;
           await logger?.info(`Copied cover art`);
@@ -718,7 +723,7 @@ export class FileOrganizer {
 
         // Copy from local cache instead of downloading
         await copyFile(cachedPath, targetPath);
-        await fs.chmod(targetPath, 0o644);
+        await fs.chmod(targetPath, this.fileMode);
         moduleLogger.debug(`Copied cover art from cache: ${filename}`);
       } else {
         // Download from external URL (e.g., Audible CDN)
@@ -846,7 +851,7 @@ export class FileOrganizer {
       await logger?.info(`Target directory: ${targetDir}`);
 
       // Create target directory
-      await fs.mkdir(targetDir, { recursive: true });
+      await fs.mkdir(targetDir, { recursive: true, mode: this.dirMode });
 
       // Build target filename (apply rename template if enabled, otherwise sanitize source filename)
       const sourceFilename = path.basename(ebookFile);
@@ -882,7 +887,7 @@ export class FileOrganizer {
 
       // Copy ebook file (do NOT delete original - may need for seeding or retry)
       await copyFile(sourceFilePath, targetPath);
-      await fs.chmod(targetPath, 0o644);
+      await fs.chmod(targetPath, this.fileMode);
 
       await logger?.info(`Copied ebook: ${targetFilename}`);
 
@@ -968,7 +973,7 @@ export class FileOrganizer {
 
 /**
  * Get FileOrganizer instance configured from database settings
- * Reads media_dir from database configuration, falls back to /media/audiobooks if not configured
+ * Reads media_dir, file_chmod, dir_chmod from database configuration
  */
 export async function getFileOrganizer(): Promise<FileOrganizer> {
   // Read media_dir from database config
@@ -979,7 +984,15 @@ export async function getFileOrganizer(): Promise<FileOrganizer> {
   const mediaDir = config?.value || process.env.MEDIA_DIR || '/media/audiobooks';
   const tempDir = process.env.TEMP_DIR || '/tmp/readmeabook';
 
-  return new FileOrganizer(mediaDir, tempDir);
+  // Read file/directory permission settings
+  const { getConfigService } = await import('../services/config.service');
+  const configService = getConfigService();
+  const fileChmodStr = await configService.get('file_chmod') || '664';
+  const dirChmodStr = await configService.get('dir_chmod') || '775';
+  const fileMode = parseInt(fileChmodStr, 8);
+  const dirMode = parseInt(dirChmodStr, 8);
+
+  return new FileOrganizer(mediaDir, tempDir, fileMode, dirMode);
 }
 
 /**

src/lib/utils/ignored-audiobooks.ts

@@ -0,0 +1,37 @@
+/**
+ * Component: Ignored Audiobooks Utility
+ * Documentation: documentation/features/ignored-audiobooks.md
+ *
+ * Shared utility for annotating audiobook lists with per-user ignore status.
+ * Uses a single bulk query for the user's full ignore list, then annotates in-memory.
+ */
+
+import { prisma } from '@/lib/db';
+
+/**
+ * Annotate an array of audiobook objects with `isIgnored: boolean`.
+ * Fetches the user's full ignore list in one query and matches by ASIN.
+ *
+ * If userId is undefined (unauthenticated), all books get `isIgnored: false`.
+ */
+export async function annotateWithIgnoreStatus<T extends { asin: string }>(
+  audiobooks: T[],
+  userId?: string
+): Promise<(T & { isIgnored: boolean })[]> {
+  if (!userId || audiobooks.length === 0) {
+    return audiobooks.map((book) => ({ ...book, isIgnored: false }));
+  }
+
+  // Single query: get all ASINs this user has ignored
+  const ignoredEntries = await prisma.ignoredAudiobook.findMany({
+    where: { userId },
+    select: { asin: true },
+  });
+
+  const ignoredAsinSet = new Set(ignoredEntries.map((e) => e.asin));
+
+  return audiobooks.map((book) => ({
+    ...book,
+    isIgnored: ignoredAsinSet.has(book.asin),
+  }));
+}

src/lib/utils/jwt.ts

@@ -20,11 +20,13 @@ export interface TokenPayload {
   plexId: string;
   username: string;
   role: string;
+  iat?: number; // Issued-at (auto-set by jsonwebtoken)
 }
 
 export interface RefreshTokenPayload {
   sub: string;
   type: 'refresh';
+  iat?: number; // Issued-at (auto-set by jsonwebtoken)
 }
 
 /**

src/lib/utils/rateLimit.ts

@@ -1,8 +1,8 @@
 /**
- * Component: API Token Rate Limiting
- * Documentation: documentation/backend/services/api-tokens.md
+ * Component: Rate Limiting
+ * Documentation: documentation/backend/services/auth.md
  *
- * In-memory sliding-window rate limiter with lazy eviction and periodic sweep
+ * In-memory fixed-window rate limiter with lazy eviction and periodic sweep
  * to prevent unbounded memory growth.
  */
 
@@ -11,7 +11,7 @@ type Bucket = {
   resetAt: number;
 };
 
-type RateLimitResult = {
+export type RateLimitResult = {
   allowed: boolean;
   retryAfterSeconds: number;
 };
@@ -37,7 +37,7 @@ function sweepExpiredBuckets(): void {
   }
 }
 
-function checkRateLimit(key: string, maxRequests: number, windowMs: number): RateLimitResult {
+export function checkRateLimit(key: string, maxRequests: number, windowMs: number): RateLimitResult {
   const now = Date.now();
 
   // Periodic full sweep every SWEEP_INTERVAL calls
@@ -72,14 +72,21 @@ function checkRateLimit(key: string, maxRequests: number, windowMs: number): Rat
   };
 }
 
+/** 10 attempts per minute per actor */
 export function checkApiTokenCreateRateLimit(actorId: string): RateLimitResult {
   return checkRateLimit(`api-token-create:${actorId}`, 10, 60 * 1000);
 }
 
+/** 20 attempts per minute per actor */
 export function checkApiTokenRevokeRateLimit(actorId: string): RateLimitResult {
   return checkRateLimit(`api-token-revoke:${actorId}`, 20, 60 * 1000);
 }
 
+/** 10 attempts per 15 minutes per IP */
+export function checkTokenLoginRateLimit(ip: string): RateLimitResult {
+  return checkRateLimit(`token-login:${ip}`, 10, 15 * 60 * 1000);
+}
+
 /** Reset all buckets and the sweep counter. For testing only. */
 export function _resetBuckets(): void {
   buckets.clear();

tests/api/admin-api-tokens.routes.test.ts

@@ -29,7 +29,7 @@ vi.mock('@/lib/middleware/auth', () => ({
   requireAdmin: requireAdminMock,
 }));
 
-vi.mock('@/lib/utils/apiTokenRateLimit', () => ({
+vi.mock('@/lib/utils/rateLimit', () => ({
   checkApiTokenCreateRateLimit: checkApiTokenCreateRateLimitMock,
 }));