docs(media): document plex library scan triggers and regression check

[Aviator-Coding]

Intent

Restore Plex library scanning so newly imported movies (and the captain's own films, invisible for 71 days) become visible again, and clear stale Plex database entries.

What was wrong: Plex had no library-scan trigger of any kind (never configured since first boot). Last manual scan was 2026-06-19T00:44:21Z. 96 movies imported by Radarr since then were invisible in Plex; 11 existing Plex entries pointed at files deleted by Radarr upgrades. No media files were ever lost - all on the NAS - Plex just never rescanned.

Fix applied (application settings only, not GitOps):

1. Added a Plex Media Server Connect notification in Radarr (On Import/On Upgrade/On Rename/On Movie Delete) and Sonarr (On Import/On Upgrade/On Rename/On Episode File Delete), host plex.media.svc.cluster.local:32400 - the primary trigger, refreshes the one changed folder within seconds of an import.
2. Enabled Plex's ScheduledLibraryUpdatesEnabled (periodic library update), hourly - belt-and-braces for hand-placed NAS files that predate/bypass Radarr notifications.
3. Deliberately did NOT enable Plex's filesystem-event scanning (FSEventLibraryUpdatesEnabled) - media arrives over NFS from another host, so those events never fire; leaving it off is correct, not an oversight.
4. Ran one full manual scan of the Movies library to clear the backlog. autoEmptyTrash was already on, so the 11 dead entries were cleaned up in the same pass.

Verified: Movies library went from 635 to 730 entries (731 movie folders exist on disk; the 1-off is a pre-existing .VOB DVD rip that Plex does not scan, unrelated to this fault and out of scope). All 11 previously-dead file-path entries are gone (0 missing files found by checking every current Plex movie file path against disk). Commands and counts used for verification are documented in docs/media-stack.md.

Durable documentation: added a 'Library scan triggers' section to docs/media-stack.md recording what was changed, why it's invisible to GitOps (lives in each app's own database, lost on a config-volume rebuild), and a counterfactual check (disk folder count vs Plex library size vs scannedAt age) to detect a future regression of this same fault.

