@besales/mcp 0.48.0 → 1.0.0-beta.4

package/docs/host-compatibility-matrix.md

@@ -1,104 +1,81 @@
 # Матрица хостов, версий и установки
 
-Снимок: 2026-09-11. Это проверяемая граница текущего hardening, а не обещание для любого
-MCP-клиента.
+Снимок хостов: 2026-09-11. Снимок протокола самого пакета: 2026-10-19. Это проверяемая граница,
+а не обещание для любого MCP-клиента. Версии хостов перепроверяются перед каждым выпуском
+следующей мажорной версии пакета.
 
-## Линии продукта
+## Линия продукта
 
-| Линия | MCP | API | Источник API-контракта | Tool schema | Transport |
-|---|---|---|---|---|---|
-| main | `be-sales/mcp`, `codex/mcp-hardening-main-20260910`, `0.46.0` | `be-sales/back-main`, `codex/mcp-hardening-api-main-20260910`, `1.0.1` | loose `animaly/docs/specs/v2/contracts/openapi-besales-api.yaml` → `src/types/api-contract.gen.ts` | tracked `besales-mcp/src/schemas/mcp-tools.json`; build копирует его в dist | local stdio |
-| v2 beta | тот же GitHub repo, отдельная ветка `codex/mcp-hardening-v2-20260910`, `1.0.0-beta.1` | `be-sales/besales-api`, `codex/mcp-hardening-api-v2-20260910`, `0.0.1` | `besales-api/contracts/openapi-besales-api.yaml` → generated types | локальный `src/schemas/mcp-tools.json` + route export | local stdio |
+| MCP | API | Источник API-контракта | Tool schema | Transport |
+|---|---|---|---|---|
+| `be-sales/mcp`, `@besales/mcp` | `be-sales/besales-api`, маршруты `/api/v2` | `besales-api/contracts/openapi-besales-api.yaml` → `src/types/api-contract.gen.ts` (`yarn types:gen:api`) | tracked `src/schemas/mcp-tools.json`; build копирует его в dist | local stdio |
 
-Main и v2 не взаимозаменяемы по совпадению имени файла. Изменение переносится только после
-сверки route, DTO, scope, ответа и теста своей пары.
+Прежняя линия пакета (`0.x`, работала с прежней системой) этой матрицей не описывается: у неё свой
+набор инструментов и прав, и изменения между линиями не переносятся по совпадению имени файла —
+только после сверки route, DTO, scope, ответа и теста своей пары. Эталон прежней линии для таких
+сверок и порядок замены линии — [RELEASING.md](../RELEASING.md).
 
-Общий loose `docs/specs/v2/contracts/mcp-tools.json` является целью v2 registry publish и больше
-не копируется внутрь main. Это устраняет перезапись канона одной линии контрактом другой; main
-проверяет собственный tracked schema, v2 публикует свой schema в явно выбранные targets.
-
-## Поддерживаемые хосты этой итерации
+## Поддерживаемые хосты
 
 | Хост | Проверенная версия | Фактическое поведение | Статус |
 |---|---|---|---|
-| MCP SDK / Inspector | SDK из lockfile, raw stdio | полный initialize; main: 253 tools / 38 resources / 5 prompts, v2: 213 / 38 / 5; schema validation до HTTP | блокирующий protocol gate |
+| MCP SDK / Inspector | SDK из lockfile, raw stdio | полный initialize; schema validation до HTTP | блокирующий protocol gate |
 | Codex CLI / App | `codex-cli 0.153.4` | один сервер `besales`; tools могут грузиться отложенно; resources модели не гарантированы, поэтому есть `besales_help_*` | поддержан |
-| Claude Code | `2.1.220` | stdio подключён; видит tools/resources/prompts; server instructions режет **4123 → 2048 символов** | поддержан с полезным префиксом и help-tools |
-| Claude Desktop | app `1.49585.0` | local stdio; два намеренно разных подключения `besales-tg` и `besales-ksamata`, каждое прибито к своему workspace | поддержан; ручной UI smoke после установки |
+| Claude Code | `2.1.220` | stdio подключён; видит tools/resources/prompts; server instructions режет до **2048 символов** | поддержан с полезным префиксом и help-tools |
+| Claude Desktop | app `1.49585.0` | local stdio; допускается несколько намеренно разных подключений, каждое прибито к своему workspace | поддержан; ручной UI smoke после установки |
 
 Новый неизвестный хост не становится блокирующим автоматически. Для него сначала повторяются
 raw initialize/list/read/call и модельная оценка.
 
-## Протокольное доказательство main
-
-Артефакт: `docs/evidence/2026-09-11-main-wire-protocol.json`.
+## Протокольное доказательство
 
