omnius 1.0.609 → 1.0.610

package/docs/DISCOVERY.md

@@ -46,14 +46,20 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 
 | ID | Title | Summary |
 | --- | --- | --- |
+| `api.` | / | HATEOAS API root when the client does not request HTML |
+| `api.asyncapi` | /asyncapi | Compatibility alias for the AsyncAPI contract |
 | `api.discovery` | Discovery API | Search the Omnius capability catalog and expand a stable entry over REST. |
 | `api.health` | /health | Liveness probe |
 | `api.health-ready` | /health/ready | Readiness probe |
 | `api.health-startup` | /health/startup | Startup complete |
+| `api.help` | /help | Compact daemon help and integration entrypoints |
 | `api.metrics` | /metrics | Prometheus metrics |
 | `api.openapi` | OpenAPI contract | The live machine-readable REST contract for the running Omnius daemon. |
+| `api.realtime` | /realtime | Generate one short text reply for a voice-adapter transcript |
+| `api.routes` | /routes | Compatibility alias for the daemon route summary |
 | `api.skills` | Skills API | List and load Omnius and project skills incrementally. |
 | `api.tools` | Tools API | Inspect live tool schemas and invocation metadata, register external tools, and call only tools marked direct-callable. |
+| `api.v1-admin-access` | /v1/admin/access | Read the daemon network access mode; Change and persist the daemon network access mode from loopback |
 | `api.v1-agents` | /v1/agents | List agent types |
 | `api.v1-aims` | /v1/aims | AIMS root — control map and endpoint index |
 | `api.v1-aims-config-history` | /v1/aims/config-history | Configuration change history (A.6.2.8) |
@@ -87,13 +93,16 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `api.v1-asr-status` | /v1/asr/status | Read the selected ASR engine/model and runtime status |
 | `api.v1-asr-test` | /v1/asr/test | Test the selected ASR engine using an uploaded audio sample |
 | `api.v1-asr-transcriptions` | /v1/asr/transcriptions | Transcribe audio with the selected ASR engine |
+| `api.v1-audio-embed` | /v1/audio/embed | Create an audio embedding for uploaded or referenced audio |
 | `api.v1-audio-speech` | /v1/audio/speech | OpenAI-compatible alias of /v1/voice/tts (input/voice/response_format names) |
 | `api.v1-audio-transcriptions` | /v1/audio/transcriptions | OpenAI-compatible alias of /v1/asr/transcriptions |
 | `api.v1-audit` | /v1/audit | Query audit log |
 | `api.v1-chat` | /v1/chat | Stateful chat session with full agent tool access (OpenAI-compatible response shape) |
+| `api.v1-chat-attachments` | /v1/chat/attachments | Upload an attachment for a stateful chat |
 | `api.v1-chat-check-in` | /v1/chat/check-in | Send a steering check-in to the active chat session — returns model inference + queued steering_packet |
 | `api.v1-chat-completions` | /v1/chat/completions | OpenAI-compatible chat completion (with optional server-side agent loop) |
-| `api.v1-chat-sessions` | /v1/chat/sessions | List active chat sessions |
+| `api.v1-chat-sessions` | /v1/chat/sessions | List persisted browser chats and importable TUI sessions for a workspace |
+| `api.v1-chat-sessions-id` | /v1/chat/sessions/{id} | Hydrate one chat or imported TUI session with full history and live-run state; Permanently delete a canonical chat or TUI history session |
 | `api.v1-chat-sessions-id-status` | /v1/chat/sessions/{id}/status | Reactive recall: is this session running right now + unseen deltas since ?since=&lt;seq&gt; (running, phase, seq, partial, deltas[]) |
 | `api.v1-chat-sessions-id-summarize` | /v1/chat/sessions/{id}/summarize | Generate + cache an inference-based title/summary for a session — body {force?, root?} |
 | `api.v1-chat-suggest-followup` | /v1/chat/suggest-followup | Suggest one short next-message follow-up for a session (ghost-text input) — body {session_id} |
