fix(jupiter): add Intel compute-runtime for OpenCL HDR tone-mapping

HDR HEVC transcodes were failing with "Failed to get number of OpenCL
platforms: -1001" (CL_PLATFORM_NOT_FOUND_KHR). The tonemap_opencl
filter jellyfin-ffmpeg uses for HDR-to-SDR tone-mapping needs an OpenCL
ICD, which intel-media-driver/vpl-gpu-rt don't provide on their own.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/superpowers/plans/2026-07-26-jellyfin-hw-transcoding.md

@@ -0,0 +1,154 @@
+# Jellyfin Hardware Transcoding (jupiter) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Give jupiter's Jellyfin service access to the Intel iGPU's VAAPI render node so Quick Sync hardware transcoding can be enabled, instead of every transcode falling back to CPU.
+
+**Architecture:** One NixOS module change (`modules/environments/jellyfin/default.nix`) grants the `jellyfin` systemd service supplementary access to the `video`/`render` groups and installs `libva-utils` for verification. This is declarative and build-verifiable from the Mac. Enabling Quick Sync inside Jellyfin's own dashboard, and the on-machine verification, is a manual step run by the user on jupiter after deploy — the NixOS module has no option for it and this environment's convention is that the assistant never SSHes into jupiter directly (see `docs/superpowers/specs/2026-07-26-jellyfin-hw-transcoding.md`).
+
+**Tech Stack:** NixOS (flake-parts), nixpkgs `services.jellyfin` module, VAAPI/`intel-media-driver`, `libva-utils`.
+
+## Global Constraints
+
+- No SSH from the assistant into jupiter — all on-machine commands are given to the user to run and paste back.
+- Follow the existing profile pattern in `modules/environments/jellyfin/default.nix` (`config = lib.mkIf cfg.enable { ... }`); don't introduce a new toggle option — hardcode the hardware-acceleration wiring on, per the approved spec.
+- Verify locally via `nix eval` / `nix build` before asking the user to deploy.
+
+---
+
+### Task 1: Grant Jellyfin access to the iGPU and verify the build
+
+**Files:**
+- Modify: `modules/environments/jellyfin/default.nix`
+
+**Interfaces:**
+- Produces: `systemd.services.jellyfin.serviceConfig.SupplementaryGroups = [ "video" "render" ];` — verified via `nix eval` in Step 2.
+
+- [ ] **Step 1: Add the device-access config and `libva-utils` package**
+
+Read the current file first (`modules/environments/jellyfin/default.nix`), then edit the `config = lib.mkIf cfg.enable { ... }` block so it reads:
+
+```nix
+  config = lib.mkIf cfg.enable {
+    services.jellyfin = {
+      enable = true;
+      openFirewall = true;
+    };
+
+    environment.systemPackages = [ pkgs.libva-utils ];
+
+    my.homepage.services = [
+      {
+        group = "Media";
+        name = "Jellyfin";
+        description = "Media server";
+        href = "http://${hostName}:${toString port}";
+        icon = "jellyfin.png";
+      }
+    ];
+
+    systemd.services.jellyfin = {
+      after = [ "network-online.target" ];
+      serviceConfig.SupplementaryGroups = [
+        "video"
+        "render"
+      ];
+    };
+  };
+```
+
+Note the two existing `systemd.services.jellyfin` keys (`after`) and the new `serviceConfig.SupplementaryGroups` now live in the same attrset — don't create a second `systemd.services.jellyfin = { ... }` block, it would overwrite the first.
+
+- [ ] **Step 2: Verify the rendered config with `nix eval`**
+
+Run (from the repo root on the Mac):
+
+```bash
+nix eval '.#nixosConfigurations.jupiter.config.systemd.services.jellyfin.serviceConfig.SupplementaryGroups' \
+  --extra-experimental-features 'nix-command flakes'
+```
+
+Expected output: `[ "video" "render" ]`
+
+- [ ] **Step 3: Verify the machine still builds**
+
+Run:
+
+```bash
+nix build '.#nixosConfigurations.jupiter.config.system.build.toplevel' \
+  --extra-experimental-features 'nix-command flakes' --no-link
+```
+
+Expected: build succeeds with no errors (may take a while; watch for any evaluation error mentioning `jellyfin` or `libva-utils`).
+
+- [ ] **Step 4: Format and commit**
+
+```bash
+nixfmt-rfc-style modules/environments/jellyfin/default.nix
+git add modules/environments/jellyfin/default.nix
+git commit -m "feat(jellyfin): grant iGPU access for Quick Sync hardware transcoding"
+```
+
+---
+
+### Task 2: Deploy on jupiter and enable Quick Sync (user-executed)
+
+**Files:** none (on-machine deploy + Jellyfin dashboard UI)
+
+**Interfaces:**
+- Consumes: the `SupplementaryGroups` change from Task 1, already merged into the flake.
+
+These steps run **on jupiter**, by the user — paste the output back so we can confirm each one before moving to the next.
+
+- [ ] **Step 1: Deploy**
+
+```bash
+sudo nixos-rebuild switch --flake '.#jupiter'
+```
+
+Expected: switch succeeds, no errors mentioning `jellyfin`.
+
+- [ ] **Step 2: Confirm the service picked up the new groups**
+
+```bash
+systemctl show jellyfin -p SupplementaryGroups
+systemctl status jellyfin --no-pager
+```
+
+Expected: `SupplementaryGroups=video render` (order may vary) and the service is `active (running)`.
+
+- [ ] **Step 3: Confirm VAAPI driver loads**
+
+```bash
+vainfo
+```
+
+Expected: output starts with something like `vainfo: VA-API version: 1.x` and `Driver version: Intel iHD driver`, followed by a list of supported VAProfiles/VAEntrypoints (e.g. `VAProfileH264Main : VAEntrypointVLD`, `VAEntrypointEncSlice`).
+
+If this instead prints a permissions or "no VA display" error, paste it back — that means the group grant isn't reaching the process and Task 1 needs a follow-up fix (e.g. the jellyfin service may be more sandboxed than expected, requiring an explicit `DeviceAllow=char-drm rw` in `serviceConfig` as well).
+
+- [ ] **Step 4: Enable Quick Sync in the Jellyfin dashboard**
+
+In the Jellyfin web UI:
+1. **Dashboard → Playback**.
+2. Hardware acceleration: **Intel QuickSync (QSV)**.
+3. VA-API device: `/dev/dri/renderD128`.
+4. Enable hardware decoding for the codecs your library uses (H264 at minimum).
+5. If the library has HDR content, enable tone-mapping.
+6. Save.
+
+- [ ] **Step 5: Functional check**
+
+Play a file that requires transcoding (or force a lower quality in the client's playback settings to trigger one), then:
+
+```bash
+journalctl -u jellyfin -n 50 --no-pager
+```
+
+Look for a line referencing `qsv` or `vaapi` in the transcode command. Separately, watch CPU usage (`htop`) during playback — it should stay low on the core doing the transcode, rather than pegging at 100%, since the iGPU is now doing the encode/decode work.
+
+## Self-Review Notes
+
+- Spec coverage: NixOS change (Task 1) ✓, manual dashboard step (Task 2 Step 4) ✓, verification via `vainfo`/build (Task 1 Step 2-3, Task 2 Step 3) ✓, functional check (Task 2 Step 5) ✓. Toggle option explicitly excluded per approved spec — not present, correctly.
+- No placeholders — every step has literal commands/code.
+- `SupplementaryGroups` key/value matches exactly between Task 1 (produced) and Task 2 (consumed/checked).

docs/superpowers/specs/2026-07-26-jellyfin-hw-transcoding.md

@@ -0,0 +1,108 @@
+# Intel Quick Sync hardware transcoding for Jellyfin on jupiter
+
+## Problem
+
+Jellyfin streams stutter on jupiter whenever a client needs a transcode
+(unsupported codec/container, bitrate cap, or a client that can't
+direct-play). Transcoding currently runs entirely on CPU.
+
+jupiter's Intel iGPU is already usable at the OS level:
+
+- `hardware.graphics.enable = true` with `intel-media-driver` (the `iHD`
+  VAAPI driver) is configured in
+  `machines/jupiter/hardware-configuration.nix:20-27`.
+- The commented-out `i915.force_probe = "9a49"` kernel param there
+  corresponds to a Quick-Sync-capable Intel UHD iGPU, confirming the
+  hardware supports it.
+
+But `modules/environments/jellyfin/default.nix` never grants the
+`jellyfin` systemd service access to `/dev/dri`, so Jellyfin has no path
+to the GPU and silently falls back to software transcoding.
+
+## Goal
+
+Give the Jellyfin service access to the iGPU's VAAPI render node, so
+Quick Sync can be enabled in Jellyfin's own dashboard and transcodes are
+offloaded from the CPU.
+
+## Non-goals
+
+- Remote/external access or reverse-proxy tuning.
+- General CPU/RAM headroom review of jupiter.
+- A toggle option (`my.profiles.jellyfin.hardwareAcceleration.enable`) —
+  jupiter only has the one iGPU, so this is hardcoded on rather than
+  made configurable.
+
+## Design
+
+### NixOS change (declarative)
+
+In `modules/environments/jellyfin/default.nix`, inside the existing
+`config = lib.mkIf cfg.enable { ... }` block, grant the systemd service
+supplementary access to the `video` and `render` groups (the groups that
+own `/dev/dri/card*` and `/dev/dri/renderD*`):
+
+```nix
+systemd.services.jellyfin.serviceConfig.SupplementaryGroups = [
+  "video"
+  "render"
+];
+```
+
+This is additive to the existing `systemd.services.jellyfin.after = [
+"network-online.target" ];` block already in the file — both apply to
+the same service.
+
+Also add `libva-utils` to `environment.systemPackages` (or scoped to
+this module) so `vainfo` is available on jupiter to verify the driver
+loads correctly.
+
+### Manual step (not declarative)
+
+Jellyfin stores its transcoding/hardware-acceleration choice in its own
+internal `encoding.xml`, which the NixOS module does not expose as an
+option. After deploying the Nix change, one-time manual configuration in
+the Jellyfin dashboard is required:
+
+1. **Dashboard → Playback**.
+2. Hardware acceleration: **Intel QuickSync (QSV)**.
+3. VA-API device: `/dev/dri/renderD128`.
+4. Enable hardware decoding for the codecs your library actually uses
+   (H264 at minimum; HEVC/VP9 depending on iGPU generation).
+5. If any HDR content exists in the library, enable tone-mapping — this
+   is one of the more CPU-expensive operations Quick Sync can offload.
+
+## Verification
+
+Build-time (from the Mac, no SSH needed):
+
+```
+nix eval '.#nixosConfigurations.jupiter.config.systemd.services.jellyfin.serviceConfig.SupplementaryGroups' \
+  --extra-experimental-features 'nix-command flakes'
+```
+
+Expect `[ "video" "render" ]`.
+
+On jupiter after `sudo nixos-rebuild switch --flake '.#jupiter'`:
+
+```
+systemctl status jellyfin
+journalctl -u jellyfin -n 50 --no-pager
+vainfo
+```
+
+`vainfo` should list the `iHD` driver and print supported VAEntrypoints
+(VLD decode / encode profiles for H264/HEVC).
+
+Functional check: play a file on a client that forces transcoding (or
+force it manually via Jellyfin's playback quality setting), then in
+Jellyfin's dashboard **Activity/Now Playing** panel confirm the
+transcode reason and check that CPU usage on jupiter (`htop`) stays low
+during playback rather than pegging a core — Quick Sync offload should
+show up as low CPU, some GPU (`intel_gpu_top`) activity instead.
+
+## Open items
+
+- Exact supported codec list depends on the iGPU generation (device ID
+  `9a49`) — confirm via `vainfo` output once run, and enable only the
+  hardware decode paths it actually reports.

docs/superpowers/specs/2026-07-27-mibook-boot-desktop-choice-design.md

@@ -1,61 +0,0 @@
-# mibook: choose terminal-only vs desktop at boot
-
-## Goal
-
-Let mibook boot to a text console by default, with KDE fully installed and
-launchable on demand. The user decides after boot whether they need the
-graphical desktop, without rebuilding the system.
-
-## Behavior
-
-- mibook boots to a text console (`multi-user.target`). SDDM and Plasma do
-  **not** start automatically.
-- KDE (SDDM + Plasma 6) remains fully installed.
-- Running `desktop` in the terminal starts the SDDM display manager, which
-  presents the graphical login screen; logging in there enters a Plasma 6
-  session.
-- No reverse command. To return to a text console, stop the display manager
-  (`sudo systemctl stop display-manager`) or reboot.
-- Other machines that enable the `kde-desktop` profile are unaffected; their
-  desktop still starts on boot.
-
-## Implementation
-
-### `modules/environments/kde-desktop/default.nix`
-
-Add an opt-out option to the existing profile:
-
-- New option `my.profiles.kde-desktop.startOnBoot`, a boolean defaulting to
-  `true`. The default preserves the current behavior for every consumer.
-- The existing `config` block (SDDM, Plasma 6, user packages) stays enabled
-  whenever the profile is enabled, regardless of `startOnBoot`.
-- When `startOnBoot = false`, additionally apply:
-  - `systemd.services.display-manager.wantedBy = lib.mkForce [ ];` so SDDM is
-    defined but not pulled in by any boot target.
-  - `systemd.defaultUnit = "multi-user.target";` so the boot target is the
-    text console.
-  - A `desktop` command provided via
-    `pkgs.writeShellScriptBin "desktop" "exec sudo systemctl start display-manager.service"`,
-    added to `environment.systemPackages`.
-
-### `machines/mibook/environments.nix`
-
-Set `kde-desktop.startOnBoot = false;` alongside the existing
-`kde-desktop.enable = true;`.
-
-## Testing / verification
-
-- `nix build '.#nixosConfigurations.mibook.config.system.build.toplevel'`
-  builds without error.
-- After `nixos-rebuild switch` on mibook: system boots to a TTY, no SDDM;
-  running `desktop` brings up the SDDM login and a working Plasma session.
-- Confirm jupiter (or any non-mibook consumer) is unchanged: its evaluated
-  `systemd.defaultUnit` / display-manager wantedBy are not altered.
-
-## Trade-offs
-
-- `desktop` relies on `sudo`; the user has sudo access, so no extra
-  configuration is required.
-- Chose "boot to terminal, launch on demand" over a GRUB boot-menu entry
-  because it is more robust across NixOS generations and needs no fragile
-  static kernel entries.

flake.lock

@@ -89,11 +89,11 @@
         "nixpkgs-regression": "nixpkgs-regression"
       },
       "locked": {
-        "lastModified": 1784762557,
-        "narHash": "sha256-R/r6jRnANV50c8F5Fz5+1Q1moab0IGWRk+cg5ME2nMY=",
+        "lastModified": 1784375420,
+        "narHash": "sha256-dt1zVj4MRpmffhsgQk+3tx1m/pFTXbtVWrn5KZ1y+8Q=",
         "owner": "NixOS",
         "repo": "nix",
-        "rev": "d10c84cd0cc0efdcb29cf2611caf5fbcd10fa071",
+        "rev": "bebd2f851a304e9fb2e143ce0cbeff577c6a37ac",
         "type": "github"
       },
       "original": {
@@ -143,11 +143,11 @@
         "nixpkgs": "nixpkgs_2"
       },
       "locked": {
-        "lastModified": 1784723954,
-        "narHash": "sha256-1CfD8ZUjCkTgjsneLZ/lxCHhgDfqxxE7/GX0MmsgiqA=",
+        "lastModified": 1784310968,
+        "narHash": "sha256-rkSPTePrKqs4dg+i7ZFCq93+HrClac6oSwXX927SVjA=",
         "owner": "NixOS",
         "repo": "nixos-hardware",
-        "rev": "a017f5b72210026af5b3ac5949f08d94380a6fbd",
+        "rev": "779c32a00155994c86cde8213a8dd4df139d4355",
         "type": "github"
       },
       "original": {
@@ -218,11 +218,11 @@
     },
     "nixpkgs-unstable": {
       "locked": {
-        "lastModified": 1784796856,
-        "narHash": "sha256-vwxWgF+Gj276WznzGb1LxGsK/39HaQwgQXiU3EkC844=",
-        "rev": "e2587caef70cea85dd97d7daab492899902dbf5d",
+        "lastModified": 1784497964,
+        "narHash": "sha256-WhdsTtaih3DgTPP/PX023b36UNQyMzEoi6GkPyGx0y4=",
+        "rev": "241313f4e8e508cb9b13278c2b0fa25b9ca27163",
         "type": "tarball",
-        "url": "https://releases.nixos.org/nixos/unstable/nixos-26.11pre1040357.e2587caef70c/nixexprs.tar.xz"
+        "url": "https://releases.nixos.org/nixos/unstable/nixos-26.11pre1037713.241313f4e8e5/nixexprs.tar.xz"
       },
       "original": {
         "id": "nixpkgs",
@@ -245,11 +245,11 @@
     },
     "nixpkgs_3": {
       "locked": {
-        "lastModified": 1784707089,
-        "narHash": "sha256-DUedXhD2Rg8q4Xyd07Sb90eZGy4gg6W+Vl/WbLNwAZo=",
-        "rev": "b3fe9581c9061c749abef42b6d4ee7b7c05c33fa",
+        "lastModified": 1784432872,
+        "narHash": "sha256-IX7j5TvSD7hYC9NZ8mgmq7pZ97mYyl24Qs4Tz4uyvO4=",
+        "rev": "fd1462031fdee08f65fd0b4c6b64e22239a77870",
         "type": "tarball",
-        "url": "https://releases.nixos.org/nixos/26.05/nixos-26.05.5845.b3fe9581c906/nixexprs.tar.xz"
+        "url": "https://releases.nixos.org/nixos/26.05/nixos-26.05.5591.fd1462031fde/nixexprs.tar.xz"
       },
       "original": {
         "id": "nixpkgs",

machines/jupiter/hardware-configuration.nix

@@ -35,6 +35,8 @@
       #vaapiIntel         # LIBVA_DRIVER_NAME=i965 (older but works better for Firefox/Chromium)
       libva-vdpau-driver
       libvdpau-va-gl
+      vpl-gpu-rt # oneVPL/MFX runtime, required for QSV (h264_qsv/hevc_qsv) session creation
+      intel-compute-runtime # OpenCL runtime, required for tonemap_opencl (HDR tone-mapping)
     ];
   };
 

machines/mibook/configuration.nix

@@ -44,14 +44,6 @@
 
   services.openssh.enable = true;
 
-  # KDE (PowerDevil) power settings: do nothing on lid close while on AC power.
-  # Shipped as a system-wide default; KConfig cascades so a user's own
-  # ~/.config/powerdevilrc will override this if present.
-  environment.etc."xdg/powerdevilrc".text = ''
-    [AC][SuspendAndShutdown]
-    LidAction=0
-  '';
-
   system = {
     stateVersion = "23.05";
     autoUpgrade.enable = true;

machines/mibook/environments.nix

@@ -6,7 +6,6 @@ in
 {
   my.profiles = {
     kde-desktop.enable = true;
-    kde-desktop.startOnBoot = false;
     zsh.enable = true;
     apps = {
       desktop_apps = true;

modules/environments/jellyfin/default.nix

@@ -22,6 +22,8 @@ in
       openFirewall = true;
     };
 
+    environment.systemPackages = [ pkgs.libva-utils ];
+
     my.homepage.services = [
       {
         group = "Media";
@@ -34,6 +36,10 @@ in
 
     systemd.services.jellyfin = {
       after = [ "network-online.target" ];
+      serviceConfig.SupplementaryGroups = [
+        "video"
+        "render"
+      ];
     };
   };
 }

modules/environments/kde-desktop/default.nix

@@ -11,19 +11,9 @@ in
 {
   options.my.profiles.kde-desktop = with lib; {
     enable = mkEnableOption "KDE Desktop Environment";
-    startOnBoot = mkOption {
-      type = types.bool;
-      default = true;
-      description = ''
-        Whether the display manager (SDDM) starts automatically at boot.
-        When false, the system boots to a text console and KDE can be
-        launched on demand with the `desktop` command.
-      '';
-    };
   };
 
-  config = lib.mkIf cfg.enable (lib.mkMerge [
-    {
+  config = lib.mkIf cfg.enable {
     services = {
       displayManager.sddm.enable = true;
       displayManager.sddm.wayland.enable = true;
@@ -33,15 +23,5 @@ in
       # Programms can be added here...
       numix-icon-theme
     ];
-    }
-    (lib.mkIf (!cfg.startOnBoot) {
-      # Boot to a text console; SDDM stays installed but is not pulled in
-      # by any boot target. Launch KDE on demand with `desktop`.
-      systemd.services.display-manager.wantedBy = lib.mkForce [ ];
-      systemd.defaultUnit = lib.mkForce "multi-user.target";
-      environment.systemPackages = [
-        (pkgs.writeShellScriptBin "desktop" "exec sudo systemctl start display-manager.service")
-      ];
-    })
-  ]);
+  };
 }