-- initialize: `@besales/mcp 0.46.0`, instructions 4123 символа / 6532 UTF-8 байта;
-- capabilities: tools, resources, prompts;
-- tools/list: 253 уникальных имени, 418380 байт;
-- resources/list: 38; каждый URI реально прочитан и снабжён SHA-256;
-- prompts/list: 5;
-- пустой `besales_agent_create` отклонён MCP кодом `-32602` до HTTP: отсутствуют
-  `platform_id`, `name`, а `model_lane` не входит в `CHEAP|STANDARD|DEEP`;
-- wire schema сохраняет required, UUID format, enums, вложенные объекты и
-  `const: true` + `type: boolean`.
+Артефакт: `docs/evidence/2026-10-19-v2-wire-protocol.json` (предыдущий снимок —
+`2026-09-11-v2-wire-protocol.json`). Повторение:
 
-Скрипт повторения: `yarn build && yarn host:probe bin/besales-mcp.js <output.json>`.
+```bash
+yarn build && yarn host:probe bin/besales-mcp.js <output.json>
+```
 
-## Протокольное доказательство v2 beta
+Снимок 2026-10-19, пакет `1.0.0-beta.1`, сборка ветки `integ/bridge-w8` на коммите `84bcb97`:
 
-Артефакт в v2 checkout: `docs/evidence/2026-09-11-v2-wire-protocol.json`.
+- capabilities: tools, resources, prompts;
+- initialize: instructions 4633 символа / 7474 UTF-8 байта;
+- tools/list: 292 уникальных имени, 611740 байт; resources/list: 39; prompts/list: 5;
+- каждый resource реально прочитан и снабжён SHA-256;
+- пустой `besales_agent_create` отклонён MCP кодом `-32602` до HTTP — обязательными полями.
 
-- initialize: `@besales/mcp 1.0.0-beta.1`, instructions 4122 символа / 6538 UTF-8 байт;
-- tools/list: 213 уникальных имён, 322105 байт; resources/list: 38; prompts/list: 5;
-- все resources прочитаны, representative schemas сохранены, пустой `besales_agent_create`
-  отклонён кодом `-32602` до API теми же обязательными полями;
-- снимок собран из v2 MCP `912a70a`; API-зависимые main tools в него не копировались.
+Числа дрейфуют с каждым инструментом; актуальные получают повтором скрипта. Размер `tools/list`
+стоит знать заранее: хост, который не откладывает загрузку инструментов, кладёт его в контекст
+модели целиком.
 
 ## Что видит модель
 
-У установленной до hardening main-версии Codex App было 215 активных tools. Старый сервер
-добавлял полный текст инструкций в описание каждого tool: 22385 символов у одного описания,
-4747836 символов суммарно. Это подтверждённый дефект версии, а не лимит MCP.
-
-Новая версия передаёт инструкции один раз через initialize. В первых 2048 символах, которые
-оставляет проверенный Claude Code, находятся:
-
-1. `besales_workspace_current` и выбор компании по названию;
-2. overview → точечный platform context;
-3. `besales_help_search` → `besales_help_get`;
-4. запрет одинакового повторного read и конкретный следующий шаг;
-5. запрет секретов в чате и начало правила подтверждений.
-
-Глубокие правила после этой границы остаются доступны через тот же registry ресурсов и
-`besales_help_search` / `besales_help_get`; модель не зависит от UI resources конкретного хоста.
-
-Повторная проверка model-eval 2026-09-11 отозвала прежний сравнительный PASS:
-все 15 baseline-прогонов были заблокированы политикой approvals хоста до выполнения fixture.
-Сопоставимого baseline нет; улучшение времени, токенов или успешности не доказано.
-Current отдельно дал 14/15 успешных маршрутов и чтение справки в 12/15 на пяти fixture-сценариях
-(`gpt-5.6-luna`, reasoning `low`, три повтора). Это не проверка production API или всех workflows.
-Scorer пересчитывает метрики из исходных calls/events и учитывает только успешные ответы;
-approval-blocked read не считается мутацией. UPD-048 открыт до сопоставимой серии.
-Raw JSONL сохранён в `docs/evidence/model-eval-2026-09-11/`.
-
-Claude Code debug подтвердил stdio connection и capabilities tools/resources/prompts, а также
-точный лимит instructions 2048. Модельный ответ не получен: аккаунт вернул 429 weekly limit до
-первого token. Это ограничение хоста/аккаунта, не ошибка MCP; raw protocol и command discovery
-остаются валидны. В Claude Code prompts появляются как
-`/mcp__besales__besales_setup_agent` и аналогичные команды. Обычный текстовый запрос остаётся
-основным и полностью эквивалентным входом.
+Инструкции передаются один раз через initialize. Claude Code отдаёт модели только первые 2048
+символов, поэтому порядок текста значим. В эту границу сейчас входят:
 
