manage/openspec/changes/jellyfin-service-registry/proposal.md

Proposal — Jellyfin service-registry migration (completion)

Change: jellyfin-service-registry Phase: proposal Date: 2026-06-23

Problem

The service-registry foundation already moved Jellyfin/Jellyseerr resolution into dependencies.py (get_jellyfin_client, get_jellyseerr_client, get_user_id) using jellyfin_service_id. The frontend Applications, Media, and Users pages already consume useServiceInstances("jellyfin").

However, the machine-level config still carries legacy Jellyfin DNA that is now dead or misleading:

• DEFAULT_SERVICES = ["monitoring", "files", "jellyfin"] in settings_store.py auto-tags every local machine as a Jellyfin source.
• The Settings machine editor still exposes services multi-select that can include jellyfin, even though Jellyfin is selected via the Services page, not via a machine.
• MonitoringMachine types still carry media_root and path_prefix fields whose original purpose was Jellyfin→SSH path mapping, but the path-mapping logic in path_utils.py now operates independently and those fields are no longer read by the media/file flows.
• Documentation still describes machine-level Jellyfin fields in places.

This creates UI confusion (two places to think about Jellyfin) and stale surface area.

Goal

Cleanly complete the Jellyfin migration onto the service registry:

1. Remove Jellyfin from the machine services taxonomy entirely.
2. Remove dead media_root / path_prefix machine fields from backend, frontend types, Settings form, and tests.
3. Update path-resolution helpers to rely only on the Jellyfin service config (or explicit path-prefix settings on the service record if needed), not on machine fields.
4. Update docs and changelog.

Non-goals

• Do NOT change how Jellyfin/Jellyseerr clients are resolved in dependencies.py — that is already correct.
• Do NOT remove the jellyfin / jellyseerr service definitions.
• Do NOT add new service types or widgets in this change.

Acceptance

• grep -R "media_root\|path_prefix" backend/src frontend/src returns only path_utils.py and its tests (if those helpers remain) or nothing (if the helpers are removed).
• jellyfin no longer appears in machine services options in the Settings UI.
• DEFAULT_SERVICES no longer includes jellyfin.
• Backend and frontend test suites remain green.
• Docs/CHANGELOG explain the final migration.