@deadragdoll/tellymcp 0.0.13 → 0.0.15

package/.env.example.client

@@ -1,21 +1,14 @@
-# TellyMCP client example
+# TellyMCP agent-console example. See docs/ENVIRONMENT.md for the complete contract.
 
-# Optional project label shown in prompts.
+# Workspace identity. NEW generates a stable value on first run.
 # PROJECT_NAME=
+TELLYMCP_SESSION_ID=NEW
+TELLYMCP_SESSION_LABEL=NEW
 
-# Optional explicit session identity for the first run.
-# TELLYMCP_SESSION_ID=NEW
-# TELLYMCP_SESSION_LABEL=NEW
-
-REDIS_HOST=127.0.0.1
-REDIS_PORT=6379
-REDIS_DB=1
-# REDIS_USERNAME=
-# REDIS_PASSWORD=
-
-MODE=reject
-PAIR_CODE_TTL_SECONDS=300
+# Local runtime state is process-local; Redis is not used by clients.
+TELEGRAM_REQUEST_MODE=reject
 
+# Local MCP endpoint exposed to the agent.
 MCP_HTTP_HOST=127.0.0.1
 MCP_HTTP_PORT=8787
 MCP_HTTP_PATH=/mcp
@@ -23,25 +16,26 @@ MCP_HTTP_PATH=/mcp
 MCP_HTTP_ENABLE_DEBUG_ROUTES=false
 MCP_HTTP_ENABLE_PRUNE_ROUTE=false
 
+# Gateway connection.
 DISTRIBUTED_MODE=client
 GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
 GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
-GATEWAY_WS_PATH=/api/gateway/ws
-GATEWAY_TOKEN=change_me_gateway_token
+# GATEWAY_WS_PATH=/api/gateway/ws
+# Optional data-scope key. Must match the gateway when used.
+GATEWAY_SCOPE_TOKEN=change_me_scope_token
+# Optional owner binding for Telegram visibility.
 GATEWAY_USER_UUID=
-# GATEWAY_AUTH_TOKEN=
+# Required shared HTTP/WebSocket transport credential.
+GATEWAY_AUTH_TOKEN=change_me_transport_token
 
+# Built-in PTY runtime.
 TERMINAL_SHELL=bash
 TERMINAL_COLS=120
 TERMINAL_ROWS=40
 TERMINAL_SCROLLBACK_LINES=4000
-
 TERMINAL_NUDGE_ENABLED=true
 TERMINAL_NUDGE_DEBOUNCE_SECONDS=10
 TERMINAL_NUDGE_COOLDOWN_SECONDS=30
-TERMINAL_NUDGE_MESSAGE=получи newest telegram_message через list_xchange_records/get_xchange_record, выполни запрос и ответь человеку через notify_telegram; не останавливайся на анализе
-TERMINAL_PARTNER_NUDGE_MESSAGE=получи newest partner_note через list_xchange_records/get_xchange_record, выполни задачу в текущей консоли и обязательно отправь результат через send_partner_note или send_partner_file; только потом mark_xchange_record_read
-TERMINAL_PARTNER_REPLY_NUDGE_MESSAGE=получи newest partner_note через list_xchange_records/get_xchange_record; если newest note имеет kind=reply или не требует ответа, не отправляй новый send_partner_note/send_partner_file без явного нового запроса. Если этот reply завершает задачу от человека, сразу отправь финальный результат в Telegram через notify_telegram или send_file_to_telegram; только потом mark_xchange_record_read
 TERMINAL_CAPTURE_MODE=visible
 TERMINAL_CAPTURE_LINES=300
 TERMINAL_PROMPT_SCAN_ENABLED=true
@@ -49,18 +43,8 @@ TERMINAL_PROMPT_SCAN_INTERVAL_SECONDS=15
 TERMINAL_PROMPT_SCAN_COOLDOWN_SECONDS=120
 TERMINAL_PROMPT_SCAN_STRATEGY=strict
 TERMINAL_PROMPT_SCAN_MIN_SCORE=5
-WEBAPP_ENABLED=true
-WEBAPP_BASE_PATH=/webapp
-WEBAPP_PUBLIC_URL=https://your-domain.example/api/webapp
-WEBAPP_INITDATA_TTL_SECONDS=300
-WEBAPP_SESSION_TTL_SECONDS=900
-WEBAPP_LAUNCH_MODE=fullscreen
-WEBAPP_VISIBLE_SCREENS=10
-WEBAPP_POLL_INTERVAL_MS=2000
-WEBAPP_ACTION_COOLDOWN_MS=150
-
-MCP_XCHANGE_DIR=.mcp-xchange
 
