oomi-ai 0.2.48 → 0.2.49

package/README.md

@@ -1,57 +1,60 @@
-# oomi-ai
-
-OpenClaw channel plugin and bridge tooling for Oomi managed chat and voice.
-
-## Current Focus
-
-`0.2.40` keeps the persona automation lane, adds a stable local persona runtime manager, upgrades the Docker dev harness from a package simulator to a real OpenClaw runtime, and introduces a shared OpenClaw profile contract so local onboarding, Docker bootstrap, and future hosted agents use the same setup model:
-- WebSpatial-based persona scaffolding for generated Oomi apps
-- vendored AndroidXR WebSpatial fork sync for persona runtimes, including the npm-safe package metadata needed by OpenClaw installs
-- managed persona runtime installs now detect vendored WebSpatial drift and reinstall automatically so existing workspaces pick up XR runtime fixes
-- a high-level `oomi personas create-managed` command for agent-driven persona creation
-- a stable `oomi personas launch-managed` flow for local persona hosting under `OPENCLAW_WORKSPACE/personas`
-- a matching `oomi personas delete` flow that stops managed runtimes and removes the persona workspace from the OpenClaw machine
-- shared OpenClaw path handling for isolated local or containerized dev roots
-- versioned `oomi openclaw profile init|apply` commands for deterministic local/dev or hosted setup flows
-- explicit model auth modes so onboarding can default to `oomi-managed` while internal testing can still opt into direct provider auth
-- a repo-local `openclaw debug persona-runtime` smoke test for managed persona runtime launch/reuse/stop
-- a Docker-based OpenClaw dev harness that runs a real `openclaw gateway` inside an isolated container
-- device-authenticated persona runtime registration and job callbacks
-- automatic bridge-side polling for queued `persona_job` control messages
-- one shared spoken-metadata normalizer used by both the extension and the bridge
-- a repo-backed local `tts-pipeline` replay that can validate assistant-final -> backend -> real Qwen TTS before publishing
-- spoken-metadata handling that preserves natural pauses like `...` and keeps the managed voice contract valid on the real chat session path
-
-This package is for two audiences:
-- OpenClaw operators who need to connect a machine to Oomi and keep chat or voice healthy
-- Developers evaluating the plugin on npm and deciding whether it matches their OpenClaw + Oomi setup
-
-## What This Package Ships
-
-The npm package contains two Oomi integration surfaces:
-
-1. OpenClaw channel extension
-- File: `openclaw.extension.js`
-- Purpose: stable managed text transport through the Oomi backend channel API
-- This is the preferred integration surface for normal chat
-
-2. Local bridge + CLI
-- Files: `bin/oomi-ai.js`, `bin/sessionBridgeState.js`
-- Purpose: pair a device, manage the OpenClaw bridge worker, and support managed gateway traffic needed by device-backed chat and voice
-- This is the part that deals with broker sockets, local gateway sessions, challenge auth, and bridge health
-
-In practical terms:
-- If you only need a clean managed chat channel, the extension is the main reason to install this package
-- If you need Oomi device-backed chat or voice on an OpenClaw machine, you also need the bridge tooling in this package
+# oomi-ai
+
+Managed Oomi chat, voice bridge, and XR-first persona scaffolding for OpenClaw.
+
+## At A Glance
+
+- managed OpenClaw channel extension for Oomi text chat
+- local bridge and pairing tooling for device-backed chat and voice
+- XR-first WebSpatial persona scaffolding for generated Oomi work surfaces
+- vendored AndroidXR WebSpatial fork sync and scaffold repair for managed persona runtimes
+- managed persona launch, register, stop, delete, and queued persona-job execution flows
+- repo-local runtime and TTS validation loops for package developers
+
+This package is for two audiences:
+- OpenClaw operators who need to connect a machine to Oomi and keep chat or voice healthy
+- Developers evaluating the plugin on npm and deciding whether it matches their OpenClaw + Oomi setup
+
+## Current Package Focus
+
+The current package is centered on three operational contracts:
+
+1. managed Oomi text transport inside OpenClaw
+2. device-backed chat and voice through the local bridge
+3. XR-first persona runtime generation and repair for Oomi work surfaces
+
+## What This Package Ships
+
+The npm package contains three Oomi integration surfaces:
+
+1. OpenClaw channel extension
+- File: `openclaw.extension.js`
+- Purpose: stable managed text transport through the Oomi backend channel API
+- This is the preferred integration surface for normal chat
+
+2. Local bridge + CLI
+- Files: `bin/oomi-ai.js`, `bin/sessionBridgeState.js`
+- Purpose: pair a device, manage the OpenClaw bridge worker, and support managed gateway traffic needed by device-backed chat and voice
+- This is the part that deals with broker sockets, local gateway sessions, challenge auth, and bridge health
+
+3. Persona scaffold + runtime helpers
+- Files: `templates/persona-app/*`, `lib/scaffold.js`, `lib/personaRuntime*.js`
+- Purpose: create, launch, repair, and register XR-first managed persona apps for Oomi
+- This is the part that matters when Oomi or an agent generates a specialist work surface
+
+In practical terms:
+- If you only need a clean managed chat channel, the extension is the main reason to install this package
+- If you need Oomi device-backed chat or voice on an OpenClaw machine, you also need the bridge tooling in this package
+- If you need Oomi-managed personas that open as real XR work surfaces, you also need the scaffold and runtime helpers in this package
 
 ## When To Install It
 
