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.

Monitors/backup_verify.sh

@@ -19,6 +19,24 @@
 # to HOST*_DAILY_SYNC_SHARES. Both aliased by detect_hosts().
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Pre-flight — connectivity to the remote, remote array mounted, version parity
+#   2. Resolve the share list (BACKUP_VERIFY_SHARES, else DAILY_SYNC_SHARES)
+#   3. Per share:
+#        a. Randomly sample BACKUP_VERIFY_SAMPLE files above BACKUP_VERIFY_MIN_SIZE
+#        b. Compute each file's MD5 locally
+#        c. Compute the same file's MD5 on the remote over SSH
+#        d. Classify: MATCH | MISMATCH | MISSING
+#   4. Report per-share and overall counts; notify on any MISMATCH and on
+#      significant MISSING counts
+#
+# Sampling rather than full verification is deliberate — a complete checksum of every
+# mirrored file would take longer than the interval between runs. Random sampling over
+# a weekly cadence surfaces systematic corruption without ever reading the whole library.
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #
@@ -56,9 +74,6 @@
 # SSH Timeout
 #   SSH_TIMEOUT caps all SSH calls. One hung connection does not block the run.
 #
-# Notification Validated
-#   platform_require_cmd confirms the notify script is present before use.
-#
 # ==============================================================================================
 # CONFIGURATION
 # ==============================================================================================

Monitors/bandwidth_monitor.sh

@@ -17,6 +17,24 @@
 # last 7 days activity timeline, any transfers or days exceeding BANDWIDTH_WARN_GB.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# Log mode (--log-transfer), called by rsync.sh after every sync:
+#   1. Append one line: YYYY-MM-DD|HH:MM|profile|duration|status|bytes
+#   2. Trim entries older than BANDWIDTH_LOG_RETENTION days
+#   One bounded write per rsync run — never grows without limit, never rewrites history.
+#
+# Report mode (default), scheduled weekly:
+#   1. Read the accumulated log
+#   2. Aggregate per profile — run count, total bytes, average duration, failures
+#   3. Build a 7-day activity timeline
+#   4. Flag any single transfer or any single day exceeding BANDWIDTH_WARN_GB
+#
+# The two modes never run together: logging is a side effect of rsync, reporting is a
+# scheduled read. Report mode never writes to the log.
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #
@@ -46,9 +64,6 @@
 # Log Directory Guard
 #   Creates the log directory if it doesn't exist. Exits cleanly if unwritable.
 #
-# Notification Validated
-#   platform_require_cmd confirms the notify script is present before use.
-#
 # ==============================================================================================
 # CONFIGURATION
 # ==============================================================================================

Monitors/cert_monitor.sh

@@ -15,6 +15,23 @@
 # separate message lists all CRITICAL domains. Not one notification per domain.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Validate openssl is present (platform_require_cmd) — without it nothing can be checked
+#   2. Per domain in CERT_MONITOR_DOMAINS:
+#        a. Open a real TLS connection with openssl s_client
+#        b. Parse notAfter from the served certificate
+#        c. Compute days remaining
+#        d. Classify: HEALTHY (silent) | WARNING (≤ CERT_WARN_DAYS)
+#                     | CRITICAL (≤ CERT_CRIT_DAYS) | FAILED (no connect / no parse)
+#   3. Batch by severity — one notification listing all WARNING domains, a separate
+#      one listing all CRITICAL domains
+#
+# A domain that fails to connect is reported as FAILED rather than assumed healthy or
+# assumed expired — an unreachable host and an expiring cert are different problems.
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #
@@ -44,8 +61,10 @@
 #   CERT_TIMEOUT caps each openssl connection attempt. One unreachable domain
 #   does not block the remaining domains.
 #
-# Notification Validated
-#   platform_require_cmd confirms openssl and notify script are present before use.
+# openssl Validated
+#   platform_require_cmd confirms openssl is present before any domain is checked — every
+#   check depends on it, so a missing binary is reported as itself rather than as every
+#   domain failing. The notify script is validated separately by the platform adapter.
 #
 # ==============================================================================================
 # CONFIGURATION

Monitors/emby_session_report.sh

@@ -18,6 +18,22 @@
 # configuration issue. Silent on clean runs.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Reachability — Emby API responding; unreachable exits cleanly rather than
+#      reporting an empty library as a real result
+#   2. Server info and uptime
+#   3. Active sessions — count, and the transcode-to-direct-play ratio
+#   4. Library counts — movies, episodes, songs
+#   5. Activity history over the last EMBY_REPORT_DAYS
+#   6. Top EMBY_REPORT_TOP_N items and most active users
+#   7. Ramdisk transcode status, read from the shared transcode state
+#
+# Every figure is queried fresh. The only notification is the transcode-ratio warning;
+# everything else is report output.
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #
@@ -54,9 +70,6 @@
 #   detect_hosts() aliases HOST*_EMBY_URL and HOST*_EMBY_API_KEY → EMBY_URL / EMBY_API_KEY.
 #   Each server reports on its own Emby instance automatically.
 #
-# Notification Validated
-#   platform_require_cmd confirms the notify script is present before use.
-#
 # ==============================================================================================
 # CONFIGURATION
 # ==============================================================================================

Monitors/mesh_monitor.sh

@@ -53,6 +53,13 @@
 #   collect_hosts() populates ALL_HOST_IDS — if no HOST* vars are defined the
 #   output sections iterate over an empty array and exit cleanly.
 #
+# No Root, No Lock, No detect_hosts — Deliberate
+#   This is the one script in the ecosystem that intentionally omits all three, and
+#   they should not be added. It writes nothing, so there is no state for a lock to
+#   protect and no privileged operation to justify a root gate. It reports on every
+#   node rather than acting as one, so detect_hosts() would narrow it to this host's
+#   aliases — the opposite of what it is for. Every HOST* var is read directly instead.
+#
 # ==============================================================================================
 # CONFIGURATION
 # ==============================================================================================

Monitors/smart_health.sh

@@ -19,6 +19,26 @@
 # from master.conf if dynamix.cfg is not found.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Validate smartctl is present (platform_require_cmd)
+#   2. Resolve temperature thresholds — dynamix.cfg first, master.conf as fallback
+#   3. Enumerate drives, skipping anything in SMART_IGNORE_DRIVES
+#   4. Per drive, read live SMART attributes and evaluate:
+#        overall status              FAILED           → critical
+#        Reallocated_Sector_Ct  > 0                   → concerning
+#        Current_Pending_Sector > 0                   → concerning
+#        Offline_Uncorrectable  > 0                   → critical
+#        Temperature_Celsius    vs warn/crit thresholds
+#        Power_On_Hours                               → informational only
+#      NVMe drives expose different attribute names — detected and mapped automatically.
+#   5. Report; notify only when something crosses a threshold. Silent when all pass.
+#
+# Read-only throughout — this queries attributes the drive already maintains and never
+# starts a self-test. Running one is smart_long_test.sh's job.
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #
@@ -55,8 +75,9 @@
 #   Reads hot/max/hotssd/maxssd from dynamix.cfg so smart_health.sh and unRAID's
 #   dashboard use the same thresholds. Falls back to master.conf values if not found.
 #
-# Notifications Validated
-#   platform_require_cmd confirms smartctl and notify script are present before use.
+# smartctl Validated
+#   platform_require_cmd confirms smartctl is present before any drive is queried. The
+#   notify script is validated separately by the platform adapter.
 #
 # ==============================================================================================
 # CONFIGURATION

Monitors/system_tuning_monitor.sh

@@ -65,9 +65,6 @@
 #   Trim uses tmp file + mv — partial writes during log rotation cannot corrupt
 #   the accumulated history.
 #
-# Notification Validated
-#   platform_require_cmd confirms the notify script is present before use.
-#
 # ==============================================================================================
 # STATE FILES
 # ==============================================================================================

Monitors/weekly_health_digest.sh

@@ -76,8 +76,10 @@
 #   smart profile produces no output and no notification when nothing worth
 #   reporting is found.
 #
-# Notifications Validated
-#   platform_require_cmd confirms notify and openssl are present before use.
+# openssl Validated — Non-Fatal
+#   platform_require_cmd checks openssl and, unlike the other monitors, only warns if it
+#   is missing: the SSL section is skipped and the rest of the digest still runs. The
+#   notify script is validated separately by the platform adapter.
 #
 # ==============================================================================================
 # CONFIGURATION

Monitors/zfs_memory_snapshot.sh

@@ -79,9 +79,6 @@
 # Docker Stats Timeout
 #   DOCKER_TIMEOUT caps docker stats calls. A hung daemon does not block the report.
 #
-# Notification Validated
-#   platform_require_cmd confirms the notify script is present before use.
-#
 # ==============================================================================================
 # STATE FILES
 # ==============================================================================================