+# Browser automation and optional attach bridge.
 BROWSER_ENABLED=true
 BROWSER_HEADLESS=false
 BROWSER_DEVTOOLS=false
@@ -71,17 +55,17 @@ BROWSER_WAIT_UNTIL=load
 # BROWSER_EXECUTABLE_PATH=
 # BROWSER_CHANNEL=chrome
 BROWSER_SLOW_MO_MS=0
+# BROWSER_ATTACH_ENABLED=true
+# BROWSER_ATTACH_WS_HOST=127.0.0.1
+# BROWSER_ATTACH_WS_PORT=9999
+# BROWSER_ATTACH_WS_PATH=/browser-attach/ws
 
+MCP_XCHANGE_DIR=.mcp-xchange
 NAMESPACE=mcp
 NODE_ID=agent
-
-# Optional outbound proxy.
-# PROXY_USE=http
-# HTTP_PROXY=http://user:pass@proxy.example:3128
-# SOCKS5_PROXY=socks5h://user:pass@proxy.example:1080
-
 LOG_LEVEL=info
 LOG_FILE_ENABLED=false
 LOG_FILE_PATH=.tellymcp/log.jsonl
 # LOG_STDERR_LEVEL=error
-ENABLE_LOGFEED=0
+# LOG_FILE_LEVEL=info
+LOGFEED_ENABLED=false

package/.env.example.gateway

@@ -1,7 +1,35 @@
-# TellyMCP gateway example
+# TellyMCP gateway example. See docs/ENVIRONMENT.md for the complete contract.
 
+# Required gateway identity and infrastructure.
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_BOT_USERNAME=
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_DB=1
+# REDIS_USERNAME=
+# REDIS_PASSWORD=
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_USER=user
+DB_PASSWORD=password
+DB_NAME=mydb
+DB_SCHEMA=mcp
+
+# Public gateway transport.
+DISTRIBUTED_MODE=gateway
+GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
+GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
+# Optional data-scope key. This is not an authentication credential.
+GATEWAY_SCOPE_TOKEN=change_me_scope_token
+# Required shared HTTP/WebSocket transport credential.
+GATEWAY_AUTH_TOKEN=change_me_transport_token
+ROOT_PREFIX=/api
+PORT=8080
+MCP_HTTP_HOST=0.0.0.0
+MCP_HTTP_PATH=/mcp
+
+# Request handling and operator access.
+TELEGRAM_REQUEST_MODE=reject
 # ADMIN_TOKEN=
 # DEBUG_LANGUAGE=ru
 
@@ -13,40 +41,24 @@ TELEGRAM_BOT_USERNAME=
 # TELEGRAM_WEBHOOK_TRACE=false
 # TELEGRAM_WEBHOOK_DROP_PENDING_UPDATES=false
 
-REDIS_HOST=127.0.0.1
-REDIS_PORT=6379
-REDIS_DB=1
-# REDIS_USERNAME=
-# REDIS_PASSWORD=
-
-MODE=reject
-PAIR_CODE_TTL_SECONDS=300
-
-MCP_HTTP_HOST=127.0.0.1
-MCP_HTTP_PORT=8787
-MCP_HTTP_PATH=/mcp
+# Optional static bearer auth for internal MCP clients.
 # MCP_HTTP_BEARER_TOKEN=
 MCP_HTTP_ENABLE_DEBUG_ROUTES=false
 MCP_HTTP_ENABLE_PRUNE_ROUTE=false
 
