@aicopycoders/exodus 2026.8.1600 → 2026.9.200

package/README.md

@@ -46,6 +46,9 @@ health, CLI currency — and tells you exactly what to fix.
 - `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.
+- `npx -y @aicopycoders/exodus@beta hooks --help` — browse the Organic Scout
+  hook library: filter by score, lane, validation status and more; explain a
+  score; find cards sharing a hook pattern; export to CSV or JSON. Read-only.
 
 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

@@ -60,6 +60,7 @@ These are the **Exodus** pipelines — the automatic system that drives the Gene
 | **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. |
+| **Hooks** | `exodus-hooks` | Read the Scout library — the hook cards captured from Instagram outliers. Compose filters (score, lane, validation status, language, hook type, recency), inspect one card, find cards sharing a hook pattern, export to CSV. Read-only. |
 | **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

@@ -15,6 +15,7 @@ In Claude Code you don't click buttons. You say **"exodus"** plus what you want
 | 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-hooks | Read the Scout library of hook cards — composable filters, one-card detail, pattern matches, CSV export (read-only) |
 | 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 |
@@ -197,6 +198,30 @@ Every workflow/session/bank verb takes --json — that output is the machine API
 
 ---
 
+## exodus-hooks
+
+**What it does:** Reads the Scout library — the brand's pool of hook cards captured from Instagram outliers. Filters compose, so one query answers "10×+, on-screen hooks, Spanish, under 14 days". Read-only; promoting a card is a dashboard act.
+
+```operator-guide
+Commands:
+  exodus hooks list [filters] [--limit n] [--json]      the filtered slice
+  exodus hooks show <ref> [--json]                      one full card
+  exodus hooks find-similar <ref> [--json]              cards sharing the hook pattern
+  exodus hooks explain-score <ref>                      the evidence behind the score
+  exodus hooks export --csv|--json [filters] [--out f]  the whole filtered corpus
+Filters (compose):
+  --min-score N · --lane relative|absolute|velocity|evergreen
+  --status unproven|corroborated|cross-validated|saturated|virgin-market
+  --lifecycle new|reviewed|promoted|tested|killed · --creator <handle>
+  --language xx · --market xx · --via paste|seed|expansion|spotter · --days N
+  --extract pending|complete|partial|failed|skipped · --has spoken|onscreen|caption
+  --pattern "text" · --limit N (default 50, max 200)
+<ref>: card id, Instagram shortcode, or post URL
+Returns: a table, --json data, or an exported CSV/JSON file
+```
+
+---
+
 ## exodus-browse
 
 **What it does:** View past pipeline runs and pull outputs from previous sessions.

package/assets/skills/exodus/SKILL.md

@@ -24,6 +24,7 @@ This skill ROUTES. Read what the user wants, name the destination skill, and han
 | 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` |
