omnius 1.0.594 → 1.0.595

package/docs/.vitepress/config.mts

@@ -53,6 +53,7 @@ export default defineConfig({
         items: [
           { text: "Bring Your Own Inference", link: "/guides/bring-your-own-inference" },
           { text: "Tools And Web Search", link: "/guides/tools-and-web-search" },
+          { text: "Categorized OSINT Research", link: "/guides/osint-research" },
           { text: "Agent Integration", link: "/guides/agent-integration" },
           { text: "TUI Workflows", link: "/guides/tui-workflows" },
           { text: "Sponsor And COHERE", link: "/guides/sponsor-and-cohere" },

package/docs/DISCOVERY.json

@@ -5771,6 +5771,65 @@
         "operation.version-compatibility"
       ]
     },
+    {
+      "id": "capability.osint-research",
+      "kind": "capability",
+      "title": "Categorized OSINT research",
+      "summary": "Discover a compact ranked shortlist from the bundled 77-category OSINT4ALL snapshot, expand one exact resource, then deliberately route it through an appropriate web tool with provenance and safety guidance.",
+      "aliases": [
+        "OSINT",
+        "OSINT4ALL",
+        "long-haul research",
+        "open source intelligence"
+      ],
+      "keywords": [
+        "research",
+        "catalog",
+        "search",
+        "provenance",
+        "corroboration",
+        "identity",
+        "social",
+        "network",
+        "geospatial"
+      ],
+      "maturity": "stable",
+      "prerequisites": [
+        "Legitimate research purpose",
+        "Authorization for active or sensitive target interaction"
+      ],
+      "interfaces": [
+        {
+          "type": "agent-tool",
+          "target": "osint_search",
+          "description": "Compact deterministic local discovery"
+        },
+        {
+          "type": "agent-tool",
+          "target": "osint_show",
+          "description": "Exact resource expansion"
+        }
+      ],
+      "references": [
+        {
+          "type": "guide",
+          "target": "docs/guides/osint-research.md",
+          "relation": "canonical-guide"
+        },
+        {
+          "type": "source",
+          "target": "packages/execution/src/tools/osint-catalog-data.ts",
+          "relation": "generated-catalog"
+        }
+      ],
+      "related": [
+        "tool.osint-search",
+        "tool.osint-show",
+        "tool.web-search",
+        "tool.web-fetch",
+        "tool.web-crawl"
+      ]
+    },
     {
       "id": "command.access",
       "kind": "command",
@@ -10866,6 +10925,32 @@
         }
       ]
     },
+    {
+      "id": "guide.guides-osint-research",
+      "kind": "guide",
+      "title": "Categorized OSINT research",
+      "summary": "Bundled Omnius documentation artifact: docs/guides/osint-research.md.",
+      "keywords": [
+        "guides",
+        "osint",
+        "research",
+        "md"
+      ],
+      "maturity": "stable",
+      "interfaces": [
+        {
+          "type": "file",
+          "target": "docs/guides/osint-research.md"
+        }
+      ],
+      "references": [
+        {
+          "type": "documentation",
+          "target": "docs/guides/osint-research.md",
+          "relation": "canonical-artifact"
+        }
+      ]
+    },
     {
       "id": "guide.guides-realtime",
       "kind": "guide",
@@ -13807,6 +13892,7 @@
       ],
       "related": [
         "capability.bring-your-own-inference",
+        "capability.osint-research",
         "api.discovery",
         "api.tools",
         "operation.version-compatibility"
@@ -18273,6 +18359,107 @@
       ],
       "direct_callable": false
     },
