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.

Partnership/share_setup.sh

@@ -25,7 +25,96 @@
 # Remote admin assigns disk sets from the Unraid UI after onboarding.
 #
 # ==============================================================================================
-# USAGE
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Resolve the mirror and its Tailscale IP — unresolvable aborts before any remote call
+#   2. Detect the remote's appdata cache pool from its own appdata.cfg (default: cache)
+#   3. For each path across the owner's daily/weekly/critical/intermediate share lists:
+#        a. Extract the top-level Unraid share name
+#        b. Remote already has a .cfg for it? → skip, never modify
+#        c. Otherwise use the LOCAL .cfg as a template:
+#             - substitute the remote's detected pool
+#             - clear disk include/exclude (disk layouts differ per server)
+#        d. Write the .cfg to remote /boot/config/shares/ and mkdir -p the share directory
+#        e. Sub-paths (e.g. appdata-Fallback/Critical-Data) get their subdir created after
+#           the top-level share exists
+#
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Create Only, Never Modify
+#   An existing remote .cfg is always left alone. The remote admin may have deliberately
+#   tuned a share's pool, allocation or disk set — this script has no way to tell an
+#   intentional setting from a stale one, so it never overwrites.
+#
+# Disk Layout Is Not Portable
+#   Include/exclude lists are cleared rather than copied, because the two servers have
+#   different disks. Copying the owner's disk set onto a mirror with a different array
+#   would produce a share pointing at disks that do not exist.
+#
+# Detect the Pool, Do Not Assume It
+#   The remote's cache pool name is read from its own appdata.cfg rather than hardcoded or
+#   copied from local. Pool names differ per server and a wrong one silently lands appdata
+#   on the array.
+#
+# Media Shares Land Array-Only
+#   Shares with shareUseCache=no are created without a pool assignment. Disk sets are the
+#   remote admin's call from the Unraid UI after onboarding.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# Root Enforcement
+#   Reads $SSH_KEY from /root/.ssh and the local /boot/config/shares/*.cfg, and writes share
+#   configs onto the mirror as root.
+#
+# Lock Acquisition
+#   acquire_lock prevents concurrent runs. Two instances could both observe a share as
+#   missing and race to create it.
+#
+# Host Detection
+#   detect_hosts() resolves REMOTE_SERVER_NAME — the mirror this script targets.
+#
+# Mirror Resolution Guard
+#   Aborts if REMOTE_SERVER_NAME is unset or its Tailscale IP cannot be resolved, before any
+#   remote command is attempted.
+#
+# Existing Share Protection
+#   A remote .cfg that already exists is never touched — see Create Only above.
+#
+# SSH Timeouts and BatchMode
+#   Every remote call uses ConnectTimeout and BatchMode=yes, so an unreachable or
+#   password-prompting mirror fails fast instead of hanging the onboarding run.
+#
+# Pool Fallback
+#   An undetectable remote pool defaults to "cache" rather than writing an empty pool name
+#   into the share config.
+#
+# Dry Run Support
+#   --dry-run reports every share it would create and writes nothing.
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# host*.conf (aliased by detect_hosts())
+#
+#   HOST*_DAILY_SYNC_SHARES / _WEEKLY_ / _CRITICAL_ / _INTERMEDIATE_
+#       The share lists this script reads. Any path appearing in one of these on the owner
+#       is a share the mirror is expected to have.
+#
+#   SSH_KEY
+#       Key used for every remote call. Written by ssh_setup.sh.
+#
+# master.conf
+#
+#   HOST* — hostnames, used to resolve the mirror via detect_hosts()
+#
+# ==============================================================================================
+# RUNTIME MODES
 # ==============================================================================================
 #
 # share_setup.sh
@@ -40,9 +129,21 @@ set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/../load_config.sh"
-detect_hosts
 parse_args "$@"
 
+# ==============================================================================================
+# ━━━ Setup ━━━
+# ==============================================================================================
+# Reads $SSH_KEY from /root/.ssh, reads local /boot/config/shares/*.cfg, and writes share
+# configs onto the mirror as root.
+[[ "$EUID" -ne 0 ]] && { error "Must be run as root"; exit 1; }
+
+# Writes share .cfg files to the mirror. Two concurrent runs could both see a share as
+# missing and race to create it.
+acquire_lock
+
+detect_hosts
+
 # ── Resolve mirror ────────────────────────────────────────────────────────────────────────────
 
 [[ -z "${REMOTE_SERVER_NAME:-}" ]] && { error "Cannot determine mirror hostname — check HOST* in master.conf"; exit 1; }