diff --git a/README.md b/README.md
index 6f3dd5a..e66a6b4 100644
--- a/README.md
+++ b/README.md
@@ -1,41 +1,129 @@
 # MarkdownHub
 
-Self-hosted collaborative markdown workspace.
+Self-hosted collaborative markdown workspace with real-time editing, Git integration, and AI-powered code generation.
 
-See [SPEC.md](../SPEC.md) for full specification.
+## Features
 
-## Development
+- **Three editor modes**: WYSIWYG (Milkdown), raw markdown (CodeMirror-style), and split-pane with live preview
+- **File management**: Tree-based file browser, folders, search, create/delete
+- **Git versioning**: Auto-commit on save, full history, diff viewer, restore previous versions
+- **External Git sync**: Per-user remotes (Gitea, GitHub, etc.), push/pull on demand
+- **Sharing**: Share files/folders with other users (read-only or read-write)
+- **AI integration**: Verify specs, generate prompts, summarize — via LiteLLM/vLLM
+- **AI Build Pipeline**: Write a spec → verify → build entire project → push to Gitea
+- **2FA**: TOTP-based two-factor authentication
+- **Light/Dark theme**: Toggle in UI, persisted in preferences
+- **Export**: PDF, HTML, raw markdown download
+- **Offline-ready**: PWA architecture (planned)
+- **Multi-device**: Responsive, works on desktop and iPad
+- **Docker deployment**: Single container, easy backup
+
+## Quick Start
+
+### Docker (recommended)
 
-### Backend (Go)
 ```bash
-cd project
+docker build -t markdownhub .
+docker run -d --name markdownhub \
+  -p 8080:8080 \
+  -v ./data:/app/data \
+  -e MH_SECRET=your-random-secret \
+  markdownhub
+```
+
+Default admin: `admin@localhost` / `admin`
+
+### Development
+
+**Backend:**
+```bash
 go run ./cmd/server
 ```
 
-### Frontend (Vue)
+**Frontend:**
 ```bash
-cd project/frontend
+cd frontend
 npm install
 npm run dev
 ```
 
-### Docker
-```bash
-cd project
-docker compose up --build
+Frontend dev server proxies API calls to `localhost:8080`.
+
+## Configuration
+
+Environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MH_PORT` | `8080` | Server port |
+| `MH_DATA_DIR` | `./data` | Data directory (SQLite + files) |
+| `MH_SECRET` | `dev-secret-change-me` | JWT signing secret |
+| `MH_ADMIN_EMAIL` | `admin@localhost` | Initial admin email |
+| `MH_ADMIN_PASSWORD` | `admin` | Initial admin password |
+| `MH_AI_ENDPOINT` | — | LiteLLM-compatible API URL |
+| `MH_AI_API_KEY` | — | API key for AI endpoint |
+| `MH_AI_MODEL` | `gpt-4` | Default model for AI features |
+
+## Architecture
+
+```
+┌─────────────┐     ┌──────────────┐     ┌────────┐
+│  Frontend   │────▶│  Go Backend  │────▶│ SQLite │
+│  (Vue 3)    │◀────│  (net/http)  │     └────────┘
+└─────────────┘     │              │────▶ Filesystem (.md files)
+                    │              │────▶ Git (per-user repos)
+                    └──────────────┘
+                           │
+                    ┌──────▼───────┐     ┌────────┐
+                    │ Build Daemon │────▶│ Gitea  │
+                    │  (Python)    │     └────────┘
+                    └──────────────┘
 ```
 
+- **Backend**: Go, stdlib `net/http`, SQLite (pure Go via modernc.org/sqlite)
+- **Frontend**: Vue 3, Vite, Milkdown, CodeMirror 6, marked
+- **Auth**: JWT + bcrypt + TOTP
+- **Git**: Shell-based git operations (auto-commit, remotes, push/pull)
+- **AI**: LiteLLM-compatible OpenAI API calls
+- **Build Daemon**: Python (stdlib only), polls for build jobs, runs Pi coding agent
+
 ## Project Structure
+
 ```
-cmd/server/       — Web server entry point
-cmd/mdsync/       — CLI sync tool
-internal/api/     — HTTP handlers & routing
-internal/db/      — SQLite connection & schema
-internal/auth/    — Authentication & sessions
-internal/files/   — File CRUD operations
-internal/git/     — Git operations (go-git)
-internal/collab/  — Yjs WebSocket relay
-internal/crypto/  — AES-256-GCM encryption
-internal/ai/      — LiteLLM integration
-frontend/         — Vue 3 SPA
+cmd/server/          — Web server entry point
+cmd/mdsync/          — CLI sync tool (planned)
+internal/api/        — HTTP handlers & routing
+internal/auth/       — JWT, bcrypt, TOTP
+internal/db/         — SQLite schema & connection
+internal/files/      — File CRUD & search
+internal/git/        — Git operations
+internal/crypto/     — AES-256-GCM encryption (for private vault)
+daemon/              — Build daemon (Python)
+frontend/            — Vue 3 SPA
 ```
+
+## Build Daemon
+
+The build daemon runs on a separate Linux machine and processes AI build jobs:
+
+```bash
+export MH_URL=http://your-markdownhub:8080
+export MH_DAEMON_TOKEN=your-token
+export MH_WORKSPACE=~/builds
+python3 daemon/build_daemon.py
+```
+
+It polls MarkdownHub for pending jobs, creates Gitea repos, runs the Pi coding agent, and pushes results.
+
+## Backup & Restore
+
+All data lives in the `data/` volume:
+- `data/db/markdownhub.db` — SQLite database
+- `data/files/{user_id}/` — User markdown files (also git repos)
+
+**Backup**: Copy the `data/` directory.
+**Restore**: Stop container, replace `data/`, start container.
+
+## License
+
+MIT