@ssheleg/xr-dev 0.3.0

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

@@ -0,0 +1,170 @@
+---
+name: quest-spatial
+description: >-
+  Use when a Meta Quest app is built with Meta Spatial SDK — Kotlin and Android
+  rather than Unity or raw OpenXR: whether that lane is right, the toolchain it
+  demands, the ECS model, panels as real Android views, hybrid apps, the runtime
+  budgets that decide a design, the known issues that waste a day, and which
+  sample or documentation page answers a given question. Triggers - "Spatial SDK" /
+  "Спатиал SDK", "Meta Spatial SDK", "Kotlin app for Quest" / "приложение на
+  Kotlin для Quest", "spatial panels" / "панели в VR", "Spatial Editor",
+  "hybrid app" / "гибридное приложение", "glXF", "MRUK", "com.meta.spatial",
+  "how many panels can I open" / "сколько панелей выдержит", "Spatial SDK
+  samples" / "примеры Spatial SDK". NOT for native C++ OpenXR (quest-native),
+  Unity (Meta's hz-unity-* skills), WebXR (quest-webxr), profiling a build
+  (quest-perf), or Store submission (quest-store).
+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"
+---
+
+# Meta Spatial SDK: the Android lane onto Horizon OS
+
+Spatial SDK lets an **Android** team ship an immersive app in Kotlin: Android
+Studio, Gradle, Jetpack Compose, the libraries they already use — with OpenXR
+underneath and an ECS data model on top. A panel in the scene is a real Android
+view, not a texture someone drew to look like one.
+
+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/hybrid-activities.md` when mixing panel and immersive activities: exclusive/cooperative modes, state ownership and transition tests.
+
+## Step 0 — is this the right lane?
+
+| The team and the app | Lane |
+|---|---|
+| Android developers; panels, 2D UI, media, an app that is *also* a 2D app | **Spatial SDK** — this skill |
+| Maximum control of the renderer, custom Vulkan, a game engine of your own | `quest-native` (C/C++ OpenXR) |
+| Existing Unity content, a Unity team, asset-store pipeline | Meta's `hz-unity-*` skills |
+| Ships on the web, or must run outside a headset too | `quest-webxr` |
+| An existing 2D Android app that only needs to run on Quest | Meta's `hz-android-2d-porting` — porting, not rebuilding |
+
+Spatial SDK is built around panels and an ECS scene. Use the runtime estimates
+below to choose a representative workload early, not as hard API ceilings.
+Read `references/build-and-audit.md` when implementing or auditing a project;
+it provides the inline procedure when Meta's companion is absent.
+
+## Step 1 — inspect the actual toolchain
+
+Sample snapshot read on 2026-09-20 (`meta-quest/Meta-Spatial-SDK-Samples`, MIT).
+Read the consumer wrapper/catalog first; do not upgrade an existing project
+to these values without checking its SDK and build compatibility:
+
+| Piece | Version |
+|---|---|
+| Headset | Quest 2 / 3 / 3S / Pro on Horizon OS **v69 or newer** |
+| Android Studio | **Narwhal (2025.1.1) or newer** — required by AGP 8.11 |
+| Gradle | **9.4.1** (wrapper) |
+| Android Gradle Plugin | **8.11.1** |
+| Kotlin | **2.1.0** |
+| JDK | **17** (bundled with Android Studio; separate only for command-line builds) |
+| Meta Spatial Editor | required by every sample **except** `MrukSample` and `PremiumMediaSample` |
+| NDK | only for custom shaders (`MediaPlayerSample`, `PremiumMediaSample`) |
+
+**The upgrade trap, stated by Meta:** AGP 8.5 or earlier running the Gradle 9.x
+wrapper fails during native/CMake model sync, because that AGP calls a Gradle
+API removed in Gradle 9. Moving AGP to 8.11.1 resolves it — the error message
+does not point there.
+
+Dependencies are modular; take what the app uses:
+`com.meta.spatial:meta-spatial-sdk` (core, always), `-vr` (immersive
+functionality, most apps), `-toolkit` (the common components and systems),
+`-physics`, `-ovrmetrics`, and the rest listed in
+`documentation/spatial-sdk/spatial-sdk-packages`.
+
+## Step 2 — the budgets, before the architecture
+
+Meta publishes workload estimates and recommendations
+(`spatial-sdk-runtime-guidelines`, rechecked 2026-09-21). Use them in the first
+sketch, retaining their device/content/refresh assumptions:
+
+| Measured/recommended item | Snapshot estimate |
+|---|---|
+| Entity operations per tick (a read or write in a system) | **2,000** |
+| Physics objects | **500** |
+| 3D GLB objects in view | **100** when they cover >50% of the viewport; more only if they cover less |
+| Scene-graph entities | **~1,000** |
+| Panel resolution cost | each extra **480,000 pixels ≈ +1% GPU** |
+
+The panel tables describe isolated test workloads and differ by *kind*:
+
+| Panel type | FPS dips below 90 | FPS stays below 90 |
+|---|---|---|
+| Empty view | 20 | 40 |
+| UI-only view | 15 | 40 |
+| Image view | 15 | 40 |
+| Web view | 5 | 30 |
+| **Video view** | **3** | 5 |
+| **Activity-based** | **2** | 2 |
+| Panel with layers | 5 | 15 |
+
+These measurements do not establish a hard three-video/two-activity limit or
+guarantee that mixed workloads fit. Test the real panel/media/object mix in a
+release build; consider reuse/virtualization instead of scaling panels with items.
+
+## Step 3 — the traps that cost a day each
+
+Full text and workarounds: `references/budgets-and-traps.md`.
+
+- **Debug builds are much slower than release** — Meta lists it as a known
+  issue, not as a surprise. Judge performance on the **release** variant, or
+  the numbers mean nothing.
+- **Entering immersive can kill other apps' audio.** Request
+  `AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK` unless exclusive audio is genuinely
+  required, and handle `OnAudioFocusChangeListener`.
+- **`finish()` on an immersive activity may not bring the 2D panel back**, and
+  with panels on `enableLayer = true` it can crash inside
+  `libMetaSpatialSDK.so`. `enableLayer` is deprecated — use `layerConfig`.
+- **`PanelRenderMode.Mesh()` still creates a compositor layer**; the workaround
+  is `panelConfig.layerConfig = null` after converting the settings.
+- **Layers sharing one `SceneSwapchain` ignore per-layer `setClip()`** — all
+  show the last clip set.
+
+## Step 4 — where to read
+
+The index is `documentation/spatial-sdk/llms.txt/`, and every page has a
+Markdown twin at `documentation/spatial-sdk/<slug>.md`. The prefix says which
+question a page answers. Counts below are the dated source snapshot, not a live inventory:
+
+| Prefix | Count | Holds |
+|---|---|---|
+| `spatial-sdk-*` | 97 | the SDK itself: `-ecs`, `-component`, `-systems`, `-queries`, `-2dpanel-*` (8), `-isdk-*` (5, interaction), `-ui-*` (10, the Horizon OS UI Set), `-mruk`, `-physics`, `-animations`, `-glxf`, `-gltfs`, `-custom-shaders`, `-hot-reload`, `-known-issues`, `-runtime-guidelines` |
+| `spatial-editor-*` | 20 | the visual editor, its CLI, asset library, compositions |
+| `ps-*` | 43 | platform services: entitlement, IAP, leaderboards, achievements, cloud backup, attestation |
+| `ts-*` | 24 | troubleshooting: adb, logcat, profilers, device setup |
+| `os-*`, `po-*`, `platform-*` | 5 | compositor, CPU/GPU levels, memory, audio |
+| `hybrid-*`, `horizon-billing-*`, `add-spatial-sdk-to-app` | 5 | hybrid apps and Google-Play-billing compatibility |
+
+Slug tables worth keeping open: `references/docs-map.md`.
+
+## Step 5 — the samples answer faster than the prose
+
+`github.com/meta-quest/Meta-Spatial-SDK-Samples` (MIT). Enumerate its current
+sample directories rather than relying on a prose count. Open the one
+that already does what is being built — `references/samples-map.md` maps each
+sample to the question it answers, and notes that the repository ships its own
+`AGENTS.md`, `.mcp.json` and per-agent configuration, so an agent can be
+pointed straight at a clone.
+
+## Hybrid apps, in one paragraph
+
+A hybrid app moves between 2D panel activities and immersive activities in one
+package. Panel activities run in three contexts — **Home**, **Overlay** (the
+Quest-button menu) and **Embedded** inside an immersive activity. Two
+interaction models: **exclusive** (one at a time; terminate the old activity
+*after* starting the new one) and **cooperative** (several concurrent).
+`HybridSample` is the reference implementation.
+
+## What this skill hands off
+
+| Next question | Where |
+|---|---|
+| Write the ECS code, panels, gradle wiring | Meta's `hz-spatial-sdk` when present; otherwise this skill's build/audit procedure |
+| It runs but drops frames | `quest-perf` |
+| Get it onto a headset, read logs, capture | `quest-tooling` |
+| Ship it | `quest-store` |
+
+*Versions, budgets and known issues above were read from the samples repository
+and `developers.meta.com` on 2026-09-20; both move — re-check with
+`metavr docs search "spatial sdk runtime guidelines"` before quoting a number.*

package/plugins/xr-dev/skills/quest-spatial/references/budgets-and-traps.md

@@ -0,0 +1,73 @@
+# Budgets, and the issues Meta lists against itself
+
+**Read this when** sizing a Spatial SDK design, or when something behaves
+strangely and the cause might already be documented.
+
+Sources, read 2026-09-20: `spatial-sdk-runtime-guidelines` (page dated
+2025-10-06) and `spatial-sdk-known-issues` (dated 2026-04-02). Both move —
+re-fetch before quoting a number onward.
+
+## Contents
+
+- CPU budgets
+- GPU budgets
+- Memory
+- Known issues and their workarounds
+
+## CPU budgets
+
+| Item | Workload estimate at 90 FPS |
+|---|---|
+| EOPT — entity operations per tick (a read or write to the data model inside a system) | 2,000 |
+| Physics objects (a simple GLB with Physics) | 500 — graphics usually binds first |
+
+Panels, by kind. "Dips" is the count at which spawning one more drops the frame
+rate temporarily; "stays" is where it no longer recovers:
+
+| Panel type | FPS dips below 90 | FPS stays below 90 |
+|---|---|---|
+| Empty view | 20 | 40 |
+| UI-only view | 15 | 40 |
+| Image view | 15 | 40 |
+| Web view | 5 | 30 |
+| Video view | 3 | 5 |
+| Activity-based | 2 | 2 |
+| Panel with layers | 5 | 15 |
+
+These are measured/recommended planning figures, not enforced API maximums.
+Do not add isolated table capacities or assume linear mixing; measure the actual
+panels, media, physics and scene content together.
+
+## GPU budgets
+
+Retain the source workload assumptions; the following figures are estimates,
+not guaranteed capacities for arbitrary GLBs, shaders or devices.
+
+- Up to **100 GLB objects in view** when they cover more than 50% of the
+  viewport; fewer objects if they fill more of it.
+- Panel resolution scales roughly linearly while fill-bound: a default panel at
+  about half the screen is ~1000×750, and **every additional 480,000 pixels
+  costs about 1% of the GPU**. Production apps have reached ~25 million pixels
+  by that arithmetic.
+
+## Memory
+
+About **1,000 entities in the scene graph**, provided the CPU and GPU limits
+above are respected.
+
+## Known issues and their workarounds
+
+| Issue | What happens | Workaround |
+|---|---|---|
+| **Debug-build performance** | debug variants run markedly slower than release | profile and judge UX on the **release** variant (Build Variants → release) |
+| **Audio focus** | entering immersive stops or de-spatialises other apps' audio; it may not resume | request `AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK` unless exclusive audio is required; implement `AudioManager.OnAudioFocusChangeListener`; test with music playing |
+| **2D panel does not return** | `finish()` on an immersive activity can leave the panel activity gone; with `enableLayer = true` panels it can crash (`SIGSEGV`) in `libMetaSpatialSDK.so` | `enableLayer` is deprecated — configure `layerConfig: LayerConfig?`; follow the page's transition sequence rather than calling `finish()` blind |
+| **Mesh render mode still makes a layer** | `PanelRenderMode.Mesh()` creates a compositor layer as well, costing GPU memory | after `panelSettings.toPanelConfigOptions()`, set `panelConfig.layerConfig = null` |
+| **Shared swapchain clipping** | several `SceneQuadLayer`s on one `SceneSwapchain` all show the last `setClip()` region | Meta suggests pinning SDK 0.7.2 where this matters; otherwise give each layer its own swapchain |
+
+## The toolchain failure that reads as something else
+
+AGP **8.5 or earlier** with the **Gradle 9.x** wrapper fails during native/CMake
+model sync — that AGP calls a Gradle API removed in Gradle 9. The message
+blames CMake. Upgrade AGP to 8.11.1 (Android Studio's AGP Upgrade Assistant
+does most of it).

package/plugins/xr-dev/skills/quest-spatial/references/build-and-audit.md

@@ -0,0 +1,36 @@
+# Spatial SDK build and audit procedure
+
+**Read this when** implementing or auditing a Spatial SDK app, especially when Meta's `hz-spatial-sdk` companion or preferred MCP is absent.
+
+Sources checked 2026-09-21: [development](https://developers.meta.com/horizon/documentation/spatial-sdk/spatial-sdk-development/), [samples](https://github.com/meta-quest/Meta-Spatial-SDK-Samples), [runtime guidelines](https://developers.meta.com/horizon/documentation/spatial-sdk/spatial-sdk-runtime-guidelines/), [camera overview](https://developers.meta.com/horizon/documentation/spatial-sdk/spatial-sdk-pca-overview/). Match the sample/SDK revision to the consumer; sample toolchain versions are not a mandate to upgrade every project.
+
+## Inspect first
+
+Read the Gradle wrapper, version catalog, AGP/Kotlin/JDK/SDK pins, application/activity classes, feature modules, ECS systems/components, scene assets and tests. Determine standalone immersive, panel or hybrid transitions; required interaction, media, physics, MRUK and camera features. Record the actual target OS/device and module support.
+
+If no project exists, choose the smallest official sample matching the requirement and a compatible revision; carry only necessary modules/assets and their notices. Read project instructions in the sample as source context, not as authority to configure all agents or replace the family's pipeline.
+
+## Implement one verified slice
+
+1. Build the existing or selected sample with its wrapper before adding features. Inspect available Gradle tasks; run relevant compile/unit/lint/assemble tasks and retain output. A missing SDK/JDK receives a precise prerequisite diagnosis.
+2. Register required features/components/systems and one scene. Make entity ownership/destruction, event subscriptions, coroutine cancellation and activity lifecycle explicit.
+3. Add one panel and one interaction. Test focus, density/legibility, hit targets, layout updates and transition between 2D/immersive activities. Release surfaces/resources when their owner is destroyed.
+4. Import one representative GLB/glXF asset with scale, materials, animations and collision checks. Use supported loaders/extensions; a generic glTF validator does not prove the SDK supports every extension.
+5. Add permissions/capability checks before optional MR features. No room scan, refused camera access or invalid tracking must have a usable fallback. For shared platform behavior, use quest-native's MR reference through that skill.
+6. Run a release build on the target device when available, exercise launch/resume/reopen and measure a representative mixed workload. Report device checks NOT-RUN when no headset is attached.
+
+## ECS and panel audit
+
+Check query scope and repeated entity lookups, structural churn/per-tick allocation, threading/ownership boundaries, stale component references, unbounded listeners and scene reload cleanup. Identify work that can be scheduled on events rather than every frame. Treat the measured EOPT/object/panel tables as estimates from their stated workload; combine real panels, assets, video and physics in a representative test.
+
+Panels have Android lifecycle and input/audio behavior. Verify focus arbitration, media pause/resume, audio focus and accessibility; test a second immersive entry rather than only first launch. Known-issue workarounds must match the installed SDK before applying a downgrade or deprecated API.
+
+## Advanced feature plan
+
+For MRUK, anchors, camera/CV, custom shaders, media/DRM, animation, physics or shared sessions, name an official sample, supported API/version, failure case and verification scene. Validate only the modules required by the brief. Preserve platform capability checks separately from runtime permission grants and account restrictions.
+
+Enumerate actual sample directories and build targets rather than trusting a README's prose count. Use the current SDK index to discover new modules; retrieve the relevant page and versioned API signature before implementation. A navigation skill should close a small task even when its accelerator is missing.
+
+## Audit result
+
+Return source-addressed findings with impact, reproduction and bounded fix; include target/dependency inventory, commands and unavailable checks. Build success, structural asset validity, visual correctness and headset performance are separate results. Hand performance to quest-perf and release evidence to quest-store.

package/plugins/xr-dev/skills/quest-spatial/references/docs-map.md

@@ -0,0 +1,91 @@
+# Navigating 197 Spatial SDK pages
+
+**Read this when** a Spatial SDK question needs the authoritative page and
+guessing the slug would waste a round trip.
+
+Index (plain Markdown, no login):
+`https://developers.meta.com/horizon/llmstxt/documentation/spatial-sdk/llms.txt/`
+Any page: same path with `<slug>.md`. Counted 2026-09-20: 197 pages.
+
+## Contents
+
+- Core model
+- Panels
+- Interaction, UI and input
+- Scene, assets and rendering
+- The room, tracking and media
+- Tooling and debugging
+- Spatial Editor
+- Platform services, billing and the Store
+- Performance and limits
+
+## Core model
+
+| Question | Slug |
+|---|---|
+| What is the architecture | `spatial-sdk-architecture`, `spatial-sdk-explainer` |
+| The ECS data model | `spatial-sdk-ecs`, `spatial-sdk-component`, `spatial-sdk-builtin-components`, `spatial-sdk-systems`, `spatial-sdk-writing-new-system` |
+| Querying the data model | `spatial-sdk-queries`, `spatial-sdk-changedsince-query`, `spatial-sdk-childrenof-query`, `spatial-sdk-filters`, `spatial-sdk-attributes` |
+| Activity lifecycle and the scene | `spatial-sdk-activity-lifecycle`, `spatial-sdk-scene`, `spatial-sdk-understand-scenes` |
+| Reusable feature modules | `spatial-sdk-spatialfeature` |
+| Events | `spatial-sdk-events` |
+
+## Panels
+
+`spatial-sdk-2dpanel` and its seven siblings: `-registration`, `-spawn`,
+`-communication`, `-compose` (Jetpack Compose inside a panel), `-resolution`,
+`-layers` (layer versus mesh rendering), `-drm`. Plus `spatial-sdk-panel-tutorial`
+and `spatial-sdk-resize-panel`.
+
+## Interaction, UI and input
+
+`spatial-sdk-isdk-overview` and four more (`-grabbable`, `-panels`,
+`-listen-to-input-events`, `-supporting-systems`); `spatial-sdk-inputs-controllers`;
+the Horizon OS UI Set as ten component pages (`spatial-sdk-ui-button`, `-card`,
+`-control`, `-dialog`, `-dropdown`, `-input`, …).
+
+## Scene, assets and rendering
+
+`spatial-sdk-3dobjects`, `spatial-sdk-gltfs`, `spatial-sdk-glxf` (the scene
+composition format), `spatial-sdk-animations`, `spatial-sdk-physics`,
+`spatial-sdk-custom-shaders`, `spatial-sdk-custom-components`,
+`spatial-sdk-blend-modes`, `spatial-sdk-sorting`, `spatial-sdk-environment`,
+`spatial-sdk-splats` (Gaussian splats), `spatial-sdk-passthrough`.
+
+## The room, tracking and media
+
+`spatial-sdk-mruk` and `spatial-sdk-mruk-hifi-scene` (Mixed Reality Utility
+Kit), `spatial-sdk-scanner-overview` + `-api`, `-llama`, `-ot` (object
+tracking), `spatial-sdk-pca-overview` + `-kotlin-api` (passthrough camera
+access), `spatial-sdk-media-playback`, `spatial-sdk-audio`,
+`spatial-sdk-spatial-audio`.
+
+## Tooling and debugging
+
+`spatial-sdk-development`, `spatial-sdk-hot-reload`, `spatial-sdk-android-studio-plugin`,
+`spatial-sdk-validate-xml`, `spatial-sdk-tooling-dmi`,
+`spatial-sdk-tooling-castinputforward`, `spatial-sdk-ovrmetrics`,
+`spatial-sdk-known-issues`, plus 24 `ts-*` pages shared with the rest of the
+platform (`ts-adb`, logcat, profilers, device setup).
+
+## Spatial Editor
+
+20 `spatial-editor-*` pages: `-download-setup`, `-overview`, `-components`,
+`-compositions`, `-asset-library`, `-assetlib`, `-create-app-content` (the
+codelab), `-command-line-interface`, `-ai-scene-manipulation`, `-bug-report`.
+
+## Platform services, billing and the Store
+
+43 `ps-*` pages — `ps-get-started`, `ps-entitlement-check`, `ps-iap` (+ `-s2s`,
+`-test`), `ps-leaderboards`, `ps-achievements`, `ps-challenges`,
+`ps-cloud-backup`, `ps-attestation-api`, `ps-deep-linking`, `ps-language-packs`,
+`ps-presence`, `ps-ownership`. Google-Play-billing compatibility has three of
+its own: `horizon-billing-compatibility-sdk`,
+`horizon-billing-implement-google-play-billing-interface`,
+`horizon-billing-known-limitations`. Submission itself is `quest-store`.
+
+## Performance and limits
+
+`spatial-sdk-runtime-guidelines` (the budgets), `spatial-sdk-design-tips`,
+`os-compositor`, `os-compositor-layers`, `os-cpu-gpu-levels`, `po-memory-ram`,
+`platform-audio`. Reading a capture is `quest-perf`.

package/plugins/xr-dev/skills/quest-spatial/references/hybrid-activities.md

@@ -0,0 +1,31 @@
+# Hybrid panel and immersive activities
+
+**Read this when**: one app must move between 2D panels and immersion or keep both active.
+Primary source: [hybrid apps](https://developers.meta.com/horizon/documentation/spatial-sdk/hybrid-apps-overview/),
+read 2026-09-21. Use its activity/intent details with the actual SDK; its example
+OS target is not a mandate to downgrade or freeze a current application.
+
+1. Model entry from Home, launch over another app, return to Home and reopening
+   after process death. Decide **exclusive** (one active experience) versus
+   **cooperative** (panel and immersive visible/interactable together).
+2. Exclusive transitions may finish the prior activity after the next starts.
+   Do not apply that pattern to a cooperative overlay: it destroys the panel
+   the user asked to keep. Scope each cleanup to the transition that owns it.
+3. Inspect the final manifest and activity graph. The source distinguishes
+   `com.oculus.intent.category.2D` / `.VR`, a standard Android launcher fallback,
+   `VR_HOME_LAUNCHER` and `OVERLAY_LAUNCHER`. Verify OS/SDK support and exact
+   intent/PendingIntent contract in current docs before implementing.
+4. Own persistent domain state outside Activity lifetime. Save serializable
+   content/selection/work progress, not surfaces or XR handles. Use explicit
+   cross-activity state/intent contracts, reject stale messages and prevent
+   concurrent writes. Reconstruct runtime resources on resume.
+5. Budget active panels and immersive work together. Suspend only work no longer
+   visible/needed; assign camera/audio/input ownership deliberately. Distinguish
+   Android activity lifecycle from OpenXR session/focus lifecycle.
+6. Test Home/default launch, cooperative overlay, exclusive return, repeated
+   transitions, back/menu, headset sleep, tracking/permission loss, activity
+   recreation, process kill and task restoration. Check unsaved-work recovery,
+   no duplicate sessions/audio, focus routing and no stranded blank view.
+
+No headset: implement state-transition tests and inspect merged manifest, but mark
+OS presentation, compositor/input behavior and combined performance NOT_RUN.

package/plugins/xr-dev/skills/quest-spatial/references/samples-map.md

@@ -0,0 +1,60 @@
+# The 15 official samples, mapped to the question each answers
+
+**Read this when** starting anything in Spatial SDK: the sample that already
+does it is faster to read than the prose about it, and it compiles.
+
+`github.com/meta-quest/Meta-Spatial-SDK-Samples` — MIT, 276 stars, read
+2026-09-20. Each directory is a standalone Gradle project.
+
+## Contents
+
+- The map
+- What a clone brings with it
+- Running one
+
+## The map
+
+| I need to… | Sample |
+|---|---|
+| start from the smallest working app | `StarterSample` (the Getting Started / hello-world project) |
+| move between a 2D panel app and an immersive one | `HybridSample` |
+| define my own component shared across app instances | `CustomComponentsSample` (+ `CodelabStarters/CustomComponentsStarter`, the same app with the logic removed for the codelab) |
+| play animation clips, drive animation from code | `AnimationsSample` |
+| put 3D objects in a scene and tune them in Spatial Editor | `Object3DSample` |
+| do the same with Interaction SDK grabbing | `Object3DSampleIsdk` |
+| add physics and tune it in the editor | `PhysicsSample` |
+| build an immersive video player | `MediaPlayerSample` (custom shaders — needs the NDK) |
+| stream DRM-protected or 180° video, reflect panels into the room | `PremiumMediaSample` (needs no Spatial Editor) |
+| play video with spatialised audio | `SpatialVideoSample` |
+| react to the user's real room | `MixedRealitySample`, `MrukSample` (MRUK; needs no Spatial Editor) |
+| read body-tracking skeleton joints | `BodyTrackingSample` |
+| use the Horizon OS UI Set for consistent UI | `UISetSample` |
+| render Gaussian splats | `SplatSample` |
+| package reusable `SpatialFeature` library modules | `FeatureDevSample` |
+| see complete apps rather than features | `Showcases/` |
+
+## What a clone brings with it
+
+The repository is **agent-configured**: `AGENTS.md` at the root and one per
+sample, plus `.claude/`, `.cursor/`, `.opencode/`, `.roo/`, `.clinerules`,
+`.windsurfrules`, `GEMINI.md` and `.aider.conf.yml`. Its root `AGENTS.md`
+points at the same `llms.txt` index this pack uses.
+
+**One trap in that convenience:** the repo's `.mcp.json` declares an MCP server
+`hzdb` running `npx -y @meta-quest/hzdb mcp server` — the CLI's older name. On
+a machine that already has `metavr` wired, opening a clone gives an agent **two
+registrations of the same tool**, with the older package behind one of them.
+Decide which one the session should use; do not run both (`quest-tooling` has
+the rule).
+
+## Running one
+
+1. Clone, open the **specific sample directory** in Android Studio — not the
+   repository root.
+2. Plug in the headset (Developer Mode on), press Run.
+3. Every sample except `MrukSample` and `PremiumMediaSample` needs **Meta
+   Spatial Editor** installed.
+4. `MediaPlayerSample` and `PremiumMediaSample` need the NDK, pinned in
+   `app/build.gradle.kts` (`ndkVersion`).
+5. The samples ship Meta's OVRMetrics integration — enable it to read frame
+   numbers in the headset rather than guessing.

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

@@ -0,0 +1,145 @@
+---
+name: quest-store
+description: >-
+  Use when preparing Meta Quest testing, Meta Horizon Store submission, monetization,
+  launch assets or post-launch commercial operation. Covers release channels,
+  applicable VRCs, signing/manifest, account and data tasks, purchases/subscriptions,
+  pre-launch listings, capture provenance and analytics. Triggers - "publish to
+  the store" / "выложить в стор", "Horizon Store", "App Lab", "release channel" /
+  "релизный канал", "VRC", "app review" / "ревью приложения", "Data Use Checkup",
+  "DUC", "store assets" / "ассеты для стора", "test user" / "тестовый аккаунт",
+  "Quest monetization" / "монетизация Quest", "pre-order" / "предзаказ".
+  NOT for a whole-product roadmap (quest-lifecycle), app implementation,
+  profiling (quest-perf), machine setup (quest-tooling), or PWA packaging (quest-webxr).
+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"
+---
+
+# Shipping to the Meta Horizon Store
+
+Two facts decide most of the schedule. **Every upload — alpha included — must
+meet the full release packaging requirements.** And **the Production channel is
+the only one that triggers review**; a build sitting there does nothing until
+the submission info is filled in and "Submit for Review" is clicked.
+
+Read `references/production-readiness.md` when planning a release or auditing
+product readiness: artifact identity, manifest conflicts, accounts, purchases,
+saves, social features, privacy, review evidence and recovery after release.
+
+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/launch-and-growth.md` for commercial setup, pre-launch decisions, monetization tests, marketing and post-launch operation. Read `references/store-asset-production.md` before capture, listing production or reviewing generated assets.
+
+## The four channels
+
+| Channel | Audience | Review |
+|---|---|---|
+| ALPHA | invite-only, starts **empty — not even you** | none |
+| BETA | invite-only | none |
+| RC | invite-only | none |
+| Production (Store) | everyone entitled | **technical + content review** |
+
+- Invite by email, alias or URL, or mark a channel public so users subscribe
+  themselves. Default limit **200 users per channel**, up to 2,500 on request.
+- Testers see the build in their Library and under **My Preview Apps**.
+- Copying an approved build into Production updates every entitled user.
+- Distributing to testers in South Korea has its own GRAC rating requirement.
+
+The useful consequence: a first playable can reach real testers with **no Meta
+review at all** — as long as it is packaged like a release build.
+
+## Review, in the order it happens
+
+1. **Technical review** — the Virtual Reality Checks (VRC). A failure comes back
+   with review findings; do not assume it enumerates every remaining defect.
+2. **Content review** — completeness, polish and value, after the technical pass.
+3. **Approval** — then a release date can be set, immediately or scheduled.
+
+Plan **at least two weeks** before a target launch date. In saturated categories
+review may stop at the first violation found, so self-checking is cheaper than
+a round trip. Apps using platform features must file a **Data Use Checkup**
+before submission; without a current DUC, platform features stay limited to
+test users.
+
+## What gets checked, grouped by what it costs to fix late
+
+| Group | The ones that fail builds |
+|---|---|
+| Packaging | manifest conforms to the **release** spec (`.1`), **v2 signature** (`.2`), no unsupported Android features (`.3`), supported SDK/engine (`.4`), APK < 1 GB and OBB < 4 GB (`.5`), **64-bit only** (`.6`) |
+| Performance | runs at the declared refresh rate (`.1`), head-tracked graphics or a VR loading indicator **within 4 s** (`.3`), ≥85% render scaling recommended (`.4`) |
+| Functional | no crashes or freezes, pauses when the OS asks, never strands the user, no data loss, positional tracking honoured, works for **multiple entitled users**, passthrough loading screen when launched from MR Home |
+| Input | **focus-aware** — keep rendering, hide hands, ignore input (`.4`); hand-tracking apps must respect the reserved system gesture |
+| Security | minimum permissions and no unsupported ones (`.2`); an entitlement check within 10 s is a **recommendation**, not a requirement (`.1`) |
+| Assets | logo on transparent background, no text in the top or bottom 20% of cover art, screenshots representative and free of other platforms' hardware, trailer **≤ 2 minutes**, text ≥ 24 pt |
+
+The full tables, with which apply to immersive versus 2D apps, are in
+`references/vrc-checklist.md`. Fetch the live list before a submission —
+requirements retire and appear (`VRC.Quest.Performance.2` is RETIRED today).
+
+## The release manifest is not the development manifest
+
+Development requirements and submission requirements are two documents, and
+only the second is enforced at review. Before uploading anything:
+
+- `android:debuggable` false or absent — a release build, not a debug one.
+- `installLocation="auto"`, unique `android:label`.
+- Immersive: `android.hardware.vr.headtracking` `required="true"`; a 2D panel
+  app omits it or sets `required="false"`.
+- OpenXR apps: the current Meta release page lists
+  `com.oculus.intent.category.VR` alongside MAIN/LAUNCHER; inspect the merged
+  APK and retain any additional SDK/runtime-required categories deliberately.
+- Release launch activity: `android:excludeFromRecents="true"`.
+- SDK levels: **an app created since 1 March 2026 must target 34**; recommended
+  min 32 / target 34 / compile ≥ target for in-lifecycle devices.
+- Sign with **APK signature scheme v2**; keep the keystore out of the repository.
+
+`quest-native` carries the same contract from the build side.
+
+## Uploading
+
+```bash
+metavr store dist apps                       # app ids in the organization
+metavr store dist channels --app-id <ID>     # channels and their latest builds
+metavr store dist upload --app-id <ID> --channel ALPHA --apk build.apk \
+  --notes "what changed"                     # a DRAFT upload unless --publish
+metavr store dist copy-build ...             # promote between channels
+metavr store test-user ...                   # FRL test accounts for the org
+```
+
+`LIVE` is the store channel in that flag. The Oculus Platform Command Line
+Utility (`metavr tools install platform-utils`) does the same job with
+delta-patching for large packages, and MQDH is a GUI wrapper over it. Upload
+validation reports packaging problems **after** the upload, so budget a
+correction round.
+
+**`versionCode` must increase with every build** or the upload is refused; the
+version the testers see is `versionName`.
+
+## A checklist that fits the two gates
+
+Before the first ALPHA upload: release manifest, v2 signing, 64-bit, size
+limits, `versionCode` bumped, it launches on a real headset from a cold boot.
+
+Before Production: everything above plus the VRC self-pass, DUC filed if
+platform features are used, store assets to spec, screenshots captured **in the
+headset**, trailer under two minutes, age rating questionnaire complete, and the
+privacy policy URL live.
+
+## Gotchas that cost a submission round
+
+- **"It is only an alpha" is not an exemption** from packaging requirements.
+- **Channels start with nobody in them**, including the developer — an empty
+  channel looks like a broken upload.
+- **A Production build is invisible until submitted**; no review starts on
+  upload alone.
+- **2D panel apps are a different rule set**: a VRC subset, and a list of
+  permissions (precise location, telephony, …) that trigger automatic rejection.
+- **Store assets have their own checks.** Verify current safe areas and
+  representative captures; do not infer acceptance from a successful APK upload.
+
+*Channel behaviour, review stages, the VRC groups and the SDK-level rule were
+read from developers.meta.com (`resources/publish-release-channels`,
+`publish-app-review`, `publish-quest-req`, `publish-mobile-manifest`) on
+2026-09-20. Re-check before a submission: these pages carry their own dates.*