whitepaper: draft opening paragraph

doc/whitepaper.md

@@ -0,0 +1,15 @@
+# Ollie Technical Whitepaper
+
+Ollie is an AI agent runtime distilled to one idea: **agent state and behavior are files**. A single binary (`olliesrv`) exposes every session, agent, prompt, tool, and state value as entries in a 9P2000 filesystem. There is no API server, no protocol daemon, no plugin framework — `cat`, `echo`, and `tail` are the client library.
+
+The motivation came from building agent systems the conventional way and finding them brittle. Monolithic frameworks bake in assumptions about deployment, tooling, and UI that are wrong more often than they are right. Every abstraction that "just handles" scheduling, tool management, or frontend communication eventually becomes a constraint that has to be worked around. The Plan 9 approach — a small kernel exposing resources as files, letting the surrounding system compose them however it wants — seemed like the right antidote.
+
+Concretely, that means:
+
+- **Sessions are directories.** Creating a session is writing to `session/new`. Listing agents is `ls session/{sname}/agent/`. Killing a session is writing `kill` to `session/{sname}/ctl`.
+- **Prompts are files.** Sending a prompt is writing to `session/{sname}/agent/{aname}/prompt`. The agent reads it, processes it, and appends the response to `chat`. Streaming is a blocking read on `chat`.
+- **Tools are scripts.** No tool is compiled into the binary. Every tool — `shell`, `file_read`, `file_edit`, `reasoning_think`, `lsp_definition`, `gui_screenshot` — is an executable script loaded dynamically from the filesystem. The core is pure coordination: stream from the LLM → dispatch tool calls → loop.
+- **State is a file.** `state` returns the current agent state. `statewait` blocks until it changes. No events, no callbacks, no polling.
+- **Frontends are interchangeable.** The Emacs client (`ellie.el`), the Qt6 GUI (`ollie-gui`), the acme editor, the `o` CLI, and shell scripts all talk to the same 9P filesystem. The server does not know or care which one is connected.
+
+Over ~1400 commits across roughly four months of development, the architecture shed accumulated complexity in waves: D-Bus removed, MCP removed, FUSE replaced with a lightweight 9P client, accumulated interface indirection flattened, tool metadata extracted into standalone JSON sidecars. Each removal made the system simpler and more composable. What remains is a minimal coordination surface — the 9P namespace, the agent loop, and a sandboxed tool dispatcher — that external scripts and frontends use however they want.