Document the PHP api layer and fix what documenting it exposed

Writing down what each endpoint actually guarantees made the places it
didn't obvious — shell arguments reaching a crontab or a bash -c
unescaped, master.conf written without tmp+rename, and conf edits that
could be saved without ever being parsed.

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();