@@ -121,6 +130,7 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `api.v1-evaluate` | /v1/evaluate | Evaluate a run by ID |
 | `api.v1-events` | /v1/events | Subscribe to the event bus (PT-06) |
 | `api.v1-files` | /v1/files | List workspace directory |
+| `api.v1-files-raw` | /v1/files/raw | Stream raw workspace file bytes for browser previews; Inspect raw workspace file response metadata |
 | `api.v1-files-read` | /v1/files/read | Read file content (PT-05) |
 | `api.v1-hooks` | /v1/hooks | List hook types and counts |
 | `api.v1-index` | /v1/index | Trigger repository indexing |
@@ -142,8 +152,12 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `api.v1-media-store` | /v1/media/store | Media-store root + disk usage plus any legacy per-group caches still reclaimable |
 | `api.v1-media-video` | /v1/media/video | Generate a video — body {prompt, model?, backend?, num_frames?, fps?, width?, height?, steps?, guidance?, seed?} |
 | `api.v1-memory` | /v1/memory | Memory backends summary (PT-04) |
+| `api.v1-memory-entities` | /v1/memory/entities | List extracted memory entities |
 | `api.v1-memory-episodes` | /v1/memory/episodes | List episodes |
 | `api.v1-memory-failures` | /v1/memory/failures | List failures |
+| `api.v1-memory-feedback` | /v1/memory/feedback | Record relevance or quality feedback for a memory item |
+| `api.v1-memory-ingest` | /v1/memory/ingest | Ingest content or files into Omnius memory |
+| `api.v1-memory-jobs-run` | /v1/memory/jobs/run | Run a named memory maintenance job |
 | `api.v1-memory-search` | /v1/memory/search | Search memory stores (PT-04) |
 | `api.v1-memory-write` | /v1/memory/write | Write a memory entry (PT-04) |
 | `api.v1-models` | /v1/models | List aggregated models |
@@ -157,17 +171,23 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `api.v1-projects-preferences` | /v1/projects/preferences | Get per-project UI preferences (model, theme, current chat session id, current agent run id, recent indexes); Patch preferences (server-managed v + updatedAt are stripped from client patches); Reset preferences to default |
 | `api.v1-projects-register` | /v1/projects/register | Register a project root — body {root, pid?} |
 | `api.v1-projects-rename` | /v1/projects/rename | Rename a project — body {root, name} |
+| `api.v1-projects-scan` | /v1/projects/scan | Scan configured roots for discoverable project workspaces |
 | `api.v1-projects-switch` | /v1/projects/switch | Set the active project — body {root, registerIfMissing?} |
+| `api.v1-realtime` | /v1/realtime | Auth-scoped alias for the text-only realtime voice adapter |
+| `api.v1-routes` | /v1/routes | Flat grep-friendly daemon route summary |
 | `api.v1-run` | /v1/run | Submit agentic task |
 | `api.v1-runs` | /v1/runs | List runs |
 | `api.v1-runs-id` | /v1/runs/{id} | Get run details; Abort run |
+| `api.v1-runs-id-output` | /v1/runs/{id}/output | Read the captured output for one agentic run |
 | `api.v1-scheduled` | /v1/scheduled | List scheduled jobs |
-| `api.v1-scheduled-all` | /v1/scheduled/all | List all scheduled jobs (all queues) |
+| `api.v1-scheduled-all` | /v1/scheduled/all | Delete all scheduled tasks, timers, cron entries, and persisted sources |
 | `api.v1-scheduled-fixup` | /v1/scheduled/fixup | Reconcile scheduled job state |
+| `api.v1-scheduled-id` | /v1/scheduled/{id} | Enable or disable one scheduled task or user timer; Delete one scheduled task or user timer |
 | `api.v1-scheduled-kill` | /v1/scheduled/kill | Kill a running scheduled job |
