oomi-ai 0.2.50 → 0.3.1

package/README.md

@@ -1,554 +1,271 @@
 # oomi-ai
 
-Managed Oomi chat, voice bridge, and XR-first persona scaffolding for OpenClaw.
+Managed Oomi channel, bridge, voice, and persona app API tooling for OpenClaw.
 
-## At A Glance
+`oomi-ai` connects an OpenClaw machine to Oomi. Persona UI creation and rendering happen inside Oomi-managed systems. The OpenClaw machine uses API actions only.
 
-- 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
+The current model is:
 
-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
+- OpenClaw talks to Oomi through managed channel and bridge APIs.
+- Oomi clients render persona apps from approved templates, components, data bindings, actions, and permissions.
+- The agent may inspect and update persona app state through approved Oomi API actions.
+- The user adds persona apps from the Oomi client so platform permissions and data hydration happen in the right place.
 
 ## 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
+- Purpose: managed text transport through the Oomi backend channel API.
+
+2. Local bridge and 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, 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
-
-Global install:
-
-```bash
-pnpm add -g oomi-ai@latest
-```
-
-Fallback:
-
-```bash
-npm install -g oomi-ai@latest
-```
-
-Install the OpenClaw plugin:
-
-```bash
-openclaw plugins install oomi-ai@latest
-```
-
-Upgrade an existing machine:
-
-```bash
-pnpm add -g oomi-ai@latest
-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
-- generating or repairing XR-first managed persona apps
-
-Fast-path install flow:
-
-```bash
-oomi openclaw pair --app-url https://www.oomi.ai --no-start
-openclaw plugins install oomi-ai@latest
-oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai
-```
-
-Then apply the printed `channels.oomi.accounts.default` config and restart OpenClaw.
-
-## Configuration
-
-OpenClaw channel config lives under:
-
-```json
-{
-  "channels": {
-    "oomi": {
-      "defaultAccountId": "default",
-      "accounts": {
-        "default": {
-          "backendUrl": "https://api.oomi.ai",
-          "deviceToken": "...",
-          "defaultSessionKey": "agent:main:webchat:channel:oomi",
-          "requestTimeoutMs": 15000
-        }
-      }
-    }
-  }
-}
-```
-
-Required fields:
-- `backendUrl`
-- `deviceToken`
-
-Optional fields:
-- `defaultSessionKey`
-- `requestTimeoutMs`
-
-## Runtime Model
-
-There are two runtime contracts worth understanding.
-
-### Managed Text Chat
-
-Managed text chat uses the OpenClaw channel extension and the Oomi backend channel API.
-This path is the more stable contract and should be preferred when evaluating the plugin for normal chat.
-
-### Device-Backed Chat And Voice
-
-Device-backed chat and voice use the local bridge.
-That bridge:
-- keeps a broker socket open to Oomi
-- opens local gateway sessions on demand
-- enforces `connect`-first request ordering
-- preserves or synthesizes `idempotencyKey` for `chat.send`
-- keeps voice-session faults from poisoning normal provider health where possible
-
-This is the part of the package most likely to matter when debugging voice turn failures.
-
-For managed cloned-voice replies, the canonical contract is:
-- visible assistant `content` stays user-facing
-- hidden `metadata.spoken` carries the backend TTS payload
-- the shared helper in `lib/spokenMetadata.js` is used by both the extension and the local bridge to preserve or normalize that sidecar before it reaches the backend
-
-The backend cloned-voice path is intentionally strict. If `metadata.spoken` does not reach Oomi, backend TTS fails instead of speaking a flat fallback voice.
-
-## Bridge Logging
-
-The bridge is intentionally quiet by default in production so normal deploys do not spam logs with frame-level transport noise.
-
-To enable verbose bridge tracing temporarily, set:
-
-```bash
-OOMI_BRIDGE_DEBUG=1
-```
-
-With that flag enabled, the bridge will emit low-level session, frame, and spoken-metadata debug logs again.
-
-## Local TTS Validation
-
-If you are developing this package inside the Oomi repo, you can now validate the managed voice path locally before publishing.
-
-This local gate does three things:
-- replays an assistant `chat.final` frame through the same spoken-metadata normalization path used by the OpenClaw extension and the bridge
-- feeds that normalized frame into the Rails backend replay harness
-- optionally calls the real Qwen cloned-voice provider and confirms that audio deltas come back
-
-Important:
-- this is a repo developer workflow, not a generic npm-only operator command
-- it expects the Oomi repo checkout, the Rails backend, and local provider env vars
-- the real-provider replay can auto-enroll a disposable default sample voice profile from `assets/voice/source/nemu-enrollment-sample.mp3`
-
-Assistant-final contract only:
-
-```bash
-oomi openclaw debug assistant-final --text "Hey Justin! How is the testing going?" --json
-```
-
-Full local backend replay:
-
-```bash
-oomi openclaw debug tts-pipeline --text "When your voice reaches me, it gets turned into text, I read it and think about it, then I speak back through the managed chat session." --json
-```
-
-Real Qwen provider replay:
-
-```bash
-oomi openclaw debug tts-pipeline --text "When your voice reaches me, it gets turned into text, I read it and think about it, then I speak back through the managed chat session." --live-provider --env-file .env.local --provider-timeout-ms 20000 --json
-```
-
-What a good result looks like:
-- `backend.success = true`
-- `managed.assistantSpeechFinal.present = true`
-- `qwen.errorCode = null`
-- `qwen.audioDeltaCount > 0` when `--live-provider` is used
-
-This is the preferred pre-publish gate for managed voice regressions, because it is much faster than publishing to npm and testing through a live OpenClaw machine first.
-
-## Local OpenClaw Dev Harness
-
-For plugin/runtime work, the preferred pre-publish loop is:
-
-1. run the repo-local CLI directly from source
-2. run the same flow inside the Dockerized OpenClaw dev harness using a local packed tarball
-3. only then update a real OpenClaw machine
-
-Fast source smoke from the repo checkout:
-
-```bash
-node packages/oomi-ai/bin/oomi-ai.js openclaw debug persona-runtime --name "Chef Dev" --json
-```
-
-Containerized real-runtime smoke:
-
-```bash
-docker compose -f docker/openclaw-dev/compose.yml build openclaw-dev
-docker compose -f docker/openclaw-dev/compose.yml up -d openclaw-dev
-docker compose -f docker/openclaw-dev/compose.yml exec -T openclaw-dev openclaw gateway health --url ws://127.0.0.1:18789 --token dev-gateway-token --json
-docker compose -f docker/openclaw-dev/compose.yml exec -T openclaw-dev oomi-local openclaw debug persona-runtime --name "Chef Dev" --json
+- Purpose: pair a device, manage the OpenClaw bridge worker, and support managed gateway traffic for device-backed chat and voice.
+
+3. Persona app API tools
+
+- Files: `persona-app/*`, `lib/personaApiClient.js`, `bin/oomi-ai.js`
+- Purpose: inspect account-linked component-composed persona apps and apply approved backend actions.
+
+4. Permissioned context tools
+
+- Files: `lib/personaApiClient.js`, `bin/oomi-ai.js`
+- Purpose: read user-approved Oomi backend context, such as HealthKit summaries synced by the mobile app.
+
+5. Agent/operator instructions
+
+- Files: `agent_instructions.md`, `skills/oomi/*`
+- Purpose: tell OpenClaw agents how to connect, repair, and use Oomi without local UI code generation.
+
+## Boundary
+
+Persona UI is an Oomi-managed client capability, not an OpenClaw-machine responsibility.
+
+This package exposes connection, bridge, voice, and persona app state APIs. It does not include a local persona app workspace, local persona runtime manager, queued UI job runner, or app framework bundle.
+
+## Install And Upgrade
+
+Global install:
+
+```bash
+pnpm add -g oomi-ai@latest
+```
+
+Fallback:
+
+```bash
+npm install -g oomi-ai@latest
+```
+
+Install or update the OpenClaw plugin:
+
+```bash
+openclaw plugins install oomi-ai@latest
+```
+
+After upgrading, refresh the running bridge so stale gateway connections do not keep using the previous package:
+
+```bash
+oomi openclaw refresh --skip-version-check
+oomi openclaw bridge ps
+```
+
+If the bridge still looks stale, restart it explicitly:
+
+```bash
+oomi openclaw bridge restart --detach
+oomi openclaw bridge ps
+```
+
+On macOS supervised installs:
+
+```bash
+oomi openclaw bridge service restart
+oomi openclaw bridge service status
 ```
 
