omnius 1.0.608 → 1.0.610

package/README.md

@@ -37,8 +37,10 @@ omnius tray install
 omnius tray status
 ```
 
-The per-login indicator observes the daemon over loopback and provides health,
-dashboard, logs, and explicit daemon controls. See the
+The per-login indicator observes the daemon over loopback, checks health and npm
+updates every 10 seconds, and provides dashboard, logs, and explicit daemon
+controls. Its version row is passive when current and becomes a verified global
+update action only when a newer exact semver is available. See the
 [system tray guide](docs/guides/system-tray.md), including Ubuntu/GNOME setup.
 
 ## Agent Discovery
@@ -49,6 +51,9 @@ which endpoint owns a capability:
 
 ```bash
 omnius discover "bring your own inference"
+omnius show workflow.choose-entrypoint
+omnius show layer.orchestration
+omnius show store.project
 omnius show provider.anthropic
 omnius show provider.gemini
 omnius show tool.web-search
@@ -57,14 +62,15 @@ omnius show capability.osint-research
 omnius capabilities --json
 ```
 
-With the daemon running, the same discovery cascade is available at
-`GET /v1/discovery`, with exact entry expansion at
+With the daemon running, begin at `GET /v1/discovery/bootstrap`. The same
+discovery cascade is available at `GET /v1/discovery`, with exact entry expansion at
 `GET /v1/discovery/{id}`. The live API contract remains available at
 `/openapi.json`, direct tool metadata at `/v1/tools`, and skills at
 `/v1/skills`.
 
 Start with [the discovery guide](docs/DISCOVERY.md) when integrating another
-agent or service. Use [bring-your-own inference](docs/guides/bring-your-own-inference.md)
+agent or service, and use the [agent system map](docs/architecture/agent-system-map.md)
+to trace layers, modules, runtimes, and state ownership. Use [bring-your-own inference](docs/guides/bring-your-own-inference.md)
 for provider protocols and keys, and [tools and web search](docs/guides/tools-and-web-search.md)
 for the distinction between direct tools and agent-bound tools. The
 [categorized OSINT research guide](docs/guides/osint-research.md) documents
@@ -91,7 +97,14 @@ omnius serve
 /help                 command help
 /model                select or inspect the active model
 /endpoint             select or configure local, cloud, sponsor, or peer endpoints
+/title                name the current session
 /realtime             toggle short ASR/TTS-oriented conversation mode
+/voice                choose TTS, voice-clone, voicechat, and ASR controls
+/voice asr            select, set up, activate, or test an exact ASR engine/model
+/indicator            reconcile the daemon, then start the native tray indicator
+/update check         force an update availability check
+/update quick         run the verified global update with live TUI progress
+/update full          run the full clean/build/install/restart verification flow
 /broker               inspect model broker, RAM/VRAM thresholds, and loaded models
 /sponsor              expose local or upstream capacity to peers
 /cohere               participate in distributed COHERE inference
@@ -111,9 +124,11 @@ omnius serve
 | Bring your own inference | [Provider protocols and keys](docs/guides/bring-your-own-inference.md) |
 | Tools and web search | [Tool discovery and invocation](docs/guides/tools-and-web-search.md) |
 | Terminal workflows | [TUI workflows](docs/guides/tui-workflows.md), [Slash commands](docs/reference/slash-commands.md) |
+| Web dashboard | [All dashboard routes, workspaces, sessions, Voice, Generate, updates, and observability](docs/guides/dashboard.md) |
 | REST daemon | [REST reference](docs/reference/rest-api.md), [REST quickref](docs/rest/QUICKREF.md), [OpenAPI source](docs/rest/openapi-source.md) |
 | System tray | [Cross-platform tray and Ubuntu setup](docs/guides/system-tray.md) |
 | Realtime voice chat | [Realtime guide](docs/guides/realtime.md) |
+| TTS and selectable ASR | [Voice/vision REST guide](docs/rest/endpoints/voice-vision.md), [Dashboard Voice page](docs/guides/dashboard.md#voice-and-asr) |
 | Sponsor and COHERE mesh | [Sponsor and COHERE guide](docs/guides/sponsor-and-cohere.md) |
 | Telegram bridge | [Telegram guide](docs/guides/telegram.md) |
 | Media generation | [Media guide](docs/guides/media-generation.md) |
@@ -122,6 +137,40 @@ omnius serve
 | Architecture | [Architecture overview](docs/architecture/overview.md) |
 | Agent-explorable docs | [Agent memory docs index](docs/agent-memory/INDEX.md) |
 
+## Web Dashboard
+
+`omnius serve` exposes a self-contained operational dashboard at
+`http://127.0.0.1:11435/`. All pages use the same compact NOCLIP-derived style
+tokens and responsive observability-card grid, while keeping workspace, model,
+session, run, service, and update state visible instead of hiding it behind
+decorative pages.
+
+| Route | Purpose |
+| --- | --- |
+| `/chat` (`/`) | Stateful browser and imported TUI chats, full-history hydration, live run recovery, attachments, files, plan/context, and steering check-ins |
+| `/agent` | One-shot task contracts, personas/profiles, tool/isolation controls, run records, output, and events |
+| `/voice` | Voicechat, exact TTS model/options, clone references, ASR engine/model setup and activation, real-file ASR testing, transcript, and TTS testing |
+| `/generate` | Image/video/audio/music jobs, AV analysis, model/store controls, relocation progress, and global gallery |
+| `/projects` | Scan, register, rename, activate, and remove workspaces |
+| `/dashboard` (`/jobs`) | CPU/RAM/GPU/VRAM, processes, scheduler, services, usage, and verified updates |
+| `/activity` | Live run/tool/memory/engine event observability |
+| `/discover` | Agent bootstrap, capability intent search, and exact entry expansion |
+| `/settings` (`/config`) | Models, endpoints, voice, runtime, access, keys, appearance, and services |
+
+The clickable sidebar brand opens the registered-workspace picker. Workspace
+selection scopes preferences, files, session history, chat pins/folders/search,
+and agent defaults. Chats, TUI visual history, and one-shot agent runs are
+distinct records: `/quit`, `/exit`, manual-save noise, empty histories, and
+duplicate TUI transcripts are rejected from the chat projection; selecting a
+valid session loads its full history and in-flight status from the daemon.
+
+The dashboard checks for updates every 10 seconds. An update button appears only
+for a newer exact semver and drives `POST /v1/update`, then polls the durable
+transaction until the global npm package, resolved executable, restarted daemon,
+package/boot hashes, and tray runtime are reconciled. See the
+[complete dashboard guide](docs/guides/dashboard.md) for state ownership,
+security, page-by-page behavior, and exact REST flows.
+
 ## Shared Media Dependencies
 
 Image, video, audio, and music generation share a **single, system-wide dependency store** instead of duplicating heavy runtimes per project or per Telegram group.
