@besales/mcp 0.47.1 → 1.0.0-beta.2

package/dist/resources/docs/pipeline-builder.md

@@ -1,225 +1,35 @@
-# 14. Pipeline Builder и PipelineSettings
+# Настройка CRM-воронок
 
-> **Источник правды:** `ai-aniomaly/docs/ai-prompt-builder/14-pipeline-builder.md` — копия для MCP doc-bridge (v1.5 Increment 6b). Синкать при изменении оригинала.
->
-> ⚠️ **MCP-контекст:** это доменная справка, написанная для людей/админ-UI. В MCP-сессии ты выполняешь те же операции **через besales_* tools**, а не через UI (drag-n-drop, клики в админке). Где текст ниже говорит «клиент/админ делает X через UI» — это «что должно получиться»; механику бери из tool (напр. загрузка файла → `besales_file_upload_request`; документ в knowledge → `besales_knowledge_document_upload`; сайт → `besales_knowledge_website_add`) + из workflow-ресурсов. Внутренние ссылки `[NN-name.md]` — относительные пути исходной доки, через MCP НЕ резолвятся: ищи `besales://docs/<slug>` или concept-resource.
+Воронка и её стадии — workspace-каталог CRM. Каноническая бизнес-связь в v2 принадлежит агенту,
+но отгруженная совместимая MCP-поверхность пока умеет только канальную связь.
 
-## 1. Назначение
+## Базовый порядок
 
-Когда платформа подключена к CRM, нужно решить две задачи:
+1. Получи актуальные воронки через `besales_crm_pipeline_list`.
+2. При необходимости создай или обнови пользовательскую запись каталога.
+3. Проверь стадии и их внешние идентификаторы.
+4. Если нужна построенная сегодня связь, вызови `besales_platform_pipeline_link` для конкретного
+   канала. Не выдавай её за agent-level связь.
+5. Проверь сценарий на тестовом контакте до массового запуска.
 
-1. **Что делать, если в CRM уже есть сделка/контакт с тем же телефоном** (повторное обращение клиента) — `PipelineSettings.filter*`.
-2. **Куда автоматически переводить сделку** при определённых событиях: пришло сообщение от пользователя, ответил бот, ответил оператор — `PipelineSettings.*MoveToStatus`.
+Agent-level поверхность для `agent_active_pipelines` этим инструментом не построена. Если задача
+требует именно общей воронки агента на нескольких каналах, сообщи об этом разрыве вместо серии
+канальных вызовов, которая создала бы другую модель владения.
 
-Обе задачи настраиваются в Pipeline Builder UI (одна страница админки). Структура — модель `PipelineSettings` (one-to-one с `Platform`).
+## Автоматические переходы
 
-## 2. JSON-схема
+Переход стадии выполняется серверным action step после ActionGovernor. Условия используют общий
+`ConditionGroupJson`; отдельные строки выражений и второй DSL запрещены. Для каждой автоматизации
+нужно явно определить:
 
