docs: restructure docs into diataxis (#121)

docs/how-to/topics.md

@@ -0,0 +1,53 @@
+# Topics
+
+Topics bind Telegram forum threads to a specific project/branch context. They can also store resume tokens and a default agent per topic.
+
+## Enable topics
+
+```toml
+[transports.telegram.topics]
+enabled = true
+scope = "auto" # auto | main | projects | all
+```
+
+Your bot needs **Manage Topics** permission in the group.
+
+If any `projects.<alias>.chat_id` are configured, topics are managed in those project chats; otherwise topics are managed in the main chat.
+
+## Topic commands
+
+Run these inside a topic thread:
+
+| Command | Description |
+|---------|-------------|
+| `/topic <project> @branch` | Create a new topic bound to context |
+| `/ctx` | Show the current binding |
+| `/ctx set <project> @branch` | Update the binding |
+| `/ctx clear` | Remove the binding |
+| `/new` | Clear stored sessions for this topic |
+
+In project chats, omit the project: `/topic @branch` or `/ctx set @branch`.
+
+## Chat sessions
+
+Chat sessions store one resume token per chat (per sender in groups) so new messages can auto-resume without replying.
+
+Enable:
+
+```toml
+[transports.telegram]
+session_mode = "chat" # stateless | chat
+```
+
+Reset the stored session with `/new`.
+
+## State files
+
+- Topic state: `telegram_topics_state.json`
+- Chat sessions state: `telegram_chat_sessions_state.json`
+- Chat defaults (e.g. `/agent`): `telegram_chat_prefs_state.json`
+
+## Related
+
+- [Switch engines](switch-engines.md)
+- [Commands & directives](../reference/commands-and-directives.md)