omnius 1.0.607 → 1.0.609

package/docs/architecture/agent-system-map.md

@@ -0,0 +1,176 @@
+# Omnius Agent System Map
+
+Use this page when you need to understand how a user-visible behavior travels
+through Omnius, where its state lives, and which package owns a change. For a
+specific task recipe, search the generated catalog first:
+
+```bash
+omnius discover "<desired outcome>"
+omnius show workflow.choose-entrypoint
+omnius show layer.<name>
+omnius show module.<name>
+```
+
+## Entrypoint Decision
+
+| Caller needs | Entrypoint | Lifecycle | State owner |
+| --- | --- | --- | --- |
+| Human conversation and slash commands | `omnius` | foreground TUI | selected project + global config |
+| One synchronous shell task | `omnius "<task>"` | foreground process | selected project |
+| Stateful service conversation | `POST /v1/chat` | daemon session | selected project chat session |
+| OpenAI-compatible completion | `POST /v1/chat/completions` | request; optional agent loop | request or selected session |
+| Long autonomous task | `POST /v1/run` | asynchronous run ID + events | project run/session stores |
+| One safe direct tool | declared `POST /v1/tools/{name}/call` | request | tool-specific |
+| Browser GUI | daemon dashboard | browser + daemon | active workspace registry |
+| Desktop health/update control | `omnius indicator`, `/indicator` | tray + daemon | global runtime |
+| Remote messaging | Telegram gateway | gateway + daemon/TUI engines | scoped Telegram session |
+
+A slash command does not automatically have a REST route. A tool schema does
+not automatically imply direct-call exposure. Read the command `surfaces` or
+tool `direct_callable` field first.
+
+## Request And Evidence Flow
+
+```text
+TUI / CLI / REST / Dashboard / Tray / Telegram
+                       |
+                       v
+          intake + version/auth/scope gates
+                       |
+             +---------+----------+
+             |                    |
+      chat/session path     asynchronous run path
+             |                    |
+             +------ AgenticRunner+
+                       |
+       prompt + context + memory + code retrieval
+                       |
+              provider/model backend
+                       |
+                 tool requests
+                       |
+          execution policy + tool runtime
+                       |
+             observation/evidence ledgers
+                       |
+      events + action tree + status + final result
+```
+
+The orchestration loop must retain a substantive frontier between turns.
+Context compaction may summarize history, but it must not erase the current
+task, inspected evidence, completed actions, unresolved blockers, or next
+verification. Repeated reads without new evidence point to the context,
+trajectory checkpoint, or run-frontier contracts—not to a need for more reads.
+
+## Layer Map
+
+| Layer ID | Owns | First source to inspect |
+| --- | --- | --- |
+| `layer.discovery` | catalog, bootstrap, init guidance, docs skills | `scripts/generate-discovery.mjs` |
+| `layer.interface` | CLI/TUI, REST, dashboard, tray, Telegram | `packages/cli/src` |
+| `layer.orchestration` | agent loop, task/run lifecycle, completion and recovery | `packages/orchestrator/src` |
+| `layer.inference` | provider descriptors, endpoint/model routing | `packages/backend-vllm/src` |
+| `layer.execution` | tools, schemas, security and exposure | `packages/execution/src` |
+| `layer.context` | prompts, context admission/compaction, token budgets | `packages/prompts/src`, orchestrator context modules |
+| `layer.memory` | sessions, episodes, temporal memory, maintenance | `packages/memory/src`, CLI session adapters |
+| `layer.code-intelligence` | index, code graph, repository retrieval | `packages/indexer/src`, `packages/retrieval/src` |
+| `layer.media` | ASR, TTS, voice, vision, generated media | execution ASR/media + CLI voice runtime |
+| `layer.persistence` | project/global state and precedence | CLI config/project state + model store |
+| `layer.observability` | events, action tree, metrics, evidence/debug artifacts | orchestrator ledgers + CLI projections |
+| `layer.security` | auth/scopes, secret boundaries, tool and hardware policy | REST auth + execution classifier |
+| `layer.operations` | daemon, indicator, updates, install, publish | CLI daemon/update/tray + scripts |
+| `layer.contracts` | schemas, OpenAPI, registries, compatibility | schemas package + metadata registries |
+
+Run `omnius show layer.<name>` for a compact description and source-of-truth
+list. Run `omnius discover --kind module "<behavior>"` to locate package
+ownership without scanning every package.
+
+## Workspace Packages
+
+| Package | Responsibility | Depends on |
+| --- | --- | --- |
+| `@omnius/cli` | all public surfaces and runtime adapters | backend, execution, memory, orchestrator, retrieval, schemas |
+| `@omnius/orchestrator` | long-horizon agent control | backend, execution, memory, retrieval, schemas |
+| `@omnius/execution` | executable tools and policy | schemas and external runtimes |
+| `@omnius/backend-vllm` | inference protocols/providers | transport dependencies |
+| `@omnius/prompts` | system/task prompt loading | prompt artifacts |
+| `@omnius/memory` | persistent episodic/temporal memory | storage dependencies |
+| `@omnius/indexer` | code graph/index construction | schemas/storage |
+| `@omnius/retrieval` | repository retrieval | index/schema contracts |
+| `@omnius/schemas` | shared wire/domain types | no higher Omnius layer |
+
+The generated `module.*` entries are derived from workspace package manifests,
+so they remain the machine-readable ownership map.
+
+## State And Storage
+
+| Scope | Root | Examples | Do not put here |
+| --- | --- | --- | --- |
+| Project | `<project>/.omnius` | sessions, task/run artifacts, project context, indexes, project memory/skills/preferences | shared weights, global credentials, daemon identity |
+| User global | `~/.omnius` | global config/credentials, daemon/update state, managed Python environments, shared model/media store, workspace registry | project chat/task history |
+| Published package | installed `omnius` package | compiled runtime, docs catalog, templates/assets | mutable user/project state |
+
+Before reading project state, resolve the dashboard/TUI active workspace.
+Before reading global config, apply secret-redaction rules. Never use the
+current shell directory as a substitute for an explicitly selected project
+when the caller supplied one.
+
+## Canonical Registries
+
+| Surface | Registry/source of truth | Live proof |
+| --- | --- | --- |
+| Slash commands | `packages/cli/src/tui/command-registry.ts` | `GET /v1/commands` for REST-exposed commands |
+| REST | `packages/cli/src/api/openapi.ts` | `GET /openapi.json` |
+| Providers | `packages/backend-vllm/src/providerRegistry.ts` | provider/model status routes |
+| Tools | execution classes + tool manifest + direct registry | `GET /v1/tools`, `GET /v1/tools/{name}` |
+| ASR | `packages/execution/src/asr/registry.ts` | `GET /v1/asr/engines`, `/status` |
+| Discovery | `agent-map.json` + generated sources | `GET /v1/discovery/bootstrap`, `/v1/discovery` |
+| Package/runtime identity | package metadata + boot provenance | `GET /version` |
+
+Static discovery tells an agent what Omnius declares. Live registries tell it
+what the running installation currently exposes and has ready. Listing static
+discovery must never install dependencies, load models, or execute probes.
+
+## Change Recipes
+
+### Add or change a slash command
+
+1. Update the command registry metadata and the execution dispatcher.
+2. Set implementation status, exact surfaces, aliases, and every safety flag.
+3. Add command-registry and dispatcher tests, including blocked surfaces.
+4. Regenerate slash-command docs and discovery.
+
+### Add or change a REST route
+
+1. Define method, auth, input, output, errors, and operation summary in OpenAPI.
+2. Implement the route with matching version/auth/policy gates.
+3. Add route tests for success, validation, auth, and failure behavior.
+4. Regenerate discovery; every OpenAPI path/method is cataloged automatically.
+
+### Add or change a tool
+
+1. Implement the executable and schema in `@omnius/execution`.
+2. Classify side effects, risk, off-device behavior, and default exposure.
+3. Add direct-call registration only when isolated invocation is intentional.
+4. Test both metadata and execution; regenerate discovery.
+
+### Add or change a provider
+
+1. Add one descriptor with protocol, auth, paths, capabilities, and URL match.
+2. Add transport/normalization tests and fail-closed unknown-provider tests.
+3. Update configuration and provider guide only where the public workflow changes.
+4. Regenerate discovery from the source registry—never from stale `dist/`.
+
+## Debug Order
+
+1. Capture the exact request/command, expected and actual output, project,
+   timestamp, installed package version, and daemon version.
+2. Check `/health`, `/health/ready`, `/version`, port/PID ownership, then the
+   exact live registry/OpenAPI contract.
+3. Inspect run/session events and verify the correct project/global state root.
+4. Expand `workflow.debug-runtime`, the implicated `layer.*`, and `module.*`.
+5. Patch the source owner, run the smallest regression tests, regenerate
+   discovery, and reproduce the original path through terminal verification.
+
+Do not begin with broad cache deletion, process killing, reinstalling, or model
+loading. Those actions destroy evidence or can affect unrelated runtimes.