-## Подключения и дубли
+1. правило подтверждения перед правкой (одно сообщение со списком всех правок и один вопрос), в
+   него же сведены `explicit_confirmation`, запрет автоповтора после timeout/5xx и отчёт после
+   правок;
+2. запрет просить токены, пароли и API keys в чате;
+3. пункты 1–3 раздела «Как начать»: `besales_workspace_current` и выбор компании по названию,
+   продолжение задачи, `besales_workspace_navigate`.
+
+Пункт 4 («Как начать»: `besales_help_search` → `besales_help_get`) границей обрезается, а
+запрет повторного чтения, правила полноты и маршрут настройки лежат за ней целиком. Они остаются
+доступны через тот же реестр ресурсов и `besales_help_search` / `besales_help_get`; модель не
+зависит от UI resources конкретного хоста. Что именно удерживается внутри границы, проверяет
+`src/server.spec.ts`: правило подтверждения и запрет секретов обязаны лежать в первых 2048
+символах, и перенос любого из них ниже границы роняет тест.
 
-Наблюдавшиеся «3 сервера / 642 записи» не являются тремя случайными копиями в одном каталоге:
+Модельной оценки поведения (сравнение версий инструкций на сценариях) для этой линии не
+проводилось.
 
-- Codex имеет один `besales`;
-- Claude Code имеет один `besales`;
-- Claude Desktop имеет два purpose-specific сервера для разных workspace.
+## Подключения и дубли
 
-Удалять их автоматически нельзя: это уничтожило бы выбор компании. Случайным дублем считается
-только повтор одного executable, API URL и workspace pin внутри одного host. Миграция:
+Дублем считается только повтор одного executable, API URL и workspace pin внутри одного хоста.
+Несколько серверов, прибитых к разным компаниям, — штатная конфигурация (Claude Desktop часто
+держит по одному серверу на компанию), и автоматически их удалять нельзя: это уничтожило бы выбор
+компании. Миграция:
 
 1. оставить по одному имени на уникальную тройку executable/API/workspace;
 2. обновить executable на проверенный пакет;
@@ -107,23 +84,24 @@ Claude Code debug подтвердил stdio connection и capabilities tools/re
 
 Профиль `BESALES_MCP_TOOLSETS` уменьшает поверхность одного сервера и одинаково ограничивает
 list и call; help возвращает скрытые совпадения отдельно, не выдавая их за вызываемые. Профиль не
-заменяет workspace pin и не объединяет разные компании.
+заменяет workspace pin и не объединяет разные компании ([tool-surface.md](tool-surface.md)).
 
 ## Scopes
 
-| Линия | Запрашивает MCP | Поддерживает API | Фактически выдаёт |
-|---|---|---|---|
-| main | `mcp:* mcp:platform-setup mcp:funnel-test read:campaigns launch:campaigns read:contacts write:operators` | тот же ratchet-набор | consent-набор с учётом прав пользователя; exchange возвращает `scopes` и `dropped_scopes` |
-| v2 beta | `mcp:* mcp:platform-setup read:contacts` | та же тройка; `read:platform-setup` входит в composite read | consent выдаёт только поддержанный v2-набор |
+Пакет запрашивает при подключении набор `MCP_OAUTH_SCOPES` (`src/auth/oauth-client.ts`): `mcp:*`,
+`mcp:platform-setup`, `mcp:funnel-test`, `read:campaigns`, `launch:campaigns`, `read:contacts`,
+`write:operators`. Фактически выдаётся пересечение с правами пользователя в компании; обмен
+возвращает `scopes` и `dropped_scopes`, а `connect` предупреждает о потерянных и невыданных
+правах.
 
 `besales_workspace_current.effective_scopes` берётся из конкретного выбранного credential.
 Union других ключей workspace не используется. 403 сохраняет названный API недостающий scope;
-reconnect добавляет права и не должен сужать прежние. Main и beta не копируют scope-set друг
-друга.
+reconnect добавляет права и не должен сужать прежние.
 
 ## Установка, обновление, отзыв
 
-Поддержанный пользовательский путь сейчас — local stdio и browser OAuth:
+Поддержанный пользовательский путь сейчас — local stdio и browser OAuth
+([connect.ru.md](connect.ru.md)):
 
 1. host запускает `npx -y @besales/mcp@<проверенная-версия>` либо pinned локальный executable;
 2. `besales-mcp connect` открывает browser consent; секрет в чат не копируется;
@@ -132,21 +110,22 @@ reconnect добавляет права и не должен сужать пре
 5. reconnect нужен для протухшего credential или новых scopes, а не для неоднозначного выбора;
 6. отзыв выполняется в настройках подключения, затем проверяется 401 именно этого workspace.
 
