diff --git a/Plugin/unraid/README-unraid.md b/Plugin/unraid/README-unraid.md
index b6a484b..57d2f2c 100644
--- a/Plugin/unraid/README-unraid.md
+++ b/Plugin/unraid/README-unraid.md
@@ -112,6 +112,39 @@ be the reason a page fails to load.
 
 ---
 
+## ━━━ WHAT GUARDS THE API LAYER ━━━
+
+Every endpoint under `api/` is protected by exactly one thing: **the Unraid WebGUI session.**
+Anything that can reach `/plugins/varaverk/api/*.php` with a valid session can do everything
+this plugin can do — stop the array, power off the host, write `master.conf` and push it to
+every partner, create an lldap user, write and schedule a root-run script.
+
+That is the same trust level as the rest of the WebGUI, and it is the intended model. It is
+written down here because two things about it are easy to assume and wrong.
+
+**No endpoint validates a CSRF token.** `pages/partnership.php` and `pages/scheduler.php` send
+Unraid's `csrf_token` with their POSTs, which reads like the token is checked somewhere. It is
+not — no file in `api/` looks at it. A request that arrives with a logged-in session cookie is
+honoured whatever caused the browser to send it. Adding validation is a worthwhile hardening
+pass, but it is a real change: every caller has to send the token before any endpoint requires
+it, or the UI breaks silently on whichever page was missed. Do it deliberately, in one pass,
+with the pages open — not opportunistically while touching one endpoint.
+
+**`api/webhook.php` is the exception that authenticates nothing at all.** It exists to receive
+Sonarr/Radarr/Lidarr download events, which arrive from a container rather than a browser.
+`master.conf` carries a `WEBHOOK_SECRET` and the standalone Node listener on `WEBHOOK_PORT`
+validates it — this WebGUI-hosted path does not. Injection is not the risk (the path is
+validated and escaped); triggering work is. Closing it means adding a secret check here **and**
+updating the webhook URL in each arr's settings, in that order.
+
+Two further endpoints are worth knowing about because they read wider than the rest:
+`api/api_test.php` returns an API key prefix and the live GraphQL schema, and
+`api/import_script.php`'s browse action and `api/manual_sync.php`'s browse actions list
+directory names anywhere on either host. All three are read-only and none return file contents,
+but they are the ones to look at first if the session boundary ever moves.
+
+---
+
 ## ━━━ ARRAY LIFECYCLE HOOKS ━━━
 
 `event/` plugs Varaverk into Unraid's own array lifecycle. These are how the ecosystem starts
diff --git a/Plugin/unraid/Tools/api_cache_writer.php b/Plugin/unraid/Tools/api_cache_writer.php
index 1827856..e579cb2 100644
--- a/Plugin/unraid/Tools/api_cache_writer.php
+++ b/Plugin/unraid/Tools/api_cache_writer.php
@@ -1,9 +1,83 @@
 <?php
-// API cache writer — runs every minute via Varaverk scheduler.
-// Builds monitor + arrs payloads and writes them to /tmp/vv_cache/ so page
-// loads can serve instantly from the file instead of making live HTTP calls.
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Background cache writer. Builds the full monitor payload and the arrs payload once a
+//   minute and writes them to the cache, so page loads serve from a file instead of paying
+//   for collection.
 //
-// Called by api_cache_writer.sh (bash wrapper required by the scheduler).
+// OPERATIONAL MODEL
+//   This is what makes the monitor and arrs tabs fast. api/monitor.php and api/arrs.php read
+//   the files this process writes and only fall back to collecting for themselves on a miss.
+//   The expensive work — GraphQL, docker stats, SSH to partners, HTTP to every arr instance —
+//   happens here, on a schedule, off the request path.
+//
+//   Runs from cron every minute via api_cache_writer.sh, a bash wrapper the scheduler
+//   requires. Not reachable over HTTP, and refuses to run if it ever is.
+//
+//   The payload assembled here is deliberately identical to api/monitor.php's. The two are
+//   maintained together: a field added there and not here is a field that is only ever served
+//   on a cache miss.
+//
+// DESIGN PRINCIPLES
+//   One API round trip for the whole payload.
+//       vv_api_data() is called once up front and static-cached for the life of the process,
+//       so the API-first collectors below share a single GraphQL query rather than issuing
+//       one each.
+//
+//   Writes two caches, not one.
+//       monitor and arrs have different consumers and different costs, so they are written
+//       under separate keys and either can be served while the other is stale.
+//
+//   Every payload carries its own timestamp, so consumers can render age rather than
+//   presenting minute-old numbers as current.
+//
+//   Reports its own duration on stdout.
+//       The elapsed time goes to the job log, which is the only place a slow collection cycle
+//       becomes visible — this process has no other output and no failure anyone would see.
+//
+// OPERATIONAL SAFEGUARDS
+//   Refuses to run under a web server.
+//       PHP_SAPI is checked first and a non-CLI invocation is answered with a 404 and no
+//       output. Otherwise a browser hitting this path would trigger the full expensive
+//       collection — including SSH to every partner — outside any cache or rate limit, once
+//       per request.
+//
+//   Read-only with respect to the system. Every collector observes; none start, stop, or
+//   change anything. The only writes are the two cache files.
+//
+//   Cache writes are atomic.
+//       vv_cache_write() writes a .tmp and renames, so a page load landing mid-write reads
+//       the previous complete payload rather than a truncated one.
+//
+//   Every collector degrades to empty rather than fatal.
+//       The library suppresses its filesystem reads and redirects stderr on every shell call,
+//       so absent hardware yields an empty section. On a payload this wide that property is
+//       what keeps one missing subsystem from failing the whole cycle and leaving both caches
+//       to expire.
+//
+//   A failed cycle is survivable by design.
+//       Nothing here clears the previous cache before building the new one. A run that dies
+//       partway leaves the last good payload in place, and the readers' own age windows —
+//       300s for monitor, 300s for arrs — are several cycles wide, so a single missed minute
+//       is invisible.
+//
+// OUTPUT
+//   VV_CACHE_DIR/monitor.json   consumed by api/monitor.php
+//   VV_CACHE_DIR/arrs.json      consumed by api/arrs.php
+//   stdout                      one timing line, captured into the job log
+//
+// DEPENDS ON
+//   include/monitor.php, include/common.php, include/unraid_api.php,
+//   include/vms.php, include/docker_folders.php, include/arrs.php
+//   Tools/api_cache_writer.sh   the bash wrapper cron actually invokes
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+
+// Collecting this payload means GraphQL, docker stats and SSH to every partner. It must never
+// be triggerable by an HTTP request.
+if (PHP_SAPI !== 'cli') {
+    http_response_code(404);
+    exit(1);
+}
 
 $_base = dirname(__DIR__);
 require_once $_base . '/include/monitor.php';
diff --git a/Plugin/unraid/api/api_test.php b/Plugin/unraid/api/api_test.php
index 513b383..53cfe42 100644
--- a/Plugin/unraid/api/api_test.php
+++ b/Plugin/unraid/api/api_test.php
@@ -1,6 +1,80 @@
 <?php
