@wrangled/cli 0.2.0 → 0.3.0

package/dist/main.js

@@ -9,7 +9,7 @@ import { brand, envPrefix } from "./brand.js";
 import { firstSymlink, inRunFolder, writeFileAtomic } from "./files.js";
 import { guide, skill } from "./guide.js";
 import { PULL_STATE_FILE, pullContent } from "./pull.js";
-import { AGENTS_MD_MARKER, META_ADS_SKILL_NAME, metaAdsAgentsMd, metaAdsPlaybook, metaAdsSkill, P3_REFRESH_SKILL_NAME, p3RefreshPlaybook, p3RefreshSkill, } from "./playbooks.js";
+import { AGENTS_MD_MARKER, metaAdsAgentsMd, PLAYBOOK_CHOICES, playbooks } from "./playbooks.js";
 import { AGENT_ENV, HARNESS_COMMAND_ENV, RUNNER_TOKEN_ENV, runLoop, runOnce } from "./runner/run.js";
 import { SKILL_NAME_PATTERN } from "./skill-zip.js";
 import { installSkillFolder, operatorConnection, packSkill, parseSkillRef, readSkillFolder, unpackSkill, } from "./skills.js";
@@ -102,20 +102,18 @@ const commands = {
         },
     },
     "warehouse query": {
-        usage: 'warehouse query "<sql>" | --file <path> | < query.sql',
+        usage: 'warehouse query "<sql>" | --file <path> | < query.sql [--out <file.csv | file.json>]',
         async run(args, options) {
             const sql = await readSql(args, options.file);
             const text = await apiText(await resolveConnection(options.apiUrl), "/api/v1/warehouse/query", { sql });
+            if (options.out !== undefined)
+                return saveQueryResult(text, options.out, options.format);
             if (options.format === "json")
                 return console.log(text);
-            const result = JSON.parse(text);
-            const exact = JSON.parse(text, keepNumberDigits);
-            const rows = result.rows.map((row, i) => Object.fromEntries(Object.entries(row).map(([k, v]) => [k, typeof v === "number" ? exact.rows[i][k] : v])));
-            console.log(renderTable(result.columns.map((c) => c.name), rows));
-            console.log(`(${result.rows.length} ${result.rows.length === 1 ? "row" : "rows"})`);
-            if (result.truncated) {
-                console.error(`Results were cut off (${result.truncated}). Aggregate in SQL or add LIMIT.`);
-            }
+            const result = queryResultWithExactNumbers(text);
+            console.log(renderTable(result.columns.map((c) => c.name), result.rows));
+            console.log(`(${rowCount(result.rows.length)})`);
+            warnIfTruncated(result);
         },
     },
     funnel: {
@@ -142,6 +140,9 @@ const commands = {
             printReport(`Money by ${money.grain}`, money, ["period", "currency"], MONEY_NUMBERS);
             if (money.by_source.length > 0)
                 console.log(`\nMoney in by payment source:\n${renderTable(["source", "currency", "gross", "refunds", "net", "orders"], money.by_source)}`);
+            if (money.store_orders_in_stripe?.length) {
+                console.log(`\nStore orders paid through Stripe, counted under stripe:\n${renderTable(["source", "currency", "orders", "total"], money.store_orders_in_stripe)}`);
+            }
             if (money.refund_days.length > 0)
                 console.log(`\nBiggest refund days:\n${renderTable(["date", "currency", "refunds"], money.refund_days)}`);
         },
@@ -258,8 +259,9 @@ const commands = {
             const missing = source.missingAccess ?? [];
             if (missing.length > 0)
                 console.log(`\nMissing access:\n${missing.map((m) => `- ${m.message}`).join("\n")}`);
-            if (source.tables.length > 0)
-                console.log(`\n${renderTable(["name", "rows", "earliest", "latest"], source.tables)}`);
+            const tables = source.tables.map((t) => ({ ...t, rows: t.rowsEstimated ? `about ${t.rows}` : t.rows }));
+            if (tables.length > 0)
+                console.log(`\n${renderTable(["name", "rows", "earliest", "latest"], tables)}`);
             if (runs.length === 0)
                 return console.log("\nNo sync runs yet.");
             const runRows = runs.map((r) => ({ ...r, error: r.error && excerpt(r.error) }));
@@ -479,11 +481,7 @@ const commands = {
             const target = await downloadTarget(args[0], connection);
             const { bytes, contentType } = await apiDownload(connection, `${ASSET_ROUTE}${target.assetPath.split("/").map(encodeURIComponent).join("/")}`);
             const path = await savePath(options.out, extname(target.fileName) ? target.fileName : `${target.fileName}.${extensionFor(contentType)}`);
-            await writeFileAtomic(path, bytes, 0o644).catch((error) => {
-                if (error.code === "ENOENT")
-                    throw new CliError(`No folder at ${dirname(path)} to save into.`, exitCodes.usage);
-                throw error;
-            });
+            await saveFile(path, bytes);
             if (options.open)
                 openFile(resolve(path));
             if (options.format === "json")
@@ -551,6 +549,34 @@ const commands = {
             process.stdout.write(guide.text);
         },
     },
+    brief: {
+        usage: "brief [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--channel <channel>] [--campaign <id>] [--top <n>]   (start here before writing new ads or a campaign plan)",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: brief [--from <date>] [--to <date>] [--channel <channel>] [--campaign <id>] [--top <n>]", exitCodes.usage);
+            const query = reportQuery(options, { channel: options.channel, campaignId: options.campaign, top: options.top });
+            const brief = await api(await resolveConnection(options.apiUrl), `/api/v1/brief${query}`);
+            if (options.format === "json")
+                return printJson(brief);
+            process.stdout.write(brief.text);
+        },
+    },
+    examples: {
+        usage: "examples   (plain questions with SQL that answers them, for the tables this workspace has)",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: examples", exitCodes.usage);
+            const { examples } = await api(await resolveConnection(options.apiUrl), "/api/v1/examples");
+            if (options.format === "json")
+                return printJson({ examples });
+            for (const e of examples) {
+                console.log(`## ${e.id}\n\n${e.question}\nReads: ${e.needs.join(", ")}`);
+                if (e.notes)
+                    console.log(`Note: ${e.notes}`);
+                console.log(`\n\`\`\`sql\n${e.sql}\n\`\`\`\n`);
+            }
+        },
+    },
     "content search": {
         usage: "content search [--text <words>] [--mode word|meaning] [--kind <kind>] [--platform <platform>] [--origin discovered|made] [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--sort recent|<scorecard column>] [--order desc|asc] [--limit <n>]",
         async run(args, options) {
@@ -672,6 +698,38 @@ const commands = {
             printPublication(publication, options.format);
         },
     },
+    "meta adset publish": {
+        usage: "meta adset publish --plan '<json>' --idempotency-key <key> [--run <run-id>]",
+        async run(args, options) {
+            if (args.length !== 0 || options.plan === undefined || !options.idempotencyKey) {
+                throw new CliError("Usage: meta adset publish --plan '<json>' --idempotency-key <key> [--run <run-id>]", exitCodes.usage);
+            }
+            const { adsetPublication } = await api(await resolveConnection(options.apiUrl), "/api/v1/meta/adsets", {
+                plan: await parseJson(options.plan, "--plan"),
+                idempotencyKey: options.idempotencyKey,
+                ...(options.run === undefined ? {} : { runId: options.run }),
+            });
+            printAdSetPublication(adsetPublication, options.format);
+        },
+    },
+    "meta adset show": {
+        usage: "meta adset show <adset-publication-id>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: meta adset show <adset-publication-id>", exitCodes.usage);
+            const { adsetPublication } = await api(await resolveConnection(options.apiUrl), `/api/v1/meta/adsets/${encodeURIComponent(args[0])}`);
+            printAdSetPublication(adsetPublication, options.format);
+        },
+    },
+    "meta adset reconcile": {
+        usage: "meta adset reconcile <adset-publication-id>",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: meta adset reconcile <adset-publication-id>", exitCodes.usage);
+            const { adsetPublication } = await api(await resolveConnection(options.apiUrl), `/api/v1/meta/adsets/${encodeURIComponent(args[0])}/reconcile`, {});
+            printAdSetPublication(adsetPublication, options.format);
+        },
+    },
     "content unpublish": {
         usage: "content unpublish <deployment-id> [--force]",
         async run(args, options) {
@@ -726,7 +784,6 @@ const commands = {
                 ...(start.result ? [{ field: "result", value: `${start.result.name} (${start.result.metaActionTypes.join(", ") || "no Meta source"})` }] : []),
                 ...(quota ? [{ field: "ideas today", value: `${quota.creativeProposalsToday} of ${quota.ideasPerDay} used, ${quota.remainingToday} left` }] : []),
                 { field: "brand profile", value: brandProfile ? `version ${brandProfile.version}, ${brandProfile.ageDays} days old` : "none yet" },
-                ...start.memory.map((note) => ({ field: `memory ${note.key}`, value: note.value ? `${note.value.length} characters` : "empty" })),
             ];
             console.log(renderTable(["field", "value"], rows));
         },
@@ -814,36 +871,6 @@ const commands = {
             console.log(`\n${rows.length ? renderTable(Object.keys(rows[0]), rows) : "No P1 winners."}`);
         },
     },