-Keytar остаётся частью local distribution и хранит ключи в системном credential store. Remote
-HTTP/OAuth не вводится в этом инкременте: для него нет ратифицированной модели размещения,
-tenant routing и миграции локальных ключей. Возвращаться к нему следует, когда появится
-server-side host и отдельный threat model. Перенос аккаунта выполняется новым browser connect;
-credential store не копируется между машинами.
+Keytar (`keytar`) остаётся частью local distribution и хранит ключи в системном credential store.
+Remote HTTP/OAuth не вводится: для него нет ратифицированной модели размещения, tenant routing и
+миграции локальных ключей. Возвращаться к нему следует, когда появится server-side host и
+отдельный threat model. Перенос аккаунта выполняется новым browser connect; credential store не
+копируется между машинами.
 
 ## Выпуск
 
-- Аддитивные tools/resources/prompts совместимы в minor main и beta build.
+- Аддитивные tools/resources/prompts совместимы в minor.
 - Новые обязательные поля, default limits и форма результата требуют отдельного rollout.
 - `BESALES_MCP_RESULT_ENVELOPE=on` включает одинаковые text/structuredContent и outputSchema;
-  default остаётся off один совместимый релиз.
-- main и `1.0.0-beta.1` не публикуются на один dist-tag.
-- Публикация и деплой в этот документ не входят. После публикации обязателен smoke реально
-  установленного пакета после полного restart host; локальный worktree smoke его не заменяет.
+  по умолчанию выключен один совместимый релиз (README).
+- Версии разных линий не публикуются на один dist-tag.
+- Порядок выпуска и откат — [RELEASING.md](../RELEASING.md). После публикации обязателен smoke
+  реально установленного пакета после полного restart host; локальный worktree smoke его не
+  заменяет.
 
 Официальное отображение prompts в Claude Code: MCP prompt становится командой
 `/mcp__<server>__<prompt>`; resources доступны через `@server:uri`. Источник:

package/docs/host-setup.md

@@ -1,20 +1,21 @@
 # MCP Host Setup Runbook
 
 This runbook covers local development setup for `@besales/mcp` in the MCP hosts
-we support during v1.5 validation: MCP Inspector, Claude Desktop, Claude Code,
-and Codex CLI.
+we support: MCP Inspector, Claude Desktop, Claude Code, and Codex CLI. Hosts and
+versions that were actually checked are listed in
+[host-compatibility-matrix.md](host-compatibility-matrix.md).
 
 ## Scope
 
-`besales-mcp` is a thin MCP server for Animaly v1.5. It never calls
-`prompt-services` directly. Every tool call goes through `ai-aniomaly`
-`/api/v2/*`, and `ai-aniomaly` decides whether the operation is internal or
+`besales-mcp` is a thin MCP server for Besales. It never calls
+`prompt-services` directly. Every tool call goes through `besales-api`
+`/api/v2/*`, and `besales-api` decides whether the operation is internal or
 external.
 
 External execution is host-neutral:
 
 1. The host calls a `*_get_instructions` tool.
-2. `ai-aniomaly` creates an operation request and returns stages.
+2. `besales-api` creates an operation request and returns stages.
 3. The host/model executes the stages locally.
 4. The host calls the matching `*_submit` tool.
 
@@ -22,34 +23,33 @@ Claude Desktop, Claude Code, and Codex CLI all use this same two-step MCP flow.
 
 ## Local Preconditions
 
-Run these from `/Users/peresvets/apps/animaly/besales-mcp`.
+Run these from the `besales-mcp` directory.
 
 ```bash
 yarn install
 yarn build
 ```
 
-For live local API testing, `ai-aniomaly` must be running on port `3000` and the
-v1.5 migrations must already be applied:
+For live local API testing, `besales-api` must be running (default port `3000`)
+and its migrations must already be applied:
 
 ```bash
 curl -fsS http://localhost:3000/health
-curl -fsS http://localhost:3000/.well-known/jwks.json
 ```
 
 Use this base URL for local host configs:
 
 ```bash
 export BESALES_API_BASE_URL=http://localhost:3000/api/v2
-export BESALES_OAUTH_AUTHORIZE_URL=http://localhost:5173/settings/mcp/consent
+export BESALES_OAUTH_AUTHORIZE_URL=http://localhost:3000/api/v2/auth/mcp-connect/start
 ```
 
 `prompt-services` is not a host precondition. Hosts talk only to `besales-mcp`,
-and `besales-mcp` talks only to `ai-aniomaly`.
+and `besales-mcp` talks only to `besales-api`.
 
 For production users, omit both variables. The package defaults to
 `BESALES_API_BASE_URL=https://core.besales.ai/api/v2` and
-`BESALES_OAUTH_AUTHORIZE_URL=https://app.besales.ai/settings/mcp/consent`.
+`BESALES_OAUTH_AUTHORIZE_URL=https://core.besales.ai/api/v2/auth/mcp-connect/start`.
 
 ## Credentials
 
