BRIDGE_SPEC.md: front-door to muse.ai metadata bridge v0.1

docs/BRIDGE_SPEC.md

@@ -0,0 +1,109 @@
+# Bridge Spec: Front-Door ↔ muse.ai Side Conversations
+
+## Overview
+Metadata bridge (not message relay) linking front-door chat channels
+(muse-dev.online) to muse.ai side conversations. Operators manage via
+front-door; agents work in muse.ai; the bridge provides organizational
+linkage via `channel_id`.
+
+## Architecture
+
+```
+Front-Door (muse-dev.online)          muse.ai (browser agents)
+┌─────────────────────┐               ┌─────────────────────┐
+│ #lobby              │               │ muse: side chats    │
+│ #ops                │◄── bridge ──►│ pip: side chats     │
+│ #operators          │   (metadata)  │ 646: side chats     │
+│ #fleet-status       │               └─────────────────────┘
+└─────────────────────┘
+         ▲
+    Operators manage here;
+    agents work there.
+    Bridge = channel_id mapping.
+```
+
+## Data Model
+
+### Bridge Mapping
+```json
+{
+  "bridge_id": "string (unique)",
+  "frontdoor_channel": "#ops | #lobby | #operators | #fleet-status",
+  "muse_side_chat_id": "string (from muse.ai)",
+  "agent": "muse | pip | 646",
+  "linked_at": "ISO8601",
+  "linked_by": "operator | agent",
+  "status": "active | archived"
+}
+```
+
+### Query Patterns
+- **By channel**: "Show all side chats for #ops" → list of {agent, side_chat_id, purpose, last_activity}
+- **By agent**: "Show 646's side chats" → list grouped by channel_id
+- **By purpose**: "Find onboarding side chats" → across agents
+
+## Storage
+
+**Location**: `~/Projects/NetVM/bridge/` on bl (operator-managed via SSH)
+
+**Files**:
+- `mappings.json` — array of bridge mapping objects
+- `channels.json` — front-door channel registry (id, name, purpose)
+
+**Why bl, not the browser**: The browser agents can't reliably persist files.
+Operators maintain the bridge via SSH (proven). Agents tag their side chats
+with `channel_id`; operators record the mapping.
+
+## API Extensions
+
+### `muse-chat-api.py`
+```
+sidechat bridge --channel <id>    # List side chats linked to a front-door channel
+sidechat tag <chat_id> --channel <id> --purpose <str>  # Tag a side chat with metadata
+```
+
+### Bridge CLI (new: `bin/bridge.py`)
+```
+bridge list --channel #ops       # Show mappings for a channel
+bridge add --agent 646 --chat <id> --channel #ops --purpose "incident-123"
+bridge remove <bridge_id>
+```
+
+## Workflow
+
+### Agent creates side chat
+1. Agent (e.g., 646) creates side chat in muse.ai UI
+2. Agent tags it: `sidechat tag <id> --channel #ops --purpose "tunnel-debug"`
+3. Bridge mapping recorded in `~/Projects/NetVM/bridge/mappings.json`
+4. Operator can now query: `bridge list --channel #ops` → sees 646's chat
+
+### Operator queries
+1. Operator: "What's happening in #ops?"
+2. `bridge list --channel #ops` → shows all linked side chats across agents
+3. Operator drills in: `muse-chat-api.py --account 646 sidechat use <id>` → reads messages
+
+### No message relay
+- Messages stay in their native system
+- Bridge is organizational, not communicative
+- Operators context-switch via the API, not via copied messages
+
+## Security
+
+- Bridge files on bl are operator-managed (SSH only)
+- Agents can tag their own side chats (via API)
+- Agents cannot modify other agents' mappings
+- Front-door channel membership controls who can query (e.g., #operators is private)
+
+## Implementation Status
+
+- [ ] `bin/bridge.py` CLI
+- [ ] `sidechat tag` command in muse-chat-api.py
+- [ ] `sidechat bridge` query command
+- [ ] `bridge/mappings.json` schema
+- [ ] Documentation
+
+## Notes
+
+- This is v0.1. The metadata model will evolve as 646 documents the DOM.
+- The bridge does NOT require muse.ai API changes — it's an operator-layer construct.
+- Future: Web UI for the bridge (operator dashboard showing channel → side chats).