@aicopycoders/exodus 2026.6.2400

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

@@ -0,0 +1,117 @@
+---
+name: exodus-brand
+description: List, switch, inspect, or troubleshoot the brand workspaces the Exodus CLI has access to — "brands" here means the Exodus dashboard's brand workspaces, nothing else. Admins use a single API key with a local active-brand pointer; switching is one `npx @aicopycoders/exodus brand use <slug>` call, no .env editing. **This is the only way to verify which brands the CLI sees — `whoami` only shows the active brand, NOT the list.** Pick the right subcommand from intent — don't ask the user "list, switch, or inspect?". Only invoke when the user has explicitly invoked Exodus — they said "exodus" in the request ("exodus brand list", "switch my exodus brand", "which exodus brand am I on"), named this skill or /exodus-brand, ran an `npx exodus` command, referenced the Exodus CLI or dashboard ("the CLI doesn't see my new brand", "I just created a brand on the dashboard"), or the exodus hub skill routed here. Never claim generic brand questions ("what's our brand strategy", "update the brand colors") — in shared folders those may belong to the user's other tools.
+---
+
+```operator-guide
+Subcommands:
+  list             Show all brands available to your key
+  use <slug>       Set the active brand for this CLI
+  current          Print the active brand
+  inspect <slug>   Show the brand's full config (foundation, primer, account)
+  clear            Stop overriding — fall back to the key's default brand
+Returns:
+  Plain text summary (no JSON). The starred row is the active brand.
+```
+
+# Brand — Move the CLI Between Brands
+
+## Strategic Context
+
+One API key, many brands. **Any user can create and own unlimited brands** — via `npx @aicopycoders/exodus brand create "<name>"` or the dashboard. This is NOT admin-only, and brand names are scoped per user (two different users can each have a "Matt Beard"). The key works for every brand the user OWNS (admin keys see everything); the CLI attaches `X-Active-Brand: <slug>` on every request. The ONLY "pinned to one brand" case is a brand someone ELSE invited the user into: they don't own it, so the header is ignored for it and it's the single brand their key sees. Never tell a user they can't create brands or are "locked to one brand" because their key shows `role: member` — a member who owns brands sees and creates as many as they want.
+
+The active brand resolves **folder > pointer > key default**: on a multi-brand install each brand has a subfolder (marked by `.exodus-brand.json`), and running from inside one targets that brand automatically — it wins over the `{ activeBrand: "<slug>" }` pointer in `.exodus/state.json` that `brand use` writes. `brand current` tells you which one applied.
+
+The dashboard's brand-switcher in the top-right is independent — your CLI active brand and your dashboard active brand can differ. That's a feature: read reports on Brand A while the CLI generates ads for Brand B.
+
+## Read the Intent, Pick the Subcommand
+
+Don't surface a "list, switch, or inspect?" menu to the user — figure it out from what they said:
+
+| User says... | Run |
+|---|---|
+| "What brand am I on?" / "Which brand right now?" | `current` (then `inspect` if they want detail) |
+| "List my brands" / "What brands do I have?" | `list` |
+| "Create a new brand" / "Add a brand called X" / "Set up brand Y" | `create "<name>"` (no admin needed; switches you in) |
+| "Switch to dlc" / "Change to brand X" | `use <slug>` |
+| "Show me the foundation for brand X" / "What's brand Y configured with?" | `inspect <slug>` |
+| "The new brand isn't showing up" | `list` first — if visible, suggest `use`; if not, the dashboard create didn't propagate |
+
+## Common Commands
+
+### List brands
+
+```bash
+npx @aicopycoders/exodus brand list
+```
+
+Shows role, the active brand (marked `★`), and the full accessible list. Flags it if the local active brand points at something you no longer have access to.
+
+### Create a new brand
+
+```bash
+npx @aicopycoders/exodus brand create "Matt Beard"
+```
+
+Creates a brand the user owns (any user can — no admin role required), then switches the CLI into it and, on multi-brand installs, sets up its subfolder. Brand names are scoped per user, so this succeeds even if another account already has a brand by that name (the slug is auto-disambiguated under the hood). Tell the user the next step is the primer (`exodus, set up my brand primer`). If the dashboard ever reports a name conflict for a brand the user is *sure* they've never made, that's a separate bug — not a sign the name is taken for them.
+
+### Switch the active brand
+
+```bash
+npx @aicopycoders/exodus brand use new-brand-slug
+```
+
+Validates the slug, writes it to local state, and (multi-brand installs) creates the brand's subfolder + pulls its `state/brand-profile.md` if missing. Every subsequent CLI call (genesis, creative, template, foundation, etc.) targets the new brand — unless you run from inside a different brand's subfolder, which wins.
+
+### Print the active brand
+
+```bash
+npx @aicopycoders/exodus brand current
+```
+
+Cheap pre-flight check before kicking off a long pipeline.
+
+### Inspect a brand's config
+
+```bash
+npx @aicopycoders/exodus brand inspect <slug>
+```
+
+Surfaces foundation completeness, primer status, connected ad account, and writing-mode defaults. Use this when the user asks "is brand X ready to run?" — don't guess.
+
+### Clear the override
+
+```bash
+npx @aicopycoders/exodus brand clear
+```
+
+Falls back to the brand the API key was originally minted for.
+
+## Anticipate the Next Move
+
+Brand operations are almost never the goal. Read what's next and offer it:
+
+- After `use <slug>` — "Want me to confirm foundation completeness with `inspect`, or jump straight to a Genesis run?"
+- After `list` shows a new brand — "Switching to it now and walking through `exodus-foundation` if you want."
+- After `inspect` reveals missing primers — "Foundation isn't ready. Want me to walk through it from a source doc?"
+- After `current` — "Ready to run `exodus-genesis` on this brand?"
+
+## After Creating a New Brand on the Dashboard
+
+```bash
+# 1. Confirm the new brand is visible
+npx @aicopycoders/exodus brand list
+
+# 2. Switch into it (creates its subfolder + pulls its profile on multi-brand installs)
+npx @aicopycoders/exodus brand use my-new-brand
+
+# 3. Walk through foundation
+npx @aicopycoders/exodus foundation
+```
+
+`npx @aicopycoders/exodus@latest init` does the folder syncing in bulk — it creates a subfolder for EVERY brand the user owns and refreshes all their profiles, and prints the brand summary at the end. Either path works; `brand use` is the targeted one.
+
+## Not the Right Skill For
+
+- Creating, editing, or deleting brands themselves — those happen on the dashboard at Settings → Brands.
+- Editing a brand's foundation content — use the `exodus-foundation` skill.

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