-Install `oomi-ai` if all of the following are true:
-- you use OpenClaw
-- you want Oomi as a managed channel inside OpenClaw
-- you want device-backed Oomi chat, Oomi voice, or both
-
-Do not install it just to use the Oomi web app by itself.
+Install `oomi-ai` if all of the following are true:
+- you use OpenClaw
+- you want Oomi as a managed channel, bridge-backed voice surface, or persona runtime inside OpenClaw
+- you want device-backed Oomi chat, Oomi voice, generated personas, or some combination of those
+
+Do not install it just to use the Oomi web app by itself.
 
 ## Install And Upgrade
 
@@ -82,14 +85,15 @@ openclaw plugins install oomi-ai@latest
 
 ## Operator Quick Start
 
-The packaged operator instructions live in [agent_instructions.md](./agent_instructions.md).
-That is the primary reference for:
-- pairing a device
-- installing the plugin
-- configuring `channels.oomi.accounts.default`
-- running or supervising the bridge
-- checking whether the system is healthy
-- troubleshooting chat and voice failures
+The packaged operator instructions live in [agent_instructions.md](./agent_instructions.md).
+That is the primary reference for:
+- pairing a device
+- installing the plugin
+- configuring `channels.oomi.accounts.default`
+- running or supervising the bridge
+- checking whether the system is healthy
+- troubleshooting chat and voice failures
+- generating or repairing XR-first managed persona apps
 
 Fast-path install flow:
 
@@ -285,19 +289,19 @@ OPENROUTER_API_KEY=<your-openrouter-key>
 
 The local harness uses the `openrouter-free` preset for direct-provider smoke. If `OPENROUTER_API_KEY` is present in `.env.local`, `pnpm run dev:openclaw-local` automatically uses the provider-backed testing path. Without that key, it boots in `oomi-managed` mode and waits on a future Oomi-managed provider relay.
 
-## Persona Scaffolding
-
-Use the scaffold flow when OpenClaw needs to build a managed persona app that will live inside Oomi:
+## Persona Scaffolding
+
+Use the scaffold flow when OpenClaw needs to build a managed persona app that will live inside Oomi:
 
 ```bash
 oomi personas scaffold market-analyst --name "Market Analyst" --description "Private app for reviewing my broker positions and risk." --out ~/.openclaw/workspace/personas/market-analyst
 ```
 
-Use:
-- `oomi personas create <id>` for repo-local manifest work
-- `oomi personas create-managed --name "Cooking Persona" --description "Private cooking workspace"` for the end-to-end Oomi-managed persona flow
-- `oomi personas scaffold <slug>` for a WebSpatial-based Oomi app shell with runtime metadata and health documents
-- `oomi persona-jobs execute --message-file <job.json>` when OpenClaw receives a structured persona orchestration job from Oomi
+Use:
+- `oomi personas create <id>` only for repo-local manifest work, not for the normal managed Oomi persona flow
+- `oomi personas create-managed --name "Cooking Persona" --description "Private cooking workspace"` for the end-to-end Oomi-managed persona flow
+- `oomi personas scaffold <slug>` for an XR-first WebSpatial Oomi app shell with runtime metadata and health documents
+- `oomi persona-jobs execute --message-file <job.json>` when OpenClaw receives a structured persona orchestration job from Oomi
 
 Additional persona runtime commands:
 