-| `api.v1-scheduled-reconcile` | /v1/scheduled/reconcile | Force-reconcile scheduled jobs against persisted state |
+| `api.v1-scheduled-reconcile` | /v1/scheduled/reconcile | Preview reconciliation of persisted and legacy scheduled jobs; Preview or apply scheduled-job reconciliation |
 | `api.v1-scheduled-status` | /v1/scheduled/status | Status of scheduled job runner |
 | `api.v1-services-systemd` | /v1/services/systemd | Systemd service status (where supported) |
+| `api.v1-services-systemd-unit` | /v1/services/systemd/{unit} | Perform an action on one user-level systemd unit |
 | `api.v1-sessions` | /v1/sessions | List Omnius task sessions |
 | `api.v1-sessions-id` | /v1/sessions/{id} | Get session history |
 | `api.v1-skills` | /v1/skills | List AIWG skills (PT-02) |
@@ -184,6 +204,7 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `api.v1-update` | /v1/update | Global Omnius update transaction status; Start an exact-version global Omnius update |
 | `api.v1-usage` | /v1/usage | Token usage and rate limits |
 | `api.v1-vision-describe` | /v1/vision/describe | Vision describe (deferred to PT-07) |
+| `api.v1-vision-embed` | /v1/vision/embed | Create a vision embedding for uploaded or referenced media |
 | `api.v1-voice-asr` | /v1/voice/asr | Legacy alias of /v1/asr/transcriptions |
 | `api.v1-voice-asr-models` | /v1/voice/asr-models | Compatibility alias of GET /v1/asr/engines |
 | `api.v1-voice-asr-models-switch` | /v1/voice/asr-models/switch | Compatibility alias of POST /v1/asr/activate |
@@ -374,6 +395,7 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `guide.getting-started-model-providers` | Model Providers And Endpoints | Omnius routes model requests through a provider abstraction instead of treating local Ollama as the only source of models. |
 | `guide.guides-agent-integration` | Agent And Service Integration | An integration should discover Omnius at runtime instead of encoding a partial provider or tool list. |
 | `guide.guides-bring-your-own-inference` | Bring Your Own Inference | Omnius routes local and hosted models through an explicit provider descriptor. The descriptor determines the wire protocol, URL paths, authentication headers, and supported operations. It is the source of truth used by setup, model discovery, TUI runs, REST chat, summaries, voice, Telegram, sponsors, and endpoint probes. |
+| `guide.guides-dashboard` | Web Dashboard | The Omnius daemon serves a zero-build, self-contained dashboard from the same origin as the REST API. Start it with omnius serve, then open http://127.0.0.1:11435/. The interface uses Omnius's compact NOCLIP-derived style kit and shared responsive observability-card grids; the route registry in packages/cli/src/api/web-ui.ts is the source of truth for pages  |
 | `guide.guides-media-generation` | Media Generation | Omnius exposes media generation through TUI commands, tools, Telegram creative workflows, and sponsor media endpoints. |
 | `guide.guides-osint-research` | Categorized OSINT research | Omnius ships a local, searchable snapshot of the OSINT4ALL Start.me page. It uses the same compact discovery pattern as AIWG skills: |
 | `guide.guides-realtime` | Realtime Conversations | Realtime mode is for short, natural, back-and-forth spoken conversation behind ASR and TTS. |
@@ -403,7 +425,7 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `guide.proposals-opencode-modules-runner` | Runner | Bundled Omnius documentation artifact: docs/proposals/opencode-modules/runner.ts. |
 | `guide.reference-auth-map` | Authentication And Authorization Map | Omnius has two separate credential boundaries: |
 | `guide.reference-configuration` | Configuration Reference | Configuration is layered from environment, global user settings, project settings, and active TUI state. |
