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/build.sh

@@ -26,6 +26,73 @@
 #   rebuild cron when the array mounts. Scripts stay on appdata (git clone).
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Resolve version — first argument, else today's date as YYYY.MM.DD
+#   2. Verify makepkg exists (Slackware tooling — this only runs on unRAID)
+#   3. Stage Plugin/unraid/ into the install layout the package expects
+#   4. makepkg the stage into Plugin/dist/<name>-<version>-noarch-1.txz
+#   5. sha256sum the result and write the .sha256 alongside it
+#   6. Rewrite <!ENTITY version> and <!ENTITY sha256> in varaverk.plg so the .plg
+#      always points at the package just built
+#
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Release Path, Not the Dev Path
+#   Day-to-day work uses plugin_setup.sh, which symlinks the source directory so edits are
+#   live immediately. This produces the artifact unRAID reinstalls from flash on every boot.
+#   Keeping the two separate is what allows fast iteration without shipping half-finished
+#   files into a package.
+#
+# The .plg Always Matches the Package
+#   Version and checksum are written into varaverk.plg in the same run that produces the
+#   .txz. A .plg pointing at a checksum it was not built against fails to install with a
+#   mismatch error, so the two are never updated independently.
+#
+# Date Version by Default
+#   An omitted version becomes today's date. Builds are therefore always ordered and always
+#   unique without anyone maintaining a counter.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# No Root — Deliberate
+#   Writes only into Plugin/dist/ and rewrites varaverk.plg inside the repo. It installs
+#   nothing and touches nothing under /usr or /boot, so it needs no privilege. Requiring
+#   root would mean building release artifacts as root for no reason.
+#
+# makepkg Presence Check
+#   Aborts immediately if makepkg is missing, with a note that this runs on unRAID. The
+#   Slackware toolchain is not present on a normal dev machine and a partial build would be
+#   worse than a clear refusal.
+#
+# Checksum Written From the Real Artifact
+#   The sha256 is computed from the .txz that was just produced, never assumed or carried
+#   forward, so the .plg cannot advertise a checksum for a different build.
+#
+# Staged Build
+#   The package is assembled from a staging directory rather than from the live source
+#   tree, so an in-progress edit cannot end up inside a release artifact.
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# None — this is a build tool, not a runtime script. It reads no conf and calls no
+# load_config.sh.
+#
+# Inputs are positional and derived:
+#   $1                  version string (default: today, YYYY.MM.DD)
+#   Plugin/unraid/      source tree that gets packaged
+#   Plugin/varaverk.plg rewritten in place with the new version and checksum
+#
+# Output: Plugin/dist/<name>-<version>-noarch-1.txz and its .sha256
+#
+# ==============================================================================================
 # RUNTIME MODES
 # ==============================================================================================
 #

Plugin/plugin_setup.sh

@@ -14,9 +14,52 @@
 # immediately without re-running this script.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Detect the OS from /etc/*-version markers
+#   2. Resolve Plugin/<os>/ as the source — missing means abort before any change
+#   3. Inspect the web server's plugin location:
+#        symlink already        → remove it, it will be recreated
+#        real directory         → refuse, this is an existing install to clean up by hand
+#        absent                 → proceed
+#   4. Create the symlink
+#
+# After this, every edit under Plugin/<os>/ is live immediately — that is the whole point,
+# and why this is the development path rather than build.sh's packaged one.
+#
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Symlink, Not Copy
+#   The web server points at the repo rather than holding its own copy, so there is exactly
+#   one source of truth for the plugin's PHP. A copy would drift the moment anyone edited
+#   either side, and the drift would only surface as a UI behaving unlike the code.
+#
+# Run Once, By Hand
+#   Never scheduled. It performs a one-time structural change to where the web server looks;
+#   putting that on a timer would mean an unattended job could recreate a symlink over a
+#   deliberate manual install.
+#
+# Refuse, Do Not Replace
+#   A real directory at the target is left alone and the script exits. That directory is a
+#   genuine installation, and silently deleting it to make room for a symlink would discard
+#   an install this script did not create.
+#
+# OS Detected, Not Assumed
+#   The source directory comes from the detected OS, so the same script works unchanged on a
+#   second platform once Plugin/<os>/ exists — matching the adapter's approach.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
+# No Root — Deliberate
+#   Run by hand during install, when the operator already has whatever privilege the web
+#   server's plugin path requires. The guards below are structural rather than privilege
+#   based: the dangerous outcome here is clobbering an existing install, not lacking rights.
+#
 # Idempotent Symlink
 #   Removes any existing symlink at the target before recreating it. Safe to
 #   re-run after a repo move without leaving stale paths.