-DISTRIBUTED_MODE=gateway
-GATEWAY_PUBLIC_URL=https://your-domain.example/api/gateway
-GATEWAY_WS_URL=wss://your-domain.example/api/gateway/ws
-GATEWAY_WS_PATH=/api/gateway/ws
-GATEWAY_TOKEN=change_me_gateway_token
-# GATEWAY_AUTH_TOKEN=
-
-ROOT_PREFIX=/api
-PORT=8080
-NAMESPACE=mcp
-NODE_ID=GWAY
-
-DB_HOST=127.0.0.1
-DB_PORT=5432
-DB_USER=
-DB_PASSWORD=
-DB_NAME=
-DB_SCHEME=mcp
+# ChatGPT / Claude OAuth facade. Setting any OAuth value enables it.
+# TELLYMCP_PUBLIC_URL=https://your-domain.example/api
+# TELLYMCP_OAUTH_ISSUER=https://your-domain.example/api
+# TELLYMCP_OAUTH_AUDIENCE=https://your-domain.example/api
+# TELLYMCP_MAGIC_TOKEN=change_me_private_connector_token
+# TELLYMCP_MAGIC_TOKEN_HASH=sha256:<hex>
+# TELLYMCP_OAUTH_CLIENT_ID=tellymcp
+# TELLYMCP_OAUTH_CLIENT_SECRET=
+# TELLYMCP_ALLOWED_REDIRECT_URIS=https://chatgpt.com/connector/oauth/...,https://claude.ai/api/mcp/auth_callback
+# TELLYMCP_OAUTH_PRIVATE_KEY_PEM="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+# TELLYMCP_AUTH_CODE_TTL_SECONDS=300
+# TELLYMCP_OAUTH_SCOPES=tellymcp:read tellymcp:write
+# TELLYMCP_OAUTH_KEY_ID=tellymcp-oauth
 
 # Optional RabbitMQ fanout.
 # RMQ_HOST=127.0.0.1
@@ -56,54 +68,33 @@ DB_SCHEME=mcp
 # RMQ_VHOST=/
 # RMQ_EXCHANGE=telegram_mcp.gateway
 
+# Telegram Mini App.
 WEBAPP_ENABLED=true
 WEBAPP_BASE_PATH=/webapp
 WEBAPP_PUBLIC_URL=https://your-domain.example/api/webapp
 WEBAPP_INITDATA_TTL_SECONDS=300
 WEBAPP_SESSION_TTL_SECONDS=900
 WEBAPP_LAUNCH_MODE=fullscreen
-WEBAPP_VISIBLE_SCREENS=10
-WEBAPP_POLL_INTERVAL_MS=2000
+WEBAPP_VISIBLE_SCREENS=2
 WEBAPP_ACTION_COOLDOWN_MS=150
 
-MCP_XCHANGE_DIR=.mcp-xchange
-
-TERMINAL_SHELL=bash
-TERMINAL_COLS=120
-TERMINAL_ROWS=40
-TERMINAL_SCROLLBACK_LINES=4000
-
-TERMINAL_NUDGE_ENABLED=true
-TERMINAL_NUDGE_DEBOUNCE_SECONDS=10
-TERMINAL_NUDGE_COOLDOWN_SECONDS=30
-TERMINAL_NUDGE_MESSAGE=получи newest telegram_message через list_xchange_records/get_xchange_record, выполни запрос и ответь человеку через notify_telegram; не останавливайся на анализе
-TERMINAL_PARTNER_NUDGE_MESSAGE=получи newest partner_note через list_xchange_records/get_xchange_record, выполни задачу в текущей консоли и обязательно отправь результат через send_partner_note или send_partner_file; только потом mark_xchange_record_read
-TERMINAL_PARTNER_REPLY_NUDGE_MESSAGE=получи newest partner_note через list_xchange_records/get_xchange_record; если newest note имеет kind=reply или не требует ответа, не отправляй новый send_partner_note/send_partner_file без явного нового запроса. Если этот reply завершает задачу от человека, сразу отправь финальный результат в Telegram через notify_telegram или send_file_to_telegram; только потом mark_xchange_record_read
-TERMINAL_CAPTURE_MODE=visible
-TERMINAL_CAPTURE_LINES=300
+# Gateway-side terminal prompt detection.
 TERMINAL_PROMPT_SCAN_ENABLED=false
 TERMINAL_PROMPT_SCAN_INTERVAL_SECONDS=15
 TERMINAL_PROMPT_SCAN_COOLDOWN_SECONDS=120
 TERMINAL_PROMPT_SCAN_STRATEGY=strict
 TERMINAL_PROMPT_SCAN_MIN_SCORE=5
-BROWSER_ENABLED=false
-BROWSER_HEADLESS=false
-BROWSER_DEVTOOLS=false
-# BROWSER_ADDRESS=http://localhost:5173
-BROWSER_TIMEOUT_MS=20000
-BROWSER_MAX_EVENTS=200
-BROWSER_WAIT_UNTIL=load
-# BROWSER_EXECUTABLE_PATH=
-# BROWSER_CHANNEL=chrome
-BROWSER_SLOW_MO_MS=0
 
-# Optional outbound proxy.
+# Optional outbound proxy for Telegram.
 # PROXY_USE=http
 # HTTP_PROXY=http://user:pass@proxy.example:3128
 # SOCKS5_PROXY=socks5h://user:pass@proxy.example:1080
 