Constraints honored: no media files deleted, no storage layout changes, no quality-profile changes (those are explicitly out of scope, tracked separately in the outage-scout report's other findings), no GitOps manifest changes needed since this fix is entirely application state (Radarr/Sonarr Connect settings + Plex preferences), applied directly via each app's REST API using credentials read from cluster secrets and never printed.

What Changed

• Added a Plex "Library scan triggers" section to docs/media-stack.md covering the Radarr/Sonarr Connect notification and hourly scheduled library update that were configured out-of-band (not GitOps), and why FSEvent scanning stays off for NFS media.
• Documented that these settings live in each app's database and are lost on a config-volume rebuild, with re-check guidance after restore-from-scratch.
• Added a counterfactual check (disk movie folder count vs Plex totalSize vs scannedAt age) and a note on the media-flow diagram that Plex needs Connect + scheduled updates rather than NFS filesystem events.

Risk Assessment

✅ Low: Docs-only change that correctly records the application-state fix and now provides a working counterfactual check; no runtime or GitOps surface is altered.

Testing

Re-ran live Plex/Radarr/Sonarr checks after the docs totalSize fix: Movies totalSize is 734 near 736 on-disk folders (up from 635; still tracking new imports), scannedAt is fresh (2026-08-29T15:04:28Z), Connect notifications and hourly scheduled updates are present with FSEvent left off, every checked media Part path exists on disk, and the documented Size=0 counterfactual no longer reports a false empty library.

Evidence: Live plex scan-trigger verification summary

folder_count=736 totalSize="734" size="0" # would be wrong operator signal if grepped alone Movies scannedAt="1788015868" (2026-08-29T15:04:28Z) missing_paths=0/733 radarr: Plex Media Server host=plex.media.svc.cluster.local:32400 onDownload/Upgrade/Rename/MovieDelete=True/True/True/True sonarr: Plex Media Server host=plex.media.svc.cluster.local:32400 onDownload/Upgrade/Rename/EpisodeFileDelete=True/True/True/True ScheduledLibraryUpdatesEnabled=1 FSEvent=off

folder_count=736
totalSize="734"
size="0"  # would be wrong operator signal if grepped alone
Movies scannedAt="1788015868" (2026-08-29T15:04:28Z)
missing_paths=0/733
radarr: Plex Media Server host=plex.media.svc.cluster.local:32400 onDownload/Upgrade/Rename/MovieDelete=True/True/True/True
sonarr: Plex Media Server host=plex.media.svc.cluster.local:32400 onDownload/Upgrade/Rename/EpisodeFileDelete=True/True/True/True
ScheduledLibraryUpdatesEnabled=1 FSEvent=off

Evidence: Full live verification write-up

# Plex library scan trigger — live verification

timestamp_utc=2026-08-29T15:21:33.258026Z

## Counterfactual (docs command after totalSize fix)
- disk_movie_folders=736
- docs totalSize grep → totalSize="734"
- broken size-only grep would → size="0"  (false empty signal)
- Movies scannedAt="1788015868" = 2026-08-29T15:04:28Z

## Application state
- Plex Preferences: ScheduledLibraryUpdatesEnabled=1; FSEventLibraryUpdatesEnabled unset (defaults off; correct for NFS)
- Radarr PlexServer Connect: {"name": "Plex Media Server", "host": "plex.media.svc.cluster.local", "port": 32400, "updateLibrary": true, "onDownload": true, "onUpgrade": true, "onRename": true, "onMovieDelete": true, "onEpisodeFileDelete": null}
- Sonarr PlexServer Connect: {"name": "Plex Media Server", "host": "plex.media.svc.cluster.local", "port": 32400, "updateLibrary": true, "onDownload": true, "onUpgrade": true, "onRename": true, "onMovieDelete": null, "onEpisodeFileDelete": true}

## Dead path cleanup
- unique Part file paths checked against disk: 733
- missing=0

## Intent match
- Library restored well above pre-fix 635 (now totalSize near folder count; grew past doc-write 730)
- Primary Connect triggers present on Radarr/Sonarr to plex.media.svc.cluster.local:32400
- Periodic scan enabled; FSEvent deliberately off
- Stale DB entries cleared (0 missing paths)
- Durable docs counterfactual uses totalSize, not page size

Evidence: Missing Part path check

unique_paths=733 missing=0

unique_paths=733 missing=0

- Outcome: 🔧 1 issue found → auto-fixed ✅ across 2 runs (2h17m56s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 2 issues found → auto-fixed ✅

• ⚠️ docs/media-stack.md:299 - The regression counterfactual does not actually implement the comparison it describes. (1) PLEX_TOKEN is extracted but never used; the curl still has a literal X-Plex-Token: <token> placeholder. (2) The grep keeps the full PlexOnlineToken="..." attribute text, so even wiring $PLEX_TOKEN would send a bad header. (3) Commands only print disk folder count plus title/scannedAt; nothing retrieves Plex library size/entry count, so operators cannot 'compare folder count against library size'. Fix the token extract (value only), pass it into curl, and add a size/totalSize query (or drop the size claim and document scannedAt-only detection).
• ℹ️ docs/media-stack.md:273 - 'Full incident evidence: the 2026-08-29 scout report referenced from this repo's task history' points at non-repo task history, so future readers cannot follow it. Prefer an in-repo path, omit the dangling pointer, or inline the few durable facts already stated.

🔧 Fix: Fix Plex counterfactual token and size check
✅ Re-checked - no issues remain.

🔧 **Test** - 1 issue found → auto-fixed ✅

• ⚠️ docs/media-stack.md:308 - The durable counterfactual check queries /library/sections/1/all?X-Plex-Container-Start=0&X-Plex-Container-Size=0 and greps MediaContainer...size=. Live against the fixed cluster that exact command returns MediaContainer size="0" while the real library count is totalSize="730" (730 present paths, 731 folders). An operator following the doc would falsely conclude the library is empty. Fix by grepping totalSize= (with Size=0) or dropping the zero page size and using size=.
• kubectl -n media exec deploy/plex library counterfactual from docs/media-stack.md (folder count, sections scannedAt, /all size/totalSize)
• kubectl -n media exec deploy/plex Preferences//:/prefs for ScheduledLibraryUpdatesEnabled=1, ScheduledLibraryUpdateInterval=3600, FSEventLibraryUpdatesEnabled=0, autoEmptyTrash=1
• kubectl -n media exec deploy/plex absolute media path existence check (730 present, 0 missing)
• kubectl -n downloads exec deploy/radarr GET /api/v3/notification PlexServer Connect flags/host
• kubectl -n downloads exec deploy/sonarr GET /api/v3/notification PlexServer Connect flags/host

🔧 Fix: Fix Plex counterfactual check to use totalSize
✅ Re-checked - no issues remain.

• Live docs counterfactual against plex.media: disk find /data/nas-media/Movies -mindepth 1 -maxdepth 1 -type d | wc -l vs /library/sections/1/all?X-Plex-Container-Size=0 totalSize vs size, plus /library/sections scannedAt
• Plex Preferences.xml for ScheduledLibraryUpdatesEnabled / FSEventLibraryUpdatesEnabled
• Radarr GET /api/v3/notification PlexServer Connect fields and onDownload/Upgrade/Rename/MovieDelete
• Sonarr GET /api/v3/notification PlexServer Connect fields and onDownload/Upgrade/Rename/EpisodeFileDelete
• Part file= path existence check inside plex pod (733 unique paths, missing=0)
• Confirmed docs/media-stack.md counterfactual greps totalSize after prior auto-fix

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.