package/docs/architecture/overview.md

@@ -2,6 +2,11 @@
 
 Omnius combines a terminal-first agent loop, REST daemon, model routing layer, tool runtime, persistent context, and peer mesh.
 
+For package ownership, runtime boundaries, state scopes, canonical registries,
+change recipes, and agent-oriented failure tracing, use the
+[Agent System Map](./agent-system-map.md). The generated discovery equivalents
+are `layer.*`, `module.*`, `runtime.*`, and `store.*` entries.
+
 ## Main Surfaces
 
 - TUI: interactive control plane and task interface.

package/docs/discovery/agent-map.json

@@ -0,0 +1,119 @@
+{
+  "schema_version": "2.0.0",
+  "bootstrap": {
+    "strategy": [
+      "Identify the caller and intent, then search instead of guessing a command, route, tool, provider, or file.",
+      "Expand one stable ID and read its use/avoid conditions, exact interfaces, safety data, workflow, failure recovery, and source of truth.",
+      "For live work, compare the installed package and daemon at GET /version, then inspect GET /openapi.json and the relevant live registry.",
+      "Choose one execution surface, send X-Omnius-Min-Version for mutating or model-backed requests, and preserve the project/global state boundary.",
+      "Verify the observable result described by the entry; do not equate an accepted or queued request with completion."
+    ],
+    "start_here": [
+      "overview",
+      "layer.interface",
+      "layer.orchestration",
+      "workflow.choose-entrypoint",
+      "store.project",
+      "store.global",
+      "workflow.debug-runtime"
+    ],
+    "agent_profiles": {
+      "small-context": ["overview", "workflow.choose-entrypoint", "workflow.debug-runtime"],
+      "coding-agent": ["layer.architecture", "layer.orchestration", "layer.execution", "store.project", "workflow.extend-omnius"],
+      "service-integrator": ["runtime.daemon", "workflow.async-agent-run", "workflow.stateful-chat", "workflow.direct-tool-call"],
+      "operator": ["layer.operations", "runtime.daemon", "runtime.tray", "workflow.daemon-tray-update"],
+      "maintainer": ["layer.contracts", "layer.observability", "workflow.extend-omnius", "workflow.publish-package"]
+    },
+    "common_intents": [
+      {"intent": "Choose CLI, TUI, REST chat, REST run, or a direct tool", "query": "which entrypoint should I use", "expand": "workflow.choose-entrypoint"},
+      {"intent": "Run a long coding task asynchronously", "query": "long horizon coding REST run poll cancel", "expand": "workflow.async-agent-run"},
+      {"intent": "Understand where state is stored", "query": "project global state sessions memory config", "expand": "store.project"},
+      {"intent": "Use web search", "query": "web search tool exposure agent bound", "expand": "workflow.agent-bound-tools"},
+      {"intent": "Debug a stale or unhealthy daemon", "query": "daemon version port logs health debug", "expand": "workflow.debug-runtime"},
+      {"intent": "Add or change Omnius code", "query": "module ownership extend command endpoint tool", "expand": "workflow.extend-omnius"}
+    ],
+    "live_checks": [
+      "GET /version — package, boot, API, and discovery schema identity",
+      "GET /health and GET /health/ready — liveness and dependency readiness",
+      "GET /openapi.json — exact methods, auth, request, and response schemas",
+      "GET /v1/tools — live tool exposure and availability",
+      "GET /v1/asr/status and GET /v1/voice/status — active media engines"
+    ],
+    "safety_rules": [
+      "A TUI slash command is not a REST command unless its discovery surfaces.rest field is true.",
+      "A listed tool is not directly callable unless direct_callable is true and a rest-call interface is present.",
+      "Never expose secrets from configuration, logs, state files, discovery output, or URLs.",
+      "Never load a model or send inference before satisfying the workspace hardware preflight policy.",
+      "Never treat queued, accepted, or process-started as verified completion."
+    ]
+  },
+  "entries": [
+    {
+      "id": "overview",
+      "kind": "capability",
+      "title": "Omnius agent bootstrap",
+      "summary": "The canonical first stop for discovering Omnius by intent, choosing the correct surface, locating ownership and state, and verifying live behavior without guessing.",
+      "aliases": ["omnius", "help", "start here", "capabilities", "agent bootstrap"],
+      "keywords": ["discover", "architecture", "workflow", "runtime", "state", "ownership"],
+      "maturity": "stable",
+      "layer": "discovery",
+      "audiences": ["small-context-agent", "coding-agent", "integrator", "operator", "user"],
+      "use_when": ["You do not yet know which Omnius surface, layer, module, or workflow owns a task"],
+      "interfaces": [
+        {"type": "cli", "target": "omnius discover \"<intent>\""},
+        {"type": "cli", "target": "omnius show <stable-id>"},
+        {"type": "http", "target": "GET /v1/discovery/bootstrap"},
+        {"type": "http", "target": "GET /v1/discovery?q=<intent>"},
+        {"type": "file", "target": "docs/DISCOVERY.json"}
+      ],
+      "workflow": [
+        {"step": "1", "action": "Search using the desired outcome, not an assumed implementation name.", "interface": "omnius discover \"<intent>\"", "expected": "A short ranked list of stable IDs"},
+        {"step": "2", "action": "Expand one ID and inspect interfaces, safety, state, verification, and references.", "interface": "omnius show <stable-id>", "expected": "An actionable entry with source-of-truth links"},
+        {"step": "3", "action": "If a daemon is involved, verify its version and live contract before execution.", "interface": "GET /version and GET /openapi.json", "expected": "The running service matches the required package and route contract"}
+      ],
+      "verification": [{"check": "Expand workflow.choose-entrypoint", "expected": "A decision table for all supported public surfaces"}],
+      "failure_modes": [{"symptom": "Search is noisy or finds an internal note first", "likely_cause": "The query is too generic", "recovery": "Filter by kind or expand one layer/workflow ID from the bootstrap list"}],
+      "source_of_truth": ["docs/discovery/agent-map.json", "docs/DISCOVERY.json", "packages/cli/src/discovery.ts"]
+    },
+
+    {"id":"layer.discovery","kind":"layer","title":"Discovery and onboarding","summary":"Stable IDs, bootstrap profiles, task workflows, generated catalogs, package guidance, and live discovery endpoints that let agents navigate Omnius without prior repository knowledge.","aliases":["discovery"],"keywords":["bootstrap","catalog","docs"],"maturity":"stable","audiences":["all-agents"],"interfaces":[{"type":"cli","target":"omnius discover"},{"type":"http","target":"GET /v1/discovery/bootstrap"}],"source_of_truth":["scripts/generate-discovery.mjs","docs/discovery/agent-map.json","packages/cli/src/discovery.ts"]},
+    {"id":"layer.architecture","kind":"layer","title":"Architecture and ownership","summary":"The process, package, dependency, and data-flow map that connects public interfaces to their source owners and runtime boundaries.","aliases":["system map","ownership"],"keywords":["packages","modules","data flow"],"maturity":"stable","audiences":["coding-agent","maintainer"],"interfaces":[{"type":"guide","target":"docs/architecture/agent-system-map.md"}],"source_of_truth":["docs/architecture/agent-system-map.md","pnpm-workspace.yaml"]},
+    {"id":"layer.interface","kind":"layer","title":"Interfaces","summary":"The TUI, one-shot CLI, REST daemon, dashboard, tray indicator, Telegram gateway, and JavaScript library through which users and agents enter Omnius.","aliases":["surface","UI","REST"],"keywords":["cli","tui","dashboard","tray","telegram"],"maturity":"stable","audiences":["user","integrator","coding-agent"],"interfaces":[{"type":"module","target":"module.cli"}],"source_of_truth":["packages/cli/src/index.ts","packages/cli/src/api/serve.ts","packages/cli/src/api/openapi.ts"]},
+    {"id":"layer.orchestration","kind":"layer","title":"Agent orchestration","summary":"Long-horizon task intake, planning, agent/tool turns, sub-agents, completion contracts, trajectory checkpoints, recovery, and run lifecycle.","aliases":["agent loop","runner"],"keywords":["long horizon","run","task","subagent","verification"],"maturity":"stable","audiences":["coding-agent","maintainer","integrator"],"interfaces":[{"type":"module","target":"module.orchestrator"},{"type":"http","target":"POST /v1/run"}],"source_of_truth":["packages/orchestrator/src/agenticRunner.ts","packages/orchestrator/src/agent-operating-contract.ts"]},
+    {"id":"layer.inference","kind":"layer","title":"Inference and provider routing","summary":"Provider descriptors, endpoint protocol selection, model routing, local Ollama/vLLM, hosted APIs, sponsor capacity, and compatibility translation.","aliases":["models","providers","backend"],"keywords":["ollama","vllm","openai","anthropic","gemini"],"maturity":"stable","audiences":["integrator","operator","coding-agent"],"interfaces":[{"type":"module","target":"module.backend-vllm"},{"type":"http","target":"GET /v1/models"}],"source_of_truth":["packages/backend-vllm/src/providerRegistry.ts","packages/backend-vllm/src/backendFactory.ts"]},
+    {"id":"layer.execution","kind":"layer","title":"Tool execution and policy","summary":"Executable tools, schemas, security classification, direct versus agent-bound exposure, MCP/custom tools, mutation contracts, and shell/file/browser boundaries.","aliases":["tools","MCP"],"keywords":["tool policy","security","direct call"],"maturity":"stable","audiences":["coding-agent","integrator","maintainer"],"interfaces":[{"type":"module","target":"module.execution"},{"type":"http","target":"GET /v1/tools"}],"source_of_truth":["packages/execution/src/index.ts","packages/execution/src/tools/tool-manifest.ts","packages/cli/src/api/direct-tool-registry.ts"]},
+    {"id":"layer.context","kind":"layer","title":"Prompts and context engineering","summary":"System prompts, task templates, context compilation, admission, compaction, dumps, history sanitation, token budgeting, and working-context recovery.","aliases":["context","prompts","compaction"],"keywords":["token budget","history","prompt"],"maturity":"stable","audiences":["coding-agent","maintainer"],"interfaces":[{"type":"module","target":"module.prompts"}],"source_of_truth":["packages/prompts/src","packages/orchestrator/src/context-compiler.ts","packages/orchestrator/src/context-admission.ts"]},
+    {"id":"layer.memory","kind":"layer","title":"Memory and sessions","summary":"Project sessions, episodes, temporal graph memory, maintenance, summaries, task continuity, and explicit separation between conversational history and slash-command control input.","aliases":["sessions","history","temporal graph"],"keywords":["memory","chat history","episodes"],"maturity":"stable","audiences":["coding-agent","integrator","maintainer"],"interfaces":[{"type":"module","target":"module.memory"}],"source_of_truth":["packages/memory/src","packages/cli/src/api/chat-session.ts","packages/cli/src/tui/project-context.ts"]},
+    {"id":"layer.code-intelligence","kind":"layer","title":"Code intelligence","summary":"Repository indexing, symbol and code graph storage, retrieval, repository context, and evidence-directed navigation used by coding agents.","aliases":["indexer","retrieval","code graph"],"keywords":["symbols","repository","search"],"maturity":"stable","audiences":["coding-agent","maintainer"],"interfaces":[{"type":"module","target":"module.indexer"},{"type":"module","target":"module.retrieval"}],"source_of_truth":["packages/indexer/src","packages/retrieval/src"]},
+    {"id":"layer.media","kind":"layer","title":"Voice, ASR, TTS, vision, and media","summary":"ASR engine registry and managed weights, TTS/voice cloning, realtime voicechat, live sensors, vision, and image/video/audio generation backed by shared model storage.","aliases":["voice","ASR","TTS","vision"],"keywords":["transcription","speech","media","VibeVoice"],"maturity":"stable","audiences":["user","integrator","operator","coding-agent"],"interfaces":[{"type":"http","target":"GET /v1/asr/engines"},{"type":"http","target":"POST /v1/voice/tts"}],"source_of_truth":["packages/execution/src/asr","packages/cli/src/api/voice-runtime.ts","packages/cli/src/tui/voice.ts"]},
+    {"id":"layer.persistence","kind":"layer","title":"Persistence and state scopes","summary":"Project-local .omnius state, user-global ~/.omnius state, shared model/runtime caches, configuration precedence, and the rules preventing cross-project leakage.","aliases":["state","storage",".omnius"],"keywords":["project","global","cache","config"],"maturity":"stable","audiences":["all-agents"],"interfaces":[{"type":"store","target":"store.project"},{"type":"store","target":"store.global"}],"source_of_truth":["packages/cli/src/tui/omnius-directory.ts","packages/cli/src/config.ts"]},
+    {"id":"layer.observability","kind":"layer","title":"Observability and evidence","summary":"Action trees, run events, status, metrics, context dumps, logs, evidence and verification ledgers, debug artifacts, and UI projections for proving what happened.","aliases":["logs","metrics","action tree"],"keywords":["events","verification","debug"],"maturity":"stable","audiences":["operator","coding-agent","maintainer"],"interfaces":[{"type":"http","target":"GET /v1/runs/{id}/events"},{"type":"http","target":"GET /metrics"}],"source_of_truth":["packages/orchestrator/src/evidenceLedger.ts","packages/orchestrator/src/verification-ledger.ts","packages/cli/src/tui/action-tree.ts"]},
+    {"id":"layer.security","kind":"layer","title":"Security and trust boundaries","summary":"Authentication, REST scopes, secret handling, tool risk and mutation policy, remote access, hardware preflight, AIMS controls, and fail-closed execution gates.","aliases":["auth","policy","AIMS"],"keywords":["secrets","scopes","hardware gate"],"maturity":"stable","audiences":["operator","integrator","maintainer"],"interfaces":[{"type":"guide","target":"docs/operations/security-and-remote-access.md"}],"source_of_truth":["docs/reference/auth-map.md","packages/execution/src/tools/security-classifier.ts","packages/cli/src/api/runtime-keys.ts","packages/cli/src/api/serve.ts"]},
+    {"id":"layer.operations","kind":"layer","title":"Runtime operations","summary":"Daemon lifecycle and port ownership, tray indicator, update and restart verification, schedulers, installation, runtime dependencies, packaging, and publish staging.","aliases":["daemon","updates","install"],"keywords":["service","tray","npm","publish"],"maturity":"stable","audiences":["operator","maintainer","coding-agent"],"interfaces":[{"type":"runtime","target":"runtime.daemon"},{"type":"runtime","target":"runtime.tray"}],"source_of_truth":["packages/cli/src/daemon.ts","packages/cli/src/update-service.ts","packages/cli/src/tray.ts","scripts/build-publish.mjs"]},
+    {"id":"layer.contracts","kind":"layer","title":"Contracts and schemas","summary":"Shared TypeScript schemas, OpenAPI, command/tool/provider registries, version preconditions, and generated documentation that keep surfaces consistent.","aliases":["schemas","OpenAPI","registries"],"keywords":["contract","version","types"],"maturity":"stable","audiences":["integrator","maintainer","coding-agent"],"interfaces":[{"type":"module","target":"module.schemas"},{"type":"http","target":"GET /openapi.json"}],"source_of_truth":["packages/schemas/src","packages/cli/src/api/openapi.ts","packages/cli/src/tui/command-registry.ts"]},
+    {"id":"layer.documentation","kind":"layer","title":"Documentation","summary":"User, operator, integrator, and maintainer explanations linked from the generated discovery graph and deployable AIWG skills.","aliases":["docs","guides"],"keywords":["reference","skill","VitePress"],"maturity":"stable","audiences":["all-agents"],"interfaces":[{"type":"file","target":"docs/index.md"}],"source_of_truth":["docs",".aiwg/addons/omnius-docs"]},
+
+    {"id":"runtime.tui","kind":"runtime","title":"Interactive TUI","summary":"Foreground terminal control plane for chat, tasks, slash commands, action trees, media, setup, and operator confirmation.","aliases":["omnius interactive"],"keywords":["terminal","chat"],"maturity":"stable","layer":"interface","interfaces":[{"type":"cli","target":"omnius"}],"state":{"project":"<project>/.omnius","global":"~/.omnius"},"source_of_truth":["packages/cli/src/tui/interactive.ts","packages/cli/src/tui/commands.ts"]},
+    {"id":"runtime.one-shot","kind":"runtime","title":"One-shot CLI task","summary":"Foreground single-task agent execution from a shell, suitable when the caller can wait for completion and consume terminal output.","aliases":["one shot"],"keywords":["CLI","task"],"maturity":"stable","layer":"orchestration","interfaces":[{"type":"cli","target":"omnius \"<task>\""}],"source_of_truth":["packages/cli/src/index.ts","packages/cli/src/commands/run.ts"]},
+    {"id":"runtime.daemon","kind":"runtime","title":"REST daemon","summary":"Long-running HTTP/WebSocket service, normally on 127.0.0.1:11435, that owns automation, dashboard, chat/run, tool, voice, media, update, and health routes.","aliases":["service","port 11435"],"keywords":["REST","HTTP","websocket"],"maturity":"stable","layer":"operations","interfaces":[{"type":"cli","target":"omnius daemon"},{"type":"http","target":"GET /version"}],"verification":[{"check":"GET /health and GET /version","expected":"Healthy response and the intended installed package version"}],"failure_modes":[{"symptom":"Port 11435 is occupied by an old runtime","likely_cause":"Stale daemon ownership","recovery":"Use the documented daemon start/reclaim flow; verify the new PID and /version rather than killing unrelated processes"}],"source_of_truth":["packages/cli/src/daemon.ts","packages/cli/src/api/serve.ts"]},
+    {"id":"runtime.dashboard","kind":"runtime","title":"Dashboard","summary":"Browser UI served by the daemon for projects, chats, runs, activity, voice/media, settings, updates, and observability.","aliases":["web UI"],"keywords":["browser","GUI"],"maturity":"stable","layer":"interface","interfaces":[{"type":"http","target":"GET /"}],"source_of_truth":["packages/cli/src/api/web-ui.ts"]},
+    {"id":"runtime.tray","kind":"runtime","title":"System tray indicator","summary":"Desktop status and update control registered through the host tray implementation, focused on Ubuntu/Linux and linked to daemon readiness.","aliases":["indicator"],"keywords":["tray","desktop","Ubuntu"],"maturity":"stable","layer":"operations","interfaces":[{"type":"cli","target":"omnius indicator"},{"type":"tui","target":"/indicator"}],"verification":[{"check":"Run indicator status after startup","expected":"Tray readiness and daemon online state are both reported"}],"source_of_truth":["packages/cli/src/tray.ts","packages/cli/src/tui/indicator-command.ts"]},
+    {"id":"runtime.telegram","kind":"runtime","title":"Telegram gateway","summary":"Scoped external chat/control bridge with its own authentication, command exposure, persona/session state, and observability.","aliases":["bot"],"keywords":["gateway","remote"],"maturity":"stable","layer":"interface","interfaces":[{"type":"tui","target":"/telegram"}],"source_of_truth":["packages/cli/src/tui/telegram-bridge.ts","docs/guides/telegram.md"]},
+    {"id":"runtime.model-workers","kind":"runtime","title":"Model and media workers","summary":"External local processes and managed Python environments used for inference, ASR, TTS, and generated media; their real hardware placement must be verified before live inference.","aliases":["workers","venv"],"keywords":["GPU","Python","Ollama"],"maturity":"stable","layer":"inference","safety":{"hardware_preflight_required":true},"source_of_truth":["packages/execution/src/asr","packages/execution/src/transcribe-python-runtime.ts","packages/cli/src/api/voice-runtime.ts"]},
+
+    {"id":"store.project","kind":"store","title":"Project-local state","summary":"State scoped to one workspace under <project>/.omnius, including sessions, task/run artifacts, project context, indexes, memories, skills, and UI preferences where applicable.","aliases":[".omnius","workspace state"],"keywords":["sessions","project","memory"],"maturity":"stable","layer":"persistence","audiences":["all-agents"],"use_when":["Reading or changing state that must follow the active workspace"],"avoid_when":["Storing machine-wide credentials, shared model weights, or global runtime installations"],"interfaces":[{"type":"filesystem","target":"<project>/.omnius"}],"verification":[{"check":"Resolve the active workspace before reading or writing","expected":"The state path belongs to the intended project"}],"failure_modes":[{"symptom":"Chats, indexes, or memory appear to belong to another project","likely_cause":"The active workspace or state root was inferred incorrectly","recovery":"Resolve the project through the workspace registry and use the selected project's .omnius path"}],"source_of_truth":["packages/cli/src/tui/project-context.ts","packages/cli/src/tui/omnius-directory.ts"]},
+    {"id":"store.global","kind":"store","title":"User-global state","summary":"Machine/user-scoped Omnius state under ~/.omnius for daemon identity, global configuration and credentials, shared managed environments, model weights, media store, updates, and cross-project registries.","aliases":["~/.omnius","global state"],"keywords":["models","venv","credentials","daemon"],"maturity":"stable","layer":"persistence","audiences":["operator","coding-agent","integrator"],"use_when":["Managing runtime-wide installation, credentials, shared models, or service identity"],"avoid_when":["Persisting project conversation or task state that should not leak between workspaces"],"interfaces":[{"type":"filesystem","target":"~/.omnius"}],"safety":{"may_contain_secrets":true,"never_emit_raw_values":true},"source_of_truth":["packages/cli/src/config.ts","packages/cli/src/daemon.ts","packages/execution/src/tools/model-store.ts"]},
+
+    {"id":"workflow.choose-entrypoint","kind":"workflow","title":"Choose the correct Omnius entrypoint","summary":"Select TUI, one-shot CLI, REST chat, asynchronous run, OpenAI-compatible completion, or direct tool execution from the caller's lifecycle and state requirements.","aliases":["entrypoint decision","how to use Omnius"],"keywords":["CLI","REST","chat","run","tool"],"maturity":"stable","layer":"interface","audiences":["all-agents"],"inputs":["Desired outcome","Need for conversational state","Need for asynchronous polling/cancel","Whether a specific tool is directly callable"],"outputs":["One exact invocation surface"],"workflow":[{"step":"1","action":"Use `omnius` for interactive human control or slash commands.","interface":"omnius"},{"step":"2","action":"Use a one-shot CLI task when the shell caller can wait synchronously.","interface":"omnius \"<task>\""},{"step":"3","action":"Use /v1/chat for daemon-managed conversational sessions and /v1/chat/completions for OpenAI compatibility.","interface":"POST /v1/chat or POST /v1/chat/completions"},{"step":"4","action":"Use /v1/run for a long autonomous task that needs an ID, events, polling, and cancellation.","interface":"POST /v1/run"},{"step":"5","action":"Use /v1/tools/{name}/call only when live metadata says direct_callable=true; otherwise bind the tool to an agent loop.","interface":"GET /v1/tools/{name}"}],"verification":[{"check":"Inspect the exact interface in discovery and live OpenAPI/tool metadata","expected":"The selected surface is explicitly supported"}],"failure_modes":[{"symptom":"A guessed endpoint returns 404 or bypasses expected state","likely_cause":"The surface was inferred from a command/tool name","recovery":"Return to this workflow and inspect the exact discovery entry plus /openapi.json"}],"source_of_truth":["docs/guides/agent-integration.md","packages/cli/src/api/openapi.ts"]},
+    {"id":"workflow.async-agent-run","kind":"workflow","title":"Run a long-horizon task through REST","summary":"Create an asynchronous agent run, retain its ID, stream or poll evidence, steer/cancel when needed, and verify terminal completion.","aliases":["REST run","long horizon"],"keywords":["poll","events","cancel","agent"],"maturity":"stable","layer":"orchestration","audiences":["service-agent","integrator"],"prerequisites":["Healthy daemon","Compatible /version","Configured model/provider"],"inputs":["task","workspace","optional model and tool profile"],"outputs":["run ID","events","terminal result"],"workflow":[{"step":"1","action":"Check version/readiness and OpenAPI request schema.","interface":"GET /version; GET /health/ready; GET /openapi.json","expected":"Compatible ready service"},{"step":"2","action":"Create the run and persist the returned ID.","interface":"POST /v1/run","expected":"Accepted run record with ID"},{"step":"3","action":"Read events/status until a terminal state; use steering or cancel routes only by their documented contract.","interface":"GET /v1/runs/{id}/events and run status routes","expected":"Observable progress followed by a terminal state"},{"step":"4","action":"Verify produced changes/evidence rather than accepting the status label alone.","expected":"Requested outcome and verification evidence are present"}],"verification":[{"check":"Run state is terminal and its output/evidence satisfies the task","expected":"Completed result, or explicit recoverable failure"}],"failure_modes":[{"symptom":"Caller reports success immediately after POST /v1/run","likely_cause":"Accepted/queued was mistaken for completed","recovery":"Retain the run ID and poll/stream through terminal verification"},{"symptom":"Run uses stale code after an update","likely_cause":"Daemon was not restarted into the installed target version","recovery":"Compare GET /version with the package target before resubmitting"}],"source_of_truth":["packages/cli/src/api/openapi.ts","packages/orchestrator/src/agenticRunner.ts"]},
+    {"id":"workflow.stateful-chat","kind":"workflow","title":"Use stateful daemon chat","summary":"Create or select a real chat session, send conversational turns, and load its history without treating control commands such as /quit as chats.","aliases":["chat sessions","history"],"keywords":["session","conversation","history"],"maturity":"stable","layer":"memory","audiences":["integrator","service-agent"],"workflow":[{"step":"1","action":"List or create sessions through the documented chat/session routes.","interface":"GET /v1/chats and chat creation route"},{"step":"2","action":"Send user content through POST /v1/chat with the selected session identity.","interface":"POST /v1/chat"},{"step":"3","action":"Load message history when selecting the session and distinguish UI/control events from conversational turns.","expected":"The selected chat displays its saved conversation"}],"verification":[{"check":"Reload the selected session","expected":"History is restored and control-only commands are absent from the chat list"}],"failure_modes":[{"symptom":"Chats named quit or duplicate Last task summaries appear","likely_cause":"Control/task metadata was projected as a chat session","recovery":"Use the canonical session registry and filter non-conversational control records"}],"source_of_truth":["packages/cli/src/api/chat-session.ts","packages/cli/src/api/session-summary.ts","packages/cli/src/api/web-ui.ts"]},
+    {"id":"workflow.direct-tool-call","kind":"workflow","title":"Call a directly exposed tool","summary":"Inspect live metadata, confirm direct-call exposure and safety, submit the exact schema, and verify the tool result.","aliases":["tool REST call"],"keywords":["direct_callable","schema"],"maturity":"stable","layer":"execution","audiences":["integrator","service-agent"],"workflow":[{"step":"1","action":"Inspect the tool metadata and direct_callable flag.","interface":"GET /v1/tools/{name}","expected":"A rest-call interface is explicitly present"},{"step":"2","action":"Validate arguments against the returned parameter schema and call the exact route.","interface":"POST /v1/tools/{name}/call"},{"step":"3","action":"Inspect the structured output and any side effects.","expected":"Tool-specific verified result"}],"avoid_when":["The tool is agent-bound, unavailable, profile-gated, or lacks a rest-call interface"],"verification":[{"check":"Metadata, schema, and result all agree","expected":"No inferred route or unvalidated arguments"}],"failure_modes":[{"symptom":"Direct call returns not found or not callable","likely_cause":"The route was inferred or live exposure changed","recovery":"Re-read GET /v1/tools/{name}; use an agent-bound workflow when no rest-call interface exists"}],"source_of_truth":["packages/cli/src/api/direct-tool-registry.ts","packages/execution/src/tools/tool-manifest.ts"]},
+    {"id":"workflow.agent-bound-tools","kind":"workflow","title":"Use agent-bound tools such as web_search","summary":"Offer a non-direct tool to an Omnius agent loop through run/chat instead of inventing a direct REST call.","aliases":["web search","daemon tools"],"keywords":["agent loop","web_search","tool exposure"],"maturity":"stable","layer":"execution","audiences":["integrator","coding-agent"],"workflow":[{"step":"1","action":"Inspect live tool metadata, security classification, availability, and schema.","interface":"GET /v1/tools/web_search"},{"step":"2","action":"Offer the tool through an agent-capable surface and a compatible tool profile.","interface":"POST /v1/run or POST /v1/chat/completions with agent_loop=true"},{"step":"3","action":"Require source/provenance verification appropriate to the research task.","expected":"The agent executes the bound tool and returns evidence"}],"avoid_when":["Calling POST /v1/tools/web_search/call unless live metadata explicitly adds direct exposure"],"verification":[{"check":"Inspect run/chat tool events and returned source evidence","expected":"The intended tool actually ran and its claims are traceable"}],"failure_modes":[{"symptom":"Direct tool URL is missing","likely_cause":"The tool is intentionally agent-bound","recovery":"Use /v1/run or agent-loop chat with the tool offered"}],"source_of_truth":["docs/guides/tools-and-web-search.md","packages/execution/src/tools/web-search.ts"]},
+    {"id":"workflow.provider-selection","kind":"workflow","title":"Select an inference provider and model","summary":"Resolve an explicit provider protocol, credentials, endpoint, and model; verify live reachability and hardware placement for local inference.","aliases":["BYOI","model selection"],"keywords":["provider","endpoint","protocol"],"maturity":"stable","layer":"inference","audiences":["operator","integrator","coding-agent"],"workflow":[{"step":"1","action":"Discover and expand the provider descriptor; do not infer protocol from a label or API key."},{"step":"2","action":"Configure endpoint/protocol/credential using the documented scope."},{"step":"3","action":"For local model work, perform the required hardware preflight before any token-generating request."},{"step":"4","action":"Verify the selected provider and exact model through live metadata."}],"verification":[{"check":"Live model/provider status matches the intended endpoint, protocol, and hardware","expected":"No silent fallback"}],"failure_modes":[{"symptom":"Model listing works but inference fails or uses the wrong protocol","likely_cause":"Endpoint display label was used instead of the provider descriptor","recovery":"Resolve the stable provider ID/protocol and re-test the exact endpoint before execution"}],"source_of_truth":["packages/backend-vllm/src/providerRegistry.ts","docs/guides/bring-your-own-inference.md"]},
+    {"id":"workflow.voice-asr-tts","kind":"workflow","title":"Select and use ASR/TTS engines","summary":"Discover installed and supported ASR/TTS systems, perform managed setup when needed, activate one exact engine/model/device, and use the documented REST or TUI surface.","aliases":["speech","voice engines"],"keywords":["ASR","TTS","VibeVoice","transcribe_cli","LuxTTS"],"maturity":"stable","layer":"media","audiences":["integrator","operator","user"],"workflow":[{"step":"1","action":"List engines/models and inspect status before activation.","interface":"GET /v1/asr/engines; GET /v1/asr/status; voice model routes"},{"step":"2","action":"Run explicit managed setup for missing runtimes/weights and an exact accelerator when required."},{"step":"3","action":"Activate the selected engine/model and verify active status."},{"step":"4","action":"Transcribe or synthesize through the OpenAPI-documented route and validate the output artifact."}],"verification":[{"check":"Status reports the requested active engine/model/device and a small non-live test succeeds","expected":"No interpreter override or fallback to a different engine"}],"failure_modes":[{"symptom":"transcribe_cli is missing although a managed environment exists","likely_cause":"TRANSCRIBE_PYTHON points at an older Whisper environment","recovery":"Use the canonical managed transcribe runtime selection and re-check ASR status"}],"source_of_truth":["packages/execution/src/asr/registry.ts","packages/execution/src/transcribe-python-runtime.ts","packages/cli/src/api/voice-runtime.ts"]},
+    {"id":"workflow.daemon-tray-update","kind":"workflow","title":"Operate daemon, tray, and updates","summary":"Ensure one current daemon owns the service port, start the tray against it, install updates through the real global npm flow, stream progress, restart components, and verify the target runtime.","aliases":["update Omnius","indicator update"],"keywords":["npm global","restart","version"],"maturity":"stable","layer":"operations","audiences":["operator","coding-agent"],"workflow":[{"step":"1","action":"Read installed and running identities from /version; diagnose port ownership before restart."},{"step":"2","action":"Start/reclaim the daemon through its managed lifecycle and confirm health."},{"step":"3","action":"Start the indicator and require daemon-online state before enabling service actions."},{"step":"4","action":"Run the update service, stream its live progress, restart the daemon/indicator, and compare /version with the target."}],"verification":[{"check":"Installed package, daemon /version, and indicator version all equal the update target","expected":"Verified target runtime, not merely queued or process-started"}],"failure_modes":[{"symptom":"UI remains on updating/queued","likely_cause":"The update worker was never executed or progress was not connected","recovery":"Inspect update job status/log stream and fail explicitly if no worker owns it"},{"symptom":"Restart verification fails","likely_cause":"Old daemon retained port ownership or new runtime did not become ready","recovery":"Resolve exact port PID, preserve unrelated processes, restart, then verify /health and /version"}],"source_of_truth":["packages/cli/src/update-service.ts","packages/cli/src/update-worker.ts","packages/cli/src/daemon.ts","packages/cli/src/tray.ts"]},
+    {"id":"workflow.debug-runtime","kind":"workflow","title":"Debug an Omnius runtime failure","summary":"Diagnose from identity and ownership outward: version, health, port/process, live contract, status/events, state scope, logs/evidence, then the owning module.","aliases":["troubleshoot","root cause"],"keywords":["health","logs","failure","stale"],"maturity":"stable","layer":"observability","audiences":["all-agents"],"workflow":[{"step":"1","action":"Capture the exact command/request, expected result, actual result, workspace, package version, daemon version, and timestamp."},{"step":"2","action":"Check /health, /health/ready, /version, port ownership, and process identity before changing state."},{"step":"3","action":"Inspect /openapi.json or the command/tool/provider registry so the attempted surface is proven valid."},{"step":"4","action":"Trace status/events/logs and confirm the correct project/global state root."},{"step":"5","action":"Map the failure to a layer and module entry, patch the source owner, and run the smallest relevant regression tests."}],"verification":[{"check":"Reproduce the original path after the fix","expected":"The requested outcome succeeds and adjacent safety/version/state invariants remain true"}],"failure_modes":[{"symptom":"The same file or state is read repeatedly without progress","likely_cause":"Loop progress is not recorded or compaction removed the active evidence/frontier","recovery":"Inspect trajectory checkpoints, run frontier, context admission, and read-loop progress tests in the orchestration/context layers"}],"source_of_truth":["docs/architecture/agent-system-map.md","packages/orchestrator/src/debugArtifactLibrary.ts","packages/orchestrator/src/trajectory-checkpoint.ts"]},
+    {"id":"workflow.extend-omnius","kind":"workflow","title":"Extend or modify Omnius safely","summary":"Locate the owning layer/module and canonical registry, change the smallest source boundary, update discovery/docs/contracts, and run targeted plus freshness tests.","aliases":["add feature","change code"],"keywords":["ownership","tests","registry"],"maturity":"stable","layer":"architecture","audiences":["coding-agent","maintainer"],"workflow":[{"step":"1","action":"Search the discovery map by behavior, expand the layer and module, and inspect git status before editing."},{"step":"2","action":"Find the canonical registry/contract and every consumer; preserve unrelated dirty-worktree changes."},{"step":"3","action":"Implement with explicit state, safety, version, and error semantics."},{"step":"4","action":"Add focused regression tests and update agent map/docs when a public surface, ownership boundary, workflow, or failure mode changes."},{"step":"5","action":"Run targeted tests, discovery/docs freshness, and diff checks; leave publish/build to the authorized workflow."}],"verification":[{"check":"Targeted tests and node scripts/generate-discovery.mjs --check","expected":"Behavior and machine-readable discovery are both current"}],"failure_modes":[{"symptom":"A fix works in one surface but discovery or another consumer is stale","likely_cause":"The source registry and consumers were not traced before editing","recovery":"Expand the layer/module, enumerate registry consumers, update contract/docs/tests, and rerun freshness checks"}],"source_of_truth":["AGENTS.md","docs/architecture/agent-system-map.md","scripts/generate-discovery.mjs"]},
+    {"id":"workflow.publish-package","kind":"workflow","title":"Build and publish the Omnius package","summary":"Follow the repository Minimal Publish SOP: clean all workspaces, rebuild, bundle publish/, inspect a local-cache tarball, patch-bump, publish only from publish/, and verify npm metadata.","aliases":["npm publish","release"],"keywords":["publish","tarball","README"],"maturity":"stable","layer":"operations","audiences":["maintainer"],"prerequisites":["Node >=22","pnpm >=9","npm >=10","npm publish rights"],"workflow":[{"step":"1","action":"Follow AGENTS.md exactly and rebuild every workspace."},{"step":"2","action":"Run scripts/build-publish.mjs and work only in publish/."},{"step":"3","action":"Pack with a local npm cache; verify README, package metadata, dist files, and absence of junk."},{"step":"4","action":"Patch-bump above npm latest, publish with local cache, and verify npm metadata."}],"avoid_when":["Publishing from the repository root","Skipping the rebuild or tarball audit"],"verification":[{"check":"npm view omnius version readmeFilename and npm view omnius readme","expected":"New version and rendered README are live"}],"failure_modes":[{"symptom":"npm shows stale code, missing README, or junk artifacts","likely_cause":"Publish was run outside publish/ or without the full rebuild/bundle/audit sequence","recovery":"Deprecate the bad version, patch-bump, and repeat the Minimal Publish SOP from AGENTS.md"}],"source_of_truth":["AGENTS.md","scripts/build-publish.mjs","scripts/audit-publish-artifacts.mjs"]}
+  ]
+}

