feat(packaging): ship punktfunk everywhere, and deprecate the session's stray pairing flag

The rest of C1. A CLI that only exists in a dev tree is not a door anyone can use, so it
now builds and installs in deb, rpm, arch, nix, flatpak and MSIX alongside the client and
the session. On Windows it gets its own `AppListEntry="none"` application with the alias
`punktfunk.exe` — a command, not a Start-menu tile — which is what the Playnite importer
will shell to for `punktfunk library <host> --json`.

`punktfunk-session --pair` prints a deprecation notice and forwards. Pairing is a trust
ceremony and belongs to the brain, fronted by `punktfunk pair` or a shell; a renderer
owning one is precisely the mixing of concerns this split exists to undo. It keeps working
for a release, because someone's provisioning script is calling it today.

Decky's invocations are untouched and verified still working (`--list-hosts` JSON shape
unchanged, `--reachable` exit codes unchanged): those flags are a frozen compat contract
until Decky migrates to the verbs at its own pace.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

packaging/arch/PKGBUILD

@@ -96,10 +96,11 @@ build() {
   # opts back to libav VAAPI), and a failed open falls back to VAAPI so unsupported devices are safe.
   if [ "$CARCH" = 'aarch64' ]; then
     # Client-only: no host crate, so none of the encode features below apply.
-    cargo build --release --locked -p punktfunk-client-linux -p punktfunk-client-session
+    cargo build --release --locked -p punktfunk-client-linux -p punktfunk-client-session \
+      -p punktfunk-cli
   else
   cargo build --release --locked --features punktfunk-host/nvenc,punktfunk-host/vulkan-encode \
-    -p punktfunk-host -p punktfunk-client-linux -p punktfunk-client-session
+    -p punktfunk-host -p punktfunk-client-linux -p punktfunk-client-session -p punktfunk-cli
   # The status tray in its OWN cargo invocation — load-bearing, not tidiness. Cargo unifies features
   # across everything in one build, so co-building the tray with the host pulls the host's
   # ashpd -> zbus/tokio onto the tray's shared zbus; the tray (ksni async-io + blocking, no tokio
@@ -250,6 +251,8 @@ package_punktfunk-client() {
   install -Dm0755 "$T/punktfunk-client"  "$pkgdir/usr/bin/punktfunk-client"
   # The session streamer the shell execs for a connect (resolved as its sibling in /usr/bin).
   install -Dm0755 "$T/punktfunk-session" "$pkgdir/usr/bin/punktfunk-session"
+  # The headless CLI (design/client-architecture-split.md §4).
+  install -Dm0755 "$T/punktfunk" "$pkgdir/usr/bin/punktfunk"
   install -Dm0644 "$R/packaging/linux/io.unom.Punktfunk.desktop" \
     "$pkgdir/usr/share/applications/io.unom.Punktfunk.desktop"
   # DualSense hidraw access (full pad fidelity through SDL's HIDAPI driver).

packaging/debian/build-client-deb.sh

@@ -38,9 +38,11 @@ BIN="$OUTDIR/$PKG"
 # The Vulkan/Skia session streamer the shell execs for a connect — shipped alongside the shell
 # (the shell resolves it as its /usr/bin sibling), or desktop streaming breaks.
 SESSION_BIN="$OUTDIR/punktfunk-session"
+# The headless CLI (design/client-architecture-split.md §4) ships with every client.
+CLI_BIN="$OUTDIR/punktfunk"
 if [ ! -x "$BIN" ] || [ ! -x "$SESSION_BIN" ]; then
   echo "==> building $CRATE + punktfunk-client-session (release${TARGET:+ for $TARGET})"
-  cargo build --release --locked "${CARGO_TARGET_ARGS[@]}" -p "$CRATE" -p punktfunk-client-session
+  cargo build --release --locked "${CARGO_TARGET_ARGS[@]}" -p "$CRATE" -p punktfunk-client-session -p punktfunk-cli
 fi
 
 STAGE="$(mktemp -d)"
@@ -50,6 +52,7 @@ DOCDIR="$STAGE/usr/share/doc/$PKG"
 # --- file layout --------------------------------------------------------------
 install -Dm0755 "$BIN"                                   "$STAGE/usr/bin/$PKG"
 install -Dm0755 "$SESSION_BIN"                           "$STAGE/usr/bin/punktfunk-session"
+install -Dm0755 "$CLI_BIN"                               "$STAGE/usr/bin/punktfunk"
 install -Dm0644 packaging/linux/io.unom.Punktfunk.desktop \
                 "$STAGE/usr/share/applications/io.unom.Punktfunk.desktop"
 # DualSense hidraw access (full pad fidelity through SDL's HIDAPI driver).

packaging/flatpak/io.unom.Punktfunk.yml

@@ -222,8 +222,12 @@ modules:
       # unification identical to a workspace build (the pinned skia-binaries archive's
       # `pdf-textlayout-vulkan` key must match the resolved feature set).
       - cargo --offline build --release -p punktfunk-client-linux -p punktfunk-client-session
+          -p punktfunk-cli
       - install -Dm0755 target/release/punktfunk-client ${FLATPAK_DEST}/bin/punktfunk-client
       - install -Dm0755 target/release/punktfunk-session ${FLATPAK_DEST}/bin/punktfunk-session
+      # The headless CLI (design/client-architecture-split.md §4) — reachable as
+      # `flatpak run --command=punktfunk io.unom.Punktfunk …`.
+      - install -Dm0755 target/release/punktfunk ${FLATPAK_DEST}/bin/punktfunk
       # Desktop entry (renamed to the app id; Exec is the in-sandbox binary).
       - install -Dm0644 packaging/flatpak/io.unom.Punktfunk.desktop
           ${FLATPAK_DEST}/share/applications/io.unom.Punktfunk.desktop

packaging/nix/packages.nix

@@ -224,7 +224,7 @@ in
       # so build the session without it. The GTK shell (punktfunk-client-linux) is skia-free and full.
       # Re-adding the Skia OSD under Nix is tracked in packaging/nix/README.md.
       cargoExtraArgs =
-        "--locked -p punktfunk-client-linux -p punktfunk-client-session "
+        "--locked -p punktfunk-client-linux -p punktfunk-client-session -p punktfunk-cli "
         + "--no-default-features --features punktfunk-client-session/pyrowave";
 
       # pf-ffvk runs bindgen over libavutil/hwcontext_vulkan.h, which `#include <vulkan/vulkan.h>`.

packaging/rpm/punktfunk.spec

@@ -226,10 +226,10 @@ export PUNKTFUNK_BUILD_VERSION="%{version}-%{release}"
 # back to libav VAAPI), and a failed open falls back to VAAPI so unsupported devices degrade gracefully.
 %if %{with host}
 cargo build --release --locked --features punktfunk-host/nvenc,punktfunk-host/vulkan-encode \
-  -p punktfunk-host -p punktfunk-client-linux -p punktfunk-client-session
+  -p punktfunk-host -p punktfunk-client-linux -p punktfunk-client-session -p punktfunk-cli
 %else
 # Client-only (aarch64): no host crate, so none of the encode features apply.
-cargo build --release --locked -p punktfunk-client-linux -p punktfunk-client-session
+cargo build --release --locked -p punktfunk-client-linux -p punktfunk-client-session -p punktfunk-cli
 %endif
 # The status tray in its OWN cargo invocation — load-bearing, not tidiness. Cargo unifies features
 # across everything in one build, so co-building the tray with the host pulls the host's
@@ -326,6 +326,9 @@ done
 install -Dm0755 target/release/punktfunk-client %{buildroot}%{_bindir}/punktfunk-client
 # The session streamer the shell execs for a connect (resolved as its sibling in %{_bindir}).
 install -Dm0755 target/release/punktfunk-session %{buildroot}%{_bindir}/punktfunk-session
+%{_bindir}/punktfunk
+# The headless CLI (design/client-architecture-split.md §4).
+install -Dm0755 target/release/punktfunk %{buildroot}%{_bindir}/punktfunk
 install -Dm0644 packaging/linux/io.unom.Punktfunk.desktop \
                 %{buildroot}%{_datadir}/applications/io.unom.Punktfunk.desktop
 # DualSense hidraw access (full pad fidelity through SDL's HIDAPI driver).