ai-hub-open/vk-ads-manager

SKILL.md

---
name: vk-ads-manager
description: Полный lifecycle для VK Рекламы (ads.vk.ru) — от стратегии и медиаплана до запуска через API и работы с активной кампанией. Включает воронку подготовки (бриф → конкуренты по 4 кругам с заменителями «снизу» → персоны → аудитории → семантика → УТП по сегментам → прогноз с гейтом маркетолога → структура → креативы → залив) и lifecycle (мониторинг, бюджет, пауза, lookalike, оптимизация). Используй когда пользователь хочет запустить таргет в VK Рекламе / VK Ads / ВКонтакте, собрать медиаплан или стратегию, проанализировать конкурентов, проработать аудитории и УТП, составить объявления, спрогнозировать охваты/лиды/CPL, собрать отчёт для агентства — а также «как у нас в VK», «отчёт по VK», «увеличь бюджет VK», «пауза VK», «запусти кампанию VK», «добавь lookalike», «оптимизация VK», «прошла неделя что доработать». Триггерится и на обобщённое «таргет», «таргетированная реклама», «реклама в соцсетях» для русскоязычных продуктов. Работает на русском языке.
---

# VK Ads Funnel — полный lifecycle

Скилл проводит как через 10-шаговую воронку подготовки кампании в VK Рекламе (ads.vk.ru), так и через повседневную работу с уже существующей кампанией. На максимуме автоматизации, который позволяет среда: сам ищет конкурентов в интернете, читает лендинги, генерит persona, проектирует структуру аудиторий и креативы. Пользователь — source of truth и редактор, не оператор. Что скилл требует от среды и что делает, когда способности нет, — в разделе «Что нужно от среды» ниже.

С января 2026 года старый кабинет ВКонтакте (vk.com/ads) и myTarget закрыты для создания новых кампаний — всё ведётся через единый кабинет VK Реклама (ads.vk.ru), который покрывает VK, OK, Дзен, Mail и проекты VK. Этот скилл — только про новый кабинет.

## ⚠️ Терминология VK Ads API (важно знать)

API использует legacy myTarget имена. В новом UI ads.vk.ru они означают **другое**:

| UI термин | API термин |
|---|---|
| **Кампания** (top-level контейнер) | `ad_plan` |
| **Группа объявлений** | `campaign` |
| **Объявление** | `banner` |

**🚨 Главный gotcha:** `campaign` (= группа объявлений) без `ad_plan_id` создаётся, но становится **orphan** — невидим в новом UI. Всегда создавать ad_plan с nested campaigns атомарно, или указывать существующий `ad_plan_id`.

В диалоге с пользователем используй UI-термины («Кампания / Группа / Объявление»). В API-вызовах и логах — `ad_plan / campaign / banner`. См. `references/vk-ads-mcp-integration.md` для полной таблицы.

## Что нужно от среды

**Обязательный минимум — две способности:**

- **Чтение и запись файлов** в рабочей папке `<outputs>/vk-campaign-<slug>/`. Каждый шаг порождает артефакт, следующий шаг его читает.
- **Диалог с пользователем** — задать вопрос, получить ответ, дождаться подтверждения. Пользователь здесь source of truth и редактор: без диалога не работают гейты (согласование списка конкурентов, прогноз, креативы).

Больше ничего обязательного нет. Всё ниже — **необязательно**: без любой из этих способностей скилл доходит до конца, но часть работы уходит человеку, а часть данных недобрана.

**Необязательные способности.** У каждой есть ветка «если нет». Идёшь по ветке — **печатаешь пометку о пропуске** в артефакт этого шага (формат ниже).

| Способность | Где нужна | Если нет |
|---|---|---|
| **Запуск кода** — Python 3.10+ и команды оболочки | Почти везде: `scripts/*` — прогноз, xlsx, картинки M1, видео M2, PDF M3, залив M4, ключи, пиксель, отчёт | Отдай команду пользователю текстом, попроси прислать вывод и работай с ним как со своим. Не может и он: прогноз Шага 9.5 считай вручную по `references/forecasting.md`; таблицу объявлений отдай Markdown-таблицей вместо xlsx; M1/M2/M3 пропускаются целиком (см. их ветки); залив идёт путём A (MCP) или ручным гайдом, который ты пишешь сам. **Теряется:** валидация лимитов и юр.чистоты из `generate_ads_xlsx`, все генераторы медиа и автоматический залив по REST. |
| **Вызов MCP-инструментов** (хостовый сервер `vk-ads`, aihub.click.ru) | Шаг 0.5 (аудит аккаунта), Шаг 9.5 (фактические CPM/CTR), Шаг 11 путь A | Путь B — наш REST через `scripts/deploy_campaign.py`; нет и запуска кода — путь C, ручной залив в кабинете. Фактические CPM/CTR из кабинета не получить: в прогнозе они остаются `benchmark`. **Теряется:** автоматический залив и живые данные аккаунта. |
| **Сетевые вызовы внешних API по ключу** — VK Ads, OpenAI, Replicate/Runway | Шаг 11 путь B, модули M1 (картинки), M2 (видео), M3 (PDF) | Залив — путь C, ручной. M1/M2 — визуал заказывается у дизайнера по ТЗ, которое ты пишешь текстом. **Теряется:** готовые креативы; Шаг 10 отдаётся с описаниями визуала вместо файлов, и это блокер запуска, а не косметика. |
| **Поиск в интернете** | Шаги 3, 4, 7 — конкуренты и их реклама | Спроси у клиента прямо: «с кем вас сравнивают, что говорят при отказе»; попроси 3–5 скриншотов рекламы конкурентов из ленты VK; возьми список из брифа. Четыре круга заполняются со слов, тег `source-trust: client`. **Теряется:** широкая корзина кандидатов и круг «заменители снизу», которых клиент сам не называет — а они часто крупнейшие по объёму. |
| **Чтение веб-страниц по URL** | Шаги 1, 2, 4, 9 — лендинг и сайты конкурентов | Спроси у пользователя 5 пунктов словами: H1, бенефиты, CTA, цена/триал, доказательная база. Чек-лист посадочной Шага 9 пройди вопросами к пользователю, а не сам. **Теряется:** сверка обещания в креативе с тем, что реально на лендинге — прямая причина слитого бюджета. |
| **Показ файлов пользователю** — превью, ссылки на файлы | Шаги 10.5–10.7, 11, 12 | Перечисли пути к файлам от корня рабочей папки и скажи, что открыть. **Теряется:** быстрый визуальный ревью креативов. |

**Дочерних агентов этот пакет не требует** — все шаги выполняются в основном контексте.

**Названия инструментов в тексте ниже — примеры.** Где встречаются `mcp__workspace__bash`, `mcp__vk-ads__*`, `WebSearch`, `WebFetch`, `computer://`-ссылки — это имена из одной конкретной среды, приведённые для наглядности. Ориентируйся на **способность**, а не на имя: если инструмент называется иначе, но делает то же — используй его.

### Пометка о пропуске

Шаг выполнен без необязательной способности — впиши в артефакт этого шага строку такого вида:

> ⚠️ **пропущено: нет `<способность или источник данных>`** — `<что сделал вместо>`. Потеряно: `<что именно недобрано>`. Как добрать: `<что сделать человеку>`.

Например:

> ⚠️ **пропущено: нет поиска в интернете** — список конкурентов собран со слов клиента, 4 кандидата вместо 10–20. Потеряно: круг «заменители снизу» (Excel, руки, ассистент). Как добрать: поискать «как вести <задачу> в Excel» и вернуться на Шаг 3.

Пометки складываются в **обязательный раздел «Пропущено из-за среды»** в `launch_log.md` и в сводный отчёт Шага 12. Пропусков не было — напиши «пропусков нет». Пользователь должен видеть, где данные недобраны, а не получать молча упрощённый результат.

## ⚠️ Как работаем: пользователь не оператор

Скилл рассчитан на **не-технического пользователя**. Правила ниже действуют, **когда нужные способности из таблицы есть**:

- ✅ **Скрипты запускаешь сам** инструментом запуска кода (например, `mcp__workspace__bash`). Пользователь не открывает терминал.
- ✅ **Результаты собираешь сам** и показываешь превью или итоги в чате.
- ✅ **Ключи API пользователь скидывает в чат** — сохраняй через `manage_credentials.py set <service> --key <KEY>`. Способ Б — дефолт для коллег. Способ А (`getpass` в терминале) — только если пользователь явно скажет «я сам».
- ✅ **Каждый Шаг 1-10 + lifecycle** выполняешь сам, не передаёшь пользователю команды для копи-паста.
- ❌ **Не передавай пользователю команды для терминала**, если можешь выполнить сам. Исключение — в среде нет запуска кода: тогда команду отдаёшь с пояснением, зачем она нужна, и просишь прислать вывод.

**Onboarding нового пользователя (первая встреча):**

1. Проверь установлены ли зависимости — выполни:
   ```
   python -c "import openai, PIL, requests, openpyxl, docx" 2>&1
   ```
   Если ошибка — попроси пользователя один раз запустить `python <skill-path>/install.py` (это идемпотентно, безопасно). **Запуска кода в среде нет** — пропусти проверку: библиотеки нужны только скриптам, а те шаги всё равно пойдут по своим ветками «если нет».

2. Проверь сохранены ли ключи — выполни:
   ```
   python -m scripts.manage_credentials list
   ```
   Если каких-то нужных нет — попросишь когда дойдёшь до шага где они нужны (не заранее всех сразу). **Запуска кода нет** — хранилища ключей нет: спрашивай ключ в тот момент, когда он нужен, и не сохраняй его.

3. **Проверь, есть ли у тебя инструменты MCP-сервера `vk-ads`** (в одной среде они видны как `mcp__vk-ads__*`, в другой имена выглядят иначе — смотри по короткому имени, например `vk_ads_auth_check`). Есть — это primary путь для финального залива (Шаг 11), скажи об этом пользователю. Нет — предложи подключение к **хостовому** серверу через `scripts/setup_vk_ads_mcp.py` (нужны только токен click.ru и ID аккаунта; клонировать репозиторий и ставить Bun не надо). Не блокирующее: без MCP скилл работает через наш REST, а без него — ручным заливом.

4. Спроси что хочет запустить и иди по 10-шаговой воронке.

## Когда триггерится

**Подготовка (10-шаговая воронка):**
- «Запусти таргет в VK» / «нужна VK Реклама» / «сделай РК во ВКонтакте»
- «Подготовь медиаплан под VK Ads»
- «Собери аудитории для VK» / «спроектируй lookalike»
- «Загрузи базу клиентов в VK» / «настрой CRM-аудиторию»
- Любой запрос на запуск таргета в соцсетях для русскоязычного продукта без явного указания канала

