doc: expand README with full feature list and 9P architecture section

README.md

@@ -25,17 +25,146 @@ Monorepo with Git submodules. Each submodule has its own Go module (except `el`
 | [contrib/](contrib/) | Mixed | Community scripts |
 | [experiments/](experiments/) | Mixed | Trial notes |
 
-## What you get
+## Features
 
-- **Agent loop with streaming tool calls** — the core runs a turn loop: prompt the model, parse tool calls, dispatch them (in parallel where safe), repeat until done
-- **Multi-backend routing** — Ollama (local), OpenAI-compatible, Anthropic, GitHub Copilot, Kiro; switch backends per-session or let the tier router pick automatically
-- **Sandboxed tool execution** — every tool call runs inside a Landlock sandbox with per-profile filesystem access rules
-- **Extensible tools** — tools are executable scripts with header metadata; add one by dropping a file in a directory
-- **Multi-agent orchestration** — orchestrator/worker patterns, subagent delegation, parallel fan-out — all coordinated through the session primitives
-- **Domain skills** — teach the agent your project's conventions with a markdown file; loaded on demand
+### Sessions
+
+- **Create / kill / rename / list** — full lifecycle management of concurrent agent sessions
+- **Prompt submission with FIFO queue** — prompts are queued and processed in order; multiple clients can submit without conflicts
+- **State observation** — each session exposes its current state (`idle`, `thinking`, `calling: <tool>`) with a blocking-wait primitive for efficient polling
+- **Chat streaming** — stream model output in real time via file tail or D-Bus signal
+- **Session persistence** — active sessions survive server restarts; state is checkpointed to `~/.local/share/ollie/sessions/`
+- **Plan / scratchpad** — per-session markdown checklist that survives context compaction and is visible to peer agents
+- **Environment inspection** — read the effective environment variables for any session
+
+### Agent loop
+
+- **Streaming tool calls** — the core runs a turn loop: prompt the model, parse tool calls, dispatch them (in parallel where safe), feed results back, repeat until done
 - **Automatic context compaction** — long conversations are summarized transparently when approaching the context limit
-- **Multiple frontends** — terminal, acme, Emacs, KDE (plasmoid, standalone GUI, Kate plugin), and a browser-based web UI
-- **AI code completion** — a completion endpoint that any editor can call via stdin/stdout
+- **System prompt templating** — prompts are rendered from markdown templates with variable substitution; inspect the fully rendered prompt at any time
+
+### Backends
+
+- **Multi-backend routing** — Ollama (local), OpenAI-compatible, Anthropic, GitHub Copilot, Kiro; switch backends per-session or let the tier router pick automatically
+- **Model listing and switching** — enumerate available models from any backend; switch models mid-session
+- **24-hour model cache** — model lists are cached at the backend level to avoid repeated API calls
+
+### Tools and sandboxing
+
+- **Sandboxed execution** — every tool call runs inside a Landlock sandbox with per-profile filesystem access rules
+- **Extensible tools** — tools are executable scripts with header metadata; add one by dropping a file in a directory
+- **Elevation** — commands that need to escape the sandbox can request elevation through a streaming protocol (frame-based, over unix socket)
+
+### Agents
+
+- **Agent definitions** — JSON configs that set personality, tools, backend preferences, and constraints
+- **List and switch** — enumerate available agents and assign one to any session
+
+### Multi-agent
+
+- **Peer communication** — bidirectional links between sessions; peers can submit prompts to each other
+- **Orchestrator/worker patterns** — subagent delegation, parallel fan-out, coordinated through session primitives
+- **Domain skills** — teach the agent your project’s conventions with a markdown file; loaded on demand
+
+### Background processes
+
+- **Detach** — start a long-running command and immediately background it; the agent continues working
+- **Monitor** — list running processes, read their output (64KB ring buffer), check status
+- **Signal and dismiss** — send TERM/KILL to a detached process; remove finished processes from the list
+
+### Code completion
+
+- **Stateless completion endpoint** — write a JSON request (language, code, position), read back completions; works from any editor or script
+
+### Frontends
+
+- **Terminal** — interactive CLI (`b`, `bfg`, `sh`)
+- **Plan 9 acme** — editor integration for acme
+- **Emacs** — `ellie.el` package
+- **KDE** — plasmoid, standalone GUI, Kate plugin, KRunner, system tray
+- **Web UI** — Preact SPA served by the HTTP gateway
+
+### Configuration
+
+- **Per-session config** — backend, model, agent, generation parameters; all readable and writable at runtime
+- **Tier routing** — worker/expert model tiers per backend for automatic cost/capability optimization
+
+---
+
+## 9P: everything is a file
+
+The 9P filesystem server (`olliesrv`) exposes the entire agent runtime as a synthetic filesystem. This is not a convenience wrapper — it is the primary interface, and it provides architectural benefits that no RPC or REST API can match.
+
+### Why a filesystem?
+
+Every session is a directory. Every operation is a read or write. There is no client library, no SDK, no protocol buffer — `echo`, `cat`, `tail`, and `rm` are the API.
+
+```sh
+# Create a session
+echo "name=worker" > /mnt/ollie/s/new
+
+# Submit a prompt
+echo "fix the bug in main.go" > /mnt/ollie/s/worker/prompt
+
+# Stream the response
+tail -f /mnt/ollie/s/worker/chat
+
+# Check state
+cat /mnt/ollie/s/worker/state
+
+# Kill a background process
+echo "signal 12345 TERM" > /mnt/ollie/s/worker/ctl
+
+# Get completions
+echo '{"language":"go","code":"func he"}' > /mnt/ollie/s/worker/complete
+cat /mnt/ollie/s/worker/complete
+```
+
+### Network transparency
+
+9P is a network protocol. Mount the agent filesystem from any machine on the network:
+
+```sh
+9pfuse 'tcp!server:5640' /mnt/ollie
+```
+
+No SSH tunneling, no port forwarding for individual endpoints, no API gateway. One mount and every session, every tool, every config value is accessible as if local.
+
+### Container and headless deployment
+
+The 9P server embeds the core library directly — no D-Bus, no display server, no desktop dependencies. It runs anywhere a Go binary runs: containers, cloud VMs, CI runners, embedded systems.
+
+### Shell composability
+
+Because operations are file I/O, they compose with the entire Unix toolkit:
+
+```sh
+# Fan out a prompt to all sessions
+for s in /mnt/ollie/s/*/prompt; do echo "run tests" > "$s"; done
+
+# Wait for all agents to finish
+for s in /mnt/ollie/s/*/statewait; do cat "$s" > /dev/null; done
+
+# Grep all agent plans
+grep -r "TODO" /mnt/ollie/s/*/plan
+
+# Monitor costs
+paste /mnt/ollie/s/*/cost
+```
+
+Pipe agents into `awk`. Filter with `grep`. Schedule with `cron`. Orchestrate with a 10-line shell script instead of a framework.
+
+### Multiplexing
+
+Multiple clients — terminals, editors, scripts, other agents — can mount the same server simultaneously. Each gets an independent view through 9P’s per-fid state model. No connection pools, no session affinity, no WebSocket juggling.
+
+### Plan 9 patterns
+
+The design follows Plan 9 conventions directly:
+
+- **`/net/dns` pattern** — the `/complete` file is stateless per-fid: write a request, read back the result, like a DNS lookup
+- **`ctl` files** — control operations (stop, kill, rename, compact) are writes to a control file, not method calls
+- **Blocking reads** — `statewait` blocks until state changes, replacing event subscriptions with a simple `cat`
 
 ## Getting started