-The local managed-chat smoke uses a dedicated session key separate from the browser shell so repeated sentinel prompts do not leak into the interactive conversation history.
-
-`oomi-local` is a deterministic container wrapper that executes the installed packed `oomi-ai` artifact directly with Node. In the Docker harness, it is only the package wrapper. The agent itself is the real OpenClaw runtime running in the foreground.
-
-Shared profile contract smoke:
-
-```bash
-node packages/oomi-ai/bin/oomi-ai.js openclaw profile init --profile-id oomi-dev-local --label "Oomi Local Dev" --backend-url http://127.0.0.1:3001 --device-token dev-device-token --json
-node packages/oomi-ai/bin/oomi-ai.js openclaw profile apply --profile ~/.openclaw/oomi-openclaw-profile.json --openclaw-home ~/.openclaw --json
-```
-
-What the harness does:
-
-- bootstraps an isolated OpenClaw home rooted at `HOME/.openclaw`
-- runs `openclaw onboard --non-interactive ...`
-- writes and applies `HOME/.openclaw/oomi-dev-profile.json` using the same shared profile contract the future onboarding UI and hosted-agent bootstrap should use
-- enables the Oomi channel account through that applied profile and relies on local OpenClaw plugin auto-discovery for the installed `oomi-ai` plugin
-- writes device identity material used by the `oomi-ai` bridge tooling
-- packs the local `packages/oomi-ai` checkout into a `.tgz`
-- installs that tarball globally in the container
-- installs the same tarball as a real OpenClaw plugin
-- defaults model auth to `oomi-managed` so onboarding/bootstrap does not require end-user provider keys
-- runs `openclaw gateway` as the foreground container process
-
-Useful env overrides for local integration:
-
-- `OOMI_DEV_BACKEND_URL`
-- `OOMI_DEV_DEVICE_TOKEN`
-- `OOMI_DEV_MODEL_AUTH_MODE`
-- `OPENCLAW_GATEWAY_TOKEN`
-- `OPENCLAW_GATEWAY_PASSWORD`
-
-Recommended local modes:
-
-- onboarding/runtime checks without provider keys
-  - `OOMI_DEV_MODEL_AUTH_MODE=oomi-managed`
-- internal real-response smoke before publish
-  - `OPENROUTER_API_KEY=...`
-  - optional explicit override: `OOMI_DEV_MODEL_AUTH_MODE=provider-env`
-
-The default container config is intentionally safe for onboarding and runtime testing. It does not require a published npm version, and it does not require end-user provider keys.
-
-To make the Dockerized OpenClaw runtime actually answer managed chat locally today, add this to the repo `.env.local`:
+Healthy update expectation:
+
+- exactly one bridge worker is active
+- the worker reports the newly installed package version
+- bridge status reaches `connected`
+
+## Standard Connect Flow
+
+Pair the machine:
 
 ```bash
-OOMI_DEV_MODEL_AUTH_MODE=provider-env
-OPENROUTER_API_KEY=<your-openrouter-key>
+oomi openclaw pair --app-url https://www.oomi.ai --no-start
 ```
 