Plugin/unraid/Partnership/containers.sh

@@ -23,6 +23,82 @@
 #   - Deployed stack tracking via _STACK_DEPLOYED / _STACK_FAILED counters
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Platform Adapter, Same Contract as adapter.sh
+#   Container deployment is Unraid-specific — CA XML templates, dockerMan paths, the
+#   templates-user directory. Confining it here means the partnership scripts contain no
+#   Unraid knowledge and a second platform is a new Partnership/containers.sh, not edits
+#   scattered through onboard and offboard.
+#
+# Deploy From the Template, Not a Copy
+#   Containers are created from the CA XML the operator already maintains, so a partnership
+#   deployment produces the same container the Unraid UI would. Hand-built docker run lines
+#   would drift from the template the moment anyone edited it in the UI.
+#
+# GPU Detection Cached Per Session
+#   The remote GPU type is probed once and reused. Onboarding deploys several containers and
+#   each would otherwise repeat the same SSH round-trip to learn an answer that cannot change
+#   mid-run.
+#
+# Count Outcomes, Do Not Abort
+#   Failures increment _STACK_FAILED rather than exiting. A stack deployment that fails on
+#   one container should report which one and continue — the caller owns whether a partial
+#   stack is acceptable, and it is the only side with the context to decide.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# No Root, No Lock, No detect_hosts — Deliberate
+#   Sourced by partnership_onboard.sh and partnership_offboard.sh, both of which already
+#   enforce root and hold their own strict locks. Re-checking here would be redundant, and
+#   taking a lock would deadlock against the caller's. Do not add them.
+#
+# Caller Scope Is the Contract
+#   Functions read MIRROR, MIRROR_IP, MIRROR_SSH_KEY, SSH_TIMEOUT, DRY_RUN and SCRIPTS_ROOT
+#   from the caller. That coupling is deliberate — it keeps one definition of who the mirror
+#   is — but it means these functions are only valid inside the partnership scripts and
+#   cannot be sourced standalone.
+#
+# DRY_RUN Honoured Throughout
+#   Every deploy and cleanup path checks the caller's DRY_RUN, so a dry-run onboard makes no
+#   remote container changes.
+#
+# SSH Timeouts on Every Remote Call
+#   All remote operations use the caller's SSH_TIMEOUT — an unreachable mirror cannot hang
+#   an onboard partway through a stack deployment.
+#
+# Template Existence Checked
+#   A missing CA XML is counted as a failure for that container rather than producing a
+#   container built from nothing.
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# No config vars of its own. Inputs come from the calling script's scope (see above).
+#
+# Platform paths it owns:
+#
+#   /boot/config/plugins/dockerMan/templates-user
+#       Unraid CA template directory. Source of every container definition deployed here.
+#
+# The container lists themselves live in host*.conf as HOST*_PARTNERSHIP_AUTH_STACK and
+# HOST*_PARTNERSHIP_ARR_STACK — read by the partnership scripts, passed in as arguments.
+#
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+# None — sourced, never executed:
+#
+#   source "$SCRIPTS_ROOT/Plugin/$PLATFORM/Partnership/containers.sh"
+#
+# No argument parsing and no flags. Dry-run behaviour comes from the caller's DRY_RUN.
+#
+# ==============================================================================================
 
 TEMPLATES_DIR="/boot/config/plugins/dockerMan/templates-user"
 

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
 # ==============================================================================================
 #

