@aicopycoders/exodus 2026.7.200-beta.9 → 2026.8.1100

package/README.md

@@ -0,0 +1,51 @@
+# @aicopycoders/exodus
+
+The Exodus CLI + Claude Code skills for the Copycoders ad pipeline. It drives the
+Genesis creative bots, workflows, banks, and image/meme pipelines against your
+brand — from your terminal and from Claude Code.
+
+You don't install it globally. Run it with `npx` from your workspace folder.
+
+## Quickstart
+
+```bash
+# 1. Scaffold (or refresh) the workspace in the current folder
+npx -y @aicopycoders/exodus@beta init
+```
+
+`init` creates the workspace (the `.claude/` skills, docs, and your brand
+subfolder) and prints the next steps. The `@beta` tag is the dev/preview channel;
+drop it (`@aicopycoders/exodus`) for the stable release channel.
+
+### Connect your account
+
+1. Open the Exodus dashboard → **Settings → Claude Code**.
+2. Copy the `.env` snippet it shows you (your `EXODUS_API_KEY` + dashboard URL)
+   and paste it into a `.env` file in your workspace folder.
+3. Pull your provider keys down so the local tools have them:
+
+   ```bash
+   npx -y @aicopycoders/exodus@beta keys pull
+   ```
+
+   This writes your dashboard provider + image keys into `.env` (it only upserts
+   those keys and preserves the rest of the file). Values are never printed.
+
+### Check everything is wired up
+
+```bash
+npx -y @aicopycoders/exodus@beta doctor
+```
+
+`doctor` diagnoses local and dashboard-side issues in one shot — keys, workspace
+health, CLI currency — and tells you exactly what to fix.
+
+## Where to go next
+
+- `npx -y @aicopycoders/exodus@beta --help` — the full command surface.
+- `npx -y @aicopycoders/exodus@beta workflow --help` — run, build, and automate
+  saved multi-node workflows; resolve gate/repair parks from the inbox; read
+  banks and promote winners.
+
+Inside Claude Code, just say **"exodus"** plus what you want
+("exodus, write me some ads") and the skills route the rest.

package/assets/docs/CLAUDE.md

