Say how the spawned tools are actually invoked

Plugin/unraid/Tools/ai_rpc.php

@@ -42,6 +42,11 @@
 //       stdin is an untrusted stream from another process. A malformed or endless payload must
 //       fail as a bad request, not as an out-of-memory.
 //
+// RUNTIME MODES
+//   Not invoked by hand. include/ai_rpc.php opens an SSH session to the owner and runs this
+//   file with the request as JSON on stdin; the response is JSON on stdout. There are no flags
+//   and no arguments — the action, the profile and the payload all arrive in the request body.
+//
 // DEPENDS ON
 //   include/ai_actions.php  vv_ai_dispatch() — the shared handlers
 //   include/config.php      vv_ai_is_owner()

Plugin/unraid/Tools/api_cache_writer.php

@@ -66,6 +66,13 @@
 //   VV_CACHE_DIR/arrs.json      consumed by api/arrs.php
 //   stdout                      one timing line, captured into the job log
 //
+// RUNTIME MODES
+//   api_cache_writer.php
+//       Build both payloads and write them to the cache. Takes no arguments.
+//
+//   Run every minute by Tools/api_cache_writer.sh, which is the cron entry — this file is the
+//   work, that one is the schedule, the lock and the log.
+//
 // DEPENDS ON
 //   include/monitor.php, include/common.php, include/unraid_api.php,
 //   include/vms.php, include/docker_folders.php, include/arrs.php

Plugin/unraid/Tools/mirror_folders.php

@@ -63,6 +63,22 @@
 //                                  "unfiled":[…]}
 //   import: one line per folder written, then a count
 //
+// RUNTIME MODES
+//   mirror_folders.php --export
+//       Print this host's folder layout as JSON, for the owner to compute a plan from.
+//
+//   mirror_folders.php --import
+//       Read a layout on stdin and apply it to this host's folder.view3.
+//
+//   mirror_folders.php --containers=<csv>
+//       Restrict the operation to these container names.
+//
+//   mirror_folders.php --fallback-only=<csv>
+//       Place only these into the partner's fallback folder, leaving the rest where they are.
+//
+//   --dry-run
+//       Compute and report the plan without writing folder.view3. Combines with any of the above.
+//
 // DEPENDS ON
 //   /boot/config/plugins/folder.view3/docker.json   the third-party layout, optional on import
 //   SCRIPTS_DIR/docker_folders.json                 Varaverk's own layout — what the card reads

Plugin/unraid/Tools/node_chat_receive.php

@@ -5,12 +5,25 @@
 //   vv_nc_deliver(), with the record on stdin.
 //
 // OPERATIONAL MODEL
-//   php node_chat_receive.php --channel=<id>          record on stdin, one JSON object
-//   php node_chat_receive.php --flush                 retry this host's own undelivered spool
-//
 //   Exit 0 means stored. The sender treats anything else as undelivered and spools for retry, so
 //   a non-zero exit here is a message that will arrive later rather than one that is lost.
 //
+//   Two jobs in one file because they are two halves of the same contract: --channel takes what
+//   a partner is delivering now, --flush pushes what this host failed to deliver earlier. A node
+//   is both a receiver and a sender, and splitting them would mean two files that must agree on
+//   the same spool layout.
+//
+// DESIGN PRINCIPLES
+//   The exit code is the receipt, and it is the only one.
+//       There is no acknowledgement message and no reply body. The sender is an SSH command that
+//       already has an exit status, so inventing a second channel to say the same thing would
+//       give the two ways to disagree.
+//
+//   Refusing is cheaper than being wrong.
+//       An unparseable record, an unknown channel or a failed write all exit non-zero and leave
+//       the message in the sender's spool. A retry costs one SSH round trip; a message accepted
+//       and dropped is gone with nothing recording that it existed.
+//
 // OPERATIONAL SAFEGUARDS
 //   Reached only over SSH with a key this mesh installed, so the caller already has root. This
 //   file therefore validates shape, not authority — there is no privilege here to protect that
@@ -22,6 +35,12 @@
 //   Storage is append-and-trim through vv_nc_append(), which is idempotent on message id — a
 //   retry of something that already landed is a no-op rather than a duplicate.
 //
+// RUNTIME MODES
+//   Not invoked by hand — the sending node's vv_nc_deliver() runs it over SSH.
+//
+//   php node_chat_receive.php --channel=<id>   store one JSON record, read from stdin
+//   php node_chat_receive.php --flush          retry this host's own undelivered spool
+//
 // DEPENDS ON
 //   include/node_chat.php   vv_nc_append(), vv_nc_channel(), vv_nc_flush_spool()
 // ═══════════════════════════════════════════════════════════════════════════════════════════════