@koda-sl/baker-cli 0.131.0-dev.cad5e0bc7 → 0.131.0

package/README.md

@@ -223,6 +223,8 @@ baker ads google query --list-presets
 | `keyword-analysis`     | Keyword performance with match type      | LAST_30_DAYS       |
 | `positive-keywords`    | Positive (targeting) keywords only       | ALL_TIME           |
 | `negative-keywords`    | Negative (blocking) keywords only        | ALL_TIME           |
+| `negative-keyword-lists`   | Shared negative lists + their terms  | ALL_TIME           |
+| `negative-list-attachments`| Which campaigns each shared list covers | ALL_TIME        |
 | `search-terms`         | Actual user queries triggering ads       | LAST_7_DAYS        |
 | `ad-copy-performance`  | Ad headline/description effectiveness    | LAST_30_DAYS       |
 | `asset-performance`    | PMax asset performance labels            | LAST_30_DAYS       |
@@ -397,262 +399,6 @@ baker ads google keywords metrics --customer-id 1234567890 --keywords "running s
 
 ---
 
-### Google Ads Library (`baker ads google library`)
-
-Manage and search the Google Ads Transparency Center. Track competitor advertisers, browse their ad creatives, and discover who's bidding on keywords.
-
-**Typical workflow:** `search-advertiser` → `track` → `search-ads`
-
----
-
-### `baker ads google library search-advertiser "query"`
-
-Search for an advertiser on the Google Ads Transparency Center.
-
-> **Recommended:** use the domain running the ads (e.g. `example.com`) for more accurate results.
-
-```bash
-baker ads google library search-advertiser "example.com"
-baker ads google library search-advertiser "Nike"
-```
-
-**Response:**
-
-```json
-{
-  "ok": true,
-  "data": {
-    "results": [
-      { "advertiserId": "AR12345678901234567", "name": "Nike, Inc.", "region": "US", "format": "TEXT_IMAGE_VIDEO" }
-    ]
-  }
-}
-```
-
-**Flags:**
-
-| Flag       | Description                    |
-|------------|--------------------------------|
-| `--output` | Format: `json` \| `csv` \| `md` |
-
----
-
-### `baker ads google library track <id> <name>`
-
-Track a new Google advertiser and wait for the initial ad sync to complete. Polls every 5 seconds with a 10-minute timeout. Progress is written to stderr.
-
-```bash
-baker ads google library track AR12345678901234567 "Nike, Inc."
-baker ads google library track AR12345678901234567 "Nike, Inc." --json
-```
-
-**Response (with `--json`):**
-
-```json
-{
-  "ok": true,
-  "data": {
-    "advertiserId": "ar_abc123",
-    "accountId": "acc_def456",
-    "totalAdCount": 342,
-    "activeAdCount": 89
-  }
-}
-```
-
-**Flags:**
-
-| Flag     | Description          |
-|----------|----------------------|
-| `--json` | Output in JSON format |
-
----
-
-### `baker ads google library list-advertisers`
-
-List all tracked Google advertisers and their accounts.
-
-```bash
-baker ads google library list-advertisers
-baker ads google library list-advertisers --output md
-```
-
-**Flags:**
-
-| Flag       | Description                    |
-|------------|--------------------------------|
-| `--output` | Format: `json` \| `csv` \| `md` |
-
----
-
-### `baker ads google library sync-status <accountId>`
-
-Check the sync status and ad counts of a tracked account.
-
-```bash
-baker ads google library sync-status acc_def456
-```
-
-**Response:**
-
-```json
-{
-  "ok": true,
-  "data": {
-    "syncStatus": null,
-    "totalAdCount": 342,
-    "activeAdCount": 89
-  }
-}
-```
-
-`syncStatus` is `null` when idle, `"syncing"` during a sync, or `"error"` if the last sync failed.
-
----
-
-### `baker ads google library search-ads <accountId>`
-
-Search and filter ads for a tracked account. Supports pagination.
-
-```bash
-baker ads google library search-ads acc_def456
-baker ads google library search-ads acc_def456 --search "summer sale" --isActive --mediaType image
-baker ads google library search-ads acc_def456 --sort newest --limit 50
-baker ads google library search-ads acc_def456 --cursor "eyJwYWdl..."
-```
-
-**Response:**
-
-```json
-{
-  "ok": true,
-  "data": {
-    "page": [
-      {
-        "_id": "abc123",
-        "platform": "google",
-        "externalId": "CR_1234567890",
-        "isActive": true,
-        "mediaType": "image",
-        "headline": "Summer Sale — 50% Off Everything",
-        "description": "Shop our biggest sale of the year. Free shipping on all orders.",
-        "destinationUrl": "https://example.com/summer-sale",
-        "bodyText": "Summer Sale — 50% Off Everything",
-        "pageName": "Example Store",
-        "impressionsMin": 100000,
-        "impressionsMax": 200000,
-        "startDate": "2025-06-01",
-        "endDate": "2025-06-30",
-        "firstSeenAt": 1717200000000,
-        "lastSeenAt": 1719792000000,
-        "publisherPlatforms": ["GOOGLE_ADS"],
-        "regionCodes": ["US", "GB"],
-        "variations": [
-          {
-            "headline": "Summer Sale — 50% Off",
-            "description": "Shop our biggest sale of the year.",
-            "destinationUrl": "https://example.com/summer-sale",
-            "imageUrl": "https://...",
-            "visibleUrl": "example.com"
-          }
-        ],
-        "regions": [
-          { "code": "US", "name": "United States" }
-        ],
-        "analysisStatus": "completed",
-        "aiAnalysis": {
-          "aiSummary": "Promotional display ad for a seasonal sale with urgency-driven CTA",
-          "hookAngle": "Discount/Price",
-          "offerType": "Percentage Discount",
-          "ctaStrategy": "Shop Now",
-          "funnelStage": "Bottom",
-          "targetAudience": "Price-sensitive shoppers",
-          "adFormat": "responsive_display",
-          "tags": ["sale", "discount", "ecommerce"],
-          "trustSignals": ["Free shipping"],
-          "keyMessages": ["50% off", "Free shipping"],
-          "competitiveAngle": "Price leadership",
-          "dominantColors": ["#FF5733", "#FFFFFF"],
-          "analyzedAt": 1719792000000
-        }
-      }
-    ],
-    "continueCursor": "eyJwYWdl...",
-    "isDone": false
-  }
-}
-```
-
-**Key response fields:**
-
-| Field | Description |
-|-------|-------------|
-| `headline`, `description` | Top-level ad copy (first variation) |
-| `variations[]` | All ad variations with copy, images, videos, and URLs |
-| `regions[]` | Geographic targeting regions |
-| `impressionsMin/Max` | Estimated impression range (Google Ads Transparency data) |
-| `publisherPlatforms` | Where the ad ran (GOOGLE_ADS, YOUTUBE, etc.) |
-| `analysisStatus` | AI analysis state: `pending`, `processing`, `completed`, `failed` |
-| `aiAnalysis` | AI-generated creative analysis (only present when `analysisStatus` is `completed`) |
-| `aiAnalysis.aiSummary` | One-line AI summary of the ad |
-| `aiAnalysis.hookAngle` | Creative hook (Discount, Fear, Social Proof, etc.) |
-| `aiAnalysis.funnelStage` | Funnel position: Top, Middle, Bottom |
-| `aiAnalysis.tags` | AI-generated tags for filtering |
-
-**Flags:**
-
-| Flag          | Description                                    |
-|---------------|------------------------------------------------|
-| `--search`    | Search term for ad text                        |
-| `--isActive`  | Filter by active ads only                      |
-| `--mediaType` | Filter by media type: `image`, `video`, `text` |
-| `--sort`      | Sort: `newest` or `oldest`                     |
-| `--limit`     | Max results per page (default 20, max 100)     |
-| `--cursor`    | Pagination cursor from previous response       |
-| `--output`    | Format: `json` \| `csv` \| `md`               |
-
----
-
-### `baker ads google library sync <accountId>`
-
-Trigger an immediate re-sync for a tracked account. Polls every 5 seconds until complete (10-minute timeout). Progress is written to stderr.
-
-```bash
-baker ads google library sync acc_def456
-```
-
-**Response:**
-
-```json
-{
-  "ok": true,
-  "data": {
-    "totalAdCount": 350,
-    "activeAdCount": 92
-  }
-}
-```
-
----
-
-### `baker ads google library search-competitors "keyword"`
-
-Search for competitors running Google ads for a keyword. Uses DataForSEO (same data as `baker research advertisers`).
-
-```bash
-baker ads google library search-competitors "running shoes"
-baker ads google library search-competitors "crm software" --location uk
-```
-
-**Flags:**
-
-| Flag         | Description                |
-|--------------|----------------------------|
-| `--location` | Location name or code      |
-| `--json`     | Output in JSON format      |
-
----
-
 ### Staged writes (`baker ads google budgets|campaigns|...`)
 
 Write commands **never touch the Google Ads API at stage time**. Each command stages a create/update/pause/resume/remove op against the current chat's draft (`BAKER_CHAT_ID`); the dashboard shows it as a pending "Google Ads" change, and the whole draft applies as one atomic `GoogleAdsService.Mutate` when the chat is published. Feature-flagged per company (`companies.googleAdsWriteEnabled`) — off by default = a fully simulated publish with zero real API calls.
