M7: polish + E2E + docs (layout pass, theming, states, e2e driver, schema, setup.md, security)

README.md

@@ -15,6 +15,21 @@ A **native Android + Desktop** experience for [hermes-agent](https://github.com/
 📚 **The full implementation reference library is in [`docs/`](docs/README.md).**
 Read `docs/00-overview.md` first, then follow the numbered docs.
 
+## Quickstart
+
+Full walkthrough: [`docs/setup.md`](docs/setup.md).
+
+1. **Gateway:** install the plugin (`ln -s "$PWD/gateway-plugin" ~/.hermes/plugins/android`), run `hermes gateway setup` (generates the pairing token, prints the server URL), then `hermes gateway`.
+2. **App:** `cd app && ./gradlew :androidApp:installDebug` (Android; ADB device connected) or `./gradlew :desktopApp:run` (desktop).
+3. **Pair:** on the app's Connect screen, enter the server URL (`ws://<gateway-ip>:8790/ws`) + pairing token, then **Test & Connect**.
+4. **Chat.**
+
+### Pairing notes
+
+- **Token location:** `~/.hermes/.env` on the gateway host (`ANDROID_TOKEN`), or the `hermes gateway setup` output (printed once, at generation).
+- **Manual entry only:** the app has no QR scanner yet — the server prints a QR payload, but you type the URL + token.
+- **Default bind is `127.0.0.1`:** for a phone on the LAN, set `ANDROID_WS_HOST` to the gateway's LAN IP.
+
 ## The three deliverables (this monorepo)
 
 | Path | What |
@@ -28,7 +43,7 @@ project** (`app/`) with a shared KMP module (`app/shared`).
 
 ## Status
 
-- **Phase:** Planning complete → ready to implement (Milestone M0).
+- **Phase:** M0–M6 complete; M7 (polish + E2E + docs) in progress.
 - **Milestones:** see [`docs/14-milestones.md`](docs/14-milestones.md).
 - **Locked decisions:** see [`docs/16-open-questions.md`](docs/16-open-questions.md).