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>

scripts/host.env.example

@@ -1,16 +1,17 @@
 # punktfunk host configuration (~/.config/punktfunk/host.env) — consumed by punktfunk-host.service.
 #
-# The compositor + input backend are AUTO-DETECTED per connect from the live session (the host
-# probes which compositor is actually running and retargets WAYLAND_DISPLAY/XDG_CURRENT_DESKTOP/
-# DBUS at it), so a box that flips between Steam Gaming Mode and a KDE/GNOME desktop is followed
-# automatically. The blocks below are OPTIONAL OVERRIDES — uncomment one only to force a backend
-# (this also skips the per-connect env retargeting). The anchors XDG_RUNTIME_DIR + DBUS stay.
-
-# Session / compositor environment (headless KWin example).
-XDG_RUNTIME_DIR=/run/user/1000
-DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
-WAYLAND_DISPLAY=wayland-kde
-XDG_CURRENT_DESKTOP=KDE
+# YOU BARELY NEED THIS FILE. The host AUTO-DETECTS the live session per connect — which compositor
+# is running (KWin / Mutter / sway / Hyprland / gamescope), its Wayland socket, session bus, and the
+# matching input backend — and FOLLOWS the box when it switches between a desktop and Steam Gaming
+# Mode, even mid-stream. Everything below except PUNKTFUNK_VIDEO_SOURCE is an optional override.
+#
+# Two rules that save debugging sessions:
+#   * Keys are CASE-SENSITIVE. `punktfunk_gamescope_attach=1` sets nothing — use the exact
+#     uppercase names.
+#   * On a desktop you actually use, do NOT set PUNKTFUNK_COMPOSITOR / WAYLAND_DISPLAY /
+#     XDG_CURRENT_DESKTOP. Pinning the compositor DISABLES session-following (a switch to Game
+#     Mode mid-stream then kills the stream instead of being followed), and stale session vars
+#     point detection at dead sockets. Those knobs are for CI and dedicated appliances (below).
 
 # Video source: `virtual` creates a per-client virtual output at the client's exact
 # resolution+refresh (the flagship mode); `portal` captures an existing monitor.
@@ -20,33 +21,41 @@ PUNKTFUNK_VIDEO_SOURCE=virtual
 # CPU automatically. No need to set it. Set to 0 only to force the CPU path.
 # PUNKTFUNK_ZEROCOPY=0
 
-# --- Bazzite / SteamOS-like host: host-managed Steam-Deck-UI session -----------------------
-# The host LAUNCHES gamescope-session-plus headless AT THE CLIENT'S mode (so games see the
-# client's exact resolution + refresh, not the box's TV), and relaunches it when the mode
-# changes. Requires the headless-appliance prereqs (linger + multi-user.target — see
-# punktfunk-steam-session.service header) and NO physical gaming session running.
-#PUNKTFUNK_COMPOSITOR=gamescope
-#PUNKTFUNK_GAMESCOPE_SESSION=steam   # host owns a gamescope-session-plus session at the client mode
-#PUNKTFUNK_INPUT_BACKEND=gamescope
-# Mutually exclusive with the above: ATTACH to a gamescope session something ELSE owns (fixed mode):
-#PUNKTFUNK_GAMESCOPE_NODE=auto       # discover + capture a running gamescope (do NOT combine with SESSION)
+# --- Session anchors (rarely needed) -------------------------------------------------------
+# As a `systemctl --user` service the host inherits the correct XDG_RUNTIME_DIR from systemd and
+# derives the bus (`unix:path=$XDG_RUNTIME_DIR/bus`) itself. Set these ONLY when running the host
+# outside a user service (ssh, cron) — and with YOUR uid (`id -u`), never a copy-pasted 1000: a
+# wrong uid points the host at another user's (nonexistent) PipeWire/D-Bus, and every session
+# fails with errors like "pw audio connect … Creation failed".
+#XDG_RUNTIME_DIR=/run/user/<uid>
+#DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/<uid>/bus
 
