Fill the single missing section in three scripts that had everything else

AI/ai_token_sync.sh

@@ -30,6 +30,31 @@
 # fetches its own data controls its own freshness rather than depending on the partner's cron.
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# A missing file means unknown, never zero.
+#   The whole point of the tab reporting "not collected here" is that it is a different claim
+#   from "this partner spent nothing". If a partner is dark, unreachable or has never run a turn,
+#   there is simply no cache file, and the reader is expected to say so rather than render a 0
+#   that looks like a measurement.
+#
+# The reader pulls; nobody pushes.
+#   conf_sync.sh pushes as well, because a partner that cannot reach us still needs our
+#   credentials. Nothing here is needed by anyone else, so a host that wants fleet totals fetches
+#   them and owns its own freshness instead of depending on someone else's cron having run.
+#
+# RAM, not flash.
+#   The cache lands in tmpfs. It is a copy of a file that already exists on the partner and is
+#   rebuilt on the next pass, so writing it to flash would cost wear for something that is never
+#   worth surviving a reboot.
+#
+# Same shape as conf_sync.sh, deliberately.
+#   Resolve over Tailscale, scp one small file into a tmpfs cache, let a missing file mean
+#   unknown. A second transport pattern for a second small file would be a second set of
+#   failure modes to learn.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #

Plugin/unraid/System_Essentials/pcie_aer_quiet.sh

@@ -24,6 +24,22 @@
 # list and reboot.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# One pass over PCIE_QUIET_DEVICES at array start. Each address is looked up under
+# /sys/bus/pci/devices, checked against the guards below, and removed through the kernel's own
+# per-device remove attribute. Nothing is masked and no kernel parameter is set.
+#
+# Idempotent, and silent when there is nothing to do. An address that is already gone is not an
+# error — that is the normal state on every array start after the first within one boot.
+#
+# Reapplied every array start rather than once, because a reboot re-enumerates the bus and the
+# devices come back. That is also the undo: clear PCIE_QUIET_DEVICES and reboot.
+#
+# PCIE_QUIET_ENABLED gates the whole run before any device is touched.
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #

Rsync/media_seed.sh

@@ -35,6 +35,25 @@
 # progress in the UI, and lets it be re-run or cancelled without touching onboard.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# One share at a time, in DAILY_SYNC_SHARES order, each handed to Rsync/rsync.sh --seed. The
+# transfer itself, its bandwidth cap and its resume behaviour are all rsync.sh's — this script
+# decides what to seed and in what order, never how.
+#
+# Sequential on purpose. The cap that matters is DEFAULT_RSYNC_OPTS' --bwlimit, which is a limit
+# per rsync rather than per host; running shares in parallel would multiply it by the number of
+# shares and saturate the link the rest of the ecosystem is still using.
+#
+# Refuses before it starts rather than partway. RSYNC_ENABLED must be true and DAILY_SYNC_SHARES
+# must be non-empty, both checked up front — a multi-week transfer is the wrong place to
+# discover that the global gate was off.
+#
+# Nothing waits on this. Phase 3 runs after the partnership is already established, so a seed
+# that is still copying weeks later blocks no flag, no status card and no job record.
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #