@aicopycoders/exodus 2026.6.2700-beta.2 → 2026.6.2900-beta.4

package/assets/docs/CLAUDE.md

@@ -0,0 +1,125 @@
+# Creative Strategy Workspace
+
+> **New here?** Your onboarding home is the Exodus dashboard (Settings → Claude Code) — it walks you through install and keys. If anything's broken at runtime, run `npx @aicopycoders/exodus doctor` from this directory — it diagnoses local and dashboard-side issues in one shot.
+
+This is a creative-strategy workspace operated by the **exodus** CLI. It is brand-agnostic infrastructure serving **all of the account's brands**: each brand has its own subfolder here (marked by a `.exodus-brand.json` file) holding that brand's `state/` and `output/`. Which brand you're working on resolves **folder first, pointer second**: commands run from inside a brand's subfolder target that brand automatically; otherwise the `npx @aicopycoders/exodus brand use <slug>` pointer applies. (Older single-brand installs keep `state/` and `output/` at this root — same rules, one brand.)
+
+**How to engage the system:** every skill here is namespaced `exodus-*`, and a front-door `exodus` hub skill routes generic asks. Members say "exodus" to engage ("exodus, write me some ads") or invoke a specific skill with `/exodus-<name>` (e.g. `/exodus-write`). This namespacing is deliberate: it lets these skills coexist with other skill packs (like the workshop pack) installed in the same folder, and it keeps the bare word "Genesis" unambiguous — on its own, "Genesis" always means the member's own Genesis API key/recipes, never Exodus. CLI commands are unchanged (`npx @aicopycoders/exodus genesis`, `npx @aicopycoders/exodus brand use`, etc.).
+
+The strategist persona, the Luke Mills / Genesis frameworks, the operating rules and creative principles, and the operating discipline all live in **one skill** plus its references:
+
+- `.claude/skills/exodus-strategist/SKILL.md` — the single always-on creative-strategy skill: persona, operating rules, creative principles, red flags, active-brand resolution, the quality bars, and a **Framework Index** that routes to the depth below
+- `references/` — the framework depth, consulted from the skill when needed: `creative-strategy.md` (the encyclopedia + Genesis bot catalog), `segments.md`, `copy-blocks.md` (P3C2), `cast-video.md` (CAST), `iterations.md` (CASHED), `editing-rules.md`, `scrawls.md`, `hook-quality-checklist.md`, `awareness-framework.md`
+
+If the persona isn't firing for you, check that the skill loaded. It is not optional reading.
+
+---
+
+## Two systems in this folder: Exodus (automatic) + Genesis (manual)
+
+This folder usually holds **two related products that share the same Genesis engine** — keep them straight. Think of it as a car: same engine underneath, two ways to drive it.
+
+- **Exodus — the automatic transmission.** This workspace: the `exodus-*` skills and the `npx @aicopycoders/exodus` CLI. Pre-built, done-for-you pipelines (write, image, idea bank, brand onboarding) that drive the Genesis bots *for* you against your brand. You engage it by saying **"exodus"** ("exodus, write me some ads"). Its keys are `EXODUS_API_KEY` / `EXODUS_API_URL` in `.env`; Genesis access is internal — there's nothing to configure or debug about Genesis for Exodus to work.
+
+- **Genesis (standalone) — the manual transmission.** A separate skill at `.claude/skills/genesis-bots` that calls the *same* Genesis copywriting / research / strategy bots **directly** with the member's own `gen_` key — you pick a bot and prompt it yourself. It reads `GENESIS_API_KEY` plus a provider key (`ANTHROPIC_API_KEY` or `OPENROUTER_API_KEY`) from `.env`. This is the member's own workflow, **not** owned by the `exodus-*` skills. (It may not be installed in every folder — check for the `genesis-bots` skill.)
+
+**Routing rule:** "exodus …" → the Exodus pipelines below. Bare **"genesis"**, "run the bots", or a named bot slug → the `genesis-bots` skill (the member's direct workflow — never route it into Exodus). If someone clearly just wants ads and doesn't know which system they have, ask one question — "drive the Genesis bots directly, or run an Exodus pipeline?" — rather than guessing.
+
+**Provider key:** the manual Genesis bots need a provider key in `.env`. `npx @aicopycoders/exodus keys pull` syncs your dashboard provider + image keys down for you (the install runs it; safe to re-run anytime keys change). Exodus's own pipelines don't need it locally — they run server-side.
+
+---
+
+## Multi-Brand Operating Notes
+
+Any user can create and own unlimited brands — `npx @aicopycoders/exodus brand create "<name>"` (or the dashboard); it is NOT admin-only, and brand names are scoped per user (two users can each have a "Matt Beard"). One account key then switches across every brand the user owns (admins: every brand). The only exception is a brand someone ELSE invited the user into — they don't own it, so their key stays pinned to just that one. Never tell a user they can't make brands or are "locked to one brand" just because their key shows `role: member`. The active brand resolves **folder > pointer > key default**: being inside a brand's subfolder wins, then the `brand use` pointer, then the key's default brand.
+
+- **Identify the active brand:** `npx @aicopycoders/exodus brand current` (also says whether it came from the folder or the pointer)
+- **List accessible brands:** `npx @aicopycoders/exodus brand list`
+- **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
+- **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.
+
+---
+
+## Available Pipelines
+
+### Exodus pipelines (automatic)
+
+These are the **Exodus** pipelines — the automatic system that drives the Genesis bots for you. Use them to generate and analyze creative. Each has its own skill directory in `.claude/skills/`. Invoke them by saying "exodus" plus what you want, or directly with `/exodus-<name>`.
+
+| Pipeline | Skill | When to Use |
+|----------|-----------|-------------|
+| **Write** | `exodus-write` | **Start here for copywriting.** Say what you want ("exodus, write me some ads"); it routes new-brand → foundation → brief → genesis → Doc and sequences the whole flow. |
+| **Genesis** | `exodus-genesis` | Brief → ad copy in two voices (Mario + Infeed). Default 1 pass = 2 variants; scale with `--passes` (pass 2 adds the Top-Ads-biased primer). Also writes from a pasted reel (`--reel`). |
+| **Idea** | `exodus-idea` | The Idea Bank — capture reels/brain-dumps/swipes into formed ideas, curate them, then write the keepers through Genesis. Use when collecting and curating ideas rather than writing one ad on the spot. |
+| **Image** | `exodus-image` | **Start here for static images.** Say what you want; it reads the request and routes to the right engine — `exodus-creative` (renders from copy) or `exodus-template` (33 ad-type formats). |
+| **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 33 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. |
+| **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) |
+
+For the operator-facing quick reference on how to invoke these in Claude Code, see `PIPELINES.md` in the workspace root.
+
+### Genesis bots (manual)
+
+The same folder usually also carries **`genesis-bots`** — the *manual* way to drive the same Genesis bots. You pick a bot and prompt it yourself with the member's own `gen_` key, chaining bots by hand (buyer profile → creative brief → ad hooks → ads). It is **not** an `exodus-*` skill and is **never** invoked by saying "exodus".
+
+| Skill | When to Use |
+|-------|-------------|
+| `genesis-bots` | The user says bare **"genesis"**, "run the bots", "openclaw", or names a bot slug, and wants to call a Genesis copywriting / research / strategy / image-prompt bot directly. Needs `GENESIS_API_KEY` plus a provider key (`ANTHROPIC_API_KEY` or `OPENROUTER_API_KEY`) in `.env` — see **Dashboard** below. May not be installed in every folder — check for the skill directory before assuming it's there. |
+
+Route a bare-"genesis" ask to this skill and an "exodus …" ask to the pipelines above — never cross the two. If someone clearly just wants ads and doesn't know which system they have, ask one question ("drive the Genesis bots directly, or run an Exodus pipeline?") rather than guessing.
+
+---
+
+## Awareness Level Routing
+
+Every ad targets an audience at a specific awareness level. Getting this right is one of the highest-leverage decisions in creative strategy.
+
+> `--awareness` sets the audience awareness level for a Genesis run (unaware / problem-aware / solution-aware / product-aware). Pick the level the idea is actually written for.
+
+| Level | Audience State | Ad Approach |
+|-------|---------------|-------------|
+| **Unaware** | Doesn't know they have a problem | Shock, pattern interrupt, reveal |
+| **Problem-Aware** | Knows the problem, not the solution | Educate, validate, agitate |
+| **Solution-Aware** | Knows solutions exist, not ours | Compare, differentiate, position |
+| **Product-Aware** | Knows the brand, hasn't bought yet | Offer, urgency, social proof |
+
+Routing detail and signal patterns live in `.claude/skills/exodus-strategist/SKILL.md` and `references/creative-strategy.md`.
+
+---
+
+## Dashboard
+
+This workspace connects to a live dashboard for:
+- Settings management (defaults, account connections)
+- **Pipeline keys** — your provider LLM key (Anthropic or OpenRouter) plus Kie.ai, entered once in Settings → Pipeline Keys
+- Google Drive credentials (where outputs are saved)
+- Run history and output retrieval
+- Ad account connections (e.g. the Genesis top-ads-biased track)
+- Brand admin (switching, profile management)
+
+The dashboard URL and your `EXODUS_API_KEY` live in `.env`.
+
+**Keys & setup.** Exodus's own pipelines run server-side and need nothing beyond `EXODUS_API_KEY` — there's no provider key to configure for them. The **manual `genesis-bots` path** (and other local tools) *do* need a provider key in `.env`. Enter your keys once in the dashboard, then pull them down:
+
+- `npx @aicopycoders/exodus keys pull` — writes your dashboard provider + Kie.ai keys into `.env` (the install runs this for you; safe to re-run anytime a key changes). It only upserts the keys and preserves the rest of the file.
+- `npx @aicopycoders/exodus keys status` — shows which keys are set in the dashboard vs locally. Values are never printed.
+
+---
+
+## Reviewing Run Output
+
+When you need to review a run's creative output, always read it via `npx @aicopycoders/exodus read-doc <runId>`. This walks every tab of the Google Doc and gives you the full output as markdown.
+
+Do **not** use the Drive MCP as your first choice — it only sees tab 1 and will misreport the run as empty. If `npx @aicopycoders/exodus read-doc` exits with code 2 (`unavailable`), fall back to the Drive MCP using the URL printed by the command, and warn the user in your summary that you only saw tab 1.
+
+---
+
+## Tool Feedback
+
+This workspace is also a testbed for the CLI and pipelines. When you run a pipeline and hit a gap — a missing input, missing output, missing filter, awkward flow — log it per the **Tool Feedback Protocol** in `.claude/skills/exodus-strategist/SKILL.md`. Your feedback drives the next round of pipeline improvements.

