Site: current app and docs; Controller buttons page; clearer wording

- Home, meta descriptions: Linux apps alongside Quest, PC VR and Android; shorter notice, matching the README. - Setup page: the app's labels ('Already set up?', 'Connect by address…'); Pair new host asks by itself. - Tour: the install video is about 90 s. - Docs: CONTROLLERS.md is a site page now, and the image sync copies docs/images subfolders (its diagram lives in controllers/); the 'game won't start' path starts with the FAQ. - 'it'/'this'/'that' replaced by the noun where the referent was unclear (walkthrough, setup, download, install pages, compare, PC VR panel, demo app).
Docs: name the thing instead of 'it', 'this' or 'that' where the referent was unclear
2026-10-25 23:03:43 +01:00 · 2026-10-24 23:35:53 -04:00 · 2026-10-24 23:35:52 -04:00 · 2026-10-24 23:35:52 -04:00 · 2026-10-24 23:35:51 -04:00 · 2026-10-24 23:35:51 -04:00
35 changed files with 840 additions and 874 deletions
@@ -2,12 +2,17 @@

 Thanks for helping. The quickest contributions:

- **A game works on the Frame?** In FramePort: the game's menu → **Share working config…** opens a prefilled issue
-  with its recipe. Accepted configs become built-in recipes.
- **Something doesn't work?** The game's menu → **Report a problem…** saves a diagnostics zip (personal data
-  removed) and opens a prefilled issue to attach it to.
+- **A game works on the Frame?** Game menu → **Recipe → Share working recipe…** opens a prefilled issue. After
+  review the recipe becomes a built-in recipe (`catalog/games/<package>.yaml`), and installed copies of FramePort get
+  the recipe within 6 hours.
+- **Something doesn't work?** Game menu → **Troubleshoot → Report a problem…** saves a diagnostics zip (personal data
+  removed) and opens a prefilled issue to attach the zip to.
+
+Without the app: [working recipe form](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml)
+· [problem report form](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml).

 ## Development
+
 ```
 uv sync --extra dev          # Python 3.11+, uv (https://docs.astral.sh/uv/)
 uv run frameport-gui         # the app
@@ -15,39 +20,32 @@ uv run frameport --help      # the command line
 uv run pytest                # tests (no headset or game files needed)
 uv run ruff check .          # lint
 ```
- Code and architecture: `CLAUDE.md`, `docs/ARCHITECTURE.md`; per-game symptoms and fixes: `docs/PLAYBOOK.md`.
- Interface wording: `docs/STYLE.md`. GUI texts go through `tr()`; after changing them run
-  `python scripts/i18n_extract.py`.
- Translations: see [Translating FramePort](#translating-frameport) below.
- New fixes are patch modules (`src/frameport/patches/`), with a triage signature (`catalog/triage.yaml`), a PLAYBOOK
-  row and a unit test.
- Native binaries in `artifacts/` are rebuilt with `python native/build.py` (downloads the NDK).

-## Adding a tested game
-
-Tested a game on the Steam Frame? The easiest way is in FramePort: open the game → **…** → **Share working config…**.
-It opens a prefilled GitHub issue with the exact recipe; after review a workflow turns it into
-`catalog/games/<package>.yaml`. Without the app: [working config form](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml). Something doesn't run: the game's
-**Report a problem…** (diagnostics zip, personal data removed) or the [problem report form](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml).
-After catalog changes, regenerate the games list: `python scripts/compat_list.py`.
+- Where things are: `docs/ARCHITECTURE.md` (module notes in `CLAUDE.md`), `docs/PLAYBOOK.md` (symptoms and fixes),
+  `docs/FRAME_RUNTIME.md` (runtime facts).
+- A new fix = a patch module (`src/frameport/patches/`) + a triage signature (`catalog/triage.yaml`) + a PLAYBOOK row
+  + a unit test.
+- After changing a patch, game setting, recipe or triage signature: `python scripts/patch_docs.py`. After catalog
+  changes also `python scripts/compat_list.py`.
+- GUI texts go through `tr()`; after changing them run `python scripts/i18n_extract.py`. Wording rules:
+  `docs/STYLE.md`.
+- Docs screenshots and videos are rendered, never taken by hand: `docs/SHOWCASE.md`.
+- Native binaries in `artifacts/`: `python native/build.py` (downloads the NDK).

 ## Translating FramePort
-The app's texts (screens, help, patch and setting descriptions) can be translated; the command line, logs and
-diagnostics stay English. No programming needed:

-1. Copy `src/frameport/locales/template.json` to `src/frameport/locales/<code>.json`, where `<code>` is the language
-   code (`de`, `fr`, `pt`, `ja`, …).
-2. Add `"_language": "<the language's own name>"` (e.g. `"Deutsch"`); it's shown in Settings → Language.
-3. Fill in the values. Each key is the English text; leave a value empty to keep the English text. Plural entries
-   have a list value: `["<one>", "<other>"]`. Keep `{placeholders}` such as `{title}` or `{n}` exactly as they are,
-   and keep `…`, `·` and line breaks where the English has them.
-4. Try it: `uv run frameport-gui`, choose the language in Settings → Language, restart FramePort.
-5. Open a pull request with the file. When the English texts change, `python scripts/i18n_extract.py` refreshes the
-   template; new texts then show in English until they're translated.
+The app's texts can be translated, no programming needed. The command line, logs and diagnostics stay English.

-Wording rules for English (and a guide for tone) are in `docs/STYLE.md`.
+1. Copy `src/frameport/locales/template.json` to `src/frameport/locales/<code>.json` (`de`, `fr`, `pt`, `ja`, …).
+2. Add `"_language": "<the language's own name>"`, for example `"Deutsch"`.
+3. Fill in the values. Each key is the English text; an empty value keeps the English. Plural entries take a list:
+   `["<one>", "<other>"]`. Keep `{placeholders}` such as `{title}` exactly, and `…`, `·` and line breaks where the
+   English has them.
+4. Try the translation: `uv run frameport-gui`, pick the language in Settings → Appearance → Language, restart FramePort.
+5. Open a pull request with the file. New English texts show in English until they're translated.

 ## Ground rules
+
 - Use only games you own. Contributions that help bypass DRM, licence or entitlement checks, or that add game files,
  are not accepted.
 - Never commit personal data (IP addresses, user names, home paths, Steam IDs).
@@ -8,41 +8,35 @@
 ![Steam Frame](https://img.shields.io/badge/Steam%20Frame-supported-1b2838?logo=steam&logoColor=white)

 Install Quest games, Android apps, Linux apps and PC VR games on the **Valve Steam Frame**. FramePort sets up the
-Frame, patches each game so it runs there, uploads it and adds it to your Steam library with artwork.
+Frame, patches each game to run there, uploads the game and adds the game to your Steam library with artwork.

 [![FramePort: library, one-click install, play, monitor](docs/images/tour-teaser.webp)](docs/media/frameport-tour.mp4)

-▶ [Watch the full tour](docs/media/frameport-tour.mp4) · New to FramePort? [Watch the install tutorial](docs/media/frameport-install.mp4)
+▶ [Watch the tour](docs/media/frameport-tour.mp4) · [Watch the install tutorial](docs/media/frameport-install.mp4)
 (about 90 seconds each)

 > **Notice:** FramePort doesn't download, share or unlock games. Use games you got legally, for example from
-> [SideQuest](https://sidequestvr.com/). FramePort downloads published open-source tools (see [Built on](#built-on))
-> and adds its own patches so games run on the Frame.
+> [SideQuest](https://sidequestvr.com/). FramePort downloads published open-source tools ([Built on](#built-on))
+> and adds its own patches.
 >
-> Not every game runs on the Frame: recipes are tested by the community, and some games need Meta's services or
-> hardware the Frame lacks.
+> Not every game runs on the Frame. Some need Meta's services or hardware the Frame lacks.

 ## Features

 ![Library](docs/images/library.png)

 - **Easy setup:** one line in the Frame's terminal. No root, no password. [What it changes](docs/FRAME_SETUP.md).
- **One click per game:** patch, upload, add to Steam with artwork and test that it starts.
- **Recipes:** tested patches and settings for 120+ games; other games get suggested patches, each explained in
-  plain words.
+- **One click per game:** patch, upload, add to Steam with artwork, test that the game starts.
+- **Recipes:** tested patches and settings for hundreds of games. Other games get suggested patches, each explained.
 - **Game settings:** sharpness, refresh rate, controllers, 360° video and mixed reality as simple switches.
 - **More than Quest games:** Android apps in a window, Linux apps, PC VR games and Windows programs.
- **Install links:** "Install with FramePort" buttons on websites ([frameport.app](https://frameport.app) links) open
-  in FramePort.
- **Your Frame from your PC:** Type on Frame (your keyboard on the Frame), Files, Screenshots, Live view (what the
-  headset shows, in your browser) and Monitor (frame rate, temperatures, battery, processes).
- **Your room for mixed reality (experimental):** scan the room in the headset, see it in 3D, clean up the scan and
-  fix furniture, screen and door labels, so mixed-reality games get your room. Try it with
+- **Install links:** "Install with FramePort" buttons on websites open in FramePort.
+- **Your Frame from your PC:** Type on Frame, Files, Screenshots, Live view (what the headset shows) and Monitor
+  (frame rate, temperatures, battery, processes).
+- **Your room for mixed reality (experimental):** scan your room in the headset and fix the scan up in 3D. Try the room with
  [Test Quest MR](https://github.com/spoopyghosty0/TestQuestMR).
 - **Updates itself**, and reports problems without personal data.

-Details for each: [Install and first steps](docs/INSTALL.md).
-
 ![Monitor](docs/images/monitor.png)

 ![Screenshots](docs/images/screenshots.png)
@@ -51,40 +45,36 @@ Details for each: [Install and first steps](docs/INSTALL.md).

 ## Quick start

-1. [Download](https://github.com/spoopyghosty0/frameport/releases/latest) the build for Windows, macOS (Apple
-   Silicon) or Linux (Arch Linux: [AUR package](docs/INSTALL.md)), unpack it and start FramePort.
-2. In FramePort click **Steam Frame → Start setup**. The Frame and your PC must be on the same Wi-Fi (or use a USB
-   cable).
-3. On the Frame open the **SteamVR dashboard → Launch a program → Desktop**, then the app menu → **System →
-   Konsole**, and run:
+1. [Download](https://github.com/spoopyghosty0/frameport/releases/latest) FramePort for Windows, macOS (Apple
+   Silicon) or Linux, unpack the download and start FramePort.
+2. Click **Steam Frame → Start setup**. The Frame and your PC must be on the same Wi-Fi (or use a USB cable).
+3. On the Frame open **SteamVR dashboard → Launch a program → Desktop**, then **app menu → System → Konsole**, and
+   run:

   ```
   curl -fsSL https://frameport.app/s | bash
   ```

-4. Click **Allow** in FramePort when it shows the same 4-digit code as the Frame. Steam restarts once; if it asks to
-   install **Lepton** (Valve's Android runtime), confirm it.
-5. **Add games → Scan a folder…** with your games, open one and click **Install on Frame**. Play it from the Frame's
-   Steam library.
+4. Click **Allow** when FramePort shows the same 4-digit code as the Frame. Steam restarts once. If Steam asks to install
+   **Lepton** (Valve's Android runtime), confirm.
+5. **Add games → Scan a folder…**, open a game and click **Install on Frame**. Play the game from the Frame's Steam library.

-Full guide, firewalls and troubleshooting: [Install and first steps](docs/INSTALL.md). How to lay out game folders:
-[FAQ](docs/FAQ.md).
+Full guide: [Install and first steps](docs/INSTALL.md). Game folders: [FAQ](docs/FAQ.md).

 ## Compatibility

-Tested games use their recipe (the patches and settings that work for them) automatically; for other games FramePort
-suggests patches. See the [list of tested games](docs/GAMES.md). Got a game working? Share its recipe from the game's
-**…** menu: [how](docs/INSTALL.md#share-a-recipe-or-report-a-problem).
+Tested games get their recipe (the patches and settings that work) automatically. Other games get suggested
+patches. See the [tested games](docs/GAMES.md). Got a game working?
+[Share its recipe](docs/INSTALL.md#share-a-recipe-or-report-a-problem).

 ## Compared with other tools

-FrameDrop and Valve's own tools install an app as it is. FramePort differs in four ways:
+FrameDrop and Valve's own tools install an app as it is. FramePort also:

- **Free and open source** (GPL-3.0). FrameDrop is free (donationware) without published source.
- **Quest games that don't run on the Frame as they are** get converted and patched, with a tested recipe for 120+
-  games. The others install the game unchanged.
- **Windows, macOS and Linux.** FrameDrop is for Windows.
- **Wi-Fi or a USB cable**, and no **Pair new host** step.
+- is **free and open source** (GPL-3.0). FrameDrop is free (donationware), without published source.
+- **converts and patches Quest games** that don't run as they are, with tested recipes for hundreds of games.
+- runs on **Windows, macOS and Linux**. FrameDrop is for Windows.
+- connects over **Wi-Fi or a USB cable**, without a **Pair new host** step.

 <details>
 <summary>All differences</summary>
@@ -93,12 +83,12 @@ FrameDrop and Valve's own tools install an app as it is. FramePort differs in fo
 |---|---|---|---|
 | Cost and source code | Free, open source (GPL-3.0) | Free (donationware), source not published | Free, from Valve |
 | Runs on | Windows, macOS, Linux | Windows | Depends on the tool |
-| First connection | One line in the Frame's terminal; it turns on Developer Mode itself. No password | Turn on Developer Mode, then **Pair new host** | Turn on Developer Mode and pair, or use Android's debug tool (adb) |
+| First connection | One line in the Frame's terminal; turns on Developer Mode itself. No password | Turn on Developer Mode, then **Pair new host** | Turn on Developer Mode and pair, or use Android's debug tool (adb) |
 | Wireless or cable | Wi-Fi, the Frame's hotspot or a USB cable | Same Wi-Fi network | Wi-Fi, or adb |
 | Quest games that don't run as they are | Converted and patched for the Frame | Installed as they are | Installed as they are |
-| Knows which patches a game needs | Tested recipes for 120+ games, updated without an app update | Not stated | No |
+| Knows which patches a game needs | Tested recipes for hundreds of games, updated without an app update | Not stated | No |
 | In the Steam library | Yes, with artwork and tags | As a "Devkit Game" shortcut | As "Devkit Game: &lt;title&gt;"; not with adb |
-| Android apps, Linux apps, Windows programs | All three; Proton (runs Windows programs) is installed for you | All three; install Proton first | Yes; 2D Android apps need an extra file |
+| Android apps, Linux apps, Windows programs | All three; Proton is installed for you | All three; install Proton first | Yes; 2D Android apps need an extra file |
 | PC VR games | On your PC; some also on the Frame | Not supported | Not supported |
 | "Install with …" buttons on websites | Yes ([frameport.app](https://frameport.app) links) | Its own | No |
 | A game doesn't start | A launch test reads the logs and suggests a patch | A log viewer | No help |
@@ -106,10 +96,10 @@ FrameDrop and Valve's own tools install an app as it is. FramePort differs in fo

 </details>

-Other tools as described on their own pages, checked 2026-10-09:
+Based on each tool's own pages, checked 2026-10-09:
 [FrameDrop about](https://framedropvr.com/about) · [how-to](https://framedropvr.com/how-to) ·
 [Valve: loading games on Steam Frame](https://partner.steamgames.com/doc/steamhardware/steamframe/loadgames).
-Out of date? [Report a problem](https://github.com/spoopyghosty0/frameport/issues/new).
+Out of date? [Report the problem](https://github.com/spoopyghosty0/frameport/issues/new).

 ## Built on

@@ -124,15 +114,17 @@ What FramePort adds: [Architecture](docs/ARCHITECTURE.md).

 | | |
 |---|---|
-| [Install and first steps](docs/INSTALL.md) | Install, connect, update, PC VR games, files, problem reports |
-| [What the setup changes](docs/FRAME_SETUP.md) | What setup changes on the Frame, networks and firewalls, undoing it |
-| [Compatibility](docs/COMPATIBILITY.md) | What runs and how well |
-| [Tested games](docs/GAMES.md) | Tested games and how well they run |
-| [FAQ](docs/FAQ.md) | Game folders and common questions |
-| [Controller buttons](docs/CONTROLLERS.md) | Quest Touch buttons on the Frame: SteamVR default, Mirror and Quest pair |
-| [Porting playbook](docs/PLAYBOOK.md) | Symptoms and fixes per game |
-| [Steam Frame runtime reference](docs/FRAME_RUNTIME.md) | Facts about the Frame's runtime |
-| [Architecture](docs/ARCHITECTURE.md) | How the code is organized |
+| [Install and first steps](docs/INSTALL.md) | Install, connect, install games, update |
+| [What the setup changes](docs/FRAME_SETUP.md) | Changes on the Frame, firewalls, undoing it |
+| [FAQ](docs/FAQ.md) | Game folders and fixing problems |
+| [Compatibility](docs/COMPATIBILITY.md) · [Tested games](docs/GAMES.md) | What runs, and how well |
+| [Controller buttons](docs/CONTROLLERS.md) | Quest buttons on the Frame's controllers |
+| [Themes](docs/THEMES.md) | Color themes and making your own |
+| [Install button](docs/INSTALL_BUTTON.md) | An "Install with FramePort" button for your download page |
+| [Diagnostics](docs/DIAGNOSTICS.md) | What a problem report contains |
+| [Patch reference](docs/PATCHES.md) | Every patch and game setting |
+| [Porting playbook](docs/PLAYBOOK.md) · [Runtime reference](docs/FRAME_RUNTIME.md) | Symptoms and fixes; facts about the Frame |
+| [Architecture](docs/ARCHITECTURE.md) · [Screenshots and videos](docs/SHOWCASE.md) | How the code and the docs' pictures are made |
 | [Contributing](CONTRIBUTING.md) | Code, recipes, translations |

 ## Development
@@ -1,6 +1,6 @@
 # Third-party notices

-FramePort is GPL-3.0-only (see `LICENSE`). It includes or downloads the following third-party work.
+FramePort is GPL-3.0-only (see `LICENSE`). FramePort includes or downloads the following third-party work.

 ## Included in this repository / the release bundles
 | Component | Where | License |
@@ -25,6 +25,8 @@ FramePort's own native code (the FrameBridge adapter, GL/Vulkan/OpenXR shims, th
 | Eclipse Temurin JRE | api.adoptium.net | GPL-2.0 with Classpath Exception |
 | apksigner (Android build-tools) | dl.google.com Android repository | Apache-2.0 |
 | Revive (portable copy, only if Revive isn't installed) | github.com/LibreVR/Revive releases | GPL-3.0 |
+| Cpp2IL (only for Unity IL2CPP patches) | github.com/SamboyCoding/Cpp2IL releases | MIT |
+| APKEditor (only for app bundles with resource splits) | github.com/REAndroid/APKEditor releases | Apache-2.0 |

 Valve's Lepton, Proton and SteamVR, and Meta's software, are used on your devices as installed by Steam / Meta;
 FramePort doesn't distribute them.
@@ -1,16 +1,18 @@
 # Announcements

-`current.md` is the one announcement FramePort shows as a pop-up in the app. Edit it on `main`: the app reads it
-from GitHub `main` (raw.githubusercontent.com) at most every 6 hours, so a push reaches everyone without a release.
+`current.md` is the one announcement FramePort shows as a pop-up in the app. Edit `current.md` on `main`: the app
+reads the file from GitHub `main` (raw.githubusercontent.com) at most every 6 hours, so a push reaches everyone
+without a release.

 ## Who sees it

- **Only people who already used FramePort before the announcement's `date`.** A new install never shows one, and
-  nor does an announcement published before FramePort was installed.
- **Once.** Closing it in any way (the X, a click outside it, Escape, or its button) dismisses it for good. The app
-  remembers dismissals in its settings (`announce.dismissed`).
- **A new announcement = a new `id`.** Fixing a typo with the same `id` doesn't show it again to anyone who closed it.
-  A new `id` shows to everyone who used FramePort before its `date`, whether they closed the earlier one or not.
+- **Only people who used FramePort before the announcement's `date`.** A new install never shows an announcement,
+  and neither does an announcement published before FramePort was installed.
+- **Once.** Closing the pop-up in any way (the X, a click outside, Escape, or the pop-up's button) dismisses the
+  announcement for good. The app remembers dismissals in its settings (`announce.dismissed`).
+- **A new announcement = a new `id`.** A typo fix with the same `id` doesn't show the announcement again to anyone
+  who closed it. A new `id` shows to everyone who used FramePort before its `date`, whether they closed the earlier
+  announcement or not.

 ## The file

@@ -31,7 +33,7 @@ The body, in Markdown: **bold**, *italic*, `code`, [links](https://frameport.app

 The body is Markdown (no HTML). A `date` in the future works as a schedule: nobody sees it before then.

-Images look best at about 2:1 (e.g. 1200×600). The pop-up is 600 px wide and shows between 140 and 320 px of the
+Images look best at about 2:1 (for example 1200×600). The pop-up is 600 px wide and shows between 140 and 320 px of the
 picture's height.

 `pytest tests/test_announcements.py` checks this file, so a broken announcement fails CI instead of silently showing
@@ -3,7 +3,9 @@
 ![FramePort's modules: the desktop app and the CLI drive pipeline.py (add, suggest, build, install, launch test), which uses sources/, analysis/, recommend/, build.py, targets/ and validate/; builds use patches/ and tools/; targets reach the agent on the Steam Frame through frame/ and install/ over SSH](images/architecture.svg)

 ## Data flow for one game
-1. **Source** (`sources/quest_dump.py`): folder with an APK and optional `<package>/` or `obb/` data.
+1. **Source** (`sources/quest_dump.py`): folder with an APK and optional `<package>/` or `obb/` data; SideQuest
+   backups and AXRB downloads are recognised, app bundles (`.xapk`/`.apks`/`.apkm`/`.apkx`, split APKs) are merged
+   into one APK first (`sources/bundles.py`).
 2. **Analysis** (`analysis/detect.py`): package/label/version (pyaxmlparser), ABIs, engine, XR API, graphics API,
   direct-VrApi, GLAD/eglGetProcAddress, Unity MSAA levels, Meta permissions, telemetry references.
 3. **Recipe** (`recommend/engine.py`): every patch's `detect()` suggests itself with a reason; a catalog entry (exact
@@ -16,37 +18,50 @@
   deployment.json, artwork) → `shortcuts` (detached systemd unit stops Steam, writes shortcuts.vdf + grid art,
   restarts Steam).
 6. **Test** (`validate/device.py`): agent `launch_test` (systemd-run launch.sh, wait, stop) → fetch launch.log →
-   `triage.py` (milestones + signatures → suggested patches) → UI offers "apply suggestions and rebuild".
+   `triage.py` (milestones + signatures → suggested patches) → UI offers "apply suggestions and rebuild". Real play
+   sessions are triaged the same way afterwards (`validate/session.py`, game page "Last session").

 ## Extending
 - **New patch**: `patches/frame/<name>.py` with a `Patch` subclass (`detect`, `apply`, optional `validate`), plus a
  signature in `catalog/triage.yaml` and a PLAYBOOK row. Stages: `overport` | `apk` | `install`.
- **Upstream fixed a bug we work around**: register an `UpstreamFix` (`patches/upstream.py`) in the workaround's
+- **Upstream fixed a bug FramePort works around**: register an `UpstreamFix` (`patches/upstream.py`) in the workaround's
  module: a probe that finds the fix in OVRPort's output (True / False / None = can't tell). Each build runs the probes
  on the converted APK and leaves out the workarounds whose fix is there (log "not needed: …", `build.superseded`,
  left out of settings.conf at install; game page and `frameport show` say so). The recipe keeps asking for the fix,
-  so builds made with an older runtime keep the workaround. `FRAMEPORT_KEEP_WORKAROUNDS=1` turns it off.
- **New heuristic**: put it in the patch's `detect()` (and `applies()` for visibility), with the evidence in the
+  so builds made with an older runtime keep the workaround. `FRAMEPORT_KEEP_WORKAROUNDS=1` turns the probes off.
+- **New heuristic**: put the rule in the patch's `detect()` (and `applies()` for visibility), with the evidence in the
  reason text; check `scripts/eval_heuristics.py` still reproduces the catalog and add a test in
  `tests/test_heuristics.py`.
 - **New game recipe**: `catalog/games/<package>.yaml` (or "Save as known-good" in the GUI, which writes to the user
-  catalog). Publish recipes by serving a folder with `index.json` and pointing `FRAMEPORT_CATALOG_URL` at it.
+  catalog). Installed apps fetch `catalog/games/` from GitHub `main` every 6 hours (`recommend/catalog.refresh_remote`),
+  so a merged recipe reaches users without a release; `catalog/triage.yaml` follows the same way. `FRAMEPORT_CATALOG_URL` points the apps at another folder that
+  serves `index.json` + `<package>.yaml` instead.
 - **New target**: implement `targets/base.Target`; the pipeline and UI only use that interface.

-## Oculus Rift (PC VR) games
-`sources/rift_dump` finds Windows game folders; `analysis/rift` (own PE reader) detects exe, bitness, engine, LibOVR vs
-OpenXR, D3D version and Oculus Platform SDK use; ids are `rift.<slug>`. Their only patches are the `pcvr` category
-(`patches/pcvr.py`: Revive, OpenVR backend, crash reporter, Oculus detection, OpenXR layer, Proton
-log/version/env); `base.for_game` keeps Quest and PC VR patches
-apart. "Build" = `pipeline.prepare_rift` (checks + Revive). Revive is a portable tool (`tools/revive.py` unpacks
-`ReviveInstaller.exe` in pure Python: NSIS header + deflate blocks). Targets:
- `targets/pc_revive.PcReviveTarget`: Windows/WSL (`core/winhost.py`), non-Steam shortcut running
-  `ReviveInjector.exe /openxr <exe>` via the agent's VDF code, grid art, local records in `<user data>/pc/`.
+## PC VR (Oculus Rift and SteamVR) games
+`sources/rift_dump` finds Windows game folders (one game per folder); `analysis/rift` (own PE reader) ranks the
+programs, detects bitness, engine, the VR APIs (LibOVR, OpenVR, OpenXR), D3D version and Oculus Platform SDK use; ids
+are `rift.<slug>`. Their only patches are the `pcvr` category (`patches/pcvr.py`: Revive, OpenVR backend, crash
+reporter, Oculus detection, OpenXR layer, launch arguments, Proton version/env); `base.for_game` keeps Quest and PC
+VR patches apart. Repacks are usually pre-patched, so a game is installed unchanged and its program started
+directly; Revive is only suggested for games with LibOVR code, and those run only on the PC (Revive's hooks don't
+work under Proton on ARM64). "Build" = `pipeline.prepare_rift` (checks, plus Revive when the recipe has it). Revive
+is a portable tool (`tools/revive.py` unpacks `ReviveInstaller.exe` in pure Python: NSIS header + deflate blocks).
+Targets:
+- `targets/pc_revive.PcReviveTarget`: Windows/WSL (`core/winhost.py`), non-Steam shortcut (the game's program, or
+  `ReviveInjector.exe [/openxr] <exe>`; Revive's OpenVR backend by default) via the agent's VDF code, grid art, local
+  records in `<user data>/pc/`.
 - `FrameLeptonTarget.install_pcvr` → `installer.install_pcvr` → agent `prepare_pcvr`/`finalize_pcvr`: upload
-  `game/` + `revive/` (+ `xrlayer/` for `pcvr.xr_timefix`, `helpers/` for `pcvr.oculus_unreal`; size-manifest dedupe,
+  `game/` (+ `revive/`, `xrlayer/` for `pcvr.xr_timefix`, `helpers/` for `pcvr.oculus_unreal`; size-manifest dedupe,
  stale files removed), `launch.sh` running the ARM64 Proton chain (built from toolmanifest.vdf; with
-  `pcvr.oculus_unreal` the injector runs through `helpers/fp_oculushmd.exe`, which provides Unreal's
+  `pcvr.oculus_unreal` the program runs through `helpers/fp_oculushmd.exe`, which provides Unreal's
  `OculusHMDConnected` event); `proton_status`/`install_proton` manage Proton from Valve's ARM64 compat list.
+
+## Linux apps and Windows programs
+`pipeline.add_linux_app` (AppImage, archive or folder; library kind `linux`) and `pipeline.add_windows_exe` add
+programs that are installed unchanged. The agent's `finalize_linux` unpacks them, writes the launcher (arm64 builds
+directly, x86_64 builds through Valve's FEX), a Desktop Mode menu entry and, for SteamVR overlay apps, their
+`.vrmanifest` registration; Windows programs run through Proton like PC VR games.
 - **Native binaries** (`artifacts/`): edit `native/…`, run `python native/build.py`, commit the new artifacts + SHA256SUMS,
  run `frameport parity` to see which games change.

@@ -60,19 +75,20 @@ apart. "Build" = `pipeline.prepare_rift` (checks + Revive). Revive is a portable
  release's wheel).
 - `prepare()` (bundle): `<data>/updates/<ver>/`: download → SHA256SUMS.txt check → extract to `staged/` (ditto on
  macOS) → layout check → on Windows the same Authenticode signer as the running exe → `ready.json`.
- `apply()`: writes `<data>/updates/apply.{ps1,sh}` and starts it detached; FramePort quits. The script waits for the
+- `apply()`: writes `<data>/updates/apply.{ps1,sh}` and starts the script detached; FramePort quits. The script waits for the
  pid. Windows: backs up the files it replaces (`updates/<ver>/previous`) and copies over the folder (the zip has no
  folder of its own). macOS/Linux: `mv` target → `.old`, staged → target, rollback on failure, clears the quarantine.
-  Then it relaunches FramePort. Log: `<data>/logs/update.log`.
+  Then the script relaunches FramePort. Log: `<data>/logs/update.log`.
 GUI: background check 10 s after start + every 6 h → sidebar card + Library bar → dialog with notes → job
 `app-update` (waits for other jobs) → restart. "Install updates automatically": prepare in the background, apply in
 `main()` before the window opens. CLI: once-a-day hint from the cached result (a daemon thread refreshes it), `frameport
 update [--check] [--yes]`. CI runs `scripts/update_smoke.py` on every OS with the archive it just built.

 ## Dynamic data (fetched live, cached, bundled fallback)
-overport CLI release (Android-XR-Bridge/OVRPort, fallback ovrport/app) + patch list + titles, Temurin JRE (Adoptium API), apksigner (Google repository index),
-store artwork/titles (overport image API), catalog (optional remote), Lepton location/appid (Frame appmanifests),
-Steam user (Frame userdata).
+overport CLI release (Android-XR-Bridge/OVRPort, fallback ovrport/app) + patch list + titles, Temurin JRE (Adoptium
+API), apksigner (Google repository index), Cpp2IL and APKEditor (GitHub releases, on first use), store artwork,
+titles and details (overport image API, OculusDB, Steam), catalog recipes and triage signatures (GitHub `main`),
+announcements, Lepton location/appid (Frame appmanifests), Steam user (Frame userdata).

 ## Built on

@@ -1,8 +1,8 @@
 # Compatibility

-FramePort's catalog has a tested recipe (the patches and settings that work) for many games, each marked as working,
-working with issues or not running: see the [list of tested games](GAMES.md). Other games get suggested patches,
-each with its reason. Every patch can be switched on or off under **Customize** on the game's page.
+FramePort has tested recipes (the patches and settings that work) for hundreds of games, each marked as working,
+working with issues or not running: see the [tested games](GAMES.md). Other games get suggested patches, each with
+its reason. **Customize** on a game's page turns any patch on or off.

 Got a game working? [Share its recipe](INSTALL.md#share-a-recipe-or-report-a-problem).

@@ -10,13 +10,14 @@ Got a game working? [Share its recipe](INSTALL.md#share-a-recipe-or-report-a-pro

 | Kind of game | On the Steam Frame |
 |---|---|
-| Quest games | Converted to OpenXR (the VR standard the Frame uses) by OVRPort and patched; they run in Lepton, Valve's Android runtime |
-| 32-bit Gear VR, Oculus Go and early Quest games | Run through FramePort's 32-bit bridge (experimental): it translates the game's 32-bit code inside the app; the Frame's right controller acts as the Gear VR / Go controller |
-| Other Android VR apps using OpenXR (for example Pico builds) | Converted the same way; the other headset's own features and store services aren't available |
-| Android apps without VR | Installed unchanged and shown as a window in the headset |
-| PC VR games | On the Frame through Proton (experimental), or on your PC and streamed to the Frame: see [PC VR games](INSTALL.md#pc-vr-games) |
+| Quest games | Converted to OpenXR (the Frame's VR standard) by OVRPort, patched, and run in Lepton, Valve's Android runtime |
+| 32-bit Gear VR, Oculus Go and early Quest games | Run through FramePort's 32-bit bridge (experimental). The right controller acts as the Gear VR or Go controller |
+| Other Android VR apps using OpenXR (for example Pico builds) | Converted the same way, without the other headset's own features and store services |
+| Android apps without VR | Installed unchanged and shown as a window |
+| PC VR games | On the Frame through Proton (experimental), or on your PC and streamed: see [PC VR games](INSTALL.md#pc-vr-games) |
+| Linux apps | Installed unchanged. x86_64 builds run through FEX, slower than arm64 builds: see [Linux apps](INSTALL.md#linux-apps) |
 | Can't run | x86-only Android apps, apps for Pico's or HTC's own VR system, Android XR apps, and games that check their license through the Oculus app |

-Automatic launch tests show that a game starts; only the headset shows whether it looks right.
+Launch tests show that a game starts. Only the headset shows whether the game looks right.

 ![Steam Frame](images/frame.png)
@@ -1,25 +1,24 @@
 # Controller buttons

-> **Experimental.** The Frame's runtime accepts these bindings, but the modes haven't been tried in the headset on
-> many games yet. If buttons stop working in a game, set it back to **SteamVR default** (Game settings →
-> Controllers) and report it.
+> **Experimental.** The Frame's runtime accepts these bindings, but few games have been tried in the headset. If
+> buttons stop working in a game, set the game back to **SteamVR default** (Game settings → Controllers) and report the problem.

-Quest games usually bind Quest Touch controllers. Steam Frame has a d-pad and View button on the left controller,
-and an A/B/X/Y diamond and Menu button on the right. Without a game's own Frame bindings, SteamVR maps Touch X/A
-to the bottom button and Touch Y/B to all three top buttons. View sends Touch Menu. The right X and Y therefore
-send Touch B, rather than the left-hand X and Y of a Quest controller.
+Quest games expect Quest Touch controllers. The Frame's left controller has a d-pad and a View button; the right one
+has an A/B/X/Y diamond and a Menu button. Without a game's own Frame bindings, SteamVR sends Touch X/A from the bottom
+button and Touch Y/B from all three top buttons, so the right X and Y both send Touch B. View sends Touch Menu.

-**Controller buttons** chooses an alternative for Quest games running through FrameBridge:
+**Controller buttons** offers other mappings for Quest games:

- **SteamVR default (0)** leaves SteamVR's Touch remapping in place. This is the initial default.
- **Mirror (1)** uses every face button. On each controller, bottom and outer send X/A; top and inner send Y/B, as on Quest controllers, whose second button sits up and toward the other hand.
- **Quest pair (2)** uses two face buttons per controller, placed like Touch's: left X = d-pad down, Y = d-pad
-  right; right A = A, B = X. The other face buttons send no Touch input.
+- **SteamVR default (0):** SteamVR's mapping above. The initial default.
+- **Mirror (1):** uses every face button. Bottom and outer send X/A; top and inner send Y/B, as on a Quest
+  controller, whose second button sits up and toward the other hand.
+- **Quest pair (2):** two buttons per controller, placed like Touch's: left X = d-pad down, Y = d-pad right; right
+  A = A, B = X. The other face buttons send nothing.

 ![Quest Touch reference and the three Steam Frame button mappings](images/controllers/quest-buttons.svg)

-The small label identifies the physical button; the larger label is the Touch input the game receives. Blue is
-X/A, orange is Y/B or Menu, and a dash means no Touch input. Left and right refer to the hand holding the controller.
+The small label names the physical button, the large one the Touch input the game gets. Blue is X/A, orange is Y/B
+or Menu, a dash is no input.

 <!-- quest-buttons-table:start -->
 | Frame input | SteamVR default (0) | Mirror (1) | Quest pair (2) |
@@ -38,32 +37,25 @@ X/A, orange is Y/B or Menu, and a dash means no Touch input. Left and right refe
 | Right bumper | — | — | — |
 <!-- quest-buttons-table:end -->

-The table describes button clicks and face-button touches. View sends Menu click only. Triggers, grip pressure,
-thumbsticks, tracked poses and vibration keep their corresponding Touch bindings.
+Triggers, grips, thumbsticks, tracking and vibration keep their Touch bindings. View sends Menu click only.

 ## Choose a mode

-For one game, open its **Game settings → Controllers → Controller buttons**. Choose **Use global default** to
-follow Settings, or select a specific mode to keep an override for that game. An explicit **SteamVR default**
-keeps mode 0 even when the global choice is Mirror or Quest pair.
+- **One game:** **Game settings → Controllers → Controller buttons**. **Use global default** follows Settings; any
+  other choice stays for that game, including an explicit **SteamVR default**.
+- **All games:** **Settings → Controllers**. New installs and updates use the default for games without their own
+  choice.
+  **Apply to installed games now** sends the default to installed Quest games that follow it.

-For the library default, open **Settings → Controllers**. The diagram follows the selected mode. New installs
-and configuration updates use this default for games without an override. With a Frame connected, choose
-**Apply to installed games now** to send it to installed Quest games that follow the global default. Overrides
-are kept. Changing the default does not mark every game as needing an update.
+Changes apply at the **next launch**. Games installed before this feature need **Update on Frame** once.

-Changes take effect at the **next launch**. Close and relaunch a running game.
-Games installed before this feature need **Update on Frame** once for the mode to work.
-
-The CLI can change an installed game's runtime setting:
+Command line, for an installed game (writes the Frame's settings only):

 ```sh
 frameport settings <pkg> quest_buttons=2
 ```

-Use `0` for SteamVR default or `1` for Mirror. This command writes the installed settings directly; it does not
-save a per-game recipe override. To keep the value through later installs and global applies, also save it in
-the recipe, or use Game settings:
+To keep the value through later installs, also save the value in the recipe (or use Game settings):

 ```sh
 frameport recipe <pkg> --set quest_buttons=2
@@ -71,23 +63,18 @@ frameport recipe <pkg> --set quest_buttons=2

 ## Limits

- SteamVR's binding UI can still override these suggested bindings. Check custom bindings if the result differs
-  from the diagram.
- The d-pad has a single touch sensor: a thumb resting on it touches X and Y together. The right controller's
-  face buttons sense touch one by one.
- Bumpers have no Touch counterpart and are unbound. Thumbrest touch is dropped; the Frame profile has no
-  corresponding input. System buttons keep their runtime role.
- Mirror and Quest pair require the Frame runtime's `XR_VALVE_frame_controller_interaction` extension. If it is
-  absent, FrameBridge logs that fact and leaves SteamVR's remap in place.
- Games suggesting their own Frame Controller bindings keep those bindings and continue seeing the Frame
-  Controller profile, even if they also suggest Touch bindings. These modes do not replace the game's own mapping.
- Touch suggestions using bare pose, trigger, squeeze or button paths are translated too; explicit components
-  such as `/pose`, `/value`, `/click` and `/touch` are also supported where the mapping provides them.
- Finger proximity emulation (`proximity_emul`) continues to work with Mirror and Quest pair. Dropping the
-  unsupported thumbrest path does not disable proximity emulation from the other touch inputs.
- The setting applies to Quest VR games, including 32-bit games through the bridge. It does not change PC VR or
-  flat Android Steam Input layouts.
+- Custom bindings in SteamVR's binding UI override these. Check them if the result differs from the diagram.
+- The d-pad has one touch sensor: a thumb resting on the d-pad touches X and Y together. The right face buttons sense touch
+  one by one.
+- Bumpers and thumbrest touch have no Touch counterpart and do nothing. System buttons keep their role.
+- Mirror and Quest pair need the runtime's `XR_VALVE_frame_controller_interaction` extension. Without the extension,
+  FrameBridge logs the fact and keeps SteamVR's mapping.
+- Games with their own Frame Controller bindings keep them; these modes don't replace a game's own mapping.
+- Touch bindings on bare pose, trigger, squeeze or button paths are translated too, as are `/pose`, `/value`,
+  `/click` and `/touch` where the mapping has them.
+- Finger proximity emulation (`proximity_emul`) keeps working with Mirror and Quest pair.
+- Applies to Quest VR games, including 32-bit games on the bridge. PC VR games and flat Android apps aren't changed.

 The mapping follows [Valve's Frame Controller input reference](https://partner.steamgames.com/doc/steamhardware/steamframe/input)
-and the [shared mapping data](input/quest_buttons.json). To regenerate the diagram, app illustrations and table,
-run `uv run python scripts/controller_diagram.py`; add `--check` to verify them without writing files.
+and the [shared mapping data](input/quest_buttons.json). `uv run python scripts/controller_diagram.py` regenerates
+the diagram, app illustrations and table (`--check` verifies them).
@@ -1,19 +1,22 @@
 # Diagnostics and problem reports

-Two ways users feed results back, both without a GitHub token:
+FramePort sends results back in two ways, both without a GitHub account token:

- **Share working recipe…** (game page, recipe card; `frameport share-recipe <pkg>`): saves the recipe as a user catalog entry and
-  opens a prefilled issue from `.github/ISSUE_TEMPLATE/working-config.yml`. A maintainer checks it and adds the label
-  `catalog-accepted`. Then `.github/workflows/catalog-from-issue.yml` runs `scripts/catalog_from_issue.py`, which reads
-  only the YAML block, validates it, and writes `catalog/games/<pkg>.yaml`, and the workflow opens a PR.
-  - The PR step needs Settings → Actions → "Allow GitHub Actions to create and approve pull requests".
-  - Create the labels `working-config`, `catalog-accepted` and `bug` once.
- **Report a problem…** / **Collect logs** (game menu, Settings, the failure pop-up, `frameport diag report|collect`): writes
-  a redacted zip and opens a prefilled `bug-report.yml` issue.
-  - GitHub has no API for issue attachments, so the user drags the zip in (25 MB max; the bundle stays under 24 MB).
-  - Prefilled links are capped at about 7.5k characters. Free text is trimmed first; the recipe is never cut.
+- **Report a problem…** / **Collect logs** (game menu → Troubleshoot, Settings, the failure pop-up,
+  `frameport diag report|collect`) writes a zip of logs with personal data removed ([Redaction](#redaction)) and
+  opens a prefilled issue (`bug-report.yml`). You drag the zip into the issue: GitHub has no API for attachments.
+  The zip stays under GitHub's 25 MB limit and holds no game files.
+- **Share working recipe…** (game menu → Recipe; `frameport share-recipe <pkg>`) saves the recipe as your own catalog
+  entry and opens a prefilled issue (`working-config.yml`).

-Code: `src/frameport/diag/` (`redact.py`, `bundle.py`, `issue.py`), agent command `collect_diag` (agent ≥ 21),
+Prefilled links are capped at about 7.5k characters; free text is trimmed first, the recipe never.
+
+**For maintainers:** labelling a recipe issue `catalog-accepted` runs `.github/workflows/catalog-from-issue.yml`:
+`scripts/catalog_from_issue.py` reads only the YAML block, validates it, writes `catalog/games/<pkg>.yaml` and the
+workflow opens a PR. The workflow needs Settings → Actions → "Allow GitHub Actions to create and approve pull requests" and the
+labels `working-config`, `catalog-accepted` and `bug`.
+
+Code: `src/frameport/diag/` (`redact.py`, `bundle.py`, `issue.py`), agent command `collect_diag`,
 `Target.collect_diag`, `core/applog.py` (app log + saved job logs).

 ## Bundle layout (schema 1)
@@ -41,19 +44,19 @@ games/<pkg>/package/         stand-in for the game files (no content):
 games/<pkg>/target/          from the Frame (or the PC): launch.sh, settings.conf, deployment.json, launch.log,
                             launch-test.log (PC VR), lepton-steamlaunch-<appid>.log, logcat-{main,crash,system,...}.log,
                             ReviveInjector.txt / steam-<appid>.log / game-log-N.txt (PC VR), files.json (+ missing)
-                             stop-pause.log, exit-hook.log, theater.log, dashboard.log, plays.log (agent v122): how
-                             the last session ended (pause before the stop, Steam's Exit game hook; play start/end)
+                             stop-pause.log, exit-hook.log, theater.log, dashboard.log, plays.log: how the last
+                             session ended (pause before the stop, Steam's Exit game hook; play start/end)
                             (game-log-N.txt: Unreal Saved/Logs + crash summaries, Unity Player.log / Player-prev.log /
-                             output_log.txt + crash error.log from the Proton prefix, agent v67)
-                             threads.txt (agent v79): saved while a Quest game runs (e.g. hangs), each thread's
+                             output_log.txt + crash error.log from the Proton prefix)
+                             threads.txt: saved while a Quest game runs (for example a hang): each thread's
                             state, CPU ms over 2 s, kernel wait and syscall, plus its TCP sockets (remote = loopback /
                             local / internet + port, no addresses); read once from /proc, the game isn't paused
-games/<pkg>/target/shaders/  shader dumps (agent v72), when the game wrote any:
+games/<pkg>/target/shaders/  shader dumps, when the game wrote any:
    fp_vk_shaders/           adapter vk_shader_dump=1 (Vulkan shim): <size>_<sha256>.spv + index.txt
    fp_spirv/                adapter zink_shader_dump=1 (OpenGL ES, shader-fix layer under Zink): <size>_<sha256>.spv
 ```
 Each log keeps at most its last 4 MB (2 MB per file from the Frame). Shader dumps, SPIR-V unchanged (compiled game
-shaders, not redacted): Vulkan (agent v74) every module the game's newest run (the last `# start` in `index.txt`)
+shaders, not redacted): Vulkan: every module the game's newest run (the last `# start` in `index.txt`)
 created, last used first, each up to 4 MB and up to 30 MB in all, with that run's index lines, so a module created
 well before a GPU hang comes along too (if the zip would pass 24 MB, the least recently used ones are left out
 after the logs were cut); OpenGL ES (no index): the newest modules (by time written) up to 4 MB.
@@ -62,11 +65,10 @@ after the logs were cut); OpenGL ES (no index): the newest modules (by time writ
 the kernel's `hangcheck detected gpu lockup` line (this-boot-kernel.txt). All modules stay in the game's storage on
 the Frame (`Android/data/<pkg>/files/fp_vk_shaders/`, Files tab → the game's storage).

-Display queries run only while collecting logs. The Windows event query has a five-second timeout and runs without
-a console window; the result distinguishes no matching events from a failed or timed-out query. Window visibility,
-focus and completed move/resize events are recorded in `app.log`, with UTC timestamps for comparison with Windows
-events. There is no display polling loop or change to display settings. Empty System event results do not rule out
-a rendering or monitor-link problem.
+Display queries run only while collecting logs (the Windows event query times out after 5 s and says whether the query
+found nothing or failed). `app.log` records window visibility, focus and move/resize events with UTC times, to
+compare with Windows events. No display polling, no change to display settings. Empty System events don't rule out
+a display problem.

 ## Redaction
 `diag/redact.py` runs on every file and on the issue text.
@@ -79,12 +81,12 @@ a rendering or monitor-link problem.
 - **Kept:** generic accounts that identify no one: `steamos`, `steamuser` (Proton), `root`, `deck`.

 ## Debugging from a bundle (no game, no Frame, no GUI)
-1. `frameport diag inspect <zip>` (`--json` for everything). It prints the versions and warnings, the last launch
+1. `frameport diag inspect <zip>` (`--json` for everything). The command prints the versions and warnings, the last launch
   test, and a fresh triage of the newest launch log with the current `catalog/triage.yaml`.
 2. Match the findings and log lines against `docs/PLAYBOOK.md` (symptom → cause → fix) and `docs/FRAME_RUNTIME.md`.
 3. Check the analysis in `entry.json` (engine, XR API, `extra`: missing ovr symbols, features, Unreal version) and
-   `package/elf.json` against the heuristics in CLAUDE.md. Compare `recipe.yaml` with catalog games that use the same
+   `package/elf.json` against the patches' heuristics (each patch's `detect()`; [HEURISTICS_EVAL.md](HEURISTICS_EVAL.md)). Compare `recipe.yaml` with catalog games that use the same
   engine and API.
 4. Compare `manifest.json → env.frame.build_id` with the build the docs describe: SteamOS updates change the runtime.
 5. A new failure signature means adding a patch module, a `triage.yaml` signature, a PLAYBOOK row and a unit test (see
-   Conventions). Then `diag inspect` on the same zip should report it.
+   [CONTRIBUTING.md](../CONTRIBUTING.md)). Then `diag inspect` on the same zip should report the new signature.
@@ -2,8 +2,8 @@

 ## How should I lay out a game that has OBB files?

-Some Quest games come as an APK (the app file) plus `.obb` files (the game's data). Give every game its own folder,
-put the APK in it and put the data in a folder named after the game's **package name** (for example `com.Armature.VR4`):
+Some Quest games come as an APK (the app) plus `.obb` files (the game's data). Give every game its own folder. Put
+the APK in the game's folder, and the data in a folder named after the game's **package name** (for example `com.Armature.VR4`):

 ```tree
 Games/                                  ← scan this folder (Add games → Scan a folder)
@@ -16,38 +16,35 @@ Games/                                  ← scan this folder (Add games → Scan
    └── com.beatgames.beatsaber.apk     ← games without OBBs: just the APK
 ```

- **Data folder name:** the package name (`com.Armature.VR4` above) or `obb`.
- **Everything in that folder is copied** to the Steam Frame, subfolders included, so other data files work too.
+- **Data folder name:** the package name or `obb`. Everything in the data folder is copied to the Frame,
+  subfolders included.
 - **One game per folder.** Several APKs in one folder count as one game.
- **Scanning:** pick the folder that contains the game folders (`Games/` above) to add them all, or one game's folder
-  to add just that game. FramePort looks up to 5 levels deep.
- **A single game:** **Add games → Add an APK…** also finds the data folder next to the APK.
+- **Scanning:** pick the folder with the game folders to add them all, or one game's folder for one game.
+  FramePort looks up to 5 levels deep. **Add games → Add an APK…** also finds the data folder next to the APK.

-Not sure of the package name? It's in the OBB file names (`main.<version>.<package name>.obb`), and the game's page
-shows it under **Details**.
+The package name is in the OBB file names (`main.<version>.<package name>.obb`) and under **Details** on the game's
+page.

 ## I moved my games to another folder or drive. How do I update the library?

-Scan the new folder (**Add games → Scan a folder…**, or **Settings → Library folders → Add folder…**). A game whose
-files are gone from their old place and that FramePort finds again in the new folder keeps its library entry: only
-where its files are changes. Its name, tags, artwork, your own recipe and what's installed on the Frame stay; you don't
-have to remove it from the library first. **Rescan folders** in the Library does the same for every library folder.
+Scan the new folder (**Add games → Scan a folder…** or **Settings → Library folders → Add folder…**). Games found
+there whose old files are gone keep their library entry: name, tags, artwork, your recipe and the install on the
+Frame stay. **Rescan folders** in the Library checks every library folder
+the same way.

- **Removing a folder:** **Settings → Library folders** lists every folder FramePort scans, with how many library games
-  come from it and whether it's there now (a folder on an unplugged drive shows as not found). The bin icon stops
-  scanning a folder; its games stay in the library. `frameport folders [--add DIR] [--remove DIR]` does the same on the
-  command line, `frameport rescan` rescans.
- **Another version in the new folder** (a different APK or game build): **Scan a folder…** on that folder takes it, as
-  **Update with a newer APK…** would (name, tags, art and your own recipe stay). **Rescan folders** leaves such games
-  alone and says so; use the game's **Update with a newer APK…** / **…version…** to switch.
- **Two copies** (the old folder is still there): the library keeps the copy it has. To use the other one, delete or
-  rename the old copy and rescan.
- PC VR games are recognised by their folder name, or a renamed folder by its program file. Linux apps aren't part of
-  folder scans: add the moved app again with **Add a Linux app…** (it keeps its name, art and switches).
+- **Remove the old folder** in **Settings → Library folders** (bin icon). The folder's games stay in the library.
+- **Another version in the new folder:** **Scan a folder…** takes the new version like **Update with a newer
+  APK…** would.
+  **Rescan folders** leaves such games alone; use the game's **Update** menu to switch.
+- **Both copies still there:** the library keeps the copy it already has. Delete or rename the old
+  copy and rescan.
+- PC VR games are matched by folder name, or by program file if renamed. Linux apps aren't scanned: add the moved app
+  again with **Add a Linux app…** (the app keeps its name, art and switches).
+- Command line: `frameport folders [--add DIR] [--remove DIR]`, `frameport rescan`.

 ## Can I scan SideQuest backups or AXRB downloads directly?

-Yes. Scan the folder as it is; FramePort finds the APK and its OBB files in both layouts:
+Yes. Scan the folder as it is:

 ```tree
 SideQuest Backups/                      ← scan this folder
@@ -71,21 +68,20 @@ AXRB/                                   ← AXRB's download folder (Downloads/AX
 └── patched/                            ← AXRB's own PC builds: ignored
 ```

- **Several backups of one game:** FramePort uses the newest one. To use another, scan just that backup's folder.
- **AXRB's patched builds** (`patched/`, `*-axrb.apk`) are converted for AXRB's PC runtime and lack the game's data, so
-  FramePort skips them and, on the next scan, replaces a game that was added from one with the original download.
- **AXRB export ZIPs:** unpack them first. A game's ZIP holds `base.apk` and `Android/obb/<package>/`, which FramePort
-  finds as is.
- **"Game data (.obb) is missing" on the game's page** although you have the file: the backup didn't include it (copy
-  the game's `Android/obb/<package>` folder from the Quest with SideQuest), or it sits in a folder FramePort doesn't
-  look in. Then use the layout in the previous answer.
+- **Several backups of one game:** FramePort uses the newest. To use another, scan just that backup's folder.
+- **AXRB's patched builds** (`patched/`, `*-axrb.apk`) are made for AXRB's PC runtime and lack the game's data, so
+  FramePort skips them.
+- **AXRB export ZIPs:** unpack them first.
+- **"Game data (.obb) is missing"** although you have the OBB files: the backup didn't include them (copy
+  `Android/obb/<package>` from the Quest with SideQuest), or the files are somewhere FramePort doesn't look. Use the layout in
+  the first answer.
 - **The game starts and stops at once (Steam shows Resume):** add the game again from its original download or
-  backup, click **Update on Frame**, then report it (last answer on this page) if it still stops.
+  backup, click **Update on Frame**, and report the problem if the game still stops.

 ## Can I add .xapk, .apks, .apkm or .apkx files (app bundles)?

-Yes. Add them like an APK: **Add an APK…**, drag them onto the Library, scan a folder that holds them, an install
-link that points at one, or `frameport scan <file>`. These formats are supported:
+Yes. Add them like an APK: **Add an APK…**, drag them onto the Library, scan a folder, use an install link, or
+`frameport scan <file>`.

 | File | Made by | Inside |
 |---|---|---|
@@ -95,188 +91,157 @@ link that points at one, or `frameport scan <file>`. These formats are supported
 | `.apkx` | various | the same kind of zip under another name |
 | a folder of split APKs | `adb pull` of `pm path`, unpacked bundles | `base.apk` + `split_config.arm64_v8a.apk` … |

- Your file isn't changed. FramePort unpacks it once into its own data folder (`bundles/`). Removing the game from the
-  Library deletes that copy.
- The Frame installs one APK per game, so FramePort merges the parts into one APK. It uses the 64-bit ARM part
-  (`arm64_v8a`) and leaves out the x86 and 32-bit parts. If a bundle only has a 32-bit part, it uses that one.
-  Language and screen-density parts are merged with [APKEditor](https://github.com/REAndroid/APKEditor), which
-  FramePort downloads the first time it needs it.
- OBB files in the bundle (`Android/obb/<package>/`), or in an `obb/` or `<package>` folder next to it, are sent to the
-  Frame like a normal game's data.
- A merged APK has no signature from the original publisher. FramePort signs it with the game's own key, like every
-  build. A game that checks its own signature may refuse to run.
- **"is a protected APKMirror bundle":** older `.apkm` files are encrypted for APKMirror's own installer app, and
-  FramePort can't open them. Download the app from APKMirror again (current `.apkm` files are plain zips), or get it
-  as an `.apk` or `.xapk`.
- A bundle needs about twice its size in free space while it's unpacked.
+- FramePort merges the parts into one APK (the Frame installs one APK per game), in FramePort's data folder
+  (`bundles/`). Your file isn't changed. FramePort takes the 64-bit ARM part, else the 32-bit one. Language and screen
+  parts are merged with [APKEditor](https://github.com/REAndroid/APKEditor), downloaded on first use.
+- OBB files in the bundle, or in an `obb/` or `<package>` folder next to the bundle, are sent like a normal game's data.
+- The merged APK is signed with the game's own key, like every build. A game that checks its own signature may
+  refuse to run.
+- **"is a protected APKMirror bundle":** older `.apkm` files are encrypted for APKMirror's installer. Download the
+  app again (current `.apkm` files work), or get an `.apk` or `.xapk`.
+- Unpacking needs about twice the bundle's size in free space.

 ## Where are a game's settings in FramePort?

-Every game has three places; the answers below refer to them.
+- **Game settings:** right-click the game → **Game settings…**. Render resolution, refresh rate, controllers, menus
+  and more. Changes apply at the next start.
+- **Patches:** open the game's page → **Customize** (next to **What FramePort will do**). Turn a patch on or off,
+  then click **Update on Frame**.
+- **The game's menu:** right-click the game, or **…** on the game's page. Groups: **Update**, **On the Frame**, **Saves**,
+  **Name and artwork**, **Recipe** (**Reset to suggested recipe…**, **Share working recipe…**) and **Troubleshoot**
+  (**Report a problem…**).

- **Game settings:** right-click the game in the **Library** → **Game settings…**. Render resolution (supersampling), refresh rate,
-  controllers, menus and more, in plain words. Changes apply the next time the game starts.
- **Patches:** click the game in the **Library** to open its page, then **Customize** (in the **Patches** section).
-  Turn a patch on or off, then click **Update on Frame** at the top of the page.
- **The game's menu:** right-click the game in the **Library**, or the **…** button at the top of its page. Its
-  groups open to the side: **Update**, **On the Frame**, **Saves**, **Name and artwork**, **Recipe** (with **Reset to
-  suggested recipe…**) and **Troubleshoot** (with **Report a problem…**). The arrow keys, Enter and Esc work too.
- **The recipe:** **Reset to suggested recipe…**, **Save as known-good recipe** and **Share working recipe…** are also
-  under **What FramePort will do** on the game's page.
-
-The sidebar has two tabs for troubleshooting: **Monitor** (the running game's frame rate, CPU and graphics) and
-**Files** (each installed game's storage on the Frame, under **Game storage**). Quest games expose their Android
-storage; PC VR and Linux games expose their install folders, including installations on another drive.
-SD cards, USB drives and other Steam library drives appear under **Drives**, with free space when available.
-Read-only drives can be browsed and downloaded from, but cannot be changed.
+For troubleshooting, the sidebar has **Monitor** (frame rate, CPU, graphics) and **Files** (each game's files on the
+Frame under **Game storage**; microSD cards and other drives under **Drives**).

 ## A game doesn't work right. Where do I start?

-1. **Update FramePort** (it offers updates itself; Settings → Updates), then open the game's page: if it shows
-   **Update on Frame**, click it. Recipes and patches improve often.
-2. **Read the game's page.** The last launch test and your last play session (**Last session**) leave their result
-   there, often with a suggested patch or setting and a button that applies it. Try that first.
-3. **Changed patches yourself?** **Reset to suggested recipe…** (on the game's page, under **What FramePort will
-   do**) brings back the tested ones.
-4. **Find your symptom below.** Each answer says how to tell what's wrong and what to do.
-5. **Still stuck?** Report it (last answer on this page).
+1. **Update FramePort**, then open the game's page. If the page shows **Update on Frame**, click **Update on Frame**.
+2. **Read the game's page.** The last launch test and **Last session** often suggest a patch or setting, with a
+   button that applies the suggestion. Try the suggestion first.
+3. **Changed patches yourself?** **Recipe → Reset to suggested recipe…** brings back the tested ones.
+4. **Find your symptom below.**
+5. **Still stuck?** [Report the problem](#how-do-i-report-a-problem-well).

 ## The game doesn't start, or stops right away

-How to tell: the game's page shows the last launch test's result (**Last launch test:** …) with an explanation, and
-Steam returns to **Play** or **Resume** within seconds.
+The game's page shows the last launch test's result with an explanation.

- **"Game data (.obb) is missing"** on the game's page: FramePort didn't find the game's data files, so they never
-  reached the Frame.
-  1. Find the game's `.obb` files (named like `main.<version>.<package>.obb`).
-  2. Put them in a folder named exactly the package name (shown in the file names) next to the game's APK, as in the
-     first answer on this page.
-  3. Library → **Add games** → **Scan a folder…** and pick the game's folder.
-  4. Open the game's page and click **Update on Frame**.
- **"Lepton didn't start the game this time"**, or it failed only on the first start after an install: click **Play**
-  again.
- **"This game is 32-bit only"**: the Frame can't run 32-bit apps, and no patch changes that. Look for a PC VR version
-  of the game.
- **"The game quit itself right after starting"**: open the game's page and click **Update on Frame** so the suggested
-  patches apply (many games check for a Quest at start, and a patch removes that).
- **Nothing like that, or it still fails:** report it.
+- **"Game data (.obb) is missing":** the data files never reached the Frame.
+  1. Find the game's `.obb` files (`main.<version>.<package>.obb`).
+  2. Put them in a folder named exactly the package name, next to the APK ([layout](#how-should-i-lay-out-a-game-that-has-obb-files)).
+  3. **Add games → Scan a folder…** and pick the game's folder.
+  4. Click **Update on Frame**.
+- **"Lepton didn't start the game this time":** click **Play** again.
+- **32-bit-only APK:** the Frame has no 32-bit support. FramePort's 32-bit bridge (experimental) is suggested; if the
+  game still doesn't run, look for a PC VR version.
+- **"The game quit itself right after starting":** click **Update on Frame** so the suggested patches apply.
+- **Anything else:** report the problem.

-## It hangs on a logo, a black screen or a loading screen
+## The game hangs on a logo, a black screen or a loading screen

-How to tell what it's doing: leave it running and open **Monitor** in FramePort's sidebar.
+Leave the game running and open **Monitor**.

- **CPU or graphics busy:** it's still working, often preparing its shaders on the first start. Wait up to 10 minutes
-  once; the next start is quicker.
- **CPU and graphics near zero:** it's stuck waiting for something. While it still hangs, open the game's menu →
-  **Report a problem…** and save the diagnostics: that zip shows what each of the game's threads waits for (FramePort
-  1.0.1 and newer), which a zip saved after quitting can't. Attach it to the report.
- **The game starts with a video** and hangs at its logo: game page → **Customize** → turn off **Hardware video
-  decoding** → **Update on Frame**, and try again.
+- **CPU or graphics busy:** the game is still working, often preparing shaders on the first start. Wait up to 10 minutes
+  once; later starts are quicker.
+- **CPU and graphics near zero:** the game is stuck. **While the game still hangs**, use **Troubleshoot → Report a problem…**: the
+  zip then shows what the game waits for.
+- **The game starts with a video** and hangs at its logo: **Customize** → turn off **Hardware video decoding** →
+  **Update on Frame**.

 ## The picture is wrong

-Most picture problems have a setting or a patch. Change one thing at a time, then start the game again (patches also
-need **Update on Frame**).
+Change one thing at a time, then start the game again (patches also need **Update on Frame**).

 | You see | Try |
 |---|---|
-| Something shows in one eye only, or one eye is gray (Unity games) | Game page → **Customize** → [Unity: render each eye separately](PATCHES.md#frame-unity_multipass) |
+| Something shows in one eye only, or one eye is gray (Unity games) | **Customize** → [Unity: render each eye separately](PATCHES.md#frame-unity_multipass) |
 | Left and right look swapped (depth feels wrong) | **Game settings…** → **Swap eyes** |
 | Textures flicker, objects pop in and out | **Game settings…** → **Turn off space warp** |
-| One eye shimmers while menus look steady | Game page → **Customize** → **Eye-tracked foveation (Valve)**: **Fixed**, else **Off** |
+| One eye shimmers while menus look steady | **Game settings…** → **Foveated rendering (Valve)**: **Fixed**, else **Off** |
 | Menus or screens upside down | **Game settings…** → **Fix upside-down menus** |
 | Curved menus or video screens missing | **Game settings…** → **Show curved menus and screens** |
 | Blurry | **Game settings…** → raise **Render resolution (supersampling)** (costs frame rate) |

-The [patch reference](PATCHES.md) lists every patch with what it does. If nothing helps, report it with a short
-description of what you see.
+Every patch is in the [patch reference](PATCHES.md). Nothing helps? Report the problem and describe what you see.

-## It stutters or runs slowly
+## The game stutters or runs slowly

-How to tell: open **Monitor** in the sidebar while you play. Smooth play needs the game's frame rate at the refresh
-rate (for example 72 or 90 fps).
+Open **Monitor** while you play. Smooth play needs the frame rate at the refresh rate (for example 72 or 90 fps).

- **Below the refresh rate:** right-click the game → **Game settings…** → lower **Render resolution (supersampling)** (for example to 0.8×) or
-  pick a lower **Refresh rate**. After a session, the game's page may suggest a value.
- **At the refresh rate but it still judders:** report it; that points to timing, not speed.
+- **Below the refresh rate:** **Game settings…** → lower **Render resolution (supersampling)** (for example to 0.8×) or the
+  **Refresh rate**. After a session, the game's page may suggest a value.
+- **At the refresh rate, but the game still judders:** report the problem.

 ## The game pauses or recenters by itself

-The Frame briefly tells games they lost focus, for example when the headset's sensor thinks you took it off.
-Right-click the game → **Game settings…**: keep **Don't pause on short interruptions** on and raise **Ignore focus
-dips up to** (for example to 2.5 s).
+The Frame briefly tells games they lost focus, for example when the headset's sensor thinks you took the headset off.
+**Game settings…**: keep **Don't pause on short interruptions** on and raise **Ignore focus dips up to** (for example
+to 2.5 s).

 ## Controllers don't work in a game

-Right-click the game → **Game settings…**:
+In **Game settings…**:

 - **No controllers, or only hands:** turn on **Use controllers**.
- **Buttons work but you can't aim at menus:** adjust **Pointer angle**.
+- **Can't aim at menus:** adjust **Pointer angle**.
 - **Vibration too strong:** lower **Vibration strength**.
+- **Buttons repeat or do the wrong thing:** **Controller buttons** → **Mirror** or **Quest pair**
+  ([Controller buttons](CONTROLLERS.md)).

 ## The Frame turns off or gets hot during a game

-How to tell: if it only happens on battery and never while plugged in, it's power, not FramePort. Heavy games can
-draw more than the battery delivers, especially at lower charge, and the Frame then turns off without an error.
+Only on battery, never plugged in? The cause is power, not FramePort: heavy games can draw more than the battery delivers.

- Play plugged in, or right-click the game → **Game settings…** → lower **Render resolution (supersampling)** to reduce the load.
- It also turns off while plugged in: report it. The diagnostics include the log of the boot that ended.
+- Play plugged in, or lower **Render resolution (supersampling)** in **Game settings…**.
+- The Frame also turns off while plugged in: report the problem.

 ## My progress isn't saved

-1. Quit through the game's own menu, not Steam's **Exit game**. Exit game closes the game at once, and some games only
-   save when they exit normally.
-2. Check whether it saves at all: **Files** in the sidebar → under **Game storage**, the game → look at the files'
-   dates. Play, save in the game, quit from its menu and look again.
-3. Nothing changes: report it.
+1. Quit through the game's own menu. Most games save when Steam's **Exit game** pauses them, but some only save when
+   you quit them yourself.
+2. Check that the game saves at all: **Files** → **Game storage** → the game → look at the files' dates. Play, save, quit
+   and look again.
+3. Nothing changes: report the problem.

 Saves stay on the Frame when you update or reinstall a game.

 ## Can I back up a game's saves?

-Yes. Steam doesn't sync Quest games' saves, so FramePort copies them to your PC: **Back up saves** next to Play on
-the installed game's page, or **Back up all saves** on the Steam Frame page (Installed games). Close the game
-first. A backup holds the game's own storage (`/data/data/<package>` and `/sdcard/Android/data/<package>`), without
-caches, shader caches and large downloaded content (videos, OBBs, files over 64 MB); the job says when something was
-left out. FramePort keeps the 10 newest backups per game (Settings → Data). They're in FramePort's data folder under
-`save-backups/<package>/` (**Open backups folder** in the game's menu).
+Yes. Steam doesn't sync Quest games' saves, so FramePort copies them to your PC. Close the game first, then use
+**Back up saves** next to **Play**, or **Back up all saves** on the Steam Frame page. Caches and large downloaded
+content (videos, OBBs, files over 64 MB) are left out.

-In **Settings → Data**, **Choose backup folder…** selects a different folder, including a local Drive or Nextcloud
-sync folder. FramePort checks that it can write there. **Use the default** resets the location. Existing backups stay
-where they are and remain listed for restoring; retention only removes old backups in the currently selected folder.
-FramePort writes local files; your cloud client handles uploading them.
+- **Where:** `save-backups/<package>/` in FramePort's data folder (**Saves → Open backups folder**). Settings →
+  **Data** → **Choose backup folder…** picks another, for example a cloud-sync folder. Older backups stay restorable.
+- **How many:** the 10 newest per game by default (Settings → Data).
+- **Automatically:** **Back up saves when a game closes** (Settings → Data, off by default). The Frame keeps 3
+  snapshots per game, even while FramePort is closed; FramePort copies the snapshots over when FramePort
+  connects. Connect once after turning the setting on.
+- **Restore:** **Saves → Restore saves…**. **Undo last restore** in the same window takes you back. Uninstalling a
+  game with *Also delete its saves* backs them up first.

-**Back up saves when a game closes** (Settings → Data, off by default) keeps the newest three changed snapshots per
-game on the Frame, even while FramePort is closed. Connect once after changing this setting to apply it to the Frame.
-New snapshots are copied to your backup folder when FramePort connects or polls the connection, marked **automatic**,
-and count toward the same backup limit. Unchanged saves are skipped. A snapshot captures what the game wrote to disk;
-it cannot recover progress a forcibly closed game never saved.
-
-**Restore saves…** puts one back: it replaces the game's saves on the Frame. The Frame keeps a copy of the saves it
-had, so **Undo last restore** in the same window takes you back. When you uninstall a game and tick *Also delete its
-saves*, FramePort backs them up first. Command line: `frameport saves backup|list|restore|undo <game>`.
+Command line: `frameport saves backup|list|restore|undo <game>`.

 ## A game with mods crashes

-How to tell: play once without mods and custom content. If it then works, a mod is the cause; the diagnostics zip
-usually names the mod's library in the crash. Report it to the mod's author, and check for a mod version that matches
-your game version.
+Play once without mods. If the game then works, a mod is the cause (the diagnostics zip usually names the mod).
+Report the crash to the mod's author, and check for a mod version that matches your game version.

 ## The game needs files I supply (ports, emulators, mods)

-How to tell where they go: the game says it on screen or in its instructions, and its log names the path (in the
-diagnostics zip, `launch.log`). It's usually `Android/data/<package>/files`.
+The game's instructions say where; the place is usually `Android/data/<package>/files` (the game's `launch.log`
+names the path).

-1. Unpack or extract the files on your PC first: these apps read folders, not disc images (`.iso`) or archives.
-2. **Files** in the sidebar → under **Game storage**, the game → open that folder → **Upload folder…** (or
-   **Upload files…**). The game's menu → **Add videos and files** opens the same place.
+1. Unpack the files on your PC first: these apps read folders, not disc images (`.iso`) or archives.
+2. **Files** → **Game storage** → the game → that folder → **Upload folder…** or **Upload files…**.

-In-game "choose a file" buttons don't work on the Frame, which has no file picker.
+In-game "choose a file" buttons don't work: the Frame has no file picker.

 ## How do I report a problem well?

-1. Reproduce it once, then right away open the game's menu (**…** on its page) → **Report a problem…**. For a hang,
-   do it while the game still hangs.
-2. Say what you saw in the headset and what you already tried.
-3. **Collect and open GitHub** saves a diagnostics zip and opens a prefilled game report; attach the zip to it. The
-   zip holds logs, not your game files, and personal details are removed.
+1. Reproduce the problem, then right away use **Troubleshoot → Report a problem…** in the game's menu. For a hang,
+   report while the game still hangs.
+2. Say what you saw in the headset and what you tried.
+3. **Collect and open GitHub** saves a diagnostics zip and opens a prefilled report: attach the zip. The zip holds logs,
+   not your game files, and personal details are removed.
@@ -1,16 +1,20 @@
-# Steam Frame runtime reference (SteamOS 0.3.0, build 20260922)
+# Steam Frame runtime reference

-## Setup from the project page (checked 2026-10-10, dev Frame, SteamOS build 20260922)
+Facts about the Steam Frame's runtime that FramePort relies on, checked on the device from SteamOS 0.3.0 (build
+20260922) onwards; each section says when and on which version where it matters. Symptoms and fixes per game are in
+[PLAYBOOK.md](PLAYBOOK.md), longer investigations in [DEVICE_NOTES.md](DEVICE_NOTES.md).
+
+## Setup from the project page (checked 2026-10-10, SteamOS build 20260922)

 - Factory Frames have no browser; Steam's taskbar **+** offers Chromium as a Flatpak (`org.chromium.Chromium`,
-  flathub is configured as a system remote). It is the default handler for https links once installed.
+  flathub is configured as a system remote). Chromium is the default handler for https links once installed.
 - Desktop Mode has `curl`, `wget`, `python3` 3.12, `konsole`, `kdialog`, `xdg-open`, `avahi-browse`, `systemd-run`;
  no `wl-copy`/`xclip`.
 - avahi-daemon runs, but `avahi-browse` from an SSH session fails ("Daemon not running": no system D-Bus access
  there). A stdlib-Python mDNS query works when it listens on port 5353 in the 224.0.0.251 group (like avahi):
  replies to a random source port are dropped by the Frame's firewall. `bootstrap/setup.sh` does exactly that.
- The Frame reaches the PC's port 8765 over the home Wi-Fi without any firewall change on the PC side here (WSL in
-  mirrored mode with the earlier FramePort rule state). The PC is also visible through the Frame's hotspot
+- The Frame reaches the PC's port 8765 over home Wi-Fi without a firewall change on the PC (tested with WSL in
+  mirrored mode). The PC is also visible through the Frame's hotspot
  (`wlanap`, 10.35.78.x): the script lists one PC once, by name and words.
 - Dolphin's "executable scripts" setting is the default (ask); `.sh` files open with a `bash.desktop` handler that
  runs them in a terminal. Not used by the setup (a pasted line is simpler and needs no download prompt).
@@ -40,13 +44,13 @@
  game path in Steam's UI (the in-headset frame menu, Quick Access, "exit the running game?" dialogs) is
  `SteamClient.Apps.TerminateApp(gameid, false)` in SharedJSContext's code (the menus are popups without scripts of
  their own; each popup window has its own `SteamClient` object, unused), and `SteamClient.Apps.TerminateApp` is a
-  writable property there. FramePort hooks it while a game runs (agent v121 `_exit_hook`, DEVICE_NOTES "Graceful
+  writable property there. FramePort hooks it while a game runs (launch.sh's `_exit_hook`, DEVICE_NOTES "Graceful
  stop"). CDP `Runtime.addBinding` works on Steam's CEF (calls arrive as `Runtime.bindingCalled` on the connection
  that added it; the function stays on the page after that connection closes, calls then go nowhere).
 - 64-bit only (no AArch32): 32-bit-only APKs run through FramePort's a32 bridge (`frame.a32_bridge`).
 - `<install>/lepton-shaders/` holds Mesa's shader cache (Lepton sets `mesa.shader.cache.dir=/data/shaders`):
  `foz_cache.foz` + `foz_cache_idx.foz` per graphics driver (Turnip Vulkan, zink GL), typically 4–6 files and 7–19 MB
-  per game, 2D apps included. It speeds up later starts; deleting it only costs one slower start.
+  per game, 2D apps included. The cache speeds up later starts; deleting the cache only costs one slower start.
 - **2D apps** (verified 2026-10-02 with an open-source 2048 game): Lepton runs every app headless
  (`lepton.headless=true`; only OpenXR output reaches the headset) unless the app folder (`STEAM_COMPAT_INSTALL_PATH`)
  contains a file `lepton-show-flatscreen` (`liblepton/app_metadata.sh`): then Android (11, Waydroid) gets a Wayland
@@ -70,7 +74,7 @@
  changes when the files move.
 - The game's files (`lepton-app/`, `lepton-data/` = saves, `lepton-shaders/`, `settings.conf`, `launch.log`; PC VR:
  `game/`, `revive/`, `compatdata/` = Proton prefix; Linux: `app/`) live in `deployment.json["base"]`: the anchor
-  itself on internal storage, or `<mount>/FramePort/<pkg>` on another drive (GitHub #90, agent v63).
+  itself on internal storage, or `<mount>/FramePort/<pkg>` on another drive (GitHub #90).
 - SteamOS mounts removable drives (microSD) under `/run/media/<user>/<label or uuid>`; the agent's `drives` reads
  `/proc/mounts` (plus the drives of Steam library folders) and refuses vfat/exfat/ntfs (Lepton's data and Proton
  prefixes need Unix owners, permissions and symlinks) and read-only mounts. A drive that isn't mounted is an error for
@@ -83,21 +87,6 @@

 ## Room data

-Live floor coverage (agent v104) is enabled by default for manual and game-requested scans; the capture
-payload accepts `preview: false`, and `frameport frame room scan --no-preview` disables it. A world-locked,
-upward-facing 6 m square at floor height follows the current raw-to-STAGE calibration and stays centred on the
-scan's first recorded camera position. Every 16th depth vertex contributes to raw-space 10 cm voxels; at most once
-per second, newly occupied cells redraw a 256×256 RGBA map in one colour (FramePort's secondary blue), each cell a
-filled 10 cm square, only the opacity telling floor (<0.3 m, faint), raised surfaces (0.3–1.5 m) and tall surfaces
-(>1.5 m, strongest, the room's outline) apart; unseen transparent. Overlays have no depth (they draw over hands and
-passthrough), so the map stays faint; three colours in 3x3 blotches clashed in the owner's first run. It shows
-coverage, not a validated room boundary. IVROverlay_028 slots 1/3/20/22/33/43/62 (OpenVR 2.15.6 header)
-create/destroy/sort order (1, below the scan prompts' 10)/set width/set absolute STAGE transform/show/upload raw
-pixels. Each upload is 256 KiB (at most 256 KiB/s); timing for the first
-20 uploads and every tenth thereafter, plus failures, goes to `rooms/scans/scan-*.fprs.log` and the built room’s `scan.log`. Overlay errors or an
-upload taking over 50 ms disable the preview while capture continues; headset appearance and upload cost still
-need device validation.
-
 - SteamVR on the Frame has no Meta scene/anchor extensions. Its chaperone supplies only a 2D outline raised to
  2.43 m, without furniture, ceiling or a room mesh. Valve's default boundary is a 20-point circle of roughly 1 m
  radius; FramePort refuses to treat it as a room.
@@ -115,20 +104,37 @@ need device validation.
  `dirname($FRAMEBRIDGE_CONFIG)/room.txt`. Stale copies are removed if no room exists or emulation is disabled.
  Each game's persistent anchors stay in `/sdcard/Android/data/<pkg>/files/framebridge-anchors.txt`.
 - With `scene_emul`, launch.sh starts `_scan_watch <pkg>` after Lepton, closing fd 9; its exit trap stops the
-  watcher, which also exits if the launcher disappears. It polls once a second and logs to `<base>/scan-watch.log`.
+  watcher, which also exits if the launcher disappears. The watcher polls once a second and logs to `<base>/scan-watch.log`.
  In `<base>/lepton-data/external/Android/data/<pkg>/files/`, FrameBridge writes `framebridge-scan-request`
  (`request <id> <unix_seconds>`); the watcher clears stale request/ack/result files at startup, writes
  `framebridge-scan-ack` (`ack <id>`), reuses the headset capture/build worker, stores the current room and copies
  it beside settings.conf before atomically writing `framebridge-scan-result` (`ok <id>` or `failed <id> <reason>`).
  A global `rooms/.scan.lock` excludes concurrent captures, including manual scans; `rooms/.lock` still protects
  room publication. Launcher exit cancels the scan; a 350-second deadline leaves time for the six-minute protocol timeout.
- Frame → Room and `frameport frame room` manage rooms. `from-boundary` creates walls without furniture;
+- The Room tab and `frameport frame room` manage rooms. `from-boundary` creates walls without furniture;
  `import` / `export` transfer room files; `show` writes an SVG preview; `build <dump.fprs>` syncs the bundled
  `fp_roomscan` by SHA-256 and runs it on the Frame with `--offline`. `scan` = agent `room_capture`: records the
  RoomView meshes (`/xrservice/roomview3d/meshData` + `/meshLayout`, `IVRBlockQueue_005`) while in-headset prompts
  guide the player, then builds the room from that recording.

-## Save backups (Quest games, agent v101, discussion #352)
+### Scan preview
+
+Live floor coverage is shown by default for manual and game-requested scans; the capture
+payload accepts `preview: false`, and `frameport frame room scan --no-preview` disables it. A world-locked,
+upward-facing 6 m square at floor height follows the current raw-to-STAGE calibration and stays centred on the
+scan's first recorded camera position. Every 16th depth vertex contributes to raw-space 10 cm voxels; at most once
+per second, newly occupied cells redraw a 256×256 RGBA map in one colour (FramePort's secondary blue), each cell a
+filled 10 cm square, only the opacity telling floor (<0.3 m, faint), raised surfaces (0.3–1.5 m) and tall surfaces
+(>1.5 m, strongest, the room's outline) apart; unseen transparent. Overlays have no depth (they draw over hands and
+passthrough), so the map stays faint; three colours in 3x3 blotches clashed in the first headset test. The map shows
+coverage, not a validated room boundary. IVROverlay_028 slots 1/3/20/22/33/43/62 (OpenVR 2.15.6 header)
+create/destroy/sort order (1, below the scan prompts' 10)/set width/set absolute STAGE transform/show/upload raw
+pixels. Each upload is 256 KiB (at most 256 KiB/s); timing for the first
+20 uploads and every tenth thereafter, plus failures, goes to `rooms/scans/scan-*.fprs.log` and the built room’s `scan.log`. Overlay errors or an
+upload taking over 50 ms disable the preview while capture continues; headset appearance and upload cost still
+need device validation.
+
+## Save backups (Quest games, discussion #352)
 - A Lepton game's saves are two folders of `<base>/lepton-data`: `internal/<pkg>` (= `/data/data/<pkg>`:
  `shared_prefs/`, `files/`, `databases/`; Unreal's `files/UE4Game|UnrealGame/.../Saved` often lives here) and
  `external/Android/data/<pkg>` (= `/sdcard/Android/data/<pkg>`: Unity's `files/`, Unreal's external `Saved`). On the
@@ -140,7 +146,7 @@ need device validation.
  exec channel's stdout, the result JSON on stderr. Left out: folders named cache/code_cache/no_backup/il2cpp/
  UnityShaderCache/(Vulkan)ProgramBinaryCache/GPUCache/… at any depth, Unreal `Saved/Logs|Crashes`, FrameBridge's
  `fb_snap_*`/`framebridge*` files, `.obb/.apk/.foz/.mp4/.mkv/.webm/.mov`, symlinks and special files, and files over
-  64 MiB (big downloaded content; e.g. BattleTalent's `files/Video`). More than 4 GiB of saves is refused.
+  64 MiB (big downloaded content; for example BattleTalent's `files/Video`). More than 4 GiB of saves is refused.
 - `_restore_saves '<json>'` reads the archive from stdin and treats it as untrusted: only regular files and folders
  under `internal/`/`external/` (no `..`, absolute paths, links, devices, duplicates), ≤1 GiB per file / 8 GiB in all,
  each file's sha256 must match the manifest, the manifest's package must be the game. Everything is staged in
@@ -169,7 +175,7 @@ need device validation.
  (archive stdout, result JSON stderr). PC `install/saves.sync_snapshots` runs in the background, verifies the archive
  hash and package, imports it as a normal backup marked `automatic`, and applies `saves.keep`. A local
  `<data>/save-snapshots-synced.json` digest ledger prevents reimporting snapshots after pruning or deleting backups.
-  Failures leave snapshots on the Frame for the next poll. This path does no disk/SSH work in rendering.
+  Failures leave snapshots on the Frame for the next poll. The snapshot sync does no disk/SSH work in rendering.

 ## OpenXR runtime (as seen by games through overport's loader)
 - Instance extensions present include KHR_android_create_instance (must be enabled; the adapter adds it),
@@ -184,7 +190,7 @@ need device validation.
 - Layer types (checked 2026-09-30 in `/opt/steamvr/bin/androidarm64/vrclient.so`, the Android-side runtime Lepton
  mounts at `/data/steamvr/runtime`): its compositors (`CSxrCompositorPrism`, `CSxrCompositorOpenVR`) only have
  `ComposeLayerQuad` and `ComposeLayerProjection`; cube/cylinder/equirect/equirect2 exist only as enum names, so
-  there is nothing to switch on. It has a layer limit ("Exceeded the layer limit"; the value is logged by
+  there is nothing to switch on. The runtime has a layer limit ("Exceeded the layer limit"; the value is logged by
  `layer_debug` from `maxLayerCount`). The adapter emulates cylinders (strips) and, per game, equirect layers
  (`equirect_emul`, an adapter projection layer). Refused cube swapchains use GLES/Vulkan stand-ins;
  `cube_quads` (default on) copies their faces into six quads for frames without a projection
@@ -215,23 +221,24 @@ and left/up/right as Touch Y; right A as Touch A and X/Y/B as Touch B. Left View
 FrameBridge's `quest_buttons` preference (`0` default, `1` Mirror, `2` Quest pair) enables the extension when offered
 and suggests a Frame binding translated from the game's Touch suggestions. Common pressure/trigger/thumbstick,
 pose and haptic paths keep their Touch counterparts; thumbrest touch and system click are dropped, bumpers stay
-unbound. The player's SteamVR custom bindings can override suggestions. This works on both bridge ABIs, without
+unbound. The player's SteamVR custom bindings can override suggestions. `quest_buttons` works on both bridge ABIs, without
 the arm64-only extension shim. See [Controller buttons](CONTROLLERS.md) and the [mapping contract](input/QUEST_BUTTONS.md).
-Device verification of the new modes is pending integration with the native stream.
+The runtime accepts the suggested bindings in headless launches; the modes haven't been tried in the headset on
+many games yet.

 ## Lua native pointer compatibility

 Frame's Android processes can map libraries above the lowest 2^47 bytes of address space. The verified xLua API 105
-engine in BattleTalent 4.7 rejects those otherwise valid pointers in `lua_pushlightuserdata`. This was isolated using
+engine in BattleTalent 4.7 rejects those otherwise valid pointers in `lua_pushlightuserdata`. The cause was isolated using
 the unchanged library from the source APK: a real allocation at `0x10000000` round-trips, but its own native `xlua_tag`
 pointer above 47 bits raises `bad light userdata pointer` and exits. With `frame.luajit_pointers`, both round-trip
-exactly. No game scripts or account checks are changed. This validates an address-layout compatibility requirement;
+exactly. No game scripts or account checks are changed. The test validates an address-layout compatibility requirement;
 the APK was not run on an actual Quest during this investigation.

 The patch is restricted to SHA-256 `6d5860e4a4f1cc2b05c600c63297ed467369739666edca79413fff4374ff2684`.
-It redirects only the Lua engine's public API to a pinned full-pointer LuaJIT, keeping the original xLua bindings,
+The patch redirects only the Lua engine's public API to a pinned full-pointer LuaJIT, keeping the original xLua bindings,
 LuaSocket and game helpers. The patched build survives a 60 s headless launch and creates OpenXR swapchains.
-Early frame-rectangle errors and backend login errors remain in the capture; this does not verify rendering or play.
+Early frame-rectangle errors and backend login errors remain in the capture; the launch does not verify rendering or play.
 An arbitrary `lj_err_throw` followed by Unity destructor failures does not prove this pointer issue: first capture the
 Lua error text. `Unknown Platform` also appears after this crash is fixed, so it was not the fatal cause here.

@@ -242,10 +249,10 @@ Lua error text. `Unknown Platform` also appears after this crash is fixed, so it
  Appending `debug` while preserving inherited flags showed `fdm_injection_CreateInstance: skipped`.
  A temporary `FDM_DEBUG=enable,debug` launch created the Unity/Manta Vulkan instance and device,
  detected a 54x54 two-layer density map for 1728x1728 eye buffers, and logged render passes with
-  `fdm 1`, `already_has_fdm=1`, and changing offsets for both eyes. This verifies the injection path,
+  `fdm 1`, `already_has_fdm=1`, and changing offsets for both eyes. The probe verifies the injection path,
  not visual quality, gaze calibration, sustained gameplay stability, or an FPS/power improvement.
  `device.foveation` mode `tracked` now explicitly loads the layer and sets `FDM_DEBUG=enable` without
-  debug spam. It is opt-in; do not enable it globally or assume all GLES/Zink and Vulkan renderers work.
+  debug spam. The mode is opt-in; do not enable it globally or assume all GLES/Zink and Vulkan renderers work.
  Follow-up wearer test on 2026-10-11 FAILED in Batman: large rainbow glitches outside the gaze region
  and jitter even in clear regions. Restoring the original launcher and restarting removed BOTH symptoms,
  confirmed by the wearer. Do not recommend forced injection for this Batman build. Reaching foveated
@@ -269,7 +276,7 @@ Lua error text. `Unknown Platform` also appears after this crash is fixed, so it
  That is the only way to reach the Vulkan side of OpenGL ES games (Zink creates the instance inside Mesa).
 - GL ES: Zink (Mesa GL on Vulkan). Strict GLSL (see PLAYBOOK) and occasional `DEVICE LOST` with MSAA render-to-texture.

-## Proton / Windows games (surveyed 2026-09-29; running a Rift game under it not yet verified)
+## Proton / Windows games (surveyed 2026-09-29)
 - Steam on the Frame registers ARM64 compat tools from the app **"Steam Frame ARM64 Compat List"** (appinfo
  `extended.compat_tools`, found dynamically by the agent): `proton_11-arm64` (4628740, needs
  `steamlinuxruntime_steamrt4-arm64` 4185400), `proton-experimental-arm64` (4427310), `fex` (3127680, FEX-Emu for
@@ -277,10 +284,11 @@ Lua error text. `Unknown Platform` also appears after this crash is fixed, so it
  SteamLinuxRuntime_4). None are installed by default.
 - `steam -ifrunning steam://install/<appid>` only opens a confirmation dialog in the headset. The agent's unattended
  mode writes an appmanifest stub (StateFlags 1026, installdir from appinfo) and restarts Steam, which then downloads it.
- **x86_64 Linux apps (agent v61; verified on the device 2026-10-07: an x86_64 glibc test program installed + launch test RUNNING, "machine=x86_64 glibc=2.41"):**
+- **x86_64 Linux apps (verified on the device 2026-10-07: an x86_64 glibc test program installed + launch test
+  RUNNING, "machine=x86_64 glibc=2.41"):**
  FEX is Steam app 3127680 (`fex`, installs as `common/FEX-Emu`, ~6 MB, 21 s via the appmanifest-stub path:
-  `install_proton` / `proton_status` with `kind: linux_x86`). Its toolmanifest commandline is
-  `/fex-compat-tool %verb% --`, **no** require_tool_appid: it does not use the Steam Linux Runtime. fex-compat-tool
+  `install_proton` / `proton_status` with `kind: linux_x86`). FEX's toolmanifest commandline is
+  `/fex-compat-tool %verb% --`, **no** require_tool_appid: FEX does not use the Steam Linux Runtime. fex-compat-tool
  (Python) runs `<FEX-Emu>/usr/bin/FEX` with RootFS `/usr/share/guestos/fex-mesa` (part of the SteamOS image: an
  x86 Arch-style root with glibc 2.41, Mesa, graphics_provider.json for x86_64 + i386), emulates x86_64 and i386
  (emulator.json), honors `STEAM_FEX_TSOENABLED`, `STEAM_FEX_MULTIBLOCK`, `STEAM_COMPAT_FEX_CONFIG`, sets
@@ -312,8 +320,12 @@ Lua error text. `Unknown Platform` also appears after this crash is fixed, so it
  `XR_API_LAYER_PATH` (it keeps `XR_ENABLE_API_LAYERS`), so the agent registers the layer as an explicit layer in
  `~/.local/share/openxr/1/api_layers/explicit.d/` (home is shared into the container) with an absolute library path.
 - Oculus Store builds that delay-load `LibOVRPlatform64_1.dll` (Platform SDK, for example Lies Beneath) crash with
-  `0xc06d007e` (delay-load module not found): that DLL comes with the Oculus app, which the Frame doesn't have. (No Oculus runtime DLLs or
-  registry keys are needed: Revive's LibOVRRT hook works once OpenXR does.)
+  `0xc06d007e` (delay-load module not found): that DLL comes with the Oculus app, which the Frame doesn't have.
+- Revive under Proton arm64: Revive's Detours hooks (LoadLibrary, WinVerifyTrust) don't take effect because Wine's
+  kernelbase is ARM64EC code. `pcvr.libovr_redirect` puts Revive's runtime where the game looks for `LibOVRRT*_1.dll`
+  (gets past `-3001`), but games that check the runtime's Oculus signature then stop at `-3021`
+  (`ovrError_LibSignCheck`), which FramePort doesn't bypass. So LibOVR games run only on the PC; OpenVR/OpenXR builds
+  (for example Rick and Morty, Vader Immortal) run directly under Proton. DEVICE_NOTES "Revive under Proton arm64".
 - Unreal's Oculus plugin (and LibOVR's `ovr_Detect`) first checks for the Windows event `OculusHMDConnected` (created
  by the Oculus service on a PC) and silently skips VR without it. Revive hooks `OpenEventW` for that — Lies Beneath
  got as far as OVRPlugin, so the hook evidently works there — but it depends on Detours patching Wine's kernelbase,
@@ -325,18 +337,20 @@ Lua error text. `Unknown Platform` also appears after this crash is fixed, so it
 - Non-Steam shortcut: binary `userdata/<id>/config/shortcuts.vdf`; appid = crc32(exe+title) | 0x80000000;
  artwork in `config/grid/<appid>p.*` (portrait), `<appid>.*` (landscape), `<appid>_hero.*`, `<appid>_logo.*`.
  KeyValues names are case-insensitive: Steam may save `Shortcuts` / `AppName` after a devkit registration
-  (GitHub #263). Agent v86 reads and updates keys case-insensitively, keeping Steam's spelling and existing appids.
+  (GitHub #263). The agent reads and updates keys case-insensitively, keeping Steam's spelling and existing appids.
  Steam reads the file only at start → stop steam.service, edit, start (FramePort does it once per batch).
- Processes started from Steam (Konsole, SSH sessions?) share steam.service's cgroup: use `systemd-run --user`.
- SSH: `sshd` must be enabled (`sudo systemctl enable --now sshd`), which needs a user password (`passwd`).
+- Processes started from Steam (Konsole, and SSH sessions started from it) share steam.service's cgroup and end with
+  Steam: run such work through `systemd-run --user`.
+- SSH: Developer Mode enables `sshd`; FramePort logs in with its own key (the setup adds it), so no user password is
+  needed.
 - mDNS: avahi-daemon runs by default; hostname `frame` → `frame.local`.
- Desktop Mode menu entries (GitHub #84, agent v63): Linux apps get `~/.local/share/applications/frameport-<slug>.desktop`
+- Desktop Mode menu entries (GitHub #84): Linux apps get `~/.local/share/applications/frameport-<slug>.desktop`
  (+ an executable copy in `~/Desktop` when that folder exists; Plasma starts executable `.desktop` files there
  without a trust prompt), `Exec=env FRAMEPORT_DESKTOP=1 "<anchor>/launch.sh"`, marked `X-FramePort-Package=<pkg>`.
  Plasma's launcher exits right after starting the program, so with `FRAMEPORT_DESKTOP=1` the Linux launcher skips
  its "Steam parent gone → end the app" watchdog and keeps the desktop's DISPLAY/WAYLAND_DISPLAY instead of taking
  gamescope's from Steam. Not yet tried from the Frame's Desktop Mode.
- Linux apps' own icons (GitHub #99, agent v64): finalize_linux (and every refresh of the menu entries) copies the
+- Linux apps' own icons (GitHub #99): finalize_linux (and every refresh of the menu entries) copies the
  app's icon to `<anchor>/artwork/app-icon.{png,svg}`: an AppImage's `squashfs-root/.DirIcon` (usually a symlink),
  else the `Icon=` of its top-level `.desktop` file (a folder app: the first `.desktop` within 3 levels) looked up
  next to it, in `(usr/)share/icons/hicolor/*/apps/` and `(usr/)share/pixmaps/`; the biggest PNG ≥128 px, else an
@@ -378,7 +392,7 @@ over Quest games.
  a utility client, live; the path is kept in `~/.config/openvr/config/appconfig.json` `manifest_paths`.
  `SetApplicationAutoLaunch` is accepted (GetApplicationAutoLaunch → true; vrserver has
  `CAppInfoManager::StartAutolaunchOverlays`) but on the dev Frame it never reached `steamvr.vrsettings` (no
-  autolaunch entry for `temporalreality.overlay` there, appconfig.json holds only manifest_paths) and the owner's
+  autolaunch entry for `temporalreality.overlay` there, appconfig.json holds only manifest_paths) and the
  watch didn't start by itself, so FramePort doesn't rely on it (see "Autostart" below). The linuxarm64 vrserver only reads
  **`binary_path_linux_arm`**: a manifest with `binary_path_linux` alone is skipped ("must specify binary_path for
  launch_type binary. Skipping"; Steam's own steamapps.vrmanifest entries are skipped the same way), so an app's
@@ -386,12 +400,12 @@ over Quest games.
  `LaunchApplication(key)` then starts the binary (Temporal Reality's launch.sh: process up, overlays created).
 - A Steam shortcut of an overlay app and a game shortcut run at the same time (Temporal Reality, then 4XVR, both
  through `steam://rungameid`: both "Game process added", both kept running).
- FramePort (agent v75): `register_vr_overlay` writes `<anchor>/frameport-overlay.vrmanifest` (the app's own key,
+- FramePort: `register_vr_overlay` writes `<anchor>/frameport-overlay.vrmanifest` (the app's own key,
  name and image from its bundled manifest, binary = launch.sh in `binary_path_linux_arm` + `binary_path_linux`,
  absolute paths) and registers it; `unregister_vr_overlay`, uninstall and purge remove it; `ensure_host_fixes`
  registers ones SteamVR missed (it wasn't running). Overlay apps skip launch tests, the Linux launcher's
  Steam-parent watchdog (`FRAMEPORT_OVERLAY=1`) and don't count as a running game.
- **Autostart (agent v76)**: the deployment's `overlay.autostart` is the source of truth (SetApplicationAutoLaunch
+- **Autostart**: the deployment's `overlay.autostart` is the source of truth (SetApplicationAutoLaunch
  is still set for SteamVR builds that honour it). While at least one installed overlay app has it on,
  `ensure_host_fixes` keeps the user service `frameport-vr-overlays.service` (`~/.config/systemd/user`, enabled for
  default.target, Restart=always) = `frameport_agent.py _vr_overlay_watch`: every 5 s it checks the vrserver it knows
@@ -410,17 +424,18 @@ over Quest games.

 ## Video of the headset view (surveyed 2026-10-05; used by the Live view tab)
 - `steamvr-v4l2cam.service` (user unit, part of gamescope-session.target, `Restart=always`) runs SteamVR's
-  `/opt/steamvr/bin/linuxarm64/v4l2cam --output=99`: it reads the compositor's "Headset View" (IVRHeadsetView) and
+  `/opt/steamvr/bin/linuxarm64/v4l2cam --output=99`: v4l2cam reads the compositor's "Headset View" (IVRHeadsetView) and
  writes it to a v4l2loopback webcam named **"SteamVR"** (`/dev/video99`, 1920x1080 RGB24, advertised 30 fps, frames
  arrive at the display rate). Nothing on the Frame reads it by default; idle it costs nothing, read ~0.2 core.
-  It shows what the wearer sees (SteamVR home, Steam's panels; a game's layers are expected but not yet seen in it).
+  It shows what the wearer sees: SteamVR home, Steam's panels and games (4XVR's theatre with an overlay on top,
+  2026-10-10).
  Black and ~1 fps (one frame per ~1.0 s) while the Frame sleeps (standby): a 30 fps stream then repeats each
-  frame in bursts, which looks like a stall in a player. Its size follows SteamVR's headset view (v4l2cam has no size
+  frame in bursts, which looks like a stall in a player. The picture's size follows SteamVR's headset view (v4l2cam has no size
  option), so the live view only scales down (360p/480p/720p/1080p) or sends it as is ("full").
 - Sound: `pactl get-default-sink` (`alsa_loopback_device.stereo.alsa_output.platform-sound.HiFi__Speaker__sink`) and its
  `.monitor` source carry what the Frame plays; the Frame's ffmpeg has the `pulse` input and `aac`. Timestamps: pulse
  uses the wall clock, v4l2 CLOCK_MONOTONIC → `-ts mono2abs` on the v4l2 input. Don't force
-  `-use_wallclock_as_timestamps` on the pulse input: it stamped bursts of AAC packets with one time.
+  `-use_wallclock_as_timestamps` on the pulse input: that option stamped bursts of AAC packets with one time.
 - Steam's own game recording / Remote Play / broadcast capture the **gamescope** PipeWire node (`CDesktopCapturePipeWire:
  ... node path: gamescope`): with gamescope's `--backend openvr` that's only the flat Steam UI, not VR. Steam's arm64
  `libvideo.so` encodes with x264 (vaapi/nvenc paths don't apply). No cast/spectator feature for the Frame's own VR view
@@ -429,9 +444,9 @@ over Quest games.
  `h264_v4l2m2m` hangs, gst `v4l2h264enc` not-negotiated). ffmpeg + libx264 works: FramePort's live view
  (`install/livestream.py`: `fps=30` before the scale, ultrafast/zerolatency, 3 threads, nice 10, fragmented MP4 on
  stdout, + AAC 128k) measured 0.34 core at 720p / 0.56 at 1080p with a quiet picture (video only); expect ~1-1.4
-  cores with a busy scene. That is now only the fallback.
+  cores with a busy scene. The x264 path is now only the fallback.
 - Hardware encoding (2026-10-07): the iris encoder works when driven directly through the V4L2 stateful encoder
-  interface. That is FramePort's `fp_venc` (`native/venc`, spec + every measured value in `native/venc/SPEC.md`).
+  interface. FramePort's `fp_venc` does that (`native/venc`, spec + every measured value in `native/venc/SPEC.md`).
  Facts:
  - Device: `/dev/video23` (`/dev/video-enc0` links to it), driver `iris_driver`, M2M multiplanar.
  - Formats: input NV12/NV21/AB24(RGBA)/QC24/Q08C; output H264/HEVC; sizes 128..8192.
@@ -469,7 +484,7 @@ over Quest games.
      0–N s alongside), plus `frag_keyframe` so that a requested keyframe starts a fragment.
    - With sound, ffmpeg paces its inputs against each other and pulse's audio arrives later than the wall clock
      (more while something plays). The video input then counts as ahead, and ffmpeg stops reading it for up to
-      0.7 s, so the writer blocks. That was the cause of 1080p dropping frames: busy 1080p replayed with sound took
+      0.7 s, so the writer blocks. The blocked writer caused 1080p's dropped frames: busy 1080p replayed with sound took
      34–47 s for 20 s of video. Video alone was fine; `nice`, `-raw_packet_size` and the input queue size didn't
      matter. Shifting the video input back fixes it, but too far makes ffmpeg hold the video for interleaving and
      release it in clumps: -1 s gave output gaps of up to 550 ms, a longer and stuttering delay in the browser.
@@ -479,7 +494,7 @@ over Quest games.
      sound about 1 s. Chrome keeps about 0.6 s of audio ahead and stalls below that, whatever the player does:
      1.1× catch-up gave 8 stalls per 30 s, no speed-up 1–2, same average lag; 50 ms fragments didn't help. So the
      player doesn't speed up while sound is on.
-  - Quality (owner's headset test, 2026-10-07): 3 Mbit/s CBR at 720p36 showed heavy compression artifacts. The
+  - Quality (headset test, 2026-10-07): 3 Mbit/s CBR at 720p36 showed heavy compression artifacts. The
    hardware path now uses VBR with a 1.5× peak (the encoder accepts BITRATE_MODE VBR + BITRATE_PEAK) and higher
    targets: 360p 1.5, 480p 2.5, 720p 5, 1080p 8, Full 10 Mbit/s. The x264 fallback keeps its rates.
  - The default sink is SUSPENDED while nothing plays; its monitor still delivers (silent) audio.
@@ -514,7 +529,7 @@ radius pairs do **not** describe the generated shared-injection density map.
 The inspected arm64 `libVkLayer_VALVE_fdm_injection.so` has these semantics (virtual addresses):
 - `init_fdm_fove_level` at `0x1cdf4` calls the cached option reader, then
  `debug_parse_flags_option` (`0x21d74`) with table `0x27e70`: named tokens `lo` → 1,
-  `med` → 2, `hi` → 3. It does not call atoi/strtol. Unset, empty, unknown and numeric
+  `med` → 2, `hi` → 3. The parser does not call atoi/strtol. Unset, empty, unknown and numeric
  strings parse to zero and retain the current profile (initialized to 1 at `0x1ce74`).
  Tokens are case-sensitive and separated by non-alphanumeric/non-underscore characters;
  matching values are ORed, so combinations can alias another profile. `all` also yields 3;
@@ -533,7 +548,7 @@ The inspected arm64 `libVkLayer_VALVE_fdm_injection.so` has these semantics (vir
  `disable_offsets` fixes the gaze position (`0x1b6c8`), and `yflip` flips the vertical
  offset (`0x1b9b8`). These three flags do not resize the profile.
 - `FDM_SWAPCHAIN_SIZE` is parsed by `atoi` (`0x1c518`), clamped to nonnegative, and
-  seeds a known swapchain size (`0x1ccf8`). It is a size/matching hint, not a radius.
+  seeds a known swapchain size (`0x1ccf8`). The value is a size/matching hint, not a radius.
  The synthetic map (Zink/GLES dynamic-rendering path, `CmdBeginRendering`) is square with side
  `ceil(size/32)`, size = the render area width (`0x19048–0x19088`); image association also matches
  this tile size (`0x16c78`).
@@ -541,7 +556,7 @@ The inspected arm64 `libVkLayer_VALVE_fdm_injection.so` has these semantics (vir
  DEVICE_NOTES.md "Foveation: sharp area centre and size"): for Vulkan games the layer's
  `xrCreateSwapchain` creates a map of `ceil(w/32) x ceil(h/32)` texels per eye swapchain (one array
  layer per eye) and fills the preset rectangles in map-normalized coordinates, so the sharp area is
-  centred on the **whole swapchain** (all presets centre at about 0.51, 0.51). It knows each view's
+  centred on the **whole swapchain** (all presets centre at about 0.51, 0.51). The layer knows each view's
  imageRect (`xrEndFrame` stores them) but doesn't use it for the map. Eye-tracked offsets
  (`calc_offset`, `0x1b848`) are `gaze NDC x 0.5 x render-area size`, rounded to the offset
  granularity (8), measured from that same swapchain centre; `disable_offsets` (Fixed) also leaves
@@ -549,21 +564,21 @@ The inspected arm64 `libVkLayer_VALVE_fdm_injection.so` has these semantics (vir
  only when offsets are on). A game that submits a smaller or shifted rect (dynamic resolution,
  asymmetric eyes: AC Nexus rect=0,0 / 287,0 1726x1728 in 2016x1728, Asgard's Wrath 2 0,0 / 347,0
  2237x2256 in 2592x2256) gets the sharp area off its view's centre, and the eye's optical axis
-  (asymmetric FOV, e.g. -1.03/+0.88 rad) isn't the rect centre either. FramePort's
+  (asymmetric FOV, for example -1.03/+0.88 rad) isn't the rect centre either. FramePort's
  `VK_LAYER_FRAMEPORT_fdm_centre` (native/foveation/centre.h, below Valve's layer) rewrites the
  per-view offsets so the area sits on each eye.
 - Turnip (freedreno) applies a density map per GMEM **bin**: it reads the map on the CPU at the
  bin's centre (`tu_calc_frag_area`, texel size `2^ceil(log2(fb/map))` >= 32 px) and renders the
  whole bin at that density. The visible sharp area is therefore the set of bins whose centre falls
-  in Valve's rectangle: its size snaps to the bin grid (bins are ~150-200 px here and get relatively
+  in Valve's rectangle: the area's size snaps to the bin grid (bins are ~150-200 px here and get relatively
  smaller as render resolution grows), so the same preset looks bigger or smaller and changes
-  shape between render scales. That part is the driver's design, not a setting; FramePort can't
+  shape between render scales. The bin snapping is the driver's design, not a setting; FramePort can't
  pick the bins.

 Per-game library preferences now store `level`. Legacy radius choices are translated on read
 (and written as `level` on Save): nearest old nominal .30 → lo, .25 → med, .20 → hi,
 with larger values clamped by nearest choice; zero or unknown/invalid values → Default.
-This preserves approximate intent, not a claim that these presets implement those radii.
+The translation preserves approximate intent, not a claim that these presets implement those radii.
 Explicit `level` wins. Obsolete radius exports are removed from managed launchers.

 For device verification, hold game scene, render resolution and gaze constant; compare explicit
@@ -576,7 +591,7 @@ builds need diagnostic support installed. Turn the test and snapshots off before
 Agent `FOVEATION_ENV_KEYS` must include `"FOVE_LEVEL"` for launcher updates via `set_settings`.

 `device.foveation` enables Valve's shared Vulkan injection and suppresses competing native foveation through
-`foveation_fix=1`. Game settings stores mode, profile and test selection as a per-game library preference, outside shared recipes. This remains
+`foveation_fix=1`. Game settings stores mode, profile and test selection as a per-game library preference, outside shared recipes. Foveation remains
 experimental: complete images were confirmed in RE4, Batman, Deadpool, The Climb 2 and Asgard's Wrath 2,
 not all Quest games or renderers. RE4 and Batman checks include title/calibration scenes; these are not
 equivalent to extended gameplay coverage. Asgard gameplay was visually confirmed, without an on/off benchmark.
@@ -584,7 +599,7 @@ Batman additionally receives the verified ordinary shared-allocation patch, guar
 OVRPlugin hash; unknown Batman versions fail explicitly rather than receiving unchecked binary offsets.

 The Climb 2 uses a private `libvrapi_foveation.so` bridge, installed only into that game's APK after the
-standard bridge patch. It retains images during held-focus visibility dips, separates mono overlay output
+standard bridge patch. The private bridge retains images during held-focus visibility dips, separates mono overlay output
 storage from stereo density-map storage, and rate-limits its view-cache writes. Its process-local Valve layer
 correction supplies both eye offsets and avoids the invalid subpass mask-table reads seen during Alps loading;
 `yflip` corrects vertical gaze direction. The renderer SHA-256 and 1.0 resolution scale are checked before
@@ -594,7 +609,7 @@ the reason. No system library is changed. A SteamOS update requires revalidation
 Both-eye gaze following was confirmed in Climb's darkening diagnostic, but long-session stability remains
 experimental. Off disables injection through launcher exports; the private APK compatibility support remains installed.

-**Darken coarse fragments (test)** enables the dormant Vulkan shader diagnostic. It dims RGB where the
+**Darken coarse fragments (test)** enables the dormant Vulkan shader diagnostic. The diagnostic dims RGB where the
 actual `FragSizeEXT` footprint exceeds one pixel; alpha is unchanged. Deadpool's shaded regions were confirmed
 to follow gaze in the headset. Unsupported shader output interfaces are skipped, and multiple passes may
 compound darkening, so this is a diagnostic rather than a precise composited mask. Do not benchmark with it on.
@@ -607,6 +622,23 @@ Preset export/migration has configuration coverage. Headless device check of the
 Fixed, darkening test + FrameBridge `snapshot=N`, which also reads Vulkan eye images back): DEVICE_NOTES.md
 "Foveation: sharp area centre and size".

+### User preferences (discussion #365)
+
+Game settings → Picture provides Default / Eye-tracked / Fixed / Off, a runtime profile, and an advanced diagnostic switch.
+`set_settings` atomically rewrites just the managed launcher exports and records them in deployment.json;
+no APK rebuild, reinstall or live device intervention is needed. Changes apply at the next start. Default restores
+recipe/catalog launcher defaults; explicit preferences win. One-time library migration extracts old recipe choices
+and leaves internal APK compatibility support. Catalog defaults (including Climb 2 and Batman) still apply to new
+entries. Shared working configs omit `device.foveation` entirely.
+
+APK-side: adapter builds automatically prepare Batman's hash-verified allocation fix and Climb 2's
+renderer-guarded private bridge for verified builds, independently of the runtime choice. Unknown versions skip
+automatic compatibility edits; explicit catalog requests still fail validation rather than guessing offsets. FrameBridge
+builds include the dormant diagnostic layer (activated only by `FRAMEPORT_FOVEATION_TEST=1`), so future test toggles
+need only a launcher update. Existing builds need one normal update to acquire that support. Render resolution
+(supersampling) changes the game's render resolution: higher is sharper but slower. Climb 2 foveation still requires
+1.0 scale.
+
 ## Monitoring sources (probed 2026-10-07, SteamOS 0.4.3, kernel 6.18; used by the Monitor tab, agent `_monitor`)

 All readable by the steamos user without root; the agent reads them directly (no programs started per sample).
@@ -614,7 +646,7 @@ All readable by the steamos user without root; the agent reads them directly (no
 | Metric | Source | Notes |
 |---|---|---|
 | CPU | `/proc/stat` deltas; `cpufreq/policy{0,2,5,7}` | 8 cores in 4 clusters: 0-1 / 2-4 / 5-6 / 7 (max 2.27 / 3.15 / 2.96 / 3.05 GHz) |
-| GPU busy | Sum of `drm-engine-gpu` (ns) deltas in `/proc/<pid>/fdinfo/<fd>` over every render-node fd (msm DRM) | Gives GPU % per process too. A process can hold several render fds: add them all. Lepton games see the node as `/dev/kgsl-3d0` (bind mount of `/dev/dri/renderD128`). `drm-total-memory` reads 0. msm can report garbage engine time (SteamVR's vrcompositor: near 2^64, rising ~1000x faster than real time; idle Frame at 100 %, 2026-10-18): a per-fd delta longer than the interval falls back to `drm-cycles-gpu` / GPU clock (agent v102 `gpu_busy_ns`) |
+| GPU busy | Sum of `drm-engine-gpu` (ns) deltas in `/proc/<pid>/fdinfo/<fd>` over every render-node fd (msm DRM) | Gives GPU % per process too. A process can hold several render fds: add them all. Lepton games see the node as `/dev/kgsl-3d0` (bind mount of `/dev/dri/renderD128`). `drm-total-memory` reads 0. msm can report garbage engine time (SteamVR's vrcompositor: near 2^64, rising ~1000x faster than real time; idle Frame at 100 %, 2026-10-18): a per-fd delta longer than the interval falls back to `drm-cycles-gpu` / GPU clock (agent `gpu_busy_ns`) |
 | GPU clock | `/sys/class/devfreq/3d00000.gpu/{cur,max}_freq` | 231–903 MHz in 12 steps |
 | Memory / pressure | `/proc/meminfo`; `/proc/pressure/{cpu,memory,io}` (`some avg10`) | 16 GB RAM, 8 GB swap |
 | Temperatures | `/sys/class/thermal/thermal_zone*/{type,temp}` | 48 zones: `cpu*`/`cpuss*`, `gpuss-*`, `ddr`, `nsph*` (NPU), `pm8550*`/`pm8010*` (power ICs), `modem*`, `camera*`, `video`, `max1720x_bat*` |
@@ -630,26 +662,9 @@ game processes without one), temperatures every 2 s, the CPU-cluster power rails
 2-10 s, the stream measured ~10-13 ms CPU per 1 s tick on the device (idle clocks; idle or with 4XVR running) = about
 1 % of one core, ~0.15 % of the whole CPU. The I2C sensors (power monitors, battery gauge) are the slowest reads.

-### Foveation user preferences (discussion #365)
-
-Game settings → Picture provides Default / Eye-tracked / Fixed / Off, a runtime profile, and an advanced diagnostic switch.
-`set_settings` (agent 98) atomically rewrites just the managed launcher exports and records them in deployment.json;
-no APK rebuild, reinstall or live device intervention is needed. Changes apply at the next start. Default restores
-recipe/catalog launcher defaults; explicit preferences win. One-time library migration extracts old recipe choices
-and leaves internal APK compatibility support. Catalog defaults (including Climb 2 and Batman) still apply to new
-entries. Shared working configs omit `device.foveation` entirely.
-
-APK-side: adapter builds automatically prepare Batman's hash-verified allocation fix and Climb 2's
-renderer-guarded private bridge for verified builds, independently of the runtime choice. Unknown versions skip
-automatic compatibility edits; explicit catalog requests still fail validation rather than guessing offsets. FrameBridge
-builds include the dormant diagnostic layer (activated only by `FRAMEPORT_FOVEATION_TEST=1`), so future test toggles
-need only a launcher update. Existing builds need one normal update to acquire that support. Render resolution
-(supersampling) changes the game's render resolution: higher is sharper but slower. Climb 2 foveation still requires
-1.0 scale.
-
 ## Steam library scheduling

-Agent v99 holds automatic shortcut restarts while the local app's
+The agent holds automatic shortcut restarts while the local app's
 `~/.local/share/frameport-app/gui.alive` heartbeat is under ten seconds old, as well as while a game or Desktop Mode
 is open. Closed/crashed GUIs expire; the existing twelve-hour hold limit still applies.

@@ -669,10 +684,10 @@ mode isn't `later` and nothing is pending, and by purge; an otherwise empty `ste
 SteamOS 0.3.0 facts (checked 2026-10-16): Steam is the static user unit `/usr/lib/systemd/user/steam.service`
 (Type=simple, Restart=always, TimeoutStartSec 90 s, its own `-` ExecStartPre lines; `extra_args.conf` drop-ins are
 Valve's documented way to extend it), systemd 257; no user drop-ins exist by default.
-This automatic application targets SteamOS's `steam.service`; if Steam is started outside that service, use
+The automatic reapplication targets SteamOS's `steam.service`; if Steam is started outside that service, use
 FramePort's Restart Steam now action to apply the journal safely.

 Off skips new shortcuts (existing entries remain). Play in Off, and Play for a pending Later entry, starts launch.sh
 in a detached user systemd unit, just as launch tests do, without adding a devkit entry. Steam/SteamVR must already
-be running. This loses Steam's per-game overlay/controller setup and Exit game integration; use FramePort Monitor
-to stop the game. This direct path has unit coverage; headset input/visual behaviour needs device validation.
+be running. Direct starts lose Steam's per-game overlay/controller setup and Exit game integration; use FramePort Monitor
+to stop the game. The direct path has unit coverage; headset input/visual behaviour needs device validation.
@@ -5,7 +5,7 @@ setup changes on the Steam Frame, how to undo it and what your network needs.

 ## Changes on the Frame

-The setup runs [`bootstrap/bootstrap.sh`](../bootstrap/bootstrap.sh), which FramePort sends from your PC. It changes:
+The setup runs [`bootstrap/bootstrap.sh`](../bootstrap/bootstrap.sh), which FramePort sends from your PC. The script changes:

 | Change | Where | How to undo |
 |---|---|---|
@@ -14,14 +14,14 @@ The setup runs [`bootstrap/bootstrap.sh`](../bootstrap/bootstrap.sh), which Fram
 | Stops game starts from failing after about 200 launches (a limit in podman, the tool Lepton runs games with). | `[containers]` / `keyring = false` in `~/.config/containers/containers.conf`. | Remove those lines. |
 | Asks Steam to install **Lepton** (Valve's Android runtime) if it's missing. You confirm it in Steam. | Steam library | Uninstall it in Steam. |

-Valve's Developer Mode helper is the same one the Settings switch uses. It turns on remote login (SSH), the service
+Valve's Developer Mode helper is the same one the Settings switch uses. The helper turns on remote login (SSH), the service
 that makes the Frame findable on your network, remote desktop, debugging and crash dumps; turning Developer Mode off
 turns them all off again.

-The script runs as your user: no root, no `sudo`, no password. Nothing else on the system changes. It also leaves two
-files: `~/.cache/frameport-setup.sh` (the part that finishes on its own) and its log.
+The script runs as your user: no root, no `sudo`, no password. Nothing else on the system changes. The script also leaves
+two files: `~/.cache/frameport-setup.sh` (the part that finishes on its own) and its log.

-If Developer Mode can't be turned on automatically, the script asks you to turn it on in Settings → System →
+If Developer Mode can't be turned on automatically, the script asks you to turn Developer Mode on in Settings → System →
 **Enable Developer Mode** and run the setup line again.

 **Later, FramePort adds** (as your user):
@@ -29,15 +29,19 @@ If Developer Mode can't be turned on automatically, the script asks you to turn
 - the games, each with a launcher and its data in `~/Applications/quest-frame/<package>/`;
 - their Steam library entries and artwork (`shortcuts.vdf` + `config/grid/`);
 - for PC VR games: an OpenXR layer (`~/.local/share/openxr/1/api_layers/explicit.d/XR_APILAYER_FRAMEPORT_timefix.json`)
-  and Valve's ARM64 Proton with its Steam Linux Runtime (Steam downloads them and restarts once).
+  and Valve's ARM64 Proton with its Steam Linux Runtime (Steam downloads them and restarts once); for x86_64 Linux
+  apps: Valve's FEX;
+- for Linux apps: entries in Desktop Mode's app menu (`~/.local/share/applications/frameport-*.desktop`);
+- only when used: a user service that starts SteamVR overlay apps (`frameport-vr-overlays.service`) and, with
+  **Steam library: Later**, a drop-in for Steam's service (`~/.config/systemd/user/steam.service.d/`).

 **Settings → Uninstall FramePort → Also remove from the Frame** deletes the games, their Steam entries, the helper
-folder, the OpenXR layer and the setup files. Developer Mode, the login line, the podman setting, Lepton and Proton
+folder, the OpenXR layer, the menu entries, the services and the setup files. Developer Mode, the login line, the podman setting, Lepton and Proton
 stay: undo them as shown above.

 ## Network and firewalls

-The setup is the only time the Frame connects to your PC. It downloads the setup script from FramePort on TCP port
+The setup is the only time the Frame connects to your PC. The Frame downloads the setup script from FramePort on TCP port
 8765 (8766 or 8767 if taken), only while the setup page is open and for at most 30 minutes. Everything else goes
 from your PC to the Frame.

@@ -51,15 +55,15 @@ How the setup line finds your PC:
 The setup line's script is [bootstrap/setup.sh](../bootstrap/setup.sh). If the setup just says "timed out", the
 setup page shows what is likely blocking it after about 45 seconds:

- **Windows:** allow FramePort when Windows asks. On a network Windows treats as **Public** it stays blocked; set
+- **Windows:** allow FramePort when Windows asks. On a network Windows treats as **Public** the connection stays blocked; set
  your home network to Private in Windows' network settings.
 - **macOS:** with the firewall on (System Settings → Network → Firewall), allow incoming connections for FramePort
  when asked.
 - **Linux:** firewalld: `sudo firewall-cmd --add-port=8765/tcp` (until the next restart). ufw:
  `sudo ufw allow 8765/tcp`, afterwards `sudo ufw delete allow 8765/tcp`.
 - **WSL** (FramePort's Linux version on Windows): Windows blocks connections into WSL without asking. FramePort
-  adds a temporary firewall rule (one admin prompt) and removes it when setup is done or after 35 minutes. WSL must
+  adds a temporary firewall rule (one admin prompt) and removes the rule when setup is done or after 35 minutes. WSL must
  share Windows' network: `networkingMode=mirrored` under `[wsl2]` in `%UserProfile%\.wslconfig`, then
  `wsl --shutdown`.
 - Or skip the setup line and use **Pair new host** (see [Install and first steps](INSTALL.md#connecting-the-steam-frame)):
-  it needs no connection into your PC.
+  **Pair new host** needs no connection into your PC.
@@ -13,10 +13,12 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Arkio | Quest | ✅ Works |  |
 | Asgard's Wrath 2 | Quest | ✅ Works |  |
 | Assassin's Creed Nexus | Quest | ✅ Works |  |
+| Astro VR Host | Quest | ✅ Works |  |
 | Attack on Titan VR: Unbreakable | Quest | ✅ Works |  |
 | Audica | Quest | ✅ Works |  |
 | AugmentedEmpire | Quest | ✅ Works |  |
 | BAM | Quest | ✅ Works |  |
+| Barbaria | Quest | ✅ Works |  |
 | BARTENDER VR SIMULATOR | Quest | ✅ Works |  |
 | Batman: Arkham Shadow | Quest | ✅ Works |  |
 | BattleGlide | Quest | ✅ Works |  |
@@ -44,17 +46,21 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | cubism | Quest | ✅ Works |  |
 | cubism | Quest | ✅ Works |  |
 | Dance Central | Quest | ✅ Works |  |
+| Darksword | Quest | ✅ Works |  |
 | Deep Cuts | Quest | ✅ Works |  |
+| Deisim | Quest | ✅ Works |  |
 | Demeo | Quest | ✅ Works |  |
 | Demeter | Quest | ✅ Works |  |
 | Dinosaur Island | Quest | ✅ Works |  |
 | Doom3Quest | Quest | ✅ Works |  |
 | Down the Rabbit Hole | Quest | ✅ Works |  |
+| Drums Rock | Quest | ✅ Works |  |
 | Drunkn Bar Fight | Quest | ✅ Works |  |
 | Drunkn Bar Fight 2 - Early Access | Quest | ✅ Works |  |
 | Eleven Table Tennis | Quest | ✅ Works |  |
 | Eleven: Table Tennis VR | PC VR | ✅ Works |  |
 | EndoparasiticVR | Quest | ✅ Works |  |
+| Epic Roller Coasters | Quest | ✅ Works |  |
 | Espire 2 | Quest | ✅ Works |  |
 | Eye of the Temple | Quest | ✅ Works |  |
 | FrenzyVR | Quest | ✅ Works |  |
@@ -84,6 +90,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Lambda1VR | Quest | ✅ Works |  |
 | Laser Dance | Quest | ✅ Works |  |
 | LEGO® Bricktales | Quest | ✅ Works |  |
+| Little Nightmares VR | Quest | ✅ Works |  |
 | Lost Recipes | Quest | ✅ Works |  |
 | Lucky's Tale | Quest | ✅ Works |  |
 | Maestro | Quest | ✅ Works |  |
@@ -96,6 +103,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Mobile Suit Gundam: Silver Phantom | Quest | ✅ Works |  |
 | Moss | Quest | ✅ Works |  |
 | Moss: Book II | Quest | ✅ Works |  |
+| Movie Deck for Plex | Quest | ✅ Works |  |
 | Munkr Funkr (The Legacy Days) | Quest | ✅ Works |  |
 | Nano | Quest | ✅ Works |  |
 | Neko Atsume Purrfect | Quest | ✅ Works |  |
@@ -105,6 +113,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Ocean Rift | Quest | ✅ Works |  |
 | Operation Wolf Returns: First Mission VR | Quest | ✅ Works |  |
 | OrbusVR | Quest | ✅ Works |  |
+| Orcs Must Die: By The Blade | Quest | ✅ Works |  |
 | palazzo_santacruz | Quest | ✅ Works |  |
 | Path of the Warrior | Quest | ✅ Works |  |
 | Pistol Whip | Quest | ✅ Works |  |
@@ -129,10 +138,13 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Shoot The Zombirds VR | Quest | ✅ Works |  |
 | Shores of Loci | Quest | ✅ Works |  |
 | SilentSlayer | Quest | ✅ Works |  |
+| Simpsons Hit and Run VR | Quest | ✅ Works |  |
 | Smash Drums | Quest | ✅ Works |  |
 | Sniper Elite VR | Quest | ✅ Works |  |
 | Sniper Elite VR: Winter Warrior | Quest | ✅ Works |  |
+| Solero | Quest | ✅ Works |  |
 | Space Pirate Trainer Quest | Quest | ✅ Works |  |
+| SpaceControl | Quest | ✅ Works |  |
 | Spectre | Quest | ✅ Works |  |
 | Sports Scramble (Santa Cruz) | Quest | ✅ Works |  |
 | Star Wars Pinball VR | Quest | ✅ Works |  |
@@ -166,6 +178,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | ToyTrains | Quest | ✅ Works |  |
 | TRIANGLE STRATEGY | Quest | ✅ Works |  |
 | Under Cover | Quest | ✅ Works |  |
+| UNDERDOGS | Quest | ✅ Works |  |
 | Vacation Simulator | Quest | ✅ Works |  |
 | Vader Immortal: Episode I | Quest | ✅ Works |  |
 | Vader Immortal: Episode II | Quest | ✅ Works |  |
@@ -187,12 +200,15 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Does it Stack? | Quest | ⚠️ Works with issues | Mixed reality mode does not work (works on Demeo), everything else seems to be OK |
 | Dungeons of Eternity | Quest | ⚠️ Works with issues | It can not connect to servers |
 | End Space | Quest | ⚠️ Works with issues | Controls stop responding after the first mission loads. |
+| Eternal Starlight | Quest | ⚠️ Works with issues | Voice commands do not appear to work. |
 | Exploding Kittens VR | Quest | ⚠️ Works with issues | Requires online for most modes. |
 | ExploreVR | Quest | ⚠️ Works with issues | The 3D world warps and shifts with head movement (wrong perspective). |
 | FGO VR | Quest | ⚠️ Works with issues | Audio stuttering and popping sounds |
 | Fisherman | Quest | ⚠️ Works with issues | Loading screens have corruption, but everything works otherwise. |
+| GoldenEye VR | Quest | ⚠️ Works with issues | No sound; otherwise works great. |
 | HardBullet | Quest | ⚠️ Works with issues | Loading screens (a cube overlay) are missing or corrupted up to FramePort 1.2.1; cube_quads (next release) shows them as six panels, not confirmed in the hea… |
 | Homeworld: Vast Reaches | Quest | ⚠️ Works with issues | The game starts but after selecting to start a new game it seems to crash. |
+| JKXR | Quest | ⚠️ Works with issues | Tested in the early part of Jedi Outcast. |
 | Lawn Mowing Simulator VR | Quest | ⚠️ Works with issues | Left eye textures flicker only when mowing in specific areas. |
 | MacacoVR | Quest | ⚠️ Works with issues | 2d loading screens are glitchy, otherwise main gameplay is fine |
 | Majora's Mask VR | Quest | ⚠️ Works with issues | Audio on the file select screen sounds crunchy. |
@@ -200,8 +216,10 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Phantom: Covert Ops | Quest | ⚠️ Works with issues | DLC/store button crashes (no Meta store). |
 | Pinball FX VR | Quest | ⚠️ Works with issues | Plays; space warp off (fewer stutters). |
 | Plezy | Quest | ⚠️ Works with issues | Some videos play with strong artifacts and wrong colours; the cause is unknown, possibly hardware video decoding. |
+| PrimedGun v2 | Quest | ⚠️ Works with issues | Vulkan via a statically linked Khronos OpenXR loader, which bypasses FrameBridge (the picture jumps). |
 | Puzzling Places | Quest | ⚠️ Works with issues | Works fine, but pointers dont show well on main menu, easy to work around. |
 | Quantum Void | Quest | ⚠️ Works with issues | no hands |
+| QuestZDoom | Quest | ⚠️ Works with issues | Needs a WAD: put it into QuestZDoom/wads in the game's storage (Files tab) and set QuestZDoom/commandline.txt to "qzdoom -iwad /sdcard/QuestZDoom/wads/<name>… |
 | Ragnarock | Quest | ⚠️ Works with issues |  |
 | Real VR Fishing | Quest | ⚠️ Works with issues | Seems to be almost 100% functional with meta permissions enabled. |
 | Silhouette | Quest | ⚠️ Works with issues | Hand-tracking game; the Frame synthesizes hands from controllers, so it is janky. |
@@ -212,6 +230,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | The Light Brigade | Quest | ⚠️ Works with issues | Judder in weapons |
 | The Thrill Of The Fight | Quest | ⚠️ Works with issues | Right eye doesn't draw the opponent or the referee. |
 | Time Stall | Quest | ⚠️ Works with issues | Both eyes distort during movement (unresolved). |
+| Umurangi Generation VR | Quest | ⚠️ Works with issues | The game freezes after taking a photo, while it saves it, which makes it hard to play. |
 | Vampire: The Masquerade - Justice | Quest | ⚠️ Works with issues | Game runs fine and playable, on loading there's a random sphere in the middle of the sceen. |
 | WiiCompiled VR | Quest | ⚠️ Works with issues | To add a game: in FramePort's Files tab, upload your .wcgame file to this game's storage, folder Android/data/org.wiicompiled.quest/files/WiiCompiledOpenXRVR… |
 | Breachers | Quest | ❌ Doesn't run | Online-only multiplayer that needs Meta's online services, which aren't available on the Frame. |
@@ -219,5 +238,6 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | Espire 1: VR Operative (Quest Edition) | Quest | ❌ Doesn't run | Mesa GL driver crash during texture upload. |
 | GOLF+ | Quest | ❌ Doesn't run | Black screen. |
 | HITMAN 3 VR: Reloaded | Quest | ❌ Doesn't run | Vulkan driver crash (freedreno), even without Valve layers. |
+| PianoVision | Quest | ❌ Doesn't run | Starts, but needs camera hand tracking (Android games on the Frame only get hands built from the controllers) and USB MIDI from a piano, which the Frame's An… |
 | Roblox | Quest | ❌ Doesn't run | Crashes on its first VR frame on the Frame. |
 | Thief Simulator | Quest | ❌ Doesn't run | Quits at start with the game's own "installed from unknown source" message. |
@@ -1,8 +1,8 @@
 # Evaluating patch heuristics

 `scripts/eval_heuristics.py` compares `engine.suggest(analysis, use_catalog=False)` with the bundled
-`catalog/games/*.yaml` entries. It does not merge personal or remote catalog recipes into the benchmark.
-It supports the original dumps command, or a precomputed `scripts/heuristics_snapshot.py` snapshot:
+`catalog/games/*.yaml` entries. The script does not merge personal or remote catalog recipes into the benchmark.
+The script supports the original dumps command, or a precomputed `scripts/heuristics_snapshot.py` snapshot:

 ```sh
 .venv/bin/python scripts/eval_heuristics.py '<dumps folder>' --verbose
@@ -24,7 +24,7 @@ can move the cutoff. Very small strata can have no holdout. Unsupported entries

 Ground truth contains catalog choices and patch registry defaults, with no inherited heuristic adapter settings.
 Default expectations are determined per analysis, using each default patch's own detection in the same way as the
-engine's initial heuristic pass. Thus a conditional default that is not detected (e.g. LTW on a game without LTW)
+engine's initial heuristic pass. Thus a conditional default that is not detected (for example LTW on a game without LTW)
 is not expected. Explicit catalog `overport_remove` and `frame_remove` entries remove expected defaults. An absent
 expected default is represented as `remove:<patch id>`; enabled defaults do not inflate patch scores.

@@ -59,10 +59,10 @@ Before tuning a rule to remove an "extra", check which kind it is: a gap on an o
 catalog (fit report), not a detection error. Before adding a patch to a working entry, weigh its benefit (does it
 fix something the game hits?) against a rebuild prompt for everyone who installed it; adapter settings never need
 adding (inherited). Results 2026-10-15: strict 5/65 exact, F1 73.8%; dated 39/65, F1 88.6% (dev 90.5%, holdout
-79.5%). Remaining misses are one-game fixes found at runtime (e.g. Vader's gl_error_clear, BlazeRush's GL settings).
+79.5%). Remaining misses are one-game fixes found at runtime (for example Vader's gl_error_clear, BlazeRush's GL settings).

 An evaluation writes JSON even when its headline has differences, then exits 1 for compatibility with the original
-script. It exits 0 when exact, or after producing a fit report.
+script. The script exits 0 when exact, or after producing a fit report.

 ## New patch fit

@@ -6,7 +6,7 @@ game on the Steam Frame.
 [![The install tutorial](media/frameport-install.jpg)](media/frameport-install.mp4)

 Download the file for your PC from the [latest release](https://github.com/spoopyghosty0/frameport/releases/latest)
-and unpack it anywhere. No installer or admin rights are needed.
+and unpack it anywhere. No installer or admin rights needed.

 | Your PC | Download | Start |
 |---|---|---|
@@ -16,208 +16,185 @@ and unpack it anywhere. No installer or admin rights are needed.
 | Linux (ARM64, Ubuntu 22.04 or newer) | `FramePort-linux-arm64.tar.gz` | `FramePort/FramePort` |
 | Arch Linux (AUR, community package) | [`frameport-bin`](https://aur.archlinux.org/packages/frameport-bin) | `frameport` |

-On first start FramePort downloads the tools it uses (Settings → Tools shows them).
+On first start FramePort downloads the tools it uses (listed in Settings → Tools).

 ## First launch

-Starting FramePort again brings its existing window to the front. If a previous instance was left running after
-its window closed, FramePort recovers it automatically, including on Windows where the GUI lock cannot be read.
-
 FramePort isn't signed with a paid certificate, so the first start shows a warning:

 - **Windows:** "Windows protected your PC" → **More info** → **Run anyway**.
 - **macOS:** right-click `FramePort.app` → **Open** → **Open** (once).
- **Linux:** `tar xzf FramePort-linux-x64.tar.gz && ./FramePort/FramePort`. On Arch Linux, install the community AUR package [`frameport-bin`](https://aur.archlinux.org/packages/frameport-bin) (`yay -S frameport-bin`).
+- **Linux:** `tar xzf FramePort-linux-x64.tar.gz && ./FramePort/FramePort`. Arch Linux: `yay -S frameport-bin`.

 ## Connecting the Steam Frame

-The Frame and your PC must be on the same network (or connected with a [USB cable](#with-a-usb-cable)).
+The Frame and your PC must be on the same network, or connected with a [USB cable](#with-a-usb-cable).

 1. In FramePort open **Steam Frame** and click **Start setup**. Keep that page open.
-2. On the Frame, first time only:
-   1. Open the **SteamVR dashboard → Launch a program → Desktop**. The Frame's desktop opens.
-   2. Open the app menu (bottom left) → **System → Konsole**, the Frame's terminal.
-   3. Type this setup line and press **Enter** (on-screen keyboard or any USB or Bluetooth keyboard):
+2. On the Frame (first time only):
+   1. Open **SteamVR dashboard → Launch a program → Desktop**.
+   2. Open the app menu (bottom left) → **System → Konsole**.
+   3. Type this line and press **Enter**:

      ```
      curl -fsSL https://frameport.app/s | bash
      ```

-      No keyboard? Open [the setup page](https://frameport.app/setup/) in Chromium on the Frame,
-      tap **Copy** and paste it into Konsole.
-   4. Konsole shows a 4-digit code. When FramePort shows the same code, click **Allow**. Nothing changes on the Frame
-      before that.
-   5. Steam restarts once and the desktop closes. If Steam asks to install **Lepton** (Valve's Android runtime),
-      confirm it.
+      No keyboard? Open [the setup page](https://frameport.app/setup/) in Chromium on the Frame, tap **Copy** and
+      paste the line into Konsole.
+   4. Konsole shows a 4-digit code. When FramePort shows the same code, click **Allow**. Nothing changes before that.
+   5. Steam restarts once. If Steam asks to install **Lepton** (Valve's Android runtime), confirm.

-FramePort connects within a minute. No password is needed. The setup turns on **Developer Mode**;
-[What the setup changes](FRAME_SETUP.md) lists everything.
+FramePort connects within a minute, without a password, and from then on by itself. The setup turns on **Developer
+Mode** (Settings → System on the Frame); keep Developer Mode on. [What the setup changes](FRAME_SETUP.md) lists everything.

-Later, FramePort connects to the Frame by itself. If you turn Developer Mode off (Settings → System → **Enable
-Developer Mode**), turn it on again there.
-
-**Setup command:** if your network blocks FramePort's search, click **Use the setup command**. It shows a line with
-your PC's address and a one-time code, for example `curl -fsS 192.168.1.20:8765/1a2b3c4d | bash`. Run it in Konsole instead.
-
-**Without Konsole:** turn on Developer Mode yourself (Settings → System → **Enable Developer Mode**), then open
-Settings → Developer → **Pair new host** on the Frame. FramePort finds the Frame and asks to connect; approve it in the
-headset. Install Lepton from FramePort's Steam Frame page afterwards if it's missing.
+- **Network blocks the search?** Click **Use the setup command** and run the line FramePort shows in Konsole
+  instead (the line holds your PC's address and a one-time code).
+- **Without Konsole:** turn on Developer Mode, then open Settings → Developer → **Pair new host** on the Frame.
+  Approve FramePort's request in the headset. Install Lepton from FramePort's Steam Frame page if Lepton is missing.

 ### With a USB cable

-A cable works on networks that block the setup, and uploads are faster (about 37 MB/s, three times typical Wi-Fi).
+A cable works on networks that block the setup, and uploads are about three times faster than on typical Wi-Fi.

-1. On the Frame, turn on Developer Mode (Settings → System → **Enable Developer Mode**). The cable only works in
-   Developer Mode.
-2. Connect the Frame's USB-C port to your PC. No driver is needed.
-3. In FramePort click **Steam Frame → Set up with a USB cable** and follow the steps.
+1. On the Frame, turn on Developer Mode (Settings → System). The cable only works in Developer Mode.
+2. Connect the Frame's USB-C port to your PC. No driver needed.
+3. Click **Steam Frame → Set up with a USB cable** and follow the steps.

-Uploads use the cable whenever it's plugged in. Unplug it any time: FramePort finds the Frame on Wi-Fi again.
+Uploads use the cable while the cable is plugged in. You can unplug the cable any time.

 ### Firewalls

 If the setup only says "timed out", a firewall on your PC blocks the Frame. After about 45 seconds the setup page
-says which. Details: [Network and firewalls](FRAME_SETUP.md#network-and-firewalls).
+says which one. Details: [Network and firewalls](FRAME_SETUP.md#network-and-firewalls).

 ## Running FramePort on the Frame (experimental)

-FramePort can run on the Frame itself, without a PC:
+1. Turn on Developer Mode (Settings → System).
+2. In Desktop Mode, download `FramePort-linux-arm64.tar.gz`, unpack the file and start `FramePort/FramePort`.

-1. Turn on Developer Mode (Settings → System → **Enable Developer Mode**).
-2. In Desktop Mode, download `FramePort-linux-arm64.tar.gz`, unpack it (`tar xzf FramePort-linux-arm64.tar.gz`) and
-   start `FramePort/FramePort`.
-
-With the default **Steam library: Now**, games appear after you close FramePort and return to Gaming Mode.
-FramePort also waits while its window is open in Gaming Mode, so you can install several games in one session.
-Please report anything odd with **Report a problem…**.
-
-Settings → Installing → **Steam library** controls future installs:
-
- **Now** (default): restart Steam after adding shortcuts, waiting while a game, Desktop Mode, or FramePort's local
-  window is open (up to 12 hours). Unchanged shortcuts need no restart.
- **Later**: save shortcuts without restarting Steam. Keep installing; changes are applied at the next Steam
-  service start, including after a reboot. **Restart Steam now** applies them immediately. It closes Desktop Mode
-  and FramePort running on the Frame, and asks again if a game is running.
- **Off**: skip new Steam shortcuts; existing entries stay. FramePort's **Play** runs the installed launcher directly.
-  Steam and SteamVR must already be running. Steam's per-game overlay, controller setup, and Exit game integration
-  are unavailable; stop the game from FramePort's Monitor. Pending games in Later also use this direct Play path.
-
-CLI: `frameport frame steam-library now|later|off` saves the setting and applies it to the connected Frame.
-`frameport frame restart-steam` applies pending entries now; `--yes` confirms ending a running game.
-These settings concern game shortcuts; installing a missing Steam runtime such as Proton can still require a restart.
+Games appear in Steam once you close FramePort and return to Gaming Mode ([when games appear in
+Steam](#when-games-appear-in-steam)).

 **Moving from a PC:**

-1. Copy the signing keys first: the `<package>.keystore` files in
-   `%LOCALAPPDATA%\FramePort\overport-workspace\signatures\`
-   (Linux/macOS: FramePort's data folder, `overport-workspace/signatures/`) go to
-   `~/.local/share/frameport-app/overport-workspace/signatures/` on the Frame, before FramePort there builds those
-   games. Otherwise it makes new keys: updates are signed differently from the installed games, and games that keep
-   progress per Meta account get a different account id, so their progress can look gone.
-2. Put the original game files on the Frame and add that folder to the Library there; the PC's library doesn't carry
-   over, and updates are built from the originals. Data files on the same drive as the installs are linked into the
-   install instead of copied, so they take space once.
-3. Games already installed keep working; installing them again from the Frame keeps their saves. Don't manage the
-   same game from both the PC and the Frame unless both have the same keys.
+1. First copy the signing keys: the `<package>.keystore` files from `overport-workspace/signatures/` in FramePort's
+   data folder (Windows: `%LOCALAPPDATA%\FramePort`) to
+   `~/.local/share/frameport-app/overport-workspace/signatures/` on the Frame. Without them, updates can't install
+   over your games and progress tied to a Meta account can look gone.
+2. Put the original game files on the Frame and add that folder to the Library there. The PC's library doesn't
+   carry over. Data files on the same drive as the installs take space only once.
+3. Installed games keep working, and reinstalling them from the Frame keeps their saves. Don't manage a game from
+   both the PC and the Frame unless both have the same keys.

 ## Installing games

 ![Game page](images/game.png)

- **Install on Frame** on a game's page, or select several games in the Library and install them together. Installs
-  run in the background; **Activity** shows the current one.
+- **Install on Frame** on a game's page, or select several games in the Library. Installs run in the background;
+  **Activity** shows the current one.
 - **Update all** updates every game whose build changed, for example after a FramePort update.
- If the Frame sleeps or leaves the Wi-Fi, installs wait and continue when it's back. While installs run, the Frame
-  stays awake.
- Your own game files are never changed. The patched copy is deleted once the game is on the Frame (Settings →
-  Installing).
- In the downloaded app you can also **drag files onto the Library**: games, Linux apps, Windows programs or folders.
- App bundles (`.xapk`, `.apks`, `.apkm`, `.apkx` or a folder of split APKs) are added like an APK. FramePort merges
-  their parts into one APK; see [the FAQ](FAQ.md#can-i-add-xapk-apks-apkm-or-apkx-files-app-bundles).
+- If the Frame sleeps or drops off the network, installs wait and continue. The Frame stays awake while they run.
+- Your own game files are never changed.
+- In the downloaded app you can **drag files onto the Library**: games, Linux apps, Windows programs or folders.
+- App bundles (`.xapk`, `.apks`, `.apkm`, `.apkx`, split APKs) are added like an APK:
+  [FAQ](FAQ.md#can-i-add-xapk-apks-apkm-or-apkx-files-app-bundles).

-**Game settings…** (in the game's menu) shows the settings that matter for that game in plain words: sharpness,
-refresh rate, controllers, menus, 360° video and mixed reality. Changes are used the next time the game starts.
+A game's **menu** opens with a right-click in the Library or the **…** button on the game's page. The menu's groups
+are
+**Update**, **On the Frame**, **Saves**, **Name and artwork**, **Recipe** and **Troubleshoot**.
+
+- **Game settings…** shows the settings that matter for that game: sharpness, refresh rate, controllers, menus,
+  360° video and mixed reality. Changes apply the next time the game starts.
+- **Name and artwork → Rename…** renames the game in the Library and in Steam. The game's Steam entry, artwork and
+  saves stay.

 ![Game settings](images/game-settings.png)

-**Rename…** (in the game's menu) changes the name in the Library and in Steam; FramePort keeps it from then on. An
-installed game keeps its Steam entry, artwork and saves (Steam restarts once).
+### When games appear in Steam
+
+Steam reads new games only when Steam starts. Settings → Installing → **Steam library** sets when Steam restarts:
+
+- **Now** (default): Steam restarts after an install. The restart waits while a game, Desktop Mode or FramePort on the Frame
+  is open (up to 12 hours).
+- **Later**: new games appear at Steam's next start, also after a reboot. **Restart Steam now** adds them at once
+  (the restart closes Desktop Mode and FramePort on the Frame, and asks first if a game is running).
+- **Off**: no new Steam entries; existing ones stay. FramePort's **Play** starts the game directly. Steam and SteamVR
+  must be running, and Steam's overlay, controller setup and Exit game don't work for the game: end the game from **Monitor**.
+  Games waiting for **Later** start this way too.
+
+Command line: `frameport frame steam-library now|later|off`, `frameport frame restart-steam [--yes]`. Installing
+Proton can still restart Steam.

 ### microSD cards and other drives

- The **Steam Frame** page's **Storage** section sets where new games go (**Install new games to**).
- To move an installed game, right-click it (or use **…** on its page) → **On the Frame** → **Move to…**. The game must be closed; saves and the Steam entry stay.
+- **Steam Frame → Storage → Install new games to** sets where new games go.
+- **On the Frame → Move to…** in a game's menu moves the game. Close the game first; saves and the Steam entry stay.
 - A game on a card only starts while the card is inserted.
- Cards formatted as FAT, exFAT or NTFS can't hold games: format the card in SteamOS first.
+- Cards formatted as FAT, exFAT or NTFS can't hold games. Format the card in SteamOS first.

-### Why do the controller buttons repeat or do the wrong thing?
+### Controller buttons

-SteamVR maps Quest Touch onto the Frame's controller buttons by default: three top buttons repeat Touch Y/B.
-Choose **Game settings → Controllers → Controller buttons** to use Mirror or Quest pair for one game, or
-**Settings → Controllers** for the library default. **Apply to installed games now** sends the default to Quest
-games without an override. Changes take effect at the next launch.
-See [Controller buttons](CONTROLLERS.md) for the diagram, mappings and limits.
+Buttons repeat or do the wrong thing? **Game settings → Controllers → Controller buttons** picks **Mirror** or
+**Quest pair** for one game. **Settings → Controllers** sets the default; **Apply to installed games now** sends the
+default to games without their own choice. Details: [Controller buttons](CONTROLLERS.md).

 ### Android apps and Windows programs

- Android apps without VR are installed unchanged and shown as a window in the headset. If one shows nothing (or a
-  VR app opens as a window), open **Customize** on the game's page, set **Show as VR or as a flat window** and click
-  **Update on Frame**.
- **Add games → Add a Windows program…** adds a single Windows program. The Frame runs it as a window through Proton
-  (Valve's tool for running Windows programs).
+- Android apps without VR are installed unchanged and shown as a window. Shows nothing, or a VR app opens as a
+  window? On the game's page: **Customize** → **Show as VR or as a flat window** → **Update on Frame**.
+- **Add games → Add a Windows program…** adds one Windows program. The Frame runs the program as a window through Proton.

 ### Install links ("Install with FramePort" buttons)

-Some websites have an **Install with FramePort** button (a `https://frameport.app/install?…` link):
+Some websites have an **Install with FramePort** button (a `https://frameport.app/install?…` link).

- **Click a button** on Windows or Linux: FramePort opens, shows what it would download and asks first. Then it adds
-  the game and installs it on the Frame.
- **Add games → Add from a link…** takes a button's address (right-click → Copy link) or a direct download link. Use
-  it on macOS, where buttons can't open FramePort yet.
+- **Click the button** (Windows, Linux): FramePort opens, shows what FramePort would download and asks first.
+- **Add games → Add from a link…** takes a button's address (right-click → Copy link) or a direct download link.
+  Use **Add from a link…** on macOS, where buttons can't open FramePort yet.
 - **Settings → Install links** turns the buttons on or off.
- Only `https://` links to public servers are used. Only install from sites you trust.
+- Only `https://` links to public servers work. Only install from sites you trust.

-Website owners: see [Install button](INSTALL_BUTTON.md).
+Website owners: [Install button](INSTALL_BUTTON.md).

 ## Typing on the Frame

- **Type on Frame** (in the sidebar): while this tab is open, your PC's keyboard types on the Frame. Select a text
-  field in the headset and type, or paste longer text into the box.
- **Steam's on-screen keyboard** works in apps shown as a window. Steam lists that window as **Gamescope**: leave it
-  open.
- **Unity games whose text fields close at once:** FramePort suggests the patch **Make Unity text fields work**.
-  Games added before this patch existed: open the game's menu → **Analyze again**, then reinstall.
+- **Type on Frame** (sidebar): while the tab is open, your PC's keyboard types on the Frame. Select a text field in
+  the headset and type, or paste text into the box.
+- **Steam's on-screen keyboard** works in apps shown as a window. Steam lists that window as **Gamescope**: leave the
+  window open.
+- **Unity text fields close at once?** Use the patch **Make Unity text fields work**. Not offered for an older game?
+  **Troubleshoot → Analyze again**, then **Update on Frame**.

 ![Type on Frame](images/type-on-frame.png)

 ## Watching the Frame

- **Monitor** (in the sidebar) shows the running game's frame rate, CPU, graphics, memory, temperature, power and
-  battery, each with a 2-minute chart. **Show details** shows more.
- Under **Processes**, right-click a process to end it. **End game** closes the game like Steam's Exit game. A lock
-  marks programs Steam or the desktop needs; FramePort asks again before ending those.
- **Live view** streams what the headset shows, with sound, to your browser. It uses about one CPU core of the Frame,
-  so stop it when you're done.
- **Screenshots** shows the screenshots you took in the headset, sorted by game and day, to view or download.
+- **Monitor** (sidebar): the running game's frame rate, CPU, graphics, memory, temperature, power and battery.
+  **Show details** shows more.
+- Under **Processes**, right-click a process to end the process. **End game** closes the game like Steam's Exit game.
+  FramePort asks again before ending programs Steam or the desktop needs (marked with a lock).
+- **Live view** streams what the headset shows, with sound, to your browser. Live view uses about one CPU core of the
+  Frame: stop Live view when you're done.
+- **Screenshots** shows your headset screenshots by game and day, to view or download.

 ## Your room (mixed reality, experimental)

-Mixed-reality games ask for your room: walls, furniture and its surfaces. **Room** (in the sidebar) keeps it:
+Mixed-reality games ask for your room: walls, furniture and surfaces. The **Room** tab keeps the room.

- **Scan room in the headset**, then put the headset on with passthrough and look around for about a minute; the tab
-  shows how far the scan is. **Cancel scan** stops it and keeps your saved room. **Use my play area** makes walls from
-  the SteamVR play area instead (no furniture).
- The room shows in 3D: drag to turn it, scroll to zoom, right-drag to move it, double-click to see all of it.
-  **Open full 3D view** shows every detail of the scan in your browser (a page on this PC only).
- **Clean-up** tidies every scan (flat walls, no scan behind walls or where you walked, no loose bits). The
-  recommended settings suit most rooms; change them (**More settings** has all of them) and press **Apply** to clean
-  up your saved scan again. Your settings are also used for your next scans.
- **Labels** shows what the scanner's boxes became and why. A tall, thin box by a wall can be **Add as door** or
-  **Add as closet**.
- **Furniture & screens**: pick a box in the list or click it in the 3D view to change its type, place or size, add
-  or delete boxes, and add doors and windows on a wall. **Save** sends them to the Frame; they stay when you clean up
-  the scan again (**Back to the scan's boxes** under Labels drops them).
- The free **Test Quest MR** app (Get Test Quest MR on the tab) shows what a game receives from your scan.
+1. **Scan room in the headset**, put the headset on and look around for about a minute. **Cancel scan** keeps your
+   saved room. **Use my play area** makes walls only, from the SteamVR play area.
+2. Check the room in 3D: drag to turn, scroll to zoom, right-drag to move, double-click to see the whole room. **Open full
+   3D view** shows every detail in your browser.
+3. Fix the room if needed:
+   - **Clean-up** tidies every scan. The recommended settings suit most rooms; **Apply** re-cleans your scan with
+     changed ones (also used for later scans).
+   - **Labels** shows what each scanned box became and why. A tall, thin box by a wall can be **Add as door** or
+     **Add as closet**.
+   - **Furniture & screens**: click a box to change the box's type, place or size; add or delete boxes; add doors and
+     windows. **Save** sends them to the Frame. They survive a new clean-up (**Back to the scan's boxes** drops them).
+
+The free **Test Quest MR** app (**Get Test Quest MR** on the tab) shows what a game receives.

 ![Room](images/room.png)

@@ -225,54 +202,44 @@ Mixed-reality games ask for your room: walls, furniture and its surfaces. **Room

 ## Updating

-FramePort checks for a new version at start and every 6 hours. When there is one, the Library shows **Update now**:
-FramePort downloads it, checks it, restarts and keeps your games and settings. **Later** skips that version.
+FramePort checks for a new version at start and every 6 hours. **Update now** in the Library downloads the new
+version, checks it and restarts FramePort; your games and settings stay. **Later** skips that version.

- Settings → **Updates** turns the check off or turns on **Install updates automatically**.
- **Recipes** (the tested patches and settings for each game) update by themselves. A game whose recipe changed shows
-  **Update on Frame**.
- **Moved your games?** Scan the new folder (or **Rescan folders**): games found there whose old files are gone keep their library entry, name, artwork, tags and settings, and only their location changes. **Settings → Library folders** lists the folders FramePort scans; remove the old one there (the games stay). See the [FAQ](FAQ.md#i-moved-my-games-to-another-folder-or-drive-how-do-i-update-the-library).
- **A newer version of a game:** right-click it (or use **…** on its page) → **Update** → **Update with a newer
-  APK…** (Quest and Android games) or **Update with a newer version…** (Linux apps: the new AppImage, archive or
-  folder; PC VR games: the new game folder). Its name, artwork, tags and your settings stay. Then click **Update on
-  Frame** (or **on this PC**).
- **Dev builds:** if you're asked to test a change before its release, use Settings → Updates → **Install the latest
-  dev build…**. The next release then arrives as a normal update.
- **Installed from the AUR?** Update with your AUR helper (`yay -Syu`); FramePort can't update itself in `/opt` and
-  opens the release page instead. New releases reach the AUR once the community package is updated.
+- Settings → **Updates** turns the check off or on, or turns on **Install updates automatically**.
+- **Recipes** update by themselves. A game whose recipe changed shows **Update on Frame**.
+- **Moved your games?** Scan the new folder or click **Rescan folders**. Moved games keep their name, artwork, tags
+  and settings. [FAQ](FAQ.md#i-moved-my-games-to-another-folder-or-drive-how-do-i-update-the-library).
+- **A newer version of a game:** game menu → **Update** → **Update with a newer APK…** (Quest and Android games) or
+  **Update with a newer version…** (Linux apps, PC VR games). Then **Update on Frame** (or **on this PC**). Name,
+  artwork, tags and settings stay.
+- **Dev builds** (when asked to test a change): Settings → Updates → **Install the latest dev build…**.
+- **AUR install:** update with your AUR helper (`yay -Syu`). FramePort can't update itself in `/opt`.

 ## PC VR games

-PC VR games are Windows VR games. Scan a folder of them (one folder per game) or use **Add games → Add a PC game
-folder…**. FramePort asks which program starts the game if it finds more than one.
+Scan a folder of Windows VR games (one folder per game), or **Add games → Add a PC game folder…**. If a game has
+several programs, FramePort asks which program starts the game.

- **Play from this PC** (Windows with Steam and SteamVR): **Install on this PC** adds the game to Steam. Stream it to
-  the Frame with Steam Link.
- **Play on the Frame (experimental):** on the Steam Frame page, install *PC VR games (Proton)*, then click **Install
-  on Frame** on the game's page.
- **Oculus games** (made for Meta's Rift headset) need Revive, which FramePort downloads. Games that check their
-  license through the Oculus app only run on your PC.
+- **Play from this PC** (Windows with Steam and SteamVR): **Install on this PC** adds the game to Steam. Stream the
+  game to the Frame with Steam Link.
+- **Play on the Frame (experimental):** install *PC VR games (Proton)* on the Steam Frame page, then **Install on
+  Frame**.
+- **Oculus games** (made for Meta's Rift) need Revive, which FramePort downloads, and run only on your PC. Games that
+  check their license through the Oculus app need the Oculus app there.

-**Windows games without VR:** use **Add games → Add a PC game folder…** too. The Frame runs them as a window through
-Proton, like Steam's own Windows games. Whether a game runs depends on Proton.
+**Windows games without VR:** also **Add a PC game folder…**. The Frame runs them as a window through Proton.

 ## Linux apps

-**Add games → Add a Linux app…** takes an AppImage (a single-file Linux app) or a `.zip`/`.tar.gz`/`.tar.xz`
-archive; **Add a Linux app folder…** takes an unpacked app. **Install on Frame** uploads it unchanged and adds it to
-the Steam library.
+**Add games → Add a Linux app…** takes an AppImage or a `.zip`/`.tar.gz`/`.tar.xz` archive; **Add a Linux app
+folder…** takes an unpacked app. **Install on Frame** uploads the app unchanged and adds the app to Steam.

- Apps built for **arm64** (the Frame's processor) run directly. Apps built for **x86_64** (most PCs) run through FEX,
-  a translator Steam installs on the Frame the first time; they run slower. The game page shows which kind you have.
- If the app needs libraries the Frame doesn't have, the game page lists them: look for a build that includes them.
- Linux apps also appear in **Desktop Mode**'s app menu. Turn this off on the game
-  page (**Desktop Mode**).
- **SteamVR overlay apps** (a wrist watch, a performance display: programs that draw over games instead of being
-  one) are registered with the Frame's SteamVR, which shows them over whatever you play, Quest and PC VR games
-  alike. FramePort recognises them by the `.vrmanifest` file they ship. By default they start by themselves whenever
-  SteamVR starts (**SteamVR overlay → Start with SteamVR** on the game page; a small FramePort service on the Frame
-  does this, `frameport-vr-overlays`); otherwise start the app from your library before the game. Windows overlay
-  apps get the patch **SteamVR overlay app (Frame)**.
+- **arm64** builds run directly. **x86_64** builds run through FEX, which Steam installs the first time; they're
+  slower. The game page shows which you have.
+- Missing libraries are listed on the game page: look for a build that includes them.
+- Linux apps also appear in Desktop Mode's app menu (switch **Desktop Mode** on the game page).
+- **SteamVR overlay apps** (a wrist watch, a performance display) show over any game. They start with SteamVR
+  (**Start with SteamVR** on the game page). Windows overlay apps use the patch **SteamVR overlay app (Frame)**.

 ## Files on the Frame

@@ -280,27 +247,25 @@ The **Files** tab copies files between your PC and the Frame: videos, documents,

 ![Files](images/files.png)

- Use **Upload files**, **Upload folder** and **New folder**; right-click an entry to download, rename or delete
-  it. Drag across entries to select several.
- In the downloaded app you can drag files from your PC onto the list.
- **Videos**, **Downloads** and **Documents** are shared by every Quest game (inside the game: `/sdcard/Movies`,
-  `/sdcard/Download`, `/sdcard/Documents`).
- **Game storage** holds each game's own files. A game's menu → **Add videos and files…** opens it.
+- **Upload files**, **Upload folder**, **New folder**; right-click to download, rename or delete. Drag across
+  entries to select several. In the downloaded app you can also drag files onto the list.
+- **Videos**, **Downloads** and **Documents** are shared by every Quest game (`/sdcard/Movies`, `/sdcard/Download`,
+  `/sdcard/Documents` inside the game).
+- **Game storage** holds each game's own files (game menu → **On the Frame** → **Add videos and files**).

 ## Backing up saves

-Steam doesn't sync Quest games' saves. **Back up saves** next to **Play** on a game's page copies them to your PC
-(close the game first; also in the game's menu → **Saves**); **Back up all saves** on the Steam Frame page does every
-installed Quest game. The game's menu (right-click it, or **…** on its page) → **Saves** → **Restore saves…** puts a backup back on the Frame and keeps a copy of the replaced saves there (**Undo last
-restore**). Backups live in FramePort's data folder under `save-backups/`; the 10 newest per game are kept (Settings →
-Data). Caches and large downloaded content stay out. More in the [FAQ](FAQ.md#can-i-back-up-a-games-saves).
+Steam doesn't sync Quest games' saves. **Back up saves** next to **Play** copies them to your PC (close the game
+first); **Back up all saves** on the Steam Frame page does every game. Game menu → **Saves** → **Restore saves…** puts
+one back. Settings → **Data** sets the folder, how many to keep and automatic backups.
+[FAQ](FAQ.md#can-i-back-up-a-games-saves).

 ## Share a recipe or report a problem

- **Share working recipe…** (on the game's page, under **What FramePort will do**) opens a GitHub issue with the
-  game's recipe filled in. Accepted recipes become built-in for everyone. Untested games ask how they run after you install or test them.
- **Report a problem…** (in the game's menu, or Settings → Problems and feedback) saves a diagnostics zip with
-  personal data removed and opens a GitHub issue to attach it to.
+- **Share working recipe…** (game menu → **Recipe**) opens a GitHub issue with the game's recipe filled in. Accepted
+  recipes become built-in for everyone.
+- **Report a problem…** (game menu → **Troubleshoot**, or Settings → Problems and feedback) saves a diagnostics zip
+  without personal data and opens a GitHub issue to attach the zip to.

 Without the app: [share a recipe](https://github.com/spoopyghosty0/frameport/issues/new?template=working-config.yml)
 · [report a problem](https://github.com/spoopyghosty0/frameport/issues/new?template=bug-report.yml).
@@ -308,45 +273,44 @@ Without the app: [share a recipe](https://github.com/spoopyghosty0/frameport/iss
 ## Uninstalling

 Settings → **Uninstall FramePort…** removes FramePort's data and, if you choose, its games on the Frame (saves can be
-kept). It first saves your signing keys to Documents: you need them to update your games later. Then delete the
+kept). The uninstaller first saves your signing keys to Documents; you need them to update your games later. Then delete the
 FramePort folder.

 ## Verify a download

-`SHA256SUMS.txt` in each release lists the files' checksums: `sha256sum -c SHA256SUMS.txt`. Each file also has a
-GitHub build attestation (proof that GitHub built it from this repository):
-`gh attestation verify FramePort-windows-x64.zip -R spoopyghosty0/frameport`.
+- `sha256sum -c SHA256SUMS.txt` checks the files against the release's checksums.
+- `gh attestation verify FramePort-windows-x64.zip -R spoopyghosty0/frameport` checks that GitHub built the file from
+  this repository.
+- Windows: to show FramePort as the publisher, import `FramePort-selfsigned.cer` (attached to each release) into
+  *Trusted Root Certification Authorities* (Current User). The certificate can only sign code; remove the certificate with `certmgr.msc`.
+  SHA-256 fingerprint:
+  `4E:12:98:91:62:C0:E4:50:FB:65:1D:34:BB:73:00:09:7B:78:BE:88:5C:A7:6C:42:23:46:9B:92:A1:59:A7:6E`.

-Windows: to show FramePort as the publisher, import `FramePort-selfsigned.cer` (attached to each release) into
-*Trusted Root Certification Authorities* (Current User). The certificate can only sign code; remove it with
-`certmgr.msc`. Its SHA-256 fingerprint:
-`4E:12:98:91:62:C0:E4:50:FB:65:1D:34:BB:73:00:09:7B:78:BE:88:5C:A7:6C:42:23:46:9B:92:A1:59:A7:6E`.
+## Command line

-## For power users: the command line
-
-The **command-line version** (Python 3.11 or newer) installs from the release's
-`frameport-<version>-py3-none-any.whl` with `uv tool install <link>` (or pipx or pip).
-
-Everything the app does is also a `frameport` command; `frameport --help` and `frameport <command> --help` list every
-option. The main ones:
+The command-line version (Python 3.11 or newer) installs from the release's `frameport-<version>-py3-none-any.whl`
+with `uv tool install <link>` (or pipx or pip). `frameport --help` and `frameport <command> --help` list every
+option. The main commands:

 | Command | What it does |
 |---|---|
 | `scan <folder>` / `list` / `show <game>` | add games, list the library, show a game's patches |
-| `folders [--add <folder>] [--remove <folder>]` / `rescan` | list the library folders, add or remove one (its games stay); scan them again for new and moved games |
+| `rename <game> "<name>"` | rename a game (`--reset`: back to the automatic name) |
+| `folders [--add <folder>] [--remove <folder>]` / `rescan` | manage library folders; scan them again |
 | `add-linux <path> [--exe <program>]` | add a Linux app (AppImage, folder or archive) |
-| `new-version <game> <path>` | point a game at its newer version (APK, Linux app file/folder, PC VR game folder) |
-| `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them all) |
-| `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc` for this PC), launch test |
+| `new-version <game> <path>` | point a game at its newer version |
+| `recipe <game> --enable/--disable <patch>` | change a game's patches (`patches` lists them) |
+| `build <game>` / `install <game>` / `test <game>` | build, install on the Frame (`--to pc`: this PC), launch test |
+| `session <game>` / `settings <game> <key>=<value>` | check the last play session; change a game setting without rebuilding |
 | `frame discover` / `frame connect` / `frame info` | find, connect to and describe the Frame |
-| `frame send <files> --dest videos` / `frame storage` / `frame cleanup` | copy files to the Frame, list where they can go, free space |
-| `frame drives` / `frame move <game> --to <drive>` / `install --dest <drive>` | list the Frame's drives, move a game, install to a drive |
-| `saves backup <game>\|--all` / `saves list <game>` / `saves restore <game> [n]` / `saves undo <game>` | back up Quest games' saves to this PC, restore one, undo the last restore |
+| `frame send <files> --dest videos` / `frame storage` / `frame cleanup` | copy files to the Frame, list targets, free space |
+| `frame drives` / `frame move <game> --to <drive>` / `install --dest <drive>` | list drives, move a game, install to a drive |
+| `saves backup <game>\|--all` / `saves list` / `saves restore` / `saves undo` | back up and restore Quest games' saves |
 | `tools status` / `tools install` | the tools FramePort downloads |
-| `open-link "<link>"` | install from an install button's address or a download link (`--yes`, `--no-install`) |
+| `open-link "<link>"` | install from an install link (`--yes`, `--no-install`) |
 | `diag report <game>` / `share-recipe <game>` | report a problem / share a working recipe |
-| `update` | update FramePort (`--check` only checks: exit code 10 = update available) |
+| `update` | update FramePort (`--check`: exit code 10 = update available) |
 | `uninstall-app` | uninstall FramePort |

-Exit codes: 0 done, 1 failed, 2 wrong usage. `FRAMEPORT_DEBUG=1` shows full error details;
-`FRAMEPORT_NO_UPDATE_CHECK=1` turns update checks off.
+Exit codes: 0 done, 1 failed, 2 wrong usage. `FRAMEPORT_DEBUG=1` shows full errors; `FRAMEPORT_NO_UPDATE_CHECK=1`
+turns update checks off.
@@ -1,8 +1,7 @@
 # Install button

-A button for web pages and READMEs that opens a game straight in FramePort. Clicking it hands FramePort an install
-link; FramePort shows what it would download and asks before it does anything (see
-[Install links](INSTALL.md#install-links-install-with-frameport-buttons)).
+A button for web pages and READMEs that opens a game in FramePort. FramePort shows what it would download and asks
+before doing anything ([Install links](INSTALL.md#install-links-install-with-frameport-buttons)).

 <p>
  <img src="badges/install-with-frameport-animated.svg" alt="Install with FramePort" width="216" height="60">
@@ -12,27 +11,26 @@ link; FramePort shows what it would download and asks before it does anything (s

 All files are in [`docs/badges/`](badges/). Each SVG is self-contained (no external fonts or images), 216 × 60.

-| File | Use it for |
+| File | Use for |
 |---|---|
 | [`install-with-frameport.svg`](badges/install-with-frameport.svg) | Everywhere. No motion. |
-| [`install-with-frameport-animated.svg`](badges/install-with-frameport-animated.svg) | GitHub READMEs and other pages that only allow images. The glow plays by itself every 6 seconds. |
-| [`install-with-frameport-hover.svg`](badges/install-with-frameport-hover.svg) | Websites where you can paste HTML. It glows while the pointer is on it, but only when its SVG code is in the page itself (see below). |
-| [`install-with-frameport@2x.png`](badges/install-with-frameport@2x.png) | Places without SVG support (some forums, email). 432 × 120; show it at 216 × 60. |
+| [`install-with-frameport-animated.svg`](badges/install-with-frameport-animated.svg) | GitHub READMEs and other image-only pages. Glows every 6 seconds. |
+| [`install-with-frameport-hover.svg`](badges/install-with-frameport-hover.svg) | Websites where you can paste HTML. Glows under the pointer, only when the SVG code is in the page ([below](#on-a-website)). |
+| [`install-with-frameport@2x.png`](badges/install-with-frameport@2x.png) | Places without SVG (some forums, email). 432 × 120; show the PNG at 216 × 60. |

-Both animated versions stop moving for visitors who turn on reduced motion in their system settings.
+The animated versions stand still for visitors who turn on reduced motion.

 ## The link

-The button links to FramePort's install page, which names either a manifest or one file:
+The button links to FramePort's install page with a manifest or one file:

 ```
 https://frameport.app/install?manifest=<URL-encoded https address of a manifest .json>
 https://frameport.app/install?url=<URL-encoded https address of an .apk, a Linux build (.zip, .tar.*, .AppImage) or a Windows .exe>
 ```

-The page shows what the link installs, opens FramePort with the matching `frameport://` link and, when FramePort
-isn't installed, offers the download. Pages that only target people who already have FramePort can link to the
-`frameport://` form directly:
+The page shows what the link installs, opens FramePort, and offers the download when FramePort isn't installed. For
+people who already have FramePort you can link to the `frameport://` form directly:

 ```
 frameport://install?manifest=<URL-encoded https address of a manifest .json>
@@ -51,26 +49,24 @@ The manifest:
 }
 ```

-`name` becomes the game's title in Steam. `sha256` is optional but recommended: FramePort checks the download
-against it. The `frameport` object is optional; its icon and description are shown in the
-install question. Only public `https://` addresses are accepted.
-
-`version` is optional (it can also go inside the `frameport` object) and makes updates possible: FramePort remembers
-the manifest's address and version, fetches the manifest again at start (at most every 6 hours) and, when its
-`version` is newer, offers to download and install the update (Library bar and the game's page; CLI
-`frameport link-updates [--install]`). Keep the manifest at the same address and raise `version` with every build.
-Versions compare number by number (`1.10` > `1.9`), and a suffix sorts before the plain release (`1.2.0-beta2` <
-`1.2.0`). Bare file links (`?url=…`) and manifests without a version are never checked.
+- `name` becomes the game's title in Steam.
+- `sha256` is optional but recommended: FramePort checks the download against it.
+- `frameport` is optional: the icon and description are shown in the install question.
+- `version` is optional (`version` can also go inside `frameport`) and enables updates. FramePort fetches the manifest again
+  at most every 6 hours and offers newer versions (Library bar, game page, `frameport link-updates [--install]`).
+  Keep the manifest at the same address and raise `version` with every build. Versions compare number by number
+  (`1.10` > `1.9`); a suffix sorts before the release (`1.2.0-beta2` < `1.2.0`). Bare file links (`?url=…`) and
+  manifests without a version are never checked.
+- Only public `https://` addresses are accepted.

 To build a link from Python: `frameport.deeplink.make_link(manifest_url="https://…/my-game.json")`.

 **Where to host the manifest.** The install page shows the manifest's name, description and icon only when the
-manifest's host lets web pages read it (CORS); otherwise it shows "A game or app" (FramePort itself reads any public
-address). On GitHub, commit the manifest to the repository and link it as a file: `https://raw.githubusercontent.com/
-<owner>/<repo>/main/my-game.json`, or the `https://github.com/<owner>/<repo>/blob/main/my-game.json` page address,
-which the page and FramePort turn into the raw address. A manifest attached to a GitHub release
-(`…/releases/download/…`) installs fine, but web pages can't read it: the page then shows the release's name from
-GitHub's API instead.
+manifest's host allows web pages to read the manifest (CORS); otherwise the page shows "A game or app". FramePort itself reads any public address.
+On GitHub, commit the manifest and link the raw file
+(`https://raw.githubusercontent.com/<owner>/<repo>/main/my-game.json`) or the file's `…/blob/main/my-game.json` page,
+which FramePort turns into the raw address. A manifest attached to a GitHub release installs fine, but the page then shows the
+release's name instead.

 ## On a website

@@ -91,21 +87,19 @@ give the link an accessible name:
 </a>
 ```

-Host the files yourself, or load them from jsDelivr, which serves them with the right content type:
-`https://cdn.jsdelivr.net/gh/spoopyghosty0/frameport@main/docs/badges/install-with-frameport.svg` (replace `main`
-with a release tag such as `v1.0.0` to pin a version; jsDelivr caches `@main` for up to 12 hours).
+Host the files yourself, or load them from jsDelivr:
+`https://cdn.jsdelivr.net/gh/spoopyghosty0/frameport@main/docs/badges/install-with-frameport.svg`. Replace `main`
+with a release tag such as `v1.0.0` to pin a version (jsDelivr caches `@main` for up to 12 hours).

 ## In a GitHub README

-GitHub removes links that don't start with `https://` or `http://` from READMEs, so a `frameport://` link there is
-not clickable. Use the `https://frameport.app/install?…` link:
+GitHub removes `frameport://` links from READMEs. Use the `https://frameport.app/install?…` link with the animated or
+still SVG (the hover version doesn't react on GitHub):

 ```markdown
 [![Install with FramePort](https://cdn.jsdelivr.net/gh/spoopyghosty0/frameport@main/docs/badges/install-with-frameport-animated.svg)](https://frameport.app/install?manifest=https%3A%2F%2Fexample.com%2Fmy-game.json)
 ```

-Use the animated or still SVG: GitHub shows SVGs as images, so the hover version doesn't react there.
-
 ## Testing your setup

 The example button on [frameport.app](https://frameport.app/#button) uses a demo link:
@@ -114,20 +108,18 @@ The example button on [frameport.app](https://frameport.app/#button) uses a demo
 https://frameport.app/install/?manifest=https%3A%2F%2Fframeport.app%2Fdemo%2Fcool-game.json
 ```

-Click it to check that FramePort receives install links on your PC. FramePort recognises this one address and shows
-a demo install question for a placeholder game, "Cool Game"; nothing is downloaded, added to the library or
-installed (`frameport open-link` says it's the demo link and stops). Real buttons install real games.
+Click the button to check that FramePort receives install links on your PC. FramePort shows a demo install question for "Cool Game";
+nothing is downloaded or installed (`frameport open-link` says the link is the demo and stops).

 ## If a visitor doesn't have FramePort

-The `https://frameport.app/install?…` link handles this: its page offers the download and a second try. A bare
-`frameport://` link does nothing visible (or shows the browser's "no app for this link" message) when FramePort
-isn't installed; put a line next to such a button, for example "Needs [FramePort](https://frameport.app)". On macOS, web pages can't hand links to FramePort yet: users paste the link into Add games →
-Add from a link….
+The `https://frameport.app/install?…` link handles a missing FramePort: the install page offers the download. A bare `frameport://` link does
+nothing visible without FramePort, so add a line such as "Needs [FramePort](https://frameport.app)". On macOS, web
+pages can't hand links to FramePort yet: users paste the link into **Add games → Add from a link…**.

 ## Usage rules

 - Keep the alt text "Install with FramePort".
- Don't recolor, stretch, crop or redraw the button, and don't show it smaller than 40 px tall.
- Leave some space around it (at least 8 px) so it doesn't touch other buttons.
- It works on light and dark pages as it is; there is no light version.
+- Don't recolor, stretch, crop or redraw the button, and don't show the button smaller than 40 px tall.
+- Leave at least 8 px of space around the button.
+- The button works on light and dark pages as it is; there is no light version.
@@ -1,7 +1,9 @@
 # Porting playbook

-Everything here was hit while porting Quest and Rift games to the Steam Frame (September–October 2026; 38 catalog recipes). The machine-readable
-version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); keep both in sync.
+Symptoms, causes and fixes found while porting Quest and PC VR games to the Steam Frame since September 2026. The
+machine-readable version is `catalog/triage.yaml` (used by launch tests, session triage and `frameport test`); keep
+both in sync. Rows name the GitHub issue (#N) where a problem was reported; [DEVICE_NOTES.md](DEVICE_NOTES.md) has the
+longer investigations.

 ## Fast path for a new game
 1. `frameport scan <folder>` → check the suggested recipe (`frameport show <pkg>`). Direct-VrApi engines get the bridge.
@@ -12,28 +14,28 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke

 ## Startup failures (visible in launch.log)
 | Symptom | Cause | Fix |
-| `RuntimeManifestFile::FindManifestFiles - using global runtime file /vendor/etc/openxr/1/active_runtime.json`, no FrameBridge lines (#254) | Embedded Khronos loader bypasses the APK loader chain | `frame.static_openxr_loader`: redirect its manifest paths and broker authorities, bundle runtime shim + inner loader + FrameBridge; reinstall to write `/sdcard/fp_openxr_runtime.json`. Device check pending |
 |---|---|---|
+| `RuntimeManifestFile::FindManifestFiles - using global runtime file /vendor/etc/openxr/1/active_runtime.json`, no FrameBridge lines (#254) | Embedded Khronos loader bypasses the APK loader chain | `frame.static_openxr_loader`: redirect its manifest paths and broker authorities, bundle runtime shim + inner loader + FrameBridge; reinstall to write `/sdcard/fp_openxr_runtime.json`. Device check pending |
 | Valve foveation sharp centre moves to the top right or a white line appears at the right edge as Batman shrinks its projection rect (#406 / #394) | Dynamic resolution draws a corner-anchored subrect inside the full swapchain used by Valve FDM | Enable `adapter.fixed_resolution` (Game settings → Picture), rebuild/reinstall for the new adapter and OVRPlugin shim; verify `fixed_resolution: recommended ... -> ...` and full-size `projection view ... rect change` logs. Headset verification pending; more GPU load |
 | Quest 3-only options missing; OVRPlugin logs `venderId 10291, systemName Oculus Quest2` (#373, Asgard's Wrath 2) | OVRPort's dispatcher overwrites FrameBridge's name and supplies a Quest 2 `XR_META_headset_id`; OVRPlugin prioritizes that UUID | `device.headset_model`: Quest 3 by default, per-game Quest 3S / Quest Pro / Quest 2; rebuild the APK. Byte-checked dispatcher name + UUID edit; Quest 2 leaves the dispatcher unchanged. See DEVICE_NOTES 'Per-game headset identity' |
-| Startup exits through `libxlua.so (lj_err_throw)`, then Unity aborts in mutex cleanup; captured Lua error is `bad light userdata pointer` (GitHub #257, BattleTalent 4.7) | This older LuaJIT encodes lightuserdata in 47 bits; Frame supplies valid wider native pointers. Controlled tests with the unchanged library pass a real low-address allocation and fail its own high-address static pointer | `frame.luajit_pointers` automatically selects a full-pointer Lua engine only for the verified library SHA-256, retaining xLua bindings and custom helpers. The scoped patch reaches OpenXR startup for 60 s headless; rendering and gameplay remain unverified. A `lj_err_throw` cleanup stack without the original error message is insufficient to infer this cause |
+| Startup exits through `libxlua.so (lj_err_throw)`, then Unity aborts in mutex cleanup; captured Lua error is `bad light userdata pointer` (GitHub #257, BattleTalent 4.7) | The game's older LuaJIT encodes lightuserdata in 47 bits; Frame supplies valid wider native pointers. Controlled tests with the unchanged library pass a real low-address allocation and fail its own high-address static pointer | `frame.luajit_pointers` automatically selects a full-pointer Lua engine only for the verified library SHA-256, retaining xLua bindings and custom helpers. The scoped patch reaches OpenXR startup for 60 s headless; rendering and gameplay remain unverified. A `lj_err_throw` cleanup stack without the original error message is insufficient to infer this cause |
 | A GL4ES Team Beef game draws stretched triangles or spikes across characters and the scene (GitHub #191, Lambda1VR) | The newer GL shim exports GLES draw functions that intercept GL4ES's desktop OpenGL calls, bypassing its client-array and immediate-mode translation | `frame.tbxr_vendor` keeps the shim's five draw symbols private when the APK bundles `libgl4es.so`. GL queries and single-sampled framebuffer fixes remain active; other games retain the draw hooks. A/B eye captures on SteamOS 0.4.5: old shim normal, current shim spikes, current shim with private draw symbols normal at ~72 fps. Worn-headset gameplay still needs confirmation |
 | A Team Beef game reports a crash after manually quitting: `fdm_injection_xrDestroySwapchain` → `TBXR_LeaveVR` (GitHub #191, Lambda1VR) | Valve's foveation layer dereferences a null pointer during swapchain cleanup | Triage `tbxr-fdm-shutdown-crash` identifies this as a teardown crash, separate from startup and distorted geometry. No verified cleanup fix yet |
 | Conversion fails with `NoSuchElementException: Sequence is empty` in `PatcherContext.appName` (GitHub #269, Accounting+) | OVRPort assumes an application label exists; some APKs only label their activity | FramePort retries that exact failure once using a temporary APK whose application inherits the activity's label; existing labels and the original APK are kept |
 | Updating a flat Android app after saving its recipe fails with `no OVRPort patches selected` (GitHub #271, Plezy) | older FramePort loads the saved recipe without restoring its unchanged-install setting or applying the flat-app build rules, then tries an empty VR conversion | update FramePort: saved recipes keep `as_is`, and flat apps still skip OVRPort; existing catalog-derived recipes refresh at the next app update. Until then, enable "Install as is" for an app whose APK needs no fixes |
 | A launch test suggests a patch (for example triage `sdl-no-clipboard` → `frame.sdl_clipboard`) but the game page doesn't show it / lists it as not applicable; or a game added long ago lacks warnings newer ones get (Android version, web wrapper, missing OBB) (GitHub #104, Dramatic Shape) | the library entry was analyzed by an older FramePort: the analysis field the patch reads (`sdl_java`, `min_sdk`, `web_wrapper`, `expects_obb`, …) is missing, so `applies()` is false | entries whose `analysis.extra.analysis_version` is below `detect.ANALYSIS_VERSION` are analyzed again at the GUI's start (background) and before a build (`pipeline.refresh_analyses`); by hand: game menu → "Analyze again", then Update on Frame. An unreadable APK is marked `analysis_failed` (retried after the next version bump). Adding an analysis field: bump `ANALYSIS_VERSION` |
 | Foveation full-resolution area looks identical at 10% and 45% (GitHub #394), while render resolution changes it | `FOVE_INNER`/`FOVE_OUTER` are neither passed through by Lepton nor read by Valve's layer; shared injection uses rectangular density presets | Game settings → Picture now exports named `FOVE_LEVEL=lo/med/hi`; Default preserves the runtime choice. Medium/high shrink the center and reduce peripheral density further. Legacy radius preferences map to the nearest old nominal preset. Compare Fixed + Darken coarse fragments with adapter `snapshot=N` at a fixed render resolution; see FRAME_RUNTIME.md for addresses and profile data. Agent launcher allowlist needs `FOVE_LEVEL`. |
-| Valve foveation's sharp area sits off-centre in both eyes (bottom right in In Death: Unchained / The 7th Guest, towards the swapchain centre with dynamic resolution or asymmetric eye rects), Eye-tracked or Fixed (GitHub #394) | Valve's density map covers the whole swapchain with its sharp rectangle at the swapchain centre; the game's view is a smaller or shifted imageRect and the eye's optical axis isn't the rect centre (asymmetric FOV) | Rebuild (Update on Frame): the arm64 FrameBridge build's `VK_LAYER_FRAMEPORT_fdm_centre` (native/foveation/centre.h) sits below Valve's layer and moves each eye's map to its optical centre (Fixed, run on Valve's offset path: Valve's own `disable_offsets` path crashed AC Nexus) or re-bases the gaze on the eye's rect (Eye-tracked); it never changes images and writes every offset Turnip reads (Valve declares 1 for two views). launch.log: `FrameBridge: fdm views: …` and `fdm_centre: pass WxH map … -> x,y`. Check headlessly with Darken coarse fragments + `snapshot=N` (Vulkan: `fb_snap_vk_N_vV.ppm`). `FRAMEPORT_FDM_CENTRE=0` (launcher `LEPTON_ENV_`) turns it off for comparison. The area's size still snaps to Turnip's GMEM bins (density is chosen per bin), so it changes somewhat with render resolution; that part isn't fixable in FramePort |
+| Valve foveation's sharp area sits off-centre in both eyes (bottom right in In Death: Unchained / The 7th Guest, towards the swapchain centre with dynamic resolution or asymmetric eye rects), Eye-tracked or Fixed (GitHub #394) | Valve's density map covers the whole swapchain with its sharp rectangle at the swapchain centre; the game's view is a smaller or shifted imageRect and the eye's optical axis isn't the rect centre (asymmetric FOV) | Rebuild (Update on Frame): the arm64 FrameBridge build's `VK_LAYER_FRAMEPORT_fdm_centre` (native/foveation/centre.h) sits below Valve's layer and moves each eye's map to its optical centre (Fixed, run on Valve's offset path: Valve's own `disable_offsets` path crashed AC Nexus) or re-bases the gaze on the eye's rect (Eye-tracked); the layer never changes images and writes every offset Turnip reads (Valve declares 1 for two views). launch.log: `FrameBridge: fdm views: …` and `fdm_centre: pass WxH map … -> x,y`. Check headlessly with Darken coarse fragments + `snapshot=N` (Vulkan: `fb_snap_vk_N_vV.ppm`). `FRAMEPORT_FDM_CENTRE=0` (launcher `LEPTON_ENV_`) turns it off for comparison. The area's size still snaps to Turnip's GMEM bins (density is chosen per bin), so the area changes somewhat with render resolution; the bin snapping isn't fixable in FramePort |
 | FDM layer loads but diagnostic logging reports `fdm_injection_CreateInstance: skipped` | Layer loading alone does not enable injection on the tested SteamOS 0.4.5 build; a skipped helper instance alone also does not establish game-wide inactivity | Opt-in `device.foveation` mode `tracked`: loads Valve's layer and sets `FDM_DEBUG=enable`. Batman probe reached foveated render passes with changing per-eye offsets. Validate graphics and matched gameplay GPU time; do not enable globally. Use `debug` only for brief diagnostics, preserving existing flags; never benchmark with debug spam. See FRAME_RUNTIME.md. |
-| One eye (usually the right) shimmers or jitters in the 3D view while menus and panels look steady; pacing is clean (GitHub #69, e.g. RTCWQuest, Moss) | Valve's eye-tracked foveation layer (`VALVE_fdm_injection`) moves its low-density regions with each eye's gaze, and the right eye's gaze filter restarts often (`CEyePoseUKF R: Large dt … Bootstrapped` in `~/.local/share/Steam/logs/eyetracking.txt`) | Game settings → Picture → "Foveated rendering (Valve)": **Fixed** (`FDM_DEBUG=disable_offsets`; verify injection remains active on the installed runtime) or **Off** (`VK_INSTANCE_LAYERS=""`); catalog field `foveation:` |
+| One eye (usually the right) shimmers or jitters in the 3D view while menus and panels look steady; pacing is clean (GitHub #69, for example RTCWQuest, Moss) | Valve's eye-tracked foveation layer (`VALVE_fdm_injection`) moves its low-density regions with each eye's gaze, and the right eye's gaze filter restarts often (`CEyePoseUKF R: Large dt … Bootstrapped` in `~/.local/share/Steam/logs/eyetracking.txt`) | Game settings → Picture → "Foveated rendering (Valve)": **Fixed** (`FDM_DEBUG=disable_offsets`; verify injection remains active on the installed runtime) or **Off** (`VK_INSTANCE_LAYERS=""`); catalog field `foveation:` |
 | With `device.foveation` Eye-tracked/Fixed, the sharp area looks right but everything around it is black with scattered coloured blocks (menus on quads too); pacing fine (GitHub #303, Medieval Dynasty; Vampire Survivors reported the same) | Unity's Oculus XR plugin asks for SUBSAMPLED eye images (`XR_META_vulkan_swapchain_create_info`, `VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT`); under Valve's FDM their coarse areas stay in the compact subsampled layout, which the compositor reads as an ordinary image. `foveation_fix=1` only dropped the `XrSwapchainCreateInfoFoveationFB` nodes and passed the META node on. With `foveation_fix=0` + `foveation_storage_fix=1` the adapter logs `foveation_storage_fix: shared allocation SUBSAMPLED cleared` for the eye swapchains | `device.foveation` (tracked/fixed) now also sets `foveation_storage_fix=1`, which clears SUBSAMPLED whatever `foveation_fix` is (generic version of Batman's OVRPlugin allocation fix). Rebuild + reinstall (new adapter). Headless-checked only (72 fps, bit cleared); picture needs the headset |
 | A Unity OpenXR game closes right after the OpenXR instance is created: `F VrApiLoader: vrapi_SetPropertyInt was called before vrapi_Initialize()!`, SIGABRT on UnityMain (GitHub #62, Jurassic World Aftermath) | the APK still ships Meta's VrApi loader; OVRPlugin (1.89, on OpenXR) calls it without starting VrApi and Meta's loader aborts. The VrApi bridge can't replace it (39 of the loader's 114 functions: OVRPlugin wouldn't link) | `frame.vrapi_stub` (same exports, each returns 0); triage `vrapi-before-init` |
 | A VrApi game exits at once: `UnsatisfiedLinkError … dlopen failed: cannot locate symbol "vrapi_PollEvent"` (GitHub #57, BlazeRush) | the engine imports a VrApi function the VrApi bridge didn't implement | the bridge has `vrapi_PollEvent`, `RecenterPose`, `SetDisplayRefreshRate`, `GetSystemPropertyFloatArray` (rebuild the game); the static check "VrApi functions resolvable" names any other missing one; triage `vrapi-symbol-missing` |
 | A Team Beef port (Lambda1VR, RTCWQuest, …) exits at once: `UnsatisfiedLinkError: dlopen failed: library "libopenxr_loader_valve.so" not found` (GitHub #59) | TBXR loads `openxr_loader_<Build.MANUFACTURER>` (Lepton: valve) and takes the Meta path only when `strstr(OPENXR_HMD, "meta")` matches, else Pico's | `frame.tbxr_vendor` (empty `libopenxr_loader_valve.so` + the "meta" literal → "alve"). Game data (`xash/`, …) goes to /sdcard: upload it with the Files tab to the game's storage. Black eyes with `TBXR: Incomplete frame buffer object: GL_FRAMEBUFFER_INCOMPLETE_MULTISAMPLE`: TBXR always uses multisampled render-to-texture (even `--msaa 1`); `frame.tbxr_vendor` links the GL shim, which hands it single-sampled versions (log `GL shim: multisampled render-to-texture … drawn single-sampled`) |
-| A Quest game renders, then logs `Entitlement check failed` / `ovrPlatformInitialize_NotEntitled` (often with retries) and quits, e.g. `SIG: 9` after `[Photon] Disconnected` (GitHub #322, Deadly Delivery) | The game's Meta licence check (entitlement) needs Meta's online login, which the Frame doesn't have; online-only games quit (triage `meta-entitlement`) | None: FramePort doesn't get around entitlement checks. Offline games that log it and play on are fine |
-| Black screen after VR starts; `Asset status error  (code 100)` in `DLC_Manager:AssetStatusCallback` (GitHub #203, e.g. PixelRipped 1995) | Meta asset-file status fails after entitlement succeeds; the log does not identify the native call or asset ID | Try `frame.asset_files_stub` (opt-in, triage-only): native/langpack answers GetList with an empty successful list and StatusById with installed status, an empty path and the requested ID. No DLC files are supplied; download requests retain their existing behavior. Disable with `FRAMEPORT_ASSET_FILES_STUB=0`. Host-tested only; whether this fixes startup needs a game/device test |
-| A Unity Quest game stays on a loading screen or doesn't go on; `An unknown error occurred. Request failed.` from `Oculus.Platform.Request`1:OnComplete` (GitHub #346 Eleven, #360 Spectre, #368 Thief Simulator; triage `meta-request-failed`) | A Meta platform call the game waits for got no usable answer: OVRPort's platform library answers some calls without Meta's services (request id 0) and Meta's Unity wrapper drops the callback | Find the call in the stack (the game's own coroutine after `OnComplete`); a per-game fix that skips it when it isn't needed to play (e.g. an analytics id request). Calls the game needs online stay unsupported |
-| Game aborts at start: `OVRPlatform-Loader: DisplayErrorAndExit: Failed to launch SystemActivities` after an `ActivityNotFoundException` stack (GitHub #357 Breachers; triage `meta-system-activities`) | The game ships its own renamed copy of Meta's platform loader (e.g. `libovr_custom.so`), which bypasses OVRPort's dispatcher and tries to open Meta's system activities (Horizon OS) | None in general: such games are online games built on Meta's services. Serving OVRPort's dispatcher under that name is possible but unlikely to make them playable |
+| A Quest game renders, then logs `Entitlement check failed` / `ovrPlatformInitialize_NotEntitled` (often with retries) and quits, for example `SIG: 9` after `[Photon] Disconnected` (GitHub #322, Deadly Delivery) | The game's Meta licence check (entitlement) needs Meta's online login, which the Frame doesn't have; online-only games quit (triage `meta-entitlement`) | None: FramePort doesn't get around entitlement checks. Offline games that log it and play on are fine |
+| Black screen after VR starts; `Asset status error  (code 100)` in `DLC_Manager:AssetStatusCallback` (GitHub #203, for example PixelRipped 1995) | Meta asset-file status fails after entitlement succeeds; the log does not identify the native call or asset ID | Try `frame.asset_files_stub` (opt-in, triage-only): native/langpack answers GetList with an empty successful list and StatusById with installed status, an empty path and the requested ID. No DLC files are supplied; download requests retain their existing behavior. Disable with `FRAMEPORT_ASSET_FILES_STUB=0`. Host-tested only; whether this fixes startup needs a game/device test |
+| A Unity Quest game stays on a loading screen or doesn't go on; `An unknown error occurred. Request failed.` from `Oculus.Platform.Request`1:OnComplete` (GitHub #346 Eleven, #360 Spectre, #368 Thief Simulator; triage `meta-request-failed`) | A Meta platform call the game waits for got no usable answer: OVRPort's platform library answers some calls without Meta's services (request id 0) and Meta's Unity wrapper drops the callback | Find the call in the stack (the game's own coroutine after `OnComplete`); a per-game fix that skips it when it isn't needed to play (for example an analytics id request). Calls the game needs online stay unsupported |
+| Game aborts at start: `OVRPlatform-Loader: DisplayErrorAndExit: Failed to launch SystemActivities` after an `ActivityNotFoundException` stack (GitHub #357 Breachers; triage `meta-system-activities`) | The game ships its own renamed copy of Meta's platform loader (for example `libovr_custom.so`), which bypasses OVRPort's dispatcher and tries to open Meta's system activities (Horizon OS) | None in general: such games are online games built on Meta's services. Serving OVRPort's dispatcher under that name is possible but unlikely to make them playable |
 | Missing sound or extra content in a game whose OBB folder has separate `*.pak` files (GitHub #61, Star Wars: Tales from the Galaxy's Edge: seasons + Wwise banks) | the game asks Meta's platform for these asset files (`ovr_AssetFile_GetList` / `DownloadById`); OVRPort's loader doesn't list them | copy every content/sound-bank PAK and use `frame.asset_files` (native/langpack lists the data's `*.pak` as installed `default` assets, IAP `free`, and answers DownloadById at once with the path; off: env FRAMEPORT_ASSET_FILES=0). Tales also needs the splash and depth-size fixes below |
 | Quest saves need a cloud folder or backups after playing (discussion #352) | Steam does not sync Quest saves | Settings → Data: choose a writable local cloud-sync folder and optionally enable **Back up saves when a game closes**, then connect to apply it. The Frame keeps three changed snapshots per game; FramePort imports them on connection/poll. Manual **Back up saves** is next to Play; Restore stays in the menu. Old backup folders remain available and are never moved silently |
 | A SideQuest backup has `apk/` and a sibling `obb/` with content/sound-bank PAKs, but the Frame only has the main OBB (GitHub #61, Tales from the Galaxy's Edge) | older scans treated that layout as loose expansion files and selected only the named OBBs; the asset-file patch then found no PAKs | the scanner chooses the OBB folder by version first, then keeps the whole sibling data folder when all its expansion files are selected for this APK; app updates repair affected library entries and refresh asset/language-pack detection. Reinstall to copy the missing files, or scan the backup again first. Folders with other packages or unselected OBB versions still send only the selected OBBs |
@@ -41,55 +43,51 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Upper part of the intro/environment is black or clipped, but a separate menu panel is intact (GitHub #61, Tales from the Galaxy's Edge) | `FSceneRenderTargets::AllocMobileMultiViewDepth` caches the initial Android window dimensions (1920x1016/1020), leaving the depth attachment shorter than the eye color texture (1728x1728); drawing is limited by the smaller attachment | `frame.unreal_multiview_depth`: refreshes both cached depth dimensions from the current scene `BufferSize` before allocation. Checks the exported symbol, function size and surrounding instructions, then replaces only the branch that skips refresh. Keeps multiview and multisampling. Headset test: full view and gameplay work |
 | `cannot locate symbol "ovrPeerConnectionState_ToString"` (or another `ovr<Enum>_ToString`) at start (BlazeRush, GitHub #57) | OVRPort's platform loader lacks several Platform SDK enum helpers | `frame.ovrstubs` now stubs them too; `*_ToString` stubs return "" (not NULL) |
 | Exits right after the OpenXR instance is created: `Failed to create XR session: -50` (`XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING`, Lambda1VR) | the game skips `xrGet*GraphicsRequirementsKHR`; Meta's runtime tolerates it, SteamVR's doesn't. Lambda1VR's TBXR doesn't even enable `XR_KHR_opengl_es_enable` (only `XR_EXT_local_floor`) | FrameBridge adds `XR_KHR_opengl_es_enable` when an app enables no graphics API extension, asks for the requirements on the game's behalf and retries xrCreateSession once (logs `added XR_KHR_opengl_es_enable …`, `the app skipped …; asked for it`; every launch logs the final extension list `xrCreateInstance with N extension(s)`); triage `graphics-requirements-missing`. Verified headless: Lambda1VR runs at 72 fps |
-| Exits at start: `OVRAvatar-Loader: DisplayErrorAndExit: Failed to launch SystemActivities` after `ovrAvatar_Initialize: Failed to load AvatarSDK driver` (BlazeRush, GitHub #57) | Meta's avatar loader needs Horizon; it then tries Meta's error screen and aborts | `frame.avatar_stub` (same exports, do nothing); triage `avatar-driver-missing`. Games that ship the library but don't start avatars at launch (Lucky's Tale, BattleSisters, Arcsmith) don't need it |
+| Exits at start: `OVRAvatar-Loader: DisplayErrorAndExit: Failed to launch SystemActivities` after `ovrAvatar_Initialize: Failed to load AvatarSDK driver` (BlazeRush, GitHub #57) | Meta's avatar loader needs Horizon; the loader then tries Meta's error screen and aborts | `frame.avatar_stub` (same exports, do nothing); triage `avatar-driver-missing`. Games that ship the library but don't start avatars at launch (Lucky's Tale, BattleSisters, Arcsmith) don't need it |
 | BlazeRush (GitHub #57, Klownicle's guide): the first menu takes A, the next ignores all input; car bodies and controllers invisible; coloured streaks/flashes from particles; narrow square view; blurry, or displaced with black borders after a scale change | the menus wait for a Meta avatar the stub never delivers; bone indices fed with glVertexAttribPointer (Mesa converts them to floats); mediump particle maths; FOV read once before any session (bridge said 90x90); old program binaries in its shader cache; user_config.xml keeps the old resolution | catalog recipe: `frame.blazerush` (avatar wait NOP + avatar renderer RET + cache folder `cache/br_shader_v1`, exact build only), GL shim `gl_int_attribs=1` + `gl_highp_markers=in uvec2 inBoneIndices;\|uniform InstanceData\|void main()` (`gl_hide_multiview=0`, `gl_hide_msrtt=0` keep its GL as tested), the VrApi bridge's saved FOV (`framebridge-vrapi-fov.txt`; triage `vrapi-fov-before-tracking`), `scale=1.7`, `device.config_sync` (agent writes r_3dwidth/r_3dheight/r_width/r_height from the runtime's eye size × scale before each start); triage `gl-integer-attribs` |
 | Frame freezes or the game is killed (OOM) on the first controller vibration (for example Lucky's Tale's save slots, BattleSisters, Sniper Elite VR's tutorial grab: memory grows ~1 GB/s until the kill) | OVRPort runtimes up to 3.4.3-23204ea read the haptic envelope's duration (ns) as seconds and allocate gigabytes of samples (GitHub #9, ovrport/app#73); also reached from Unity's legacy `ovrp_SetControllerHaptics`; perf page faults all in `libopenxr_loader.so` `xrApplyHapticFeedback` | `adapter.haptic_fix` (envelope → one plain vibration in `native/xrshim`; PCM vibrations (`XrHapticPcmVibrationFB`) are converted the same way). Fixed in runtime 3.4.3-aa54c3f: builds made with it leave the workaround out by themselves (log "not needed: adapter.haptic_fix", `frameport show` "last build left out"); rebuild an older build to switch |
 | Controller vibrations much stronger than on a Quest (The Boys VR, Jurassic World, BONELAB, …) | OVRPlugin games send amplitude envelopes; `haptic_fix` turned each into one vibration at the envelope's *peak* for its whole duration (a short fading pulse became a long full-strength buzz) | `haptic_fix` now uses the envelope's RMS; Game settings → "Vibration strength" (`haptic_scale`, 0-1) scales every vibration in FrameBridge; launch.log shows the first requests (`haptic: …`). OVRPlugin stops a vibration with amplitude 0 (2 s duration): FrameBridge turns that into xrStopHapticFeedback (without it the last buzz ran its full 2 s) |
 | Play or a launch test fails at once: `Game files missing at <path> (storage not mounted?)` in launch.log, or "… files are on a drive that isn't inserted" (GitHub #90) | the game was installed or moved to a microSD card (`<mount>/FramePort/<pkg>`) that isn't inserted or mounted now | insert the card; or move the game back (game menu → Move to…, `frameport frame move <pkg> --to internal`) once the card is back. `frameport frame drives` shows what the agent sees (exFAT/NTFS cards are refused: format in SteamOS) |
-| A Linux app started from Desktop Mode's menu closes after ~2 s, or opens on the wrong display (GitHub #84) | its launcher predates agent v63: the "Steam parent gone" watchdog ended it when Plasma's launcher exited, and it took gamescope's DISPLAY from Steam | connect FramePort once (agent v63's `upgrade_launchers` adds the `FRAMEPORT_DESKTOP` checks; the menu entry runs `env FRAMEPORT_DESKTOP=1 <anchor>/launch.sh`). Game Mode controller problems in such apps are Steam Input's (a separate issue) |
-| A Linux app (AppImage) shows no/FramePort's placeholder icon in Desktop Mode or Steam (GitHub #99) | before agent v64 only FramePort's art set's icon was used, and a lone AppImage has no store art | connect FramePort once (agent v64 copies the app's `.DirIcon` / `.desktop` `Icon=` to `<anchor>/artwork/app-icon.*` and refreshes the menu entry); reinstall to also get it into the library + Steam shortcut. Still the placeholder: check `<base>/app/squashfs-root/.DirIcon` and the `.desktop` file's `Icon=` (an icon outside the app folder or only an XPM isn't used); a chosen icon (`artwork/.icon-source` = `custom`) always wins |
-| An overlay app (fpsVR, a wrist watch) installed on the Frame never appears, or SteamVR doesn't start it | not registered with the Frame's SteamVR, or registered with a manifest SteamVR skips: on the Frame vrserver reads only `binary_path_linux_arm` (vrserver.txt: "must specify binary_path for launch_type binary. Skipping") | `pcvr.vr_overlay` (Windows) / a Linux app with a bundled `.vrmanifest` (`is_dashboard_overlay`): agent v75 `register_vr_overlay` (check `vrcmd --overlays`, `~/.config/openvr/config/appconfig.json` manifest_paths); the app's own `--install` writes binary_path_linux only. fpsVR under Proton never loads OpenVR (quits after 60 s): unsupported for now |
-| An overlay app with **Start with SteamVR** on doesn't start by itself after the Frame or SteamVR starts (it works when started by hand) | SteamVR's own auto-launch flag (SetApplicationAutoLaunch) didn't persist on the Frame (no autolaunch entry in `~/.config/openvr/config/steamvr.vrsettings`) | agent v76: FramePort's service `frameport-vr-overlays.service` starts it at every new vrserver. Check `systemctl --user status frameport-vr-overlays`, `~/.local/share/frameport/vr-overlays.log` (`new SteamVR (vrserver N)` → `<pkg>: started` / `running` / `couldn't start it: …`), the deployment's `overlay.autostart`, and that `~/.local/share/frameport/vr-overlays.disabled` doesn't exist; `frameport frame info` (ensure_host_fixes) installs a missing service |
+| A Linux app started from Desktop Mode's menu closes after ~2 s, or opens on the wrong display (GitHub #84) | an older launcher: the "Steam parent gone" watchdog ended it when Plasma's launcher exited, and it took gamescope's DISPLAY from Steam | connect FramePort once (`upgrade_launchers` adds the `FRAMEPORT_DESKTOP` checks; the menu entry runs `env FRAMEPORT_DESKTOP=1 <anchor>/launch.sh`). Game Mode controller problems in such apps are Steam Input's (a separate issue) |
+| A Linux app (AppImage) shows no/FramePort's placeholder icon in Desktop Mode or Steam (GitHub #99) | older installs used only FramePort's art set's icon, and a lone AppImage has no store art | connect FramePort once (the agent copies the app's `.DirIcon` / `.desktop` `Icon=` to `<anchor>/artwork/app-icon.*` and refreshes the menu entry); reinstall to also get it into the library + Steam shortcut. Still the placeholder: check `<base>/app/squashfs-root/.DirIcon` and the `.desktop` file's `Icon=` (an icon outside the app folder or only an XPM isn't used); a chosen icon (`artwork/.icon-source` = `custom`) always wins |
+| An overlay app (fpsVR, a wrist watch) installed on the Frame never appears, or SteamVR doesn't start it | not registered with the Frame's SteamVR, or registered with a manifest SteamVR skips: on the Frame vrserver reads only `binary_path_linux_arm` (vrserver.txt: "must specify binary_path for launch_type binary. Skipping") | `pcvr.vr_overlay` (Windows) / a Linux app with a bundled `.vrmanifest` (`is_dashboard_overlay`): agent `register_vr_overlay` (check `vrcmd --overlays`, `~/.config/openvr/config/appconfig.json` manifest_paths); the app's own `--install` writes binary_path_linux only. fpsVR under Proton never loads OpenVR (quits after 60 s): unsupported for now |
+| An overlay app with **Start with SteamVR** on doesn't start by itself after the Frame or SteamVR starts (it works when started by hand) | SteamVR's own auto-launch flag (SetApplicationAutoLaunch) didn't persist on the Frame (no autolaunch entry in `~/.config/openvr/config/steamvr.vrsettings`) | FramePort's service `frameport-vr-overlays.service` starts it at every new vrserver. Check `systemctl --user status frameport-vr-overlays`, `~/.local/share/frameport/vr-overlays.log` (`new SteamVR (vrserver N)` → `<pkg>: started` / `running` / `couldn't start it: …`), the deployment's `overlay.autostart`, and that `~/.local/share/frameport/vr-overlays.disabled` doesn't exist; `frameport frame info` (ensure_host_fixes) installs a missing service |
 | Every game suddenly fails to start: `crun: create keyring …: Disk quota exceeded`, `is not a running context` | rootless podman leaked a kernel keyring per launch; 200-key quota exhausted | `keyring = false` in `~/.config/containers/containers.conf` (FramePort agent does it), then reboot the Frame once |
-| Launch test "failed" although the game runs in the headset: frames paced, then `OVRPortVrApi: EnterVrMode: no tracked head pose before deadline`, then a crash (e.g. `zink: DEVICE LOST` + SIGSEGV in a `gdrv` thread) (GitHub #57, BlazeRush) | the VrApi bridge ends the VR session after 30 s without head tracking, which only happens without a worn headset; the game's renderer then crashes while tearing down | none needed: launch tests (`triage(..., headless=True)`) treat an exit or crash after a `headless_end` line (catalog/triage.yaml) as a pass when frames were paced before it (info finding `headless-end`); play sessions ignore it. Add new such markers to `headless_end` |
+| Launch test "failed" although the game runs in the headset: frames paced, then `OVRPortVrApi: EnterVrMode: no tracked head pose before deadline`, then a crash (for example `zink: DEVICE LOST` + SIGSEGV in a `gdrv` thread) (GitHub #57, BlazeRush) | the VrApi bridge ends the VR session after 30 s without head tracking, which only happens without a worn headset; the game's renderer then crashes while tearing down | none needed: launch tests (`triage(..., headless=True)`) treat an exit or crash after a `headless_end` line (catalog/triage.yaml) as a pass when frames were paced before it (info finding `headless-end`); play sessions ignore it. Add new such markers to `headless_end` |
 | Launch test EXITED, launch.log has `Target app (<pkg>) did not start` and no `Start proc …:<pkg>` (GitHub #179) | Lepton occasionally doesn't start the app on the first start after an APK change; Android's `WebViewLoader-: System.exit` at boot is not the game (triage `app-not-started`) | start it again |
 | A game keeps no progress between starts although it saves (its storage gets a new `Profiles/Oculus/<id>/`-style folder per start; Walkabout Mini Golf, GitHub #182) | OVRPort's platform loader answers `ovr_GetLoggedInUserID` with a made-up id (6e18 + `random()`), new at every start; games file saves under the user id | `frame.ovr_stable_user` (default for games with the platform library): a fixed id per game and keystore. Old progress: copy the newest old profile into the new id's folder |
 | A Cortopia game (Escaping Wonderland, GitHub #360; TMNT: Empire City, #422) stays on its loading screen (frames paced); launch.log: `E Unity: An unknown error occurred. Request failed.` with `OculusPlatformExtension:ToUniTask` / `Cortopia.Scripts.Platform.Meta.<Initialize>d__13`, or `PlatformExtensions:ToUniTask` / `Cortopia.Scripts.Platform.<Login>d__17` | after the licence check and the logged-in user, the game asks for `Users.GetOrgScopedID` when on Wi-Fi (its analytics id); OVRPort's `ovr_User_GetOrgScopedID` returns request id 0, Meta's C# wrapper logs that line and never calls back, so the awaited start-up never finishes | `frame.cortopia_org_id` (suggested from the analysis, triage `cortopia-org-id-wait`): the `b.ne` after `cmp w0, #2` on `get_internetReachability` in `<Initialize>d__13.MoveNext` (or `OculusPlatform.<Login>d__N.MoveNext`) -> `b` (Cpp2IL), the game's own no-Wi-Fi path; the licence check before it is untouched (the error comes from the generic `Request`1`, the licence check uses the non-generic `Request`); the same "Request failed." line in another game = another request OVRPort doesn't implement |
 | A Unity game waits on its loading screen after Meta's logged-in user; launch.log: `An unknown error occurred. Request failed.` from `Oculus.Platform.Request`1:OnComplete` called in the logged-in user's callback (GitHub #452 Eleven Table Tennis: `MetaPlatform:<BuildIdentity>b__0`; also Cortopia's games, #360/#422) | the game asks `Users.GetOrgScopedID(userId)` and waits for the answer; OVRPort's `ovr_User_GetOrgScopedID`, `ovr_Message_GetOrgScopedID` and `ovr_OrgScopedID_GetID` are `mov x0, xzr; ret` (request id 0, no message ever), so Meta's wrapper drops the callback. (`ovr_User_GetUserProof`, which Eleven asks next, is answered by OVRPort: a queued message with a nonce) | `frame.ovr_org_scoped_id` (triage `meta-org-scoped-id-wait`; suggested for known games and Cortopia's analysis flag): `libfp_langpack.so` (native/langpack, marker `@FPORGID@`, env `FRAMEPORT_ORG_SCOPED_ID=1`) answers with a fresh request id and a successful `ovrMessage_User_GetOrgScopedID` whose id is a hash of the (already stable) user id; linked alone it passes the language-pack calls through (`@FPLANGS@` 0) |
-| A VR game renders but ignores the controllers; the Android screen (or the dashboard showing it) with a mouse pointer in front of you (AC Nexus, #476 PadelVRTraining, #477 AltspaceVR; all with "Show the app's Android window") | `device.text_input_window` makes the Android window a Steam game window in gamescope; SteamVR auto-theaters it before the game's OpenXR session exists and opens the dashboard on it when the session starts (`vrwebhelper_systemui.txt`: "GameFrame now alive, auto-theatering", `SetDockLocation`) | agent 119+: the dashboard worker turns `dashboard.autoShowGameTheater` off while such a game runs (dashboard.log: "theater mode off while the game runs"); older agent or `FRAMEPORT_KEEP_DASHBOARD=1`: turn the window off for that game or press the dashboard button once |
+| A VR game renders but ignores the controllers; the Android screen (or the dashboard showing it) with a mouse pointer in front of you (AC Nexus, #476 PadelVRTraining, #477 AltspaceVR; all with "Show the app's Android window") | `device.text_input_window` makes the Android window a Steam game window in gamescope; SteamVR auto-theaters it before the game's OpenXR session exists and opens the dashboard on it when the session starts (`vrwebhelper_systemui.txt`: "GameFrame now alive, auto-theatering", `SetDockLocation`) | the dashboard worker turns `dashboard.autoShowGameTheater` off while such a game runs (dashboard.log: "theater mode off while the game runs"); with `FRAMEPORT_KEEP_DASHBOARD=1` (or an older FramePort): turn the window off for that game or press the dashboard button once |
 | A Unity app's text field shows a caret for a moment and loses focus; no keyboard appears (for example Stremio VR login) | Unity's TMP_InputField/InputField wait for Android's on-screen keyboard and close themselves without one (Lepton has none); headless VR apps also have no focused Android window, so no key press reaches them | `frame.unity_text_input` (Cpp2IL finds `TouchScreenKeyboardShouldBeUsed`/`isKeyboardUsingEvents`, rewritten to false/true) + `device.text_input_window` (lepton-show-flatscreen: Steam's keyboard and Type on Frame work) |
-| The game starts (Process RUNNING, launch test passes) but nothing appears and no OpenXR/FrameBridge line is ever logged; logcat shows a 2D/SDL activity drawing to its window and then going quiet (#475 Xelee) | The launcher activity is a flat 2D launcher (often category `com.oculus.intent.category.2D`) that starts a separate VR activity (analysis `extra.vr_activity`); Lepton runs VR apps headless, so the launcher is never seen and waits forever | `device.text_input_window` (suggested for such apps) shows the launcher; the deployment's recipe `flat_launcher` keeps SteamVR's theater mode on for it (agent 122+). Once set up, `frame.start_activity` can start the VR activity directly (skips the launcher) |
-| FramePort's games disappear after Steam restarts, especially after a devkit registration (GitHub #263) | Steam saves `Shortcuts` / `AppName` with capital letters; older FramePort reads them case-sensitively and writes a second shortcut map that Steam ignores | agent v86 reads and updates keys case-insensitively, keeping Steam's spelling, appids and tags; update FramePort and add the missing games to the library again |
-| Play gives Steam's "Game configuration unavailable"; Steam's console_log: `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` | this Frame's Steam never loaded FramePort's shortcuts.vdf entry (it treats the id as a store app); see the casing fix above, other causes remain unconfirmed (GitHub #21/#30) | automatic since agent v43: Play registers the game through Steam's devkit interface ("Devkit Game: …", `devkit_register`) and starts that; uninstall removes it. Agent v58: a devkit entry Steam forgot after a restart is added again live on Play (no NOT_IN_LIBRARY → no Steam restart), and installs/art updates of devkit games only copy art (no Steam restart, GitHub #41) |
-| Steam's Exit game leaves the game running (container `lepton-steamlaunch-<appid>` still up) | Steam stopped only its `reaper`; launch.sh and Lepton (setsid) never got a signal (GitHub #36) | agent v44: launch.sh's 2 s loop ends the game when its parent is gone (`upgrade_launchers` adds it to existing launchers); by hand: `podman kill lepton-steamlaunch-<appid>` |
-| Progress/settings lost after closing the game, although it saves on a Quest; every start logs a fresh save (Just Dance VR: `OfflineSaveDico_FromString - NeedLoad: False`), the session log has no `OnApplicationPause(true)` before its end (GitHub #480) | The container was killed (launch.sh `podman kill`, Lepton's teardown `reboot -p` + `podman stop -t 0`) while the activity was still resumed: Android never paused the app, so saves written in `onPause`/`OnApplicationPause` never ran | agent v120: launch.sh `pause_game` (added to existing launchers by `upgrade_launchers`), `stop` and the Monitor's End game first `am start` the HOME intent in the container and wait (≤3 s) until the activity is STOPPED; result in `<base>/stop-pause.log`. A game still loading may not answer within 3 s (`still state=STOPPING`). Steam's own Exit game (Steam signals the whole process tree at once): agent v121, launch.sh's `_exit_hook` worker hooks `SteamClient.Apps.TerminateApp` in Steam's UI through CEF devtools and pauses the game before Steam's call goes through (≤3 s; `<base>/exit-hook.log`; off per game with `FRAMEPORT_NO_EXIT_HOOK=1`). Not covered: Steam restarts / power-off, SteamVR's own "Exit <app>" (`QuitSceneApp`). See DEVICE_NOTES "Graceful stop" |
-| Just Dance VR (0.5.4 and later): progress, unlocks and the tutorial are gone at every start although the game now pauses before it ends (`OnApplicationPause(true)` in the log); `OfflineSave_Init succeeded` and no save file is ever written (GitHub #480) | The game loads its progress from a local save (`LocalSaveEvents.RequestHasSaveData`/`RequestLoad` -> `LocalSaveManager.OnLoadValueRequested` -> `LocalSaveController.LoadData` -> `OfflineSave_GetValue`) but `LocalSaveEvents.RequestSave` is empty (one `ret` in libil2cpp.so), so `OnSaveValueRequested` -> `SaveData` -> `OfflineSave_SetValue` never run. On a Quest progress lives in Ubisoft's PlayFab after a login with the Meta user id (`PlayfabAuthenticate`, `LoginWithCustomID`); no Meta platform on the Frame = no sign-in = nothing kept. `OfflineSaveDico_FromString - NeedLoad: False` is logged after every parse with a constant false: it doesn't mean the data was rejected (an HMAC mismatch is error 41 = file marked corrupted) | `frame.justdance_local_save`: RequestSave branches to its declared body (`SaveValueRequested?.Invoke(new LocalSaveEventArgs(key, value))`), built from `SaveSystemReady` decoded with capstone, in a new R+X segment (`elf.append_segment`); all addresses from Cpp2IL per build; a build whose RequestSave has a body is left alone. The game's OfflineSave thread then writes `files/JdNext.OfflineSave/JdOfflineSave_JdLog.OfflineSave.txt` within ~1 s. Nothing online touched. Triage `justdance-local-save-off` (`unless_patch`: not when the fix is in the build). Per-song star records (PlayerDataTracker) still don't load: its loader ends with a `yield break` |
+| The game starts (Process RUNNING, launch test passes) but nothing appears and no OpenXR/FrameBridge line is ever logged; logcat shows a 2D/SDL activity drawing to its window and then going quiet (#475 Xelee) | The launcher activity is a flat 2D launcher (often category `com.oculus.intent.category.2D`) that starts a separate VR activity (analysis `extra.vr_activity`); Lepton runs VR apps headless, so the launcher is never seen and waits forever | `device.text_input_window` (suggested for such apps) shows the launcher; the deployment's recipe `flat_launcher` keeps SteamVR's theater mode on for it. Once set up, `frame.start_activity` can start the VR activity directly (skips the launcher) |
+| FramePort's games disappear after Steam restarts, especially after a devkit registration (GitHub #263) | Steam saves `Shortcuts` / `AppName` with capital letters; older FramePort reads them case-sensitively and writes a second shortcut map that Steam ignores | FramePort now reads and updates keys case-insensitively, keeping Steam's spelling, appids and tags; update FramePort and add the missing games to the library again |
+| Play gives Steam's "Game configuration unavailable"; Steam's console_log: `GameAction [AppID <id>] … RequestingLicense → UpdatingAppInfo → LaunchApp failed with AppError_9` | this Frame's Steam never loaded FramePort's shortcuts.vdf entry (it treats the id as a store app); see the casing fix above, other causes remain unconfirmed (GitHub #21/#30) | automatic: Play registers the game through Steam's devkit interface ("Devkit Game: …", `devkit_register`) and starts that; uninstall removes it. A devkit entry Steam forgot after a restart is added again live on Play (no NOT_IN_LIBRARY → no Steam restart), and installs/art updates of devkit games only copy art (no Steam restart, GitHub #41) |
+| Steam's Exit game leaves the game running (container `lepton-steamlaunch-<appid>` still up) | Steam stopped only its `reaper`; launch.sh and Lepton (setsid) never got a signal (GitHub #36) | launch.sh's 2 s loop ends the game when its parent is gone (`upgrade_launchers` adds it to existing launchers); by hand: `podman kill lepton-steamlaunch-<appid>` |
+| Progress/settings lost after closing the game, although it saves on a Quest; every start logs a fresh save (Just Dance VR: `OfflineSaveDico_FromString - NeedLoad: False`), the session log has no `OnApplicationPause(true)` before its end (GitHub #480) | The container was killed (launch.sh `podman kill`, Lepton's teardown `reboot -p` + `podman stop -t 0`) while the activity was still resumed: Android never paused the app, so saves written in `onPause`/`OnApplicationPause` never ran | launch.sh `pause_game` (added to existing launchers by `upgrade_launchers`), `stop` and the Monitor's End game first `am start` the HOME intent in the container and wait (≤3 s) until the activity is STOPPED; result in `<base>/stop-pause.log`. A game still loading may not answer within 3 s (`still state=STOPPING`). Steam's own Exit game (Steam signals the whole process tree at once): launch.sh's `_exit_hook` worker hooks `SteamClient.Apps.TerminateApp` in Steam's UI through CEF devtools and pauses the game before Steam's call goes through (≤3 s; `<base>/exit-hook.log`; off per game with `FRAMEPORT_NO_EXIT_HOOK=1`). Not covered: Steam restarts / power-off, SteamVR's own "Exit <app>" (`QuitSceneApp`). See DEVICE_NOTES "Graceful stop" |
+| Just Dance VR (0.5.4 and later): progress, unlocks and the tutorial are gone at every start although the game now pauses before it ends (`OnApplicationPause(true)` in the log); `OfflineSave_Init succeeded` and no save file is ever written (GitHub #480) | The game loads its progress from a local save (`LocalSaveEvents.RequestHasSaveData`/`RequestLoad` -> `LocalSaveManager.OnLoadValueRequested` -> `LocalSaveController.LoadData` -> `OfflineSave_GetValue`) but `LocalSaveEvents.RequestSave` is empty (one `ret` in libil2cpp.so), so `OnSaveValueRequested` -> `SaveData` -> `OfflineSave_SetValue` never run. On a Quest progress lives in Ubisoft's PlayFab after a login with the Meta user id (`PlayfabAuthenticate`, `LoginWithCustomID`); no Meta platform on the Frame = no sign-in = nothing kept. `OfflineSaveDico_FromString - NeedLoad: False` is logged after every parse with a constant false: the line doesn't mean the data was rejected (an HMAC mismatch is error 41 = file marked corrupted) | `frame.justdance_local_save`: RequestSave branches to its declared body (`SaveValueRequested?.Invoke(new LocalSaveEventArgs(key, value))`), built from `SaveSystemReady` decoded with capstone, in a new R+X segment (`elf.append_segment`); all addresses from Cpp2IL per build; a build whose RequestSave has a body is left alone. The game's OfflineSave thread then writes `files/JdNext.OfflineSave/JdOfflineSave_JdLog.OfflineSave.txt` within ~1 s. Nothing online touched. Triage `justdance-local-save-off` (`unless_patch`: not when the fix is in the build). Per-song star records (PlayerDataTracker) still don't load: its loader ends with a `yield break` |
 | Black screen at start while audio/ExoPlayer runs; log `xrEndFrame: dropped N unusable layer(s)`, a quad layer with swapchain 0x0 (for example I Am Monkey's intro video) | The game plays video into an Android-surface swapchain (XR_KHR_android_surface_swapchain); the Frame's runtime lists the extension but returns FUNCTION_UNSUPPORTED | adapter `surface_emul` (default on): FrameBridge gives the player a SurfaceTexture-backed Surface and copies each frame into an ordinary swapchain (log `surface_emul: …`) |
-| The game quits right after start: `Something failed to initialize. Quitting!` / `We don't have write permission to …/files/cloud/data` (for example SUPERHOT); or stays at loading with `UnauthorizedAccessException` in `StartupLoading.Start` (GitHub #239, Jurassic World Aftermath) | The game created a cloud-save folder with mode 1700; inside Lepton the app writes through the folder's group. Its startup routine can fail before the permission watchdog repairs the newly created folder | launch.sh `fix_perms` adds owner + group write to every folder in the game's storage (agent 41). Close and start the game again without uninstalling: the folders are now repaired (Aftermath confirmed in the headset). Agent 84 creates `files/cloud/data` before `fix_perms` and startup, including in upgraded launchers, to prevent the first-start race. Triage `startup-save-permission` fails the launch test despite rendering frames |
+| The game quits right after start: `Something failed to initialize. Quitting!` / `We don't have write permission to …/files/cloud/data` (for example SUPERHOT); or stays at loading with `UnauthorizedAccessException` in `StartupLoading.Start` (GitHub #239, Jurassic World Aftermath) | The game created a cloud-save folder with mode 1700; inside Lepton the app writes through the folder's group. The game's startup routine can fail before the permission watchdog repairs the newly created folder | launch.sh `fix_perms` adds owner + group write to every folder in the game's storage. Close and start the game again without uninstalling: the folders are now repaired (Aftermath confirmed in the headset). The launcher also creates `files/cloud/data` before `fix_perms` and startup, including in upgraded launchers, to prevent the first-start race. Triage `startup-save-permission` fails the launch test despite rendering frames |
 | The whole Frame slows to a halt, then the game is killed (`Out of memory: Killed process … anon-rss:10+ GB`), for example Lucky's Tale | The game's own memory grows ~1 GB/s on Unity's `Loading.PreloadManager` thread (perf page-fault profile); not the flat window, not the text-input patches | none yet: mark unsupported; profile with `perf record -p <pid> -e page-faults --call-graph fp` (works as steamos, `perf_event_paranoid` 2) |
-| A Linux app exits at once: `cannot execute binary file: Exec format error` in launch.log | an x86_64 program started directly (installed before FramePort ran x86 builds through FEX, or by hand) | reinstall it: x86_64 Linux apps install FEX on the Frame and start through it (agent v61, `kind: linux_x86`; FEX also needs `STEAM_COMPAT_DATA_PATH`: "No compat data path?" in launch.log = an agent v60 launcher, reinstall); triage `linux-x86-no-fex`. Prefer an arm64 build when the app offers one |
+| A Linux app exits at once: `cannot execute binary file: Exec format error` in launch.log | an x86_64 program started directly (installed before FramePort ran x86 builds through FEX, or by hand) | reinstall it: x86_64 Linux apps install FEX on the Frame and start through it (`kind: linux_x86`; FEX also needs `STEAM_COMPAT_DATA_PATH`: "No compat data path?" in launch.log = an older launcher, reinstall); triage `linux-x86-no-fex`. Prefer an arm64 build when the app offers one |
 | The game closes about a minute after starting, at a different spot each time; `Start proc …:<pkg>:<name> for pre-top-activity`, then `Target app (<pkg>) did not start` (GitHub #178) | The started activity runs in its own process (`android:process`); Lepton watches only the main process (triage `app-separate-process`) | `frame.main_process` (automatic) |
 | `APP_ACTIVITY is empty`, nothing starts | Manifest has category INFO only; Lepton needs LAUNCHER | `frame.launcher` (automatic) |
 | PC VR game on the Frame shows as a flat window / Revive: `Unable to load LibOVRRT DLL` / `LoaderInstance::CreateInstance chained CreateInstance call failed` | Frame SteamVR runtime rejects OpenXR apiVersion 1.1 (`XR_ERROR_API_VERSION_UNSUPPORTED`), which Proton 11's VR helper requests | `pcvr.xr_timefix` (Frame OpenXR layer, default on): retries xrCreateInstance as 1.0 |
 | Unreal PC VR game on the Frame runs as a flat window although OpenXR works (no `LogHMD` OVRPlugin lines; Unreal logs nothing when it skips the Oculus plugin) / launch.log: `FramePort oculushmd: could not create the OculusHMDConnected event` | UE's OculusHMD (and LibOVR's `ovr_Detect`) only start when the Windows event `OculusHMDConnected` exists and is signaled; on a PC the Oculus service creates it. Revive hooks `OpenEventW` for it, but that relies on Detours patching Wine's (ARM64EC) kernelbase | `pcvr.oculus_unreal` (default for Unreal Rift games; PC VR counterpart of overport's `patch_oculus_unreal`): launch.sh runs the injector through `fp_oculushmd.exe`, which provides the real event until the game exits |
 | PC VR game runs as a flat 2D window (no VR) | SteamVR was not running, so Revive/LibOVR had no runtime to bind to | FramePort now auto-starts SteamVR on Play; make sure SteamVR comes up before the game |
 | PC VR game crashed launching via Steam on the OpenXR backend | Revive's newer OpenXR backend was less reliable | PC now defaults to Revive's OpenVR (SteamVR) backend; reinstall to apply |
-| Oculus PC VR game: `Unable to load LibOVRRT DLL` / `-3001` on the Frame | The game can't find a VR runtime (Revive's LoadLibrary hook doesn't work under Proton-arm64) | `pcvr.libovr_redirect` (default on) symlinks Revive's runtime as `LibOVRRT{64,32}_1.dll` in the exe dir — pure substitution; a build that checks the runtime signature then hits `-3021` (not bypassed) |
+| Oculus PC VR game: `Unable to load LibOVRRT DLL` / `Failed to initialize Oculus API (-3001)` on the Frame | The game can't find a VR runtime: Revive's LoadLibrary hook doesn't work under Proton-arm64 (ARM64EC kernelbase) | `pcvr.libovr_redirect` (default on with Revive) symlinks Revive's runtime as `LibOVRRT{64,32}_1.dll` in the exe dir and next to every OVRPlugin.dll: pure substitution; a build that checks the runtime signature then hits `-3021` (not bypassed) |
 | Oculus Rift game won't run on the Frame | Oculus/LibOVR game: needs Revive, whose hooks don't work under Proton-arm64, and FramePort won't defeat the Oculus runtime signature check | Play it on this PC (SteamVR + Revive). Only OpenVR/OpenXR-native Rift games run on the Frame |
 | Un-cracked Oculus PC VR game: "Initializing OVR session" then exits / signature check on the runtime | Revive's hooks don't install on Proton-arm64; the Oculus shim rejects the unsigned Revive runtime | Not runnable on the Frame without the repack's crack extracted (not done by FramePort); use the PC version |
-| PC VR game: `Failed to initialize Oculus API (-3001)` / `Unable to load LibOVRRT DLL` | Revive's LoadLibrary hook doesn't work under Proton arm64 (ARM64EC kernelbase); the game's LibOVR shim finds no runtime DLL | Symlink `LibOVRRT64_1.dll` → Revive's DLL in the prefix's system32 (manual so far) → then -3021 (runtime signature check; open) |
-| Uploads to the Frame are slow | The link, storage or transfer backend can limit throughput | Check the job's "Transfer link"; try the Frame's hotspot or USB cable. Large install files prefer system OpenSSH SFTP, retaining paired-host checks and `.part` resume; unavailable or failed native uploads fall back to Paramiko. The log names the backend. Settings → Installing → Parallel uploads accepts 1–8 (default 3; saved preferences are preserved). More is not always faster. Measure the production path with `scripts/upload_bench.py --methods app-files-3 --check-resume` (three repetitions, checksum verification) |
-| Log: `OpenSSH SFTP failed (255): … Permission denied (publickey,password)`, then Paramiko | OpenSSH offered keys the Frame doesn't authorize (GitHub #242) | The log lists the keys OpenSSH offered (`Offering public key`) and its warnings. A connection that logged in with the PC's own keys/agent makes OpenSSH use them too (copies of `~/.ssh/id_*` + the agent); a refused FramePort key is retried that way once. A Frame that accepts only another key file: Settings → Installing → SSH keys (CLI `frameport frame ssh-keys --add <file>`); passphrase keys go through the SSH agent |
-| Log: `OpenSSH SFTP failed (1): stat C://…/[…: No such file or directory` | sftp got glob escapes inside its quotes (GitHub #324, fixed): `[` in a local folder name | Update FramePort; the native_upload `quote()` passes only `\\` and `\"` escapes, Windows paths with `/` |
 | PC VR game exits right away: `Unhandled Exception: 0xc06d007e` (after `FOnlineSubsystemOculus::InitWithWindowsPlatform`) | Delay-loaded `LibOVRPlatform64_1.dll` (Oculus Platform SDK, installed with the Oculus app) is missing | None on the Frame (entitlement check; FramePort doesn't replace it). PC mode with the Oculus app |
-| Unity PC VR game (Oculus + SteamVR build: `OVRPlugin.dll` and `openvr_api.dll` in `<Name>_Data/Plugins`) opens a window and quits after ~20 s; no VR Vulkan instance after the game's DXVK device in launch.log; Unity log (`unity log … Player.log`, agent v67): `OpenVR failed initialization` / `Initialization of device … failed` | Unity's built-in VR tries its SDKs in list order (Oculus first) unless `-vrmode` picks one; a catalog recipe verified with another build of the game (for example SUPERHOT VR's OpenXR build, GitHub #105) used to drop the build's own arguments | `pcvr.launch_args` = `-vrmode OpenVR` (detected for such builds; kept when the catalog's `xr` differs from the build's). A game's Electron launcher next to it (SHVR.exe) is ranked below the game |
+| Unity PC VR game (Oculus + SteamVR build: `OVRPlugin.dll` and `openvr_api.dll` in `<Name>_Data/Plugins`) opens a window and quits after ~20 s; no VR Vulkan instance after the game's DXVK device in launch.log; Unity log (`unity log … Player.log`): `OpenVR failed initialization` / `Initialization of device … failed` | Unity's built-in VR tries its SDKs in list order (Oculus first) unless `-vrmode` picks one; a catalog recipe verified with another build of the game (for example SUPERHOT VR's OpenXR build, GitHub #105) used to drop the build's own arguments | `pcvr.launch_args` = `-vrmode OpenVR` (detected for such builds; kept when the catalog's `xr` differs from the build's). A game's Electron launcher next to it (SHVR.exe) is ranked below the game |
 | Unreal PC VR game opens the crash reporter instead of closing | UE starts CrashReportClient.exe on a crash | `pcvr.no_crash_reporter` (default for Unreal Rift games): `-nocrashreports` + CrashReportClient.exe renamed `.disabled` in the Frame copy |
 | A backup's game was added without its data (library `data_dir` null, `data_bytes` 0) although the folder has .obb files | The OBBs sit in a layout the scan didn't know: `<game>/obb/<package>/`, `Android/obb/<package>/`, or SideQuest-style `<game>/apk/x.apk` + `<game>/obb/<package>/` | `sources/quest_dump.find_data_dir` finds a `<package>` folder with .obb files ≤3 levels below the APK's folder or ≤2 below its parent (skipping neighboring folders with APKs: other games); an `apk`/`apks` folder counts as part of its game folder. Add the folder again (Analyze again doesn't look for data) |
 | "Failed to correctly load the game files" at the menu; `Error loading FMOD bank "…/Android/obb/<package>/Master.bank": ERROR` (GitHub #239, Jurassic World Aftermath Collection); launch test previously passed at 72 fps | SideQuest's `<package>/<backup time>/apk/x.apk` + `obb/Master.bank` + `obb/Master.strings.bank` backup was scanned without data: these are raw sound banks, not .obb expansion files, so the sibling-folder search missed them | `quest_dump.find_data_dir` checks the parent game folder's `obb/` (or `obbs/`) when the APK is in `apk/` or `apks/`, including raw assets with or without a package subfolder. Add the backup folder again and reinstall; triage `fmod-bank-missing` fails the launch test even when the error screen renders frames. Copy the whole data folder from the same backup as the APK |
 | A game from an AXRB download starts and stops at once (Steam shows Resume), no OBB on the Frame; or a SideQuest backup adds a second game named after an APK in its `obb/` folder (reddit 2026-10-11) | AXRB keeps its own PC builds in `AXRB/patched/<package>/*-axrb.apk` (OVRPort-converted for its runtime, no OBBs); the scan added them over the original `AXRB/<app id>/<binary id>/base.apk`. SideQuest's VR4 backup has Unreal's `VR4-Android-Shipping-arm64.apk` next to the OBBs | `quest_dump._axrb_patched` skips AXRB's patched copies; a rescan replaces entries made from them; AXRB downloads send every non-APK file next to `base.apk` (DLC, assets) and are named after the package; APKs inside another game's data folder are ignored; SideQuest backups are named after the package folder, not the backup time. docs/FAQ.md has both layouts |
 | Game hangs at start / never loads although its .obb files are right there: next to the APK, in an `obb` folder beside an `apk` folder inside a `<package>` folder, or a SideQuest backup (`<timestamp>_<versionCode>.apk`) (GitHub #85, #91) | No folder named after the package, so the folder-layout checks found nothing and no OBB was uploaded | `quest_dump.find_data` then looks for the files by name, `(main\|patch).<versionCode>.<package>.obb` (any case), in the APK's folder, its parent and up to 3 levels below each (folders with their own APKs are other games); prefers the folder and files of the APK's own versionCode, else the newest older, else any version. When that folder also holds other things (the APK itself, other games' OBBs), the library entry gets `data_files` and only those files are uploaded, counted and deleted with the game. Add the folder again |
 | Unreal/Unity game stops right after its graphics start or hangs at start although its OBBs are complete; the files are named `main.203.com.Armature.VR4-003.obb` / `patch.203.com.Armature.VR4-001.obb` or differ in case (GitHub #450, #481) | the game opens `main.<versionCode>.<package>.obb` by exact name | installs send such files under the right name (`quest_dump.obb_names`; the files on the PC keep theirs) and the game page says so (info). Still a warning, sent unchanged: another app's name (#129 `….lj369vr.obb`), a copy next to the right-named file, two copies for one name, a copy suffix without a versionCode: rename by hand, scan again, Update on Frame. docs/DEVICE_NOTES.md#expansion-file-names-450-481 |
-| CryEngine game: `Powered by CRYENGINE`, then SIGTRAP in `libAndroidLauncher.so` during `CreateSystemInterface`, before any OpenXR instance (GitHub #238, The Climb 666.0) | Installed without its OBB: the SideQuest backup has `apk/com.crytek.climb.apk` + `obb/main.com.crytek.climb.obb`, but the scan required a versionCode in the OBB name and skipped it. The reported backtrace's fatal-error call formats `Engine initialization failed: Open Engine Paks: Unable to find "engine" pak files (%s)` | `quest_dump.find_data` accepts `(main\|patch).<package>.obb` as well as numbered names, keeping the original filename. Update on Frame finds the previously skipped data; a rescan finds it too. Analysis version 12 recognizes monolithic CryEngine through `assets/game.cryproject`, Vulkan through `assets/system.cfg` (`r_Driver = vk`), and an expected OBB through the launcher's expansion-path format strings; a missing OBB now gets the existing `missing-obb` warning/finding. This fixes the original missing-content startup failure; the rendering failures below were found once the data was installed |
+| CryEngine game: `Powered by CRYENGINE`, then SIGTRAP in `libAndroidLauncher.so` during `CreateSystemInterface`, before any OpenXR instance (GitHub #238, The Climb 666.0) | Installed without its OBB: the SideQuest backup has `apk/com.crytek.climb.apk` + `obb/main.com.crytek.climb.obb`, but the scan required a versionCode in the OBB name and skipped it. The reported backtrace's fatal-error call formats `Engine initialization failed: Open Engine Paks: Unable to find "engine" pak files (%s)` | `quest_dump.find_data` accepts `(main\|patch).<package>.obb` as well as numbered names, keeping the original filename. Update on Frame finds the previously skipped data; a rescan finds it too. Analysis version 12 recognizes monolithic CryEngine through `assets/game.cryproject`, Vulkan through `assets/system.cfg` (`r_Driver = vk`), and an expected OBB through the launcher's expansion-path format strings; a missing OBB now gets the existing `missing-obb` warning/finding. The OBB fix solves the original missing-content startup failure; the rendering failures below were found once the data was installed |
 | CryEngine game (The Climb 1/2) on FramePort 1.3.0: `Messagebox: cap: Engine initialization failed!  text:CrySystem initialization failed!` right after the renderer lists its Vulkan device extensions, then SIGSEGV in `CSystem::ShutDown` (GitHub #432/#449). The Climb 1 (monolithic, no symbols): SIGSEGV fault addr 0xf0 under `CreateSystemInterface+320` in `libAndroidLauncher.so` right after `MESA: Using gralloc0 CrOS API`, or a hang at that line | 1.3.0 links the dormant foveation diagnostic `libVkLayer_fdm_darken.so` into every arm64 game's engine library; in CryEngine's `libCryRenderVulkan.so` that stops CrySystem from starting. Bisected headless on the dev Frame: the new build runs once only its renderer is the unmodified one | The layer exports `vkEnumerate{Instance,Device}{Extension,Layer}Properties` and `elf.add_needed` put it first, so a renderer that imports those from `libvulkan.so` got the layer's answers (no extensions). `foveation.diagnostic_support` now links it after the existing DT_NEEDED entries, skips `libCryRender*` and CryEngine's monolithic `libAndroidLauncher.so` (The Climb 1; Climb 2's private VrApi bridge still loads the layer); `frame.adapter` package revision 3 for Climb 2, 5 for The Climb 1 marks their builds for Update on Frame. Triage `cryengine-init-failed` |
 | VrApi game: `OVRPortVrApi: xrInitializeLoaderKHR failed: OpenXR result -7`, then SIGTRAP from the engine (no `FrameBridge:` lines; static check warns `not in the APK or the system list: libVkLayer_fdm_darken.so`) (GitHub #432, The Climb 1 on a dev build) | FrameBridge (`libopenxr_loader_generic.so`) is linked against `libVkLayer_fdm_darken.so` on arm64, but the build skipped shipping the layer file together with the CryEngine link, so FrameBridge didn't load and the bridge found no loader | `diagnostic_support` always ships the layer; `frame.adapter` validate fails without it. Triage `vrapi-bridge-no-loader` |
 | QuestCraft: Minecraft never starts, `libjvm.so not found`; no `files/runtimes/` folder in the game's storage; the log shows `Transports: ETHERNET` (GitHub #18, #468) | pojlib's `API.hasConnection()` only counts Wi-Fi and Lepton's Android reports Ethernet, so the Java runtime download is skipped | `frame.pojlib_connection` makes `hasConnection()` return true (dex edit; catalog + QuestCraft's package, new scans by analysis field). Workaround: unpack QuestCraft's `JRE.zip` into `files/runtimes/JRE` with the Files tab. Triage `questcraft-no-java-runtime` |
@@ -97,14 +95,14 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | A game shows UTC instead of local time (Walkabout Mini Golf's clock, GitHub #429); in the container `getprop persist.sys.timezone` = `../usr/share/zoneinfo/<Zone>` | Lepton sets the zone from a bare `readlink /etc/localtime` minus `/usr/share/zoneinfo/`, and SteamOS' link is relative | Lepton launchers put `~/.local/share/frameport/lepton-shims` first on PATH (agent `TZ_LINE`, `upgrade_launchers` adds it); its `readlink` answers `/etc/localtime` with the resolved path. Checked on the dev Frame: `America/New_York`, `date` in EDT. A boot property line from FramePort can't override it (Lepton writes its own line later) |
 | A companion app doesn't find its game's files (JKXR's companion app and `/sdcard/JKXR`, GitHub #440) | On a Quest all apps share one /sdcard; in Lepton each game has its own | `device.shared_folder` (`game`, `folder`; catalog field `shared_folder`): launch.sh links the folder to the other game's copy and adds that path to `STEAM_COMPAT_LIBRARY_PATHS`, which Lepton bind-mounts at the same path (agent `SHARE_LINES`). Checked on the dev Frame between two installed games (read + write). The companion can't start the other game: each game has its own container |
 | 8K video (Batman's cutscenes) plays choppy: `Iris video/hevc busy (8192x4096)` then `initialization failed (-12); using software decoding` (GitHub #437) | Iris takes an 8K session only while no other is open; Steam's own web helper sometimes keeps `/dev/video22` (qcom-iris-decoder) open, most likely after its UI played a video. With it free the same file decodes in hardware (dev Frame, 2026-10-23) | Restart Steam (or the Frame) before playing. Hardware-video launchers log `FramePort: hardware video decoder … in use by: …` at start (agent `DECODER_USERS_LINE`); triage `video-decoder-held-by-steam`. Videos up to 640x480 decode in software so FramePort's own small players never hold Iris |
-| The Climb 666.0: audio with no headset picture, `OVRPortVrApi: Unsupported frame flags or swap interval`; then SIGSEGV in `vulkan.freedreno.so` during `vkCmdEndRenderPass` once frames are accepted (GitHub #238) | The game submits the obsolete Quest texture-density debug flag (`0x100`), which the bridge rejected. It also binds the bridge's full-rate texture as a fragment-density attachment even though foveation support is reported off; Turnip reads density maps on the CPU, but an ordinary sampled image has no mapped backing memory | Updated `frame.vrapi_bridge` accepts the compositor debug/volume flags and creates the compatibility texture with `VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT`. Do not gate that usage on the advertised format features (the Frame reports R8G8_UNORM without the density bit). `device.files` selects `r_vr_foveated = 0` when the engine contains that cvar; The Climb 2 keeps `r_variable_rate_shading = 0`. Triage `vrapi-frame-rejected` marks rejected frames as fatal despite pacing logs. Picture confirmed on the headset. With the corrected config, an uncapped launch stayed running for over four minutes at a median 72 fps with no native crash or GPU fault. The user confirmed working menus and gameplay on 2026-10-12 |
+| The Climb 666.0: audio with no headset picture, `OVRPortVrApi: Unsupported frame flags or swap interval`; then SIGSEGV in `vulkan.freedreno.so` during `vkCmdEndRenderPass` once frames are accepted (GitHub #238) | The game submits the obsolete Quest texture-density debug flag (`0x100`), which the bridge rejected. The game also binds the bridge's full-rate texture as a fragment-density attachment even though foveation support is reported off; Turnip reads density maps on the CPU, but an ordinary sampled image has no mapped backing memory | Updated `frame.vrapi_bridge` accepts the compositor debug/volume flags and creates the compatibility texture with `VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT`. Do not gate that usage on the advertised format features (the Frame reports R8G8_UNORM without the density bit). `device.files` selects `r_vr_foveated = 0` when the engine contains that cvar; The Climb 2 keeps `r_variable_rate_shading = 0`. Triage `vrapi-frame-rejected` marks rejected frames as fatal despite pacing logs. Picture confirmed on the headset. With the corrected config, an uncapped launch stayed running for over four minutes at a median 72 fps with no native crash or GPU fault. The user confirmed working menus and gameplay on 2026-10-12 |
 | Unreal game: `JNI_OnLoad` (OVRPlugin), then silence: no OpenXR instance, no crash, no frames (GitHub #85 TRIANGLE STRATEGY; launch-test finding `missing-obb`) | Installed without its OBB: the manifest says `com.epicgames.ue4.GameActivity.bHasOBBFiles` = true (UE5: `com.epicgames.unreal.…`) but the library has no data folder (`data_dir` null, `data_bytes` 0) | Put the .obb files in a `<package>` (or `obb/`) folder next to the APK, add the folder again, reinstall. Analysis `extra.expects_obb`; the game page, the install question and `frameport scan`/`install` warn; launch tests that sent no frames get the `missing-obb` finding from the library (the game logs nothing). Unity split-binary builds count too (`extra.unity_split`, `analysis/unity_split.py`): an XR-plugin build (Oculus XR Plugin / Unity OpenXR library) without `assets/bin/Data/UnitySubsystems/` in the APK, or BuildSettings listing more scenes than the APK has `levelN` files (globalgamemanagers loose or read from the head of data.unity3d); exact on the 48 Unity APKs of the dumps (13 split, 17 full games; OBBs of full builds are asset bundles or sound banks) |
-| Unreal game: launch.log ends with `ActivityTaskManager: START u0 {… cmp=<pkg>/.DownloaderActivity}` and `Displayed <pkg>/.DownloaderActivity`, then nothing: no OpenXR instance, no crash (GitHub #159 Contractors; triage `unreal-obb-check-stuck`, also when the OBB is on the Frame) | Epic's DownloaderActivity (started by GameActivity.onResume before the engine's main init) checks every OBB's name + size compiled into the APK (OBBData); with manifest meta-data `com.epicgames.ue4.GameActivity.bVerifyOBBOnStartUp=true` it then reads the whole OBB and compares each entry's CRC32 (cached in `files/cacheFile.txt` by the OBB's mtime). Its progress and error screens are invisible in Lepton (headless VR); a CRC mismatch waits for a button forever. A missing / wrong-size OBB starts Google Play's downloader (or a "No Google Play Store Key" dialog) and also waits | `frame.unreal_skip_obb_check` (suggested by analysis `unreal_verify_obb`): sets that meta-data to false (one boolean in the manifest, `axml.set_meta_data_bool`), which skips only the CRC pass. Still stuck: the OBB doesn't match the APK version (name `main.<versionCode>.<pkg>.obb` and its size) - copy APK + OBB from the same install |
+| Unreal game: launch.log ends with `ActivityTaskManager: START u0 {… cmp=<pkg>/.DownloaderActivity}` and `Displayed <pkg>/.DownloaderActivity`, then nothing: no OpenXR instance, no crash (GitHub #159 Contractors; triage `unreal-obb-check-stuck`, also when the OBB is on the Frame) | Epic's DownloaderActivity (started by GameActivity.onResume before the engine's main init) checks every OBB's name + size compiled into the APK (OBBData); with manifest meta-data `com.epicgames.ue4.GameActivity.bVerifyOBBOnStartUp=true` it then reads the whole OBB and compares each entry's CRC32 (cached in `files/cacheFile.txt` by the OBB's mtime). DownloaderActivity's progress and error screens are invisible in Lepton (headless VR); a CRC mismatch waits for a button forever. A missing / wrong-size OBB starts Google Play's downloader (or a "No Google Play Store Key" dialog) and also waits | `frame.unreal_skip_obb_check` (suggested by analysis `unreal_verify_obb`): sets that meta-data to false (one boolean in the manifest, `axml.set_meta_data_bool`), which skips only the CRC pass. Still stuck: the OBB doesn't match the APK version (name `main.<versionCode>.<pkg>.obb` and its size) - copy APK + OBB from the same install |
 | Unreal game has CRC verification off but the delivery bypass is unavailable (GitHub #159, Medal of Honor: Above and Beyond) | Obfuscation renamed `expansionFilesDelivered`: MoH calls boolean predicates `a()` and `d()` from its package DownloaderActivity.onCreate, both logging `Checking for file : ` and calling Google expansion filename/delivery helpers. The second gate can show “Select OBB to use” | Analysis recognizes these predicates by activity, caller, log and helper return types; stuck-downloader triage offers `frame.unreal_skip_obb_delivery` as an experimental opt-in. CRC stays off. The inspected build checks three Java OBB entries and has native indexed-patch filename support; its backup has 22 OBBs and 34 MP4s, all selected from the package folder. Bypassing Java delivery does not establish native data completeness or headset success |
-| Unreal game still stays on `DownloaderActivity` with CRC checking off (`bVerifyOBBOnStartUp=false`) and a fully uploaded matching OBB (GitHub #283, Into The Radius) | The separate Java `expansionFilesDelivered()` name and size gate can reject an OBB through Android external storage in Lepton; disabling CRC does not bypass it | Try `frame.unreal_skip_obb_delivery` (opt-in, experimental, triage-only). It returns true from known Unreal/package delivery predicates in every dex, preserving normal downloader success and main init. Analysis `unreal_obb_delivery` (version 16) controls applicability. The native engine still needs complete, matching, readable OBB data; unverified on a device |
+| Unreal game still stays on `DownloaderActivity` with CRC checking off (`bVerifyOBBOnStartUp=false`) and a fully uploaded matching OBB (GitHub #283, Into The Radius) | The separate Java `expansionFilesDelivered()` name and size gate can reject an OBB through Android external storage in Lepton; disabling CRC does not bypass it | Try `frame.unreal_skip_obb_delivery` (opt-in, experimental, triage-only). The patch returns true from known Unreal/package delivery predicates in every dex, preserving normal downloader success and main init. Analysis `unreal_obb_delivery` (version 16) controls applicability. The native engine still needs complete, matching, readable OBB data; unverified on a device |
 | `INSTALL_FAILED_MISSING_SPLIT`, or the game page notes "Split APK: only the base APK was found" (triage `missing-split`, analysis `extra.split_apk`) | Only the base of a split APK set (Play app bundle install) was added: `android:isSplitRequired` / `requiredSplitTypes`, code or libraries live in the splits | Add the whole bundle (.xapk/.apks/.apkm/.apkx) or the folder of split APKs (discussion #482): `sources/bundles.py` merges base + the arm64-v8a split (lib/assets in Python, resource/feature splits via APKEditor), drops the split attributes and `com.android.vending.splits.required`; the merged APK is signed with the game's key |
 | `INSTALL_FAILED_NO_MATCHING_ABIS` | 32-bit-only APK (Gear VR / Go / early Quest); Frame has no AArch32 | `frame.a32_bridge` (suggested for every 32-bit-only APK, experimental): the a32 translator runs the game's 32-bit libraries inside the 64-bit app (native/a32translator/bridge) |
-| a32 bridge faults at a low Thumb PC while loading a library, with the same unrelocated pointer in `.init_array` (e.g. Journey of the Gods: `0x1259e9` in OVRPlugin) | The guest loader ignored the older `DT_ANDROID_RELR` / `DT_ANDROID_RELRSZ` tags, leaving relative pointers at their link addresses | Fixed in the guest loader: both Android and standard RELR tags use the existing RELR decoder. Rebuild the a32 runtime and APK; host regression tests cover both tag families, but game startup still needs a Frame run |
+| a32 bridge faults at a low Thumb PC while loading a library, with the same unrelocated pointer in `.init_array` (for example Journey of the Gods: `0x1259e9` in OVRPlugin) | The guest loader ignored the older `DT_ANDROID_RELR` / `DT_ANDROID_RELRSZ` tags, leaving relative pointers at their link addresses | Fixed in the guest loader: both Android and standard RELR tags use the existing RELR decoder. Rebuild the a32 runtime and APK; host regression tests cover both tag families, but game startup still needs a Frame run |
 | 32-bit game on the bridge quits right after its loading screen with `a32: block at 0x… overflowed the code buffer` (exit 127; Pinball FX2 VR, GitHub #342: OpenSSL's `sha1_block_data_order_armv8`, ~60 SHA-1 crypto instructions in a row, reached from `RAND_poll`) | Every instruction the JIT hands to the interpreter needs an exit stub; the translator only ended a block at 96 instructions or half its code buffer, so a dense run of such instructions overflowed the 64-entry stub table and `fatal()` ended the process | Fixed in the translator (jit.c `STUB_RESERVE`: a block ends while 8 stubs are left); rebuild the game. Find the code with the logged address minus the library's load address (`a32rt: loaded …`) and `A32_BREAK=<addr>` for its caller; `tests/programs/sha1ce.c` covers it |
 | 32-bit Unity game on the bridge: a video never shows (Ghost Giant's intro stays black, GitHub #439); log `AndroidMediaNDK could not load symbol AMediaFormat_new` then `GetDirectBufferAddress: buffer at 0x… is outside the guest's reach` / `AndroidVideoMedia: Error while getting codec input buffers` | Unity's video player needs libmediandk (AMediaFormat/AMediaCodec/AMediaExtractor); the bridge had none, and Unity's JNI fallback reads MediaCodec ByteBuffers in the host's heap, above the guest's 4 GiB | Bridge `host/media.c` + imports.txt: the NDK media functions (and `guest/media_keys.c`: the `AMEDIAFORMAT_KEY_*` data symbols Unity also looks up; without them it stops at `could not load symbol AMEDIAFORMAT_KEY_AAC_PROFILE`), format strings/buffers copied, codec buffers mirrored in guest memory (synced at `queueInputBuffer` / `getOutputBuffer`); triage `a32-video-ndk`; harness `fakemedia.c` + `libbtest4.c`. Headless check (2026-10-24, `OVP_HEADLESS_TEST=1` + `snapshot=3`): Ghost Giant's two intro videos play and its main menu renders |
 | 32-bit game on the bridge: framerate falls over minutes, purple/garbled geometry, then `Could not allocate memory: System out of memory!` (Spunky Dungeon) | The bridge's guest copies of mapped GL buffers were tracked per buffer target: a second buffer mapped on the same target lost the first one's copy (never written back: garbage vertices; never freed: ~10 MB/s until the guest's 4 GiB were full) | Fixed in the bridge (gl.c: mappings per buffer object). Check: the guest's `[anon:scudo:*]` maps below 4 GiB in /proc/<pid>/maps must stay flat |
@@ -120,7 +118,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | The game stays in its built-in language or waits at start although its OBB / files hold language packs (`<tag>.lang`, for example `de.lang`) | overport's platform loader answers `ovr_LanguagePack_GetCurrent/SetCurrent` with request id 0, so the game never gets the pack's path | `frame.langpacks` (opt-in, experimental, shown for games whose data has `*.lang`; `native/langpack`, build it with `python native/build.py --only langpack`). Default pack: the one the game applies, else env `FRAMEPORT_LANGPACK=<tag>`, else the only pack; search path override `FRAMEPORT_LANGPACK_DIRS`. Unreal games (Deadpool VR) gray out a pack whose asset `Metadata` differs from the game's version string: the patch writes the APK's versionName as Metadata (env `FRAMEPORT_LANGPACK_META` overrides) and reports the pack under the `/storage/emulated/0/Android/obb/<pkg>/` spelling of its path; with `/sdcard/…` the text switched but the dialogue stayed silent (verified in the headset with Deadpool VR) |
 | `ClassNotFoundException com.oculus.os.AnalyticsEvent` → abort | Quest telemetry lookup in Meta XR Audio (Unreal build) or native code | `frame.metaxr_telemetry` + `frame.oculusos` (automatic) |
 | `JNI DETECTED ERROR`, `GetStringUTFChars … NULL` | CheckJNI is on because overport marks the app debuggable | `frame.nodebug` |
-| Unreal game shows a one-time "optimizing" screen on its very first start, then closes (`System.exit` status 0 right after the system log's `ActivityTaskManager: START … LAUNCHER … pkg=<own package> … from uid 10xxx`, Lepton "Exited!"); the next start works | UE 4.21+ restarts the app after its first-run shader precompile (`r.ProgramBinaryCache.RestartAndroidAfterPrecompile`, `AndroidThunkJava_RestartApplication`); Lepton ends the container with the first process, the restarted one with it (Sports Scramble). Skipping the restart or setting the cvar to 0 (`-ini:Engine:[ConsoleVariables]:…` in UE4CommandLine.txt: read, no restart requested) left Sports Scramble on the "optimizing" level for good: the game relies on the restart | launch.sh starts Lepton once more (agent v86 `_restart_requested` matches both log lines within 5 s; `launch-before-restart.log` keeps the first run; `FRAMEPORT_NO_RESTART=1` turns it off). Works for 32- and 64-bit games |
+| Unreal game shows a one-time "optimizing" screen on its very first start, then closes (`System.exit` status 0 right after the system log's `ActivityTaskManager: START … LAUNCHER … pkg=<own package> … from uid 10xxx`, Lepton "Exited!"); the next start works | UE 4.21+ restarts the app after its first-run shader precompile (`r.ProgramBinaryCache.RestartAndroidAfterPrecompile`, `AndroidThunkJava_RestartApplication`); Lepton ends the container with the first process, the restarted one with it (Sports Scramble). Skipping the restart or setting the cvar to 0 (`-ini:Engine:[ConsoleVariables]:…` in UE4CommandLine.txt: read, no restart requested) left Sports Scramble on the "optimizing" level for good: the game relies on the restart | launch.sh starts Lepton once more (`_restart_requested` matches both log lines within 5 s; `launch-before-restart.log` keeps the first run; `FRAMEPORT_NO_RESTART=1` turns it off). Works for 32- and 64-bit games |
 | Unreal game quits a few seconds after start (`System.exit`) | ForceQuit after a failed Quest platform check | alternate build with `patch_remove_unreal_force_quit` (`use_alt`) |
 | Unreal game crashes a few seconds after the logo with no backtrace (Unreal's own signal handler hides it: logcat-crash.log empty, Zygote `exited due to signal 11`); the crashing thread is `GameThread`, pc in `libaaudio.so`, lr `libovrplatformloader.so (ovr_Microphone_GetOutputBufferMaxSize+0x10)`; the last platform call is `ovr_Microphone_Create` (for example The Walking Dead: Saints & Sinners Ch. 2) | OVRPort's platform loader opens the microphone's AAudio stream only in `ovr_Microphone_Start`, but `GetOutputBufferMaxSize` reads that stream unchecked; Unreal's Oculus voice asks for the size right after `Create` | `frame.ovr_microphone` (NULL check rewritten in place; size 0 until the microphone starts). OVRPort runtime 3.4.3-aa54c3f has the check itself: builds made with it leave the patch out (log "not needed: frame.ovr_microphone", `patches/upstream.py`) |
 | `xrCreateSwapchain` -26 / format unsupported (GLES) | Frame takes only sRGB formats, no MSAA | adapter `swapchain_fix` (default on) |
@@ -130,18 +128,18 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | SIGABRT right after start, backtrace `libopenxr_loader.so (xrCreateSwapchain+…)` | overport's dispatcher aborts on swapchains > 4096 px ("Wrong createInfo size"); video players use 7680×3840 theater textures | `frame.swapchain_limit` (default on; guard → 16384 px; triage `swapchain-size-abort`), for example 4XVR |
 | Cube loading screen missing/frozen, `cube_standin: dropped a layer (type=1000006000)` (HardBullet #385, Budget Cuts #107) | Runtime refuses cube swapchains and composites only quad/projection layers | Rebuild with `cube_standin=1`, `cube_quads=1` (defaults): mip-0 cube faces become six inward quads. Pools reuse six swapchains per size/format, with array slices for distinct cubes. Cubes are conservatively skipped in any frame containing a projection, since Frame draws quads above it. Allocation/copy failure falls back to dropping with `cube_quads:` diagnostics. Host-tested; headset visuals pending |
 | Video/menu panel missing, log `dropped N unusable layer(s)` with cylinder (1000017000) or equirect2 (1000091000) layers | the Frame runtime lacks XR_KHR_composition_layer_cylinder/equirect(2)/cube (its SteamVR runtime only composites quad + projection layers) | adapter shows cylinders as flat strips (setting `cylinder_strips`, default on); 360° equirect layers (theaters, 360° videos): `adapter.equirect_emul` (GLES only, per game) |
-| 360° theater / 360° video black or missing (for example 4XVR) | equirect layers dropped | `adapter.equirect_emul=1`: a worker thread with a shared GLES context converts each 360° image to a cube map when it changes and draws one adapter projection layer from it for every frame with exactly that frame's views; it replaces the 360° layers in place, so the game's own projection layer (balcony, controllers, 360° videos it draws itself) stays on top. Quads can't be used: the Frame draws quad layers above every projection layer whatever the order. Log: `first 360 view ready`, `in 5 s: N 360 image update(s) … M view redraw(s)`. Upside down / mirrored / behind you: `equirect_flip` 1/2/4 (`frameport settings <pkg> equirect_flip=1`, no rebuild). Never Vulkan (a Vulkan renderer hung the Frame's GPU in AC Nexus) |
+| 360° theater / 360° video black or missing (for example 4XVR) | equirect layers dropped | `adapter.equirect_emul=1`: a worker thread with a shared GLES context converts each 360° image to a cube map when it changes and draws one adapter projection layer from it for every frame with exactly that frame's views; the layer replaces the 360° layers in place, so the game's own projection layer (balcony, controllers, 360° videos it draws itself) stays on top. Quads can't be used: the Frame draws quad layers above every projection layer whatever the order. Log: `first 360 view ready`, `in 5 s: N 360 image update(s) … M view redraw(s)`. Upside down / mirrored / behind you: `equirect_flip` 1/2/4 (`frameport settings <pkg> equirect_flip=1`, no rebuild). Never Vulkan (a Vulkan renderer hung the Frame's GPU in AC Nexus) |
 | Fades to black don't show: you see the level loading behind a loading screen (Batman: Arkham Shadow, GitHub #197); with `layer_debug=1` launch.log shows `color scale 0.00 0.00 0.00 …` on the projection layer | the game fades by dimming its eye image with XR_KHR_composition_layer_color_scale_bias; whether the Frame's runtime applies it isn't confirmed in the headset yet | `adapter.fade_quad=1` (opt-in, `native/adapter/fade_quad.c`): FrameBridge adds a black, alpha-blended quad right after the dimmed projection layer (VIEW space, 1 m ahead, 6×6 m; opacity = 1 − scale in 16 steps from one 8×8 swapchain refilled only when the step changes: Vulkan clear / GLES clear; one swapchain per step hit XR_ERROR_LIMIT_REACHED in Batman), log `fade_quad: drawing fades over the picture`; `fade_quad=2` also removes the layer's own scale (if both show, the fade is doubled) |
 | GAZZLERS stops at start: `Exception: Current Platform is not supported` at `PlatformDeterminer.GetAndroidPlatform` (GitHub #404) | the game chooses its Meta/PICO code from `SystemInfo.deviceModel` ("pico"/Quest substrings) and throws for anything else; Lepton's Android is "Valve Lepton" (write-once `ro.product.*`, not settable through `LEPTON_GFXRECON_*` boot properties) | `frame.gazzlers_quest_platform` (catalog): `PlatformDeterminer.GetAndroidPlatform` -> 1 (Platform.Meta) in libil2cpp.so (Cpp2IL), the path it takes on a Quest |
 | Vermillion: the hand and brush disappear over the canvas while painting, but still paint (GitHub #200) | the game shows a canvas being painted as its own compositor (quad) layer and turns the canvas's scene renderer off; the Frame draws quad layers above every projection layer whatever the order, so the canvas covers the hand (Vulkan game: no GL layer emulation) | `frame.vermillion_scene_canvas` (catalog): `PaintableMesh.HasCompositorLayerAvailable` / `ShouldUseCompositorOverlay` -> false in libil2cpp.so (Cpp2IL), so the game's own fallback draws the canvas in the scene (Klownicle's finding) |
 | Unity game hangs right after its first frames, no `pacing:` lines; SIGQUIT dump shows UnityMain in a game library's `JNI_OnLoad` → `usleep` (for example SKYBOX: `libskybox.so`, `SignatureChecker`) | the game checks its APK signing certificate; every port is re-signed | can't be fixed without defeating anti-tamper (FramePort doesn't): mark "Can't run". Diagnose hangs: `podman exec <container> kill -3 <pid>` writes all thread stacks to launch.log |
 | Video player doesn't list sent videos (for example 4XVR "Internal Storage" only shows some) | the player lists its own /sdcard folder (4XVR: /sdcard/4XPlayer), not /sdcard/Movies; Android's media index doesn't work in Lepton | game page "Add videos" / game menu "Add videos and files" (Videos + the app's own folder, hard links) or `frameport frame send <files> --app <pkg>` |
-| One eye gray in a stereo video, extra menus close, or the game stops drawing after a new eye-image set; log `xrCreateSwapchain … result=-10` | the runtime refused a swapchain (XR_ERROR_LIMIT_REACHED): about 15 live swapchains per session | `adapter.swapchain_pool=1` shares extra panel images in atlases: GLES (#387, 4XVR) and Vulkan (#424, AC Nexus with the Quest 3 identity; Vulkan pools only sRGB format-43 panels, never eye images). Log `swapchain_pool: virtual WxH [Vulkan] (…)`. This is a count cap, so lowering resolution does not fix it; headset validation pending |
+| One eye gray in a stereo video, extra menus close, or the game stops drawing after a new eye-image set; log `xrCreateSwapchain … result=-10` | the runtime refused a swapchain (XR_ERROR_LIMIT_REACHED): about 15 live swapchains per session | `adapter.swapchain_pool=1` shares extra panel images in atlases: GLES (#387, 4XVR) and Vulkan (#424, AC Nexus with the Quest 3 identity; Vulkan pools only sRGB format-43 panels, never eye images). Log `swapchain_pool: virtual WxH [Vulkan] (…)`. The limit is a count cap, so lowering resolution does not fix it; headset validation pending |
 | VrApi game (32-bit bridge or `frame.vrapi_bridge`): holding the menu button to recenter turns the view ~90-120 degrees to the side | the bridge's app space is LOCAL + the head's yaw at the start; the Frame's recenter moves LOCAL to the head, so the old yaw was added again | fixed in the VrApi bridge (2026-10-13): on XR_TYPE_EVENT_DATA_REFERENCE_SPACE_CHANGE_PENDING (LOCAL) and on `vrapi_RecenterPose` it takes the origin from the head again (log `recentered: head yaw …`); rebuild the game |
 | Menu/screen jumps to where you look (for example 4XVR) | the app re-creates LOCAL spaces (4XVR: every 2–4 s) and the Frame places them at the current head yaw, or the app recenters after the Frame's brief focus dips | turn on `adapter.layer_debug`, check `that LOCAL space sits at … deg` vs `focus_hold: hid a … ms focus dip`; patches: `adapter.stable_local` (new LOCAL spaces line up with the first) / `adapter.focus_hold` (on by default: hides dips up to `focus_hold_ms` once the game has been focused for a second; never at start-up: a global debounce broke AC Nexus) |
 | Pointer misses menu items | the Frame's aim pose differs from Touch's | `adapter.layer_debug` logs `aim in grip … pitch/yaw`; correct with `aim_pitch`/`aim_yaw`/`aim_forward` (`frameport settings`, no rebuild) |
 | Video stutters although fps is steady | video frame rate doesn't divide the refresh rate (30 fps at 72 Hz) | `adapter.refresh_rate` (for example 90 for 30 fps, 72 for 24 fps); `layer_debug` logs the offered rates and the app's own requests |
-| A saved 90 Hz refresh setting still launches at 72 Hz (for example Jurassic World Aftermath); FrameBridge reads `refresh_rate=90` but logs result `-1000101000` | The Frame's OpenXR runtime only enumerates its current rate and rejects requests for another mode (`XR_ERROR_DISPLAY_REFRESH_RATE_UNSUPPORTED_FB`) | Agent v92 applies `adapter.refresh_rate` to SteamVR's per-game `preferredRefreshRate` through IVRSettings, on save/install and before Lepton starts (existing launchers upgrade on connection). `0` clears the override; unavailable SteamVR is retried at launch. Device-tested: Aftermath selected 90 Hz and sustained 90.2 fps |
+| A saved 90 Hz refresh setting still launches at 72 Hz (for example Jurassic World Aftermath); FrameBridge reads `refresh_rate=90` but logs result `-1000101000` | The Frame's OpenXR runtime only enumerates its current rate and rejects requests for another mode (`XR_ERROR_DISPLAY_REFRESH_RATE_UNSUPPORTED_FB`) | FramePort applies `adapter.refresh_rate` to SteamVR's per-game `preferredRefreshRate` through IVRSettings, on save/install and before Lepton starts (existing launchers upgrade on connection). `0` clears the override; unavailable SteamVR is retried at launch. Device-tested: Aftermath selected 90 Hz and sustained 90.2 fps |
 | PC VR game judders/stutters although the GPU keeps up; vrcompositor.txt "Timed out. N total" high or frames dropped | the game misses the headset's refresh (for example 96 Hz = 10.4 ms; Stormland's slow frames take 10.7 ms) | `pcvr.steamvr_tuning` (default on): next Play sets SteamVR per-app `preferredRefreshRate` + `motionSmoothingOverride` via `fp_vrsettings.exe` |
 | Quest app keeps recentering / snapping the view when you turn your head; log shows session state 5→4→3→4→5 within a second | the Frame briefly takes focus; the app recenters on focus changes | adapter `focus_hold` (on by default; an earlier global debounce made AC Nexus stay black and was removed) |
 | Video player / app finds no local videos; MediaProvider "Requested path /home/steamos/... doesn't appear under ..." | Lepton's /sdcard is a symlink to a host path, so Android's media index rejects every file | upload in the Files tab (Videos = /sdcard/Movies) and browse folders in the app |
@@ -154,8 +152,8 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Game (Unity, GLES) freezes, `zink: DEVICE LOST` | multisampled render-to-texture hangs the GPU | `frame.unity_no_msaa`; if it persists: unfixable → PC version |
 | Unreal GLES game crashes ~3 s after start: `Fatal signal 11 … fault addr 0x10000 in tid … (RHIThread)`, `#01 … libgallium_dri.so` (GitHub #83 Star Wars Pinball VR, triage `unreal-msrtt-crash`) | Unreal's mobile MSAA renders through multisampled render-to-texture; Zink's `find_rp_state` then indexes `rendering_state_cache[6]` one past its end (sample count ≥ 32) and calls a junk hash function (0x10000). Mesa bug (no bounds check) | `frame.unreal_gl_shim` (GL shim with `gl_hide_msrtt`, multiview kept for Unreal: Unreal 4.25 only enables multiview with GL_OVR_multiview, GL_OVR_multiview2 **and** GL_OVR_multiview_multisampled_render_to_texture, so the shim keeps the last one visible for Unreal and maps glFramebufferTextureMultisampleMultiviewOVR to the single-sampled glFramebufferTextureMultiviewOVR; log `multiview multisampled render-to-texture (N samples) drawn single-sampled`) |
 | Crash with `SIGILL (ILL_ILLOPN)` and `*pc=0xd50323bf` (autiasp), for example on Unreal's HttpManager thread (GitHub #83 Star Wars Pinball VR, triage `pac-unpaired`) | The engine's OpenSSL ARMv8 assembly has autiasp without a matching paciasp (libUE4.so: 38 paciasp, 40 autiasp; Poly1305 NEON). Quest CPUs treat PAC hints as NOPs, the Frame's CPU checks them | `frame.pac_hints`: in a library with unpaired counts every paciasp/autiasp becomes a NOP (in place) |
-| launch.log stops at `Waiting for app …` (nothing after it, `logcat: Unexpected EOF!` or `Logcat read failure`); the game runs, but Steam's "Resume game" menu isn't closed, the launch test shows nothing and session triage has no log (Vader Immortal on Lepton 3.0.5, Under Cover on 2.8.14; a silent mirror twice on 3.0.5 on 2026-10-14) | Lepton's logcat mirror died or never wrote | `_logcat_keeper` (started by launch.sh, added to older launchers by `upgrade_launchers`; agent v91) reads the container's logcat itself after a failure line or 20 s without a logcat line (`podman exec lepton-steamlaunch-<appid> logcat -v threadtime -T <epoch>`: from the launcher's start, or from just before the mirror's last line), sets a 16 MiB log buffer and appends to launch.log; log `<base>/logcat-keeper.log` |
-| A game no longer starts after a reinstall that was launch-tested right away: logcat `Zip: EOCD not found, …/base.apk is not zip` / `Failed to parse …base.apk`, no `Start proc` for the game (VR HOT, 2026-10-09) | The launch test's 45 s ran from the launcher, but the first start after an APK change spends ~1–2 min booting Lepton and installing the app: stopping the container mid-install left a broken installed copy | Agent v68: the test window counts from Lepton's `Waiting for app` (at most 240 s extra for boot + install). Repair a broken one: `touch <base>/lepton-app/game.apk` (Lepton re-installs it on the next start) |
+| launch.log stops at `Waiting for app …` (nothing after it, `logcat: Unexpected EOF!` or `Logcat read failure`); the game runs, but Steam's "Resume game" menu isn't closed, the launch test shows nothing and session triage has no log (Vader Immortal on Lepton 3.0.5, Under Cover on 2.8.14; a silent mirror twice on 3.0.5 on 2026-10-14) | Lepton's logcat mirror died or never wrote | `_logcat_keeper` (started by launch.sh, added to older launchers by `upgrade_launchers`) reads the container's logcat itself after a failure line or 20 s without a logcat line (`podman exec lepton-steamlaunch-<appid> logcat -v threadtime -T <epoch>`: from the launcher's start, or from just before the mirror's last line), sets a 16 MiB log buffer and appends to launch.log; log `<base>/logcat-keeper.log` |
+| A game no longer starts after a reinstall that was launch-tested right away: logcat `Zip: EOCD not found, …/base.apk is not zip` / `Failed to parse …base.apk`, no `Start proc` for the game (VR HOT, 2026-10-09) | The launch test's 45 s ran from the launcher, but the first start after an APK change spends ~1–2 min booting Lepton and installing the app: stopping the container mid-install left a broken installed copy | The test window counts from Lepton's `Waiting for app` (at most 240 s extra for boot + install). Repair a broken one: `touch <base>/lepton-app/game.apk` (Lepton re-installs it on the next start) |
 | Unreal game (OVRPlugin) never starts VR: launch.log has `OVRPlugin: JNI_OnLoad` but never `CompositorOpenXR::PreInitialize`, no OpenXR session, then a crash a few seconds in (for example Star Wars Pinball VR, UE 4.25: null pointer in `FSceneRenderer::GetMultiViewSceneColor`, GitHub #83) | Unreal's Oculus module looks up every `ovrp_*` function of the OVRPlugin it was built against (`InitializeOculusPluginWrapper`, all ANDed); OVRPort's OpenXR OVRPlugin lacks a few old ones (UE 4.25 / OVRPlugin 1.44: `ovrp_GetPTWNear`), so the wrapper fails and OculusHMD is never pre-initialized | `frame.unreal_ovrp_entrypoints` (suggested when analysis `unreal_ovrp_lookups` name functions the shipped OVRPlugin lacks): generated `libfp_ovrpstubs.so` (DT_NEEDED of libOVRPlugin.so; dlsym on the plugin's handle searches its dependencies) with a stand-in per missing name returning ovrpFailure (-1000); build note lists the names |
 | Only the Android home screen shows; the log has Unity's VR device as `None` (for example Accounting+, Unity 2017) | Unity 2017–2018 built-in Oculus support starts VR only when `com.oculus.systemactivities` is installed; Lepton has no Meta system apps, so Unity falls back to non-VR | `frame.unity_oculus_check`: that package name in libunity.so → `android`, plus `native/ovrpshim` (libfp_ovrp.so): Unity 2017's legacy frame loop (`ovrp_Update2`/`ovrp_BeginFrame`) never calls `ovrp_WaitToBeginFrame`, so without the shim no `xrWaitFrame` happens, `CompositorOpenXR::Update … outside of frame bounds` floods the log and the dashboard freezes. With it: log `ovrp frame loop shim: waited for frame N`, ~71 fps. Accounting+ then stops at "press any button" although its OVRInput gets clean input (`INPUT_PROBE` in the patch logs connected controllers/buttons/input focus per call) — unresolved |
 | Stuck on the loading screen or quits at start; `Unable to open archive file`, `is corrupted! Remove it and launch unity again` or `Failed to read data for the AssetBundle` in launch.log (for example Batman, GitHub #155) | The game's data folder (OBB) is incomplete or from another version than the APK | Copy the whole data folder again from the same install as the APK, add the game again, reinstall (triage `unity-data-missing`) |
@@ -171,7 +169,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Godot 4 app crashes at start: `java.lang.NullPointerException: null cannot be cast to non-null type android.content.ClipboardManager` at `org.godotengine.godot.Godot.<init>` (Godot 4.3/4.4; 4.2 when the clipboard is first used, in `Godot$mClipboard$2.invoke`) (for example EndoparasiticVR, GitHub #134); triage `godot-no-clipboard` | Lepton's Android has no clipboard service and Godot's Kotlin code casts it with a non-null `as ClipboardManager` (`Intrinsics.checkNotNull` before the check-cast). Godot 4.1 (Java) and 4.5+ (`as?`) don't throw | `frame.godot_clipboard` (suggested by analysis `godot_clipboard`): that checkNotNull call → nops in classes.dex (check-cast accepts null), and Godot's getClipboard/hasClipboard/setClipboard return at once ("" / false / nothing; `Dex.return_early`), in place; matched exactly, other dex files untouched. Checked against the Maven godot-lib 4.2.2/4.3.0/4.4.1 and the 4.3/4.4.1 release export templates (D8 re-reads the result); not yet run on the device |
 | Game crashes at start: `java.lang.NoSuchMethodError: No virtual method getAvailableCommunicationDevices()… in class Landroid/media/AudioManager` at `com.vivox.sdk.AudioChangeListener.checkAudioRouteAndApplyChanges` (for example Green Hell VR, GitHub #101); triage `vivox-api31` | Newer Vivox (voice chat) builds call Android 12 audio-routing methods without a version check; Lepton is Android 11. Older Vivox builds (Eleven Table Tennis, BattleSisters) don't have that code | `frame.vivox_audio_route` (suggested by analysis `vivox_api31`): every AudioChangeListener method that calls one of them returns at once (`Dex.return_early`: return-void / `const/4 v0, 0; return v0`, in place); voice chat keeps the default audio route |
 | Game crashes when voice chat starts (Table Troopers: at the tutorial's start): `java.lang.NoSuchMethodError: No virtual method getAvailableCommunicationDevices()… in class Landroid/media/AudioManager` at `com.exitgames.photon.audioinaec.AudioInAEC.updateAudioDevice` ← `AudioInAEC$1.run` (GitHub #362/#325); triage `photon-voice-api31` (the same error from another library: `audio-api31`, report it) | Photon Voice's Android microphone plugin picks the audio device with Android 12 methods (getAvailableCommunicationDevices / setCommunicationDevice) and has no version check (it logs "Start: SDK >= 31, using BroadcastReceiver" on every Android); Lepton is Android 11. `frame.vivox_audio_route` only edits Vivox's class, so it can't help here | `frame.photon_voice_audio_route` (suggested by analysis `photon_voice_api31`): AudioInAEC.updateAudioDevice (void, the only caller) returns at once (`Dex.return_early`, in place); the microphone thread goes on (communication mode, echo canceller, AudioRecord) on the default route. Checked against Table Troopers' classes.dex; not yet run on the device |
-| A game on a microSD card or another drive doesn't start, loses its saves or loops at start; launch.log has `ln: cannot create symbolic link from 'Frame' to '/data/data/<pkg>'` or `Couldn't create directory for SharedPreferences file /data/user/0/<pkg>/…` (GitHub #213/#214/#215/#221: a card named "Steam Frame 512g"); triage `lepton-data-link-failed` | Valve's Lepton pastes `STEAM_COMPAT_DATA_PATH` unquoted into `sh -c "ln -s …/internal/<pkg> /data/data/<pkg>"` (liblepton mounting.sh) and APK paths into unquoted substitutions, so a path with a space never gets the app's internal storage | agent v83: the Quest launcher links the game folder to `~/.local/share/frameport/lepton-paths/<pkg>` at every start and gives Lepton that path (`app_dir_lines`); `upgrade_launchers` converts existing launchers at the next connection; deployment.json keeps the real path |
+| A game on a microSD card or another drive doesn't start, loses its saves or loops at start; launch.log has `ln: cannot create symbolic link from 'Frame' to '/data/data/<pkg>'` or `Couldn't create directory for SharedPreferences file /data/user/0/<pkg>/…` (GitHub #213/#214/#215/#221: a card named "Steam Frame 512g"); triage `lepton-data-link-failed` | Valve's Lepton pastes `STEAM_COMPAT_DATA_PATH` unquoted into `sh -c "ln -s …/internal/<pkg> /data/data/<pkg>"` (liblepton mounting.sh) and APK paths into unquoted substitutions, so a path with a space never gets the app's internal storage | the Quest launcher links the game folder to `~/.local/share/frameport/lepton-paths/<pkg>` at every start and gives Lepton that path (`app_dir_lines`); `upgrade_launchers` converts existing launchers at the next connection; deployment.json keeps the real path |
 | Start never finishes, 100 % CPU, launch.log of gigabytes repeating `EOSSDK.createKeychain` / `resetKeychain` (Beyond Sandbox, GitHub #214); triage `eos-keychain-loop` | Epic Online Services' Java keychain can't write its SharedPreferences and resets/creates without end (seen when the app had no internal storage, row above) | fix the storage first; `frame.eos_keychain_loop` (opt-in, offered by triage; analysis `eos_keychain`) makes `EOSSDK.resetKeychain` return at once (`Dex.return_early`) |
 | Game quits ~20 s after start (Titan Isles, GitHub #310); launch.log has `FATAL EXCEPTION: GoogleApiHandler` `java.lang.NoSuchMethodError: No virtual method permitUnsafeIntentLaunch()` at `com.google.android.gms.common.internal.zzp` (play-services-basement); triage `gms-android12-call` | Not the missing Play services: the APK was built for minSdk 32, so R8 folded Play services' `PlatformVersion.isAtLeastS()`/`isAtLeastSv2()` to `return true`; OVRPort lowers minSdk, the folded checks stay, and Lepton (Android 11) lacks the Android 12 method | `frame.gms_platform_version` (suggested by analysis `gms_folded_sdk_checks`): those constant checks return false again (in-place dex edit) |
 | App quits a few seconds after OpenXR starts (PianoVision, GitHub #297, after `frame.unity_appui_vibrator`); launch.log has `FATAL EXCEPTION: MidiDeviceConnectionWatchThread` `NullPointerException: … UsbManager.getDeviceList()' on a null object reference` at `jp.kshoji.driver.midi.device.MidiDeviceConnectionWatcher$MidiDeviceConnectionWatchThread.checkConnectedDevices`; triage `usb-midi-watcher` | Lepton's Android has no USB service (`getSystemService("usb")` is null); kshoji's USB MIDI driver polls it | `frame.usb_midi_watcher` (suggested by analysis `usb_midi_watcher`): the poll returns at once; no USB MIDI on the Frame |
@@ -179,8 +177,8 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Unity game freezes on its loading screen ~10-15 s in (Yupitergrad, GitHub #235); launch.log has `GrantPermissionsActivity: Permission grant result … permission=android.permission.BLUETOOTH_CONNECT`, then OVRPlugin `SetupDisplayObjects(): Unable to find EGLConfig for configId 0` and no more frames; triage `bhaptics-permission-prompt` | bHaptics' vest SDK (`com.bhaptics.commons.PermissionUtils.requestBluetoothPermission`) asks for Android 12's BLUETOOTH_CONNECT; on Lepton's Android 11 it can't be granted at install, so Android's permission screen takes the foreground for a moment, the game pauses/resumes and OVRPlugin's GLES compositor stops drawing | `frame.bhaptics_permission` (suggested by analysis `bhaptics_permission`): the request returns at once (`Dex.return_early`) |
 | Unity game aborts at start: `Abort message: 'cannot create thread specific key for __cxa_get_globals()'` (SIGABRT in a library such as `libFirebaseCppApp-*.so`, for example Wander 0.3570, GitHub #198); triage `pthread-keys-exhausted` | Bionic allows 128 pthread keys per process; Unity 6 takes ~40 (most without a destructor), large native libraries (Gecko `libxul.so`, Firebase, avatar SDKs) and the Frame's own libraries (Mesa/Zink, FrameBridge, OVRPort, Valve's Vulkan layers) take the rest | `frame.unity_tls_key_pool` (opt-in; suggested for Unity 6 with Firebase C++ or Gecko): libunity.so's `pthread_key_*`/`pthread_get/setspecific` imports are renamed to `fp_tkey_*` (`elf.rename_imports`, versions set global) and `libfp_tkeys.so` (`native/tlskeys`) is added to its DT_NEEDED; destructor-less keys become slots behind one real key (logs `fp_tkeys: pooling Unity's thread keys`). Approach by Klownicle (#198) |
 | Controllers do nothing (for example stuck on a setup screen); log: `xrSuggestInteractionProfileBindings … XR_ERROR_PATH_UNSUPPORTED` | the game only suggests bindings for Meta's newer profiles (Touch Plus / Touch Pro); the Frame's Android runtime knows `oculus/touch_controller`, not those | adapter `profile_remap` (default on): the bindings are suggested again for Touch (log: `controller profile … -> oculus/touch_controller`) |
-| Controllers "don't sync": virtual hands/controllers lie on the floor below you, no buttons (Unity OpenXR games that only suggest Touch Plus/Pro, e.g. Hotel Infinity #327); log with `input_diag=1`: only `meta/touch_controller_plus` (or Pro) suggested, `controller profile … -> oculus/touch_controller` | the runtime then reports `oculus/touch_controller` for each hand, a profile the game never suggested: Unity's OpenXR input creates no device for it | adapter `profile_remap` (default on) reports the game's own profile for such hands (log: `profile_remap: /user/hand/left reported as meta/touch_controller_plus`) |
-| Controllers "don't sync": hands on the floor below you, no buttons, in a Unity OpenXR game with Meta's OpenXR features (e.g. Spatial Zombies #328); log: `xrCreateAction: XR_ERROR_PATH_UNSUPPORTED` (input_diag: `xrCreateAction -> XR_ERROR_PATH_UNSUPPORTED (thumbstick)`), then `xrGetCurrentInteractionProfile: XR_ERROR_ACTIONSET_NOT_ATTACHED` | Meta's "Detached … Controller" devices add `/user/detached_controller_meta/left|right` to Unity's merged actions; the Frame has no XR_META_detached_controllers, the action fails and Unity attaches no action set (OVRPlugin's input goes with it) | adapter `profile_remap` (default on) leaves those paths out of actions and bindings (log: `profile_remap: action thumbstick without 2 detached-controller path(s)`) |
+| Controllers "don't sync": virtual hands/controllers lie on the floor below you, no buttons (Unity OpenXR games that only suggest Touch Plus/Pro, for example Hotel Infinity #327); log with `input_diag=1`: only `meta/touch_controller_plus` (or Pro) suggested, `controller profile … -> oculus/touch_controller` | the runtime then reports `oculus/touch_controller` for each hand, a profile the game never suggested: Unity's OpenXR input creates no device for it | adapter `profile_remap` (default on) reports the game's own profile for such hands (log: `profile_remap: /user/hand/left reported as meta/touch_controller_plus`) |
+| Controllers "don't sync": hands on the floor below you, no buttons, in a Unity OpenXR game with Meta's OpenXR features (for example Spatial Zombies #328); log: `xrCreateAction: XR_ERROR_PATH_UNSUPPORTED` (input_diag: `xrCreateAction -> XR_ERROR_PATH_UNSUPPORTED (thumbstick)`), then `xrGetCurrentInteractionProfile: XR_ERROR_ACTIONSET_NOT_ATTACHED` | Meta's "Detached … Controller" devices add `/user/detached_controller_meta/left|right` to Unity's merged actions; the Frame has no XR_META_detached_controllers, the action fails and Unity attaches no action set (OVRPlugin's input goes with it) | adapter `profile_remap` (default on) leaves those paths out of actions and bindings (log: `profile_remap: action thumbstick without 2 detached-controller path(s)`) |
 | Some buttons do nothing or the wrong thing (for example a Quest game's X/Y on the Frame's left controller) | the game binds only Quest Touch and SteamVR maps Touch onto the Frame controllers with its own remap (Touch left X/Y land on the d-pad, right X and Y repeat B), or the runtime rejected a profile or an input call | choose **Game settings → Controllers → Controller buttons**: Mirror (`quest_buttons=1`) or Quest pair (`2`); `0` restores SteamVR default. **Settings → Controllers** sets the global default and can apply it to installed games without overrides. Used from the next launch; [mapping and limits](CONTROLLERS.md). For rejected bindings, turn on adapter `input_diag` (`frameport settings <pkg> input_diag=1`) and inspect `input_diag:` lines: accepted profiles, rejected paths and input calls. With a mode enabled, expect `quest_buttons: frame_controller bindings (mode N, K bindings, D dropped): <XrResult>` |
 | Unity game hangs or the whole Frame restarts (for example in a menu); log: `The current MSAA level is 0, but the recommended MSAA level is 4. Switching to the recommended level.` (for example Lucky's Tale) | Meta's OVRManager (`useRecommendedMSAALevel`) turns 4x MSAA on at runtime, past QualitySettings; multisampled render-to-texture on GLES/Zink hangs the GPU | `frame.unity_runtime_msaa_off` (Cpp2IL: `OVRDisplay.get_recommendedMSAALevel` → 0) |
 | Unity game: one eye shows only effects or gray, the other is fine (for example I Am Cat, Oculus XR Plugin on GLES) | the game's single-pass multiview rendering goes wrong for array slice 1 (the adapter submits both slices correctly) | `frame.unity_multipass` (Cpp2IL: `OculusSettings.GetStereoRenderingMode` → MultiPass); `swap_eyes=1` tells whether the game or the adapter is at fault |
@@ -188,11 +186,18 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | VrApi bridge: never enters VR | Frame reaches FOCUSED later than Quest; tracking only when worn | bridge waits 30 s; test in the headset |
 | Unreal game (ILMxLAB, for example Vader Immortal) plays its intro, then stays on its loading card (portrait + progress bar) at 72 fps and ignores input (GitHub #49) | the menu waits for `UVRUtils::GetQuestShaderPrecompilePercent()` to reach 100 %; the precompile only starts when `IsRunningOnSantaCruz()` (a Quest), the other branch returns 0.0 | `frame.unreal_quest_precompile` (non-Quest branch returns 1.0; found by Klownicle); suggested when the engine exports that function (analysis `unreal_quest_gates`) |
 | Video in a game or player stutters, falls behind or drops to a few fps (4K/8K, for example a video player's 360° video, Batman's cutscenes); `OMX.google.*` / `c2.android.*` decoders in the log | Lepton's Android has only software decoders | `frame.hw_video_decode` (suggested when the APK uses MediaCodec/ExoPlayer/VLC; no APK change, reinstall): `OMX.frameport.{avc,hevc,vp9}.decoder` on the Frame's Iris hardware (H.264 High, HEVC Main, VP9 profile 0 up to 4096x2304; 8-bit; up to 8192 px), mounted into this game's container only (log `Iris hardware video/… decoder active`; launch.log `FramePort video: loading the Iris hardware codec plugin`). `Iris … unavailable` / `initialization failed (-12)` (triage `hw-video-decoder-busy`): another decoder holds the hardware, usually Steam's own hardware video decoding: turn it off in Steam, restart Steam. Video broken with it: Settings → Installing → Hardware video decoding off (all games) or `FRAMEPORT_NO_HW_VIDEO=1 %command%` (one game) |
+| `Rec.709 color space unavailable`, the game quits before xrCreateSession (GitHub #336, OutRun Quest VR) | The Frame's runtime has no XR_FB_color_space | Adapter setting `fb_color_space=1` (triage `color-space-missing` suggests it): FrameBridge offers the extension (v3), reports Rec.709 and accepts any colour space without converting. Reaches games with their own OpenXR loader; OVRPort's dispatcher can't forward the new functions. Device-unverified |
+| `AppSW recommended buffers unavailable`, the game quits at start with or without XR_FB_space_warp (GitHub #336, OutRun Quest VR) | The game requires Meta's Application SpaceWarp; the Frame's runtime reports no motion-vector size and its GLES swapchains take only sRGB colour formats. `hide_space_warp` can't help (the game refuses to start without the extension) | Adapter setting `space_warp_emul=1` (triage `appsw-required`): FrameBridge offers XR_FB_space_warp, reports a motion-vector size (the runtime's, else eye/4), serves the motion-vector + space-warp depth swapchains as its own GL textures / Vulkan images and strips `XrCompositionLayerSpaceWarpInfoFB` at xrEndFrame. Log `space_warp_emul:`. docs/DEVICE_NOTES.md#xr_fb_space_warp-emulation-336 |
+
+Foveation mode, area size and diagnostic test are per-game user preferences (discussion #365), excluded from
+shared working recipes. Saving Game settings rewrites launcher exports through `set_settings`; changes apply
+at the next game start without rebuilding or reinstalling. Existing builds need one update for dormant diagnostic
+support. Catalog `device.foveation` defaults and the guarded Batman/Climb 2 APK compatibility work remain supported.

 ## Picture problems (headset on)
 | Symptom | Cause | Fix |
 |---|---|---|
-| Found after playing: the game page's "Last session" (or `frameport session <pkg>`) lists a finding (agent v70 `session_log`: the newest `plays.log` session's launch.log, ≤4 MB, + its crash logcat + kernel GPU lines) | launch tests never reach FOCUSED or gameplay; the same `catalog/triage.yaml` signatures (sync_guard, pac_hints, unreal_gl_shim, vk_spec_fixes, …) now also run on real sessions, plus the frame-rate and focus-dip findings below | "Try this setting" (FrameBridge settings: written on the Frame at once via `set_settings`, used from the next start) / "Rebuild with this patch" (APK patches); launch-test sessions (`test <unix>` in plays.log) are skipped |
+| Found after playing: the game page's "Last session" (or `frameport session <pkg>`) lists a finding (agent `session_log`: the newest `plays.log` session's launch.log, ≤4 MB, + its crash logcat + kernel GPU lines) | launch tests never reach FOCUSED or gameplay; the same `catalog/triage.yaml` signatures (sync_guard, pac_hints, unreal_gl_shim, vk_spec_fixes, …) now also run on real sessions, plus the frame-rate and focus-dip findings below | "Try this setting" (FrameBridge settings: written on the Frame at once via `set_settings`, used from the next start) / "Rebuild with this patch" (APK patches); launch-test sessions (`test <unix>` in plays.log) are skipped |
 | Textures flicker, jump or smear while moving in an OVRPlugin game that renders space-warp swapchains (`xrCreateSwapchain 376x376 format=97` / `format=129`; triage `space-warp-used`, info + question) | Application SpaceWarp: half the frames plus motion vectors; the Frame's reprojection of them misbehaves (Into The Radius 2, Metro Awakening) | adapter `hide_space_warp=1`; offered as "Did textures flicker…?" after a play session, never applied on its own |
 | The game froze or closed and the kernel log has `hangcheck` / GPU fault / `msm_drm … recover` lines during the session (triage `gpu-hang`, play sessions only) | a shader or effect hangs the Frame's GPU (for example Vader Immortal's lightspeed jump) | capture the shaders (`adapter.vk_shader_dump=1` Vulkan, `adapter.zink_shader_dump=1` OpenGL ES: triage keeps the one matching the session's swapchain formats), play to the hang again and send a problem report (diagnostics carry the newest dumped modules); the maintainer adds a `vk_shader_fix` / `zink_shader_fix` catalog entry. `zink-device-lost` keeps its MSAA suggestions |
 | The game keeps pausing or recentring for a moment while worn (session finding `focus-dips`: ≥3 `focus: back after N ms` lines longer than the game's focus_hold_ms, up to 5 s) | the Frame's wear sensor flickers "HMD off"; FrameBridge logs every runtime focus loss/return (always, before focus_hold) | `adapter.focus_hold_ms=<longest dip + 250 ms, in 500 ms steps, ≤5000>` (or `adapter.focus_hold=1` when off) |
@@ -204,10 +209,9 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Team Beef port slows to a crawl after 5-10 minutes on any map; vrcompositor logs `WaitForPendingPresent: failed to wait for present` more and more often, until its watchdog aborts or the kernel oopses in `drm_gpuvm_validate_deferred_collect` (`msm_ioctl_gem_submit`, from the game's render thread) and the Frame restarts; `xrclient_<package>.txt` has `SXR_GL_CHECK: error:0x500 ... glGenTextures` (GitHub #237, QuestZDoom) | Same runtime GL-interop leak as above: the game leaves GL_INVALID_ENUM pending every frame. `/sys/kernel/debug/dri/0/gem` (readable as steamos) showed the game's GPU VM growing by ~105 objects a second (8,000 after 75 s headless); every GPU submit then has more objects to validate | `adapter.gl_error_clear=1`: suggested for every Team Beef port (`tbxr_libs`), set in QuestZDoom's catalog recipe. Headless 2026-10-24: the game's GPU objects stay flat (1,915 in total over 2 minutes), no SXR_GL_CHECK |
 | OpenGL ES game: the GPU hangs at one effect (freeze/exit, compositor watchdog, for example Vader Immortal's lightspeed jump) | a shader (as Zink compiles it) reads loop counters/accumulators before setting them | capture the SPIR-V (adapter `zink_shader_dump=1` writes every module to `files/fp_spirv/`, or a GPU capture), then a `zink_shader_fix` entry (same format as `vk_shader_fix`) + `frame.zink_shader_fix` (Vulkan layer under Zink, activated through GraphicsEnv's debug layer list); log `shader fix layer: fixed shader module N`; triage `zink-shader-fix-mismatch` when a Frame update changed the driver's output |
 | A game with a shader fix in its recipe (`vk_shader_fix` / `zink_shader_fix`, for example VR4, Vader Immortal) hangs the GPU again at the effect it was fixed for, after a game update; the log has `… shader fix(es) configured, none matched after N modules in S s (game updated?)` (triage `shader-fix-unmatched`, info) | fixes match a shader by exact size + SHA-256, so a changed shader is silently left alone; the shim/layer logs that line once per session when no configured fix matched 5 minutes after the first shader (checked only at shader creation; a match logs `fixed shader module`). Not reaching the effect yet gives the same line | capture the shaders again (`adapter.vk_shader_dump=1` / `adapter.zink_shader_dump=1`), play to the hang and send diagnostics; the maintainer updates the catalog's fix for the new shader. Never key this on the game's version string |
-| 2D Android app: Steam says it's running but nothing shows | Lepton runs apps headless unless the app folder has `lepton-show-flatscreen` | FramePort adds it for apps without VR (agent v28+); reinstall apps installed before |
+| 2D Android app: Steam says it's running but nothing shows | Lepton runs apps headless unless the app folder has `lepton-show-flatscreen` | FramePort adds it for apps without VR; reinstall apps installed by a very old FramePort |
 | A phone/tablet app shows nothing in the headset, or a VR app opens as a flat window | FramePort's VR/2D guess (`vr_kind`) is wrong for this app | patch `device.display_mode` → **Flat window** or **VR** (Customize → "Show as VR or as a flat window"), then Update on Frame |
-| An install button opens another program (or nothing) instead of FramePort | another program owns the link type, or the switch is off, or macOS (Flet can't receive links there) | Settings → Install links → **Use FramePort for these links**; else Add games → Install from a link… (paste the button's address) |
-| 2D Android game ignores the controllers: they only move a pointer, an SDL game keeps its touch controls ("no controller attached"); Android's log lists only `wayland_touch`/`wayland_keyboard`/`wayland_pointer` (GitHub #162, Skate 3) | Lepton's Android gets keyboard, pointer and touch from the Wayland seat only: no gamepad device | patch `device.steam_gamepad` (2D apps; suggested when the manifest declares `android.hardware.gamepad` or `LEANBACK_LAUNCHER`; no APK change, reinstall): the launcher puts FramePort's Podman wrapper (`~/.local/share/frameport/agent/bin/podman`) first on PATH, which binds the host's `/dev/input` at `/dev/fp-input` plus an Xbox 360 key layout (Vendor_28de_Product_11ff.kl, incl. D-pad buttons), and exports `LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD=1`; the launcher's `_gamepad_links` worker (agent v85) keeps `/dev/input/eventN` links to Steam Input's virtual pads (uinput, 28de, "Microsoft X-Box 360 pad N") in step while the game runs, so a pad Steam makes later (controllers woke up, reconnected) is added and a gone one removed (Android's EventHub follows through inotify). Check: `<base>/gamepad.log` (`pads: event5` / `pads: none`), launch.log `EventHub: New device … pad`, `podman exec lepton-steamlaunch-<appid> dumpsys input` lists the pad. Steam Input must be on for the shortcut; Steam activates the shortcut's own layout while the game has focus (controller.txt `Queueing activation for controller: 0 app: <shortcut appid as signed int>`), and Steam's UI layout (app 769) while the dashboard is open. Off for one start: `FRAMEPORT_NO_GAMEPAD=1 %command%` |
+| 2D Android game ignores the controllers: they only move a pointer, an SDL game keeps its touch controls ("no controller attached"); Android's log lists only `wayland_touch`/`wayland_keyboard`/`wayland_pointer` (GitHub #162, Skate 3) | Lepton's Android gets keyboard, pointer and touch from the Wayland seat only: no gamepad device | patch `device.steam_gamepad` (2D apps; suggested when the manifest declares `android.hardware.gamepad` or `LEANBACK_LAUNCHER`; no APK change, reinstall): the launcher puts FramePort's Podman wrapper (`~/.local/share/frameport/agent/bin/podman`) first on PATH, which binds the host's `/dev/input` at `/dev/fp-input` plus an Xbox 360 key layout (Vendor_28de_Product_11ff.kl, incl. D-pad buttons), and exports `LEPTON_ENV_SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD=1`; the launcher's `_gamepad_links` worker keeps `/dev/input/eventN` links to Steam Input's virtual pads (uinput, 28de, "Microsoft X-Box 360 pad N") in step while the game runs, so a pad Steam makes later (controllers woke up, reconnected) is added and a gone one removed (Android's EventHub follows through inotify). Check: `<base>/gamepad.log` (`pads: event5` / `pads: none`), launch.log `EventHub: New device … pad`, `podman exec lepton-steamlaunch-<appid> dumpsys input` lists the pad. Steam Input must be on for the shortcut; Steam activates the shortcut's own layout while the game has focus (controller.txt `Queueing activation for controller: 0 app: <shortcut appid as signed int>`), and Steam's UI layout (app 769) while the dashboard is open. Off for one start: `FRAMEPORT_NO_GAMEPAD=1 %command%` |
 | A 2D app's sign-in (or another link) says no browser is installed, and nothing opens (GitHub #466, Plex) | Lepton's Android has no browser package; the app checks for one (its manifest's `<queries>` ask for http/https VIEW handlers or a Custom Tabs service) before it starts the VIEW intent that Lepton would have sent to Steam's browser (`ActivityStarter.execute`: every VIEW → `steam://openurl/<url>` into `/lepton/steam.pipe`) | patch `frame.browser_handoff` (opt-in, game page "Browser for sign-ins: open pages in Steam's browser"; then Update on Frame): a browser stand-in activity + `classesN.dex` in the app's own APK; the app's check finds it and the page opens in Steam's browser. Check: launch.log `ActivityTaskManager: Intercepted VIEW`, Steam's console_log.txt `ExecCommandLine: "steam://openurl/…"`. A sign-in that returns to the app through a link can't complete (Lepton sends every VIEW to Steam); code/PIN sign-ins work. The first patched build is signed with FramePort's key (the app was installed unchanged before) |
 | Game starts in English and has no in-game language choice | Game follows Lepton's English Android locale | Choose Game language under Customize (`device.language`), then Update on Frame; the game must include the selected language |
 | 2D Android app: back/home/recents buttons cover the app's own buttons | Android's navigation bar | patch `device.hide_navbar` (on by default for apps without VR) sets `qemu.hw.mainkeys=1`; reinstall to apply |
@@ -220,18 +224,18 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | UI panels upside down (AC Nexus) | XrCompositionLayerImageLayoutFB VERTICAL_FLIP unsupported | adapter `flip_emul=1` (default: upside-down copies in an atlas, every frame); `flip_dump=N` saves what the runtime gets; rotating quads makes them vanish |
 | Passthrough black (BAM) | XR_FB_passthrough missing | adapter `passthrough_emul=1` (default) + `patch_force_passthrough` for MR-only games |
 | Mixed reality inside out: the room shows on the game's objects, black where the room should be (Unreal, for example Star Wars: Beyond Victory, GitHub #329) | Unreal keeps 1 - coverage in the scene alpha and OVRPlugin chains XrCompositionLayerAlphaBlendFB (colour factors ONE_MINUS_SRC_ALPHA / SRC_ALPHA, `layer_debug` shows `n=1000041001(3,2/3,2)`) to the eye layer; the Frame's runtime ignores it | adapter `alpha_blend_emul=1` (default, Vulkan): inverts the alpha of the eye images in place while passthrough is emulated; logs `alpha_blend: inverting the alpha of swapchain=…` |
-| Quest Touch controllers (or none) shown in a game that uses Meta's runtime controller models | XR_FB_render_model missing on the Frame | adapter `controller_models=1`: the agent converts the Frame's SteamVR controller models to glb at install, the adapter serves them. Games with their own controller meshes aren't affected (none of the 34 catalog games use runtime models) |
+| Quest Touch controllers (or none) shown in a game that uses Meta's runtime controller models | XR_FB_render_model missing on the Frame | adapter `controller_models=1`: the agent converts the Frame's SteamVR controller models to glb at install, the adapter serves them. Games with their own controller meshes aren't affected (no catalog game uses runtime models) |
 | `overportOXR: Unknown proc addr: xr…` for a function the adapter emulates | overport's dispatcher only forwards functions in its own table | route the plugin's lookups through `native/xrshim` (done for XR_FB_render_model when `controller_models=1`) |
 | MR game asks for a room scan | The game requested a new room through Meta scene capture | FramePort scans in the headset and loads the new room. `scene_scan_request=0` turns it off and uses the stored room. |
-| MR game stuck waiting for room data (e.g. Demeter) | No Meta scene API | `adapter.scene_emul=1` (+ `frame.meta_permissions`); Frame → Room → Use my play area, or import a scanned room |
-| Unity MR game rejects every room / its "use guardian" fallback does nothing; `ovrpBoundary_Outer is not supported`, `IndexOutOfRangeException` in a guardian check (e.g. Demeter's `RemoveObjectNotInGuardian`) | OVRPlugin calls the Frame's 1x1 m STAGE rect a configured boundary but can't give its outline | `adapter.scene_hide_bounds=1` (with `scene_emul`): FrameBridge then answers the app's STAGE `xrGetReferenceSpaceBoundsRect` with `XR_SPACE_BOUNDS_UNAVAILABLE` (log `scene: STAGE bounds hidden`). Per game only: NOPE stalled without a play area. Demeter also needs a floor of at least 2.5 x 2.5 m, as on a Quest |
-| MR game with `scene_emul` never asks for the room (no `scene: query`/`discovery` lines), black screen or MR mode with no room (e.g. NOPE, Pinball FX); `m_XR_META_boundary_visibility extension is not supported` every frame | Meta's scene/anchor permissions undeclared (Lepton can't grant them); boundary suppression unsupported | `frame.meta_permissions` (now with every `scene_emul` recipe of a USE_SCENE/USE_ANCHOR_API game, migration `scene_permissions`); FrameBridge emulates `XR_META_boundary_visibility` (log `scene: boundary suppressed`). `passthrough:` lines show the app's passthrough calls |
+| MR game stuck waiting for room data (for example Demeter) | No Meta scene API | `adapter.scene_emul=1` (+ `frame.meta_permissions`); Room tab → Scan room in the headset or Use my play area |
+| Unity MR game rejects every room / its "use guardian" fallback does nothing; `ovrpBoundary_Outer is not supported`, `IndexOutOfRangeException` in a guardian check (for example Demeter's `RemoveObjectNotInGuardian`) | OVRPlugin calls the Frame's 1x1 m STAGE rect a configured boundary but can't give its outline | `adapter.scene_hide_bounds=1` (with `scene_emul`): FrameBridge then answers the app's STAGE `xrGetReferenceSpaceBoundsRect` with `XR_SPACE_BOUNDS_UNAVAILABLE` (log `scene: STAGE bounds hidden`). Per game only: NOPE stalled without a play area. Demeter also needs a floor of at least 2.5 x 2.5 m, as on a Quest |
+| MR game with `scene_emul` never asks for the room (no `scene: query`/`discovery` lines), black screen or MR mode with no room (for example NOPE, Pinball FX); `m_XR_META_boundary_visibility extension is not supported` every frame | Meta's scene/anchor permissions undeclared (Lepton can't grant them); boundary suppression unsupported | `frame.meta_permissions` (now with every `scene_emul` recipe of a USE_SCENE/USE_ANCHOR_API game, migration `scene_permissions`); FrameBridge emulates `XR_META_boundary_visibility` (log `scene: boundary suppressed`). `passthrough:` lines show the app's passthrough calls |
 | Build says `Unity text fields: not fixed: Cpp2IL couldn't start on this PC` (older versions: `Cpp2IL couldn't read this game's code: at Cpp2IL.Program.Main`) | .NET aborts without libicu (fresh WSL/Linux) | FramePort runs Cpp2IL with `DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1`; such failures aren't cached, so the next build retries |
-| MR uses an empty/simple room; FrameBridge `scene: capture requested -> guardian box` / `using guardian room`, `room from guardian`, or fallback box dimensions (`mr-no-room`) | No saved room, so FrameBridge uses its guardian box | Save a room in Frame → Room. A real SteamVR boundary supplies walls; Valve's default circle is refused. Import a scanner-built room for furniture/mesh; headset capture is not implemented yet |
+| MR uses an empty/simple room; FrameBridge `scene: capture requested -> guardian box` / `using guardian room`, `room from guardian`, or fallback box dimensions (`mr-no-room`) | No saved room, so FrameBridge uses its guardian box | Scan or save a room in the Room tab (**Scan room in the headset**, or **Use my play area**: walls only, from a real SteamVR boundary; Valve's default circle is refused) |
 | `Unknown proc addr: xrDiscoverSpacesMETA` or MRUK `NoRoomsFound` (`mr-discovery-unsupported`) | Scene discovery is unavailable or no room was discovered | Enable `adapter.scene_emul`, rebuild/reinstall to get the updated extension shim, then save a room. All games declaring USE_SCENE or USE_ANCHOR_API now get this suggestion |
-| MR game: virtual objects (e.g. Laser Dance's lasers) vanish when you come close to them | Meta's Depth API occlusion: the Frame has no depth sensor (XR_META_environment_depth), so the environment depth the occlusion shaders read is never valid and near objects count as hidden behind the room | `frame.meta_depth_occlusion` (Unity IL2CPP; offered, not turned on, when the game has the HARD_OCCLUSION / SOFT_OCCLUSION keywords; analysis `meta_depth_occlusion`): EnvironmentDepthManager's checks -> false and its keyword setter does nothing (Cpp2IL), the keywords renamed in the asset files that contain them; Laser Dance's known build also gets its laser materials/LODs fixed. From PR #246; not checked in the owner's headset yet |
-| Unity MR game keeps asking for a room scan / `No scene model found` although FrameBridge served a room (OVRSceneManager with ActiveRoomsOnly) | OVRSceneManager loads only the room whose floor outline contains the player (IsUserInRoom); with the play-area room the player can stand outside it (FrameBridge logs the head against the floor outline: `scene: head in STAGE ... OUTSIDE the floor outline`) | Scan the room first (Frame → Room). Still stuck: `frame.unity_scene_active_rooms` (catalog or by hand, Unity IL2CPP scene games): IsUserInRoom / PointInPolygon2D -> true (Cpp2IL). From PR #246 (Laser Dance) |
-| MR game with many quads (21+): frames refused with `XR_ERROR_LAYER_LIMIT_EXCEEDED` (e.g. Punch Fit) | The runtime takes at most maxLayerCount (16) layers | FrameBridge keeps the projection layers and its own fade quad, then the app's other layers in submission order up to the limit (log `xrEndFrame: N layers exceed the runtime limit 16`). From PR #246 |
+| MR game: virtual objects (for example Laser Dance's lasers) vanish when you come close to them | Meta's Depth API occlusion: the Frame has no depth sensor (XR_META_environment_depth), so the environment depth the occlusion shaders read is never valid and near objects count as hidden behind the room | `frame.meta_depth_occlusion` (Unity IL2CPP; offered, not turned on, when the game has the HARD_OCCLUSION / SOFT_OCCLUSION keywords; analysis `meta_depth_occlusion`): EnvironmentDepthManager's checks -> false and its keyword setter does nothing (Cpp2IL), the keywords renamed in the asset files that contain them; Laser Dance's known build also gets its laser materials/LODs fixed. From PR #246; not checked in the headset yet |
+| Unity MR game keeps asking for a room scan / `No scene model found` although FrameBridge served a room (OVRSceneManager with ActiveRoomsOnly) | OVRSceneManager loads only the room whose floor outline contains the player (IsUserInRoom); with the play-area room the player can stand outside it (FrameBridge logs the head against the floor outline: `scene: head in STAGE ... OUTSIDE the floor outline`) | Scan the room first (Room tab). Still stuck: `frame.unity_scene_active_rooms` (catalog or by hand, Unity IL2CPP scene games): IsUserInRoom / PointInPolygon2D -> true (Cpp2IL). From PR #246 (Laser Dance) |
+| MR game with many quads (21+): frames refused with `XR_ERROR_LAYER_LIMIT_EXCEEDED` (for example Punch Fit) | The runtime takes at most maxLayerCount (16) layers | FrameBridge keeps the projection layers and its own fade quad, then the app's other layers in submission order up to the limit (log `xrEndFrame: N layers exceed the runtime limit 16`). From PR #246 |
 | Hand-tracking game janky (Silhouette) | Frame synthesizes hands from controllers | `controller_fix=0` passes hands through; not really fixable |
 | Eye distortion while moving (Arcsmith, Time Stall) | unknown (not eye swap, tracking, Valve layers, depth or pacing) | unresolved |
 | The Climb 666.0: hand outlines ripple in both eyes while menus and gameplay work (GitHub #238) | Unknown. Sessions paced around 72 fps, controller tracking reported valid, and SteamVR motion smoothing was already off; these checks do not establish the cause | Unresolved after wearer comparisons on 2026-10-12: disabling Valve's Vulkan layers, setting `r_AntialiasingMode = 1`, and setting `r_AntialiasingMode = 0` with `r_MotionBlur = 0` each gave the same or worse result. These were config comparisons; runtime cvar values were not verified. Restored the playable configuration (`r_vr_foveated = 0` with the default Vulkan layers), retaining the startup/rendering crash fixes above. Do not keep the unsuccessful experimental settings as a fix |
@@ -247,6 +251,15 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Unreal 5 game crashes in `vulkan.freedreno.so` called straight from `libUnreal.so` right after its swapchains, or a few seconds into the first frames (Metro Awakening) | Unreal turns on fragment-density-map foveation because Turnip offers VK_EXT_fragment_density_map, then records barriers (to `FRAGMENT_DENSITY_MAP_OPTIMAL`) and image views (2D array R8G8) for a density map the Frame never provides (VK_NULL_HANDLE); Turnip dereferences it | adapter `vk_hide_fdm=1` (the game doesn't see the extension) + `vk_spec_fixes=1` (leaves out null-image barriers, refuses null-image views); triage `unreal-fdm-missing`. Found by disassembling the driver at the crash pc: the struct offsets (0x58 = VkSubpassDescription2, 0x48/0x60 = image barriers, viewType/format in registers) name the call |
 | Own-engine game crashes in `je_free` from its own library on the first frames (Roblox) | the game frees memory it doesn't own; not the Vulkan shim or the format fallback | unsupported |

+## FramePort itself (uploads, links, store details)
+| Symptom | Cause | Fix |
+|---|---|---|
+| Uploads to the Frame are slow | The link, storage or transfer backend can limit throughput | Check the job's "Transfer link"; try the Frame's hotspot or USB cable. Large install files prefer system OpenSSH SFTP, retaining paired-host checks and `.part` resume; unavailable or failed native uploads fall back to Paramiko. The log names the backend. Settings → Installing → Parallel uploads accepts 1–8 (default 3; saved preferences are preserved). More is not always faster. Measure the production path with `scripts/upload_bench.py --methods app-files-3 --check-resume` (three repetitions, checksum verification) |
+| Log: `OpenSSH SFTP failed (255): … Permission denied (publickey,password)`, then Paramiko | OpenSSH offered keys the Frame doesn't authorize (GitHub #242) | The log lists the keys OpenSSH offered (`Offering public key`) and its warnings. A connection that logged in with the PC's own keys/agent makes OpenSSH use them too (copies of `~/.ssh/id_*` + the agent); a refused FramePort key is retried that way once. A Frame that accepts only another key file: Settings → Installing → SSH keys (CLI `frameport frame ssh-keys --add <file>`); passphrase keys go through the SSH agent |
+| Log: `OpenSSH SFTP failed (1): stat C://…/[…: No such file or directory` | sftp got glob escapes inside its quotes (GitHub #324, fixed): `[` in a local folder name | Update FramePort; the native_upload `quote()` passes only `\\` and `\"` escapes, Windows paths with `/` |
+| An install button opens another program (or nothing) instead of FramePort | another program owns the link type, or the switch is off, or macOS (Flet can't receive links there) | Settings → Install links → **Use FramePort for these links**; else Add games → Add from a link… (paste the button's address) |
+| Game page shows another game's description or screenshots, or they stay wrong after Rename (GitHub #377: "Lollipop" matched an adult Steam game) | Store details were looked up by title and kept after a rename; Steam exact-title matches had no content check | Rename/reset drops title-matched details and screenshots and fetches them again under the new name (package-matched details and custom art stay); Steam matches with sexual-content descriptors are rejected for details and artwork |
+
 ## Live view (Live view tab, `install/livestream.py`)
 | Symptom | Cause | Fix |
 |---|---|---|
@@ -278,7 +291,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
  addresses with a full Cpp2IL diffable-cs dump (method `Offset` = address − the r-xp mapping of libil2cpp.so).
  Sample memory per mapping name from `/proc/<pid>/smaps` (`[anon:libc_malloc]` = native heap).
 - Hangs (every thread asleep): first ask for a diagnostics zip saved *while the game hangs*: `target/threads.txt`
-  (agent v79) shows each thread's wait and syscall (futex = a lock, ppoll/recvfrom + an internet socket = network). Then
+  shows each thread's wait and syscall (futex = a lock, ppoll/recvfrom + an internet socket = network). Then
  backtraces of all threads with gdb. Root inside the Lepton container may ptrace the
  game (the host's `ptrace_scope` 1 doesn't apply there) and the guest has `gdbserver64`; `debuggerd -b` fails (no
  tombstoned). Copy every mapped library to a local sysroot (`podman exec <container> cat /proc/<pid>/maps`, then
@@ -297,7 +310,7 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
  libil2cpp.so) — patch the field read in the caller (`Il2cppReturnPatch.field_loads`).
 - Fixes found by users count: a reporter's shader capture (VR4) became the `vk_shader_fix` recipe data (match by size
  + SHA-256, insert words); verify on the device that the log shows the module being fixed.
- Don't install or test on the Frame while the owner is playing: adding a library entry restarts Steam (FramePort
+- Don't install or test on the Frame while someone is playing on it: adding a library entry restarts Steam (FramePort
  now skips the restart when the shortcut is unchanged and waits while a game runs), and a launch test starts a game.
 - Catalog YAML: a `: ` inside an unquoted value breaks the file and the loader skipped it silently (the game vanished
  from the list); `tests/test_catalog_files.py` now catches it.
@@ -308,14 +321,15 @@ Stream PC VR instead: native Steam version if one exists (Espire 1: 669290; HITM
 or the Rift version through Revive (Journey of the Gods, Shadow Point). The catalog stores these as
 `pcvr_alternative`. FramePort handles Rift games itself (next section).

-## Oculus Rift (PC VR) games
-Scan a folder with Rift game dumps (Windows game folders) like Quest dumps; they get ids `rift.<slug>` and the
-"PC VR (Proton and Revive)" patch group. Two ways to run them:
- **This PC** (`--to pc`, GUI "Install on this PC"): a non-Steam shortcut in the local Windows Steam runs
-  `ReviveInjector.exe /openxr "<game.exe>"` (FramePort's portable Revive; on WSL copied to
+## PC VR games (Oculus Rift and SteamVR)
+Scan a folder of Windows game folders like Quest dumps; they get ids `rift.<slug>` and the "PC VR" patch group.
+Repacks are usually pre-patched: by default the game is installed unchanged and its program started directly.
+Revive is only suggested for games with Oculus (LibOVR) code, and those only run on the PC.
+- **This PC** (`--to pc`, GUI "Install on this PC"): a non-Steam shortcut in the local Windows Steam runs the game,
+  or `ReviveInjector.exe "<game.exe>"` with Revive's OpenVR backend (FramePort's portable Revive; on WSL copied to
  `%LOCALAPPDATA%\FramePort`). Play on the Frame by streaming from SteamVR.
- **The Frame** (GUI "Install on Frame"): game + Revive are uploaded to `~/Applications/quest-frame/rift.*`,
-  and launch.sh runs them with the Frame's ARM64 Proton (install it first: Frame page → PC VR games (Proton) → Install…). Experimental.
+- **The Frame** (GUI "Install on Frame", experimental): the game is uploaded to `~/Applications/quest-frame/rift.*`
+  and launch.sh runs it with the Frame's ARM64 Proton (Steam Frame page → PC VR games (Proton) → Install…).

 | Symptom | Cause | Fix |
 |---|---|---|
@@ -323,15 +337,7 @@ Scan a folder with Rift game dumps (Windows game folders) like Quest dumps; they
 | Game quits at once; `ovrPlatformInitialize_NotEntitled` / entitlement failed | Oculus Platform SDK entitlement check (FramePort flags these: "Uses the Oculus Platform SDK") | PC mode with the Oculus app installed and a license you own. FramePort doesn't bypass entitlement checks |
 | `Failed to create process` in ReviveInjector.txt | wrong exe, or 32/64-bit mismatch | check the detected exe on the game page; rescan |
 | `XR_ERROR_RUNTIME_UNAVAILABLE` / no OpenXR runtime (PC) | SteamVR not running / not the OpenXR runtime | start SteamVR, set it as OpenXR runtime; or `pcvr.revive_openvr` |
-| `XR_ERROR_EXTENSION_NOT_PRESENT` / `xrConvertTimespecTimeToTimeKHR failed` (Frame) | ReviveXR needs `XR_KHR_win32_convert_performance_counter_time`; wineopenxr builds it on the host's timespec conversion. The Frame's Linux runtime supports it (2026-09-29), unlike its Android runtime | `pcvr.xr_timefix` (off by default): FramePort's timefix OpenXR layer emulates it like the Quest adapter |
+| `XR_ERROR_EXTENSION_NOT_PRESENT` / `xrConvertTimespecTimeToTimeKHR failed` (Frame) | ReviveXR needs `XR_KHR_win32_convert_performance_counter_time`; wineopenxr builds it on the host's timespec conversion. The Frame's Linux runtime supports it (2026-09-29), unlike its Android runtime | `pcvr.xr_timefix` (default on): FramePort's timefix OpenXR layer emulates it like the Quest adapter |
 | Proton game hangs at start in a headless/SSH launch; log `no driver could be loaded` / `explorer process failed to start` | no display session (DISPLAY/GAMESCOPE_WAYLAND_DISPLAY) | the Proton launch.sh takes them from the running Steam (built in) |
-| Unreal game starts (window created) then `CrashReportClient` runs | the game crashed under Proton; often no VR runtime reached it (Revive off) | keep `pcvr.revive` on (repacks' bundled LibRevive64.dll isn't loaded by itself); read the game log + crash summary in the launch log |
+| Unreal game starts (window created) then `CrashReportClient` runs | the game crashed under Proton; often no VR runtime reached it (Revive off) | LibOVR (Oculus) games need `pcvr.revive` (a repack's bundled LibRevive64.dll isn't loaded by itself) and run only on the PC; otherwise read the game log + crash summary in the launch log |
 | `VK_ERROR_DEVICE_LOST` under DXVK | freedreno GPU hang | `pcvr.proton_log` to capture; PC mode |
-| Game page shows another game's description or screenshots, or they stay wrong after Rename (GitHub #377: "Lollipop" matched an adult Steam game) | Store details were looked up by title and kept after a rename; Steam exact-title matches had no content check | Rename/reset drops title-matched details and screenshots and fetches them again under the new name (package-matched details and custom art stay); Steam matches with sexual-content descriptors are rejected for details and artwork |
-| `Rec.709 color space unavailable`, the game quits before xrCreateSession (GitHub #336, OutRun Quest VR) | The Frame's runtime has no XR_FB_color_space | Adapter setting `fb_color_space=1` (triage `color-space-missing` suggests it): FrameBridge offers the extension (v3), reports Rec.709 and accepts any colour space without converting. Reaches games with their own OpenXR loader; OVRPort's dispatcher can't forward the new functions. Device-unverified |
-| `AppSW recommended buffers unavailable`, the game quits at start with or without XR_FB_space_warp (GitHub #336, OutRun Quest VR) | The game requires Meta's Application SpaceWarp; the Frame's runtime reports no motion-vector size and its GLES swapchains take only sRGB colour formats. `hide_space_warp` can't help (the game refuses to start without the extension) | Adapter setting `space_warp_emul=1` (triage `appsw-required`): FrameBridge offers XR_FB_space_warp, reports a motion-vector size (the runtime's, else eye/4), serves the motion-vector + space-warp depth swapchains as its own GL textures / Vulkan images and strips `XrCompositionLayerSpaceWarpInfoFB` at xrEndFrame. Log `space_warp_emul:`. docs/DEVICE_NOTES.md#xr_fb_space_warp-emulation-336 |
-
-Foveation mode, radius and diagnostic test are per-game user preferences (discussion #365), excluded from
-shared working recipes. Saving Game settings rewrites launcher exports through `set_settings`; changes apply
-at the next game start without rebuilding or reinstalling. Existing builds need one update for dormant diagnostic
-support. Catalog `device.foveation` defaults and the guarded Batman/Climb 2 APK compatibility work remain supported.
@@ -81,7 +81,7 @@ scenes:

 Filmed scenes are one continuous session: each starts where the last one left off. Cards are rendered at the end
 and slotted in, with crossfades between everything. The `fresh` profile starts FramePort as on a new computer: an
-empty library, the welcome screen and a Frame that isn't set up. Its games wait for the pretend folder scan.
+empty library, the welcome screen and a Frame that isn't set up. The demo games wait for the pretend folder scan.

 ## Writing steps

@@ -139,7 +139,7 @@ The `showcase` workflow (`.github/workflows/showcase.yml`):
 1. **When it runs:** on pushes to `main` that touch the UI, its translations or the showcase files, and on
   **Run workflow**.
 2. **What it renders:** the screenshots every time. Videos when their storyboard changed (all of them when the
-   scripts changed), or the ones named on a manual run (`all`, or e.g. `tour install`). UI tweaks alone don't
+   scripts changed), or the ones named on a manual run (`all`, or for example `tour install`). UI tweaks alone don't
   re-commit 10 MB videos.
 3. **What happens next:** every render is uploaded as the run's `showcase` artifact. When a picture changed, the
   workflow opens or updates the pull request on branch `showcase/update`, which you review and merge.
@@ -1,27 +1,24 @@
 # Themes

-FramePort comes with three color themes, all dark:
+FramePort has three color themes, all dark. Switch in **Settings → Appearance**; the change applies at once.

 | Theme | Look |
 |---|---|
-| **Portal** (default) | The logo's two portals: orange for actions and the current selection, blue for secondary actions, progress and the PC side. |
+| **Portal** (default) | The logo's colors: orange for actions and selection, blue for secondary actions, progress and the PC side. |
 | **Portal (OLED)** | Portal on true black, for OLED screens. |
 | **Original** | FramePort's first look, with a violet accent. |

-Switch in **Settings → Appearance**. The change applies at once.
-
 ## Your own theme

-A theme is a small JSON file. To make one:
+A theme is a small JSON file.

-1. In **Settings → Appearance**, pick the theme closest to what you want and click **Copy this theme as a file**.
-2. Paste it into a text editor and save it as `something.json`.
-3. Change the name and the colors you want different. You can delete every color you keep: missing colors come
-   from the `base` theme.
-4. Back in **Settings → Appearance**, click **Install theme file…** and choose the file. FramePort checks it,
-   switches to it and keeps a copy in its data folder (`themes/`), so you can delete the original.
+1. In **Settings → Appearance**, pick the closest theme and click **Copy this theme as a file**.
+2. Paste the theme into a text editor and save the file as `something.json`.
+3. Change the name and the colors you want. Delete the colors you keep: missing ones come from the `base` theme.
+4. Click **Install theme file…** and choose the file. FramePort checks the file, switches to the theme and keeps a
+   copy, so you can delete the original.

-To remove an installed theme, click the bin icon on its card.
+The bin icon on a theme's card removes the theme.

 ### Format

@@ -51,11 +48,10 @@ To remove an installed theme, click the bin icon on its card.
 | `SURFACE`, `SURFACE_2`, `SURFACE_3` | Cards; raised and hovered parts; inputs and chips |
 | `BORDER`, `BORDER_STRONG` | Outlines |
 | `TEXT`, `TEXT_2`, `TEXT_3` | Main text; secondary text; captions and disabled text |
-| `ACCENT`, `ACCENT_SOFT`, `ON_ACCENT` | Main buttons and the current selection; its tint; text on it |
-| `SECONDARY`, `SECONDARY_SOFT` | Secondary buttons, progress, switch tracks; its tint |
+| `ACCENT`, `ACCENT_SOFT`, `ON_ACCENT` | Main buttons and the current selection; the accent's tint; text on the accent |
+| `SECONDARY`, `SECONDARY_SOFT` | Secondary buttons, progress, switch tracks; the secondary color's tint |
 | `OK`, `WARN`, `ERROR`, `INFO` | Status: works, needs attention, failed, information |
 | `PC` | PC VR games and "on this PC" |

-FramePort refuses a theme file it can't show well, and says why: a light window background (FramePort is dark only),
-text that's hard to read on cards, an unknown color name or a value that isn't a color. An example is in
-[`themes/example-theme.json`](themes/example-theme.json).
+FramePort refuses a theme it can't show well and says why: a light background (FramePort is dark only), hard-to-read
+text, an unknown color name or a value that isn't a color. Example: [`themes/example-theme.json`](themes/example-theme.json).
@@ -1,29 +1,32 @@
 # Transfer measurements and incremental installs

+## Current uploader
+
+OpenSSH SFTP is the installer backend for files of 8 MiB and more, with Paramiko as the fallback; smaller files go in
+tar batches. **Parallel uploads** (Settings → Installing) is 3 by default (1–8; saved preferences are kept). The
+sections after "Production OpenSSH follow-up" are the measurements that led there, kept for reference: their
+statements about the "production" uploader describe the state at the time.
+
 ## Production OpenSSH follow-up

-OpenSSH is now the preferred installer backend for files >=8 MiB. The new default is three workers (range 1–8),
-with saved preferences preserved. Fresh files use `put`; existing partial files use `reput`. Each worker keeps
+With the OpenSSH backend, the default became three workers. Fresh files use `put`; existing partial files use `reput`. Each worker keeps
 one SFTP batch session. Progress is polled through a separate bounded SFTP channel. Native failures resume via
 Paramiko; cancellation stops the owned SFTP/SSH process trees and does not trigger fallback.

 Windows matched production comparison: eight 64 MiB files, 512 MiB total, three shuffled repetitions per backend,
 three workers, same home Wi-Fi/internal storage. OpenSSH median **15.51 MB/s**, Paramiko median **11.08 MB/s**
 (about 40% faster). All six checksums passed. OpenSSH trials ranged 9.5–16.8 MB/s, so link variability still
-matters; it was slower than Paramiko in one pass. Native credential/progress setup took 0.12–0.13 seconds.
+matters; OpenSSH was slower than Paramiko in one pass. Native credential/progress setup took 0.12–0.13 seconds.

 The separate Windows 128 MiB production test also passed every checksum. Native cancellation left a partial file
 of 74,752,000 bytes; resuming with OpenSSH produced the expected SHA-256. The log confirmed no fallback for the
-resumed production upload. Reports:
-`/mnt/c/Users/Austin/AppData/Local/Temp/frameport-upload-native-production-comparison-windows.json` and
-`/mnt/c/Users/Austin/AppData/Local/Temp/frameport-upload-native-production-windows.json`.
+resumed production upload.

 The earlier sections below preserve measurements made before the production backend switch.

 The WSL production validation (128 MiB, three workers, three repetitions) measured 14.1 / 19.1 / 15.0 MB/s,
 with every checksum passing and native backend logs recorded. Production cancellation left a 72,330,240-byte
-partial file; OpenSSH resumed it in 4.23 seconds with the expected SHA-256 and no Paramiko fallback. Report:
-`/tmp/frameport-upload-native-production-wsl.json`.
+partial file; OpenSSH resumed it in 4.23 seconds with the expected SHA-256 and no Paramiko fallback.

 ## Measurements (2026-10-14)

@@ -54,7 +57,7 @@ checks application cancellation and both resume paths; native SFTP cancellation

 The Frame's USB and hotspot interfaces were up, but neither direct endpoint was reachable from the PC. No removable
 storage was mounted. USB, hotspot and microSD performance remain **unmeasured** in this round. The Frame's router
-connection used 5 GHz / 80 MHz Wi-Fi, with roughly -56 dBm signal during a read-only probe. This does not reproduce
+connection used 5 GHz / 80 MHz Wi-Fi, with roughly -56 dBm signal during a read-only probe. That setup does not reproduce
 the 6 GHz direct-hotspot setup in [discussion #242](https://github.com/spoopyghosty0/frameport/discussions/242), where
 the reporter measured about 114 MB/s with OpenSSH versus 23 MB/s with Paramiko.

@@ -72,7 +75,7 @@ uses independent Paramiko connections.
 The later comparison tested both backends sequentially on Windows and WSL, with three shuffled repetitions of
 the same eight 16 MiB files per worker count. Native `sftp-files-N` balances files across N persistent OpenSSH
 SFTP batch processes. Setup and completion are included; checksum verification is excluded. All 60 transfers
-passed SHA-256 checks. This is benchmark code; the production uploader still uses Paramiko.
+passed SHA-256 checks. `sftp-files-N` is benchmark code; the production uploader still uses Paramiko.

 | Workers | Windows Paramiko MB/s | Windows OpenSSH MB/s | WSL Paramiko MB/s | WSL OpenSSH MB/s |
 |---|---:|---:|---:|---:|
@@ -87,10 +90,7 @@ by 6.5% on Windows and 22.8% on WSL. Eight was faster on Windows but slower on W
 default remains two because three regressed by 16.1% on Windows and 5.3% on WSL in this matched comparison.
 Link variability remains substantial, and no fast hotspot/USB result is claimed.

-Reports: `/mnt/c/Users/Austin/AppData/Local/Temp/frameport-upload-native-parallel-windows.json` and
-`/tmp/frameport-upload-native-parallel-wsl.json`.
-
-Settings → Installing → **Parallel uploads** accepts **1–8**, default **2**. It controls large files within one
+Settings → Installing → **Parallel uploads** accepts **1–8** (default 2 at the time, 3 now). The setting controls large files within one
 install; the FIFO still runs one install job at a time. A single APK is not split into chunks. Large files are
 scheduled largest first, with at most one authenticated SSH connection per active worker and never more workers
 than files. Small files still use tar batches after the large-file uploads. Choose 1 on a busy network; a higher
@@ -112,7 +112,7 @@ closes only its worker transports; completed files and interrupted `.part` files
 On Windows, the production uploader improved from 5.6 to 10.9 MB/s with 2 workers (**1.95 times faster**), and
 17.3 MB/s with 8 (**3.08 times faster**). All twelve Windows production transfers passed SHA-256 verification.
 The preceding Windows prototype also tested 3 workers (12.2 MB/s median), before aggregate progress/cancellation
-were integrated; that is not included as a production measurement in the table.
+were integrated; that result is not included as a production measurement in the table.

 WSL was noisy: four workers improved its median by about 29%, but 2 did not improve its median, and 3 was slower.
 There is no evidence that a particular worker count is universally fastest. The option is retained because it
@@ -124,7 +124,8 @@ environment. Production code, including cleanup and progress checks, was used fo
 uv run python scripts/upload_bench.py --mib 128 --repeat 3 --methods app-files-1,app-files-2,app-files-3,app-files-4,app-files-8 --json parallel.json
 ```

-`install.upload_threads` persists the setting. Malformed values use 2 and numeric values are clamped to 1–8.
+`install.upload_threads` persists the setting. Malformed values use the default and numeric values are clamped to
+1–8.
 The serial setting reuses the existing control connection; parallel workers verify that the new transport reaches
 the same paired headset before sending any files.

@@ -145,7 +146,7 @@ other network traffic. A 512 MiB payload is preferred for follow-up tests on fas
 above used 128 MiB.

 The script creates a unique scratch directory on the selected filesystem, checks content outside the timed upload,
-and removes its own temporary remote files and temporary key copy. It never modifies the pairing key's ACL. Windows
+and removes its own temporary remote files and temporary key copy. The script never modifies the pairing key's ACL. Windows
 OpenSSH rejects an `OWNER RIGHTS` ACL entry; the temporary copy grants only the current user, without Python's
 Windows `chmod` behaviour that can introduce that entry. Native clients use the application's key and known-hosts
 file with strict host verification.
@@ -169,7 +170,7 @@ when the user customized their recipe.
  data manifest/digest and artwork hashes. Routine device samples carry only the digest, and updates fetch a
  detailed manifest only when necessary. Live numeric settings writes update only the applied runtime configuration,
  leaving APK build identity intact. Desired data manifests are cached locally for badges, without render-path I/O.
- Runtime-only updates use agent v87 `configure`: no conversion, signing, APK transfer, artwork, Steam restart or
+- Runtime-only updates use the agent's `configure`: no conversion, signing, APK transfer, artwork, Steam restart or
  automatic launch test. They still require the installed APK identity and an available destination, and refuse
  changes while the game is running. Defaults explicitly reset overrides embedded in an older APK. Generated
  configuration files are restored or removed only when they still match FramePort's last write; user edits survive.
@@ -188,7 +189,7 @@ when the user customized their recipe.
  safely. Converted-copy cleanup and `build.keep_copies` remain in effect; a configuration/data update does not
  require the deleted converted APK.

-Install results record `stage_seconds` in the library's install history. This includes planning, conversion,
+Install results record `stage_seconds` in the library's install history. The timings include planning, conversion,
 validation, transfer and finalization stages reached by that operation; the GUI's subsequent optional launch test
 is separate. Use these timings to distinguish build cost, network transfer and device/Steam work when reviewing a
 slow install. Configuration success is recorded after writing the configuration and completing its sync; a failed
@@ -48,9 +48,9 @@ for (const [id, from] of [['tour', 18], ['install', 28]]) {
 copy(join(repo, 'bootstrap/setup.sh'), join(site, 'public/s'));
 copy(join(repo, 'bootstrap/setup.sh'), join(site, 'public/setup.sh'));

-// every image the docs pages show (docs/images → media/docs)
+// every image the docs pages show (docs/images → media/docs, subfolders such as controllers/ included)
 let docImages = 0;
-for (const name of readdirSync(join(repo, 'docs/images'))) {
+for (const name of readdirSync(join(repo, 'docs/images'), { recursive: true })) {
  if (!/\.(png|jpe?g|webp|gif|svg)$/i.test(name)) continue;
  copy(join(repo, 'docs/images', name), join(site, 'public/media/docs', name));
  docImages++;
@@ -32,7 +32,7 @@ const shots = [
 ];
 const videos = [
  { id: 'tour', title: 'The tour', text: 'Library, install, play, monitor · about 90 s' },
-  { id: 'install', title: 'The install tutorial', text: 'From the download to the first game · about 80 s' },
+  { id: 'install', title: 'The install tutorial', text: 'From the download to the first game · about 90 s' },
 ];
 ---
 <section class="section tour" id="tour">
@@ -12,8 +12,8 @@ const LABEL = { yes: 'Yes', no: 'No', part: 'Partly', unknown: 'Not stated' } as
    <div class="head reveal">
      <p class="label">Compare the tools</p>
      <h2>FramePort patches the games that don't run as they are</h2>
-      <p class="lead">Other tools install an app unchanged. FramePort also converts and patches it, and it's free and
-        open source (GPL-3.0).</p>
+      <p class="lead">Other tools install an app unchanged. FramePort also converts and patches the app, and FramePort is
+        free and open source (GPL-3.0).</p>
    </div>

    <div class="cmp" data-cmp data-with="1">
@@ -60,7 +60,7 @@ const latest = latestCheck(games);
          <span role="columnheader" class="c-date">Checked</span>
        </div>
        <ul class="rows" role="rowgroup" data-rows set:html={rowsHtml(games, patchHref)} />
-        <p class="empty" data-empty hidden>No tested game matches. It may still work: FramePort suggests patches.</p>
+        <p class="empty" data-empty hidden>No tested game matches. The game may still work: FramePort suggests patches.</p>
      </div>
      <div class="board-foot">
        <button type="button" class="btn btn-ghost btn-small" data-more>Show all {games.length} games</button>
@@ -11,8 +11,8 @@ const { games } = Astro.props;
    <div class="copy">
      <h1>Your <span class="q">VR games</span>, on the <span class="f">Steam Frame</span></h1>
      <p class="lead">
-        FramePort puts Quest games, PC VR games and Android apps on the Steam Frame and in your Steam library. Connect the
-        Frame once; then it's one click per game.
+        FramePort puts Quest games, PC VR games, Android apps and Linux apps on the Steam Frame and in your Steam
+        library. Connect the Frame once; then each game is one click.
      </p>
      <div class="ctas">
        <a class="btn btn-primary" href={downloadPage()} data-download>
@@ -14,7 +14,7 @@ const steps = [
  { side: 'pc', where: 'On your PC', title: 'Start setup' },
  { side: 'fr', where: 'On the Frame, once', title: 'Run the setup line' },
  { side: 'pc', where: 'On your PC', title: 'Allow it' },
-  { side: 'fr', where: 'On the Frame, by itself', title: 'It sets itself up' },
+  { side: 'fr', where: 'On the Frame, by itself', title: 'The Frame sets itself up' },
  { side: 'fr', where: 'Every game', title: 'Add games, play' },
 ];
 ---
@@ -34,7 +34,8 @@ const steps = [
      <div class="txt">
        <p class="ey pc">Step 1 · On your PC</p>
        <h3>Download FramePort</h3>
-        <p>Windows, macOS or Linux. Unpack it anywhere and start it. No installer; it updates itself.</p>
+        <p>Windows, macOS or Linux. Unpack the download anywhere and start FramePort. No installer; FramePort updates
+            itself.</p>
        <div class="dls">
          {DOWNLOADS.map((d) => (
            <a class="dl" href={downloadPage(d.os)} data-os={d.os} data-first={FIRST[d.os]} data-asset={d.asset} data-run={RUN[d.os]}>
@@ -90,7 +91,7 @@ const steps = [
          <p>Open Konsole: SteamVR dashboard → <b>Launch a program → Desktop</b>, then app menu → <b>System → Konsole</b>.
            Run this line:</p>
          <div class="cmd"><code><span class="prompt">$</span>{LINE}</code><button type="button" class="btn btn-ghost btn-small" data-copy-line={LINE}>Copy</button></div>
-          <p class="calm">It finds FramePort on your PC and waits: nothing changes on the Frame until you click
+          <p class="calm">The setup line finds FramePort on your PC and waits: nothing changes on the Frame until you click
            <b>Allow</b>. Then it turns on Developer Mode. No password, no root. <a href={url('setup.sh')}>Read the script</a></p>
          <p class="small">No keyboard? Open <a href={url('setup/')}>the setup page</a> in Chromium on the Frame (Steam's
            <b>+</b> on the taskbar installs it) and copy the line.</p>
@@ -116,7 +117,7 @@ const steps = [
    <section class="pane" data-pane="3" role="tabpanel" hidden>
      <div class="txt">
        <p class="ey pc">Step 4 · On your PC</p>
-        <h3>Allow it when the codes match</h3>
+        <h3>Allow the Frame when the codes match</h3>
        <p>Konsole and FramePort show the same 4 digits. Click <b>Allow</b>. Nothing changes on the Frame before
          that.</p>
        <p class="small">Try it: the Frame here shows <b data-digits-txt>4831</b>.</p>
@@ -159,7 +160,7 @@ const steps = [
        <p class="ey fr">Step 6 · Every game</p>
        <h3>Add games, install, play</h3>
        <p><b>Add games → Scan a folder…</b>, pick a game, click <b>Install on Frame</b>. It shows up in the Frame's
-          Steam library. Play it from FramePort or in the headset.</p>
+          Steam library. Play the game from FramePort or in the headset.</p>
        <a class="video" href={url('media/frameport-install.mp4')}>
          <video muted loop playsinline preload="none" poster={url('media/frameport-install.jpg')} data-preview={url('media/preview-install.mp4')} width="1280" height="720" aria-hidden="true"></video>
          <span>▶ Watch the video</span>
@@ -6,8 +6,8 @@
    <span class="mark" aria-hidden="true">!</span>
    <p><strong>Notice:</strong> FramePort doesn't download, share or unlock games. Use games you got legally, for example from
      <a href="https://sidequestvr.com/">SideQuest</a>. FramePort downloads published open-source tools (see
-      <a href="#credits">Built on</a>) and adds its own patches so games run on the Frame.</p>
-    <p class="poc">Not every game runs on the Frame: recipes are tested by the community, and some games need Meta's services or hardware the Frame lacks.</p>
+      <a href="#credits">Built on</a>) and adds its own patches.</p>
+    <p class="poc">Not every game runs on the Frame. Some need Meta's services or hardware the Frame lacks.</p>
  </div>
 </aside>

@@ -6,7 +6,7 @@ import { REPO, url } from '../data/site';

 type Step = { glyph: Parameters<typeof Glyph>[0]['name']; side: 'pc' | 'frame'; name: string; text: string };
 const onFrame: Step[] = [
-  { glyph: 'pc', side: 'pc', name: 'scan', text: 'One folder per game. FramePort finds the program that starts it and asks when there are several.' },
+  { glyph: 'pc', side: 'pc', name: 'scan', text: 'One folder per game. FramePort finds the program that starts the game and asks when there are several.' },
  { glyph: 'container', side: 'pc', name: 'analyze', text: 'Reads which VR interface the game uses (OpenXR, OpenVR or Oculus) from its files.' },
  { glyph: 'sync', side: 'frame', name: 'upload', text: 'The game goes to the Frame unchanged. Proton, Valve’s layer for Windows games, is installed for you.' },
  { glyph: 'patch', side: 'frame', name: 'patch', text: 'A small OpenXR layer lets the game talk to the Frame’s SteamVR. Unreal games start without their crash reporter.' },
@@ -31,8 +31,8 @@ const onPc: Step[] = [
          <li class={s.side}><span class="g"><Glyph name={s.glyph} size={18} /></span><code class="n">{s.name}</code><p>{s.text}</p></li>
        ))}
      </ol>
-      <p class="note muted">Games that use OpenXR or OpenVR run directly. Oculus-only games run on your PC; running them on the Frame
-        is the experimental path below. <a href={url('docs/install/#pc-vr-games')}>PC VR in the docs</a></p>
+      <p class="note muted">Games that use OpenXR or OpenVR run directly. Oculus-only games run on your PC; the experimental
+        path below runs them on the Frame. <a href={url('docs/install/#pc-vr-games')}>PC VR in the docs</a></p>
    </details>

    <details class="panel">
@@ -42,7 +42,7 @@ const onPc: Step[] = [
          <li class={s.side}><span class="g"><Glyph name={s.glyph} size={18} /></span><code class="n">{s.name}</code><p>{s.text}</p></li>
        ))}
      </ol>
-      <p class="note muted">Needs Windows with Steam and SteamVR. Games that check their license through Meta’s app need that
+      <p class="note muted">Needs Windows with Steam and SteamVR. Games that check their license through Meta’s app need Meta’s
        app on the PC too. <a href={url('docs/install/#pc-vr-games')}>PC VR in the docs</a></p>
    </details>

@@ -17,7 +17,7 @@ export const HEADLINES: Headline[] = [
    frameport: 'GPL-3.0. Read it, build it, change it, share it.',
    others: ['Free (donationware). Source not published.', 'Free, from Valve.'] },
  { icon: 'game', title: "Quest games that don't run as they are",
-    frameport: 'Patches them for the Frame, with a tested recipe for 120+ games.',
+    frameport: 'Patches them for the Frame, with tested recipes for hundreds of games.',
    others: ['Installs the APK as it is.', 'Installs the APK as it is.'] },
  { icon: 'pc', title: 'Your PC',
    frameport: 'Windows, macOS and Linux.',
@@ -45,7 +45,7 @@ export const ROWS: Row[] = [
    y('Converted and patched for the Frame'),
    n('Installs the APK as it is'),
    n('Installs the APK as it is')] },
-  { label: 'Does it know which patches a game needs?', cells: [y('A tested recipe for 120+ games, updated without an app update'), u(), n('No')] },
+  { label: 'Does it know which patches a game needs?', cells: [y('Tested recipes for hundreds of games, updated without an app update'), u(), n('No')] },
  { label: 'Will the game be in my Steam library?', cells: [
    y('Yes, with artwork and tags'), p('As a "Devkit Game" shortcut'), p('As "Devkit Game: <title>"; not with adb')] },
  { label: 'Android apps, Linux apps, Windows programs?', cells: [
@@ -21,6 +21,8 @@ export const DOCS: DocInfo[] = [
    summary: "Common questions about FramePort: how to lay out game folders with APK and OBB files, where a game's settings are, and how to fix games that don't start, hang, look wrong or stutter." },
  { file: 'COMPATIBILITY.md', slug: 'compatibility', name: 'Compatibility', group: 'Using FramePort', blurb: 'What runs on the Frame.',
    summary: 'Which Quest games, PC VR games and Android apps run on the Steam Frame with FramePort, and how to share a recipe that works.' },
+  { file: 'CONTROLLERS.md', slug: 'controllers', name: 'Controller buttons', group: 'Using FramePort', blurb: 'Quest buttons on the Frame’s controllers.',
+    summary: "How Quest games' controller buttons map to the Steam Frame's controllers, and the Mirror and Quest pair modes in Game settings." },
  { file: 'THEMES.md', slug: 'themes', name: 'Themes', group: 'Using FramePort', blurb: 'Color themes and making your own.',
    summary: "FramePort's dark color themes (Portal, Portal OLED, Original) and how to make and share your own theme file." },
  { file: 'INSTALL_BUTTON.md', slug: 'install-button', name: 'Install button', group: 'For developers', blurb: 'An install button for your download page.',
@@ -12,7 +12,7 @@ const groups = [...new Set(docs.map((d) => d.group))];
 // what people come for → the pages to read, in order (docs-ui.ts lights them up)
 const paths = [
  { key: 'first', label: 'Get my first game running', say: 'From the download to playing, in this order:', docs: ['install', 'frame-setup', 'compatibility', 'faq'] },
-  { key: 'broken', label: "A game won't start or looks wrong", say: 'Check whether it can run, then look up the symptom or report it:', docs: ['compatibility', 'diagnostics', 'playbook', 'frame-runtime'] },
+  { key: 'broken', label: "A game won't start or looks wrong", say: 'Look up the symptom, check whether the game can run, then report the problem:', docs: ['faq', 'compatibility', 'controllers', 'diagnostics', 'playbook'] },
  { key: 'button', label: 'Add an install button to my site', say: 'The button, then what your players will see:', docs: ['install-button', 'install'] },
  { key: 'how', label: 'Understand how it works', say: 'The big picture first, then the details:', docs: ['architecture', 'frame-runtime', 'playbook'] },
  { key: 'look', label: 'Make it look my way', say: 'Color themes and how to share your own:', docs: ['themes'] },
@@ -59,14 +59,14 @@ const builds = DOWNLOADS.map((d) => ({ os: d.os, label: d.label, detail: d.detai
        <span class="sha" data-sha-wrap hidden>SHA-256 <code data-sha></code><button type="button" data-copysha>Copy</button></span>
        <a href={RELEASES}>Release notes</a>
      </p>
-      <p class="trust">Windows and macOS warn the first time you open FramePort: it's signed by its developer, not with a
-        paid certificate. Each release lists every file's SHA-256 in SHA256SUMS.txt to check it.</p>
+      <p class="trust">Windows and macOS warn the first time you open FramePort: FramePort is signed by its developer, not
+        with a paid certificate. Each release lists every file's SHA-256 in SHA256SUMS.txt.</p>
    </section>

    <section class="wrap next" aria-labelledby="next-h">
      <h2 id="next-h">Then</h2>
      <ol>
-        <li><span class="n">1</span><div><h3>Unpack it</h3><p>Anywhere you like. No admin rights needed.</p></div></li>
+        <li><span class="n">1</span><div><h3>Unpack the download</h3><p>Anywhere you like. No admin rights needed.</p></div></li>
        <li><span class="n">2</span><div><h3>Start FramePort</h3><p data-first>Open FramePort. The first start downloads its tools (about a minute).</p></div></li>
        <li><span class="n">3</span><div><h3>Connect your Steam Frame</h3><p>Run one line on the Frame, then click Allow on your PC. <a href={url('setup/')}>Setup</a></p></div></li>
      </ol>
@@ -37,11 +37,11 @@ const logGames = games.filter((g) => g.status !== 'unsupported' && g.platform ==
 ---
 <Layout
  title="FramePort · Quest and PC VR games on the Steam Frame"
-  description="FramePort puts Quest games, PC VR games and Android apps on the Steam Frame and in your Steam library. Free and open source."
+  description="FramePort puts Quest games, PC VR games, Android apps and Linux apps on the Steam Frame and in your Steam library. Free and open source."
  data={[
    { '@type': 'WebSite', name: 'FramePort', url: Astro.site!.href },
    { '@type': 'SoftwareApplication', name: 'FramePort', url: Astro.site!.href,
-      description: 'Installs Meta Quest games, PC VR games and Android apps on the Valve Steam Frame, patched to run there.',
+      description: 'Installs Meta Quest games, PC VR games, Android apps and Linux apps on the Valve Steam Frame, patched to run there.',
      applicationCategory: 'GameApplication', operatingSystem: 'Windows, macOS, Linux',
      offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' },
      license: 'https://www.gnu.org/licenses/gpl-3.0.html', isAccessibleForFree: true,
@@ -40,8 +40,8 @@ import { DOWNLOADS, downloadPage, url } from '../../data/site';

      <section class="status" data-when="fallback">
        <h2>FramePort didn't open?</h2>
-        <p class="muted">It may not be on this PC yet. FramePort is free and installs games on a Steam Frame from your
-          PC.</p>
+        <p class="muted">FramePort may not be on this PC yet. FramePort is free and installs games on a Steam Frame from
+          your PC.</p>

        <ol class="steps">
          <li>
@@ -52,8 +52,8 @@ import { DOWNLOADS, downloadPage, url } from '../../data/site';
                <a class="btn btn-primary" href={downloadPage()} data-download><Glyph name="frame-solid" size={18} /><span data-download-label>Download FramePort</span></a>
                {DOWNLOADS.map((d) => <a class="other" href={downloadPage(d.os)} data-os={d.os}>{d.label}</a>)}
              </div>
-              <p class="muted small">Unpack it and start FramePort. It shows how to <a href={url('setup/')}>set up
-                your Frame</a>.</p>
+              <p class="muted small">Unpack the download and start FramePort. FramePort shows how to <a href={url('setup/')}>set
+                up your Frame</a>.</p>
            </div>
          </li>
          <li>
@@ -45,7 +45,7 @@ const line = 'curl -fsSL https://frameport.app/s | bash';
        <li class="st ok">
          <span class="n">3</span>
          <div>
-            <h2>Allow it on the PC</h2>
+            <h2>Allow the Frame on the PC</h2>
            <p>When Konsole and FramePort show the same 4 digits, click <b>Allow</b>. Steam restarts once and
              FramePort connects within a minute.</p>
          </div>
@@ -58,12 +58,12 @@ const line = 'curl -fsSL https://frameport.app/s | bash';
      </section>

      <section class="what">
-        <h2>What it changes on the Frame</h2>
+        <h2>What the setup changes on the Frame</h2>
        <ul>
          <li>Nothing until you click <b>Allow</b> on the PC.</li>
-          <li>Then it lets FramePort connect, turns on Developer Mode and asks Steam to install Lepton (Valve's Android
-            app support).</li>
-          <li><a href={url('docs/frame-setup/')}>What it changes and how to undo it</a> · <a href={url('setup.sh')}>Read the
+          <li>Then the setup lets FramePort connect, turns on Developer Mode and asks Steam to install Lepton (Valve's
+            Android app support).</li>
+          <li><a href={url('docs/frame-setup/')}>What the setup changes and how to undo it</a> · <a href={url('setup.sh')}>Read the
            script</a></li>
        </ul>
      </section>
@@ -76,10 +76,10 @@ const line = 'curl -fsSL https://frameport.app/s | bash';
          <div><h3>USB cable</h3><p>Turn on Developer Mode (Steam button → Settings → System), plug the Frame into your
            PC and click <b>Set up with a USB cable</b>.</p></div>
          <div><h3>Pair new host</h3><p>With Developer Mode on, open Settings → Developer → <b>Pair new host</b> on the
-            Frame. In FramePort, click <b>Connect</b> next to it under <b>Already set up</b>, then approve it in the
-            headset.</p></div>
-          <div><h3>Address and password</h3><p>Know the Frame's address and desktop password? Use <b>Enter the
-            address</b>.</p></div>
+            Frame. FramePort asks to connect (or click <b>Connect</b> next to the Frame under <b>Already set up?</b>);
+            approve the request in the headset.</p></div>
+          <div><h3>Address and password</h3><p>Know the Frame's address and desktop password? Use <b>Connect by
+            address…</b>.</p></div>
        </div>
      </section>
    </div>
@@ -593,7 +593,7 @@ export function initMock(root: HTMLElement, games: MockGame[], opts: MockOptions
      dialog(`<h4>Set up your Steam Frame</h4>`
        + `<p>On the Frame, open the SteamVR dashboard → <b>Launch a program → Desktop</b>, then app menu → <b>System → Konsole</b>, and run:</p>`
        + `<div class="cmdl"><code>curl -fsSL https://frameport.app/s | bash</code></div>`
-        + `<p class="small">It finds this PC ("amber-otter") and asks. You allow it here.</p>`
+        + `<p class="small">The setup line finds this PC ("amber-otter") and asks. You allow the Frame here.</p>`
        + `<div data-ask></div><ul class="progress" data-prog></ul>`
        + `<div class="row"><button class="btn-p" data-act="ran">I ran it on the Frame</button><button class="btn-s" data-act="close">Close</button></div>`);
      emit('command');
@@ -876,7 +876,7 @@ export function initMock(root: HTMLElement, games: MockGame[], opts: MockOptions
      target: '[data-sidebar] [data-route="frame"]', wait: 'route:frame' },
    { title: 'Set up the Frame', text: 'Pick <b>Wi-Fi</b> or <b>USB cable</b>, then <b>Start setup</b>.',
      target: '[data-act="show-command"]', wait: 'command' },
-    { title: 'Run it, allow it', text: 'Run the line in Konsole on the Frame. Click the button, then <b>Allow</b> when the codes match.',
+    { title: 'Run the line, allow the Frame', text: 'Run the line in Konsole on the Frame. Click the button, then <b>Allow</b> when the codes match.',
      target: '.dlg', wait: 'connected' },
    { title: 'Connected', text: 'The Frame card shows the battery and what is playing.',
      target: '[data-framecard]', next: 'Next' },
@@ -887,7 +887,7 @@ export function initMock(root: HTMLElement, games: MockGame[], opts: MockOptions
      target: '.grid .card', wait: 'route:game' },
    { title: 'One click', text: 'Click <b>Install on Frame</b> and watch the activity card.',
      target: '[data-act="install"]', wait: 'installed' },
-    { title: 'Play', text: "It's in the Frame's Steam library now. Play it from here or in the headset.",
+    { title: 'Play', text: "The game is in the Frame's Steam library now. Play the game from here or in the headset.",
      target: '[data-act="play"]', wait: 'played' },
    { title: "That's it", text: 'Now try Monitor, Room, Live view, Screenshots, Files, Type on Frame and Settings.',
      place: 'center', next: 'Explore' },
Author	SHA1	Message	Date
spoopyghosty0	4fd95635d6	Site: current app and docs; Controller buttons page; clearer wording - Home, meta descriptions: Linux apps alongside Quest, PC VR and Android; shorter notice, matching the README. - Setup page: the app's labels ('Already set up?', 'Connect by address…'); Pair new host asks by itself. - Tour: the install video is about 90 s. - Docs: CONTROLLERS.md is a site page now, and the image sync copies docs/images subfolders (its diagram lives in controllers/); the 'game won't start' path starts with the FAQ. - 'it'/'this'/'that' replaced by the noun where the referent was unclear (walkthrough, setup, download, install pages, compare, PC VR panel, demo app).	2026-10-24 23:35:53 -04:00
spoopyghosty0	8d2cb30da8	Docs: name the thing instead of 'it', 'this' or 'that' where the referent was unclear Every page this branch touches: sentences that started with 'It'/'This'/'That' after naming two things, and short answers ('report it', 'click it'), now say what they mean. Two FAQ headings start with 'The game' (no page links to them).	2026-10-24 23:35:52 -04:00
spoopyghosty0	d16ff4e53f	Docs: themes, install button, controller buttons, diagnostics, contributing: tighter wording Diagnostics starts with what a user sends and moves the maintainer workflow into one paragraph; contributing folds the tested-game section into the quick contributions.	2026-10-24 23:35:52 -04:00
spoopyghosty0	c5014bf249	Docs: install guide and FAQ: shorter, one idea per sentence Same instructions in fewer words: setup alternatives as a list, moving from a PC in three short steps, room editing as numbered steps, save backups once in the FAQ. The FAQ's 32-bit answer was outdated: the 32-bit bridge is suggested for such games now.	2026-10-24 23:35:51 -04:00
spoopyghosty0	ce155af69d	Docs: README and compatibility: no game count, shorter text 'Hundreds of games' instead of a number that goes stale (README, COMPATIBILITY, the site's comparison). Shorter notice, features, quick start and comparison bullets; one-line docs index rows.	2026-10-24 23:35:51 -04:00
spoopyghosty0	173137ed33	Docs: architecture: triage signatures now update from GitHub main too	2026-10-24 23:35:50 -04:00
spoopyghosty0	370d3ae247	Docs: third-party notices list Cpp2IL and APKEditor, which FramePort downloads on first use	2026-10-24 23:35:50 -04:00
spoopyghosty0	e8b746ec9a	Docs: transfer benchmark: remove local report paths, say what the uploader does today The page named report files under a personal Windows home folder; the measurements stay, the paths go. A short current-state section (OpenSSH SFTP for big files, 3 parallel uploads) heads the page, so the older 'production still uses Paramiko, default 2' statements read as history.	2026-10-24 23:35:50 -04:00
spoopyghosty0	2f617d708a	Docs: runtime reference: version-neutral title, current Revive-under-Proton facts, no agent versions The title pinned SteamOS 0.3.0 although sections cover up to 0.5.x; PC VR under Proton isn't 'unverified' any more, and Revive's hooks don't work there (the old line said they did). sshd comes with Developer Mode and FramePort's key, no password. The headset-view webcam does show games. Foveation preferences moved next to the other foveation notes (they sat under Monitoring sources), the scan preview below the room overview. Room tab paths.	2026-10-24 23:35:49 -04:00
spoopyghosty0	cf9da9a6d0	Docs: playbook: fix the broken first table, current PC VR model, one section for FramePort's own problems The startup table had a row above its header separator (it rendered as plain text). PC VR games are installed unchanged by default, Revive only for LibOVR games; the two duplicate -3001 rows are one now. Upload/SSH, install link and store-detail rows moved out of the startup and PC VR tables into their own section, the OutRun rows into the startup table. No agent version numbers; room scanning in the headset exists now; Add from a link.	2026-10-24 23:35:49 -04:00
spoopyghosty0	fdd3df2714	Docs: contributor pages: current menu labels, PC VR runs as-is by default, Linux apps, no agent versions CONTRIBUTING: Share working recipe / Report a problem under their menu groups, Language lives in Appearance, patch_docs and showcase pointers. ARCHITECTURE: bundles and backups as sources, session triage, remote catalog, PC VR games installed unchanged with Revive only for LibOVR games, a Linux apps section. FRAME_SETUP: menu entries, services and FEX that FramePort adds later. DIAGNOSTICS: no agent version numbers. 'for example' instead of e.g.	2026-10-24 23:35:48 -04:00
spoopyghosty0	9ef2c952b0	Docs: install guide and FAQ follow the new game menu, settings and save backups INSTALL: menu paths through the game menu's groups, one section on when games appear in Steam (was buried under running FramePort on the Frame), save backup folder/automatic snapshots, shorter overlay and first-launch notes, rename/session/settings commands. FAQ: foveation lives in Game settings now, Exit game pauses games first, save backups as a short list, controller buttons.	2026-10-24 23:35:48 -04:00
spoopyghosty0	404beb7786	Docs: README and compatibility pages: current game count, full docs index, Linux apps; regenerate the tested-games list	2026-10-24 23:35:48 -04:00