From 4653c8c913cb8707cdce6206ed06449803a865aa Mon Sep 17 00:00:00 2001 From: enoch85 Date: Sat, 4 Jul 2026 08:47:19 +0000 Subject: [PATCH 1/6] docs(rules): document Sonarr episode retention rank and arr scoping properties Covers the episodeFileRank/seriesTitle/seriesId properties from Maintainerr/Maintainerr#3095 and the Radarr movieTitle/movieId pair from Maintainerr/Maintainerr#3222, with a keep-newest-N walkthrough. Also converts a stray em dash to a plain hyphen. --- docs/Rules.mdx | 53 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/docs/Rules.mdx b/docs/Rules.mdx index 8a25bdc39..5eec62efa 100644 --- a/docs/Rules.mdx +++ b/docs/Rules.mdx @@ -96,7 +96,7 @@ Maintainerr only shows `Force reset Seerr record` for movie, show, and season ru When you choose `Change quality profile and search` for Radarr or Sonarr, Maintainerr shows a quality profile selector for the chosen server. This action does not use `Take action after days`; it changes the item's quality profile immediately when the collection action runs. -The `Tag this content` option keeps a Radarr/Sonarr tag named after the rule group on each matching item for as long as it stays in the collection, and removes it when the item leaves. Because Sonarr tags apply to the whole series, the option is offered for movie collections (Radarr) and whole-show collections (Sonarr) only — not season or episode collections. The tag is created on the \*arr instance if missing, the rule group's name is normalized to the tag character set Radarr/Sonarr accept (lowercase letters, numbers, and hyphens), and tagging is best-effort, so it never blocks a rule run. Renaming a rule group applies the new tag on the next membership change but leaves the previous tag in place until you remove it. +The `Tag this content` option keeps a Radarr/Sonarr tag named after the rule group on each matching item for as long as it stays in the collection, and removes it when the item leaves. Because Sonarr tags apply to the whole series, the option is offered for movie collections (Radarr) and whole-show collections (Sonarr) only - not season or episode collections. The tag is created on the \*arr instance if missing, the rule group's name is normalized to the tag character set Radarr/Sonarr accept (lowercase letters, numbers, and hyphens), and tagging is best-effort, so it never blocks a rule run. Renaming a rule group applies the new tag on the next membership change but leaves the previous tag in place until you remove it. For Sonarr season rules, additional actions are available to also clean up the parent show when it becomes empty after season processing. @@ -306,3 +306,54 @@ When you use Radarr or Sonarr disk space properties, Maintainerr may also ask yo - `Remaining disk space` and `Total disk space` rules can target a specific configured path instead of assuming a single global root folder. - The path list is populated from the selected Radarr or Sonarr server. - For `Total disk space`, Maintainerr only shows paths where the server can report an accurate total size. + +### Episode retention rules (Sonarr) + +Long-running shows, daily series especially, can grow to thousands of episodes. +Three Sonarr properties let you build a rolling window that keeps only the +newest downloaded episodes of a show and cleans up the rest. + +- `Episode file rank by air date (newest = 1)` (number, episode rules only) + ranks every episode within its own show by air date, counting **only episodes + that are currently downloaded** in Sonarr. The newest downloaded episode is + rank 1, the next one rank 2, and so on. Episodes Sonarr knows about but has + no file for do not take up a rank. Specials (season 0), unaired episodes, + and episodes without a valid air date never receive a rank, so rules never + match them. +- `Series title` (text) is the show's title as Sonarr knows it. Matching is + case-insensitive. +- `Series ID` (number) is the show's id in Sonarr. Prefer this over the title + for rules that delete: the id keeps working after a rename or when titles + carry a year or region suffix. The easiest way to find it is the + [Test media](/test-media) feature: add a `Series ID` rule, test any episode + of the show, and read the value from the result. + +#### Keeping the newest episodes of a show + +A typical "keep the newest 5" rule group looks like this: + +- Media type `Episodes`, with a Sonarr action such as `Unmonitor and delete episode`. +- Rule 1: `Episode file rank by air date (newest = 1)` `bigger` than `5` +- Rule 2 (AND): `Series ID` `equals` the show's id + +Every run, all downloaded episodes of that show except the 5 newest by air +date enter the collection and are handled after `Take action after days`. As +new episodes download, they take rank 1 and the oldest of the kept window +rotates out on the next run. Episodes of every other show stay untouched: for +them the `Series ID` rule doesn't match, and without a scoping rule the rank +rule would apply the same window to every show in the library, which is +usually not what you want. + +The rank is computed fresh on every rule run from what is on disk at that +moment, and this also works for daily series whose Plex episodes only carry an +air date instead of a season and episode number. If Sonarr is unreachable +during a run, affected episodes are skipped rather than treated as matches, so +a temporary outage never causes unexpected deletions. + +#### Movie scoping (Radarr) + +`Movie title` (text, case-insensitive) and `Movie ID` (number) are the movie +equivalents of `Series title` and `Series ID`: they pin a movie rule to +specific movies without going through tags or collections. The same advice +applies - prefer `Movie ID` for destructive rules, and use +[Test media](/test-media) to read a movie's id. From 7a8603fc9eaf4bb27353615fe39158d8448da567 Mon Sep 17 00:00:00 2001 From: enoch85 Date: Sat, 4 Jul 2026 09:07:00 +0000 Subject: [PATCH 2/6] docs(rules): add seasonFileRank to the episode retention section Covers Maintainerr/Maintainerr#3223. --- docs/Rules.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/Rules.mdx b/docs/Rules.mdx index 5eec62efa..41f24ce9a 100644 --- a/docs/Rules.mdx +++ b/docs/Rules.mdx @@ -322,6 +322,11 @@ newest downloaded episodes of a show and cleans up the rest. match them. - `Series title` (text) is the show's title as Sonarr knows it. Matching is case-insensitive. +- `Season file rank by air date (newest = 1)` (number, season rules only) + is the same idea one level up: it ranks every season within its show by the + air date of its newest downloaded episode. Seasons without any downloaded + episode take no rank slot, and specials (season 0) are excluded. Use it for + "keep the newest N seasons" rule groups. - `Series ID` (number) is the show's id in Sonarr. Prefer this over the title for rules that delete: the id keeps working after a rename or when titles carry a year or region suffix. The easiest way to find it is the From 8aadfd047ac23d4a9af71c60c5693d7e689b4d6f Mon Sep 17 00:00:00 2001 From: enoch85 Date: Sat, 4 Jul 2026 09:09:44 +0000 Subject: [PATCH 3/6] docs(rules): integrate seasonFileRank properly (count, order, season walkthrough) --- docs/Rules.mdx | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/Rules.mdx b/docs/Rules.mdx index 41f24ce9a..c11c640c1 100644 --- a/docs/Rules.mdx +++ b/docs/Rules.mdx @@ -310,8 +310,8 @@ When you use Radarr or Sonarr disk space properties, Maintainerr may also ask yo ### Episode retention rules (Sonarr) Long-running shows, daily series especially, can grow to thousands of episodes. -Three Sonarr properties let you build a rolling window that keeps only the -newest downloaded episodes of a show and cleans up the rest. +Four Sonarr properties let you build a rolling window that keeps only the +newest downloaded episodes or seasons of a show and cleans up the rest. - `Episode file rank by air date (newest = 1)` (number, episode rules only) ranks every episode within its own show by air date, counting **only episodes @@ -320,13 +320,13 @@ newest downloaded episodes of a show and cleans up the rest. no file for do not take up a rank. Specials (season 0), unaired episodes, and episodes without a valid air date never receive a rank, so rules never match them. -- `Series title` (text) is the show's title as Sonarr knows it. Matching is - case-insensitive. - `Season file rank by air date (newest = 1)` (number, season rules only) is the same idea one level up: it ranks every season within its show by the air date of its newest downloaded episode. Seasons without any downloaded episode take no rank slot, and specials (season 0) are excluded. Use it for "keep the newest N seasons" rule groups. +- `Series title` (text) is the show's title as Sonarr knows it. Matching is + case-insensitive. - `Series ID` (number) is the show's id in Sonarr. Prefer this over the title for rules that delete: the id keeps working after a rename or when titles carry a year or region suffix. The easiest way to find it is the @@ -349,10 +349,14 @@ them the `Series ID` rule doesn't match, and without a scoping rule the rank rule would apply the same window to every show in the library, which is usually not what you want. +The season variant works the same way one level up: media type `Seasons`, +`Season file rank by air date (newest = 1)` `bigger` than `2`, and the same +`Series ID` scope rule keep the newest two seasons and select the older ones. + The rank is computed fresh on every rule run from what is on disk at that moment, and this also works for daily series whose Plex episodes only carry an air date instead of a season and episode number. If Sonarr is unreachable -during a run, affected episodes are skipped rather than treated as matches, so +during a run, affected items are skipped rather than treated as matches, so a temporary outage never causes unexpected deletions. #### Movie scoping (Radarr) From a78a2a3beb91b18ea162c93bc5cabd77da064e1f Mon Sep 17 00:00:00 2001 From: enoch85 Date: Sat, 4 Jul 2026 10:28:37 +0000 Subject: [PATCH 4/6] docs(rules): split episode and season retention walkthroughs, clarify daily-series behavior Review polish: each retention level gets its own self-contained recipe with expected outcome, the scoping advice is stated once up front, and a dedicated daily-series section spells out date-only episode matching, year-seasons, and that airing without downloading never moves the window. --- docs/Rules.mdx | 75 +++++++++++++++++++++++++++++++++----------------- 1 file changed, 50 insertions(+), 25 deletions(-) diff --git a/docs/Rules.mdx b/docs/Rules.mdx index c11c640c1..8376335d6 100644 --- a/docs/Rules.mdx +++ b/docs/Rules.mdx @@ -307,7 +307,7 @@ When you use Radarr or Sonarr disk space properties, Maintainerr may also ask yo - The path list is populated from the selected Radarr or Sonarr server. - For `Total disk space`, Maintainerr only shows paths where the server can report an accurate total size. -### Episode retention rules (Sonarr) +### Episode and season retention rules (Sonarr) Long-running shows, daily series especially, can grow to thousands of episodes. Four Sonarr properties let you build a rolling window that keeps only the @@ -317,14 +317,14 @@ newest downloaded episodes or seasons of a show and cleans up the rest. ranks every episode within its own show by air date, counting **only episodes that are currently downloaded** in Sonarr. The newest downloaded episode is rank 1, the next one rank 2, and so on. Episodes Sonarr knows about but has - no file for do not take up a rank. Specials (season 0), unaired episodes, + no file for do not take up a rank, and an episode airing without being + downloaded never shifts the window. Specials (season 0), unaired episodes, and episodes without a valid air date never receive a rank, so rules never match them. -- `Season file rank by air date (newest = 1)` (number, season rules only) - is the same idea one level up: it ranks every season within its show by the - air date of its newest downloaded episode. Seasons without any downloaded - episode take no rank slot, and specials (season 0) are excluded. Use it for - "keep the newest N seasons" rule groups. +- `Season file rank by air date (newest = 1)` (number, season rules only) is + the same idea one level up: it ranks every season within its show by the air + date of its newest downloaded episode. Seasons without any downloaded + episode take no rank slot, and specials (season 0) are excluded. - `Series title` (text) is the show's title as Sonarr knows it. Matching is case-insensitive. - `Series ID` (number) is the show's id in Sonarr. Prefer this over the title @@ -333,31 +333,56 @@ newest downloaded episodes or seasons of a show and cleans up the rest. [Test media](/test-media) feature: add a `Series ID` rule, test any episode of the show, and read the value from the result. -#### Keeping the newest episodes of a show +In every case the rank is computed fresh on each rule run from what is on disk +at that moment. If Sonarr is unreachable during a run, affected items are +skipped rather than treated as matches, so a temporary outage never causes +unexpected deletions. -A typical "keep the newest 5" rule group looks like this: +Both rank properties apply their window per show. Always pair them with a +`Series ID` (or `Series title`) rule as shown below - without one, the same +window applies to every show in the library, which is usually not what you +want. + +#### Keep the newest N episodes of a show + +A "keep the newest 5 episodes" rule group looks like this: - Media type `Episodes`, with a Sonarr action such as `Unmonitor and delete episode`. - Rule 1: `Episode file rank by air date (newest = 1)` `bigger` than `5` - Rule 2 (AND): `Series ID` `equals` the show's id Every run, all downloaded episodes of that show except the 5 newest by air -date enter the collection and are handled after `Take action after days`. As -new episodes download, they take rank 1 and the oldest of the kept window -rotates out on the next run. Episodes of every other show stay untouched: for -them the `Series ID` rule doesn't match, and without a scoping rule the rank -rule would apply the same window to every show in the library, which is -usually not what you want. - -The season variant works the same way one level up: media type `Seasons`, -`Season file rank by air date (newest = 1)` `bigger` than `2`, and the same -`Series ID` scope rule keep the newest two seasons and select the older ones. - -The rank is computed fresh on every rule run from what is on disk at that -moment, and this also works for daily series whose Plex episodes only carry an -air date instead of a season and episode number. If Sonarr is unreachable -during a run, affected items are skipped rather than treated as matches, so -a temporary outage never causes unexpected deletions. +date enter the collection and are handled after `Take action after days`. +When a new episode downloads, it takes rank 1 and the oldest episode of the +kept window rotates out on the next run. + +#### Keep the newest N seasons of a show + +A "keep the newest 2 seasons" rule group looks like this: + +- Media type `Seasons`, with a Sonarr action such as `Unmonitor and delete season`. +- Rule 1: `Season file rank by air date (newest = 1)` `bigger` than `2` +- Rule 2 (AND): `Series ID` `equals` the show's id + +Every run, all seasons that have downloaded episodes, except the 2 with the +newest downloaded episodes, enter the collection and are handled after +`Take action after days`. When a new season starts downloading it becomes +rank 1, and the oldest kept season rotates out on the next run. A season +whose files have all been removed drops out of the ranking entirely; it does +not linger in the collection. + +#### Daily series + +Both walkthroughs work unchanged for daily series: + +- Daily shows that use one season per year rank those year-seasons like any + other season. +- Some servers store daily episodes with only an air date and no episode + number. Those episodes are matched to Sonarr by broadcast date, so + `Episode file rank by air date (newest = 1)` still resolves. When two + episodes of a date-only show share the same broadcast day, the newer one's + rank is used, which errs on the side of keeping media. +- Airing alone never changes anything: only a new download moves the window. #### Movie scoping (Radarr) From bf8e7759da0a889385d907fddf11dc4352310b1d Mon Sep 17 00:00:00 2001 From: enoch85 Date: Sat, 4 Jul 2026 10:40:35 +0000 Subject: [PATCH 5/6] docs(rules): match the renamed rank labels (Maintainerr/Maintainerr#3224) --- docs/Rules.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/Rules.mdx b/docs/Rules.mdx index 8376335d6..3ceff9d36 100644 --- a/docs/Rules.mdx +++ b/docs/Rules.mdx @@ -313,7 +313,7 @@ Long-running shows, daily series especially, can grow to thousands of episodes. Four Sonarr properties let you build a rolling window that keeps only the newest downloaded episodes or seasons of a show and cleans up the rest. -- `Episode file rank by air date (newest = 1)` (number, episode rules only) +- `Episode position by air date (1 = newest downloaded)` (number, episode rules only) ranks every episode within its own show by air date, counting **only episodes that are currently downloaded** in Sonarr. The newest downloaded episode is rank 1, the next one rank 2, and so on. Episodes Sonarr knows about but has @@ -321,7 +321,7 @@ newest downloaded episodes or seasons of a show and cleans up the rest. downloaded never shifts the window. Specials (season 0), unaired episodes, and episodes without a valid air date never receive a rank, so rules never match them. -- `Season file rank by air date (newest = 1)` (number, season rules only) is +- `Season position by air date (1 = newest downloaded)` (number, season rules only) is the same idea one level up: it ranks every season within its show by the air date of its newest downloaded episode. Seasons without any downloaded episode take no rank slot, and specials (season 0) are excluded. @@ -348,7 +348,7 @@ want. A "keep the newest 5 episodes" rule group looks like this: - Media type `Episodes`, with a Sonarr action such as `Unmonitor and delete episode`. -- Rule 1: `Episode file rank by air date (newest = 1)` `bigger` than `5` +- Rule 1: `Episode position by air date (1 = newest downloaded)` `bigger` than `5` - Rule 2 (AND): `Series ID` `equals` the show's id Every run, all downloaded episodes of that show except the 5 newest by air @@ -361,7 +361,7 @@ kept window rotates out on the next run. A "keep the newest 2 seasons" rule group looks like this: - Media type `Seasons`, with a Sonarr action such as `Unmonitor and delete season`. -- Rule 1: `Season file rank by air date (newest = 1)` `bigger` than `2` +- Rule 1: `Season position by air date (1 = newest downloaded)` `bigger` than `2` - Rule 2 (AND): `Series ID` `equals` the show's id Every run, all seasons that have downloaded episodes, except the 2 with the @@ -379,7 +379,7 @@ Both walkthroughs work unchanged for daily series: other season. - Some servers store daily episodes with only an air date and no episode number. Those episodes are matched to Sonarr by broadcast date, so - `Episode file rank by air date (newest = 1)` still resolves. When two + `Episode position by air date (1 = newest downloaded)` still resolves. When two episodes of a date-only show share the same broadcast day, the newer one's rank is used, which errs on the side of keeping media. - Airing alone never changes anything: only a new download moves the window. From cee331a201d5434a78dc88d0cdedfd67374cce78 Mon Sep 17 00:00:00 2001 From: enoch85 Date: Sat, 4 Jul 2026 10:45:07 +0000 Subject: [PATCH 6/6] docs(rules): final label wording (1 = latest) --- docs/Rules.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/Rules.mdx b/docs/Rules.mdx index 3ceff9d36..642914a0f 100644 --- a/docs/Rules.mdx +++ b/docs/Rules.mdx @@ -313,7 +313,7 @@ Long-running shows, daily series especially, can grow to thousands of episodes. Four Sonarr properties let you build a rolling window that keeps only the newest downloaded episodes or seasons of a show and cleans up the rest. -- `Episode position by air date (1 = newest downloaded)` (number, episode rules only) +- `Episode position by air date (1 = latest)` (number, episode rules only) ranks every episode within its own show by air date, counting **only episodes that are currently downloaded** in Sonarr. The newest downloaded episode is rank 1, the next one rank 2, and so on. Episodes Sonarr knows about but has @@ -321,7 +321,7 @@ newest downloaded episodes or seasons of a show and cleans up the rest. downloaded never shifts the window. Specials (season 0), unaired episodes, and episodes without a valid air date never receive a rank, so rules never match them. -- `Season position by air date (1 = newest downloaded)` (number, season rules only) is +- `Season position by air date (1 = latest)` (number, season rules only) is the same idea one level up: it ranks every season within its show by the air date of its newest downloaded episode. Seasons without any downloaded episode take no rank slot, and specials (season 0) are excluded. @@ -348,7 +348,7 @@ want. A "keep the newest 5 episodes" rule group looks like this: - Media type `Episodes`, with a Sonarr action such as `Unmonitor and delete episode`. -- Rule 1: `Episode position by air date (1 = newest downloaded)` `bigger` than `5` +- Rule 1: `Episode position by air date (1 = latest)` `bigger` than `5` - Rule 2 (AND): `Series ID` `equals` the show's id Every run, all downloaded episodes of that show except the 5 newest by air @@ -361,7 +361,7 @@ kept window rotates out on the next run. A "keep the newest 2 seasons" rule group looks like this: - Media type `Seasons`, with a Sonarr action such as `Unmonitor and delete season`. -- Rule 1: `Season position by air date (1 = newest downloaded)` `bigger` than `2` +- Rule 1: `Season position by air date (1 = latest)` `bigger` than `2` - Rule 2 (AND): `Series ID` `equals` the show's id Every run, all seasons that have downloaded episodes, except the 2 with the @@ -379,7 +379,7 @@ Both walkthroughs work unchanged for daily series: other season. - Some servers store daily episodes with only an air date and no episode number. Those episodes are matched to Sonarr by broadcast date, so - `Episode position by air date (1 = newest downloaded)` still resolves. When two + `Episode position by air date (1 = latest)` still resolves. When two episodes of a date-only show share the same broadcast day, the newer one's rank is used, which errs on the side of keeping media. - Airing alone never changes anything: only a new download moves the window.