@koda-sl/baker-cli 0.125.0 → 0.128.0-dev.70bf43ce4

package/README.md

@@ -223,8 +223,6 @@ 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       |
@@ -399,6 +397,262 @@ 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.
@@ -888,7 +1142,7 @@ Notes:
 - All write commands take `--file <json>` payloads; explicit flags override file keys. `baker schema ads.linkedin.campaigns.create` for exact args.
 - Money flags (`--bid`, `--daily-budget`, `--total-budget`) require `--currency`.
 - Creative media comes from the Baker library (`--image-id`/`--video-id` from `baker images`/`baker videos` — uploaded to LinkedIn at publish) or as LinkedIn URNs (`--image-urn`/`--video-urn`). Formats: `image|video|text|spotlight|follower|document|carousel|conversation|tla|jobs`; complex formats take `--file` with the full content object; conversation ads take `--file` with the message flow (`{message: {subject, body, senderName?, buttons[]}}` — buttons `NESTED` (with `nestedMessage`) or `LANDING_PAGE` (with `landingPageUrl`), ≤25 messages, bodies ≤500 chars, labels ≤25). Limits: headline ≤70, text-ad 25/75, intro soft-truncates at 600 chars. TLA sponsors an existing post via `--post-urn`.
-- Lead forms are file-first (`lead-forms create --file form.json`). Required: name, headline (≤60), privacyPolicyUrl, questions[] (≤12; playbook: ≤4 for completion). Each question is a predefined profile field (`{ name, predefinedField: "EMAIL" }` — Contact/Work/Company/Education/Demographic library) or a custom question (`{ name, questionType: "SINGLE_LINE_TEXT" | "MULTIPLE_CHOICE", options?: [...] }`; ≤3 custom, MULTIPLE_CHOICE needs 2–30 options). Also supported: `locale {country,language}`, `formImageId`/`formImageUrn` (banner), `consents[]` (≤5 disclosure checkboxes `{text, required}`), `hiddenFields[]` (≤20 `{name, value}` tracking fields), `legalDisclaimer`, `thankYou {message, cta, landingUrl | appointmentUrl}` (Calendly/Chili Piper booking link). The staged preview emits non-blocking best-practice warnings when a form has no qualifying question, no confirmation message/action, or no consent checkbox.
+- Lead forms are file-first (`lead-forms create --file form.json`). Required: name, headline (≤60), privacyPolicyUrl, questions[] (≤12; playbook: ≤4 for completion). Each question is a predefined profile field (`{ name, predefinedField: "EMAIL" }` — Contact/Work/Company/Education/Demographic library) or a custom question (`{ name, questionType: "SINGLE_LINE_TEXT" | "MULTIPLE_CHOICE", options?: [...] }`; ≤3 custom, MULTIPLE_CHOICE needs 2–30 options). Also supported: `locale {country,language}`, `formImageId`/`formImageUrn` (banner), `privacyPolicyText`, `consents[]` (≤5 disclosure checkboxes `{text, required}`), `hiddenFields[]` (≤20 `{name, value}` tracking fields), `legalDisclaimer`, `thankYou {message, cta, landingUrl | appointmentUrl}` (Calendly/Chili Piper booking link). The staged preview emits non-blocking best-practice warnings when a form has no qualifying question, no confirmation message/action, or no consent checkbox.
 
 #### `audit` — playbook diagnostic
 
@@ -1690,14 +1944,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 `google/gemini-3.1-flash-image-preview`):
+**Models** (`--model`, default `openai/gpt-5.4-image-2`):
 
 | Model | Best for | Aspect ratios | Sizes |
 |---|---|---|---|
-| `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` |
+| `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.5-flash` | Fast; extreme aspect ratios | standard **+** `1:4` `4:1` `1:8` `8:1` | `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` |
+| `google/gemini-3.1-flash-image-preview` | Same as 3.5 flash (preview) | extreme set | `0.5K`–`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`.
@@ -1706,7 +1960,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 `google/gemini-3.1-flash-image-preview`) |
+| `--model` | Model id (default `openai/gpt-5.4-image-2`) |
 | `--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. |
@@ -2163,17 +2417,13 @@ 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`), 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.)
+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.
 
 > 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) → `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.
+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.
 
 > `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.
 
