diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1cfe3ad
--- /dev/null
+++ b/README.md
@@ -0,0 +1,93 @@
+# Barclays BMB Banner Visualiser
+
+AI-powered banner creation tool for Barclays Mobile Banking campaign managers.
+
+**Brief → compliant copy variants → DAM image + icon → in-situ preview → PDF contact sheet + Workfront CSV**
+
+Live: https://optical-dev.oliver.solutions/barclays-banner-builder/
+
+---
+
+## Stack
+
+| Layer | Tech |
+|---|---|
+| Frontend | React 18 + Vite + TypeScript + TailwindCSS + shadcn/ui |
+| Backend | FastAPI (Python 3.12) + SQLAlchemy 2.0 async |
+| Queue | RQ + Redis (HTTP polling — no WebSocket) |
+| DB | PostgreSQL 16 + pgvector |
+| AI | OpenAI `gpt-5.4-mini` + `text-embedding-3-small` (RAG) |
+| PDF | WeasyPrint |
+| Deploy | Docker Compose + Apache reverse proxy |
+
+---
+
+## Quick start (dev)
+
+```bash
+cp .env.example .env
+# Set OPENAI_API_KEY in .env
+
+docker compose up -d --build
+docker compose exec api alembic upgrade head
+docker compose exec api python scripts/seed_admin.py
+docker compose exec api python scripts/ingest_rag.py
+docker compose exec api python scripts/index_icons.py
+```
+
+- Frontend: http://localhost:5174
+- API docs: http://localhost:8010/docs
+- Login: `admin@barclays.com` / `change_me_password`
+
+---
+
+## Deploy (Ubuntu + Apache)
+
+```bash
+# Clone once:
+git clone <repo> /opt/barclays-banner-builder
+
+# Every deploy (idempotent):
+bash /opt/barclays-banner-builder/deploy.sh
+
+# Options:
+bash deploy.sh --reindex        # force re-embed RAG + icons
+bash deploy.sh --skip-frontend  # backend-only update
+```
+
+The script handles: Docker build (with cache), DB migrations, first-run seeding, npm build, Apache config patching.
+
+---
+
+## Key rules
+
+- **No WebSocket** — all async work uses `POST → 202 + job_id → GET /api/jobs/{id}` polling
+- **OpenAI only** — model `gpt-5.4-mini`, key in `.env` only (never committed)
+- **System prompt editable** from `/admin` — full version history kept for FCA audit
+- **Character limits enforced server-side** — short_title ≤ 32, long_body ≤ 128, cta ≤ 50
+- **DAM mock mode** — if `ADOBE_DAM_API_BASE_URL` is empty, mock client is used automatically
+
+---
+
+## Project structure
+
+```
+backend/app/
+  api/         — FastAPI routers
+  models/      — SQLAlchemy models
+  services/    — copy_generation, exporter, adobe_dam_client
+  llm/         — OpenAI client wrapper
+  rag/         — pgvector cosine retrieval
+  workers/     — RQ tasks (generate_copy, render_pdf)
+  prompts/     — system_prompt.md (initial seed)
+
+frontend/src/
+  pages/       — BriefEditor, VariantsGrid, BannerEditor, ExportPage, AdminPage, LoginPage
+  lib/         — jobPolling.ts
+  store/       — Zustand auth store
+
+rag-corpus/    — Consumer Duty, Consumer Understanding, Regulators .docx
+assets/        — illustrations/ (PNG icons) + templates/
+deploy/        — apache-barclays.conf (Apache Include fragment)
+scripts/       — index_icons.py, ingest_rag.py, seed_admin.py
+```