@retensy/mcp 0.11.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "retensy",
+  "owner": { "name": "retensy", "url": "https://bots.retensy.com" },
+  "description": "Плагины Retensy для Claude Code.",
+  "plugins": [
+    {
+      "name": "retensy-mcp",
+      "source": "./",
+      "description": "Сборка и публикация воронок ботов (Telegram/MAX/Instagram, Retensy Bots) из описания + публикация статей блога в Markdown — через MCP + скилл."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "retensy-mcp",
+  "displayName": "Retensy MCP",
+  "version": "0.11.0",
+  "description": "MCP-сервер + скилл для Retensy Bots: сборка и публикация воронок ботов (Telegram/MAX/Instagram) и публикация статей блога в Markdown — всё одним токеном zmcp_.",
+  "author": { "name": "retensy", "url": "https://bots.retensy.com" },
+  "homepage": "https://bots.retensy.com/bots",
+  "repository": "https://github.com/retensy/retensy-mcp",
+  "license": "MIT",
+  "keywords": ["mcp", "telegram", "bot", "funnel", "retensy", "no-code", "claude-code"],
+  "mcpServers": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "retensy-mcp": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/src/index.mjs"],
+      "env": {
+        "RETENSY_BASE_URL": "https://bots.retensy.com",
+        "RETENSY_MCP_TOKEN": "${RETENSY_MCP_TOKEN:-}"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 retensy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# retensy-mcp
+
+[![CI](https://github.com/retensy/retensy-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/retensy/retensy-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@retensy/mcp.svg)](https://www.npmjs.com/package/@retensy/mcp)
+[![node](https://img.shields.io/node/v/@retensy/mcp.svg)](https://nodejs.org)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+MCP-сервер (+ скилл для Claude Code) для **сборки и публикации воронок/автоматизаций ботов (Telegram, MAX и Instagram)** в сервисе [retensy `/bots`](https://bots.retensy.com/bots): из текстового описания → валидный граф сценария → заливка и публикация через API.
+
+- 🤖 **30 инструментов сборки/публикации**: `list_bots`, `list_graphs`, `list_channels`, `get_graph`, `create_graph`, `update_graph`, `edit_graph_live`, `patch_graph`, `dry_run`, `publish_graph`, `import_funnel`, `list_templates`, `create_graph_from_template`, `clone_graph`, `copy_graph`, `rename_graph`, `set_active_graph`, `delete_graph`, `upload_file`, `list_files`, `delete_file`, `graph_analytics`, `list_bot_users`, `list_links` (+ `setup`/`set_token`).
+- 📝 **Статьи блога** (тот же токен `zmcp_…`): `article_publish`, `article_update`, `article_list`, `article_get` — публикация статей в Markdown (как README на GitHub) в раздел **/articles**.
+- 📎 **Медиа**: `upload_file` грузит фото/видео/документы в библиотеку **/bots/files** (до 50 МБ) и возвращает публичный URL — его вставляешь в медиа-карточку сценария.
+- 🧠 **Скилл `build-bot-funnel`**: учит агента собирать корректный граф (типы узлов, ветки, кнопки, задержки) и проверять его перед публикацией. Поддерживает Telegram, MAX и Instagram.
+- 📦 **Без зависимостей** — чистый Node ≥18, ставится и запускается сразу.
+
+### Поддерживаемые платформы
+
+| Платформа | Онбординг | Триггеры входа | Ограничения |
+|---|---|---|---|
+| **Telegram** | Токен бота (BotFather) | `/start`, команды, callback, текст, рассылки | Полный функционал |
+| **MAX** | Токен бота (MAX Developer) | Команды, callback, текст | Без SUBSCRIBED/reply-клавиатур (мягкие предупреждения) |
+| **Instagram** | OAuth в `/growth` (без токена) | Комментарий/Direct/Ответ на историю/Упоминание | Ограниченный набор узлов; DELAY ≤ 24ч; ASK_QUESTION только TEXT/EMAIL/PHONE/NUMBER/CONTACT (CONTACT = ручной ввод номера); без рассылок |
+
+---
+
+## Установка
+
+### Вариант A — как плагин Claude Code (рекомендуется)
+
+```text
+/plugin marketplace add retensy/retensy-mcp
+/plugin install retensy-mcp@retensy
+```
+
+Подтянутся и MCP-сервер `bot-graph`, и скилл `build-bot-funnel`. Проверить: `/mcp` и `/plugin`.
+
+### Вариант B — как обычный MCP-сервер (Claude Code / Cursor / Windsurf / любой MCP-клиент)
+
+Через `npx` без установки. Пример конфига (`.mcp.json` / настройки клиента):
+
+```json
+{
+  "mcpServers": {
+    "retensy-mcp": {
+      "command": "npx",
+      "args": ["-y", "@retensy/mcp"],
+      "env": {
+        "RETENSY_BASE_URL": "https://bots.retensy.com",
+        "RETENSY_MCP_TOKEN": "zmcp_ваш_токен"
+      }
+    }
+  }
+}
+```
+
+См. также [`examples/.mcp.json`](examples/.mcp.json).
+
+---
+
+## Авторизация — персональный токен
+
+Токен даёт **полный доступ** к управлению твоими ботами (как вход в аккаунт).
+
+1. Залогинься на https://bots.retensy.com → открой **`/bots/mcp-tokens`**.
+2. Создай токен → скопируй секрет `zmcp_...` (показывается один раз).
+3. Передай токен любым способом:
+   - **просто пришли его агенту в чат** — он вызовет инструмент `set_token` и сохранит токен в `~/.retensy-bot-graph/token` (применяется сразу, без рестарта), **или**
+   - `env` в `.mcp.json` (Вариант B), **или**
+   - переменной окружения: PowerShell `setx RETENSY_MCP_TOKEN "zmcp_..."`, bash `export RETENSY_MCP_TOKEN="zmcp_..."`.
+
+Отозвать токен можно там же — доступ блокируется мгновенно.
+
+> **Не знаешь, что делать?** Скажи агенту «настрой подключение» — он вызовет `setup`, объяснит шаги и попросит токен. Любой инструмент при отсутствии токена тоже вернёт пошаговую инструкцию.
+
+> Дев-окружение: `RETENSY_BASE_URL=http://localhost:8066`.
+> Fallback без токена: `RETENSY_SESSION_COOKIE` = значение куки `SESSION` из браузера.
+
+---
+
+## Использование
+
+Опиши воронку словами — агент соберёт граф и (через MCP) опубликует:
+
+> «Собери бота: `/start` → приветствие с кнопкой подписки на канал → вопрос с 3 кнопками (бизнес / эксперт / просто смотрю) → для каждой свою цепочку из 2 сообщений с задержкой 1 день → финал с регистрацией на вебинар. Залей в бота и опубликуй.»
+
+Под капотом скилл соберёт `nodes/edges`, прогонит локальную проверку и вызовет `import_funnel` → создаст граф, зальёт узлы, прогонит `dry-run /start`, опубликует. При ошибках публикации — разберёт по `code`/`nodeId`, починит, повторит.
+
+### Инструменты
+
+| Tool | Назначение |
+|---|---|
+| `setup` | статус авторизации + пошаговая инструкция подключения |
+| `set_token` | сохранить присланный токен `zmcp_…` (без env/рестарта) |
+| `list_bots` | список ботов |
+| `list_graphs(botId)` | графы (сценарии) бота |
+| `list_channels(botId)` | каналы/группы, подключённые к боту (chatId для условия SUBSCRIBED) |
+| `get_graph(graphId, [summary], [saveToFile])` | получить граф; `summary:true` — компактная сводка (id/type/title + рёбра), `saveToFile` — записать полный JSON на диск (для больших графов, чтобы не упереться в лимит токенов) |
+| `create_graph(botId, name)` | создать пустой граф (DRAFT) |
+| `update_graph(graphId, graphFile\|graph\|nodes,edges)` | залить узлы/рёбра (PUT); `graphFile` — путь к локальному JSON, граф не нужно слать инлайном |
+| `edit_graph_live(graphId, graphFile\|graph\|nodes,edges)` | правка живого графа НА МЕСТЕ + авто-бэкап (рекомендуется для прода) |
+| `patch_graph(graphId, replacements)` | строковые замены в JSON графа на сервере (для больших/живых графов) |
+| `dry_run(graphId, kind, value)` | прогон без публикации |
+| `publish_graph(graphId)` | публикация (вернёт `errors[]` при провале) |
+| `import_funnel(botId, name, graphFile\|graph)` | всё за раз: create → update → dry-run → publish |
+| `list_templates()` | готовые шаблоны воронок |
+| `create_graph_from_template(botId, templateId, name)` | граф из шаблона (DRAFT) |
+| `clone_graph(graphId)` | копия графа в новый DRAFT |
+| `rename_graph(graphId, name)` | переименовать сценарий |
+| `set_active_graph(botId, graphId)` | переключить активный (живой) граф бота |
+| `delete_graph(graphId)` | удалить граф (активный — нельзя, 409) |
+| `upload_file(path\|url)` | загрузить файл в /bots/files → публичный `url` для медиа-карточки |
+| `list_files()` | файлы библиотеки /bots/files + использовано/лимит байт |
+| `delete_file(id)` | удалить файл из /bots/files |
+| `graph_analytics(graphId)` | прохождение сценария по узлам (где отваливается воронка) |
+| `list_bot_users(botId)` | подписчики/лиды бота (постранично, поиск `query`) |
+| `list_links(botId)` | стартовые трекинговые ссылки бота с UTM |
+| `article_list()` | свои статьи блога (id, slug, title, просмотры) |
+| `article_get(slug)` | статья по slug (Markdown content, excerpt, обложка) |
+| `article_publish(content, title?, cover?, excerpt?)` | новая статья (Markdown; title из `# ...`, если не задан; обложка из `cover`-URL или 1-й картинки → OG; `excerpt` явно или авто) → id, slug, URL |
+| `article_update(id, content, title?)` | обновить свою статью по id |
+
+---
+
+## Формат графа и проверка
+
+Граф — контейнер `retensy-bot-graph` (`nodes[]` + `edges[]`). Полная схема узлов/хэндлов и правила валидатора — в скилле:
+- [`skills/build-bot-funnel/reference/schema.md`](skills/build-bot-funnel/reference/schema.md)
+- [`skills/build-bot-funnel/reference/validation.md`](skills/build-bot-funnel/reference/validation.md)
+
+Локальная проверка графа перед заливкой:
+
+```bash
+# Telegram (по умолчанию)
+node skills/build-bot-funnel/validate.mjs path/to/import.json
+# Instagram-бот
+node skills/build-bot-funnel/validate.mjs path/to/import.json --platform=INSTAGRAM
+# MAX-бот
+node skills/build-bot-funnel/validate.mjs path/to/import.json --platform=MAX
+```
+
+---
+
+## Разработка
+
+```bash
+git clone https://github.com/retensy/retensy-mcp
+cd retensy-mcp
+RETENSY_MCP_TOKEN=zmcp_... node src/index.mjs   # стартует stdio MCP-сервер
+```
+
+Зависимостей нет — это голый JSON-RPC по stdio (протокол MCP `2024-11-05`).
+
+## Безопасность
+
+Токен = доступ к аккаунту по API. Не коммить его; держи в `env`. В конфигах храни ссылку `${RETENSY_MCP_TOKEN}`, не само значение.
+
+## Лицензия
+
+MIT — см. [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@retensy/mcp",
+  "version": "0.11.0",
+  "description": "MCP server to build and publish Telegram, MAX and Instagram bot funnels/automations — and publish Markdown blog articles — in the Retensy Bots service. Zero dependencies.",
+  "type": "module",
+  "bin": { "retensy-mcp": "src/index.mjs" },
+  "main": "src/index.mjs",
+  "publishConfig": { "access": "public" },
+  "files": ["src", "skills", ".mcp.json", ".claude-plugin", "README.md", "LICENSE"],
+  "scripts": {
+    "start": "node src/index.mjs",
+    "check": "node --check src/index.mjs",
+    "test": "node scripts/smoke.mjs",
+    "validate": "node skills/build-bot-funnel/validate.mjs"
+  },
+  "engines": { "node": ">=18" },
+  "keywords": ["mcp", "telegram", "max", "instagram", "bot", "funnel", "automation", "articles", "blog", "markdown", "retensy", "claude-code", "model-context-protocol"],
+  "repository": { "type": "git", "url": "git+https://github.com/retensy/retensy-mcp.git" },
+  "homepage": "https://bots.retensy.com/bots",
+  "license": "MIT"
+}

package/skills/build-bot-funnel/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: build-bot-funnel
+description: Собрать воронку (сценарий) бота для сервиса /bots из текстового описания — сгенерировать валидный граф формата retensy-bot-graph, проверить его и (через MCP bot-graph) залить в бота, прогнать dry-run и опубликовать. Поддерживает Telegram, MAX и Instagram. Использовать, когда пользователь описывает воронку/прогрев/сценарий бота словами и просит «собрать», «сделать граф», «залить в бота», «опубликовать сценарий».
+---
+
+# Сборка воронки бота (retensy /bots)
+
+Превращает **текстовое описание воронки** в валидный граф `retensy-bot-graph` и (опционально) публикует его через MCP-сервер `bot-graph`. Поддерживаются платформы **Telegram, MAX и Instagram** — у каждой свои триггеры и ограничения, описанные в schema.md.
+
+**Различия платформ (кратко):**
+- **Telegram** — полный функционал: `/start` и другие команды, все типы узлов, SUBSCRIBED, кнопки-контакты, рассылки.
+- **MAX** — те же узлы, но без SUBSCRIBED/reply-клавиатур (мягкие предупреждения при публикации, не блокируют).
+- **Instagram** — ограниченный набор узлов; вход только через комментарий/директ/историю (нет `/start`); нет рассылок; DELAY не более 24ч; ASK_QUESTION только TEXT/EMAIL/PHONE/NUMBER/CONTACT (CONTACT = ручной ввод номера, кнопки «Поделиться номером» в IG нет); онбординг через OAuth в разделе «Инструменты роста» (/growth), без токена бота.
+
+## Когда применять
+Пользователь описывает сценарий бота словами: приветствие → подписка → вопрос с кнопками → ветки → задержки → вебинар и т.п. Либо просит залить/опубликовать готовую воронку.
+
+## Рабочий процесс (делай по шагам)
+
+1. **Уточни вход.** Если описание неполное, спроси кратко: точка(и) входа (команда `/start` и т.п.), тексты сообщений, кнопки и куда они ведут, развилки/условия, задержки, финал. Не выдумывай маркетинговые тексты — проси у пользователя или помечай `[ВСТАВЬ ТЕКСТ]` только если он сам разрешил.
+
+2. **Спланируй граф.** Нарисуй в голове дерево: триггеры → сообщения → ветки. Каждой кнопке-выбору — свой выходной хэндл (`btn_0`, `btn_1`…). Подробности типов узлов и хэндлов: [reference/schema.md](reference/schema.md).
+
+3. **Сгенерируй JSON** формата `retensy-bot-graph` (см. схему). Требования к корректности (иначе не опубликуется) — в [reference/validation.md](reference/validation.md). Главное:
+   - У каждого `SEND_MESSAGE` непустой `config.text` (и продублируй в `cards[0].text`).
+   - id узлов и рёбер — валидные UUID, уникальные.
+   - Есть хотя бы один корневой `TRIGGER_*`; все нелистовые узлы достижимы от триггера; синхронных циклов нет (цикл только через `ASK_QUESTION`/`DELAY`/`SCHEDULE`).
+   - Кнопки-выборы разведены по хэндлам `btn_N` — у такой `CALLBACK`-кнопки `value` ОБЯЗАТЕЛЬНО пустой (`""`): бот сам сгенерит `callback_data`, непустой `value` ломает переход (`NO_MATCH`). Цвет кнопки — только `""`/`#34C759`/`#FF3B30`. Условия `CONDITION` — `yes`/`no`; вопрос (`ASK_QUESTION` или `SEND_MESSAGE` с `awaitReply:true`) — `valid`/`invalid`.
+   - **Не добавляй узлы `END`** — ветка завершается сама на узле без исходящих рёбер; явный «конец сценария» убран из редактора.
+   - `SEND_MESSAGE` умеет быть и сообщением, и **вопросом** (`awaitReply:true` + `saveTo`/`inputKind`/`validator`). У кнопок-ссылок (`kind:"URL"`) есть флаг `track:true` — на такой шаг ссылается условие `LINK_CLICKED`.
+   - **Медиа** (фото/видео/аудио/документ/кружок/галерея): загрузи файл инструментом `upload_file` (локальный `path` или `url` для перезаливки) → получишь публичный URL → вставь его в медиа-карточку `SEND_MESSAGE` (`url`, у `gallery` — `urls[]`) или в `SEND_PHOTO.photoUrl`. Уже загруженное — `list_files`. Бинарь в графе не хранится, только ссылки. Подробности — в schema.md.
+   - `CONDITION` умеет: теги, переменные, UTM-метки, имя/email/телефон из профиля, @username, подписку на канал (`SUBSCRIBED`), клик по ссылке шага (`LINK_CLICKED`), дату/время/день недели. Полная таблица `kind`/`op` — в schema.md.
+   - Пакет `ACTIONS` — до 30 действий (метки, профиль, HTTP, уведомления, интеграции GetCourse/amoCRM/Google Sheets/Я.Метрика, модерация группы). Список — в schema.md.
+
+4. **Проверь локально** перед заливкой:
+   ```bash
+   node "<путь к скиллу>/validate.mjs" <путь к import.json>
+   # Для IG-бота:
+   node "<путь к скиллу>/validate.mjs" <путь к import.json> --platform=INSTAGRAM
+   # Для MAX-бота:
+   node "<путь к скиллу>/validate.mjs" <путь к import.json> --platform=MAX
+   ```
+   Скрипт ловит пустые сообщения, висячие рёбра, дубли и не-UUID id узлов/рёбер, недостижимые узлы, превышение 4096, кривые DELAY (вкл. `duration`+`unit`), непустой `value` у кнопок-выборов с ребром `btn_N`, неподдерживаемые цвета. При `--platform=INSTAGRAM` дополнительно: IG-allowlist узлов (`IG_NODE_UNSUPPORTED`), DELAY > 24ч (`IG_DELAY_OVER_24H`), неподдерживаемый inputKind (`IG_INPUT_UNSUPPORTED`). Исправь всё, что он покажет.
+
+5. **Залей и опубликуй через MCP `bot-graph`** (если он подключён и пользователь просит публикацию):
+   - `list_bots` → выбрать `botId` (или `create_graph` в существующем боте).
+   - `create_graph(botId, name)` → получить `graphId`. Либо стартуй с готовой основы: `list_templates` → `create_graph_from_template(botId, templateId, name)`.
+   - `update_graph(graphId, nodes, edges, canvasMeta)` → залить узлы/рёбра.
+   - `dry_run(graphId, kind:"command", value:"start")` → прогнать стартовую ветку, проверить `runStatus`.
+   - `publish_graph(graphId)` → если вернулись `errors[]`, разобрать по `code`/`nodeId`, починить узлы, обновить, опубликовать снова.
+   - Управление сценариями: `clone_graph`, `rename_graph`, `set_active_graph` (переключить живой граф), `delete_graph` (активный нельзя — сначала переключи).
+   Если MCP не подключён — отдай готовый `import.json` и подскажи: /bots → граф → **Импорт**.
+
+5b. **Правка СУЩЕСТВУЮЩЕГО / живого сценария — по умолчанию `edit_graph_live`, а НЕ clone+publish.**
+   - Когда пользователь просит «поправь сценарий X» (особенно если он уже открыт в редакторе или опубликован) — правь **ТОТ ЖЕ `graphId`** через **`edit_graph_live(graphId, nodes, edges)`**. Он сам снимает авто-бэкап предыдущего состояния (один rolling-граф «🔙 Авто-бэкап») и делает PUT на месте — **id не меняется**.
+   - Почему так: бэкенд при PUT/публикации шлёт `external_update` в WS-комнату → открытые редакторы перечитывают граф **вживую** (юзеру не надо перезаходить). Бот читает активный граф **заново из БД на каждое сообщение** → правка живого PUBLISHED-графа применяется **сразу, без отдельной публикации**.
+   - `clone_graph`+`publish_graph` каждый раз плодят НОВЫЙ id и переключают активный → юзер вынужден открывать новый граф. Так делай только для крупного рискованного рефактора, где нужна изолированная песочница.
+   - ⚠️ PUT не валидирует (валидирует только `publish`) → перед `edit_graph_live` живого графа **обязательно** прогони `validate.mjs` + `dry_run`. Откат: опубликовать граф «🔙 Авто-бэкап» (или скопировать его содержимое обратно).
+
+6. **Отчитайся**: сколько узлов/веток, какие тексты помечены на проверку, ссылка/ id графа.
+
+## Важные ограничения
+- **Источник = текст** (этот режим). Если просят распознать с приватной Miro-доски — самый надёжный путь: CSV-экспорт из Miro; либо запуск залогиненного Chrome пользователя и съёмка экрана (headless WebGL-холст Miro не отдаёт). Это отдельный сценарий, не основной для этого скилла.
+- **Авторизация MCP** — персональный токен (создаётся в вебе на `/bots/mcp-tokens`, формат `zmcp_…`, полный доступ). Если инструмент вернул «нет токена» или ошибку доступа — **вызови `setup`**, объясни пользователю шаги, попроси прислать токен и сохрани его через **`set_token`** (применяется сразу, без env/рестарта). Также работают env `RETENSY_MCP_TOKEN` и session-cookie.
+- Бэкенд читает плоские поля `config.text`/`config.photoUrl`; редактор берёт текст из первой карточки `type:"text"`. Поэтому **всегда заполняй и `text`, и `cards`**.
+
+## Файлы скилла
+- [reference/schema.md](reference/schema.md) — формат графа, типы узлов, конфиги, хэндлы.
+- [reference/validation.md](reference/validation.md) — правила валидатора бэкенда (коды ошибок) и `cardsToLegacy`.
+- `validate.mjs` — оффлайн-проверка графа перед заливкой.

package/skills/build-bot-funnel/reference/schema.md

@@ -0,0 +1,193 @@
+# Формат графа `retensy-bot-graph`
+
+## Контейнер импорта
+```json
+{
+  "format": "retensy-bot-graph",
+  "version": 1,
+  "name": "Название воронки",
+  "nodes": [ /* TgNode[] */ ],
+  "edges": [ /* TgEdge[] */ ],
+  "canvasMeta": {}
+}
+```
+При заливке через MCP в `update_graph` передаются только `nodes`, `edges`, `canvasMeta`, `name`.
+
+## Узел (TgNode)
+```json
+{ "id": "<uuid>", "type": "<NodeType>", "config": { ... }, "position": { "x": 0, "y": 0 } }
+```
+- `id` — валидный UUID (8-4-4-4-12), уникальный.
+- `position` — раскладка на холсте (слева направо: шаг x ≈ 420; ветки разносим по y).
+
+## Ребро (TgEdge) — «стрелка»
+```json
+{ "id": "<uuid>", "sourceNodeId": "<uuid>", "sourceHandle": "next", "targetNodeId": "<uuid>" }
+```
+`sourceHandle` — какой выход узла используется (см. ниже).
+- `id`, `sourceNodeId`, `targetNodeId` — **валидные UUID** (бэкенд десериализует их как `java.util.UUID`; короткая строка вроде `"m1"` → HTTP 400 при заливке). `id` уникален среди рёбер.
+
+## Типы узлов (NodeType) и их config
+
+### Триггеры (точки входа, корневые)
+
+#### Telegram / MAX
+- `TRIGGER_COMMAND` — `{ "isRoot": true, "command": "start" }` (команда без `/`). Первый — с `isRoot:true`.
+- `TRIGGER_CALLBACK` — `{ "matchMode": "EQUALS"|"STARTS_WITH", "value": "<callback_data>" }`
+- `TRIGGER_TEXT` — `{ "matchMode": "ANY"|"EQUALS"|"CONTAINS"|"REGEX", "value": "..." }`
+- `BROADCAST_FILTER` — режим рассылки (если есть — единственный триггер).
+
+#### Instagram (только для IG-ботов)
+IG-боты не поддерживают команды (`/start`). Вход — через взаимодействие с контентом или директ:
+- `TRIGGER_IG_DM` — `{ "isRoot": true, "keywords": "хочу, каталог" }` — входящее сообщение в Instagram Direct. Это дефолтный триггер нового IG-графа (бэкенд сеет его при создании). `keywords` (опц.) — список через запятую или с новой строки; **регистронезависимо, совпадение по вхождению (contains)**; пусто = любое сообщение.
+- `TRIGGER_IG_COMMENT` — `{ "isRoot": true, "keywords": "купить, цена" }` — комментарий к посту или Reel бота. `keywords` (опц.) — список через запятую или с новой строки; регистронезависимый contains; пусто = любой комментарий.
+- `TRIGGER_IG_STORY_REPLY` — `{ "isRoot": true, "keywords": "хочу, вопрос" }` — ответ на историю бота. `keywords` (опц.) — список через запятую или с новой строки; регистронезависимый contains; пусто = любой ответ.
+- `TRIGGER_IG_STORY_MENTION` — `{ "isRoot": true }` — упоминание бота в истории подписчика. **Текста нет → фильтрация по ключевым словам не применяется**; срабатывает на каждое упоминание независимо от содержимого истории.
+
+> **Разные слова — разные сценарии:** добавь **несколько триггеров одного типа** с разными `keywords`; бэкенд берёт **первый совпавший по порядку узлов**. Триггер-«ловушку» с пустыми `keywords` (ловит всё) ставь **последним** — иначе он заблокирует все нижестоящие ключевые слова.
+
+Для всех IG-триггеров реакция бота отправляется через Instagram Messaging API в течение **24-часового окна** после последнего входящего действия пользователя.
+
+### Сообщения
+- `SEND_MESSAGE` —
+  ```json
+  { "_title": "Заголовок узла", "parseMode": "PLAIN"|"HTML"|"MARKDOWN",
+    "text": "Текст сообщения",
+    "cards": [ { "id": "c1", "type": "text", "text": "Текст сообщения" } ],
+    "buttons": [ [ { "text": "Кнопка", "kind": "CALLBACK"|"URL", "value": "<url для URL; ПУСТО для CALLBACK>", "color": "", "track": true } ] ] }
+  ```
+  ВСЕГДА заполняй и `text`, и `cards[0].text` одинаково. `buttons` — массив рядов (каждый ряд — массив кнопок).
+  - **Медиа-карточки** (`cards[].type`): `text`, `image`, `video`, `audio`, `file`, `voice`, `videonote` (кружок), `gallery` (альбом 2–10 фото), `question` (вопрос). У медиа-карточки ссылка на файл лежит в поле `url` (у `gallery` — массив `urls`). Сам файл (фото/видео/документ) в графе НЕ хранится — только URL. Чтобы получить URL, сперва загрузи файл инструментом **`upload_file`** (`path` локального файла или `url` для перезаливки) — он кладёт файл в библиотеку **/bots/files** и возвращает публичный `url`; его и вставляй в карточку. Примеры: `{ "id":"c2","type":"image","url":"https://bots.retensy.com/media/botmedia/<id>.jpg","text":"подпись (опц.)" }`, видео/аудио/файл/`voice`/`videonote` — так же с `url`; галерея — `{ "type":"gallery","urls":["https://…","https://…"] }`. Уже загруженные файлы — `list_files`, удалить — `delete_file`. Лимит 50 МБ; типы: image/video/audio/pdf/zip/doc(x)/xlsx/pptx/txt (SVG нельзя).
+  - `parseMode:"HTML"` (дефолт редактора) — текст должен быть **безопасным Telegram-HTML**: разрешены только `b,strong,i,em,u,ins,s,strike,del,code,pre,a[href],tg-spoiler,br`. Любой другой тег/атрибут → ошибка публикации `HTML_NOT_SAFE`. Не уверен — ставь `PLAIN`.
+  - **Кнопки-выборы (`kind:"CALLBACK"`)**: `value` ОСТАВЛЯЙ ПУСТЫМ (`""`). Бот сам сгенерит `callback_data` вида `n:<id узла>:<индекс>`, а переход задаётся ребром `btn_N` от кнопки. **Непустой `value`** трактуется как legacy-`callback_data` для отдельного узла `TRIGGER_CALLBACK` (у такой кнопки ребра `btn_N` быть не должно) — если поставить `value` обычной кнопке-выбору, переход по `btn_N` **сломается** (нажатие → `NO_MATCH`).
+  - **Кнопки-ссылки (`kind:"URL"`)**: `value` = URL. Могут иметь `"track": true` — клики считаются, и на такой шаг можно сослаться из условия `LINK_CLICKED` (см. ниже).
+  - **`color`** (опционально, и у CALLBACK, и у URL) — только стили, которые рендерит Telegram (как в основном боте / pengrad `ButtonStyle`): `""`=по умолчанию, `"#2EA6FF"`=primary (синий), `"#34C759"`=success (зелёный), `"#FF3B30"`=danger (красный). Других цветов нет.
+  - **Режим «Вопрос» (`awaitReply: true`)** — сообщение задаёт вопрос и ждёт ответ (паркуется как `ASK_QUESTION`). Доп. поля: `"saveTo":"name"` (обязателен, `[a-z_][a-z0-9_]{0,63}`), `"inputKind":"TEXT"|"PHOTO"|"DOCUMENT"|"CONTACT"|"LOCATION"`, `"validator":"ANY"|"PHONE"|"EMAIL"|"REGEX"`, `"regex":"..."`, `"retryText":"..."`, `"maxAttempts":3`. Выходы — `valid` / `invalid` (как у `ASK_QUESTION`), плюс `btn_N` для кнопок.
+  - **Канал ответа Instagram (`igReplyChannel`, только для IG-ботов)** — `"comment"` (по умолчанию) — публичный ответ под комментарием; `"dm"` — личное сообщение автору комментария (Private Reply). `"dm"` срабатывает только в графе с `TRIGGER_IG_COMMENT` (нужен `comment_id`): Meta разрешает **1 ЛС на комментарий**, 24-часовое окно на private reply не распространяется. Чтобы ответить и публично, и в ЛС — поставь два шага: один с `"igReplyChannel":"comment"`, второй с `"igReplyChannel":"dm"`.
+- `SEND_PHOTO` — `{ "photoUrl": "https://...", "caption": "подпись (необязательно, ≤1024)", "igReplyChannel": "comment"|"dm" }` (`igReplyChannel` — только IG, см. `SEND_MESSAGE`). `photoUrl` можно получить через `upload_file`.
+
+### Логика / ветвление
+- `CONDITION` — проверка условий, выходы `yes` / `no`. `{ "match":"ALL"|"ANY", "conditions":[ { "kind":"...", "op":"...", "key":"...", "value":"..." } ] }`. `match:"ALL"` — все условия истинны; `"ANY"` — хотя бы одно. Полный список `kind`/`op`/полей — в разделе [«Условия CONDITION»](#условия-condition).
+- `BRANCH` — `{ "cases":[ {"id":"c1","label":"...","expression":"var.x=='a'"} ], "hasDefault": false, "abTest": false }`. Выходы: `case_<id>` (+ `default`).
+- `ASK_QUESTION` — вопрос со сбором ответа. `{ "promptText":"...","saveTo":"name","inputKind":"TEXT"|"PHOTO"|"DOCUMENT"|"CONTACT"|"LOCATION","validator":"ANY"|"PHONE"|"EMAIL"|"REGEX","regex":"...","retryText":"...","maxAttempts":3 }`. `inputKind` (по умолчанию `TEXT`) — что ждём в ответ (`CONTACT` → телефон: в Telegram показывается кнопка «Поделиться номером», в MAX/Instagram кнопки нет — номер вводится вручную и принимается как телефон на всех платформах; `LOCATION` → `lat,lon`, `PHOTO`/`DOCUMENT` → file_id). Выходы `valid` / `invalid`.
+- `END` — `{}` (конец ветки). **Не добавляй `END`**: ветка и так завершается на узле без исходящих рёбер; явный «конец сценария» бесполезен и убран из палитры редактора. Тип оставлен лишь для совместимости со старыми графами.
+
+### Тайминги
+- `DELAY` — пауза. Три вида (`kind`):
+  - **`FIXED`** («Отправить через»): `{ "kind":"FIXED", "durationSec": 86400 }` — `durationSec` в **секундах** (60 = 1 мин, 3600 = 1 час, 86400 = 1 сутки). Редактор также пишет `{ "kind":"FIXED", "duration": 24, "unit":"MINUTES"|"HOURS"|"DAYS" }` (минуты/часы/дни — чтобы не вбивать большие числа). Для генерации проще `durationSec`.
+  - **`TOMORROW`** («Отправить завтра»): `{ "kind":"TOMORROW", "time":"18:00" }` — завтра в указанное время `HH:mm` (МСК), относительно момента, когда пользователь дошёл до узла.
+  - **`UNTIL`** («Отправить в»): `{ "kind":"UNTIL", "isoTimestamp":"2026-06-25T15:00:00Z" }` — конкретный момент в ISO-8601 (UTC). ⚠️ Рантайм читает только `isoTimestamp`; пары `isoDate`+`time` НЕ работают.
+- `SCHEDULE` — `{ "isoDate":"2026-06-25", "time":"18:00", "timezone":"Europe/Moscow" }`. Выходы `scheduled` / `past`.
+
+### Состояние / действия
+- `SET_VARIABLE` (`{ "key":"name", "value":"..." }`), `ADD_TAG`/`REMOVE_TAG` (`{ "tag":"lead" }`), `FORMULA` (`{ "expression":"...", "saveTo":"name" }`)
+- `ACTIONS` — непустой пакет действий `{ "actions":[ { "kind":"...", ...поля } ] }`. Допустимые `kind` (иначе ошибка `ACTION_UNKNOWN_KIND`):
+  - **метки/автоворонки**: `add_tag`, `remove_tag`, `autoflow_add`, `autoflow_remove` — поле `tag` (`[a-z0-9_-]{1,64}`)
+  - **профиль**: `set_field` — `key` (`[a-z_][a-z0-9_]{0,63}`) + `value`; `subscribe`, `unsubscribe`
+  - **HTTP**: `external_request`, `subscriber_webhook` — `url` (http/https) + `method`/`headersJson`/`bodyTemplate`
+  - **уведомления**: `notify` (`text`), `subscriber_email` (`email`,`text`), `agent_chat`
+  - **бот/шаг**: `stop_bot`, `delete_step_message`, `cancel_payment_subscription`
+  - **Google Таблицы (работает)**: `gsheets_send` — дописать строку-заявку в таблицу: `{ "kind":"gsheets_send", "googleEmail":"me@gmail.com", "spreadsheetId":"<id таблицы>", "sheetName":"Лист1", "cells":["{{from.first_name}}","{{var.phone}}","{{var.email}}"] }`. `cells` — значения по порядку (шаблоны), бот дописывает их строкой в конец листа. Google-аккаунт подключается В ВЕБЕ (`/bots` → у действия кнопка «Подключить Google»), НЕ через MCP — у пользователя уже должен быть подключён `googleEmail`. Нужны `googleEmail` + `spreadsheetId` + непустой `cells[]` (иначе `ACTION_GSHEETS_INCOMPLETE`).
+  - **интеграции (пока заглушки, no-op `integration_not_connected`)**: `getcourse_send`, `getcourse_order`, `amocrm_send`, `amocrm_update`, `yametrika_event`, `gsheets_get`, `gsheets_update`, `gsheets_write_cell`, `gsheets_read_cell`
+  - **модерация группы**: `group_unban`, `group_kick`, `group_approve`, `group_decline`
+
+### Внешнее / прочее
+- `CALL_WEBHOOK` — `{ "url":"https://...", "method":"POST", "bodyTemplate":"{...}", "timeoutMs":5000 }`. Выходы `ok` / `error`.
+- `AI_REPLY`, `PAYMENT_LINK`.
+
+## Условия CONDITION
+
+Каждый элемент `conditions[]` — `{ "kind", "op", ...поля }`. Любая внутренняя ошибка условия = `false` (узел уходит в `no`).
+
+| `kind` | `op` (допустимые) | Поля | Что проверяет |
+|---|---|---|---|
+| `TAG` | `HAS`, `NOT_HAS` | `value` — метка `[a-z0-9_-]{1,64}` | есть ли у пользователя тег |
+| `VARIABLE` | `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `NOT_EMPTY`, `EMPTY`, `GT`, `LT` | `key` — имя переменной `[a-z_][a-z0-9_]{0,63}`, `value` | значение переменной (`GT`/`LT` — числовое сравнение) |
+| `UTM` | `EQUALS`, `CONTAINS`, `NOT_EMPTY`, `EMPTY` | `key` ∈ `source`/`medium`/`campaign`/`content`/`term`, `value` | UTM-метку клика (`utm_<key>`), регистронезависимо |
+| `NAME` | `EQUALS`, `CONTAINS`, `NOT_EMPTY`, `EMPTY` | `value` | имя из профиля, регистронезависимо |
+| `EMAIL` | `EQUALS`, `CONTAINS`, `NOT_EMPTY`, `EMPTY` | `value` | email из профиля |
+| `PHONE` | `EQUALS`, `CONTAINS`, `NOT_EMPTY`, `EMPTY` | `value` | телефон из профиля |
+| `USERNAME` | `EQUALS`, `CONTAINS` | `value` | @username пользователя Telegram |
+| `SUBSCRIBED` | `SUBSCRIBED`, `NOT_SUBSCRIBED` | `key` — **числовой** id канала/группы (напр. `-1001234567890`); узнать числовой id подключённых каналов: `list_channels(botId)` | подписан ли пользователь на канал бота |
+| `LINK_CLICKED` | `CLICKED`, `NOT_CLICKED` | `key` — **`id` узла-шага** с отслеживаемой URL-кнопкой (тот же UUID, что у `SEND_MESSAGE`) | кликал ли пользователь по ссылке этого шага |
+| `CURRENT_DATE` | `BEFORE`, `AFTER`, `EQUALS` | `value` — дата `YYYY-MM-DD` | сегодняшнюю дату (МСК) |
+| `CURRENT_TIME` | `BETWEEN` | `value`, `value2` — время `HH:mm` | текущее время в интервале (через полночь — если `value`>`value2`) |
+| `DAY_OF_WEEK` | `IN` | `days` — массив из `MON`,`TUE`,`WED`,`THU`,`FRI`,`SAT`,`SUN` | день недели (МСК) |
+
+Для `NOT_EMPTY`/`EMPTY` поле `value` не нужно. `UTM` без `key` всегда `false`.
+
+**`SUBSCRIBED`** работает только если бот **админ** в канале/группе и канал «привязан» (бот узнаёт о членстве через хук `my_chat_member` — добавь бота в канал админом). `key` должен парситься в число, иначе условие = `false`. Профильные поля (`NAME`/`EMAIL`/`PHONE`) и UTM заполняются по ходу воронки (`ASK_QUESTION`→`saveTo`, диплинк-клик с UTM).
+
+**`LINK_CLICKED`** проверяет факт клика по URL-кнопке конкретного шага. Чтобы условие работало: у нужного `SEND_MESSAGE` хотя бы одна кнопка `kind:"URL"` с `"track": true`, а в условии `key` = `id` этого узла-шага. Клик фиксируется через публичный редирект бота, поэтому условие имеет смысл ставить **после** `DELAY`/`ASK_QUESTION` (дай пользователю время кликнуть).
+
+> **Платформа MAX.** Боты конструктора умеют работать и в мессенджере MAX. Там не поддерживаются `SUBSCRIBED`/`NOT_SUBSCRIBED` (нет членства в каналах) и reply-клавиатуры; публикация такого графа на MAX-бот вернёт **мягкие предупреждения** (не блокирует). Для Telegram-ботов всё работает как описано.
+
+## Платформа Instagram
+
+IG-боты подключаются через OAuth в разделе **«Инструменты роста»** (`/growth`) — **без вставки токена вручную**; у IG нет персонального бот-токена. После OAuth бот получает доступ к Messaging API через привязанный Instagram Business/Creator-аккаунт.
+
+### Разрешённые типы узлов для IG-ботов
+
+Только следующие (всё остальное — ошибка `IG_NODE_UNSUPPORTED` при публикации):
+
+| Тип | Доступен в IG |
+|---|---|
+| `TRIGGER_IG_COMMENT`, `TRIGGER_IG_DM`, `TRIGGER_IG_STORY_REPLY`, `TRIGGER_IG_STORY_MENTION` | ✅ (триггеры входа) |
+| `SEND_MESSAGE`, `SEND_PHOTO` | ✅ |
+| `BRANCH`, `CONDITION` | ✅ |
+| `SET_VARIABLE`, `ADD_TAG`, `REMOVE_TAG`, `FORMULA` | ✅ |
+| `ASK_QUESTION` | ✅ (с ограничениями — см. ниже) |
+| `DELAY` | ✅ (не более 24ч — см. ниже) |
+| `END` | ✅ |
+| `TRIGGER_COMMAND`, `TRIGGER_CALLBACK`, `TRIGGER_TEXT` | ❌ |
+| `BROADCAST_FILTER` (рассылки) | ❌ |
+| `SCHEDULE`, `ACTIONS`, `CALL_WEBHOOK`, `AI_REPLY`, `PAYMENT_LINK` | ❌ |
+
+### Ограничения IG-ботов
+
+- **Нет команд** — вход только через `TRIGGER_IG_COMMENT` / `TRIGGER_IG_DM` / `TRIGGER_IG_STORY_REPLY` / `TRIGGER_IG_STORY_MENTION`. `/start` и другие команды не поддерживаются.
+- **Нет рассылок** — `BROADCAST_FILTER` недоступен.
+- **DELAY не более 24 часов** — Instagram доставляет сообщения только в течение 24-часового окна после последнего входящего действия (`IG_DELAY_OVER_24H`). `DELAY` с `kind=TOMORROW` или `kind=UNTIL` блокируются (они заведомо > 24ч). `kind=FIXED` с `durationSec > 86400` тоже блокируется.
+- **`ASK_QUESTION`** — `inputKind`: `TEXT`, `EMAIL`, `PHONE`, `NUMBER`, `CONTACT` (`IG_INPUT_UNSUPPORTED` для остальных). `CONTACT` допустим: кнопки «Поделиться номером» в IG нет, поэтому бот отправляет текст-инструкцию и принимает номер, набранный вручную (как телефон). Нельзя запрашивать `LOCATION`, `PHOTO`, `DOCUMENT`.
+- **Нет reply-клавиатур** — кнопки IG работают как inline (URL или Deep Link); стиль кнопок ограничен возможностями IG Messaging API.
+- **Нет SUBSCRIBED** — условие «подписан на канал» недоступно.
+- **Коммент → ЛС (Private Reply)** — на `SEND_MESSAGE`/`SEND_PHOTO` в графе с `TRIGGER_IG_COMMENT` укажи `"igReplyChannel": "dm"`, чтобы ответить автору комментария в Direct (а не публично под постом). По умолчанию (`"comment"`) — публичный ответ. Подробнее — `igReplyChannel` в разделе «Сообщения». **`"comment"` тоже требует, чтобы шаг был достижим от `TRIGGER_IG_COMMENT`** — иначе ошибка валидации `IG_COMMENT_REPLY_NO_COMMENT_TRIGGER` (в DM/story-флоу отвечать в комментарии некуда).
+
+### Оффлайн-проверка IG-графа
+
+```bash
+node validate.mjs graph.json --platform=INSTAGRAM
+```
+
+Ловит `IG_NODE_UNSUPPORTED`, `IG_DELAY_OVER_24H`, `IG_INPUT_UNSUPPORTED` — в дополнение ко всем обычным структурным проверкам.
+
+## Кросс-платформенное копирование (Telegram ⇄ MAX)
+
+Инструмент `copy_graph` копирует граф в **другого бота** пользователя (`targetBotId`), в т.ч. на другую платформу. Формат графа один и тот же; различается лишь платформа бота-получателя. При копировании в MAX-бот несовместимые узлы **адаптируются**, отчёт — в `notes[]`:
+
+| code | severity | что значит |
+|---|---|---|
+| `MAX_CONTACT_AS_TEXT` | TRANSFORM | вопрос с `inputKind=CONTACT` переписан в `inputKind=TEXT` + `validator=PHONE` (в MAX нет кнопки «поделиться контактом»; иначе узел стал бы тупиком) |
+| `MAX_SUBSCRIBED_ALWAYS_NO` | MANUAL | условие `SUBSCRIBED` оставлено как есть, но в MAX всегда «не подписан» — проверьте ветвление вручную |
+| `MAX_VOICE_AS_AUDIO` | INFO | голосовое уйдёт обычным аудио |
+| `MAX_VIDEO_NOTE_AS_VIDEO` | INFO | кружок уйдёт обычным видео |
+| `MAX_GALLERY_AS_ATTACHMENTS` | INFO | галерея уйдёт одним сообщением с вложениями |
+| `MAX_DELETE_NOOP` | INFO | действие «удалить сообщение» в MAX игнорируется |
+
+`preview: true` возвращает только `notes[]` (без копирования). Копирование в Telegram-бота (или в бота той же платформы) — точная копия, `notes[]` пустой. Новый граф создаётся как `DRAFT` с именем «… (copy)». Копировать в тот же бот нельзя (для дублирования — `clone_graph`).
+
+## Выходные хэндлы (`sourceHandle`) — шпаргалка
+| Узел | Хэндлы |
+|---|---|
+| обычный поток | `next` |
+| кнопки сообщения (`buttons`) | `btn_0`, `btn_1`, … (по индексу кнопки, плоско по всем рядам) |
+| `CONDITION` | `yes`, `no` |
+| `BRANCH` | `case_<id>`, `default` |
+| `ASK_QUESTION` | `valid`, `invalid` |
+| `SEND_MESSAGE` с `awaitReply:true` | `valid`, `invalid` (+ `btn_N` для кнопок) |
+| `CALL_WEBHOOK` | `ok`, `error` |
+| `SCHEDULE` | `scheduled`, `past` |
+| `DELAY` | `next` |
+
+## Подстановки в тексте
+`{{from.first_name}}`, `{{from.username}}`, `{{var.<имя>}}`, либо `{Имя}` как плейсхолдер. Имена переменных/меток: `[a-z_][a-z0-9_]{0,63}` (var) и `[a-z0-9_-]{1,64}` (tag).