@@ -1944,14 +1690,14 @@ baker images generate "flat geometric mascot, brand palette" \
   --model recraft/recraft-v4.1-pro-vector --rgb-colors "[[10,10,10],[255,80,0]]" --bg-rgb "[255,255,255]"
 ```
 
-**Models** (`--model`, default `openai/gpt-5.4-image-2`):
+**Models** (`--model`, default `google/gemini-3.1-flash-image-preview`):
 
 | Model | Best for | Aspect ratios | Sizes |
 |---|---|---|---|
-| `openai/gpt-5.4-image-2` **(default)** | Photoreal + cleanest in-image text — ad/landing reproduction | standard set | `1K` `2K` `4K` |
-| `google/gemini-3-pro-image-preview` | Highest fidelity (Nano Banana Pro) | standard set | `1K` `2K` `4K` |
+| `google/gemini-3.1-flash-image-preview` **(default)** | Fast iteration, reference editing, extreme aspect ratios (Nano Banana flash) | standard **+** `1:4` `4:1` `1:8` `8:1` | `0.5K`–`4K` |
 | `google/gemini-3.5-flash` | Fast; extreme aspect ratios | standard **+** `1:4` `4:1` `1:8` `8:1` | `0.5K`–`4K` |
-| `google/gemini-3.1-flash-image-preview` | Same as 3.5 flash (preview) | extreme set | `0.5K`–`4K` |
+| `google/gemini-3-pro-image-preview` | Highest fidelity (Nano Banana Pro) — strong prompt adherence and reference grounding | standard set | `1K` `2K` `4K` |
+| `openai/gpt-5.4-image-2` | Photoreal + cleanest in-image text — ad/landing reproduction | standard set | `1K` `2K` `4K` |
 | `recraft/recraft-v4.1-pro-vector` | Vector/flat/SVG-style with palette control | standard set | `1K` `2K` `4K` |
 
 Standard aspect ratios: `1:1` `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9`.
@@ -1960,7 +1706,7 @@ Standard aspect ratios: `1:1` `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9`
 
 | Flag | Description |
 |---|---|
-| `--model` | Model id (default `openai/gpt-5.4-image-2`) |
+| `--model` | Model id (default `google/gemini-3.1-flash-image-preview`) |
 | `--aspect-ratio` | Output aspect ratio (default `1:1`) |
 | `--image-size` | Resolution: `1K` (default) `2K` `4K` (Gemini flash also `0.5K`) |
 | `--reference` | Comma-separated visual references, each either a **public image URL** (Pinterest / stock / library `imageUrl`) **or a local file path** (a sandbox image — brand logo, product shot, cropped photo, screenshot). Local files are downscaled (≤1536px) and inlined automatically — no manual upload. Applied in order; the biggest quality lever for photographed, on-brand output. Split is on `,`, so a URL containing a literal comma in its query string would be torn in two (rare for image CDNs — pass it alone if it occurs); a single `data:` URL is taken whole. |
@@ -2419,13 +2165,17 @@ baker testimonials tags
 
 ### Winning Ads (`baker winning-ads`)
 
-Search the **ad-dna** corpus of scored "winning" competitor ads for reference creatives to reproduce (e.g. with `baker canvas`). Each result carries a presigned media URL (~1h TTL), the ad's DNA summary, and scores. The CLI authenticates with the normal `BAKER_API_KEY`; the Baker backend proxies the request to the ad-dna service with a server-held token — no extra credential in the sandbox.
+Search the **ad-dna** corpus of scored "winning" competitor ads for reference creatives to reproduce (e.g. with `baker canvas`), and manage the brands your library tracks (`follow` / `following` / `unfollow`). Each result carries a presigned media URL (~1h TTL), the ad's DNA summary, and scores. The CLI authenticates with the normal `BAKER_API_KEY`; the Baker backend proxies the request to the ad-dna service with a server-held token — no extra credential in the sandbox.
+
+> The corpus has **Meta + LinkedIn** connectors, so `--platform` inputs are limited to `meta,linkedin`. (Older result rows may still carry a legacy platform string.)
 
 > Backend env: the Convex deployment must have `AD_DNA_API_TOKEN` set (`npx convex env set AD_DNA_API_TOKEN …`). `AD_DNA_API_URL` is optional and defaults to `https://ads.withbaker.com`.
 
+> Replaces the old `baker ads google library` tree, which has been removed. Competitor-by-keyword discovery still lives at `baker research advertisers`.
+
 ### `baker winning-ads search <query>`
 
-Semantic search (dense recall + BM25 + rerank). The CLI projects each result to a **lean, decision-focused** shape so the agent's context stays small — default fields: `advertiser`, `advertiser_id`, `platform`, `format`, `relevance`, `winner_score`, `summary` (what the ad is about), `media_url`; plus top-level `pool_size` and `match_confidence`. `--full` adds DNA detail (`angle`, `target_persona`, `hook_archetype`, `awareness_stage`, `industry`) + longevity (`days_active`, `reach`, `active`, `winner_category`, `media_kind`). `--output json` (default) returns the lean objects; `--output md` prints a table.
+Semantic search (dense recall + BM25 + rerank) → `POST /api/ad-library/winners/search`. The CLI projects each result to a **lean, decision-focused** shape so the agent's context stays small — default fields: `advertiser`, `advertiser_id`, `platform`, `format`, `relevance`, `winner_score`, `summary` (what the ad is about), `media_url`; plus top-level `pool_size`, `match_confidence` (`high|medium|low`), and `below_floor_count` (matches dropped under the relevance floor). `--full` adds DNA detail (`angle`, `target_persona`, `hook_archetype`, `awareness_stage`, `industry`) + longevity (`days_active`, `reach`, `active`, `winner_category`, `media_kind`). `--output json` (default) returns the lean objects; `--output md` prints a table.
 
 > `media_url` is the creative itself: for `static` it's the image, for `video` it's the video file. ad-dna stores **no separate poster** for videos, so a video result has only the video URL.
 
@@ -2447,7 +2197,7 @@ baker winning-ads search --ref-ad-id a_12345 --first-seen-after 2026-01-01T00:00
 | `--limit <n>` | Max results 1–100 (**default 10** — shortlist size) |
 | `--max-per-advertiser <n>` | Cap results per advertiser 1–50 (default 3) |
 | `--min-relevance <0-1>` | Relevance floor; trims weak matches |
