@aicopycoders/exodus 2026.6.2400 → 2026.6.2700-beta.3

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

@@ -92,6 +92,9 @@ Save to `/tmp/genesis-seeds.txt` (one per line, `#` comments allowed), or pass `
 **Pass count is the user's knob** — if they didn't specify, surface a quick menu (1 pass / 2 variants recommended · 2 passes / 4 variants · more) rather than assuming. Always `run_in_background: true` — these runs are past the 10-min foreground cap.
 
 ```bash
+# 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>
 
@@ -110,12 +113,17 @@ npx @aicopycoders/exodus genesis run --brief "<brief>" --awareness <level> --aut
 
 `--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.
 
-**Hook Selection Mode:**
-The pipeline can pause after Genesis generates hooks, allowing the user to pick which hooks to keep before writing body copy. This is controlled by a persisted per-user preference (manual or auto-select).
+**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.
+
+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.**
 
-- **`--stop-at-hooks`** — pause after hook generation. The run lands in `awaiting_hook_selection` status and the CLI prints a dashboard URL. The user reviews and picks hooks on the run-detail page; the pipeline then continues automatically to body-copy generation.
-- **`--auto-hooks`** — force auto-select for this run (overrides a saved "manual" default). The pipeline auto-computes the strongest hooks and runs straight through without pausing.
-- **Saved preference** — the first time a user runs Genesis (or when no preference is saved), you should ask once: *"Want to choose the hooks yourself, or have me auto-pick and write straight through?"* Then run with `--stop-at-hooks` (manual mode) or `--auto-hooks` (auto mode), and after reporting the result, offer to save the choice with `npx @aicopycoders/exodus genesis hook-pref <manual|auto>` so you don't ask again. If the user has already set a preference via `hook-pref`, skip the question and just run with the saved default.
+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).
 
 > "Genesis run started at problem-aware — 1 pass per bot (2 variants: Mario × Brand + Infeed × Brand). I'll surface the Doc when it lands."
 

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

@@ -122,6 +122,8 @@ Skip the menu only if the user already said how many ("just give me two", "run a
 
 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.
 
+**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.
+
 ```bash
 # Default — 1 pass per bot = 2 variants:
 npx @aicopycoders/exodus genesis run --brief "<brief>" --awareness <level>

package/dist/commands/genesis.js

@@ -446,8 +446,24 @@ async function waitForGenesisRun(runId) {
 async function runHookPref() {
     const positionals = parsePositional();
     const pref = positionals[1];
+    if (pref === undefined) {
+        const res = await apiGet("/api/v2/genesis/hook-pref");
+        if (!res.ok) {
+            console.log(`Error: ${res.data.error ?? "Unknown error"}`);
+            process.exit(1);
+        }
+        const cur = res.data.preference ?? null;
+        if (cur === null) {
+            console.log("unset");
+            console.log("No saved hook preference. Runs require --stop-at-hooks or --auto-hooks until one is set.");
+        }
+        else {
+            console.log(cur);
+        }
+        return;
+    }
     if (pref !== "manual" && pref !== "auto") {
-        console.error('Usage: exodus genesis hook-pref <manual|auto>');
+        console.error('Usage: exodus genesis hook-pref [manual|auto]   (no arg prints the current value)');
         console.error('  manual  Pause each run at hook selection so you choose hooks.');
         console.error('  auto    Skip hook selection and let the pipeline pick automatically.');
         process.exit(1);

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/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/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,12 +1,20 @@
 {
   "name": "@aicopycoders/exodus",
-  "version": "2026.6.2400",
+  "version": "2026.6.2700-beta.3",
   "description": "CLI + Claude Code skills for the Copycoders Exodus ad pipeline",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aicopycoders/exodus.git"
+  },
+  "homepage": "https://github.com/aicopycoders/exodus#readme",
   "type": "module",
   "bin": {
-    "exodus": "./dist/bin/exodus.js"
+    "exodus": "dist/bin/exodus.js"
   },
-  "files": ["dist", "assets"],
+  "files": [
+    "dist",
+    "assets"
+  ],
   "engines": {
     "node": ">=20"
   },

package/assets/skills/genesis-bots/.env.example

@@ -1,12 +0,0 @@
-# Genesis Bots credentials. Keep this file private — never commit or share it.
-# Easiest: replace this ENTIRE file with what the portal's "Copy .env" button
-# gives you (https://genesis.copycoders.ai/portal), then add your provider key.
-
-GENESIS_BASE_URL=https://gas.copycoders.ai/api/v1
-GENESIS_API_KEY=gen_your_key_here
-
-# Your provider key (you pay usage). Use ONE of these — match the name to your key:
-#   Anthropic  → ANTHROPIC_API_KEY=sk-ant-...
-#   OpenRouter → OPENROUTER_API_KEY=sk-or-...
-# (`npx @aicopycoders/exodus keys pull` writes these names for you from the dashboard.)
-ANTHROPIC_API_KEY=sk-ant-your_provider_key_here

package/dist/commands/__tests__/genesis.hookgate.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/commands/__tests__/genesis.hookgate.test.js

@@ -1,12 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { buildBriefBody } from "../genesis.js";
-describe("buildBriefBody stopAtHooks", () => {
-    it("omits stopAtHooks when unset", () => {
-        const b = buildBriefBody("brief text", { awarenessLevel: "problem-aware" });
-        expect("stopAtHooks" in b).toBe(false);
-    });
-    it("includes stopAtHooks:true when set", () => {
-        const b = buildBriefBody("brief text", { awarenessLevel: "problem-aware", stopAtHooks: true });
-        expect(b.stopAtHooks).toBe(true);
-    });
-});