docs: restructure docs into diataxis (#121)

docs/tutorials/first-run.md

@@ -0,0 +1,32 @@
+# First run
+
+You’ll run Takopi in a repo, send a task from Telegram, and learn the basic controls.
+
+## 1) Start Takopi in a repo
+
+```sh
+cd ~/dev/your-repo
+takopi
+```
+
+## 2) Send a message to your bot
+
+Takopi streams progress in chat and posts a final message when the engine finishes.
+
+If you want to override the default engine for a single message, prefix the first line:
+
+```
+/codex explain this code
+/claude refactor this module
+```
+
+## 3) Continue or cancel
+
+- Continue the same thread by **replying** to any bot message that contains a resume line in the footer.
+- Cancel an in-flight run by clicking the cancel button or replying to the progress message with `/cancel`.
+
+## Next
+
+- [Projects](../how-to/projects.md) and [Worktrees](../how-to/worktrees.md)
+- [Commands & directives](../reference/commands-and-directives.md)
+

docs/tutorials/index.md

@@ -0,0 +1,41 @@
+# Tutorials
+
+Tutorials are **step-by-step learning paths**. If you’re new, start here and follow them in order.
+
+If you already know what you want to do (e.g. “enable topics” or “fetch a file”), jump to **How-to**.
+
+## Before you start
+
+You’ll need:
+
+- A Telegram account + a bot token
+- Python **3.14+** and `uv`
+- At least one engine CLI on your `PATH`: `codex`, `claude`, `opencode`, or `pi`
+
+## 1) Install and onboard
+
+Get Takopi installed, create a bot token, capture your chat id, and pick a default engine.
+
+- [Install & onboard](install-and-onboard.md)
+
+## 2) Your first run
+
+Run Takopi in a repo, send your first task from Telegram, and learn the two core controls:
+
+- reply-to-continue (resume)
+- cancel a run
+
+- [First run](first-run.md)
+
+## What to do next
+
+Once you can run tasks end-to-end, you’ll usually want:
+
+- Register a repo as a **project alias**: [How-to: Projects](../how-to/projects.md)
+- Run work on a branch in a dedicated **worktree**: [How-to: Worktrees](../how-to/worktrees.md)
+- Keep long-running work organized in threads: [How-to: Topics](../how-to/topics.md)
+
+When you need exact knobs and defaults:
+
+- [Reference: Configuration](../reference/config.md)
+- [Reference: Commands & directives](../reference/commands-and-directives.md)

docs/tutorials/install-and-onboard.md

@@ -0,0 +1,56 @@
+# Install & onboard
+
+You’ll install Takopi, connect it to Telegram, and generate a working `takopi.toml`.
+
+## Prerequisites
+
+- A Telegram account
+- Python 3.14+ and `uv`
+- At least one supported engine CLI on your `PATH` (`codex`, `claude`, `opencode`, or `pi`)
+
+## 1) Install Takopi
+
+```sh
+uv tool install -U takopi
+```
+
+## 2) Run onboarding
+
+Start Takopi:
+
+```sh
+takopi
+```
+
+If you want to re-run onboarding later:
+
+```sh
+takopi --onboard
+```
+
+The wizard walks you through:
+
+1. Creating a bot token via [@BotFather](https://t.me/BotFather)
+2. Capturing your `chat_id` (it listens for a message from you)
+3. Choosing a default engine
+
+Your configuration lives at `~/.takopi/takopi.toml`.
+
+## 3) Verify minimal config
+
+After onboarding you should have something like:
+
+```toml
+default_engine = "codex"
+transport = "telegram"
+
+[transports.telegram]
+bot_token = "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
+chat_id = 123456789
+```
+
+## Next
+
+- [First run](first-run.md)
+- [Config reference](../reference/config.md)
+