diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5996e41
--- /dev/null
+++ b/README.md
@@ -0,0 +1,113 @@
+# homeai-kit-test
+
+A full local AI stack for personal homelab use. Bundles Ollama (local LLM inference), Open WebUI (chat interface), ChromaDB (vector database), SearXNG (private search), and n8n (workflow automation) into a single Docker Compose deployment.
+
+This is a test/evaluation deployment of the **HomeAI Kit** stack on the Linux server.
+
+## Stack
+
+### Core Services (always started)
+
+| Service | Container | Port | Description |
+|---------|-----------|------|-------------|
+| Ollama | `homeai-ollama` | `11435` | Local LLM inference server |
+| Open WebUI | `homeai-open-webui` | `3000` | Chat UI connected to Ollama |
+| ChromaDB | `homeai-chromadb` | `8100` | Vector database (token-auth enabled) |
+| SearXNG | `homeai-searxng` | `8080` | Private meta-search engine |
+| PostgreSQL | `homeai-postgres` | `5432` | Database backend for n8n |
+| n8n | `homeai-n8n` | `5678` | Workflow automation |
+
+### Optional Services (`--profile extras`)
+
+| Service | Container | Port | Description |
+|---------|-----------|------|-------------|
+| LibreTranslate | `homeai-libretranslate` | `5000` | ML translation API |
+| Redis | `homeai-redis` | `6379` | Caching layer |
+| ChromaDB Admin | `homeai-chromadb-admin` | `3002` | Vector DB admin UI |
+
+## Running
+
+```bash
+# Core stack only
+docker compose up -d
+
+# Core + optional extras
+docker compose --profile extras up -d
+
+# Stop everything
+docker compose down
+```
+
+## Setup
+
+```bash
+cp .env.example .env
+# Edit .env — at minimum change POSTGRES_PASSWORD and CHROMA_SERVER_AUTHN_CREDENTIALS
+```
+
+After startup, pull an LLM model:
+```bash
+docker exec homeai-ollama ollama pull llama3.2:3b
+# Or use the helper script:
+./scripts/pull-models.sh llama3.2:3b
+```
+
+Then open `http://localhost:3000` to create your Open WebUI admin account.
+
+## Configuration
+
+All ports and credentials are set in `.env`. Key settings:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OLLAMA_PORT` | `11435` | Ollama API port |
+| `WEBUI_PORT` | `3000` | Open WebUI port |
+| `POSTGRES_PASSWORD` | *(required)* | PostgreSQL password |
+| `N8N_PORT` | `5678` | n8n workflow UI |
+| `CHROMA_PORT` | `8100` | ChromaDB port |
+| `CHROMA_SERVER_AUTHN_CREDENTIALS` | *(required)* | ChromaDB auth token |
+| `SEARXNG_PORT` | `8080` | SearXNG port |
+
+## Stacks
+
+The `stacks/` directory contains modular sub-stacks for selective deployment:
+
+| Stack | Description |
+|-------|-------------|
+| `stacks/llm/` | Ollama + Open WebUI only |
+| `stacks/rag/` | ChromaDB + SearXNG for RAG pipelines |
+| `stacks/automation/` | n8n + PostgreSQL |
+| `stacks/extras/` | LibreTranslate, Redis, ChromaDB Admin |
+
+## SearXNG Config
+
+SearXNG settings are in `config/searxng/settings.yml` and `config/searxng/limiter.toml`. These are mounted read-only into the container.
+
+## Data Persistence
+
+All service data is stored in named Docker volumes:
+
+| Volume | Service |
+|--------|---------|
+| `ollama_data` | Downloaded LLM models |
+| `openwebui_data` | Chat history, users |
+| `chromadb_data` | Vector embeddings |
+| `postgres_data` | n8n workflows |
+| `n8n_data` | n8n credentials |
+| `libretranslate_data` | Translation models |
+
+## Deployment
+
+Runs on `192.168.0.241` (albert-MacBookPro Linux server).
+
+**Docker Compose:** `/opt/docker/homeai-kit-test/docker-compose.yml`
+
+| Service | URL |
+|---------|-----|
+| Open WebUI | `http://192.168.0.241:3000` |
+| n8n | `http://192.168.0.241:5678` |
+| Ollama API | `http://192.168.0.241:11435` |
+| SearXNG | `http://192.168.0.241:8080` |
+| ChromaDB | `http://192.168.0.241:8100` |
+
+> **Note:** This is a separate Ollama instance from the one used by ScraperControl (which runs as a systemd service on port `11434`). This stack uses port `11435` to avoid conflict.