docs(env): stop teaching the compositor pin + uid-1000 anchors in starters

Field triage (Nobara, Discord): the kde.md starter host.env told desktop
users to set PUNKTFUNK_COMPOSITOR=kwin, which PINS the backend — detect()
short-circuits and the capture-loss rebuild never re-detects — so a
mid-stream switch to Game Mode killed the stream instead of following it.
A follow-up hardcoded XDG_RUNTIME_DIR=/run/user/1000 anchor broke PipeWire
for any non-1000 uid (pw audio connect: Creation failed).

Revamp across every starter/example/reference:
- Desktop starters (kde/gnome/hyprland/sway) shrink to
  PUNKTFUNK_VIDEO_SOURCE=virtual + an explicit warning that pinning
  disables session-following; forcing a backend is CI/appliance-only.
- host.env.example: rewritten around auto-detection; anchors demoted to a
  commented ssh/cron-only block with the uid trap spelled out; the
  gamescope ATTACH/MANAGED knobs documented (previously missing);
  case-sensitivity called out.
- packaging/bazzite/host.env + README: drop the uid-1000 anchors (a
  systemctl --user service inherits/derives them); README's stale
  PUNKTFUNK_COMPOSITOR=gamescope-era template synced to the real one.
- packaging/kde/host.env: loud APPLIANCE-ONLY header (it pins on purpose).
- configuration.md: session-anchors section inverted to "leave unset",
  compositor row states the pin consequence, case-sensitivity note.
- troubleshooting.md: new "session fails right after editing host.env"
  section (case, wrong-uid anchors, stale pin, restart-to-apply).
- gamescope.md/bazzite.md: attach/managed descriptions match current
  behavior (managed is the infra-detected default; attach re-modes a
  box-owned session to the client's resolution).

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

docs-site/content/docs/bazzite.md

@@ -85,11 +85,10 @@ cp /usr/share/punktfunk/host.env.bazzite ~/.config/punktfunk/host.env
 
 The template is deliberately minimal — it does **not** force a compositor, because the host
 auto-detects Gaming Mode (gamescope) vs Desktop (KWin) on every connect and follows the switch
-mid-stream. The only settings that matter are the session anchors (GPU zero-copy is on by default):
+mid-stream. No session anchors are needed either (a user service inherits the right runtime dir).
+The only settings that matter (GPU zero-copy is on by default):
 
 ```sh
-XDG_RUNTIME_DIR=/run/user/1000
-DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
 PUNKTFUNK_VIDEO_SOURCE=virtual
 # GPU zero-copy (dmabuf → CUDA → NVENC) is ON by default; auto-falls back to CPU. Set =0 to force CPU.
 PUNKTFUNK_GAMESCOPE_ATTACH=1    # Gaming Mode = attach to the box's own session (see below)
@@ -99,12 +98,13 @@ PUNKTFUNK_GAMESCOPE_ATTACH=1    # Gaming Mode = attach to the box's own session
 
 For Gaming Mode there are two models (pick one; the shipped default is **attach**):
 
-- **Attach** (`PUNKTFUNK_GAMESCOPE_ATTACH=1`, the default) — the **box** owns its gamescope session,
-  the host attaches to whatever's live and never tears it down, and the streamed game-mode resolution
-  is the box's own gamescope mode. Switching Desktop ↔ Game is rock-solid.
-- **Managed** (`PUNKTFUNK_GAMESCOPE_MANAGED=1`, and remove the attach line) — the host launches its
-  **own** gamescope at the *client's* exact resolution and refresh. Client-mode-following, but there
-  must be no physical gaming session already running.
+- **Attach** (`PUNKTFUNK_GAMESCOPE_ATTACH=1`, the template's default) — the **box** owns its
+  gamescope session on its own display, and the host attaches to whatever's live without ever
+  tearing it down (a box-owned autologin session is restarted at the client's resolution on a
+  mismatch). Switching Desktop ↔ Game is rock-solid.
+- **Managed** (`PUNKTFUNK_GAMESCOPE_MANAGED=1`, and remove the attach line) — the host takes the
+  box's gamescope over and relaunches it **headless** at the *client's* exact resolution and
+  refresh — Game Mode on the virtual screen — restoring the box on idle.
 
 Full treatment: [Steam / gamescope → Attach vs managed](/docs/gamescope#attach-vs-managed).
 

docs-site/content/docs/configuration.md

@@ -4,7 +4,8 @@ description: Every host.env setting and PUNKTFUNK_* environment variable — com
 ---
 
 The host reads its settings from **`~/.config/punktfunk/host.env`** (a simple `KEY=value` file, `#`
-starts a comment). On Windows the service reads **`%ProgramData%\punktfunk\host.env`** instead. Your
+starts a comment; keys are **case-sensitive** — `punktfunk_compositor` sets nothing, use the exact
+uppercase names). On Windows the service reads **`%ProgramData%\punktfunk\host.env`** instead. Your
 [setup guide](/docs/requirements) gives you a starting `host.env` for your desktop; this page is the
 full reference for every setting.
 
