Tidy AGENTS.md for handoff: lean Current state, Phase 3 deploy forward-pointer

This commit is contained in:
Keysat
2026-06-15 22:55:25 -05:00
parent ff0dada0d5
commit 843582ec03
+16 -22
View File
@@ -64,6 +64,8 @@ the full answer back into the room (ask mode, D12).
- **Deploy:** pull the bot files from the Mac (no Gitea needed) —
`scp mac-bridge:/Users/macpro/Projects/matrix-bridge/{Dockerfile,docker-compose.yml,docker-entrypoint.sh,requirements.txt,config.toml,.env} .`
and `scp -r mac-bridge:/Users/macpro/Projects/matrix-bridge/src .`, then rebuild.
*(Phase 3 switches this to `git pull` once the Spark's `~/matrix-bridge` becomes a Gitea clone —
see `docs/spark-control-integration.md`; not done yet, so scp-from-Mac is still the live path.)*
## Layout
@@ -189,26 +191,18 @@ once" is not done.
## Current state
- **Working & proven live on the Spark (Phases 01 + ask mode, 2026-06-16).** The bot runs as a Docker
container on the Spark (`~/matrix-bridge`, `docker compose up -d --build`): generic image, host
networking, `restart: unless-stopped`, read-only mounts of `.env`/`config.toml`/SSH key. Listens as
`@agent` in 11 project rooms + an all-projects fan-out room (each fan-out session named `<repo> - <date>`).
- **Interactive** (plain message): `ssh mac-bridge → gui-launch.sh → launch-claude.sh → claude`
drivable session on the phone via Remote Control.
- **Ask mode** (`?`-prefixed message): `ssh mac-bridge → ask-claude.sh → claude -p`, full answer posted
back into the room (chunked, no truncation). See D12.
- **Phase 2 (multi-room routing) — DONE.** Owner confirmed the N=3 pass: routes by `room_id`,
correct repo, zero wrong-directory launches.
- **Phase 3 (Spark Control integration) — spec drafted, handed to the Spark Control dev (2026-06-15).**
See `docs/spark-control-integration.md`: the SSH command contract (status via `docker inspect`;
restart via `docker restart`; update via `git fetch && git reset --hard origin/master &&
docker compose up -d --build`) plus a one-time conversion of the Spark's `~/matrix-bridge` from
scp'd loose files to a Gitea clone (secrets are gitignored, so `reset --hard` preserves them).
Decisions this session: update source = git-pull-from-Gitea (not scp-from-Mac); Spark Control
already SSHes into `spark-32d0`, so no new key. **matrix-bridge needs no code change** — the work
is now Spark Control-side (status tile + buttons) + the one-time Spark migration. Awaiting the dev.
- **Live on the Spark (Phases 02 + ask mode).** matrix-nio bot in a Docker container
(`~/matrix-bridge`, `docker compose up -d --build`): host networking, `restart: unless-stopped`,
read-only mounts of `.env`/`config.toml`/SSH key. Runs as `@agent` in 11 project rooms + an
all-projects fan-out room. Both modes proven — interactive (plain msg → phone via Remote Control)
and ask (`?`-prefix → full answer posted back; D12).
- **Phase 2 — DONE** (owner-confirmed N=3: routes by `room_id`, correct repo, zero wrong-dir launches).
- **Phase 3 (Spark Control) — IN PROGRESS, awaiting the Spark Control dev.** The contract is
`docs/spark-control-integration.md`: status/restart/git-pull-update SSH commands + a one-time
conversion of the Spark's `~/matrix-bridge` to a Gitea clone. matrix-bridge needs no code change;
remaining work is Spark Control-side (tile + buttons) + the one-time migration. **When live:** trim
the spec to the lean command contract, update the Commands "Deploy" entry (scp → git pull), flip
Phase 3 → DONE.
- **Open / risks:** a `?`-ask in a repo `claude` has never opened may stall on the folder-trust gate
— add a trust flag to `ask-claude.sh` if/when hit, not preemptively. (Resolved this session: the
accidental MacBook docker deploy was cleaned up by the owner.)
- **Repo:** `master` == `phase-1`, pushed to Gitea; the Phase 3 spec + doc updates landed as `e5a751d`.
No test suite (pre-existing); the doc is a spec, no code changed.
— add a trust flag to `ask-claude.sh` if/when hit, not preemptively.
- **Repo:** `master` == `phase-1`, clean, pushed to Gitea. No test suite (pre-existing).