-// Diagnostic endpoint — tests the Unraid GraphQL API and returns raw results.
-// Hit from browser: /plugins/varaverk/api/api_test.php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Unraid GraphQL API diagnostic. Reports whether this host has a usable API key, what the
+//   PHP environment can do, and what the API actually answers — including live schema
+//   introspection for the types the monitor layer depends on.
+//
+// OPERATIONAL MODEL
+//   A hand-run tool, not part of any page. Nothing in the UI links here; it is opened
+//   directly at /plugins/varaverk/api/api_test.php when the monitor page starts showing
+//   degraded detail and the question is whether the API, the key, or the parsing is at fault.
+//
+//   It exists because that question was expensive to answer. The Unraid API renamed and
+//   removed types between 7.2.5 and 7.3 — ArrayParity and ArrayCache stopped being distinct
+//   types — and the only reliable way to know what the running version exposes is to ask it.
+//
+// DESIGN PRINCIPLES
+//   Reports the environment before the result.
+//       Key presence, curl availability and allow_url_fopen are answered first, because a
+//       failed probe means something entirely different depending on those three.
+//
+//   Two transports, same query.
+//       curl when available, a stream context otherwise. The fallback exists so the
+//       diagnostic still returns something on a PHP build where the probe's failure would
+//       otherwise be indistinguishable from the API being down.
+//
+//   Returns raw alongside decoded.
+//       probe_raw carries the first 1000 bytes verbatim. When the response is not JSON — an
+//       HTML error page, a proxy interception — the decoded field is null and the raw text is
+//       the only thing that explains why.
+//
+//   Introspects the specific types the monitor layer reads.
+//       Not a full schema dump. The named type lists are the ones whose field names the
+//       collectors depend on, so a rename shows up here as a missing field rather than as a
+//       quietly empty card on the monitor page.
+//
+//   Pretty-printed on purpose. The only consumer is a person reading it in a browser tab.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Every query is a read or an introspection; nothing here mutates array, docker,
+//   or VM state through the API.
+//
+//   Every request is time-boxed.
+//       5s with a 3s connect timeout on the probe, 8s on each introspection call. A hung or
+//       unreachable API returns a diagnostic rather than becoming one.
+//
+//   The whole probe is skipped without a key, and reports that as the finding.
+//       key_present is false and probe stays null. The absence of a key is the most common
+//       answer this tool gives, and it is reported as a result rather than as a failure.
+//
+//   Localhost only. The endpoint is hardcoded to http://localhost/graphql — no part of the
+//   request selects a target, so this cannot be used to probe another host.
+//
+//   The key is truncated in the response.
+//       Only the first 8 characters are returned, as key_prefix — enough to confirm which key
+//       is in use, not enough to use it.
+//
+//   Known exposure: this returns more than a normal endpoint should.
+//       A key prefix, the cached API debug log, and the live schema are all visible to anyone
+//       with a WebGUI session. That is acceptable for a diagnostic reachable only by typing
+//       its URL, but it is the reason it is not linked from any page and should not be
+//       wrapped in one. See the CSRF note in README-unraid.md for the session-only guard this
+//       shares with the rest of the api layer.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   {"host","key_present","key_prefix","curl_available","allow_url_fopen","debug_log",
+//    "probe":{"url","http_code","curl_err","decoded"},"probe_raw",
+//    "schema","pool_drives","schema2"}
+//   The schema, pool_drives and schema2 keys are present only when a key exists.
+//
+// DEPENDS ON
+//   include/config.php   vv_detect_host(), vv_conf_vars(), VV_CACHE_DIR
+//   Unraid API           http://localhost/graphql
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
diff --git a/Plugin/unraid/api/arrs.php b/Plugin/unraid/api/arrs.php
index c3f49cc..93a1741 100644
--- a/Plugin/unraid/api/arrs.php
+++ b/Plugin/unraid/api/arrs.php
@@ -1,7 +1,74 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Arr data endpoint. Serves the arrs tab: local Sonarr/Radarr/Lidarr statistics gathered
+//   live, partner statistics served from the background cache, plus an on-demand refresh of
+//   one partner's cache.
+//
+// OPERATIONAL MODEL
+//   Two modes on one URL. Without parameters it answers from a 300s cache and only builds a
+//   fresh payload on a miss. With ?action=refresh_remote&host=hostN it shells out to
+//   Tools/remote_arr_cache_writer.sh for that one host, returns the newly written node, and
+//   busts the main cache so the next ordinary poll picks the change up.
+//
+// DESIGN PRINCIPLES
+//   The refresh branch runs before the cache read, and exits.
+//       It is a distinct operation, not a cache-control flag, so it never falls through into
+//       the normal load path and cannot return a stale payload labelled as refreshed.
+//
+//   Cache first for the ordinary case.
+//       vv_arrs_all() contacts every configured arr instance. At the tab's poll rate that is
+//       far too expensive to repeat, so the 300s cache is the default path and the live build
+//       is the exception.
+//
+//   include/arrs.php is required only on a cache miss.
+//       A cache hit answers without loading the library at all, which is the difference
+//       between a poll that costs a file read and one that costs an autoload.
+//
+// OPERATIONAL SAFEGUARDS
+//   The host parameter is matched against a pattern, never used as a path.
+//       ^host\d+$ is enforced before the value goes anywhere. It reaches the script only as
+//       an escapeshellarg'd --host= value and the cache filename it composes, so neither a
+//       shell metacharacter nor a traversal sequence can survive the check.
+//
+//   The refresh is externally time-boxed.
+//       set_time_limit() does not count time spent inside exec() on Linux, so PHP's own limit
+//       cannot end a hung SSH call — the child is wrapped in `timeout` instead. Exit 124 is
+//       reported as a timeout rather than a generic failure, so the UI can distinguish an
+//       unreachable partner from a broken script.
+//
+//   A missing script is reported, not executed.
+//       The file_exists() check runs before exec(), so a partial deploy returns a named error
+//       rather than a shell "command not found" surfacing as an empty refresh.
+//
+//   The cache is busted after the write, not before.
+//       @unlink() of arrs.json follows the script run, so a failed refresh leaves the previous
+//       good payload in place instead of forcing every subsequent poll onto the live path.
+//
+//   Read-only with respect to the arrs themselves. Statistics come from the databases the
+//   scripts write; nothing here triggers a scan, cleanup, or import.
+//
+// REQUEST
+//   GET                                        cached (300s) full payload
+//   GET ?action=refresh_remote&host=host<n>     re-run the partner cache writer for one host
+//
+// RESPONSE
+//   normal   vv_arrs_all() verbatim — local node live, remote nodes cached with cache_age
+//   refresh  {"ok":bool,"node":object|null,"output":string}
+//   errors   {"ok":false,"error":string}  — invalid host, missing script, or timeout
+//
+// DEPENDS ON
+//   include/config.php            vv_cache_read(), VV_CACHE_DIR
+//   include/arrs.php             vv_arrs_all()          (loaded only on a cache miss)
+//   Tools/remote_arr_cache_writer.sh                     (refresh branch only)
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
+// Bound on the partner refresh child process. set_time_limit() does not cover exec() time
+// on Linux, so this is enforced by `timeout`, not by PHP.
+define('VV_ARRS_REFRESH_TIMEOUT', 120);
+
 // ── Manual remote refresh — runs remote_arr_cache_writer for one host ─────────
 $_action = trim($_GET['action'] ?? '');
 if ($_action === 'refresh_remote') {
@@ -13,9 +80,19 @@ if ($_action === 'refresh_remote') {
     if (!file_exists($script)) {
         echo json_encode(['ok' => false, 'error' => 'remote_arr_cache_writer.sh not found']); exit;
     }
-    set_time_limit(30);
+    set_time_limit(VV_ARRS_REFRESH_TIMEOUT + 30);
     $out = []; $exit = 0;
-    exec('bash ' . escapeshellarg($script) . ' --host=' . escapeshellarg(strtoupper($host)) . ' 2>&1', $out, $exit);
+    exec('timeout ' . VV_ARRS_REFRESH_TIMEOUT . ' bash ' . escapeshellarg($script)
+         . ' --host=' . escapeshellarg(strtoupper($host)) . ' 2>&1', $out, $exit);
+
+    if ($exit === 124) {
+        echo json_encode([
+            'ok'     => false,
+            'error'  => 'Refresh timed out after ' . VV_ARRS_REFRESH_TIMEOUT . 's',
+            'output' => implode("\n", $out),
+        ]);
+        exit;
+    }
 
     $cacheFile = VV_CACHE_DIR . '/arrs_remote_' . $host . '.json';
     $node = null;
diff --git a/Plugin/unraid/api/auth.php b/Plugin/unraid/api/auth.php
index 2dc6023..7895b3b 100644
--- a/Plugin/unraid/api/auth.php
+++ b/Plugin/unraid/api/auth.php
@@ -1,4 +1,93 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Auth stack endpoint. The single URL behind the auth tab, covering all three services it
+//   manages: Nginx Proxy Manager proxy hosts and certificates, lldap users and groups, and
+//   Authelia access rules.
+//
+// OPERATIONAL MODEL
+//   Read and write share one URL, split on HTTP method. GET serves the five read actions and
+//   is always safe. POST carries an action naming exactly one library call. Anything that is
+//   neither GET nor POST is refused with 405 before a parameter is read.
+//
+//   Three services, one endpoint, because they are one subject. The auth stack is HOST1's
+//   source of truth for identity, and a change in one service usually accompanies a change in
+//   another — a new lldap user is only useful once an Authelia rule and an NPM host exist for
+//   it. Splitting them into three endpoints would split one page's work across three files
+//   with three copies of the same dispatch.
+//
+// DESIGN PRINCIPLES
+//   Both dispatches are closed match expressions.
+//       Every action maps to one named library call, and an unrecognised action falls to a
+//       default arm that returns an error. No part of the request is ever used to construct a
+//       function name, so the action list is the complete set of things this endpoint can do.
+//
+//   The endpoint holds no auth logic of its own.
+//       Token acquisition, API dialects, config parsing and the Authelia container restart
+//       all live in include/auth.php. This file is dispatch and nothing else, which is what
+//       keeps the credential handling in one auditable place.
+//
+//   Structured payloads arrive as JSON in a form field.
+//       Proxy definitions and rule sets are nested, so they are passed as encoded JSON rather
+//       than flattened into form keys — a rule set does not survive form encoding intact.
+//
+// OPERATIONAL SAFEGUARDS
+//   Wrong method is refused with a status code, not just a body, so a mistaken caller fails
+//   visibly rather than parsing an error object as data.
+//
+//   Every parameter is optional and typed at the call site.
+//       (int) casts on ids, ?? '' on strings, ?? '0' === '1' on flags. A malformed POST
+//       reaches the library as zeros and empty strings — which the library rejects — rather
+//       than raising undefined-index warnings into the JSON body and corrupting the response.
+//
+//   Malformed JSON degrades to an empty structure.
+//       json_decode with ?: [] on both data and rules. A truncated payload becomes an empty
+//       set the library refuses, not a partial one it might act on.
+//
+//   Credentials pass through, and are never returned.
+//       lldap_set_password and lldap_create_user accept a password and hand it straight to
+//       the library. No action in either dispatch returns a stored credential, and nothing
+//       here writes one to a log.
+//
+//   The destructive actions are POST-only by construction.
+//       Delete of a proxy, a user, or a group exists only in the POST match. The GET arm has
+//       five read actions and no others, so no link or prefetch can reach a delete.
+//
+//   Authelia rule writes are atomic and refuse to create.
+//       The library writes .vv.tmp and renames, and returns 'Config not found' rather than
+//       authoring a fresh config — a config it created would carry no rules and a default
+//       policy, which is an accidental open door.
+//
+//   Known gap: no CSRF token is validated on the POST actions.
+//       The endpoint is guarded by the Unraid WebGUI session alone, and this is the highest-
+//       value endpoint in the plugin to reach — it can create a user and open a proxy host.
+//       Shared with the rest of the api layer; see the CSRF note in README-unraid.md.
+//
+// REQUEST
+//   GET  ?action=npm_proxies | npm_certs | lldap_users | lldap_groups | authelia_rules
+//   POST action=npm_create              data=<JSON>
+//   POST action=npm_update              id, data=<JSON>
+//   POST action=npm_delete              id
+//   POST action=npm_toggle              id, enabled=0|1
+//   POST action=lldap_create_user       uid, email, display_name, password
+//   POST action=lldap_update_user       uid, email, display_name
+//   POST action=lldap_delete_user       uid
+//   POST action=lldap_set_password      uid, password
+//   POST action=lldap_create_group      name
+//   POST action=lldap_delete_group      id
+//   POST action=lldap_add_to_group      uid, gid
+//   POST action=lldap_remove_from_group uid, gid
+//   POST action=authelia_save           rules=<JSON>, default_policy
+//
+// RESPONSE
+//   Whatever the invoked library call returns — ['ok' => bool] with a payload or an error,
+//   or an _err key on a failed remote call. npm_certs is wrapped as {"ok":true,"certs":[…]}.
+//   {"ok":false,"error":"Unknown action: …"} for anything outside the lists above.
+//
+// DEPENDS ON
+//   include/auth.php   vv_npm_*(), vv_lldap_*(), vv_authelia_read_rules(),
+//                      vv_authelia_write_rules()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/auth.php';
 
diff --git a/Plugin/unraid/api/board.php b/Plugin/unraid/api/board.php
index 855ae87..cd67585 100644
--- a/Plugin/unraid/api/board.php
+++ b/Plugin/unraid/api/board.php
@@ -1,5 +1,101 @@
 <?php
-// Live board data: locks, recent errors, partner reachability.
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Attention board. The three things worth knowing without opening a tab: locks nobody is
+//   holding, scripts whose last run ended badly, and whether the partner is reachable.
+//
+// OPERATIONAL MODEL
+//   A dashboard of exceptions, not of state. Everything here is designed to be empty on a
+//   healthy host — an empty board is the expected reading, which is what makes a non-empty
+//   one worth looking at.
+//
+//   Each section answers a question no single other endpoint does. Locks come from the
+//   filesystem, errors from correlating logs against their stat files, reachability from an
+//   actual ping. They are collected together because they are read together.
+//
+// DESIGN PRINCIPLES
+//   Only stale locks are reported.
+//       A lock whose owning pid is still in /proc is a job legitimately running and is
+//       skipped. What remains is the set a person might need to clear — which is exactly what
+//       clearlock.php exists for.
+//
+//   Errors are gated on the stat file, not on the log text.
+//       A script is only reported when its last recorded run exited warn or error. Scanning
+//       logs for the word "error" produced two persistent false positives: dry runs, which
+//       print failures they did not cause, and success summaries containing lines like
+//       "Failed: 0". The stat file is the run's own verdict, and it is authoritative.
+//
+//   A script with no stat file is skipped entirely.
+//       No stat file means it never ran through run_job.sh, so there is no verdict to trust
+//       and no basis for reporting it.
+//
+//   The error line is the last matching one, searched backwards.
+//       Logs are appended, so the most recent failure is at the end. The search walks up from
+//       there and stops at the first hit rather than reading forward and reporting the oldest.
+//
+//   There is a fallback when nothing matches.
+//       A run that failed without printing a recognisable error still reports its last
+//       non-blank line. A script marked error with no explanation is worse than an imperfect
+//       one.
+//
+//   The partner is discovered, not configured.
+//       master.conf is scanned for HOST<n> entries and the first non-self one is used, so this
+//       works for any number of hosts without a second list to maintain.
+//
+//   Tailscale resolves the address, never local DNS.
+//       vv_resolve_tailscale_ip() mirrors common.sh, so the board tests the same path the
+//       rest of the system uses and survives the partner's IP changing.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Nothing here clears a lock, truncates a log, or restarts anything — the board
+//   reports; clearlock.php and stop.php act.
+//
+//   The lock scan is bounded to a hardcoded directory.
+//       glob over /tmp/unraid_locks/*.lock — a literal, not a config value, so no conf edit
+//       can point this scan somewhere else.
+//
+//   The log walk is wrapped in a try/catch.
+//       RecursiveDirectoryIterator throws when LOG_DIR is absent or a subdirectory is
+//       unreadable — the normal state on a fresh install. The catch yields an empty error
+//       list rather than a 500.
+//
+//   Every file read is independently suppressed and defaulted.
+//       @file_get_contents, @file, and ?: fallbacks throughout. One unreadable log or stat
+//       file costs its own row, not the response.
+//
+//   The scan window and the output are both bounded.
+//       Logs older than 7 days are skipped, only the last 200 lines of each are read, each
+//       line is truncated at 220 characters, and the result is capped at 20 errors. This runs
+//       against a directory that grows without limit.
+//
+//   ANSI escapes are stripped before matching and before returning.
+//       Logs are written with colour. Without stripping, the patterns would miss coloured
+//       error markers and the JSON would carry terminal control codes into the page.
+//
+//   The ping target is escaped, and time-boxed by ping itself.
+//       escapeshellarg() on a value that came from conf, and -c1 -W2 so an unreachable
+//       partner costs two seconds. The result is cached 30s so the board's poll does not ping
+//       on every request.
+//
+//   Reachability falls back to the hostname when Tailscale cannot resolve.
+//       Better to test something and report the result than to report nothing because the
+//       preferred resolution path failed.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   {"ok":true,
+//    "locks":[{"name","file","age"}],            stale locks only — empty is healthy
+//    "errors":[{"script","line","ts"}],          newest first, max 20
+//    "partner":{"host","reachable","latency"}}   null when no partner is configured
+//
+// DEPENDS ON
+//   include/config.php   LOG_DIR, vv_conf_vars(), vv_get_hostname(),
+//                        vv_resolve_tailscale_ip(), vv_cache_read(), vv_cache_write()
+//   /tmp/unraid_locks    lock files written by common.sh's locking helper
+//   LOG_DIR/**           .log files and their .json stat files, written by run_job.sh
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
diff --git a/Plugin/unraid/api/cert.php b/Plugin/unraid/api/cert.php
index 3bb1c78..9fdb4bf 100644
--- a/Plugin/unraid/api/cert.php
+++ b/Plugin/unraid/api/cert.php
@@ -1,4 +1,95 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Certificate status. Serves the cert panel four ways — the cached results of the last
+//   cert_monitor.sh run, the configured domain list, a live read of NPM's own certificate
+//   store, and an on-demand re-run of the monitor.
+//
+// OPERATIONAL MODEL
+//   Two independent sources of truth, deliberately kept separate. cert_monitor.sh checks the
+//   domains as they resolve from outside — the certificate a visitor actually receives. NPM's
+//   API reports what it holds internally. They disagree exactly when something is wrong: a
+//   renewed cert that was never reloaded, or a proxy host pointing at the wrong certificate.
+//   Collapsing them into one number would hide the only case worth catching.
+//
+//   The default path serves cert_monitor.sh's cache and never checks anything itself. That
+//   script runs on the Sunday report schedule; the run action exists for when someone does
+//   not want to wait for it.
+//
+// DESIGN PRINCIPLES
+//   Thresholds come from master.conf, with shipped defaults.
+//       CERT_WARN_DAYS and CERT_CRIT_DAYS are read per request rather than baked in, so the
+//       page and the script that notifies agree on what "critical" means.
+//
+//   No cache is answered with the domain list, not with an error.
+//       Before the first run there is nothing to report, so the configured domains are
+//       returned marked UNKN. The panel shows what is being watched rather than an empty
+//       state that looks like nothing is configured.
+//
+//   Already expired sorts with critical, not past it.
+//       A negative day count is CRIT rather than a separate state, and the sort puts the
+//       smallest number first — so the most urgent certificate is always at the top.
+//
+//   The run action returns the script's output alongside the fresh data.
+//       Capped at 30 lines. When a check fails, the reason is in that output and nowhere in
+//       the structured result.
+//
+// OPERATIONAL SAFEGUARDS
+//   The action is chosen from a fixed set, and everything else falls to the cached read.
+//       No part of the request names a script, a domain, or a file. The one script this
+//       endpoint can run is a hardcoded path.
+//
+//   The script run is externally time-boxed.
+//       `timeout 180` wraps it — set_time_limit() does not cover exec() time on Linux, so
+//       PHP's own limit cannot end a check hung on an unresponsive domain. Exit 124 is
+//       reported as a timeout rather than a generic failure.
+//
+//   A missing script is reported, not executed.
+//       file_exists() precedes exec(), so a partial deploy returns a named error rather than
+//       a shell failure surfacing as an empty result.
+//
+//   Every threshold read has a default.
+//       ?: 30 and ?: 7 on the regex captures, so a master.conf mid-edit or missing the keys
+//       still yields coherent statuses instead of comparing every certificate against zero
+//       and reporting the whole estate critical.
+//
+//   Missing or malformed expiry data is UNKN, never OK.
+//       A certificate whose expires_on is absent or unparseable yields a null day count and
+//       an explicit unknown status. Defaulting it to OK would silently drop a certificate out
+//       of monitoring — the one failure this panel exists to prevent.
+//
+//   Every cache read degrades.
+//       json_decode with ?: fallbacks throughout, so a truncated cache file yields an empty
+//       result rather than a fatal.
+//
+//   The NPM path reports its own transport failures.
+//       vv_npm_req() returns an _err key rather than throwing, and that is checked before the
+//       response is treated as a certificate list — so an unreachable NPM is reported as such
+//       instead of rendering as zero certificates.
+//
+//   Accepted: the run action is reachable over GET.
+//       It re-runs a read-only monitor and writes only its own cache, so repeating it is
+//       harmless. Guarded by the Unraid WebGUI session; see the CSRF note in README-unraid.md.
+//
+// REQUEST
+//   GET                        cached status, or the configured domains when no cache exists
+//   GET|POST ?action=npm       live certificate list from NPM's API
+//   GET|POST ?action=domains   configured domains and thresholds, no checks run
+//   GET|POST ?action=run       re-run cert_monitor.sh, then return its fresh cache
+//
+// RESPONSE
+//   default  {"ok":true,"checked_at","host","warn_days","crit_days","domains":[…]}
+//   npm      {"ok":true,"certs":[{id,nice_name,domain_names,provider,expires,days,status}],
+//             "warn_days","crit_days"}
+//   domains  {"ok":true,"host_id","domains":[…],"warn_days","crit_days"}
+//   run      {"ok":true,"data":…,"output":[…],"rc":int}
+//   {"ok":false,"error":"NPM request failed"|"cert_monitor.sh not found"|"… timed out …"}
+//
+// DEPENDS ON
+//   include/config.php    vv_detect_host(), vv_read_conf_raw(), STATE_DIR, SCRIPTS_DIR
+//   include/auth.php      vv_npm_req()
+//   Monitors/cert_monitor.sh   writes STATE_DIR/cert_status.json
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 require_once dirname(__DIR__) . '/include/auth.php';
@@ -81,8 +172,15 @@ if ($action === 'run') {
         echo json_encode(['ok' => false, 'error' => 'cert_monitor.sh not found']);
         exit;
     }
-    set_time_limit(180);
-    exec('bash ' . escapeshellarg($script) . ' 2>&1', $out, $rc);
+    // set_time_limit() does not cover exec() time on Linux, so the bound has to be external —
+    // cert_monitor.sh reaches out to every configured domain and one unreachable host would
+    // otherwise hold a php-fpm worker open indefinitely.
+    set_time_limit(210);
+    exec('timeout 180 bash ' . escapeshellarg($script) . ' 2>&1', $out, $rc);
+    if ($rc === 124) {
+        echo json_encode(['ok' => false, 'error' => 'cert_monitor.sh timed out after 180s']);
+        exit;
+    }
     // Read freshly written cache
     $data = file_exists($cacheFile)
         ? (json_decode(file_get_contents($cacheFile), true) ?: null)
diff --git a/Plugin/unraid/api/checklist.php b/Plugin/unraid/api/checklist.php
index 18ae98f..5c3d4f9 100644
--- a/Plugin/unraid/api/checklist.php
+++ b/Plugin/unraid/api/checklist.php
@@ -1,4 +1,83 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Setup checklist. Evaluates what this host still needs before it is fully configured —
+//   identity, conf, API and SSH keys, service discovery, media keys, and partnership state —
+//   and names the action that fixes each gap.
+//
+// OPERATIONAL MODEL
+//   Derived, never stored. Every item is computed from the conf files and the setup state on
+//   each request, so the checklist cannot go stale or disagree with reality. There is no
+//   "completed" flag anyone could tick.
+//
+//   The item list is not fixed. Emby and Jellyfin checks appear only once their container is
+//   configured; the master.conf pull appears only on a partner host; partnership appears only
+//   once a HOST2 is named. A checklist that listed everything would tell a single-host
+//   install it was permanently incomplete.
+//
+//   Items carry an action name, not a URL. The page maps create_key, ssh_setup, run_populate,
+//   pull_master and onboard onto the right endpoint or instruction — so this file describes
+//   what is wrong, and the UI owns how to fix it.
+//
+// DESIGN PRINCIPLES
+//   Each check answers the narrowest useful question.
+//       The SSH item tests that the configured path exists on disk, not merely that a path is
+//       set — a path set to a file that was never generated is the actual failure mode, and
+//       the detail text distinguishes the two cases.
+//
+//   Auto-populate is satisfied by any one service.
+//       The check passes on the first arr key or media container found. Requiring all of them
+//       would leave the item permanently red on a host that legitimately runs only some.
+//
+//   Partnership reports its phases separately.
+//       Phase 1 done with phase 2 outstanding is its own message, because the fix is to go
+//       finish onboarding on the other host — not to re-run anything here.
+//
+//   State keys are read case-insensitively.
+//       Both HOST2_PHASE1_DONE and host2_phase1_done are accepted, because the state file has
+//       been written by both the shell layer and the PHP layer over its life.
+//
+//   complete is derived from the items, not tracked.
+//       A single strict in_array(false, …) over the item results, so the summary can never
+//       disagree with the list it summarises.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. This endpoint diagnoses and never fixes — every remedy is a separate,
+//   explicitly invoked action. That separation is what makes it safe to poll.
+//
+//   No input at all. There are no parameters, so there is nothing to validate and no way to
+//   ask about a host other than this one.
+//
+//   An unidentified host degrades to a report rather than an error.
+//       vv_detect_host() returning 'unknown' is handled at every use — the host conf is not
+//       read, and the identity and host_conf items say so explicitly. That is the exact state
+//       a fresh install is in, and it is the checklist's job to describe it.
+//
+//   Every conf read is defaulted.
+//       vv_read_conf_raw() returns empty for a missing file and every scalar lookup is
+//       trimmed with a ?? fallback, so a partial or absent conf yields items marked not-ok
+//       rather than a fatal that would blank the whole panel.
+//
+//   Key presence is reported, key values never are.
+//       The API, SSH, Emby and Jellyfin items report only whether a value is set — and for
+//       SSH, the basename of the path. No credential is returned.
+//
+//   Missing is reported as missing, never as fine.
+//       Every item defaults to ok:false and is only set true by a positive test. A check that
+//       cannot run reports the gap it could not rule out.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   {"ok":true,"complete":bool,"host_id":"host<n>|unknown",
+//    "items":[{"id","label","ok","detail","action"?}, …]}
+//   action is present and non-null only when there is a remedy the UI can invoke.
+//
+// DEPENDS ON
+//   include/config.php   vv_detect_host(), vv_read_conf_raw(), vv_parse_conf_scalar(),
+//                        vv_setup_state_read(), CONF_DIR
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
diff --git a/Plugin/unraid/api/clearlock.php b/Plugin/unraid/api/clearlock.php
index 8e3154f..7041376 100644
--- a/Plugin/unraid/api/clearlock.php
+++ b/Plugin/unraid/api/clearlock.php
@@ -1,4 +1,56 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Stale lock removal. Deletes one lock file from /tmp/unraid_locks so a script whose
+//   previous run died without releasing its lock can be started again from the UI.
+//
+// OPERATIONAL MODEL
+//   The manual escape hatch for the one failure the lock discipline cannot resolve on its
+//   own. Scripts take a lock to prevent concurrent runs; a run killed by OOM, a reboot mid-
+//   job, or kill -9 leaves the lock behind and every subsequent run refuses to start. This
+//   endpoint is how a person clears that, and it is deliberately the only way — nothing
+//   automatically reaps locks, because "the lock is old" and "the job is still running" are
+//   not distinguishable from the file alone.
+//
+// DESIGN PRINCIPLES
+//   Loads nothing.
+//       This is the only endpoint in the api layer that requires no include. The operation is
+//       one unlink in one fixed directory; pulling in the config layer to perform it would
+//       add failure modes to something that must work when other things are broken.
+//
+//   Deletes exactly one lock, never sweeps.
+//       There is no clear-all. Releasing every lock at once would restart the concurrent runs
+//       the locks exist to prevent.
+//
+// OPERATIONAL SAFEGUARDS
+//   POST only. A GET cannot delete a lock, so a stray link, prefetch, or browser history
+//   entry cannot release one.
+//
+//   The filename is stripped and then pattern-matched, in that order.
+//       basename() removes any directory component, and the surviving name must match
+//       ^[a-zA-Z0-9_\-]+\.lock$ — no dots beyond the extension, no slashes, no traversal. The
+//       two together mean the composed path cannot leave /tmp/unraid_locks, and the .lock
+//       suffix means nothing but a lock file is a candidate in the first place.
+//
+//   Deleting an absent lock is success, not an error.
+//       file_exists() is checked and @unlink() suppressed, so two clicks, or a race with the
+//       script releasing its own lock, both end with the lock gone and ok:true. The caller
+//       wants the lock absent; it does not care who removed it.
+//
+//   Scope is one fixed directory, hardcoded here.
+//       /tmp/unraid_locks is a literal, not a config value, so no conf edit or empty variable
+//       can redirect this delete somewhere else.
+//
+// REQUEST
+//   POST file=<name>.lock
+//
+// RESPONSE
+//   {"ok":true}                     lock removed, or already absent
+//   {"ok":false,"error":string}     wrong method or a filename that failed validation
+//
+// DEPENDS ON
+//   nothing — /tmp/unraid_locks is written by the shell layer's locking helper
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
     echo json_encode(['ok' => false, 'error' => 'POST only']);
diff --git a/Plugin/unraid/api/conf_toggle.php b/Plugin/unraid/api/conf_toggle.php
index b9779d9..562813d 100644
--- a/Plugin/unraid/api/conf_toggle.php
+++ b/Plugin/unraid/api/conf_toggle.php
@@ -1,4 +1,64 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Orchestrator membership toggle. Comments or uncomments one script's entry inside the
+//   *_SCRIPTS arrays in master.conf, so the scheduler page can take a script out of an
+//   orchestrator's run list without deleting it.
+//
+// OPERATIONAL MODEL
+//   This is not the same switch as the scheduler's enable/disable. Scheduler state controls
+//   whether a *cron entry* fires; this controls whether an orchestrator *calls a child
+//   script* during its own run. A script can be disabled here and still run, if another
+//   orchestrator lists it — unraid_api_key_renew.sh is deliberately in two arrays.
+//
+//   The edit is a comment marker, not a deletion. The line stays in master.conf with its
+//   arguments and its position intact, so re-enabling restores exactly what was there before
+//   and a diff shows an intent change rather than a removal.
+//
+// DESIGN PRINCIPLES
+//   Only the first match is toggled.
+//       vv_conf_toggle_script() breaks after the first array entry it matches. A script
+//       listed in two orchestrators is not silently changed in both by one click.
+//
+//   No match is success, not failure.
+//       A script that is not in any array has nothing to toggle and the conf is already in
+//       the requested state. Returning an error there would make the UI report a problem
+//       where none exists.
+//
+// OPERATIONAL SAFEGUARDS
+//   POST only, checked before any parameter is read.
+//
+//   The id is pattern-matched and traversal-checked separately.
+//       ^[a-zA-Z0-9_./\-]+\.sh$ permits the Category/script.sh form the arrays actually use,
+//       so the slash cannot simply be banned — str_contains($id, '..') is therefore a second,
+//       explicit check rather than something folded into the pattern.
+//
+//   The id is never used as a path.
+//       It reaches vv_conf_toggle_script() only as a preg_quote()d needle matched against
+//       existing lines in master.conf. Nothing is opened, executed, or created from it, so a
+//       value that slipped past validation still has no file to reach.
+//
+//   The scope of the edit is bounded to array bodies.
+//       The library tracks whether it is inside a `*_SCRIPTS=(` block and skips every line
+//       outside one, so a matching string in a comment or an unrelated variable cannot be
+//       rewritten.
+//
+//   The write is atomic.
+//       vv_conf_toggle_script() writes through vv_write_conf_raw() (tmp + rename). Every
+//       script sources master.conf; a truncated write here would be a system-wide outage
+//       rather than a lost toggle.
+//
+// REQUEST
+//   POST id=<Category/script.sh>  enabled=0|1
+//
+// RESPONSE
+//   {"ok":true,"error":null}
+//   {"ok":false,"error":"POST only"|"Invalid id"|"Failed to write master.conf"}
+//
+// DEPENDS ON
+//   include/scheduler.php   vv_conf_toggle_script() → vv_write_conf_raw()
+//   Configurations/master.conf   the *_SCRIPTS arrays
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/scheduler.php';
 
diff --git a/Plugin/unraid/api/confform.php b/Plugin/unraid/api/confform.php
index 630f13a..8321294 100644
--- a/Plugin/unraid/api/confform.php
+++ b/Plugin/unraid/api/confform.php
@@ -1,4 +1,91 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Structured conf editing. GET returns the configuration fields relevant to one script,
+//   grouped and typed for rendering as a form; POST writes a set of field changes back to
+//   whichever conf files they belong to.
+//
+// OPERATIONAL MODEL
+//   The counterpart to rawconf.php. That one hands over a text file; this one presents the
+//   subset of keys a given script actually reads, with their types and current values, so a
+//   threshold can be changed without opening master.conf and finding it.
+//
+//   Changes are keyed by file, not by form. Each change carries its own target file, because
+//   one script's settings routinely span master.conf and a host conf — a threshold is shared,
+//   the credential it applies to is not. A single save therefore writes to several files, and
+//   reports per-file results.
+//
+//   A master.conf write is followed by a push to every partner, matching rawconf.php. The
+//   two endpoints edit the same file and must distribute it the same way.
+//
+// DESIGN PRINCIPLES
+//   Which fields belong to a script is derived, not configured.
+//       vv_conf_fields_for_script() resolves them from the script itself, so a new conf
+//       variable appears in the form as soon as the script reads it — there is no second list
+//       to keep in step.
+//
+//   Validation is total before any write begins.
+//       Every change in the set is checked first, and the endpoint exits on the first bad
+//       one. A partially applied save across multiple conf files is far harder to reason
+//       about than a rejected one.
+//
+//   ok reflects the whole set.
+//       ok is false if any file failed, while files carries the per-file detail. A caller
+//       that checks only ok is correct but coarse; one that wants to know which file failed
+//       can see it.
+//
+// OPERATIONAL SAFEGUARDS
+//   Every change names its own file, and every one is checked against the allowlist.
+//       in_array(..., true) against vv_get_conf_files() per change — not once for the batch.
+//       The allowlist is what enforces sparse checkout: HOST2 cannot be handed a change
+//       targeting host1.conf, because host1.conf is not in its list.
+//
+//   Keys must look like shell variables.
+//       ^[A-Z_][A-Z0-9_]*$ — no lowercase, no punctuation, no leading digit. The key is used
+//       to locate and rewrite an assignment in a bash file, so anything that could not be a
+//       variable name has no legitimate target.
+//
+//   Malformed payloads are refused, not coerced.
+//       is_array() on the decoded changes, and an explicit missing-id check. A truncated body
+//       becomes a rejection rather than an empty change set that would report success while
+//       writing nothing.
+//
+//   The GET path blocks traversal on the id.
+//       An explicit '..' check before the id reaches the field resolver.
+//
+//   Writes are atomic per file — vv_conf_write_changes() goes through the same tmp + rename
+//   path as every other conf write, so a script sourcing a conf mid-save sees the old file or
+//   the new one.
+//
+//   The push only happens after master.conf is confirmed written.
+//       Guarded on the per-file result being exactly true, so a failed edit cannot distribute
+//       a stale or partly-written master.conf to partners.
+//
+//   Unknown methods are refused explicitly, so a PUT or DELETE cannot fall through the two
+//   handled blocks into an empty 200.
+//
+//   Narrower than rawconf.php, but not narrow enough to skip the syntax gate.
+//       Every write rewrites the value of an existing, named key — no key can be added,
+//       deleted, or moved. But only the scalar path escapes its value: the array,
+//       array_single and assoc_array paths splice the caller's text into the file verbatim,
+//       and the type is chosen by the request. vv_conf_write_changes() therefore runs the
+//       same `bash -n` check config.php and rawconf.php apply, and a file that does not parse
+//       is reported as a failed write with the original left intact.
+//
+// REQUEST
+//   GET  ?id=<Category/name.sh>
+//   POST id=<Category/name.sh>  changes=<JSON array of {file, key, value}>
+//
+// RESPONSE
+//   GET   {"ok":true,"groups":[…]}
+//   POST  {"ok":bool,"files":{"<conf>":bool, …},"push":[{"host","ok","ready","error"}, …]}
+//   {"ok":false,"error":"Invalid id"|"Missing id"|"Invalid changes"
+//                      |"Unauthorized file: …"|"Invalid key: …"|"Method not allowed"}
+//
+// DEPENDS ON
+//   include/confform.php   vv_conf_fields_for_script(), vv_conf_write_changes()
+//   include/config.php     vv_get_conf_files(), vv_push_master_conf(), vv_push_setup_state()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/scheduler.php';
 require_once dirname(__DIR__) . '/include/confform.php';
diff --git a/Plugin/unraid/api/config.php b/Plugin/unraid/api/config.php
index 8bc8587..41f8829 100644
--- a/Plugin/unraid/api/config.php
+++ b/Plugin/unraid/api/config.php
@@ -1,7 +1,69 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Conf save endpoint. Writes the full text of one configuration file back to
+//   Configurations/, for the settings tab's raw editor.
+//
+// OPERATIONAL MODEL
+//   Whole-file replacement, not a patch. The editor sends back everything it was given, so a
+//   save is a straight overwrite. There is no merge, no per-key update, and no attempt to
+//   reconcile with a concurrent edit — last writer wins, which is correct for a single-admin
+//   plugin and far more predictable than a partial merge of a bash file.
+//
+// DESIGN PRINCIPLES
+//   Which files exist is decided by the host, never by the request.
+//       vv_get_conf_files() returns the allowlist for this host — master.conf plus its own
+//       host conf on HOST1, its own conf alone elsewhere. The filename is checked for exact
+//       membership in that list. This is what keeps sparse checkout honest: HOST2 cannot be
+//       asked to write host1.conf, because host1.conf is not in its list.
+//
+//   Raw is the point.
+//       The structured editor is confform.php. This endpoint exists for the cases that one
+//       cannot express — new keys, comments, array literals, bulk edits — so it deliberately
+//       does not parse, reformat, or normalise what it is given.
+//
+// OPERATIONAL SAFEGUARDS
+//   POST only. Refused before the allowlist is even consulted, so a link or a prefetch can
+//   never reach the write path.
+//
+//   Exact allowlist membership, not a pattern.
+//       in_array() against vv_get_conf_files() — not a regex, not a prefix test, not
+//       basename(). A filename that is not literally one of the permitted strings is rejected,
+//       which makes traversal and absolute paths unreachable rather than merely filtered.
+//
+//   The content is syntax-checked before it can replace a working file.
+//       Conf files are sourced by every script in the system. A stray quote saved here would
+//       break load_config.sh, and with it every orchestrator, watchdog and fallback path — on
+//       a machine whose whole purpose is running unattended. `bash -n` on a private temp copy
+//       is the difference between a rejected save and a silent, total outage, so a file that
+//       does not parse is refused and the previous version is left untouched.
+//
+//   The temp copy is created with tempnam() and always removed.
+//       The candidate is never written next to the real conf and never under a predictable
+//       name, so a failed validation cannot leave a stray file for a script to source.
+//
+//   The real write is atomic.
+//       vv_write_conf_raw() writes .vv.tmp and rename()s, so a script sourcing the conf
+//       during the save reads either the old file or the new one, never a half-written one.
+//
+// REQUEST
+//   POST file=<allowed conf name>  content=<full file text>
+//
+// RESPONSE
+//   {"ok":true,"error":null}
+//   {"ok":false,"error":"POST only"|"File not permitted"|"Syntax error: …"|"Failed to write file"}
+//
+// DEPENDS ON
+//   include/config.php   vv_get_conf_files(), vv_write_conf_raw(), CONF_DIR
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
+if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
+    echo json_encode(['ok' => false, 'error' => 'POST only']);
+    exit;
+}
+
 $file    = trim($_POST['file']    ?? '');
 $content = $_POST['content'] ?? '';
 
@@ -12,5 +74,23 @@ if (!$file || !in_array($file, $allowed)) {
     exit;
 }
 
+// Every script sources these. A syntax error here takes the whole system down, so the
+// candidate is parsed before it is allowed to replace a working file.
+$check = tempnam(sys_get_temp_dir(), 'vvconf');
+if ($check !== false) {
+    file_put_contents($check, $content);
+    $out = []; $rc = 0;
+    exec('bash -n ' . escapeshellarg($check) . ' 2>&1', $out, $rc);
+    @unlink($check);
+    if ($rc !== 0) {
+        $msg = implode(' ', array_filter(array_map('trim', $out)));
+        echo json_encode([
+            'ok'    => false,
+            'error' => 'Syntax error: ' . str_replace($check, $file, $msg ?: 'conf does not parse'),
+        ]);
+        exit;
+    }
+}
+
 $ok = vv_write_conf_raw($file, $content);
 echo json_encode(['ok' => $ok, 'error' => $ok ? null : 'Failed to write file']);
diff --git a/Plugin/unraid/api/create_api_key.php b/Plugin/unraid/api/create_api_key.php
index d072338..af5b47a 100644
--- a/Plugin/unraid/api/create_api_key.php
+++ b/Plugin/unraid/api/create_api_key.php
@@ -1,4 +1,68 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Unraid API key provisioning. Runs unraid_api_key_renew.sh for this host and reports a
+//   masked preview of the key that ended up in the conf — the "create key" action on the
+//   setup and partnership tabs.
+//
+// OPERATIONAL MODEL
+//   Provisioning for the local host only. There is no host parameter: the target is whatever
+//   vv_detect_host() resolves to, because a key can only be created on the machine that owns
+//   the API it authenticates against. A partner's key is created on the partner.
+//
+//   Repair, not just creation. The underlying script is the same one the array-start and
+//   15-minute watchdog runs call, because the registry it writes can be cleared by a service
+//   restart rather than only by a reboot. Running it against a host that already has a valid
+//   key is a no-op that re-registers, which is why this endpoint is safe to press twice.
+//
+// DESIGN PRINCIPLES
+//   Idempotent by delegation.
+//       This file contains no key logic at all. Whether a key needs creating, renewing, or
+//       leaving alone is decided in one place — the shell script — so the UI path and the
+//       scheduled path can never diverge on that judgement.
+//
+//   The key is never returned.
+//       Only a masked preview (first 8, last 4) leaves the server. The full value lives in
+//       host*.conf, which is the only place anything reads it from. There is no workflow that
+//       needs the key in a browser, so it is not sent to one.
+//
+// OPERATIONAL SAFEGUARDS
+//   The host slot is validated before it is used to compose a conf filename.
+//       vv_detect_host() can return 'unknown' when hostname matching fails, and 'unknown.conf'
+//       is not a file that should be read or written. ^host\d+$ is enforced first, so a host
+//       this plugin cannot identify gets a clear error instead of a confusing failure deeper
+//       in the script.
+//
+//   A missing script is reported, not executed.
+//       vv_auto_create_api_key() checks file_exists() before exec(), so a partial deploy
+//       returns a named error rather than a shell failure surfacing as an empty key.
+//
+//   The script run is externally time-boxed.
+//       `timeout 120` wraps it inside the library — PHP's own limit does not cover exec()
+//       time on Linux, so a stalled unraid-api call would otherwise hold a php-fpm worker
+//       open indefinitely. Exit 124 is reported as a timeout, distinctly from a script error.
+//
+//   Never cached.
+//       Cache-Control: no-store, no-cache. A cached provisioning response would report an old
+//       key preview after a genuine renewal — the one moment the preview matters.
+//
+//   Known gap: this is a state-changing action served over GET.
+//       Both callers (pages/setup.php, pages/partnership.php) fetch it, and POST bodies are
+//       unreliable on this nginx/PHP setup. It is guarded by the Unraid WebGUI session rather
+//       than by method or token. Documented rather than silently accepted — see the CSRF note
+//       in README-unraid.md.
+//
+// REQUEST
+//   GET, no parameters (the target host is the local host, by construction)
+//
+// RESPONSE
+//   {"ok":true,"key_preview":"abcd1234...wxyz"}   or "registered" when the key is not readable
+//   {"ok":false,"error":string}                   unknown host, missing script, or timeout
+//
+// DEPENDS ON
+//   include/config.php   vv_detect_host(), vv_auto_create_api_key()
+//   System_Essentials/unraid_api_key_renew.sh
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 header('Cache-Control: no-store, no-cache');
 require_once dirname(__DIR__) . '/include/config.php';
diff --git a/Plugin/unraid/api/docker.php b/Plugin/unraid/api/docker.php
index d7871fc..d8cd252 100644
--- a/Plugin/unraid/api/docker.php
+++ b/Plugin/unraid/api/docker.php
@@ -1,4 +1,62 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Docker folder endpoint. GET returns the full container inventory with folder assignments;
+//   POST performs one folder operation — create, rename, delete, move a container, or sync
+//   the folder store against master.conf in either direction.
+//
+// OPERATIONAL MODEL
+//   Read and write share one URL, split on HTTP method. GET is the docker tab's poll and is
+//   always safe. POST carries an `action` naming exactly one library call. Anything that is
+//   neither GET nor POST is refused with 405 before a parameter is read.
+//
+// DESIGN PRINCIPLES
+//   The action list is a closed match expression, not a dispatch table.
+//       Six named actions map to six library functions. An unrecognised action falls to the
+//       default arm and returns an error — it cannot resolve to a callable, because no part
+//       of the request is ever used to build a function name.
+//
+//   Grouping is metadata, never container control.
+//       This endpoint moves containers between folders in a JSON store. It does not start,
+//       stop, or recreate anything — that is docker_action.php, deliberately a separate file
+//       with a separate confirmation path in the UI.
+//
+//   Validation belongs to the library.
+//       Folder ids and names are trimmed here and checked in include/docker.php, so the same
+//       rules apply whether a call arrives from this endpoint or from the conf sync.
+//
+// OPERATIONAL SAFEGUARDS
+//   Wrong method is refused with a status code, not just a body.
+//       405 is set alongside the JSON error so a mistaken caller fails visibly rather than
+//       parsing an error object as data.
+//
+//   Every parameter is optional and defaults to empty.
+//       ?? '' on all four inputs means a malformed POST reaches the library as blank strings
+//       and is rejected there, rather than raising an undefined-index warning into the JSON
+//       body and corrupting the response.
+//
+//   The folder store is written atomically by the library.
+//       vv_dk_write_json() writes to .vv.tmp and rename()s, so a delete or move interrupted
+//       mid-write cannot leave a truncated store — which would scatter every container back
+//       to ungrouped.
+//
+// REQUEST
+//   GET                        full inventory, no parameters
+//   POST action=move_container container, folder_id
+//   POST action=create_folder  name
+//   POST action=rename_folder  folder_id, name
+//   POST action=delete_folder  folder_id
+//   POST action=sync_conf_to_json | sync_json_to_conf   no further parameters
+//
+// RESPONSE
+//   GET   vv_dk_all() verbatim — containers, folders, icons, WebUI links
+//   POST  {"ok":bool,"error":string|null} as returned by the invoked library call
+//
+// DEPENDS ON
+//   include/docker.php   vv_dk_all(), vv_dk_move_container(), vv_dk_create_folder(),
+//                        vv_dk_rename_folder(), vv_dk_delete_folder(),
+//                        vv_dk_sync_conf_to_json(), vv_dk_sync_json_to_conf()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/docker.php';
 
diff --git a/Plugin/unraid/api/docker_action.php b/Plugin/unraid/api/docker_action.php
index 6f07364..e467011 100644
--- a/Plugin/unraid/api/docker_action.php
+++ b/Plugin/unraid/api/docker_action.php
@@ -1,4 +1,91 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Container control. Start, stop, restart, tail logs, and pull-and-rebuild one container —
+//   the action buttons on the docker tab.
+//
+// OPERATIONAL MODEL
+//   Four of the five actions are synchronous and answer within the request. pull_rebuild is
+//   not: a pull can take minutes, so it spawns docker_pull_worker.php detached, returns a job
+//   id immediately, and the page polls job_status until the worker writes a terminal state.
+//   The job file in /tmp is the only channel between the two.
+//
+//   Deliberately separate from docker.php. That endpoint moves containers between folders —
+//   metadata only. This one starts and stops them. Keeping the destructive verbs in their own
+//   file is what lets the UI put a confirmation in front of exactly these and not the others.
+//
+//   Loads no library at all. Every operation here is a docker CLI call, and pulling in the
+//   config layer would add failure modes to the endpoint most likely to be used while
+//   something else is broken.
+//
+// DESIGN PRINCIPLES
+//   Prefers Unraid's own rebuild helper over stop/start.
+//       restart and pull_rebuild both try rebuild_container first, because recreating a
+//       container correctly means reapplying its full template — ports, mounts, variables. The
+//       stop/start fallback exists for when that helper is absent and is explicitly the lesser
+//       option.
+//
+//   The image is resolved from the container, never supplied.
+//       pull_rebuild reads both the current image id and the configured image reference via
+//       docker inspect. The request names a container; it cannot name what to pull into it.
+//
+//   Job ids are random, not sequential.
+//       bin2hex(random_bytes(8)) — a job's status is readable by anyone who can guess its id,
+//       so the id is not guessable.
+//
+//   Every action reports docker's own output.
+//       Combined stdout and stderr are returned rather than a generic failure message. When a
+//       container will not start, the reason is in that text and nowhere else.
+//
+// OPERATIONAL SAFEGUARDS
+//   The container name is pattern-matched and then confirmed to exist.
+//       ^[a-zA-Z0-9_.-]+$ excludes every shell metacharacter, and a `docker ps -a` lookup with
+//       an anchored filter must return that exact name before any container-scoped action
+//       runs. The existence check is what stops a valid-looking name from reaching an action
+//       at all — and it is anchored (^name$) so a prefix cannot select a different container.
+//
+//   Every value interpolated into a shell command is escaped.
+//       Container name, image, job file, worker path and the rebuild helper all pass through
+//       escapeshellarg(), on top of the pattern check rather than instead of it.
+//
+//   job_status is reachable without a container name, and is validated separately.
+//       It returns before the name check, because the container it refers to may have been
+//       recreated by then. Its id must match ^[0-9a-f]+$, so it cannot escape the job
+//       directory or name a file outside it.
+//
+//   An unknown job id reports pending, not missing.
+//       The worker writes its first state after the request returns, so a poll that arrives in
+//       between must not be told the job does not exist.
+//
+//   The job directory is private and created on demand.
+//       mkdir 0700 under /tmp — a hardcoded literal, not a config value, so no conf edit can
+//       redirect these writes. /tmp is tmpfs, so abandoned jobs clear on reboot.
+//
+//   pull_rebuild refuses to start without an image.
+//       An empty docker inspect result aborts before the worker is spawned, so a container
+//       whose image cannot be determined is never stopped in pursuit of an update.
+//
+//   Unknown actions fall through to an explicit error, so a typo cannot reach a container.
+//
+// REQUEST
+//   POST action=start|stop|restart  name=<container>
+//   POST action=logs                name=<container>     last 200 lines, timestamped
+//   POST action=pull_rebuild        name=<container>     spawns the worker, returns job_id
+//   POST action=job_status          job_id=<hex>         poll a pull_rebuild job
+//
+// RESPONSE
+//   {"ok":bool,"output":"<docker output>"}                start / stop / restart
+//   {"ok":true,"logs":"…"}                                logs
+//   {"ok":true,"status":"started","job_id":"…"}           pull_rebuild
+//   {"ok":true,"status":"pending"} or the worker's job file verbatim
+//   {"ok":false,"error":"invalid name"|"invalid job_id"|"Container not found"
+//                      |"Could not determine image"|"Unknown action"}
+//
+// DEPENDS ON
+//   api/docker_pull_worker.php   detached worker for the pull_rebuild path
+//   docker CLI                   ps, logs, start, stop, inspect
+//   dynamix.docker.manager       rebuild_container, when present
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 
 define('VV_JOB_DIR', '/tmp/varaverk_dk_jobs');
@@ -48,7 +135,7 @@ if ($action === 'start' || $action === 'stop') {
 if ($action === 'restart') {
     $rebuild = '/usr/local/emhttp/plugins/dynamix.docker.manager/scripts/rebuild_container';
     if (is_executable($rebuild)) {
-        exec($rebuild . ' ' . escapeshellarg($name) . ' 2>&1', $out, $rc);
+        exec(escapeshellarg($rebuild) . ' ' . escapeshellarg($name) . ' 2>&1', $out, $rc);
     } else {
         exec('docker stop '  . escapeshellarg($name) . ' 2>&1', $o1, $rc1);
         exec('docker start ' . escapeshellarg($name) . ' 2>&1', $o2, $rc2);
diff --git a/Plugin/unraid/api/docker_pull_worker.php b/Plugin/unraid/api/docker_pull_worker.php
index 787ab37..ddc7d84 100644
--- a/Plugin/unraid/api/docker_pull_worker.php
+++ b/Plugin/unraid/api/docker_pull_worker.php
@@ -1,7 +1,94 @@
 <?php
-// Background worker: docker pull → compare image ID → rebuild if updated.
-// Called via: php docker_pull_worker.php <name> <jobFile> <oldId> <image> <rebuild>
-[$name, $jobFile, $oldId, $image, $rebuild] = array_slice($argv, 1, 5);
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Container update worker. Pulls one image, decides whether it actually changed, and
+//   recreates the container if it did — reporting progress through a job file the docker tab
+//   polls.
+//
+// OPERATIONAL MODEL
+//   Not an HTTP endpoint. This runs as a detached CLI process, spawned by docker_action.php,
+//   because a pull can take minutes and no web request should be held open for it. It lives
+//   under api/ because it is part of that endpoint's implementation, not because it is
+//   reachable over HTTP — and it refuses to run if it ever is.
+//
+//   Progress is a file, not a return value. The parent request returns immediately with a job
+//   id; this process writes the current state to that file as it goes, and the page polls it.
+//   The file is the only channel between the two.
+//
+//   Called as: php docker_pull_worker.php <name> <jobFile> <oldId> <image> <rebuild>
+//
+// DESIGN PRINCIPLES
+//   Compares image ids, not pull output.
+//       `docker pull` reports success whether or not anything changed. The image id before
+//       and after is the only reliable signal, and it is what decides whether the container
+//       is disturbed at all — an up-to-date container is never restarted.
+//
+//   Prefers Unraid's own rebuild path.
+//       When a rebuild helper is supplied and executable it is used, because recreating a
+//       container correctly means reapplying its full template — ports, mounts, variables.
+//       The stop/start fallback exists for the case where that helper is unavailable, and is
+//       explicitly the lesser option: it picks up a new image only if the container was
+//       already configured to be recreated on start.
+//
+//   Every exit writes a terminal state.
+//       Both outcomes end with a job-file write, so the poller always converges. A worker that
+//       died without writing would leave the page spinning indefinitely.
+//
+// OPERATIONAL SAFEGUARDS
+//   Refuses to run under a web server.
+//       PHP_SAPI is checked first and a non-CLI invocation is answered with a 404 and no
+//       output. Without that, requesting this file over HTTP would evaluate it with no $argv
+//       at all — and it is a script whose entire job is to stop and restart containers.
+//
+//   Required arguments are checked before anything runs.
+//       Missing name, job file, or image exits non-zero before the first docker call, so a
+//       malformed spawn cannot pull or restart anything.
+//
+//   Every value interpolated into a shell command is escaped.
+//       Image, container name and the rebuild helper path all go through escapeshellarg(),
+//       even though they originate from docker_action.php rather than from a request. The
+//       escaping is what stays correct if that caller ever changes.
+//
+//   The rebuild helper is confirmed executable before it is invoked.
+//       is_executable() gates it, so a missing or non-executable helper falls back to
+//       stop/start rather than failing the update with a shell error.
+//
+//   Failure is reported as failure.
+//       A non-zero rebuild status writes ok:false with an explicit message. The image has
+//       already been pulled at that point, so silently reporting success would leave a
+//       container running an old image that the page claims was updated.
+//
+//   Docker output is captured, never echoed.
+//       Every call redirects stderr and the output is discarded or kept locally. This process
+//       has no stdout consumer; writing to it would only risk corrupting the job file if the
+//       two were ever pointed at the same place.
+//
+// ARGUMENTS
+//   1 name      container name
+//   2 jobFile   path the progress JSON is written to
+//   3 oldId     image id before the pull, for the changed/unchanged comparison
+//   4 image     image reference to pull
+//   5 rebuild   optional path to Unraid's container rebuild helper
+//
+// JOB FILE STATES
+//   {"ok":true,"status":"done","updated":false,"message":"Already up to date"}
+//   {"ok":true,"status":"rebuilding"}
+//   {"ok":true,"status":"done","updated":true,"message":"Updated and rebuilt"}
+//   {"ok":false,"status":"done","error":"Rebuild failed after pull"}
+//
+// DEPENDS ON
+//   api/docker_action.php   spawns this worker and creates the job file path
+//   docker CLI              pull, image inspect, stop, start
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+
+// This file stops and starts containers. It is a CLI worker and must never be reachable as a
+// web request — over HTTP there is no $argv, and every argument below would be undefined.
+if (PHP_SAPI !== 'cli') {
+    http_response_code(404);
+    exit(1);
+}
+
+[$name, $jobFile, $oldId, $image, $rebuild] = array_slice($argv, 1, 5) + array_fill(0, 5, '');
 
 if (!$name || !$jobFile || !$image) exit(1);
 
@@ -21,7 +108,7 @@ if ($oldId && $newId && $oldId === $newId) {
 jw($jobFile, ['ok' => true, 'status' => 'rebuilding']);
 
 if ($rebuild && is_executable($rebuild)) {
-    exec($rebuild . ' ' . escapeshellarg($name) . ' 2>&1', $out, $rc);
+    exec(escapeshellarg($rebuild) . ' ' . escapeshellarg($name) . ' 2>&1', $out, $rc);
 } else {
     exec('docker stop '  . escapeshellarg($name) . ' 2>&1', $o1, $rc1);
     exec('docker start ' . escapeshellarg($name) . ' 2>&1', $o2, $rc2);
diff --git a/Plugin/unraid/api/dryrun.php b/Plugin/unraid/api/dryrun.php
index eb37c0d..551cd7f 100644
--- a/Plugin/unraid/api/dryrun.php
+++ b/Plugin/unraid/api/dryrun.php
@@ -1,4 +1,69 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Dry-run launcher. Starts one script through run_job.sh with --dry-run, so the scheduler
+//   page can show what a job would do without letting it do any of it.
+//
+// OPERATIONAL MODEL
+//   Identical to run.php but for two differences: --dry-run is added, and there is no
+//   already-running guard. The missing guard is deliberate — a dry run changes nothing, so
+//   there is no reason to refuse one while a real run is in progress, and the two write to
+//   the same log where their output is distinguishable by the dry-run banner.
+//
+//   Fire and forget. The child is nohup'd and detached, and the response returns immediately
+//   with ok:true meaning "launched", not "finished". Progress is followed through log.php.
+//
+// DESIGN PRINCIPLES
+//   Never executes the target script directly.
+//       Everything goes through run_job.sh, so a dry run gets the same locking, logging, stat
+//       file and exit handling as a scheduled run. A second execution path would be a second
+//       set of bugs.
+//
+//   --dry-run is added here, honoured there.
+//       This endpoint guarantees the flag is passed; whether a given script actually respects
+//       it is that script's contract. The scripts that accept the flag are the ones the UI
+//       offers the button for.
+//
+// OPERATIONAL SAFEGUARDS
+//   The job id is validated and then confirmed to exist.
+//       ^[a-zA-Z0-9_./\-]+\.sh$ plus an explicit '..' check — the slash must be permitted for
+//       Category/name.sh ids, so traversal is caught by its own test rather than by the
+//       character class. file_exists() then confirms the resolved path is a real script, so a
+//       well-formed id for a file that is not there fails before anything is spawned.
+//
+//   The location argument must be absolute and clean.
+//       Leading slash required, '..' rejected, control characters rejected — then passed as a
+//       single escapeshellarg'd --location= token.
+//
+//   Extra arguments cannot become shell syntax.
+//       Control characters are rejected, then the string is split on whitespace and each
+//       token escaped individually. The previous blocklist of metacharacters missed newlines,
+//       which would have terminated the command line and started a second one — a blocklist
+//       has to be right about every character, whereas escaping each token is right about all
+//       of them.
+//
+//   Every interpolated value is escaped, including the ones that are already validated.
+//       Runner path, id, script path and log path all go through escapeshellarg() even though
+//       none of them can currently carry a metacharacter. Validation and escaping guard
+//       different things, and the escaping is what stays correct if the validation is ever
+//       loosened.
+//
+//   Output is appended, never truncated.
+//       >> to the job's own log with stdin from /dev/null, so a dry run cannot consume the
+//       request's stdin or discard the history of previous runs.
+//
+// REQUEST
+//   POST id=<Category/name.sh>  [location=/absolute/path]  [extra_args=…]
+//
+// RESPONSE
+//   {"ok":true}                              launched — not completed
+//   {"ok":false,"error":"Invalid id"|"Script not found: …"|"Invalid location"
+//                      |"Invalid extra_args"}
+//
+// DEPENDS ON
+//   include/scheduler.php   vv_job_log_path(), vv_job_flags()
+//   run_job.sh              the single execution path for every job
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/scheduler.php';
 
@@ -25,8 +90,11 @@ if ($location && (!str_starts_with($location, '/') || str_contains($location, '.
     exit;
 }
 
+// Control characters are rejected outright — a newline would end the command line and start
+// a second one. Everything that survives is split on whitespace and escaped per token, so
+// the shell never parses any of it as syntax.
 $extra_args = trim($_POST['extra_args'] ?? '');
-if ($extra_args && preg_match('/[;&|`$<>\\\\"\']/', $extra_args)) {
+if ($extra_args !== '' && preg_match('/[\x00-\x1f\x7f]/', $extra_args)) {
     echo json_encode(['ok' => false, 'error' => 'Invalid extra_args']);
     exit;
 }
@@ -34,7 +102,10 @@ if ($extra_args && preg_match('/[;&|`$<>\\\\"\']/', $extra_args)) {
 $runner   = dirname(__DIR__) . '/run_job.sh';
 $flags    = vv_job_flags($id);
 $locArg   = $location   ? ' ' . escapeshellarg('--location=' . $location) : '';
-$extraStr = $extra_args ? ' ' . $extra_args : '';
+$extraStr = '';
+foreach (preg_split('/\s+/', $extra_args, -1, PREG_SPLIT_NO_EMPTY) as $tok) {
+    $extraStr .= ' ' . escapeshellarg($tok);
+}
 exec('nohup bash ' . escapeshellarg($runner) . ' ' . escapeshellarg($id) . ' ' . escapeshellarg($script) . ' --dry-run' . ($flags ? " $flags" : '') . ' --manual' . $locArg . $extraStr . ' >> ' . escapeshellarg($logFile) . ' 2>&1 </dev/null &');
 
 echo json_encode(['ok' => true]);
diff --git a/Plugin/unraid/api/fallback.php b/Plugin/unraid/api/fallback.php
index aeeea10..144e3a9 100644
--- a/Plugin/unraid/api/fallback.php
+++ b/Plugin/unraid/api/fallback.php
@@ -1,4 +1,41 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Fallback data endpoint. One JSON document describing every node's fallback picture —
+//   state, tier activation, handback strikes, covered container status — for the fallback
+//   tab's 30s poll.
+//
+// DESIGN PRINCIPLES
+//   Thin transport. Every judgement about what a state file means lives in
+//   include/fallback.php. This file exists to give the browser a URL.
+//
+//   No parameters. There is exactly one answer to "what is the fallback state", so the
+//   endpoint takes no input and has no branch that can be asked for the wrong thing.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only by construction.
+//       There is no code path here that writes a state file, starts a container, or forces a
+//       tier. Failover and handback are driven by fallback.sh reacting to real reachability;
+//       a browser request is exactly the wrong way to enter either state.
+//
+//   Unknown is passed through, never smoothed into NORMAL.
+//       vv_fb_all() reports a missing or unparseable state file as empty rather than healthy.
+//       This endpoint encodes that verbatim instead of substituting a default, because
+//       claiming NORMAL for a fallback process that is not running is the worst available lie.
+//
+//   A dark partner degrades the payload, never fails it.
+//       Remote SSH failures inside vv_fb_all() return empty, so the node this page exists to
+//       diagnose cannot take the page down with it.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   vv_fb_all() verbatim — per-node state, tiers, strikes and covered container status
+//
+// DEPENDS ON
+//   include/fallback.php   vv_fb_all()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/fallback.php';
 echo json_encode(vv_fb_all());
diff --git a/Plugin/unraid/api/flag_toggle.php b/Plugin/unraid/api/flag_toggle.php
index 2d96f03..795265d 100644
--- a/Plugin/unraid/api/flag_toggle.php
+++ b/Plugin/unraid/api/flag_toggle.php
@@ -1,4 +1,73 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Rsync tier toggle. Flips one *_RSYNC_ENABLED boolean in master.conf and propagates the
+//   changed file to every partner host — the enable switches on the rsync tab.
+//
+// OPERATIONAL MODEL
+//   master.conf is shared, not per-host. A tier flag has to mean the same thing on both sides
+//   of the partnership or a sync will run from one end and not the other, so the write is
+//   always followed by a push. The push is a no-op on a non-owner: vv_push_master_conf()
+//   returns empty when this host has no SSH key, so a partner flipping a flag locally does
+//   not overwrite the owner's file.
+//
+//   Two flags exist at different levels — RSYNC_ENABLED is the global gate and the tier flags
+//   (CRITICAL_, INTERMEDIATE_, DAILY_, WEEKLY_, FALLBACK_) sit under it. This endpoint treats
+//   them identically; the precedence lives in the shell layer.
+//
+// DESIGN PRINCIPLES
+//   Toggles existing flags, never creates them.
+//       vv_conf_flag_set() rewrites a line that already matches NAME=true|false and returns
+//       false when nothing matched. A typo'd flag name fails loudly rather than appending a
+//       key no script reads.
+//
+//   Push results are reported, not swallowed.
+//       The per-host push outcome is returned in the response so the page can show that a
+//       partner did not receive the change. A flag that is set on one host and not the other
+//       is exactly the state that produces a one-sided sync.
+//
+//   Setup state is pushed alongside the conf.
+//       vv_push_setup_state() runs after the conf push so the partner's onboarding view
+//       reflects the same reality — the two are written together because they are read
+//       together.
+//
+// OPERATIONAL SAFEGUARDS
+//   POST only, checked before any parameter is read.
+//
+//   The flag name is constrained to the rsync namespace.
+//       ^[A-Z_]+_RSYNC_ENABLED$ — this endpoint cannot be used to flip an unrelated boolean
+//       in master.conf. Every other conf edit goes through confform.php or config.php, which
+//       have their own rules; a general-purpose flag setter would bypass all of them.
+//
+//   Anything other than the literal "1" is treated as false.
+//       ($_POST['enabled'] ?? '0') === '1' — strict comparison against one value, so a
+//       missing, malformed, or unexpected parameter disables rather than enables. Failing
+//       toward off is the safe direction for a flag that starts data movement.
+//
+//   The conf write is atomic.
+//       vv_conf_flag_set() writes through vv_write_conf_raw() (tmp + rename). Every script
+//       sources master.conf, so a truncated write would be a system-wide outage.
+//
+//   The push only happens after a confirmed local write.
+//       Guarded on $ok, so a failed edit cannot distribute a stale or partly-written conf to
+//       partners.
+//
+//   Related risk, not guarded here: turning RSYNC_ENABLED on for HOST2 onboarding requires
+//   re-reading the --merge-run / --delete interlock in Rsync/rsync.sh first. That is a
+//   property of the sync, not of this switch, and this endpoint does not enforce it.
+//
+// REQUEST
+//   POST name=<TIER>_RSYNC_ENABLED  enabled=0|1
+//
+// RESPONSE
+//   {"ok":true,"error":null,"push":[{"host","ok","ready","error"}, …]}
+//   {"ok":false,"error":"POST only"|"Invalid flag name"|"Failed to write master.conf",
+//    "push":[]}
+//
+// DEPENDS ON
+//   include/scheduler.php   vv_conf_flag_set() → vv_write_conf_raw()
+//   include/config.php      vv_push_master_conf(), vv_push_setup_state()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/scheduler.php';
 
diff --git a/Plugin/unraid/api/import_script.php b/Plugin/unraid/api/import_script.php
index 1abf97f..ae75837 100644
--- a/Plugin/unraid/api/import_script.php
+++ b/Plugin/unraid/api/import_script.php
@@ -1,7 +1,93 @@
 <?php
-// Import Script — lets the Scheduler page's "+ Import Script" browser move an existing
-// .sh file from anywhere on the server into CUSTOM_SCRIPTS_DIR. This is a MOVE: the
-// source is deleted once the copy is verified, so no stale duplicate is left behind.
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Script import. Browses the filesystem for .sh files and moves a chosen one into
+//   CUSTOM_SCRIPTS_DIR, so an existing script can be brought under Varaverk's scheduler
+//   without retyping it.
+//
+// OPERATIONAL MODEL
+//   Two actions on one URL: a GET browser and a POST import. The browser is rooted at / and
+//   walks one directory at a time, because the scripts people want to import live wherever
+//   they happened to put them — most often the User Scripts plugin's own folders.
+//
+//   This is a move, not a copy. The source is deleted once the destination is verified, so
+//   there is exactly one copy afterwards and no chance of editing the wrong one. That is also
+//   why the verification is so deliberate: a move that half-succeeds destroys the only copy.
+//
+// DESIGN PRINCIPLES
+//   Copy, verify, then delete — in that order, always.
+//       copy() first, then a size comparison and a SHA-256 of both files, and only then the
+//       unlink. Source and destination are routinely on different filesystems, where rename()
+//       is not atomic and a partial write is a real outcome rather than a theoretical one.
+//
+//   A failed verification leaves the source untouched.
+//       The destination is removed and the source is left exactly where it was. Between
+//       losing the import and losing the script, the import is the acceptable loss.
+//
+//   An undeletable source is a warning, not a failure.
+//       If the copy verified but the original could not be removed — read-only mount,
+//       permissions — the import is reported successful with a warning naming the file to
+//       clean up. The script works from its new home either way, and failing the whole
+//       operation would leave the user with two copies and an error message.
+//
+//   Directory listings are capped and sorted.
+//       300 entries each for directories and .sh files. A browser rooted at / will eventually
+//       be pointed at something enormous.
+//
+// OPERATIONAL SAFEGUARDS
+//   Refuses to import from inside the Varaverk repo.
+//       Both paths are resolved with realpath() and compared by prefix. Importing a tracked
+//       file would delete it out from under git with no commit recording it — the next pull
+//       would either restore it as a phantom or report a deletion nobody made. This check is
+//       the reason realpath() is used rather than the submitted string: a symlink into the
+//       repo would otherwise slip past a textual comparison.
+//
+//   Refuses a source already inside CUSTOM_SCRIPTS_DIR.
+//       Also compared after realpath(). Without it, the move would copy a file onto itself
+//       and then delete it.
+//
+//   Refuses to overwrite an existing custom script.
+//       file_exists() on the destination aborts with the conflicting name. A silent overwrite
+//       here would destroy a script that may already be scheduled and running.
+//
+//   Both paths are validated as absolute with no traversal.
+//       ^/[^\0]*$ for the browse path and ^/[^\0]*\.sh$ for the import, plus an explicit '..'
+//       check on each. Null bytes are excluded by the character class, which matters because
+//       these strings reach both the filesystem and a shell.
+//
+//   Both find invocations escape their argument, and neither takes anything else from the
+//   request — depth, type and name filters are all literals.
+//
+//   The destination is made executable before it is reported.
+//       chmod 0755 after verification, so a freshly imported script is immediately runnable
+//       rather than failing the first time it is scheduled.
+//
+//   Existence is confirmed before work begins — is_dir() for browse, is_file() for import —
+//   so a bad path returns a named error rather than a warning leaking into the JSON body.
+//
+//   Accepted exposure: the browser can list any directory on the host.
+//       It returns directory names and .sh filenames only — no file contents, and nothing
+//       outside those two types. That is the minimum a file picker rooted at / can do, and it
+//       is guarded by the Unraid WebGUI session; see the CSRF note in README-unraid.md.
+//
+// REQUEST
+//   GET  ?action=browse&path=/absolute/dir     list subdirectories and .sh files
+//   POST action=import  path=/absolute/file.sh move it into CUSTOM_SCRIPTS_DIR
+//
+// RESPONSE
+//   browse  {"ok":true,"path","dirs":[…],"files":[…],"parent":…}
+//   import  {"ok":true,"id":"Custom/<name>.sh"}  optionally with a "warning"
+//   {"ok":false,"error":"Invalid path"|"Not a directory: …"|"Invalid script path"
+//                      |"Not found: …"|"Could not resolve path"
+//                      |"Refusing to import from inside the Varaverk repo …"
+//                      |"Already in Custom Scripts."|"A script named \"…\" already exists …"
+//                      |"Copy failed"|"Copy verification failed — source left untouched"
+//                      |"Invalid request"}
+//
+// DEPENDS ON
+//   include/config.php   SCRIPTS_DIR, CUSTOM_SCRIPTS_DIR
+//   api/script.php       manages the scripts once they are here
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 header('Cache-Control: no-store, no-cache');
 require_once dirname(__DIR__) . '/include/config.php';
diff --git a/Plugin/unraid/api/log.php b/Plugin/unraid/api/log.php
index f5b0415..5c7cc4e 100644
--- a/Plugin/unraid/api/log.php
+++ b/Plugin/unraid/api/log.php
@@ -1,4 +1,70 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Job log endpoint. Returns the tail of one job's log for the scheduler page's live output
+//   view, and — on POST with clear=1 — truncates it.
+//
+// OPERATIONAL MODEL
+//   Read and clear share one URL because they share one identifier and one validation path.
+//   The method decides which: GET always reads, POST reads unless clear is set. Splitting
+//   them would duplicate the id validation, which is the only part with teeth.
+//
+//   The response carries the log's mtime as ts, so the page can tell a log that is still
+//   growing from one that has stopped without diffing the content it already has.
+//
+// DESIGN PRINCIPLES
+//   Tail, never the whole file.
+//       The last 200 lines. Orchestrator logs are appended to indefinitely and this is polled
+//       while a job runs, so returning the file would grow the response without bound exactly
+//       when the page is fetching it most often.
+//
+//   A log that does not exist is a successful empty read.
+//       ok:true with empty content and ts:0. A job that has never run has no log, and that is
+//       a normal state on a fresh install — not a condition the page should report as an
+//       error.
+//
+//   Clearing truncates, never deletes.
+//       file_put_contents with an empty string keeps the inode, so a running job's open file
+//       handle keeps writing to the same file. Unlinking it would leave the job appending to
+//       a file nothing can read.
+//
+// OPERATIONAL SAFEGUARDS
+//   The job id is validated identically on both paths.
+//       ^[a-zA-Z0-9_./\-]+\.sh$ plus an explicit '..' check, applied before the method is
+//       branched on, so the clear path cannot be reached with an id the read path would have
+//       rejected. The slash must be permitted for Category/name.sh ids, which is why
+//       traversal gets its own test rather than being implied by the character class.
+//
+//   The id is never used as a path directly.
+//       vv_job_log_path() maps it into LOG_DIR and rewrites the .sh suffix to .log, so the
+//       only files this endpoint can name are job logs — the .sh requirement in the pattern
+//       is what makes that rewrite total.
+//
+//   Clearing requires POST and an explicit flag.
+//       A GET cannot truncate a log, and a POST without clear=1 reads like any other request.
+//       Destroying output needs to be asked for twice, in two different ways.
+//
+//   Clearing an absent log is success, not an error.
+//       file_exists() is checked first, so clearing a job that has never run reports ok
+//       rather than failing on a file the caller did not expect to exist anyway.
+//
+//   The tail read degrades to empty.
+//       file() with a ?: [] fallback, so an unreadable or vanishing log yields an empty view
+//       instead of a fatal that would blank the page mid-poll.
+//
+// REQUEST
+//   GET  ?id=<Category/name.sh>              last 200 lines
+//   POST id=<…>                              same as GET
+//   POST id=<…>  clear=1                     truncate the log
+//
+// RESPONSE
+//   {"ok":true,"content":"…","ts":<mtime>}   read — ts is 0 when the log does not exist
+//   {"ok":true}                              clear
+//   {"ok":false,"error":"Invalid job id"}
+//
+// DEPENDS ON
+//   include/scheduler.php   vv_job_log_path()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/scheduler.php';
 
diff --git a/Plugin/unraid/api/manual_sync.php b/Plugin/unraid/api/manual_sync.php
index cfcf878..eb965b8 100644
--- a/Plugin/unraid/api/manual_sync.php
+++ b/Plugin/unraid/api/manual_sync.php
@@ -1,4 +1,129 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Ad-hoc rsync between hosts. Picks a partner, browses both filesystems to choose a source
+//   and destination, runs a transfer in the background, streams its output, and cancels it —
+//   the manual sync panel on the rsync tab.
+//
+// OPERATIONAL MODEL
+//   Entirely outside the profile system. The scheduled tiers sync configured shares with
+//   configured profiles; this is for the one-off move that does not belong in a conf file —
+//   seeding a new host, recovering a share, copying something once. Nothing here is recorded,
+//   scheduled, or repeated.
+//
+//   Six actions on one URL, in the order the panel uses them: hosts, browse, browse_local,
+//   run, poll, stop. run returns a token immediately and the transfer continues detached; poll
+//   reads its log until a sentinel appears; stop kills it.
+//
+//   Progress is a log file in /tmp keyed by token, terminated by a __DONE__ sentinel the
+//   wrapper appends after rsync exits. That sentinel is what lets poll distinguish "still
+//   running" from "finished" without inspecting a process — and the pid file is the backstop
+//   for the case where rsync died without reaching it.
+//
+//   Both filesystems are browsed the same way, one directory at a time. The remote side runs
+//   the same find over SSH that the local side runs directly, so the two panes behave
+//   identically.
+//
+// DESIGN PRINCIPLES
+//   Source is always local, destination always remote.
+//       The direction is fixed. A tool that could pull as well as push would need twice the
+//       path validation and would make "which side am I about to overwrite" a question the
+//       user has to answer correctly every time.
+//
+//   Trailing slashes are normalised onto both paths.
+//       rsync's most consequential piece of syntax is whether the source ends in a slash. It
+//       is appended unconditionally here so the transfer always means "the contents of", never
+//       "the directory itself nested inside".
+//
+//   One manual sync at a time, host-wide.
+//       Enforced by scanning for any live pid file, not per token. Two concurrent ad-hoc
+//       transfers would compete for the same bandwidth the scheduled tiers are also using.
+//
+//   An inconclusive remote check proceeds; a definite failure stops.
+//       A destination that reports 'missing' is refused. An SSH check that answers neither
+//       'ok' nor 'missing' — Tailscale still coming up, for instance — is allowed through,
+//       because rsync will fail cleanly and visibly in the log if the path really is wrong.
+//
+// OPERATIONAL SAFEGUARDS
+//   System paths are refused as both source and destination.
+//       An explicit blocklist — /, /proc, /sys, /dev, /run, /etc, /bin, /sbin, /usr, /lib,
+//       /lib64, /boot/EFI, /tmp — compared after trailing-slash normalisation so /etc and
+//       /etc/ are the same answer. This is the guard against a blank or truncated field
+//       collapsing into a path that would sync the operating system over the network.
+//
+//   Both paths must be absolute, traversal-free, and free of shell metacharacters.
+//       Leading slash required, '..' rejected, and null bytes, newlines, backticks and $
+//       rejected outright — then escapeshellarg() on top.
+//
+//   rsync flags cannot become shell syntax.
+//       Control characters are rejected and every remaining token is escaped individually.
+//       The previous blocklist stripped metacharacters but not newlines, and these flags are
+//       spliced into a `bash -c` script — a newline would have started a second command
+//       inside it. Escaping each token is right about every character; a blocklist has to be.
+//
+//   The bandwidth limit is cast, not filtered.
+//       (int) with a max(0, …) floor, so it can only ever be a non-negative number.
+//
+//   The remote user is reduced to a safe character set before it is used.
+//       preg_replace strips everything outside [a-z0-9_.-], with 'root' as the fallback when
+//       nothing survives.
+//
+//   The local source is confirmed to exist before anything is launched.
+//
+//   Tokens are random and fixed-length.
+//       bin2hex(random_bytes(8)) produces the token; poll and stop both reduce the submitted
+//       value to hex and require exactly 16 characters, so neither can name a file outside
+//       the /tmp/vv_ms_ namespace. A transfer's log is readable by anyone who can guess its
+//       token, so the token is not guessable.
+//
+//   Stop escalates and then cleans up.
+//       SIGTERM, 400ms, SIGKILL — rsync should be given the chance to finish its current file
+//       and close its connection. The cancellation is then written into the log with the
+//       sentinel, so a poll already in flight terminates cleanly instead of hanging.
+//
+//   Poll detects a crashed transfer as well as a finished one.
+//       A missing sentinel with a dead pid is reported done with an explicit note, so a
+//       transfer killed by OOM or a reboot does not leave the panel polling forever.
+//
+//   SSH is non-interactive and time-boxed.
+//       BatchMode=yes and ConnectTimeout=10 on the transfer, 8s and 4s on the browse and ping
+//       calls — nothing here can sit waiting for a password or a dead host.
+//
+//   Log files are removed on the terminal poll, so a completed transfer does not leave its
+//   output in /tmp indefinitely. /tmp is tmpfs, so an abandoned one clears at reboot anyway.
+//
+//   Accepted exposure: browse can list any directory on either host.
+//       Directory names only — no file contents, no file names. Guarded by the Unraid WebGUI
+//       session; see the CSRF note in README-unraid.md.
+//
+// REQUEST
+//   GET  ?action=hosts                             partners, Tailscale state, key presence
+//   GET  ?action=browse&host=<slot>&path=/dir      remote directory listing over SSH
+//   GET  ?action=browse_local&path=/dir            local directory listing
+//   POST action=run  local=/src  host=<slot>  remote_path=/dst
+//        [user=root] [bw_limit=<KB/s>] [use_key=0|1] [flags=<rsync flags>]
+//   GET  ?action=poll&token=<hex16>                output so far, and whether it finished
+//   POST action=stop  token=<hex16>                cancel a running transfer
+//
+// RESPONSE
+//   hosts    {"ok":true,"hosts":[{slot,id,hostname,online,ip}],"has_key":bool,"ssh_key":"…"}
+//   browse   {"ok":true,"path","dirs":[…],"parent":…}      max 200 entries
+//   run      {"ok":true,"token":"<hex16>"}
+//   poll     {"ok":true,"output":"…","done":bool,"started":bool}
+//   stop     {"ok":true}
+//   {"ok":false,"error":"Invalid path"|"Missing: …"|"Refusing to sync from system path: …"
+//                      |"Local source does not exist: …"|"Another manual sync is already
+//                        running — stop it first."|"Remote destination does not exist: …"
+//                      |"SSH connection failed to …"|"Invalid flags"|"Invalid token"
+//                      |"Unknown action"}
+//
+// DEPENDS ON
+//   include/config.php        vv_detect_host(), vv_read_conf_raw(), vv_conf_vars(),
+//                             vv_resolve_tailscale_ip()
+//   include/arrs.php          vv_arr_known_hosts(), vv_arr_scalar()
+//   include/partnership.php   vv_pt_ts_peers(), vv_pt_ssh()
+//   /tmp/vv_ms_<token>.log|.pid   per-transfer state
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 header('Cache-Control: no-store, no-cache');
 require_once dirname(__DIR__) . '/include/config.php';
@@ -104,8 +229,16 @@ if ($_SERVER['REQUEST_METHOD'] === 'POST' && $action === 'run') {
     $user       = preg_replace('/[^a-z0-9_.-]/i', '', trim($_POST['user'] ?? 'root')) ?: 'root';
     $bwLimit    = max(0, (int)($_POST['bw_limit'] ?? 0));
     $useKey     = ($_POST['use_key'] ?? '1') !== '0';
-    $rawFlags   = trim($_POST['flags'] ?? '');
-    $flags      = $rawFlags !== '' ? preg_replace('/[`$!|&;><(){}\[\]\\\\]/', '', $rawFlags) : '-av --stats';
+    // Control characters are rejected outright — a newline would start a second command
+    // inside the bash -c script this is spliced into. What survives is split on whitespace
+    // and escaped per token below, so the shell never parses any of it as syntax.
+    $rawFlags = trim($_POST['flags'] ?? '');
+    if ($rawFlags !== '' && preg_match('/[\x00-\x1f\x7f]/', $rawFlags)) {
+        echo json_encode(['ok' => false, 'error' => 'Invalid flags']); exit;
+    }
+    $flagList = $rawFlags !== ''
+        ? preg_split('/\s+/', $rawFlags, -1, PREG_SPLIT_NO_EMPTY)
+        : ['-av', '--stats'];
 
     foreach (['local' => $local, 'host' => $slot, 'remote_path' => $remotePath] as $f => $v) {
         if (!$v) { echo json_encode(['ok' => false, 'error' => 'Missing: ' . $f]); exit; }
@@ -170,7 +303,8 @@ if ($_SERVER['REQUEST_METHOD'] === 'POST' && $action === 'run') {
     } else {
         $sshOpts = 'ssh -o StrictHostKeyChecking=no -o ConnectTimeout=10';
     }
-    if ($bwLimit) $flags .= ' --bwlimit=' . (int)$bwLimit;
+    if ($bwLimit) $flagList[] = '--bwlimit=' . (int)$bwLimit;
+    $flags = implode(' ', array_map('escapeshellarg', $flagList));
 
     $src = escapeshellarg(rtrim($local, '/') . '/');
     $dst = escapeshellarg($user . '@' . $t['ip'] . ':' . rtrim($remotePath, '/') . '/');
diff --git a/Plugin/unraid/api/media.php b/Plugin/unraid/api/media.php
index 2fcd580..ed5cff1 100644
--- a/Plugin/unraid/api/media.php
+++ b/Plugin/unraid/api/media.php
@@ -1,4 +1,38 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Active media sessions endpoint. Normalised now-playing across every Emby, Jellyfin and
+//   Plex instance configured for this host, for the monitor page's session panel.
+//
+// DESIGN PRINCIPLES
+//   Thin transport. Discovery, per-server API dialects and normalisation all live in
+//   include/media.php; this file only sets the content type and encodes the result.
+//
+//   No parameters. Which servers to ask is derived from conf, not from the request, so the
+//   browser cannot point this endpoint at an arbitrary URL.
+//
+// OPERATIONAL SAFEGUARDS
+//   Bounded by the library's 3s per-request timeout.
+//       A wedged media server cannot hold this endpoint open, because every fetch inside
+//       vv_media_sessions() carries a stream-context timeout. This is the only thing between
+//       a hung Emby and a poll that never returns.
+//
+//   Failure is an empty list, not an error.
+//       Unreachable servers, non-JSON bodies and unexpected shapes all resolve to [] inside
+//       the library. The panel renders empty and the rest of the monitor page is unaffected.
+//
+//   Read-only. Sessions are observed. Nothing here stops a stream, forces a transcode, or
+//   messages a client.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   vv_media_sessions() verbatim — a flat list of normalised sessions across all servers
+//
+// DEPENDS ON
+//   include/media.php   vv_media_sessions()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/media.php';
 
diff --git a/Plugin/unraid/api/monitor.php b/Plugin/unraid/api/monitor.php
index bdd8c4c..04ad0b6 100644
--- a/Plugin/unraid/api/monitor.php
+++ b/Plugin/unraid/api/monitor.php
@@ -1,4 +1,81 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Full monitor payload. Every metric the monitor page renders — system, CPU, memory,
+//   network, GPUs, disks and pools, array, parity, UPS, containers, VMs, transcodes, watchdog
+//   and rsync summaries, and remote node roll-ups — in one document.
+//
+// OPERATIONAL MODEL
+//   Deliberately one large response rather than many small ones. Most of these metrics share
+//   an underlying source — the Unraid API, /proc, the same emhttp ini files — so collecting
+//   them together means one pass over each source instead of one per endpoint. The page
+//   renders from a single consistent snapshot; twenty parallel fetches would render from
+//   twenty slightly different moments.
+//
+//   Served from a 300s cache written by Tools/api_cache_writer.sh, which runs every minute.
+//   The page therefore almost never pays for collection — the background writer does. ?live
+//   forces a fresh build for the refresh button.
+//
+// DESIGN PRINCIPLES
+//   The cache check happens before the heavy includes.
+//       Only include/config.php is loaded to reach vv_cache_read(). monitor.php, vms.php and
+//       docker_folders.php are required only after a miss, so a cache hit costs one file read
+//       rather than parsing three libraries.
+//
+//   The API cache is pre-warmed once, on purpose.
+//       vv_api_data() is called before the payload is assembled so the API-first functions
+//       below it share a single GraphQL round trip instead of each making their own.
+//
+//   Every field is a named function call, in render order.
+//       The payload is a flat map of key to collector. Adding a metric is adding a line, and
+//       nothing in the assembly depends on anything else in it — so one expensive or broken
+//       collector can be moved or removed without touching the others.
+//
+//   Reports the API's own health alongside the data.
+//       _api_status travels with the payload, so the page can show that a section degraded to
+//       its local fallback rather than silently presenting less detail.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Every function here observes; none of them start, stop, or change anything.
+//
+//   Cache miss is distinguished from empty payload.
+//       vv_cache_read() returns null on a miss, expiry, or unparseable file, and the check is
+//       an explicit !== null — so a legitimately sparse payload is served from cache instead
+//       of being mistaken for a miss and forced onto the expensive path on every poll.
+//
+//   Every collector degrades to empty rather than fatal.
+//       The library suppresses its filesystem reads and redirects stderr on every shell call,
+//       so absent hardware — no GPU, no UPS, no ZFS, no VMs — yields an empty section and an
+//       unrendered card. On a payload this wide that property is what keeps one missing
+//       subsystem from blanking the entire page.
+//
+//   Remote collection degrades per node, so one dark partner costs its own card and nothing
+//   else.
+//
+//   Known cost: a cache miss on a host with an unreachable partner pays the remote SSH
+//   timeouts inline. That is why the background writer exists and why the cache window is
+//   long — the miss path is the exception, not the design.
+//
+// REQUEST
+//   GET             served from the 300s cache when one is present
+//   GET ?live       bypass the cache and collect everything fresh
+//
+// RESPONSE
+//   A flat object of the keys listed in the assembly below, plus _api_status and ts.
+//
+// DEPENDS ON
+//   include/config.php          vv_cache_read()
+//   include/common.php          raw hardware metrics — system, cpu, mem, net, gpu, disks,
+//                               ups, parity, containers, transcodes, remote roll-ups
+//                               (loaded transitively through include/monitor.php)
+//   include/monitor.php         the "is anything wrong" roll-ups — vv_partner_state(),
+//                               vv_fallback_state(), vv_watchdog_summary(),
+//                               vv_scripts_status(), vv_rsync_status()
+//   include/unraid_api.php      vv_api_data(), vv_api_get_status()
+//   include/vms.php             vv_get_vms()
+//   include/docker_folders.php  vv_get_docker_folders()
+//   Tools/api_cache_writer.sh   writes the cache this endpoint normally serves
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
diff --git a/Plugin/unraid/api/monitor_fast.php b/Plugin/unraid/api/monitor_fast.php
index 8cd616f..cc1d414 100644
--- a/Plugin/unraid/api/monitor_fast.php
+++ b/Plugin/unraid/api/monitor_fast.php
@@ -1,4 +1,75 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   High-frequency monitor poll. CPU, memory and network only, cheap enough to fetch every
+//   second — the live-updating subset of what monitor.php returns in full.
+//
+// OPERATIONAL MODEL
+//   Split from monitor.php on refresh rate. The fields here move second to second and are
+//   readable from /proc alone. Everything that needs `docker stats`, a GraphQL call, or an
+//   SSH round trip stays in the full payload, because those cannot be sampled at this rate.
+//
+//   The expensive memory breakdown is borrowed rather than recomputed. Docker and VM memory,
+//   top processes and swap come from the last full cache — a 600s window, wide enough that
+//   the card stays populated even when the background writer falls behind. Stale is the right
+//   trade here: per-container memory does not move meaningfully between seconds, and paying
+//   for it would defeat the point of this endpoint.
+//
+// DESIGN PRINCIPLES
+//   Reads /proc directly, no shell.
+//       /proc/meminfo and the ZFS arcstats file are parsed inline. At this poll rate a single
+//       fork per request would dominate the cost of the endpoint.
+//
+//   Shares the CPU baseline with everything else.
+//       vv_cpu_per_core() keeps its counters in a shared state file, so this endpoint, the
+//       header snapshot, and the full monitor payload all report the same number rather than
+//       three independent samples that visibly disagree.
+//
+//   Free means available, not unused.
+//       MemAvailable, not MemFree — reclaimable page cache is not memory pressure, and
+//       reporting MemFree would show a healthy machine as nearly full.
+//
+//   ZFS ARC is broken out of system memory.
+//       On a host with ZFS cache pools the ARC is most of the "used" figure and is fully
+//       reclaimable. Folding it into system memory would make every reading alarming and
+//       none of them actionable.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only.
+//
+//   Every source read has a fallback.
+//       file() with a ?: [] fallback, @file() for the arcstats path that does not exist on a
+//       host without ZFS, and ?? 0 on every extracted key. A missing subsystem contributes
+//       zero rather than a warning or a fatal — and at one request per second, a fatal here
+//       would be a page that never stops erroring.
+//
+//   The borrowed fields degrade to zero independently.
+//       Each ?? default is applied per field, so an absent or expired full cache costs those
+//       four values and leaves CPU, memory and network — the reason to call this endpoint —
+//       intact.
+//
+//   Swap has its own fallback path.
+//       When the cached figures are absent, swap is recomputed from /proc/meminfo rather than
+//       reported as zero, because zero swap used and unknown swap used look identical in the
+//       UI and mean very different things.
+//
+//   Derived values are clamped.
+//       max(0, …) on used and system memory, so the subtraction cannot go negative when the
+//       cached docker and VM figures were sampled against a different total.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   {"cpu":{…},"mem":{total_kb,free_kb,used_kb,arc_kb,docker_kb,vm_kb,system_kb,
+//    swap_total_kb,swap_used_kb,top_procs},"net":{…},"ts":epoch}
+//
+// DEPENDS ON
+//   include/config.php   vv_cache_read()
+//   include/common.php   vv_cpu_per_core(), vv_network_stats()
+//   /proc/meminfo, /proc/spl/kstat/zfs/arcstats
+//   monitor cache        written by Tools/api_cache_writer.sh — source of the borrowed fields
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 require_once dirname(__DIR__) . '/include/common.php';
diff --git a/Plugin/unraid/api/monitor_remote.php b/Plugin/unraid/api/monitor_remote.php
index c941f11..42c9139 100644
--- a/Plugin/unraid/api/monitor_remote.php
+++ b/Plugin/unraid/api/monitor_remote.php
@@ -1,11 +1,64 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Remote node metrics endpoint. The monitor page's partner cards — CPU, memory, storage,
+//   uptime and container counts for every host other than this one.
+//
+// OPERATIONAL MODEL
+//   Split from monitor.php on cost, not on subject. Local metrics are cheap file reads;
+//   remote metrics are SSH round trips to every partner. Keeping them on separate URLs lets
+//   the page poll local stats often and remote stats rarely, and lets a dark partner slow
+//   only its own request. Served from a 1-hour cache by default; ?live bypasses it for the
+//   page's explicit refresh button.
+//
+// DESIGN PRINCIPLES
+//   The cache is the default and the live call is the exception.
+//       An hour is deliberately long. Partner hardware stats do not move fast enough to
+//       justify paying SSH latency on every page load, and the refresh button exists for the
+//       moment someone actually needs current numbers.
+//
+//   Every payload carries its own timestamp.
+//       ts is written into the cached document, so the page can render the age rather than
+//       presenting hour-old numbers as current.
+//
+//   The live path writes the cache too.
+//       A manual refresh benefits every subsequent visitor instead of being discarded.
+//
+// OPERATIONAL SAFEGUARDS
+//   Cache miss is distinguished from empty payload.
+//       vv_cache_read() returns null on a miss, expiry, or unparseable file, and the check is
+//       an explicit !== null. A legitimately empty result — the single-host case, where there
+//       are no remote hosts at all — is served from cache rather than being mistaken for a
+//       miss and forced onto the SSH path on every single poll.
+//
+//   Read-only over SSH. The remote commands are stat collection only; nothing is started,
+//   stopped, or written on a partner.
+//
+//   Unreachable partners degrade per node inside vv_remote_hosts_stats(), so one dark host
+//   cannot empty the other cards.
+//
+//   HTTP caching is disabled even though the payload is cached server-side.
+//       The two are not the same lever. The server-side cache has an age the page can see and
+//       a bypass it can trigger; a browser or proxy cache has neither, and would defeat ?live
+//       entirely.
+//
+// REQUEST
+//   GET             served from the 3600s cache when one is present
+//   GET ?live       bypass the cache, collect fresh, and rewrite it
+//
+// RESPONSE
+//   {"remote_hosts":{…},"ts":epoch}
+//
+// DEPENDS ON
+//   include/monitor.php   vv_remote_hosts_stats(), vv_cache_read(), vv_cache_write()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 header('Cache-Control: no-cache, no-store');
 require_once dirname(__DIR__) . '/include/monitor.php';
 
 if (!isset($_GET['live'])) {
     $cached = vv_cache_read('monitor_remote', 3600);
-    if ($cached) { echo json_encode($cached); exit; }
+    if ($cached !== null) { echo json_encode($cached); exit; }
 }
 
 $data = ['remote_hosts' => vv_remote_hosts_stats(), 'ts' => time()];
diff --git a/Plugin/unraid/api/movescript.php b/Plugin/unraid/api/movescript.php
index 1c9fc60..463f6ad 100644
--- a/Plugin/unraid/api/movescript.php
+++ b/Plugin/unraid/api/movescript.php
@@ -1,6 +1,84 @@
 <?php
-// Move a script between *_SCRIPTS arrays in master.conf.
-// POST: script (rel path), to_array (var name, or '' to remove from all arrays).
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Moves a script between orchestrators. Removes its line from whichever *_SCRIPTS array in
+//   master.conf currently holds it and inserts it into the named one — or into none, which
+//   removes it from every orchestrator.
+//
+// OPERATIONAL MODEL
+//   Line surgery on master.conf, not a re-serialisation. The file is read as lines, one line
+//   is relocated, and the rest is written back byte for byte. master.conf is hand-maintained
+//   and full of comments, grouping and deliberate ordering that no round trip through a
+//   parser would preserve.
+//
+//   Two passes, in order: remove first, then insert. Doing it in one pass would need to know
+//   whether the target array comes before or after the source, and getting that wrong would
+//   either duplicate the entry or drop it.
+//
+//   Position within the target array is the end, immediately before its closing paren.
+//   Orchestrators run their arrays in order, so appending is the only placement that does not
+//   silently reorder someone else's work.
+//
+// DESIGN PRINCIPLES
+//   Move is remove-plus-insert, and remove alone is a valid operation.
+//       An empty to_array performs only the removal pass, which is how a script is taken out
+//       of every orchestrator. That is a distinct intent from conf_toggle.php's commenting
+//       out — this removes the line, that disables it in place.
+//
+//   Indentation is normalised on re-insertion.
+//       The moved line is rewritten as two spaces and the quoted path, so a script does not
+//       carry its old array's formatting into its new one.
+//
+//   A move that finds nothing to move still succeeds.
+//       The removal pass is best-effort; only a missing *target* is an error. A script that
+//       was in no array is simply added to the one requested.
+//
+// OPERATIONAL SAFEGUARDS
+//   POST only, checked before any parameter is read.
+//
+//   Both inputs are pattern-matched, and neither is used as a path.
+//       The script must match ^[A-Za-z0-9_.\-/]+\.sh$ with an explicit '..' check, and the
+//       array name ^[A-Z_]+_SCRIPTS$. Both then reach the matcher only through preg_quote(),
+//       so they are needles matched against existing lines — nothing is opened or executed
+//       from either.
+//
+//   The scope of both passes is bounded to array bodies.
+//       Each pass tracks whether it is inside a *_SCRIPTS=( block and ignores every line
+//       outside one, so a matching string in a comment or an unrelated variable is never
+//       moved or displaced.
+//
+//   A missing target array aborts before the write.
+//       If the insert pass never finds the target, the endpoint returns an error and writes
+//       nothing — the removal is discarded with it. Without that check a typo'd array name
+//       would silently delete the script from the orchestrator it was in.
+//
+//   master.conf is confirmed present and readable before either pass.
+//       Both file_exists() and the file() result are checked, so a missing or unreadable conf
+//       returns a named error rather than writing a file built from an empty line list.
+//
+//   The write is atomic.
+//       vv_write_conf_raw() writes .vv.tmp and rename()s. Every script sources master.conf,
+//       so a truncated write here would be a system-wide outage rather than a lost move.
+//
+//   The push happens only after a confirmed write, and its result is returned.
+//       A partner that did not receive the move is exactly the state that makes one host run
+//       a script the other does not, so the per-host outcome is reported rather than
+//       discarded.
+//
+// REQUEST
+//   POST script=<Category/name.sh>  to_array=<NAME>_SCRIPTS
+//   POST script=<Category/name.sh>  to_array=            remove from all arrays
+//
+// RESPONSE
+//   {"ok":true,"push":[{"host","ok","ready","error"}, …]}
+//   {"ok":false,"error":"POST only"|"Invalid script"|"Invalid array name"
+//                      |"master.conf not found"|"Could not read master.conf"
+//                      |"Target array \"…\" not found in master.conf"|"Write failed"}
+//
+// DEPENDS ON
+//   include/config.php   CONF_DIR, vv_write_conf_raw(), vv_push_master_conf(),
+//                        vv_push_setup_state()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
@@ -75,5 +153,8 @@ if (!vv_write_conf_raw('master.conf', implode('', $newLines))) {
     exit;
 }
 
-vv_push_master_conf();
-echo json_encode(['ok' => true]);
+// Reported rather than discarded — a partner that did not receive the move is exactly the
+// state that makes one host run a script the other does not. Mirrors rawconf/confform.
+$push = vv_push_master_conf();
+vv_push_setup_state();
+echo json_encode(['ok' => true, 'push' => $push]);
diff --git a/Plugin/unraid/api/partnership.php b/Plugin/unraid/api/partnership.php
index af5c925..f99fef3 100644
--- a/Plugin/unraid/api/partnership.php
+++ b/Plugin/unraid/api/partnership.php
@@ -1,4 +1,40 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Partnership data endpoint. The whole partnership picture in one document — known hosts,
+//   reachability, SSH trust, conf-sync state and the shared-service inventory — for the
+//   partnership tab's poll.
+//
+// DESIGN PRINCIPLES
+//   Thin transport. Host enumeration, SSH probing and trust evaluation live in
+//   include/partnership.php; this file only sets the content type and encodes.
+//
+//   No parameters. The partnership is defined by conf, not by the request, so there is
+//   nothing for a caller to select and nothing to validate.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Nothing here installs a key, edits a conf, or changes a partner's state.
+//   Every mutating partnership operation is a separate endpoint (partnership_settings.php,
+//   setup.php) so that a page poll can never alter trust.
+//
+//   An unreachable partner is a reported condition, not a failure.
+//       vv_partnership_all() returns each host with its own reachability result, so a dark
+//       node renders as unreachable while the rest of the page stays accurate. The tab has to
+//       stay useful precisely when a partner is down.
+//
+//   Probes are time-boxed inside the library, so this endpoint cannot outlast them.
+//       vv_pt_ssh() runs with ConnectTimeout (4s default) and BatchMode=yes, so a partner
+//       that is powered off costs that timeout and can never sit waiting for a password.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   vv_partnership_all() verbatim — {"config":…,"nodes":…,"sync":…,"ts":epoch}
+//
+// DEPENDS ON
+//   include/partnership.php   vv_partnership_all()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/partnership.php';
 echo json_encode(vv_partnership_all());
diff --git a/Plugin/unraid/api/partnership_ping.php b/Plugin/unraid/api/partnership_ping.php
index adcb43f..c25d154 100644
--- a/Plugin/unraid/api/partnership_ping.php
+++ b/Plugin/unraid/api/partnership_ping.php
@@ -1,6 +1,52 @@
 <?php
-// Connectivity test — SSH echo to a partner host with round-trip latency.
-// GET ?id=HOST2  (GET avoids the bodyless-POST issue on this nginx setup).
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Partner connectivity test. Runs one SSH `echo ok` against a named host slot and reports
+//   success plus round-trip latency — the "Test" button on the partnership tab.
+//
+// OPERATIONAL MODEL
+//   Deliberately a GET, despite being an action. php -S and this nginx setup drop POST
+//   bodies on Unraid PHP 8.4, so a POST would arrive with no id at all. The operation is
+//   safe to repeat and changes nothing, which is what makes GET acceptable here rather than
+//   merely convenient.
+//
+// DESIGN PRINCIPLES
+//   Tests the real path, not a substitute for it.
+//       The probe is SSH over the Tailscale IP with the same key every partnership operation
+//       uses. An ICMP ping would answer a question nobody is asking — what matters is whether
+//       this host can actually drive the partner.
+//
+//   Distinguishes why it failed.
+//       vv_pt_ping() returns separate errors for an unknown slot, a missing key, and an
+//       unresolvable Tailscale name, because those need three different fixes.
+//
+// OPERATIONAL SAFEGUARDS
+//   The host id is pattern-matched before it is used.
+//       ^host\d+$ (case-insensitive) is enforced here, and the value is then only used as a
+//       conf-key lookup — it never reaches a path or a shell. The remote command is the fixed
+//       literal `echo ok`; nothing from the request composes it.
+//
+//   The probe is time-boxed at 8 seconds.
+//       vv_pt_ping() passes an explicit timeout to vv_pt_ssh(), which also sets BatchMode=yes
+//       so it can never sit waiting for a password. A powered-off partner costs 8s, not a
+//       stuck request.
+//
+//   Read-only on the partner. `echo ok` is the entire remote payload.
+//
+//   Never cached.
+//       Cache-Control: no-store, no-cache — a connectivity test served from cache is worse
+//       than no test, because it reports a partner reachable after it has gone dark.
+//
+// REQUEST
+//   GET ?id=host<n>   (case-insensitive; the slot name, not the hostname)
+//
+// RESPONSE
+//   {"ok":true,"ms":int,…}                on success
+//   {"ok":false,"error":string}           invalid id, no key, unresolvable, or no reply
+//
+// DEPENDS ON
+//   include/partnership.php   vv_pt_ping() → vv_pt_ssh(), vv_resolve_tailscale_ip()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 header('Cache-Control: no-store, no-cache');
 require_once dirname(__DIR__) . '/include/partnership.php';
diff --git a/Plugin/unraid/api/partnership_settings.php b/Plugin/unraid/api/partnership_settings.php
index e480084..29eb59f 100644
--- a/Plugin/unraid/api/partnership_settings.php
+++ b/Plugin/unraid/api/partnership_settings.php
@@ -1,8 +1,61 @@
 <?php
-// Partnership-related settings for this host — the Partnership section of each accessible conf.
-// HOST1 (owner): master.conf PARTNERSHIP + host1.conf Partnership. Other hosts: their own.
-// Uses vv_conf_all_groups() (handles master.conf's sandwiched major header) then filters
-// to partnership sections. Writes go through confform.php (which pushes master.conf to partners).
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Partnership settings reader. Returns the partnership-related field groups from every conf
+//   file this host is allowed to see, so the partnership tab can render them as a form.
+//
+// OPERATIONAL MODEL
+//   Read-only, and deliberately so. Saves from this form go to confform.php, which already
+//   knows how to write a field change and push master.conf to partners. Duplicating that here
+//   would mean two write paths for the same keys, and only one of them would push.
+//
+//   Which files are read is decided by the host, not the request. On HOST1 that is
+//   master.conf's PARTNERSHIP section plus host1.conf's; on any other host, its own conf
+//   alone — the same split sparse checkout enforces at git level.
+//
+// DESIGN PRINCIPLES
+//   Filters full group parsing rather than pattern-matching the file.
+//       vv_conf_all_groups() is used and then filtered by subsection, because it already
+//       handles master.conf's sandwiched major header — the structure a naive section grep
+//       gets wrong.
+//
+//   Matches the section name case-insensitively and by substring.
+//       stripos, not equality, because the section is spelled PARTNERSHIP in master.conf and
+//       Partnership in the host confs. Requiring an exact match would silently return one
+//       file's groups and not the other's.
+//
+//   Files with no partnership section are omitted entirely.
+//       The response lists only files that contributed, so the page renders one panel per
+//       real section rather than an empty panel per readable file.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. No parameters, no writes, nothing to validate — there is no input to this
+//   endpoint at all, which is what makes the file list unforgeable.
+//
+//   The file list comes from vv_get_conf_files(), the same allowlist every conf endpoint uses,
+//   so this cannot expose a partner's conf even though it enumerates rather than being told
+//   what to read.
+//
+//   Never cached.
+//       Cache-Control: no-store, no-cache — these are the values a user is actively editing,
+//       and a cached read would show them their own change reverting.
+//
+//   Credential fields are returned as they appear in the conf.
+//       The partnership sections carry SSH key paths and API keys, and this endpoint returns
+//       them for editing. That is the same exposure the raw conf editor has, over the same
+//       WebGUI session; see the CSRF note in README-unraid.md.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   {"ok":true,"files":[{"file":"<conf>","groups":[…]}, …]}
+//
+// DEPENDS ON
+//   include/confform.php   vv_conf_all_groups()
+//   include/config.php     vv_get_conf_files()
+//   api/confform.php       the write path for these same fields
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 header('Cache-Control: no-store, no-cache');
 require_once dirname(__DIR__) . '/include/confform.php';
diff --git a/Plugin/unraid/api/rawconf.php b/Plugin/unraid/api/rawconf.php
index 6bc3f62..44a11fc 100644
--- a/Plugin/unraid/api/rawconf.php
+++ b/Plugin/unraid/api/rawconf.php
@@ -1,5 +1,76 @@
 <?php
-// Raw conf read/write — respects per-host file visibility from vv_get_conf_files().
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Raw conf read and write. Serves the full text of one configuration file and saves it
+//   back, and — when the file is master.conf — distributes the result to every partner host.
+//
+// OPERATIONAL MODEL
+//   Read and write on one URL, split on method, sharing one allowlist. GET also returns the
+//   allowlist itself, so the editor can populate its file picker from the same authority that
+//   will later authorise the save. The two can therefore never disagree about what this host
+//   is permitted to edit.
+//
+//   master.conf is shared; host*.conf is not. A master.conf save is followed by a push to
+//   every partner, because a threshold or toggle that differs between hosts produces
+//   behaviour neither side expects. A host conf is local by definition and is never pushed.
+//
+// DESIGN PRINCIPLES
+//   The allowlist encodes sparse checkout.
+//       vv_get_conf_files() returns master.conf plus its own host conf on HOST1, and its own
+//       conf alone elsewhere. That is the same split git enforces at checkout — HOST2 has no
+//       host1.conf to read, and this endpoint will not name one either.
+//
+//   master.conf defaults on read, nothing defaults on write.
+//       GET with no file returns master.conf, because that is what the editor opens to. POST
+//       has no default: a save must name its target explicitly.
+//
+//   Push results travel with the response.
+//       Per-host outcomes are returned rather than logged, so the page can show that a partner
+//       did not receive the change instead of leaving the two hosts quietly divergent.
+//
+// OPERATIONAL SAFEGUARDS
+//   Exact allowlist membership with strict comparison, on both paths.
+//       in_array(..., true) against vv_get_conf_files() — not a pattern, not basename(). A
+//       filename that is not literally one of the permitted strings is rejected, which makes
+//       traversal and absolute paths unreachable rather than merely filtered. The redundant
+//       '..' check is kept as a second, explicit statement of intent.
+//
+//   The content is syntax-checked before it can replace a working file.
+//       Conf files are sourced by every script in the system, and master.conf is pushed from
+//       here to every partner — so a stray quote saved through this endpoint would not just
+//       break this host's orchestrators, watchdogs and fallback, it would distribute that
+//       break across the mesh. `bash -n` on a private temp copy is checked first, and a file
+//       that does not parse is refused with the previous version left untouched.
+//
+//   The temp copy is created with tempnam() and always removed, so a rejected save cannot
+//   leave a stray file beside the real conf for a script to source.
+//
+//   The real write is atomic.
+//       vv_write_conf_raw() writes .vv.tmp and rename()s, so a script sourcing the conf during
+//       the save reads either the old file or the new one, never a half-written one.
+//
+//   The push only happens after a confirmed write.
+//       Guarded on $written, so a failed save cannot distribute a stale or partly-written
+//       master.conf. The push is also a no-op on a host with no SSH key, which is what stops a
+//       partner from overwriting the owner's file.
+//
+//   Unknown methods are refused explicitly, so a PUT or DELETE cannot fall through the two
+//   handled blocks into an empty 200.
+//
+// REQUEST
+//   GET  ?file=<allowed conf name>          defaults to master.conf
+//   POST file=<allowed conf name>  content=<full file text>
+//
+// RESPONSE
+//   GET   {"ok":true,"content":"…","file":"…","allowed":["…"]}
+//   POST  {"ok":true,"push":[{"host","ok","ready","error"}, …]}
+//         push is empty for host confs and on hosts with no partners
+//   {"ok":false,"error":"Not allowed"|"Syntax error: …"|"Method not allowed"}
+//
+// DEPENDS ON
+//   include/config.php   vv_get_conf_files(), vv_read_conf_raw(), vv_write_conf_raw(),
+//                        vv_push_master_conf(), vv_push_setup_state()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
@@ -22,6 +93,25 @@ if ($_SERVER['REQUEST_METHOD'] === 'POST') {
         echo json_encode(['ok' => false, 'error' => 'Not allowed']);
         exit;
     }
+    // Every script sources these, and master.conf is pushed to every partner from here — a
+    // syntax error saved through this endpoint would propagate the outage across the mesh.
+    $check = tempnam(sys_get_temp_dir(), 'vvconf');
+    if ($check !== false) {
+        file_put_contents($check, $content);
+        $out = []; $rc = 0;
+        exec('bash -n ' . escapeshellarg($check) . ' 2>&1', $out, $rc);
+        @unlink($check);
+        if ($rc !== 0) {
+            $msg = implode(' ', array_filter(array_map('trim', $out)));
+            echo json_encode([
+                'ok'    => false,
+                'error' => 'Syntax error: ' . str_replace($check, $file, $msg ?: 'conf does not parse'),
+                'push'  => [],
+            ]);
+            exit;
+        }
+    }
+
     $written = vv_write_conf_raw($file, $content);
     $push    = [];
     if ($written && $file === 'master.conf') {
diff --git a/Plugin/unraid/api/readscript.php b/Plugin/unraid/api/readscript.php
index 93c4976..3bdd9cc 100644
--- a/Plugin/unraid/api/readscript.php
+++ b/Plugin/unraid/api/readscript.php
@@ -1,5 +1,61 @@
 <?php
-// Read-only endpoint: return full content of any script in SCRIPTS_DIR.
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Script and document reader. Returns the full text of one .sh or .md file inside
+//   SCRIPTS_DIR — the source view behind the scheduler page's script viewer and the docs tab.
+//
+// DESIGN PRINCIPLES
+//   Two extensions, one endpoint.
+//       Scripts and their READMEs are read the same way because they are read for the same
+//       reason — someone wants to see what a job actually does. Splitting them would mean two
+//       endpoints with identical validation.
+//
+//   Returns text, never renders it.
+//       Markdown arrives as source. Rendering is the browser's job, and doing it here would
+//       make this endpoint an HTML producer with an HTML producer's escaping problems.
+//
+//   Relative ids only.
+//       The id is a path relative to SCRIPTS_DIR, so the caller never learns or supplies the
+//       installation root. That is also what makes the same id valid in internal and appdata
+//       storage modes.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. There is no write counterpart in this file; edits go through movescript.php
+//   and import_script.php, which have their own validation.
+//
+//   Traversal is blocked before the path is composed.
+//       str_contains($id, '..') is checked explicitly, and the pattern
+//       ^[A-Za-z0-9_.\-/]+\.(sh|md)$ excludes null bytes, backslashes, spaces, and every
+//       shell metacharacter. The slash has to be permitted because ids are Category/name.sh,
+//       so the '..' check carries the traversal guarantee on its own rather than being
+//       implied by the character class.
+//
+//   The extension allowlist is the real access boundary.
+//       Only .sh and .md can be named at all, which is what keeps Configurations/*.conf —
+//       the files holding every credential in the system — outside this endpoint's reach. Any
+//       future extension added here has to be checked against that first.
+//
+//   A missing file is reported, not opened.
+//       file_exists() precedes file_get_contents(), so a bad id returns a named error rather
+//       than a PHP warning leaking the absolute path into the JSON body.
+//
+//   Known limit: symlinks inside SCRIPTS_DIR are followed.
+//       Containment is enforced on the id, not on the resolved path, so a symlink placed
+//       inside the tree pointing outside it would be read. Not tightened with a realpath
+//       check, because the plugin's own boot model installs SCRIPTS_DIR as a symlink and a
+//       naive containment test would break it. The tree is git-managed; a rogue symlink in it
+//       is a repo compromise, which is a larger problem than this endpoint.
+//
+// REQUEST
+//   GET ?id=<Category/name.sh|Category/README-name.md>
+//
+// RESPONSE
+//   {"ok":true,"content":"<full file text>"}
+//   {"ok":false,"error":"Invalid id"|"Not found"}
+//
+// DEPENDS ON
+//   include/config.php   SCRIPTS_DIR
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
diff --git a/Plugin/unraid/api/recent.php b/Plugin/unraid/api/recent.php
index 674909b..bf43e03 100644
--- a/Plugin/unraid/api/recent.php
+++ b/Plugin/unraid/api/recent.php
@@ -1,4 +1,57 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Recent run history. The last 24 finished job runs across every orchestrator and script,
+//   newest first, with status and duration — the activity feed on the scheduler page.
+//
+// OPERATIONAL MODEL
+//   There is no run database. Each job writes a .json stat file beside its log, and this
+//   endpoint reconstructs history by walking LOG_DIR recursively and sorting what it finds by
+//   start time. That keeps the stat file the single source of truth for a job's outcome —
+//   the same file status.php reads for live state — instead of maintaining a second record
+//   that could disagree with it.
+//
+// DESIGN PRINCIPLES
+//   Finished runs only.
+//       status === 'running' is skipped, because a run in progress has no duration and
+//       belongs to status.php's live indicators, not to history. The two endpoints partition
+//       the same files rather than overlapping.
+//
+//   Capped at 24 after sorting, not before.
+//       Every stat file is read and ranked before the slice, so the newest 24 are genuinely
+//       the newest — filesystem iteration order says nothing about run time.
+//
+//   Duration is derived, never stored.
+//       end - start is computed here, so a stat file that recorded a start but never got to
+//       write an end still yields a usable row rather than being discarded.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Nothing here deletes a stat file, truncates a log, or re-runs a job.
+//
+//   The whole walk is wrapped in a try/catch.
+//       RecursiveDirectoryIterator throws when LOG_DIR does not exist or a subdirectory is
+//       unreadable — on a fresh install that is the normal state, not an error. The catch
+//       yields an empty run list so the page renders "no runs yet" instead of a 500.
+//
+//   Every individual file read is independently suppressed and validated.
+//       @file_get_contents, @json_decode, then an is_array plus required-key check. A stat
+//       file caught mid-write, truncated, or left over from an older schema is skipped —
+//       one bad file cannot cost the other 23 rows.
+//
+//   Negative durations are clamped.
+//       max(0, end - start) — a stat file whose clock went backwards across an NTP step
+//       reports 0s rather than a negative duration the UI would have to special-case.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   {"ok":true,"runs":[{"id","label","status","start","dur"}, …]}   newest first, max 24
+//
+// DEPENDS ON
+//   include/config.php   LOG_DIR
+//   LOG_DIR/**/*.json    stat files written by run_job.sh
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
diff --git a/Plugin/unraid/api/reorderarray.php b/Plugin/unraid/api/reorderarray.php
index 7e0cd94..61f6af5 100644
--- a/Plugin/unraid/api/reorderarray.php
+++ b/Plugin/unraid/api/reorderarray.php
@@ -1,8 +1,85 @@
 <?php
-// Rewrite a *_SCRIPTS array in master.conf with a new script order.
-// POST: array_name (e.g. "DAILY_SCRIPTS"), scripts (JSON: [{"id":"rel/path.sh","enabled":true}, ...])
-// Preserves original entry lines (including inline flags/args) where possible.
-// Scripts absent from the new list are dropped; new scripts are added as fresh entries.
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Rewrites one *_SCRIPTS array in master.conf with a new order and a new enabled/disabled
+//   state per entry — the drag-to-reorder on the scheduler page's orchestrator view.
+//
+// OPERATIONAL MODEL
+//   Order is behaviour, not presentation. An orchestrator runs its array top to bottom, so
+//   moving an entry changes when that script runs relative to the others — which is why this
+//   writes to master.conf rather than to a UI preference.
+//
+//   The array block is located, its entries harvested, and the whole block replaced. Only the
+//   lines between the opening and closing parens are touched; everything else in master.conf
+//   is written back byte for byte, because the file is hand-maintained and full of comments
+//   and grouping no round trip through a parser would preserve.
+//
+//   Disabled entries stay in the file, commented. Enabled state is expressed by the presence
+//   or absence of a leading '# ', the same convention conf_toggle.php uses.
+//
+// DESIGN PRINCIPLES
+//   Original entry text is preserved, not regenerated.
+//       Entries are harvested from the existing block keyed by script path, and reused
+//       verbatim when the same path appears in the new order. That is what keeps inline flags
+//       and arguments — "Media/cleanup.sh --deep" — through a reorder. Only a script that was
+//       not previously in the array is written fresh, as a bare quoted path.
+//
+//   The opening and closing lines are preserved exactly.
+//       Both are carried over untouched rather than rebuilt, so a trailing comment on the
+//       array declaration survives.
+//
+//   Absent means removed.
+//       A script in the file but not in the submitted order is dropped from the array. The
+//       page always submits the complete list, so absence is an instruction, not an omission.
+//
+// OPERATIONAL SAFEGUARDS
+//   POST only, checked before any parameter is read.
+//
+//   The array name is pattern-matched and only ever used as a needle.
+//       ^[A-Z_]+_SCRIPTS$, then preg_quote()d and matched against existing lines. Nothing is
+//       opened or executed from it.
+//
+//   Every entry is validated, and an invalid one fails the request rather than being skipped.
+//       ^[A-Za-z0-9_.\-/]+\.sh$ with an explicit '..' check per entry. Skipping would be
+//       actively dangerous here: the array is rebuilt from the validated list alone, so a
+//       silently dropped entry is a script silently removed from its orchestrator. Validation
+//       completes before anything is written.
+//
+//   A missing array aborts before the write.
+//       Both the block start and end must be found, otherwise the endpoint returns a named
+//       error and writes nothing. Without that, a typo'd array name would splice a block into
+//       an undefined position.
+//
+//   master.conf is confirmed present and readable before either pass.
+//
+//   The write is atomic.
+//       vv_write_conf_raw() writes .vv.tmp and rename()s. Every script sources master.conf, so
+//       a truncated write here would be a system-wide outage rather than a lost reorder.
+//
+//   The push happens only after a confirmed write, and its result is returned — a partner
+//   that did not receive the new order runs these scripts in a different sequence.
+//
+//   Known limit: block detection counts parens textually.
+//       depth is tracked with substr_count over '(' and ')', which does not know about quotes
+//       or comments. An entry whose arguments contained an unbalanced paren would end the
+//       block early. No current entry does, and the alternative is a bash parser — but a
+//       future entry with a paren in its arguments would be the thing that broke this.
+//
+// REQUEST
+//   POST array_name=<NAME>_SCRIPTS
+//        scripts=<JSON array of {"id":"Category/name.sh","enabled":bool}>
+//
+// RESPONSE
+//   {"ok":true,"push":[{"host","ok","ready","error"}, …]}
+//   {"ok":false,"error":"POST only"|"Invalid array_name"|"Invalid scripts JSON"
+//                      |"Invalid script id: …"|"master.conf not found"
+//                      |"Could not read master.conf"|"Array … not found in master.conf"
+//                      |"Write failed"}
+//
+// DEPENDS ON
+//   include/config.php   CONF_DIR, vv_write_conf_raw(), vv_push_master_conf(),
+//                        vv_push_setup_state()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
@@ -24,12 +101,17 @@ if (!is_array($decoded)) {
     exit;
 }
 
-// Validate each entry
+// Validate every entry before anything is written. A rejected entry cannot be skipped here:
+// this endpoint rewrites the array from $order alone, so a silently dropped entry is a script
+// silently removed from its orchestrator.
 $order = [];
 foreach ($decoded as $item) {
     $id      = trim((string)($item['id']      ?? ''));
     $enabled = (bool)($item['enabled'] ?? true);
-    if (!$id || str_contains($id, '..') || !preg_match('/^[A-Za-z0-9_.\-\/]+\.sh$/', $id)) continue;
+    if (!$id || str_contains($id, '..') || !preg_match('/^[A-Za-z0-9_.\-\/]+\.sh$/', $id)) {
+        echo json_encode(['ok' => false, 'error' => 'Invalid script id: ' . $id]);
+        exit;
+    }
     $order[] = ['id' => $id, 'enabled' => $enabled];
 }
 
@@ -106,5 +188,8 @@ if (!vv_write_conf_raw('master.conf', implode('', $lines))) {
     exit;
 }
 
-vv_push_master_conf();
-echo json_encode(['ok' => true]);
+// Reported rather than discarded — a partner that did not receive the new order is a partner
+// running these scripts in a different sequence. Mirrors rawconf/confform/movescript.
+$push = vv_push_master_conf();
+vv_push_setup_state();
+echo json_encode(['ok' => true, 'push' => $push]);
diff --git a/Plugin/unraid/api/rsync.php b/Plugin/unraid/api/rsync.php
index 206a5e7..34f94e6 100644
--- a/Plugin/unraid/api/rsync.php
+++ b/Plugin/unraid/api/rsync.php
@@ -1,4 +1,90 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Rsync tab data. Tier enablement, the currently running sync, last-run results, 30 days of
+//   bandwidth history, the per-window script and share lists, and the tuning settings — plus
+//   a separate action serving the live sync log.
+//
+// OPERATIONAL MODEL
+//   Two responses on one URL. The default is the tab's full state. ?action=rsync_log is the
+//   log viewer, split out because it polls far faster than the rest and returns a payload
+//   nothing else needs.
+//
+//   The log action has two sources and prefers the live one. An active sync is identified by
+//   a lock file whose pid is still in /proc, and its in-progress log is read directly. With
+//   no active sync, the most recently modified .last.log is served instead — so the panel
+//   shows the run that is happening, or failing that the run that just happened, without the
+//   caller having to know which.
+//
+//   Window definitions are a table, not a set of branches. Each tier names the master.conf
+//   script array and the host.conf shares array it draws from, so adding a tier is a row.
+//   monthly is deliberately half-populated — monthly_maintenance.sh does ZFS scrub and SMART
+//   tests and has no rsync section, so no shares variable exists for it. fallback has neither:
+//   it is driven entirely by fallback.sh.
+//
+// DESIGN PRINCIPLES
+//   Liveness is proven by the process table, not by the lock file's existence.
+//       A lock whose pid is gone is a crashed run, and treating it as active would show a
+//       stale log as a sync in progress forever.
+//
+//   Toggles default to on when the key is absent.
+//       !== 'false' rather than === 'true', so a conf that predates a flag behaves as it did
+//       before the flag existed. That is the correct default for a tier that was previously
+//       unconditional.
+//
+//   History is filtered by date, not by line count.
+//       The bandwidth log is append-only and unbounded; a 30-day cutoff keeps the response
+//       proportional to the window the page renders rather than to the file's age.
+//
+//   Elapsed time comes from the lock's mtime.
+//       The lock is touched when the run starts, so its age is the run's age without the
+//       script having to report progress.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Nothing here starts, stops, or reconfigures a sync — this endpoint reports on
+//   rsync.sh, and the interlocks that make a sync safe live there. In particular, the
+//   --merge-run / --delete ordering is rsync.sh's to enforce; nothing in this payload implies
+//   it has been satisfied.
+//
+//   The lock and log scan is bounded to a hardcoded directory.
+//       glob over /tmp/unraid_locks — a literal, not a config value.
+//
+//   Every read degrades to empty.
+//       @file_get_contents, file() with ?: [] fallbacks, and file_exists() before each read.
+//       A lock caught mid-write or a log removed between the glob and the read yields an empty
+//       line list rather than a fatal.
+//
+//   Malformed history lines are skipped, not repaired.
+//       A count check before the fields are used, and an isset() on the optional bytes column,
+//       so a truncated or older-format row is dropped instead of producing a row of nulls.
+//
+//   Output is bounded and stripped.
+//       Last 200 lines, with ANSI escapes removed. rsync logs are long and coloured, and the
+//       escapes would otherwise reach the page as control codes.
+//
+//   Every setting has a default.
+//       ?? on all four tuning values and on the bandwidth warning threshold, so a conf missing
+//       a key renders a usable panel rather than zeros that read as "no limit configured".
+//
+//   The profile name is derived from the lock's own contents, with the filename as fallback,
+//   so a lock written by an older format still identifies its run.
+//
+// REQUEST
+//   GET                      full rsync tab state
+//   GET ?action=rsync_log    live sync log, or the most recent completed one
+//
+// RESPONSE
+//   default  {"enabled","windows","active","last_sync","bw_history":[…],"bw_warn_gb",
+//             "win_arrays":{<window>:{"scripts":[…],"shares":[…]}},"settings":{…},"ts"}
+//   log      {"ok":true,"live":bool,"profile","elapsed","lines":[…]}
+//
+// DEPENDS ON
+//   include/monitor.php   vv_rsync_status()
+//   include/config.php    vv_conf_vars(), vv_read_conf_raw(), vv_detect_host(),
+//                         vv_parse_bash_array(), DATA_DIR
+//   /tmp/unraid_locks     rsync_*.lock, rsync_*.log, rsync_*.last.log — written by rsync.sh
+//   DATA_DIR              bandwidth_history.db
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 require_once dirname(__DIR__) . '/include/monitor.php';
diff --git a/Plugin/unraid/api/rsync_profiles.php b/Plugin/unraid/api/rsync_profiles.php
index 7616a5c..77ba589 100644
--- a/Plugin/unraid/api/rsync_profiles.php
+++ b/Plugin/unraid/api/rsync_profiles.php
@@ -1,4 +1,85 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Rsync profile CRUD. Lists, creates, updates and deletes the named transfer profiles that
+//   control how a given share is synced — rsync options, bandwidth cap, retry behaviour,
+//   container stop/start lists and exclusions.
+//
+// OPERATIONAL MODEL
+//   A profile is not stored as a record. It is one key spread across nine parallel
+//   `declare -A PROFILE_*` associative arrays in master.conf — PROFILE_RSYNC_OPTS[name],
+//   PROFILE_BW_LIMIT[name], and so on. That layout exists because the shell layer reads each
+//   setting independently, and this endpoint's whole job is to present it as a record anyway:
+//   read all nine, pivot by profile name, and on save write the same key back into each.
+//
+//   Every write therefore touches nine array declarations at once, submitted as a single
+//   change set so they land together. A profile that existed in some arrays and not others
+//   would read back with silently missing settings.
+//
+// DESIGN PRINCIPLES
+//   Create and update are the same operation.
+//       Save sets the named key in every array whether or not it was already there. There is
+//       no separate create path, and therefore no way for the two to diverge on what a
+//       complete profile looks like.
+//
+//   Delete only touches arrays that actually contain the profile.
+//       array_key_exists() is checked per array, and an empty change set is reported as
+//       "Profile not found" rather than as a successful no-op.
+//
+//   Values are quoted only when they need to be.
+//       _rp_build_assoc() emits a bare value unless it is empty or contains whitespace or a
+//       shell metacharacter. That keeps master.conf readable by hand, which is the reason the
+//       whole config layer is bash rather than JSON.
+//
+//   Missing arrays are skipped, not created.
+//       A PROFILE_* declaration absent from master.conf is passed over. This endpoint edits
+//       the schema that exists; adding a new setting is a conf template change, not a runtime
+//       one.
+//
+// OPERATIONAL SAFEGUARDS
+//   The profile name is constrained to characters that cannot break the array.
+//       ^[a-zA-Z0-9_\-]+$ on both save and delete — no spaces, quotes, brackets or shell
+//       metacharacters. The name becomes an associative-array subscript, so anything outside
+//       that set could terminate the key or the declaration.
+//
+//   Values are escaped on the way in, and the result is parsed before it lands.
+//       Embedded quotes are backslash-escaped by _rp_build_assoc(), and
+//       vv_conf_write_changes() then runs `bash -n` over the rewritten file. The escaping
+//       handles the expected case; the syntax gate is what catches the unexpected one — and
+//       it matters here because assoc_array values are spliced in verbatim rather than
+//       through the scalar path's escaping.
+//
+//   Writes go through the shared conf writer, so they are atomic — tmp + rename — and a
+//   script sourcing master.conf mid-save sees the old file or the new one.
+//
+//   The push happens only after every array write succeeded.
+//       Guarded on the combined result, so a partially failed change set is not distributed
+//       to partners. Profiles are shared configuration; a partner holding a different
+//       definition of a profile would sync the same share differently.
+//
+//   Save and delete are POST-only; only list is reachable by GET.
+//
+//   Unknown actions fall through to an explicit error rather than an empty 200.
+//
+// REQUEST
+//   GET|POST ?action=list      all profiles, pivoted into records
+//   POST action=save    name=<profile>  rsync_opts, bw_limit, retry_count, sleep,
+//                       critical_containers, delayed_containers, container_delay,
+//                       exclude_dirs, remote_restart   (all optional, default empty)
+//   POST action=delete  name=<profile>
+//
+// RESPONSE
+//   list    {"ok":true,"profiles":{"<name>":{"<field>":"<value>", …}, …}}
+//   save    {"ok":bool,"results":{"master.conf":bool}}
+//   delete  {"ok":bool}
+//   {"ok":false,"error":"Invalid profile name — …"|"No profile arrays found in master.conf"
+//                      |"Profile not found"|"Unknown action"}
+//
+// DEPENDS ON
+//   include/confform.php   vv_conf_write_changes()
+//   include/config.php     vv_read_conf_raw(), vv_push_master_conf(), vv_push_setup_state()
+//   Rsync/rsync.sh         consumer of every PROFILE_* array this writes
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 header('Cache-Control: no-store, no-cache');
 require_once dirname(__DIR__) . '/include/config.php';
diff --git a/Plugin/unraid/api/rsync_standalone.php b/Plugin/unraid/api/rsync_standalone.php
index 1338b2e..3a8936d 100644
--- a/Plugin/unraid/api/rsync_standalone.php
+++ b/Plugin/unraid/api/rsync_standalone.php
@@ -1,8 +1,76 @@
 <?php
-// Save rsync standalone config (location + cron) for a specific rsync tier.
-// POST: flag_name (e.g. "DAILY_RSYNC_ENABLED"), orch_id, location, cron
-// Stored in schedule.json under "__rsync_{FLAG_NAME}".
-// Triggers a cron rebuild so the standalone entry takes effect immediately.
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Standalone rsync scheduling. Records a location and cron expression for one rsync tier so
+//   that tier can run on its own schedule when its orchestrator is disabled.
+//
+// OPERATIONAL MODEL
+//   Rsync normally runs as a step inside an orchestrator — critical, intermediate, daily,
+//   weekly. This exists for the case where someone wants that tier's sync without the rest of
+//   the orchestrator's work. vv_cron_rebuild() emits the standalone entry only when the
+//   orchestrator is disabled and both a location and a cron are configured, so the two can
+//   never both fire: enabling the orchestrator silently takes precedence.
+//
+//   Stored in schedule.json under __rsync_<FLAG_NAME>, a namespace deliberately outside the
+//   job id space. Everything that iterates the schedule as jobs skips keys with that prefix.
+//
+//   The cron is rebuilt immediately on save, so the change takes effect without waiting for
+//   another event to regenerate varaverk.cron.
+//
+// DESIGN PRINCIPLES
+//   Keyed by flag, not by orchestrator.
+//       The tier flag is the stable identity — CRITICAL_RSYNC_ENABLED means the same thing
+//       regardless of which orchestrator currently carries that tier. orch_id is stored
+//       alongside it purely so the rebuild can check whether that orchestrator is enabled.
+//
+//   Configuration only. Nothing here starts a sync; it records when one should start.
+//
+//   Empty fields are permitted and mean "not configured".
+//       location and cron may both be blank, which is how a standalone entry is cleared —
+//       vv_cron_rebuild() requires both to be present before it emits anything.
+//
+// OPERATIONAL SAFEGUARDS
+//   POST only, checked before any parameter is read.
+//
+//   The flag name is constrained to the rsync namespace.
+//       ^[A-Z_]+_RSYNC_ENABLED$ — this endpoint cannot create a schedule key for anything
+//       else, so the __rsync_ namespace stays exactly as wide as the tiers it was built for.
+//
+//   The cron expression is validated as a crontab injection surface.
+//       vv_cron_rebuild() interpolates it directly into a generated crontab line. Only
+//       [0-9A-Za-z*,\-/ ] is permitted, and then five whitespace-separated fields are
+//       required. The character class is what carries the guarantee: the field-count pattern
+//       uses \s, which matches newline, so on its own it would accept a value carrying a
+//       second, caller-chosen crontab entry. It was previously not validated at all.
+//
+//   The orchestrator id is validated even though it is only ever used as a lookup key.
+//       ^[A-Za-z0-9_.\-/]+\.sh$ with an explicit '..' check, so a value that could not name a
+//       real script cannot be stored as though it does.
+//
+//   The location must be absolute and clean.
+//       Leading slash required, '..' rejected, control characters rejected. It reaches the
+//       crontab as an escapeshellarg'd --location= token, so validation and escaping are both
+//       in place.
+//
+//   The rest of the schedule is preserved — the file is loaded, one key replaced, and the
+//   whole structure written back.
+//
+//   The cron rebuild only runs after a confirmed write, so a failed save cannot regenerate
+//   the crontab from a schedule that was not persisted.
+//
+// REQUEST
+//   POST flag_name=<TIER>_RSYNC_ENABLED  orch_id=<Category/name.sh>
+//        location=/absolute/path         cron=<5 fields>
+//
+// RESPONSE
+//   {"ok":true}
+//   {"ok":false,"error":"POST only"|"Invalid flag_name"|"Invalid orch_id"|"Invalid location"
+//                      |"Invalid cron expression"|"Write failed"}
+//
+// DEPENDS ON
+//   include/scheduler.php   vv_schedule_load(), vv_schedule_save(), vv_cron_rebuild()
+//   Rsync/rsync.sh          the script the generated cron entry invokes
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 require_once dirname(__DIR__) . '/include/scheduler.php';
@@ -29,6 +97,13 @@ if ($location && (!str_starts_with($location, '/') || str_contains($location, '.
     echo json_encode(['ok' => false, 'error' => 'Invalid location']);
     exit;
 }
+// vv_cron_rebuild() interpolates this straight into a crontab line. Restrict to cron-safe
+// characters first — a field-count check alone would accept a value carrying a newline and
+// therefore a second, caller-chosen crontab entry.
+if ($cron && (!preg_match('/^[0-9A-Za-z*,\-\/ ]+$/', $cron) || !preg_match('/^(\S+ +){4}\S+$/', $cron))) {
+    echo json_encode(['ok' => false, 'error' => 'Invalid cron expression']);
+    exit;
+}
 
 $key      = '__rsync_' . $flagName;
 $schedule = vv_schedule_load();
diff --git a/Plugin/unraid/api/rsync_win_arrays.php b/Plugin/unraid/api/rsync_win_arrays.php
index ecd9138..54c0a9a 100644
--- a/Plugin/unraid/api/rsync_win_arrays.php
+++ b/Plugin/unraid/api/rsync_win_arrays.php
@@ -1,4 +1,102 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Sync window editor. Lists the available scripts and rsync profiles, and saves which
+//   scripts and which shares belong to one maintenance window — critical, intermediate, daily
+//   or weekly.
+//
+// OPERATIONAL MODEL
+//   One save writes to two files, because a window is defined in two places. The script list
+//   is a *_MAINTENANCE_SCRIPTS array in master.conf, shared across the partnership; the share
+//   list is a <HOST>_*_SYNC_SHARES array in this host's own conf, because what a host syncs
+//   is local to it. The three-file model puts them there, and this endpoint respects that
+//   split rather than flattening it.
+//
+//   The two halves are written independently and their failures reported separately. A shares
+//   write that fails does not roll back a successful scripts write — they are different files
+//   with different consumers, and a partial success is more useful than an all-or-nothing
+//   that leaves both stale.
+//
+//   Scripts are edited by block surgery, shares by the structured conf writer. The script
+//   array carries inline arguments and comment-disabled entries that must survive a round
+//   trip; the shares array is a flat list this endpoint fully owns.
+//
+// DESIGN PRINCIPLES
+//   The window name is a key into a fixed map, never a composed variable.
+//       Four windows, each naming its two conf variables. An unrecognised window is rejected
+//       before anything is read, so no part of the request can name a conf variable directly.
+//
+//   The script library excludes what cannot be scheduled here.
+//       Plugin, .git, Orchestrators, Custom, Configurations, Deployment, State_Files, data and
+//       the archive folders are filtered out, and root-level scripts are excluded by requiring
+//       at least one directory component. Orchestrators are excluded specifically because
+//       putting one inside another window's array is how a run becomes recursive.
+//
+//   Original entry lines are preserved through a save.
+//       Existing entries are harvested keyed by script path and reused verbatim, so inline
+//       flags survive. Only a newly added script is written as a bare quoted path.
+//
+//   Disabled entries stay in the file, commented — the same convention conf_toggle.php and
+//   reorderarray.php use.
+//
+//   A share's profile is optional and encoded inline as path|profile, matching what rsync.sh
+//   parses. No profile means the default.
+//
+// OPERATIONAL SAFEGUARDS
+//   Every script id is validated, and an invalid one fails the request rather than being
+//   skipped.
+//       The block is regenerated from the submitted list alone, so a silently dropped entry is
+//       a script silently removed from its window. Validation completes before the block is
+//       rebuilt.
+//
+//   Share paths must be absolute with no traversal, and profile names are constrained.
+//       ^[A-Za-z0-9_\-]+$ on the profile, because it is spliced into a quoted conf array
+//       element where a quote would terminate the string and a paren would close the array.
+//
+//   A missing script array aborts that half of the save.
+//       Both block boundaries must be found, otherwise an error is recorded and nothing is
+//       written — without it, a splice would land at an undefined position.
+//
+//   Both writes are atomic.
+//       The scripts half goes through vv_write_conf_raw() (tmp + rename) and the shares half
+//       through vv_conf_write_changes(), which does the same. Every script sources master.conf;
+//       a truncated write here would be a system-wide outage rather than a lost edit.
+//
+//   The shares write is syntax-checked before it lands.
+//       vv_conf_write_changes() runs `bash -n` on the result, so a share path that would not
+//       parse is reported as a failed write with the original conf intact.
+//
+//   master.conf is pushed to partners after a confirmed write.
+//       It is a shared file; leaving one host's window definition ahead of the other's is what
+//       makes the two run different work. Mirrors reorderarray, movescript and rawconf.
+//
+//   The script scan is wrapped in a try/catch, so an unreadable subdirectory yields a partial
+//   library rather than a 500.
+//
+//   Known limit: block detection counts parens textually.
+//       depth is tracked with substr_count, which does not know about quotes or comments. An
+//       entry whose arguments contained an unbalanced paren would end the block early. No
+//       current entry does — but a future one would be the thing that broke this.
+//
+// REQUEST
+//   GET|POST ?action=list_scripts     .sh files grouped by folder, schedulable ones only
+//   GET|POST ?action=list_profiles    rsync profile names declared in master.conf
+//   POST action=save  win_key=critical|intermediate|daily|weekly
+//        scripts=<JSON [{"id","enabled"}]>   shares=<JSON [{"path","profile"}]>
+//        Either list may be omitted; only the ones supplied are written.
+//
+// RESPONSE
+//   list_scripts   {"ok":true,"groups":{"<folder>":[{"id","label"}, …]}}
+//   list_profiles  {"ok":true,"profiles":["…"]}
+//   save           {"ok":bool,"errors":[…]}
+//   {"ok":false,"error":"Invalid window"|"Invalid script id: …"|"Unknown action"}
+//
+// DEPENDS ON
+//   include/config.php     SCRIPTS_DIR, CONF_DIR, vv_detect_host(), vv_read_conf_raw(),
+//                          vv_write_conf_raw(), vv_push_master_conf(), vv_push_setup_state()
+//   include/confform.php   vv_conf_write_changes()
+//   Rsync/rsync.sh         consumer of the shares arrays this writes
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 require_once dirname(__DIR__) . '/include/confform.php';
@@ -89,18 +187,41 @@ if ($action === 'save' && $_SERVER['REQUEST_METHOD'] === 'POST') {
         }
 
         if ($blockStart !== null && $blockEnd !== null) {
+            // Validate the whole list before rebuilding. The block is regenerated from this
+            // loop alone, so skipping an invalid entry would silently drop that script from
+            // the orchestrator rather than reporting a bad request.
+            $bad = null;
+            foreach ($scripts as $item) {
+                $id = trim((string)($item['id'] ?? ''));
+                if (!$id || str_contains($id, '..') || !preg_match('/^[A-Za-z0-9_.\-\/]+\.sh$/', $id)) {
+                    $bad = $id;
+                    break;
+                }
+            }
+            if ($bad !== null) {
+                echo json_encode(['ok' => false, 'error' => 'Invalid script id: ' . $bad]);
+                exit;
+            }
+
             $newBlock = [$lines[$blockStart]];
             foreach ($scripts as $item) {
-                $id      = trim((string)($item['id'] ?? ''));
-                $enabled = !isset($item['enabled']) || (bool)$item['enabled'];
-                if (!$id || str_contains($id, '..') || !preg_match('/^[A-Za-z0-9_.\-\/]+\.sh$/', $id)) continue;
+                $id         = trim((string)$item['id']);
+                $enabled    = !isset($item['enabled']) || (bool)$item['enabled'];
                 $entry      = $origLines[$id] ?? '"' . $id . '"';
                 $prefix     = $enabled ? '        ' : '        #';
                 $newBlock[] = $prefix . $entry . "\n";
             }
             $newBlock[] = $lines[$blockEnd];
             array_splice($lines, $blockStart, $blockEnd - $blockStart + 1, $newBlock);
-            if (file_put_contents($confPath, implode('', $lines)) === false) $errors[] = 'scripts write failed';
+            // tmp+rename — every script sources master.conf, so a truncated write here is a
+            // system-wide outage, not a lost edit.
+            if (!vv_write_conf_raw('master.conf', implode('', $lines))) {
+                $errors[] = 'scripts write failed';
+            } else {
+                // master.conf is shared — mirrors reorderarray/movescript/rawconf.
+                vv_push_master_conf();
+                vv_push_setup_state();
+            }
         } else {
             $errors[] = "Array $scriptsVar not found in master.conf";
         }
@@ -114,6 +235,9 @@ if ($action === 'save' && $_SERVER['REQUEST_METHOD'] === 'POST') {
             $path    = trim((string)($item['path']    ?? ''));
             $profile = trim((string)($item['profile'] ?? ''));
             if (!$path || str_contains($path, '..') || !str_starts_with($path, '/')) continue;
+            // The profile name is spliced into a quoted conf array element; anything outside
+            // this set could terminate the string or the array.
+            if ($profile !== '' && !preg_match('/^[A-Za-z0-9_\-]+$/', $profile)) continue;
             $val    = $profile ? "{$path}|{$profile}" : $path;
             $inner .= '        "' . $val . '"' . "\n";
         }
diff --git a/Plugin/unraid/api/run.php b/Plugin/unraid/api/run.php
index d2025da..a0d898d 100644
--- a/Plugin/unraid/api/run.php
+++ b/Plugin/unraid/api/run.php
@@ -1,4 +1,72 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Manual job launcher. Starts one script through run_job.sh, marked --manual, from the
+//   scheduler page's run button.
+//
+// OPERATIONAL MODEL
+//   Fire and forget. The child is nohup'd, detached from the request, and its output appended
+//   to the job's own log. ok:true means "launched", not "succeeded" — the outcome arrives in
+//   the stat file, and the page follows it through status.php and log.php.
+//
+//   A manual run is the same run the cron would do. Same runner, same flags, same log, same
+//   lock — only --manual differs, so that the stat file records who started it.
+//
+// DESIGN PRINCIPLES
+//   Never executes the target script directly.
+//       run_job.sh is the single execution path, so locking, logging, the stat file and exit
+//       handling are identical whether a job was started by cron or by a person. A second
+//       path would be a second set of bugs, and they would only show up under manual runs.
+//
+//   Refuses a concurrent run, rather than relying on the script's own lock.
+//       The scripts do lock and would exit on their own, but they would do it silently in a
+//       log nobody has open yet. Checking here turns that into an immediate, visible
+//       "Already running" with an already_running flag the UI can act on.
+//
+// OPERATIONAL SAFEGUARDS
+//   The job id is validated and then confirmed to exist.
+//       ^[a-zA-Z0-9_./\-]+\.sh$ plus an explicit '..' check — the slash must be permitted for
+//       Category/name.sh ids, so traversal is caught by its own test rather than by the
+//       character class. file_exists() then confirms the resolved path is a real script.
+//
+//   The running check is cross-checked against the process table.
+//       A stat file saying 'running' is only believed while /proc/<pid> exists. Without that,
+//       a job whose runner was OOM-killed — the exact case where someone is trying to start
+//       it again — would be permanently unstartable from the UI.
+//
+//   The location argument must be absolute and clean.
+//       Leading slash required, '..' rejected, control characters rejected — then passed as a
+//       single escapeshellarg'd --location= token.
+//
+//   Extra arguments cannot become shell syntax.
+//       Control characters are rejected, then the string is split on whitespace and each
+//       token escaped individually. The previous blocklist of metacharacters missed newlines,
+//       which would have terminated the command line and started a second one — a blocklist
+//       has to be right about every character, whereas escaping each token is right about all
+//       of them.
+//
+//   Every interpolated value is escaped, including the ones that are already validated.
+//       Runner path, id, script path and log path all go through escapeshellarg(). Validation
+//       and escaping guard different things, and the escaping is what stays correct if the
+//       validation is ever loosened.
+//
+//   Output is appended, never truncated.
+//       >> to the job's own log with stdin from /dev/null, so a manual run cannot consume the
+//       request's stdin or discard the history of previous runs.
+//
+// REQUEST
+//   POST id=<Category/name.sh>  [location=/absolute/path]  [extra_args=…]
+//
+// RESPONSE
+//   {"ok":true}                                          launched — not completed
+//   {"ok":false,"already_running":true,"error":"Already running"}
+//   {"ok":false,"error":"Invalid id"|"Script not found: …"|"Invalid location"
+//                      |"Invalid extra_args"}
+//
+// DEPENDS ON
+//   include/scheduler.php   vv_job_log_path(), vv_job_stat_path(), vv_job_flags()
+//   run_job.sh              the single execution path for every job
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/scheduler.php';
 
@@ -25,8 +93,11 @@ if ($location && (!str_starts_with($location, '/') || str_contains($location, '.
     exit;
 }
 
+// Control characters are rejected outright — a newline would end the command line and start
+// a second one. Everything that survives is split on whitespace and escaped per token below,
+// so the shell never parses any of it as syntax.
 $extra_args = trim($_POST['extra_args'] ?? '');
-if ($extra_args && preg_match('/[;&|`$<>\\\\"\']/', $extra_args)) {
+if ($extra_args !== '' && preg_match('/[\x00-\x1f\x7f]/', $extra_args)) {
     echo json_encode(['ok' => false, 'error' => 'Invalid extra_args']);
     exit;
 }
@@ -46,7 +117,10 @@ if (file_exists($statFile)) {
 $runner   = dirname(__DIR__) . '/run_job.sh';
 $flags    = vv_job_flags($id);
 $locArg   = $location   ? ' ' . escapeshellarg('--location=' . $location) : '';
-$extraStr = $extra_args ? ' ' . $extra_args : '';
+$extraStr = '';
+foreach (preg_split('/\s+/', $extra_args, -1, PREG_SPLIT_NO_EMPTY) as $tok) {
+    $extraStr .= ' ' . escapeshellarg($tok);
+}
 exec('nohup bash ' . escapeshellarg($runner) . ' ' . escapeshellarg($id) . ' ' . escapeshellarg($script) . ($flags ? " $flags" : '') . ' --manual' . $locArg . $extraStr . ' >> ' . escapeshellarg($logFile) . ' 2>&1 </dev/null &');
 
 echo json_encode(['ok' => true]);
diff --git a/Plugin/unraid/api/savefolders.php b/Plugin/unraid/api/savefolders.php
index 7481b00..ad89e6c 100644
--- a/Plugin/unraid/api/savefolders.php
+++ b/Plugin/unraid/api/savefolders.php
@@ -1,6 +1,64 @@
 <?php
-// Save custom-script folder assignments to schedule.json (__folders key).
-// POST: folders (JSON-encoded object: {"FolderName": ["Custom/script.sh", ...]})
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Script folder assignments. Saves the grouping of scripts into named folders on the
+//   scheduler page, stored in schedule.json under the __folders key.
+//
+// OPERATIONAL MODEL
+//   Whole-map replacement, not a patch. The page sends the complete folder structure and it
+//   replaces __folders entirely, so a removed folder disappears by absence. Reconciling
+//   individual moves would need a change log the UI does not have and cannot produce from a
+//   drag.
+//
+//   Stored alongside the schedule rather than in a file of its own, under a key prefixed with
+//   __ to keep it out of the job namespace — the same convention __rsync_* uses. Everything
+//   that iterates the schedule as jobs skips these keys by prefix.
+//
+// DESIGN PRINCIPLES
+//   Presentation only. Folder membership changes nothing about whether or when a script runs;
+//   vv_cron_rebuild() never reads __folders, which is why this endpoint does not trigger one.
+//
+//   Invalid entries are dropped, not rejected.
+//       A bad folder name or an unrecognised script id is skipped and the rest of the map is
+//       saved. Failing the whole request would lose a full reorganisation over one stale
+//       entry — and the entries most likely to be stale are scripts deleted since the page
+//       loaded.
+//
+// OPERATIONAL SAFEGUARDS
+//   POST only, checked before the payload is read.
+//
+//   The payload must decode to an array.
+//       is_array() on the decoded JSON — a truncated or non-JSON body is refused outright
+//       rather than writing an empty map, which would silently erase every folder.
+//
+//   Every script id is validated exactly as the run paths validate it.
+//       ^[A-Za-z0-9_.\-/]+\.sh$ with an explicit '..' check, applied per entry. These ids are
+//       stored and later handed back to the page as job references, so a value that could not
+//       be run has no business being persisted next to ones that can.
+//
+//   Folder names are length-capped and type-coerced.
+//       Cast to string, trimmed, empty rejected, and capped at 80 characters — a JSON object
+//       with numeric or absurdly long keys cannot bloat schedule.json, which is read on every
+//       scheduler page load and every cron rebuild.
+//
+//   Non-array folder contents are skipped.
+//       is_array() per folder before iterating, so a malformed value cannot raise a warning
+//       into the JSON response.
+//
+//   The rest of the schedule is preserved.
+//       The file is loaded, one key replaced, and the whole structure written back — job
+//       entries and __rsync_* keys are carried through untouched.
+//
+// REQUEST
+//   POST folders=<JSON object: {"<folder name>": ["Category/script.sh", …], …}>
+//
+// RESPONSE
+//   {"ok":true}
+//   {"ok":false,"error":"POST only"|"Invalid JSON"|"Write failed"}
+//
+// DEPENDS ON
+//   include/scheduler.php   vv_schedule_load(), vv_schedule_save()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 require_once dirname(__DIR__) . '/include/scheduler.php';
diff --git a/Plugin/unraid/api/scheduler.php b/Plugin/unraid/api/scheduler.php
index 34312b7..9b212b6 100644
--- a/Plugin/unraid/api/scheduler.php
+++ b/Plugin/unraid/api/scheduler.php
@@ -1,4 +1,77 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Schedule writer. Saves one job's enabled state, cron expression and log flag — or a whole
+//   set of them in one call — and rebuilds varaverk.cron from the result.
+//
+// OPERATIONAL MODEL
+//   schedule.json is the source of truth; varaverk.cron is generated from it. Nothing edits
+//   the crontab directly, which is why the generated file carries a "managed by plugin, do
+//   not edit manually" banner. Every save here ends in a vv_cron_rebuild() inside the library,
+//   so the two can never drift.
+//
+//   Two paths, same effect. The single-entry path is what the UI's toggles use; the batch
+//   path exists so a bulk edit is one load/write/rebuild cycle rather than N of them. The
+//   batch path is currently unreferenced by the UI.
+//
+//   The two paths differ in how they treat a bad cron, deliberately. A single save rejects it
+//   and tells the user; a batch save blanks that one field and continues, because failing an
+//   entire bulk edit over one malformed row would lose every other change in it.
+//
+// DESIGN PRINCIPLES
+//   Event triggers are stored here but never reach cron.
+//       array_start and array_stop are accepted as cron values and recorded in schedule.json,
+//       but vv_cron_rebuild() skips them — they fire from the array event hook instead. One
+//       schedule holds both kinds of trigger so the page has a single list to render.
+//
+//   Enablement is decided here, precedence in the library.
+//       A child script whose orchestrator is enabled gets no independent cron line, and that
+//       suppression lives in vv_cron_rebuild(). This endpoint records intent; the library
+//       resolves what that intent means against the rest of the schedule.
+//
+// OPERATIONAL SAFEGUARDS
+//   The job id and the cron expression are both crontab injection surfaces, and are validated
+//   as such.
+//       vv_cron_rebuild() interpolates both into a generated crontab line inside double
+//       quotes. The id must match ^[A-Za-z0-9_./\-]+\.sh$ with no '..', and the cron
+//       expression must consist only of [0-9A-Za-z*,\-/ ] — neither can carry a quote, a
+//       shell metacharacter, or a newline. Previously the id was checked only for emptiness,
+//       and the field-count pattern used \s, which matches newline: a value of "* * * *\nX"
+//       satisfied it and would have appended a second, attacker-chosen line to root's crontab.
+//       The character-class check is what carries that guarantee now; the field count is a
+//       usability check on top of it.
+//
+//   Both paths share one validator.
+//       vv_sched_id_valid() and vv_sched_cron_valid() are called from the single and batch
+//       paths alike, so the bulk path cannot become the loose one — which is exactly how the
+//       id check came to be missing from it before.
+//
+//   POST only, checked before any parameter is read.
+//
+//   Anything other than the literal "1" is false.
+//       Both flags compare strictly against '1', so a missing or malformed parameter disables
+//       rather than enables. The single-entry path previously used a (bool) cast, under which
+//       the string "false" evaluates to true.
+//
+//   Malformed batch JSON degrades to an empty set.
+//       json_decode with a ?: [] fallback, so a truncated payload writes nothing rather than
+//       rebuilding the crontab from garbage.
+//
+// REQUEST
+//   POST id=<Category/name.sh>  enabled=0|1  cron=<5 fields|array_start|array_stop|empty>
+//                               log_enabled=0|1
+//   POST batch=<JSON array of {id, enabled, cron, log_enabled}>
+//
+// RESPONSE
+//   {"ok":true,"error":null}
+//   {"ok":false,"error":"POST only"|"Invalid id"|"Invalid cron expression"
+//                      |"Failed to write schedule"}
+//
+// DEPENDS ON
+//   include/scheduler.php   vv_schedule_update(), vv_schedule_update_batch(),
+//                           vv_cron_rebuild()
+//   varaverk.cron           generated output — never edited directly
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/scheduler.php';
 
@@ -7,6 +80,20 @@ if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
     exit;
 }
 
+// Both values below are interpolated into the generated crontab by vv_cron_rebuild(), so
+// neither may contain a quote, a shell metacharacter, or a newline.
+function vv_sched_id_valid(string $id): bool {
+    return $id !== '' && !str_contains($id, '..') && (bool)preg_match('/^[A-Za-z0-9_.\-\/]+\.sh$/', $id);
+}
+
+// Five whitespace-separated fields of cron-safe characters only. \s matches newline, so the
+// field-count pattern alone would accept a value carrying a second crontab line.
+function vv_sched_cron_valid(string $cron): bool {
+    if (in_array($cron, ['array_start', 'array_stop'], true)) return true;
+    if (!preg_match('/^[0-9A-Za-z*,\-\/ ]+$/', $cron)) return false;
+    return (bool)preg_match('/^(\S+ +){4}\S+$/', $cron);
+}
+
 // Batch save — all entries in one load/write/rebuild cycle
 if (!empty($_POST['batch'])) {
     $entries = json_decode($_POST['batch'], true) ?: [];
@@ -14,9 +101,8 @@ if (!empty($_POST['batch'])) {
     foreach ($entries as $e) {
         $id   = trim($e['id'] ?? '');
         $cron = trim($e['cron'] ?? '');
-        if (!$id) continue;
-        if ($cron && !in_array($cron, ['array_start', 'array_stop'], true)
-                  && !preg_match('/^(\S+\s+){4}\S+$/', $cron)) $cron = '';
+        if (!vv_sched_id_valid($id)) continue;
+        if ($cron && !vv_sched_cron_valid($cron)) $cron = '';
         $clean[] = [
             'id'          => $id,
             'enabled'     => ($e['enabled'] ?? '0') === '1',
@@ -30,18 +116,17 @@ if (!empty($_POST['batch'])) {
 }
 
 $id          = trim($_POST['id']      ?? '');
-$enabled     = (bool)($_POST['enabled'] ?? false);
+$enabled     = ($_POST['enabled']     ?? '0') === '1';
 $cron        = trim($_POST['cron']    ?? '');
 $log_enabled = ($_POST['log_enabled'] ?? '0') === '1';
 
-if (!$id) {
-    echo json_encode(['ok' => false, 'error' => 'Missing id']);
+if (!vv_sched_id_valid($id)) {
+    echo json_encode(['ok' => false, 'error' => 'Invalid id']);
     exit;
 }
 
-// Basic cron validation — 5 fields, or known @event trigger, or empty
-if ($cron && !in_array($cron, ['array_start', 'array_stop'], true)
-         && !preg_match('/^(\S+\s+){4}\S+$/', $cron)) {
+// 5 cron fields, or a known event trigger, or empty
+if ($cron && !vv_sched_cron_valid($cron)) {
     echo json_encode(['ok' => false, 'error' => 'Invalid cron expression']);
     exit;
 }
diff --git a/Plugin/unraid/api/script.php b/Plugin/unraid/api/script.php
index 5386cb0..8f99904 100644
--- a/Plugin/unraid/api/script.php
+++ b/Plugin/unraid/api/script.php
@@ -1,4 +1,78 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Custom script CRUD. Reads, saves and deletes the user-authored scripts behind the
+//   scheduler page's "+ Create Script" editor.
+//
+// OPERATIONAL MODEL
+//   Custom scripts live in CUSTOM_SCRIPTS_DIR, outside the git repo entirely — alongside the
+//   User Scripts plugin's own storage. That is what keeps them out of the pushed repository
+//   and lets them survive a git pull that rewrites everything under SCRIPTS_DIR. Any .sh file
+//   dropped into that folder by hand is picked up too; it does not have to be created here.
+//
+//   The Custom/ prefix is a namespace, not a directory under SCRIPTS_DIR. Ids are
+//   Custom/<name>.sh everywhere in the scheduler, and vv_cron_rebuild() is the other half of
+//   the convention — it maps that prefix onto CUSTOM_SCRIPTS_DIR when generating cron lines.
+//
+//   Saving also registers. A new script gets a disabled, unscheduled entry in schedule.json so
+//   it appears in the job list immediately; the user then schedules it through scheduler.php.
+//
+// DESIGN PRINCIPLES
+//   Names, not paths, on the write side.
+//       POST takes a bare name and composes the id and the path from it. There is no way to
+//       express a subdirectory, so the flat namespace is a property of the interface rather
+//       than something validation has to enforce afterwards.
+//
+//   Delete removes the script and its schedule entry together.
+//       Unlink, drop the schedule key, save, rebuild the cron. Leaving a schedule entry for a
+//       script that no longer exists would put a cron line in place for a missing file.
+//
+//   Reading a script that does not exist returns empty content, not an error.
+//       The editor opens the same way for a new script and an existing one.
+//
+// OPERATIONAL SAFEGUARDS
+//   The read id is constrained to the Custom namespace.
+//       ^Custom/[a-zA-Z0-9_\-]+\.sh$ plus a '..' check — no dots in the name, no nested path,
+//       no other prefix. This endpoint cannot be used to read a repo script; that is
+//       readscript.php, which has its own extension allowlist.
+//
+//   The write name excludes every path character.
+//       ^[a-zA-Z0-9_\-]+$ — no slash, no dot, no traversal sequence can be expressed, so the
+//       composed path is always a direct child of CUSTOM_SCRIPTS_DIR. The name pattern is
+//       stricter than the read pattern because it is what constructs the filename.
+//
+//   The script write is atomic, and executable before it is visible.
+//       tmp + chmod 0755 + rename. An enabled custom script can be launched by cron at any
+//       moment; writing in place would let it fire against a truncated file, and chmod after
+//       the write would let it fire against a non-executable one.
+//
+//   Delete confirms existence first, so a repeated delete reports a clear "Script not found"
+//   rather than silently rebuilding the cron for nothing.
+//
+//   Unknown methods are refused explicitly at the end, so a PUT or DELETE cannot fall through
+//   the two handled blocks into an empty 200.
+//
+//   Accepted by design: this endpoint writes an executable root-run script from a browser.
+//       That is the entire feature, and it is why it is confined to a directory outside the
+//       repo with a flat namespace and a strict name pattern. It is guarded by the Unraid
+//       WebGUI session; see the CSRF note in README-unraid.md.
+//
+// REQUEST
+//   GET  ?id=Custom/<name>.sh                       read (empty content when absent)
+//   POST name=<name>  content=<script text>         save or overwrite (action defaults to save)
+//   POST name=<name>  action=delete                 delete script and schedule entry
+//
+// RESPONSE
+//   {"ok":true,"content":"…"}                       read
+//   {"ok":true,"id":"Custom/<name>.sh"}             save
+//   {"ok":true}                                     delete
+//   {"ok":false,"error":"Invalid id"|"Name must be letters, numbers, _ or - only"
+//                      |"Script not found"|"Failed to write script"|"Method not allowed"}
+//
+// DEPENDS ON
+//   include/scheduler.php   vv_schedule_load(), vv_schedule_save(), vv_cron_rebuild()
+//   include/config.php      CUSTOM_SCRIPTS_DIR
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/scheduler.php';
 
@@ -42,11 +116,20 @@ if ($_SERVER['REQUEST_METHOD'] === 'POST') {
 
     $dir = CUSTOM_SCRIPTS_DIR;
     if (!is_dir($dir)) mkdir($dir, 0755, true);
-    if (file_put_contents($path, $content) === false) {
+    // tmp + chmod + rename — an enabled script can be launched by cron at any moment, and a
+    // half-written or not-yet-executable file would run as a truncated script.
+    $tmp = $path . '.vv.tmp';
+    if (file_put_contents($tmp, $content) === false) {
+        @unlink($tmp);
+        echo json_encode(['ok' => false, 'error' => 'Failed to write script']);
+        exit;
+    }
+    chmod($tmp, 0755);
+    if (!rename($tmp, $path)) {
+        @unlink($tmp);
         echo json_encode(['ok' => false, 'error' => 'Failed to write script']);
         exit;
     }
-    chmod($path, 0755);
 
     // Ensure schedule.json has an entry so the script appears in the job list
     $schedule = vv_schedule_load();
diff --git a/Plugin/unraid/api/scriptinfo.php b/Plugin/unraid/api/scriptinfo.php
index dfb0df2..ffeacbd 100644
--- a/Plugin/unraid/api/scriptinfo.php
+++ b/Plugin/unraid/api/scriptinfo.php
@@ -1,4 +1,71 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Contextual help for one script. Returns its header block plus any documentation sections
+//   about it found in the README and Manual files — the info panel on the scheduler page.
+//
+// OPERATIONAL MODEL
+//   Documentation is assembled at request time, not indexed. Two sources are combined: the
+//   script's own header comment, which is authoritative because it lives next to the code,
+//   and matching sections from the markdown docs, which give the surrounding context the
+//   header deliberately leaves out.
+//
+//   Four documents are searched per request — the top-level README.md and Manual.md, plus the
+//   module-level README-<Dir>.md and Manual-<Dir>.md for the script's own folder. That mirrors
+//   how the docs are actually organised: general behaviour at the top, specifics per folder.
+//
+// DESIGN PRINCIPLES
+//   Matches headings by slug, with a first-word fallback.
+//       The script name is normalised — underscores and hyphens to spaces, lowercased — and a
+//       heading matches if it contains the whole slug or, failing that, the first word when
+//       that word is longer than three characters. The length floor is what stops a script
+//       beginning with "arr" or "sync" from matching every section in the file.
+//
+//   Intro sections are never matched.
+//       The matcher returns false for the intro, because the opening prose of a README
+//       mentions many scripts and would otherwise match nearly all of them.
+//
+//   Every section carries its source label.
+//       The panel shows where each block came from, so a reader can tell the module manual
+//       from the top-level README rather than seeing one undifferentiated wall of text.
+//
+//   Works for documents as well as scripts.
+//       A non-.sh id yields no header and only the doc sections, so the same endpoint serves
+//       the docs tab's own entries.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Nothing here writes, executes, or schedules anything.
+//
+//   Traversal is blocked before any path is composed.
+//       An explicit '..' check plus ^[A-Za-z0-9_./\-]+$. The slash must be permitted because
+//       ids are Category/name.sh, so the '..' test carries the traversal guarantee on its own.
+//
+//   The filesystem is only touched for ids that name a script.
+//       The header read is guarded by both the .sh suffix test and file_exists(), so a
+//       well-formed id for a file that is not there returns an empty header rather than a
+//       warning that would leak the absolute path into the JSON body.
+//
+//   Every document is existence-checked before it is searched, and the module-level path is
+//   additionally guarded against a dirname of '.' — an id with no directory component would
+//   otherwise compose README-..md and search a file that cannot exist.
+//
+//   Missing documentation is a normal outcome.
+//       No header and no matching sections yields ok:true with empty values. A script nobody
+//       has written about yet is not an error, and reporting it as one would put a failure in
+//       the panel for most custom scripts.
+//
+// REQUEST
+//   GET ?id=<Category/name.sh>   or any documented id
+//
+// RESPONSE
+//   {"ok":true,"name":"…","header":"…","sections":[{"source":"…","body":"…"}, …]}
+//   {"ok":false,"error":"Invalid id"}
+//
+// DEPENDS ON
+//   include/scheduler.php   vv_script_header_clean()
+//   include/docs.php        vv_readme_section()   (loaded transitively)
+//   SCRIPTS_DIR             README.md, Manual.md, README-<Dir>.md, Manual-<Dir>.md
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/scheduler.php';
 
diff --git a/Plugin/unraid/api/settings.php b/Plugin/unraid/api/settings.php
index 2cc7227..e0f9a2d 100644
--- a/Plugin/unraid/api/settings.php
+++ b/Plugin/unraid/api/settings.php
@@ -1,7 +1,73 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Relocates the plugin. Points SCRIPTS_DIR in varaverk.cfg at a different Varaverk checkout
+//   — the manual equivalent of what the storage-migration flow does automatically.
+//
+// OPERATIONAL MODEL
+//   varaverk.cfg is the one file whose location is fixed. Everything else the plugin reads —
+//   scripts, Configurations/, Deployment/, State_Files/, data/ — is resolved relative to the
+//   SCRIPTS_DIR it names, which is what makes internal-vs-appdata storage mode possible at
+//   all. Rewriting that one value moves the entire plugin.
+//
+//   Currently unreferenced by the UI. The settings tab drives relocation through the storage
+//   migration flow, which also copies the data. This endpoint changes the pointer alone, and
+//   is kept as the recovery path for a cfg that points somewhere that no longer exists.
+//
+// DESIGN PRINCIPLES
+//   Changes the pointer, never moves the data.
+//       There is deliberately no copy step. Migration is a separate, longer operation with
+//       its own confirmation; conflating the two would make a one-field edit capable of
+//       deleting a directory.
+//
+//   Merges into the existing cfg rather than authoring it.
+//       varaverk.cfg carries GITEA_CONTAINER, GITEA_REPO_PATH, GITEA_SSH_KEY, SSH_PORT and
+//       CUSTOM_SCRIPTS_DIR alongside SCRIPTS_DIR. Only the key being changed is touched.
+//
+// OPERATIONAL SAFEGUARDS
+//   POST only, checked before anything is read.
+//
+//   The target must actually be a Varaverk checkout.
+//       is_dir() alone is not enough — it would happily accept /mnt/user or /tmp and leave
+//       every subsequent page resolving conf and script paths under a directory that contains
+//       none of them, with no single obvious symptom. common.sh and load_config.sh must both
+//       be present, because those are the two files every script in the repo sources.
+//
+//   Unrelated keys survive the write.
+//       The previous version emitted a file containing SCRIPTS_DIR and nothing else, silently
+//       discarding the Gitea coordinates that git_pull_execute.sh needs — so a relocation
+//       would have broken both the daily pull and the UI pull button, and only at the next
+//       scheduled run. The cfg is now read, one key replaced, and all keys written back.
+//
+//   The write is atomic.
+//       tmp + rename, so a page render or a script reading varaverk.cfg mid-save sees the old
+//       file or the new one. A truncated varaverk.cfg would leave SCRIPTS_DIR undefined and
+//       every path in the plugin falling back to the compiled-in default.
+//
+//   Values are escaped for the ini quoting parse_ini_file() expects.
+//       addslashes() on every value written, not just the new one, so a path containing a
+//       quote cannot terminate the string early and corrupt the keys that follow it.
+//
+// REQUEST
+//   POST scripts_dir=<absolute path to a Varaverk checkout>
+//
+// RESPONSE
+//   {"ok":true,"error":null}
+//   {"ok":false,"error":"POST only"|"scripts_dir is required"|"Directory does not exist"
+//                      |"Not a Varaverk checkout — common.sh and load_config.sh not found"
+//                      |"Failed to write cfg file"}
+//
+// DEPENDS ON
+//   include/config.php   PLUGIN_CFG
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
+if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
+    echo json_encode(['ok' => false, 'error' => 'POST only']);
+    exit;
+}
+
 $scriptsDir = trim($_POST['scripts_dir'] ?? '');
 
 if (!$scriptsDir) {
@@ -14,11 +80,33 @@ if (!is_dir($scriptsDir)) {
     exit;
 }
 
+// Pointing SCRIPTS_DIR at an arbitrary directory leaves every conf and script path in the
+// plugin resolving under something that holds none of them. These two files are sourced by
+// every script in the repo, so their presence is what makes a directory a checkout.
+if (!file_exists($scriptsDir . '/common.sh') || !file_exists($scriptsDir . '/load_config.sh')) {
+    echo json_encode([
+        'ok'    => false,
+        'error' => 'Not a Varaverk checkout — common.sh and load_config.sh not found',
+    ]);
+    exit;
+}
+
 $cfgFile = PLUGIN_CFG;
 $cfgDir  = dirname($cfgFile);
 if (!is_dir($cfgDir)) mkdir($cfgDir, 0755, true);
 
-$content = 'SCRIPTS_DIR="' . addslashes($scriptsDir) . '"' . "\n";
-$ok = file_put_contents($cfgFile, $content) !== false;
+// Merge, do not author. varaverk.cfg also carries the Gitea coordinates git_pull_execute.sh
+// needs — rewriting the file with SCRIPTS_DIR alone would silently break the daily pull.
+$cfg = @parse_ini_file($cfgFile) ?: [];
+$cfg['SCRIPTS_DIR'] = $scriptsDir;
+
+$content = '';
+foreach ($cfg as $k => $v) {
+    $content .= $k . '="' . addslashes((string)$v) . '"' . "\n";
+}
+
+$tmp = $cfgFile . '.vv.tmp';
+$ok  = file_put_contents($tmp, $content) !== false && rename($tmp, $cfgFile);
+if (!$ok) @unlink($tmp);
 
 echo json_encode(['ok' => $ok, 'error' => $ok ? null : 'Failed to write cfg file']);
diff --git a/Plugin/unraid/api/setup.php b/Plugin/unraid/api/setup.php
index 6a30d72..fcd27ff 100644
--- a/Plugin/unraid/api/setup.php
+++ b/Plugin/unraid/api/setup.php
@@ -1,4 +1,119 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   First-run setup. Detects the environment, generates the SSH keypair, populates the host
+//   conf from discovered services, writes the initial master.conf and host*.conf, and — on a
+//   partner server — pulls master.conf down from HOST1.
+//
+// OPERATIONAL MODEL
+//   Two entirely different journeys share this file because they write the same files. HOST1
+//   authors master.conf from the wizard's answers; every other host receives it over SCP and
+//   never edits it. Which one runs is decided by the action, not by a mode setting.
+//
+//   Ordering is the substance of the save path. master.conf is written first because
+//   host*.conf is generated from a template that needs the host slot; the SSH keypair is
+//   generated before the API key because the key path is written into the conf that the API
+//   key provisioning then reads back. Reordering these silently produces a half-configured
+//   host.
+//
+//   Storage mode is decided here and acted on later. The response reports whether the chosen
+//   mode implies a relocation, and the UI hands that to storage.php — this endpoint never
+//   moves anything itself.
+//
+//   The host conf is only ever created, never overwritten. Every path checks file_exists()
+//   first, so re-running the wizard on a configured host cannot destroy credentials that were
+//   filled in afterwards.
+//
+// DESIGN PRINCIPLES
+//   Detection is advisory; the wizard's answer wins.
+//       Boot transport is auto-detected, but an explicit storage_mode parameter overrides it.
+//       The detection is a good default, not a verdict — someone deliberately choosing appdata
+//       on an internal boot device has a reason.
+//
+//   The partner path resolves HOST1's layout rather than assuming it.
+//       Before the SCP, HOST1's own varaverk.cfg is read over SSH to find its SCRIPTS_DIR,
+//       because the two hosts can legitimately be in different storage modes. Falling back to
+//       the default path when that read fails is the right degradation — it is correct in the
+//       common case.
+//
+//   The template is filled by substitution, not by generation.
+//       HOSTN/hostn placeholders are replaced and two specific keys rewritten. Everything else
+//       in host.conf.template — comments, structure, ordering, the keys not yet filled in —
+//       arrives intact, which is what makes the generated conf readable and diffable.
+//
+//   Failures are named at the step that failed.
+//       Missing SSH key, unresolvable Tailscale name, failed SCP and missing master.conf each
+//       return their own message with the remedy in it. This is the one screen where the user
+//       has no context yet, so a generic error is worth nothing.
+//
+// OPERATIONAL SAFEGUARDS
+//   The host slot is pattern-matched on both paths.
+//       ^host\d+$ before it is used to compose a conf filename or upper-cased into variable
+//       names. That check is what stops 'unknown' — vv_detect_host()'s failure value — from
+//       producing an unknown.conf.
+//
+//   Every script run is externally time-boxed.
+//       `timeout` wraps ssh_setup.sh, conf_populate.sh, the remote cfg read and the SCP.
+//       set_time_limit() does not cover exec() time on Linux, so without this an unreachable
+//       HOST1 would hold a php-fpm worker open for as long as SSH kept trying. The SCP also
+//       runs BatchMode=yes so it can never sit waiting for a password.
+//
+//   Missing scripts are reported, not executed.
+//       file_exists() precedes every exec(), so a partial deploy returns a named error rather
+//       than a shell failure that looks like a failed setup.
+//
+//   Conf values are escaped before substitution.
+//       addslashes() on every hostname written into master.conf, so a pasted value containing
+//       a quote cannot terminate the assignment and corrupt the keys after it.
+//
+//   Conf writes are atomic.
+//       vv_write_conf_raw() (tmp + rename) for both files, and the master.conf write is
+//       checked before the host conf is generated from it.
+//
+//   The setup state is read-modify-written.
+//       vv_setup_state_write() replaces the file wholesale, so the save path reads the
+//       existing state first. Passing only the one new key would erase the partnership phase
+//       markers on a host that had already been onboarded and re-ran the wizard.
+//
+//   The host conf is never overwritten.
+//       Both creation paths are guarded by file_exists(), so re-running setup on a configured
+//       host is a no-op for that file rather than a credential wipe.
+//
+//   The SCP target is the local conf path, composed here — no part of the request names a
+//   destination file.
+//
+//   Accepted: this endpoint writes credentials and runs setup scripts as root.
+//       It is the setup wizard; that is its function. It is guarded by the Unraid WebGUI
+//       session; see the CSRF note in README-unraid.md.
+//
+// REQUEST
+//   GET  ?action=detect          hostname, Unraid version, boot transport, suggested mode
+//   GET|POST action=ssh_generate generate the local keypair, return the public key
+//   POST action=populate         run conf_populate.sh --no-push
+//   POST action=pull             partner: SCP master.conf from HOST1, create host conf
+//        [my_slot] [my_hostname] [host1_hostname]
+//   POST (action=save, default)  HOST1: write master.conf and host conf
+//        host1  [host2] [my_slot] [my_hostname] [storage_mode=internal|flash]
+//
+// RESPONSE
+//   detect        {"ok":true,"hostname","unraid_ver","transport","boot_device","mode",
+//                  "scripts_dir"}
+//   ssh_generate  {"ok":bool,"pubkey":"…","error":…}
+//   populate      {"ok":bool,"lines":[…]}
+//   pull          {"ok":true,"host_id","conf_file","api_key":…,"redirect":"…"}
+//   save          {"ok":true,"host_id","api_key":…,"needs_migration":bool,
+//                  "migrate_to":"internal|flash"|null,"redirect":"…"}
+//   {"ok":false,"error":…} naming the specific step that failed
+//
+// DEPENDS ON
+//   include/config.php              vv_get_hostname(), vv_detect_host(), vv_read_conf_raw(),
+//                                   vv_write_conf_raw(), vv_setup_state_read/_write(),
+//                                   vv_auto_create_api_key(), CONF_DIR, DEPLOY_DIR
+//   Partnership/ssh_setup.sh        keypair generation
+//   Deployment/conf_populate.sh     service discovery
+//   Deployment/host.conf.template   source of the generated host conf
+//   api/storage.php                 performs the migration this endpoint only recommends
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
@@ -39,7 +154,9 @@ if ($action === 'ssh_generate') {
         echo json_encode(['ok' => false, 'error' => 'ssh_setup.sh not found']);
         exit;
     }
-    exec('bash ' . escapeshellarg($script) . ' --local-only 2>&1', $out, $rc);
+    // set_time_limit() does not cover exec() time on Linux — every script run below is
+    // wrapped in `timeout` so a stalled child cannot hold a php-fpm worker open.
+    exec('timeout 120 bash ' . escapeshellarg($script) . ' --local-only 2>&1', $out, $rc);
     // Derive pubkey path from hostname
     $hostname  = vv_get_hostname();
     $shortName = strtolower(preg_replace('/^unraid-/i', '', $hostname));
@@ -60,7 +177,7 @@ if ($action === 'populate') {
         echo json_encode(['ok' => false, 'error' => 'conf_populate.sh not found']);
         exit;
     }
-    exec('bash ' . escapeshellarg($script) . ' --no-push 2>&1', $out, $rc);
+    exec('timeout 180 bash ' . escapeshellarg($script) . ' --no-push 2>&1', $out, $rc);
     $lines = array_values(array_filter(array_map('trim', $out)));
     echo json_encode(['ok' => $rc === 0, 'lines' => array_slice($lines, 0, 20)]);
     exit;
@@ -116,15 +233,15 @@ if ($action === 'pull') {
     // Get HOST1's SCRIPTS_DIR from their varaverk.cfg
     $sshBase   = 'ssh -i ' . escapeshellarg($sshKey)
                . ' -o ConnectTimeout=10 -o StrictHostKeyChecking=no root@' . $ip;
-    $remoteCfg = trim(shell_exec($sshBase . ' "grep SCRIPTS_DIR /boot/config/plugins/varaverk/varaverk.cfg 2>/dev/null"') ?: '');
+    $remoteCfg = trim(shell_exec('timeout 30 ' . $sshBase . ' "grep SCRIPTS_DIR /boot/config/plugins/varaverk/varaverk.cfg 2>/dev/null"') ?: '');
     preg_match('/SCRIPTS_DIR\s*=\s*["\']?([^"\']+)["\']?/', $remoteCfg, $sm);
     $remoteConf = rtrim($sm[1] ?? '/boot/config/plugins/varaverk', '/') . '/Configurations';
 
     // SCP master.conf from HOST1
     $localMaster = CONF_DIR . '/master.conf';
     $src  = escapeshellarg('root@' . $ip . ':' . $remoteConf . '/master.conf');
-    $cmd  = 'scp -i ' . escapeshellarg($sshKey)
-          . ' -o ConnectTimeout=10 -o StrictHostKeyChecking=no'
+    $cmd  = 'timeout 60 scp -i ' . escapeshellarg($sshKey)
+          . ' -o ConnectTimeout=10 -o StrictHostKeyChecking=no -o BatchMode=yes'
           . ' ' . $src . ' ' . escapeshellarg($localMaster) . ' 2>&1';
     exec($cmd, $out, $rc);
     if ($rc !== 0) {
@@ -154,7 +271,7 @@ if ($action === 'pull') {
     }
 
     if (file_exists($sshScript)) {
-        exec('bash ' . escapeshellarg($sshScript) . ' --local-only 2>/dev/null');
+        exec('timeout 120 bash ' . escapeshellarg($sshScript) . ' --local-only 2>/dev/null');
     }
     $apiKeyResult = vv_auto_create_api_key($hostId, $confFile);
 
@@ -247,12 +364,16 @@ if (!file_exists(CONF_DIR . '/' . $confFile)) {
     }
 }
 
-// Write setup state file — lets partner servers know HOST1 is configured
-vv_setup_state_write(['host1_hostname' => $host1]);
+// Write setup state file — lets partner servers know HOST1 is configured.
+// Read-modify-write: vv_setup_state_write() replaces the file wholesale, and re-running the
+// wizard must not erase onboarding progress recorded by the partnership phases.
+$state = vv_setup_state_read();
+$state['host1_hostname'] = $host1;
+vv_setup_state_write($state);
 
 // Auto-generate SSH keypair (local only — remote copy happens during onboarding)
 if (file_exists($sshScript)) {
-    exec('bash ' . escapeshellarg($sshScript) . ' --local-only 2>/dev/null');
+    exec('timeout 120 bash ' . escapeshellarg($sshScript) . ' --local-only 2>/dev/null');
 }
 
 // Auto-create Unraid API key and write into the fresh conf
diff --git a/Plugin/unraid/api/snapshot.php b/Plugin/unraid/api/snapshot.php
index 072b7ea..33817cf 100644
--- a/Plugin/unraid/api/snapshot.php
+++ b/Plugin/unraid/api/snapshot.php
@@ -1,4 +1,72 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Header snapshot. The small always-visible summary carried across every tab — CPU, RAM,
+//   fallback state, partner peers, and active stream and transcode counts.
+//
+// OPERATIONAL MODEL
+//   This is the most frequently requested endpoint in the plugin: it is polled from whichever
+//   tab happens to be open, continuously, for as long as the page is open. Everything about
+//   it is shaped by that. Each field is the cheapest available answer to its question, not
+//   the most complete one — monitor.php exists for the complete one.
+//
+// DESIGN PRINCIPLES
+//   Shares the CPU baseline rather than sampling its own.
+//       vv_cpu_per_core() keeps its counters in /tmp/vv_cpu_stat.json, and reading through it
+//       means the header and the monitor page report the same number. Two independent
+//       samplers would drift apart and produce a visible disagreement between the header and
+//       the page directly below it.
+//
+//   Fallback state is read from the file, never derived.
+//       A direct read of fallback_state.db with no exec and no SSH. The authoritative answer
+//       is the one fallback.sh wrote; recomputing it here would be both slower and capable of
+//       disagreeing with the process that actually controls failover.
+//
+//   Media counts are cached 30 seconds, everything else is live.
+//       Streams are the only field that costs HTTP round trips to another service. Caching
+//       just that keeps the poll cheap without making CPU or RAM stale, and 30s is well under
+//       the time it takes anyone to notice a stream started.
+//
+//   Peers exclude self.
+//       is_me is filtered out here rather than in the UI, so every consumer of this payload
+//       gets the same definition of "peers" and none of them can forget to apply it.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Nothing here starts, stops, or changes anything.
+//
+//   The fallback read degrades to a named unknown.
+//       @file_get_contents with a ?: '' fallback, and the parsed state defaults to 'UNKNOWN'.
+//       A missing or unreadable state file shows UNKNOWN in the header rather than NORMAL —
+//       reporting healthy for a fallback process that is not running is the one error this
+//       field must never make.
+//
+//   Division is guarded.
+//       ram_total_mb > 0 is checked before the percentage, so a failed meminfo read yields 0
+//       rather than a division by zero that would fatal on every tab at once.
+//
+//   Every count is cast on the way out.
+//       (int) on the cached stream and transcode counts with ?? 0 defaults, so a cache file
+//       written by an older schema cannot put a null or a string into the header payload.
+//
+//   Media failures are already contained upstream — vv_media_sessions() time-boxes each
+//   request at 3s and returns an empty session list on any failure, so an unreachable Emby
+//   costs this poll nothing beyond that timeout, once every 30 seconds.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   {"cpu_pct","ram_pct","ram_used_mb","ram_total_mb","fallback","partner_enabled",
+//    "peers":[…],"stream_count","transcode_count"}
+//
+// DEPENDS ON
+//   include/common.php    vv_cpu_per_core(), vv_system_resources()
+//                         (loaded transitively through include/monitor.php)
+//   include/monitor.php   vv_partner_state()
+//   include/config.php    vv_parse_kv_db(), vv_cache_read(), vv_cache_write(), STATE_DIR
+//   include/media.php     vv_media_sessions()
+//   STATE_DIR             fallback_state.db — written by Fallback/fallback.sh
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/monitor.php';
 require_once dirname(__DIR__) . '/include/media.php';
diff --git a/Plugin/unraid/api/status.php b/Plugin/unraid/api/status.php
index 7747530..7f60276 100644
--- a/Plugin/unraid/api/status.php
+++ b/Plugin/unraid/api/status.php
@@ -1,12 +1,60 @@
 <?php
-// Returns current run status for all scheduled jobs.
-// Used by the scheduler page to light up running indicators without user interaction.
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Job status endpoint. The current run status of every scheduled job, keyed by job id, so
+//   the scheduler page can light up running indicators on a poll without the user opening
+//   anything.
+//
+// OPERATIONAL MODEL
+//   Status is not stored centrally — each job writes its own .json stat file beside its log,
+//   and this endpoint reads the schedule to know which ids exist, then collects one file per
+//   id. A job with no stat file has never run and is omitted entirely, which is how the page
+//   tells "never run" apart from "ran and finished".
+//
+// DESIGN PRINCIPLES
+//   The recorded status is cross-checked against the process table.
+//       A stat file saying "running" is only believed while /proc/<pid> still exists. A
+//       runner killed mid-job — OOM, reboot, kill -9 — never gets to write its own failure,
+//       so trusting the file alone would leave the page showing a spinner forever.
+//
+//   Reports status only.
+//       No timestamps, no output, no exit codes. This is polled frequently and exists to
+//       drive indicator state; the detail views fetch what they need from log.php.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Nothing here starts, stops, or reaps a job.
+//
+//   Every file read degrades to an empty object.
+//       @file_get_contents with a ?: '{}' fallback and a ?: [] after json_decode, so a stat
+//       file that is unreadable or caught mid-write yields status 'unknown' rather than a
+//       fatal that would blank every indicator on the page.
+//
+//   A dead runner is reported as error, never as still running.
+//       This is the safe direction to be wrong in: a job wrongly shown as finished prompts
+//       someone to look, whereas one wrongly shown as running is silently ignored forever.
+//
+//   Known limit: PID reuse.
+//       /proc/<pid> existing does not prove it is still *this* job's process. On a host that
+//       has churned through the pid space a recycled pid could hold a dead job in 'running'.
+//       Accepted rather than fixed — the alternative is a start-time comparison against
+//       /proc/<pid>/stat, which is more machinery than an indicator light justifies.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   {"<job id>":"running"|"success"|"error"|"unknown", …}
+//   Jobs that have never run are absent from the object entirely.
+//
+// DEPENDS ON
+//   include/scheduler.php   vv_schedule_load(), vv_job_stat_path()
+//   LOG_DIR                 <job>.json stat files written by run_job.sh
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/scheduler.php';
 
-$schedule = vv_schedule_load();
-$result   = [];
-foreach ($schedule as $id => $entry) {
+$result = [];
+foreach (array_keys(vv_schedule_load()) as $id) {
     $statFile = vv_job_stat_path($id);
     if (!file_exists($statFile)) continue;
     $stat   = json_decode(@file_get_contents($statFile) ?: '{}', true) ?: [];
diff --git a/Plugin/unraid/api/stop.php b/Plugin/unraid/api/stop.php
index 4a58bdc..bc203e3 100644
--- a/Plugin/unraid/api/stop.php
+++ b/Plugin/unraid/api/stop.php
@@ -1,4 +1,88 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Job killer. Terminates a running job, clears the lock files it left behind, and corrects
+//   its stat file — the stop button on the scheduler page.
+//
+// OPERATIONAL MODEL
+//   Escalating termination, then cleanup. SIGTERM to the whole process group, up to three
+//   seconds to exit, SIGKILL if it did not. The group is the target rather than the pid
+//   because a Varaverk script is mostly other processes — rsync, ssh, curl, docker — and
+//   killing only the parent would orphan every one of them still holding the resources the
+//   next run needs.
+//
+//   The stat file is the job's own record, and a killed job never gets to correct it. This
+//   endpoint does that on its behalf, which is what stops the scheduler page from showing a
+//   spinner for a job that no longer exists.
+//
+// DESIGN PRINCIPLES
+//   Kills the group, falls back to the tree.
+//       `ps -o pgid=` resolves the process group; when that fails the fallback is pkill -P
+//       plus the pid itself. Two strategies, because a job whose runner already exited can
+//       leave children whose group id is no longer discoverable from the recorded pid.
+//
+//   Waits before escalating.
+//       Six 500ms checks between TERM and KILL. Scripts have cleanup handlers — releasing
+//       locks, finishing a write, unmounting — and killing immediately would skip exactly the
+//       work that makes the next run safe.
+//
+//   Reports honestly when the kill failed.
+//       ok mirrors whether the process is actually gone. A process in uninterruptible sleep
+//       survives SIGKILL, and the response says so rather than claiming success and leaving
+//       the user to discover the job is still running.
+//
+// OPERATIONAL SAFEGUARDS
+//   The job id is validated, and the pid is an integer before it reaches a shell.
+//       ^[a-zA-Z0-9_./\-]+\.sh$ with an explicit '..' check on the id, and (int) casts on
+//       every pid — the recorded one and each lock's owner — before interpolation. The signal
+//       commands are the only shell in this file and none of them can carry anything but a
+//       number.
+//
+//   pid < 2 is refused.
+//       A zero, missing, or malformed pid in the stat file would make `kill -TERM -0` signal
+//       the caller's own process group — the web server. Rejecting anything below 2 also
+//       excludes init.
+//
+//   A job that is not running is a no-op success.
+//       Both the missing-stat-file and status-not-running paths exit before any signal is
+//       sent, so pressing stop twice cannot kill an unrelated process that has since been
+//       assigned the recorded pid.
+//
+//   The pid is only cleared from the stat file if the process is confirmed gone.
+//       D-state processes survive SIGKILL. Clearing the pid there would lose the only handle
+//       anyone has on a process that is still holding locks, and would report the job stopped
+//       while it continues to run.
+//
+//   Lock clearing is bounded to the lock directory and to dead owners.
+//       glob over /tmp/unraid_locks/*.lock — a hardcoded literal, not a config value — and a
+//       lock is removed only when its recorded owner is this pid or is no longer in /proc. A
+//       lock held by a live, unrelated process is never touched.
+//
+//   Deliberate side effect: stale locks from other jobs are reaped too.
+//       The dead-owner test is not scoped to this job, so one stop clears every abandoned
+//       lock on the host. That is intentional — a lock whose owner does not exist is by
+//       definition stale, and leaving it to be found later means a future run refuses to
+//       start for no reason.
+//
+//   The name-based fallback covers pid rotation.
+//       A lock file named after the script is removed regardless of its recorded owner,
+//       because a rotated pid can make a genuinely stale lock look live.
+//
+// REQUEST
+//   POST id=<Category/name.sh>
+//
+// RESPONSE
+//   {"ok":true,"killed":true,"locks":["…"],"error":null}
+//   {"ok":true,"msg":"Not running"}
+//   {"ok":false,"killed":false,"locks":[…],
+//    "error":"Process still alive after SIGKILL (D-state) — lock may persist"}
+//   {"ok":false,"error":"Invalid id"|"No stat file — script may not be running"
+//                      |"No valid PID in stat file"}
+//
+// DEPENDS ON
+//   include/scheduler.php   vv_job_stat_path()
+//   /tmp/unraid_locks       lock files written by common.sh's locking helper
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/scheduler.php';
 
diff --git a/Plugin/unraid/api/storage.php b/Plugin/unraid/api/storage.php
index 53848a7..aa48d7c 100644
--- a/Plugin/unraid/api/storage.php
+++ b/Plugin/unraid/api/storage.php
@@ -1,6 +1,111 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Storage mode and API key management. Reports where the plugin currently lives and what
+//   kind of device it boots from, migrates it between internal and flash layouts, records the
+//   detected mode into conf, and reports or provisions Unraid API keys across all hosts.
+//
+// OPERATIONAL MODEL
+//   Storage mode exists because /boot is not the same thing on every Unraid host. On a real
+//   USB flash device, write wear is a genuine constraint and the plugin belongs in appdata; on
+//   a host that boots from an internal SSD or a ZFS pool it does not, and living under
+//   /boot/config/plugins is simpler. The mode is therefore detected from the boot device's
+//   transport rather than assumed.
+//
+//   Detection walks from the mountpoint down to physical media, and handles two shapes. A
+//   block-device /boot resolves through lsblk's parent-name to the whole disk. A ZFS /boot
+//   resolves through zpool to a backing vdev first, skipping the mirror/raidz/spare topology
+//   rows, and then to its whole disk. Only then is the transport read.
+//
+//   Migration is delegated entirely to storage_migrate.sh. It copies data, rewrites
+//   varaverk.cfg and master.conf, and removes the old location — far too much to do inside a
+//   web request, and it must be resumable and testable on its own.
+//
+// DESIGN PRINCIPLES
+//   Reports detected and current separately, and never reconciles them itself.
+//       current_mode is where the plugin actually is; detected is where the hardware suggests
+//       it should be. A host can legitimately sit in either state, so the status action
+//       presents both and lets a person decide.
+//
+//   A third mode, custom, is a first-class answer.
+//       A SCRIPTS_DIR matching neither known path is reported as custom rather than being
+//       forced into one of the two. Someone who deliberately relocated the plugin should not
+//       see the UI claim it is somewhere it is not.
+//
+//   API key status is reported for every host, from conf.
+//       Partner keys live in the partner's own conf section, so a partner's key can be
+//       reported present without contacting it. Only the local host's key is validated
+//       against the API, because only the local host has one to call.
+//
+//   Keys are previewed, never returned.
+//       First 8 and last 4 characters — enough to confirm which key is in use, not enough to
+//       use it.
+//
+// OPERATIONAL SAFEGUARDS
+//   The migration target is an exact allowlist with strict comparison.
+//       Only 'internal' and 'flash' reach the script, as an escapeshellarg'd --to= value. No
+//       part of the request names a path, so migration cannot be pointed anywhere else.
+//
+//   Every shell argument is escaped, including ones derived from other shell calls.
+//       The device names discovered during detection are fed back into lsblk through
+//       escapeshellarg(), so a device name containing anything unexpected cannot compose a
+//       command.
+//
+//   Every detection step degrades to 'unknown' rather than guessing.
+//       A failed findmnt, lsblk, or zpool returns unknown at that step and stops. Guessing
+//       here would mean recommending a migration based on a device that was never identified.
+//
+//   Both script runs are externally time-boxed.
+//       `timeout` wraps each — set_time_limit() does not cover exec() time on Linux, so PHP's
+//       own limit cannot end a stalled migration or a key renewal hung on an unreachable
+//       partner. Exit 124 is reported as a timeout, distinctly from a script failure.
+//
+//   Missing scripts are reported, not executed.
+//       file_exists() precedes both exec() calls, so a partial deploy returns a named error
+//       rather than a shell failure that would look like a failed migration.
+//
+//   Migration and detection are POST-only. status and api_status are the only GET-reachable
+//   actions, and both are pure reads.
+//
+//   Handle with care: the detect action writes HOST<n>_STORAGE_MODE_INTERNAL.
+//       That value decides where the plugin's data lives, and on HOST1 it is deliberately
+//       pinned. Running detect on a host whose boot device reports an unexpected transport
+//       would rewrite it. The action exists for onboarding a new host, where nothing has been
+//       decided yet — it is not a repair tool for an established one.
+//
+//   The conf write goes through the structured writer, so it is atomic and syntax-checked —
+//   which is also why include/confform.php must be loaded here. It was previously absent and
+//   the detect action fataled on an undefined function.
+//
+// REQUEST
+//   GET|POST ?action=status         current mode, detected mode, boot device, conf value
+//   GET|POST ?action=api_status     per-host API key presence and local API health
+//   POST action=migrate  to=internal|flash
+//   POST action=detect              write the detected mode into this host's conf
+//   POST action=setup_apikeys       run unraid_api_key_renew.sh
+//
+// RESPONSE
+//   status         {"ok":true,"current_mode","current_dir","internal_dir","flash_dir",
+//                   "transport","detected","boot_disk","conf_key","conf_val","array_started"}
+//   api_status     {"ok":true,"my_id","key_name","hosts":[…],"fallbacks":…}
+//   migrate        {"ok":bool,"exit":int,"output":"…"}
+//   detect         {"ok":bool,"detected":"true|false","transport":"…"}
+//   setup_apikeys  {"ok":bool,"exit":int,"output":"…"}
+//   {"ok":false,"error":"Invalid target: …"|"storage_migrate.sh not found"
+//                      |"unraid_api_key_renew.sh not found"|"… timed out …"|"Unknown action"}
+//
+// DEPENDS ON
+//   include/config.php       SCRIPTS_DIR, vv_detect_host(), vv_conf_vars()
+//   include/confform.php     vv_conf_write_changes()
+//   include/unraid_api.php   vv_api_get_status()   (loaded only by api_status)
+//   Tools/storage_migrate.sh
+//   System_Essentials/unraid_api_key_renew.sh
+//   findmnt, lsblk, zpool
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
+// vv_conf_write_changes() lives here — the detect action fatals without it.
+require_once dirname(__DIR__) . '/include/confform.php';
 
 $action = $_GET['action'] ?? $_POST['action'] ?? '';
 
@@ -58,7 +163,7 @@ if ($action === 'status') {
         'flash_dir'    => $flashDir,
         'transport'    => $transport,
         'detected'     => $detected,
-        'boot_disk'    => $bootDisk ? '/dev/' . $bootDisk : 'unknown',
+        'boot_disk'    => $bootDisk ?: 'unknown',
         'conf_key'     => $confKey,
         'conf_val'     => $confVal,
         'array_started'=> is_dir('/mnt/user') && count(scandir('/mnt/user')) > 2,
@@ -80,10 +185,15 @@ if ($action === 'migrate' && $_SERVER['REQUEST_METHOD'] === 'POST') {
         exit;
     }
 
-    set_time_limit(300);
+    // set_time_limit() does not cover exec() time on Linux, so the bound is external.
+    set_time_limit(630);
     $output = [];
     $exit   = 0;
-    exec('bash ' . escapeshellarg($script) . ' --to=' . escapeshellarg($to) . ' 2>&1', $output, $exit);
+    exec('timeout 600 bash ' . escapeshellarg($script) . ' --to=' . escapeshellarg($to) . ' 2>&1', $output, $exit);
+    if ($exit === 124) {
+        echo json_encode(['ok' => false, 'error' => 'storage_migrate.sh timed out after 600s', 'output' => implode("\n", $output)]);
+        exit;
+    }
 
     echo json_encode([
         'ok'     => $exit === 0,
@@ -160,9 +270,14 @@ if ($action === 'setup_apikeys' && $_SERVER['REQUEST_METHOD'] === 'POST') {
     if (!file_exists($script)) {
         echo json_encode(['ok' => false, 'error' => 'unraid_api_key_renew.sh not found']); exit;
     }
-    set_time_limit(60);
+    // set_time_limit() does not cover exec() time on Linux — this script reaches every
+    // partner over SSH, so the bound has to be external.
+    set_time_limit(150);
     $output = []; $exit = 0;
-    exec('bash ' . escapeshellarg($script) . ' 2>&1', $output, $exit);
+    exec('timeout 120 bash ' . escapeshellarg($script) . ' 2>&1', $output, $exit);
+    if ($exit === 124) {
+        echo json_encode(['ok' => false, 'error' => 'unraid_api_key_renew.sh timed out after 120s']); exit;
+    }
     echo json_encode(['ok' => $exit === 0, 'exit' => $exit, 'output' => implode("\n", $output)]);
     exit;
 }
diff --git a/Plugin/unraid/api/system.php b/Plugin/unraid/api/system.php
index c10550b..df40207 100644
--- a/Plugin/unraid/api/system.php
+++ b/Plugin/unraid/api/system.php
@@ -1,4 +1,73 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Host power control. Stops the array, shuts the machine down, or reboots it. The three
+//   most destructive operations the plugin can perform, deliberately isolated in one small
+//   file rather than folded into a general-purpose action endpoint.
+//
+// OPERATIONAL MODEL
+//   The command is detached and the response returns immediately. A shutdown kills the web
+//   server that is serving this request, so waiting on the child would mean the browser sees
+//   a connection reset rather than a result. Backgrounding is what lets the UI acknowledge
+//   the action before the host stops answering.
+//
+//   ok:true therefore means "accepted and dispatched", not "completed". Nothing can report
+//   the completion of an operation that ends the process reporting it.
+//
+// DESIGN PRINCIPLES
+//   Three fixed commands, chosen by name.
+//       The action string selects among three compiled-in literals through a match. No part
+//       of the request is ever interpolated into the command, so there is no injection
+//       surface to protect — the request cannot express a command that is not one of these
+//       three.
+//
+//   Reads its body as JSON, not as a form.
+//       php://input is parsed directly, because POST bodies are unreliable on this Unraid
+//       PHP setup and reading the raw stream sidesteps the form parser entirely.
+//
+//   No scheduling, no delay, no cancel.
+//       There is nothing to cancel because there is no window in which to cancel it. A delayed
+//       shutdown with a cancel path would need state, and state that can be wrong about
+//       whether a host is about to power off is worse than no state.
+//
+// OPERATIONAL SAFEGUARDS
+//   POST only, checked first.
+//       A GET cannot power off the host, so no link, prefetch, bookmark, or browser history
+//       entry can reach these commands.
+//
+//   Strict allowlist with strict comparison.
+//       in_array($action, ['stop','shutdown','restart'], true) — the third argument matters.
+//       Without it PHP's loose comparison would accept values that are not these strings, and
+//       the match below would then have no arm for them.
+//
+//   The match has no default arm, and that is safe only because of the check above.
+//       An unmatched action would raise \UnhandledMatchError, which is a hard failure rather
+//       than a wrong command — but it is unreachable, because the allowlist already rejected
+//       everything that is not one of the three. The two guards are deliberately redundant.
+//
+//   The audit line is written before the command is dispatched, not after.
+//       Ordering is the whole point: after a shutdown there is no "after". Timestamp, action
+//       and originating IP land in actions.log with LOCK_EX while the machine is still
+//       running, so a power event always has a record of who asked for it.
+//
+//   The audit write is best-effort and never blocks the action.
+//       @ and FILE_APPEND — a full or read-only flash must not be able to prevent a shutdown.
+//       Losing the log line is the lesser failure; the log is gitignored and local by design.
+//
+// REQUEST
+//   POST {"action":"stop"}       stop the array (mdcmd stop)
+//   POST {"action":"shutdown"}   power off the host
+//   POST {"action":"restart"}    reboot the host
+//
+// RESPONSE
+//   {"ok":true}                             accepted and dispatched — not completed
+//   {"ok":false,"error":"POST only"|"invalid action"}
+//
+// DEPENDS ON
+//   include/config.php          SCRIPTS_DIR (audit log location)
+//   /usr/local/sbin/mdcmd       array control
+//   /sbin/shutdown              host power control
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
diff --git a/Plugin/unraid/api/watchdog.php b/Plugin/unraid/api/watchdog.php
index 9fcc124..b8bf731 100644
--- a/Plugin/unraid/api/watchdog.php
+++ b/Plugin/unraid/api/watchdog.php
@@ -1,4 +1,47 @@
 <?php
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Watchdog data endpoint. Every watchdog's current state for every node in one document —
+//   resource, docker, system, storage, network and stability — together with the thresholds
+//   each one is judging against, for the watchdog tab's poll.
+//
+// DESIGN PRINCIPLES
+//   Thin transport. State-file parsing and threshold resolution live in
+//   include/watchdog.php; this file only sets the content type and encodes.
+//
+//   Thresholds ship with the state, not separately.
+//       vv_wd_all() resolves every threshold from master.conf into the same payload as the
+//       counters they apply to. A strike count means nothing without the limit it is counted
+//       against, so the page never has to fetch the two independently and risk mismatching
+//       them across a conf edit.
+//
+//   No parameters. Which watchdogs exist is fixed by the codebase, not by the request.
+//
+// OPERATIONAL SAFEGUARDS
+//   Read-only. Nothing here clears a strike, lifts a skip-list entry, restarts a container,
+//   or cancels a pending reboot. The watchdogs own their own state; this endpoint reports it.
+//
+//   Absent counters are reported quiet, not alarming.
+//       A watchdog that has not yet written state reads as zero rather than unknown, so a
+//       fresh boot does not light the page up with false strikes.
+//
+//   Thresholds fall back to the shipped defaults.
+//       Every vv_wd_scalar() lookup has a ?: default, so a master.conf that is mid-edit or
+//       missing a key still yields a coherent payload instead of comparing counters against
+//       zero and declaring everything critical.
+//
+//   Remote collection degrades per node — one unreachable partner drops that node's card and
+//   leaves the local host and every other partner intact.
+//
+// REQUEST
+//   GET, no parameters
+//
+// RESPONSE
+//   vv_wd_all() verbatim — per-node watchdog state plus the resolved threshold set
+//
+// DEPENDS ON
+//   include/watchdog.php   vv_wd_all()
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/watchdog.php';
 echo json_encode(vv_wd_all());
diff --git a/Plugin/unraid/api/webhook.php b/Plugin/unraid/api/webhook.php
index af798a0..fd642d7 100644
--- a/Plugin/unraid/api/webhook.php
+++ b/Plugin/unraid/api/webhook.php
@@ -1,6 +1,96 @@
 <?php
-// Receives Sonarr/Radarr/Lidarr Download events. Fires upgrade_webhook_handler.sh
-// in the background and returns 200 immediately — arr does not wait on the push.
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
+// PURPOSE
+//   Arr download webhook. Receives Sonarr, Radarr and Lidarr Download events and fires
+//   upgrade_webhook_handler.sh against the affected folder so the partner learns about the
+//   new file immediately rather than at the next scheduled sync.
+//
+// OPERATIONAL MODEL
+//   Accept, dispatch, return. The handler is backgrounded and the response goes out at once,
+//   because an arr that is made to wait on a cross-host push will time the webhook out and
+//   log it as a failure — and it retries on a schedule that would compound the problem.
+//
+//   200 therefore means accepted, not propagated. The handler's own log is the record of what
+//   happened; this endpoint cannot report it and does not pretend to.
+//
+//   The reason for immediacy is search suppression: until the partner knows a file exists, it
+//   will keep searching for it. The scheduled sync would close that gap eventually; the
+//   webhook closes it in seconds.
+//
+// DESIGN PRINCIPLES
+//   The arr type is inferred from the payload's shape, not from a parameter.
+//       series.path means Sonarr, movie.folderPath means Radarr, artist.path means Lidarr.
+//       Each app names its own field, so the structure identifies the sender without a query
+//       string the user could get wrong when configuring three separate applications.
+//
+//   Test events are answered with instructions.
+//       Sonarr's "Test" button gets a message telling the user to configure On Download,
+//       because a bare success there is exactly what leads to a webhook that is connected and
+//       wired to nothing.
+//
+//   Every non-Download event is acknowledged and skipped.
+//       ok:true with the event name, never an error. An arr that receives an error status
+//       retries and eventually disables the webhook, so events this endpoint does not care
+//       about have to be accepted rather than rejected.
+//
+//   Fires on all Download events, not just upgrades.
+//       New grabs and upgrades both need propagating; distinguishing them would suppress
+//       exactly the first-time grabs the partner is most likely to duplicate.
+//
+//   The kill switch is read per request.
+//       DOWNLOAD_WEBHOOK_ENABLED is checked from conf on every call, so turning it off takes
+//       effect without touching the arr configuration — and the response says it was skipped
+//       rather than silently doing nothing.
+//
+// OPERATIONAL SAFEGUARDS
+//   POST only, with a real status code.
+//       405 for the wrong method, 400 for unparseable or unrecognised bodies. Status codes
+//       matter more here than elsewhere in this layer: the caller is a machine that changes
+//       its retry behaviour based on them.
+//
+//   The path is validated and then escaped.
+//       Must be absolute, no '..', no null bytes or newlines — then passed through
+//       escapeshellarg() into the handler invocation. The arr type is likewise escaped even
+//       though it is one of three literals this file chose itself.
+//
+//   Both the empty-path and unrecognised-structure cases are handled explicitly.
+//       A payload with a recognised key holding an empty value is rejected separately from
+//       one whose structure is unknown, because those are different misconfigurations.
+//
+//   A missing handler is reported as a server error, not swallowed.
+//       500 with a named error, so a partial deploy is visible in the arr's own webhook log
+//       rather than appearing to succeed forever.
+//
+//   Output is appended to a dedicated log with stdin detached, so a backgrounded handler
+//   cannot hold the request's file descriptors open.
+//
+//   Known gap: this endpoint authenticates nothing.
+//       master.conf carries WEBHOOK_SECRET, and the standalone Node listener on WEBHOOK_PORT
+//       validates it — this WebGUI-hosted path does not. Anyone who can reach the URL can
+//       make it run the handler against any absolute path that passes validation. Injection
+//       is not the risk (the path is escaped); triggering work is. Left as-is deliberately
+//       rather than fixed in passing: adding a secret check here would break whichever arr
+//       instances are currently configured against this URL, and that is a change to make
+//       with the arr configs open, not as part of a documentation pass. See also the CSRF
+//       note in README-unraid.md.
+//
+// REQUEST
+//   POST <arr webhook JSON body>
+//        eventType=Test        → connection acknowledgement
+//        eventType=Download    → dispatches the handler
+//        any other eventType   → acknowledged and skipped
+//
+// RESPONSE
+//   {"ok":true,"arr":"sonarr|radarr|lidarr","path":"…"}   dispatched
+//   {"ok":true,"message":"Webhook connected — …"}         Test
+//   {"ok":true,"skipped":"<event>|DOWNLOAD_WEBHOOK_ENABLED=false"}
+//   {"ok":false,"error":…} with 405 / 400 / 500 as appropriate
+//
+// DEPENDS ON
+//   include/config.php   vv_conf_vars(), SCRIPTS_DIR
+//   Media/upgrade_webhook_handler.sh   the backgrounded handler
+//   master.conf          DOWNLOAD_WEBHOOK_ENABLED
+// ═══════════════════════════════════════════════════════════════════════════════════════════════
 header('Content-Type: application/json');
 require_once dirname(__DIR__) . '/include/config.php';
 
diff --git a/Plugin/unraid/include/confform.php b/Plugin/unraid/include/confform.php
index f6150cf..5f94c5e 100644
--- a/Plugin/unraid/include/confform.php
+++ b/Plugin/unraid/include/confform.php
@@ -282,7 +282,23 @@ function vv_conf_write_changes(array $changes): array {
                 ) ?? $raw;
             }
         }
-        $results[$file] = vv_write_conf_raw($file, $raw);
+        // Only the scalar path escapes its value; the array, array_single and assoc_array
+        // paths splice the caller's text into the file verbatim, and the type comes from the
+        // request. Every script sources these files, so the result is parsed before it is
+        // allowed to replace a working conf.
+        $results[$file] = vv_conf_syntax_ok($raw) && vv_write_conf_raw($file, $raw);
     }
     return $results;
 }
+
+// bash -n against a private temp copy. Returns true when the content parses as a sourceable
+// conf, false otherwise — never writes anything itself.
+function vv_conf_syntax_ok(string $content): bool {
+    $tmp = tempnam(sys_get_temp_dir(), 'vvconf');
+    if ($tmp === false) return true;   // cannot check — do not block the write
+    file_put_contents($tmp, $content);
+    $out = []; $rc = 0;
+    exec('bash -n ' . escapeshellarg($tmp) . ' 2>&1', $out, $rc);
+    @unlink($tmp);
+    return $rc === 0;
+}
diff --git a/Plugin/unraid/include/config.php b/Plugin/unraid/include/config.php
index 1813d56..9e03da7 100644
--- a/Plugin/unraid/include/config.php
+++ b/Plugin/unraid/include/config.php
@@ -476,7 +476,12 @@ function vv_auto_create_api_key(string $hostId, string $confFile): array {
     if (!file_exists($script)) {
         return ['ok' => false, 'error' => 'unraid_api_key_renew.sh not found'];
     }
-    exec('bash ' . escapeshellarg($script) . ' 2>&1', $out, $rc);
+    // set_time_limit() does not cover exec() time on Linux, so the bound has to be external —
+    // otherwise a stalled unraid-api call holds a php-fpm worker open indefinitely.
+    exec('timeout 120 bash ' . escapeshellarg($script) . ' 2>&1', $out, $rc);
+    if ($rc === 124) {
+        return ['ok' => false, 'error' => 'Key renewal timed out after 120s'];
+    }
     if ($rc !== 0) {
         $msg = implode(' ', array_filter(array_map('trim', $out)));
         return ['ok' => false, 'error' => $msg ?: 'Script failed'];
diff --git a/Plugin/unraid/include/scheduler.php b/Plugin/unraid/include/scheduler.php
index a250749..539db26 100644
--- a/Plugin/unraid/include/scheduler.php
+++ b/Plugin/unraid/include/scheduler.php
@@ -579,7 +579,9 @@ function vv_conf_flag_set(string $name, bool $value): bool {
         $content, -1, $count
     );
     if (!$count) return false;
-    return file_put_contents($confPath, $new) !== false;
+    // tmp+rename — every script sources master.conf, so a truncated write here is a
+    // system-wide outage, not a lost toggle.
+    return vv_write_conf_raw('master.conf', $new);
 }
 
 // Comment or uncomment a script's line in the first master.conf array that contains it.
@@ -607,7 +609,9 @@ function vv_conf_toggle_script(string $rel, bool $enable): bool {
     }
     unset($line);
     if (!$changed) return true;
-    return file_put_contents($confPath, implode('', $lines)) !== false;
+    // tmp+rename — every script sources master.conf, so a truncated write here is a
+    // system-wide outage, not a lost toggle.
+    return vv_write_conf_raw('master.conf', implode('', $lines));
 }
 
 // Parse an orchestrator script to find which child scripts it calls.