docs: address 3.8.0 → HEAD drift (#42)

- Glossary: rename sw_allEpisodesSeenBy / sw_watchers entries to match
  the new humanNames in rules.constants.ts (Plex, Jellyfin, Tautulli)
- Notifications: add ntfy agent (URL, Topic, Token)
- Collections: add Custom Poster section (one-shot writer, 500 KB cap,
  survives collection recreation)
- Overlays: add "Coexisting with other artwork tools" section noting
  Kometa/Posterizarr behaviour — per-item overlays reconcile on every
  cron tick, collection posters are last-writer-wins

Author: enoch85

docs/Collections.md

@@ -28,6 +28,22 @@ Collections now power additional Maintainerr views beyond cleanup.
 
 In the rule or collection form, you can enable overlays per collection and optionally choose a specific overlay template. Movies, shows, and seasons use poster templates. Episode collections use title card templates.
 
+## Custom Poster
+
+Maintainerr can store one custom poster per Maintainerr-managed collection and push it to the current media server. The stored file survives normal collection recreation, so you don't need to re-upload artwork after Plex or Jellyfin drops a collection and Maintainerr creates it again.
+
+The poster picker is available in the rule group's edit modal once the collection exists in Maintainerr.
+
+- Uploads accept JPEG, PNG, or WebP up to 500 KB. The image is normalized to JPEG before being stored.
+- The poster is pushed to the media server immediately on upload when the collection has a live media-server id. If the live push fails or the collection has no live id yet, the local file is still kept and pushed automatically when Maintainerr next recreates the collection.
+- Clearing a poster removes Maintainerr's stored file and sends a best-effort metadata refresh request to the media server. Whether the server replaces the artwork depends on its configured metadata/image agents.
+- Deleting a Maintainerr collection also removes its stored poster file.
+
+:::note One-shot writer
+Maintainerr writes the poster on upload and on collection recreation, then stops. It does not poll or reapply on a schedule, so it won't fight other artwork tools (e.g. Kometa, Posterizarr) or manual changes made directly in Plex or Jellyfin after the upload.
+
+:::
+
 ## Manual actions
 
 ### Adding

docs/Glossary.md

@@ -161,10 +161,10 @@ List of genres associated with the Plex item.
 - Availability: movies, shows, seasons, episodes
 - Type: text[]
 
-#### Users that saw all available episodes
+#### Users that watched every episode
 
 :::info
-List of users who have seen all available episodes of the Plex item. This rule is only available for shows.
+List of users who have watched every available episode of the Plex item. This rule is only available for shows.
 
 :::
 
@@ -249,10 +249,10 @@ The total number of views for the Plex item. This rule is only available for sho
 - Availability: shows, seasons, episodes
 - Type: number
 
-#### Users that watch the show/season/episode
+#### Users that watched at least one episode
 
 :::info
-List of users who watch the Plex item. This rule is only available for shows.
+List of users who have watched at least one episode of the Plex item. This rule is only available for shows.
 
 :::
 
@@ -691,10 +691,10 @@ List of genres associated with the Jellyfin item.
 - Availability: movies, shows, seasons, episodes
 - Type: text[]
 
-#### Users that saw all available episodes
+#### Users that watched every episode
 
 :::info
-List of users who have seen all available episodes of the Jellyfin item.
+List of users who have watched every available episode of the Jellyfin item.
 
 :::
 
@@ -779,10 +779,10 @@ The total number of views for the Jellyfin item. This rule is only available for
 - Availability: shows, seasons, episodes
 - Type: number
 
-#### Users that watch the show/season/episode
+#### Users that watched at least one episode
 
 :::info
-List of users who watch the Jellyfin item. This rule is only available for shows.
+List of users who have watched at least one episode of the Jellyfin item. This rule is only available for shows.
 
 :::
 
@@ -1741,21 +1741,21 @@ List of Plex usernames who have viewed (according to Tautulli) the Plex item. Th
 - Availability: movies
 - Type: text[]
 
-#### Users that saw all available episodes
+#### Users that watched every episode
 
 :::info
-List of users who have seen (according to Tautulli) all available episodes of the Plex item. The percentage for an episode to be considered as viewed is configured in the Tautulli settings.
+List of users who have watched (according to Tautulli) every available episode of the Plex item. The percentage for an episode to be considered as viewed is configured in the Tautulli settings.
 
 :::
 
 - Key: Tautulli.sw_allEpisodesSeenBy
 - Availability: shows, seasons
 - Type: text[]
 
-#### Users that watch the show/season/episode
+#### Users that watched at least one episode
 
 :::info
-List of users who watch (according to Tautulli) the Plex item. The percentage for an episode to be considered as viewed is configured in the Tautulli settings. This rule is only available for shows.
+List of users who have watched (according to Tautulli) at least one episode of the Plex item. The percentage for an episode to be considered as viewed is configured in the Tautulli settings. This rule is only available for shows.
 
 :::
 

docs/Notifications.md

@@ -112,6 +112,20 @@ You'll need the LunaSea mobile app installed and configured. The webhook setup d
 | Webhook URL | Yes | LunaSea webhook URL |
 | Profile Name | No | Specific profile name (if not using default) |
 
+### ntfy
+
+Send notifications to an [ntfy](https://ntfy.sh) server.
+
+:::note Setup Required
+You can use the public [ntfy.sh](https://ntfy.sh) server or a self-hosted instance. Pick a topic name (any string) and, if your server requires authentication, generate an access token. See the [ntfy docs](https://docs.ntfy.sh/) for setup details.
+
+:::
+| Parameter | Required | Description |
+| --------- | -------- | ----------- |
+| URL | Yes | Base URL of the ntfy server (e.g. `https://ntfy.sh`) |
+| Topic | Yes | Topic name to publish notifications to |
+| Token | No | Bearer access token for protected topics |
+
 ### Pushbullet
 
 Send notifications via Pushbullet.

docs/Overlays.md

@@ -93,6 +93,18 @@ Overlay processing only applies when all of these are true:
 
 Maintainerr re-renders overlays when the visible days-left value changes, and it can revert overlay artwork for a single collection or for all collections.
 
+## Coexisting with other artwork tools
+
+Maintainerr is one writer among several. Tools like [Kometa](https://kometa.wiki) and [Posterizarr](https://github.com/fscorrupt/Posterizarr), or manual uploads in Plex/Jellyfin, may replace Maintainerr's overlaid artwork between runs.
+
+Per-item overlays carry day-counter state, so they're re-applied on every cron tick (and on demand via `Run Now`). That means:
+
+- If Kometa restores its own artwork after Maintainerr writes an overlay, Maintainerr will reapply the overlay on the next run.
+- The cron interval determines how quickly that reconciliation happens — set it to match how often Kometa or other tools touch artwork.
+- After `Reset All Overlays`, Maintainerr restores its saved originals and stops re-writing. Other tools may still overwrite the artwork afterwards; that's expected.
+
+Collection posters (see [Collections — Custom Poster](./Collections.md#custom-poster)) behave differently: they're a one-shot write with no schedule, so other artwork tools can win against them permanently until you re-upload.
+
 ## Upgrade notes
 
 Recent Maintainerr releases add overlay tables and new collection fields to the database. On first startup after upgrading, allow database migration to finish before opening the Overlays pages.