From c4d9f0273a8f33236d0790f87457da5388dc434b Mon Sep 17 00:00:00 2001
From: Jiayuan Zhang <forrestchang7@gmail.com>
Date: Tue, 17 Feb 2026 03:15:37 +0800
Subject: [PATCH] docs: clarify channel route key conversation binding

---
 docs/development.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/development.md b/docs/development.md
index e464c0fd..fefc24a2 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -75,6 +75,12 @@ Telegram behavior:
 - `/session <id>` switches the active conversation.
 - `/sessions` lists available conversations.
 
+Channel route behavior:
+
+- Runtime route key is `channelId:accountId:externalConversationId`.
+- Each route key is bound to one Hub `conversationId`.
+- Incoming/outgoing channel traffic is isolated per bound conversation (no global first-agent fallback).
+
 ## Local Full-Stack Notes (`pnpm dev:local`)
 
 `pnpm dev:local` is the recommended way to run the full local stack for integration work.