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>

packaging/bazzite/README.md

@@ -339,7 +339,7 @@ control port (UDP 9777) + mDNS + the mgmt/library API (TCP 47990, HTTPS + mTLS).
 host runs `serve --gamestream` (both planes). The
 per-port breakdown below is for reference (or for opening ports by hand); the ports are the code
 constants (`crates/punktfunk-host/src/gamestream/mod.rs`, `mgmt.rs`) and the GameStream-host port-map
-(`design/gamestream-host-plan.md`).
+(punktfunk-planning: `gamestream-host-plan.md`).
 
 **GameStream / Moonlight ports** (fixed; Moonlight derives them from the HTTP base). These only apply
 when the host runs `serve --gamestream` (the bundled unit's default); on a bare-`serve` native-only

packaging/debian/README.md

@@ -2,7 +2,8 @@
 
 `punktfunk-host` is published as a `.deb` to **Gitea's Debian package registry** in the public
 `unom` org, so the Ubuntu hosts update with plain `apt`. CI (`.gitea/workflows/deb.yml`) builds
-and publishes on every push to `main` (a rolling `0.5.0~ciN.g<sha>` build to the **`canary`** apt
+and publishes on every push to `main` (a rolling `<next-minor>~ciN.g<sha>` build — the base is
+derived from the latest stable tag by `scripts/ci/pf-version.sh` — to the **`canary`** apt
 distribution) and on `vX.Y.Z` tags (a clean `X.Y.Z` to the **`stable`** distribution, plus attached
 to the unified Gitea Release). The two are separate apt distributions, so a stable box never jumps
 to a canary build — see [Release Channels](https://punktfunk.unom.io/docs/channels). The repo line

packaging/flatpak/README.md

@@ -4,7 +4,8 @@ The native Linux **client** — the shell (crate `punktfunk-client-linux`, binar
 `punktfunk-client`) plus the Vulkan session binary it execs for streaming (crate
 `punktfunk-client-session`, binary `punktfunk-session`) — is
 published two ways by CI (`.gitea/workflows/flatpak.yml`), on every push to `main` (a rolling
-`0.0.1-ciN.<sha>` build) and on `v*` tags (a clean `X.Y.Z`):
+`<next-minor>-ciN.g<sha>` build, base derived from the latest stable tag by
+`scripts/ci/pf-version.sh`) and on `v*` tags (a clean `X.Y.Z`):
 
 1. **Hosted OSTree repo at `https://flatpak.unom.io`** (recommended) — a GPG-signed Flatpak
    remote served by a static Caddy container on unom-1, so users **install once and then
@@ -58,11 +59,11 @@ per-user (no root, survives SteamOS updates). This is what the Decky plugin uses
 repo above is the better path for a human on the Deck:
 
 ```sh
-# Pick a version: a tag like 1.2.3, or the newest main build's 0.0.1-ciN.gSHA.
+# Pick a version: a tag like 1.2.3, or the newest main build's <next-minor>-ciN.gSHA.
 VER=1.2.3
 URL="https://git.unom.io/api/packages/unom/generic/punktfunk-client-flatpak/$VER/punktfunk-client-$VER.flatpak"
 
-# Flathub must be enabled (it is on the Deck) so the GNOME runtime + ffmpeg-full pull in:
+# Flathub must be enabled (it is on the Deck) so the GNOME runtime + codecs-extra extension pull in:
 flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
 
 curl -fL -o /tmp/punktfunk-client.flatpak "$URL"
@@ -138,11 +139,19 @@ extension point (auto-downloaded with the runtime; no app-side codec declaration
 `--device=all` (GPU/VAAPI render node + evdev + the hidraw char-devices SDL3 needs for DualSense)
 + `--socket=pulseaudio` (PipeWire-pulse: playback + mic) + `--share=network`. Alongside it:
 `io.unom.Punktfunk.desktop`, `io.unom.Punktfunk.metainfo.xml`, `io.unom.Punktfunk.svg` (all
-installed by the manifest). `cargo-sources.json` (the offline crate cache) is a pure function of
+installed by the manifest). A `vulkan-headers` module supplies what the session binary's ash/Vulkan
+build needs. `cargo-sources.json` (the offline crate cache) is a pure function of
 `Cargo.lock`; CI regenerates it each build and it is **gitignored** — generate it on any box with
 network + `python3`/`aiohttp`/`tomlkit` (`build-flatpak.sh` does this automatically) and, for a
 build host that lacks those (the Deck), rsync the generated file in alongside the manifest.
 
+**Offline Skia:** the session binary's Skia console UI (`pf-console-ui` → `skia-safe`) normally
+downloads prebuilt `libskia` binaries at build time, which is dead in the offline sandbox — so the
+manifest pins a `skia-binaries-….tar.gz` source and points the build at it with
+`SKIA_BINARIES_URL: file://…`. When bumping the `skia-safe`/`skia-bindings` crate version, update
+that pinned tarball (URL + sha256) to the matching `skia-binaries` release or the build breaks
+offline.
+
 ## Hosting the repo (unom-1) + one-time setup
 
 The OSTree repo flatpak-builder produces is GPG-signed in CI and rsynced to unom-1, where a tiny

packaging/linux/steam-deck-gadget/README.md

@@ -12,7 +12,7 @@ binds the kernel `hid-steam` driver, but **Steam Input will not manage it**: Ste
 controller to USB **interface 2**, and a UHID device has no USB interface number (`Interface: -1` in
 Steam's `controller.txt`), so Steam enumerates it but never promotes it. A single-interface DualSense
 is accepted at `-1` (no ambiguity), but the multi-interface Deck specifically needs interface 2. See
-`design/steam-controller-deck-support.md` §11.
+punktfunk-planning: `steam-controller-deck-support.md` §11.
 
 A real multi-interface USB device with the controller on interface 2 requires a **USB gadget**.
 SteamOS ships every piece (`CONFIG_USB_DUMMY_HCD=m`, `CONFIG_USB_RAW_GADGET=m`,

packaging/linux/steam-deck-gadget/usbip-poc/README.md

@@ -17,7 +17,7 @@ sudo modprobe vhci_hcd
 sudo usbip attach -r 127.0.0.1 -b 0-0-0
 ```
 
-See `design/steam-deck-passthrough-plan.md` for the production build plan (vendor-trim the crate to
+See punktfunk-planning: `steam-deck-passthrough-plan.md` for the production build plan (vendor-trim the crate to
 drop the `rusb`/libusb dep; in-process `vhci_hcd` attach to avoid the `usbip` CLI; transport-select
 `raw_gadget`→`usbip`→UHID). `usbip` crate API: a custom `UsbInterfaceHandler` —
 `get_class_specific_descriptor()` = the 9-byte HID descriptor; `handle_urb()` dispatches EP0

packaging/rpm/README.md

@@ -3,7 +3,8 @@
 `punktfunk-host` is published as an RPM to **Gitea's RPM package registry** in the public `unom`
 org (stable groups `bazzite`/`fedora-44`, canary groups `bazzite-canary`/`fedora-44-canary`), so
 Bazzite / Fedora Atomic hosts layer and update it with `rpm-ostree`. CI (`.gitea/workflows/rpm.yml`)
-builds and publishes on every push to `main` (a rolling `0.5.0-0.ciN.g<sha>` build to the `*-canary`
+builds and publishes on every push to `main` (a rolling `<next-minor>-0.ciN.g<sha>` build — the base
+is derived from the latest stable tag by `scripts/ci/pf-version.sh` — to the `*-canary`
 groups) and on `vX.Y.Z` tags (a clean `X.Y.Z-1` to the base groups, plus attached to the unified
 Gitea Release) — separate repos, so a stable box never jumps to a canary build (see
 [Release Channels](https://punktfunk.unom.io/docs/channels)). The `baseurl` below subscribes to the

packaging/windows/README.md

@@ -3,7 +3,7 @@
 A one-file, signed `setup.exe` for the punktfunk streaming **host** on Windows, published to Gitea's
 generic package registry (`punktfunk-host-windows`) by `.gitea/workflows/windows-host.yml`.
 
-> Full picture (drivers-from-source, toolchain, CI, dev loop): **[`design/windows-build-and-packaging.md`](../../design/windows-build-and-packaging.md)**. This README is the `packaging/windows/` file index.
+> Full picture (drivers-from-source, toolchain, CI, dev loop): **punktfunk-planning: `windows-build-and-packaging.md`** (internal planning repo). This README is the `packaging/windows/` file index.
 
 ## Windows 11 22H2+ only (no Windows 10)
 
@@ -135,7 +135,7 @@ fresh install uses the generated random console password — read it from
 > needed). Building from source keeps `.dll`/`.inf`/`.cat` in lockstep. nefcon (the device-node tool -
 > the install creates the `root\pf_vdisplay` node with it, **never** `devgen`, which leaves persistent
 > phantom devices) is fetched + SHA-256-verified from its pinned release in `stage-pf-vdisplay.ps1`. See
-> [`design/windows-build-and-packaging.md`](../../design/windows-build-and-packaging.md) for the toolchain
+> punktfunk-planning: `windows-build-and-packaging.md` (internal planning repo) for the toolchain
 > + signing details.
 
 ## Dev iteration on the test box (driver)
@@ -179,4 +179,5 @@ Push a `vX.Y.Z` tag — one tag releases every platform (see
 [Release Channels](https://punktfunk.unom.io/docs/channels)). The workflow builds, signs, and
 publishes `punktfunk-host-setup-X.Y.Z.exe` + the public `.cer`, refreshes the stable `latest/`
 alias, and attaches the installer to the unified Gitea Release. Main pushes publish rolling
-`0.3.<run>` **canary** builds to the `canary/` alias.
+`<next-minor>.<run>` **canary** builds (base derived from the latest stable tag by
+`scripts/ci/pf-version.ps1`) to the `canary/` alias.

packaging/windows/drivers/pf-dualsense/README.md

@@ -87,7 +87,7 @@ silently breaks them:
   WUDFHost (so the per-instance statics don't collide), and the driver reads its pad index from the
   device Location (`WdfDeviceAllocAndQueryProperty`) to poll its own `*-boot-<index>` bootstrap
   mailbox (the DATA section itself is unnamed — the sealed pad channel,
-  `design/gamepad-channel-sealing.md` — and its `pad_index` is validated against this index on
-  attach).
+  punktfunk-planning: `gamepad-channel-sealing.md` — and its `pad_index` is validated against this
+  index on attach).
 - Port of the WDK `vhidmini2` UMDF2 sample; the DualSense identity + 273-byte descriptor + feature
-  blobs `0x05`/`0x09`/`0x20` come from `crates/punktfunk-host/src/inject/dualsense.rs`.
+  blobs `0x05`/`0x09`/`0x20` come from `crates/punktfunk-host/src/inject/proto/dualsense_proto.rs`.

packaging/windows/drivers/pf-xusb/README.md

@@ -15,7 +15,7 @@ instance (= player slot 0–3) with `CreateFile`, and polls it with buffered IOC
 - registers the XUSB interface with `WdfDeviceCreateDeviceInterface(device, &XUSB_GUID, NULL)`;
 - answers the XUSB IOCTLs (all `METHOD_BUFFERED`, delivered to user mode by the reflector) from
   controller state the host publishes into an **unnamed** shared DATA section reached over the
-  **sealed pad channel** (`design/gamepad-channel-sealing.md`): the host duplicates the section
+  **sealed pad channel** (punktfunk-planning: `gamepad-channel-sealing.md`): the host duplicates the section
   handle into this driver's WUDFHost, bootstrapped via the named `Global\pfxusb-boot-<index>`
   mailbox (`pf_driver_proto::gamepad::PadBootstrap`); a game's rumble (`SET_STATE`) is published
   back for the host to forward to the client.