Add full banner headers to all scripts across the codebase

Every script now has the established header format: PURPOSE with ─────── separator, OPERATIONAL MODEL, DESIGN PRINCIPLES, OPERATIONAL SAFEGUARDS, CONFIGURATION, and RUNTIME MODES — structured with full ====== banner sections throughout. Orchestrators converted from compact ── inline format to full banners. Stale emby-fallback and dirty sync references removed from Plugin/user_script_plug-in.sh.
2026-06-26 18:50:05 -04:00
parent 1003bee72a
commit f92ee4064b
51 changed files with 1822 additions and 563 deletions
@@ -15,7 +15,29 @@
 # Accepts --host=HOST2 to refresh a single host (used by the UI refresh button).
 #
 # ==============================================================================================
-# USAGE
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Cache-First, Never Live on Page Load
+#   Remote arr APIs have non-trivial latency — calling them on every page view
+#   would make the arrs page slow and fragile. Writing to /tmp/vv_cache/ on a
+#   2-hour schedule decouples page load time from network availability.
+#
+# Single-Host Refresh for UI
+#   The UI refresh button passes --host=HOSTN to update one host without waiting
+#   for the full 2-hour cycle. Keeps the cache fresh when a user requests it.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+#   acquire_lock    — prevents concurrent cache write runs
+#   detect_hosts()  — MY_ID and partner host list
+#   SSH reachability — skips a host cleanly if it cannot be reached
+#   /tmp/vv_cache/  — auto-created if missing; cleared on reboot (intentional)
+#
+# ==============================================================================================
+# RUNTIME MODES
 # ==============================================================================================
 #
 #   remote_arr_cache_writer.sh               — refresh all remote hosts