-| `guide.reference-rest-api` | REST API Reference | This is the maintained human endpoint inventory for the Omnius daemon. The machine contract is generated by packages/cli/src/api/openapi.ts and served at /openapi.json. |
+| `guide.reference-rest-api` | REST API Reference | This is the maintained human inventory for the supported Omnius daemon API. The machine contract is generated by packages/cli/src/api/openapi.ts and served at /openapi.json; every operation in that contract must appear here, and the generated REST block in the root README must match this file byte-for-byte after heading normalization. Browser HTML routes and |
 | `guide.reference-slash-commands` | Slash Commands | This file is generated from packages/cli/src/tui/command-registry.ts. |
 | `guide.research-archived-context-window-attention-model` | Context Window Attention Model | Bundled Omnius documentation artifact: docs/research/_archived/context_window_attention_model.py. |
 | `guide.research-archived-context-window-attention-spec` | Context Window Attention-Weighted Optimization Spec | The context window treats all items (system prompt, memory cards, chat history, voice transcriptions, reflection notes) at roughly equal attention weight (~1.0). This causes: |

package/docs/guides/dashboard.md

@@ -0,0 +1,170 @@
+# Web Dashboard
+
+The Omnius daemon serves a zero-build, self-contained dashboard from the same
+origin as the REST API. Start it with `omnius serve`, then open
+`http://127.0.0.1:11435/`. The interface uses Omnius's compact NOCLIP-derived
+style kit and shared responsive observability-card grids; the route registry in
+`packages/cli/src/api/web-ui.ts` is the source of truth for pages and aliases.
+
+## Routes
+
+| Route | Alias | Operational surface |
+| --- | --- | --- |
+| `/chat` | `/` | Stateful conversations, full history, active plan/context, attachments, files, and steering check-ins |
+| `/agent` | - | One-shot agent task contract, persona/profile, isolation controls, run history, and event stream |
+| `/voice` | - | Voicechat, exact TTS model selection, model options, ASR setup/activation/test, transcript, and TTS test |
+| `/generate` | - | Image/video/audio/music generation, AV analysis, store relocation, model inventory, and global gallery |
+| `/projects` | - | Workspace discovery, registration, activation, rename, removal, and current-context inspection |
+| `/dashboard` | `/jobs` | System/GPU/resource state, processes, scheduler, services, usage, and update state |
+| `/activity` | - | Run, tool, engine, memory, and server-event observability |
+| `/discover` | - | Capability-catalog start points, intent search, and exact discovery-entry expansion |
+| `/settings` | `/config` | Models, endpoints, voice, runtime behavior, access, keys, appearance, and service configuration |
+
+The browser router and daemon HTML allow-list consume the same route registry,
+so a page cannot be added in only one layer without a route test failing.
+
+## Workspace Scope
+
+The active workspace is global daemon state and scopes project preferences,
+browser chat organization, TUI session discovery, files, model/theme choices,
+and agent forms. The clickable brand at the top of the sidebar opens a searchable
+workspace dialog sourced from `GET /v1/projects`. Selecting an entry calls
+`POST /v1/projects/switch`; **Manage workspaces** opens `/projects`.
+
+Every normal TUI start registers its working directory. The Projects page can
+also call `GET /v1/projects/scan`, explicitly register a root, rename it, make it
+current, or unregister it. Per-project preferences are server-managed through
+`/v1/projects/preferences`; the client cannot overwrite the preference schema
+version or `updatedAt` fields.
+
+## Chats, TUI Sessions, And Agent Runs
+
+Chats and agent runs are intentionally different records:
+
+- A chat is a multi-turn conversation backed by the canonical daemon chat
+  store. It may have an active agent subprocess and a reactive partial reply.
+- A TUI session is quality-filtered visual history imported from the selected
+  workspace. Its public id has a `tui:` prefix.
+- An agent run is a one-shot execution record and form snapshot shown on the
+  Agent page; it is not inserted into the chat list.
+
+The chat index calls `GET /v1/chat/sessions?root=<workspace>`. By default the
+response combines persisted browser chats with importable TUI sessions. The
+session-quality layer suppresses exit-only commands such as `/quit` and `/exit`,
+manual-save placeholders, empty/noise-only transcripts, and duplicate normalized
+TUI histories. Pass `include_tui=0` when an integration needs browser chats only.
+
+Opening a chat calls `GET /v1/chat/sessions/{id}` and hydrates the complete
+public message history, source transcript, token/timestamp metadata, and any
+in-flight run. While a run is active, the page polls
+`GET /v1/chat/sessions/{id}/status?since=<seq>` to restore unseen deltas rather
+than rerunning the task. Summaries/titles and ghost-text follow-ups use the
+dedicated summarize and suggest endpoints.
+
+Search, pins, folders, folder open-state, and inline display renames are
+workspace-scoped browser organization stored in local storage. They do not
+rewrite the underlying daemon transcript. The current dashboard **del** and row
+delete controls remove the browser-side organization entry only; a canonical
+delete must use the admin-scoped `DELETE /v1/chat/sessions/{id}` endpoint. This
+distinction prevents documentation from implying that hiding a row destroyed
+server history.
+
+During an active chat, typing can become a steering check-in. The raw user input
+and its interpreted steering packet are persisted, rendered in the conversation,
+and delivered to the runner at a turn boundary through `/v1/chat/check-in`.
+
+## Agent Command Center
+
+The Agent page keeps task definition and runtime observability together. It
+contains the task contract, working directory/workspace synchronization,
+persona/profile, model and endpoint selection, tool and sandbox controls,
+isolation settings, run submission, captured output, and event history. Submit
+with `POST /v1/run`, query `/v1/runs` or `/v1/runs/{id}`, read captured output at
+`/v1/runs/{id}/output`, and abort with `DELETE /v1/runs/{id}`.
+
+## Voice And ASR
+
+The Voice page exposes the same control plane as the CLI and REST API:
+
+1. Read `/v1/voice/state` and `/v1/voice/models`.
+2. Switch an exact TTS model with `/v1/voice/models/switch`; starting or TTS
+   synthesis warms the selected engine instead of silently falling back.
+3. Read `/v1/asr/engines`, choose an engine/model, run managed setup when its
+   runtime or weights are absent, activate it, then upload a real audio sample to
+   `/v1/asr/test` with optional names/hotwords/context.
+4. Start `/v1/voicechat/ws` for full-duplex browser mic → ASR → agent text → TTS
+   audio. Transcript, partial/final state, agent text, synthesis boundaries, and
+   errors remain visible in the page.
+
+TTS choices include GLaDOS, Overwatch, the packaged
+`luxtts:announcer-testchamber03` reference, and enabled Voicebox models. ASR is
+selected independently and includes Whisper, managed `transcribe-cli`, the
+currently gated Nemotron adapter, and pinned Microsoft VibeVoice ASR. VibeVoice
+is a completed-file backend (up to 60 minutes, with speakers/timestamps/context),
+not an incremental PCM backend. On CUDA Jetson/ARM64, managed setup inherits the
+host CUDA Torch build and hardware readiness uses `tegrastats` plus Torch CUDA
+device properties; it never replaces the host build with generic PyPI Torch.
+
+## Generate And Media Store
+
+Generate lists available model adapters, accepts image/video/audio/music jobs,
+shows model and progress state, and reads the project-independent global gallery
+under `~/.omnius/media`. It also exposes:
+
+- AV analysis through `POST /v1/media/av/analyze`;
+- store inspection/migration through `/v1/media/store` and `/v1/media/migrate`;
+- store relocation with a dry-run or background job through
+  `/v1/media/relocate`, with progress from `/v1/media/relocate/status`;
+- raw media streaming through `/v1/media/file`.
+
+Heavy runtimes and weights remain in the unified Omnius model store; they are
+not copied into each workspace or shipped in the npm package.
+
+## Dashboard, Activity, Discovery, And Settings
+
+The Dashboard page combines resource metrics, GPU/VRAM placement, Ollama pool
+state, process/run cards, scheduled work, user services, token usage, and update
+progress. Activity consumes the SSE event stream and presents run/tool/memory/
+engine state. Discover begins from `/v1/discovery/bootstrap`, searches the
+machine catalog, and expands exact entries without requiring source inspection.
+Settings groups model/endpoint, voice, runtime, access/key, appearance, and
+service controls while preserving project scope.
+
+## Verified Updates
+
+The dashboard polls `/v1/system` every 10 seconds. When its semver-safe registry
+check reports `latest_version`, the normally hidden update controls become exact
+version buttons. Clicking one:
+
+1. preflights the live daemon version;
+2. sends `POST /v1/update` with that exact semver;
+3. polls `GET /v1/update` every two seconds for the durable operation id, phase,
+   live subprocess output, failure remediation, and verification evidence;
+4. requires the installed package, resolved executable, restarted daemon,
+   installed package hash, daemon boot hash, and target version to agree;
+5. reconnects event/model/health views only after verification succeeds.
+
+If the tray was running, the coordinator relaunches and verifies it. A failed or
+timed-out update stays visibly failed and includes the update log path; it is not
+reported as complete merely because an npm child exited.
+
+## Authentication And Remote Access
+
+Loopback is the default and the safest dashboard deployment. If REST bearer keys
+are configured, the browser stores the selected key locally and sends it through
+the same scope policy as external clients (`read` < `run` < `admin`). Remote
+access should use a tunnel or an authenticated share URL; changing
+`/v1/admin/access` is loopback-only even when the current policy is `any`.
+
+Useful diagnostics:
+
+```bash
+curl -s http://127.0.0.1:11435/health
+curl -s http://127.0.0.1:11435/version
+curl -s http://127.0.0.1:11435/v1/routes
+curl -s http://127.0.0.1:11435/v1/projects
+curl -s http://127.0.0.1:11435/v1/update
+```
+
+For the complete supported API use the [REST reference](../reference/rest-api.md),
+and for bearer-key behavior use the [authentication map](../reference/auth-map.md).