-```json
-{
-  "id": "uuid",
-  "platformId": "<platformId>",
+- исходную и целевую стадию;
+- событие или условие активации;
+- поведение при отсутствии внешней записи;
+- допустимость повтора и правила неоднозначного исхода;
+- аудит и видимый оператору результат.
 
-  "filterEnabled": true,
-  "filterByPhoneEnabled": true,
-  "filterByFieldEnabled": false,
-  "filterByContactEnabled": false,
+## Защита от дрейфа
 
-  "fieldId": null,
-  "fieldEntityType": null,
-  "valueType": null,
-  "value": null,
-
-  "actionOnFound": "LINK",
-
-  "createNewLead": true,
-  "createNewContact": true,
-
-  "incomingMoveToStatus": 142,
-  "incomingMoveToStatusPipelineId": 1234567,
-  "incomingMoveToStatusCrmId": "<Crm.id>",
-
-  "outgoingMoveToStatus": 143,
-  "outgoingMoveToStatusPipelineId": 1234567,
-  "outgoingMoveToStatusCrmId": "<Crm.id>",
-
-  "aiResponseMoveToStatus": null,
-  "aiResponseMoveToStatusPipelineId": null,
-  "aiResponseMoveToStatusCrmId": null,
-
-  "operatorSpeechMoveToStatus": 145,
-  "operatorSpeechMoveToStatusPipelineId": 1234567,
-  "operatorSpeechMoveToStatusCrmId": "<Crm.id>"
-}
-```
-
-## 3. Фильтрация существующих сделок
-
-### Поля
-
-| Поле | Тип | Описание |
-|---|---|---|
-| `filterEnabled` | bool | Главный выключатель — без него фильтр не работает. |
-| `filterByPhoneEnabled` | bool | Искать существующую сделку/контакт по телефону клиента. |
-| `filterByFieldEnabled` | bool | Искать по кастомному CRM-полю. |
-| `filterByContactEnabled` | bool | Полнотекстовый поиск через CRM-контакт. |
-| `fieldId` | string / null | ID кастомного поля CRM (для `filterByFieldEnabled`). |
-| `fieldEntityType` | string / null | `LEAD` или `CONTACT` — где искать поле. |
-| `valueType` | enum `PipelineFilterValueType` / null | `CONSTANT` (фиксированное значение) или `SYSTEM_VARIABLE` (имя системной переменной — `phone`, `telegramId` и т.п.). |
-| `value` | string / null | Само значение или имя системной переменной. |
-| `actionOnFound` | enum `PipelineFilterAction` / null | `IGNORE` (игнорировать обращение, `isBotActive=false`) или `LINK` (привязать к существующей сделке и продолжить). |
-
-### Сценарии
-
-| Сценарий бизнеса | Настройки |
-|---|---|
-| «Если клиент уже у нас в работе — не дублировать сделку, а продолжить в существующей» | `filterEnabled=true`, `filterByPhoneEnabled=true`, `actionOnFound=LINK` |
-| «Если есть сделка — не отвечать ботом, отдать оператору» | `filterEnabled=true`, `filterByPhoneEnabled=true`, `actionOnFound=IGNORE` |
-| «Искать по нашему UTM-полю, чтобы не дублировать с лендингов» | `filterEnabled=true`, `filterByFieldEnabled=true`, `fieldId=<UTM_FIELD_ID>`, `fieldEntityType=LEAD`, `valueType=CONSTANT`, `value="lp_main_2026"`, `actionOnFound=LINK` |
-
-### Создание новых сущностей
-
-| Поле | Описание |
-|---|---|
-| `createNewLead` | Создавать ли сделку в CRM при первом обращении клиента, если фильтр не нашёл существующую (или фильтр выключен). |
-| `createNewContact` | Аналогично для контакта. |
-
-Обычно оба `true` — иначе сделки/контакты в CRM не появятся.
-
-## 4. Status movement: автоматические переходы между этапами
-
-Каждое событие в системе может автоматически двигать сделку. Настройка задаёт композитный ключ `(crmId, pipelineId, statusId)` — статус **может быть в любой воронке** активной для платформы (см. `PlatformPipeline`).
-
-### Все события
-
-| Поле | Когда срабатывает | Куда уйдёт сделка |
-|---|---|---|
-| `incomingMoveToStatus` | Пользователь написал в бот (входящее сообщение) | На указанный статус (обычно «Новый» или «В работе») |
-| `outgoingMoveToStatus` | Бот/оператор ответил пользователю | На указанный статус (обычно «Идёт диалог») |
-| `aiResponseMoveToStatus` | Бот сгенерировал и отправил ответ через LLM | На указанный статус (опционально — если хочется отделить «AI ответил» от «оператор ответил») |
-| `operatorSpeechMoveToStatus` | Оператор написал в карточку (через CRM Chat API) | На указанный статус (обычно «У оператора») |
-
-Каждое поле — это **тройка**: `*MoveToStatus`, `*MoveToStatusPipelineId`, `*MoveToStatusCrmId`. Если основное поле `null` — переход не выполняется.
-
-### Связь со `StatusType`
-
-В `CrmPipelineStatus.statusTypes[]` (массив enum `StatusType`) можно указать «семантику» этапа: `INCOMING`, `OUTGOING`, `MESSAGE_SENT`, `AI_TOOK_OVER`, `OPERATOR_TOOK_OVER`, `USER_BLOCKED`. Эти теги — для UI и аналитики (показывают, какие этапы что обрабатывают), но **не управляют автопереходами** — это делает `PipelineSettings.*MoveToStatus`.
-
-### `CrmPipelineStatus.onMessageReceivedMoveToStatus`
-
-Альтернативный механизм автоперехода — на уровне самого статуса: `null` или ID статуса, в который перейти при получении сообщения от пользователя. Может конфликтовать с `PipelineSettings.incomingMoveToStatus` — приоритет за `PipelineSettings`.
-
-### `CrmPipelineStatus.isSystemManaged`, `isBotActive` и `isOperatorAvailable`
-
-Эти поля хранятся на статусе и редактируются в Pipeline Builder:
-- `isSystemManaged=false` → master-гейт выключен: статус не управляется системой, а UI считает бота и оператора неактивными независимо от дочерних флагов.
-- `isBotActive=false` → бот молчит на этом этапе.
-- `isOperatorAvailable=false` → оператор не может быть подключён через `CALL_OPERATOR`.
-
-Через MCP эти поля меняются в `besales_crm_pipeline_status_update` как
-`is_system_managed`, `is_bot_active` и `is_operator_available`.
-
-## 5. PlatformPipeline — связь платформы с воронками
-
-Платформа может работать с **несколькими воронками** одной CRM (например, одна для лидов, другая для текущих клиентов):
-
-```json
-{
-  "platformId": "<platformId>",
-  "pipelineCrmId": "<Crm.id>",
-  "pipelineId": 1234567,
-  "isActive": true
-}
-```
-
-Это many-to-many связь. PipelineSettings может ссылаться на статусы из любой активной воронки.
-
-## 6. Inline-пример: типичный e-commerce setup
-
-```json
-{
-  "platformId": "<platformId>",
-
-  "filterEnabled": true,
-  "filterByPhoneEnabled": true,
-  "filterByFieldEnabled": false,
-  "filterByContactEnabled": false,
-  "actionOnFound": "LINK",
-
-  "createNewLead": true,
-  "createNewContact": true,
-
-  "incomingMoveToStatus": 142,
-  "incomingMoveToStatusPipelineId": 1234567,
-  "incomingMoveToStatusCrmId": "<Crm.id>",
-
-  "outgoingMoveToStatus": 143,
-  "outgoingMoveToStatusPipelineId": 1234567,
-  "outgoingMoveToStatusCrmId": "<Crm.id>",
-
-  "operatorSpeechMoveToStatus": 145,
-  "operatorSpeechMoveToStatusPipelineId": 1234567,
-  "operatorSpeechMoveToStatusCrmId": "<Crm.id>"
-}
-```
-
-Логика:
-- При первом сообщении — ищем по телефону, если уже есть — привязываем; если нет — создаём новую сделку в этапе 142.
-- При первом ответе — переводим в 143 («Идёт диалог»).
-- Когда оператор подключился — 145 («У оператора»).
-
-## 7. Inline-пример: фильтр по UTM (B2B-лендинг)
-
-Для разных лендингов — разные воронки:
-
-```json
-{
-  "filterEnabled": true,
-  "filterByFieldEnabled": true,
-  "fieldId": "987",
-  "fieldEntityType": "LEAD",
-  "valueType": "SYSTEM_VARIABLE",
-  "value": "telegramId",
-  "actionOnFound": "LINK",
-  "createNewLead": true,
-  "createNewContact": true
-}
-```
-
-Логика: ищем сделку по полю с ID `987` (например, «Telegram User ID» в LEAD), значение которого совпадает с `{telegramId}` текущего пользователя. Если найдено — привязываем; иначе создаём новую.
-
-## 8. Граничные случаи и валидация
-
-| Правило | Что AI-сервису помнить |
-|---|---|
-| `PipelineSettings` — one-to-one с Platform | Для каждой платформы максимум одна запись. |
-| `filterEnabled=true` без `filterBy*` | Бесполезно — система не знает, по чему искать. |
-| `filterByPhoneEnabled=true` для платформ без телефона (Web Widget без UTM) | Может не найти, но бот всё равно сработает (фильтр пропустится). |
-| `actionOnFound=IGNORE` | `ChatUser.isBotActive=false` — бот не отвечает. Подходит для «после ручного открытия сделки оператор сам отвечает». |
-| `actionOnFound=LINK` | `ChatUser` привязывается к существующей `leadId/bitrixDealId`. Хорошо для непрерывности. |
-| `*MoveToStatus` без всех трёх ID | Если нет `*MoveToStatusPipelineId`/`*MoveToStatusCrmId` — переход не сработает. |
-| Конфликт `aiResponseMoveToStatus` и `outgoingMoveToStatus` | Оба сработают по очереди (сначала AI, потом outgoing). Часто хватает только `outgoing`, чтобы не перегружать. |
-| Composite key статуса | Все три поля (`MoveToStatus`, `MoveToStatusPipelineId`, `MoveToStatusCrmId`) или ни одного. |
-| Удаление воронки/статуса | Если ID удалится в CRM — переход просто не выполнится (без ошибки). Регулярно проверять синхронизацию. |
-| Pipeline Builder не управляет триггерами | Это два разных механизма перевода. Триггер `CRM_MOVE_STAGE` — точечный, по условию. PipelineSettings — автоматически по событию. |
-
-## 9. Что AI-сервис должен спрашивать у клиента
-
-Перед генерацией PipelineSettings:
-
-1. «Если клиент уже есть в CRM — продолжить в существующей сделке или создать новую?» (`actionOnFound`).
-2. «Куда переводить сделку, когда клиент написал?» (`incomingMoveToStatus`).
-3. «Куда переводить, когда вы ответили?» (`outgoingMoveToStatus`).
-4. «Куда переводить, когда подключился оператор?» (`operatorSpeechMoveToStatus`).
-5. «Создавать ли новые сделки/контакты автоматически?» (`createNewLead`/`createNewContact`).
-6. «По какому ключу искать дубликаты — телефон, кастомное поле, что-то ещё?» (`filterBy*`).
-
-## 10. Связь с другими подсистемами
-
-| Подсистема | Связь |
-|---|---|
-| **Платформы** ([`11-platforms.md`](11-platforms.md)) | `PipelineSettings` принадлежит платформе (one-to-one). |
-| **CRM** ([`12-crm-integration.md`](12-crm-integration.md)) | Использует `CrmPipelineStatus` (composite key). `StatusType` теги влияют на UI/аналитику. |
-| **Триггеры** ([`04-triggers-and-actions.md`](04-triggers-and-actions.md)) | Триггер `CRM_MOVE_STAGE` — независимый механизм перевода (точечный, по условию). Совместимы — могут работать параллельно. |
-| **Маршрутизация** ([`06-routing.md`](06-routing.md)) | `LEAD_STATUS` стратегия router-а опирается на `ChatUser.leadStatusId`, который обновляется автоматически после переходов через PipelineSettings. |
-| **AgentBehavior** ([`10-agent-behavior.md`](10-agent-behavior.md)) | `aiErrorTargetStageId` — куда перевести при ошибке LLM (читает напрямую `pipelineId` текущей воронки, если `null`). |
+Не сохраняй название стадии как единственный идентификатор: оно редактируется в CRM. Не передавай
+модели внешний ID. После ресинхронизации проверяй ссылки на удалённые стадии и правила
+маршрутизации; невалидная ссылка должна быть видна владельцу, а не молча выбирать соседнюю стадию.

