docs: reorganize documentation structure

docs/reference/rpc.md

@@ -0,0 +1,35 @@
+---
+summary: "RPC adapters for external CLIs (signal-cli, imsg) and gateway patterns"
+read_when:
+  - Adding or changing external CLI integrations
+  - Debugging RPC adapters (signal-cli, imsg)
+---
+# RPC adapters
+
+Clawdbot integrates external CLIs via JSON-RPC. Two patterns are used today.
+
+## Pattern A: HTTP daemon (signal-cli)
+- `signal-cli` runs as a daemon with JSON-RPC over HTTP.
+- Event stream is SSE (`/api/v1/events`).
+- Health probe: `/api/v1/check`.
+- Clawdbot owns lifecycle when `signal.autoStart=true`.
+
+See [`docs/signal.md`](/signal) for setup and endpoints.
+
+## Pattern B: stdio child process (imsg)
+- Clawdbot spawns `imsg rpc` as a child process.
+- JSON-RPC is line-delimited over stdin/stdout (one JSON object per line).
+- No TCP port, no daemon required.
+
+Core methods used:
+- `watch.subscribe` → notifications (`method: "message"`)
+- `watch.unsubscribe`
+- `send`
+- `chats.list` (probe/diagnostics)
+
+See [`docs/imessage.md`](/imessage) for setup and addressing (`chat_id` preferred).
+
+## Adapter guidelines
+- Gateway owns the process (start/stop tied to provider lifecycle).
+- Keep RPC clients resilient: timeouts, restart on exit.
+- Prefer stable IDs (e.g., `chat_id`) over display strings.