Docs pass: update headers and READMEs for all new scripts

Script headers (6 files): - Add OPERATIONAL SAFEGUARDS section to all discovery + emby sync scripts - Add STATE FILES section to all 3 discovery scripts - Add CONFIGURATION section to emby_to_*_sync.sh - Rename USAGE → RUNTIME MODES in emby_to_*_sync.sh (doc standard) - Fix SONARR_DISCOVERY_MONITOR_MODE default doc: "future" → "all" Media/README-Media.md: - Remove "WIP prototype" label; describe all 3 discovery scripts - Add discovery scripts to scripts table and HOW THE SCRIPTS RELATE diagram - Add weekly discovery schedule block to EXECUTION ORDER section - Update intro to mention behavior-driven discovery Media/Manual-Media.md: - Add configuration reference sections for all 3 discovery scripts - Add flag reference sections for all 3 discovery scripts Tools/README-Tools.md: - Add "Library Sync Bootstrap" category and emby_to_*_sync.sh to scripts table - Add emby sync scripts to HOW THE SCRIPTS RELATE diagram Tools/Manual-Tools.md: - Update emby sync notes: search commands now fire immediately after add README.md: - Update Media folder description to include discovery - Update weekly schedule to show discovery scripts - Update README table entry for Media
2026-05-20 17:48:30 -04:00
parent 644225c4dc
commit 649a3b7b62
11 changed files with 328 additions and 25 deletions
@@ -216,6 +216,64 @@ LIDARR_ART_SLEEP_BETWEEN=1        # seconds between fanart.tv API calls (rate li

 ---