**Lifecycle (мониторинг + изменения через API):**
- «Как у нас VK?» / «Что в VK Рекламе?» / «Отчёт по кампании»
- «Daily check» / «Сводка по VK за вчера»
- «Увеличь / сократи бюджет VK»
- «Пауза кампании» / «Запусти снова»
- «Активируй кампанию» / «Включи»
- «Добавь lookalike» / «Сделай похожих»
- «Загрузи новую базу» / «Обнови CRM-аудиторию»
- «Измени текст объявления» / «Поправь заголовок»
- «Добавь интересы» / «Сузь по соцдему»
- «Скопируй кампанию»
- «Оптимизация по VK» / «Прошла неделя что доработать»

Lifecycle-сценарии — **`references/lifecycle-runbook.md`**.

## Главный принцип

**Каждый шаг порождает артефакт.** Рабочая папка: `<outputs>/vk-campaign-<slug>/`. Артефакты пронумерованы (`01_brief.md` ... `10_creatives.md`), плюс `_state.json`, `_account_audit.md` (если есть доступ к API), `_audiences.md`, `_semantics.md`, `_usp.md`, `_forecast.md`, `operations_log.md` (для lifecycle), финальные `ads.xlsx`, `audiences.json`, `creatives.json`.

**Промежуточные артефакты самодостаточны** — каждый можно отдать/показать отдельно: анализ конкурентов (`_competitors.md`), семантика (`_semantics.md`), УТП по сегментам (`_usp.md`), посадочные (`_landings.md`), стратегия (`_strategy.md`), структура кампаний (`_campaign_structure.md`). Финальный Шаг 12 (`scripts/generate_strategy_report.py`) собирает их в `report/` + сводный отчёт для команды агентства.

## Как использовать references

- `references/vk-ads-specs.md` — **обязательно** перед Шагом 10. Лимиты символов по форматам, требования к креативам, дисклеймеры модерации.
- `references/targeting-strategy.md` — **обязательно** перед Шагом 6.5. Методология подбора аудиторий: соцдем + интересы + поведение, кастомные на собственных данных, баланс «алгоритмическое vs ручное» для алгоритмов VK 2026.
- `references/audiences-and-lookalike.md` — **обязательно** перед Шагом 7. Пиксель VK Ads, события, CRM-загрузки (phone/email), lookalike (мин. 1000), стратегии комбинирования.
- `references/competitor-research.md` — шаги 3-4, 7. Четыре круга конкурентов (прямые / непрямые / заменители «снизу» / ничего не делать), расширенный сбор, **гейт согласования списка человеком**, иерархия источников.
- `references/buyer-personas.md` — шаг 6. Структура персон, специфика VK (поведенческая и сообществовая активность).
- `references/ad-copywriting.md` — шаги 5 и 10. **УТП и боли ОТДЕЛЬНО по сегментам** (не смешивать; отдельно «конкуренты снизу»), формулы, **юр.чистота** (нет имён конкурентов в текстах, защита от сравнений «лучше чем X», закон о рекламе), анти-«ни о чём», маркировка ОРД.
- `references/forecasting.md` — **обязательно** перед Шагом 9.5. Откуда берутся охваты/клики/CTR/конверсии/лиды, теги источников (`api`/`client`/`benchmark`/`assumption`), почему лиды/CPL нельзя отдавать без проверки, reality-check, гейт согласования с маркетологом.
- `references/landing-checklist.md` — шаг 9.
- `references/vk-ads-api.md` — REST API endpoints (OAuth2, campaigns, ad_plans, banners, statistics).
- `references/lifecycle-runbook.md` — **обязательно** для всех lifecycle-сценариев. 13 готовых сценариев с проверками безопасности и логированием.
- `references/visual-generation.md` — методология генерации картинок через AI (Шаг 10.5, модуль M1).
- `references/video-generation.md` — методология генерации видео через AI (Шаг 10.6, модуль M2). Провайдер-абстракция Replicate / Runway / Kling / AiSMM / Veo + A/B variants workflow + FFmpeg склейка длинных видео.
- `references/replicate-models.md` — каталог моделей Replicate (Kling, Hunyuan, Seedance, Wan, Hailuo) с input-параметрами и стоимостью. Расширяется при появлении новых SOTA-моделей без переписывания скилла.
- `references/pdf-generation.md` — методология PDF lead magnet (Шаг 10.7, модуль M3). Workflow: Claude пишет markdown в чате → скрипт собирает PDF с обложками от M1.
- `references/credentials.md` — универсальная система API-ключей. **Обязательно перед** любым шагом, требующим API (OpenAI, VK Ads, Runway, Kling и т.д.). Объясняет как спрашивать ключ у пользователя безопасно.
- `references/vk-ads-mcp-integration.md` — **рекомендуемый путь работы с VK Ads API через хостовый MCP-сервер** vk-ads-mcp (45 инструментов, aihub.click.ru). Включает: подключение (Cursor / Claude Code / Claude Desktop), авторизацию через click.ru, список tools, маппинг наших задач на tools, правильную терминологию (`ad_plan` vs `campaign` vs `banner`). **Обязательно прочитать перед Шагом 11** — если MCP-инструменты доступны, идём по ним вместо нашего REST.

### Тематические справочники по разделам VK Рекламы (читать по потребности задачи)

Сверены построчно с официальной справкой ads.vk.com/help; у фактов проставлены слаги-источники. Каждый блок помечен [MCP] (автоматизируемо через API) или [UI] (только в кабинете).

- `references/start-and-launch.md` — процесс запуска: «Быстрый запуск vs Режим эксперта», лимиты объявлений/бюджета, статусы, операции с сущностями, «цель нельзя менять после запуска». Читать, когда вопрос про создание/статусы/лимиты.
- `references/moderation-rules.md` — **читать при написании текстов и креативов** (Шаги 5, 10): полные запрещённые/лицензируемые категории (таблица «категория → документ»), требования к тексту/визуалу, размеры дисклеймеров, 18+, конкурсы, банкротство, крипта. Расширяет краткий блок из `vk-ads-specs.md`.
- `references/ord-agency.md` — **читать для агентских кабинетов**: ОРД-онбординг клиента/договоров, обязательные ежемесячные акты (15-30 числа), сбор 3% (ФЗ-479), статусы ОРД, размеры дисклеймеров. Связан с `preflight_ord()` в API-клиенте.
- `references/lead-forms.md` — при работе с лид-формами: конструктор (типы/лимиты), интеграции CRM, уведомления (нюанс для агентств), визитка, лендинг-прогрев, сплит-тест. API создаёт только объявление-обёртку.
- `references/ecommerce-catalogs.md` — при рекламе товаров: каталоги/фиды (форматы, поля, лимиты), [MCP] события динамического ретаргетинга с `product_id`, группы товаров, макросы `{{product.*}}`, маркетплейсы (Ozon/WB/AliExpress/Яндекс.Маркет), FSA.
- `references/app-promotion.md` — при продвижении мобильных приложений: добавление/подтверждение владения, трекеры/MMP, диплинки, категории событий, «агентский кабинет не может быть владельцем приложения».
- `references/branding-formats.md` — медийные CPM-форматы «Узнаваемость и охват» (аудио, баннерная, HTML5, видео-branding до 180-300 сек, Дзен, ОК, музыка, профили/каналы, премиум, прямые сделки). Спеки тут ДРУГИЕ, не путать с перформанс из `vk-ads-specs.md`.
- `references/mini-ads.md` — [UI-fallback] упрощённый/мобильный кабинет: через MCP не заливается, знание для консультаций (свои цели/лимиты/автоподбор).

## Как использовать scripts