package/docs/getting-started/install.md

@@ -55,7 +55,7 @@ Agent-readable daemon entrypoints:
 ```text
 http://127.0.0.1:11435/help
 http://127.0.0.1:11435/openapi.json
-http://127.0.0.1:11435/v1/discovery
+http://127.0.0.1:11435/v1/discovery/bootstrap
 http://127.0.0.1:11435/v1/tools
 http://127.0.0.1:11435/v1/skills
 ```

package/docs/guides/agent-integration.md

@@ -5,12 +5,18 @@ provider or tool list.
 
 ## Bootstrap Sequence
 
-1. Read `GET /version` and assert the minimum compatible Omnius package
+1. Read `GET /v1/discovery/bootstrap` (or run `omnius docs`) to obtain the
+   compact strategy, start-here entries, profiles, common intents, and safety
+   invariants.
+2. Read `GET /version` and assert the minimum compatible Omnius package
    version.
-2. Read `GET /v1/discovery` or the bundled `docs/DISCOVERY.json`.
-3. Search by user intent, then expand the chosen stable ID.
-4. Follow the returned interface and reference links.
-5. For live work, send `X-Omnius-Min-Version` on execution requests.
+3. Search `GET /v1/discovery` or the bundled `docs/DISCOVERY.json` by user
+   intent, then expand one stable ID.
+4. Follow its `use_when`, `avoid_when`, exact interfaces, workflow, safety,
+   state, verification, failure recovery, and source-of-truth fields.
+5. Confirm dynamic availability through OpenAPI and the relevant live registry.
+6. For live work, send `X-Omnius-Min-Version` on execution requests and verify
+   the declared terminal result.
 
 Human and CLI equivalents:
 