package/docs/guides/system-tray.md

@@ -46,6 +46,34 @@ version, dashboard and log shortcuts, service-manager-aware daemon controls,
 login-startup control, and **Quit indicator**. Daemon stop is a separate,
 explicit menu action.
 
+## Health And Updates
+
+The indicator refreshes daemon health and update availability at startup and
+every 10 seconds. Update discovery uses the same cached registry lookup and
+semver comparator as the CLI and dashboard, so an older registry/cache value is
+never presented as an upgrade.
+
+The first menu row always shows the live daemon version and health. It is greyed
+and non-clickable while that version is current. When a newer exact version is
+available, the same row changes to **update to vX.Y.Z available** and becomes the
+primary update button. While an update runs it displays the durable transaction
+phase; if verification fails it stays clickable as a retry and its tooltip shows
+the remediation/error instead of silently returning to the current state.
+
+Clicking the row starts the same verified global update transaction as
+`POST /v1/update` and `/update quick`. The coordinator:
+
+1. installs the exact target through the real global npm flow;
+2. verifies the installed package and resolved `omnius` executable;
+3. restarts the daemon and verifies the target runtime and boot/package hashes;
+4. relaunches and verifies the indicator because it was running when the update
+   started.
+
+State persists in `~/.omnius/update-state.json` and detailed output in
+`~/.omnius/update.log`, so a daemon or tray restart does not turn an incomplete
+install into a false success. The dashboard can inspect the same operation with
+`GET /v1/update`.
+
 ## Linux / Ubuntu
 
 GNOME needs a StatusNotifier/AppIndicator host. Ubuntu Desktop normally ships

