M0: toolchain, monorepo scaffold, gateway plugin skeleton, CMP app

- gateway-plugin/: android platform plugin (plugin.yaml + adapter.py
  register(ctx) + no-op AndroidAdapter) + stub modules for M1-M5
- app/: Compose Multiplatform project (shared KMP + androidApp +
  desktopApp) with Gradle wrapper; builds :androidApp:assembleDebug
  and :desktopApp:compileKotlin
- scripts/guard_hermes_agent.sh + pre-commit hook: fail if hermes-agent/
  is staged (read-only reference, never committed)
- .gitignore excludes hermes-agent/; docs/ reference library

README.md

@@ -0,0 +1,42 @@
+# Iris × Hermes
+
+A **native Android + Desktop** experience for [hermes-agent](https://github.com/NousResearch/hermes-agent), connected through a **gateway platform plugin**.
+
+> ## ⚠️ HARD RULES
+> 1. **`hermes-agent/` is a read-only research reference. It is git-ignored and
+>    must NEVER be committed, pushed, or shipped.** We only *install* our plugin
+>    into a live hermes home (`~/.hermes/plugins/android`); we never modify hermes
+>    core.
+> 2. **ADB is installed and a device is connected** (`a5ca2a4b`, Xiaomi MIX 2S,
+>    Android 10 / API 29). Use it to install/launch/debug the app on-device.
+
+## Start here
+
+📚 **The full implementation reference library is in [`docs/`](docs/README.md).**
+Read `docs/00-overview.md` first, then follow the numbered docs.
+
+## The three deliverables (this monorepo)
+
+| Path | What |
+|---|---|
+| `gateway-plugin/` | Python hermes **platform plugin** (`android`). Runs in the `hermes gateway` process; opens a WebSocket server the apps connect to. Zero new Python deps, zero hermes-core changes. |
+| `app/androidApp` | Native **Kotlin + Jetpack Compose** client. |
+| `app/desktopApp` | **Kotlin + Compose Multiplatform** client — the Android app, tweaked for a big screen (shares `app/shared`). |
+
+The Android and Desktop clients live in **one Compose Multiplatform Gradle
+project** (`app/`) with a shared KMP module (`app/shared`).
+
+## Status
+
+- **Phase:** Planning complete → ready to implement (Milestone M0).
+- **Milestones:** see [`docs/14-milestones.md`](docs/14-milestones.md).
+- **Locked decisions:** see [`docs/16-open-questions.md`](docs/16-open-questions.md).
+
+## Quick orientation
+
+- Architecture + rationale → [`docs/01-architecture.md`](docs/01-architecture.md)
+- Wire protocol → [`docs/04-wire-protocol.md`](docs/04-wire-protocol.md) (+ [`docs/protocol/frames.schema.json`](docs/protocol/frames.schema.json))
+- Gateway plugin design → [`docs/03-gateway-plugin.md`](docs/03-gateway-plugin.md)
+- hermes source cheat-sheet → [`docs/15-hermes-reference.md`](docs/15-hermes-reference.md)
+- Toolchain setup → [`docs/12-toolchain.md`](docs/12-toolchain.md)
+</file>