# Architecture Overview

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.
- CLI: one-shot tasks and operational commands.
- REST daemon: HTTP/WebSocket API for automation, GUI, CI, voice, and remote clients.
- Tool runtime: file, shell, browser, memory, media, MCP, Telegram, and P2P tools.
- Model routing: local Ollama, managed Ollama pool, vLLM, OpenAI-compatible endpoints, sponsors, and COHERE peers.
- Memory and context: session context, scoped Telegram persona state, failure records, episodes, and skill indexes.

## Agent Loop

The agent loop assembles task context, chooses tools, executes them through policy gates, observes raw output, and iterates until task completion or interruption.

Steering input should enter through an intake layer that interprets the new requirement relative to the active trajectory before interleaving it with the next model turn.

## Skills And Docs

Omnius discovers skills from AIWG roots, project `.aiwg/skills`, project-local AIWG bundles, and `.omnius/skills`. Docs that should be available to agents should be exposed as small skills that point to structured docs rather than dumping whole manuals into context.

## P2P Mesh

Sponsor and COHERE capabilities use the Nexus/libp2p layer to discover peers, route capacity, exchange usage signals, and expose selected models or media modalities.

## REST Contract

The canonical API contract is generated from `packages/cli/src/api/openapi.ts`. Human docs summarize and explain the contract, but automation should validate against the source.