package/dist/resources/docs/pipeline-settings-deep.md

@@ -1,231 +1,38 @@
-# 24. Pipeline Settings — глубокая конфигурация
+# Расширенные правила CRM и маршрутизации
 
-> **Источник правды:** `ai-aniomaly/docs/ai-prompt-builder/24-pipeline-settings-deep.md` — копия для MCP doc-bridge (v1.5 Increment 6b). Синкать при изменении оригинала.
->
-> ⚠️ **MCP-контекст:** это доменная справка, написанная для людей/админ-UI. В MCP-сессии ты выполняешь те же операции **через besales_* tools**, а не через UI (drag-n-drop, клики в админке). Где текст ниже говорит «клиент/админ делает X через UI» — это «что должно получиться»; механику бери из tool (напр. загрузка файла → `besales_file_upload_request`; документ в knowledge → `besales_knowledge_document_upload`; сайт → `besales_knowledge_website_add`) + из workflow-ресурсов. Внутренние ссылки `[NN-name.md]` — относительные пути исходной доки, через MCP НЕ резолвятся: ищи `besales://docs/<slug>` или concept-resource.
+В Besales нет одного JSON-объекта «настройки воронки канала». Поведение разделено по владельцам,
+чтобы изменение транспорта не переписывало CRM-логику и наоборот.
 