@@ -2195,7 +2445,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>` | `meta,linkedin` — pass a single value to search **only** that platform |
+| `--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 |
 | `--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` |
@@ -2210,66 +2460,13 @@ Reading the scores: **`relevance`** (0–1) = match of the creative to your quer
 
 ### `baker winning-ads advertisers <brand>`
 
-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`.
+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`.
 
 ```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`)
@@ -2305,46 +2502,6 @@ Rules:
 
 ---
 
-### Marketing Tags (`baker tags`)
-
-Read the client's marketing/analytics tags (Meta pixel, GA4, Google Ads, GTM, Clarity, Hotjar, PostHog, …) — production tags overlaid with the changes staged in this chat.
-
-**The CLI is read-only.** Every tag change (create, edit, delete) goes through the `request_tag_input` tool (`baker_ui` MCP server): the agent proposes one or more changes — each becomes a tab in one blocking approval form — pre-filling the non-secret fields it knows; the user reviews, edits, fills secret fields, and approves or skips each tab. Approved changes stage on the chat and apply when the chat is published; discarding the chat drops them.
-
-`BAKER_CHAT_ID` must be set.
-
-```bash
-baker tags list       # effective view: production + staged, full readable config + secret status
-baker tags draft      # review the staged changes awaiting publish
-```
-
-Notes:
-
-- **`list` prints each tag's full readable config.** Every non-secret field is shown in full under the tag — the Clarity `projectId`, GA4 `measurementId`, the entire custom `code` snippet, etc. — so the agent reuses a stored value to pre-fill a follow-up change instead of asking the user for something already installed. Secrets are never among these fields. (`--json` emits the same data as the raw envelope.)
-- **Secrets never travel through this CLI or the chat.** Secret fields (`accessToken`, `apiSecret`, `authorizationToken`, `apiKey`, `conversionToken`, `oauthProviderId`) are entered only in the dashboard's secure tag form and flow straight into the staged draft; tool responses only ever name which secret fields are set/pending.
-- Staged creates get a server-generated `tag_temp_*` ref (returned in the tool result and printed by `list`). Use it (or a real tag id) as flow side-effect `tagIds` — the published tag keeps resolving under the temp ref.
-- Proposing a delete on a `tag_temp_*` ref drops the staged create instead.
-- Single-instance types (`code`, `posthog`, `datafast`) reject a second instance against the chat's effective view.
-- Conflicts at publish (tag deleted in the dashboard, config invalid) skip the op with a recorded reason — they never block the publish.
-
-### Forms / Flows (`baker flows`)
-
-Read this workspace's Forms (flows) and the configuration status of each one's **confidential fields** — side-effect connection secrets, OAuth connections, and third-party field definitions (HubSpot, Calendly, HighLevel, SavvyCal). Reads the local `_data.json` files; no secret values are ever decrypted or printed.
-
-**The CLI is read-only.** Author a Form's structure (nodes, conditions, side effects, field mappings) by editing its `_data.json` with the flow-builder skill. Configure the confidential fields it reports as `[missing]` / `[needs connection]` / `not selected` through the `request_flow_input` tool (`baker_ui` MCP server): the agent authors the surrounding structure, references it by `nodeId`/`sideEffectId`, and the user enters secrets, connects/picks OAuth accounts, and picks third-party forms in the dashboard. Those values are written (encrypted, where a secret) into the Form on the chat's branch and go live when the chat is published.
-
-```bash
-baker flows list            # every Form + how many confidential fields still need setup
-baker flows show contact    # one Form's confidential fields and their status
-baker flows show contact --full   # include the full flow tree (secret values redacted)
-```
-
-Notes:
-
-- **Secrets never travel through this CLI or the chat.** `show` reports only whether each field is configured (`[set]`/`[missing]`, `[connected]`/`[needs connection]`, selected/not selected) — never a value. Configured secrets appear only as `[configured]` ciphertext markers.
-- Confidential side-effect types: `httpWebhook`, `zapier`, `crmble` (typed credentials); `pipedrive`, `googleSpreadsheet`, `hubspotForm`, `goHighlevelContact` (OAuth connection + resource); `email`. Widget node types needing a resource pick: `calendly`, `savvycal`, `hubspot`, `hubspotMeeting`, `highlevel`, `highlevelForm`.
-- `request_flow_input` changes stage on the chat's branch and apply when the chat is published; discarding the chat drops them.
-
 ### Action Items (`baker actions`)
 
 Manage action items for the current chat. Most write operations stage on the chat's draft and apply atomically when the chat is published. Claim/release run live so other chats can see who's working on what.
