@besales/mcp 0.1.0 → 0.11.1

package/dist/resources/registry.js

@@ -1,19 +1,41 @@
 import { readFile } from 'node:fs/promises';
 import { getResourceContracts } from '../tools/contracts.js';
-const conceptFilesByUri = {
-    'besales://concepts/icp': 'icp.md',
-    'besales://concepts/triggers': 'triggers.md',
-    'besales://concepts/sandbox': 'sandbox.md',
-    'besales://concepts/handoff': 'handoff.md',
-    'besales://concepts/external-execution': 'external-execution.md',
+// URI → относительный путь от `src/resources/` (включая подпапку).
+// concepts/* — справочники паттернов; workflows/* — orchestration-маршруты (v1.5 Increment 6a).
+const resourceFilesByUri = {
+    'besales://concepts/icp': 'concepts/icp.md',
+    'besales://concepts/triggers': 'concepts/triggers.md',
+    'besales://concepts/sandbox': 'concepts/sandbox.md',
+    'besales://concepts/handoff': 'concepts/handoff.md',
+    'besales://concepts/external-execution': 'concepts/external-execution.md',
+    'besales://concepts/feedback-sheets': 'concepts/feedback-sheets.md',
+    'besales://concepts/workbook-classification': 'concepts/workbook-classification.md',
+    'besales://workflows/platform-setup-from-scratch': 'workflows/platform-setup-from-scratch.md',
+    'besales://workflows/connect-crm-from-scratch': 'workflows/connect-crm-from-scratch.md',
+    'besales://workflows/connect-datasource-from-scratch': 'workflows/connect-datasource-from-scratch.md',
+    'besales://workflows/extract-from-document': 'workflows/extract-from-document.md',
+    'besales://workflows/iterate-with-sandbox': 'workflows/iterate-with-sandbox.md',
+    'besales://workflows/compare-models': 'workflows/compare-models.md',
+    'besales://workflows/production-readiness-check': 'workflows/production-readiness-check.md',
+    // v1.5 Increment 6b — doc-bridge глав ai-prompt-builder (копии, source of truth в ai-aniomaly).
+    'besales://docs/prompt-anatomy': 'docs/prompt-anatomy.md',
+    'besales://docs/knowledge-base': 'docs/knowledge-base.md',
+    'besales://docs/agent-behavior': 'docs/agent-behavior.md',
+    'besales://docs/platforms': 'docs/platforms.md',
+    'besales://docs/crm-integration': 'docs/crm-integration.md',
+    'besales://docs/pipeline-builder': 'docs/pipeline-builder.md',
+    'besales://docs/files-and-uploads': 'docs/files-and-uploads.md',
+    'besales://docs/pipeline-settings-deep': 'docs/pipeline-settings-deep.md',
+    // Дистиллят принципов промптинга (человечность + sales-плейбук), переиспользуется между компаниями.
+    'besales://docs/prompt-principles': 'docs/prompt-principles.md',
 };
-function conceptUrl(fileName) {
-    return new URL(`./concepts/${fileName}`, import.meta.url);
+function resourceUrl(relativePath) {
+    return new URL(`./${relativePath}`, import.meta.url);
 }
 function createResource(contract) {
-    const fileName = conceptFilesByUri[contract.uri];
-    if (!fileName) {
-        throw new Error(`Concept resource file mapping not found: ${contract.uri}`);
+    const relativePath = resourceFilesByUri[contract.uri];
+    if (!relativePath) {
+        throw new Error(`Resource file mapping not found: ${contract.uri}`);
     }
     return {
         uri: contract.uri,
@@ -24,7 +46,7 @@ function createResource(contract) {
             return {
                 uri: contract.uri,
                 mimeType: contract.mimeType,
-                text: await readFile(conceptUrl(fileName), 'utf-8'),
+                text: await readFile(resourceUrl(relativePath), 'utf-8'),
             };
         },
     };

package/dist/resources/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/resources/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAI5C,OAAO,EAAE,oBAAoB,EAAyB,MAAM,uBAAuB,CAAC;AAMpF,MAAM,iBAAiB,GAAqC;IAC1D,wBAAwB,EAAE,QAAQ;IAClC,6BAA6B,EAAE,aAAa;IAC5C,4BAA4B,EAAE,YAAY;IAC1C,4BAA4B,EAAE,YAAY;IAC1C,uCAAuC,EAAE,uBAAuB;CACjE,CAAC;AAEF,SAAS,UAAU,CAAC,QAAgB;IAClC,OAAO,IAAI,GAAG,CAAC,cAAc,QAAQ,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,cAAc,CAAC,QAA0B;IAChD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAEjD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,4CAA4C,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO;QACL,GAAG,EAAE,QAAQ,CAAC,GAAG;QACjB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,KAAK,CAAC,IAAI;YACR,OAAO;gBACL,GAAG,EAAE,QAAQ,CAAC,GAAG;gBACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,IAAI,EAAE,MAAM,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;aACpD,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,SAAS,GAAyB,oBAAoB,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/resources/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAI5C,OAAO,EAAE,oBAAoB,EAAyB,MAAM,uBAAuB,CAAC;AAMpF,mEAAmE;AACnE,gGAAgG;AAChG,MAAM,kBAAkB,GAAqC;IAC3D,wBAAwB,EAAE,iBAAiB;IAC3C,6BAA6B,EAAE,sBAAsB;IACrD,4BAA4B,EAAE,qBAAqB;IACnD,4BAA4B,EAAE,qBAAqB;IACnD,uCAAuC,EAAE,gCAAgC;IACzE,oCAAoC,EAAE,6BAA6B;IACnE,4CAA4C,EAAE,qCAAqC;IACnF,iDAAiD,EAAE,0CAA0C;IAC7F,8CAA8C,EAAE,uCAAuC;IACvF,qDAAqD,EACnD,8CAA8C;IAChD,2CAA2C,EAAE,oCAAoC;IACjF,0CAA0C,EAAE,mCAAmC;IAC/E,oCAAoC,EAAE,6BAA6B;IACnE,gDAAgD,EAAE,yCAAyC;IAC3F,gGAAgG;IAChG,+BAA+B,EAAE,wBAAwB;IACzD,+BAA+B,EAAE,wBAAwB;IACzD,+BAA+B,EAAE,wBAAwB;IACzD,0BAA0B,EAAE,mBAAmB;IAC/C,gCAAgC,EAAE,yBAAyB;IAC3D,iCAAiC,EAAE,0BAA0B;IAC7D,kCAAkC,EAAE,2BAA2B;IAC/D,uCAAuC,EAAE,gCAAgC;IACzE,oGAAoG;IACpG,kCAAkC,EAAE,2BAA2B;CAChE,CAAC;AAEF,SAAS,WAAW,CAAC,YAAoB;IACvC,OAAO,IAAI,GAAG,CAAC,KAAK,YAAY,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvD,CAAC;AAED,SAAS,cAAc,CAAC,QAA0B;IAChD,MAAM,YAAY,GAAG,kBAAkB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAEtD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,OAAO;QACL,GAAG,EAAE,QAAQ,CAAC,GAAG;QACjB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,KAAK,CAAC,IAAI;YACR,OAAO;gBACL,GAAG,EAAE,QAAQ,CAAC,GAAG;gBACjB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,IAAI,EAAE,MAAM,QAAQ,CAAC,WAAW,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;aACzD,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,SAAS,GAAyB,oBAAoB,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC"}

package/dist/resources/workflows/compare-models.md

@@ -0,0 +1,46 @@
+# Workflow: Compare models (model bake-off)
+
+Прогон одного и того же набора диалогов промпта агента на **нескольких моделях
+сразу** — чтобы понять, какая модель лучше для этого промпта.
+
+**Когда:** фаза 4 пайплайна (Build & Prove) ИЛИ по явному запросу оператора («сравни
+модели», «на какой модели лучше»). Операция **дорогая** (N моделей × M диалогов × ~10
+ходов) — **не запускай после каждого фикса промпта** (тест-рефлекс гоняет тест-сценарии,
+а НЕ перевыбор модели).
+
+## Маршрут
+
+1. **`besales_model_catalog_list`** — каталог моделей с `bestFor`-тегами «когда что
+   лучше», `tier` (budget/balanced/premium) и `available` (доступен ли провайдер
+   сейчас). Выбери **~5 моделей** под use-case агента (продажи → живой тон;
+   рассуждение → reasoning-модели; дёшево/много → budget). `defaultModelIds` —
+   разумный набор по умолчанию, если оператор не назвал модели.
+   - `available=false` → провайдер не настроен. grok/deepseek/gemini/qwen идут
+     через OpenRouter (нужен `OPENROUTER_API_KEY` на стороне prompt-services).
+
+2. **`besales_model_comparison_run_start`** `{ agent_id, models?, dialogue_count? }`
+   — запуск (async). По умолчанию `dialogue_count=5`; `models` опционально (тогда
+   набор по умолчанию). До **10 моделей** и **20 диалогов**, если оператор просит
+   больше. Возвращает `run_id`.
+
+3. **`besales_model_comparison_get`** `{ agent_id, run_id }` — поллируй до
+   `status=COMPLETED`. По каждой модели: диалоги + детерминированные метрики
+   (относительная стоимость в кредитах, длина ответа, completion-rate, wall-clock).
+
+4. **Суди сам.** Прочитай диалоги + метрики и реши, какая модель лучше — по
+   **качеству диалога** (живость, следование промпту, отсутствие слива/робота) и
+   **метрикам** (дешевле/быстрее при равном качестве). Ответь оператору с
+   **аргументами и конкретными выдержками** из диалогов.
+
+5. **`besales_model_comparison_eval_submit`** — зафиксируй вердикт: `winner`,
+   `rationale`, по каждой модели `success_score` (0-100), сильные/слабые стороны,
+   `excerpts`. Сохраняется (replace при повторе) для будущего UI. Ты всё равно
+   отвечаешь оператору в чате — submit просто фиксирует структуру.
+
+## Важно
+
+- Это **internal-операция**: prompt-services сам гоняет модели-кандидаты (ты НЕ
+  выполняешь стадии локально, в отличие от prompt/analyze external-пар).
+- Персоны генерируются один раз и реюзаются между моделями; меняется только модель
+  агента, «клиент» фиксирован — честное сравнение.
+- Реальный USD-расход прогона виден в costs ai-aniomaly (cost-callback).

package/dist/resources/workflows/connect-crm-from-scratch.md

@@ -0,0 +1,89 @@
+# Workflow: Connect CRM From Scratch
+
+Операционные шаги подключения CRM через MCP-провизионинг (Setup URL pattern). Это
+**source of truth** для «как получить credentials конкретной CRM» — НЕ ищи эти шаги в
+исходниках платформы. Доменная модель CRM (сущности, lifecycle, field-mapping) —
+`besales://docs/crm-integration`.
+
+> ⚠️ Секреты вводит ПОЛЬЗОВАТЕЛЬ на `setup_page_url` в браузере, минуя чат/LLM. Никогда не
+> проси токены/секретные ключи в чат. Несекретные поля (поддомен, публичный client_id)
+> тоже вводятся на setup-странице — не проси их у пользователя в чат, просто дай ссылку.
+
+## Общий цикл (любая CRM)
+
+1. `besales_crm_create_init({ crm_type })` → отдаёт `setup_ref` + `setup_page_url` +
+   `required_secret_fields`.
+2. Дай пользователю `setup_page_url`, перечисли что подготовить (см. по типу ниже), и
+   попроси заполнить **все поля на странице**.
+3. Поллируй `besales_crm_create_status({ setup_ref })`: `AWAITING_USER` → `VALIDATING` →
+   `READY` (`crm_id`) | `VALIDATION_FAILED` (`error_message` — пусть повторит) | `EXPIRED`
+   (новый init).
+4. После `READY` — активация (см. «Активация» ниже).
+
+Ordering-инвариант: CRM должна быть `READY` (и активной) прежде чем настраивать pipelines /
+field-mapping / operators.
+
+## AMOCRM — подключение по долгосрочному токену
+
+> Через MCP AmoCRM подключается **долгосрочным токеном** (long-lived token), а НЕ
+> OAuth-redirect. Поэтому callback/redirect настраивать не нужно — всё берётся из одной
+> интеграции в аккаунте AmoCRM.
+
+Что пользователь делает в AmoCRM (один раз):
+
+1. **Настройки → Интеграции → «+ Создать интеграцию» → «Создать внешнюю интеграцию»**
+   (приватная, для своего аккаунта).
+2. Имя любое (напр. `Besales`). Redirect URL — любой `https://` (напр. `https://app.besales.ai`):
+   для долгосрочного токена он не используется, но поле обязательное.
+3. **Доступы (scopes) — выдать пошире.** Обязательно: сделки, контакты, **события/звонки** —
+   без доступа к звонкам не сработает выгрузка аудио-диалогов (`besales_workbook_extract_amocrm_leads`
+   → `besales_icp_import_dialogues` и извлечение записей звонков).
+4. Сохранить. На вкладке **«Ключи и доступы»** появятся 4 значения:
+
+| Значение в AmoCRM | Поле | Тип |
+|---|---|---|
+| Поддомен аккаунта (`<name>.amocrm.ru`) | `sub_domain` | несекретное |
+| ID интеграции | `client_id` | несекретное |
+| Секретный ключ | `client_secret` | **секрет** |
+| Долгосрочный токен (кнопка «Долгосрочный токен») | `long_access_token` | **секрет** |
+
+Все 4 пользователь вводит на `setup_page_url`. `READY` для AmoCRM = креды сохранены и
+**токен онлайн-проверен** живым запросом к аккаунту (битый токен → `VALIDATION_FAILED`).
+
+Уникальность: один AmoCRM на workspace (`(workspaceId, AMOCRM)`).
+
+## BITRIX24 — подключение
+
+Несекретные: `domain` (`<portal>.bitrix24.ru`), `client_id`. Секрет: `client_secret`.
+После `READY` Bitrix24 требует **ручной установки local-app в портале** (завершается
+вебхуком на стороне Bitrix24) — предупреди пользователя об этом follow-up шаге.
+
+## GETCOURSE — подключение
+
+Несекретное: `account_domain` (`school.getcourse.ru`, опц. `managed_tag_prefix`).
+Секрет: `school_api_key` (опц. `legacy_api_key`). `READY` = read-only API-проба прошла.
+
+## TELEGRAM (Forum CRM) — подключение
+
+Несекретное: `forum_group_id` (ID форум-группы). Секрет: `crm_bot_token`. `READY` =
+`getMe` бота прошёл.
+
+## Активация
+
+CRM создаётся в `status` и работает (sync воронок, выгрузка звонков, запись лидов) только
+когда она **активна**. На workspace активна одна CRM за раз.
+
+- **Auto:** если в workspace нет другой активной CRM, провизионинг активирует подключённую
+  CRM сам на `READY` (после успешной live-валидации). Дополнительных шагов не нужно.
+- **Явно / переключение:** `besales_crm_activate({ crm_id })` — активирует указанную CRM и
+  **деактивирует остальные** в этом workspace. Используй когда уже есть активная CRM и нужно
+  переключиться, либо чтобы повторно включить CRM, авто-отключённую по ошибке авторизации
+  (`401/403`). ⚠️ Это деактивирует текущую активную — предупреди пользователя перед вызовом.
+
+## Что дальше (CRM READY + активна)
+
+Pipelines: `besales_crm_pipeline_list` / `besales_crm_pipeline_create`,
+`besales_platform_pipeline_link`. Маппинг полей: `besales_crm_field_mapping_get` /
+`besales_crm_field_mapping_upsert`. Операторы: `besales_crm_operator_list` /
+`besales_crm_operator_update`. Глубина — `besales://docs/crm-integration`,
+`besales://docs/pipeline-builder`, `besales://docs/pipeline-settings-deep`.

package/dist/resources/workflows/connect-datasource-from-scratch.md

@@ -0,0 +1,92 @@
+# Workflow: Connect Data Source (1С) From Scratch
+
+Операционные шаги подключения источника данных **1С** через MCP-провизионинг (Setup URL
+pattern). Это **source of truth** для «как подключить 1С и научить агента читать/писать в
+неё» — НЕ ищи эти шаги в исходниках платформы.
+
+1С — это **товарная БД** (категория «БД»), доступ через **OData**: товары, остатки, цены,
+история покупок, заказы. Это НЕ CRM (покупатели/сделки остаются в AmoCRM/Bitrix24).
+
+> ⚠️ Пароль пользователя 1С вводит ПОЛЬЗОВАТЕЛЬ на `setup_page_url` в браузере, минуя
+> чат/LLM. Никогда не проси пароль/секреты в чат. Несекретные поля (URL/логин/имя) тоже
+> можно ввести на setup-странице — просто дай ссылку.
+
+## Подключение (создание connection)
+
+1. `besales_datasource_create_init({ data_source_type: 'ONE_C' })` → отдаёт `setup_ref` +
+   `setup_page_url` + `required_secret_fields` (`password`) + `required_non_secret_fields`
+   (`name`, `base_url`, `username`; опц. `proxy_url`). `fields` в init опционально (pre-fill).
+2. Дай пользователю `setup_page_url` и попроси заполнить **все поля на странице**:
+   - `name` — имя подключения (любое, напр. «Основная база 1С»).
+   - `base_url` — URL публикации OData, напр. `https://host:port/<публикация>/odata/standard.odata/`.
+   - `username` — пользователь 1С (Basic Auth) с правами на чтение (для записи — на запись).
+   - `password` — **секрет**, только на setup-странице.
+   - `proxy_url` — опц., если 1С за приватной сетью/туннелем (см. «Доступ к сети» ниже).
+3. Поллируй `besales_datasource_create_status({ setup_ref })`: `AWAITING_USER` → `VALIDATING`
+   → `READY` (`data_source_id`) | `VALIDATION_FAILED` (`error_message` — пусть повторит) |
+   `EXPIRED` (новый init).
+
+> 1С часто за VPN/приватной сетью → health на finalize **best-effort**: `READY` = «подключение
+> создано», а живую достижимость смотри `besales_datasource_health` / `besales_datasource_list`.
+
+Ordering-инвариант: connection `READY` прежде чем назначать роли / включать векторизацию /
+строить 1С-триггеры.
+
+## Доступ к сети (частый блокер)
+
+Платформа ходит в 1С **исходящим HTTPS-запросом** к OData-URL — она НЕ заходит в сеть клиента
+(VPN на стороне платформы не нужен). Чтобы запрос дошёл:
+- OData-URL должен быть **достижим из интернета** (публичный домен/IP + порт), либо через
+  туннель/обратный прокси (тогда `proxy_url` указывает на него).
+- Клиент **вайтлистит исходящий IP платформы** (egress IP прод-окружения). Если health=false —
+  почти всегда это сеть: URL недоступен снаружи или IP не в whitelist.
+
+## Назначение ролей объектам
+
+1. `besales_datasource_catalogs({ data_source_id })` → объекты из `$metadata`
+   (`external_code`, `display_name`, `kind`: catalog/document/register).
+2. `besales_datasource_role_assign({ data_source_id, role, external_code, display_name })` —
+   one-role-per-object (прежние роли объекта снимаются). Роли:
+   - `PRODUCT_CATALOG` — каталог товаров (можно векторизовать, см. ниже).
+   - `STOCK` / `PRICE` — регистры остатков/цен. Передай `metadata.register.virtualTable`
+     (`Balance` — текущие, `SliceLast` — срез последних).
+   - `ORDER` — документ «Заказ покупателя» (для записи). `CUSTOMER` — история. `OTHER`.
+3. `besales_datasource_catalog_roles({ data_source_id })` → проверить назначенные роли +
+   флаг `vectorized`.
+
+## Векторизация каталога товаров (семантический поиск)
+
+`besales_datasource_vectorize({ data_source_id, catalog_external_code, enabled: true })` —
+включает семантический поиск по каталогу (роль `PRODUCT_CATALOG` обязательна, подключение
+`ACTIVE`): синк в Pinecone. `enabled: false` — удаление векторов. Нужно, когда товаров много
+и поиск по точному `$filter` не годится («покажи что-то для дома до 5000»).
+
+## Чтение/запись в диалоге — это ДЕЙСТВИЯ ТРИГГЕРОВ (не tools агента)
+
+Финальный шаг «агент реально читает/пишет 1С в разговоре» настраивается через **существующий**
+`besales_trigger_upsert` (НЕ через `besales_datasource_*`). У агента ровно 3 attachable tool
+(`run_trigger`/`send_pic`/`call_qa`) — 1С-логика живёт внутри действий триггера. Форма действия:
+
+```
+besales_trigger_upsert({ platform_id, agent_id, name, condition, actions: [{
+  actionType: 'DATA_SOURCE_READ',         // или 'DATA_SOURCE_WRITE'
+  dataSourceReadConfig: {                 // или dataSourceWriteConfig
+    connectionId: '<data_source_id>',
+    catalogRole: 'STOCK',                 // PRODUCT_CATALOG/STOCK/PRICE/CUSTOMER/...
+    catalogExternalCode: '<external_code>',
+    filterTemplate: [ { field, op, valueTemplate } ]   // READ: фильтр (поддержка {phone}/{{var}})
+    // WRITE: вместо filterTemplate → fieldMappings: [ { field, valueTemplate } ]
+  }
+}] })
+```
+
+Backend строго валидирует (anti-IDOR + обязательность конфига): кривой/отсутствующий
+`dataSourceReadConfig`/`WriteConfig` → `400` (не молча теряется). Бизнес-примеры: триггер
+«ПроверкаНаличия» (READ STOCK+PRICE), «ИсторияПокупок» (READ CUSTOMER, фильтр `{phone}`),
+«ОформлениеЗаказа» (WRITE ORDER).
+
+## Управление
+
+`besales_datasource_list` (status/enabled/base_url), `besales_datasource_health` (live OData),
+`besales_datasource_enable({ enabled })` (вкл/выкл подключение — выключенное не используется
+действиями триггеров, даже если 1С доступна).

package/dist/resources/workflows/extract-from-document.md

@@ -0,0 +1,36 @@
+# Workflow: Extract From Document (fan-out)
+
+Пользователь дал документ (xlsx / Google Sheets / текст / PDF). **Один источник часто питает
+несколько целей сразу** — не клади «только в одно место». Это продуктивный discovery, а не
+блокирующий шаг фазы 2 (Discover).
+
+## Шаг 1 — Осмотр
+
+- xlsx / Google Sheets: `besales_workbook_inspect` (вкладки, заголовки, типы колонок).
+- Иначе: прочитай содержимое и классифицируй сам.
+- Глубже про таксономию вкладок — concept `besales://concepts/workbook-classification`.
+
+## Шаг 2 — Триаж и fan-out
+
+Реши что внутри (часто несколько типов одновременно) и разложи параллельно:
+
+| Что в документе | Куда (инструменты) |
+|---|---|
+| FAQ / вопросы-ответы | `besales_knowledge_qa_create` (+ опц. `besales_qa_generation_get_instructions` / `besales_qa_generation_submit` для авто-draft) |
+| Прайс / каталог / таблица | `besales_knowledge_table_link` либо `besales_workbook_to_knowledge_document` |
+| Продуктовый / бизнес-текст | `besales_knowledge_document_upload` |
+| Brand-guide / tone / persona | ICP tone (`besales_icp_create`) + `besales_behavior_update` |
+| Выгрузка диалогов из CRM (amoCRM) | `besales_workbook_extract_amocrm_leads` → `besales_icp_import_dialogues` → `besales_icp_import_status` |
+| Значения (имя компании, телефон, часы) | `besales_variable_create` |
+| Общий PDF / договор / политика / непонятный тип (fallback) | `besales_knowledge_document_upload` — дефолт, если ничего выше не подошло |
+
+## Шаг 3 — Привязка knowledge к каналу
+
+Если что-то ушло в knowledge — не забудь создать/привязать space:
+`besales_knowledge_space_create` → `besales_knowledge_space_channel_link_upsert`.
+
+## Принцип
+
+Документ редко = «одна сущность». Прайс-лист несёт и таблицу для RAG, и переменные
+(контакты), и иногда tone. Раскладывай по всем релевантным целям за один проход.
+Затем возвращайся в `besales://workflows/platform-setup-from-scratch`.

package/dist/resources/workflows/iterate-with-sandbox.md

@@ -0,0 +1,31 @@
+# Workflow: Iterate With Sandbox
+
+Цикл улучшения агента (промпт / behavior / triggers) через прогон на тест-сценариях.
+Это **петля**, а не финальный шаг — повторяй пока качество не стабилизируется.
+
+## Цикл
+
+1. **Прогон.** `besales_sandbox_run_start` (на ICP test scenarios / personas).
+2. **Анализ findings (external execution).**
+   - `besales_sandbox_findings_get_instructions` → локально проанализируй прогон →
+     `besales_sandbox_findings_submit`.
+   - Для персонажных симуляций: `besales_simulation_findings_get_instructions` /
+     `besales_simulation_findings_submit`.
+   - Ты видишь ICP/ТЗ контекст и умнее internal-модели — давай конкретные findings.
+3. **Правки.**
+   - Промпт: `besales_prompt_patch_start` → `besales_prompt_patch_get` →
+     `besales_prompt_patch_apply` → `besales_prompt_patch_commit`
+     (откат — `besales_prompt_patch_discard`). После commit прогони `besales_prompt_lint`.
+   - Поведение/действия: `besales_behavior_update` / `besales_trigger_upsert`.
+4. **Повторный прогон** `besales_sandbox_run_start` → сравни с предыдущим.
+
+## Когда останавливаться
+
+- Findings ниже порога серьёзности и нет регрессий между прогонами.
+- Ключевые ICP-сценарии проходят.
+- Не гонись за идеалом — после стабилизации иди в
+  `besales://workflows/production-readiness-check`.
+
+## Глубина
+
+Concept `besales://concepts/sandbox` — что именно тестирует sandbox и какие сценарии.

package/dist/resources/workflows/platform-setup-from-scratch.md

@@ -0,0 +1,113 @@
+# Workflow: Platform Setup From Scratch
+
+Backbone happy-path настройки с нуля по **6-фазной модели** (1 Connect · 2 Discover · 3 Author ·
+4 Build&Prove · 5 Enrich · 6 Activate). Веди пользователя по фазам, после каждой говори «мы здесь,
+дальше — X». Фазы — **ориентир, не жёсткий конвейер**: жёсткий gate один (фаза 1 — нельзя строить
+на неподключённом канале); фазы 2–6 можно чередовать и забегать вперёд (document fan-out).
+Канонич. фазовая модель + completeness→phase mapping живут в serverInstructions; здесь —
+операционные шаги с именами инструментов.
+
+## Шаг 0 — Ориентация (всегда)
+
+1. `besales_workspace_overview` → прочитай `setupCompleteness` и `suggestedNextPhase`.
+2. Если workspace частично настроен — **не начинай с нуля**, продолжи с `suggestedNextPhase`.
+3. Убедись, что выбран нужный workspace (`besales_workspace_current`; при необходимости
+   `besales_workspace_use`).
+
+## Фаза 1 — Connect (async gate ⏸)
+
+Если `channelsConnected === 0` (или нужен новый канал):
+
+- API-key канал (TelegramBot/Wazzup/Salebot/SmsGorod/VKon/GetCourse/WebWidget/Bitrix24Bot):
+  `besales_platform_create_init` → покажи пользователю `setup_page_url` (секреты он вводит
+  в браузере) → поллируй `besales_platform_create_status` по `setup_ref` до `READY`.
+- OAuth канал (Instagram/Avito): `besales_platform_create_oauth_init` → покажи `auth_url` →
+  поллируй `besales_platform_create_status` до `READY`.
+
+**Не строй дальше пока статус не `READY`.** `VALIDATION_FAILED` → покажи `error_message`,
+повтори ввод. `EXPIRED` → новый init. **CRM здесь НЕ подключаем** — она ленивая (фаза 5/6).
+
+## Фаза 2 — Discover (профиль компании + ICP)
+
+**(2a) Профиль компании.** Собери: что продают / УТП / контакты / ограничения. Значения
+(имя компании, телефон) → `besales_variable_create` (доступны в промпте как `{{{name}}}`).
+
+**(2b) ICP — сначала определи ТИП бота:**
+- **sales / qualification / booking / outbound / продажи** → ICP **ОБЯЗАТЕЛЕН**. Без него
+  промпт generic, квалификация лидов плохая. Не финализируй промпт (фаза 4) пока нет ICP.
+  Нет данных — спроси про ЦА / боли / возражения ИЛИ импортируй из диалогов.
+- **FAQ / support / справочный** → ICP опционален; не навязывай.
+
+Источники ICP — файлы, инфо о компании, аудио-звонки, выгрузки переписок (Google Sheets), CRM:
+`besales_icp_create` (+ `besales_icp_import_dialogues` → `besales_icp_import_status`, затем пара
+`besales_icp_analysis_get_instructions` / `besales_icp_analysis_submit`). Таблицы — всегда
+`besales_workbook_inspect` первым (правило 6). **Документ от пользователя?** → workflow
+`besales://workflows/extract-from-document` (fan-out). Discovery продуктивен — не блокирует.
+
+## Фаза 3 — Author (скрипт + тест-сценарии)
+
+Подготовь материал, который дальше расходится:
+1. **«Скрипт диалога»** — теперь ОТДЕЛЬНАЯ ХРАНИМАЯ сущность (поле `dialog_script` = source of truth),
+   сохраняется на Фазе 4 ПОСЛЕ `agent_create` через `besales_dialog_script_update`; §6 промпта
+   рендерится ИЗ неё детерминированно. Если есть ICP-диалоги / звонки — намайни реальные фразы операторов
+   по этапам (`besales://docs/prompt-principles` раздел C), на их живом языке, не из абстрактной «рыбы».
+2. **Справочное / «лишнее»** (факты, прайс, регламент) → RAG/Q&A, НЕ в промпт:
+   `besales_knowledge_qa_*`, `besales_agent_facts_set` (+ `besales_facts_classify_and_migrate`).
+3. **Тест-сценарии** для будущих прогонов → `besales_test_scenario_generate_get_instructions` /
+   `besales_test_scenario_generate_submit`.
+
+## Фаза 4 — Build & Prove (агент + промпт + доказан тестами + модель)
+
+Требует фазу 1 `READY`:
+
+1. `besales_agent_create` (на READY-канале).
+2. «Скрипт диалога» → промпт (скрипт ПЕРВЫМ, отдельным шагом):
+   а) построй структуру скрипта (этапы/ветки/реплики/переходы) → `besales_dialog_script_update`
+      (поле `dialog_script` = source of truth; §6 рендерится из него; читать/сверять — `besales_dialog_script_get`);
+   б) промпт: `besales_prompt_generate_get_instructions` → локально выполни стадии →
+   `besales_prompt_generate_submit` → `besales_prompt_finalize` (§6 = render скрипта). Структура — `besales://docs/prompt-anatomy`.
+3. `besales_behavior_update` — приветствие: ТОЛЬКО `bot_greeting` текстом, БЕЗ кнопок (дефолт
+   «Привет!/Hello» → язык аудитории; для INBOUND открывает диалог). `greeting_buttons` opt-in — лишь
+   по явному запросу; остальной behavior (persona/тон/typing) — фаза Enrich. `besales://docs/agent-behavior`.
+4. **Статика:** `besales_prompt_lint` + анализ `besales_prompt_analyze_get_instructions` /
+   `besales_prompt_analyze_submit`.
+5. **Симуляция:** `besales_sandbox_run_start` по тест-сценариям (фаза 3) → findings → правки.
+   Глубже — `besales://workflows/iterate-with-sandbox`.
+6. **Выбор модели (только здесь или по запросу — дорого):** `besales://workflows/compare-models`
+   (`besales_model_catalog_list` → `besales_model_comparison_run_start` → `_get` → `_eval_submit`).
+
+## Фаза 5 — Enrich (знания + поведение + действия; чередуется с фазой 4)
+
+- **Знания (RAG):** `besales_file_upload_request` → `besales_file_upload_status`;
+  `besales_knowledge_space_create` → наполни (`besales_knowledge_document_upload` /
+  `besales_knowledge_qa_create` / `besales_knowledge_table_link` / `besales_knowledge_website_add`) →
+  **обязательно** привяжи space к каналу: `besales_knowledge_space_channel_link_upsert`
+  (иначе агент knowledge «не видит» — частая ошибка). Глубина — `besales://docs/knowledge-base`.
+- **Поведение:** `besales_behavior_update` (тонкая настройка тона/фильтров).
+- **Триггеры + роутинг:** `besales_trigger_upsert`; multi-agent — `besales_routing_rule_upsert` +
+  `besales_router_update` (тестируй каждого агента и систему — см. serverInstructions, правило 4).
+- **Внешняя БД (1С) для триггеров:** `besales://workflows/connect-datasource-from-scratch`
+  (`besales_datasource_*`; чтение/запись через триггеры DATA_SOURCE_READ/WRITE, не тулы агента).
+- **CRM подключаем здесь — ЕСЛИ нужна триггерам** (`besales://workflows/connect-crm-from-scratch`).
+- Каждая новая версия промпта → тест-рефлекс (serverInstructions, правило 1).
+
+## Фаза 6 — Activate (воронка + операторы + follow-ups + настройки)
+
+«Вокруг диалога» — обычно когда ядро уже работает:
+- **Воронка CRM (CRM ОБЯЗАТЕЛЕН):** `besales_crm_pipeline_list` / `besales_crm_pipeline_create`,
+  `besales_platform_pipeline_link`, `besales_crm_field_mapping_upsert`.
+- **Операторы:** `besales_crm_operator_list` / `besales_crm_operator_update`.
+- **Follow-ups / реактивация** (CRM не требует): `besales_followup_sequence_upsert`.
+- **Настройки платформы:** `besales_platform_settings_update` / `besales_pipeline_settings_update`.
+
+## Финал
+
+→ workflow `besales://workflows/production-readiness-check`. Затем предложи: вернуться к доработке
+любой фазы или зафиксировать, что настройка завершена.
+
+---
+
+**Компас:** `suggestedNextPhase` эмитит `{1,4,5,null}` и НЕ знает тип бота — для свежего канала
+сразу показывает `'4'`. Для non-FAQ ботов сделай фазы 2 (ICP) и 3 (скрипт) ДО финализации промпта,
+даже если компас их пропустил. Сквозные правила (тест-рефлекс, Sheets-feedback, модели→фаза 4,
+мультиагент+роутер, ленивая CRM, гибкость) — в serverInstructions.

package/dist/resources/workflows/production-readiness-check.md

@@ -0,0 +1,41 @@
+# Workflow: Production Readiness Check
+
+Финальная проверка перед запуском бота. Опирается на `besales_workspace_overview` →
+`setupCompleteness`. Формируй список «готово / недоделано», не блокируй жёстко —
+часть пунктов опциональна по бизнес-цели.
+
+## Шаг 1 — Снимок
+
+`besales_workspace_overview` → читай `setupCompleteness`. При необходимости детали:
+`besales_platform_context_get` (по конкретному каналу), `besales_agent_list`.
+
+## Чеклист (по `setupCompleteness`, поля camelCase)
+
+**Блокирующее (должно быть):**
+- `channelsConnected ≥ 1` и нет залипших `channelsPending`. Канал `isActive` + AI включён.
+- `hasAnchorAgent` — агент существует, с непустым промптом (проверь `besales_prompt_lint`)
+  и приветствием (`besales_behavior_update`).
+
+**Сильно рекомендуется:**
+- `hasKnowledge` И `knowledgeLinkedToChannel` — knowledge не просто загружен, а **привязан**
+  к каналу (`besales_knowledge_space_channel_link_upsert`). «Загружен но не связан» = агент не видит.
+- `lastSandboxRunAt` не null — прогонялся sandbox, findings закрыты
+  (см. `besales://workflows/iterate-with-sandbox`).
+
+**По типу бота:**
+- **sales / qualification / booking** → `hasIcp` должен быть true. Для таких ботов ICP —
+  не опция, а условие качества (без него промпт generic). Если false — это «недоделано».
+- **FAQ / support** → ICP опционален, `hasIcp=false` не блокирует.
+
+**По бизнес-цели (опционально — НЕ «недоделано» если не нужно):**
+- Triggers / follow-ups: `besales_trigger_upsert` / `besales_followup_sequence_upsert`.
+- CRM: `crmConnected`, pipelines привязаны (`besales_platform_pipeline_link`),
+  field-mapping (`besales_crm_field_mapping_get`), операторы (`besales_crm_operator_list`).
+
+## Шаг 2 — Отчёт пользователю
+
+Покажи «✅ готово / ⚠️ стоит доделать / ⏭️ опционально». Для каждого ⚠️ — какой инструмент
+закрывает пробел. Не запускай молча — дай пользователю решение.
+
+> Доменная глубина: `besales://docs/platforms` (готовность канала), `besales://docs/crm-integration`
+> (CRM-настройка), `besales://docs/knowledge-base` (RAG-привязка).