docs: restructure docs into diataxis (#121)

docs/how-to/worktrees.md

@@ -0,0 +1,42 @@
+# Worktrees
+
+Use `@branch` to run tasks in a dedicated git worktree for that branch.
+
+## Enable worktree-based runs for a project
+
+Add a `worktrees_dir` (and optionally a base branch) to the project:
+
+```toml
+[projects.happy-gadgets]
+path = "~/dev/happy-gadgets"
+worktrees_dir = ".worktrees"      # relative to project path
+worktree_base = "master"          # base branch for new worktrees
+```
+
+## Run in a branch worktree
+
+Send a message like:
+
+```
+/happy-gadgets @feat/memory-box freeze artifacts forever
+```
+
+## Ignore `.worktrees/` in git status
+
+If you use the default `.worktrees/` directory inside the repo, add it to a gitignore.
+One option is a global ignore:
+
+```sh
+git config --global core.excludesfile ~/.config/git/ignore
+echo ".worktrees/" >> ~/.config/git/ignore
+```
+
+## Context persistence
+
+When project/worktree context is active, Takopi includes a `ctx:` footer in messages.
+When you reply, this context carries forward (you usually don’t need to repeat `/project @branch`).
+
+## Related
+
+- [Context resolution](../reference/context-resolution.md)
+