From 535847477e789b34b8afc816cd693b7de97f7dbd Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 2 Nov 2026 14:12:46 -0500 Subject: [PATCH] =?UTF-8?q?docs(admin):=20all-podcasts=20page=20=E2=80=94?= =?UTF-8?q?=20the=20maintenance=20view?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Seventh admin page. Documents the disk-usage sort (hogs surface first), the header totals, each column's meaning (orphaned = no subscribers, usually a departed user's feed), and the three actions with their real semantics: Refresh (manual poll vs. the Settings→Podcasts interval), Delete files (resets episodes to pending, re-download on demand, and the non-obvious part quoted: a refresh will not re-materialize them), Remove (instance-wide: rows + files + everyone's subscriptions, unlike a user's own unsubscribe). Cross-links the user podcast guide for the listening side. Glossary gains Delete files and a scoped Remove. --- docs/admin/podcasts.md | 51 +++++++++++++++++++++++++++++++++++ docs/developer/ui-controls.md | 8 ++++++ 2 files changed, 59 insertions(+) create mode 100644 docs/admin/podcasts.md diff --git a/docs/admin/podcasts.md b/docs/admin/podcasts.md new file mode 100644 index 00000000..4d5081ae --- /dev/null +++ b/docs/admin/podcasts.md @@ -0,0 +1,51 @@ + + +# All Podcasts + +This is the maintenance view for the podcast subsystem: **every feed from +every user**, sorted by disk usage, so the biggest disk hogs surface +first. (The listening side — subscribing, playing, downloading episodes — +lives in the [user podcast guide](../user/podcasts.md); this page is +about running the thing.) + +## The header totals + +Above the table: how many feeds exist, how many episodes are downloaded +versus total, and how much disk the downloads occupy instance-wide. + +## The table + +One row per feed: + +| Column | Meaning | +| --- | --- | +| **Feed** | Title (links to its podcast page) and host | +| **Library** | Which library holds it | +| **Subscribers** | How many users subscribe (hover for names). **orphaned** means nobody does — usually a departed user's feed | +| **Downloaded** | Episodes on disk / episodes the feed has published | +| **Disk** | Space the downloaded files occupy | +| **Last fetch** | When the feed was last checked for new episodes | + +## Actions, per feed + +- **Refresh** — checks the feed for new episodes right now, instead of + waiting for the automatic poll (its interval lives in Settings → + Podcasts). +- **Delete files** (only when episodes are downloaded) — frees the disk + and resets those episodes to *pending*. They re-download on demand when + someone plays them. The confirm says the important part: **a feed + refresh will not re-materialize them** — deleting files is safe and + reversible by playback, not by refresh. +- **Remove** — the admin delete: removes the feed, its episode rows, its + downloaded files, and everyone's subscriptions. This is instance-wide + (the confirm says so); a user removing their own subscription from the + listening side only affects that user. + +## When the page is empty + +"No podcast feeds exist yet." — feeds appear when users add them (or when +you do, from the podcast section of the app). diff --git a/docs/developer/ui-controls.md b/docs/developer/ui-controls.md index 576a7085..3c91f5fc 100644 --- a/docs/developer/ui-controls.md +++ b/docs/developer/ui-controls.md @@ -292,6 +292,14 @@ label: Keep this copy where: Admin → Hash Conflicts → a copy row does: Keeps that copy, folds the other copies' reading data into it, and removes their catalog rows. Files on disk are never touched. +label: Delete files +where: Admin → All Podcasts → a feed row +does: Frees the disk and resets downloaded episodes to pending; they re-download on demand. A feed refresh will NOT re-materialize them. + +label: Remove +where: Admin → All Podcasts → a feed row +does: Admin-wide feed removal — episode rows, downloaded files, and every user's subscription are deleted. Instance-wide, unlike a user's own unsubscribe. + label: Resume rewind where: audio player → player settings; profile settings does: Rewinds playback a configured few seconds when you resume.