package/assets/docs/PIPELINES.md

@@ -0,0 +1,202 @@
+# Pipelines Cheat Sheet
+
+In Claude Code you don't click buttons. You say **"exodus"** plus what you want — "exodus, write me some ads" — and the `exodus` hub skill routes you to the right pipeline. You can also invoke a specific skill directly with a slash command: `/exodus-write`, `/exodus-image`, etc.
+
+> This doc is the CLI/skill invocation reference for the active brand workspace. For the dashboard's clickable pipeline list, see the dashboard's Creative Suite.
+
+## All skills at a glance
+
+| Skill | What it does |
+|-------|--------------|
+| exodus-write | The front door — routes brand → foundation → brief → Genesis → Doc. Start here. |
+| exodus-genesis | Brief → Ad Copy (two voices; 1 pass = 2 variants, scalable via --passes) |
+| exodus-image | The front door for static images — routes to exodus-creative or exodus-template. Start here for "make me images / statics". |
+| exodus-creative | Creative-Suite Engines (native / copy-derived / ref-match) — when you've already picked an engine |
+| exodus-template | Ad-Type Format Variations across 33 structured formats |
+| exodus-meme | Meme Ad Generator — recommend formats, one batched server-side run |
+| exodus-browse | View History and Surface the Right Run |
+| exodus-drive | Google Drive, Docs, Sheets via the Dashboard's OAuth |
+
+---
+
+## exodus-write (start here)
+
+**What it does:** The guided front door for copywriting. You don't need to know which command to run — say "exodus" plus what you want and the exodus-write flow figures out where you are, helps shape the brief, sets up your foundation if needed, runs Genesis, and hands back the Google Doc.
+
+```operator-guide
+No command — say "exodus" plus what you want (or /exodus-write). It sequences
+the existing commands (foundation, genesis, browse, read-doc) for you.
+
+Say things like:
+  "exodus, I want to write some ads: <your idea>"
+  "exodus, turn this winning ad into copy: <paste>"
+  "exodus, set up a new brand and write my first ad"
+  "exodus, make a variant of that last run"
+
+Routing:
+  new brand / no foundation → onboarding (foundation, optional primer prompt)
+  brief or idea in hand      → straight to the Genesis writing pass
+  rerun / tweak              → browse past runs + the editing menu
+Works without a primer (defaults); sharper once your foundation has winning examples.
+```
+
+---
+
+## exodus-genesis
+
+**What it does:** Take a brief through Luke's full Genesis writing process — two voices (Mario × Brand + Infeed × Brand). Default is 1 pass per bot = 2 variants; add `--passes` to widen coverage (pass 2 brings in the Top-Ads-biased primer). Also accepts per-run seeds extracted from a source ad.
+
+```operator-guide
+Inputs:
+  --brief <file|"text"> (required) — path to a text file OR an inline brief string
+Optional:
+  --seeds <file|"text"> — per-run creative seeds (file: one per line or JSON array; inline: one string)
+  --awareness — unaware | problem-aware (default) | solution-aware | product-aware
+  --passes <n> — writing passes per bot (1–5, default 1). 1 pass = 2 variants
+                 (1 Mario×Brand + 1 Infeed×Brand); pass 2 adds the Top-Ads-biased primer
+  --variants <n> — advanced: raw total count (1–10) that overrides --passes
+  --ad-account <id> — Meta ad account for the top-ads-biased track (defaults to first active account)
+  --no-wait — return immediately with the run ID
+Returns: Google Doc URL printed to stdout when the run completes
+Examples:
+  exodus genesis run --brief brief.txt --seeds seeds.txt
+  exodus genesis run --brief "Grounding sheets help joint pain" --awareness problem-aware --passes 2
+```
+
+---
+
+## exodus-image (start here for statics)
+
+**What it does:** The front door for static image ads. Just say "exodus" plus what
+you want — "exodus, make me some statics from this ad", "exodus, render AD-001" —
+and Claude reads the request and runs the right engine: **exodus-creative**
+(renders straight from copy, or matches a reference image) or **exodus-template**
+(one piece of copy spread across 33 ad-type formats). You don't pick the engine;
+the request decides it. Use the engines below directly only when you already know
+exactly which one you want.
+
+**Say something like:** "exodus, make me some image ads from this copy" · "exodus,
+render this ad as statics" · "exodus, spread AD-001 across ad formats" · "exodus,
+make ads that look like this library image".
+
+---
+
+## exodus-creative
+
+**What it does:** Generate static creative images through the creative-suite engines — native (render image ads straight from ad copy), copy-derived (renders derived from copy variations), and ref-match (match the look of one or more reference images you've uploaded to the library).
+
+```operator-guide
+Subcommands:
+  exodus creative native --ad "<text>" [options]         Render image ads from ad copy
+  exodus creative copy-derived --ad "<text>" [options]   Renders derived from copy variations
+  exodus creative ref-match --refs <id,id,...> [options] Match the look of reference image(s)
+  exodus creative status --id <runId>                    Poll a run
+
+Shared options (kickoffs):
+  --variations N        Renders to generate (default: engine-specific)
+  --aspect 1:1|4:5|9:16   Image aspect ratio (default: 1:1)
+  --name "<label>"      Custom run name (otherwise auto-generated)
+  --ad-group <id>       Attach to an existing ad-group
+
+ref-match additional options:
+  --refs <id,id,...>    REQUIRED. Comma-separated creativeSuiteImages ids
+                        (the images must already be in the dashboard library)
+  --subject "<text>"    Optional subject hint
+  --objects <id,id,...> Optional object-overlay image ids
+
+Returns: runId + dashboard URL (/creative-suite/runs/<runId>).
+Status: `exodus creative status --id <runId>` → engine, status, completed/total, isTerminal.
+Auth: Bearer (kickoff via Convex HTTP; status via dashboard route).
+```
+
+---
+
+## exodus-template
+
+**What it does:** Turn finished ad copy into many static ad images spread across structured ad-type formats (testimonial, hero, UGC, logo, infographic, and 28 more). Runs Fernando's 5-stage Template pipeline — give it one brief or a numbered list of ads and it generates format variations, then renders them.
+
+```operator-guide
+Subcommands:
+  exodus template run --input "<text>" [options]   Kick off a run
+  exodus template resume --id <runId>              Finalize an orphaned run (#56)
+  exodus template ad-types                          Print the 33 AD_TYPES
+  exodus template reptile-triggers                  Print the 13 reptile triggers
+
+run options:
+  --input "<text>"      REQUIRED. One brief, or a numbered list of finished ads
+                        ("1. <ad copy> 2. <ad copy> ..."). Min 3 chars.
+  --mode auto|manual|hybrid   Generation mode (default: auto)
+  --render-mode images|prompts   prompts = skip render, return LLM prompts only (default: images)
+  --aspect 1:1|9:16     Image aspect ratio (default: 1:1)
+  --model gpt-image-2|nano-banana-pro   Kie.ai model (default: gpt-image-2)
+  --realism off|realistic   Realism enforcement (default: off)
+  --quantities "slug:N,slug:N"   manual-mode per-type counts (e.g. "testimonial:3,hero:2")
+  --pairings '<JSON>'   hybrid-mode host/modifier pairs: '[{"host":"testimonial","modifier":"hero"}]'
+  --requested-count N   auto-mode total render target (optional)
+
+Returns:
+  runId + dashboard URL. POST-only — there is NO CLI status endpoint yet.
+  Live progress renders in the dashboard at /creative-suite/template/sessions/<runId>.
+```
+
+---
+
+## exodus-meme
+
+**What it does:** Generate meme-style ad creative for the active brand — recommends meme formats for a brief, then renders the whole batch server-side in one run (AI image memes via Kie.ai, classic Imgflip-template memes on the member's Imgflip login).
+
+```operator-guide
+Subcommands:
+  exodus meme recommend --brief "<text>" [--avatar "<text>"]
+  exodus meme run --brief "<text>" --formats '<json>' [--avatar "<text>"] [--name "<label>"]
+  exodus meme regenerate --brief "<text>" --layer 1|2|3 <format fields> [--hint "<text>"] [--id <runId>]
+
+Typical flow:
+  1. recommend  → { recommendations: [...] } — 15 picks (5 per layer) with
+                  name, layer, reasoning, ad_angle. Layer 1 = classic Imgflip
+                  templates; layers 2/3 = AI-image formats.
+  2. run        → pass the picked recommendation objects straight into
+                  --formats (JSON array, 1–50). One enqueue; the batch renders
+                  server-side via Trigger.dev — closing the session won't kill it.
+  3. poll       → exodus status --id <runId> --type creative
+                  (terminal: complete | partial-error | error)
+  4. regenerate → re-render a single miss (layer 1: --template-id
+                  --template-name --boxes; layer 2/3: --format [--hint]).
+
+Keys (strict BYOK, preflighted server-side): classic memes need the member's
+Imgflip login; AI memes need their Kie.ai key; captions always need an LLM key.
+Returns: runId + dashboard URL /creative-suite/runs/<runId> (results land in the library).
+```
+
+---
+
+## exodus-browse
+
+**What it does:** View past pipeline runs and pull outputs from previous sessions.
+
+```operator-guide
+Inputs:
+  none required — defaults to recent runs across all pipelines
+Flags:
+  --limit (default: 20) — max runs to list
+  --agent — filter by agent: genesis | creative | template | meme
+Returns: terminal table of recent runs with timestamps, agents, statuses, and Doc URLs
+```
+
+---
+
+## exodus-drive
+
+**What it does:** Read and write Google Drive / Docs / Sheets via the dashboard's existing OAuth, using `npx @aicopycoders/exodus drive` subcommands.
+
+```operator-guide
+Subcommands (use the one that matches intent):
+  get-doc <docId>             Read a Google Doc by ID
+  get-sheet <sheetId>         Read a spreadsheet range
+  list-files                  Search/list Drive files
+  create-doc <title>          Create a new Google Doc
+  batch-update <docId>        Apply Docs API requests (insertText, etc.)
+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)
+```

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

@@ -1,6 +1,6 @@
 ---
 name: exodus-genesis
-description: Run the standalone Exodus Genesis pipeline — Luke's full writing process across two voices (MarioBot + Infeed VSL) on the brand primer. The default is one pass per bot = 2 variants (1 Mario × Brand + 1 Infeed × Brand); the user can run more passes to widen coverage and bring in the Top-Ads-Biased primer. Includes the per-variant editing menu (Natural Language / Shorten / Cut / Simplify / Make Better). `--reel` also writes ads on the spot from a pasted Instagram/TikTok reel — it transcribes the reel into an idea and writes it through this same writer (just another input, nothing custom); to COLLECT reels/ideas into a bank to curate before writing, that's the `exodus-idea` skill. Only invoke when the user has explicitly invoked Exodus: they said "exodus" in the request ("run the exodus genesis pipeline", "exodus, run another pass", "exodus, make me ads from this reel"), named this skill or /exodus-genesis, ran an `npx exodus` command, or the `exodus` hub skill routed here. Never claim generic requests ("run the Genesis pipeline", "write ads from this reel") — 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. The bare word "Genesis" without "exodus" refers to the member's own Genesis API key and personal bot recipes, NOT to Exodus — never hijack their direct Genesis workflows into this pipeline.
+description: Run the standalone Exodus Genesis pipeline — Luke's full writing process. Hooks come from the dedicated new-hook-bot (a single ~10-hook pool); the human hook gate then lets the user review and pick those hooks RIGHT IN CLAUDE CODE (the primary venue; dashboard is ad-hoc) — each pick becomes one ad — or auto-pick and write straight through. Body copy is written across two voices (MarioBot + Infeed VSL) on the brand primer; in auto mode the default is one pass per bot = 2 variants and more passes widen coverage / bring in the Top-Ads-Biased primer (passes don't apply in manual mode). Includes the per-variant editing menu (Natural Language / Shorten / Cut / Simplify / Make Better). `--reel` also writes ads on the spot from a pasted Instagram/TikTok reel — it transcribes the reel into an idea and writes it through this same writer (just another input, nothing custom); to COLLECT reels/ideas into a bank to curate before writing, that's the `exodus-idea` skill. Only invoke when the user has explicitly invoked Exodus: they said "exodus" in the request ("run the exodus genesis pipeline", "exodus, run another pass", "exodus, make me ads from this reel"), named this skill or /exodus-genesis, ran an `npx exodus` command, or the `exodus` hub skill routed here. Never claim generic requests ("run the Genesis pipeline", "write ads from this reel") — 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. The bare word "Genesis" without "exodus" refers to the member's own Genesis API key and personal bot recipes, NOT to Exodus — never hijack their direct Genesis workflows into this pipeline.
 ---
 
 ```operator-guide
@@ -19,14 +19,21 @@ Optional:
 Returns:
   Google Doc with one tab per variant (Headlines + Hook + Body Copy)
   Per-variant editing menu surfaced on the dashboard run page
+
+Hook gate (manual mode — review hooks in Claude Code):
+  on pause the run prints a numbered hook pool, then:
+  genesis continue   --id <runId> --hooks 1,3,5       write the picked hooks (one ad each)
+  genesis regenerate --id <runId> [--steering "…"]    re-roll the pool (reject + steer)
+  genesis hooks      --id <runId>                      re-print the pool (fresh-session resume)
 ```
 
 # Genesis — Brief + Seeds → Mario + Infeed Variants → Editing Menu
 
 Luke's full Ad Writing Process end-to-end:
 
-- Two parallel hook voices (MarioBot + InfeedVSL) producing ~40 hooks total
-- Body-copy variants in two voices, **scaled by passes**:
+- Hook generation from the dedicated **new-hook-bot** (single source, ~10 strategically
+  ordered hooks) — the pool the user reviews at the hook gate
+- Body-copy variants in two voices, **scaled by passes** (auto mode):
   - **Mario × Brand primer** — established brand voice
   - **Infeed × Brand primer** — InfeedVSL voice on the same brand reference
   - **Top-Ads-Biased** — primed with the brand's actual top performers (CTR × spend),
@@ -41,9 +48,11 @@ How Much Coverage* below).
 
 > If the user hasn't named the pipeline specifically and just wants Exodus to "write some ads,"
 > start from the `exodus-write` skill — it walks brand → foundation → brief → here, and it owns the passes menu.