- `scripts/generate_strategy_report.py` — **главный итоговый отчёт для команды агентства**. Собирает `report/strategy_report.md` (+ `.docx` с `--docx`) и отдельные самодостаточные .md-артефакты по блокам (`_competitors.md`, `_semantics.md`, `_usp.md`, `_landings.md`, `_funnels.md`, `_campaign_structure.md`, `_forecast.md`, `_client_requests.md`, `_strategy.md`). Воронки, посадочные/лид-формы и структуру выводит из creatives.json — единый источник со ads.xlsx, не противоречат друг другу. Запускать в самом конце обработки (Шаг 12).
- `scripts/forecast.py` — прогноз по сценариям (минимальный/целевой/расширенный) с тегами источников и reality-check. `--init` создаёт `forecast_inputs.json` (заполнить CPM/CTR из MCP, CR от клиента) → запуск без `--init` собирает `_forecast.md` со статусом согласования. См. `references/forecasting.md`.
- `scripts/generate_media_plan.py` — артефакты → docx (или md фолбек). Технический сборник всех артефактов; для агентства используем `generate_strategy_report.py`.
- `scripts/generate_ads_xlsx.py` — creatives.json → xlsx (или CSV фолбек). Колонки связки (campaign/group/segment/hypothesis/audience_id/funnel_stage/landing). Валидация лимитов VK + юр.чистоты (сравнения, имена конкурентов из `brand.json.competitor_names`, «ни о чём»).
- `scripts/vk_ads_api.py` — REST клиент к VK Ads API (OAuth2, campaigns, banners, audiences, statistics). Для lifecycle и финального залива.
- `scripts/vk_pixel_helper.py` — генерация кода пикселя VK для встраивания на сайт + чек-лист событий.
- `scripts/generate_creative_images.py` (M1) — **генератор картинок** через OpenAI Images API. Читает creatives.json + brand.json → генерит обложки eBook, pain-split, abstract-brand композиции, карусели. См. `references/visual-generation.md`.
- `scripts/prompt_templates.py` — 7 шаблонов промптов для М1 (ebook_cover/preview/cta, pain_split, abstract_brand, carousel_card, ui_mockup).
- `scripts/brand_defaults.json` — defaults бренд-конфига для M1 (переопределяется локальным `brand.json`).
- `scripts/credentials.py` + `scripts/manage_credentials.py` — **универсальная система API-ключей**. Скрипты модулей не привязаны к env-переменным — ключ один раз сохраняется в `~/.vk-ads-manager/credentials.json` через `python -m scripts.manage_credentials set <service>`. См. `references/credentials.md`. Поддерживаемые сервисы: `openai`, `vk_ads`, `runway`, `kling`, `aismm`, `anthropic`.
- `scripts/generate_creative_videos.py` (M2) — **генератор видео** через провайдер-абстракцию (Runway / Kling / AiSMM / Veo). Читает creatives.json, для каждого видео-креатива (format/image_or_video содержат «video») генерит 5-10s MP4 в `assets/videos/`. Дефолт-провайдер `runway` (полностью реализован). Опция `--use-seed-images` использует `assets/images/<name>.png` как первый кадр (image-to-video). См. `references/video-generation.md`.
- `scripts/video_prompt_templates.py` — 3 шаблона видео-промптов (pain_reframe, ugc_testimonial, product_demo).
- `scripts/video_providers/` — провайдер-абстракция: `runway.py`, `kling.py`, `veo.py` (Google AI Studio), `aismm.py` (generic). Все 4 реализованы.
- `scripts/video_concat.py` — FFmpeg-обёртка: склейка сегментов в длинное видео, извлечение последнего кадра (для chain-segments), overlay-текст. CLI: `python -m scripts.video_concat {check,concat,last-frame,overlay-text}`.
- `scripts/video_providers/replicate.py` — **рекомендуемый дефолт для тестирования и гибкости**. Универсальный провайдер: один ключ Replicate → доступ к десяткам видео-моделей (Kling, Hunyuan, Seedance, Wan, Hailuo, Veo). Модель задаётся через `--model <slug>`. См. `references/replicate-models.md` для каталога.
- `scripts/deploy_campaign.py` (M4) — **end-to-end залив в кабинет VK Реклама**. Читает creatives.json + audiences.json + assets/images/ + assets/videos/, загружает медиа, создаёт ad_plan + campaigns + banners — всё в `status=blocked`. Никогда не активирует — это делает пользователь через UI после прохождения Сценария 10.
- `scripts/generate_lead_magnet_pdfs.py` (M3) — **генератор PDF lead magnet** для eBook-креативов. Читает markdown из `assets/pdf_content/<creative>.md` (создаёт Claude в диалоге с пользователем), собирает в PDF через ReportLab, использует обложки от M1 если есть. См. `references/pdf-generation.md`.
- `scripts/pdf_builder.py` — низкоуровневый ReportLab builder (обложка/тело markdown/CTA).
- `scripts/package_skill.py` — упаковщик скилла в `.skill` файл для распространения. Запуск: `python -m scripts.package_skill` или двойной клик `package.bat` (Windows) / `./package.sh` (Unix). Исключает `evals/`, `assets/`, рабочие папки кампаний, кэши Python.
- `scripts/generate_launch_guide.py` (M5) — **UI fallback**. Генерирует `LAUNCH_GUIDE.md` (опционально `.docx`) для ручного залива в кабинете ads.vk.ru — все шаги от настройки ОРД до активации, с точными значениями бюджета / таргетинга / текстов баннеров. Использовать когда у клиента нет API доступа.
- `scripts/setup_vk_ads_mcp.py` — **подключает хостовый vk-ads-mcp** (https://vkads-mcp.aihub.click.ru/mcp, 45 инструментов) к Cursor / Claude Code / Claude Desktop: токен click.ru + ID аккаунта, `--target`, `--dry-run`, `--remove`. Клонировать репозиторий и ставить Bun не нужно. Требует запуска кода; без него — конфиг пишет человек по `docs/hosted-mcp-setup.md`. Путь через MCP — **primary** для Шага 11 (приоритет над нашим REST). См. `references/vk-ads-mcp-integration.md`.

---

# Workflow подготовки: 10 шагов

## Шаг 0. Подготовка

1. Имя продукта (1-2 слова) для slug.
2. Создай `vk-campaign-<slug>/`, в ней `_state.json` с `"current_step": 1`.

## Шаг 0.5. Аудит API-доступа (опциональный)

Если подключён MCP `vk-ads` — аудит делается через него: `vk_ads_auth_check` → `vk_ads_account_info` → `vk_ads_ad_plans_list`. Если MCP нет, но у пользователя есть токен VK Ads API — попроси выполнить read-only вызов `GET /api/v2/campaigns.json` через `scripts/vk_ads_api.py audit`. Запиши `_account_audit.md`: всего/активных/на паузе кампаний, имена, бюджеты, цели. Пометь семантически близкие.

Покажи: «Вижу N кампаний, K похожи. Учитываем при подборе аудиторий и прогнозе CPL?»

В `_state.json`: `"api_available": true|false, "similar_campaign_ids": [...]`.

Если ни MCP, ни токена нет — пользователь работает руками в UI ads.vk.ru, скилл всё равно полезен, просто финальный залив будет через UI (см. Шаг 11).

## Шаг 1. Продуктовый бриф

Спроси одним блоком:
1. Что продаёте (в одной фразе)
2. Сайт/лендинг
3. Цена (сумма или диапазон, подписка/разовая)
4. **Тип товара** — массовый ширпотреб / премиум / B2B / локальный сервис / SaaS / инфопродукт
5. **Тип спроса** — горячий (уже ищут) / тёплый (знают о проблеме) / холодный (нужно создавать осознание). В VK работают **все три**, но стратегия аудиторий разная.
6. **Уровень бренда** — известный или новый
7. География
8. **Целевая аудитория «в одном предложении»** (для проверки на шаге 6)
9. Метрика успеха + LTV/чек
10. **Целевой CPL** — минимально приемлемый и потолок. В VK CPL зависит от категории: от 100-300 ₽ (массовка) до 2000-5000 ₽ (B2B/услуги).
11. **Бюджет на тест** — общая сумма + срок. В VK минимум для адекватного теста — 30-50 тыс ₽ на 2 недели. Меньше — алгоритм не успеет выйти из обучения (нужно 50+ событий целевого действия).
12. **Цель кампании в VK** (см. `references/targeting-strategy.md`): подписчики сообщества, охват и вовлечение, лиды (форма VK), сайт+конверсии, посещения магазина. Алгоритмы VK оптимизируют **на уровне кампании** — смешивать цели нельзя.
13. **Пиксель установлен? События настроены?** Без него — нет lookalike по посетителям, нет оптимизации на конверсии, нет ретаргета.
14. Срок запуска

Прочитай лендинг инструментом чтения веб-страниц (например, `WebFetch`). **Если такого инструмента в среде нет или страница заблокирована** — спроси 5 пунктов у юзера: H1, бенефиты, CTA, цена/триал, доказательная база. Пометь, что данные со слов, и впиши в `01_brief.md`: «пропущено: нет чтения веб-страниц — данные о продукте со слов клиента, с лендингом не сверены».

**Артефакт:** `01_brief.md`. **Гейт:** «Идём дальше?»

## Шаг 2. Сбор визуала

VK Реклама визуально-первичная — карточки в ленте, видео в клипах, креативы в universal. Сразу собери:
- Логотип в высоком разрешении
- 5-10 скриншотов главных блоков лендинга
- Фото продукта в использовании
- Брендовые цвета (HEX)
- Уже снятые видео / отзывы клиентов (если есть)

Читаем страницы сайта (например, `WebFetch`); нет такой возможности — просим ссылки напрямую у пользователя. ⚠️ **Ссылки на изображения запрашивай сразу по правилам из `references/vk-ads-specs.md` → «Требования к ссылкам на изображения от клиента»** (там же готовый шаблон запроса). Ссылка, не отвечающая правилам, не загрузится на Шаге 11 — а к тому моменту переделывать поздно. Каждую полученную ссылку прогоняй через пре-флайт (см. Шаг 11) в момент получения, а не перед заливом. **Артефакт:** `02_visual.md` со ссылками или встроенными фрагментами + явный список **чего не хватает** (визуал — частый блокер на Шаге 10). Собрано только со слов — пометь пропуск: список «чего не хватает» в этом случае неполный.

## Шаг 3. Поиск конкурентов (+ гейт согласования списка)

**Прочитай `references/competitor-research.md`.** Собираем не только прямых — а **четыре круга**, и каждый помечаем типом:

1. **Прямые / ближайшие** (`direct`) — тот же продукт, та же ЦА.
2. **Непрямые** (`indirect`) — другой продукт, та же боль.
3. **Заменители / «конкуренты снизу»** (`substitute`) — способ обойтись без покупки: Excel, руки, ассистент, «ведём в Telegram». Если продаёте CRM — конкурент снизу это **Excel-таблица**. Почти всегда существует и часто крупнейший по объёму.
4. **Ничего не делать** (`do_nothing`) — боль не осознана.

Собери широкую корзину 10-20 кандидатов поиском в интернете (например, `WebSearch`): по транзакционным запросам И по запросам про заменители «как вести Y в Excel»; `vk.com/search`; каталоги; отзовики и подборки «альтернативы X». Плюс всегда спроси клиента: «с кем вас сравнивают / что говорят при отказе».

**Если поиска в интернете в среде нет** — корзина собирается только со слов клиента и из брифа: спроси про сравнения и отказы, попроси назвать 3–5 конкурентов, а круг «заменители снизу» вытяни вопросом «а как эту задачу решают те, кто ничего не покупает?». Все кандидаты помечаются `source-trust: client`. В `03_competitors.md` — пометка: «пропущено: нет поиска в интернете — корзина собрана со слов клиента, N кандидатов вместо 10–20. Потеряно: заменители и непрямые конкуренты, которых клиент не назвал. Как добрать: поискать транзакционные запросы и «как вести <задачу> в Excel» руками». На гейте скажи это словами — пользователь должен понимать, что согласовывает неполный список.

**🚦 Гейт:** покажи таблицу-кандидатов (название · тип · почему в списке) и спроси: «Кого глубоко анализируем, кого убрать, кого добавить?» Без подтверждения списка Шаг 4 не начинаем.

**Артефакт:** `03_competitors.md` — кандидаты с типом и пометкой «согласовано / на согласовании».

## Шаг 4. Анализ конкурентов

Читаем сайты топ-5 (инструмент чтения веб-страниц, например `WebFetch`). **Нечем читать** — разбор строится на том, что знает клиент, плюс на скриншотах, которые он пришлёт; пункты, которые так не добываются (цены, Tone of Voice), помечай `n/a`, а не догадкой, и ставь пропуск в `04_competitors_deep.md`. Для каждого:
- Офер (H1)
- УТП
- Цены
- ЦА (по позиционированию)
- Tone of Voice
- CTA
- Доказательная база (отзывы, сертификаты)
- **VK-сообщество**: размер, активность, частота постов, формат контента, наличие виджетов (лид-форма, товары)

Разбери **отдельно ближайших** (direct) и **отдельно остальные релевантные** (indirect + substitute): у заменителя нет лендинга/сообщества — вместо этого опиши «чем человек пользуется сейчас», что в этом плохо (боль), что его держит. Это вход для УТП-сегмента «конкуренты снизу» (Шаг 5).

**Артефакт:** `04_competitor_analysis.md` (каждый блок с типом). Это и есть самодостаточный `_competitors.md` для отдельной выдачи — Шаг 12 скопирует его в `report/`.

## Шаг 5. Свой смысл

Покажи саммари конкурентов и не-закрытые ниши. 2-3 вопроса, 3 варианта позиционирования. **Артефакт:** `05_positioning.md` — главное обещание + УТП + антипозиционирование.

**Особое внимание к УТП.** УТП ≠ «качество и индивидуальный подход». УТП = то, чем отличаемся от **всех** конкурентов из шага 4. См. `ad-copywriting.md` секции 0 и 0.5.

**УТП и боли — ОТДЕЛЬНО по каждому сегменту, не смешивать.** Сегмент задаётся тем, **с чем человек сравнивает нас сейчас** (его текущая альтернатива): против прямых (amoCRM), против непрямых, **«конкуренты снизу»** (Excel/руки/ничего), ничего-не-делать. У каждого — своя боль и своё УТП. Сегмент «снизу» прорабатывай отдельно и тщательно: его сообщение («хватит терять заявки в Excel») нельзя класть в одно объявление с отстройкой от amoCRM — это другой человек.

Если на сайте нет УТП и в шагах 1-4 не нашлось — **не выдумывай**. Спроси юзера прямо: «У продукта нет явного УТП на сайте. Может быть в продукте есть что-то уникальное? Менеджеры рассказывают клиентам что-то особенное?»

**Артефакты:** `05_positioning.md` (главное обещание + антипозиционирование) и **`_usp.md`** — по блоку на сегмент: текущая альтернатива → боли (3-5) → УТП → чего НЕ говорим. Каркас — в `ad-copywriting.md` секция 0.5.

**Гейт:** явное согласие на позиционирование и на разбивку по сегментам.

## Шаг 6. Buyer Personas

3-5 персон. Для каждой:
- Демография (возраст, пол, доход, образование, семейное положение, география)
- **Поведение в VK**: какие сообщества читает, какие интересы по соцграфу, частые активности
- JTBD (job to be done)
- Боли
- Возражения
- Триггеры покупки
- **5-10 точных гипотез аудиторий** (это гипотезы, не финальные настройки)

**Если API доступен** — посмотри, что уже есть: `vk_ads_remarketing_segments_list` (сегменты)
и `vk_ads_users_lists_list` (загруженные CRM-базы). Через наш REST — `vk_ads_api.py audiences-list`.
Не дублируй уже залитые. См. `references/audiences-and-lookalike.md`.

**Артефакт:** `06_personas.md` — для каждой персоны блок «Гипотезы аудиторий».

## Шаг 6.5. Архитектура аудиторий — матрица сегментации

**Это критичный шаг.** Без него на Шаге 10 структура групп объявлений будет хаотичная. Прочитай **`references/targeting-strategy.md`** и **`references/audiences-and-lookalike.md`** до начала.

**Цель:** превратить гипотезы из персон в **матрицу аудиторий**, которая ляжет в основу структуры групп объявлений (1 аудитория ≈ 1 группа).

**Как:**

1. **Сегменты по холодности (вертикальная ось):**
   - Hot — те, кто уже взаимодействовал (посетители сайта, текущая база CRM, аудитория сообщества)
   - Warm — lookalike по горячим / по тематическим интересам и сообществам
   - Cold — широкий соцдем + интересы / посевы по сообществам конкурентов

2. **Сегменты по персоне (горизонтальная ось):**
   - P1, P2, P3 из Шага 6

3. **Заполни матрицу.** Не каждая клетка обязательна — фокус на 4-6 ячейках с самой сильной гипотезой.

| Сегмент / Персона | P1 SMM-фрилансер | P2 Эксперт | P3 Блогер |
|---|---|---|---|
| Hot (посетители + база) | LAL 1% от посетителей-фрилансеров | LAL 1% от экспертов-клиентов | — |
| Warm (LAL + интересы) | Интерес «SMM», сообщества SMM-планнера | Интерес «инфобиз», аудитория курсов | Интерес «съёмка контента» |
| Cold (соцдем + широкие интересы) | 25-40, маркетинг/SMM в графе | 30-50, образование/экспертиза | 18-35, креативные индустрии |

4. **Для каждой ячейки запиши:**
   - Тип аудитории VK (LAL, intent, custom, key phrases, retargeting)
   - Размер (примерный)
   - Источник данных (если custom — какая база; если LAL — от чего)
   - Географию — **названия городов/регионов словами**; числовые `region_id` для API резолвишь позже через `vk_ads_regions_search` (Шаг 11) и фиксируешь маппинг в `_state.json`

5. **Покажи матрицу пользователю.** Очень важная точка контроля.

**Артефакт:** `_audiences.md` + новая секция в `06_personas.md`:

```markdown
## Матрица аудиторий

### Hot ячейки (3-7 дней атрибуции)
- A1: LAL 1% от посетителей лендинга (нужен пиксель + 1000+ событий)
- A2: CRM-список существующих платных клиентов (csv с phone/email, мин 1000)

### Warm ячейки
- W1: P1 — интерес «SMM и маркетинг» + ключи «контент-план», «smm специалист»
- W2: P2 — сообщества крупных образовательных платформ (список ID через UI)

### Cold ячейки
- C1: P1 — соцдем 25-40, занятость = маркетинг/SMM в профиле, gender = ж 70%
- C2: P3 — соцдем 18-35, интерес «фотография и видео» + «креатив»
```

**Гейт:** покажи матрицу, спроси «всё верно? Где-то размер слишком мал / слишком велик?». Без явного подтверждения — Шаг 10 не начинай.

**Семантика (только для горячих ячеек).** В VK «семантика» = ключевые фразы (что человек искал в VK/Mail), это **один тип таргетинга**, а не парсинг ядра как в Директе. 15-40 точных фраз на горячий сегмент — потолок. Имена конкурентов живут **здесь** (ключевые фразы / таргет на их сообщества), но **никогда в текстах объявлений** (см. `ad-copywriting.md`). Минус-слов нет — есть исключения интересов/сообществ. Оформи отдельным самодостаточным артефактом **`_semantics.md`** (каркас — в `targeting-strategy.md`, секция «Семантика в VK»).

**Особое внимание:**
- **Hot нужен пиксель** — если его нет, переходим к Шагу 7а.
- **CRM-загрузки** — минимум 1000 записей после матчинга, лучше 5000+.
- **LAL** — минимум 1000 совпавших пользователей в источнике.

## Шаг 7. Реклама конкурентов

Поиск в интернете не отдаёт креативы VK дословно. Иерархия источников:

1. **Скриншоты от пользователя** — золотой стандарт. Запроси 3-5 скриншотов рекламы в ленте VK по горячим темам.
2. **adheart.ru / publer / target hunter** если подписка.
3. **Реконструкция** через поиск в интернете (например, `WebSearch`) + ленты сообществ конкурентов. Тег `source-trust: reconstruction`.

**Если поиска в интернете нет** — остаётся только источник 1: работаем на скриншотах от пользователя. Не прислал — Шаг 7 выполнить нечем: не выдумывай креативы конкурентов. Напиши в `07_competitor_ads.md` пометку «пропущено: нет поиска в интернете и скриншотов от пользователя — реклама конкурентов не собрана. Потеряно: вход для Шага 8 (успешные паттерны). Как добрать: прислать 3–5 скриншотов рекламы в ленте VK», и на Шаге 8 строй паттерны только на брифе и разборе конкурентов Шага 4, честно назвав это гипотезой.

**Артефакт:** `07_competitor_ads.md` с пометкой источника.

## Шаг 7а. Настройка пикселя и событий (опциональный, но критичный)

Запускается если в Шаге 1 пиксель ещё не установлен. Запусти `scripts/vk_pixel_helper.py` — он сгенерит:
- Базовый код пикселя VK Ads (для вставки в `<head>`)
- Чек-лист событий под цели кампании: `page_view`, `lead`, `purchase`, `add_to_cart`, `registration` и т.д.
- Инструкцию: где взять `pixel_id` в кабинете → куда вставить → как проверить (`vk_ads_pixel_check.html`)

**Артефакт:** `07a_pixel_setup.md` с готовым кодом и пошаговой инструкцией.

**Если MCP подключён** — пиксель можно создать не руками: `vk_ads_remarketing_pixels_create(payload={...})`,
затем `vk_ads_remarketing_pixels_list` для проверки и получения `pixel_id`. Установка кода на сайт
и проверка срабатываний всё равно остаются за человеком — API отдаёт факт существования счётчика,
а не поток событий.

**Гейт:** перед запуском кампании пользователь должен подтвердить «пиксель стоит, события ловятся».

## Шаг 8. Успешные паттерны

3-5 повторяющихся паттернов из шага 7. Формулы, не текст. Включая:
- Типы офферов (скидка, дедлайн, гарантия, кейс)
- Структуры заголовков
- Композиции креативов (фото героя, скриншот продукта, видео-демо, UGC-стиль)
- CTA-формулировки

**Артефакт:** `08_patterns.md`.

## Шаг 9. Посадочные

Читаем лендинг (инструмент чтения веб-страниц, например `WebFetch`). Нечем читать или снова заблокирован — пройди чек-лист **вопросами к пользователю** и отметь каждый пункт как «со слов»; пункты, которые словами не проверить (скорость на мобиле по Lighthouse), помечай `не проверено`, а не «ок». Пометка в `09_landings.md`: «пропущено: нет чтения веб-страниц — посадочная проверена со слов, соответствие креатива и H1 не сверено».

Чек-лист (см. `landing-checklist.md`):
- H1 совпадает с обещанием в креативе
- Скорость на мобиле (Lighthouse > 70)
- Форма выше первого скролла
- Доказательства (логотипы клиентов, отзывы)
- Пиксель VK Ads установлен + события настроены
- ОРД-маркировка не требуется на лендинге (она на креативах), но юр.информация в футере обязательна

**География.** VK Реклама использует свои region_ids. Шорт-лист:
- Россия: 0 (весь), 1 (Москва), 2 (СПб), 41 (Краснодарский край), 60 (Свердловская обл.), 78 (Татарстан)
- Города: можно выбрать «город + N км»
- Беларусь: country=br, Казахстан: country=kz
- Если нужен редкий регион — через UI или `dictionaries_regions` API

**Артефакт:** `09_landing.md` + точные **regions** (с ID или названиями). Это и есть самодостаточный `_landings.md`.

## Шаг 9.5. Прогноз и сценарии бюджета (с гейтом маркетолога)

**Обязательно прочитай `references/forecasting.md`.** Это шаг, на котором скилл раньше завышал лиды/CPL. Главное правило: **базовые цифры берём из проверяемых источников, лиды/CPL не отдаём как обещание без согласования.**

Порядок:

1. **Собери базу из кабинета (MCP).** Если есть доступ (инструменты MCP-сервера `vk-ads` — например, с префиксом `mcp__vk-ads__` — либо `api_available`) — вытащи фактические **CPM и CTR** через `vk_ads_statistics_summary` / `vk_ads_statistics_day` по похожим/прошлым кампаниям клиента (из аудита Шага 0.5). Это тег `api`. Нет доступа или нет похожих кампаний → CPM/CTR только `benchmark`, и так и пометь; если причина в среде, а не в отсутствии истории, добавь пометку о пропуске в `_forecast.md`.
2. **CR и конверсию в лид НЕ выдумывай.** Спроси клиента (его Метрика/CRM). Нет ответа → прогноз обрывается на кликах, лиды = «нет данных».
3. **Посчитай сценарии:** `python -m scripts.forecast --workspace <path> --init` → впиши метрики с тегами в `forecast_inputs.json` → `python -m scripts.forecast --workspace <path>`. Получишь `_forecast.md` с тремя сценариями (минимальный/целевой/расширенный) и reality-check.
4. **Reality-check.** Если расчётный CPL ниже пола ниши, лидов меньше 50 за тест (не выйдет из обучения) или больше, чем отдел продаж обработает — **пересчитай консервативнее**, не отдавай красивое число.
5. **🚦 Гейт маркетолога.** Охваты/клики можно показывать. Лиды/CPL уходят в стратегию **только после явного согласования**: покажи таблицу источников и спроси «согласуем эти цифры?». Если «нереалистично» — возьми поправку как `client`-вход и перезапусти forecast.py.

**Артефакт:** `_forecast.md`. Лиды/CPL со статусом `⚠️ требует согласования`, пока маркетолог не подтвердил.

## Шаг 10. Креативные концепции

**Обязательно прочитай** `vk-ads-specs.md` и `ad-copywriting.md`.

Структура: для каждой ячейки матрицы аудиторий из 6.5 — отдельная группа объявлений с 3-5 креативами.

**Человеческие названия (конвенция).** Не «Кампания 1 / Группа 2», а читаемо:
- Кампания (ad_plan): `<Продукт> | <Воронка> | <Цель>` — напр. `КвартБот | Холодный трафик | Заявки`.
- Группа (campaign): `<Сегмент> · <Аудитория> · <Гипотеза>` — напр. `Снизу-Excel · C1 соцдем 22-35 · H-cold-1`.
- Креатив (banner): `cr_<сегмент>_<формат>_<вариант>` — напр. `cr_snizu_video_v2`.

**Явная связка.** В `creatives.json` у каждого креатива заполняй поля: `campaign_name`, `group_name`, `segment`, `hypothesis`, `audience_id`, `funnel_stage` (cold/warm/hot/retarget/leadmagnet/subscribers), `url` (или формат lead_form). Тогда кампания → группа → гипотеза → аудитория → воронка → посадочная → креатив связаны сквозь, и `ads.xlsx` + отчёт-стратегия строятся из одного источника и не противоречат.

**Дисциплина бюджета — не распылять.** На тесте держим деньги на немногих сильных гипотезах: ориентир ≥ ~1000 ₽/группу/день, иначе алгоритм не выходит из обучения (нужно 50+ событий). Прикинь: `бюджет/день ÷ 1000 ≈ макс. число групп`. Если гипотез больше — режь число гипотез, а не размазывай.

**Сценарии бюджета.** Заложи три (синхронно с `_forecast.md`):
- **Минимальный** — 2-3 сильнейшие группы, только горячие/тёплые ячейки.
- **Целевой** — основной план: + холодные ячейки, лид-магнит.
- **Расширенный / оптимистичный** — масштабирование на каскад LAL и доп. плейсменты после первых результатов.

**Чек-лист креатива:**
- **Заголовок** — сайт ≤ 25 знаков; приложение/сообщество/лид-форма ≤ 40 (источник: general/start/creating)
- **Текст** ≤ 2000 знаков для сайтов (новый расширенный лимит до 16 384, но первые 200-220 знаков критичны — выше «Показать ещё»)
- **Описание** для коллажа: длинное ≤ 2000 / короткое ≤ 90
- **Текст рядом с кнопкой** ≤ 30 знаков
- **«О компании»** (юр.информация) ≤ 115 знаков
- **CTA-кнопка** — из списка VK (Купить, Узнать больше, Подписаться, Записаться, Заказать звонок и т.д.)
- **Маркировка ОРД** — автоматическая в VK Реклама, но проверь что галочка «Передать данные в ОРД» включена

**Форматы (по приоритету для теста):**
1. **Универсальная запись** — flagship, работает почти всегда
2. **Карусель** — для линейки продуктов / нескольких преимуществ
3. **Видео** — для холодных аудиторий + клипы для P3 (блогеры/креаторы)
4. **Лид-форма VK** — для оптимизации на лиды без лендинга (мобильный трафик)

См. `vk-ads-specs.md` для полного списка с размерами и техтребованиями.

**Тестовая матрица:** 3 креатива на группу, различия в одной оси (заголовок / визуал / CTA — но не всё сразу).

**Проверка перед сдачей:**
- Лимиты VK (см. specs)
- УТП — настоящее (не «качество и индивидуальный подход») и **от правильного сегмента** (Шаг 5 / `ad-copywriting.md` 0.5)
- **Не «ни о чём»**: в первых 220 знаках ≥2 из 4 — оффер / боль / число / след. шаг
- **Имена конкурентов НЕ в тексте** (только в таргете/ключах) — иначе риск ст. 5 ФЗ и отказ модерации
- **Нет сравнений «лучше чем X» / «№1 / самый / единственный»** без пруфа и оговорки
- Требования модерации: нет КАПС, превосходных степеней без пруфа, контактов в основном тексте, более одного «!». Запрещены «100% гарантия», «лучший на рынке», «единственный».
- Закон о рекламе РФ: маркировка ОРД (автоматическая), лицензии для медицины/инвестиций/образования, возрастные ограничения 18+ если применимо
- Дисклеймеры: «Имеются противопоказания, проконсультируйтесь со специалистом» для медицины; «Реклама. ИП Иванов И.И., ИНН ...» в поле «О компании»

**Артефакты:** `10_creatives.md` + **`creatives.json`** (machine-readable) + **`audiences.json`** (для импорта).

После — `python -m scripts.generate_ads_xlsx --workspace <path>` → xlsx/csv + warnings.txt с проблемными креативами (превышение лимитов, потенциальные триггеры модерации).

## Шаг 10.5. Генерация визуала (M1 — картинки)

**Когда:** после Шага 10 (есть creatives.json), перед финальным заливом. **Обязательно прочитай** `references/visual-generation.md` и `references/credentials.md`.

**Цель:** превратить текстовые описания визуала в `creatives.json` (например «split-screen messy Excel vs clean PlanFix») в реальные .png-файлы готовые для залива в VK.

### Pre-flight 1: brand.json

Создай `brand.json` в рабочей папке с цветами и стилем продукта (см. `scripts/brand_defaults.json` для структуры). Если не создать — используются defaults.

Пример для B2B SaaS:
```json
{"product_name": "PlanFix", "primary_color": "#1E40AF", "accent_color": "#22C55E"}
```

Пример для e-commerce / fashion:
```json
{"product_name": "ZARA-style", "primary_color": "#000000", "accent_color": "#D4AF37"}
```

Пример для услуг (доставка / beauty / repair):
```json
{"product_name": "BeautyBot", "primary_color": "#EC4899", "accent_color": "#FB7185"}
```

### Pre-flight 2: ключ OpenAI

**Главное правило:** скилл должен работать «в одно окно» — пользователь не открывает терминал, не запускает команды, не редактирует файлы. Всё происходит через диалог с тобой.

**Если в среде нет запуска кода или сетевых вызовов по ключу — весь модуль M1 пропускается.** Ключ спрашивать не надо: генератор всё равно не запустить. Вместо картинок собери в `10_creatives.md` **ТЗ дизайнеру текстом** по описаниям визуала из `creatives.json`: формат и размер под VK, композиция, что на переднем плане, цвета из `brand.json`, текст на картинке. Пометка: «пропущено: нет генерации визуала — картинки не созданы, вместо них ТЗ дизайнеру. Потеряно: готовые файлы для залива. Как добрать: прогнать `scripts/generate_creative_images.py` с ключом OpenAI либо отдать ТЗ дизайнеру». Скажи пользователю прямо: **без визуала кампанию не залить**, это блокер Шага 11, а не мелочь.

Стратегия запроса ключа (для модели):

1. **Сначала проверь сохранён ли уже ключ.** Выполни сам инструментом запуска кода (например, `mcp__workspace__bash`):
   ```
   python -m scripts.manage_credentials list
   ```
   Если в выводе есть `openai` — ключ уже есть, Pre-flight 2 закрыт. Переходим к запуску генерации.

2. **Если ключа нет** — **попроси пользователя скинуть его в чат** (это Способ Б — дефолт для коллег без терминального опыта):

   > Мне нужен ключ OpenAI для генерации картинок. Скинь его сюда — я сохраню в безопасном месте (`~/.vk-ads-manager/credentials.json`, права 600, вне папки проекта). Спрашивать больше не буду, ключ сработает для всех будущих кампаний.
   >
   > Если ключа нет — заведи на https://platform.openai.com/api-keys (нужен платёжный метод, минимум ~$5 на счёт). Это займёт 2 минуты.

3. **После того как пользователь пришлёт ключ** — сразу сохрани его через bash:
   ```
   python -m scripts.manage_credentials set openai --key <KEY>
   ```
   Подтверди в чате: «✓ ключ сохранён, ввожу его в работу».

4. **Альтернатива (Способ А — только если пользователь явно скажет «я сам введу»):**
   Попроси пользователя самостоятельно выполнить:
   ```
   python -m scripts.manage_credentials set openai
   ```
   Это запросит ключ через `getpass` — ввод не светится в терминале.

**Никогда не сохраняй ключ в `_state.json`, `creatives.json`, `operations_log.md` или других артефактах рабочей папки** — они могут уйти клиенту в архиве. Только в `~/.vk-ads-manager/credentials.json`.

**После сохранения** Claude никогда не повторяет ключ в чате, только маска (через `manage_credentials get openai`).

**Workflow:**

1. **Dry-run первым** — генерация только промптов, без вызова API:
   ```
   python -m scripts.generate_creative_images --workspace <path> --dry-run
   ```
   Создаёт `assets/prompts/<creative_name>.txt` для каждого статичного креатива. Прочитай 1-2, оцени промпт, при необходимости попроси Claude улучшить шаблон в `prompt_templates.py`.

2. **Тест на одном креативе** — реальный вызов API:
   ```
   python -m scripts.generate_creative_images --workspace <path> --only cr_pain_p2_static
   ```
   Получаешь одну картинку в `assets/images/`. Смотришь, нравится / не нравится. Если не нравится — `--force` и итерируешь промпт.

3. **Полный прогон** когда промпты работают:
   ```
   python -m scripts.generate_creative_images --workspace <path>
   ```

**Что генерится автоматически:**
- ✅ `ebook_cover` — обложки PDF lead magnet
- ✅ `pain_split` — split-screen «до/после»
- ✅ `abstract_brand` — брендовые композиции с текстом
- ✅ `carousel_card` — карточки карусели

**Что НЕ генерится автоматически (выводится placeholder + предупреждение):**
- ❌ `ui_mockup` — реальные UI-скриншоты продукта. AI делает их плохо. **Запрашивай у клиента реальные high-res скрины** (минимум 2160×2160).
- ❌ Видео — это модуль M2 (Veo / Kling / Runway), пока не реализован.
- ❌ UGC с реальными людьми — нужен живой человек на камеру.

**Артефакты:**
- `assets/images/<name>.png` — готовые картинки для залива
- `assets/prompts/<name>.txt` — сохранённые промпты (для аудита и тюнинга)
- `assets/generation_log.json` — лог запуска со статусами каждого креатива

**Гейт:** ревью картинок в `assets/images/` перед заливом. Те что в статусе `needs_real_screenshot` — добавь к списку запросов клиенту, приложив шаблон запроса из `references/vk-ads-specs.md` (правила к ссылкам). Скриншоты интерфейса запрашивай от 2160×2160 — меньшее разрешение придётся запрашивать повторно.

## Шаг 10.6. Генерация видео (M2 — Runway / провайдеры)

**Когда:** после Шага 10.5 (есть `creatives.json` + желательно картинки в `assets/images/`), перед заливом. **Обязательно прочитай** `references/video-generation.md`.

**Цель:** создать MP4-видео для креативов где `format` или `image_or_video` содержит «video» (например `cr_pain_p1_video`, `cr_ugc_p1`).

**Если в среде нет запуска кода или сетевых вызовов по ключу — модуль M2 пропускается целиком.** Провайдера и модель не выбирай, ключ не спрашивай. Вместо видео собери в `10_creatives.md` **ТЗ на съёмку/монтаж**: длительность, раскадровка по секундам, что в кадре, текстовые оверлеи, музыка, финальный CTA — по тем же описаниям, что пошли бы в промпт. Пометка: «пропущено: нет генерации видео — MP4 не созданы, вместо них ТЗ на съёмку. Потеряно: готовые видеокреативы. Как добрать: прогнать `scripts/generate_creative_videos.py` с ключом провайдера либо снять по ТЗ». Видео-креативы при этом **не считай готовыми** на Шаге 11: либо заливаем кампанию только с картинками, либо ждём видео.

### Pre-flight 1: выбор провайдера и модели

**Рекомендуемый дефолт — `replicate`** (один ключ → десятки моделей, быстрая смена SOTA, A/B сравнения).

При работе с Replicate **обязательно выбрать модель** через `--model <slug>`:
- `kwaivgi/kling-v1.6-standard` — универсал дефолт ($0.05/sec)
- `bytedance/seedance-1-pro` — высокое качество motion ($0.15/sec)
- `bytedance/seedance-1-lite` — дёшево для перебора вариантов ($0.04/sec)
- `minimax/hailuo-02` — лучшие лица для UGC ($0.45/clip)
- `kwaivgi/kling-v2-master` — текущий флагман Kling ($0.28/sec)
- Полный каталог: `references/replicate-models.md`

Стратегия выбора модели:
- **Pain reframe / split-screen без людей** → `kwaivgi/kling-v1.6-standard`
- **UGC с реальным человеком** → `minimax/hailuo-02` или `kwaivgi/kling-v2-master`
- **Product demo (UI скринкаст)** → `bytedance/seedance-1-pro`
- **Дешёвый перебор вариантов** → `bytedance/seedance-1-lite`
- **Премиум финал** → `google/veo-3` (если в бюджете)

**Альтернативные провайдеры** (прямые API без Replicate):
- `runway` — Runway Gen-4 Turbo ($0.05/sec, 5/10s)
- `kling` — прямой Kling API (требует AccessKey+SecretKey)
- `veo` — Google AI Studio (премиум $0.50/sec)
- `aismm` — для владельцев AiSMM Pro

Прямые провайдеры могут быть дешевле/быстрее Replicate, но требуют отдельных ключей и не дают гибкости в смене моделей.

Спроси пользователя если выбор не очевиден. Если нет ясного предпочтения — используй `replicate` с моделью под тип креатива.

### Pre-flight 2: ключ провайдера

По шаблону из Шага 10.5 Pre-flight 2 (Способ Б — дефолт):

1. Проверь через `python -m scripts.manage_credentials list` есть ли ключ выбранного провайдера.
2. Если нет — попроси пользователя скинуть в чат:
   > Для видео-генерации нужен ключ Runway. Скинь сюда — я сохраню. Если ключа нет: app.runwayml.com/account → Settings → API. Минимум ~$10 на счёт.
3. Получив ключ — выполни `python -m scripts.manage_credentials set runway --key <KEY>`.

### Workflow (для Replicate — рекомендуемый)

#### Шаг A: Dry-run (бесплатно)

```
python -m scripts.generate_creative_videos --workspace <path> --dry-run
```

Промпты сохранятся в `assets/video_prompts/`. Прочитай 1-2 — убедись что качественные.

#### Шаг B: A/B Variants (3 варианта первого сегмента)

```
python -m scripts.generate_creative_videos \
  --workspace <path> \
  --only cr_pain_p1_video \
  --provider replicate \
  --model kwaivgi/kling-v1.6-standard \
  --variants 3
```

Создаст `cr_pain_p1_video_seg1_var1.mp4`, `_var2.mp4`, `_var3.mp4` (~$0.75 за все 3 на Kling Standard).

**Покажи варианты пользователю** способом, который есть в среде (например, `computer://`-ссылками) — пусть выберет лучший. Нечем показать — дай пути к файлам.

#### Шаг C: Финализация с выбранным + дозагенерирование + склейка

```
python -m scripts.generate_creative_videos \
  --workspace <path> \
  --only cr_pain_p1_video \
  --provider replicate \
  --model kwaivgi/kling-v1.6-standard \
  --chosen-variant 2 \
  --target-duration 15 \
  --chain-segments
```

- Вариант 2 копируется как `seg1`
- Генерируются `seg2`, `seg3` с предыдущим last frame как seed (плавные переходы)
- Склейка через FFmpeg → финальный `cr_pain_p1_video.mp4` (15s)

#### Альтернативный workflow (без variants, для дешёвого теста одного варианта)

```
python -m scripts.generate_creative_videos \
  --workspace <path> \
  --provider replicate \
  --model bytedance/seedance-1-lite \
  --target-duration 5
```

**MVP ограничения (важно сказать пользователю):**

- **5 секунд максимум** — Runway Gen-4 Turbo возвращает 5 или 10s, мы дефолтим в 5s через `--max-duration 5`
- **Без звука** — Runway не генерит аудио. Озвучку добавлять отдельно (ElevenLabs / реальный диктор / закадровый текст в Premiere)
- **Без overlay-текста** — добавляется в постпродакшене (CapCut / DaVinci / Premiere)
- **Image-to-video с seed** — экспериментально, лучше работает для медленного движения

**Артефакты:**
- `assets/videos/<name>.mp4` — готовые видео-файлы
- `assets/video_prompts/<name>.txt` — сохранённые промпты
- `assets/video_generation_log.json` — лог + оценка стоимости

**Гейт:** ревью видео в `assets/videos/`. Если качество не устраивает — итерируй промпт в `video_prompt_templates.py` или попроси пользователя снять реальное видео (особенно для UGC).

## Шаг 10.7. PDF Lead magnet (M3)

**Когда:** в стратегии есть eBook-креативы (формат `carousel_with_lead_form` или name содержит `ebook`). Это главная ставка стратегии — 40% бюджета на конверсионную кампанию через email-цепочку. **Обязательно прочитай** `references/pdf-generation.md`.

**Цель:** создать реальные PDF которые пользователь будет получать после заполнения лид-формы VK. Без PDF eBook-креатив не работает — нечего отдавать.

### Workflow

1. **Узнай какие PDF нужны** — выполни:
   ```
   python -m scripts.generate_lead_magnet_pdfs --workspace <path> --list-expected
   ```
   Скрипт покажет какие eBook-креативы есть и какие markdown-файлы ожидаются.

2. **Напиши контент в диалоге с пользователем.** Для каждого eBook-креатива:
   - Спроси у пользователя: какие 5-7 разделов хочется? Есть ли реальные кейсы? Какие цифры?
   - Напиши markdown — экспертный, конкретный, без воды. 5-10 страниц A4 (~1000-2000 слов).
   - Сохрани через `Write` в `assets/pdf_content/<creative_name>.md`.
   - Покажи пользователю → жди ОК или правки.

3. **Собери PDF**:
   ```
   python -m scripts.generate_lead_magnet_pdfs --workspace <path>
   ```
   - Использует обложки от M1 (`<name>_card1.png`) и CTA от M1 (`<name>_card3.png`) если они есть.
   - Если их нет — генерирует программную обложку и CTA через ReportLab.
   - PDF в `assets/pdfs/<name>.pdf`.

4. **Покажи пользователю PDF** тем способом, который есть в среде (например, `computer://`-ссылкой); нечем показать — дай путь к файлу. Проси проверить. Правки → меняем markdown → `--force` для перегенерации.

**Если в среде нет запуска кода — PDF не собрать.** Пункты 1 и 3 пропускаются, пункт 2 остаётся: markdown-контент лид-магнита ты всё равно пишешь в диалоге и сохраняешь в `assets/pdf_content/<creative_name>.md`. Пометка: «пропущено: нет запуска кода — PDF не собран, готов только markdown-контент. Потеряно: файл лид-магнита для залива. Как добрать: прогнать `scripts/generate_lead_magnet_pdfs.py` или собрать PDF из markdown вручную». Скажи пользователю, что eBook-креативы без файла лид-магнита заливать нет смысла — обещание в объявлении будет нечем закрыть.

### Что писать в markdown — пример каркаса

```markdown
# 5 готовых процессов для агентства

## Введение

Если вы агентство 2-5 человек, ведёте 5-10 клиентов и теряете задачи между Telegram, Trello и Excel — эта PDF для вас.

Внутри: 5 рабочих процессов которые можно настроить в PlanFix за 2 часа без программиста.

---

## Процесс 1: Брифы и согласования с клиентом

Текст с конкретикой про шаги, шаблоны полей, кто получает уведомления.

### Как настроить за 15 минут

1. Шаг
2. Шаг
3. Шаг

---

(ещё 4 раздела по той же структуре)

---

## Что делать дальше

Получили PDF — настройте 1 процесс из 5 на этой неделе. Если нужна помощь — 14 дней триал, поддержка отвечает за 2 часа.
```

`---` создаёт разрыв страницы.

**Гейт:** PDF проверен пользователем. После этого в лид-форму VK при заливе (Шаг 11) добавляется автоотправка PDF на указанный email (это настраивается в самой VK лид-форме как «успешный экран» + интеграция с email-сервисом клиента).

**Что НЕ делает MVP:**
- ❌ Автоотправка PDF на email — нужна интеграция с email-сервисом (Mindbox / SendPulse / Unisender) у клиента
- ❌ Дизайнерская вёрстка с иллюстрациями — для каждого раздела
- ❌ Embedded интерактивные элементы (формы внутри PDF)

---

# Шаг 11. Финальный залив в кабинет

**Когда:** после Шагов 10/10.5/10.6 — есть `creatives.json`, `audiences.json`, картинки в `assets/images/`, видео в `assets/videos/` (где есть). Реквизиты для ОРД зафиксированы.

## Какой путь выбрать

| Путь | Когда выбирать | Что нужно от среды |
|---|---|---|
| **A. vk-ads-mcp** (рекомендуется) | Есть инструменты MCP-сервера `vk-ads` | Вызов MCP-инструментов. Запуск кода не нужен |
| **B. Наш REST API** (M4) | MCP нет, но есть запуск кода и токен VK Ads | Запуск кода + сетевые вызовы по ключу (`scripts/deploy_campaign.py`) |
| **C. Ручной залив** (M5) | Ни MCP, ни запуска кода; либо клиент не выдаёт токен | Только файлы и диалог |

Выбирай **первый путь, который среда позволяет**, а не первый по списку предпочтений. Ушёл на путь C не по выбору клиента, а из-за среды — это пропуск, помечай его в `launch_log.md`.

### Путь A: vk-ads-mcp (рекомендуемый)

**Если инструменты MCP-сервера `vk-ads` есть** (в одной среде они видны с префиксом `mcp__vk-ads__`, в другой имена выглядят иначе — ищи по короткому имени: `vk_ads_ad_plans_create`, `vk_ads_content_upload_image`):

0. **Выбор кабинета:** если в режиме click.ru доступно несколько кабинетов — `vk_ads_accounts_list`, покажи список пользователю, зафиксируй выбранный `account_id` и передавай его в каждый последующий вызов.
0.1. **Пакет размещения (`package_id`) — обязателен, без него создание группы падает.**
   `vk_ads_packages_list(objective="<цель>")` → выбери пакет и зафиксируй его `id` в `_state.json`.
   Правила отбора: (1) только `status: "active"` — в выдаче встречаются `blocked`;
   (2) `priced_event_type` определяет модель оплаты — `0` = CPM, `1` = CPC, `30` = oCPM;
   (3) при равных условиях бери пакет с `banner_format_id: 0` (мультиформат) —
   он не привязывает тебя к одному формату креатива.
   Всего на сервере ~174 пакета, поэтому **всегда фильтруй по `objective`**, не тяни полный список.
   Доступные значения `objective` приходят в поле `available_objectives` того же ответа;
   для воронки этого скилла рабочие — `leadads` (лид-формы) и `site_conversions` (конверсии на сайте).
   Покажи пользователю выбранный пакет словами («оплата за показы, мультиформат») и подтверди.

0.2. **Гео → `region_id`.** `targetings.geo.regions` принимает **числовые id**, а не названия.
   Для каждого города/региона из `audiences.json` — `vk_ads_regions_search(query="<название>")`,
   возьми `id` из `items`. Полное дерево (`vk_ads_dictionary_get(name="regions")`) не тяни — оно
   большое (5500+ регионов). Ничего не нашлось или нашлось несколько — **спроси пользователя**,
   какой регион имелся в виду, не угадывай. Зафиксируй маппинг «название → id» в `_state.json`.
1. **Пре-флайт по каждой ссылке.** До загрузки проверь URL: HEAD-запрос должен вернуть `Content-Type: image/jpeg` или `image/png`. Вернулся `text/html` — это страница просмотрщика (типовой случай: шаренная ссылка Google Drive / Яндекс.Диска), файл по ней не скачается. Вернулась ошибка или таймаут — ссылка приватная либо во внутренней сети. В обоих случаях **не вызывай загрузку**: покажи пользователю конкретную ссылку и запроси замену по правилам из `references/vk-ads-specs.md`. Ни одной битой ссылки на входе в залив.
2. **Загрузка медиа:** для каждой картинки/видео — `vk_ads_content_upload_image` / `vk_ads_content_upload_video`, параметр `source_path_or_url`. ⚠️ **Хостовый сервер (aihub.click.ru) не читает локальные файлы** — только публичный http(s)-URL. Файлы из `assets/images/` сначала выложи по ссылке (или залив медиа делай через путь B — `deploy_campaign.py` умеет локальные файлы). **Сохраняй возвращённые `id`: API не отдаёт список ранее загруженного контента, потерянный ID означает повторную заливку и мусор в хранилище.**
3. **Создание ad_plan (UI «Кампания», верхний уровень):** `vk_ads_ad_plans_create` с `payload`, где nested `campaigns: [...]` (по числу аудиторий) и nested `banners: [...]` внутри каждой campaign. Один атомарный вызов — избегаем orphan'ов.
4. **Альтернатива (если атомарный payload слишком большой):** `vk_ads_ad_plans_create` → потом `vk_ads_campaigns_create(ad_plan_id=..., banners=[...])` по одной группе за вызов. ⚠️ Баннеры передаются **внутри** payload группы: отдельного `banners_create` в API нет, «долить» объявления в уже созданную группу невозможно. Группа, созданная без `banners`, навсегда останется пустой — её придётся удалять и пересоздавать.
5. **Все объекты в `status: "blocked"`** — никогда не активируй сам.
6. **Проверка:** `vk_ads_ad_plans_get(ad_plan_id=...)`, затем по каждой группе `vk_ads_ad_groups_get(ad_group_id=..., fields="id,name,status,banners,issues")`. **Обязательно убедись, что `banners` не пустой.** Пустой массив + issue `NO_BANNERS_WITH_ACTIVE_STATUS` означает, что залив креативов провалился — сообщи пользователю и не выдавай ссылку как успешный результат.
   Полезные поля для диагностики: `vk_ads_campaigns_list(fields="id,name,status,objective,budget_limit,budget_limit_day,ad_plan_id,package_id,targetings,issues")`
   — `issues` показывает словами, почему группа не крутится (`NO_BANNERS_WITH_ACTIVE_STATUS`,
   `NO_MONEY`, `AD_PLAN_STOPPED`, `STOPPED`).
7. **Дай ссылку:** `https://ads.vk.ru/hq/campaign/<ad_plan_id>` (в URL это всё ещё `/campaign/`, исторически).

**Если MCP-инструментов нет** — предложи подключение к хостовому серверу за 2 минуты (ничего клонировать и ставить не надо):
```
python -m scripts.setup_vk_ads_mcp --token <CLICK_RU_TOKEN> --vk-account-id <ID_АККАУНТА> --target all
```
См. `references/vk-ads-mcp-integration.md` для полной инструкции. Установщик требует запуска кода: если кода запустить нельзя — конфиг пишет человек по `docs/hosted-mcp-setup.md`, а ты идёшь на путь B или C, не пытаясь настроить MCP сам.

### Путь B: наш REST API (если MCP не подключен)

**Главный скрипт:** `scripts/deploy_campaign.py`

### Pre-flight: ключ VK Ads

По шаблону Способа Б:

1. Проверь `python -m scripts.manage_credentials list` — есть ли `vk_ads`.
2. Если нет — попроси:
   > Для залива в кабинет нужен access_token VK Ads API. Получить: ads.vk.ru → Настройки → API → создать приложение → токен. Скинь сюда — я сохраню.
3. Получил → `python -m scripts.manage_credentials set vk_ads --key <KEY>`.

### Workflow для модели

1. **Сначала dry-run** — покажи пользователю что будет создано:
   ```
   python -m scripts.deploy_campaign --workspace <path> --dry-run
   ```
   Выведет план без реальных вызовов. Покажи пользователю саммари: «создам 1 кампанию, N групп, M баннеров, бюджет X — ОК?».

2. **После «ОК» — реальный запуск**:
   ```
   python -m scripts.deploy_campaign --workspace <path>
   ```
   Что произойдёт:
   - Загрузит все медиа из `assets/images/` и `assets/videos/`
   - Создаст ad_plan — «Кампанию» верхнего уровня (status=blocked)
   - Создаст campaigns — «Группы объявлений» по числу аудиторий, каждая с `ad_plan_id` (всё blocked)
   - Создаст banners — «Объявления» с привязкой медиа, каждое с `campaign_id` (всё blocked)
   - Запишет в `operations_log.md`
   - Сохранит `assets/deploy_plan.json` со всеми ID

3. **Дай ссылку пользователю**:
   ```
   ✅ Кампания создана: https://ads.vk.ru/hq/campaign/<id>
   Открой кабинет → проверь Сценарий 10 → активируй кнопкой «Запустить».
   ```

**Никогда не активируй** (`status: active`) автоматически. Это всегда финальное действие пользователя через UI после прохождения чек-листа.

### Сценарий 10 (предзапусковый чек-лист) — напомни пользователю

Перед тем как пользователь нажмёт «Запустить» в кабинете:

- [ ] Все группы внутри проверены (бюджет, таргетинг, плейсменты)
- [ ] Все креативы прошли модерацию VK (`status: accepted`, обычно 1-4 часа после создания)
- [ ] Пиксель установлен и стреляет (см. Шаг 7а)
- [ ] События пикселя замаплены на цели в кабинете
- [ ] Лендинг доступен с мобилки, форма работает
- [ ] ОРД-данные заполнены (плашка «Реклама. Рекламодатель: ...»)
- [ ] UTM-метки на месте
- [ ] Бюджет соответствует плану
- [ ] Есть план на первые 3 дня мониторинга (Сценарий 11 daily check)

### Если API недоступен — M5 ручной залив

Если у пользователя/клиента нет токена VK Ads (или клиент не готов выдавать, или API возвращает ошибки), **или в среде нет вызова MCP-инструментов и запуска кода** — используй M5:

```
python -m scripts.generate_launch_guide --workspace <path>
```

Скрипт читает `creatives.json` + `audiences.json` + `_state.json` + `brand.json` → собирает `LAUNCH_GUIDE.md` с пошаговой инструкцией:

- Шаг 0: чек-лист подготовки (доступы, реквизиты ОРД, файлы)
- Шаг 1: настройка ОРД в кабинете
- Шаг 2: создание кампании (с точными значениями бюджета, цели, стратегии)
- Шаг 3: создание групп (по числу аудиторий — таргетинг описан построчно)
- Шаг 4: создание баннеров (полные тексты для copy-paste + ссылки на файлы медиа)
- Шаг 5: финальный чек-лист
- Шаг 6: активация и первые часы

Опционально добавь `--docx` чтобы сгенерить ещё `LAUNCH_GUIDE.docx` (для печати / отправки клиенту).

**Если в среде нет запуска кода** — генератор не поможет, но путь остаётся: напиши `LAUNCH_GUIDE.md` **сам**, руками, по той же структуре из семи шагов выше, взяв точные значения из `creatives.json`, `audiences.json`, `_state.json` и `brand.json`. Это единственный путь залива, который работает при обязательном минимуме способностей, поэтому пропускать его нельзя. Пометка: «пропущено: нет запуска кода — `LAUNCH_GUIDE.md` написан вручную, `.docx` не собран. Как добрать: прогнать `scripts/generate_launch_guide.py`».

Покажи получившийся гайд способом, который есть в среде (например, `computer://`-ссылкой), либо дай путь к файлу. Оператор или маркетолог со стороны клиента сможет залить руками за 1-2 часа.

**Раздел «Пропущено из-за среды» в `launch_log.md` — обязательный.** Собери в него все пометки о пропуске со всех шагов одним списком: какой шаг, какой способности не было, что сделано вместо, что недобрано, что делать человеку. Пропусков не было — напиши «пропусков нет, все шаги выполнены полностью». Этот раздел пользователь читает **до** активации кампании.

### Что НЕ делает deploy_campaign в MVP

- ❌ Не создаёт lookalike audiences (требуют source — у первого запуска нет)
- ❌ Не загружает CRM-базы (нужны CSV — опциональная отдельная команда)
- ❌ Не создаёт пиксель — путь B этого не умеет. Через MCP умеет: `vk_ads_remarketing_pixels_create` (см. Шаг 7а)
- ❌ Не активирует кампанию — только пользователь

---

---

# Шаг 11 (опциональный). Пост-релизная оптимизация

**Когда:** через 5-7 дней после активации. Триггер: «прошла неделя», «оптимизация VK».

1. Статистика за период: `vk_ads_statistics_day(entity="campaigns", ids="<id через запятую>", date_from=..., date_to=...)`.
   ⚠️ `ids` обязателен — режима «по всему кабинету» нет, сначала `vk_ads_campaigns_list`.
   MCP недоступен — прямой REST `GET /statistics/campaigns/{id}/day.json` (см. `vk-ads-api.md`).
2. По каждой группе:
   - CTR < 0.3% + Impressions > 5000 → креатив устарел / аудитория не та → перезалить или выключить
   - CTR > 1.5% + Clicks > 50 → масштабировать (увеличить бюджет в 1.5-2x)
   - Высокий CTR + низкий CR → проблема в лендинге, не в креативе
   - Лиды есть, но дорогие → попробовать стратегию «предельная цена» с лимитом CPL
3. **Look-alike дозалив:** если в горячей аудитории накопилось > 1000 конверсий → создать LAL 1%, 2-3%, 4-5% — тестировать каскадом.
4. **Минусы:** в VK нет ключевых минус-слов, но есть исключения интересов и сообществ. Анализ — через отчёт `keywords` (если включён key phrases targeting).
5. `11_optimization.md` с конкретным action plan по каждой группе.
6. С согласия — изменения через `vk_ads_api.py`. Никогда не удаляй сущности — только пауза.

**Безопасность.** Никогда не вызывай автоматически:
`vk_ads_*_delete` (любые), `vk_ads_campaigns_set_status(status="active")`,
`vk_ads_ad_plans_update({"status": "active"})`, `vk_ads_banners_update({"status": "active"})`.
Разрешено без отдельного «запускай»: чтение, `*_update` неструктурных полей после «ОК»,
создание сегментов и списков.

⚠️ У `ad_plan` **нет** метода `set_status` — пауза и запуск «Кампании» целиком идут только
через `vk_ads_ad_plans_update({"status": "blocked"|"active"})`. У `campaign` метод есть:
`vk_ads_campaigns_set_status`.

---

# Шаг 12. Итоговый отчёт-стратегия для команды агентства

**Когда:** в самом конце обработки — собраны creatives.json, audiences.json, `_forecast.md`, артефакты конкурентов/УТП/семантики/посадочных. Триггер: «собери стратегию», «отдай отчёт для команды», «финальный документ».

Запусти:
```
python -m scripts.generate_ads_xlsx --workspace <path>
python -m scripts.generate_strategy_report --workspace <path> --docx
```

Что получится в `<path>/report/`:
- **`strategy_report.md`** (+ `.docx`) — сводный отчёт для команды агентства: резюме/УТП, **карта воронок** (холодный/ретаргет/лид-магниты/подписчики), **посадочные и лид-формы явно**, **структура кампаний** (связка из того же источника, что и `ads.xlsx`), **прогноз** со статусом согласования, **«что запросить у клиента»**, чек-лист согласований.
- Отдельные самодостаточные .md по блокам: `_competitors.md`, `_semantics.md`, `_usp.md`, `_landings.md`, `_funnels.md`, `_campaign_structure.md`, `_forecast.md`, `_client_requests.md`, `_strategy.md` — каждый можно показать/отдать по отдельности.

**Важно:** структура и воронки в отчёте выводятся из `creatives.json`, поэтому отчёт и `ads.xlsx` не противоречат друг другу. Если что-то правишь — правь creatives.json и перегенерируй оба.

**Если в среде нет запуска кода** — отчёт собери сам: напиши `report/strategy_report.md` по перечисленным разделам, читая те же артефакты, и разложи самодостаточные блоки по отдельным `.md`. Вместо `ads.xlsx` — Markdown-таблица `ads.md`. Пометка: «пропущено: нет запуска кода — отчёт и таблица объявлений собраны вручную, `.docx` и `.xlsx` не сгенерированы. Потеряно: валидация лимитов и юр.чистоты, которую делает `generate_ads_xlsx`. Как добрать: прогнать оба скрипта в среде с Python». Валидацию при этом **пройди глазами** по `references/vk-ads-specs.md` и `references/ad-copywriting.md` — иначе отчёт уйдёт с текстами, которые не пройдут модерацию.

**Раздел «Пропущено из-за среды» в отчёте — обязательный.** Продублируй в него сводный список пропусков из `launch_log.md`, чтобы команда агентства видела, какие блоки стратегии построены на полных данных, а какие нет.

**Перед выдачей** проверь чек-лист согласований в конце отчёта (список конкурентов, УТП по сегментам, прогноз согласован маркетологом, тексты юр.чисты, структура = xlsx). Покажи пользователю `strategy_report.docx` и нужные `.md` тем способом, который есть в среде (например, `computer://`-ссылками), либо перечисли пути к файлам.

---

# Lifecycle: повседневная работа с активной кампанией

Второй большой режим. **Полный набор сценариев — в `references/lifecycle-runbook.md`** (13 операций с проверками безопасности).

## Главные правила lifecycle

1. **Никогда не активируй** (`status: active`) без явного «запускай».
2. **Никогда не удаляй** сущности (audiences, campaigns, banners) — только пауза (`status: blocked`).
3. **Перед write — план + «ОК?»**.
4. **После операции — `GET`** той же сущности для проверки.
5. **Логируй в `operations_log.md`**: дата, операция, до/после, причина, подтверждение.

## Когда какой сценарий

| Триггер | Сценарий | R/W |
|---|---|---|
| «Как у нас VK?» | 1: общий отчёт | Read |
| «Daily check» | 11: ежедневный мониторинг | Read |
| «Увеличь/сократи бюджет» | 2 | Write |
| «Пауза / запусти снова» | 3 | Write |
| «Активируй кампанию» | 10: предзапусковый чек-лист | Write |
| «Добавь lookalike» / «сделай похожих» | 4 | Write |
| «Загрузи CRM-базу» | 5 | Write |
| «Измени текст / визуал креатива» | 6 | Write |
| «Добавь интересы / сузь аудиторию» | 7 | Write |
| «Прошла неделя, оптимизация» | 8 / Шаг 11 | Write |
| «Переключи стратегию ставок» | 9: «минимальная» ↔ «предельная цена» | Write |
| «Корректировки по соцдему» | 12 | Write |
| «Скопируй кампанию» | 13 | Write |

## Ограничения API VK Ads — фолбеки

| Не умеет через API | Фолбек |
|---|---|
| ~~Создать пиксель~~ — **умеет**: `vk_ads_remarketing_pixels_create` | — (фолбек не нужен) |
| Проверить, что пиксель стреляет | Только UI / браузер — API отдаёт факт существования, а не события |
| Загрузка events через UI (manual) | UI или Conversion API (отдельная интеграция) |
| Сложные правила автоматизации | UI или внешний скрипт на cron |
| Дублирование с правкой одного поля | API копирует + апдейт отдельно |

Когда упираешься — **скажи прямо**: «Через API не сделать. Покажу в UI» — и дай пошаговый сценарий для ads.vk.ru.

---

# Стиль работы

- **Не клянчи.** Один прямой вопрос за раз.
- **Не вываливай простыни.** Артефакт в файл, сводка в чат 5-10 строк.
- **Гипотеза > пустой вопрос.** «Вот моя версия — согласны?»
- **Защищай качество** на шагах 5, 6 и 6.5 — это шаги где скилл даёт максимум value.
- **Бюджет важен** — предупреди при <30 тыс ₽ / 2 недели (алгоритм не успеет выйти из обучения).
- **Не выдумывай метрики и УТП** — «не знаю» лучше выдуманного.
- **Не завышай прогноз.** Охваты/клики — из кабинета (MCP); лиды/CPL — только производные с тегом источника и **гейтом согласования маркетолога**. Нереалистично — пересчитай сценарии, не защищай красивую цифру.
- **Не смешивай сегменты.** У каждого сегмента (вкл. «конкурентов снизу» — Excel/руки) свои боли и своё УТП. Имена конкурентов — в таргете/ключах, не в текстах.
- **VK ≠ Директ.** В VK работаем с **аудиториями**, а не с поисковыми запросами. Не пытайся притянуть keyword research из контекста.
- **Пользователь не оператор.** Все скрипты запускай сам инструментом запуска кода (например, `mcp__workspace__bash`). Запускать код нечем — передай команду пользователю с пояснением «моё окружение не даёт мне это запустить, выполните пожалуйста: ...» и попроси прислать вывод. И это невозможно — иди по ветке «если нет» этого шага.
- **Пропуск всегда виден.** Шаг, выполненный без необязательной способности среды, получает пометку о пропуске в свой артефакт (формат — в «Что нужно от среды»), а на гейте ты говоришь об этом словами. Молча упрощённый результат — хуже честно недобранного.
- **Ключи в чате — это нормально.** Когда пользователь скидывает API-ключ — благодари кратко, сразу сохраняй через `manage_credentials.py set <service> --key <KEY>`, в следующих сообщениях не повторяй ключ (используй маску если нужно). Хранилища нет (нет запуска кода) — скажи прямо, что ключ сохранить негде, и не проси его заранее.
- **Показывай результат.** После генерации картинки или создания кампании — покажи файл способом, который есть в среде (например, `computer://`-ссылкой или встраиванием в чат). Нечем показать — дай путь к файлу от корня рабочей папки. Пользователь не должен лазить по папкам наугад.

# Возобновление

«Продолжаем по VK» → найди `vk-campaign-*/`, прочитай `_state.json` и `launch_log.md` / `operations_log.md`, продолжай с того места. Не начинай сначала.

README