@clipwright/mcp-server 0.1.0 → 0.2.0

package/SKILL.md

@@ -1,96 +1,93 @@
-# SKILL.md — установка и эксплуатация `clipwright-mcp`
+# SKILL.md — installing and operating `clipwright-mcp`
 
-Самодостаточная инструкция для АГЕНТА (или человека в Claude Code) без устной
-помощи от разработчика. Следуй шагам по порядку. Не путать с
-`apps/web/.claude/skills/*` — это скиллы дашборда Next.js, к MCP-серверу
-отношения не имеют.
+A self-contained guide for an AGENT (or a human in Claude Code) that needs no
+spoken help from a developer. Follow the steps in order. Not to be confused with
+`apps/web/.claude/skills/*` — those are dashboard skills for the Next.js app and
+have nothing to do with the MCP server.
 
-Пакет `@clipwright/mcp-server` (`bin: clipwright-mcp`) опубликован в npm под
-лицензией MIT, поэтому репозиторий для установки НЕ НУЖЕН — хватит `npx`.
-Сборка из исходников осталась ниже как путь для разработки.
+The package `@clipwright/mcp-server` (`bin: clipwright-mcp`) is published to npm
+under the MIT license, so you do NOT need the repository to install it — `npx` is
+enough. Building from source is kept below as the development path.
 
-Три пакета клиентской поверхности — `@clipwright/core`, `@clipwright/sdk`,
-`@clipwright/mcp-server` — открыты по MIT; сам сервис (REST API, рендер-пайплайн,
-дашборд) закрыт. Это намеренное разделение, а не недосмотр: см. `LICENSE` в
-корне репозитория.
+Four client-side packages — `@clipwright/core`, `@clipwright/sdk`,
+`@clipwright/mcp-server` and `@clipwright/cli` — are MIT; the service itself
+(REST API, render pipeline, dashboard) is closed. That split is deliberate, not
+an oversight: see `LICENSE` in the repository root.
 
-## 1. Установка
+## 1. Installation
 
-### 1.1 Из npm — обычный путь
+### 1.1 From npm — the normal path
 
 ```bash
 npx -y -p @clipwright/mcp-server@latest clipwright-mcp
 ```
 
-Ожидаемо: процесс НЕ завершается, в stderr печатается
-`clipwright mcp server running on stdio` и висит, ожидая JSON-RPC. Это и есть
-признак исправного сервера, а не зависание. Останови `Ctrl+C`.
+Expected: the process does NOT exit, prints `clipwright mcp server running on
+stdio` to stderr, and hangs waiting for JSON-RPC. That is what a healthy server
+looks like, not a freeze. Stop it with `Ctrl+C`.
 
-Немедленный выход с `CLIPWRIGHT_API_KEY env var is required` — тоже ожидаемое
-поведение при пустом ключе (`src/index.ts:11-15`), а не поломка сборки.
+Exiting immediately with `CLIPWRIGHT_API_KEY env var is required` is also
+expected when the key is empty (`src/index.ts`) — it is not a broken build.
 
-Дальше сразу к разделу 1.3: конфиг хоста для этого варианта отличается только
-командой (`npx` вместо `node` с абсолютным путём), оба показаны там.
+Go straight to section 1.3: the host config for this variant differs only in the
+command (`npx` instead of `node` with an absolute path); both are shown there.
 
-### 1.2 Из исходников — только для разработки
+### 1.2 From source — development only
 
-Требования: Node ≥24, pnpm (`packageManager: pnpm@11.13.1` в корневом
-`package.json` — при наличии corepack: `corepack enable`).
+Requirements: Node ≥24, pnpm (`packageManager: pnpm@11.13.1` in the root
+`package.json` — with corepack available: `corepack enable`).
 
 ```bash
-git clone <repo-url> ugc-video-platform   # или используй уже готовый чекаут
+git clone <repo-url> ugc-video-platform   # or use a checkout you already have
 cd ugc-video-platform
 pnpm install
-pnpm build          # pnpm -r build — собирает ВСЕ пакеты монорепо в топологическом порядке
+pnpm build          # pnpm -r build — builds every package in topological order
 ```
 
-Если нужна только эта поверхность (быстрее, но зависимости `@clipwright/core`
-и `@clipwright/sdk` обязаны быть собраны первыми — `...` тянет их
-автоматически):
+If you only need this surface (faster, but `@clipwright/core` and
+`@clipwright/sdk` must be built first — `...` pulls them in automatically):
 
 ```bash
 pnpm --filter @clipwright/mcp-server... build
 ```
 
-После сборки должен существовать файл `packages/mcp-server/dist/index.js`.
-Проверь:
+After the build, `packages/mcp-server/dist/index.js` must exist. Check it:
 
 ```bash
 ls packages/mcp-server/dist/index.js
 ```
 
-#### Предполётная проверка собранного бинаря
+#### Pre-flight check of the built binary
 
-Относится к сборке из исходников. Прежде чем подключать сервер к хосту,
-убедись, что он вообще стартует и не падает на импортах:
+This applies to source builds. Before wiring the server into a host, make sure it
+starts at all and does not die on imports:
 
 ```bash
 CLIPWRIGHT_API_KEY=cw_test node packages/mcp-server/dist/index.js
 ```
 
-Ожидаемо: процесс НЕ завершается сам, в stderr печатается
-`clipwright mcp server running on stdio` и висит на stdio (ждёт JSON-RPC).
-Останови `Ctrl+C`. Если вместо этого немедленный выход с
-`CLIPWRIGHT_API_KEY env var is required` — значит переменная не была передана
-(это ожидаемое поведение при пустом ключе, см. `src/index.ts:11-15`), не баг.
-Если падает на импорте модуля — сборка неполная, вернись к шагу 1.2
-(`pnpm build` из корня, не адресный `--filter`, чтобы точно пересобрать
-`@clipwright/core`/`@clipwright/sdk`).
+Expected: the process does NOT exit on its own, prints `clipwright mcp server
+running on stdio` to stderr, and waits on stdio for JSON-RPC. Stop it with
+`Ctrl+C`. If it instead exits immediately with `CLIPWRIGHT_API_KEY env var is
+required`, the variable was not passed through (expected behaviour on an empty
+key, see `src/index.ts`) — not a bug. If it dies on a module import, the build is
+incomplete: go back to step 1.2 and run `pnpm build` from the root rather than a
+targeted `--filter`, so `@clipwright/core` and `@clipwright/sdk` are definitely
+rebuilt.
 
-### 1.3 Подключение к MCP-хосту
+### 1.3 Connecting it to an MCP host
 
-Варианты A и B ниже запускают сервер ИЗ ИСХОДНИКОВ и потому требуют
-АБСОЛЮТНЫЙ путь до `dist/index.js`:
+Variants A and B below run the server FROM SOURCE and therefore need the ABSOLUTE
+path to `dist/index.js`:
 
 ```bash
 realpath packages/mcp-server/dist/index.js
 ```
 
-Если ставил из npm (раздел 1.1), путь не нужен — бери вариант В в конце
-раздела, он отличается только полями `command`/`args`.
+If you installed from npm (section 1.1), you do not need a path — take variant C
+at the end of this section; it differs only in `command`/`args`.
 
-**Вариант A — `.mcp.json` (проектный конфиг хоста, стиль как в
-`apps/web/.mcp.json` этого репо):**
+**Variant A — `.mcp.json` (project-level host config):**
 
 ```json
 {
@@ -98,28 +95,29 @@ realpath packages/mcp-server/dist/index.js
     "clipwright": {
       "type": "stdio",
       "command": "node",
-      "args": ["/абсолютный/путь/до/ugc-video-platform/packages/mcp-server/dist/index.js"],
+      "args": ["/absolute/path/to/ugc-video-platform/packages/mcp-server/dist/index.js"],
       "env": {
         "CLIPWRIGHT_API_KEY": "cw_...",
         "CLIPWRIGHT_API_URL": "https://api-production-7e69.up.railway.app",
-        "CLIPWRIGHT_CLIENT_ID": "<см. раздел 2 — сгенерировать ДО первого запуска>"
+        "CLIPWRIGHT_CLIENT_ID": "<see section 2 — generate BEFORE the first run>"
       }
     }
   }
 }
 ```
 
-**Вариант B — CLI `claude mcp add`** (эквивалент варианта A одной командой):
+**Variant B — `claude mcp add`** (variant A as a single command):
 
 ```bash
 claude mcp add clipwright \
   -e CLIPWRIGHT_API_KEY=cw_... \
   -e CLIPWRIGHT_API_URL=https://api-production-7e69.up.railway.app \
-  -e CLIPWRIGHT_CLIENT_ID="$(uuidgen | tr -d '-')" \
-  -- node /абсолютный/путь/до/ugc-video-platform/packages/mcp-server/dist/index.js
+  -e CLIPWRIGHT_CLIENT_ID="$(node -e "console.log(crypto.randomUUID().replaceAll('-',''))")" \
+  -- node /absolute/path/to/ugc-video-platform/packages/mcp-server/dist/index.js
 ```
 
-**Вариант В — из npm, без репозитория.** То же самое, но команда — `npx`:
+**Variant C — from npm, without the repository.** Same thing, but the command is
+`npx`:
 
 ```json
 {
@@ -131,171 +129,193 @@ claude mcp add clipwright \
       "env": {
         "CLIPWRIGHT_API_KEY": "cw_...",
         "CLIPWRIGHT_API_URL": "https://api-production-7e69.up.railway.app",
-        "CLIPWRIGHT_CLIENT_ID": "<см. раздел 2 — сгенерировать ДО первого запуска>"
+        "CLIPWRIGHT_CLIENT_ID": "<see section 2 — generate BEFORE the first run>"
       }
     }
   }
 }
 ```
 
-Одной командой:
+As a single command:
 
 ```bash
 claude mcp add clipwright \
   -e CLIPWRIGHT_API_KEY=cw_... \
   -e CLIPWRIGHT_API_URL=https://api-production-7e69.up.railway.app \
-  -e CLIPWRIGHT_CLIENT_ID="$(uuidgen | tr -d '-')" \
+  -e CLIPWRIGHT_CLIENT_ID="$(node -e "console.log(crypto.randomUUID().replaceAll('-',''))")" \
   -- npx -y -p @clipwright/mcp-server@latest clipwright-mcp
 ```
 
-**`@latest` здесь — осознанный выбор, а не небрежность.** Он тянет свежую
-версию при каждом запуске: для прототипа это правильно, потому что контракт
-ещё меняется и рассинхрон клиента с сервером дороже, чем неожиданное
-обновление. Когда контракт устоится, версию надо будет прибить.
+**`@latest` here is a deliberate choice, not sloppiness.** It pulls a fresh
+version on every start: right for a prototype, because the contract still moves
+and a client out of sync with the server costs more than an unexpected upgrade.
+Once the contract settles, the version should be pinned.
 
-Переменные окружения:
+Environment variables:
 
-| Переменная | Обязательна | Значение |
+| Variable | Required | Meaning |
 |---|---|---|