-    "memory get": {
-        usage: "memory get [baselines|watch_items|changes_log|gotchas]",
-        async run(args, options) {
-            if (args.length > 1)
-                throw new CliError("Usage: memory get [<note>]", exitCodes.usage);
-            const connection = await resolveConnection(options.apiUrl);
-            if (args[0]) {
-                const { note } = await api(connection, `${agentPath(options)}/memory/${encodeURIComponent(args[0])}`);
-                if (options.format === "json")
-                    return printJson({ note });
-                return void process.stdout.write(note.value ? `${note.value.replace(/\n?$/, "\n")}` : "");
-            }
-            const { memory } = await api(connection, `${agentPath(options)}/memory`);
-            if (options.format === "json")
-                return printJson({ memory });
-            console.log(memory.map((n) => `## ${n.key}${n.updatedAt ? ` (updated ${n.updatedAt})` : ""}\n\n${n.value || "(empty)"}`).join("\n\n"));
-        },
-    },
-    "memory set": {
-        usage: "memory set <note> [--file <path> | < note.md]",
-        async run(args, options) {
-            if (args.length !== 1)
-                throw new CliError("Usage: memory set <note> [--file <path>]", exitCodes.usage);
-            const value = await readText(options.file, "the note");
-            const { note } = await api(await resolveConnection(options.apiUrl), `${agentPath(options)}/memory/${encodeURIComponent(args[0])}`, { value }, "PUT");
-            if (options.format === "json")
-                return printJson({ note });
-            console.log(`Saved ${note.key} (${note.value.length} characters).`);
-        },
-    },
     "brand get": {
         usage: "brand get",
         async run(_args, options) {
@@ -918,11 +945,147 @@ const commands = {
             printTrail(trail, options.format);
         },
     },
+    "funnels show": {
+        usage: "funnels show [--version <n>]   the offers and funnels map as text: the confirmed map (or that version) and the draft on hold",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: funnels show [--version <n>]", exitCodes.usage);
+            const query = options.version === undefined ? "" : `?version=${wholeNumber(options.version, "--version")}`;
+            const view = await api(await resolveConnection(options.apiUrl), `${FUNNELS_PATH}${query}`);
+            if (options.format === "json")
+                return printJson(view);
+            process.stdout.write(view.text);
+        },
+    },
+    "funnels numbers": {
+        usage: "funnels numbers [--funnel <key>] [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>]   how many reached each funnel step and moved on from the one before",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: funnels numbers [--funnel <key>] [--from <date>] [--to <date>]", exitCodes.usage);
+            const view = await api(await resolveConnection(options.apiUrl), `${FUNNELS_PATH}/numbers${reportQuery(options, { funnel: options.funnel })}`);
+            if (options.format === "json")
+                return printJson(view);
+            process.stdout.write(view.text);
+        },
+    },
+    "funnels evidence": {
+        usage: "funnels evidence   what the data says the client sells: prices paid, buyer paths, GoHighLevel funnels, calendars and tags, webinars, pages, campaigns, past campaigns",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: funnels evidence", exitCodes.usage);
+            const view = await api(await resolveConnection(options.apiUrl), `${FUNNELS_PATH}/evidence`);
+            if (options.format === "json")
+                return printJson(view);
+            process.stdout.write(view.text);
+        },
+    },
+    "funnels draft": {
+        usage: "funnels draft --file <map.json> [--note <why>] [--evidence '<json>' | @file.json] [--based-on <n>]   save a whole map; it counts at once when every step can be counted",
+        async run(args, options) {
+            const usage = "Usage: funnels draft --file <map.json> [--note <why>] [--evidence '<json>' | @file.json] [--based-on <n>]";
+            if (args.length > 0 || !options.file)
+                throw new CliError(usage, exitCodes.usage);
+            const map = await parseJson(`@${options.file}`, "--file");
+            const evidence = options.evidence === undefined ? undefined : await parseJson(options.evidence, "--evidence");
+            const connection = await resolveConnection(options.apiUrl);
+            const basedOn = options.basedOn === undefined ? null : wholeNumber(options.basedOn, "--based-on");
+            const saved = await api(connection, `${FUNNELS_PATH}/draft`, { map, note: options.note, evidence, based_on: basedOn }, "PUT");
+            if (options.format === "json")
+                return printJson(saved);
+            const based = basedOn === null ? "" : `, based on version ${basedOn}`;
+            console.log(saved.applied
+                ? `Map version ${saved.version.version} is live${based}: it counts from now. A person can undo it in the app.`
+                : `Saved version ${saved.version.version}${based}. It is on hold: it counts nothing until every step can be counted.`);
+            if (saved.warnings.length > 0)
+                console.log(`\n${saved.applied ? "Not in synced data yet" : "To fill in"}:\n${saved.warnings.map((w) => `- ${w.path}: ${w.message}`).join("\n")}`);
+            if (saved.weak.length > 0)
+                console.log(`\nNot backed up by synced data:\n${saved.weak.map((w) => `- ${w.path}: ${w.reason}`).join("\n")}`);
+        },
+    },
+    "funnels versions": {
+        usage: "funnels versions [--diff <a> <b>]   every version of the map, or what changed from version a to b",
+        async run(args, options) {
+            const connection = await resolveConnection(options.apiUrl);
+            if (options.diff !== undefined) {
+                if (args.length !== 1)
+                    throw new CliError("Usage: funnels versions --diff <a> <b>", exitCodes.usage);
+                const pair = [options.diff, args[0]].map((v) => wholeNumber(v, "--diff")).join(",");
+                const diff = await api(connection, `${FUNNELS_PATH}/versions?diff=${pair}`);
+                if (options.format === "json")
+                    return printJson(diff);
+                process.stdout.write(diff.text);
+                return;
+            }
+            if (args.length > 0)
+                throw new CliError("Usage: funnels versions [--diff <a> <b>]", exitCodes.usage);
+            const { versions } = await api(connection, `${FUNNELS_PATH}/versions`);
+            if (options.format === "json")
+                return printJson({ versions });
+            if (versions.length === 0)
+                return console.log("No map versions yet.");
+            const rows = versions.map((v) => ({
+                version: v.version,
+                status: v.status,
+                "created by": v.createdBy,
+                "created at": v.createdAt,
+                "confirmed by": v.confirmedBy,
+                "confirmed at": v.confirmedAt,
+                note: v.note && excerpt(v.note),
+            }));
+            console.log(renderTable(["version", "status", "created by", "created at", "confirmed by", "confirmed at", "note"], rows));
+        },
+    },
+    facts: {
+        usage: "facts [--kind <kind>] [--subject <type>[:<ref>]] [--status <status>] [--json]   settled facts about this workspace's data, to treat as true",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: facts [--kind <kind>] [--subject <type>[:<ref>]] [--status <status>] [--json]", exitCodes.usage);
+            const query = new URLSearchParams();
+            if (options.kind)
+                query.set("kind", options.kind);
+            if (options.subject) {
+                const colon = options.subject.indexOf(":");
+                query.set("subject_type", colon === -1 ? options.subject : options.subject.slice(0, colon));
+                if (colon !== -1 && colon < options.subject.length - 1)
+                    query.set("subject_ref", options.subject.slice(colon + 1));
+            }
+            if (options.status)
+                query.set("status", options.status);
+            const { facts } = await api(await resolveConnection(options.apiUrl), `${FACTS_PATH}${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson({ facts });
+            if (facts.length === 0)
+                return console.log("No facts.");
+            console.log(renderTable(FACT_COLUMNS, facts.map(factRow)));
+        },
+    },
+    "facts show": {
+        usage: "facts show <id>   one fact with its value and evidence",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: facts show <id>", exitCodes.usage);
+            const { fact } = await api(await resolveConnection(options.apiUrl), `${FACTS_PATH}/${encodeURIComponent(args[0])}`);
+            if (options.format === "json")
+                return printJson({ fact });
+            printFields({ ...factRow(fact), summary: fact.summary, value: fact.value, evidence: fact.evidence, author: fact.author, "confirmed by": fact.confirmedBy, replaces: fact.replaces });
+        },
+    },
+    "facts propose": {
+        usage: "facts propose --file <fact.json> | < fact.json   suggest a fact; a person confirms it in the app",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: facts propose --file <fact.json> | < fact.json", exitCodes.usage);
+            const { fact } = await api(await resolveConnection(options.apiUrl), FACTS_PATH, await readToolInput(options));
+            if (options.format === "json")
+                return printJson({ fact });
+            console.log(`Proposed fact ${fact.id}. A person confirms or rejects it in the app.`);
+        },
+    },
     "plans create": {
-        usage: "plans create --name <name> --goal <text> --channel meta|ghl|klaviyo|web [--target '<json>' | @file.json] [--landing <sku | item-id> | --landing-url <url>] [--run <agent-run-id>]",
+        usage: "plans create --name <name> --goal <text> --channel meta|ghl|klaviyo|web [--target '<json>' | @file.json] [--landing <sku | item-id> | --landing-url <url>] [--funnel <key> --step <key>] [--run <agent-run-id>]",
         async run(args, options) {
             if (args.length > 0 || !options.name || !options.goal || !options.channel) {
-                throw new CliError("Usage: plans create --name <name> --goal <text> --channel meta|ghl|klaviyo|web [--target '<json>'] [--landing <sku> | --landing-url <url>]", exitCodes.usage);
+                throw new CliError("Usage: plans create --name <name> --goal <text> --channel meta|ghl|klaviyo|web [--target '<json>'] [--landing <sku> | --landing-url <url>] [--funnel <key> --step <key>]", exitCodes.usage);
             }
             const { plan } = await api(await resolveConnection(options.apiUrl), "/api/v1/launch-plans", {
                 name: options.name,
@@ -931,6 +1094,8 @@ const commands = {
                 ...(options.target === undefined ? {} : { target: await parseJson(options.target, "--target") }),
                 ...(options.landing === undefined ? {} : { landingItem: options.landing }),
                 ...(options.landingUrl === undefined ? {} : { landingUrl: options.landingUrl }),
+                ...(options.funnel === undefined ? {} : { funnelKey: options.funnel }),
+                ...(options.step === undefined ? {} : { stepKey: options.step }),
                 ...(options.run === undefined ? {} : { runId: options.run }),
             });
             printPlan(plan, options.format);
@@ -1054,9 +1219,9 @@ const commands = {
         },
     },
     "skill install": {
-        usage: "skill install [meta-ads|p3-refresh|<name>[@<version>]] [--project] [--codex]",
+        usage: `skill install [${PLAYBOOK_CHOICES}|<name>[@<version>]] [--project] [--codex]`,
         async run(args, options) {
-            const usage = "Usage: skill install [meta-ads|p3-refresh|<name>[@<version>]] [--project] [--codex]";
+            const usage = `Usage: skill install [${PLAYBOOK_CHOICES}|<name>[@<version>]] [--project] [--codex]`;
             const [which] = args;
             if (args.length > 1)
                 throw new CliError(usage, exitCodes.usage);
@@ -1067,15 +1232,15 @@ const commands = {
                 if (which === "meta-ads")
                     return installAgentsMd(join(process.cwd(), "AGENTS.md"));
                 if (!playbook)
-                    throw new CliError("--codex installs a playbook: skill install meta-ads|p3-refresh --codex", exitCodes.usage);
+                    throw new CliError(`--codex installs a playbook: skill install ${PLAYBOOK_CHOICES} --codex`, exitCodes.usage);
                 if (options.project)
                     throw new CliError(`--codex installs ${playbook.name} for every Codex run, under CODEX_HOME; drop --project`, exitCodes.usage);
-                const path = await writeSkill(codexSkillsDir(), playbook.name, playbook.skill, []);
+                const path = await writeSkill(codexSkillsDir(), playbook.name, playbook.skill, playbook.files, []);
                 return console.log(`Installed the ${playbook.name} skill for Codex to ${path}.`);
             }
-            const [name, content] = playbook ? [playbook.name, playbook.skill] : [brand.slug, skill];
+            const [name, content, files] = playbook ? [playbook.name, playbook.skill, playbook.files] : [brand.slug, skill, []];
             const { skillsDir, above } = claudeSkillsDir(options.project);
-            const path = await writeSkill(skillsDir, name, content, above);
+            const path = await writeSkill(skillsDir, name, content, files, above);
             console.log(`Installed the ${name} skill to ${path}.`);
         },
     },
@@ -1088,7 +1253,7 @@ const commands = {
             if (options.format === "json")
                 return printJson({ workers });
             if (workers.length === 0)
-                return console.log("No workers yet.");
+                return console.log("No scheduled hands yet.");
             const rows = workers.map((w) => ({
                 id: w.id,
                 skill: w.skill,
@@ -1104,10 +1269,10 @@ const commands = {
         },
     },
     "worker runs": {
-        usage: "worker runs <worker-id | skill> [--limit <n>]",
+        usage: "worker runs <hand-id | skill> [--limit <n>]",
         async run(args, options) {
             if (args.length !== 1)
-                throw new CliError("Usage: worker runs <worker-id | skill> [--limit <n>]", exitCodes.usage);
+                throw new CliError("Usage: worker runs <hand-id | skill> [--limit <n>]", exitCodes.usage);
             const connection = await resolveConnection(options.apiUrl);
             const id = await workerId(connection, args[0]);
             const query = options.limit === undefined ? "" : `?limit=${encodeURIComponent(options.limit)}`;
@@ -1120,10 +1285,10 @@ const commands = {
         },
     },
     "worker run-now": {
-        usage: "worker run-now <worker-id | skill>",
+        usage: "worker run-now <hand-id | skill>",
         async run(args, options) {
             if (args.length !== 1)
-                throw new CliError("Usage: worker run-now <worker-id | skill>", exitCodes.usage);
+                throw new CliError("Usage: worker run-now <hand-id | skill>", exitCodes.usage);
             const connection = await resolveConnection(options.apiUrl);
             const id = await workerId(connection, args[0]);
             const queued = await api(connection, `/api/v1/workers/${encodeURIComponent(id)}/run-now`, {});
@@ -1140,7 +1305,7 @@ const commands = {
             const { promoted } = await changeCandidate("promote", args, options);
             if (options.format === "json")
                 return printJson({ promoted });
-            console.log(`${promoted.skill} version ${promoted.version} is now in use on ${promoted.moved} worker${promoted.moved === 1 ? "" : "s"}.`);
+            console.log(`${promoted.skill} version ${promoted.version} is now in use on ${promoted.moved} hand${promoted.moved === 1 ? "" : "s"}.`);
         },
     },
     "worker drop": {
@@ -1175,11 +1340,11 @@ const commands = {
         },
     },
     docs: {
-        usage: "docs [meta-ads|p3-refresh]",
+        usage: `docs [${PLAYBOOK_CHOICES}]`,
         async run(args) {
             const [which] = args;
             if (args.length > 1 || (which !== undefined && !isPlaybook(which)))
-                throw new CliError("Usage: docs [meta-ads|p3-refresh]", exitCodes.usage);
+                throw new CliError(`Usage: docs [${PLAYBOOK_CHOICES}]`, exitCodes.usage);
             process.stdout.write(which === undefined ? guide : playbooks[which].text);
         },
     },
@@ -1208,10 +1373,6 @@ async function withRunner(options, work) {
         process.off("SIGTERM", onSignal);
     }
 }
-const playbooks = {
-    "meta-ads": { name: META_ADS_SKILL_NAME, skill: metaAdsSkill, text: metaAdsPlaybook },
-    "p3-refresh": { name: P3_REFRESH_SKILL_NAME, skill: p3RefreshSkill, text: p3RefreshPlaybook },
-};
 const isPlaybook = (name) => Object.hasOwn(playbooks, name);
 const codexSkillsDir = () => join(process.env.CODEX_HOME || join(homedir(), ".codex"), "skills");
 /** Claude Code's skills folder, in the user's home or (with --project) the current folder. */
@@ -1232,15 +1393,20 @@ async function installLibrarySkill(ref, options) {
     const path = await installSkillFolder(skillsDir, download.name, files, above);
     console.log(`installed ${download.name} version ${download.version} to ${path}`);
 }
-/** Writes <skillsDir>/<name>/SKILL.md, refusing to follow a symlink at any of `above` or the skill's own paths. */
-async function writeSkill(skillsDir, name, content, above) {
-    const path = await inRunFolder(join(skillsDir, name, "SKILL.md"));
-    const linked = await firstSymlink([...above, join(skillsDir, name), path]);
+/**
+ * Writes <skillsDir>/<name>/SKILL.md and any files beside it, refusing to follow a symlink at any of `above` or the
+ * skill's own paths. Returns the SKILL.md path.
+ */
+async function writeSkill(skillsDir, name, content, files, above) {
+    const written = [{ name: "SKILL.md", content }, ...files];
+    const paths = await Promise.all(written.map((f) => inRunFolder(join(skillsDir, name, f.name))));
+    const linked = await firstSymlink([...above, join(skillsDir, name), ...paths]);
     if (linked)
         throw new CliError(`Refusing to write through the symlink at ${linked}. Remove it and try again.`, exitCodes.error);
-    await mkdir(dirname(path), { recursive: true });
-    await writeFileAtomic(path, content, 0o644);
-    return path;
+    await mkdir(join(skillsDir, name), { recursive: true });
+    for (const [i, file] of written.entries())
+        await writeFileAtomic(paths[i], file.content, 0o644);
+    return paths[0];
 }
 const SOURCE_RUNS_SHOWN = 10;
 /** What the source is retrying: "the whole sync since <time>", and each failing part as "<part> since <time>". */
@@ -1290,6 +1456,11 @@ function printReport(title, report, labels, numbers) {
     console.log(renderTable(["currency", ...numbers], report.totals));
 }
 const agentPath = (options) => `/api/v1/agents/${encodeURIComponent(options.agent)}`;
+const FACTS_PATH = "/api/v1/facts";
+const FACT_COLUMNS = ["id", "kind", "subject", "key", "status", "summary"];
+function factRow(f) {
+    return { id: f.id, kind: f.kind, subject: `${f.subjectType}:${f.subjectRef}`, key: f.key, status: f.status, summary: excerpt(f.summary, 80) };
+}
 const PROPOSAL_COLUMNS = ["id", "kind", "status", "target", "change", "reason"];
 function proposalChange(p) {
     if (p.kind === "creative")
@@ -1331,7 +1502,7 @@ Options:
   --format table|json   output format (default: table)
   --api-url <url>       API base URL
   --wait <seconds>      how long tools run and tools get wait for a run (default: ${DEFAULT_WAIT_SECONDS}; 0 returns at once)
-  --agent <kind>        which agent the agent and memory commands use: meta_ads (default) or p3_refresh; in a worker run, skill
+  --agent <kind>        which agent the agent commands use: meta_ads (default) or p3_refresh; in a scheduled hand's run, skill
                         (the run's skill's agent) is the default
   --kind <kind>         what sends to a new intake address: generic (default), ghl_workflow, aloware, webinarfuel, stealth_seminar or mailgun
   --retention-days <n>  how many days intake create keeps each event (default: 90)
@@ -1340,18 +1511,21 @@ Options:
                         for warehouse schema, a table to describe in full; repeat for several
   --summary             warehouse schema: one short row per table (kind, source, column count, summary)
   --search <words>      warehouse schema: describe in full the tables whose name, description or columns mention a word
-  --out <path>          the file, or existing folder, creatives download saves to (default: the current folder)
+  --out <path>          the file, or existing folder, creatives download and warehouse query save to; warehouse query
+                        writes CSV for a .csv path, otherwise JSON
   --open                open the file creatives download saved
   --media               with content pull, also save each item's files and HTML under media/ in the folder
   --full                with content pull, fetch every item, not only what changed since the last pull (brings new numbers)
   --force               content unpublish: take the page down even while delivering Meta ads link to it
+  --plan <json>         meta adset publish: the ad set to make, {"kind": "copy", ...} or {"kind": "create", ...}
   --yes                 confirm intake delete or import remove, which delete saved data for good
-  --from <YYYY-MM-DD>   first day funnel, campaigns and money cover (default: 29 days before --to)
-  --to <YYYY-MM-DD>     last day funnel, campaigns and money cover (default: today in the workspace reporting time zone)
+  --from <YYYY-MM-DD>   first day funnel, campaigns, money and brief cover (default: 29 days before --to)
+  --to <YYYY-MM-DD>     last day funnel, campaigns, money and brief cover (default: today in the workspace reporting time zone)
   --grain <grain>       how funnel and money group days: day (default), week (starting Monday) or month
-  --channel <channel>   only this channel's campaigns: meta, google, affiliate, a utm_source, or unknown;
+  --channel <channel>   only this channel's campaigns (and, with brief, its ads): meta, google, affiliate, a utm_source, unknown or recorded_in_crm;
                         for content track-link, where the link goes: facebook, email, sms or web (default)
-  --campaign <id>       the campaign content track-link puts in utm_campaign
+  --campaign <id>       the campaign content track-link puts in utm_campaign; with brief, the one campaign it covers
+  --top <n>             how many best ads, worst ads, pages and campaigns brief shows (default: 5, at most 20)
   --body, --html <text | @file>   the words, or the full HTML, content create, capture and edit save
   --file <path>         an image, video or audio file, up to 50 MB, content create, capture and edit save; repeat for several
   --transcript <text | @file>   what is said in the first video or audio file content capture saves, so none is paid for
@@ -1362,6 +1536,14 @@ Options:
   --run <id>            the agent run making the content (content), or the tool run to record (creatives create)
   --platform, --external-id   where content status launched says it was published, and that platform's id for it
   --notes <text>        what changed in the version skill publish adds
+  --version <n>         the map version funnels show prints (default: the confirmed one)
+  --based-on <n>        the map version funnels draft was written from; refused when someone saved since
+                        (leave it out only for the first map, when there is neither a map nor a draft)
+  --evidence <json | @file.json>   what funnels draft was written from: counts and ids, never names, emails or phones
+  --diff <a> <b>        with funnels versions, what changed from version a to version b
+  --funnel <key>        only this funnel's steps in funnels numbers (default: every funnel in the confirmed map);
+                        with plans create and --step, the funnel whose step the push feeds
+  --step <key>          with plans create, the step of --funnel the push feeds, as on the confirmed map
   --harness <list>      which agents skill publish marks the skill for: claude, codex, or claude,codex (default)
   --text <words>        words content search finds in a subject, headline, body or video transcript
   --mode word|meaning   how content search matches --text: word (default, the words themselves) or meaning (close in meaning, nearest first; no --sort)
@@ -1372,13 +1554,13 @@ Options:
   --order desc|asc      content search's sort direction (default: desc, best or newest first)
   --limit <n>           how many results content search, creatives list and campaigns return
   --max-seconds <n>     stop a runner's run after this many seconds, if that comes before its deadline
-  --workspace <slug>    the workspace whose worker worker promote and worker drop change
+  --workspace <slug>    for worker promote and worker drop: the workspace whose hand they change
   -h, --help            show this help
 
 skill publish, skill list and skill install <name> use the skill library, which takes the operator token in
 ${envPrefix}_OPERATOR_TOKEN instead of an API key, as do worker promote and worker drop. worker promote makes the
-version a worker is trying the one in use, there and on every worker of the skill on an older version; worker drop
-stops trying it.
+version a scheduled hand is trying the one in use, there and on every hand of the skill on an older version; worker
+drop stops trying it.
 
 runner and runner once take the runner token in ${RUNNER_TOKEN_ENV}. ${HARNESS_COMMAND_ENV}, if set, names a program
 the runner starts instead of Claude Code or Codex.
@@ -1391,6 +1573,7 @@ function parseOptions(argv) {
         allowPositionals: true,
         options: {
             format: { type: "string", default: "table" },
+            json: { type: "boolean", default: false },
             "api-url": { type: "string" },
             file: { type: "string", multiple: true },
             project: { type: "boolean", default: false },
@@ -1421,6 +1604,7 @@ function parseOptions(argv) {
             grain: { type: "string" },
             channel: { type: "string" },
             campaign: { type: "string" },
+            top: { type: "string" },
             name: { type: "string" },
             subject: { type: "string" },
             preview: { type: "string" },
@@ -1451,6 +1635,11 @@ function parseOptions(argv) {
             position: { type: "string" },
             plan: { type: "string" },
             version: { type: "string" },
+            "based-on": { type: "string" },
+            evidence: { type: "string" },
+            diff: { type: "string" },
+            funnel: { type: "string" },
+            step: { type: "string" },
             workspace: { type: "string" },
             "max-seconds": { type: "string" },
             help: { type: "boolean", short: "h", default: false },
@@ -1470,7 +1659,7 @@ function parseOptions(argv) {
         positionals,
         help: values.help,
         options: {
-            format: values.format,
+            format: values.json ? "json" : values.format,
             apiUrl: values["api-url"],
             file: values.file?.at(-1),
             files: values.file ?? [],
@@ -1503,6 +1692,7 @@ function parseOptions(argv) {
             grain: values.grain,
             channel: values.channel,
             campaign: values.campaign,
+            top: values.top,
             name: values.name,
             subject: values.subject,
             preview: values.preview,
@@ -1533,18 +1723,26 @@ function parseOptions(argv) {
             position: values.position,
             plan: values.plan,
             version: values.version,
+            basedOn: values["based-on"],
+            evidence: values.evidence,
+            diff: values.diff,
+            funnel: values.funnel,
+            step: values.step,
             workspace: values.workspace,
             maxSeconds,
         },
     };
 }
-/** Promotes or drops the candidate version of a workspace's worker for a skill, with the operator token. */
+/** Promotes or drops the candidate version of a workspace's scheduled hand for a skill, with the operator token. */
 async function changeCandidate(change, args, options) {
     if (args.length !== 1 || !options.workspace)
         throw new CliError(`Usage: worker ${change} <skill> --workspace <slug>`, exitCodes.usage);
     return api(await operatorConnection(options.apiUrl), `/api/operator/workers/${change}`, { workspace: options.workspace, skill: args[0] });
 }
 function findCommand(positionals) {
+    const three = positionals.slice(0, 3).join(" ");
+    if (Object.hasOwn(commands, three))
+        return { command: commands[three], args: positionals.slice(3) };
     const two = positionals.slice(0, 2).join(" ");
     if (Object.hasOwn(commands, two))
         return { command: commands[two], args: positionals.slice(2) };
@@ -1740,6 +1938,14 @@ async function uploadContentFile(connection, data, contentType) {
     await putSigned(upload.url, data, contentType);
     return upload.uploadId;
 }
+/** What the CLI says after a link: that its platform no longer lists it, or that it was edited there. */
+function linkNote(link) {
+    if (link.removedAt)
+        return ` (no longer on ${link.platform})`;
+    if (link.platformChangedAt)
+        return ` (changed on ${link.platform} since it was published)`;
+    return "";
+}
 function printContent(content, format) {
     if (format === "json")
         return printJson(content);
@@ -1758,7 +1964,7 @@ function printContent(content, format) {
         html: version.htmlUrl,
         files: version.media.length ? version.media.map((m) => m.url).join(" ") : null,
         links: item.links.length
-            ? item.links.map((l) => `${l.platform} ${l.objectType} ${l.externalId}${l.removedAt ? ` (no longer on ${l.platform})` : ""}`).join(", ")
+            ? item.links.map((l) => `${l.platform} ${l.objectType} ${l.externalId}${linkNote(l)}`).join(", ")
             : null,
         by: version.capturedBy,
         note: version.note,
@@ -1769,10 +1975,20 @@ function printContent(content, format) {
         deployments: content.deployments?.length ? content.deployments.map(deploymentLine).join(", ") : null,
         versions: content.versions && content.versions.length > 1 ? content.versions.length : null,
         transcript: content.transcripts?.map((t) => (t.text ? excerpt(t.text, 80) : t.status)).join(" | ") || null,
+        description: descriptionLine(content.descriptions?.find((d) => d.version === version.version)),
         ...scoreFields(content.scorecards ?? []),
     };
     printFields(rows);
 }
+/** The current version's picture description in one line: its kind, and the words printed on it. */
+function descriptionLine(d) {
+    if (!d)
+        return null;
+    if (!d.description)
+        return d.status;
+    const words = d.description.on_image_text.trim();
+    return words ? `${d.description.visual_kind}: "${excerpt(words, 80)}"` : d.description.visual_kind;
+}
 function printContentDiff(diff) {
     const stamp = (sign, v) => `${sign} version ${v.version}, ${v.capturedAt} by ${v.capturedBy}${v.note ? `: ${v.note}` : ""}`;
     const value = (v) => (typeof v === "string" ? v : JSON.stringify(v));
@@ -1794,6 +2010,10 @@ function printContentDiff(diff) {
         lines.push("", "No changes.");
     console.log(lines.join("\n"));
 }
+function feedsText(funnel) {
+    const sells = funnel.sellsOffer === null ? "" : `, which sells ${funnel.sellsOffer.name}`;
+    return `step ${funnel.step.position} (${funnel.step.name}) of ${funnel.name}${sells}`;
+}
 const planPath = (id) => `/api/v1/launch-plans/${encodeURIComponent(id)}`;
 function printPlan(plan, format) {
     if (format === "json")
@@ -1808,6 +2028,9 @@ function printPlan(plan, format) {
         status: plan.status,
         next: plan.moves.length ? plan.moves.join(", ") : null,
         by: plan.createdBy,
+        feeds: plan.funnel && feedsText(plan.funnel),
+        "funnel note": plan.funnelNote,
+        "funnel steps": plan.funnel?.steps.map((s) => `${s.position}. ${s.name}`).join(", "),
     });
     console.log("");
     if (plan.items.length === 0)
@@ -1816,12 +2039,12 @@ function printPlan(plan, format) {
 }
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const dollars = (cents) => `$${(cents / 100).toFixed(2)}`;
-/** The workspace's worker for the skill named `ref`, else the worker whose id it is: a skill's name may look like a uuid. */
+/** The workspace's scheduled hand for the skill named `ref`, else the one whose id it is: a skill's name may look like a uuid. */
 async function workerId(connection, ref) {
     const { workers } = await api(connection, "/api/v1/workers");
     const found = workers.find((w) => w.skill === ref) ?? workers.find((w) => w.id === ref.toLowerCase());
     if (!found)
-        throw new CliError(`unknown_worker: no worker with skill or id ${JSON.stringify(ref)} in this workspace`, exitCodes.error);
+        throw new CliError(`unknown_worker: no scheduled hand with skill or id ${JSON.stringify(ref)} in this workspace`, exitCodes.error);
     return found.id;
 }
 function workerRunRow(r) {
@@ -1921,6 +2144,27 @@ function printPublication(publication, format) {
         finished: publication.finishedAt,
     });
 }
+function printAdSetPublication(publication, format) {
+    if (format === "json")
+        return printJson({ adsetPublication: publication });
+    const { verification, budget } = publication;
+    printFields({
+        "adset publication": publication.id,
+        kind: publication.kind,
+        account: publication.accountId,
+        campaign: publication.campaignId,
+        source: publication.sourceAdsetId,
+        name: publication.name,
+        "external id": publication.externalId,
+        status: publication.status,
+        error: publication.error,
+        verified: verification && (verification.ok ? "yes" : `no: ${verification.problems.join("; ")}`),
+        budget: budget && (budget.dailyBudget !== null ? `${budget.dailyBudget} a day` : budget.lifetimeBudget !== null ? `${budget.lifetimeBudget} lifetime` : "the campaign's"),
+        recorded: publication.recordedAt,
+        sent: publication.sentAt,
+        finished: publication.finishedAt,
+    });
+}
 async function readToolInput(options) {
     let text;
     if (options.input !== undefined)
@@ -2047,6 +2291,53 @@ function decodeLinkPath(encoded) {
         throw new CliError(`"${excerpt(encoded)}" is not a valid asset link.`, exitCodes.usage);
     }
 }
+async function saveFile(path, content) {
+    await writeFileAtomic(path, content, 0o644).catch((error) => {
+        if (error.code === "ENOENT")
+            throw new CliError(`No folder at ${dirname(path)} to save into.`, exitCodes.usage);
+        throw error;
+    });
+}
+/** Saves every row the server returned: CSV for a `.csv` path, otherwise the response body as it came. */
+async function saveQueryResult(text, out, format) {
+    const path = await savePath(out, "results.json");
+    const result = queryResultWithExactNumbers(text);
+    await saveFile(path, extname(path).toLowerCase() === ".csv" ? toCsv(text) : text);
+    if (format === "json")
+        printJson({ path: resolve(path), rowCount: result.rows.length, truncated: result.truncated });
+    else
+        console.log(`Saved ${rowCount(result.rows.length)} to ${path}`);
+    warnIfTruncated(result);
+}
+/** Top-level numbers keep the digits the server sent, so a numeric column is never rounded. */
+function queryResultWithExactNumbers(text) {
+    const result = JSON.parse(text);
+    const exact = JSON.parse(text, keepNumberDigits);
+    const rows = result.rows.map((row, i) => Object.fromEntries(Object.entries(row).map(([k, v]) => [k, typeof v === "number" ? exact.rows[i][k] : v])));
+    return { ...result, rows };
+}
+function rowCount(n) {
+    return `${n.toLocaleString("en-US")} ${n === 1 ? "row" : "rows"}`;
+}
+function warnIfTruncated(result) {
+    if (result.truncated)
+        console.error(`Results were cut off (${result.truncated}). Aggregate in SQL or add LIMIT.`);
+}
+/** Every number keeps the digits the server sent, nested ones too, and json columns are written as JSON text. */
+function toCsv(text) {
+    const result = JSON.parse(text, keepRawNumbers);
+    const json = new Set(result.columns.filter((c) => c.type === "json" || c.type === "jsonb").map((c) => c.name));
+    const field = (name, value) => (value != null && json.has(name) ? JSON.stringify(value) : cell(value));
+    const names = result.columns.map((c) => c.name);
+    const line = (values) => values.map(csvField).join(",");
+    return [line(names), ...result.rows.map((row) => line(names.map((name) => field(name, row[name]))))].map((l) => `${l}\n`).join("");
+}
+function keepRawNumbers(_key, value, context) {
+    return typeof value === "number" && context?.source !== undefined ? JSON.rawJSON(context.source) : value;
+}
+function csvField(value) {
+    return /[",\r\n]/.test(value) ? `"${value.replaceAll('"', '""')}"` : value;
+}
 /** `--out` names the file, or an existing folder to save into under the default name. */
 async function savePath(out, fileName) {
     if (out === undefined)
@@ -2074,6 +2365,13 @@ function openFile(path) {
     child.unref();
 }
 const INTAKE_PATH = "/api/v1/intake-endpoints";
+const FUNNELS_PATH = "/api/v1/funnels";
+function wholeNumber(value, flag) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1)
+        throw new CliError(`${flag} must be a whole number from 1.`, exitCodes.usage);
+    return n;
+}
 const intakePath = (id) => `${INTAKE_PATH}/${encodeURIComponent(id)}`;
 function parseRetentionDays(text) {
     const days = Number(text);