docs: restructure docs into diataxis (#121)

docs/reference/agents/index.md

@@ -0,0 +1,7 @@
+# For agents
+
+These pages are **high-signal reference** for LLM agents (and humans acting like one).
+
+- [Repo map](repo-map.md)
+- [Invariants](invariants.md)
+

docs/reference/agents/invariants.md

@@ -0,0 +1,35 @@
+# Invariants
+
+These are the “don’t break this” rules that keep Takopi reliable.
+
+## Runner contract
+
+The runner contract is enforced by `tests/test_runner_contract.py`:
+
+- Exactly one `StartedEvent`
+- Exactly one `CompletedEvent`
+- `CompletedEvent` is last
+- `CompletedEvent.resume == StartedEvent.resume`
+
+See also the [Plugin API](../plugin-api.md) runner contract section.
+
+## Per-thread serialization
+
+At most one active run may operate on the same thread/session at a time.
+This is enforced both by scheduling and by per-resume-token runner locks.
+
+Normative details live in the [Specification](../specification.md) (§5.2).
+
+## Resume lines
+
+Resume lines embedded in chat are the engine’s canonical resume command (e.g. `claude --resume <id>`).
+
+- The runner is authoritative for formatting and extraction.
+- Transports/rendering must preserve the resume line reliably (even when trimming/splitting).
+
+Normative details live in the [Specification](../specification.md) (§3).
+
+## Local contribution hygiene
+
+- Run `just check` before code commits.
+

docs/reference/agents/repo-map.md

@@ -0,0 +1,40 @@
+# Repo map
+
+Quick pointers for navigating the Takopi codebase.
+
+## Where things start
+
+- CLI entry point: `src/takopi/cli.py`
+- Telegram backend entry point: `src/takopi/telegram/backend.py`
+- Telegram bridge loop: `src/takopi/telegram/bridge.py`
+- Transport-agnostic handler: `src/takopi/runner_bridge.py`
+
+## Core concepts
+
+- Domain types (resume tokens, events, actions): `src/takopi/model.py`
+- Runner protocol: `src/takopi/runner.py`
+- Router selection and resume polling: `src/takopi/router.py`
+- Per-thread scheduling: `src/takopi/scheduler.py`
+- Progress reduction and rendering: `src/takopi/progress.py`, `src/takopi/markdown.py`
+
+## Engines and streaming
+
+- Runner implementations: `src/takopi/runners/*`
+- JSONL decoding schemas: `src/takopi/schemas/*`
+
+## Plugins
+
+- Public API boundary (`takopi.api`): `src/takopi/api.py`
+- Entrypoint discovery + lazy loading: `src/takopi/plugins.py`
+- Engine/transport/command backend loading: `src/takopi/engines.py`, `src/takopi/transports.py`, `src/takopi/commands.py`
+
+## Configuration
+
+- Settings model + TOML/env loading: `src/takopi/settings.py`
+- Config migrations: `src/takopi/config_migrations.py`
+
+## Docs and contracts
+
+- Normative behavior: [Specification](../specification.md)
+- Runner invariants: `tests/test_runner_contract.py`
+