-| `CLIPWRIGHT_API_KEY` | ДА | Bearer-токен формата `cw_*`. Без него процесс завершается сразу с ошибкой (`src/index.ts:11-15`). Токен ВЫДАН ЛИЧНО ТЕБЕ (US-550): он лежит в таблице `api_tokens`, привязан к аккаунту и отзывается отдельно от чужих. Не пересылай его дальше — второму человеку выпускается свой. Разным аккаунтам не видны раны друг друга, и суточный потолок трат у каждого свой. |
-| `CLIPWRIGHT_API_URL` | НЕТ | Прод-URL. Если не задать — SDK сам подставляет `https://api-production-7e69.up.railway.app` (дефолт в `packages/sdk/src/index.ts:18`). Указывай явно только если целишься в другое окружение. |
-| `CLIPWRIGHT_CLIENT_ID` | ДА (см. раздел 2) | Уникальный идентификатор УСТАНОВКИ. |
-
-После подключения перезапусти/переоткрой MCP-хост и убедись, что `tools/list`
-отдаёт четыре тула: `make_ugc`, `get_run`, `quote_ugc`, `list_voices`.
-
-## 2. `CLIPWRIGHT_CLIENT_ID` — обязательно и ПОЧЕМУ
-
-**Правило: КАЖДАЯ установка обязана получить СВОЙ уникальный
-`CLIPWRIGHT_CLIENT_ID` ДО первого вызова `make_ugc`.** Не копировать значение
-с другой машины, не оставлять пустым в расчёте на дефолт "как-нибудь
-сработает".
-
-### Почему это не опционально
-
-Ключ идемпотентности, которым SDK помечает каждый платный `POST
-/v1/skills/make_ugc/run`, детерминированно вычисляется из **хеша входа
-(`script`/`person`/`image`/… после canonicalize) И идентичности клиента**
-(`idempotencyKeyFor`, `packages/core/src/idempotency.ts`; используется в
-`packages/sdk/src/index.ts:104-115`). Сервер дедуплицирует по этому ключу:
-`apps/api/src/app.ts:103` — если для уже сохранённого ключа
-`existing.request_hash === hash`, он возвращает 200 с раном, который
-**создал первый запрос с этим ключом**, а не запускает новый платный рендер.
-
-Это правильное поведение для ретрая ОДНОГО И ТОГО ЖЕ пользователя (не платить
-дважды за случайный дубль-клик агента). Но:
-
-- поиск по ключу идемпотентности идёт по ключу, а не по аккаунту
-  (`runs_idempotency_key_unique` — частичный индекс по одной колонке);
-- поэтому **разделение аккаунтов токеном (US-550) само по себе НЕ разводит
-  одинаковые входы**: `clientId`, примешанный в хеш ключа, остаётся тем, что
-  делает ключи разными;
-- и он же нужен внутри одного аккаунта: ноутбук и CI одного человека обязаны
-  ретраить независимо.
-
-Если второй пользователь не выставил СВОЙ `CLIPWRIGHT_CLIENT_ID` и его запрос
-(тот же скрипт, те же опции — например, оба используют пример из этого
-SKILL.md дословно) совпадает по входу с чужим уже выполненным раном, сервер
-схлопнёт их в ОДИН ран. Второй пользователь получит 200, `run_id` и играющуюся
-ссылку — но это будет ЧУЖОЕ видео, представленное ему как его собственный
-успех. Это дефект 3.2 плана Этапа 5: диагностический инструмент/установка
-прочитались бы как «работает», хотя платный рендер для второго пользователя
-никогда не запускался.
-
-### Как выставить
-
-Явный `CLIPWRIGHT_CLIENT_ID` в env хоста (раздел 1.3, вариант A/B) — самый
-надёжный путь, не зависящий от состояния файловой системы. Значение — любая
-уникальная строка; для согласованности с генератором SDK используй тот же
-формат (UUID без дефисов):
+| `CLIPWRIGHT_API_KEY` | YES | Bearer token shaped `cw_*`. Without it the process exits immediately with an error (`src/index.ts`). The token is ISSUED TO YOU PERSONALLY: it lives in the `api_tokens` table, is bound to an account, and is revoked independently of anyone else's. Do not forward it — a second person gets their own. What separates people is the ACCOUNT, not the token: accounts cannot see each other's runs, each has its own daily cap and its own idempotency axis, and several tokens on one account share all of it. |
+| `CLIPWRIGHT_API_URL` | no | Production URL. Left unset, the SDK supplies `https://api-production-7e69.up.railway.app` itself. Set it explicitly only when you target another environment. |
+| `CLIPWRIGHT_CLIENT_ID` | YES (see section 2) | Unique identifier of this INSTALLATION. |
+
+After connecting, restart or reopen the MCP host and confirm that `tools/list`
+returns four tools: `make_ugc`, `get_run`, `quote_ugc`, `list_voices`.
+
+## 2. `CLIPWRIGHT_CLIENT_ID` — required, and WHY
+
+**Rule: EVERY installation must get its OWN unique `CLIPWRIGHT_CLIENT_ID` BEFORE
+the first `make_ugc` call.** Do not copy the value from another machine, and do
+not leave it empty hoping the default will "work out somehow".
+
+### Why this is not optional
+
+The idempotency key the SDK stamps on every paid `POST /v1/skills/make_ugc/run`
+is derived deterministically from **the hash of the input** (`script`, `person`,
+`image`, … after canonicalisation) **and the client identity**
+(`idempotencyKeyFor` in `packages/core/src/idempotency.ts`, used by
+`packages/sdk/src/index.ts`). The server deduplicates on that key: if a stored
+key matches on `request_hash`, it returns 200 with the run **created by the first
+request that used the key**, instead of starting a new paid render.
+
+That is the right behaviour when the SAME user retries — you should not pay twice
+for an agent's accidental double click. Its boundaries are these.
+
+Collapsing requires BOTH to match: the account and the `clientId`. Separating
+either one is enough.
+
+- **The account separates by construction.** Both the unique index
+  (`runs_account_idempotency_key_unique`) and the lookup use the pair
+  `(account_id, idempotency_key)`. A run from ANOTHER account can never reach you,
+  and nobody can take your key — whatever sits in `CLIPWRIGHT_CLIENT_ID`.
+  **The axis is the account, not the token.** A separate token does not by itself
+  mean a separate account: several live tokens on one account are normal (laptop,
+  CI, smoke script), and they all share one idempotency axis. The account is not
+  visible from the token — only the service side knows it, so "is this my own
+  account?" is confirmed by whoever issued the token.
+- **`clientId` separates within one account.** On its own it comes from
+  `~/.clipwright/client-id` and is born random on first run, so two genuinely
+  separate installations diverge even without the environment variable. It can
+  only match if it was MADE to match: a shared `HOME`, a value copied from
+  someone else's machine, an image cloned together with the file.
+
+The dangerous case is exactly the crossing of those two conditions: **one account
+AND one `clientId`**. Then a request whose input matches an earlier one — for
+example, both people copied a sample from this SKILL.md verbatim — returns 200, a
+`run_id` and a playable link. But it is the video rendered for the first person,
+presented to the second as their own success. A diagnostic tool would read as
+"works" while no paid render ever ran for the second person.
+
+Hence the rule: **a second person gets their own ACCOUNT and a token issued on
+it**, and the value of `CLIPWRIGHT_CLIENT_ID` is not copied from anyone's machine.
+Setting it explicitly is mandatory wherever the file resolver cannot give a stable
+value of its own: a read-only or shared `HOME`, a container from a cloned image,
+CI.
+
+### How to set it
+
+An explicit `CLIPWRIGHT_CLIENT_ID` in the host environment (section 1.3, variants
+A/B/C) is the most reliable path, because it does not depend on the state of the
+file system. The value is any unique string; for consistency with the SDK's own
+generator use the same shape (a UUID without dashes). Generate it with Node, not
+`uuidgen`: Node is certainly present here, whereas `uuidgen` may be missing on a
+bare Linux image — and then the shell silently substitutes an EMPTY string, which
+switches off precisely the protection the variable exists for.
 
 ```bash
-uuidgen | tr -d '-'
+node -e "console.log(crypto.randomUUID().replaceAll('-',''))"
 ```
 
-Если переменная НЕ задана, `resolveClientId()`
-(`packages/sdk/src/client-id.ts`) падает на файл `~/.clipwright/client-id`:
-при первом запуске генерирует случайный id и сохраняет его туда, дальше читает
-оттуда. Это рабочий фолбэк для одиночной установки на чистой машине, но НЕ
-полагайся на него как на единственную защиту при установке агентом: домашние
-каталоги при клонировании образов/контейнеров/дев-окружений могут унести файл
-`~/.clipwright/client-id` с собой и породить коллизию, которую этот фолбэк
-не заметит. Для установки по этой инструкции — **всегда выставляй
-`CLIPWRIGHT_CLIENT_ID` явно в env хоста**, не полагайся на автогенерацию.
-
-Если ни env, ни запись файла невозможны (read-only `$HOME`), `resolveClientId()`
-намеренно БРОСАЕТ исключение вместо тихого эфемерного id на каждый запуск —
-молчаливый фолбэк убил бы дедупликацию целиком (`packages/sdk/src/client-id.ts:9-19`).
-Если сервер упал с этой ошибкой — это сигнал поставить `CLIPWRIGHT_CLIENT_ID`
-явно, а не искать баг.
-
-## 3. ПОРЯДОК ВЫЗОВОВ — сначала `quote_ugc`, потом `make_ugc`
-
-Это не совет по вежливости, а механизм, без которого контракт молчит о своих
-решениях.
+If the variable is NOT set, `resolveClientId()` (`packages/sdk/src/client-id.ts`)
+falls back to the file `~/.clipwright/client-id`: on first run it generates a
+random id and stores it there, then reads it back. That is a workable fallback for
+a single installation on a clean machine, but do NOT lean on it as your only
+protection when an agent does the install: home directories carried along when
+images, containers or dev environments are cloned can take
+`~/.clipwright/client-id` with them and produce a collision this fallback will not
+notice. When installing by this guide, **always set `CLIPWRIGHT_CLIENT_ID`
+explicitly in the host environment** rather than relying on auto-generation.
+
+If neither the variable nor writing the file is possible (read-only `$HOME`),
+`resolveClientId()` deliberately THROWS instead of inventing a throwaway id on
+every start — a silent fallback would disable deduplication entirely
+(`packages/sdk/src/client-id.ts`).
+
+**The server does NOT die in that case, and this is verified by a test run.** The
+identity resolves lazily — only on the first `make_ugc`. In an environment where
+`~/.clipwright` is not writable the server starts, `tools/list` returns all four
+tools, and `quote_ugc`, `get_run` and `list_voices` work: they do not need the
+identity. Only `make_ugc` refuses, and its refusal names the variable that fixes
+it. So the action to take is to set `CLIPWRIGHT_CLIENT_ID` explicitly — not to
+hunt for a bug and not to reinstall the package.
+
+## 3. CALL ORDER — `quote_ugc` first, `make_ugc` second
+
+This is not a politeness convention but a mechanism, without which the contract
+stays silent about its own decisions.
 
 ```
-quote_ugc  →  прочитать source / resolved_aspect_ratio / warnings  →  make_ugc  →  get_run (поллинг)
+quote_ugc  →  read source / resolved_aspect_ratio / warnings  →  make_ugc  →  get_run (polling)
 ```
 