@@ -2504,6 +2661,29 @@ baker canvas run my-canvas.json
 #     single node — that old serial workaround is obsolete.
 baker canvas run my-canvas.json --parallel 8
 
+# 2c. Runs persist across sandboxes/sessions by default: node results sync to a
+#     company-scoped remote cache (small JSON pointers; bytes stay in R2), so a FRESH
+#     sandbox re-runs an already-computed canvas at zero credits — assets rehydrate
+#     from R2, sha-verified. Every run also posts a durable history record (per-node
+#     outputs, credits, cached/fresh) that powers the dashboard's Creatives
+#     generations timeline. Opt out with --remote-cache off (env
+#     BAKER_CANVAS_REMOTE_CACHE=off) and --no-record. With --remote-cache off,
+#     assets are not uploaded, so a recorded run keeps its stats but has no
+#     browsable outputs — pass --no-record too if you want nothing persisted.
+baker canvas run my-canvas.json --remote-cache off --no-record
+
+# 2d. Regenerate a node whose prompt is fine (force a fresh roll). The engine is
+#     content-addressed: re-running an UNCHANGED node returns the identical cached
+#     render, never a new draw. To re-roll a node without editing its prompt (a
+#     color drifted, a face came out wrong), force it fresh two ways — NEVER
+#     restructure the canvas (repointing output / deleting nodes) to trick the cache:
+#       • One-shot flag — forces the named nodes + everything downstream fresh this
+#         run, leaving every other node cached (unknown ids fail loudly before billing):
+baker canvas run my-canvas.json --regenerate gen_4x5,gen_9x16
+#       • Persistent — add/bump a node's `regenerate` field in the canvas JSON
+#         (e.g. "regenerate": 2) and re-run; the fresh render is reproducible in any
+#         later session. Bump it again (3, 4, …) for each additional draw.
+
 # 3. Inspect a finished run (per-node timing, file list, optional video thumbs)
 baker canvas inspect <run_id>
 
