docs: cron integration with --deliver flag

- CLI.md: add --deliver to run flags table + examples
- CONFIG.md: add Telegram config section with default_chat_id
- TELEGRAM.md: add Cron Integration section (prerequisites, setup,
  debugging, config reference)

Author: molty3000

docs/CLI.md

@@ -37,6 +37,7 @@
 | `--max-iter <n>` | int | `90` | Max think→act cycles |
 | `--thinking <level>` | string | profile default | Reasoning depth: `enabled`/`disabled`/`low`/`medium`/`high` |
 | `--sandbox` | bool | false | Execute shell commands inside Docker container |
+| `--deliver` | bool | false | Deliver the agent's final response to the configured Telegram `default_chat_id`. Requires `telegram.bot_token` + `telegram.default_chat_id` in config. Use with cron for scheduled agent tasks. |
 | `--interaction-mode <mode>` | string | `engaging` | Tool-call rendering: `engaging` (emoji narration) or `verbose` (raw tool output) |
 | `--no-color` | bool | false | Disable colored terminal output |
 | `--prompt-caching` | bool | false | Enable Anthropic/OpenAI/DeepSeek prompt caching markers |
@@ -324,7 +325,14 @@ odek run "Set up CI with GitHub Actions"
 # File attachments
 odek run --ctx go.mod "check go version"
 odek run -c main.go,util.go "refactor both files"
