Windows client: ship a per-user Inno Setup installer + portable zip as the default download; keep the MSIX for the Store

A user report: launching via Big Picture doesn't work and the Steam overlay never appears. Not because the app is UWP (it's full-trust Win32 under MSIX too) but because of the MSIX install SHAPE: the exe lives under the ACL'd WindowsApps dir Steam's non-Steam-game picker can't browse, and alias/shell:AppsFolder activation defeats the overlay's injection — Steam must spawn the exe itself from a normal path. - punktfunk-client.iss: per-user (no UAC) install to %LOCALAPPDATA%\Programs\Punktfunk. Re-creates the manifest's grants in HKCU (punktfunk:// scheme, Start entries, {app} on the user PATH for the punktfunk CLI) and fetches the Windows App Runtime when missing. - pack-client-installer.ps1: consumes pack-msix.ps1's layout (one assembly, three artifacts), signs the four exes individually, emits setup.exe + a portable zip. Same signing backends and fail-closed-on-tags rule as the sibling scripts; no .cer (an exe runs untrusted). - windows-client.yml: pack step after the MSIX, publish + release-attach the new artifacts (canary/latest aliases punktfunk-client-setup_<arch>.exe, ..._<arch>-portable.zip). - deeplink.rs: write_shortcut targets the app-execution alias only under package identity; unpackaged installs have no alias but a stable path, so they target current_exe(). has_package_identity() now shared with main.rs's AppUserModelID probe. - docs: install-client (installer default + a 'Launching through Steam' section + MSIX/portable as alternates), channels, uninstall, clients, platforms.json (both copies, drift check green).
Merge pull request 'KWin creates our virtual output disabled and refuses to stream it — enable it and retry' (#344 ) from worktree-kwin-vout-enable-repair into main
2026-08-20 00:52:46 +02:00 · 2026-08-19 20:48:43 +00:00 · 2026-08-19 22:39:11 +02:00 · 2026-08-19 19:01:45 +00:00 · 2026-08-19 21:01:00 +02:00 · 2026-08-19 20:57:02 +02:00
25 changed files with 1330 additions and 70 deletions
@@ -0,0 +1,6 @@
+<!-- What and why — the diff says how. -->
+
+**User-facing fact changed?** (an install step, a knob, a port, what a feature does, a limit)
+→ the docs-site page that owns it is updated in this PR, or this is n/a. Install/repo/port facts
+live in `data/platforms.json`. (CONTRIBUTING.md "Where facts live"; `docs-drift` in CI only
+catches the mechanical half.)
@@ -0,0 +1,63 @@
+# Smoke test for the guided installer (scripts/install.sh, docs-and-onboarding overhaul WP4).
+# Runs the script unattended inside a clean container per package family against the REAL
+# package registry — the one path a textual gate can't cover: does the repo line, the key import
+# and the install actually work today on a fresh box. `--no-start` because a container has no
+# user systemd; the script degrades to printing the enable command, which is also under test.
+#
+# Path-filtered on purpose: it pulls ~100 MB of packages per family, so it runs when the script
+# or its fact source changes, not on every push (check-docs-drift.sh gate 6 covers the cheap
+# half — the install lines in the script must match data/platforms.json verbatim — on every push).
+name: installer-smoke
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - scripts/install.sh
+      - data/platforms.json
+      - .gitea/workflows/installer-smoke.yml
+  pull_request:
+    paths:
+      - scripts/install.sh
+      - data/platforms.json
+      - .gitea/workflows/installer-smoke.yml
+
+jobs:
+  smoke:
+    name: smoke (${{ matrix.family }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # actions/checkout needs git + node + CA certs in the container; curl is the
+          # script's own prerequisite (it says so and stops without it).
+          - family: debian-13
+            image: debian:trixie
+            prep: apt-get update -qq && apt-get install -y -qq --no-install-recommends ca-certificates curl git nodejs
+          - family: fedora-44
+            image: fedora:44
+            prep: dnf install -y -q curl git nodejs
+          - family: arch
+            image: archlinux:base
+            prep: pacman -Sy --noconfirm --needed curl git nodejs && (pacman-key --init >/dev/null 2>&1 || true)
+    container:
+      image: ${{ matrix.image }}
+    steps:
+      - name: Prepare the container (${{ matrix.family }})
+        run: ${{ matrix.prep }}
+      - uses: actions/checkout@v4
+      # No tty → the script runs as --yes; --no-start because there is no user systemd here.
+      # Root without sudo → the script's sudo shim, another path under test.
+      - name: Run the installer unattended
+        run: sh scripts/install.sh --yes --no-start
+      - name: The host is installed and conflict-free
+        run: |
+          punktfunk-host --version
+          punktfunk-host detect-conflicts
+      - name: Re-running is a no-op install
+        run: sh scripts/install.sh --yes --no-start | grep -q 'already installed'
@@ -56,8 +56,12 @@
 #
 # ── Packaging (the `Pack + sign MSIX` step onward; skipped on pull requests) ──────────────────────
 #
-# Publishes signed MSIX packages (x64 + ARM64) to Gitea's generic package registry, so Windows boxes
-# can install a real package (Start tile, clean install/uninstall) instead of a loose exe.
+# Publishes THREE artifacts per arch (x64 + ARM64) to Gitea's generic package registry, all packed
+# from one assembled layout:
+#   punktfunk-client-setup_<arch>.exe   — Inno Setup per-user installer, the DEFAULT download
+#                                         (stable path Steam can launch: overlay + Big Picture work)
+#   punktfunk-client-windows_<arch>-portable.zip — the same file set, no installer
+#   punktfunk-client-windows_<arch>.msix — kept for Microsoft Store compatibility
 #
 # Registry (public, unom org): https://git.unom.io/unom/-/packages  (generic group)
 # Packaging internals: clients/windows/packaging/README.md.
@@ -283,6 +287,28 @@ jobs:
            -Version $env:MSIX_VERSION -Arch ${{ matrix.arch }} `
            -TargetDir ${{ matrix.td }}\${{ matrix.target }}\release -OutDir ${{ matrix.td }}\msix

+      # The DEFAULT download: a per-user Inno Setup exe + a portable zip, packed from the layout
+      # the MSIX step just assembled. The MSIX shape (WindowsApps ACLs, alias-only activation)
+      # breaks Steam's non-Steam-game picker, the Steam overlay injection and Big Picture launch;
+      # the installer's stable %LOCALAPPDATA%\Programs\Punktfunk path is the fix. The MSIX stays
+      # published for Microsoft Store compatibility. Same signing env as the MSIX step above.
+      - name: Pack + sign installer + portable zip
+        if: github.event_name != 'pull_request'
+        shell: pwsh
+        env:
+          AZURE_CODESIGNING_ENDPOINT: https://neu.codesigning.azure.net/
+          AZURE_CODESIGNING_ACCOUNT: unomsigning
+          AZURE_CODESIGNING_PROFILE: unom-io
+          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+          AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
+          MSIX_CERT_PFX_B64: ${{ secrets.MSIX_CERT_PFX_B64 }}
+          MSIX_CERT_PASSWORD: ${{ secrets.MSIX_CERT_PASSWORD }}
+        run: |
+          & clients/windows/packaging/pack-client-installer.ps1 `
+            -Version $env:MSIX_VERSION -Arch ${{ matrix.arch }} `
+            -LayoutDir ${{ matrix.td }}\msix\layout -OutDir ${{ matrix.td }}\installer
+
      - name: Publish to Gitea generic registry
        if: github.event_name != 'pull_request'
        shell: pwsh
@@ -301,7 +327,10 @@ jobs:
          # on that accident, so removing the quotes can't silently reintroduce it.
          $aliasNames = @{ "$($env:MSIX_PATH)" = "$($env:PKG)_${{ matrix.arch }}.msix" }
          if ($env:MSIX_CER_PATH) { $aliasNames[$env:MSIX_CER_PATH] = "$($env:PKG)_${{ matrix.arch }}.cer" }
-          $files = @($env:MSIX_PATH, $env:MSIX_CER_PATH) | Where-Object { $_ -and (Test-Path $_) }
+          # The installer + portable zip (the default download; docs point at these alias URLs).
+          if ($env:CLIENT_SETUP_PATH) { $aliasNames[$env:CLIENT_SETUP_PATH] = "punktfunk-client-setup_${{ matrix.arch }}.exe" }
+          if ($env:CLIENT_ZIP_PATH) { $aliasNames[$env:CLIENT_ZIP_PATH] = "$($env:PKG)_${{ matrix.arch }}-portable.zip" }
+          $files = @($env:MSIX_PATH, $env:MSIX_CER_PATH, $env:CLIENT_SETUP_PATH, $env:CLIENT_ZIP_PATH) | Where-Object { $_ -and (Test-Path $_) }
          if (-not $files) { throw "pack produced no artifacts to publish" }
          function Put($f, $url) {
            # The generic registry makes a versioned path immutable and 409s a re-upload, so a tag
@@ -324,10 +353,11 @@ jobs:
            Put $f "$base/$alias/$an"
          }

-      # On a real release, also attach the MSIX (+ its .cer) to the unified Gitea Release. Both
-      # arch legs attach to the same release concurrently — the helper's create-or-fetch handles
-      # the race, and x64/arm64 filenames differ so the assets don't collide.
-      - name: Attach MSIX to the Gitea release (stable tags only)
+      # On a real release, also attach the installer + portable zip + MSIX (+ its .cer) to the
+      # unified Gitea Release. Both arch legs attach to the same release concurrently — the
+      # helper's create-or-fetch handles the race, and x64/arm64 filenames differ so the assets
+      # don't collide.
+      - name: Attach client artifacts to the Gitea release (stable tags only)
        if: startsWith(gitea.ref, 'refs/tags/v')
        shell: pwsh
        env:
@@ -335,6 +365,6 @@ jobs:
        run: |
          . scripts/ci/gitea-release.ps1
          $rid = Ensure-GiteaRelease -Tag $env:GITHUB_REF_NAME -Name $env:GITHUB_REF_NAME -Prerelease 'auto'
-          foreach ($f in @($env:MSIX_PATH, $env:MSIX_CER_PATH)) {
+          foreach ($f in @($env:CLIENT_SETUP_PATH, $env:CLIENT_ZIP_PATH, $env:MSIX_PATH, $env:MSIX_CER_PATH)) {
            if ($f -and (Test-Path $f)) { Upsert-GiteaAsset -ReleaseId $rid -File $f }
          }
@@ -113,7 +113,7 @@ PR.

 CI enforces the cheap half of this (`scripts/ci/check-docs-drift.sh` and `check-docs-links.sh`):
 the OpenAPI snapshot must match `api/openapi.json`, the docs-site copy of `data/platforms.json` must
-match the canonical one, every `PUNKTFUNK_*` variable the docs mention
+match the canonical one, `scripts/install.sh` must carry the file's install lines verbatim, every `PUNKTFUNK_*` variable the docs mention
 must still exist in the tree, the counts of undocumented `PUNKTFUNK_*` variables and undocumented
 `punktfunk-host` subcommands may never grow (document the new knob, or consciously raise the
 baseline in the script), and internal docs links must resolve.
@@ -33,11 +33,14 @@ the fast **`punktfunk/1`** protocol.
  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.

-Builds and ships for both **x64** and **ARM64** as a signed **MSIX**.
+Builds and ships for both **x64** and **ARM64**, three ways from one layout: a signed **installer**
+(the default — a per-user setup.exe whose stable install path Steam can launch, so the Steam
+overlay and Big Picture work), a **portable zip**, and a signed **MSIX** (kept for Microsoft Store
+compatibility).

 ## Get it

-Install the signed MSIX from the package registry — see
+Install the signed installer from the package registry — see
 **[docs.punktfunk.unom.io/docs/install-client](https://docs.punktfunk.unom.io/docs/install-client)**.
 A stock [Moonlight](https://moonlight-stream.org/) client also works over GameStream if you prefer.

@@ -58,7 +61,7 @@ punktfunk-client --headless --speed-test --connect host[:port]  # probe burst
 ```

 > `CARGO_HOME` must be an ASCII path — non-ASCII characters break SDL3's MSVC precompiled-header
-> build. Packaging (MSIX manifest, signing) lives in [`packaging/`](packaging/).
+> build. Packaging (MSIX manifest, the Inno Setup installer, signing) lives in [`packaging/`](packaging/).

 ## Layout

@@ -79,7 +82,7 @@ src/
  trust.rs · discovery.rs persistent identity, TOFU/PIN pairing, mDNS browse
  probe.rs · wol.rs       speed probe · Wake-on-LAN
  logfile.rs              log tee to %LOCALAPPDATA%
-packaging/                MSIX manifest, signing, pack script
+packaging/                MSIX manifest + Inno Setup installer, signing, pack scripts
 ```

 ## Manual smoke checklist
@@ -1,11 +1,30 @@
-# punktfunk Windows client — MSIX packaging
+# punktfunk Windows client — packaging

-The Windows client ships as **signed MSIX** packages so Windows boxes get a real package (Start
-tile, clean install/uninstall) instead of a loose exe. CI builds + publishes them from
-[`.gitea/workflows/windows-client.yml`](../../../.gitea/workflows/windows-client.yml) to Gitea's
+The Windows client ships **three ways, packed from one assembled layout** by CI
+([`.gitea/workflows/windows-client.yml`](../../../.gitea/workflows/windows-client.yml)) to Gitea's
 **generic** package registry (`https://git.unom.io/unom/-/packages`), on every `main` push that
 touches the client (canary) and on `vX.Y.Z` release tags (stable) — see
-[Release Channels](https://punktfunk.unom.io/docs/channels).
+[Release Channels](https://punktfunk.unom.io/docs/channels):
+
+1. **Inno Setup installer** (`punktfunk-client-setup_<arch>.exe`) — the **default download**. A
+   per-user, no-UAC install to `%LOCALAPPDATA%\Programs\Punktfunk`. It exists because the MSIX
+   install shape breaks the top user-reported flows: the exe lands under the ACL'd
+   `C:\Program Files\WindowsApps`, which Steam's *Add a Non-Steam Game* picker can't browse, and
+   the alias/`shell:AppsFolder` activation defeats the Steam overlay's injection and Big Picture
+   launch — Steam must spawn the exe itself from a normal path. `punktfunk-client.iss` +
+   `pack-client-installer.ps1`; it re-creates the manifest's declarative grants per-user
+   (`punktfunk://` in HKCU Classes, Start shortcuts, `{app}` on the user PATH for the
+   `punktfunk` CLI) and fetches the Windows App Runtime when missing.
+2. **Portable zip** (`punktfunk-client-windows_<arch>-portable.zip`) — the same signed file set,
+   nothing registered.
+3. **Signed MSIX** (`punktfunk-client-windows_<arch>.msix`) — kept for **Microsoft Store**
+   compatibility. Everything below the fold documents this path.
+
+`pack-msix.ps1` assembles the layout and packs the MSIX; `pack-client-installer.ps1` then consumes
+that same `layout/` for the installer + zip (and signs the four exes individually — the MSIX only
+signs its container).
+
+# MSIX packaging

 **Two architectures, one x64 runner.** Both `x64` and `arm64` packages are produced off the single
 x64 Windows runner — `x86_64-pc-windows-msvc` builds natively, `aarch64-pc-windows-msvc` is
@@ -0,0 +1,246 @@
+<#
+.SYNOPSIS
+  Pack + sign the punktfunk Windows client as an Inno Setup setup.exe (the default download) and a
+  portable .zip, from the layout pack-msix.ps1 already assembled.
+
+.DESCRIPTION
+  Runs AFTER pack-msix.ps1 in the same job and consumes its $OutDir\layout verbatim — one assembly,
+  three artifacts (.msix, setup.exe, portable .zip). Why the installer exists at all: the MSIX
+  install shape (WindowsApps ACLs + alias-only activation) breaks Steam's non-Steam-game picker,
+  the Steam overlay's injection, and Big Picture launching — see punktfunk-client.iss's header.
+
+  Steps:
+    1. stage the runtime file set from -LayoutDir (drops AppxManifest.xml + the tile Assets),
+    2. sign the four exes individually (the MSIX only signs its container),
+    3. zip the stage -> the portable build,
+    4. ISCC punktfunk-client.iss over the same stage, sign the setup.exe,
+    5. emit CLIENT_SETUP_PATH / CLIENT_ZIP_PATH to GITHUB_ENV for the publish step.
+
+  Signing backend precedence is identical to pack-msix.ps1 / pack-host-installer.ps1 (Azure
+  Artifact Signing -> supplied .pfx -> ephemeral self-signed; fail closed on v* tags). No .cer is
+  exported here: unlike an MSIX, a plain exe RUNS regardless of signer trust — an untrusted
+  signature only costs a SmartScreen warning, so canary self-signed builds need nothing imported.
+
+.EXAMPLE
+  pwsh -File pack-client-installer.ps1 -Version 0.2.137.0 -Arch x64 `
+    -LayoutDir C:\t\msix\layout -OutDir C:\t\installer
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)][string]$Version,                 # 4-part numeric, same as the MSIX
+    [Parameter(Mandatory = $true)][string]$LayoutDir,               # pack-msix.ps1's $OutDir\layout
+    [ValidateSet('x64', 'arm64')][string]$Arch = 'x64',
+    [string]$OutDir = (Join-Path (Split-Path -Parent $LayoutDir) 'installer'),
+    # Subject for the EPHEMERAL self-signed fallback only; Azure/pfx carry their own subjects.
+    [string]$Publisher = "CN=unom - Enrico B$([char]0xFC)hler, O=unom - Enrico B$([char]0xFC)hler, L=Rottweil, S=Baden-W$([char]0xFC)rttemberg, C=DE",
+    [string]$PfxBase64 = $env:MSIX_CERT_PFX_B64,                    # reuse the client's signing secret
+    [string]$PfxPassword = $env:MSIX_CERT_PASSWORD,
+    [string]$AzureEndpoint = $env:AZURE_CODESIGNING_ENDPOINT,
+    [string]$AzureAccount = $env:AZURE_CODESIGNING_ACCOUNT,
+    [string]$AzureProfile = $env:AZURE_CODESIGNING_PROFILE,
+    [string]$AzureDlib = $env:AZURE_CODESIGNING_DLIB,
+    [ValidateSet('auto', 'true', 'false')][string]$RequireSignedCert = 'auto',
+    [switch]$NoSign                                                 # skip signing (local debug)
+)
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+# Keep the "check $LASTEXITCODE myself" model (see pack-host-installer.ps1): pwsh 7.4 must not
+# turn a non-zero native exit into a terminating error before Sign-File's timestamp retry runs.
+$PSNativeCommandUseErrorActionPreference = $false
+
+if ($Version -notmatch '^\d+\.\d+\.\d+\.\d+$') {
+    throw "Version must be 4-part numeric (Major.Minor.Build.Revision); got '$Version'."
+}
+
+$here = Split-Path -Parent $MyInvocation.MyCommand.Path
+$iss = Join-Path $here 'punktfunk-client.iss'
+
+# --- locate ISCC (Inno Setup) + signtool (Windows SDK) — same finders as the sibling scripts ---
+function Find-Iscc {
+    foreach ($p in @(
+            'C:\Program Files (x86)\Inno Setup 6\ISCC.exe',
+            'C:\Program Files\Inno Setup 6\ISCC.exe')) {
+        if (Test-Path $p) { return $p }
+    }
+    $c = Get-Command iscc -ErrorAction SilentlyContinue
+    if ($c) { return $c.Source }
+    throw "ISCC.exe (Inno Setup 6, any 6.x) not found - install it (choco install innosetup -y)."
+}
+function Find-SdkTool([string]$name) {
+    $root = 'C:\Program Files (x86)\Windows Kits\10\bin'
+    $hit = Get-ChildItem -Path $root -Recurse -Filter $name -ErrorAction SilentlyContinue |
+        Where-Object { $_.FullName -match '\\(10\.0\.\d+\.\d+)\\x64\\' } |
+        Sort-Object { [version]([regex]::Match($_.FullName, '\\(10\.0\.\d+\.\d+)\\x64\\').Groups[1].Value) } |
+        Select-Object -Last 1
+    if (-not $hit) { throw "$name not found under $root - install the Windows 10/11 SDK." }
+    $hit.FullName
+}
+function Find-AzureDlib([string]$Explicit) {
+    if ($Explicit) {
+        if (-not (Test-Path $Explicit)) { throw "AZURE_CODESIGNING_DLIB points at a missing file: $Explicit" }
+        return (Resolve-Path $Explicit).Path
+    }
+    $roots = @(
+        (Join-Path $env:USERPROFILE '.nuget\packages\microsoft.trusted.signing.client'),
+        'C:\trusted-signing\microsoft.trusted.signing.client'
+    ) | Where-Object { $_ -and (Test-Path $_) }
+    $hit = $roots | ForEach-Object { Get-ChildItem -Path $_ -Recurse -Filter 'Azure.CodeSigning.Dlib.dll' -ErrorAction SilentlyContinue } |
+        Where-Object { $_.FullName -match '\\bin\\x64\\' } |
+        Sort-Object LastWriteTime | Select-Object -Last 1
+    if (-not $hit) {
+        throw ("Azure.CodeSigning.Dlib.dll not found. Install the signing client on this box, e.g. " +
+               "``nuget install Microsoft.Trusted.Signing.Client -OutputDirectory " +
+               "`$env:USERPROFILE\.nuget\packages``, or set AZURE_CODESIGNING_DLIB to its full path.")
+    }
+    $hit.FullName
+}
+$iscc = Find-Iscc
+Write-Host "ISCC: $iscc"
+
+# --- stage the runtime file set (the portable layout = what the installer lays down) ----------
+# Explicit list, not a wildcard copy: the MSIX layout also holds AppxManifest.xml and the tile
+# Assets, which mean nothing outside a package (the exes embed their icons via build.rs).
+$required = @('punktfunk-client.exe', 'punktfunk-session.exe', 'punktfunk-console.exe', 'punktfunk.exe',
+              'Microsoft.WindowsAppRuntime.Bootstrap.dll', 'SDL3.dll', 'resources.pri')
+$stage = Join-Path $OutDir 'portable'
+if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
+New-Item -ItemType Directory -Force -Path $stage | Out-Null
+foreach ($f in $required) {
+    $src = Join-Path $LayoutDir $f
+    if (-not (Test-Path $src)) { throw "missing '$f' in $LayoutDir (did pack-msix.ps1 run first?)" }
+    Copy-Item $src (Join-Path $stage $f) -Force
+}
+$licSrc = Join-Path $LayoutDir 'licenses'
+if (-not (Test-Path $licSrc)) { throw "missing licenses\ in $LayoutDir (did pack-msix.ps1 run first?)" }
+Copy-Item $licSrc (Join-Path $stage 'licenses') -Recurse -Force
+
+# --- signing backend, same precedence + fail-closed rule as pack-msix.ps1 ---------------------
+$requireCert = if ($RequireSignedCert -eq 'auto') { $env:GITHUB_REF -like 'refs/tags/v*' }
+               else { [Convert]::ToBoolean($RequireSignedCert) }
+if ($NoSign -and $requireCert) {
+    throw "release build ($env:GITHUB_REF) with -NoSign - refusing to publish an unsigned installer."
+}
+$pfxPath = Join-Path $OutDir 'signing.pfx'
+$azureMetadata = Join-Path $OutDir 'azure-codesigning.json'
+$signMode = 'none'
+$signtool = $null
+if (-not $NoSign) {
+    $signtool = Find-SdkTool 'signtool.exe'
+    Write-Host "signtool: $signtool"
+    if ($AzureEndpoint -and $AzureAccount -and $AzureProfile) {
+        $signMode = 'azure'
+        $AzureDlib = Find-AzureDlib $AzureDlib
+        @{
+            Endpoint               = $AzureEndpoint
+            CodeSigningAccountName = $AzureAccount
+            CertificateProfileName = $AzureProfile
+        } | ConvertTo-Json | Set-Content -Path $azureMetadata -Encoding utf8
+        Write-Host "signing via Azure Artifact Signing: $AzureAccount/$AzureProfile at $AzureEndpoint"
+        foreach ($v in 'AZURE_TENANT_ID', 'AZURE_CLIENT_ID', 'AZURE_CLIENT_SECRET') {
+            if (-not [Environment]::GetEnvironmentVariable($v)) {
+                throw ("Azure signing selected but $v is not set. The dlib authenticates with " +
+                       "DefaultAzureCredential; without the service-principal trio it falls through to " +
+                       "an interactive login that cannot complete on a runner and hangs the build.")
+            }
+        }
+    }
+    elseif ($PfxBase64) {
+        $signMode = 'pfx'
+        Write-Host "signing with supplied code-signing cert (MSIX_CERT_PFX_B64)"
+        [IO.File]::WriteAllBytes($pfxPath, [Convert]::FromBase64String($PfxBase64))
+    }
+    elseif ($requireCert) {
+        throw ("release build ($env:GITHUB_REF) with neither AZURE_CODESIGNING_* nor MSIX_CERT_PFX_B64 - " +
+               "refusing to fall back to an ephemeral self-signed cert. Restore the signing secrets " +
+               "(packaging/windows/README.md), or pass -RequireSignedCert false if this really is a test build.")
+    }
+    else {
+        $signMode = 'selfsigned'
+        Write-Host "no MSIX_CERT_PFX_B64 -> generating an ephemeral self-signed cert (subject $Publisher)"
+        if (-not $PfxPassword) { $PfxPassword = 'punktfunk' }
+        $tmp = New-SelfSignedCertificate -Type Custom -Subject $Publisher `
+            -KeyUsage DigitalSignature -FriendlyName 'punktfunk client installer (self-signed)' `
+            -CertStoreLocation 'Cert:\CurrentUser\My' `
+            -TextExtension @('2.5.29.37={text}1.3.6.1.5.5.7.3.3', '2.5.29.19={text}')
+        $sec = ConvertTo-SecureString -String $PfxPassword -Force -AsPlainText
+        Export-PfxCertificate -Cert "Cert:\CurrentUser\My\$($tmp.Thumbprint)" -FilePath $pfxPath -Password $sec | Out-Null
+        Remove-Item "Cert:\CurrentUser\My\$($tmp.Thumbprint)" -Force
+    }
+}
+
+# Timestamp policy matches the sibling scripts: best-effort for a long-lived .pfx, MANDATORY under
+# Azure signing (those leaf certs expire in ~3 days; untimestamped signatures die with them).
+function Sign-File([string]$Path) {
+    if ($NoSign) { return }
+    if ($signMode -eq 'azure') {
+        $signArgs = @('sign', '/fd', 'SHA256', '/dlib', $AzureDlib, '/dmdf', $azureMetadata)
+        $ts = 'http://timestamp.acs.microsoft.com'
+    }
+    else {
+        $signArgs = @('sign', '/fd', 'SHA256', '/f', $pfxPath)
+        if ($PfxPassword) { $signArgs += @('/p', $PfxPassword) }
+        $ts = 'http://timestamp.digicert.com'
+    }
+    & $signtool ($signArgs + @('/tr', $ts, '/td', 'SHA256', $Path))
+    if ($LASTEXITCODE -eq 0) { return }
+    if ($signMode -eq 'azure') {
+        throw ("timestamped sign failed for $Path ($LASTEXITCODE) - NOT retrying without a timestamp. " +
+               "An Azure signing cert is valid for ~3 days; an untimestamped signature would go " +
+               "untrusted within days of release.")
+    }
+    Write-Warning "timestamped sign failed for $Path - retrying without a timestamp"
+    & $signtool ($signArgs + @($Path))
+    if ($LASTEXITCODE -ne 0) { throw "signtool sign failed for $Path ($LASTEXITCODE)" }
+}
+
+# --- sign the inner exes, zip the stage (portable build), then build + sign the installer ------
+foreach ($f in $required | Where-Object { $_ -like '*.exe' }) {
+    Sign-File (Join-Path $stage $f)
+}
+
+$zip = Join-Path $OutDir "punktfunk-client-windows_${Version}_${Arch}-portable.zip"
+if (Test-Path $zip) { Remove-Item $zip -Force }
+Compress-Archive -Path (Join-Path $stage '*') -DestinationPath $zip
+Write-Host "==> portable zip: $zip"
+
+# Stage the .iss + branding next to each other under $OutDir: ISCC is a 32-bit process, and on the
+# SYSTEM-profile runner WOW64 redirection breaks reads from the checkout path (see
+# pack-host-installer.ps1's staging note) — everything ISCC touches must live under C:\t.
+$issLocal = Join-Path $OutDir 'punktfunk-client.iss'
+Copy-Item -LiteralPath $iss -Destination $issLocal -Force
+$brandSrc = (Resolve-Path (Join-Path $here '..\..\..\packaging\windows\branding')).Path
+$brandStage = Join-Path $OutDir 'branding'
+if (Test-Path $brandStage) { Remove-Item $brandStage -Recurse -Force }
+New-Item -ItemType Directory -Force -Path $brandStage | Out-Null
+Copy-Item (Join-Path $brandSrc '*.bmp') $brandStage -Force
+Copy-Item (Join-Path $brandSrc 'punktfunk.ico') $brandStage -Force
+
+$defines = @(
+    "/DMyAppVersion=$Version",
+    "/DArch=$Arch",
+    "/DLayoutDir=$stage",
+    "/DBrandingDir=$brandStage",
+    "/DOutputDir=$OutDir"
+)
+Write-Host "==> ISCC $($defines -join ' ') $issLocal"
+& $iscc @defines $issLocal
+if ($LASTEXITCODE -ne 0) { throw "ISCC failed ($LASTEXITCODE)" }
+
+$setup = Join-Path $OutDir "punktfunk-client-setup-${Version}_${Arch}.exe"
+if (-not (Test-Path $setup)) { throw "expected installer not produced: $setup" }
+Sign-File $setup
+Remove-Item $pfxPath -Force -ErrorAction SilentlyContinue
+Remove-Item $azureMetadata -Force -ErrorAction SilentlyContinue
+
+Write-Host ""
+Write-Host "==> installer: $setup"
+if ($signMode -eq 'azure') {
+    Write-Host "==> signed by a publicly trusted CA."
+}
+elseif ($signMode -ne 'none') {
+    Write-Host "==> $signMode-signed: the exe still runs everywhere; expect a SmartScreen prompt on canary builds."
+}
+if ($env:GITHUB_ENV) {
+    "CLIENT_SETUP_PATH=$setup" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+    "CLIENT_ZIP_PATH=$zip" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+}
@@ -0,0 +1,244 @@
+; punktfunk Windows CLIENT installer (Inno Setup 6) — the default download.
+;
+; A classic per-user setup.exe, NOT because MSIX failed technically (the app is full-trust Win32
+; either way) but because the MSIX install SHAPE breaks the most-reported use case: the exe lands
+; under the ACL'd C:\Program Files\WindowsApps, which Steam's "Add a Non-Steam Game" picker cannot
+; browse and whose activation path defeats the overlay's GameOverlayRenderer64.dll injection —
+; Steam has to spawn the process itself from a normal path for the overlay (and a Big Picture
+; launch) to work. This installs to {userpf}\Punktfunk: user-writable-visible, no UAC, and a
+; stable path Steam can target. The MSIX is kept for Microsoft Store compatibility
+; (clients/windows/packaging/pack-msix.ps1 — both are packed from the same layout every build).
+;
+; Built by pack-client-installer.ps1, e.g.:
+;   ISCC.exe /DMyAppVersion=0.2.137.0 /DArch=x64 /DLayoutDir=C:\t\installer\portable \
+;            /DBrandingDir=C:\t\installer\branding /DOutputDir=C:\t\installer punktfunk-client.iss
+;
+; What the MSIX manifest granted declaratively is re-created here per-user (all HKCU, so no
+; elevation and uninstall leaves nothing behind):
+;   punktfunk:// protocol        -> HKCU\Software\Classes\punktfunk (deeplink.rs positional parse)
+;   Start entries                -> {userprograms} shortcuts (Punktfunk + Punktfunk Console)
+;   punktfunk.exe CLI alias      -> {app} appended to the HKCU PATH (Playnite importer shells to it)
+;   punktfunk-client.exe alias   -> unnecessary: deeplink.rs targets current_exe() when unpackaged
+;   Microsoft.WindowsAppRuntime.2 PackageDependency
+;                                -> download + run the runtime installer when missing ([Code])
+
+#ifndef MyAppVersion
+  #define MyAppVersion "0.0.0.0"
+#endif
+#ifndef Arch
+  #define Arch "x64"
+#endif
+#ifndef LayoutDir
+  #define LayoutDir "."
+#endif
+#ifndef BrandingDir
+  #define BrandingDir "..\..\..\packaging\windows\branding"
+#endif
+#ifndef OutputDir
+  #define OutputDir "."
+#endif
+; The unpackaged app resolves an INSTALLED Windows App SDK runtime via the bootstrap DLL
+; (windows-reactor pins WINDOWSAPPSDK_RELEASE_MAJORMINOR = 0x20000; the MSIX manifest's
+; PackageDependency floor is 2.2 — keep the two in sync with packaging/AppxManifest.xml).
+#define AppRuntimeUrl "https://aka.ms/windowsappsdk/2.2/latest/windowsappruntimeinstall-" + Arch + ".exe"
+
+[Setup]
+AppId={{52464E61-68A1-4621-B6B3-5B8BBB823D1A}
+AppName=Punktfunk
+AppVersion={#MyAppVersion}
+AppPublisher=unom
+AppPublisherURL=https://git.unom.io/unom/punktfunk
+; Per-user, no UAC: {userpf} = %LOCALAPPDATA%\Programs. A browsable, stable path is the point —
+; see the header (Steam overlay / Big Picture).
+DefaultDirName={userpf}\Punktfunk
+PrivilegesRequired=lowest
+DisableProgramGroupPage=yes
+UsePreviousAppDir=yes
+; Same floor as the MSIX manifest's TargetDeviceFamily MinVersion (10.0.17763).
+MinVersion=10.0.17763
+#if Arch == "arm64"
+ArchitecturesAllowed=arm64
+ArchitecturesInstallIn64BitMode=arm64
+#else
+ArchitecturesAllowed=x64
+ArchitecturesInstallIn64BitMode=x64
+#endif
+OutputDir={#OutputDir}
+OutputBaseFilename=punktfunk-client-setup-{#MyAppVersion}_{#Arch}
+Compression=lzma2/max
+SolidCompression=yes
+; Modern branded wizard, same version gate as the host installer (punktfunk-host.iss).
+#if VER >= EncodeVer(6,6,0)
+WizardStyle=modern dynamic windows11
+#else
+WizardStyle=modern
+#endif
+SetupIconFile={#BrandingDir}\punktfunk.ico
+WizardImageFile={#BrandingDir}\wizard-image-*.bmp
+WizardSmallImageFile={#BrandingDir}\wizard-small-*.bmp
+UninstallDisplayName=Punktfunk {#MyAppVersion}
+UninstallDisplayIcon={app}\punktfunk-client.exe
+; {app} goes on the USER PATH (see [Registry] + PathNeedsAdd/RemoveAppFromPath below) so the
+; documented `punktfunk hosts list` / `punktfunk launch` one-liners work by name — same contract
+; the MSIX's punktfunk.exe app-execution alias provided. Broadcasts WM_SETTINGCHANGE.
+ChangesEnvironment=yes
+
+[Languages]
+Name: "english"; MessagesFile: "compiler:Default.isl"
+
+[Tasks]
+Name: "desktopicon"; Description: "Create a Desktop shortcut"; Flags: unchecked
+
+[Files]
+; The staged MSIX layout, minus the package-only bits (AppxManifest.xml, the tile Assets — the
+; exes embed their own icons via build.rs winresource). pack-client-installer.ps1 signs the four
+; exes individually before ISCC runs; the .msix signs only its container, so this cannot be
+; skipped by "the MSIX build already signed them".
+Source: "{#LayoutDir}\punktfunk-client.exe"; DestDir: "{app}"; Flags: ignoreversion
+Source: "{#LayoutDir}\punktfunk-session.exe"; DestDir: "{app}"; Flags: ignoreversion
+Source: "{#LayoutDir}\punktfunk-console.exe"; DestDir: "{app}"; Flags: ignoreversion
+Source: "{#LayoutDir}\punktfunk.exe"; DestDir: "{app}"; Flags: ignoreversion
+Source: "{#LayoutDir}\Microsoft.WindowsAppRuntime.Bootstrap.dll"; DestDir: "{app}"; Flags: ignoreversion
+Source: "{#LayoutDir}\SDL3.dll"; DestDir: "{app}"; Flags: ignoreversion
+Source: "{#LayoutDir}\resources.pri"; DestDir: "{app}"; Flags: ignoreversion
+; MIT/Apache + the client-scoped THIRD-PARTY-NOTICES — same payload the MSIX carries.
+Source: "{#LayoutDir}\licenses\*"; DestDir: "{app}\licenses"; Flags: ignoreversion
+
+[Icons]
+; Flat Start-menu entries, mirroring the MSIX's two Application tiles.
+Name: "{userprograms}\Punktfunk"; Filename: "{app}\punktfunk-client.exe"
+Name: "{userprograms}\Punktfunk Console"; Filename: "{app}\punktfunk-console.exe"; \
+  Comment: "Controller-driven couch interface for TVs and HTPCs"
+Name: "{userdesktop}\Punktfunk"; Filename: "{app}\punktfunk-client.exe"; Tasks: desktopicon
+
+[Registry]
+; The punktfunk:// scheme (design/client-deep-links.md §4.2) — the registry twin of the MSIX
+; manifest's windows.protocol extension. Protocol activation delivers the URI as "%1" on the
+; command line, so this lands in the same positional URL parse in main() that the packaged
+; activation does. HKCU + uninsdeletekey: nothing survives uninstall.
+Root: HKCU; Subkey: "Software\Classes\punktfunk"; ValueType: string; \
+  ValueData: "URL:Punktfunk stream link"; Flags: uninsdeletekey
+Root: HKCU; Subkey: "Software\Classes\punktfunk"; ValueType: string; ValueName: "URL Protocol"; ValueData: ""
+Root: HKCU; Subkey: "Software\Classes\punktfunk\DefaultIcon"; ValueType: string; \
+  ValueData: "{app}\punktfunk-client.exe,0"
+Root: HKCU; Subkey: "Software\Classes\punktfunk\shell\open\command"; ValueType: string; \
+  ValueData: """{app}\punktfunk-client.exe"" ""%1"""
+; Put {app} on the USER PATH so `punktfunk` (the headless CLI) is runnable by name. Appended to
+; {olddata} and guarded by PathNeedsAdd so a repair/upgrade never appends a duplicate. NOT
+; uninsdeletevalue — that would delete the whole Path value; the uninstaller surgically removes
+; just our entry (RemoveAppFromPath). expandsz preserves %VAR%-style entries other software put here.
+Root: HKCU; Subkey: "Environment"; ValueType: expandsz; ValueName: "Path"; \
+  ValueData: "{olddata};{app}"; Check: PathNeedsAdd(ExpandConstant('{app}'))
+
+[Code]
+const
+  EnvKey = 'Environment';   { the HKCU per-user environment key }
+
+{ Is the install dir missing from the user PATH? Guards the [Registry] append so a repair or
+  upgrade can't add a second copy. Semicolon-delimited, case-insensitive — a path that merely
+  CONTAINS ours as a substring doesn't count as a match. (Same helper as punktfunk-host.iss,
+  retargeted from the HKLM machine key to HKCU.) }
+function PathNeedsAdd(Param: String): Boolean;
+var
+  OrigPath: String;
+begin
+  if not RegQueryStringValue(HKEY_CURRENT_USER, EnvKey, 'Path', OrigPath) then
+  begin
+    Result := True;   { no Path value at all - the append creates it }
+    exit;
+  end;
+  Result := Pos(';' + Uppercase(Param) + ';', ';' + Uppercase(OrigPath) + ';') = 0;
+end;
+
+{ Remove exactly our install-dir entry from the user PATH on uninstall, leaving every other entry
+  (and their order) intact. Entry-by-entry rebuild, never a substring delete. }
+procedure RemoveAppFromPath;
+var
+  OrigPath, NewPath, Entry: String;
+  Target: String;
+  P: Integer;
+begin
+  if not RegQueryStringValue(HKEY_CURRENT_USER, EnvKey, 'Path', OrigPath) then
+    exit;
+  Target := Uppercase(ExpandConstant('{app}'));
+  NewPath := '';
+  OrigPath := OrigPath + ';';
+  repeat
+    P := Pos(';', OrigPath);
+    Entry := Trim(Copy(OrigPath, 1, P - 1));
+    OrigPath := Copy(OrigPath, P + 1, Length(OrigPath));
+    if (Entry <> '') and (Uppercase(Entry) <> Target) then
+    begin
+      if NewPath <> '' then NewPath := NewPath + ';';
+      NewPath := NewPath + Entry;
+    end;
+  until OrigPath = '';
+  RegWriteExpandStringValue(HKEY_CURRENT_USER, EnvKey, 'Path', NewPath);
+end;
+
+procedure CurUninstallStepChanged(CurUninstallStep: TUninstallStep);
+begin
+  if CurUninstallStep = usPostUninstall then
+    RemoveAppFromPath;
+end;
+
+{ The Windows App SDK runtime the bootstrap DLL resolves at launch (the unpackaged twin of the
+  MSIX's PackageDependency). Probe per-user via Get-AppxPackage; when missing, fetch Microsoft's
+  runtime installer and run it quietly — it registers Store-signed framework packages, which
+  needs no elevation. Every failure path is NON-FATAL and ends in the same message the docs
+  carry, because the app itself reports the missing runtime on first launch too. }
+function AppRuntimeMissing(): Boolean;
+var
+  ResultCode: Integer;
+begin
+  { exit 0 = found, 1 = missing; a powershell failure (rc <> 0/1) counts as missing - the
+    download below is idempotent and the runtime installer no-ops when it is present. }
+  if not Exec('powershell.exe',
+      '-NoProfile -ExecutionPolicy Bypass -Command "if (Get-AppxPackage -Name Microsoft.WindowsAppRuntime.2*) { exit 0 } else { exit 1 }"',
+      '', SW_HIDE, ewWaitUntilTerminated, ResultCode) then
+  begin
+    Result := True;
+    exit;
+  end;
+  Result := ResultCode <> 0;
+end;
+
+procedure EnsureAppRuntime;
+var
+  ResultCode: Integer;
+  Installer: String;
+begin
+  if not AppRuntimeMissing() then
+    exit;
+  Installer := 'windowsappruntimeinstall.exe';
+  try
+    DownloadTemporaryFile('{#AppRuntimeUrl}', Installer, '', nil);
+    if not Exec(ExpandConstant('{tmp}\' + Installer), '--quiet', '',
+        SW_HIDE, ewWaitUntilTerminated, ResultCode) or (ResultCode <> 0) then
+      RaiseException('runtime installer exit code ' + IntToStr(ResultCode));
+  except
+    SuppressibleMsgBox(
+      'The Windows App Runtime 2.x could not be installed automatically.' + #13#10 + #13#10 +
+      'Punktfunk needs it to start. Install it from ' + #13#10 +
+      'https://learn.microsoft.com/windows/apps/windows-app-sdk/downloads' + #13#10 +
+      'and then launch Punktfunk normally.',
+      mbInformation, MB_OK, IDOK);
+  end;
+end;
+
+procedure CurStepChanged(CurStep: TSetupStep);
+var
+  ResultCode: Integer;
+begin
+  { On upgrade a running shell/stream locks the exes; kill them best-effort so the copy succeeds.
+    taskkill matches the image NAME, so "punktfunk.exe" hits only the CLI, not the host service. }
+  if CurStep = ssInstall then
+    Exec(ExpandConstant('{sys}\taskkill.exe'),
+      '/F /IM punktfunk-client.exe /IM punktfunk-session.exe /IM punktfunk-console.exe /IM punktfunk.exe',
+      '', SW_HIDE, ewWaitUntilTerminated, ResultCode);
+  { ssPostInstall, NOT a wizard-page hook: silent installs (winget-style /VERYSILENT) show no
+    pages, and skipping the runtime there would ship an app that cannot start. This step runs on
+    every install mode, and SuppressibleMsgBox keeps the failure path unattended-safe. }
+  if CurStep = ssPostInstall then
+    EnsureAppRuntime;
+end;
@@ -203,14 +203,30 @@ pub(crate) fn queue(url: String) {
    INBOX.lock().unwrap().push(url);
 }

+/// Whether this process runs with MSIX package identity. Decides how a shortcut must target us
+/// (`write_shortcut` below) and whether the process may stamp its own AppUserModelID
+/// (`set_app_user_model_id` in main.rs).
+pub(crate) fn has_package_identity() -> bool {
+    use windows::Win32::appmodel::GetCurrentPackageFullName;
+    use windows::Win32::winerror::APPMODEL_ERROR_NO_PACKAGE;
+    // SAFETY: `GetCurrentPackageFullName` with `len = 0` and no buffer is the documented identity
+    // PROBE — it writes nothing and only reports whether this process is packaged.
+    unsafe {
+        let mut len: u32 = 0;
+        GetCurrentPackageFullName(&mut len, None) != APPMODEL_ERROR_NO_PACKAGE
+    }
+}
+
 /// Write a `.lnk` on the Desktop that launches this URL, and return its path.
 ///
-/// The shortcut targets the app execution alias with the URL as an ARGUMENT, rather than being
-/// a `.url` internet shortcut. Both would work while the scheme is registered; only this one
-/// still works if it isn't, because it invokes the client directly — which is the whole point
-/// of a shortcut being a container for a URL rather than a second launch mechanism
-/// (design/client-deep-links.md §5). Targeting the alias (not the package path) is what keeps
-/// it valid across updates, since the install path changes and the alias doesn't.
+/// The shortcut targets the client exe with the URL as an ARGUMENT, rather than being a `.url`
+/// internet shortcut. Both would work while the scheme is registered; only this one still works
+/// if it isn't, because it invokes the client directly — which is the whole point of a shortcut
+/// being a container for a URL rather than a second launch mechanism
+/// (design/client-deep-links.md §5). Which exe reference is durable depends on how we were
+/// installed: under MSIX the install path changes on every update but the app execution alias
+/// doesn't, so packaged runs target the alias; the Inno Setup / portable installs have no alias
+/// but a stable install dir, so unpackaged runs target the absolute exe path.
 pub(crate) fn write_shortcut(label: &str, url: &str) -> Result<std::path::PathBuf, String> {
    use windows::core::{Interface, HSTRING};
    use windows::Win32::combaseapi::{CoCreateInstance, CoInitializeEx};
@@ -223,6 +239,15 @@ pub(crate) fn write_shortcut(label: &str, url: &str) -> Result<std::path::PathBu
        .map(|p| std::path::PathBuf::from(p).join("Desktop"))
        .map_err(|_| "USERPROFILE isn't set".to_string())?;
    let path = desktop.join(format!("{}.lnk", file_name(label)));
+    // Alias when packaged, absolute path when not — see the doc comment above.
+    let target = if has_package_identity() {
+        "punktfunk-client.exe".to_string()
+    } else {
+        std::env::current_exe()
+            .map_err(|e| format!("current exe: {e}"))?
+            .to_string_lossy()
+            .into_owned()
+    };
    // SAFETY: COM calls on this thread's apartment. `CoCreateInstance` returns an owned interface
    // checked by `?`, and every setter below takes a borrowed `HSTRING`/`PCWSTR` that outlives its
    // synchronous call; nothing here dereferences a pointer the caller supplied.
@@ -233,7 +258,7 @@ pub(crate) fn write_shortcut(label: &str, url: &str) -> Result<std::path::PathBu
        let _ = CoInitializeEx(None, COINIT_APARTMENTTHREADED as u32);
        let link: IShellLinkW = CoCreateInstance(&ShellLink, None, CLSCTX_INPROC_SERVER)
            .map_err(|e| format!("shell link: {e}"))?;
-        link.SetPath(&HSTRING::from("punktfunk-client.exe"))
+        link.SetPath(&HSTRING::from(target.as_str()))
            .ok()
            .map_err(|e| format!("shortcut target: {e}"))?;
        link.SetArguments(&HSTRING::from(url))
@@ -173,18 +173,12 @@ fn main() {
 /// processes are left alone. Must run before any window exists.
 #[cfg(windows)]
 fn set_app_user_model_id() {
-    use windows::Win32::appmodel::GetCurrentPackageFullName;
    use windows::Win32::shobjidl_core::SetCurrentProcessExplicitAppUserModelID;
-    use windows::Win32::winerror::APPMODEL_ERROR_NO_PACKAGE;
-    // SAFETY: `GetCurrentPackageFullName` is called with `len = 0` and no buffer, which is the
-    // documented identity PROBE — it writes nothing and only reports whether this process is
-    // packaged; `SetCurrentProcessExplicitAppUserModelID` takes a static wide literal.
+    if deeplink::has_package_identity() {
+        return; // packaged (or indeterminate) — leave the identity alone
+    }
+    // SAFETY: `SetCurrentProcessExplicitAppUserModelID` takes a static wide literal.
    unsafe {
-        let mut len: u32 = 0;
-        // No buffer: just probe whether the process has package identity.
-        if GetCurrentPackageFullName(&mut len, None) != APPMODEL_ERROR_NO_PACKAGE {
-            return; // packaged (or indeterminate) — leave the identity alone
-        }
        // Must stay in sync with pf-presenter's win32.rs, or the windows stop grouping.
        let _ = SetCurrentProcessExplicitAppUserModelID(windows::core::w!("unom.punktfunk.client"));
    }
@@ -66,6 +66,16 @@ use zkde::zkde_screencast_unstable_v1::ZkdeScreencastUnstableV1 as Screencast;
 const POINTER_METADATA: u32 = 4;
 const POINTER_EMBEDDED: u32 = 2;

+/// Marks the one KWin refusal a retry can clear: the disabled-output repair ran and changed the
+/// box between attempts ([`kwin_output_mgmt::enable_disabled_output`]).
+///
+/// It is load-bearing in TWO places and both are easy to break. The opener keys on it to skip the
+/// `KWin virtual output failed` wrapper below — and that wrapper's prefix is exactly what the
+/// host's `is_permanent_build_error` matches to short-circuit the retry loop, so a repaired
+/// refusal carrying it would be classified permanent and the retry that consumes the repair would
+/// never run. It is also the human-readable half of the message; keep it a phrase, not a code.
+const REPAIRED_HINT: &str = "enabled it over output management";
+
 /// The name we give the created output; KWin exposes it to output-management as `Virtual-<name>`.
 const VOUT_NAME: &str = "punktfunk";

@@ -268,6 +278,10 @@ impl VirtualDisplay for KwinDisplay {
                .context("spawn KWin virtual-output thread")?;
            match setup_rx.recv_timeout(OPENER_BUDGET) {
                Ok(Ok(v)) => Ok((v, stop)),
+                // Repaired: report it as-is. The wrapper below would prepend the phrase the host
+                // reads as "permanent, do not retry", and this is the one refusal whose retry is
+                // the entire point — the repair only fixes the NEXT request.
+                Ok(Err(e)) if e.contains(REPAIRED_HINT) => bail!("{e}"),
                // KWin's reason is TRANSLATED into the session's language, so it is often
                // unsearchable for the person reading the log. Say what it means once, here.
                Ok(Err(e)) => bail!(
@@ -1793,14 +1807,41 @@ fn run(
    );

    // Pump events until KWin reports the node id (or an error, or the budget).
-    let node_id = await_created(
+    //
+    // A refusal here is where the KWin >= 6.6 disabled-output trap lands, and it is repairable
+    // FROM INSIDE THIS SCOPE and nowhere else: KWin destroys the output when our stream is
+    // destroyed, so the connection has to stay up while we enable it (see
+    // [`kwin_output_mgmt::enable_disabled_output`] for why the output is still alive at all, and
+    // why enabling it fixes the NEXT request rather than this one).
+    let node_id = match await_created(
        &conn,
        &mut queue,
        &mut state,
        stop,
        "stream_virtual_output",
        started,
-    )?;
+    ) {
+        Ok(id) => id,
+        Err(e) => {
+            // `Virtual-<name>` is the address KWin exposes our output under (the same prefix the
+            // topology path resolves against).
+            match crate::kwin_output_mgmt::enable_disabled_output(&format!("Virtual-{name}")) {
+                // Deliberately does NOT carry the "KWin virtual output failed" prefix: that string
+                // is what marks a KWin refusal PERMANENT for the session's retry loop, and this is
+                // the one refusal where something DID change between attempts. Retrying is the
+                // whole point of repairing.
+                Some(repaired) => bail!(
+                    "KWin created the virtual output disabled and refused to stream it ({e}); \
+                     {REPAIRED_HINT} (head {repaired}) — the retry picks up the configuration \
+                     KWin just persisted"
+                ),
+                // Nothing to repair (no such head, already enabled, or the apply was refused):
+                // the refusal stands, and its own prefix keeps it permanent so the session fails
+                // fast instead of burning the retry budget on an unchanged box.
+                None => return Err(e),
+            }
+        }
+    };
    setup_tx
        .send(Ok(node_id))
        .map_err(|_| anyhow!("virtual-output opener went away"))?;
@@ -1274,6 +1274,76 @@ pub(crate) fn reenable_outputs(outputs: &[(String, String)]) -> bool {
    complete
 }

+/// Enable a virtual output KWin created but left DISABLED, addressed by the `Virtual-<name>`
+/// prefix it exposes ours under. Returns the head's name when one matched, was disabled, and the
+/// enable applied.
+///
+/// This is the repair for the KWin ≥ 6.6 refusal (`"Could not find output"`, translated into the
+/// session's language). `streamVirtualOutput` there creates the output on the backend and then
+/// hands `workspace()->findOutput(output)` to the stream — and that returns null for an output the
+/// workspace does not manage, which `wantsToManage` defines as `isEnabled() && !isNonDesktop()`.
+/// KWin 6.4/6.5 passed the backend output straight through, so a disabled one streamed anyway;
+/// from 6.6 it is a hard refusal, and one that repeats forever: the host asks for a STABLE
+/// per-client name so KWin persists that client's scale and mode, and a stored setup naming it
+/// `enabled: false` is therefore reapplied to every future session.
+///
+/// Two properties of KWin make the repair possible, both verified against Plasma/6.7:
+///
+/// * `sendFailed` only sends the event — it does not emit `finished`, and `removeVirtualOutput` is
+///   wired to `finished`. So the disabled output stays alive for exactly as long as the caller
+///   holds its (failed) stream open, which is the window this runs in.
+/// * `WaylandServer::handleOutputAdded` offers EVERY backend output to the output-device registry,
+///   gating only placeholders and non-desktop ones. A disabled output has no `wl_output` — that
+///   side is gated on the workspace — but it is addressable over `kde_output_management_v2`.
+///
+/// Enabling it through output management is a user-applied configuration, so KWin persists it
+/// against that output's identity: the caller's next `stream_virtual_output` under the same name
+/// finds a stored setup that enables it. Which is why the caller must RETRY after this returns
+/// `Some` — the request that failed cannot be salvaged, only the one after it.
+pub(crate) fn enable_disabled_output(prefix: &str) -> Option<String> {
+    let mut sess = Session::open("enable_disabled").ok()?;
+    let deadline = Instant::now() + OP_BUDGET;
+    // Newest-wins, exactly as the supersede resolve elsewhere in this file: a reconnect can leave
+    // a predecessor of the same name briefly announced, and enabling THAT one repairs an output
+    // that is already going away.
+    let dev = sess
+        .state
+        .devices
+        .values()
+        .filter(|d| d.name.as_deref().is_some_and(|n| n.starts_with(prefix)) && d.proxy.is_some())
+        .max_by_key(|d| (d.global, d.seq))
+        .cloned()?;
+    let name = dev.name.clone()?;
+    if dev.enabled {
+        // Not the shape we repair. Say so rather than applying a no-op config that would `applied`
+        // successfully and read as a fix — the caller decides whether to retry on this.
+        tracing::debug!(
+            %name,
+            "KWin output management: our virtual output is already enabled — nothing to repair"
+        );
+        return None;
+    }
+    let proxy = dev.proxy.as_ref()?;
+    let config = sess.new_config();
+    config.enable(proxy, 1);
+    let ok = sess.apply(&config, deadline);
+    config.destroy();
+    if !ok {
+        tracing::warn!(
+            %name,
+            reason = ?sess.state.failure_reason,
+            "KWin output management: could not enable the virtual output KWin created disabled"
+        );
+        return None;
+    }
+    tracing::info!(
+        %name,
+        "KWin output management: KWin created our virtual output DISABLED and refused to stream \
+         it; enabled it — KWin persists that, so the retry's request comes back enabled"
+    );
+    Some(name)
+}
+
 /// Position the output identified by `uuid` at `(x, y)` in the desktop layout, in-process. Returns
 /// `true` if applied; `false` tells the caller to fall back to `kscreen-doctor`.
 pub(crate) fn set_position(uuid: &str, x: i32, y: i32) -> bool {
@@ -5345,6 +5345,17 @@ mod tests {
            "spawn gamescope (is it installed? `apt install gamescope`)"
        ));
        assert!(is_permanent_build_error("virtual displays require Linux"));
+        // The ONE KWin refusal that must stay retryable: pf-vdisplay repaired the box (it enabled
+        // the output KWin created disabled, which KWin persists), so the next attempt is not the
+        // same attempt. That path deliberately reports WITHOUT the `KWin virtual output failed`
+        // prefix above — if it ever regains it, the retry that consumes the repair stops running
+        // and the repair is dead code.
+        assert!(!is_permanent_build_error(
+            "create virtual output: KWin created the virtual output disabled and refused to \
+             stream it (stream_virtual_output failed: Não foi possível encontrar saída); enabled \
+             it over output management (head Virtual-punktfunk-a1b2) — the retry picks up the \
+             configuration KWin just persisted"
+        ));
        // Transient: negotiation/timeout races — exactly what backoff is for.
        assert!(!is_permanent_build_error(
            "first frame: no PipeWire frame within 10s (node 42): format negotiation never completed"
@@ -47,6 +47,20 @@
    "web": "punktfunk-web"
  },

+  "installer": {
+    "$comment": "The guided Linux installer (WP4, preview). Canonical URL is the website's /install.sh, a redirect to the raw script on main so it's versioned with the code it installs; the docs hub and the download page quote these lines.",
+    "status": "preview",
+    "url": "https://punktfunk.unom.io/install.sh",
+    "source": "https://git.unom.io/unom/punktfunk/raw/branch/main/scripts/install.sh",
+    "oneLiner": "curl -fsSL https://punktfunk.unom.io/install.sh | sh",
+    "inspectFirst": [
+      "curl -fsSLO https://punktfunk.unom.io/install.sh",
+      "less install.sh",
+      "sh install.sh"
+    ],
+    "docs": "/docs/install#guided-install-preview"
+  },
+
  "conflicts": {
    "hosts": ["Sunshine", "Apollo", "Vibeshine"],
    "detect": "punktfunk-host detect-conflicts",
@@ -171,11 +185,11 @@
      "id": "windows-client",
      "name": "Windows client",
      "installs": "client",
-      "packageManager": "msix",
+      "packageManager": "installer",
      "docs": "/docs/install-client#windows",
      "install": [
-        "curl.exe -LO https://git.unom.io/api/packages/unom/generic/punktfunk-client-windows/latest/punktfunk-client-windows_x64.msix",
-        "Add-AppxPackage .\\punktfunk-client-windows_x64.msix"
+        "curl.exe -LO https://git.unom.io/api/packages/unom/generic/punktfunk-client-windows/latest/punktfunk-client-setup_x64.exe",
+        ".\\punktfunk-client-setup_x64.exe"
      ]
    },
    {
@@ -32,7 +32,8 @@ track per machine; switching is a one-line change.
 | **pacman** (Arch host/client) | `[punktfunk-canary]` repo section | `[punktfunk]` (`Server = …/api/packages/unom/arch/$repo/$arch`) |
 | **Flatpak** (client) | `flatpak install --user https://flatpak.unom.io/io.unom.Punktfunk.Canary.flatpakref` | `…/io.unom.Punktfunk.flatpakref` |
 | **Decky** (Steam Deck) | install-from-URL `…/generic/punktfunk-decky/canary/punktfunk.zip` | `…/punktfunk-decky/latest/punktfunk.zip` |
-| **Windows client** (MSIX) | `…/generic/punktfunk-client-windows/canary/punktfunk-client-windows_x64.msix` | `…/latest/…` + the release page |
+| **Windows client** (installer) | `…/generic/punktfunk-client-windows/canary/punktfunk-client-setup_x64.exe` | `…/latest/…` + the release page |
+| **Windows client** (MSIX / portable zip) | `…/generic/punktfunk-client-windows/canary/punktfunk-client-windows_x64.msix` (or `…_x64-portable.zip`) | `…/latest/…` + the release page |
 | **Windows host** (installer) | `…/generic/punktfunk-host-windows/canary/punktfunk-host-setup.exe` | `…/latest/…` + the release page |
 | **Windows host** (winget) | — *(stable only)* | `winget install unom.PunktfunkHost` / `winget upgrade unom.PunktfunkHost`, after `winget source add -n punktfunk https://winget.punktfunk.unom.io -t Microsoft.Rest` |
 | **Android** | Play **Internal testing** (invite-only) + sideload `…/generic/punktfunk-android/canary/punktfunk-android.apk` | **[Google Play](https://play.google.com/store/apps/details?id=io.unom.punktfunk)** (production) + the release page |
@@ -113,7 +113,7 @@ per-vendor: **Vulkan Video, then D3D11VA, then software** on NVIDIA and AMD, and
 on Intel and other GPUs (Intel's driver advertises Vulkan Video, but DXVA is the proven path there).
 It has [10-bit/HDR present](/docs/hdr#per-client), WASAPI audio + mic, SDL3 controllers (rumble,
 lightbar, DualSense), network discovery, the host's **game library** with cover art, and the full
-PIN-pairing trust surface. It builds for `x86_64` and `aarch64` and ships as a **signed MSIX**.
+PIN-pairing trust surface. It builds for `x86_64` and `aarch64` and ships as a **signed installer** (plus a portable zip, and an MSIX for Microsoft Store compatibility).

 The package installs **two** Start-menu entries — **Punktfunk**, the desktop window, and
 **Punktfunk Console**, a controller-driven fullscreen interface for a TV or HTPC (host list, pairing,
@@ -148,7 +148,7 @@ It ships as a sideloadable `.ipk` (homebrew package) rather than through the LG
 ## Scripting: the `punktfunk` CLI

 `punktfunk` is the headless client — the same core the graphical apps use, with no window. It ships
-in **every Linux client package** (apt, dnf, pacman and the Flatpak) and in the **Windows MSIX**, so
+in **every Linux client package** (apt, dnf, pacman and the Flatpak) and in the **Windows installer**, so
 if you have a desktop client you already have it:

 ```sh
@@ -213,7 +213,7 @@ has no pasteboard to share. See [Shared clipboard](/docs/clipboard).
 | A Linux desktop or laptop | **[`punktfunk-client`](#linux-desktop-client-gtk4)** (GTK4) |
 | A **Steam Deck** | The **[Decky plugin](/docs/steam-deck)** in Gaming Mode, or the [GTK4 client](#linux-desktop-client-gtk4) in Desktop Mode |
 | An Android phone or TV | The **[Android app](#android-app-phone--android-tv)** |
-| Windows | The native **[`punktfunk-client`](#windows-desktop-client)** (signed MSIX) or **[Moonlight](/docs/moonlight)** |
+| Windows | The native **[`punktfunk-client`](#windows-desktop-client)** (signed installer) or **[Moonlight](/docs/moonlight)** |
 | An **LG webOS TV** | The community **[`pf-webos`](https://github.com/dyptan-io/pf-webos)** client, or **[Moonlight](/docs/moonlight)** |
 | A browser, another smart TV, or any other device | **[Moonlight](/docs/moonlight)** |
 | Scripts, plugins, home automation | The headless **[`punktfunk`](#scripting-the-punktfunk-cli)** CLI |
@@ -22,7 +22,7 @@ Already installed? Skip to [Keeping a client up to date](#keeping-a-client-up-to
 |--------|---------|
 | **Linux** desktop / laptop | [Flatpak](#linux-desktop-flatpak) (any distro) or native apt/rpm/Arch packages |
 | **Steam Deck** | [Decky plugin](/docs/steam-deck) for Gaming Mode, or [Flatpak in Desktop Mode](#steam-deck) |
-| **Windows** | [Signed MSIX](#windows) from the package registry |
+| **Windows** | [Signed installer](#windows) from the package registry (portable zip and MSIX too) |
 | **macOS** | [Notarized `.dmg`](#macos) from the releases page |
 | **iPhone / iPad / Apple TV** | [TestFlight beta](#ios-ipados-apple-tv) |
 | **Android / Android TV** | [Google Play](#android), or sideload the APK |
@@ -100,38 +100,51 @@ See [packaging/flatpak](https://git.unom.io/unom/punktfunk/src/branch/main/packa

 ## Windows

-The Windows client ships as a **signed MSIX** in the package registry, signed with a publicly
-trusted certificate — nothing to import or trust by hand.
+The Windows client ships as a **signed installer** in the package registry, signed with a publicly
+trusted certificate — nothing to import or trust by hand. It installs per-user (no admin prompt) to
+`%LOCALAPPDATA%\Programs\Punktfunk`.

-1. Download the package. Each channel keeps one fixed URL, so this line always fetches the current
-   build — in PowerShell:
+1. Download the installer. Each channel keeps one fixed URL, so this line always fetches the
+   current build — in PowerShell:

   ```powershell
-   curl.exe -LO https://git.unom.io/api/packages/unom/generic/punktfunk-client-windows/latest/punktfunk-client-windows_x64.msix
+   curl.exe -LO https://git.unom.io/api/packages/unom/generic/punktfunk-client-windows/latest/punktfunk-client-setup_x64.exe
   ```

   Swap `_x64` for `_arm64` on an Arm device, and `latest` for `canary` to track `main`. The same
   file is attached to every [release](https://git.unom.io/unom/punktfunk/releases), and every
   build is kept under its own version on the
   [packages page](https://git.unom.io/unom/-/packages) (generic group, `punktfunk-client-windows`).
-2. Install it:
-
-   ```powershell
-   # use the _arm64 file instead on an Arm device
-   Add-AppxPackage .\punktfunk-client-windows_x64.msix
-   ```
-
-   If Windows reports a missing dependency, install the
+2. Run it. The installer registers `punktfunk://` links, puts the headless `punktfunk` command on
+   your PATH, and fetches the
   [Windows App Runtime 2.x](https://learn.microsoft.com/windows/apps/windows-app-sdk/downloads)
-   (the MSIX depends on `Microsoft.WindowsAppRuntime.2`), then re-run `Add-AppxPackage`.
+   automatically if this PC doesn't have it yet.
+3. Launch **Punktfunk** from the Start menu and pick your host. A second entry, **Punktfunk
+   Console**, is the same client as a controller-driven fullscreen interface for a TV or HTPC.

-   Install from a signed-in desktop session. Over a remote, non-interactive session (SSH, an RMM
-   tool) `Add-AppxPackage` can fail with `0x80070005` when the Windows App Runtime is in use and
-   Windows can't restart the apps holding it.
+### Launching through Steam (overlay, Big Picture)

-3. Launch **Punktfunk** from the Start menu and pick your host. The package also adds a second
-   entry, **Punktfunk Console** — the same client as a controller-driven fullscreen interface for a
-   TV or HTPC — and the headless `punktfunk` command on your PATH.
+Because the client is a normal exe at a stable path, you can hand it to Steam: **Add a Non-Steam
+Game** → browse to `%LOCALAPPDATA%\Programs\Punktfunk\punktfunk-client.exe` (or
+`punktfunk-console.exe` for the couch interface). Launched that way, the **Steam overlay** and
+controller configs work in the stream, and it's launchable from **Big Picture**. This is exactly
+what the older MSIX package couldn't do — Steam can neither browse nor inject into an app under
+`WindowsApps` — so if you set that up before, reinstall with the installer above and re-add it.
+
+### Portable zip and MSIX
+
+Two alternates, same signed binaries, published next to the installer on every build:
+
+- **Portable** — `…/latest/punktfunk-client-windows_x64-portable.zip`: unzip anywhere and run
+  `punktfunk-client.exe`. Nothing is registered, so `punktfunk://` links and the `punktfunk`
+  command on PATH stay with the installer. Needs the
+  [Windows App Runtime 2.x](https://learn.microsoft.com/windows/apps/windows-app-sdk/downloads)
+  installed once.
+- **MSIX** — `…/latest/punktfunk-client-windows_x64.msix`, kept for Microsoft Store
+  compatibility: `Add-AppxPackage .\punktfunk-client-windows_x64.msix`. If Windows reports a
+  missing dependency, install the Windows App Runtime 2.x above and re-run it. Install from a
+  signed-in desktop session — over SSH/RMM, `Add-AppxPackage` can fail with `0x80070005`. Note the
+  Steam integration above does **not** work from the MSIX.

 > The Windows client's hardware decode and HDR10 present are validated on glass on NVIDIA and Intel
 > (including HDR pass-through on the Intel D3D11VA path). If anything misbehaves,
@@ -218,7 +231,8 @@ but keeping them close is the least surprising. (Updating the **host** is its ow
 | **Linux Flatpak** | `flatpak update --user io.unom.Punktfunk` — **without `sudo`** (see the [Flatpak section](#linux-desktop-flatpak)) |
 | **Linux apt / dnf / pacman** | your normal `sudo apt upgrade` / `sudo dnf upgrade` / `sudo pacman -Syu`, or the app's own updater below |
 | **Fedora Atomic (layered)** | `rpm-ostree upgrade` on its own is not enough — see the note below the table |
-| **Windows MSIX** | no self-update — download the newer `.msix` as in [Windows](#windows) and re-run `Add-AppxPackage`. Coming from **0.28.1 or earlier**, see the note below the table |
+| **Windows installer** | download the newer `punktfunk-client-setup_<arch>.exe` as in [Windows](#windows) and run it — it upgrades in place, keeping your saved hosts and pairing. Switching **from the MSIX**, see the note below the table |
+| **Windows MSIX / portable** | no self-update — download the newer `.msix` and re-run `Add-AppxPackage` (from **0.28.1 or earlier**, see the note below the table), or unzip the newer portable build over the old one |
 | **macOS `.dmg`** | download the newer `Punktfunk-<version>.dmg` and drag it over the copy in Applications |
 | **iOS / iPadOS / tvOS** | TestFlight updates it |
 | **Android** | Google Play updates it; if you sideloaded, download the APK again and install over it |
@@ -253,6 +267,11 @@ This is one-time; releases after that upgrade in place. A packaged app's setting
 package, so removing the old one also removes this client's identity and its paired hosts — expect
 to [pair](/docs/pairing) again once. Nothing on the host side is affected.

+**Switching from the MSIX to the installer** (for the [Steam integration](#launching-through-steam-overlay-big-picture),
+or just to follow the new default): remove the MSIX first — `Get-AppxPackage unom.Punktfunk |
+Remove-AppxPackage` — then run the installer. Same caveat as above: the packaged app's saved hosts
+and pairing identity go with the package, so expect to pair again once.
+
 ### The Linux client can update itself

 The native Linux client checks its own channel and can apply the update in place, whichever package
@@ -21,6 +21,29 @@ repositories on Linux and from a signed installer on Windows — pick your syste

 Streaming **to** a device instead? That's a client — see [Install a Client](/docs/install-client).

+## Guided install (preview)
+
+On Linux, one command does what the pages above walk you through — detects your distro, adds the
+repo, installs the host, notices a Sunshine/Apollo/Vibeshine already on the box and moves one port
+so both can run, joins the `input` group, opens the firewall if you run one, starts the host and the
+console, and tells you how to pair:
+
+<Installer />
+
+Prefer to read what runs first (it's plain `sh`, ~350 lines):
+
+<Installer inspect />
+
+It asks before anything optional (Moonlight compat, the shared clipboard, the `punktfunk` group,
+starting at boot) and every answer has a default, so `sh install.sh --yes` — or piping it with no
+terminal — runs unattended; `--channel canary`, `--mgmt-port`, `--no-start` and the environment
+twins (`PUNKTFUNK_INSTALL_YES`, `PUNKTFUNK_INSTALL_CHANNEL`, `PUNKTFUNK_INSTALL_GAMESTREAM`,
+`PUNKTFUNK_INSTALL_CLIPBOARD`, `PUNKTFUNK_INSTALL_PUNKTFUNK_GROUP`, `PUNKTFUNK_INSTALL_LINGER`,
+`PUNKTFUNK_INSTALL_MGMT_PORT`) are listed by `--help`. It covers Ubuntu/Debian, Fedora, Arch-family
+and Bazzite/Fedora Atomic; NixOS, SteamOS and Windows it points at their pages. **Preview:** the
+per-system pages above remain the documented path, and the script runs exactly the install commands
+they show (CI fails if the two drift apart). Re-running is safe.
+
 ## Good to know

 - **Read [Security & Safe Use](/docs/security) once.** A streaming host is remote control of the
@@ -289,6 +289,18 @@ Then remove the repository as described under the host sections above, if this b
 it. To clear the client's own state without uninstalling — saved hosts and stream settings, keeping
 the paired identity — run `punktfunk-client --reset` instead.

+### Windows client (installer)
+
+Uninstall **Punktfunk** from **Settings → Apps → Installed apps** (it's a per-user install, so no
+admin prompt), or silently:
+
+```powershell
+& "$env:LOCALAPPDATA\Programs\Punktfunk\unins000.exe" /VERYSILENT
+```
+
+The uninstaller removes the Start-menu entries, the `punktfunk://` registration, and its own PATH
+entry. A **portable** unzip has nothing registered — just delete the folder.
+
 ### Windows client (MSIX)

 ```powershell
@@ -2,7 +2,7 @@ import defaultMdxComponents from 'fumadocs-ui/mdx'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import type { MDXComponents } from 'mdx/types'
 import BitrateCalculator from '@/components/BitrateCalculator'
-import { Install, Ports } from '@/components/platforms'
+import { Install, Installer, Ports } from '@/components/platforms'

 export function getMDXComponents(components?: MDXComponents) {
  return {
@@ -11,6 +11,7 @@ export function getMDXComponents(components?: MDXComponents) {
    BitrateCalculator,
    // Install commands / port table quoted from data/platforms.json: <Install platform="debian" />, <Ports />
    Install,
+    Installer,
    Ports,
    // Per-platform instructions: <Tabs items={['Linux', 'Windows']}><Tab value="Linux">…
    Tabs,
@@ -35,6 +35,24 @@ export function Install({ platform, title }: { platform: string; title?: string
  )
 }

+/** `<Installer />` — the guided installer's one-liner and its inspect-first form, from platforms.json. */
+export function Installer({ inspect }: { inspect?: boolean }) {
+  const lines = inspect ? platforms.installer.inspectFirst : [platforms.installer.oneLiner]
+  return (
+    <CodeBlock>
+      <Pre>
+        <code>
+          {lines.map((line, i) => (
+            <span key={i} className="line">
+              {line}
+            </span>
+          ))}
+        </code>
+      </Pre>
+    </CodeBlock>
+  )
+}
+
 /** `<Ports />` — every port the host and console use, with the firewall profile that opens it. */
 export function Ports() {
  const { ports, firewall } = platforms
@@ -47,6 +47,20 @@
    "web": "punktfunk-web"
  },

+  "installer": {
+    "$comment": "The guided Linux installer (WP4, preview). Canonical URL is the website's /install.sh, a redirect to the raw script on main so it's versioned with the code it installs; the docs hub and the download page quote these lines.",
+    "status": "preview",
+    "url": "https://punktfunk.unom.io/install.sh",
+    "source": "https://git.unom.io/unom/punktfunk/raw/branch/main/scripts/install.sh",
+    "oneLiner": "curl -fsSL https://punktfunk.unom.io/install.sh | sh",
+    "inspectFirst": [
+      "curl -fsSLO https://punktfunk.unom.io/install.sh",
+      "less install.sh",
+      "sh install.sh"
+    ],
+    "docs": "/docs/install#guided-install-preview"
+  },
+
  "conflicts": {
    "hosts": ["Sunshine", "Apollo", "Vibeshine"],
    "detect": "punktfunk-host detect-conflicts",
@@ -171,11 +185,11 @@
      "id": "windows-client",
      "name": "Windows client",
      "installs": "client",
-      "packageManager": "msix",
+      "packageManager": "installer",
      "docs": "/docs/install-client#windows",
      "install": [
-        "curl.exe -LO https://git.unom.io/api/packages/unom/generic/punktfunk-client-windows/latest/punktfunk-client-windows_x64.msix",
-        "Add-AppxPackage .\\punktfunk-client-windows_x64.msix"
+        "curl.exe -LO https://git.unom.io/api/packages/unom/generic/punktfunk-client-windows/latest/punktfunk-client-setup_x64.exe",
+        ".\\punktfunk-client-setup_x64.exe"
      ]
    },
    {
@@ -14,6 +14,12 @@ release is born complete and the announcement always has something to say.

 1. **Write the notes.** Add `docs/releases/vX.Y.Z.md` in the same commit (or PR) as the version
   bump. Copy `TEMPLATE.md` and fill it in. This file is the single source of truth for the body.
+   **Docs freshness, while you have the diff in front of you:** every user-facing fact the release
+   changes has its docs-site page updated (CONTRIBUTING.md "Where facts live" — `docs-drift` in CI
+   catches renamed knobs and dead links, not a stale sentence). If an install command, repo URL or
+   port changed, `data/platforms.json` changed with it — then run `bun run sync-platforms` in
+   punktfunk-website and commit, because its download page vendors that file and only refreshes
+   when someone does.
 2. **Tag & push.** `git tag -a vX.Y.Z … && git push origin vX.Y.Z` fans out to the build
   workflows. Whichever one wins the create race seeds the release body from this file
   (`scripts/ci/gitea-release.sh` → `ensure_release`, and its PowerShell twin). The release page
@@ -24,6 +24,10 @@
 #      platforms.json — the snapshot the <Install/> and <Ports/> MDX components render from
 #      (the docs Docker build context is docs-site/ alone) — must be a byte copy of it, same
 #      rule as gate 1.
+#   6. scripts/install.sh (the guided installer, WP4) runs the install lines platforms.json
+#      states — every `install` line of an apt/pacman/dnf/sysext host platform must appear in
+#      the script verbatim (it edits channel/group into the string at run time, never the
+#      literal), and the script must parse under sh.
 #
 # Textual gates, so textual limits: gate 2/3 match token spelling, not env reads — a var name in
 # a code comment counts as "exists", and a quoted constant that isn't an env var counts toward
@@ -107,4 +111,16 @@ if [ "$(cksum < data/platforms.json)" != "$(cksum < docs-site/src/data/platforms
    fail=1
 fi

+# ---------------------------------------------------------------- gate 6: installer quotes platforms.json
+if ! sh -n scripts/install.sh; then
+    echo "::error::scripts/install.sh does not parse under sh"
+    fail=1
+fi
+installer_check='const fs=require("fs");const p=JSON.parse(fs.readFileSync("data/platforms.json","utf8"));const sh=fs.readFileSync("scripts/install.sh","utf8");let bad=0;for(const x of p.platforms){if(x.installs!=="host"||!["apt","pacman","dnf","sysext"].includes(x.packageManager))continue;for(const line of x.install||[]){if(!sh.includes(line)){console.error(`::error::scripts/install.sh no longer carries platforms.json\x27s ${x.id} install line verbatim: ${line}`);bad=1}}}process.exit(bad)'
+if command -v bun >/dev/null 2>&1; then
+    bun -e "$installer_check" || fail=1
+elif command -v node >/dev/null 2>&1; then
+    node -e "$installer_check" || fail=1
+fi
+
 exit "$fail"
@@ -0,0 +1,384 @@
+#!/bin/sh
+# punktfunk guided host installer — PREVIEW.
+#
+#   curl -fsSL https://punktfunk.unom.io/install.sh | sh
+#   curl -fsSLO https://punktfunk.unom.io/install.sh && sh install.sh --help   # read it first
+#
+# Zero-to-streaming for a Linux host: detect the distro → add the package repo → install → deal
+# with a Sunshine/Apollo/Vibeshine already on the box (move one port) → groups → options →
+# firewall → start the services → verify → print how to pair. Plain POSIX sh, `read` prompts,
+# no TUI. Every prompt has a default so `--yes` (or no terminal) runs unattended.
+#
+# This is WP4 of the docs-and-onboarding overhaul and is labelled PREVIEW on purpose: the per-distro
+# docs pages (https://docs.punktfunk.unom.io/docs/install) remain the documented default until it
+# has mileage. The install commands it runs are the ones data/platforms.json states — verbatim, and
+# CI (scripts/ci/check-docs-drift.sh) fails if they drift apart. Windows (winget/installer), the
+# clients, NixOS and SteamOS have their own paths; this script points at them and stops.
+#
+# Exit codes: 0 done · 1 unsupported system / a step failed · 2 bad usage.
+set -u
+
+DOCS=https://docs.punktfunk.unom.io/docs
+USER=${USER:-$(id -un)}; export USER
+
+# ---------------------------------------------------------------------------- options
+YES=${PUNKTFUNK_INSTALL_YES:-0}
+CHANNEL=${PUNKTFUNK_INSTALL_CHANNEL:-stable}
+GAMESTREAM=${PUNKTFUNK_INSTALL_GAMESTREAM:-}     # 1/0, empty = ask (default no)
+CLIPBOARD=${PUNKTFUNK_INSTALL_CLIPBOARD:-}       # 1/0, empty = ask (default no)
+PF_GROUP=${PUNKTFUNK_INSTALL_PUNKTFUNK_GROUP:-}  # 1/0, empty = ask (default no)
+LINGER=${PUNKTFUNK_INSTALL_LINGER:-}             # 1/0, empty = ask (default no)
+MGMT_PORT=${PUNKTFUNK_INSTALL_MGMT_PORT:-47991}  # where the management API moves to on a conflict
+START=1
+DRY=${PUNKTFUNK_INSTALL_DRY_RUN:-0}
+
+usage() {
+    cat <<EOF
+punktfunk guided host installer (preview)
+
+usage: sh install.sh [options]
+  -y, --yes             no prompts: take every default (also the behaviour without a terminal)
+  --channel stable|canary   package channel (default stable; canary = latest main build)
+  --gamestream | --no-gamestream   also serve stock Moonlight clients (default no — trusted LANs only)
+  --clipboard | --no-clipboard     allow the shared clipboard on this host (default no)
+  --punktfunk-group | --no-punktfunk-group   join the punktfunk group (virtual Steam Deck pad; default no)
+  --linger | --no-linger           start the host at boot with nobody logged in (default no)
+  --mgmt-port N         port to move the management API to if Sunshine/Apollo holds 47990 (default $MGMT_PORT)
+  --no-start            install and configure, but don't enable the services
+  --dry-run             print every command it would run, change nothing
+  -h, --help            this text
+
+Every option has an environment twin for scripted installs: PUNKTFUNK_INSTALL_YES=1,
+PUNKTFUNK_INSTALL_CHANNEL, PUNKTFUNK_INSTALL_GAMESTREAM, PUNKTFUNK_INSTALL_CLIPBOARD,
+PUNKTFUNK_INSTALL_PUNKTFUNK_GROUP, PUNKTFUNK_INSTALL_LINGER, PUNKTFUNK_INSTALL_MGMT_PORT (1/0 for the flags).
+Docs: $DOCS/install
+EOF
+}
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        -y|--yes) YES=1 ;;
+        --channel) shift; CHANNEL=${1:-} ;;
+        --channel=*) CHANNEL=${1#*=} ;;
+        --gamestream) GAMESTREAM=1 ;;      --no-gamestream) GAMESTREAM=0 ;;
+        --clipboard) CLIPBOARD=1 ;;        --no-clipboard) CLIPBOARD=0 ;;
+        --punktfunk-group) PF_GROUP=1 ;;   --no-punktfunk-group) PF_GROUP=0 ;;
+        --linger) LINGER=1 ;;              --no-linger) LINGER=0 ;;
+        --mgmt-port) shift; MGMT_PORT=${1:-} ;;
+        --mgmt-port=*) MGMT_PORT=${1#*=} ;;
+        --no-start) START=0 ;;
+        --dry-run) DRY=1 ;;
+        -h|--help) usage; exit 0 ;;
+        *) echo "unknown option: $1" >&2; usage >&2; exit 2 ;;
+    esac
+    shift
+done
+case "$CHANNEL" in stable|canary) ;; *) echo "--channel must be stable or canary" >&2; exit 2 ;; esac
+case "$MGMT_PORT" in ''|*[!0-9]*) echo "--mgmt-port must be a number" >&2; exit 2 ;; esac
+
+# ---------------------------------------------------------------------------- plumbing
+say()  { printf '\033[1;36m==>\033[0m %s\n' "$*"; }
+ok()   { printf '\033[1;32m  ok\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33m  !!\033[0m %s\n' "$*" >&2; }
+die()  { printf '\033[1;31m  xx\033[0m %s\n' "$*" >&2; exit 1; }
+
+# Prompts read from the terminal, not stdin — stdin is the script itself under `curl | sh`.
+# No terminal (CI, cron, a pipe) behaves like --yes.
+# Probe by opening it: in a container or under a service /dev/tty is a node that exists but
+# can't be opened (ENXIO — no controlling terminal), so -r/-w would say yes and the redirect fail.
+TTY=/dev/tty
+(exec 3<>/dev/tty) 2>/dev/null || { TTY=; YES=1; }
+
+# ask "question" default(y|n) → 0 = yes, 1 = no
+ask() {
+    if [ "$YES" = 1 ]; then [ "$2" = y ]; return; fi
+    if [ "$2" = y ]; then hint="[Y/n]"; else hint="[y/N]"; fi
+    printf '\033[1m?\033[0m %s %s ' "$1" "$hint" > "$TTY"
+    read -r ans < "$TTY" || ans=
+    case "${ans:-$2}" in y|Y|yes|YES) return 0 ;; *) return 1 ;; esac
+}
+
+# run "shell snippet": print it, run it (-e), and give the package manager the terminal so its own
+# confirmation prompt works; under --yes the snippet is made non-interactive first.
+run() {
+    cmd=$1
+    if [ "$YES" = 1 ]; then
+        cmd=$(printf '%s' "$cmd" | sed \
+            -e 's/^sudo apt install /sudo apt install -y /' \
+            -e 's/^sudo dnf install /sudo dnf install -y /' \
+            -e 's/^sudo pacman -Syu /sudo pacman -Syu --noconfirm /')
+    fi
+    printf '  + %s\n' "$cmd"
+    [ "$DRY" = 1 ] && return 0
+    if [ -n "$TTY" ]; then sh -ec "$cmd" < "$TTY"; else sh -ec "$cmd" < /dev/null; fi \
+        || die "that step failed — fix it and re-run (the script is safe to repeat), or follow the page by hand: $DOCS_PAGE"
+}
+
+# Running as root without sudo (a minimal Debian container): a shim so the verbatim
+# `sudo …` lines from platforms.json still work.
+if [ "$(id -u)" = 0 ] && ! command -v sudo >/dev/null 2>&1; then
+    SHIM=$(mktemp -d) && printf '#!/bin/sh\nexec "$@"\n' > "$SHIM/sudo" && chmod +x "$SHIM/sudo" && PATH="$SHIM:$PATH"
+fi
+
+HOST_ENV=${XDG_CONFIG_HOME:-$HOME/.config}/punktfunk/host.env
+# set_env KEY VALUE — replace or append one line in host.env (created on first use).
+set_env() {
+    if [ "$DRY" = 1 ]; then ok "would set $1=$2 in $HOST_ENV"; return 0; fi
+    mkdir -p "$(dirname "$HOST_ENV")"
+    touch "$HOST_ENV"
+    if grep -q "^$1=" "$HOST_ENV"; then
+        sed -i "s|^$1=.*|$1=$2|" "$HOST_ENV"
+    else
+        printf '%s=%s\n' "$1" "$2" >> "$HOST_ENV"
+    fi
+    ok "$1=$2 → $HOST_ENV"
+}
+
+# ---------------------------------------------------------------------------- 0. preflight
+cat <<EOF
+
+  punktfunk guided host installer — PREVIEW
+  The per-distro pages stay the documented path; this automates them. Docs: $DOCS/install
+  Re-running is safe. Ctrl-C stops between steps.
+
+EOF
+
+[ "$(uname -s)" = Linux ] || [ -n "${PUNKTFUNK_INSTALL_OS_RELEASE:-}" ] || die "this installer is for Linux hosts — Windows: $DOCS/windows-host"
+[ -n "${SUDO_USER:-}" ] && [ "$(id -u)" = 0 ] && die "run this as your normal user, not under sudo — it calls sudo itself where needed, and the host runs as you (host.env, the services)"
+command -v curl >/dev/null 2>&1 || die "curl is required (install it with your package manager first)"
+OS_RELEASE=${PUNKTFUNK_INSTALL_OS_RELEASE:-/etc/os-release}   # override for testing the detection
+[ -r "$OS_RELEASE" ] || die "no /etc/os-release — can't tell which distro this is: $DOCS/install"
+. "$OS_RELEASE"
+ID=${ID:-}; ID_LIKE=${ID_LIKE:-}; VERSION_ID=${VERSION_ID:-}; PRETTY=${PRETTY_NAME:-$ID}
+like() { case " $ID $ID_LIKE " in *" $1 "*) return 0 ;; esac; return 1; }
+
+FAMILY=
+DOCS_PAGE=$DOCS/install
+if [ "$ID" = nixos ]; then
+    die "NixOS: add the flake input and enable the module instead — $DOCS/nixos"
+elif [ "$ID" = steamos ]; then
+    die "SteamOS host: the on-device installer builds against the running OS — $DOCS/steamos-host"
+elif command -v rpm-ostree >/dev/null 2>&1 || command -v bootc >/dev/null 2>&1 || [ "$ID" = bazzite ]; then
+    FAMILY=sysext;  DOCS_PAGE=$DOCS/bazzite
+elif like debian || like ubuntu; then
+    FAMILY=apt;     DOCS_PAGE=$DOCS/debian
+    [ "$ID" = ubuntu ] && DOCS_PAGE=$DOCS/ubuntu
+elif like fedora; then
+    FAMILY=dnf;     DOCS_PAGE=$DOCS/fedora
+elif like arch; then
+    FAMILY=pacman;  DOCS_PAGE=$DOCS/arch
+else
+    die "no package repo for '$PRETTY' yet — $DOCS/build-from-source"
+fi
+say "Detected $PRETTY → $FAMILY (guide: $DOCS_PAGE)"
+
+# Version floors the package can't express: below these the install succeeds and nothing can stream.
+major=${VERSION_ID%%.*}
+case "$ID" in
+    debian) [ "${major:-0}" -ge 13 ] 2>/dev/null || die "Debian $VERSION_ID is below the glibc floor — Debian 13+ or build from source: $DOCS/build-from-source" ;;
+    ubuntu) case "$VERSION_ID" in 2[0-5].*) warn "Ubuntu $VERSION_ID installs the package but cannot host — its desktop is too old to create a virtual display ($DOCS/requirements#the-floor-for-a-working-host). Use 26.04+."
+                ask "Continue anyway?" n || exit 1 ;; esac ;;
+    linuxmint) case "$VERSION_ID" in 2[0-2]*) warn "Linux Mint $VERSION_ID (Ubuntu 24.04 base) installs the package but cannot host — $DOCS/requirements#cinnamon-linux-mint-and-lmde. LMDE 7 and Mint 23 can."
+                ask "Continue anyway?" n || exit 1 ;; esac ;;
+esac
+RPM_GROUP=
+if [ "$FAMILY" = dnf ]; then
+    case "$major" in
+        44) RPM_GROUP=fedora-44 ;;
+        43) RPM_GROUP=bazzite ;;      # a plain Fedora 43 build of the same package
+        *)  die "no RPM group for Fedora $VERSION_ID yet — $DOCS/build-from-source" ;;
+    esac
+fi
+
+# ---------------------------------------------------------------------------- 1. install
+# The snippets below are data/platforms.json's install lines, verbatim (stable channel); canary
+# and the Fedora group are edited in. check-docs-drift.sh gate 6 keeps them identical.
+if command -v punktfunk-host >/dev/null 2>&1; then
+    say "punktfunk-host is already installed ($(punktfunk-host --version 2>/dev/null | head -1)) — skipping the install, continuing with setup"
+else
+    say "Installing the host ($CHANNEL channel)"
+    case "$FAMILY" in
+        apt)
+            repo_line='echo "deb [signed-by=/etc/apt/keyrings/punktfunk.asc] https://git.unom.io/api/packages/unom/debian stable main" | sudo tee /etc/apt/sources.list.d/punktfunk.list'
+            [ "$CHANNEL" = canary ] && repo_line=$(printf '%s' "$repo_line" | sed 's/ stable main/ canary main/')
+            run 'sudo install -d -m 0755 /etc/apt/keyrings'
+            run 'curl -fsSL https://git.unom.io/api/packages/unom/debian/repository.key | sudo tee /etc/apt/keyrings/punktfunk.asc >/dev/null'
+            run "$repo_line"
+            run 'sudo apt update'
+            run 'sudo apt install punktfunk-host'
+            ;;
+        pacman)
+            repo_line=$(cat <<'LINE'
+grep -q '^\[punktfunk\]' /etc/pacman.conf || printf '\n[punktfunk]\nServer = https://git.unom.io/api/packages/unom/arch/$repo/$arch\n' | sudo tee -a /etc/pacman.conf >/dev/null
+LINE
+)
+            # canary: both the grep guard (escaped brackets) and the printf body name the repo
+            [ "$CHANNEL" = canary ] && repo_line=$(printf '%s' "$repo_line" | sed -e 's/punktfunk\\\]/punktfunk-canary\\]/' -e 's/\[punktfunk\]/[punktfunk-canary]/')
+            run 'curl -fsS https://git.unom.io/api/packages/unom/arch/repository.key | sudo pacman-key --add -'
+            run 'sudo pacman-key --lsign-key E0CA04465C99C936E0B0C6510A317015A34DDD69'
+            run "$repo_line"
+            run 'sudo pacman -Syu punktfunk-host'
+            if ask "Install the web console and the plugin runner too (punktfunk-web, punktfunk-scripting — optional on Arch, recommended)?" y; then
+                run 'sudo pacman -Syu punktfunk-web punktfunk-scripting'
+            fi
+            ;;
+        dnf)
+            group=$RPM_GROUP
+            [ "$CHANNEL" = canary ] && group="$group-canary"
+            run "$(cat <<'CMD'
+sudo tee /etc/yum.repos.d/punktfunk.repo >/dev/null <<'REPO'
+[punktfunk]
+name=punktfunk
+# fedora-44 on Fedora 44; bazzite on Fedora 43 (a plain Fedora 43 build of the same package)
+baseurl=https://git.unom.io/api/packages/unom/rpm/fedora-44
+enabled=1
+gpgcheck=1
+repo_gpgcheck=1
+gpgkey=https://git.unom.io/api/packages/unom/rpm/repository.key
+       https://git.unom.io/api/packages/unom/generic/punktfunk-keys/1/RPM-GPG-KEY-punktfunk
+REPO
+CMD
+)"
+            [ "$group" = fedora-44 ] || run "sudo sed -i 's|/rpm/fedora-44|/rpm/$group|' /etc/yum.repos.d/punktfunk.repo"
+            run 'sudo dnf install punktfunk'
+            ;;
+        sysext)
+            install_line='sudo bash punktfunk-sysext.sh install'
+            [ "$CHANNEL" = canary ] && install_line="$install_line --channel canary"
+            run 'curl -fsSLO https://git.unom.io/unom/punktfunk/raw/branch/main/packaging/bazzite/punktfunk-sysext.sh'
+            run "$install_line"
+            ;;
+    esac
+    hash -r 2>/dev/null || true
+    if [ "$DRY" != 1 ]; then
+        command -v punktfunk-host >/dev/null 2>&1 || die "the install finished but punktfunk-host isn't on PATH — open a new terminal and re-run, or see $DOCS_PAGE"
+        ok "punktfunk-host $(punktfunk-host --version 2>/dev/null | head -1) installed"
+    fi
+fi
+
+# ---------------------------------------------------------------------------- 2. another host?
+# detect-conflicts exits 1 only for a Sunshine-family host that runs or autostarts; dormant
+# leftovers print and exit 0. Native-only, the single port both want is the management API's.
+say "Checking for Sunshine / Apollo / Vibeshine"
+CONFLICT=0
+if [ "$DRY" = 1 ] && ! command -v punktfunk-host >/dev/null 2>&1; then
+    printf '  + %s\n' 'punktfunk-host detect-conflicts'
+elif report=$(punktfunk-host detect-conflicts 2>&1); then
+    ok "${report:-No conflicting game-streaming host detected.}"
+else
+    CONFLICT=1
+    printf '%s\n' "$report" | sed 's/^/     /'
+    warn "another streaming host is active on this box — both want TCP 47990 (its web UI, punktfunk's management API)"
+    if ask "Keep both for now and move punktfunk's management API to port $MGMT_PORT? (No = you stop the other host yourself)" y; then
+        set_env PUNKTFUNK_MGMT_BIND "0.0.0.0:$MGMT_PORT"
+        echo "     Clients learn the port from discovery; the console and plugins read it from mgmt-endpoint. Details: $DOCS/switching-from-sunshine"
+    else
+        MGMT_PORT=
+        echo "     Stop it before you start punktfunk (e.g. sudo systemctl disable --now sunshine) — $DOCS/switching-from-sunshine"
+    fi
+fi
+[ "$CONFLICT" = 0 ] && MGMT_PORT=
+
+# ---------------------------------------------------------------------------- 3. groups
+say "Controller access"
+if id -nG "$USER" 2>/dev/null | tr ' ' '\n' | grep -qx input; then
+    ok "already in the input group"
+elif command -v ujust >/dev/null 2>&1; then   # Bazzite: the input group is recipe-managed, usermod is the wrong tool
+    run 'ujust add-user-to-input-group'; RELOGIN=1
+elif ! getent group input >/dev/null 2>&1; then
+    warn "no 'input' group on this system — virtual gamepads need /dev/uinput access; see $DOCS_PAGE"
+else
+    run 'sudo usermod -aG input "$USER"'; RELOGIN=1
+fi
+if [ -z "$PF_GROUP" ]; then
+    ask "Also join the punktfunk group? It enables the virtual Steam Deck controller (paddles, trackpads, gyro) by granting usbip attach — only on a machine you trust ($DOCS/gamescope#nobara-and-other-autologin-display-managers)" n && PF_GROUP=1 || PF_GROUP=0
+fi
+if [ "$PF_GROUP" = 1 ]; then
+    if id -nG "$USER" 2>/dev/null | tr ' ' '\n' | grep -qx punktfunk; then ok "already in the punktfunk group"
+    else run 'sudo usermod -aG punktfunk "$USER"'; RELOGIN=1; fi
+fi
+
+# ---------------------------------------------------------------------------- 4. options
+say "Options (host.env — everything here is off by default and reversible)"
+if [ -z "$GAMESTREAM" ]; then
+    ask "Also serve stock Moonlight clients (GameStream compat)? Its pairing runs over plain HTTP — trusted LANs only; Punktfunk's own apps don't need it" n && GAMESTREAM=1 || GAMESTREAM=0
+fi
+if [ "$GAMESTREAM" = 1 ]; then
+    [ "$CONFLICT" = 1 ] && warn "with another GameStream host running, only one can bind the Moonlight ports — stop the other first or skip this"
+    set_env PUNKTFUNK_GAMESTREAM 1
+fi
+if [ -z "$CLIPBOARD" ]; then
+    ask "Allow the shared clipboard on this host (each client still opts in per host)?" n && CLIPBOARD=1 || CLIPBOARD=0
+fi
+[ "$CLIPBOARD" = 1 ] && set_env PUNKTFUNK_CLIPBOARD on
+
+# ---------------------------------------------------------------------------- 5. firewall
+# Packages never open ports; they install firewalld services / ufw profiles by these names.
+say "Firewall"
+if command -v firewall-cmd >/dev/null 2>&1 && systemctl is-active --quiet firewalld 2>/dev/null; then
+    svcs="--add-service=punktfunk-native --add-service=punktfunk-web"
+    [ "$GAMESTREAM" = 1 ] && svcs="$svcs --add-service=punktfunk-gamestream"
+    [ -n "$MGMT_PORT" ] && svcs="$svcs --add-port=$MGMT_PORT/tcp"
+    run 'sudo firewall-cmd --reload'
+    run "sudo firewall-cmd --permanent $svcs"
+    run 'sudo firewall-cmd --reload'
+elif command -v ufw >/dev/null 2>&1 && grep -qs '^ENABLED=yes' /etc/ufw/ufw.conf; then
+    run 'sudo ufw allow punktfunk-native'
+    run 'sudo ufw allow punktfunk-web'
+    [ "$GAMESTREAM" = 1 ] && run 'sudo ufw allow punktfunk-gamestream'
+    [ -n "$MGMT_PORT" ] && run "sudo ufw allow $MGMT_PORT/tcp"
+else
+    ok "no active firewall found — nothing to open ($DOCS/ports if you add one later)"
+fi
+
+# ---------------------------------------------------------------------------- 6. start
+if [ "$START" = 1 ]; then
+    say "Starting the host and the web console"
+    if ! systemctl --user show-environment >/dev/null 2>&1; then
+        warn "no user systemd session here (ssh without a login session?) — run this from a terminal in your desktop session:"
+        echo "     systemctl --user enable --now punktfunk-host punktfunk-web"
+        START=0
+    else
+        systemctl --user daemon-reload 2>/dev/null
+        units="punktfunk-host"
+        systemctl --user list-unit-files punktfunk-web.service 2>/dev/null | grep -q '^punktfunk-web.service' && units="$units punktfunk-web"
+        # The plugin runner fills the game library; apt/dnf/sysext start it themselves, Arch doesn't.
+        if systemctl --user list-unit-files punktfunk-scripting.service 2>/dev/null | grep -q disabled; then units="$units punktfunk-scripting"; fi
+        run "systemctl --user enable --now $units"
+        if [ -z "$LINGER" ]; then
+            ask "Start the host at boot even with nobody logged in (headless box)?" n && LINGER=1 || LINGER=0
+        fi
+        [ "$LINGER" = 1 ] && run 'sudo loginctl enable-linger "$USER"'
+    fi
+fi
+
+# ---------------------------------------------------------------------------- 7. verify + next
+say "Checking"
+if [ "$START" = 1 ] && [ "$DRY" != 1 ]; then
+    sleep 2
+    if systemctl --user is-active --quiet punktfunk-host; then ok "punktfunk-host is running"
+    else warn "punktfunk-host is not active — journalctl --user -u punktfunk-host -e ($DOCS/troubleshooting#the-linux-host-service-wont-start)"; fi
+    if command -v ss >/dev/null 2>&1 && ss -lun 2>/dev/null | grep -q ':9777 '; then ok "listening on UDP 9777 (punktfunk/1)"
+    else warn "nothing on UDP 9777 yet — give it a second, then: journalctl --user -u punktfunk-host -e"; fi
+fi
+# GPU drivers are the docs pages' job (one step, per distro) — but the one silent failure worth
+# calling out: Fedora + NVIDIA with Fedora's own ffmpeg has no NVENC, and the RPM only Recommends
+# RPM Fusion's build, so the install succeeded and encoding won't.
+if [ "$FAMILY" = dnf ] && grep -qs 0x10de /sys/bus/pci/devices/*/vendor 2>/dev/null && ! rpm -q ffmpeg-libs >/dev/null 2>&1; then
+    warn "NVIDIA GPU, but RPM Fusion's ffmpeg-libs isn't installed — NVENC won't work until it is: step 1 of $DOCS_PAGE"
+fi
+ip=$(hostname -I 2>/dev/null | awk '{print $1}')
+[ -n "$ip" ] || ip=$(ip -4 route get 1.1.1.1 2>/dev/null | awk '{for(i=1;i<=NF;i++) if($i=="src") print $(i+1); exit}')
+cat <<EOF
+
+  Done. Next:
+  1. Open the web console:  https://${ip:-<host-ip>}:47992  (the certificate is the host's own — continue past the warning)
+     password:  sed -n 's/^PUNKTFUNK_UI_PASSWORD=//p' ~/.config/punktfunk/web-password
+  2. Install a client on the device you stream to ($DOCS/install-client), connect, and click
+     Approve in the console — or Pair a device for a PIN ($DOCS/pairing).
+  3. Stream. Ctrl+Alt+Shift+Q hands mouse and keyboard back on desktop clients.
+EOF
+[ "${RELOGIN:-0}" = 1 ] && echo "  Group changes apply after you log out and back in (controllers won't work until then)."
+[ "$CONFLICT" = 1 ] && echo "  Running next to Sunshine/Apollo: $DOCS/switching-from-sunshine"
+echo "  Stuck? $DOCS/troubleshooting · this installer is a preview — the full guide is $DOCS_PAGE"
+echo