+NAMESPACE=mcp
+NODE_ID=gateway
 LOG_LEVEL=info
-LOG_FILE_ENABLED=true
+LOG_FILE_ENABLED=false
 LOG_FILE_PATH=.tellymcp/log.jsonl
 # LOG_STDERR_LEVEL=error
-ENABLE_LOGFEED=0
+# LOG_FILE_LEVEL=info
+LOGFEED_ENABLED=false

package/CHANGELOG.md

@@ -2,7 +2,52 @@
 
 ## Unreleased
 
+### Changed
+
+- CLI больше не загружает `node-pty` до разбора команды: `tellymcp --help`,
+  setup и diagnostics остаются доступны при отсутствующем native addon.
+  `doctor`, `run` и postinstall теперь реально проверяют `pty.node` и выводят
+  platform-aware инструкции для Linux ARM64, npm lifecycle scripts и rebuild.
+- Redis теперь используется только в режимах gateway и `both`. Client runtime
+  больше не подключается к Redis и не требует `REDIS_*`; временное состояние
+  хранится локально в процессе, а стабильный `gateway_client_uuid` — в
+  `.mcpsession.json`. Клиентские шаблоны, migration, configure, doctor, prune и
+  runtime diagnostics приведены к этой модели.
+
 ### Added
+
+- Добавлен локальный web-конфигуратор `tellymcp configure`: browser wizard
+  предлагает выбрать Client или Gateway, показывает role-specific поля,
+  формирует HTTP/WS/WebApp/webhook/OAuth URL из одного Public base URL,
+  показывает русские hints и примеры, выполняет role-specific live-check
+  Telegram, Redis, PostgreSQL, gateway HTTP/WS и RabbitMQ, затем скачивает
+  `.env-client` либо `.env-gateway`.
+- Добавлен безопасный MCP tool `get_runtime_diagnostics` для end-to-end проверки
+  версии/protocol, принятой env-схемы, runtime state store, PTY, gateway config и
+  gateway-to-client relay без вывода секретов; Redis проверяется только на gateway.
+- Добавлены связанные MCP tools `get_file_list` и `get_file` для получения
+  файлов из workspace выбранной live-консоли через gateway. Первый возвращает
+  список managed files и точные пути, второй принимает `file_path` либо
+  `selector=latest_screenshot`. По умолчанию `get_file(type="url")` возвращает
+  короткоживущую download-ссылку в `data`; временная gateway-копия хранится в
+  `.tellymcp/tmp/file-links`, а `type="base64"` остаётся fallback.
+- Добавлен явный режим `get_file(type="image")`: download URL остаётся в
+  `structuredContent.data`, сам structured type равен `image`, а изображение
+  возвращается отдельным нативным MCP-блоком, чтобы Claude и другие совместимые
+  клиенты могли рендерить его inline.
+- Для Claude.ai сохранён совместимый `type="base64"`: полный JSON вместе с raw
+  base64 в `data` возвращается обычным MCP text-блоком без native image, поскольку
+  некоторые MCP-host адаптеры заменяют изображение на `[image]` и скрывают
+  structured output от модели.
+- Добавлен `get_file(type="text")` для прямого чтения UTF-8 Markdown и исходников
+  через native MCP text-блок. Для `.ts`, `.tsx` и других source-расширений добавлены
+  текстовые MIME overrides.
+- Доступ к live `.env`, credential stores, private-key расширениям и чувствительным
+  директориям теперь блокируется на клиенте до чтения или отправки файла; выход
+  за workspace и через symlink по-прежнему запрещён.
+- Имена временных gateway-файлов очищаются до безопасного basename: управляющие
+  и файлово-зарезервированные символы заменяются перед сохранением и формированием
+  `Content-Disposition`.
 - Перенос `telegram_mcp` на сервисную архитектуру `Moleculer`:
   - `telegramMcp.runtime`
   - `telegramMcp.http`
@@ -74,6 +119,14 @@
   - безопасные packaged templates для `.env`
 
 ### Changed