@@ -307,13 +311,21 @@ oomi personas status market-analyst
 oomi personas stop market-analyst
 oomi personas delete market-analyst
 oomi personas runtime-register market-analyst --local-port 4789
-oomi personas heartbeat market-analyst --local-port 4789
+oomi personas heartbeat market-analyst --local-port 4789
 oomi persona-jobs start pj_123
 oomi persona-jobs succeed pj_123 --workspace-path ~/.openclaw/workspace/personas/market-analyst --local-port 4789
 oomi persona-jobs fail pj_123 --code JOB_FAILED --message "Scaffold generation failed."
-```
-
-Recommended agent flow:
+```
+
+Notes:
+
+- For remote Oomi clients such as web and Android XR, do not manually register `http://127.0.0.1:<port>` as the persona `entryUrl`.
+- When you pass only `--local-port`, `oomi-ai` derives a LAN-reachable endpoint automatically and keeps the healthcheck on loopback.
+- If you pass `--endpoint` explicitly, it should be a LAN or relay URL that the client can actually open.
+- The scaffolded XR route should default directly into a mounted scene component that calls `configurePersonaScene()`, logs `detectSpatialEnvironment()`, and renders multiple authored `enable-xr` panels.
+- The browser route should remain valid, but the XR entry path should not fall back to a flat marketing or home page.
+
+Recommended agent flow:
 
 ```bash
 oomi personas create-managed --name "Cooking Persona" --description "Private cooking workspace for recipes, meal planning, and kitchen notes."
@@ -412,18 +424,26 @@ What to check:
 - if the package local replay succeeds but the live machine fails, verify the OpenClaw machine is actually running the updated bridge binary
 - if the local replay fails, fix the assistant-final contract first instead of debugging the browser or backend deployment
 
-## Developer Notes
-
-If you are inspecting this package on npm, the main architectural points are:
-- the extension path is the stable managed text contract
-- the local bridge exists because Oomi also needs device-backed and voice-capable flows
-- the bridge has been hardened for:
-  - strict `connect`-first forwarding
-  - method-specific request shaping
-  - `idempotencyKey` handling
-  - bridge status that does not report `connected` before managed subscription is ready
-  - runtime fault isolation so local session failures are less likely to crash the whole provider
-  - one shared hidden managed-voice speech metadata helper used by both the extension and the local bridge
+## Developer Notes
+
+If you are inspecting this package on npm, the main architectural points are:
+- the extension path is the stable managed text contract
+- the local bridge exists because Oomi also needs device-backed and voice-capable flows
+- the persona scaffold exists because Oomi specialist personas can surface as scoped XR/web work surfaces, not just chat tabs
+- the bridge has been hardened for:
+  - strict `connect`-first forwarding
+  - method-specific request shaping
+  - `idempotencyKey` handling
+  - bridge status that does not report `connected` before managed subscription is ready
+  - runtime fault isolation so local session failures are less likely to crash the whole provider
+  - one shared hidden managed-voice speech metadata helper used by both the extension and the local bridge
+
+For generated WebSpatial persona apps, the intended scaffold contract is:
+- XR mode defaults directly into the mounted scene route
+- `configurePersonaScene()` runs from that scene component
+- runtime diagnostics are logged on scene boot
+- multiple meaningful UI surfaces use `enable-xr` and `xrStyle()`
+- `html.is-spatial` keeps the host shell transparent
 
 If you are developing the plugin, test the packaged surface with:
 

package/agent_instructions.md

@@ -1,6 +1,11 @@
-# Oomi OpenClaw Operator Guide
-
-Use these instructions when you need to connect, repair, or verify an OpenClaw machine that should talk to Oomi.
+# Oomi OpenClaw Operator Guide
+
+Use these instructions when you need to connect, repair, or verify an OpenClaw machine that should talk to Oomi.
+
+This is the packaged agent-facing reference for:
+- managed OpenClaw connect and repair flows
+- device-backed chat and voice bridge recovery
+- XR-first persona generation and persona runtime repair
 
 ## Primary Goal
 
@@ -194,20 +199,33 @@ Aliases allowed if needed:
 
 ## Persona App Generation
 
+For persona app work, treat the scaffold as a runtime contract, not a disposable starting point.
+
 When a user asks you in chat to create a new persona for Oomi:
 
 1. Prefer `oomi personas create-managed --name "<name>" --description "<description>"`.
 2. That is the primary end-to-end command for agent-driven persona creation.
 3. It creates the managed persona record in Oomi and relies on the running bridge to consume the queued `persona_job` automatically.
 4. Do not manually scaffold first unless you are recovering a failed persona job or working outside the queued Oomi flow.
+5. Do not present a localhost URL like `http://127.0.0.1:4789` as the final persona runtime URL for Oomi clients.
+6. If you need to inspect or repair runtime registration manually, prefer `oomi personas launch-managed <slug>` or `oomi openclaw refresh` before dropping to low-level callbacks.
 
 When generating a managed persona app for Oomi:
 
 1. Do not build the app shell from scratch.
 2. Always run `oomi personas scaffold <slug> --name "<name>" --description "<description>" --out <path>` first.
 3. Only customize persona-specific files inside `src/persona/` and `persona/` unless Oomi explicitly instructs otherwise.
-4. Preserve the scaffolded WebSpatial/Vite shell, `public/oomi.health.json`, `oomi.runtime.json`, and `public/manifest.webmanifest`.
-5. After customization, start the app and register the runtime with Oomi using the current runtime contract.
+4. Preserve the scaffolded WebSpatial/Vite shell, `public/oomi.health.json`, `oomi.runtime.json`, `public/manifest.webmanifest`, and the vendored WebSpatial fork.
+5. Keep the browser route and the XR route split. In XR mode, the index route should open directly into the mounted scene component, not a flat homepage.
+6. Call `configurePersonaScene()` from that mounted scene component and log `detectSpatialEnvironment()` on scene boot so the runtime can be verified in headset.
+7. Author multiple meaningful XR surfaces with `enable-xr`, `--xr-back`, and `--xr-background-material` values instead of putting one outer `enable-xr` wrapper around the whole page.
+8. Keep `html.is-spatial` shell styles transparent so the host recedes and the authored panels carry the spatial material.
+9. Keep `snapdom` and `html2canvas` exposed from `main.tsx` because AndroidXR DOM capture depends on them.
+10. After customization, start the app and register the runtime with Oomi using the current runtime contract.
+11. For normal OpenClaw-hosted persona apps on the same LAN, the runtime registration contract is:
+   - backend `entryUrl`: LAN-reachable host such as `http://192.168.x.x:<port>`
+   - backend `healthcheckUrl`: local loopback such as `http://127.0.0.1:<port>/webspatial/avp/oomi.health.json`
+12. Do not override `--endpoint` with `127.0.0.1` unless the persona is intentionally local-only and not meant to open from Oomi web/XR.
 
 When editing an existing managed persona that is already open in Oomi:
 
@@ -215,7 +233,7 @@ When editing an existing managed persona that is already open in Oomi:
 2. First run `oomi personas status <slug> --json`.
 3. Use `editableWorkspacePath` from that command as the authoritative directory for reads, edits, and verification.
 4. Treat `compatibilityWorkspacePath` only as a fallback or migration clue.
-5. Preserve the scaffolded WebSpatial shell and runtime health files unless the user explicitly asks for a deeper structural change.
+5. Preserve the scaffolded WebSpatial shell and runtime health files unless the user explicitly asks for a deeper structural change, and do not regress the XR route back into a flat home page.
 6. Do not claim the persona changed unless you have verified the file contents changed in `editableWorkspacePath` or the runtime reflects the update.
 
 When executing a structured persona job from Oomi:
@@ -228,5 +246,7 @@ When executing a structured persona job from Oomi:
    - `oomi persona-jobs start <jobId>`
    - `oomi persona-jobs succeed <jobId> --workspace-path <path> --local-port 4789`
    - `oomi persona-jobs fail <jobId> --code <code> --message "<text>"`
+4. If you use the low-level `runtime-register` or `heartbeat` commands, prefer `--local-port` by itself and let `oomi-ai` derive the LAN-reachable endpoint automatically.
+5. If you must pass `--endpoint` explicitly, it must be the LAN-reachable host or a relay URL, not `127.0.0.1`.
 
 When the Oomi bridge is running on the machine, queued persona jobs from Oomi are now polled and executed automatically through the filtered control-message lane. You should still use the explicit commands above for manual retries, recovery, or direct operator workflows.

package/bin/oomi-ai.js

@@ -259,12 +259,12 @@ Commands:
   personas sync
     Sync personas from the repo into the Oomi backend registry.
 
-  personas create <id>
-    Create a new persona manifest and optionally sync it to the backend.
-  personas create-managed [slug]
-    Create a managed persona in Oomi and enqueue its build job for the linked device.
-  personas launch-managed [slug]
-    Launch or reuse a managed persona runtime on this OpenClaw machine.
+  personas create <id>
+    Create a new persona manifest for local or repo work. For managed Oomi personas prefer create-managed.
+  personas create-managed [slug]
+    Create a managed persona in Oomi and enqueue its build job for the linked device.
+  personas launch-managed [slug]
+    Launch or reuse a managed persona runtime on this OpenClaw machine and register a client-reachable runtime URL.
   personas scaffold <slug>
     Create an Oomi-managed persona app scaffold for agent customization.
   personas status <slug>
@@ -274,9 +274,9 @@ Commands:
   personas delete <slug>
     Stop a managed persona runtime and remove its workspace from this OpenClaw machine.
   personas runtime-register <slug>
-    Register a running persona runtime with the Oomi backend.
-  personas heartbeat <slug>
-    Send a persona runtime heartbeat to the Oomi backend.
+    Register a running persona runtime with the Oomi backend. Prefer --local-port so the CLI can derive a reachable endpoint.
+  personas heartbeat <slug>
+    Send a persona runtime heartbeat to the Oomi backend. Prefer --local-port so the CLI can derive a reachable endpoint.
   personas runtime-fail <slug>
     Report persona runtime failure to the Oomi backend.
   persona-jobs start <jobId>

package/lib/personaRuntimeProcess.js

@@ -54,6 +54,7 @@ const LEGACY_WEBSPATIAL_TEMPLATE_FILE_RULES = [
     shouldReplace: (content) =>
       !content.includes('WEBSPATIAL_FORK_REPOSITORY') ||
       !content.includes('configurePersonaScene') ||
+      !content.includes('"--xr-back": String(back)') ||
       content.includes('WEBSPATIAL_FORK_COMMIT = "b2746721e4fe6b4f86dac0ea55938074eea00cda"') ||
       content.includes('WEBSPATIAL_FORK_COMMIT = "8904ac8fec48fe49ee14d1739237bd1afb2894fe"'),
   },