@@ -57,14 +57,15 @@ Live tool calls require an MCP API key stored in the local macOS keychain:
 
 ```bash
 BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
-BESALES_OAUTH_AUTHORIZE_URL=http://localhost:5173/settings/mcp/consent \
+BESALES_OAUTH_AUTHORIZE_URL=http://localhost:3000/api/v2/auth/mcp-connect/start \
   node bin/besales-mcp.js connect
 BESALES_API_BASE_URL=http://localhost:3000/api/v2 node bin/besales-mcp.js status
 ```
 
 The `connect` command opens the browser and completes
-the frontend consent bridge, which forwards to backend
-`/api/v2/auth/mcp-connect` through the loopback callback. `disconnect` removes the
+the connect page served by the backend (`/api/v2/auth/mcp-connect/start`: sign in, choose
+the workspace, approve the whole permission set) and receives the one-time code through the
+loopback callback. `disconnect` removes the
 active workspace (add an id to remove one, or `--all` to clear every workspace):
 
 ```bash
@@ -115,7 +116,7 @@ state.
 
 ```bash
 BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
-BESALES_OAUTH_AUTHORIZE_URL=http://localhost:5173/settings/mcp/consent \
+BESALES_OAUTH_AUTHORIZE_URL=http://localhost:3000/api/v2/auth/mcp-connect/start \
   yarn dlx @modelcontextprotocol/inspector node bin/besales-mcp.js
 ```
 
@@ -137,11 +138,10 @@ BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
 
 Expected:
 
-- 248 tools are listed.
-- 38 resources are listed.
-- 5 optional task prompts are listed.
+- The tool, resource and prompt counts match the current wire snapshot
+  (`docs/evidence/`, produced by `yarn host:probe`).
 - `besales://concepts/external-execution` opens.
-- A direct tool, for example `besales_icp_create`, reaches `ai-aniomaly`.
+- A direct tool, for example `besales_icp_create`, reaches `besales-api`.
 - An external pair returns instructions and accepts submit.
 
 For mock-only protocol checks, point Inspector at `http://127.0.0.1:3100/api/v2`
@@ -164,10 +164,10 @@ timestamped backup:
   "mcpServers": {
     "besales": {
       "command": "/absolute/path/to/node",
-      "args": ["/Users/peresvets/apps/animaly/besales-mcp/bin/besales-mcp.js"],
+      "args": ["/absolute/path/to/besales-mcp/bin/besales-mcp.js"],
       "env": {
         "BESALES_API_BASE_URL": "http://localhost:3000/api/v2",
-        "BESALES_OAUTH_AUTHORIZE_URL": "http://localhost:5173/settings/mcp/consent"
+        "BESALES_OAUTH_AUTHORIZE_URL": "http://localhost:3000/api/v2/auth/mcp-connect/start"
       }
     }
   }
@@ -192,8 +192,8 @@ If `claude` is on `PATH`, add the server at user scope:
 ```bash
 claude mcp add --scope user \
   -e BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
-  -e BESALES_OAUTH_AUTHORIZE_URL=http://localhost:5173/settings/mcp/consent \
-  -- besales node /Users/peresvets/apps/animaly/besales-mcp/bin/besales-mcp.js
+  -e BESALES_OAUTH_AUTHORIZE_URL=http://localhost:3000/api/v2/auth/mcp-connect/start \
+  -- besales node /absolute/path/to/besales-mcp/bin/besales-mcp.js
 ```
 
 If the app-managed binary is not on `PATH`, use the absolute Claude Code binary
@@ -205,7 +205,7 @@ Verify:
 claude mcp list
 ```
 
-Start a fresh Claude Code session from `/Users/peresvets/apps/animaly`, run
+Start a fresh Claude Code session from any project directory, run
 `/mcp`, and check that `besales` is connected. Then run the same direct tool and
 external-pair smoke as Claude Desktop.
 
@@ -216,8 +216,8 @@ Codex CLI manages stdio MCP servers through `codex mcp`.
 ```bash
 codex mcp add besales \
   --env BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
-  --env BESALES_OAUTH_AUTHORIZE_URL=http://localhost:5173/settings/mcp/consent \
-  -- node /Users/peresvets/apps/animaly/besales-mcp/bin/besales-mcp.js
+  --env BESALES_OAUTH_AUTHORIZE_URL=http://localhost:3000/api/v2/auth/mcp-connect/start \
+  -- node /absolute/path/to/besales-mcp/bin/besales-mcp.js
 ```
 
 Equivalent `~/.codex/config.toml` shape:
@@ -225,11 +225,11 @@ Equivalent `~/.codex/config.toml` shape:
 ```toml
 [mcp_servers.besales]
 command = "node"
-args = ["/Users/peresvets/apps/animaly/besales-mcp/bin/besales-mcp.js"]
+args = ["/absolute/path/to/besales-mcp/bin/besales-mcp.js"]
 
 [mcp_servers.besales.env]
 BESALES_API_BASE_URL = "http://localhost:3000/api/v2"
