docs(opencode): integration guide — token scoping, tools, SAFE-T1401 note (closes #814)

docs/integrations/opencode.md

@@ -0,0 +1,94 @@
+# Molecule AI + opencode Integration
+
+> **opencode** is an AI coding agent ([opencode.ai](https://opencode.ai)) that supports remote MCP servers via `opencode.json`. This guide shows how to wire it to your Molecule AI workspace.
+
+## Prerequisites
+
+- A running Molecule platform (`MOLECULE_MCP_URL` — e.g. `https://api.molecule.ai`)
+- A workspace-scoped bearer token (`MOLECULE_MCP_TOKEN`) issued via the platform API
+
+## 1. Declare Molecule as a remote MCP server
+
+Create (or extend) `opencode.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "molecule": {
+      "type": "remote",
+      "url": "${MOLECULE_MCP_URL}",
+      "headers": { "Authorization": "Bearer ${MOLECULE_MCP_TOKEN}" },
+      "description": "Molecule AI A2A orchestration — delegate_task, list_peers, check_task_status"
+    }
+  }
+}
+```
+
+> ⚠️ **Never embed the token in the URL** (e.g. `?token=...`). Always use the `Authorization: Bearer` header. URL-embedded tokens appear in server logs, browser history, and Git history if the file is committed.
+
+A pre-configured template is available at `org-templates/molecule-dev/opencode.json`.
+
+## 2. Obtain a workspace-scoped token
+
+```bash
+curl -X POST https://$MOLECULE_MCP_URL/workspaces/$WORKSPACE_ID/tokens \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "opencode-agent", "scopes": ["mcp:read", "mcp:delegate"]}'
+```
+
+Store the returned token as `MOLECULE_MCP_TOKEN` in your `.env` (see `.env.example`).
+
+## 3. Available tools
+
+When opencode connects to the Molecule MCP endpoint, the agent gains access to:
+
+| Tool | Description |
+|------|-------------|
+| `list_peers` | Discover available workspaces in your org |
+| `delegate_task` | Send a task to a peer workspace and wait for the result |
+| `delegate_task_async` | Fire-and-forget task delegation; returns a `task_id` |
+| `check_task_status` | Poll an async delegation by `task_id` |
+| `commit_memory` | Persist information to LOCAL or TEAM memory scope |
+| `recall_memory` | Search previously committed memories |
+
+### Restricted tools
+
+- **`send_message_to_user`** — disabled for remote MCP callers by default; requires explicit opt-in via `MOLECULE_MCP_ALLOW_SEND_MESSAGE=true`
+- **GLOBAL memory scope** — `commit_memory` with `scope: GLOBAL` is blocked for external agents; LOCAL and TEAM scopes are available
+
+## 4. Example: delegate a research task
+
+```json
+{
+  "tool": "delegate_task",
+  "arguments": {
+    "target": "research-lead",
+    "task": "Summarise the last 7 days of commits in Molecule-AI/molecule-monorepo"
+  }
+}
+```
+
+opencode sends this tool call to the Molecule MCP endpoint. The platform routes it to your `research-lead` workspace and streams the response back.
+
+## 5. Security notes
+
+### SAFE-T1401 — org topology exposure
+`list_peers` returns the full set of workspace names and roles visible to your workspace. This is intentional: provisioned agents need to know their peers to delegate effectively. Be aware that any opencode agent with a valid `MOLECULE_MCP_TOKEN` can enumerate your org topology.
+
+### SAFE-T1201 — tool surface audit pending
+The full `@molecule-ai/mcp-server` npm package exposes additional tools beyond those listed above. These are pending a SAFE-T1201 security audit (tracked in #747 follow-on) and **should not be exposed to external agents in production** until that audit completes.
+
+### Token scoping
+Issue tokens with the minimum required scopes (`mcp:read`, `mcp:delegate`). Rotate tokens regularly. Revoke via `DELETE /workspaces/:id/tokens/:token_id`.
+
+## 6. Environment variables
+
+Add to your `.env`:
+
+```bash
+MOLECULE_MCP_URL=https://api.molecule.ai   # or http://localhost:8080 for local dev
+MOLECULE_MCP_TOKEN=                         # workspace-scoped bearer token from step 2
+```
+
+See `.env.example` for the canonical reference.