-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
+Print the OpenClaw config:
 
-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>` only for repo-local manifest work, not for the normal managed Oomi persona flow
-- `oomi personas create-managed <slug>` to create the backend managed persona record before launch or runtime registration
-- `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
+```bash
+oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai
+```
 
-Managed runtime and recovery commands:
+Apply the printed `channels.oomi.accounts.default` config and restart OpenClaw.
+
+Start or repair the bridge:
 
 ```bash
-oomi personas launch-managed market-analyst --workspace-root ~/.openclaw/workspace/personas --force-install --json
-oomi personas status market-analyst
-oomi personas stop market-analyst
-oomi personas delete market-analyst
-# recovery only, after create-managed already exists
-oomi personas runtime-register 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."
+oomi openclaw bridge ensure --detach
 ```
 
-Notes:
+## Configuration
+
+OpenClaw channel config lives under:
+
+```json
+{
+  "channels": {
+    "oomi": {
+      "defaultAccountId": "default",
+      "accounts": {
+        "default": {
+          "backendUrl": "https://api.oomi.ai",
+          "deviceToken": "...",
+          "defaultSessionKey": "agent:main:webchat:channel:oomi",
+          "requestTimeoutMs": 15000
+        }
+      }
+    }
+  }
+}
+```
 
-- 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.
-- Do not use manual `npm run dev` as the first-time persona launch path for managed Oomi personas.
+Required fields:
 