-> This skill owns the run once the brief, awareness, and pass count are settled. If the user
-> invoked Genesis directly and didn't say how many, surface the same quick passes menu (default
-> 1 pass = 2 variants, recommended) before firing — don't silently assume a big run.
+> This skill owns the run once the brief, awareness, and (in auto mode) pass count are settled.
+> **In manual mode the passes question disappears** — the ad count equals the number of hooks the
+> user picks, so don't ask "how many passes?" Passes only apply to **auto** mode (default 1 pass =
+> 2 variants, recommended); if the user is in auto and didn't say how many, surface the quick passes
+> menu before firing — don't silently assume a big run.
 
 ## Workflow
 
@@ -95,37 +104,77 @@ Save to `/tmp/genesis-seeds.txt` (one per line, `#` comments allowed), or pass `
 # Resolve hook mode FIRST (see "Hook selection mode" below) — these commands
 # assume a saved default exists, else add --stop-at-hooks or --auto-hooks or they error.
 
-# Default — 1 pass per bot = 2 variants (1 Mario × Brand + 1 Infeed × Brand):
-npx @aicopycoders/exodus genesis run --brief "<brief>" --awareness <level>
-
-# More coverage — 2 passes = 4 variants (adds the Top-Ads-Biased pass):
-npx @aicopycoders/exodus genesis run --brief "<brief>" --awareness <level> --passes 2
-
-# With seeds:
-npx @aicopycoders/exodus genesis run --brief "<brief>" --seeds /tmp/genesis-seeds.txt --awareness <level> --passes 2
-
-# Manual hook selection — pause after hook generation:
+# Manual (default) — pause so the user picks hooks IN CLAUDE CODE; one ad per pick.
+# Passes do NOT apply in manual mode (ad count = hooks chosen):
 npx @aicopycoders/exodus genesis run --brief "<brief>" --awareness <level> --stop-at-hooks
 
-# Force auto-select (overrides a saved "manual" preference):
+# Auto — auto-pick the top N hooks (N = passes default) and write straight through:
 npx @aicopycoders/exodus genesis run --brief "<brief>" --awareness <level> --auto-hooks
+
+# Auto, more coverage — 2 passes = 4 variants (adds the Top-Ads-Biased pass):
+npx @aicopycoders/exodus genesis run --brief "<brief>" --awareness <level> --auto-hooks --passes 2
+
+# With seeds:
+npx @aicopycoders/exodus genesis run --brief "<brief>" --seeds /tmp/genesis-seeds.txt --awareness <level> --stop-at-hooks
 ```
 
-`--brief` accepts inline text or a file path. `--passes <n>` (1–5) is the friendly knob; `--variants <n>` (1–10) is an advanced raw-total override that wins if both are given.
+`--brief` accepts inline text or a file path. `--passes <n>` (1–5) is the friendly knob (auto mode only); `--variants <n>` (1–10) is an advanced raw-total override that wins if both are given.
 
 **Hook selection mode — REQUIRED gate before EVERY run (do not skip):**
-The pipeline can pause after hook generation so the user picks which hooks become body copy — the human quality gate. You MUST resolve the mode **before** firing a run. A `genesis run` with **no** `--stop-at-hooks`/`--auto-hooks` **and** no saved preference now **hard-errors** (`Hook-selection preference not set`) **by design** — so the gate can't be silently skipped. If you see that error, you skipped this step; do it now.
+The pipeline can pause after hook generation so the user picks which hooks become body copy — the human quality gate, and **reviewing those hooks right here in Claude Code is the primary venue** (the dashboard is an ad-hoc escape hatch). You MUST resolve the mode **before** firing a run. A `genesis run` with **no** `--stop-at-hooks`/`--auto-hooks` **and** no saved preference now **hard-errors** (`Hook-selection preference not set`) **by design** — so the gate can't be silently skipped. If you see that error, you skipped this step; do it now.
 
 Resolve it in this order, every time, BEFORE you run:
 1. **Check the saved default:** run `npx @aicopycoders/exodus genesis hook-pref` (no argument). It prints `manual`, `auto`, or `unset` on the first line.
-2. **If it prints `manual` or `auto`:** just fire the run — the saved default applies, no flag needed.
-3. **If it prints `unset`:** STOP and ask the user once, plainly — *"Want to choose the hooks yourself before I write the copy, or have me auto-pick and write straight through?"* Then fire the run with the matching flag (`--stop-at-hooks` = they choose, `--auto-hooks` = auto), and after it starts, offer to save it as their default so you never ask again: `npx @aicopycoders/exodus genesis hook-pref <manual|auto>`. **Do NOT fire the run before they answer.**
+2. **If it prints `manual` or `auto`:** just fire the run — the saved default applies, no flag needed. (`manual` = review the hooks here in Claude Code.)
+3. **If it prints `unset`:** STOP and ask the user once — **mode only, two options, in-Claude-Code first:**
+   > ① **Show me the hooks here — I'll pick** (review in Claude Code) · ② **Just write the ads — auto-pick the hooks**
+   > *(Prefer the dashboard? Say so and I'll give you the link.)*
+
+   Don't ask "how many passes?" in this question — that only matters in auto mode. Fire the run with the matching flag (`--stop-at-hooks` = ①, `--auto-hooks` = ②). **Do NOT fire the run before they answer.** Then, **after** the run kicks off (a separate step), ask **once** whether to save it as the default so you never ask again: `npx @aicopycoders/exodus genesis hook-pref <manual|auto>`. (Only `manual`/`auto` are savable — never save "dashboard".)
 
 Flags:
-- **`--stop-at-hooks`** — pause after hook generation. The run lands in `awaiting_hook_selection` and the CLI prints a dashboard URL; the user picks hooks on the run-detail page and the pipeline continues automatically to body copy.
-- **`--auto-hooks`** — auto-pick the strongest hooks and write straight through (also overrides a saved "manual" default for this one run).
+- **`--stop-at-hooks`** — manual: pause after hook generation. The run lands in `awaiting_hook_selection` and **the CLI prints the hook pool as a numbered list** (see *Manual hook selection* below). Picking resumes the pipeline to body copy; rejecting re-rolls the pool (`regenerate`).
+- **`--auto-hooks`** — auto: pick the top N hooks in bot order and write straight through (also overrides a saved "manual" default for this one run). Stay silent — just deliver the Doc.
+
+### 3b. Manual hook selection — review and pick IN CLAUDE CODE
+
+When a manual run pauses, the `run` command prints the generated pool as a flat numbered list. Surface it to the user **verbatim — hook text only, numbered.** Do **not** add ratings, tags, voice labels, or your own opinion about which hooks are best; the user picks.
+
+```
+⏸  Paused for hook selection (10 hooks).
+
+  1. <hook text>
+  2. <hook text>
+  …
+```
+
+Then the user does one of two things — **pick** or **re-roll**:
+
+**A. Pick the hooks to write:**
+1. Ask the user which hooks to write — **by number ("1, 3, 5") or in natural language** ("the first one and the curiosity one about cortisol"). Resolve any natural-language reference to the actual hook numbers yourself.
+2. Each pick becomes one ad. If the user picks **more than 10**, warn and confirm before continuing — the pipeline caps at 10 and would drop the rest; don't let that happen silently.
+3. Write the chosen hooks:
+   ```bash
+   npx @aicopycoders/exodus genesis continue --id <runId> --hooks 1,3,5
+   ```
+   This resumes the run (one ad per hook) and polls to the Doc.
+
+**B. Reject the pool and re-roll (regenerate):** when the user says "these all suck, try again" — optionally with direction ("…and lead with the cost, not the shame"):
+```bash
+npx @aicopycoders/exodus genesis regenerate --id <runId> --steering "lead with the cost, not the shame"
+```
+- Drop `--steering` entirely for a plain "just try again" — it re-rolls on the brand steering alone.
+- The whole pool is **replaced** with a fresh set, the run re-pauses, and the new numbered list prints. Surface it the same way (verbatim, hook text only) and loop back to A or B. **Unlimited rounds** — keep re-rolling until the user picks or walks away.
+- Steering is **additive across rounds**: round 2's "punchier" stacks on round 1's "lead with the cost" — pass only the *new* direction each time; the backend accumulates.
+- If the user references a specific hook ("**7** is the closest but too aggressive"), **resolve that number to the real hook text yourself** and fold it into the steering you pass — e.g. `--steering "build on 'Your cortisol is wrecking your sleep' but soften the aggression"`. The CLI sends steering as plain text; the bot never sees your numbering.
+
+**Fresh session / lost the list?** Re-fetch and reprint the pool any time with:
+```bash
+npx @aicopycoders/exodus genesis hooks --id <runId>
+```
+A paused run resumes cleanly from a cold session this way — fetch the pool, then pick (`continue`) or re-roll (`regenerate`).
 
-> "Genesis run started at problem-aware — 1 pass per bot (2 variants: Mario × Brand + Infeed × Brand). I'll surface the Doc when it lands."
+> "Genesis paused with 10 hooks — here they are. Tell me which to write (numbers or describe them), or say the word and I'll re-roll the whole set."
 
 Status check (only if user asks): `npx @aicopycoders/exodus status --id <runId> --type genesis` — `--type genesis` required.
 
@@ -161,7 +210,9 @@ What still needs *your* judgment after the run: **verify any statistics, studies
 
 ## Common Failure Modes
 
-- **In-feed-vsl-bot fails** — InfeedVSL hook generation degrades to Mario-only; the Infeed variant still runs if recovered. Note in report.
+- **new-hook-bot fails** — hooks now come from a single source (no two-lane fallback), so a hook-gen failure fails the run cleanly with no pool. Re-run; if it persists, it's a Tool Feedback item.
+- **Empty hook bank** — if the brand's hook primer is empty the pool is generated from the brief alone (weaker hooks). Surface it so the user knows to fill the foundation.
+- **In-feed-vsl-bot fails** — affects **body copy** only (Phase 2): the Infeed variant degrades to Mario-only; the Infeed variant still runs if recovered. Note in report.
 - **Top-ads primer empty (2+ passes)** — the 2nd pass's two variants fall back to the brand primer. Pipeline completes; flag it.
 - **Pipeline timeout** — rare, and only realistic on a large pass count. Check run-detail for partial variants; trigger an editing pass from the UI to recover usable output.
 - **`status` 400 "Invalid generation ID format"** — missing `--type genesis`.

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

@@ -108,31 +108,37 @@ Awareness picks the primer; never mix buckets in one run. Detail in `references/
 
 ---
 
-## Stage C — Pick the pass count, then run Genesis
+## Stage C — Resolve the hook gate, then run Genesis
 
-Genesis writes in two voices — **MarioBot** and the **Infeed VSL bot**. The default is **one pass per bot = 2 variants** (1 Mario × Brand + 1 Infeed × Brand): the fastest read on both voices against the same brief. More passes widen coverage and bring in the Top-Ads-Biased primer.
+**First, resolve the hook-selection gate — it decides the whole shape of the run** (the `exodus-genesis` skill's "Hook selection mode" step). Run `npx @aicopycoders/exodus genesis hook-pref`:
 
-How many passes is the user's call, not yours — so **menu it** (one AskUserQuestion call) rather than assuming. Lead with the recommended default:
+- **`manual`** — the user reviews and picks the hooks **right here in Claude Code** (the primary venue). The run pauses, the CLI prints a numbered hook pool, the user picks, and each pick becomes one ad. **Passes do not apply — ad count = hooks chosen — so skip the passes menu entirely.** Fire with `--stop-at-hooks`.
+- **`auto`** — auto-pick the top hooks and write straight through. Passes apply here (see below). Fire with `--auto-hooks`.
+- **`unset`** — STOP and ask **mode only, two options, in-Claude-Code first**: *① Show me the hooks here — I'll pick · ② Just write the ads — auto-pick the hooks. (Prefer the dashboard? I'll give you the link.)* Then fire with the matching flag, and **after** the run kicks off, offer **once** to save it as the default (`genesis hook-pref <manual|auto>` — never "dashboard"). A run with no flag and no saved default hard-errors by design — don't skip this.
+
+**Passes (auto mode only).** Genesis writes body copy in two voices — **MarioBot** and the **Infeed VSL bot**. The default is **one pass per bot = 2 variants** (1 Mario × Brand + 1 Infeed × Brand). How many passes is the user's call — **menu it** (one AskUserQuestion call) rather than assuming, but only when the user chose auto:
 
 - **1 pass — 2 variants (recommended)** — one Mario, one Infeed, on the brand primer. Fast.
 - **2 passes — 4 variants** — adds a Mario + Infeed pair on the brand's top-performers primer.
 - **3+ passes — 6+ variants** — a wider sprint; "Other" takes a custom number.
 
-Skip the menu only if the user already said how many ("just give me two", "run a big batch"). Awareness you do *not* menu — that's your strategist call from Stage B; state it and move.
-
-Hand off to the `exodus-genesis` skill — it owns the run (double-pass hooks, the built-in 15-point QA, the editing menu). Always background it; even the default run is ~12–15 min, past the 10-min foreground cap.
+Skip the passes menu if the user already said how many, or whenever the mode is manual. Awareness you do *not* menu — that's your strategist call from Stage B; state it and move.
 
-**Before firing, resolve the hook-selection gate** (the `exodus-genesis` skill's "Hook selection mode" step): run `npx @aicopycoders/exodus genesis hook-pref` — if it prints `unset`, ask the user *"choose the hooks yourself, or auto-pick and write straight through?"* and pass `--stop-at-hooks` or `--auto-hooks` accordingly (offer to save the choice). A run with no flag and no saved default hard-errors by design — don't skip this.
+Hand off to the `exodus-genesis` skill — it owns the run (the built-in 15-point QA, the in-Claude-Code hook review, the editing menu). Always background it; even the default run is ~12–15 min, past the 10-min foreground cap.
 
 ```bash
-# Default — 1 pass per bot = 2 variants:
-npx @aicopycoders/exodus genesis run --brief "<brief>" --awareness <level>
-# More coverage — 2 passes = 4 variants:
-npx @aicopycoders/exodus genesis run --brief "<brief>" --awareness <level> --passes 2
+# Manual — review & pick hooks in Claude Code (one ad per pick; no passes):
+npx @aicopycoders/exodus genesis run --brief "<brief>" --awareness <level> --stop-at-hooks
+# Auto — auto-pick and write straight through (default 1 pass = 2 variants):
+npx @aicopycoders/exodus genesis run --brief "<brief>" --awareness <level> --auto-hooks
+# Auto, more coverage — 2 passes = 4 variants:
+npx @aicopycoders/exodus genesis run --brief "<brief>" --awareness <level> --auto-hooks --passes 2
 # with seeds:
-npx @aicopycoders/exodus genesis run --brief "<brief>" --seeds /tmp/genesis-seeds.txt --awareness <level> --passes 2
+npx @aicopycoders/exodus genesis run --brief "<brief>" --seeds /tmp/genesis-seeds.txt --awareness <level> --stop-at-hooks
 ```
 
+When a manual run pauses, drive the in-Claude-Code pick loop from the `exodus-genesis` skill (§3b): print the numbered pool verbatim, let the user pick by number or natural language, then `genesis continue --id <runId> --hooks 1,3,5`.
+
 > "Genesis run started at problem-aware — 1 pass per bot (2 variants: Mario × Brand + Infeed × Brand). I'll surface the Doc when it lands."
 
 Quality is enforced inside the pipeline (Cleanup + QA — see the `exodus-genesis` skill): markdown stripped, bot commentary removed, body copy 700–1500 words, no hook repetition, clean 14pt Google Doc. You don't hand-clean output.

package/dist/commands/genesis.d.ts

@@ -20,6 +20,18 @@ export interface GenesisBody {
 }
 export declare function buildBriefBody(brief: string, opts: GenesisOpts): GenesisBody;
 export declare function buildPasteBody(text: string, opts: GenesisOpts): GenesisBody;
+export declare const VARIANT_CAP = 10;
+export declare function parseHookSelection(raw: string): number[];
+export declare function buildContinueBody(runId: string, selection: number[]): {
+    runId: string;
+    selectedHookIndices: number[];
+};
+export declare function exceedsVariantCap(count: number): boolean;
+export declare function buildRegenerateBody(runId: string, steering?: string): {
+    runId: string;
+    steering?: string;
+};
+export declare function formatHookPool(hooks: string[]): string;
 export interface SwipeRow {
     _id?: string;
     brandName?: string;

package/dist/commands/genesis.js

@@ -37,6 +37,7 @@ Source (choose one):
 Options:
   --steering "<text>"         With --swipe-url: what to model from the ad (angle,
                               tone, structure) — folded into the brief as direction.
+                              With regenerate: re-roll guidance for the hook pool.
   --seeds <file|"text">       Per-run creative seeds (brief mode). File: one per
                               line OR a JSON array. Inline: a single seed.
   --awareness <level>         unaware | problem-aware (default) | solution-aware | product-aware
@@ -121,8 +122,45 @@ export function buildPasteBody(text, opts) {
         body.variantCount = opts.variantCount;
     if (opts.adAccountId)
         body.adAccountId = opts.adAccountId;
+    if (typeof opts.stopAtHooks === "boolean")
+        body.stopAtHooks = opts.stopAtHooks;
     return body;
 }
+export const VARIANT_CAP = 10;
+export function parseHookSelection(raw) {
+    const tokens = raw
+        .split(/[\s,]+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+    if (tokens.length === 0) {
+        throw new Error("No hooks selected. Give the numbers to write, e.g. --hooks 1,3,5");
+    }
+    const nums = tokens.map((t) => {
+        if (!/^\d+$/.test(t)) {
+            throw new Error(`"${t}" is not a hook number. Pick from the printed list, e.g. --hooks 1,3,5`);
+        }
+        const n = parseInt(t, 10);
+        if (n < 1) {
+            throw new Error(`Hook numbers start at 1 (got "${t}").`);
+        }
+        return n;
+    });
+    return nums;
+}
+export function buildContinueBody(runId, selection) {
+    const indices = Array.from(new Set(selection.map((n) => n - 1))).sort((a, b) => a - b);
+    return { runId, selectedHookIndices: indices };
+}
+export function exceedsVariantCap(count) {
+    return count > VARIANT_CAP;
+}
+export function buildRegenerateBody(runId, steering) {
+    const trimmed = typeof steering === "string" ? steering.trim() : "";
+    return trimmed ? { runId, steering: trimmed } : { runId };
+}
+export function formatHookPool(hooks) {
+    return hooks.map((h, i) => `  ${i + 1}. ${h}`).join("\n");
+}
 export function resolveSwipeText(swipe) {
     const transcript = typeof swipe.transcript === "string" ? swipe.transcript.trim() : "";
     if (transcript)
@@ -229,6 +267,12 @@ export async function run(flags) {
         return runScrape(flags, cc);
     if (sub === "hook-pref")
         return runHookPref();
+    if (sub === "continue")
+        return runContinue(flags, cc);
+    if (sub === "regenerate")
+        return runRegenerate(flags, cc);
+    if (sub === "hooks")
+        return runHooks(flags);
     const action = resolveGenesisAction(flags);
     const noWait = flags["wait"] === false || flags["no-wait"] === true;
     switch (action.kind) {
@@ -301,7 +345,7 @@ async function runFromBank(ideaId, opts, rt) {
 }
 async function runReel(urls, opts, rt) {
     console.log(`Transcribing ${urls.length === 1 ? "the reel" : `${urls.length} reels`} → idea → Genesis…`);
-    const result = await captureReelAndWrite(urls, { awarenessLevel: opts.awarenessLevel, variantCount: opts.variantCount }, { cc: rt.cc });
+    const result = await captureReelAndWrite(urls, { awarenessLevel: opts.awarenessLevel, variantCount: opts.variantCount, stopAtHooks: opts.stopAtHooks }, { cc: rt.cc });
     for (const f of result.bankedFailed) {
         console.error(`  ✗ couldn't pull an idea from ${f} (private, region-locked, or no transcript?)`);
     }
@@ -322,7 +366,7 @@ async function runReel(urls, opts, rt) {
 }
 async function runSwipeUrl(urls, opts, steering, rt) {
     console.log(`Swiping ${urls.length === 1 ? "the ad" : `${urls.length} ads`} → idea → Genesis…`);
-    const result = await captureSwipeAndWrite(urls, { awarenessLevel: opts.awarenessLevel, variantCount: opts.variantCount, steering }, { cc: rt.cc });
+    const result = await captureSwipeAndWrite(urls, { awarenessLevel: opts.awarenessLevel, variantCount: opts.variantCount, steering, stopAtHooks: opts.stopAtHooks }, { cc: rt.cc });
     for (const f of result.bankedFailed) {
         console.error(`  ✗ couldn't pull an idea from ${f} (inactive, image-only, or not in the Ad Library index?)`);
     }
@@ -433,10 +477,18 @@ async function waitForGenesisRun(runId) {
     });
     console.log();
     if (result.data["status"] === "awaiting_hook_selection") {
+        const pool = Array.isArray(result.data["hookPool"])
+            ? result.data["hookPool"]
+            : [];
         const dashboardUrl = getDashboardUrl();
-        console.log(`\n⏸  Paused for hook selection.`);
-        console.log(`Pick your hooks here: ${dashboardUrl}/runs/${runId}`);
-        console.log(`(The pipeline resumes automatically once you choose.)`);
+        console.log(`\n⏸  Paused for hook selection (${pool.length} hook${pool.length === 1 ? "" : "s"}).`);
+        if (pool.length > 0) {
+            console.log("");
+            console.log(formatHookPool(pool));
+            console.log("");
+        }
+        console.log(`Write the ones you want:  exodus genesis continue --id ${runId} --hooks 1,3,5`);
+        console.log(`(Prefer the dashboard? ${dashboardUrl}/runs/${runId})`);
         return;
     }
     console.log(formatGenesisRun(result.data));
