diff --git a/README.md b/README.md
index f127ee2..04f6d8a 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,140 @@
-# vrious
+# vriōus — Multi-Agent Orchestration & Shared Memory Patterns
 
-Multi-agent orchestration and shared memory patterns
\ No newline at end of file
+Canonical patterns for orchestrating coding agents (pi, opencode, claude-code) from Hermes, with shared memory across a distributed, multi-container fleet.
+
+## Architecture Model
+
+This is **multi-host, multi-container** — not single-host. Each agent runs in its own container or host:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Hermes (hertz) — orchestrator                │
+│  fact_store / memory tool / MCP client                          │
+│  Skills: codex, opencode, claude-code, hermes-agent              │
+└──────┬───────────────────────────┬────────────────────┬──────────┘
+       │                           │                    │
+       ▼                           ▼                    ▼
+┌──────────────┐    ┌──────────────────┐    ┌──────────────────┐
+│ pi agent      │    │ opencode         │    │ claude-code      │
+│ (pica)        │    │ (local or cont.) │    │ (local or cont.) │
+│ Codex CLI     │    │ OpenCode CLI     │    │ Claude Code CLI  │
+│ --print       │    │ run / TUI        │    │ exec / TUI       │
+│ NPU inference │    │ provider-agnostic│    │ Anthropic Claude │
+└──────┬───────┘    └────────┬─────────┘    └────────┬─────────┘
+       │                     │                        │
+       └─────────────────────┼────────────────────────┘
+                             │
+                    ┌────────▼────────┐
+                    │  Stash / MCP    │
+                    │  memory server  │
+                    │ (memory.fritz   │
+                    │ .box:8080/sse)  │
+                    └─────────────────┘
+```
+
+Each agent is independent — separate process, separate container, separate config. Hermes invokes them via the appropriate transport (MCP shell, lmcp, SSH, direct CLI).
+
+## Agents
+
+| Agent | CLI | Invocation | Transport | Location |
+|-------|-----|------------|-----------|----------|
+| **Hermes** | `hermes` | n/a (orchestrator) | — | hertz (bare metal) |
+| **pi** | `pi --print` | `pi_exec` MCP tool, SSH+nohup | MCP / SSH | pica (RPi5, container) |
+| **opencode** | `opencode run` | direct terminal or bg pty | local terminal | any container |
+| **claude-code** | `claude` | direct terminal or bg pty | local terminal | any container |
+
+## Invocation Patterns
+
+### One-Shot (pi)
+
+```
+# Via pi_exec MCP tool (preferred — configurable timeout)
+mcp__pica__pi_exec(
+    prompt="Read /path/to/file and summarize it",
+    model="qwen3.5-9b-npu",
+    provider="hossenfelder"
+)
+
+# Via SSH (fallback)
+ssh mfritsche@pica "pi --print --provider hossenfelder --model qwen3.5-9b-npu 'prompt'"
+```
+
+### One-Shot (opencode)
+
+```
+opencode run 'Implement retry logic for API calls' --model openrouter/anthropic/claude-sonnet-4
+```
+
+### One-Shot (claude-code)
+
+```
+claude execute -p 'Refactor the auth module and add tests' --model claude-sonnet-4
+```
+
+### Background / Long-Running Tasks
+
+```
+# pi: SSH + nohup with lock file, timeout per file
+# See references/batch-pi-processing.md for full pattern
+
+# opencode/claude-code: terminal background + pty
+terminal(command="opencode", background=true, pty=true)
+# then: process(action="submit", data="prompt")
+
+terminal(command="claude", background=true, pty=true)
+# then: process(action="submit", data="prompt")
+```
+
+## Shared Memory Patterns
+
+### Tier 1: Hermes Holographic Memory (Hermes-only)
+
+```
+fact_store(action='add', content='...', category='general')
+```
+
+Accessed exclusively by Hermes via `fact_store` and `fact_feedback` tools. Agents report results, Hermes extracts facts and stores them.
+
+### Tier 2: Stash MCP Server (Any MCP-capable agent)
+
+```
+Memory server at memory.fritz.box:8080/sse (boltzmann container)
+- Postgres + pgvector + Ollama
+- 28 MCP tools
+- Query via /stash recall --namespaces "/" -- "query"
+```
+
+If pi, opencode, or claude-code support MCP client configuration, they can read/write to the same stash namespace directly. Otherwise, all memory flows through Hermes.
+
+### Tier 3: File-Based (Every agent)
+
+```
+Shared facts.md — agents append with >>, Hermes reads with read_file
+```
+
+Simple, universal. Used in the batch-pi-processing pattern.
+
+## Multi-Host, Multi-Container Design
+
+YES — this is designed for separate hosts/containers. Each agent is independently deployed:
+
+| Host | Container? | Agent | Notes |
+|------|-----------|-------|-------|
+| hertz | bare metal | Hermes | Orchestrator, MCP client |
+| pica | Incus | pi agent | RPi5, RK3588 NPU, qwen3.5-9b-npu |
+| boltzmann | Incus | Stash / memory | Postgres, pgvector |
+| (any) | Incus or Docker | opencode | Provider-agnostic |
+| (any) | Incus or Docker | claude-code | Anthropic Claude |
+
+**No shared filesystem required.** Communication is via:
+- MCP (HTTP/SSE) — stash, pi_exec, file tools
+- SSH — fallback for pi on pica
+- Hermes terminal — opencode and claude-code on any reachable host
+
+## Recommendations
+
+1. **New agents go in their own container** — keeps dependencies, configs, and sessions isolated
+2. **Stash as shared memory** — structured, queryable, MCP-accessible. Best upgrade path from file-based
+3. **Hermes as sole memory curator** — extracts durable facts from agent outputs, stores in fact_store with trust scoring
+4. **One-shot for bounded tasks, background TUI for iterative** — match the invocation pattern to the task
+5. **AGENTS.md per repo** — project-level context that all agents respect