-## 1. Назначение
+## Где живёт настройка
 
-`PipelineSettings` — расширение [14-pipeline-builder.md](14-pipeline-builder.md). Настройки 1:1 с `Platform`, отвечают за две группы поведения:
-
-1. **Фильтр поиска существующих сделок** — когда новый клиент пишет, нужно ли искать его уже-имеющуюся сделку и как с ней поступить.
-2. **Автопереход статусов** — 6 разных триггеров системного перемещения сделки по воронке.
-
-Базовый файл [14-pipeline-builder.md](14-pipeline-builder.md) описывал часть полей; здесь — **полная JSON-схема** со всеми 30+ полями.
-
-## 2. Полная JSON-схема `PipelineSettings`
-
-```json
-{
-  "id": "uuid",
-  "platformId": "<Platform.id>",
-
-  // === FILTER SEARCH (поиск существующих сделок) ===
-  "filterEnabled": true,
-  "filterByPhoneEnabled": true,
-  "filterByFieldEnabled": false,
-  "filterByContactEnabled": false,
-  "fieldId": null,
-  "fieldEntityType": null,
-  "valueType": null,
-  "value": null,
-  "actionOnFound": "LINK",
-
-  // === CREATION FLAGS ===
-  "createNewLead": true,
-  "createNewContact": true,
-
-  // === STATUS MOVEMENT (6 триггеров) ===
-  "aiResponseMoveToStatus": 142,
-  "aiResponseMoveToStatusPipelineId": 1234567,
-  "aiResponseMoveToStatusCrmId": "<Crm.id>",
-
-  "operatorSpeechMoveToStatus": 145,
-  "operatorSpeechMoveToStatusPipelineId": 1234567,
-  "operatorSpeechMoveToStatusCrmId": "<Crm.id>",
-
-  "incomingMoveToStatus": 140,
-  "incomingMoveToStatusPipelineId": 1234567,
-  "incomingMoveToStatusCrmId": "<Crm.id>",
-
-  "outgoingMoveToStatus": 141,
-  "outgoingMoveToStatusPipelineId": 1234567,
-  "outgoingMoveToStatusCrmId": "<Crm.id>",
-
-  "messageSentMoveToStatus": null,
-  "messageSentMoveToStatusPipelineId": null,
-  "messageSentMoveToStatusCrmId": null,
-
-  "userBlockedMoveToStatus": 199,
-  "userBlockedMoveToStatusPipelineId": 1234567,
-  "userBlockedMoveToStatusCrmId": "<Crm.id>",
-
-  // Marker-статус покупки для /chats (не движение сделки)
-  "saleStatus": 200,
-  "saleStatusPipelineId": 1234567,
-  "saleStatusCrmId": "<Crm.id>",
-
-  // === GLOBAL ===
-  "alwaysMoveToAiStatus": false,
-  "preventBackwardMovement": true
-}
-```
-
-## 3. Группа: Фильтр поиска существующих сделок
-
-### 3.1. Master switch
-
-`filterEnabled: true` — без этого ни один из под-флагов не работает.
-
-### 3.2. Три режима поиска (взаимоисключающие, AI-сервис выбирает один)
-
-| Флаг | Поведение | Когда использовать |
-|---|---|---|
-| `filterByPhoneEnabled` | Искать сделку по полю `phone` контакта **И** по кастомным полям сделки, в которых есть телефон | По умолчанию для всех платформ с телефоном (Wazzup, Avito, SMS) |
-| `filterByFieldEnabled` | Искать по конкретному кастомному полю CRM | Когда у клиента CRM-поле «UTM» или «email», и нужно дедуплицировать по нему |
-| `filterByContactEnabled` | Полнотекстовый поиск через **контакт** CRM (AmoCRM Search Contact API) | Когда у клиента нет фиксированных полей, но нужен fuzzy-матч |
-
-### 3.3. Параметры для `filterByFieldEnabled`
-
-```json
-{
-  "filterByFieldEnabled": true,
-  "fieldId": "12345",
-  "fieldEntityType": "CONTACT",
-  "valueType": "SYSTEM_VARIABLE",
-  "value": "phone"
-}
-```
-
-| Поле | Тип | Описание |
-|---|---|---|
-| `fieldId` | string | ID кастомного поля в CRM (числовой ID) |
-| `fieldEntityType` | `'LEAD'` / `'CONTACT'` | Где искать поле — у сделки или у контакта |
-| `valueType` | enum `PipelineFilterValueType` | `CONSTANT` (искать по фиксированной строке) / `SYSTEM_VARIABLE` (брать значение из системной переменной типа `{phone}`) |
-| `value` | string | Либо константа, либо имя переменной (`phone`, `telegramId`, etc.) |
-
-### 3.4. Действие при нахождении сделки
-
-`actionOnFound` — enum `PipelineFilterAction`:
-
-| Значение | Поведение |
-|---|---|
-| `LINK` | Привязать `ChatUser` к найденной сделке. Бот будет общаться с этой сделкой |
-| `IGNORE` | Игнорировать существующую сделку, создать новую (если `createNewLead=true`) |
-
-### 3.5. Флаги создания
-
-| Флаг | Поведение | Default |
-|---|---|---|
-| `createNewLead` | Создать новую сделку, если ничего не найдено или `actionOnFound=IGNORE` | true |
-| `createNewContact` | Создать новый контакт, если ничего не найдено | true |
-
-> Если `createNewLead=false` и сделка не найдена → бот будет общаться без CRM-сделки. CRM-actions триггеров (`CRM_MOVE_STAGE`) silently не сработают.
-
-## 4. Группа: Автопереход статусов
-
-`PipelineSettings` определяет **6 триггеров** автоматического перевода сделки по воронке. Каждый триггер — composite-FK на `CrmPipelineStatus` (3 поля: `<X>MoveToStatus`, `<X>MoveToStatusPipelineId`, `<X>MoveToStatusCrmId`).
-
-| Триггер | Когда срабатывает | Назначение |
-|---|---|---|
-| `aiResponseMoveToStatus` | После каждого ответа AI боту | Маркировка «бот говорил с клиентом» |
-| `operatorSpeechMoveToStatus` | После каждого сообщения от оператора-человека | Маркировка «оператор уже подключился» |
-| `incomingMoveToStatus` | При первом входящем сообщении от пользователя | Маркировка «появился новый запрос» |
-| `outgoingMoveToStatus` | При первом исходящем сообщении (например, follow-up) | Маркировка «бот написал первым» |
-| `messageSentMoveToStatus` | После любого исходящего сообщения (повторяется) | Аналитика «сколько касаний с клиентом» |
-| `userBlockedMoveToStatus` | Когда пользователь блокирует бота / пишет «STOP» | Архив для очистки воронки |
-
-`saleStatus` / `saleStatusPipelineId` / `saleStatusCrmId` настраиваются тем же способом через
-`crm_pipeline_behavior.status_movement`, но это marker для списка чатов, а не автопереход сделки.
-Если текущий `ChatUser.leadStatusId` совпадает с `saleStatus` своей платформы, `/chats` покажет
-shopping bag и фильтр «Купил» будет считать этот чат купленным.
-
-### 4.1. Composite-FK
-
-В CRM статус идентифицируется тройкой: `(crmId, pipelineId, statusId)`. AI-сервис всегда заполняет все три поля или все три оставляет null. Заполнить только `<X>MoveToStatus` без `<X>MoveToStatusPipelineId` нельзя — runtime не поймёт, в какую воронку.
-
-### 4.2. Конфликты и приоритеты
-
-| Конфликт | Поведение |
+| Вопрос | Канонический владелец |
 |---|---|