@@ -2748,7 +2928,7 @@ Pick a `source` discriminator and declare the kind you expect. See [Ingestion](#
 
 **Outputs:** `asset` → `<params.expect>` / content-determined (URL strategy table) or extension-inferred (path).
 
-**Path-source notes:** the canvas is **not portable** to another machine without the file. Cache key folds the file's `mtime:size`, so editing the file invalidates the cache automatically. Supported extensions: `png`, `jpg`/`jpeg`, `webp`, `gif`, `avif`, `svg`, `mp4`, `webm`, `mov`, `m4v`, `mp3`, `wav`, `m4a`, `ogg`, `flac`, `json`, `txt`, `md`, `markdown`, `html`/`htm`, `csv`, `ttf`, `otf`, `woff`, `woff2`. Unknown extensions fall back to magic-byte sniffing for common image formats (and an SVG content sniff), else `kind_mismatch`. **SVG (`expect: "image"`) is rasterized to a transparent PNG on ingest** — brand logos are usually SVG, and image-generation models can't read SVG markup, so it's upscaled (longest edge near 2048px) with transparency preserved and the resulting asset carries `metadata.rasterized_from: "svg"`. **Video (`expect: "video"`) duration is probed from the file's ISO-BMFF (`mp4`/`mov`/`m4v`) header** and stamped as the canonical `duration_ms` (and `metadata.duration_ms`); other containers (e.g. `webm`) leave it unset. Downstream `video_deconstruct` uses this declared duration to size its ingest-poll timeout and preflight — without it those fall back to worst-case budgets and a single deconstruct step can hit the action time limit.
+**Path-source notes:** the canvas is **not portable** to another machine without the file. Cache key folds the file's `mtime:size`, so editing the file invalidates the cache automatically. Supported extensions: `png`, `jpg`/`jpeg`, `webp`, `gif`, `avif`, `svg`, `mp4`, `webm`, `mov`, `m4v`, `mp3`, `wav`, `m4a`, `ogg`, `flac`, `json`, `txt`, `md`, `markdown`, `html`/`htm`, `csv`, `ttf`, `otf`, `woff`, `woff2`. Unknown extensions fall back to magic-byte sniffing for common image formats (and an SVG content sniff), else `kind_mismatch`. **Any `expect: "image"` in a format image-generation models can't read (SVG, AVIF, HEIC, TIFF, BMP) is normalized to PNG on ingest** — model-safe rasters (`jpeg`/`png`/`gif`/`webp`) pass through untouched, everything else is transcoded so a reference can never 400 a generation. This applies to **both `source: "path"` and `source: "url"`** (URL images are fetched and normalized locally, since the backend can't run the rasterizer). SVG gets density-aware upscaling (longest edge near 2048px, transparency preserved). The normalized asset carries `metadata.rasterized_from` set to the source format (e.g. `"svg"`, `"avif"`). **Video (`expect: "video"`) duration is probed from the file's ISO-BMFF (`mp4`/`mov`/`m4v`) header** and stamped as the canonical `duration_ms` (and `metadata.duration_ms`); other containers (e.g. `webm`) leave it unset. Downstream `video_deconstruct` uses this declared duration to size its ingest-poll timeout and preflight — without it those fall back to worst-case budgets and a single deconstruct step can hit the action time limit.
 
 **Cost:** 0 engine credits for direct fetch + yt-dlp + local file. Handinger charges per scrape.
 
@@ -3198,9 +3378,9 @@ Accepted ref-image MIMEs vary by model — see per-model sections below.
 
 ###### Model: `bytedance/seedance-2.0`
 
-Production-quality ad-creative model. Routed via **fal.ai** (not OpenRouter) because OpenRouter's Seedance passthrough rejects photorealistic human reference frames via ByteDance's "real person" safety filter.
+Production-quality ad-creative model. Routed via **Replicate** (`bytedance/seedance-2.0`). NOTE: ByteDance's upstream "real person" likeness filter still blocks photorealistic human reference frames on **any** reseller — the escape is a synthetic/AI presenter face or routing real faces to Veo, not the provider.
 
-Ref-image MIMEs: `image/png`, `image/jpeg`, `image/webp` (via fal.ai).
+Ref-image MIMEs: `image/png`, `image/jpeg`, `image/webp`.
 
 | Name | Type | Required | Notes |
 |---|---|---|---|
@@ -3254,7 +3434,7 @@ Ref-image MIMEs: `image/png`, `image/jpeg`, `image/webp`, `image/gif` (via OpenR
 >
 > A scaffolded canvas carries this table inline at `metadata.todo.model_constraints`.
 
-> **Content-policy blocks are deterministic, not flaky.** fal.ai/Seedance rejects any first/last frame that reads as a real-person likeness (even an AI-generated face) — surfaced as `content_policy_blocked` (HTTP 422, **non-retryable**), even when fal's proxy chain masks it as a 5xx. Retrying **never** succeeds and wastes credits. Fix the cause: switch the clip to the other curated model (Veo routes around fal's filter), or make the source frame less photorealistic.
+> **Content-policy blocks are deterministic, not flaky.** ByteDance's Seedance rejects any first/last frame that reads as a real-person likeness (even an AI-generated face) — surfaced as `content_policy_blocked` (HTTP 422, **non-retryable**). This is ByteDance's upstream filter, so it fires on **any** reseller (Replicate or otherwise) — a provider swap does **not** route around it. Retrying **never** succeeds and wastes credits. Fix the cause: use a **synthetic/AI-generated** (non-identifiable) presenter face, or route a real face to **Veo** (`person_generation: allow_adult`), or make the source frame less photorealistic.
 
 ---
 
@@ -3305,7 +3485,7 @@ None.
 
 ##### `video_lipsync`
 
-Lip-sync a video to an audio track via VEED (fal.ai).
+Lip-sync a video to an audio track via Sync Labs `sync/lipsync-2` (Replicate).
 
 **Inputs**
 
@@ -3332,7 +3512,7 @@ Lip-sync a video to an audio track via VEED (fal.ai).
 
 ##### `video_background_remove`
 
-Strip a video's background → alpha WebM/H264. Powered by fal.ai VEED.
+Strip a video's background → transparent alpha WebM (VP9) or MOV (ProRes 4444). Powered by `sprited/birefnet-video` (Replicate).
 
 **Inputs**
 
@@ -3508,7 +3688,7 @@ Place and mix several audio clips onto one timeline — a music bed plus timed v
 
 ##### `image_background_remove`
 
-Strip background → transparent PNG (or mask). Powered by fal.ai BiRefNet v2.
+Strip background → transparent PNG. Powered by `men1scus/birefnet` (Replicate). (Note: mask-only output is no longer produced.)
 
 **Inputs**
 
@@ -3750,12 +3930,16 @@ Validate, then execute the graph. Blocks until done. Logs one line per node. Ret
 | `--run-id <id>` | auto ULID | Override the generated run id. |
 | `--cache-policy <policy>` | `read_write` | `read_write`, `bypass`, or `read_only`. |
 | `--concurrency <n>` | `5` (or `BAKER_CANVAS_CONCURRENCY`) | Max nodes executing at once within a layer. |
+| `--remote-cache <on\|off>` | `on` (or `BAKER_CANVAS_REMOTE_CACHE`) | Company-scoped remote cache + durable asset persistence. |
+| `--no-record` | records | Skip posting the durable run-history record (and its live progress). |
+
+**Run history streams live.** The run posts its plan (every node + its dependency edges) the moment validation passes, then re-posts a progress snapshot as each node starts and settles — the dashboard's creative workflow graph shows nodes flipping pending → running → done in real time, with each node's outputs attached as they land. A failed run keeps its per-node trail (what completed, what died). All best-effort: an unreachable backend never changes the run's outcome.
 
 **Failures don't abandon sibling work.** Nodes in a layer run under the concurrency cap and every one **settles** — a failed clip no longer kills its in-flight siblings, whose finished results still land in the content-addressed cache. One failure re-throws as-is; several are reported together (each failed node named). Re-running `baker canvas run` resumes from the cache and re-executes **only** the failed nodes and their descendants — never hand-orchestrate per-node renders. Long `video_generate` clips execute as **backend jobs** (the CLI polls; a CDN/proxy timeout can no longer kill a generation mid-flight).
 
 #### `baker canvas scaffold-video <video> [flags]`
 
-Turn a reference video into a **runnable, self-validated reproduction canvas** in one command — the video counterpart of `scaffold-static-ad`. It runs **billed passes** up front:
+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`**. Each scene's `start_frame_prompt`/`end_frame_prompt` are inlined into the frame nodes (see below); `prompt.json` then rides along as the shared **global style reference** (palette, cast cohesion) and as provenance.
 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.
@@ -3815,6 +3999,7 @@ baker canvas run ./reference-ad.video.canvas.json
 | Flag | Default | Effect |
 |---|---|---|
 | `--out <path>` | `<video-dir>/<name>.video.canvas.json` | Where to write the canvas (composition is copied alongside). |
+| `--slug <slug>` | — | Creative slug (lowercase kebab): writes the canvas to `src/creatives/<slug>/<slug>.canvas.json` — the repo convention that attaches every run to the creative's dashboard generation history. `--out` wins over `--slug`. |
 | `--frames <mode>` | `generate` | `generate` emits ONE recast keyframe per scene (the original frame is dropped so the dropped `el_*` assets drive identity); `reuse` wires the real extracted first+last frames straight into the clips (faithful, cheaper, no recast). |
 | `--ambient` | off | Give silent **b-roll** scenes native diegetic ambient (Seedance `generate_audio`), mixed deep under the music bed. Talking scenes already carry voice; check levels don't muddy the mix before keeping it. |
 | `--max-scenes <n>` | all source scenes | **Cost lever that reduces fidelity** — caps the deconstruct, MERGING away every scene beyond the cap (fewer cuts, lost beats). Prints a warning when set; omit it to reproduce every scene. |
@@ -3856,6 +4041,7 @@ baker canvas run ./static-ad.canvas.json
 |---|---|---|
 | `--context <text>` | — | Known provenance (advertiser, category, market) to ground the describe. |
 | `--out <path>` | `<image-dir>/static-ad.canvas.json` (cwd when `<image>` is a URL) | Where to write the canvas (`prompt.json` is written alongside). |
+| `--slug <slug>` | — | Creative slug (lowercase kebab): writes the canvas to `src/creatives/<slug>/<slug>.canvas.json` — the repo convention that attaches every run to the creative's dashboard generation history. `--out` wins over `--slug`. With a slug, the reference image is **downloaded into `src/creatives/<slug>/references/` and normalized to a model-safe format** (SVG/AVIF/HEIC/… → PNG), named from the actual bytes (not the URL string) so a presigned/extensionless URL never lands as PNG-bytes-in-`.jpg` — the canvas ingests that committed, portable path instead of the expiring URL. |
 | `--describe-model <id>` | registry default (`~google/gemini-pro-latest`) | Override the `image_describe` model. |
 | `--select-model <id>` | registry default (`~google/gemini-flash-latest`) | Override the element-selection `text_generate` model. |
 | `--layout-model <id>` | registry default (`~google/gemini-flash-latest`) | Override the global-layout `text_generate` model. |
@@ -3865,6 +4051,8 @@ baker canvas run ./static-ad.canvas.json
 
 Scaffolding runs (and bills) the two vision passes; **running** the result generates a billed image. `baker canvas validate` does not check that the `[TODO]` paths exist — supply the real files before `run`.
 
+**Resuming an interrupted run.** A long `baker canvas run` (multi-clip video) that is killed mid-render — session end, sandbox pause — leaves a marker under the outputs dir. The next `baker canvas run` of the same canvas automatically **resumes** that run: it reuses the run id so still-running billed jobs re-attach instead of being abandoned and re-billed, and completed nodes come from the cache. A clean completion (or a handled failure) clears the marker, so a normal re-run starts a fresh generation. Force a new run with `--fresh`, or pin a specific run with `--run-id <id>`. Independent same-layer nodes (e.g. video clips) fan out in parallel up to `--parallel`/`--concurrency` (default 8; env `BAKER_CANVAS_CONCURRENCY`).
+
 #### `baker canvas inspect <run_id> [--thumbnails]`
 
 One-page summary of a completed run: per-node duration + cache status, list of files in the run dir, optional video thumbnails (start/middle/end frames extracted via ffmpeg).
@@ -4327,6 +4515,26 @@ import {
 } from "@koda-sl/baker-cli/engine";
 ```
 
+## Creatives
+
+Publish an approved canvas render as a first-class Baker creative. The image uploads to the Baker image library (tagged `creative`), a creative record is created/updated, and the command prints the creative reference JSON the dashboard renders in chat.
+
+```bash
+baker creatives publish ./canvas/<run_id>/<final>.png --title "Spring Offer 4x5" \
+  --slug spring-offer-4x5 --run-id r_01JXYZ... \
+  --source-reference-url "https://www.facebook.com/ads/library/?id=..."
+```
+
+| Flag | Effect |
+|---|---|
+| `--title <text>` | Required. Human title for the creative. |
+| `--slug <slug>` | Creative slug (`src/creatives/<slug>/`) — attaches the image to that creative's row, marks it `published`. |
+| `--run-id <r_…>` | Pins the approved generation from the creative's run history as the published one. |
+| `--source-reference-url <url>` | Original reference ad URL, recorded on the creative. |
+| `--context <text>` | Optional describe context for the uploaded image asset. |
+
+Without `--slug` the command behaves as before (one creative record per published image). With `--slug` it upserts the repo-convention row — the same one the dashboard's Creatives tab and the `src/creatives/{slug}/` folder describe — so publish, repo sync, and run history all land on a single record regardless of order.
+
 ## Help & Discovery
 
 Every command supports `--help` for usage info:
@@ -4363,7 +4571,6 @@ This CLI is designed for AI agent consumption. Key patterns:
 - **0.105.0**: `baker images ...`, `baker videos ...`, and `baker testimonials ...` commands now type their `/api/{images,videos,testimonials}/...` request/response payloads from the shared `@baker/api` contract package instead of hand-written local interfaces. No command, flag, or output-shape changes.
 - **0.106.0**: `baker ads linkedin` gains staged write commands — `campaign-groups`/`campaigns`/`creatives` create|update|pause|resume|(archive|)duplicate, `audiences create|upload`, `conversions create|update`, `lead-forms create|update`, plus `draft [remove|clear]` for review/undo. Ops validate at stage time, apply on chat publish, and run simulated (`urn:li:simulated:*`) unless LinkedIn writes are enabled for the company.
 - **0.116.0**: `lead-forms create` models the full Campaign Manager form — `locale`, form banner image (`formImageId`/`formImageUrn`), predefined profile-field questions (validated enum) vs custom questions (`SINGLE_LINE_TEXT`/`MULTIPLE_CHOICE` with `options`, ≤3 custom), `privacyPolicyText`, disclosure `consents[]` (≤5), tracking `hiddenFields[]` (≤20), and `thankYou` confirmation CTA + landing/appointment link. Staged preview surfaces best-practice warnings (no qualifying question, no confirmation, no consent). No breaking flag changes.
-- **0.121.0**: `lead-forms create` drops the `privacyPolicyText` field — LinkedIn's versioned lead-form API has no privacy-policy-text slot, so it was silently discarded on publish. Use `legalDisclaimer` (shown under the form) or `consents[]` (disclosure checkboxes) instead. (Companion backend fix: staged lead-form questions were serialized in a shape LinkedIn dropped — they now publish correctly, and the staged preview lists each question.)
 - **0.119.0**: `draft amend`/`draft show` land on both `baker ads google` and `baker ads linkedin` — a generic JSON-merge-patch to update any staged op in place plus a full-payload receipt, replacing remove+recreate as the correction path. Google gains `assets update` and `asset-groups create|update` (Performance Max asset groups are now their own entity — `ads create --format performanceMaxAssetGroup` never worked and is gone); `ads create --format video` moves from a bare YouTube id to `--video-assets` refs (**breaking flag change** — stage the video as an asset first); `--format demandGen` gains `--image-assets`/`--square-image-assets`/`--logo-image-assets` and flag-building for headlines/descriptions. LinkedIn's `draft list` now renders a readable Campaign group ▸ Campaign ▸ Creative tree by default (`--json` for raw), `creatives update` gains `--campaign` (re-parent while staged), and `campaigns update` passes create-only fields (`--group`/`--type`/`--locale`/`--associated-entity`) through when amending a `li_temp_*` staged create instead of always stripping them.
 
 ## Publishing