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.

Plugin/unraid/System_Essentials/mover_stop.sh

@@ -29,6 +29,28 @@
 # used as a last resort and may leave a file split across cache and array.
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Warn the Room First
+#   A wall message goes out before the mover is signalled. The mover moves other people's
+#   data between cache and array; anyone watching a transfer deserves to know why it stopped.
+#
+# Graceful First, Forced Last
+#   SIGTERM with a configurable window, then SIGKILL only if it is ignored. The mover is
+#   mid-file-move by definition — giving it the chance to finish the current file and exit
+#   cleanly is the difference between a stopped transfer and a half-moved file.
+#
+# Not Running Is Success
+#   An absent mover exits 0. Callers use this as a precondition ("ensure the mover is not
+#   running"), not as a command that must find something to kill — treating "already stopped"
+#   as failure would abort every reboot on a quiet system.
+#
+# Stop, Never Start
+#   This script has no counterpart that restarts the mover. Unraid's own schedule owns when
+#   the mover runs; this only ever removes it from the picture for a window.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #

Plugin/unraid/System_Essentials/php_fpm_max_children.sh

@@ -41,6 +41,19 @@
 #   7. Read back config to confirm value applied
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Read the current pm.max_children from the PHP-FPM pool config
+#   2. Already at or above the target → exit silently, no write, no restart
+#   3. Otherwise rewrite the value and restart PHP-FPM via the adapter
+#   4. Verify PHP-FPM came back up
+#
+# Runs at array start, before the WebGUI sees real load. The setting does not survive an
+# unRAID update — the OS replaces the pool config — which is why this reapplies every boot
+# rather than being a one-time install step.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #

Plugin/unraid/System_Essentials/unraid_api_key_renew.sh

@@ -28,6 +28,19 @@
 #   without a separate sync step.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Check whether a Varaverk key already exists in the unraid-api registry
+#   2. Create or overwrite it — the registry is ephemeral, so re-registering is the norm
+#   3. Write the resulting key into this host's conf, replacing any previous value
+#   4. Report whether the key was created, refreshed, or unchanged
+#
+# Runs at array start. The registry does not survive OS updates or an unraid-api restart,
+# which is why this re-registers unconditionally rather than only when the key is missing —
+# a key present in the conf but absent from the registry is the exact failure it repairs.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
@@ -37,6 +50,22 @@
 #   dry-run mode    — shows what would happen without touching anything
 #
 # ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# host*.conf
+#
+#   HOST*_UNRAID_API_KEY
+#       Written by this script every array start. Read by the plugin's PHP for enhanced
+#       monitoring. Treated as output, not input — an existing value is always replaced,
+#       because a conf value that no longer matches the registry is precisely the broken
+#       state this exists to fix.
+#
+# Platform-owned:
+#
+#   The unraid-api service registry — ephemeral, cleared by OS updates and service restarts.
+#
+# ==============================================================================================
 # RUNTIME MODES
 # ==============================================================================================
 #
@@ -56,6 +85,10 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/../../../load_config.sh"
 
 parse_args "$@"
+
+# Rewrites the API key into host*.conf and registers it with the unraid-api service.
+[[ "$EUID" -ne 0 ]] && { error "Must be run as root"; exit 1; }
+
 acquire_lock
 detect_hosts
 

Plugin/unraid/System_Essentials/user_scripts_stop.sh

@@ -32,6 +32,25 @@
 #   tree mid-execution.
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Name the Scripts, Not Just the PIDs
+#   Output resolves each process to the script it is running. "Stopping 4 processes" tells
+#   an operator nothing they can act on; "stopping mover_tuning, preclear" tells them
+#   exactly what they are about to lose and whether they should wait.
+#
+# Targeted, Never Blanket
+#   Only processes spawned by the User Scripts plugin are matched. A broad pattern would
+#   catch unrelated shells and Varaverk's own scripts — including, during a reboot sequence,
+#   the very script doing the stopping.
+#
+# Shutdown Step and Manual Tool, Same Behaviour
+#   Called automatically by server_reboot.sh and usable by hand on a stuck script. It takes
+#   no "reboot mode" — the correct action is identical either way, and a mode flag would be
+#   a second code path that only ever runs unattended.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
@@ -51,6 +70,21 @@
 #   No processes running = log() only, no visible output.
 #
 # ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# No config vars. Targets are discovered from running processes rather than from a list,
+# because the User Scripts plugin owns what exists and any list here would go stale.
+#
+# Platform-owned:
+#
+#   The unRAID User Scripts plugin's script directory and the processes it spawns. Matching
+#   is scoped to those — see Targeted, Never Blanket above for why that matters during a
+#   reboot sequence.
+#
+# Called by server_reboot.sh as a shutdown step; also safe to run by hand.
+#
+# ==============================================================================================
 # RUNTIME MODES
 # ==============================================================================================
 #