diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7a17d41
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# Android Fleet Godhead
+
+Autonomous Android VM fleet control node for Proxmox. Dashboard + REST API + WebSocket at
+`http://10.30.20.31:8080` (LXC CT704, systemd `android-fleet` + `android-harvest`).
+
+## What it does
+- **Spawn on demand**: clone from Android-x86 template VM 1301 (linked clones) → random MAC →
+  LAN DHCP → auto-registration via adb :5555 → unique egress proxy. Zero IP assignment.
+- **ProxyFly engine**: harvests proxifly.dev's free list every 25 min, live-tests each proxy,
+  cleanliness-grades (ip-api hosting/proxy flags + Spamhaus DNSBL), dedupes by egress IP, and
+  auto-assigns the best clean proxy to every device (pushed via `settings put global http_proxy`).
+- **Full device control**: interactive xterm.js terminal (`/ws/shell/<mac>`), programmatic exec
+  (`POST /api/device/<mac>/exec`, token-gated), screenshots, live hover previews, reboot/kill,
+  onboarding (basics → IG → account via instagrapi + IMAP verification), existing-account login.
+- **Live dashboard**: fleet cards with CPU/MEM/battery/net, 4 live charts, proxy bank with
+  clean badges, IG accounts panel, event log.
+
+## Files
+| File | Purpose |
+|---|---|
+| `app.py` | Flask + flask-sock control node (discovery, adb, spawn, proxies, WS) |
+| `proxy_harvest.py` | ProxyFly fetch → test → clean-grade → assign engine |
+| `onboard.py` | Per-device phone setup + IG account pipeline |
+| `static/index.html` | Dashboard (Tailwind + Chart.js + xterm.js, zero build) |
+| `docs/` | MASTER_PROMPT.md + operator manual |
+| `*.service` | systemd units |
+
+## Deploy
+```bash
+# from repo root, on the godhead CT:
+mkdir -p /opt/android-fleet
+cp app.py proxy_harvest.py onboard.py config.json /opt/android-fleet/
+cp -r static /opt/android-fleet/
+cp android-fleet.service android-harvest.service /etc/systemd/system/
+pip3 install --break-system-packages flask flask-sock requests pysocks instagrapi
+apt-get install -y adb
+systemctl daemon-reload && systemctl enable --now android-fleet android-harvest
+```
+
+## Quick API
+```bash
+curl -X POST http://10.30.20.31:8080/api/spawn -H "Content-Type: application/json" -d '{"count":3}'
+curl http://10.30.20.31:8080/api/devices
+curl -X POST http://10.30.20.31:8080/api/device/<MAC>/exec \
+     -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"cmd":"getprop ro.build.version.release"}'
+```
+
+Secrets live in `config.json` (gitignored) — copy `config.json.example`.