diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5b3ccd8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,178 @@
+# HeatGuard
+
+Personalized heat preparedness for your home. HeatGuard analyzes your living spaces, fetches weather forecasts, and generates hour-by-hour action plans to keep you safe during heat events.
+
+![License](https://img.shields.io/badge/license-GPL--3.0-blue)
+
+## Features
+
+- **Room-level heat budget analysis** — models internal gains (devices, occupants), solar gains, ventilation, and AC capacity per room
+- **Risk assessment** — 4-tier risk levels (low/moderate/high/extreme) with time windows
+- **24h SVG temperature timeline** — color-coded area chart with budget status strip
+- **Weather integration** — Open-Meteo forecasts + DWD severe weather warnings
+- **AI summary** — optional LLM-powered 3-bullet daily briefing (Anthropic, OpenAI, Gemini)
+- **Care checklist** — automatic reminders when vulnerable occupants are present
+- **Multilingual** — English and German, switchable in-app
+- **Privacy-first** — all user data stays in the browser (IndexedDB), server is stateless
+
+## Architecture
+
+```
+Browser (IndexedDB)          Go Server (stateless)
+┌─────────────────┐         ┌──────────────────────┐
+│ Profiles, Rooms │  JSON   │ /api/compute/dashboard│
+│ Devices, AC     │────────>│ /api/weather/forecast │
+│ Forecasts       │<────────│ /api/weather/warnings │
+│ LLM Settings    │         │ /api/llm/summarize    │
+└─────────────────┘         └──────────────────────┘
+```
+
+The Go server embeds all web assets (templates, JS, CSS, i18n) and serves them directly. No database on the server — all user data lives in the browser's IndexedDB.
+
+## Quick Start
+
+### Prerequisites
+
+- Go 1.23+
+- Node.js 18+ (for Tailwind CSS build)
+
+### Build & Run
+
+```bash
+# Install frontend dependencies
+npm install
+
+# Build (compiles CSS + Go binary)
+make build
+
+# Run
+./bin/heatguard
+```
+
+Open [http://localhost:8080](http://localhost:8080) in your browser.
+
+### Development Mode
+
+```bash
+make dev
+```
+
+Serves files from the filesystem (hot-reload templates/JS) on port 8080.
+
+## Configuration
+
+HeatGuard works out of the box with zero configuration. Optional server-side config for LLM:
+
+```yaml
+# ~/.config/heatwave/config.yaml
+llm:
+  provider: anthropic  # anthropic | openai | ollama | none
+  model: claude-sonnet-4-5-20250929
+  # endpoint: http://localhost:11434  # for ollama
+```
+
+API keys for LLM providers can also be configured directly in the browser under **Setup > AI Summary**, stored locally in IndexedDB.
+
+### CLI Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-port` | `8080` | HTTP listen port |
+| `-dev` | `false` | Development mode (serve from filesystem) |
+
+## Deploy
+
+### Standalone Binary
+
+```bash
+make build
+./bin/heatguard -port 3000
+```
+
+The binary is fully self-contained — all web assets are embedded. Copy it to any Linux server and run.
+
+### Systemd Service
+
+```ini
+# /etc/systemd/system/heatguard.service
+[Unit]
+Description=HeatGuard heat preparedness server
+After=network.target
+
+[Service]
+Type=simple
+User=heatguard
+ExecStart=/opt/heatguard/heatguard -port 8080
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now heatguard
+```
+
+### Behind a Reverse Proxy (nginx)
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name heatguard.example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/heatguard.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/heatguard.example.com/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+### Docker
+
+```dockerfile
+FROM golang:1.23-alpine AS build
+RUN apk add --no-cache nodejs npm
+WORKDIR /src
+COPY . .
+RUN npm install && make build
+
+FROM alpine:3.20
+COPY --from=build /src/bin/heatguard /usr/local/bin/
+EXPOSE 8080
+ENTRYPOINT ["heatguard"]
+```
+
+```bash
+docker build -t heatguard .
+docker run -d -p 8080:8080 heatguard
+```
+
+## Usage Workflow
+
+1. **Create a profile** — name + coordinates (auto-detect via browser geolocation)
+2. **Add rooms** — area, orientation, windows, insulation, indoor target temp
+3. **Add devices & occupants** — heat-producing equipment and people per room
+4. **Configure AC units** — capacity, type, room assignments
+5. **Fetch forecast** — pulls 3-day hourly weather data
+6. **View dashboard** — risk level, temperature timeline, room budgets, care checklist
+
+## Development
+
+```bash
+make test    # run all tests with race detector
+make build   # build CSS + binary
+make dev     # run in dev mode
+make clean   # remove build artifacts
+```
+
+## License
+
+[GPL-3.0](LICENSE)