@@ -38,6 +38,7 @@ Any user can create and own unlimited brands — `npx @aicopycoders/exodus brand
 - **Create a new brand:** `npx @aicopycoders/exodus brand create "<name>"` — creates it server-side, switches you in, and sets up its local subfolder
 - **Switch brand:** `npx @aicopycoders/exodus brand use <slug>` — or just work from inside that brand's subfolder
 - **New brand created on the dashboard?** `npx @aicopycoders/exodus@latest init` creates its subfolder and pulls its profile
+- **Update the CLI + skills:** `npx @aicopycoders/exodus@latest update` — the only command that refreshes `.claude/skills/` and the workspace docs (`doctor` reports health but never rewrites them)
 - **Brand voice / ICP / offer:** the active brand's `state/brand-profile.md` (inside its subfolder; at this root on older single-brand installs) — read this at session start and after any switch. If it doesn't match the active brand, the exodus-strategist skill will prompt to refresh.
 
 Don't carry voice or proven angles across brands — each brand is its own creative universe.
@@ -58,6 +59,7 @@ These are the **Exodus** pipelines — the automatic system that drives the Gene
 | **Creative** | `exodus-creative` | A specific creative-suite engine (native / copy-derived renders from copy, or ref-match to a reference image) when you've already picked one. Otherwise start at **Image**. |
 | **Template** | `exodus-template` | Finished ad copy → many static ads across 50 structured formats (testimonial, hero, UGC…). Otherwise start at **Image**. |
 | **Meme** | `exodus-meme` | Meme ads — recommends formats for a brief, then one batched run renders AI-image and classic Imgflip-template memes server-side. |
+| **Workflow** | `exodus-workflow` | Run and build saved multi-node workflow automations from the CLI, resolve checkpoint/repair parks from the inbox, continue bot sessions, fire triggers, and read banks or promote winners. |
 | **Browse** | `exodus-browse` | View history and retrieve past outputs |
 | **Drive** | `exodus-drive` | Read/write Google Docs, Sheets, and Drive files via `npx @aicopycoders/exodus drive` (uses the dashboard's Google OAuth — no local CLI) |
 | **Winners** | `exodus-winners` | Mine your own Meta ad account for winning ads (via the Meta Ads MCP) and import them into Exodus as generative fuel — interview, visual confirmation, `npx @aicopycoders/exodus winners import` |

package/assets/docs/PIPELINES.md

@@ -14,6 +14,7 @@ In Claude Code you don't click buttons. You say **"exodus"** plus what you want
 | exodus-creative | Creative-Suite Engines (native / copy-derived / ref-match) — when you've already picked an engine |
 | exodus-template | Ad-Type Format Variations across 50 structured formats |
 | exodus-meme | Meme Ad Generator — recommend formats, one batched server-side run |
+| exodus-workflow | Run/build saved multi-node workflows, resolve inbox gate/repair parks, continue sessions, fire triggers, read banks + promote winners |
 | exodus-browse | View History and Surface the Right Run |
 | exodus-drive | Google Drive, Docs, Sheets via the Dashboard's OAuth |
 | exodus-winners | Mine your own Meta ad account for winners (needs the Meta Ads MCP) and import them into Exodus |
@@ -171,6 +172,31 @@ Returns: runId + dashboard URL /creative-suite/runs/<runId> (results land in the
 
 ---
 
+## exodus-workflow
+
+**What it does:** Run, chain, build, and edit saved multi-node Exodus Workflows from the CLI — the automations that wire Genesis bots, primers, briefs, and image nodes together on the dashboard canvas. Also resolves runs that park at a gate or repair step (from the inbox), continues bot chat sessions, enables/fires triggers, reads copy banks, and promotes a winner (which fires the Winner Flywheel).
+
+```operator-guide
+Say something like:
+  "exodus, run my launch workflow"
+  "exodus, what does this workflow need"
+  "exodus, check my workflow inbox"
+  "exodus, review that gate" / "exodus, approve the run"
+  "exodus, continue that session"
+  "exodus, promote this winner"
+
+Representative commands:
+  exodus workflow list
+  exodus workflow run <wf> --wait
+  exodus workflow inbox
+  exodus workflow gate <runId> pick 3,7 | edit 4 | push "punchier" | approve | reject
+  exodus session list | show | chat
+  exodus bank list | show <key> | promote <key>
+Every workflow/session/bank verb takes --json — that output is the machine API.
+```
+
+---
+
 ## exodus-browse
 
 **What it does:** View past pipeline runs and pull outputs from previous sessions.

package/assets/skills/exodus/SKILL.md

@@ -18,13 +18,16 @@ This skill ROUTES. Read what the user wants, name the destination skill, and han
 | Static image ads ("make images", "statics", "render this ad") | `exodus-image` (the image front door — it menus engines and confirms before firing) |
 | A specific image engine they already chose | `exodus-creative` (native / copy-derived / ref-match) or `exodus-template` (33 ad-type formats) |
 | Meme ads ("exodus, meme this offer", "make me meme ads") | `exodus-meme` |
-| Run / chain / build / edit a saved workflow ("run my workflow", "what does this workflow need", "build a workflow that…", "list my workflows") | `exodus-workflow` |
+| Run / chain / build / edit a saved workflow, enable/fire its triggers, or roll back a version ("run my workflow", "what does this workflow need", "build a workflow that…", "list my workflows", "enable/fire the trigger", "roll back my workflow", "workflow versions") | `exodus-workflow` |
+| Check the workflow inbox or review/resolve a parked run — checkpoint or repair ("check my workflow inbox", "approve that checkpoint", "approve the run", "repair that run") | `exodus-workflow` |
+| Continue a bot chat session ("continue that session", "chat with the bot session", "list my sessions") | `exodus-workflow` |
+| Read copy banks or promote a winner ("show my hook bank", "list my banks", "promote this winner") | `exodus-workflow` |
 | Onboard a new brand / build the primer | `exodus-primer` (with winning ads) or `exodus-foundation` (no ads yet) |
 | List/switch/troubleshoot brands | `exodus-brand` |
 | See past runs / find an output | `exodus-browse` |
 | Open or create Google Docs/Sheets | `exodus-drive` |
 | Import their OWN winning ads from their Meta ad account ("import my winners", "mine my ad account for winners", "exodus winners") | `exodus-winners` |
-| Update the CLI + skills | run `npx @aicopycoders/exodus@latest init` |
+| Update the CLI + skills ("update exodus", "run an exodus update") | run `npx @aicopycoders/exodus@latest update` — the ONLY command that refreshes skills; `doctor` checks health but never rewrites them |
 
 If a custom pipeline skill is installed in this folder (any additional `exodus-*` directory under `.claude/skills/`), it routes the same way — match the user's words to that skill's description.
 

package/assets/skills/exodus-meme/SKILL.md

@@ -4,11 +4,11 @@ description: Generate meme-style ad creative for the active brand — recommends
 ---
 
 ```operator-guide
-Subcommands (three; the batch renders server-side via Trigger.dev):
+Subcommands (three; the batch renders server-side):
   exodus meme recommend --brief "<text>" [--avatar "<text>"]
   exodus meme run --brief "<text>" --formats '<json>' [--formats-file <path>] [--avatar "<text>"] [--name "<label>"]
-  exodus meme regenerate --brief "<text>" --layer 1 --template-id <id> --template-name "<name>" --boxes <N> [--id <runId>]
-  exodus meme regenerate --brief "<text>" --layer 2|3 --format <formatId> [--hint "<text>"] [--id <runId>]
+  exodus meme regenerate --brief "<text>" --layer 1 --template-id <id> --template-name "<name>" --boxes <N>
+  exodus meme regenerate --brief "<text>" --layer 2|3 --format <formatId> [--hint "<text>"]
 
 Flow:
   1. recommend → { recommendations: [...] } — 15 picks (5 per layer), each with
@@ -17,14 +17,17 @@ Flow:
   2. run → pass the picked recommendation objects straight into --formats (JSON
      array, 1–50; the CLI normalizes them). Returns { runId }. One enqueue —
      closing the session does NOT kill the batch.
-  3. Poll: exodus status --id <runId> --type creative
-     Terminal statuses: complete | partial-error | error (also failed/cancelled).
-  4. regenerate → re-render one miss, synchronously (returns image_url).
+  3. Poll: exodus workflow status --id <runId>
+     Memes render through the Image Rig, so a meme run IS a workflow run — the
+     workflow verb is the one that can read it, NOT `status --type creative`.
+  4. regenerate → re-render one miss, synchronously (returns image_url). Do not
+     pass its optional --id the run id from step 2 — that flag takes a
+     creative-suite run id, a different id space.
 
 Keys (strict BYOK, refused server-side before anything starts):
   layer 1 needs the member's Imgflip login · layers 2/3 need their Kie.ai key ·
   captions always need their LLM key. `npx @aicopycoders/exodus doctor` checks all three.
-Returns: runId + dashboard URL /creative-suite/runs/<runId> (the visual review surface).
+Returns: runId + dashboard URL /runs/<runId> (the visual review surface).
 ```
 
 # Meme — Meme Ad Generator (Max's pipeline)
@@ -111,38 +114,43 @@ session and the run finishes anyway.
 ### 3. Poll
 
 ```bash
-npx @aicopycoders/exodus status --id <runId> --type creative
+npx @aicopycoders/exodus workflow status --id <runId>
 ```
 
+Memes render through the Image Rig, so a meme run **is** a workflow run — the
+workflow status verb reads it. `status --type creative` will not find it.
+
 Poll roughly every 45 seconds while the user is waiting (or just hand them the
 dashboard URL if they'd rather watch it live). Treat these statuses as
-terminal: `complete`, `partial-error`, `error` — plus `failed`/`cancelled`. The
-status output includes `completedImages / totalImages` and, on failures, an
-`errorMessage` naming what missed.
+terminal: `succeeded`, `succeeded-with-warnings`, `failed`, `cancelled`. A
+warnings verdict is the meme batch's old `partial-error` — some memes landed,
+some missed, and the node detail names what missed.
 
 ### 4. Regenerate the misses
 
-`partial-error` means some renders failed and the rest landed. Name the misses
-to the user and offer to re-render them — the format fields come from the
-recommend output you're still holding:
+"Succeeded with warnings" means some renders failed and the rest landed. Name
+the misses to the user and offer to re-render them — the format fields come from
+the recommend output you're still holding:
 
 ```bash
 # Classic (layer 1) miss:
 npx @aicopycoders/exodus meme regenerate --brief "<brief>" --layer 1 \
-  --template-id <imgflip_template_id> --template-name "<name>" --boxes <imgflip_box_count> --id <runId>
+  --template-id <imgflip_template_id> --template-name "<name>" --boxes <imgflip_box_count>
 
 # AI (layer 2/3) miss — --hint steers the re-roll:
 npx @aicopycoders/exodus meme regenerate --brief "<brief>" --layer 2 --format <format_id> \
