docs: rework client/crate READMEs, add missing ones

Rework the client READMEs to be accurate and inviting to first-time
visitors, and fill in the gaps where crates and tools had none.

- Rewrite clients/{apple,android,decky} READMEs (features-first, trim
  dense internal narrative; drop the stale "one session at a time" /
  "renegotiation not implemented" section from the Apple README).
- Add READMEs for clients/{linux,windows,probe}, which had none.
- Add crate READMEs for punktfunk-host, punktfunk-core, pf-driver-proto.
- Add brief READMEs for tools/{loss-harness,latency-probe}.
- Fix packaging/README duplicate "Option B" heading (bootc -> Option C).
- Fix docs-site/README stale docs/ -> design/ reference.
- De-stale packaging/windows/drivers/pf-dualsense README (drop "M0 spike"
  / external-checkout framing; reflect in-tree workspace + shipped +
  installer-bundled + multi-pad), keeping the driver-authoring lore.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

clients/decky/README.md

@@ -1,189 +1,84 @@
-# punktfunk Decky plugin (SteamOS / Steam Deck)
+# punktfunk — Steam Deck plugin (Decky)
 
-A **[Decky Loader](https://decky.xyz/)** plugin that adds a **punktfunk** panel to the Steam
-Deck's Quick Access Menu (the QAM, opened with the `…` button), so you can launch the
-punktfunk streaming client from **Gaming Mode** without dropping to the desktop.
+Stream to your **Steam Deck** without ever leaving Gaming Mode. This
+**[Decky Loader](https://decky.xyz/)** plugin adds a **punktfunk** panel to the Quick Access Menu
+(the `…` button): discover hosts on your network, pair with a PIN, tweak stream settings, and launch
+a fullscreen, gamescope-focused stream — all from the couch, gamepad-navigable.
 
-Because Decky plugins run inside Steam's CEF, the panel is built from real Steam UI
-primitives (`@decky/ui`: `PanelSection`, `PanelSectionRow`, `ButtonItem`, `Field`,
-`Spinner`) — so it looks and feels native to Gaming Mode.
-
-> **Full Gaming-Mode client.** Discovery, a fullscreen page, in-UI SPAKE2 PIN pairing,
-> stream settings, and a stream that actually launches fullscreen under gamescope (via a
-> Steam shortcut, MoonDeck-style). The video itself is the existing GTK4 flatpak client
-> (`io.unom.Punktfunk`) — the plugin discovers, pairs, configures, and *launches it the
-> right way* so gamescope focuses it. The Steam-shortcut launch + pairing need a real Deck
-> in Gaming Mode to fully confirm.
+The video itself is the native GTK4 Linux client (the `io.unom.Punktfunk` flatpak); the plugin
+discovers, pairs, configures, and *launches it the right way* so gamescope fullscreens it — the same
+Steam-shortcut trick MoonDeck uses. Because it's built from real Steam UI primitives (`@decky/ui`),
+the panel looks and feels native to Gaming Mode.
 
 ## What it does
 
-1. **Discover** — browses the LAN over mDNS for punktfunk/1 hosts (`_punktfunk._udp`,
-   backend `discover()` via `avahi-browse`). Shown in both the QAM panel and a **fullscreen
-   page** (Decky route `/punktfunk`, via `routerHook.addRoute`).
-2. **Pair** — for a `pair=required` host: a gamepad-navigable PIN keypad. The operator arms
-   pairing on the host (it shows a 4-digit PIN), the user enters it on the Deck, and the
-   backend runs the SPAKE2 ceremony headlessly via the flatpak client's `--pair` mode
-   (`pair()`), persisting the host as paired so the stream then connects silently.
-3. **Stream** — launches fullscreen in Gaming Mode. The plugin registers ONE hidden
-   non-Steam shortcut pointing at `bin/punktfunkrun.sh`, passes `PF_HOST` as the shortcut's
-   Steam launch options, and starts it with `SteamClient.Apps.RunGame` — so gamescope
-   focuses + fullscreens it. (A flatpak launched directly from the backend is invisible:
-   gamescope only focuses the process tree Steam launched via `reaper` — gamescope#484.)
-   The wrapper then execs `flatpak run io.unom.Punktfunk --connect <host>`.
-4. **Settings** — resolution / refresh / bitrate / gamepad / mic, written to the client's
-   `client-gtk-settings.json` (`get_settings`/`set_settings`), which the launched client reads.
+1. **Discover** — browses the LAN over mDNS for punktfunk hosts, in both the QAM panel and a
+   fullscreen page.
+2. **Pair** — for a host that requires it, a gamepad-navigable PIN keypad runs the SPAKE2 pairing
+   ceremony headlessly, then remembers the host so future streams connect silently.
+3. **Stream** — launches fullscreen via a hidden Steam shortcut so gamescope focuses it.
+4. **Settings** — resolution / refresh / bitrate / gamepad / mic, written to the client's config.
 
-To leave the stream: the in-client controller chord (**L1+R1+Start+Select**) or close the
-"game" from the Steam overlay — exiting the client ends the Steam game and returns to
-Gaming Mode automatically.
-
-## Architecture
-
-| File | Role |
-| --- | --- |
-| `src/index.tsx` | Frontend: QAM panel + the `/punktfunk` fullscreen page (host list, PIN keypad modal, settings). |
-| `src/steam.ts` | Steam-shortcut launch (`AddShortcut` / `SetAppLaunchOptions` / `RunGame`) — the focus-correct stream start. |
-| `src/backend.ts` | Typed `callable` bridges to `main.py`. |
-| `bin/punktfunkrun.sh` | The launch wrapper the Steam shortcut targets (so the window is focusable). |
-| `main.py` | Backend: `discover` / `pair` / `runner_info` / `get_settings` / `set_settings` / `kill_stream` / `check_update`. |
-| `plugin.json` | Decky plugin manifest. |
-| `update.json` | CI-baked `{channel, manifest}` — where `check_update()` polls (absent on dev builds). |
-| `decky.pyi` | Type stub for the injected `decky` module (vendored from the template). |
-
-### Discovery (`discover()`)
-
-Shells out to **`avahi-browse -rpt _punktfunk._udp`** (SteamOS and Bazzite ship
-`avahi-daemon`; this avoids bundling python-zeroconf):
-
-- `-r` resolve services, `-p` parseable output, `-t` terminate after the cache dump.
-- Resolved records start with `=` and are semicolon-separated:
-  `=;iface;protocol;name;type;domain;hostname;address;port;txt`.
-- The `txt` column is space-separated, quoted `"key=value"` tokens. We read the keys the
-  host advertises (`crates/punktfunk-host/src/discovery.rs`): `proto`, `fp`, `pair`, `id`.
-- Records are deduped on the `id` TXT key (a host re-advertises per interface and across
-  IPv4/IPv6), preferring the IPv4 address for the user-facing host string.
-
-### Client launch (`connect()`)
-
-The client binary `punktfunk-client` is resolved in order: `PATH` → `/usr/bin` →
-`/usr/local/bin` → `~/.local/bin` → a `flatpak run io.unom.Punktfunk` fallback. The resolved
-argv and a clear `client-not-found` error surface to the UI. The child PID is tracked so
-`disconnect()` (and plugin `_unload`) can terminate it.
-
-> On the **Steam Deck** the client install is the flatpak `io.unom.Punktfunk`
-> (`packaging/flatpak/`) — SteamOS `/usr` is read-only and lacks `libadwaita`/`libSDL3`, so
-> the flatpak (which bundles them) is the canonical path; the resolver's flatpak fallback
-> launches exactly that.
-
-## Prerequisites
-
-- **Decky Loader** installed on the Deck (https://decky.xyz/).
-- **`punktfunk-client`** (the GTK4/libadwaita Linux client, crate `punktfunk-client-linux`)
-  installed and runnable on the Deck — via `.deb`/RPM/flatpak, or symlinked into
-  `~/.local/bin`.
-- **avahi** (`avahi-daemon` + `avahi-browse`) for discovery — present on SteamOS/Bazzite.
-- A punktfunk/1 host on the LAN (`punktfunk-host serve` or `punktfunk1-host`).
-
-## Build
-
-```sh
-pnpm install
-pnpm build      # rollup → dist/index.js
-```
-
-(`npm install && npm run build` also works.)
+To leave a stream: the in-client controller chord (**L1 + R1 + Start + Select**), or close the
+"game" from the Steam overlay — either returns you to Gaming Mode.
 
 ## Install on the Deck
 
-### Option A — Decky "install from URL" (recommended; published by CI)
+You need **[Decky Loader](https://decky.xyz/)** and the **`io.unom.Punktfunk` flatpak**
+([`packaging/flatpak`](../../packaging/flatpak/README.md)) installed on the Deck — SteamOS `/usr` is
+read-only, so the flatpak (which bundles libadwaita/SDL3) is the canonical client. Discovery uses
+`avahi-browse`, which ships on SteamOS/Bazzite.
 
-CI (`.gitea/workflows/decky.yml`) builds the plugin into a store-layout zip and publishes it to
-Gitea's **generic package registry** on every push to `main` and on `v*` tags, exposing a stable
-URL. In Decky's settings → **Developer Mode** → **Install Plugin from URL**, paste:
+**Recommended — install from URL** (published by CI): in Decky → Settings → **Developer Mode** →
+**Install Plugin from URL**, paste:
 
 ```
 https://git.unom.io/api/packages/unom/generic/punktfunk-decky/latest/punktfunk.zip
 ```
 
-(or a pinned version: `.../punktfunk-decky/<version>/punktfunk.zip`). On tags the same zip is
-also attached to the Gitea release. The zip's layout is the store-required one — a single
-top-level `punktfunk/` dir holding `plugin.json`, `package.json`, `main.py`, `dist/index.js`,
-`README.md`, and `LICENSE`.
+(or a pinned `.../punktfunk-decky/<version>/punktfunk.zip`). The plugin then **self-updates** without
+the Decky store — when a newer build exists, an **Update to vX** button appears and drives Decky
+Loader's own (SHA-256-verified) install.
 
-### Option B — manual dev copy (sideload)
-
-Decky's `~/homebrew/plugins/` is **root-owned** (PluginLoader runs as root and manages it), so a
-plain `rsync` into it fails — stage to a writable temp dir, then `sudo`-install and restart the
-loader. The two helper scripts do exactly this:
+## Build & sideload (development)
 
 ```sh
 cd clients/decky
 pnpm install
+pnpm build                             # rollup → dist/index.js
 pnpm run package                       # → out/punktfunk/ + out/punktfunk-v<ver>.zip
-DECK=deck@<deck-ip> pnpm run deploy    # rsync → /tmp, sudo cp into plugins/, chown root, restart
+DECK=deck@<deck-ip> pnpm run deploy    # rsync → /tmp, sudo-install into the root-owned plugins dir, restart loader
 ```
 
-`deploy.sh` prompts for the Deck's sudo password interactively (via `ssh -t`); set `DECKPASS=…`
-to run it non-interactively. Equivalent by hand:
+`~/homebrew/plugins/` is root-owned (the loader runs as root), so `deploy.sh` stages to a temp dir
+then `sudo`-installs and restarts the loader — set `DECKPASS=…` to run it non-interactively. A loader
+restart is required for an out-of-band install to appear.
 
-```sh
-cd clients/decky && pnpm build && bash scripts/package.sh
-rsync -azp --delete out/punktfunk/ deck@<deck-ip>:/tmp/punktfunk/
-ssh -t deck@<deck-ip> 'sudo sh -c "rm -rf ~deck/homebrew/plugins/punktfunk && \
-  cp -r /tmp/punktfunk ~deck/homebrew/plugins/punktfunk && \
-  chown -R root:root ~deck/homebrew/plugins/punktfunk && systemctl restart plugin_loader"'
-```
+## Architecture
 
-A loader restart is required for an out-of-band install to appear. The **punktfunk** panel then
-shows up in the Quick Access Menu.
+| File | Role |
+| --- | --- |
+| `src/index.tsx` | Frontend: QAM panel + the `/punktfunk` fullscreen page (host list, PIN keypad, settings). |
+| `src/steam.ts` | Steam-shortcut launch (`AddShortcut` / `SetAppLaunchOptions` / `RunGame`) — the focus-correct stream start. |
+| `src/backend.ts` | Typed `callable` bridges to `main.py`. |
+| `bin/punktfunkrun.sh` | The launch wrapper the Steam shortcut targets (so the window is focusable). |
+| `main.py` | Backend: `discover` (via `avahi-browse`) / `pair` / settings / `kill_stream` / `check_update`. |
+| `plugin.json` · `update.json` | Decky manifest; CI-baked update channel. |
 
-> The plugin launches the client via the flatpak `io.unom.Punktfunk` (see
-> [`../../packaging/flatpak/README.md`](../../packaging/flatpak/README.md)) — install that on
-> the Deck too, or the panel's Connect surfaces a `client-not-found` error.
-
-## Updating (self-update, no store)
-
-The plugin updates itself without the official Decky store. CI (`decky.yml`) publishes a tiny
-per-channel `manifest.json` next to the zip in the Gitea registry:
-
-```json
-{"version":"0.3.123","artifact":".../punktfunk-decky/0.3.123/punktfunk.zip","sha256":"…"}
-```
-
-and bakes an `update.json` (`{channel, manifest}`) into the plugin so it knows which channel it was
-installed from. The backend `check_update()` reads the **installed** version from `package.json` —
-the value Decky itself reports (it does **not** read `plugin.json`) — fetches the channel manifest,
-and compares. When a newer build exists the frontend shows an **Update to vX** button that drives
-Decky Loader's own install RPC:
-
-```ts
-window.DeckyBackend.callable("utilities/install_plugin")(artifact, "punktfunk", version, hash, /*UPDATE=*/2)
-```
-
-The loader (root) downloads the immutable per-version zip, **SHA-256-verifies** it against `hash`,
-replaces `~/homebrew/plugins/punktfunk`, and hot-reloads — the unprivileged backend never writes the
-root-owned plugins dir itself. `window.DeckyBackend` / `utilities/install_plugin` are loader
-internals (not `@decky/api`), so every access is guarded; missing them, the button falls back to a
-toast pointing at **Install Plugin from URL**.
-
-> CI stamps a **plain numeric** semver per channel (`0.3.<run>` canary, `X.Y.Z` stable) into
-> `package.json`. Decky's `compare-versions` orders pre-release identifiers lexically (so `ci10 < ci9`)
-> — a `-ciN` suffix would mis-detect updates.
-
-**Optional — native Updates tab:** Decky's store is single-source (a custom store URL *replaces* the
-official catalog), so punktfunk doesn't ship one by default. A user who wants the native update badge
-can point Decky → Settings → **Custom store** at a punktfunk-only store JSON — not recommended if you
-use other plugins, since it hides the official catalog.
+The client binary is resolved `PATH` → `/usr/bin` → `/usr/local/bin` → `~/.local/bin` → a
+`flatpak run io.unom.Punktfunk` fallback, so the flatpak install always works.
 
 ## Limitations / next steps
 
-- **Needs on-Deck validation in Gaming Mode**: the Steam-shortcut launch (`AddShortcut` /
-  `RunGame` / the `gameId` encoding) and the headless pairing env are coded to MoonDeck's
-  proven pattern but verified only at build time here.
-- mDNS discovery depends on `avahi-browse`; no manual "add host by IP" entry yet.
-- No in-stream overlay (latency/bitrate HUD) inside the plugin — the client owns the session
-  once launched; leave it with the L1+R1+Start+Select chord.
-- Pairing requires the operator to **arm pairing on the host** (so it shows the PIN); the
-  plugin can't arm it remotely (no host mgmt token on the Deck).
-- Settings are written to the flatpak's sandbox config path; if the client ever moves its
-  config location, that path mapping must follow.
+- **Needs on-Deck validation in Gaming Mode** — the Steam-shortcut launch and headless pairing follow
+  MoonDeck's proven pattern but are verified only at build time here.
+- No manual "add host by IP" entry yet (discovery is mDNS-only).
+- No in-stream overlay inside the plugin — the client owns the session once launched.
+- Pairing needs the operator to **arm pairing on the host** so it shows the PIN; the plugin can't arm
+  it remotely.
+
+## Related
+
+- **[Documentation](https://docs.punktfunk.unom.io/docs/steam-deck)** — Steam Deck setup guide
+- **[Linux client](../linux/README.md)** — the app this plugin launches
+- **[Project README](../../README.md)** — the host, the other clients, and how it all fits together