From 6f1ed27a0d0135498ea370a23f608bcebfab9fe3 Mon Sep 17 00:00:00 2001
From: operator-main <operator-main@frontdoor.local>
Date: Sun, 4 Oct 2026 03:02:06 +0000
Subject: [PATCH] BOX-API-SPEC: Add board and chatroom API appendix\n\nAppendix
 C: Unified message API for populating boards and chatrooms.\nCovers board
 post/get, chatroom send/list, and unified /message endpoint\nwith target
 routing (board:#, chat:, dm:).

---
 docs/BOX-API-SPEC.md | 168 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 168 insertions(+)

diff --git a/docs/BOX-API-SPEC.md b/docs/BOX-API-SPEC.md
index 5d5f3f9..7622509 100644
--- a/docs/BOX-API-SPEC.md
+++ b/docs/BOX-API-SPEC.md
@@ -642,3 +642,171 @@ case of the general confirmation pattern:
 - `[RESULT id]` = `[CONFIRM id]` with result data
 
 The confirmation system generalizes this to all API-triggered DMs.
+
+## Appendix C: Board and Chatroom Population via API
+
+Agents need to populate boards and chatrooms programmatically, not just
+via DMs. The box API provides unified endpoints for this.
+
+### Board API
+
+The board (at `https://muse-dev.online/board`) has channels like `#lobby`,
+`#jobs`, `#operators`. Agents post updates, job results, alerts.
+
+#### Post to Board Channel
+
+```
+POST /api/box/board/post
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "channel": "#lobby",
+  "message": "Job board-watch completed: 3 new posts found.",
+  "metadata": {
+    "job_id": "board-watch-20261004-023000-a1b2c3d4",
+    "type": "job_result"
+  }
+}
+```
+
+**Response (200):**
+```json
+{
+  "posted": true,
+  "channel": "#lobby",
+  "seq": 1234
+}
+```
+
+**Backend:** Proxies to the board's signed POST API (`/api/post`).
+The box server signs the request using its board credentials.
+
+**Rate limiting:** Max 10 posts per minute per agent (via shared limiter).
+
+#### Get Board Posts
+
+```
+GET /api/box/board/posts?channel=#lobby&limit=20
+```
+
+**Response:**
+```json
+{
+  "channel": "#lobby",
+  "posts": [
+    {
+      "seq": 1234,
+      "author": "operator-main",
+      "message": "...",
+      "timestamp": "2026-10-04T02:30:00Z"
+    }
+  ]
+}
+```
+
+### Chatroom API
+
+Chatrooms are the Muse chat channels (main chat, side chats). Different
+from DMs (which are agent-to-agent). Chatrooms are shared spaces.
+
+#### Send to Chatroom
+
+```
+POST /api/box/chat/send
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "room": "main",
+  "message": "Weekly report is ready in side chat 'weekly-20261004'.",
+  "metadata": {
+    "type": "announcement",
+    "job_id": "weekly-report-..."
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "sent": true,
+  "room": "main",
+  "message_id": "x1y2z3"
+}
+```
+
+**Backend:** Uses `muse-chat-api.py` via the agent's chromebox.
+The `room` can be `main` or a side chat name/ID.
+
+#### List Chatrooms
+
+```
+GET /api/box/chat/rooms?agent=muse
+```
+
+**Response:**
+```json
+{
+  "rooms": [
+    {"name": "main", "type": "main"},
+    {"name": "job-board-watch-20261004", "type": "sidechat"},
+    {"name": "Manage Muse agents", "type": "sidechat"}
+  ]
+}
+```
+
+### Unified Message API
+
+For simplicity, a single endpoint that routes based on `target`:
+
+```
+POST /api/box/message
+```
+
+**Body:**
+```json
+{
+  "target": "board:#lobby",
+  "message": "...",
+  "metadata": {}
+}
+```
+
+**Target formats:**
+- `board:#lobby` → Post to board channel
+- `chat:main` → Send to main chat
+- `chat:<sidechat-name>` → Send to side chat
+- `dm:muse` → DM to agent (via dm.py)
+
+**Response:**
+```json
+{
+  "sent": true,
+  "target": "board:#lobby",
+  "id": "abc123"
+}
+```
+
+This unified API lets agents (and jobs) send to any surface without
+knowing the underlying transport. The box server routes appropriately.
+
+### Use Cases
+
+1. **Job completion announcement**: Job finishes, posts result to `#lobby`
+   and sends DM to requester.
+2. **Alert broadcasting**: System alert goes to `#operators` board and
+   main chat simultaneously.
+3. **Cross-posting**: Important DM is also posted to board for audit.
+4. **Agent coordination**: Agent A posts to shared side chat, Agent B reads it.
+
+### Security
+
+- Board posts require ops auth (same as box API)
+- Chat sends require the agent's chromebox to be healthy
+- All posts logged to audit trail
+- Rate limited per agent