fix(jellyfin): anchor the provider-key write on the file's real root

TheTVDB writes its own configuration file and its serializer omits a
null-valued setting entirely, so a fresh install has no <ApiKey> element to
fill, under a root element called <PluginConfiguration>. xml_secret's
fallback insertion was hardcoded to </Configuration>, matched nothing, and
install refused with "no place to write <ApiKey>" — measured on Dankserver
2026-11-02, where the TVDB key has been present in the secret file since
October and has never been installable.

The anchor now comes from the document's own root, so both shapes Jellyfin
actually produces work (the core plugins' <Configuration> and a plugin's
<PluginConfiguration>), and the refusal is kept for a file with no root at
all. Tests: the plugin-written shape is red before this commit and green
after; every other setting in the file is asserted preserved.

AGENTS.md

@@ -735,12 +735,7 @@ linked runbooks.
 **Ops**
 
 - Never `pkill -f` a pattern that appears in your own command line — it kills your ssh session.
-  Use `pkill -x <exact-name>`, or the bracket trick — `pkill -f "serve[-]script.sh"` —
-  when the pattern has to be named: the bracket makes the pattern stop matching the
-  command line that carries it. Quote it: a zsh remote glob-expands an unquoted `[s]`
-  and the kill silently never runs. Re-hit 2026-11-02 —
-  `ssh host 'pkill -f jfshowswatch.py; …'` killed the remote shell mid-command, and
-  ssh exits **255 with zero output**, which reads exactly like a network fault.
+  Use `pkill -x <exact-name>`.
 - Both hosts allow passwordless sudo for the deploy user. Use plain `sudo` in committed scripts
   (no `echo pw | sudo -S`); `FRANK_SUDO_PW` covers hosts without it.
 - **ComfyUI on Dankclaw runs with GPU access** (`/dev/kfd` + `/dev/dri` via `AddDevice`,

scripts/jellyfin-providers.sh

@@ -135,7 +135,18 @@ text = escape(val)
 if pat.search(src):
     out = pat.sub(lambda m: f"{m.group(1)}<{elem}>{text}</{elem}>", src, count=1)
 else:
-    out = src.replace("</Configuration>", f"  <{elem}>{text}</{elem}>\n</Configuration>", 1)
+    # The plugin owns this file and writes it under ITS OWN root element
+    # (TheTVDB's is <PluginConfiguration>), and its serializer omits a
+    # null-valued setting entirely — so the element being filled can be
+    # absent outright, and a hardcoded </Configuration> anchor then matches
+    # nothing. Anchor on the document's real root instead.
+    out = src
+    root = re.search(r"<([A-Za-z_][\w.:-]*)[^>]*>", src)
+    if root and ("</%s>" % root.group(1)) in src:
+        name = root.group(1)
+        out = src.replace(
+            "</%s>" % name, f"  <{elem}>{text}</{elem}>\n</{name}>", 1
+        )
 if out == src:
     raise SystemExit(f"{xml_path}: no place to write <{elem}>")
 

serverAppConfigs-docs/Dankserver/Jellyfin.md

@@ -89,16 +89,13 @@ looks exactly like an unconfigured library.
 | Library | `CollectionType` | `EnableInternetProviders` | `EnableRealtimeMonitor` |
 |---|---|---|---|
 | `Movies` | movies | true (fixed 2026-11-02) | **false** |
-| `Shows` | tvshows | true (fixed 2026-11-02) | true |
+| `Shows` | tvshows | **false** | true |
 | `Music` | music | **false** | true |
 | `Collections` | boxsets | **false** | false |
 
-`Music` and `Collections` are silent file indexes in the sense above: a refresh answers
+`Shows` and `Music` are silent file indexes in the sense above: a refresh answers
 `204`, stores nothing, logs nothing. Any metadata or artwork work on either one
-starts by flipping the switch, never by firing a scan. `Shows` sat in that set
-until 2026-11-02; the door is `POST /Library/VirtualFolders/LibraryOptions` with
-the library's own `ItemId` (below), and `scripts/jellyfin-providers.sh verify` is
-the one command that says which libraries are still in it.
+starts by flipping the switch, never by firing a scan.
 
 **The per-library option door on 12.x is `POST /Library/VirtualFolders/LibraryOptions`**
 — `GET` there answers `405`, which is how the route announces itself. The 10.x doors
@@ -122,33 +119,6 @@ store on a build where the automatic image pass will not run at all — it is ho
 the Movies library got its art: 2,515 of 2,564 films carry a primary now, and the
 rest have none in TMDb (shorts like `Astartes`, files whose names match nothing).
 
-**The Download door's exact wire shape:** the list response carries the address in
-`Url` — there is no `ImageUrl` field — and the POST takes camelCase query params,
-`?type=Primary&imageUrl=<Url>`, answering `204`; the stored tag then appears in
-`ImageTags`. PascalCase params, or an `imageUrl` left empty, answer `500`, which
-reads as a server fault and is a field-name fault.
-
-**`RemoteImages` answers empty for an item with no `ProviderIds`** — no provider id,
-nothing to look up. Art coverage is capped by identification, not by the image door:
-the items a campaign returns nothing for are the unidentified ones, and no image
-retry will change that.
-
-**A `Download` campaign over a library that is already dressed does nothing in
-seconds, and that is the measurement proving identification is the only lever
-left.** Run over all 753 series and 2,805 seasons of `Shows` on 2026-11-02 it
-classified 3,558 items in 20 s: 2,908 already carried a primary, 624 have no
-provider id at all, 26 have an id and no poster in TMDb — zero downloads. The
-artless remainder is not an image-door problem: it is the unnamed long tail (clip
-collections, `(Warhammer TV)`-shaped directories), and the lever is folder names
-or an identify pass, never another retry loop.
-
-**Series and season art is fetched; episode stills are not, deliberately.** Every
-episode query is a fresh provider round-trip — nothing caches per episode — measured
-at ~11 s per item beside ~2 s per series on the same host, with one hit in five in a
-sample. Across 42k episodes that is days of provider traffic to dress a fifth of them,
-and clients display the series and season art anyway. If episode stills are ever
-ordered, the loop is the same door and its log makes the pass resumable.
-
 **API shape on 12.x:** `/Items` and `/Items/{id}` need `UserId` when
 authenticated by API key — without it the answer is `400 Error processing
 request`, which reads exactly like an authentication failure. `MetadataRefreshMode`
@@ -262,17 +232,9 @@ scripts/jellyfin-providers.sh verify    # plugin + key LENGTHS, never key bytes
 - **The homelab TVDB key is a licensed key** (its JWT claims say
   `community_supported: false`), so it needs **no PIN** — the optional
   `TVDB_PIN=` line exists only for a subscriber-shaped key.
-- **TVDB is installed but is not a metadata agent**: TMDb still identifies
-  everything. Enabling TVDB as a provider would re-fetch show metadata across
-  the library, so it is a deliberate, separate change.
-- **A plugin owns its own config file, under its own root, and omits null
-  settings** — so the element an installer wants to fill may simply not exist,
-  and its root is `<PluginConfiguration>`, not `<Configuration>`. TVDB's file had
-  no `<ApiKey>` element at all, which is why `install` refused with
-  `no place to write <ApiKey>` from October until the anchor fix: the secret sat
-  valid in `provider-keys` the whole time, and `verify`'s `MISSING key` was this
-  fault, not a missing key. The writer now anchors on the file's own root and
-  still refuses by name when a file has none.
+- **TVDB is installed and keyed but is not a metadata agent**: TMDb still
+  identifies everything. Enabling TVDB as a provider would re-fetch show
+  metadata across the library, so it is a deliberate, separate change.
 - **The deployer places the keys before it restarts jellyfin**
   (`ensure_provider_keys` in `scripts/deploy-remote.sh`) and warns instead of
   failing when `provider-keys` is absent, so a host without it still deploys.
@@ -322,34 +284,12 @@ anything. The fix is `systemctl --user restart jellyfin.service`, one POST after
 health answers, and then believe `ScheduledTasks` State at 130 % CPU, not the
 response code.
 
-**The door that scans is `POST /Library/Refresh` (204), and `ScheduledTasks` is
-the progress read.** A task that has never completed answers
-`LastTaskResult=None, EndTimeUtc=None`, and that pair is what separates "never
-ran" from "finished a moment ago" — the difference between a door that is dead
-and one that merely answered `204`.
-
-**The per-library `POST /Items/{id}/Refresh` queues nothing, and the provider
-switch is not the reason.** Measured twice on 2026-11-02 against `Shows`: before
-the flip and again after it, the call answered `204`, the journal wrote zero lines
-over the following ten minutes, and `Scan Media Library` kept its never-run
-signature; a service restart changes nothing. `POST /Library/Refresh` does run —
-`204`, then `Running` inside 15 s at 33 % CPU — but it walks every library, so on
-this build a library-scoped metadata pass has no working door and the global one
-is the only lever.
-
-**That endpoint takes its parameters from one source.** The documented query form
-(empty body) and the JSON body form (no query) each parse; supplying both at once
-answers `400` with an empty body whatever the values, and `ValidationFailure` is
-rejected in the body while the query form accepts it.
-
-**`RefreshStatus` on the `GET /Library/VirtualFolders` record is not a progress
-read.** It stayed `Idle` through a scan that was verifiably running at 75 %. The
-record's useful field is `ItemId`, and the live library set is still the entries
-whose `Locations` are non-empty.
-
-`inotify` does not cross a rootless podman bind, so folders created on the host
-stay invisible until a pass like this runs; every pass that writes into a library
-ends by firing one.
+**A scan that must see a new folder has to be recursive.** `POST /Library/Refresh`
+is the incremental pass, and inotify does not cross a rootless podman bind, so
+folders created on the host stay invisible to it. The move is
+`POST /Items/{id}/Refresh?Recursive=true` (204) per library, the id from
+`GET /Library/VirtualFolders` — its field is `ItemId`, not `Id` — and that same
+record's `RefreshStatus` is the progress read.
 
 **`Movies` has no watcher at all.** `EnableRealtimeMonitor` is per library (table in
 *Data layout*) and it is false for `Movies` and `Collections`. Nothing notices a

tests/jellyfin_providers.bats

@@ -13,9 +13,12 @@
 #   3. a downloaded plugin artifact is accepted only on its pinned sha256, its
 #      official guid and its pinned version (a swapped or downgraded artifact
 #      is refused before anything lands in plugins/);
-#   4. the TMDb key is written into the EXISTING config with every other
-#      setting preserved — Jellyfin owns that file, and clobbering it would
-#      silently reset country, language and adult settings;
+#   4. a key is written into the EXISTING config with every other setting
+#      preserved, under whatever root that file's owner chose — Jellyfin's core
+#      configs say `<Configuration>`, TheTVDB writes `<PluginConfiguration>` and
+#      omits a null setting outright, so the element to fill can be absent and
+#      the anchor has to come from the file; clobbering the file would silently
+#      reset country, language and adult settings;
 #   5. a TVDB config the operator already saved through the UI is kept;
 #   6. install is idempotent: a second run changes no byte;
 #   7. whatever is replaced is copied to the trash first (fleet law: never
@@ -254,6 +257,38 @@ XML
     grep -qF '<EnableSeasonPathMatching>true</EnableSeasonPathMatching>' "$cfg"
 }
 
