installer: add explicit --install-runtime for the pinned CPU Python runtime (D4)

Creates a user-local venv under $XDG_DATA_HOME/frameyap/runtimes from the
invoking python3 (3.10-3.13), installs CPU torch==2.8.0 from PyTorch's CPU
index and moondream==2.4.0 from PyPI (binary wheels only, pip --isolated,
Torch constrained), verifies imports and no CUDA, then sets python= in
paths.conf and removes superseded managed runtimes. Requires --yes; has a
read-only --print-plan/--json. A failure removes only the new venv.

Offline tests mock pip; a real run passed on x86-64 Python 3.12. ARM64 Frame
install is still pending.

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

docs/build.md

@@ -63,7 +63,8 @@ initialize OpenVR, open a microphone, run ASR, download files or inject input.
   source-build mode, safe extraction, atomic current-version selection, retained
   rollback, runtime/install lock, foreign-file refusal and explicit
   unregister-before-uninstall acknowledgement. Source mode needs a local
-  compiler, SDK and libraries; the installer does not yet pip-install a runtime.
+  compiler, SDK and libraries. An explicit `--install-runtime --yes` step
+  pip-installs the pinned CPU Python runtime into a user-local venv.
 
 ## Deliberately not claimed
 
@@ -103,7 +104,8 @@ compatible offline runtime and independent tests. Native `--run` flags `--backen
 `--manifest-dir /absolute/manifests` are wired through
 the installed launcher as an explicit override, not a provisioning command.
 Inference uses the `moondream` Python package and Kestrel runtime, separately
-provisioned in your own environment; builds/tests/installer do not pip-install them. See
+provisioned in your own environment or by the explicit `install.sh --install-runtime --yes`;
+builds and tests never pip-install them. See
 [third-party notes](third-party.md).
 
 ## Developer native build

docs/install-design.md

@@ -4,9 +4,10 @@ Goal: a one-command, pinned GitHub release install for Steam Frame without a Ste
 store AppID, sudo or end-user compiler. **No public archive or verified clean
 install is published. Do not advertise a `curl | sh` command as functional.**
 The local installer has binary-archive and explicitly provisioned source-build
-modes, machine-readable plans/results and an attended TTY path. The current
-native-only artifact does not include or pip-install an ASR runtime; it is not
-a one-command voice-typing experience. See [packaging](packaging.md) for exact
+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](packaging.md) for exact
 flags and [third-party notes](third-party.md).
 
 `scripts/install-preflight.sh` is a read-only Linux ARM64/glibc/bootstrap check;
@@ -52,7 +53,7 @@ already be available for registration; never start/restart it for installation.
   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, Kestrel or an interpreter. Launch paths to an independently
+  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
@@ -66,7 +67,7 @@ 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. Native-only archives support overlay checks but need
+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.
 

docs/packaging.md

@@ -102,8 +102,21 @@ installed `redux.json` bytes: under the model lock a mismatch fails **before**
 a model directory is created or any network request. In the locally implemented
 Models UI, Install displays source, rounded size, license text, attribution and
 the fingerprint; only the second Confirm Install click passes that fingerprint
-through the backend helper to the installer. Installation alone does not
+through the backend helper to the installer. Model installation does not
 provision a CPU Python runtime; no in-panel flow has been accepted on Frame.
+
+`sh install.sh --install-runtime --yes` explicitly creates a user-local venv
+under `$XDG_DATA_HOME/frameyap/runtimes/` from the invoking `python3` (3.10–3.13),
+pip-installs `torch==2.8.0` from PyTorch's CPU index, then `moondream==2.4.0`
+(which pins kestrel 0.8.0, kestrel-native 0.1.8, kestrel-kernels 0.7.0) from PyPI
+with Torch constrained, binary wheels only and `pip --isolated`. It verifies the
+imports and that Torch has no CUDA, then sets `python=` in `paths.conf` (other
+lines kept) and removes superseded FrameYap-managed runtimes. A failure removes
+only the new venv and leaves `paths.conf` unchanged. `--print-plan --json` shows
+the packages, index and size (about 200 MB of wheels, roughly 1–1.5 GB on disk)
+without touching anything. The app must be closed (install lock). Transitive
+dependencies are not pinned. Validated end to end on x86-64 Python 3.12
+(2026-09-25); a clean Frame install is still pending.
 In the source tree, `python3 scripts/model-status.py --list-models` or
 `--check-model redux --model-dir /absolute/model` hash-checks local files;
 the native `frameyap --list-models` / `--check-model` entry points use the
@@ -151,7 +164,7 @@ model=/absolute/path/to/pinned/local/model
 The launcher reads these as **literal absolute paths**, not shell code, and does
 not follow a symlink to the config file. Environment variables override either
 setting for an explicit launch. This `paths.conf` survives upgrade/uninstall;
-the installer does not populate it or bundle an unauthorized runtime. No
+only `--install-runtime` writes its `python=` line, and no runtime is bundled. No
 pip/bootstrap/model download or fallback is invoked by the launcher. Without
 paths, the native-only artifact cannot perform voice inference; its default
 runtime and model locations do not exist. A new installer accepts only the exact

docs/worker.md

@@ -80,8 +80,9 @@ flags do not prove every third-party internal is unable to access a network.
 Runtime/build/tests perform no downloads; the separate explicit setup utility
 `scripts/fetch-model.py` can provision the public pinned weights.
 
-Current native-only archives do not bundle or pip-install the runtime; see
-[third-party notes](third-party.md). No public runtime bundle has been released.
+Native-only archives do not bundle the runtime; the explicit
+`install.sh --install-runtime --yes` step pip-installs it into a user-local venv
+(see [packaging](packaging.md) and [third-party notes](third-party.md)). No public runtime bundle has been released.
 Limited ARM64 measurements were taken during development; they are not a claim
 of complete headset acceptance.