@@ -0,0 +1,96 @@
+---
+name: exodus-browse
+description: View past Exodus pipeline runs and pull outputs from previous sessions. This skill should not just dump the run table back at the user — it should filter, name the most relevant entry, and offer the next move (open the doc, re-run with a sharper brief, rerun with tweaks). Only invoke when the user has explicitly invoked Exodus: they said "exodus" in the request ("exodus, what did we run today", "show me my exodus runs", "did the exodus genesis run from earlier finish"), named this skill or /exodus-browse, ran an `npx exodus` command, or the `exodus` hub skill routed here. Never claim generic history questions ("what did we run today", "show me past runs") — 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.
+---
+
+```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
+```
+
+# Browse — View History and Surface the Right Run
+
+## Strategic Context
+
+`exodus-browse` (the `npx @aicopycoders/exodus browse` command) is the cheap, fast read on what's happened recently in Exodus. Almost every exodus-invoked "where did that go?" / "what did we run?" question routes here. The mistake to avoid is treating it as a dumb proxy — pasting the full table back to the user is more noise than signal. Your job is to find the run they actually mean and queue up the next move on it.
+
+## When to Use
+
+- "What did we run today / this week?"
+- "Find that Genesis run about cortisol from this morning."
+- "Did the Creative run finish yet?"
+- "Show me all our Template runs."
+- "Where's the doc from earlier?"
+
+## Workflow
+
+### 1. Run the query that matches the user's intent
+
+If they named a pipeline, filter by it — don't make them re-ask:
+
+```bash
+npx @aicopycoders/exodus browse --agent genesis --limit 20
+```
+
+If they didn't name one, list across all:
+
+```bash
+npx @aicopycoders/exodus browse --limit 30
+```
+
+Bump `--limit` higher when they say "this week" or "all our runs" — the default 20 will miss things on a busy day.
+
+### 2. Parse the output, then surface the relevant entry
+
+Don't paste the whole table. Read it, find the run that matches what the user asked for (by topic keyword, time, status), and call it out by name. Examples:
+
+> "The cortisol Genesis run from this morning is `gen_xyz123` — finished at 9:42am, doc here: <url>."
+
+> "Three Creative runs this week. The most recent (`run_abc789`) is the only one that completed — the other two failed mid-render."
+
+If multiple runs match, list 2-3 with one-line context each, then ask which one. If nothing matches, say so directly and suggest the closest neighbor ("nothing today, but here's yesterday's Genesis run on a similar angle").
+
+### 3. Anticipate the next move
+
+The user almost never wants `exodus-browse` for its own sake. They want to do something with what they find. Offer the obvious next step inline:
+
+- "Want me to read the doc for `gen_xyz123` and pull the top hooks?"
+- "Should I re-run that with a sharper brief and a new awareness level?"
+- "Want me to check the run that just finished?"
+- "Ready to rerun the failed one with the fix?"
+
+Pick the one that fits their pattern, don't list all four.
+
+### 4. For "is it done yet?" questions
+
+Use `status` directly with the run ID — it's faster than re-listing:
+
+```bash
+npx @aicopycoders/exodus status --id <runId> --type genesis
+```
+
+`--type` is required and pipeline-specific. Get it wrong and you get a 400. For standalone Genesis runs, use `--type genesis`. Creative-suite runs (native / copy-derived / ref-match / meme) use `--type creative`; Template runs use `--type template`.
+
+## Reading a Run's Doc
+
+Once you've identified the run, prefer `read-doc` over the Drive MCP — it walks every tab. The MCP only sees tab 1 and will misreport the run as empty:
+
+```bash
+npx @aicopycoders/exodus read-doc <runId>
+```
+
+Falls back to the Drive MCP only if `read-doc` exits with code 2 (`unavailable`).
+
+## Run Types Reference
+
+| Type | Used For |
+|------|----------|
+| `genesis` | Standalone Genesis runs |
+| `creative` | Creative-suite runs — native, copy-derived, ref-match, and meme |
+| `template` | Template (ad-type format) runs |
+
+All of them also render live in the creative-suite library / dashboard if you'd rather watch there.

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

