@deadragdoll/tellymcp 0.0.10 → 0.0.12

package/README-ru.md

@@ -1,521 +1,371 @@
-# TellyMCP
+<div align="center">
 
-[English](README.md) | [Русский](README-ru.md) | [Standalone Guide](STANDALONE.md) | [Standalone RU](STANDALONE-ru.md) | [Screenshots](screenshots/README.md) | [Gallery](screenshots/GALLERY.md) | [Release Notes](VERSION.md)
+# TellyMCP
 
-[![npm version](https://img.shields.io/npm/v/%40deadragdoll%2Ftellymcp)](https://www.npmjs.com/package/@deadragdoll/tellymcp)
-[![npm downloads](https://img.shields.io/npm/dm/%40deadragdoll%2Ftellymcp)](https://www.npmjs.com/package/@deadragdoll/tellymcp)
-[![node >= 24](https://img.shields.io/badge/node-%3E%3D24-339933)](https://nodejs.org/)
-[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+**Telegram control plane для MCP-подключённых coding agents**
 
-TellyMCP — это self-hosted Telegram control plane для coding agents.
+[English](./README.md) · [Русский](./README-ru.md) · [Standalone](./docs/STANDALONE.md) · [Standalone RU](./docs/STANDALONE-ru.md)
 
-Он привязывает реальные agent-сессии к Telegram, делает их доступными с телефона и даёт им работать вместе между локальными и удалёнными машинами.
+[![npm version](https://img.shields.io/npm/v/@deadragdoll/tellymcp.svg)](https://www.npmjs.com/package/@deadragdoll/tellymcp)
+[![node](https://img.shields.io/badge/node-%3E%3D24-339933.svg)](https://nodejs.org/)
+[![license](https://img.shields.io/npm/l/@deadragdoll/tellymcp.svg)](./LICENSE)
+[![gateway--first](https://img.shields.io/badge/runtime-gateway--first-1f6feb.svg)](./README-ru.md#текущая-модель)
+[![telegram webhook](https://img.shields.io/badge/telegram-webhook%20%7C%20polling-26A5E4.svg)](./README-ru.md#webhook)
 
-Он не завязан на одного вендора или один coding assistant. Если агент умеет работать с MCP server, он может использовать TellyMCP.
+</div>
 
-## Зачем он нужен
+`@deadragdoll/tellymcp` — Telegram control plane для MCP-подключённых coding agents.
 
-Coding agents полезны ровно до того момента, пока они не остаются одни в терминале:
+Текущая модель — gateway-first:
 
-- им нужно уточнение, пока тебя нет за компьютером
-- им нужен approval перед рискованным действием
-- им нужно передать скриншот, файл или note между сессиями
-- им нужно быстро подключить человека или другого агента, не ломая общий workflow
+- один gateway держит Telegram-бота, web app, проекты и live registry консолей
+- один или несколько agent-процессов подключаются к этому gateway
+- каждая запущенная консоль агента — отдельный routable target
+- пользователь работает через gateway-бота, а не через pairing отдельных сессий
 
-TellyMCP даёт каждой сессии мобильную панель управления и collaboration layer:
+## Что умеет
 
-- `Live` tmux view и лёгкое управление из Telegram
-- session-scoped inbox и уведомления
-- workspace-aware handoff для файлов и note
-- локальную и удалённую коллаборацию между сессиями
-- поддержку mixed agent setups, если они умеют говорить по MCP
+- даёт MCP tools для human-in-the-loop через Telegram
+- позволяет одной консоли агента ставить задачу другой консоли
+- хранит structured xchange records в `.mcp-xchange`
+- поддерживает browser automation через Playwright
+- отдаёт Telegram Mini App / Live View с gateway
+- поддерживает polling и webhook на gateway
+- поставляет встроенный Codex plugin со skills под типовые workflow
 
-## Ключевые идеи продукта
+## Текущая модель
 
-- `Live` tmux view и управление внутри Telegram Mini App
-- `Collab`-сценарии для локальных и удалённых agent-сессий
-- `.mcp-xchange` как workspace-level handoff шина для note, файлов и скриншотов
-- MCP-native pairing сессий и session-scoped tools
-- optional gateway mode для multi-machine и multi-bot проектов
+Схема:
 
-## Human-in-the-loop — это только один слой системы
+```text
+Telegram user
+    |
+Telegram bot + WebApp
+    |
+Gateway
+    |
+    +-- Agent console A
+    +-- Agent console B
+    +-- Agent console C
+```
 
-Telegram HITL здесь тоже есть, но он не исчерпывает продукт:
+Следствия:
 
-- задавать человеку уточняющие вопросы через Telegram
-- получать несвязанные входящие сообщения позже через inbox
-- уведомлять человека о прогрессе, blockers и approvals
+- обычный flow больше не использует pairing
+- `/menu` в gateway-боте показывает live-консоли напрямую
+- межсессионная маршрутизация идёт по canonical `session_id = client_uuid:local_session_id`
+- несвязанные задачи читаются через structured xchange records, а не через старые inbox APIs
 
-## Что отличает TellyMCP от простого Telegram bot bridge
+## Основные поверхности
 
-- он завязан на сессии, а не только на чат
-- он понимает локальные и удалённые collaboration targets
-- у него есть live terminal surface, а не только обмен сообщениями
-- он передаёт файлы через workspace-aware exchange paths, а не просто через ad hoc upload
-- он может работать как standalone node или как gateway-backed control plane
+Для человека:
 
-## Типовые сценарии
+- `telegram_message`
+- `notify_telegram`
+- `browser_screenshot(send_to_telegram=true)`
 
-- держать долгоживущего агента доступным с телефона
-- запускать рядом разных агентов, если каждый умеет подключаться по MCP
-- подруливать tmux-сессией без ноутбука
-- маршрутизировать работу между `frontend`, `backend`, `review` и другими локальными сессиями
-- работать с удалёнными сессиями через gateway-backed project
-- передавать note, скриншоты и реальные файлы через `.mcp-xchange`
-- проверять локальный веб-интерфейс через `browser_*` tools и отправлять результат обратно в Telegram
+Для agent-to-agent:
 
-## Группы инструментов
+- `partner_note`
+- `send_partner_note`
+- `send_partner_file`
+- `list_gateway_sessions`
 
-- pairing и session context
-- Telegram ask/notify/inbox
-- `Live` tmux control
-- browser inspection и screenshots
-- partner notes и partner files
-- tools sync и version checks
+Для браузера:
 
-Важно для `Share`:
+- `browser_open`
+- `browser_click`
+- `browser_fill`
+- `browser_press`
+- `browser_wait_for`
+- `browser_screenshot`
 
-- текущая сессия должна выполнить работу сама
-- target-сессии отправляется только результат
-- исходное поручение не должно пересылаться дальше как новая задача
+Синхронизация инструкций:
 
-Полный список MCP tools лучше держать ниже по README и в самом MCP server, а не на первом экране.
+- `refresh_tools_markdown`
+- `.mcpsession.json` хранит startup identity и последний известный tools hash
 
-## Prerequisites
+## Требования
 
-- Node.js 24+
-- `tmux`
+- Node.js `>= 24`
 - Redis
-- Telegram bot token от BotFather
-- для `gateway` / `both`: Postgres
-- опционально для durable fanout на шлюзе: RabbitMQ
-
-## `tmux` настоятельно рекомендуется
-
-TellyMCP лучше всего работает, когда сам агент запущен внутри `tmux`.
+- PostgreSQL для gateway mode
+- опционально RabbitMQ для durable gateway fanout
+- Playwright browser binaries, если нужны browser tools
 
-Без `tmux` сервис всё равно может работать, но полноценный интерактивный режим будет неполным:
-
-- не будет `Live View`
-- не будет tmux `nudge`
-- не будет прямого управления tmux из Telegram Mini App
-
-Типичный старт:
+## Установка
 
 ```bash
-tmux new -s backend
+npm install -g @deadragdoll/tellymcp
 ```
 
-Позже можно просто подключиться:
+Если нужны browser tools:
 
 ```bash
-tmux attach -t backend
+tellymcp browser install
 ```
 
-Почему имя tmux-сессии важно:
-
-- по нему проще различать агентов
-- оно участвует в tmux-related UI и диагностике
-- с ним проще понимать, какую сессию ты открываешь в Telegram и `Live`
-
-Лучше использовать короткие осмысленные имена:
-
-- `backend`
-- `frontend`
-- `review`
-- `ops`
-
-Если агентов несколько, лучше запускать каждого в своей tmux-сессии или pane и привязывать отдельно.
+Если используешь Codex:
 
-Если tmux pane пересоздан и его `pane_id` изменился, TellyMCP теперь пытается автоматически восстановить актуальный target по сохранённым tmux session/window/pane hints.
-
-Если авто-восстановление не удалось, в Telegram придёт operational warning, а не только запись в backend log.
+```bash
+tellymcp codex-plugin install
+```
 
 ## Быстрый старт
 
-### 1. Standalone client без шлюза
-
-Это самый простой режим:
+### 1. Gateway
 
-- без shared gateway
-- без Postgres
-- без RabbitMQ
-
-Установка:
+Создай workspace и env:
 
 ```bash
-npm install -g @deadragdoll/tellymcp
+mkdir -p ~/telly-gateway
+cd ~/telly-gateway
+tellymcp init gateway
 ```
 
-Создай клиентский конфиг:
+Или возьми sample:
 
-```bash
-tellymcp init client
-```
+- [.env.example.gateway](./.env.example.gateway)
 
-В `.env` заполни минимум:
+Минимально важные значения:
 
 - `TELEGRAM_BOT_TOKEN`
-- `TELEGRAM_BOT_USERNAME`
 - `REDIS_HOST`
-- `MCP_HTTP_BEARER_TOKEN`
-
-Проверь конфиг:
-
-```bash
-tellymcp doctor --env .env
-```
+- `DB_HOST`
+- `DB_USER`
+- `DB_PASSWORD`
+- `DB_NAME`
+- `GATEWAY_PUBLIC_URL`
+- `GATEWAY_WS_URL`
+- `GATEWAY_TOKEN`
 
-Запусти сервис:
+Запуск:
 
 ```bash
 tellymcp run --env .env
 ```
 
-Локальный MCP endpoint в `client`-режиме:
-
-- `http://127.0.0.1:8787/mcp`
-
-Чтобы получить готовый JSON snippet для агента:
-
-```bash
-tellymcp mcp --help
-```
-
-### 2. Gateway или combined `both`
-
-Используй этот режим, если нужен:
-
-- `Collab` между машинами
-- проекты между разными ботами
-- gateway-relayed Live View
-- persistent gateway-side состояние по проектам и доставке
+### 2. Agent
 
-Создай конфиг:
+Для каждой консоли лучше отдельный workspace:
 
 ```bash
-tellymcp init gateway
+mkdir -p ~/agent-a
+cd ~/agent-a
+tellymcp init client
 ```
 
-или
+Или используй sample:
 
-```bash
-tellymcp init both
-```
+- [.env.example.client](./.env.example.client)
 
-В `.env` настроить:
+Минимально важные значения:
 
-- `DISTRIBUTED_MODE=gateway|both`
-- `PORT`
-- `ROOT_PREFIX=/api`
-- `TELEGRAM_BOT_TOKEN`
-- `REDIS_*`
-- `DB_*`
-- `WEBAPP_PUBLIC_URL`
 - `GATEWAY_PUBLIC_URL`
 - `GATEWAY_WS_URL`
-- при необходимости `RMQ_*`
+- `GATEWAY_TOKEN`
+- `GATEWAY_USER_UUID`, если консоль должна быть видна конкретному владельцу в gateway-боте
 
-Ожидаемый публичный ingress:
+Рекомендуется:
 
-- `/api/mcp`
-- `/api/webapp`
-- `/api/gateway`
-- `/api/healthz`
+- по умолчанию используется встроенный PTY terminal runtime
+- на первом запуске явно задать `TELLYMCP_SESSION_ID` и `TELLYMCP_SESSION_LABEL`
 
-Проверка:
+Первый запуск:
 
 ```bash
-tellymcp doctor --env .env
+tellymcp run --env .env -s NEW
 ```
 
-Запуск:
+После первого запуска `.mcpsession.json` хранит:
 
-```bash
-tellymcp run --env .env
-```
-
-Типовой публичный MCP endpoint:
+- `local_session_id`
+- `session_label`
+- `env_file`
 
-- `https://your-host.example/api/mcp`
+Поэтому дальше в том же каталоге обычно достаточно:
 
-## Mini App / Live
+```bash
+tellymcp run
+```
 
-Если `WEBAPP_ENABLED=true`, в меню сессии появляется `🖥 Live`.
+## Webhook
 
-Mini App:
+Gateway умеет работать через Telegram webhook.
 
-- обслуживается этим же Node service по `WEBAPP_BASE_PATH`
-- в `client`-режиме тоже может открываться через общий gateway domain
-- показывает видимую область tmux pane и отправляет ограниченный набор control actions
-- валидирует Telegram `initData` на сервере
-- умеет открываться в режимах:
-  - `default`
-  - `expand`
-  - `fullscreen` с fallback на `expand`
-- после успешного bootstrap удаляет временное launcher-сообщение
-- автоматически восстанавливается после короткого рестарта шлюза:
-  - краткий `502/503` переживается обычным polling
-  - если in-process WebApp session на шлюзе была потеряна и приходит `401/403`, Mini App сама делает повторный bootstrap
-  - в типовом restart-case переоткрывать `Live` не нужно
+Если nginx уже проксирует весь `/api/` на standalone HTTP listener gateway, отдельный `location` для webhook не обязателен. Route такой:
 
-## Docker: только для инфраструктуры или для `gateway`-only
+- `/api/telegram/webhook`
 
-Docker больше не является основным способом запуска TellyMCP, но один container path поддерживается:
+Нужные env:
 
-- запуск только `gateway`-ноды в контейнере
+```env
+TELEGRAM_WEBHOOK_ENABLED=true
+TELEGRAM_WEBHOOK_PATH=/telegram/webhook
+TELEGRAM_WEBHOOK_PUBLIC_URL=https://your-domain.example/api/telegram/webhook
+TELEGRAM_WEBHOOK_SECRET=change_me_webhook_secret
+```
 
-Это вариант именно для чистого control-plane узла:
+Когда webhook mode включён:
 
-- без локальных agent sessions
-- без локального `tmux`
-- не для `client`
-- не для `both`
+- gateway вызывает `setWebhook(...)` на старте
+- polling не запускается
+- секрет проверяется через `x-telegram-bot-api-secret-token`
 
-Плюс `docker-compose.yml` по-прежнему может поднимать локальную инфраструктуру:
+## MCP
 
-- `redis` для всех режимов
-- `postgres` для `gateway` / `both`
-- `rabbitmq` только если нужен durable fanout на шлюзе
+### Local HTTP
 
-Только Redis, для `standalone` или `client`:
+В client mode локальный MCP endpoint обычно:
 
-```bash
-docker compose up -d redis
-```
-
-Redis + Postgres, для `gateway` или `both`:
-
-```bash
-docker compose --profile gateway up -d
+```text
+http://127.0.0.1:8787/mcp
 ```
 
-Добавить RabbitMQ при необходимости:
+Helper:
 
 ```bash
-docker compose --profile gateway --profile rmq up -d
+tellymcp mcp --url http://127.0.0.1:8787/mcp
 ```
 
-Полный gateway stack в Docker:
-
-1. Скопировать пример:
+Для Codex и похожих агентов используй MCP HTTP endpoint, который поднимает `tellymcp run`.
 
-```bash
-cp .env.example.gateway .env-gateway
-```
+## Codex Plugin
 
-2. Отредактировать `.env-gateway` и задать минимум:
+Пакет включает локальный Codex plugin со skills для:
 
-- `TELEGRAM_BOT_TOKEN`
-- `TELEGRAM_BOT_USERNAME`
-- `WEBAPP_PUBLIC_URL`
-- `GATEWAY_PUBLIC_URL`
-- `GATEWAY_WS_URL`
-- `MCP_HTTP_BEARER_TOKEN`
+- ответов человеку в Telegram
+- `partner_note`
+- browser screenshot задач
+- artifact-return flow
 
-3. Запустить:
+Команды:
 
 ```bash
-docker compose up -d
+tellymcp codex-plugin status
+tellymcp codex-plugin install
 ```
 
-Это поднимет:
+Installer:
 
-- `redis`
-- `postgres`
-- `tellymcp-gateway`
+- копирует bundled plugin в managed local Codex path
+- обновляет personal marketplace manifest
+- ставит или обновляет plugin, если найден Codex CLI
 
-Внутри Docker compose сам переопределяет:
+## Browser Workflow
 
-- `MCP_HTTP_HOST=0.0.0.0`
-- `REDIS_HOST=redis`
-- `DB_HOST=postgres`
+Browser tools используют Playwright Chromium.
 
-Ожидаемые endpoint'ы:
+Предпочтительный путь:
 
-- `http://127.0.0.1:8080/api/healthz`
-- `http://127.0.0.1:8080/api/mcp`
-- `http://127.0.0.1:8080/api/webapp`
-- `http://127.0.0.1:8080/api/gateway`
+1. `browser_open`
+2. `browser_screenshot`
+3. дальше либо:
+   - `send_to_telegram=true` для ответа человеку
+   - `send_partner_file` для возврата артефакта другой консоли
 
-Остановить всё:
+Если browser runtime не установлен:
 
 ```bash
-docker compose down
+tellymcp browser install
 ```
 
-Сам TellyMCP при этом запускается напрямую на хосте:
-
-```bash
-tellymcp run --env .env
-```
-
-Для `client` и `both` по-прежнему рекомендуется именно хостовый запуск.
-
-## Как начать работу с ботом изнутри агента
-
-После подключения MCP можно просто написать агенту обычной фразой, что нужно привязаться к Telegram.
-
-Типовые фразы, которые агент должен понимать:
-
-- `привяжись к Telegram`
-- `подключись к Telegram`
-- `зарегистрируй эту сессию в Telegram`
-- `свяжи эту сессию с ботом`
-- `создай код привязки к Telegram`
-- `дай код для pairing с Telegram`
+Не подменяй browser workflow ad hoc shell-командами с Playwright, кроме случаев, когда ты отлаживаешь сам browser runtime.
 
-Ожидаемый flow:
+## Terminal Blockers
 
-1. Агент вызывает `create_session_pair_code`.
-2. Возвращается короткий код и, если возможно, deep link.
-3. Ты открываешь Telegram и отправляешь боту `/start <code>` или `/link <code>`.
-4. После успешной привязки можно открыть `/menu`.
+Gateway prompt scanner теперь живёт от live-client lifecycle:
 
-Если хочешь написать совсем явно, используй так:
+- на старте gateway scanner только armed, но не крутится вхолостую
+- реальная работа начинается после подключения live client
+- relay console materialization идёт из `hello` и owner-route hydration, а не из `/menu`
+- детект работает по хвосту захваченного terminal buffer
 
-```text
-Привяжись к Telegram и дай мне код для pairing.
-```
+Основная эвристика blocker-а:
 
-Если агент работает внутри `tmux`, ему желательно передать `cwd` и tmux-атрибуты уже на этапе pairing, чтобы `Live` и `nudge` заработали сразу.
+- подряд идущие numbered choices: `1.`, `2.`, `3.`
+- рядом есть action hints вроде `press`, `input`, `choose`, `enter`, `esc`, `yes`, `no`
+- в Telegram notice попадают и 1-2 строки контекста выше menu block
 
-## Telegram setup
+Когда blocker найден, gateway может отправить inline-кнопки:
 
-1. Открой BotFather.
-2. Создай бота через `/newbot`.
-3. Сохрани токен.
-4. Укажи `TELEGRAM_BOT_USERNAME`, если хочешь deep-link подсказки для pairing.
+- `1..N`
+- `Enter`
+- `Esc`
 
-## MCP helper
+Эти кнопки отправляют в консоль ровно цифру или terminal action. Навигация маркером не используется.
 
-TellyMCP сам не прописывает себя в конфиг агента.
+Операционные заметки:
 
-Команда:
+- одинаковый blocker fingerprint не перевысылается повторно
+- relay capture miss для offline agent считается debug-only шумом
+- `Storage` и `Screenshots` на gateway теперь relay-aware и читают metadata через gateway routes, а не через filesystem самого gateway
 
-```bash
-tellymcp mcp --help
-```
+## Collaboration
 
-печатает готовые snippets для:
+Проекты:
 
-- локального standalone клиента
-- общего gateway endpoint
-- варианта с bearer token
+- live presence консолей идёт из gateway live registry
+- membership проекта хранится отдельно от live presence
+- один client может иметь несколько live консолей одновременно
+- console participation в проекте хранится отдельно
 
-## Doctor
+Ожидаемое поведение агента:
 
-`doctor` mode-aware.
+- target резолвится через `list_gateway_sessions`
+- входящая работа читается через `list_xchange_records` и `get_xchange_record`
+- реальные файлы возвращаются через `send_partner_file`
+- `mark_xchange_record_read` вызывается только после успешного outbound reply
 
-В `client` режиме проверяет:
+## Файлы конфигурации
 
-- `tmux`
-- `.env`
-- Redis
-- локальный MCP bind
-- внешний `gateway healthz`, если задан `GATEWAY_PUBLIC_URL`
-- `GATEWAY_WS_URL`
-- `WEBAPP_PUBLIC_URL`
+Канонические стартовые точки:
 
-В `gateway` / `both` режиме проверяет:
+- [.env.example.gateway](./.env.example.gateway)
+- [.env.example.client](./.env.example.client)
 
-- `tmux`
-- `.env`
-- Redis
-- локальный `healthz`
-- публичный `healthz`
-- публичный `ws`
-- публичный `webapp`
-- Postgres
-- RabbitMQ, если настроен
+Bundled templates:
 
-## Ключевые переменные
+- [config/templates/env.gateway.template](./config/templates/env.gateway.template)
+- [config/templates/env.client.template](./config/templates/env.client.template)
+- [config/templates/env.both.template](./config/templates/env.both.template)
 
-Общие:
+Samples уже вычищены под текущий runtime:
 
-- `TELEGRAM_BOT_TOKEN`
-- `TELEGRAM_BOT_USERNAME`
-- `REDIS_HOST`
-- `REDIS_PORT`
-- `REDIS_DB`
-- `MODE=queue|reject`
-- `PAIR_CODE_TTL_SECONDS`
-- `MCP_HTTP_HOST`
-- `MCP_HTTP_PORT`
-- `MCP_HTTP_PATH`
-- `MCP_HTTP_BEARER_TOKEN`
-- `TMUX_SOCKET_PATH`
-- `TMUX_NUDGE_ENABLED`
-- `TMUX_NUDGE_DEBOUNCE_SECONDS`
-- `TMUX_NUDGE_COOLDOWN_SECONDS`
-- `WEBAPP_ENABLED`
-- `WEBAPP_BASE_PATH`
-- `WEBAPP_LAUNCH_MODE=default|expand|fullscreen`
-- `MCP_XCHANGE_DIR`
-- `PROXY_USE=http|socks5`
-- `HTTP_PROXY`
-- `SOCKS5_PROXY`
-- `LOG_LEVEL`
-- `LOG_FILE_ENABLED`
-- `LOG_FILE_PATH`
-
-Только client:
-
-- `DISTRIBUTED_MODE=client`
-- `GATEWAY_PUBLIC_URL`
-- `GATEWAY_WS_URL`
-- `GATEWAY_WS_PATH`
-- `GATEWAY_AUTH_TOKEN`
-
-Gateway / both:
+- убраны старые inbox-only настройки
+- убраны obsolete pairing-oriented тексты
+- убраны неиспользуемые секреты вроде `SESSION_SECRET`
+- убран неиспользуемый `APP_NAME`
 
-- `DISTRIBUTED_MODE=gateway|both`
-- `PORT`
-- `ROOT_PREFIX=/api`
-- `DB_HOST`
-- `DB_PORT`
-- `DB_USER`
-- `DB_PASSWORD`
-- `DB_NAME`
-- `RMQ_HOST`
-- `RMQ_PORT`
-- `RMQ_USER`
-- `RMQ_PASSWORD`
-- `RMQ_VHOST`
-- `RMQ_EXCHANGE`
+## Операционные команды
 
-Готовые шаблоны:
+Проверка окружения:
 
-- `.env.example.client`
-- `.env.example.gateway`
-- `tellymcp init client|gateway|both`
+```bash
+tellymcp doctor --env .env
+```
 
-## Что умеет
+Разрушительная очистка local+gateway state:
 
-Базовый поток такой:
+```bash
+tellymcp system-prune --env .env --yes
+```
 
-1. Агент создаёт или обновляет session context.
-2. Агент вызывает `create_session_pair_code`.
-3. Человек делает `/start <code>` или `/link <code>` в Telegram.
-4. После pairing бот открывает меню сессий, inbox, storage, local/collab и live view.
-5. Агент вызывает `ask_user_telegram` для связанной `session_id`.
-6. Ответ пользователя возвращается как MCP tool output.
-7. Несвязанные входящие Telegram-сообщения остаются в inbox этой сессии.
-8. Файлы и note попадают в `.mcp-xchange`.
+## Карта документации
 
-## Полезные команды
+- [README.md](./README.md)
+- [STANDALONE.md](./docs/STANDALONE.md)
+- [STANDALONE-ru.md](./docs/STANDALONE-ru.md)
+- [TOOLS.md](./TOOLS.md)
+- [screenshots/README.md](./screenshots/README.md)
 
-```bash
-tellymcp help
-tellymcp doctor --env .env
-tellymcp mcp --help
-tellymcp run --env .env
-```
+## Статус
 
-## Для разработки
+Этот README описывает текущую gateway-first модель.
 
-См.:
+Legacy concepts, которые не стоит использовать в новых setup:
 
-- [README.md](README.md)
-- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
-- [TOOLS.md](TOOLS.md)
+- pairing codes
+- session inbox APIs
+- `Local` partner menu
+- linked-session flows вне `partner_note` / project collaboration