Initialize standalone Frame Dictation scaffold and install preflight

docs/install-design.md

@@ -0,0 +1,105 @@
+# Installation and distribution goal
+
+**User goal:** install from GitHub with a `curl … | bash`-style command, without a
+Steam store AppID. This is a requirement for the future release, not a working
+installer. No release artifacts or functional installer are published yet.
+
+The read-only `scripts/install-preflight.sh` checks whether a host appears suitable
+for the **proposed** Linux ARM64 glibc package format and has the expected basic
+bootstrap utilities. It reports system Python, Git and uv, but none is required
+for the intended bundled release. A read-only check on one Frame observed
+Python 3.12.3 and Git, but not uv; availability may change. This script
+is not an installer or a model/runtime compatibility test; it has no downloads,
+registration, SteamVR initialization or persistent changes. No glibc minimum can
+be certified until release artifacts are chosen and tested.
+
+## Non-Steam overlay identity
+
+OpenVR overlay applications do not require a Steam store AppID or Steamworks.
+The native executable initializes as `VRApplication_Overlay`. For discoverability
+and optional autolaunch, register an OpenVR application manifest with a stable,
+project-owned **string application key** (proposed: `local.frame-dictation.overlay`).
+That key is not a numeric Steam AppID. No purchase/store listing or non-Steam Steam
+library shortcut should be necessary for the normal route.
+
+The manifest identifies the installed executable; the installer/registration
+helper should use `IVRApplications::AddApplicationManifest` and the corresponding
+remove operation, not hand-edit Steam's internal JSON. Autolaunch uses the OpenVR
+application setting only when explicitly requested. Validate the exact manifest,
+launch behaviour, registration persistence and uninstall on native Frame before
+claiming this route works end to end. Existing probes established overlay client
+initialization, not manifest installation.
+
+SteamVR/OpenVR must already be installed and usable. If registration needs a
+running runtime, defer it to the first explicit launch rather than starting or
+restarting SteamVR behind the user's back.
+
+## Intended user experience
+
+1. Run one documented command from the eventual GitHub repository/release.
+2. Installer identifies native Linux ARM64 Frame, resolves a pinned release and
+   explains/downloads the application, compatible CPU runtime and pinned model.
+3. User-local installation provides a simple `frame-dictation` launcher, desktop
+   entry where supported, and an OpenVR manifest. No compiler, engine checkout,
+   Python dependency troubleshooting or separate ASR server for ordinary users.
+4. The user explicitly launches/enables dictation. No installation-time microphone
+   recording, input injection, inference benchmark or overlay takeover.
+
+Illustrative command shape only; `OWNER`, `REPO` and `VERSION` are placeholders:
+
+```sh
+curl --fail --silent --show-error --location \
+  https://raw.githubusercontent.com/OWNER/REPO/VERSION/install.sh | bash
+```
+
+Also document a download-inspect-run path for users who do not want to pipe remote
+code into a shell. Pin a release/tag instead of executing a moving branch by default.
+Offer explicit version selection and noninteractive flags; do not read interactive
+confirmation from stdin while the installer itself is arriving through that pipe.
+
+## Packaging boundary
+
+- Prebuilt ARM64 executable plus a known-compatible, isolated CPU inference runtime;
+  no external application libraries/assets and no system Python modification.
+- Model fetched during explicit installation/setup, with pinned revision/hash and
+  attribution. A documented `--without-model` option can defer the large download.
+  No surprise first-utterance downloads. Licensing may require obtaining particular
+  runtime components from their vendor instead of redistributing them in our tarball.
+- Install under `$XDG_DATA_HOME/frame-dictation` (default `~/.local/share/...`),
+  configuration under `$XDG_CONFIG_HOME/frame-dictation`, optional launcher in
+  `~/.local/bin`; transient audio stays in a private `$XDG_RUNTIME_DIR` directory.
+- No sudo, OS read-only-root changes, package-manager installs, udev changes,
+  `/dev/uinput` permission changes or modifications to unrelated launchers.
+- No Steam store AppID, Steamworks SDK, root service or network ASR dependency.
+- Distribution license/third-party notices must be resolved before publication;
+  the small model file alone is not the full runtime or redistribution permission.
+
+## Installer lifecycle and safety
+
+- Detect architecture, libc and prerequisites first. Unsupported hosts fail with a
+  clear explanation; never install an x86 payload silently on ARM64.
+- Download to a staging directory, check versioned SHA-256 manifests and archive
+  paths, then atomically select the completed version. HTTPS/checksums alone do not
+  authenticate a compromised publisher; use signed release metadata if provided.
+- Keep configuration across upgrades; retain the previous version for rollback.
+  Refuse or defer replacement while this application's process is running rather
+  than killing arbitrary processes. Never touch SSH or unrelated sessions.
+- Autostart is opt-in (`--autostart` or explicit settings); do not enable a systemd
+  service or SteamVR autolaunch by default. Do not enable overlay input overrides.
+- Uninstall removes only owned launcher, manifest registration and install files;
+  model/config deletion is separately explicit. Preserve other SteamVR apps.
+- No update daemon initially. A deliberate rerun/update command is sufficient.
+
+## Acceptance before advertising one-command installation
+
+- Clean supported Frame: install without sudo/compiler/engine checkout/store AppID;
+  launch overlay, load local Redux and type into an owned disposable target.
+- Normal use after installation needs no network connection or desktop ASR host.
+- Failed download/hash, unsupported architecture, low disk space and interrupted
+  upgrades leave a usable previous install or a cleanly reported failure.
+- Reinstall, rollback and uninstall preserve unrelated data and SteamVR entries.
+- Noninteractive piped invocation never hangs on stdin; inspection-first path works.
+- Autolaunch remains off unless chosen; uninstall removes only our registration.
+- Hardware-free installer tests use temporary homes, mocked runtime registration
+  and local fixture artifacts. Never exercise a real user's Steam configuration
+  in ordinary CI/CTest.