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
@@ -17,7 +17,7 @@
 # fetch as fallback.
 #
 # ==============================================================================================
-# FLOW
+# OPERATIONAL MODEL
 # ==============================================================================================
 #
 #   1. Pull play completions from Emby activity log (all time, or --days N)
@@ -25,6 +25,29 @@
 #   3. For each played artist not in Lidarr → add to Lidarr
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Add-Only, Never Remove
+#   The tool only adds artists 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 MusicBrainz 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
 # ==============================================================================================
 #
@@ -40,7 +63,7 @@
 #   modification. Safe to run multiple times — the second run finds nothing to add.
 #
 # ==============================================================================================
-# CONFIGURATION (host*.conf)
+# CONFIGURATION
 # ==============================================================================================
 #
 #   HOST*_LIDARR_URL / HOST*_LIDARR_API_KEY    — Lidarr connection (aliased by detect_hosts)