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.

Watchdogs/resource_watchdog.sh

@@ -42,6 +42,32 @@
 #   Cleared when pressure resolves and containers are restarted.
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Graduated Response
+#   Pressure is answered with the smallest effective action first — throttle,
+#   then pause, then stop. Each level is only reached because the level below it
+#   failed to relieve pressure. Nothing jumps straight to stopping containers.
+#
+# Reversibility First
+#   docker pause suspends a container without losing its state and is instantly
+#   reversible, so it is preferred at level 2. docker stop, which discards
+#   in-memory state, is held back to level 3 and applied only to services
+#   explicitly listed as expendable in RW_STOP_CONTAINERS.
+#
+# Hysteresis on Recovery
+#   Restoring requires RW_RECOVER_CYCLES consecutive clear cycles and
+#   de-escalates one level at a time. Recovering instantly on a single good
+#   reading would flap — restore, re-trigger, restore — under sustained load.
+#
+# Cross-Watchdog Coordination
+#   Level 3 publishes mem_shutdown_active=true so docker_watchdog.sh defers its
+#   restart logic. Two watchdogs acting on the same containers with opposite
+#   intent would otherwise fight: one stopping to free RAM, the other restarting
+#   to restore health.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
@@ -51,13 +77,45 @@
 # Single Instance Lock
 #   acquire_lock prevents concurrent runs from racing on state file writes.
 #
+# Docker Presence Check
+#   Verifies the docker binary exists before any pressure response — every
+#   level-2 and level-3 action depends on it.
+#
+# Host Detection
+#   detect_hosts() aliases HOST*_RW_PAUSE_CONTAINERS, HOST*_RW_STOP_CONTAINERS
+#   and the downloader credentials to the correct host's values.
+#
+# State File Verification
+#   Exits if RW_STATE_FILE cannot be created. Without durable state the script
+#   cannot track recovery cycles or know which containers it paused, and would
+#   never restore them.
+#
 # RW_CRITICAL_CONTAINERS
-#   Containers listed here are never paused or stopped regardless of pressure level.
+#   Containers listed here are never paused or stopped regardless of pressure
+#   level. Enforced by is_critical(), which gates both the pause and the stop
+#   path — not just the configuration lists.
 #
 # RW_ENABLED Flag
 #   Set RW_ENABLED=false to disable the entire script without removing it from
 #   the orchestrator schedule.
 #
+# Timeout Protection
+#   All docker commands wrapped in a 15 second timeout. Pressure response runs
+#   during a degraded system, which is exactly when the daemon is most likely
+#   to be slow — a hang here would stall the whole watchdog chain every minute.
+#
+# Downloader Availability Guards
+#   SABnzbd and qBittorrent throttling no-ops when the service is disabled or
+#   its URL/credentials are unset. A missing downloader never blocks the
+#   container-level pressure response.
+#
+# Recovery Hysteresis
+#   Restoration requires RW_RECOVER_CYCLES consecutive clear cycles and
+#   de-escalates one level per cycle, preventing flapping under sustained load.
+#
+# Dry Run Support
+#   --dry-run reports every throttle, pause and stop without performing any.
+#
 # ==============================================================================================
 # CONFIGURATION
 # ==============================================================================================