-| `--platform <list>` | One or many of `meta,tiktok,linkedin,google_search,google_display,youtube,reddit,x,pinterest,snapchat` — pass a single value to search **only** that platform |
+| `--platform <list>` | `meta,linkedin` — pass a single value to search **only** that platform |
 | `--format <list>` | `video,static,carousel` |
 | `--winner-category <list>` | `winner,scaled_winner,evergreen,rising,untested,dud,…` (default: all) |
 | `--awareness <list>` | `unaware,problem_aware,solution_aware,product_aware,most_aware` |
@@ -2461,20 +2211,21 @@ baker winning-ads search --ref-ad-id a_12345 --first-seen-after 2026-01-01T00:00
 
 Reading the scores: **`relevance`** (0–1) = match of the creative to your query; **`winner_score`** = how proven the ad is in-market. Pick references that are both relevant *and* proven.
 
-### `baker winning-ads hooks|mechanisms|patterns`
+### `baker winning-ads hooks|mechanisms|formats`
 
-Read the **winner-weighted rollup** of the ad-dna corpus — the hook / mechanism / static-format patterns that
-actually win, ranked by `winner_score`, keyed on the closed seeds/enums the extractor emits (no clustering).
-Ground a creative in a **proven** pattern for the exact segment instead of guessing.
+Read the **winner-weighted rollup** of the ad-dna corpus → `GET /api/ad-library/seed-catalog` — the hook /
+mechanism / static-format patterns that actually win, ranked by `winner_score`, keyed on the closed seeds/enums
+the extractor emits (no clustering). Ground a creative in a **proven** pattern for the exact segment instead of
+guessing. (Distinct from `winning-ads patterns`, which contrasts two ad cohorts.)
 
 ```bash
 # Top winning hook seeds for problem-aware SaaS on Meta:
 baker winning-ads hooks --platform meta --awareness problem_aware --industry saas --output md
 # Then narrow a reference search to that proven hook:
 baker winning-ads search "onboarding demo" --hook-archetype callout --output md
-# Also: mechanisms (persuasion), patterns (static ad layouts):
+# Also: mechanisms (persuasion), formats (static ad layouts):
 baker winning-ads mechanisms --platform linkedin --output md
-baker winning-ads patterns --awareness solution_aware --output md
+baker winning-ads formats --awareness solution_aware --output md
 ```
 
 | Flag | Purpose |
@@ -2490,13 +2241,66 @@ proven grand-slam pattern floats to the top and a measured dud is floored.
 
 ### `baker winning-ads advertisers <brand>`
 
-Resolve a brand name → `advertiser_id`(s) in the corpus. Use it to find **your own** advertiser (to `--exclude-advertiser`) or a **competitor** (to `--advertiser-id`). Returns `advertiser_id`, `label`, `active_ads`, `total_ads`.
+List corpus brands by name or domain → `GET /api/ad-library/advertisers`. Use it to find **your own** advertiser (to `--exclude-advertiser`) or a **competitor** (to `--advertiser-id` / `winners`). Lean default fields: `advertiser_id`, `label`, `platform_count`, `family_count`, `active_ad_count`, `total_ad_count`; `--full` adds `scraped_name`, `image_url`, `platforms`, `total_reach`, `last_synced_at`. Supports `--platform meta|linkedin`, `--limit`, `--offset`.
 
 ```bash
 baker winning-ads advertisers "Acme" --output md          # find our own advertiser id
 baker winning-ads advertisers "Deel" --platform meta --output md
 ```
 
+### `baker winning-ads follow "<domain | profile URL | brand>" --platform meta|linkedin`
+
+Add **all** of a brand's ads to your library — every platform (Meta + LinkedIn) and every country → `POST /api/ad-library/follow`. `--platform` is **required**, but it only tells us how to read your `input` (Facebook vs LinkedIn URL); it does **not** limit what we track. A bare domain is best: we resolve both the Meta page and the LinkedIn company from it and track both. Discovery is never region-scoped. The result `status` is one of:
+
+- `following` — the brand is already in the corpus; you're now subscribed (no wait).
+- `added` — a new brand was queued for ingestion; its ads appear as discovery completes (a `hints[]` note flags this).
+- `ambiguous` — the input mapped to multiple brands; pick one from `candidates` and re-run with a more specific domain/URL.
+
+```bash
+baker winning-ads follow "deel.com" --platform meta
+baker winning-ads follow "https://www.linkedin.com/company/acme" --platform linkedin --label "Acme (competitor)"
+```
+
+### `baker winning-ads following`
+
+List the brands you follow → `GET /api/ad-library/following`. Each row shows `status` (`ready` vs `adding…`) plus cached counts (`active_ad_count`, `total_ad_count`, `family_count`) and discovery progress (`adding_discovered`, `adding_enqueued`). `--full` adds `image_url` + `platforms`.
+
+```bash
+baker winning-ads following --output md
+```
+
+### `baker winning-ads winners <advertiser>`
+
+Top winning ads for one advertiser id → `GET /api/ad-library/advertiser-winners`. Same lean winner cards as `search` (add `--full` for DNA + longevity). Supports `--top N` and `--platform meta|linkedin`.
+
+```bash
+baker winning-ads winners adv_123 --top 15 --output md
+```
+
+### `baker winning-ads unfollow <advertiser>`
+
+Stop following a brand by advertiser id → `POST /api/ad-library/unfollow`. Returns `{ removed }`.
+
+```bash
+baker winning-ads unfollow adv_123
+```
+
+### `baker winning-ads brief`
+
+Generate a creative brief grounded in strategically-similar winners → `POST /api/ad-library/brief`. Optionally describe the target creative with `--dna` (a JSON object), steer with `--notes`, and cap references with `--k`. Returns `brief_markdown` + `reference_ad_ids`.
+
+```bash
+baker winning-ads brief --dna '{"angle":"cost savings","awareness_stage":"solution_aware"}' --notes "B2B, LinkedIn video" --k 8
+```
+
+### `baker winning-ads patterns --winners <adIds> --duds <adIds>`
+
+Mine what separates two cohorts of ads → `POST /api/ad-library/patterns`. Pass a comma-list of winning ad ids (`--winners`, cohort A) and weaker/dud ad ids (`--duds`, cohort B), plus optional `--top-n`. Returns each discriminating DNA field with the cohort it `favors` (`winners`/`duds`), a `score`, and the top values on each side.
+
+```bash
+baker winning-ads patterns --winners a_1,a_2,a_3 --duds a_9,a_8 --top-n 10 --output md
+```
+
 ---
 
 ### Scheduled Actions (`baker scheduled-actions`)