-BESALES_OAUTH_AUTHORIZE_URL = "http://localhost:5173/settings/mcp/consent"
+BESALES_OAUTH_AUTHORIZE_URL = "http://localhost:3000/api/v2/auth/mcp-connect/start"
 ```
 
 Verify:
@@ -244,8 +244,6 @@ are present, then run:
 
 1. One direct tool (`besales_icp_create`).
 2. One external pair (`*_get_instructions` then matching `*_submit`).
-3. A natural-language help request through `besales_help_search`, followed by one section through
-   `besales_help_get`. This check is required when the host does not expose resources to the model.
 
 For the ICP analysis pair, `besales_icp_analysis_submit` personas must include
 `segment_id`. Use either an existing ICP segment id or the `id` of a segment in
@@ -259,7 +257,7 @@ session may need an app/session restart before new tools appear.
 Codex App can defer MCP tool schemas until the model searches for them. This is
 host behavior, not a `besales-mcp` server problem: `codex mcp list/get besales`
 and MCP Inspector `tools/list` are still the source checks for whether the
-server is installed and exposing all 248 tools.
+server is installed and exposing the full tool list.
 
 User-facing prompts must stay natural. Users should ask for the business action,
 for example:
@@ -280,12 +278,12 @@ Use this matrix for local validation before staging/prod checks.
 
 | Host | Config check | Protocol check | Direct tool | External pair |
 |---|---|---|---|---|
-| MCP Inspector | command launches | 248 tools / 38 resources / 5 prompts | `besales_icp_create` | instructions -> submit |
+| MCP Inspector | command launches | counts match the wire snapshot | `besales_icp_create` | instructions -> submit |
 | Claude Desktop | config JSON has `besales` | server connected | `besales_icp_create` | instructions -> submit |
 | Claude Code | `claude mcp list` has `besales` | `/mcp` connected | `besales_icp_create` | instructions -> submit |
 | Codex CLI | `codex mcp list` has `besales` | new session sees tools | `besales_icp_create` | instructions -> submit |
 
 Do not mark the ROADMAP manual E2E acceptance from mock-only checks. Mock mode
 only verifies host wiring and MCP protocol shape. ROADMAP acceptance requires a
-live `ai-aniomaly` backend, real stored MCP credentials, and successful direct
+live `besales-api` backend, real stored MCP credentials, and successful direct
 plus external tool calls.

package/docs/invariants/public-api-and-contracts.md

@@ -0,0 +1,16 @@
+# Перечни входного контракта моста
+
+`DELIBERATE` требует причины словами и ссылки `decision:<task>:<id>`. ACTIVE-решение содержит тот же точный ключ и собственную непустую причину в каталоге API `docs/contract-ledger/cledg-decisions.md`. Одной строки со ссылкой недостаточно. Путь каталога задаётся `BESALES_LAG_DECISIONS_FILE`, по умолчанию читается соседнее API-дерево. Каталог — обязательный вход производителя наряду с планами; отсутствие, отмена решения или изменение ключа роняют сверку. API независимо проверяет тот же договор, включая внутренние расширения входа.
+
+Прежние настройки школы принимаются атомарным серверным переводчиком: пустой домен сохраняет идентичность школы, список отделов считается копией живого справочника с пояснением в ответе, номера образцов пишутся в выбранное CRM-подключение той же школы с отдельной проверкой прав. Прежний предпросмотр принимает рассылку и разовый текст вместе; текст переопределяет только предпросмотр. Выбор транспортов шага сохраняет рабочую отгруженную форму `explicit`; в реактивационной цепочке сочетание `all` со списком отвергалось уже отгруженным фильтром.
+
+У отгруженного фильтра проверка доставки запускалась только для реактивационной цепочки: прочие типы могли пропустить список рядом с `contact`/`all`, хотя режим его не исполняет, а сервер v2 отвергает. Такой отказ моста v2 объявляется отдельно от сохранённого приёма `explicit`, без переключения режима или игнорирования списка. Объект вместо списка ключевых слов Instagram тоже адресно отвергается: обработчик читает массив, произвольный объект не определяет отбор комментариев. Список строк и `null` сохраняются. Наблюдённый отказ и различие JSON-типа имеют отдельные точные ключи реестра; одна запись не подменяет другую.
+
+Все значения enum/const общих путей опубликованного JSON и фактического фильтра zod равны после разворачивания refs и всех альтернатив, включая отдельные скалярные и массивные ветви. null не является расхождением. Односторонний перечень допускается только в поимённом списке с причиной; отказ конвертера и число сравнений проверяются отдельно.
+
+Это не обещание полноты всех необязательных полей в обратном направлении zod→JSON и не доказательство живой совместимости сервера. Маршруты и генерируемые типы проверяются отдельными генераторами и контрактными наборами.
+Пределы `minimum`/`maximum`/`maxItems` защищены только отдельными тестами соответствующих инструментов, например `model-comparison.spec.ts`.
+
+Каждая строка отставания имеет владельцем открытую задачу рабочего плана либо `DELIBERATE` с той же тяжестью. Выгрузка и тест `scripts/lag-open-task-owners.spec.mjs` требуют `BESALES_WORKING_PLAN` и `BESALES_CLOSED_PLAN`: абсолютные пути к актуальным рабочему и закрытому планам. Номер проверяется по заголовкам, задача в закрытом плане не проходит даже при наличии в рабочем. В CI оба файла предоставляются отдельным checkout документации; отсутствие любого файла — ошибка проверки. Список задач внутри пакета не заменяет эти входы.
+
+Прежний `audio_source_type=xlsx_upload` с `audio_source_config: {storedFileId, crmConnectionId, sheets?}` переводится в тот же типизированный источник, что новая форма `source`. Остальные прежние источники переводятся по именованным псевдонимам. Обе формы требуют `request_key`, явное `gdpr_confirmed=true` и обязательное обезличивание. Неизвестные поля конфигурации, смешение двух форм, неверные идентификаторы и отсутствие согласия отвергаются до запроса; секреты и внешние адреса в конфигурацию не принимаются.

package/docs/legacy-action-settings.md

@@ -0,0 +1,21 @@
+# Прежние настройки пересказа и поиска
+
+`besales_trigger_upsert` принимает настройки действий в прежнем конверте и передаёт их API целиком.
+У `SUMMARIZE_DIALOG` это `summarizeConfig` (также принимается `summarizeAction`): `targetType`,
+`targetName`, `instructions`, `historyLimit`, `maxCharacters`. Тип цели `USER_VARIABLE` выбирает
+текстовую переменную канала; глубина задаётся в сообщениях, предел длины — в кодовых единицах.
+API переводит поля в канонические настройки шага и исполняет их в ходе модели.
+Отказ от `PLATFORM_CONSTANT` действует до HTTP для обоих прежних конвертов
+и при имени действия в `type`, `stepType` или `actionType`; ошибка называет
+именно присланное поле цели. `USER_VARIABLE` передаётся без потерь.
+
+У `READ_NAMESPACES` передаётся `readNamespacesConfig`: `dataTypes`, `limit`, `minScore`.
+Типы выбирают источники знаний; число, отличное от 3, заменяет число профиля агента; заполненный
+порог (включая 0) заменяет векторный порог агента. Порог не фильтрует поиск по словам, вопросы-ответы
+со своим порогом и сырые таблицы. Пустой список типов либо все четыре означают поиск без фильтра типов.
+
+Семь прежних строк отставания `LIVE_422` сняты. В `legacyActionLag` остаётся только осознанный
+отказ `summarizeConfig.targetType#PLATFORM_CONSTANT`: пересказ одного человека нельзя сохранить
+в константу, общую всем собеседникам канала. API отвечает адресным отказом и предлагает выбрать
+переменную. Доставка остальных полей до тела запроса проверяется тестами схемы инструмента;
+снятие отставания — отдельным сторожем реестра.

