From 3699f9c2289bb342a81003c3424f14d884155c67 Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Tue, 10 Mar 2026 16:36:01 -0500
Subject: [PATCH 01/20] Fix #169: Expand clean_search_title regex to handle
 special chars in author names (#178)

The "by Author" stripping regex now handles periods (F. Scott Fitzgerald),
apostrophes (O'Brien), hyphens (Mary-Jane), and trailing parenthetical
content like (Audiobook)(Nonfiction).

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 library_manager/utils/naming.py |  2 +-
 test-env/test-naming-issues.py  | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/library_manager/utils/naming.py b/library_manager/utils/naming.py
index 92d1511..98c18b2 100644
--- a/library_manager/utils/naming.py
+++ b/library_manager/utils/naming.py
@@ -113,7 +113,7 @@ def clean_search_title(messy_name):
     # Remove file extensions
     clean = re.sub(r'\.(mp3|m4b|m4a|epub|pdf|mobi|webm|opus)$', '', clean, flags=re.IGNORECASE)
     # Remove "by Author" at the end temporarily for searching
-    clean = re.sub(r'\s+by\s+[\w\s]+$', '', clean, flags=re.IGNORECASE)
+    clean = re.sub(r'\s+by\s+[\w\s.\'\-]+(?:\s*\([^)]*\))*$', '', clean, flags=re.IGNORECASE)
     # Remove audiobook-related junk (YouTube rip artifacts)
     clean = re.sub(r'\b(full\s+)?audiobook\b', '', clean, flags=re.IGNORECASE)
     clean = re.sub(r'\b(complete|unabridged|abridged)\b', '', clean, flags=re.IGNORECASE)
diff --git a/test-env/test-naming-issues.py b/test-env/test-naming-issues.py
index 4e36e63..483e463 100644
--- a/test-env/test-naming-issues.py
+++ b/test-env/test-naming-issues.py
@@ -1422,6 +1422,38 @@ def is_book_like_folder(name):
     else:
         failed += 1
 
+    # ==========================================
+    # Issue #169: clean_search_title "by Author" regex edge cases
+    # ==========================================
+    print("\n--- Issue #169: 'by Author' regex handles special characters ---")
+
+    by_author_tests = [
+        # Basic case (already worked)
+        ("The Great Gatsby by F Scott Fitzgerald", "The Great Gatsby"),
+        # Periods/initials in author name
+        ("The Great Gatsby by F. Scott Fitzgerald", "The Great Gatsby"),
+        ("A Space Odyssey by Arthur C. Clarke", "A Space Odyssey"),
+        # Apostrophes in author name
+        ("Leaving Las Vegas by John O'Brien", "Leaving Las Vegas"),
+        # Hyphens in author name
+        ("The Joy Luck Club by Mary-Jane Smith", "The Joy Luck Club"),
+        # Parenthetical content after author
+        ("LAST RITES by Ozzy Osbourne (Audiobook)(Nonfiction)", "LAST RITES"),
+        ("Some Book by Jane Doe (Unabridged)", "Some Book"),
+        # Combined edge cases
+        ("A Tale by J.R.R. Tolkien (Fantasy)", "A Tale"),
+        ("My Book by Mary O'Brien-Smith (Audiobook)", "My Book"),
+    ]
+
+    for input_title, expected in by_author_tests:
+        result = clean_search_title(input_title)
+        if test_result(f"By-author strip: '{input_title}'",
+                       result.strip() == expected,
+                       f"Expected '{expected}', got '{result.strip()}'"):
+            passed += 1
+        else:
+            failed += 1
+
     # ==========================================
     # Summary
     # ==========================================

From d51dac576aed2023d2fbe51416c880c0a7ec4636 Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Tue, 10 Mar 2026 16:36:03 -0500
Subject: [PATCH 02/20] feat: Integrate file validation into scan pipeline
 (#110) (#179)

* Fix #110: Integrate file validation into scan pipeline

Wire up the existing file_validation.py module into deep_scan_library()
so invalid audio files (corrupt, truncated, too short) are caught before
they enter the processing queue.

Changes:
- database.py: Add validation_status and validation_reason columns to books table
- config.py: Add enable_file_validation, min_audio_duration_seconds, min_audio_file_size_mb settings
- file_validation.py: Accept configurable min_duration and min_size overrides
- app.py: Import and call validate_audio_file at all 4 queue insertion points
  (loose files, flat books, series books, regular books). Invalid files get
  status='validation_failed' and are excluded from the queue. ffprobe
  unavailability is non-blocking (validation skipped gracefully).
- app.py: Add validation_failed counts to dashboard, /api/stats, and /api/library
- database.py: Add validation_failed to should_requeue_book skip list
- dashboard.html: Show validation failure alert when count > 0
- settings.html: Add File Validation toggle with configurable thresholds

* chore: Bump version to beta.135 for file validation integration (#110)

---------

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 CHANGELOG.md                       |  13 +++
 README.md                          |   2 +-
 app.py                             | 146 ++++++++++++++++++++++++++++-
 library_manager/config.py          |   6 +-
 library_manager/database.py        |  13 ++-
 library_manager/file_validation.py |  17 +++-
 templates/dashboard.html           |  15 +++
 templates/settings.html            |  27 ++++++
 8 files changed, 232 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 226fac1..ec063ac 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,19 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.135] - 2026-03-10
+
+### Added
+
+- **Issue #110: File validation in scan pipeline** - The existing `file_validation.py` module is now
+  integrated into the scan pipeline. Audio files are validated with ffprobe before queuing — corrupt,
+  truncated, or too-short files are marked `validation_failed` and skipped. Enabled by default,
+  requires ffprobe (gracefully skips if unavailable). Configurable thresholds in Settings: minimum
+  duration (default 10 min) and minimum file size (default 1 MB). Dashboard shows a warning when
+  validation failures exist. Books with `validation_failed` status are excluded from re-queuing.
+
+---
+
 ## [0.9.0-beta.134] - 2026-02-28
 
 ### Fixed
diff --git a/README.md b/README.md
index 145c6ce..4ad36bb 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.134-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.135-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
diff --git a/app.py b/app.py
index 78562d3..aefc156 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.134"
+APP_VERSION = "0.9.0-beta.135"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
@@ -118,6 +118,7 @@
     get_system_info, store_feedback, sanitize_string as feedback_sanitize,
 )
 from library_manager.folder_triage import triage_folder, triage_book_path, should_use_path_hints, confidence_modifier
+from library_manager.file_validation import validate_audio_file, check_ffmpeg_available
 from library_manager.hints import get_all_hints
 from library_manager.hooks import hooks_bp, run_hooks, build_hook_context
 
@@ -4859,6 +4860,53 @@ def compare_book_folders(source_path, dest_path, deep_analysis=True):
     return result
 
 
+def _validate_book_audio(book_path, config, ffmpeg_available):
+    """Issue #110: Validate a book's audio file before queueing.
+
+    Finds the first audio file in the book folder and validates it.
+
+    Args:
+        book_path: Path to the book folder (or file for loose files)
+        config: Configuration dictionary
+        ffmpeg_available: Whether ffprobe/ffmpeg are available
+
+    Returns:
+        (status, reason) where:
+        - ('valid', 'valid') - file passed validation
+        - ('invalid', reason) - file failed validation
+        - ('skipped', reason) - validation was skipped (disabled or ffmpeg unavailable)
+    """
+    if not config.get('enable_file_validation', True):
+        return 'skipped', 'validation_disabled'
+
+    if not ffmpeg_available:
+        return 'skipped', 'ffprobe_not_available'
+
+    # Determine audio file to validate
+    path = Path(book_path)
+    if path.is_file():
+        audio_file = str(path)
+    else:
+        audio_file = get_first_audio_file(str(path))
+
+    if not audio_file:
+        return 'skipped', 'no_audio_file_found'
+
+    # Get config thresholds
+    min_duration = config.get('min_audio_duration_seconds', 600)
+    min_size_mb = config.get('min_audio_file_size_mb', 1)
+    min_size_bytes = min_size_mb * 1_000_000
+
+    is_valid, reason, metadata = validate_audio_file(
+        audio_file, min_duration=min_duration, min_size=min_size_bytes
+    )
+
+    if is_valid:
+        return 'valid', 'valid'
+    else:
+        return 'invalid', reason
+
+
 def deep_scan_library(config):
     """
     Deep scan library - the AUTISTIC LIBRARIAN approach.
@@ -4870,9 +4918,18 @@ def deep_scan_library(config):
     checked = 0  # Total book folders examined
     scanned = 0  # New books added to tracking
     queued = 0   # Books added to fix queue
+    validation_counts = {'valid': 0, 'invalid': 0, 'skipped': 0}  # Issue #110: File validation stats
     issues_found = {}  # path -> list of issues
     triage_counts = {'clean': 0, 'messy': 0, 'garbage': 0}  # Issue #110: Folder triage stats
 
+    # Issue #110: Check ffmpeg availability once at scan start
+    ffmpeg_available, ffmpeg_msg = check_ffmpeg_available()
+    if config.get('enable_file_validation', True):
+        if ffmpeg_available:
+            logger.info("[VALIDATION] ffprobe available - file validation enabled")
+        else:
+            logger.warning(f"[VALIDATION] {ffmpeg_msg} - file validation will be skipped")
+
     # Track files for duplicate detection
     file_signatures = {}  # signature -> list of paths
     file_names = {}  # basename -> list of paths
@@ -4940,6 +4997,17 @@ def deep_scan_library(config):
                     book_id = c.lastrowid
                     reset_layer = 1  # New books always start at layer 1
 
+                # Issue #110: Validate audio file before queueing
+                v_status, v_reason = _validate_book_audio(path_str, config, ffmpeg_available)
+                validation_counts[v_status] = validation_counts.get(v_status, 0) + 1
+                c.execute('UPDATE books SET validation_status = ?, validation_reason = ? WHERE id = ?',
+                         (v_status, v_reason, book_id))
+                if v_status == 'invalid':
+                    c.execute('UPDATE books SET status = ? WHERE id = ?', ('validation_failed', book_id))
+                    conn.commit()
+                    logger.info(f"[VALIDATION] Skipping invalid loose file ({v_reason}): {filename}")
+                    continue
+
                 # Add to queue with special "loose_file" reason
                 c.execute('''INSERT OR REPLACE INTO queue
                             (book_id, reason, added_at, priority)
@@ -5068,6 +5136,17 @@ def deep_scan_library(config):
                     reset_layer = 1
                     logger.info(f"Added flat book: {flat_author} - {flat_title} (triage: {flat_triage})")
 
+                # Issue #110: Validate audio file before queueing
+                v_status, v_reason = _validate_book_audio(flat_path, config, ffmpeg_available)
+                validation_counts[v_status] = validation_counts.get(v_status, 0) + 1
+                c.execute('UPDATE books SET validation_status = ?, validation_reason = ? WHERE id = ?',
+                         (v_status, v_reason, flat_book_id))
+                if v_status == 'invalid':
+                    c.execute('UPDATE books SET status = ? WHERE id = ?', ('validation_failed', flat_book_id))
+                    conn.commit()
+                    logger.info(f"[VALIDATION] Skipping invalid flat book ({v_reason}): {flat_author} - {flat_title}")
+                    continue
+
                 # Queue for processing
                 c.execute('SELECT id FROM queue WHERE book_id = ?', (flat_book_id,))
                 if not c.fetchone():
@@ -5236,6 +5315,17 @@ def deep_scan_library(config):
                                 scanned += 1
                                 reset_layer = 1
 
+                            # Issue #110: Validate audio file before queueing
+                            v_status, v_reason = _validate_book_audio(book_path, config, ffmpeg_available)
+                            validation_counts[v_status] = validation_counts.get(v_status, 0) + 1
+                            c.execute('UPDATE books SET validation_status = ?, validation_reason = ? WHERE id = ?',
+                                     (v_status, v_reason, book_id))
+                            if v_status == 'invalid':
+                                c.execute('UPDATE books SET status = ? WHERE id = ?', ('validation_failed', book_id))
+                                conn.commit()
+                                logger.info(f"[VALIDATION] Skipping invalid series book ({v_reason}): {author}/{book_title}")
+                                continue
+
                             # Queue for processing
                             c.execute('SELECT id FROM queue WHERE book_id = ?', (book_id,))
                             if not c.fetchone():
@@ -5356,6 +5446,17 @@ def deep_scan_library(config):
                     scanned += 1
                     reset_layer = 1
 
+                # Issue #110: Validate audio file before queueing
+                v_status, v_reason = _validate_book_audio(path, config, ffmpeg_available)
+                validation_counts[v_status] = validation_counts.get(v_status, 0) + 1
+                c.execute('UPDATE books SET validation_status = ?, validation_reason = ? WHERE id = ?',
+                         (v_status, v_reason, book_id))
+                if v_status == 'invalid':
+                    c.execute('UPDATE books SET status = ? WHERE id = ?', ('validation_failed', book_id))
+                    conn.commit()
+                    logger.info(f"[VALIDATION] Skipping invalid book ({v_reason}): {author}/{title}")
+                    continue
+
                 # Add to queue if has issues
                 if all_issues:
                     # Skip multi-book collections - they need manual splitting, not renaming
@@ -5412,6 +5513,7 @@ def deep_scan_library(config):
     logger.info(f"Queued: {queued} books need fixing")
     logger.info(f"Already correct: {checked - queued} books")
     logger.info(f"Folder triage: {triage_counts['clean']} clean, {triage_counts['messy']} messy, {triage_counts['garbage']} garbage")
+    logger.info(f"File validation: {validation_counts['valid']} valid, {validation_counts['invalid']} invalid, {validation_counts['skipped']} skipped")
 
     return checked, scanned, queued
 
@@ -6923,6 +7025,10 @@ def dashboard():
                  WHERE h.status = 'pending_fix' ''')
     pending_fixes = c.fetchone()['count']
 
+    # Issue #110: Count validation failures
+    c.execute("SELECT COUNT(*) as count FROM books WHERE validation_status = 'invalid'")
+    validation_failed_count = c.fetchone()['count']
+
     # Get recent history (use LEFT JOIN in case book was deleted)
     c.execute('''SELECT h.*, b.path FROM history h
                  LEFT JOIN books b ON h.book_id = b.id
@@ -6944,6 +7050,7 @@ def dashboard():
                           fixed_count=fixed_count,
                           verified_count=verified_count,
                           pending_fixes=pending_fixes,
+                          validation_failed_count=validation_failed_count,
                           recent_history=recent_history,
                           daily_stats=daily_stats,
                           config=config,
@@ -7200,6 +7307,11 @@ def settings_page():
         # P2P cache setting (Issue #62)
         config['enable_p2p_cache'] = 'enable_p2p_cache' in request.form
 
+        # Issue #110: File validation settings
+        config['enable_file_validation'] = 'enable_file_validation' in request.form
+        config['min_audio_duration_seconds'] = int(request.form.get('min_audio_duration_seconds', 600))
+        config['min_audio_file_size_mb'] = int(request.form.get('min_audio_file_size_mb', 1))
+
         # Provider chain settings - parse comma-separated values into lists
         audio_chain_str = request.form.get('audio_provider_chain', 'bookdb,gemini').strip()
         config['audio_provider_chain'] = [p.strip() for p in audio_chain_str.split(',') if p.strip()]
@@ -8722,6 +8834,10 @@ def api_stats():
     c.execute("SELECT COUNT(*) as count FROM books WHERE status = 'verified'")
     verified = c.fetchone()['count']
 
+    # Issue #110: Validation failure count
+    c.execute("SELECT COUNT(*) as count FROM books WHERE validation_status = 'invalid'")
+    validation_failed = c.fetchone()['count']
+
     conn.close()
 
     return jsonify({
@@ -8730,6 +8846,7 @@ def api_stats():
         'fixed': fixed,
         'pending_fixes': pending,
         'verified': verified,
+        'validation_failed': validation_failed,
         'worker_running': is_worker_running(),
         'processing': get_processing_status()
     })
@@ -9230,6 +9347,10 @@ def build_order_by(sort_cols, default_order):
     c.execute("SELECT COUNT(*) FROM books WHERE user_locked = 1")
     counts['locked'] = c.fetchone()[0]
 
+    # Issue #110: Count validation failures
+    c.execute("SELECT COUNT(*) FROM books WHERE validation_status = 'invalid'")
+    counts['validation_failed'] = c.fetchone()[0]
+
     # Count orphans (detected on-the-fly)
     orphan_list = []
     for lib_path in config.get('library_paths', []):
@@ -9468,6 +9589,27 @@ def build_order_by(sort_cols, default_order):
                 'user_locked': True
             })
 
+    # Issue #110: Validation failed filter
+    elif status_filter == 'validation_failed':
+        order = build_order_by(BOOK_SORT_COLS, 'current_author, current_title')
+        c.execute('''SELECT id, path, current_author, current_title, status, updated_at,
+                            validation_status, validation_reason
+                     FROM books
+                     WHERE validation_status = 'invalid'
+                     ''' + order + '''
+                     LIMIT ? OFFSET ?''', (per_page, offset))
+        for row in c.fetchall():
+            items.append({
+                'id': row['id'],
+                'type': 'book',
+                'book_id': row['id'],
+                'author': row['current_author'],
+                'title': row['current_title'],
+                'path': row['path'],
+                'status': 'validation_failed',
+                'validation_reason': row['validation_reason']
+            })
+
     # Issue #53: Media type filters
     elif status_filter == 'audiobook_only':
         order = build_order_by(BOOK_SORT_COLS, 'current_author, current_title')
@@ -9635,6 +9777,8 @@ def build_order_by(sort_cols, default_order):
         total = counts['attention']
     elif status_filter == 'locked':
         total = counts['locked']
+    elif status_filter == 'validation_failed':
+        total = counts['validation_failed']
     elif status_filter == 'search':
         total = counts.get('search', 0)
     # Issue #53: Media type filters
diff --git a/library_manager/config.py b/library_manager/config.py
index a3b89cc..79338ab 100644
--- a/library_manager/config.py
+++ b/library_manager/config.py
@@ -136,7 +136,11 @@ def _detect_data_dir():
     "watch_delete_empty_folders": True,    # Remove empty source folders after moving
     "watch_min_file_age_seconds": 30,      # Minimum file age before processing (wait for downloads to complete)
     # Post-processing hooks - run commands/webhooks after a book is renamed (Issue #166)
-    "post_processing_hooks": []
+    "post_processing_hooks": [],
+    # Issue #110: File validation - check audio files before processing
+    "enable_file_validation": True,            # Validate audio files with ffprobe before queueing
+    "min_audio_duration_seconds": 600,         # Minimum duration (seconds) to consider a valid audiobook (default: 10 min)
+    "min_audio_file_size_mb": 1,               # Minimum file size (MB) to consider a valid audiobook
 }
 
 DEFAULT_SECRETS = {
diff --git a/library_manager/database.py b/library_manager/database.py
index f09d68d..d29b161 100644
--- a/library_manager/database.py
+++ b/library_manager/database.py
@@ -153,6 +153,17 @@ def init_db(db_path=None):
     except:
         pass
 
+    # Issue #110: File validation columns - track whether audio files are valid
+    validation_columns = [
+        ('validation_status', "TEXT"),           # NULL=not validated, 'valid', 'invalid', 'skipped'
+        ('validation_reason', "TEXT"),           # Why it failed (e.g., 'too_short', 'corrupt', 'no_audio_stream')
+    ]
+    for col_name, col_type in validation_columns:
+        try:
+            c.execute(f'ALTER TABLE books ADD COLUMN {col_name} {col_type}')
+        except:
+            pass  # Column already exists
+
     # Stats table - daily stats
     c.execute('''CREATE TABLE IF NOT EXISTS stats (
         id INTEGER PRIMARY KEY,
@@ -379,7 +390,7 @@ def should_requeue_book(book_row, max_retries=3):
     max_layer = max_layer or 0
 
     # Never requeue these statuses
-    skip_statuses = {'user_locked', 'needs_attention', 'needs_split', 'series_folder', 'multi_book_files'}
+    skip_statuses = {'user_locked', 'needs_attention', 'needs_split', 'series_folder', 'multi_book_files', 'validation_failed'}
     if status in skip_statuses:
         return (False, None)
 
diff --git a/library_manager/file_validation.py b/library_manager/file_validation.py
index f55c91a..3157721 100644
--- a/library_manager/file_validation.py
+++ b/library_manager/file_validation.py
@@ -32,16 +32,27 @@ def check_ffmpeg_available() -> Tuple[bool, str]:
     return True, "ok"
 
 
-def validate_audio_file(path: str) -> Tuple[bool, str, Dict[str, Any]]:
+def validate_audio_file(path: str, min_duration: Optional[float] = None,
+                        min_size: Optional[int] = None) -> Tuple[bool, str, Dict[str, Any]]:
     """
     Validate an audio file using ffprobe.
 
+    Args:
+        path: Path to the audio file
+        min_duration: Minimum duration in seconds (default: MIN_DURATION_SECONDS)
+        min_size: Minimum file size in bytes (default: MIN_FILE_SIZE_BYTES)
+
     Returns:
         (is_valid, reason, metadata)
         - is_valid: True if file is a valid audiobook
         - reason: "valid" or error description
         - metadata: Dict with duration, size, format info (empty if invalid)
     """
+    if min_duration is None:
+        min_duration = MIN_DURATION_SECONDS
+    if min_size is None:
+        min_size = MIN_FILE_SIZE_BYTES
+
     file_path = Path(path)
 
     # Basic checks with TOCTOU protection
@@ -57,7 +68,7 @@ def validate_audio_file(path: str) -> Tuple[bool, str, Dict[str, Any]]:
         logger.warning(f"File disappeared during validation {path}: {e}")
         return False, "file_disappeared", {}
 
-    if file_size < MIN_FILE_SIZE_BYTES:
+    if file_size < min_size:
         return False, "too_small", {"size": file_size}
 
     # Run ffprobe
@@ -137,7 +148,7 @@ def validate_audio_file(path: str) -> Tuple[bool, str, Dict[str, Any]]:
     if duration == 0:
         return False, "no_duration_truncated", metadata
 
-    if duration < MIN_DURATION_SECONDS:
+    if duration < min_duration:
         return False, "too_short", metadata
 
     # Try to seek to end (catches truncated files)
diff --git a/templates/dashboard.html b/templates/dashboard.html
index 3a72805..709d133 100644
--- a/templates/dashboard.html
+++ b/templates/dashboard.html
@@ -51,6 +51,21 @@
     </div>
 </div>
 
+{% if validation_failed_count is defined and validation_failed_count > 0 %}
+<div class="row mb-3">
+    <div class="col-12">
+        <div class="alert alert-warning py-2 mb-0 d-flex align-items-center" role="alert">
+            <i class="bi bi-exclamation-triangle me-2"></i>
+            <small>
+                <strong>{{ validation_failed_count }}</strong> {{ _('file(s) failed validation') }}
+                {{ _('(corrupt, truncated, or too short). These are excluded from processing.') }}
+                <a href="/library?status=validation_failed" class="alert-link">{{ _('View') }}</a>
+            </small>
+        </div>
+    </div>
+</div>
+{% endif %}
+
 <!-- Toast container for action feedback -->
 <div class="toast-container position-fixed top-0 end-0 p-3" style="z-index: 1080;">
     <div id="action-toast" class="toast align-items-center border-0" role="alert" aria-live="assertive" aria-atomic="true">
diff --git a/templates/settings.html b/templates/settings.html
index 5627f0f..c2dd7fe 100644
--- a/templates/settings.html
+++ b/templates/settings.html
@@ -541,6 +541,33 @@ <h5 class="mt-2">Demo Mode</h5>
 
                             <hr class="my-2">
 
+                            <!-- Issue #110: File Validation -->
+                            <div class="form-check form-switch mb-2">
+                                <input class="form-check-input" type="checkbox" name="enable_file_validation"
+                                       id="enable_file_validation" {% if config.enable_file_validation is not defined or config.enable_file_validation %}checked{% endif %}>
+                                <label class="form-check-label" for="enable_file_validation">
+                                    <i class="bi bi-shield-check text-success"></i> <strong>{{ _('File Validation') }}</strong>
+                                    <span class="badge bg-success">{{ _('Local') }}</span>
+                                    <br><small class="text-muted">{{ _('Check audio files with ffprobe before processing (catches corrupt, truncated, or non-audiobook files)') }}</small>
+                                </label>
+                            </div>
+                            <div class="row mb-3 ms-4" id="validation-options">
+                                <div class="col-md-6">
+                                    <label for="min_audio_duration_seconds" class="form-label small">{{ _('Min Duration (seconds)') }}</label>
+                                    <input type="number" class="form-control form-control-sm" name="min_audio_duration_seconds"
+                                           id="min_audio_duration_seconds" value="{{ config.min_audio_duration_seconds|default(600) }}" min="0" max="7200">
+                                    <small class="text-muted">{{ _('Default: 600 (10 minutes)') }}</small>
+                                </div>
+                                <div class="col-md-6">
+                                    <label for="min_audio_file_size_mb" class="form-label small">{{ _('Min File Size (MB)') }}</label>
+                                    <input type="number" class="form-control form-control-sm" name="min_audio_file_size_mb"
+                                           id="min_audio_file_size_mb" value="{{ config.min_audio_file_size_mb|default(1) }}" min="0" max="100">
+                                    <small class="text-muted">{{ _('Default: 1 MB') }}</small>
+                                </div>
+                            </div>
+
+                            <hr class="my-2">
+
                             <div class="form-check form-switch mb-3">
                                 <input class="form-check-input" type="checkbox" name="enable_api_lookups"
                                        id="enable_api_lookups" {% if config.enable_api_lookups != false %}checked{% endif %}>

From 8072c18eac49e0ffe48360a62343ddfd42fef1b5 Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Tue, 10 Mar 2026 16:40:59 -0500
Subject: [PATCH 03/20] Addresses #66: Add LayerRegistry and LayerInfo for
 modular pipeline (#180)

Introduces the foundational registry that describes all processing layers,
their ordering, enable/disable config keys, and circuit breaker dependencies.

- LayerInfo: frozen dataclass with layer metadata (id, name, description,
  config key, default order, circuit breaker info)
- LayerRegistry: lookup by id, ordered listing, enable/disable checks,
  custom pipeline_order support, order validation
- default_registry: pre-populated with all 5 current layers matching the
  execution order in worker.process_all_queue

Purely additive -- nothing uses the registry yet. No behavior changes.

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 library_manager/pipeline/__init__.py   |   6 +
 library_manager/pipeline/layer_info.py |  44 +++++
 library_manager/pipeline/registry.py   | 222 +++++++++++++++++++++++++
 3 files changed, 272 insertions(+)
 create mode 100644 library_manager/pipeline/layer_info.py
 create mode 100644 library_manager/pipeline/registry.py

diff --git a/library_manager/pipeline/__init__.py b/library_manager/pipeline/__init__.py
index dd4cc6f..4d42a87 100644
--- a/library_manager/pipeline/__init__.py
+++ b/library_manager/pipeline/__init__.py
@@ -5,6 +5,8 @@
 """
 
 from library_manager.pipeline.base_layer import ProcessingLayer, LayerResult, LayerAction
+from library_manager.pipeline.layer_info import LayerInfo
+from library_manager.pipeline.registry import LayerRegistry, default_registry, build_default_registry
 from library_manager.pipeline.layer_content import process_layer_4_content
 from library_manager.pipeline.layer_audio_credits import process_layer_3_audio
 from library_manager.pipeline.layer_api import process_layer_1_api, process_sl_requeue_verification
@@ -15,6 +17,10 @@
     'ProcessingLayer',
     'LayerResult',
     'LayerAction',
+    'LayerInfo',
+    'LayerRegistry',
+    'default_registry',
+    'build_default_registry',
     'process_layer_4_content',
     'process_layer_3_audio',
     'process_layer_1_api',
diff --git a/library_manager/pipeline/layer_info.py b/library_manager/pipeline/layer_info.py
new file mode 100644
index 0000000..668af91
--- /dev/null
+++ b/library_manager/pipeline/layer_info.py
@@ -0,0 +1,44 @@
+"""LayerInfo dataclass for describing processing layers.
+
+Each processing layer in the pipeline has metadata describing its identity,
+configuration, and capabilities. LayerInfo captures this without any
+runtime behavior -- it's purely descriptive.
+"""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class LayerInfo:
+    """Metadata describing a single processing layer.
+
+    This is a pure data object -- it knows WHAT a layer is, not HOW it runs.
+    The registry uses these to track ordering, enable/disable state, and
+    circuit breaker dependencies.
+
+    Attributes:
+        layer_id: Unique identifier (e.g. "audio_id", "api_lookup").
+        layer_name: Human-readable display name.
+        description: What this layer does, shown in UI/logs.
+        config_enable_key: Config key that enables/disables this layer.
+        default_order: Default position in the pipeline (1-based).
+        supports_circuit_breaker: Whether this layer uses circuit breakers.
+        circuit_breaker_apis: Which API circuit breakers this layer depends on.
+    """
+
+    layer_id: str
+    layer_name: str
+    description: str
+    config_enable_key: str
+    default_order: int
+    supports_circuit_breaker: bool = False
+    circuit_breaker_apis: tuple = field(default_factory=tuple)
+
+    def __post_init__(self):
+        if not self.layer_id:
+            raise ValueError("layer_id cannot be empty")
+        if self.default_order < 1:
+            raise ValueError("default_order must be >= 1")
+
+
+__all__ = ['LayerInfo']
diff --git a/library_manager/pipeline/registry.py b/library_manager/pipeline/registry.py
new file mode 100644
index 0000000..48acb88
--- /dev/null
+++ b/library_manager/pipeline/registry.py
@@ -0,0 +1,222 @@
+"""LayerRegistry -- knows about all processing layers and their ordering.
+
+The registry is the single source of truth for which layers exist, what
+order they run in, and which config keys control them. Nothing in this
+module executes layers -- it only describes and queries them.
+"""
+
+import logging
+from typing import Dict, List, Optional
+
+from library_manager.pipeline.layer_info import LayerInfo
+
+logger = logging.getLogger(__name__)
+
+
+class LayerRegistry:
+    """Registry of all processing layers in the pipeline.
+
+    Provides lookup by layer_id, ordered listing, and enable/disable
+    checks against a config dict.
+    """
+
+    def __init__(self):
+        self._layers: Dict[str, LayerInfo] = {}
+
+    def register(self, info: LayerInfo) -> None:
+        """Register a layer.
+
+        Args:
+            info: LayerInfo describing the layer.
+
+        Raises:
+            ValueError: If a layer with the same layer_id is already registered.
+        """
+        if info.layer_id in self._layers:
+            raise ValueError(f"Layer '{info.layer_id}' is already registered")
+        self._layers[info.layer_id] = info
+        logger.debug(f"Registered layer: {info.layer_id} (order={info.default_order})")
+
+    def get_layer(self, layer_id: str) -> Optional[LayerInfo]:
+        """Return LayerInfo for a given layer_id, or None if not found."""
+        return self._layers.get(layer_id)
+
+    def get_ordered_layers(self, config: Optional[dict] = None) -> List[LayerInfo]:
+        """Return all layers in pipeline order.
+
+        If *config* contains a ``pipeline_order`` list of layer_ids, that
+        ordering is used (unknown ids are skipped with a warning). Otherwise
+        layers are sorted by their ``default_order``.
+
+        Args:
+            config: Optional config dict. If None or missing pipeline_order,
+                    default ordering is used.
+
+        Returns:
+            List of LayerInfo in execution order.
+        """
+        if config and 'pipeline_order' in config:
+            ordered = []
+            for layer_id in config['pipeline_order']:
+                info = self._layers.get(layer_id)
+                if info:
+                    ordered.append(info)
+                else:
+                    logger.warning(f"pipeline_order references unknown layer: {layer_id}")
+            return ordered
+
+        return sorted(self._layers.values(), key=lambda li: li.default_order)
+
+    def get_enabled_layers(self, config: dict) -> List[LayerInfo]:
+        """Return only enabled layers, in pipeline order.
+
+        A layer is enabled when its ``config_enable_key`` is truthy in
+        *config* (or defaults to True if the key is absent).
+
+        Args:
+            config: Config dict to check enable keys against.
+
+        Returns:
+            List of enabled LayerInfo in execution order.
+        """
+        return [
+            info for info in self.get_ordered_layers(config)
+            if self.is_enabled(info.layer_id, config)
+        ]
+
+    def is_enabled(self, layer_id: str, config: dict) -> bool:
+        """Check whether a layer is enabled in *config*.
+
+        Looks up the layer's ``config_enable_key`` in *config*. If the key
+        is missing from config, the layer is considered enabled (safe
+        default -- existing behavior before registry existed).
+
+        Args:
+            layer_id: The layer to check.
+            config: Config dict.
+
+        Returns:
+            True if enabled, False otherwise.
+
+        Raises:
+            KeyError: If layer_id is not registered.
+        """
+        info = self._layers.get(layer_id)
+        if info is None:
+            raise KeyError(f"Unknown layer_id: {layer_id}")
+        return bool(config.get(info.config_enable_key, True))
+
+    def get_all_layer_ids(self) -> List[str]:
+        """Return all registered layer IDs in default order."""
+        return [info.layer_id for info in sorted(
+            self._layers.values(), key=lambda li: li.default_order
+        )]
+
+    def validate_order(self, order: List[str]) -> tuple:
+        """Validate a proposed pipeline_order list.
+
+        Checks that every id in *order* is registered and that there are no
+        duplicates. Layers missing from *order* are noted as warnings (they
+        won't run).
+
+        Args:
+            order: List of layer_ids representing the desired execution order.
+
+        Returns:
+            Tuple of (is_valid, errors) where errors is a list of strings.
+        """
+        errors: List[str] = []
+        seen = set()
+
+        for layer_id in order:
+            if layer_id in seen:
+                errors.append(f"Duplicate layer_id in order: {layer_id}")
+            seen.add(layer_id)
+
+            if layer_id not in self._layers:
+                errors.append(f"Unknown layer_id: {layer_id}")
+
+        # Warn about registered layers not present in the order
+        missing = set(self._layers.keys()) - seen
+        for m in sorted(missing):
+            errors.append(f"Registered layer '{m}' is missing from order (it will not run)")
+
+        return (len(errors) == 0, errors)
+
+    def __len__(self) -> int:
+        return len(self._layers)
+
+    def __contains__(self, layer_id: str) -> bool:
+        return layer_id in self._layers
+
+
+def build_default_registry() -> LayerRegistry:
+    """Build and return a registry pre-populated with all current layers.
+
+    The ordering matches the execution sequence in worker.process_all_queue:
+      1. audio_id      -- Audio transcription + BookDB identification
+      2. audio_credits  -- AI audio clip analysis (Gemini)
+      3. sl_requeue     -- Skaldleita re-verification after nightly merge
+      4. api_lookup     -- API database lookups (Audnexus, OpenLibrary, etc.)
+      5. ai_verify      -- AI verification of folder-based guesses
+
+    Config enable keys are taken from config.py DEFAULT_CONFIG.
+    """
+    registry = LayerRegistry()
+
+    registry.register(LayerInfo(
+        layer_id="audio_id",
+        layer_name="Audio ID",
+        description="Transcribe audiobook intro via Skaldleita/Whisper and identify from narrator announcement.",
+        config_enable_key="enable_audio_identification",
+        default_order=1,
+        supports_circuit_breaker=True,
+        circuit_breaker_apis=("bookdb",),
+    ))
+
+    registry.register(LayerInfo(
+        layer_id="audio_credits",
+        layer_name="AI Audio Analysis",
+        description="Send longer audio clip to Gemini AI for deeper analysis when transcription was unclear.",
+        config_enable_key="enable_audio_analysis",
+        default_order=2,
+        supports_circuit_breaker=True,
+        circuit_breaker_apis=("gemini",),
+    ))
+
+    registry.register(LayerInfo(
+        layer_id="sl_requeue",
+        layer_name="SL Requeue Check",
+        description="Re-verify books against Skaldleita after nightly database merge.",
+        config_enable_key="enable_api_lookups",
+        default_order=3,
+        supports_circuit_breaker=True,
+        circuit_breaker_apis=("bookdb",),
+    ))
+
+    registry.register(LayerInfo(
+        layer_id="api_lookup",
+        layer_name="API Lookup",
+        description="Look up book metadata from Skaldleita, Audnexus, OpenLibrary, and Google Books.",
+        config_enable_key="enable_api_lookups",
+        default_order=4,
+        supports_circuit_breaker=False,
+    ))
+
+    registry.register(LayerInfo(
+        layer_id="ai_verify",
+        layer_name="AI Verify",
+        description="Use AI to verify folder-name-based identification as a last resort.",
+        config_enable_key="enable_ai_verification",
+        default_order=5,
+        supports_circuit_breaker=False,
+    ))
+
+    return registry
+
+
+# Module-level default instance -- importable from anywhere
+default_registry = build_default_registry()
+
+
+__all__ = ['LayerRegistry', 'LayerInfo', 'build_default_registry', 'default_registry']

From 04d625ec28bfc6344059ca1c5401440040be478f Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Tue, 10 Mar 2026 16:42:41 -0500
Subject: [PATCH 04/20] Addresses #66: Add pipeline_order to default config
 (#181)

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 library_manager/config.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/library_manager/config.py b/library_manager/config.py
index 79338ab..fc8d8c7 100644
--- a/library_manager/config.py
+++ b/library_manager/config.py
@@ -116,6 +116,8 @@ def _detect_data_dir():
     # Text providers: "gemini", "openrouter", "ollama"
     "audio_provider_chain": ["bookdb", "gemini"],  # Order to try audio identification (bookdb = Skaldleita)
     "text_provider_chain": ["gemini", "openrouter"],  # Order to try text-based AI
+    # Pipeline layer ordering - controls the sequence layers execute in
+    "pipeline_order": ["audio_id", "audio_credits", "sl_requeue", "api_lookup", "ai_verify"],
     "deep_scan_mode": False,              # Always use all enabled layers regardless of confidence
     "profile_confidence_threshold": 85,   # Minimum confidence to skip remaining layers (0-100)
     "multibook_ai_fallback": True,         # Use AI for ambiguous chapter/multibook detection

From a09343b785221161565f2c7175b10bdffcbf1603 Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Tue, 10 Mar 2026 16:55:25 -0500
Subject: [PATCH 05/20] Addresses #66: Add PipelineOrchestrator with layer
 adapters and feature flag (#182)

Introduces a configurable PipelineOrchestrator that can replace the
hardcoded process_all_queue sequence. Uses adapter pattern to wrap
existing battle-tested layer functions with a uniform interface.

- Add adapters.py: AudioIdAdapter, ApiLookupAdapter, AudioCreditsAdapter,
  AiVerifyAdapter, SlRequeueAdapter wrapping existing layer functions
- Add orchestrator.py: PipelineOrchestrator handling layer ordering,
  circuit breaker waits, batch loops, rate limiting, stuck item recovery
- Add use_modular_pipeline feature flag (default: False) for safe rollout
- Update pipeline __init__.py with new exports

When use_modular_pipeline is False (default), existing behavior is
completely unchanged. When True, the orchestrator runs layers in the
order defined by pipeline_order config using the registry and adapters.

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 library_manager/config.py                |   1 +
 library_manager/pipeline/__init__.py     |  13 +
 library_manager/pipeline/adapters.py     | 202 ++++++++
 library_manager/pipeline/orchestrator.py | 627 +++++++++++++++++++++++
 library_manager/worker.py                |  32 ++
 5 files changed, 875 insertions(+)
 create mode 100644 library_manager/pipeline/adapters.py
 create mode 100644 library_manager/pipeline/orchestrator.py

diff --git a/library_manager/config.py b/library_manager/config.py
index fc8d8c7..9bfc193 100644
--- a/library_manager/config.py
+++ b/library_manager/config.py
@@ -118,6 +118,7 @@ def _detect_data_dir():
     "text_provider_chain": ["gemini", "openrouter"],  # Order to try text-based AI
     # Pipeline layer ordering - controls the sequence layers execute in
     "pipeline_order": ["audio_id", "audio_credits", "sl_requeue", "api_lookup", "ai_verify"],
+    "use_modular_pipeline": False,        # Feature flag: use PipelineOrchestrator instead of hardcoded process_all_queue
     "deep_scan_mode": False,              # Always use all enabled layers regardless of confidence
     "profile_confidence_threshold": 85,   # Minimum confidence to skip remaining layers (0-100)
     "multibook_ai_fallback": True,         # Use AI for ambiguous chapter/multibook detection
diff --git a/library_manager/pipeline/__init__.py b/library_manager/pipeline/__init__.py
index 4d42a87..9252701 100644
--- a/library_manager/pipeline/__init__.py
+++ b/library_manager/pipeline/__init__.py
@@ -7,6 +7,11 @@
 from library_manager.pipeline.base_layer import ProcessingLayer, LayerResult, LayerAction
 from library_manager.pipeline.layer_info import LayerInfo
 from library_manager.pipeline.registry import LayerRegistry, default_registry, build_default_registry
+from library_manager.pipeline.orchestrator import PipelineOrchestrator
+from library_manager.pipeline.adapters import (
+    LayerAdapter, AudioIdAdapter, ApiLookupAdapter, AudioCreditsAdapter,
+    AiVerifyAdapter, SlRequeueAdapter, build_default_adapters,
+)
 from library_manager.pipeline.layer_content import process_layer_4_content
 from library_manager.pipeline.layer_audio_credits import process_layer_3_audio
 from library_manager.pipeline.layer_api import process_layer_1_api, process_sl_requeue_verification
@@ -21,6 +26,14 @@
     'LayerRegistry',
     'default_registry',
     'build_default_registry',
+    'PipelineOrchestrator',
+    'LayerAdapter',
+    'AudioIdAdapter',
+    'ApiLookupAdapter',
+    'AudioCreditsAdapter',
+    'AiVerifyAdapter',
+    'SlRequeueAdapter',
+    'build_default_adapters',
     'process_layer_4_content',
     'process_layer_3_audio',
     'process_layer_1_api',
diff --git a/library_manager/pipeline/adapters.py b/library_manager/pipeline/adapters.py
new file mode 100644
index 0000000..de2687c
--- /dev/null
+++ b/library_manager/pipeline/adapters.py
@@ -0,0 +1,202 @@
+"""Layer adapters -- uniform interface wrappers around existing layer functions.
+
+Each adapter wraps one battle-tested layer function with a consistent interface
+so the PipelineOrchestrator can run them generically. The adapters do NOT
+reimplement any processing logic -- they translate between the orchestrator's
+uniform call convention and each layer's specific function signature.
+
+Adapter Pattern:
+    Orchestrator -> adapter.run(config, deps) -> existing layer function -> (processed, resolved)
+"""
+
+import logging
+from typing import Callable, Dict, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+class LayerAdapter:
+    """Base adapter interface for pipeline layers.
+
+    Every layer adapter must define a ``layer_id`` matching the registry
+    and implement ``run()`` which delegates to the real layer function.
+
+    Attributes:
+        layer_id: Must match a registered LayerInfo.layer_id in the registry.
+    """
+
+    layer_id: str = ""
+
+    def run(self, config: Dict, deps: Dict) -> Tuple[int, int]:
+        """Run one batch cycle of this layer.
+
+        Args:
+            config: Current application configuration dict.
+            deps: Dictionary of injected dependencies (get_db, load_config,
+                  is_circuit_open, etc.). Each adapter picks what it needs.
+
+        Returns:
+            Tuple of (processed_count, resolved_count).
+        """
+        raise NotImplementedError(f"{self.__class__.__name__}.run() not implemented")
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} layer_id={self.layer_id!r}>"
+
+
+class AudioIdAdapter(LayerAdapter):
+    """Wraps process_layer_1_audio -- audio transcription + AI parsing.
+
+    This is the primary identification method. It transcribes audiobook
+    intros via Skaldleita/Whisper and identifies from narrator announcements.
+
+    Dependencies required in deps dict:
+        - process_layer_1_audio: The app.py wrapper that already has
+          all app-level deps injected (get_db, identify_audio_with_bookdb, etc.)
+    """
+
+    layer_id = "audio_id"
+
+    def run(self, config: Dict, deps: Dict) -> Tuple[int, int]:
+        """Run one batch of audio identification.
+
+        Delegates to the app-level process_layer_1_audio wrapper which
+        already injects get_db, identify_audio_with_bookdb, transcribe_audio_intro,
+        parse_transcript_with_ai, is_circuit_open, get_circuit_breaker,
+        load_config, build_new_path, update_processing_status, and set_current_book.
+        """
+        process_fn = deps.get('process_layer_1_audio')
+        if not process_fn:
+            logger.warning(f"[{self.layer_id}] No process function provided, skipping")
+            return 0, 0
+        return process_fn(config)
+
+
+class ApiLookupAdapter(LayerAdapter):
+    """Wraps process_layer_1_api -- API database lookups.
+
+    Queries Skaldleita, Audnexus, OpenLibrary, and Google Books to enrich
+    book metadata. Faster and cheaper than AI verification.
+
+    Dependencies required in deps dict:
+        - process_layer_1_api: The app.py wrapper with get_db,
+          gather_all_api_candidates, and set_current_book injected.
+    """
+
+    layer_id = "api_lookup"
+
+    def run(self, config: Dict, deps: Dict) -> Tuple[int, int]:
+        """Run one batch of API lookups."""
+        process_fn = deps.get('process_layer_1_api')
+        if not process_fn:
+            logger.warning(f"[{self.layer_id}] No process function provided, skipping")
+            return 0, 0
+        return process_fn(config)
+
+
+class AudioCreditsAdapter(LayerAdapter):
+    """Wraps process_layer_3_audio -- AI audio clip analysis.
+
+    Sends longer audio samples to Gemini AI for deeper analysis when
+    transcription was unclear. This is an expensive layer.
+
+    Dependencies required in deps dict:
+        - process_layer_3_audio: The app.py wrapper with get_db,
+          find_audio_files, analyze_audio_for_credits, auto_save_narrator,
+          contribute_audio_extraction, and standardize_initials injected.
+    """
+
+    layer_id = "audio_credits"
+
+    def run(self, config: Dict, deps: Dict) -> Tuple[int, int]:
+        """Run one batch of audio credits analysis.
+
+        Passes verification_layer=2 to process Layer 2 items (unclear L1 results).
+        The underlying function checks the enable_audio_analysis config key.
+        """
+        process_fn = deps.get('process_layer_3_audio')
+        if not process_fn:
+            logger.warning(f"[{self.layer_id}] No process function provided, skipping")
+            return 0, 0
+        # audio_credits processes items at verification_layer=2
+        return process_fn(config, verification_layer=2)
+
+
+class AiVerifyAdapter(LayerAdapter):
+    """Wraps process_queue -- AI verification of folder-based guesses.
+
+    Uses AI to verify identification as a last resort. Folder names CAN be
+    wrong, so confidence is set LOW for folder-derived identifications.
+
+    Dependencies required in deps dict:
+        - process_queue: The app.py wrapper with get_db, check_rate_limit,
+          call_ai, detect_multibook_vs_chapters, auto_save_narrator,
+          standardize_initials, extract_series_from_title, is_placeholder_author,
+          build_new_path, is_drastic_author_change, verify_drastic_change,
+          analyze_audio_for_credits, compare_book_folders, sanitize_path_component,
+          extract_narrator_from_folder, build_metadata_for_embedding,
+          embed_tags_for_path, BookProfile, audio_extensions, and set_current_book
+          injected.
+    """
+
+    layer_id = "ai_verify"
+
+    def run(self, config: Dict, deps: Dict) -> Tuple[int, int]:
+        """Run one batch of AI verification.
+
+        Passes verification_layer=4 because at this point in the pipeline,
+        we're trusting folder names as a last resort.
+        """
+        process_fn = deps.get('process_queue')
+        if not process_fn:
+            logger.warning(f"[{self.layer_id}] No process function provided, skipping")
+            return 0, 0
+        return process_fn(config, verification_layer=4)
+
+
+class SlRequeueAdapter(LayerAdapter):
+    """Wraps process_sl_requeue_verification -- re-verify after nightly merge.
+
+    Books with sl_requeue set had partial ID from Skaldleita. After the
+    nightly database merge, we re-check to see if they're now fully identified.
+
+    Dependencies required in deps dict:
+        - process_sl_requeue_verification: The app.py wrapper with get_db
+          and search_bookdb injected.
+    """
+
+    layer_id = "sl_requeue"
+
+    def run(self, config: Dict, deps: Dict) -> Tuple[int, int]:
+        """Run SL requeue verification (single pass, not a batch loop)."""
+        process_fn = deps.get('process_sl_requeue_verification')
+        if not process_fn:
+            logger.debug(f"[{self.layer_id}] No process function provided, skipping")
+            return 0, 0
+        return process_fn(config)
+
+
+def build_default_adapters():
+    """Build the default set of layer adapters.
+
+    Returns:
+        List of LayerAdapter instances for all known layers.
+    """
+    return [
+        AudioIdAdapter(),
+        AudioCreditsAdapter(),
+        SlRequeueAdapter(),
+        ApiLookupAdapter(),
+        AiVerifyAdapter(),
+    ]
+
+
+__all__ = [
+    'LayerAdapter',
+    'AudioIdAdapter',
+    'ApiLookupAdapter',
+    'AudioCreditsAdapter',
+    'AiVerifyAdapter',
+    'SlRequeueAdapter',
+    'build_default_adapters',
+]
diff --git a/library_manager/pipeline/orchestrator.py b/library_manager/pipeline/orchestrator.py
new file mode 100644
index 0000000..f9ad50b
--- /dev/null
+++ b/library_manager/pipeline/orchestrator.py
@@ -0,0 +1,627 @@
+"""PipelineOrchestrator -- configurable replacement for hardcoded process_all_queue.
+
+This module provides a PipelineOrchestrator that executes processing layers
+in the order defined by the LayerRegistry and config, using LayerAdapter
+objects to delegate to the existing (battle-tested) layer functions.
+
+The orchestrator handles:
+    - Layer ordering (from registry + config pipeline_order)
+    - Enable/disable checks (from config enable keys)
+    - Circuit breaker waits (per-layer, checking _worker_running)
+    - Batch loops with configurable delays
+    - Rate limit handling (for AI verify layer)
+    - Disabled-layer fallback (advancing stuck items)
+    - Stuck item recovery
+    - Worker stop checks
+    - Status updates and logging
+
+Feature flag: controlled by config key ``use_modular_pipeline`` (default False).
+When False, the existing process_all_queue runs unchanged. When True, the
+orchestrator takes over.
+"""
+
+import logging
+import time
+from typing import Callable, Dict, List, Optional, Tuple
+
+from library_manager.pipeline.adapters import LayerAdapter
+from library_manager.pipeline.registry import LayerRegistry
+
+logger = logging.getLogger(__name__)
+
+# Import worker state -- needed for stop checks and status updates
+from library_manager.worker import (
+    _processing_status,
+    update_processing_status,
+    LAYER_NAMES,
+)
+
+
+# Layer display numbers for status bar (maps layer_id to legacy layer number)
+_LAYER_DISPLAY_NUMBERS = {
+    'audio_id': 1,
+    'audio_credits': 2,
+    'sl_requeue': 2,  # Runs between L2 and L3, show as L2
+    'api_lookup': 3,
+    'ai_verify': 4,
+}
+
+# Delay between batches per layer (seconds)
+_BATCH_DELAYS = {
+    'audio_id': 2,       # Audio processing needs more time
+    'audio_credits': 2,  # Audio processing needs more time
+    'sl_requeue': 0,     # Single pass, no batch loop
+    'api_lookup': 0.5,   # APIs are fast
+    'ai_verify': None,   # Uses rate-limit-based delay (calculated at runtime)
+}
+
+# Status messages shown when each layer starts
+_LAYER_STATUS_MESSAGES = {
+    'audio_id': "Transcribing audio intro via Skaldleita...",
+    'audio_credits': "Sending audio clip to Gemini AI...",
+    'sl_requeue': "Checking SL requeue verifications...",
+    'api_lookup': "Looking up metadata from Skaldleita/Audnexus...",
+    'ai_verify': "Verifying identification with AI...",
+}
+
+_LAYER_ACTIVITY_MESSAGES = {
+    'audio_id': "Started audio identification",
+    'audio_credits': "Started AI audio analysis",
+    'sl_requeue': "Re-verifying books after nightly merge",
+    'api_lookup': "Started API metadata lookup",
+    'ai_verify': "Started AI verification of folder names",
+}
+
+# Log banner messages
+_LAYER_LOG_BANNERS = {
+    'audio_id': "LAYER 1: Audio Transcription + AI Parsing",
+    'audio_credits': "LAYER 2: AI Audio Clip Analysis (for unclear L1 results)",
+    'sl_requeue': "SL REQUEUE CHECK: Re-verifying pending books after nightly merge",
+    'api_lookup': "LAYER 3: API Enrichment (adding metadata to identified books)",
+    'ai_verify': "LAYER 4: Folder Name Fallback (last resort, low confidence)",
+}
+
+
+class PipelineOrchestrator:
+    """Executes processing layers in configured order using adapter pattern.
+
+    The orchestrator replaces the hardcoded layer sequence in
+    worker.process_all_queue with a configurable, registry-driven pipeline.
+    Each layer runs through its adapter, which delegates to the existing
+    layer function with all its battle-tested logic intact.
+
+    Args:
+        registry: LayerRegistry defining available layers and ordering.
+        adapters: List of LayerAdapter instances (one per layer).
+        config: Application configuration dict.
+        deps: Dictionary of injected dependencies passed to each adapter.
+            Must include: get_db, load_config, is_circuit_open,
+            get_circuit_breaker, check_rate_limit, and the layer wrapper
+            functions (process_layer_1_audio, process_layer_1_api, etc.).
+    """
+
+    def __init__(
+        self,
+        registry: LayerRegistry,
+        adapters: List[LayerAdapter],
+        config: Dict,
+        deps: Dict,
+    ):
+        self.registry = registry
+        self.adapters = {a.layer_id: a for a in adapters}
+        self.config = config
+        self.deps = deps
+
+    def run_pipeline(self) -> Tuple[int, int]:
+        """Execute all enabled layers in configured order.
+
+        This is the main entry point, replacing the hardcoded sequence in
+        process_all_queue. It handles:
+            - Queue empty check
+            - Stuck item cleanup
+            - Disabled layer fallback (advancing items past disabled layers)
+            - Per-layer batch loops with circuit breaker waits
+            - Status bar updates
+            - Final status reset
+
+        Returns:
+            Tuple of (total_processed, total_fixed).
+        """
+        global _processing_status
+        import library_manager.worker as _worker_mod
+
+        get_db = self.deps['get_db']
+
+        # Check if queue has items
+        conn = get_db()
+        c = conn.cursor()
+        c.execute('SELECT COUNT(*) as count FROM queue')
+        total = c.fetchone()['count']
+        conn.close()
+
+        if total == 0:
+            logger.info("Queue is empty, nothing to process")
+            return 0, 0
+
+        # Calculate delay for rate-limited layers
+        user_max = self.config.get('max_requests_per_hour', 30)
+        max_per_hour = max(10, min(user_max, 500))
+        min_delay = max(2, 3600 // max_per_hour)
+        logger.info(f"Rate limit: {max_per_hour}/hour, delay between batches: {min_delay}s")
+
+        # Initialize processing status
+        _processing_status.update({
+            "active": True,
+            "processed": 0,
+            "total": total,
+            "current": "Starting processing...",
+            "current_book": "",
+            "current_author": "",
+            "errors": [],
+            "layer": 1,
+            "layer_name": LAYER_NAMES[1],
+            "queue_remaining": total,
+            "last_activity": f"Starting processing of {total} items",
+            "last_activity_time": time.time(),
+        })
+        logger.info(f"=== STARTING AUDIO-FIRST PROCESSING: {total} items in queue ===")
+
+        # Issue #62: Clean up stuck queue items
+        conn = get_db()
+        c = conn.cursor()
+        c.execute('''DELETE FROM queue WHERE book_id IN (
+                        SELECT b.id FROM books b WHERE b.status IN ('needs_attention', 'verified', 'fixed')
+                     )''')
+        cleaned = c.rowcount
+        if cleaned > 0:
+            logger.info(f"Cleaned {cleaned} stuck items from queue (already needs_attention/verified/fixed)")
+            total -= cleaned
+        conn.commit()
+        conn.close()
+
+        # Advance items stuck at Layer 2 if audio analysis is disabled
+        if not self.config.get('enable_audio_analysis', False):
+            self._advance_stuck_layer2_items()
+
+        total_processed = 0
+        total_fixed = 0
+
+        # Get layers in configured order
+        ordered_layers = self.registry.get_ordered_layers(self.config)
+
+        for layer_info in ordered_layers:
+            # Check worker stop
+            if not _worker_mod._worker_running:
+                logger.info("Worker stop requested, breaking pipeline")
+                break
+
+            adapter = self.adapters.get(layer_info.layer_id)
+            if not adapter:
+                logger.debug(f"No adapter for layer '{layer_info.layer_id}', skipping")
+                continue
+
+            # Check if layer is enabled
+            if not self.registry.is_enabled(layer_info.layer_id, self.config):
+                self._handle_disabled_layer(layer_info)
+                continue
+
+            # Run the layer
+            layer_processed, layer_fixed = self._run_layer(
+                layer_info, adapter, min_delay
+            )
+            total_processed += layer_processed
+            total_fixed += layer_fixed
+
+        # Reset status to idle
+        _processing_status.update({
+            "active": False,
+            "layer": 0,
+            "layer_name": "Idle",
+            "current": "Processing complete",
+            "current_book": "",
+            "current_author": "",
+            "queue_remaining": 0,
+            "last_activity": f"Completed: {total_processed} processed, {total_fixed} fixed",
+            "last_activity_time": time.time(),
+        })
+        logger.info(f"=== LAYERED PROCESSING COMPLETE: {total_processed} processed, {total_fixed} fixed ===")
+        return total_processed, total_fixed
+
+    def _run_layer(
+        self,
+        layer_info,
+        adapter: LayerAdapter,
+        min_delay: int,
+    ) -> Tuple[int, int]:
+        """Run a single layer with its batch loop and circuit breaker logic.
+
+        Handles:
+            - Status bar updates before starting
+            - Circuit breaker waits (for layers that support them)
+            - Batch loop with per-layer delay
+            - Special rate-limit handling for ai_verify
+            - Worker stop checks between iterations
+
+        Args:
+            layer_info: LayerInfo describing this layer.
+            adapter: The LayerAdapter to execute.
+            min_delay: Rate-limit-based delay for ai_verify layer.
+
+        Returns:
+            Tuple of (layer_processed, layer_fixed).
+        """
+        import library_manager.worker as _worker_mod
+        global _processing_status
+
+        layer_id = layer_info.layer_id
+        display_num = _LAYER_DISPLAY_NUMBERS.get(layer_id, 0)
+        banner = _LAYER_LOG_BANNERS.get(layer_id, f"Layer: {layer_info.layer_name}")
+        status_msg = _LAYER_STATUS_MESSAGES.get(layer_id, f"Processing {layer_info.layer_name}...")
+        activity_msg = _LAYER_ACTIVITY_MESSAGES.get(layer_id, f"Started {layer_info.layer_name}")
+
+        logger.info(f"=== {banner} ===")
+        _processing_status["layer"] = display_num
+        _processing_status["layer_name"] = layer_info.layer_name
+        _processing_status["current"] = status_msg
+        _processing_status["last_activity"] = activity_msg
+        _processing_status["last_activity_time"] = time.time()
+
+        # Special case: sl_requeue is single-pass, not a batch loop
+        if layer_id == 'sl_requeue':
+            return self._run_single_pass(adapter)
+
+        # Special case: ai_verify has its own complex rate-limit loop
+        if layer_id == 'ai_verify':
+            return self._run_ai_verify_loop(adapter, min_delay)
+
+        # Standard batch loop (audio_id, audio_credits, api_lookup)
+        return self._run_batch_loop(layer_info, adapter)
+
+    def _run_batch_loop(
+        self,
+        layer_info,
+        adapter: LayerAdapter,
+    ) -> Tuple[int, int]:
+        """Standard batch loop: run adapter in a loop until it returns 0.
+
+        Handles circuit breaker waits for layers that support them.
+
+        Args:
+            layer_info: LayerInfo for this layer.
+            adapter: The adapter to call.
+
+        Returns:
+            Tuple of (total_processed, total_resolved).
+        """
+        import library_manager.worker as _worker_mod
+        global _processing_status
+
+        layer_id = layer_info.layer_id
+        batch_delay = _BATCH_DELAYS.get(layer_id, 1)
+        layer_processed = 0
+        layer_resolved = 0
+
+        is_circuit_open = self.deps.get('is_circuit_open')
+        get_circuit_breaker = self.deps.get('get_circuit_breaker')
+
+        while True:
+            if not _worker_mod._worker_running:
+                break
+
+            # Circuit breaker wait for layers that need it
+            if layer_info.supports_circuit_breaker and is_circuit_open and get_circuit_breaker:
+                should_continue = self._wait_for_circuit_breaker(
+                    layer_info, is_circuit_open, get_circuit_breaker
+                )
+                if should_continue == 'break':
+                    break
+                if should_continue == 'continue':
+                    continue
+
+            processed, resolved = adapter.run(self.config, self.deps)
+            if processed == 0:
+                break
+            layer_processed += processed
+            layer_resolved += resolved
+            _processing_status["processed"] = _processing_status.get("processed", 0) + processed
+            if batch_delay:
+                time.sleep(batch_delay)
+
+        logger.info(
+            f"{layer_info.layer_name} complete: {layer_processed} items processed, "
+            f"{layer_resolved} resolved"
+        )
+        return layer_processed, layer_resolved
+
+    def _run_single_pass(self, adapter: LayerAdapter) -> Tuple[int, int]:
+        """Run a layer once (no batch loop). Used for sl_requeue.
+
+        Args:
+            adapter: The adapter to call.
+
+        Returns:
+            Tuple of (processed, resolved).
+        """
+        processed, resolved = adapter.run(self.config, self.deps)
+        if processed > 0:
+            logger.info(
+                f"SL Requeue Check complete: {processed} processed, {resolved} upgraded"
+            )
+        return processed, resolved
+
+    def _run_ai_verify_loop(
+        self,
+        adapter: LayerAdapter,
+        min_delay: int,
+    ) -> Tuple[int, int]:
+        """Run AI verify layer with rate limiting and 3-strike exhaustion.
+
+        This replicates the complex Layer 4 logic from process_all_queue:
+            - Rate limit checks with exponential backoff
+            - processed == -1 means rate-limited (don't count toward exhaustion)
+            - 3 consecutive empty batches -> mark remaining as needs_attention
+            - Circuit breaker awareness for AI providers
+            - Worker stop checks
+
+        Args:
+            adapter: The AiVerifyAdapter.
+            min_delay: Rate-limit-based delay between batches.
+
+        Returns:
+            Tuple of (layer_processed, layer_fixed).
+        """
+        import library_manager.worker as _worker_mod
+        global _processing_status
+
+        get_db = self.deps['get_db']
+        load_config = self.deps['load_config']
+        check_rate_limit = self.deps['check_rate_limit']
+        is_circuit_open = self.deps.get('is_circuit_open')
+
+        batch_num = 0
+        rate_limit_hits = 0
+        empty_batch_count = 0
+        layer_processed = 0
+        layer_fixed = 0
+
+        while True:
+            if not _worker_mod._worker_running:
+                break
+
+            config = load_config()
+
+            allowed, calls_made, max_calls = check_rate_limit(config)
+            if not allowed:
+                rate_limit_hits += 1
+                wait_time = min(300 * rate_limit_hits, 1800)
+                logger.info(f"Rate limit reached ({calls_made}/{max_calls}), waiting {wait_time // 60} minutes...")
+                _processing_status["current"] = f"Rate limited, waiting {wait_time // 60}min..."
+                time.sleep(wait_time)
+                continue
+
+            batch_num += 1
+            logger.info(f"--- Layer 4 batch {batch_num} (API: {calls_made}/{max_calls}) ---")
+
+            processed, fixed = adapter.run(config, self.deps)
+
+            # Issue #160: processed == -1 means rate-limited
+            if processed == -1:
+                logger.info("Batch skipped due to rate limiting - not counting toward exhaustion")
+                _processing_status["current"] = "Rate limited, waiting for cooldown..."
+                _processing_status["last_activity"] = "Waiting for rate limit cooldown"
+                _processing_status["last_activity_time"] = time.time()
+                time.sleep(30)
+                continue
+
+            if processed == 0:
+                # Check if AI providers are circuit-broken
+                ai_provider = config.get('ai_provider', 'gemini')
+                providers_to_check = [ai_provider]
+                if ai_provider != 'bookdb':
+                    providers_to_check.append('bookdb')
+
+                any_circuit_open = False
+                if is_circuit_open:
+                    any_circuit_open = any(is_circuit_open(p) for p in providers_to_check)
+
+                if any_circuit_open:
+                    broken = ', '.join(p for p in providers_to_check if is_circuit_open(p))
+                    logger.info(f"AI providers circuit-broken ({broken}) - waiting for recovery")
+                    _processing_status["current"] = "AI provider cooling down, waiting..."
+                    _processing_status["last_activity"] = "Waiting for circuit breaker recovery"
+                    _processing_status["last_activity_time"] = time.time()
+                    time.sleep(30)
+                    continue
+
+                conn = get_db()
+                c = conn.cursor()
+                c.execute('SELECT COUNT(*) as count FROM queue')
+                remaining = c.fetchone()['count']
+                conn.close()
+
+                if remaining == 0:
+                    logger.info("Queue is now empty")
+                    break
+                else:
+                    empty_batch_count += 1
+                    logger.warning(f"No items processed but {remaining} remain (attempt {empty_batch_count}/3)")
+                    if empty_batch_count >= 3:
+                        self._mark_orphaned_items(remaining)
+                        break
+                    time.sleep(10)
+                    continue
+
+            empty_batch_count = 0
+            layer_processed += processed
+            layer_fixed += fixed
+            _processing_status["processed"] = _processing_status.get("processed", 0) + processed
+            logger.info(f"Layer 4 Batch {batch_num}: {processed} processed, {fixed} fixed")
+            time.sleep(min_delay)
+
+        logger.info(f"Layer 4 complete: {layer_processed} items processed, {layer_fixed} fixed via folder fallback")
+        return layer_processed, layer_fixed
+
+    def _wait_for_circuit_breaker(
+        self,
+        layer_info,
+        is_circuit_open: Callable,
+        get_circuit_breaker: Callable,
+    ) -> Optional[str]:
+        """Wait for circuit breakers to close before processing.
+
+        Checks all circuit breaker APIs for the layer. If any are open,
+        waits up to 60s at a time, checking _worker_running.
+
+        Args:
+            layer_info: LayerInfo with circuit_breaker_apis.
+            is_circuit_open: Function to check if a circuit breaker is open.
+            get_circuit_breaker: Function to get circuit breaker state dict.
+
+        Returns:
+            None if no circuit breaker is open (proceed normally).
+            'continue' if we waited and should re-check.
+            'break' if worker was stopped during wait.
+        """
+        import library_manager.worker as _worker_mod
+        global _processing_status
+
+        for api_name in layer_info.circuit_breaker_apis:
+            if is_circuit_open(api_name):
+                cb = get_circuit_breaker(api_name)
+                remaining = int(cb.get('circuit_open_until', 0) - time.time())
+                if remaining > 0:
+                    wait_time = min(remaining, 60)
+                    logger.info(
+                        f"[{layer_info.layer_name}] {api_name} circuit breaker open, "
+                        f"waiting {wait_time}s ({remaining}s total remaining)"
+                    )
+                    _processing_status["current"] = (
+                        f"{layer_info.layer_name}: Waiting for {api_name} ({remaining}s)"
+                    )
+
+                    # Sleep in small increments to check worker stop
+                    for _ in range(wait_time):
+                        if not _worker_mod._worker_running:
+                            return 'break'
+                        time.sleep(1)
+
+                    return 'continue'
+
+        return None  # No circuit breaker is open
+
+    def _handle_disabled_layer(self, layer_info) -> None:
+        """Handle a disabled layer by advancing stuck items past it.
+
+        When audio_credits (Layer 2) is disabled, items stuck at
+        verification_layer=2 need to be advanced to Layer 4 so they
+        get processed by the folder fallback.
+
+        Args:
+            layer_info: LayerInfo for the disabled layer.
+        """
+        if layer_info.layer_id == 'audio_credits':
+            get_db = self.deps['get_db']
+            conn = get_db()
+            c = conn.cursor()
+            c.execute('SELECT id FROM books WHERE verification_layer = 2 AND status = "pending"')
+            layer2_books = [row['id'] for row in c.fetchall()]
+            if layer2_books:
+                c.execute('UPDATE books SET verification_layer = 4 WHERE verification_layer = 2 AND status = "pending"')
+                for book_id in layer2_books:
+                    c.execute('SELECT id FROM queue WHERE book_id = ?', (book_id,))
+                    if not c.fetchone():
+                        c.execute(
+                            'INSERT INTO queue (book_id, reason, priority) VALUES (?, ?, ?)',
+                            (book_id, 'layer2_fallback', 5),
+                        )
+                conn.commit()
+                logger.info(f"Layer 2 disabled - advanced {len(layer2_books)} items to Layer 4 (folder fallback)")
+            conn.close()
+
+    def _advance_stuck_layer2_items(self) -> None:
+        """Advance items stuck at verification_layer=2 when audio analysis is disabled.
+
+        This runs once at pipeline start, before any layers execute.
+        Identical to the logic at the top of process_all_queue.
+        """
+        get_db = self.deps['get_db']
+        conn = get_db()
+        c = conn.cursor()
+        c.execute('SELECT id FROM books WHERE verification_layer = 2 AND status = "pending"')
+        stuck_books = [row['id'] for row in c.fetchall()]
+        if stuck_books:
+            c.execute('UPDATE books SET verification_layer = 4 WHERE verification_layer = 2 AND status = "pending"')
+            for book_id in stuck_books:
+                c.execute('SELECT id FROM queue WHERE book_id = ?', (book_id,))
+                if not c.fetchone():
+                    c.execute(
+                        'INSERT INTO queue (book_id, reason, priority) VALUES (?, ?, ?)',
+                        (book_id, 'startup_layer2_recovery', 5),
+                    )
+            conn.commit()
+            logger.info(f"Advanced {len(stuck_books)} stuck items from Layer 2 to Layer 4")
+        conn.close()
+
+    def _mark_orphaned_items(self, remaining: int) -> None:
+        """Mark orphaned queue items as needs_attention after 3-strike exhaustion.
+
+        Replicates the Issue #131 logic from process_all_queue.
+
+        Args:
+            remaining: Number of items remaining in queue.
+        """
+        get_db = self.deps['get_db']
+        logger.info(f"Layer 4 cannot process remaining {remaining} items - marking as needs_attention")
+        conn = get_db()
+        try:
+            c = conn.cursor()
+            # Issue #168: Increment attempt_count and record last_attempted
+            c.execute('''UPDATE books SET status = 'needs_attention',
+                            error_message = 'All processing layers exhausted - could not identify this book automatically',
+                            attempt_count = COALESCE(attempt_count, 0) + 1,
+                            last_attempted = CURRENT_TIMESTAMP,
+                            max_layer_reached = MAX(COALESCE(max_layer_reached, 0), COALESCE(verification_layer, 0))
+                         WHERE id IN (
+                             SELECT q.book_id FROM queue q
+                             JOIN books b ON q.book_id = b.id
+                             WHERE b.status NOT IN ('verified', 'fixed', 'series_folder', 'multi_book_files', 'needs_attention')
+                               AND (b.user_locked IS NULL OR b.user_locked = 0)
+                         )''')
+            orphaned = c.rowcount
+            c.execute('''DELETE FROM queue WHERE book_id IN (
+                             SELECT id FROM books WHERE status = 'needs_attention'
+                         )''')
+            conn.commit()
+            if orphaned:
+                logger.info(f"Marked {orphaned} orphaned queue items as needs_attention")
+        finally:
+            conn.close()
+
+    def run_single_layer(self, layer_id: str) -> Tuple[int, int]:
+        """Run just one specific layer (for standalone/manual execution).
+
+        Useful for testing or manually triggering a single layer from
+        the API without running the full pipeline.
+
+        Args:
+            layer_id: The layer_id to run (must be registered and have an adapter).
+
+        Returns:
+            Tuple of (processed, resolved).
+
+        Raises:
+            KeyError: If layer_id is not registered.
+            ValueError: If no adapter exists for the layer.
+        """
+        layer_info = self.registry.get_layer(layer_id)
+        if layer_info is None:
+            raise KeyError(f"Unknown layer_id: {layer_id}")
+
+        adapter = self.adapters.get(layer_id)
+        if adapter is None:
+            raise ValueError(f"No adapter registered for layer: {layer_id}")
+
+        return adapter.run(self.config, self.deps)
+
+
+__all__ = ['PipelineOrchestrator']
diff --git a/library_manager/worker.py b/library_manager/worker.py
index 25a8634..1e9a5a4 100644
--- a/library_manager/worker.py
+++ b/library_manager/worker.py
@@ -143,6 +143,11 @@ def process_all_queue(
 
     Philosophy: The audio content IS the book. Folder names can be wrong.
 
+    When config['use_modular_pipeline'] is True, delegates to
+    PipelineOrchestrator instead of running the hardcoded sequence below.
+    The orchestrator uses the same layer functions via adapter objects
+    and produces identical behavior, but is configurable via pipeline_order.
+
     Args:
         config: Configuration dict
         get_db: Function to get database connection. Returns a new
@@ -162,6 +167,33 @@ def process_all_queue(
     Returns:
         Tuple of (total_processed, total_fixed)
     """
+    # Feature flag: use modular pipeline orchestrator when enabled
+    if config.get('use_modular_pipeline', False):
+        from library_manager.pipeline.orchestrator import PipelineOrchestrator
+        from library_manager.pipeline.adapters import build_default_adapters
+        from library_manager.pipeline.registry import default_registry
+
+        deps = {
+            'get_db': get_db,
+            'load_config': load_config,
+            'is_circuit_open': is_circuit_open,
+            'get_circuit_breaker': get_circuit_breaker,
+            'check_rate_limit': check_rate_limit,
+            'process_layer_1_audio': process_layer_1_audio,
+            'process_layer_3_audio': process_layer_3_audio,
+            'process_layer_1_api': process_layer_1_api,
+            'process_queue': process_queue,
+            'process_sl_requeue_verification': process_sl_requeue_verification,
+        }
+        orchestrator = PipelineOrchestrator(
+            registry=default_registry,
+            adapters=build_default_adapters(),
+            config=config,
+            deps=deps,
+        )
+        return orchestrator.run_pipeline()
+
+    # === Legacy hardcoded pipeline (default, unchanged) ===
     global _processing_status
 
     conn = get_db()

From 6182293b37fcfdd68f652ae52d5cdf07c4b17338 Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Tue, 10 Mar 2026 17:55:35 -0500
Subject: [PATCH 06/20] feat: Add pipeline configuration UI in settings (#66)
 (#183)

* Addresses #66: Add pipeline configuration UI in settings

* fix: Wire up pipeline layer toggles and add version bump/changelog

- Add name attribute to pipeline layer toggle checkboxes so they submit with form
- Bump version to beta.136
- Add CHANGELOG entry for pipeline configuration UI

* fix: Use existing json import instead of inline alias

---------

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 CHANGELOG.md            |  11 +++
 README.md               |   2 +-
 app.py                  |  28 ++++++-
 templates/settings.html | 159 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 197 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ec063ac..1b61438 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.136] - 2026-03-10
+
+### Added
+
+- **Issue #66: Pipeline configuration UI in settings** - New "Processing Pipeline Order" section
+  in Settings > Processing with drag-and-drop and arrow button reordering of processing layers.
+  Each layer shows enable/disable toggle that saves to config. Experimental `use_modular_pipeline`
+  feature flag toggle. "Reset to Default Order" button. Pipeline order saved as JSON to config.
+
+---
+
 ## [0.9.0-beta.135] - 2026-03-10
 
 ### Added
diff --git a/README.md b/README.md
index 4ad36bb..4ae8fde 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.135-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.136-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
diff --git a/app.py b/app.py
index aefc156..e51b4cd 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.135"
+APP_VERSION = "0.9.0-beta.136"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
@@ -7318,6 +7318,22 @@ def settings_page():
         text_chain_str = request.form.get('text_provider_chain', 'gemini,openrouter').strip()
         config['text_provider_chain'] = [p.strip() for p in text_chain_str.split(',') if p.strip()]
 
+        # Pipeline order and modular pipeline feature flag
+        config['use_modular_pipeline'] = 'use_modular_pipeline' in request.form
+        pipeline_order_json = request.form.get('pipeline_order', '').strip()
+        if pipeline_order_json:
+            try:
+                proposed_order = json.loads(pipeline_order_json)
+                if isinstance(proposed_order, list):
+                    from library_manager.pipeline.registry import default_registry
+                    is_valid, errors = default_registry.validate_order(proposed_order)
+                    if is_valid:
+                        config['pipeline_order'] = proposed_order
+                    else:
+                        logger.warning(f"Invalid pipeline_order from settings form: {errors}")
+            except (ValueError, TypeError) as e:
+                logger.warning(f"Failed to parse pipeline_order from settings form: {e}")
+
         # Save config (without secrets)
         save_config(config)
 
@@ -7350,7 +7366,15 @@ def settings_page():
     config['openrouter_api_key'] = secrets.get('openrouter_api_key', '')
     config['google_books_api_key'] = secrets.get('google_books_api_key', '')
     config['bookdb_api_key'] = secrets.get('bookdb_api_key', '')
-    return render_template('settings.html', config=config, version=APP_VERSION)
+    # Pipeline layer info for settings UI
+    from library_manager.pipeline.registry import default_registry
+    pipeline_layers = default_registry.get_ordered_layers(config)
+    pipeline_order = [layer.layer_id for layer in pipeline_layers]
+    pipeline_default_order = default_registry.get_all_layer_ids()
+    return render_template('settings.html', config=config, version=APP_VERSION,
+                           pipeline_layers=pipeline_layers,
+                           pipeline_order=pipeline_order,
+                           pipeline_default_order=pipeline_default_order)
 
 
 # ============== PATH DIAGNOSTIC ==============
diff --git a/templates/settings.html b/templates/settings.html
index c2dd7fe..ced67bc 100644
--- a/templates/settings.html
+++ b/templates/settings.html
@@ -668,6 +668,76 @@ <h5 class="mt-2">Demo Mode</h5>
                     </div>
                 </div>
             </div>
+
+            <!-- Processing Pipeline Order -->
+            <div class="row mt-3">
+                <div class="col-12">
+                    <div class="card mb-3">
+                        <div class="card-header py-2">
+                            <i class="bi bi-sort-numeric-down"></i> Processing Pipeline Order
+                        </div>
+                        <div class="card-body">
+                            <p class="text-muted small mb-3">
+                                Drag layers to reorder, or use the arrow buttons. The pipeline processes books through each enabled layer in this order.
+                            </p>
+
+                            <!-- Feature flag -->
+                            <div class="form-check form-switch mb-3">
+                                <input class="form-check-input" type="checkbox" name="use_modular_pipeline" id="use_modular_pipeline"
+                                       {% if config.use_modular_pipeline %}checked{% endif %}>
+                                <label class="form-check-label" for="use_modular_pipeline">
+                                    <strong>Enable Modular Pipeline</strong>
+                                    <span class="badge bg-warning text-dark ms-1">Experimental</span>
+                                    <br><small class="text-muted">Use the new PipelineOrchestrator instead of the built-in processing logic. Layer order below only applies when this is enabled.</small>
+                                </label>
+                            </div>
+
+                            <!-- Pipeline layer list -->
+                            <div id="pipeline-layer-list">
+                                {% for layer in pipeline_layers %}
+                                <div class="pipeline-layer d-flex align-items-center p-2 mb-2 rounded border"
+                                     draggable="true"
+                                     data-layer-id="{{ layer.layer_id }}"
+                                     data-enable-key="{{ layer.config_enable_key }}"
+                                     style="background: rgba(255,255,255,0.03); cursor: grab;">
+                                    <span class="pipeline-drag-handle me-2 text-muted" style="cursor: grab; font-size: 1.2rem; user-select: none;">&#x2261;</span>
+                                    <span class="pipeline-position badge bg-secondary me-2" style="min-width: 28px;">{{ loop.index }}</span>
+                                    <div class="flex-grow-1">
+                                        <strong>{{ layer.layer_name }}</strong>
+                                        <br><small class="text-muted">{{ layer.description }}</small>
+                                    </div>
+                                    <div class="d-flex align-items-center ms-2 gap-1">
+                                        <div class="form-check form-switch mb-0 me-2">
+                                            <input class="form-check-input pipeline-layer-toggle" type="checkbox"
+                                                   name="{{ layer.config_enable_key }}"
+                                                   id="pipeline-toggle-{{ layer.layer_id }}"
+                                                   {% if config.get(layer.config_enable_key, True) %}checked{% endif %}
+                                                   data-layer-id="{{ layer.layer_id }}"
+                                                   title="Enable/disable this layer">
+                                        </div>
+                                        <button type="button" class="btn btn-sm btn-outline-secondary pipeline-move-up" title="Move up" onclick="movePipelineLayer(this, -1)">
+                                            <i class="bi bi-arrow-up"></i>
+                                        </button>
+                                        <button type="button" class="btn btn-sm btn-outline-secondary pipeline-move-down" title="Move down" onclick="movePipelineLayer(this, 1)">
+                                            <i class="bi bi-arrow-down"></i>
+                                        </button>
+                                    </div>
+                                </div>
+                                {% endfor %}
+                            </div>
+
+                            <!-- Hidden input for form submission -->
+                            <input type="hidden" name="pipeline_order" id="pipeline_order_input" value="{{ pipeline_order | tojson }}">
+
+                            <div class="mt-2">
+                                <button type="button" class="btn btn-sm btn-outline-secondary" onclick="resetPipelineOrder()">
+                                    <i class="bi bi-arrow-counterclockwise"></i> Reset to Default Order
+                                </button>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
         </div>
 
         <!-- ==================== AI SETUP TAB ==================== -->
@@ -2531,5 +2601,94 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
 // Initial render if hooks exist
 if (hooksData.length) renderHooksList();
 else document.getElementById('hooks-empty') && (document.getElementById('hooks-empty').style.display = 'block');
+
+// ==================== PIPELINE ORDER ====================
+var pipelineDefaultOrder = {{ pipeline_default_order | tojson }};
+
+function updatePipelineOrderInput() {
+    var list = document.getElementById('pipeline-layer-list');
+    if (!list) return;
+    var items = list.querySelectorAll('.pipeline-layer');
+    var order = [];
+    items.forEach(function(item, idx) {
+        order.push(item.getAttribute('data-layer-id'));
+        var badge = item.querySelector('.pipeline-position');
+        if (badge) badge.textContent = idx + 1;
+    });
+    document.getElementById('pipeline_order_input').value = JSON.stringify(order);
+}
+
+function movePipelineLayer(btn, direction) {
+    var item = btn.closest('.pipeline-layer');
+    var list = item.parentNode;
+    var items = Array.from(list.querySelectorAll('.pipeline-layer'));
+    var idx = items.indexOf(item);
+    var newIdx = idx + direction;
+    if (newIdx < 0 || newIdx >= items.length) return;
+    if (direction === -1) {
+        list.insertBefore(item, items[newIdx]);
+    } else {
+        list.insertBefore(items[newIdx], item);
+    }
+    updatePipelineOrderInput();
+}
+
+function resetPipelineOrder() {
+    var list = document.getElementById('pipeline-layer-list');
+    if (!list) return;
+    var items = Array.from(list.querySelectorAll('.pipeline-layer'));
+    // Sort by default order
+    items.sort(function(a, b) {
+        return pipelineDefaultOrder.indexOf(a.getAttribute('data-layer-id')) - pipelineDefaultOrder.indexOf(b.getAttribute('data-layer-id'));
+    });
+    items.forEach(function(item) { list.appendChild(item); });
+    updatePipelineOrderInput();
+}
+
+// Drag and drop for pipeline layers
+(function() {
+    var dragItem = null;
+    var list = document.getElementById('pipeline-layer-list');
+    if (!list) return;
+
+    list.addEventListener('dragstart', function(e) {
+        dragItem = e.target.closest('.pipeline-layer');
+        if (dragItem) {
+            dragItem.style.opacity = '0.5';
+            e.dataTransfer.effectAllowed = 'move';
+        }
+    });
+
+    list.addEventListener('dragend', function(e) {
+        if (dragItem) {
+            dragItem.style.opacity = '1';
+            dragItem = null;
+        }
+        list.querySelectorAll('.pipeline-layer').forEach(function(el) {
+            el.style.borderTop = '';
+        });
+    });
+
+    list.addEventListener('dragover', function(e) {
+        e.preventDefault();
+        e.dataTransfer.dropEffect = 'move';
+        var target = e.target.closest('.pipeline-layer');
+        list.querySelectorAll('.pipeline-layer').forEach(function(el) {
+            el.style.borderTop = '';
+        });
+        if (target && target !== dragItem) {
+            target.style.borderTop = '2px solid #00d9ff';
+        }
+    });
+
+    list.addEventListener('drop', function(e) {
+        e.preventDefault();
+        var target = e.target.closest('.pipeline-layer');
+        if (target && dragItem && target !== dragItem) {
+            list.insertBefore(dragItem, target);
+            updatePipelineOrderInput();
+        }
+    });
+})();
 </script>
 {% endblock %}

From d0e07b33a49fe68b0928d35933bbc760194afc0a Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Tue, 10 Mar 2026 18:01:50 -0500
Subject: [PATCH 07/20] feat: Add standalone layer execution API and UI (#66)
 (#184)

* Addresses #66: Add standalone layer execution API and UI

Adds POST /api/pipeline/run-layer/<layer_id> endpoint that runs a single
pipeline layer on demand (synchronous). Adds a play button next to each
layer in the settings pipeline section with spinner feedback and result
badges showing processed/resolved counts.

* chore: Bump version to beta.137 for standalone layer execution (#66)

---------

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 CHANGELOG.md            | 10 +++++
 README.md               |  2 +-
 app.py                  | 91 ++++++++++++++++++++++++++++++++++++++++-
 templates/settings.html | 61 +++++++++++++++++++++++++++
 4 files changed, 162 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1b61438..021d925 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,16 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.137] - 2026-03-10
+
+### Added
+
+- **Issue #66: Standalone layer execution** - Play button next to each layer in the pipeline
+  settings section. Runs a single pipeline layer on demand via `POST /api/pipeline/run-layer/<id>`.
+  Shows spinner during execution and result badge with processed/resolved counts.
+
+---
+
 ## [0.9.0-beta.136] - 2026-03-10
 
 ### Added
diff --git a/README.md b/README.md
index 4ae8fde..2e4a0f4 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.136-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.137-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
diff --git a/app.py b/app.py
index e51b4cd..8e2b42e 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.136"
+APP_VERSION = "0.9.0-beta.137"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
@@ -8064,6 +8064,95 @@ def api_process_status():
     return jsonify(get_processing_status())
 
 
+@app.route('/api/pipeline/run-layer/<layer_id>', methods=['POST'])
+def api_run_single_layer(layer_id):
+    """Run a single pipeline layer on demand.
+
+    Executes one batch of the specified layer synchronously.
+    The request blocks until the layer finishes processing its batch.
+    """
+    global _bg_processing_active
+
+    # Validate layer_id exists in registry
+    from library_manager.pipeline.registry import default_registry
+    layer_info = default_registry.get_layer(layer_id)
+    if layer_info is None:
+        return jsonify({
+            'success': False,
+            'message': f'Unknown layer: {layer_id}'
+        }), 404
+
+    # Check that background processing is not currently running
+    if _bg_processing_active:
+        return jsonify({
+            'success': False,
+            'message': 'Background processing is already running. Wait for it to finish.'
+        }), 409
+
+    config = load_config()
+
+    # Check that the layer is enabled in config
+    if not config.get(layer_info.config_enable_key, True):
+        return jsonify({
+            'success': False,
+            'message': f'Layer "{layer_info.layer_name}" is disabled. Enable it in settings first.'
+        }), 400
+
+    # Map layer_id to the corresponding processing function
+    layer_functions = {
+        'audio_id': lambda: process_layer_1_audio(config),
+        'audio_credits': lambda: process_layer_3_audio(config, verification_layer=2),
+        'sl_requeue': lambda: process_sl_requeue_verification(config),
+        'api_lookup': lambda: process_layer_1_api(config),
+        'ai_verify': lambda: process_queue(config, verification_layer=4),
+    }
+
+    layer_func = layer_functions.get(layer_id)
+    if layer_func is None:
+        return jsonify({
+            'success': False,
+            'message': f'Layer "{layer_id}" does not have a processing function mapped.'
+        }), 501
+
+    # Update status to show this layer is running
+    update_processing_status('active', True)
+    update_processing_status('layer_name', layer_info.layer_name)
+    update_processing_status('current', f'Running {layer_info.layer_name} (manual)...')
+
+    try:
+        processed, resolved = layer_func()
+        # process_queue returns -1 when rate-limited
+        if processed == -1:
+            processed = 0
+            message = f'{layer_info.layer_name}: Rate limited, try again later.'
+        elif processed == 0:
+            message = f'{layer_info.layer_name}: No items to process at this layer.'
+        else:
+            message = f'{layer_info.layer_name}: {processed} processed, {resolved} resolved.'
+
+        log_action("run_layer", detail=f"layer={layer_id} processed={processed} resolved={resolved}", result="success")
+
+        return jsonify({
+            'success': True,
+            'layer_id': layer_id,
+            'layer_name': layer_info.layer_name,
+            'processed': max(0, processed),
+            'resolved': resolved,
+            'message': message
+        })
+    except Exception as e:
+        logger.error(f"Error running layer {layer_id}: {e}", exc_info=True)
+        return jsonify({
+            'success': False,
+            'message': f'Error running {layer_info.layer_name}: {str(e)}'
+        }), 500
+    finally:
+        update_processing_status('active', False)
+        update_processing_status('layer_name', 'Idle')
+        update_processing_status('current', 'Idle')
+        clear_current_book()
+
+
 @app.route('/api/live_status')
 def api_live_status():
     """Get comprehensive live status for the status bar.
diff --git a/templates/settings.html b/templates/settings.html
index ced67bc..1684516 100644
--- a/templates/settings.html
+++ b/templates/settings.html
@@ -3,6 +3,12 @@
 
 {% block content %}
 <style>
+    .spin-icon {
+        animation: spin-anim 1s linear infinite;
+    }
+    @keyframes spin-anim {
+        100% { transform: rotate(360deg); }
+    }
     .hint-icon {
         display: inline-flex;
         align-items: center;
@@ -721,6 +727,12 @@ <h5 class="mt-2">Demo Mode</h5>
                                         <button type="button" class="btn btn-sm btn-outline-secondary pipeline-move-down" title="Move down" onclick="movePipelineLayer(this, 1)">
                                             <i class="bi bi-arrow-down"></i>
                                         </button>
+                                        <button type="button" class="btn btn-sm btn-outline-primary pipeline-run-btn ms-1"
+                                                title="Run this layer now"
+                                                data-layer-id="{{ layer.layer_id }}"
+                                                onclick="runPipelineLayer(this)">
+                                            <i class="bi bi-play-fill"></i>
+                                        </button>
                                     </div>
                                 </div>
                                 {% endfor %}
@@ -2645,6 +2657,55 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
     updatePipelineOrderInput();
 }
 
+function runPipelineLayer(btn) {
+    var layerId = btn.getAttribute('data-layer-id');
+    var icon = btn.querySelector('i');
+    var origClass = icon.className;
+
+    // Show spinner
+    icon.className = 'bi bi-arrow-repeat spin-icon';
+    btn.disabled = true;
+
+    // Remove any previous result badge on this layer
+    var layerDiv = btn.closest('.pipeline-layer');
+    var oldBadge = layerDiv.querySelector('.pipeline-run-result');
+    if (oldBadge) oldBadge.remove();
+
+    fetch('/api/pipeline/run-layer/' + layerId, {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'}
+    })
+    .then(function(resp) { return resp.json(); })
+    .then(function(data) {
+        icon.className = origClass;
+        btn.disabled = false;
+
+        var badge = document.createElement('span');
+        badge.className = 'pipeline-run-result badge ms-2 small';
+        if (data.success) {
+            badge.classList.add('bg-success');
+            badge.textContent = data.processed + ' processed, ' + data.resolved + ' resolved';
+        } else {
+            badge.classList.add('bg-danger');
+            badge.textContent = data.message || 'Error';
+        }
+        layerDiv.querySelector('.flex-grow-1').appendChild(badge);
+
+        // Auto-remove after 10 seconds
+        setTimeout(function() { badge.remove(); }, 10000);
+    })
+    .catch(function(err) {
+        icon.className = origClass;
+        btn.disabled = false;
+
+        var badge = document.createElement('span');
+        badge.className = 'pipeline-run-result badge bg-danger ms-2 small';
+        badge.textContent = 'Network error';
+        layerDiv.querySelector('.flex-grow-1').appendChild(badge);
+        setTimeout(function() { badge.remove(); }, 10000);
+    });
+}
+
 // Drag and drop for pipeline layers
 (function() {
     var dragItem = null;

From 63988497c59f9bd4d38e1b491957efd9a3128c70 Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Sat, 21 Mar 2026 10:33:23 -0500
Subject: [PATCH 08/20] feat: Template HTTP layers - no-code custom API sources
 (#185) (#191)

Adds CustomApiLayer backend for user-defined HTTP API processing layers. Includes JSONPath extractor, URL template substitution, auth support (bearer/api_key/basic), per-layer circuit breakers, and registration into LayerRegistry. Foundation for #66 Phase 5.

Closes #185
---
 CHANGELOG.md                             |  10 +
 README.md                                |   2 +-
 app.py                                   |   2 +-
 library_manager/config.py                |   2 +
 library_manager/pipeline/custom_layer.py | 678 +++++++++++++++++++++++
 5 files changed, 692 insertions(+), 2 deletions(-)
 create mode 100644 library_manager/pipeline/custom_layer.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 021d925..bf3146c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,16 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.138] - 2026-03-21
+
+### Fixed
+
+- **Issue #185: Custom layer infinite reprocessing** - `CustomApiLayer._apply_result` now
+  advances `verification_layer` to `self.order + 1` after updating the book profile. Previously
+  the layer never advanced the item, causing `_fetch_batch` to pick up the same books every cycle.
+
+---
+
 ## [0.9.0-beta.137] - 2026-03-10
 
 ### Added
diff --git a/README.md b/README.md
index 2e4a0f4..a097120 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.137-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.138-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
diff --git a/app.py b/app.py
index 8e2b42e..63c6d58 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.137"
+APP_VERSION = "0.9.0-beta.138"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
diff --git a/library_manager/config.py b/library_manager/config.py
index 9bfc193..858c772 100644
--- a/library_manager/config.py
+++ b/library_manager/config.py
@@ -140,6 +140,8 @@ def _detect_data_dir():
     "watch_min_file_age_seconds": 30,      # Minimum file age before processing (wait for downloads to complete)
     # Post-processing hooks - run commands/webhooks after a book is renamed (Issue #166)
     "post_processing_hooks": [],
+    # Custom HTTP API layers - user-defined external API processing layers (Issue #185)
+    "custom_layers": [],
     # Issue #110: File validation - check audio files before processing
     "enable_file_validation": True,            # Validate audio files with ffprobe before queueing
     "min_audio_duration_seconds": 600,         # Minimum duration (seconds) to consider a valid audiobook (default: 10 min)
diff --git a/library_manager/pipeline/custom_layer.py b/library_manager/pipeline/custom_layer.py
new file mode 100644
index 0000000..4f295fd
--- /dev/null
+++ b/library_manager/pipeline/custom_layer.py
@@ -0,0 +1,678 @@
+"""Custom HTTP API layers for the processing pipeline.
+
+Allows users to define custom API endpoints that act as processing layers.
+Each custom layer makes HTTP requests to external services and maps the
+response fields back into the book profile system.
+
+Config schema (in config.json under "custom_layers"):
+    {
+        "layer_id": "my_bookdb",
+        "layer_name": "My Book Database",
+        "enabled": true,
+        "order": 35,
+        "url_template": "https://api.example.com/search?title={{title}}&author={{author}}",
+        "method": "GET",
+        "timeout": 10,
+        "auth": {"type": "bearer", "token_secret_key": "my_bookdb_key"},
+        "request_fields": ["title", "author", "narrator", "path"],
+        "response_mapping": {
+            "title": "$.results[0].title",
+            "author": "$.results[0].author_name"
+        },
+        "source_weight": 55,
+        "on_error": "skip",
+        "circuit_breaker": {"max_failures": 3, "cooldown": 300}
+    }
+"""
+
+import json
+import logging
+import re
+import time
+from base64 import b64encode
+from typing import Any, Callable, Dict, List, Optional, Tuple
+from urllib.parse import quote as url_quote
+
+import requests as http_requests
+
+from library_manager.config import load_secrets
+from library_manager.models.book_profile import BookProfile
+
+logger = logging.getLogger(__name__)
+
+# Default limits
+DEFAULT_TIMEOUT = 10
+MAX_TIMEOUT = 60
+DEFAULT_BATCH_SIZE = 10
+
+# Circuit breaker state: layer_id -> {"failures": int, "cooldown_until": float}
+_circuit_breakers = {}
+
+
+# ============== JSONPATH EXTRACTION ==============
+
+def extract_jsonpath(data: Any, path: str) -> Any:
+    """Extract a value from nested data using a simple JSONPath expression.
+
+    Supports:
+        $.key              - top-level access
+        $.nested.key       - dot-notation nesting
+        $.array[0].field   - array index access
+
+    Args:
+        data: Parsed JSON data (dict, list, or primitive)
+        path: JSONPath expression starting with $
+
+    Returns:
+        Extracted value, or None if path doesn't resolve
+    """
+    if not path or not path.startswith('$'):
+        return None
+
+    # Strip the leading $
+    remaining = path[1:]
+    if not remaining:
+        return data
+
+    # Strip leading dot if present
+    if remaining.startswith('.'):
+        remaining = remaining[1:]
+
+    current = data
+
+    # Tokenize: split on dots but handle array indices like [0]
+    # e.g. "results[0].title" -> ["results[0]", "title"]
+    tokens = _tokenize_jsonpath(remaining)
+
+    for token in tokens:
+        if current is None:
+            return None
+
+        # Check for array index: fieldname[N] or just [N]
+        match = re.match(r'^([^\[]*)\[(\d+)\]$', token)
+        if match:
+            field_name = match.group(1)
+            index = int(match.group(2))
+
+            # Navigate to field first (if present)
+            if field_name:
+                if isinstance(current, dict):
+                    current = current.get(field_name)
+                else:
+                    return None
+
+            # Then index into array
+            if isinstance(current, (list, tuple)):
+                if 0 <= index < len(current):
+                    current = current[index]
+                else:
+                    return None
+            else:
+                return None
+        else:
+            # Simple field access
+            if isinstance(current, dict):
+                current = current.get(token)
+            else:
+                return None
+
+    return current
+
+
+def _tokenize_jsonpath(path: str) -> List[str]:
+    """Split a JSONPath remainder into tokens, respecting array brackets.
+
+    Examples:
+        "results[0].title" -> ["results[0]", "title"]
+        "a.b.c" -> ["a", "b", "c"]
+        "items[2].nested[0].value" -> ["items[2]", "nested[0]", "value"]
+    """
+    tokens = []
+    current = ''
+
+    i = 0
+    while i < len(path):
+        ch = path[i]
+        if ch == '.':
+            if current:
+                tokens.append(current)
+                current = ''
+        elif ch == '[':
+            # Consume until closing bracket
+            bracket_start = i
+            while i < len(path) and path[i] != ']':
+                i += 1
+            current += path[bracket_start:i + 1]  # include ]
+        else:
+            current += ch
+        i += 1
+
+    if current:
+        tokens.append(current)
+
+    return tokens
+
+
+# ============== CIRCUIT BREAKER ==============
+
+def _check_circuit_breaker(layer_id: str) -> bool:
+    """Check if the circuit breaker allows requests for this layer.
+
+    Returns:
+        True if requests are allowed, False if circuit is open (cooldown active)
+    """
+    state = _circuit_breakers.get(layer_id)
+    if not state:
+        return True
+
+    cooldown_until = state.get('cooldown_until', 0)
+    if time.monotonic() < cooldown_until:
+        return False
+
+    # Cooldown expired, reset
+    if state.get('failures', 0) > 0:
+        state['failures'] = 0
+    return True
+
+
+def _record_failure(layer_id: str, max_failures: int, cooldown: int):
+    """Record a failure and potentially trip the circuit breaker."""
+    if layer_id not in _circuit_breakers:
+        _circuit_breakers[layer_id] = {'failures': 0, 'cooldown_until': 0}
+
+    state = _circuit_breakers[layer_id]
+    state['failures'] = state.get('failures', 0) + 1
+
+    if state['failures'] >= max_failures:
+        state['cooldown_until'] = time.monotonic() + cooldown
+        logger.warning(
+            f"[CUSTOM:{layer_id}] Circuit breaker tripped after {state['failures']} failures, "
+            f"cooldown {cooldown}s"
+        )
+
+
+def _record_success(layer_id: str):
+    """Record a success, resetting the failure counter."""
+    if layer_id in _circuit_breakers:
+        _circuit_breakers[layer_id]['failures'] = 0
+
+
+def init_circuit_breaker(layer_id: str):
+    """Initialize circuit breaker state for a layer."""
+    if layer_id not in _circuit_breakers:
+        _circuit_breakers[layer_id] = {'failures': 0, 'cooldown_until': 0}
+
+
+# ============== REQUEST BUILDING ==============
+
+def _build_template_context(item: Dict) -> Dict[str, str]:
+    """Build template variable context from a queue/book item.
+
+    Args:
+        item: Database row dict with book info
+
+    Returns:
+        Dict of template variables (all strings, safe for URL substitution)
+    """
+    return {
+        'title': str(item.get('current_title') or ''),
+        'author': str(item.get('current_author') or ''),
+        'narrator': str(item.get('narrator') or ''),
+        'path': str(item.get('path') or ''),
+        'isbn': str(item.get('isbn') or ''),
+    }
+
+
+def _substitute_url_template(template: str, context: Dict[str, str]) -> str:
+    """Replace {{variable}} placeholders in URL template with URL-encoded values.
+
+    Args:
+        template: URL string with {{variable}} placeholders
+        context: Dict of variable values
+
+    Returns:
+        URL with placeholders replaced by URL-encoded values
+    """
+    result = template
+    for key, value in context.items():
+        placeholder = '{{' + key + '}}'
+        if placeholder in result:
+            result = result.replace(placeholder, url_quote(str(value), safe=''))
+    return result
+
+
+def _build_auth_headers(auth_config: Optional[Dict], secrets: Dict) -> Dict[str, str]:
+    """Build authentication headers based on auth config.
+
+    Supports:
+        none         - no auth headers
+        bearer       - Authorization: Bearer <token>
+        api_key_header - X-API-Key: <token> (or custom header name)
+        basic        - Authorization: Basic <base64(user:pass)>
+
+    Args:
+        auth_config: Auth configuration dict with type and token_secret_key
+        secrets: Loaded secrets dict
+
+    Returns:
+        Dict of headers to add to the request
+    """
+    if not auth_config:
+        return {}
+
+    auth_type = auth_config.get('type', 'none')
+    if auth_type == 'none':
+        return {}
+
+    token_key = auth_config.get('token_secret_key', '')
+    token = secrets.get(token_key, '') if token_key else ''
+
+    if auth_type == 'bearer':
+        if not token:
+            logger.warning(f"Bearer auth configured but secret '{token_key}' is empty")
+            return {}
+        return {'Authorization': f'Bearer {token}'}
+
+    elif auth_type == 'api_key_header':
+        header_name = auth_config.get('header_name', 'X-API-Key')
+        if not token:
+            logger.warning(f"API key auth configured but secret '{token_key}' is empty")
+            return {}
+        return {header_name: token}
+
+    elif auth_type == 'basic':
+        username = auth_config.get('username', '')
+        password = secrets.get(token_key, '') if token_key else ''
+        credentials = b64encode(f'{username}:{password}'.encode()).decode()
+        return {'Authorization': f'Basic {credentials}'}
+
+    return {}
+
+
+# ============== CUSTOM API LAYER ==============
+
+class CustomApiLayer:
+    """A user-defined HTTP API processing layer.
+
+    Fetches book items from the queue, queries a custom API endpoint,
+    and maps the response back into book profile fields.
+    """
+
+    def __init__(self, layer_config: Dict, get_db: Callable, secrets_loader: Callable = None):
+        """Initialize the custom API layer.
+
+        Args:
+            layer_config: Layer configuration dict (see module docstring for schema)
+            get_db: Callable that returns a database connection
+            secrets_loader: Callable that returns secrets dict (defaults to load_secrets)
+        """
+        self.layer_config = layer_config
+        self.get_db = get_db
+        self._load_secrets = secrets_loader or load_secrets
+
+        self.layer_id = layer_config.get('layer_id', 'unknown')
+        self.layer_name = layer_config.get('layer_name', f'Custom: {self.layer_id}')
+        self.order = layer_config.get('order', 50)
+        self.enabled = layer_config.get('enabled', True)
+
+        self.url_template = layer_config.get('url_template', '')
+        self.method = layer_config.get('method', 'GET').upper()
+        self.timeout = min(layer_config.get('timeout', DEFAULT_TIMEOUT), MAX_TIMEOUT)
+
+        self.auth_config = layer_config.get('auth')
+        self.request_fields = layer_config.get('request_fields', ['title', 'author'])
+        self.response_mapping = layer_config.get('response_mapping', {})
+        self.source_weight = layer_config.get('source_weight', 55)
+        self.on_error = layer_config.get('on_error', 'skip')
+
+        cb_config = layer_config.get('circuit_breaker', {})
+        self.cb_max_failures = cb_config.get('max_failures', 3)
+        self.cb_cooldown = cb_config.get('cooldown', 300)
+
+        self.log_prefix = f"[CUSTOM:{self.layer_id}]"
+
+    def run(self, config: Dict, deps: Optional[Dict] = None) -> Tuple[int, int]:
+        """Run one processing cycle for this custom layer.
+
+        Matches the LayerAdapter interface: accepts config and deps,
+        returns (processed_count, resolved_count).
+
+        Args:
+            config: App configuration dict
+            deps: Optional dependencies dict (unused, for interface compatibility)
+
+        Returns:
+            Tuple of (processed_count, resolved_count)
+        """
+        if not self.enabled:
+            logger.debug(f"{self.log_prefix} Layer disabled, skipping")
+            return 0, 0
+
+        if not self.url_template:
+            logger.warning(f"{self.log_prefix} No url_template configured, skipping")
+            return 0, 0
+
+        # Check circuit breaker
+        if not _check_circuit_breaker(self.layer_id):
+            logger.debug(f"{self.log_prefix} Circuit breaker open, skipping")
+            return 0, 0
+
+        # Fetch batch from queue
+        batch = self._fetch_batch(config)
+        if not batch:
+            return 0, 0
+
+        logger.info(f"{self.log_prefix} Processing {len(batch)} items")
+
+        secrets = self._load_secrets()
+        auth_headers = _build_auth_headers(self.auth_config, secrets)
+
+        processed = 0
+        resolved = 0
+
+        for item in batch:
+            try:
+                result = self._process_item(item, auth_headers)
+                if result is not None:
+                    if self._apply_result(item, result):
+                        resolved += 1
+                processed += 1
+            except Exception as e:
+                logger.error(f"{self.log_prefix} Exception processing item {item.get('book_id')}: {e}",
+                             exc_info=True)
+                processed += 1
+
+        logger.info(f"{self.log_prefix} Processed {processed}, resolved {resolved}")
+        return processed, resolved
+
+    def _fetch_batch(self, config: Dict) -> List[Dict]:
+        """Fetch items from the queue that are at or below this layer's order.
+
+        Uses the same query pattern as base_layer.py but filters by
+        verification_layer matching the custom layer order position.
+
+        Args:
+            config: App configuration dict
+
+        Returns:
+            List of item dicts from database
+        """
+        batch_size = config.get('batch_size', DEFAULT_BATCH_SIZE)
+
+        conn = self.get_db()
+        c = conn.cursor()
+
+        # Custom layers process items at their assigned verification_layer
+        # The order field maps to a verification_layer value
+        c.execute('''SELECT q.id as queue_id, q.book_id, q.reason,
+                            b.path, b.current_author, b.current_title,
+                            b.verification_layer, b.status, b.profile,
+                            b.confidence
+                     FROM queue q
+                     JOIN books b ON q.book_id = b.id
+                     WHERE b.verification_layer = ?
+                       AND b.status NOT IN ('verified', 'fixed', 'series_folder',
+                                            'multi_book_files', 'needs_attention')
+                       AND (b.user_locked IS NULL OR b.user_locked = 0)
+                     ORDER BY q.priority, q.added_at
+                     LIMIT ?''', (self.order, batch_size))
+
+        batch = [dict(row) for row in c.fetchall()]
+        conn.close()
+
+        return batch
+
+    def _process_item(self, item: Dict, auth_headers: Dict) -> Optional[Dict]:
+        """Process a single item by calling the external API.
+
+        Args:
+            item: Database row dict with book info
+            auth_headers: Pre-built authentication headers
+
+        Returns:
+            Dict of mapped response fields, or None on error/skip
+        """
+        # Build template context from item
+        context = _build_template_context(item)
+
+        # Check we have at least one required field populated
+        has_data = any(context.get(f) for f in self.request_fields)
+        if not has_data:
+            logger.debug(f"{self.log_prefix} No request data for book_id={item.get('book_id')}, skipping")
+            return None
+
+        # Build the request URL
+        url = _substitute_url_template(self.url_template, context)
+
+        # Make the HTTP request
+        headers = dict(auth_headers)
+        headers.setdefault('Accept', 'application/json')
+
+        start = time.monotonic()
+        try:
+            if self.method == 'POST':
+                # POST with JSON body containing the context fields
+                body = {f: context.get(f, '') for f in self.request_fields}
+                headers.setdefault('Content-Type', 'application/json')
+                resp = http_requests.post(url, json=body, headers=headers, timeout=self.timeout)
+            else:
+                resp = http_requests.get(url, headers=headers, timeout=self.timeout)
+
+            duration_ms = int((time.monotonic() - start) * 1000)
+            logger.info(f"{self.log_prefix} {self.method} {url} -> {resp.status_code} ({duration_ms}ms)")
+
+            if not (200 <= resp.status_code < 300):
+                _record_failure(self.layer_id, self.cb_max_failures, self.cb_cooldown)
+                logger.warning(f"{self.log_prefix} HTTP {resp.status_code} from {url}")
+                return None
+
+            _record_success(self.layer_id)
+
+            # Parse response
+            try:
+                data = resp.json()
+            except (ValueError, json.JSONDecodeError):
+                logger.warning(f"{self.log_prefix} Non-JSON response from {url}")
+                return None
+
+            # Map response fields using JSONPath
+            mapped = {}
+            for field_name, jsonpath in self.response_mapping.items():
+                value = extract_jsonpath(data, jsonpath)
+                if value is not None:
+                    mapped[field_name] = str(value)
+
+            if not mapped:
+                logger.debug(f"{self.log_prefix} No fields mapped from response for book_id={item.get('book_id')}")
+                return None
+
+            return mapped
+
+        except http_requests.Timeout:
+            duration_ms = int((time.monotonic() - start) * 1000)
+            logger.warning(f"{self.log_prefix} Timeout after {duration_ms}ms: {url}")
+            _record_failure(self.layer_id, self.cb_max_failures, self.cb_cooldown)
+            return None
+
+        except http_requests.ConnectionError as e:
+            duration_ms = int((time.monotonic() - start) * 1000)
+            logger.warning(f"{self.log_prefix} Connection error ({duration_ms}ms): {e}")
+            _record_failure(self.layer_id, self.cb_max_failures, self.cb_cooldown)
+            return None
+
+        except Exception as e:
+            duration_ms = int((time.monotonic() - start) * 1000)
+            logger.error(f"{self.log_prefix} Request error ({duration_ms}ms): {e}")
+            _record_failure(self.layer_id, self.cb_max_failures, self.cb_cooldown)
+            return None
+
+    def _apply_result(self, item: Dict, mapped_fields: Dict) -> bool:
+        """Apply mapped response fields to the book profile in the database.
+
+        Args:
+            item: Original item dict from database
+            mapped_fields: Dict of field_name -> value from API response
+
+        Returns:
+            True if the item was resolved (profile updated), False otherwise
+        """
+        # Build a source name for this custom layer
+        source_name = f'custom_{self.layer_id}'
+
+        # Load or create profile
+        profile = BookProfile()
+        if item.get('profile'):
+            try:
+                existing = json.loads(item['profile']) if isinstance(item['profile'], str) else item['profile']
+                profile = BookProfile.from_dict(existing) if hasattr(BookProfile, 'from_dict') else profile
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+        # Apply mapped fields to profile
+        fields_applied = 0
+        for field_name, value in mapped_fields.items():
+            if not value:
+                continue
+
+            if field_name == 'author':
+                if profile.add_author(source_name, value, self.source_weight):
+                    fields_applied += 1
+            elif field_name == 'title':
+                if profile.add_title(source_name, value, self.source_weight):
+                    fields_applied += 1
+            elif field_name == 'narrator':
+                profile.narrator.add_source(source_name, value, self.source_weight)
+                fields_applied += 1
+            elif field_name == 'series':
+                profile.series.add_source(source_name, value, self.source_weight)
+                fields_applied += 1
+            elif field_name == 'series_num':
+                profile.series_num.add_source(source_name, value, self.source_weight)
+                fields_applied += 1
+            elif field_name == 'year':
+                profile.year.add_source(source_name, value, self.source_weight)
+                fields_applied += 1
+            elif field_name == 'language':
+                profile.language.add_source(source_name, value, self.source_weight)
+                fields_applied += 1
+
+        if fields_applied == 0:
+            return False
+
+        # Add this layer to verification history
+        if source_name not in profile.verification_layers_used:
+            profile.verification_layers_used.append(source_name)
+
+        profile.finalize()
+
+        # Write updated profile to database
+        profile_json = json.dumps(profile.to_dict())
+        confidence = profile.overall_confidence
+
+        conn = self.get_db()
+        c = conn.cursor()
+
+        try:
+            # Update the book with new profile data
+            # Advance verification_layer past this layer so _fetch_batch
+            # (which queries WHERE verification_layer = self.order) won't
+            # pick up the same item again next cycle
+            next_layer = self.order + 1
+            c.execute('''UPDATE books SET
+                        profile = ?,
+                        confidence = ?,
+                        verification_layer = ?,
+                        max_layer_reached = MAX(COALESCE(max_layer_reached, 0), ?)
+                        WHERE id = ?''',
+                     (profile_json, confidence, next_layer, self.order, item['book_id']))
+            conn.commit()
+
+            logger.info(
+                f"{self.log_prefix} Updated profile for book_id={item['book_id']} "
+                f"({fields_applied} fields, confidence={confidence}%)"
+            )
+            return True
+
+        except Exception as e:
+            logger.error(f"{self.log_prefix} Failed to update book {item['book_id']}: {e}")
+            conn.rollback()
+            return False
+        finally:
+            conn.close()
+
+
+# ============== REGISTRATION ==============
+
+def register_custom_layers(
+    registry: Any,
+    config: Dict,
+    get_db: Callable
+) -> List[CustomApiLayer]:
+    """Read custom_layers from config, register each in the LayerRegistry.
+
+    Args:
+        registry: LayerRegistry instance (must have .register() method)
+        config: App configuration dict (should contain "custom_layers" list)
+        get_db: Callable that returns a database connection
+
+    Returns:
+        List of instantiated CustomApiLayer adapters
+    """
+    custom_configs = config.get('custom_layers', [])
+    if not custom_configs:
+        return []
+
+    adapters = []
+
+    for layer_cfg in custom_configs:
+        layer_id = layer_cfg.get('layer_id')
+        if not layer_id:
+            logger.warning("[CUSTOM] Skipping custom layer with no layer_id")
+            continue
+
+        if not layer_cfg.get('enabled', True):
+            logger.debug(f"[CUSTOM:{layer_id}] Layer disabled, skipping registration")
+            continue
+
+        if not layer_cfg.get('url_template'):
+            logger.warning(f"[CUSTOM:{layer_id}] No url_template, skipping registration")
+            continue
+
+        # Create the adapter
+        adapter = CustomApiLayer(layer_cfg, get_db)
+
+        # Initialize circuit breaker
+        init_circuit_breaker(layer_id)
+
+        # Register in the layer registry if it has the expected interface
+        order = layer_cfg.get('order', 50)
+        layer_name = layer_cfg.get('layer_name', f'Custom: {layer_id}')
+
+        if hasattr(registry, 'register'):
+            try:
+                # LayerInfo-style registration: pass the info the registry needs
+                registry.register(
+                    layer_id=layer_id,
+                    layer_name=layer_name,
+                    order=order,
+                    adapter=adapter,
+                    layer_type='custom'
+                )
+                logger.info(f"[CUSTOM:{layer_id}] Registered custom layer '{layer_name}' at order {order}")
+            except TypeError:
+                # Registry might have a different signature - try simpler registration
+                try:
+                    registry.register(layer_id, adapter)
+                    logger.info(f"[CUSTOM:{layer_id}] Registered custom layer '{layer_name}'")
+                except Exception as e:
+                    logger.error(f"[CUSTOM:{layer_id}] Failed to register: {e}")
+                    continue
+        else:
+            logger.debug(f"[CUSTOM:{layer_id}] Registry has no register method, adapter created but not registered")
+
+        adapters.append(adapter)
+
+    if adapters:
+        logger.info(f"[CUSTOM] Registered {len(adapters)} custom layer(s)")
+
+    return adapters

From 19a4d1d2747d962ba88cf07010f2e05a81a82d83 Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Sat, 21 Mar 2026 10:41:54 -0500
Subject: [PATCH 09/20] feat: Expand hooks with event system and body templates
 (#187) (#194)

Expands hook system from fixed-only to 8 event types with run_on filtering, body_template for custom webhook payloads, standardized event envelope, and emit_event() helper. Fully backward compatible.

Closes #187
---
 CHANGELOG.md                  |  17 ++++
 README.md                     |   2 +-
 app.py                        |   2 +-
 library_manager/hooks.py      | 179 ++++++++++++++++++++++++++++++----
 templates/hooks_settings.html |  65 ++++++++++++
 templates/settings.html       |  47 ++++++++-
 6 files changed, 291 insertions(+), 21 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bf3146c..11752dc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,23 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.139] - 2026-03-21
+
+### Added
+
+- **Issue #187: Expanded hook events with filtering and custom payloads** - Hooks now fire on 8
+  event types (`scan_started`, `scan_completed`, `book_discovered`, `rename_proposed`,
+  `rename_applied`, `rename_rejected`, `processing_failed`, `queue_empty`) instead of just
+  `fixed`. Each hook supports a `run_on` list for per-hook event filtering, so a single hook
+  can subscribe to only the events it cares about. New `body_template` field enables custom
+  webhook payloads with full template variable support (enables Discord/Slack/Home Assistant
+  without code). All events use a standardized envelope format with `event`, `timestamp`,
+  `app_version`, and event-specific `payload`. New `emit_event()` helper centralizes event
+  dispatching across the codebase. Fully backward compatible — existing hooks default to
+  `run_on: ["rename_applied"]` and the legacy `"fixed"` event name is aliased automatically.
+
+---
+
 ## [0.9.0-beta.138] - 2026-03-21
 
 ### Fixed
diff --git a/README.md b/README.md
index a097120..657b570 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.138-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.139-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
diff --git a/app.py b/app.py
index 63c6d58..ac46e43 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.138"
+APP_VERSION = "0.9.0-beta.139"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
diff --git a/library_manager/hooks.py b/library_manager/hooks.py
index e041095..bcfd2ef 100644
--- a/library_manager/hooks.py
+++ b/library_manager/hooks.py
@@ -1,8 +1,11 @@
-"""Post-processing hooks for Library Manager (Issue #166).
+"""Post-processing hooks for Library Manager (Issue #166, #187).
 
 Runs external commands or webhooks after a book is successfully renamed.
 Use cases: m4binder conversion, ABS library scan, Discord notifications, etc.
 
+Issue #187: Extended event system with run_on filtering, body_template support,
+standardized event envelope, and emit_event() helper.
+
 This is a self-contained Flask Blueprint - routes, logic, DB schema all in one file.
 """
 import json
@@ -13,7 +16,7 @@
 import subprocess
 import threading
 import time
-from datetime import datetime
+from datetime import datetime, timezone
 
 import requests as http_requests
 from flask import Blueprint, request, jsonify
@@ -41,6 +44,23 @@
     'old_author', 'old_title',
 ]
 
+# Supported hook events with descriptions (Issue #187)
+HOOK_EVENTS = {
+    'scan_started': 'Library scan has started',
+    'scan_completed': 'Library scan finished',
+    'book_discovered': 'A new book was found during scanning',
+    'rename_proposed': 'A rename fix has been proposed for review',
+    'rename_applied': 'A rename was successfully applied (formerly "fixed")',
+    'rename_rejected': 'A proposed rename was rejected by the user',
+    'processing_failed': 'Book processing encountered an error',
+    'queue_empty': 'The processing queue is empty',
+}
+
+# Backward compat: map old event name to new
+_EVENT_ALIASES = {
+    'fixed': 'rename_applied',
+}
+
 
 # ============== DATABASE ==============
 
@@ -115,7 +135,14 @@ def build_hook_context(book_id, history_id, old_path, new_path,
                        new_author='', new_title='',
                        new_narrator='', new_series='', new_series_num='',
                        new_year='', media_type='audiobook', event='fixed'):
-    """Build the template variable dict from fix data. All values stringified."""
+    """Build the template variable dict from fix data. All values stringified.
+
+    Note: the ``event`` param still accepts 'fixed' for backward compat; it is
+    normalised to 'rename_applied' internally.
+    """
+    # Normalize legacy event name
+    event = _EVENT_ALIASES.get(event, event)
+
     ctx = {
         'book_id': str(book_id),
         'history_id': str(history_id),
@@ -131,7 +158,7 @@ def build_hook_context(book_id, history_id, old_path, new_path,
         'new_year': str(new_year or ''),
         'media_type': str(media_type or 'audiobook'),
         'event': str(event),
-        'timestamp': datetime.now().isoformat(),
+        'timestamp': datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'),
     }
     # Convenience aliases
     ctx['author'] = ctx['new_author']
@@ -143,6 +170,43 @@ def build_hook_context(book_id, history_id, old_path, new_path,
     return ctx
 
 
+def build_event_context(event_name, payload=None):
+    """Build a generic event context dict for non-rename events.
+
+    For events like scan_started or queue_empty that don't have book-specific data.
+    All values are stringified for template substitution.
+    """
+    event_name = _EVENT_ALIASES.get(event_name, event_name)
+    ctx = {
+        'event': str(event_name),
+        'timestamp': datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'),
+    }
+    # Merge any event-specific payload fields
+    if payload:
+        for key, value in payload.items():
+            ctx[key] = str(value) if value is not None else ''
+    return ctx
+
+
+def _build_webhook_envelope(event_name, payload_dict, app_version=None):
+    """Wrap a payload dict in the standardized event envelope (Issue #187).
+
+    Envelope format:
+        {
+            "event": "rename_applied",
+            "timestamp": "2026-03-21T14:32:00Z",
+            "app_version": "0.9.0-beta.133",
+            "payload": { ... }
+        }
+    """
+    return {
+        'event': event_name,
+        'timestamp': datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'),
+        'app_version': app_version or '',
+        'payload': payload_dict,
+    }
+
+
 def substitute_template(template, context, shell_escape=False):
     """Replace {{variable}} placeholders in a template string.
 
@@ -226,9 +290,29 @@ def execute_command_hook(hook, context):
 
 # ============== WEBHOOK EXECUTION ==============
 
-def execute_webhook_hook(hook, context, secrets=None):
+def _resolve_body_template(body_template, context):
+    """Recursively substitute {{variable}} placeholders in a body_template structure.
+
+    body_template can be a dict, list, or string. All string values get substitution.
+    Returns a new structure with substituted values.
+    """
+    if isinstance(body_template, str):
+        return substitute_template(body_template, context)
+    elif isinstance(body_template, dict):
+        return {k: _resolve_body_template(v, context) for k, v in body_template.items()}
+    elif isinstance(body_template, list):
+        return [_resolve_body_template(item, context) for item in body_template]
+    else:
+        return body_template
+
+
+def execute_webhook_hook(hook, context, secrets=None, app_version=None):
     """Send an HTTP webhook with context as JSON payload.
 
+    If ``body_template`` is set on the hook, it is used as the payload with
+    template variables substituted.  Otherwise, the context is wrapped in the
+    standardised event envelope (Issue #187).
+
     Returns dict with: success, exit_code (HTTP status), stdout (response body), error, duration_ms
     """
     url = hook.get('url', '')
@@ -247,13 +331,20 @@ def execute_webhook_hook(hook, context, secrets=None):
     # Substitute template variables in URL (no shell escaping needed for URLs)
     resolved_url = substitute_template(url, context)
 
-    # Build payload
-    payload = {k: v for k, v in context.items()}
+    # Build payload - body_template takes priority (Issue #187)
+    body_template = hook.get('body_template')
+    if body_template:
+        payload = _resolve_body_template(body_template, context)
+    else:
+        # Wrap in standardized envelope
+        event_name = context.get('event', 'rename_applied')
+        payload = _build_webhook_envelope(event_name, context, app_version)
 
     start = time.monotonic()
     try:
         if method == 'GET':
-            resp = http_requests.get(resolved_url, params=payload, headers=headers, timeout=timeout)
+            resp = http_requests.get(resolved_url, params=payload if isinstance(payload, dict) else {},
+                                     headers=headers, timeout=timeout)
         else:
             headers.setdefault('Content-Type', 'application/json')
             resp = http_requests.post(resolved_url, json=payload, headers=headers, timeout=timeout)
@@ -283,7 +374,19 @@ def execute_webhook_hook(hook, context, secrets=None):
 
 # ============== ORCHESTRATOR ==============
 
-def run_hooks(context, config, get_db, secrets=None):
+def _normalize_run_on(run_on_list):
+    """Normalize a hook's run_on list, mapping legacy event names.
+
+    Handles backward compat: 'fixed' -> 'rename_applied'.
+    Returns a set for fast membership testing.
+    """
+    normalized = set()
+    for event in run_on_list:
+        normalized.add(_EVENT_ALIASES.get(event, event))
+    return normalized
+
+
+def run_hooks(context, config, get_db, secrets=None, app_version=None):
     """Main orchestrator - called from apply_fix() after a successful rename.
 
     Iterates enabled hooks, routes to correct executor, handles sync/async.
@@ -293,7 +396,9 @@ def run_hooks(context, config, get_db, secrets=None):
     if not hooks:
         return
 
-    event = context.get('event', 'fixed')
+    event = context.get('event', 'rename_applied')
+    # Normalize legacy event name in context
+    event = _EVENT_ALIASES.get(event, event)
     history_id = context.get('history_id')
     book_id = context.get('book_id')
 
@@ -304,8 +409,9 @@ def run_hooks(context, config, get_db, secrets=None):
         if not hook.get('enabled', True):
             continue
 
-        # Check if this hook should run for this event type
-        run_on = hook.get('run_on', ['fixed'])
+        # Check if this hook should run for this event type (Issue #187)
+        # Default to ['rename_applied'] for backward compat (covers old 'fixed' hooks)
+        run_on = _normalize_run_on(hook.get('run_on', ['rename_applied']))
         if event not in run_on:
             continue
 
@@ -313,18 +419,18 @@ def run_hooks(context, config, get_db, secrets=None):
         hook_type = hook.get('type', 'command')
         mode = hook.get('mode', 'sync')
 
-        logger.info(f"[HOOKS] Running {hook_type} hook: {hook_name} (mode={mode})")
+        logger.info(f"[HOOKS] Running {hook_type} hook: {hook_name} (mode={mode}, event={event})")
 
         if mode == 'async':
             # Fire and forget in a background thread
             t = threading.Thread(
                 target=_run_single_hook,
-                args=(hook, hook_name, hook_type, context, secrets, get_db, history_id, book_id),
+                args=(hook, hook_name, hook_type, context, secrets, get_db, history_id, book_id, app_version),
                 daemon=True,
             )
             t.start()
         else:
-            result = _run_single_hook(hook, hook_name, hook_type, context, secrets, get_db, history_id, book_id)
+            result = _run_single_hook(hook, hook_name, hook_type, context, secrets, get_db, history_id, book_id, app_version)
             if result and not result.get('success'):
                 any_error = True
                 if not first_error:
@@ -348,11 +454,11 @@ def run_hooks(context, config, get_db, secrets=None):
             logger.error(f"[HOOKS] Failed to update history hook status: {e}")
 
 
-def _run_single_hook(hook, hook_name, hook_type, context, secrets, get_db, history_id, book_id):
+def _run_single_hook(hook, hook_name, hook_type, context, secrets, get_db, history_id, book_id, app_version=None):
     """Execute a single hook and log the result."""
     try:
         if hook_type == 'webhook':
-            result = execute_webhook_hook(hook, context, secrets)
+            result = execute_webhook_hook(hook, context, secrets, app_version=app_version)
         else:
             result = execute_command_hook(hook, context)
 
@@ -371,6 +477,37 @@ def _run_single_hook(hook, hook_name, hook_type, context, secrets, get_db, histo
         return error_result
 
 
+# ============== EVENT EMISSION (Issue #187) ==============
+
+def emit_event(event_name, context_dict, config, get_db, secrets=None, app_version=None):
+    """Emit a hook event, filtering hooks by their run_on list.
+
+    This is the primary entry point for triggering hooks from anywhere in the app.
+    It normalizes the event name, ensures the context has the event field set,
+    and delegates to run_hooks() which handles filtering, sync/async, and logging.
+
+    Args:
+        event_name: One of the HOOK_EVENTS keys (e.g. 'rename_applied', 'scan_started')
+        context_dict: Dict of template variables for this event.
+                      For rename events, use build_hook_context().
+                      For other events, use build_event_context() or pass a plain dict.
+        config: The app config dict (must contain 'post_processing_hooks')
+        get_db: Database connection factory
+        secrets: Optional secrets dict for webhook auth
+        app_version: Optional app version string for webhook envelope
+    """
+    # Normalize legacy event names
+    event_name = _EVENT_ALIASES.get(event_name, event_name)
+
+    # Ensure context has the event and timestamp fields
+    context_dict['event'] = event_name
+    if 'timestamp' not in context_dict:
+        context_dict['timestamp'] = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
+
+    logger.debug(f"[HOOKS] Emitting event: {event_name}")
+    run_hooks(context_dict, config, get_db, secrets=secrets, app_version=app_version)
+
+
 # ============== TEST HOOK ==============
 
 def test_hook(hook, secrets=None):
@@ -393,7 +530,7 @@ def test_hook(hook, secrets=None):
         new_series_num='',
         new_year='1977',
         media_type='audiobook',
-        event='fixed',
+        event='rename_applied',
     )
 
     hook_type = hook.get('type', 'command')
@@ -463,6 +600,12 @@ def api_hooks_log_clear():
         return jsonify({'success': False, 'error': str(e)}), 500
 
 
+@hooks_bp.route('/api/hooks/events')
+def api_hooks_events():
+    """Return available hook events with descriptions (Issue #187)."""
+    return jsonify({'events': HOOK_EVENTS})
+
+
 @hooks_bp.route('/api/hooks/save', methods=['POST'])
 def api_hooks_save():
     """Save hooks array to config.json."""
diff --git a/templates/hooks_settings.html b/templates/hooks_settings.html
index a10bc89..6bb1b15 100644
--- a/templates/hooks_settings.html
+++ b/templates/hooks_settings.html
@@ -171,6 +171,71 @@ <h5 class="modal-title" id="hookEditModalTitle"><i class="bi bi-terminal"></i> A
                         <input type="text" class="form-control bg-dark text-light font-monospace" id="hook-headers"
                                placeholder='{"Authorization": "Bearer {{webhook_secret}}"}'>
                     </div>
+                    <div class="mb-3">
+                        <label class="form-label">Body Template <small class="text-muted">(JSON, optional - overrides default payload)</small></label>
+                        <textarea class="form-control bg-dark text-light font-monospace" id="hook-body-template" rows="4"
+                                  placeholder='{"embeds": [{"title": "Book: {{title}}", "description": "Author: {{author}}"}]}'></textarea>
+                        <small class="text-muted">Custom JSON payload with <code>{{"{{"}}variable{{"}}"}}</code> placeholders. Leave empty for the default event envelope.</small>
+                    </div>
+                </div>
+
+                <!-- Event Triggers (Issue #187) -->
+                <div class="mb-3">
+                    <label class="form-label">Trigger on Events</label>
+                    <div class="row" id="hook-events-checkboxes">
+                        <div class="col-md-6">
+                            <div class="form-check">
+                                <input class="form-check-input" type="checkbox" value="rename_applied" id="hook-evt-rename_applied" checked>
+                                <label class="form-check-label" for="hook-evt-rename_applied">
+                                    <strong>rename_applied</strong> <small class="text-muted">- Rename was applied</small>
+                                </label>
+                            </div>
+                            <div class="form-check">
+                                <input class="form-check-input" type="checkbox" value="rename_proposed" id="hook-evt-rename_proposed">
+                                <label class="form-check-label" for="hook-evt-rename_proposed">
+                                    <strong>rename_proposed</strong> <small class="text-muted">- Rename proposed for review</small>
+                                </label>
+                            </div>
+                            <div class="form-check">
+                                <input class="form-check-input" type="checkbox" value="rename_rejected" id="hook-evt-rename_rejected">
+                                <label class="form-check-label" for="hook-evt-rename_rejected">
+                                    <strong>rename_rejected</strong> <small class="text-muted">- Rename rejected by user</small>
+                                </label>
+                            </div>
+                            <div class="form-check">
+                                <input class="form-check-input" type="checkbox" value="book_discovered" id="hook-evt-book_discovered">
+                                <label class="form-check-label" for="hook-evt-book_discovered">
+                                    <strong>book_discovered</strong> <small class="text-muted">- New book found during scan</small>
+                                </label>
+                            </div>
+                        </div>
+                        <div class="col-md-6">
+                            <div class="form-check">
+                                <input class="form-check-input" type="checkbox" value="scan_started" id="hook-evt-scan_started">
+                                <label class="form-check-label" for="hook-evt-scan_started">
+                                    <strong>scan_started</strong> <small class="text-muted">- Library scan started</small>
+                                </label>
+                            </div>
+                            <div class="form-check">
+                                <input class="form-check-input" type="checkbox" value="scan_completed" id="hook-evt-scan_completed">
+                                <label class="form-check-label" for="hook-evt-scan_completed">
+                                    <strong>scan_completed</strong> <small class="text-muted">- Library scan finished</small>
+                                </label>
+                            </div>
+                            <div class="form-check">
+                                <input class="form-check-input" type="checkbox" value="processing_failed" id="hook-evt-processing_failed">
+                                <label class="form-check-label" for="hook-evt-processing_failed">
+                                    <strong>processing_failed</strong> <small class="text-muted">- Processing error</small>
+                                </label>
+                            </div>
+                            <div class="form-check">
+                                <input class="form-check-input" type="checkbox" value="queue_empty" id="hook-evt-queue_empty">
+                                <label class="form-check-label" for="hook-evt-queue_empty">
+                                    <strong>queue_empty</strong> <small class="text-muted">- Processing queue is empty</small>
+                                </label>
+                            </div>
+                        </div>
+                    </div>
                 </div>
 
                 <div class="row">
diff --git a/templates/settings.html b/templates/settings.html
index 1684516..05eb73f 100644
--- a/templates/settings.html
+++ b/templates/settings.html
@@ -2370,6 +2370,7 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
                 <strong>${escapeHtml(hook.name)}</strong>
                 <span class="badge ${hook.type === 'webhook' ? 'bg-info' : 'bg-secondary'} ms-1" style="font-size: 0.65rem;">${hook.type}</span>
                 <span class="badge ${hook.mode === 'async' ? 'bg-warning text-dark' : 'bg-dark'} ms-1" style="font-size: 0.65rem;">${hook.mode || 'sync'}</span>
+                ${(hook.run_on || ['rename_applied']).map(e => '<span class="badge bg-dark border border-secondary ms-1" style="font-size: 0.6rem;">' + escapeHtml(e) + '</span>').join('')}
                 <br><small class="text-muted font-monospace">${escapeHtml(hook.type === 'webhook' ? (hook.url || '').substring(0, 60) : (hook.command || '').substring(0, 60))}${(hook.type === 'webhook' ? hook.url : hook.command || '').length > 60 ? '...' : ''}</small>
             </div>
             <div class="btn-group btn-group-sm ms-2">
@@ -2405,10 +2406,13 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
     document.getElementById('hook-url').value = '';
     document.getElementById('hook-method').value = 'POST';
     document.getElementById('hook-headers').value = '';
+    document.getElementById('hook-body-template').value = '';
     document.getElementById('hook-timeout').value = '300';
     document.getElementById('hook-mode').value = 'sync';
     document.getElementById('hook-on-error').value = 'log';
     document.getElementById('hook-test-result').style.display = 'none';
+    // Reset event checkboxes - default to rename_applied only
+    setEventCheckboxes(['rename_applied']);
     toggleHookTypeFields();
     new bootstrap.Modal(document.getElementById('hookEditModal')).show();
 }
@@ -2423,10 +2427,13 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
     document.getElementById('hook-url').value = hook.url || '';
     document.getElementById('hook-method').value = hook.method || 'POST';
     document.getElementById('hook-headers').value = hook.headers ? JSON.stringify(hook.headers) : '';
+    document.getElementById('hook-body-template').value = hook.body_template ? JSON.stringify(hook.body_template, null, 2) : '';
     document.getElementById('hook-timeout').value = hook.timeout || 300;
     document.getElementById('hook-mode').value = hook.mode || 'sync';
     document.getElementById('hook-on-error').value = hook.on_error || 'log';
     document.getElementById('hook-test-result').style.display = 'none';
+    // Load event checkboxes (default to rename_applied for backward compat)
+    setEventCheckboxes(hook.run_on || ['rename_applied']);
     toggleHookTypeFields();
     new bootstrap.Modal(document.getElementById('hookEditModal')).show();
 }
@@ -2448,6 +2455,28 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
     saveHooksToServer();
 }
 
+// Event checkbox helpers (Issue #187)
+const HOOK_EVENT_NAMES = ['scan_started', 'scan_completed', 'book_discovered', 'rename_proposed',
+                          'rename_applied', 'rename_rejected', 'processing_failed', 'queue_empty'];
+
+function setEventCheckboxes(selectedEvents) {
+    // Normalize legacy 'fixed' -> 'rename_applied'
+    const normalized = selectedEvents.map(e => e === 'fixed' ? 'rename_applied' : e);
+    HOOK_EVENT_NAMES.forEach(evt => {
+        const cb = document.getElementById('hook-evt-' + evt);
+        if (cb) cb.checked = normalized.includes(evt);
+    });
+}
+
+function getSelectedEvents() {
+    const selected = [];
+    HOOK_EVENT_NAMES.forEach(evt => {
+        const cb = document.getElementById('hook-evt-' + evt);
+        if (cb && cb.checked) selected.push(evt);
+    });
+    return selected;
+}
+
 function toggleHookTypeFields() {
     const type = document.getElementById('hook-type').value;
     document.getElementById('hook-command-fields').style.display = type === 'command' ? 'block' : 'none';
@@ -2471,6 +2500,21 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
         catch (e) { alert('Invalid JSON in headers field'); return; }
     }
 
+    // Parse body_template if provided
+    let bodyTemplateObj = undefined;
+    const bodyTemplateStr = document.getElementById('hook-body-template').value.trim();
+    if (bodyTemplateStr && type === 'webhook') {
+        try { bodyTemplateObj = JSON.parse(bodyTemplateStr); }
+        catch (e) { alert('Invalid JSON in body template field'); return; }
+    }
+
+    // Collect selected events
+    const selectedEvents = getSelectedEvents();
+    if (selectedEvents.length === 0) {
+        alert('Please select at least one event to trigger this hook');
+        return;
+    }
+
     const hook = {
         name: name,
         type: type,
@@ -2478,11 +2522,12 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
         url: type === 'webhook' ? document.getElementById('hook-url').value.trim() : undefined,
         method: type === 'webhook' ? document.getElementById('hook-method').value : undefined,
         headers: type === 'webhook' ? headersObj : undefined,
+        body_template: bodyTemplateObj,
         timeout: parseInt(document.getElementById('hook-timeout').value) || 300,
         mode: document.getElementById('hook-mode').value,
         on_error: document.getElementById('hook-on-error').value,
         enabled: true,
-        run_on: ['fixed']
+        run_on: selectedEvents
     };
 
     // Validate

From 3a63024c8f2521499cdb297ee8423b460168824c Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Sat, 21 Mar 2026 10:53:58 -0500
Subject: [PATCH 10/20] feat: Add Custom Layer Builder wizard UI (#186) (#195)

Adds Plugins tab to Settings with 4-step wizard for no-code custom API layers. Includes plugins Blueprint with CRUD + test endpoints, wizard modal (info, API config, response mapping, test & save), and full integration with existing patterns.

Closes #186
---
 CHANGELOG.md                    |  16 ++
 README.md                       |   7 +-
 app.py                          |   4 +-
 library_manager/plugins.py      | 270 ++++++++++++++++++++++++
 templates/plugins_settings.html | 352 +++++++++++++++++++++++++++++++
 templates/settings.html         | 360 ++++++++++++++++++++++++++++++++
 6 files changed, 1007 insertions(+), 2 deletions(-)
 create mode 100644 library_manager/plugins.py
 create mode 100644 templates/plugins_settings.html

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 11752dc..4e2f0d0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,22 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.140] - 2026-03-21
+
+### Added
+
+- **Issue #186: Custom Layer Builder wizard UI** - New "Plugins" tab in settings with a 4-step
+  wizard for creating custom HTTP API metadata sources without writing code. Step 1 collects name
+  and description, step 2 configures URL template with variable placeholders, HTTP method, timeout,
+  and authentication (none/bearer/API key header/basic auth), step 3 maps API response fields to
+  book profile fields via JSONPath expressions with a configurable confidence weight slider, and
+  step 4 provides live API testing with sample book data showing HTTP status, response time, mapped
+  field values, and raw response. Full CRUD via `/api/plugins/` endpoints: list, save, delete, and
+  toggle layers. Each custom layer is stored in `config.json` under `custom_layers` and feeds into
+  the existing `CustomApiLayer` processing pipeline.
+
+---
+
 ## [0.9.0-beta.139] - 2026-03-21
 
 ### Added
diff --git a/README.md b/README.md
index 657b570..3c09e4f 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.139-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.140-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
@@ -16,6 +16,11 @@
 
 ## Recent Changes (stable)
 
+> **beta.140** - **Feature: Custom Layer Builder** (Issue #186)
+> - **Plugins tab** - New settings tab with 4-step wizard to add custom HTTP API metadata sources
+> - **No-code API integration** - Configure URL templates, authentication, JSONPath response mapping, and confidence weights
+> - **Live testing** - Test API calls with sample book data before saving, with mapped field preview
+
 > **beta.134** - **Hotfix: Settings Page Crash** (Issue #173)
 > - Jinja2 template recursion bug in hooks_settings.html caused blank settings page for all users on beta.133
 
diff --git a/app.py b/app.py
index ac46e43..6e33ecd 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.139"
+APP_VERSION = "0.9.0-beta.140"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
@@ -121,6 +121,7 @@
 from library_manager.file_validation import validate_audio_file, check_ffmpeg_available
 from library_manager.hints import get_all_hints
 from library_manager.hooks import hooks_bp, run_hooks, build_hook_context
+from library_manager.plugins import plugins_bp
 
 # Try to import P2P cache (optional - gracefully degrades if not available)
 try:
@@ -561,6 +562,7 @@ def extract_narrator_from_folder(folder_path):
 app = Flask(__name__)
 app.secret_key = 'library-manager-secret-key-2024'
 app.register_blueprint(hooks_bp)
+app.register_blueprint(plugins_bp)
 
 # ============== INTERNATIONALIZATION (i18n) ==============
 # Flask-Babel for UI translations - book metadata (author/title) is NOT translated
diff --git a/library_manager/plugins.py b/library_manager/plugins.py
new file mode 100644
index 0000000..bf963ad
--- /dev/null
+++ b/library_manager/plugins.py
@@ -0,0 +1,270 @@
+"""Custom Layer Builder API routes (Issue #186).
+
+Flask Blueprint providing CRUD and test endpoints for custom HTTP API layers.
+These layers let users add their own book metadata sources without writing code.
+"""
+import json
+import logging
+import re
+import time
+
+import requests as http_requests
+from flask import Blueprint, request, jsonify
+
+from library_manager.config import CONFIG_PATH, load_config, load_secrets
+from library_manager.pipeline.custom_layer import (
+    extract_jsonpath, _build_auth_headers, _substitute_url_template
+)
+
+logger = logging.getLogger(__name__)
+
+plugins_bp = Blueprint('plugins', __name__)
+
+# Keys that must never be written to config.json
+SECRETS_KEYS = ['openrouter_api_key', 'gemini_api_key', 'google_books_api_key',
+                'abs_api_token', 'bookdb_api_key', 'webhook_secret']
+
+
+def _slugify(name):
+    """Convert a layer name to a safe layer_id slug."""
+    slug = name.lower().strip()
+    slug = re.sub(r'[^a-z0-9]+', '_', slug)
+    slug = slug.strip('_')
+    return slug or 'custom_layer'
+
+
+def _save_config_safe(config):
+    """Save config.json, stripping secret keys."""
+    config_only = {k: v for k, v in config.items() if k not in SECRETS_KEYS}
+    with open(CONFIG_PATH, 'w') as f:
+        json.dump(config_only, f, indent=2)
+
+
+@plugins_bp.route('/api/plugins/layers')
+def api_plugins_list():
+    """List all custom layers from config."""
+    config = load_config()
+    layers = config.get('custom_layers', [])
+    return jsonify({'success': True, 'layers': layers})
+
+
+@plugins_bp.route('/api/plugins/save-layer', methods=['POST'])
+def api_plugins_save():
+    """Save or update a custom layer in config.json."""
+    data = request.get_json()
+    if not data:
+        return jsonify({'success': False, 'error': 'No data provided'}), 400
+
+    layer = data.get('layer', {})
+    if not layer.get('layer_name'):
+        return jsonify({'success': False, 'error': 'Layer name is required'}), 400
+    if not layer.get('url_template'):
+        return jsonify({'success': False, 'error': 'URL template is required'}), 400
+
+    # Auto-generate layer_id from name if not provided
+    if not layer.get('layer_id'):
+        layer['layer_id'] = _slugify(layer['layer_name'])
+
+    # Ensure defaults
+    layer.setdefault('enabled', True)
+    layer.setdefault('method', 'GET')
+    layer.setdefault('timeout', 10)
+    layer.setdefault('source_weight', 55)
+    layer.setdefault('order', 35)
+    layer.setdefault('on_error', 'skip')
+    layer.setdefault('response_mapping', {})
+    layer.setdefault('request_fields', ['title', 'author'])
+    layer.setdefault('circuit_breaker', {'max_failures': 3, 'cooldown': 300})
+
+    # Clamp timeout
+    layer['timeout'] = max(1, min(int(layer.get('timeout', 10)), 60))
+    layer['source_weight'] = max(0, min(int(layer.get('source_weight', 55)), 100))
+
+    try:
+        config = load_config()
+        custom_layers = config.get('custom_layers', [])
+
+        # Check if updating existing layer
+        existing_idx = None
+        for i, existing in enumerate(custom_layers):
+            if existing.get('layer_id') == layer['layer_id']:
+                existing_idx = i
+                break
+
+        if existing_idx is not None:
+            custom_layers[existing_idx] = layer
+        else:
+            custom_layers.append(layer)
+
+        config['custom_layers'] = custom_layers
+        _save_config_safe(config)
+
+        return jsonify({'success': True, 'layer_id': layer['layer_id']})
+    except Exception as e:
+        logger.error(f"[PLUGINS] Failed to save layer: {e}")
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@plugins_bp.route('/api/plugins/layer/<layer_id>', methods=['DELETE'])
+def api_plugins_delete(layer_id):
+    """Remove a custom layer from config.json."""
+    try:
+        config = load_config()
+        custom_layers = config.get('custom_layers', [])
+        original_count = len(custom_layers)
+
+        custom_layers = [l for l in custom_layers if l.get('layer_id') != layer_id]
+
+        if len(custom_layers) == original_count:
+            return jsonify({'success': False, 'error': f'Layer "{layer_id}" not found'}), 404
+
+        config['custom_layers'] = custom_layers
+        _save_config_safe(config)
+
+        return jsonify({'success': True})
+    except Exception as e:
+        logger.error(f"[PLUGINS] Failed to delete layer {layer_id}: {e}")
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@plugins_bp.route('/api/plugins/toggle-layer', methods=['POST'])
+def api_plugins_toggle():
+    """Toggle a custom layer's enabled state."""
+    data = request.get_json()
+    if not data or not data.get('layer_id'):
+        return jsonify({'success': False, 'error': 'No layer_id provided'}), 400
+
+    layer_id = data['layer_id']
+    enabled = bool(data.get('enabled', True))
+
+    try:
+        config = load_config()
+        custom_layers = config.get('custom_layers', [])
+
+        found = False
+        for layer in custom_layers:
+            if layer.get('layer_id') == layer_id:
+                layer['enabled'] = enabled
+                found = True
+                break
+
+        if not found:
+            return jsonify({'success': False, 'error': f'Layer "{layer_id}" not found'}), 404
+
+        config['custom_layers'] = custom_layers
+        _save_config_safe(config)
+
+        return jsonify({'success': True, 'enabled': enabled})
+    except Exception as e:
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@plugins_bp.route('/api/plugins/test-layer', methods=['POST'])
+def api_plugins_test():
+    """Test a custom layer config by making the actual API call.
+
+    Receives a layer config and test book data (title/author),
+    makes the HTTP request server-side, and returns the results.
+    """
+    data = request.get_json()
+    if not data:
+        return jsonify({'success': False, 'error': 'No data provided'}), 400
+
+    layer = data.get('layer', {})
+    test_title = data.get('test_title', 'The Final Empire')
+    test_author = data.get('test_author', 'Brandon Sanderson')
+
+    url_template = layer.get('url_template', '')
+    if not url_template:
+        return jsonify({'success': False, 'error': 'No URL template provided'}), 400
+
+    method = layer.get('method', 'GET').upper()
+    timeout = max(1, min(int(layer.get('timeout', 10)), 60))
+
+    # Build template context from test data
+    context = {
+        'title': test_title,
+        'author': test_author,
+        'narrator': '',
+        'path': '/test/path',
+        'isbn': '',
+    }
+
+    # Substitute URL template
+    url = _substitute_url_template(url_template, context)
+
+    # Build auth headers
+    secrets = load_secrets()
+    auth_config = layer.get('auth')
+    auth_headers = _build_auth_headers(auth_config, secrets)
+
+    headers = dict(auth_headers)
+    headers['Accept'] = 'application/json'
+
+    result = {
+        'success': True,
+        'url': url,
+        'method': method,
+        'status_code': None,
+        'response_time_ms': None,
+        'mapped_fields': {},
+        'raw_response': None,
+        'error': None,
+    }
+
+    start = time.monotonic()
+    try:
+        if method == 'POST':
+            body = {f: context.get(f, '') for f in layer.get('request_fields', ['title', 'author'])}
+            headers.setdefault('Content-Type', 'application/json')
+            resp = http_requests.post(url, json=body, headers=headers, timeout=timeout)
+        else:
+            resp = http_requests.get(url, headers=headers, timeout=timeout)
+
+        duration_ms = int((time.monotonic() - start) * 1000)
+        result['status_code'] = resp.status_code
+        result['response_time_ms'] = duration_ms
+
+        # Try to parse JSON response
+        try:
+            resp_data = resp.json()
+            # Truncate raw response for display (max 2000 chars)
+            raw_str = json.dumps(resp_data, indent=2)
+            result['raw_response'] = raw_str[:2000] + ('...' if len(raw_str) > 2000 else '')
+
+            # Apply response mappings
+            response_mapping = layer.get('response_mapping', {})
+            for field_name, jsonpath in response_mapping.items():
+                value = extract_jsonpath(resp_data, jsonpath)
+                if value is not None:
+                    result['mapped_fields'][field_name] = str(value)
+                else:
+                    result['mapped_fields'][field_name] = None
+
+        except (ValueError, json.JSONDecodeError):
+            result['raw_response'] = resp.text[:500]
+            result['error'] = 'Response is not valid JSON'
+
+        if not (200 <= resp.status_code < 300):
+            result['success'] = False
+            result['error'] = f'HTTP {resp.status_code}'
+
+    except http_requests.Timeout:
+        duration_ms = int((time.monotonic() - start) * 1000)
+        result['success'] = False
+        result['response_time_ms'] = duration_ms
+        result['error'] = f'Request timed out after {timeout}s'
+
+    except http_requests.ConnectionError as e:
+        duration_ms = int((time.monotonic() - start) * 1000)
+        result['success'] = False
+        result['response_time_ms'] = duration_ms
+        result['error'] = f'Connection error: {str(e)[:200]}'
+
+    except Exception as e:
+        duration_ms = int((time.monotonic() - start) * 1000)
+        result['success'] = False
+        result['response_time_ms'] = duration_ms
+        result['error'] = f'Error: {str(e)[:200]}'
+
+    return jsonify(result)
diff --git a/templates/plugins_settings.html b/templates/plugins_settings.html
new file mode 100644
index 0000000..aa60168
--- /dev/null
+++ b/templates/plugins_settings.html
@@ -0,0 +1,352 @@
+<!-- Custom Layer Builder Tab (Issue #186) -->
+{# Included in settings.html via include 'plugins_settings.html' #}
+
+<div class="row">
+    <div class="col-lg-8">
+        <!-- Layer List -->
+        <div class="card mb-3">
+            <div class="card-header py-2 d-flex justify-content-between align-items-center">
+                <span>
+                    <i class="bi bi-plug"></i> Custom API Sources
+                    <span class="hint-icon" aria-label="Help">?<span class="hint-text">Add your own book metadata APIs as processing layers. Each source queries an HTTP endpoint and maps the response into the book profile system.</span></span>
+                </span>
+                <button type="button" class="btn btn-sm btn-outline-primary py-0" onclick="openPluginWizard()">
+                    <i class="bi bi-plus-lg"></i> Add Custom API Source
+                </button>
+            </div>
+            <div class="card-body p-0">
+                <div id="plugins-list">
+                    <!-- Populated by JS -->
+                </div>
+                <div id="plugins-empty" class="text-center text-muted py-4" style="display: none;">
+                    <i class="bi bi-plug" style="font-size: 2rem;"></i>
+                    <p class="mt-2 mb-0">No custom API sources configured</p>
+                    <small>Add a custom layer to query your own book metadata APIs</small>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <div class="col-lg-4">
+        <!-- How It Works -->
+        <div class="card mb-3">
+            <div class="card-header py-2">
+                <i class="bi bi-lightbulb"></i> How Custom Layers Work
+            </div>
+            <div class="card-body py-2" style="font-size: 0.8rem;">
+                <p class="mb-2">Custom API sources plug into the processing pipeline. When a book needs metadata, your API is queried alongside built-in sources.</p>
+                <ol class="mb-2 ps-3">
+                    <li>Your API receives book title &amp; author</li>
+                    <li>Response fields are extracted via JSONPath</li>
+                    <li>Extracted data feeds into the book profile with your chosen confidence weight</li>
+                </ol>
+                <hr class="my-2">
+                <p class="mb-1"><strong>URL Template Variables:</strong></p>
+                <code>{{"{{"}}title{{"}}"}}</code>,
+                <code>{{"{{"}}author{{"}}"}}</code>,
+                <code>{{"{{"}}narrator{{"}}"}}</code>,
+                <code>{{"{{"}}isbn{{"}}"}}</code>,
+                <code>{{"{{"}}path{{"}}"}}</code>
+                <hr class="my-2">
+                <p class="mb-1"><strong>JSONPath Examples:</strong></p>
+                <code>$.title</code> - top-level field<br>
+                <code>$.results[0].author</code> - first array item<br>
+                <code>$.data.book.name</code> - nested field
+            </div>
+        </div>
+
+        <!-- Source Weight Guide -->
+        <div class="card mb-3">
+            <div class="card-header py-2">
+                <i class="bi bi-speedometer2"></i> Confidence Weights
+            </div>
+            <div class="card-body py-2" style="font-size: 0.8rem;">
+                <p class="mb-2 text-muted">Higher weight = more trusted. Multiple sources agreeing boosts confidence.</p>
+                <table class="table table-sm table-dark mb-0" style="font-size: 0.75rem;">
+                    <thead><tr><th>Source</th><th>Weight</th></tr></thead>
+                    <tbody>
+                        <tr><td>Audio analysis</td><td>85</td></tr>
+                        <tr><td>ID3 tags</td><td>80</td></tr>
+                        <tr><td>JSON metadata</td><td>75</td></tr>
+                        <tr><td>BookDB / Audnexus</td><td>65</td></tr>
+                        <tr><td>AI verification</td><td>60</td></tr>
+                        <tr class="text-info"><td><strong>Custom layers</strong></td><td><strong>55 (default)</strong></td></tr>
+                        <tr><td>Path parsing</td><td>40</td></tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    </div>
+</div>
+
+<!-- Plugin Wizard Modal (4-step) -->
+<div class="modal fade" id="pluginWizardModal" tabindex="-1" data-bs-backdrop="static">
+    <div class="modal-dialog modal-lg">
+        <div class="modal-content bg-dark">
+            <div class="modal-header">
+                <h5 class="modal-title" id="pluginWizardTitle"><i class="bi bi-plug"></i> Add Custom API Source</h5>
+                <button type="button" class="btn-close btn-close-white" data-bs-dismiss="modal"></button>
+            </div>
+            <div class="modal-body">
+                <!-- Step indicators -->
+                <div class="d-flex justify-content-center mb-4">
+                    <div class="d-flex align-items-center">
+                        <span class="badge rounded-pill bg-primary plugin-step-badge" id="plugin-step-badge-1">1</span>
+                        <small class="ms-1 me-3 text-muted">Info</small>
+                        <i class="bi bi-chevron-right text-muted me-3"></i>
+                        <span class="badge rounded-pill bg-secondary plugin-step-badge" id="plugin-step-badge-2">2</span>
+                        <small class="ms-1 me-3 text-muted">API</small>
+                        <i class="bi bi-chevron-right text-muted me-3"></i>
+                        <span class="badge rounded-pill bg-secondary plugin-step-badge" id="plugin-step-badge-3">3</span>
+                        <small class="ms-1 me-3 text-muted">Mapping</small>
+                        <i class="bi bi-chevron-right text-muted me-3"></i>
+                        <span class="badge rounded-pill bg-secondary plugin-step-badge" id="plugin-step-badge-4">4</span>
+                        <small class="ms-1 text-muted">Test</small>
+                    </div>
+                </div>
+
+                <input type="hidden" id="plugin-edit-id" value="">
+
+                <!-- Step 1: Basic Info -->
+                <div id="plugin-step-1">
+                    <h6 class="mb-3"><i class="bi bi-info-circle"></i> Basic Information</h6>
+                    <div class="mb-3">
+                        <label class="form-label">Name <span class="text-danger">*</span></label>
+                        <input type="text" class="form-control bg-dark text-light" id="plugin-name"
+                               placeholder="e.g. My Book Database">
+                        <small class="text-muted">A short name for this API source</small>
+                    </div>
+                    <div class="mb-3">
+                        <label class="form-label">Description</label>
+                        <input type="text" class="form-control bg-dark text-light" id="plugin-description"
+                               placeholder="e.g. Custom metadata lookup using my private book API">
+                        <small class="text-muted">Optional description for your reference</small>
+                    </div>
+                </div>
+
+                <!-- Step 2: API Configuration -->
+                <div id="plugin-step-2" class="d-none">
+                    <h6 class="mb-3"><i class="bi bi-globe"></i> API Configuration</h6>
+                    <div class="mb-3">
+                        <label class="form-label">URL Template <span class="text-danger">*</span></label>
+                        <input type="text" class="form-control bg-dark text-light font-monospace" id="plugin-url"
+                               placeholder="https://api.example.com/search?title={{title}}&author={{author}}">
+                        <small class="text-muted">Use <code>{{"{{"}}title{{"}}"}}</code>, <code>{{"{{"}}author{{"}}"}}</code>, <code>{{"{{"}}narrator{{"}}"}}</code>, <code>{{"{{"}}isbn{{"}}"}}</code> as placeholders. Values are URL-encoded automatically.</small>
+                    </div>
+
+                    <div class="row">
+                        <div class="col-md-6">
+                            <div class="mb-3">
+                                <label class="form-label">HTTP Method</label>
+                                <select class="form-select bg-dark text-light" id="plugin-method">
+                                    <option value="GET">GET</option>
+                                    <option value="POST">POST</option>
+                                </select>
+                            </div>
+                        </div>
+                        <div class="col-md-6">
+                            <div class="mb-3">
+                                <label class="form-label">Timeout (seconds)</label>
+                                <input type="number" class="form-control bg-dark text-light" id="plugin-timeout"
+                                       value="10" min="1" max="60">
+                            </div>
+                        </div>
+                    </div>
+
+                    <div class="mb-3">
+                        <label class="form-label">Authentication</label>
+                        <select class="form-select bg-dark text-light" id="plugin-auth-type" onchange="togglePluginAuthFields()">
+                            <option value="none">None</option>
+                            <option value="bearer">Bearer Token</option>
+                            <option value="api_key_header">API Key Header</option>
+                            <option value="basic">Basic Auth</option>
+                        </select>
+                    </div>
+
+                    <!-- Bearer fields -->
+                    <div id="plugin-auth-bearer" class="d-none">
+                        <div class="mb-3">
+                            <label class="form-label">Secret Key Name</label>
+                            <input type="text" class="form-control bg-dark text-light" id="plugin-bearer-secret"
+                                   placeholder="e.g. my_bookdb_key">
+                            <small class="text-muted">Key name in <code>secrets.json</code> that holds the token</small>
+                        </div>
+                    </div>
+
+                    <!-- API Key Header fields -->
+                    <div id="plugin-auth-apikey" class="d-none">
+                        <div class="row">
+                            <div class="col-md-6">
+                                <div class="mb-3">
+                                    <label class="form-label">Header Name</label>
+                                    <input type="text" class="form-control bg-dark text-light" id="plugin-apikey-header"
+                                           placeholder="X-API-Key" value="X-API-Key">
+                                </div>
+                            </div>
+                            <div class="col-md-6">
+                                <div class="mb-3">
+                                    <label class="form-label">Secret Key Name</label>
+                                    <input type="text" class="form-control bg-dark text-light" id="plugin-apikey-secret"
+                                           placeholder="e.g. my_api_key">
+                                    <small class="text-muted">Key name in <code>secrets.json</code></small>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+
+                    <!-- Basic Auth fields -->
+                    <div id="plugin-auth-basic" class="d-none">
+                        <div class="row">
+                            <div class="col-md-6">
+                                <div class="mb-3">
+                                    <label class="form-label">Username</label>
+                                    <input type="text" class="form-control bg-dark text-light" id="plugin-basic-user"
+                                           placeholder="username">
+                                </div>
+                            </div>
+                            <div class="col-md-6">
+                                <div class="mb-3">
+                                    <label class="form-label">Password Secret Key</label>
+                                    <input type="text" class="form-control bg-dark text-light" id="plugin-basic-secret"
+                                           placeholder="e.g. my_api_password">
+                                    <small class="text-muted">Key name in <code>secrets.json</code></small>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Step 3: Response Mapping -->
+                <div id="plugin-step-3" class="d-none">
+                    <h6 class="mb-3"><i class="bi bi-diagram-3"></i> Response Mapping</h6>
+                    <p class="text-muted small mb-3">Map API response fields to book profile fields using JSONPath expressions.</p>
+
+                    <div class="table-responsive">
+                        <table class="table table-sm table-dark mb-3">
+                            <thead>
+                                <tr>
+                                    <th style="width: 130px;">Field</th>
+                                    <th>JSONPath Expression</th>
+                                </tr>
+                            </thead>
+                            <tbody>
+                                <tr>
+                                    <td><i class="bi bi-book"></i> Title</td>
+                                    <td><input type="text" class="form-control form-control-sm bg-dark text-light font-monospace" id="plugin-map-title" placeholder="$.results[0].title"></td>
+                                </tr>
+                                <tr>
+                                    <td><i class="bi bi-person"></i> Author</td>
+                                    <td><input type="text" class="form-control form-control-sm bg-dark text-light font-monospace" id="plugin-map-author" placeholder="$.results[0].author"></td>
+                                </tr>
+                                <tr>
+                                    <td><i class="bi bi-mic"></i> Narrator</td>
+                                    <td><input type="text" class="form-control form-control-sm bg-dark text-light font-monospace" id="plugin-map-narrator" placeholder="$.results[0].narrator"></td>
+                                </tr>
+                                <tr>
+                                    <td><i class="bi bi-collection"></i> Series</td>
+                                    <td><input type="text" class="form-control form-control-sm bg-dark text-light font-monospace" id="plugin-map-series" placeholder="$.results[0].series"></td>
+                                </tr>
+                                <tr>
+                                    <td><i class="bi bi-hash"></i> Series #</td>
+                                    <td><input type="text" class="form-control form-control-sm bg-dark text-light font-monospace" id="plugin-map-series_num" placeholder="$.results[0].series_number"></td>
+                                </tr>
+                                <tr>
+                                    <td><i class="bi bi-calendar"></i> Year</td>
+                                    <td><input type="text" class="form-control form-control-sm bg-dark text-light font-monospace" id="plugin-map-year" placeholder="$.results[0].year"></td>
+                                </tr>
+                            </tbody>
+                        </table>
+                    </div>
+
+                    <div class="mb-3">
+                        <label class="form-label">Confidence Weight: <span id="plugin-weight-display" class="text-info">55</span></label>
+                        <input type="range" class="form-range" id="plugin-weight" min="0" max="100" value="55"
+                               oninput="document.getElementById('plugin-weight-display').textContent = this.value">
+                        <div class="d-flex justify-content-between" style="font-size: 0.7rem;">
+                            <span class="text-muted">Low trust (0)</span>
+                            <span class="text-muted">Path level (40)</span>
+                            <span class="text-info">Default (55)</span>
+                            <span class="text-muted">BookDB level (65)</span>
+                            <span class="text-muted">High trust (100)</span>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Step 4: Test & Save -->
+                <div id="plugin-step-4" class="d-none">
+                    <h6 class="mb-3"><i class="bi bi-play-circle"></i> Test & Save</h6>
+                    <p class="text-muted small mb-3">Test your API configuration with sample book data before saving.</p>
+
+                    <div class="row mb-3">
+                        <div class="col-md-6">
+                            <label class="form-label">Test Title</label>
+                            <input type="text" class="form-control bg-dark text-light" id="plugin-test-title"
+                                   value="The Final Empire">
+                        </div>
+                        <div class="col-md-6">
+                            <label class="form-label">Test Author</label>
+                            <input type="text" class="form-control bg-dark text-light" id="plugin-test-author"
+                                   value="Brandon Sanderson">
+                        </div>
+                    </div>
+
+                    <button type="button" class="btn btn-outline-info btn-sm mb-3" onclick="testPluginLayer()" id="plugin-test-btn">
+                        <i class="bi bi-play-circle"></i> Test API
+                    </button>
+
+                    <!-- Test Results -->
+                    <div id="plugin-test-result" class="d-none">
+                        <div class="card bg-dark border-secondary">
+                            <div class="card-header py-1 d-flex justify-content-between align-items-center">
+                                <small><strong>Test Results</strong></small>
+                                <span id="plugin-test-status" class="badge bg-secondary">-</span>
+                            </div>
+                            <div class="card-body py-2">
+                                <div class="row mb-2" style="font-size: 0.8rem;">
+                                    <div class="col-4"><strong>Status:</strong> <span id="plugin-test-http-status">-</span></div>
+                                    <div class="col-4"><strong>Time:</strong> <span id="plugin-test-time">-</span></div>
+                                    <div class="col-4"><strong>URL:</strong> <span id="plugin-test-url" class="text-truncate d-inline-block" style="max-width: 200px;">-</span></div>
+                                </div>
+
+                                <!-- Mapped Fields -->
+                                <div id="plugin-test-mapped" class="mb-2 d-none">
+                                    <strong class="small">Mapped Fields:</strong>
+                                    <table class="table table-sm table-dark mb-0 mt-1" style="font-size: 0.75rem;">
+                                        <thead><tr><th>Field</th><th>Value</th></tr></thead>
+                                        <tbody id="plugin-test-mapped-body"></tbody>
+                                    </table>
+                                </div>
+
+                                <!-- Raw Response (collapsible) -->
+                                <div class="mt-2">
+                                    <a class="small text-muted" data-bs-toggle="collapse" href="#plugin-test-raw-collapse" role="button">
+                                        <i class="bi bi-code"></i> Show raw response
+                                    </a>
+                                    <div class="collapse mt-1" id="plugin-test-raw-collapse">
+                                        <pre id="plugin-test-raw" class="bg-dark border border-secondary p-2 rounded mb-0 text-light"
+                                             style="font-size: 0.7rem; max-height: 200px; overflow-y: auto; white-space: pre-wrap;"></pre>
+                                    </div>
+                                </div>
+
+                                <!-- Error -->
+                                <div id="plugin-test-error" class="text-danger small mt-2 d-none"></div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+            <div class="modal-footer">
+                <button type="button" class="btn btn-secondary" id="plugin-prev-btn" onclick="pluginWizardPrev()" style="display: none;">
+                    <i class="bi bi-chevron-left"></i> Back
+                </button>
+                <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button>
+                <button type="button" class="btn btn-primary" id="plugin-next-btn" onclick="pluginWizardNext()">
+                    Next <i class="bi bi-chevron-right"></i>
+                </button>
+                <button type="button" class="btn btn-success" id="plugin-save-btn" onclick="savePluginLayer()" style="display: none;">
+                    <i class="bi bi-check-lg"></i> Save Layer
+                </button>
+            </div>
+        </div>
+    </div>
+</div>
diff --git a/templates/settings.html b/templates/settings.html
index 05eb73f..d768b57 100644
--- a/templates/settings.html
+++ b/templates/settings.html
@@ -128,6 +128,11 @@ <h5 class="alert-heading"><i class="bi bi-lightbulb"></i> How It Works</h5>
                 <i class="bi bi-terminal"></i> Post-Processing
             </button>
         </li>
+        <li class="nav-item">
+            <button class="nav-link" data-bs-toggle="tab" data-bs-target="#tab-plugins" type="button">
+                <i class="bi bi-plug"></i> Plugins
+            </button>
+        </li>
     </ul>
 
     <!-- Tab Content -->
@@ -1596,6 +1601,11 @@ <h6 class="alert-heading"><i class="bi bi-exclamation-octagon"></i> Read Before
             {% include 'hooks_settings.html' %}
         </div>
 
+        <!-- ==================== PLUGINS TAB ==================== -->
+        <div class="tab-pane fade" id="tab-plugins">
+            {% include 'plugins_settings.html' %}
+        </div>
+
     </div>
 
     <!-- Save Button (sticky) -->
@@ -2796,5 +2806,355 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
         }
     });
 })();
+
+// ==================== CUSTOM LAYER PLUGINS (Issue #186) ====================
+
+let pluginsData = {{ config.custom_layers | default([], true) | tojson }};
+let pluginWizardStep = 1;
+
+function renderPluginsList() {
+    const list = document.getElementById('plugins-list');
+    const empty = document.getElementById('plugins-empty');
+    if (!pluginsData.length) {
+        list.innerHTML = '';
+        empty.style.display = 'block';
+        return;
+    }
+    empty.style.display = 'none';
+    list.innerHTML = pluginsData.map((layer, i) => `
+        <div class="d-flex align-items-center border-bottom border-secondary px-3 py-2">
+            <div class="form-check form-switch me-2 mb-0">
+                <input class="form-check-input" type="checkbox" ${layer.enabled !== false ? 'checked' : ''}
+                       onchange="togglePluginEnabled('${escapeHtml(layer.layer_id)}', this.checked)">
+            </div>
+            <div class="flex-grow-1">
+                <strong>${escapeHtml(layer.layer_name)}</strong>
+                <span class="badge bg-info ms-1" style="font-size: 0.65rem;">${escapeHtml(layer.method || 'GET')}</span>
+                <span class="badge bg-secondary ms-1" style="font-size: 0.65rem;">weight: ${layer.source_weight || 55}</span>
+                ${layer.description ? '<br><small class="text-muted">' + escapeHtml(layer.description) + '</small>' : ''}
+                <br><small class="text-muted font-monospace">${escapeHtml((layer.url_template || '').substring(0, 70))}${(layer.url_template || '').length > 70 ? '...' : ''}</small>
+            </div>
+            <div class="btn-group btn-group-sm ms-2">
+                <button class="btn btn-outline-secondary py-0" onclick="editPluginLayer(${i})" title="Edit"><i class="bi bi-pencil"></i></button>
+                <button class="btn btn-outline-danger py-0" onclick="deletePluginLayer('${escapeHtml(layer.layer_id)}', '${escapeHtml(layer.layer_name)}')" title="Remove"><i class="bi bi-trash"></i></button>
+            </div>
+        </div>
+    `).join('');
+}
+
+function togglePluginEnabled(layerId, enabled) {
+    fetch('/api/plugins/toggle-layer', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({layer_id: layerId, enabled: enabled})
+    }).then(r => r.json()).then(data => {
+        if (data.success) {
+            const layer = pluginsData.find(l => l.layer_id === layerId);
+            if (layer) layer.enabled = enabled;
+        } else {
+            console.error('Toggle failed:', data.error);
+        }
+    }).catch(err => console.error('Toggle error:', err));
+}
+
+function deletePluginLayer(layerId, layerName) {
+    if (!confirm('Remove custom layer "' + layerName + '"?')) return;
+    fetch('/api/plugins/layer/' + encodeURIComponent(layerId), {
+        method: 'DELETE'
+    }).then(r => r.json()).then(data => {
+        if (data.success) {
+            pluginsData = pluginsData.filter(l => l.layer_id !== layerId);
+            renderPluginsList();
+        } else {
+            alert('Failed to delete: ' + (data.error || 'Unknown error'));
+        }
+    }).catch(err => alert('Delete error: ' + err));
+}
+
+function openPluginWizard(editLayer) {
+    pluginWizardStep = 1;
+    document.getElementById('plugin-edit-id').value = '';
+    document.getElementById('plugin-name').value = '';
+    document.getElementById('plugin-description').value = '';
+    document.getElementById('plugin-url').value = '';
+    document.getElementById('plugin-method').value = 'GET';
+    document.getElementById('plugin-timeout').value = '10';
+    document.getElementById('plugin-auth-type').value = 'none';
+    document.getElementById('plugin-bearer-secret').value = '';
+    document.getElementById('plugin-apikey-header').value = 'X-API-Key';
+    document.getElementById('plugin-apikey-secret').value = '';
+    document.getElementById('plugin-basic-user').value = '';
+    document.getElementById('plugin-basic-secret').value = '';
+    document.getElementById('plugin-map-title').value = '';
+    document.getElementById('plugin-map-author').value = '';
+    document.getElementById('plugin-map-narrator').value = '';
+    document.getElementById('plugin-map-series').value = '';
+    document.getElementById('plugin-map-series_num').value = '';
+    document.getElementById('plugin-map-year').value = '';
+    document.getElementById('plugin-weight').value = '55';
+    document.getElementById('plugin-weight-display').textContent = '55';
+    document.getElementById('plugin-test-title').value = 'The Final Empire';
+    document.getElementById('plugin-test-author').value = 'Brandon Sanderson';
+    document.getElementById('plugin-test-result').classList.add('d-none');
+    document.getElementById('pluginWizardTitle').innerHTML = '<i class="bi bi-plug"></i> Add Custom API Source';
+
+    if (editLayer) {
+        document.getElementById('plugin-edit-id').value = editLayer.layer_id || '';
+        document.getElementById('plugin-name').value = editLayer.layer_name || '';
+        document.getElementById('plugin-description').value = editLayer.description || '';
+        document.getElementById('plugin-url').value = editLayer.url_template || '';
+        document.getElementById('plugin-method').value = editLayer.method || 'GET';
+        document.getElementById('plugin-timeout').value = editLayer.timeout || 10;
+        document.getElementById('plugin-weight').value = editLayer.source_weight || 55;
+        document.getElementById('plugin-weight-display').textContent = editLayer.source_weight || 55;
+        document.getElementById('pluginWizardTitle').innerHTML = '<i class="bi bi-pencil"></i> Edit Custom API Source';
+
+        // Auth
+        const auth = editLayer.auth || {};
+        const authType = auth.type || 'none';
+        document.getElementById('plugin-auth-type').value = authType;
+        if (authType === 'bearer') {
+            document.getElementById('plugin-bearer-secret').value = auth.token_secret_key || '';
+        } else if (authType === 'api_key_header') {
+            document.getElementById('plugin-apikey-header').value = auth.header_name || 'X-API-Key';
+            document.getElementById('plugin-apikey-secret').value = auth.token_secret_key || '';
+        } else if (authType === 'basic') {
+            document.getElementById('plugin-basic-user').value = auth.username || '';
+            document.getElementById('plugin-basic-secret').value = auth.token_secret_key || '';
+        }
+
+        // Response mapping
+        const mapping = editLayer.response_mapping || {};
+        document.getElementById('plugin-map-title').value = mapping.title || '';
+        document.getElementById('plugin-map-author').value = mapping.author || '';
+        document.getElementById('plugin-map-narrator').value = mapping.narrator || '';
+        document.getElementById('plugin-map-series').value = mapping.series || '';
+        document.getElementById('plugin-map-series_num').value = mapping.series_num || '';
+        document.getElementById('plugin-map-year').value = mapping.year || '';
+    }
+
+    togglePluginAuthFields();
+    updatePluginWizardUI();
+    new bootstrap.Modal(document.getElementById('pluginWizardModal')).show();
+}
+
+function editPluginLayer(index) {
+    openPluginWizard(pluginsData[index]);
+}
+
+function updatePluginWizardUI() {
+    // Show/hide steps
+    for (let i = 1; i <= 4; i++) {
+        const step = document.getElementById('plugin-step-' + i);
+        const badge = document.getElementById('plugin-step-badge-' + i);
+        if (i === pluginWizardStep) {
+            step.classList.remove('d-none');
+            badge.classList.remove('bg-secondary');
+            badge.classList.add('bg-primary');
+        } else {
+            step.classList.add('d-none');
+            if (i < pluginWizardStep) {
+                badge.classList.remove('bg-secondary');
+                badge.classList.add('bg-primary');
+            } else {
+                badge.classList.remove('bg-primary');
+                badge.classList.add('bg-secondary');
+            }
+        }
+    }
+    // Show/hide buttons
+    document.getElementById('plugin-prev-btn').style.display = pluginWizardStep > 1 ? '' : 'none';
+    document.getElementById('plugin-next-btn').style.display = pluginWizardStep < 4 ? '' : 'none';
+    document.getElementById('plugin-save-btn').style.display = pluginWizardStep === 4 ? '' : 'none';
+}
+
+function pluginWizardNext() {
+    // Validate current step
+    if (pluginWizardStep === 1) {
+        const name = document.getElementById('plugin-name').value.trim();
+        if (!name) { alert('Please enter a layer name'); return; }
+    }
+    if (pluginWizardStep === 2) {
+        const url = document.getElementById('plugin-url').value.trim();
+        if (!url) { alert('Please enter a URL template'); return; }
+    }
+    if (pluginWizardStep < 4) {
+        pluginWizardStep++;
+        updatePluginWizardUI();
+    }
+}
+
+function pluginWizardPrev() {
+    if (pluginWizardStep > 1) {
+        pluginWizardStep--;
+        updatePluginWizardUI();
+    }
+}
+
+function togglePluginAuthFields() {
+    const authType = document.getElementById('plugin-auth-type').value;
+    document.getElementById('plugin-auth-bearer').classList.toggle('d-none', authType !== 'bearer');
+    document.getElementById('plugin-auth-apikey').classList.toggle('d-none', authType !== 'api_key_header');
+    document.getElementById('plugin-auth-basic').classList.toggle('d-none', authType !== 'basic');
+}
+
+function buildPluginLayerConfig() {
+    const name = document.getElementById('plugin-name').value.trim();
+    const editId = document.getElementById('plugin-edit-id').value.trim();
+
+    const layer = {
+        layer_id: editId || '',
+        layer_name: name,
+        description: document.getElementById('plugin-description').value.trim(),
+        url_template: document.getElementById('plugin-url').value.trim(),
+        method: document.getElementById('plugin-method').value,
+        timeout: parseInt(document.getElementById('plugin-timeout').value) || 10,
+        source_weight: parseInt(document.getElementById('plugin-weight').value) || 55,
+        enabled: true,
+        order: 35,
+        on_error: 'skip',
+        request_fields: ['title', 'author'],
+        circuit_breaker: {max_failures: 3, cooldown: 300},
+    };
+
+    // Auth
+    const authType = document.getElementById('plugin-auth-type').value;
+    if (authType === 'none') {
+        layer.auth = {type: 'none'};
+    } else if (authType === 'bearer') {
+        layer.auth = {
+            type: 'bearer',
+            token_secret_key: document.getElementById('plugin-bearer-secret').value.trim()
+        };
+    } else if (authType === 'api_key_header') {
+        layer.auth = {
+            type: 'api_key_header',
+            header_name: document.getElementById('plugin-apikey-header').value.trim() || 'X-API-Key',
+            token_secret_key: document.getElementById('plugin-apikey-secret').value.trim()
+        };
+    } else if (authType === 'basic') {
+        layer.auth = {
+            type: 'basic',
+            username: document.getElementById('plugin-basic-user').value.trim(),
+            token_secret_key: document.getElementById('plugin-basic-secret').value.trim()
+        };
+    }
+
+    // Response mapping (only include non-empty fields)
+    const mapping = {};
+    const fields = ['title', 'author', 'narrator', 'series', 'series_num', 'year'];
+    fields.forEach(f => {
+        const val = document.getElementById('plugin-map-' + f).value.trim();
+        if (val) mapping[f] = val;
+    });
+    layer.response_mapping = mapping;
+
+    return layer;
+}
+
+function testPluginLayer() {
+    const layer = buildPluginLayerConfig();
+    const testTitle = document.getElementById('plugin-test-title').value.trim() || 'The Final Empire';
+    const testAuthor = document.getElementById('plugin-test-author').value.trim() || 'Brandon Sanderson';
+
+    const btn = document.getElementById('plugin-test-btn');
+    btn.disabled = true;
+    btn.innerHTML = '<i class="bi bi-hourglass-split"></i> Testing...';
+
+    const resultDiv = document.getElementById('plugin-test-result');
+    resultDiv.classList.remove('d-none');
+
+    fetch('/api/plugins/test-layer', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({layer: layer, test_title: testTitle, test_author: testAuthor})
+    }).then(r => r.json()).then(data => {
+        btn.disabled = false;
+        btn.innerHTML = '<i class="bi bi-play-circle"></i> Test API';
+
+        // Status badge
+        const statusBadge = document.getElementById('plugin-test-status');
+        if (data.success) {
+            statusBadge.textContent = 'SUCCESS';
+            statusBadge.className = 'badge bg-success';
+        } else {
+            statusBadge.textContent = 'FAILED';
+            statusBadge.className = 'badge bg-danger';
+        }
+
+        // HTTP status and time
+        document.getElementById('plugin-test-http-status').textContent = data.status_code || '-';
+        document.getElementById('plugin-test-time').textContent = data.response_time_ms ? data.response_time_ms + 'ms' : '-';
+        document.getElementById('plugin-test-url').textContent = data.url || '-';
+        document.getElementById('plugin-test-url').title = data.url || '';
+
+        // Mapped fields
+        const mappedDiv = document.getElementById('plugin-test-mapped');
+        const mappedBody = document.getElementById('plugin-test-mapped-body');
+        if (data.mapped_fields && Object.keys(data.mapped_fields).length > 0) {
+            mappedDiv.classList.remove('d-none');
+            mappedBody.innerHTML = Object.entries(data.mapped_fields).map(([field, value]) => {
+                const badge = value !== null
+                    ? '<span class="text-success">' + escapeHtml(String(value)) + '</span>'
+                    : '<span class="text-danger">null (path not found)</span>';
+                return `<tr><td>${escapeHtml(field)}</td><td>${badge}</td></tr>`;
+            }).join('');
+        } else {
+            mappedDiv.classList.add('d-none');
+        }
+
+        // Raw response
+        document.getElementById('plugin-test-raw').textContent = data.raw_response || '(no response body)';
+
+        // Error
+        const errorDiv = document.getElementById('plugin-test-error');
+        if (data.error) {
+            errorDiv.classList.remove('d-none');
+            errorDiv.textContent = data.error;
+        } else {
+            errorDiv.classList.add('d-none');
+        }
+
+    }).catch(err => {
+        btn.disabled = false;
+        btn.innerHTML = '<i class="bi bi-play-circle"></i> Test API';
+        alert('Test error: ' + err);
+    });
+}
+
+function savePluginLayer() {
+    const layer = buildPluginLayerConfig();
+
+    if (!layer.layer_name) { alert('Please enter a layer name'); return; }
+    if (!layer.url_template) { alert('Please enter a URL template'); return; }
+
+    fetch('/api/plugins/save-layer', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({layer: layer})
+    }).then(r => r.json()).then(data => {
+        if (data.success) {
+            // Refresh the list from server
+            fetch('/api/plugins/layers').then(r => r.json()).then(listData => {
+                if (listData.success) {
+                    pluginsData = listData.layers;
+                    renderPluginsList();
+                }
+            });
+            bootstrap.Modal.getInstance(document.getElementById('pluginWizardModal')).hide();
+        } else {
+            alert('Failed to save: ' + (data.error || 'Unknown error'));
+        }
+    }).catch(err => alert('Save error: ' + err));
+}
+
+// Load plugins on tab show
+document.querySelector('[data-bs-target="#tab-plugins"]')?.addEventListener('shown.bs.tab', function() {
+    renderPluginsList();
+});
+
+// Initial render
+if (pluginsData.length) renderPluginsList();
+else document.getElementById('plugins-empty') && (document.getElementById('plugins-empty').style.display = 'block');
 </script>
 {% endblock %}

From c246f37644a4db3f1f081ece9a9e9417214beb7f Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Sat, 21 Mar 2026 11:03:54 -0500
Subject: [PATCH 11/20] feat: Add Plugin Health Dashboard with auto-disable
 circuit breaker (#189) (#196)

Adds plugin health dashboard with metrics tracking, auto-disable circuit breaker (5 consecutive failures), health API endpoints, and UI with status cards and error logs.

Closes #189
---
 CHANGELOG.md                             |  25 ++
 README.md                                |   2 +-
 app.py                                   |   2 +-
 library_manager/database.py              |   4 +
 library_manager/pipeline/custom_layer.py |  27 ++
 library_manager/plugins.py               | 302 ++++++++++++++++++++++-
 templates/plugins_settings.html          |  30 +++
 templates/settings.html                  | 213 ++++++++++++++++
 8 files changed, 600 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4e2f0d0..252780f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,31 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.141] - 2026-03-21
+
+### Added
+
+- **Issue #189: Plugin Health Dashboard** - New health monitoring section in the Plugins tab
+  showing real-time status for each custom API source. Tracks success rate (last 50 runs),
+  average response time, items processed/resolved, and last run timestamp. Health cards use
+  color-coded status indicators (green=active, yellow=errored, red=auto-disabled). Expandable
+  error logs show the 5 most recent failures per plugin with timestamps. Full metric log modal
+  shows the last 20 execution entries with status, duration, and error details.
+
+- **Auto-disable circuit breaker** - Plugins are automatically disabled after 5 consecutive
+  failures to prevent repeated errors from slowing the pipeline. Auto-disabled plugins show
+  a red status badge and a "Re-enable" button that resets the failure counter and re-enables
+  the layer. Toast notification logged when a plugin is auto-disabled.
+
+- **Plugin metrics recording** - New `plugin_metrics` database table tracks every custom
+  layer execution with timestamp, success/failure, duration, error message, and item counts.
+  Metrics are recorded automatically after each `CustomApiLayer.run()` batch with minimal
+  overhead (single INSERT, no aggregation on write path). Three new API endpoints:
+  `GET /api/plugins/health` (aggregated stats), `GET /api/plugins/health/<id>/logs`
+  (last 20 entries), `POST /api/plugins/health/<id>/reset` (re-enable disabled plugin).
+
+---
+
 ## [0.9.0-beta.140] - 2026-03-21
 
 ### Added
diff --git a/README.md b/README.md
index 3c09e4f..974946a 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.140-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.141-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
diff --git a/app.py b/app.py
index 6e33ecd..fa6b844 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.140"
+APP_VERSION = "0.9.0-beta.141"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
diff --git a/library_manager/database.py b/library_manager/database.py
index d29b161..62d4df6 100644
--- a/library_manager/database.py
+++ b/library_manager/database.py
@@ -182,6 +182,10 @@ def init_db(db_path=None):
     from library_manager.hooks import init_hook_tables
     init_hook_tables(path)
 
+    # Initialize plugin metrics table (Issue #189)
+    from library_manager.plugins import init_plugin_metrics_table
+    init_plugin_metrics_table(path)
+
 
 def cleanup_garbage_entries(db_path=None):
     """Remove garbage entries from database on startup.
diff --git a/library_manager/pipeline/custom_layer.py b/library_manager/pipeline/custom_layer.py
index 4f295fd..2653739 100644
--- a/library_manager/pipeline/custom_layer.py
+++ b/library_manager/pipeline/custom_layer.py
@@ -337,6 +337,8 @@ def run(self, config: Dict, deps: Optional[Dict] = None) -> Tuple[int, int]:
         Matches the LayerAdapter interface: accepts config and deps,
         returns (processed_count, resolved_count).
 
+        Records metrics after each batch for the plugin health dashboard.
+
         Args:
             config: App configuration dict
             deps: Optional dependencies dict (unused, for interface compatibility)
@@ -369,6 +371,8 @@ def run(self, config: Dict, deps: Optional[Dict] = None) -> Tuple[int, int]:
 
         processed = 0
         resolved = 0
+        error_message = None
+        start_time = time.monotonic()
 
         for item in batch:
             try:
@@ -381,8 +385,31 @@ def run(self, config: Dict, deps: Optional[Dict] = None) -> Tuple[int, int]:
                 logger.error(f"{self.log_prefix} Exception processing item {item.get('book_id')}: {e}",
                              exc_info=True)
                 processed += 1
+                if not error_message:
+                    error_message = str(e)[:500]
+
+        duration_ms = int((time.monotonic() - start_time) * 1000)
+        success = error_message is None and processed > 0
 
         logger.info(f"{self.log_prefix} Processed {processed}, resolved {resolved}")
+
+        # Record metrics for health dashboard (Issue #189)
+        try:
+            from library_manager.plugins import record_plugin_metric
+            was_disabled = record_plugin_metric(
+                self.get_db, self.layer_id,
+                success=success,
+                duration_ms=duration_ms,
+                error_message=error_message,
+                items_processed=processed,
+                items_resolved=resolved
+            )
+            if was_disabled:
+                self.enabled = False
+                logger.warning(f"{self.log_prefix} Auto-disabled due to consecutive failures")
+        except Exception as e:
+            logger.debug(f"{self.log_prefix} Failed to record metric: {e}")
+
         return processed, resolved
 
     def _fetch_batch(self, config: Dict) -> List[Dict]:
diff --git a/library_manager/plugins.py b/library_manager/plugins.py
index bf963ad..e0b6b99 100644
--- a/library_manager/plugins.py
+++ b/library_manager/plugins.py
@@ -1,11 +1,12 @@
-"""Custom Layer Builder API routes (Issue #186).
+"""Custom Layer Builder API routes (Issue #186) + Plugin Health Dashboard (Issue #189).
 
-Flask Blueprint providing CRUD and test endpoints for custom HTTP API layers.
-These layers let users add their own book metadata sources without writing code.
+Flask Blueprint providing CRUD, test, and health monitoring endpoints for custom HTTP
+API layers. These layers let users add their own book metadata sources without writing code.
 """
 import json
 import logging
 import re
+import sqlite3
 import time
 
 import requests as http_requests
@@ -24,6 +25,9 @@
 SECRETS_KEYS = ['openrouter_api_key', 'gemini_api_key', 'google_books_api_key',
                 'abs_api_token', 'bookdb_api_key', 'webhook_secret']
 
+# Auto-disable threshold: consecutive failures before a plugin is auto-disabled
+AUTO_DISABLE_THRESHOLD = 5
+
 
 def _slugify(name):
     """Convert a layer name to a safe layer_id slug."""
@@ -40,6 +44,116 @@ def _save_config_safe(config):
         json.dump(config_only, f, indent=2)
 
 
+# ============== PLUGIN METRICS DATABASE ==============
+
+def init_plugin_metrics_table(db_path):
+    """Create plugin_metrics table. Called from database.py init_db()."""
+    conn = sqlite3.connect(db_path, timeout=30)
+    c = conn.cursor()
+
+    c.execute('''CREATE TABLE IF NOT EXISTS plugin_metrics (
+        id INTEGER PRIMARY KEY,
+        plugin_id TEXT NOT NULL,
+        timestamp REAL NOT NULL,
+        success INTEGER DEFAULT 0,
+        duration_ms INTEGER,
+        error_message TEXT,
+        items_processed INTEGER DEFAULT 0,
+        items_resolved INTEGER DEFAULT 0
+    )''')
+
+    c.execute('''CREATE INDEX IF NOT EXISTS idx_plugin_metrics_plugin
+                 ON plugin_metrics(plugin_id, timestamp)''')
+
+    conn.commit()
+    conn.close()
+
+
+def record_plugin_metric(get_db, plugin_id, success, duration_ms,
+                         error_message=None, items_processed=0, items_resolved=0):
+    """Record a single plugin execution metric.
+
+    Fast INSERT only - no aggregation on write path.
+    Also checks for consecutive failures and triggers auto-disable if needed.
+
+    Args:
+        get_db: Callable that returns a database connection
+        plugin_id: The custom layer's layer_id
+        success: Whether the run succeeded (bool)
+        duration_ms: Execution time in milliseconds
+        error_message: Error text if failed (truncated to 1000 chars)
+        items_processed: Number of items processed this run
+        items_resolved: Number of items resolved this run
+
+    Returns:
+        True if the plugin was auto-disabled due to consecutive failures
+    """
+    auto_disabled = False
+    try:
+        conn = get_db()
+        c = conn.cursor()
+        c.execute('''INSERT INTO plugin_metrics
+                     (plugin_id, timestamp, success, duration_ms, error_message,
+                      items_processed, items_resolved)
+                     VALUES (?, ?, ?, ?, ?, ?, ?)''',
+                  (plugin_id, time.time(), 1 if success else 0, duration_ms,
+                   (error_message or '')[:1000] if error_message else None,
+                   items_processed, items_resolved))
+        conn.commit()
+
+        # Check for consecutive failures if this run failed
+        if not success:
+            c.execute('''SELECT success FROM plugin_metrics
+                         WHERE plugin_id = ?
+                         ORDER BY timestamp DESC
+                         LIMIT ?''', (plugin_id, AUTO_DISABLE_THRESHOLD))
+            recent = c.fetchall()
+            if (len(recent) >= AUTO_DISABLE_THRESHOLD and
+                    all(row[0] == 0 for row in recent)):
+                # Auto-disable the plugin
+                auto_disabled = _auto_disable_plugin(plugin_id)
+
+        conn.close()
+    except Exception as e:
+        logger.error(f"[PLUGINS] Failed to record metric for {plugin_id}: {e}")
+
+    return auto_disabled
+
+
+def _auto_disable_plugin(plugin_id):
+    """Auto-disable a plugin after consecutive failures.
+
+    Sets auto_disabled: true in the layer config and saves to config.json.
+
+    Returns:
+        True if the plugin was disabled, False if not found or already disabled
+    """
+    try:
+        config = load_config()
+        custom_layers = config.get('custom_layers', [])
+
+        for layer in custom_layers:
+            if layer.get('layer_id') == plugin_id:
+                if layer.get('auto_disabled'):
+                    return False  # Already disabled
+                layer['auto_disabled'] = True
+                layer['enabled'] = False
+                config['custom_layers'] = custom_layers
+                _save_config_safe(config)
+                logger.warning(
+                    f"[PLUGINS] Auto-disabled plugin '{plugin_id}' after "
+                    f"{AUTO_DISABLE_THRESHOLD} consecutive failures"
+                )
+                return True
+
+        return False
+    except Exception as e:
+        logger.error(f"[PLUGINS] Failed to auto-disable {plugin_id}: {e}")
+        return False
+
+
+# ============== CRUD ROUTES ==============
+
 @plugins_bp.route('/api/plugins/layers')
 def api_plugins_list():
     """List all custom layers from config."""
@@ -268,3 +382,185 @@ def api_plugins_test():
         result['error'] = f'Error: {str(e)[:200]}'
 
     return jsonify(result)
+
+
+# ============== HEALTH DASHBOARD API (Issue #189) ==============
+
+@plugins_bp.route('/api/plugins/health')
+def api_plugins_health():
+    """Return aggregated health stats for all custom plugins.
+
+    For each plugin returns:
+    - success_rate (from last 50 runs)
+    - avg_duration_ms
+    - last_run timestamp
+    - total_processed, total_resolved
+    - status: active / errored / auto-disabled
+    - recent_errors (last 5 error messages)
+    """
+    from library_manager.database import get_db
+
+    config = load_config()
+    custom_layers = config.get('custom_layers', [])
+
+    if not custom_layers:
+        return jsonify({'success': True, 'plugins': []})
+
+    try:
+        conn = get_db()
+        c = conn.cursor()
+        plugins_health = []
+
+        for layer in custom_layers:
+            plugin_id = layer.get('layer_id', '')
+            if not plugin_id:
+                continue
+
+            # Get last 50 runs for success rate
+            c.execute('''SELECT success, duration_ms, timestamp, error_message,
+                                items_processed, items_resolved
+                         FROM plugin_metrics
+                         WHERE plugin_id = ?
+                         ORDER BY timestamp DESC
+                         LIMIT 50''', (plugin_id,))
+            recent_rows = c.fetchall()
+
+            if not recent_rows:
+                plugins_health.append({
+                    'plugin_id': plugin_id,
+                    'plugin_name': layer.get('layer_name', plugin_id),
+                    'enabled': layer.get('enabled', True),
+                    'auto_disabled': layer.get('auto_disabled', False),
+                    'status': 'no_data',
+                    'success_rate': None,
+                    'avg_duration_ms': None,
+                    'last_run': None,
+                    'total_processed': 0,
+                    'total_resolved': 0,
+                    'recent_errors': [],
+                })
+                continue
+
+            total_runs = len(recent_rows)
+            successes = sum(1 for r in recent_rows if r[0])
+            success_rate = round(successes / total_runs * 100, 1) if total_runs else 0
+
+            durations = [r[1] for r in recent_rows if r[1] is not None]
+            avg_duration = int(sum(durations) / len(durations)) if durations else 0
+
+            last_run = recent_rows[0][2] if recent_rows else None
+
+            total_processed = sum(r[4] or 0 for r in recent_rows)
+            total_resolved = sum(r[5] or 0 for r in recent_rows)
+
+            # Recent errors (last 5 non-null)
+            recent_errors = []
+            for r in recent_rows:
+                if r[3] and len(recent_errors) < 5:
+                    recent_errors.append({
+                        'message': r[3],
+                        'timestamp': r[2],
+                    })
+
+            # Determine status
+            auto_disabled = layer.get('auto_disabled', False)
+            enabled = layer.get('enabled', True)
+            if auto_disabled:
+                status = 'auto-disabled'
+            elif not enabled:
+                status = 'disabled'
+            elif success_rate < 50:
+                status = 'errored'
+            else:
+                status = 'active'
+
+            plugins_health.append({
+                'plugin_id': plugin_id,
+                'plugin_name': layer.get('layer_name', plugin_id),
+                'enabled': enabled,
+                'auto_disabled': auto_disabled,
+                'status': status,
+                'success_rate': success_rate,
+                'avg_duration_ms': avg_duration,
+                'last_run': last_run,
+                'total_processed': total_processed,
+                'total_resolved': total_resolved,
+                'recent_errors': recent_errors,
+            })
+
+        conn.close()
+        return jsonify({'success': True, 'plugins': plugins_health})
+
+    except Exception as e:
+        logger.error(f"[PLUGINS] Health check error: {e}")
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@plugins_bp.route('/api/plugins/health/<plugin_id>/logs')
+def api_plugins_health_logs(plugin_id):
+    """Return last 20 metric entries for a specific plugin."""
+    from library_manager.database import get_db
+
+    try:
+        conn = get_db()
+        c = conn.cursor()
+        c.execute('''SELECT id, plugin_id, timestamp, success, duration_ms,
+                            error_message, items_processed, items_resolved
+                     FROM plugin_metrics
+                     WHERE plugin_id = ?
+                     ORDER BY timestamp DESC
+                     LIMIT 20''', (plugin_id,))
+        rows = c.fetchall()
+        conn.close()
+
+        entries = []
+        for r in rows:
+            entries.append({
+                'id': r[0],
+                'plugin_id': r[1],
+                'timestamp': r[2],
+                'success': bool(r[3]),
+                'duration_ms': r[4],
+                'error_message': r[5],
+                'items_processed': r[6],
+                'items_resolved': r[7],
+            })
+
+        return jsonify({'success': True, 'entries': entries})
+
+    except Exception as e:
+        logger.error(f"[PLUGINS] Health logs error for {plugin_id}: {e}")
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@plugins_bp.route('/api/plugins/health/<plugin_id>/reset', methods=['POST'])
+def api_plugins_health_reset(plugin_id):
+    """Reset failure count and re-enable an auto-disabled plugin.
+
+    Clears the auto_disabled flag in config and removes recent failure
+    metrics so the consecutive failure counter starts fresh.
+    """
+    try:
+        config = load_config()
+        custom_layers = config.get('custom_layers', [])
+
+        found = False
+        for layer in custom_layers:
+            if layer.get('layer_id') == plugin_id:
+                layer['auto_disabled'] = False
+                layer['enabled'] = True
+                found = True
+                break
+
+        if not found:
+            return jsonify({'success': False, 'error': f'Plugin "{plugin_id}" not found'}), 404
+
+        config['custom_layers'] = custom_layers
+        _save_config_safe(config)
+
+        logger.info(f"[PLUGINS] Reset and re-enabled plugin '{plugin_id}'")
+        return jsonify({'success': True, 'enabled': True})
+
+    except Exception as e:
+        logger.error(f"[PLUGINS] Reset error for {plugin_id}: {e}")
+        return jsonify({'success': False, 'error': str(e)}), 500
diff --git a/templates/plugins_settings.html b/templates/plugins_settings.html
index aa60168..7bd4311 100644
--- a/templates/plugins_settings.html
+++ b/templates/plugins_settings.html
@@ -79,6 +79,36 @@
     </div>
 </div>
 
+<!-- Plugin Health Dashboard (Issue #189) -->
+<div class="row mt-3">
+    <div class="col-12">
+        <div class="card mb-3">
+            <div class="card-header py-2 d-flex justify-content-between align-items-center">
+                <span>
+                    <i class="bi bi-heart-pulse"></i> Plugin Health
+                    <span class="hint-icon" aria-label="Help">?<span class="hint-text">Monitor the health and performance of your custom API sources. Plugins are auto-disabled after 5 consecutive failures.</span></span>
+                </span>
+                <button type="button" class="btn btn-sm btn-outline-secondary py-0" onclick="loadPluginHealth()">
+                    <i class="bi bi-arrow-clockwise"></i> Refresh
+                </button>
+            </div>
+            <div class="card-body p-0">
+                <div id="plugin-health-cards">
+                    <!-- Populated by JS -->
+                </div>
+                <div id="plugin-health-empty" class="text-center text-muted py-4" style="display: none;">
+                    <i class="bi bi-heart-pulse" style="font-size: 1.5rem;"></i>
+                    <p class="mt-2 mb-0">No metrics yet</p>
+                    <small>Health data appears after custom layers process books</small>
+                </div>
+                <div id="plugin-health-loading" class="text-center text-muted py-3" style="display: none;">
+                    <i class="bi bi-hourglass-split"></i> Loading health data...
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+
 <!-- Plugin Wizard Modal (4-step) -->
 <div class="modal fade" id="pluginWizardModal" tabindex="-1" data-bs-backdrop="static">
     <div class="modal-dialog modal-lg">
diff --git a/templates/settings.html b/templates/settings.html
index d768b57..10d044c 100644
--- a/templates/settings.html
+++ b/templates/settings.html
@@ -3151,10 +3151,223 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
 // Load plugins on tab show
 document.querySelector('[data-bs-target="#tab-plugins"]')?.addEventListener('shown.bs.tab', function() {
     renderPluginsList();
+    loadPluginHealth();
 });
 
 // Initial render
 if (pluginsData.length) renderPluginsList();
 else document.getElementById('plugins-empty') && (document.getElementById('plugins-empty').style.display = 'block');
+
+// ==================== PLUGIN HEALTH DASHBOARD (Issue #189) ====================
+
+let pluginHealthData = [];
+
+function loadPluginHealth() {
+    const cards = document.getElementById('plugin-health-cards');
+    const empty = document.getElementById('plugin-health-empty');
+    const loading = document.getElementById('plugin-health-loading');
+    if (!cards) return;
+
+    loading.style.display = 'block';
+    empty.style.display = 'none';
+    cards.innerHTML = '';
+
+    fetch('/api/plugins/health').then(r => r.json()).then(data => {
+        loading.style.display = 'none';
+        if (!data.success) {
+            cards.innerHTML = '<div class="text-danger p-3">Error loading health data: ' + (data.error || 'Unknown') + '</div>';
+            return;
+        }
+
+        pluginHealthData = data.plugins || [];
+        if (!pluginHealthData.length) {
+            empty.style.display = 'block';
+            return;
+        }
+
+        // Check if all plugins have no data
+        const allNoData = pluginHealthData.every(p => p.status === 'no_data');
+        if (allNoData) {
+            empty.style.display = 'block';
+            return;
+        }
+
+        renderPluginHealthCards();
+    }).catch(err => {
+        loading.style.display = 'none';
+        cards.innerHTML = '<div class="text-danger p-3">Failed to load health data: ' + err + '</div>';
+    });
+}
+
+function renderPluginHealthCards() {
+    const cards = document.getElementById('plugin-health-cards');
+    cards.innerHTML = pluginHealthData.map(p => {
+        // Status dot color
+        let dotColor = 'secondary';
+        let statusLabel = 'No Data';
+        if (p.status === 'active') { dotColor = 'success'; statusLabel = 'Active'; }
+        else if (p.status === 'errored') { dotColor = 'warning'; statusLabel = 'Errored'; }
+        else if (p.status === 'auto-disabled') { dotColor = 'danger'; statusLabel = 'Auto-Disabled'; }
+        else if (p.status === 'disabled') { dotColor = 'secondary'; statusLabel = 'Disabled'; }
+        else if (p.status === 'no_data') { dotColor = 'secondary'; statusLabel = 'No Data'; }
+
+        const successRate = p.success_rate !== null ? p.success_rate + '%' : '-';
+        const avgDuration = p.avg_duration_ms !== null ? p.avg_duration_ms + 'ms' : '-';
+        const lastRun = p.last_run ? new Date(p.last_run * 1000).toLocaleString() : 'Never';
+        const errorCount = (p.recent_errors || []).length;
+
+        let reEnableBtn = '';
+        if (p.auto_disabled) {
+            reEnableBtn = `<button class="btn btn-sm btn-outline-success py-0 ms-2" onclick="resetPluginHealth('${escapeHtml(p.plugin_id)}')">
+                <i class="bi bi-arrow-counterclockwise"></i> Re-enable
+            </button>`;
+        }
+
+        // Build error log accordion
+        let errorLog = '';
+        if (errorCount > 0) {
+            const collapseId = 'plugin-errors-' + p.plugin_id.replace(/[^a-zA-Z0-9]/g, '_');
+            errorLog = `
+                <div class="mt-2">
+                    <a class="small text-muted" data-bs-toggle="collapse" href="#${collapseId}" role="button">
+                        <i class="bi bi-exclamation-triangle"></i> ${errorCount} recent error${errorCount > 1 ? 's' : ''}
+                    </a>
+                    <div class="collapse mt-1" id="${collapseId}">
+                        <div style="max-height: 150px; overflow-y: auto; font-size: 0.7rem;">
+                            ${p.recent_errors.map(e => `
+                                <div class="border-bottom border-secondary py-1 px-2">
+                                    <span class="text-muted">${new Date(e.timestamp * 1000).toLocaleString()}</span>
+                                    <br><span class="text-danger">${escapeHtml(e.message)}</span>
+                                </div>
+                            `).join('')}
+                        </div>
+                    </div>
+                </div>`;
+        }
+
+        // Logs link
+        const logsLink = p.status !== 'no_data'
+            ? `<a class="small text-muted ms-2" href="#" onclick="showPluginLogs('${escapeHtml(p.plugin_id)}', '${escapeHtml(p.plugin_name)}'); return false;">
+                 <i class="bi bi-list-ul"></i> Logs
+               </a>`
+            : '';
+
+        return `
+            <div class="d-flex align-items-start border-bottom border-secondary px-3 py-2">
+                <div class="me-2 mt-1">
+                    <span class="d-inline-block rounded-circle bg-${dotColor}" style="width: 10px; height: 10px;"></span>
+                </div>
+                <div class="flex-grow-1">
+                    <div class="d-flex align-items-center">
+                        <strong>${escapeHtml(p.plugin_name)}</strong>
+                        <span class="badge bg-${dotColor} ms-2" style="font-size: 0.65rem;">${statusLabel}</span>
+                        ${reEnableBtn}
+                        ${logsLink}
+                    </div>
+                    <div class="row mt-1" style="font-size: 0.75rem;">
+                        <div class="col-3">
+                            <span class="text-muted">Success:</span> <strong>${successRate}</strong>
+                        </div>
+                        <div class="col-3">
+                            <span class="text-muted">Avg Time:</span> <strong>${avgDuration}</strong>
+                        </div>
+                        <div class="col-3">
+                            <span class="text-muted">Processed:</span> <strong>${p.total_processed}</strong>
+                        </div>
+                        <div class="col-3">
+                            <span class="text-muted">Resolved:</span> <strong>${p.total_resolved}</strong>
+                        </div>
+                    </div>
+                    <div style="font-size: 0.7rem;" class="text-muted mt-1">
+                        Last run: ${lastRun}
+                    </div>
+                    ${errorLog}
+                </div>
+            </div>`;
+    }).join('');
+}
+
+function resetPluginHealth(pluginId) {
+    if (!confirm('Re-enable plugin "' + pluginId + '"? This resets the failure counter.')) return;
+    fetch('/api/plugins/health/' + encodeURIComponent(pluginId) + '/reset', {
+        method: 'POST'
+    }).then(r => r.json()).then(data => {
+        if (data.success) {
+            // Refresh both lists
+            fetch('/api/plugins/layers').then(r => r.json()).then(listData => {
+                if (listData.success) {
+                    pluginsData = listData.layers;
+                    renderPluginsList();
+                }
+            });
+            loadPluginHealth();
+        } else {
+            alert('Reset failed: ' + (data.error || 'Unknown error'));
+        }
+    }).catch(err => alert('Reset error: ' + err));
+}
+
+function showPluginLogs(pluginId, pluginName) {
+    fetch('/api/plugins/health/' + encodeURIComponent(pluginId) + '/logs')
+        .then(r => r.json())
+        .then(data => {
+            if (!data.success || !data.entries.length) {
+                alert('No log entries for ' + pluginName);
+                return;
+            }
+
+            // Build a simple modal with log entries
+            let existingModal = document.getElementById('pluginLogsModal');
+            if (existingModal) existingModal.remove();
+
+            const entries = data.entries;
+            const rows = entries.map(e => {
+                const ts = new Date(e.timestamp * 1000).toLocaleString();
+                const badge = e.success
+                    ? '<span class="badge bg-success">OK</span>'
+                    : '<span class="badge bg-danger">FAIL</span>';
+                const dur = e.duration_ms !== null ? e.duration_ms + 'ms' : '-';
+                const err = e.error_message ? '<br><small class="text-danger">' + escapeHtml(e.error_message) + '</small>' : '';
+                return `<tr>
+                    <td style="font-size: 0.75rem;">${ts}</td>
+                    <td>${badge}</td>
+                    <td style="font-size: 0.75rem;">${dur}</td>
+                    <td style="font-size: 0.75rem;">${e.items_processed || 0} / ${e.items_resolved || 0}</td>
+                    <td style="font-size: 0.75rem;">${err || '-'}</td>
+                </tr>`;
+            }).join('');
+
+            const modalHtml = `
+                <div class="modal fade" id="pluginLogsModal" tabindex="-1">
+                    <div class="modal-dialog modal-lg">
+                        <div class="modal-content bg-dark">
+                            <div class="modal-header py-2">
+                                <h6 class="modal-title"><i class="bi bi-list-ul"></i> Logs: ${escapeHtml(pluginName)}</h6>
+                                <button type="button" class="btn-close btn-close-white" data-bs-dismiss="modal"></button>
+                            </div>
+                            <div class="modal-body p-0">
+                                <div class="table-responsive">
+                                    <table class="table table-sm table-dark mb-0">
+                                        <thead><tr>
+                                            <th>Time</th><th>Status</th><th>Duration</th><th>Proc/Res</th><th>Error</th>
+                                        </tr></thead>
+                                        <tbody>${rows}</tbody>
+                                    </table>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>`;
+
+            document.body.insertAdjacentHTML('beforeend', modalHtml);
+            new bootstrap.Modal(document.getElementById('pluginLogsModal')).show();
+
+            // Clean up on close
+            document.getElementById('pluginLogsModal').addEventListener('hidden.bs.modal', function() {
+                this.remove();
+            });
+        })
+        .catch(err => alert('Error loading logs: ' + err));
+}
 </script>
 {% endblock %}

From 3c973c1df58f025ab2d9b71a87054d4171e82bfe Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Sat, 21 Mar 2026 11:14:52 -0500
Subject: [PATCH 12/20] feat: Add drop-in Python plugin system (#188) (#197)

Adds Python drop-in plugin system. Users drop plugin directories into /data/plugins/ with manifest.json and a BasePlugin subclass. Features: auto-discovery via importlib, PluginAdapter for pipeline compatibility, timeout enforcement, deep copy isolation, exception handling, metrics recording with auto-disable, and an example plugin template.

Closes #188
---
 CHANGELOG.md                          |  29 +
 README.md                             |   2 +-
 app.py                                |  15 +-
 library_manager/config.py             |   3 +
 library_manager/plugin_loader.py      | 775 ++++++++++++++++++++++++++
 test-env/example-plugin/layer.py      |  78 +++
 test-env/example-plugin/manifest.json |  16 +
 7 files changed, 916 insertions(+), 2 deletions(-)
 create mode 100644 library_manager/plugin_loader.py
 create mode 100644 test-env/example-plugin/layer.py
 create mode 100644 test-env/example-plugin/manifest.json

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 252780f..dde3b26 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,35 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.142] - 2026-03-21
+
+### Added
+
+- **Issue #188: Drop-in Python plugin system** - New plugin loader that discovers and loads
+  Python plugins from a configurable directory (`/data/plugins` for Docker). Plugins extend
+  a simple `BasePlugin` class with `setup()`, `can_process()`, `process()`, and `teardown()`
+  methods. The loader handles manifest validation, dynamic module importing via `importlib`,
+  exception isolation (bad plugins never crash the app), timeout enforcement via
+  `ThreadPoolExecutor`, and deep-copying book data before passing to plugins. Each plugin is
+  wrapped in a `PluginAdapter` that implements the `LayerAdapter` interface, making plugins
+  fully compatible with the modular pipeline orchestrator. Plugins are registered in the
+  `LayerRegistry` and tracked by the existing health dashboard with auto-disable circuit
+  breaker support.
+
+- **Plugin manifest system** - Each plugin requires a `manifest.json` with metadata (id,
+  name, version, description), entry point configuration, ordering, and dependency
+  declarations (required config keys and secrets). Manifests are strictly validated on
+  discovery -- invalid plugins are logged as warnings and skipped.
+
+- **Plugin configuration** - New `plugin_dir` config key (default: `/data/plugins`) and
+  `plugin_configs` dict for per-plugin configuration overrides. Plugin-specific secrets are
+  read from `secrets.json`.
+
+- **Example plugin** - Template plugin at `test-env/example-plugin/` demonstrating the
+  `BasePlugin` interface with manifest.json and a simple logging implementation.
+
+---
+
 ## [0.9.0-beta.141] - 2026-03-21
 
 ### Added
diff --git a/README.md b/README.md
index 974946a..4a1a3aa 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.141-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.142-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
diff --git a/app.py b/app.py
index fa6b844..b5e8b96 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.141"
+APP_VERSION = "0.9.0-beta.142"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
@@ -122,6 +122,7 @@
 from library_manager.hints import get_all_hints
 from library_manager.hooks import hooks_bp, run_hooks, build_hook_context
 from library_manager.plugins import plugins_bp
+from library_manager.plugin_loader import register_plugins, teardown_plugins
 
 # Try to import P2P cache (optional - gracefully degrades if not available)
 try:
@@ -12142,6 +12143,18 @@ def _setup_user_packages():
     init_db()
     cleanup_garbage_entries()  # Remove @eaDir, #recycle, etc. from database (Issue #88)
     cleanup_duplicate_history_entries()  # Remove duplicate history entries (Issue #79)
+
+    # Issue #188: Load drop-in Python plugins
+    try:
+        from library_manager.pipeline.registry import default_registry
+        _startup_config = load_config()
+        _loaded_plugins = register_plugins(default_registry, _startup_config, get_db)
+        if _loaded_plugins:
+            logger.info(f"[PLUGIN] {len(_loaded_plugins)} plugin(s) loaded and registered")
+    except Exception as e:
+        logger.error(f"[PLUGIN] Failed to load plugins: {e}")
+        _loaded_plugins = []
+
     start_worker()
     port = int(os.environ.get('PORT', 5757))
     app.run(host='0.0.0.0', port=port, debug=False)
diff --git a/library_manager/config.py b/library_manager/config.py
index 858c772..4abb3a8 100644
--- a/library_manager/config.py
+++ b/library_manager/config.py
@@ -142,6 +142,9 @@ def _detect_data_dir():
     "post_processing_hooks": [],
     # Custom HTTP API layers - user-defined external API processing layers (Issue #185)
     "custom_layers": [],
+    # Drop-in Python plugins (Issue #188)
+    "plugin_dir": "/data/plugins",             # Directory to scan for drop-in plugins (Docker: /data/plugins)
+    "plugin_configs": {},                      # Per-plugin config overrides: {"plugin-id": {"key": "value"}}
     # Issue #110: File validation - check audio files before processing
     "enable_file_validation": True,            # Validate audio files with ffprobe before queueing
     "min_audio_duration_seconds": 600,         # Minimum duration (seconds) to consider a valid audiobook (default: 10 min)
diff --git a/library_manager/plugin_loader.py b/library_manager/plugin_loader.py
new file mode 100644
index 0000000..c2c9858
--- /dev/null
+++ b/library_manager/plugin_loader.py
@@ -0,0 +1,775 @@
+"""Drop-in Python plugin system for Library Manager.
+
+Discovers, validates, and loads plugins from a configurable directory
+(default: /data/plugins for Docker). Plugins extend the processing
+pipeline with custom book identification logic.
+
+Plugin structure:
+    /data/plugins/
+      my_plugin/
+        manifest.json    # metadata, config schema
+        layer.py         # class extending BasePlugin
+
+See BasePlugin for the simplified interface plugins should implement.
+"""
+
+import copy
+import importlib.util
+import json
+import logging
+import sys
+import time
+import traceback
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeoutError
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from library_manager.config import load_secrets
+from library_manager.pipeline.layer_info import LayerInfo
+
+logger = logging.getLogger(__name__)
+
+LOG_PREFIX = "[PLUGIN]"
+
+# Manifest required fields
+REQUIRED_MANIFEST_FIELDS = ('id', 'name', 'entry_point')
+
+# Default timeout for plugin process() calls (seconds)
+DEFAULT_PLUGIN_TIMEOUT = 30
+
+# Default batch size for plugin processing
+DEFAULT_PLUGIN_BATCH_SIZE = 10
+
+
+# ============== BASE PLUGIN CLASS ==============
+
+class BasePlugin:
+    """Simple base class for drop-in plugins.
+
+    Plugins extend this class and implement process() at minimum.
+    The plugin loader wraps BasePlugin subclasses in a PluginAdapter
+    that makes them compatible with the pipeline's LayerAdapter interface.
+
+    Attributes:
+        name: Human-readable plugin name (set from manifest).
+        description: What this plugin does (set from manifest).
+        version: Plugin version string (set from manifest).
+    """
+
+    name = "unnamed"
+    description = ""
+    version = "0.0.1"
+
+    def setup(self, config: dict, secrets: dict):
+        """Called once on load. Store config, create sessions, etc.
+
+        Args:
+            config: Plugin-specific configuration from plugin_configs.
+            secrets: Full secrets dict from secrets.json.
+        """
+        pass
+
+    def can_process(self, book_data: dict) -> bool:
+        """Return True if this plugin should process this book.
+
+        Args:
+            book_data: Dict with book info (current_title, current_author,
+                       path, status, profile, etc.)
+
+        Returns:
+            True to process this book, False to skip.
+        """
+        return True
+
+    def process(self, book_data: dict) -> dict:
+        """Process a book. Return dict with metadata fields.
+
+        The returned dict can contain any of these keys:
+            title, author, narrator, series, series_num, year, language
+
+        Return empty dict or None to skip (no changes).
+
+        Args:
+            book_data: Deep copy of book info dict. Safe to modify.
+
+        Returns:
+            Dict of metadata fields, or None/empty dict to skip.
+        """
+        return {}
+
+    def teardown(self):
+        """Called on shutdown. Clean up resources."""
+        pass
+
+
+# ============== PLUGIN INFO ==============
+
+@dataclass
+class PluginInfo:
+    """Metadata about a discovered plugin.
+
+    Populated from manifest.json during discovery.
+    """
+    plugin_id: str
+    name: str
+    version: str
+    description: str
+    plugin_dir: Path
+    entry_point: str
+    class_name: str = ""
+    default_order: int = 35
+    plugin_type: str = "layer"
+    requires_config: List[str] = field(default_factory=list)
+    requires_secrets: List[str] = field(default_factory=list)
+    permissions: Dict[str, Any] = field(default_factory=dict)
+    manifest: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def entry_point_path(self) -> Path:
+        return self.plugin_dir / self.entry_point
+
+
+# ============== PLUGIN ADAPTER ==============
+
+class PluginAdapter:
+    """Wraps a BasePlugin instance into a LayerAdapter-compatible object.
+
+    Handles:
+    - Fetching batch items from the database
+    - Deep copying book data before passing to plugins
+    - Timeout enforcement via ThreadPoolExecutor
+    - Exception isolation (bad plugins never crash the app)
+    - Recording metrics via record_plugin_metric()
+    """
+
+    def __init__(self, plugin: BasePlugin, plugin_info: PluginInfo,
+                 get_db: Callable, timeout: int = DEFAULT_PLUGIN_TIMEOUT):
+        """Initialize the plugin adapter.
+
+        Args:
+            plugin: Instantiated BasePlugin subclass.
+            plugin_info: PluginInfo from manifest discovery.
+            get_db: Callable that returns a database connection.
+            timeout: Max seconds for a single process() call.
+        """
+        self.plugin = plugin
+        self.plugin_info = plugin_info
+        self.get_db = get_db
+        self.timeout = timeout
+        self.layer_id = f"plugin_{plugin_info.plugin_id}"
+        self.log_prefix = f"[PLUGIN:{plugin_info.plugin_id}]"
+        self.enabled = True
+
+    def run(self, config: Dict, deps: Optional[Dict] = None) -> Tuple[int, int]:
+        """Run one processing cycle for this plugin.
+
+        Matches the LayerAdapter interface: accepts config and deps,
+        returns (processed_count, resolved_count).
+
+        Args:
+            config: App configuration dict.
+            deps: Optional dependencies dict (unused, for interface compat).
+
+        Returns:
+            Tuple of (processed_count, resolved_count).
+        """
+        if not self.enabled:
+            logger.debug(f"{self.log_prefix} Plugin disabled, skipping")
+            return 0, 0
+
+        # Fetch batch from queue
+        batch = self._fetch_batch(config)
+        if not batch:
+            return 0, 0
+
+        logger.info(f"{self.log_prefix} Processing {len(batch)} items")
+
+        processed = 0
+        resolved = 0
+        error_message = None
+        start_time = time.monotonic()
+
+        for item in batch:
+            try:
+                result = self._process_item(item)
+                if result:
+                    if self._apply_result(item, result):
+                        resolved += 1
+                processed += 1
+            except Exception as e:
+                logger.error(
+                    f"{self.log_prefix} Exception processing item "
+                    f"{item.get('book_id')}: {e}", exc_info=True
+                )
+                processed += 1
+                if not error_message:
+                    error_message = str(e)[:500]
+
+        duration_ms = int((time.monotonic() - start_time) * 1000)
+        success = error_message is None and processed > 0
+
+        logger.info(
+            f"{self.log_prefix} Processed {processed}, resolved {resolved} "
+            f"({duration_ms}ms)"
+        )
+
+        # Record metrics for health dashboard
+        try:
+            from library_manager.plugins import record_plugin_metric
+            was_disabled = record_plugin_metric(
+                self.get_db, self.layer_id,
+                success=success,
+                duration_ms=duration_ms,
+                error_message=error_message,
+                items_processed=processed,
+                items_resolved=resolved,
+            )
+            if was_disabled:
+                self.enabled = False
+                logger.warning(
+                    f"{self.log_prefix} Auto-disabled due to consecutive failures"
+                )
+        except Exception as e:
+            logger.debug(f"{self.log_prefix} Failed to record metric: {e}")
+
+        return processed, resolved
+
+    def _fetch_batch(self, config: Dict) -> List[Dict]:
+        """Fetch items from the queue at this plugin's order position."""
+        batch_size = config.get('batch_size', DEFAULT_PLUGIN_BATCH_SIZE)
+
+        conn = self.get_db()
+        c = conn.cursor()
+
+        c.execute('''SELECT q.id as queue_id, q.book_id, q.reason,
+                            b.path, b.current_author, b.current_title,
+                            b.verification_layer, b.status, b.profile,
+                            b.confidence
+                     FROM queue q
+                     JOIN books b ON q.book_id = b.id
+                     WHERE b.verification_layer = ?
+                       AND b.status NOT IN ('verified', 'fixed', 'series_folder',
+                                            'multi_book_files', 'needs_attention')
+                       AND (b.user_locked IS NULL OR b.user_locked = 0)
+                     ORDER BY q.priority, q.added_at
+                     LIMIT ?''', (self.plugin_info.default_order, batch_size))
+
+        batch = [dict(row) for row in c.fetchall()]
+        conn.close()
+
+        return batch
+
+    def _process_item(self, item: Dict) -> Optional[Dict]:
+        """Process a single item through the plugin with timeout enforcement.
+
+        Deep copies book data before passing to the plugin. Runs the
+        plugin's process() method in a thread pool with a timeout.
+
+        Args:
+            item: Database row dict with book info.
+
+        Returns:
+            Dict of metadata fields from the plugin, or None on error/skip.
+        """
+        # Deep copy the item so plugins can't mutate our data
+        book_data = copy.deepcopy(item)
+
+        # Check if plugin wants to process this book
+        try:
+            if not self.plugin.can_process(book_data):
+                logger.debug(
+                    f"{self.log_prefix} Plugin skipped book_id={item.get('book_id')}"
+                )
+                return None
+        except Exception as e:
+            logger.warning(
+                f"{self.log_prefix} can_process() raised: {e}"
+            )
+            return None
+
+        # Run process() with timeout enforcement
+        try:
+            with ThreadPoolExecutor(max_workers=1) as executor:
+                future = executor.submit(self.plugin.process, book_data)
+                result = future.result(timeout=self.timeout)
+        except FuturesTimeoutError:
+            logger.warning(
+                f"{self.log_prefix} process() timed out after {self.timeout}s "
+                f"for book_id={item.get('book_id')}"
+            )
+            return None
+        except Exception as e:
+            logger.error(
+                f"{self.log_prefix} process() raised: {e}",
+                exc_info=True
+            )
+            return None
+
+        if not result:
+            return None
+
+        # Validate result is a dict
+        if not isinstance(result, dict):
+            logger.warning(
+                f"{self.log_prefix} process() returned {type(result).__name__}, "
+                f"expected dict"
+            )
+            return None
+
+        return result
+
+    def _apply_result(self, item: Dict, mapped_fields: Dict) -> bool:
+        """Apply plugin results to the book profile in the database.
+
+        Args:
+            item: Original item dict from database.
+            mapped_fields: Dict of field_name -> value from plugin.
+
+        Returns:
+            True if the item was updated, False otherwise.
+        """
+        from library_manager.models.book_profile import BookProfile
+
+        source_name = f'plugin_{self.plugin_info.plugin_id}'
+        source_weight = 60  # Plugin default weight
+
+        # Load or create profile
+        profile = BookProfile()
+        if item.get('profile'):
+            try:
+                existing = json.loads(item['profile']) if isinstance(item['profile'], str) else item['profile']
+                if hasattr(BookProfile, 'from_dict'):
+                    profile = BookProfile.from_dict(existing)
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+        # Apply fields
+        fields_applied = 0
+        for field_name, value in mapped_fields.items():
+            if not value:
+                continue
+
+            if field_name == 'author':
+                if profile.add_author(source_name, value, source_weight):
+                    fields_applied += 1
+            elif field_name == 'title':
+                if profile.add_title(source_name, value, source_weight):
+                    fields_applied += 1
+            elif field_name == 'narrator':
+                profile.narrator.add_source(source_name, value, source_weight)
+                fields_applied += 1
+            elif field_name == 'series':
+                profile.series.add_source(source_name, value, source_weight)
+                fields_applied += 1
+            elif field_name == 'series_num':
+                profile.series_num.add_source(source_name, value, source_weight)
+                fields_applied += 1
+            elif field_name == 'year':
+                profile.year.add_source(source_name, value, source_weight)
+                fields_applied += 1
+            elif field_name == 'language':
+                profile.language.add_source(source_name, value, source_weight)
+                fields_applied += 1
+
+        if fields_applied == 0:
+            return False
+
+        # Add to verification history
+        if source_name not in profile.verification_layers_used:
+            profile.verification_layers_used.append(source_name)
+
+        profile.finalize()
+
+        # Write to database
+        profile_json = json.dumps(profile.to_dict())
+        confidence = profile.overall_confidence
+
+        conn = self.get_db()
+        c = conn.cursor()
+
+        try:
+            next_layer = self.plugin_info.default_order + 1
+            c.execute('''UPDATE books SET
+                        profile = ?,
+                        confidence = ?,
+                        verification_layer = ?,
+                        max_layer_reached = MAX(COALESCE(max_layer_reached, 0), ?)
+                        WHERE id = ?''',
+                     (profile_json, confidence, next_layer,
+                      self.plugin_info.default_order, item['book_id']))
+            conn.commit()
+
+            logger.info(
+                f"{self.log_prefix} Updated profile for book_id={item['book_id']} "
+                f"({fields_applied} fields, confidence={confidence}%)"
+            )
+            return True
+
+        except Exception as e:
+            logger.error(
+                f"{self.log_prefix} Failed to update book {item['book_id']}: {e}"
+            )
+            conn.rollback()
+            return False
+        finally:
+            conn.close()
+
+
+# ============== MANIFEST VALIDATION ==============
+
+def _validate_manifest(manifest: Dict, plugin_dir: Path) -> List[str]:
+    """Validate a plugin manifest.
+
+    Args:
+        manifest: Parsed manifest dict.
+        plugin_dir: Path to the plugin directory.
+
+    Returns:
+        List of error strings. Empty list means valid.
+    """
+    errors = []
+
+    for field_name in REQUIRED_MANIFEST_FIELDS:
+        if not manifest.get(field_name):
+            errors.append(f"Missing required field: {field_name}")
+
+    # Validate entry_point exists
+    entry_point = manifest.get('entry_point', '')
+    if entry_point:
+        entry_path = plugin_dir / entry_point
+        if not entry_path.exists():
+            errors.append(f"Entry point file not found: {entry_point}")
+        elif not entry_path.suffix == '.py':
+            errors.append(f"Entry point must be a .py file: {entry_point}")
+
+    # Validate plugin ID format (alphanumeric, hyphens, underscores)
+    plugin_id = manifest.get('id', '')
+    if plugin_id:
+        import re
+        if not re.match(r'^[a-zA-Z0-9_-]+$', plugin_id):
+            errors.append(
+                f"Invalid plugin id '{plugin_id}': use only letters, numbers, "
+                f"hyphens, underscores"
+            )
+
+    # Validate type
+    plugin_type = manifest.get('type', 'layer')
+    if plugin_type not in ('layer',):
+        errors.append(f"Unsupported plugin type: {plugin_type}")
+
+    # Validate default_order is reasonable
+    order = manifest.get('default_order', 35)
+    if not isinstance(order, int) or order < 1 or order > 999:
+        errors.append("default_order must be an integer between 1 and 999")
+
+    return errors
+
+
+# ============== DISCOVERY ==============
+
+def discover_plugins(plugin_dir: Path) -> List[PluginInfo]:
+    """Scan a directory for valid plugins.
+
+    Looks for subdirectories containing manifest.json, validates them,
+    and returns PluginInfo objects for valid plugins.
+
+    Args:
+        plugin_dir: Directory to scan for plugins.
+
+    Returns:
+        List of PluginInfo for valid plugins. Invalid plugins are
+        logged as warnings and skipped.
+    """
+    if not plugin_dir.exists():
+        logger.info(f"{LOG_PREFIX} Plugin directory does not exist: {plugin_dir}")
+        return []
+
+    if not plugin_dir.is_dir():
+        logger.warning(f"{LOG_PREFIX} Plugin path is not a directory: {plugin_dir}")
+        return []
+
+    plugins = []
+
+    for subdir in sorted(plugin_dir.iterdir()):
+        if not subdir.is_dir():
+            continue
+
+        # Skip hidden directories and __pycache__
+        if subdir.name.startswith('.') or subdir.name == '__pycache__':
+            continue
+
+        manifest_path = subdir / 'manifest.json'
+        if not manifest_path.exists():
+            logger.debug(
+                f"{LOG_PREFIX} Skipping {subdir.name}: no manifest.json"
+            )
+            continue
+
+        # Parse manifest
+        try:
+            with open(manifest_path) as f:
+                manifest = json.load(f)
+        except (json.JSONDecodeError, OSError) as e:
+            logger.warning(
+                f"{LOG_PREFIX} Invalid manifest.json in {subdir.name}: {e}"
+            )
+            continue
+
+        # Validate manifest
+        errors = _validate_manifest(manifest, subdir)
+        if errors:
+            for err in errors:
+                logger.warning(f"{LOG_PREFIX} {subdir.name}: {err}")
+            continue
+
+        info = PluginInfo(
+            plugin_id=manifest['id'],
+            name=manifest['name'],
+            version=manifest.get('version', '0.0.1'),
+            description=manifest.get('description', ''),
+            plugin_dir=subdir,
+            entry_point=manifest['entry_point'],
+            class_name=manifest.get('class_name', ''),
+            default_order=manifest.get('default_order', 35),
+            plugin_type=manifest.get('type', 'layer'),
+            requires_config=manifest.get('requires_config', []),
+            requires_secrets=manifest.get('requires_secrets', []),
+            permissions=manifest.get('permissions', {}),
+            manifest=manifest,
+        )
+
+        logger.info(
+            f"{LOG_PREFIX} Discovered plugin: {info.name} v{info.version} "
+            f"({info.plugin_id})"
+        )
+        plugins.append(info)
+
+    if plugins:
+        logger.info(f"{LOG_PREFIX} Discovered {len(plugins)} plugin(s)")
+    else:
+        logger.debug(f"{LOG_PREFIX} No plugins found in {plugin_dir}")
+
+    return plugins
+
+
+# ============== LOADING ==============
+
+def load_plugin(plugin_info: PluginInfo, config: dict = None,
+                secrets: dict = None) -> Optional[BasePlugin]:
+    """Load and instantiate a plugin from its PluginInfo.
+
+    Uses importlib to dynamically load the plugin module, finds the
+    target class (by class_name or auto-discovery), instantiates it,
+    and calls setup().
+
+    Args:
+        plugin_info: PluginInfo from discovery.
+        config: Plugin-specific config (from plugin_configs).
+        secrets: Full secrets dict.
+
+    Returns:
+        Instantiated BasePlugin, or None on failure.
+    """
+    entry_path = plugin_info.entry_point_path
+    module_name = f"lm_plugin_{plugin_info.plugin_id}"
+
+    try:
+        # Load the module
+        spec = importlib.util.spec_from_file_location(module_name, entry_path)
+        if spec is None or spec.loader is None:
+            logger.error(
+                f"{LOG_PREFIX} Failed to create module spec for "
+                f"{plugin_info.plugin_id}: {entry_path}"
+            )
+            return None
+
+        module = importlib.util.module_from_spec(spec)
+
+        # Add to sys.modules so relative imports work within plugins
+        sys.modules[module_name] = module
+
+        try:
+            spec.loader.exec_module(module)
+        except Exception as e:
+            logger.error(
+                f"{LOG_PREFIX} Failed to execute module for "
+                f"{plugin_info.plugin_id}: {e}"
+            )
+            # Clean up on failure
+            sys.modules.pop(module_name, None)
+            return None
+
+        # Find the plugin class
+        plugin_class = None
+
+        if plugin_info.class_name:
+            # Look up by explicit class name
+            plugin_class = getattr(module, plugin_info.class_name, None)
+            if plugin_class is None:
+                logger.error(
+                    f"{LOG_PREFIX} Class '{plugin_info.class_name}' not found "
+                    f"in {entry_path}"
+                )
+                return None
+        else:
+            # Auto-discover: find first BasePlugin subclass
+            for attr_name in dir(module):
+                attr = getattr(module, attr_name)
+                if (isinstance(attr, type)
+                        and issubclass(attr, BasePlugin)
+                        and attr is not BasePlugin):
+                    plugin_class = attr
+                    break
+
+            if plugin_class is None:
+                logger.error(
+                    f"{LOG_PREFIX} No BasePlugin subclass found in {entry_path}"
+                )
+                return None
+
+        # Instantiate
+        try:
+            instance = plugin_class()
+        except Exception as e:
+            logger.error(
+                f"{LOG_PREFIX} Failed to instantiate {plugin_class.__name__} "
+                f"for {plugin_info.plugin_id}: {e}"
+            )
+            return None
+
+        # Set metadata from manifest
+        instance.name = plugin_info.name
+        instance.description = plugin_info.description
+        instance.version = plugin_info.version
+
+        # Call setup
+        try:
+            instance.setup(config or {}, secrets or {})
+        except Exception as e:
+            logger.error(
+                f"{LOG_PREFIX} setup() failed for {plugin_info.plugin_id}: {e}"
+            )
+            return None
+
+        logger.info(
+            f"{LOG_PREFIX} Loaded plugin: {plugin_info.name} v{plugin_info.version} "
+            f"({plugin_class.__name__})"
+        )
+        return instance
+
+    except Exception as e:
+        logger.error(
+            f"{LOG_PREFIX} Unexpected error loading {plugin_info.plugin_id}: {e}",
+            exc_info=True
+        )
+        return None
+
+
+# ============== REGISTRATION ==============
+
+def register_plugins(registry, config: dict, get_db: Callable) -> List[PluginAdapter]:
+    """Discover, load, and register all plugins.
+
+    This is the main entry point called from app.py on startup. It:
+    1. Reads plugin_dir from config
+    2. Discovers plugins in that directory
+    3. Loads each plugin (with config and secrets)
+    4. Wraps each in a PluginAdapter
+    5. Registers each in the LayerRegistry
+
+    Args:
+        registry: LayerRegistry instance.
+        config: Full app configuration dict.
+        get_db: Callable that returns a database connection.
+
+    Returns:
+        List of PluginAdapter instances for loaded plugins.
+    """
+    plugin_dir = Path(config.get('plugin_dir', '/data/plugins'))
+    plugin_configs = config.get('plugin_configs', {})
+
+    # Discover
+    discovered = discover_plugins(plugin_dir)
+    if not discovered:
+        return []
+
+    # Load secrets once
+    secrets = load_secrets()
+
+    adapters = []
+
+    for info in discovered:
+        # Get per-plugin config
+        plugin_config = plugin_configs.get(info.plugin_id, {})
+
+        # Check for missing required secrets
+        missing_secrets = [
+            s for s in info.requires_secrets
+            if not secrets.get(s)
+        ]
+        if missing_secrets:
+            logger.warning(
+                f"{LOG_PREFIX} {info.plugin_id}: missing required secrets: "
+                f"{', '.join(missing_secrets)} -- skipping"
+            )
+            continue
+
+        # Load the plugin
+        instance = load_plugin(info, config=plugin_config, secrets=secrets)
+        if instance is None:
+            continue
+
+        # Determine timeout from plugin config or default
+        timeout = plugin_config.get('timeout', DEFAULT_PLUGIN_TIMEOUT)
+
+        # Wrap in adapter
+        adapter = PluginAdapter(instance, info, get_db, timeout=timeout)
+
+        # Register in the layer registry
+        layer_id = adapter.layer_id
+        try:
+            registry.register(LayerInfo(
+                layer_id=layer_id,
+                layer_name=info.name,
+                description=info.description or f"Plugin: {info.name}",
+                config_enable_key=f"plugin_{info.plugin_id}_enabled",
+                default_order=info.default_order,
+                supports_circuit_breaker=False,
+            ))
+            logger.info(
+                f"{LOG_PREFIX} Registered {info.name} as '{layer_id}' "
+                f"at order {info.default_order}"
+            )
+        except ValueError as e:
+            # Already registered (duplicate plugin ID)
+            logger.warning(f"{LOG_PREFIX} {info.plugin_id}: {e}")
+            continue
+
+        adapters.append(adapter)
+
+    if adapters:
+        logger.info(f"{LOG_PREFIX} Loaded {len(adapters)} plugin(s)")
+
+    return adapters
+
+
+def teardown_plugins(adapters: List[PluginAdapter]):
+    """Call teardown() on all loaded plugins.
+
+    Called during app shutdown to clean up plugin resources.
+
+    Args:
+        adapters: List of PluginAdapter instances.
+    """
+    for adapter in adapters:
+        try:
+            adapter.plugin.teardown()
+            logger.debug(
+                f"{LOG_PREFIX} Teardown complete: {adapter.plugin_info.plugin_id}"
+            )
+        except Exception as e:
+            logger.warning(
+                f"{LOG_PREFIX} teardown() failed for "
+                f"{adapter.plugin_info.plugin_id}: {e}"
+            )
diff --git a/test-env/example-plugin/layer.py b/test-env/example-plugin/layer.py
new file mode 100644
index 0000000..cea74a6
--- /dev/null
+++ b/test-env/example-plugin/layer.py
@@ -0,0 +1,78 @@
+"""Example plugin for Library Manager.
+
+This is a minimal plugin that demonstrates the BasePlugin interface.
+It logs each book it sees and returns empty results (no modifications).
+
+To use this as a template:
+1. Copy this directory to /data/plugins/your-plugin-name/
+2. Edit manifest.json with your plugin's metadata
+3. Implement process() with your logic
+4. Restart Library Manager
+
+The plugin loader will discover and load your plugin automatically.
+"""
+
+import logging
+
+# Import BasePlugin from the plugin loader
+from library_manager.plugin_loader import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+
+class ExampleLoggerPlugin(BasePlugin):
+    """A simple plugin that logs book information.
+
+    This demonstrates:
+    - setup() for one-time initialization
+    - can_process() for filtering books
+    - process() for the main logic
+    - teardown() for cleanup
+    """
+
+    name = "Example Logger"
+    description = "Logs book data for debugging"
+    version = "1.0.0"
+
+    def setup(self, config, secrets):
+        """Store config for later use."""
+        self.log_level = config.get('log_level', 'info')
+        self.books_seen = 0
+        logger.info("[ExamplePlugin] Setup complete")
+
+    def can_process(self, book_data):
+        """Process all books."""
+        return True
+
+    def process(self, book_data):
+        """Log the book data and return empty (no changes).
+
+        In a real plugin, you would:
+        1. Extract info from book_data (title, author, path, etc.)
+        2. Query your data source (API, database, file, etc.)
+        3. Return a dict with matched fields
+
+        Example return for a match:
+            return {
+                'title': 'The Corrected Title',
+                'author': 'Correct Author Name',
+                'narrator': 'Narrator Name',
+            }
+        """
+        self.books_seen += 1
+        title = book_data.get('current_title', 'Unknown')
+        author = book_data.get('current_author', 'Unknown')
+
+        logger.info(
+            f"[ExamplePlugin] Book #{self.books_seen}: "
+            f"'{title}' by {author}"
+        )
+
+        # Return empty dict = no changes (this is just a logger)
+        return {}
+
+    def teardown(self):
+        """Log summary on shutdown."""
+        logger.info(
+            f"[ExamplePlugin] Shutting down. Saw {self.books_seen} books total."
+        )
diff --git a/test-env/example-plugin/manifest.json b/test-env/example-plugin/manifest.json
new file mode 100644
index 0000000..4c6c417
--- /dev/null
+++ b/test-env/example-plugin/manifest.json
@@ -0,0 +1,16 @@
+{
+  "id": "example-logger",
+  "name": "Example Logger Plugin",
+  "version": "1.0.0",
+  "description": "A minimal example plugin that logs book data and returns empty results. Use as a template for building your own plugins.",
+  "type": "layer",
+  "entry_point": "layer.py",
+  "class_name": "ExampleLoggerPlugin",
+  "default_order": 35,
+  "requires_config": [],
+  "requires_secrets": [],
+  "permissions": {
+    "network": [],
+    "database": "read"
+  }
+}

From 2986cdb2f2e4236eb12bbbfdb97d856afa8073cf Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Sat, 21 Mar 2026 11:57:21 -0500
Subject: [PATCH 13/20] feat: Professional UI overhaul - design system, CSS/JS
 extraction, settings reorg (#198) (#199)

Professional UI overhaul: extracted 730 lines CSS to static/css/style.css with design tokens, consolidated duplicate JS to static/js/common.js, reorganized settings from 7 tabs to 4 (Library, Engine, Pipeline, Integrations), fixed color palette, added mobile responsive breakpoints, replaced all hardcoded colors with CSS variables.

Closes #198
---
 CHANGELOG.md                    |   19 +
 README.md                       |    2 +-
 app.py                          |    2 +-
 static/css/style.css            | 1110 +++++++++++++++++++++++++++++++
 static/js/common.js             |   41 ++
 templates/base.html             |  743 +--------------------
 templates/dashboard.html        |   50 +-
 templates/history.html          |   13 +-
 templates/hooks_settings.html   |    2 +-
 templates/library.html          |  145 +---
 templates/orphans.html          |   12 +-
 templates/plugins_settings.html |    2 +-
 templates/queue.html            |    9 +-
 templates/settings.html         |  151 +----
 templates/setup_wizard.html     |  158 +----
 15 files changed, 1236 insertions(+), 1223 deletions(-)
 create mode 100644 static/css/style.css
 create mode 100644 static/js/common.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dde3b26..9debc1f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,25 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.143] - 2026-03-21
+
+### Changed
+
+- **Issue #198: Comprehensive UI overhaul** - Extracted 728 lines of inline CSS from base.html
+  into `static/css/style.css` with CSS custom properties design system (spacing scale, border
+  radius tokens, transition timing). Consolidated duplicate `escapeHtml()` and `showToast()`
+  helpers from 5 templates into `static/js/common.js`. Reorganized Settings from 7 tabs
+  (Library, Processing, AI Setup, Safety, Advanced, Post-Processing, Plugins) into 4 tabs
+  (Library, Engine, Pipeline, Integrations) with section headers. Added mobile responsive
+  breakpoints for tables, nav-tabs, cards, and stat numbers. Replaced hardcoded hex colors
+  with CSS variables throughout all templates. Changed accent success color from `#00ff00`
+  to `#2ecc71` for professional appearance. Added sticky settings save bar with backdrop blur.
+  Replaced all inline `font-size` styles with utility classes (`fs-icon-lg`, `fs-icon-xl`).
+  Setup wizard styles extracted with `setup-mode` body class for navbar hiding. All modal
+  backgrounds now use theme CSS variables instead of hardcoded `#16213e`.
+
+---
+
 ## [0.9.0-beta.142] - 2026-03-21
 
 ### Added
diff --git a/README.md b/README.md
index 4a1a3aa..62617a4 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.142-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.143-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
diff --git a/app.py b/app.py
index b5e8b96..2c2462d 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.142"
+APP_VERSION = "0.9.0-beta.143"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
diff --git a/static/css/style.css b/static/css/style.css
new file mode 100644
index 0000000..844e036
--- /dev/null
+++ b/static/css/style.css
@@ -0,0 +1,1110 @@
+/* ===== THEME SYSTEM - CSS Variables ===== */
+:root,
+[data-theme="default"] {
+    /* Background colors */
+    --theme-bg-primary: #1a1a2e;
+    --theme-bg-secondary: #16213e;
+    --theme-bg-card: rgba(22, 33, 62, 0.8);
+    --theme-bg-navbar: rgba(15, 52, 96, 0.9);
+    --theme-bg-header: rgba(15, 52, 96, 0.5);
+    /* Accent colors */
+    --theme-accent-primary: #e94560;
+    --theme-accent-primary-hover: #d63d56;
+    --theme-accent-secondary: #00d9ff;
+    --theme-accent-warning: #ffc107;
+    --theme-accent-success: #2ecc71;
+    /* Text colors */
+    --theme-text-primary: #eee;
+    --theme-text-secondary: rgba(255, 255, 255, 0.6);
+    --theme-text-link: #00d9ff;
+    /* Border colors */
+    --theme-border-primary: rgba(15, 52, 96, 0.5);
+    --theme-border-accent: rgba(0, 217, 255, 0.3);
+    /* Gradients */
+    --theme-gradient-bg: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+    --theme-gradient-stat: linear-gradient(45deg, #e94560, #00d9ff);
+    --theme-gradient-progress: linear-gradient(90deg, #e94560, #00d9ff);
+    /* Fonts - Bootstrap system default */
+    --theme-font-heading: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    --theme-font-body: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    /* Shadows */
+    --theme-shadow-glow: rgba(0, 217, 255, 0.1);
+    --theme-shadow-card: rgba(0, 0, 0, 0.5);
+    /* Spacing scale */
+    --space-xs: 0.25rem;
+    --space-sm: 0.5rem;
+    --space-md: 1rem;
+    --space-lg: 1.5rem;
+    --space-xl: 2rem;
+    /* Border radius */
+    --radius-sm: 4px;
+    --radius-md: 8px;
+    --radius-lg: 12px;
+    /* Transitions */
+    --transition-fast: 150ms ease;
+    --transition-normal: 250ms ease;
+}
+
+/* ===== SKALDLEITA THEME - Norse Gold ===== */
+[data-theme="skaldleita"] {
+    /* Background colors - darker, more dramatic */
+    --theme-bg-primary: #0a0c10;
+    --theme-bg-secondary: #12151c;
+    --theme-bg-card: rgba(18, 21, 28, 0.9);
+    --theme-bg-navbar: rgba(26, 30, 40, 0.95);
+    --theme-bg-header: rgba(26, 30, 40, 0.7);
+    /* Accent colors - gold and ice blue */
+    --theme-accent-primary: #c9a55c;
+    --theme-accent-primary-hover: #e8c87d;
+    --theme-accent-secondary: #7eb8da;
+    --theme-accent-warning: #c9a55c;
+    --theme-accent-success: #7eb8da;
+    /* Text colors */
+    --theme-text-primary: #e8e6e3;
+    --theme-text-secondary: #9ca3af;
+    --theme-text-link: #c9a55c;
+    /* Border colors */
+    --theme-border-primary: rgba(201, 165, 92, 0.2);
+    --theme-border-accent: rgba(201, 165, 92, 0.4);
+    /* Gradients */
+    --theme-gradient-bg: linear-gradient(135deg, #0a0c10 0%, #12151c 100%);
+    --theme-gradient-stat: linear-gradient(45deg, #c9a55c, #7eb8da);
+    --theme-gradient-progress: linear-gradient(90deg, #c9a55c, #7eb8da);
+    /* Fonts - Norse-inspired */
+    --theme-font-heading: 'Cinzel', serif;
+    --theme-font-body: 'Inter', sans-serif;
+    /* Shadows - warmer glow */
+    --theme-shadow-glow: rgba(201, 165, 92, 0.15);
+    --theme-shadow-card: rgba(0, 0, 0, 0.6);
+}
+
+/* ===== Apply theme variables ===== */
+:root {
+    --bs-body-bg: var(--theme-bg-primary);
+    --bs-body-color: var(--theme-text-primary);
+    --bs-card-bg: var(--theme-bg-card);
+    --bs-border-color: var(--theme-border-primary);
+}
+body {
+    background: var(--theme-gradient-bg);
+    min-height: 100vh;
+    font-family: var(--theme-font-body);
+    color: var(--theme-text-primary);
+}
+h1, h2, h3, h4, h5, h6, .navbar-brand {
+    font-family: var(--theme-font-heading);
+}
+.navbar {
+    background: var(--theme-bg-navbar) !important;
+    backdrop-filter: blur(10px);
+}
+.card {
+    background: var(--theme-bg-card);
+    border: 1px solid var(--theme-border-primary);
+    border-radius: var(--radius-lg);
+    transition: border-color var(--transition-normal), box-shadow var(--transition-normal);
+}
+.card:hover {
+    border-color: var(--theme-border-accent);
+    box-shadow: 0 4px 20px var(--theme-shadow-glow);
+}
+.card-header {
+    background: var(--theme-bg-header);
+    border-bottom: 1px solid var(--theme-border-primary);
+}
+.table {
+    --bs-table-bg: transparent;
+    --bs-table-color: var(--theme-text-primary);
+}
+.btn-primary {
+    background: var(--theme-accent-primary);
+    border-color: var(--theme-accent-primary);
+}
+.btn-primary:hover {
+    background: var(--theme-accent-primary-hover);
+    border-color: var(--theme-accent-primary-hover);
+}
+.btn-success {
+    background: var(--theme-accent-secondary);
+    border-color: var(--theme-accent-secondary);
+    color: #000;
+}
+.stat-card {
+    transition: transform 0.2s;
+}
+.stat-card:hover {
+    transform: translateY(-5px);
+}
+.stat-number {
+    font-size: 2.5rem;
+    font-weight: bold;
+    background: var(--theme-gradient-stat);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+}
+.badge-fix {
+    background: var(--theme-accent-primary);
+}
+.badge-ok {
+    background: var(--theme-accent-secondary);
+    color: #000;
+}
+.badge-pending {
+    background: var(--theme-accent-warning);
+    color: #000;
+}
+.status-indicator {
+    display: inline-block;
+    width: 10px;
+    height: 10px;
+    border-radius: 50%;
+    margin-right: 8px;
+}
+.status-running {
+    background: var(--theme-accent-success);
+    box-shadow: 0 0 10px var(--theme-accent-success);
+    animation: pulse 2s infinite;
+}
+.status-stopped {
+    background: #ff0000;
+}
+@keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.5; }
+}
+.nav-link {
+    color: rgba(255,255,255,0.8) !important;
+}
+.nav-link:hover, .nav-link.active {
+    color: var(--theme-text-link) !important;
+}
+.text-muted {
+    color: var(--theme-text-secondary) !important;
+}
+
+/* ===== SKALDLEITA THEME - Comprehensive Color Overrides ===== */
+/* All Bootstrap text utilities -> Gold */
+[data-theme="skaldleita"] .text-primary,
+[data-theme="skaldleita"] .text-info,
+[data-theme="skaldleita"] .text-success,
+[data-theme="skaldleita"] .text-warning,
+[data-theme="skaldleita"] .text-danger {
+    color: #c9a55c !important;
+}
+[data-theme="skaldleita"] .text-secondary {
+    color: #8b7340 !important;
+}
+/* ALL icons become gold */
+[data-theme="skaldleita"] i.bi,
+[data-theme="skaldleita"] .bi {
+    color: #c9a55c !important;
+}
+/* Headings get gold accent */
+[data-theme="skaldleita"] h1,
+[data-theme="skaldleita"] h2,
+[data-theme="skaldleita"] h3,
+[data-theme="skaldleita"] h4,
+[data-theme="skaldleita"] h5,
+[data-theme="skaldleita"] .card-header {
+    color: #c9a55c !important;
+}
+/* Card header text */
+[data-theme="skaldleita"] .card-header * {
+    color: #c9a55c !important;
+}
+/* Navbar brand gold */
+[data-theme="skaldleita"] .navbar-brand {
+    color: #c9a55c !important;
+}
+/* Links gold */
+[data-theme="skaldleita"] a {
+    color: #c9a55c !important;
+}
+[data-theme="skaldleita"] a:hover {
+    color: #e8c87d !important;
+}
+/* Nav links */
+[data-theme="skaldleita"] .nav-link {
+    color: #9ca3af !important;
+}
+[data-theme="skaldleita"] .nav-link:hover,
+[data-theme="skaldleita"] .nav-link.active {
+    color: #c9a55c !important;
+}
+/* Background colors - all use gold */
+[data-theme="skaldleita"] .bg-primary,
+[data-theme="skaldleita"] .bg-info,
+[data-theme="skaldleita"] .bg-success,
+[data-theme="skaldleita"] .bg-warning,
+[data-theme="skaldleita"] .bg-danger {
+    background-color: #c9a55c !important;
+    color: #0a0c10 !important;
+}
+/* Badges - gold with dark text */
+[data-theme="skaldleita"] .badge {
+    background-color: #c9a55c !important;
+    color: #0a0c10 !important;
+    font-weight: 500;
+}
+/* Buttons */
+[data-theme="skaldleita"] .btn-primary,
+[data-theme="skaldleita"] .btn-success,
+[data-theme="skaldleita"] .btn-info {
+    background-color: #c9a55c !important;
+    border-color: #c9a55c !important;
+    color: #0a0c10 !important;
+}
+[data-theme="skaldleita"] .btn-primary:hover,
+[data-theme="skaldleita"] .btn-success:hover,
+[data-theme="skaldleita"] .btn-info:hover {
+    background-color: #e8c87d !important;
+    border-color: #e8c87d !important;
+}
+[data-theme="skaldleita"] .btn-outline-primary,
+[data-theme="skaldleita"] .btn-outline-success,
+[data-theme="skaldleita"] .btn-outline-info,
+[data-theme="skaldleita"] .btn-outline-secondary,
+[data-theme="skaldleita"] .btn-outline-warning {
+    color: #c9a55c !important;
+    border-color: #c9a55c !important;
+}
+[data-theme="skaldleita"] .btn-outline-primary:hover,
+[data-theme="skaldleita"] .btn-outline-success:hover,
+[data-theme="skaldleita"] .btn-outline-info:hover,
+[data-theme="skaldleita"] .btn-outline-secondary:hover,
+[data-theme="skaldleita"] .btn-outline-warning:hover {
+    background-color: #c9a55c !important;
+    color: #0a0c10 !important;
+}
+/* Status bar elements */
+[data-theme="skaldleita"] .status-book,
+[data-theme="skaldleita"] .status-author {
+    color: #c9a55c !important;
+}
+[data-theme="skaldleita"] .status-layer {
+    background: rgba(201, 165, 92, 0.2) !important;
+    color: #c9a55c !important;
+}
+[data-theme="skaldleita"] .status-stat-value {
+    color: #c9a55c !important;
+}
+/* Stat numbers gradient -> solid gold */
+[data-theme="skaldleita"] .stat-number {
+    background: none !important;
+    -webkit-background-clip: unset !important;
+    -webkit-text-fill-color: #c9a55c !important;
+    color: #c9a55c !important;
+}
+/* Form focus states */
+[data-theme="skaldleita"] .form-control:focus,
+[data-theme="skaldleita"] .form-select:focus {
+    border-color: #c9a55c !important;
+    box-shadow: 0 0 0 0.2rem rgba(201, 165, 92, 0.25) !important;
+}
+[data-theme="skaldleita"] .form-check-input:checked {
+    background-color: #c9a55c !important;
+    border-color: #c9a55c !important;
+}
+/* Gold borders around elements */
+[data-theme="skaldleita"] .card {
+    border: 1px solid rgba(201, 165, 92, 0.3) !important;
+}
+[data-theme="skaldleita"] .card-header {
+    border-bottom: 1px solid rgba(201, 165, 92, 0.3) !important;
+}
+[data-theme="skaldleita"] .form-control,
+[data-theme="skaldleita"] .form-select {
+    border-color: rgba(201, 165, 92, 0.3) !important;
+}
+[data-theme="skaldleita"] .table {
+    border-color: rgba(201, 165, 92, 0.2) !important;
+}
+[data-theme="skaldleita"] .table > :not(caption) > * > * {
+    border-color: rgba(201, 165, 92, 0.15) !important;
+}
+[data-theme="skaldleita"] .navbar {
+    border-bottom: 1px solid rgba(201, 165, 92, 0.2) !important;
+}
+[data-theme="skaldleita"] .status-bar {
+    border-bottom: 1px solid rgba(201, 165, 92, 0.3) !important;
+}
+[data-theme="skaldleita"] .alert {
+    border-color: rgba(201, 165, 92, 0.3) !important;
+}
+[data-theme="skaldleita"] .list-group-item {
+    border-color: rgba(201, 165, 92, 0.2) !important;
+}
+[data-theme="skaldleita"] hr {
+    border-color: rgba(201, 165, 92, 0.2) !important;
+    opacity: 1;
+}
+[data-theme="skaldleita"] .modal-content {
+    border: 1px solid rgba(201, 165, 92, 0.3) !important;
+}
+[data-theme="skaldleita"] .dropdown-menu {
+    border: 1px solid rgba(201, 165, 92, 0.3) !important;
+}
+/* Skaldleita-specific: rune divider */
+[data-theme="skaldleita"] .rune-divider {
+    text-align: center;
+    color: var(--theme-accent-primary);
+    opacity: 0.3;
+    font-size: 0.8rem;
+    letter-spacing: 0.5em;
+    margin: var(--space-md) 0;
+}
+[data-theme="skaldleita"] .rune-divider::before {
+    content: "\16A0 \16A2 \16A6 \16A8 \16B1 \16B2";
+}
+/* Theme-aware form controls */
+.form-select, .form-control {
+    transition: border-color 0.2s, box-shadow 0.2s;
+}
+.form-select:focus, .form-control:focus {
+    border-color: var(--theme-accent-primary);
+    box-shadow: 0 0 0 0.2rem rgba(var(--theme-accent-primary-rgb, 233, 69, 96), 0.25);
+}
+.form-check-input:checked {
+    background-color: var(--theme-accent-primary);
+    border-color: var(--theme-accent-primary);
+}
+/* Theme-aware links */
+a {
+    color: var(--theme-text-link);
+}
+a:hover {
+    color: var(--theme-accent-primary-hover);
+}
+/* Alert styling */
+.alert-dark {
+    background: var(--theme-bg-card);
+    border-color: var(--theme-border-primary);
+    color: var(--theme-text-primary);
+}
+/* Skaldleita theme enhancements */
+[data-theme="skaldleita"] .navbar-brand {
+    font-weight: 600;
+    letter-spacing: 0.05em;
+}
+[data-theme="skaldleita"] .card-header {
+    font-family: var(--theme-font-heading);
+    font-weight: 500;
+    letter-spacing: 0.02em;
+}
+
+/* ===== Book Info Card (Hover Preview) ===== */
+.book-hover-card {
+    position: absolute;
+    z-index: 1000;
+    width: 380px;
+    background: var(--theme-gradient-bg);
+    border: 1px solid var(--theme-border-accent);
+    border-radius: var(--radius-lg);
+    box-shadow: 0 8px 32px var(--theme-shadow-card), 0 0 20px var(--theme-shadow-glow);
+    padding: 0;
+    display: none;
+    overflow: hidden;
+}
+.book-hover-card.show {
+    display: block;
+    animation: fadeIn 0.2s ease;
+}
+@keyframes fadeIn {
+    from { opacity: 0; transform: translateY(-10px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+.book-hover-card .card-header {
+    background: rgba(var(--theme-accent-secondary-rgb, 0, 217, 255), 0.1);
+    padding: 12px 15px;
+    border-bottom: 1px solid var(--theme-border-accent);
+}
+.book-hover-card .card-body {
+    padding: 15px;
+}
+.book-hover-card .card-header .d-flex {
+    min-width: 0;
+}
+.book-hover-card #hover-cover-container {
+    flex-shrink: 0;
+}
+.book-hover-card .card-header .flex-grow-1 {
+    min-width: 0;
+    overflow: hidden;
+}
+.book-hover-card .book-cover {
+    width: 80px;
+    height: 120px;
+    object-fit: cover;
+    border-radius: 6px;
+    border: 2px solid var(--theme-border-accent);
+    background: rgba(0, 0, 0, 0.3);
+}
+.book-hover-card .book-cover-placeholder {
+    width: 80px;
+    height: 120px;
+    background: var(--theme-bg-header);
+    border-radius: 6px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: rgba(255,255,255,0.3);
+    font-size: 2rem;
+}
+.book-hover-card .book-author,
+.book-hover-card .book-series {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+.book-hover-card .book-title {
+    font-size: 1.1rem;
+    font-weight: 600;
+    color: var(--theme-text-primary);
+    margin-bottom: 4px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+}
+.book-hover-card .book-author {
+    color: var(--theme-accent-secondary);
+    font-size: 0.9rem;
+}
+.book-hover-card .book-series {
+    color: var(--theme-accent-warning);
+    font-size: 0.85rem;
+}
+.book-hover-card .book-meta {
+    font-size: 0.8rem;
+    color: var(--theme-text-secondary);
+}
+.book-hover-card .book-description {
+    font-size: 0.85rem;
+    color: rgba(255,255,255,0.8);
+    max-height: 80px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    line-height: 1.4;
+}
+.book-hover-card .book-tags {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 4px;
+}
+.book-hover-card .book-tag {
+    font-size: 0.7rem;
+    padding: 2px 8px;
+    border-radius: 10px;
+    background: rgba(var(--theme-accent-secondary-rgb, 0, 217, 255), 0.15);
+    color: var(--theme-accent-secondary);
+}
+.book-hover-card .abs-status {
+    background: rgba(0,0,0,0.2);
+    border-radius: var(--radius-md);
+    padding: 10px;
+    margin-top: 10px;
+}
+.book-hover-card .abs-user {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 0.85rem;
+    padding: 4px 0;
+}
+.book-hover-card .abs-user .progress {
+    flex: 1;
+    height: 6px;
+}
+.book-hover-card .click-hint {
+    text-align: center;
+    font-size: 0.75rem;
+    color: rgba(255,255,255,0.4);
+    padding: 8px;
+    border-top: 1px solid var(--theme-border-accent);
+}
+
+/* ===== Search Result Cover Thumbnails ===== */
+.search-cover-container {
+    flex-shrink: 0;
+    width: 40px;
+    height: 60px;
+}
+.search-result-cover {
+    width: 40px;
+    height: 60px;
+    object-fit: cover;
+    border-radius: var(--radius-sm);
+    border: 1px solid var(--theme-border-accent);
+}
+.search-cover-placeholder {
+    width: 40px;
+    height: 60px;
+    background: var(--theme-bg-header);
+    border-radius: var(--radius-sm);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: rgba(255,255,255,0.3);
+    font-size: 1.2rem;
+}
+.search-result-item {
+    border-color: var(--theme-border-primary) !important;
+}
+.search-result-item:hover {
+    background: var(--theme-bg-header) !important;
+    border-color: var(--theme-border-accent) !important;
+}
+
+/* ===== Live Status Bar ===== */
+.status-bar {
+    background: var(--theme-bg-navbar);
+    border-bottom: 1px solid var(--theme-border-accent);
+    padding: 8px 0;
+    margin-bottom: var(--space-md);
+    backdrop-filter: blur(10px);
+    transition: all 0.3s ease;
+}
+.status-bar.processing {
+    border-bottom-color: var(--theme-accent-primary);
+}
+.status-bar.idle {
+    opacity: 0.7;
+}
+.status-bar.idle:hover {
+    opacity: 1;
+}
+.status-bar-content {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    flex-wrap: wrap;
+    gap: 10px;
+}
+.status-main {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    flex: 1;
+    min-width: 0;
+}
+.status-icon {
+    font-size: 1.2rem;
+    width: 28px;
+    text-align: center;
+}
+.status-icon.processing {
+    color: var(--theme-accent-primary);
+    animation: pulse-icon 1.5s ease-in-out infinite;
+}
+.status-icon.idle {
+    color: var(--theme-accent-secondary);
+}
+.status-icon.stopped {
+    color: #6c757d;
+}
+@keyframes pulse-icon {
+    0%, 100% { opacity: 1; transform: scale(1); }
+    50% { opacity: 0.6; transform: scale(0.95); }
+}
+.status-text {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    flex: 1;
+}
+.status-primary {
+    font-size: 0.9rem;
+    font-weight: 500;
+    color: var(--theme-text-primary);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+.status-secondary {
+    font-size: 0.75rem;
+    color: var(--theme-text-secondary);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+.status-book {
+    color: var(--theme-accent-secondary);
+    font-weight: 500;
+}
+.status-author {
+    color: var(--theme-accent-warning);
+}
+.status-layer {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    background: rgba(var(--theme-accent-primary-rgb, 233, 69, 96), 0.2);
+    color: var(--theme-accent-primary);
+    padding: 2px 8px;
+    border-radius: 10px;
+    font-size: 0.7rem;
+    font-weight: 600;
+    text-transform: uppercase;
+}
+.status-provider {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    margin-left: 8px;
+}
+.provider-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    background: rgba(0, 200, 150, 0.2);
+    color: #00c896;
+    padding: 2px 8px;
+    border-radius: 10px;
+    font-size: 0.7rem;
+    font-weight: 600;
+}
+.provider-badge.paid {
+    background: rgba(255, 193, 7, 0.2);
+    color: #ffc107;
+}
+.provider-free-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 3px;
+    background: rgba(0, 200, 150, 0.15);
+    color: #00c896;
+    padding: 2px 6px;
+    border-radius: 8px;
+    font-size: 0.6rem;
+    font-weight: 700;
+    text-transform: uppercase;
+}
+.status-step {
+    color: var(--theme-text-secondary);
+    font-size: 0.75rem;
+    margin-left: 8px;
+    font-style: italic;
+}
+.status-meta {
+    display: flex;
+    align-items: center;
+    gap: 15px;
+    flex-shrink: 0;
+}
+.status-stat {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    padding: 0 10px;
+    border-left: 1px solid rgba(255, 255, 255, 0.1);
+}
+.status-stat:first-child {
+    border-left: none;
+}
+.status-stat-value {
+    font-size: 1rem;
+    font-weight: 600;
+    color: var(--theme-accent-secondary);
+    line-height: 1;
+}
+.status-stat-label {
+    font-size: 0.65rem;
+    color: var(--theme-text-secondary);
+    text-transform: uppercase;
+}
+.status-progress {
+    height: 3px;
+    background: rgba(0, 0, 0, 0.3);
+    border-radius: 2px;
+    overflow: hidden;
+    margin-top: 4px;
+    width: 100%;
+    max-width: 200px;
+}
+.status-progress-bar {
+    height: 100%;
+    background: var(--theme-gradient-progress);
+    border-radius: 2px;
+    transition: width 0.5s ease;
+}
+
+/* ===== Hint Icon (Settings & Library) ===== */
+.hint-icon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 16px;
+    height: 16px;
+    border-radius: 50%;
+    border: 1px solid var(--theme-border-accent);
+    color: var(--theme-accent-secondary);
+    font-size: 10px;
+    font-weight: bold;
+    font-style: normal;
+    cursor: help;
+    margin-left: 4px;
+    position: relative;
+    vertical-align: middle;
+    line-height: 1;
+    flex-shrink: 0;
+}
+.hint-icon:hover {
+    border-color: var(--theme-accent-secondary);
+    color: var(--theme-accent-secondary);
+}
+.hint-icon .hint-text {
+    display: none;
+    position: absolute;
+    bottom: calc(100% + 8px);
+    left: 50%;
+    transform: translateX(-50%);
+    background: rgba(15, 52, 96, 0.95);
+    border: 1px solid var(--theme-border-accent);
+    color: #eee;
+    padding: var(--space-sm) var(--space-md);
+    border-radius: 6px;
+    font-size: 0.8rem;
+    font-weight: normal;
+    font-style: normal;
+    line-height: 1.4;
+    white-space: normal;
+    width: 280px;
+    z-index: 1000;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
+    pointer-events: none;
+}
+.hint-icon .hint-text::after {
+    content: '';
+    position: absolute;
+    top: 100%;
+    left: 50%;
+    transform: translateX(-50%);
+    border: 6px solid transparent;
+    border-top-color: var(--theme-border-accent);
+}
+.hint-icon:hover .hint-text {
+    display: block;
+}
+
+/* ===== Dashboard Activity Log ===== */
+#activity-log-table { table-layout: fixed; width: 100%; }
+#activity-log-table td, #activity-log-table th {
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    padding: 0.35rem 0.5rem;
+}
+#activity-log-table td.scroll-text:hover {
+    overflow: visible;
+}
+#activity-log-table td.scroll-text:hover span {
+    display: inline-block;
+    animation: marquee 4s linear infinite;
+}
+@keyframes marquee {
+    0% { transform: translateX(0); }
+    100% { transform: translateX(-50%); }
+}
+
+/* ===== History Page ===== */
+.resizable-table th { resize: horizontal; overflow: auto; min-width: 60px; }
+.resizable-table td { word-break: break-word; }
+
+/* ===== Library Page ===== */
+.filter-chip {
+    display: inline-flex;
+    align-items: center;
+    padding: var(--space-sm) var(--space-md);
+    margin: var(--space-xs);
+    border-radius: 20px;
+    background: var(--theme-bg-header);
+    border: 1px solid var(--theme-border-accent);
+    color: #eee;
+    cursor: pointer;
+    transition: all var(--transition-fast);
+    text-decoration: none;
+}
+.filter-chip:hover {
+    background: rgba(0, 217, 255, 0.2);
+    border-color: rgba(0, 217, 255, 0.5);
+    color: #fff;
+}
+.filter-chip.active {
+    background: rgba(0, 217, 255, 0.3);
+    border-color: var(--theme-accent-secondary);
+    color: var(--theme-accent-secondary);
+}
+.filter-chip .count {
+    background: rgba(0, 0, 0, 0.3);
+    padding: 2px 8px;
+    border-radius: 10px;
+    margin-left: 8px;
+    font-size: 0.85rem;
+}
+.filter-chip.active .count {
+    background: rgba(0, 217, 255, 0.3);
+}
+.filter-chip.has-items .count {
+    background: rgba(233, 69, 96, 0.5);
+}
+.activity-stream {
+    max-height: 150px;
+    overflow-y: auto;
+    background: rgba(0, 0, 0, 0.2);
+    border-radius: var(--radius-md);
+    padding: 10px;
+    font-family: monospace;
+    font-size: 0.85rem;
+    display: none;
+}
+.activity-stream.active {
+    display: block;
+}
+.activity-stream .entry {
+    padding: 2px 0;
+    border-bottom: 1px solid rgba(255,255,255,0.05);
+}
+.activity-stream .entry.success { color: var(--theme-accent-secondary); }
+.activity-stream .entry.error { color: var(--theme-accent-primary); }
+.activity-stream .entry.info { color: var(--theme-accent-warning); }
+.item-row {
+    transition: background var(--transition-fast);
+}
+.item-row:hover {
+    background: rgba(0, 217, 255, 0.05);
+}
+.status-badge {
+    font-size: 0.75rem;
+    padding: 3px 8px;
+}
+.action-btn {
+    padding: 2px 8px;
+    font-size: 0.8rem;
+}
+/* Issue #111: Sortable column headers */
+th[onclick]:hover {
+    color: var(--theme-accent-secondary);
+}
+.sort-icon {
+    font-size: 0.7rem;
+    opacity: 0.5;
+}
+.sort-icon.active {
+    opacity: 1;
+    color: var(--theme-accent-secondary);
+}
+
+/* ===== Setup Wizard ===== */
+.setup-container {
+    max-width: 700px;
+    margin: 0 auto;
+}
+.step-indicators {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    margin-bottom: 2rem;
+    flex-wrap: wrap;
+    gap: 5px;
+}
+.step-indicator {
+    width: 40px;
+    height: 40px;
+    border-radius: 50%;
+    background: var(--theme-bg-secondary);
+    border: 2px solid var(--theme-border-primary);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-weight: bold;
+    color: #888;
+    transition: all 0.3s ease;
+}
+.step-indicator.active {
+    background: var(--theme-accent-primary);
+    border-color: var(--theme-accent-primary);
+    color: #fff;
+    transform: scale(1.1);
+}
+.step-indicator.completed {
+    background: var(--theme-accent-secondary);
+    border-color: var(--theme-accent-secondary);
+    color: #000;
+}
+.step-line {
+    width: 40px;
+    height: 2px;
+    background: var(--theme-border-primary);
+    transition: background 0.3s ease;
+}
+.step-line.completed {
+    background: var(--theme-accent-secondary);
+}
+.setup-step {
+    animation: fadeIn 0.3s ease;
+}
+.setup-card {
+    background: var(--theme-bg-card);
+    border: 1px solid var(--theme-border-accent);
+    border-radius: 16px;
+}
+.setup-card .card-body {
+    padding: 2rem;
+}
+.option-card {
+    background: var(--theme-bg-header);
+    border: 2px solid transparent;
+    border-radius: var(--radius-lg);
+    padding: var(--space-md);
+    cursor: pointer;
+    transition: all var(--transition-fast);
+}
+.option-card:hover {
+    border-color: rgba(0, 217, 255, 0.5);
+    background: rgba(15, 52, 96, 0.8);
+}
+.option-card.selected {
+    border-color: var(--theme-accent-secondary);
+    background: rgba(0, 217, 255, 0.1);
+}
+.option-card input[type="radio"] {
+    display: none;
+}
+.path-item {
+    background: var(--theme-bg-header);
+    border-radius: var(--radius-md);
+    padding: 0.75rem 1rem;
+    margin-bottom: var(--space-sm);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+}
+.path-item.valid {
+    border-left: 3px solid var(--theme-accent-secondary);
+}
+.path-item.invalid {
+    border-left: 3px solid var(--theme-accent-primary);
+}
+.btn-nav {
+    min-width: 120px;
+}
+.feature-icon {
+    font-size: 2.5rem;
+    margin-bottom: var(--space-md);
+}
+.summary-item {
+    background: rgba(15, 52, 96, 0.3);
+    border-radius: var(--radius-md);
+    padding: var(--space-md);
+    margin-bottom: 0.75rem;
+}
+.summary-item .label {
+    color: var(--theme-text-secondary);
+    font-size: 0.85rem;
+}
+.summary-item .value {
+    font-weight: 600;
+    color: var(--theme-accent-secondary);
+}
+.setup-header {
+    text-align: center;
+    margin-bottom: var(--space-md);
+    padding-top: var(--space-md);
+}
+.setup-header h1 {
+    font-size: 1.5rem;
+    color: var(--theme-accent-secondary);
+}
+/* Hide navbar during setup wizard - the setup_wizard.html template adds this class */
+.setup-mode .navbar,
+.setup-mode .status-bar {
+    display: none !important;
+}
+
+/* ===== Utility Classes ===== */
+.fs-icon-lg {
+    font-size: 2rem;
+}
+.fs-icon-xl {
+    font-size: 4rem;
+}
+.scroll-container {
+    max-height: 300px;
+    overflow-y: auto;
+}
+.scroll-container-sm {
+    max-height: 150px;
+    overflow-y: auto;
+}
+.cursor-pointer {
+    cursor: pointer;
+}
+
+/* ===== Table Container ===== */
+.table-container {
+    border-radius: var(--radius-md);
+    overflow: hidden;
+    border: 1px solid var(--theme-border-primary);
+}
+
+/* ===== Settings Save Bar ===== */
+.settings-save-bar {
+    position: sticky;
+    bottom: 0;
+    background: var(--theme-bg-secondary);
+    border-top: 1px solid var(--theme-border-primary);
+    padding: var(--space-md);
+    z-index: 100;
+    backdrop-filter: blur(10px);
+}
+
+/* ===== Spin Icon Animation ===== */
+.spin-icon {
+    animation: spin-anim 1s linear infinite;
+}
+@keyframes spin-anim {
+    100% { transform: rotate(360deg); }
+}
+
+/* ===== Toast Notification ===== */
+.toast-notification {
+    position: fixed;
+    top: 20px;
+    right: 20px;
+    z-index: 9999;
+    padding: 12px 20px;
+    border-radius: var(--radius-md);
+    color: #fff;
+    font-size: 0.9rem;
+    opacity: 0;
+    transition: opacity 0.3s;
+}
+
+/* ===== Mobile Responsive ===== */
+@media (max-width: 768px) {
+    .stat-card .stat-number { font-size: 1.5rem; }
+    .nav-tabs { flex-wrap: nowrap; overflow-x: auto; }
+    .nav-tabs .nav-link { white-space: nowrap; font-size: 0.85rem; padding: 0.4rem 0.75rem; }
+    .table { font-size: 0.85rem; }
+    .card-body { padding: 0.75rem; }
+    .status-bar-content {
+        flex-direction: column;
+        align-items: flex-start;
+    }
+    .status-meta {
+        width: 100%;
+        justify-content: space-around;
+        padding-top: 8px;
+        border-top: 1px solid rgba(255, 255, 255, 0.1);
+        margin-top: 4px;
+    }
+    .status-stat {
+        border-left: none;
+    }
+}
+@media (max-width: 576px) {
+    .container { padding-left: 0.5rem; padding-right: 0.5rem; }
+    .modal-dialog { margin: 0.5rem; }
+    h2 { font-size: 1.3rem; }
+}
diff --git a/static/js/common.js b/static/js/common.js
new file mode 100644
index 0000000..fb38a37
--- /dev/null
+++ b/static/js/common.js
@@ -0,0 +1,41 @@
+/**
+ * Common utility functions shared across all templates.
+ * Loaded via base.html before page-specific scripts.
+ */
+
+/**
+ * Escape HTML entities to prevent XSS.
+ * @param {string} text - Raw text to escape
+ * @returns {string} HTML-safe string
+ */
+function escapeHtml(text) {
+    if (text === null || text === undefined) return '';
+    var div = document.createElement('div');
+    div.textContent = String(text);
+    return div.innerHTML;
+}
+
+/**
+ * Show a toast notification.
+ * @param {string} message - Message to display
+ * @param {string} [type='info'] - One of: success, danger, info, warning
+ */
+function showToast(message, type) {
+    type = type || 'info';
+    var colors = {
+        success: 'var(--theme-accent-success)',
+        danger: 'var(--theme-accent-primary)',
+        info: 'var(--theme-accent-secondary)',
+        warning: 'var(--theme-accent-warning)'
+    };
+    var toast = document.createElement('div');
+    toast.className = 'toast-notification';
+    toast.style.background = colors[type] || colors.info;
+    toast.textContent = message;
+    document.body.appendChild(toast);
+    requestAnimationFrame(function() { toast.style.opacity = '1'; });
+    setTimeout(function() {
+        toast.style.opacity = '0';
+        setTimeout(function() { toast.remove(); }, 300);
+    }, 3000);
+}
diff --git a/templates/base.html b/templates/base.html
index 546b1a0..8e31220 100644
--- a/templates/base.html
+++ b/templates/base.html
@@ -20,735 +20,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Cinzel:wght@400;600;700&family=Inter:wght@400;500;600&display=swap" rel="stylesheet">
-    <style>
-        /* ===== THEME SYSTEM - CSS Variables ===== */
-        :root,
-        [data-theme="default"] {
-            /* Background colors */
-            --theme-bg-primary: #1a1a2e;
-            --theme-bg-secondary: #16213e;
-            --theme-bg-card: rgba(22, 33, 62, 0.8);
-            --theme-bg-navbar: rgba(15, 52, 96, 0.9);
-            --theme-bg-header: rgba(15, 52, 96, 0.5);
-            /* Accent colors */
-            --theme-accent-primary: #e94560;
-            --theme-accent-primary-hover: #d63d56;
-            --theme-accent-secondary: #00d9ff;
-            --theme-accent-warning: #ffc107;
-            --theme-accent-success: #00ff00;
-            /* Text colors */
-            --theme-text-primary: #eee;
-            --theme-text-secondary: rgba(255, 255, 255, 0.6);
-            --theme-text-link: #00d9ff;
-            /* Border colors */
-            --theme-border-primary: rgba(15, 52, 96, 0.5);
-            --theme-border-accent: rgba(0, 217, 255, 0.3);
-            /* Gradients */
-            --theme-gradient-bg: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
-            --theme-gradient-stat: linear-gradient(45deg, #e94560, #00d9ff);
-            --theme-gradient-progress: linear-gradient(90deg, #e94560, #00d9ff);
-            /* Fonts - Bootstrap system default */
-            --theme-font-heading: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-            --theme-font-body: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-            /* Shadows */
-            --theme-shadow-glow: rgba(0, 217, 255, 0.1);
-            --theme-shadow-card: rgba(0, 0, 0, 0.5);
-        }
-
-        /* ===== SKALDLEITA THEME - Norse Gold ===== */
-        [data-theme="skaldleita"] {
-            /* Background colors - darker, more dramatic */
-            --theme-bg-primary: #0a0c10;
-            --theme-bg-secondary: #12151c;
-            --theme-bg-card: rgba(18, 21, 28, 0.9);
-            --theme-bg-navbar: rgba(26, 30, 40, 0.95);
-            --theme-bg-header: rgba(26, 30, 40, 0.7);
-            /* Accent colors - gold and ice blue */
-            --theme-accent-primary: #c9a55c;
-            --theme-accent-primary-hover: #e8c87d;
-            --theme-accent-secondary: #7eb8da;
-            --theme-accent-warning: #c9a55c;
-            --theme-accent-success: #7eb8da;
-            /* Text colors */
-            --theme-text-primary: #e8e6e3;
-            --theme-text-secondary: #9ca3af;
-            --theme-text-link: #c9a55c;
-            /* Border colors */
-            --theme-border-primary: rgba(201, 165, 92, 0.2);
-            --theme-border-accent: rgba(201, 165, 92, 0.4);
-            /* Gradients */
-            --theme-gradient-bg: linear-gradient(135deg, #0a0c10 0%, #12151c 100%);
-            --theme-gradient-stat: linear-gradient(45deg, #c9a55c, #7eb8da);
-            --theme-gradient-progress: linear-gradient(90deg, #c9a55c, #7eb8da);
-            /* Fonts - Norse-inspired */
-            --theme-font-heading: 'Cinzel', serif;
-            --theme-font-body: 'Inter', sans-serif;
-            /* Shadows - warmer glow */
-            --theme-shadow-glow: rgba(201, 165, 92, 0.15);
-            --theme-shadow-card: rgba(0, 0, 0, 0.6);
-        }
-
-        /* ===== Apply theme variables ===== */
-        :root {
-            --bs-body-bg: var(--theme-bg-primary);
-            --bs-body-color: var(--theme-text-primary);
-            --bs-card-bg: var(--theme-bg-card);
-            --bs-border-color: var(--theme-border-primary);
-        }
-        body {
-            background: var(--theme-gradient-bg);
-            min-height: 100vh;
-            font-family: var(--theme-font-body);
-            color: var(--theme-text-primary);
-        }
-        h1, h2, h3, h4, h5, h6, .navbar-brand {
-            font-family: var(--theme-font-heading);
-        }
-        .navbar {
-            background: var(--theme-bg-navbar) !important;
-            backdrop-filter: blur(10px);
-        }
-        .card {
-            background: var(--theme-bg-card);
-            border: 1px solid var(--theme-border-primary);
-            border-radius: 12px;
-        }
-        .card-header {
-            background: var(--theme-bg-header);
-            border-bottom: 1px solid var(--theme-border-primary);
-        }
-        .table {
-            --bs-table-bg: transparent;
-            --bs-table-color: var(--theme-text-primary);
-        }
-        .btn-primary {
-            background: var(--theme-accent-primary);
-            border-color: var(--theme-accent-primary);
-        }
-        .btn-primary:hover {
-            background: var(--theme-accent-primary-hover);
-            border-color: var(--theme-accent-primary-hover);
-        }
-        .btn-success {
-            background: var(--theme-accent-secondary);
-            border-color: var(--theme-accent-secondary);
-            color: #000;
-        }
-        .stat-card {
-            transition: transform 0.2s;
-        }
-        .stat-card:hover {
-            transform: translateY(-5px);
-        }
-        .stat-number {
-            font-size: 2.5rem;
-            font-weight: bold;
-            background: var(--theme-gradient-stat);
-            -webkit-background-clip: text;
-            -webkit-text-fill-color: transparent;
-        }
-        .badge-fix {
-            background: var(--theme-accent-primary);
-        }
-        .badge-ok {
-            background: var(--theme-accent-secondary);
-            color: #000;
-        }
-        .badge-pending {
-            background: var(--theme-accent-warning);
-            color: #000;
-        }
-        .status-indicator {
-            display: inline-block;
-            width: 10px;
-            height: 10px;
-            border-radius: 50%;
-            margin-right: 8px;
-        }
-        .status-running {
-            background: var(--theme-accent-success);
-            box-shadow: 0 0 10px var(--theme-accent-success);
-            animation: pulse 2s infinite;
-        }
-        .status-stopped {
-            background: #ff0000;
-        }
-        @keyframes pulse {
-            0%, 100% { opacity: 1; }
-            50% { opacity: 0.5; }
-        }
-        .nav-link {
-            color: rgba(255,255,255,0.8) !important;
-        }
-        .nav-link:hover, .nav-link.active {
-            color: var(--theme-text-link) !important;
-        }
-        .text-muted {
-            color: var(--theme-text-secondary) !important;
-        }
-        /* ===== SKALDLEITA THEME - Comprehensive Color Overrides ===== */
-        /* All Bootstrap text utilities -> Gold */
-        [data-theme="skaldleita"] .text-primary,
-        [data-theme="skaldleita"] .text-info,
-        [data-theme="skaldleita"] .text-success,
-        [data-theme="skaldleita"] .text-warning,
-        [data-theme="skaldleita"] .text-danger {
-            color: #c9a55c !important; /* ALL accent colors become gold */
-        }
-        [data-theme="skaldleita"] .text-secondary {
-            color: #8b7340 !important; /* Dim gold for secondary */
-        }
-        /* ALL icons become gold */
-        [data-theme="skaldleita"] i.bi,
-        [data-theme="skaldleita"] .bi {
-            color: #c9a55c !important;
-        }
-        /* Headings get gold accent */
-        [data-theme="skaldleita"] h1,
-        [data-theme="skaldleita"] h2,
-        [data-theme="skaldleita"] h3,
-        [data-theme="skaldleita"] h4,
-        [data-theme="skaldleita"] h5,
-        [data-theme="skaldleita"] .card-header {
-            color: #c9a55c !important;
-        }
-        /* Card header text */
-        [data-theme="skaldleita"] .card-header * {
-            color: #c9a55c !important;
-        }
-        /* Navbar brand gold */
-        [data-theme="skaldleita"] .navbar-brand {
-            color: #c9a55c !important;
-        }
-        /* Links gold */
-        [data-theme="skaldleita"] a {
-            color: #c9a55c !important;
-        }
-        [data-theme="skaldleita"] a:hover {
-            color: #e8c87d !important; /* Brighter gold on hover */
-        }
-        /* Nav links */
-        [data-theme="skaldleita"] .nav-link {
-            color: #9ca3af !important; /* Gray when inactive */
-        }
-        [data-theme="skaldleita"] .nav-link:hover,
-        [data-theme="skaldleita"] .nav-link.active {
-            color: #c9a55c !important; /* Gold when active/hover */
-        }
-        /* Background colors - all use gold */
-        [data-theme="skaldleita"] .bg-primary,
-        [data-theme="skaldleita"] .bg-info,
-        [data-theme="skaldleita"] .bg-success,
-        [data-theme="skaldleita"] .bg-warning,
-        [data-theme="skaldleita"] .bg-danger {
-            background-color: #c9a55c !important;
-            color: #0a0c10 !important; /* Dark text on gold bg */
-        }
-        /* Badges - gold with dark text */
-        [data-theme="skaldleita"] .badge {
-            background-color: #c9a55c !important;
-            color: #0a0c10 !important;
-            font-weight: 500;
-        }
-        /* Buttons */
-        [data-theme="skaldleita"] .btn-primary,
-        [data-theme="skaldleita"] .btn-success,
-        [data-theme="skaldleita"] .btn-info {
-            background-color: #c9a55c !important;
-            border-color: #c9a55c !important;
-            color: #0a0c10 !important;
-        }
-        [data-theme="skaldleita"] .btn-primary:hover,
-        [data-theme="skaldleita"] .btn-success:hover,
-        [data-theme="skaldleita"] .btn-info:hover {
-            background-color: #e8c87d !important;
-            border-color: #e8c87d !important;
-        }
-        [data-theme="skaldleita"] .btn-outline-primary,
-        [data-theme="skaldleita"] .btn-outline-success,
-        [data-theme="skaldleita"] .btn-outline-info,
-        [data-theme="skaldleita"] .btn-outline-secondary,
-        [data-theme="skaldleita"] .btn-outline-warning {
-            color: #c9a55c !important;
-            border-color: #c9a55c !important;
-        }
-        [data-theme="skaldleita"] .btn-outline-primary:hover,
-        [data-theme="skaldleita"] .btn-outline-success:hover,
-        [data-theme="skaldleita"] .btn-outline-info:hover,
-        [data-theme="skaldleita"] .btn-outline-secondary:hover,
-        [data-theme="skaldleita"] .btn-outline-warning:hover {
-            background-color: #c9a55c !important;
-            color: #0a0c10 !important;
-        }
-        /* Status bar elements */
-        [data-theme="skaldleita"] .status-book,
-        [data-theme="skaldleita"] .status-author {
-            color: #c9a55c !important;
-        }
-        [data-theme="skaldleita"] .status-layer {
-            background: rgba(201, 165, 92, 0.2) !important;
-            color: #c9a55c !important;
-        }
-        [data-theme="skaldleita"] .status-stat-value {
-            color: #c9a55c !important;
-        }
-        /* Stat numbers gradient -> solid gold */
-        [data-theme="skaldleita"] .stat-number {
-            background: none !important;
-            -webkit-background-clip: unset !important;
-            -webkit-text-fill-color: #c9a55c !important;
-            color: #c9a55c !important;
-        }
-        /* Form focus states */
-        [data-theme="skaldleita"] .form-control:focus,
-        [data-theme="skaldleita"] .form-select:focus {
-            border-color: #c9a55c !important;
-            box-shadow: 0 0 0 0.2rem rgba(201, 165, 92, 0.25) !important;
-        }
-        [data-theme="skaldleita"] .form-check-input:checked {
-            background-color: #c9a55c !important;
-            border-color: #c9a55c !important;
-        }
-        /* Gold borders around elements */
-        [data-theme="skaldleita"] .card {
-            border: 1px solid rgba(201, 165, 92, 0.3) !important;
-        }
-        [data-theme="skaldleita"] .card-header {
-            border-bottom: 1px solid rgba(201, 165, 92, 0.3) !important;
-        }
-        [data-theme="skaldleita"] .form-control,
-        [data-theme="skaldleita"] .form-select {
-            border-color: rgba(201, 165, 92, 0.3) !important;
-        }
-        [data-theme="skaldleita"] .table {
-            border-color: rgba(201, 165, 92, 0.2) !important;
-        }
-        [data-theme="skaldleita"] .table > :not(caption) > * > * {
-            border-color: rgba(201, 165, 92, 0.15) !important;
-        }
-        [data-theme="skaldleita"] .navbar {
-            border-bottom: 1px solid rgba(201, 165, 92, 0.2) !important;
-        }
-        [data-theme="skaldleita"] .status-bar {
-            border-bottom: 1px solid rgba(201, 165, 92, 0.3) !important;
-        }
-        [data-theme="skaldleita"] .alert {
-            border-color: rgba(201, 165, 92, 0.3) !important;
-        }
-        [data-theme="skaldleita"] .list-group-item {
-            border-color: rgba(201, 165, 92, 0.2) !important;
-        }
-        [data-theme="skaldleita"] hr {
-            border-color: rgba(201, 165, 92, 0.2) !important;
-            opacity: 1;
-        }
-        [data-theme="skaldleita"] .modal-content {
-            border: 1px solid rgba(201, 165, 92, 0.3) !important;
-        }
-        [data-theme="skaldleita"] .dropdown-menu {
-            border: 1px solid rgba(201, 165, 92, 0.3) !important;
-        }
-        /* Skaldleita-specific: rune divider */
-        [data-theme="skaldleita"] .rune-divider {
-            text-align: center;
-            color: var(--theme-accent-primary);
-            opacity: 0.3;
-            font-size: 0.8rem;
-            letter-spacing: 0.5em;
-            margin: 1rem 0;
-        }
-        [data-theme="skaldleita"] .rune-divider::before {
-            content: "ᚠ ᚢ ᚦ ᚨ ᚱ ᚲ";
-        }
-        /* Theme-aware form controls */
-        .form-select, .form-control {
-            transition: border-color 0.2s, box-shadow 0.2s;
-        }
-        .form-select:focus, .form-control:focus {
-            border-color: var(--theme-accent-primary);
-            box-shadow: 0 0 0 0.2rem rgba(var(--theme-accent-primary-rgb, 233, 69, 96), 0.25);
-        }
-        .form-check-input:checked {
-            background-color: var(--theme-accent-primary);
-            border-color: var(--theme-accent-primary);
-        }
-        /* Theme-aware links */
-        a {
-            color: var(--theme-text-link);
-        }
-        a:hover {
-            color: var(--theme-accent-primary-hover);
-        }
-        /* Alert styling */
-        .alert-dark {
-            background: var(--theme-bg-card);
-            border-color: var(--theme-border-primary);
-            color: var(--theme-text-primary);
-        }
-        /* Skaldleita theme enhancements */
-        [data-theme="skaldleita"] .navbar-brand {
-            font-weight: 600;
-            letter-spacing: 0.05em;
-        }
-        [data-theme="skaldleita"] .card-header {
-            font-family: var(--theme-font-heading);
-            font-weight: 500;
-            letter-spacing: 0.02em;
-        }
-
-        /* ===== Book Info Card (Hover Preview) ===== */
-        .book-hover-card {
-            position: absolute;
-            z-index: 1000;
-            width: 380px;
-            background: var(--theme-gradient-bg);
-            border: 1px solid var(--theme-border-accent);
-            border-radius: 12px;
-            box-shadow: 0 8px 32px var(--theme-shadow-card), 0 0 20px var(--theme-shadow-glow);
-            padding: 0;
-            display: none;
-            overflow: hidden;
-        }
-        .book-hover-card.show {
-            display: block;
-            animation: fadeIn 0.2s ease;
-        }
-        @keyframes fadeIn {
-            from { opacity: 0; transform: translateY(-10px); }
-            to { opacity: 1; transform: translateY(0); }
-        }
-        .book-hover-card .card-header {
-            background: rgba(var(--theme-accent-secondary-rgb, 0, 217, 255), 0.1);
-            padding: 12px 15px;
-            border-bottom: 1px solid var(--theme-border-accent);
-        }
-        .book-hover-card .card-body {
-            padding: 15px;
-        }
-        .book-hover-card .card-header .d-flex {
-            min-width: 0;
-        }
-        .book-hover-card #hover-cover-container {
-            flex-shrink: 0;
-        }
-        .book-hover-card .card-header .flex-grow-1 {
-            min-width: 0;
-            overflow: hidden;
-        }
-        .book-hover-card .book-cover {
-            width: 80px;
-            height: 120px;
-            object-fit: cover;
-            border-radius: 6px;
-            border: 2px solid var(--theme-border-accent);
-            background: rgba(0, 0, 0, 0.3);
-        }
-        .book-hover-card .book-cover-placeholder {
-            width: 80px;
-            height: 120px;
-            background: var(--theme-bg-header);
-            border-radius: 6px;
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            color: rgba(255,255,255,0.3);
-            font-size: 2rem;
-        }
-        .book-hover-card .book-author,
-        .book-hover-card .book-series {
-            overflow: hidden;
-            text-overflow: ellipsis;
-            white-space: nowrap;
-        }
-        .book-hover-card .book-title {
-            font-size: 1.1rem;
-            font-weight: 600;
-            color: var(--theme-text-primary);
-            margin-bottom: 4px;
-            overflow: hidden;
-            text-overflow: ellipsis;
-            display: -webkit-box;
-            -webkit-line-clamp: 2;
-            -webkit-box-orient: vertical;
-        }
-        .book-hover-card .book-author {
-            color: var(--theme-accent-secondary);
-            font-size: 0.9rem;
-        }
-        .book-hover-card .book-series {
-            color: var(--theme-accent-warning);
-            font-size: 0.85rem;
-        }
-        .book-hover-card .book-meta {
-            font-size: 0.8rem;
-            color: var(--theme-text-secondary);
-        }
-        .book-hover-card .book-description {
-            font-size: 0.85rem;
-            color: rgba(255,255,255,0.8);
-            max-height: 80px;
-            overflow: hidden;
-            text-overflow: ellipsis;
-            line-height: 1.4;
-        }
-        .book-hover-card .book-tags {
-            display: flex;
-            flex-wrap: wrap;
-            gap: 4px;
-        }
-        .book-hover-card .book-tag {
-            font-size: 0.7rem;
-            padding: 2px 8px;
-            border-radius: 10px;
-            background: rgba(var(--theme-accent-secondary-rgb, 0, 217, 255), 0.15);
-            color: var(--theme-accent-secondary);
-        }
-        .book-hover-card .abs-status {
-            background: rgba(0,0,0,0.2);
-            border-radius: 8px;
-            padding: 10px;
-            margin-top: 10px;
-        }
-        .book-hover-card .abs-user {
-            display: flex;
-            align-items: center;
-            gap: 8px;
-            font-size: 0.85rem;
-            padding: 4px 0;
-        }
-        .book-hover-card .abs-user .progress {
-            flex: 1;
-            height: 6px;
-        }
-        .book-hover-card .click-hint {
-            text-align: center;
-            font-size: 0.75rem;
-            color: rgba(255,255,255,0.4);
-            padding: 8px;
-            border-top: 1px solid var(--theme-border-accent);
-        }
-
-        /* ===== Search Result Cover Thumbnails ===== */
-        .search-cover-container {
-            flex-shrink: 0;
-            width: 40px;
-            height: 60px;
-        }
-        .search-result-cover {
-            width: 40px;
-            height: 60px;
-            object-fit: cover;
-            border-radius: 4px;
-            border: 1px solid var(--theme-border-accent);
-        }
-        .search-cover-placeholder {
-            width: 40px;
-            height: 60px;
-            background: var(--theme-bg-header);
-            border-radius: 4px;
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            color: rgba(255,255,255,0.3);
-            font-size: 1.2rem;
-        }
-        .search-result-item {
-            border-color: var(--theme-border-primary) !important;
-        }
-        .search-result-item:hover {
-            background: var(--theme-bg-header) !important;
-            border-color: var(--theme-border-accent) !important;
-        }
-
-        /* ===== Live Status Bar ===== */
-        .status-bar {
-            background: var(--theme-bg-navbar);
-            border-bottom: 1px solid var(--theme-border-accent);
-            padding: 8px 0;
-            margin-bottom: 1rem;
-            backdrop-filter: blur(10px);
-            transition: all 0.3s ease;
-        }
-        .status-bar.processing {
-            border-bottom-color: var(--theme-accent-primary);
-        }
-        .status-bar.idle {
-            opacity: 0.7;
-        }
-        .status-bar.idle:hover {
-            opacity: 1;
-        }
-        .status-bar-content {
-            display: flex;
-            align-items: center;
-            justify-content: space-between;
-            flex-wrap: wrap;
-            gap: 10px;
-        }
-        .status-main {
-            display: flex;
-            align-items: center;
-            gap: 12px;
-            flex: 1;
-            min-width: 0;
-        }
-        .status-icon {
-            font-size: 1.2rem;
-            width: 28px;
-            text-align: center;
-        }
-        .status-icon.processing {
-            color: var(--theme-accent-primary);
-            animation: pulse-icon 1.5s ease-in-out infinite;
-        }
-        .status-icon.idle {
-            color: var(--theme-accent-secondary);
-        }
-        .status-icon.stopped {
-            color: #6c757d;
-        }
-        @keyframes pulse-icon {
-            0%, 100% { opacity: 1; transform: scale(1); }
-            50% { opacity: 0.6; transform: scale(0.95); }
-        }
-        .status-text {
-            display: flex;
-            flex-direction: column;
-            min-width: 0;
-            flex: 1;
-        }
-        .status-primary {
-            font-size: 0.9rem;
-            font-weight: 500;
-            color: var(--theme-text-primary);
-            white-space: nowrap;
-            overflow: hidden;
-            text-overflow: ellipsis;
-        }
-        .status-secondary {
-            font-size: 0.75rem;
-            color: var(--theme-text-secondary);
-            white-space: nowrap;
-            overflow: hidden;
-            text-overflow: ellipsis;
-        }
-        .status-book {
-            color: var(--theme-accent-secondary);
-            font-weight: 500;
-        }
-        .status-author {
-            color: var(--theme-accent-warning);
-        }
-        .status-layer {
-            display: inline-flex;
-            align-items: center;
-            gap: 4px;
-            background: rgba(var(--theme-accent-primary-rgb, 233, 69, 96), 0.2);
-            color: var(--theme-accent-primary);
-            padding: 2px 8px;
-            border-radius: 10px;
-            font-size: 0.7rem;
-            font-weight: 600;
-            text-transform: uppercase;
-        }
-        .status-provider {
-            display: inline-flex;
-            align-items: center;
-            gap: 6px;
-            margin-left: 8px;
-        }
-        .provider-badge {
-            display: inline-flex;
-            align-items: center;
-            gap: 4px;
-            background: rgba(0, 200, 150, 0.2);
-            color: #00c896;
-            padding: 2px 8px;
-            border-radius: 10px;
-            font-size: 0.7rem;
-            font-weight: 600;
-        }
-        .provider-badge.paid {
-            background: rgba(255, 193, 7, 0.2);
-            color: #ffc107;
-        }
-        .provider-free-badge {
-            display: inline-flex;
-            align-items: center;
-            gap: 3px;
-            background: rgba(0, 200, 150, 0.15);
-            color: #00c896;
-            padding: 2px 6px;
-            border-radius: 8px;
-            font-size: 0.6rem;
-            font-weight: 700;
-            text-transform: uppercase;
-        }
-        .status-step {
-            color: var(--theme-text-tertiary);
-            font-size: 0.75rem;
-            margin-left: 8px;
-            font-style: italic;
-        }
-        .status-meta {
-            display: flex;
-            align-items: center;
-            gap: 15px;
-            flex-shrink: 0;
-        }
-        .status-stat {
-            display: flex;
-            flex-direction: column;
-            align-items: center;
-            padding: 0 10px;
-            border-left: 1px solid rgba(255, 255, 255, 0.1);
-        }
-        .status-stat:first-child {
-            border-left: none;
-        }
-        .status-stat-value {
-            font-size: 1rem;
-            font-weight: 600;
-            color: var(--theme-accent-secondary);
-            line-height: 1;
-        }
-        .status-stat-label {
-            font-size: 0.65rem;
-            color: var(--theme-text-secondary);
-            text-transform: uppercase;
-        }
-        .status-progress {
-            height: 3px;
-            background: rgba(0, 0, 0, 0.3);
-            border-radius: 2px;
-            overflow: hidden;
-            margin-top: 4px;
-            width: 100%;
-            max-width: 200px;
-        }
-        .status-progress-bar {
-            height: 100%;
-            background: var(--theme-gradient-progress);
-            border-radius: 2px;
-            transition: width 0.5s ease;
-        }
-        @media (max-width: 768px) {
-            .status-bar-content {
-                flex-direction: column;
-                align-items: flex-start;
-            }
-            .status-meta {
-                width: 100%;
-                justify-content: space-around;
-                padding-top: 8px;
-                border-top: 1px solid rgba(255, 255, 255, 0.1);
-                margin-top: 4px;
-            }
-            .status-stat {
-                border-left: none;
-            }
-        }
-    </style>
+    <link rel="stylesheet" href="/static/css/style.css">
 </head>
 <body>
     <nav class="navbar navbar-expand-lg navbar-dark mb-4">
@@ -863,8 +135,8 @@
     <!-- Update Modal -->
     <div class="modal fade" id="updateModal" tabindex="-1">
         <div class="modal-dialog">
-            <div class="modal-content" style="background: #16213e; color: #eee;">
-                <div class="modal-header" style="border-color: #0f3460;">
+            <div class="modal-content" style="background: var(--theme-bg-secondary); color: var(--theme-text-primary);">
+                <div class="modal-header" style="border-color: var(--theme-border-primary);">
                     <h5 class="modal-title"><i class="bi bi-arrow-up-circle text-success"></i> Update Available</h5>
                     <button type="button" class="btn-close btn-close-white" data-bs-dismiss="modal"></button>
                 </div>
@@ -875,7 +147,7 @@ <h5 class="modal-title"><i class="bi bi-arrow-up-circle text-success"></i> Updat
                     <div id="release-notes" class="mt-3 p-2" style="background: rgba(0,0,0,0.2); border-radius: 8px; max-height: 200px; overflow-y: auto;">
                     </div>
                 </div>
-                <div class="modal-footer" style="border-color: #0f3460;">
+                <div class="modal-footer" style="border-color: var(--theme-border-primary);">
                     <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Later</button>
                     <a id="release-link" href="#" target="_blank" class="btn btn-outline-light">
                         <i class="bi bi-github"></i> View Release
@@ -986,6 +258,7 @@ <h5 class="modal-title"><i class="bi bi-exclamation-triangle text-warning"></i>
     </div>
 
     <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
+    <script src="/static/js/common.js"></script>
     <script>
         let updateData = null;
 
@@ -1164,11 +437,7 @@ <h5 class="modal-title"><i class="bi bi-exclamation-triangle text-warning"></i>
                 });
         }
 
-        function escapeHtml(text) {
-            const div = document.createElement('div');
-            div.textContent = text;
-            return div.innerHTML;
-        }
+        // escapeHtml is provided by common.js
 
         // Start status polling
         updateLiveStatus();
diff --git a/templates/dashboard.html b/templates/dashboard.html
index 709d133..500bcec 100644
--- a/templates/dashboard.html
+++ b/templates/dashboard.html
@@ -6,7 +6,7 @@
     <div class="col-md-3">
         <div class="card stat-card h-100" title="{{ _('All audiobook folders found in your library') }}">
             <div class="card-body text-center">
-                <i class="bi bi-collection text-info" style="font-size: 2rem;"></i>
+                <i class="bi bi-collection text-info fs-icon-lg"></i>
                 <div class="stat-number" id="total-books">{{ total_books }}</div>
                 <div class="text-muted">{{ _('Total Books') }}</div>
                 <small class="text-muted" style="font-size: 0.7rem;">{{ _('in library') }}</small>
@@ -15,9 +15,9 @@
     </div>
     <div class="col-md-3">
         <a href="/queue" class="text-decoration-none">
-            <div class="card stat-card h-100" title="{{ _('Books waiting to be analyzed by AI') }}" style="cursor: pointer;">
+            <div class="card stat-card h-100 cursor-pointer" title="{{ _('Books waiting to be analyzed by AI') }}">
                 <div class="card-body text-center">
-                    <i class="bi bi-list-task text-warning" style="font-size: 2rem;"></i>
+                    <i class="bi bi-list-task text-warning fs-icon-lg"></i>
                     <div class="stat-number" id="queue-count">{{ queue_size }}</div>
                     <div class="text-muted">{{ _('In Queue') }}</div>
                     <small class="text-muted" style="font-size: 0.7rem;">{{ _('awaiting AI analysis') }}</small>
@@ -27,9 +27,9 @@
     </div>
     <div class="col-md-3">
         <a href="/history" class="text-decoration-none">
-            <div class="card stat-card h-100" title="{{ _('Books that have been renamed/corrected') }}" style="cursor: pointer;">
+            <div class="card stat-card h-100 cursor-pointer" title="{{ _('Books that have been renamed/corrected') }}">
                 <div class="card-body text-center">
-                    <i class="bi bi-check-circle text-success" style="font-size: 2rem;"></i>
+                    <i class="bi bi-check-circle text-success fs-icon-lg"></i>
                     <div class="stat-number" id="fixed-count">{{ fixed_count }}</div>
                     <div class="text-muted">{{ _('Fixed') }}</div>
                     <small class="text-muted" style="font-size: 0.7rem;">{{ _('renamed successfully') }}</small>
@@ -39,9 +39,9 @@
     </div>
     <div class="col-md-3">
         <a href="/history?status=pending" class="text-decoration-none">
-            <div class="card stat-card h-100" title="{{ _('AI suggested fixes waiting to be applied to files') }}" style="cursor: pointer;">
+            <div class="card stat-card h-100 cursor-pointer" title="{{ _('AI suggested fixes waiting to be applied to files') }}">
                 <div class="card-body text-center">
-                    <i class="bi bi-hourglass-split text-danger" style="font-size: 2rem;"></i>
+                    <i class="bi bi-hourglass-split text-danger fs-icon-lg"></i>
                     <div class="stat-number" id="pending-fixes">{{ pending_fixes }}</div>
                     <div class="text-muted">{{ _('Pending Fixes') }}</div>
                     <small class="text-muted" style="font-size: 0.7rem;">{{ _('ready to apply') }}</small>
@@ -114,27 +114,6 @@
 </div>
 
 <!-- Processing Activity Log - Shows ALL recent processing, not just fixes -->
-<style>
-    #activity-log-table { table-layout: fixed; width: 100%; }
-    #activity-log-table td, #activity-log-table th {
-        white-space: nowrap;
-        overflow: hidden;
-        text-overflow: ellipsis;
-        padding: 0.35rem 0.5rem;
-    }
-    /* Marquee scroll on hover for truncated text */
-    #activity-log-table td.scroll-text:hover {
-        overflow: visible;
-    }
-    #activity-log-table td.scroll-text:hover span {
-        display: inline-block;
-        animation: marquee 4s linear infinite;
-    }
-    @keyframes marquee {
-        0% { transform: translateX(0); }
-        100% { transform: translateX(-50%); }
-    }
-</style>
 <div class="row">
     <div class="col-12">
         <div class="card">
@@ -142,8 +121,8 @@
                 <span><i class="bi bi-activity"></i> Processing Activity (Last 15)</span>
                 <small class="text-muted" id="activity-refresh-time">Auto-refreshes</small>
             </div>
-            <div class="card-body p-0" style="max-height: 400px; overflow-y: auto;">
-                <table class="table table-sm mb-0" id="activity-log-table">
+            <div class="card-body p-0 scroll-container" style="max-height: 400px;">
+                <table class="table table-sm table-hover mb-0" id="activity-log-table">
                     <thead style="position: sticky; top: 0; background: rgba(22, 33, 62, 0.95);">
                         <tr>
                             <th style="width: 42px;">Time</th>
@@ -171,9 +150,9 @@
             <div class="card-header">
                 <i class="bi bi-clock-history"></i> Pending Fixes (Last 15)
             </div>
-            <div class="card-body p-0" style="max-height: 300px; overflow-y: auto;">
+            <div class="card-body p-0 scroll-container">
                 {% if recent_history %}
-                <table class="table table-sm mb-0" id="recent-activity-table">
+                <table class="table table-sm table-hover mb-0" id="recent-activity-table">
                     <thead style="position: sticky; top: 0; background: rgba(22, 33, 62, 0.95);">
                         <tr>
                             <th>Date</th>
@@ -512,12 +491,7 @@
     new bootstrap.Toast(toast, {delay: 3000}).show();
 }
 
-function escapeHtml(text) {
-    if (!text) return '';
-    const div = document.createElement('div');
-    div.textContent = text;
-    return div.innerHTML;
-}
+// escapeHtml provided by common.js
 
 // Start auto-refresh immediately and every 5 seconds
 refreshDashboard();
diff --git a/templates/history.html b/templates/history.html
index 17797bc..01e5bfc 100644
--- a/templates/history.html
+++ b/templates/history.html
@@ -57,10 +57,6 @@ <h2>
 </div>
 
 {% if history_items %}
-<style>
-    .resizable-table th { resize: horizontal; overflow: auto; min-width: 60px; }
-    .resizable-table td { word-break: break-word; }
-</style>
 <div class="card">
     <div class="card-body p-0" style="max-height: 700px; overflow: auto;">
         <table class="table table-sm mb-0 resizable-table" style="table-layout: auto;">
@@ -215,7 +211,7 @@ <h2>
 {% else %}
 <div class="card">
     <div class="card-body text-center py-5">
-        <i class="bi bi-journal-x text-muted" style="font-size: 4rem;"></i>
+        <i class="bi bi-journal-x text-muted fs-icon-xl"></i>
         <h4 class="mt-3">No history yet</h4>
         <p class="text-muted">Process the queue to start fixing books.</p>
         <a href="/queue" class="btn btn-primary">View Queue</a>
@@ -497,12 +493,7 @@ <h5 class="modal-title"><i class="bi bi-pencil"></i> Edit Book Metadata</h5>
         .catch(e => alert('Error: ' + e));
 }
 
-function escapeHtml(text) {
-    if (!text) return '';
-    const div = document.createElement('div');
-    div.textContent = text;
-    return div.innerHTML;
-}
+// escapeHtml provided by common.js
 
 // ===== EXISTING FUNCTIONS =====
 function applyFix(historyId) {
diff --git a/templates/hooks_settings.html b/templates/hooks_settings.html
index 6bb1b15..5c44802 100644
--- a/templates/hooks_settings.html
+++ b/templates/hooks_settings.html
@@ -19,7 +19,7 @@
                     <!-- Populated by JS -->
                 </div>
                 <div id="hooks-empty" class="text-center text-muted py-4" style="display: none;">
-                    <i class="bi bi-terminal" style="font-size: 2rem;"></i>
+                    <i class="bi bi-terminal fs-icon-lg"></i>
                     <p class="mt-2 mb-0">No hooks configured</p>
                     <small>Add a hook to run commands or webhooks after books are renamed</small>
                 </div>
diff --git a/templates/library.html b/templates/library.html
index 92ec03f..e327ba7 100644
--- a/templates/library.html
+++ b/templates/library.html
@@ -2,145 +2,6 @@
 {% block title %}Library - Library Manager{% endblock %}
 
 {% block content %}
-<style>
-    .filter-chip {
-        display: inline-flex;
-        align-items: center;
-        padding: 8px 16px;
-        margin: 4px;
-        border-radius: 20px;
-        background: rgba(15, 52, 96, 0.5);
-        border: 1px solid rgba(0, 217, 255, 0.2);
-        color: #eee;
-        cursor: pointer;
-        transition: all 0.2s;
-        text-decoration: none;
-    }
-    .filter-chip:hover {
-        background: rgba(0, 217, 255, 0.2);
-        border-color: rgba(0, 217, 255, 0.5);
-        color: #fff;
-    }
-    .filter-chip.active {
-        background: rgba(0, 217, 255, 0.3);
-        border-color: #00d9ff;
-        color: #00d9ff;
-    }
-    .filter-chip .count {
-        background: rgba(0, 0, 0, 0.3);
-        padding: 2px 8px;
-        border-radius: 10px;
-        margin-left: 8px;
-        font-size: 0.85rem;
-    }
-    .filter-chip.active .count {
-        background: rgba(0, 217, 255, 0.3);
-    }
-    .filter-chip.has-items .count {
-        background: rgba(233, 69, 96, 0.5);
-    }
-    .activity-stream {
-        max-height: 150px;
-        overflow-y: auto;
-        background: rgba(0, 0, 0, 0.2);
-        border-radius: 8px;
-        padding: 10px;
-        font-family: monospace;
-        font-size: 0.85rem;
-        display: none;
-    }
-    .activity-stream.active {
-        display: block;
-    }
-    .activity-stream .entry {
-        padding: 2px 0;
-        border-bottom: 1px solid rgba(255,255,255,0.05);
-    }
-    .activity-stream .entry.success { color: #00d9ff; }
-    .activity-stream .entry.error { color: #e94560; }
-    .activity-stream .entry.info { color: #ffc107; }
-    .item-row {
-        transition: background 0.2s;
-    }
-    .item-row:hover {
-        background: rgba(0, 217, 255, 0.05);
-    }
-    .status-badge {
-        font-size: 0.75rem;
-        padding: 3px 8px;
-    }
-    .action-btn {
-        padding: 2px 8px;
-        font-size: 0.8rem;
-    }
-    /* Issue #111: Sortable column headers */
-    th[onclick]:hover {
-        color: #00d9ff;
-    }
-    .sort-icon {
-        font-size: 0.7rem;
-        opacity: 0.5;
-    }
-    .sort-icon.active {
-        opacity: 1;
-        color: #00d9ff;
-    }
-    .hint-icon {
-        display: inline-flex;
-        align-items: center;
-        justify-content: center;
-        width: 14px;
-        height: 14px;
-        border-radius: 50%;
-        border: 1px solid rgba(0, 217, 255, 0.4);
-        color: rgba(0, 217, 255, 0.6);
-        font-size: 9px;
-        font-weight: bold;
-        font-style: normal;
-        cursor: help;
-        margin-left: 3px;
-        position: relative;
-        vertical-align: middle;
-        line-height: 1;
-    }
-    .hint-icon:hover {
-        border-color: #00d9ff;
-        color: #00d9ff;
-    }
-    .hint-icon .hint-text {
-        display: none;
-        position: absolute;
-        bottom: calc(100% + 8px);
-        left: 50%;
-        transform: translateX(-50%);
-        background: rgba(15, 52, 96, 0.95);
-        border: 1px solid rgba(0, 217, 255, 0.3);
-        color: #eee;
-        padding: 8px 12px;
-        border-radius: 6px;
-        font-size: 0.8rem;
-        font-weight: normal;
-        font-style: normal;
-        line-height: 1.4;
-        white-space: normal;
-        width: 260px;
-        z-index: 1000;
-        box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
-        pointer-events: none;
-    }
-    .hint-icon .hint-text::after {
-        content: '';
-        position: absolute;
-        top: 100%;
-        left: 50%;
-        transform: translateX(-50%);
-        border: 6px solid transparent;
-        border-top-color: rgba(0, 217, 255, 0.3);
-    }
-    .hint-icon:hover .hint-text {
-        display: block;
-    }
-</style>
 
 <!-- Filter Chips -->
 <div class="mb-4">
@@ -306,8 +167,8 @@
 <!-- Orphan Edit Modal -->
 <div class="modal fade" id="orphanModal" tabindex="-1">
     <div class="modal-dialog">
-        <div class="modal-content" style="background: #16213e; color: #eee;">
-            <div class="modal-header" style="border-color: #0f3460;">
+        <div class="modal-content" style="background: var(--theme-bg-secondary); color: var(--theme-text-primary);">
+            <div class="modal-header" style="border-color: var(--theme-border-primary);">
                 <h5 class="modal-title"><i class="bi bi-folder-plus"></i> Organize Orphan Files</h5>
                 <button type="button" class="btn-close btn-close-white" data-bs-dismiss="modal"></button>
             </div>
@@ -327,7 +188,7 @@ <h5 class="modal-title"><i class="bi bi-folder-plus"></i> Organize Orphan Files<
                 <input type="hidden" id="orphan-author-path">
                 <input type="hidden" id="orphan-files-json">
             </div>
-            <div class="modal-footer" style="border-color: #0f3460;">
+            <div class="modal-footer" style="border-color: var(--theme-border-primary);">
                 <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button>
                 <button type="button" class="btn btn-success" onclick="saveOrphan()">
                     <i class="bi bi-folder-plus"></i> Create & Move
diff --git a/templates/orphans.html b/templates/orphans.html
index 335eebf..45e08ea 100644
--- a/templates/orphans.html
+++ b/templates/orphans.html
@@ -53,8 +53,8 @@ <h2><i class="bi bi-file-earmark-music"></i> Orphan Files</h2>
 <!-- Edit Title Modal -->
 <div class="modal fade" id="editModal" tabindex="-1">
     <div class="modal-dialog">
-        <div class="modal-content" style="background: #16213e; color: #eee;">
-            <div class="modal-header" style="border-color: #0f3460;">
+        <div class="modal-content" style="background: var(--theme-bg-secondary); color: var(--theme-text-primary);">
+            <div class="modal-header" style="border-color: var(--theme-border-primary);">
                 <h5 class="modal-title"><i class="bi bi-pencil"></i> Edit Book Title</h5>
                 <button type="button" class="btn-close btn-close-white" data-bs-dismiss="modal"></button>
             </div>
@@ -74,7 +74,7 @@ <h5 class="modal-title"><i class="bi bi-pencil"></i> Edit Book Title</h5>
                 <input type="hidden" id="edit-author-path">
                 <input type="hidden" id="edit-files-json">
             </div>
-            <div class="modal-footer" style="border-color: #0f3460;">
+            <div class="modal-footer" style="border-color: var(--theme-border-primary);">
                 <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button>
                 <button type="button" class="btn btn-success" onclick="saveOrganize()">
                     <i class="bi bi-folder-plus"></i> Create Folder & Move
@@ -167,11 +167,7 @@ <h5 class="modal-title"><i class="bi bi-pencil"></i> Edit Book Title</h5>
         });
 }
 
-function escapeHtml(text) {
-    const div = document.createElement('div');
-    div.textContent = text;
-    return div.innerHTML;
-}
+// escapeHtml provided by common.js
 
 function editOrphan(idx) {
     const orphan = orphanData[idx];
diff --git a/templates/plugins_settings.html b/templates/plugins_settings.html
index 7bd4311..9b598af 100644
--- a/templates/plugins_settings.html
+++ b/templates/plugins_settings.html
@@ -19,7 +19,7 @@
                     <!-- Populated by JS -->
                 </div>
                 <div id="plugins-empty" class="text-center text-muted py-4" style="display: none;">
-                    <i class="bi bi-plug" style="font-size: 2rem;"></i>
+                    <i class="bi bi-plug fs-icon-lg"></i>
                     <p class="mt-2 mb-0">No custom API sources configured</p>
                     <small>Add a custom layer to query your own book metadata APIs</small>
                 </div>
diff --git a/templates/queue.html b/templates/queue.html
index 7bf5779..7f0b9a0 100644
--- a/templates/queue.html
+++ b/templates/queue.html
@@ -100,7 +100,7 @@ <h2><i class="bi bi-list-task"></i> Processing Queue <span class="badge bg-warni
 {% else %}
 <div class="card" id="empty-queue">
     <div class="card-body text-center py-5">
-        <i class="bi bi-check-circle text-success" style="font-size: 4rem;"></i>
+        <i class="bi bi-check-circle text-success fs-icon-xl"></i>
         <h4 class="mt-3">Queue is empty!</h4>
         <p class="text-muted">All books have been processed. Run a scan to check for new issues.</p>
         <a href="/" class="btn btn-primary">Back to Dashboard</a>
@@ -761,12 +761,7 @@ <h5 class="modal-title"><i class="bi bi-pencil-square"></i> Multi-Edit Queue Ite
     });
 }
 
-function escapeHtml(text) {
-    if (!text) return '';
-    const div = document.createElement('div');
-    div.textContent = text;
-    return div.innerHTML;
-}
+// escapeHtml provided by common.js
 
 // ===== HOVER CARD FUNCTIONS =====
 let hoverTimeout = null;
diff --git a/templates/settings.html b/templates/settings.html
index 10d044c..562dce1 100644
--- a/templates/settings.html
+++ b/templates/settings.html
@@ -2,70 +2,6 @@
 {% block title %}Settings - Library Manager{% endblock %}
 
 {% block content %}
-<style>
-    .spin-icon {
-        animation: spin-anim 1s linear infinite;
-    }
-    @keyframes spin-anim {
-        100% { transform: rotate(360deg); }
-    }
-    .hint-icon {
-        display: inline-flex;
-        align-items: center;
-        justify-content: center;
-        width: 16px;
-        height: 16px;
-        border-radius: 50%;
-        border: 1px solid rgba(0, 217, 255, 0.4);
-        color: rgba(0, 217, 255, 0.6);
-        font-size: 10px;
-        font-weight: bold;
-        font-style: normal;
-        cursor: help;
-        margin-left: 4px;
-        position: relative;
-        vertical-align: middle;
-        line-height: 1;
-        flex-shrink: 0;
-    }
-    .hint-icon:hover {
-        border-color: #00d9ff;
-        color: #00d9ff;
-    }
-    .hint-icon .hint-text {
-        display: none;
-        position: absolute;
-        bottom: calc(100% + 8px);
-        left: 50%;
-        transform: translateX(-50%);
-        background: rgba(15, 52, 96, 0.95);
-        border: 1px solid rgba(0, 217, 255, 0.3);
-        color: #eee;
-        padding: 8px 12px;
-        border-radius: 6px;
-        font-size: 0.8rem;
-        font-weight: normal;
-        font-style: normal;
-        line-height: 1.4;
-        white-space: normal;
-        width: 280px;
-        z-index: 1000;
-        box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
-        pointer-events: none;
-    }
-    .hint-icon .hint-text::after {
-        content: '';
-        position: absolute;
-        top: 100%;
-        left: 50%;
-        transform: translateX(-50%);
-        border: 6px solid transparent;
-        border-top-color: rgba(0, 217, 255, 0.3);
-    }
-    .hint-icon:hover .hint-text {
-        display: block;
-    }
-</style>
 <div class="d-flex justify-content-between align-items-center mb-3">
     <h2><i class="bi bi-gear"></i> Settings</h2>
     <span class="text-muted">v{{ version }}</span>
@@ -104,33 +40,18 @@ <h5 class="alert-heading"><i class="bi bi-lightbulb"></i> How It Works</h5>
             </button>
         </li>
         <li class="nav-item">
-            <button class="nav-link" data-bs-toggle="tab" data-bs-target="#tab-processing" type="button">
-                <i class="bi bi-cpu"></i> Processing
-            </button>
-        </li>
-        <li class="nav-item">
-            <button class="nav-link" data-bs-toggle="tab" data-bs-target="#tab-ai" type="button">
-                <i class="bi bi-robot"></i> AI Setup
-            </button>
-        </li>
-        <li class="nav-item">
-            <button class="nav-link" data-bs-toggle="tab" data-bs-target="#tab-safety" type="button">
-                <i class="bi bi-shield-check"></i> Safety
-            </button>
-        </li>
-        <li class="nav-item">
-            <button class="nav-link" data-bs-toggle="tab" data-bs-target="#tab-advanced" type="button">
-                <i class="bi bi-gear-wide-connected"></i> Advanced
+            <button class="nav-link" data-bs-toggle="tab" data-bs-target="#tab-engine" type="button">
+                <i class="bi bi-cpu"></i> Engine
             </button>
         </li>
         <li class="nav-item">
-            <button class="nav-link" data-bs-toggle="tab" data-bs-target="#tab-hooks" type="button">
-                <i class="bi bi-terminal"></i> Post-Processing
+            <button class="nav-link" data-bs-toggle="tab" data-bs-target="#tab-pipeline" type="button">
+                <i class="bi bi-layers"></i> Pipeline
             </button>
         </li>
         <li class="nav-item">
-            <button class="nav-link" data-bs-toggle="tab" data-bs-target="#tab-plugins" type="button">
-                <i class="bi bi-plug"></i> Plugins
+            <button class="nav-link" data-bs-toggle="tab" data-bs-target="#tab-integrations" type="button">
+                <i class="bi bi-plug"></i> Integrations
             </button>
         </li>
     </ul>
@@ -166,7 +87,7 @@ <h5 class="alert-heading"><i class="bi bi-lightbulb"></i> How It Works</h5>
                     {% else %}
                     <div class="card mb-3 border-info">
                         <div class="card-body text-center py-4">
-                            <i class="bi bi-info-circle text-info" style="font-size: 2rem;"></i>
+                            <i class="bi bi-info-circle text-info fs-icon-lg"></i>
                             <h5 class="mt-2">Demo Mode</h5>
                             <p class="text-muted mb-0">This is a public demo instance. Library paths are locked.</p>
                         </div>
@@ -434,8 +355,9 @@ <h5 class="mt-2">Demo Mode</h5>
             </div>
         </div>
 
-        <!-- ==================== PROCESSING TAB ==================== -->
-        <div class="tab-pane fade" id="tab-processing">
+        <!-- ==================== ENGINE TAB (Processing + AI Keys + Safety) ==================== -->
+        <div class="tab-pane fade" id="tab-engine">
+            <h5 class="mb-3"><i class="bi bi-play-circle"></i> Processing</h5>
             <div class="row">
                 <div class="col-lg-6">
                     <!-- Background Processing -->
@@ -755,17 +677,16 @@ <h5 class="mt-2">Demo Mode</h5>
                     </div>
                 </div>
             </div>
-        </div>
 
-        <!-- ==================== AI SETUP TAB ==================== -->
-        <div class="tab-pane fade" id="tab-ai">
+            <hr class="my-4">
+            <h5 class="mb-3"><i class="bi bi-key"></i> AI Providers</h5>
             <div class="row">
                 <!-- API Keys Card - Hidden in demo mode -->
                 <div class="col-lg-6">
                     {% if config.demo_mode %}
                     <div class="card mb-3 border-info">
                         <div class="card-body text-center py-4">
-                            <i class="bi bi-shield-lock text-info" style="font-size: 2rem;"></i>
+                            <i class="bi bi-shield-lock text-info fs-icon-lg"></i>
                             <h5 class="mt-2">API Keys Hidden</h5>
                             <p class="text-muted mb-0">API keys are pre-configured on this demo instance.</p>
                         </div>
@@ -992,7 +913,11 @@ <h5 class="mt-2">API Keys Hidden</h5>
                 </div>
             </div>
 
-            <!-- Continue with rest of AI tab -->
+        </div>{# end engine primary AI provider section #}
+
+        <!-- ==================== PIPELINE TAB (Provider Chains + Advanced) ==================== -->
+        <div class="tab-pane fade" id="tab-pipeline">
+            <h5 class="mb-3"><i class="bi bi-diagram-3"></i> Provider Chains</h5>
             <div class="row">
 
                 <div class="col-lg-6">
@@ -1133,10 +1058,9 @@ <h5 class="mt-2">API Keys Hidden</h5>
                     </div>
                 </div>
             </div>
-        </div>
 
-        <!-- ==================== SAFETY TAB ==================== -->
-        <div class="tab-pane fade" id="tab-safety">
+            <hr class="my-4">
+            <h5 class="mb-3"><i class="bi bi-shield-check"></i> Safety, Language & Maintenance</h5>
             <div class="row">
                 <div class="col-lg-6">
                     <!-- Auto-Apply Settings -->
@@ -1249,10 +1173,7 @@ <h5 class="mt-2">API Keys Hidden</h5>
                     </div>
                 </div>
             </div>
-        </div>
 
-        <!-- ==================== ADVANCED TAB ==================== -->
-        <div class="tab-pane fade" id="tab-advanced">
             <div class="row">
                 <div class="col-lg-6">
                     <!-- Language -->
@@ -1594,22 +1515,22 @@ <h6 class="alert-heading"><i class="bi bi-exclamation-octagon"></i> Read Before
                     </div>
                 </div>
             </div>
-        </div>
+        </div>{# end tab-pipeline #}
 
-        <!-- ==================== POST-PROCESSING TAB ==================== -->
-        <div class="tab-pane fade" id="tab-hooks">
+        <!-- ==================== INTEGRATIONS TAB ==================== -->
+        <div class="tab-pane fade" id="tab-integrations">
+            <h5 class="mb-3"><i class="bi bi-terminal"></i> Post-Processing Hooks</h5>
             {% include 'hooks_settings.html' %}
-        </div>
 
-        <!-- ==================== PLUGINS TAB ==================== -->
-        <div class="tab-pane fade" id="tab-plugins">
+            <hr class="my-4">
+            <h5 class="mb-3"><i class="bi bi-plug"></i> Custom API Sources</h5>
             {% include 'plugins_settings.html' %}
         </div>
 
     </div>
 
     <!-- Save Button (sticky) -->
-    <div class="position-sticky bottom-0 bg-dark py-3 border-top mt-3" style="z-index: 100;">
+    <div class="settings-save-bar">
         <div class="d-flex justify-content-end">
             <button type="submit" class="btn btn-primary">
                 <i class="bi bi-save"></i> Save Settings
@@ -2021,11 +1942,7 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
     }).catch(e => { document.getElementById('log-output').textContent = 'Error: ' + e; });
 }
 
-function escapeHtml(text) {
-    const div = document.createElement('div');
-    div.textContent = text;
-    return div.innerHTML;
-}
+// escapeHtml provided by common.js
 
 // API Tests
 function showApiTestResult(msg, success) {
@@ -2238,7 +2155,7 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
         .catch(e => alert('Error: ' + e));
 }
 
-document.querySelector('[data-bs-target="#tab-advanced"]')?.addEventListener('shown.bs.tab', loadBackupInfo);
+document.querySelector('[data-bs-target="#tab-pipeline"]')?.addEventListener('shown.bs.tab', loadBackupInfo);
 
 // Library path test
 function testLibraryPaths() {
@@ -2396,11 +2313,7 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
     `).join('');
 }
 
-function escapeHtml(str) {
-    const div = document.createElement('div');
-    div.textContent = str || '';
-    return div.innerHTML;
-}
+// escapeHtml provided by common.js
 
 function toggleHookEnabled(index, enabled) {
     hooksData[index].enabled = enabled;
@@ -2660,7 +2573,7 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
 }
 
 // Load hooks on tab show
-document.querySelector('[data-bs-target="#tab-hooks"]')?.addEventListener('shown.bs.tab', function() {
+document.querySelector('[data-bs-target="#tab-integrations"]')?.addEventListener('shown.bs.tab', function() {
     renderHooksList();
     refreshHookLog();
 });
@@ -3149,7 +3062,7 @@ <h5 class="modal-title"><i class="bi bi-upload"></i> Restore Backup</h5>
 }
 
 // Load plugins on tab show
-document.querySelector('[data-bs-target="#tab-plugins"]')?.addEventListener('shown.bs.tab', function() {
+document.querySelector('[data-bs-target="#tab-integrations"]')?.addEventListener('shown.bs.tab', function() {
     renderPluginsList();
     loadPluginHealth();
 });
diff --git a/templates/setup_wizard.html b/templates/setup_wizard.html
index 2ba1f21..6cfa99a 100644
--- a/templates/setup_wizard.html
+++ b/templates/setup_wizard.html
@@ -1,163 +1,7 @@
 {% extends "base.html" %}
 {% block title %}Setup - Library Manager{% endblock %}
 {% block content %}
-
-<style>
-    /* Setup Wizard Styles */
-    .setup-container {
-        max-width: 700px;
-        margin: 0 auto;
-    }
-
-    .step-indicators {
-        display: flex;
-        justify-content: center;
-        align-items: center;
-        margin-bottom: 2rem;
-        flex-wrap: wrap;
-        gap: 5px;
-    }
-
-    .step-indicator {
-        width: 40px;
-        height: 40px;
-        border-radius: 50%;
-        background: #16213e;
-        border: 2px solid #0f3460;
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        font-weight: bold;
-        color: #888;
-        transition: all 0.3s ease;
-    }
-
-    .step-indicator.active {
-        background: #e94560;
-        border-color: #e94560;
-        color: #fff;
-        transform: scale(1.1);
-    }
-
-    .step-indicator.completed {
-        background: #00d9ff;
-        border-color: #00d9ff;
-        color: #000;
-    }
-
-    .step-line {
-        width: 40px;
-        height: 2px;
-        background: #0f3460;
-        transition: background 0.3s ease;
-    }
-
-    .step-line.completed {
-        background: #00d9ff;
-    }
-
-    .setup-step {
-        animation: fadeIn 0.3s ease;
-    }
-
-    @keyframes fadeIn {
-        from { opacity: 0; transform: translateY(10px); }
-        to { opacity: 1; transform: translateY(0); }
-    }
-
-    .setup-card {
-        background: rgba(22, 33, 62, 0.9);
-        border: 1px solid rgba(0, 217, 255, 0.2);
-        border-radius: 16px;
-    }
-
-    .setup-card .card-body {
-        padding: 2rem;
-    }
-
-    .option-card {
-        background: rgba(15, 52, 96, 0.5);
-        border: 2px solid transparent;
-        border-radius: 12px;
-        padding: 1rem;
-        cursor: pointer;
-        transition: all 0.2s ease;
-    }
-
-    .option-card:hover {
-        border-color: rgba(0, 217, 255, 0.5);
-        background: rgba(15, 52, 96, 0.8);
-    }
-
-    .option-card.selected {
-        border-color: #00d9ff;
-        background: rgba(0, 217, 255, 0.1);
-    }
-
-    .option-card input[type="radio"] {
-        display: none;
-    }
-
-    .path-item {
-        background: rgba(15, 52, 96, 0.5);
-        border-radius: 8px;
-        padding: 0.75rem 1rem;
-        margin-bottom: 0.5rem;
-        display: flex;
-        align-items: center;
-        justify-content: space-between;
-    }
-
-    .path-item.valid {
-        border-left: 3px solid #00d9ff;
-    }
-
-    .path-item.invalid {
-        border-left: 3px solid #e94560;
-    }
-
-    .btn-nav {
-        min-width: 120px;
-    }
-
-    .feature-icon {
-        font-size: 2.5rem;
-        margin-bottom: 1rem;
-    }
-
-    .summary-item {
-        background: rgba(15, 52, 96, 0.3);
-        border-radius: 8px;
-        padding: 1rem;
-        margin-bottom: 0.75rem;
-    }
-
-    .summary-item .label {
-        color: rgba(255,255,255,0.6);
-        font-size: 0.85rem;
-    }
-
-    .summary-item .value {
-        font-weight: 600;
-        color: #00d9ff;
-    }
-
-    /* Hide navbar during setup for cleaner experience */
-    .navbar {
-        display: none !important;
-    }
-
-    .setup-header {
-        text-align: center;
-        margin-bottom: 1rem;
-        padding-top: 1rem;
-    }
-
-    .setup-header h1 {
-        font-size: 1.5rem;
-        color: #00d9ff;
-    }
-</style>
+<script>document.body.classList.add('setup-mode');</script>
 
 <div class="setup-container">
     <!-- Header -->

From b6f6a9dc4c05bcee5384ba261a36efe9b60305cb Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Tue, 7 Apr 2026 00:45:35 -0500
Subject: [PATCH 14/20] fix: Resolve SAFETY BLOCK for files in library root
 (#201) (#202)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Fix #201: Resolve path normalization mismatch causing SAFETY BLOCK for library root files

Windows mapped drives (e.g. R:\) resolve to UNC paths (\\server\share) but
library path comparisons in the processing layers used raw config paths
without .resolve(), causing the match to fail. The fallback then used
parent.parent which went above the library root for loose files.

Fixed all 4 locations to resolve both sides before comparison, and added
smart fallback that checks if the path is a file before deciding depth.

* Bump APP_VERSION to beta.144, update README badge and CHANGELOG

* Fix same path resolution bug in layer_content.py

Missed 5th location with identical unresolved relative_to() and
parent.parent fallback — caught by vibe-check review.

---------

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 CHANGELOG.md                                  | 13 ++++++++++
 README.md                                     |  2 +-
 app.py                                        | 24 +++++++++++++------
 library_manager/pipeline/layer_ai_queue.py    | 12 +++++++---
 .../pipeline/layer_audio_credits.py           | 10 +++++---
 library_manager/pipeline/layer_content.py     | 11 ++++++---
 6 files changed, 55 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9debc1f..9871940 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,19 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.144] - 2026-04-07
+
+### Fixed
+
+- **Issue #201: SAFETY BLOCK error for files in library root** - Fixed path normalization
+  mismatch where Windows mapped drives (e.g. `R:\`) resolve to UNC paths but config paths
+  were compared without `.resolve()`, causing library matching to fail. Fixed fallback logic
+  that assumed 2-level directory structure (`parent.parent`), which went above the library
+  root for loose files. Applied fix across all 4 path-matching locations in `app.py`,
+  `layer_ai_queue.py`, and `layer_audio_credits.py`.
+
+---
+
 ## [0.9.0-beta.143] - 2026-03-21
 
 ### Changed
diff --git a/README.md b/README.md
index 62617a4..bd1e126 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.143-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.144-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
diff --git a/app.py b/app.py
index 2c2462d..548fc42 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.143"
+APP_VERSION = "0.9.0-beta.144"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
@@ -11725,17 +11725,22 @@ def api_manual_match():
 
         # If not from watch folder, find which library it belongs to
         if lib_path is None:
+            old_path_resolved = Path(old_path).resolve()
             for lp in config.get('library_paths', []):
-                lp_path = Path(lp)
+                lp_path = Path(lp).resolve()
                 try:
-                    Path(old_path).relative_to(lp_path)
+                    old_path_resolved.relative_to(lp_path)
                     lib_path = lp_path
                     break
                 except ValueError:
                     continue
 
         if lib_path is None:
-            lib_path = Path(old_path).parent.parent
+            old_p = Path(old_path)
+            if old_p.is_file():
+                lib_path = old_p.parent
+            else:
+                lib_path = old_p.parent.parent
 
         # Detect language from title for multi-language naming
         lang_code = detect_title_language(new_title) if new_title else None
@@ -11894,17 +11899,22 @@ def api_edit_book():
                 return jsonify({'success': False, 'error': 'No output folder configured for watch folder items'})
         else:
             # Normal library item - find which library it belongs to
+            old_path_resolved = Path(old_path).resolve()
             for lp in config.get('library_paths', []):
-                lp_path = Path(lp)
+                lp_path = Path(lp).resolve()
                 try:
-                    Path(old_path).relative_to(lp_path)
+                    old_path_resolved.relative_to(lp_path)
                     lib_path = lp_path
                     break
                 except ValueError:
                     continue
 
             if lib_path is None:
-                lib_path = Path(old_path).parent.parent
+                old_p = Path(old_path)
+                if old_p.is_file():
+                    lib_path = old_p.parent
+                else:
+                    lib_path = old_p.parent.parent
 
         # Detect language from title for multi-language naming
         lang_code = detect_title_language(new_title) if new_title else None
diff --git a/library_manager/pipeline/layer_ai_queue.py b/library_manager/pipeline/layer_ai_queue.py
index 06a7987..aa294d3 100644
--- a/library_manager/pipeline/layer_ai_queue.py
+++ b/library_manager/pipeline/layer_ai_queue.py
@@ -450,10 +450,11 @@ def process_queue(
             # (Don't assume 2-level structure - series_grouping uses 3 levels)
             lib_path = None
             is_from_watch_folder = False
+            old_path_resolved = old_path.resolve()
             for lp in config.get('library_paths', []):
-                lp_path = Path(lp)
+                lp_path = Path(lp).resolve()
                 try:
-                    old_path.relative_to(lp_path)
+                    old_path_resolved.relative_to(lp_path)
                     lib_path = lp_path
                     break
                 except ValueError:
@@ -479,7 +480,12 @@ def process_queue(
 
             # Fallback if not found in configured libraries
             if lib_path is None:
-                lib_path = old_path.parent.parent
+                # For loose files in library root, parent is the library itself
+                # Only go up 2 levels for normal Author/Title structure
+                if old_path.is_file():
+                    lib_path = old_path.parent
+                else:
+                    lib_path = old_path.parent.parent
                 logger.warning(f"Book path {old_path} not under any configured library, guessing lib_path={lib_path}")
 
             # Detect language for multi-language naming
diff --git a/library_manager/pipeline/layer_audio_credits.py b/library_manager/pipeline/layer_audio_credits.py
index 50bf93c..9d6008f 100644
--- a/library_manager/pipeline/layer_audio_credits.py
+++ b/library_manager/pipeline/layer_audio_credits.py
@@ -219,10 +219,11 @@ def process_layer_3_audio(
             else:
                 # Audio suggests different values - build new path
                 lib_path = None
+                book_path_resolved = book_path.resolve()
                 for lp in config.get('library_paths', []):
-                    lp_path = Path(lp)
+                    lp_path = Path(lp).resolve()
                     try:
-                        book_path.relative_to(lp_path)
+                        book_path_resolved.relative_to(lp_path)
                         lib_path = lp_path
                         break
                     except ValueError:
@@ -240,7 +241,10 @@ def process_layer_3_audio(
                         logger.debug(f"Watch folder path check failed: {e}")
 
                 if lib_path is None:
-                    lib_path = book_path.parent.parent
+                    if book_path.is_file():
+                        lib_path = book_path.parent
+                    else:
+                        lib_path = book_path.parent.parent
                     logger.warning(f"[LAYER 3] Book path {book_path} not under any configured library, guessing lib_path={lib_path}")
 
                 # Detect language for multi-language naming
diff --git a/library_manager/pipeline/layer_content.py b/library_manager/pipeline/layer_content.py
index b408a92..210f8fe 100644
--- a/library_manager/pipeline/layer_content.py
+++ b/library_manager/pipeline/layer_content.py
@@ -113,16 +113,21 @@ def process_layer_4_content(
 
             # Build new path
             lib_path = None
+            book_path_resolved = book_path.resolve()
             for lp in config.get('library_paths', []):
+                lp_path = Path(lp).resolve()
                 try:
-                    book_path.relative_to(Path(lp))
-                    lib_path = Path(lp)
+                    book_path_resolved.relative_to(lp_path)
+                    lib_path = lp_path
                     break
                 except ValueError:
                     continue
 
             if not lib_path:
-                lib_path = book_path.parent.parent
+                if book_path.is_file():
+                    lib_path = book_path.parent
+                else:
+                    lib_path = book_path.parent.parent
 
             # Build target path with series grouping if applicable
             if new_series and config.get('series_grouping', True):

From a06840c18d1d2963af2141ff8701724ad5fa5925 Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Tue, 7 Apr 2026 01:04:59 -0500
Subject: [PATCH 15/20] docs: Plugin system documentation and discoverability
 (#203) (#204)

* Docs #203: Plugin system documentation and discoverability

Add in-app docs for Python drop-in plugins, secrets management, and
real-world API examples (Google Books, Open Library) to the Plugins
settings tab. Ship example-logger plugin to examples/plugins/ with
comprehensive README.

* Fix extra brace in Google Books URL template example

---------

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 CHANGELOG.md                                  |  14 ++
 README.md                                     |   2 +-
 app.py                                        |   2 +-
 examples/plugins/README.md                    | 121 ++++++++++++++++
 examples/plugins/example-logger/layer.py      |  78 +++++++++++
 examples/plugins/example-logger/manifest.json |  16 +++
 library_manager/hints.py                      |   6 +
 templates/plugins_settings.html               | 131 ++++++++++++++++++
 8 files changed, 368 insertions(+), 2 deletions(-)
 create mode 100644 examples/plugins/README.md
 create mode 100644 examples/plugins/example-logger/layer.py
 create mode 100644 examples/plugins/example-logger/manifest.json

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9871940..823ec7c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,20 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.145] - 2026-04-07
+
+### Added
+
+- **Issue #203: Plugin system documentation and discoverability** - Added Python drop-in
+  plugin guide with manifest.json and BasePlugin interface examples directly in the Plugins
+  settings tab. Added secrets management card explaining secrets.json usage for Docker and
+  bare metal. Added ready-to-use API configurations for Google Books and Open Library.
+  Shipped example-logger plugin to `examples/plugins/` with comprehensive README covering
+  plugin creation, manifest fields, BasePlugin interface, configuration, and behavior.
+  Added new hint entries for plugin-related tooltips.
+
+---
+
 ## [0.9.0-beta.144] - 2026-04-07
 
 ### Fixed
diff --git a/README.md b/README.md
index bd1e126..ff83754 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.144-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.145-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
diff --git a/app.py b/app.py
index 548fc42..bd4b705 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.144"
+APP_VERSION = "0.9.0-beta.145"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
diff --git a/examples/plugins/README.md b/examples/plugins/README.md
new file mode 100644
index 0000000..ac6b573
--- /dev/null
+++ b/examples/plugins/README.md
@@ -0,0 +1,121 @@
+# Example Plugins
+
+Drop-in Python plugins for Library Manager. Copy a plugin folder to `/data/plugins/` (Docker) or `plugins/` (bare metal) and restart.
+
+## example-logger
+
+A minimal template plugin that logs each book it processes. Use as a starting point for your own plugins.
+
+**Install:**
+```bash
+cp -r example-logger /data/plugins/
+# Restart Library Manager
+```
+
+## Creating Your Own Plugin
+
+Each plugin needs two files in its own folder:
+
+### manifest.json
+
+```json
+{
+  "id": "my-plugin",
+  "name": "My Plugin",
+  "version": "1.0.0",
+  "description": "What it does",
+  "type": "layer",
+  "entry_point": "layer.py",
+  "class_name": "MyPlugin",
+  "default_order": 35,
+  "requires_config": [],
+  "requires_secrets": ["my_api_key"],
+  "permissions": {
+    "network": ["api.example.com"],
+    "database": "read"
+  }
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | Yes | Unique identifier (alphanumeric, hyphens, underscores) |
+| `name` | Yes | Display name |
+| `version` | No | Semver version string |
+| `description` | No | What the plugin does |
+| `type` | Yes | Must be `layer` |
+| `entry_point` | Yes | Python file containing the plugin class |
+| `class_name` | No | Class name to load (auto-detected if omitted) |
+| `default_order` | No | Pipeline position 1-999 (default: 50). Lower = runs earlier |
+| `requires_config` | No | Config keys your plugin reads |
+| `requires_secrets` | No | Secret keys your plugin needs (stored in secrets.json) |
+| `permissions.network` | No | Domains your plugin connects to |
+| `permissions.database` | No | `read` or `write` |
+
+### layer.py
+
+```python
+from library_manager.plugin_loader import BasePlugin
+
+class MyPlugin(BasePlugin):
+    name = "My Plugin"
+    description = "What it does"
+    version = "1.0.0"
+
+    def setup(self, config, secrets):
+        """Called once on startup. Store config/secrets you need."""
+        self.api_key = secrets.get('my_api_key')
+
+    def can_process(self, book_data):
+        """Return True to process this book, False to skip."""
+        return True
+
+    def process(self, book_data):
+        """Main logic. Return dict of matched fields, or empty dict for no match.
+
+        book_data contains:
+          - current_title: Current title (from path or prior identification)
+          - current_author: Current author
+          - current_narrator: Current narrator (if known)
+          - path: Full filesystem path to the book
+          - book_id: Database ID
+
+        Return any of: title, author, narrator, series, series_num, year, language
+        """
+        return {}
+
+    def teardown(self):
+        """Called on shutdown. Clean up resources."""
+        pass
+```
+
+## Plugin Behavior
+
+- Plugins run with a **30 second timeout** per `process()` call
+- Default confidence weight: **60** (configurable via `plugin_configs` in config.json)
+- Auto-disabled after **5 consecutive failures** (re-enable from Plugin Health dashboard)
+- Plugins never crash the app - exceptions are caught and logged
+- Results feed into the book profile system alongside built-in sources
+
+## Configuration
+
+Per-plugin settings in `config.json`:
+
+```json
+{
+  "plugin_configs": {
+    "my-plugin": {
+      "timeout": 30,
+      "custom_setting": "value"
+    }
+  }
+}
+```
+
+Secrets in `secrets.json`:
+
+```json
+{
+  "my_api_key": "your-key-here"
+}
+```
diff --git a/examples/plugins/example-logger/layer.py b/examples/plugins/example-logger/layer.py
new file mode 100644
index 0000000..cea74a6
--- /dev/null
+++ b/examples/plugins/example-logger/layer.py
@@ -0,0 +1,78 @@
+"""Example plugin for Library Manager.
+
+This is a minimal plugin that demonstrates the BasePlugin interface.
+It logs each book it sees and returns empty results (no modifications).
+
+To use this as a template:
+1. Copy this directory to /data/plugins/your-plugin-name/
+2. Edit manifest.json with your plugin's metadata
+3. Implement process() with your logic
+4. Restart Library Manager
+
+The plugin loader will discover and load your plugin automatically.
+"""
+
+import logging
+
+# Import BasePlugin from the plugin loader
+from library_manager.plugin_loader import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+
+class ExampleLoggerPlugin(BasePlugin):
+    """A simple plugin that logs book information.
+
+    This demonstrates:
+    - setup() for one-time initialization
+    - can_process() for filtering books
+    - process() for the main logic
+    - teardown() for cleanup
+    """
+
+    name = "Example Logger"
+    description = "Logs book data for debugging"
+    version = "1.0.0"
+
+    def setup(self, config, secrets):
+        """Store config for later use."""
+        self.log_level = config.get('log_level', 'info')
+        self.books_seen = 0
+        logger.info("[ExamplePlugin] Setup complete")
+
+    def can_process(self, book_data):
+        """Process all books."""
+        return True
+
+    def process(self, book_data):
+        """Log the book data and return empty (no changes).
+
+        In a real plugin, you would:
+        1. Extract info from book_data (title, author, path, etc.)
+        2. Query your data source (API, database, file, etc.)
+        3. Return a dict with matched fields
+
+        Example return for a match:
+            return {
+                'title': 'The Corrected Title',
+                'author': 'Correct Author Name',
+                'narrator': 'Narrator Name',
+            }
+        """
+        self.books_seen += 1
+        title = book_data.get('current_title', 'Unknown')
+        author = book_data.get('current_author', 'Unknown')
+
+        logger.info(
+            f"[ExamplePlugin] Book #{self.books_seen}: "
+            f"'{title}' by {author}"
+        )
+
+        # Return empty dict = no changes (this is just a logger)
+        return {}
+
+    def teardown(self):
+        """Log summary on shutdown."""
+        logger.info(
+            f"[ExamplePlugin] Shutting down. Saw {self.books_seen} books total."
+        )
diff --git a/examples/plugins/example-logger/manifest.json b/examples/plugins/example-logger/manifest.json
new file mode 100644
index 0000000..4c6c417
--- /dev/null
+++ b/examples/plugins/example-logger/manifest.json
@@ -0,0 +1,16 @@
+{
+  "id": "example-logger",
+  "name": "Example Logger Plugin",
+  "version": "1.0.0",
+  "description": "A minimal example plugin that logs book data and returns empty results. Use as a template for building your own plugins.",
+  "type": "layer",
+  "entry_point": "layer.py",
+  "class_name": "ExampleLoggerPlugin",
+  "default_order": 35,
+  "requires_config": [],
+  "requires_secrets": [],
+  "permissions": {
+    "network": [],
+    "database": "read"
+  }
+}
diff --git a/library_manager/hints.py b/library_manager/hints.py
index 74ed456..8f72c9b 100644
--- a/library_manager/hints.py
+++ b/library_manager/hints.py
@@ -108,6 +108,12 @@
 
     # === Post-Processing Hooks ===
     'post_processing': 'Run external scripts or webhooks after a book is successfully renamed. Use for M4B conversion, Audiobookshelf library scans, Discord notifications, backup scripts, etc. Hook failures never undo a successful rename.',
+
+    # === Plugins ===
+    'custom_api_sources': 'Add your own book metadata APIs as processing layers. Each source queries an HTTP endpoint and maps the response into the book profile system.',
+    'python_plugins': 'Drop-in Python plugins for advanced users. Place a plugin folder in /data/plugins/ with a manifest.json and a Python file extending BasePlugin. Plugins are auto-discovered on startup.',
+    'plugin_health': 'Monitor the health and performance of your custom API sources and Python plugins. Plugins are auto-disabled after 5 consecutive failures to protect your processing pipeline.',
+    'plugin_secrets': 'API keys and passwords are stored in secrets.json (not config.json) so they are never exposed in backups or logs. Add your key as a named entry, then reference the key name here.',
 }
 
 
diff --git a/templates/plugins_settings.html b/templates/plugins_settings.html
index 9b598af..a419806 100644
--- a/templates/plugins_settings.html
+++ b/templates/plugins_settings.html
@@ -76,6 +76,137 @@
                 </table>
             </div>
         </div>
+
+        <!-- Python Drop-in Plugins -->
+        <div class="card mb-3">
+            <div class="card-header py-2">
+                <i class="bi bi-code-slash"></i> Python Drop-in Plugins
+                <span class="hint-icon" aria-label="Help">?<span class="hint-text">{{ hints.python_plugins }}</span></span>
+            </div>
+            <div class="card-body py-2" style="font-size: 0.8rem;">
+                <p class="mb-2">For developers who need more than HTTP lookups. Write Python plugins that can do anything: parse files, call complex APIs, run local models, etc.</p>
+
+                <p class="mb-1"><strong>Quick Start:</strong></p>
+                <ol class="mb-2 ps-3" style="font-size: 0.75rem;">
+                    <li>Create a folder in <code>/data/plugins/my-plugin/</code></li>
+                    <li>Add a <code>manifest.json</code> with plugin metadata</li>
+                    <li>Add a <code>.py</code> file extending <code>BasePlugin</code></li>
+                    <li>Restart Library Manager &mdash; plugin loads automatically</li>
+                </ol>
+
+                <p class="mb-1"><strong>manifest.json:</strong></p>
+                <pre class="bg-dark border border-secondary p-2 rounded mb-2" style="font-size: 0.7rem; white-space: pre-wrap;">{
+  "id": "my-plugin",
+  "name": "My Plugin",
+  "version": "1.0.0",
+  "description": "What it does",
+  "type": "layer",
+  "entry_point": "layer.py",
+  "class_name": "MyPlugin",
+  "default_order": 35,
+  "requires_config": [],
+  "requires_secrets": ["my_api_key"],
+  "permissions": {
+    "network": ["api.example.com"],
+    "database": "read"
+  }
+}</pre>
+
+                <p class="mb-1"><strong>Plugin Interface:</strong></p>
+                <pre class="bg-dark border border-secondary p-2 rounded mb-2" style="font-size: 0.7rem; white-space: pre-wrap;">from library_manager.plugin_loader import BasePlugin
+
+class MyPlugin(BasePlugin):
+    def setup(self, config, secrets):
+        self.api_key = secrets.get('my_api_key')
+
+    def can_process(self, book_data):
+        return True  # filter which books to process
+
+    def process(self, book_data):
+        title = book_data.get('current_title')
+        # ... your logic here ...
+        return {
+            'title': 'Corrected Title',
+            'author': 'Author Name',
+            # narrator, series, series_num, year
+        }
+
+    def teardown(self):
+        pass  # cleanup on shutdown</pre>
+
+                <p class="mb-0 text-muted" style="font-size: 0.7rem;">
+                    <i class="bi bi-info-circle"></i>
+                    Plugins run with a 30s timeout per book. Auto-disabled after 5 consecutive failures.
+                    An example plugin ships in <code>examples/plugins/example-logger/</code>.
+                </p>
+            </div>
+        </div>
+
+        <!-- Secrets Management -->
+        <div class="card mb-3">
+            <div class="card-header py-2">
+                <i class="bi bi-key"></i> Managing API Secrets
+                <span class="hint-icon" aria-label="Help">?<span class="hint-text">{{ hints.plugin_secrets }}</span></span>
+            </div>
+            <div class="card-body py-2" style="font-size: 0.8rem;">
+                <p class="mb-2">API keys and passwords go in <code>secrets.json</code>, not config.json. Reference them by name in the wizard or your plugin code.</p>
+
+                <p class="mb-1"><strong>secrets.json example:</strong></p>
+                <pre class="bg-dark border border-secondary p-2 rounded mb-2" style="font-size: 0.7rem; white-space: pre-wrap;">{
+  "gemini_api_key": "AIza...",
+  "my_bookdb_key": "Bearer abc123",
+  "my_api_password": "secret456"
+}</pre>
+                <p class="mb-0 text-muted" style="font-size: 0.7rem;">
+                    <i class="bi bi-shield-check"></i>
+                    <strong>Docker:</strong> <code>/config/secrets.json</code><br>
+                    <i class="bi bi-shield-check"></i>
+                    <strong>Bare metal:</strong> <code>secrets.json</code> in app directory<br>
+                    This file is gitignored and never included in backups or logs.
+                </p>
+            </div>
+        </div>
+
+        <!-- Real-World Examples -->
+        <div class="card mb-3">
+            <div class="card-header py-2">
+                <i class="bi bi-journal-code"></i> Example API Configurations
+            </div>
+            <div class="card-body py-2" style="font-size: 0.8rem;">
+                <p class="mb-2 text-muted">Ready-to-use configs for popular book APIs. Click "Add Custom API Source" and paste these values.</p>
+
+                <div class="mb-3">
+                    <p class="mb-1"><strong><i class="bi bi-google"></i> Google Books</strong></p>
+                    <table class="table table-sm table-dark mb-1" style="font-size: 0.7rem;">
+                        <tbody>
+                            <tr><td style="width:90px;">URL</td><td><code style="word-break:break-all;">https://www.googleapis.com/books/v1/volumes?q=intitle:{{"{{"}}title{{"}}"}}+inauthor:{{"{{"}}author{{"}}"}}&amp;maxResults=1</code></td></tr>
+                            <tr><td>Method</td><td>GET</td></tr>
+                            <tr><td>Auth</td><td>None (or API Key Header: <code>key</code>)</td></tr>
+                            <tr><td>Title</td><td><code>$.items[0].volumeInfo.title</code></td></tr>
+                            <tr><td>Author</td><td><code>$.items[0].volumeInfo.authors[0]</code></td></tr>
+                            <tr><td>Year</td><td><code>$.items[0].volumeInfo.publishedDate</code></td></tr>
+                        </tbody>
+                    </table>
+                </div>
+
+                <div class="mb-0">
+                    <p class="mb-1"><strong><i class="bi bi-book"></i> Open Library</strong></p>
+                    <table class="table table-sm table-dark mb-1" style="font-size: 0.7rem;">
+                        <tbody>
+                            <tr><td style="width:90px;">URL</td><td><code style="word-break:break-all;">https://openlibrary.org/search.json?title={{"{{"}}title{{"}}"}}&amp;author={{"{{"}}author{{"}}"}}&amp;limit=1</code></td></tr>
+                            <tr><td>Method</td><td>GET</td></tr>
+                            <tr><td>Auth</td><td>None</td></tr>
+                            <tr><td>Title</td><td><code>$.docs[0].title</code></td></tr>
+                            <tr><td>Author</td><td><code>$.docs[0].author_name[0]</code></td></tr>
+                            <tr><td>Year</td><td><code>$.docs[0].first_publish_year</code></td></tr>
+                        </tbody>
+                    </table>
+                    <p class="mb-0 text-muted" style="font-size: 0.7rem;">
+                        <i class="bi bi-info-circle"></i> Open Library is free with no API key required.
+                    </p>
+                </div>
+            </div>
+        </div>
     </div>
 </div>
 

From 1bd11bf54d8afcc5d15706b136e17d58a656889f Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Tue, 7 Apr 2026 01:18:14 -0500
Subject: [PATCH 16/20] Feat #110: Add folder triage UI - dashboard stats,
 library badges, settings toggle (#206)

Backend folder triage (clean/messy/garbage classification) was already
implemented but invisible in the UI. Now surfaces triage data:
- Dashboard info banner showing messy/garbage folder counts
- Library view badges on affected books (Messy/Garbage indicators)
- Settings toggle to enable/disable folder triage
- Triage data in "all" library API responses

Split push corrections to #205 (blocked on Skaldleita backend).

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 CHANGELOG.md             | 11 +++++++++++
 README.md                |  2 +-
 app.py                   | 21 +++++++++++++++------
 library_manager/hints.py |  3 +++
 templates/dashboard.html | 21 +++++++++++++++++++++
 templates/library.html   |  8 ++++++++
 templates/settings.html  | 11 +++++++++++
 7 files changed, 70 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 823ec7c..fee571d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.146] - 2026-04-07
+
+### Added
+
+- **Issue #110: Folder triage UI** - Dashboard now shows messy/garbage folder counts in an
+  info banner. Library view displays triage badges (Messy/Garbage) on affected books. Added
+  Settings toggle to enable/disable folder triage. Triage data now included in "all" library
+  view API responses. Split push corrections feature to #205 (blocked on Skaldleita).
+
+---
+
 ## [0.9.0-beta.145] - 2026-04-07
 
 ### Added
diff --git a/README.md b/README.md
index ff83754..95ecbcb 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.145-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.146-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
diff --git a/app.py b/app.py
index bd4b705..76dd44c 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.145"
+APP_VERSION = "0.9.0-beta.146"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
@@ -4924,6 +4924,7 @@ def deep_scan_library(config):
     validation_counts = {'valid': 0, 'invalid': 0, 'skipped': 0}  # Issue #110: File validation stats
     issues_found = {}  # path -> list of issues
     triage_counts = {'clean': 0, 'messy': 0, 'garbage': 0}  # Issue #110: Folder triage stats
+    triage_enabled = config.get('enable_folder_triage', True)  # Issue #110: Folder triage toggle
 
     # Issue #110: Check ffmpeg availability once at scan start
     ffmpeg_available, ffmpeg_msg = check_ffmpeg_available()
@@ -5111,7 +5112,7 @@ def deep_scan_library(config):
                 # Issue #132: Resolve path to prevent duplicates
                 flat_path = str(author_dir.resolve())
                 # Issue #110: Triage folder name quality
-                flat_triage = triage_folder(author)
+                flat_triage = triage_folder(author) if triage_enabled else 'clean'
 
                 checked += 1
 
@@ -5293,7 +5294,7 @@ def deep_scan_library(config):
 
                             checked += 1
                             # Issue #110: Triage folder name quality
-                            series_book_triage = triage_folder(book_title)
+                            series_book_triage = triage_folder(book_title) if triage_enabled else 'clean'
 
                             # Check if already tracked
                             c.execute('''SELECT id, status, profile, user_locked, attempt_count,
@@ -5370,7 +5371,7 @@ def deep_scan_library(config):
                 checked += 1
 
                 # Issue #110: Triage folder name quality
-                folder_triage_result = triage_folder(title)
+                folder_triage_result = triage_folder(title) if triage_enabled else 'clean'
                 triage_counts[folder_triage_result] = triage_counts.get(folder_triage_result, 0) + 1
                 if folder_triage_result != 'clean':
                     logger.info(f"Folder triage: {folder_triage_result} - {title[:60]}")
@@ -7032,6 +7033,11 @@ def dashboard():
     c.execute("SELECT COUNT(*) as count FROM books WHERE validation_status = 'invalid'")
     validation_failed_count = c.fetchone()['count']
 
+    # Issue #110: Count folder triage categories
+    c.execute("SELECT folder_triage, COUNT(*) as count FROM books WHERE folder_triage != 'clean' GROUP BY folder_triage")
+    triage_rows = c.fetchall()
+    triage_counts = {row['folder_triage']: row['count'] for row in triage_rows}
+
     # Get recent history (use LEFT JOIN in case book was deleted)
     c.execute('''SELECT h.*, b.path FROM history h
                  LEFT JOIN books b ON h.book_id = b.id
@@ -7054,6 +7060,7 @@ def dashboard():
                           verified_count=verified_count,
                           pending_fixes=pending_fixes,
                           validation_failed_count=validation_failed_count,
+                          triage_counts=triage_counts,
                           recent_history=recent_history,
                           daily_stats=daily_stats,
                           config=config,
@@ -7314,6 +7321,7 @@ def settings_page():
         config['enable_file_validation'] = 'enable_file_validation' in request.form
         config['min_audio_duration_seconds'] = int(request.form.get('min_audio_duration_seconds', 600))
         config['min_audio_file_size_mb'] = int(request.form.get('min_audio_file_size_mb', 1))
+        config['enable_folder_triage'] = 'enable_folder_triage' in request.form
 
         # Provider chain settings - parse comma-separated values into lists
         audio_chain_str = request.form.get('audio_provider_chain', 'bookdb,gemini').strip()
@@ -9817,7 +9825,7 @@ def build_order_by(sort_cols, default_order):
     else:  # 'all' - show everything from books table
         order = build_order_by(BOOK_SORT_COLS, 'current_author ASC, current_title ASC')
         c.execute('''SELECT b.id, b.path, b.current_author, b.current_title, b.status,
-                            b.user_locked, b.confidence, b.media_type,
+                            b.user_locked, b.confidence, b.media_type, b.folder_triage,
                             h.old_author, h.old_title, h.new_author, h.new_title,
                             h.old_path, h.new_path, h.status as history_status,
                             h.fixed_at, h.error_message
@@ -9856,7 +9864,8 @@ def build_order_by(sort_cols, default_order):
                 'status': history_status or book_status,
                 'confidence': row['confidence'] or 0,
                 'user_locked': row['user_locked'] == 1,
-                'media_type': row['media_type'] or 'audiobook'
+                'media_type': row['media_type'] or 'audiobook',
+                'folder_triage': row['folder_triage'] or 'clean'
             }
             # Overlay history data when present
             if history_status:
diff --git a/library_manager/hints.py b/library_manager/hints.py
index 8f72c9b..3d26d6d 100644
--- a/library_manager/hints.py
+++ b/library_manager/hints.py
@@ -109,6 +109,9 @@
     # === Post-Processing Hooks ===
     'post_processing': 'Run external scripts or webhooks after a book is successfully renamed. Use for M4B conversion, Audiobookshelf library scans, Discord notifications, backup scripts, etc. Hook failures never undo a successful rename.',
 
+    # === Folder Triage ===
+    'folder_triage': 'Classifies folder names as clean, messy (scene tags, torrent markers), or garbage (hashes, generic names). Messy and garbage folders skip path-based hints and rely on audio/metadata identification only.',
+
     # === Plugins ===
     'custom_api_sources': 'Add your own book metadata APIs as processing layers. Each source queries an HTTP endpoint and maps the response into the book profile system.',
     'python_plugins': 'Drop-in Python plugins for advanced users. Place a plugin folder in /data/plugins/ with a manifest.json and a Python file extending BasePlugin. Plugins are auto-discovered on startup.',
diff --git a/templates/dashboard.html b/templates/dashboard.html
index 500bcec..2d1d497 100644
--- a/templates/dashboard.html
+++ b/templates/dashboard.html
@@ -66,6 +66,27 @@
 </div>
 {% endif %}
 
+{% if triage_counts is defined and (triage_counts.get('messy', 0) > 0 or triage_counts.get('garbage', 0) > 0) %}
+<div class="row mb-3">
+    <div class="col-12">
+        <div class="alert alert-info py-2 mb-0 d-flex align-items-center" role="alert">
+            <i class="bi bi-funnel me-2"></i>
+            <small>
+                {{ _('Folder triage:') }}
+                {% if triage_counts.get('messy', 0) > 0 %}
+                    <strong>{{ triage_counts['messy'] }}</strong> {{ _('messy') }}
+                {% endif %}
+                {% if triage_counts.get('garbage', 0) > 0 %}
+                    {% if triage_counts.get('messy', 0) > 0 %}, {% endif %}
+                    <strong>{{ triage_counts['garbage'] }}</strong> {{ _('garbage') }}
+                {% endif %}
+                {{ _('folder(s) detected. Path hints skipped for these &mdash; relying on audio/metadata only.') }}
+            </small>
+        </div>
+    </div>
+</div>
+{% endif %}
+
 <!-- Toast container for action feedback -->
 <div class="toast-container position-fixed top-0 end-0 p-3" style="z-index: 1080;">
     <div id="action-toast" class="toast align-items-center border-0" role="alert" aria-live="assertive" aria-atomic="true">
diff --git a/templates/library.html b/templates/library.html
index e327ba7..ca484fb 100644
--- a/templates/library.html
+++ b/templates/library.html
@@ -511,6 +511,14 @@ <h5 class="modal-title"><i class="bi bi-pencil"></i> Edit Book Metadata</h5>
     if (item.user_locked) {
         badge = '<span class="badge bg-info status-badge" title="User-locked - protected from automatic changes"><i class="bi bi-lock-fill"></i></span> ' + badge;
     }
+
+    // Add folder triage badge for messy/garbage folders
+    if (item.folder_triage === 'messy') {
+        badge += ' <span class="badge bg-warning text-dark status-badge" title="Messy folder name (scene tags, torrent markers). Path hints skipped - using audio/metadata only."><i class="bi bi-exclamation-triangle"></i> Messy</span>';
+    } else if (item.folder_triage === 'garbage') {
+        badge += ' <span class="badge bg-danger status-badge" title="Garbage folder name (hash, numbers, placeholder). Path hints skipped - using audio/metadata only."><i class="bi bi-trash"></i> Garbage</span>';
+    }
+
     return badge;
 }
 
diff --git a/templates/settings.html b/templates/settings.html
index 562dce1..2198a2d 100644
--- a/templates/settings.html
+++ b/templates/settings.html
@@ -499,6 +499,17 @@ <h5 class="mb-3"><i class="bi bi-play-circle"></i> Processing</h5>
                                 </div>
                             </div>
 
+                            <!-- Issue #110: Folder Triage -->
+                            <div class="form-check form-switch mb-2">
+                                <input class="form-check-input" type="checkbox" name="enable_folder_triage"
+                                       id="enable_folder_triage" {% if config.enable_folder_triage is not defined or config.enable_folder_triage %}checked{% endif %}>
+                                <label class="form-check-label" for="enable_folder_triage">
+                                    <i class="bi bi-funnel text-info"></i> <strong>{{ _('Folder Triage') }}</strong>
+                                    <span class="badge bg-success">{{ _('Local') }}</span>
+                                    <br><small class="text-muted">{{ _('Classify folder names as clean/messy/garbage. Messy and garbage folders skip path parsing and rely on audio/metadata only.') }}</small>
+                                </label>
+                            </div>
+
                             <hr class="my-2">
 
                             <div class="form-check form-switch mb-3">

From d47e916bf237a02dc881697faef03eb563860880 Mon Sep 17 00:00:00 2001
From: deucebucket <deucebucket@users.noreply.github.com>
Date: Tue, 7 Apr 2026 01:36:27 -0500
Subject: [PATCH 17/20] Add ecosystem cross-repo sync workflow

When an issue gets the 'ecosystem' label and references another
deucebucket repo (e.g. deucebucket/skaldleita#127), automatically
comments on the partner issue with a cross-reference link.
Both repos have the same workflow and share an ECOSYSTEM_PAT secret.
---
 .github/workflows/ecosystem-sync.yml | 94 ++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 .github/workflows/ecosystem-sync.yml

diff --git a/.github/workflows/ecosystem-sync.yml b/.github/workflows/ecosystem-sync.yml
new file mode 100644
index 0000000..eb27c77
--- /dev/null
+++ b/.github/workflows/ecosystem-sync.yml
@@ -0,0 +1,94 @@
+name: Ecosystem Cross-Repo Sync
+
+on:
+  issues:
+    types: [labeled]
+
+jobs:
+  create-partner-issue:
+    if: github.event.label.name == 'ecosystem'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Extract cross-repo references
+        id: extract
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const body = context.payload.issue.body || '';
+            const title = context.payload.issue.title || '';
+            const issueNumber = context.payload.issue.number;
+            const thisRepo = `${context.repo.owner}/${context.repo.repo}`;
+
+            // Find references to other deucebucket repos: deucebucket/repo-name#123
+            const refPattern = /deucebucket\/([a-zA-Z0-9_-]+)#(\d+)/g;
+            const refs = [];
+            let match;
+            while ((match = refPattern.exec(body)) !== null) {
+              const targetRepo = `deucebucket/${match[1]}`;
+              if (targetRepo !== thisRepo) {
+                refs.push({ repo: match[1], number: parseInt(match[2]) });
+              }
+            }
+
+            // Find partner repos mentioned but without existing issues
+            const repoPattern = /deucebucket\/([a-zA-Z0-9_-]+)/g;
+            const partnerRepos = new Set();
+            while ((match = repoPattern.exec(body)) !== null) {
+              const repo = match[1];
+              if (`deucebucket/${repo}` !== thisRepo) {
+                partnerRepos.add(repo);
+              }
+            }
+
+            core.setOutput('has_refs', refs.length > 0 ? 'true' : 'false');
+            core.setOutput('partner_repos', JSON.stringify([...partnerRepos]));
+            core.setOutput('this_repo', context.repo.repo);
+            core.setOutput('issue_number', issueNumber);
+            core.setOutput('issue_title', title);
+
+      - name: Comment with ecosystem links
+        if: steps.extract.outputs.has_refs == 'true'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.ECOSYSTEM_PAT }}
+          script: |
+            const partnerRepos = JSON.parse('${{ steps.extract.outputs.partner_repos }}');
+            const thisRepo = '${{ steps.extract.outputs.this_repo }}';
+            const issueNumber = ${{ steps.extract.outputs.issue_number }};
+            const issueTitle = '${{ steps.extract.outputs.issue_title }}';
+
+            for (const repo of partnerRepos) {
+              // Check if a tracking comment already exists in the partner repo's referenced issue
+              const body = context.payload.issue.body || '';
+              const refMatch = body.match(new RegExp(`deucebucket/${repo}#(\\d+)`));
+
+              if (refMatch) {
+                const partnerIssueNumber = parseInt(refMatch[1]);
+                try {
+                  // Add a cross-reference comment on the partner issue
+                  const comments = await github.rest.issues.listComments({
+                    owner: 'deucebucket',
+                    repo: repo,
+                    issue_number: partnerIssueNumber
+                  });
+
+                  const alreadyLinked = comments.data.some(c =>
+                    c.body.includes(`deucebucket/${thisRepo}#${issueNumber}`)
+                  );
+
+                  if (!alreadyLinked) {
+                    await github.rest.issues.createComment({
+                      owner: 'deucebucket',
+                      repo: repo,
+                      issue_number: partnerIssueNumber,
+                      body: `### Ecosystem Link\n\nThis issue is linked to deucebucket/${thisRepo}#${issueNumber} — **${issueTitle}**\n\nBoth issues are tracked on [The Mead Hall](https://github.com/users/deucebucket/projects/1) project board.`
+                    });
+                    console.log(`Linked ${repo}#${partnerIssueNumber} <-> ${thisRepo}#${issueNumber}`);
+                  } else {
+                    console.log(`Already linked: ${repo}#${partnerIssueNumber}`);
+                  }
+                } catch (err) {
+                  console.log(`Could not comment on ${repo}#${partnerIssueNumber}: ${err.message}`);
+                }
+              }
+            }

From 7864dcf7bc20642f63af97fc9b1ca84107783061 Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Fri, 17 Apr 2026 19:27:47 -0500
Subject: [PATCH 18/20] Fix #209: Hard link failure no longer copies+deletes
 originals (#210)

When 'Use hard links' was enabled and the watch folder and library were on
different filesystems, os.link() raised EXDEV and the code silently fell back
to shutil.copy2() then deleted the originals. That broke torrent seeding,
doubled disk use, and silently violated the user's explicit preference.

- Add filesystem-compatibility pre-check in move_to_output_folder when
  use_hard_links is True. Returns a clear, actionable error if source and
  library are on different st_dev, without touching any source files.
- Remove the EXDEV copy+delete fallback from both the single-file and
  directory-loop branches. Remaining OSErrors (permission, ENOSPC, etc.)
  propagate to the outer handler with source intact; the watch worker records
  the failure as watch_folder_error visible in the UI.
- Bump APP_VERSION to 0.9.0-beta.147 and update README badge + CHANGELOG.

Reported by @kyleviloria.

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 CHANGELOG.md | 26 ++++++++++++++++++++++
 README.md    |  6 ++++-
 app.py       | 62 +++++++++++++++++++---------------------------------
 3 files changed, 54 insertions(+), 40 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fee571d..066d4ae 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,32 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.147] - 2026-04-17
+
+### Fixed
+
+- **Issue #209: Hard link failure silently copies and deletes originals** — When
+  `Use hard links` was enabled and the watch folder and library lived on different
+  filesystems, `os.link()` raised `EXDEV` and the code silently fell back to
+  `shutil.copy2()` followed by deleting each original file. That destroyed the
+  source data (breaking torrent seeds, doubling disk use, violating the user's
+  explicit "hard link" preference). Fix:
+  - Added a filesystem-compatibility pre-check at the start of
+    `move_to_output_folder`. When hard links are requested but source and library
+    are on different `st_dev`s, the function returns a clear, actionable error
+    ("Move your library to the same volume as the watch folder, or disable 'Use
+    hard links' in Settings") and does not touch source files.
+  - Removed the EXDEV copy+delete fallback from both the single-file and
+    directory-loop branches. Remaining `OSError`s (permission, `ENOSPC`, etc.)
+    propagate to the outer handler with source files intact, and the watch
+    worker records the failure as `watch_folder_error` with the error message
+    visible in the UI.
+  - Reported by `@kyleviloria` — files weren't lost because copies still existed
+    at the library destination, but the deletion of originals broke their
+    download workflow and burned disk.
+
+---
+
 ## [0.9.0-beta.146] - 2026-04-07
 
 ### Added
diff --git a/README.md b/README.md
index 95ecbcb..0871d1d 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.146-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.147-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
@@ -16,6 +16,10 @@
 
 ## Recent Changes (stable)
 
+> **beta.147** - **Critical Fix: Hard Link Safety** (Issue #209)
+> - **Stop silent copy+delete** - When "Use hard links" was enabled and the watch folder / library sat on different filesystems, LM used to copy every file and delete the originals. That broke torrent seeding and doubled disk use. Now LM fails fast with a clear error and leaves source files untouched.
+> - **Pre-check filesystem compatibility** - Verifies `st_dev` match before any file operations when hard links are enabled.
+
 > **beta.140** - **Feature: Custom Layer Builder** (Issue #186)
 > - **Plugins tab** - New settings tab with 4-step wizard to add custom HTTP API metadata sources
 > - **No-code API integration** - Configure URL templates, authentication, JSONPath response mapping, and confidence weights
diff --git a/app.py b/app.py
index 76dd44c..8663f0e 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.146"
+APP_VERSION = "0.9.0-beta.147"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
@@ -6520,6 +6520,22 @@ def move_to_output_folder(source_path: str, output_folder: str, author: str, tit
         except Exception as e:
             return False, None, f"Cannot create output folder: {e}"
 
+    # Issue #209: Fail fast if hard links requested across filesystems.
+    # Without this, a later os.link EXDEV would silently fall back to copy+delete,
+    # destroying the user's originals (e.g. breaking torrent seeds, doubling disk).
+    if use_hard_links:
+        try:
+            if source.stat().st_dev != output.stat().st_dev:
+                return False, None, (
+                    "Hard link failed: watch folder and library are on different "
+                    "filesystems. Hard links require both paths on the same volume. "
+                    "Move your library to the same volume as the watch folder, or "
+                    "disable 'Use hard links' in Settings. Source files were not "
+                    "modified."
+                )
+        except OSError as e:
+            return False, None, f"Cannot verify filesystem compatibility: {e}"
+
     # Sanitize author and title for filesystem
     safe_author = sanitize_path_component(author) if author else "Unknown"
     safe_title = sanitize_path_component(title) if title else source.name
@@ -6598,10 +6614,6 @@ def move_to_output_folder(source_path: str, output_folder: str, author: str, tit
         if not atomic_move_done:
             dest_folder.mkdir(parents=True, exist_ok=True)
 
-        # Track if we fell back to copy (need to delete originals afterward)
-        used_copy_fallback = False
-        files_to_delete = []
-
         if atomic_move_done:
             # Atomic move succeeded - nothing more to do for the files
             pass
@@ -6609,17 +6621,9 @@ def move_to_output_folder(source_path: str, output_folder: str, author: str, tit
             # Single file - move/link to destination folder
             dest_file = dest_folder / source.name
             if use_hard_links:
-                try:
-                    os.link(source, dest_file)
-                except OSError as e:
-                    if "Invalid cross-device link" in str(e) or e.errno == 18:
-                        # Cross-filesystem - fall back to copy, then delete original
-                        logger.warning(f"Hard link failed (cross-filesystem), falling back to copy+delete: {source.name}")
-                        shutil.copy2(source, dest_file)
-                        used_copy_fallback = True
-                        files_to_delete.append(source)
-                    else:
-                        raise
+                # Pre-check guarantees same filesystem; other OSErrors (perm, ENOSPC)
+                # propagate to the outer handler with source intact.
+                os.link(source, dest_file)
             else:
                 shutil.move(str(source), str(dest_file))
         else:
@@ -6637,23 +6641,13 @@ def move_to_output_folder(source_path: str, output_folder: str, author: str, tit
                     dest_file.parent.mkdir(parents=True, exist_ok=True)
 
                     if use_hard_links:
-                        try:
-                            os.link(src_file, dest_file)
-                        except OSError as e:
-                            if "Invalid cross-device link" in str(e) or e.errno == 18:
-                                logger.warning(f"Hard link failed, copy+delete: {src_file.name}")
-                                shutil.copy2(src_file, dest_file)
-                                used_copy_fallback = True
-                                files_to_delete.append(src_file)
-                            else:
-                                raise
+                        os.link(src_file, dest_file)
                     else:
                         shutil.move(str(src_file), str(dest_file))
 
-            # Clean up empty source folder if not using hard links OR if we used copy fallback
-            if (not use_hard_links or used_copy_fallback) and delete_empty:
+            # Clean up empty source folder when we moved files out (not for hardlinks — originals stay)
+            if not use_hard_links and delete_empty:
                 try:
-                    # Remove empty directories bottom-up
                     for dirpath, dirnames, filenames in os.walk(str(source), topdown=False):
                         if not filenames and not dirnames:
                             os.rmdir(dirpath)
@@ -6662,16 +6656,6 @@ def move_to_output_folder(source_path: str, output_folder: str, author: str, tit
                 except Exception as e:
                     logger.debug(f"Could not clean up empty folder {source}: {e}")
 
-        # Delete originals if we used copy fallback (handles both single files and directories)
-        if used_copy_fallback and delete_empty:
-            for f in files_to_delete:
-                try:
-                    if f.exists():
-                        f.unlink()
-                        logger.debug(f"Deleted source after copy fallback: {f}")
-                except Exception as e:
-                    logger.warning(f"Could not delete source {f}: {e}")
-
         return True, str(dest_folder), None
 
     except Exception as e:

From 6cd29e3921eac87cb7588137bcd96d473cf38d6f Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Fri, 17 Apr 2026 19:48:32 -0500
Subject: [PATCH 19/20] Fix #208: Persist watch_folder_processed + honor
 Skaldleita server_notice (#213)

Problem 1: watch_folder_processed was an in-memory set() that got wiped on
every restart. Any file that couldn't be processed (unknown author, ambiguous
match, move failure, mtime churn) got re-submitted every scan cycle after a
restart, forever. One LM instance generated ~48% of all Skaldleita /match
traffic for days on the same filename.

Problem 2: Skaldleita PR #129 added a server_notice field to /match
responses. When the server detects a retry loop it now sends
{severity, code, message, action: abort_task, upgrade_url}. LM ignored it.

Fixes:

- New watch_folder_processed SQLite table (path PK, processed_at, outcome,
  error_message). outcome in {moved, move_failed, aborted_by_server}.
- watch_folder_is_processed() / watch_folder_mark_processed() helpers in
  library_manager/database.py. process_watch_folder swapped from set ops
  to these helpers. Restart no longer resets dedup.
- bookdb.py logs every server_notice (with upgrade_url). On
  action=abort_task it stashes the notice in a threading.local() slot so
  scope is per-thread (watch worker, API endpoint, pipeline layer don't
  cross-contaminate).
- process_watch_folder reads the abort slot after each identify attempt;
  if set, marks the item as aborted_by_server and skips the pipeline.

Bumps APP_VERSION to 0.9.0-beta.148.

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 CHANGELOG.md                        | 28 +++++++++++++++
 README.md                           |  6 +++-
 app.py                              | 33 ++++++++++++------
 library_manager/database.py         | 53 +++++++++++++++++++++++++++++
 library_manager/providers/bookdb.py | 32 +++++++++++++++++
 5 files changed, 141 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 066d4ae..daeb120 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,34 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.148] - 2026-04-17
+
+### Fixed
+
+- **Issue #208: Watch-folder retry loop survives restarts** — The watch-folder
+  worker used an in-memory `set()` to remember which files it had already
+  processed. Every LM restart wiped the set, so whenever a file couldn't be
+  processed (unknown author, ambiguous match, move failure, mtime churn), the
+  worker would re-submit it on every scan forever. Server-side evidence showed
+  one LM instance generating ~48% of all Skaldleita `/match` traffic — 2,840
+  requests in a single day on the same filename. Fix:
+  - New `watch_folder_processed` SQLite table (`path`, `processed_at`,
+    `outcome`, `error_message`) persists dedup across restarts. `outcome`
+    values: `moved`, `move_failed`, `aborted_by_server`.
+  - Added `watch_folder_is_processed()` / `watch_folder_mark_processed()`
+    helpers in `library_manager/database.py`; watch worker switched from
+    `set()` ops to these helpers.
+- **Issue #208: Skaldleita `server_notice` handler** — Skaldleita responses
+  can now carry a `server_notice` block (severity/code/message/action/
+  upgrade_url). `library_manager/providers/bookdb.py` logs every notice
+  (with upgrade URL) and, on `action=abort_task`, stashes it in a
+  `threading.local()` slot. The watch-folder worker reads that slot after
+  each identify attempt and, if an abort was signalled, marks the item as
+  `aborted_by_server` and skips the rest of the pipeline — no 30-second
+  retry loop.
+
+---
+
 ## [0.9.0-beta.147] - 2026-04-17
 
 ### Fixed
diff --git a/README.md b/README.md
index 0871d1d..a15d196 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.147-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.148-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
@@ -16,6 +16,10 @@
 
 ## Recent Changes (stable)
 
+> **beta.148** - **Fix: Watch-Folder Retry Loop Across Restarts + Skaldleita server_notice** (Issue #208)
+> - **Persistent watch-folder dedup** - `watch_folder_processed` is now a SQLite table instead of an in-memory `set()`. Restarts no longer wipe it, killing the retry loop that had one LM instance hammering Skaldleita's `/match` every 30 seconds on the same file for days.
+> - **Honors Skaldleita's abort signal** - When the server detects a retry loop it sends a `server_notice` in the response. LM now logs it (with an upgrade URL) and, on `action=abort_task`, stops retrying that file immediately.
+
 > **beta.147** - **Critical Fix: Hard Link Safety** (Issue #209)
 > - **Stop silent copy+delete** - When "Use hard links" was enabled and the watch folder / library sat on different filesystems, LM used to copy every file and delete the originals. That broke torrent seeding and doubled disk use. Now LM fails fast with a clear error and leaves source files untouched.
 > - **Pre-check filesystem compatibility** - Verifies `st_dev` match before any file operations when hard links are enabled.
diff --git a/app.py b/app.py
index 8663f0e..6972a4c 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.147"
+APP_VERSION = "0.9.0-beta.148"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
@@ -52,7 +52,8 @@
 from library_manager.database import (
     init_db, get_db, set_db_path, cleanup_garbage_entries,
     cleanup_duplicate_history_entries, insert_history_entry,
-    should_requeue_book
+    should_requeue_book,
+    watch_folder_is_processed, watch_folder_mark_processed
 )
 from library_manager.models.book_profile import (
     SOURCE_WEIGHTS, FIELD_WEIGHTS, FieldValue, BookProfile,
@@ -6432,8 +6433,8 @@ def get_circuit_breaker(api_name):
 # WATCH FOLDER FUNCTIONALITY
 # ============================================================================
 
-# Track processed watch folder items to avoid reprocessing
-watch_folder_processed = set()
+# Issue #208: watch-folder dedup now lives in the watch_folder_processed
+# SQLite table (see library_manager.database) so restarts don't reset state.
 watch_folder_last_scan = 0
 
 def get_watch_folder_items(watch_folder: str, min_age_seconds: int = 30) -> list:
@@ -6456,8 +6457,8 @@ def get_watch_folder_items(watch_folder: str, min_age_seconds: int = 30) -> list
     for item in watch_path.iterdir():
         item_path = str(item.resolve())
 
-        # Skip if already processed
-        if item_path in watch_folder_processed:
+        # Skip if already processed (persisted in SQLite, Issue #208)
+        if watch_folder_is_processed(item_path):
             continue
 
         # Check if folder contains audio files or is an audio file
@@ -6668,7 +6669,7 @@ def process_watch_folder(config: dict) -> int:
     Process items in the watch folder.
     Returns number of items processed.
     """
-    global watch_folder_processed, watch_folder_last_scan
+    global watch_folder_last_scan
 
     watch_folder = config.get('watch_folder', '').strip()
     output_folder = config.get('watch_output_folder', '').strip()
@@ -6828,6 +6829,18 @@ def norm_conf(c):
             except Exception as e:
                 logger.debug(f"Watch folder: API lookup failed, using path analysis: {e}")
 
+            # Issue #208: Skaldleita may have signalled 'abort_task' during the
+            # lookup above (retry-loop protection). Stop retrying this item and
+            # persist it so future scans skip it until the user upgrades / fixes
+            # the source. The warning + upgrade URL are already in the logs.
+            from library_manager.providers.bookdb import get_and_clear_server_abort
+            server_abort = get_and_clear_server_abort()
+            if server_abort:
+                abort_msg = server_abort.get('message', 'Skaldleita requested task abort')
+                logger.warning(f"Watch folder: Aborting '{item.name}' per Skaldleita server notice")
+                watch_folder_mark_processed(item_path, 'aborted_by_server', abort_msg)
+                continue
+
             # Issue #57: Verify drastic author changes before accepting
             if needs_verification and api_author and api_title:
                 try:
@@ -6880,7 +6893,7 @@ def norm_conf(c):
 
             if success:
                 logger.info(f"Watch folder: Moved to {new_path}")
-                watch_folder_processed.add(item_path)
+                watch_folder_mark_processed(item_path, 'moved')
                 processed += 1
 
                 # Add to books table
@@ -6914,8 +6927,8 @@ def norm_conf(c):
             else:
                 logger.error(f"Watch folder: Failed to move {item.name}: {error}")
                 # Issue #49: Track failed items in the database so user can see and fix them
-                # Add to watch_folder_processed to prevent infinite retry loop
-                watch_folder_processed.add(item_path)
+                # Issue #208: persist dedup so the retry loop dies across restarts too
+                watch_folder_mark_processed(item_path, 'move_failed', error)
                 try:
                     # Check if this item is already tracked
                     c.execute('SELECT id FROM books WHERE path = ?', (item_path,))
diff --git a/library_manager/database.py b/library_manager/database.py
index 62d4df6..b25e040 100644
--- a/library_manager/database.py
+++ b/library_manager/database.py
@@ -175,6 +175,17 @@ def init_db(db_path=None):
         api_calls INTEGER DEFAULT 0
     )''')
 
+    # Issue #208: Persistent watch-folder dedup
+    # Was an in-memory set(), wiped on restart, which caused the watch worker
+    # to re-submit the same failing file every cycle (ate ~48% of Skaldleita
+    # traffic from a single LM instance before server-side cache absorbed it).
+    c.execute('''CREATE TABLE IF NOT EXISTS watch_folder_processed (
+        path TEXT PRIMARY KEY,
+        processed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        outcome TEXT,
+        error_message TEXT
+    )''')
+
     conn.commit()
     conn.close()
 
@@ -187,6 +198,48 @@ def init_db(db_path=None):
     init_plugin_metrics_table(path)
 
 
+def watch_folder_is_processed(path, db_path=None):
+    """Return True if the watch-folder path has already been handled.
+
+    Issue #208: replaces the in-memory set. Survives restarts so the worker
+    doesn't re-submit the same failing file every scan cycle.
+    """
+    p = db_path or _db_path
+    if not p:
+        return False
+    conn = sqlite3.connect(p, timeout=30)
+    try:
+        c = conn.execute(
+            'SELECT 1 FROM watch_folder_processed WHERE path = ? LIMIT 1',
+            (path,)
+        )
+        return c.fetchone() is not None
+    finally:
+        conn.close()
+
+
+def watch_folder_mark_processed(path, outcome, error_message=None, db_path=None):
+    """Record that a watch-folder path has been handled.
+
+    outcome: 'moved' | 'move_failed' | 'unknown_author' | 'aborted_by_server'
+    Issue #208.
+    """
+    p = db_path or _db_path
+    if not p:
+        return
+    conn = sqlite3.connect(p, timeout=30)
+    try:
+        conn.execute(
+            '''INSERT OR REPLACE INTO watch_folder_processed
+               (path, processed_at, outcome, error_message)
+               VALUES (?, CURRENT_TIMESTAMP, ?, ?)''',
+            (path, outcome, error_message)
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
 def cleanup_garbage_entries(db_path=None):
     """Remove garbage entries from database on startup.
 
diff --git a/library_manager/providers/bookdb.py b/library_manager/providers/bookdb.py
index 83e7345..d003733 100644
--- a/library_manager/providers/bookdb.py
+++ b/library_manager/providers/bookdb.py
@@ -15,6 +15,7 @@
 import logging
 import subprocess
 import tempfile
+import threading
 import requests
 from pathlib import Path
 
@@ -33,6 +34,22 @@
 
 logger = logging.getLogger(__name__)
 
+# Issue #208: Skaldleita can signal "stop retrying this task" via a server_notice
+# in the JSON response. We stash the notice in a thread-local so the caller
+# (e.g. the watch-folder worker) can pick it up and mark the item as aborted
+# without a 30-second retry loop. Thread-local keeps the signal scoped to the
+# thread that issued the matching request.
+_abort_state = threading.local()
+
+
+def get_and_clear_server_abort():
+    """Return (and clear) the last server_notice with action=abort_task seen
+    on this thread, or None. Safe to call when none was set."""
+    notice = getattr(_abort_state, 'notice', None)
+    if notice is not None:
+        _abort_state.notice = None
+    return notice
+
 # Skaldleita API endpoint (our metadata service, legacy name: BookDB)
 BOOKDB_API_URL = "https://bookdb.deucebucket.com"  # URL unchanged for backwards compatibility
 # Public API key for Library Manager users (no config needed)
@@ -168,6 +185,21 @@ def search_bookdb(title, author=None, api_key=None, retry_count=0, bookdb_url=No
 
         data = resp.json()
 
+        # Issue #208: honor Skaldleita server_notice. Log every notice; on
+        # action=abort_task, stash in thread-local so the watch-folder worker
+        # can stop retrying instead of hammering /match every 30s.
+        notice = data.get('server_notice')
+        if notice:
+            code = notice.get('code', 'unknown')
+            msg = notice.get('message', '')
+            upgrade_url = notice.get('upgrade_url')
+            severity = notice.get('severity', 'info')
+            logger.warning(f"[SKALDLEITA] server notice ({severity}) [{code}]: {msg}")
+            if upgrade_url:
+                logger.warning(f"[SKALDLEITA] upgrade: {upgrade_url}")
+            if notice.get('action') == 'abort_task':
+                _abort_state.notice = notice
+
         # Check confidence threshold
         if data.get('confidence', 0) < 0.5:
             logger.debug(f"Skaldleita match below confidence threshold: {data.get('confidence')}")

From 24f08885fd12b39e5457a35e456c52fdf505c6a2 Mon Sep 17 00:00:00 2001
From: DeuceBucket <51657177+deucebucket@users.noreply.github.com>
Date: Fri, 17 Apr 2026 20:06:39 -0500
Subject: [PATCH 20/20] Fix #211: Watch-folder DB inserts silently failed on
 phantom added_at column (#214)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three INSERT statements in process_watch_folder targeted a column 'added_at'
on the books table. The real column is 'created_at' — 'added_at' only exists
on the queue table. Every watch-folder INSERT raised sqlite3.OperationalError
which two separate except blocks caught with logger.debug(), hiding the error
at default log levels.

Effects:
- Successful watch-folder moves never produced a 'pending' or 'needs_attention'
  row in the books table.
- Failed watch-folder moves never produced a 'watch_folder_error' row — the
  UI had no surface for the failure; only the log showed it.

Fixes:
- Renamed 'added_at' to 'created_at' in the three books-table INSERTs at
  app.py:6906, 6914, 6944.
- Raised both swallow-except blocks from logger.debug to logger.warning with
  exc_info=True so future failures don't rot silently.

Surfaced during live testing of the #209 fix. Bug has existed since the
watch-folder feature was introduced.

Bumps APP_VERSION to 0.9.0-beta.149.

Co-authored-by: deucebucket <deucebucket@users.noreply.github.com>
---
 CHANGELOG.md | 23 +++++++++++++++++++++++
 README.md    |  6 +++++-
 app.py       | 15 +++++++++------
 3 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index daeb120..07491bb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,29 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.149] - 2026-04-17
+
+### Fixed
+
+- **Issue #211: Watch-folder failure tracking silently dropped** — Three
+  `INSERT` statements in `process_watch_folder` (`app.py:6906`, `6914`,
+  `6944`) referenced `added_at` on the `books` table, but the schema column
+  is `created_at`. Every insert raised `sqlite3.OperationalError: table
+  books has no column named added_at`. Two `except` blocks caught it with
+  `logger.debug`, hiding the error at default log levels. Effects:
+  - Successful watch-folder moves never produced a `pending` or
+    `needs_attention` row in the books table.
+  - Failed watch-folder moves never produced a `watch_folder_error` row —
+    users had no UI surface for the failure, only a log line.
+  - Fix: renamed `added_at` to `created_at` in all three INSERTs;
+    raised both swallow-except blocks from `logger.debug` to
+    `logger.warning(..., exc_info=True)` so the same class of silent
+    failure can't rot unnoticed again.
+  - Surfaced during live testing of #209. Bug has existed since the
+    watch-folder feature was introduced.
+
+---
+
 ## [0.9.0-beta.148] - 2026-04-17
 
 ### Fixed
diff --git a/README.md b/README.md
index a15d196..e9cd420 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.148-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.149-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
@@ -16,6 +16,10 @@
 
 ## Recent Changes (stable)
 
+> **beta.149** - **Fix: Watch-Folder Move Failures Now Appear in the UI** (Issue #211)
+> - Three `INSERT` statements in the watch-folder worker referenced a phantom `added_at` column on the `books` table (the real column is `created_at`). Every insert silently raised `OperationalError`, caught by a `logger.debug` that hid the error. Result: watch-folder move failures never produced a `watch_folder_error` row — the UI never showed the failure, users only saw it in logs.
+> - Fixed the column name and raised the swallow-except log level to `warning` with full traceback so future DB errors don't rot silently.
+
 > **beta.148** - **Fix: Watch-Folder Retry Loop Across Restarts + Skaldleita server_notice** (Issue #208)
 > - **Persistent watch-folder dedup** - `watch_folder_processed` is now a SQLite table instead of an in-memory `set()`. Restarts no longer wipe it, killing the retry loop that had one LM instance hammering Skaldleita's `/match` every 30 seconds on the same file for days.
 > - **Honors Skaldleita's abort signal** - When the server detects a retry loop it sends a `server_notice` in the response. LM now logs it (with an upgrade URL) and, on `action=abort_task`, stops retrying that file immediately.
diff --git a/app.py b/app.py
index 6972a4c..fd5962e 100644
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.148"
+APP_VERSION = "0.9.0-beta.149"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
@@ -6903,7 +6903,7 @@ def norm_conf(c):
                         # Unknown author - requires user intervention before processing
                         # Issue #57: Include source_type for watch folder tracking
                         c.execute('''INSERT OR REPLACE INTO books
-                                     (path, current_author, current_title, status, error_message, source_type, added_at, updated_at)
+                                     (path, current_author, current_title, status, error_message, source_type, created_at, updated_at)
                                      VALUES (?, ?, ?, 'needs_attention', ?, 'watch_folder', datetime('now'), datetime('now'))''',
                                   (new_path, author, title, 'Watch folder: Could not determine author - please review and correct'))
                         logger.info(f"Watch folder: Flagged for attention (unknown author): {title}")
@@ -6911,7 +6911,7 @@ def norm_conf(c):
                         # Known author - normal processing
                         # Issue #57: Include source_type for watch folder tracking
                         c.execute('''INSERT OR REPLACE INTO books
-                                     (path, current_author, current_title, status, source_type, added_at, updated_at)
+                                     (path, current_author, current_title, status, source_type, created_at, updated_at)
                                      VALUES (?, ?, ?, 'pending', 'watch_folder', datetime('now'), datetime('now'))''',
                                   (new_path, author, title))
                         # Issue #126: Auto-enqueue for full pipeline processing
@@ -6923,7 +6923,8 @@ def norm_conf(c):
                         logger.info(f"Watch folder: Auto-enqueued for processing: {author}/{title}")
                     conn.commit()
                 except Exception as e:
-                    logger.debug(f"Watch folder: Could not add to books table: {e}")
+                    # Issue #211: was logger.debug which hid the real exception.
+                    logger.warning(f"Watch folder: Could not add to books table: {e}", exc_info=True)
             else:
                 logger.error(f"Watch folder: Failed to move {item.name}: {error}")
                 # Issue #49: Track failed items in the database so user can see and fix them
@@ -6941,13 +6942,15 @@ def norm_conf(c):
                     else:
                         # Insert new record for the failed item
                         c.execute('''INSERT INTO books
-                                     (path, current_author, current_title, status, error_message, source_type, added_at, updated_at)
+                                     (path, current_author, current_title, status, error_message, source_type, created_at, updated_at)
                                      VALUES (?, ?, ?, 'watch_folder_error', ?, 'watch_folder', datetime('now'), datetime('now'))''',
                                   (item_path, author, title, f'Watch folder: {error}'))
                     conn.commit()
                     logger.info(f"Watch folder: Tracked failure for user review: {item.name}")
                 except Exception as db_err:
-                    logger.debug(f"Watch folder: Could not track failure in DB: {db_err}")
+                    # Issue #211: was logger.debug which hid the real exception; raise level
+                    # so failures surface in normal operation instead of rotting silently.
+                    logger.warning(f"Watch folder: Could not track failure in DB: {db_err}", exc_info=True)
 
         except Exception as e:
             logger.error(f"Watch folder: Error processing {item_path}: {e}")