@@ -4067,16 +3871,18 @@ Validate, then execute the graph. Blocks until done. Logs one line per node. Ret
 
 Turn a reference video into a **runnable, self-validated reproduction canvas** in one command — the video counterpart of `scaffold-static-ad`. The `<video>` positional is a **local path OR an http(s) URL** (a `baker winning-ads` `media_url`, a library URL, any reel link) — a URL is downloaded for you (no manual `curl` first), so pass `--slug`/`--out` with it to give the canvas a home. It runs **billed passes** up front:
 
-1. **`video_deconstruct`** (`~google/gemini-pro-latest`, full mode) — reverse-engineers the video into a scene-by-scene blueprint + word-level transcript, written next to the canvas as **`prompt.json`** (the human-editable source of truth). Each scene's `start_frame_prompt`/`end_frame_prompt` are inlined into the frame nodes (see below); the shared **global style reference** every frame reads via `target_blueprint` is a **slim projection** written alongside as **`prompt.style.json`** (`global` cast/palette/brand + `reference_elements` only, no per-scene array). A 33-scene blueprint is ~200 KB — inlining it into every one of a dozen frame prompts was pure waste and let a frame blend in another scene's content; the slim is ~5 KB. `prompt.style.json` is a **derived file**: `baker canvas validate` and `run` regenerate it from `prompt.json` whenever they diverge (reported as `style_projection` in validate's output), so editing `prompt.json` is all it takes — global cast/palette/brand edits reach every frame on the next validate/run, and the affected frames re-bill. Never edit the derived file by hand. Per-scene `scene_setting`/`ambient` deltas are baked into that scene's own frame prompts as a `SCENE STYLE` block.
+1. **`video_deconstruct`** (`~google/gemini-pro-latest`, full mode) — reverse-engineers the video into a scene-by-scene blueprint + word-level transcript. The blueprint is **split into small, single-purpose files** so you edit ONE at a time instead of a 2000-line monolith: **`prompt.json`** holds only the **global** slice (cast, palette, brand, music, overall copy), and each scene is written to its own **`scenes/sNN.json`** (`s00.json`, `s01.json`, … in scene order). To change a scene's dialogue / action / frame prompts / overlays, edit that one scene file; to change global cast/palette/brand, edit `prompt.json`. `baker canvas validate` and `run` re-assemble the full blueprint and **re-flow every edited scene back into the graph before billing** (reported as `scene_projection` in validate's output) — so scene edits reach the render automatically, and only the changed scenes re-bill. A frozen **`prompt.rebuild.json`** holds the rebuild context that makes this re-flow deterministic and model-free; never hand-edit it. The shared **global style reference** every frame reads via `target_blueprint` is a **slim projection** written alongside as **`prompt.style.json`** (`global` cast/palette/brand + `reference_elements` only, no per-scene array). `prompt.style.json` is a **derived file**: `validate`/`run` regenerate it from `prompt.json` whenever they diverge (reported as `style_projection`), so global cast/palette/brand edits reach every frame on the next validate/run and the affected frames re-bill. Never edit the derived files (`prompt.style.json`, `prompt.rebuild.json`) or the inlined node prompts by hand — they are regenerated. Per-scene `scene_setting`/`ambient` deltas are baked into that scene's own frame prompts as a `SCENE STYLE` block.
+
+   **Structural edits still need a re-scaffold.** The per-scene re-flow covers rewriting a scene's *content*. Changing scene *timing*, adding/removing/re-ordering scenes, or flipping a scene's shot type is a structural change the graph's timing/spine nodes don't track from a prompt edit — `validate`/`run` print a drift warning telling you to re-run `baker canvas scaffold-video`.
 2. **recurring-element selection** (`~google/gemini-flash-latest`) — picks only the **recurring, identity-critical** elements (each `global.cast` person, a recurring animal, a showcased product, the brand logo) and the scene indices each appears in. One real reference image grounds each element across **every** frame it appears in, so the same actor stays consistent the whole video. This selection runs as a **second pass over a slimmed blueprint** (cast/branding + each scene's frame prompts only) — a long ad's full blueprint can exceed the engine's inline-prompt limit, so the heavy per-scene detail (dialogue, overlays, transcript) the selector never reads is dropped before the prompt.
 
 Before the deconstruct it runs a **local shot-cut pass** on the source file with **[PySceneDetect](https://www.scenedetect.com)** (`scenedetect` CLI, `detect-content` — the battle-tested HSV content detector, installed in the canvas sandbox) and passes the cut timestamps as `video_deconstruct`'s `shot_cuts`. The deconstruct snaps its scene boundaries onto those real cuts and **splits any scene that spans one**, so a scene's frames can never straddle a hard cut (the failure where a scene's start frame was the couch and its end frame the b-roll). Two knobs tuned for fast social ads: the content **threshold defaults to 18** (PySceneDetect's own default of 27 misses soft reframes) and the **minimum scene length is dropped to 0.25s** (its default ~0.6s merges away rapid montage flashes) — so super-fast cuts survive and become cheap still-holds downstream. The threshold is **adaptive**: if the first pass looks like a continuous shot shredded into many close micro-cuts (a talking-head selfie's natural motion), it re-runs at PySceneDetect's own default of 27 and **merges the two passes** — the high-threshold set is the base, and the low pass's *isolated* extras (real soft blur-morph transitions that vanish at 27) are added back while clustered extras (motion shred) stay dropped. Pinning **`--shot-threshold N`** disables the re-check (lower = more cuts). The backend snap window is likewise **adaptive** (up to 1s onto an unambiguous nearest cut, shrinking around dense cut pairs so a boundary never jumps past the wrong cut), any scene spanning an interior cut is split, and the residual-sliver coalesce is **cut-aware**: a drift sliver folds backward across its non-cut edge and never re-merges across a real cut. If `scenedetect` is unavailable it warns loudly and degrades to LLM-only boundaries.
 
 A shot longer than the video model's per-clip ceiling (Seedance's 15s, passed as `video_deconstruct`'s `max_clip_s`) is split into equal **continuation sub-scenes** that share their splice boundary exactly — so a long shot is reproduced in **full** (no truncation) and joins seamlessly. Each sub-scene carries `continues_previous`.
 
-It then scaffolds the full pipeline like an **editing timeline**: each clip gets a **static-ad-grade start AND end keyframe** (`image_generate`, each with its **own self-contained `params.prompt`** — edit a frame node to change only that frame; the slim `prompt.style.json` wired as the **shared `target_blueprint`** style reference, plus a per-element reference legend). Each keyframe is **fully recast** to the dropped `el_*` reference images. The original extracted frame is kept LAST as a **pure composition anchor** (framing / camera angle / shot size / pose) whenever identity is safely locked — i.e. a frame with no person/animal, OR every cast member present is **sheet-backed** (a multi-view turnaround owns identity, so the anchor can reproduce the source's framing without dictating the face). Since every base element is now sheet-backed by default, cast frames keep their framing anchor too — this is what reproduces the source's composition (a side-profile stays a side-profile, the camera angle holds scene to scene) instead of drifting to a fresh guess. The anchor's legend forbids taking identity/text/palette from it. It is dropped only when a cast member rests on a weak lone-snapshot reference (e.g. a `same_as` second-look slot), where the original frame could re-leak the source actor. Both keyframes feed `video_generate` (`first_frame`+`last_frame`, so Seedance interpolates real in-shot motion; ultra-detailed motion brief; duration snapped to the nearest allowed clip length). Every keyframe grounds **only on its own extracted frame + `el_*` slots** — no reference to any other generated frame — so all images render **in parallel** (no cascade). Source-frame URLs are **deduped** (each ingested once). `--frames reuse` wires the real source frame straight in.
+It then scaffolds the full pipeline like an **editing timeline**: each clip gets a **static-ad-grade start AND end keyframe** (`image_generate`, each with its **own `params.prompt`** regenerated from that scene's `scenes/sNN.json` — edit the scene file to change that frame, never the node prompt by hand; the slim `prompt.style.json` wired as the **shared `target_blueprint`** style reference, plus a per-element reference legend). Each keyframe is **fully recast** to the dropped `el_*` reference images. The original extracted frame is kept LAST as a **pure composition anchor** (framing / camera angle / shot size / pose) whenever identity is safely locked — i.e. a frame with no person/animal, OR every cast member present is **sheet-backed** (a multi-view turnaround owns identity, so the anchor can reproduce the source's framing without dictating the face). Since every base element is now sheet-backed by default, cast frames keep their framing anchor too — this is what reproduces the source's composition (a side-profile stays a side-profile, the camera angle holds scene to scene) instead of drifting to a fresh guess. The anchor's legend forbids taking identity/text/palette from it. It is dropped only when a cast member rests on a weak lone-snapshot reference (e.g. a `same_as` second-look slot), where the original frame could re-leak the source actor. Both keyframes feed `video_generate` (`first_frame`+`last_frame`, so Seedance interpolates real in-shot motion; ultra-detailed motion brief; duration snapped to the nearest allowed clip length). Every keyframe grounds **only on its own extracted frame + `el_*` slots** — no reference to any other generated frame — so all images render **in parallel** (no cascade). Source-frame URLs are **deduped** (each ingested once). `--frames reuse` wires the real source frame straight in.
 
-**Composited scenes (split-screen / picture-in-picture / keyed presenter).** Real ads aren't always one full-frame shot — a frame can be **persistently divided** (b-roll on top, a presenter talking on the bottom) or **layer a presenter** over background footage (boxed in a corner, or green-screen keyed). The deconstruct now reports this per scene as `scene.composition` (`layout: split_screen | pip | keyed_overlay`, with one `region` per stream — each its own clean-plate frame + motion brief, the talking-head region flagged `is_presenter`). The scaffold reproduces a composited scene by building **one clip per region** (`s<i>_r0_*`, `s<i>_r1_*`, …) and compositing them with ffmpeg: a split-screen `vstack`/`hstack` (stack direction read from the region **panels**, so a top/bottom split always stacks vertically), or a picture-in-picture `overlay` of the presenter inset at its corner. A **keyed** presenter is first cut to transparency by `video_background_remove` (`s<i>_key`), then overlaid. The presenter region carries the native lip-synced voice; b-roll/render panels stay silent. To change a layout, edit `composition` in `prompt.json` and re-scaffold, or hand-edit the `s<i>_composite` ffmpeg args. Plain full-frame scenes (the default) are unaffected.
+**Composited scenes (split-screen / picture-in-picture / keyed presenter).** Real ads aren't always one full-frame shot — a frame can be **persistently divided** (b-roll on top, a presenter talking on the bottom) or **layer a presenter** over background footage (boxed in a corner, or green-screen keyed). The deconstruct now reports this per scene as `scene.composition` (`layout: split_screen | pip | keyed_overlay`, with one `region` per stream — each its own clean-plate frame + motion brief, the talking-head region flagged `is_presenter`). The scaffold reproduces a composited scene by building **one clip per region** (`s<i>_r0_*`, `s<i>_r1_*`, …) and compositing them with ffmpeg: a split-screen `vstack`/`hstack` (stack direction read from the region **panels**, so a top/bottom split always stacks vertically), or a picture-in-picture `overlay` of the presenter inset at its corner. A **keyed** presenter is first cut to transparency by `video_background_remove` (`s<i>_key`), then overlaid. The presenter region carries the native lip-synced voice; b-roll/render panels stay silent. To change a layout, edit `composition` in that scene's `scenes/sNN.json` and re-scaffold, or hand-edit the `s<i>_composite` ffmpeg args. Plain full-frame scenes (the default) are unaffected.
 
 **Typed region kinds & real screen surfaces.** Each composition region now carries a `kind` — `camera` (filmed footage, re-generated), `screen_capture` (app/site/document screen recording), `static_graphic` (designed text/graphic panel), or `generated` (3D/motion graphics) — plus an optional `nested` list for video-in-video (a Loom-style camera bubble inside a screen share). `kind` is authoritative for routing (prose keywords remain the fallback for older blueprints): `screen_capture`/`static_graphic` regions are **never generated by the video model** — the scene renders as a clean background plate (its clip prompt is scrubbed of all screen narration and forbids rendering UI) and the real surface is composited on the overlay layer. The route is decided **once per persistent layout run** (consecutive scenes sharing one composition signature), so a layout that runs unbroken across many scenes can't flip between pipelines on wording differences. A persistent surface seeds **ONE grouped stub** in `video-overlay-composition/index.html` spanning its whole window, with a per-scene **state timeline** — build one continuous screen recording/mockup, not one screenshot per scene. A `screen_capture` region also carries `surface_id`: a source video routinely **splices two unrelated screen recordings** under one persistent layout (a live app-processing capture, then an unrelated pre-made demo note) — the deconstruct assigns a stable id while the SAME recording continues and a new one when the on-screen content genuinely changes, so the run splits into **separate stubs** at the splice instead of asking for one screenshot that can't cover both. Full-frame screen scenes reuse the same `surface_id`: consecutive full-frame UI beats of one screen (e.g. a 3-scene import flow) share **ONE `s<i>_screen_ref` ingest** — the operator supplies that screenshot once instead of dropping the same capture into a dozen identical `[TODO]`s (distinct surfaces stay distinct). `baker canvas validate` additionally warns (`VIDEO_UI_IN_PROMPT`) if any clip prompt still narrates a screen surface, and (`VIDEO_BRANDMARK_IN_PROMPT`) if a generate prompt asks the model to paint a brand logo/wordmark (generation garbles marks; source the real one with `baker images logo` and composite it on the overlay layer).
 
@@ -4118,7 +3924,7 @@ The emitted canvas is validated (`validateCanvasDeep`) before it's written, so i
 
 ```bash
 baker canvas scaffold-video ./reference-ad.mp4 --focus "competitor UGC ad for <brand>"
-# → writes ./reference-ad.video.canvas.json + ./prompt.json (+ video-overlay-composition/)
+# → writes ./reference-ad.video.canvas.json + ./prompt.json (global) + ./scenes/sNN.json (per scene) + ./prompt.rebuild.json (+ video-overlay-composition/)
 # edit each frame's own params.prompt + drop ONE real source image at each el_* [TODO], confirm voices, then:
 baker canvas validate ./reference-ad.video.canvas.json
 baker canvas run ./reference-ad.video.canvas.json
@@ -4150,7 +3956,7 @@ roster and prints the choice as `models.video_route_reason` in the run report (m
 shifts a Veo pick to the fast tier. The scaffolder also bakes **per-intent param recipes** so the hero/reveal
 beat claims the 1080p cine ceiling automatically and a Kling hook beat maxes prompt adherence.
 
-Each scene is captured in a **shoot mode** — `ugc_selfie` (talking heads, the default look), `ugc_broll`, `studio_product` (pack shot), `lifestyle_cinematic`, or `screen_ui`. The scaffold derives one per scene (UGC by default; the cinematic and screen lanes are opt-in) and bakes its capture block into the frame and a camera default into the clip; override per scene with a `shoot_mode` field in `prompt.json`. Capture aesthetic + depth-of-field follow the mode (UGC stays flat; studio/lifestyle allow shallow DoF). Clips also carry **diegetic native audio** — the scene's own ambience described in the Seedance prompt, never music (the music bed is a separate, ducked track); set a scene's `ambient` field to steer it.
+Each scene is captured in a **shoot mode** — `ugc_selfie` (talking heads, the default look), `ugc_broll`, `studio_product` (pack shot), `lifestyle_cinematic`, or `screen_ui`. The scaffold derives one per scene (UGC by default; the cinematic and screen lanes are opt-in) and bakes its capture block into the frame and a camera default into the clip; override per scene with a `shoot_mode` field in that scene's `scenes/sNN.json`. Capture aesthetic + depth-of-field follow the mode (UGC stays flat; studio/lifestyle allow shallow DoF). Clips also carry **diegetic native audio** — the scene's own ambience described in the Seedance prompt, never music (the music bed is a separate, ducked track); set a scene's `ambient` field to steer it.
 
 **Automatic by default (no flags).** Every recast **base element — person, pet, product, AND location/set** — is fused into ONE rich multi-view sheet (`image_reference_sheet`, one subject per sheet, **4K**, up to 8 cells) that every frame it appears in grounds on, so the same face/pet/pack/room is rendered from a multi-angle canvas instead of a lone flat snapshot (a one-scene hero element is sheeted too). Each sheet pairs a **full turnaround** (angles, for proportions/wardrobe/layout) with tight **close-ups** so the generator is prepared for ANY framing a scene needs: a **person** gets body cells + face close-ups (front/¾/profile) and a mid-sentence speaking expression (identity pinned, natural skin — no airbrushing); an **animal** gets a body turnaround + head close-ups + an eyes/face macro; a **product** gets a turnaround + label and material detail macros; a **location/set** gets several camera angles of the same room + a key-surface detail. Generated clips are pinned to **1080p** (see `--resolution`) so the video keeps the keyframe's sharpness, and each cast frame keeps the source frame as a **composition anchor** (identity stays on the sheet) so the original framing/camera is reproduced, not re-guessed. An **app/website/chat screen** is never sent to the video model — the scaffold drops the scene to a clean talking-head and seeds a phone-mockup PIP stub to fill with a real `baker images screenshot` or brand HTML block (Seedance garbles UI and a split leaves a seam). The **music bed is instrumental** (the script is never fed to the music model — it would sing over the voice), enters only after the hook, and is **sidechain-ducked** under the voice. **Word-synced TikTok captions** are wired whenever the ad has speech — and they are **transcribed from the rendered audio's CLEAN VOICE BUS** (a `video_transcribe` of the vo tracks alone — no music bed, no SFX, which smear Whisper's word timings and hallucinate tokens), never the deconstruct's original transcript. This is a correctness boundary: wiring the source transcript would burn the **competitor's** words (their brand name, a claim we can't make) over the ad once the script is re-authored, whereas transcribing the generated audio can only ever show what is actually spoken, so the captions always track the re-written lines. Seeded overlays are pushed **off the subject's face** (dead-center → bottom band).
 

package/dist/{chunk-5LCTMZJ5.js → chunk-AEBAUSIN.js}

@@ -3,9 +3,9 @@ import {
   __toESM
 } from "./chunk-5WRI5ZAA.js";
 
-// ../../.pnpm-store/v10/links/@/safe-stable-stringify/2.5.0/810146e81bae4e3a061fe487864f2fde80c4b03b886877dc0f1fffbc6480b67e/node_modules/safe-stable-stringify/index.js
+// ../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/index.js
 var require_safe_stable_stringify = __commonJS({
-  "../../.pnpm-store/v10/links/@/safe-stable-stringify/2.5.0/810146e81bae4e3a061fe487864f2fde80c4b03b886877dc0f1fffbc6480b67e/node_modules/safe-stable-stringify/index.js"(exports, module) {
+  "../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/index.js"(exports, module) {
     "use strict";
     var { hasOwnProperty } = Object.prototype;
     var stringify = configure2();
@@ -979,7 +979,7 @@ function describeCause(c) {
   }
 }
 
-// ../../.pnpm-store/v10/links/@/safe-stable-stringify/2.5.0/810146e81bae4e3a061fe487864f2fde80c4b03b886877dc0f1fffbc6480b67e/node_modules/safe-stable-stringify/esm/wrapper.js
+// ../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/esm/wrapper.js
 var import__ = __toESM(require_safe_stable_stringify(), 1);
 var configure = import__.default.configure;
 var wrapper_default = import__.default;
@@ -7696,4 +7696,4 @@ export {
   defaultRegistry,
   createEngineFromEnv
 };
-//# sourceMappingURL=chunk-5LCTMZJ5.js.map
+//# sourceMappingURL=chunk-AEBAUSIN.js.map