@besales/mcp 0.47.1 → 1.0.0-beta.2

package/docs/modules/analytics.md

@@ -0,0 +1,79 @@
+# Чтение аналитики
+
+Инструмент воронки сохраняет отгруженные `meta`, `summary`, `cohorts` и добавляет
+`velocity`, `activity`, `trigger-daily`, `drilldown`, `managers`, `stage-path`, `decision-gate`.
+Путь до стадии требует `target_status_id`; список — `metric` и необязательные координаты
+стадии/воронки и страницы. Остальные новые чтения требуют календарный период.
+Имена полей и прежние значения не переименованы. У менеджеров сервер игнорирует режим и
+менеджера: всегда когорта и все менеджеры.
+
+«Сегодня» и «Зависшие» — снимок рабочих воронок; без настройки рабочих воронок фильтра нет.
+Ошибки отправки — доказанные отказы за всё время. «Без сделки» — когорта дат без менеджера.
+Журнал стадий хранится 25 месяцев: возраст старых стадий неизмерим.
+
+Фасад аналитики рассылок добавляет `registration_intake`: один канал, ограниченный период,
+ось периода и необязательный фильтр воронки. Ответ: состояние, всего/вошли/не вошли, группы,
+люди с исходами приёма и приветствия, воронкой, моментом регистрации, заказами и живой ссылкой.
+Внешний реестр может отставать на 10 минут — 3 часа, редко сутки. Недошедший заказ без решения
+при двух каналах одной воронки виден обоим; итоги каналов не складываются.
+
+Инструмент «Входящих» сохраняет все шесть отгруженных значений и поля входа. Все шесть маршрутов текущего API построены; каждый запрос сохраняет собственный отчёт. Момент границы денежного отчёта преобразуется
+в календарный день Москвы. Список заявок — экранный, значения `leads` у инструмента нет.
+Внешние `platform_id` и `channels` переводятся в серверные `channelId` и `transports`;
+все десять отчётов воронки также передают канал как `channelId`.
+
+Во «Входящих» заявка — органический заказ, созданный нашим агентом, либо оплаченный заказ
+менеджера школы или самого человека с меткой продажи виджета (оплата по предложению).
+Два заказа одного человека — две заявки. Заявка датируется созданием заказа; счёт заказа
+с меткой продажи — оплатой. Оговорка: если дата создания заказа с меткой продажи виджета
+неизвестна, сервер использует дату оплаты для датировки заявки. Заявка, счёт и оплата относятся
+к своим событиям в календарных сутках Москвы. Определение «Заявок» в описании инструмента и
+подсказке денежного ответа дословно совпадает с серверным:
+`INBOUND_GETCOURSE_APPLICATION_DEFINITION` в
+`besales-api/src/shared/constants/getcourse-application.constants.ts`, используемым описанием
+денежного отчёта в `besales-api/src/control/inbound-analytics/inbound-analytics.controller.ts`.
+Мост сохраняет серверные цифры без пересчёта.
+
+Таблица страниц первого захода виджета доступна экрану через отдельный REST-маршрут, без
+нового значения отчёта MCP. Она считает посетителей когорты первого захода: живое сообщение
+и наличие заказа — признаки посетителя на момент снимка. Заявка — заказ, созданный агентом
+в диалоге, или оплаченный заказ с меткой продажи виджета (оплата по предложению), даже без
+заказа агента. Второй случай включает заказ менеджера или самого посетителя; живое сообщение
+для заявки не требуется. Два заказа
+одного посетителя дают один признак; последующие действия не ограничены концом периода
+захода. Денежные отчёты сохраняют собственную единицу — заказы. Отсутствующее значение
+неизвестно, нулём его подменять нельзя.
+
+Полнота веток удерживается локальной картой и проверкой перечисления. Выгрузка маршрутов для
+API выполняется после коммита моста: незакоммиченный исходник не является эталоном выгрузки.
+
+Фасад рассылок сохраняет готовые `gcUserUrl` и `gcDealUrl` в списках `recipients` (кроме
+поимённого отсева `notSent`), `deals` и `action_failures`. `null` означает отсутствие доказанного
+домена школы или идентификатора; мост и ассистент адрес не придумывают. Школу заказа агента
+определяет явное CRM-подключение заказа, даже если переписка шла в Telegram или ВКонтакте.
+Типы ответов генерируются из OpenAPI целевого API командой `yarn types:gen:api`.
+
+Для всех шести входящих отчётов генератор подбирает настоящий транспорт `Telegram`, который
+передаётся серверу как `TELEGRAM`, сохраняя остальные фильтры. Свободная строка `channels`
+в отгруженной схеме не меняется. Подтверждённое расширение перечисления отчётов проверяется
+и после предела перебора: повтор допустим только при приёме обоими фильтрами и том же методе
+и адресе. `stage-path` классифицируется как вариант только v2 по пути `report`;
+неподтверждённый предел перебора сохраняет собственную диагностическую причину.
+
+## Валюты и точность сумм
+
+Фасад рассылок, список когорт, все шесть отчётов входящих, каталог ссылок и разбивка по источникам принимают `currency`: код из трёх заглавных букв ISO 4217 либо `UNKNOWN`. Поле передаётся одноимённым query-параметром. Пропуск сохраняет серверное поведение: скаляр в валюте школы с предположительными прежними суммами. `UNKNOWN` выбирает только неизвестную исходную валюту. Очереди кандидатов и справочники фасада этот фильтр отвергают по полю `currency`; охват ссылок и лента кликов его не принимают.
+
+`moneyTotalsByCurrency` — раздельные итоги исходных валют; их нельзя складывать между валютами. `currency=null` означает неизвестную валюту; `displayCurrency` — подпись показа, `currencyAssumed=true` — предположение. Ни мост, ни ассистент не конвертируют деньги по курсу и не подставляют RUB в неизвестную валюту. `amountExact`, прочие поля `*Exact` и строковое `amount` валютных разрезов сохраняются как десятичные строки без Number/parseFloat/округления; они предпочтительнее числового приближения. Если точной строки нет в ответе API, мост её не выдумывает. Инструкции моста адресованы ассистенту на русском, как остальная поверхность; пересказ человеку — на его языке.
+
+Готовые формулировки для пяти языков:
+
+| Язык | Подпись и правило |
+| --- | --- |
+| ru | Валюта неизвестна. Предположительная валюта показа. Суммы разных валют не складываются; точные суммы сохраняются без округления. |
+| en | Currency unknown. Assumed display currency. Amounts in different currencies are kept separate; exact amounts are preserved without rounding. |
+| es | Moneda desconocida. Moneda de visualización supuesta. Los importes de distintas monedas se mantienen separados; los importes exactos se conservan sin redondear. |
+| id | Mata uang tidak diketahui. Mata uang tampilan diasumsikan. Jumlah dalam mata uang berbeda dipisahkan; jumlah tepat dipertahankan tanpa pembulatan. |
+| uz | Valyuta nomaʼlum. Koʻrsatish valyutasi taxmin qilingan. Turli valyutadagi summalar alohida saqlanadi; aniq summalar yaxlitlanmaydi. |
+
+Опубликованная схема входа и локальная карта маршрутов обновляются вместе с кодом; карта содержит запросы с USD. Подписанная выгрузка API, OpenAPI и генерируемые из него типы перевыпускаются креслом после коммита, по правилам происхождения снимка.

package/docs/modules/besales-mcp.md

@@ -0,0 +1,137 @@
+# Мост инструментов Besales
+
+Agent create/update передают raw model серверу: exact aliases/поддержка проверяются API.
+Собственного whitelist мост не имеет. Scheduled daily/hourly.model и max_tokens: отказ до HTTP, пока запись закрыта флагом API SCHEDULED_TASK_MODEL_WRITES_ENABLED (поэтапный выкат); мост откроет их вместе с флагом. Model inventory тест держит эти два договора; другая половина HTTP/БД —
+в API на contracts/mcp-tool-routes.json. Comparison ceiling/subset согласуются с PS;
+execution catalogue не расширяет comparison автоматически. API checker требует явный
+MCP_DIR и сверяет schema export/предел/workflow.
+
+Мост проверяет аргументы инструментов, переводит прежнюю форму полей в форму API и возвращает ответы сервера с короткими инструкциями для помощника. Секреты, одноразовые коды подключения и адреса служебных чатов не записываются инструментом настройки предупреждений.
+
+Выключатель канала принимается под прежним разделом настроек доступа. Если выключатель передан также в общих настройках, значение общих настроек имеет приоритет, как в прежней системе. Явное выключение сохраняется. Номера воронки, стадии, группы и предложения GetCourse в волнах допускают ноль; отрицательные, дробные и небезопасные целые отвергаются до вызова сервера.
+
+## Сверка отгруженного контракта
+
+Шаблоны комментариев Instagram принимаются под прежними именами
+`instagram_comment_templates`: `dm`, `dm_complaint`, `public_complaint`, каждый
+с языками `ru`, `uz`, `uz_cyrl`. Мост переводит их в имена HTTP-документа API,
+сохраняя все девять значений. Отсутствующее поле сохраняет настройку, `{}`
+очищает документ, `null` передаёт отсутствие документа. `PUBLIC_AND_DM`
+передаётся отдельным значением; метка жалобы `instagram_comment_kind=COMPLAINT`
+передаётся настройкой триггера. Сервер допускает новые записи только на этапе
+WRITER своей двухэтапной раскатки; отказ ворот не означает отсутствующий маршрут.
+
+Каждая строка реестра отставания имеет задачу-владельца вида `TASK-<номер>`
+либо пару `owner=DELIBERATE`, `severity=DELIBERATE` с причиной. Выгрузка
+отказывает при нарушении этого правила в любом разделе реестра, без бюджета
+на строки без владельца. Существование открытой задачи проверяется по рабочему
+плану при разборе пачки; синтаксический сторож не доказывает её открытость.
+
+Выгрузка маршрутов сначала проверяет вызов со всеми полями отгруженной схемы. У поимённо учтённых инструментов с взаимоисключающими полями она при отказе пробует минимальный набор обязательных полей вместе с проверенными аргументами маршрута. У каждой такой записи есть причина и владелец. Если полный набор начнёт собираться, выгрузка потребует удалить протухшую запись. Запасной образец проверяет рабочий вариант вызова; совместимость остальных сочетаний необязательных полей он не доказывает.
+
+Образец строки запроса отгруженного клиента сохраняет его фактические метод и адрес. Если v2 добавила параметры к запросу, у которого раньше их не было, выгрузка сохраняет пустой объект `{}` и для DELETE, POST, PATCH и PUT. Параметры v2 в него не подставляются. Так удаление переменной с новым `confirm=true` не скрывает прежний вызов без query; отсутствие его старого маршрута требует отдельного объяснения в API.
+
+## Настройки канала и предупреждений
+
+`besales_broadcast_alert_settings_update` меняет только долю доказанных недоставок. Адрес служебного Telegram-чата привязывают и отключают командой внутри группы. Чтение настроек показывает существующую привязку и порог.
+
+Для GetCourse `besales_platform_settings_update` принимает выключатель молчания бота при открытом платном счёте, ссылку на таблицу знаний рабочей области и имена колонок продукта и темы, а также имя переменной контакта с темой. Колонка продукта содержит номера продуктов GetCourse, на которые ссылаются предложения открытого счёта. Любая правка этих пяти полей требует явного подтверждения. При включении сервер требует все четыре опорных поля в сохранённом состоянии. Причины молчания сервер подписывает на языке канала; помощник показывает подпись, а не внутренний код.
+
+Карта маршрутов проверяет обычные настройки канала и подтверждённую правку открытого счёта двумя отдельными образцами. Оба вызывают один маршрут, но у правки счёта есть собственная проверка подтверждения на стороне сервера.
+
+## Действия и аудит заказов
+
+У шага создания заказа GetCourse можно включить использование уже открытого платного счёта человека той же школы. Подходит только счёт, чей продукт входит в предложение шага; ограничения давности нет. Если сведения о продуктах счёта или предложения получить не удалось, сервер не считает счёт подходящим. Сервер возвращает `reusedOpenInvoice=true` у успешно использованного счёта. Это успешное выполнение шага, но нового заказа и новой денежной регистрации нет. Выгрузка переписки и сценарий аудита исключают такой шаг из числа новых заказов.
+
+## Цепочки и волны
+
+Записка цепочки задаётся как `config.contactVariablesOnSend`: от одного до десяти имён переменных контакта с непустым значением длиной до 500 кодовых единиц. Для полной правки цепочки прочитанную записку нужно передать обратно. Ответ записи может содержать `warnings[]` о неготовой CRM-стадии; предупреждение не отменяет успешную запись.
+
+У одиночной волны GetCourse и долгого прогона строка получателя и новая строка сделки записываются за ведущим каналом человека, даже если список загрузили через соседний канал. Существующая строка сделки остаётся за каналом первой волны. Деньги и зачёт оплаты читают канал строки сделки. Предпросмотр и статус показывают `ledByOtherSchoolChannel.count` — число людей, чей живой адрес ведёт соседний канал.
+
+## Аналитика и правила текста
+
+В отчёте циклов сделки поле `cut` различает общий итог стадии и разрезы по продукту или сегменту. Пустой ключ разреза означает отсутствие продукта или сегмента, а не строку «Итого». Для итога берут `cut=overall`; медианы разрезов не складывают.
+
+В правилах замены исходящего текста образец должен быть непустым после `trim()`, но его значимые краевые пробелы сохраняются. Образец и замена отвергают несимволы Unicode. Сервер раскрывает escape в замене за один проход и экранирует обратную черту при чтении; прочитанную замену можно отправить обратно без изменения смысла.
+
+При правке только правил замены мост не добавляет `skip_task_creation_on_call_operator` в запрос: сохранённый выбор о создании задачи при вызове оператора должен остаться прежним. Явно переданное значение, включая `false`, мост переносит из прежней секции расписания в секцию фильтров. Для первой записи секции серверу требуется умолчание `false`; пока серверная схема требует поле без умолчания, такая частичная запись будет отклонена.
+
+## Имена сервера и прежние имена
+
+Сервер говорит только своими именами: канал подключения — `channelId`, карточка контакта — `contactId`, мессенджер (Telegram, WhatsApp…) — `transport`/`transports`, номер ученика GetCourse — `getcourseUserId`. Вход отгруженных инструментов остаётся прежним (`platform_id`, `channels`, `contact_id` у строк волн): мост переводит его в имена сервера в `createRequest`. Прежних имён в запросе к серверу нет — это держит сторож `legacy-api-names.spec.ts`: каждая запись карты маршрутов и синтаксическое дерево определений. Исключения поимённые: дописывание выдачи и два неиспользуемых помощника.
+
+Выдача инструмента, отгруженного клиентам, не теряет ни одного поля из-за переименований на сервере: реестр `shipped-output-names.ts` дописывает прежнее имя рядом с новым в каждом объекте выдачи — то же значение, имя сервера остаётся на месте. Дописывание стоит в одном месте — в обработчике вызова, после ответа инструмента; инструкция ответа называет дописанные имена. Новые инструменты получают только новые имена. Состав реестра выведен из описания сервера (операция с переименованным полем ответа → запись карты → инструмент отгружен), независимый перечень ожидаемых пар держит `shipped-output-names.spec.ts`. Ранние дописывания истории касаний и охвата ссылки живут в своих инструментах.
+
+У людей прогона волны `contactId` — карточка контакта, `getcourseUserId` — номер ученика; для повторной отправки в `contact_id` подставляется номер ученика. Инструкция инструмента говорит это прямо.
+
+Прежняя установка моста после переключения сервера шлёт прежние имена и получает отказ `LEGACY_FIELD_NAME` с полями `field`, `replacement` и `remediation`. Прежний клиент показывает модели текст `remediation` («перезапустите приложение, без поля запрос не отправляйте») вместо своего «исправь причину и повтори вызов»; это проверяет `scripts/legacy-field-refusal.shipped.spec.mjs` на коде отгруженной линии.
+
+## Сессии подключения
+
+API возвращает `channel_id`, а `besales_platform_create_status` дописывает
+`platform_id` для отгруженного клиента, в том числе null. Старый ответ с
+`platform_id` поддерживается. Ссылка и ref трёх init передаются человеку без
+логовой редакции успешного tool result; CRM содержит оба массива имён полей.
+Путь debug-записи маскируется, четыре polling пути кодируют ref как один сегмент.
+В долговечную задачу допускается ref, адрес страницы запрещён.
+
+До переключения API выпуск v2 доступен только как `next`. `latest` меняется
+в момент переключения с сообщением «перезапустите приложение». Старый
+установленный handler на новом API не создаёт `platform_id`; это известное
+окно перехода. Дописывание нового моста не обновляет уже запущенный процесс.
+
+Читатель HTTP-метаданных вызывает `ApiClient.requestWithResponse<T>` и получает `{status, data, headers}`.
+Axios-транспорт передаёт все заголовки ответа с именами в нижнем регистре, включая Cache-Control, Pragma,
+Retry-After, Content-Type, Content-Disposition и корреляцию. Многозначные заголовки сохраняются массивами.
+Обычные `request`/`post` возвращают тело; заголовки ошибок доступны в `ApiClientError.headers`.
+Мост не сохраняет тела ответов в постоянном кэше и не добавляет HTTP-метаданные в текст инструмента.
+Неожиданные строки, массивы и scalar ответы читателей прогонов проходят безопасную проекцию
+до перевода отгруженных имён и превращаются в пустую оболочку.
+
+## Перечни и подсказки рассылок
+
+enumValuesByPath разворачивает refs и все ветки anyOf/oneOf/allOf любой глубины, собирает enum и const на каждом пути, включая элементы массива [] и отдельную скалярную ветку. null в перечне и ветви не считается значением. Битая ссылка вызывает отказ. Сторож сравнивает значения общих путей в JSON и фактическом zod-фильтре; односторонние пути учтены поимённо, отказы конвертера считаются по именам, число сравнений не опускается ниже замера. Замер 01.10.2026: 274 общих пути, 4 односторонних, 0 отказов. Два старых перечня импорта разбора диалогов сгенерированы из фильтра: 12 категорий и 4 уровня.
+
+Граница обещания: совпадение перечней не доказывает полноту необязательных полей в обратную сторону (zod→JSON), сочетания полей и доступность живого API. Тот сверочный контур остаётся отдельным.
+Пределы `minimum`/`maximum`/`maxItems` сверяются только там, где есть отдельный тест, например `model-comparison.spec.ts`.
+
+Ответы предпросмотра, истории и пула объясняют все причины excludedBy; сохранение расписания направляет к besales_broadcast_schedule_preview без копии перечня причин. repeatNoCard означает отсутствие живой или восстановимой карточки на канале расписания. contactBlocked/blocked говорят о бане, отказах, действующем мьюте или слиянии: операторское удаление само по себе не держит отправку. По умолчанию пул выбирает старший по дате создания подходящий GetCourse-канал; web widget остаётся отдельной платформой.
+
+### Совместимость настроек канала и доставки шага
+
+`besales_followup_sequence_upsert` описывает `config.steps[].getcourse.delivery` в публичной
+схеме и при проверке вызова. Режимы `contact`, `all`, `explicit` и написание транспортов школы
+передаются серверу без переименования внутри `config`. `all` исключает SMS, явный список
+непустой; SMS требует отдельного шага. Доставка у вебхука отвергается. Полная правка с
+`delivery: null`, `contact` или без доставки снимает носитель набора; серверный флаг записи
+остаётся в силе. Для защиты открытой формы передавай в PATCH её исходную `editRevision`
+через `expected_version`. Без него нужны оба права `read:workflows` и `write:workflows`:
+мост читает текущую ревизию по ID цепочки в канале, затем выполняет один PATCH.
+Это защищает только окно между GET и PATCH: изменения после открытия формы и до GET
+могут быть перезаписаны. Чтение текущей ревизии не заменяет исходную ревизию формы.
+Если ревизия успела измениться, 409 возвращается вызывающему без автоматического повтора.
+Ошибка чтения или некорректная ревизия останавливают запись.
+Объекты `getcourse` и `getcourse.delivery` дополнительно принимают `null`: это расширение
+прежнего ввода объявлено в реестре отдельно; долги отсутствовавших полей доставки сняты.
+
+`instagram_comment_templates` принимает три группы (`dm`, `dm_complaint`, `public_complaint`)
+и три языка (`ru`, `uz`, `uz_cyrl`). Мост переводит их в серверные имена, сохраняя все девять
+значений. Объект полностью заменяет шаблоны, `{}` и `null` очищают, отсутствие сохраняет. Предел одного
+текста — 500 кодовых единиц UTF-16. `PUBLIC_AND_DM` остаётся самостоятельным режимом.
+
+В прежнем оформлении виджета переводятся также `popup.backgroundColor/textColor`,
+`window.botMessageBackgroundColor` и `window.userMessageBorderColor`. Канонический раздел
+`general_settings.customization.popup` тоже передаётся серверу. `null` у CRM-полей правила
+`entry_url_variable_mapping.rules[]` удаляет соответствующие ключи; остальные поля и правила
+сохраняются. Три отказа на сброс оформления и карт целиком остаются адресными. Прежние пустые
+списки сайтов означают `['*']`, канонический пустой список означает отсутствие доступа.
+
+Настройки канала, поведения и холодных отправок GetCourse идут **одним PATCH** в
+`/channels/:id/settings` и сохраняются в одной транзакции: ошибка любой секции отменяет
+всю запись. Ответ сохраняет `getcourseOutboundSettings` с хранимыми и действующими
+значениями для переданных полей предохранителя и тихого периода.
+
+Адрес отказавшего поля API сохраняется в `error.details.path`, например `isEnabled` или
+`config.steps[0].getcourse.delivery`. Диагностика допускает только ограниченный адрес поля;
+URL, файловые пути и произвольное содержимое вместо адреса не передаются.

package/docs/modules/dialog-review-report.md

@@ -0,0 +1,38 @@
+# Отчёт ревизора диалогов
+
+Оба инструмента чтения находок запрашивают `format=page`. Сервер сначала получает поддержку
+этого параметра, сохраняя массив по умолчанию, затем выпускается мост. Новый мост нельзя
+направлять на сервер, который ещё отвергает параметр; откат сервера требует отката моста.
+Наличие пакета в npm не определяет наличие локальных установок из исходников.
+
+Новая форма — `{ items, truncated }`. Первыми идут самые тяжёлые находки; отбор выполняется
+перед ограничением числа строк. `truncated=true` означает, что находок больше, чем показано.
+При лимите меньше 100 его можно увеличить; на потолке нужно сузить отбор.
+
+Переводчик прежних имён читает как массив, так и новую страницу. Для массива признак
+вычисляется пробой на одну лишнюю строку; при лимите 100 полный массив остаётся осторожно
+усечённым. Для новой страницы используется признак сервера вместе с размером ответа.
+Нативный инструмент обозначает неизвестную полноту массива как `truncated=null`.
+Неизвестная форма ответа приводит к явной ошибке.
+
+`chunkCount` в переводе отчёта — число начатых попыток разбора (`segmentAttemptCount`).
+Одна попытка может включать несколько обращений к провайдеру либо ни одного. `null` означает
+«не измерено», а 0 — измеренный ноль. Внешний импорт не вызывает модель. Прогон принадлежит
+одному агенту, поэтому `agentCount=1`; `rejectedFindingCount` сохраняет число находок,
+которые сервер не записал. Сводка моделью здесь не строится.
+
+`rejectedFindings` ответа внешнего импорта учитывает находки принятых отрезков с чужим
+якорем и находки по стёртому контакту. Ненулевое значение само по себе не доказывает ошибку
+якоря. Карточка использует человеческое имя агента из `report.agentName`.
+
+Карточка прогона возвращает допущенную сервером справку summary и состояние summaryState.
+Справка собирается только из подтверждённых фрагментов, а не из свободного ответа модели;
+оба инструмента карточки помечены как носители персональных данных клиентов воркспейса.
+Отсутствие справки именовано, например нечитаемая политика канала, отказ бюджета или
+стирание источника. Список прогонов summary не содержит. Область маршрута — read:agents
+(для ключа MCP — composite mcp:*); автономного чтения источников мост не делает.
+
+Оба инструмента карточки фильтруют ответ по явному списку публичных полей. Служебные токен
+владельца, heartbeatAt, отпечатки правил и инструкции, а также неизвестные новые поля
+не проходят в ответ моста. Публичные счётчики, справка и report сохраняются; псевдоним
+добавляет прежние имена только после фильтрации.

package/docs/modules/dialogue-followup-adapters.md

@@ -0,0 +1,39 @@
+# План воронки и независимая пауза дожимов
+
+`besales_followup_funnel_test_plan` принимает необязательный `funnel_id` и передаёт его как
+`funnelId` в тело плана по адресу человека. Без поля тело запроса отсутствует, как прежде.
+API проверяет пространство, канал и архивность выбранной воронки. Закрытый расширенный режим
+возвращает отказ; мост не переключает его. План сохраняет черновик и ничего не отправляет.
+Запуск остаётся отдельным инструментом с явным подтверждением и причиной после показа плана.
+
+`besales_dialogue_followup_state_get` читает один диалог. API определяет пару «контакт × канал»
+и возвращает сохранённое и действующее состояние, время измерения, `editVersion`, доступные
+действия, последствия и ограничения. Мост сохраняет ответ целиком и не переводит тексты API.
+
+`besales_dialogue_followup_state_update` вызывает `PATCH /conversations/:id/followup-state/bridge`:
+
+| Аргумент           | Тело API             | Правило                                                            |
+| ------------------ | -------------------- | ------------------------------------------------------------------ |
+| `conversation_id`  | идентификатор в пути | Обязателен                                                         |
+| `action`           | `action`             | `ENABLE`, `MUTE_FOREVER`, `MUTE_TEMPORARY`                         |
+| `expected_version` | `expectedVersion`    | Обязательная версия из чтения этого диалога                        |
+| `mute_expires_at`  | `muteExpiresAt`      | Только для `MUTE_TEMPORARY`, обязательный момент со смещением зоны |
+
+Временные границы проверяет API. Перед записью ассистент показывает последствия и ограничения
+и получает явное решение человека. Ключу нужны права чтения диалогов и расширение настройки
+платформы `mcp:platform-setup` для записи (`write:followup-state`); API проверяет текущие права
+создателя ключа и доступ к диалогу. Писатель не меняет права и не использует экранный маршрут.
+
+Ответ записи сохраняется целиком, включая `outcome` и `state`. На 409/428 запрос автоматически
+не повторяется: ассистент сохраняет намерение, перечитывает состояние, показывает актуальные
+последствия и ждёт нового решения человека. Сетевой сбой означает неизвестный исход, для
+проверки используется чтение. Ошибка чтения не означает включённые дожимы.
+
+Выключение может отменить текущие касания; включение их не воскрешает. Пауза не отзывает уже
+доставленное и не обещает остановить все сообщения. Ответы API на ru/en/es/id/uz сохраняются
+без подмены локализованных причин или матрицы последствий.
+
+Проверки адаптеров: `node scripts/verify-followup-adapters.mjs`. Скрипт создаёт временную копию
+моста, добавляет только нужные записи каталога для проверки будущей сборки и выполняет адресные
+наборы и мутации в этой копии. Исходный сгенерированный каталог выпускает интегратор после
+сведения с читающим инструментом; до этого выпуска дерево не является готовым пакетом MCP.

package/docs/modules/message-reactions.md

@@ -0,0 +1,17 @@
+# Реакции сотрудника на сообщения
+
+Emoji на конкретном сообщении — операторский HTTP API besales-api. Мост не получает нового инструмента и не подменяет эту операцию инструментом `besales_followup_reactions`: тот читает аналитику откликов на дожимы через GET.
+
+Операторские маршруты под `/api/v2/workspaces/{workspaceId}/messages`:
+
+- `POST /reactions/query`, тело `{messageIds: UUID[]}` длиной 1–100, чтение диалогов.
+- `PUT /{messageId}/reaction`, тело `{emoji}`, обязательный `Idempotency-Key: UUID`, право ответа. `null` снимает реакцию.
+- `GET /{messageId}/reaction/operations/{operationKey}`, где ключ — исходный `Idempotency-Key`, чтение исхода той же команды.
+
+Операции доступны вошедшему сотруднику. Ключ MCP не становится оператором. Сервер сам определяет Telegram-адрес, физический номер, канал и автора.
+
+Подтверждённое состояние общее для сотрудников области. Это последняя принятая команда BeSales, не live-счётчик Telegram. 204 означает подтверждение провайдера и долговечную запись. Ошибки 409/503 сохраняют прежний emoji; неизвестную команду нельзя автоматически повторять новым ключом. После replay старого подтверждённого ключа следует перечитать batch — replay не откатывает более новую команду.
+
+Контрактные DTO и Swagger-декораторы принадлежат besales-api. Выпуск канонического OpenAPI и синхронизация `src/types/api-contract.gen.ts` выполняются вместе с итоговым API ref. В карту MCP-маршрутов операторская запись не добавляется.
+
+Проверки границы: `src/tools/definitions/message-reaction-boundary.spec.ts` и существующий `follow-up.spec.ts`.