@@ -0,0 +1,94 @@
+---
+name: exodus-creative
+description: Run a SPECIFIC Exodus creative-suite engine when the user has already chosen one — native (render image ads straight from ad copy), copy-derived (renders derived from copy variations), or ref-match (match the look of reference images already in the brand library). Only invoke when the user has explicitly invoked Exodus AND names the engine or asks precisely for it: they said "exodus" in the request ("exodus native creative", "exodus, ref-match this library image", "exodus copy-derived images"), named this skill or /exodus-creative, ran an `npx @aicopycoders/exodus creative` command, or the `exodus` hub skill routed here. Never claim generic creative requests ("creative suite", "make ads that look like this image") — 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. For an unsure "exodus, just make me some images / statics" ask, start at the `exodus-image` front door — it reads the request and routes here. For a spread across structured ad-type formats use `exodus-template`; for meme formats use `exodus-meme`.
+---
+
+```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).
+```
+
+# Creative — Creative-Suite Engines (Max's pipeline)
+
+Three engines that turn copy (or a reference image) into static renders, without the SCRAWLS concept-mining pass:
+
+- **`native`** — render image ads straight from the ad copy you pass in `--ad`.
+- **`copy-derived`** — renders derived from variations of that copy.
+- **`ref-match`** — match the visual style of one or more **reference images already in the brand's library** (`--refs <imageIds>`), optionally with a subject hint and object overlays.
+
+Unlike `exodus-template` (structured ad-type formats), `exodus-creative` is the engine-direct path — fastest when the user already knows the copy or has a reference look to match.
+
+## When to reach for `exodus-creative` vs the other image tools
+
+| Situation | Use |
+|---|---|
+| "Render images from this ad copy" / "native creative" | `creative native` |
+| "Give me variations derived off this copy" | `creative copy-derived` |
+| "Make ads that look like this image" (ref already uploaded) | `creative ref-match --refs <ids>` |
+| Spread across ad-type formats (testimonial, hero, UGC…) | the `exodus-template` skill |
+
+## Workflow
+
+### 1. Pick the engine, state your read, run
+
+**Native / copy-derived** (copy in `--ad`, min 3 chars):
+
+```bash
+./node_modules/.bin/exodus creative native --ad "<finished ad copy>" --variations 10
+./node_modules/.bin/exodus creative copy-derived --ad "<finished ad copy>" --aspect 9:16
+```
+
+**Ref-match** (reference image ids must already exist in the library):
+
+```bash
+./node_modules/.bin/exodus creative ref-match --refs k57abc123,k57def456 --subject "morning routine"
+```
+
+To get reference image ids, the user uploads to the dashboard library first (Settings → library) — there's **no Bearer upload route**, so the CLI can't upload for them. If they hand you a local file, tell them to upload it in the dashboard and give you the resulting id.
+
+### 2. Poll status (only if asked)
+
+```bash
+./node_modules/.bin/exodus creative status --id <runId>
+```
+
+Returns engine, status (with `(terminal)` when done), `completed / total` render counts, and any error. The dashboard renders the same data live, so prefer linking it over polling in a loop.
+
+### 3. Report
+
+Surface the dashboard URL (`/creative-suite/runs/<runId>`) + a 2-line take per the **Default Post-Run Reporting** rule. Don't claim renders are finished off the kickoff line — the kickoff only confirms the run started. Check `status` (or the dashboard) before calling it done.
+
+## Failure Handling
+
+- **`native`/`copy-derived` without `--ad`** (or under 3 chars) errors — supply the copy.
+- **`ref-match` without `--refs`** errors — supply at least one library image id.
+- **Bad/aspect value** — `--aspect` must be `1:1`, `4:5`, or `9:16`.
+- **whoami/auth failure** — run `npx @aicopycoders/exodus doctor`; confirm `EXODUS_API_KEY`.
+- **Reference id not found** — the id must be a real `creativeSuiteImages` id from the brand's library; re-upload via the dashboard and use the returned id.
+- **"variance" (L1–L5) is NOT an engine here** — only `native | copy-derived | ref-match` are valid. Don't invent a variance engine.
+
+## Admin
+
+- Backend: Convex HTTP `POST /api/creative-suite/run` (Bearer-auth) with engine-specific Trigger.dev fanout; status via dashboard `GET /api/creative-suite/runs/[id]` (Bearer, Max QA #34).
+- Reference images live in `creativeSuiteImages`; upload is dashboard-only for now.
+- Runs appear in the creative-suite library alongside template + meme output.
+- Don't echo render prompts or bot system prompts in your reply.

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

@@ -0,0 +1,118 @@
+---
+name: exodus-drive
+description: Read and write Google Drive / Docs / Sheets via the Exodus dashboard's existing OAuth, using `npx @aicopycoders/exodus drive` subcommands — open a Google Doc URL the user references, inspect a spreadsheet, search Drive for a file, or create new Drive artifacts outside the pipeline flow. For Exodus pipeline-run docs (genesis, creative, template), use `npx @aicopycoders/exodus read-doc <runId>` instead — the Drive MCP only sees tab 1 and will misreport multi-tab pipeline output as empty. Only invoke when the user has explicitly invoked Exodus: they said "exodus" in the request ("exodus, read the doc from that run", "exodus drive, find that file"), named this skill or /exodus-drive, ran an `npx @aicopycoders/exodus drive` command, or the `exodus` hub skill routed here. Never claim generic Drive/Docs/Sheets requests ("read this Google Doc", "pull the data from this sheet") — in shared folders those usually belong to the user's other tools (e.g. a Drive MCP); if the user did not say exodus, this skill is not for them.
+---
+
+```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)
+```
+
+# Drive — Google Drive, Docs, Sheets via the Dashboard's OAuth
+
+## Strategic Context
+
+There is no separate Google CLI to install, no keyring to configure, no `gws` env vars to export. The dashboard holds a single OAuth refresh token at Settings → Google Drive, auto-refreshes it, and `npx @aicopycoders/exodus drive` proxies through with the workspace API key the user already has. One connect, every command works.
+
+If anything's wrong, run `npx @aicopycoders/exodus doctor` first — it probes the dashboard's Drive connection (label: "Google Drive (dashboard)") and tells the user exactly what to click.
+
+## Pipeline Docs Get a Different Command
+
+`npx @aicopycoders/exodus drive get-doc` reads tab 1 of a Doc. Pipeline runs (Genesis, and the creative-suite engines) write **multi-tab** Docs — one tab per variant, segment, or phase. Reading tab 1 of those gives you a fragment and looks like an empty/broken run.
+
+For any pipeline run, use `read-doc` with the run ID:
+
+```bash
+npx @aicopycoders/exodus read-doc <runId>
+```
+
+It walks every tab and gives you the full output as markdown. This is the default for "read the doc from that run" — reach for `drive get-doc` only when the doc isn't a pipeline output.
+
+## Pick the Subcommand from Intent
+
+| User says... | Run |
+|---|---|
+| "Read this Google Doc URL: …" (not a pipeline) | `get-doc <docId>` |
+| "Read the doc from yesterday's genesis run" | `read-doc <runId>` (NOT `drive`) |
+| "Find that Drive file about cortisol" | `list-files --q "name contains 'cortisol'"` |
+| "Pull the data from this sheet" | `get-sheet <sheetId> --range 'Sheet1!A1:Z100'` |
+| "Write up these notes as a new Doc" | `create-doc` then `batch-update` |
+| "Append this to the doc you just made" | `batch-update <docId>` with `insertText` |
+
+Don't ask "which subcommand?" — pick from intent.
+
+## Common Commands
+
+### Get a Google Doc by ID
+
+```bash
+npx @aicopycoders/exodus drive get-doc DOC_ID
+```
+
+Extract `DOC_ID` from `docs.google.com/document/d/DOC_ID/edit`. Returns the Docs API `documents.get` shape; parse `.body.content` for text.
+
+### Search Drive
+
+```bash
+npx @aicopycoders/exodus drive list-files --q "name contains 'genesis'" --page-size 10
+```
+
+Then pass the matching ID into `get-doc`.
+
+### Read a Spreadsheet range
+
+```bash
+npx @aicopycoders/exodus drive get-sheet SPREADSHEET_ID --range "Sheet1!A1:Z100"
+```
+
+### Create a new Doc
+
+```bash
+npx @aicopycoders/exodus drive create-doc "Draft — [topic]" --folder FOLDER_ID
+```
+
+Returns `{id, name, webViewLink}` — share `webViewLink` back to the user.
+
+### Append content to a Doc
+
+```bash
+npx @aicopycoders/exodus drive batch-update DOC_ID --requests '[{"insertText":{"location":{"index":1},"text":"Hello, world.\n"}}]'
+```
+
+Batch all `insertText` requests in a single call rather than one per paragraph.
+
+## Workflow: "Read this Doc and help me revise it"
+
+1. Extract the doc ID (or use `read-doc` if it's a pipeline run).
+2. Fetch the contents.
+3. Quote back the relevant section so the user knows you're looking at the right thing.
+4. Offer revisions inline in chat — don't mutate the Doc unless they explicitly say "update the doc".
+
+## Anticipate the Next Move
+
+- After `get-doc` / `read-doc` — "Want me to walk through the hooks one by one?" / "Should I draft revisions inline, or push edits straight back to the doc?"
+- After `create-doc` — "Want me to share this with [team email]?" / "Ready to drop the draft content in?"
+- After `list-files` finds the wrong thing — "Nothing for that exact name. Want me to broaden the query, or check by date instead?"
+
+## Errors & Recovery
+
+`npx @aicopycoders/exodus drive` exit codes:
+
+- **Exit 2 / `drive_not_connected`** — user hasn't connected Drive on the dashboard. Tell them to visit Settings → Google Drive → Connect, then retry.
+- **Exit 1 / `insufficient_scope`** — they connected before a needed scope was added. Reconnect at Settings → Google Drive.
+- **Exit 1 / `token_refresh_failed`** — refresh token was revoked. Reconnect.
+- **Permission denied on a specific file** — Google account doesn't have access. Ask them to share the file with the email shown at Settings → Google Drive.
+
+When in doubt, `npx @aicopycoders/exodus doctor` surfaces the same problems with concrete remediations.
+
+## Not the Right Skill For
+
+- Reading pipeline-run output — use `npx @aicopycoders/exodus read-doc <runId>`.
+- Running pipelines — Genesis and the creative-suite engines write their own Drive/dashboard output and return the URL.

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

@@ -0,0 +1,170 @@
+---
+name: exodus-foundation
+description: Manage an Exodus brand's Genesis foundation (audience concerns, 2 primers — cold and warm — brand voice); everything it sets lives in the Exodus dashboard, NOT in the user's local files. THREE PATHS, choose by what the user gave you. (1) If the user provided already-structured content with section headers like "## Audience Concerns" / "## Primer (Cold)" / "## Primer (Warm)" — pipe it straight in: `npx @aicopycoders/exodus foundation save -` (reads stdin) — NO interactive walkthrough, NO bot extraction. (2) If the user wants to update one field — `npx @aicopycoders/exodus foundation set <field> --stdin` and pipe content. (3) If the user gave a raw source (Doc URL, web page, brief notes that need extracting), use the interactive walkthrough. Run `npx @aicopycoders/exodus foundation status` first to see what's missing — don't ask the user "where do you want to start", figure it out. Only invoke when the user has explicitly invoked Exodus — they said "exodus" in the request ("exodus, fill in the foundation", "set the exodus brand voice", "refresh the exodus primers"), named this skill or /exodus-foundation, ran an `npx exodus` command, or the exodus hub or `exodus-primer` skill routed here. "Primer" and "foundation" are overloaded words — other toolkits build their own local primers, and a "primer" in the user's local files belongs to their other system; never claim generic asks ("update my primer file", "write a brand voice doc") without Exodus context. The bare word "Genesis" without "exodus" refers to the member's own Genesis API key and personal bot recipes, NOT to Exodus.
+---
+
+```operator-guide
+Three paths — pick by what you have:
+
+1. STRUCTURED markdown (already has "## Audience Concerns" / "## Primer ..." headers):
+     echo "<markdown>" | npx @aicopycoders/exodus foundation save -
+     # or, if it's already in a file:
+     npx @aicopycoders/exodus foundation save path/to/file.md
+
+2. ONE field at a time:
+     echo "<content>" | npx @aicopycoders/exodus foundation set <fieldKey> --stdin
+     npx @aicopycoders/exodus foundation set <fieldKey> --value "<inline string>"
+     npx @aicopycoders/exodus foundation set <fieldKey> --file path/to/section.md
+   fieldKey ∈ { audienceConcerns, brandVoice,
+                primerUnawareProblemAware, primerSolutionProductAware }
+   (Legacy primerUnaware / primerProblemAware / primerSolutionAware /
+    primerProductAware still accepted — they collapse server-side into
+    the 2-track shape.)
+
+3. RAW source needs extracting (Doc URL, web page, raw notes):
+     npx @aicopycoders/exodus foundation              # interactive walkthrough
+     npx @aicopycoders/exodus foundation --doc <url>  # skip the source picker
+     npx @aicopycoders/exodus foundation --url <url>
+     npx @aicopycoders/exodus foundation --file path/to/raw-source.md
+
+Status check (always cheap, run first):
+     npx @aicopycoders/exodus foundation status
+```
+
+# Foundation — Set Up a Brand's Genesis Foundation
+
+> **New brand with winning ads?** Prefer the `exodus-primer` skill — one pass over the brand's winners builds the single document that unlocks every pipeline. This `foundation` command is the **legacy 2-track path** and the **no-ads fallback**: use it for field-level edits, for brands that arrive with finished primer text, or when there are no winning ads to paste and you need to extract a foundation from a brand doc / URL / notes.
+
+## Strategic Context
+
+Genesis routes every variant through a brand's foundation — audience concerns + two awareness-keyed primers (cold = unaware/problem-aware; warm = solution-aware/product-aware) + an optional brand voice. If foundation is incomplete, Genesis falls back to defaults, and the output sounds wrong for the brand. This skill is how you fix that without hand-pasting JSON into the dashboard.
+
+The biggest mistake is running the interactive walkthrough on already-finished content. The walkthrough re-extracts via a bot — slower, costs tokens, and may rewrite content the user already finalized. Read what they gave you first, then pick the path.
+
+## The Primer Prompt (Winning Examples) — the highest-leverage input
+
+The two primers are collections of *winning ads* that teach the Genesis bots what "good" looks like for this market. The better the examples, the sharper every hook and body-copy variant. A brand often arrives onboarding with a **primer prompt** already prepared — a packaged set of winning ads + examples (produced by the separate onboarding/primer step). When the user has one, drop it straight into the matching primer field — no walkthrough, no re-extraction:
+
+```bash
+# cold primer — unaware / problem-aware winning ads:
+pbpaste | npx @aicopycoders/exodus foundation set primerUnawareProblemAware --stdin
+# warm primer — solution / product-aware winning ads:
+pbpaste | npx @aicopycoders/exodus foundation set primerSolutionProductAware --stdin
+```
+
+If the primer prompt is one structured document covering both awareness bands (headers like `## Primer (Cold)` / `## Primer (Warm)`), pipe the whole thing through `foundation save -` — the router splits it into the right fields.
+
+**Works without it.** No primer prompt yet? Don't block. Genesis falls back to sensible defaults and still produces copy — the output just isn't yet calibrated to this brand's winners. Set foundation up to whatever degree you can, run, and tell the user plainly: "output gets noticeably sharper once you add winning examples." Adding the primer later and re-running is cheap. See `references/hook-quality-checklist.md` for what makes an ad primer-worthy.
+
+## Picking the Right Path
+
+| Situation | Command | Why |
+|---|---|---|
+| User pasted structured markdown with `## Audience Concerns`, `## Primer (Cold)` / `## Primer (Warm)` (or legacy `## Primer (Unaware)` etc.), etc. | `foundation save -` and pipe the content | They already wrote it. Don't re-extract. Legacy single-level headers still parse and collapse into the 2-track shape. |
+| User wants to overwrite ONE field | `foundation set <fieldKey> --stdin` | Surgical, no walkthrough loop |
+| User handed you a Google Doc URL / web page / raw brief | `foundation` (interactive walkthrough) | Bot extracts each field from the source |
+
+## Workflow
+
+### 1. Check status first — always
+
+```bash
+npx @aicopycoders/exodus foundation status
+```
+
+Cheap, one query. Tells you which fields are populated, which are missing, and shows the first 80 chars of each. **Use the result to decide what to do next, don't re-ask the user.**
+
+If status shows ✓ Ready — surface that and ask whether they want to refresh anything specific or move on to a Genesis run.
+
+If status shows missing fields — start with those. Don't loop the user through populated fields they didn't ask to touch.
+
+### 2. Recommend a path based on what they gave you
+
+Don't list all three options. State your read:
+
+> "You've got structured markdown with the right headers — piping it straight in. No walkthrough needed."
+
+> "This is a Google Doc with raw brand brief — running the interactive walkthrough so each field gets extracted cleanly."
+
+### 3. For the interactive walkthrough — propose drafts, don't make them type from blank
+
+When you do run the walkthrough, the bot drafts each field from the source. Your job is to surface that draft, evaluate it against what you know about the brand (read the active brand's `state/brand-profile.md` — inside its brand subfolder on multi-brand installs — plus recent runs, the dashboard config), and tell the user "this looks right" or "this is missing X — let me regenerate" instead of just dumping the bot output and asking them to decide blind.
+
+For each field, the walkthrough offers:
+- **a** — accept and save
+- **e** — open in `$EDITOR` and tweak
+- **r** — regenerate with the same source
+- **s** — skip (keep what's there)
+
+Drive the choice. If the draft clearly fits the brand voice, recommend `a`. If a phrase is off, recommend `e` and tell them what to change. If the bot misread the source entirely, recommend `r`.
+
+### 4. After foundation is ready — verify with a real run
+
+Don't declare victory on the status badge alone. Foundation only matters insofar as it changes Genesis output. Verify with a Genesis run:
+
+```bash
+npx @aicopycoders/exodus genesis run --brief "<a known angle for this brand>" --awareness problem-aware
+```
+
+Then read the resulting Doc with `npx @aicopycoders/exodus read-doc <runId>` and check whether the voice and primer landed. If it sounds wrong, come back and `set` the drifted field.
+
+## Anticipate the Next Move
+
+- After `status` shows ✓ Ready — "Want me to verify with a Genesis run at problem-aware level?"
+- After `save -` of structured markdown — "Saved. Ready to test it with a real run?"
+- After `set <field>` — "Updated. Want me to spot-check with a quick Genesis run, or move on?"
+- After interactive walkthrough completes — "Foundation reads clean. Should I update the active brand's `state/brand-profile.md` (inside its brand subfolder on multi-brand installs) to match the new primers, or run a verification Genesis pass?"
+- If a primer drifted on the test run — "The Genesis output is leaning too generic on [field]. Let me regenerate that field with a tighter source."
+
+## Common Commands
+
+### Status only
+
+```bash
+npx @aicopycoders/exodus foundation status
+```
+
+### Interactive walkthrough — let the command pick a source
+
+```bash
+npx @aicopycoders/exodus foundation
+```
+
+Prompts for source type (Google Doc / web URL / local file / paste).
+
+### Skip the source picker
+
+```bash
+npx @aicopycoders/exodus foundation --doc https://docs.google.com/document/d/DOC_ID/edit
+npx @aicopycoders/exodus foundation --url https://example.com/about
+npx @aicopycoders/exodus foundation --file ./brand-brief.md
+npx @aicopycoders/exodus foundation --text "Brand X sells silver-threaded grounding sheets..."
+```
+
+### Iterate on a single field via walkthrough
+
+Run `npx @aicopycoders/exodus foundation`, pick a source, then answer **n** to "Regenerate?" on every populated field except the one you want to redo. That field hits the accept/edit/regenerate/skip loop alone.
+
+## Source Picking Guidance
+
+| Source | Best for |
+|---|---|
+| Google Doc | Customer hands you a brief — fastest, preserves structure across tabs |
+| Web URL | Brand has a live About / Mission / Press page worth scraping |
+| Local file | You've already pulled notes into the workspace as `brand-brief.md` |
+| Paste | Quick experiments or ad-hoc text you don't want to save |
+
+Source quality > source length. Pick something that talks like a customer, not corporate marketing copy. Voice and primer extraction are only as good as the source. The command caps at 30K chars server-side, so length isn't a real constraint.
+
+## Prerequisites
+
+- Workspace API key minted for the target brand (`EXODUS_API_KEY` in `.env`).
+- User is admin OR a member whose `currentWorkspaceId` matches the brand. Otherwise `forbidden`.
+- For Google Doc sources: Drive connected at Settings → Google Drive (same connection used by `npx @aicopycoders/exodus drive`).
+
+If anything's off, `npx @aicopycoders/exodus doctor` is the one-shot diagnosis.
+
+## Not the Right Skill For
+
+- Editing brand metadata (name, slug, ad account) — those live on the dashboard at Settings → Brands.
+- Running pipelines — once foundation is ✓ Ready, switch to `exodus-genesis`.