docs: reorganize documentation structure

docs/providers/imessage.md

@@ -0,0 +1,93 @@
+---
+summary: "iMessage support via imsg (JSON-RPC over stdio), setup, and chat_id routing"
+read_when:
+  - Setting up iMessage support
+  - Debugging iMessage send/receive
+---
+# iMessage (imsg)
+
+Updated: 2026-01-06
+
+Status: external CLI integration. Gateway spawns `imsg rpc` (JSON-RPC over stdio).
+
+## What it is
+- iMessage provider backed by `imsg` on macOS.
+- Deterministic routing: replies always go back to iMessage.
+- DMs share the agent's main session; groups are isolated (`imessage:group:<chat_id>`).
+
+## Requirements
+- macOS with Messages signed in.
+- Full Disk Access for Clawdbot + `imsg` (Messages DB access).
+- Automation permission when sending.
+
+## Setup (fast path)
+1) Ensure Messages is signed in on this Mac.
+2) Configure iMessage and start the gateway.
+
+Example:
+```json5
+{
+  imessage: {
+    enabled: true,
+    cliPath: "imsg",
+    dmPolicy: "pairing",
+    allowFrom: ["+15555550123"]
+  }
+}
+```
+
+## Access control (DMs + groups)
+DMs:
+- Default: `imessage.dmPolicy = "pairing"`.
+- Unknown senders receive a pairing code; messages are ignored until approved.
+- Approve via:
+  - `clawdbot pairing list --provider imessage`
+  - `clawdbot pairing approve --provider imessage <CODE>`
+- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/pairing)
+
+Groups:
+- `imessage.groupPolicy = open | allowlist | disabled`.
+- `imessage.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.
+- Mention gating uses `routing.groupChat.mentionPatterns` (iMessage has no native mention metadata).
+
+## How it works (behavior)
+- `imsg` streams message events; the gateway normalizes them into the shared provider envelope.
+- Replies always route back to the same chat id or handle.
+
+## Media + limits
+- Optional attachment ingestion via `imessage.includeAttachments`.
+- Media cap via `imessage.mediaMaxMb`.
+
+## Addressing / delivery targets
+Prefer `chat_id` for stable routing:
+- `chat_id:123` (preferred)
+- `chat_guid:...`
+- `chat_identifier:...`
+- direct handles: `imessage:+1555` / `sms:+1555` / `user@example.com`
+
+List chats:
+```
+imsg chats --limit 20
+```
+
+## Configuration reference (iMessage)
+Full configuration: [Configuration](/configuration)
+
+Provider options:
+- `imessage.enabled`: enable/disable provider startup.
+- `imessage.cliPath`: path to `imsg`.
+- `imessage.dbPath`: Messages DB path.
+- `imessage.service`: `imessage | sms | auto`.
+- `imessage.region`: SMS region.
+- `imessage.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `imessage.allowFrom`: DM allowlist (handles or `chat_id:*`). `open` requires `"*"`.
+- `imessage.groupPolicy`: `open | allowlist | disabled` (default: open).
+- `imessage.groupAllowFrom`: group sender allowlist.
+- `imessage.groups`: per-group defaults + allowlist (use `"*"` for global defaults).
+- `imessage.includeAttachments`: ingest attachments into context.
+- `imessage.mediaMaxMb`: inbound/outbound media cap (MB).
+- `imessage.textChunkLimit`: outbound chunk size (chars).
+
+Related global options:
+- `routing.groupChat.mentionPatterns`.
+- `messages.responsePrefix`.