package/docs/index.md

@@ -25,6 +25,7 @@ should additionally expand the owning layer and module.
 ## Workflows
 
 - [TUI Workflows](./guides/tui-workflows.md)
+- [Web Dashboard](./guides/dashboard.md)
 - [Sponsor And COHERE](./guides/sponsor-and-cohere.md)
 - [Realtime Conversation](./guides/realtime.md)
 - [Telegram](./guides/telegram.md)

package/docs/reference/rest-api.md

@@ -1,6 +1,11 @@
 # REST API Reference
 
-This is the maintained human endpoint inventory for the Omnius daemon. The machine contract is generated by `packages/cli/src/api/openapi.ts` and served at `/openapi.json`.
+This is the maintained human inventory for the supported Omnius daemon API. The
+machine contract is generated by `packages/cli/src/api/openapi.ts` and served at
+`/openapi.json`; every operation in that contract must appear here, and the
+generated REST block in the root README must match this file byte-for-byte after
+heading normalization. Browser HTML routes and implementation-only compatibility
+bridges are documented separately and are not part of the stable REST contract.
 
 Run the drift check before publishing docs:
 
@@ -21,6 +26,12 @@ pnpm docs:check
 | `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
 
@@ -58,11 +69,42 @@ pnpm docs:check
 | `POST` | `/v1/embeddings` | OpenAI-compatible embeddings |
 | `POST` | `/api/embed` | Ollama-compatible embeddings alias |
 | `GET` | `/api/tags` | Ollama-compatible model tags |
-| `GET` | `/v1/chat/sessions` | Active chat sessions |
+| `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 |
+| `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
 
@@ -71,6 +113,7 @@ pnpm docs:check
 | `POST` | `/v1/run` | Submit agentic task |
 | `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` | `/v1/todos` | Create or update todos for current session |
 | `GET` | `/v1/todos` | List sessions with todos |
@@ -110,6 +153,9 @@ pnpm docs:check
 | `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
 
