docs: fix session key examples

docs/cli/message.md

@@ -48,6 +48,7 @@ Target formats (`--to`):
   - Optional: `--media`, `--reply-to`, `--thread-id`, `--gif-playback`
   - Telegram only: `--buttons-json` (requires `"inlineButtons"` in `telegram.capabilities` or `telegram.accounts.<id>.capabilities`)
   - Telegram only: `--thread-id` (forum topic id)
+  - Slack only: `--thread-id` (thread timestamp; `--reply-to` uses the same field)
   - WhatsApp only: `--gif-playback`
 
 - `poll`

docs/concepts/session-tool.md

@@ -15,8 +15,8 @@ Goal: small, hard-to-misuse tool set so agents can list sessions, fetch history,
 - `sessions_spawn`
 
 ## Key Model
-- Main direct chat bucket is always the literal key `"main"`.
-- Group chats use `<provider>:group:<id>` or `<provider>:channel:<id>`.
+- Main direct chat bucket is always the literal key `"main"` (resolved to the current agent’s main key).
+- Group chats use `agent:<agentId>:<provider>:group:<id>` or `agent:<agentId>:<provider>:channel:<id>` (pass the full key).
 - Cron jobs use `cron:<job.id>`.
 - Hooks use `hook:<uuid>` unless explicitly set.
 - Node bridge uses `node-<nodeId>` unless explicitly set.

docs/providers/imessage.md

@@ -30,7 +30,7 @@ Minimal config:
 ## 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>`).
+- DMs share the agent's main session; groups are isolated (`agent:<agentId>:imessage:group:<chat_id>`).
 - If a multi-participant thread arrives with `is_group=false`, you can still isolate it by `chat_id` using `imessage.groups` (see “Group-ish threads” below).
 
 ## Requirements

docs/providers/msteams.md

@@ -333,7 +333,7 @@ Key settings (see `/gateway/configuration` for shared provider patterns):
 
 ## Routing & Sessions
 - Session keys follow the standard agent format (see [/concepts/session](/concepts/session)):
-  - Direct messages: `agent:<agentId>:msteams:dm:<userId>` (shared main session).
+  - Direct messages share the main session (`agent:<agentId>:<mainKey>`).
   - Channel/group messages use conversation id:
     - `agent:<agentId>:msteams:channel:<conversationId>`
     - `agent:<agentId>:msteams:group:<conversationId>`

docs/providers/signal.md

@@ -32,7 +32,7 @@ Minimal config:
 ## What it is
 - Signal provider via `signal-cli` (not embedded libsignal).
 - Deterministic routing: replies always go back to Signal.
-- DMs share the agent's main session; groups are isolated (`signal:group:<groupId>`).
+- DMs share the agent's main session; groups are isolated (`agent:<agentId>:signal:group:<groupId>`).
 
 ## The number model (important)
 - The gateway connects to a **Signal device** (the `signal-cli` account).

docs/providers/telegram.md

@@ -30,7 +30,7 @@ Minimal config:
 ## What it is
 - A Telegram Bot API provider owned by the Gateway.
 - Deterministic routing: replies go back to Telegram; the model never chooses providers.
-- DMs share the agent's main session; groups stay isolated (`telegram:group:<chatId>`).
+- DMs share the agent's main session; groups stay isolated (`agent:<agentId>:telegram:group:<chatId>`).
 
 ## Setup (fast path)
 ### 1) Create a bot token (BotFather)

docs/tools/agent-send.md

@@ -13,14 +13,14 @@ runtime on the current machine.
 
 - Required: `--message <text>`
 - Session selection:
-  - `--to <E.164>` derives the session key (normal direct-chat routing), **or**
+  - `--to <dest>` derives the session key (use delivery-style targets; group/channel targets preserve isolation), **or**
   - `--session-id <id>` reuses an existing session by id
 - Runs the same embedded agent runtime as normal inbound replies.
 - Thinking/verbose flags persist into the session store.
 - Output:
   - default: prints reply text (plus `MEDIA:<url>` lines)
   - `--json`: prints structured payload + metadata
-- Optional delivery back to a provider with `--deliver` + `--provider`.
+- Optional delivery back to a provider with `--deliver` + `--provider` (target formats match `clawdbot message --to`).
 
 If the Gateway is unreachable, the CLI **falls back** to the embedded local run.