package/docs/main-transfer-dependencies.md

@@ -0,0 +1,38 @@
+# Перенос возможностей прежней линии в v2
+
+Правило: возможность прежней линии переносится в v2 только вместе с рабочим доменом в
+`besales-api`. Зарегистрированный инструмент без бэкенда — это неработающий инструмент, а не
+перенос. Наличие похожего route или общего scope в большом OpenAPI не заменяет доменную проверку:
+CRM-операторы не являются workspace-операторами, телефонные actions не являются управлением
+телефонией, а broadcast totals не заменяют входящую аналитику.
+
+## Состояние на 2026-10-19
+
+Первая редакция документа (2026-09-11) перечисляла семь возможностей, которых в v2 ещё не было ни в
+API, ни в мосте. Все они построены: у каждой есть инструмент в мосте и контроллер в `besales-api`.
+
+| Возможность | Инструмент моста | Контроллер `besales-api` |
+|---|---|---|
+| входящая аналитика | `besales_inbound_analytics_get` | `control/inbound-analytics` |
+| аналитика воронки | `besales_funnel_analytics_get` | `control/funnel-analytics` |
+| расход ИИ (ledger) | `besales_ai_costs_get` | `control/ai-costs` |
+| сохранённые отчёты | `besales_custom_report_list`, `_get`, `_run` | `control/custom-reports` |
+| эксплуатационная сводка | `besales_workspace_operational_overview` | `control/operational-overview` |
+| очередь операторов | `besales_workspace_operator_queue_list` | `control/operators` |
+| операторы и назначение | `besales_workspace_operator_list`, `_assignment_get`, `_assignment_set` | `control/operators` |
+
+Это проверка наличия, а не работоспособности: живая проверка против настоящих систем выполняется
+после окончания бэкенда отдельной сводной задачей. Поведенческие различия с прежней линией (где
+поле отвергается, где другой адрес) перечислены в реестре отставания
+`src/schemas/shipped-lag.json` с владельцем у каждой строки.
+
+## Порядок переноса новой возможности
+
+1. Реализовать и проверить домен в `besales-api`.
+2. Добавить точный scope в server constants, DTO, OpenAPI и consent. Новый scope добавляется в
+   конец набора и не вытесняет действующие права.
+3. Сгенерировать API-типы и route map во временный файл, проверить diff и только затем обновить
+   tracked contract v2.
+4. Добавить MCP definition, result contract, проверку исхода и документацию.
+5. Прогнать scope/route/registry parity и wire-protocol snapshot. До этого возможность остаётся
+   `missing API`, а не `partial` или скрытым инструментом.

