docs: restructure docs into diataxis (#121)

2026-01-13 15:59:27 +04:00
parent d0e9a51a0f
commit e292c99ab0
52 changed files with 1538 additions and 1255 deletions
@@ -0,0 +1,65 @@
+# Reference
+
+Reference docs are **authoritative and exact**. Use these when you need stable facts, schemas, and contracts.
+
+If you’re trying to achieve a goal (“enable topics”, “fetch a file”), use **[How-to](../how-to/index.md)**.  
+If you’re trying to understand the *why*, use **[Explanation](../explanation/index.md)**.
+
+## Most-used reference pages
+
+- [Commands & directives](commands-and-directives.md)
+  - Message prefixes like `/engine`, `/project`, and `@branch`
+  - In-chat commands like `/cancel`, `/new`, `/ctx`, `/file …`, `/topic …`
+- [Configuration](config.md)
+  - `takopi.toml` options and defaults
+  - Telegram transport options (sessions, topics, files, voice transcription)
+
+## Normative behavior
+
+- [Specification](specification.md)  
+  The normative (“MUST/SHOULD/MAY”) contract for:
+  - resume tokens + resume lines
+  - event model
+  - progress/final message semantics
+  - per-thread serialization rules
+
+## Plugins and extension contracts
+
+- [Plugin API](plugin-api.md)  
+  The **only** supported import surface for plugins: `takopi.api`
+- [Context resolution](context-resolution.md)  
+  How Takopi resolves project + worktree context from directives, replies, and chat ids.
+
+## Transport reference
+
+- [Telegram transport](transports/telegram.md)  
+  Rate limits, outbox behavior, retries, message editing rules.
+
+## Runner reference
+
+These are “engine adapter” implementation details: JSONL formats, mapping rules, and emitted events.
+
+- [Runners overview](runners/index.md)
+- Claude:
+  - [runner.md](runners/claude/runner.md)
+  - [stream-json-cheatsheet.md](runners/claude/stream-json-cheatsheet.md)
+  - [takopi-events.md](runners/claude/takopi-events.md)
+- Codex:
+  - [exec-json-cheatsheet.md](runners/codex/exec-json-cheatsheet.md)
+  - [takopi-events.md](runners/codex/takopi-events.md)
+- OpenCode:
+  - [runner.md](runners/opencode/runner.md)
+  - [stream-json-cheatsheet.md](runners/opencode/stream-json-cheatsheet.md)
+  - [takopi-events.md](runners/opencode/takopi-events.md)
+- Pi:
+  - [runner.md](runners/pi/runner.md)
+  - [stream-json-cheatsheet.md](runners/pi/stream-json-cheatsheet.md)
+  - [takopi-events.md](runners/pi/takopi-events.md)
+
+## For LLM agents
+
+If you’re an LLM agent contributing to Takopi, start here:
+
+- [Agent entrypoint](agents/index.md)
+- [Repo map](agents/repo-map.md)
+- [Invariants](agents/invariants.md) (runner contract, resume handling, “don’t break this” rules)