-Exact managed persona creation order:
+- `backendUrl`
+- `deviceToken`
+
+Optional fields:
+
+- `defaultSessionKey`
+- `requestTimeoutMs`
+
+## Persona App API Tools
+
+Component-composed persona apps are the default Oomi mini-app path. Use these commands when the user asks about or updates an existing Oomi persona app such as Fitness Today:
 
 ```bash
-export WORKSPACE_ROOT="$HOME/.openclaw/workspace/personas"
-export SLUG="tokyo-guide"
-export NAME="Tokyo Guide"
-export DESCRIPTION="Personal travel assistant for Tokyo trip planning - itineraries, food, culture, and summer tips for July"
-
-# 1. Scaffold the local app workspace
-oomi personas scaffold "$SLUG" \
-  --name "$NAME" \
-  --description "$DESCRIPTION" \
-  --out "$WORKSPACE_ROOT/$SLUG" \
-  --force
-
-# 2. Verify scaffold actually wrote files
-test -f "$WORKSPACE_ROOT/$SLUG/persona.json"
-test -f "$WORKSPACE_ROOT/$SLUG/oomi.runtime.json"
-test -f "$WORKSPACE_ROOT/$SLUG/package.json"
-
-# 3. Create the backend persona record first
-oomi personas create-managed "$SLUG" \
-  --name "$NAME" \
-  --description "$DESCRIPTION" \
-  --json
-
-# 4. Launch the managed runtime and register it with Oomi
-oomi personas launch-managed "$SLUG" \
-  --workspace-root "$WORKSPACE_ROOT" \
-  --force-install \
-  --json
-
-# 5. Verify local runtime state exists
-test -f "$WORKSPACE_ROOT/$SLUG/.oomi/runtime.json"
-cat "$WORKSPACE_ROOT/$SLUG/.oomi/runtime.json"
-
-# 6. Verify Oomi-local status
-oomi personas status "$SLUG" --json
-
-# 7. Send a heartbeat using the actual assigned port
-PORT="$(jq -r '.localPort' "$WORKSPACE_ROOT/$SLUG/.oomi/runtime.json")"
-oomi personas heartbeat "$SLUG" \
-  --local-port "$PORT" \
-  --json
+oomi persona-apps list --json
+oomi persona-apps show fitness-today --json
+oomi persona-apps apply-action fitness-today --action fitness.complete_workout --payload-json '{"goalId":"easy-run","minutes":20}' --json
 ```
 
-Rules for that flow:
+Rules for agents:
 
-- scaffold first
-- verify scaffold wrote files before backend creation
-- create-managed before any runtime registration or heartbeat
-- launch-managed instead of manual `npm run dev`
-- heartbeat only after `.oomi/runtime.json` exists
-- fail fast if any `--json` command does not return success
-- never treat local runtime success as backend registration success
+- Answer from returned `appState.bindings`, not from memory.
+- Apply updates only through approved `persona-apps apply-action` actions.
+- If the persona app does not exist, tell the user to add it from the Oomi client first.
+- Do not create local persona UI projects.
 
-Do not do this for first-time creation:
+For the Fitness v0 slice:
 
 ```bash
-oomi personas runtime-register "$SLUG" --local-port 4791
-oomi personas launch-managed "$SLUG"
-npm run dev &
+oomi persona-apps apply-action fitness-today --action fitness.complete_goal --payload-json '{"goalId":"easy-run"}' --json
+oomi persona-apps apply-action fitness-today --action fitness.complete_workout --payload-json '{"goalId":"easy-run","minutes":20}' --json
 ```
 
-That sequence is wrong because `runtime-register` and `heartbeat` assume the backend persona already exists, `launch-managed` only auto-creates when the persona is missing and `--name` is present, and manual `npm run dev` bypasses the managed runtime state contract.
+## Context Tools
 