Plugin/unraid/Tools/api_cache_writer.sh

@@ -13,6 +13,58 @@
 # RAM-speed reads and auto-cleared on reboot.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# A one-line shim: exec php on api_cache_writer.php in the same directory.
+#
+# All logic lives in the PHP, because the payload builders (vv_monitor_*, vv_arrs_*) are PHP
+# functions shared with the API endpoints. Reimplementing them in bash would mean two
+# implementations of the same payload drifting apart.
+#
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# A Shim, Not a Program
+#   This file exists only because the scheduler runs shell scripts and the work is PHP. It
+#   deliberately contains no logic — anything added here would be logic the API endpoints
+#   do not share, which is exactly the drift it exists to prevent.
+#
+# Same Builders as the Live API
+#   The cache is written by the same functions that serve a live request, so a cached
+#   response and a ?live=1 response cannot disagree in shape.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# No Root, No Lock — Deliberate
+#   Writes only to /tmp/vv_cache as whatever user the scheduler runs as, and a stale cache
+#   is self-correcting on the next minute's run. There is no privileged operation to gate
+#   and no state worth locking: a torn cache file is replaced within 60 seconds, and every
+#   reader already falls back to a live call when the cache is missing or unparseable.
+#
+# Failure Is Non-Fatal by Design
+#   If the PHP fails, the cache simply is not refreshed. Pages fall back to live API calls —
+#   slower, but correct. This script must never be able to take the UI down.
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# None. Cache location and payload contents are owned by api_cache_writer.php and
+# include/config.php (VV_CACHE_DIR). Nothing is configurable from this file.
+#
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+# api_cache_writer.sh
+#     Refresh the monitor and arrs caches once. No flags — the PHP takes no arguments and
+#     there is nothing to preview, since the only effect is replacing a regenerable cache.
+#
+# ==============================================================================================
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 php "$SCRIPT_DIR/api_cache_writer.php"

Plugin/unraid/Tools/recreate_shares.sh

@@ -33,6 +33,25 @@
 #   --delete behaviour automatically. No manual cleanup needed.
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# The .cfg Files Are the Source of Truth
+#   Directories are recreated from /boot/config/shares/*.cfg rather than from a list in
+#   Varaverk's conf. Those files are Unraid's own record of what a share is and which disks
+#   it spans — anything Varaverk maintained separately would be a second copy free to drift.
+#
+# Create Only, Never Delete
+#   Missing directories are created and existing ones left alone. This runs after a rebuild,
+#   when the operator's mental model of what should exist may be out of date; removing
+#   anything on that basis is how a recovery step becomes a data loss step.
+#
+# Array Must Be Started
+#   Refuses to run without /mnt/user mounted. Creating share directories against an
+#   unmounted array writes them into the underlying root filesystem, which then shadows the
+#   real shares once the array does mount.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
@@ -58,6 +77,22 @@
 #   platform_require_cmd confirms the notify script is present before use.
 #
 # ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# No Varaverk config vars. Everything is read from Unraid's own share definitions:
+#
+#   /boot/config/shares/*.cfg
+#       One file per share. shareInclude names the disks the share spans; the directory is
+#       created on each of them. A share with no shareInclude spans all array disks.
+#
+#   /mnt/user
+#       Must be mounted — see Array Must Be Started above.
+#
+# Deliberately not driven by HOST*_*_SYNC_SHARES: this recreates every share the server
+# knows about, not only the ones Varaverk syncs.
+#
+# ==============================================================================================
 # RUNTIME MODES
 # ==============================================================================================
 #

Plugin/unraid/Tools/remote_arr_cache_writer.sh

@@ -28,6 +28,22 @@
 #   for the full 2-hour cycle. Keeps the cache fresh when a user requests it.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# Per partner host:
+#   1. Resolve its Tailscale IP — unresolvable skips that host, not the run
+#   2. SSH across and call vv_arrs_local_node() on its own PHP stack
+#   3. Write the JSON to /tmp/vv_cache/arrs_remote_<hostid>.json locally
+#
+# The remote builds its own payload rather than this host querying the remote's arr APIs
+# directly — the partner already has working local URLs and keys for its own arrs, so no
+# cross-host credentials or path mapping are involved.
+#
+# Runs every 2 hours. The arrs page reads these files for an instant first paint and falls
+# back to live calls when a file is missing or stale.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
@@ -37,6 +53,24 @@
 #   /tmp/vv_cache/  — auto-created if missing; cleared on reboot (intentional)
 #
 # ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# host*.conf
+#
+#   SSH_KEY
+#       Used to reach each partner. Written by ssh_setup.sh.
+#
+#   HOST*  — partner hostnames, resolved to Tailscale IPs at runtime
+#
+# Cache output: /tmp/vv_cache/arrs_remote_<hostid>.json
+#   tmpfs, cleared on reboot. Regenerable by definition — losing it costs one slow page
+#   load, never correctness, which is why nothing here retries hard on failure.
+#
+# No arr credentials are read locally. Each partner uses its own SONARR_*/RADARR_*/LIDARR_*
+# values on its own side, so this host never holds keys for a remote's arrs.
+#
+# ==============================================================================================
 # RUNTIME MODES
 # ==============================================================================================
 #
@@ -51,6 +85,10 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/../../../load_config.sh"
 
 parse_args "$@"
+
+# Reads $SSH_KEY from /root/.ssh to reach partner hosts.
+[[ "$EUID" -ne 0 ]] && { error "Must be run as root"; exit 1; }
+
 acquire_lock
 detect_hosts
 

Plugin/unraid/Tools/storage_migrate.sh

@@ -24,6 +24,21 @@
 #   varaverk.cron     rebuilt via PHP (job paths regenerated for new SCRIPTS_DIR)
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Determine current mode from varaverk.cfg SCRIPTS_DIR, and the requested target mode
+#      Already in the target mode → exit cleanly, nothing to do
+#   2. rsync -a --delete SRC → DST, then carry .git across so history survives the move
+#   3. Rewrite the pointers, in this order:
+#        varaverk.cfg   SCRIPTS_DIR
+#        master.conf    TARGET_DIR
+#        host*.conf     HOST*_STORAGE_MODE_INTERNAL
+#   4. Rebuild varaverk.cron via PHP so every job path points at the new SCRIPTS_DIR
+#   5. Flash mode only: sync Plugin/ back to /boot so the webUI keeps serving current PHP
+#   6. Remove the old location once the new one is confirmed in place
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #
@@ -47,6 +62,31 @@
 #   --to= required  — refuses to run without an explicit target mode
 #
 # ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# This script WRITES these rather than reading them — they are the migration's output:
+#
+#   varaverk.cfg
+#     SCRIPTS_DIR                    the authoritative install path. Everything else in the
+#                                    ecosystem derives from it, which is why it is written
+#                                    first and the cron is rebuilt from it afterwards.
+#
+#   master.conf
+#     TARGET_DIR                     kept in step with SCRIPTS_DIR
+#
+#   host*.conf
+#     HOST*_STORAGE_MODE_INTERNAL    true = /boot/config/plugins/varaverk
+#                                    false = /mnt/user/appdata/Varaverk
+#
+# Load-bearing: STATE_DIR, DATA_DIR, PERSISTENT_CONF_CACHE and the orchestrator job paths are
+# all built from SCRIPTS_DIR. Changing storage mode moves every one of them, which is why the
+# cron is regenerated rather than edited.
+#
+# In flash mode the array must be started before Varaverk can function at all — appdata is
+# not mounted before that.
+#
+# ==============================================================================================
 # RUNTIME MODES
 # ==============================================================================================
 #
@@ -68,6 +108,11 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/../../../load_config.sh"
 
 parse_args "$@"
+
+# Relocates the entire Varaverk installation with rsync --delete and rm -rf, and rewrites
+# varaverk.cfg, master.conf and host*.conf. Everything here needs root.
+[[ "$EUID" -ne 0 ]] && { error "Must be run as root"; exit 1; }
+
 acquire_lock
 detect_hosts
 