-odek run "@schema.sql design a migration plan"
+odek run "&#64;schema.sql design a migration plan"
+
+# Cron integration: deliver agent result to Telegram
+odek run --deliver "Daily weather forecast for Berlin"
+odek run --deliver "Check the CI pipeline status"
+
+# Systemd cron example (crontab -e):
+# */5 * * * * /usr/local/bin/odek run "Say hello" --deliver >> /tmp/odek-cron.log 2>&1
 ```
 
 ## Config priority

docs/CONFIG.md

@@ -272,6 +272,56 @@ and are available in `odek run`, `odek repl`, `odek continue`, and `odek serve`.
 
 See [docs/MCP.md](docs/MCP.md#odek-as-mcp-client) for detailed instructions.
 
+## Telegram
+
+The `telegram` section configures the Telegram bot integration and the `--deliver` flag.
+
+```json
+{
+  "telegram": {
+    "bot_token": "8610437446:AAElHFJ...",
+    "allowed_users": [8592463065],
+    "allowed_chats": [],
+    "poll_interval": 1,
+    "poll_timeout": 30,
+    "max_msg_length": 4096,
+    "session_ttl_hours": 24,
+    "log_level": "info",
+    "log_file": "",
+    "default_chat_id": 8592463065
+  }
+}
+```
+
+| Field | Env var | Default | Description |
+|-------|---------|---------|-------------|
+| `bot_token` | `ODEK_TELEGRAM_BOT_TOKEN` | — (required) | Telegram bot API token from @BotFather |
+| `allowed_users` | — | all | Restrict bot to specific user IDs |
+| `allowed_chats` | — | all | Restrict bot to specific chat IDs |
+| `poll_interval` | — | 1 | Seconds between poll cycles |
+| `poll_timeout` | — | 30 | Long-poll timeout (1-60 seconds) |
+| `max_msg_length` | — | 4096 | Max characters per message |
+| `session_ttl_hours` | — | 24 | Hours before inactive session expires |
+| `log_level` | — | info | Log level: debug, info, warn, error |
+| `log_file` | — | stderr | Log file path (empty = stderr) |
+| `default_chat_id` | — | 0 | **Required for `--deliver`** — numeric chat ID where `odek run --deliver` sends results. Get this from your bot's update or use a tool like `@userinfobot`. |
+
+### --deliver flag
+
+The `--deliver` flag on `odek run` sends the agent's final response to the configured
+`default_chat_id` as a plain text message. This enables **cron-based scheduled agent
+workflows** — no daemon needed.
+
+```bash
+# Run an agent task and deliver the result to Telegram
+odek run --deliver "Check the CI pipeline status"
+
+# Works with task text first too
+odek run "Daily summary" --deliver
+```
+
+See [docs/TELEGRAM.md](docs/TELEGRAM.md#cron-integration) for full cron setup instructions.
+
 ## odek init
 
 Create a config file template:

docs/TELEGRAM.md

@@ -378,6 +378,97 @@ This avoids binary overwrite races, stale HTTP/2 connections, and session contex
 
 A fire-and-forget goroutine sends `sendChatAction("typing")` every 4 seconds while the agent runs. Each API call is dispatched in its own goroutine so a slow or hanging HTTP call cannot block the ticker and permanently stop the indicator.
 
+## Cron Integration
+
+odek can run fully offline agent tasks and deliver the result to Telegram, enabling system cron-based scheduled agent workflows — no daemon or scheduler required.
+
+### How it works
+
+```
+cron daemon  ──[every N minutes]──►  odek run "<task>" --deliver
+                                           │
+                                    ┌──────┴──────┐
+                                    │  agent loop  │
+                                    │  (no daemon) │
+                                    └──────┬──────┘
+                                           │ result text
+                                           ▼
+                                    Telegram API
+                                           │
+                                    ┌──────┴──────┐
+                                    │  your chat   │
+                                    └─────────────┘
+```
+
+Each cron tick spawns an independent `odek run` process. The agent executes the task, produces a result, and exits. The `--deliver` flag sends the result to your configured Telegram chat as a plain text message. No persistent bot process, no long-polling — just a single agent run per tick.
+
+### Prerequisites
+
+1. **Telegram bot token** and **default chat ID** must be configured in `~/.odek/config.json`:
+
+```json
+{
+  "telegram": {
+    "bot_token": "8610437446:AAElHFJ...",
+    "default_chat_id": 8592463065
+  }
+}
+```
+
+2. **Verify delivery works** before setting up cron:
+
+```bash
+odek run "Say hello" --deliver
+```
+
+If no message arrives, check:
+- The bot token is valid (`curl https://api.telegram.org/bot<TOKEN>/getMe`)
+- The `default_chat_id` is correct (the numeric chat ID, not the username)
+- The binary is at a stable path (system cron uses a minimal PATH, so use the full path)
+
+### Setting up a cron job
+
+```bash
+# Edit your crontab
+crontab -e
+
+# Add a job — runs every 5 minutes
+*/5 * * * * /usr/local/bin/odek run "Say hello briefly" --deliver >> /tmp/odek-cron.log 2>&1
+```
+
+**Important:**
+- Use the **full absolute path** to the `odek` binary — cron runs with a minimal `PATH`
+- Always redirect stderr to a log file (`2>&1`) for debugging
+- Place `--deliver` **before** the task text, or anywhere after it (both work)
+- The agent runs in **single-shot mode** by default — no session persistence, no learning loop
+- Each cron tick is a fully independent agent invocation with no memory of previous runs
+
+### Debugging
+
+If messages don't arrive:
+
+```bash
+# 1. Verify the binary works standalone
+/usr/local/bin/odek run "test" --deliver
+
+# 2. Check cron's stderr log
+cat /tmp/odek-cron.log
+
+# 3. Confirm Telegram API is reachable from cron's environment
+# Add to crontab to test:
+# * * * * * curl -s "https://api.telegram.org/bot<TOKEN>/getMe" >> /tmp/telegram-test.log 2>&1
+
+# 4. Check that the config file is readable by cron's user
+ls -la ~/.odek/config.json
+```
+
+### Config reference
+
+| Config field | Env var | Description |
+|---|---|---|
+| `telegram.bot_token` | `ODEK_TELEGRAM_BOT_TOKEN` | Telegram bot API token (required) |
+| `telegram.default_chat_id` | — | Numeric chat ID to deliver results to (required) |
+
 ## Testing
 
 The Telegram package has **473 tests** with **87.1% coverage**. Tests use: