Correct and extend folder docs for Docker Essentials, Watchdogs, Media and Arrs Stack

The docs had drifted from the scripts — a script that no longer exists, three wrong variable names, a reversed run order, and seven scheduled scripts that were never documented at all.
2026-08-01 22:59:07 -04:00
parent c377ddfcca
commit 8a2707ee37
6 changed files with 331 additions and 30 deletions
@@ -100,3 +100,43 @@ syncs between them.
 | `media_shares_permissions.sh` | Apply `nobody:users` ownership + correct permissions to all media shares | Daily — runs first |
 | `media_cleaner.sh` | Remove junk files (two profiles: `anime` + `media`) | Daily — runs before arr cleanup |
 | `play_state_sync.sh` | Sync watched/played state + resume positions across Emby + Jellyfin | Every 30 min |
+
+---
+
+## ━━━ THE ctime INVARIANT — READ BEFORE CHANGING PERMISSIONS ━━━
+
+`media_shares_permissions.sh` applies every pass **conditionally** — it touches only entries
+whose owner or mode is actually wrong. That is not an optimisation, and it must stay that way.
+
+`chown` and `chmod` rewrite an inode's ctime **even when the value does not change**. A
+blanket pass would therefore restamp every file in the library every night.
+
+The arr cleanup scripts (`sonarr_cleanup.sh`, `radarr_cleanup.sh`, `lidarr_cleanup.sh`) gate
+orphan deletion on ctime. mtime cannot substitute: an import preserves the release's original
+timestamp, so mtime says nothing about when a file arrived here. Measured 2026-07-27 — of 400
+files imported that week, **all 400 had mtimes over 7 days old, one of them 9613 days.**
+
+So:
+
+```
+  blanket chown/chmod  →  every ctime resets to today
+                       →  no file ever appears older than *_ORPHAN_AGE
+                       →  orphan collection silently stops
+                       →  nothing errors, nothing warns, disk just fills
+```
+
+**The failure is invisible.** No script fails, no notification fires. The only symptom is
+orphans quietly accumulating until a pool fills — which is exactly how the 755 GB / 89%-full
+cache pool incident happened.
+
+Two rules follow, and both are load-bearing:
+
+1. **`media_shares_permissions.sh` passes stay conditional.** Making any of them unconditional
+   breaks orphan collection ecosystem-wide.
+2. **`Tools/bulk_permissions_repair.sh` is unconditional by design** — it exists to repair
+   known-wrong paths where correctness beats preserving a clock. That is precisely why it is a
+   manual, targeted tool and not scheduled. Pointing it at a whole media root pauses orphan
+   collection there for `*_ORPHAN_AGE` days.
+
+Both scripts' headers carry this warning too. If you are reading this because you are about to
+"simplify" the permissions job, this is the thing that breaks.