.claude/skills/jellyfin/ is a stale divergent copy, not the symlink CLAUDE.md describes — it documents auth that v12 only accepts by legacy opt-in #617

Closed
opened 2026-07-25 17:27:55 +02:00 by timothy · 3 comments
Owner

CLAUDE.md → Project Boundaries says:

Jellyfin skill → server-management (symlinked)

It is not a symlink. /Users/timothy/ersatztv/.claude/skills/jellyfin/ is a real directory holding a stale fork of the canonical ~/server-management/.claude/skills/jellyfin/SKILL.md.

Divergence

ersatztv copy server-management (canonical)
lines 120 183
auth header X-Emby-Token presented as the pattern Authorization: MediaBrowser Token="…", with X-Emby-Token marked legacy
Jellyfin version unstated jellyfin/jellyfin:12.0-rc2 (migrated off linuxserver in #478)
DELETE /Items/{id} data-loss warning absent present, prominent (caused permanent data loss 3×)
host / config layout thin full jazz (#633) detail
Live TV topology "ErsatzTV as tuner" ErsatzTV → Dispatcharr → Jellyfin, "never add ErsatzTV directly"

Why it matters

Two of these are actively misleading:

  1. Auth. v12 rejects X-Emby-Token and ?api_key= with 401 unless EnableLegacyAuthorization=true. That flag is currently ON, so the stale copy's examples still work — but it is slated for removal in v13, and the local copy gives no hint that the pattern is deprecated. (I used X-Emby-Token throughout #487 on that basis; it worked, but only incidentally.)
  2. The missing DELETE /Items/{id} warning. The canonical file leads with it because it has destroyed files three times. A session reading only the ersatztv copy never sees it.

The Live TV section is also wrong in a way that would cause duplicate channels if acted on.

Fix

Replace the directory with a symlink to the canonical copy, restoring the documented intent:

rm -rf /Users/timothy/ersatztv/.claude/skills/jellyfin
ln -s ~/server-management/.claude/skills/jellyfin /Users/timothy/ersatztv/.claude/skills/jellyfin

Worth checking the other cross-repo skills (ersatztv, and anything else CLAUDE.md claims is symlinked) for the same drift at the same time — this one presumably started as a symlink and got materialised by some copy operation.

Not done in-session because it deletes a checked-in tree and rewires another repo's skill, which is an operator call rather than part of #487.

Done-when

  • .claude/skills/jellyfin is a symlink to the server-management copy — relative symlink (mode 120000), matching the beets/radarr/sonarr pattern. PR fix(617): make the cross-repo skills real symlinks and reconcile the ersatztv skill (#639)
  • Other skills CLAUDE.md claims are symlinked are checked for the same drift — only ersatztv and jellyfin are cross-repo (closing-an-issue is ersatztv-local with no duplicate). ersatztv reconciled and made canonical here; server-management symlinks to it
  • Adversarial review passed — Review-verdict: MERGEABLE @ 01fb07a; the pass found and fixed a real YAML-frontmatter defect (see PR)
`CLAUDE.md` → Project Boundaries says: > Jellyfin skill → server-management (symlinked) It is **not** a symlink. `/Users/timothy/ersatztv/.claude/skills/jellyfin/` is a real directory holding a stale fork of the canonical `~/server-management/.claude/skills/jellyfin/SKILL.md`. ## Divergence | | ersatztv copy | server-management (canonical) | |---|---|---| | lines | 120 | 183 | | auth header | `X-Emby-Token` presented as *the* pattern | `Authorization: MediaBrowser Token="…"`, with `X-Emby-Token` marked legacy | | Jellyfin version | unstated | `jellyfin/jellyfin:12.0-rc2` (migrated off linuxserver in #478) | | `DELETE /Items/{id}` data-loss warning | **absent** | present, prominent (caused permanent data loss 3×) | | host / config layout | thin | full jazz (#633) detail | | Live TV topology | "ErsatzTV as tuner" | ErsatzTV → Dispatcharr → Jellyfin, "never add ErsatzTV directly" | ## Why it matters Two of these are actively misleading: 1. **Auth.** v12 rejects `X-Emby-Token` and `?api_key=` with 401 **unless** `EnableLegacyAuthorization=true`. That flag is currently ON, so the stale copy's examples still work — but it is slated for removal in v13, and the local copy gives no hint that the pattern is deprecated. (I used `X-Emby-Token` throughout #487 on that basis; it worked, but only incidentally.) 2. **The missing `DELETE /Items/{id}` warning.** The canonical file leads with it because it has destroyed files three times. A session reading only the ersatztv copy never sees it. The Live TV section is also wrong in a way that would cause duplicate channels if acted on. ## Fix Replace the directory with a symlink to the canonical copy, restoring the documented intent: ```bash rm -rf /Users/timothy/ersatztv/.claude/skills/jellyfin ln -s ~/server-management/.claude/skills/jellyfin /Users/timothy/ersatztv/.claude/skills/jellyfin ``` Worth checking the other cross-repo skills (`ersatztv`, and anything else CLAUDE.md claims is symlinked) for the same drift at the same time — this one presumably started as a symlink and got materialised by some copy operation. Not done in-session because it deletes a checked-in tree and rewires another repo's skill, which is an operator call rather than part of #487. ## Done-when - [x] `.claude/skills/jellyfin` is a symlink to the server-management copy — relative symlink (mode `120000`), matching the `beets`/`radarr`/`sonarr` pattern. PR #639 - [x] Other skills CLAUDE.md claims are symlinked are checked for the same drift — only `ersatztv` and `jellyfin` are cross-repo (`closing-an-issue` is ersatztv-local with no duplicate). `ersatztv` reconciled and made canonical here; server-management symlinks to it - [x] Adversarial review passed — `Review-verdict: MERGEABLE @ 01fb07a`; the pass found and fixed a real YAML-frontmatter defect (see PR)
timothy added the bugjellyfinpriority: medium labels 2026-07-25 17:28:00 +02:00
Author
Owner

Evidence for the second Done-when box: the ersatztv skill has the same drift, and it is worse

Found while running the completion checks for #616 (which asks whether a discovered API gotcha belongs in a skill file). This issue's second box — "Other skills CLAUDE.md claims are symlinked are checked for the same drift" — is now answered for ersatztv: it is also a real directory, not a symlink, and the two copies have diverged in BOTH directions.

/Users/timothy/ersatztv/.claude/skills/ersatztv/SKILL.md        215 lines  (git-tracked in ersatztv)
~/server-management/.claude/skills/ersatztv/SKILL.md            365 lines
                                                                338 differing lines

Unlike the jellyfin case, neither copy is simply "the stale one":

ersatztv copy server-management copy
REST API correct — /api/v1 with write paths; "do not hand-edit SQLite for something the API can do" stale and dangerous — description asserts "The REST API is read-only for most operations — channel/collection/schedule CRUD requires SQLite DB scripting"
Blazor UI correct — removed in #91b, SPA at /app is the only UI not reflected
Host / topology thin fresher — jazz move (#633), Dispatcharr-reaches-by-IP, ForwardedHeaders__KnownNetworks
Self-awareness carries a "this section was wrong for the fork — corrected 2026-07-21" banner —

Why the server-management copy is the more harmful one. Its description: is what the model reads when deciding to load the skill, and it says CRUD requires SQLite DB scripting. That actively routes a session toward hand-editing the prod SQLite for operations the API has supported since the REST work landed — against a WAL-mode, root-owned DB on a live channel server. The jellyfin drift in this issue hid a DELETE /Items warning; this one advertises a riskier path as the normal one.

So a straight rm -rf + symlink in either direction loses correct content. This one needs a reconcile-then-symlink, not a replace — worth deciding which repo is canonical for it (CLAUDE.md → Project Boundaries says ersatztv OWNS the ErsatzTV skill in server-management, i.e. content owner and host repo differ, which is probably how it drifted).

Please carry these into the reconciled copy (from #616, merged as PR #635)

The skill documents GET /api/v1/playouts and POST /api/v1/channels/{id}/playout/reset adjacently but says nothing about paging or id spaces. Both are now settled in api.paging-zero-based:

  • pageNum is 0-based. Starting at 1 silently skips a page and returns a short set with no error.
  • pageSize is clamped per-endpoint (100 typical, 200 auto-tune members, 1000 search/all-items); the offset derives from the effective size. Page to completeness against totalCount.
  • The reset endpoint takes a CHANNEL id, not the playout id from a playout row. The id spaces overlap numerically, so the wrong one returns a plausible 202 against a different channel. Playout rows carry channelId (list since #297; detail since #616) — use that.

I deliberately did not patch either copy, because editing one side of a 338-line bidirectional divergence deepens exactly the problem this issue exists to fix.

## Evidence for the second Done-when box: the `ersatztv` skill has the same drift, and it is worse Found while running the completion checks for #616 (which asks whether a discovered API gotcha belongs in a skill file). This issue's second box — *"Other skills CLAUDE.md claims are symlinked are checked for the same drift"* — is now answered for `ersatztv`: **it is also a real directory, not a symlink, and the two copies have diverged in BOTH directions.** ``` /Users/timothy/ersatztv/.claude/skills/ersatztv/SKILL.md 215 lines (git-tracked in ersatztv) ~/server-management/.claude/skills/ersatztv/SKILL.md 365 lines 338 differing lines ``` Unlike the jellyfin case, neither copy is simply "the stale one": | | ersatztv copy | server-management copy | |---|---|---| | REST API | correct — `/api/v1` **with write paths**; "do not hand-edit SQLite for something the API can do" | **stale and dangerous** — description asserts *"The REST API is read-only for most operations — channel/collection/schedule CRUD requires SQLite DB scripting"* | | Blazor UI | correct — removed in #91b, SPA at `/app` is the only UI | not reflected | | Host / topology | thin | fresher — jazz move (#633), Dispatcharr-reaches-by-IP, `ForwardedHeaders__KnownNetworks` | | Self-awareness | carries a "this section was wrong for the fork — corrected 2026-07-21" banner | — | **Why the server-management copy is the more harmful one.** Its `description:` is what the model reads when deciding to load the skill, and it says CRUD *requires SQLite DB scripting*. That actively routes a session toward hand-editing the prod SQLite for operations the API has supported since the REST work landed — against a WAL-mode, root-owned DB on a live channel server. The jellyfin drift in this issue hid a `DELETE /Items` warning; this one advertises a riskier path as the normal one. So a straight `rm -rf` + symlink in either direction **loses correct content**. This one needs a reconcile-then-symlink, not a replace — worth deciding which repo is canonical for it (`CLAUDE.md` → Project Boundaries says *ersatztv OWNS the ErsatzTV skill in server-management*, i.e. content owner and host repo differ, which is probably how it drifted). ## Please carry these into the reconciled copy (from #616, merged as PR #635) The skill documents `GET /api/v1/playouts` and `POST /api/v1/channels/{id}/playout/reset` adjacently but says nothing about paging or id spaces. Both are now settled in `api.paging-zero-based`: - **`pageNum` is 0-based.** Starting at 1 silently skips a page and returns a short set with no error. - **`pageSize` is clamped per-endpoint** (100 typical, 200 auto-tune members, 1000 search/all-items); the offset derives from the *effective* size. Page to completeness against `totalCount`. - **The reset endpoint takes a CHANNEL id, not the playout id** from a playout row. The id spaces overlap numerically, so the wrong one returns a plausible 202 against a different channel. Playout rows carry `channelId` (list since #297; detail since #616) — use that. I deliberately did **not** patch either copy, because editing one side of a 338-line bidirectional divergence deepens exactly the problem this issue exists to fix.
timothy added the in-progress label 2026-07-26 00:25:34 +02:00
Author
Owner

Claiming — bundled with #615 (shared jellyfin label).

Operator decision taken on the canonical-owner question raised in the comment above:

  • jellyfin → server-management is canonical. ersatztv's copy is strictly worse (no bidirectional divergence to preserve), so: delete the local tree, replace with a relative symlink.
  • ersatztv → ersatztv is canonical, matching CLAUDE.md → Project Boundaries ("ersatztv OWNS … the ErsatzTV skill in server-management"). Because that pair diverged in both directions, this is a reconcile-then-symlink, not a replace: port server-management's fresher host/topology content (jazz #633, Dispatcharr-reaches-by-IP, ForwardedHeaders__KnownNetworks) into the ersatztv copy, kill the dangerous "CRUD requires SQLite DB scripting" claim in its description:, fold in the api.paging-zero-based facts requested above, and only then symlink server-management → ersatztv.

Relative-symlink form follows the existing cross-repo pattern already used in server-management (beets, radarr, sonarr, … → ../../../<repo>/.claude/skills/<name>).

Claiming — bundled with #615 (shared `jellyfin` label). Operator decision taken on the canonical-owner question raised in the comment above: - **`jellyfin`** → server-management is canonical. ersatztv's copy is strictly worse (no bidirectional divergence to preserve), so: delete the local tree, replace with a relative symlink. - **`ersatztv`** → ersatztv is canonical, matching `CLAUDE.md` → Project Boundaries (*"ersatztv OWNS … the ErsatzTV skill in server-management"*). Because that pair diverged in **both** directions, this is a **reconcile-then-symlink**, not a replace: port server-management's fresher host/topology content (jazz #633, Dispatcharr-reaches-by-IP, `ForwardedHeaders__KnownNetworks`) into the ersatztv copy, kill the dangerous *"CRUD requires SQLite DB scripting"* claim in its `description:`, fold in the `api.paging-zero-based` facts requested above, and only then symlink server-management → ersatztv. Relative-symlink form follows the existing cross-repo pattern already used in server-management (`beets`, `radarr`, `sonarr`, … → `../../../<repo>/.claude/skills/<name>`).
Author
Owner

Closing record

Outcome: Both cross-repo skills are now a single copy each, reached by relative symlink from the other repo. Landed as ersatztv PR #639 (merged) plus two commits in timothy/server-management (34873a6, 05712ac).

skill canonical location other repo
jellyfin ~/server-management/.claude/skills/jellyfin (218 lines) ~/ersatztv/.claude/skills/jellyfin → symlink
ersatztv ~/ersatztv/.claude/skills/ersatztv (439 lines) ~/server-management/.claude/skills/ersatztv → symlink

Root cause: Both started as symlinks and were materialised into real directories by some copy operation, after which they drifted independently. jellyfin drifted one way (ersatztv's copy purely stale). ersatztv drifted both ways, which is why a rm -rf + symlink in either direction would have destroyed correct content.

Decisions/conventions changed: none new. CLAUDE.md → Project Boundaries updated to state where each canonical copy lives and to record the worktree caveat below.

Reusable knowledge:

  • The issue's own premise was half wrong, and following it literally would have caused data loss. The comment framed server-management's ersatztv copy as "stale and dangerous" and ersatztv's as "correct". In fact server-management's was wrong only in its description: — its body already said "Full REST CRUD is available under /api/v1" and it carried ~150 lines ersatztv's lacked. Taking ersatztv's 215-line copy as the base, as the issue implied, would have silently dropped backup/deploy, test/prod topology, the #500 streaming-mode analysis, VAAPI-vs-QSV and the channel-creation checklist. When a bug report says "file A is stale, file B is correct", diff both bodies before believing the direction.
  • A description: containing ": " breaks the whole skill. An unquoted YAML scalar with a colon-space parses as a mapping, so yaml.safe_load fails and the frontmatter never loads — silently killing the skill discovery the description exists to drive. I introduced this with IMPORTANT: the fork has…, and the canonical jellyfin file had the identical latent defect (IMPORTANT: Never use DELETE /Items/{id}) — meaning its prominent data-loss warning may never have been reaching the model. Both now quoted. Validate frontmatter by parsing it, not by reading it; eyeballing cannot see this.
  • A relative cross-repo symlink resolves only in the canonical checkout, so these skills are unavailable inside a git worktree. Inherent to the pattern already used for beets/radarr/sonarr; documented in CLAUDE.md rather than diverging to absolute paths.
  • Only ersatztv and jellyfin are cross-repo — closing-an-issue is ersatztv-local with no duplicate anywhere.

Verification:

  • Both symlinks committed as mode 120000 with correct relative targets; both SKILL.md files readable through the symlink from either repo, and md5 confirms one copy each (no divergence possible by construction now).
  • Frontmatter of both parses with yaml.safe_load.
  • No content lost in either direction: 22 key terms from the old ersatztv copy all still present; all 14 lines dropped relative to server-management's copy verified as exactly the intentional corrections.
  • Every corrected claim re-checked against a decision record or the live prod API, not memory — including three the issue never mentioned: prod has no auto-update (auto_update: false, contradicted CLAUDE.md), ErsatzTV's Music Videos library is 16 and Standup 14 (not 8/9), and both logo gotchas were fixed upstream in #502 / #340.
  • CI green on 01fb07a; Review-verdict: MERGEABLE @ 01fb07a.

Deferred: none.

Docs updated: CLAUDE.md (both Project-Boundaries lines). No docs/*.md change needed — no route, endpoint, SPA screen or convention changed.

## Closing record **Outcome:** Both cross-repo skills are now a single copy each, reached by relative symlink from the other repo. Landed as ersatztv **PR #639** (merged) plus two commits in `timothy/server-management` (`34873a6`, `05712ac`). | skill | canonical location | other repo | |---|---|---| | `jellyfin` | `~/server-management/.claude/skills/jellyfin` (218 lines) | `~/ersatztv/.claude/skills/jellyfin` → symlink | | `ersatztv` | `~/ersatztv/.claude/skills/ersatztv` (439 lines) | `~/server-management/.claude/skills/ersatztv` → symlink | **Root cause:** Both started as symlinks and were materialised into real directories by some copy operation, after which they drifted independently. `jellyfin` drifted one way (ersatztv's copy purely stale). `ersatztv` drifted **both** ways, which is why a `rm -rf` + symlink in either direction would have destroyed correct content. **Decisions/conventions changed:** none new. `CLAUDE.md` → Project Boundaries updated to state where each canonical copy lives and to record the worktree caveat below. **Reusable knowledge:** - **The issue's own premise was half wrong, and following it literally would have caused data loss.** The comment framed server-management's `ersatztv` copy as "stale and dangerous" and ersatztv's as "correct". In fact server-management's was wrong **only in its `description:`** — its body already said *"Full REST CRUD is available under `/api/v1`"* and it carried ~150 lines ersatztv's lacked. Taking ersatztv's 215-line copy as the base, as the issue implied, would have silently dropped backup/deploy, test/prod topology, the #500 streaming-mode analysis, VAAPI-vs-QSV and the channel-creation checklist. **When a bug report says "file A is stale, file B is correct", diff both bodies before believing the direction.** - **A `description:` containing `": "` breaks the whole skill.** An unquoted YAML scalar with a colon-space parses as a mapping, so `yaml.safe_load` fails and the frontmatter never loads — silently killing the skill discovery the description exists to drive. I introduced this with `IMPORTANT: the fork has…`, and **the canonical jellyfin file had the identical latent defect** (`IMPORTANT: Never use DELETE /Items/{id}`) — meaning its prominent data-loss warning may never have been reaching the model. Both now quoted. **Validate frontmatter by parsing it, not by reading it**; eyeballing cannot see this. - **A relative cross-repo symlink resolves only in the canonical checkout**, so these skills are unavailable inside a git worktree. Inherent to the pattern already used for `beets`/`radarr`/`sonarr`; documented in `CLAUDE.md` rather than diverging to absolute paths. - Only `ersatztv` and `jellyfin` are cross-repo — `closing-an-issue` is ersatztv-local with no duplicate anywhere. **Verification:** - Both symlinks committed as mode `120000` with correct relative targets; both `SKILL.md` files readable through the symlink from either repo, and `md5` confirms **one copy each** (no divergence possible by construction now). - Frontmatter of both parses with `yaml.safe_load`. - **No content lost in either direction:** 22 key terms from the old ersatztv copy all still present; all 14 lines dropped relative to server-management's copy verified as exactly the intentional corrections. - Every corrected claim re-checked against a decision record or the live prod API, not memory — including three the issue never mentioned: prod has **no auto-update** (`auto_update: false`, contradicted `CLAUDE.md`), ErsatzTV's Music Videos library is **16** and Standup **14** (not 8/9), and both logo gotchas were fixed upstream in #502 / #340. - CI green on `01fb07a`; `Review-verdict: MERGEABLE @ 01fb07a`. **Deferred:** none. **Docs updated:** `CLAUDE.md` (both Project-Boundaries lines). No `docs/*.md` change needed — no route, endpoint, SPA screen or convention changed.
timothy removed the in-progress label 2026-07-26 10:48:52 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#617