@@ -133,6 +179,37 @@ pnpm docs:check
 | `GET` | `/v1/codegraph/snapshot` | Code graph snapshot |
 | `GET` | `/v1/codegraph/events` | Code graph SSE |
 
+### Registering Application-Specific Tools
+
+Applications can register their own tools so Omnius agents can discover and
+invoke them alongside built-ins. `transport.type` selects the bridge:
+
+- `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.
+
+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
+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",
+  "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 …"}
+}'
+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"}}'
+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 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 |
@@ -158,6 +235,10 @@ pnpm docs:check
 | `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 |
@@ -167,12 +248,22 @@ pnpm docs:check
 | `GET` | `/v1/context/restore` | Build restore prompt |
 | `POST` | `/v1/context/compact` | Request compaction |
 
+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
 
 | 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 |
@@ -213,6 +304,8 @@ pnpm docs:check
 | `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 |
+| `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
@@ -260,14 +353,35 @@ All generation is backed by the unified `~/.omnius` model store and shared venvs
 | --- | --- | --- |
 | `GET` | `/v1/engines` | Long-running engine status |
 | `GET` | `/v1/scheduled` | List scheduled jobs |
-| `GET` | `/v1/scheduled/all` | List all 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 |
-| `POST` | `/v1/scheduled/reconcile` | Force scheduled reconciliation |
+| `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` | Queue or run the package update flow |
+| `POST` | `/v1/update` | Start an exact-version verified global update transaction |
+
+### Verified Global Update Transaction
+
+`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
 
@@ -290,3 +404,20 @@ All generation is backed by the unified `~/.omnius` model store and shared venvs
 | `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.

package/docs/rest/INDEX.md

@@ -96,28 +96,28 @@ Scopes:
 | --- | --- |
 | Health | `/health`, `/health/ready`, `/health/startup`, `/version`, `/metrics` |
 | Discovery | `/v1/discovery/bootstrap`, `/v1/discovery`, `/v1/discovery/{id}` |
