docs: repo-wide housekeeping — sync README & docs with the code as shipped

Six parallel audits swept the root docs, docs-site, every per-directory
README, and the packaging docs; every claim below was verified against
the source before editing.

- README: Layout gains the six missing crates (pf-client-core,
  pf-presenter, pf-console-ui, pf-ffvk, pf-driver-proto, punktfunk-tray),
  clients/session, api/ and ci/; Linux/Windows client rows reflect the
  shell + Vulkan-session split and the Vulkan Video -> VAAPI/D3D11VA ->
  software decode chains; the "every client over a C ABI" claim is
  corrected (Rust clients link the core directly); tiered stats overlay
  + console shell noted; Apple row mentions AV1.
- CONTRIBUTING: drop the dead CLAUDE.md link (deliberately untracked);
  point at the README's build/invariants sections. SECURITY: 0.9.0.
- host-cli/pairing: --allow-pairing/--require-pairing are no-op legacy
  names — pairing is required by default, --allow-tofu is the real flag;
  document --data-port and --idle-timeout-ms.
- configuration: document PUNKTFUNK_RECOVER_SESSION_CMD (session-crash
  recovery hook), PUNKTFUNK_MDNS, PUNKTFUNK_DATA_PORT.
- virtual-displays/gnome: GNOME per-client scaling shipped (host-
  persisted) — flip the ❌ to ✅ and describe how it works.
- stats: new "Detail levels" section (Off/Compact/Normal/Detailed +
  per-platform cycle gestures); retire the GTK hand-off note.
- clients/install-client/status/roadmap: decode chains, Windows client
  validation narrowed to HDR-only pending, adaptive bitrate, console
  shell, Apple AV1, Windows host vendor list.
- Sub-READMEs: clients/linux rewritten for the re-architecture; session
  Windows decode rung + d3d11va knob; Windows tiered overlay; Android
  minSdk 28; decky file table; host zerocopy/ path; scripts port
  47992 and steamos-host.md; pf-dualsense source path.
- packaging: canary version bases are tag-derived (<next-minor> via
  pf-version.sh/.ps1), codecs-extra not ffmpeg-full, document the
  pinned offline-Skia tarball + SKIA_BINARIES_URL and vulkan-headers.
- Convert 15 dangling design/*.md links to the punktfunk-planning
  prose convention (those docs live in the private planning repo).

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

clients/android/README.md

@@ -58,7 +58,7 @@ kit/              :kit — NativeBridge · native mDNS discovery · Gamepad · K
 `build-tools;37.0.0`, **`cmake;3.22.1`** (builds libopus); **JDK 21** (AGP 9.2 runs on JDK 17–21, not
 a newer default); Rust with `rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android` and
 `cargo install cargo-ndk`. Toolchain is pinned (AGP 9.2 · Gradle 9.4.1 · Kotlin 2.3.21 · Compose BOM
-2026.05.01 · compileSdk 37 · minSdk 31).
+2026.05.01 · compileSdk 37 · minSdk 28).
 
 **Android Studio:** open `clients/android` — it uses its bundled JBR 21, and the `cargoNdk*` task
 builds the `.so` as part of the normal build.

clients/android/native/vendor/ndk/README.punktfunk.md

@@ -7,7 +7,7 @@ in the workspace root.
 **The only change** is in `src/media/media_codec.rs`: `MediaCodec::as_ptr` is made
 `pub` (upstream keeps it private) so the Android client can register
 `AMediaCodec_setOnFrameRenderedCallback` through `ndk-sys` — the render-timestamp
-callback behind the HUD's `display` stage (`design/stats-unification.md`), which the
+callback behind the HUD's `display` stage (punktfunk-planning: `stats-unification.md`), which the
 wrapper doesn't expose. Grep for `punktfunk vendored patch` to find it.
 
 Drop this vendor copy when upstream exposes the raw pointer or a frame-rendered

clients/apple/README.md

@@ -122,7 +122,8 @@ PUNKTFUNK_AUTOCONNECT=<box-ip> PUNKTFUNK_MODE=1280x720x60 swift run PunktfunkCli
 - **App Store screenshots** are automated — `tools/screenshots.sh all` renders the real UI at the
   required pixel sizes via a DEBUG-only shot mode; the `apple` CI workflow captures the iOS sizes on
   every main push. See the script header for details.
-- Deeper design notes live in [`design/apple-stage2-presenter.md`](../../design/apple-stage2-presenter.md).
+- Deeper design notes live in the internal planning repo (punktfunk-planning:
+  `apple-stage2-presenter.md`).
 
 ## Related
 

clients/decky/README.md

@@ -76,6 +76,8 @@ restart is required for an out-of-band install to appear.
 | `src/page.tsx` | The `/punktfunk` fullscreen page — Hosts (with per-host details) / Settings / About tabs. |
 | `src/settings.tsx` · `src/pair.tsx` | Stream-settings section; the gamepad-navigable PIN-pairing modal. |
 | `src/library.tsx` | The per-host game picker (pin/unpin, "Open library on screen") + the pinned-game launch helper. |
+| `src/hostmgmt.tsx` | Add / edit host dialogs — mutate the shared known-hosts store (`client-known-hosts.json`) via the flatpak client's headless modes, so a host saved here shows up in the desktop client too. |
+| `src/ui.tsx` | Shared UI primitives for the fullscreen page + modals (right-aligned row actions, consistent Field layout). |
 | `src/hooks.ts` · `src/boundary.tsx` | Shared discovery/update/pins hooks + actions; the render error boundary. |
 | `src/steam.ts` | Steam-shortcut launch (`AddShortcut` / `SetAppLaunchOptions` / `RunGame`) — the focus-correct stream start. The shortcut's exe is `/bin/sh` with the wrapper passed as an argument, so the script never needs an exec bit (Decky's zip extraction drops it and the root-owned plugins dir can't be chmodded by the unprivileged backend). Launch extras ride env-prefix tokens: `PF_LAUNCH=<id>` (pinned game) / `PF_BROWSE=1` + `PF_MGMT=<port>` (on-screen library); ids are validated space/quote-free at pin AND launch time. |
 | `src/backend.ts` | Typed `callable` bridges to `main.py`. |

clients/linux/README.md

@@ -1,17 +1,20 @@
 # punktfunk — Linux client
 
 The native **Linux** app for streaming a punktfunk host to your desktop, laptop, or Steam Deck.
-It's a clean GTK4/libadwaita app that finds hosts on your network, pairs with a PIN, and puts a
-low-latency stream on glass at your display's own resolution and refresh rate.
+It's a clean relm4/GTK4/libadwaita **shell** that finds hosts on your network, pairs with a PIN,
+and manages your settings and library — the stream itself runs in the sibling
+**`punktfunk-session`** Vulkan binary ([`clients/session`](../session/README.md)), which the shell
+spawns, putting the picture on glass at your display's own resolution and refresh rate.
 
-Built in Rust, it links the shared **`punktfunk-core`** directly (no C ABI) and speaks the fast
+Built in Rust end to end (no C ABI): the shell shares its plumbing with the session binary through
+**`crates/pf-client-core`**, which links the **`punktfunk-core`** protocol crate and speaks the fast
 **`punktfunk/1`** protocol — QUIC control plane, GF(2¹⁶) FEC + AES-GCM data plane.
 
 ## Features
 
-- **Zero-copy hardware decode** — FFmpeg VAAPI decode → DRM-PRIME dmabuf → `GdkDmabufTexture`
-  (Tier-1 zero-copy on Intel and AMD), with an automatic software-HEVC fallback on NVIDIA or when
-  VAAPI is unavailable.
+- **Zero-copy hardware decode** — the session presenter decodes via **Vulkan Video** on every GPU
+  vendor (including NVIDIA), falling back to FFmpeg VAAPI → DRM-PRIME dmabuf and then software when
+  Vulkan Video is unavailable.
 - **Your display's native mode** — the host builds a virtual output at exactly your WxH@Hz; no
   scaling, no letterboxing. Steady 60 fps at 1080p60, ~6 ms capture→decoded on the LAN.
 - **Audio both ways** — PipeWire playback with a jitter ring, plus mic uplink to the host.
@@ -26,10 +29,10 @@ Built in Rust, it links the shared **`punktfunk-core`** directly (no C ABI) and
   shows its games (Steam + custom) as a poster grid; click one to launch it in the session.
   Fetched from the host's management API over mTLS — paired devices are authorized by their
   certificate, no extra host setup.
-- **Gamepad library launcher** (`--browse host`) — a console-style, controller-driven coverflow of
-  a paired host's library (drifting aurora backdrop, center-focus posters, button hints): A plays
-  the focused title, B quits, L1/R1 jump. Built for the Steam Deck plugin's "Open library" launch;
-  session end returns to the launcher. Arrow keys/Enter/Esc drive it too (no pad needed).
+- **Gamepad library launcher** (`--browse host`) — a console-style, controller-driven library view
+  of a paired host's games, rendered by the session binary's Skia console UI: A plays the focused
+  title, B quits, L1/R1 jump. Built for the Steam Deck plugin's "Open library" launch; session end
+  returns to the launcher. Arrow keys/Enter/Esc drive it too (no pad needed).
 
 ## Get it
 

clients/session/README.md

@@ -38,17 +38,18 @@ path + per-stage latency equation); any tier but Off also emits the stdout mirro
 `--no-default-features` is the ~5 MB power-user build — same streaming, stats on stdout
 only, no Skia anywhere in the dependency tree.
 
-Decode follows the Settings preference (auto: Vulkan Video → VAAPI → software):
-FFmpeg's Vulkan Video decoder runs on the presenter's own device where the stack
-supports it (every vendor, zero copy); VAAPI dmabufs import per-plane elsewhere;
-software is the universal fallback. 10-bit Main10 and HDR10 are advertised
+Decode follows the Settings preference (auto: Vulkan Video → VAAPI → software on Linux,
+Vulkan Video → D3D11VA → software on Windows): FFmpeg's Vulkan Video decoder runs on the
+presenter's own device where the stack supports it (every vendor, zero copy); VAAPI
+dmabufs import per-plane elsewhere (D3D11VA textures on Windows); software is the
+universal fallback. 10-bit Main10 and HDR10 are advertised
 (`VIDEO_CAP_10BIT|HDR`): P010 decodes through all three paths, and PQ streams present
 on an HDR10/ST.2084 swapchain when the desktop offers one (KDE HDR, gamescope) or
 tone-map in-shader to SDR when it doesn't (`PUNKTFUNK_TONEMAP_PEAK` tunes the rolloff,
 default ≈1000 nits). The host still gates the upgrade behind its `PUNKTFUNK_10BIT`
 policy.
 
-Debug/bisect knobs: `PUNKTFUNK_DECODER=vulkan|vaapi|software`, `PUNKTFUNK_PRESENT_MODE=
+Debug/bisect knobs: `PUNKTFUNK_DECODER=vulkan|vaapi|d3d11va|software`, `PUNKTFUNK_PRESENT_MODE=
 mailbox|immediate` (default FIFO), `PUNKTFUNK_VK_DEVICE=<index>` (multi-GPU), and
 `PUNKTFUNK_HW_FAULT=import` (fault every VAAPI dmabuf import — proves the three-strike
 demotion to software on healthy hardware).

clients/windows/README.md

@@ -26,7 +26,8 @@ the fast **`punktfunk/1`** protocol.
   (probe burst over the real data plane → recommended bitrate, applied in one tap) and **forget**.
 - **Polished shell** — host cards, settings (resolution / refresh / host compositor / decoder /
   codec / bitrate / HDR / forwarded controller / gamepad type / system shortcuts / audio channels /
-  mic), a status-chip stream HUD, and the full trust surface. Stream input uses Win32 low-level
+  mic / stats-overlay level), the tiered stats overlay (Off / Compact / Normal / Detailed —
+  Ctrl+Alt+Shift+S cycles it live in the session window), and the full trust surface. Stream input uses Win32 low-level
   hooks with Moonlight-style capture: Ctrl+Alt+Shift+Q releases the pointer, a click on the stream
   re-captures it, and system shortcuts (Alt+Tab, Win, …) can act locally or forward to the host.