-**Что даёт `quote_ugc`, чего не даёт ничего другого.** Он бесплатен, ничего не
-резервирует и отвечает на вопросы, которые иначе выяснятся уже после списания:
+**What `quote_ugc` gives you that nothing else does.** It is free, reserves
+nothing, and answers the questions that would otherwise surface only after money
+is spent:
 
-| Поле ответа | Что из него видно |
+| Response field | What it tells you |
 |---|---|
-| `credits_estimate` | цена — покажи её пользователю ДО генерации |
-| `source` | размеры источника кадра: пробленный `image` либо дефолтный актёр (432×768) |
-| `resolved_aspect_ratio` | формат, который РЕАЛЬНО будет отрендерен на этом входе |
-| `warnings[]` | какие переданные параметры не будут соблюдены |
-| `contract_version` | под какой версией контракта получена эта цена |
+| `credits_estimate` | the price — show it to the user BEFORE generating |
+| `source` | dimensions of the source frame: a probed `image`, or the default actor (432×768) |
+| `resolved_aspect_ratio` | the aspect ratio that will ACTUALLY be rendered for this input |
+| `warnings[]` | which of the parameters you passed will not be honoured |
+| `contract_version` | which contract version this price was quoted under |
 
-**Вердикт `quote_ugc` и вердикт `make_ugc` совпадают по построению** — обе
-поверхности зовут одну функцию. Если quote вернул 400, ран вернёт тот же 400;
-если quote показал `resolved_aspect_ratio: "9:16"` на запрошенном `1:1`, то
-именно 9:16 и отрендерится.
+**The verdict of `quote_ugc` and the verdict of `make_ugc` agree by
+construction** — both surfaces call the same function. If quote returns 400, the
+run returns the same 400; if quote showed `resolved_aspect_ratio: "9:16"` for a
+requested `1:1`, then 9:16 is what gets rendered.
 
-**Отклонённые поля — не пытайся их передавать.** Они не объявлены в схеме тула,
-и сервер отвечает 400 `rejected_field` ещё до создания рана:
+**Rejected fields — do not try to pass them.** They are not declared in the tool
+schema, and the server answers 400 `rejected_field` before a run is even created:
 
-| Поле | Чем заменить |
+| Field | Use instead |
 |---|---|
-| `character` | `person` — описание актёра словами, или ничего (дефолтный актёр) |
-| `webhook_url` | поллинг `get_run` — вебхуки не доставляются вообще |
-| `segments`, `broll_url` | одним `script`; сегментные ролики ещё не доступны |
-| `disclosure_overlay` | ничем: маркировка уже есть в ответе рана и в самом файле |
-| `image` при выключенном килсвитче | опустить — рендер пойдёт на дефолтном актёре |
+| `character` | `person` — describe the actor in words, or nothing (default actor) |
+| `webhook_url` | poll `get_run` — webhooks are not delivered at all |
+| `segments`, `broll_url` | a single `script`; segmented clips are not available yet |
+| `disclosure_overlay` | nothing: the AI disclosure is already in the run response and in the file |
+| `image` with the killswitch off | omit it — the render runs on the default actor |
 
-**Формат может быть отклонён.** Запрос `aspect_ratio: "1:1"` без `image`
-вернёт отказ: дефолтный актёр вертикальный (432×768), и квадратный кадр из
-него получился бы только центр-кропом вендора, чего мы не делаем молча. Чтобы
-получить `1:1`, передай `image` с квадратным публичным https-источником.
+**The aspect ratio can be refused.** Requesting `aspect_ratio: "1:1"` without an
+`image` returns a refusal: the default actor is vertical (432×768), and a square
+frame could only come from the vendor's centre crop, which we do not do silently.
+To get `1:1`, pass an `image` with a square public https source.
 
-## 4. Четыре тула
+## 4. The four tools
 
-Схемы — единый источник правды `@clipwright/core`
-(`packages/core/src/skills.ts`, барррель `packages/core/src/index.ts`), MCP их
-не переписывает руками (`packages/mcp-server/src/index.ts:6-8`).
+Schemas come from the single source of truth `@clipwright/core`
+(`packages/core/src/skills.ts`, barrel `packages/core/src/index.ts`); MCP does not
+retype them by hand.
 
-### `quote_ugc` — бесплатно
+### `quote_ugc` — free
 
-Вход — `offeredUgcInputShape` (`packages/mcp-server/src/server.ts`), то есть
-контракт МИНУС отклонённые поля: их там просто нет, и перечислять их здесь
-значило бы предлагать то, за что сервер накажет (раздел 3).
+The input is `offeredUgcInputShape` (`packages/mcp-server/src/server.ts`), that
+is, the contract MINUS the rejected fields: they simply are not there, and listing
+them here would mean offering what the server punishes you for (section 3).
 
-`script` (≤10000 симв., счёт слов ≤`MAX_SCRIPT_WORDS` ≈45 с речи; формально
-`.optional()`, но обязателен, пока `segments` отклонён), опционально `person`
-ИЛИ `image` (публичный `https`-URL), плюс `name`, `captions` (по умолчанию
-`false` — **субтитры opt-in, СНАЧАЛА спроси пользователя**), `caption_style`
+`script` (≤10000 chars, word count ≤`MAX_SCRIPT_WORDS` ≈45 s of speech; formally
+`.optional()`, but required while `segments` is rejected), optionally `person` OR
+`image` (a public `https` URL), plus `name`, `captions` (defaults to `false` —
+**captions are opt-in, ASK THE USER FIRST**), `caption_style`
 (`hormozi`/`tiktok`/`minimal`), `look` (`natural`/`commercial`/`raw_iphone`),
