diff --git a/app/.env.example b/app/.env.example
index 338dbd92..fe3b6353 100644
--- a/app/.env.example
+++ b/app/.env.example
@@ -6,4 +6,5 @@ OPENAI_API_KEY=your-openai-key
 DB_PATH=/path/to/your/haiku.rag.lancedb
 
 # Optional: Ollama base URL (if using local models)
-OLLAMA_BASE_URL=http://localhost:11434
+# Use host.docker.internal to reach Ollama running on the host machine
+OLLAMA_BASE_URL=http://host.docker.internal:11434
diff --git a/app/README.md b/app/README.md
new file mode 100644
index 00000000..c3c1648b
--- /dev/null
+++ b/app/README.md
@@ -0,0 +1,108 @@
+# haiku.rag Chat App
+
+A conversational RAG interface built with [CopilotKit](https://copilotkit.ai/) and [pydantic-ai](https://github.com/pydantic/pydantic-ai)'s AG-UI protocol.
+
+## Prerequisites
+
+- Docker and Docker Compose
+- A haiku.rag database (created via the `haiku-rag` CLI)
+- An LLM API key (Anthropic, OpenAI, or local Ollama)
+
+## Quick Start
+
+1. **Set up environment variables:**
+
+   ```bash
+   cp .env.example .env
+   # Edit .env with your API keys and database path
+   ```
+
+2. **Configure the LLM and embedding models:**
+
+   ```bash
+   cp haiku.rag.yaml.example haiku.rag.yaml
+   # Edit haiku.rag.yaml to configure your models
+   ```
+
+3. **Start the app:**
+
+   ```bash
+   docker compose up -d
+   ```
+
+4. **Open the chat interface:** http://localhost:3000
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `DB_PATH` | Path to your haiku.rag LanceDB database | Yes |
+| `ANTHROPIC_API_KEY` | Anthropic API key | One LLM key required |
+| `OPENAI_API_KEY` | OpenAI API key | One LLM key required |
+| `OLLAMA_BASE_URL` | Ollama server URL (default: `http://host.docker.internal:11434`) | For local models |
+| `LOGFIRE_TOKEN` | Pydantic Logfire token for debugging | No |
+
+### haiku.rag.yaml
+
+Configure the chat agent's LLM, embeddings, and search settings:
+
+```yaml
+qa:
+  model:
+    provider: anthropic  # or openai, ollama
+    name: claude-sonnet-4-20250514
+
+embeddings:
+  model:
+    provider: ollama
+    name: nomic-embed-text
+
+search:
+  limit: 10
+  context_radius: 1
+```
+
+See `haiku.rag.yaml.example` for all options.
+
+## Development
+
+For local development with hot reloading:
+
+```bash
+docker compose -f docker-compose.dev.yml up -d --build
+```
+
+- Backend code changes reload automatically
+- Frontend available at http://localhost:3000
+- Backend API at http://localhost:8001
+
+## Architecture
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│    Frontend     │────▶│     Backend     │────▶│   haiku.rag     │
+│  (CopilotKit)   │     │  (pydantic-ai)  │     │   (LanceDB)     │
+│  localhost:3000 │     │  localhost:8001 │     │                 │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+### Backend Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/chat/stream` | POST | AG-UI chat streaming |
+| `/api/documents` | GET | List documents in database |
+| `/api/info` | GET | Database statistics |
+| `/api/visualize/{chunk_id}` | GET | Visual grounding for chunks |
+| `/health` | GET | Health check |
+
+## Chat Capabilities
+
+The chat agent can:
+
+- **Search** your documents with hybrid vector + full-text search
+- **Answer questions** with citations from your knowledge base
+- **Filter by document** when you ask about specific files
+- **Show visual grounding** for PDF/image sources
diff --git a/app/haiku.rag.yaml.example b/app/haiku.rag.yaml.example
index 313ea01c..a60ea0d0 100644
--- a/app/haiku.rag.yaml.example
+++ b/app/haiku.rag.yaml.example
@@ -17,10 +17,12 @@ qa:
 embeddings:
   model:
     provider: ollama
-    name: nomic-embed-text
+    name: qwen3-embedding:4b
+    vector_dim: 2560
     # For OpenAI:
     # provider: openai
     # name: text-embedding-3-small
+    # vector_dim: 1536
 
 # Optional reranking
 # reranking:
@@ -30,10 +32,11 @@ embeddings:
 
 # Search settings
 search:
-  limit: 10
-  context_radius: 1
+  limit: 5
+  context_radius: 0
 
 # Provider settings
 providers:
   ollama:
-    base_url: http://localhost:11434
+    # Use host.docker.internal to reach Ollama running on the host machine
+    base_url: http://host.docker.internal:11434