@@ -16,25 +17,24 @@ full reference for every setting.
 
 ## Session anchors
 
-These tell the host which desktop session to attach to. Your setup guide sets them for you; they're
-required when the host runs outside your interactive session (e.g. as a service).
+**Leave these unset on a normal setup.** Running as a `systemctl --user` service the host inherits
+the correct `XDG_RUNTIME_DIR` from systemd, derives the session bus from it, and **rewrites
+`WAYLAND_DISPLAY` / `XDG_CURRENT_DESKTOP` / `XDG_RUNTIME_DIR` / `DBUS_SESSION_BUS_ADDRESS` on every
+connect** to follow the active session (Gaming ↔ Desktop) — a value written here can only be
+redundant or stale.
 
-| Setting | What it does |
+| Setting | When to set it |
 |---|---|
-| `XDG_RUNTIME_DIR` | Your session's runtime dir (e.g. `/run/user/1000`). Always needed for a service. |
-| `DBUS_SESSION_BUS_ADDRESS` | Your session bus (e.g. `unix:path=/run/user/1000/bus`). Always needed for a service. |
-| `WAYLAND_DISPLAY` | The Wayland socket of your session (`wayland-0` for a normal desktop, `wayland-kde` for the headless-KDE unit). |
-| `XDG_CURRENT_DESKTOP` | Your desktop (`GNOME`, `KDE`). |
-
-On Linux the host **rewrites `WAYLAND_DISPLAY` / `XDG_CURRENT_DESKTOP` / `XDG_RUNTIME_DIR` /
-`DBUS_SESSION_BUS_ADDRESS` on every connect** to follow the active session (Gaming ↔ Desktop). Only
-`XDG_RUNTIME_DIR` and `DBUS_SESSION_BUS_ADDRESS` need to be pinned as trustworthy anchors.
+| `XDG_RUNTIME_DIR` | Only when the host runs **outside** a user service (ssh, cron): `/run/user/<your uid>` — check `id -u`. A copy-pasted `1000` on a box where that isn't your uid points the host at another user's (nonexistent) PipeWire/D-Bus, and **everything** fails (audio `Creation failed`, no capture, clients report the host unreachable). |
+| `DBUS_SESSION_BUS_ADDRESS` | Same cases only: `unix:path=/run/user/<your uid>/bus`. Otherwise derived automatically. |
+| `WAYLAND_DISPLAY` | Only the dedicated [headless-KDE appliance](/docs/kde#headless-session) (`wayland-kde`, set by its shipped `host.env.kde`). |
+| `XDG_CURRENT_DESKTOP` | Same — appliance-only. |
 
 ## Core
 
 | Setting | Values | Meaning |
 |---|---|---|
-| `PUNKTFUNK_COMPOSITOR` | `kwin` · `mutter` · `gamescope` · `wlroots` · `hyprland` (aliases: `kde`/`plasma`, `gnome`, `sway`/`wlr`) | Which backend creates the virtual display. `wlroots` is sway/River; `hyprland` is its own backend. **Leave unset to auto-detect;** set only to force one. |
+| `PUNKTFUNK_COMPOSITOR` | `kwin` · `mutter` · `gamescope` · `wlroots` · `hyprland` (aliases: `kde`/`plasma`, `gnome`, `sway`/`wlr`) | Which backend creates the virtual display. `wlroots` is sway/River; `hyprland` is its own backend. **Leave unset.** Setting it **pins** the backend and turns session-following **off** — per connect *and* mid-stream, so a Desktop ↔ Gaming switch kills the stream instead of being followed. For CI/tests and dedicated single-session appliances only. |
 | `PUNKTFUNK_VIDEO_SOURCE` | `virtual` · `portal` | `virtual` creates a per-client display at the client's exact mode (the normal choice). `portal` captures an existing monitor instead. |
 | `PUNKTFUNK_ZEROCOPY` | `1` · `0` *(default on)* | GPU zero-copy capture→encode (dmabuf → CUDA → NVENC, or D3D11 on Windows). **On by default** — no need to set it; it falls back to a CPU path automatically. Set `0` to force the CPU path. One exception: Windows **Intel/QSV** keeps the CPU path by default until zero-copy is validated on Intel hardware — set `1` to try it there. |
 | `PUNKTFUNK_INPUT_BACKEND` | `libei` · `gamescope` · `wlr` · `uinput` | How input is injected. `libei` for GNOME/KDE, `gamescope` for Bazzite/gamescope, `wlr` for Sway/wlroots **and Hyprland**. Auto-detected with the compositor. |
@@ -53,8 +53,8 @@ the full picture (and [Bazzite](/docs/bazzite) for that distro's specifics).
 
 | Setting | Values | Meaning |
 |---|---|---|
-| `PUNKTFUNK_GAMESCOPE_ATTACH` | `1` | **Attach** model: the box owns its gamescope session (you switch Gaming ↔ Desktop with the Steam UI); the host just captures whatever's live and never tears it down. Rock-solid; streamed resolution is the box's gamescope mode. |
-| `PUNKTFUNK_GAMESCOPE_MANAGED` | `1` | **Managed** model: the host tears the box's gamescope down on connect and launches its **own** at the *client's* exact resolution, restoring on idle. Client-mode-following, but doesn't coexist with a box-owned game-mode session. |
+| `PUNKTFUNK_GAMESCOPE_ATTACH` | `1` | **Attach** model: the box owns its gamescope session on its own display (you switch Gaming ↔ Desktop with the Steam UI); the host just captures whatever's live and never tears it down. A box-owned autologin session is restarted at the client's resolution on a mismatch; a foreign/bare gamescope streams at its own mode. |
+| `PUNKTFUNK_GAMESCOPE_MANAGED` | `1` | **Managed** model (the default where session infra is detected): the host takes the box's gamescope over and relaunches it **headless** at the *client's* exact resolution — Game Mode on the virtual screen — restoring the box on idle. |
 | `PUNKTFUNK_GAMESCOPE_SESSION` | `steam` | The host owns a `gamescope-session-plus` (Steam) session at the client's mode (headless appliance; no physical session running). |
 | `PUNKTFUNK_GAMESCOPE_NODE` | `auto` · node id | Discover + capture a **running** gamescope's PipeWire node at a fixed mode. Do **not** combine with `SESSION`. |
 | `PUNKTFUNK_GAMESCOPE_APP` | command | For an ad-hoc bare-gamescope session, the nested command to run (e.g. `vkcube`). |

docs-site/content/docs/gamescope.md

@@ -17,18 +17,20 @@ from the install guide for your OS: [Bazzite](/docs/bazzite) or [SteamOS (Host)]
 
 ## Attach vs managed
 
-There are two mutually-exclusive models for a gamescope box; pick one. The shipped default is
-**attach**.
+There are two mutually-exclusive models for a gamescope box; pick one. With **nothing set**, a box
+that has gamescope session infrastructure (Bazzite, SteamOS, Nobara) gets **managed**; the
+[Bazzite template](/docs/bazzite) ships with **attach** chosen instead.
 
-- **Attach** (`PUNKTFUNK_GAMESCOPE_ATTACH=1`, the default) — the **box** owns its gamescope session
-  and decides Gaming vs Desktop via the normal Steam UI. The host just attaches to whatever's live
-  and never tears it down, so switching Desktop ↔ Game is rock-solid and disconnecting leaves the box
-  where it was. The streamed game-mode resolution is the box's gamescope mode
-  (`SCREEN_WIDTH/HEIGHT` in `/etc/gamescope-session-plus/sessions.d/steam`), not the client's.
-- **Managed** (`PUNKTFUNK_GAMESCOPE_MANAGED=1`, and remove the attach line) — the host tears the
-  box's gamescope down on connect and launches its **own** at the *client's* exact resolution and
-  refresh, restoring on idle. Client-mode-following, but it can't coexist with a box-owned game-mode
-  session, and there must be **no physical gaming session already running**.
+- **Attach** (`PUNKTFUNK_GAMESCOPE_ATTACH=1`) — the **box** owns its gamescope session and decides
+  Gaming vs Desktop via the normal Steam UI. Game Mode stays on the box's own (physical) display;
+  the host attaches to whatever's live and never tears it down, so switching Desktop ↔ Game is
+  rock-solid and disconnecting leaves the box where it was. When the session is the box's own
+  autologin unit, the host restarts it at the **client's** resolution on a mismatch; a foreign or
+  bare gamescope is streamed at its own mode.
+- **Managed** (the infra-detected default; force with `PUNKTFUNK_GAMESCOPE_MANAGED=1`) — the host
+  takes the box's gamescope session over and relaunches it **headless** at the *client's* exact
+  resolution and refresh — Game Mode runs on the virtual screen, physical displays drop out of it —
+  restoring the box on idle after disconnect.
 
 ## Session following
 
@@ -40,8 +42,8 @@ over its own compositor, and re-targets whichever is live on each switch.
 ## Start the host
 
 On an appliance box (Bazzite, SteamOS) the install guide already enables the host service for you. On
-any other distro running a gamescope session, start it from your session — the default attach model
-just latches onto whatever gamescope session is live:
+any other distro running a gamescope session, just start it — the host auto-detects the live
+gamescope session and picks the model for it:
 
 ```sh
 systemctl --user enable --now punktfunk-host
@@ -56,8 +58,8 @@ a model. See the full [Configuration reference](/docs/configuration) for every o
 
 | Setting | Values | Meaning |
 |---|---|---|
-| `PUNKTFUNK_GAMESCOPE_ATTACH` | `1` | **Attach** model: the box owns its gamescope session; the host captures whatever's live and never tears it down. Streamed resolution is the box's gamescope mode. The default. |
-| `PUNKTFUNK_GAMESCOPE_MANAGED` | `1` | **Managed** model: the host tears the box's gamescope down on connect and launches its own at the client's exact mode, restoring on idle. Doesn't coexist with a box-owned game-mode session. |
+| `PUNKTFUNK_GAMESCOPE_ATTACH` | `1` | **Attach** model: the box owns its gamescope session (on its own display); the host captures whatever's live and never tears it down. A box-owned autologin session is restarted at the client's resolution on a mismatch; a foreign/bare gamescope streams at its own mode. |
+| `PUNKTFUNK_GAMESCOPE_MANAGED` | `1` | **Managed** model (the default where session infra is detected): the host takes the box's gamescope over and relaunches it headless at the client's exact mode, restoring on idle. |
 | `PUNKTFUNK_GAMESCOPE_SESSION` | `steam` | The host owns a `gamescope-session-plus` (Steam) session at the client's mode — a headless appliance with no physical session running. |
 | `PUNKTFUNK_GAMESCOPE_NODE` | `auto` · node id | Discover and capture a **running** gamescope's PipeWire node at a fixed mode. Do **not** combine with `SESSION`. |
 | `PUNKTFUNK_GAMESCOPE_APP` | command | For an ad-hoc bare-gamescope session, the nested command to run (e.g. `vkcube`). |

docs-site/content/docs/gnome.md

@@ -12,19 +12,20 @@ installed — see [Ubuntu](/docs/ubuntu), [Fedora](/docs/fedora), or [Arch](/doc
 
 ## host.env
 
-Write `~/.config/punktfunk/host.env` with the GNOME settings. The host auto-detects the compositor
-from your session, so the explicit `PUNKTFUNK_COMPOSITOR` is belt-and-braces:
+The host auto-detects the compositor from your live session on every connect, so the starter
+`~/.config/punktfunk/host.env` is one line:
 
 ```ini
-# ~/.config/punktfunk/host.env
-WAYLAND_DISPLAY=wayland-0
-XDG_CURRENT_DESKTOP=GNOME
-PUNKTFUNK_COMPOSITOR=mutter
+# ~/.config/punktfunk/host.env  (keys are case-sensitive)
 PUNKTFUNK_VIDEO_SOURCE=virtual
 # GPU zero-copy (dmabuf → CUDA → NVENC) is ON by default; auto-falls back to CPU. Set =0 to force CPU.
-PUNKTFUNK_INPUT_BACKEND=libei
 ```
 
+> **Don't set `PUNKTFUNK_COMPOSITOR`, `WAYLAND_DISPLAY`, or `XDG_CURRENT_DESKTOP` here.** Pinning
+> the compositor turns auto-detection **off** — per connect *and* mid-stream — so the host stops
+> following session switches, and stale session values point it at dead sockets. Forcing a backend
+> is a CI / dedicated-appliance posture, not desktop configuration.
+
 You must be on a **Wayland** session (not X11), and Mutter must be **≥ 48**. See the
 [Configuration reference](/docs/configuration) for every option.
 

docs-site/content/docs/hyprland.md

@@ -19,14 +19,19 @@ or [Fedora](/docs/fedora).
 
 ## host.env
 
-The host auto-detects a Hyprland session, so you usually need nothing here. To force the backend, set
-these in `~/.config/punktfunk/host.env`:
+The host auto-detects a Hyprland session, so the starter `~/.config/punktfunk/host.env` is one line:
+
+```ini
+PUNKTFUNK_VIDEO_SOURCE=virtual
+# GPU zero-copy capture→encode is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.
+```
+
+To force the backend (CI/testing — note that pinning turns live-session auto-detection **off**, so
+the host stops following session switches):
 
 ```ini
 PUNKTFUNK_COMPOSITOR=hyprland
 PUNKTFUNK_INPUT_BACKEND=wlr
-PUNKTFUNK_VIDEO_SOURCE=virtual
-# GPU zero-copy capture→encode is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.
 ```
 
 See [Configuration](/docs/configuration) for the full reference.

docs-site/content/docs/kde.md

@@ -13,20 +13,30 @@ installed — see [Ubuntu](/docs/ubuntu), [Fedora](/docs/fedora), [Arch](/docs/a
 
 ## host.env
 
-A KDE starter `~/.config/punktfunk/host.env`:
+The host auto-detects your KWin session on every connect — including a box that switches between
+the Plasma desktop and Steam Game Mode — so the starter `~/.config/punktfunk/host.env` is one line:
 
 ```ini
-WAYLAND_DISPLAY=wayland-0
-XDG_CURRENT_DESKTOP=KDE
-PUNKTFUNK_COMPOSITOR=kwin
+# ~/.config/punktfunk/host.env  (keys are case-sensitive)
 PUNKTFUNK_VIDEO_SOURCE=virtual
 # GPU zero-copy (dmabuf → CUDA → NVENC) is ON by default; auto-falls back to CPU. Set =0 to force CPU.
-PUNKTFUNK_INPUT_BACKEND=libei
 ```
 
-The host auto-detects the running compositor on every connect, so most of this is optional — the
-values above are just what it resolves to on a KWin session. See the
-[Configuration reference](/docs/configuration) for every option.
+> **Don't set `PUNKTFUNK_COMPOSITOR`, `WAYLAND_DISPLAY`, or `XDG_CURRENT_DESKTOP` here.** Pinning
+> the compositor turns auto-detection **off** — per connect *and* mid-stream — so a switch to Game
+> Mode then kills the stream instead of being followed, and stale session values point the host at
+> dead sockets. Forcing a backend is for CI and dedicated appliances (the
+> [headless session](#headless-session) below ships a `host.env.kde` that pins on purpose).
+
+If the box switches between the desktop and Game Mode, also enable lingering — the host is a user
+service, and without linger the logout moment of a session switch tears it (and PipeWire) down
+mid-stream:
+
+```sh
+sudo loginctl enable-linger "$USER"
+```
+
+See the [Configuration reference](/docs/configuration) for every option.
 
 ## Use a Wayland session
 

docs-site/content/docs/sway.md

@@ -23,16 +23,21 @@ or [Fedora](/docs/fedora).
 
 ## host.env
 
-The host auto-detects a wlroots session, so you usually need nothing here. To force the backend, set
-these in `~/.config/punktfunk/host.env`:
+The host auto-detects a wlroots session, so the starter `~/.config/punktfunk/host.env` is one line:
 
 ```ini
-PUNKTFUNK_COMPOSITOR=wlroots      # aliases: sway, wlr, hyprland (all the wlroots family; the exact backend is auto-detected)
-PUNKTFUNK_INPUT_BACKEND=wlr
 PUNKTFUNK_VIDEO_SOURCE=virtual
 # GPU zero-copy capture→encode is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.
 ```
 
+To force the backend (CI/testing — note that pinning turns live-session auto-detection **off**, so
+the host stops following session switches):
+
+```ini
+PUNKTFUNK_COMPOSITOR=wlroots      # aliases: sway, wlr (the wlroots-proper family)
+PUNKTFUNK_INPUT_BACKEND=wlr
+```
+
 See [Configuration](/docs/configuration) for the full reference.
 
 ## How it works

docs-site/content/docs/troubleshooting.md

@@ -103,7 +103,22 @@ See [GNOME](/docs/gnome) for the GL/EGL userspace details.
 - KWin must be **≥ 6.5.6** (`kwin_wayland --version`); GNOME **≥ 48**; gamescope **≥ 3.16.22**. See
   [KDE](/docs/kde) for the KWin/Wayland requirement and [gamescope](/docs/gamescope) for the
   gamescope one.
-- Confirm `PUNKTFUNK_COMPOSITOR` in [`host.env`](/docs/configuration) matches your desktop.
+- If [`host.env`](/docs/configuration) sets `PUNKTFUNK_COMPOSITOR`, **remove it** — the host
+  auto-detects the live compositor, and the pin points it at one backend even when a different
+  session is live (it also disables Gaming ↔ Desktop following).
+
+## Session fails right after editing host.env
+
+- Keys are **case-sensitive**: `punktfunk_gamescope_attach=1` sets nothing — use the exact
+  uppercase names.
+- Hardcoded session anchors with the wrong uid (`XDG_RUNTIME_DIR=/run/user/1000` when `id -u`
+  isn't 1000) point the host at another user's PipeWire/D-Bus: audio errors like
+  `pw audio connect … Creation failed`, no capture, and clients reporting the host as
+  unreachable or asleep. **Delete both anchor lines** — a `systemctl --user` service doesn't need
+  them — or fix the uid.
+- `PUNKTFUNK_COMPOSITOR` pins the backend and disables Gaming ↔ Desktop following — remove it on
+  any box that switches sessions.
+- The env file is read at service start: `systemctl --user restart punktfunk-host` after edits.
 
 ## Capture fails: "Session creation inhibited" (GNOME)