-`aspect_ratio` (`9:16`/`1:1`, БЕЗ дефолта — молчание и явный выбор различаются),
-`resolution` (`720p`/`1080p`/`4k`), `voice`/`voice_id`.
+`aspect_ratio` (`9:16`/`1:1`, with NO default — silence and an explicit choice
+differ), `resolution` (`720p`/`1080p`/`4k`), `voice`/`voice_id`.
 
-Точный список всегда доступен из самой схемы тула: `tools/list` порождается из
-того же shape, и поля, которые не соблюдаются, несут `NOT HONORED YET` прямо в
-своём `description`.
+The exact list is always available from the tool schema itself: `tools/list` is
+generated from the same shape, and fields that are not honoured carry
+`NOT HONORED YET` right in their own `description`.
 
-Не тратит кредиты. Ответ — необработанный `quote` целиком
-(`packages/mcp-server/src/server.ts`):
+Spends no credits. The response is the raw `quote` in full:
 
 ```json
 {
@@ -306,20 +326,19 @@ quote_ugc  →  прочитать source / resolved_aspect_ratio / warnings
 }
 ```
 
-`warnings[]` здесь ПРИСУТСТВУЕТ (передаётся без фильтрации) — читай его:
-несоблюдённые параметры (например, `captions` проигнорирован в этой сборке)
-объявляются сюда, а не молча теряются.
+`warnings[]` IS present here (passed through unfiltered) — read it: parameters
+that will not be honoured (for example, `captions` ignored in this build) are
+declared there rather than dropped silently.
 
-**Всегда вызывай `quote_ugc` первым и покажи пользователю цену до `make_ugc`**
-(императив в описании тула, `packages/mcp-server/src/index.ts:83-85`).
+**Always call `quote_ugc` first and show the user the price before `make_ugc`**
+(the tool description says so in the imperative).
 
-### `make_ugc` — платный, создаёт ран
+### `make_ugc` — paid, creates a run
 
-Вход — тот же `makeUgcInputShape` + `attempt` (целое ≥1, опционален; см.
-раздел 4). Денежный контур: это ОДИН платный рендер за вызов (если не сработал
-дедуп идемпотентности — раздел 4). **Тул НЕ ждёт готовности видео** — он
-стартует ран и немедленно возвращает `run_id`
-(`packages/mcp-server/src/index.ts:28-29,39-40`):
+The input is the same shape plus `attempt` (an integer ≥1, optional; see section
+5). Money: this is ONE paid render per call, unless idempotency deduplication kicks
+in (section 2). **The tool does NOT wait for the video** — it starts the run and
+returns a `run_id` immediately:
 
 ```json
 {
@@ -331,36 +350,35 @@ quote_ugc  →  прочитать source / resolved_aspect_ratio / warnings
 }
 ```
 
-Дальше ОБЯЗАТЕЛЬНО поллить `get_run` этим `run_id` каждые ~5–10 секунд до
-терминала. Не сообщай пользователю, что видео готово, пока не получил
+After that you MUST poll `get_run` with that `run_id` every ~5–10 seconds until it
+reaches a terminal state. Do not tell the user the video is ready until you have a
 `video_url`.
 
-#### Выбор голоса (`voice` / `voice_id`)
-
-Два взаимоисключающих опциональных поля во входе `make_ugc`:
+#### Choosing a voice (`voice` / `voice_id`)
 
-- `voice` — имя **курируемого пресета**. **Рекомендуемый путь.** Список — тул
-  `list_voices` (бесплатный): `owner_ru_clone`, `sarah`, `george`, `eric`,
-  `daria_ru_female`. Валидируется на границе: неизвестное имя → 400 сразу,
-  платный вызов не создаётся.
-- `voice_id` — **сырой ElevenLabs id** (20-символьный), escape hatch для
-  голосов ВНЕ каталога, включая клонированные. Проверяется бесплатно против
-  аккаунта в начале рана (не на `quote`): несуществующий id → ран `failed` ДО
-  единого платного вызова.
-- **Ни одного не задавай без просьбы пользователя.** Голос по умолчанию уже
-  подобран под текущий аватар; менять его не нужно. `list_voices` — курируемый
-  каталог по дизайну, не полный список голосов вендора.
+Two mutually exclusive optional fields in the `make_ugc` input:
 
-Детали и инвариант «неверный голос не стоит денег» — `docs/16-voice-selection.md`.
+- `voice` — the name of a **curated preset**. **The recommended path.** The list
+  comes from the free `list_voices` tool: `owner_ru_clone`, `sarah`, `george`,
+  `eric`, `daria_ru_female`. Validated at the boundary: an unknown name returns
+  400 immediately and no paid call is made.
+- `voice_id` — a **raw ElevenLabs id** (20 characters), an escape hatch for voices
+  OUTSIDE the catalog, cloned ones included. It is checked for free against the
+  account at the start of the run (not during `quote`): a non-existent id fails the
+  run BEFORE any paid call.
+- **Set neither unless the user asks.** The default voice is already matched to
+  the current avatar; there is no need to change it. `list_voices` is a curated
+  catalog by design, not the vendor's full voice list.
 
-### `get_run` — поллинг статуса
+### `get_run` — status polling
 
-Вход: `{ "run_id": "run_..." }`. Форма ответа реализована в
-`packages/mcp-server/src/format.ts` (`formatGetRun`) — ниже она приведена
-ФАКТИЧЕСКИ, после исправления US-501.
+Input: `{ "run_id": "run_..." }`. The response shape is implemented in
+`packages/mcp-server/src/format.ts` (`formatGetRun`) and is given below as it
+actually is.
 
-**Нетерминальный ран** (`queued`/`scripting`/`tts`/`avatar`/`compositing`/`uploading`)
-несёт `state` стадии, `status` всегда `"IN_PROGRESS"`:
+**A non-terminal run**
+(`queued`/`scripting`/`tts`/`avatar`/`compositing`/`uploading`) carries the stage
+in `state`, with `status` always `"IN_PROGRESS"`:
 
 ```json
 {
@@ -372,9 +390,7 @@ quote_ugc  →  прочитать source / resolved_aspect_ratio / warnings
 }
 ```
 
-**Терминальный успех** несёт И `status: "SUCCEEDED"`, И `state: "succeeded"`
-(до US-501 `state` в терминальной успешной ветке отсутствовал — грабля №4
-`docs/14-gate4-heygen.md:75-79` — теперь это исправлено, поле есть всегда):
+**Terminal success** carries BOTH `status: "SUCCEEDED"` AND `state: "succeeded"`:
 
 ```json
 {
@@ -386,155 +402,256 @@ quote_ugc  →  прочитать source / resolved_aspect_ratio / warnings
 }
 ```
 
-**Терминальный отказ** несёт И `status: "FAILED"`, И `state: "failed"`:
+**Terminal failure** carries BOTH `status: "FAILED"` AND `state: "failed"`:
 
 ```json
 {
   "status": "FAILED",
   "run_id": "run_...",
   "state": "failed",
-  "error": "<текст ошибки>"
+  "error": "<error text>"
 }
 ```
 
-**`warnings[]` в `get_run`:** каждая ветка ответа (`IN_PROGRESS`, `SUCCEEDED`,
-`FAILED`) несёт `warnings` рана (US-512; правило проекта №3 — несоблюдённые
-параметры объявляются, никогда молча). Читай его на терминале обязательно:
-например, отсутствие субтитров в прототипе объявляется именно здесь.
+**`warnings[]` in `get_run`:** every branch of the response (`IN_PROGRESS`,
+`SUCCEEDED`, `FAILED`) carries the run's `warnings` — parameters that were not
+honoured are always declared, never dropped silently. Read it on the terminal
+response without fail: for instance, missing captions in the prototype are
+announced exactly there.
 
-**Неизвестный терминальный статус на сервере** (например гипотетический
-`"canceled"`, не входящий в `TERMINAL_STATES`) — осознанная деградация:
-`isTerminal` вернёт `false`, и такой ран попадёт в ветку `IN_PROGRESS` (агенту
-скажут «продолжай поллить» про уже завершённый ран). Это принятое поведение
-прототипа (MCP и API деплоятся одной версией), не баг форматтера.
+**An unknown terminal status on the server** (say a hypothetical `"canceled"` that
+is not in `TERMINAL_STATES`) is a deliberate degradation: `isTerminal` returns
+`false`, so such a run lands in the `IN_PROGRESS` branch and the agent is told to
+keep polling a run that has already finished. That is accepted prototype behaviour
+— MCP and the API ship as one version — not a formatter bug.
 
-### `list_voices` — бесплатно, без входа
+### `list_voices` — free, no input
 
-Отдаёт курируемый каталог пресетов для поля `voice` у `make_ugc`
-(`packages/mcp-server/src/server.ts`, регистрация четвёртым; `inputSchema: {}` —
-аргументов нет). Денег не стоит и рана не создаёт.
+Returns the curated preset catalog for the `voice` field of `make_ugc`
+(`inputSchema: {}` — it takes no arguments). Costs nothing and creates no run.
 
-Сетевой вызов при этом есть: тула ходит в НАШ `/v1/voices` и требует рабочий
-`CLIPWRIGHT_API_KEY`, как и остальные три. К вендору не ходит никто — список
-статический и живёт в `packages/core/src/voices.ts`, поэтому вендорский ключ на
-этой поверхности не нужен.
+There is still a network call: the tool hits OUR `/v1/voices` and needs a working
+`CLIPWRIGHT_API_KEY`, like the other three. Nobody calls the vendor — the list is
+static and lives in `packages/core/src/voices.ts`, so no vendor key is needed on
+this surface.
 
-Зови его до `make_ugc`, если пользователь просит «другой голос»: имя пресета
-предпочтительнее сырого `voice_id`, потому что пресет переживает смену вендора,
-а идентификатор — нет (раздел про `voice`/`voice_id` выше).
+Call it before `make_ugc` when the user asks for "a different voice": a preset
+name is preferable to a raw `voice_id`, because a preset survives a change of
+vendor and an identifier does not.
 
-## 5. Повтор упавшего рана — это НЕ перманентный отказ
+## 5. Retrying a failed run is NOT a permanent refusal
 
-Если `get_run` вернул терминальный `FAILED` и ты вызываешь `make_ugc` СНОВА с
-ТЕМ ЖЕ входом (тот же `script`/опции) и БЕЗ изменения `attempt` — сервер
-вернёт ТОТ ЖЕ терминальный `failed`-ран как есть (та же ошибка, тот же
-`run_id`), а НЕ запустит новый платный рендер. Это дедупликация по ключу
-идемпотентности (раздел 2), а не признак того, что видео навсегда
-недостижимо.
+If `get_run` returned a terminal `FAILED` and you call `make_ugc` AGAIN with the
+SAME input (same `script` and options) and WITHOUT changing `attempt`, the server
+returns THAT SAME terminal failed run as it is (same error, same `run_id`) instead
+of starting a new paid render. That is idempotency deduplication (section 2), not
+a sign that the video is forever out of reach.
 
-**Чтобы реально повторить попытку, передай `attempt` со значением на единицу
-больше предыдущего** (по умолчанию первый вызов имеет `attempt=1`; для второй
-попытки — `attempt: 2`, для третьей — `attempt: 3`, и т.д.). Это дословно
-поведение, задокументированное в описании тула `make_ugc`
-(`packages/mcp-server/src/index.ts:29-30`):
+**To actually retry, pass `attempt` one higher than before** (the first call is
+`attempt=1` by default; the second attempt is `attempt: 2`, the third `attempt: 3`,
+and so on). This is the behaviour documented verbatim in the `make_ugc` tool
+description:
 
 > "Pass attempt=2,3,… to deliberately start a NEW run for the same input
 > (retry after a failure)."
 