+    {
+      "id": "tool.osint-search",
+      "kind": "tool",
+      "title": "OSINT Search",
+      "summary": "Search the bundled OSINT4ALL snapshot locally and return a bounded ranked shortlist with category, archived-health, interaction, and risk metadata; no cataloged service is contacted.",
+      "aliases": [
+        "osint_search",
+        "OSINT catalog search"
+      ],
+      "keywords": [
+        "OSINT4ALL",
+        "local index",
+        "top-k",
+        "77 categories",
+        "1446 resources",
+        "1456 placements"
+      ],
+      "interfaces": [
+        {
+          "type": "rest-schema",
+          "target": "/v1/tools/osint_search"
+        },
+        {
+          "type": "agent-run",
+          "target": "/v1/run"
+        },
+        {
+          "type": "agent-chat",
+          "target": "/v1/chat/completions"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/execution/src/tools/osint-catalog.ts",
+          "relation": "implementation"
+        },
+        {
+          "type": "guide",
+          "target": "docs/guides/osint-research.md",
+          "relation": "usage"
+        }
+      ],
+      "direct_callable": false,
+      "maturity": "stable",
+      "related": [
+        "capability.osint-research",
+        "tool.osint-show"
+      ]
+    },
+    {
+      "id": "tool.osint-show",
+      "kind": "tool",
+      "title": "OSINT Show",
+      "summary": "Expand one exact local OSINT resource ID into its URL, aliases, original category placements, archived health, and safe next-tool route; no cataloged service is contacted.",
+      "aliases": [
+        "osint_show",
+        "OSINT resource expansion"
+      ],
+      "keywords": [
+        "OSINT4ALL",
+        "exact lookup",
+        "provenance",
+        "risk",
+        "archived health"
+      ],
+      "interfaces": [
+        {
+          "type": "rest-schema",
+          "target": "/v1/tools/osint_show"
+        },
+        {
+          "type": "agent-run",
+          "target": "/v1/run"
+        },
+        {
+          "type": "agent-chat",
+          "target": "/v1/chat/completions"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/execution/src/tools/osint-catalog.ts",
+          "relation": "implementation"
+        },
+        {
+          "type": "guide",
+          "target": "docs/guides/osint-research.md",
+          "relation": "usage"
+        }
+      ],
+      "direct_callable": false,
+      "maturity": "stable",
+      "related": [
+        "capability.osint-research",
+        "tool.osint-search",
+        "tool.web-fetch",
+        "tool.web-crawl"
+      ]
+    },
     {
       "id": "tool.pdf-to-text",
       "kind": "tool",

package/docs/DISCOVERY.md

@@ -179,6 +179,7 @@ Daemon equivalents are `GET /v1/discovery?q=<intent>` and `GET /v1/discovery/{id
 | `addon.omnius-docs` | Omnius Documentation | Project-local Omnius documentation bundle for discover-then-expand agent workflows. |
 | `addon.omnius-rest-docs` | Omnius REST Documentation | Project-local Omnius REST API documentation bundle for discover-then-expand agent workflows. |
 | `capability.bring-your-own-inference` | Bring your own inference | Connect local runtimes, Claude, Gemini, and registered OpenAI-compatible providers through explicit protocol and credential descriptors. |
+| `capability.osint-research` | Categorized OSINT research | Discover a compact ranked shortlist from the bundled 77-category OSINT4ALL snapshot, expand one exact resource, then deliberately route it through an appropriate web tool with provenance and safety guidance. |
 | `overview` | Omnius capability overview | Start here to discover Omnius providers, tools, APIs, commands, skills, configuration, operations, and shipped documentation. |
 
 ## Command
@@ -357,6 +358,7 @@ Daemon equivalents are `GET /v1/discovery?q=<intent>` and `GET /v1/discovery/{id
 | `guide.guides-agent-integration` | Agent And Service Integration | Bundled Omnius documentation artifact: docs/guides/agent-integration.md. |
 | `guide.guides-bring-your-own-inference` | Bring Your Own Inference | Bundled Omnius documentation artifact: docs/guides/bring-your-own-inference.md. |
 | `guide.guides-media-generation` | Media Generation | Bundled Omnius documentation artifact: docs/guides/media-generation.md. |
+| `guide.guides-osint-research` | Categorized OSINT research | Bundled Omnius documentation artifact: docs/guides/osint-research.md. |
 | `guide.guides-realtime` | Realtime Conversations | Bundled Omnius documentation artifact: docs/guides/realtime.md. |
 | `guide.guides-sponsor-and-cohere` | Sponsor And COHERE Mesh | Bundled Omnius documentation artifact: docs/guides/sponsor-and-cohere.md. |
 | `guide.guides-telegram` | Telegram Bridge | Bundled Omnius documentation artifact: docs/guides/telegram.md. |
@@ -591,6 +593,8 @@ Daemon equivalents are `GET /v1/discovery?q=<intent>` and `GET /v1/discovery/{id
 | `tool.ocr-image-advanced` | Ocr Image Advanced | ocr_image_advanced is an agent-bound Omnius tool available through chat/run tool exposure. |
 | `tool.ocr-pdf` | Ocr Pdf | ocr_pdf is an agent-bound Omnius tool available through chat/run tool exposure. |
 | `tool.opencode` | Opencode | opencode is an agent-bound Omnius tool available through chat/run tool exposure. |
+| `tool.osint-search` | OSINT Search | Search the bundled OSINT4ALL snapshot locally and return a bounded ranked shortlist with category, archived-health, interaction, and risk metadata; no cataloged service is contacted. |
+| `tool.osint-show` | OSINT Show | Expand one exact local OSINT resource ID into its URL, aliases, original category placements, archived health, and safe next-tool route; no cataloged service is contacted. |
 | `tool.pdf-to-text` | Pdf To Text | pdf_to_text is an agent-bound Omnius tool available through chat/run tool exposure. |
 | `tool.pdf-visual-markdown` | Pdf Visual Markdown | pdf_visual_markdown is an agent-bound Omnius tool available through chat/run tool exposure. |
 | `tool.phase-recall` | Phase Recall | phase_recall is an agent-bound Omnius tool available through chat/run tool exposure. |

package/docs/discovery/catalog-overrides.json

@@ -20,6 +20,7 @@
       ],
       "related": [
         "capability.bring-your-own-inference",
+        "capability.osint-research",
         "api.discovery",
         "api.tools",
         "operation.version-compatibility"
@@ -87,6 +88,65 @@
         "operation.version-compatibility"
       ]
     },
+    {
+      "id": "capability.osint-research",
+      "kind": "capability",
+      "title": "Categorized OSINT research",
+      "summary": "Discover a compact ranked shortlist from the bundled 77-category OSINT4ALL snapshot, expand one exact resource, then deliberately route it through an appropriate web tool with provenance and safety guidance.",
+      "aliases": ["OSINT", "OSINT4ALL", "long-haul research", "open source intelligence"],
+      "keywords": ["research", "catalog", "search", "provenance", "corroboration", "identity", "social", "network", "geospatial"],
+      "maturity": "stable",
+      "prerequisites": ["Legitimate research purpose", "Authorization for active or sensitive target interaction"],
+      "interfaces": [
+        {"type": "agent-tool", "target": "osint_search", "description": "Compact deterministic local discovery"},
+        {"type": "agent-tool", "target": "osint_show", "description": "Exact resource expansion"}
+      ],
+      "references": [
+        {"type": "guide", "target": "docs/guides/osint-research.md", "relation": "canonical-guide"},
+        {"type": "source", "target": "packages/execution/src/tools/osint-catalog-data.ts", "relation": "generated-catalog"}
+      ],
+      "related": ["tool.osint-search", "tool.osint-show", "tool.web-search", "tool.web-fetch", "tool.web-crawl"]
+    },
+    {
+      "id": "tool.osint-search",
+      "kind": "tool",
+      "title": "OSINT Search",
+      "summary": "Search the bundled OSINT4ALL snapshot locally and return a bounded ranked shortlist with category, archived-health, interaction, and risk metadata; no cataloged service is contacted.",
+      "aliases": ["osint_search", "OSINT catalog search"],
+      "keywords": ["OSINT4ALL", "local index", "top-k", "77 categories", "1446 resources", "1456 placements"],
+      "maturity": "stable",
+      "interfaces": [
+        {"type": "rest-schema", "target": "/v1/tools/osint_search"},
+        {"type": "agent-run", "target": "/v1/run"},
+        {"type": "agent-chat", "target": "/v1/chat/completions"}
+      ],
+      "references": [
+        {"type": "source", "target": "packages/execution/src/tools/osint-catalog.ts", "relation": "implementation"},
+        {"type": "guide", "target": "docs/guides/osint-research.md", "relation": "usage"}
+      ],
+      "related": ["capability.osint-research", "tool.osint-show"],
+      "direct_callable": false
+    },
+    {
+      "id": "tool.osint-show",
+      "kind": "tool",
+      "title": "OSINT Show",
+      "summary": "Expand one exact local OSINT resource ID into its URL, aliases, original category placements, archived health, and safe next-tool route; no cataloged service is contacted.",
+      "aliases": ["osint_show", "OSINT resource expansion"],
+      "keywords": ["OSINT4ALL", "exact lookup", "provenance", "risk", "archived health"],
+      "maturity": "stable",
+      "interfaces": [
+        {"type": "rest-schema", "target": "/v1/tools/osint_show"},
+        {"type": "agent-run", "target": "/v1/run"},
+        {"type": "agent-chat", "target": "/v1/chat/completions"}
+      ],
+      "references": [
+        {"type": "source", "target": "packages/execution/src/tools/osint-catalog.ts", "relation": "implementation"},
+        {"type": "guide", "target": "docs/guides/osint-research.md", "relation": "usage"}
+      ],
+      "related": ["capability.osint-research", "tool.osint-search", "tool.web-fetch", "tool.web-crawl"],
+      "direct_callable": false
+    },
     {
       "id": "provider.ollama",
       "kind": "provider",

package/docs/guides/osint-research.md

@@ -0,0 +1,90 @@
+# Categorized OSINT research
+
+Omnius ships a local, searchable snapshot of the
+[OSINT4ALL Start.me page](https://start.me/p/L1rEYQ/osint4all). It uses the
+same compact discovery pattern as AIWG skills:
+
+1. `osint_search` ranks a small candidate set from local metadata.
+2. `osint_show` expands one exact resource.
+3. The agent explicitly selects `web_fetch`, `web_crawl`,
+   `playwright_browser`, or another appropriate tool.
+4. Research findings keep their fetched-source provenance and are
+   corroborated independently.
+
+The full catalog is never injected into the model prompt.
+
+## Catalog coverage
+
+The bundled snapshot contains:
+
+- 77 Start.me bookmark categories
+- 1,456 source placements
+- 1,446 normalized canonical resources
+- every original Start.me bookmark item ID, category, position, title, and URL
+- duplicate placements retained as provenance on the canonical resource
+- Start.me's archived HTTP result code for each resource
+
+Transient RSS stories and the world-clock widget are not bookmarks and are not
+part of the tool catalog.
+
+The generated data records the source hash and a placement hash. Tests assert
+the exact counts, contiguous source ordinals, unique bookmark IDs, duplicate
+mapping, category totals, and deterministic search behavior.
+
+## Agent usage
+
+Search by need, entity type, service, category, family, domain, or URL
+fragment:
+
+```json
+{
+  "query": "reverse image face search",
+  "family": "media",
+  "health": "live",
+  "limit": 5
+}
+```
+
+`osint_search` returns compact IDs such as `osint.268396782`. Expand only the
+candidate you intend to use:
+
+```json
+{
+  "id": "osint.268396782"
+}
+```
+
+`osint_show` returns the resource URL, aliases, category placements, access
+mode, interaction/risk guidance, and a recommended next-tool route. Both
+catalog tools are local read-only operations and make no network requests.
+
+## Health and safety semantics
+
+Catalog health is an archived Start.me link-check result. It is useful for
+routing, but it is not proof that a resource works now:
+
+- `live`: archived 2xx/3xx response
+- `restricted`: archived authentication, bot-protection, rate-limit, or
+  method-friction response
+- `dead`: archived 404/410 response
+- `unknown`: timeout, server error, nonstandard failure, or missing result
+
+The index contains public links to sensitive and dual-use resources. Discovery
+does not authorize target interaction. Active or sensitive records are labeled
+so the agent can require a legitimate purpose, applicable authorization, and
+terms/legal review before choosing a network or browser tool.
+
+## Rebuilding the snapshot
+
+Fetch or restore the Start.me page-data JSON. The bundled provenance points to
+the exact
+[2026-07-21 archived page-data snapshot](https://web.archive.org/web/20260721182214id_/https://start.me/p/L1rEYQ.json?xpv=1)
+used for this build. Then run:
+
+```bash
+node scripts/build-osint-catalog.mjs --source /path/to/L1rEYQ.json
+```
+
+The source must contain exactly 77 URL-list categories and all 1,456 source
+placements. The generator refuses partial or structurally changed inputs
+instead of silently publishing an incomplete index.

package/docs/index.md

@@ -28,6 +28,7 @@ current task.
 - [Telegram](./guides/telegram.md)
 - [Media Generation](./guides/media-generation.md)
 - [Tools And Web Search](./guides/tools-and-web-search.md)
+- [Categorized OSINT Research](./guides/osint-research.md)
 
 ## Reference
 

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "omnius",
-  "version": "1.0.594",
+  "version": "1.0.595",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omnius",
-      "version": "1.0.594",
+      "version": "1.0.595",
       "bundleDependencies": [
         "image-to-ascii"
       ],
@@ -439,9 +439,9 @@
       }
     },
     "node_modules/@hono/node-server": {
-      "version": "1.19.15",
-      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.15.tgz",
-      "integrity": "sha512-Za2ai6TLdKjUvnur+eenO6nuYYipVAEhyCAdaV8IRvmU9kK8crOZUSYvIXn72E4f8fJqyAbpcJuTsYYmZp9Deg==",
+      "version": "1.19.17",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.17.tgz",
+      "integrity": "sha512-dSneS5qhiauZWGDCeK4o695Xd9nUNjviSZCMQrj10eetr8Uln1ucn6bbphOM6UynAMMtNIzZNSpL9vnASJwrPQ==",
       "license": "MIT",
       "engines": {
         "node": ">=18.14.1"
@@ -3551,9 +3551,9 @@
       }
     },
     "node_modules/express-rate-limit": {
-      "version": "8.6.0",
-      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.6.0.tgz",
-      "integrity": "sha512-XKJXDsASUOo0LLtFwW5hCcQGH0N4WQc/Rn8/Pvoia+TJFOkkFPvrtW9lZOeeNcxQJspvOIERMwiRLsVFlhHEkA==",
+      "version": "8.6.1",
+      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.6.1.tgz",
+      "integrity": "sha512-0D493aP61w0TJ2A0wy27riRsO7FMQ7FK+KUHOKCSfPvYo0R55aiC6emCVgFUeShH0fq0ICPVzNcgoS+BsbXQCA==",
       "license": "MIT",
       "dependencies": {
         "debug": "^4.4.3",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omnius",
-  "version": "1.0.594",
+  "version": "1.0.595",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/library.js",
@@ -159,5 +159,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## 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 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.\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| 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| `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"
+  "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## 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| 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| `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"
 }

package/prompts/agentic/system-large.md

@@ -34,6 +34,7 @@ When a relevant available workflow or skill applies, inspect and follow it befor
 - Search or inspect narrowly before broad exploration. Combine independent read-only checks when the tools support it, but keep mutations deliberate and scoped.
 - Before changing an existing file, obtain fresh authoritative target evidence and use the tracked edit tool. Do not bypass stale-hash or edit guards with shell rewrites.
 - Treat tool results as evidence. A successful command proves only the result it reports; verify the requested end state before claiming it.
+- For OSINT or sustained external research, first use `osint_search` for a compact ranked shortlist and `osint_show` for one selected record. Then choose a web tool explicitly. Catalog health is archived routing metadata, not source evidence; preserve fetched-source provenance and corroborate material claims.
 
 ## Ground truth
 

package/prompts/agentic/system-medium.md

@@ -34,6 +34,7 @@ When a relevant available workflow or skill applies, inspect and follow it befor
 - Search or inspect narrowly before broad exploration. Combine independent read-only checks when the tools support it, but keep mutations deliberate and scoped.
 - Before changing an existing file, obtain fresh authoritative target evidence and use the tracked edit tool. Do not bypass stale-hash or edit guards with shell rewrites.
 - Treat tool results as evidence. A successful command proves only the result it reports; verify the requested end state before claiming it.
+- For OSINT or sustained external research, first use `osint_search` for a compact ranked shortlist and `osint_show` for one selected record. Then choose a web tool explicitly. Catalog health is archived routing metadata, not source evidence; preserve fetched-source provenance and corroborate material claims.
 
 ## Ground truth
 

package/prompts/agentic/system-small.md

@@ -34,6 +34,7 @@ When a relevant available workflow or skill applies, inspect and follow it befor
 - Search or inspect narrowly before broad exploration. Combine independent read-only checks when the tools support it, but keep mutations deliberate and scoped.
 - Before changing an existing file, obtain fresh authoritative target evidence and use the tracked edit tool. Do not bypass stale-hash or edit guards with shell rewrites.
 - Treat tool results as evidence. A successful command proves only the result it reports; verify the requested end state before claiming it.
+- For OSINT or sustained external research, first use `osint_search` for a compact ranked shortlist and `osint_show` for one selected record. Then choose a web tool explicitly. Catalog health is archived routing metadata, not source evidence; preserve fetched-source provenance and corroborate material claims.
 
 ## Ground truth