{
  "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"]}
  ]
}