-Технически `attempt` уходит не в тело рендер-запроса, а в опции SDK
-(`packages/mcp-server/src/index.ts:35-40`) и превращается в суффикс
-`:N` у ключа идемпотентности (`packages/sdk/src/index.ts:104-115`) — другой
-суффикс даёт другой ключ → сервер видит НОВЫЙ запрос → новый `run_id` → новый
-платный вызов вендора.
+Technically `attempt` does not go into the render request body but into the SDK
+options, and becomes a `:N` suffix on the idempotency key — a different suffix
+gives a different key, so the server sees a NEW request, which means a new
+`run_id` and a new paid vendor call.
+
+Do not confuse this with `CLIPWRIGHT_CLIENT_ID`: `attempt` is the agent's
+deliberate "this is a new attempt", while `clientId` is the fixed identity of the
+installation and must NOT change between attempts.
+
+### ⚠️ EVERY `attempt` BUMP COSTS MONEY
+
+A new `attempt` is a new run and a **new paid vendor call**, not a free resend.
+The loop "failed → bump → failed → bump" burns real credits on every iteration.
+
+So:
+
+- **read the `error` of the failed run before retrying.** Refusals such as
+  `rejected_field`, `aspect_conflict` or `daily_cap_exceeded` are NOT fixed by
+  retrying — they are determined by the input or by a cap, and the next attempt
+  fails the same way, only now for money;
+- **bump `attempt` only for a refusal that looks temporary** (vendor timeout, 5xx,
+  a dropped connection);
+- **the cap exists and it is daily.** Exhausting it gives you
+  `daily_cap_exceeded` — that is a protection doing its job, not a broken product.
+  Wait for the next day or ask the owner to raise the limit.
+
+## 5.1. Server refusals are read from fields, not guessed (0.2.0)
+
+Since 0.2.0 an API refusal carries structured fields instead of one free-form
+sentence. It still arrives the way every tool result does — as JSON **inside the
+text block**, with `isError: true`:
+
+```ts
+{ content: [{ type: "text", text: "{\"status\":\"FAILED\", …}" }], isError: true }
+```
+
+So `JSON.parse(content[0].text)` first, then read the fields below. Reading
+`content[0].balance_credits` gives `undefined`: the numbers are inside the parsed
+text, not beside it. Do not relay the raw text to the user and do not guess from
+it.
+
+```json
+{
+  "status": "RETRY_LATER" | "FAILED",
+  "code": "rate_limited" | "insufficient_credits" | "debt_outstanding" | "http_503" | …,
+  "message": "<human-readable text from the server>",
+  "retryable": true | false,
+  "next_action": "<what to do right now>",
+  "retry_after_seconds": 7,
+  "balance_credits": 3,
+  "required_credits": 8,
+  "debt_credits": 120
+}
+```
+
+Numeric fields appear only where the refusal actually has them:
+
+| Field | Appears on |
+| --- | --- |
+| `retry_after_seconds` | `rate_limited`, and any `http_5xx` where the server named a pause |
+| `limit`, `window_seconds` | only when the 429 body followed the Clipwright contract; a 429 whose body did not carries neither |
+| `balance_credits`, `required_credits` | `insufficient_credits` only |
+| `debt_credits` | `debt_outstanding` only |
+
+Treat every one of them as optional and read what is there. In particular, do not
+expect balance numbers on `debt_outstanding`: that refusal reports the debt, and
+the balance is not what blocks the run.
+
+**One rule: look at `retryable`.**
+
+- `retryable: true` (`rate_limited`, 5xx) — wait `retry_after_seconds` and repeat
+  **THE SAME call with the same arguments**. Do not bump `attempt`: this is not a
+  failed run but a refused request, and a new `attempt` would mean a second paid
+  render (section 5).
+- `retryable: false` (`insufficient_credits`, `debt_outstanding`, other 4xx) —
+  **stop and tell the human**. A repeat gives the same answer while eating into
+  the rate limit. For money refusals, quote the NUMBERS: "the account has 3
+  credits, this needs 8" — without them the human cannot tell how much to buy.
+
+The two money codes differ in their cure and must not be conflated:
+`insufficient_credits` means "top up the balance", `debt_outstanding` means
+"settle the debt", and topping up does NOT clear a debt. Advising "buy credits" on
+the second code sends the human to spend money for nothing.
 
-Не путай это с `CLIPWRIGHT_CLIENT_ID`: `attempt` — сознательное решение агента
-«это новая попытка», а `clientId` — фиксированная идентичность установки, её
-менять между попытками НЕ нужно.
+Do not read a source into the refusal. A `429` or a `5xx` can come from the
+Clipwright API itself or from anything between you and it, and the fields above
+cannot tell you which — so the report does not claim one, and neither should you
+when relaying it. What is certain is the code and what to do about it.
 
-### ⚠️ КАЖДЫЙ БАМП `attempt` СТОИТ ДЕНЕГ
+About `429` specifically: it does **not** mean no run was created. The rate limit
+sits in front of the handler, so a repeat carrying an already-used idempotency key
+gets one too. Retry with THE SAME key — a new key is a new paid render.
 
-Новый `attempt` — это новый ран и **новый платный вызов вендора**, а не
-бесплатная переотправка. Цикл «упало → бампнул → упало → бампнул» тратит
-реальные кредиты на каждой итерации.
+**Nobody waits on your behalf here — you do the polling.** `get_run` makes one
+call and hands you whatever came back, refusals included. So a `429` on a status
+check is yours to sit out: wait `retry_after_seconds`, then call `get_run` again
+with the same `run_id`. Do not treat it as a failed run and do not start a new
+one — the run is already running and already paid for.
 
-Поэтому:
+(The SDK's own `makeUgc` does wait these out internally, which is why the CLI and
+direct SDK users never see them. The MCP tools are deliberately thin: `make_ugc`
+returns as soon as the run starts, so a long render never blocks your turn.)
 
-- **перед повтором прочитай `error` упавшего рана.** Отказы вида
-  `rejected_field`, `aspect_conflict`, `daily_cap_exceeded` повтором НЕ
-  чинятся — они детерминированы входом или потолком, и следующая попытка
-  упадёт так же, только уже за деньги;
-- **бампай `attempt` только при отказе, похожем на временный** (таймаут
-  вендора, 5xx, обрыв сети);
-- **потолок существует и он суточный.** Исчерпав его, ты получишь
-  `daily_cap_exceeded` — это сработавшая защита, а не поломка продукта.
-  Дожидаться следующих суток или просить владельца поднять лимит.
+## 6. On failure — plain curl as a diagnosis splitter
 
-## 6. При отказе — curl-скрипт как разделитель диагнозов
+If the MCP path does not get you to a playable video, hit the same public REST
+directly with curl, bypassing MCP, SDK and CLI entirely. If curl gets through, the
+packaging layer is at fault; if it does not, production or the network is.
 
-Если MCP-путь не доводит до играющегося видео, запусти
-`scripts/clipwright-smoke.sh` (US-506) — он бьёт по тому же публичному REST
-`POST /v1/skills/make_ugc/run` → `GET /v1/runs/{id}` напрямую curl'ом, в обход
-MCP/SDK/CLI целиком:
+**Two commands, no repository needed** (the package is installed from npm and
+carries no scripts):
 
 ```bash
-CLIPWRIGHT_API_TOKEN=cw_... ./scripts/clipwright-smoke.sh "Привет! Тестовая фраза."
+TOKEN=cw_...                       # the same value as CLIPWRIGHT_API_KEY, section 1.3
+API=https://api-production-7e69.up.railway.app
+
+# 1. Start a run. The idempotency key is required and must be UNIQUE per call:
+#    a repeated key returns the earlier run instead of a new one (section 2).
+#    Generate it with Node, not uuidgen: Node is certainly here (the package is
+#    installed via npx), while uuidgen may be missing on a bare Linux image — and
+#    then the shell silently substitutes an empty string, the key becomes
+#    constant, and a second run returns the earlier one, ruining exactly the
+#    diagnosis you started it for.
+curl -sS -X POST "$API/v1/skills/make_ugc/run" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "Idempotency-Key: cw-$(node -e 'process.stdout.write(crypto.randomUUID())')" \
+  -d '{"script":"Hello! This is a test line."}'
+
+# 2. Poll until terminal, every ~5–10 s.
+curl -sS "$API/v1/runs/<run_id>" -H "Authorization: Bearer $TOKEN"
 ```
 
-(`CLIPWRIGHT_API_TOKEN` — то же значение, что `CLIPWRIGHT_API_KEY` в env MCP,
-см. раздел 1.3; `CLIPWRIGHT_API_URL` опционален, тот же дефолт-прод.)
-
-Диагноз по результату:
-
-- **curl доходит до `succeeded` со своим `run_id` и играющейся ссылкой, а MCP —
-  нет:** первопричина в слое MCP-пакетирования (сборка/конфиг хоста/env,
-  раздел 1) — не в REST API и не в доступе/токене. Это допустимое закрытие с
-  документированным остаточным (курл-гейт Architect, US-511).
-- **curl тоже падает:** проблема не в MCP — проверь `CLIPWRIGHT_API_TOKEN`
-  (формат `cw_*`, не обрезан при копировании), сетевой доступ к
-  `$CLIPWRIGHT_API_URL`, и (для истории про клонированные раны) что
-  `CLIPWRIGHT_CLIENT_ID` реально уникален на этой машине (раздел 2) — если
-  ответ 200 с ЧУЖИМ по смыслу `run_id`, это симптом дефекта 3.2 на MCP-пути,
-  который curl (у него собственный, случайный `Idempotency-Key` на каждый
-  вызов — `scripts/clipwright-smoke.sh:112`) не воспроизведёт напрямую, но
-  который стоит проверить отдельно через `get_run` на этот `run_id`.
-
-Скрипт также поддерживает бесплатный `--poll-only <run_id>` для проверки уже
-существующего рана без нового платного вызова.
-
-## Итоговая последовательность (что должно воспроизвестись)
-
-1. Установить сервер: `npx -y -p @clipwright/mcp-server@latest clipwright-mcp`
-   стартует и печатает `running on stdio` (раздел 1.1). Из исходников —
-   `pnpm install && pnpm build` из корня репо → `dist/index.js` существует.
-2. Сгенерировать уникальный `CLIPWRIGHT_CLIENT_ID` (раздел 2) и прописать его
-   вместе с `CLIPWRIGHT_API_KEY` в конфиг MCP-хоста (раздел 1.3).
-3. Перезапустить хост, убедиться, что `tools/list` отдаёт 4 тула
-   (`make_ugc`, `quote_ugc`, `get_run`, `list_voices`).
-4. `quote_ugc` со скриптом → показать цену И прочитать `source`,
-   `resolved_aspect_ratio`, `warnings[]` (раздел 3).
-5. `make_ugc` → получить `run_id` немедленно.
-6. `get_run` каждые ~5–10 с, читая `state` в процессе и `status`+`state` на
-   терминале, до `SUCCEEDED` (`video_url`) или `FAILED` (`error`).
-7. При отказе — `scripts/clipwright-smoke.sh` (раздел 6) для разделения
-   диагнозов.
-
-### Если ты — второй пользователь, проверяющий продукт
-
-Задача одна: **дойти до играющегося видео по этому файлу, без устной помощи
-владельца.** Проверяется не ты, а полнота инструкции — поэтому не спрашивай,
-а записывай, где застрял.
-
-Перед началом убедись, что в конфиге стоит **твой собственный**
-`CLIPWRIGHT_CLIENT_ID` (раздел 2). Без него сервер вернёт РАН ВЛАДЕЛЬЦА с
-ответом 200 и играющей ссылкой — то есть ложный успех, который выглядит
-убедительнее настоящего.
-
-Отличай два класса отказа, они чинятся по-разному:
-
-- **`rejected_field`, `aspect_conflict`, `daily_cap_exceeded`** — это
-  сработавший контракт или сработавшая защита, а не дефект. Прочитай текст
-  ошибки: в нём назван и повод, и замена;
-- **всё остальное** (таймаут, 5xx, пустой ответ, тул не найден) — кандидат в
-  настоящие дефекты. Здесь запусти `scripts/clipwright-smoke.sh`: если curl
-  доходит до играющейся ссылки, а MCP нет — причина в слое упаковки MCP, и это
-  надо записать отдельно от остального.
+Reading the result:
+
+- **curl reaches `succeeded` with its own `run_id` and a playable link, but MCP
+  does not:** the root cause is in the MCP packaging layer (build, host config,
+  environment — section 1), not in the REST API and not in access or the token.
+- **curl fails too:** the problem is not MCP. Check `$TOKEN` from the commands
+  above (shaped `cw_*`, not truncated when copied), network access to `$API`, and —
+  for the cloned-run story — that `CLIPWRIGHT_CLIENT_ID` really is unique on this
+  machine (section 2). If you get a 200 with a `run_id` that is not yours in
+  substance, that is the symptom of the collapse described in section 2 on the MCP
+  path; curl (which uses its own random `Idempotency-Key` per call) will not
+  reproduce it directly, but it is worth checking separately via `get_run` on that
+  `run_id`.
+
+The second request above — `GET /v1/runs/{id}` — is free: you can poll an existing
+run as often as you like without making a new paid call.
+
+## The whole sequence (what must reproduce)
+
+1. Install the server: `npx -y -p @clipwright/mcp-server@latest clipwright-mcp`
+   starts and prints `running on stdio` (section 1.1). From source:
+   `pnpm install && pnpm build` in the repository root, then `dist/index.js`
+   exists.
+2. Generate a unique `CLIPWRIGHT_CLIENT_ID` (section 2) and put it, together with
+   `CLIPWRIGHT_API_KEY`, into the MCP host config (section 1.3).
+3. Restart the host and confirm `tools/list` returns 4 tools (`make_ugc`,
+   `quote_ugc`, `get_run`, `list_voices`).
+4. `quote_ugc` with a script → show the price AND read `source`,
+   `resolved_aspect_ratio`, `warnings[]` (section 3).
+5. `make_ugc` → get a `run_id` immediately.
+6. `get_run` every ~5–10 s, reading `state` along the way and `status` + `state` on
+   the terminal response, until `SUCCEEDED` (`video_url`) or `FAILED` (`error`).
+7. On failure — the same two curl commands from section 6 to split the diagnosis.
+
+### If you are a second user evaluating the product
+
+You have one task: **reach a playable video using this file, without spoken help
+from the owner.** What is being tested is the completeness of the guide, not you —
+so do not ask, write down where you got stuck.
+
+Before you start, make sure of two different things.
+
+1. **The token was issued on YOUR account, not merely as a separate token.** The
+   idempotency axis is `account_id`, and one account can hold several live tokens.
+   Your own account means another person's run cannot reach you at all. You cannot
+   check this from your side: the account behind a token is visible only to the
+   service. So the confirmation that the token was issued on a SEPARATE account
+   comes WITH the token — it is part of handing it over, not a question for the
+   owner. If it did not come, that is a gap in the instructions: write it down and
+   move on, no need to ask.
+2. **`CLIPWRIGHT_CLIENT_ID` was not copied from anyone's machine** (section 2). It
+   matters WITHIN an account: if you and the owner ended up on one account (even
+   under different tokens) AND your `clientId` matched, the server returns THE
+   OWNER'S RUN with a 200 and a playable link — a false success that looks more
+   convincing than a real one. It can match through a shared `HOME`, a copied
+   value, or a cloned image; a genuinely separate installation has its own even
+   without the environment variable.
+
+Tell two classes of failure apart, because they are fixed differently:
+
+- **`rejected_field`, `aspect_conflict`, `daily_cap_exceeded`** — a contract or a
+  protection doing its job, not a defect. Read the error text: it names both the
+  reason and the replacement;
+- **everything else** (timeout, 5xx, empty response, tool not found) — a candidate
+  for a real defect. Here, run the same two curl commands from section 6: if curl
+  reaches a playable link and MCP does not, the cause is in the MCP packaging
+  layer, and that should be written down separately from the rest.