oomi-ai 0.11.0 → 0.12.1

package/README.md

@@ -1,436 +1,436 @@
-# oomi-ai
-
-Connect OpenClaw, Hermes, Grok Bot, and other agents to Oomi through an explicit runtime adapter.
-
-`oomi-ai` connects the selected local agent to Oomi. Persona UI creation and rendering happen inside Oomi-managed systems. The OpenClaw machine uses API actions only.
-
-The current model is:
-
-- The selected agent 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
-
-1. OpenClaw channel extension
-
-- File: `openclaw.extension.js`
-- 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 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.
-
-## Connect Your Local Agent
-
-Connect the agent the user is speaking to. Identify your runtime, bot/profile, and actual host first. Computer access does not mean you run on that computer. Never substitute another installed agent.
-
-## Choose a connection by interface (oomi-ai 0.8.5+)
-
-Run setup on the host where **this agent** runs. A Grok Bot with access to someone's Mac still runs on its Grok Bot host; connecting an OpenClaw agent on that Mac does not connect the Grok Bot. No new model API key or replacement bot is needed.
-
-1. Identify yourself from your current runtime context: bot/profile identity, host, and conversation behavior. Do not guess from installed executables or names.
-2. Run `oomi capabilities`. OpenClaw and Hermes have native adapters. Grok Bot uses its own local gateway through the adapter described below. An unlisted brand is not automatically unsupported: inspect its documented message input **and completed-reply** interfaces (CLI, API, SDK, webhook, or inbound channel).
-3. For another runtime, use `--runtime command` to wrap those interfaces and return `{text, sessionId?}` only when the same agent has finished. A health endpoint or an accepted/queued response is not a final reply. If no supported input or reply interface exists, state that specific missing capability; never invent one or select another agent.
-4. Preserve identity, memories and host approvals. Say whether you resume an exact existing conversation or keep an Oomi conversation with the same agent. Verify a real reply before sharing an Auth Link; verify delivery in Oomi before claiming completion.
-
-### Grok Bot: connect the existing bot
-
-On **this bot's own Linux host**, install/update the package through the normal host approval flow, then run:
-
-```bash
-oomi connect --runtime grokbot --name YOUR_CONNECTION --agent-id YOUR_BOT_UUID --agent-name "Your name" --app-url https://www.oomi.ai
-```
-
-Use your exact bot UUID from your runtime context. Never choose whichever bot happens to be active on a shared computer. Run `oomi grokbot instructions --name YOUR_CONNECTION --agent-id YOUR_BOT_UUID` for the focused setup guide. The package uses the host's existing private local gateway; **do not ask the user to copy a webhook URL/key or create a routine**. Fresh connections require no `grokbot.json`. Existing explicit webhook configurations remain supported. If the local gateway is missing or incompatible, report that specific error and keep the selected identity; do not invent another input interface or substitute an agent.
-
-Setup returns **queued**, then waits in the background. Finish your current bot turn immediately so the verification can execute; waiting for your own verification in that turn deadlocks the host. The package installs its private Oomi delivery skill and waits until this bot has loaded it. Incoming chat shows the original message with a small skill tag; the skill claims the private request and submits its final reply. Missing or locally modified skills fail before sending; do not replace them with instruction walls in chat. Continue only for `status: claimed`. A verification answer must be exactly `OOMI_OK`. The reply command reports one Auth Link only after verification, pairing and bridge subscription succeed. Show the Auth Link to the user. If pending, finish the turn and use `oomi grokbot status --name YOUR_CONNECTION` later. Queued is not connected. Acceptance by the host is not a completed answer.
-
-Use explicit `--connection YOUR_CONNECTION` for Oomi account commands: a shared host does not inherit the bridge's environment. Text and voice transcripts are supported; photos are rejected. Oomi supplies conversation history; exact Grok Bot desktop/DM conversation continuation is not guaranteed. Host approvals remain in Grok Bot. Do not repeat uncertain or already-claimed actions; inspect the original run. Reconnect reuses verification and pairing; `oomi verify --name YOUR_CONNECTION` explicitly queues a new model verification.
-
-Oomi uses systemd user services where available. On Linux hosts without systemd, it automatically supervises bridge worker exits for the current host session. **After the whole cloud computer restarts, rerun the same connect command.** This fallback cannot start itself at boot. Use `oomi status --name YOUR_CONNECTION --json` to inspect recovery. A host-provided external supervisor can instead run `oomi bridge start --name YOUR_CONNECTION --service-managed` with explicit `connect --no-service`. Optional `--skills-dir PATH` installs the guide in a host-supported directory; otherwise use `oomi instructions`.
-
-The direct adapter targets the installed Grok Bot local gateway contract. An incompatible provider update fails closed. Each real host must pass verification, then an authorized Oomi message round trip, before claiming it is connected end to end.
-
-## Updating Oomi safely
-
-When the user asks you to update Oomi, read `oomi instructions` first; it supersedes copied setup/restart recipes. Keep the same connection on the same computer.
-
-1. Run `oomi update --connection NAME` (omit the selector for default OpenClaw). This only checks versions. If already current, report that and stop: do not reinstall or restart "to be sure."
-2. If an update exists, run the returned exact-version npm install command **alone**, through the runtime's normal approval flow. Do not append redirections, status checks or restarts. If installation is denied, fails, or cannot be verified, leave the bridge alone and explain the approval/error. Never disable security checks, retry through another executor, or enable blanket unattended approvals.
-3. After successful installation, check `npm list -g oomi-ai --depth=0` and `oomi update` separately. Only then run `oomi bridge repair --connection NAME`.
-4. A running 0.8.1+ supervised bridge queues its restart until active replies finish and queued phone replies are saved. If the result is `queued`, finish your reply now; do not wait for your own turn to end, poll in a loop, or claim completion. `oomi status --connection NAME --json` subsequently reports maintenance `completed`/`failed` and the running `packageVersion`. Pairing and conversations stay intact.
-
-For packages before 0.8.1 (no `oomi update` command), read the published guide, check `npm list -g oomi-ai --depth=0` and `npm view oomi-ai version` in separate commands. If equal, stop. Otherwise install the exact returned version through normal approvals. The first restart of an older or unsupervised bridge must happen from an independent host terminal/agent session, outside the Oomi conversation it would terminate. New CLI commands refuse to stop their own older host. After that bootstrap, in-chat restarts use the deferred path.
-
-Hermes single-query mode has no interactive approval surface. If its package/security check requires a human, tell the user to approve/run the exact install in an approval-capable host session, then continue there. A blocked install is not a reason to restart. Oomi does not override host permissions. `bridge repair` is also available for an actual connection fault when no package update is needed.
-
-## Standard Connect Flow
-
-For a new installation (for an existing installation, use the safe update flow below):
-
-```bash
-npm install -g oomi-ai@latest
-```
-
-Run ONE command for your runtime:
-
-```bash
-# OpenClaw (reuses existing default OpenClaw pairing)
-oomi connect --runtime openclaw --app-url https://www.oomi.ai
-
-# Hermes (separate connection, no OpenClaw required)
-oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
-
-# Another local agent, through its own adapter
-oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
-```
-
-Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. With oomi-ai 0.8.2+, an already-open Hermes conversation uses its existing local gateway owner and exact profile/session. Oomi attaches as another client; it never closes desktop, clears history, deletes a session lock, or substitutes a new chat. When no live owner exists, an Oomi-owned conversation (no `--resume`) runs on a warm `hermes acp` process with oomi-ai 0.9.0+: replies stream as they are written and stop when the person interrupts. From 0.9.1 the bridge starts Hermes and reopens recent conversations ahead of time (at bridge start and when a call opens), so the first message doesn't wait for Hermes to start. Hermes permission requests are denied, as `chat --quiet` denies dangerous commands; ordinary file edits run as they do in quiet mode. A conversation moving from the CLI starts a new Hermes session that receives the recent Oomi history. `--resume` conversations, Hermes without ACP, and `--hermes-transport cli` use `chat --quiet --query-file -` and resume the exact returned `session_id` on subsequent turns.
-
-Shared desktop conversations require Hermes's loopback WebSocket gateway, active-session discovery, and durable prompt/reply row IDs. Busy conversations ask you to retry after the current task. If a simultaneous desktop send queues your message without a reply receipt, or the connection drops after sending, check the same Hermes chat before resending. Oomi cannot safely repeat an uncertain action. Human approvals stay in the existing Hermes desktop UI. Shared photo submission is not yet supported; use Hermes desktop for that photo. Older or terminal-only owners without a shared gateway receive an actionable error, never a competing process. The shared owner keeps its existing environment, so use the explicit Oomi `--connection NAME` for account commands.
-
-The command verifies a real local reply, reuses saved credentials or pairs once, starts the bridge, waits for Oomi's subscription, then creates a single-use Auth Link. Failed verification means setup is incomplete: repair the selected runtime, never substitute a different one.
-
-The installer is an alternative to npm plus connect, and requires an explicit runtime:
-
-```bash
-curl -fsSL https://www.oomi.ai/install.sh | bash -s -- --runtime hermes --name hermes
-```
-
-## Agent settings and identity backups
-
-If you already have a name, add `--agent-name "Your name"` to `oomi connect`. The separate `--name` / `--connection` flag identifies a saved connection, not your display name. Do not invent a name merely to fill this field. Reconnecting preserves the account's saved name.
-
-You can read and update your own Oomi settings from any chat where you have your local CLI, including channels outside Oomi. Always select the same connection:
-
-```bash
-oomi identity get --connection hermes
-oomi identity set --connection hermes --agent-name "Miso" --bio "A curious everyday companion" --profile-image-url "https://example.com/miso.png"
-```
-
-Omit `--connection` for the default OpenClaw connection. Any of the three setting flags can be supplied alone. Use an empty bio/image value to clear it. Profile images are HTTPS URLs; 3D models are reserved for Oomi and coming soon.
-
-When a user changes settings on the website, the bridge delivers a versioned notice to your actual local runtime, including while no Oomi chat is open. Before applying it, read the current identity again. Persist the current name in your own identity file so your other channels know it: OpenClaw normally uses IDENTITY.md, Hermes uses SOUL.md. Keep the rest of your personality and memories intact. Save the short profile/image as Oomi settings, not replacement personality instructions.
-
-After saving, acknowledge the exact `identityId` and `revision` returned by `identity get`:
-
-```bash
-oomi identity acknowledge --connection hermes --identity-id <identityId> --revision <revision>
-```
-
-Never acknowledge a version you did not save. A 409 means the settings changed; read and apply the newer version. The website distinguishes pending delivery, agent notified, and agent confirmed. A reply alone does not mean your local identity was updated. Existing running conversations may retain older context until they reload identity; tell the user if a runtime requires a new conversation or restart.
-
-Backups are opt-in. Obtain the user's choice of files and inspect those files for secrets before uploading. Do not upload an entire workspace, credentials, user profiles, memories, or chat history. Supported files are SOUL.md, IDENTITY.md, AGENTS.md, and TOOLS.md, at most 64 KiB each. Identity files can themselves contain private information; the filename allowlist is not a secret scanner.
-
-```bash
-oomi identity backup --connection hermes --files '["/absolute/path/SOUL.md"]'
-oomi identity backups --connection hermes
-oomi identity restore --connection hermes --snapshot <id> --output /path/to/new-review-folder
-```
-
-Backups include current Oomi profile settings and deduplicate identical contents. Up to 50 versions are retained; the user can download or delete versions in Agent settings. Restore exports into a new private folder and refuses to overwrite any existing directory. Review the files before applying them manually; restoration does not automatically rename Oomi or modify a running agent. Disconnecting an agent preserves its backups under the original owner.
-
-## Required User-Facing Result
-
-Return the verified runtime/profile and the printed Auth Link. The human opens the link, signs in, and approves ownership. Only after a message receives a reply in Oomi can you claim end-to-end delivery works. Never expose raw tokens, pairing codes, or gateway credentials.
-
-## Repair and Reconnect
-
-Use the SAME connection name from setup. Omit `--name` for default OpenClaw.
-
-```bash
-oomi status --name hermes --json
-oomi verify --name hermes
-oomi bridge repair --name hermes
-oomi invite --name hermes --app-url https://www.oomi.ai
-```
-
-Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses saved pairing and verification; only the first connection or an explicit `oomi verify` sends a model probe. A different command, profile, or working directory requires a new connection name, so one agent cannot silently replace another. Named connections store private state and logs under `~/.oomi/connections/<name>`; default OpenClaw keeps `~/.openclaw`. Since 0.8.0, `connect` installs a separate automatic-start service for each connection: macOS launchd or Linux systemd user. It restarts an exited worker and starts at the next login/user session. Linux servers can start at boot and remain running after logout when the host administrator enables user lingering (`loginctl enable-linger <user>`); `oomi bridge service status --name hermes` reports whether this is enabled. WSL needs systemd and a running WSL instance; native Windows does not yet have an automatic service installer. A sleeping, powered-off, or disconnected computer remains unavailable.
-
-Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To update an existing connection on **each computer**, follow Updating Oomi safely above. Repair preserves pairing and conversations. On a running 0.8.1+ supervised bridge it queues a safe restart and reports pending work; on a stopped bridge it installs/starts supervision and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
-
-Use `oomi bridge service status --name hermes --json` to inspect startup protection. `oomi bridge stop --name hermes` disables automatic startup and stops only that connection; `oomi bridge start --name hermes` enables it again. `oomi bridge service uninstall --name hermes` removes startup management without deleting saved state. The legacy `oomi openclaw bridge service` command remains supported.
-
-For containers or an existing external supervisor, use `connect --no-service` explicitly, then configure that supervisor to run `oomi bridge start --name <name> --service-managed` in the foreground. Detached mode alone does not provide crash/login recovery. Setup fails with an actionable error when the service manager is unavailable; never claim automatic startup in that case. The phone's Reconnect button reconnects the client; it cannot wake a computer or start a missing host process.
-
-`connected` describes the broker transport. Inspect `runtimeReady`, `verifiedAt`, and `lastReplyAt` separately. A process ID, Auth Link, or broker connection alone does not prove the agent is answering.
-
-## Other Runtime Adapter Contract
-
-`--command` is a JSON argv array, not a shell command. Write an adapter against the selected agent's documented API or noninteractive CLI. The executable reads one JSON object from stdin:
-
-```json
-{"sessionKey":"...","message":"...","idempotencyKey":"...","history":[],"runtimeSessionId":"..."}
-```
-
-It writes `{"text":"final reply","sessionId":"optional-runtime-session"}` to stdout and exits zero on success. Errors must exit nonzero; diagnostics go to stderr. Resume `runtimeSessionId`, or use `history` for stateless runtimes. Never bypass the agent's existing approval rules. The adapter supports text (including voice transcripts); attachments are rejected explicitly. A failed or interrupted action is not silently repeated. Check the agent before sending a new message after a failure.
-
-## OpenClaw Channel Extension
-
-Managed web text and voice connect through the local gateway. The optional OpenClaw `oomi-ai` channel plugin handles agent-initiated channel output. If you need that path, install the plugin, enable its entry in OpenClaw, apply `oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai` locally, and restart OpenClaw. Never share that secret config with the user. Disabling the plugin does not explain a gateway protocol rejection.
-
-OpenClaw gateway protocols 3 and 4 are negotiated independently of the broker. For an existing install affected by a protocol mismatch, update `oomi-ai`, then run `oomi connect --runtime openclaw --app-url https://www.oomi.ai`.
-
-
-## 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`
-
-Hosted Oomi-managed agents also include a `modelRelay` block under the default account. When enabled, `oomi-ai` applies an OpenClaw custom provider named `oomi-managed` that points at Oomi's OpenAI-compatible metered relay:
-
-```json
-{
-  "channels": {
-    "oomi": {
-      "accounts": {
-        "default": {
-          "modelRelay": {
-            "enabled": true,
-            "backendUrl": "https://api.oomi.ai",
-            "openaiBasePath": "/v1/model/relay/openai",
-            "openclawProviderId": "oomi-managed",
-            "openclawModelRef": "oomi-managed/google/gemini-2.5-flash",
-            "provider": "openrouter",
-            "model": "google/gemini-2.5-flash",
-            "userId": "usr_...",
-            "deviceId": "oomi-hosted-...",
-            "internalKeyEnv": "OOMI_HOSTED_BOOTSTRAP_INTERNAL_KEY"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-The config stores only the internal-key environment variable name. The secret value stays in the runtime environment.
-
-## 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
-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 agents:
-
-- 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.
-
-For the Fitness v0 slice:
-
-```bash
-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
-```
-
-## Context Tools
-
-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 context health --json
-```
-
-Clients built from the health-history revision also support stored date ranges:
-
-```bash
-oomi context health --window year --date 2025-06-01 --group-by month --json
-oomi context health --window all --shape summary --json
-```
-
-For these queries, follow `healthHistory.agentGuidance` and use `healthHistory.summary` or `series`. Stored history remains usable while the phone is offline; missing days are unknown. See the [health-history guide](../../docs/2026-09-28-health-history-and-agent-parity.md) for custom ranges and pagination.
-
-Rules for agents:
-
-- Answer from `healthContext.summary` and `healthContext.derived`.
-- Respect `healthContext.agentGuidance.canAnswerFromContext`.
-- If `healthContext.agentGuidance.recommendedCommand` is present, run it before answering current/latest health questions.
-- If context is `stale` or `needs_sync`, run `oomi context health sync --wait --json`; answer only after fresh context is uploaded, or tell the user the phone sync is still pending if it times out.
-- If context is `missing`, `permission_denied`, `disabled_by_user`, or `unavailable`, tell the user what repair action is needed instead of guessing.
-- Never present stale HealthKit values as current values.
-- 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`: subscribed to the Oomi broker; inspect `runtimeReady` and verify a real reply separately
-- `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:
-
-- Action: follow Updating Oomi safely above, then inspect `oomi status --json` for running version and maintenance result.
-- If still stale: run `oomi bridge repair` for default OpenClaw, or add the existing `--name` for a named connection.
-- On macOS service installs: run `oomi openclaw bridge service restart`.
-- Confirm with `oomi openclaw bridge ps`.
-
-## Developer Verification
-
-From `packages/oomi-ai`:
-
-```bash
-npm run check
-npm test
-npm pack --dry-run
-npm publish --dry-run --no-git-checks --access public
-```
-
-Expected package contents are restricted by the `files` allowlist in `package.json`.
-
-## Routines (0.6.0)
-
-Oomi now stores a primary agent and reliable recurring check-ins. Agents can propose, revise, activate, pause, and record responses entirely through chat. Run `oomi routines context`, `oomi routines preferences`, and `oomi routines list` using the same `--connection` as setup. See [the operator guide](agent_instructions.md#primary-agent-routines-and-notifications-oomi-ai-060) for complete request schemas, owner authorization, retries, and events. Restart the bridge after updating to enable event delivery.
-
-## Spaces and quiet updates (0.7.0)
-
-Run `oomi capabilities` for the command map, `oomi instructions` for the installed guide, and `oomi spaces catalog --connection <name>` for supported components and bindings. Agents create and edit persistent Spaces with `spaces create/update --file`, including from other chats, without asking the user to build UI. User edits and agent writes share revisions and idempotency keys. See the packaged Oomi skill for complete examples, source permissions, layout recovery, and routine authority.
-
-When the live catalog advertises `space.v2`, named `sources` and component `sourceRef` fields connect shared readings, recorded workouts, and separate Fitness completions. Include `schemaVersion:"space.v2"` on every write to such a Space (or `--schema-version space.v2` for flag-only commands). These dependencies update data quietly without changing layout revisions, granting provider permissions, or scheduling reminders. Display periods are independent of goal recurrence.
-
-When the catalog advertises `space.v3`, `oomi objectives list/show/history/create/update/respond` manages reusable daily, selected-day, weekly, monthly and one-time goals. Space `objective` components reference those IDs; optional `streak` components reference matching calendars and count full history. Both clients support creation, manual corrections, older progress, and prospective target/pause changes. Use `schemaVersion:"space.v3"` for these Spaces. The [operator guide](agent_instructions.md#recurring-goals-and-optional-streaks-spacev3) describes authority, calendars, source rules, reminders and retries. This source change has not been published to npm.
-
-For short health answers, use `oomi context health --window week --metric steps --json`; use an explicit date range for calendar weeks. `--output <new-file>` saves full private JSON rather than risking terminal truncation.
-
-Ordinary state events sync quietly and are available through `oomi updates`. Phone reminders work without model turns. Explicit routine `agentWakeEnabled:true` enables a bounded wake path (six attempts/hour, no automatic retry after an uncertain model dispatch). Older bridges receive no wake events. Owner identity edits receive one notice per revision; agent-originated edits do not wake the agent again. Initial setup and explicit `oomi verify` send a test message; unchanged reconnects reuse successful verification, including after a failed pairing attempt. Install/update and restart the selected bridge to use the new workers.
-
-`spaces upgrade ID --file upgrade.json` applies explicit checklist-to-goal, streak and named-source mappings in one revision-checked transaction. It preserves unrelated plan data and never turns undated legacy ticks into dated completions. Goal rules may also use an either/or set of presence sources, for example a recorded workout or a Fitness check-in, counting the period once. Read the live catalog before using new capabilities; source code in this branch does not imply an npm release.
-
-### Native desktop runtime selection
-
-A native app can pin its own Hermes fork rather than resolving a different agent from PATH:
-
-```sh
-oomi connect --runtime hermes --name mac-companion --hermes-home /path/to/home --profile default --hermes-command '["/path/to/python","-m","hermes_cli.main"]' --cwd /path/to/oomi-hermes
-```
-
-The structured launcher, home, profile and exact `--resume` session are saved with that named connection. Reconnect reuses them; changing them requires a new connection name. Native callers must use argv without a shell, obtain explicit consent for the initial verification/model call and login service, and show the returned Auth Link for account ownership approval. Do not substitute a different installed agent.
-
-## Agent channels (0.10.0)
-
-An agent channel lets another agent talk with this one directly, and the owner can watch and end it. The other agent can be Claude, Codex, a Grok bot or another Oomi agent.
-
-- **Host:** `oomi channel create --purpose "..." --connection <name>` returns a single-use link (`/channel/<token>`). Each guest message wakes the agent in a separate session, `agent:main:oomi:channel:<id>`. The turn's final reply text is posted back, and an uncertain turn is never rerun.
-- **Guest:** the guest only needs the link. It reads instructions there, joins once to get a private guest token, then sends and long-polls over HTTPS. An Oomi agent can instead run `oomi channel join <link>`, which marks it verified to the owner.
-- **Both sides:** `oomi channel list`, `show`, `send` and `end` work for both roles.
-
-For a person, run `oomi channel create --for person --purpose "..." --owner-name NAME`. This returns a 24-hour web chat link for them and a sign-in-only `watchUrl` for the owner. Each chat has permissions (`privateInfo`, `actions`, `commands`, `payments`), all set to ask first by default. Agents may only restrict them with `--deny`. For an ask-first action, run `oomi channel request-approval`. The owner is notified by push and in their Oomi chat, and their decision returns as an Oomi approval notice.
-
-Guests never gain owner authority or account access. The owner can read the hash-chained transcript and end the channel from Agent settings.
-
-Restart the bridge after updating so it runs the channel worker. Run `oomi instructions` for the full guide.
+# oomi-ai
+
+Connect OpenClaw, Hermes, Grok Bot, and other agents to Oomi through an explicit runtime adapter.
+
+`oomi-ai` connects the selected local agent to Oomi. Persona UI creation and rendering happen inside Oomi-managed systems. The OpenClaw machine uses API actions only.
+
+The current model is:
+
+- The selected agent 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
+
+1. OpenClaw channel extension
+
+- File: `openclaw.extension.js`
+- 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 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.
+
+## Connect Your Local Agent
+
+Connect the agent the user is speaking to. Identify your runtime, bot/profile, and actual host first. Computer access does not mean you run on that computer. Never substitute another installed agent.
+
+## Choose a connection by interface (oomi-ai 0.8.5+)
+
+Run setup on the host where **this agent** runs. A Grok Bot with access to someone's Mac still runs on its Grok Bot host; connecting an OpenClaw agent on that Mac does not connect the Grok Bot. No new model API key or replacement bot is needed.
+
+1. Identify yourself from your current runtime context: bot/profile identity, host, and conversation behavior. Do not guess from installed executables or names.
+2. Run `oomi capabilities`. OpenClaw and Hermes have native adapters. Grok Bot uses its own local gateway through the adapter described below. An unlisted brand is not automatically unsupported: inspect its documented message input **and completed-reply** interfaces (CLI, API, SDK, webhook, or inbound channel).
+3. For another runtime, use `--runtime command` to wrap those interfaces and return `{text, sessionId?}` only when the same agent has finished. A health endpoint or an accepted/queued response is not a final reply. If no supported input or reply interface exists, state that specific missing capability; never invent one or select another agent.
+4. Preserve identity, memories and host approvals. Say whether you resume an exact existing conversation or keep an Oomi conversation with the same agent. Verify a real reply before sharing an Auth Link; verify delivery in Oomi before claiming completion.
+
+### Grok Bot: connect the existing bot
+
+On **this bot's own Linux host**, install/update the package through the normal host approval flow, then run:
+
+```bash
+oomi connect --runtime grokbot --name YOUR_CONNECTION --agent-id YOUR_BOT_UUID --agent-name "Your name" --app-url https://www.oomi.ai
+```
+
+Use your exact bot UUID from your runtime context. Never choose whichever bot happens to be active on a shared computer. Run `oomi grokbot instructions --name YOUR_CONNECTION --agent-id YOUR_BOT_UUID` for the focused setup guide. The package uses the host's existing private local gateway; **do not ask the user to copy a webhook URL/key or create a routine**. Fresh connections require no `grokbot.json`. Existing explicit webhook configurations remain supported. If the local gateway is missing or incompatible, report that specific error and keep the selected identity; do not invent another input interface or substitute an agent.
+
+Setup returns **queued**, then waits in the background. Finish your current bot turn immediately so the verification can execute; waiting for your own verification in that turn deadlocks the host. The package installs its private Oomi delivery skill and waits until this bot has loaded it. Incoming chat shows the original message with a small skill tag; the skill claims the private request and submits its final reply. Missing or locally modified skills fail before sending; do not replace them with instruction walls in chat. Continue only for `status: claimed`. A verification answer must be exactly `OOMI_OK`. The reply command reports one Auth Link only after verification, pairing and bridge subscription succeed. Show the Auth Link to the user. If pending, finish the turn and use `oomi grokbot status --name YOUR_CONNECTION` later. Queued is not connected. Acceptance by the host is not a completed answer.
+
+Use explicit `--connection YOUR_CONNECTION` for Oomi account commands: a shared host does not inherit the bridge's environment. Text and voice transcripts are supported; photos are rejected. Oomi supplies conversation history; exact Grok Bot desktop/DM conversation continuation is not guaranteed. Host approvals remain in Grok Bot. Do not repeat uncertain or already-claimed actions; inspect the original run. Reconnect reuses verification and pairing; `oomi verify --name YOUR_CONNECTION` explicitly queues a new model verification.
+
+Oomi uses systemd user services where available. On Linux hosts without systemd, it automatically supervises bridge worker exits for the current host session. **After the whole cloud computer restarts, rerun the same connect command.** This fallback cannot start itself at boot. Use `oomi status --name YOUR_CONNECTION --json` to inspect recovery. A host-provided external supervisor can instead run `oomi bridge start --name YOUR_CONNECTION --service-managed` with explicit `connect --no-service`. Optional `--skills-dir PATH` installs the guide in a host-supported directory; otherwise use `oomi instructions`.
+
+The direct adapter targets the installed Grok Bot local gateway contract. An incompatible provider update fails closed. Each real host must pass verification, then an authorized Oomi message round trip, before claiming it is connected end to end.
+
+## Updating Oomi safely
+
+When the user asks you to update Oomi, read `oomi instructions` first; it supersedes copied setup/restart recipes. Keep the same connection on the same computer.
+
+1. Run `oomi update --connection NAME` (omit the selector for default OpenClaw). This only checks versions. If already current, report that and stop: do not reinstall or restart "to be sure."
+2. If an update exists, run the returned exact-version npm install command **alone**, through the runtime's normal approval flow. Do not append redirections, status checks or restarts. If installation is denied, fails, or cannot be verified, leave the bridge alone and explain the approval/error. Never disable security checks, retry through another executor, or enable blanket unattended approvals.
+3. After successful installation, check `npm list -g oomi-ai --depth=0` and `oomi update` separately. Only then run `oomi bridge repair --connection NAME`.
+4. A running 0.8.1+ supervised bridge queues its restart until active replies finish and queued phone replies are saved. If the result is `queued`, finish your reply now; do not wait for your own turn to end, poll in a loop, or claim completion. `oomi status --connection NAME --json` subsequently reports maintenance `completed`/`failed` and the running `packageVersion`. Pairing and conversations stay intact.
+
+For packages before 0.8.1 (no `oomi update` command), read the published guide, check `npm list -g oomi-ai --depth=0` and `npm view oomi-ai version` in separate commands. If equal, stop. Otherwise install the exact returned version through normal approvals. The first restart of an older or unsupervised bridge must happen from an independent host terminal/agent session, outside the Oomi conversation it would terminate. New CLI commands refuse to stop their own older host. After that bootstrap, in-chat restarts use the deferred path.
+
+Hermes single-query mode has no interactive approval surface. If its package/security check requires a human, tell the user to approve/run the exact install in an approval-capable host session, then continue there. A blocked install is not a reason to restart. Oomi does not override host permissions. `bridge repair` is also available for an actual connection fault when no package update is needed.
+
+## Standard Connect Flow
+
+For a new installation (for an existing installation, use the safe update flow below):
+
+```bash
+npm install -g oomi-ai@latest
+```
+
+Run ONE command for your runtime:
+
+```bash
+# OpenClaw (reuses existing default OpenClaw pairing)
+oomi connect --runtime openclaw --app-url https://www.oomi.ai
+
+# Hermes (separate connection, no OpenClaw required)
+oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
+
+# Another local agent, through its own adapter
+oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
+```
+
+Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. With oomi-ai 0.8.2+, an already-open Hermes conversation uses its existing local gateway owner and exact profile/session. Oomi attaches as another client; it never closes desktop, clears history, deletes a session lock, or substitutes a new chat. When no live owner exists, an Oomi-owned conversation (no `--resume`) runs on a warm `hermes acp` process with oomi-ai 0.9.0+: replies stream as they are written and stop when the person interrupts. From 0.9.1 the bridge starts Hermes and reopens recent conversations ahead of time (at bridge start and when a call opens), so the first message doesn't wait for Hermes to start. Hermes permission requests are denied, as `chat --quiet` denies dangerous commands; ordinary file edits run as they do in quiet mode. A conversation moving from the CLI starts a new Hermes session that receives the recent Oomi history. `--resume` conversations, Hermes without ACP, and `--hermes-transport cli` use `chat --quiet --query-file -` and resume the exact returned `session_id` on subsequent turns.
+
+Shared desktop conversations require Hermes's loopback WebSocket gateway, active-session discovery, and durable prompt/reply row IDs. Busy conversations ask you to retry after the current task. If a simultaneous desktop send queues your message without a reply receipt, or the connection drops after sending, check the same Hermes chat before resending. Oomi cannot safely repeat an uncertain action. Human approvals stay in the existing Hermes desktop UI. Shared photo submission is not yet supported; use Hermes desktop for that photo. Older or terminal-only owners without a shared gateway receive an actionable error, never a competing process. The shared owner keeps its existing environment, so use the explicit Oomi `--connection NAME` for account commands.
+
+The command verifies a real local reply, reuses saved credentials or pairs once, starts the bridge, waits for Oomi's subscription, then creates a single-use Auth Link. Failed verification means setup is incomplete: repair the selected runtime, never substitute a different one.
+
+The installer is an alternative to npm plus connect, and requires an explicit runtime:
+
+```bash
+curl -fsSL https://www.oomi.ai/install.sh | bash -s -- --runtime hermes --name hermes
+```
+
+## Agent settings and identity backups
+
+If you already have a name, add `--agent-name "Your name"` to `oomi connect`. The separate `--name` / `--connection` flag identifies a saved connection, not your display name. Do not invent a name merely to fill this field. Reconnecting preserves the account's saved name.
+
+You can read and update your own Oomi settings from any chat where you have your local CLI, including channels outside Oomi. Always select the same connection:
+
+```bash
+oomi identity get --connection hermes
+oomi identity set --connection hermes --agent-name "Miso" --bio "A curious everyday companion" --profile-image-url "https://example.com/miso.png"
+```
+
+Omit `--connection` for the default OpenClaw connection. Any of the three setting flags can be supplied alone. Use an empty bio/image value to clear it. Profile images are HTTPS URLs; 3D models are reserved for Oomi and coming soon.
+
+When a user changes settings on the website, the bridge delivers a versioned notice to your actual local runtime, including while no Oomi chat is open. Before applying it, read the current identity again. Persist the current name in your own identity file so your other channels know it: OpenClaw normally uses IDENTITY.md, Hermes uses SOUL.md. Keep the rest of your personality and memories intact. Save the short profile/image as Oomi settings, not replacement personality instructions.
+
+After saving, acknowledge the exact `identityId` and `revision` returned by `identity get`:
+
+```bash
+oomi identity acknowledge --connection hermes --identity-id <identityId> --revision <revision>
+```
+
+Never acknowledge a version you did not save. A 409 means the settings changed; read and apply the newer version. The website distinguishes pending delivery, agent notified, and agent confirmed. A reply alone does not mean your local identity was updated. Existing running conversations may retain older context until they reload identity; tell the user if a runtime requires a new conversation or restart.
+
+Backups are opt-in. Obtain the user's choice of files and inspect those files for secrets before uploading. Do not upload an entire workspace, credentials, user profiles, memories, or chat history. Supported files are SOUL.md, IDENTITY.md, AGENTS.md, and TOOLS.md, at most 64 KiB each. Identity files can themselves contain private information; the filename allowlist is not a secret scanner.
+
+```bash
+oomi identity backup --connection hermes --files '["/absolute/path/SOUL.md"]'
+oomi identity backups --connection hermes
+oomi identity restore --connection hermes --snapshot <id> --output /path/to/new-review-folder
+```
+
+Backups include current Oomi profile settings and deduplicate identical contents. Up to 50 versions are retained; the user can download or delete versions in Agent settings. Restore exports into a new private folder and refuses to overwrite any existing directory. Review the files before applying them manually; restoration does not automatically rename Oomi or modify a running agent. Disconnecting an agent preserves its backups under the original owner.
+
+## Required User-Facing Result
+
+Return the verified runtime/profile and the printed Auth Link. The human opens the link, signs in, and approves ownership. Only after a message receives a reply in Oomi can you claim end-to-end delivery works. Never expose raw tokens, pairing codes, or gateway credentials.
+
+## Repair and Reconnect
+
+Use the SAME connection name from setup. Omit `--name` for default OpenClaw.
+
+```bash
+oomi status --name hermes --json
+oomi verify --name hermes
+oomi bridge repair --name hermes
+oomi invite --name hermes --app-url https://www.oomi.ai
+```
+
+Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses saved pairing and verification; only the first connection or an explicit `oomi verify` sends a model probe. A different command, profile, or working directory requires a new connection name, so one agent cannot silently replace another. Named connections store private state and logs under `~/.oomi/connections/<name>`; default OpenClaw keeps `~/.openclaw`. Since 0.8.0, `connect` installs a separate automatic-start service for each connection: macOS launchd or Linux systemd user. It restarts an exited worker and starts at the next login/user session. Linux servers can start at boot and remain running after logout when the host administrator enables user lingering (`loginctl enable-linger <user>`); `oomi bridge service status --name hermes` reports whether this is enabled. WSL needs systemd and a running WSL instance; native Windows does not yet have an automatic service installer. A sleeping, powered-off, or disconnected computer remains unavailable.
+
+Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To update an existing connection on **each computer**, follow Updating Oomi safely above. Repair preserves pairing and conversations. On a running 0.8.1+ supervised bridge it queues a safe restart and reports pending work; on a stopped bridge it installs/starts supervision and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
+
+Use `oomi bridge service status --name hermes --json` to inspect startup protection. `oomi bridge stop --name hermes` disables automatic startup and stops only that connection; `oomi bridge start --name hermes` enables it again. `oomi bridge service uninstall --name hermes` removes startup management without deleting saved state. The legacy `oomi openclaw bridge service` command remains supported.
+
+For containers or an existing external supervisor, use `connect --no-service` explicitly, then configure that supervisor to run `oomi bridge start --name <name> --service-managed` in the foreground. Detached mode alone does not provide crash/login recovery. Setup fails with an actionable error when the service manager is unavailable; never claim automatic startup in that case. The phone's Reconnect button reconnects the client; it cannot wake a computer or start a missing host process.
+
+`connected` describes the broker transport. Inspect `runtimeReady`, `verifiedAt`, and `lastReplyAt` separately. A process ID, Auth Link, or broker connection alone does not prove the agent is answering.
+
+## Other Runtime Adapter Contract
+
+`--command` is a JSON argv array, not a shell command. Write an adapter against the selected agent's documented API or noninteractive CLI. The executable reads one JSON object from stdin:
+
+```json
+{"sessionKey":"...","message":"...","idempotencyKey":"...","history":[],"runtimeSessionId":"..."}
+```
+
+It writes `{"text":"final reply","sessionId":"optional-runtime-session"}` to stdout and exits zero on success. Errors must exit nonzero; diagnostics go to stderr. Resume `runtimeSessionId`, or use `history` for stateless runtimes. Never bypass the agent's existing approval rules. The adapter supports text (including voice transcripts); attachments are rejected explicitly. A failed or interrupted action is not silently repeated. Check the agent before sending a new message after a failure.
+
+## OpenClaw Channel Extension
+
+Managed web text and voice connect through the local gateway. The optional OpenClaw `oomi-ai` channel plugin handles agent-initiated channel output. If you need that path, install the plugin, enable its entry in OpenClaw, apply `oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai` locally, and restart OpenClaw. Never share that secret config with the user. Disabling the plugin does not explain a gateway protocol rejection.
+
+OpenClaw gateway protocols 3 and 4 are negotiated independently of the broker. For an existing install affected by a protocol mismatch, update `oomi-ai`, then run `oomi connect --runtime openclaw --app-url https://www.oomi.ai`.
+
+
+## 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`
+
+Hosted Oomi-managed agents also include a `modelRelay` block under the default account. When enabled, `oomi-ai` applies an OpenClaw custom provider named `oomi-managed` that points at Oomi's OpenAI-compatible metered relay:
+
+```json
+{
+  "channels": {
+    "oomi": {
+      "accounts": {
+        "default": {
+          "modelRelay": {
+            "enabled": true,
+            "backendUrl": "https://api.oomi.ai",
+            "openaiBasePath": "/v1/model/relay/openai",
+            "openclawProviderId": "oomi-managed",
+            "openclawModelRef": "oomi-managed/google/gemini-2.5-flash",
+            "provider": "openrouter",
+            "model": "google/gemini-2.5-flash",
+            "userId": "usr_...",
+            "deviceId": "oomi-hosted-...",
+            "internalKeyEnv": "OOMI_HOSTED_BOOTSTRAP_INTERNAL_KEY"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The config stores only the internal-key environment variable name. The secret value stays in the runtime environment.
+
+## 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
+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 agents:
+
+- 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.
+
+For the Fitness v0 slice:
+
+```bash
+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
+```
+
+## Context Tools
+
+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 context health --json
+```
+
+Clients built from the health-history revision also support stored date ranges:
+
+```bash
+oomi context health --window year --date 2025-06-01 --group-by month --json
+oomi context health --window all --shape summary --json
+```
+
+For these queries, follow `healthHistory.agentGuidance` and use `healthHistory.summary` or `series`. Stored history remains usable while the phone is offline; missing days are unknown. See the [health-history guide](../../docs/2026-09-28-health-history-and-agent-parity.md) for custom ranges and pagination.
+
+Rules for agents:
+
+- Answer from `healthContext.summary` and `healthContext.derived`.
+- Respect `healthContext.agentGuidance.canAnswerFromContext`.
+- If `healthContext.agentGuidance.recommendedCommand` is present, run it before answering current/latest health questions.
+- If context is `stale` or `needs_sync`, run `oomi context health sync --wait --json`; answer only after fresh context is uploaded, or tell the user the phone sync is still pending if it times out.
+- If context is `missing`, `permission_denied`, `disabled_by_user`, or `unavailable`, tell the user what repair action is needed instead of guessing.
+- Never present stale HealthKit values as current values.
+- 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`: subscribed to the Oomi broker; inspect `runtimeReady` and verify a real reply separately
+- `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:
+
+- Action: follow Updating Oomi safely above, then inspect `oomi status --json` for running version and maintenance result.
+- If still stale: run `oomi bridge repair` for default OpenClaw, or add the existing `--name` for a named connection.
+- On macOS service installs: run `oomi openclaw bridge service restart`.
+- Confirm with `oomi openclaw bridge ps`.
+
+## Developer Verification
+
+From `packages/oomi-ai`:
+
+```bash
+npm run check
+npm test
+npm pack --dry-run
+npm publish --dry-run --no-git-checks --access public
+```
+
+Expected package contents are restricted by the `files` allowlist in `package.json`.
+
+## Routines (0.6.0)
+
+Oomi now stores a primary agent and reliable recurring check-ins. Agents can propose, revise, activate, pause, and record responses entirely through chat. Run `oomi routines context`, `oomi routines preferences`, and `oomi routines list` using the same `--connection` as setup. See [the operator guide](agent_instructions.md#primary-agent-routines-and-notifications-oomi-ai-060) for complete request schemas, owner authorization, retries, and events. Restart the bridge after updating to enable event delivery.
+
+## Spaces and quiet updates (0.7.0)
+
+Run `oomi capabilities` for the command map, `oomi instructions` for the installed guide, and `oomi spaces catalog --connection <name>` for supported components and bindings. Agents create and edit persistent Spaces with `spaces create/update --file`, including from other chats, without asking the user to build UI. User edits and agent writes share revisions and idempotency keys. See the packaged Oomi skill for complete examples, source permissions, layout recovery, and routine authority.
+
+When the live catalog advertises `space.v2`, named `sources` and component `sourceRef` fields connect shared readings, recorded workouts, and separate Fitness completions. Include `schemaVersion:"space.v2"` on every write to such a Space (or `--schema-version space.v2` for flag-only commands). These dependencies update data quietly without changing layout revisions, granting provider permissions, or scheduling reminders. Display periods are independent of goal recurrence.
+
+When the catalog advertises `space.v3`, `oomi objectives list/show/history/create/update/respond` manages reusable daily, selected-day, weekly, monthly and one-time goals. Space `objective` components reference those IDs; optional `streak` components reference matching calendars and count full history. Both clients support creation, manual corrections, older progress, and prospective target/pause changes. Use `schemaVersion:"space.v3"` for these Spaces. The [operator guide](agent_instructions.md#recurring-goals-and-optional-streaks-spacev3) describes authority, calendars, source rules, reminders and retries. This source change has not been published to npm.
+
+For short health answers, use `oomi context health --window week --metric steps --json`; use an explicit date range for calendar weeks. `--output <new-file>` saves full private JSON rather than risking terminal truncation.
+
+Ordinary state events sync quietly and are available through `oomi updates`. Phone reminders work without model turns. Explicit routine `agentWakeEnabled:true` enables a bounded wake path (six attempts/hour, no automatic retry after an uncertain model dispatch). Older bridges receive no wake events. Owner identity edits receive one notice per revision; agent-originated edits do not wake the agent again. Initial setup and explicit `oomi verify` send a test message; unchanged reconnects reuse successful verification, including after a failed pairing attempt. Install/update and restart the selected bridge to use the new workers.
+
+`spaces upgrade ID --file upgrade.json` applies explicit checklist-to-goal, streak and named-source mappings in one revision-checked transaction. It preserves unrelated plan data and never turns undated legacy ticks into dated completions. Goal rules may also use an either/or set of presence sources, for example a recorded workout or a Fitness check-in, counting the period once. Read the live catalog before using new capabilities; source code in this branch does not imply an npm release.
+
+### Native desktop runtime selection
+
+A native app can pin its own Hermes fork rather than resolving a different agent from PATH:
+
+```sh
+oomi connect --runtime hermes --name mac-companion --hermes-home /path/to/home --profile default --hermes-command '["/path/to/python","-m","hermes_cli.main"]' --cwd /path/to/oomi-hermes
+```
+
+The structured launcher, home, profile and exact `--resume` session are saved with that named connection. Reconnect reuses them; changing them requires a new connection name. Native callers must use argv without a shell, obtain explicit consent for the initial verification/model call and login service, and show the returned Auth Link for account ownership approval. Do not substitute a different installed agent.
+
+## Agent channels (0.10.0)
+
+An agent channel lets another agent talk with this one directly, and the owner can watch and end it. The other agent can be Claude, Codex, a Grok bot or another Oomi agent.
+
+- **Host:** `oomi channel create --purpose "..." --connection <name>` returns a single-use link (`/channel/<token>`). Each guest message wakes the agent in a separate session, `agent:main:oomi:channel:<id>`. The turn's final reply text is posted back, and an uncertain turn is never rerun.
+- **Guest:** the guest only needs the link. It reads instructions there, joins once to get a private guest token, then sends and long-polls over HTTPS. An Oomi agent can instead run `oomi channel join <link>`, which marks it verified to the owner.
+- **Both sides:** `oomi channel list`, `show`, `send` and `end` work for both roles.
+
+For a person, run `oomi channel create --for person --purpose "..." --owner-name NAME`. This returns a 24-hour web chat link for them and a sign-in-only `watchUrl` for the owner. Each chat has permissions (`privateInfo`, `actions`, `commands`, `payments`), all set to ask first by default. Agents may only restrict them with `--deny`. For an ask-first action, run `oomi channel request-approval`. The owner is notified by push and in their Oomi chat, and their decision returns as an Oomi approval notice.
+
+Guests never gain owner authority or account access. The owner can read the hash-chained transcript and end the channel from Agent settings.
+
+Restart the bridge after updating so it runs the channel worker. Run `oomi instructions` for the full guide.