docs(sessions): document /handoff cross-platform session transfer (#23400)

Adds a Cross-Platform Handoff section to user-guide/sessions.md covering
the CLI flow, per-platform thread behavior (Telegram topics / Discord
threads / Slack message-anchored / no-thread fallback), failure modes,
and the resume-back-to-CLI loop.

Adds the /handoff entry to reference/slash-commands.md and updates the
CLI-only commands note.

website/docs/user-guide/sessions.md

@@ -127,6 +127,44 @@ display:
 Session IDs follow the format `YYYYMMDD_HHMMSS_<hex>` — CLI/TUI sessions use a 6-char hex suffix (e.g. `20250305_091523_a1b2c3`), gateway sessions use an 8-char suffix (e.g. `20250305_091523_a1b2c3d4`). You can resume by ID (full or unique prefix) or by title — both work with `-c` and `-r`.
 :::
 
+## Cross-Platform Handoff
+
+Use `/handoff <platform>` from a CLI session to transfer the live conversation to a messaging platform's home channel. The agent picks up exactly where the CLI left off — same session id, full role-aware transcript, tool calls and all.
+
+```bash
+# Inside a CLI session
+/handoff telegram
+```
+
+What happens:
+
+1. The CLI validates that `<platform>` is enabled and has a home channel set (run `/sethome` from the destination chat once to configure it).
+2. The CLI marks the session pending and **block-polls the gateway**. It refuses if the agent is mid-turn — wait for the current response to finish first.
+3. The gateway watcher claims the handoff and asks the destination adapter for a fresh thread:
+   - **Telegram** — opens a new forum topic (DM topics if Bot API 9.4+ Topics mode is enabled in the chat, or a forum supergroup topic).
+   - **Discord** — creates a 1440-min auto-archive thread under the home text channel.
+   - **Slack** — posts a seed message and uses its `ts` as the thread anchor.
+   - **WhatsApp / Signal / Matrix / SMS** — no native threads, falls back to the home channel directly.
+4. The gateway re-binds the destination key to your existing CLI session id, then forges a synthetic user turn asking the agent to confirm and summarize. The reply lands in the new thread.
+5. When the gateway acknowledges success, the CLI prints a `/resume` hint and exits cleanly:
+
+   ```
+   ↻ Handoff complete. The session is now active on telegram.
+     Resume it on this CLI later with: /resume my-session-title
+   ```
+
+6. From that point, the conversation lives on the platform. Reply in the new thread — anyone authorized in that channel shares the same session, and any later real user message in the thread joins seamlessly because thread sessions key without `user_id`.
+
+**Resume back to CLI:** when you want to come back to a desktop, just run `/resume <title>` (or `hermes -r "<title>"` from the shell) and pick up where the platform left off.
+
+**Failure modes:**
+- No home channel configured → CLI refuses with a `/sethome` hint.
+- Platform not enabled / gateway not running → CLI times out at 60s with a clear message and your CLI session stays intact.
+- Thread creation fails (permissions, topics-mode off) → falls back to the home channel directly and still completes; no thread isolation but the handoff itself works.
+- `adapter.send` fails (rate limit, transient API error) → handoff marked failed with the reason; the row clears so you can retry.
+
+**Limitation worth knowing:** for non-thread-capable platforms with multi-user group home channels, the synthetic turn keys as a DM-style session. This works for self-DM home channels (the typical setup) but isn't ideal for genuinely shared group chats. Threading covers Telegram / Discord / Slack — by far the common case — so most setups never hit this.
+
 ## Session Naming
 
 Give sessions human-readable titles so you can find and resume them easily.