fix(mibook): boot-menu terminal choice via specialisation

The previous startOnBoot approach booted mibook headless by default and
locked the machine out: it is WiFi-only with credentials in KWallet, so
with no desktop session NetworkManager never joins the network (no SSH),
and boot stalled on NetworkManager-wait-online with the tty1 prompt
buried under service logs.

Replace it with a NixOS specialisation that adds a separate 'terminal'
GRUB entry:
- default entry boots KDE as before (identical to baseline);
- 'terminal' entry boots multi-user.target with autologin for finn and a
  'desktop' command to start SDDM on demand.
Also disable NetworkManager-wait-online so boot never stalls on the
network. Revert the kde-desktop startOnBoot option.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CfozKLQdUh5TzqyjSigLUx

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,145 @@
+# 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.
+
+## Post-deploy fix: two additional runtime packages required
+
+After the initial deploy (Task 1's `SupplementaryGroups` grant) and
+enabling QSV in the dashboard, HEVC HDR playback hung indefinitely
+(Direct Play worked for some titles; titles that needed a real
+transcode+tonemap never produced output). Root-caused via
+`journalctl -u jellyfin` and the per-session ffmpeg transcode log
+(`find / -xdev -iname '*ffmpeg-transcode*'`) — two separate runtimes
+were missing beyond `intel-media-driver` (which only provides VAAPI):
+
+1. **QSV session creation failed:** `Error creating a MFX session: -9`
+   / `Error initializing an MFX session: -3` on
+   `-init_hw_device qsv=qs@va`. VAAPI and QSV are separate runtimes on
+   Linux — QSV needs the oneVPL/MFX GPU implementation. Fix: added
+   `pkgs.vpl-gpu-rt` ("oneAPI Video Processing Library Intel GPU
+   implementation"; note `onevpl-intel-gpu` is the old, renamed
+   attribute) to `hardware.graphics.extraPackages` in
+   `machines/jupiter/hardware-configuration.nix`.
+
+2. **OpenCL device creation failed:** `Failed to get number of OpenCL
+   platforms: -1001` (`CL_PLATFORM_NOT_FOUND_KHR`) on
+   `-init_hw_device opencl=ocl@va`. The `tonemap_opencl` filter jellyfin
+   uses for HDR→SDR tone-mapping needs a working OpenCL ICD, which
+   nothing installed so far provides. Fix: added
+   `pkgs.intel-compute-runtime` ("Intel Graphics Compute Runtime oneAPI
+   Level Zero and OpenCL, supporting 12th Gen and newer" — matches
+   jupiter's Tiger Lake/Xe iGPU) to the same `extraPackages` list.
+
+Confirmed working end-to-end: HEVC HDR transcode with QSV encode +
+OpenCL tone-map runs at `speed=2.68x` realtime on jupiter's iGPU, and
+plays smoothly on Apple TV (JellyTV app).
+
+Both packages live in `machines/jupiter/hardware-configuration.nix`
+(`hardware.graphics.extraPackages`), alongside `intel-media-driver`,
+rather than in the jellyfin module itself — they're iGPU runtime
+capabilities, not something specific to the jellyfin service.

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

@@ -0,0 +1,105 @@
+# mibook: choose terminal-only vs desktop at boot
+
+## Goal
+
+Let mibook offer a choice, each time it boots, between the normal KDE desktop
+and a terminal-only ("server") mode with no graphical session — decided at
+boot, without rebuilding the system.
+
+## Background: why the first attempt failed
+
+The first implementation booted mibook to a text console by default
+(`systemd.defaultUnit = "multi-user.target"`, display manager not started) and
+provided a `desktop` command to start KDE on demand. On real hardware this
+locked the machine out:
+
+- **No SSH.** mibook is WiFi-only and its WiFi credentials are stored per-user
+  in KWallet ("agent-owned"). NetworkManager only receives the password once a
+  desktop session is running, so a headless boot never joins the network and
+  the machine has no IP — nothing to SSH into.
+- **No usable console.** The boot appeared to "hang" with no login prompt:
+  `NetworkManager-wait-online` stalled waiting for a network that never came
+  up, and the `getty` login prompt on tty1 was buried under later service
+  messages.
+
+Conclusion: a headless WiFi laptop cannot be reached remotely, and the plain
+console was hard to use. The design must (a) keep the desktop as the reliable
+default, (b) make the terminal path a deliberate, self-sufficient choice, and
+(c) not depend on the network being up.
+
+## Behavior
+
+- The **default GRUB entry** boots straight into KDE — unchanged from the
+  known-working baseline.
+- A **separate GRUB entry, `mibook (terminal)`** (a NixOS *specialisation*),
+  boots to a text console with **autologin** for `finn`. From there the user
+  can work in the shell or run `desktop` to bring KDE up (via SDDM).
+- The choice is made in the GRUB menu at boot — matching the original request
+  to "decide each time I boot."
+- Booting never stalls on the network.
+
+### Known limitation (documented, not fixed in config)
+
+In terminal mode WiFi will not connect on its own, because the password is
+stored per-user in KWallet. To reach mibook over SSH from terminal mode, the
+user must first save the WiFi as a **system** connection in KDE:
+network settings → the WiFi network → "All users may connect to this network".
+Until then, terminal mode is local-console-only. This is a one-time manual
+step outside the scope of the Nix config.
+
+## Implementation
+
+### `machines/mibook/configuration.nix`
+
+- Add a NixOS specialisation `specialisation.terminal.configuration`:
+  - `system.nixos.tags = [ "terminal" ];` — labels the generated boot entry.
+  - `systemd.defaultUnit = lib.mkForce "multi-user.target";` — boots to the
+    text console. `graphical.target` is what pulls in the display manager (via
+    its embedded `Wants=display-manager.service`), so defaulting to
+    `multi-user.target` leaves SDDM installed but not started at boot.
+  - `services.getty.autologinUser = "finn";` — guarantees a usable shell on
+    the console instead of a login prompt that can scroll off screen.
+  - A `desktop` command via
+    `pkgs.writeShellScriptBin "desktop" "exec sudo systemctl start display-manager.service"`
+    in `environment.systemPackages`, to start KDE on demand.
+- Add `systemd.services.NetworkManager-wait-online.enable = false;` (applies to
+  both the default and terminal boots) so boot never stalls waiting for the
+  network.
+
+### Reverted from the first attempt
+
+- `modules/environments/kde-desktop/default.nix` — remove the `startOnBoot`
+  option and its `mkMerge`/`mkIf` machinery; back to the original profile that
+  simply enables SDDM + Plasma 6.
+- `machines/mibook/environments.nix` — remove `kde-desktop.startOnBoot = false;`
+  (back to just `kde-desktop.enable = true;`).
+
+## Why a specialisation
+
+A specialisation generates a second boot-menu entry automatically from a
+modified copy of the configuration. It is the idiomatic NixOS mechanism for a
+boot-time choice and avoids fragile hand-written GRUB `extraEntries` that would
+need to track kernel/initrd paths across generations. The default entry remains
+byte-for-byte the working desktop configuration.
+
+## Testing / verification
+
+- `nix build '.#nixosConfigurations.mibook.config.system.build.toplevel'`
+  builds both `nixos-system-mibook` and `nixos-system-mibook-terminal`.
+- Verified on the built closures:
+  - Parent `default.target` → `graphical.target`; no console autologin
+    (identical to the pre-change baseline).
+  - Specialisation `default.target` → `multi-user.target`; tty1 getty wrapper
+    contains `--autologin finn`; `desktop` present in the system profile.
+  - `NetworkManager-wait-online` disabled in both.
+- Post-`switch` manual check on mibook: default GRUB entry boots to KDE; the
+  `terminal` entry boots to an autologged-in console; running `desktop` there
+  starts SDDM and a working Plasma session.
+
+## Trade-offs
+
+- Autologin on the terminal console means physical access grants a shell
+  without a password. Acceptable for a personal laptop the user controls; the
+  desktop (default) boot is unaffected.
+- `desktop` relies on `sudo`; the user has sudo access, so no extra config is
+  required.

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

@@ -20,7 +20,6 @@
     useOSProber = true;
   };
 
-
   # Configure keymap in X11
   services.xserver.xkb = {
     layout = "de";
@@ -34,7 +33,6 @@
   services.printing.enable = true;
   nixpkgs.config.allowUnfree = true;
 
-
   hardware.nvidia.prime = {
     sync.enable = false;
 
@@ -44,6 +42,37 @@
 
   services.openssh.enable = true;
 
+  # Don't let boot stall waiting for a network that may never come up
+  # (WiFi credentials live in KWallet and need a desktop session), which
+  # otherwise hangs the terminal boot before the login prompt appears.
+  systemd.services.NetworkManager-wait-online.enable = false;
+
+  # Boot-time choice: the default GRUB entry boots straight into KDE.
+  # A separate "terminal" entry (a NixOS specialisation) boots to a text
+  # console with autologin, where you can work or run `desktop` to bring
+  # KDE up. Pick the entry you want in the GRUB menu at boot.
+  #
+  # NOTE: in terminal mode WiFi will not connect on its own (the password
+  # is stored per-user in KWallet). To reach the machine over SSH from
+  # terminal mode, first save the WiFi as a system connection in KDE:
+  # network settings -> your WiFi -> "All users may connect to this network".
+  specialisation.terminal.configuration = {
+    system.nixos.tags = [ "terminal" ];
+
+    # Boot to a text console. graphical.target is what pulls in the display
+    # manager (via its embedded Wants=display-manager.service), so defaulting
+    # to multi-user.target leaves SDDM installed but not started at boot.
+    systemd.defaultUnit = lib.mkForce "multi-user.target";
+
+    # Guarantee a usable shell on the console (no login prompt to hunt for).
+    services.getty.autologinUser = "finn";
+
+    # Bring the desktop up on demand from the terminal.
+    environment.systemPackages = [
+      (pkgs.writeShellScriptBin "desktop" "exec sudo systemctl start display-manager.service")
+    ];
+  };
+
   # 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.

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

@@ -24,4 +24,4 @@ in
       numix-icon-theme
     ];
   };
-}
+}