Initial design for MediaShelf

Software design for a Plex library analytics and reclaim-reporting tool.
v1 is report-only: no deletion, no filesystem access, Plex API as the sole
data source. Movies at item level, TV rolled up to season level.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GVbG48GAXfCZatcmX123Ra

README.md

@@ -0,0 +1,47 @@
+# MediaShelf
+
+A self-hosted web app for figuring out which of the thousands of files in a Plex library
+are actually worth keeping.
+
+MediaShelf scans a Plex Media Server over its HTTP API, builds a local snapshot of every
+movie and TV season, and joins together the facts Plex already knows but never shows side
+by side — date added, size on disk, file path, owning library, watch count, and last
+watched — into a sortable, filterable, chartable grid with a tunable **reclaim score**
+that ranks deletion candidates.
+
+## Status
+
+**v1 is report-only.** MediaShelf does not delete, move, or modify anything. It produces
+a ranked list, saved rule sets, and CSV export. Deletion is designed for in the roadmap
+but deliberately not built, so the scanner and the scoring model can be trusted before
+anything destructive is wired up.
+
+Nothing is implemented yet — this repository currently holds the design.
+
+## What it does
+
+- Full-library ingest from Plex, no agent on the Plex host, no filesystem mounts
+- Movies at item level, TV rolled up to **season** level
+- Watch data pulled from the server-wide playback history, so plays by *every* Plex
+  account are counted — not just the token owner's
+- Sort and filter on every metric; charts for size by library, additions over time,
+  watched vs. unwatched by size, and size vs. last-watched
+- A weighted reclaim score with live sliders, and grace rules so it never recommends
+  something you added last week
+- Named, re-runnable saved views — *"unwatched, older than 2 years, over 10 GB"*
+- CSV export of any view
+
+## Planned stack
+
+Python + Flask, SQLite (WAL), vanilla JS front-end, single container deployed as a
+Portainer stack behind Nginx Proxy Manager.
+
+## Roadmap
+
+- **v2** — two-stage quarantine-then-purge deletion, with authentication, a path
+  allowlist, and an audit log
+- **v3** — Emby and Jellyfin support behind the existing `MediaProvider` abstraction
+
+## Documentation
+
+- [`docs/design.md`](docs/design.md) — the full software design