-| Триггер `CRM_MOVE_STAGE` сработал ПЕРЕД ответом ИИ | После ответа ИИ применится `aiResponseMoveToStatus` (если задан) — может перезаписать только что выставленный статус |
-| `incomingMoveToStatus` И `aiResponseMoveToStatus` оба заданы | На входящем сначала переведётся в incoming-статус, потом — после ответа — в ai-response статус. Клиент видит две движухи в воронке |
-| `alwaysMoveToAiStatus=true` | Любой ai-response игнорирует текущую колонку и форсит переход в `aiResponseMoveToStatus` (даже если бот уже там) |
-
-### 4.3. Связь с типами статусов (`CrmPipelineStatus.statusTypes[]`)
-
-| Триггер | Соответствующий `StatusType` |
-|---|---|
-| `incomingMoveToStatus` | `INCOMING` |
-| `outgoingMoveToStatus` | `OUTGOING` |
-| `messageSentMoveToStatus` | `MESSAGE_SENT` |
-
-> `CrmPipelineStatus.statusTypes` — массив, **может содержать несколько типов**. Например, статус «Бот общается» может быть и `INCOMING`, и `MESSAGE_SENT`. UI Pipeline Builder использует это для отметки колонок.
+| Какие воронки использует агент | `agent_active_pipelines` |
+| Какие стадии существуют во внешней CRM | `crm_pipeline_statuses` |
+| Как поля CRM связаны с бизнес-смыслом | `crm_field_mappings` |
+| Как выбирается агент | `agent_routing_rules` |
+| Когда выполняется действие | `agent_action_activations` |
+| Как ведёт себя транспорт | `channel_behavior_configs` |
 
