Update docs: Phase 1 bot status, run/deploy commands, headless-ask roadmap

- AGENTS.md: Commands now has the bot run/deploy (venv + scp from Mac); Layout lists
  src/bot.py, gui-launch.sh, requirements.txt, .env.example; Current state refreshed to
  Phase 1 (sub-steps 1-3 proven on the Spark; next = containerize).
- ROADMAP.md: log headless "ask" mode (claude -p -> output back into the room).

AGENTS.md

@@ -51,8 +51,12 @@ v1 decision surface.
 
 - `scripts/launch-claude.sh <repo_dir> <prompt>` — the Mac wrapper (Phase 0 deliverable;
   validate by hand before any bot code).
-- _TODO (Phase 1+):_ bot build/run (`docker build` / `docker compose up` on the Spark) once
-  `src/` exists.
+- **Bot (Phase 1), on the Spark:** `python3 -m venv .venv && .venv/bin/pip install -r requirements.txt`,
+  then `.venv/bin/python src/bot.py`. Deploy by pulling `src/`, `requirements.txt`, `config.toml`,
+  `.env` from the Mac via `scp mac-bridge:/Users/macpro/Projects/matrix-bridge/<x> .` (no Gitea
+  needed). `MB_SSH_ALIAS` env var overrides the SSH target for testing.
+- _TODO (Phase 1 sub-step 4):_ containerize — `docker compose up` on the Spark (host networking;
+  mount `.env`/`config.toml`/SSH key read-only) once the `Dockerfile` exists.
 
 ## Layout
 
@@ -62,8 +66,13 @@ v1 decision surface.
 - `scripts/launch-claude.sh` — the Mac-side launch wrapper (the only seam that knows the
   Mac's environment).
 - `config.example.toml` — room→repo mapping template; the real `config.toml` is gitignored.
+- `scripts/gui-launch.sh` — opens the desktop Terminal via `osascript` (Approach B, D11); calls
+  `launch-claude.sh` inside it. The bot invokes this over SSH.
+- `src/bot.py` — the matrix-nio bot (Phase 1): listens in mapped rooms; on a message runs
+  `ssh mac-bridge gui-launch.sh`; fans out for all-projects; reports failures back to the room.
+- `requirements.txt` (matrix-nio) · `.env.example` (credential schema; real `.env` gitignored).
 - `.claude/` — Claude wiring (dir only for now).
-- _Future:_ `src/` (the matrix-nio bot), `Dockerfile`, dependency manifest — Phase 1.
+- _Future:_ `Dockerfile` + `docker-compose.yml` — Phase 1 sub-step 4.
 
 ## Decisions (already made — don't relitigate without new information)
 
@@ -180,7 +189,14 @@ once" is not done.
   Added session naming: `launch-claude.sh` now runs `claude -n "<repo> - <topic>"` (topic from the
   message, overridable via `$MB_SESSION_NAME`) so Remote Control's phone index is readable —
   confirmed `-n` drives the phone app's conversation label.
-- **Next: Phase 1 — the matrix-nio bot.** Container on the Spark, logged in as `@agent` (token in
-  `.env`), listening in the 9 mapped rooms; on a message it runs `ssh mac-bridge gui-launch.sh
-  <repo_dir> <message>` (built with `shlex.quote`) and reports failures back to the room. See
-  ROADMAP Phase 1 (also: bake key+config into the image, curated `$MB_SESSION_NAME` topic, fail-loud).
+- **Phase 1 — bot working, sub-steps 1–3 PROVEN (2026-06-15).** `src/bot.py` (matrix-nio) logs in
+  as `@agent` with the stored token, listens in all 12 rooms, and on a message runs
+  `ssh mac-bridge gui-launch.sh <repo> <message>` (via `shlex.quote`), replies in-room, fans out
+  for `#all-projects` (each session named `<repo> - <date>`), and reports failures back (fail-loud).
+  Tested on the **Spark** (`~/matrix-bridge`, venv) — launches worked across several rooms (N=3).
+  Now 11 project rooms + all-projects; `config.toml` has a `[mac]` section (ssh_alias + launcher).
+- **Next: Phase 1 sub-step 4 — containerize.** Dockerfile + `docker-compose.yml`, host networking,
+  mount `.env`/`config.toml`/SSH key read-only, so the bot runs detached and survives reboots
+  (today it's a foreground venv run). Then FF `master` ← `phase-1`. Work is on branch **`phase-1`**
+  (pushed); `master` is at Phase 0 (`b6cc829`). Longer-term backlog (incl. headless "ask" mode) in
+  `ROADMAP.md`.

ROADMAP.md

@@ -54,3 +54,13 @@ after it.
   is actually in use.
 - **E2EE (D9).** Add matrix-nio end-to-end encryption (libolm) if the bot ever handles
   sensitive content over untrusted transport. Low priority while everything is WireGuard-local.
+- **Headless "ask" mode — return output into the chat (no interactive session).** Today a message
+  opens an interactive session surfaced to the phone. Add a mode where a message instead runs
+  `claude -p "<prompt>"` headlessly in the repo (full Claude Code context, but one-shot), captures
+  stdout, and posts the result back into the Matrix room — Matrix as a request/response interface,
+  not just a trigger. *Design notes:* `claude -p` (print mode) is exactly this capability. Likely
+  uses the long-lived OAuth token (Approach A / D11) so it runs over plain SSH with no GUI Terminal
+  and stdout is captured directly. *Open Qs:* how to select interactive-vs-ask (per-room? a prefix
+  like `?` / `/ask`? a dedicated room?); output-length handling (truncate / thread / attach file);
+  same local-only sovereignty constraints apply (output is the user's own; `claude -p` uses the
+  subscription, no frontier API on message payloads).