Initial plan: SyncPlay drift fix via quality negotiation, host-relay, active drift correction

CLAUDE.md

@@ -0,0 +1,65 @@
+# JellyfinSyncPlus
+
+Custom Jellyfin plugin replacing/augmenting SyncPlay to fix drift when
+watching remotely with friends. Full architecture and rationale: [PLAN.md](PLAN.md)
+-- read it before making design changes, it captures decisions already made
+with the user so they don't need to be re-litigated.
+
+## What this is, in one paragraph
+
+Jellyfin's SyncPlay drifts because group members end up on different
+transcode/direct-play paths and the correction mechanism is weak. This plugin
+does three things: (1) picks one quality profile the whole group can use, (2)
+relays one member's ("host") already-transcoding stream to the rest of the
+group instead of spinning up N independent transcode jobs, (3) runs an active
+drift-correction loop on top (virtual playhead + NTP-style clock calibration +
+heartbeat/EMA drift measurement + speed-nudge-or-hard-reseek). See PLAN.md
+section "Architecture -- three pillars" for the full detail on each.
+
+## Real infra this targets -- not hypothetical, verified against the actual repo
+
+- Jellyfin: `linuxserver/jellyfin:10.11.6` in the `entertainment` k8s
+  namespace. **Build the plugin against this exact server version's ABI.**
+  If the deployment's pinned tag ever changes, re-check
+  `/home/cynic/gitea/entertainment/base/jellyfin/deployment.yaml` rather than
+  assuming this file is still current.
+- Config hostPath: `/mnt/redundant/k8s/jellyfin/config` (where a real
+  Jellyfin's `plugins/` directory would live).
+- Deployed via ArgoCD app `entertainment`, **does not auto-sync** -- deploys
+  need `kubectl patch application entertainment -n argocd --type merge -p
+  '{"operation":{"sync":{"revision":"HEAD"}}}'` after a push.
+- Sibling repo `/home/cynic/gitea/entertainment` holds the k8s manifests.
+  Sibling repo `/home/cynic/gitea/MR-Discord` is a working example of this
+  exact cluster's tag-push -> Gitea Actions -> build -> deploy pipeline --
+  copy its `.gitea/workflows/` pattern when this project reaches Phase 5
+  (packaging/release) rather than designing a new one from scratch.
+
+## Guardrails -- do not skip these
+
+- **Never restart or redeploy the real k8s Jellyfin pod as part of routine
+  dev iteration.** It's a live, shared instance -- a restart interrupts
+  whoever's currently watching something. Use the local throwaway Docker
+  Jellyfin (see PLAN.md "Dev / test / iterate workflow", loop 1) for
+  everyday iteration. Only touch the real pod for a deliberate milestone
+  test, and confirm with the user first each time -- this is not a standing
+  authorization.
+- **Never push this repo to a Gitea remote without being asked.** No remote
+  has been created for this project yet as of the initial scaffold.
+- Don't assume the public Jellyfin plugin SDK (`Jellyfin.Controller` NuGet)
+  is sufficient -- SyncPlay group internals and transcode-session state are
+  not part of its stable surface. Expect to need a source checkout of
+  `jellyfin/jellyfin@v10.11.6` for some of this. Confirmed in PLAN.md's
+  "Known friction / risks" -- don't rediscover this the hard way mid-phase.
+
+## Working conventions for this repo
+
+- Follow the phase breakdown in PLAN.md in order; don't jump to Phase 3
+  (drift correction) before Phase 1/2 (quality negotiation, host-relay) are
+  working, since drift correction is meaningless to tune against N
+  independently-transcoding clients.
+- No code exists yet as of this file's creation -- the repo currently
+  contains only PLAN.md and this file. The first real work is Phase 0
+  (scaffold + confirm a trivial plugin loads in a local dev Jellyfin).
+- Keep PLAN.md's "Open questions" section updated as those questions get
+  resolved -- move resolved ones into "Scope confirmed with user" with the
+  actual decision, don't just delete them.