feat: onboarding overhaul, persona-based setup (#132)

docs/how-to/chat-sessions.md

@@ -0,0 +1,43 @@
+# Chat sessions
+
+Chat sessions store one resume token per engine per chat (per sender in group chats), so new messages can auto-resume without replying. Reply-to-continue still works and updates the stored session for that engine.
+
+## Enable chat sessions
+
+```toml
+[transports.telegram]
+session_mode = "chat" # stateless | chat
+```
+
+With `session_mode = "chat"`, new messages in the chat continue the current thread automatically.
+
+## Reset a session
+
+Use `/new` to clear the stored session for the current scope:
+
+- In a private chat, it resets the chat.
+- In a group, it resets **your** session in that chat.
+- In a forum topic, it resets the topic session.
+
+See `/new` in [Commands & directives](../reference/commands-and-directives.md).
+
+## Resume lines and branching
+
+Chat sessions do not remove reply-to-continue. If resume lines are visible, you can reply to any older message to branch the conversation.
+
+If you prefer a cleaner chat, hide resume lines:
+
+```toml
+[transports.telegram]
+show_resume_line = false
+```
+
+## How it behaves in groups
+
+In group chats, Takopi stores a session per sender, so different people can work independently in the same chat.
+
+## Related
+
+- [Conversation modes](../tutorials/conversation-modes.md)
+- [Forum topics](topics.md)
+- [Commands & directives](../reference/commands-and-directives.md)

docs/how-to/index.md

@@ -11,8 +11,8 @@ If you need exact options and defaults, use **[Reference](../reference/index.md)
 - [Projects](projects.md) (register repos + run from anywhere)
 - [Worktrees](worktrees.md) (run work on `@branch` without switching your main checkout)
 - [Route by chat](route-by-chat.md) (dedicated chats per project)
-- [Topics](topics.md) (forum threads bound to repo/branch + auto-resume)
-- [Chat sessions](topics.md#chat-sessions) (auto-resume without replying)
+- [Topics](topics.md) (forum threads bound to repo/branch + per-topic defaults)
+- [Chat sessions](chat-sessions.md) (auto-resume without replying)
 
 ## Messaging extras
 

docs/how-to/topics.md

@@ -1,6 +1,19 @@
 # Topics
 
-Topics bind Telegram forum threads to a specific project/branch context. They can also store resume tokens and a default agent per topic.
+Topics bind Telegram **forum threads** to a project/branch context. Each topic keeps its own session and default agent, which is ideal for teams or multi-project work.
+
+## Why use topics
+
+- Keep each thread tied to a repo + branch
+- Avoid context collisions in busy team chats
+- Set a default agent per topic with `/agent set`
+
+## Requirements checklist
+
+- The chat is a **forum-enabled supergroup**
+- **Topics are enabled** in the group settings
+- The bot is an **admin** with **Manage Topics** permission
+- If you want topics in project chats, set `projects.<alias>.chat_id`
 
 ## Enable topics
 
@@ -10,44 +23,65 @@ enabled = true
 scope = "auto" # auto | main | projects | all
 ```
 
-Your bot needs **Manage Topics** permission in the group.
+### Scope explained
 
-If any `projects.<alias>.chat_id` are configured, topics are managed in those project chats; otherwise topics are managed in the main chat.
+- `auto` (default): uses `projects` if any project chats exist, otherwise `main`
+- `main`: topics only in the main `chat_id`
+- `projects`: topics only in project chats (`projects.<alias>.chat_id`)
+- `all`: topics available in both the main chat and project chats
 
-## Topic commands
+## Create and bind a topic
 
-Run these inside a topic thread:
+Run this inside a forum 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
+```
+/topic <project> @branch
 ```
 
-Reset the stored session with `/new`.
+Examples:
+
+- In the main chat: `/topic backend @feat/api`
+- In a project chat: `/topic @feat/api` (project is implied)
+
+Takopi will bind the topic and rename it to match the context.
+
+## Inspect or change the binding
+
+- `/ctx` shows the current binding
+- `/ctx set <project> @branch` updates it
+- `/ctx clear` removes it
+
+## Reset a topic session
+
+Use `/new` inside the topic to clear stored sessions for that thread.
+
+## Set a default agent per topic
+
+Use `/agent set` inside the topic:
+
+```
+/agent set claude
+```
 
 ## 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`
+Topic bindings and sessions live in:
+
+- `telegram_topics_state.json`
+
+## Common issues and fixes
+
+- **"topics commands are only available..."**
+  - Your `scope` does not include this chat. Update `topics.scope`.
+- **"chat is not a supergroup" / "topics enabled but chat does not have topics"**
+  - Convert the group to a supergroup and enable topics.
+- **"bot lacks manage topics permission"**
+  - Promote the bot to admin and grant Manage Topics.
 
 ## Related
 
+- [Projects and branches](../tutorials/projects-and-branches.md)
+- [Route by chat](route-by-chat.md)
+- [Chat sessions](chat-sessions.md)
+- [Multi-engine workflows](../tutorials/multi-engine.md)
 - [Switch engines](switch-engines.md)
-- [Commands & directives](../reference/commands-and-directives.md)

docs/how-to/troubleshooting.md

@@ -8,3 +8,10 @@ takopi --debug
 
 Then check `debug.log` for errors and include it when reporting issues.
 
+You can also run a preflight check:
+
+```sh
+takopi doctor
+```
+
+This validates your Telegram token, chat id, topics setup, file transfer permissions, and voice transcription configuration.