+| Read the Scout hook library — "what do my 15×+ hooks have in common", "show me my Spanish on-screen hooks", "why did that reel score 22×", "export my hooks to a spreadsheet" | `exodus-hooks` (read-only; promoting a card is a dashboard act) |
 | 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` |

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

@@ -0,0 +1,133 @@
+---
+name: exodus-hooks
+description: Read the brand's Scout library — the pool of hook cards captured from Instagram outliers — through the read-only `npx @aicopycoders/exodus hooks` command family. Use it to answer questions about what's working organically: "exodus, what do my 15×+ hooks have in common?", "exodus, show me my Spanish on-screen hooks from the last two weeks", "exodus, why did that reel score 22×?", "exodus, find other cards with the same hook pattern", "exodus, export my hook library to a spreadsheet". The power is in composing filters — score, lane, validation status, language, market, creator, hook type, recency, discovery door — into one query, then reading the cards back and finding the pattern. Only invoke when the user has explicitly invoked Exodus: they said "exodus" in the request, named this skill or /exodus-hooks, ran an `npx @aicopycoders/exodus hooks` command, or the `exodus` hub skill routed here. Never claim generic hook questions ("what makes a good hook", "write me some hooks") — hook *writing* belongs to `exodus-genesis`/`exodus-write` and hook *judgment* to `exodus-strategist`; in shared folders generic asks may belong to the user's other tools. A hook card is NOT an Idea Bank card — `exodus idea` questions ("what's in my idea bank", "write from idea G3") are a different object with a different lifecycle and do not route here.
+---
+
+```operator-guide
+Read-only. Nothing in this family changes a card — promoting a hook is a dashboard act.
+
+  npx @aicopycoders/exodus hooks list [filters] [--limit n] [--json]
+  npx @aicopycoders/exodus hooks show <ref> [--json]
+  npx @aicopycoders/exodus hooks find-similar <ref> [--json]
+  npx @aicopycoders/exodus hooks explain-score <ref>
+  npx @aicopycoders/exodus hooks export --csv|--json [same filters as list] [--out <file>]
+
+Filters (compose freely — each one narrows the same query):
+  --min-score N        viral score at or above N (10 = "did 10× the creator's normal")
+  --lane relative|absolute|velocity|evergreen        which detection lane caught it
+  --status unproven|corroborated|cross-validated|saturated|virgin-market
+  --lifecycle new|reviewed|promoted|tested|killed
+  --creator <handle>   one creator (no @)
+  --language xx        the post's language (es, pt, en …)
+  --market xx          the market it was seen in
+  --via paste|seed|expansion|spotter                 which door captured it
+  --days N             captured in the last N days
+  --extract pending|complete|partial|failed|skipped  hook-extraction state
+  --has spoken|onscreen|caption                      that hook type is present
+  --pattern "text"     match against the hook pattern
+  --limit N            default 50, max 200
+
+<ref> is a card id, an Instagram shortcode, or the post URL — all three work.
+Returns: a table by default, structured data with --json, a file with export.
+```
+
+# Hooks — read the Scout library
+
+## Strategic Context
+
+The **Scout library** is the brand's pool of **hook cards** — one card per captured Instagram outlier, carrying the three verbatim hooks (spoken, on-screen, caption) with their type tags, the **hook pattern** (the hook with its blanks exposed: "I'm {age}, I tried {thing} for {duration} — here's what happened"), the format skeleton, the viral score with its evidence sentence, the validation status, language and market, the relevance tag, the transcript, and the source link.
+
+The dashboard shows that library as five bucket rails with filter chips. This CLI family is the *other* window on the same cards — the one where filters compose. That's the whole point: the dashboard answers "show me my breakouts"; `hooks list` answers "10×+, on-screen hooks, Spanish, captured in the last two weeks" in one query. When a member asks a pattern question, you are not browsing for them — you are pulling the right slice and telling them what it says.
+
+## When to Use
+
+- "What do my 15×+ hooks have in common?"
+- "Which hook type is winning — spoken, on-screen, or caption?"
+- "Show me the cross-validated cards I haven't reviewed yet."
+- "Why did that reel score 22×?"
+- "Are there other cards using this same hook pattern?"
+- "Export my hook library so I can look at it in a spreadsheet."
+
+## Composing filters — the move to reach for first
+
+Every filter narrows the same query, so translate the member's sentence into flags rather than pulling a big list and squinting at it. The spec's own example:
+
+> "10×+, on-screen hooks, Spanish, under 14 days"
+
+```bash
+npx @aicopycoders/exodus hooks list --min-score 10 --has onscreen --language es --days 14
+```
+
+More of the same shape:
+
+```bash
+# Structural winners nobody has run yet
+npx @aicopycoders/exodus hooks list --status cross-validated --lifecycle new
+
+# The highest-opportunity find: proven elsewhere, absent in your language
+npx @aicopycoders/exodus hooks list --status virgin-market --limit 25
+
+# One creator's breakouts, newest first
+npx @aicopycoders/exodus hooks list --creator someonehandle --min-score 5
+
+# What the feed spotter caught this week vs. what seeds brought in
+npx @aicopycoders/exodus hooks list --via spotter --days 7
+npx @aicopycoders/exodus hooks list --via seed --days 7
+```
+
+Default limit is 50, max 200. For a real corpus sweep use `export`, which cursor-walks the whole filtered set instead of stopping at the cap.
+
+## Worked example — "what do my 15×+ hooks have in common?"
+
+1. **Pull the slice as data, not a table.** You're going to analyze it, so ask for JSON:
+
+   ```bash
+   npx @aicopycoders/exodus hooks list --min-score 15 --json
+   ```
+
+2. **Read the fields that carry the pattern.** `hookPattern` (the blanks-exposed hook) and `formatSkeleton` (the shape of the video) are what group; the verbatim `hookSpoken` / `hookOnScreen` / `hookCaption` are the evidence you quote back. Also worth counting: which `lanes` fired, `validationStatus`, `language`, and which hook type is filled.
+
+3. **Group and summarize in plain words.** Name the two or three recurring shapes, say how many cards each covers, quote one real hook per shape, and note what the numbers say ("11 of your 14 cards above 15× lead with an on-screen hook; 9 are personal-timeline claims — 'I did {thing} for {duration}'").
+
+4. **Go deeper on the strongest shape.** Take the best card and ask the library whether it's a one-off:
+
+   ```bash
+   npx @aicopycoders/exodus hooks find-similar <ref>
+   npx @aicopycoders/exodus hooks explain-score <ref>
+   ```
+
+5. **Hand back a move, not just a report.** The strategist call (which shape to write from, which awareness level) belongs to `exodus-strategist`; the writing belongs to `exodus-write` / `exodus-genesis`.
+
+## Going deeper on one card
+
+- **`show <ref>`** — the full card: every hook and its type, pattern, format skeleton, scores with evidence, validation status, lifecycle, language/market, relevance tag, transcript, source link.
+- **`find-similar <ref>`** — other cards in this brand sharing the same canonical hook pattern. This is how you tell a repeatable structure from a lucky post.
+- **`explain-score <ref>`** — the receipts: the evidence sentence saying why the card scored what it scored, the baseline numbers behind it, and each detection lane's own reason ("1.2M views clears the absolute bar"). Reach for this any time a member doubts a number, and quote the sentence rather than paraphrasing it.
+
+## Honesty rules — never paper over a gap
+
+The cards are built so a gap always announces itself. Relay the gap; do not fill it in.
+
+- **No score is a real answer.** A card with `baselineInsufficient` has **no viral score** — the creator's baseline was too thin to divide by. Its `scoreEvidence` sentence says exactly that. Never estimate, average, or invent a multiple for it, and don't quietly drop it from a summary — say "3 cards can't be scored yet (too few posts to compare against)".
+- **Missing hooks have a reason.** `extractStatus` of `partial`, `failed`, or `skipped` means some or all hook text is absent, and `extractEvidence` says why. If a slice looks thin, check extraction before concluding the hooks aren't there.
+- **"unproven" is not a defect.** Every card lands as `unproven` at capture — one post, one creator, no corroboration run yet. It means "not checked", not "checked and found weak". Only call something weak on evidence.
+- **Views decide; likes and comments don't.** They're recorded as evidence, never as score. Rank on `viralScore`, never on engagement.
+- **Relevance ranks, it never gates.** A low relevance tag with a huge score is a structure to steal, not a card to discard.
+
+## Output — table, JSON, or CSV
+
+- **Table (default)** — when the member just wants to look at what's there. Don't paste 50 rows back; surface the handful that answers the question and name them.
+- **`--json`** — whenever *you* are doing the analysis: grouping, counting, comparing hook types, chasing a pattern. Parse it, then answer in plain language.
+- **`export --csv`** — when they ask for a spreadsheet or want to work outside Claude. `export` walks the whole filtered corpus past the list cap; `--out <file>` writes it, otherwise it prints.
+
+```bash
+npx @aicopycoders/exodus hooks export --csv --min-score 10 --days 30 --out hooks-30d.csv
+```
+
+Same filters as `list`, so build the query with `list` first, eyeball that it's the right slice, then re-run it as an export.
+
+## Read-only — and not the Idea Bank
+
+This family **only reads**. There is no promote, edit, kill, or re-score command here. Promoting a hook card (and moving its lifecycle along) is a **dashboard act** — if the member wants a card promoted, point them at the Scout page (Sources → Scout) on the dashboard rather than hunting for a flag that doesn't exist.
+
+And keep the two objects straight: a **hook card** is a capture in the Scout library — every outlier the system found. An **Idea Bank card** is work-queue material the member is about to write from. Different object, different lifecycle, different command family. "What's in my idea bank?" / "write from idea G3" is `exodus idea …` — route that back through the `exodus` hub skill (or `exodus-write` for the writing flow), never through `exodus hooks`.

package/dist/bin/exodus.js

@@ -22,6 +22,7 @@ const OTHER_COMMANDS = new Set([
     "workflow",
     "session",
     "bank",
+    "hooks",
 ]);
 const HIDDEN_COMMANDS = new Set([
     "creative",
@@ -39,6 +40,7 @@ const EXAMPLES = [
     'exodus meme recommend --brief "grounding sheets reduce inflammation"',
     'exodus meme run --brief "grounding sheets reduce inflammation" --formats \'[...]\'',
     'exodus browse',
+    'exodus hooks list --min-score 10',
     'exodus status --id <runId> --type genesis',
 ];
 function installedCommands() {

package/dist/commands/doctor.js

@@ -117,8 +117,8 @@ export async function checkWhoami() {
             return {
                 ok: false,
                 label: "Brand resolution",
-                detail: "API key did not resolve to a workspace",
-                fix: "ask an admin to mint a brand-scoped API key in Settings → Brands → API keys",
+                detail: "API key did not resolve to a brand",
+                fix: "pick or create a brand in the dashboard (brand picker, top right); if that's done, ask an admin to mint a brand-scoped API key in Settings → Brands → API keys",
             };
         }
         if (!d.foundationReady) {
@@ -410,8 +410,8 @@ export async function checkApiAndDrive() {
         : {
             ok: false,
             label: "Dashboard API key",
-            detail: "no workspace found for this key",
-            fix: "contact support — your workspace may not be set up",
+            detail: "no brand to work in — none selected, or the saved one is gone / not yours",
+            fix: "pick or create a brand in the dashboard (brand picker, top right), then run doctor again",
         };
     const driveResult = drive.connected
         ? {

package/dist/commands/hooks.d.ts

@@ -0,0 +1,161 @@
+import { type ApiResponse } from "../lib/client.js";
+import { type Channel } from "../lib/channel.js";
+export declare const helpText: string;
+export declare const LANES: readonly ["relative", "absolute", "velocity", "evergreen"];
+export declare const VALIDATION_STATUSES: readonly ["unproven", "corroborated", "cross-validated", "saturated", "virgin-market"];
+export declare const LIFECYCLES: readonly ["new", "reviewed", "promoted", "tested", "killed"];
+export declare const DISCOVERED_VIA: readonly ["paste", "seed", "expansion", "spotter"];
+export declare const EXTRACT_STATUSES: readonly ["pending", "complete", "partial", "failed", "skipped"];
+export declare const HAS_HOOKS: readonly ["spoken", "onscreen", "caption"];
+export interface ApiHookLane {
+    lane?: string | null;
+    reason?: string | null;
+}
+export interface ApiHookCorroboration {
+    replicationCount?: number | null;
+    languageSpread?: number | string[] | null;
+    marketsSeen?: string[] | null;
+    checkedAt?: number | null;
+}
+export interface ApiHookGate {
+    verdict?: string | null;
+    reasoning?: string | null;
+    decidedAt?: number | null;
+}
+export interface ApiHookCard {
+    id?: string | null;
+    shortcode?: string | null;
+    sourceUrl?: string | null;
+    creatorHandle?: string | null;
+    caption?: string | null;
+    thumbnailUrl?: string | null;
+    publishedAt?: number | null;
+    capturedAt?: number | null;
+    viewCount?: number | null;
+    likeCount?: number | null;
+    commentCount?: number | null;
+    creatorTypicalViews?: number | null;
+    baselineSampleSize?: number | null;
+    baselineInsufficient?: boolean | null;
+    viralScore?: number | null;
+    scoreEvidence?: string | null;
+    lanes?: ApiHookLane[] | null;
+    hookSpoken?: string | null;
+    hookOnScreen?: string | null;
+    hookCaption?: string | null;
+    hookPattern?: string | null;
+    formatSkeleton?: string | null;
+    extractStatus?: string | null;
+    extractEvidence?: string | null;
+    validationStatus?: string | null;
+    corroboration?: ApiHookCorroboration | null;
+    language?: string | null;
+    market?: string | null;
+    relevanceTag?: string | number | null;
+    lifecycle?: string | null;
+    discoveredVia?: string | null;
+    gate?: ApiHookGate | null;
+    transcript?: string | null;
+    metricSnapshots?: unknown[] | null;
+    velocityPollCount?: number | null;
+    citedStudy?: string | null;
+    hookPatternKey?: string | null;
+}
+export interface HookListResponse {
+    cards?: ApiHookCard[];
+    cursor?: string | null;
+    isDone?: boolean;
+}
+export interface HookShowResponse {
+    card?: ApiHookCard;
+}
+export interface HookSimilarSubject {
+    id?: string | null;
+    shortcode?: string | null;
+    creatorHandle?: string | null;
+    hookPattern?: string | null;
+    viralScore?: number | null;
+    scoreEvidence?: string | null;
+}
+export interface HookSimilarResponse {
+    card?: HookSimilarSubject;
+    similar?: ApiHookCard[];
+}
+export declare const EXPORT_CAP = 5000;
+export declare const EXPORT_PAGE_SIZE = 200;
+export declare const LIST_SCAN_CAP = 2000;
+export interface FlowResult {
+    code: number;
+    lines: string[];
+    warnings?: string[];
+}
+export interface HooksDeps {
+    get: (path: string) => Promise<ApiResponse<unknown>>;
+    writeFile: (path: string, content: string) => void;
+    channel: Channel;
+    now: () => number;
+    apiUrl: () => string;
+}
+export interface HookFilters {
+    minScore?: number;
+    lane?: string;
+    status?: string;
+    lifecycle?: string;
+    creator?: string;
+    language?: string;
+    market?: string;
+    via?: string;
+    sinceDays?: number;
+    extract?: string;
+    has?: string;
+    pattern?: string;
+    limit?: number;
+}
+export type ParseResult = {
+    ok: true;
+    filters: HookFilters;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function parseHookFilters(flags: Record<string, string | boolean>, maxLimit: number): ParseResult;
+export declare function filterQuery(filters: HookFilters, extra?: {
+    limit?: number;
+    cursor?: string;
+}): string;
+export declare function formatScore(score: unknown): string;
+export declare function shortAge(value: unknown, now: number): string;
+export declare function laneCodes(lanes: ApiHookLane[] | null | undefined): string;
+export declare function truncate(text: unknown, max: number): string;
+export declare function formatCardTable(cards: ApiHookCard[], now: number): string;
+export interface ListWalk {
+    cards: ApiHookCard[];
+    more: boolean;
+    scanCapped: boolean;
+}
+export declare function formatList(walk: ListWalk, now: number): string[];
+export declare function formatShow(card: ApiHookCard, now: number): string;
+export declare function formatExplainScore(card: ApiHookCard, now: number): string[];
+export declare function explainScoreJson(card: ApiHookCard): Record<string, unknown>;
+export declare const CSV_COLUMNS: readonly ["id", "shortcode", "sourceUrl", "creatorHandle", "viralScore", "scoreEvidence", "viewCount", "likeCount", "commentCount", "creatorTypicalViews", "baselineSampleSize", "baselineInsufficient", "validationStatus", "lanes", "hookSpoken", "hookOnScreen", "hookCaption", "hookPattern", "formatSkeleton", "extractStatus", "language", "market", "lifecycle", "discoveredVia", "capturedAt", "publishedAt", "replicationCount", "languageSpread"];
+export declare function csvEscape(value: unknown): string;
+export declare const CSV_RECORD_SEP = "\r\n";
+export declare function toCsv(cards: ApiHookCard[]): string;
+export declare function listFlow(filters: HookFilters, json: boolean, deps: HooksDeps): Promise<FlowResult>;
+export declare function showFlow(ref: string, json: boolean, deps: HooksDeps): Promise<FlowResult>;
+export declare function explainScoreFlow(ref: string, json: boolean, deps: HooksDeps): Promise<FlowResult>;
+export declare function findSimilarFlow(ref: string, json: boolean, deps: HooksDeps): Promise<FlowResult>;
+export interface ExportOptions {
+    format: "csv" | "json";
+    out?: string;
+}
+export declare function exportFlow(filters: HookFilters, options: ExportOptions, deps: HooksDeps): Promise<FlowResult>;
+export declare function parsePositional(args?: string[]): string[];
+export declare function resolveExportFormat(flags: Record<string, string | boolean>): {
+    ok: true;
+    format: "csv" | "json";
+} | {
+    ok: false;
+    message: string;
+};
+export declare function run(flags: Record<string, string | boolean>): Promise<void>;

package/dist/commands/hooks.js

@@ -0,0 +1,815 @@
+import fs from "node:fs";
+import { apiGet, getApiUrl } from "../lib/client.js";
+import { formatApiError } from "../lib/format.js";
+import { auth401Hint } from "../lib/backend-hint.js";
+import { getChannel } from "../lib/channel.js";
+import { missingRouteLine } from "../lib/route-support.js";
+export const helpText = `
+exodus hooks — browse the Scout hook library (read-only)
+
+Every organic reel the Scout captured for this brand becomes a HOOK CARD: the
+outlier score with the sentence that justifies it, the three hooks (spoken,
+on-screen, caption), the pattern behind them, and how far the pattern has been
+validated. This family only READS that library — nothing here changes a card.
+Promoting a hook into a brief or an Idea Bank card is a dashboard act, on
+purpose: a hook card and an Idea Bank card are different objects.
+
+Usage:
+  exodus hooks list [filters] [--limit n] [--json]
+  exodus hooks show <ref> [--json]
+  exodus hooks find-similar <ref> [--json]
+  exodus hooks explain-score <ref> [--json]
+  exodus hooks export --csv|--json [filters] [--limit n] [--out <file>]
+
+<ref> is a card id, an Instagram shortcode, or a full Instagram URL.
+
+Filters (list + export):
+  --min-score <n>        Only cards scoring at least n× the creator's own median
+  --lane <x>             relative | absolute | velocity | evergreen
+  --status <x>           unproven | corroborated | cross-validated | saturated | virgin-market
+  --lifecycle <x>        new | reviewed | promoted | tested | killed
+  --creator <handle>     One creator's cards (with or without the leading @)
+  --language <xx>        Spoken/caption language code, e.g. en, es
+  --market <xx>          Market code, e.g. US, MX
+  --via <x>              paste | seed | expansion | spotter
+  --days <n>             Captured within the last n days
+  --extract <x>          pending | complete | partial | failed | skipped
+  --has <x>              spoken | onscreen | caption — cards with that hook extracted
+  --pattern "<text>"     Hook patterns containing this text
+
+Other flags:
+  --limit <n>            list: how many cards to show, 1–200 (default 50). A
+                         filtered list keeps paging until it has that many, or
+                         until it has searched the newest ~2000 cards — older
+                         ones live behind \`export\`.
+                         export: most rows to write, 1–5000 (default 5000).
+  --json                 Machine-readable JSON instead of the human view
+  --csv                  (export) Comma-separated rows, RFC-4180 quoted
+  --out <file>           (export) Write to a file instead of stdout
+
+Examples:
+  exodus hooks list --min-score 10 --lane velocity
+  exodus hooks list --has onscreen --language es --days 14
+  exodus hooks show C9xAbCdEfGh
+  exodus hooks explain-score https://www.instagram.com/reel/C9xAbCdEfGh/
+  exodus hooks find-similar C9xAbCdEfGh
+  exodus hooks export --csv --min-score 5 --out hooks.csv
+`.trim();
+export const LANES = ["relative", "absolute", "velocity", "evergreen"];
+export const VALIDATION_STATUSES = [
+    "unproven",
+    "corroborated",
+    "cross-validated",
+    "saturated",
+    "virgin-market",
+];
+export const LIFECYCLES = ["new", "reviewed", "promoted", "tested", "killed"];
+export const DISCOVERED_VIA = ["paste", "seed", "expansion", "spotter"];
+export const EXTRACT_STATUSES = ["pending", "complete", "partial", "failed", "skipped"];
+export const HAS_HOOKS = ["spoken", "onscreen", "caption"];
+const LIST_PATH = "/api/v2/hooks";
+const SHOW_PATH = "/api/v2/hooks/show";
+const SIMILAR_PATH = "/api/v2/hooks/find-similar";
+export const EXPORT_CAP = 5000;
+export const EXPORT_PAGE_SIZE = 200;
+export const LIST_SCAN_CAP = 2000;
+const VALUE_FLAGS = new Set([
+    "min-score",
+    "lane",
+    "status",
+    "lifecycle",
+    "creator",
+    "language",
+    "market",
+    "via",
+    "days",
+    "extract",
+    "has",
+    "pattern",
+    "limit",
+    "out",
+]);
+const defaultDeps = {
+    get: (path) => apiGet(path),
+    writeFile: (path, content) => fs.writeFileSync(path, content, "utf-8"),
+    channel: getChannel(),
+    now: () => Date.now(),
+    apiUrl: () => getApiUrl(),
+};
+function str(flag) {
+    return typeof flag === "string" && flag.trim() ? flag.trim() : undefined;
+}
+function oneOf(flags, name, allowed) {
+    const raw = flags[name];
+    if (raw === undefined)
+        return { ok: true };
+    if (typeof raw !== "string" || raw.trim() === "") {
+        return { ok: false, message: `--${name} needs a value — one of: ${allowed.join(", ")}` };
+    }
+    const value = raw.trim();
+    if (!allowed.includes(value)) {
+        return {
+            ok: false,
+            message: `--${name} must be one of: ${allowed.join(", ")} (got "${value}")`,
+        };
+    }
+    return { ok: true, value };
+}
+function positiveNumber(flags, name) {
+    const raw = flags[name];
+    if (raw === undefined)
+        return { ok: true };
+    if (typeof raw !== "string" || raw.trim() === "") {
+        return { ok: false, message: `--${name} must be a number (got "${String(raw)}")` };
+    }
+    const n = Number(raw);
+    if (Number.isNaN(n) || n < 0) {
+        return { ok: false, message: `--${name} must be a number 0 or greater (got "${raw}")` };
+    }
+    return { ok: true, value: n };
+}
+export function parseHookFilters(flags, maxLimit) {
+    const filters = {};
+    const minScore = positiveNumber(flags, "min-score");
+    if (!minScore.ok)
+        return { ok: false, message: minScore.message };
+    if (minScore.value !== undefined)
+        filters.minScore = minScore.value;
+    const days = positiveNumber(flags, "days");
+    if (!days.ok)
+        return { ok: false, message: days.message };
+    if (days.value !== undefined) {
+        if (!Number.isInteger(days.value) || days.value < 1) {
+            return { ok: false, message: `--days must be a whole number of days, 1 or more` };
+        }
+        filters.sinceDays = days.value;
+    }
+    const enums = [
+        ["lane", "lane", LANES],
+        ["status", "status", VALIDATION_STATUSES],
+        ["lifecycle", "lifecycle", LIFECYCLES],
+        ["via", "via", DISCOVERED_VIA],
+        ["extract", "extract", EXTRACT_STATUSES],
+        ["has", "has", HAS_HOOKS],
+    ];
+    for (const [key, flagName, allowed] of enums) {
+        const parsed = oneOf(flags, flagName, allowed);
+        if (!parsed.ok)
+            return { ok: false, message: parsed.message };
+        if (parsed.value !== undefined) {
+            filters[key] = parsed.value;
+        }
+    }
+    const creator = str(flags["creator"]);
+    if (creator)
+        filters.creator = creator.replace(/^@+/, "");
+    const language = str(flags["language"]);
+    if (language)
+        filters.language = language;
+    const market = str(flags["market"]);
+    if (market)
+        filters.market = market;
+    const pattern = str(flags["pattern"]);
+    if (pattern)
+        filters.pattern = pattern;
+    const limitRaw = flags["limit"];
+    if (limitRaw !== undefined) {
+        if (typeof limitRaw !== "string" || limitRaw.trim() === "") {
+            return { ok: false, message: `--limit must be a whole number 1–${maxLimit}` };
+        }
+        const n = Number(limitRaw);
+        if (!Number.isInteger(n) || n < 1 || n > maxLimit) {
+            return { ok: false, message: `--limit must be a whole number 1–${maxLimit} (got "${limitRaw}")` };
+        }
+        filters.limit = n;
+    }
+    return { ok: true, filters };
+}
+export function filterQuery(filters, extra = {}) {
+    const params = new URLSearchParams();
+    if (extra.limit !== undefined)
+        params.set("limit", String(extra.limit));
+    if (extra.cursor)
+        params.set("cursor", extra.cursor);
+    if (filters.minScore !== undefined)
+        params.set("minScore", String(filters.minScore));
+    if (filters.lane)
+        params.set("lane", filters.lane);
+    if (filters.status)
+        params.set("status", filters.status);
+    if (filters.lifecycle)
+        params.set("lifecycle", filters.lifecycle);
+    if (filters.creator)
+        params.set("creator", filters.creator);
+    if (filters.language)
+        params.set("language", filters.language);
+    if (filters.market)
+        params.set("market", filters.market);
+    if (filters.via)
+        params.set("via", filters.via);
+    if (filters.sinceDays !== undefined)
+        params.set("sinceDays", String(filters.sinceDays));
+    if (filters.extract)
+        params.set("extract", filters.extract);
+    if (filters.has)
+        params.set("has", filters.has);
+    if (filters.pattern)
+        params.set("pattern", filters.pattern);
+    const qs = params.toString();
+    return qs ? `?${qs}` : "";
+}
+function table(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((row) => row[i]?.length ?? 0)));
+    const fmt = (row) => row.map((cell, i) => (cell ?? "").padEnd(widths[i])).join("  ").trimEnd();
+    return [
+        fmt(headers),
+        fmt(headers.map((h) => "-".repeat(h.length))),
+        ...rows.map(fmt),
+    ].join("\n");
+}
+export function formatScore(score) {
+    if (typeof score !== "number" || !Number.isFinite(score))
+        return "—";
+    return `${score.toFixed(1)}×`;
+}
+function formatCount(n) {
+    return typeof n === "number" && Number.isFinite(n) ? n.toLocaleString("en-US") : "—";
+}
+export function shortAge(value, now) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        return "—";
+    const diff = now - value;
+    if (diff < 0)
+        return "now";
+    const min = Math.floor(diff / 60000);
+    if (min < 60)
+        return min < 1 ? "now" : `${min}m`;
+    const hr = Math.floor(min / 60);
+    if (hr < 24)
+        return `${hr}h`;
+    const day = Math.floor(hr / 24);
+    if (day < 7)
+        return `${day}d`;
+    const wk = Math.floor(day / 7);
+    if (wk < 5)
+        return `${wk}w`;
+    const mo = Math.floor(day / 30);
+    if (mo < 12)
+        return `${mo}mo`;
+    return `${Math.floor(day / 365)}y`;
+}
+function isoOrEmpty(ms) {
+    if (typeof ms !== "number" || !Number.isFinite(ms) || ms <= 0)
+        return "";
+    const d = new Date(ms);
+    return Number.isNaN(d.getTime()) ? "" : d.toISOString();
+}
+function dateOrDash(ms) {
+    const iso = isoOrEmpty(ms);
+    return iso ? iso.slice(0, 10) : "—";
+}
+const LANE_SHORT = {
+    relative: "rel",
+    absolute: "abs",
+    velocity: "vel",
+    evergreen: "evg",
+};
+export function laneCodes(lanes) {
+    if (!Array.isArray(lanes) || lanes.length === 0)
+        return "—";
+    const codes = lanes
+        .map((l) => (typeof l?.lane === "string" ? (LANE_SHORT[l.lane] ?? l.lane) : ""))
+        .filter(Boolean);
+    return codes.length > 0 ? codes.join(",") : "—";
+}
+export function truncate(text, max) {
+    if (typeof text !== "string")
+        return "";
+    const flat = text.replace(/\s+/g, " ").trim();
+    if (flat.length <= max)
+        return flat;
+    const cut = flat.slice(0, max - 1);
+    const lastSpace = cut.lastIndexOf(" ");
+    const body = lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut;
+    return `${body}…`;
+}
+const PATTERN_WIDTH = 44;
+export function formatCardTable(cards, now) {
+    return table(["score", "creator", "hook pattern", "validation", "lanes", "captured"], cards.map((c) => [
+        formatScore(c.viralScore),
+        c.creatorHandle ? `@${c.creatorHandle.replace(/^@+/, "")}` : "—",
+        truncate(c.hookPattern, PATTERN_WIDTH) || "(not extracted)",
+        c.validationStatus ?? "—",
+        laneCodes(c.lanes),
+        shortAge(c.capturedAt, now),
+    ]));
+}
+const EMPTY_LIST_LINES = [
+    "No hook cards match those filters.",
+    "Loosen a filter, or see everything:  exodus hooks list",
+];
+const NARROW_OR_EXPORT = "Narrow it with --days or --creator, or pull everything:  exodus hooks export --csv --out hooks.csv";
+export function formatList(walk, now) {
+    const { cards, more, scanCapped } = walk;
+    if (cards.length === 0) {
+        if (scanCapped) {
+            return [
+                `Nothing matched in the newest ~${LIST_SCAN_CAP} cards; older cards remain unscanned.`,
+                NARROW_OR_EXPORT,
+            ];
+        }
+        return [...EMPTY_LIST_LINES];
+    }
+    const count = `${cards.length} card${cards.length === 1 ? "" : "s"}`;
+    const lines = [formatCardTable(cards, now), ""];
+    if (scanCapped) {
+        lines.push(`${count}. Searched the newest ~${LIST_SCAN_CAP} cards; older cards remain unscanned.`);
+        lines.push(NARROW_OR_EXPORT);
+    }
+    else if (more) {
+        lines.push(`${count} — more available; raise --limit (max 200) or use \`exodus hooks export\`.`);
+    }
+    else {
+        lines.push(`${count}.`);
+    }
+    return lines;
+}
+function labelledHook(label, value) {
+    if (typeof value === "string" && value.trim()) {
+        return `  ${label.padEnd(11)}${value.trim()}`;
+    }
+    return `  ${label.padEnd(11)}(none extracted)`;
+}
+function corroborationLines(c, now) {
+    if (!c)
+        return ["  (no corroboration run yet)"];
+    const lines = [];
+    lines.push(`  replications: ${typeof c.replicationCount === "number" ? c.replicationCount : "—"}`);
+    const spread = Array.isArray(c.languageSpread)
+        ? c.languageSpread.join(", ")
+        : typeof c.languageSpread === "number"
+            ? String(c.languageSpread)
+            : "—";
+    lines.push(`  languages:    ${spread}`);
+    lines.push(`  markets:      ${Array.isArray(c.marketsSeen) && c.marketsSeen.length > 0 ? c.marketsSeen.join(", ") : "—"}`);
+    lines.push(`  checked:      ${typeof c.checkedAt === "number" ? shortAge(c.checkedAt, now) + " ago" : "never"}`);
+    return lines;
+}
+export function formatShow(card, now) {
+    const lines = [];
+    const handle = card.creatorHandle ? `@${card.creatorHandle.replace(/^@+/, "")}` : "(unknown creator)";
+    lines.push(`Hook card — ${handle}`);
+    if (card.sourceUrl)
+        lines.push(`url:       ${card.sourceUrl}`);
+    lines.push(`views:     ${formatCount(card.viewCount)}  (likes ${formatCount(card.likeCount)} · comments ${formatCount(card.commentCount)})`);
+    lines.push(`score:     ${formatScore(card.viralScore)}`);
+    if (card.scoreEvidence)
+        lines.push(`           ${card.scoreEvidence}`);
+    lines.push(`published: ${dateOrDash(card.publishedAt)} · captured ${shortAge(card.capturedAt, now)} ago`);
+    lines.push("");
+    lines.push("Hooks");
+    lines.push(labelledHook("spoken:", card.hookSpoken));
+    lines.push(labelledHook("on-screen:", card.hookOnScreen));
+    lines.push(labelledHook("caption:", card.hookCaption));
+    lines.push("");
+    lines.push("Pattern");
+    lines.push(`  pattern:   ${card.hookPattern ?? "(not extracted yet)"}`);
+    lines.push(`  skeleton:  ${card.formatSkeleton ?? "(not extracted yet)"}`);
+    lines.push("");
+    lines.push("Extraction");
+    lines.push(`  status:    ${card.extractStatus ?? "unknown"}`);
+    lines.push(`  evidence:  ${card.extractEvidence ?? "(none recorded)"}`);
+    lines.push("");
+    lines.push(`Validation — ${card.validationStatus ?? "unknown"}`);
+    lines.push(...corroborationLines(card.corroboration, now));
+    lines.push("");
+    lines.push("Lanes");
+    if (Array.isArray(card.lanes) && card.lanes.length > 0) {
+        for (const lane of card.lanes) {
+            lines.push(`  ${lane.lane ?? "?"} — ${lane.reason ?? "(no reason recorded)"}`);
+        }
+    }
+    else {
+        lines.push("  (no lane qualified this card)");
+    }
+    lines.push("");
+    lines.push("Gate");
+    if (card.gate && (card.gate.verdict || card.gate.reasoning)) {
+        lines.push(`  verdict:   ${card.gate.verdict ?? "—"}`);
+        lines.push(`  reasoning: ${card.gate.reasoning ?? "—"}`);
+        if (typeof card.gate.decidedAt === "number") {
+            lines.push(`  decided:   ${shortAge(card.gate.decidedAt, now)} ago`);
+        }
+    }
+    else {
+        lines.push("  (no gate decision recorded)");
+    }
+    lines.push("");
+    lines.push("Provenance");
+    lines.push(`  lifecycle:  ${card.lifecycle ?? "—"}`);
+    lines.push(`  discovered: ${card.discoveredVia ?? "—"}`);
+    lines.push(`  language:   ${card.language ?? "—"} · market ${card.market ?? "—"} · tag ${card.relevanceTag ?? "—"}`);
+    if (typeof card.velocityPollCount === "number") {
+        lines.push(`  velocity:   ${card.velocityPollCount} poll(s) recorded`);
+    }
+    if (card.citedStudy)
+        lines.push(`  cited:      ${card.citedStudy}`);
+    lines.push(`  id:         ${card.id ?? "—"} · shortcode ${card.shortcode ?? "—"}`);
+    if (card.hookPatternKey)
+        lines.push(`  patternKey: ${card.hookPatternKey}`);
+    lines.push("");
+    lines.push("Transcript");
+    if (typeof card.transcript === "string" && card.transcript.trim()) {
+        for (const line of card.transcript.trim().split("\n"))
+            lines.push(`  ${line}`);
+    }
+    else {
+        lines.push("  (no transcript captured)");
+    }
+    return lines.join("\n");
+}
+export function formatExplainScore(card, now) {
+    const lines = [];
+    lines.push(card.scoreEvidence?.trim() || "(this card carries no score evidence sentence)");
+    lines.push("");
+    lines.push(`score:              ${formatScore(card.viralScore)}`);
+    lines.push(`views:              ${formatCount(card.viewCount)}`);
+    lines.push(`creator's typical:  ${formatCount(card.creatorTypicalViews)}`);
+    lines.push(`baseline sample:    ${typeof card.baselineSampleSize === "number" ? `${card.baselineSampleSize} post(s)` : "—"}`);
+    if (card.baselineInsufficient) {
+        lines.push("                    ⚠ thin baseline — too few posts to trust this multiple yet.");
+    }
+    lines.push("");
+    lines.push("Lanes");
+    if (Array.isArray(card.lanes) && card.lanes.length > 0) {
+        for (const lane of card.lanes) {
+            lines.push(`  ${lane.lane ?? "?"} — ${lane.reason ?? "(no reason recorded)"}`);
+        }
+    }
+    else {
+        lines.push("  (no lane qualified this card)");
+    }
+    if (card.gate?.reasoning) {
+        lines.push("");
+        lines.push("Gate");
+        lines.push(`  ${card.gate.verdict ? `${card.gate.verdict} — ` : ""}${card.gate.reasoning}`);
+        if (typeof card.gate.decidedAt === "number") {
+            lines.push(`  decided ${shortAge(card.gate.decidedAt, now)} ago`);
+        }
+    }
+    return lines;
+}
+export function explainScoreJson(card) {
+    return {
+        id: card.id,
+        shortcode: card.shortcode,
+        viralScore: card.viralScore,
+        scoreEvidence: card.scoreEvidence,
+        viewCount: card.viewCount,
+        creatorTypicalViews: card.creatorTypicalViews,
+        baselineSampleSize: card.baselineSampleSize,
+        baselineInsufficient: card.baselineInsufficient,
+        lanes: card.lanes ?? [],
+        gate: card.gate,
+    };
+}
+export const CSV_COLUMNS = [
+    "id",
+    "shortcode",
+    "sourceUrl",
+    "creatorHandle",
+    "viralScore",
+    "scoreEvidence",
+    "viewCount",
+    "likeCount",
+    "commentCount",
+    "creatorTypicalViews",
+    "baselineSampleSize",
+    "baselineInsufficient",
+    "validationStatus",
+    "lanes",
+    "hookSpoken",
+    "hookOnScreen",
+    "hookCaption",
+    "hookPattern",
+    "formatSkeleton",
+    "extractStatus",
+    "language",
+    "market",
+    "lifecycle",
+    "discoveredVia",
+    "capturedAt",
+    "publishedAt",
+    "replicationCount",
+    "languageSpread",
+];
+const CSV_FORMULA_LEAD = /^[=+\-@\t\r]/;
+export function csvEscape(value) {
+    if (value === undefined || value === null)
+        return "";
+    const s = typeof value === "string" && CSV_FORMULA_LEAD.test(value) ? `'${value}` : String(value);
+    if (/[",\r\n]/.test(s))
+        return `"${s.replace(/"/g, '""')}"`;
+    return s;
+}
+function csvCell(card, column) {
+    switch (column) {
+        case "lanes":
+            return Array.isArray(card.lanes)
+                ? card.lanes.map((l) => l?.lane ?? "").filter(Boolean).join("|")
+                : "";
+        case "capturedAt":
+            return isoOrEmpty(card.capturedAt);
+        case "publishedAt":
+            return isoOrEmpty(card.publishedAt);
+        case "replicationCount":
+            return card.corroboration?.replicationCount;
+        case "languageSpread": {
+            const spread = card.corroboration?.languageSpread;
+            return Array.isArray(spread) ? spread.join("|") : spread;
+        }
+        default:
+            return card[column];
+    }
+}
+export const CSV_RECORD_SEP = "\r\n";
+export function toCsv(cards) {
+    const rows = [CSV_COLUMNS.join(",")];
+    for (const card of cards) {
+        rows.push(CSV_COLUMNS.map((col) => csvEscape(csvCell(card, col))).join(","));
+    }
+    return rows.join(CSV_RECORD_SEP);
+}
+function asErrorResult(res, json, deps) {
+    if (json) {
+        return { code: 1, lines: [JSON.stringify({ ok: false, status: res.status, data: res.data })] };
+    }
+    const lines = [formatApiError(res)];
+    if (res.status === 401 || res.status === 403) {
+        lines.push("");
+        lines.push(auth401Hint(deps.apiUrl()));
+    }
+    else if (res.status === 400 && /workspace|brand/i.test(lines[0])) {
+        lines.push("No active brand. Pick one first:  exodus brand use <slug>");
+    }
+    return { code: 1, lines };
+}
+function notFoundResult(ref, res, json) {
+    if (json) {
+        return { code: 1, lines: [JSON.stringify({ ok: false, status: res.status, data: res.data })] };
+    }
+    const server = formatApiError(res);
+    const lines = [`No hook card matches "${ref}".`];
+    if (server && server !== `HTTP ${res.status}`)
+        lines.push(server);
+    lines.push("Give a card id, an Instagram shortcode, or the reel URL — or browse: exodus hooks list");
+    return { code: 1, lines };
+}
+function errorFor(res, verb, json, deps, ref) {
+    if (res.ok)
+        return undefined;
+    const unsupported = missingRouteLine(res, verb, deps.channel);
+    if (unsupported)
+        return { code: 1, lines: [unsupported] };
+    if (res.status === 404 && ref !== undefined)
+        return notFoundResult(ref, res, json);
+    return asErrorResult(res, json, deps);
+}
+export async function listFlow(filters, json, deps) {
+    const limit = filters.limit ?? 50;
+    const cards = [];
+    let cursor;
+    let requested = 0;
+    let more = false;
+    let scanCapped = false;
+    let firstPage = true;
+    for (;;) {
+        const scanRemaining = LIST_SCAN_CAP - requested;
+        if (scanRemaining <= 0) {
+            scanCapped = true;
+            break;
+        }
+        const pageSize = Math.min(firstPage ? limit : EXPORT_PAGE_SIZE, scanRemaining);
+        firstPage = false;
+        requested += pageSize;
+        const res = await deps.get(`${LIST_PATH}${filterQuery(filters, { limit: pageSize, cursor })}`);
+        const err = errorFor(res, "hooks list", json, deps);
+        if (err)
+            return err;
+        const data = (res.data ?? {});
+        const page = Array.isArray(data.cards) ? data.cards : [];
+        let dropped = 0;
+        for (const card of page) {
+            if (cards.length >= limit) {
+                dropped++;
+                continue;
+            }
+            cards.push(card);
+        }
+        const exhausted = data.isDone !== false;
+        const next = data.cursor ?? undefined;
+        if (cards.length >= limit) {
+            more = dropped > 0 || (!exhausted && !!next);
+            break;
+        }
+        if (exhausted)
+            break;
+        if (!next)
+            break;
+        cursor = next;
+    }
+    if (json)
+        return { code: 0, lines: [JSON.stringify(cards)] };
+    return { code: 0, lines: formatList({ cards, more, scanCapped }, deps.now()) };
+}
+export async function showFlow(ref, json, deps) {
+    const res = await deps.get(`${SHOW_PATH}?ref=${encodeURIComponent(ref)}`);
+    const err = errorFor(res, "hooks show", json, deps, ref);
+    if (err)
+        return err;
+    const card = (res.data ?? {}).card;
+    if (!card)
+        return { code: 1, lines: [`No hook card matches "${ref}".`] };
+    if (json)
+        return { code: 0, lines: [JSON.stringify(card)] };
+    return { code: 0, lines: [formatShow(card, deps.now())] };
+}
+export async function explainScoreFlow(ref, json, deps) {
+    const res = await deps.get(`${SHOW_PATH}?ref=${encodeURIComponent(ref)}`);
+    const err = errorFor(res, "hooks explain-score", json, deps, ref);
+    if (err)
+        return err;
+    const card = (res.data ?? {}).card;
+    if (!card)
+        return { code: 1, lines: [`No hook card matches "${ref}".`] };
+    if (json)
+        return { code: 0, lines: [JSON.stringify(explainScoreJson(card))] };
+    return { code: 0, lines: formatExplainScore(card, deps.now()) };
+}
+export async function findSimilarFlow(ref, json, deps) {
+    const res = await deps.get(`${SIMILAR_PATH}?ref=${encodeURIComponent(ref)}`);
+    const err = errorFor(res, "hooks find-similar", json, deps, ref);
+    if (err)
+        return err;
+    const data = (res.data ?? {});
+    if (json)
+        return { code: 0, lines: [JSON.stringify(data)] };
+    const subject = data.card ?? {};
+    const similar = Array.isArray(data.similar) ? data.similar : [];
+    const handle = subject.creatorHandle
+        ? `@${subject.creatorHandle.replace(/^@+/, "")}`
+        : "(unknown creator)";
+    const lines = [];
+    lines.push(`Subject — ${handle}  ${formatScore(subject.viralScore)}`);
+    lines.push(`pattern: ${subject.hookPattern ?? "(not extracted yet)"}`);
+    if (subject.scoreEvidence)
+        lines.push(`         ${subject.scoreEvidence}`);
+    lines.push("");
+    if (similar.length === 0) {
+        lines.push("No other cards share this hook pattern.");
+        if (!subject.hookPattern) {
+            lines.push("This card has no extracted pattern yet, so there was nothing to match on — that's why the list is empty, not because the hook is one of a kind.");
+            lines.push("Check extraction:  exodus hooks show " + ref);
+        }
+        return { code: 0, lines };
+    }
+    lines.push(formatCardTable(similar, deps.now()));
+    lines.push("");
+    lines.push(similar.length === 1
+        ? "1 card shares this pattern."
+        : `${similar.length} cards share this pattern.`);
+    return { code: 0, lines };
+}
+export async function exportFlow(filters, options, deps) {
+    const cap = Math.min(filters.limit ?? EXPORT_CAP, EXPORT_CAP);
+    const cards = [];
+    let cursor;
+    let hitCap = false;
+    let more = false;
+    for (;;) {
+        const pageSize = Math.min(EXPORT_PAGE_SIZE, cap - cards.length);
+        if (pageSize <= 0) {
+            hitCap = true;
+            break;
+        }
+        const res = await deps.get(`${LIST_PATH}${filterQuery(filters, { limit: pageSize, cursor })}`);
+        const err = errorFor(res, "hooks export", options.format === "json", deps);
+        if (err)
+            return err;
+        const data = (res.data ?? {});
+        const page = Array.isArray(data.cards) ? data.cards : [];
+        for (const card of page) {
+            if (cards.length >= cap) {
+                hitCap = true;
+                break;
+            }
+            cards.push(card);
+        }
+        if (hitCap) {
+            more = true;
+            break;
+        }
+        if (data.isDone !== false)
+            break;
+        const next = data.cursor ?? undefined;
+        if (!next)
+            break;
+        cursor = next;
+    }
+    const body = options.format === "csv" ? toCsv(cards) : JSON.stringify(cards, null, 2);
+    const capNote = hitCap || more
+        ? `Stopped at ${cards.length} cards (export cap ${cap}) — there are more in the library. Narrow the filters to get the rest.`
+        : undefined;
+    if (options.out) {
+        const terminator = options.format === "csv" ? CSV_RECORD_SEP : "\n";
+        deps.writeFile(options.out, `${body}${terminator}`);
+        return {
+            code: 0,
+            lines: [`Wrote ${cards.length} hook card${cards.length === 1 ? "" : "s"} to ${options.out}.`],
+            warnings: capNote ? [capNote] : undefined,
+        };
+    }
+    return { code: 0, lines: [body], warnings: capNote ? [capNote] : undefined };
+}
+export function parsePositional(args = process.argv.slice(3)) {
+    const out = [];
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg.startsWith("--")) {
+            const key = arg.slice(2).split("=", 1)[0] ?? "";
+            if (!arg.includes("=") && VALUE_FLAGS.has(key))
+                i += 2;
+            else
+                i++;
+            continue;
+        }
+        out.push(arg);
+        i++;
+    }
+    return out;
+}
+export function resolveExportFormat(flags) {
+    const csv = flags["csv"] === true;
+    const json = flags["json"] === true;
+    if (csv && json) {
+        return { ok: false, message: "pass either --csv or --json to export, not both." };
+    }
+    if (!csv && !json) {
+        return { ok: false, message: "export needs an output shape: pass --csv or --json." };
+    }
+    return { ok: true, format: csv ? "csv" : "json" };
+}
+function printResult(result) {
+    for (const line of result.lines)
+        console.log(line);
+    for (const warning of result.warnings ?? [])
+        console.error(warning);
+    if (result.code !== 0)
+        process.exit(result.code);
+}
+function usageError(message, usage) {
+    console.error(`Error: ${message}`);
+    console.log(`Usage: ${usage}`);
+    process.exit(1);
+}
+export async function run(flags) {
+    const positional = parsePositional();
+    const [sub, ...rest] = positional;
+    const json = flags["json"] === true;
+    if (!sub || sub === "help") {
+        console.log(helpText);
+        return;
+    }
+    if (sub === "list") {
+        const parsed = parseHookFilters(flags, 200);
+        if (!parsed.ok)
+            usageError(parsed.message, "exodus hooks list [filters] [--limit n] [--json]");
+        return printResult(await listFlow(parsed.filters, json, defaultDeps));
+    }
+    if (sub === "show" || sub === "explain-score" || sub === "find-similar") {
+        const ref = rest[0];
+        if (!ref)
+            usageError(`hooks ${sub} needs a card id, shortcode, or Instagram URL.`, `exodus hooks ${sub} <ref> [--json]`);
+        if (sub === "show")
+            return printResult(await showFlow(ref, json, defaultDeps));
+        if (sub === "explain-score")
+            return printResult(await explainScoreFlow(ref, json, defaultDeps));
+        return printResult(await findSimilarFlow(ref, json, defaultDeps));
+    }
+    if (sub === "export") {
+        const format = resolveExportFormat(flags);
+        if (!format.ok) {
+            usageError(format.message, "exodus hooks export --csv|--json [filters] [--out <file>]");
+        }
+        const parsed = parseHookFilters(flags, EXPORT_CAP);
+        if (!parsed.ok) {
+            usageError(parsed.message, "exodus hooks export --csv|--json [filters] [--out <file>]");
+        }
+        const out = typeof flags["out"] === "string" ? flags["out"] : undefined;
+        return printResult(await exportFlow(parsed.filters, { format: format.format, out }, defaultDeps));
+    }
+    console.error(`Unknown subcommand: "${sub}"\n`);
+    console.log(helpText);
+    process.exit(1);
+}

package/dist/commands/keys.js

@@ -27,6 +27,7 @@ const PROVIDER_LABEL = {
     imgflip: "Imgflip",
     scrapecreators: "ScrapeCreators",
     apify: "Apify",
+    browserbase: "Browserbase",
 };
 async function status() {
     let remote;

package/dist/lib/keys-sync.js

@@ -12,6 +12,7 @@ export const SERVER_RESOLVED_PROVIDERS = new Set([
     "imgflip",
     "scrapecreators",
     "apify",
+    "browserbase",
 ]);
 export async function fetchRemoteKeys() {
     const res = await apiGetDashboard("/api/settings/keys");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicopycoders/exodus",
-  "version": "2026.8.1600",
+  "version": "2026.9.200",
   "description": "CLI + Claude Code skills for the Copycoders Exodus ad pipeline",
   "repository": {
     "type": "git",