-  --hint "make the punchline land the product" --id <runId>
+  --hint "make the punchline land the product"
 ```
 
-Regenerate is synchronous (caption + render server-side) and
-returns the new `image_url` directly. Passing `--id <runId>` attaches the fresh
-meme to the run so it shows up in the same library entry.
+Regenerate is synchronous (caption + render server-side) and returns the new
+`image_url` directly. **Do not pass the run id from step 2 to `--id`** — that
+flag attaches the fresh meme to a *creative-suite* run, and since memes moved
+onto the Image Rig the id `run` prints is a workflow run id, a different id
+space. Omit `--id` and hand the user the returned URL.
 
 ### 5. Report
 
-Surface the dashboard URL (`/creative-suite/runs/<runId>`) + a 2-line
+Surface the dashboard URL (`/runs/<runId>`) + a 2-line
 strategist take ("the classics carry the relatability, the Group Chat one is
 the sleeper — review them in the library"). The dashboard is where the user
 actually evaluates memes visually; your report gets them there with a point of
@@ -157,9 +165,9 @@ internals into chat.
   `npx @aicopycoders/exodus doctor` to confirm, then send the user to **Settings → Keys** on
   the dashboard. A batch with no layer-1 picks doesn't need Imgflip at all — if
   the user lacks an Imgflip login, an AI-only batch is a legitimate fallback.
-- **`partial-error`** — not a failed run; some memes landed. Report the
-  successes, name the misses from `errorMessage`, regenerate per step 4.
-- **`error` / `failed`** — the batch died; the status `errorMessage` says why.
+- **`succeeded-with-warnings`** — not a failed run; some memes landed. Report the
+  successes, name the misses from the node detail, regenerate per step 4.
+- **`failed` / `cancelled`** — the batch died; the status error says why.
   Fix the cause (usually a key issue mid-run) before re-firing, don't just retry.
 - **No progress for 15+ minutes** — presume the run dead and say so rather than
   polling forever; the dashboard run page shows the same stall.
@@ -176,8 +184,16 @@ internals into chat.
 
 ## Admin
 
-- Backend: `/api/meme/{recommend,run,regenerate}` (Bearer-auth). `run` enqueues
-  the `meme-batch` Trigger.dev task; meme runs ride `creativeSuiteRuns` with
-  engine `meme`, which is why `exodus status --type creative` and
-  `exodus browse --agent meme` cover them.
-- Finished runs appear in the creative-suite library alongside other engines.
+- Backend: `/api/meme/{recommend,run,regenerate}` (Bearer-auth). Since #1142
+  `run` is an ADAPTER onto the Image Rig: it compiles the picked formats into a
+  firing plan and starts a hidden, per-workspace single-rig workflow, so the id
+  it returns names a `workflowRuns` row and every meme now carries the same
+  per-image provenance as any other rig render. That is why the poll verb is
+  `exodus workflow status`, not `exodus status --type creative` — the creative
+  status route reads `creativeSuiteRuns` for a Bearer caller.
+- The rig's child image runs are still `creativeSuiteRuns` with engine `meme`,
+  so finished memes appear in the creative-suite library alongside other engines
+  and `exodus browse --agent meme` still covers them.
+- `run` accepts only the two models the rig renders (`gpt-image-2`,
+  `nano-banana-pro`, or their Kie slugs); anything else is a 400 listing the
+  accepted values. It used to accept any value and silently ignore it.

package/assets/skills/exodus-winners/SKILL.md

@@ -53,15 +53,17 @@ Call `ads_get_ad_accounts`. It returns **every** account the login can touch —
 
 You are not collecting preferences here so much as confirming inferences. Four things get settled, and only one of them ever shows the user a choice.
 
-**a) Objective → metric is invisible.** Ads group by their campaign **objective**; each group's success metric is the account's own self-labeled result type — Meta hands it to you already labeled (`results: {"value": "98 (Website appointments scheduled)"}`, `cost_per_result: {"value": "$91.64 USD (Website appointments scheduled)"}` — the string lives under `.value`). **Never ask the user to pick a metric.** The account already declared it. Offer one free-text escape hatch only — *"If your definition of a winner is different from 'the ads that drove the most results,' tell me in your own words."* — and record whatever they say **verbatim** as `customDefinition`, applied agent-side. Do not turn their words into a number.
+**a) Objective → metric is invisible.** Ads group by their **self-labeled result type** (within objective — §2c); each group's success metric is the account's own label — Meta hands it to you already labeled (`results: {"value": "98 (Website appointments scheduled)"}`, `cost_per_result: {"value": "$91.64 USD (Website appointments scheduled)"}` — the string lives under `.value`). **Never ask the user to pick a metric.** The account already declared it. Offer one free-text escape hatch only — *"If your definition of a winner is different from 'the ads that drove the most results,' tell me in your own words."* — and record whatever they say **verbatim** as `customDefinition`, applied agent-side. Do not turn their words into a number.
 
 **b) Funnel mapping is infer-then-confirm.** Propose, per campaign, an **awareness level** from the Schwartz five — `unaware` / `problem-aware` / `solution-aware` / `product-aware` / `most-aware` — inferred from the campaign objective plus the campaign/adset **names** (naming is read-only creative context; see §6). Present the whole proposed map **once** for a single confirm/adjust pass, then save it. On a re-mine, only **new** campaigns get proposed; already-mapped ones stay put.
 
 **c) The winner rule is fixed — volume over efficiency, all-time, no caps.** State it, don't negotiate it:
 
-> Within each objective group, over the account's full lifetime (`date_preset: "maximum"`), the winners are the **smallest set of ads that together carry ~80% of that group's lifetime results**, where each qualifying ad has **at least 10 results** (a materiality floor — one lucky conversion is not a winner). No top-N cap.
+> Within each result-type group, over the account's full lifetime (`date_preset: "maximum"`), the winners are the **smallest set of creatives that together carry ~80% of that group's lifetime results**, where each qualifying creative has **at least 10 results** (a materiality floor — one lucky conversion is not a winner). No top-N cap.
 
-- **Union with per-format cuts.** Run the same 80%/≥10 rule three ways: **overall**, **within video only**, and **within image only**, then union the results. This guarantees both lanes populate even when one format dominates spend. Each winner records which cut(s) it cleared as `selectionBasis`: any of `overall` / `top-video` / `top-image`.
+- **Groups key on the self-labeled result type, not on objective alone.** Real accounts mix objectives, and one objective can hide two currencies — OUTCOME_LEADS covers both a booked-call funnel (`"Website appointments scheduled"`) and an opt-in funnel (`"Website leads"`), and those must never share one 80% line (the cheap high-volume metric drowns the scarce valuable one). Partition by objective first, then by the parenthetical label on `results.value`; each distinct label is its own group with its own 80% line and its own floor.
+- **The unit you rank is aggregated content, never the raw ad instance.** Advertisers duplicate: the same post runs in many ad sets and campaigns (same post id = the exact same content with its results split across instances), and the same video or image runs under several copy versions. Rank raw instances and a true winner shatters into sub-threshold fragments — or surfaces as several "different" winners that are one ad. Aggregate BEFORE applying the rule, and apply the **floor to the aggregate, never the instance** — four 6-result duplicates are one 24-result winner (§3 has the mechanics): collapse instances sharing an `effective_object_story_id` in every cut, and collapse further by creative asset (same video / same image across copy variants) within the format cuts.
+- **Union with per-format cuts.** Run the same 80%/≥10 rule three ways: **overall** (post-level aggregates), **within video only**, and **within image only** (creative-level aggregates), then union the results. This guarantees both lanes populate even when one format dominates spend. The union dedupes on the aggregate's `accountAdId` (§3); a winner clearing multiple cuts is ONE row whose `selectionBasis` lists every cut it cleared (`overall` / `top-video` / `top-image`), and when a format cut is among them the stored verdict carries the **creative-level** aggregate's numbers and instance count (the broadest collapse it cleared).
 - **Flat curve honesty.** If contribution is flat — no elbow, results spread evenly across hundreds of ads — say so plainly and show the top contributors instead of pretending there's a clean winner set. Never fabricate outliers to hit the 80% line.
 
 **d) There are no losers at v1.** You designate winners only. Don't ask about, or invent, a "worst ads" pass.
@@ -72,8 +74,11 @@ The defaults behind this rule (`window: "maximum"`, `resultsFloor: 10`, `contrib
 
 Mine on `ads_get_ad_entities`. These are hard-won live-probe facts; encode them into how you call, not into a doc you can look up later:
 
