@aicopycoders/exodus 2026.7.200-beta.5 → 2026.7.200-beta.7

package/assets/references/meta-ads-mcp-probe.md

@@ -0,0 +1,167 @@
+# Meta Ads MCP — live probe findings (wayfinder #563)
+
+Probed 2026-07-14 against Brad's real accounts via the **official Meta Ads MCP**
+(`https://mcp.facebook.com/ads`, remote HTTP MCP, OAuth-in-browser). All calls
+read-only. Primary probe account: **Matt Beard FPI** (act `…820395`, ~$62.9k
+spend / 1.07M impressions in the trailing 90 days). Feeds the enrichment-path
+ticket (#565) and the bridge contract (#566) on map #562.
+
+## TL;DR for the specs
+
+1. **The winner query works end-to-end**: per-ad `amount_spent`, `results`
+   (labeled with the result type), `cost_per_result`, `ctr`, `cpm`,
+   `impressions`, `lead`, `purchase_roas` over any date preset or custom
+   range, sortable by any metric. A "top ads by spend, then threshold on
+   cost-per-result" winner definition is executable **agent-side over sorted
+   results** — server-side *metric filtering* consistently 500s (see gotchas).
+2. **The Ad Library cross-reference exists but is fuzzy**: `ads_library_search`
+   by `page_ids` returns the public **`adArchiveId` directly** (the result `id`;
+   `ad_snapshot_url` = `facebook.com/ads/library/?id=<archiveId>`). But library
+   results carry only `ad_creative_link_title` + creation/delivery timestamps —
+   **no body text, no ad-account ad id** — so account-ad → library-ad mapping is
+   a **fingerprint match** (creative `title` == library `ad_creative_link_title`,
+   ± creation-time proximity), not a direct key. No tool/field exposes
+   `adArchiveId` from the account side.
+3. **Images are fully retrievable; videos are not.** Image detail gives a
+   signed full-res CDN `url` (+ `url_128`, `permalink_url`, dimensions) —
+   downloadable now, but the URL **expires** (`oe=` param). Video detail gives
+   `length`, poster `picture`, and a *relative* `permalink_url` — **no source /
+   download URL**. This confirms the map's scrape-first asset strategy, with
+   MCP image-pull as gap-filler and **no MCP gap-filler for video files**.
+4. **Naming comes through intact** at every level (`name` on ad/adset/campaign,
+   creative `name`, video `title` — titles even encode aspect ratios like
+   `-9x16`). Naming-conventions guidance can rely on free-text ad names plus
+   `campaign_id`/`adset_id` for hierarchy grouping.
+5. **Setup surface is one URL**: add `https://mcp.facebook.com/ads` as a remote
+   MCP server; OAuth happens in the browser with the user's own Facebook login.
+   Per-account gates: `is_ads_mcp_enabled` and `is_queryable` (disabled/flagged
+   accounts come back with a human-readable `not_queryable_reason`).
+
+## Tool-by-tool findings
+
+### `ads_get_ad_accounts`
+Returns **every** account the user can access — Brad sees 13 across 5
+businesses (own + client accounts), each with `ad_account_id`,
+`ad_account_name`, owning `business_id`/`business_name`, `account_status`,
+`currency`, `is_ads_mcp_enabled`, `is_queryable`, `not_queryable_reason`.
+Two disabled accounts surfaced with the flag reason string. **Multi-account
+selection is a real UX step the skill must handle** (fog item on the map,
+now sharpened). Account names can be empty strings.
+
+### `ads_get_ad_entities` (the insights workhorse)
+- Levels: `account` / `campaign` / `adset` / `ad`. Metrics require
+  `date_preset` (e.g. `last_90d`, `maximum`) or `time_range` JSON;
+  `time_increment` gives time series.
+- Real sample (ad level, last_90d, sorted `amount_spent_descending`):
+
+  ```json
+  {
+    "id": "120241083993850557",
+    "name": "PT-Intro-me-and-ai-Image-Promoted",
+    "effective_status": "ADSET_PAUSED",
+    "creative_id": "952613677477713",
+    "campaign_id": "120239743848310557",
+    "adset_id": "120241083975980557",
+    "amount_spent": "$8,980.38 USD",
+    "results": {"value": "98 (Website appointments scheduled)"},
+    "cost_per_result": {"value": "$91.64 USD (Website appointments scheduled)"},
+    "impressions": "212,816", "ctr": "4.20%", "cpm": "$42.20 USD",
+    "lead": "7", "created_time": "April 17, 2026"
+  }
+  ```
+- **Values are formatted display strings**, not numbers (`"$8,980.38 USD"`,
+  `"4.20%"`, `"Not available"` for zero-delivery ads). Exception: account
+  level also returns numeric `amount_spent_cents`. The bridge/skill must
+  parse display strings (or treat them as verdict-snapshot text, which is
+  what the map's verdict-snapshot design wants anyway).
+- `results`/`cost_per_result` self-label the optimization outcome ("Website
+  appointments scheduled", "Website purchases") — ideal raw material for the
+  verdict snapshot, and it makes result-type explicit across mixed-objective
+  accounts.
+- Field catalog via `ads_get_field_context`: `spend` aliases `amount_spent`;
+  `lead`, `purchase_roas`, `results`, `cost_per_result`, `clicks`, video
+  metrics (`video_thruplay_watched_actions`, `video_p50_watched_actions` —
+  metric-only, not filterable/sortable) exist. **Not present**: `purchase`,
+  `cost_per_purchase`, `cost_per_lead`, `roas`, `campaign_name`/`adset_name`
+  (use ids + a campaign-level call), `link_click`, `hook_rate`,
+  `ad_archive_id`, `preview_shareable_link`, `effective_object_story_id`
+  (creative-side only).
+- Hierarchy: ads carry `campaign_id` + `adset_id`; `objective` lives on
+  campaign/ad, `optimization_goal` on adset.
+
+### `ads_get_creatives`
+The content payload. By id, returns `body` (primary text, full), `title`
+(headline), `call_to_action_type`, `object_type`, `image_hash`, `image_url`
+(signed CDN), `thumbnail_url`, `object_story_id` +
+`effective_object_story_id` (`<pageId>_<postId>`) and
+`effective_instagram_media_id`. Listing mode returns only
+id/name/account_id/status — **must re-fetch by `creative_ids` for content**.
+`link_url` was absent on the probed `SHARE`-type creative (link lives in the
+story post). The `<pageId>_<postId>` story id is the strongest identity hook
+for enrichment (post permalink = `facebook.com/<pageId>/posts/<postId>`).
+
+### `ads_get_ad_images` / `ads_get_ad_videos`
+- Image by hash: `url` full-res signed CDN JPEG + `url_128` + `permalink_url`
+  + `width/height` + timestamps. Downloadable **now**; URL expires later.
+- Video by id: `title`, `length` (seconds float), poster `picture`, relative
+  `permalink_url` (`/<pageId>/videos/<videoId>/…`). **No source URL.**
+- **Gotcha (both tools + creatives): the documented "omit `fields` → all
+  fields" default is broken on by-id lookups** — a `video_ids` lookup without
+  `fields` returned only `{id}`. Always pass explicit `fields`.
+
+### `ads_library_search`
+By `page_ids` (page id from the creative's `effective_object_story_id` prefix
+or `ads_get_ad_account_pages`): returns per ad `id` (**= adArchiveId**),
+`page_id`, `page_name`, `ad_creative_link_title`, `ad_creation_time`,
+`ad_delivery_start_time`, `ad_snapshot_url`, `currency`, plus
+`estimated_total_count` (48 for the probed page). Requires the caller to have
+an active ad account. No body text, no media URLs → cross-reference by
+title + time fingerprint, then hand the `adArchiveId` to the existing
+ScrapeCreators pipeline for full public payload (media, transcription).
+
+### `ads_get_ad_preview`
+Returns an actual **rendered creative image** as in-context image content +
+an authenticated, expiring `preview_url` iframe (business.facebook.com). Good
+for HITL confirmation inside the skill ("is THIS the winner you mean?");
+not a durable asset source.
+
+### `ads_get_ad_account_pages`
+Returns `page_id`s but `page_name` came back `"(unknown)"` on the probed
+account — get the human page name from the library search result instead.
+
+## Gotchas / reliability
+
+- **Metric filtering 500s.** Every `filtering` on `ad.amount_spent`
+  (GREATER_THAN, dollar or cent values) → `Internal Server Error`, repeatably.
+  Attribute filters (`ad.effective_status IN [ACTIVE]`) work. Metric *sorting*
+  works. → Winner definitions execute as: sort by metric server-side, pull top
+  N, threshold agent-side.
+- **Transient 500s** happen on entity queries too (one wide 12-field call
+  failed once, then an identical narrower call succeeded; a later identical
+  call with the same fields also succeeded). Retry-once is a sane default.
+- Only ONE `breakdowns` value per call; only documented params exist.
+- The `ads_insights_*` tools (`performance_trend`, `advertiser_context`, etc.)
+  are opinionated analysis wrappers (trend narratives, funnel context), not
+  raw data — the skill's mining procedure should stay on `ads_get_ad_entities`.
+- Every tool takes an `advertiser_request` verbatim-user-words param — a
+  Meta-side audit surface; the skill should pass the user's actual ask through.
+
+## What this settles for the open tickets
+
+- **#565 (enrichment)**: key = fingerprint match into Ad Library
+  (`title` + creation time → `adArchiveId`) → ScrapeCreators; MCP `image_url`
+  is the image gap-filler (download immediately — signed URLs expire); there is
+  **no video-file gap-filler** via MCP — video enrichment depends on the ad
+  still being scrapeable (or the post being public via
+  `effective_object_story_id`).
+- **#566 (bridge contract)**: payload fields available agent-side per winner:
+  ad id, name, campaign/adset ids, creative id, body, title, CTA type,
+  story/IG ids, image hash + bytes, video id + length + poster, metrics as
+  display strings (+ result-type labels), account id/currency, page id,
+  matched `adArchiveId` (best-effort). Numbers arrive as formatted strings —
+  the contract should either accept snapshot strings verbatim or require the
+  agent to parse.
+- **#564 (interview)**: winner definitions must be expressible as
+  sort-metric + date-window + agent-side thresholds; `results` self-labeling
+  means the definition can be per-result-type; multi-account users (13 visible
+  here) need an explicit account-selection step.

package/assets/references/native-audio-dialogue.md

@@ -0,0 +1,178 @@
+# Native-Audio Dialogue — per-model way to make `dialogue` actually get SPOKEN (in English)
+
+**Research date:** 2026-07-13
+**For:** Build ticket #547 (send storyboard `dialogue` to the native-audio video models). Feeds map #545.
+**Scope:** The four v1 picker models, all via Kie.ai — `veo3_fast` (Veo 3.1 Fast), `veo3` (Veo 3.1 Quality), `bytedance/seedance-2` (Seedance 2.0), `kling-3.0/video` (Kling 3.0).
+**Method:** Primary = docs.kie.ai model pages (fetchable), Google's official Veo prompting guide (cloud.google.com + ai.google.dev), fal.ai model guides, Kling official blog (blocked to automated fetch — corroborated via fal + community). Community tricks flagged inline. Builds on the #529 catalog (`workspace/references/kie-video-models.md`) and the #533 bake-off (`workspace/output/bakeoff-533/`).
+**Confidence labels:** `[docs]` verified on a first-party API/prompting doc · `[official-guide]` first-party prompting guide (Google/Kling/ByteDance) · `[vendor-guide]` fal.ai / infra vendor guide · `[community]` community-reported, use with caution.
+
+---
+
+## The core problem (confirmed in code)
+
+`buildClipPrompt` in `scout/src/workflow/video/clips.ts` never reads `scene.dialogue`. It only threads `videoPrompt` + `voText` (and `voText` is dropped entirely when native audio is ON). So on a native-audio run the model is told `generate_audio: true` / `sound: true` with **no words to say**, and it invents speech-shaped babble. Every fix below is about getting the `scene.dialogue[]` lines (`{ speaker, line }`, see `convex/lib/workflow/storyboardContract.ts`) into the prompt in the format each family actually speaks — in English, without burning in captions.
+
+**None of the four models accepts spoken dialogue as a structured API field.** On all four, through Kie, dialogue is **in-prompt text only**. (Details in §"Structured audio params".)
+
+---
+
+## TL;DR table
+
+| Family | Dialogue embedding format (recommended) | Force English | Subtitle guard | Structured audio params (Kie) | Pacing guidance |
+|---|---|---|---|---|---|
+| **Veo 3.1 Fast / Quality** (`veo3_fast`,`veo3`) | Inline attribution **with quotes**, per Google's own guide: `She says, in English: "…"`. Multi-speaker = separate attributed sentences. | Write English inside the quotes **and** add an explicit clause `spoken in English (American accent)`. Keep `enableTranslation:false` (it translates the *prompt* to English and can paraphrase quoted lines). No language param. `[docs]`/`[official-guide]` | **No `negativePrompt` param on Kie's `/veo/generate`** — in-prompt only. Keep `ANTI_SUBTITLE_CORE` first; community: quotes can trigger captions, so the anti-caption clause is load-bearing for Veo. `[docs]`/`[community]` | **None.** Audio always on, not togglable; no voice/reference-audio field. `[docs]` | Keep each line short; dialogue lives inside a 4/6/8s clip. Google: short lines sync best. `[official-guide]` |
+| **Seedance 2.0** (`bytedance/seedance-2`) | **Speaker label + colon + double quotes**: `The senior woman, arms crossed, says: "…"`. Short lines; insert written beats (`She pauses, then continues:`) as resync anchors between lines. `[vendor-guide]` | Add per-scene `American accent, conversational tone` + write English text. Mandarin is its most-consistent lip-sync language, so English **must** be stated explicitly or it drifts. `[vendor-guide]`/`[community]` | No first-party subtitle guidance found. Keep `ANTI_SUBTITLE_CORE`. Quoted lines are the documented format, so the core's on-screen-text ban complements (not conflicts). `[community]` | `generate_audio` bool (default true). `reference_audio_urls` (≤3, 2–15s, wav/mp3) exists — a voice/style reference lever, **not** a documented dialogue-content field. `[docs]` | ~**12 words / 10s**, ~**20 words / 15s** (~1.2 wps); sync drops past 10s; record "mental" pace ~80% of natural. **Tighter than the repo's 17 chars/s VO budget.** `[vendor-guide]` |
+| **Kling 3.0** (`kling-3.0/video`) | **Bracketed speaker label + tone, colon, quotes**: `[Character A: Exhausted Partner, trembling voice]: "…"`. Consistent labels (no pronouns); for multi-speaker insert a switch beat. `[official-guide]`/`[vendor-guide]` | Specify language in the prompt (`spoken in English`) — helps phoneme mapping. Supports EN natively but also CN/JA/KO/ES, so state it. No language param. `[official-guide]`/`[community]` | No first-party subtitle guidance found. Keep `ANTI_SUBTITLE_CORE`. `[community]` | `sound` bool. `kling_elements[].audio` (5–30s) is an element-level audio lever, not a dialogue-voice field. `[docs]` | Short, single-speaker segments sync best; use Master/`pro` mode when lip-sync is scrutinized; medium shots > extreme close-ups. `[official-guide]` |
+
+---
+
+## Recommended rider / format per API family (implementation-ready for #547)
+
+### Where it slots into the existing rider stack
+
+`buildClipPrompt` today (native audio ON) emits, in order:
+
+1. `ANTI_SUBTITLE_CORE`
+2. `MOTION_POLICY`
+3. `FIRST_FRAME_RIDER` (if a Scene Frame is wired)
+4. `body` (the `videoPrompt`)
+
+**Add a DIALOGUE block as a new final section, ONLY when `nativeAudio === true` AND `scene.dialogue.length > 0`.** Rules:
+
+- Keep `ANTI_SUBTITLE_CORE` **first and unchanged** — it is the only subtitle guard Veo has (no `negativePrompt` param), and its wording bans *on-screen* text ("no dialogue text, no transcript text"), which does not suppress *spoken* audio.
+- The dialogue block is **family-specific** (Veo/Seedance/Kling format differently), so it must be built where the family is known. Two clean options:
+  - **(A)** Thread `scene.dialogue` + `family` into `buildClipPrompt` and branch there.
+  - **(B)** Keep `buildClipPrompt` family-agnostic; in `generateSceneClip` (which already has `spec.family`) append a `buildDialogueBlock(family, scene.dialogue)` string to the returned prompt.
+  Recommend **(B)** — smallest change, keeps `buildClipPrompt` pure, and the per-family request builders already live next to it.
+- `buildClipPrompt` currently accepts `voText` but **not** `dialogue`. #547 must thread `scene.dialogue` through `generateSceneClip` (it already has the full `scene`).
+- When `nativeAudio === false`, do **not** emit dialogue (current behavior — mouths shut, VO track). Unchanged.
+
+### Concrete template strings
+
+Let `LANG = "spoken in English (natural American accent)"`.
+
+**Veo (`veo3_fast`, `veo3`)** — inline, quoted, per Google's guide:
+```
+DIALOGUE (on-camera, lip-synced, {LANG}; no on-screen captions):
+<Speaker A description> says: "<line 1>"
+<Speaker B description> replies: "<line 2>"
+```
+- Single speaker → one attributed sentence.
+- Use the storyboard `speaker` string as the attribution ("The woman", "The barista"). Quotes around the exact words per Google's official example: `A woman says, "We have to leave now."`
+- Do **not** set `enableTranslation:true` (it translates/paraphrases the prompt to English and can rewrite the quoted line). Current code already sends `enableTranslation:false` — keep it.
+
+**Seedance (`bytedance/seedance-2`)** — label + colon + quotes, short lines, beats:
+```
+DIALOGUE ({LANG}, conversational tone; lip-synced to the speaker):
+<Speaker A description> says: "<short line>"
+[She pauses, then continues:] "<next short line>"
+```
+- Colon-then-quotes is the fal-documented Seedance format: `The senior woman, arms crossed, says: "You ran that client call better than I would have."`
+- Split anything over ~10–12 words into two lines with a written beat between them (`She pauses, then continues:`) — Seedance uses written beats as resync anchors.
+- The `American accent, conversational tone` clause is the sourced mitigation for its Mandarin-lip-sync bias — include it every scene.
+
+**Kling (`kling-3.0/video`)** — bracketed labelled speakers:
+```
+DIALOGUE ({LANG}):
+[<Speaker A label>, <tone>]: "<line>"
+[<Speaker B label>, <tone>]: "<line>"
+```
+- Consistent bracket labels, no pronouns (`[Character A: Exhausted Partner, trembling voice]: "You never listen to me."`).
+- Map the storyboard `speaker` to the label and (optionally) infer a tone from `scene.narrative`.
+- Prefer `mode: "pro"` when dialogue is central (official: use Master/high mode for scrutinized lip-sync). Current `klingModeFromResolution` already honors the operator's std/pro pick.
+
+### Request-builder param changes
+
+- **`buildVeoBody`** — no new params. `enableTranslation:false` stays. Dialogue rides in `prompt`. (Kie Veo exposes no audio/voice/negativePrompt field — verified on the docs.)
+- **`buildSeedanceInput`** — no *required* new params; `generate_audio` already tracks the toggle. Optional future lever: `reference_audio_urls` for voice consistency (§Cross-scene). Dialogue rides in `prompt`.
+- **`buildKlingInput`** — no new params; `sound` already tracks the toggle. Dialogue rides in `prompt`.
+
+**Net:** #547 is a **prompt-assembly change, not a request-schema change.** The only transport-level opportunity (Seedance `reference_audio_urls`) is optional and unverified for dialogue voice.
+
+---
+
+## Per-model deep dives
+
+### Google Veo 3.1 (`veo3_fast`, `veo3`) — Kie `/api/v1/veo/generate`
+
+- **Dialogue format — quotes, inline attribution.** Google's official *Ultimate prompting guide for Veo 3.1* and the Gemini API docs both use quotation marks with a speaker + verb: `A woman says, "We have to leave now."` and `"This must be the key," he murmured.` The guide lists three audio cue types — Dialogue (quotes), Sound Effects (describe explicitly), Ambient — and says the model "captures the nuance of these cues to generate a synchronized soundtrack." `[official-guide]`
+- **Colon-vs-quotes tension (must reconcile).** A widespread community technique claims you should use a **colon and NO quotation marks** (`the man says: hello there`) because Veo "may interpret quotation marks as text to display" and burn in captions. `[community]` This directly contradicts Google's own quoted examples. Resolution for #547: **follow Google (quotes) for reliable lip-sync**, and neutralize the caption risk with the explicit anti-subtitle clause (which we already have) rather than dropping quotes. If Veo captions still appear in testing, the fallback is the colon-no-quotes variant — treat as a tuning knob, not the default.
+- **Subtitle suppression.** Kie's `/veo/generate` exposes **no `negativePrompt` field** (verified — the param list is prompt/model/aspect_ratio/duration/resolution/generationType/imageUrls/enableTranslation/watermark/callBackUrl only; ai.google.dev's Gemini-API Veo page likewise shows no negativePrompt for the dialogue flow). So the only caption lever is **in-prompt text** — exactly what `ANTI_SUBTITLE_CORE` provides. Community adds "no subtitles"/"no captions" phrasing and keeping dialogue under the 8s clip length so the model "focuses on visuals and audio rather than captions." `[docs]`/`[community]`
+- **English forcing.** No language param. `enableTranslation` "enable[s] prompt translation to English … before video generation" — i.e. it translates *your prompt*, not the spoken output; for an already-English prompt it's a no-op at best and a paraphrase risk at worst, so **keep it false**. Force English by (a) writing the words in English inside the quotes and (b) an explicit `spoken in English (American accent)` clause; Veo "will handle the accent and lip-sync automatically" from the written language. `[docs]`/`[community]`
+- **Audio toggle.** "All videos ship with background audio by default"; rarely suppressed for sensitive scenes. Not togglable on Kie — matches `audioTogglable:false` in `models.ts` (code already forces `nativeAudio=true` for the veo family). `[docs]`
+- **Bake-off note (#533):** Veo 3.1 Fast native-audio clip generated in ~10s wall (anchored) — the fastest of the four; the audio dialogue shoot-out cell is `dlg-veo3-quality.mp4` / `clipref-s1.mp4`. Sora 2 was excluded (paused on Kie). See `workspace/output/bakeoff-533/index.html`.
+
+Sources: [docs.kie.ai/veo3-api/generate-veo-3-video](https://docs.kie.ai/veo3-api/generate-veo-3-video) · [Ultimate prompting guide for Veo 3.1 (Google Cloud)](https://cloud.google.com/blog/products/ai-machine-learning/ultimate-prompting-guide-for-veo-3-1) · [Gemini API Veo docs](https://ai.google.dev/gemini-api/docs/veo) · [GlobalGPT Veo 3.1 dialogue guide](https://www.glbgpt.com/hub/how-to-make-characters-speak-in-veo-3-1-the-ultimate-guide-to-dialogue-audio-lip-sync/) `[community]` · [VidAU "no subtitles"](https://www.vidau.ai/veo-3-prompt-no-subtitles/) `[community]`
+
+### ByteDance Seedance 2.0 (`bytedance/seedance-2`) — Kie jobs API
+
+- **Dialogue format — label, colon, double quotes.** fal.ai's Seedance 2.0 prompting guide: "Put the spoken words in double quotes, and the model voices them, matching the lip movement to each line," e.g. `The senior woman, arms crossed, says: "You ran that client call better than I would have."` For multi-speaker, hold a two-shot then cut to the speaker, "lips matched to each line." Keep lines short — "Long monologues drift out of sync, so I split a speech into a couple of shorter lines and let the cuts carry it." `[vendor-guide]`
+- **Written beats as resync anchors.** "Insert a written beat ('She pauses, then continues:') between sentences — Seedance uses written beats as resync anchors." Directly useful for splitting a scene's multiple `dialogue` lines. `[vendor-guide]`
+- **English forcing / drift.** Seedance supports 8+ languages incl. English/Mandarin, but "Mandarin produces the most consistent lip sync," and separate generations of the same character drift in accent unless pinned. Sourced mitigation: **"Specify accent explicitly in every scene prompt: 'American accent, conversational tone.'"** No API language param. The specific "drifts to Chinese/Mandarin" failure the map calls out is **community-reported and consistent with these vendor guides, but I could not pin a primary Reddit/X thread this session** — treat the drift as real-risk, the accent clause as the sourced fix. `[vendor-guide]`/`[community]`
+- **Subtitle risk.** No first-party statement that quoted Seedance dialogue burns in captions; no first-party suppression guidance found. Keep `ANTI_SUBTITLE_CORE`. `[community]`
+- **Pacing (important — conflicts with the repo budget).** fal / UGC-Copilot guidance: **~12 words per 10s, ~20 words per 15s (~1.2 words/sec)**; "short sentences … five to ten words per line is the sweet spot"; sync quality "drops past 10" seconds. The storyboard gate (`VO_CHARS_PER_SEC = 17`, `sceneSpeechSec`) budgets ~17 chars/s ≈ ~3 words/s — **~2.5× looser than Seedance actually speaks cleanly.** A scene that "fits" at 17 cps can still overflow / rush / desync on Seedance native audio. **Recommendation for #547 (or a fast-follow):** use a tighter chars-per-second budget for native-audio *dialogue* (≈9–10 cps, ~1.2–1.5 wps) than for VO narration. Seedance does not hard-truncate; it rushes and desyncs. `[vendor-guide]`
+- **Bake-off note (#533):** Seedance native audio was slowest by far — measured ≈24 min/clip, which is why `POLL_TIMEOUT_VIDEO_MS` was raised to 35 min in `kie-video.ts`. It won "best native audio" per the map, but at a steep latency/cost. `dlg-seedance.mp4` vs the silent control `dlg-seedance-silent.mp4` vs pixr mux `dlg-elevenlabs-mux.mp4`.
+
+Sources: [docs.kie.ai/market/bytedance/seedance-2](https://docs.kie.ai/market/bytedance/seedance-2) · [fal.ai Seedance 2.0 prompting guide](https://fal.ai/learn/tools/seedance-2-0-prompting-guide) · [UGC-Copilot Seedance native audio guide](https://ugccopilot.ai/blog/seedance-2-native-audio-generation-guide/) `[community]` · [Cutout.pro Seedance audio guide](https://www.cutout.pro/learn/blog-seedance-2-0-audio-guide/) `[community]`
+
+### Kling 3.0 (`kling-3.0/video`) — Kie jobs API
+
+- **Dialogue format — bracketed labelled speakers.** fal.ai's Kling 3.0 guide: `[Character Label, tone/emotion]: "dialogue text"`, e.g. `[Character A: Exhausted Partner, trembling frustrated voice]: "You never listen to me."` Structured naming (P1): "Character labels must be consistent. Avoid pronouns or synonyms." For sequencing/multi-speaker, insert a switch beat ("this is when the speaker switches"). `[vendor-guide]`
+- **Official audio behavior.** Kling's own blog (Kling VIDEO 3.0 / 3.0 Omni "Native Audio") — dialogue, sound and lip movement are generated together. Best-practice guidance (corroborated across Kling + fal + community): short simple sentences beat rapid complex speech; **specify the language in the prompt to help phoneme mapping**; medium shots sync better than extreme close-ups; avoid overlapping dialogue — single-speaker segments sync much better; use Master/high mode when lip-sync will be scrutinized. `[official-guide]`/`[community]` (Note: the official Kling blog returns HTTP 446 to automated fetch; content is corroborated via the search excerpt + fal guide, not a direct page read.)
+- **Language support / forcing.** Supports Chinese, English, Japanese, Korean, Spanish + dialects/accents (American/British/Indian English). No language param — state `spoken in English` in the prompt. `[official-guide]`/`[community]`
+- **Kie param nuance.** On Kie, the native-audio toggle is `sound` (bool) and `prompt` "takes effect when multi_shots is false" — our builder sends `multi_shots:false`, so the single `prompt` (with the dialogue block) is the right channel. Multi-shot mode would need the `multi_prompt[]` array instead (each shot's `prompt` ≤500 chars); v1 does not use it. `[docs]`
+- **Bake-off note (#533):** `dlg-kling.mp4`, ~103s gen — much faster than Seedance, comparable to Veo Quality.
+
+Sources: [docs.kie.ai/market/kling/kling-3-0](https://docs.kie.ai/market/kling/kling-3-0) · [Kling official: Kling Video 3.0 Omni Native Lip Sync & Audio](https://kling.ai/blog/kling-video-3-omni-native-lip-sync-audio-guide) (446 to automated fetch) · [fal.ai Kling 3.0 prompting guide](https://blog.fal.ai/kling-3-0-prompting-guide/) · [Imagine.art Kling 3.0 prompt guide](https://www.imagine.art/blogs/kling-3-0-prompt-guide) `[community]`
+
+---
+
+## Cross-scene voice consistency (map fog — levers that exist)
+
+The problem: each scene is an independently-generated clip, so the same actor gets a **different synthesized voice** each time. No picker model exposes a first-class "voice ID" through Kie's jobs/veo API. Levers found, none verified to solve it:
+
+- **Seedance `reference_audio_urls`** `[docs]` — up to 3 audio clips (2–15s, wav/mp3), also accepts `asset://{assetId}`. Documented as a *reference* input (style/voice conditioning), **not** as the dialogue-content source. **Fog:** it *might* anchor timbre if the same reference clip is passed to every scene — but the docs don't say it transfers voice identity, and whether the model speaks the *prompt* text in the *reference* voice is untested. This is the single most promising Kie-native lever; worth an empirical probe before relying on it. Seedance is also the only one of the four with any audio-input field.
+- **Kling `kling_elements[].audio`** `[docs]` — per-element audio (5–30s) tied to an `@element`. Element references are aimed at *visual* character consistency (2–4 images/element); the audio slot is under-documented for voice transfer. **Fog.**
+- **Veo** — **no audio input at all.** No lever for cross-scene voice. `[docs]`
+- **Higher-level "voice fingerprint" features** (e.g. fal's "AI Twins" persona voice-locking) exist at the infra layer but are **not exposed through Kie's jobs API**, so not usable in this pipeline as-is. `[community]`
+
+**Practical read for v1:** there is no reliable cross-scene voice-consistency lever through Kie today. If it matters, the more controllable path remains the old pixr architecture — render silent + one ElevenLabs voice muxed across all scenes (the `dlg-elevenlabs-mux.mp4` control in #533). Keep cross-scene voice in the fog for #547; if pursued, the first experiment is Seedance `reference_audio_urls` with a fixed reference clip.
+
+---
+
+## Duration / pacing behavior (per family)
+
+- **Seedance:** ~12 words/10s, ~20 words/15s; sync degrades past ~10s and with long lines; does **not** hard-truncate — it rushes and drifts out of sync. Written beats resync it. `[vendor-guide]`
+- **Veo:** fixed 4/6/8s clips; keep dialogue short enough to land inside the clip; Google/community both say short lines sync best and staying under 8s reduces caption bleed. `[official-guide]`/`[community]`
+- **Kling:** 3–15s; short single-speaker segments sync best; no published words/sec number found. `[official-guide]`
+- **Repo gate today:** `sceneSpeechSec = max(voText, dialogue) ÷ 17 chars/s` fits *both* tracks to `durationSec` and fails loud rather than truncating. For **VO narration** 17 cps is reasonable; for **native lip-synced dialogue** it is too loose (Seedance ≈ 7–8 cps of clean speech). **Actionable:** consider a separate, tighter cps for native-audio dialogue-fit. (Flagged as a recommendation; whether #547 changes the budget or just formats the block is a scoping call.)
+
+---
+
+## Open questions / unverifiable this session
+
+1. **Veo colon-vs-quotes for captions** — Google officially uses quotes; the "quotes burn captions, use a colon" claim is community-only and contradicts the official examples. Not resolvable without a live Veo-on-Kie A/B. Default to quotes + anti-caption clause; keep colon-no-quotes as a fallback knob. `[community]`
+2. **Seedance→Chinese drift** — consistent with vendor guides ("Mandarin most consistent," "specify accent every scene") but no primary Reddit/X thread pinned this session. The accent clause is the sourced mitigation; the drift itself is community-level. `[community]`
+3. **Whether `ANTI_SUBTITLE_CORE`'s "no dialogue text" wording ever suppresses *spoken* audio** — it targets on-screen typography, so it *shouldn't*, but a paranoid model could misread it. Low risk; worth watching in the first native-audio+dialogue test. Not observed in #533 (which ran without a dialogue block).
+4. **Seedance `reference_audio_urls` as a voice-consistency lever** — exists in the API but its effect on spoken-dialogue voice is undocumented. Needs an empirical probe.
+5. **Kie Veo `negativePrompt`** — absent from Kie's `/veo/generate` param list (Vertex AI Veo has one; Kie's endpoint does not expose it). Confident but worth a 1-line confirm if #547 wants a param-based caption guard.
+6. **Exact per-family words/sec** — only Seedance publishes numbers; Veo/Kling give qualitative "keep it short." Any tighter dialogue-fit budget will be model-family-specific and partly empirical.
+
+---
+
+## Sources
+
+Primary / first-party:
+- [docs.kie.ai — Veo 3.1 generate](https://docs.kie.ai/veo3-api/generate-veo-3-video), [Seedance 2.0](https://docs.kie.ai/market/bytedance/seedance-2), [Kling 3.0](https://docs.kie.ai/market/kling/kling-3-0)
+- [Google Cloud — Ultimate prompting guide for Veo 3.1](https://cloud.google.com/blog/products/ai-machine-learning/ultimate-prompting-guide-for-veo-3-1)
+- [Google AI for Developers — Generate videos with Veo 3.1 (Gemini API)](https://ai.google.dev/gemini-api/docs/veo)
+- [Kling.ai — Kling Video 3.0 Omni Native Lip Sync & Audio](https://kling.ai/blog/kling-video-3-omni-native-lip-sync-audio-guide) (446 to automated fetch; corroborated indirectly)
+
+Vendor guides (fal.ai):
+- [Seedance 2.0 prompting guide](https://fal.ai/learn/tools/seedance-2-0-prompting-guide), [Kling 3.0 prompting guide](https://blog.fal.ai/kling-3-0-prompting-guide/)
+
+Community (labeled inline):
+- [GlobalGPT Veo 3.1 dialogue/lip-sync](https://www.glbgpt.com/hub/how-to-make-characters-speak-in-veo-3-1-the-ultimate-guide-to-dialogue-audio-lip-sync/) · [VidAU Veo no-subtitles](https://www.vidau.ai/veo-3-prompt-no-subtitles/) · [UGC-Copilot Seedance native audio](https://ugccopilot.ai/blog/seedance-2-native-audio-generation-guide/) · [Cutout.pro Seedance audio](https://www.cutout.pro/learn/blog-seedance-2-0-audio-guide/) · [Imagine.art Kling 3.0](https://www.imagine.art/blogs/kling-3-0-prompt-guide)
+
+Local prior art:
+- `workspace/references/kie-video-models.md` (#529 catalog) · `workspace/output/bakeoff-533/index.html` + `manifest.json` (#533 native-audio bake-off) · `scout/src/workflow/video/clips.ts`, `models.ts`, `kie-video.ts`, `storyboard.ts` · `convex/lib/workflow/storyboardContract.ts`

package/assets/references/own-brand-enrichment-path.md

@@ -0,0 +1,160 @@
+# Own-Brand Winners — enrichment path design (wayfinder #565)
+
+Designed 2026-07-14 from the [MCP probe findings](meta-ads-mcp-probe.md) (#563)
+plus a code audit of the live swipe rail (`scout/src/scrapecreators.ts`,
+`scout/src/trigger/swipe-mine.ts`, `swipe-transcribe.ts`, `image-classify.ts`,
+`convex/swipeAds.ts`, `convex/imageClassification.ts`). Answers: what is the
+exact path from a designated winner (ad-account identity) to a complete stored
+package? Feeds the bridge contract (#566) and the build specs (#567).
+
+## TL;DR decisions
+
+1. **Match server-side on ad copy, not agent-side on the MCP title fingerprint.**
+   The bridge payload carries the account-side ground truth (body, title,
+   created_time, format, page id); a new import task scrapes the brand's own
+   page once via the existing `fetchCompanyAds` and matches winners to library
+   ads by **normalized body+title equality** (tiebreak: earliest `start_date`).
+   Full ScrapeCreators snapshots include body text — a far stronger key than
+   the library-search `title + time` fingerprint the probe had to settle for,
+   and it drops `ads_library_search` from the skill entirely.
+2. **One new Trigger task (`own-brand-import`), everything downstream as-is.**
+   The task reuses the scrapecreators.ts helpers + the `/api/v2/swipes/batch`
+   upsert, stores **only matched winners**, then fires the existing
+   `swipe-transcribe` and `image-classify` sweeps, which pick own-brand rows up
+   with zero changes (both sweep global "missing transcript" / "unclassified"
+   states).
+3. **Gap-filler = agent-pushed assets for unmatched winners** (ad stopped
+   running): text is always complete from MCP; images are downloaded by the
+   agent immediately (signed CDN URLs expire) and uploaded as bytes via the
+   existing Convex `generateUploadUrl` pattern; **video files have no MCP
+   source — the skill asks the user for their own creative file** (it's their
+   ad), else the package is stored partial.
+4. **Mirror winner media into Convex storage at import.** fbcdn URLs expire;
+   competitor rows survive because the daily re-scrape refreshes them, but
+   winners are long-lived fuel imported once. Store the storage **serve URL in
+   the existing `imageUrl`/`videoUrl` fields** so every downstream consumer
+   (pickers, classify, transcribe, gallery) works unchanged.
+5. **Own-brand `brands` rows must be flagged out of the daily swipe-mine cron**
+   (`isOwnBrand: true`, mine filters it): otherwise the nightly sweep scrapes
+   the user's whole page and stores every active ad — violating winners-only.
+6. **Completeness is an explicit stored field**, not derived: `complete` |
+   `partial` (+ what's missing), surfaced amber in the UI tab (the #478
+   partial-delivery pattern).
+
+## Stage 0 — what the agent holds per winner (input to the bridge)
+
+Per the probe, after the winner interview designates ads, the agent can gather
+via MCP (`ads_get_ad_entities` + `ads_get_creatives` + `ads_get_ad_images` /
+`ads_get_ad_videos`, all with explicit `fields`):
+
+| Field | Source | Notes |
+|---|---|---|
+| account ad id, name, campaign/adset ids | entities | hierarchy + provenance |
+| `created_time` | entities | matching tiebreak + daysRunning fallback |
+| body (primary text), title (headline), CTA type | creative | ground truth for matching |
+| `effective_object_story_id` (`<pageId>_<postId>`) | creative | **page id prefix** = scrape target |
+| image hash → full-res signed URL | ad_images | **download immediately**, expires |
+| video id, length, poster URL | ad_videos | no source URL — cannot download |
+| metrics as display strings + result-type labels | entities | verdict snapshot material |
+
+The bridge payload (#566) should carry all of the above per winner, plus the
+page id once per import.
+
+## Stage 1 — matching: winner → `adArchiveId`
+
+Runs inside `own-brand-import` (server-side, ScrapeCreators BYOK key snapshot
+exactly like `swipe-mine`'s manual-run pattern):
+
+1. `fetchCompanyAds(pageId)` — one paginated scrape of the user's own page.
+   Returns full snapshots: `body.text`, `title`, `start_date`, media URLs,
+   `collation_count`.
+2. For each winner: **normalize** (trim, collapse whitespace, strip zero-width
+   chars, normalize curly quotes) and match on **body equality**; require
+   title equality too when both sides have a title.
+3. Ambiguity: multiple library ads with identical copy are creative variants /
+   republishes — any is acceptable (same creative); pick the **earliest
+   `start_date`** (longest `daysRunning`, best longevity signal for pickers).
+4. Fallback when the account creative has no body (some `SHARE`-type creatives
+   keep copy on the story post): match on unique title + `created_time`
+   proximity (±72h). Non-unique → treat as unmatched (gap-filler), never guess.
+5. Matched → optionally `fetchAdLibraryAdById(archiveId, get_transcript=true)`
+   for the inline transcript (the idea-ad-library / workflow-executor pattern);
+   store it at insert so most video winners never wait for the transcribe cron.
+
+**Failure modes:** page scrape empty (wrong page id, zero active ads) → all
+winners unmatched → gap-filler; the Ad Library only lists **running** ads for
+non-political advertisers, so any stopped winner is *expected* to be unmatched
+— that's the designed-for case, not an error. One spec-time item:
+`fetchCompanyAds` hardcodes `country: "US"` — the import path must make this
+configurable (or "ALL" if the endpoint accepts it) or non-US advertisers will
+false-unmatch.
+
+## Stage 2 — gap-filler protocol (unmatched winners)
+
+What MCP can and cannot supply fills the row directly:
+
+- **Copy**: body/title/CTA come from the creative — always complete. No
+  library `linkUrl`/`linkDescription`; acceptable loss (fields stay empty).
+- **Image**: the agent downloads the signed CDN URL **at interview time** (not
+  at push time — it expires) and the CLI uploads bytes: request an upload URL
+  (the `creativeSuite.generateUploadUrl` service pattern), PUT the file, record
+  the storage id. Import stores the serve URL in `imageUrl`.
+- **Video**: no MCP file. Ladder: (a) the skill asks the user to point at
+  their own creative file — they made the ad, they usually have it — CLI
+  uploads it; (b) no file → store partial: copy + poster image (poster URL
+  *is* downloadable now) and no transcript. Once a video lands in storage, its
+  serve URL in `videoUrl` makes the existing `pendingTranscripts` sweep
+  transcribe it automatically (note: `transcribeVideo` rejects >25MB —
+  acceptable v1 cap, flag oversize uploads as partial-transcript).
+- **Identity**: gap-filled rows get a synthetic archive id `own:<accountAdId>`
+  — stable, unique, satisfies the `by_adArchiveId` dedup index, can't collide
+  with numeric library ids. `isActive: false`, `startDate` from
+  `created_time`.
+
+## Stage 3 — reuse audit
+
+| Piece | Verdict |
+|---|---|
+| `scrapecreators.ts` helpers (fetch, extract*, classifyFormat, transcribe) | **as-is** — the import task composes them |
+| `/api/v2/swipes/batch` → `swipeAds.upsertBatch` | **as-is** — winners-only array in, dedup by archive id |
+| `swipe-transcribe` (`pendingTranscripts` sweep) | **as-is** — global format=video-missing-transcript scan includes own-brand rows; also fire it at import end |
+| `image-classify` (`getUnclassifiedSwipeAds`) | **as-is** — sweeps `classificationStatus === undefined`; own-brand rows enter automatically |
+| Consumption (`swipeAdToText`, pickers, `listForWorkspacePublic`) | **as-is** — own-brand rows are swipeAds under a workspace brand; they flow into every picker. Spec check (per map): run-dialog top-N ranks by `daysRunning` — matched winners inherit real longevity, gap-filled ones get `created_time`-derived values, and the winner fields below let pickers boost designated winners explicitly |
+| `swipe-mine` task | **not reused** (fetch-everything shape violates winners-only); its building blocks are |
+| Daily `swipe-mine` cron | **needs a filter**: skip `isOwnBrand` brands (decision 5) |
+| New code | one Trigger task `own-brand-import` + one HTTP route to start it (BYOK key snapshot like `swipe.startMineRun`) + the CLI ingestion command (#566's contract) |
+
+## Stage 4 — completeness contract
+
+A package is **usable generative fuel** when:
+
+- **every winner**: verdict snapshot (composed sentence + metric display
+  strings) — non-negotiable, it's the point of the feature — plus body or
+  title, and provenance (account ad id, campaign/adset ids).
+- **image winner**: + full-res image (storage-mirrored). Missing image →
+  `partial` (copy bots still work; ref-match image engines can't use it).
+- **video winner**: + transcript (from library inline, sweep, or uploaded
+  file). Video file itself is desired (gallery, future variations) but
+  transcript is the fuel; no transcript AND no video → `partial`.
+
+Store it explicitly: `enrichmentStatus: "complete" | "partial"` +
+`enrichmentMissing: string[]` (e.g. `["video-file", "transcript"]`), set by the
+import task, re-evaluated when a sweep fills a gap. UI shows amber on partial
+rows with the missing list (the #478 pattern).
+
+New optional `swipeAds` columns this implies for #567 (all additive):
+winner verdict text + metrics snapshot, `designatedAt`, source account
+ad/campaign/adset ids, `enrichmentSource: "library-match" | "agent-push"`,
+`enrichmentStatus` / `enrichmentMissing`, `imageStorageId` / `videoStorageId`
+(lifecycle), plus `brands.isOwnBrand`.
+
+## Open items handed to #566 / #567
+
+- Bridge contract (#566): exact payload shape per winner (Stage 0 table), how
+  the CLI transports image/video bytes (upload-URL handshake vs multipart),
+  idempotency on re-push (upsert by account ad id → synthetic/matched archive
+  id), and where the "ask the user for the video file" step lives in the skill.
+- Spec (#567): country parameter on the import scrape; winner-boost rule in
+  top-selection heuristics; amber partial UI in the Swipe Mining tab; whether
+  matched winners' media also gets storage-mirrored at import (recommended:
+  yes, both paths, decision 4).

package/dist/commands/brand.js

@@ -5,6 +5,7 @@ import { sniffImageType, BRAND_IMAGE_MAX_BYTES } from "../lib/image-sniff.js";
 import { getActiveBrand, setActiveBrand, clearActiveBrand, findWorkspaceRoot, } from "../lib/state.js";
 import { detectLayout, ensureBrandDir, resolveActiveBrand, brandStateDir, brandDirFor, } from "../lib/layout.js";
 import { promptYesNo } from "../lib/prompts.js";
+import { pkgRef } from "../lib/channel.js";
 const AUTO_END_MARKER = "<!-- exodus:auto-section-end — manual brand notes below survive `brand use` refreshes -->";
 export const helpText = `
 exodus brand — list, switch, and inspect brands available to your CLI
@@ -180,7 +181,7 @@ async function runCreate(name) {
         console.log(`✓ Wrote ${refresh.pathRel}.`);
     }
     console.log(`\nNext: set up the brand's primer to unlock the pipelines —\n` +
-        `  say "exodus, set up my brand primer" (or run \`npx @aicopycoders/exodus primer\`).`);
+        `  say "exodus, set up my brand primer" (or run \`npx ${pkgRef()} primer\`).`);
 }
 async function runDelete(slug, flags) {
     if (!slug)