@aicopycoders/exodus 2026.7.200-beta.8 → 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,8 +59,10 @@ 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` |
 
 For the operator-facing quick reference on how to invoke these in Claude Code, see `PIPELINES.md` in the workspace root.
 

package/assets/docs/PIPELINES.md

@@ -14,8 +14,10 @@ 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 |
 
 ---
 
@@ -170,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.
@@ -200,3 +227,26 @@ For pipeline-run docs, use:
   npx @aicopycoders/exodus read-doc <runId> — walks every tab, renders to markdown
 Returns: structured JSON forwarded from Google's APIs (or markdown for read-doc)
 ```
+
+---
+
+## exodus-winners
+
+**What it does:** Mines your own Meta ad account for winning ads and imports them into Exodus as generative fuel. Your agent session needs the official Meta Ads MCP connected (`https://mcp.facebook.com/ads` — OAuth with your own Facebook login); the skill interviews you (no numeric questions), finds the ads carrying ~80% of your lifetime results, confirms each pick visually, then pushes a winner package through the CLI. Imported winners surface in generation selection with their verdict.
+
+```operator-guide
+Subcommands:
+  exodus winners import <file.json | ->   Push a winner package (- reads stdin)
+  exodus winners status <importId>        Re-poll an import later
+  exodus winners list                     Winners Exodus already holds
+
+Import flags:
+  --dry-run    Would-create vs would-update per winner; zero writes
+  --no-wait    Return the importId immediately instead of polling
+  --json       Machine-readable output
+
+Requires: Meta Ads MCP in the session (mining) + your Scrape Creators key in
+Settings → Keys (the own-page match scrape bills your account).
+Say things like: "exodus, import my winning ads" · "exodus, mine my ad
+account for winners" · "exodus, which winners does Exodus already hold?"
+```

package/assets/skills/exodus/SKILL.md

