omnius 1.0.321 → 1.0.323

package/docs/reference/rest-api.md

@@ -189,6 +189,22 @@ pnpm docs:check
 | `GET` | `/v1/voicechat/ws` | WebSocket upgrade for full-duplex voicechat |
 | `POST` | `/v1/vision/describe` | Vision describe placeholder |
 
+## Generative Media
+
+All generation is backed by the unified `~/.omnius` model store and shared venvs (single source of truth — no per-project duplication). Generated files are consolidated into the global gallery at `~/.omnius/media/{images,videos,audio,music}`.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/v1/media/models` | List available image/video/audio/music models |
+| `GET` | `/v1/media/store` | Unified store disk usage + reclaimable legacy caches |
+| `POST` | `/v1/media/migrate` | Dedup + migrate legacy per-group caches into the unified store |
+| `POST` | `/v1/media/image` | Generate an image |
+| `POST` | `/v1/media/video` | Generate a video |
+| `POST` | `/v1/media/audio` | Generate a sound effect |
+| `POST` | `/v1/media/music` | Generate music |
+| `GET` | `/v1/media/gallery` | List previously generated media (global, newest first) |
+| `GET` | `/v1/media/file` | Stream one generated media file |
+
 ## Engines And Scheduled Jobs
 
 | Method | Path | Purpose |

package/docs/reference/slash-commands.md

@@ -14,11 +14,11 @@ Command metadata drives the TUI, REST command proxy, gateway exposure, and agent
 
 | Category | Commands |
 | --- | ---: |
-| Core | 23 |
+| Core | 26 |
 | Models And Endpoints | 2 |
 | Sessions And Control | 14 |
 | Runtime | 12 |
-| Media | 10 |
+| Media | 11 |
 | Network And P2P | 10 |
 | Memory And Context | 1 |
 | Tools And Skills | 6 |
@@ -26,7 +26,7 @@ Command metadata drives the TUI, REST command proxy, gateway exposure, and agent
 | Secrets | 2 |
 | Interface | 9 |
 | Administration | 2 |
-| Planned | 10 |
+| Planned | 8 |
 
 ## Core
 
@@ -122,6 +122,33 @@ Signatures:
 
 - `/cost` - Show session token cost breakdown
 
+### /cron
+
+Cron/scheduled job management
+
+| Field | Value |
+| --- | --- |
+| Category | Core |
+| Status | implemented |
+| Surfaces | tui, rest, gateway |
+| Safety | userOnly, networked |
+| Aliases | - |
+| Args | - |
+| Subcommands | list, add, edit, pause, resume, run, remove, outputs, tick |
+
+Signatures:
+
+- `/cron` - Cron/scheduled job management
+- `/cron list` - List cron jobs
+- `/cron add <schedule> <prompt>` - Create a new cron job
+- `/cron edit <id> <field> <val>` - Update a cron job field
+- `/cron pause <id>` - Pause a cron job
+- `/cron resume <id>` - Resume a paused cron job
+- `/cron run <id>` - Execute a cron job immediately
+- `/cron remove <id>` - Delete a cron job
+- `/cron outputs <id>` - Show saved output files for a job
+- `/cron tick` - Run scheduler tick
+
 ### /deep
 
 Toggle deep context - relaxes compaction so large models use 85% of context
@@ -253,6 +280,24 @@ Signatures:
 - `/hf clear` - Remove the persisted HF token
 - `/hf cancel` - Cancel any pending HF token prompt and fall back immediately
 
+### /insights
+
+Show historical session insights
+
+| Field | Value |
+| --- | --- |
+| Category | Core |
+| Status | implemented |
+| Surfaces | tui, rest, gateway, agentTool |
+| Safety | none |
+| Aliases | - |
+| Args | - |
+| Subcommands | - |
+
+Signatures:
+
+- `/insights` - Show historical session insights
+
 ### /music
 
 Open music-generation model/setup menu
@@ -458,6 +503,24 @@ Signatures:
 
 - `/think` - Toggle thinking/reasoning mode (Qwen3, DeepSeek-R1, etc.)
 
+### /usage
+
+Show current session token count and cost
+
+| Field | Value |
+| --- | --- |
+| Category | Core |
+| Status | implemented |
+| Surfaces | tui, rest, gateway, agentTool |
+| Safety | none |
+| Aliases | - |
+| Args | - |
+| Subcommands | - |
+
+Signatures:
+
+- `/usage` - Show current session token count and cost
+
 ### /verbose
 
 Toggle verbose mode
@@ -510,12 +573,16 @@ List all available models
 | Safety | userOnly |
 | Aliases | - |
 | Args | - |
-| Subcommands | evict, cleanup |
+| Subcommands | 3d, cad, viewer, hf, evict, cleanup |
 
 Signatures:
 
 - `/models` - List all available models
 - `/models` - Show unified ~/.omnius model store: disk usage, cached repos, last-used
+- `/models 3d` - Select CAD/3D generation and reconstruction model adapters
+- `/models cad` - Select text-to-CAD model adapters such as cad0
+- `/models viewer [file]` - Start a temporary standalone CAD/3D viewer endpoint
+- `/models hf list --modality 3d` - List curated and installed Hugging Face CAD/3D adapters
 - `/models evict <repo>` - Remove a cached HF repo from the unified store to reclaim disk
 - `/models evict --free <GB>` - LRU-evict cached models until <GB> of free disk is available
 - `/models cleanup` - Migrate legacy per-repo .omnius/{image,video,audio}-gen caches into the unified store and delete the originals
@@ -953,14 +1020,13 @@ Scheduled tasks control panel (list/kill/toggle)
 | Status | implemented |
 | Surfaces | tui, rest, gateway |
 | Safety | userOnly |
-| Aliases | /cron |
+| Aliases | - |
 | Args | - |
 | Subcommands | menu, list, kill |
 
 Signatures:
 
 - `/scheduler` - Scheduled tasks control panel (list/kill/toggle)
-- `/cron` - Alias for /scheduler
 - `/scheduler menu` - Interactive scheduler menu (toggle/kill)
 - `/scheduler list` - List all scheduled tasks and timers
 - `/scheduler kill` - Kill schedulers + active runs (with escalation if needed)
@@ -1143,6 +1209,32 @@ Signatures:
 
 - `/paste` - Attach clipboard image content to the current or next prompt
 
+### /pointcloud
+
+Open point-cloud generation model/setup menu
+
+| Field | Value |
+| --- | --- |
+| Category | Media |
+| Status | implemented |
+| Surfaces | tui, rest, gateway |
+| Safety | userOnly, networked |
+| Aliases | /points, /pcl, /point |
+| Args | - |
+| Subcommands | --image, setup, list, prewarm |
+
+Signatures:
+
+- `/pointcloud` - Open point-cloud generation model/setup menu
+- `/pointcloud --image <path>` - Generate a 3D point cloud PLY from an image using depth estimation
+- `/pointcloud --image <path> --model <model>` - Generate with an explicit depth model (depth-anything-v3-* or mda-*)
+- `/pointcloud --image <path1,path2> --backend mda` - Multi-view depth fusion from comma-separated image paths
+- `/pointcloud setup <depth-anything\|mda>` - Show setup commands for a point-cloud backend
+- `/pointcloud list` - List point-cloud models by backend, quality, and VRAM fit
+- `/pointcloud prewarm` - Download and warm up the selected depth model
+- `/points <args>` - Alias for /pointcloud
+- `/pcl <args>` - Alias for /pointcloud
+
 ### /transcribe
 
 Alias for /ingest <file>
@@ -1202,10 +1294,10 @@ Toggle TTS voice feedback
 Signatures:
 
 - `/voice` - Toggle TTS voice feedback
-- `/voice <model>` - Set voice: glados, overwatch, kokoro, luxtts, supertonic
+- `/voice <model>` - Set voice: glados, overwatch, kokoro, luxtts, misotts, supertonic
 - `/voice clone <file>` - Set voice clone reference audio (wav/mp3/ogg/flac)
-- `/voice clone glados` - Generate clone ref from GLaDOS for LuxTTS
-- `/voice clone overwatch` - Generate clone ref from Overwatch for LuxTTS
+- `/voice clone glados` - Generate clone ref from GLaDOS for LuxTTS/MisoTTS voice cloning
+- `/voice clone overwatch` - Generate clone ref from Overwatch for LuxTTS/MisoTTS voice cloning
 
 ### /voicechat
 
@@ -1625,7 +1717,7 @@ Save Telegram bot token (persisted to settings)
 | Safety | userOnly, networked, secretBearing, profileGated |
 | Aliases | /tg |
 | Args | --key <token> |
-| Subcommands | --key, --admin, status, stop, mode, subagents, auth, bot, poll, live-photo, draft, admins, personal, access, tools, delete-message, delete-messages, delete-reaction, delete-reactions |
+| Subcommands | --key, --admin, status, stop, disable, enable, mode, subagents, model, endpoint, auth, bot, poll, live-photo, draft, admins, personal, access, tools, delete-message, delete-messages, delete-reaction, delete-reactions |
 
 Signatures:
 
@@ -1634,8 +1726,14 @@ Signatures:
 - `/telegram` - Toggle Telegram bridge on/off (uses saved key)
 - `/telegram status` - Show Telegram bridge status
 - `/telegram stop` - Disconnect Telegram bridge
+- `/telegram disable` - Persistently disable Telegram long polling
+- `/telegram enable` - Re-enable Telegram long polling
 - `/telegram mode auto\|chat\|action` - Set Telegram interaction routing: auto, fast chat, or action sub-agent
 - `/telegram subagents <1-5>` - Set global Telegram work-slot limit across all chats/groups
+- `/telegram model` - Pick the Telegram-isolated model (model list from the Telegram endpoint)
+- `/telegram model <name\|reset>` - Set or clear the Telegram-isolated model (separate from main agent)
+- `/telegram endpoint` - Pick the Telegram-isolated backend endpoint (same menu as /endpoint, bot-scoped)
+- `/telegram endpoint <url\|reset> [--auth <t>]` - Set or clear the Telegram-isolated endpoint
 - `/telegram auth` - Show a TUI-only one-time code for Telegram admin authentication
 - `/telegram auth cancel` - Cancel the pending Telegram admin authentication code
 - `/telegram bot <username> <text>` - Send a Bot API bot-to-bot message by @username
@@ -1968,24 +2066,6 @@ Signatures:
 
 - `/deny` - Deny a pending gateway/admin action
 
-### /insights
-
-Show session insights
-
-| Field | Value |
-| --- | --- |
-| Category | Planned |
-| Status | planned |
-| Surfaces | tui |
-| Safety | none |
-| Aliases | - |
-| Args | - |
-| Subcommands | - |
-
-Signatures:
-
-- `/insights` - Show session insights
-
 ### /plugins
 
 List or manage plugins
@@ -2075,21 +2155,3 @@ Show or select tool exposure sets
 Signatures:
 
 - `/toolsets` - Show or select tool exposure sets
-
-### /usage
-
-Show usage and quota details
-
-| Field | Value |
-| --- | --- |
-| Category | Planned |
-| Status | planned |
-| Surfaces | tui |
-| Safety | none |
-| Aliases | - |
-| Args | - |
-| Subcommands | - |
-
-Signatures:
-
-- `/usage` - Show usage and quota details

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "omnius",
-  "version": "1.0.321",
+  "version": "1.0.323",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omnius",
-      "version": "1.0.321",
+      "version": "1.0.323",
       "bundleDependencies": [
         "image-to-ascii"
       ],
@@ -2094,12 +2094,12 @@
       }
     },
     "node_modules/@types/node": {
-      "version": "25.9.3",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.9.3.tgz",
-      "integrity": "sha512-603BddQMv3pUcr4U2dhujk83N2tTDVr/34wII2B6bJy6g+8WD6yUb11jszNs0gdi4PesVWl7ABt8nYMVpnLUcg==",
+      "version": "26.0.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.0.0.tgz",
+      "integrity": "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA==",
       "license": "MIT",
       "dependencies": {
-        "undici-types": ">=7.24.0 <7.24.7"
+        "undici-types": "~8.3.0"
       }
     },
     "node_modules/@types/sinon": {
@@ -4026,9 +4026,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.25",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.25.tgz",
-      "integrity": "sha512-2NFaIyNVgJmBs/ecmtGzlmluTFs5cHEWGTdu0t1HBwYzoGXOL5nUQBRMXsXWla5i4KkG//QMzVP88m1+I3fdAQ==",
+      "version": "4.12.26",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.26.tgz",
+      "integrity": "sha512-uyZtpnYxM9CmQ7QsQknM4zN8EftNqhON1qYeIKM0Se67CCEe2c44xyGURwB0axX2fBDu1dqHrHAc1hmNT8ITkw==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"
@@ -5239,9 +5239,9 @@
       "license": "Apache-2.0 OR MIT"
     },
     "node_modules/nanoid": {
-      "version": "5.1.11",
-      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-5.1.11.tgz",
-      "integrity": "sha512-v+KEsUv2ps74PaSKv0gHTxTCgMXOIfBEbaqa6w6ISIGC7ZsvHN4N9oJ8d4cmf0n5oTzQz2SLmThbQWhjd/8eKg==",
+      "version": "5.1.14",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-5.1.14.tgz",
+      "integrity": "sha512-5c8l8kVzqpnDPaicbEop/fV0Q1w16FmbWtVhMqugTozAwYdlIQojWH5a/M7UfziFmGdQRrUdV+EPzc9Xng3VAQ==",
       "funding": [
         {
           "type": "github",
@@ -7197,9 +7197,9 @@
       }
     },
     "node_modules/undici-types": {
-      "version": "7.24.6",
-      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
-      "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==",
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.3.0.tgz",
+      "integrity": "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==",
       "license": "MIT"
     },
     "node_modules/unlimited-timeout": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omnius",
-  "version": "1.0.321",
+  "version": "1.0.323",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/index.js",
@@ -143,5 +143,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\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| 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| 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| Architecture | [Architecture overview](docs/architecture/overview.md) |\n| Agent-explorable docs | [Agent memory docs index](docs/agent-memory/INDEX.md) |\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:\n\n```bash\nomnius serve\n```\n\nUseful entrypoints:\n\n```text\nGET  /docs\nGET  /openapi.json\nPOST /v1/chat\nPOST /v1/chat/completions\nPOST /v1/run\nGET  /v1/events\nGET  /v1/skills\nPOST /v1/tools/{name}/call\nWS   /v1/voicechat/ws\n```\n\nFor shared deployments, use bearer keys:\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```\n\nSee [docs/reference/rest-api.md](docs/reference/rest-api.md) for the maintained endpoint inventory. The canonical machine contract is generated from [packages/cli/src/api/openapi.ts](packages/cli/src/api/openapi.ts).\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\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| 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| 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| 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### 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 · tool metadata |\n| `POST` | `/v1/tools/{name}/call` | Call tool |\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### 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| `POST` | `/v1/context/save` · `/v1/context/compact` | Save entry · request compaction |\n| `GET` | `/v1/context/restore` | Build restore prompt |\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| `GET`/`POST` | `/v1/voice/models` · `/v1/voice/models/switch` | List · switch 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\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"
 }