@@ -29,6 +35,7 @@ omnius capabilities --json
 | `docs/DISCOVERY.md` | compact human/agent orientation |
 | `omnius discover` | ranked local lookup |
 | `omnius show` | exact entry expansion |
+| `GET /v1/discovery/bootstrap` | compact onboarding profiles and start-here map |
 | `GET /v1/discovery` | daemon lookup |
 | `GET /v1/discovery/{id}` | daemon exact entry |
 | `GET /openapi.json` | canonical HTTP wire contract |
@@ -46,8 +53,63 @@ in stored integrations. Use free text only to find an ID or handle a user's
 new intent. Exact IDs, aliases, and titles should rank above prefix and token
 matches.
 
-Supported kinds are `capability`, `provider`, `tool`, `api`, `command`,
-`skill`, `guide`, `config`, and `operation`.
+Supported kinds are `capability`, `layer`, `module`, `workflow`, `runtime`,
+`store`, `provider`, `tool`, `api`, `command`, `skill`, `guide`, `config`, and
+`operation`. Filters also accept exact `audience` and `layer` values;
+`include_internal=true` deliberately includes internal notes that are hidden
+from the default result set.
+
+## Agent Profiles
+
+| Agent | Minimum context to load |
+| --- | --- |
+| Small or constrained model | bootstrap + one `workflow.*` entry + its smallest referenced guide |
+| Coding agent | workflow + owning `layer.*` + owning `module.*` + targeted source/tests |
+| Service integrator | bootstrap + `workflow.choose-entrypoint` + exact `api.*`/tool/provider entry + live OpenAPI |
+| Operator | `layer.operations` + affected `runtime.*` + `workflow.debug-runtime` |
+| Maintainer | architecture/system map + contracts/observability layers + affected modules and freshness tests |
+
+Do not dump the complete 600+ entry catalog or whole docs tree into a small
+model. Use search to narrow, exact expansion to plan, and references to load
+only the evidence required by the current step.
+
+## Entrypoint Decision
+
+| Requirement | Surface | Completion semantics |
+| --- | --- | --- |
+| Interactive human control or user-only slash command | `omnius` | foreground TUI event |
+| One synchronous shell task | `omnius "<task>"` | process exit plus verified output |
+| Stateful daemon conversation | `POST /v1/chat` | response tied to a real chat session |
+| OpenAI client compatibility | `POST /v1/chat/completions` | one completion or SSE; optional agent loop |
+| Long task, events, steering, or cancellation | `POST /v1/run` | retain run ID until terminal verified state |
+| One isolated directly exposed tool | declared `POST /v1/tools/{name}/call` | structured tool result and side-effect check |
+
+Expand `workflow.choose-entrypoint` for executable steps. Never construct
+`/v1/commands/<name>` or `/v1/tools/<name>/call` from a display name alone.
+Command `surfaces.rest` and tool `direct_callable`/interfaces are authoritative.
+
+## Long-Run Recipe
+
+1. Check `/version`, `/health/ready`, and the `/v1/run` OpenAPI operation.
+2. Submit the task with the explicit workspace and minimum Omnius version.
+3. Persist the returned run ID. Accepted or queued is not completed.
+4. Poll status and/or consume events; retain evidence across reconnects.
+5. Steer or cancel only through documented routes and state transitions.
+6. At terminal status, inspect result artifacts and verification evidence.
+
+Expand `workflow.async-agent-run` for failure recovery and canonical sources.
+
+## State Scope
+
+- `<project>/.omnius` is project-local: conversations, sessions, tasks/runs,
+  project context, indexes, memories, and project preferences.
+- `~/.omnius` is user-global: daemon and update state, global configuration and
+  credentials, managed Python environments, shared model/media storage, and
+  the workspace registry.
+
+Resolve the active workspace before reading project state. Never return raw
+global secrets through discovery, errors, logs, URLs, or telemetry. Expand
+`store.project` or `store.global` before writing state from an integration.
 
 ## Bring Your Own Inference
 

