docs: clarify single strategy goal updates

Author: Адель

docs/API_SIMPLE.md

@@ -941,7 +941,7 @@ POST /yandex/campaigns/{campaign_id}/strategy
 - `idempotency_key` (str, required, min 6 символов);
 - `dry_run` (bool, default `true`) — preview-only без мутации;
 - `strategy_type` — `"WB_MAXIMUM_CONVERSION_RATE"`;
-- `goal_id` (int, required) — ID цели Метрики;
+- `goal_id` (int, required) — ID одной цели Метрики, которая станет текущим `GoalId` стратегии;
 - `weekly_spend_limit` (float, required) — недельный бюджет в **рублях** (конвертируется в микроединицы × 1 000 000);
 - `bid_ceiling` (float, optional) — максимальная ставка в **рублях**;
 - `network` (str, optional) — `"SERVING_OFF"` для явного выключения сетей. Когда опущено, текущая Network-стратегия сохраняется из readback. Endpoint никогда молча не включает сети;
@@ -952,6 +952,8 @@ POST /yandex/campaigns/{campaign_id}/strategy
 - `dry_run=false` в `live_readonly`/`sandbox`/`mock` — **отклоняется с HTTP 409 до сетевого вызова**;
 - реальный apply возможен только в `live_write` с `approved=true` + `idempotency_key` + `dry_run=false`;
 - `weekly_spend_limit` и `bid_ceiling` — в **рублях** (публичное REST-соглашение). Конвертируются в Direct-микроединицы (× 1 000 000) строго в store-слое;
+- `goal_id` **заменяет** текущий `GoalId` в стратегии кампании. Это не добавление цели в список: повторный вызов с другим `goal_id` переключит стратегию на новую цель;
+- текущий endpoint не поддерживает `goal_ids: []` или «добавить все цели». Если нужна оптимизация по нескольким целям, сначала нужно подтвердить поддержку и payload-формат в Yandex Direct API и доработать DirectPilot;
 - `BudgetType` (например `WEEKLY_BUDGET`) сохраняется из readback-блока стратегии. Direct требует его при update; удаление `BudgetType` вызывает `error_code=8000`;
 - Network-стратегия по умолчанию сохраняется из текущего состояния кампании. Endpoint не включает РСЯ молча;
 - Для live-применения endpoint сначала делает readback кампании. Если `DailyBudget` нельзя надежно прочитать из `campaigns.get` (отсутствует или невалидная форма), apply отклоняется с `502` (fail-closed) до `campaigns.update`.
