.claude/skills/ersatztv/SKILL.md

@@ -433,6 +433,27 @@ Consumers reach ETV **only through Dispatcharr** (`ErsatzTV → Dispatcharr →
   `GET`/`PUT /api/v1/settings/iptv` (`iptv.base_url`, ersatztv#340, `iptv.base-url`) — to pin them to
   a fixed public origin; unset falls back byte-identical to the old behavior. The base64-upload
   workaround in `docs/Docker/ErsatzTV.md` is only needed if that setting is left unset.
+- **No usable logo ⇒ no on-screen bug, from every attachment point** (ersatztv#510, 2026-07-26,
+  `ffmpeg.watermark-resolution-unified`). A `ChannelLogo` watermark resolves through one shared
+  `WatermarkSelector.ResolveWatermark` whether it came from a playout item, the channel, the global
+  setting, **or a deco**. A missing cached file, an un-migrated external URL, and a channel with no logo
+  artwork each render *without* a bug and log a warning. So when debugging "this channel has a watermark
+  configured but no bug appears", grep the log for `has no logo artwork` / `no longer exists` before
+  suspecting the ffmpeg pipeline.
+  - Before #510 the **deco** path alone was unchecked and returned the generated-initials nameplate
+    (`/iptv/logos/gen`) for a logoless channel — it genuinely rendered. That fallback is now off
+    everywhere; reviving it via the image cache is ersatztv#652.
+  - **Not covered:** the song-progress overlay is built as a `WatermarkOptions` directly by the
+    streaming/troubleshooting handlers, bypassing the resolver, and is still unchecked — ersatztv#653.
+- **`/iptv/logos/gen` is unauthenticated**, unlike the rest of `/iptv`: `ConditionalIptvAuthorizeFilter`
+  is a class-level attribute on `IptvController` only, and that route lives on `ArtworkController`.
+  Handy for probing, and the reason a container-internal self-fetch of a generated logo succeeds.
+- **Seeding a deco watermark for testing is fully API-driven** (no SQLite needed): `POST /api/v1/watermarks`
+  (needs the full required field set — check `v1.json`), `POST /api/v1/decos/groups`, `POST /api/v1/decos`,
+  `PUT /api/v1/decos/{id}` (set `watermarkMode` + `watermarkIds`), then `PUT /api/v1/playouts/{id}/deco`.
+  Use `watermarkMode: "Override"` to make the deco watermark the only one selected. Note branding is
+  **not** testable through the troubleshooting-playback API (`testing.troubleshoot-path-cannot-test-branding`)
+  — drive a real channel playout and capture a frame.
 - `logo_XX.png` files in the logos root dir are HTML garbage (broken downloads), not actual logos — ignore them
 
 ### Other