+
+- Общее чтение workspace-файлов теперь проверяет реальный путь после разрешения
+  symlink и не позволяет выйти за пределы workspace.
+- Telegram Mini App Live Console переведена на WS-only rendering:
+  - HTTP polling и `/api/view` удалены
+  - после разрыва WebSocket автоматически восстанавливается с exponential backoff
+  - размеры xterm рассчитываются официальным `@xterm/addon-fit`
+  - resize колонок и строк передаётся локальным и relay PTY
 - Полностью убран legacy standalone MCP transport. `telegram_mcp` работает только через REST/MCP over HTTP.
 - Локальный standalone HTTP listener убран; `telegram_mcp` больше не поднимает отдельный сервер вне Moleculer gateway.
 - UI Telegram переосмыслен по двум режимам:
@@ -113,6 +166,10 @@
 - старый `go/node terminal-proxy` path полностью удалён, поддерживается только прямой локальный terminal runtime
 
 ### Fixed
+
+- Remote session-context actions больше не пытаются повторно уйти с client node
+  обратно в gateway без `clientUuid`; backend error payload дополнительно
+  ограничен по размеру, чтобы relay-сбой не создавал рекурсивный exception.
 - Исправлен `Headers have already sent` при работе MCP/WebApp через общий HTTP runtime.
 - Исправлены route/alias проблемы после перехода под `${ROOT_PREFIX}`.
 - Исправлены зависания Mini App bootstrap и проблемы с relative WebApp routes.

package/README-ru.md

@@ -27,6 +27,7 @@
 
 - даёт MCP tools для human-in-the-loop через Telegram
 - позволяет одной консоли агента ставить задачу другой консоли
+- позволяет MCP chat-клиенту получать проектный текст, изображения и артефакты выбранной консоли
 - хранит structured xchange records в `.mcp-xchange`
 - поддерживает browser automation через Playwright
 - умеет attach к уже открытому Firefox или Chrome через bundled local extensions
@@ -66,6 +67,7 @@ Gateway
 - `telegram_message`
 - `notify_telegram`
 - `browser_screenshot(send_to_telegram=true)`
+- `get_file` для возврата скриншотов и артефактов в MCP chat-клиент
 
 Для agent-to-agent:
 
@@ -74,6 +76,10 @@ Gateway
 - `send_partner_file`
 - `list_gateway_sessions`
 
+Для диагностики:
+
+- `get_runtime_diagnostics` для безопасной end-to-end проверки gateway/client
+
 Для браузера:
 
 - `browser_open`
@@ -87,6 +93,15 @@ Gateway
 - `browser_recording_stop`
 - `browser_recording_status`
 
+Файлы:
+
+- `get_file_list(source=..., limit=...)`
+- `get_file(file_path=..., type="url")`
+- `get_file(file_path=..., type="image")`
+- `get_file(file_path=..., type="text")`
+- `get_file(file_path=..., type="base64")`
+- `get_file(selector="latest_screenshot")`
+
 Синхронизация инструкций:
 
 - `refresh_tools_markdown`
@@ -95,17 +110,38 @@ Gateway
 ## Требования
 
 - Node.js `>= 24`
-- Redis
+- Python 3, `make` и C/C++ toolchain на Linux для локальной сборки native addon `node-pty`; npm lifecycle scripts должны быть включены
+- Redis только для режимов gateway и `both`; клиент Redis не использует
 - PostgreSQL для gateway mode
 - опционально RabbitMQ для durable gateway fanout
 - Playwright browser binaries, если нужны browser tools
 
 ## Установка
 
+На Debian/Ubuntu сначала установи зависимости для сборки native PTY:
+
+```bash
+sudo apt install -y python3 make g++
+npm config set ignore-scripts false
+```
+
+```bash
+npm install -g @deadragdoll/tellymcp --foreground-scripts
+```
+
+Опубликованная зависимость `node-pty` не содержит готового Linux ARM64 binary,
+поэтому install lifecycle собирает `pty.node` локально. Если пакет ранее
+установился без него, восстанови глобальную установку:
+
 ```bash
-npm install -g @deadragdoll/tellymcp
+npm rebuild -g @deadragdoll/tellymcp --foreground-scripts
+tellymcp doctor --env <file>
 ```
 
+`tellymcp --help` и setup-команды не загружают native PTY. Runtime проверяет
+модуль перед запуском и вместо сырого stack trace выводит те же инструкции по
+восстановлению.
+
 Если нужны browser tools:
 
 ```bash
@@ -139,9 +175,20 @@ tellymcp codex-plugin install
 ```bash
 mkdir -p ~/telly-gateway
 cd ~/telly-gateway