package/docs/index.md

@@ -7,10 +7,12 @@ Omnius is an autonomous local-first agent runtime with a TUI, REST daemon, P2P s
 - [Discovery Cascade](./DISCOVERY.md)
 - [Machine Discovery Catalog](./DISCOVERY.json)
 - [Agent And Service Integration](./guides/agent-integration.md)
+- [Agent System Map](./architecture/agent-system-map.md)
 
 Agents should begin with `omnius discover "<need>"`, expand a result with
 `omnius show <id>`, and read only the referenced artifact needed for the
-current task.
+current task. Small-context agents should expand one workflow; coding agents
+should additionally expand the owning layer and module.
 
 ## Start Here
 

package/docs/reference/configuration.md

@@ -18,6 +18,10 @@ Configuration is layered from environment, global user settings, project setting
 | `OMNIUS_DAEMON` | Start in daemon mode when set to `1` |
 | `OMNIUS_FORCE_NO_THINK` | Force `think: false` for Qwen-style backends |
 | `OMNIUS_THINK_AUTO` | Enable opt-in automatic thinking mode trigger |
+| `OMNIUS_ASR_CUDA_VISIBLE_DEVICES` | Exact CUDA GPU index or UUID used for managed ASR activation; multi-device masks are rejected (Jetson's integrated GPU is `0`) |
+| `OMNIUS_VIBEVOICE_PYTHON` | Host Python used to create the VibeVoice venv; its CUDA-enabled Torch is inherited with `--system-site-packages` |
+| `OMNIUS_VIBEVOICE_ATTN` | VibeVoice attention implementation (`sdpa` by default; use a host-supported implementation) |
+| `OMNIUS_VIBEVOICE_MAX_NEW_TOKENS` | Explicit VibeVoice structured-transcript generation ceiling (default `32768`) |
 
 ## Provider Key Precedence
 
@@ -61,6 +65,12 @@ Project runtime state:
 
 User-global state may live under `~/.omnius/`, including runtime API keys and voice clone references.
 
+The persisted `asrEngine` and `asrModel` settings select one exact entry from
+the canonical ASR registry. Selection is not readiness: clients should inspect
+`GET /v1/asr/status` before treating a backend as active. Managed VibeVoice
+runtime state is stored below `~/.omnius/runtimes/asr/`; its Hugging Face
+weights use the unified model cache rather than the project or npm package.
+
 ## Auth Key Format
 
 ```text

package/docs/reference/rest-api.md

@@ -41,7 +41,8 @@ pnpm docs:check
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `/v1/discovery` | Search or list the capability catalog |
+| `GET` | `/v1/discovery/bootstrap` | Compact agent bootstrap and start-here map |
+| `GET` | `/v1/discovery` | Search layers, workflows, runtimes, modules, stores, and capabilities |
 | `GET` | `/v1/discovery/{id}` | Expand one stable capability entry |
 
 ## Inference And Chat
@@ -188,13 +189,20 @@ pnpm docs:check
 | `POST` | `/v1/voice/models/switch` | Switch and enable an exact TTS model by default |
 | `GET` | `/v1/voice/supertonic-settings` | Voice tuning settings |
 | `POST` | `/v1/voice/supertonic-settings` | Update voice tuning settings |
-| `GET` | `/v1/voice/asr-models` | ASR models |
-| `POST` | `/v1/voice/asr-models/switch` | Switch ASR model |
+| `GET` | `/v1/asr/engines` | Canonical ASR engines/models, capabilities, readiness, and selection |
+| `GET` | `/v1/asr/status` · `/v1/asr/selection` | Selected engine/model and runtime status |
+| `PATCH` | `/v1/asr/selection` | Persist and activate an exact engine/model |
+| `POST` | `/v1/asr/activate` | Activate and persist an exact engine/model |
+| `POST` | `/v1/asr/engines/{engineId}/setup` | Install a managed runtime and pinned weights |
+| `POST` | `/v1/asr/transcriptions` · `/v1/asr/test` | Transcribe/test using the real selected backend |
+| `GET` | `/v1/voice/asr-models` | Compatibility registry alias |
+| `POST` | `/v1/voice/asr-models/switch` | Compatibility activation alias |
 | `POST` | `/v1/voice/tts` | Synthesize speech |
 | `POST` | `/v1/audio/speech` | OpenAI-compatible TTS alias |
 | `POST` | `/v1/voice/transcribe` | Transcribe audio |
+| `POST` | `/v1/voice/asr` | Legacy transcription alias |
 | `POST` | `/v1/audio/transcriptions` | OpenAI-compatible transcription alias |
-| `POST` | `/v1/voice/transcribe/stream` | Streaming transcription |
+| `POST` | `/v1/voice/transcribe/stream` | Isolated final transcription over SSE (no shared mic state or fake partials) |
 | `POST` | `/v1/voice/clone-refs` | Upload voice clone reference |
 | `GET` | `/v1/voice/clone-refs` | List clone references |
 | `POST` | `/v1/voice/clone-refs/upload` | Upload clone reference |
@@ -214,6 +222,19 @@ Overwatch, `luxtts:announcer-testchamber03`, and the selected Voicebox suite.
 Set `OMNIUS_VOICEBOX_MODELS=all` for every carried-in Voicebox model, leave it
 at `stable` for the default set, or provide a comma-separated subset.
 
+ASR selection is independent from TTS selection. The registry currently exposes
+OpenAI Whisper, managed `transcribe-cli`, NVIDIA Nemotron (reported unavailable
+until its legacy bootstrap is migrated), and Microsoft VibeVoice ASR. VibeVoice
+uses the exact pinned `microsoft/VibeVoice-ASR` checkpoint, reports setup and
+activation separately, supports completed files up to 60 minutes with speakers,
+timestamps, and `?context=` hotwords, and is deliberately not advertised as an
+incremental PCM backend. Its managed setup inherits the host CUDA-enabled Torch
+build (needed on Jetson/ARM64), never installs generic PyPI Torch, and activation
+requires one explicit capable GPU. Discrete Linux uses `nvidia-smi` process/GPU
+evidence; Jetson/L4T uses NVIDIA's documented `tegrastats` plus CUDA Torch device
+properties because `nvidia-smi` is unavailable there. Model weights live under
+the unified Omnius ASR cache and are not shipped in the npm package.
+
 ## Generative Media
 
 All generation is backed by the unified `~/.omnius` model store and shared venvs (single source of truth — no per-project duplication). Generated files are consolidated into the global gallery at `~/.omnius/media/{images,videos,audio,music}`.
@@ -246,6 +267,7 @@ All generation is backed by the unified `~/.omnius` model store and shared venvs
 | `POST` | `/v1/scheduled/reconcile` | Force scheduled reconciliation |
 | `GET` | `/v1/services/systemd` | Systemd service status |
 | `GET` | `/v1/update` | Self-update status |
+| `POST` | `/v1/update` | Queue or run the package update flow |
 
 ## AIMS Governance