-| Inference and chat | `/v1/models`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/chat`, `/v1/generate`, `/api/generate`, `/v1/chat/sessions`, `/v1/chat/check-in` |
+| Inference and chat | `/v1/models`, `/v1/chat/completions`, `/v1/chat`, `/realtime`, `/v1/realtime`, `/v1/chat/sessions`, `/v1/chat/sessions/{id}`, `/v1/chat/check-in` |
 | AIWG | `/v1/aiwg`, `/v1/aiwg/frameworks`, `/v1/aiwg/skills`, `/v1/aiwg/use`, `/v1/aiwg/expand` |
-| Runs | `/v1/run`, `/v1/runs`, `/v1/runs/{id}`, `/v1/todos`, `/v1/todos/{session_id}` |
+| Runs | `/v1/run`, `/v1/runs`, `/v1/runs/{id}`, `/v1/runs/{id}/output`, `/v1/todos`, `/v1/todos/{session_id}` |
 | Config | `/v1/config`, `/v1/config/model`, `/v1/config/endpoint`, `/v1/config/endpoint/test`, `/v1/config/endpoint/history`, `/v1/share/generate` |
 | Metering and audit | `/v1/usage`, `/v1/audit`, `/v1/cost`, `/v1/system` |
 | Runtime keys | `/v1/keys`, `/v1/keys/{prefix}` |
 | Profiles | `/v1/profiles`, `/v1/profiles/{name}` |
-| Files | `/v1/files`, `/v1/files/read` |
+| Files | `/v1/files`, `/v1/files/read`, `/v1/files/raw` |
 | Skills and commands | `/v1/skills`, `/v1/skills/{name}`, `/v1/commands`, `/v1/commands/{cmd}` |
 | MCP | `/v1/mcps`, `/v1/mcps/{name}`, `/v1/mcps/{name}/call` |
 | Tools | `/v1/tools`, `/v1/tools/{name}`, `/v1/tools/{name}/call`, `/v1/hooks`, `/v1/agents` |
-| Memory | `/v1/memory`, `/v1/memory/search`, `/v1/memory/write`, `/v1/memory/episodes`, `/v1/memory/failures` |
+| Memory | `/v1/memory`, `/v1/memory/search`, `/v1/memory/write`, `/v1/memory/ingest`, `/v1/memory/entities`, `/v1/memory/jobs/run`, `/v1/memory/feedback` |
 | Events | `/v1/events` |
 | Sessions and context | `/v1/sessions`, `/v1/sessions/{id}`, `/v1/context`, `/v1/context/window-dumps`, `/v1/context/window-dumps/{id}`, `/v1/context/save`, `/v1/context/restore`, `/v1/context/compact` |
 | Nexus | `/v1/nexus/status`, `/v1/sponsors` |
 | Ollama pool | `/v1/ollama/pool/processes`, `/v1/ollama/pool/cleanup` |
 | Voice and audio | `/v1/voice/state`, `/v1/voice/models`, `/v1/voice/tts`, `/v1/audio/speech`, `/v1/asr/engines`, `/v1/asr/selection`, `/v1/asr/activate`, `/v1/asr/transcriptions`, `/v1/asr/test`, `/v1/audio/transcriptions`, `/v1/voicechat/ws` |
-| Vision | `/v1/vision/describe` |
-| Projects | `/v1/projects`, `/v1/projects/current`, `/v1/projects/switch`, `/v1/projects/register`, `/v1/projects/rename`, `/v1/projects/preferences` |
+| Vision/audio embeddings | `/v1/vision/describe`, `/v1/vision/embed`, `/v1/audio/embed` |
+| Projects | `/v1/projects`, `/v1/projects/current`, `/v1/projects/switch`, `/v1/projects/register`, `/v1/projects/rename`, `/v1/projects/scan`, `/v1/projects/preferences` |
 | Code graph | `/v1/codegraph/snapshot`, `/v1/codegraph/events` |
 | Scheduled jobs | `/v1/scheduled`, `/v1/scheduled/all`, `/v1/scheduled/status`, `/v1/scheduled/kill`, `/v1/scheduled/fixup`, `/v1/scheduled/reconcile` |
-| Services and update | `/v1/services/systemd`, `/v1/update` |
+| Services and update | `/v1/services/systemd`, `/v1/services/systemd/{unit}`, `/v1/update` |
 | AIMS | `/v1/aims`, `/v1/aims/policies`, `/v1/aims/roles`, `/v1/aims/resources`, `/v1/aims/impact-assessments`, `/v1/aims/lifecycle`, `/v1/aims/data-quality`, `/v1/aims/transparency`, `/v1/aims/usage`, `/v1/aims/suppliers`, `/v1/aims/incidents`, `/v1/aims/oversight`, `/v1/aims/decisions`, `/v1/aims/config-history` |
 
 ## Realtime REST Flag