@ssheleg/xr-dev 0.3.0

package/plugins/xr-dev/skills/quest-native/references/manifest-and-gradle.md

@@ -0,0 +1,111 @@
+# The manifest and Gradle contract, both halves
+
+**Read this when** writing or reviewing an `AndroidManifest.xml` or `build.gradle`
+for a native Quest app, or when a build is rejected for `VRC.Quest.Packaging.1`
+or `.4`.
+
+Sources: [native manifest](https://developers.meta.com/horizon/documentation/native/android/mobile-native-manifest/)
+(page dated 2026-09-01) and [release manifest](https://developers.meta.com/horizon/resources/publish-mobile-manifest/)
+(2026-08-31), rechecked 2026-09-21. **Development and release requirements are two different documents.**
+
+## Contents
+
+- Development manifest
+- Release manifest (the one review enforces)
+- SDK levels, with the 2026 rule
+- Gradle and the OpenXR loader
+- Supported devices and compatibility mode
+
+## Development manifest
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+          package="<packagename>">
+  <uses-feature android:name="android.hardware.vr.headtracking"
+                android:required="true" android:version="1" />
+  <application android:label="@string/app_name"
+               android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen">
+    <activity android:name="android.app.NativeActivity"
+              android:screenOrientation="landscape"
+              android:configChanges="density|keyboard|keyboardHidden|navigation|orientation|screenLayout|screenSize|uiMode"
+              android:excludeFromRecents="false">
+      <intent-filter>
+        <action   android:name="android.intent.action.MAIN" />
+        <category android:name="android.intent.category.LAUNCHER" />
+        <category android:name="com.oculus.intent.category.VR" />
+      </intent-filter>
+    </activity>
+  </application>
+</manifest>
+```
+
+- `android.hardware.vr.headtracking` `required="true"` is also what v2 signing
+  and store review expect from an immersive app.
+- **Never** add `android:noHistory`.
+- Landscape and the black fullscreen theme are comfort requirements during app
+  transitions, not style.
+
+## Release manifest — the delta
+
+| Element | Release requirement |
+|---|---|
+| `android:debuggable` | `false` or absent — a release build |
+| `installLocation` | `auto` (or `0`); anything else needs store-team approval |
+| `android:label` | the app's name, **unique on the platform** |
+| `android.hardware.vr.headtracking` | `required="true"` for immersive; omitted or `false` for a 2D panel app |
+| `android:excludeFromRecents` | `true` in the release launch activity |
+| intent filter | `MAIN` + `LAUNCHER`; current Meta OpenXR release example adds `com.oculus.intent.category.VR` |
+| `com.oculus.supportedDevices` | `quest2\|questpro\|quest3\|quest3s` as a `meta-data` element in `application` |
+
+The snippet is a manifest segment, not a complete generated project. Verify
+merged APK output and preserve additional categories required by the chosen
+SDK/cross-runtime target; the Meta category is not a universal OpenXR spec rule.
+
+Non-conformance fails `VRC.Quest.Packaging.1` and/or `.4` — while still
+installing happily when sideloaded, which is what makes it a late surprise.
+
+## SDK levels, with the 2026 rule
+
+Recommended for in-lifecycle devices (Quest 2, Quest Pro, Quest 3 family):
+
+| | minSdkVersion | targetSdkVersion | compileSdkVersion |
+|---|---|---|---|
+| Recommended | 32 | 34 | 34 |
+| Legal range | 29–34 | 32–34 immersive, 32–36 for 2D | ≥ targetSdkVersion |
+
+**Apps created since 1 March 2026 must set `targetSdkVersion` to 34.** Horizon
+OS has been Android 14 (SDK 34) since HzOS v76 in April 2025; older releases
+were Android 12 (SDK 32). To gate on a Horizon OS version rather than an Android
+one, use "Requiring Minimum OS Versions"
+(`documentation/native/min-os-versions`), not `minSdkVersion`.
+
+`maxSdkVersion` is supported by Android and **not recommended** on Quest.
+
+## Gradle and the OpenXR loader
+
+```gradle
+android {
+  compileSdk 34
+  defaultConfig { minSdk 32; targetSdk 34; ndk { abiFilters 'arm64-v8a' } }
+  buildFeatures { prefab true }          // required for the loader's prefab
+  externalNativeBuild { cmake { cppFlags '-std=c++20' } }
+}
+dependencies {
+  implementation 'org.khronos.openxr:openxr_loader_for_android:<version>'
+}
+```
+
+- Only `arm64-v8a` ships: `VRC.Quest.Packaging.6` requires 64-bit binaries.
+- **Loader below 1.0.34 crashes**; apps on the Khronos loader also crash on
+  Horizon OS older than v62, and non-Quest-1 users below v62 never see the
+  update in the Store.
+- Pin the loader version in whatever lock file the project keeps **and** in
+  `build.gradle`, then check they agree — a drifted lock is a release note
+  describing a build that does not exist.
+
+## Supported devices and compatibility mode
+
+A headset whose model is absent from `com.oculus.supportedDevices` runs the app
+in **compatibility mode** and reports itself as a previous generation. That is a
+safety net, not a plan: query capabilities (extension enumeration) rather than
+device models, and add new identifiers as they appear.

package/plugins/xr-dev/skills/quest-native/references/mixed-reality.md

@@ -0,0 +1,46 @@
+# Mixed reality capabilities and lifecycle
+
+**Read this when** implementing passthrough, room understanding, anchors, hands/body/eyes, shared physical space, camera processing or AI input on Quest.
+
+Sources checked 2026-09-21. Select a feature by the app's need and runtime support, not by “all SDK features.” The acceptance checks below are recommended project tests, not a claim that every row is a Store rule.
+
+## Capability contract
+
+For each feature record: API/SDK and source date; required versus optional; runtime support; manifest declaration; current permission grant; account/device restrictions; data lifetime; fallback; test scene and evidence. An available extension and a granted Android permission are separate facts. Inspect valid/tracked pose flags before using coordinates.
+
+| Feature | Choose it for | Failure path to test |
+|---|---|---|
+| Displayed passthrough | Showing the real world behind/through virtual content | Unavailable session/mode, focus loss, transition back to VR; do not assume access to camera pixels |
+| Scene/MRUK room model | Semantic surfaces, placement, generated room gameplay | Permission denied, no Space Setup, incomplete scan, changed room, rescan and unsupported semantics |
+| Environment depth | Occlusion against the physical world | Unsupported/invalid depth; fall back visually, never treat it as authoritative collision/safety geometry |
+| Spatial anchors | Stable real-world placement and later localization | Save/share/load failure, localization timeout, changed room, deleted anchor |
+| Shared anchors/colocation | Aligning multiple users' coordinate systems | Anchor alignment success with network-state failure and vice versa; stale alignment and host loss |
+| Hands/controllers | Interaction, gestures and haptics | Switching input source, tracking quality, occluded hands, controller disconnect, reserved system gesture |
+| Body/face/eye data | Supported avatar/interaction requirements | Capability unavailable or consent refused; retain a usable avatar/input alternative |
+| Raw passthrough camera | CV/ML, object recognition, QR/reference acquisition | Missing grant/device/account support, camera busy, invalid frame, changed resolution, resume after pause |
+
+Primary maps: [passthrough](https://developers.meta.com/horizon/essentials/horizon-os-passthrough/), [spatial data permission](https://developers.meta.com/horizon/documentation/unity/unity-spatial-data-perm/), [MRUK features](https://developers.meta.com/horizon/documentation/unreal/unreal-mr-utility-kit-features/), [Shared Spatial Anchors sample](https://github.com/oculus-samples/Unity-SharedSpatialAnchors), [native feature samples](https://developers.meta.com/horizon/documentation/native/native-openxr-sdk-sample/).
+
+## Camera facts that commonly get mixed together
+
+Displayed passthrough, raw forward camera frames, environment depth, a saved scene mesh and MediaProjection/casting are distinct products. Their images, coordinate frames, permissions and availability are not interchangeable. An image that looks like the headset view may omit UI or cover a different field of view.
+
+The [camera overview](https://developers.meta.com/horizon/documentation/spatial-sdk/spatial-sdk-pca-overview/) describes Quest 3/3S, Horizon OS v74+, Camera2-based access and either CAMERA or HEADSET_CAMERA. The [native camera page](https://developers.meta.com/horizon/documentation/native/android/pca-native-documentation/) also says both permissions are needed, while [MRUK's component](https://developers.meta.com/horizon/reference/mruk/v85/class_meta_x_r_passthrough_camera_access/) names HEADSET_CAMERA. Treat this as a documented discrepancy: use the chosen component's versioned requirements, inspect the merged manifest, request the minimum supported grant and verify a fresh install. Record unresolved conflicts; do not silently broaden permissions.
+
+Query camera identity, supported output sizes and calibration metadata; never hardcode camera index, resolution or the assumption that it covers the user's full view. Keep capture timestamps and convert through the correct camera/head/world transforms before placing content. Close images, sessions, readers and GPU resources according to the API lifecycle; bound queues and drop stale frames rather than accumulating latency.
+
+The overview states that the Passthrough Camera API is unsupported in XR Simulator. It also warns that parental restrictions may not be applied to an MQDH-installed app: developer sideloading cannot certify the release-channel age/account path. Validate that path separately. The [public-release announcement](https://developers.meta.com/horizon/blog/new-era-mixed-reality-passthrough-camera-api-machine-learning-computer-vision/) permits Store publication; do not repeat the obsolete blanket claim that camera apps cannot ship.
+
+Camera data is Device User Data under the linked Meta policy. Explain capture/off-device use, minimize retention and redact diagnostics; apply the product's consent/privacy flow. Permission to render passthrough is not permission to upload room images to an AI service. Test denial/revocation without stranding the user.
+
+## Shared physical play is more than anchors
+
+Keep local tracking space, shared world transform and authoritative game simulation distinct. Share anchor identities/alignment under the chosen SDK; use an actual networking solution for object state, ownership, prediction/interpolation and reconnection. [Group Presence](https://developers.meta.com/horizon/documentation/native/ps-group-presence-overview/) reports destinations/joinability; it does not synchronize physics. Exercise invite/deep-link joining when the app is cold, active or already in another session.
+
+Test two real accounts and devices in representative rooms, including non-joinable/private states. Bound avatar/network updates independently of the render loop. Include mute/block/report and data handling when the product has social/UGC features, under current platform policy.
+
+## Comfort and interaction review
+
+Consume the project's scenario set. Cover seated/standing reach, left/right-handed input, snap/smooth movement preferences, controller/hand alternatives, text angular size and distance, subtitles and non-audio feedback. World-lock stable content; use head-locked content deliberately. Do not force camera motion or hide tracking failure behind a seemingly stable world. Respect system focus/gestures and the OS boundary.
+
+Use [Meta design guidance](https://developers.meta.com/horizon/design/) and a human headset review for comfort. Automated input, screenshots and static reach calculations cannot certify comfort or environmental safety.

package/plugins/xr-dev/skills/quest-native/references/project-playbook.md

@@ -0,0 +1,56 @@
+# Project discovery, implementation and audit
+
+**Read this when** starting a Quest project, entering an unfamiliar repository, planning a vertical slice or deciding which engine/platform procedure to use.
+
+Checked 2026-09-21. Procedures below are this pack's engineering contract; linked platform behavior comes from the named primary sources. A source audit is useful without an engine, MCP or headset; label unavailable checks NOT-RUN.
+
+## Establish the target before choosing libraries
+
+Record in the consuming project's existing architecture/evidence location:
+
+| Field | Inspect or decide |
+|---|---|
+| Deliverable | Standalone Horizon OS APK, PC OpenXR executable over Link, browser WebXR, Android panel/hybrid, or a separate Horizon Worlds experience |
+| Source | Commit, dirty changes, project files, build scripts, asset import configuration and dependency locks |
+| Engine | Native/Spatial/Unity/Unreal/Godot version, renderer, plugin/SDK versions and matching build/export tools |
+| Runtime | Device and Horizon OS, OpenXR runtime/loader, refresh rate, supported capabilities, permissions and account state |
+| Product | VR/MR mode, seated/standing/roomscale, input options, offline behavior, save/account/network needs |
+| Delivery | Package ID, signing owner, app ID/creation date, channel, supported devices and asset target profile |
+
+Do not use “Oculus” alone as a build target. Legacy Rift/PC or Go tutorials, standalone Quest and Meta's current Android surface have different rendering, lifecycle and distribution paths. Link testing is not a standalone APK test. Android API level is not a Horizon OS feature version.
+
+## Engine handoff
+
+| Evidence | Procedure and primary entry |
+|---|---|
+| CMake/NDK/NativeActivity/OpenXR | This skill; [Meta samples](https://github.com/meta-quest/Meta-OpenXR-SDK) and [Khronos SDK source](https://github.com/KhronosGroup/OpenXR-SDK-Source) |
+| Kotlin + `com.meta.spatial` | `quest-spatial`; [Spatial samples](https://github.com/meta-quest/Meta-Spatial-SDK-Samples) |
+| Unity ProjectSettings/Packages/Assets | Discover available `hz-unity-*` skills; otherwise [Unity getting started](https://developers.meta.com/horizon/documentation/unity/unity-tutorial-hello-vr/), locked packages, scene/prefab inspection, EditMode/PlayMode and Android build |
+| Unreal `.uproject`/Plugins/Source | [Meta compatibility matrix](https://developers.meta.com/horizon/documentation/unreal/unreal-compatibility-matrix/); choose Epic+plugin versus Meta fork deliberately; inspect assets/Blueprint/C++, cook/package and device render path |
+| Godot `project.godot`/scenes/resources | [Godot XR setup](https://docs.godotengine.org/en/stable/tutorials/xr/setting_up_xr.html) and [Android export](https://docs.godotengine.org/en/stable/tutorials/xr/deploying_to_android.html); match engine/templates/vendor extension and renderer |
+| Browser application | `quest-webxr`; native OpenXR extensions are not browser APIs |
+
+Use engine companions if installed; never invent their tools. This platform skill supplies requirements and evidence, not Unity APIs inside a C++ project. For Godot, the setup/deployment pages currently disagree on Mobile versus Compatibility recommendations for Quest. Pin a release and test the required renderer/extensions on target hardware before choosing. Native engine compilation is needed only for an actual engine modification or custom template requirement.
+
+## Build a representative vertical slice
+
+1. Preserve the existing project. Reproduce its current build before scaffolding missing pieces.
+2. Implement launch → tracked view/input → one real interaction → save/resume → exit. Add one MR capability only if it is required by the brief.
+3. Import one representative source asset; check scale, axes, pivot, collision, material extensions, texture formats, skin weights and animation. Keep the editable master and import settings.
+4. Keep gameplay simulation separate from rendering and asynchronous I/O. Budget physics, AI, navigation, animation, audio and asset loading as well as draw work. Avoid per-frame allocations and unbounded event subscriptions.
+5. Exercise focus loss, permission refusal, tracking loss, input-source changes, background/resume and a second entitled account where applicable. Reset global/static state between sessions.
+6. Produce the actual target build, install/cold-start it and capture representative sustained behavior. A successful editor, simulator or headless import check proves only that surface.
+
+## Audit output
+
+For each finding record severity, source location, observed/expected behavior, reproduction, affected targets, bounded fix and verification. Separate measured defect, source-risk, documented upstream limitation and NOT-RUN. Do not award a whole-project score from file names or a single screenshot.
+
+Suggested evidence files, only if the project has no equivalent: `docs/xr/target.md`, `docs/xr/capabilities.json`, `docs/xr/verification.md`. Do not create a competing registry when the project's existing plan/scenario/evidence owners already hold these facts.
+
+## Runtime AI is a separate latency and data path
+
+Generation servers such as [vLLM-Omni](https://github.com/vllm-project/vllm-omni) can supply prepared speech/images/video or asynchronous NPC services. They do not provide collision-ready geometry or a replacement for the OpenXR frame loop. Route production assets through the configured asset/job owner, such as Asset Foundry when present; use delivered manifests and target gates.
+
+Keep requests asynchronous, bound the queue and payload, cancel/ignore obsolete results using scene/session IDs, and cache approved fallbacks. Continue tracking/rendering and essential interactions when offline. Benchmark network/queue/inference/audio-playout separately from frame time; no universal latency claim follows from “streaming.” For camera/microphone input, apply the MR permission/data contract before any off-device transfer.
+
+For small on-device CV, evaluate [Meta's Unity Inference Engine sample](https://developers.meta.com/horizon/documentation/unity/unity-pca-sentis/) against the exact model/operators and headset GPU budget. A model loading successfully does not prove it coexists with 90 Hz rendering.

package/plugins/xr-dev/skills/quest-perf/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: quest-perf
+description: >-
+  Use when a Meta Quest / Horizon OS app misses frames, judders, overheats or
+  must be profiled — the frame budget per refresh rate, logcat stats, the GPU%
+  number that lies during frame drops, Dynamic Resolution, foveation,
+  Application SpaceWarp, and capturing with OVR Metrics, Perfetto, simpleperf or
+  RenderDoc. Engine-independent. Triggers - "dropped frames" / "просадка кадров", "judder" /
+  "джаддер", "Quest performance" / "производительность на Quest", "GPU bound" /
+  "упёрлись в GPU", "profile the headset" / "профилировать шлем", "perfetto trace"
+  / "трейс perfetto", "simpleperf", "RenderDoc", "OVR Metrics", "stale frames",
+  "SpaceWarp", "foveated rendering" / "фовеальный рендеринг", "72 vs 90 Hz",
+  "app is hot" / "шлем греется". NOT for wiring the render loop itself
+  (quest-native), not for Store performance VRCs as a submission gate
+  (quest-store), and not for desktop or mobile-phone profiling.
+license: MIT
+compatibility: Any agent can read this workflow. Live source checks need network; build, device, profiling and Store actions need the named installed tools and accounts. Missing capabilities use the inline fallback and leave dependent checks unverified.
+metadata:
+  version: "0.3.0"
+---
+
+# Quest performance: the budget, the lie, and the capture
+
+Performance work on Horizon OS fails in one of two ways: optimising without a
+capture, or reading the capture wrong. This skill fixes the second first, because
+the most-quoted number on the platform — `GPU%` — is misleading exactly when it
+matters.
+
+For a whole-product roadmap or stage audit, use `quest-lifecycle`; a single technical task stays with this owner. If absent, identify the current stage, its evidence and the next prerequisite inline.
+
+Read `references/mobile-rendering.md` when choosing the render pipeline or investigating tile, render-pass, geometry, overdraw and asset costs.
+
+## The budget is a deadline, not a target
+
+| Refresh rate | Time per frame |
+|---|---|
+| 72 Hz | 13.9 ms |
+| 90 Hz | 11.1 ms |
+| 120 Hz | 8.3 ms |
+
+CPU, render-thread, GPU and compositor work form a pipeline and can overlap
+across frames. Compare the critical path and synchronization against the
+deadline; do not add independent CPU/GPU samples as a universal frame-time
+formula. Missed submissions may invoke reprojection, with visible artifacts
+that depend on motion, depth and the selected runtime path.
+
+## The GPU% lie, and the 50% threshold
+
+When an app drops to half rate the GPU finishes early and idles, so utilisation
+*falls* while the app is firmly GPU-bound.
+
+```text
+FPS=36/72  Stale=36  GPU%=0.65  App=18.05ms
+```
+
+- `FPS=36/72` — half rate: every frame shown twice.
+- `App=18.05ms` — the real per-frame GPU time, against a 13.9 ms budget.
+- `GPU%=0.65` — measured across the doubled 27.8 ms interval, which is why it
+  reads 65% while the app needs a **23% cut**, not the 35% "headroom" it implies.
+
+**Rule: read `App` in milliseconds against the refresh-rate budget. Only trust
+`GPU%` near saturation.** To climb back out of half rate, GPU work must fit one
+refresh interval — i.e. utilisation must fall **below ~50%** while at half rate.
+
+If `App` is inside budget and `Stale` remains non-zero, inspect CPU submission,
+synchronization and compositor timing in a trace. That symptom alone does not
+prove a CPU bottleneck. The worked half-rate example above assumes the stated
+metric definitions and no intentional SpaceWarp mode; verify both first.
+
+## Select a lever from the measured bottleneck
+
+Read `references/rendering-playbook.md` when choosing multiview, render scale,
+foveation, layers, assets, shaders or reprojection. It links each experiment to
+its prerequisites, visual failure cases and target-device evidence.
+
+1. **Dynamic Resolution** — tune render scale through the engine/SDK's supported
+   control path; verify actual behavior rather than assuming the OS enables it.
+2. **Foveation** — distinguish fixed from eye-tracked; test supported levels and
+   quality. A simple shader can cost more with FFR than without it.
+3. **Refresh rate** — request a rate the representative workload sustains; observe
+   actual runtime and thermal behavior rather than promising an automatic rate change.
+4. **Application SpaceWarp** — a supported depth/motion-vector integration with
+   artifact and latency tests, not an automatic rescue or guaranteed percentage gain.
+
+## Capture chain — what each tool answers
+
+| Question | Tool | How |
+|---|---|---|
+| Am I missing frames at all, and where | logcat VrApi stats (`FPS`, `Stale`, `App`, `GPU%`) | `metavr log` / `adb logcat` |
+| Live numbers inside the headset | OVR Metrics Tool (`ovrmetric` APK) | `metavr tools install ovrmetric`, then enable its overlay |
+| CPU vs GPU, thread timeline, stalls | Perfetto | `metavr` MCP `start_perfetto_capture` → `stop_perfetto_capture` → `analyze_trace`, or the CLI equivalents |
+| Which C/C++ functions burn the CPU | simpleperf | Android NDK's simpleperf against the running package |
+| Which draw call, shader or render stage burns the GPU | RenderDoc Meta fork | `metavr tools install renderdoc`; draw-call trace, render-stage trace, Vulkan shader stats |
+
+Meta ships task skills for two of these — `hz-perfetto-debug` and
+`hz-simpleperf-debug`, plus `hz-vr-debug` for general on-device debugging. When
+they are installed, this skill decides *what to measure* and they drive the tool.
+
+`references/capture-playbook.md` holds the exact sequences, including what to
+capture for a report that another agent can act on.
+
+## Method, so a second capture means something
+
+1. Reproduce on a **release build on a real headset**. A simulator run
+   (`xrsim`, `spatialsim`) checks supported simulated behavior, not headset performance.
+2. Note refresh rate and the resulting budget before looking at anything else.
+3. Capture with the app in the *worst* scene, not the menu.
+4. Change **one** thing; re-capture; compare `App` ms, not impressions.
+5. Record the pair (before/after `App`, `Stale`, scene, build id) in the
+   project's own notes — a performance claim with no capture is an opinion.
+
+## Gotchas that cost a debugging round
+
+- **A thermally throttled headset invalidates the comparison.** Long sessions
+  drift; let it cool or state the temperature state with the number.
+- **Dev-mode overlays and logging cost frames.** Measure with them off, then
+  turn them on only to read the numbers you cannot get otherwise.
+- **Counter semantics depend on capture/runtime mode.** Inspect timestamps and
+  reprojection state before interpreting a stale-frame count as dropped work
+  or pipeline latency.
+- **Draw calls are a CPU cost and fill is a GPU cost.** Cutting draw calls on a
+  fill-bound frame moves nothing, which is why the capture comes first.
+- **WebXR has its own counters** — draw-call metrics in the browser docs; see
+  `quest-webxr` before applying native advice to a web build.
+
+*Frame budgets, the 65%/18.05 ms worked example and the recovery mechanisms were
+read from `documentation/native/android/os-missed-frames.md` on 2026-09-20;
+re-verify with `metavr docs search "missed frames"`.*

package/plugins/xr-dev/skills/quest-perf/references/capture-playbook.md

@@ -0,0 +1,102 @@
+# Capture playbook — the exact sequences
+
+**Read this when** a performance problem needs evidence rather than an opinion,
+or when a capture has to be handed to another agent or another person.
+
+Commands verified against `metavr` 1.3.2.2.2 on 2026-09-20 (`metavr perf --help`
+and its subcommands). Every one of them needs a **connected headset**; a
+simulator answers behaviour questions only.
+
+## Contents
+
+- Step 0: the numbers before any tool
+- Perfetto through metavr
+- simpleperf: CPU hotspots and what is actually bound
+- RenderDoc: the GPU side
+- OVR Metrics Tool: live, in the headset
+- What a usable capture report contains
+
+## Step 0: the numbers before any tool
+
+```bash
+metavr device list                  # the headset is attached at all
+metavr device battery               # a throttling device invalidates the run
+metavr app launch <package>
+metavr log | grep -E 'FPS=|Stale=|App='
+```
+
+Read `App` (ms) against the refresh-rate budget, `Stale` against the refresh
+rate, and only then `GPU%`. The interpretation — including why `GPU%` reads low
+exactly when the app is GPU-bound — is in the skill body.
+
+## Perfetto through metavr
+
+```bash
+# one-shot, fixed duration
+metavr perf capture --mode vr --duration 10000 --app <package> -o before
+
+# or bracket an interaction by hand
+metavr perf start --mode custom --gpu-render-stage --cpu-scheduling --xr-runtime
+#   … reproduce the worst scene in the headset …
+metavr perf stop
+
+metavr perf analyze-trace --focus frames        # overview | gpu | cpu | frames | threads
+metavr perf compare before after                # a delta report, after one change
+metavr perf open                                # ui.perfetto.dev, for a human
+metavr perf query "<SQL>"                       # trace processor, for a specific question
+```
+
+Modes: `standard`, `gpu`, `cpu`, `lightweight`, `full`, `vr`, `custom`. Start
+with `vr`; go to `custom` when a specific data source is missing. The `--gpu-*`,
+`--cpu-scheduling`, `--xr-runtime` and `--vulkan-layer` switches only apply to
+`custom`.
+
+Meta's `hz-perfetto-debug` skill drives this tool in depth — use it once the
+capture exists.
+
+## simpleperf: CPU hotspots and what is actually bound
+
+```bash
+metavr perf simpleperf classify          # CPU-bound, memory-bound or I/O-bound, from PMU counters
+metavr perf simpleperf record            # cycle-sampled hotspots
+metavr perf simpleperf kernel-overhead   # kernel vs userspace, per thread
+```
+
+`classify` first: optimising a memory-bound loop as if it were compute is the
+most common wasted day. Meta's `hz-simpleperf-debug` covers the deeper flags.
+
+## RenderDoc: the GPU side
+
+`metavr tools install renderdoc` (Meta's fork). Three captures answer three
+different questions:
+
+| Question | Capture |
+|---|---|
+| Which draw call costs what | draw-call trace |
+| Which render stage dominates | render-stage trace |
+| Is a shader the problem | Vulkan shader stats |
+
+Docs: `ts-renderdoc-for-oculus`, `ts-renderdoc-capture`, `ts-renderdoc-drawcall`,
+`ts-renderdoc-renderstage`, `ts-renderdoc-shaderstats`.
+
+## OVR Metrics Tool: live, in the headset
+
+`metavr tools install ovrmetric` installs the OVRMonitorMetricsService APK;
+enable its overlay on the device to watch FPS, stale frames and utilisation
+while playing. Best for "does this scene ever recover", worst for precise
+numbers — the overlay itself costs a little.
+
+## What a usable capture report contains
+
+A report another agent can act on names all seven:
+
+1. build id and whether it is a **release** build;
+2. device model and Horizon OS version;
+3. requested refresh rate, and therefore the budget in ms;
+4. the scene and the interaction reproduced;
+5. `App` ms, `Stale`, `FPS=x/y`, `GPU%` — as read, not summarised;
+6. battery/thermal state at capture time;
+7. the trace file path, so the claim can be re-checked.
+
+A performance claim missing (1), (3) or (7) cannot be verified later and will
+be re-measured from scratch.

package/plugins/xr-dev/skills/quest-perf/references/mobile-rendering.md

@@ -0,0 +1,56 @@
+# Mobile rendering: experiments before prescriptions
+
+**Read this when**: choosing an art/render pipeline or diagnosing costs that desktop intuition
+misses. Sources checked 2026-09-21; no fixed scene-wide triangle/draw-call/texture
+budget applies to every device, content type or renderer.
+
+## Establish the workload
+
+Record device/OS, graphics API, render pipeline, stereo mode, refresh target,
+resolution, FFR/ETFR, MSAA, layers, lighting, animation/skinning, active cameras,
+content and thermal state. Capture representative CPU/GPU/frame/memory baselines.
+Use the same view and input sequence before/after; compare visual quality too.
+
+## Tile-based GPU decisions
+
+- Render-pass transitions and intermediate targets can cause costly stores,
+  resolves and reads from shared memory. Inventory postprocessing, camera stacks,
+  portals/reflections and copies before reducing asset quality indiscriminately.
+- Test pass fusion/subpass or direct rendering where supported by the actual
+  engine/backend. FFR/MSAA behavior depends on the target path; a screenshot of
+  an enabled setting does not prove it applies to the final rendering.
+- MSAA can be relatively efficient in tile memory, but higher sample counts still
+  cost memory/bandwidth and interactions matter. Benchmark against the chosen
+  resolution and shader workload rather than blanket-disable or max it.
+- Expensive position/vertex work and triangles crossing many tiles affect binning.
+  Inspect RenderDoc Meta Fork tile/render-stage evidence when available. Do not
+  assume tile dimensions or quote an unverified per-triangle execution formula.
+- Compare transparent/alpha-blended overdraw, particle layers and screen coverage;
+  reduce what profiling implicates. Measure baked versus realtime lighting,
+  shadows, shader variants and material complexity on the target.
+- For assets, measure compressed and resident textures, mip use, mesh/skin/animation
+  cost, LOD transitions, collisions, loading/upload stalls and memory peaks.
+  Normal maps or impostors trade geometry for other costs; verify the trade.
+
+## Advanced experiments and stop rules
+
+Use the existing rendering playbook for multiview, foveation, dynamic resolution,
+composition layers, symmetric projection, late latching and SpaceWarp. Every
+proposal states prerequisite, expected bottleneck, quality risk, capture and
+revert criterion. Do not enable multiple techniques then attribute a gain to one.
+Low app GPU utilization alone is not spare frame budget; distinguish app render,
+compositor, CPU scheduling and thermal behavior.
+
+Keep spectator/capture cameras out of normal gameplay budgets unless shipped.
+Profile representative sustained use and transitions, not just an empty scene.
+A simulator can exercise logic/API availability; it cannot certify headset GPU,
+comfort, thermal or Store performance. Never claim a fixed sum of CPU and GPU
+intervals when stages overlap.
+
+## Primary reading
+
+- [Tile rendering](https://developers.meta.com/horizon/documentation/unity/gpu-tiled/): architecture and binning.
+- [Improved algorithms](https://developers.meta.com/horizon/documentation/unity/gpu-improved-algorithms/): mobile-friendly tradeoffs.
+- [Impaired algorithms](https://developers.meta.com/horizon/documentation/unity/gpu-impaired-algorithms/): pass/resolve and vertex costs; verify its unresolved formula separately.
+- [Graphics pipeline](https://developers.meta.com/horizon/design/design-graphic-rendering-pipeline/): vocabulary, not a device feature support matrix.
+- [Display](https://developers.meta.com/horizon/design/display/): stereo, color and capture presentation.

package/plugins/xr-dev/skills/quest-perf/references/rendering-playbook.md

@@ -0,0 +1,51 @@
+# Rendering decisions and controlled experiments
+
+**Read this when** choosing a render path, diagnosing an expensive scene, importing assets or integrating foveation, compositor layers, late latching or SpaceWarp.
+
+Checked 2026-09-21. The tests below are engineering guidance. Use the engine/SDK's versioned documentation for switches; a native Vulkan extension name is not a Unity setting.
+
+## Capture the right workload
+
+Record build hash, engine/packages, graphics API, device/OS, refresh rate, render scale, CPU/render-thread/GPU times, waits, dropped frames, memory and sustained thermal state. Include scene/input, warmup and capture overhead. Compare the same workload before/after; average FPS hides spikes and half-rate operation.
+
+CPU and GPU can process different frames concurrently. Diagnose the critical path and deadline, not a sum of independent durations. GPU idle time may be waiting for CPU submission; a CPU wait may be waiting for the GPU. Compositor scheduling, sync and asset uploads can also produce missed frames. [Unity profiler markers](https://docs.unity3d.com/6000.0/Documentation/Manual/profiler-markers.html) documents these distinctions.
+
+## Select an experiment from the evidence
+
+| Suspected cost | Controlled change | Check for damage |
+|---|---|---|
+| CPU draw submission | Batching/instancing, culling, compatible multiview | Correct per-eye transforms/shaders, visibility, materials and animation |
+| Pixel/fragment cost | Reduce render scale, shader complexity, transparent coverage or FFR | Text/edges, central/peripheral quality, scene readability |
+| Bandwidth/tile stores | Reduce intermediate targets, resolves and full-screen passes; compatible subsampled layout | Alpha, MSAA/depth resolves, post effects and capture |
+| Geometry/animation | LOD, skin/bone budgets, animation update policy | Silhouette, deformation, popping and physics consistency |
+| Memory/residency | Mips/compression, bounded streaming, release unused assets | Unsupported importer extensions, texture color space, transition hitching |
+| CPU simulation/GC | Fixed-step budget, pooled allocations, bounded AI/pathfinding/I/O | Gameplay determinism, collision and response latency |
+| Load/warmup | Async loading, shader/pipeline warmup, progressive scene entry | First-use spikes and OS-compliant loading feedback |
+
+Quest's mobile/tile GPU behavior differs from desktop preview. Prefer the engine's supported mobile renderer; desktop Lumen/Nanite/post-processing assumptions are not standalone evidence. Consult [Meta Vulkan/OpenGL guidance](https://developers.meta.com/horizon/documentation/unreal/os-vulkan-opengl/) and the exact engine compatibility matrix rather than applying one graphics API rule to every engine.
+
+## Stereo, foveation and dynamic resolution
+
+[Unreal Mobile Multi-View](https://developers.meta.com/horizon/documentation/unreal/unreal-multi-view/) reduces CPU stereo submission overhead and is a prerequisite there for SpaceWarp/late latching; it does not make pixel shading free. Check the equivalent Unity/native path, shaders and per-view resources.
+
+[FFR](https://developers.meta.com/horizon/essentials/fixed-foveated-rendering/) is fixed-center and distinct from eye-tracked foveation. It helps appropriate fill-heavy workloads but can cost more than it saves for simple shaders. Test quality levels and compatible subsampled layout on each supported target. Query ETFR support rather than inferring it from a model name. Text that must remain sharp may belong on compositor layers.
+
+Dynamic resolution changes render scale, not the simulation budget. Verify the selected engine/SDK's control path and interaction with manual scale, FFR and frame-rate policy. Record hysteresis/quality limits and sustained behavior. A feature being available does not mean it is already enabled by the OS.
+
+[Symmetric projection](https://developers.meta.com/horizon/documentation/native/android/os-symmetric-projection/) changes eye frusta/render areas and can combine with supported Vulkan foveation/optimization paths. Preserve correct view/projection math and test clipping/per-eye edges. Evaluate it after a working baseline; do not hand-modify matrices merely because a tutorial reports a gain.
+
+## Layers, alpha and color
+
+[Compositor layers](https://developers.meta.com/horizon/essentials/compositor-layers/) can improve text/UI/video clarity, but have a rendering, memory and per-layer cost. Choose overlay versus underlay deliberately; verify alpha semantics, depth/occlusion and transparent ordering. Do not keep unused zero-alpha layers alive as a free placeholder. Confirm linear/sRGB conversions, supported swapchain formats and the selected engine's premultiplication convention; compare a color/alpha test pattern in the headset.
+
+For exported assets inspect post-import triangles/vertices, material slots/draw submissions, texture residency, mips, decoder support and bounds. A smaller compressed file may decode slowly or require an unavailable extension. Preserve masters, measure the scene after import and use the project's target profile instead of a universal polygon limit.
+
+## Reprojection and latency
+
+TimeWarp, application SpaceWarp and application rendering are different stages. [Application SpaceWarp](https://developers.meta.com/horizon/documentation/unreal/unreal-asw/) requires a supported engine/runtime integration, including depth/motion data. Test thin geometry, disocclusion, transparency, particles, UI and controller motion. No advertised percentage is a guaranteed budget increase for this scene.
+
+Late latching/prediction affects pose-to-display latency; it cannot repair an incorrect simulation, invalid pose or blocking network call. Verify engine support and input path. Retain full-rate rendering as a measured comparison when evaluating half-rate synthesis.
+
+## Deliver evidence, not a list of toggles
+
+For each optimization retain settings diff, trace/capture, metric distributions, visual regressions and an explanation of the bottleneck addressed. Report a sustained device result or NOT-RUN; simulator/remote PC rendering is not a headset thermal test. Change one variable per experiment unless a documented dependency requires a group.