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

docs/16-open-questions.md

@@ -0,0 +1,75 @@
+# 16 — Decisions & Open Questions
+
+## Locked decisions (from planning, 2026-08-19)
+
+| # | Decision | Choice | Rationale |
+|---|---|---|---|
+| 1 | Desktop app tech | **Compose Multiplatform** | Desktop = "the Android app, tweaked"; share protocol/state/UI. |
+| 2 | Push backend | **Both — FCM primary, ntfy fallback** | FCM is standard/reliable; ntfy for self-hosters with no Firebase. `ANDROID_PUSH_BACKEND`. |
+| 3 | Media transport | **Over the WebSocket** | One transport, zero new Python deps; chunked binary frames. |
+| 4 | Phone default layout | **User-toggleable, single-pane default** | App-like on phones; auto two-pane on large screens; desktop defaults two-pane. |
+
+## Additional decisions made during planning
+
+| Decision | Choice | Note |
+|---|---|---|
+| Connection point | **Messaging gateway** (platform plugin `android`), not `tui_gateway` | Makes cron/`send_message`/slash/coexistence native. |
+| Plugin style | **Community plugin** (`register(ctx)`) | Zero hermes-core changes. |
+| Python deps | **None new** (`websockets` + `httpx` are core) | Respects hermes pinning policy. |
+| Tool events | **Structured frames; app controls verbosity** | Gateway sends full data; app = everything/truncated/nothing. |
+| Reasoning | **Adapter splits the `show_reasoning` prefix** | Clean `reasoning` field → collapsible block above message. |
+| Channels/threads | **Map onto `chat_id`/`thread_id`** | Existing gateway primitives; cron targets them. |
+| Offline | **SQLite outbox + sync cursor** | Catch-up on reconnect; push on disconnect. |
+| Default chat id | `android:default` | Home channel + cron default. |
+| WS port | `8790` (default) | Configurable. |
+| minSdk | 26 (test device API 29) | Broad coverage. |
+| Frame routing | **Broadcast to all connected devices** (no per-chat subscribe) | Single-user model; simpler. |
+| Initial channel load | **`history` frame** (paginated) | `sync` only replays outbox; `history` loads full messages. |
+| Slash menu | **`commands.catalog` + `commands.complete`** frames | Gateway serves catalog; app renders bottom sheet + autocomplete. |
+| Agent lifecycle | **`agent.busy`/`agent.idle`** events + **`agent.stop`/`agent.steer`** requests | App shows thinking indicator; user can abort or steer mid-turn. |
+| Local DB (KMP) | **SQLDelight** (not Room) | Room is Android-only; SQLDelight works in commonMain for both platforms. |
+| Voice input | **Record → upload as audio media** (no client-side STT) | Agent's STT (if configured) handles transcription. |
+
+## Open questions (resolve during implementation)
+
+These are **implementation-time** details, not blockers. Each has a default we
+will proceed with unless you say otherwise.
+
+1. **Tool-progress vs commentary classification (M2).** The exact signal that
+   distinguishes a tool-progress `send()` from a regular `send()`/commentary in
+   the legacy path. *Default:* per-chat turn-state machine + line-format
+   heuristic, **verified empirically** with the `ws_probe.py` harness against the
+   live gateway. If a clean metadata marker exists, prefer it.
+2. **Reasoning prefix format stability (M2).** We split on the `code`-style
+   `💭 **Reasoning:**\n```\n…\n```\n\n` prefix. *Default:* set
+   `reasoning_style: code` for android and split on that; fallback = no
+   reasoning field (full text) if the prefix isn't found. Verify in M2.
+3. **Per-device tokens vs shared token (M1/M5).** *Default (v1):* shared
+   `ANDROID_TOKEN` + optional `ANDROID_ALLOWED_USERS` device allowlist.
+   Per-device revocable tokens are a stretch.
+4. **Desktop video backend (M6).** *Default:* `libmpv`/`mpv`-backed Compose
+   surface, WebView fallback. Confirm `mpv` availability on target OSes during
+   M6.
+5. **Remote access default (M1).** *Default:* document Tailscale as the
+   recommended remote path; WSS + reverse proxy as alternatives. No public bind
+   by default.
+6. **Streaming cadence (M2).** If live updates look chunky, tune
+   `display.platforms.android.streaming` / consumer edit interval. *Default:*
+   follow global streaming config.
+7. **App package name / branding.** *Default:* applicationId `dev.iris.app`,
+   app name "Iris". Confirm final product name + package + icon.
+8. **ntfy in-app listener (M5).** *Default:* a foreground service maintaining the
+   ntfy subscription (no extra native lib) — or a lightweight ntfy client lib if
+   one is acceptable. Decide in M5.
+9. **Auto-update for desktop (M7).** *Default:* out of scope (manual download).
+   Revisit post-v1.
+10. **iOS port.** Out of scope for v1 (protocol is transport-agnostic, so it's a
+    future port). No action now.
+
+## Explicit non-goals (v1)
+
+- Multi-user / group chat (personal 1-user agent).
+- End-to-end encryption (transport WSS only).
+- Standalone-cron delivery while the gateway process is fully down (best-effort
+  push only).
+- iOS.