+### Lidarr Discovery
+
+```bash
+LIDARR_DISCOVERY_THRESHOLD=70         # minimum score for Stage 1 seeds and Stage 2 adds
+LIDARR_DISCOVERY_LOOKBACK_DAYS=7      # Emby play history window in days
+LIDARR_DISCOVERY_MIN_PLAYS=3          # min plays before an artist is evaluated as a seed
+LIDARR_DISCOVERY_MAX_ADDS=5           # max seeds (Stage 1) and max adds (Stage 2) per run
+LIDARR_DISCOVERY_USER_CAP_PCT=35      # max % any one user contributes to play weight
+LIDARR_DISCOVERY_REJECT_COOLDOWN=30   # days before re-evaluating a Stage 2 reject
+LIDARR_DISCOVERY_HISTORY="$DATA_DIR/lidarr_discovery_history.db"
+```
+
+Requires `HOST*_LASTFM_API_KEY` in `master_host*.conf`.
+
+---
+
+### Radarr Discovery
+
+```bash
+RADARR_DISCOVERY_THRESHOLD=52         # minimum score to add a candidate
+RADARR_DISCOVERY_LOOKBACK_DAYS=30     # Emby watch history window in days
+RADARR_DISCOVERY_MAX_SEEDS=5          # max seed movies from Stage 1
+RADARR_DISCOVERY_MAX_ADDS=5           # max movies to add per run
+RADARR_DISCOVERY_MIN_VOTE_COUNT=100   # min TMDB votes for a candidate
+RADARR_DISCOVERY_MIN_RATING=60        # min TMDB vote_average × 10 (60 = 6.0/10)
+RADARR_DISCOVERY_REJECT_COOLDOWN=60   # days before re-evaluating a rejected movie
+RADARR_DISCOVERY_SEED_LIBRARIES=("Movies")   # Emby libraries to draw seeds from
+RADARR_DISCOVERY_HISTORY="$DATA_DIR/radarr_discovery_history.db"
+```
+
+Requires `HOST*_TMDB_API_KEY` in `master_host*.conf`.
+
+---
+
+### Sonarr Discovery
+
+```bash
+SONARR_DISCOVERY_THRESHOLD=52         # minimum score to add a candidate
+SONARR_DISCOVERY_LOOKBACK_DAYS=14     # Emby episode history window in days
+SONARR_DISCOVERY_MAX_SEEDS=5          # max seed series from Stage 1
+SONARR_DISCOVERY_MAX_ADDS=3           # max shows to add per run (TV is a larger commitment)
+SONARR_DISCOVERY_MIN_VOTE_COUNT=50    # min TMDB votes for a candidate
+SONARR_DISCOVERY_MIN_RATING=65        # min TMDB vote_average × 10 (65 = 6.5/10)
+SONARR_DISCOVERY_REJECT_COOLDOWN=60   # days before re-evaluating a rejected show
+SONARR_DISCOVERY_USER_EPISODE_CAP=8   # max episodes per user in seed scoring
+SONARR_DISCOVERY_MONITOR_MODE="all"   # "all" = all seasons monitored; "future" = upcoming only
+SONARR_DISCOVERY_HISTORY="$DATA_DIR/sonarr_discovery_history.db"
+# SONARR_EMBY_LIBRARIES is shared with emby_to_sonarr_sync — see Orchestrator Job Order
+```
+
+Requires `HOST*_TMDB_API_KEY` in `master_host*.conf`.
+
+> **MONITOR_MODE note:** Use `"all"` (default) to have Sonarr search all existing seasons
+> after adding a show. `"future"` only marks upcoming seasons as monitored — shows where
+> all seasons have already aired will appear unmonitored and Sonarr will not search for them.
+
+---
+
 ### Orchestrator Job Order

 ```bash
@@ -634,3 +692,59 @@ Show configuration and API key status.

 `lidarr_missing_art.sh --log`  
 Verbose per-album, per-artist output.
+
+---
+
+### playback_aware_lidarr_discovery.sh
+
+`playback_aware_lidarr_discovery.sh`  
+Score Emby play history, run Last.fm getSimilar on top artists, add candidates above
+threshold to Lidarr. Triggers ArtistSearch immediately after each successful add.
+
+`playback_aware_lidarr_discovery.sh --dry-run`  
+Score and rank all Stage 1 seeds and Stage 2 candidates. No Lidarr API calls. No writes
+to history file. Shows exactly what would be added and at what score.
+
+`playback_aware_lidarr_discovery.sh --status`  
+Show config values, history file path and size, and API key status.
+
+`playback_aware_lidarr_discovery.sh --log`  
+Verbose per-artist scoring output for both stages.
+
+---
+
+### playback_aware_radarr_discovery.sh
+
+`playback_aware_radarr_discovery.sh`  
+Score recently watched Emby movies, run TMDB recommendations on seeds, add candidates
+above threshold to Radarr. Triggers MoviesSearch immediately after each successful add.
+
+`playback_aware_radarr_discovery.sh --dry-run`  
+Score and rank all Stage 1 seeds and Stage 2 candidates. No Radarr API calls. No writes
+to history file.
+
+`playback_aware_radarr_discovery.sh --status`  
+Show config values, history file path and size, and API key status.
+
+`playback_aware_radarr_discovery.sh --log`  
+Verbose per-movie scoring output for both stages.
+
+---
+
+### playback_aware_sonarr_discovery.sh
+
+`playback_aware_sonarr_discovery.sh`  
+Score recently watched Emby series (weighted by user diversity), run TMDB TV
+recommendations on seeds, add candidates above threshold to Sonarr. Triggers SeriesSearch
+immediately after each successful add.
+
+`playback_aware_sonarr_discovery.sh --dry-run`  
+Score and rank all Stage 1 seeds and Stage 2 candidates. No Sonarr API calls. No writes
+to history file.
+
+`playback_aware_sonarr_discovery.sh --status`  
+Show config values, history file path and size, and API key status.
+
+`playback_aware_sonarr_discovery.sh --log`  
+Verbose per-series scoring output — shows user diversity, recency, and volume scores per
+seed; breadth, rating, and votes scores per candidate.
@@ -1,9 +1,11 @@
 # ━━━━━ MEDIA ━━━━━

-Library health, consistency, and sync for a multi-server arr stack. Correct permissions
-so arrs can manage files. Junk removal so orphan detection isn't confused by scene debris.
-Library sync so every node tracks the same content. Orphan cleanup against live arr APIs
-so deleted content actually leaves disk. Emby notified automatically after every deletion.
+Library health, consistency, sync, and behavior-driven discovery for a multi-server arr
+stack. Correct permissions so arrs can manage files. Junk removal so orphan detection
+isn't confused by scene debris. Library sync so every node tracks the same content.
+Orphan cleanup against live arr APIs so deleted content actually leaves disk. Emby
+notified automatically after every deletion. Weekly discovery adds new music, movies,
+and TV shows based on what you actually play — no manual browsing required.

 > **These scripts permanently delete files.** The arr cleanup scripts are protected by
 > multiple safety layers that must all pass before anything is touched — but dry runs and
@@ -89,9 +91,15 @@ free overnight recovery.
 `lidarr_missing_art.sh` — fetch missing album and artist artwork from fanart.tv and
 fallback sources. Never overwrites existing files.

-**Discovery (WIP)**  
-`playback_aware_lidarr_discovery.sh` — scoring prototype for behavior-driven music
-discovery. Consumes `Kernel/decision_engine.sh`. Not yet connected to a data source.
+**Discovery**  
+`playback_aware_lidarr_discovery.sh` — behavior-driven music discovery. Scores your
+Emby play history, runs Last.fm getSimilar on top artists, adds the best matches to
+Lidarr. 0–5 meaningful adds per week.  
+`playback_aware_radarr_discovery.sh` — behavior-driven movie discovery. Scores recently
+watched movies, runs TMDB recommendations on seeds, adds top candidates to Radarr.  
+`playback_aware_sonarr_discovery.sh` — behavior-driven TV discovery. Scores recently
+watched series weighted by user diversity, runs TMDB TV recommendations on seeds, adds
+top shows to Sonarr. Multi-user design: one person binge-watching does not dominate seeds.

 ---

@@ -122,6 +130,14 @@ arr_sync.sh    — arrs agree on library → rsync then spreads the files
 arrs_failed_stalled_recovery.sh
 ```

