@besales/mcp 0.48.0 → 1.0.0-beta.2

package/docs/connect.ru.md

@@ -1,5 +1,134 @@
 # Подключение Besales MCP к Claude Code и Codex
 
+## Онлайн-MCP: подключение коллег
+
+Онлайн-MCP позволяет Claude Code и Codex CLI работать с твоей рабочей областью Besales:
+смотреть данные и выполнять действия в пределах выданных прав. Клиенты обращаются к
+`https://mcp.besales.ai/mcp`; держать локальный мост запущенным не нужно.
+
+Нужны Node.js 20+ (`node -v`), Claude Code и/или Codex CLI и аккаунт Besales с доступом
+к нужной рабочей области. Выполняй команды сам в своём терминале, не передавай ключ агенту
+и не вставляй его в чат.
+
+**Важно:** `beta` — тег предварительной версии. Для этих инструкций нужен именно
+`@besales/mcp@beta`. Обычный `npx -y @besales/mcp` без тега по-прежнему устанавливает
+прежнюю версию 0.48. Пакет этой ветки станет доступен через `beta` после публикации владельцем.
+
+### Шаг 1. Получи ключ своей рабочей области
+
+```bash
+npx -y @besales/mcp@beta connect
+npx -y @besales/mcp@beta connections
+```
+
+Первая команда открывает браузер: войди в Besales, выбери область и подтверди права.
+Ключ `mcp_…` сохранится в локальной связке ключей. Повтори `connect` один раз для каждой
+нужной области; вторая команда покажет их имена и UUID. Ключ получается локальной командой
+`connect` один раз, а дальше локальный мост для работы онлайн-клиентов не нужен.
+
+### Шаг 2. Настрой клиентов скриптом или вручную
+
+В репозитории [be-sales/mcp](https://github.com/be-sales/mcp) скачай файл
+`scripts/connect-clients.sh` из ветки с онлайн-MCP и запусти:
+
+```bash
+bash scripts/connect-clients.sh
+```
+
+Или получи скрипт из установленного пакета:
+
+```bash
+npm install -g @besales/mcp@beta
+bash "$(npm root -g)/@besales/mcp/scripts/connect-clients.sh"
+```
+
+Скрипт читает только `connections --json`: это JSON-массив объектов
+`{workspaceId, workspaceName, accountLabel, keyPrefix, active}` одной строкой, без полных ключей.
+В обычном выводе управляющие символы имён и подписей заменяются пробелами; JSON сохраняет
+имя целиком с экранированием. Имена передаются разборщику только через stdin, без исполнения.
+Скрипт принимает UUID только по шаблону `^[0-9a-f-]{36}$` и создаёт запись
+`besales-<слаг имени>` только из букв `a-z`, цифр и дефиса: для слага берутся первые
+200 символов очищенного имени, сам слаг ограничен 64 символами; пустой слаг заменяется
+первыми 8 символами UUID. При совпадении имён добавляются первые четыре символа UUID,
+при дальнейшей коллизии — полный UUID. Отсутствующий в PATH клиент
+пропускается. Повторный запуск обновляет подключения. Для выбора отдельных областей передай
+имена записей или префиксы UUID:
+
+```bash
+bash scripts/connect-clients.sh besales-sales 1234abcd
+```
+
+Ключи для Codex сохраняются в `~/.besales-secrets/mcp-remote-keys.env` (каталог 700, файл 600).
+Скрипт напечатает строку `source` без ключей: добавь её в `~/.zshrc` или `~/.bashrc` и выполни
+в текущем терминале. Запускай Codex из терминала, где загружены эти переменные.
+При любом запуске сохраняются посторонние строки и переменные остальных областей:
+заменяются или добавляются только `export BESALES_MCP_KEY_<ИМЯ>="…"` успешно подключённых
+в этом запуске областей и отсутствующий заголовок. Повторный запуск не дублирует записи.
+Запись атомарна: временный файл рядом с исходным и `mv`; ошибка клиента сохраняет прежний файл.
+
+Адрес можно задать через `BESALES_MCP_URL`, команду получения ключей — через
+`BESALES_MCP_BRIDGE` (по умолчанию `npx -y @besales/mcp@beta`). Для исходников:
+
+```bash
+BESALES_MCP_BRIDGE='node /путь/к/mcp/bin/besales-mcp.js' bash scripts/connect-clients.sh
+```
+
+Здесь команда моста — аргументы через пробелы; путь не должен содержать пробелов.
+
+Вместо скрипта можно выполнить три команды вручную. Замени `UUID` идентификатором из
+`connections`, а `besales-sales` — своим уникальным именем записи:
+
+```bash
+claude mcp add --scope user --transport http besales-sales https://mcp.besales.ai/mcp --header "Authorization: Bearer $(npx -y @besales/mcp@beta key UUID)"
+export BESALES_MCP_KEY_SALES="$(npx -y @besales/mcp@beta key UUID)"
+codex mcp add besales-sales --url https://mcp.besales.ai/mcp --bearer-token-env-var BESALES_MCP_KEY_SALES
+```
+
+Для ручной настройки Codex повторяй `export` в каждом новом терминале или добавь именно
+команду с подстановкой `$(…)` в профиль оболочки. При нескольких областях нужны разные
+имена записей, UUID и имена переменных. Для обновления уже существующей записи сначала
+удали её: `claude mcp remove --scope user besales-sales` или `codex mcp remove besales-sales`,
+затем повтори нужную команду добавления. Скрипт делает это сам.
+
+Ключ лежит в настройках Claude Code открытым текстом. Codex хранит имя переменной,
+а её значение скрипт записывает открытым текстом в закрытый файл. Не публикуй настройки
+или файл ключей, ограничь доступ к своему компьютеру. Подстановка команды в терминале
+не печатает ключ; отдельная команда `key [UUID]` выводит секрет, поэтому не запускай её
+на общей демонстрации экрана.
+
+Известное ограничение: Claude Code принимает заголовок только аргументом команды
+`claude mcp add --header`, поэтому на время её выполнения (доли секунды) ключ виден в
+списке процессов этого же компьютера. Запускай скрипт на личном компьютере, где нет
+посторонних пользователей. У Codex такого нет: ему передаётся только имя переменной.
+
+### Шаг 3. Проверь подключение
+
+```bash
+claude mcp list
+codex mcp list
+```
+
+Проверь установленный у тебя клиент, открой новую сессию агента и спроси:
+«какая у меня рабочая область?». Ответ должен соответствовать выбранной области.
+
+| Ответ службы | Что делать |
+| --- | --- |
+| 401 | Ключ просрочен (срок — 90 дней), отозван или потерял доступ. Снова выполни `npx -y @besales/mcp@beta connect`, затем скрипт; для Codex повтори `source`. |
+| 502 | Ядро временно недоступно. Для известного ключа повторная проверка приостановлена до 5 секунд; соблюдай `Retry-After`. |
+| 429 | Достигнут лимит. Подожди число секунд из `Retry-After` и повтори запрос. |
+| 503 | Служба занята или обновляется. Повтори через несколько секунд. |
+
+Чтобы отозвать доступ, открой список подключений в Besales и отзови нужное подключение.
+Удаление записи только в Claude Code или Codex не отзывает сам ключ.
+Общая проверка службы учитывает отзыв ключа после истечения кэша, даже если все
+ожидавшие её клиенты отключились до ответа ядра.
+
+## Локальное подключение через stdio
+
+Ниже — прежний способ: мост работает локально при каждом запуске клиента.
+Для онлайн-службы используй три шага выше.
+
+
 Три шага: добавить сервер в программу → один раз войти через браузер → открыть новую сессию и
 проверить. Пароли и токены в чат не вводятся никогда — вход только через браузер.
 
@@ -85,14 +214,22 @@ Code или Codex.
 труднее найти нужный. Во вкладке Code десктоп-приложения Claude видны ещё и серверы, добавленные в
 Claude Desktop, — учитывай их тоже.
 
+## Другие команды
+
+| Команда | Что делает |
+|---|---|
+| `npx -y @besales/mcp status` | показать выбранную компанию и все подключения |
+| `npx -y @besales/mcp connections` | список подключённых компаний с их ID |
+| `npx -y @besales/mcp disconnect <id>` | отключить одну компанию (`--all` — все) |
+
 ## Обновление
 
 1. Закрой и снова открой программу.
 2. Один раз для каждой компании: `npx -y @besales/mcp@latest connect`.
 
 Новые права помощнику выдаются только при подключении, поэтому шаг 2 обязателен, когда в версии
-появились новые возможности (с 0.47.0 — контакты и назначение операторов). `@latest` нужен потому,
-что npx хранит старую копию пакета в кэше. Уже работающие настройки от этого не сбрасываются.
+появились новые возможности. `@latest` нужен потому, что npx хранит старую копию пакета в кэше.
+Уже работающие настройки от этого не сбрасываются.
 
 ## Как проверить, что всё работает
 
@@ -100,7 +237,8 @@ Claude Desktop, — учитывай их тоже.
 В ответе должны быть:
 
 - названия компаний и какая выбрана сейчас;
-- в `effective_scopes` — `read:contacts` и `write:operators` (с версии 0.47.0).
+- в `effective_scopes` — права, которые ты выдал при подключении. Если нужного права нет (например
+  `read:contacts` или `write:operators`), выполни `connect` ещё раз и дай его на странице согласия.
 
 ## Если что-то не так
 
@@ -110,7 +248,9 @@ Claude Desktop, — учитывай их тоже.
 | Просит ID рабочего пространства | Скажи «покажи мои рабочие пространства» и выбери по названию. Вводить ID не нужно. |
 | «Не хватает прав» (403) | `npx -y @besales/mcp@latest connect` и перезапуск программы. |
 | После обновления нет новых инструментов | npx взял старую копию: `npx -y @besales/mcp@latest connect`, затем перезапуск. |
-| Страница входа пишет, что `scope` не поддерживается | Пакет новее сервера Besales. Подожди обновления сервера или напиши в поддержку. |
+| Страница входа пишет, что набор прав недопустим, и называет право | Пакет новее сервера Besales: он просит право, которого сервер ещё не знает. Подожди обновления сервера или напиши в поддержку. |
+| `connect` пишет `WARNING: this key has FEWER permissions than the one it replaced` | Новый ключ получил меньше прав, чем прежний ключ в этой компании (`Lost:` — какие). Обнови пакет и подключись ещё раз: `npx -y @besales/mcp@latest connect`. |
+| `connect` пишет `WARNING: some requested permissions were not granted` | Роль в этой компании не разрешает часть прав (`Not granted:` — какие). Попроси владельца компании или администратора расширить роль и подключись ещё раз. |
 
 ## Для разработчиков: запуск из исходников
 

package/docs/contact-company-profile.md

@@ -0,0 +1,17 @@
+# Компания и должность в карточке человека
+
+Редактор компании принадлежит операторскому интерфейсу API. Он читает выбранный адрес человека
+и сохраняет только изменённые поля с обязательной непрозрачной `profileVersion`.
+Его GET/PATCH не вызываются инструментами моста и не добавляются в карту маршрутов MCP.
+
+`besales_contact_get` по-прежнему читает `/contacts/{contact_id}`. Поиск и пакетное чтение
+профилей сохраняют свой разрешённый состав ответа; они не получают права изменения.
+Новый инструмент записи компании не вводится. Ключ `read:contacts` не открывает операторский
+редактор, даже если вызывающий знает его адрес.
+
+Контракт формы и сценарий восстановления после 409 описаны в API:
+`docs/modules/contact-company-profile.md`. Базовый путь формы:
+`/api/v2/workspaces/{workspaceId}/contacts/{contactId}/identities/{identityId}/company-profile`.
+Нужны пользовательская сессия и текущие права `CONVERSATION_VIEW`/`CONVERSATION_REPLY`.
+
+Регрессия границы: `src/tools/definitions/contacts.spec.ts`.

package/docs/contact-recommendations.md

@@ -0,0 +1,7 @@
+# Рекомендации между людьми
+
+Рекомендации связывают выбранные адреса разных людей и не объединяют их карточки. Их редактор принадлежит пользовательскому API Besales. Ключи моста и публичного API не получают маршруты списка, поиска кандидатов, записи и удаления рекомендаций.
+
+Состав `besales_contact_get`, `besales_contact_search` и `besales_contact_diagnostics_get` сохраняется. Нового инструмента записи или фиктивной записи в реестре маршрутов нет. Исходный `operatorContactLinks` не является частью контрактов этих инструментов; API удаляет этот служебный ключ из канальных данных, включая вложенные значения.
+
+Переход к диалогу выполняет интерфейс по `target.conversationId`, полученному от отдельного API рекомендаций. Это существующий диалог именно `target.identityId` и `target.channelId`; при `null` интерфейс не выбирает случайный другой канал и не создаёт диалог запросом чтения.

package/docs/crm-stage-pool.md

@@ -0,0 +1,73 @@
+# Ответственные при смене стадии amoCRM
+
+Настройку передают существующие `besales_trigger_upsert` и
+`besales_followup_sequence_upsert`. Новых инструментов и прав нет. Список относится к
+подключению amoCRM целевой стадии; принадлежность каналу, пространству и подключению
+проверяет API. Сотруднику не обязательно иметь рабочее место Besales.
+
+Каноническое поле `assign_responsible_operator_ids` содержит уникальные UUID из каталога
+`crm_operators.id`. Порядок значим: сервер выбирает сотрудника по номеру сделки. Прежнее
+`assignResponsibleOperatorIds` содержит положительные безопасные целые номера пользователей
+amoCRM; API разрешает их в том же подключении. Два формата одновременно запрещены.
+Это настройка администратора, а не аргумент выбора сотрудника моделью во время исполнения.
+
+Пример действия:
+
+```json
+{
+  "stepType": "CRM_MOVE_STAGE",
+  "config": {
+    "schema_version": 1,
+    "step_type": "CRM_MOVE_STAGE",
+    "pipeline_external_id": "700",
+    "status_external_id": "701",
+    "assign_responsible_operator_ids": [
+      "10000000-0000-4000-8000-000000000031",
+      "10000000-0000-4000-8000-000000000017"
+    ]
+  }
+}
+```
+
+Пул действия — максимум 20 сотрудников. `config`, `crmConfig`, `crmMoveStage` и
+`crmMoveStageConfig` несут одну настройку; одновременно несколько оболочек запрещены.
+Прежняя `crmConfig.extra.assignResponsibleOperatorIds` разворачивается в
+`crmConfig.assignResponsibleOperatorIds` до HTTP. Неизвестные поля `extra` и канонического
+конфига стадии отвергаются; числа из строк не приводятся автоматически. Ошибочный список
+не становится командой снятия.
+
+У цепочки поле лежит прямо в `config`, без предела 20. Инструмент поддерживает
+`trigger=USER_INACTIVITY` и `trigger=LOST_CLIENTS`; второй соответствует внутреннему виду
+`CONTACT_INACTIVE`. Календарная форма молчания использует тот же список. Применение к
+собственным переходам с прямым номером стадии определяет API. Пул цепочки не заменяет
+пул вызываемого действия и не оживляет инертные поля источника.
+
+При правке других полей цепочки **не передавай ключ пула**: HTTP-тело сохраняет отсутствие,
+а API переносит прежний пул до перевода конфигурации. `[]` или `null` — явное снятие.
+Для действия правка метаданных без `actions` сохраняет шаги. Полная замена `actions`
+задаёт их заново: сначала прочитай контекст, затем передай желаемый набор вместе с пулом.
+Мост не получает `stepId` или `keepSecretFields`; ссылки интерактивного редактора отвергаются.
+
+Контекст канала, каталог действий и чтение цепочек сохраняют список без сортировки.
+Для чтения исходной формы цепочки передай `sequence_id`.
+Ответ `data` содержит `type`, `trigger`, `config` и `configUnavailableReason`; при
+`config=null` требуется восстановление полной формы. Исполняемые `latestVersion.steps`
+нельзя подставлять в `config`.
+Копирование цепочки и отдельная правка текста выполняются существующими маршрутами API;
+мост не переписывает их конфигурацию. Подсказки и отказы списка доступны на ru/en/es/id/uz,
+язык задаётся `BESALES_LOCALE`; HTTP передаёт его через штатный `Accept-Language`.
+
+Типы обновляются `yarn types:gen:api` из канона соседнего принятого API. Реестр пула
+обновляется после `yarn build` командой `yarn schemas:sync:crm-stage-pool`.
+Генератор сверяет UUID, уникальность и отсутствие общего цепочного предела с
+`openapi-generated.yaml`; он сохраняет объявления других полей. Каталог контрактов можно
+задать через `BESALES_API_CONTRACTS_DIR`.
+
+Карту маршрутов выпускает `yarn publish:mcp-registry` из закоммиченного дерева.
+Штатный отказ грязного дерева сохраняется: текущий рабочий код нельзя подписать старым
+коммитом. Реестр `shipped-lag.json` этим изменением не очищается.
+
+Проверки `crm-stage-pool.spec.ts` контролируют тела, чтение и отказы до HTTP;
+`crm-stage-pool.http.spec.ts` проверяет сериализованное тело через настоящий локальный
+HTTP-сервер и Axios. Серверные проверки принадлежности и сохранения идут по действующим
+API-наборам. Эти проверки не подтверждают поведение живой CRM или допуск школы.

package/docs/customer-data.md

@@ -0,0 +1,61 @@
+# Данные клиентов на пути моста
+
+## В чём проблема — и в чём её нет
+
+**Это не про право доступа.** Тот, кто зовёт мост, — сотрудник воркспейса; те же переписки он
+видит в интерфейсе продукта. Отбирать у него доступ не за чем.
+
+**Это про периметр.** Ответ инструмента оседает в транскрипте стороннего приложения (Claude
+Desktop, Cursor, другой хост) и в его телеметрии. Сроком хранения там владелец воркспейса не
+управляет и согласия у своих клиентов на такую передачу не спрашивал. Раньше тем же путём
+уходили партнёрские ключи — это уже исправлено; данные людей идут по нему до сих пор.
+
+## Носители — поимённо
+
+Разобрано по тому, что маршруты реально отдают, а не по названиям инструментов.
+
+План теста воронки тоже несёт данные конкретного человека. Его вызов сохраняет черновик
+на сервере и удаляет прежний черновик автора для этого человека, хотя сообщений человеку не
+отправляет. Поэтому у него одновременно есть пометка данных клиента и побочного эффекта.
+
+| Инструмент | Что именно уходит |
+|---|---|
+| `besales_dialogue_transcript` | реплики переписки целиком — всё, что человек написал сам: в тексте бывают телефон, адрес, номер заказа |
+| `besales_dialogues_query` | имя контакта и его идентификатор в канале (у части каналов это номер телефона), плюс суммы оплат |
+| `besales_getcourse_wave_run_contacts` | перечень контактов волны — это и есть назначение инструмента |
+| `besales_icp_sample_messages` | тексты реплик из отобранных диалогов |
+| `besales_dialog_review_findings` | находки со свободным полем подробностей: цитата из переписки туда попасть **может**, гарантий обратного нет |
+| `besales_dialogue_analysis_notes` | служебный разбор конкретной переписки: текст пересказывает сказанное клиентом и менеджером |
+| `besales_broadcast_analytics_get` | отчёты получателей, сделок, отказов действий и отсеянных отдают имя человека и его идентификатор в кабинете школы. До возврата выбора отчёта фасад умел только сводку и носителем не был |
+| `besales_broadcast_payment_candidates_list` | имя человека, его идентификатор в кабинете школы и ссылка на карточку — то же содержимое, что у фасада с отчётом оплат |
+| `besales_tracked_link_clicks` | лента переходов: имя контакта, его идентификатор и идентификатор сообщения, в котором ссылка была выдана. Соседние инструменты каталога ссылок носителями НЕ являются — там только сводные числа |
+
+Пометка живёт у определения (`carriesCustomerData`), а не списком имён в каждом новом месте:
+будущая политика применится к одному объявленному множеству. Тест держит, что пометка и
+предупреждение в описании описывают одно и то же множество — иначе помеченный без
+предупреждения молча отдаёт данные, а предупреждённый без пометки выпадет из политики.
+
+## Что сделано сейчас
+
+1. **Перечень носителей объявлен** и закреплён тестом: новый носитель не появится незамеченным.
+2. **Описание каждого носителя предупреждает** прямым текстом, что ответ содержит персональные
+   данные и сохранится в транскрипте хоста. Модель читает описания и передаёт это человеку.
+3. **Проверено, что мост не пишет эти данные в собственный лог**: наружу идёт только метод,
+   путь и код ответа.
+
+## Что НЕ сделано и почему это решение владельца
+
+Ограничить саму передачу можно тремя способами, и они несовместимы по цене:
+
+- **Обезличивать на стороне сервера.** Защищает сильнее всех, но ломает работу: по
+  обезличенному перечню волны некому написать, а это назначение инструмента. Часть смысла
+  теряют и разборы диалогов.
+- **Отдельная область доступа у ключа** (например `read:customer-data`). Передача становится
+  осознанным действием того, кто выпускает ключ, и видна в аудите. ⚠️ **Цена: в день включения
+  все существующие ключи теряют доступ к пяти инструментам**, пока область не выдадут заново.
+- **Согласие владельца воркспейса, записанное один раз.** Ничего не ломает и ничего не
+  ограничивает: фиксирует, что передача согласована.
+
+Выбор — не инженерный: он про обязательства перед клиентами школ и про то, чей это риск.
+Поэтому политика не выбрана в коде, а вынесена владельцу; объявленная пометка делает любой из
+трёх вариантов правкой в одном месте.

package/docs/edit-versions.md

@@ -0,0 +1,36 @@
+# Versions of settings forms
+
+Keep the version returned with the original form until the person decides to save
+that form. The tools below accept an optional `expected_version`. Omitting it
+preserves the existing API behavior; passing it protects the original snapshot.
+
+| Tool                                | Version sent to the API                                                                                                |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `besales_followup_step_message_set` | Sequence revision in `expectedVersion`; `expected_content` remains required                                            |
+| `besales_router_update`             | Routing token in `expectedVersion`                                                                                     |
+| `besales_routing_rule_upsert`       | Routing token in `expectedVersion`, for create and update                                                              |
+| `besales_behavior_update`           | Routing token in `expectedVersion`                                                                                     |
+| `besales_pipeline_settings_update`  | Routing token in `expectedVersion`                                                                                     |
+| `besales_platform_settings_update`  | Routing token in `expectedVersion`                                                                                     |
+| `besales_platform_pipeline_link`    | Routing token in `expectedVersion`                                                                                     |
+| `besales_platform_pipeline_unlink`  | Routing token in a strong `If-Match` header                                                                            |
+| `besales_variable_update`           | Variable UUID in `expectedVersion`, for CHANNEL and WORKSPACE                                                          |
+| `besales_variable_delete`           | Variable UUID in a strong `If-Match` header, for CHANNEL and WORKSPACE                                                 |
+| `besales_agent_update`              | Settings UUID in `expectedVersion`; optional `expected_routing_version` is sent separately as `expectedRoutingVersion` |
+| `besales_agent_facts_set`           | Facts UUID in `expectedVersion`, independent of settings and Routing                                                   |
+
+The original required arguments, deletion confirmations, null resets and false
+values retain their meaning. `If-Match` and the idempotency key are independent;
+the HTTP client quotes the original version without substituting a newly read
+token. The bridge does not expose arbitrary HTTP headers to tool arguments.
+
+After a 409, preserve the person's input, read the current state for comparison
+and wait for an explicit human decision. Do not automatically repeat the old
+change using a new version or new `expected_content`. Conflict instructions are
+available in en, ru, es, id and uz.
+
+`src/schemas/mcp-tools.json` is the input registry. The transport regression suite
+executes the real Zod schemas, request builders, dispatcher and HTTP client with
+only the network transport replaced. The API route snapshot must be republished
+from the committed bridge with the project's `publish:mcp-registry` command;
+its completeness baseline remains the shipped ref.

package/docs/failure-semantics.md

@@ -9,13 +9,13 @@
 в базу или постановки задачи в очередь. Для читающего вызова это не важно — повторить его
 ничего не стоит. Для меняющего важно всё:
 
-| Операция | Что делает повтор после неизвестного исхода |
-|---|---|
-| создание канала, агента, переменной | второй экземпляр, который никто не заказывал |
-| перевыпуск ключа партнёра | отзывает ключ, который партнёр только что получил |
-| импорт и запуск волны | отправляет сообщения людям второй раз |
-| раскатка правки промптов | применяет правки к уже пропатченному тексту |
-| всё, что тратит модель или квоту | платит второй раз |
+| Операция                            | Что делает повтор после неизвестного исхода       |
+| ----------------------------------- | ------------------------------------------------- |
+| создание канала, агента, переменной | второй экземпляр, который никто не заказывал      |
+| перевыпуск ключа партнёра           | отзывает ключ, который партнёр только что получил |
+| импорт и запуск волны               | отправляет сообщения людям второй раз             |
+| раскатка правки промптов            | применяет правки к уже пропатченному тексту       |
+| всё, что тратит модель или квоту    | платит второй раз                                 |
 
 ## Как это выражено
 
@@ -26,8 +26,16 @@
 ⚠️ **Идемпотентность объявляется явно, умолчание — худшее.** Правило «все `*_upsert`
 идемпотентны» неверно: без идентификатора они уходят в создание.
 
-Что НЕ считается неоднозначным: 4xx (сервер отверг запрос, не выполнив его), 429 (вызов
-отклонён лимитом), 401/403 (не пропущен вовсе). Там прежние тексты сохранены.
+Для обычных 4xx сервер отверг текущий запрос. Но отказ приёма результата длинной операции не доказывает, что прежняя работа не оплачена. Мост сначала читает известную операцию промптового семейства через `/llm-operations/:operationId`. Только при COMPLETED с живым результатом он повторяет тот же submit: сервер сверяет тело и возвращает сохранённый успех без исполнения. Другое тело получает 409; незавершённая, скрытая, отредактированная строка или недоступное чтение не повторяют submit.
+
+На 410 платного инструмента (`sideEffect=spend` или объявлен `restartToolName`) текст предупреждает о возможной оплате без сохранённого результата и отдельной цене нового запуска. Подсказка требует сообщить человеку и дождаться его решения; новое задание мост не создаёт. Семейства, которым промптовое чтение недоступно, получают это предупреждение без запроса чужого семейства.
+
+На 410 бесплатного инструмента мост сохраняет причину из ответа API, например истечение срока черновика, и предлагает продолжить по указанию ответа. Если причины нет, даёт нейтральное сообщение о недоступной ссылке, токене или предварительном просмотре. Предупреждения об оплате в этой ветке нет.
+
+409 при сохранении настроек с исходной версией требует сохранить ввод и дождаться
+явного решения человека после сравнения со свежим снимком. Мост не подменяет версию
+и не повторяет прежнюю правку автоматически. Поля всех таких инструментов и
+независимые версии настроек, фактов и Routing описаны в [протоколе версий](edit-versions.md).
 
 ## Чем свериться — выводится, а не перечисляется
 

package/docs/help-navigation.md

@@ -1,48 +1,21 @@
 # Навигация по справке Besales MCP
 
-## Зачем нужен tool-мост
+Некоторые MCP-хосты показывают модели tools, но не передают resources. Поэтому справка доступна
+двумя равноправными путями: по URI `besales://...` и через `besales_help_search` /
+`besales_help_get`, которые читают те же файлы пакета.
 
-Некоторые MCP-хосты показывают модели tools, но не передают список resources или не предлагают
-прочитать resource автоматически. Поэтому справка доступна двумя равноправными путями:
+`besales_help_search({query})` принимает обычную русскую или английскую формулировку. Синонимы
+связывают «дожим» с follow-up, «волна» с broadcast, «бот молчит» с silence/handoff. Ответ отдельно
+возвращает операции (`operations`) и документы (`results`); у операции есть `score` и `matchedBy`
+для совпадения по имени или пользовательскому намерению.
 
-- MCP resource по URI `besales://...`;
-- `besales_help_search` и `besales_help_get`, которые читают те же файлы пакета.
+Каждый активный инструмент получает короткую русскую формулировку намерения в описании из
+`tools/list`. Английская часть сохраняется для совместимости и поиска. Поэтому создание агента,
+изменение маршрутизации, запуск GetCourse-волны и финализация промпта находятся обычным русским
+запросом без знания технического имени.
 
-В ответах tool-моста есть `version`, `source` и `complete`. Это позволяет отличить актуальную
-справку пакета от пересказа модели и понять, был ли получен весь документ или один раздел.
+`besales_help_get({uri})` возвращает индекс. Параметр `section` отдаёт один раздел, `full=true` —
+весь документ. Ответы содержат version/source/complete; неоднозначный раздел не выбирается молча.
 
-## Поиск
-
-`besales_help_search({query})` принимает обычную русскую или английскую формулировку. Встроенные
-синонимы связывают лексику пользователя и продукта: «дожим» с follow-up, «волна» с broadcast,
-«бот молчит» с silence/handoff. Ответ разделяет найденные операции (`operations`) и документы
-(`results`). Для операции также возвращаются `score` и `matchedBy`: совпадение по имени или по
-пользовательскому намерению.
-
-Все активные инструменты получают короткую русскую формулировку намерения в описании, которое
-публикуется через `tools/list`. Английская часть сохраняется для существующих клиентов и поиска.
-Так модель может найти создание агента, изменение маршрутизации, запуск GetCourse-волны или
-финализацию промпта по обычному русскому запросу без знания технического имени инструмента.
-
-Поиск не вызывает API и не читает данные workspace. Если результатов нет, нужно уточнить объект
-или цель, а не угадывать имя инструмента.
-
-## Точечное и полное чтение
-
-`besales_help_get({uri})` возвращает индекс заголовков. Затем можно запросить один раздел через
-`section` или весь документ через `full=true`. Неоднозначный фрагмент заголовка возвращает список
-кандидатов; отсутствующий раздел возвращает `found=false`.
-
-Полная версия остаётся доступной, но для небольшой операции лучше читать один релевантный раздел.
-Содержимое resource и tool-ответа берётся из одного файла, поэтому две копии документа не
-расходятся.
-
-## Проверка
-
-- `src/tools/definitions/help.spec.ts` проверяет паритет русских и английских намерений, индекс,
-  раздел и полное чтение.
-- `src/tools/description-localization.spec.ts` не допускает активный инструмент без русской
-  формулировки в опубликованном описании.
-- `src/resources/registry.spec.ts` проверяет ссылки на реальные инструменты во всех resources и
-  коротких server instructions.
-- `src/server.spec.ts` проверяет публикацию server instructions через MCP initialize.
+Проверки: `src/tools/definitions/help.spec.ts`, `src/tools/description-localization.spec.ts`,
+`src/resources/registry.spec.ts` и `src/server.spec.ts`.