-# --- GNOME / Mutter host (e.g. an Ubuntu desktop) -----------------------------------------
-# Attach to a running GNOME (Wayland) session — its default socket is wayland-0, not wayland-kde.
-# Mutter creates the per-client virtual output via its `RecordVirtual` D-Bus API (a virtual
-# monitor alongside any real one), and input goes through the RemoteDesktop portal (libei). On a
-# real desktop the host runs as the logged-in user; headless GNOME also works (gnome-shell
-# --headless). Needs GNOME ≥ 48 for the zero-copy RecordVirtual path.
-#WAYLAND_DISPLAY=wayland-0
-#XDG_CURRENT_DESKTOP=GNOME
-#PUNKTFUNK_COMPOSITOR=mutter
-#PUNKTFUNK_VIDEO_SOURCE=virtual
-#PUNKTFUNK_INPUT_BACKEND=libei
+# --- Steam Gaming Mode (Linux boxes with gamescope session infra: Bazzite/SteamOS/Nobara) ---
+# Game Mode is auto-handled; two models decide WHERE it runs when a client streams:
+#   * MANAGED (the default where session infra is detected) — the host relaunches the gaming
+#     session HEADLESS at the CLIENT's exact mode ("game mode on the virtual screen"); physical
+#     displays drop out of it, and the box is restored on a debounced idle after disconnect.
+#   * ATTACH — the BOX owns its session: Game Mode stays on the physical screen and the host
+#     captures/follows it, never tearing it down. Reconnects land wherever the box is.
+#PUNKTFUNK_GAMESCOPE_ATTACH=1        # pick the ATTACH model
+#PUNKTFUNK_GAMESCOPE_MANAGED=1      # force MANAGED even where infra detection wouldn't pick it
+#PUNKTFUNK_GAMESCOPE_SESSION=steam  # host owns a gamescope-session-plus session at the client mode
+#PUNKTFUNK_GAMESCOPE_NODE=auto      # raw attach: discover + capture a running gamescope's node
+#                                   # (do NOT combine with SESSION)
+#PUNKTFUNK_GAMESCOPE_APP=vkcube     # nested command for ad-hoc bare-gamescope sessions
+#PUNKTFUNK_SESSION_WATCH=0          # disable mid-stream Desktop<->Game following (on by default
+#                                   # on gamescope-infra boxes)
+
+# --- Force a backend (CI / tests / dedicated single-session appliances ONLY) ---------------
+# PINS the backend: the host stops following the live session entirely — per connect AND
+# mid-stream. Fine for a dedicated headless appliance (punktfunk-kde-session.service, a pure
+# gamescope box) or a CI run; wrong for any box that switches sessions.
+#PUNKTFUNK_COMPOSITOR=kwin          # kwin | mutter | gamescope | wlroots | hyprland
+#PUNKTFUNK_INPUT_BACKEND=libei      # wlr | libei | gamescope | uinput (auto-routed per connect)
+#WAYLAND_DISPLAY=wayland-kde        # headless-KDE appliance socket; retargeted per connect otherwise
+#XDG_CURRENT_DESKTOP=KDE
 
 # Optional overrides (apps.json is the primary mechanism for per-app settings):
-#PUNKTFUNK_COMPOSITOR=kwin          # kwin | mutter | gamescope | wlroots
-#PUNKTFUNK_GAMESCOPE_APP=vkcube     # nested command for ad-hoc bare-gamescope sessions
-#PUNKTFUNK_INPUT_BACKEND=libei      # wlr | libei | gamescope | uinput
 #PUNKTFUNK_FEC_PCT=20               # video FEC overhead percent
 #PUNKTFUNK_PERF=1                   # per-stage timing logs
 #PUNKTFUNK_MDNS=0                   # disable the mDNS adverts (native + GameStream) — for multicast-

scripts/punktfunk-host.service

@@ -2,15 +2,18 @@
 # GameStream/Moonlight-compat planes). For a SECURE native-only host (no plain-HTTP pairing / legacy
 # GCM nonce reuse — security-review #5/#9; native clients only), drop `--gamestream` from ExecStart.
 #
-# Install (against an already-running compositor session):
+# Install (against an already-running compositor session — the host auto-detects and follows it,
+# so host.env needs no backend config):
 #   mkdir -p ~/.config/systemd/user && cp scripts/punktfunk-host.service ~/.config/systemd/user/
-#   cp scripts/host.env.example ~/.config/punktfunk/host.env   # then edit for your backend
+#   cp scripts/host.env.example ~/.config/punktfunk/host.env   # defaults are right for a desktop
 #   systemctl --user daemon-reload && systemctl --user enable --now punktfunk-host
 #
-# Self-contained boot appliance (no login, no manual steps after boot):
+# Self-contained boot appliance (no login, no manual steps after boot). These routes PIN the
+# backend via PUNKTFUNK_COMPOSITOR — correct for a dedicated single-session box, but it turns off
+# live-session auto-detection, so never do it on a desktop that switches sessions (Game Mode etc.):
 #   - kwin backend (stream the Plasma desktop): also install + enable
-#     punktfunk-kde-session.service (it brings up the headless KWin session this After=s), and set
-#     PUNKTFUNK_COMPOSITOR=kwin + WAYLAND_DISPLAY=wayland-kde in host.env.
+#     punktfunk-kde-session.service (it brings up the headless KWin session this After=s), and use
+#     the shipped packaging/kde/host.env (pins kwin + WAYLAND_DISPLAY=wayland-kde on purpose).
 #   - gamescope backend (stream a nested app, no desktop): set PUNKTFUNK_COMPOSITOR=gamescope in
 #     host.env — the host spawns gamescope per session, so no kde-session unit is needed.
 #   Then `sudo loginctl enable-linger "$USER"` so user units start at boot, and reboot.