Bring script headers onto the template and close safeguard gaps

Headers claimed protections the code never had, and several destructive paths had no guard against a collapsed config value.
2026-08-01 20:37:59 -04:00
parent cdce877601
commit e8b114094a
78 changed files with 3301 additions and 277 deletions
@@ -16,7 +16,7 @@
 # fetch as fallback.
 #
 # ==============================================================================================
-# FLOW
+# OPERATIONAL MODEL
 # ==============================================================================================
 #
 #   1. Fetch all Series items from Emby (with TVDB provider IDs)
@@ -27,6 +27,29 @@
 # falling back to case-insensitive title comparison.
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Add-Only, Never Remove
+#   The tool only adds series the arr is missing. It never deletes or unmonitors anything,
+#   so the worst outcome of a bad match is an extra tracked entry — trivially reversible —
+#   rather than lost tracking on something already curated.
+#
+# Library Membership Is the Whole Criterion
+#   No scoring, no thresholds, no metadata quality gates. If it is in Emby, the arr should
+#   know about it. This is deliberately not a discovery tool; the playback_aware_* scripts
+#   own that job and its judgement calls.
+#
+# Provider ID Over Title
+#   Matching prefers the TVDB ID and falls back to case-insensitive title only when the ID
+#   is absent. Titles differ across sources by punctuation, year suffixes and articles;
+#   matching on them alone would re-add things the arr already tracks.
+#
+# Cache-First Read
+#   The arr library comes from the shared tracked-data cache, kept warm by
+#   arr_cache_prefill.sh, with a live fetch as fallback. One read regardless of library size.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
@@ -42,7 +65,7 @@
 #   without modification. Safe to run multiple times — the second run finds nothing to add.
 #
 # ==============================================================================================
-# CONFIGURATION (master.conf / host*.conf)
+# CONFIGURATION
 # ==============================================================================================
 #
 #   SONARR_EMBY_LIBRARIES                      — Emby library names to scan (master.conf); empty = all libraries