@agentmedia/schema 0.3.0 → 0.5.0

package/scripts/generate-v2-docs.ts

@@ -0,0 +1,548 @@
+#!/usr/bin/env tsx
+// Copyright 2026 agent-media contributors. Apache-2.0 license.
+
+/**
+ * Generate v2 docs + SKILL.md from V2_GENERATORS.
+ *
+ * Reads packages/schema/src/v2/generators.ts and emits:
+ *   - docs/v2/api-reference.md   — Markdown reference for the v2 REST surface
+ *   - skills/agent-media-v2/SKILL.md  — Claude skill file pointing only at v2
+ *
+ * Both files are derived. Hand edits get blown away on the next run — the
+ * single source of truth is the registry.
+ */
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import {
+  V2_GENERATORS,
+  V2_SHOT_PRESETS,
+  V2_VIBES,
+  quoteV2Credits,
+  type V2GeneratorRecord,
+} from '../src/v2/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, '../../..');
+
+const DOCS_OUT = resolve(repoRoot, 'docs/v2/api-reference.md');
+const SKILL_OUT = resolve(repoRoot, 'skills/agent-media-v2/SKILL.md');
+
+const GENERATED_NOTE = `<!--
+  AUTO-GENERATED — do not hand-edit.
+  Source: packages/schema/src/v2/generators.ts
+  Regenerate: pnpm --filter @agentmedia/schema gen:v2-docs
+-->`;
+
+// ── Markdown helpers ───────────────────────────────────────────────────────
+
+function fmtInputSchema(def: V2GeneratorRecord): string {
+  const schema = zodToJsonSchema(def.inputSchema, {
+    name: `${def.id}_input`,
+    $refStrategy: 'none',
+  }) as {
+    definitions?: Record<string, { properties?: Record<string, unknown>; required?: string[] }>;
+  };
+  const body = schema.definitions?.[`${def.id}_input`] ?? (schema as any);
+  return '```json\n' + JSON.stringify(body, null, 2) + '\n```';
+}
+
+function fmtPricing(def: V2GeneratorRecord): string {
+  if (!def.pricing) return '_Pricing not declared on this generator._';
+  if (def.pricing.basis === 'one_shot') {
+    const c = def.pricing.baseCredits;
+    return `One-shot: **${c} credits** ($${(c / 100).toFixed(2)})`;
+  }
+  // per_clip — show 5/10/15
+  const rows = [5, 10, 15].map((s) => {
+    const c = quoteV2Credits(def.id as any, { durationSeconds: s });
+    return `| ${s}s | ${c} | $${(c / 100).toFixed(2)} |`;
+  });
+  return `Per-clip (base ${def.pricing.baseCredits} + ${def.pricing.perSecondCredits}/sec):\n\n| Duration | Credits | USD |\n|---|---:|---:|\n${rows.join('\n')}`;
+}
+
+// ── docs/v2/api-reference.md ──────────────────────────────────────────────
+
+function renderApiReference(): string {
+  const generators = Object.values(V2_GENERATORS);
+
+  const toc = generators
+    .map((g) => `- [\`${g.rest?.method ?? ''} ${g.rest?.path ?? '(internal)'}\` — ${g.summary}](#${g.id})`)
+    .join('\n');
+
+  const sections = generators
+    .map((g) => {
+      const status = g.status === 'beta' ? ' · _beta_' : '';
+      return [
+        `## ${g.id}${status}`,
+        '',
+        `\`${g.rest?.method ?? ''} ${g.rest?.path ?? '(internal)'}\``,
+        '',
+        g.description,
+        '',
+        '### Pricing',
+        '',
+        fmtPricing(g),
+        '',
+        '### Request body',
+        '',
+        fmtInputSchema(g),
+        '',
+        '### Response',
+        '',
+        g.output === 'video_url'
+          ? 'Returns a job submission. Poll `GET /v1/videos/{job_id}` until `status: "completed"`; the final row carries `video_url`.'
+          : 'Returns a job submission. Poll `GET /v1/videos/{job_id}` until `status: "completed"`; the final row carries the new `character_id` (`char_xxxxxxxxxx`).',
+        '',
+        '#### Submission (201)',
+        '',
+        '```json',
+        JSON.stringify(
+          {
+            job_id: '<uuid>',
+            status: 'submitted',
+            credits_deducted: g.pricing
+              ? g.pricing.basis === 'one_shot'
+                ? g.pricing.baseCredits
+                : g.pricing.baseCredits + g.pricing.perSecondCredits * 8
+              : 0,
+            generator: g.id,
+          },
+          null,
+          2,
+        ),
+        '```',
+        '',
+        ...(g.cli?.examples?.length
+          ? [
+              '### CLI examples',
+              '',
+              '```bash',
+              ...g.cli.examples,
+              '```',
+              '',
+            ]
+          : []),
+      ].join('\n');
+    })
+    .join('\n---\n\n');
+
+  return [
+    GENERATED_NOTE,
+    '',
+    '# agent-media v2 — API reference',
+    '',
+    '_Public REST surface for v2 generators (Selfie, Character). Auth is a Bearer API key (`ma_xxx`)._',
+    '',
+    '**Base URL:** `https://api.agent-media.ai`',
+    '',
+    '## Endpoints',
+    '',
+    toc,
+    '',
+    '---',
+    '',
+    sections,
+    '## Shared',
+    '',
+    '### Authentication',
+    '',
+    'Every v2 request sends `Authorization: Bearer ma_xxx`. Get a key via `agent-media login` (CLI) or the dashboard.',
+    '',
+    '### Polling',
+    '',
+    '`GET /v1/videos/{job_id}` returns the same shape for v1 and v2 jobs. v2-specific fields:',
+    '',
+    '- `character_id` — present on jobs that create a v2 character (`char_xxxxxxxxxx`).',
+    '- `video_url` — present on completed video jobs.',
+    '',
+    '### Shot grammar (Selfie)',
+    '',
+    `Selfie's \`preset\` field accepts one of:`,
+    '',
+    V2_SHOT_PRESETS.map((p) => `- \`${p}\``).join('\n'),
+    '',
+    `Or \`custom-scene:<text>\` to compose a new shot ad-hoc.`,
+    '',
+    '### Vibes (Selfie)',
+    '',
+    V2_VIBES.map((v) => `- \`${v}\``).join('\n'),
+    '',
+  ].join('\n');
+}
+
+// ── skills/agent-media-v2/SKILL.md ─────────────────────────────────────────
+
+function renderSkill(): string {
+  const generators = Object.values(V2_GENERATORS);
+  const generatorBlocks = generators
+    .map((g) => {
+      const cliExample = g.cli?.examples?.[0] ?? `agent-media ${g.cli?.command ?? g.id} …`;
+      const pricingLine = g.pricing
+        ? g.pricing.basis === 'one_shot'
+          ? `Cost: **${g.pricing.baseCredits} credits** ($${(g.pricing.baseCredits / 100).toFixed(2)}).`
+          : `Cost: **${g.pricing.baseCredits} + ${g.pricing.perSecondCredits}/sec** (8s ≈ ${quoteV2Credits(g.id as any, { durationSeconds: 8 })} credits ≈ $${(quoteV2Credits(g.id as any, { durationSeconds: 8 }) / 100).toFixed(2)}).`
+        : '';
+      return [
+        `### ${g.id}`,
+        '',
+        g.description,
+        '',
+        pricingLine,
+        '',
+        '**CLI:**',
+        '',
+        '```bash',
+        cliExample,
+        '```',
+        '',
+        '**MCP tool:** `' + (g.mcp?.toolName ?? '(none)') + '`',
+        '',
+        '**REST:** `' + (g.rest?.method ?? '') + ' ' + (g.rest?.path ?? '(internal)') + '`',
+        '',
+      ].join('\n');
+    })
+    .join('---\n\n');
+
+  return [
+    '---',
+    'name: agent-media-v2',
+    'description: AI UGC video production via agent-media v2 — Selfie videos and reusable Characters. Use this skill when the user wants to make TikTok-style "AI person talking to camera" clips or save a character for reuse across multiple generations.',
+    'homepage: https://agent-media.ai/skill',
+    `version: 1.3.0`,
+    '---',
+    '',
+    GENERATED_NOTE,
+    '',
+    '# agent-media — STRICT RULES (read first, every time)',
+    '',
+    '## 0. CONVERSATION FLOW — follow this in order',
+    '',
+    'Before you EVER call the CLI, walk the user through these steps. Ask in batches of 2-3 questions at a time, never one-by-one, never silently default. Use the user\'s answers to populate the CLI args.',
+    '',
+    '### Step 1 — What\'s the video about?',
+    '',
+    'This is the FIRST question, every time. Even if the user typed a full prompt with a script, confirm:',
+    '',
+    '> *"Got it — quick check before I generate:*',
+    '> *• What\'s the video about?  (the topic / what they\'re selling / what\'s happening in the scene)*',
+    '> *• What\'s the exact line you want them to say?  (the script — 1-3 sentences usually works best)"*',
+    '',
+    'Don\'t skip this. The "topic" informs the preset + vibe selection later. If the user already gave you a script, repeat it back so they can confirm or tweak it.',
+    '',
+    '### Step 2 — Who\'s the character?',
+    '',
+    '**agent-media generates the character image itself from your description. You DO NOT need to provide a photo.** A description like "25yo asian woman with long wavy dark hair" is enough — the pipeline produces a consistent on-model person.',
+    '',
+    'Three valid input paths (in order of preference):',
+    '',
+    '1. **Description only** (the default — use this 95% of the time)',
+    '   Just `--description "..."`. agent-media generates the portrait and the multi-pose sheet, then runs the video. No photo, no upload, no questions about photos. Example:',
+    '   ```bash',
+    '   agent-media selfie --description "25yo asian woman, long wavy dark hair, soft smile" --script "..."',
+    '   ```',
+    '',
+    '2. **Saved character** (`--character char_xxxxxxxxxx`)',
+    '   Use when the user references a person from a previous run ("use the same girl again", "the one from yesterday\'s video"). Run `agent-media character` to list saved characters if you need to look one up.',
+    '',
+    '3. **Real-person photo + description** (`--photo <file|url> --description "..."`)',
+    '   Use ONLY when the user explicitly says "use THIS person" and gives you a photo of someone specific. Otherwise default to path 1.',
+    '',
+    'Hard rules:',
+    '- NEVER ask the user "do you have a photo?". Default to description-only.',
+    '- NEVER ask the user about the underlying models (gpt-image-2, Seedance, etc.). They are implementation details. Just say "agent-media generates the character".',
+    '- NEVER fall back to `agent-media ugc` or a stock actor library. Forbidden.',
+    '- If the user wants the SAME person across multiple videos, run `agent-media character create --description "..."` once first (no photo needed) to get a `char_xxxxxxxxxx`, then pass `--character <id>` to every selfie.',
+    '',
+    '### Step 3 — Where + how does it feel? (preset + vibe)',
+    '',
+    'Pick one **preset** (location/shot grammar) + one **vibe** (emotional tone). If you can guess from the topic, propose them as defaults to confirm; if not, ask.',
+    '',
+    '**Presets (20, one of):**',
+    '',
+    '| Preset | Best for |',
+    '|---|---|',
+    '| `bedroom-morning-ritual` | Default. Skincare, routine, "morning vibes" content |',
+    '| `getting-ready-mirror-edge` | OOTD, makeup, fashion |',
+    '| `bathroom-skincare-routine` | Beauty, hair care, skincare reveals |',
+    '| `bedside-lamp-evening` | Wind-down, journal, ASMR-style |',
+    '| `kitchen-glow-up` | Food, drinks, supplements, cooking |',
+    '| `backyard-morning-coffee` | Lifestyle, mindfulness, slow content |',
+    '| `picnic-blanket-outdoor` | Outdoor, summer, friends |',
+    '| `car-quick-honest-review` | Honest reviews, "I just bought this..." |',
+    '| `car-passenger-honest` | Same vibe, passenger angle |',
+    '| `outdoor-walking-talking` | Walking-and-talking, candid |',
+    '| `couch-haul-show-off` | Unboxing, hauls, "look what I got" |',
+    '| `closet-fit-check` | Fashion, fit-checks, OOTD |',
+    '| `studio-apartment-tour` | Lifestyle, apartment content |',
+    '| `balcony-evening-vibes` | Aesthetic, lifestyle, golden hour |',
+    '| `desk-wfh-quick-pitch` | SaaS, productivity, work-from-home |',
+    '| `cafe-window-seat` | Lifestyle, work, coffee culture |',
+    '| `office-bathroom-discreet` | Workplace anecdotes, "let me tell you" |',
+    '| `gym-post-workout` | Fitness, supplements, wellness |',
+    '| `salon-mirror-result` | Hair, beauty reveals, "before/after" |',
+    '| `travel-hotel-room-review` | Travel, hotel reviews |',
+    '',
+    '**Vibes (5, one of):** `excited` · `calm` · `sassy` · `serious` · `curious`',
+    '',
+    '- `excited` — high energy, "you won\'t believe this", default for hype/product/reveal',
+    '- `calm` — softer, intimate, default for wellness/skincare/lifestyle',
+    '- `sassy` — playful, eye-roll, default for "let me tell you" anecdotes',
+    '- `serious` — measured, default for honest reviews / SaaS / B2B',
+    '- `curious` — thoughtful, leaning-in, default for storytelling',
+    '',
+    '### Step 4 — How long?',
+    '',
+    '**Allowed durations: 5, 10, or 15 seconds. ONLY these three.** Default to 10 if unsure. The schema rejects any other value (the worker will reject 6, 8, 12, etc.).',
+    '',
+    '- `5` — single hook, no body. Best for ads with strong intro.',
+    '- `10` — default. Hook + payoff. Best for organic UGC.',
+    '- `15` — full mini-story with setup + reveal.',
+    '',
+    '### Step 5 — Voice direction (optional, but improves quality)',
+    '',
+    'Ask: *"Any voice direction? E.g. \'whisper\', \'gen-z deadpan\', \'NYC accent\', \'sleepy morning voice\'. Skip if you\'re happy with the default."*',
+    '',
+    'Pass as `--voice-brief "<text>"`. Max 240 chars. If the character has a saved `voice_brief`, it\'s used unless this is set.',
+    '',
+    '### Step 6 — Subtitles',
+    '',
+    'Subs are ON by default in Hormozi style. Offer alternatives only if asked.',
+    '',
+    '**Subtitle styles (17, one of):** `hormozi` (default) · `minimal` · `bold` · `karaoke` · `clean` · `tiktok` · `neon` · `fire` · `glow` · `pop` · `aesthetic` · `impact` · `pastel` · `electric` · `boxed` · `gradient` · `spotlight`',
+    '',
+    '### Step 7 — Quote price, confirm, run',
+    '',
+    'Print a one-line summary including ALL collected inputs + the credit cost + USD. ONLY then call the CLI. See section 4 for the pricing formula.',
+    '',
+    'Example summary line to print before submitting:',
+    '> *"Summary: 10s selfie · char_8x2vqp · preset=kitchen-glow-up · vibe=excited · subs=hormozi · voice="gen-z deadpan". Cost: **375 credits ($3.75)**. Run it?"*',
+    '',
+    '## 1. Commands you MUST use',
+    '',
+    '| User intent | Command |',
+    '|---|---|',
+    '| "make me a TikTok / UGC / Selfie / talking-head" | `agent-media selfie` |',
+    '| "save / persist this character" / "use the same person again" | `agent-media character create` (returns `char_xxxxxxxxxx`) |',
+    '| "add subtitles / captions / subs to a video" | `agent-media subs` |',
+    '',
+    '## 2. Commands you MUST NEVER use',
+    '',
+    'These are LEGACY v1 commands. They produce inferior output and use a stale actor library. They are hidden from `agent-media --help` in CLI 1.10.0+ but may still be callable directly:',
+    '',
+    '- ❌ `agent-media ugc` — replaced by `agent-media selfie`',
+    '- ❌ `agent-media show-your-app` — coming back as v2 product later',
+    '- ❌ `agent-media laptop-ugc` — coming back as v2 product later',
+    '- ❌ `agent-media character-video` — replaced by `agent-media selfie --character <id>`',
+    '- ❌ `agent-media text-to-video` — not part of v2 yet',
+    '- ❌ `agent-media subtitle` — replaced by `agent-media subs`',
+    '- ❌ `agent-media review` — not part of v2',
+    '- ❌ `agent-media product-acting` — coming back as v2 product later',
+    '',
+    'If you catch yourself reaching for any command in the list above, STOP and re-route to the v2 equivalent.',
+    '',
+    '## 3. Per-command required + optional flags',
+    '',
+    '### `agent-media selfie` (cheat-sheet)',
+    '',
+    '| Flag | Required | Allowed values | Default |',
+    '|---|---|---|---|',
+    '| `--description "..."` | ✓ (unless `--character`) | 8-400 chars describing the person | — |',
+    '| `--character <char_id>` | OR | `char_xxxxxxxxxx` (saved character) | — |',
+    '| `--photo <file\\|url>` | optional | only when user gives an exact-person reference photo | — |',
+    '| `--script "..."` | ✓ | 4-600 chars | — |',
+    '| `--preset <name>` |  | one of 20 (see Step 3) | `bedroom-morning-ritual` |',
+    '| `--vibe <name>` |  | `excited\\|calm\\|sassy\\|serious\\|curious` | `excited` |',
+    '| `--duration <n>` |  | **`5` \\| `10` \\| `15`** | `10` |',
+    '| `--voice-brief "..."` |  | 4-240 chars | (none / character default) |',
+    '| `--subs-style <name>` |  | one of 17 (see Step 6) | `hormozi` |',
+    '| `--no-subs` |  | flag | (subs on) |',
+    '',
+    '### `agent-media character create`',
+    '',
+    '| Flag | Required | Notes |',
+    '|---|---|---|',
+    '| `--name <slug>` | ✓ | lowercase, hyphens, e.g. `sofia` |',
+    '| `--description "..."` | ✓ | free text — age, look, vibe. agent-media generates the portrait from this. |',
+    '| `--photo <file\\|url>` | optional | ONLY when the user wants an exact real-person likeness. Otherwise omit. |',
+    '| `--voice-brief "..."` |  | default voice direction baked into character |',
+    '| `--preset-default <name>` |  | preset to use when this character runs selfie |',
+    '',
+    'Returns `char_xxxxxxxxxx` — copy and reuse it.',
+    '',
+    '### `agent-media subs`',
+    '',
+    '| Flag | Required | Notes |',
+    '|---|---|---|',
+    '| `--video <url>` | ✓ | publicly-fetchable mp4 URL |',
+    '| `--style <name>` |  | one of 17 (see Step 6). Default: `hormozi`. |',
+    '| `--transcript "..."` |  | skip Whisper if you already have the exact words |',
+    '| `--language <code>` |  | ISO code (`en`, `es`, `pt`, `fr`, …) |',
+    '',
+    '## 4. PRICING FORMULA — do not improvise',
+    '',
+    '**1 credit = $0.01 USD. Period.** Never quote a price without using this conversion.',
+    '',
+    'Selfie cost = `75 base + 30 × seconds`:',
+    '',
+    '| Duration | Credits | USD |',
+    '|---|---:|---:|',
+    '| 5s | 225 | **$2.25** |',
+    '| 10s | 375 | **$3.75** |',
+    '| 15s | 525 | **$5.25** |',
+    '',
+    'Character create = 27 credits = **$0.27** (one-shot).',
+    'Subtitle = `0 base + 3 × seconds` (a 10s clip = 30 credits = **$0.30**).',
+    '',
+    'If you find yourself about to print any USD value not in this table or derivable by `credits / 100`, STOP. Recompute.',
+    '',
+    '## 5. Output handling',
+    '',
+    'Every command returns a job id. Poll until terminal:',
+    '',
+    '```bash',
+    'agent-media status <job-id>',
+    '```',
+    '',
+    'When `status: "completed"`, the response carries `video_url`. Print the FULL url to the user verbatim — do not abbreviate.',
+    '',
+    'Sync mode (blocking): add `--sync` to selfie/subs and the CLI will poll for you and print the URL when done.',
+    '',
+    '### For `agent-media character create`',
+    '',
+    'Required: `--photo <file|url>`, `--name <slug>`, `--description "..."`.',
+    'Optional: `--voice-brief`, `--preset`.',
+    '',
+    'Cost: 27 credits ($0.27). Confirm.',
+    '',
+    '### For `agent-media subs`',
+    '',
+    'Required: `--video <url>`.',
+    'Optional: `--style` (default `hormozi`, one of 17), `--transcript` (skip Whisper), `--language`.',
+    '',
+    'Cost: ~24 credits / 8s clip. Confirm.',
+    '',
+    '## 4. Output handling',
+    '',
+    'Every command returns a job id. Poll until terminal:',
+    '',
+    '```bash',
+    'agent-media status <job-id>',
+    '```',
+    '',
+    'When status is `completed`, the final mp4 URL is printed. Show it to the user. Do not summarize or shorten it.',
+    '',
+    '---',
+    '',
+    '# agent-media v2 — Selfie + Characters',
+    '',
+    'The v2 surface ships two generators today: **Selfie** (a 9:16 TikTok-style video of an AI person talking to camera) and **character_create** (persist an AI character so subsequent Selfies stay on-model). When the next v2 product lands (Product-in-hands), it appears here automatically — this file is generated from `packages/schema/src/v2/generators.ts`.',
+    '',
+    '## When to use this skill',
+    '',
+    'Trigger phrases:',
+    '- "make me a TikTok / Selfie / UGC video"',
+    '- "have an AI person say …"',
+    '- "create a character / actor / persona for reuse"',
+    '- "use the same person across multiple videos"',
+    '',
+    '## Setup',
+    '',
+    '```bash',
+    'npm install -g agent-media-cli',
+    'agent-media login            # opens browser; pastes ma_xxx into ~/.agent-media',
+    '```',
+    '',
+    'Or use the SDK directly:',
+    '',
+    '```ts',
+    "import { AgentMedia } from '@agentmedia/sdk';",
+    "const client = new AgentMedia({ apiKey: process.env.AGENT_MEDIA_API_KEY! });",
+    "const job = await client.v2.createCharacter({ photo_url: '…', display_name: 'sofia', description: '…' });",
+    "const done = await client.v2.runUntilDone(Promise.resolve(job));",
+    '```',
+    '',
+    '## Generators',
+    '',
+    generatorBlocks,
+    '## Recommended flow (multi-clip from one character)',
+    '',
+    '1. **Create the character once** with `character create`. Returns `char_xxxxxxxxxx`.',
+    '2. **Reuse that id** for every subsequent Selfie — same face, same voice, same seed.',
+    '3. If the user wants a different *look*, make a new character; don\'t mutate the existing one.',
+    '',
+    '```bash',
+    "ID=$(agent-media character create --photo me.png --name sofia \\",
+    '    --description "25, asian, long wavy dark hair, casual confident" --quiet)',
+    '',
+    'agent-media selfie --character $ID --script "Got my first 100 customers in 30 days." --preset desk-wfh-quick-pitch',
+    'agent-media selfie --character $ID --script "Here\'s how I did it."             --preset bedroom-morning-ritual',
+    '```',
+    '',
+    '## Shot grammar (Selfie)',
+    '',
+    '`--preset` accepts one of:',
+    '',
+    V2_SHOT_PRESETS.map((p) => `- \`${p}\``).join('\n'),
+    '',
+    'Or pass `--preset custom-scene:"<your scene description>"` for an ad-hoc setup.',
+    '',
+    '## Vibes',
+    '',
+    V2_VIBES.map((v) => `- \`${v}\``).join('\n'),
+    '',
+    '## Realism rubric',
+    '',
+    'Every Selfie clip is composed with these constraints baked into the prompt:',
+    '',
+    '1. Skin micro-detail visible — pores, freckles, oil sheen, baby hairs at hairline.',
+    '2. Hands always doing something — hair-touch, strap-fix, product hold.',
+    '3. Mouth caught mid-syllable when talking, not closed.',
+    '4. Eyes slightly off-center to camera, not a dead stare.',
+    '5. Single mixed light source (daylight + warm bulb).',
+    '6. Real setting (bedroom / kitchen / car / dresser-corner) — never plain wall / studio.',
+    '7. Outfit plain + matte or satin — never patterned or logo\'d.',
+    '8. Hair long, brushed, in motion.',
+    '9. Product (if any) held mid-chest, ~25° tilt.',
+    '',
+    'You don\'t need to repeat these in the script — they\'re always applied.',
+    '',
+    '## Error handling',
+    '',
+    '| Error code | What it means |',
+    '|---|---|',
+    '| `VALIDATION_ERROR` | Inputs failed Zod validation. Look at `error.issues`. |',
+    '| `INSUFFICIENT_CREDITS` | User\'s balance is below the quote. Tell them the exact amount needed. |',
+    '| `MISSING_CHARACTER_INPUT` | Selfie was called without either `--character` or `--photo + --description`. |',
+    '| `AMBIGUOUS_CHARACTER_INPUT` | Both `--character` and `--photo` were passed. Pick one. |',
+    '| `JOB_FAILED` | Worker reported failure. `error_message` carries the reason. |',
+    '| `POLL_TIMEOUT` | Job didn\'t complete within 30 minutes. Surface the job id; it may still finish. |',
+    '',
+    '## When NOT to use this skill',
+    '',
+    '- The user has an EXISTING legacy job they want to check or modify — use the v1 commands (`agent-media status`, `agent-media ugc`, etc.).',
+    '- The user wants a Show-Your-App / Product-Acting / Laptop-UGC clip — those products live in the v1 surface (separate generators, separate skill).',
+    '',
+  ].join('\n');
+}
+
+// ── Run ────────────────────────────────────────────────────────────────────
+
+function main() {
+  mkdirSync(dirname(DOCS_OUT), { recursive: true });
+  mkdirSync(dirname(SKILL_OUT), { recursive: true });
+
+  const docs = renderApiReference();
+  writeFileSync(DOCS_OUT, docs, 'utf8');
+
+  const skill = renderSkill();
+  writeFileSync(SKILL_OUT, skill, 'utf8');
+
+  console.log(`✓ wrote ${DOCS_OUT} (${docs.length} bytes)`);
+  console.log(`✓ wrote ${SKILL_OUT} (${skill.length} bytes)`);
+  console.log(`  generators emitted: ${Object.keys(V2_GENERATORS).length}`);
+}
+
+main();