-Queued-job shortcut:
+Use context tools when the user asks a data-backed question that should come from Oomi-approved mobile permissions, not model memory. For health and fitness questions, read the latest backend HealthKit context first:
 
 ```bash
-oomi personas create-managed cooking-persona --name "Cooking Persona" --description "Private cooking workspace for recipes, meal planning, and kitchen notes."
+oomi context health --json
 ```
 
-Use that shortcut only when the backend and running bridge are already set up to consume the queued `persona_job` automatically. Do not confuse it with the explicit scaffold + launch flow above.
+Rules for agents:
+
+- Answer from `healthContext.summary` and `healthContext.derived`.
+- Respect `healthContext.agentGuidance.canAnswerFromContext`.
+- If context is `missing`, `needs_sync`, `permission_denied`, `disabled_by_user`, or `unavailable`, tell the user what repair action is needed instead of guessing.
+- If context is `stale`, mention freshness when timing matters.
+- Do not ask the phone for HealthKit directly; the Oomi mobile app syncs HealthKit to the backend.
+
+## Voice Contract
+
+Managed voice uses the same Oomi plugin and bridge layer as managed chat.
+
+For assistant replies, visible chat text stays user-facing. Optional hidden TTS metadata may live at `metadata.spoken`:
+
+```json
+{
+  "metadata": {
+    "spoken": {
+      "text": "Speech-optimized text for TTS only.",
+      "language": "English",
+      "instructions": "Speak with warm, upbeat conversational energy and natural pacing."
+    }
+  }
+}
+```
+
+Rules:
+
+- visible `content` is the source of truth for chat rendering
+- `metadata.spoken.text` is backend TTS input only
+- visible chat text should not contain raw speaking tags
+- the package preserves valid `metadata.spoken`
+- if omitted, the package may synthesize a bounded fallback from visible assistant text
+
+## Health Checks
+
+Use these when chat or voice is failing:
+
+```bash
+oomi openclaw bridge ps
+oomi openclaw bridge service status
+oomi openclaw status
+tail -f ~/.openclaw/logs/oomi-bridge-live.log
+tail -f ~/.openclaw/logs/gateway.log
+tail -f ~/.openclaw/logs/gateway.err.log
+```
+
+Bridge status meanings:
+
+- `starting`: bridge booting or waiting for managed subscription
+- `connected`: ready for managed chat and voice traffic
+- `reconnecting`: transport dropped and retry is scheduled
+- `degraded`: bridge caught a runtime fault but is still alive
+- `error`: startup or auth failure blocked useful operation
+- `stopped`: not running or intentionally stopped
+
+## Troubleshooting
+
+Duplicate plugin id warning:
+
+- Cause: multiple discoverable `oomi-ai` installs.
+- Action: remove stale extension copies and reinstall once.
+
+`invalid handshake: first request must be connect`:
+
+- Cause: a gateway request was sent before `connect` had been accepted.
+- Action: update `oomi-ai`, restart the bridge, and confirm only one bridge worker is running.
+
+STT works but the assistant does not reply:
+
+- Cause: the voice turn likely reached Oomi, but the managed gateway or OpenClaw run failed later.
+- Action: inspect `gateway.log`, `gateway.err.log`, and the session JSONL for auth, network, or bridge restart errors.
+
+Bridge keeps using an old package after update:
 
-If you want to explicitly host or reuse the persona app on the OpenClaw machine outside the queued-job path, use:
-
-```bash
-oomi personas launch-managed cooking-persona --entry-url https://your-relay.example/oomi/cooking-persona
-```
-
-This command:
+- Action: run `oomi openclaw refresh --skip-version-check`.
+- If still stale: run `oomi openclaw bridge restart --detach`.
+- On macOS service installs: run `oomi openclaw bridge service restart`.
+- Confirm with `oomi openclaw bridge ps`.
 
-- reuses `OPENCLAW_WORKSPACE/personas/<slug>` as the stable workspace
-- scaffolds only when the workspace is missing
-- installs dependencies only when needed or forced
-- allocates or reuses a free local port
-- starts or reuses the local runtime
-- registers the runtime URL back to Oomi unless `--no-register` is set
+## Developer Verification
 