Plugin/unraid/Watchdogs/System/webgui_watchdog.sh

@@ -36,6 +36,29 @@
 #     All three failed → notify, manual intervention needed → exit 1.
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Lightest Fix First
+#   Escalation runs cheapest-to-heaviest, and stops the moment the WebGUI answers. Most
+#   hangs clear with a php-fpm restart; going straight to the heavy remedy would take the
+#   whole management interface down for a fault a service reload would have fixed.
+#
+# The WebGUI Is Not the Server
+#   An unresponsive WebGUI does not mean an unhealthy machine. Docker, the array and every
+#   share keep working while emhttp is wedged, so nothing here reboots or touches storage —
+#   the remedy stays scoped to the web stack.
+#
+# Verify After Every Step
+#   Responsiveness is re-tested between escalation steps rather than assuming a restart
+#   worked. Without that the script would walk the full ladder every time, restarting
+#   services that were already fixed one step earlier.
+#
+# Silent When Healthy
+#   Runs every cycle via system_watchdog.sh and prints nothing on a working WebGUI. A
+#   per-minute "all good" line would bury the one cycle that mattered.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #

Plugin/unraid/adapter.sh

@@ -49,6 +49,84 @@
 #   platform_push_setup_state      — push wizard setup state to WebGUI PHP
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# One Place Knows the OS
+#   Every Unraid-specific path, rc.d script and config location lives here. Scripts never
+#   branch on OS and never hardcode /etc/rc.d, /boot/config or dynamix paths. That is what
+#   makes a second platform a single new file rather than a hundred edits.
+#
+# Never Exit, Always Return
+#   No function here calls exit. A platform capability being absent is information the
+#   caller needs, not a decision the adapter gets to make — a watchdog may want to skip a
+#   check where an installer wants to abort, and only they know which.
+#
+# Report, Do Not Remediate
+#   The adapter answers questions and performs the single action asked of it. It does not
+#   retry, escalate, notify or heal. Every one of those policies belongs to the caller, and
+#   burying them here would make identical calls behave differently per platform.
+#
+# Stdout Is the Return Channel
+#   Value-producing functions write to stdout and are captured with $(). Status is carried
+#   by the exit code. Keeping those separate is what lets callers use them in conditionals
+#   without parsing output.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# No Root, No Lock, No detect_hosts — Deliberate
+#   This is a sourced library, loaded by load_config.sh whenever PLATFORM=unraid. It runs
+#   inside the caller's process and holds no state of its own. A root check here would fire
+#   for every script in the ecosystem including read-only ones, and a lock would be taken
+#   on every source. The executable scripts own those gates. Do not "fix" this to match them.
+#
+# Executable Validation Before Use
+#   platform_require_cmd() and the rc.d helpers verify a target exists and is executable
+#   before invoking it, so a missing platform binary returns a clean failure rather than a
+#   command-not-found in the middle of a caller's flow.
+#
+# Notification Is Best-Effort
+#   platform_send_os_notification() returns 1 if the dynamix notify script is absent rather
+#   than failing the caller. A missing notifier must never turn a successful operation into
+#   a reported failure.
+#
+# Graceful Degradation on Unknown Services
+#   _platform_rc_script() falls through to /etc/rc.d/rc.<name> for any service it does not
+#   explicitly map, so a new service works without an adapter change — and still fails
+#   cleanly if that path does not exist.
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# None of its own. The adapter is selected by PLATFORM in varaverk.cfg, which load_config.sh
+# uses to source Plugin/$PLATFORM/adapter.sh.
+#
+# It reads platform-owned files rather than Varaverk config:
+#
+#   /boot/config/plugins/dynamix/dynamix.cfg   disk temperature thresholds
+#   /boot/config/plugins/varaverk/varaverk.cfg SCRIPTS_DIR probe
+#   /boot/config/plugins/dockerMan/templates-user  container rebuild templates
+#   /etc/rc.d/rc.*                             service control
+#
+# Those paths are Unraid's, not Varaverk's — which is exactly why they are confined to this
+# file. STATE_DIR, DATA_DIR and friends belong to master.conf and are not the adapter's
+# concern.
+#
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+# None — sourced, never executed:
+#
+#   source "$LOAD_CONFIG_DIR/Plugin/$PLATFORM/adapter.sh"
+#
+# No argument parsing, no --dry-run, no --status. Callers that need a dry run implement it
+# around the platform_*() call, since only they know which of their actions are destructive.
+#
+# ==============================================================================================
 
 # ──────────────────────────────────────────────────────────────────────────────────────────────
 # Internal: map a logical service name → its rc.d script path