@@ -18,12 +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` |
-| Update the CLI + skills | run `npx @aicopycoders/exodus@latest init` |
+| 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 ("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

@@ -0,0 +1,239 @@
+---
+name: exodus-winners
+description: Mine the member's OWN Meta ad account for its winning ads and import them into Exodus as generative fuel. The member's Claude Code session holds BOTH the official Meta Ads MCP (their Facebook login, their machine) and the Exodus CLI; this skill orchestrates the whole journey — point them at the Meta MCP, pick one ad account, run a NO-NUMBERS winner-definition interview, mine the account via the MCP, confirm each pick visually, then push a winner-package JSON with `npx @aicopycoders/exodus winners import` and run the two-phase video gap-filler. Only invoke when the user has explicitly invoked Exodus: they said "exodus" in the request ("exodus, import my winning ads", "exodus winners", "exodus, mine my ad account for winners", "exodus, which of my own ads are winners"), named this skill or /exodus-winners, ran an `npx @aicopycoders/exodus winners` command, or the `exodus` hub skill routed here. Never claim generic asks ("what are my best ads", "pull my Meta ads", "analyze my Facebook ads") without Exodus context — in shared folders those may belong to the user's other tools; if the user did not say exodus, this skill is not for them. This is the member's OWN account's winners, NOT competitor swipes — competitor swipe mining lives on the dashboard's Swipe Mining surfaces, not here. The bare word "Genesis" without "exodus" refers to the member's own Genesis API key and personal bot recipes, NOT to Exodus.
+---
+
+```operator-guide
+Subcommands:
+  exodus winners import <file.json | ->  [--dry-run] [--no-wait] [--json]   Push a winner package (- reads stdin)
+  exodus winners status <importId>       [--json]                           Re-poll an import later
+  exodus winners list                    [--json]                           Winners Exodus already holds
+
+Key flags:
+  --dry-run   Local schema check + server dry-run: would-create vs would-update per winner,
+              plus a Scrape Creators key warning if it's missing. Zero writes, no media upload.
+  --no-wait   Return the importId immediately instead of polling to outcomes
+  --json      Machine-readable output
+
+Facts baked into the CLI:
+  • Scopes to your active brand (exodus brand current). Switch with the exodus-brand skill.
+  • Requires the member's Scrape Creators key (Settings → Keys) — the own-page match scrape bills them.
+  • asset paths in the package resolve RELATIVE TO THE JSON FILE'S FOLDER.
+  • Re-push never duplicates rows: verdict snapshots replace wholesale; gap-filled rows
+    upgrade in place; winners absent from a re-push are untouched. It DOES re-run the
+    billed match scrape + enrichment — push updates, don't push as a retry reflex.
+
+Meta side: the official Meta Ads MCP (https://mcp.facebook.com/ads) supplies all account data.
+This skill NEVER calls the Meta Graph API directly and NEVER calls ads_library_search.
+```
+
+# Winners — Mine Your Own Ad Account and Import the Champions
+
+This is the agent-side journey for **Own-Brand Winners**: turn the member's real Meta ad account into a set of designated winners that Exodus stores as generative fuel. The session holds the member's **own Meta Ads MCP** (their Facebook OAuth) alongside the Exodus CLI — you drive both.
+
+The member is a **creative strategist, not a media buyer**. This entire journey is data *collection and preparation* — the analysis happens later, server-side, on the stored winners. So the interview **never asks a single numeric question**: no budgets, no ROAS targets, no thresholds, no "top how many?". You infer the mechanics and confirm in plain language. Make that rule impossible to break — if you catch yourself about to ask for a number, stop and infer it instead.
+
+The arc, in order: **MCP check → pick one account → winner-definition interview → mine via MCP → 30k-foot view → visual confirmation → write the package → dry-run → import → video gap-filler.** Persist the definition so re-mining re-asks nothing already settled.
+
+## 0. Meta Ads MCP must be connected
+
+Everything here reads from the **official Meta Ads MCP** — a remote MCP server at `https://mcp.facebook.com/ads`, OAuth'd in the user's browser with their own Facebook login. We don't own that flow; there is exactly one setup pointer and no troubleshooting beyond it.
+
+**If the `ads_*` Meta tools are not present in this session, stop.** Tell the user to add `https://mcp.facebook.com/ads` as a remote MCP server and complete the browser OAuth, then come back. Do not attempt any workaround, any Graph API call, or any other connection method.
+
+## 1. Account selection — the required first step, pinned forever
+
+Call `ads_get_ad_accounts`. It returns **every** account the login can touch — often a dozen-plus across several businesses. For each: `ad_account_id`, `ad_account_name`, `business_name`, `is_queryable`, `not_queryable_reason`, currency.
+
+- Show only **queryable** accounts (`is_queryable: true`). For any flagged one, surface its `not_queryable_reason` so the user understands why it's absent — don't silently drop it.
+- **Account names can be empty strings** — fall back to the id and business name so the list is still legible.
+- The user picks **one**. That account is **pinned** in the definition file (`adAccountId` + name) and is **never re-asked** and never allowed to silently drift. Multi-account handling beyond this single pin is out of scope — one account per definition file.
+
+## 2. The winner-definition interview — prescriptive, no numbers
+
+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 **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 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.
+
+- **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.
+
+The defaults behind this rule (`window: "maximum"`, `resultsFloor: 10`, `contributionLine: 0.80`) live in the definition file and are **edited in the file, never interrogated**. Selection is **format-agnostic** — you never ask "video or image?"; the per-format cuts already guarantee top images *and* top videos import.
+
+## 3. Mining mechanics — the MCP facts that make or break this
+
+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:
+
+- **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.
+- **Always pass explicit `fields`** on every by-id lookup (`ads_get_creatives`, `ads_get_ad_images`, `ads_get_ad_videos`). The "omit fields → all fields" default is **broken** — a bare by-id lookup returns only `{id}`.
+- **Creative content needs a re-fetch by `creative_ids`.** Listing mode returns ids/names only. A creative detail call gives `body` (primary text), `title` (headline), `call_to_action_type`, `image_hash`, `image_url` (signed CDN), and `effective_object_story_id` (`<pageId>_<postId>` — its **prefix is your page id**, the scrape target and own-brand row key).
+- **`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. 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.
+
+## 4. The 30,000-foot view first
+
+Before you confirm a single ad, lead with the **account summary** — the strategist wants the shape before the specimens:
+
+> "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 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
+
+This is a HITL gate; treat it like one. For each proposed winner, render it with **`ads_get_ad_preview`** (an actual in-context creative image) and show it. The strategist:
+
+- **strikes** picks that don't belong,
+- **adds** any obvious winner the rule missed,
+- and may attach an optional free-text **note** per winner (`strategistNote`).
+
+Their edits win over the algorithm. Don't argue the rule against their eyes — they made these ads. Only after this pass do you compose verdicts and write the package.
+
+## 6. Naming is read-only
+
+Campaign / adset / ad names feed two things: your **awareness inference** (§2b) and the winner's `sourceNames` as creative context. That's all. **No naming-conventions guidance** — nobody is asked to rename anything, and the account's naming hygiene is not your concern.
+
+## 7. The verdict snapshot & the winner-package JSON
+
+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
+{
+  "version": 1,
+  "source": {
+    "adAccountId": "act_123…",
+    "adAccountName": "Ground Co",
+    "pageId": "10715…",              // scrape target + own-brand row key (from effective_object_story_id prefix)
+    "pageName": "Ground Co",
+    "country": "US",                 // optional, default US — non-US accounts false-unmatch otherwise
+    "minedAt": "2026-07-14T18:30:00Z"
+  },
+  "winners": [
+    {
+      "accountAdId": "1202…",        // the natural key; REQUIRED
+      "campaignId": "1201…",
+      "adSetId": "1202…",
+      "sourceNames": { "campaign": "…", "adSet": "…", "ad": "…" },  // verbatim, read-only
+      "createdTime": "2025-11-02T…",
+      "format": "video",              // "video" | "image"; REQUIRED
+      "bodyText": "…",                // verbatim; bodyText OR headline required
+      "headline": "…",                // optional
+      "ctaType": "SHOP_NOW",          // optional
+      "effectiveObjectStoryId": "pageId_postId",  // optional
+      "verdict": {
+        "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",
+        "awarenessLevel": "product-aware",       // from the confirmed mapping (§2b)
+        "selectionBasis": ["overall", "top-video"],  // which cut(s) it cleared
+        "strategistNote": "…"         // optional, from §5
+      },
+      "assets": {
+        "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)
+      }
+    }
+  ]
+}
+```
+
+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
+
+Run these in this exact order.
+
+**1. Write the package to disk.** Put it at `state/own-brand-winners/import-<date>.json` (user-inspectable and re-runnable), with the interview-time downloaded media in a folder alongside it. **Asset paths are relative to the JSON file's folder** — so `./media/…jpg` next to `import-<date>.json` resolves correctly.
+
+**2. Dry-run first, always:**
+
+```bash
+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). **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
+```
+
+Default polling waits for outcomes. Present the **per-winner outcome table** it returns — each row is `matched` / `gap-filled` / `partial (missing: …)` / `rejected (reason)` — plus the created-vs-updated split.
+
+**3. The two-phase video gap-filler.** Do **not** open with "find me 12 mp4 files." Push everything first; the report names exactly which video winners came back `partial (missing: video-file)` (expected — MCP has no video download). Then ask the user for **just those** files — they made the ads, they usually have them. Write a **second import JSON** containing only the partial winners: copy each winner's **full object** from the first import file (the server validates every push the same way — a stripped-down winner missing its `verdict`, `format`, or copy is rejected, not merged), same `source` block, and add the `videoPath`. Re-push it — the idempotent upgrade path completes those rows in place (the identical verdict re-replacing itself is harmless):
+
+```bash
+npx @aicopycoders/exodus winners import state/own-brand-winners/gapfill-<date>.json --json
+```
+
+Pick gap-fill candidates by their `missing` array **containing** `video-file` — an unmatched video winner usually lists `transcript` too. The re-push fills the file gap, but transcription runs as a **separate sweep after the import finalizes**, so the row typically still reads `partial (missing: transcript)` right away. That's not a failure — tell the user, and re-check `exodus winners list` later for the transcript to land.
+
+Any winner the user can't supply a file for **stays amber and visible** in `exodus winners list` — that's fine, not a failure.
+
+**4. "What does Exodus already hold?" is `exodus winners list`** — never keep the imported-winners ledger agent-side; it lives server-side and this is how you read it.
+
+**5. Re-push safety** (from the CLI itself): re-pushing never duplicates rows — verdict snapshots replace wholesale, gap-filled rows upgrade in place, winners absent from a re-push are left untouched. But it is not free: every push re-uploads referenced assets, re-runs enrichment, and re-fires the Scrape Creators match scrape (billed to the member) — so re-push when there's something to update, not as a retry reflex.
+
+## 9. Definition persistence
+
+Persist the interview to `state/own-brand-winners.json`, keyed by **brand slug** (`state/` survives skill refreshes). It holds:
+
+- pinned `adAccountId` + name (§1),
+- `campaignAwarenessMap` (§2b),
+- editable `defaults` — `{ "window": "maximum", "resultsFloor": 10, "contributionLine": 0.80 }`,
+- `customDefinition` (the §2a escape-hatch text, verbatim),
+- `lastMinedAt`.
+
+Re-running re-asks **nothing already pinned** — only genuinely new campaigns get a confirm pass. Losing the file costs a short re-interview, never duplicate rows (dedup is server-side on `accountAdId`). Defaults are changed by editing the file, never by interrogating the user.
+
+## Failure handling
+
+- **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).
+- **`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.
+- **`partial (missing: video-file)`** — expected for video winners; run the §8 gap-filler.
+- **Import poll timed out** — the import is still running server-side; re-poll with `npx @aicopycoders/exodus winners status <importId>` rather than re-pushing.
+- **Import auth / wrong brand** — `npx @aicopycoders/exodus doctor`, then confirm `npx @aicopycoders/exodus brand current` is the brand you mean (switch via the `exodus-brand` skill). Winners scope to the active brand.
+
+## Not the right skill for
+
+- **Competitor swipe mining** — this skill is the member's OWN ad account only. Mining competitors' ads lives on the dashboard's **Swipe Mining** surfaces (and the CLI swipe commands), not here.
+- **Naming-conventions guidance** — names are read-only inputs; nobody is asked to rename anything.
+- **Designating losers** — winners only at v1.
+- **Scheduled / automated re-mining cadence** — re-run the skill when you want a fresh snapshot; there's no scheduler.
+- **Multi-account handling beyond the single pin** — one account per definition file.
+- **Meta MCP connection troubleshooting beyond the one URL**, and **any direct Meta Graph API call** — out of bounds; the MCP is the only Meta surface.
+- **Writing copy or rendering images from these winners** — that happens downstream once they're stored (`exodus-genesis`, `exodus-image`); this skill only collects and imports.