docs: cover the overlay deletion gate and the richer webhook media items

docs/Calendar.md

@@ -37,6 +37,8 @@ The details dialog shows:
 - collection name
 - media type
 
+A season or episode is named under its show, as `Some Show - S02` and `Some Show - S02E05`, so several seasons of one show can be told apart. When the library leaves the season number unset, the season's own name is used instead.
+
 From that dialog, you can jump directly to the related collection.
 
 ## Reading the schedule correctly

docs/Notifications.md

@@ -239,12 +239,31 @@ Example `mediaItems` value for a **Media About to be Handled** notification when
 
 ```json
 [
-  { "mediaServerId": "abc123", "requestedBy": ["alice"] },
+  {
+    "mediaServerId": "abc123",
+    "type": "movie",
+    "title": "A Sample Movie",
+    "providerIds": { "imdb": ["tt0000000"], "tmdb": ["1234"], "tvdb": [] },
+    "requestedBy": ["alice"]
+  },
   { "mediaServerId": "def456" }
 ]
 ```
 
-Each entry contains `mediaServerId`. The optional `requestedBy` array lists the Seerr usernames who requested the item; it is omitted when Seerr is not configured or the item was not requested there.
+Every entry contains `mediaServerId`. The rest are optional:
+
+| Field         | Description                                                                          |
+| ------------- | ------------------------------------------------------------------------------------ |
+| `type`        | `movie`, `show`, `season` or `episode`                                               |
+| `title`       | The item's name, worded the same way as in the message text                          |
+| `providerIds` | The item's IMDb, TMDB and TVDB ids. Each is an array, and empty when there is no id. |
+| `requestedBy` | The Seerr usernames who requested the item                                           |
+
+`type`, `title` and `providerIds` come from a snapshot Maintainerr takes just before it handles an item, so they still name it once the deletion has made its media server id useless. Only **Media About to be Handled** and **Media Handled** carry them, and they are left out for an item the media server could not be asked about at the time.
+
+The ids are the item's own, so a season or episode carries season or episode ids rather than the show's. If you match on them, resolve the show yourself.
+
+`requestedBy` is left out when Seerr is not configured or the item was not requested there.
 
 Example JSON payload:
 

docs/Overlays.md

@@ -79,8 +79,11 @@ Overlay processing only applies when all of these are true:
 - a supported media server is configured
 - the collection has overlays enabled
 - the collection has `Take action after days` set
+- the collection's action deletes files
 - a matching template can be resolved
 
+A countdown says the media leaves the library on that date, so a collection whose action keeps the files draws nothing at all. That covers the actions that only unmonitor, `Change quality profile and search`, and `Do nothing`. Point a collection at one of them and the next overlay run puts the original artwork back on everything it had drawn on before.
+
 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.
 
 Deleting a collection restores its overlays first, so its items keep their original artwork.
@@ -90,11 +93,11 @@ Deleting a collection restores its overlays first, so its items keep their origi
 When a collection's action deletes files, more than the items in the collection are deleted. Maintainerr draws the same countdown on those extra items:
 
 - Everything under an item in the collection. Deleting a show also deletes its seasons and episodes. Deleting a season also deletes its episodes.
-- A season or show that is left empty. If every episode of a season is in the collection, the season goes with them. If every season of a show is in the collection, the show goes too. Both get the date of the last item to be deleted. A leftover `Specials` season does not stop this.
+- A season or show that is left empty. If every episode of a season is in the collection, the season goes with them. If every season of a show is in the collection, the show goes too. Both get the date of the last item to be deleted. Every child has to be covered, `Specials` included: a season 0 left outside the collection keeps its episode files, so the show stays in the library and gets no countdown.
 
 These extra items only get an overlay. They are never added to the collection, so nothing extra is deleted.
 
-This happens for show, season and episode collections that have `Take action after days` set and an action that deletes files. Actions that keep the files, such as `Unmonitor and keep files`, `Change quality profile` and `Do nothing`, draw nothing extra. Neither do movie collections, because deleting a movie deletes nothing else.
+This happens for show, season and episode collections. Movie collections draw nothing extra, because deleting a movie deletes nothing else.
 
 Episodes need a title card template, so make sure you have one if a show or season collection reaches down to episodes. Without it, those episodes are skipped and the log says so.