Plugin/unraid/user_script_plug-in.sh

@@ -144,6 +144,82 @@
 # bash /boot/config/plugins/varaverk/Orchestrators/array_started.sh
 
 
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Schedule Orchestrators, Not Scripts
+#   The catalog below lists every script in the ecosystem, but only a handful of
+#   orchestrators are meant to be scheduled. The orchestrators own ordering, dependencies,
+#   pass/fail tracking and one notification per window — scheduling their children directly
+#   bypasses all of that and produces overlapping runs the locks then have to fight.
+#
+# Everything Listed, Most Commented
+#   Individual scripts are documented here so they can be run standalone for a specific
+#   task, not so they can be scheduled. The commented-out default is the safe state: paste
+#   the file, uncomment exactly one block, set the schedule.
+#
+# One Block Per User Script Entry
+#   Each entry runs one thing. Combining blocks defeats the per-entry schedule and makes a
+#   failure in the first silently skip the rest.
+#
+# Documentation That Cannot Drift Silently
+#   Schedules here are stated alongside what the script does, so a mismatch with
+#   varaverk.cron is visible when read. Cross-check against the cron before trusting a
+#   cadence quoted in a comment — the cron is authoritative.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# Inert by Default
+#   Every command in this file is commented out. Pasted as-is it does nothing — the
+#   operator must deliberately uncomment a block. That is the safeguard: there is no state
+#   in which this file runs something unintended.
+#
+# No Root, No Lock, No detect_hosts — Deliberate
+#   This is a reference template, never executed as a file. Each uncommented block invokes
+#   a real script that enforces its own root check and takes its own lock. Adding them here
+#   would gate a file that is only ever read.
+#
+# Full Paths Throughout
+#   Every example uses an absolute path. User Scripts entries run with an unpredictable
+#   working directory, and a relative path would resolve differently depending on how the
+#   plugin happened to invoke it.
+#
+# Background Flag Documented Per Entry
+#   Continuous scripts are marked Background: YES and single-pass ones NO. Getting this
+#   wrong either blocks the array-start sequence on a script that never exits, or detaches
+#   one whose exit code the sequence needed.
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# None — this file configures nothing and reads nothing. It is documentation shaped like a
+# shell script so it can be pasted into a User Scripts entry.
+#
+# What the scheduled orchestrators actually read:
+#
+#   master.conf   ARRAY_START_SCRIPTS, ARRAY_STOP_SCRIPTS, WATCHDOG_ORCHESTRATOR_SCRIPTS,
+#                 CRITICAL_/INTERMEDIATE_/DAILY_/WEEKLY_/MONTHLY_MAINTENANCE_SCRIPTS
+#
+# Add or remove a script by editing those lists — not by adding another User Scripts entry.
+# That is the whole point of the orchestrator model.
+#
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+# Not executed. Paste into a User Scripts entry, uncomment ONE block, set its schedule.
+#
+# The blocks below are grouped by area (Fallback, Rsync, Docker Essentials, Unraid
+# Essentials, Media, Transcodes, Monitors, Partnership). Each carries its own recommended
+# schedule and Background flag.
+#
+# ==============================================================================================
+
+
 # ── ARRAY STOPPING ────────────────────────────────────────────────────────────────────────────
 # Schedule:   At Stopping of Array
 # Background: YES