@@ -966,7 +968,7 @@ POST /yandex/campaigns/{campaign_id}/strategy
 GET /metrika/counters/{counter_id}/goals
 ```
 
-Возвращает список целей счётчика. Выберите нужный `goal_id` и передайте его в `POST /yandex/campaigns/{campaign_id}/strategy`.
+Возвращает список целей счётчика. Выберите **один** нужный `goal_id` и передайте его в `POST /yandex/campaigns/{campaign_id}/strategy`. Этот `goal_id` станет единственной текущей целью оптимизации в стратегии, которую поддерживает данный endpoint.
 
 ---
 

docs/MARKETER_GUIDE.md

@@ -41,7 +41,7 @@ DirectPilot — единая прослойка для маркетолога:
 | Обновить почасовое расписание показов | `POST /yandex/campaigns/{campaign_id}/time-targeting` | v5 `campaigns.update TimeTargeting`; endpoint читает текущий `DailyBudget` (нормализация `SpendMode`→`Mode`) и, если `DailyBudget: null` у smart-стратегии (`TEXT_CAMPAIGN`), дополнительно читает `TextCampaign.BiddingStrategy` и включает её в payload; отсутствие необходимых полей в таком кейсе приводит к fail-closed с 502 до `campaigns.update`; `dry_run=true` доступен в любом режиме; `dry_run=false` + apply только в `live_write`; `readback` после apply — v5 `campaigns.get TimeTargeting`; payload preview в ответе |
 | Посмотреть текущее расписание показов | `GET /yandex/campaigns/{campaign_id}/time-targeting` | read-only; возвращает текущий `TimeTargeting` блок (v5 `campaigns.get`) + нормализованное 7×24 расписание; без write-гейтов; доступен во всех режимах (`mock`/`sandbox`/`live_readonly`/`live_write`) |
 | Посмотреть стратегию кампании | `GET /yandex/campaigns/{campaign_id}/strategy` | тип, статус, бюджет, цели, BiddingStrategy; read-only |
-| Обновить стратегию кампании | `POST /yandex/campaigns/{campaign_id}/strategy` | `dry_run=true` для preview (рубли); для live-apply нужны `approved=true`, `idempotency_key`; `goal_id` берется из `GET /metrika/counters/{counter_id}/goals` (counter_id берется из `GET /yandex/campaigns/{campaign_id}/strategy -> counter_ids`) |
+| Обновить стратегию кампании | `POST /yandex/campaigns/{campaign_id}/strategy` | `dry_run=true` для preview (рубли); для live-apply нужны `approved=true`, `idempotency_key`; выбрать один `goal_id` из `GET /metrika/counters/{counter_id}/goals` (counter_id берется из `GET /yandex/campaigns/{campaign_id}/strategy -> counter_ids`). Повторный update с другим `goal_id` заменяет текущую цель стратегии, а не добавляет цель в список |
 | Баланс общего счета | `GET /yandex/account/balance` | безопасная финансовая сводка |
 | Счетчики Метрики | `GET /metrika/counters` | доступные сайты/счетчики |
 | Цели Метрики | `GET /metrika/counters/{counter_id}/goals` | список целей |

skills/directpilot-operations/SKILL.md

@@ -132,10 +132,11 @@ When adding ads to an existing campaign/group via ``POST /yandex/ad-groups/{ad_g
 - Current strategy can be read via `GET /yandex/campaigns/{campaign_id}/strategy` — read-only, no write gate, available in all modes. Returns `Type`, `State`, `Status`, `DailyBudget`, `CounterIds`, `TextCampaign.BiddingStrategy` (raw) and `strategy_summary` (normalized with micros→rubles conversion).
 - To update strategy, use `POST /yandex/campaigns/{campaign_id}/strategy` — gate contract identical to time-targeting: `approved` + `idempotency_key` + `dry_run`; `live_readonly` blocks real writes with HTTP 409; real apply only in `live_write`.
 - Live apply first reads campaign `DailyBudget` from `campaigns.get` and requires an unambiguous read for mode-dependent shape mapping. If `DailyBudget` cannot be reliably extracted in a supported shape, the request is rejected before `campaigns.update` with fail-closed 502 (no invented budget block).
-- Currently supports switching search to `WB_MAXIMUM_CONVERSION_RATE` with `goal_id`, `weekly_spend_limit` (RUBLES, converted to micros × 1 000 000), optional `bid_ceiling` (RUBLES).
+- Currently supports switching search to `WB_MAXIMUM_CONVERSION_RATE` with a single `goal_id`, `weekly_spend_limit` (RUBLES, converted to micros × 1 000 000), optional `bid_ceiling` (RUBLES). This is a **replacement** of the strategy's current `GoalId`, not an append/add-to-list operation.
+- The current DirectPilot endpoint does not accept `goal_ids: []` or “optimize for all goals”. If callers need multiple optimization goals, treat that as a product/API investigation first; do not imply that repeated calls accumulate goals.
 - `BudgetType` (e.g. `WEEKLY_BUDGET`) is preserved from readback strategy block. Direct requires it on update; stripping it caused live `error_code=8000`.
 - Network strategy defaults to preserve-from-readback. Explicit `network="SERVING_OFF"` is supported. Endpoint never silently turns networks ON.
-- Before applying, read current campaign state via the GET endpoint to verify `goal_id` against `/metrika/counters/{counter_id}/goals`.
+- Before applying, read current campaign state via the GET endpoint to verify the single selected `goal_id` against `/metrika/counters/{counter_id}/goals`.
 
 - For live bid updates through Direct v5 `keywordbids.set`, concrete known keywords should use the minimal item shape:
   ```json