A CLI tool has runtime modes, not a request

2026-08-25 16:42:39 -04:00
parent 1f9915f074
commit d25b147a56
2 changed files with 25 additions and 1 deletions
@@ -9,6 +9,19 @@
 //   Onboard calls this on the mirror after deploying the owner's stack, so those containers land
 //   somewhere that says whose they are instead of scattering into the mirror's own groups.
 //
+// OPERATIONAL MODEL
+//   Create-or-update, never replace. The named folder is found in folder.view3 if it exists and
+//   is amended in place; only its absence causes one to be created. Every other folder in the
+//   file, and every container already filed elsewhere, is left exactly as it was — this is one
+//   shelf in someone else's cupboard.
+//
+//   Called during onboard on the mirror, after the owner's stack has been deployed there, so the
+//   containers exist by the time anything tries to file them.
+//
+//   The icon is resolved separately from the folder and never gates it. --icon-only performs
+//   just that lookup and prints the URL, which is how onboard asks for it without writing
+//   anything.
+//
 // DESIGN PRINCIPLES
 //   The name comes from master.conf, never from a second source.
 //       HOST2="unRAID-Jayred36" → "Jayred36-Fallback". The convention already existed by hand as
@@ -39,7 +52,7 @@
 //   --dry-run prints the resulting folder and writes nothing.
 //   Icon resolution failing never blocks the folder: no image is a cosmetic loss, no folder is not.
 //
-// REQUEST
+// RUNTIME MODES
 //   fallback_folder.php --host=HOST2 [--containers=A,B,C] [--icon=URL] [--dry-run]
 //   fallback_folder.php --host=HOST2 --icon-only        resolve and print the icon URL, write nothing
 //