Complete the header template across Partnership, Kernel, Deployment and Plugin

Finishes the pass: every script now documents its safeguards, and the deliberate absences
in the sourced libraries are recorded so they are not "corrected" later.

common.sh

@@ -2,9 +2,103 @@
 # ==============================================================================================
 # ================================= COMMON LIBRARY =============================================
 # ==============================================================================================
+#
+# PURPOSE
+# ─────────────────────────────────────────────────────────────────────────────
 # Shared functions used by every script in the ecosystem.
 # Sourced automatically by load_config.sh — do not source directly.
 #
+# ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# A pure function library. It defines and returns; it starts nothing on its own.
+#
+# Load order matters and is owned by load_config.sh:
+#   varaverk.cfg → master.conf → host*.conf → common.sh → Plugin/$PLATFORM/adapter.sh
+#
+# common.sh is sourced AFTER the conf files because detect_hosts() and the health checks
+# need HOST* and the thresholds to already exist. It is sourced BEFORE the adapter so the
+# adapter can rely on log()/warn()/error() being defined.
+#
+# Note it defines detect_hosts() but never calls it. MY_ID and REMOTE_ID stay unset until a
+# script calls it itself — anything building HOST*-prefixed variable names must do so after
+# that call, not before.
+#
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Define, Never Act
+#   Sourcing this file changes no system state: no containers touched, no files written, no
+#   locks taken, no host detected. Every script in the ecosystem sources it, including
+#   read-only reporting ones, so anything that acted here would act everywhere.
+#
+# One Implementation of Each Shared Behaviour
+#   Locking, host detection, notification, retry and timeout wrapping live here once. When
+#   a safeguard needs strengthening it is strengthened for every caller at the same moment —
+#   which is why individual scripts call acquire_lock() rather than rolling their own flock.
+#
+# Platform-Agnostic
+#   No OS-specific paths or commands. Anything Unraid-specific belongs in the adapter, which
+#   is why this file calls platform_*() rather than touching /etc/rc.d or /boot directly.
+#
+# Callers Own Policy
+#   Helpers return status; they do not decide what failure means. retry_docker() reports
+#   that a command failed after N attempts — whether that aborts a run, skips an item, or
+#   raises a notification is the caller's call, and only the caller has the context.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# No Root, No Lock, No detect_hosts on Load — Deliberate
+#   This is a sourced library and must stay inert. A root check here would fire for every
+#   script including ones that legitimately do not need it; a lock would be taken on every
+#   source; calling detect_hosts() automatically would exit the caller on an unknown
+#   hostname before it had a chance to handle that itself. Do not add them.
+#
+# Safe Defaults on Every Threshold
+#   Helpers apply :- defaults (DOCKER_TIMEOUT, RESTART_VERIFY_WAIT, RETRY_COUNT and friends)
+#   so a conf missing a key degrades to a sane value rather than an empty string that would
+#   silently disable a timeout or a retry ceiling.
+#
+# Timeout Wrapping Provided Centrally
+#   docker_cmd() and the remote helpers wrap calls in timeout, so no caller has to remember
+#   to. A hung daemon or unreachable partner cannot stall a scheduled window.
+#
+# Locking Provided Centrally
+#   acquire_lock() implements strict, wait and continuous modes in one place, so every
+#   script gets identical semantics and a fix applies everywhere at once.
+#
+# Host Identity Is Exact-Match Only
+#   detect_hosts() matches hostname exactly, with a single explicit NetBIOS-truncation
+#   fallback that requires an unambiguous candidate. No fuzzy or similarity matching — a
+#   wrong host identity would alias the wrong credentials and paths into every script.
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# Defines no config of its own. It consumes what load_config.sh has already sourced from
+# master.conf and host*.conf, and applies defaults where a key may be absent.
+#
+# Consumed broadly: DOCKER_TIMEOUT, RESTART_VERIFY_WAIT, RETRY_COUNT, SLEEP, SSH_KEY,
+# SSH_TIMEOUT, STATE_DIR, DATA_DIR, LOCK_DIR, NOTIFY_UNRAID, HOST*, and the RSYNC_*/
+# PARTNERSHIP_* gates.
+#
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+# None — sourced, never executed:
+#
+#   source "$SCRIPT_DIR/../load_config.sh"     # which sources this file
+#
+# It parses no arguments of its own. parse_args() is defined here for callers to invoke,
+# and --dry-run/--status/--log are honoured by the calling script, not by this file.
+#
+# ==============================================================================================
 # ── WHAT THIS FILE PROVIDES ───────────────────────────────────────────────────────────────────
 #   Icons            — consistent visual language across all script output
 #   Output helpers   — info, warn, error, success, log, notify