Update headers on today's arr-caching changes

Comment-only. Headers on the scripts touched during today's caching work
(cache-first fetches, write-through per-item cache, single-walk
consolidation, movieFile-embedded fix) still described pre-change
behavior. Also brought common.sh's top-level cache doc block current --
it was written for the single-consumer 2026-07-16 state and didn't
mention the tmpfs move, the write guard, or the 15+ consumers that now
go through it.

Arrs_Stack/arr_sync.sh

@@ -10,6 +10,12 @@
 # rsync in the weekly sync window: once arrs agree on what to track, rsync
 # spreads the actual files.
 #
+# The LOCAL side of each sync (_local_library()) is cache-first (2026-07-17) — comes from
+# the shared tracked-data cache via arr_get_tracked_data(), fresh (kept warm every 30min by
+# arr_cache_prefill.sh), live fetch as fallback. The REMOTE side (_remote_library()) is
+# unaffected — that cache is per-host by design, so a remote node's library is always
+# fetched live here.
+#
 # ==============================================================================================
 # OPERATIONAL MODEL
 # ==============================================================================================

Arrs_Stack/lidarr_cleanup.sh

@@ -20,6 +20,16 @@
 # Only escalates to the scary abort-and-notify when the count is genuinely low AND nothing
 # is actively rescanning.
 #
+# Cache-first, both layers (2026-07-17). The artist list itself comes from the shared
+# tracked-data cache via arr_get_tracked_data() — fresh (kept warm every 30min by
+# arr_cache_prefill.sh), live fetch as fallback. The per-artist trackFile walk below still
+# always fetches live (that's the actual disk-truth this script's delete decisions depend
+# on), but write-throughs its result to arr_item_cache_write() so lidarr_missing_art.sh,
+# running later in the same nightly window, can read it instead of repeating the same walk.
+# The filesystem is walked once per run, not twice — classification records which paths are
+# eligible for deletion as it goes, and the delete pass (once the size-threshold check below
+# passes) just acts on that list instead of re-walking and re-classifying the whole tree.
+#
 # ==============================================================================================
 # OPERATIONAL MODEL
 # ==============================================================================================

Arrs_Stack/lidarr_missing_art.sh

@@ -24,6 +24,14 @@
 # tags or renames media files. Only writes missing artwork files to existing
 # album/artist directories.
 #
+# Cache-first, both layers (2026-07-17). The artist list comes from the shared tracked-data
+# cache via arr_get_tracked_data() — fresh (kept warm every 30min by arr_cache_prefill.sh),
+# live fetch as fallback. The per-artist track-file walk used to build the album→directory
+# map now reads lidarr_cleanup.sh's write-through cache first (arr_get_cached_items() —
+# lidarr_cleanup.sh runs earlier in the same nightly window and already does this exact
+# walk for its own cleanup decisions), falling back to its own live per-artist walk only if
+# that cache is missing or from outside the current window.
+#
 # ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================

Arrs_Stack/lidarr_release_fixer.sh

@@ -34,6 +34,11 @@
 # RefreshArtist is batched — one per artist, even if multiple albums were fixed.
 # Lidarr handles the post-refresh rescan and import automatically.
 #
+# Cache-first artist list (2026-07-17) — comes from the shared tracked-data cache via
+# arr_get_tracked_data(), fresh (kept warm every 30min by arr_cache_prefill.sh), live fetch
+# as fallback. Everything below (per-album release lookups) still fetches live — that data
+# isn't part of what's cached.
+#
 # ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================

Arrs_Stack/playback_aware_lidarr_discovery.sh

@@ -33,6 +33,11 @@
 #   8. Score candidates: affinity + breadth + popularity + quality
 #   9. Take top MAX_ADDS above threshold → add to Lidarr
 #
+# Step 7's "already in Lidarr" check reads the shared tracked-data cache via
+# arr_get_tracked_data() (cache-first, live fallback, 2026-07-17) instead of a live fetch —
+# this runs weekly right after arr_full_rescan.sh, so it's reading the genuine post-rescan
+# snapshot arr_full_rescan.sh just wrote.
+#
 # ==============================================================================================
 # SCORING MODEL
 # ==============================================================================================

Arrs_Stack/playback_aware_radarr_discovery.sh

@@ -33,6 +33,11 @@
 #   7. Score candidates: breadth + TMDB rating + vote count
 #   8. Take top MAX_ADDS above threshold → add to Radarr
 #
