@aicopycoders/exodus 2026.7.200-beta.3 → 2026.7.200-beta.5

package/assets/skills/exodus/SKILL.md

@@ -18,6 +18,7 @@ This skill ROUTES. Read what the user wants, name the destination skill, and han
 | Static image ads ("make images", "statics", "render this ad") | `exodus-image` (the image front door — it menus engines and confirms before firing) |
 | A specific image engine they already chose | `exodus-creative` (native / copy-derived / ref-match) or `exodus-template` (33 ad-type formats) |
 | Meme ads ("exodus, meme this offer", "make me meme ads") | `exodus-meme` |
+| Run / chain / build / edit a saved workflow ("run my workflow", "what does this workflow need", "build a workflow that…", "list my workflows") | `exodus-workflow` |
 | Onboard a new brand / build the primer | `exodus-primer` (with winning ads) or `exodus-foundation` (no ads yet) |
 | List/switch/troubleshoot brands | `exodus-brand` |
 | See past runs / find an output | `exodus-browse` |

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

@@ -0,0 +1,173 @@
+---
+name: exodus-workflow
+description: Run, chain, build, and edit saved Exodus Workflows — the multi-node automations that wire Genesis bots, primers, briefs, and image nodes together on the dashboard canvas — from the CLI. Use it to list a brand's workflows, describe what a workflow needs before running it (inputs, per-workspace primer prerequisites, outputs), run one and collect its outputs, chain one workflow's output into another's input, browse the bot catalog, and author or update a workflow contract via export → edit → import. Only invoke when the user has explicitly invoked Exodus: they said "exodus" in the request ("exodus, run my launch workflow", "exodus, what does this workflow need", "exodus, build a workflow that turns a swipe into hooks then ads", "list my exodus workflows", "exodus, edit that workflow"), named this skill or /exodus-workflow, ran an `npx @aicopycoders/exodus workflow` command, or the `exodus` hub skill routed here. Never claim generic "workflow"/"automation" requests ("automate this", "build me a workflow") without Exodus context — in shared folders those may belong to the user's other tools; if the user did not say exodus, this skill is not for them. The bare word "Genesis" without "exodus" refers to the member's own Genesis API key and personal bot recipes, NOT to Exodus.
+---
+
+```operator-guide
+Subcommands:
+  exodus workflow list [--json]                              List the brand's saved workflows
+  exodus workflow describe <workflowId|name> [--json]        Inputs, prerequisites, outputs
+  exodus workflow bots [--category <cat>] [--slug <slug>] [--json]   Bot catalog / one bot's spec
+  exodus workflow run <workflowId|name> [--input key=value ...] [--wait] [--json]   Run it
+  exodus workflow status [--id <runId>] [--json]             Poll a run / read its outputs
+  exodus workflow export <workflowId|name> [--out <file>]    Dump the contract JSON
+  exodus workflow import <file> [--update <workflowId>] [--dry-run] [--json]   Author/edit
+
+Key flags:
+  --input key=value    Repeatable run input; the value may contain "="
+  --input key=@path    Load the value from a file (path resolved from the cwd);
+                       use key=@@text to keep a leading "@" as a literal character
+  --wait               Poll until the run reaches a terminal status, then print outputs
+  --id <runId>         Run id for `status` detail
+  --category <cat>     (bots) Filter the catalog to one category id
+  --slug <slug>        (bots) Show a single bot's full port + param spec
+  --out <file>         (export) Write JSON to a file instead of stdout
+  --update <workflowId> (import) Update this workflow in place (optimistic-concurrency
+                       guarded by the export's updatedAt — a 409 means re-export first)
+  --dry-run            (import) Validate + resolve refs without writing; returns issues
+
+Auth: Bearer (EXODUS_API_KEY). The canvas lives on the dashboard at /workflows.
+```
+
+# Workflow — Run, Chain, and Build Saved Automations
+
+An Exodus **Workflow** is a saved graph the member builds on the dashboard canvas (`/workflows`): brief and primer sources feed Genesis bots, bots feed other bots or an image node, and an Output node collects the deliverables. This skill is the CLI operator for those graphs — discover and run them, chain one into the next, and author or edit the contract without opening a browser.
+
+Three jobs, three sections below. Read the request and jump to the one that fits; don't walk all three when the user just wants a run.
+
+## 1. Discover & run
+
+The mistake to avoid is firing a run blind and wasting it on a missing input or an unmet prerequisite. Always **`describe` before `run`**.
+
+### Step 1 — List
+
+```bash
+npx @aicopycoders/exodus workflow list
+```
+
+Prints the brand's saved workflows (name, id, node/edge counts, timestamps). If the user named the workflow already, skip straight to `describe`.
+
+### Step 2 — Describe (read inputs, prereqs, outputs)
+
+```bash
+npx @aicopycoders/exodus workflow describe "Launch Flow"
+```
+
+Accepts a workflow id **or** a name. It reports three things:
+
+- **Inputs** — each free input the run needs: field name, source (`text`, `swipe-ad`, `swipe-bundle`, `organic-url`, `ad-url`), whether it's required, and a description. These are the `--input key=value` pairs you'll pass.
+- **Prerequisites** — the per-workspace primer markers the graph's primer nodes depend on, each shown **✓ stored** or **✗ missing** for *this brand*. **If any prerequisite is ✗, warn the user before running** — the run will not produce good output (or will fail) without it. Route them to the `exodus-primer` / `exodus-foundation` skill to fill the gap first, rather than burning a run.
+- **Outputs** — the deliverables the Output node collects (text or image, with labels), so you know what to expect back.
+
+### Step 3 — Gather inputs
+
+Fill every required input. For a free-text brief you can compose a **bespoke brief from in-session research** — the winning angle you just worked out, the swipe you analyzed — and pass it inline (`--input brief="..."`) or, if it's long, write it to a project file and pass it with `@file` (see Chain, below). For URL/swipe sources, pass the value the source expects.
+
+### Step 4 — Run and collect
+
+```bash
+npx @aicopycoders/exodus workflow run "Launch Flow" --input brief="new cortisol offer, problem-aware" --wait
+```
+
+`--wait` polls to a terminal status and prints the run's collected outputs — text inline, image URLs. Without `--wait` the command returns the `runId` and you poll it yourself:
+
+```bash
+npx @aicopycoders/exodus workflow status --id <runId>
+```
+
+Report the outputs plus a short take. Don't call a run "done" off the kickoff line alone — a run reaches `completed`, `partial`, or `failed`; a `partial` means some nodes were skipped or failed, so read the status before declaring victory.
+
+## 2. Chain — feed one workflow's output into the next
+
+The chaining surface is the run's flattened outputs. After a `--wait` run (or once `status` shows terminal), pull the machine-readable outputs:
+
+```bash
+npx @aicopycoders/exodus workflow status --id <runId> --json
+```
+
+The response carries a top-level `outputs` array — each entry is `{ nodeId, botSlug?, type, label, text?, imageUrl?, imageId? }`. Extract the text you want (e.g. `.outputs[].text`) and pass it into the next workflow's input:
+
+```bash
+# Inline, for short outputs
+npx @aicopycoders/exodus workflow run "Ad Writer" --input hooks="<text from run A>" --wait
+```
+
+**The file-as-persistence convention.** For anything reusable or long — a brief, a sales letter, a hook pool — write the text to a **markdown file in the project** and pass it with `@file`. This is the deliberate v1 alternative to a server-side store: the file *is* the persistence layer, versioned in the project alongside the brand's other artifacts.
+
+```bash
+# Save run A's text output to a project file, then feed it to workflow B
+npx @aicopycoders/exodus workflow status --id <runId> --json   # copy .outputs[].text into state/hooks.md
+npx @aicopycoders/exodus workflow run "Ad Writer" --input hooks=@state/hooks.md --wait
+```
+
+`@path` is resolved from the current directory. If the literal value you need actually starts with `@`, escape it as `@@` (e.g. `--input handle=@@brand` passes the string `@brand`).
+
+Use this pattern to compose pipelines the canvas doesn't wire directly: run the research/hook workflow, persist its best output as a file, then run the writing workflow off that file — reproducibly, because the file stays.
+
+## 3. Build & edit — author a workflow contract
+
+The documented way to learn the contract format is to **export an existing workflow and study it** — there is no separate schema doc. The loop is: learn the bots → learn the format → compose → dry-run until clean → import → review on the canvas.
+
+### Step 1 — Learn the bot catalog
+
+```bash
+npx @aicopycoders/exodus workflow bots                     # full catalog, grouped by category
+npx @aicopycoders/exodus workflow bots --category writing  # one category
+npx @aicopycoders/exodus workflow bots --slug new-hook-bot # one bot's full port + param spec
+npx @aicopycoders/exodus workflow bots --json              # raw catalog for machine use
+```
+
+Per bot you get its **input ports** (id, what it accepts — `text` / `primer` / `image`, whether it's required, and for primer ports which `primerKinds` gate it — `body` / `hook` / `headline` / `summary`), its **params** (select/text/toggle/number/multiselect, with options and defaults), and its output type. This is what tells you which node can wire into which — a port only accepts an edge whose source produces a type it lists in `accepts`.
+
+### Step 2 — Learn the format by exporting
+
+```bash
+npx @aicopycoders/exodus workflow export "Launch Flow" --out launch.json
+```
+
+Study `launch.json`: it's the `exodus-workflow` contract — `nodes` (each with `id`, `kind` = `brief`/`bot`/`primer`/`image`/`output`, a `config`, and an optional `position`) and `edges` (`source`/`sourceHandle` → `target`/`targetHandle`, the handles being port ids). An export also carries `workflowId` + `updatedAt` at the top — those are update anchors, not part of the graph.
+
+### Step 3 — Compose the contract
+
+Author the JSON by hand or by adapting an export. **Node positions are optional** — leave them out and the server auto-layouts the graph on import; you don't need to compute coordinates.
+
+### Step 4 — Dry-run like a compiler loop
+
+```bash
+npx @aicopycoders/exodus workflow import launch.json --dry-run
+```
+
+`--dry-run` validates and resolves refs without writing. It returns compiler-style issues — each names the **node id**, the **port id** where relevant, and a concrete **remedy** (the exact edit that fixes it). Codes you'll see include `dangling-edge`, `unknown-port`, `type-mismatch`, `missing-required-input`, `duplicate-input`, `cycle`, `unknown-kind`, and `bad-config`. Fix, re-run `--dry-run`, repeat until it's clean — same loop as fixing type errors.
+
+### Step 5 — Import (create or update)
+
+```bash
+# Create a new workflow
+npx @aicopycoders/exodus workflow import launch.json
+
+# Update an existing workflow in place
+npx @aicopycoders/exodus workflow import launch.json --update wf_123
+```
+
+Then **tell the user to review it on the canvas at `/workflows`** — the CLI writes the graph; the human eye confirms it reads right.
+
+**Two rules for edits (`--update`):**
+
+- **Always export a backup first.** v1 has no version history — a destructive `--update` overwrites the live workflow with no undo. `export --out backup.json` before you import over it.
+- **A 409 means the canvas moved.** `--update` sends the export's `updatedAt` as an optimistic-concurrency guard. If someone edited the workflow on the dashboard since your export, the import 409s. Re-export the current workflow, reapply your edits onto the fresh contract, and import again — never force past a 409, or you'll clobber their change.
+
+## Failure handling
+
+- **`describe` shows a ✗ prerequisite** — don't run yet. Fill the primer via `exodus-primer` / `exodus-foundation`, then re-check `describe`.
+- **Run comes back `partial` or `failed`** — read `status --id <runId>` (drop `--json` for a readable view) to see which node failed and why before re-running.
+- **`import --dry-run` issues** — fix the exact node/port each issue names using its remedy; don't guess.
+- **`import --update` 409** — re-export, reapply, re-import (see Step 5). This is a conflict, not a bug.
+- **Auth / whoami failure** — run `npx @aicopycoders/exodus doctor` and confirm `EXODUS_API_KEY`.
+- **Wrong brand** — workflows are per-brand. `npx @aicopycoders/exodus brand current` to confirm you're on the brand you think you are; switch with the `exodus-brand` skill.
+
+## Not the right skill for
+
+- **Running a single Genesis writing pass** (brief → copy in two voices) — that's `exodus-genesis`. Reach here when the member has a *saved multi-node workflow* to run or build.
+- **One-off image renders** — `exodus-image` / `exodus-creative` / `exodus-template`.
+- **Building the primer a workflow depends on** — `exodus-primer` (winning ads) or `exodus-foundation` (no ads).
+- **Finding a past run's output doc** — `exodus-browse`.

package/dist/bin/exodus.js

@@ -17,6 +17,8 @@ const OTHER_COMMANDS = new Set([
     "doctor",
     "init",
     "migrate",
+    "segment",
+    "workflow",
 ]);
 const HIDDEN_COMMANDS = new Set([
     "creative",
@@ -76,7 +78,7 @@ async function buildHelp() {
     const fmt = (rows) => rows.map(([n, s]) => `  ${n.padEnd(18)} ${s}`.trimEnd()).join("\n");
     const commonOptions = [
         "Common Options:",
-        "  --awareness <level>    Awareness level: unaware, problem-aware, solution-aware, product-aware",
+        "  --awareness <level>    Awareness level: unaware, problem-aware, solution-aware, product-aware, most-aware",
         "  --wait                 Wait for completion (default)",
         "  --no-wait              Return immediately after starting",
         "  --help, -h             Show help (top-level or per-subcommand)",

package/dist/commands/brand.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { apiGetDashboard, apiPostDashboard } from "../lib/client.js";
+import { sniffImageType, BRAND_IMAGE_MAX_BYTES } from "../lib/image-sniff.js";
 import { getActiveBrand, setActiveBrand, clearActiveBrand, findWorkspaceRoot, } from "../lib/state.js";
 import { detectLayout, ensureBrandDir, resolveActiveBrand, brandStateDir, brandDirFor, } from "../lib/layout.js";
 import { promptYesNo } from "../lib/prompts.js";
@@ -15,6 +16,9 @@ Subcommands:
   exodus brand current          Print the active brand
   exodus brand clear            Stop overriding the brand (use the key's default)
   exodus brand delete <slug>    Delete a brand you own (asks before removing the local folder)
+  exodus brand images add <files...> --kind founder|product|reference
+                                Upload brand-identity images (png/jpg/webp, max 15MB each)
+  exodus brand images list      Show the active brand's uploaded identity images
 
 Any user can create and own unlimited brands (\`brand create\`) — you do NOT
 need to be an admin, and brands are scoped to you (two users can have the
@@ -260,11 +264,166 @@ function runClear() {
         console.log("from here still target it (the folder wins over the pointer).");
     }
 }
+const BRAND_IMAGE_KINDS = ["founder", "product", "reference"];
+async function runImagesAdd(files, flags) {
+    const kind = typeof flags["kind"] === "string" ? flags["kind"] : "";
+    if (!BRAND_IMAGE_KINDS.includes(kind)) {
+        console.error(`Error: brand images add requires --kind ${BRAND_IMAGE_KINDS.join("|")}. ` +
+            `(Logo stays a dashboard upload — it replaces rather than appends.)`);
+        process.exit(1);
+        return;
+    }
+    if (files.length === 0) {
+        console.error("Error: brand images add requires at least one file.");
+        process.exit(1);
+        return;
+    }
+    const valid = [];
+    const skipped = [];
+    for (const file of files) {
+        let buf;
+        try {
+            buf = fs.readFileSync(file);
+        }
+        catch {
+            skipped.push({ file, reason: "unreadable (does the path exist?)" });
+            continue;
+        }
+        if (buf.length > BRAND_IMAGE_MAX_BYTES) {
+            skipped.push({
+                file,
+                reason: `too large (${(buf.length / 1024 / 1024).toFixed(1)}MB > 15MB)`,
+            });
+            continue;
+        }
+        const sniffed = sniffImageType(buf);
+        if (!sniffed) {
+            skipped.push({ file, reason: "not a png/jpg/webp (content check failed)" });
+            continue;
+        }
+        valid.push({ file, buf, mime: sniffed.mime });
+    }
+    for (const s of skipped) {
+        console.error(`  skipped ${path.basename(s.file)}: ${s.reason}`);
+    }
+    if (valid.length === 0) {
+        console.error("Error: no valid image files to upload.");
+        process.exit(1);
+        return;
+    }
+    const mint = await apiPostDashboard("/api/brands/images/upload-url", { count: valid.length });
+    if (!mint.ok || !Array.isArray(mint.data.urls)) {
+        console.error(`Error: ${mint.data.error ?? `HTTP ${mint.status} minting upload URLs`}`);
+        process.exit(1);
+        return;
+    }
+    const storageIds = [];
+    const uploadedFiles = [];
+    for (let i = 0; i < valid.length; i++) {
+        const { file, buf, mime } = valid[i];
+        try {
+            const res = await fetch(mint.data.urls[i], {
+                method: "POST",
+                headers: { "Content-Type": mime },
+                body: new Uint8Array(buf),
+            });
+            const body = JSON.parse(await res.text());
+            if (!res.ok || !body.storageId)
+                throw new Error(`HTTP ${res.status}`);
+            storageIds.push(body.storageId);
+            uploadedFiles.push(file);
+        }
+        catch (err) {
+            console.error(`  skipped ${path.basename(file)}: storage upload failed (${err instanceof Error ? err.message : String(err)})`);
+        }
+    }
+    if (storageIds.length === 0) {
+        console.error("Error: every storage upload failed.");
+        process.exit(1);
+        return;
+    }
+    const attach = await apiPostDashboard("/api/brands/images", {
+        kind,
+        storageIds,
+    });
+    if (!attach.ok) {
+        console.error(`Error: ${attach.data.error ?? `HTTP ${attach.status} attaching images`}`);
+        process.exit(1);
+        return;
+    }
+    for (const s of attach.data.skipped ?? []) {
+        console.error(`  server skipped ${s.storageId}: ${s.reason}`);
+    }
+    for (const f of uploadedFiles)
+        console.log(`  uploaded ${path.basename(f)}`);
+    console.log(`✓ ${kind}: ${attach.data.added} added (brand now has ${attach.data.total} ${kind} image${attach.data.total === 1 ? "" : "s"})`);
+}
+async function runImagesList() {
+    const res = await apiGetDashboard("/api/brands/images");
+    if (!res.ok) {
+        console.error(`Error: ${res.data.error ?? `HTTP ${res.status}`}`);
+        process.exit(1);
+        return;
+    }
+    console.log(`brand: ${res.data.brand}`);
+    for (const kind of BRAND_IMAGE_KINDS) {
+        const entries = res.data[kind] ?? [];
+        console.log(`${kind}: ${entries.length}`);
+        for (const e of entries) {
+            console.log(`  ${e.url ?? e.storageId}`);
+        }
+    }
+}
+function imagesPositionals() {
+    const rest = process.argv.slice(3);
+    const out = [];
+    let i = 0;
+    while (i < rest.length) {
+        const arg = rest[i];
+        if (arg === "--help" || arg === "-h") {
+            i++;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            const key = arg.slice(2);
+            const next = rest[i + 1];
+            if (key.startsWith("no-")) {
+                i++;
+            }
+            else if (next !== undefined && !next.startsWith("--")) {
+                i += 2;
+            }
+            else {
+                i++;
+            }
+            continue;
+        }
+        out.push(arg);
+        i++;
+    }
+    return out;
+}
+async function runImages(args, flags) {
+    const sub = args[0];
+    if (sub === "add") {
+        await runImagesAdd(args.slice(1), flags);
+        return;
+    }
+    if (sub === "list" || sub === undefined) {
+        await runImagesList();
+        return;
+    }
+    console.error(`exodus brand images: unknown subcommand "${sub}" (use add | list)`);
+    process.exit(1);
+}
 export async function run(flags) {
     const positionals = process.argv.slice(3).filter((a) => !a.startsWith("--"));
     const sub = positionals[0];
     const arg = positionals[1];
     switch (sub) {
+        case "images":
+            await runImages(imagesPositionals().slice(1), flags);
+            return;
         case "list":
         case undefined:
             await runList();

package/dist/commands/genesis.js

@@ -22,7 +22,7 @@ Options:
   --seeds <file|"text">       Per-run creative seeds. File: one per line OR a
                               JSON array. Inline: a single seed.
   --steering "<text>"         With regenerate: re-roll guidance for the hook pool.
-  --awareness <level>         unaware | problem-aware (default) | solution-aware | product-aware
+  --awareness <level>         unaware | problem-aware (default) | solution-aware | product-aware | most-aware
   --passes <n>                Writing passes per bot — Mario + Infeed (1-5, default 1 = 2 variants)
   --variants <n>              Advanced: raw total variant count (1-10); overrides --passes
   --ad-account <id>           Meta ad account ID for the top-ads-biased track

package/dist/commands/primer.js

@@ -36,8 +36,8 @@ Genesis writer for that primer honors it on every run.
 
   <lane> is one of: bodyUnaware | bodyAware | hooks | headlines
   (aliases: body-unaware/unaware/problem-aware, body-aware/solution-aware/
-   product-aware, hook, headline). Setting just one of --always / --never
-   leaves the other field as-is.
+   product-aware/most-aware, hook, headline). Setting just one of --always /
+   --never leaves the other field as-is.
 
 Interactive build flags:
   --file <path>   Read the submission (winning ads + product info) from a file
@@ -397,6 +397,8 @@ const LANE_ALIASES = {
     solutionaware: "bodyAware",
     "product-aware": "bodyAware",
     productaware: "bodyAware",
+    "most-aware": "bodyAware",
+    mostaware: "bodyAware",
     hooks: "hooks",
     hook: "hooks",
     headlines: "headlines",

package/dist/commands/segment.d.ts

@@ -0,0 +1,57 @@
+export declare const helpText: string;
+interface NValue {
+    slug: string;
+    name: string;
+}
+interface MapOutcome {
+    slug: string;
+    name: string;
+    lens?: "Type" | "Location" | "Function" | "Moment" | "Severity";
+    subs: NValue[];
+}
+interface MapGroup {
+    name: string;
+    values: NValue[];
+}
+export interface SegmentMap {
+    productWord: string;
+    brandLabel: string;
+    outcomes: MapOutcome[];
+    demoGroups: MapGroup[];
+    facetFamilies: MapGroup[];
+}
+export interface ImportSummary {
+    added: string[];
+    keptRenamed: string[];
+    deleted: string[];
+    subsDeleted: string[];
+    demoValuesDeleted: string[];
+    facetValuesDeleted: string[];
+    personasArchived: string[];
+    personasDeleted: string[];
+}
+export declare function asSummary(data: unknown): ImportSummary;
+export declare function isDestructive(summary: ImportSummary): boolean;
+export declare function formatImportSummary(summary: ImportSummary): string;
+export declare function formatMapSummary(map: SegmentMap): string;
+export interface ImportDeps {
+    post: (path: string, body: unknown) => Promise<{
+        ok: boolean;
+        status: number;
+        data: unknown;
+    }>;
+    readFile: (path: string) => string;
+}
+export interface ImportFlowResult {
+    code: number;
+    lines: string[];
+    calls: Array<{
+        dryRun: boolean;
+    }>;
+}
+export declare function importFlow(file: string, opts: {
+    yes: boolean;
+    json: boolean;
+}, deps: ImportDeps): Promise<ImportFlowResult>;
+export declare function run(flags: Record<string, string | boolean>): Promise<void>;
+export {};