From 840ccbccf6a3ce045dc3e6849b6a1d59ed2f5a09 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 9 Jan 2026 19:03:17 +0000
Subject: [PATCH] docs: add messages concept overview

---
 docs/concepts/messages.md     | 83 +++++++++++++++++++++++++++++++++++
 docs/docs.json                |  9 ++++
 docs/gateway/configuration.md |  1 +
 3 files changed, 93 insertions(+)
 create mode 100644 docs/concepts/messages.md

diff --git a/docs/concepts/messages.md b/docs/concepts/messages.md
new file mode 100644
index 000000000..7f06ae7a4
--- /dev/null
+++ b/docs/concepts/messages.md
@@ -0,0 +1,83 @@
+---
+summary: "Message flow, sessions, queueing, and reasoning visibility"
+read_when:
+  - Explaining how inbound messages become replies
+  - Clarifying sessions, queueing modes, or streaming behavior
+  - Documenting reasoning visibility and usage implications
+---
+# Messages
+
+This page ties together how Clawdbot handles inbound messages, sessions, queueing,
+streaming, and reasoning visibility.
+
+## Message flow (high level)
+
+```
+Inbound message
+  -> routing/bindings -> session key
+  -> queue (if a run is active)
+  -> agent run (streaming + tools)
+  -> outbound replies (provider limits + chunking)
+```
+
+Key knobs live in configuration:
+- `messages.*` for prefixes, queueing, and group behavior.
+- `agents.defaults.*` for block streaming and chunking defaults.
+- Provider overrides (`whatsapp.*`, `telegram.*`, etc.) for caps and streaming toggles.
+
+See [Configuration](/gateway/configuration) for full schema.
+
+## Sessions and devices
+
+Sessions are owned by the gateway, not by clients.
+- Direct chats collapse into the agent main session key.
+- Groups/channels get their own session keys.
+- The session store and transcripts live on the gateway host.
+
+Multiple devices/providers can map to the same session, but history is not fully
+synced back to every client. Recommendation: use one primary device for long
+conversations to avoid divergent context. The Control UI and TUI always show the
+gateway-backed session transcript, so they are the source of truth.
+
+Details: [Session management](/concepts/session).
+
+## Queueing and followups
+
+If a run is already active, inbound messages can be queued, steered into the
+current run, or collected for a followup turn.
+
+- Configure via `messages.queue` (and `messages.queue.byProvider`).
+- Modes: `interrupt`, `steer`, `followup`, `collect`, plus backlog variants.
+
+Details: [Queueing](/concepts/queue).
+
+## Streaming, chunking, and batching
+
+Block streaming sends partial replies as the model produces text blocks.
+Chunking respects provider text limits and avoids splitting fenced code.
+
+Key settings:
+- `agents.defaults.blockStreamingDefault` (`on|off`)
+- `agents.defaults.blockStreamingBreak` (`text_end|message_end`)
+- `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`)
+- `agents.defaults.blockStreamingCoalesce` (idle-based batching)
+- Provider overrides: `*.blockStreaming` and `*.blockStreamingCoalesce`
+
+Details: [Streaming + chunking](/concepts/streaming).
+
+## Reasoning visibility and tokens
+
+Clawdbot can expose or hide model reasoning:
+- `/reasoning on|off|stream` controls visibility.
+- Reasoning content still counts toward token usage when produced by the model.
+- Telegram supports reasoning stream into the draft bubble.
+
+Details: [Thinking + reasoning directives](/tools/thinking) and [Token use](/token-use).
+
+## Prefixes, threading, and replies
+
+Outbound message formatting is centralized in `messages`:
+- `messages.responsePrefix` and `messages.messagePrefix`
+- Reply threading via `replyToMode` and per-provider defaults
+
+Details: [Configuration](/gateway/configuration#messages) and provider docs.
diff --git a/docs/docs.json b/docs/docs.json
index 0de50a2bd..f04f1c3c8 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -37,6 +37,14 @@
       "source": "/model/",
       "destination": "/models"
     },
+    {
+      "source": "/messages",
+      "destination": "/concepts/messages"
+    },
+    {
+      "source": "/messages/",
+      "destination": "/concepts/messages"
+    },
     {
       "source": "/AGENTS.default",
       "destination": "/reference/AGENTS.default"
@@ -575,6 +583,7 @@
           "concepts/session-tool",
           "concepts/presence",
           "concepts/provider-routing",
+          "concepts/messages",
           "concepts/groups",
           "concepts/group-messages",
           "concepts/typing-indicators",
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index becbf7ce3..fbd7bbc8f 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -921,6 +921,7 @@ message envelopes). If unset, Clawdbot uses the host timezone at runtime.
 ### `messages`
 
 Controls inbound/outbound prefixes and optional ack reactions.
+See [Messages](/concepts/messages) for queueing, sessions, and streaming context.
 
 ```json5
 {