omnius 1.0.608 → 1.0.610

package/docs/rest/QUICKREF.md

@@ -44,6 +44,7 @@ curl -s http://127.0.0.1:11435/version
 ## Discovery
 
 ```bash
+curl -s http://127.0.0.1:11435/v1/discovery/bootstrap
 curl -s 'http://127.0.0.1:11435/v1/discovery?q=bring%20your%20own%20inference'
 curl -s http://127.0.0.1:11435/v1/discovery/tool.web-search
 ```
@@ -71,6 +72,22 @@ curl -s http://127.0.0.1:11435/v1/chat \
   -d '{"message":"Keep this short for voice.","realtime":true}'
 ```
 
+Text-only ASR/TTS adapter:
+
+```bash
+curl -s http://127.0.0.1:11435/v1/realtime \
+  -H 'content-type: application/json' \
+  -d '{"message":"Give me one short spoken reply."}'
+```
+
+## Session History
+
+```bash
+curl -s 'http://127.0.0.1:11435/v1/chat/sessions?root=/absolute/workspace'
+curl -s 'http://127.0.0.1:11435/v1/chat/sessions/tui%3Asession-id?root=/absolute/workspace'
+curl -s 'http://127.0.0.1:11435/v1/chat/sessions/tui%3Asession-id/status?since=0'
+```
+
 ## OpenAI-Compatible Chat
 
 ```bash
@@ -146,6 +163,28 @@ curl -s -X POST http://127.0.0.1:11435/v1/voice/tts \
   --output speech.wav
 ```
 
+## ASR Registry And Test
+
+```bash
+curl -s http://127.0.0.1:11435/v1/asr/engines
+curl -s http://127.0.0.1:11435/v1/asr/status
+curl -s -X POST http://127.0.0.1:11435/v1/asr/activate \
+  -H 'content-type: application/json' \
+  -d '{"engine_id":"transcribe-cli"}'
+```
+
+## Verified Global Update
+
+```bash
+curl -s http://127.0.0.1:11435/v1/update
+curl -s -X POST http://127.0.0.1:11435/v1/update \
+  -H 'content-type: application/json' \
+  -d '{"version":"1.2.3"}'
+```
+
+The POST requires an exact semver. Poll the GET route for live phase/output and
+package, executable, daemon, hash, restart, and tray verification.
+
 ## Runtime Key Minting
 
 Requires admin scope:

package/docs/rest/endpoints/chat.md

@@ -12,8 +12,14 @@
 | `POST` | `/v1/chat` | Stateful Omnius chat with optional full agent tools |
 | `POST` | `/v1/generate` | Ollama-compatible one-shot generation |
 | `POST` | `/api/generate` | Ollama-compatible alias |
-| `GET` | `/v1/chat/sessions` | List active chat sessions |
+| `GET` | `/v1/chat/sessions` | List persisted browser chats plus quality-filtered 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 and cache a clean title/summary |
+| `GET` | `/v1/chat/sessions/{id}/status` | Read live state and unseen deltas since a sequence number |
+| `POST` | `/v1/chat/suggest-followup` | Suggest one short next message |
 | `POST` | `/v1/chat/check-in` | Send a steering check-in to the active chat session |
+| `POST` | `/v1/chat/attachments` | Upload an attachment for a stateful chat |
 
 ## `/v1/models`
 
@@ -73,6 +79,23 @@ Body fields:
 | `realtime` | boolean | Short ASR/TTS conversation mode |
 | `realtime_options` | object | Realtime settings |
 
+## Session History And Recovery
+
+`GET /v1/chat/sessions` is a workspace history index, not merely an active-run
+list. `?root=/absolute/workspace` selects the project and `?include_tui=0`
+excludes TUI history. The default result combines canonical browser chats with
+TUI sessions that pass quality checks. Exit-only commands such as `/quit` and
+`/exit`, manual-save placeholders, empty/noise-only histories, and duplicate
+normalized transcripts are not emitted as chats.
+
+Open a row with `GET /v1/chat/sessions/{id}`. The response contains all public
+messages, the imported TUI transcript when applicable, identity/source/project
+metadata, token counts, timestamps, and an in-flight job snapshot with a bounded
+partial-output tail. Poll `GET /v1/chat/sessions/{id}/status?since=<seq>` while a
+run is active to catch up without rerunning it. `DELETE` is admin-scoped and
+removes canonical daemon history; hiding a row in browser-local organization is
+not a server deletion.
+
 ## `/v1/generate` And `/api/generate`
 
 These endpoints provide one-shot Ollama-compatible generation. They are useful for clients that speak Ollama's generate shape rather than OpenAI chat messages. The route has no session history and can still use Omnius' backend routing layer.

package/docs/rest/endpoints/config.md

@@ -27,7 +27,10 @@
 | `POST` | `/v1/projects/switch` | Switch active project |
 | `POST` | `/v1/projects/register` | Register project root |
 | `POST` | `/v1/projects/rename` | Rename project |
-| `GET`/`PUT` | `/v1/projects/preferences` | Read or patch project preferences |
+| `GET` | `/v1/projects/scan` | Scan configured roots for project workspaces |
+| `GET`/`PUT`/`DELETE` | `/v1/projects/preferences` | Read, patch, or reset project preferences |
+| `GET` | `/v1/admin/access` | Read daemon network access mode |
+| `POST` | `/v1/admin/access` | Persist a new access mode from loopback only |
 
 ## Endpoint Switching
 
@@ -54,3 +57,7 @@ Profiles constrain tools and runtime behavior for a key or request path. Use the
 ## Projects
 
 The daemon is process-wide, but project endpoints track the active workspace and per-project preferences such as selected model, chat session, and UI choices.
+
+The dashboard brand picker uses `/v1/projects` and `/v1/projects/switch`.
+`/v1/projects/scan` discovers candidate roots without activating them. Access
+mode mutation is loopback-only even if the daemon currently permits any address.

package/docs/rest/endpoints/discovery.md

@@ -5,19 +5,24 @@ and used by `omnius discover` / `omnius show`.
 
 | Method | Path | Purpose |
 | --- | --- | --- |
+| `GET` | `/v1/discovery/bootstrap` | Compact agent strategy, profiles, intents, safety rules, and expanded start-here entries |
 | `GET` | `/v1/discovery` | Search or list catalog entries |
 | `GET` | `/v1/discovery/{id}` | Expand one stable entry |
 
 ## Search
 
 ```bash
-curl -s "http://127.0.0.1:11435/v1/discovery?q=web%20search&kind=tool&limit=5"
+curl -s http://127.0.0.1:11435/v1/discovery/bootstrap
+curl -s "http://127.0.0.1:11435/v1/discovery?q=web%20search&kind=workflow&audience=integrator&limit=5"
 ```
 
 Query fields:
 
 - `q`: free-text intent; omit to list entries.
 - `kind`: one supported catalog kind.
+- `audience`: require an exact audience tag.
+- `layer`: require an exact architecture layer.
+- `include_internal`: `true`/`1` to include internal notes hidden by default.
 - `limit`: page size.
 - `offset`: zero-based page offset.
 
@@ -31,14 +36,27 @@ curl -s http://127.0.0.1:11435/v1/discovery/tool.web-search
 ```
 
 An entry contains its stable ID, kind, title, summary, aliases/keywords,
-invocation interfaces, typed references, and related entries. Discovery is
-read-scoped and does not execute the selected capability.
+audiences/layer, use and avoid conditions, inputs/outputs, invocation
+interfaces, workflow steps, verification, failure recovery, source-of-truth,
+typed references, and related entries as applicable. Discovery is static,
+read-scoped, cacheable, and does not probe hardware, install dependencies,
+load models, or execute the selected capability.
 
 Important entrypoints:
 
+- `overview`
+- `workflow.choose-entrypoint`
+- `workflow.async-agent-run`
+- `workflow.debug-runtime`
+- `layer.orchestration`
+- `store.project`
 - `capability.bring-your-own-inference`
 - `provider.anthropic`
 - `provider.gemini`
 - `tool.web-search`
 - `api.tools`
 - `operation.version-compatibility`
+
+Static discovery describes declared behavior. For observed state, use the live
+service endpoints named by an entry, such as `/version`, `/health/ready`,
+`/v1/tools`, `/v1/asr/status`, or `/v1/voice/state`.

package/docs/rest/endpoints/files.md

@@ -5,7 +5,9 @@
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `GET` | `/v1/files` | List a workspace directory |
-| `GET` | `/v1/files/read` | Read a workspace file |
+| `POST` | `/v1/files/read` | Read a workspace file as structured text |
+| `GET` | `/v1/files/raw` | Stream raw bytes with content type and range support |
+| `HEAD` | `/v1/files/raw` | Inspect raw-file response metadata |
 
 ## Directory Listing
 
@@ -13,6 +15,9 @@
 
 ## File Read
 
-`GET /v1/files/read?path=<path>` reads file content where policy permits.
+`POST /v1/files/read` accepts a JSON body with `path` plus optional `offset`,
+`limit`, and `allow_outside_cwd`. `GET /v1/files/raw?path=<path>` is intended for
+browser previews and media/file downloads; HEAD has the same path resolution
+without returning the body.
 
 File operations are subject to workspace, auth, and profile restrictions. Remote clients should not assume arbitrary filesystem access.

package/docs/rest/endpoints/memory.md

@@ -9,6 +9,10 @@
 | `POST` | `/v1/memory/write` | Write memory |
 | `GET` | `/v1/memory/episodes` | List episodes |
 | `GET` | `/v1/memory/failures` | List captured failures |
+| `POST` | `/v1/memory/ingest` | Ingest content or files |
+| `GET` | `/v1/memory/entities` | List extracted entities |
+| `POST` | `/v1/memory/jobs/run` | Run a named maintenance job |
+| `POST` | `/v1/memory/feedback` | Record memory relevance/quality feedback |
 | `GET` | `/v1/sessions` | List Omnius task sessions |
 | `GET` | `/v1/sessions/{id}` | Get session history |
 | `GET` | `/v1/context` | Show current session context |

package/docs/rest/endpoints/run.md

@@ -7,18 +7,25 @@
 | `POST` | `/v1/run` | Submit an 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 a run |
 | `GET` | `/v1/todos` | List sessions with todo lists |
 | `GET` | `/v1/todos/{session_id}` | Get todos for a session |
-| `POST` | `/v1/todos/{session_id}` | Replace or update todos for a session |
+| `POST` | `/v1/todos` | Replace or update todos for a session |
+| `DELETE` | `/v1/todos/{session_id}` | Delete todos for a session |
 | `POST` | `/v1/evaluate` | Evaluate a run by ID |
 | `POST` | `/v1/index` | Trigger repository indexing |
 | `GET` | `/v1/scheduled` | List scheduled jobs |