@@ -67,20 +68,22 @@ const LEGACY_WEBSPATIAL_TEMPLATE_FILE_RULES = [
   {
     relativePath: path.join('src', 'App.tsx'),
     shouldReplace: (content) =>
+      !content.includes('const isSpatialRuntime = __XR_ENV_BASE__.startsWith("/webspatial/avp");') ||
+      !content.includes('<Route path="home" element={<HomePage />} />') ||
       content.includes('<Route path="/" element={<HomePage />} />') ||
-      content.includes('<Route path="/scene" element={<ScenePage />} />'),
+      content.includes('<Route path="/scene" element={<ScenePage />} />') ||
+      content.includes('<Route index element={<HomePage />} />'),
   },
   {
     relativePath: path.join('src', 'pages', 'HomePage.tsx'),
     shouldReplace: (content) =>
       (content.includes('Open Spatial Scene') &&
       content.includes('Open Scene Route')) ||
-      (content.includes('Launch Spatial Surface') &&
-      content.includes('Open Browser Preview') &&
-      content.includes('Focused surface') &&
-      !content.includes('sceneMode')) ||
-      content.includes('enable-xr-monitor={sceneMode || undefined}') ||
-      content.includes('enable-xr={sceneMode || undefined}') ||
+      content.includes('sceneMode') ||
+      content.includes('configurePersonaScene();') ||
+      content.includes('persona-preview-card') ||
+      content.includes('Launch Spatial Surface') ||
+      content.includes('Open Spatial Preview') ||
       (
         content.includes('persona-panel persona-runtime" enable-xr') ||
         content.includes('persona-button" onClick={openPersonaScene} enable-xr') ||
@@ -91,6 +94,7 @@ const LEGACY_WEBSPATIAL_TEMPLATE_FILE_RULES = [
   {
     relativePath: path.join('src', 'pages', 'ScenePage.tsx'),
     shouldReplace: (content) =>
+      content.includes('sceneMode') ||
       (
         !content.includes('enable-xr-monitor') &&
         content.includes(
@@ -103,14 +107,23 @@ const LEGACY_WEBSPATIAL_TEMPLATE_FILE_RULES = [
         content.includes('Fork-backed proof points')
       ),
   },
+  {
+    relativePath: path.join('src', 'index.css'),
+    shouldReplace: (content) =>
+      !content.includes('html.is-spatial #root') ||
+      content.includes('radial-gradient(circle at top, rgba(205, 183, 143, 0.32), transparent 36%)'),
+  },
   {
     relativePath: path.join('src', 'App.css'),
     shouldReplace: (content) =>
+      content.includes('.persona-shell') ||
       (content.includes('.scene-panel') && !content.includes('.scene-interaction-grid')) ||
       content.includes('html.is-spatial .persona-runtime {') ||
       content.includes('html.is-spatial .persona-scene-root {') ||
       content.includes('html.is-spatial .persona-button,') ||
-      content.includes('html.is-spatial .persona-card,'),
+      content.includes('html.is-spatial .persona-card,') ||
+      !content.includes('.scene-workspace-grid') ||
+      !content.includes('.home-grid'),
   },
   {
     relativePath: 'vite.config.ts',

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "oomi-ai",
   "name": "Oomi Channel Plugin",
   "description": "Managed Oomi channel integration for OpenClaw.",
-  "version": "0.2.48",
+  "version": "0.2.49",
   "author": "Oomi",
   "license": "MIT",
   "openclawVersion": ">=0.5.0",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oomi-ai",
-  "version": "0.2.48",
-  "description": "Oomi OpenClaw channel plugin and bridge tooling",
+  "version": "0.2.49",
+  "description": "Managed Oomi chat, voice bridge, and XR-first persona scaffolding for OpenClaw",
   "bin": {
     "oomi": "bin/oomi-ai.js"
   },
@@ -29,14 +29,19 @@
       "defaultChoice": "npm"
     }
   },
-  "keywords": [
-    "oomi",
-    "openclaw",
-    "cli",
-    "voice",
-    "agent"
-  ],
-  "homepage": "https://oomi.ai",
+  "keywords": [
+    "oomi",
+    "openclaw",
+    "cli",
+    "plugin",
+    "voice",
+    "agent",
+    "persona",
+    "webspatial",
+    "xr",
+    "androidxr"
+  ],
+  "homepage": "https://www.oomi.ai",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/crispcode-io/oomi.git",

package/templates/persona-app/README.md

@@ -4,7 +4,7 @@ This project was scaffolded by `oomi personas scaffold`.
 
 ## Purpose
 
-This app is intended to run inside the Oomi client as a managed persona surface and uses the WebSpatial quick-example pattern as its base.
+This app is intended to run inside the Oomi client as a managed persona surface with an XR-first WebSpatial scaffold.
 
 ## Editable Zones
 
@@ -12,7 +12,19 @@ Only customize files in these zones unless Oomi explicitly changes the scaffold
 
 - `src/persona/`
 - `persona/`
-
+
+## XR Scaffold Contract
+
+The scaffold is considered healthy only when all of the following stay true:
+
+- the index route defaults to `ScenePage` in XR mode and keeps a valid browser route for non-spatial use
+- `ScenePage` calls `configurePersonaScene()` on mount
+- `ScenePage` logs `detectSpatialEnvironment()` so developers can verify the runtime is actually live
+- multiple meaningful surfaces use `enable-xr` and `xrStyle()`
+- `html.is-spatial` keeps the shell background transparent
+- `src/main.tsx` still exposes `snapdom` and `html2canvas` on `window`
+- the vendored WebSpatial fork metadata in `vendor/webspatial/FORK.md` stays intact
+
 ## Runtime Contract
 
 - Template version: `__OOMI_TEMPLATE_VERSION__`
@@ -25,11 +37,11 @@ Only customize files in these zones unless Oomi explicitly changes the scaffold
 
 ```bash
 npm install
-npm run dev
+npm run dev:avp
 ```
 
 ## Notes
 
-- Preserve the WebSpatial/Vite shell and the files in `public/`.
-- Keep the app safe to embed inside Oomi and future XR clients.
+- Preserve the WebSpatial/Vite shell, the runtime metadata files in `public/`, and the XR-specific route split between browser and scene modes.
+- Treat the scene route as the real XR workspace, not as a flat homepage with one outer `enable-xr` wrapper.
 - Customize persona behavior in `src/persona/`.