diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dd17407
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# Converse Service
+
+Chat UI and web frontend for Egregore.
+
+## Purpose
+
+Serves the conversational web interface and handles user authentication. Acts as the public-facing entry point for human users interacting with the AI through a browser.
+
+## Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | Chat interface (HTML) |
+| `/api/chat` | POST | Send message, get response |
+| `/api/history` | GET | Get chat history |
+| `/api/search` | GET | Search messages |
+| `/api/transcribe` | POST | Transcribe audio (Whisper) |
+| `/health` | GET | Health check |
+
+## Configuration
+
+Environment variables (from `~/.env`):
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CHAT_USERNAME` | Basic auth username | `admin` |
+| `CHAT_PASSWORD` | Basic auth password | `changeme` |
+| `REASON_URL` | Reason service URL | `http://127.0.0.1:8081` |
+| `RECALL_URL` | Recall service URL | `http://127.0.0.1:8082` |
+| `OPENAI_API_KEY` | For audio transcription | - |
+
+## Running
+
+```bash
+# Activate venv
+source ~/.venv/bin/activate
+
+# Run directly
+python main.py
+
+# Or via systemd
+sudo systemctl start converse
+sudo systemctl status converse
+```
+
+## Dependencies
+
+- FastAPI
+- httpx (async HTTP client)
+- openai (for Whisper transcription)
+
+## Architecture
+
+```
+Browser → Converse → Reason (AI processing)
+                  → Recall (message storage)
+```
+
+Converse orchestrates requests between the user and backend services, handling authentication and session management.