-- **Sort server-side, threshold agent-side.** Metric *filtering* on `ads_get_ad_entities` consistently **500s** — never filter by a metric. Metric *sorting* works. Sort by **results descending** and pull **the complete group — every page** — over `date_preset: "maximum"`; you need the group's full results total (the 80% denominator), so a sorted prefix is never enough. Then apply the 80%/≥10 rule yourself in memory.
-- **Retry once on a 500.** Transient 500s happen even on valid calls; an identical retry usually succeeds. Retry a failed call once before treating it as real.
+- **Never mine account-wide — scope every metrics pull to one campaign.** Account-wide ad-level pulls that include `results` **500 consistently** on real accounts (mixed objectives, thousands of near-duplicate test ads) — no limit, no sort tweak, and no retry unsticks them, and `results` 500s at campaign level too. Enumerate campaigns first (attributes, `objective`, and spend all work fine at campaign level), then pull ads **campaign-by-campaign** with `results` over `date_preset: "maximum"` and aggregate agent-side into result-type groups (ads carry `campaign_id`; join `objective` from the campaign pull).
+- **Sort server-side, tally compactly — never hold full blobs, and never floor raw rows.** Metric *filtering* on `ads_get_ad_entities` consistently **500s** — never filter by a metric. Metric *sorting* works. Per campaign: sort by **results descending**, page through, and retain one **compact tuple per result-bearing ad** — ad id, ad name, campaign id, creative id, created time, results, spend — discarding zero-result rows (they can't move any sum) and every other field. **The 10-result floor does NOT apply while paging**: sub-floor instances of one post can sum to a winner (§2c), so no row is ever dropped for being small. A creative-testing account runs 100+ near-duplicate ads per campaign; compact tuples keep the whole account to a few hundred short lines, where retaining or printing whole per-campaign blobs burns the session's context before the winner rule ever runs.
+- **Aggregate across the whole result-type group, then floor, then rank.** A scoring group spans campaigns — finish paging **every** campaign that feeds a group before ranking it (the per-campaign loop is just how you gather; the group is the unit you rank, once). Then batch re-fetch creatives by `creative_ids` for the retained tuples — that yields each ad's `effective_object_story_id` (post identity), `image_hash` / video identity, and **format** (which the format-cut denominators need for every result-bearing row, not just candidates). Merge instances sharing a post id (every cut), then copy variants sharing the same creative asset (format cuts), summing results and spend as you merge. Only **now** apply the ≥10 floor — to aggregate totals, never to instances: four 6-result duplicates are one 24-result winner. Denominators: the overall 80% line divides by the group's total; each format cut divides by that format's own subtotal (`resultsShare` still reports share of the full group total).
+- **The aggregate's identity must survive a re-mine.** Its `accountAdId` is its **earliest-created instance** — stable across re-mines (the top performer can change month to month; the oldest instance can't, and the server dedupes rows on this id — an unstable pick would duplicate the winner on the next import). The **highest-results instance** supplies the copy and `sourceNames`. When an aggregate spans more than one instance the verdict sentence says so plainly ("… across 4 ad instances in 3 campaigns"); summed counts are numbers **you** derived — own that in the sentence, and leave single-instance display strings verbatim.
+- **Retry once on a 500 — but only where 500s are transient.** An identical retry usually clears a one-off 500 on a scoped call. It never clears the two structural 500s above (metric filtering, account-wide results) — don't burn calls proving that again.
 - **Metric values are display strings, not numbers** — `"$8,980.38 USD"`, `"4.20%"`, `"Not available"` for zero-delivery ads. Keep them **verbatim** for the verdict snapshot. You still need to *rank* by them agent-side — parse a working copy for the math, but never mutate the string you store. (Account level also returns a numeric `amount_spent_cents` if you need a clean total.)
 - **`results` / `cost_per_result` self-label the outcome** (`.value` = `"98 (Website appointments scheduled)"`). That label is the metric — carry it into `resultType`.
 - **Hierarchy:** ads carry `campaign_id` + `adset_id`; `objective` lives on the **campaign**. There is no `campaign_name` at ad level — get campaign/adset names from a **campaign-level / adset-level call**, then join by id.