+**Weekly discovery (WEEKLY_MAINTENANCE_SCRIPTS in master.conf):**
+
+```
+playback_aware_lidarr_discovery.sh   — score play history → Last.fm similar → add to Lidarr
+playback_aware_radarr_discovery.sh   — score watch history → TMDB recommendations → add to Radarr
+playback_aware_sonarr_discovery.sh   — score episode history → TMDB TV recommendations → add to Sonarr
+```
+
 **Ad-hoc or separate schedule:**

 ```
@@ -176,7 +192,9 @@ cleanly with no action. No manual `HOST1`/`HOST2` comparisons exist in any scrip
 | `lidarr_missing_art.sh` | Fetch missing album and artist artwork | Ad-hoc or separate schedule |
 | `radarr_tmdb_removed.sh` | Remove movies dropped from TMDb | Ad-hoc or weekly |
 | `sonarr_tvdb_removed.sh` | Remove series dropped from TVDB | Ad-hoc or weekly |
-| `playback_aware_lidarr_discovery.sh` | Behavior-driven music discovery scoring (WIP prototype) | Not yet scheduled |
+| `playback_aware_lidarr_discovery.sh` | Behavior-driven music discovery — Emby plays → Last.fm similar → Lidarr | Weekly via `weekly_sync_maintenance.sh` |
+| `playback_aware_radarr_discovery.sh` | Behavior-driven movie discovery — Emby watches → TMDB recommendations → Radarr | Weekly via `weekly_sync_maintenance.sh` |
+| `playback_aware_sonarr_discovery.sh` | Behavior-driven TV discovery — Emby episodes → TMDB TV recommendations → Sonarr | Weekly via `weekly_sync_maintenance.sh` |

 ---

@@ -206,6 +224,13 @@ Daily maintenance window (media_management.sh):
 Daily recovery:
  arrs_failed_stalled_recovery.sh ── importFailed/stalled → blocklist → re-search

+Weekly discovery (WEEKLY_MAINTENANCE_SCRIPTS):
+  playback_aware_lidarr_discovery.sh ─ Emby plays → Last.fm similar → top candidates → Lidarr
+  playback_aware_radarr_discovery.sh ─ Emby watches → TMDB recommendations → top candidates → Radarr
+  playback_aware_sonarr_discovery.sh ─ Emby episodes → TMDB TV recommendations → top candidates → Sonarr
+        │
+        └── each discovery script fires arr search immediately after successful add
+
 Ad-hoc enrichment:
  lidarr_missing_art.sh ─────── discovers missing artwork → fetches from fanart.tv
  radarr_tmdb_removed.sh ────── status="deleted" → remove from Radarr + add exclusion
@@ -83,6 +83,33 @@
 # Recommended schedule: weekly (WEEKLY_MAINTENANCE_SCRIPTS in master.conf)
 #
 # ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# Root Required
+#   acquire_lock and Lidarr API writes require root. Script exits cleanly if not root.
+#
+# Dry-Run Mode
+#   --dry-run scores and ranks all candidates but makes no Lidarr API calls and does not
+#   write to the history file. Safe to run at any time to preview what would be added.
+#
+# Add-Only
+#   Only adds artists to Lidarr. Never deletes or modifies existing entries.
+#
+# Cooldown Guard
+#   Candidates rejected this run are recorded in the history file and not re-evaluated
+#   until LIDARR_DISCOVERY_REJECT_COOLDOWN days have elapsed.
+#
+# ==============================================================================================
+# STATE FILES
+# ==============================================================================================
+#
+#   LIDARR_DISCOVERY_HISTORY (default: $DATA_DIR/lidarr_discovery_history.db)
+#     Tracks added artists and rejected candidates with timestamps. Written after every
+#     non-dry-run. Enforces reject cooldown and prevents re-adding items added by previous
+#     runs. Safe to delete — next run starts fresh with no memory.
+#
+# ==============================================================================================

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

@@ -84,6 +84,33 @@
 # Recommended schedule: weekly (WEEKLY_MAINTENANCE_SCRIPTS in master.conf)
 #
 # ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# Root Required
+#   acquire_lock and Radarr API writes require root. Script exits cleanly if not root.
+#
+# Dry-Run Mode
+#   --dry-run scores and ranks all candidates but makes no Radarr API calls and does not
+#   write to the history file. Safe to run at any time to preview what would be added.
+#
+# Add-Only
+#   Only adds movies to Radarr. Never deletes or modifies existing entries.
+#
+# Cooldown Guard
+#   Candidates rejected this run are recorded in the history file and not re-evaluated
+#   until RADARR_DISCOVERY_REJECT_COOLDOWN days have elapsed.
+#
+# ==============================================================================================
+# STATE FILES
+# ==============================================================================================
+#
+#   RADARR_DISCOVERY_HISTORY (default: $DATA_DIR/radarr_discovery_history.db)
+#     Tracks added movies and rejected candidates with timestamps. Written after every
+#     non-dry-run. Enforces reject cooldown and prevents re-adding items added by previous
+#     runs. Safe to delete — next run starts fresh with no memory.
+#
+# ==============================================================================================

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

@@ -77,7 +77,7 @@
 #   SONARR_DISCOVERY_MIN_RATING       — min TMDB vote_average × 10 (default: 65 = 6.5/10)
 #   SONARR_DISCOVERY_REJECT_COOLDOWN  — days before re-evaluating a rejected show (default: 60)
 #   SONARR_DISCOVERY_USER_EPISODE_CAP — max episodes per user in seed scoring (default: 8)
-#   SONARR_DISCOVERY_MONITOR_MODE     — Sonarr monitor mode on add (default: "future")
+#   SONARR_DISCOVERY_MONITOR_MODE     — Sonarr monitor mode on add: "all" or "future" (default: "all")
 #   SONARR_EMBY_LIBRARIES             — Emby library names to draw seeds from
 #   SONARR_DISCOVERY_HISTORY          — history/state file path
 #
@@ -93,6 +93,38 @@
 # Recommended schedule: weekly (WEEKLY_MAINTENANCE_SCRIPTS in master.conf)
 #
 # ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# Root Required
+#   acquire_lock and Sonarr API writes require root. Script exits cleanly if not root.
+#
+# Dry-Run Mode
+#   --dry-run scores and ranks all candidates but makes no Sonarr API calls and does not
+#   write to the history file. Safe to run at any time to preview what would be added.
+#
+# Add-Only
+#   Only adds series to Sonarr. Never deletes or modifies existing entries.
+#
+# Cooldown Guard
+#   Candidates rejected this run are recorded in the history file and not re-evaluated
+#   until SONARR_DISCOVERY_REJECT_COOLDOWN days have elapsed.
+#
+# Monitor Mode
+#   SONARR_DISCOVERY_MONITOR_MODE="all" monitors every season on add — correct for shows
+#   where you want Sonarr to search back-catalogue. "future" only marks upcoming seasons;
+#   use only when you intentionally want to skip existing seasons.
+#
+# ==============================================================================================
+# STATE FILES
+# ==============================================================================================
+#
+#   SONARR_DISCOVERY_HISTORY (default: $DATA_DIR/sonarr_discovery_history.db)
+#     Tracks added series and rejected candidates with timestamps. Written after every
+#     non-dry-run. Enforces reject cooldown and prevents re-adding items added by previous
+#     runs. Safe to delete — next run starts fresh with no memory.
+#
+# ==============================================================================================

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

@@ -482,7 +482,7 @@ Unraid_Scripts/
 ├── unRAID_Essentials/       ← Server-level: system watchdog, WebGUI, log hygiene, tuning
 │   README: README-Unraid_Essentials.md
 │
-├── Media/                   ← Library health: permissions, junk cleanup, orphan removal
+├── Media/                   ← Library health + behavior-driven discovery: permissions, junk cleanup, orphan removal, weekly arr adds
 │   README: README-Media.md
 │
 ├── Transcodes/              ← Ramdisk transcode management with SSD fallback
@@ -560,6 +560,7 @@ Every 6 hours:

 2:30am Sunday:
  weekly_sync_maintenance.sh  stop → update images → clean sync → start → weekly restarts
+                              + playback_aware_lidarr/radarr/sonarr_discovery.sh  (behavior-driven arr discovery)

 8am daily:
  weekly_health_digest.sh     DIGEST_PROFILE controls when it actually notifies
@@ -679,7 +680,7 @@ If you're setting this up from scratch on two servers:
 | [README-Docker_Essentials.md](Docker_Essentials/README-Docker_Essentials.md) | Two-tier container watchdog, memory limits, dependency ordering, skip list, daily/weekly restarts |
 | [README-Unraid_Essentials.md](unRAID_Essentials/README-Unraid_Essentials.md) | Three-tier system watchdog, WebGUI recovery, inotify tuning, PHP-FPM, log hygiene |
 | [README-Orchestrators.md](Orchestrators/README-Orchestrators.md) | What runs when, execution order, daily/weekly windows, adding jobs |
-| [README-Media.md](Media/README-Media.md) | Permissions model, junk cleanup, arr orphan removal, safety layers, testing procedure |
+| [README-Media.md](Media/README-Media.md) | Permissions model, junk cleanup, arr orphan removal, safety layers, behavior-driven discovery, testing procedure |
 | [README-Transcoding.md](Transcodes/README-Transcoding.md) | Ramdisk design, symlink architecture, Docker mount requirement, SSD fallback |
 | [README-Monitors.md](Monitors/README-Monitors.md) | Cert monitoring, SMART health, bandwidth tracking, health digest profiles |
 | [README-Partnership.md](Partnership/README-Partnership.md) | Auth stack sharing, onboard/offboard/transfer lifecycle, deferred offboard |
@@ -52,10 +52,10 @@ bash Tools/emby_to_lidarr_sync.sh

 ### Notes

- Reads completions from the Emby activity log (`has finished playing` events)
+- Reads all MusicAlbum items from Emby and extracts AlbumArtist — primary album
+  artists only, not guest features or tag credits
 - Filters out VA, Various Artists, and other metadata placeholders
- Uses `searchForMissingAlbums: false` — adds monitoring without triggering a
-  full album search; run Lidarr's own missing-album search afterwards if desired
+- Triggers `ArtistSearch` immediately after each successful add — no manual search needed
 - Activity log has a finite history; use `--days N` if the log has been pruned

 ---
@@ -84,10 +84,11 @@ bash Tools/emby_to_sonarr_sync.sh

 ### Notes

- Uses `searchForMissingEpisodes: false` — adds monitoring without triggering
-  episode searches; Sonarr's library scan will pick up existing files
- Adds to the first accessible root folder in Sonarr (`/tv` by default)
+- Triggers `SeriesSearch` immediately after each successful add — Sonarr begins
+  searching for missing episodes right away
+- Adds to the first accessible root folder in Sonarr
 - TVDB ID match preferred over title; title fallback handles edge cases
+- Requires `SONARR_EMBY_LIBRARIES` configured in `master.conf`

 ---

@@ -115,9 +116,9 @@ bash Tools/emby_to_radarr_sync.sh

 ### Notes

- Uses `searchForMovie: false` — adds monitoring without triggering movie
-  searches; Radarr's library scan will pick up existing files
- Adds to the first accessible root folder in Radarr (`/movies` by default)
+- Triggers `MoviesSearch` immediately after each successful add — Radarr begins
+  searching for the movie right away
+- Adds to the first accessible root folder in Radarr
 - TMDB ID match preferred over title; title fallback handles edge cases

 ---
@@ -78,6 +78,9 @@ something new, write the tool. Store it here. Find it at 2am next time.
 **Lifecycle Tools** — Backup, setup, and migration support  
 `container_data_export.sh`, `recreate_shares.sh`, `claude_startup.sh`

+**Library Sync Bootstrap** — Close the gap between Emby and arr libraries  
+`emby_to_lidarr_sync.sh`, `emby_to_sonarr_sync.sh`, `emby_to_radarr_sync.sh`
+
 ---

 ## ━━━ RELATIONSHIP TO OTHER FOLDERS ━━━
@@ -122,6 +125,9 @@ The relationship is one-way: Tools act on state that other scripts have written.
 | `recreate_shares.sh` | Share directories missing after fresh install or disk rebuild | After fresh unRAID install or disk replacement on HOST2 |
 | `continuous_scripts_status.sh` | Need a live view of watchdog and fallback state | Any time — manual dashboard, no schedule |
 | `claude_startup.sh` | Claude Code session setup after reboot — symlinks persistent storage | After each unRAID reboot, or called by array_started.sh |
+| `emby_to_lidarr_sync.sh` | Add all Emby album artists not yet tracked in Lidarr | After Lidarr setup, database wipe, or when you suspect gaps |
+| `emby_to_sonarr_sync.sh` | Add all Emby TV series not yet tracked in Sonarr | After Sonarr setup, database wipe, or when you suspect gaps |
+| `emby_to_radarr_sync.sh` | Add all Emby movies not yet tracked in Radarr | After Radarr setup, database wipe, or when you suspect gaps |

 ---

@@ -145,6 +151,10 @@ Situation arises
 │  recreate_shares             ◄── fresh HOST2 setup or disk rebuild    │
 │  continuous_scripts_status   ◄── manual status check at any time     │
 │  claude_startup              ◄── after each unRAID reboot             │
+│                                                                       │
+│  emby_to_lidarr_sync         ◄── Lidarr setup / database wipe / gap  │
+│  emby_to_sonarr_sync         ◄── Sonarr setup / database wipe / gap  │
+│  emby_to_radarr_sync         ◄── Radarr setup / database wipe / gap  │
 └──────────────────────────────────────────────────────────────────────┘
      │
      ▼
@@ -21,12 +21,33 @@
 #   3. For each played artist not in Lidarr → add to Lidarr
 #
 # ==============================================================================================
-# USAGE
+# OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
-#   emby_to_lidarr_sync.sh             — add all played artists not in Lidarr
+# Root Required
+#   acquire_lock requires root. Script exits cleanly if not root.
+#
+# Dry-Run Mode
+#   --dry-run shows all artists that would be added without making any Lidarr API calls.
+#   Always run first when closing the gap after a fresh Lidarr install or database wipe.
+#
+# Add-Only
+#   Only adds artists to Lidarr. Items already tracked (by name) are skipped without
+#   modification. Safe to run multiple times — the second run finds nothing to add.
+#
+# ==============================================================================================
+# CONFIGURATION (master_host*.conf)
+# ==============================================================================================
+#
+#   HOST*_LIDARR_URL / HOST*_LIDARR_API_KEY    — Lidarr connection (aliased by detect_hosts)
+#   HOST*_EMBY_URL   / HOST*_EMBY_API_KEY      — Emby connection (aliased by detect_hosts)
+#
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+#   emby_to_lidarr_sync.sh             — add all album artists not in Lidarr
 #   emby_to_lidarr_sync.sh --dry-run   — show what would be added, no changes
-#   emby_to_lidarr_sync.sh --days N    — limit to plays in the last N days
 #   emby_to_lidarr_sync.sh --log       — verbose output
 #
 # ==============================================================================================
@@ -23,7 +23,29 @@
 # falling back to case-insensitive title comparison.
 #
 # ==============================================================================================
-# USAGE
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# Root Required
+#   acquire_lock requires root. Script exits cleanly if not root.
+#
+# Dry-Run Mode
+#   --dry-run shows all movies that would be added without making any Radarr API calls.
+#   Always run first when closing the gap after a fresh Radarr install or database wipe.
+#
+# Add-Only
+#   Only adds movies to Radarr. Items already tracked by TMDB ID or title are skipped
+#   without modification. Safe to run multiple times — the second run finds nothing to add.
+#
+# ==============================================================================================
+# CONFIGURATION (master_host*.conf)
+# ==============================================================================================
+#
+#   HOST*_RADARR_URL / HOST*_RADARR_API_KEY    — Radarr connection (aliased by detect_hosts)
+#   HOST*_EMBY_URL   / HOST*_EMBY_API_KEY      — Emby connection (aliased by detect_hosts)
+#
+# ==============================================================================================
+# RUNTIME MODES
 # ==============================================================================================
 #
 #   emby_to_radarr_sync.sh             — add all untracked movies to Radarr
@@ -23,7 +23,30 @@
 # falling back to case-insensitive title comparison.
 #
 # ==============================================================================================
-# USAGE
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# Root Required
+#   acquire_lock requires root. Script exits cleanly if not root.
+#
+# Dry-Run Mode
+#   --dry-run shows all series that would be added without making any Sonarr API calls.
+#   Always run first when closing the gap after a fresh Sonarr install or database wipe.
+#
+# Add-Only
+#   Only adds series to Sonarr. Items already tracked by TVDB ID or title are skipped
+#   without modification. Safe to run multiple times — the second run finds nothing to add.
+#
+# ==============================================================================================
+# CONFIGURATION (master.conf / master_host*.conf)
+# ==============================================================================================
+#
+#   SONARR_EMBY_LIBRARIES                      — Emby library names to scan (master.conf)
+#   HOST*_SONARR_URL / HOST*_SONARR_API_KEY    — Sonarr connection (aliased by detect_hosts)
+#   HOST*_EMBY_URL   / HOST*_EMBY_API_KEY      — Emby connection (aliased by detect_hosts)
+#
+# ==============================================================================================
+# RUNTIME MODES
 # ==============================================================================================
 #
 #   emby_to_sonarr_sync.sh             — add all untracked series to Sonarr