@@ -171,6 +220,11 @@ The same surface drives the **Generate** tab in the web UI (`http://127.0.0.1:11
 
 ## Recent Highlights
 
+- The dashboard now has nine route-level operational surfaces with shared modular observability grids, a searchable workspace picker, and project-scoped navigation state.
+- Chat history unifies persisted browser sessions with quality-filtered TUI transcripts, rejects command/noise sessions such as `/quit`, hydrates full history on selection, and exposes summaries, follow-up suggestions, reactive live deltas, and canonical deletion.
+- `/indicator` reconciles daemon ownership and health before launching the tray; the tray polls every 10 seconds and turns its version row into a retryable verified-update action only when an update exists.
+- Dashboard, tray, and TUI update actions now share an exact-version global transaction with live phase/output and package, executable, daemon, hash, restart, and tray verification.
+- TTS exposes GLaDOS, Overwatch, `luxtts:announcer-testchamber03`, and configurable Voicebox models; ASR independently exposes Whisper, managed `transcribe-cli`, Nemotron readiness, and pinned Microsoft VibeVoice ASR with Jetson/ARM64 CUDA-aware setup.
 - `/realtime` and REST `realtime: true` provide short, natural, SOUL.md-aware conversation for ASR/TTS clients.
 - Endpoint setup and sponsor setup aggregate models from all enabled endpoints, including external OpenAI-compatible routers.
 - `/sponsor` can expose text inference and media generation for image, video, sound, and music with per-modality limits.
@@ -195,21 +249,42 @@ OMNIUS_REST_API_KEYS="read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key
 # then: Authorization: Bearer <key>
 ```
 
-The complete endpoint inventory follows. It is kept in lockstep with the served OpenAPI spec by `pnpm docs:check`; the canonical machine contract is generated from [`packages/cli/src/api/openapi.ts`](packages/cli/src/api/openapi.ts) and mirrored in [`docs/reference/rest-api.md`](docs/reference/rest-api.md).
+The complete supported endpoint inventory follows. The canonical machine
+contract is generated from [`packages/cli/src/api/openapi.ts`](packages/cli/src/api/openapi.ts),
+validated against [`docs/reference/rest-api.md`](docs/reference/rest-api.md),
+and projected into the generated block below. `pnpm docs:check` now fails when
+any of those three surfaces drift. Browser HTML pages, Swagger static assets,
+and implementation-only compatibility bridges are intentionally outside this
+stable REST contract.
 
-### Docs and compatibility aliases
+<!-- BEGIN GENERATED REST INVENTORY -->
+### Docs And Compatibility Aliases
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `/docs` · `/api/docs` · `/swagger-ui` | Swagger UI |
-| `GET` | `/openapi.json` · `/openapi.yaml` · `/v3/api-docs` · `/swagger.json` · `/api-docs` | OpenAPI spec (JSON/YAML + aliases) |
+| `GET` | `/docs` | Swagger UI |
+| `GET` | `/api/docs` | Swagger UI alias |
+| `GET` | `/openapi.json` | OpenAPI JSON |
+| `GET` | `/openapi.yaml` | OpenAPI YAML |
+| `GET` | `/v3/api-docs` | OpenAPI alias |
+| `GET` | `/swagger.json` | Swagger-era alias |
+| `GET` | `/api-docs` | OpenAPI alias |
+| `GET` | `/swagger-ui` | Swagger UI alias |
 | `GET` | `/redoc` | ReDoc renderer |
+| `GET` | `/` | HATEOAS API root when the client does not request HTML |
+| `GET` | `/help` | Compact daemon integration help |
+| `GET` | `/v1/routes` | Flat grep-friendly daemon route summary |
+| `GET` | `/routes` | Route-summary compatibility alias |
+| `GET` | `/asyncapi.json` | AsyncAPI 2.6 voicechat WebSocket contract |
+| `GET` | `/asyncapi` | AsyncAPI compatibility alias |
 
-### Health and observability
+### Health And Observability
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `/health` · `/health/ready` · `/health/startup` | Liveness, backend readiness, startup probes |
+| `GET` | `/health` | Liveness probe |
+| `GET` | `/health/ready` | Backend readiness |
+| `GET` | `/health/startup` | Startup probe |
 | `GET` | `/version` | Package version and platform |
 | `GET` | `/metrics` | Prometheus metrics |
 | `GET` | `/v1/events` | Server-sent event stream |
@@ -222,207 +297,376 @@ The complete endpoint inventory follows. It is kept in lockstep with the served
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `/v1/discovery` | Search or list the bundled capability catalog |
+| `GET` | `/v1/discovery/bootstrap` | Compact agent bootstrap and start-here map |
+| `GET` | `/v1/discovery` | Search layers, workflows, runtimes, modules, stores, and capabilities |
 | `GET` | `/v1/discovery/{id}` | Expand one stable capability entry |
 
-### Inference and chat
+### Inference And Chat
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `/v1/models` · `/api/tags` | Aggregated model list (OpenAI + Ollama tags) |
+| `GET` | `/v1/models` | Aggregated model list |
 | `POST` | `/v1/chat/completions` | OpenAI-compatible chat completion |
 | `POST` | `/v1/chat` | Stateful Omnius chat |
 | `POST` | `/api/chat` | Ollama-compatible chat alias |
-| `POST` | `/v1/generate` · `/api/generate` | One-shot generation (Ollama-compatible) |
-| `POST` | `/v1/embeddings` · `/api/embed` | Embeddings (OpenAI + Ollama aliases) |
-| `GET` | `/v1/chat/sessions` | Active chat sessions |
+| `POST` | `/v1/generate` | Ollama-compatible one-shot generation |
+| `POST` | `/api/generate` | Ollama-compatible generate alias |
+| `POST` | `/v1/embeddings` | OpenAI-compatible embeddings |
+| `POST` | `/api/embed` | Ollama-compatible embeddings alias |
+| `GET` | `/api/tags` | Ollama-compatible model tags |
+| `POST` | `/realtime` | Text-only voice-adapter reply from a transcript |
+| `POST` | `/v1/realtime` | Auth-scoped realtime adapter alias |
+| `GET` | `/v1/chat/sessions` | Workspace-scoped persisted browser chats and importable TUI sessions |
+| `GET` | `/v1/chat/sessions/{id}` | Hydrate full session history, transcript, and in-flight state |
+| `DELETE` | `/v1/chat/sessions/{id}` | Permanently delete a canonical chat or TUI history session |
+| `POST` | `/v1/chat/sessions/{id}/summarize` | Generate + cache an inference-based session title/summary |
+| `POST` | `/v1/chat/suggest-followup` | Suggest one short next-message follow-up (ghost-text input) |
+| `GET` | `/v1/chat/sessions/{id}/status` | Reactive recall: live run status + unseen deltas (`?since=<seq>`) |
 | `POST` | `/v1/chat/check-in` | Steering check-in for active chat |
-
-### Agentic runs
+| `POST` | `/v1/chat/attachments` | Upload an attachment for a stateful chat |
+
+#### Session History Contract
+
+`GET /v1/chat/sessions` is a history index, not merely a list of processes that
+are currently active. It returns canonical persisted browser chats for the
+selected workspace and, by default, quality-filtered TUI visual sessions that
+can be imported on demand. Pass `?root=/absolute/workspace` to scope the list and
+`?include_tui=0` to omit TUI history. Exit-only inputs such as `/quit` and
+`/exit`, manual-save noise, empty transcripts, and duplicate normalized TUI
+sessions are rejected by the session-quality projection rather than presented as
+chats.
+
+Selecting a row should call `GET /v1/chat/sessions/{id}`. That response hydrates
+the complete public message history (system prompts are intentionally omitted),
+the original TUI transcript when applicable, token counts, timestamps, source
+and project identity, and any in-flight run with a bounded partial-output tail.
+Use the `status` endpoint with `?since=<seq>` for cheap reactive polling while a
+run is active. `DELETE /v1/chat/sessions/{id}` is an admin operation and removes
+the canonical record; deleting only a browser-side row does not remove daemon
+history.
+
+`POST /realtime` and `/v1/realtime` are text-only conversation adapters. They
+accept transcript text through `message`, `text`, `recent_turn`, `asr_text`, or
+`callerText`, optionally accept adapter-local `soul_md`, and can return plain
+text with `Accept: text/plain` or `format: "text"`. ASR and TTS remain separate
+operations.
+
+### Agentic Runs
 
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `POST` | `/v1/run` | Submit agentic task |
-| `GET` | `/v1/runs` · `/v1/runs/{id}` | List runs · get run details |
+| `GET` | `/v1/runs` | List runs |
+| `GET` | `/v1/runs/{id}` | Get run details |
+| `GET` | `/v1/runs/{id}/output` | Read captured run output and status |
 | `DELETE` | `/v1/runs/{id}` | Abort run |
-| `POST`/`GET` | `/v1/todos` | Create/update · list sessions with todos |
-| `GET`/`DELETE` | `/v1/todos/{session_id}` | Get · delete session todos |
+| `POST` | `/v1/todos` | Create or update todos for current session |
+| `GET` | `/v1/todos` | List sessions with todos |
+| `GET` | `/v1/todos/{session_id}` | Get session todos |
+| `DELETE` | `/v1/todos/{session_id}` | Delete session todos |
 | `POST` | `/v1/evaluate` | Evaluate a run |
 | `POST` | `/v1/index` | Trigger repository indexing |
 
-### Configuration, keys, profiles, projects
+### Configuration, Keys, Profiles, Projects
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET`/`PATCH` | `/v1/config` | Read · update daemon config |
-| `GET`/`PUT` | `/v1/config/model` | Current model · switch model |
-| `POST` | `/v1/config/model/check` | Probe model readiness |
-| `GET`/`PUT` | `/v1/config/endpoint` | Current endpoint · switch endpoint |
+| `GET` | `/v1/config` | Read daemon config |
+| `PATCH` | `/v1/config` | Update daemon config |
+| `GET` | `/v1/config/model` | Current model |
+| `PUT` | `/v1/config/model` | Switch model |
+| `POST` | `/v1/config/model/check` | Probe model readiness with non-empty text |
+| `GET` | `/v1/config/endpoint` | Current endpoint |
+| `PUT` | `/v1/config/endpoint` | Switch endpoint |
 | `POST` | `/v1/config/endpoint/test` | Probe endpoint |
-| `GET`/`DELETE` | `/v1/config/endpoint/history` | Endpoint history · remove item |
+| `GET` | `/v1/config/endpoint/history` | Endpoint history |
+| `DELETE` | `/v1/config/endpoint/history` | Remove endpoint history item |
 | `POST` | `/v1/share/generate` | Generate remote-access share URL |
-| `GET`/`POST` | `/v1/keys` | List · mint runtime API keys |
-| `DELETE` | `/v1/keys/{prefix}` | Revoke runtime keys by prefix |
-| `GET`/`POST` | `/v1/profiles` | List · create tool profiles |
-| `GET`/`DELETE` | `/v1/profiles/{name}` | Get · delete profile |
-| `GET`/`DELETE` | `/v1/projects` | List · unregister projects |
+| `GET` | `/v1/keys` | List runtime API keys |
+| `POST` | `/v1/keys` | Mint runtime API key |
+| `DELETE` | `/v1/keys/{prefix}` | Revoke runtime API keys by prefix |
+| `GET` | `/v1/profiles` | List tool profiles |
+| `POST` | `/v1/profiles` | Create tool profile |
+| `GET` | `/v1/profiles/{name}` | Get profile |
+| `DELETE` | `/v1/profiles/{name}` | Delete profile |
+| `GET` | `/v1/projects` | List known projects |
+| `DELETE` | `/v1/projects` | Unregister a project |
 | `GET` | `/v1/projects/current` | Current project |
-| `POST` | `/v1/projects/switch` · `/v1/projects/register` · `/v1/projects/rename` | Switch · register · rename project |
-| `GET`/`PUT`/`DELETE` | `/v1/projects/preferences` | Read · patch · reset project preferences |
-
-### Skills, commands, tools, MCP
+| `POST` | `/v1/projects/switch` | Switch project |
+| `POST` | `/v1/projects/register` | Register project |
+| `POST` | `/v1/projects/rename` | Rename project |
+| `GET` | `/v1/projects/preferences` | Read project preferences |
+| `PUT` | `/v1/projects/preferences` | Patch project preferences |
+| `DELETE` | `/v1/projects/preferences` | Reset project preferences |
+| `GET` | `/v1/projects/scan` | Scan configured roots for discoverable workspaces |
+| `GET` | `/v1/admin/access` | Read the daemon network access mode |
+| `POST` | `/v1/admin/access` | Change and persist access mode from loopback only |
+
+### Skills, Commands, Tools, MCP
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `/v1/skills` · `/v1/skills/{name}` | List · load skill content |
+| `GET` | `/v1/skills` | List skills |
+| `GET` | `/v1/skills/{name}` | Load skill content |
 | `GET` | `/v1/commands` | List slash commands |
 | `POST` | `/v1/commands/{cmd}` | Execute slash command |
-| `GET` | `/v1/tools` · `/v1/tools/{name}` | List (built-in + external) · tool metadata |
+| `GET` | `/v1/tools` | List tools (built-in + external) |
 | `POST` | `/v1/tools/register` | Register an application-specific external tool |
+| `GET` | `/v1/tools/{name}` | Tool metadata |
 | `DELETE` | `/v1/tools/{name}` | Unregister an external tool |
 | `POST` | `/v1/tools/{name}/call` | Call tool |
 | `POST` | `/v1/tools/{name}/eval` | Evaluate an external tool against test cases |
-| `GET` | `/v1/mcps` · `/v1/mcps/{name}` | List · MCP server details |
+| `GET` | `/v1/mcps` | List MCP servers |
+| `GET` | `/v1/mcps/{name}` | MCP server details |
 | `POST` | `/v1/mcps/{name}/call` | Call MCP tool |
-| `GET` | `/v1/hooks` · `/v1/agents` | Hook registry · agent type registry |
-| `GET` | `/v1/codegraph/snapshot` · `/v1/codegraph/events` | Code graph snapshot · SSE |
+| `GET` | `/v1/hooks` | Hook registry |
+| `GET` | `/v1/agents` | Agent type registry |
+| `GET` | `/v1/codegraph/snapshot` | Code graph snapshot |
+| `GET` | `/v1/codegraph/events` | Code graph SSE |
 
-### Registering application-specific tools
+#### Registering Application-Specific Tools
 
-Agents integrating Omnius into their own stack can register tools at runtime so the Omnius agent loop can call them alongside built-ins. Registration is a single unified contract — `transport.type` selects how Omnius reaches the implementation:
+Applications can register their own tools so Omnius agents can discover and
+invoke them alongside built-ins. `transport.type` selects the bridge:
 
-- **`http`** — Omnius POSTs `{name, args, session_id}` to a `callback_url` your app hosts and relays the response.
-- **`mcp`** — the tool proxies to a named tool on an MCP server (auto-connected when you pass `connect`).
+- `http` makes Omnius POST `{name, args, session_id}` to the application's
+  `callback_url` and relay the result.
+- `mcp` proxies to a named tool on an MCP server and can auto-connect from the
+  supplied connection descriptor.
 
-Registered tools are persisted per working directory (`.omnius/external-tools.json`), surface in `GET /v1/tools`, and respect the same scope/off-device security gate as built-ins. Registration needs `run` scope (remote callers need `admin`).
+Registrations persist per workspace at `.omnius/external-tools.json`, appear in
+`GET /v1/tools`, and use the same scope and off-device security gates as built-in
+tools. Registration needs `run` scope; a non-loopback caller needs `admin`.
 
 ```bash
-# Register an HTTP-backed tool
 curl -s -X POST localhost:11435/v1/tools/register -H 'content-type: application/json' -d '{
   "name": "lookup_order",
-  "description": "Look up an order by id in the billing system",
+  "description": "Look up an order by id",
   "parameters": {"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},
   "security": {"requires_scope":"run","risk":"low"},
   "transport": {"type":"http","callback_url":"https://app.internal/tools/lookup_order","auth_header":"Bearer …"}
 }'
-
-# It now appears in the registry and is directly callable
 curl -s localhost:11435/v1/tools/lookup_order
 curl -s -X POST localhost:11435/v1/tools/lookup_order/call -H 'content-type: application/json' -d '{"args":{"id":"A-1001"}}'
-
-# Evaluate it against cases during development (pass/fail + metrics)
-curl -s -X POST localhost:11435/v1/tools/lookup_order/eval -H 'content-type: application/json' -d '{
-  "cases": [
-    {"name":"known order","args":{"id":"A-1001"},"expect":{"success":true,"output_contains":"A-1001"}},
-    {"name":"missing order","args":{"id":"nope"},"expect":{"success":false}}
-  ]
-}'
-
-# Unregister when done
+curl -s -X POST localhost:11435/v1/tools/lookup_order/eval -H 'content-type: application/json' -d '{"cases":[{"name":"known","args":{"id":"A-1001"},"expect":{"success":true}}]}'
 curl -s -X DELETE localhost:11435/v1/tools/lookup_order
 ```
 
-The same registration accepts an MCP transport, e.g. `"transport":{"type":"mcp","server":"acme","tool":"search","connect":{"url":"https://app.internal/mcp","transport":"streamable-http"}}`.
+The MCP equivalent uses a transport such as
+`{"type":"mcp","server":"acme","tool":"search","connect":{"url":"https://app.internal/mcp","transport":"streamable-http"}}`.
 
 ### AIWG
 
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `GET` | `/v1/aiwg` | AIWG root and control map |
-| `GET` | `/v1/aiwg/frameworks` · `/v1/aiwg/frameworks/{name}` · `/v1/aiwg/frameworks/{name}/content` | List · details · tier-aware content |
-| `GET` | `/v1/aiwg/skills` · `/v1/aiwg/skills/{name}` | List · load AIWG skill |
-| `GET` | `/v1/aiwg/agents` · `/v1/aiwg/agents/{name}` | List · load AIWG agent |
+| `GET` | `/v1/aiwg/frameworks` | List frameworks |
+| `GET` | `/v1/aiwg/frameworks/{name}` | Framework details |
+| `GET` | `/v1/aiwg/frameworks/{name}/content` | Tier-aware content |
+| `GET` | `/v1/aiwg/skills` | List AIWG skills |
+| `GET` | `/v1/aiwg/skills/{name}` | Load AIWG skill |
+| `GET` | `/v1/aiwg/agents` | List AIWG agents |
+| `GET` | `/v1/aiwg/agents/{name}` | Load AIWG agent |
 | `GET` | `/v1/aiwg/addons` | List AIWG addons |
-| `POST` | `/v1/aiwg/use` · `/v1/aiwg/expand` | Activation bundle · expand item |
+| `POST` | `/v1/aiwg/use` | Tier-sized activation bundle |
+| `POST` | `/v1/aiwg/expand` | Expand matching AIWG item |
 
-### Memory, sessions, context
+### Memory, Sessions, Context
 
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `GET` | `/v1/memory` | Memory backend summary |
-| `POST` | `/v1/memory/search` · `/v1/memory/write` | Search · write memory |
-| `GET` | `/v1/memory/episodes` · `/v1/memory/failures` | List episodes · failures |
-| `GET` | `/v1/sessions` · `/v1/sessions/{id}` | List task sessions · get history |
+| `POST` | `/v1/memory/search` | Search memory |
+| `POST` | `/v1/memory/write` | Write memory |
+| `GET` | `/v1/memory/episodes` | List episodes |
+| `GET` | `/v1/memory/failures` | List failure records |
+| `POST` | `/v1/memory/ingest` | Ingest content or files into memory |
+| `GET` | `/v1/memory/entities` | List extracted memory entities |
+| `POST` | `/v1/memory/jobs/run` | Run a named memory-maintenance job |
+| `POST` | `/v1/memory/feedback` | Record relevance or quality feedback for a memory item |
+| `GET` | `/v1/sessions` | List task sessions |
+| `GET` | `/v1/sessions/{id}` | Get session history |
 | `GET` | `/v1/context` | Current context snapshot |
-| `GET` | `/v1/context/window-dumps` · `/v1/context/window-dumps/{id}` | List/fetch full outbound model context-window dumps |
-| `POST` | `/v1/context/save` · `/v1/context/compact` | Save entry · request compaction |
+| `GET` | `/v1/context/window-dumps` | List persisted outbound model context-window dumps |
+| `GET` | `/v1/context/window-dumps/{id}` | Fetch a full outbound model context-window dump |
+| `POST` | `/v1/context/save` | Save context entry |
 | `GET` | `/v1/context/restore` | Build restore prompt |
+| `POST` | `/v1/context/compact` | Request compaction |
 
-Context-window dumps are written for main agents, sub-agents, internal runners, and adversary audits before backend inference. Use `GET /v1/context/window-dumps?agent_type=main` for summaries with signal/noise metrics, or `GET /v1/context/window-dumps/latest` for the full request payload. Dumps include focus-supervisor state when the runner is enforcing a next-action contract. Set `OMNIUS_CONTEXT_WINDOW_DUMP_DIR` to relocate dumps, `OMNIUS_DISABLE_CONTEXT_WINDOW_DUMPS=1` to disable them, or `OMNIUS_FOCUS_SUPERVISOR=off|auto|strict` to tune small-model focus enforcement.
+Context-window dumps are written before backend inference for main agents,
+sub-agents, internal runners, and adversary audits. Query
+`GET /v1/context/window-dumps?agent_type=main` for summaries with signal/noise
+metrics, or fetch a full payload by id. Dumps include focus-supervisor state when
+a next-action contract is active. Set `OMNIUS_CONTEXT_WINDOW_DUMP_DIR` to move
+the store, `OMNIUS_DISABLE_CONTEXT_WINDOW_DUMPS=1` to disable it, and
+`OMNIUS_FOCUS_SUPERVISOR=off|auto|strict` to tune focus enforcement.
 
-### Files, nexus, ollama pool
+### Files, Nexus, Ollama Pool
 
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `GET` | `/v1/files` | List workspace directory |
 | `POST` | `/v1/files/read` | Read workspace file |
+| `GET` | `/v1/files/raw` | Stream raw workspace bytes with content type and range support |
+| `HEAD` | `/v1/files/raw` | Inspect raw-file response metadata |
 | `GET` | `/v1/nexus/status` | Nexus peer state |
 | `GET` | `/v1/sponsors` | Sponsor directory cache |
 | `GET` | `/v1/ollama/pool/processes` | Ollama process inventory |
 | `POST` | `/v1/ollama/pool/cleanup` | Cleanup stale Ollama pool processes |
 
-### Voice, audio, vision
+### Voice, Audio, Vision
 
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `GET` | `/v1/voice/state` | Voice runtime status |
-| `POST` | `/v1/voice/start` · `/v1/voice/stop` | Enable/warm voice · pause voice input |
-| `GET`/`POST` | `/v1/voice/models` · `/v1/voice/models/switch` | List · switch and enable an exact TTS model |
-| `GET`/`POST` | `/v1/voice/supertonic-settings` | Read · update voice tuning |
-| `GET`/`POST` | `/v1/voice/asr-models` · `/v1/voice/asr-models/switch` | List · switch ASR model |
-| `POST` | `/v1/voice/tts` · `/v1/audio/speech` | Synthesize speech (+ OpenAI alias) |
-| `POST` | `/v1/voice/transcribe` · `/v1/audio/transcriptions` · `/v1/voice/transcribe/stream` | Transcribe (+ alias + streaming) |
-| `GET`/`POST` | `/v1/voice/clone-refs` | List · upload clone reference |
-| `POST` | `/v1/voice/clone-refs/upload` · `/v1/voice/clone-refs/from-url` | Upload · fetch clone reference |
-| `POST` | `/v1/voice/clone-refs/{filename}/activate` · `/v1/voice/clone-refs/{filename}/rename` | Activate · rename clone reference |
+| `POST` | `/v1/voice/start` | Select an optional model, enable voice, and wait for readiness |
+| `POST` | `/v1/voice/stop` | Pause daemon voice input while leaving TTS warm |
+| `GET` | `/v1/voice/models` | TTS models |
+| `POST` | `/v1/voice/models/switch` | Switch and enable an exact TTS model by default |
+| `GET` | `/v1/voice/supertonic-settings` | Voice tuning settings |
+| `POST` | `/v1/voice/supertonic-settings` | Update voice tuning settings |
+| `GET` | `/v1/asr/engines` | Canonical ASR engines/models, capabilities, readiness, and selection |
+| `GET` | `/v1/asr/status` · `/v1/asr/selection` | Selected engine/model and runtime status |
+| `PATCH` | `/v1/asr/selection` | Persist and activate an exact engine/model |
+| `POST` | `/v1/asr/activate` | Activate and persist an exact engine/model |
+| `POST` | `/v1/asr/engines/{engineId}/setup` | Install a managed runtime and pinned weights |
+| `POST` | `/v1/asr/transcriptions` · `/v1/asr/test` | Transcribe/test using the real selected backend |
+| `GET` | `/v1/voice/asr-models` | Compatibility registry alias |
+| `POST` | `/v1/voice/asr-models/switch` | Compatibility activation alias |
+| `POST` | `/v1/voice/tts` | Synthesize speech |
+| `POST` | `/v1/audio/speech` | OpenAI-compatible TTS alias |
+| `POST` | `/v1/voice/transcribe` | Transcribe audio |
+| `POST` | `/v1/voice/asr` | Legacy transcription alias |
+| `POST` | `/v1/audio/transcriptions` | OpenAI-compatible transcription alias |
+| `POST` | `/v1/voice/transcribe/stream` | Isolated final transcription over SSE (no shared mic state or fake partials) |
+| `POST` | `/v1/voice/clone-refs` | Upload voice clone reference |
+| `GET` | `/v1/voice/clone-refs` | List clone references |
+| `POST` | `/v1/voice/clone-refs/upload` | Upload clone reference |
+| `POST` | `/v1/voice/clone-refs/from-url` | Fetch clone reference |
+| `POST` | `/v1/voice/clone-refs/{filename}/activate` | Activate clone reference |
+| `POST` | `/v1/voice/clone-refs/{filename}/rename` | Rename clone reference |
 | `DELETE` | `/v1/voice/clone-refs/{filename}` | Delete clone reference |
 | `POST` | `/v1/voice/speak` | Broadcast speech to voicechat clients |
 | `GET` | `/v1/voicechat/ws` | WebSocket upgrade for full-duplex voicechat |
 | `POST` | `/v1/vision/describe` | Vision describe placeholder |
-
-TTS requests auto-warm the daemon and never silently fall back to a different
-voice. The built-in registry includes GLaDOS, Overwatch, and the packaged
-`luxtts:announcer-testchamber03` clone source. Voicebox defaults to its stable
-sub-model set; use `OMNIUS_VOICEBOX_MODELS=all` for the full suite or a
-comma-separated list of `voicebox_*` IDs for an explicit subset.
-
-### Generative media
-
-Backed by the unified `~/.omnius` store and shared venvs (see [Shared Media Dependencies](#shared-media-dependencies)). Outputs land in the global gallery at `~/.omnius/media/{images,videos,audio,music}`.
+| `POST` | `/v1/vision/embed` | Create a vision embedding from media |
+| `POST` | `/v1/audio/embed` | Create an audio embedding from audio input |
+
+`POST /v1/voice/tts` and `/v1/audio/speech` automatically warm the daemon.
+An explicit model must render exactly or the request fails; Omnius does not
+silently synthesize with another voice. Responses include `X-Voice-Model`,
+`X-Voice-Backend`, and `X-Sample-Rate`. Available models include GLaDOS,
+Overwatch, `luxtts:announcer-testchamber03`, and the selected Voicebox suite.
+Set `OMNIUS_VOICEBOX_MODELS=all` for every carried-in Voicebox model, leave it
+at `stable` for the default set, or provide a comma-separated subset.
+
+ASR selection is independent from TTS selection. The registry currently exposes
+OpenAI Whisper, managed `transcribe-cli`, NVIDIA Nemotron (reported unavailable
+until its legacy bootstrap is migrated), and Microsoft VibeVoice ASR. VibeVoice
+uses the exact pinned `microsoft/VibeVoice-ASR` checkpoint, reports setup and
+activation separately, supports completed files up to 60 minutes with speakers,
+timestamps, and `?context=` hotwords, and is deliberately not advertised as an
+incremental PCM backend. Its managed setup inherits the host CUDA-enabled Torch
+build (needed on Jetson/ARM64), never installs generic PyPI Torch, and activation
+requires one explicit capable GPU. Discrete Linux uses `nvidia-smi` process/GPU
+evidence; Jetson/L4T uses NVIDIA's documented `tegrastats` plus CUDA Torch device
+properties because `nvidia-smi` is unavailable there. Model weights live under
+the unified Omnius ASR cache and are not shipped in the npm package.
+
+### Generative Media
+
+All generation is backed by the unified `~/.omnius` model store and shared venvs (single source of truth — no per-project duplication). Generated files are consolidated into the global gallery at `~/.omnius/media/{images,videos,audio,music}`.
 
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `GET` | `/v1/media/models` | List available image/video/audio/music models |
 | `GET` | `/v1/media/store` | Unified store disk usage + reclaimable legacy caches |
 | `POST` | `/v1/media/migrate` | Dedup + migrate legacy per-group caches into the unified store |
-| `POST` | `/v1/media/image` · `/v1/media/video` · `/v1/media/audio` · `/v1/media/music` | Generate media (run scope) |
+| `POST` | `/v1/media/relocate` | Relocate the whole media store (weights/venvs/gallery) to a chosen folder |
+| `GET` | `/v1/media/relocate/status` | Status + progress of the media-store relocation job |
+| `POST` | `/v1/media/av/analyze` | Analyze a media file into a grounded entity/event answer (AV comprehension) |
+| `POST` | `/v1/media/image` | Generate an image |
+| `POST` | `/v1/media/video` | Generate a video |
+| `POST` | `/v1/media/audio` | Generate a sound effect |
+| `POST` | `/v1/media/music` | Generate music |
 | `GET` | `/v1/media/gallery` | List previously generated media (global, newest first) |
 | `GET` | `/v1/media/file` | Stream one generated media file |
 
-### Engines and scheduled jobs
+### Engines And Scheduled Jobs
 
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `GET` | `/v1/engines` | Long-running engine status |
-| `GET` | `/v1/scheduled` · `/v1/scheduled/all` · `/v1/scheduled/status` | List · list all · scheduler status |
-| `POST` | `/v1/scheduled/kill` · `/v1/scheduled/fixup` · `/v1/scheduled/reconcile` | Kill · reconcile · force reconcile |
+| `GET` | `/v1/scheduled` | List scheduled jobs |
+| `DELETE` | `/v1/scheduled/all` | Delete all tasks, timers, cron entries, and persisted sources |
+| `GET` | `/v1/scheduled/status` | Scheduler status |
+| `POST` | `/v1/scheduled/{id}` | Enable or disable one scheduled task or user timer |
+| `DELETE` | `/v1/scheduled/{id}` | Delete one scheduled task or user timer |
+| `POST` | `/v1/scheduled/kill` | Kill scheduled job |
+| `POST` | `/v1/scheduled/fixup` | Reconcile scheduled state |
+| `GET` | `/v1/scheduled/reconcile` | Preview scheduled reconciliation |
+| `POST` | `/v1/scheduled/reconcile` | Preview or apply scheduled reconciliation |
 | `GET` | `/v1/services/systemd` | Systemd service status |
+| `POST` | `/v1/services/systemd/{unit}` | Act on one user-level systemd unit |
 | `GET` | `/v1/update` | Self-update status |
+| `POST` | `/v1/update` | Start an exact-version verified global update transaction |
+
+#### Verified Global Update Transaction
 
-### AIMS governance (ISO/IEC 42001:2023)
+`POST /v1/update` is not a CLI-local package edit. It starts one durable
+transaction that installs the requested exact npm version globally, verifies
+the installed package and resolved `omnius` executable, restarts and verifies
+the daemon, verifies package/hash/runtime agreement, and relaunches the tray if
+it was running. The response is `202` with operation state; poll
+`GET /v1/update` for live phase, subprocess output, verification evidence, and
+the final success or failure. Concurrent transactions and requests with no
+available target return `409`.
+
+The web dashboard and native tray both use this same endpoint. Update discovery
+is shared and semver-aware, so an older cached registry result cannot downgrade
+or falsely present an update. A completed transaction means the global package,
+executable, daemon, and tray runtime were all reconciled—not merely that `npm`
+exited successfully.
+
+### AIMS Governance
 
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `GET` | `/v1/aims` | AIMS root and endpoint index |
-| `GET`/`PUT` | `/v1/aims/policies` | Policy register · replace |
-| `GET` | `/v1/aims/roles` · `/v1/aims/resources` | Roles · resource inventory |
-| `GET`/`POST` | `/v1/aims/impact-assessments` | List · file impact assessment |
-| `GET` | `/v1/aims/lifecycle` · `/v1/aims/data-quality` · `/v1/aims/transparency` · `/v1/aims/usage` · `/v1/aims/suppliers` | Lifecycle, data quality, transparency, usage, suppliers |
-| `GET`/`POST` | `/v1/aims/incidents` | List · file incident |
-| `GET` | `/v1/aims/oversight` · `/v1/aims/decisions` · `/v1/aims/config-history` | Oversight gates · decision log · config history |
-
-For per-endpoint schemas, parameters, and response shapes, see the served `/openapi.json` and the maintained inventory in [`docs/reference/rest-api.md`](docs/reference/rest-api.md).
-
+| `GET` | `/v1/aims/policies` | Policy register |
+| `PUT` | `/v1/aims/policies` | Replace policy register |
+| `GET` | `/v1/aims/roles` | Roles and responsibilities |
+| `GET` | `/v1/aims/resources` | Resource inventory |
+| `GET` | `/v1/aims/impact-assessments` | Impact assessments |
+| `POST` | `/v1/aims/impact-assessments` | File impact assessment |
+| `GET` | `/v1/aims/lifecycle` | Lifecycle state |
+| `GET` | `/v1/aims/data-quality` | Data quality controls |
+| `GET` | `/v1/aims/transparency` | Model cards and transparency |
+| `GET` | `/v1/aims/usage` | AIMS usage view |
+| `GET` | `/v1/aims/suppliers` | Supplier inventory |
+| `GET` | `/v1/aims/incidents` | Incident records |
+| `POST` | `/v1/aims/incidents` | File incident |
+| `GET` | `/v1/aims/oversight` | Human oversight gates |
+| `GET` | `/v1/aims/decisions` | Consequential decision log |
+| `GET` | `/v1/aims/config-history` | Config change history |
+
+### Browser And Compatibility Surfaces
+
+The dashboard HTML routes (`/`, `/chat`, `/agent`, `/voice`, `/generate`,
+`/projects`, `/dashboard`, `/jobs`, `/activity`, `/discover`, `/settings`, and
+`/config`) are documented in the [dashboard guide](../guides/dashboard.md). They
+are pages, not JSON API operations; `/` returns the HATEOAS JSON root when the
+client does not request HTML.
+
+Swagger/ReDoc trailing-slash variants, `/api/docs/*` static assets, and
+`/favicon.ico` exist for browsers. They are delivery details rather than stable
+integration endpoints. The daemon also retains browser/legacy bridges at
+`/v1/model`, `/v1/endpoint`, `/v1/theme`, `/v1/tor/*`, `/v1/remote-proxy`, and
+`/v1/command`. New clients should prefer `/v1/config/model`,
+`/v1/config/endpoint`, `/v1/config`, and `/v1/commands/{cmd}`. Compatibility
+handlers may accept additional HTTP verbs for old dashboard bundles; only the
+methods in the supported inventory above are contractual.
+<!-- END GENERATED REST INVENTORY -->
 ## Agent-Explorable Documentation
 
 Omnius discovers project-local docs skills from `.aiwg/addons/*/skills`. The docs bundles in this repo expose high-signal entrypoints for agents: