Docs: user guides in docs/ and a new front-page README

Getting started, headset setup, installing and using Frame Home, the .fenv format and fenv-tool, performance, building, troubleshooting, and an index. Stubs for the Studio guide and bundles. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 20:03:07 +01:00 · 2026-10-21 12:21:28 -05:00
1 parent 87cae3d7e1
commit 96ef8a0a26
@@ -1,63 +1,100 @@
 # Frame Studio and Frame Home

-**Frame Home** makes your homes the Steam Frame's environment: Meta Quest homes (HSL, Clay `.opa`, glTF) and models,
-converted into Frame-native `.fenv` environments and drawn in SteamVR's compositor in place of its own.
+**Frame Home** makes your homes the Steam Frame's environment. Meta Quest homes (HSL, Clay `.opa`, glTF) and models
+become Frame-native `.fenv` environments, drawn in SteamVR's compositor in place of its own environment: at boot,
+behind the Steam menu and while games load. **Frame Studio** is the desktop editor for them, on Windows, Linux and
+macOS. It opens Meta homes, `.fenv` environments and models (glTF, FBX, OBJ), shows them with the same renderer the
+headset runs, and lets you edit, save and send them to the headset.

-**Frame Studio** is the desktop editor for them. It opens Meta homes, `.fenv` environments and models (glTF, FBX,
-OBJ), shows them with the same renderer the headset runs, and lets you move, hide and delete objects, shape the walkable
-area, add sounds and pictures, save environments and install them on the headset.
+## Quick start
+
+1. **Download** Frame Studio for your computer from the Releases page (**Latest build**, or a version release) and
+   unpack it. See [Getting started](docs/getting-started.md).
+2. **Prepare the headset** once: developer mode, SSH and a key. See [Preparing the Steam Frame](docs/headset-setup.md).
+3. **Install Frame Home**: in Studio, **Frame > Install on Steam Frame...**, then **Install**.
+   See [Installing Frame Home](docs/install-frame-home.md).
+4. **Open a home**: **File > Open Home...** and pick a Meta home `.apk`, a `.fenv` or a model.
+5. **Send it**: **Frame > Send to Frame**. Put the headset on: you are standing in it.

 ## Downloads

-Every push builds everything (Actions → the run → Artifacts). The newest build of `main` is always on the Releases
-page as **Latest build**; tagged versions (`git tag v1.0 && git push --tags`) get their own release.
+Every push builds everything. The newest build of `main` is always on the Releases page as **Latest build**; tagged
+versions (`v1.0`, ...) get their own release. Builds of other branches are under Actions (open a run, then
+Artifacts).

 | Computer | Frame Studio |
 |---|---|
 | Windows, 64-bit PCs | `FrameStudio-windows-x64.zip` |
 | Windows, 32-bit | `FrameStudio-windows-x86.zip` |
-| Windows on ARM (Snapdragon, Surface Pro X…) | `FrameStudio-windows-arm64.zip` |
+| Windows on ARM (Snapdragon, Surface Pro X...) | `FrameStudio-windows-arm64.zip` |
 | Linux, 64-bit PCs | `FrameStudio-linux-x64.tar.gz` |
 | Linux, 32-bit | `FrameStudio-linux-x86.tar.gz` |
 | Linux on ARM (Raspberry Pi 5, ARM laptops, the Steam Frame's desktop) | `FrameStudio-linux-arm64.tar.gz` |
 | Mac with Apple Silicon (M1 and later) | `FrameStudio-macos-arm64.zip` |
 | Mac with Intel | `FrameStudio-macos-x64.zip` |
+| Frame Home only, installed from any computer | `FrameHome-installer.zip` |

-Studio needs a GPU with Vulkan 1.2: any recent NVIDIA, AMD or Intel driver on Windows and Linux; on a Mac, Vulkan runs
-on Metal through MoltenVK, which comes inside the app. The 32-bit builds have at most 4 GB to work in: the very
-largest homes may not fit.
+Studio needs a GPU with Vulkan 1.2: any recent NVIDIA, AMD or Intel driver on Windows and Linux. On a Mac, Vulkan
+runs on Metal through MoltenVK, which comes inside the app. The 32-bit builds have at most 4 GB to work in, so the
+very largest homes may not fit.

-**Frame Home without Studio:** `FrameHome-installer.zip` installs it on the headset from any computer (or on the
-headset itself); see `frame/README-frame-home.txt` inside it.
+## Highlights

-## Building
+**Frame Home (on the headset)**

-Everything Studio needs is in `third_party/` (Vulkan is loaded at runtime). CMake 3.16+ and Ninja.
+- Takes SteamVR's environment slot natively: no app, no library entry, controllers and passthrough still work.
+- An **Environments** panel in the Steam menu: switch homes live, delete them, change settings, debug views.
+- Walk, teleport, snap or smooth turn, sit in seats, gravity zones, comfort vignette.
+- Built for 120 fps: baked environments, eye-tracked foveation, auto resolution, per-world tuned settings, and a
+  thermal governor that keeps the headset cool.
+- Safe: a compositor layer that steps aside if Frame Home stops, and a one-file off switch.

-| On | Command | Builds |
-|---|---|---|
-| Windows (Visual Studio 2022 with C++) | `studio\build_windows.bat x64` (or `x86`, `arm64`) | Windows |
-| Linux | `scripts/build-studio.sh linux-x64` (or `linux-x86`, `linux-arm64` on an ARM machine) | Linux |
-| Linux with [llvm-mingw](https://github.com/mstorsjo/llvm-mingw) | `scripts/build-studio.sh windows-x64 windows-x86 windows-arm64` | Windows, cross |
-| macOS (Xcode command line tools, `brew install ninja molten-vk`) | `scripts/build-studio.sh macos-arm64 macos-x64` | macOS |
-| anywhere | `scripts/build-studio.sh frame-home` | the Frame Home installer |
-| anywhere it can | `scripts/build-studio.sh all` | everything this computer can build |
+**Frame Studio (on your computer)**

-Linux builds need the X11 headers (`libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev`) and, for
-`linux-x86`, `gcc-multilib g++-multilib`. Packages land in `dist/`.
+- Opens Meta homes (HSL, Clay, glTF), `.fenv` environments and Blender or Unity models; pairs rooms with vistas.
+- Move, rotate, scale, hide and delete objects, with undo and auto-saved versions.
+- Shape the walkable area: auto-generated surfaces, drawn floors, spawns, seats, hotspots, wall spots, gravity zones.
+- Add a background sound and a picture; set and calculate per-world settings.
+- Saves baked `.fenv` files and leaves out what can't be seen; sends them to the headset in one click.
+- Debug views (wireframe, meshes, GPU cost, overdraw), a home report, and the headset's settings and debug page
+  from your desk.

-The headset side (`frame-home`, `frame-switcher`, `fenv-tool`, the compositor layer) is built on the Steam Frame
-itself against SteamVR's own OpenVR library: the top-level `CMakeLists.txt`, then
-`g++ -O2 -shared -fPIC -std=c++17 layer/frame_home_layer.cpp -o build/layer/libframe_home_layer.so`. Its ready-built
-copy is `frame/payload/`, which every Studio build and the installer carry.
+## Guides

-## Layout
-
-| | |
+| Guide | What it covers |
 |---|---|
-| `studio/` | Frame Studio: `studio.cpp` (the editor), `platform*.{h,cpp}` (Windows / Linux / macOS), `frame_pacer.h` |
-| `src/` | shared engine: renderer (`hsl_renderer`), scene loading and baking, `.fenv`, walkable area, Frame Home (`main.cpp`), `fenv-tool` |
-| `layer/` | the Vulkan layer inside SteamVR's compositor that shows Frame Home in place of its environment |
-| `frame/` | the headset payload and the stand-alone installers |
-| `third_party/` | vendored libraries (each with its own license) |
-| `tools/` | test and measuring tools (headless renders, walk tests, shader generators) |
+| [Getting started](docs/getting-started.md) | Requirements, downloads, first launch, a 5-minute walkthrough |
+| [Preparing the Steam Frame](docs/headset-setup.md) | Developer mode, SSH, keys, the `frame` address |
+| [Installing Frame Home](docs/install-frame-home.md) | Three ways to install, updating, uninstalling, the off switch |
+| [Using Frame Home](docs/using-frame-home.md) | The Environments panel, moving around, every setting |
+| [Environments and .fenv](docs/environments-and-fenv.md) | The format, `fenv-tool`, per-world settings and tuning |
+| [Performance](docs/performance.md) | Reaching 120 fps, checking it, fixing stutter |
+| [Frame Studio guide](docs/studio-guide.md) | The Studio window, tools and panels |
+| [Bundles](docs/bundles.md) | Several environments in one `.fbundle` |
+| [Building from source](docs/building.md) | Building on each system, CI, the headset side |
+| [Troubleshooting](docs/troubleshooting.md) | Symptoms and fixes, logs, the self-test |
+
+## Building from source
+
+Everything Studio needs is in `third_party/`; you need CMake 3.16+ and Ninja. In short:
+
+| On | Command |
+|---|---|
+| Windows (Visual Studio 2022 with C++) | `studio\build_windows.bat x64` (or `x86`, `arm64`) |
+| Linux, macOS | `scripts/build-studio.sh <target>...` or `scripts/build-studio.sh all` |
+
+The headset side is built on the Steam Frame; a ready-built copy is in `frame/payload/`. Full details, prerequisites
+and the CI: [docs/building.md](docs/building.md).
+
+## Repository layout
+
+| Path | What it holds |
+|---|---|
+| `studio/` | Frame Studio: `studio.cpp` (the editor), `platform*.{h,cpp}` (Windows, Linux, macOS), `frame_pacer.h` |
+| `src/` | Shared engine: renderer (`hsl_renderer`), scene loading and baking, `.fenv`, walkable area, Frame Home (`main.cpp`), the Environments panel (`switcher.cpp`), `fenv-tool` |
+| `layer/` | The Vulkan layer inside SteamVR's compositor that shows Frame Home in place of its environment |
+| `frame/` | The headset payload and the stand-alone installers |
+| `scripts/`, `cmake/` | Build script and the llvm-mingw toolchain file |
+| `tools/`, `tests_loco/` | Test and measuring tools, movement tests |
+| `third_party/` | Vendored libraries (each with its own license) |
+| `docs/` | The guides |
@@ -0,0 +1,14 @@
+# Frame Studio and Frame Home documentation
+
+| Guide | What it covers |
+|---|---|
+| [Getting started](getting-started.md) | What the two programs are, system requirements, downloads, first launch, a 5-minute walkthrough |
+| [Preparing the Steam Frame](headset-setup.md) | Developer mode, SSH, the headset's address, an SSH key and a `frame` entry |
+| [Installing Frame Home](install-frame-home.md) | Three ways to install, what goes where, updating, uninstalling, the off switch |
+| [Using Frame Home](using-frame-home.md) | The Environments panel, adding environments, moving around, every setting |
+| [Environments and .fenv](environments-and-fenv.md) | The `.fenv` format, converting homes with `fenv-tool`, per-world settings and tuning |
+| [Performance](performance.md) | How Frame Home reaches 120 fps, checking it, fixing stutter, Studio's own pacing |
+| [Frame Studio guide](studio-guide.md) | The Studio window, tools and panels (being written) |
+| [Bundles](bundles.md) | Several environments in one `.fbundle` file (being written) |
+| [Building from source](building.md) | Building on each system, the CI, the headset side, the repository layout |
+| [Troubleshooting](troubleshooting.md) | Symptoms and fixes, logs, the self-test |
@@ -0,0 +1,194 @@
+# Building from source
+
+You only need this page if you want to change the code or build a version that isn't on the Releases page. Ready
+builds for every computer are on GitHub (see [getting-started.md](getting-started.md#download)).
+
+There are two parts:
+
+- **Frame Studio** builds on Windows, Linux and macOS (and cross-builds for Windows from Linux).
+- **The headset side** (Frame Home, the Environments panel, `fenv-tool` and the compositor layer) builds on the
+  Steam Frame itself. A ready-built copy is in the repository, in `frame/payload/`, so you only rebuild it when you
+  change that code.
+
+Everything Studio needs is in `third_party/`. Vulkan is loaded when Studio starts, so you don't need the Vulkan SDK
+to build it. All builds use CMake 3.16 or later and Ninja.
+
+## Frame Studio on Windows
+
+Prerequisites: Visual Studio 2022 (any edition) with the **Desktop development with C++** workload. It includes
+CMake and Ninja.
+
+1. Open a Command Prompt in the repository folder.
+2. Run:
+
+   ```bat
+   studio\build_windows.bat x64
+   ```
+
+   Use `x86` for 32-bit Windows or `arm64` for Windows on ARM instead of `x64`.
+3. The program is `%LOCALAPPDATA%\FrameStudio\build-x64\Frame Studio.exe` (the folder ends in your architecture).
+   The headset files are copied beside it, in `frame\`.
+
+To build into another folder, give it as the second argument: `studio\build_windows.bat x64 C:\builds\studio`.
+
+For `x86` or `arm64`, Visual Studio needs the matching C++ tools. For ARM64, add "MSVC ... ARM64/ARM64EC build
+tools" in the Visual Studio Installer.
+
+## Frame Studio with scripts/build-studio.sh (Linux, macOS)
+
+```sh
+scripts/build-studio.sh TARGET... [--build-dir DIR]
+```
+
+Each target is built and packed into `dist/`. `scripts/build-studio.sh --help` lists them.
+
+| Target | Build on | Output |
+|---|---|---|
+| `linux-x64`, `linux-arm64` | Linux on that kind of machine | `dist/FrameStudio-linux-<arch>.tar.gz` |
+| `linux-x86` | 64-bit Linux with `gcc-multilib g++-multilib` | `dist/FrameStudio-linux-x86.tar.gz` |
+| `windows-x64`, `windows-x86`, `windows-arm64` | Linux with [llvm-mingw](https://github.com/mstorsjo/llvm-mingw) | `dist/FrameStudio-windows-<arch>.zip` |
+| `macos-arm64`, `macos-x64` | A Mac with Xcode's command line tools | `dist/FrameStudio-macos-<arch>.zip` |
+| `frame-home` | Anywhere | `dist/FrameHome-installer.zip` (the headset files and install scripts, no Studio) |
+| `all` | Anywhere | Every target this computer can build |
+
+`all` builds: on a Mac, both macOS targets and `frame-home`; on 64-bit x86 Linux, `linux-x64`, `linux-x86` and
+`frame-home`; on ARM Linux, `linux-arm64` and `frame-home`. On Linux it adds the three Windows targets when it finds
+llvm-mingw.
+
+Build folders go in `build/<target>` unless you pass `--build-dir`.
+
+### Linux prerequisites
+
+Debian and Ubuntu package names:
+
+```sh
+sudo apt install build-essential cmake ninja-build \
+    libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxkbcommon-dev
+```
+
+For `linux-x86`, also install `gcc-multilib g++-multilib`.
+
+Then:
+
+```sh
+scripts/build-studio.sh linux-x64
+```
+
+### Windows from Linux (llvm-mingw)
+
+1. Download an llvm-mingw release and unpack it, by default to `~/.local/opt/llvm-mingw`. Or set `LLVM_MINGW` to
+   where it is.
+2. Run:
+
+   ```sh
+   scripts/build-studio.sh windows-x64 windows-x86 windows-arm64
+   ```
+
+The toolchain file is `cmake/llvm-mingw.cmake`.
+
+### macOS prerequisites
+
+1. Install Xcode's command line tools: `xcode-select --install`.
+2. Install Ninja and MoltenVK (Vulkan on Metal) with Homebrew:
+
+   ```sh
+   brew install ninja molten-vk
+   ```
+
+3. Build:
+
+   ```sh
+   scripts/build-studio.sh macos-arm64 macos-x64
+   ```
+
+The script copies MoltenVK into the app (`Contents/Frameworks/libMoltenVK.dylib`). To use another copy, set
+`MOLTENVK` to the path of a `libMoltenVK.dylib`. Without MoltenVK the app needs the Vulkan SDK installed to run.
+
+The Apple Silicon build runs on macOS 11 and later, the Intel build on macOS 10.15 and later.
+
+## Continuous builds (GitHub Actions)
+
+The workflow is `.github/workflows/build.yml`.
+
+| When | What happens |
+|---|---|
+| Every push, to any branch or tag, and every pull request | All targets build: Linux x64, x86, arm64; Windows x64, x86, arm64 (MSVC); macOS arm64 and x64; the Frame Home installer. Each is kept as an artifact of the run. |
+| A push to `main` | The **Latest build** pre-release is replaced with the new builds. Builds that worked are published even if another platform failed. |
+| A tag starting with `v` (for example `v1.0`) | A release with that name is published, with all builds. It is only made when every build succeeded. |
+| By hand | **Actions > build > Run workflow** |
+
+A newer push to the same branch cancels a run that is still going.
+
+To publish a version:
+
+```sh
+git tag v1.0
+git push --tags
+```
+
+To download a build from any run:
+
+1. Open the repository on GitHub and choose **Actions**.
+2. Click the run (each push is one).
+3. Scroll down to **Artifacts** and download the one you need. You must be signed in.
+
+## The headset side
+
+Frame Home (`frame-home`), the Environments panel (`frame-switcher`), `fenv-tool` and the compositor layer are built
+on the Steam Frame itself, against SteamVR's own OpenVR library (`/opt/steamvr/bin/linuxarm64`, set by
+`OPENVR_LIB_DIR`). You need a C++17 compiler, CMake, Ninja and the Vulkan headers on the headset.
+
+1. Copy the repository to the headset and log in: `ssh frame`.
+2. Build the programs with the top-level `CMakeLists.txt`:
+
+   ```sh
+   cd ~/frame-env
+   cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
+   cmake --build build
+   ```
+
+   This makes `build/frame-home`, `build/frame-switcher` and `build/fenv-tool`.
+3. Build the compositor layer (it is not part of CMake):
+
+   ```sh
+   mkdir -p build/layer
+   g++ -O2 -shared -fPIC -std=c++17 -fvisibility=hidden layer/frame_home_layer.cpp -o build/layer/libframe_home_layer.so -lpthread
+   ```
+
+4. Compile the layer's shader `layer/env_ps.frag` to SPIR-V, for example with glslc:
+
+   ```sh
+   glslc layer/env_ps.frag -o build/layer/env_ps.spv
+   ```
+
+### Refreshing frame/payload
+
+`frame/payload/` is the ready-built copy that every Studio build and the installer carry. After building on the
+headset, copy the results into it:
+
+| From (on the headset) | To (in the repository) |
+|---|---|
+| `build/frame-home`, `build/frame-switcher`, `build/fenv-tool` | `frame/payload/bin/` |
+| `build/layer/libframe_home_layer.so`, `build/layer/env_ps.spv` | `frame/payload/layer/` |
+
+`frame/payload/install.sh` is the installer itself; it lives in the repository and needs no build.
+
+Commit the new payload together with the code that changed. Otherwise Studio's **Install on Steam Frame** would
+install an older Frame Home than the code says.
+
+## Repository layout
+
+| Path | What it holds |
+|---|---|
+| `studio/` | Frame Studio: `studio.cpp` (the editor), `platform*.{h,cpp}` (Windows, Linux, macOS), `frame_pacer.h`, `build_windows.bat`, its `CMakeLists.txt` |
+| `src/` | The shared engine: renderer (`hsl_renderer`), scene loading and baking, `.fenv`, walkable area, Frame Home (`main.cpp`), the Environments panel (`switcher.cpp`), `fenv-tool` |
+| `layer/` | The Vulkan layer inside SteamVR's compositor that shows Frame Home in place of its environment, and its shader |
+| `frame/` | The headset payload (`payload/`) and the stand-alone installers |
+| `scripts/` | `build-studio.sh` |
+| `cmake/` | The llvm-mingw toolchain file |
+| `tests_loco/` | Movement tests |
+| `tools/` | Test and measuring tools (headless renders, walk tests, shader sources and generators) |
+| `third_party/` | Vendored libraries, each with its own license |
+| `docs/` | These guides |
+| `CMakeLists.txt` | The headset-side build |
+| `.github/workflows/build.yml` | The CI |
@@ -0,0 +1,5 @@
+# Bundles
+
+This guide is being written. It will explain bundles: several `.fenv` environments packed into one `.fbundle` file,
+so a whole collection can be shared and installed in one step. Until it is ready, see
+[environments-and-fenv.md](environments-and-fenv.md) for single environments.
@@ -0,0 +1,197 @@
+# Environments and the .fenv format
+
+A **Frame environment** is one `.fenv` file. It holds everything Frame Home needs to show one home: the scene, where
+you can walk and sit, your edits, a sound, a thumbnail and the home's own settings. Frame Studio writes it; Frame
+Home and the Environments panel load it directly.
+
+## What a .fenv is
+
+A `.fenv` is a ZIP file. You can open it with any ZIP tool to look inside (don't change it that way, though).
+
+There are two kinds:
+
+| Kind | What's inside | Notes |
+|---|---|---|
+| **Baked** (native) | The home already converted for the Steam Frame: meshes, textures in the headset's GPU format with their smaller levels, animations, the world layer | Opens several times faster and uses less memory. What Studio and `fenv-tool` make today. |
+| **Wrapped** (older) | The original Meta `.apk` files, plus edits and a `world.json` | Frame Home converts it every time it loads. Made by older versions, or when a home could not be baked. `fenv-tool upgrade` turns it into a baked one. |
+
+`fenv-tool info` tells you which kind a file is: it prints "baked scene" or "loads from its homes".
+
+## What's inside
+
+| Member | In | What it is |
+|---|---|---|
+| `fenv.json` | every `.fenv` | The manifest: name, where the home came from (package and version of each `.apk`), and which other members are there. It also holds the environment's own settings. |
+| `scene.bin.lz` | baked | The baked scene, packed with LZMA (much smaller than ZIP's own packing for textures). It is unpacked once, into a cache, then loaded from there. |
+| `apks/...` | wrapped | The original Meta home files (a room, and maybe its vista) |
+| `world.json` | wrapped | The world layer: spawn points, seats, teleport hotspots, walkable surfaces, wall spots, gravity zones. A baked scene carries this inside `scene.bin`. |
+| `edits.json` | when you edited | What you changed in Studio: moved and deleted objects, the added sound and how loud the home's own sound plays |
+| a sound file | when you added one | The sound you added in Studio (`.ogg`, `.opus`, `.wav`, `.mp3`, `.flac`), named in `edits.json` |
+| `thumb.png` | usually | The picture the Environments panel shows |
+| `models/...` | when imported | Models from Blender or Unity, with their texture files (wrapped files only; a baked scene holds their meshes) |
+
+Unpacked copies live in a cache: `~/.cache/frame-home/fenv` on the headset and on Linux and macOS, and
+`%LOCALAPPDATA%\FrameStudio\cache` on Windows. They are keyed by the file's path, size and time, so a changed file is
+unpacked again. You can delete the cache at any time.
+
+## Typical sizes
+
+Measured over a selector of 48 environments:
+
+| | Size |
+|---|---|
+| Average | about 70 MB |
+| Median | about 48 MB |
+| Smallest | 3 MB |
+| Largest | 218 MB |
+
+A home with a room and its vista is usually larger than either alone.
+
+## Making a .fenv in Frame Studio
+
+1. Open a home: **File > Open Home...**.
+2. Edit it if you like.
+3. **File > Save to My Environments** (Ctrl+S) or **File > Save As...**.
+
+Two options in the **File** menu change how Studio saves:
+
+| Option | What it does |
+|---|---|
+| Faster Saving | Packs on all CPU cores: about 3 times quicker, about 1% bigger. Off: the smallest file. Nothing is lost either way. |
+| Leave Out What Can't Be Seen | Leaves out geometry nobody can see from anywhere they can walk, sit or teleport to (the backs of things, what's behind walls), so the headset draws less. Moved and deleted objects are kept whole. Saving takes up to a minute longer. |
+
+## Converting homes with fenv-tool
+
+`fenv-tool` is a command-line converter. It comes with Frame Home and is installed on the headset as
+`~/frame-home/bin/fenv-tool`. Run it over SSH (`ssh frame`, see [headset-setup.md](headset-setup.md)).
+
+It reads Meta home `.apk` files (HSL, Clay `.opa`, glTF `.ovrscene`) and models (`.glb`, `.gltf`, `.fbx`, `.obj`).
+
+First copy the files to the headset, for example:
+
+```sh
+scp haven2025.apk calming.apk frame:
+ssh frame
+```
+
+### convert: one .fenv per home
+
+```sh
+~/frame-home/bin/fenv-tool convert ~/frame-home/envs haven2025.apk courtyard.apk
+```
+
+Makes `haven2025.fenv` and `courtyard.fenv` in `~/frame-home/envs`. To pair a room with its vista, join them with
+`+`:
+
+```sh
+~/frame-home/bin/fenv-tool convert ~/frame-home/envs haven2025.apk+calming.apk
+```
+
+This makes `haven2025+calming.fenv`.
+
+### pack: one .fenv from chosen inputs
+
+```sh
+~/frame-home/bin/fenv-tool pack ~/frame-home/envs/haven-calming.fenv --name "Haven + Calming" haven2025.apk calming.apk
+```
+
+| Option | Meaning |
+|---|---|
+| `--name NAME` | The name the panel shows. Default: made from the package names. |
+| `--edits edits.json` | Include edits made in Studio |
+| `--thumb thumb.png` | Include a thumbnail |
+| `--keep-apks` | Store the original `.apk` files as well |
+| `--fast` | Pack in parallel: several times quicker, about 3% bigger |
+| `--no-optimize` | Keep geometry that can't be seen from anywhere you can be (also works with `convert` and `upgrade`) |
+
+### upgrade: re-bake with the current version
+
+```sh
+~/frame-home/bin/fenv-tool upgrade ~/frame-home/envs/*.fenv
+```
+
+Re-bakes each file's scene with this version and keeps everything else (world, edits, sound, picture). A file that
+needs nothing is left alone. A wrapped file is baked: the scene replaces its `.apk` files.
+
+### info: what a .fenv holds
+
+```sh
+~/frame-home/bin/fenv-tool info ~/frame-home/envs/haven-calming.fenv
+```
+
+Prints the name, baked or wrapped, its sources and models, whether it has edits and a thumbnail, and its settings.
+
+### report: what a home costs and what's wrong with it
+
+```sh
+~/frame-home/bin/fenv-tool report ~/frame-home/envs/haven-calming.fenv
+~/frame-home/bin/fenv-tool report --json haven2025.apk+calming.apk
+```
+
+Lists what the home is made of, what it costs, and problems found. It ends with exit code 3 when the home is broken.
+Studio shows the same under **Debug > Home Report...**.
+
+## Per-world settings
+
+Every home costs the headset a different amount. A `.fenv` can carry its own settings, which win over the headset's
+while you are in it. Every field is optional; an unset field uses the headset's setting.
+
+| Field | Values | Meaning |
+|---|---|---|
+| `resolution` | 0.5 to 2 | A fixed resolution scale (1 = SteamVR's recommended size) |
+| `msaa` | 1, 2, 4 | Anti-aliasing samples |
+| `anisotropy` | 4, 8, 16 | Texture filtering |
+| `foveation` | 1 to 3 (in between too) | Foveation strength: 1 gentle, 2 medium, 3 strong |
+| `frameRate` | 0 or 1 | 0 the display's rate, 1 half rate |
+
+Resolution, foveation and frame rate apply live. A different anti-aliasing or filtering makes Frame Home restart
+itself when you switch to that home. A `.fenv` keeps these in its `fenv.json`. A Meta `.apk` in `envs/` keeps them in
+a file beside it, `<name>.apk.settings.json`.
+
+### Setting them by hand
+
+```sh
+~/frame-home/bin/fenv-tool settings my-home.fenv                                  # show
+~/frame-home/bin/fenv-tool settings my-home.fenv '{"resolution": 1.2, "foveation": 2}'   # set
+~/frame-home/bin/fenv-tool settings my-home.fenv --clear                          # back to the headset's
+```
+
+In Studio, the open environment's world settings have the same fields (Resolution, Foveation, MSAA, Frame rate),
+with **Use Headset Settings** to clear them.
+
+### Letting the headset work them out: fenv-tool tune
+
+`fenv-tool tune` finds the best-looking settings the headset keeps up with in one home. Run it on the headset:
+
+```sh
+~/frame-home/bin/fenv-tool tune ~/frame-home/envs/my-home.fenv
+```
+
+How it works:
+
+1. It starts from your headset settings.
+2. For each try, it walks through the home for 30 seconds, paced at the display's rate, like a visitor: walking,
+   snap turns, teleports and fast head turns. It runs beside the live compositor, as on the headset in use.
+3. A try **keeps up** when it holds 120 fps with at most 1% of frames late.
+4. If your settings keep up, it tries sharper foveation, half a step at a time, while it still keeps up.
+   If not, it tries stronger foveation, then lower resolution (10% at a time), and as a last resort half frame rate.
+   Your anti-aliasing stays as it is.
+5. Before each try it waits until the headset is below 80 °C, so every try starts alike.
+6. It stores the result in the `.fenv` (or `<apk>.settings.json`) with a note of when and how it was tuned, and
+   prints it as JSON.
+
+It takes a few minutes. Options:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--seconds S` | 30 | Length of each walk (5 to 300) |
+| `--late F` | 0.01 | Share of frames allowed to be late (0.01 = 1%) |
+| `--hz N` | 120 | Frame rate to keep up with |
+| `--cool C` | 80 | Wait until the headset is below C °C before each try |
+| `--dry-run` | | Print the result without storing it |
+| `--bench PATH` | `frame-home` beside `fenv-tool` | The Frame Home program to walk with |
+
+From Studio, **Calculate Best Settings** in the environment's world settings does the same: it sends the home to the
+headset, runs the tune there, and keeps the result in the open environment. Save to keep it in the file.
+
+See [performance.md](performance.md) for the bigger picture.
@@ -0,0 +1,165 @@
+# Getting started
+
+This guide explains what Frame Studio and Frame Home are, what you need, and how to go from a download to a home
+on your Steam Frame in a few minutes.
+
+> Screens and panel positions are described in [studio-guide.md](studio-guide.md). This guide keeps to menu names,
+> because the window layout is being redesigned.
+
+## What they are
+
+**Frame Home** runs on the Steam Frame. It replaces SteamVR's own environment (the space you stand in when no game
+is running) with a home of your choice. It shows at boot, behind the Steam menu and while games load, like the
+built-in environment does. It is not a game and has no entry in your library.
+
+**Frame Studio** is the desktop editor. It runs on Windows, Linux and macOS. It opens:
+
+- Meta Quest homes (`.apk` files: HSL, Clay `.opa` or glTF homes),
+- Frame environments (`.fenv` files),
+- models from Blender or Unity (`.glb`, `.gltf`, `.fbx`, `.obj`).
+
+It shows them with the same renderer the headset uses. You can move, hide and delete objects, shape where you can
+walk, add seats, sounds and a picture, save the result as a `.fenv` environment, and send it to the headset.
+
+## What you need
+
+| | Requirement |
+|---|---|
+| Graphics | A GPU with Vulkan 1.2. Any recent NVIDIA, AMD or Intel driver on Windows and Linux. |
+| Windows | Windows 10 or 11. 64-bit (x64), 32-bit (x86) or ARM64. |
+| Linux | 64-bit (x64), 32-bit (x86) or ARM64, with an X11 desktop or XWayland. |
+| macOS | macOS 11 or later on Apple Silicon. macOS 10.15 or later on Intel. Vulkan runs on Metal through MoltenVK, which is inside the app. |
+| Headset | A Steam Frame with developer mode and SSH turned on, on the same network as your computer. See [headset-setup.md](headset-setup.md). |
+
+The 32-bit builds can use at most 4 GB of memory. The very largest homes may not fit.
+
+You do not need Studio to use Frame Home. If you only want to install Frame Home and copy ready-made `.fenv` files,
+see [install-frame-home.md](install-frame-home.md).
+
+## Download
+
+1. Open the project's GitHub page and go to **Releases**.
+2. Pick a release:
+   - **Latest build** is rebuilt from the newest code every time the main branch changes. It is marked as a
+     pre-release.
+   - A **version release** (for example `v1.0`) is a fixed version.
+3. Download the file for your computer:
+
+| Computer | File |
+|---|---|
+| Windows, 64-bit PCs | `FrameStudio-windows-x64.zip` |
+| Windows, 32-bit | `FrameStudio-windows-x86.zip` |
+| Windows on ARM | `FrameStudio-windows-arm64.zip` |
+| Linux, 64-bit PCs | `FrameStudio-linux-x64.tar.gz` |
+| Linux, 32-bit | `FrameStudio-linux-x86.tar.gz` |
+| Linux on ARM | `FrameStudio-linux-arm64.tar.gz` |
+| Mac with Apple Silicon (M1 and later) | `FrameStudio-macos-arm64.zip` |
+| Mac with Intel | `FrameStudio-macos-x64.zip` |
+| Frame Home only (no Studio) | `FrameHome-installer.zip` |
+
+Builds of other branches are not on the Releases page. You find them under **Actions**: open the run, then scroll
+down to **Artifacts**. You must be signed in to GitHub to download artifacts.
+
+## Unpack and first launch
+
+Every Studio download holds the program and, beside it, a `frame` folder. That folder is the headset side of
+Frame Home, which Studio installs for you. Keep the two together.
+
+### Windows
+
+1. Right-click the zip and choose **Extract All**. Pick a folder you can write to, for example your Documents.
+2. Open the extracted folder and double-click **Frame Studio.exe**.
+3. Windows may show "Windows protected your PC" (SmartScreen), because the program is not signed.
+   Click **More info**, then **Run anyway**.
+
+### macOS
+
+1. Double-click the zip. You get **Frame Studio.app**.
+2. Move it to your Applications folder if you like.
+3. The app is not signed, so a double-click is refused the first time. Instead, right-click (or Control-click) the
+   app and choose **Open**, then **Open** again in the dialog. After that, a normal double-click works.
+
+### Linux
+
+1. Unpack the archive:
+
+   ```sh
+   tar -xzf FrameStudio-linux-x64.tar.gz
+   cd FrameStudio-linux-x64
+   ```
+
+2. Make sure the program can run, then start it:
+
+   ```sh
+   chmod +x "Frame Studio"
+   ./"Frame Studio"
+   ```
+
+   You can also double-click it in your file manager. Studio writes its messages to `studio.log` in its data
+   folder (see below), not to the terminal.
+3. Open and save dialogs need `zenity` or `kdialog`. Install one with your package manager if dialogs do not appear.
+
+## Where Studio keeps its files
+
+| What | Windows | Linux | macOS |
+|---|---|---|---|
+| Studio's own files (settings, edits, recent homes, auto-saves, `studio.log`) | `%APPDATA%\FrameStudio` | `~/.local/share/FrameStudio` | `~/Library/Application Support/FrameStudio` |
+| My Environments (what you save) | `Documents\Frame Studio\Environments` | `Frame Studio/Environments` in your Documents folder (`~/Documents` on most systems) | `~/Documents/Frame Studio/Environments` |
+
+**File > My Environments > Show the Folder** opens the My Environments folder.
+
+## A first walkthrough (about 5 minutes)
+
+Before you start, set up the headset once: [headset-setup.md](headset-setup.md). Then install Frame Home on it with
+**Frame > Install on Steam Frame...** (see [install-frame-home.md](install-frame-home.md)).
+
+### 1. Open a home
+
+1. Choose **File > Open Home...** (Ctrl+O), or drop files onto the Studio window.
+2. Pick a Meta home (`.apk`), a `.fenv` environment, or a model.
+   - To open a room together with its view outside (a "footprint" and a "vista"), select both files in the dialog.
+     You can also add a vista later with **File > Add Vista...**.
+3. Wait for the home to load. Studio shows its progress.
+
+### 2. Look around
+
+| To | Do this |
+|---|---|
+| Orbit | Middle mouse drag, or Alt + left drag |
+| Pan | Shift + middle mouse drag |
+| Zoom | Mouse wheel |
+| Fly | Hold the right mouse button and use W A S D, Q and E for down and up |
+| See it from where you will stand | **View > Player View** (Numpad 0 or P) |
+| Select an object | Left click it |
+
+**Help > Controls** (F1) lists every shortcut.
+
+To change something, select an object, then use **Edit > Move** (G), **Rotate** (R), **Scale** (S), **Hide
+Selected** (H) or **Delete Selected** (X). The selected object's details show in the Inspector on the right.
+**Edit > Undo** (Ctrl+Z) takes any step back.
+
+### 3. Save
+
+1. Choose **File > Save to My Environments** (Ctrl+S).
+2. Studio bakes the home into one `.fenv` file and puts it in My Environments under its name.
+
+After the first save, the menu item is called **Save** and writes to the same file. **File > Save As...** saves a
+copy somewhere else.
+
+### 4. Send it to the headset
+
+1. Put the headset on, or at least make sure it is on and connected to your network.
+2. Choose **Frame > Send to Frame**.
+3. Studio saves the home as one `.fenv`, copies it to the headset and makes it the current environment. Its
+   progress shows in the Studio window.
+
+In the headset you now stand in your home. Open the Steam menu to switch environments or change settings: see
+[using-frame-home.md](using-frame-home.md).
+
+## Next steps
+
+- [headset-setup.md](headset-setup.md): developer mode, SSH and keys.
+- [install-frame-home.md](install-frame-home.md): all ways to install, update and remove Frame Home.
+- [using-frame-home.md](using-frame-home.md): the Environments panel and every setting.
+- [environments-and-fenv.md](environments-and-fenv.md): what a `.fenv` is and how to convert homes.
+- [troubleshooting.md](troubleshooting.md): when something does not work.
@@ -0,0 +1,136 @@
+# Preparing the Steam Frame
+
+Frame Studio and the Frame Home installers talk to the headset over SSH, the standard way to log in to another
+computer over the network. This guide sets that up once. After it, `ssh frame` logs you in to the headset without a
+password, and Studio can send homes to it.
+
+You need:
+
+- the Steam Frame, on the same network as your computer,
+- a computer with an SSH client (Windows 10 and 11, Linux and macOS all have one, see below).
+
+## 1. Turn on developer mode and SSH
+
+1. On the headset, open the system settings and turn on **developer mode**.
+2. In the developer settings, turn on **SSH** (remote login).
+
+The exact names of these options may change between SteamOS versions. If you cannot find them, look for "Developer"
+in the headset's settings.
+
+The headset's user name is `steamos`. To log in with a password the first time, that user needs one. If you have
+never set it, switch the headset to Desktop Mode, open a terminal (Konsole) and run `passwd`.
+
+## 2. Find the headset's address
+
+You need either its IP address or a name your network knows it by.
+
+- **In the headset:** the network (Wi-Fi) settings show the IP address of the connection, for example
+  `192.168.1.50`.
+- **In Desktop Mode:** open Konsole and run `hostname -I` (prints the IP addresses).
+- **On your router:** its list of connected devices shows the headset and its address.
+
+Some networks also let you reach a device by its host name with `.local` added (`<hostname>.local`). That depends on
+your network, so the IP address is the safe choice.
+
+Tip: give the headset a fixed address in your router (often called "DHCP reservation"). Then the address never
+changes.
+
+The examples below use `192.168.1.50`. Use your headset's address instead.
+
+## 3. Check that SSH works
+
+On your computer, open a terminal (on Windows: PowerShell or Command Prompt) and run:
+
+```sh
+ssh steamos@192.168.1.50
+```
+
+The first time, SSH asks whether you trust the headset's key. Type `yes`. Then enter the `steamos` password. If you
+see a prompt on the headset, SSH works. Type `exit` to log out.
+
+## 4. Set up an SSH key
+
+Frame Studio never types a password for you: it needs a key. A key also saves you typing the password every time.
+
+### Windows
+
+Windows 10 and 11 include an SSH client called "OpenSSH Client". If `ssh` is not found, turn it on in
+**Settings > Apps > Optional features**, or install Git for Windows (its SSH works too; Studio finds either).
+
+In PowerShell:
+
+1. Make a key (press Enter to accept the default file; a passphrase is optional):
+
+   ```powershell
+   ssh-keygen -t ed25519
+   ```
+
+2. Copy the public key to the headset (Windows has no `ssh-copy-id`, so this line does the same job):
+
+   ```powershell
+   type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh steamos@192.168.1.50 "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys"
+   ```
+
+   Enter the `steamos` password one last time.
+
+### Linux and macOS
+
+1. Make a key:
+
+   ```sh
+   ssh-keygen -t ed25519
+   ```
+
+2. Copy it to the headset:
+
+   ```sh
+   ssh-copy-id steamos@192.168.1.50
+   ```
+
+If you already have a developer key for the headset, you can use that key instead of making a new one. Name it in
+the `IdentityFile` line below.
+
+## 5. Add a "frame" entry to your SSH config
+
+Studio and the installers use the address `frame` unless you tell them otherwise. Make that name point at your
+headset.
+
+Open (or create) the SSH config file:
+
+| System | File |
+|---|---|
+| Windows | `C:\Users\<you>\.ssh\config` (no file extension) |
+| Linux, macOS | `~/.ssh/config` |
+
+Add:
+
+```
+Host frame
+    HostName 192.168.1.50
+    User steamos
+    IdentityFile ~/.ssh/id_ed25519
+```
+
+Replace `192.168.1.50` with your headset's address. On Windows, `~` in this file means your user folder.
+
+## 6. Test it
+
+```sh
+ssh frame
+```
+
+You should be logged in to the headset without a password. Type `exit` to leave.
+
+If it asks for a password, the key was not copied (step 4) or the `IdentityFile` line points at the wrong file. If
+it cannot connect, check the address and that SSH is on. See [troubleshooting.md](troubleshooting.md).
+
+## Using a different address
+
+You do not have to use the name `frame`:
+
+- In Studio, **Frame > Install on Steam Frame...** has a **Headset** field. Type an SSH alias or
+  `steamos@<address>`. Studio remembers it and uses it for **Send to Frame** too.
+- The installers take `--host` (Linux, macOS) or ask for the address (Windows). See
+  [install-frame-home.md](install-frame-home.md).
+
+Next: [install-frame-home.md](install-frame-home.md).
@@ -0,0 +1,195 @@
+# Installing Frame Home
+
+Frame Home is the part that runs on the Steam Frame. There are three ways to install it. All three do the same
+thing on the headset: they copy the files and run the same installer (`install.sh`).
+
+Before you start, the headset needs developer mode and SSH: see [headset-setup.md](headset-setup.md). The third way
+(on the headset itself) needs no SSH.
+
+## Way 1: from Frame Studio
+
+1. Choose **Frame > Install on Steam Frame...**.
+2. In **Headset**, type the headset's address: an SSH alias such as `frame`, or `steamos@<address>`, for example
+   `steamos@192.168.1.50`. Studio remembers it.
+3. Under **Environments**, choose what to copy along:
+   - **The open home** (if one is open). It is saved as a `.fenv` first if it isn't one already.
+   - **Add .fenv...** adds more environment files.
+   - With nothing chosen, only Frame Home is installed. Environments already on the headset stay.
+4. Click **Install**. The window shows each step and, at the end, "Installed".
+
+Environments already on the headset with the same name and size are not copied again.
+
+**Restore SteamVR's environment** in the same window uninstalls (see [Uninstalling](#uninstalling)).
+
+Studio connects without asking for passwords, so it needs an SSH key (see [headset-setup.md](headset-setup.md)).
+
+## Way 2: with FrameHome-installer.zip, from any computer
+
+Download `FrameHome-installer.zip` from the Releases page (see [getting-started.md](getting-started.md#download))
+and unpack it. Inside are:
+
+| File | For |
+|---|---|
+| `Install Frame Home.bat` | Windows: double-click it |
+| `install-frame-home.ps1` | Windows: the script the .bat runs (PowerShell) |
+| `install-frame-home.sh` | Linux and macOS |
+| `payload/` | The headset files (programs, compositor layer, `install.sh`) |
+| `README-frame-home.txt` | A short version of this page |
+
+These installers can use a key or a password. With a password, SSH asks for it several times (once per step).
+
+### Windows
+
+1. Double-click **Install Frame Home.bat**.
+2. It asks for the **Steam Frame address**. Press Enter to keep the one shown (`frame`, or the address you last used
+   in Studio), or type another, such as `steamos@192.168.1.50`.
+3. Wait for "Frame Home is installed.", then press a key to close the window.
+
+To copy environments at the same time, drag one or more `.fenv` files onto **Install Frame Home.bat**. The first
+one becomes the environment shown.
+
+Windows needs an SSH client: "OpenSSH Client" under **Settings > Apps > Optional features**, or Git for Windows.
+
+From PowerShell you can also run the script directly:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File install-frame-home.ps1 -HostName steamos@192.168.1.50 C:\path\to\home.fenv
+```
+
+| Option | Meaning |
+|---|---|
+| `-HostName HOST` | The headset's SSH address. Default `steamos@frame`. A name without `user@` gets `steamos@` added. |
+| `-Uninstall` | Give the environment back to SteamVR (files stay). |
+| `file.fenv ...` | Environments to copy. The first is the one shown. |
+
+### Linux and macOS
+
+```sh
+sh install-frame-home.sh --host steamos@192.168.1.50 my-home.fenv another.fenv
+```
+
+| Option | Meaning |
+|---|---|
+| `--host HOST` | The headset's SSH address. Default `steamos@frame`. A name without `user@` gets `steamos@` added. |
+| `--uninstall` | Give the environment back to SteamVR (files stay). |
+| `file.fenv ...` | Environments to copy. The first is the one shown. |
+| `-h`, `--help` | Show the usage. |
+
+Copied environments get a headset-friendly name: lower case, spaces become dashes, and only letters, digits, `.`,
+`_` and `-` are kept. `My Home.fenv` becomes `my-home.fenv`.
+
+## Way 3: directly on the headset
+
+1. Switch the headset to Desktop Mode.
+2. Copy the unpacked `FrameHome-installer` folder to the headset (USB stick, network share, or a download in the
+   headset's browser).
+3. Open a terminal (Konsole) in that folder.
+4. Run:
+
+   ```sh
+   sh payload/install.sh
+   ```
+
+5. Put `.fenv` files in `~/frame-home/envs`. The Environments panel lists them.
+
+## What gets installed where
+
+Everything goes into your home folder on the headset. Nothing is changed under `/opt` or `/usr`.
+
+| Path on the headset | What it is |
+|---|---|
+| `~/frame-home/bin/` | The programs: `frame-home` (draws your home), `frame-switcher` (the Environments panel), `fenv-tool` (converts and tunes environments) |
+| `~/frame-home/envs/` | Your environments (`.fenv`, or Meta home `.apk` files) |
+| `~/frame-home/envs/.thumbs/` | Thumbnails for the panel, made on the headset |
+| `~/frame-home/layer/` | The compositor layer (`libframe_home_layer.so`, `env_ps.spv`) and its log |
+| `~/frame-home/current` | The name of the environment shown now |
+| `~/frame-home/settings.json` | Your settings (see [using-frame-home.md](using-frame-home.md)) |
+| `~/frame-home/stats.json` | How Frame Home is running, for the panel and Studio to show |
+| `~/frame-home/logs/` | Logs, the environment report, and pictures saved from the Debug page |
+| `~/frame-home/.install/frame/` | The copy of the installer that Studio and the installers upload |
+| `~/.local/share/vulkan/implicit_layer.d/frame_home_layer.json` | Registers the compositor layer with Vulkan |
+| `~/.cache/frame-home/` | Unpacked environments and other caches (safe to delete; rebuilt when needed) |
+
+SteamVR's config (`~/.config/openvr/`) gets two app manifests registered and the Environments panel set to start
+with SteamVR.
+
+## How Frame Home takes SteamVR's environment slot
+
+SteamVR draws its own environment inside the compositor (the program that puts everything on the displays). Frame
+Home leaves that in place and swaps only the picture:
+
+1. A small **compositor layer** loads into SteamVR's compositor. Wherever the compositor would draw its own
+   environment, the layer draws the newest frame Frame Home rendered instead.
+2. **frame-home** renders your home in the background, at the display's frame rate.
+3. **frame-switcher**, the Environments panel, starts with SteamVR. It keeps `frame-home` running and restarts it if
+   it stops.
+
+Because the compositor still does the drawing, your home shows at boot, behind the Steam menu and during game loads,
+the controllers stay visible, and passthrough still works.
+
+The layer is careful:
+
+- It is active only inside SteamVR's compositor. Everywhere else it does nothing.
+- If Frame Home has not sent a frame for half a second (stopped or crashed), SteamVR's own environment shows.
+- If the compositor stops twice in a row before the layer got going, the layer turns itself off (it creates the
+  `off` file, see below).
+
+## Updating
+
+Install again, any of the three ways. The installer:
+
+- replaces the programs and the layer (a running copy keeps its old file until it restarts),
+- keeps your environments, settings and choice of environment,
+- restarts the Environments panel and Frame Home so the new version takes over at once. If the layer changed, it
+  also restarts SteamVR's compositor, which comes straight back.
+
+If SteamVR is not running, the installer writes the registration into SteamVR's config files. Frame Home then takes
+over the next time SteamVR starts.
+
+Studio's download carries its own copy of the headset files. Installing from an older Studio installs that older
+Frame Home.
+
+## Uninstalling
+
+| From | Do this |
+|---|---|
+| Studio | **Frame > Install on Steam Frame...**, then **Restore SteamVR's environment** |
+| Windows | `powershell -ExecutionPolicy Bypass -File install-frame-home.ps1 -Uninstall` |
+| Linux, macOS | `sh install-frame-home.sh --uninstall` |
+| On the headset | `sh payload/install.sh uninstall` |
+
+This gives the environment back to SteamVR. SteamVR's own environment returns once SteamVR restarts.
+Your environments and the programs in `~/frame-home` stay. To remove everything, delete `~/frame-home` afterwards.
+
+## The emergency off switch
+
+If anything goes wrong, create this file on the headset:
+
+```sh
+touch ~/frame-home/layer/off
+```
+
+The layer checks for it every second and steps aside: SteamVR's own environment shows (at the latest after
+SteamVR's next start). Nothing else is changed.
+
+To turn Frame Home back on, do one of these:
+
+- In the Environments panel, press **Start Frame Home** or **Turn Frame Home On**. This deletes the file and starts
+  Frame Home.
+- Delete the file yourself: `rm ~/frame-home/layer/off`. If your home does not come back, restart SteamVR.
+- Install again. The installer removes the file.
+
+If the layer turned itself off after two failed starts, the panel says "Off: it failed to start twice".
+
+## Backups
+
+The installer does not make backups. Before you try something new, you can save your settings and programs with one
+command on the headset:
+
+```sh
+tar -czf ~/frame-home-backup-$(date +%Y%m%d-%H%M%S).tgz -C ~ --exclude=frame-home/envs frame-home
+```
+
+This leaves out `envs/`, which is large. Your environments are usually also on your computer (in Studio's My
+Environments folder). To restore, unpack the archive into your home folder (`tar -xzf <file> -C ~`) and restart
+SteamVR.
@@ -0,0 +1,104 @@
+# Performance
+
+The Steam Frame shows 120 frames a second. That leaves about 8.3 ms per frame. A late frame is a visible stutter.
+This page explains how Frame Home keeps up, how to check it, and what to do when a home stutters. The last section
+covers Frame Studio on your computer.
+
+## How Frame Home reaches 120 fps
+
+| What | How it helps |
+|---|---|
+| **Baked environments** | A baked `.fenv` holds the home already converted for the headset: textures in its GPU format with all their smaller levels, animations stored as data, geometry that can't be seen left out. Loading is quick, memory use is lower and the GPU does less. See [environments-and-fenv.md](environments-and-fenv.md). |
+| **Eye-tracked foveation** | Full detail where you look, coarser toward the edges. The Steam Frame's eye tracking moves the sharp area with your gaze, so you don't see the coarse parts. The time saved goes to resolution. |
+| **Foveation smoothing in the compositor** | The coarse edge areas are smoothed as SteamVR's compositor reads Frame Home's picture, instead of in an extra pass of their own. That saves GPU time on every frame. |
+| **Auto resolution** | With Resolution set to Auto, Frame Home moves the resolution between 70% and 150% to keep each frame inside its time: sharper whenever the home is light enough. |
+| **Per-world settings** | Each `.fenv` can carry settings tuned for that home (resolution, foveation strength, frame rate). `fenv-tool tune` and Studio's **Calculate Best Settings** find them by walking the home on the headset. |
+| **Thermal governor** | A hot Steam Frame slows its GPU (to about a third in the mid-90s °C), and every frame then takes up to three times as long. Above the **Keep cool** temperature (86 °C by default), Frame Home makes the edges of view a little coarser at a time until the headset cools. Where you look stays sharp. |
+| **Half frame rate** (optional) | Draws the environment every other display frame and turns it with your head in between, as Meta's home does. Each frame gets twice the GPU time. A last resort for very heavy homes. |
+| **Behind the Steam menu** (optional) | Half rate there leaves more GPU to the menu and its apps. The default is full rate. |
+
+## Checking performance
+
+### In the headset
+
+Open the Steam menu, then **Environments > Settings**. The **Graphics** heading shows the GPU time a frame takes
+out of the time it has, the size drawn per eye, and whether eye tracking is in use. When it starts with **"Too slow,
+lower Resolution"**, frames are late.
+
+The **Debug** page helps find what is slow:
+
+- **View > GPU cost** tints each mesh: green is cheap, red is costly.
+- **Costliest meshes** lists the most expensive ones.
+- **Leave out** See-through surfaces, Cut-out surfaces or Sky shows whether those are what's slow.
+
+See [using-frame-home.md](using-frame-home.md#the-debug-page).
+
+### From your computer
+
+- In Studio, **Edit > Settings...** shows "Now on the headset: ..." under the Steam Frame settings, read from the
+  headset. **Read from Headset** refreshes it.
+- **Debug > Headset Debug...** shows and changes the headset's Debug page.
+- **Debug > Home Report...** lists what the open home costs and what's wrong with it.
+- Studio's own **Debug** views (Normal, Wireframe, Meshes, GPU Cost, Overdraw) and **Debug > Leave Out** work like the
+  headset's, but they measure your computer's GPU, not the headset's.
+
+On the headset, Frame Home writes its numbers to `~/frame-home/stats.json` every 2 seconds (GPU and CPU time per
+frame, frame rate, late frames, resolution, temperature). `ssh frame cat frame-home/stats.json` shows them.
+
+### Benchmark (advanced)
+
+`frame-home --bench` draws a home the way the headset does, without SteamVR showing it, and prints what its frames
+cost. Run it on the headset over SSH:
+
+```sh
+~/frame-home/bin/frame-home --bench ~/frame-home/envs/my-home.fenv --seconds 30
+```
+
+| Option | Meaning |
+|---|---|
+| `--seconds N` | How long to run |
+| `--hz N` | The rate to pace at (default 120) |
+| `--unpaced` | Run as fast as possible instead of at the display's rate |
+
+The live environment shares the GPU, so the numbers include its work. `fenv-tool tune` uses this benchmark to walk
+through a home.
+
+## When a home stutters
+
+Try these in order:
+
+1. **Tune it.** On the headset: `~/frame-home/bin/fenv-tool tune ~/frame-home/envs/<home>.fenv`, or in Studio open
+   the home and use **Calculate Best Settings**, then save and send it again. See
+   [environments-and-fenv.md](environments-and-fenv.md#letting-the-headset-work-them-out-fenv-tool-tune).
+2. **Re-bake it** if it is an older, wrapped `.fenv` or a Meta `.apk`: `fenv-tool upgrade <file>.fenv`, or open and
+   save it in a current Studio. Baked homes are much lighter.
+3. **Lower the settings** in **Environments > Settings**:
+   - Resolution to Auto, or a lower fixed value.
+   - Foveated rendering to Eye tracked, and Foveation strength up (Medium or Strong).
+   - Anti-aliasing to 2x.
+   - As a last resort, Frame rate to Half.
+4. **Let it cool.** A hot headset is slower. Keep **Keep cool** on (86° is the default).
+5. **Find the costly part** with the Debug page (GPU cost view, Costliest meshes, Leave out). In Studio you can then
+   hide or delete that object, or turn on **File > Leave Out What Can't Be Seen** before saving.
+
+Other programs running on the headset share its GPU too.
+
+## Frame Studio's own frame pacing
+
+Studio tries not to use your computer more than it needs to:
+
+- It draws at your display's refresh rate while its window has focus, and at 30 fps when it doesn't.
+- When nothing changes (no input for a second and nothing moving by itself), it stops drawing and waits for input.
+  Playing animations, loading and saving keep it drawing.
+- **Edit > Settings...** under "This PC (Frame Studio)" has Viewport resolution, Anti-aliasing, Texture limit and
+  Texture filtering for big homes on slower computers.
+
+Two environment variables help when measuring:
+
+| Variable | Effect |
+|---|---|
+| `FS_FPS=n` | Draw at `n` frames a second instead of the display's rate. `0` means unlimited. |
+| `FS_STATS=1` | Every 5 seconds, write the frame rate and where a frame's time goes (3D view, GPU, UI, present) to `studio.log` |
+
+For example, on Linux: `FS_STATS=1 ./"Frame Studio"`. On Windows (Command Prompt): `set FS_STATS=1` then
+`"Frame Studio.exe"`.
@@ -0,0 +1,6 @@
+# Frame Studio guide
+
+This guide is being written. It will walk through Frame Studio's window: the editor layout with its docked panels,
+the tools for moving, hiding and deleting objects, shaping the walkable area, adding seats, sounds and a picture, and
+the world settings. Until it is ready, [getting-started.md](getting-started.md) covers a first walkthrough by menu
+name, and **Help > Controls** (F1) in Studio lists every shortcut.
@@ -0,0 +1,155 @@
+# Troubleshooting
+
+Find your symptom in the table, then read the matching section below for details. Logs are described at the end.
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Studio won't start, or says "Couldn't start Vulkan on this GPU" | No Vulkan 1.2 driver | Update your graphics driver. See [Studio won't start](#studio-wont-start). |
+| Studio won't start on a Mac | MoltenVK missing, or the app is blocked | Right-click > Open. Use the release build, which has MoltenVK inside. |
+| Windows says "Windows protected your PC" | The program is not signed | **More info > Run anyway** |
+| The 3D view is blank or black | Nothing open, still loading, or everything hidden | See [Blank or black view](#blank-or-black-view) |
+| Open and save dialogs don't appear (Linux) | No dialog helper installed | Install `zenity` or `kdialog` |
+| "Can't reach the headset" / "Can't reach the Frame" | SSH can't connect or needs a password | See [Can't reach the headset](#cant-reach-the-headset) |
+| Install failed | Something on the headset | Read the install output. See [Install failed](#install-failed). |
+| SteamVR shows its own environment again | Frame Home stopped, or turned off | See [SteamVR's environment is back](#steamvrs-environment-is-back) |
+| The home stutters in the headset | Too heavy for the settings | Tune it. See [performance.md](performance.md#when-a-home-stutters). |
+| A new environment has no picture in the panel | Thumbnails are made only while you're not looking at Frame Home | Wait, or run a game for a while |
+| A large home fails to open in a 32-bit build | 32-bit programs have at most 4 GB | Use a 64-bit build |
+
+## Studio won't start
+
+Studio needs a GPU with Vulkan 1.2.
+
+- **Windows and Linux:** install the current driver from NVIDIA, AMD or Intel (on Linux, your distribution's Mesa
+  Vulkan drivers, often `mesa-vulkan-drivers`, or NVIDIA's driver). Old or very basic GPUs may not have Vulkan 1.2.
+- **macOS:** Vulkan runs on Metal through MoltenVK. The release builds carry it inside the app. If you built the app
+  yourself without MoltenVK, see [building.md](building.md#macos-prerequisites). The first time, right-click the app
+  and choose **Open** (the app is not signed).
+- **Linux:** Studio needs an X11 desktop or XWayland. Start it from a terminal to see whether it starts at all, then
+  look at `studio.log`.
+
+If Studio starts but says it couldn't start Vulkan, the message names the `studio.log` file. Its last lines say why.
+
+## Blank or black view
+
+- With nothing open, Studio shows its start screen. Open a home with **File > Open Home...**.
+- A big home takes a while to load; textures arrive after the shapes.
+- Check that things aren't hidden: **View > Show Everything**, and **Edit > Unhide All** (Alt+H). **Show Only
+  Selected** (I) hides everything else; press I or Esc to show everything again.
+- Make sure **Debug** is set to **Normal** and nothing is ticked under **Debug > Leave Out**.
+- Use **View > Frame All** (Home key) to bring the whole home into view.
+
+## Dialogs don't appear on Linux
+
+Studio's open and save dialogs use `zenity` or `kdialog`. Install one:
+
+```sh
+sudo apt install zenity      # Debian, Ubuntu
+sudo dnf install zenity      # Fedora
+```
+
+Meanwhile you can drop files onto the Studio window to open them.
+
+## Can't reach the headset
+
+Studio and the installers use SSH. Test it yourself in a terminal:
+
+```sh
+ssh frame
+```
+
+(or `ssh steamos@<address>` if you don't use the name `frame`).
+
+| What you see | Fix |
+|---|---|
+| "Could not resolve hostname frame" | The `frame` entry is missing from your SSH config, or you didn't use it. See [headset-setup.md](headset-setup.md#5-add-a-frame-entry-to-your-ssh-config). Or use the IP address. |
+| "Connection timed out" or "No route to host" | Wrong address, the headset is off or asleep, or on another network. Check the address in the headset's network settings. |
+| "Connection refused" | SSH is not on in the headset's developer settings |
+| It asks for a password | Fine for the stand-alone installers. **Studio needs a key**: it never types a password. Set one up: [headset-setup.md](headset-setup.md#4-set-up-an-ssh-key). |
+| "Permission denied (publickey...)" | The key isn't on the headset, or the `IdentityFile` line points at the wrong file |
+| "Host key verification failed" | The headset's key changed (for example after a reset). Remove the old entry: `ssh-keygen -R <address>` (and `ssh-keygen -R frame`), then connect again and answer `yes`. |
+| Windows: "ssh is not recognized", or Studio says "install OpenSSH or Git for Windows" | Turn on **OpenSSH Client** in **Settings > Apps > Optional features**, or install Git for Windows |
+| "... isn't a Steam Frame" | The address points at another computer |
+
+In Studio, the address is the **Headset** field in **Frame > Install on Steam Frame...**. Studio remembers it.
+
+## Install failed
+
+The installers print each step. The last lines say what went wrong. In Studio, the message shows in the Install
+window.
+
+| Message | Meaning |
+|---|---|
+| "the headset files are missing" | The `frame` folder (Studio) or `payload` folder (installer) is not beside the program. Unpack the whole download again. |
+| "Frame Home can't run on this headset: ..." | The programs don't fit this headset's system. Nothing was changed. Use a newer release. |
+| "SteamVR refused the Environments panel" | SteamVR would not register the panel. Restart SteamVR and install again. |
+| "couldn't register with SteamVR" | SteamVR's config files could not be written or read. The message names the file. |
+| "Copying ... failed" | The network dropped, or the headset is full. Check free space with `ssh frame df -h ~`. |
+
+If it still fails, look at the logs (below) and try installing on the headset itself
+([install-frame-home.md](install-frame-home.md#way-3-directly-on-the-headset)).
+
+## SteamVR's environment is back
+
+Frame Home steps aside and SteamVR's own environment shows whenever Frame Home isn't sending pictures. Check, in this
+order:
+
+1. **Open the Environments panel** in the Steam menu. The top right says whether Frame Home is running:
+   - "Frame Home isn't running": press **Start Frame Home**.
+   - "Off: it failed to start twice": the layer turned itself off after two failed starts. Press **Turn Frame Home
+     On**.
+   - The panel isn't in the Steam menu at all: install again (the panel starts Frame Home).
+2. **Check the off switch.** If `~/frame-home/layer/off` exists, Frame Home is off on purpose:
+
+   ```sh
+   ssh frame ls ~/frame-home/layer/
+   ```
+
+   Delete `off` (`ssh frame rm ~/frame-home/layer/off`), or use the panel's button.
+3. **Look at the logs** (below). `layer.log` says whether the layer loaded and why it stepped aside;
+   `frame-home.log` says whether Frame Home started and loaded the home.
+4. **Install again.** It replaces the programs and the layer, clears the off switch and restarts what's needed.
+
+If the headset's environment breaks after an update, create the off file to get SteamVR's environment back at once:
+`ssh frame touch ~/frame-home/layer/off`. See [install-frame-home.md](install-frame-home.md#the-emergency-off-switch).
+
+## Stutter
+
+See [performance.md](performance.md#when-a-home-stutters). In short: tune the home (`fenv-tool tune` or **Calculate
+Best Settings**), make sure it's a baked `.fenv`, and lower Resolution or raise Foveation strength.
+
+## Where the logs are
+
+| Log | Where | What's in it |
+|---|---|---|
+| `studio.log` | Studio's data folder: `%APPDATA%\FrameStudio` (Windows), `~/.local/share/FrameStudio` (Linux), `~/Library/Application Support/FrameStudio` (macOS) | Everything Studio reports. Started fresh each time Studio starts. |
+| `frame-home.log` | `~/frame-home/logs/` on the headset | Frame Home: start, loading, settings, problems |
+| `report.txt` | `~/frame-home/logs/` on the headset | The current environment's report (what it costs, what's wrong) |
+| `layer.log` | `~/frame-home/layer/` on the headset | The compositor layer: loaded, showing, or stepping aside and why |
+
+To read a headset log from your computer:
+
+```sh
+ssh frame tail -50 frame-home/logs/frame-home.log
+ssh frame tail -50 frame-home/layer/layer.log
+```
+
+When you ask for help, include the end of the relevant log. Logs contain file names and paths from your computer or
+headset; look through them before posting them publicly.
+
+## Self-test (for diagnosing)
+
+Studio has a self-test. It opens a home, drives the real interface (selecting, moving, rotating, scaling, making
+surfaces, undo, saving) and checks the results. It is meant for finding problems, not for everyday use. It doesn't
+change your home's edits or My Environments.
+
+Run it with a Meta home or a `.fenv`:
+
+| System | Command |
+|---|---|
+| Windows | `"Frame Studio.exe" --selftest C:\path\to\home.apk` |
+| Linux | `./"Frame Studio" --selftest /path/to/home.apk` |
+| macOS | `"Frame Studio.app/Contents/MacOS/Frame Studio" --selftest /path/to/home.apk` |
+
+Studio runs the test and quits. The report is `selftest/report.txt` in Studio's data folder, with screenshots beside
+it.
@@ -0,0 +1,171 @@
+# Using Frame Home on the headset
+
+Once Frame Home is installed (see [install-frame-home.md](install-frame-home.md)), your home is the Steam Frame's
+environment. It shows when no game is running, behind the Steam menu, and while games load.
+
+## The Environments panel
+
+Frame Home adds a panel called **Environments** to the Steam menu. It starts with SteamVR on its own.
+
+1. Open the Steam menu.
+2. Choose **Environments** in the menu's bar.
+3. Point at the panel with a controller and click.
+
+The panel has three pages: **Environments**, **Settings** and **Debug**. Its top right shows whether Frame Home is
+running, with a button:
+
+| The panel says | The button | What it does |
+|---|---|---|
+| Frame Home is running | Restart Frame Home | Reloads the home from its file |
+| Frame Home isn't running | Start Frame Home | Starts it now |
+| Off: it failed to start twice | Turn Frame Home On | Clears the off switch and starts it |
+
+### Choosing an environment
+
+The **Environments** page shows a card for every environment on the headset, with its name, its kind and a
+thumbnail. The one you are in says "Showing now".
+
+- **Click a card** to switch to it. Frame Home changes the environment live; you don't need to restart anything.
+- **Delete** a card with its delete button. The panel asks first ("Delete ...?"). Deleting removes the file from the
+  headset, its thumbnail and its unpacked copy.
+
+The kinds you may see:
+
+| Kind | Meaning |
+|---|---|
+| Frame environment | A `.fenv` file |
+| Frame environment, footprint + vista | A `.fenv` holding a room and the view outside it |
+| Meta home | A Meta Quest home `.apk` |
+| Meta home, footprint only / vista only | Half of a Meta home pair |
+| Footprint + Vista | Two `.apk` files listed as a pair (see below) |
+
+### From a terminal
+
+Over SSH (`ssh frame`) you can do the same with the panel's program:
+
+```sh
+~/frame-home/bin/frame-switcher --list          # the environments; the current one is marked with *
+~/frame-home/bin/frame-switcher --set 3         # switch, by number from --list or by file name
+~/frame-home/bin/frame-switcher --delete NAME   # delete one, like the panel's delete button
+```
+
+## Adding environments
+
+Every environment lives in `~/frame-home/envs` on the headset. Ways to put one there:
+
+- From Frame Studio: **Frame > Send to Frame** (the open home), or **Frame > Install on Steam Frame...** (any
+  `.fenv` files).
+- With the stand-alone installer: drop `.fenv` files on `Install Frame Home.bat`, or list them after
+  `install-frame-home.sh`. See [install-frame-home.md](install-frame-home.md).
+- By hand: copy the file into `~/frame-home/envs`, for example `scp my-home.fenv frame:frame-home/envs/`.
+
+The panel notices new files by itself. Then, in the background:
+
+- **Each new `.fenv` is unpacked ahead of time.** A big one takes about ten seconds. After that, switching to it is
+  as quick as switching back to one you have used before.
+- **Thumbnails are made while nobody is looking at Frame Home**, for example while a game is running. Making one
+  loads and draws the whole home, which would make the home you are standing in stutter. So a new environment can
+  show without a picture for a while.
+
+Meta home `.apk` files work too, but they load more slowly than a `.fenv`. Studio or `fenv-tool` converts them (see
+[environments-and-fenv.md](environments-and-fenv.md)). To show a room `.apk` and its vista `.apk` together, add a
+line with both file names to `~/frame-home/pairs.txt`:
+
+```
+haven2025.apk calming.apk
+```
+
+## Moving around
+
+Frame Home moves you the way Meta's homes do. You start at the home's spawn point, its floor on your real floor.
+
+| Control | What it does |
+|---|---|
+| Left stick | Walk in the direction you push it, relative to where you look. A light push strolls. Walls stop you and you slide along them; ramps and steps are followed. |
+| Right stick left / right | Turn: snap turns (30, 45 or 90 degrees) or smooth turning, as set in Settings |
+| Right stick forward | Aim a teleport arc from your right hand. A marker shows where you'll land. Let go to go there. |
+| Point at a seat, pull the trigger | Sit in it. Seats near you show a faint marker that lights up when you point at it. |
+| Walk, teleport or step away while seated | Stand up again |
+
+More details:
+
+- The teleport arc stops at the first thing it meets. A floor or a seat is a landing; a wall, a ceiling or the side
+  of furniture is not, unless it is low, then you land at its foot.
+- Landing near a teleport hotspot snaps you onto it.
+- Seated, you can still turn, but you stay put.
+- Falling is real. If you fall further than the home's limit, you are put back at the spawn point.
+- Some homes have gravity zones (walls you can walk up, small planets).
+- **With the Steam menu open, the controllers belong to the menu.** Nothing moves you until you close it.
+
+## Settings
+
+The **Settings** page has three groups. Frame Studio shows the same settings under **Edit > Settings...**, in the
+"Steam Frame (Frame Home)" part, so you can change them from your computer too.
+
+Settings are stored in `~/frame-home/settings.json` on the headset. Frame Home reads it again whenever it changes.
+
+### Movement (applies right away)
+
+| Setting | Choices | Default | What it does |
+|---|---|---|---|
+| Walking | Off, Smooth | Smooth | Left stick walks you smoothly. Off: teleport only. |
+| Teleport | Off, Instant, Slide | Instant | Right stick forward, aim, let go. Instant blinks you there; Slide glides there. |
+| Turning | Snap, Smooth | Snap | What the right stick does left and right |
+| Snap turn angle | 30°, 45°, 90° | 30° | How far each snap turn goes |
+| Walking speed | Slow, Normal, Fast | Normal | How fast smooth walking moves you (1.4, 2 and 3 m/s) |
+| Comfort vignette | Off, Gentle, Strong | Off | Darkens the edges of view while the stick moves or turns you. Helps if smooth walking makes you queasy. |
+| Seat markers | Shown, Hidden | Shown | Markers on the seats near you. Hidden, pointing at a seat still finds it. |
+
+### Environment (applies right away)
+
+| Setting | Choices | Default | What it does |
+|---|---|---|---|
+| Volume | Off, 25%, 50%, 75%, 100% | 100% | All of the environment's sound |
+| Animations | Play, Hold still | Play | Hold still stops the environment's moving parts; animated environments then cost less. |
+
+### Graphics
+
+The group's heading shows how Frame Home is doing right now: the GPU time a frame takes out of the time it has, the
+size drawn per eye and its resolution, and whether eye tracking is used. For example: "6.1 of 8.3 ms a frame, ... per
+eye (140%), eye tracking on". If it starts with "Too slow, lower Resolution", frames are late and the home stutters.
+
+| Setting | Choices | Default | What it does |
+|---|---|---|---|
+| Resolution | Auto, 80%, 100%, 120%, 140% | Auto | Share of SteamVR's recommended size per eye. Auto moves between 70% and 150% to keep every frame on time, sharper whenever the home is light enough. |
+| Frame rate | Full, Half | Full | Half draws the environment every other frame and turns it with your head in between, as Meta's home does: each frame gets twice the GPU time. |
+| Anti-aliasing | Off, 2x, 4x | 4x | Smooths jagged edges. 4x looks best; lower is faster. |
+| Texture filtering | 4x, 8x, 16x | 8x | Keeps floors and walls sharp at an angle. Higher looks better. |
+| Foveated rendering | Off, Fixed, Eye tracked | Eye tracked | Full detail where you look, coarser toward the edges. The time this frees goes to resolution (with Auto). Fixed keeps the sharp area at the lens centre; Eye tracked follows your gaze. |
+| Foveation strength | Gentle, Medium, Strong | Medium | How quickly detail falls off away from where you look |
+| Keep cool | Off, 80°, 86°, 90° | 86° | Above this temperature (°C), the edges of view give up a little detail at a time until the headset cools. Where you look stays sharp. A hot headset slows its GPU. |
+| Behind the Steam menu | Half rate, Full rate | Full rate | With the menu open, the environment is only a backdrop. Half rate leaves more GPU to the menu and its apps. |
+
+Anti-aliasing, texture filtering and turning foveation on or off restart Frame Home. That takes a few seconds.
+The others apply at once.
+
+With eye-tracked foveation, the heading says "eye tracking waiting for your eyes" until the headset sees your gaze.
+
+**Per-environment settings.** An environment can carry its own resolution, foveation strength, anti-aliasing and
+frame rate, tuned for that home. While you are in it, those win over the settings above. See
+[environments-and-fenv.md](environments-and-fenv.md#per-world-settings) and [performance.md](performance.md).
+
+## The Debug page
+
+The Debug page is for finding out why a home looks or runs wrong. Its settings are not kept: they switch off when
+Frame Home restarts.
+
+| Item | What it does |
+|---|---|
+| View | Normal, Wireframe (every triangle edge), Meshes (each in its own colour), GPU cost (green is cheap, red is costly), Overdraw (bright where surfaces pile up) |
+| World layer | Shows where you can walk (green), surfaces and colliders, spawns, seats, wall spots and gravity zones |
+| See-through surfaces | Leave out glass, water, glow and fog, to see whether they're what's slow |
+| Cut-out surfaces | Leave out leaves, grass and fences |
+| Sky | Leave out the sky |
+| Costliest meshes | The meshes that cost the GPU most, with their time |
+| This environment | The environment's report: problems found, if any (also in `~/frame-home/logs/report.txt`) |
+| Save a Picture | Saves what you see to `~/frame-home/logs` |
+| Turn Debug Views Off | Back to normal |
+
+The GPU cost view times every draw, which makes the GPU a little slower while it is on.
+
+Studio can show and change the same page from your computer: **Debug > Headset Debug...**.