From ac35ba35949aa8db3fee37c2798cfdd49f7ffc7b Mon Sep 17 00:00:00 2001
From: banteg <4562643+banteg@users.noreply.github.com>
Date: Thu, 1 Jan 2026 01:35:30 +0400
Subject: [PATCH] docs: reorganize and refresh documentation

- move developing.md and specification.md into docs/

- update readme links to new locations

- add missing telegram.py module documentation

- fix engines.py location (was incorrectly under runners/)

- remove stale "moved to markdown.py" entries
---
 developing.md => docs/developing.md       | 18 +++++++++++++-----
 specification.md => docs/specification.md |  0
 readme.md                                 |  2 +-
 3 files changed, 14 insertions(+), 6 deletions(-)
 rename developing.md => docs/developing.md (92%)
 rename specification.md => docs/specification.md (100%)

diff --git a/developing.md b/docs/developing.md
similarity index 92%
rename from developing.md
rename to docs/developing.md
index 667eb0f..642e5ab 100644
--- a/developing.md
+++ b/docs/developing.md
@@ -40,7 +40,6 @@ The orchestrator module containing:
 | `handle_message()` | Per-message handler with progress updates and final render |
 | `ProgressEdits` | Throttled progress edit worker |
 | `_handle_cancel()` | `/cancel` routing |
-| `truncate_for_telegram()` | Moved to `markdown.py` |
 
 **Key patterns:**
 - Bridge schedules runs FIFO per thread to avoid concurrent progress messages; runner locks enforce per-thread serialization
@@ -64,6 +63,13 @@ The orchestrator module containing:
 | `prepare_telegram()` | Render + truncate for Telegram limits |
 | `truncate_for_telegram()` | Smart truncation preserving resume lines |
 
+### `telegram.py` - Telegram API wrapper
+
+| Component | Purpose |
+|-----------|---------|
+| `BotClient` | Protocol defining the bot client interface |
+| `TelegramClient` | HTTP client for Telegram Bot API (send, edit, delete messages) |
+
 ### `runners/codex.py` - Codex runner
 
 | Component | Purpose |
@@ -87,7 +93,6 @@ Transforms takopi events into human-readable text:
 | `ExecProgressRenderer` | Stateful renderer tracking recent actions for progress display |
 | `render_event_cli()` | Format a takopi event for CLI logs |
 | `format_elapsed()` | Formats seconds as `Xh Ym`, `Xm Ys`, or `Xs` |
-| `render_markdown()` | Moved to `markdown.py` |
 
 **Supported event types:**
 - `started`
@@ -101,13 +106,16 @@ Transforms takopi events into human-readable text:
 | `model.py` | Domain types: resume tokens, actions, events, run result |
 | `runner.py` | Runner protocol + event queue utilities |
 
+### `engines.py` - Engine backend registry
+
+Registers available engines and provides setup checks + runner construction.
+
 ### `runners/` - Runner implementations
 
 | File | Purpose |
 |------|---------|
-| `engines.py` | Engine backend registry (setup checks + runner construction) |
-| `runners/codex.py` | Codex runner (JSONL → takopi events) + per-resume locks |
-| `runners/mock.py` | Mock runner for tests/demos |
+| `codex.py` | Codex runner (JSONL → takopi events) + per-resume locks |
+| `mock.py` | Mock runner for tests/demos |
 
 ### `config.py` - Configuration loading
 
diff --git a/specification.md b/docs/specification.md
similarity index 100%
rename from specification.md
rename to docs/specification.md
diff --git a/readme.md b/readme.md
index 087746b..f9c47e8 100644
--- a/readme.md
+++ b/readme.md
@@ -113,7 +113,7 @@ Reply to a progress message with `/cancel` to stop the running execution.
 
 ## Development
 
-See [`developing.md`](developing.md) and `specification.md` for architecture and behavior details.
+See [`developing.md`](docs/developing.md) and [`specification.md`](docs/specification.md) for architecture and behavior details.
 
 ## License