diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7186ed0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,88 @@
+# ollie-webui
+
+Browser-based front-end for [ollie](../README.md). A Preact single-page application that talks to [ollie-httpgw](../httpgw/) over REST. Provides session management, a chat interface with markdown rendering, and theme switching.
+
+## Prerequisites
+
+- [olliesrv](../9p/) running
+- [ollie-httpgw](../httpgw/) running (translates HTTP to 9P)
+
+## Build
+
+```sh
+npm install
+npm run build
+```
+
+Output: `dist/` (static files).
+
+## Development
+
+Vite dev server with hot reload and API proxy:
+
+```sh
+npm run dev
+# Open http://localhost:5173
+```
+
+The proxy forwards `/sessions`, `/backends`, `/agents`, and `/openapi.json` to `localhost:8011` (httpgw default with `-listen :8011`, or adjust `vite.config.ts`).
+
+## Serve (production)
+
+`dist/` is a static site. Serve with any HTTP server and proxy API paths to httpgw:
+
+```nginx
+server {
+    listen 3000;
+    root /path/to/ollie/webui/dist;
+    index index.html;
+
+    location / { try_files $uri /index.html; }
+
+    location ~ ^/(sessions|backends|agents|openapi\.json)(/|$) {
+        proxy_pass http://localhost:8011;
+    }
+}
+```
+
+## Features
+
+- Session list sidebar with state, backend, model, and cwd
+- Create, rename, and kill sessions
+- Send prompts; updates via 250ms poll
+- Stop a running agent turn
+- Markdown rendering of assistant responses (via marked + mermaid + KaTeX)
+- Two built-in themes: `midnight` (dark) and `acme` (Plan 9-inspired light); persisted to localStorage
+
+## Stack
+
+- [Preact](https://preactjs.com/) (UI)
+- [Vite](https://vitejs.dev/) (build/dev server)
+- [marked](https://marked.js.org/) (markdown)
+- [mermaid](https://mermaid.js.org/) (diagrams)
+- [KaTeX](https://katex.org/) (math)
+- TypeScript
+
+## File layout
+
+```
+webui/
+├── package.json
+├── vite.config.ts
+├── src/
+│   ├── app.tsx              # Root component: session polling, routing
+│   ├── style.css            # Global styles
+│   ├── components/
+│   │   ├── ChatPane.tsx     # Chat display + prompt bar
+│   │   ├── PromptBar.tsx    # Input field
+│   │   └── NewSession.tsx   # Session creation dialog
+│   └── lib/
+│       ├── api.ts           # HTTP client (fetch wrappers for httpgw)
+│       ├── chat.ts          # Chat log parser
+│       └── theme.ts         # Theme definitions and localStorage persistence
+└── dist/                    # Build output (static site)
+```
+
+## License
+
+GPLv3