@besales/mcp 0.14.0 → 0.18.0

package/docs/agent-usage-guide.full.ru.md

@@ -0,0 +1,426 @@
+# Besales — подробный гайд по работе с помощником
+
+> **Для кого:** и для человека (оператора, менеджера, интегратора), и как ориентир
+> для самого **AI-агента** (Claude Code / Codex), которому этот текст можно дать как
+> контекст «как правильно работать».
+>
+> Это **подробная** версия. Если нужен короткий гайд «на пальцах» —
+> [`agent-usage-guide.ru.md`](./agent-usage-guide.ru.md). Технический runbook по
+> установке (локальная разработка, отладка) — [`host-setup.md`](./host-setup.md).
+>
+> Названия инструментов (вроде `besales_...`) приведены **для справки и для агента** —
+> человеку их знать не обязательно: помощник подбирает их сам.
+
+---
+
+## Оглавление
+
+1. [Что это и как устроено](#1-что-это-и-как-устроено)
+2. [Как помощник думает — 4 идеи](#2-как-помощник-думает--4-идеи)
+3. [Подключение (Claude Code и Codex)](#3-подключение-claude-code-и-codex)
+4. [Как формулировать запросы](#4-как-формулировать-запросы)
+5. [Чем Claude Code отличается от Codex](#5-чем-claude-code-отличается-от-codex)
+6. [Правила, которые помощник соблюдает сам](#6-правила-которые-помощник-соблюдает-сам)
+7. [Обычный порядок настройки — 6 этапов](#7-обычный-порядок-настройки--6-этапов)
+8. [Готовые сценарии (рецепты)](#8-готовые-сценарии-рецепты)
+9. [Что помощник умеет — по группам](#9-что-помощник-умеет--по-группам)
+10. [Справочники, которые он читает сам](#10-справочники-которые-он-читает-сам)
+11. [Безопасность и необратимые действия](#11-безопасность-и-необратимые-действия)
+12. [Если что-то идёт не так](#12-если-что-то-идёт-не-так)
+13. [Чеклист «бот с нуля»](#13-чеклист-бот-с-нуля)
+14. [Словарик понятных слов](#14-словарик-понятных-слов)
+
+---
+
+## 1. Что это и как устроено
+
+**Помощник Besales** — это набор «умений», через которые AI-агент настраивает твоих
+чат-ботов: подключает каналы связи, обучает на твоих материалах, пишет и улучшает
+характер и сценарий разговора, связывает с CRM, настраивает автоматические действия,
+проверяет бота на учебных диалогах, делает напоминания клиентам.
+
+Ты не нажимаешь кнопки руками — ты **пишешь задачу словами**, а помощник делает.
+
+Как это устроено по цепочке:
+
+```
+Ты (заказчик)
+   │  пишешь словами: «настрой бота …»
+   ▼
+Claude Code / Codex   ← здесь живёт AI-агент: понимает задачу и решает, что делать
+   │
+   ▼
+помощник Besales      ← маленькая программа на твоём компьютере (соединяет агента с системой)
+   │
+   ▼
+система Besales       ← здесь хранится всё по-настоящему: боты, каналы, CRM, база знаний
+```
+
+Что важно понять:
+
+- **Сама программа-помощник ничего не «придумывает»** — она передаёт задачи в систему.
+  Думает AI-агент (в Claude Code / Codex).
+- Всё, что помощник делает, **на самом деле меняет настройки в системе** — это не
+  черновик. Поэтому перед необратимым он спрашивает подтверждение.
+- Набор умений **растёт** — точное число не важно; если нужно «что сейчас есть»,
+  помощник сам сверяется с системой.
+
+---
+
+## 2. Как помощник думает — 4 идеи
+
+Четыре принципа объясняют почти всё его поведение:
+
+1. **Сначала осмотреться.** Если непонятен контекст, помощник сперва смотрит, что у
+   тебя уже настроено (какие каналы, боты, CRM, база знаний и что ещё не доделано).
+   Он не угадывает — он сверяется. *(Технически — `besales_workspace_overview`.)*
+
+2. **Идти по понятному порядку.** Настройка обычно идёт по шагам: подключить канал →
+   разобраться с бизнесом и клиентом → собрать сценарий → создать и проверить бота →
+   обогатить знаниями и действиями → запустить с CRM и напоминаниями (подробно — §7).
+   Строго следовать не обязательно: можно перескакивать. Жёсткое правило одно —
+   **нельзя настраивать бота на канале, который ещё не подключён**.
+
+3. **Секреты — только в браузере, не в чат.** Когда нужен пароль или токен (от канала,
+   от CRM), помощник **не просит его в переписке**. Он присылает ссылку — ты открываешь
+   её в браузере и вводишь там. Так безопаснее, и секрет не «утекает» через переписку.
+
+4. **Сложное — в два приёма.** Для умных задач (сочинить промпт, проанализировать
+   диалоги, придумать учебные сценарии) помощник работает в два приёма: сначала берёт
+   инструкцию, потом выполняет своим умом, потом отправляет результат в систему. Тебе
+   это видеть не обязательно — просто так получается умнее и быстрее.
+
+---
+
+## 3. Подключение (Claude Code и Codex)
+
+> Делается **один раз**. Если не дружишь с терминалом — попроси технического коллегу:
+> это пара команд, дальше нужен только чат.
+
+### Шаг 1. Добавить помощника
+
+Смотря чем пользуешься:
+
+**Claude Code:**
+```
+claude mcp add --scope user -- besales npx -y @besales/mcp
+```
+Проверить, что добавился: `claude mcp list` (должен быть `besales`). В новой сессии —
+команда `/mcp` покажет, что `besales` на связи.
+
+**Codex (в терминале или в приложении):**
+```
+codex mcp add besales -- npx -y @besales/mcp
+```
+Проверить: `codex mcp list` и `codex mcp get besales`.
+
+То же самое для Codex можно записать в файл `~/.codex/config.toml`:
+```toml
+[mcp_servers.besales]
+command = "npx"
+args = ["-y", "@besales/mcp"]
+```
+
+### Шаг 2. Представиться системе
+
+Один раз войди под своим аккаунтом и выбери рабочее пространство (откроется браузер):
+```
+npx -y @besales/mcp connect
+```
+
+Полезные команды (нужны редко):
+
+| Команда | Что делает |
+|---|---|
+| `npx -y @besales/mcp connect` | подключить / обновить рабочее пространство |
+| `npx -y @besales/mcp status` | показать, какое пространство сейчас активно |
+| `npx -y @besales/mcp connections` | список подключённых пространств (звёздочка — активное) |
+| `npx -y @besales/mcp use <id>` | сделать другое пространство активным по умолчанию |
+| `npx -y @besales/mcp disconnect --all` | отключить все пространства |
+
+### Если пространств несколько
+
+Можно подключить несколько (даже под разными аккаунтами): `connect` под аккаунтом A →
+перелогинься в браузере → `connect` под аккаунтом B. Чтобы зафиксировать сессию под
+нужное пространство — просто попроси в чате: «используй рабочее пространство <название>».
+Помощник сам подставит правильное; **спрашивать у тебя ID он не должен**.
+
+---
+
+## 4. Как формулировать запросы
+
+Главное правило: **опиши бизнес-задачу обычными словами**, как живому исполнителю.
+Помощник сам поймёт, какие «кнопки» нажать.
+
+✅ **Хорошо:**
+- «Настрой Telegram-бота для продажи косметики. Вот информация о компании: … Примеры
+  наших диалогов с клиентами — вот ссылка: …»
+- «Добавь этот прайс и ответы на частые вопросы в знания бота и привяжи к каналу.»
+- «Сделай, чтобы бот звучал как живой человек, не повторялся и не сдавался после
+  первого “нет”.»
+- «Поменяй у бота сценарий поиска товара — пусть сначала ищет по артикулу.»
+- «Прогони бота на учебных диалогах и покажи, где он плохо отрабатывает возражения.»
+- «Подключи AmoCRM и настрой воронку продаж.»
+
+❌ **Не нужно:**
+- Просить «найди такой-то инструмент» или называть технические имена — он сам.
+- Присылать ID / номер рабочего пространства — он уже знает твоё.
+- Вводить пароли и токены прямо в чат — для них он даст ссылку в браузер.
+
+Если задача открытая («настрой мне бота под наш бизнес») — помощник сначала осмотрится,
+потом пойдёт по понятному порядку (§7) и будет коротко проговаривать, на каком шаге вы
+сейчас и что дальше.
+
+---
+
+## 5. Чем Claude Code отличается от Codex
+
+Сам процесс одинаков. Разница — в мелочах хоста (программы, в которой живёт агент):
+
+| | Claude Code | Codex (терминал и приложение) |
+|---|---|---|
+| Умения помощника | видны агенту сразу | **могут подгружаться по мере надобности** |
+| Как проверить, что подключён | `claude mcp list`, команда `/mcp` | `codex mcp list`, `codex mcp get besales` |
+| Если агент «не видит» нужное умение | обычно видно сразу | агент должен **сам** его найти — это его работа, не твоя |
+| После добавления | новая сессия подхватывает | запущенному приложению Codex иногда нужен перезапуск |
+
+**Важно про Codex:** иногда умение «подгружается не сразу». Если ты попросил задачу, а
+агент говорит «такого нет» — это его недоработка: он обязан сначала **поискать** нужное
+умение и только потом делать вывод. Тебе достаточно сказать: «поищи нужный инструмент
+Besales и сделай». Что система реально «отдаёт всё» — видно по `codex mcp list/get`.
+
+---
+
+## 6. Правила, которые помощник соблюдает сам
+
+Эти правила «вшиты» в помощника — он следует им без напоминаний. Тебе полезно их знать,
+чтобы понимать его поведение (а если ты — агент, читающий этот гайд, это твои правила).
+
+1. **Сначала осмотр.** При неясности — смотрит, что уже настроено, не угадывает.
+
+2. **Что должно быть готово раньше:**
+   - Канал должен быть **подключён и готов**, прежде чем создавать на нём бота.
+   - CRM должна быть **подключена**, прежде чем настраивать её воронки, поля, операторов.
+   - Бот должен **существовать**, прежде чем настраивать его действия, поведение, умения.
+   - Хранилище знаний должно **существовать**, прежде чем загружать в него файлы и
+     привязывать к каналу.
+
+3. **Подключения идут с паузой.** Подключение канала/CRM не мгновенное: помощник даёт
+   ссылку, ты вводишь секрет в браузере, он ждёт, пока система подтвердит готовность.
+   Если данные неверные — покажет ошибку и предложит повторить; если ссылка протухла —
+   сделает новую.
+
+4. **Необратимое — только с подтверждением.** Удалить бота-платформу через помощника
+   нельзя (только вручную в личном кабинете). Скопировать настройку «поверх» существующей
+   — **двойное** подтверждение. Удалить действие/воронку/переменную/документ — отдельное
+   явное «да».
+
+5. **Сложное — в два приёма** (сочинить промпт, проанализировать, придумать сценарии):
+   взять инструкцию → выполнить умом → отправить результат.
+
+6. **Твой документ раскладывается по нескольким местам.** Прислал прайс + FAQ — помощник
+   разложит: вопросы-ответы в одно место, прайс/таблицу в другое, текст в третье. Для
+   таблиц (Excel/Google Sheets) он сначала аккуратно читает **все вкладки**, а не верит
+   плоской копипасте. Если материал на другом языке — сперва даст краткое саммари на
+   твоём языке и по цифрам/условиям дождётся подтверждения.
+
+7. **Инструкции «как сделать» он берёт из своих справочников**, а не выдумывает (откуда
+   взять токен CRM, какие права нужны, в каком порядке шаги). Нет нужного справочника —
+   честно скажет, что это пробел.
+
+8. **Рабочее пространство не переспрашивает** — оно выбрано при подключении. Если вдруг
+   «не нахожу» — сперва проверит активное пространство, а не решит, что всё удалено.
+
+---
+
+## 7. Обычный порядок настройки — 6 этапов
+
+Так обычно идёт настройка «с нуля до запуска». Это **не жёсткий маршрут** — этапы можно
+чередовать и забегать вперёд. Единственное твёрдое правило: нельзя строить бота на
+неподключённом канале.
+
+| Этап | О чём он | Что происходит |
+|---|---|---|
+| **1. Подключить канал** | где бот будет общаться | подключаем Telegram/WhatsApp/сайт и т.д.; ждём, пока канал станет готов. CRM пока **не** трогаем |
+| **2. Понять бизнес и клиента** | для кого и что продаём | заносим инфо о компании (что продаём, плюсы, контакты) и **портрет идеального клиента** — его боли, возражения, как он говорит. Источник: файлы, записи звонков, выгрузки переписок |
+| **3. Собрать сценарий** | как бот ведёт разговор | готовим скелет диалога (этапы → ветки → **реальные фразы** ваших менеджеров) и учебные ситуации для проверки |
+| **4. Создать и проверить бота** | сам бот + промпт | создаём бота, пишем его «характер» и сценарий, задаём приветствие; прогоняем по учебным диалогам и смотрим слабые места; при желании сравниваем разные модели |
+| **5. Обогатить знаниями и действиями** | что бот знает и делает | загружаем базу знаний (и **обязательно привязываем к каналу**), настраиваем поведение, автоматические действия, при необходимости — связь с товарной базой (1С) и CRM |
+| **6. Запустить** | всё вокруг диалога | настраиваем воронку в CRM (тут CRM обязательна), операторов, напоминания клиентам, общие настройки канала; финальная проверка перед запуском |
+
+Подсказка системы «какой шаг следующий» — это **совет, а не приказ**: для продающих
+ботов этапы 2 (клиент) и 3 (сценарий) лучше сделать **до** финального промпта, даже если
+система предложила сразу строить бота.
+
+**Что помощник делает по ходу всегда:**
+- **Проверяет после каждой правки** — гоняет бота на учебных диалогах (если ты явно не
+  отказался). Не ждёт самого конца.
+- **Сравнение моделей — вещь дорогая**, делает только по запросу.
+- **CRM подключает лениво** — не на старте, а когда она реально нужна.
+- **Гибок** — в любой момент может сделать что-то вне текущего шага.
+
+---
+
+## 8. Готовые сценарии (рецепты)
+
+Что сказать → что произойдёт. Формулировки — обычные.
+
+### Бот с нуля
+> «Настрой Telegram-бота для продаж <X>. Инфо о компании: … Портрет клиента возьми из
+> этого Google-листа оценённых звонков: <ссылка>.»
+
+Помощник: осмотрится → подключит канал (ты введёшь токен в браузере) → занесёт инфо о
+компании и портрет клиента из листа → подготовит учебные ситуации → создаст бота, напишет
+промпт, задаст приветствие → проверит на учебных диалогах → покажет отчёт.
+
+### Добавить базу знаний
+> «Добавь этот прайс и ответы на частые вопросы в знания бота и привяжи к каналу.»
+
+Разложит по местам (вопросы-ответы / прайс-таблица / текст), создаст хранилище знаний и
+**обязательно привяжет его к каналу** — иначе бот знания «не увидит».
+
+### Подключить CRM
+> «Подключи AmoCRM к этому боту и настрой воронку.»
+
+Сверится со справочником, даст ссылку для ввода доступа в браузере, дождётся готовности,
+активирует и настроит воронку, поля, операторов.
+
+### Поменять/удалить действия бота
+> «У бота поменяй сценарий поиска товара — пусть сначала ищет по артикулу.»
+
+- Переименовать/включить-выключить действие — простая правка.
+- **Заменить набор действий** (например, сменить режим поиска) — помощник сперва
+  прочитает текущие действия и пришлёт **полный** новый набор (замена целиком, как в
+  личном кабинете). По умолчанию это защищено, чтобы случайно ничего не потерять.
+- **Удалить действие/триггер** — с обязательным подтверждением.
+
+### Итерации по замечаниям тестировщика
+> «Тестировщик пишет замечания в этот Google-лист — обработай их.»
+
+Прочитает замечания из листа → внесёт правки в промпт → отметит обработанные строки →
+перепроверит на учебных диалогах, чтобы не сломалось.
+
+### Сравнить модели
+> «Сравни промпт на нескольких моделях.»
+
+Подберёт несколько моделей, прогонит один и тот же набор диалогов на каждой, сам оценит,
+какая лучше. Дорогая операция — только по запросу.
+
+### Подключить товарную базу (1С)
+> «Подключи 1С, чтобы бот искал товары и остатки.»
+
+Проведёт через подключение (ввод доступа в браузере), настроит, и сделает действия
+«найти товар / остаток» внутри сценария бота.
+
+### Скопировать настройку на другой канал
+> «Скопируй этого бота на новый WhatsApp-канал.»
+
+Покажет предпросмотр и скопирует. Если копирует «поверх» существующего — спросит дважды.
+
+---
+
+## 9. Что помощник умеет — по группам
+
+(Для человека — обзор; для агента — где искать. Точные имена знать не нужно.)
+
+| Группа | Зачем | Примеры умений |
+|---|---|---|
+| Обзор | посмотреть, что уже настроено | `besales_workspace_overview` |
+| Каналы | подключить канал, настройки | `besales_platform_create_init` / `_oauth_init` / `_create_status`, `besales_platform_settings_update` |
+| Боты и промпты | создать бота, сочинить/улучшить промпт, скелет диалога, приветствие | `besales_agent_*`, `besales_prompt_*`, `besales_dialog_script_*`, `besales_behavior_update` |
+| Действия бота | что бот делает по условиям, несколько ботов + переключение | `besales_trigger_upsert` / `besales_trigger_delete`, `besales_routing_rule_upsert`, `besales_router_update` |
+| База знаний | хранилища, документы, вопросы-ответы, таблицы, сайты | `besales_knowledge_*` |
+| Клиент (портрет) | портрет клиента, импорт диалогов, учебные ситуации | `besales_icp_*`, `besales_test_scenario_generate_*` |
+| CRM | подключить, активировать, воронки, поля, операторы | `besales_crm_*` |
+| Товарная база (1С) | внешняя база товаров/остатков | `besales_datasource_*` |
+| Проверка | прогон учебных диалогов, разбор слабых мест | `besales_sandbox_run_start`, `besales_*_findings_*` |
+| Сравнение моделей | «соревнование» моделей на твоём промпте | `besales_model_*` |
+| Файлы/таблицы | загрузка файлов, чтение Excel/Sheets | `besales_file_*`, `besales_workbook_*` |
+| Напоминания/фидбэк | догоны клиентам, замечания из Google-листа | `besales_followup_sequence_upsert`, `besales_feedback_sheet_*` |
+| Откат/копирование | откатить правку, скопировать на другой канал | `besales_audit_revert`, `besales_platform_clone_*` |
+
+---
+
+## 10. Справочники, которые он читает сам
+
+Помощник держит внутри пошаговые инструкции и подтягивает их по ходу. Тебе — чтобы
+понимать, откуда у него знания (а если ты агент — что и когда открывать).
+
+| Справочник | Когда нужен |
+|---|---|
+| «Настройка с нуля» | полный путь от пустого пространства до запуска |
+| «Подключение CRM» | где взять доступ, какие права, как активировать |
+| «Подключение 1С» | подключение товарной базы |
+| «Улучшение через проверки» | как итеративно доводить бота на учебных диалогах |
+| «Сравнение моделей» | как устроить «соревнование» моделей |
+| «Готовность к запуску» | финальная проверка перед боем |
+| «Анатомия промпта» и «Принципы общения» | **перед тем как писать или править промпт** (ограничения + как звучать по-человечески + как продавать) |
+| Разборы реальных диалогов (по темам) | первое касание, выявление потребности, цена и возражения, передача оператору, догоны, «как не звучать роботом», тон |
+
+---
+
+## 11. Безопасность и необратимые действия
+
+- **Пароли и токены — только в браузере по ссылке от помощника, никогда в чат.** Если
+  он вдруг просит вставить секрет прямо в переписку — **не делай этого**, это ошибка.
+- **Доступ помощника ограничен правами ключа.** Серьёзные изменения (правка ботов,
+  действий, настроек) требуют ключа с правами на настройку — обычного доступа на чтение
+  для них недостаточно.
+- **Перед необратимым — подтверждение:**
+  - Удалить бота-платформу через помощника **нельзя** (только вручную в кабинете).
+  - Удаление действий/воронок/переменных/документов — явное «да».
+  - Копирование «поверх» существующего — **двойное** подтверждение.
+- **Откат.** Многие правки можно откатить (помощник умеет «вернуть как было»). Но
+  удаление и полная замена набора действий **автоматически не откатываются** — система
+  сохраняет «снимок до» для ручного восстановления, но не возвращает сама. Поэтому перед
+  удалением читай, что именно удаляешь.
+
+---
+
+## 12. Если что-то идёт не так
+
+| Что видишь | Что сделать |
+|---|---|
+| «Не вижу такого инструмента» (чаще в Codex) | Скажи: «поищи нужный инструмент Besales и сделай». Обычно срабатывает. Проверить, что система отдаёт всё: `codex mcp list/get besales`. |
+| Просит ID / номер рабочего пространства | Не давай. Скажи: «используй моё рабочее пространство». Если совсем не находит — повтори вход: `npx -y @besales/mcp connect`. |
+| Завис на «ожидании» при подключении канала/CRM | Скорее всего не довёл до конца ввод секрета в браузере. Открой присланную ссылку и заверши. |
+| «Данные неверные» при подключении | Токен/доступ неправильный — помощник покажет, что не так; начни подключение заново. |
+| «Срок ссылки истёк» | Просто попроси начать подключение заново. |
+| Помощник строит бота, а канал ещё не готов | Это нарушение порядка — останови; дождись готовности канала (это единственное твёрдое правило). |
+| Бот звучит как робот, повторяется, сливается после «нет» | Скажи прямо: «бот звучит роботом, поправь» — помощник умеет это чинить и перепроверять. |
+| Бот не находит ответ из твоих материалов | Скажи: «проверь, что база знаний привязана к каналу, и переиндексируй». |
+
+---
+
+## 13. Чеклист «бот с нуля»
+
+```
+[ ] Подключил помощника + вошёл (npx -y @besales/mcp connect, проверка: status)
+[ ] Канал подключён и готов (секрет введён в браузере)
+[ ] Занесена инфо о компании + портрет клиента (для продаж — обязательно)
+[ ] Готов сценарий разговора (реальные фразы менеджеров) + учебные ситуации
+[ ] Создан бот, написан промпт, задано приветствие, прогнан на учебных диалогах
+[ ] Загружена база знаний (и привязана к каналу!) + настроены поведение и действия
+[ ] Настроена CRM-воронка + операторы + напоминания клиентам + настройки канала
+[ ] Финальная проверка готовности к запуску
+```
+
+> На открытый запрос «настрой бота под наш бизнес» помощник сам пройдёт по этому пути и
+> будет проговаривать, на каком шаге вы находитесь.
+
+---
+
+## 14. Словарик понятных слов
+
+| Слово | Что значит простыми словами |
+|---|---|
+| Канал | где бот общается с клиентами (Telegram, WhatsApp, сайт, Avito …) |
+| Рабочее пространство | твой «кабинет» в системе, где живут боты и настройки |
+| Промпт | текст-инструкция, задающий характер и поведение бота |
+| Портрет клиента (ICP) | кого продаём: боли, возражения, как клиент говорит |
+| База знаний | твои материалы (прайс, FAQ, описания), по которым бот отвечает |
+| Воронка | этапы сделки в CRM, по которым двигается клиент |
+| Учебные диалоги (песочница) | проверка бота на придуманных ситуациях, без реальных клиентов |
+| Напоминания (follow-up) | автосообщения клиентам, которые перестали отвечать |
+| Токен / доступ | «ключ-пароль» от канала или CRM — вводится только в браузере |
+| Действие/триггер бота | «если случилось X — сделай Y» внутри сценария бота |

package/docs/agent-usage-guide.ru.md

@@ -0,0 +1,139 @@
+# Как пользоваться помощником Besales — простыми словами
+
+> Этот гайд — для обычного человека, **не программиста**.
+>
+> Помощник Besales — это как толковый сотрудник, которому ты **словами** говоришь, что
+> нужно сделать с твоим чат-ботом, а он делает. Команды и код знать не нужно —
+> достаточно понятно объяснить задачу.
+
+---
+
+## Что это и зачем
+
+У тебя есть (или будет) AI-бот, который общается с клиентами — в Telegram, WhatsApp,
+на сайте, в Avito и т.д. Чтобы его настроить — обучить, подключить к каналам, дать ему
+базу знаний, связать с CRM — обычно нужен программист.
+
+**Помощник заменяет эту рутину.** Ты открываешь Claude Code или Codex, пишешь задачу
+обычными словами — и он сам делает все настройки. Думай о нём как об ассистенте: ты —
+заказчик, он — исполнитель.
+
+---
+
+## Что он умеет (по-человечески)
+
+- Подключить бота к каналу: Telegram, WhatsApp, сайт, Avito, ВКонтакте и др.
+- «Обучить» бота на твоих материалах: прайс, ответы на частые вопросы, описания
+  товаров, записи звонков с клиентами.
+- Написать и улучшить «характер» и сценарий разговора бота — чтобы звучал как живой
+  человек и доводил клиента до покупки.
+- Связать бота с CRM (AmoCRM, Bitrix24 и др.) — чтобы он вёл сделки и контакты.
+- Настроить автоматические действия («если клиент спросил про цену — …»).
+- Проверить бота на учебных диалогах и показать, где он отвечает слабо.
+- Настроить напоминания клиентам, которые перестали отвечать.
+
+---
+
+## Разовая настройка (один раз, ~5 минут)
+
+> Если не дружишь с терминалом — **попроси технического коллегу**, это буквально пара
+> команд. Дальше терминал больше не нужен — только чат.
+
+**Шаг 1.** Подключи помощника — смотря чем пользуешься:
+
+Claude Code:
+```
+claude mcp add --scope user -- besales npx -y @besales/mcp
+```
+
+Codex:
+```
+codex mcp add besales -- npx -y @besales/mcp
+```
+
+**Шаг 2.** Один раз «представься» системе — откроется браузер, войдёшь под своим
+аккаунтом и выберешь рабочее пространство:
+```
+npx -y @besales/mcp connect
+```
+
+Всё. Дальше просто открываешь чат и пишешь задачи словами.
+
+---
+
+## Как с ним разговаривать (самое важное)
+
+Просто опиши, что нужно — как живому человеку. Не нужно знать названий кнопок,
+инструментов или команд: он сам во всём разберётся.
+
+**Хорошие примеры:**
+- «Настрой Telegram-бота для продажи косметики. Вот информация о компании: …»
+- «Добавь этот прайс и ответы на частые вопросы в знания бота» (приложи файл или ссылку)
+- «Сделай, чтобы бот не звучал как робот и не сдавался после первого “нет”»
+- «Поменяй у бота сценарий поиска товара — пусть сначала ищет по артикулу»
+- «Проверь бота на учебных диалогах и покажи слабые места»
+- «Подключи AmoCRM и настрой воронку продаж»
+
+**Не нужно:**
+- Писать команды или технические названия — хватает обычных слов.
+- Присылать какие-то ID или номера рабочего пространства — он уже знает, какое твоё
+  (выбрал при настройке).
+- Вводить пароли и токены прямо в чат (об этом ниже — это важно).
+
+---
+
+## Что будет происходить
+
+Помощник работает примерно так:
+
+1. **Сначала осмотрится** — посмотрит, что у тебя уже настроено, чтобы не делать
+   лишнего.
+2. **Будет вести тебя по шагам** и коротко говорить: «сейчас сделали то-то, дальше —
+   то-то».
+3. **Когда понадобится секрет** (пароль или токен от канала / от CRM) — он **не
+   спросит его в чате**, а пришлёт ссылку. Ты откроешь её в браузере и введёшь там.
+   Так безопаснее.
+4. **Перед чем-то необратимым** (например, удалить настройку) — спросит подтверждение.
+5. **По ходу будет сам проверять бота** на учебных диалогах и показывать результат.
+
+Если задача большая («настрой мне бота под наш бизнес») — он сам разобьёт её на шаги и
+проведёт тебя от начала до запуска.
+
+---
+
+## Важно про безопасность
+
+- **Пароли и токены вводи только в браузере по ссылке от помощника — не в чат.** Если
+  он вдруг попросит вставить пароль прямо в переписку, **не делай этого** — это ошибка.
+- Перед удалением или перезаписью он спрашивает подтверждение — прочитай, что именно
+  удаляется, прежде чем согласиться.
+
+---
+
+## Если что-то пошло не так
+
+| Что видишь | Что сделать |
+|---|---|
+| «Не вижу такого инструмента» (чаще в Codex) | Скажи: «поищи нужный инструмент Besales и сделай». Обычно после этого срабатывает. |
+| Просит ID / номер рабочего пространства | Не давай. Скажи: «используй моё рабочее пространство». Если совсем не находит — повтори настройку: `npx -y @besales/mcp connect`. |
+| Завис на «ожидании» при подключении канала или CRM | Скорее всего ты не довёл до конца ввод пароля в браузере. Открой присланную ссылку и заверши. |
+| «Срок ссылки истёк» | Просто попроси начать подключение заново. |
+| Бот звучит как робот, повторяется, сливается после «нет» | Скажи об этом прямо: «бот звучит роботом, поправь». Помощник умеет это чинить и перепроверять. |
+| Бот не находит ответ из твоих материалов | Скажи: «проверь, что база знаний привязана к каналу, и переиндексируй». |
+
+---
+
+## Шпаргалка: готовые фразы (копируй и меняй под себя)
+
+- «Настрой **<канал>**-бота для **<чем занимаемся>**. Информация о компании: **<…>**.
+  Примеры наших диалогов с клиентами: **<ссылка или файл>**.»
+- «Добавь в знания бота: **<файл или ссылка>**. И привяжи к каналу.»
+- «Поправь характер бота: **<что не нравится>**.»
+- «Подключи **<CRM>** и настрой воронку.»
+- «Проверь бота на учебных диалогах и покажи, где он отвечает плохо.»
+- «Настрой напоминания клиентам, которые перестали отвечать.»
+
+---
+
+> **Коротко:** подключил один раз → открыл чат → пишешь задачи обычными словами →
+> помощник всё делает сам, а пароли ты вводишь только в браузере. Всё.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@besales/mcp",
-  "version": "0.14.0",
+  "version": "0.18.0",
   "description": "Model Context Protocol server for Animaly / Besales",
   "license": "MIT",
   "homepage": "https://github.com/be-sales/mcp#readme",