# Design overview

Yoi is organized around one rule: durable authority must live in explicit records, while runtime conveniences remain reconstructable hints.

That rule shapes the crate split. The runtime can restart, attach, compact, or delegate work without relying on hidden controller state, and developer tooling can inspect the records that explain why an agent acted.

## Core layers

- `yoi` owns the product CLI and top-level command shape. It is the façade that wires profile selection, memory linting, and normal TUI launch.
- `pod` turns a `Worker` into a named runtime entity with scope, session persistence, protocol handling, tools, and Pod metadata integration.
- `llm-worker` owns model-facing turns: history append, retries, continuation, pruning/compaction mechanics, tool loops, and provider-independent callbacks.
- `session-store` owns replayable append-only conversation/session logs.
- `pod-store` owns current Pod metadata keyed by Pod name.
- `protocol` defines the socket message boundary between clients and Pods.
- `client` contains reusable one-shot socket/runtime-command mechanics so lower crates do not depend on the product CLI.
- `manifest` resolves Profiles, Manifests, model/provider references, scopes, prompts, and tool permission policy into a runtime contract.
- `tools` implements built-in tools with bounded output and policy-aware execution.
- `memory` owns generated memory, Knowledge records, linting, staging, and audit observations.
- `tui` is a UI over Pod authority; it should not invent durable state.

## Why these boundaries exist

The Worker should not know process identity, Pod names, live sockets, spawned children, or UI state. It should know how to run an LLM turn over committed history and tools.

The Pod should not make provider-specific wire decisions. It coordinates runtime identity, persistence, scope, and protocol delivery around a Worker.

The TUI should not be an alternate source of truth. It may queue local input, show optimistic affordances, and render snapshots, but durable state comes from Pod/session records.

The CLI should own product command shape. Other crates should expose library APIs and typed runtime commands rather than re-parsing product arguments.

## Documentation boundary

Design docs explain the constraints that code must preserve. They should not duplicate every public type, exact schema field, or command output; those are owned by code, tests, and work items.