diff --git a/README.md b/README.md
index 83cfae4..5032631 100644
--- a/README.md
+++ b/README.md
@@ -6,10 +6,10 @@ A Go library for building agentic systems. Provides sandboxed tool execution, a
 
 ```mermaid
 graph TD
-    agent --> tools
-    agent --> backend
-    agent --> log
-    agent --> paths
+    session --> tools
+    session --> backend
+    session --> log
+    session --> paths
 
     execute --> tools
     execute --> skills
@@ -24,40 +24,32 @@ graph TD
 ## Packages
 
 ```
-agent/       Core interface, agent loop, compaction, hooks, session persistence, config loading
+session/     Session + Agent: the core runtime (loop, compaction, hooks, commands, persistence)
 backend/     Backend interface + LLM providers (Anthropic, OpenAI, Ollama, Gemini, Copilot, CodeWhisperer)
 tools/       Server/Dispatcher interfaces, tool registry, discovery, schema parsing
-execute/     Sandboxed shell execution, promoted tool dispatch, skill dispatch, remote SSH execution
+execute/     Sandboxed shell execution, promoted tool dispatch, skill dispatch, remote SSH
 detach/      Background process management (ring buffer, signal)
 skills/      Skill metadata parsing and per-session registry
-elevate/     Elevation broker (privilege escalation daemon, policy management)
+elevate/     Elevation broker (privilege escalation daemon, policy)
 sandbox/     Landrun sandbox configuration and command wrapping
 env/         Session environment helpers
 log/         Structured logger
 paths/       XDG path resolution
 ```
 
-## Primitives
+## Core concepts
 
-**`agent.Core`** — the central interface for a running agent session:
+**`session.Session`** — the public interface. A session is the runtime environment that hosts an agent. It provides identity, working directory, event bus, environment, and lifecycle management.
 
-- `Submit` — send a prompt, stream events via the bus
-- `Interrupt` — cancel the current turn
-- `Inject` — append a user interruption to the next tool result
-- `Queue`/`PopQueue` — buffered prompt FIFO
-- `Bus` — session event bus (pubsub)
-- `State` — current state: `idle`, `thinking`, or `calling: <tool>`
-- `Reply` — assistant text from the last completed turn
-- `WaitChange` — block until a field changes (state, usage, ctxsz, cwd)
-- `Detach`/`ListDetached`/`SignalDetached`/`GetDetachedOutput` — background process management
+**`session.Agent`** — the reasoning entity within a session. Owns the conversation history, LLM backend, tools, hooks, and system prompt. Swappable via `/agent` command.
 
-**`backend.Backend`** — the LLM interface: `ChatStream`, `Models`, `ContextLength`, `Name`, `Model`/`SetModel`, `DefaultModel`.
+**`session.harness`** (unexported) — implements Session. Wires the agent to the session environment and drives turn execution.
 
-**`tools.Server`** — interface for a tool provider: `ListTools`, `CallTool`. The primary implementation is `execute.Server` (local) with `execute.RemoteServer` for SSH-transparent execution.
+**`backend.Backend`** — the LLM interface: `ChatStream`, `Models`, `ContextLength`, `Name`, `Model`/`SetModel`.
 
-**`tools.Dispatcher`** — routes tool calls to the correct server by name. Built via `NewDispatcher` or `NewDispatcherFunc`.
+**`tools.Server`** — interface for a tool provider: `ListTools`, `CallTool`. Implementations: `execute.Server` (local) and `execute.RemoteServer` (SSH).
 
-**`tools.Registry`** — per-session dynamic tool loading. Discovers tool scripts from `OLLIE_TOOLS_PATH`, parses their schemas and metadata, and promotes them to native callable functions on demand.
+**`tools.Registry`** — per-session dynamic tool loading. Discovers scripts from `OLLIE_TOOLS_PATH`, parses schemas, promotes to native callable functions on demand.
 
 ## Install
 
@@ -102,7 +94,7 @@ Skills are domain-specific knowledge modules in `OLLIE_SKILLS_PATH` (default: `~
 
 The 9P server (`olliesrv`) is the session manager. It instantiates the execute server, elevation broker, and tool/skill registries at daemon level. Sessions are created, queried, and controlled via the 9P filesystem — all agent interaction uses the `ollie-9p` client internally.
 
-`NewAgentCore` handles per-session state: message history, tool call routing, compaction, and hooks. `Core.Close()` tears down resources when a session is killed.
+`session.New()` creates a session with its agent. The session drives turn execution, manages compaction, and handles lifecycle events. `Close()` tears down resources when a session is killed.
 
 ## License
 
diff --git a/session/config.go b/session/agent_config.go
similarity index 100%
rename from session/config.go
rename to session/agent_config.go