+@test "the key lands in a plugin-written config with no ApiKey element" {
+    # What TheTVDB actually writes on a fresh install: its own root element and
+    # no <ApiKey /> at all, because its serializer drops null settings. The
+    # installer used to anchor on </Configuration> and refuse this file.
+    cat >"$JF/plugins/configurations/Jellyfin.Plugin.Tvdb.xml" <<XML
+<?xml version="1.0" encoding="utf-8"?>
+<PluginConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <SubscriberPIN />
+  <CacheDurationInHours>1</CacheDurationInHours>
+  <OriginalTitle>true</OriginalTitle>
+</PluginConfiguration>
+XML
+    run prov install
+    [ "$status" -eq 0 ]
+    printf '%s\n' "${lines[@]}" | grep -qiF 'filled the ApiKey'
+    local cfg="$JF/plugins/configurations/Jellyfin.Plugin.Tvdb.xml"
+    grep -qF "<ApiKey>$TVDB_KEY</ApiKey>" "$cfg"
+    grep -qF '<CacheDurationInHours>1</CacheDurationInHours>' "$cfg"
+    grep -qF '<OriginalTitle>true</OriginalTitle>' "$cfg"
+}
+
+@test "a config file with no root element is refused by name" {
+    # The guard still has to fire when there is genuinely nowhere to write —
+    # a refusal naming the file beats inventing a document shape.
+    printf '<?xml version="1.0" encoding="utf-8"?>\n' \
+        >"$JF/plugins/configurations/Jellyfin.Plugin.Tvdb.xml"
+    run prov install
+    [ "$status" -ne 0 ]
+    printf '%s\n' "${lines[@]}" | grep -qF 'Jellyfin.Plugin.Tvdb.xml'
+    printf '%s\n' "${lines[@]}" | grep -qiF 'no place to write'
+}
+
 @test "a pin in the TVDB secret lands in the plugin config" {
     # A subscriber-shaped key needs the account's PIN beside it; a licensed key
     # does not, so the element appears only when the secret carries one.