-| `GET` | `/v1/scheduled/all` | List all scheduled jobs |
+| `DELETE` | `/v1/scheduled/all` | Remove all scheduled tasks, timers, cron entries, and sources |
 | `GET` | `/v1/scheduled/status` | Scheduled runner status |
+| `POST` | `/v1/scheduled/{id}` | Enable or disable one task/timer |
+| `DELETE` | `/v1/scheduled/{id}` | Delete one task/timer |
 | `POST` | `/v1/scheduled/kill` | Kill a scheduled job |
 | `POST` | `/v1/scheduled/fixup` | Reconcile scheduled job state |
-| `POST` | `/v1/scheduled/reconcile` | Force reconciliation |
+| `GET`/`POST` | `/v1/scheduled/reconcile` | Preview or apply reconciliation |
+| `GET` | `/v1/services/systemd` | List user-level services |
+| `POST` | `/v1/services/systemd/{unit}` | Act on one user-level unit |
+| `GET`/`POST` | `/v1/update` | Inspect or start a verified exact-version global update |
 
 ## `/v1/run`
 
@@ -65,4 +72,10 @@ Todo endpoints expose the same checklist state the TUI and agent loop use. They
 
 ## Scheduled Jobs
 
-Scheduled endpoints report and repair the long-running scheduler state. Use admin-scoped controls for kill or reconciliation operations.
+Scheduled endpoints report and repair the long-running scheduler state. Concrete
+actions (`kill`, `fixup`, and `reconcile`) are matched before the generic
+`/{id}` enable/disable route. Use admin-scoped controls for destructive actions.
+
+`POST /v1/update` starts the same durable install/verify/restart transaction used
+by the TUI, dashboard, and tray. Poll the GET form for live output and exact
+package, executable, daemon, hash, and tray verification.

package/docs/rest/endpoints/voice-vision.md

@@ -7,14 +7,19 @@
 | `GET` | `/v1/voice/state` | Voice runtime status |
 | `GET` | `/v1/voice/models` | List TTS voice models |
 | `POST` | `/v1/voice/models/switch` | Switch active TTS model |
-| `GET`/`PUT` | `/v1/voice/supertonic-settings` | Voice tuning settings |
-| `GET` | `/v1/voice/asr-models` | List Whisper ASR models |
-| `POST` | `/v1/voice/asr-models/switch` | Switch active ASR model |
+| `GET`/`POST` | `/v1/voice/supertonic-settings` | Read or update voice tuning settings |
+| `GET` | `/v1/asr/engines` | List ASR systems, models, capabilities, and readiness |
+| `GET` | `/v1/asr/status` · `/v1/asr/selection` | Read selection and runtime status |
+| `PATCH` | `/v1/asr/selection` | Persist and activate an exact ASR engine/model |
+| `POST` | `/v1/asr/activate` | Activate and persist an exact ASR engine/model |
+| `POST` | `/v1/asr/engines/{engineId}/setup` | Install a managed ASR runtime and pinned weights |
+| `POST` | `/v1/asr/transcriptions` · `/v1/asr/test` | Transcribe/test with the selected backend |
+| `GET`/`POST` | `/v1/voice/asr-models` · `/v1/voice/asr-models/switch` | Compatibility registry/activation aliases |
 | `POST` | `/v1/voice/tts` | Synthesize text |
 | `POST` | `/v1/audio/speech` | OpenAI-compatible TTS alias |
 | `POST` | `/v1/voice/transcribe` | Transcribe audio |
 | `POST` | `/v1/audio/transcriptions` | OpenAI-compatible transcription alias |
-| `POST` | `/v1/voice/transcribe/stream` | Streaming transcription |
+| `POST` | `/v1/voice/transcribe/stream` | Isolated final transcription over SSE |
 | `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 server-side |
@@ -37,12 +42,24 @@ POST /v1/audio/speech
 
 ## ASR
 
-`POST /v1/voice/transcribe` transcribes uploaded audio. The OpenAI-compatible alias is:
+`POST /v1/asr/transcriptions` transcribes uploaded audio with the selected
+engine. `/v1/asr/test` runs the same real path for readiness checks. The
+OpenAI-compatible alias is:
 
 ```text
 POST /v1/audio/transcriptions
 ```
 
+VibeVoice is exposed as `vibevoice-transformers/vibevoice-asr-7b`. It is a
+completed-file backend, not an incremental PCM stream: the response preserves
+speaker IDs, segment timestamps, raw structured text, and warnings. Pass
+`?context=` for customized hotwords/background context. Setup installs the
+exact pinned `microsoft/VibeVoice-ASR` snapshot into the unified ASR cache;
+activation requires an explicit GPU and verified placement, and never falls
+back to CPU or another device. Discrete Linux uses `nvidia-smi`; Jetson/L4T,
+where NVIDIA does not ship `nvidia-smi`, uses `tegrastats` plus CUDA Torch
+device properties.
+
 ## Voicechat WebSocket
 
 `/v1/voicechat/ws` supports full-duplex realtime voice.

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "omnius",
-  "version": "1.0.608",
+  "version": "1.0.610",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omnius",
-      "version": "1.0.608",
+      "version": "1.0.610",
       "bundleDependencies": [
         "image-to-ascii"
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omnius",
-  "version": "1.0.608",
+  "version": "1.0.610",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/library.js",
@@ -33,7 +33,10 @@
     "templates",
     "prompts",
     "vendor",
-    "voices",
+    "voices/personaplex/OverBarn.pt",
+    "voices/personaplex/clone-voice.py",
+    "voices/personaplex/dequant-loader.py",
+    "voices/personaplex/quantize-weights.py",
     "npm-shrinkwrap.json",
     "README.md",
     "LICENSE"
@@ -161,5 +164,5 @@
     "transcribe-cli": "^2.0.1",
     "viem": "2.47.4"
   },
-  "readme": "# Omnius\n\nOmnius is a local-first agentic coding runtime: terminal UI, autonomous coding loop, REST daemon, model router, memory layer, media tools, Telegram bridge, and peer-to-peer inference mesh in one CLI.\n\nIt is designed for open-weight and user-controlled models first, while still routing cleanly through Ollama, vLLM, OpenAI-compatible endpoints, OpenRouter, Groq, Chutes, sponsor peers, COHERE peers, and other configured providers.\n\n[![npm](https://img.shields.io/npm/v/omnius.svg)](https://www.npmjs.com/package/omnius)\n[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/license-CC--BY--NC--4.0-blue.svg)](LICENSE)\n\n## Install\n\n```bash\nnpm install -g omnius\nomnius\n```\n\nRequirements:\n\n- Node.js 22 or newer\n- npm 10 or newer for published CLI use\n- pnpm 9 or newer for workspace development\n- A local model or configured remote endpoint\n\nStart the REST daemon:\n\n```bash\nomnius serve\n```\n\nThe daemon defaults to `http://127.0.0.1:11435`. Open the interactive API docs at `http://127.0.0.1:11435/docs`.\n\nRegister the native system tray indicator (Linux, macOS, and Windows x64):\n\n```bash\nomnius tray install\nomnius tray status\n```\n\nThe per-login indicator observes the daemon over loopback and provides health,\ndashboard, logs, and explicit daemon controls. See the\n[system tray guide](docs/guides/system-tray.md), including Ubuntu/GNOME setup.\n\n## Agent Discovery\n\nThe npm package ships its complete documentation and a machine-readable\ncapability catalog. An agent does not need to inspect Omnius source or guess\nwhich endpoint owns a capability:\n\n```bash\nomnius discover \"bring your own inference\"\nomnius show provider.anthropic\nomnius show provider.gemini\nomnius show tool.web-search\nomnius discover \"osint research\"\nomnius show capability.osint-research\nomnius capabilities --json\n```\n\nWith the daemon running, the same discovery cascade is available at\n`GET /v1/discovery`, with exact entry expansion at\n`GET /v1/discovery/{id}`. The live API contract remains available at\n`/openapi.json`, direct tool metadata at `/v1/tools`, and skills at\n`/v1/skills`.\n\nStart with [the discovery guide](docs/DISCOVERY.md) when integrating another\nagent or service. Use [bring-your-own inference](docs/guides/bring-your-own-inference.md)\nfor provider protocols and keys, and [tools and web search](docs/guides/tools-and-web-search.md)\nfor the distinction between direct tools and agent-bound tools. The\n[categorized OSINT research guide](docs/guides/osint-research.md) documents\nthe local discover → exact expansion → explicit web-tool workflow.\n\n## What Omnius Does\n\n- Runs autonomous coding tasks, edits files, executes tools, tests changes, and iterates on failures.\n- Provides a dense terminal UI for model selection, endpoint routing, task control, shell output, voice, sponsors, Telegram, and system telemetry.\n- Exposes a REST daemon with OpenAI/Ollama-compatible inference, agentic task execution, memory, skills, tools, MCP, events, voice, projects, and governance endpoints.\n- Routes models through local, cloud, sponsor, and peer-to-peer endpoints without assuming local Ollama is the only source.\n- Supports realtime spoken conversation for ASR/TTS clients through `/realtime` and REST `realtime: true`.\n- Supports image, video, sound, music, TTS, ASR, voice clone references, Telegram media workflows, and sponsor-provided media generation.\n- Keeps project runtime state in `.omnius/`, which is intentionally ignored by git.\n\n## Common Workflows\n\n```bash\nomnius \"inspect this repo and summarize the main entrypoints\"\nomnius serve\n```\n\n```text\n/help                 command help\n/model                select or inspect the active model\n/endpoint             select or configure local, cloud, sponsor, or peer endpoints\n/realtime             toggle short ASR/TTS-oriented conversation mode\n/broker               inspect model broker, RAM/VRAM thresholds, and loaded models\n/sponsor              expose local or upstream capacity to peers\n/cohere               participate in distributed COHERE inference\n/telegram             configure or toggle the Telegram bridge\n/skills               list explorable skills and docs memories\n/pause                pause after the current turn boundary\n/stop                 interrupt the active run\n/resume               resume saved state\n```\n\n## Current Feature Areas\n\n| Area | What to read |\n| --- | --- |\n| Install and setup | [Install](docs/getting-started/install.md), [First run](docs/getting-started/first-run.md), [Model providers](docs/getting-started/model-providers.md) |\n| Agent discovery | [Discovery cascade](docs/DISCOVERY.md), [machine catalog](docs/DISCOVERY.json), [agent integration](docs/guides/agent-integration.md) |\n| Bring your own inference | [Provider protocols and keys](docs/guides/bring-your-own-inference.md) |\n| Tools and web search | [Tool discovery and invocation](docs/guides/tools-and-web-search.md) |\n| Terminal workflows | [TUI workflows](docs/guides/tui-workflows.md), [Slash commands](docs/reference/slash-commands.md) |\n| REST daemon | [REST reference](docs/reference/rest-api.md), [REST quickref](docs/rest/QUICKREF.md), [OpenAPI source](docs/rest/openapi-source.md) |\n| System tray | [Cross-platform tray and Ubuntu setup](docs/guides/system-tray.md) |\n| Realtime voice chat | [Realtime guide](docs/guides/realtime.md) |\n| Sponsor and COHERE mesh | [Sponsor and COHERE guide](docs/guides/sponsor-and-cohere.md) |\n| Telegram bridge | [Telegram guide](docs/guides/telegram.md) |\n| Media generation | [Media guide](docs/guides/media-generation.md) |\n| Operations | [Runtime hygiene](docs/operations/runtime-hygiene.md), [Security and remote access](docs/operations/security-and-remote-access.md) |\n| Service compatibility | [Runtime version gate](docs/operations/version-compatibility.md) |\n| Architecture | [Architecture overview](docs/architecture/overview.md) |\n| Agent-explorable docs | [Agent memory docs index](docs/agent-memory/INDEX.md) |\n\n## Shared Media Dependencies\n\nImage, video, audio, and music generation share a **single, system-wide dependency store** instead of duplicating heavy runtimes per project or per Telegram group.\n\nEarlier builds wrote a private Python venv plus Hugging Face / Torch / pip caches under every scoped working directory (for example `…/telegram-creative/<group-id>/.omnius/image-gen/.venv`). On a busy machine the same multi-gigabyte diffusers stack and model weights were re-downloaded once per group — tens of gigabytes of pure duplication.\n\nEverything now resolves to one source of truth under `~/.omnius` (override with `OMNIUS_HOME`):\n\n| Location | Holds |\n| --- | --- |\n| `~/.omnius/runtimes/<kind>/.venv-<backend>` | One shared Python venv per kind+backend (image/video/audio) |\n| `~/.omnius/models/huggingface/{hub,transformers,diffusers}` | Shared model weights — downloaded once, reused everywhere |\n| `~/.omnius/models/{torch,cache,pip-cache}` | Shared Torch hub, XDG, and pip caches |\n| `~/.omnius/models/_meta.json` | LRU usage index for automatic disk-pressure eviction |\n| `~/.omnius/media/{images,videos,audio,music}` | Global generated-media gallery (project-independent) |\n\nProject directories keep only lightweight session artifacts; no venvs or model weights are written per project.\n\n**Migrate and dedup existing machines.** A one-time cleanup consolidates any legacy per-group caches into the unified store — unique weights are moved (never re-downloaded), duplicates and stale venvs are reclaimed:\n\n```bash\n# TUI — current project only\n/models cleanup\n# TUI — every project + nested scoped group on this machine (dry-run first)\n/models cleanup --all --dry-run\n/models cleanup --all\n```\n\n```bash\n# REST — preview, then apply\ncurl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{\"dryRun\":true}'\ncurl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{}'\n# Inspect store + reclaimable legacy caches\ncurl -s localhost:11435/v1/media/store\n```\n\n**Generate over REST.** The daemon (default `127.0.0.1:11435`, a port in the IANA dynamic/private range that avoids common system-service collisions) exposes the local generators so any user on the machine can list models, generate, and browse the global gallery without the CLI:\n\n```bash\ncurl -s localhost:11435/v1/media/models\ncurl -s -X POST localhost:11435/v1/media/image -H 'content-type: application/json' -d '{\"prompt\":\"a compact robot painter\"}'\ncurl -s -X POST localhost:11435/v1/media/music -H 'content-type: application/json' -d '{\"prompt\":\"warm lo-fi piano loop\"}'\ncurl -s localhost:11435/v1/media/gallery\n```\n\nThe same surface drives the **Generate** tab in the web UI (`http://127.0.0.1:11435`) — pick a kind (image/video/audio/music), choose a model loaded from the system, generate, and review every previously generated file in one global gallery.\n\n## Recent Highlights\n\n- `/realtime` and REST `realtime: true` provide short, natural, SOUL.md-aware conversation for ASR/TTS clients.\n- Endpoint setup and sponsor setup aggregate models from all enabled endpoints, including external OpenAI-compatible routers.\n- `/sponsor` can expose text inference and media generation for image, video, sound, and music with per-modality limits.\n- Sponsor and COHERE status surfaces now use shared telemetry concepts: concurrency, request rate, daily tokens, peer usage, model usage, and remote system metrics.\n- The TUI reports token production rate as `t/s`, supports Shift+Enter multiline input, and renders dynamic shell output inside bounded Unicode cards.\n- Telegram state is scoped by user and group, supports durable reply preferences, and feeds raw platform/tool failures back into the agent loop.\n- Ollama pool cleanup now accounts for process groups and orphan runner processes that can keep VRAM pinned.\n- REST documentation is available both as human docs and as Omnius-discoverable docs skills.\n\n## REST API\n\nStart the daemon (default `http://127.0.0.1:11435`; interactive docs at `/docs`, machine spec at `/openapi.json`):\n\n```bash\nomnius serve\n```\n\nFor shared deployments, gate access with scoped bearer keys (`read` < `run` < `admin`):\n\n```bash\nOMNIUS_REST_API_KEYS=\"read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops\" omnius serve\n# then: Authorization: Bearer <key>\n```\n\nThe 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).\n\n### Docs and compatibility aliases\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/docs` · `/api/docs` · `/swagger-ui` | Swagger UI |\n| `GET` | `/openapi.json` · `/openapi.yaml` · `/v3/api-docs` · `/swagger.json` · `/api-docs` | OpenAPI spec (JSON/YAML + aliases) |\n| `GET` | `/redoc` | ReDoc renderer |\n\n### Health and observability\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/health` · `/health/ready` · `/health/startup` | Liveness, backend readiness, startup probes |\n| `GET` | `/version` | Package version and platform |\n| `GET` | `/metrics` | Prometheus metrics |\n| `GET` | `/v1/events` | Server-sent event stream |\n| `GET` | `/v1/usage` | Token usage and rate limits |\n| `GET` | `/v1/audit` | Audit log query |\n| `GET` | `/v1/cost` | Cost tracker |\n| `GET` | `/v1/system` | CPU, RAM, GPU, and system snapshot |\n\n### Discovery\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/discovery` | Search or list the bundled capability catalog |\n| `GET` | `/v1/discovery/{id}` | Expand one stable capability entry |\n\n### Inference and chat\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/models` · `/api/tags` | Aggregated model list (OpenAI + Ollama tags) |\n| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completion |\n| `POST` | `/v1/chat` | Stateful Omnius chat |\n| `POST` | `/api/chat` | Ollama-compatible chat alias |\n| `POST` | `/v1/generate` · `/api/generate` | One-shot generation (Ollama-compatible) |\n| `POST` | `/v1/embeddings` · `/api/embed` | Embeddings (OpenAI + Ollama aliases) |\n| `GET` | `/v1/chat/sessions` | Active chat sessions |\n| `POST` | `/v1/chat/check-in` | Steering check-in for active chat |\n\n### Agentic runs\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `POST` | `/v1/run` | Submit agentic task |\n| `GET` | `/v1/runs` · `/v1/runs/{id}` | List runs · get run details |\n| `DELETE` | `/v1/runs/{id}` | Abort run |\n| `POST`/`GET` | `/v1/todos` | Create/update · list sessions with todos |\n| `GET`/`DELETE` | `/v1/todos/{session_id}` | Get · delete session todos |\n| `POST` | `/v1/evaluate` | Evaluate a run |\n| `POST` | `/v1/index` | Trigger repository indexing |\n\n### Configuration, keys, profiles, projects\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET`/`PATCH` | `/v1/config` | Read · update daemon config |\n| `GET`/`PUT` | `/v1/config/model` | Current model · switch model |\n| `POST` | `/v1/config/model/check` | Probe model readiness |\n| `GET`/`PUT` | `/v1/config/endpoint` | Current endpoint · switch endpoint |\n| `POST` | `/v1/config/endpoint/test` | Probe endpoint |\n| `GET`/`DELETE` | `/v1/config/endpoint/history` | Endpoint history · remove item |\n| `POST` | `/v1/share/generate` | Generate remote-access share URL |\n| `GET`/`POST` | `/v1/keys` | List · mint runtime API keys |\n| `DELETE` | `/v1/keys/{prefix}` | Revoke runtime keys by prefix |\n| `GET`/`POST` | `/v1/profiles` | List · create tool profiles |\n| `GET`/`DELETE` | `/v1/profiles/{name}` | Get · delete profile |\n| `GET`/`DELETE` | `/v1/projects` | List · unregister projects |\n| `GET` | `/v1/projects/current` | Current project |\n| `POST` | `/v1/projects/switch` · `/v1/projects/register` · `/v1/projects/rename` | Switch · register · rename project |\n| `GET`/`PUT`/`DELETE` | `/v1/projects/preferences` | Read · patch · reset project preferences |\n\n### Skills, commands, tools, MCP\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/skills` · `/v1/skills/{name}` | List · load skill content |\n| `GET` | `/v1/commands` | List slash commands |\n| `POST` | `/v1/commands/{cmd}` | Execute slash command |\n| `GET` | `/v1/tools` · `/v1/tools/{name}` | List (built-in + external) · tool metadata |\n| `POST` | `/v1/tools/register` | Register an application-specific external tool |\n| `DELETE` | `/v1/tools/{name}` | Unregister an external tool |\n| `POST` | `/v1/tools/{name}/call` | Call tool |\n| `POST` | `/v1/tools/{name}/eval` | Evaluate an external tool against test cases |\n| `GET` | `/v1/mcps` · `/v1/mcps/{name}` | List · MCP server details |\n| `POST` | `/v1/mcps/{name}/call` | Call MCP tool |\n| `GET` | `/v1/hooks` · `/v1/agents` | Hook registry · agent type registry |\n| `GET` | `/v1/codegraph/snapshot` · `/v1/codegraph/events` | Code graph snapshot · SSE |\n\n### Registering application-specific tools\n\nAgents 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:\n\n- **`http`** — Omnius POSTs `{name, args, session_id}` to a `callback_url` your app hosts and relays the response.\n- **`mcp`** — the tool proxies to a named tool on an MCP server (auto-connected when you pass `connect`).\n\nRegistered 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`).\n\n```bash\n# Register an HTTP-backed tool\ncurl -s -X POST localhost:11435/v1/tools/register -H 'content-type: application/json' -d '{\n  \"name\": \"lookup_order\",\n  \"description\": \"Look up an order by id in the billing system\",\n  \"parameters\": {\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"}},\"required\":[\"id\"]},\n  \"security\": {\"requires_scope\":\"run\",\"risk\":\"low\"},\n  \"transport\": {\"type\":\"http\",\"callback_url\":\"https://app.internal/tools/lookup_order\",\"auth_header\":\"Bearer …\"}\n}'\n\n# It now appears in the registry and is directly callable\ncurl -s localhost:11435/v1/tools/lookup_order\ncurl -s -X POST localhost:11435/v1/tools/lookup_order/call -H 'content-type: application/json' -d '{\"args\":{\"id\":\"A-1001\"}}'\n\n# Evaluate it against cases during development (pass/fail + metrics)\ncurl -s -X POST localhost:11435/v1/tools/lookup_order/eval -H 'content-type: application/json' -d '{\n  \"cases\": [\n    {\"name\":\"known order\",\"args\":{\"id\":\"A-1001\"},\"expect\":{\"success\":true,\"output_contains\":\"A-1001\"}},\n    {\"name\":\"missing order\",\"args\":{\"id\":\"nope\"},\"expect\":{\"success\":false}}\n  ]\n}'\n\n# Unregister when done\ncurl -s -X DELETE localhost:11435/v1/tools/lookup_order\n```\n\nThe same registration accepts an MCP transport, e.g. `\"transport\":{\"type\":\"mcp\",\"server\":\"acme\",\"tool\":\"search\",\"connect\":{\"url\":\"https://app.internal/mcp\",\"transport\":\"streamable-http\"}}`.\n\n### AIWG\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/aiwg` | AIWG root and control map |\n| `GET` | `/v1/aiwg/frameworks` · `/v1/aiwg/frameworks/{name}` · `/v1/aiwg/frameworks/{name}/content` | List · details · tier-aware content |\n| `GET` | `/v1/aiwg/skills` · `/v1/aiwg/skills/{name}` | List · load AIWG skill |\n| `GET` | `/v1/aiwg/agents` · `/v1/aiwg/agents/{name}` | List · load AIWG agent |\n| `GET` | `/v1/aiwg/addons` | List AIWG addons |\n| `POST` | `/v1/aiwg/use` · `/v1/aiwg/expand` | Activation bundle · expand item |\n\n### Memory, sessions, context\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/memory` | Memory backend summary |\n| `POST` | `/v1/memory/search` · `/v1/memory/write` | Search · write memory |\n| `GET` | `/v1/memory/episodes` · `/v1/memory/failures` | List episodes · failures |\n| `GET` | `/v1/sessions` · `/v1/sessions/{id}` | List task sessions · get history |\n| `GET` | `/v1/context` | Current context snapshot |\n| `GET` | `/v1/context/window-dumps` · `/v1/context/window-dumps/{id}` | List/fetch full outbound model context-window dumps |\n| `POST` | `/v1/context/save` · `/v1/context/compact` | Save entry · request compaction |\n| `GET` | `/v1/context/restore` | Build restore prompt |\n\nContext-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.\n\n### Files, nexus, ollama pool\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/files` | List workspace directory |\n| `POST` | `/v1/files/read` | Read workspace file |\n| `GET` | `/v1/nexus/status` | Nexus peer state |\n| `GET` | `/v1/sponsors` | Sponsor directory cache |\n| `GET` | `/v1/ollama/pool/processes` | Ollama process inventory |\n| `POST` | `/v1/ollama/pool/cleanup` | Cleanup stale Ollama pool processes |\n\n### Voice, audio, vision\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/voice/state` | Voice runtime status |\n| `POST` | `/v1/voice/start` · `/v1/voice/stop` | Enable/warm voice · pause voice input |\n| `GET`/`POST` | `/v1/voice/models` · `/v1/voice/models/switch` | List · switch and enable an exact TTS model |\n| `GET`/`POST` | `/v1/voice/supertonic-settings` | Read · update voice tuning |\n| `GET`/`POST` | `/v1/voice/asr-models` · `/v1/voice/asr-models/switch` | List · switch ASR model |\n| `POST` | `/v1/voice/tts` · `/v1/audio/speech` | Synthesize speech (+ OpenAI alias) |\n| `POST` | `/v1/voice/transcribe` · `/v1/audio/transcriptions` · `/v1/voice/transcribe/stream` | Transcribe (+ alias + streaming) |\n| `GET`/`POST` | `/v1/voice/clone-refs` | List · upload clone reference |\n| `POST` | `/v1/voice/clone-refs/upload` · `/v1/voice/clone-refs/from-url` | Upload · fetch clone reference |\n| `POST` | `/v1/voice/clone-refs/{filename}/activate` · `/v1/voice/clone-refs/{filename}/rename` | Activate · rename clone reference |\n| `DELETE` | `/v1/voice/clone-refs/{filename}` | Delete clone reference |\n| `POST` | `/v1/voice/speak` | Broadcast speech to voicechat clients |\n| `GET` | `/v1/voicechat/ws` | WebSocket upgrade for full-duplex voicechat |\n| `POST` | `/v1/vision/describe` | Vision describe placeholder |\n\nTTS requests auto-warm the daemon and never silently fall back to a different\nvoice. The built-in registry includes GLaDOS, Overwatch, and the packaged\n`luxtts:announcer-testchamber03` clone source. Voicebox defaults to its stable\nsub-model set; use `OMNIUS_VOICEBOX_MODELS=all` for the full suite or a\ncomma-separated list of `voicebox_*` IDs for an explicit subset.\n\n### Generative media\n\nBacked 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}`.\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/media/models` | List available image/video/audio/music models |\n| `GET` | `/v1/media/store` | Unified store disk usage + reclaimable legacy caches |\n| `POST` | `/v1/media/migrate` | Dedup + migrate legacy per-group caches into the unified store |\n| `POST` | `/v1/media/image` · `/v1/media/video` · `/v1/media/audio` · `/v1/media/music` | Generate media (run scope) |\n| `GET` | `/v1/media/gallery` | List previously generated media (global, newest first) |\n| `GET` | `/v1/media/file` | Stream one generated media file |\n\n### Engines and scheduled jobs\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/engines` | Long-running engine status |\n| `GET` | `/v1/scheduled` · `/v1/scheduled/all` · `/v1/scheduled/status` | List · list all · scheduler status |\n| `POST` | `/v1/scheduled/kill` · `/v1/scheduled/fixup` · `/v1/scheduled/reconcile` | Kill · reconcile · force reconcile |\n| `GET` | `/v1/services/systemd` | Systemd service status |\n| `GET` | `/v1/update` | Self-update status |\n\n### AIMS governance (ISO/IEC 42001:2023)\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/aims` | AIMS root and endpoint index |\n| `GET`/`PUT` | `/v1/aims/policies` | Policy register · replace |\n| `GET` | `/v1/aims/roles` · `/v1/aims/resources` | Roles · resource inventory |\n| `GET`/`POST` | `/v1/aims/impact-assessments` | List · file impact assessment |\n| `GET` | `/v1/aims/lifecycle` · `/v1/aims/data-quality` · `/v1/aims/transparency` · `/v1/aims/usage` · `/v1/aims/suppliers` | Lifecycle, data quality, transparency, usage, suppliers |\n| `GET`/`POST` | `/v1/aims/incidents` | List · file incident |\n| `GET` | `/v1/aims/oversight` · `/v1/aims/decisions` · `/v1/aims/config-history` | Oversight gates · decision log · config history |\n\nFor 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).\n\n## Agent-Explorable Documentation\n\nOmnius discovers project-local docs skills from `.aiwg/addons/*/skills`. The docs bundles in this repo expose high-signal entrypoints for agents:\n\n```text\n/skills omnius docs\nskill_execute name=\"omnius-docs\"\nskill_execute name=\"omnius-rest-docs\"\nskill_extract name=\"omnius-realtime-docs\" query=\"How does realtime REST mode work?\"\n```\n\nThe intended pattern is index first, targeted document second, not loading the whole manual into the active context.\n\n## Development\n\n```bash\npnpm install\npnpm -r build\npnpm docs:check\n```\n\nFocused checks used for the docs skill surface:\n\n```bash\npnpm --filter @omnius/execution exec vitest run tests/skill-discovery.test.ts\npnpm --filter omnius exec vitest run tests/realtime-mode.test.ts tests/command-registry.test.ts\n```\n\n## Publishing\n\nPublish only from `publish/`.\n\n```bash\ncd omnius\npnpm -r clean || true\nfind . -name 'tsconfig.tsbuildinfo' -not -path '*/node_modules/*' -delete\npnpm -r build\nnode scripts/build-publish.mjs\ncd publish\nmkdir -p .npm-cache\nNPM_CONFIG_CACHE=$(pwd)/.npm-cache npm pack --prefer-online --cache-min=0 --registry https://registry.npmjs.org/\nNPM_CONFIG_CACHE=$(pwd)/.npm-cache npm publish --access public --prefer-online --cache-min=0 --registry https://registry.npmjs.org/\n```\n\nBefore publishing, verify `README.md`, `package.json`, `dist/index.js`, and `dist/launcher.cjs` are in the tarball, and that `package.json` includes `readmeFilename: \"README.md\"` plus a string `readme`.\n\n## License\n\nOmnius is released under [CC-BY-NC-4.0](LICENSE) for non-commercial use. Commercial use, redistribution, hosted services, and enterprise deployment require a commercial license.\n"
+  "readme": "# Omnius\n\nOmnius is a local-first agentic coding runtime: terminal UI, autonomous coding loop, REST daemon, model router, memory layer, media tools, Telegram bridge, and peer-to-peer inference mesh in one CLI.\n\nIt is designed for open-weight and user-controlled models first, while still routing cleanly through Ollama, vLLM, OpenAI-compatible endpoints, OpenRouter, Groq, Chutes, sponsor peers, COHERE peers, and other configured providers.\n\n[![npm](https://img.shields.io/npm/v/omnius.svg)](https://www.npmjs.com/package/omnius)\n[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/license-CC--BY--NC--4.0-blue.svg)](LICENSE)\n\n## Install\n\n```bash\nnpm install -g omnius\nomnius\n```\n\nRequirements:\n\n- Node.js 22 or newer\n- npm 10 or newer for published CLI use\n- pnpm 9 or newer for workspace development\n- A local model or configured remote endpoint\n\nStart the REST daemon:\n\n```bash\nomnius serve\n```\n\nThe daemon defaults to `http://127.0.0.1:11435`. Open the interactive API docs at `http://127.0.0.1:11435/docs`.\n\nRegister the native system tray indicator (Linux, macOS, and Windows x64):\n\n```bash\nomnius tray install\nomnius tray status\n```\n\nThe per-login indicator observes the daemon over loopback, checks health and npm\nupdates every 10 seconds, and provides dashboard, logs, and explicit daemon\ncontrols. Its version row is passive when current and becomes a verified global\nupdate action only when a newer exact semver is available. See the\n[system tray guide](docs/guides/system-tray.md), including Ubuntu/GNOME setup.\n\n## Agent Discovery\n\nThe npm package ships its complete documentation and a machine-readable\ncapability catalog. An agent does not need to inspect Omnius source or guess\nwhich endpoint owns a capability:\n\n```bash\nomnius discover \"bring your own inference\"\nomnius show workflow.choose-entrypoint\nomnius show layer.orchestration\nomnius show store.project\nomnius show provider.anthropic\nomnius show provider.gemini\nomnius show tool.web-search\nomnius discover \"osint research\"\nomnius show capability.osint-research\nomnius capabilities --json\n```\n\nWith the daemon running, begin at `GET /v1/discovery/bootstrap`. The same\ndiscovery cascade is available at `GET /v1/discovery`, with exact entry expansion at\n`GET /v1/discovery/{id}`. The live API contract remains available at\n`/openapi.json`, direct tool metadata at `/v1/tools`, and skills at\n`/v1/skills`.\n\nStart with [the discovery guide](docs/DISCOVERY.md) when integrating another\nagent or service, and use the [agent system map](docs/architecture/agent-system-map.md)\nto trace layers, modules, runtimes, and state ownership. Use [bring-your-own inference](docs/guides/bring-your-own-inference.md)\nfor provider protocols and keys, and [tools and web search](docs/guides/tools-and-web-search.md)\nfor the distinction between direct tools and agent-bound tools. The\n[categorized OSINT research guide](docs/guides/osint-research.md) documents\nthe local discover → exact expansion → explicit web-tool workflow.\n\n## What Omnius Does\n\n- Runs autonomous coding tasks, edits files, executes tools, tests changes, and iterates on failures.\n- Provides a dense terminal UI for model selection, endpoint routing, task control, shell output, voice, sponsors, Telegram, and system telemetry.\n- Exposes a REST daemon with OpenAI/Ollama-compatible inference, agentic task execution, memory, skills, tools, MCP, events, voice, projects, and governance endpoints.\n- Routes models through local, cloud, sponsor, and peer-to-peer endpoints without assuming local Ollama is the only source.\n- Supports realtime spoken conversation for ASR/TTS clients through `/realtime` and REST `realtime: true`.\n- Supports image, video, sound, music, TTS, ASR, voice clone references, Telegram media workflows, and sponsor-provided media generation.\n- Keeps project runtime state in `.omnius/`, which is intentionally ignored by git.\n\n## Common Workflows\n\n```bash\nomnius \"inspect this repo and summarize the main entrypoints\"\nomnius serve\n```\n\n```text\n/help                 command help\n/model                select or inspect the active model\n/endpoint             select or configure local, cloud, sponsor, or peer endpoints\n/title                name the current session\n/realtime             toggle short ASR/TTS-oriented conversation mode\n/voice                choose TTS, voice-clone, voicechat, and ASR controls\n/voice asr            select, set up, activate, or test an exact ASR engine/model\n/indicator            reconcile the daemon, then start the native tray indicator\n/update check         force an update availability check\n/update quick         run the verified global update with live TUI progress\n/update full          run the full clean/build/install/restart verification flow\n/broker               inspect model broker, RAM/VRAM thresholds, and loaded models\n/sponsor              expose local or upstream capacity to peers\n/cohere               participate in distributed COHERE inference\n/telegram             configure or toggle the Telegram bridge\n/skills               list explorable skills and docs memories\n/pause                pause after the current turn boundary\n/stop                 interrupt the active run\n/resume               resume saved state\n```\n\n## Current Feature Areas\n\n| Area | What to read |\n| --- | --- |\n| Install and setup | [Install](docs/getting-started/install.md), [First run](docs/getting-started/first-run.md), [Model providers](docs/getting-started/model-providers.md) |\n| Agent discovery | [Discovery cascade](docs/DISCOVERY.md), [machine catalog](docs/DISCOVERY.json), [agent integration](docs/guides/agent-integration.md) |\n| Bring your own inference | [Provider protocols and keys](docs/guides/bring-your-own-inference.md) |\n| Tools and web search | [Tool discovery and invocation](docs/guides/tools-and-web-search.md) |\n| Terminal workflows | [TUI workflows](docs/guides/tui-workflows.md), [Slash commands](docs/reference/slash-commands.md) |\n| Web dashboard | [All dashboard routes, workspaces, sessions, Voice, Generate, updates, and observability](docs/guides/dashboard.md) |\n| REST daemon | [REST reference](docs/reference/rest-api.md), [REST quickref](docs/rest/QUICKREF.md), [OpenAPI source](docs/rest/openapi-source.md) |\n| System tray | [Cross-platform tray and Ubuntu setup](docs/guides/system-tray.md) |\n| Realtime voice chat | [Realtime guide](docs/guides/realtime.md) |\n| TTS and selectable ASR | [Voice/vision REST guide](docs/rest/endpoints/voice-vision.md), [Dashboard Voice page](docs/guides/dashboard.md#voice-and-asr) |\n| Sponsor and COHERE mesh | [Sponsor and COHERE guide](docs/guides/sponsor-and-cohere.md) |\n| Telegram bridge | [Telegram guide](docs/guides/telegram.md) |\n| Media generation | [Media guide](docs/guides/media-generation.md) |\n| Operations | [Runtime hygiene](docs/operations/runtime-hygiene.md), [Security and remote access](docs/operations/security-and-remote-access.md) |\n| Service compatibility | [Runtime version gate](docs/operations/version-compatibility.md) |\n| Architecture | [Architecture overview](docs/architecture/overview.md) |\n| Agent-explorable docs | [Agent memory docs index](docs/agent-memory/INDEX.md) |\n\n## Web Dashboard\n\n`omnius serve` exposes a self-contained operational dashboard at\n`http://127.0.0.1:11435/`. All pages use the same compact NOCLIP-derived style\ntokens and responsive observability-card grid, while keeping workspace, model,\nsession, run, service, and update state visible instead of hiding it behind\ndecorative pages.\n\n| Route | Purpose |\n| --- | --- |\n| `/chat` (`/`) | Stateful browser and imported TUI chats, full-history hydration, live run recovery, attachments, files, plan/context, and steering check-ins |\n| `/agent` | One-shot task contracts, personas/profiles, tool/isolation controls, run records, output, and events |\n| `/voice` | Voicechat, exact TTS model/options, clone references, ASR engine/model setup and activation, real-file ASR testing, transcript, and TTS testing |\n| `/generate` | Image/video/audio/music jobs, AV analysis, model/store controls, relocation progress, and global gallery |\n| `/projects` | Scan, register, rename, activate, and remove workspaces |\n| `/dashboard` (`/jobs`) | CPU/RAM/GPU/VRAM, processes, scheduler, services, usage, and verified updates |\n| `/activity` | Live run/tool/memory/engine event observability |\n| `/discover` | Agent bootstrap, capability intent search, and exact entry expansion |\n| `/settings` (`/config`) | Models, endpoints, voice, runtime, access, keys, appearance, and services |\n\nThe clickable sidebar brand opens the registered-workspace picker. Workspace\nselection scopes preferences, files, session history, chat pins/folders/search,\nand agent defaults. Chats, TUI visual history, and one-shot agent runs are\ndistinct records: `/quit`, `/exit`, manual-save noise, empty histories, and\nduplicate TUI transcripts are rejected from the chat projection; selecting a\nvalid session loads its full history and in-flight status from the daemon.\n\nThe dashboard checks for updates every 10 seconds. An update button appears only\nfor a newer exact semver and drives `POST /v1/update`, then polls the durable\ntransaction until the global npm package, resolved executable, restarted daemon,\npackage/boot hashes, and tray runtime are reconciled. See the\n[complete dashboard guide](docs/guides/dashboard.md) for state ownership,\nsecurity, page-by-page behavior, and exact REST flows.\n\n## Shared Media Dependencies\n\nImage, video, audio, and music generation share a **single, system-wide dependency store** instead of duplicating heavy runtimes per project or per Telegram group.\n\nEarlier builds wrote a private Python venv plus Hugging Face / Torch / pip caches under every scoped working directory (for example `…/telegram-creative/<group-id>/.omnius/image-gen/.venv`). On a busy machine the same multi-gigabyte diffusers stack and model weights were re-downloaded once per group — tens of gigabytes of pure duplication.\n\nEverything now resolves to one source of truth under `~/.omnius` (override with `OMNIUS_HOME`):\n\n| Location | Holds |\n| --- | --- |\n| `~/.omnius/runtimes/<kind>/.venv-<backend>` | One shared Python venv per kind+backend (image/video/audio) |\n| `~/.omnius/models/huggingface/{hub,transformers,diffusers}` | Shared model weights — downloaded once, reused everywhere |\n| `~/.omnius/models/{torch,cache,pip-cache}` | Shared Torch hub, XDG, and pip caches |\n| `~/.omnius/models/_meta.json` | LRU usage index for automatic disk-pressure eviction |\n| `~/.omnius/media/{images,videos,audio,music}` | Global generated-media gallery (project-independent) |\n\nProject directories keep only lightweight session artifacts; no venvs or model weights are written per project.\n\n**Migrate and dedup existing machines.** A one-time cleanup consolidates any legacy per-group caches into the unified store — unique weights are moved (never re-downloaded), duplicates and stale venvs are reclaimed:\n\n```bash\n# TUI — current project only\n/models cleanup\n# TUI — every project + nested scoped group on this machine (dry-run first)\n/models cleanup --all --dry-run\n/models cleanup --all\n```\n\n```bash\n# REST — preview, then apply\ncurl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{\"dryRun\":true}'\ncurl -s -X POST localhost:11435/v1/media/migrate -H 'content-type: application/json' -d '{}'\n# Inspect store + reclaimable legacy caches\ncurl -s localhost:11435/v1/media/store\n```\n\n**Generate over REST.** The daemon (default `127.0.0.1:11435`, a port in the IANA dynamic/private range that avoids common system-service collisions) exposes the local generators so any user on the machine can list models, generate, and browse the global gallery without the CLI:\n\n```bash\ncurl -s localhost:11435/v1/media/models\ncurl -s -X POST localhost:11435/v1/media/image -H 'content-type: application/json' -d '{\"prompt\":\"a compact robot painter\"}'\ncurl -s -X POST localhost:11435/v1/media/music -H 'content-type: application/json' -d '{\"prompt\":\"warm lo-fi piano loop\"}'\ncurl -s localhost:11435/v1/media/gallery\n```\n\nThe same surface drives the **Generate** tab in the web UI (`http://127.0.0.1:11435`) — pick a kind (image/video/audio/music), choose a model loaded from the system, generate, and review every previously generated file in one global gallery.\n\n## Recent Highlights\n\n- The dashboard now has nine route-level operational surfaces with shared modular observability grids, a searchable workspace picker, and project-scoped navigation state.\n- 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.\n- `/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.\n- 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.\n- 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.\n- `/realtime` and REST `realtime: true` provide short, natural, SOUL.md-aware conversation for ASR/TTS clients.\n- Endpoint setup and sponsor setup aggregate models from all enabled endpoints, including external OpenAI-compatible routers.\n- `/sponsor` can expose text inference and media generation for image, video, sound, and music with per-modality limits.\n- Sponsor and COHERE status surfaces now use shared telemetry concepts: concurrency, request rate, daily tokens, peer usage, model usage, and remote system metrics.\n- The TUI reports token production rate as `t/s`, supports Shift+Enter multiline input, and renders dynamic shell output inside bounded Unicode cards.\n- Telegram state is scoped by user and group, supports durable reply preferences, and feeds raw platform/tool failures back into the agent loop.\n- Ollama pool cleanup now accounts for process groups and orphan runner processes that can keep VRAM pinned.\n- REST documentation is available both as human docs and as Omnius-discoverable docs skills.\n\n## REST API\n\nStart the daemon (default `http://127.0.0.1:11435`; interactive docs at `/docs`, machine spec at `/openapi.json`):\n\n```bash\nomnius serve\n```\n\nFor shared deployments, gate access with scoped bearer keys (`read` < `run` < `admin`):\n\n```bash\nOMNIUS_REST_API_KEYS=\"read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops\" omnius serve\n# then: Authorization: Bearer <key>\n```\n\nThe complete supported endpoint inventory follows. The canonical machine\ncontract is generated from [`packages/cli/src/api/openapi.ts`](packages/cli/src/api/openapi.ts),\nvalidated against [`docs/reference/rest-api.md`](docs/reference/rest-api.md),\nand projected into the generated block below. `pnpm docs:check` now fails when\nany of those three surfaces drift. Browser HTML pages, Swagger static assets,\nand implementation-only compatibility bridges are intentionally outside this\nstable REST contract.\n\n<!-- BEGIN GENERATED REST INVENTORY -->\n### Docs And Compatibility Aliases\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/docs` | Swagger UI |\n| `GET` | `/api/docs` | Swagger UI alias |\n| `GET` | `/openapi.json` | OpenAPI JSON |\n| `GET` | `/openapi.yaml` | OpenAPI YAML |\n| `GET` | `/v3/api-docs` | OpenAPI alias |\n| `GET` | `/swagger.json` | Swagger-era alias |\n| `GET` | `/api-docs` | OpenAPI alias |\n| `GET` | `/swagger-ui` | Swagger UI alias |\n| `GET` | `/redoc` | ReDoc renderer |\n| `GET` | `/` | HATEOAS API root when the client does not request HTML |\n| `GET` | `/help` | Compact daemon integration help |\n| `GET` | `/v1/routes` | Flat grep-friendly daemon route summary |\n| `GET` | `/routes` | Route-summary compatibility alias |\n| `GET` | `/asyncapi.json` | AsyncAPI 2.6 voicechat WebSocket contract |\n| `GET` | `/asyncapi` | AsyncAPI compatibility alias |\n\n### Health And Observability\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/health` | Liveness probe |\n| `GET` | `/health/ready` | Backend readiness |\n| `GET` | `/health/startup` | Startup probe |\n| `GET` | `/version` | Package version and platform |\n| `GET` | `/metrics` | Prometheus metrics |\n| `GET` | `/v1/events` | Server-sent event stream |\n| `GET` | `/v1/usage` | Token usage and rate limits |\n| `GET` | `/v1/audit` | Audit log query |\n| `GET` | `/v1/cost` | Cost tracker |\n| `GET` | `/v1/system` | CPU, RAM, GPU, and system snapshot |\n\n### Discovery\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/discovery/bootstrap` | Compact agent bootstrap and start-here map |\n| `GET` | `/v1/discovery` | Search layers, workflows, runtimes, modules, stores, and capabilities |\n| `GET` | `/v1/discovery/{id}` | Expand one stable capability entry |\n\n### Inference And Chat\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/models` | Aggregated model list |\n| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completion |\n| `POST` | `/v1/chat` | Stateful Omnius chat |\n| `POST` | `/api/chat` | Ollama-compatible chat alias |\n| `POST` | `/v1/generate` | Ollama-compatible one-shot generation |\n| `POST` | `/api/generate` | Ollama-compatible generate alias |\n| `POST` | `/v1/embeddings` | OpenAI-compatible embeddings |\n| `POST` | `/api/embed` | Ollama-compatible embeddings alias |\n| `GET` | `/api/tags` | Ollama-compatible model tags |\n| `POST` | `/realtime` | Text-only voice-adapter reply from a transcript |\n| `POST` | `/v1/realtime` | Auth-scoped realtime adapter alias |\n| `GET` | `/v1/chat/sessions` | Workspace-scoped persisted browser chats and importable TUI sessions |\n| `GET` | `/v1/chat/sessions/{id}` | Hydrate full session history, transcript, and in-flight state |\n| `DELETE` | `/v1/chat/sessions/{id}` | Permanently delete a canonical chat or TUI history session |\n| `POST` | `/v1/chat/sessions/{id}/summarize` | Generate + cache an inference-based session title/summary |\n| `POST` | `/v1/chat/suggest-followup` | Suggest one short next-message follow-up (ghost-text input) |\n| `GET` | `/v1/chat/sessions/{id}/status` | Reactive recall: live run status + unseen deltas (`?since=<seq>`) |\n| `POST` | `/v1/chat/check-in` | Steering check-in for active chat |\n| `POST` | `/v1/chat/attachments` | Upload an attachment for a stateful chat |\n\n#### Session History Contract\n\n`GET /v1/chat/sessions` is a history index, not merely a list of processes that\nare currently active. It returns canonical persisted browser chats for the\nselected workspace and, by default, quality-filtered TUI visual sessions that\ncan be imported on demand. Pass `?root=/absolute/workspace` to scope the list and\n`?include_tui=0` to omit TUI history. Exit-only inputs such as `/quit` and\n`/exit`, manual-save noise, empty transcripts, and duplicate normalized TUI\nsessions are rejected by the session-quality projection rather than presented as\nchats.\n\nSelecting a row should call `GET /v1/chat/sessions/{id}`. That response hydrates\nthe complete public message history (system prompts are intentionally omitted),\nthe original TUI transcript when applicable, token counts, timestamps, source\nand project identity, and any in-flight run with a bounded partial-output tail.\nUse the `status` endpoint with `?since=<seq>` for cheap reactive polling while a\nrun is active. `DELETE /v1/chat/sessions/{id}` is an admin operation and removes\nthe canonical record; deleting only a browser-side row does not remove daemon\nhistory.\n\n`POST /realtime` and `/v1/realtime` are text-only conversation adapters. They\naccept transcript text through `message`, `text`, `recent_turn`, `asr_text`, or\n`callerText`, optionally accept adapter-local `soul_md`, and can return plain\ntext with `Accept: text/plain` or `format: \"text\"`. ASR and TTS remain separate\noperations.\n\n### Agentic Runs\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `POST` | `/v1/run` | Submit agentic task |\n| `GET` | `/v1/runs` | List runs |\n| `GET` | `/v1/runs/{id}` | Get run details |\n| `GET` | `/v1/runs/{id}/output` | Read captured run output and status |\n| `DELETE` | `/v1/runs/{id}` | Abort run |\n| `POST` | `/v1/todos` | Create or update todos for current session |\n| `GET` | `/v1/todos` | List sessions with todos |\n| `GET` | `/v1/todos/{session_id}` | Get session todos |\n| `DELETE` | `/v1/todos/{session_id}` | Delete session todos |\n| `POST` | `/v1/evaluate` | Evaluate a run |\n| `POST` | `/v1/index` | Trigger repository indexing |\n\n### Configuration, Keys, Profiles, Projects\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/config` | Read daemon config |\n| `PATCH` | `/v1/config` | Update daemon config |\n| `GET` | `/v1/config/model` | Current model |\n| `PUT` | `/v1/config/model` | Switch model |\n| `POST` | `/v1/config/model/check` | Probe model readiness with non-empty text |\n| `GET` | `/v1/config/endpoint` | Current endpoint |\n| `PUT` | `/v1/config/endpoint` | Switch endpoint |\n| `POST` | `/v1/config/endpoint/test` | Probe endpoint |\n| `GET` | `/v1/config/endpoint/history` | Endpoint history |\n| `DELETE` | `/v1/config/endpoint/history` | Remove endpoint history item |\n| `POST` | `/v1/share/generate` | Generate remote-access share URL |\n| `GET` | `/v1/keys` | List runtime API keys |\n| `POST` | `/v1/keys` | Mint runtime API key |\n| `DELETE` | `/v1/keys/{prefix}` | Revoke runtime API keys by prefix |\n| `GET` | `/v1/profiles` | List tool profiles |\n| `POST` | `/v1/profiles` | Create tool profile |\n| `GET` | `/v1/profiles/{name}` | Get profile |\n| `DELETE` | `/v1/profiles/{name}` | Delete profile |\n| `GET` | `/v1/projects` | List known projects |\n| `DELETE` | `/v1/projects` | Unregister a project |\n| `GET` | `/v1/projects/current` | Current project |\n| `POST` | `/v1/projects/switch` | Switch project |\n| `POST` | `/v1/projects/register` | Register project |\n| `POST` | `/v1/projects/rename` | Rename project |\n| `GET` | `/v1/projects/preferences` | Read project preferences |\n| `PUT` | `/v1/projects/preferences` | Patch project preferences |\n| `DELETE` | `/v1/projects/preferences` | Reset project preferences |\n| `GET` | `/v1/projects/scan` | Scan configured roots for discoverable workspaces |\n| `GET` | `/v1/admin/access` | Read the daemon network access mode |\n| `POST` | `/v1/admin/access` | Change and persist access mode from loopback only |\n\n### Skills, Commands, Tools, MCP\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/skills` | List skills |\n| `GET` | `/v1/skills/{name}` | Load skill content |\n| `GET` | `/v1/commands` | List slash commands |\n| `POST` | `/v1/commands/{cmd}` | Execute slash command |\n| `GET` | `/v1/tools` | List tools (built-in + external) |\n| `POST` | `/v1/tools/register` | Register an application-specific external tool |\n| `GET` | `/v1/tools/{name}` | Tool metadata |\n| `DELETE` | `/v1/tools/{name}` | Unregister an external tool |\n| `POST` | `/v1/tools/{name}/call` | Call tool |\n| `POST` | `/v1/tools/{name}/eval` | Evaluate an external tool against test cases |\n| `GET` | `/v1/mcps` | List MCP servers |\n| `GET` | `/v1/mcps/{name}` | MCP server details |\n| `POST` | `/v1/mcps/{name}/call` | Call MCP tool |\n| `GET` | `/v1/hooks` | Hook registry |\n| `GET` | `/v1/agents` | Agent type registry |\n| `GET` | `/v1/codegraph/snapshot` | Code graph snapshot |\n| `GET` | `/v1/codegraph/events` | Code graph SSE |\n\n#### Registering Application-Specific Tools\n\nApplications can register their own tools so Omnius agents can discover and\ninvoke them alongside built-ins. `transport.type` selects the bridge:\n\n- `http` makes Omnius POST `{name, args, session_id}` to the application's\n  `callback_url` and relay the result.\n- `mcp` proxies to a named tool on an MCP server and can auto-connect from the\n  supplied connection descriptor.\n\nRegistrations persist per workspace at `.omnius/external-tools.json`, appear in\n`GET /v1/tools`, and use the same scope and off-device security gates as built-in\ntools. Registration needs `run` scope; a non-loopback caller needs `admin`.\n\n```bash\ncurl -s -X POST localhost:11435/v1/tools/register -H 'content-type: application/json' -d '{\n  \"name\": \"lookup_order\",\n  \"description\": \"Look up an order by id\",\n  \"parameters\": {\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"}},\"required\":[\"id\"]},\n  \"security\": {\"requires_scope\":\"run\",\"risk\":\"low\"},\n  \"transport\": {\"type\":\"http\",\"callback_url\":\"https://app.internal/tools/lookup_order\",\"auth_header\":\"Bearer …\"}\n}'\ncurl -s localhost:11435/v1/tools/lookup_order\ncurl -s -X POST localhost:11435/v1/tools/lookup_order/call -H 'content-type: application/json' -d '{\"args\":{\"id\":\"A-1001\"}}'\ncurl -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}}]}'\ncurl -s -X DELETE localhost:11435/v1/tools/lookup_order\n```\n\nThe MCP equivalent uses a transport such as\n`{\"type\":\"mcp\",\"server\":\"acme\",\"tool\":\"search\",\"connect\":{\"url\":\"https://app.internal/mcp\",\"transport\":\"streamable-http\"}}`.\n\n### AIWG\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/aiwg` | AIWG root and control map |\n| `GET` | `/v1/aiwg/frameworks` | List frameworks |\n| `GET` | `/v1/aiwg/frameworks/{name}` | Framework details |\n| `GET` | `/v1/aiwg/frameworks/{name}/content` | Tier-aware content |\n| `GET` | `/v1/aiwg/skills` | List AIWG skills |\n| `GET` | `/v1/aiwg/skills/{name}` | Load AIWG skill |\n| `GET` | `/v1/aiwg/agents` | List AIWG agents |\n| `GET` | `/v1/aiwg/agents/{name}` | Load AIWG agent |\n| `GET` | `/v1/aiwg/addons` | List AIWG addons |\n| `POST` | `/v1/aiwg/use` | Tier-sized activation bundle |\n| `POST` | `/v1/aiwg/expand` | Expand matching AIWG item |\n\n### Memory, Sessions, Context\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/memory` | Memory backend summary |\n| `POST` | `/v1/memory/search` | Search memory |\n| `POST` | `/v1/memory/write` | Write memory |\n| `GET` | `/v1/memory/episodes` | List episodes |\n| `GET` | `/v1/memory/failures` | List failure records |\n| `POST` | `/v1/memory/ingest` | Ingest content or files into memory |\n| `GET` | `/v1/memory/entities` | List extracted memory entities |\n| `POST` | `/v1/memory/jobs/run` | Run a named memory-maintenance job |\n| `POST` | `/v1/memory/feedback` | Record relevance or quality feedback for a memory item |\n| `GET` | `/v1/sessions` | List task sessions |\n| `GET` | `/v1/sessions/{id}` | Get session history |\n| `GET` | `/v1/context` | Current context snapshot |\n| `GET` | `/v1/context/window-dumps` | List persisted outbound model context-window dumps |\n| `GET` | `/v1/context/window-dumps/{id}` | Fetch a full outbound model context-window dump |\n| `POST` | `/v1/context/save` | Save context entry |\n| `GET` | `/v1/context/restore` | Build restore prompt |\n| `POST` | `/v1/context/compact` | Request compaction |\n\nContext-window dumps are written before backend inference for main agents,\nsub-agents, internal runners, and adversary audits. Query\n`GET /v1/context/window-dumps?agent_type=main` for summaries with signal/noise\nmetrics, or fetch a full payload by id. Dumps include focus-supervisor state when\na next-action contract is active. Set `OMNIUS_CONTEXT_WINDOW_DUMP_DIR` to move\nthe store, `OMNIUS_DISABLE_CONTEXT_WINDOW_DUMPS=1` to disable it, and\n`OMNIUS_FOCUS_SUPERVISOR=off|auto|strict` to tune focus enforcement.\n\n### Files, Nexus, Ollama Pool\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/files` | List workspace directory |\n| `POST` | `/v1/files/read` | Read workspace file |\n| `GET` | `/v1/files/raw` | Stream raw workspace bytes with content type and range support |\n| `HEAD` | `/v1/files/raw` | Inspect raw-file response metadata |\n| `GET` | `/v1/nexus/status` | Nexus peer state |\n| `GET` | `/v1/sponsors` | Sponsor directory cache |\n| `GET` | `/v1/ollama/pool/processes` | Ollama process inventory |\n| `POST` | `/v1/ollama/pool/cleanup` | Cleanup stale Ollama pool processes |\n\n### Voice, Audio, Vision\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/voice/state` | Voice runtime status |\n| `POST` | `/v1/voice/start` | Select an optional model, enable voice, and wait for readiness |\n| `POST` | `/v1/voice/stop` | Pause daemon voice input while leaving TTS warm |\n| `GET` | `/v1/voice/models` | TTS models |\n| `POST` | `/v1/voice/models/switch` | Switch and enable an exact TTS model by default |\n| `GET` | `/v1/voice/supertonic-settings` | Voice tuning settings |\n| `POST` | `/v1/voice/supertonic-settings` | Update voice tuning settings |\n| `GET` | `/v1/asr/engines` | Canonical ASR engines/models, capabilities, readiness, and selection |\n| `GET` | `/v1/asr/status` · `/v1/asr/selection` | Selected engine/model and runtime status |\n| `PATCH` | `/v1/asr/selection` | Persist and activate an exact engine/model |\n| `POST` | `/v1/asr/activate` | Activate and persist an exact engine/model |\n| `POST` | `/v1/asr/engines/{engineId}/setup` | Install a managed runtime and pinned weights |\n| `POST` | `/v1/asr/transcriptions` · `/v1/asr/test` | Transcribe/test using the real selected backend |\n| `GET` | `/v1/voice/asr-models` | Compatibility registry alias |\n| `POST` | `/v1/voice/asr-models/switch` | Compatibility activation alias |\n| `POST` | `/v1/voice/tts` | Synthesize speech |\n| `POST` | `/v1/audio/speech` | OpenAI-compatible TTS alias |\n| `POST` | `/v1/voice/transcribe` | Transcribe audio |\n| `POST` | `/v1/voice/asr` | Legacy transcription alias |\n| `POST` | `/v1/audio/transcriptions` | OpenAI-compatible transcription alias |\n| `POST` | `/v1/voice/transcribe/stream` | Isolated final transcription over SSE (no shared mic state or fake partials) |\n| `POST` | `/v1/voice/clone-refs` | Upload voice clone reference |\n| `GET` | `/v1/voice/clone-refs` | List clone references |\n| `POST` | `/v1/voice/clone-refs/upload` | Upload clone reference |\n| `POST` | `/v1/voice/clone-refs/from-url` | Fetch clone reference |\n| `POST` | `/v1/voice/clone-refs/{filename}/activate` | Activate clone reference |\n| `POST` | `/v1/voice/clone-refs/{filename}/rename` | Rename clone reference |\n| `DELETE` | `/v1/voice/clone-refs/{filename}` | Delete clone reference |\n| `POST` | `/v1/voice/speak` | Broadcast speech to voicechat clients |\n| `GET` | `/v1/voicechat/ws` | WebSocket upgrade for full-duplex voicechat |\n| `POST` | `/v1/vision/describe` | Vision describe placeholder |\n| `POST` | `/v1/vision/embed` | Create a vision embedding from media |\n| `POST` | `/v1/audio/embed` | Create an audio embedding from audio input |\n\n`POST /v1/voice/tts` and `/v1/audio/speech` automatically warm the daemon.\nAn explicit model must render exactly or the request fails; Omnius does not\nsilently synthesize with another voice. Responses include `X-Voice-Model`,\n`X-Voice-Backend`, and `X-Sample-Rate`. Available models include GLaDOS,\nOverwatch, `luxtts:announcer-testchamber03`, and the selected Voicebox suite.\nSet `OMNIUS_VOICEBOX_MODELS=all` for every carried-in Voicebox model, leave it\nat `stable` for the default set, or provide a comma-separated subset.\n\nASR selection is independent from TTS selection. The registry currently exposes\nOpenAI Whisper, managed `transcribe-cli`, NVIDIA Nemotron (reported unavailable\nuntil its legacy bootstrap is migrated), and Microsoft VibeVoice ASR. VibeVoice\nuses the exact pinned `microsoft/VibeVoice-ASR` checkpoint, reports setup and\nactivation separately, supports completed files up to 60 minutes with speakers,\ntimestamps, and `?context=` hotwords, and is deliberately not advertised as an\nincremental PCM backend. Its managed setup inherits the host CUDA-enabled Torch\nbuild (needed on Jetson/ARM64), never installs generic PyPI Torch, and activation\nrequires one explicit capable GPU. Discrete Linux uses `nvidia-smi` process/GPU\nevidence; Jetson/L4T uses NVIDIA's documented `tegrastats` plus CUDA Torch device\nproperties because `nvidia-smi` is unavailable there. Model weights live under\nthe unified Omnius ASR cache and are not shipped in the npm package.\n\n### Generative Media\n\nAll 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}`.\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/media/models` | List available image/video/audio/music models |\n| `GET` | `/v1/media/store` | Unified store disk usage + reclaimable legacy caches |\n| `POST` | `/v1/media/migrate` | Dedup + migrate legacy per-group caches into the unified store |\n| `POST` | `/v1/media/relocate` | Relocate the whole media store (weights/venvs/gallery) to a chosen folder |\n| `GET` | `/v1/media/relocate/status` | Status + progress of the media-store relocation job |\n| `POST` | `/v1/media/av/analyze` | Analyze a media file into a grounded entity/event answer (AV comprehension) |\n| `POST` | `/v1/media/image` | Generate an image |\n| `POST` | `/v1/media/video` | Generate a video |\n| `POST` | `/v1/media/audio` | Generate a sound effect |\n| `POST` | `/v1/media/music` | Generate music |\n| `GET` | `/v1/media/gallery` | List previously generated media (global, newest first) |\n| `GET` | `/v1/media/file` | Stream one generated media file |\n\n### Engines And Scheduled Jobs\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/engines` | Long-running engine status |\n| `GET` | `/v1/scheduled` | List scheduled jobs |\n| `DELETE` | `/v1/scheduled/all` | Delete all tasks, timers, cron entries, and persisted sources |\n| `GET` | `/v1/scheduled/status` | Scheduler status |\n| `POST` | `/v1/scheduled/{id}` | Enable or disable one scheduled task or user timer |\n| `DELETE` | `/v1/scheduled/{id}` | Delete one scheduled task or user timer |\n| `POST` | `/v1/scheduled/kill` | Kill scheduled job |\n| `POST` | `/v1/scheduled/fixup` | Reconcile scheduled state |\n| `GET` | `/v1/scheduled/reconcile` | Preview scheduled reconciliation |\n| `POST` | `/v1/scheduled/reconcile` | Preview or apply scheduled reconciliation |\n| `GET` | `/v1/services/systemd` | Systemd service status |\n| `POST` | `/v1/services/systemd/{unit}` | Act on one user-level systemd unit |\n| `GET` | `/v1/update` | Self-update status |\n| `POST` | `/v1/update` | Start an exact-version verified global update transaction |\n\n#### Verified Global Update Transaction\n\n`POST /v1/update` is not a CLI-local package edit. It starts one durable\ntransaction that installs the requested exact npm version globally, verifies\nthe installed package and resolved `omnius` executable, restarts and verifies\nthe daemon, verifies package/hash/runtime agreement, and relaunches the tray if\nit was running. The response is `202` with operation state; poll\n`GET /v1/update` for live phase, subprocess output, verification evidence, and\nthe final success or failure. Concurrent transactions and requests with no\navailable target return `409`.\n\nThe web dashboard and native tray both use this same endpoint. Update discovery\nis shared and semver-aware, so an older cached registry result cannot downgrade\nor falsely present an update. A completed transaction means the global package,\nexecutable, daemon, and tray runtime were all reconciled—not merely that `npm`\nexited successfully.\n\n### AIMS Governance\n\n| Method | Path | Purpose |\n| --- | --- | --- |\n| `GET` | `/v1/aims` | AIMS root and endpoint index |\n| `GET` | `/v1/aims/policies` | Policy register |\n| `PUT` | `/v1/aims/policies` | Replace policy register |\n| `GET` | `/v1/aims/roles` | Roles and responsibilities |\n| `GET` | `/v1/aims/resources` | Resource inventory |\n| `GET` | `/v1/aims/impact-assessments` | Impact assessments |\n| `POST` | `/v1/aims/impact-assessments` | File impact assessment |\n| `GET` | `/v1/aims/lifecycle` | Lifecycle state |\n| `GET` | `/v1/aims/data-quality` | Data quality controls |\n| `GET` | `/v1/aims/transparency` | Model cards and transparency |\n| `GET` | `/v1/aims/usage` | AIMS usage view |\n| `GET` | `/v1/aims/suppliers` | Supplier inventory |\n| `GET` | `/v1/aims/incidents` | Incident records |\n| `POST` | `/v1/aims/incidents` | File incident |\n| `GET` | `/v1/aims/oversight` | Human oversight gates |\n| `GET` | `/v1/aims/decisions` | Consequential decision log |\n| `GET` | `/v1/aims/config-history` | Config change history |\n\n### Browser And Compatibility Surfaces\n\nThe dashboard HTML routes (`/`, `/chat`, `/agent`, `/voice`, `/generate`,\n`/projects`, `/dashboard`, `/jobs`, `/activity`, `/discover`, `/settings`, and\n`/config`) are documented in the [dashboard guide](../guides/dashboard.md). They\nare pages, not JSON API operations; `/` returns the HATEOAS JSON root when the\nclient does not request HTML.\n\nSwagger/ReDoc trailing-slash variants, `/api/docs/*` static assets, and\n`/favicon.ico` exist for browsers. They are delivery details rather than stable\nintegration endpoints. The daemon also retains browser/legacy bridges at\n`/v1/model`, `/v1/endpoint`, `/v1/theme`, `/v1/tor/*`, `/v1/remote-proxy`, and\n`/v1/command`. New clients should prefer `/v1/config/model`,\n`/v1/config/endpoint`, `/v1/config`, and `/v1/commands/{cmd}`. Compatibility\nhandlers may accept additional HTTP verbs for old dashboard bundles; only the\nmethods in the supported inventory above are contractual.\n<!-- END GENERATED REST INVENTORY -->\n## Agent-Explorable Documentation\n\nOmnius discovers project-local docs skills from `.aiwg/addons/*/skills`. The docs bundles in this repo expose high-signal entrypoints for agents:\n\n```text\n/skills omnius docs\nskill_execute name=\"omnius-docs\"\nskill_execute name=\"omnius-rest-docs\"\nskill_extract name=\"omnius-realtime-docs\" query=\"How does realtime REST mode work?\"\n```\n\nThe intended pattern is index first, targeted document second, not loading the whole manual into the active context.\n\n## Development\n\n```bash\npnpm install\npnpm -r build\npnpm docs:check\n```\n\nFocused checks used for the docs skill surface:\n\n```bash\npnpm --filter @omnius/execution exec vitest run tests/skill-discovery.test.ts\npnpm --filter omnius exec vitest run tests/realtime-mode.test.ts tests/command-registry.test.ts\n```\n\n## Publishing\n\nPublish only from `publish/`.\n\n```bash\ncd omnius\npnpm -r clean || true\nfind . -name 'tsconfig.tsbuildinfo' -not -path '*/node_modules/*' -delete\npnpm -r build\nnode scripts/build-publish.mjs\ncd publish\nmkdir -p .npm-cache\nNPM_CONFIG_CACHE=$(pwd)/.npm-cache npm pack --prefer-online --cache-min=0 --registry https://registry.npmjs.org/\nNPM_CONFIG_CACHE=$(pwd)/.npm-cache npm publish --access public --prefer-online --cache-min=0 --registry https://registry.npmjs.org/\n```\n\nBefore publishing, verify `README.md`, `package.json`, `dist/index.js`, and `dist/launcher.cjs` are in the tarball, and that `package.json` includes `readmeFilename: \"README.md\"` plus a string `readme`.\n\n## License\n\nOmnius is released under [CC-BY-NC-4.0](LICENSE) for non-commercial use. Commercial use, redistribution, hosted services, and enterprise deployment require a commercial license.\n"
 }

package/templates/OMNIUS.md

@@ -1,7 +1,8 @@
 <!-- omnius:discovery:start -->
-# Omnius Discovery
+# Omnius Agent Guide
 
-This project uses Omnius. Discover capabilities before guessing:
+This project uses Omnius. Search the installed discovery contract before
+guessing a command, route, tool, provider, state path, or source owner:
 
 ```bash
 omnius discover "your task"
@@ -10,11 +11,34 @@ omnius docs
 omnius capabilities --json
 ```
 
-For a running daemon, start with `GET /version`, `GET /help`,
-`GET /v1/discovery`, `GET /v1/tools`, and `GET /openapi.json`.
-Set `X-Omnius-Min-Version` on execution requests when a minimum runtime is required.
+Start with `workflow.choose-entrypoint`, then expand the relevant `layer.*`,
+`module.*`, `runtime.*`, `store.*`, or task-specific `workflow.*` entry.
+
+| Need | Use |
+| --- | --- |
+| Interactive chat and human-only slash commands | `omnius` |
+| One foreground coding task | `omnius "<task>"` |
+| Stateful daemon conversation | `POST /v1/chat` |
+| Long task with ID, events, polling, and cancel | `POST /v1/run` |
+| OpenAI-compatible client | `POST /v1/chat/completions` |
+| One direct tool | Only the exact `rest-call` interface returned by tool metadata |
+
+For a running daemon, bootstrap from `GET /v1/discovery/bootstrap`, then check
+`GET /version`, `GET /health/ready`, `GET /openapi.json`, and the relevant live
+registry such as `GET /v1/tools`. Send `X-Omnius-Min-Version` on execution
+requests so a stale runtime fails before creating work.
+
+State is deliberately split: project sessions/tasks/context belong in
+`<project>/.omnius`; daemon identity, credentials, managed runtimes, and shared
+model/media storage belong in `~/.omnius`. Resolve the active workspace before
+touching project state, and never emit secrets from global state.
 
 `web_search` is agent-bound: inspect `GET /v1/tools/web_search`, then use
 `/v1/run`, `/v1/chat`, or `/v1/chat/completions` with
 `agent_loop:true` and `include_daemon_tools:["read"]`.
+
+Never infer REST exposure from a slash command or direct-call exposure from a
+tool name. Treat queued/accepted as non-terminal; verify the observable result.
+Small-context agents should expand one workflow and its references. Maintainer
+agents should also expand the owning layer/module and run discovery freshness.
 <!-- omnius:discovery:end -->