+# Step 6's "already in Radarr" check reads the shared tracked-data cache via
+# arr_get_tracked_data() (cache-first, live fallback, 2026-07-17) instead of a live fetch —
+# this runs weekly right after arr_full_rescan.sh, so it's reading the genuine post-rescan
+# snapshot arr_full_rescan.sh just wrote.
+#
 # ==============================================================================================
 # SCORING MODEL
 # ==============================================================================================

Arrs_Stack/playback_aware_sonarr_discovery.sh

@@ -37,6 +37,11 @@
 #  11. Take top MAX_ADDS above threshold
 #  12. Get TVDB ID via TMDB external_ids → Sonarr lookup → add + trigger SeriesSearch
 #
+# Step 9's "already in Sonarr" check reads the shared tracked-data cache via
+# arr_get_tracked_data() (cache-first, live fallback, 2026-07-17) instead of a live fetch —
+# this runs weekly right after arr_full_rescan.sh, so it's reading the genuine post-rescan
+# snapshot arr_full_rescan.sh just wrote.
+#
 # ==============================================================================================
 # SCORING MODEL
 # ==============================================================================================

Arrs_Stack/radarr_cleanup.sh

@@ -18,6 +18,17 @@
 # false-alarm abort. Mirrors the same fix built for lidarr_cleanup.sh 2026-07-16 after
 # a whole-library rescan there made trackFileCount read 22% of normal mid-scan.
 #
+# Cache-first movie list, no per-movie API calls at all (2026-07-17). The movie list comes
+# from the shared tracked-data cache via arr_get_tracked_data() — fresh (kept warm every
+# 30min by arr_cache_prefill.sh), live fetch as fallback. Radarr is structurally different
+# from Lidarr/Sonarr here: its movie list already embeds movieFile.path directly on every
+# hasFile=true entry (confirmed live, zero exceptions across the full library), so there's
+# no separate per-movie moviefile?movieId=X walk needed at all — what used to be up to 2896
+# individual API calls is now a jq filter over data already in hand. The filesystem is
+# walked once per run, not twice — classification records which paths are eligible for
+# deletion as it goes, and the delete pass (once the size-threshold check below passes)
+# just acts on that list instead of re-walking and re-classifying the whole tree.
+#
 # ==============================================================================================
 # OPERATIONAL MODEL
 # ==============================================================================================

Arrs_Stack/radarr_tmdb_removed.sh

@@ -10,6 +10,10 @@
 # or downloaded. Most are announced-but-never-released films delisted before
 # release.
 #
+# Cache-first movie list (2026-07-17) — comes from the shared tracked-data cache via
+# arr_get_tracked_data(), fresh (kept warm every 30min by arr_cache_prefill.sh), live fetch
+# as fallback.
+#
 # ==============================================================================================
 # OPERATIONAL MODEL
 # ==============================================================================================

Arrs_Stack/sonarr_cleanup.sh

@@ -19,6 +19,17 @@
 # lidarr_cleanup.sh 2026-07-16 after a whole-library rescan there made trackFileCount
 # read 22% of normal mid-scan.
 #
+# Cache-first, both layers (2026-07-17). The series list itself comes from the shared
+# tracked-data cache via arr_get_tracked_data() — fresh (kept warm every 30min by
+# arr_cache_prefill.sh), live fetch as fallback. The per-series episodefile walk below still
+# always fetches live (that's the actual disk-truth this script's delete decisions depend
+# on), but write-throughs its result to arr_item_cache_write() for any future script that
+# needs Sonarr's per-episode data — no second consumer exists yet, unlike Lidarr's
+# lidarr_missing_art.sh, but the data's there once one does. The filesystem is walked once
+# per run, not twice — classification records which paths are eligible for deletion as it
+# goes, and the delete pass (once the size-threshold check below passes) just acts on that
+# list instead of re-walking and re-classifying the whole tree.
+#
 # ==============================================================================================
 # OPERATIONAL MODEL
 # ==============================================================================================

Arrs_Stack/sonarr_tvdb_removed.sh

@@ -9,6 +9,10 @@
 # status="deleted" — they generate health errors and can never be monitored
 # or downloaded.
 #
+# Cache-first series list (2026-07-17) — comes from the shared tracked-data cache via
+# arr_get_tracked_data(), fresh (kept warm every 30min by arr_cache_prefill.sh), live fetch
+# as fallback.
+#
 # ==============================================================================================
 # OPERATIONAL MODEL
 # ==============================================================================================