@@ -82,7 +87,9 @@ Mine on `ads_get_ad_entities`. These are hard-won live-probe facts; encode them
 - **`pageName` comes from the user, not from Meta.** The page tools can return `"(unknown)"` for the page name, and `ads_library_search` (which carries it) is off-limits — so once you have the page id, **confirm the page's name with the user in one line** ("This account posts as page 10715… — that's your <name> page, right?"). It names their own-brand entry in Exodus; don't guess it.
 - **Non-US accounts need `country` set.** The package's `source.country` defaults to `US`, and a wrong country makes the server-side Ad Library match silently miss. Infer it from the account (currency, business) and confirm alongside the page name when it isn't clearly US.
 - **Images: download the bytes at interview time, not push time.** `ads_get_ad_images` (by hash) returns a full-res signed CDN `url` that **expires** (watch the `oe=` param). Grab it while you're confirming the winner, save it locally, and reference the local file in the package.
-- **Video: there is no download URL. Never promise one.** `ads_get_ad_videos` gives `title`, `length`, and a poster `picture` only — no source/download URL. Grab the **poster** image for video winners; the actual mp4 comes from the user in the gap-filler (§8).
+- **Video: there is no download URL. Never promise one.** `ads_get_ad_videos` gives `title`, `length`, and a poster `picture` only — no source/download URL. The actual mp4 comes from the user in the gap-filler (§8).
+- **Every video winner MUST carry its poster.** Download the `picture` from `ads_get_ad_videos` at confirmation time and attach it as `assets.posterPath` — for an unmatched video winner it is the **only** thumbnail the Own Brand gallery will ever have; skip it and the winner renders as a blank placeholder. The CLI dry-run warns on poster-less video winners: treat that warning as a stop, not a formality.
+- **One page per package.** Winner↔library matching scrapes exactly `source.pageId` — a winner posted by any other page can never match and always gap-fills. If the account's winners span more than one Facebook page, split them into **one package per page** (each with that page's `pageId`/`pageName`); each import creates/updates its own own-brand entry and every winner keeps a real shot at matching.
 - **One `breakdowns` value per call.** Stay on `ads_get_ad_entities` for raw data — the `ads_insights_*` tools are opinionated narrative wrappers (trend/funnel prose), not the numbers you're ranking.
 - **Pass the user's real ask through `advertiser_request`** on each tool call — it's Meta's audit surface; give it the user's actual words.
 - **Never call `ads_library_search`.** Winner↔Ad-Library matching happens **server-side in Exodus** after import; the old title-fingerprint approach is dead. Your job ends at the account data.
