baketnk--frame-yap/docs/install-design.md

Installation goal and current boundary

Goal: a one-command, pinned GitHub release install for Steam Frame without a Steam store AppID, sudo or end-user compiler. Release v0.1.202609251524 publishes an ARM64 archive, its .sha256 and install.sh on GitHub, built on a Frame with scripts/build-release.sh; curl …/releases/latest/download/install.sh | sh runs the attended flow. A clean-install check on Frame is the remaining gate. The local installer has binary-archive and explicitly provisioned source-build modes, machine-readable plans/results and an attended TTY path. The native-only artifact does not include an ASR runtime; a separate explicit --install-runtime --yes step pip-installs the pinned CPU runtime into a user-local venv. Install, model and runtime are still three commands. See packaging for exact flags and third-party notes.

scripts/install-preflight.sh is a read-only Linux ARM64/glibc/bootstrap check; --source adds toolchain/library checks. It does not download, install, register, or certify model/runtime compatibility or a minimum libc version. Its report of Python/Git/uv availability is not a runtime guarantee: install.sh currently needs Python 3.12+ for its bootstrap, while native-only voice inference needs a separately provisioned compatible CPU Python environment and pinned weights.

OpenVR identity

local.frameyap.overlay is a string OpenVR application key, not a Steam store AppID. The installer creates a manifest and a desktop entry user-locally; the desktop entry (read by KDE's menu) is the intended launch path, and the app is not registered with SteamVR or launched by default. Explicit frameyap --register /absolute/manifest/path uses the OpenVR registration API; registration alone did not reveal a launcher in the first checked dashboard menu. On one Frame the user opened the panel from the Non-Steam section and quit; shortcut discovery and persistence after a normal restart are still unverified. Optional --autolaunch/--no-autolaunch on the installer explicitly request OpenVR registration/autolaunch choices; no SteamVR settings or sessions are changed without that request. Unregister explicitly before uninstall. SteamVR must already be available for registration; never start/restart it for installation.

Installation workflows

• Binary mode (no compiler): verify a locally supplied ARM64 archive digest, or, after a vetted release actually exists, explicitly approve retrieval of a pinned v0.1.YYYYMMDDHHMM GitHub tag and checksum. No moving latest tag. --mode binary --archive FILE --sha256 HASH --version 0.1.YYYYMMDDHHMM selects the local-artifact path.
• Source mode: requires explicit local source, SDK, SDL/OpenVR libraries and their notices, CMake/C++20, native build dependencies and a version. It builds, stages, packages and continues through local installation; it does not provision ASR packages. See packaging for all flags.
• Model: only an explicit --install-model --backend redux --yes fetches pinned public files for the already installed backend. Inspect the read-only --print-plan --json first; it includes model size, attribution and license metadata from assets/backends/redux.json. --expected-manifest-sha256 HASH binds consent to the exact installed manifest bytes and fails before model directory creation/network if they changed. The local in-panel chooser shows source, size, license text, attribution and manifest digest, then requires a second Confirm Install click; the installed/native UI route still needs clean-target and headset acceptance. --without-model permits an archive install without bundled model files. Neither operation installs Torch, moondream or Kestrel; only --install-runtime --yes does (see packaging). Launch paths to an independently authorized runtime/model can be set in paths.conf.
• Noninteractive: supply flags and --yes for network/model consent. --print-plan is read-only; --json provides structured results/errors and progress events for a model download. No prompt reads answers from a pipe. A bare terminal invocation, including curl … | sh, prompts on the real terminal (/dev/tty), asks y/n separately for the model and runtime downloads, and prints the equivalent flag commands.

Installation is user-local under XDG data/config paths with a managed launcher, retained rollback, SHA-256/path validation, foreign-file refusal and a lock shared with the app. No OS package changes, udev rule, root service, Steam store listing, unrelated application dependency, microphone recording, input injection or automatic update daemon. Hashes detect accidental/unauthorized alteration of a downloaded artifact but do not authenticate a compromised publisher; release metadata needs independent trust. No installer operation silently runs pip or launches inference; pip runs only under explicit --install-runtime --yes. Native-only archives support overlay checks but need an externally provisioned runtime/weights before voice typing. Selecting an uninstalled backend does not authorize a download or supply its inference engine.

Gate before publishing the goal as fulfilled

Vet the exact release closure, ARM64 symbol versions/loader and a compatible CPU Python environment; establish a tested libc/runtime floor, then publish and authenticate a checksummed archive from a clean tag. On a clean supported Frame, install without a compiler/sudo/store ID, load Redux, type into a disposable owned target and validate rollback/uninstall, foreign-file failures, autolaunch off, and no unintended session changes. Separately validate microphone → review → delivered input and headset comfort. Offline installer fixture tests and a local native build are not those acceptance gates.