-For existing managed personas that are already open in Oomi, the safe edit flow is:
+From `packages/oomi-ai`:
 
 ```bash
-oomi personas status <slug> --json
+npm run check
+npm test
+npm pack --dry-run
+npm publish --dry-run --no-git-checks --access public
 ```
 
-The agent should use `editableWorkspacePath` from that output as the authoritative directory for reads, edits, and verification. `compatibilityWorkspacePath` is only a fallback for older installs.
-
-## Bridge Health States
-
-The bridge status file is written locally and should roughly be interpreted as:
-- `starting`: process booting or waiting for managed subscription
-- `connected`: broker connected and managed subscription confirmed
-- `reconnecting`: broker or gateway transport dropped and reconnect is scheduled
-- `degraded`: bridge is still alive but hit a runtime fault that needs attention
-- `error`: startup or auth-level failure that prevents useful operation
-- `stopped`: bridge is not running or was intentionally stopped
-
-For voice support, a `voice_session_*` failure should be treated as narrower than a full provider outage.
-
-## Troubleshooting
-
-### `invalid handshake: first request must be connect`
-
-Meaning:
-- a gateway request was forwarded before the session had accepted `connect`
-
-What to check:
-- update to the latest `oomi-ai`
-- restart the bridge worker
-- confirm only one active bridge worker exists for the device
-
-### `duplicate plugin id detected`
-
-Meaning:
-- OpenClaw can see more than one `oomi-ai` plugin source
-
-What to check:
-- ensure there is only one active install under OpenClaw plugin discovery paths
-- remove stale local extension copies before reinstalling
-
-### Bridge keeps flipping between `reconnecting`, `degraded`, or `stopped`
-
-What to check:
-- `oomi openclaw bridge ps`
-- `oomi openclaw bridge service status`
-- `tail -f ~/.openclaw/logs/oomi-bridge-live.log`
-- `tail -f ~/.openclaw/logs/gateway.log`
-
-If the process is alive but runtime faults are being caught, expect `degraded` rather than an immediate hard stop.
-
-### Voice STT works but the agent does not answer
-
-This usually means one of these:
-- the managed gateway/device side is not actually ready
-- the bridge or agent run failed after delivery
-- the OpenClaw run stopped with an upstream provider `network_error`
-
-In that situation, inspect:
-- `~/.openclaw/logs/gateway.log`
-- `~/.openclaw/logs/gateway.err.log`
-- the relevant session JSONL in `~/.openclaw/agents/main/sessions/`
-
-### Voice text works but cloned TTS fails with `MISSING_SPOKEN_METADATA`
-
-Meaning:
-- the assistant text arrived
-- the backend voice relay never received valid hidden `metadata.spoken`
-
-What to check:
-- run the local replay gate before publishing:
-  - `oomi openclaw debug assistant-final --text "..."`
-  - `oomi openclaw debug tts-pipeline --text "..."`
-- 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 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:
-
-```bash
-cd packages/oomi-ai
-node --test test/*.test.mjs
-npm pack --dry-run
-```
-
-For managed voice changes, do not stop at the package tests. Run the local replay gate from the repo root as well, especially before publishing:
-
-```bash
-oomi openclaw debug tts-pipeline --text "Local managed voice validation text." --json
-oomi openclaw debug tts-pipeline --text "Local managed voice validation text." --live-provider --env-file .env.local --provider-timeout-ms 20000 --json
-```
-
-## Release Process
-
-Before publishing:
-
-```bash
-cd packages/oomi-ai
-node --test test/*.test.mjs
-npm pack --dry-run
-```
-
-For voice-related changes, also run the repo-backed local replay gate before publish:
-
-```bash
-oomi openclaw debug tts-pipeline --text "Local managed voice validation text." --json
-oomi openclaw debug tts-pipeline --text "Local managed voice validation text." --live-provider --env-file .env.local --provider-timeout-ms 20000 --json
-```
-
-Then publish the bumped version:
-
-```bash
-pnpm check
-pnpm publish --dry-run --no-git-checks --access public
-pnpm publish --access public
-```
+Expected package contents are restricted by the `files` allowlist in `package.json`.