@@ -91,9 +98,9 @@ Mine on `ads_get_ad_entities`. These are hard-won live-probe facts; encode them
 
 Before you confirm a single ad, lead with the **account summary** — the strategist wants the shape before the specimens:
 
-> "1,041 ads, 12,400 purchases all-time. 37 ads produced ~80% of them — and 29 of those 37 are video. That format skew is itself a finding."
+> "1,041 ad instances collapsing to 312 distinct creatives. In the Purchases group, 37 creatives produced ~80% of the 12,400 lifetime purchases — and 29 of those 37 are video. That format skew is itself a finding. (The account's second result type, Leads, gets its own line.)"
 
-The format skew, the count of winners, the share they carry — that framing *is* strategic value. Deliver it, then move to confirmation.
+The instance-to-creative collapse, the format skew, the count of winners, the share they carry — that framing *is* strategic value. Deliver it, then move to confirmation.
 
 ## 5. Visual confirmation — the human gate
 
@@ -111,7 +118,7 @@ Campaign / adset / ad names feed two things: your **awareness inference** (§2b)
 
 ## 7. The verdict snapshot & the winner-package JSON
 
-Every winner carries a **verdict snapshot** composed to the schema below. The metrics stay as **display strings verbatim** — never parsed into numbers in what you store — and you compose one plain-language sentence per winner. A **fresh snapshot is written on every re-mine; snapshots are never patched.**
+Every winner carries a **verdict snapshot** composed to the schema below. Single-instance metrics stay as **display strings verbatim** — never parsed into numbers in what you store. An aggregate winner (§2c) is the one exception: its `results`/`spend` are sums you derived across its instances, and its sentence names the instance count so nobody mistakes a derived total for a Meta string. You compose one plain-language sentence per winner. A **fresh snapshot is written on every re-mine; snapshots are never patched.**
 
 ```jsonc
 {
@@ -137,11 +144,11 @@ Every winner carries a **verdict snapshot** composed to the schema below. The me
       "ctaType": "SHOP_NOW",          // optional
       "effectiveObjectStoryId": "pageId_postId",  // optional
       "verdict": {
-        "sentence": "Winner by contribution: 2,214 purchases (6.2% of account) @ $18.20, all-time through Jul 2026",  // REQUIRED
-        "resultType": "Purchases",         // the self-label from results.value's parenthetical
-        "results": "2,214",                // Meta's display strings, never converted to numbers —
-        "resultsShare": "6.2%",            //   resultsShare is the one YOU derive (share of group total)
-        "spend": "$40,297",
+        "sentence": "Winner by contribution: 2,214 purchases (6.2% of group) @ $18.20 across 4 ad instances, all-time through Jul 2026",  // REQUIRED — name the instance count when the winner aggregates >1
+        "resultType": "Purchases",         // the self-label from results.value's parenthetical — also the scoring-group key (§2c)
+        "results": "2,214",                // single instance: Meta's display string verbatim; aggregate: your derived sum (the sentence names the instance count)
+        "resultsShare": "6.2%",            // YOU derive this (share of the result-type group's total)
+        "spend": "$40,297",                // same rule as results: verbatim for single instances, your derived sum for aggregates
         "costPerResult": "$18.20",
         "asOf": "2026-07-14",
         "objective": "OUTCOME_SALES",
@@ -150,16 +157,16 @@ Every winner carries a **verdict snapshot** composed to the schema below. The me
         "strategistNote": "…"         // optional, from §5
       },
       "assets": {
-        "imagePath": "./media/1202….jpg",          // optional — downloaded at interview time
-        "videoPath": "./media/1202….mp4",          // optional — user-supplied file (gap-filler)
-        "posterPath": "./media/1202…-poster.jpg"   // optional
+        "imagePath": "./media/1202….jpg",          // image winners: downloaded at interview time
+        "videoPath": "./media/1202….mp4",          // user-supplied file (gap-filler)
+        "posterPath": "./media/1202…-poster.jpg"   // video winners: REQUIRED in practice — the gallery's only thumbnail (§3)
       }
     }
   ]
 }
 ```
 