@@ -481,6 +533,80 @@ async function runHookPref() {
         console.log("Future runs will select hooks automatically without pausing.");
     }
 }
+async function runHooks(flags) {
+    const runId = typeof flags["id"] === "string" ? flags["id"].trim() : "";
+    if (!runId) {
+        console.error("Usage: exodus genesis hooks --id <runId>");
+        process.exit(1);
+    }
+    const res = await apiGet(`/api/v2/genesis?id=${runId}`);
+    if (!res.ok) {
+        console.log(formatError(res));
+        process.exit(1);
+    }
+    if (res.data.status !== "awaiting_hook_selection") {
+        console.log(`Run ${runId} is not awaiting hook selection (status: ${res.data.status ?? "unknown"}).`);
+        return;
+    }
+    const pool = Array.isArray(res.data.hookPool) ? res.data.hookPool : [];
+    if (pool.length === 0) {
+        console.log("No hooks available for this run.");
+        return;
+    }
+    console.log(`Hooks for run ${runId} (${pool.length}):`);
+    console.log("");
+    console.log(formatHookPool(pool));
+    console.log("");
+    console.log(`Write the ones you want:  exodus genesis continue --id ${runId} --hooks 1,3,5`);
+}
+async function runContinue(flags, cc) {
+    const runId = typeof flags["id"] === "string" ? flags["id"].trim() : "";
+    if (!runId) {
+        console.error("Usage: exodus genesis continue --id <runId> --hooks 1,3,5");
+        process.exit(1);
+    }
+    const raw = typeof flags["hooks"] === "string" ? flags["hooks"] : "";
+    let selection;
+    try {
+        selection = parseHookSelection(raw);
+    }
+    catch (e) {
+        console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+        return;
+    }
+    if (exceedsVariantCap(selection.length)) {
+        console.error(`Warning: you picked ${selection.length} hooks but the pipeline writes at most ${VARIANT_CAP}. ` +
+            `The ${VARIANT_CAP} lowest-numbered picks will be written and the rest dropped. ` +
+            `Re-run with ${VARIANT_CAP} or fewer to control exactly which.`);
+    }
+    const body = buildContinueBody(runId, selection);
+    const res = await apiPost("/api/v2/genesis/continue", body, { ccCommand: cc });
+    if (!res.ok) {
+        console.log(formatError(res));
+        process.exit(1);
+    }
+    console.log(`Resuming run ${runId} with ${body.selectedHookIndices.length} hook${body.selectedHookIndices.length === 1 ? "" : "s"}…`);
+    await waitForGenesisRun(runId);
+}
+async function runRegenerate(flags, cc) {
+    const runId = typeof flags["id"] === "string" ? flags["id"].trim() : "";
+    if (!runId) {
+        console.error("Usage: exodus genesis regenerate --id <runId> [--steering \"…\"]");
+        process.exit(1);
+    }
+    const steering = typeof flags["steering"] === "string" ? flags["steering"] : undefined;
+    const body = buildRegenerateBody(runId, steering);
+    const res = await apiPost("/api/v2/genesis/regenerate", body, { ccCommand: cc });
+    if (!res.ok) {
+        console.log(formatError(res));
+        process.exit(1);
+    }
+    console.log(body.steering
+        ? `Regenerating hooks for run ${runId} with steering…`
+        : `Regenerating hooks for run ${runId}…`);
+    await waitForGenesisRun(runId);
+}
 function requireActiveBrand() {
     const slug = resolveActiveBrand().slug;
     if (!slug) {

package/dist/commands/idea.d.ts

@@ -28,6 +28,7 @@ export type IdeaAction = {
     keys: string[];
     awarenessLevel: string;
     variantCount?: number;
+    stopAtHooks?: boolean;
 } | {
     kind: "rm";
     key: string;
@@ -41,6 +42,7 @@ export type IdeaAction = {
     write: boolean;
     awarenessLevel: string;
     variantCount?: number;
+    stopAtHooks?: boolean;
 } | {
     kind: "swipe";
     limit?: number;

package/dist/commands/idea.js

@@ -17,9 +17,13 @@ Usage:
   exodus idea list [--source ..] [--since YYYY-MM-DD] [--status raw|writing|written|archived] [--limit n]
   exodus idea note <KEY> "<notes>"        Attach persistent steering to an idea
   exodus idea edit <KEY> "<new concept>"  Edit an idea's description
-  exodus idea write <KEYS> [--awareness <level>] [--passes n]   Fire-and-forget; one run per key (default 1 pass = 2 variants)
+  exodus idea write <KEYS> [--awareness <level>] [--passes n] [--stop-at-hooks|--auto-hooks]   Fire-and-forget; one run per key (default 1 pass = 2 variants)
   exodus idea rm <KEY> [--hard]           Archive (or hard-delete with --hard)
 
+Hook gate (write paths): --stop-at-hooks pauses each run for in-Claude-Code hook
+review; --auto-hooks auto-picks and writes straight through. Omit both to use your
+saved default (exodus genesis hook-pref). Applies to write and organic --write.
+
 Examples:
   exodus idea gambit "joint pain at 40, sleep angle, grounding vs pills"
   exodus idea organic "https://www.instagram.com/reel/abc https://www.tiktok.com/@x/video/123"
@@ -56,6 +60,22 @@ function resolveVariantCount(flags) {
     }
     return passes * 2;
 }
+function resolveStopAtHooks(flags) {
+    if (flags["stop-at-hooks"] === true)
+        return true;
+    if (flags["auto-hooks"] === true)
+        return false;
+    return undefined;
+}
+function printHookPauseHint(dispatched) {
+    if (dispatched.length === 0)
+        return;
+    console.log("");
+    console.log("Hooks are gated (manual) — each run paused for hook selection. Review and write:");
+    for (const d of dispatched) {
+        console.log(`  exodus genesis hooks --id ${d.runId}    then  exodus genesis continue --id ${d.runId} --hooks 1,3,5`);
+    }
+}
 export function resolveIdeaAction(positionals, flags) {
     const sub = positionals[0];
     if (sub === "add") {
@@ -116,6 +136,7 @@ export function resolveIdeaAction(positionals, flags) {
             keys,
             awarenessLevel: str(flags["awareness"]) ?? "problem-aware",
             variantCount: resolveVariantCount(flags),
+            stopAtHooks: resolveStopAtHooks(flags),
         };
     }
     if (sub === "rm") {
@@ -140,6 +161,7 @@ export function resolveIdeaAction(positionals, flags) {
             write: flags["write"] === true,
             awarenessLevel: str(flags["awareness"]) ?? "problem-aware",
             variantCount: resolveVariantCount(flags),
+            stopAtHooks: resolveStopAtHooks(flags),
         };
     }
     if (sub === "swipe") {
@@ -218,7 +240,7 @@ export async function run(flags) {
         case "organic": {
             if (action.write) {
                 console.log(`Transcribing ${action.urls.length} reel(s) → ideas → Genesis…`);
-                const result = await captureReelAndWrite(action.urls, { awarenessLevel: action.awarenessLevel, variantCount: action.variantCount }, { cc });
+                const result = await captureReelAndWrite(action.urls, { awarenessLevel: action.awarenessLevel, variantCount: action.variantCount, stopAtHooks: action.stopAtHooks }, { cc });
                 for (const f of result.bankedFailed) {
                     console.error(`  ✗ couldn't pull an idea from ${f} (private, region-locked, or no transcript?)`);
                 }
@@ -228,6 +250,8 @@ export async function run(flags) {
                 }
                 for (const d of result.dispatched)
                     console.log(`  ✓ banked ${d.key} → Genesis run ${d.runId}`);
+                if (action.stopAtHooks === true)
+                    printHookPauseHint(result.dispatched);
                 console.log("");
                 console.log("Track them:  exodus idea list   (status flips to 'written' with a doc link)");
                 return;
@@ -304,7 +328,7 @@ export async function run(flags) {
             return;
         }
         case "write": {
-            const res = await apiPost("/api/v2/idea-bank/dispatch", { keys: action.keys, awarenessLevel: action.awarenessLevel, variantCount: action.variantCount }, { ccCommand: cc });
+            const res = await apiPost("/api/v2/idea-bank/dispatch", { keys: action.keys, awarenessLevel: action.awarenessLevel, variantCount: action.variantCount, stopAtHooks: action.stopAtHooks }, { ccCommand: cc });
             if (!res.ok) {
                 console.log(formatError(res));
                 process.exit(1);
@@ -316,6 +340,8 @@ export async function run(flags) {
                 console.log(`  ${d.key} → run ${d.runId}`);
             for (const s of skipped)
                 console.log(`  skipped ${s.key}: ${s.reason}`);
+            if (action.stopAtHooks === true)
+                printHookPauseHint(dispatched);
             console.log("");
             console.log("Track them:  exodus idea list   (status flips to 'written' with a doc link)");
             return;

package/dist/commands/init.d.ts

@@ -3,6 +3,7 @@ export interface InitResult {
     existing: boolean;
     envCreated: boolean;
     skills: string[];
+    docs: string[];
 }
 export declare function scaffoldInit(root: string): InitResult;
 export declare function syncBrands(root: string): Promise<{

package/dist/commands/init.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { writeEnvScaffold, ensureGitignore, writeSkills, writeReferences, ensureBaseDirs, } from "../lib/scaffold.js";
+import { writeEnvScaffold, ensureGitignore, writeSkills, writeReferences, writeDocs, ensureBaseDirs, } from "../lib/scaffold.js";
 import { loadWorkspaceEnv } from "../lib/load-env.js";
 import { ensureBrandDir } from "../lib/layout.js";
 export const helpText = `
@@ -22,7 +22,8 @@ export function scaffoldInit(root) {
     ensureGitignore(root);
     const skills = writeSkills(root);
     writeReferences(root);
-    return { existing, envCreated, skills };
+    const docs = writeDocs(root);
+    return { existing, envCreated, skills, docs };
 }
 export async function syncBrands(root) {
     loadWorkspaceEnv(root);
@@ -48,6 +49,9 @@ export async function run(flags) {
     const r = scaffoldInit(root);
     console.log(`${r.existing ? "Refreshed" : "Initialized"} Exodus workspace at ${root}`);
     console.log(`  Installed ${r.skills.length} skills into .claude/skills/`);
+    if (r.docs.length) {
+        console.log(`  Installed workspace docs: ${r.docs.join(", ")}`);
+    }
     const brands = await syncBrands(root);
     if ("synced" in brands && brands.synced.length) {
         console.log(`  Synced ${brands.synced.length} brand folder(s): ${brands.synced.join(", ")}`);

package/dist/lib/ad-library-write.d.ts

@@ -10,6 +10,7 @@ export declare function captureSwipeAndWrite(urls: string[], opts: {
     awarenessLevel: string;
     variantCount?: number;
     steering?: string;
+    stopAtHooks?: boolean;
 }, rt?: {
     cc?: string;
 }): Promise<SwipeWriteResult>;

package/dist/lib/ad-library-write.js

@@ -52,7 +52,7 @@ export async function captureSwipeAndWrite(urls, opts, rt = {}) {
                 console.error(`  (couldn't attach steering to ${key}: ${formatError(noted)})`);
         }
     }
-    const dispatch = await apiPost("/api/v2/idea-bank/dispatch", { keys, awarenessLevel: opts.awarenessLevel, variantCount: opts.variantCount }, { ccCommand: rt.cc });
+    const dispatch = await apiPost("/api/v2/idea-bank/dispatch", { keys, awarenessLevel: opts.awarenessLevel, variantCount: opts.variantCount, stopAtHooks: opts.stopAtHooks }, { ccCommand: rt.cc });
     if (!dispatch.ok) {
         console.log(formatError(dispatch));
         process.exit(1);

package/dist/lib/assets.d.ts

@@ -1,3 +1,4 @@
 export declare function assetsRoot(override?: string): string;
 export declare function skillsDir(override?: string): string;
 export declare function referencesDir(override?: string): string;
+export declare function docsDir(override?: string): string;

package/dist/lib/assets.js

@@ -21,3 +21,6 @@ export function skillsDir(override) {
 export function referencesDir(override) {
     return path.join(assetsRoot(override), "references");
 }
+export function docsDir(override) {
+    return path.join(assetsRoot(override), "docs");
+}

package/dist/lib/reel-write.d.ts

@@ -9,6 +9,7 @@ export interface ReelWriteResult {
 export declare function captureReelAndWrite(urls: string[], opts: {
     awarenessLevel: string;
     variantCount?: number;
+    stopAtHooks?: boolean;
 }, rt?: {
     cc?: string;
 }): Promise<ReelWriteResult>;

package/dist/lib/reel-write.js

@@ -44,7 +44,7 @@ export async function captureReelAndWrite(urls, opts, rt = {}) {
     if (found.size === 0)
         return { dispatched: [], bankedFailed };
     const keys = [...found.values()];
-    const dispatch = await apiPost("/api/v2/idea-bank/dispatch", { keys, awarenessLevel: opts.awarenessLevel, variantCount: opts.variantCount }, { ccCommand: rt.cc });
+    const dispatch = await apiPost("/api/v2/idea-bank/dispatch", { keys, awarenessLevel: opts.awarenessLevel, variantCount: opts.variantCount, stopAtHooks: opts.stopAtHooks }, { ccCommand: rt.cc });
     if (!dispatch.ok) {
         console.log(formatError(dispatch));
         process.exit(1);

package/dist/lib/scaffold.d.ts

@@ -5,4 +5,5 @@ export declare function writeEnvScaffold(root: string): {
 export declare function ensureGitignore(root: string): void;
 export declare function writeSkills(root: string, srcOverride?: string): string[];
 export declare function writeReferences(root: string, srcOverride?: string): void;
+export declare function writeDocs(root: string, srcOverride?: string): string[];
 export declare function ensureBaseDirs(root: string): void;

package/dist/lib/scaffold.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { skillsDir, referencesDir } from "./assets.js";
+import { skillsDir, referencesDir, docsDir } from "./assets.js";
 export const ENV_SCAFFOLD = `# Exodus config — paste your dashboard .env block below this line.
 # Get it from your Exodus dashboard -> Settings -> Claude Code -> "Copy .env block".
 # ONE key covers every brand you own; switch brands with brand subfolders or
@@ -51,6 +51,25 @@ export function writeReferences(root, srcOverride) {
     fs.rmSync(dest, { recursive: true, force: true });
     fs.cpSync(src, dest, { recursive: true });
 }
+export function writeDocs(root, srcOverride) {
+    let src;
+    try {
+        src = docsDir(srcOverride);
+    }
+    catch {
+        return [];
+    }
+    if (!fs.existsSync(src))
+        return [];
+    const names = [];
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith(".md"))
+            continue;
+        fs.copyFileSync(path.join(src, entry.name), path.join(root, entry.name));
+        names.push(entry.name);
+    }
+    return names.sort();
+}
 export function ensureBaseDirs(root) {
     const out = path.join(root, "output");
     fs.mkdirSync(out, { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicopycoders/exodus",
-  "version": "2026.6.2700-beta.2",
+  "version": "2026.6.2900-beta.4",
   "description": "CLI + Claude Code skills for the Copycoders Exodus ad pipeline",
   "repository": {
     "type": "git",