package/docs/mcp2-parity.md

@@ -0,0 +1,50 @@
+# Продолжение холодного обращения и поиск начатых обращений
+
+`besales_getcourse_cold_welcome_preview` и `_start`
+принимают optional `continuation: true` только по `contacts`. Значения false/null/строки/числа,
+аудитория `created_after` и continuation на любом уровне batch отвергаются до HTTP.
+Режим выбирается по явной просьбе человека. Сначала preview с теми же флагом, файлом,
+текстом, сегментом, продуктом и каналами, затем подтверждение и start с `explicit_confirmation:true`.
+До start сохрани UUID `idempotency_key` вместе с подтверждёнными параметрами. Он идёт только
+в заголовок `Idempotency-Key`, не в body. Повтор того же намерения использует тот же ключ;
+новое подтверждённое намерение получает новый UUID. При неизвестном исходе сначала читай статус,
+не создавай новое намерение автоматически. Ключ optional для совместимости прежних вызовов;
+отсутствие ключа не генерирует его. Preview и batch этот новый аргумент не принимают.
+Preview продолжения требует источник текста; пустой выбранный текст, вариант без текста
+или сегмента отвергает API. Обычный preview без текста по-прежнему допустим.
+
+Отображения v2: `platform_id → channelId`, `channels → transports`,
+`explicit_confirmation → explicitConfirmation`, `contacts[].contact_id → getcourseUserId`.
+`alreadyWelcomed` — справка. Охват равен `totalContacts − narrowedOutByTransports`
+(прежнее имя `narrowedOutByChannels`), неизвестные каналы не вычитаются. Контрольный ответ
+100/40/20/10 даёт 80. В текущем v2 неизвестных каналов штатно 0; школа при отправке
+повторно не опрашивается. `touchClaimed` может быть больше нуля. Одинаковый текст тому же
+сегменту повторно не отправляется. Открытый разговор требует прежнюю нашу реплику;
+предохранители и проверка состояния человека сохраняются. Прогноз и постановка не означают доставку:
+итог читается в статусе задачи.
+
+`besales_contact_search` принимает optional строковый литерал `outreach: "true"`.
+Отсутствие не превращается в false. Запрос — существующий POST
+`/workspaces/{workspaceId}/contacts/search`, селекторы остаются в body. Это сохранённый
+факт допуска к отправке, а не подтверждение доставки; старая история может быть неполной.
+`outreachInitiatedAt` передаётся как ISO-момент либо null. Пагинация, neverTruncate,
+персональные данные и серверные права не меняются.
+
+Проверки: `src/tools/mcp2-parity.spec.ts` использует настоящий handler реестра и HTTP-клиент
+с записью запросов. Явный `PRMCP2_CAPTURE_PATH` экспортирует эти запросы и SHA-256 исходников
+в парную фикстуру API. `mcp2-dispatch-dto.contract.spec.ts` пропускает фикстуру через настоящие
+строгие DTO и production ValidationPipe, сравнивает входы preview/start.
+`mcp2-intent.wire.spec.ts` проводит подтверждённый start через реальный ApiClient до HTTP,
+проверяя ключ вне строгого DTO, повтор и отсутствие переноса ключа на следующий вызов.
+`src/tools/mcp2-api-dto.spec.ts` дополнительно вызывает production ValidationPipe прямо
+из HTTP-клиента настоящего handler, используя читающий загрузчик исходников соседнего API.
+`registry.spec.ts`
+проверяет совпадение опубликованного каталога и runtime-схем. Отрицательные контроли ловят
+потерю поля, ослабление literal-validator, смену POST и потерю даты в ответе.
+
+Общий ICP-контракт использует тот же читающий загрузчик DTO API: пути CommonJS и JSON-ресурсы
+разрешаются относительно каждого исходного модуля, корень чтения ограничен `src` API.
+Проверка исторического ledger читает точный коммит `shippedRegistry.commit` подписанного
+экспорта и сверяет весь каталог входных схем. Подвижная remote-ссылка не заменяет этот срез.
+Свежесть текущей отгрузки проверяет отдельный API-контур `mcp-routes-freshness`;
+после коммита подписанную общую выгрузку перевыпускает кресло.