-All verdict metrics are display strings verbatim. `assets` is optional everywhere. A **malformed winner is rejected individually server-side** (with a reason in the ledger) — it never aborts the whole import.
+Verdict metrics are display strings verbatim (aggregates: derived sums, named as such — §7 intro). `assets` is optional in the schema, but a video winner without `posterPath` ships a blank gallery card (§3). A **malformed winner is rejected individually server-side** (with a reason in the ledger) — it never aborts the whole import.
 
 ## 8. Import — dry-run, push, then the video gap-filler
 
@@ -173,7 +180,7 @@ Run these in this exact order.
 npx @aicopycoders/exodus winners import state/own-brand-winners/import-<date>.json --dry-run --json
 ```
 
-Show the user the would-create vs would-update split. **If the dry-run reports the Scrape Creators key missing, surface it now** — a real import will fail without it; route them to Settings → Keys (scrapecreators.com). Fix any would-reject rows, then push for real:
+Show the user the would-create vs would-update split. **If the dry-run reports the Scrape Creators key missing, surface it now** — a real import will fail without it; route them to Settings → Keys (scrapecreators.com). **If it warns that a video winner has no posterPath, go back and grab the poster (§3) before pushing** — that warning is the difference between a gallery of ads and a wall of blank placeholders. Fix any would-reject rows, then push for real:
 
 ```bash
 npx @aicopycoders/exodus winners import state/own-brand-winners/import-<date>.json --json
@@ -211,7 +218,9 @@ Re-running re-asks **nothing already pinned** — only genuinely new campaigns g
 
 - **Meta `ads_*` tools not in the session** — stop and point at `https://mcp.facebook.com/ads` (§0). No workaround exists here.
 - **`ads_get_ad_entities` 500 with a metric `filtering`** — that's the known filter bug, not a transient. Drop the filter, sort instead, threshold agent-side (§3).
-- **Any tool 500s once** — retry the identical call once before reporting it.
+- **`ads_get_ad_entities` 500 on an account-wide (or campaign-level) `results` pull** — structural, not transient; retries never help. Scope to one campaign per call and aggregate agent-side (§3).
+- **Any tool 500s once on a scoped call** — retry the identical call once before reporting it.
+- **Dry-run warns "video winner has no posterPath"** — stop and grab the poster via `ads_get_ad_videos` (§3); pushing without it leaves a blank placeholder in the gallery.
 - **A by-id lookup returns only `{id}`** — you omitted `fields`. Re-call with explicit `fields` (§3).
 - **Signed image URL 403 / expired** — it lapsed since the interview. Re-fetch `ads_get_ad_images` and download again immediately.
 - **Dry-run says Scrape Creators key missing** — real import will fail; Settings → Keys first.