-## 5. Глобальные правила
+## Условия
 
-### `alwaysMoveToAiStatus`
+Маршрутизация, handoff, governance и активация используют один формат `ConditionGroupJson`, но
+разные разрешённые профили полей. `ALL` и `ANY` задают комбинатор группы. Ссылка на переменную,
+стадию или агента должна принадлежать тому же workspace и проходить сверку валидности.
 
-Если `true`: после **любого** ответа AI сделка форсированно переходит в `aiResponseMoveToStatus`, даже если она уже в колонке с включённым `isBotActive`. Это полезно, когда у клиента 5-10 «AI-колонок» и важно сводить всё в одну для аналитики.
+Локальное правило с `channel_id` действует только в этом канале. При удалении канала оно
+удаляется, а не становится глобальным. Агент, выбранный целью правила, не удаляется молча:
+владелец сначала видит список блокирующих правил и меняет их явно.
 
-### `preventBackwardMovement`
+## Переходы и создание записей
 
-Если `true`: автоматический move-to-status **не сработает**, если целевой статус имеет `sort` меньше текущего. Защита от бесконечного «маятника» (бот пишет → ai-response двигает назад → потом снова движение).
+Не смешивай в одном флаге поиск существующей сделки, создание новой и смену стадии. Это отдельные
+операции с разной идемпотентностью и ценой ошибки. Каждая внешняя запись связывается через
+`crm_record_links`, а денежные и необратимые операции требуют отдельного права и аудита.
 
-> Работает per-pipeline (учитывается только в пределах одной воронки).
+## Диагностика
 
-## 6. `PlatformPipeline` (M2M связь)
-
-Платформа может работать с **несколькими активными воронками одновременно**:
-
-```json
-{
-  "id": "uuid",
-  "platformId": "<Platform.id>",
-  "pipelineId": 1234567,
-  "pipelineCrmId": "<Crm.id>",
-  "sort": 0
-}
-```
-
-Используется когда:
-- Один Telegram-бот ведёт лидов и в основную воронку, и в воронку «холодных».
-- Несколько воронок Bitrix24 (для разных продуктов).
-
-Без хотя бы одной записи `PlatformPipeline` все CRM-actions триггеров silently не сработают (платформа «не знает» в какую воронку кладть сделки).
-
-## 7. Что AI-сервис описывает клиенту
-
-Стандартный workflow настройки Pipeline Settings:
-
-1. **Подключите Crm** (AmoCRM/Bitrix24/GetCourse) — см. [12-crm-integration.md](12-crm-integration.md).
-2. **Создайте `PlatformPipeline`** для каждой воронки, в которой бот должен работать.
-3. **Включите `filterEnabled`** и выберите режим поиска (`filterByPhoneEnabled` для Wazzup/SMS, `filterByContactEnabled` для AmoCRM).
-4. **Задайте `actionOnFound`** — обычно `LINK` (продолжить с существующей сделкой).
-5. **Настройте 1-3 автоперехода**, которые вам реально нужны:
-   - Минимум: `aiResponseMoveToStatus` для трекинга «бот ответил».
-   - Часто: `incomingMoveToStatus` + `outgoingMoveToStatus` для разделения первичной воронки.
-   - Реже: `userBlockedMoveToStatus` для архивирования.
-6. **Не включайте всё подряд** — больше автопереходов = больше движений в воронке = операторы запутаются.
-7. **`preventBackwardMovement=true`** — почти всегда нужен, защищает от глюков.
-
-## 8. Граничные случаи
-
-| Ситуация | Поведение |
-|---|---|
-| `<X>MoveToStatus` указан, но не существует в CRM | Runtime логирует ошибку, переход не происходит |
-| `<X>MoveToStatusPipelineId` не совпадает с активной `PlatformPipeline` | Runtime отклонит переход (статус не из «своей» воронки) |
-| `filterByPhoneEnabled=true`, но у платформы нет телефона (Telegram Bot без shareContact) | Поиск не выполняется, ведёт себя как `filterEnabled=false` |
-| `actionOnFound=IGNORE` И `createNewLead=false` | Сделка не создаётся, бот общается «в воздух» — CRM-actions не сработают |
-| Несколько матчей в `filterByContactEnabled` | Берётся самая свежая сделка (по `updatedAt`) |
-| Клиент сменил `filterByFieldEnabled` на лету | Существующие связи `ChatUser ↔ Deal` не пересчитываются — только для новых |
-
-## 9. Связь с другими подсистемами
-
-| Подсистема | Связь |
-|---|---|
-| **Pipeline Builder** ([14-pipeline-builder.md](14-pipeline-builder.md)) | Базовая часть — UI и `CrmPipelineStatus.statusTypes` |
-| **CRM** ([12-crm-integration.md](12-crm-integration.md)) | `Crm`, `CrmPipeline`, `CrmPipelineStatus`, поля контакта |
-| **Платформы** ([11-platforms.md](11-platforms.md)) | `Platform.dealMarkerType`, `responsibleAssigneeStrategy`, `sendToCrm` |
-| **Триггеры** ([04-triggers-and-actions.md](04-triggers-and-actions.md)) | `CRM_MOVE_STAGE` action — ручное переключение, может конфликтовать с автопереходами |
-| **Routing** ([06-routing.md](06-routing.md)) | `LEAD_STATUS` маршрутизация работает поверх той же `CrmPipelineStatus` модели |
+Если правило не сработало, проверяй последовательно: актуальность CRM-каталога, валидность ссылок,
+профиль condition-core, привязку агента к воронке, решение ActionGovernor и нормализованный исход
+провайдера. Не лечи проблему копированием настроек в промпт — модель не является источником
+истины для маршрутизации или CRM-ID.