-tellymcp init gateway
+tellymcp configure
 ```
 
+Команда открывает защищённую одноразовым токеном локальную страницу на
+`127.0.0.1`. Выбери в wizard роль `Gateway`, заполни и проверь настройки, затем
+сохрани `.env-gateway` обычным browser download. Перед использованием выставь
+файлу права `0600`. `tellymcp init gateway` остаётся вариантом для ручного
+редактирования шаблона.
+
+Публичный origin или API base вводится один раз. Wizard сам формирует gateway
+HTTP, WebSocket, Mini App, webhook, root-prefix и опциональные OAuth URL.
+На ключевых этапах доступны реальные проверки Telegram, Redis, PostgreSQL,
+gateway HTTP/WebSocket и опционального RabbitMQ.
+
 Или возьми sample:
 
 - [.env.example.gateway](./.env.example.gateway)
@@ -156,7 +203,8 @@ tellymcp init gateway
 - `DB_NAME`
 - `GATEWAY_PUBLIC_URL`
 - `GATEWAY_WS_URL`
-- `GATEWAY_TOKEN`
+- `GATEWAY_SCOPE_TOKEN`
+- `GATEWAY_AUTH_TOKEN`
 
 Запуск:
 
@@ -171,9 +219,17 @@ tellymcp run --env .env
 ```bash
 mkdir -p ~/agent-a
 cd ~/agent-a
-tellymcp init client
+tellymcp configure
 ```
 
+Выбери в wizard роль `Client`. В форме есть подключение к gateway, identity
+консоли, terminal, browser, MCP и расширенные runtime-настройки. После
+валидации браузер скачает `.env-client`. Флаг `--no-open` выводит локальный URL
+без автоматического открытия браузера.
+
+Для клиента тот же Public base URL автоматически формирует
+`GATEWAY_PUBLIC_URL`, `GATEWAY_WS_URL` и `GATEWAY_WS_PATH`.
+
 Или используй sample:
 
 - [.env.example.client](./.env.example.client)
@@ -182,7 +238,8 @@ tellymcp init client
 
 - `GATEWAY_PUBLIC_URL`
 - `GATEWAY_WS_URL`
-- `GATEWAY_TOKEN`
+- `GATEWAY_SCOPE_TOKEN`
+- `GATEWAY_AUTH_TOKEN` (тот же transport-токен, который задан на gateway)
 - `GATEWAY_USER_UUID`, если консоль должна быть видна конкретному владельцу в gateway-боте
 
 Рекомендуется:
@@ -201,6 +258,10 @@ tellymcp run --env .env -s NEW
 - `local_session_id`
 - `session_label`
 - `env_file`
+- `gateway_client_uuid`
+
+Runtime-состояние клиента локальное и не требует Redis. Сохранённый
+`gateway_client_uuid` обеспечивает стабильную идентичность после перезапуска.
 
 Поэтому дальше в том же каталоге обычно достаточно:
 
@@ -340,6 +401,7 @@ Gateway prompt scanner теперь живёт от live-client lifecycle:
 
 Канонические стартовые точки:
 
+- [Контракт env и руководство по миграции](./docs/ENVIRONMENT.md)
 - [.env.example.gateway](./.env.example.gateway)
 - [.env.example.client](./.env.example.client)
 
@@ -355,6 +417,8 @@ Samples уже вычищены под текущий runtime:
 - убраны obsolete pairing-oriented тексты
 - убраны неиспользуемые секреты вроде `SESSION_SECRET`
 - убран неиспользуемый `APP_NAME`
+- неоднозначные старые имена заменены на `TERMINAL_*`, `GATEWAY_SCOPE_TOKEN`,
+  `TELEGRAM_REQUEST_MODE`, `DB_SCHEMA` и `LOGFEED_ENABLED`
 
 ## Операционные команды
 
@@ -370,11 +434,21 @@ tellymcp doctor --env .env
 tellymcp system-prune --env .env --yes
 ```
 
+Миграция старого env в текущий ролевой контракт:
+
+```bash
+tellymcp migrate-env ./old.env > ./.migrated-env
+```
+
+Fallback на старую схему отсутствует. Если найдены legacy-ключи, запуск
+останавливается и выводит команду миграции.
+
 ## Карта документации
 
 - [README.md](./README.md)
 - [STANDALONE.md](./docs/STANDALONE.md)
 - [STANDALONE-ru.md](./docs/STANDALONE-ru.md)
+- [CHAT_CONNECTOR.md](./docs/CHAT_CONNECTOR.md) — OAuth-коннектор ChatGPT/Claude
 - [TOOLS.md](./TOOLS.md)
 - [screenshots/README.md](./screenshots/README.md)