@letterstory/cli 0.36.1 → 0.38.0

package/README.md

@@ -324,6 +324,29 @@ letterstory admin ask "which clients published nothing in the last 30 days?" --s
 This is the headless half of `/superadmin/ask` — same function, same schema — so a
 long-running agent can watch the fleet on a schedule without a browser.
 
+### Staff: kernel experiments
+
+```bash
+# Needs a STAFF key with the tuning:experiment capability. A key always acts as an
+# agent: it can propose, plan, note, spend and conclude, never approve a plan.
+export LETTERSTORY_STAFF_API_KEY=<your staff key with tuning:experiment>
+
+letterstory admin tuning-context --q "colons"          # what the agent knows (JSON)
+letterstory admin experiments list --q colons          # what we've tried
+letterstory admin experiments new "We use too many colons" --as "claude-code"
+letterstory admin experiments update <id> --plan-file plan.json --budget 120
+# ...a person approves the plan in Kernel Tuning -> Experiments...
+letterstory admin experiments spend <id> 54
+letterstory admin tuning-import lab/results/colons/publish/<brief>.json --experiment <id>
+letterstory admin experiments conclude <id> --decision drop \
+  --conclusion "Colons fell 60%; P(machine) did not move; quality held." \
+  --evidence lab:"kernels lab/results/colons/report.md"
+```
+
+The ledger behind Kernel Tuning's Experiments tab
+(docs/architecture/kernel-experiment-agent.md): every question asked of the kernels,
+how it was tested, and what we learned and why.
+
 ### Propose, then onboard a phantom
 
 The Fleet wizard's Plan and Name screens as two commands: pick the beat, then the name,

package/lib/cli.mjs

@@ -41,13 +41,16 @@ import {
 	cmdShredder,
 	cmdLede,
 	cmdLandings,
+	cmdSequences,
+	cmdProspects,
+	cmdMail,
 	cmdAdmin,
 	cmdFeedback,
 	cmdOfferings,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.36.1";
+export const VERSION = "0.38.0";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -101,8 +104,18 @@ const BOOLEAN_FLAGS = new Set([
 	"clear-topics",
 	"clear-stances",
 	"clear-avoid",
+	// `lede run --diverse`, `--high-temp`, their `--no-*` negations and `--no-enrich`
+	// are value-less and can sit next to the endpoint id or another value; without
+	// these the parser eats the following token.
+	"diverse",
+	"no-diverse",
+	"high-temp",
+	"no-high-temp",
+	"no-enrich",
 	// `offerings set-collection <id> --none` (the org itself is the subject again).
 	"none",
+	// `prospects import|source --one-per-company`.
+	"one-per-company",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -506,6 +519,24 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        read-only SQL across every org; --sql prints
                                                        the queries behind the answer. Needs the
                                                        fleet:query capability on the staff key.
+  admin experiments list [--q colons] [--status proposed] | show <id>
+          | new "<question>" [--hypothesis …] [--plan-file p.json] [--tags a,b] [--as "<agent>"]
+          | update <id> [--plan-file …] [--result-file …] [--evidence kind:ref,…] [--budget N]
+          | note|started <id> "<text>" | spend <id> <runs>
+          | conclude <id> --decision ship|drop|follow-up|inconclusive --conclusion "…" [--evidence …]
+          | abandon <id> --reason "…"
+                                                       The kernel experiment ledger: what we tried,
+                                                       how, what it found and why. Approving a plan
+                                                       stays with a signed-in person. Needs the
+                                                       tuning:experiment capability.
+  admin tuning-import <brief-results.json> [--experiment <id>]
+                                                       One brief's kernels lab results as a console
+                                                       session (a trial per arm), linked to its
+                                                       ledger entry. Written by \`npm run lab --
+                                                       publish\` in the kernels repo.
+  admin tuning-context [--q "<question>"]              The experiment agent's context pack (JSON):
+                                                       the pipeline as deployed, levers, measures,
+                                                       goals, related history.
   admin create-org --domain <bare-domain> [--name "Acme"] [--test] [--no-key]
           [--key-name N] [--capabilities a,b] [--onboard] [--watch] [+ the onboard domain flags]
                                                        The key exchange: create the client org from
@@ -624,6 +655,8 @@ Ledes (opening lines for cold email, chosen per prospect from a hand-approved li
            [--years <n>] [--linkedin <url>] [--notes <text>]
            [--candidates <1..10>] [--tone warm|direct|playful|formal] [--no-enrich]
            [--deadline-ms <2000..120000>]
+           [--default-lede <line>] [--disable-lede <id>]... [--diverse [--recent-lede <id>]...]
+           [--high-temp|--no-high-temp]
                                                        Synchronous: prints the candidate lines with the
                                                        top choice flagged. Needs at least one of
                                                        --first-name, --name, --email, --company or
@@ -632,10 +665,39 @@ Ledes (opening lines for cold email, chosen per prospect from a hand-approved li
                                                        lookup when latency matters more than fit.
                                                        --deadline-ms leaves out evidence that cannot
                                                        arrive in time (fewer lines may qualify).
+                                                       --disable-lede keeps a library line out (by id,
+                                                       repeatable). --diverse gently rotates away from
+                                                       recently used lines; pass the ids your sequence
+                                                       already sent with --recent-lede (repeatable), or
+                                                       omit them to count the endpoint's own recent runs.
+                                                       --high-temp writes one strictly checked opener
+                                                       (marked generated) when no library line qualifies;
+                                                       the --no-* spellings override endpoint defaults.
   lede runs [--endpoint <id>] [--limit <n>]            Recent lede calls (telemetry), newest first
   lede history [<domain>] [--days <n>] [--limit <n>]   Openers already sent to an account
   lede evals [--sweep]                                 Lede quality evals still above zero
   lede balance                                         Ledes left on this org
+  lede library list                                    The org's opener library: pre-built + custom lines
+  lede library create --text <line> [--alts <v>]... [--peer-alts <v>]... [--requires <trigger>]...
+           [--threshold <0..100>] [--tone warm|direct|playful|formal] [--tag <t>]...
+                                                       Add a custom line. A {{placeholder}} must appear in
+                                                       --requires; proprietary-engine triggers stay
+                                                       reserved for the pre-built lines. --threshold
+                                                       nudges the trigger's gate strictness around the
+                                                       engine default: 50 = default, higher = pickier,
+                                                       lower = looser.
+  lede library update <lede-id> [--text <line>] [--alts <v>]... [--peer-alts <v>]...
+           [--requires <trigger>]... [--threshold <0..100>] [--tone <t>] [--tag <t>]...
+                                                       Edit a line; only the flags you pass change
+  lede library enable <lede-id>                        Make a line a run candidate again
+  lede library disable <lede-id>                       Keep a line out of runs (reversible; the way to
+                                                       retire a pre-built line)
+  lede library delete <lede-id> --yes                  Delete a line (a deleted pre-built re-seeds at its
+                                                       seed wording on the next list)
+  lede library rewrite --voice <description> [--ids <lede-id>]...
+                                                       Propose brand-voice rewrites of the wording only.
+                                                       Applies nothing: accept a proposal with
+                                                       lede library update --text/--alts
 
 Landings (a link + context; auto-mentioned in articles by collections you enable):
   landings list                                        Your landing pages + mention counts
@@ -645,6 +707,41 @@ Landings (a link + context; auto-mentioned in articles by collections you enable
   landings update <landing-id> [--link <url>] [--context <text>|--file <path>]
   landings delete <landing-id> --yes
 
+Sequences (multi-step cold email sent from your mailers; approving or enrolling SENDS):
+  sequences list                                       Your sequences + per-step funnel
+  sequences get <sequence-id>                          Flow, enrollments, who replied at each step
+  sequences create --name <n> (--flow '<json>'|--flow-file <path>) [--mailer <mailer-id>]...
+                                                       New draft sequence (nothing sends yet)
+  sequences update <sequence-id> [--name <n>] [--flow '<json>'|--flow-file <path>]
+           [--status draft|active|paused|archived] [--mailer <mailer-id>]...
+  sequences pause|resume <sequence-id>                 Stop / restart sending
+  sequences enroll <sequence-id> (--list <list-id> | --email <addr>... | --recipients '<json>'|--recipients-file <path>)
+  sequences stop <sequence-id> <enrollment-id>         Stop one recipient
+  sequences review list                                Emails waiting for a decision
+  sequences review edit <item-id> [--subject <s>] [--body <text>|--file <path>]
+  sequences review approve|skip|delete <item-id>       Decide one (approve sends now)
+  sequences links list                                 Live Pocket Dispatch links (no tokens)
+  sequences links create --days <1..3>                 Mint a no-login review link (shown once)
+  sequences links revoke <link-id> --yes
+
+Prospects (who you write to):
+  prospects lists                                      Your lists + counts
+  prospects list <list-id>                             One list
+  prospects ls [--list <list-id>] [--status <s>] [--q <search>] [--limit <n>]
+  prospects get <prospect-id>
+  prospects create-list --name <n>
+  prospects import --csv-file <path|-> [--list <list-id>|--list-name <n>] [--one-per-company]
+  prospects source --description <who you want> [--list <list-id>|--list-name <n>] [--limit <1..100>]
+           [--one-per-company]                         Fill a list from paid data providers (background)
+  prospects enrich [--list <list-id>] [--status <s>] [--q <search>]
+                                                       Funding + competitors for un-enriched rows
+  prospects update <prospect-id> [--status new|contacted|replied|unsubscribed|archived] [--name <n>]
+           [--first-name] [--last-name] [--title] [--company] [--website] [--linkedin] [--school]
+           [--city] [--country] [--years] [--notes] [--custom key=value]...
+
+Mail:
+  mail connections                                     Connected mailboxes, Google connect + Vercel key status
+
 Insights:
   insights site [--period 14d|30d|90d] [--collection <uuid>]
   insights post <article-id> [--period 14d|30d|90d]
@@ -722,6 +819,9 @@ const CLIENT_COMMANDS = {
 	lede: cmdLede,
 	ledes: cmdLede,
 	landings: cmdLandings,
+	sequences: cmdSequences,
+	prospects: cmdProspects,
+	mail: cmdMail,
 	feedback: cmdFeedback,
 	// Platform-scoped (staff key) — the only commands that act BEFORE an org exists.
 	admin: cmdAdmin,

package/lib/commands/admin.mjs

@@ -4,6 +4,9 @@
 // routes, because they exist precisely to act BEFORE an org exists.
 //
 //   admin ask "which kernels are hooked up to the most clients?" [--sql] [--json]
+//   admin experiments list|show|new|update|note|started|spend|conclude|abandon …   (tuning:experiment)
+//   admin tuning-context [--q "<question>"]                                         (tuning:experiment)
+//   admin tuning-import <brief-results.json> [--experiment <id>]                    (tuning:experiment)
 //   admin create-org --domain acme.com [--name "Acme"] [--test] [--no-key] [--key-name N]
 //                    [--capabilities a,b] [--onboard] [--about "…"] [--sitemap <url>]
 //                    [--cms <provider>] [--posts N] [--seers suggest|skip] [--no-visuals]
@@ -26,6 +29,7 @@
 // The staff key comes from --staff-key or LETTERSTORY_STAFF_API_KEY; the base URL from the
 // usual --url / LETTERSTORY_API_URL / config resolution.
 
+import { readFileSync } from "node:fs";
 import { CliError, LetterstoryClient } from "../client.mjs";
 import { flagStr, flagNum, flagBool, flagList, printResult, compact, ok } from "./shared.mjs";
 import { watchDomainJob } from "./onboard.mjs";
@@ -46,12 +50,17 @@ function staffKeyFrom(flags) {
 
 /** POST a superadmin route with the staff key; surfaces the server's error text on non-2xx. */
 async function staffPost(ctx, path, body) {
+	return staffRequest(ctx, "POST", path, body);
+}
+
+/** Any method against a superadmin route with the staff key. */
+async function staffRequest(ctx, method, path, body) {
 	const { client, flags } = ctx;
 	const url = `${client.url}${path}`;
 	const res = await client.fetch(url, {
-		method: "POST",
+		method,
 		headers: { "content-type": "application/json", "x-staff-api-key": staffKeyFrom(flags) },
-		body: JSON.stringify(body),
+		...(body === undefined ? {} : { body: JSON.stringify(body) }),
 	});
 	let payload = null;
 	try {
@@ -220,11 +229,195 @@ async function cmdAdminAsk(ctx) {
 	}
 }
 
+/* ------------------------------------------------------------ kernel experiments */
+
+const EXPERIMENTS = "/api/superadmin/tuning/experiments";
+
+/** `--as "<agent name>"` records the actor as that agent; a staff key always acts as an agent. */
+function actorFrom(flags) {
+	const as = flagStr(flags.as);
+	return as ? { kind: "agent", label: as } : undefined;
+}
+
+/** A JSON object from `--<name>-file <path>` (or `-` for stdin is not supported: pass a file). */
+function jsonFile(flags, name) {
+	const path = flagStr(flags[`${name}-file`]);
+	if (!path) return undefined;
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		throw new CliError(`--${name}-file ${path}: ${err.message}`);
+	}
+}
+
+/** `--evidence kind:ref[,kind:ref…]`, e.g. `lab:kernels lab/results/colons/report.md,session:<uuid>`. */
+function evidenceFrom(flags) {
+	const items = flagList(flags.evidence);
+	if (!items?.length) return undefined;
+	return items.map((item) => {
+		const at = item.indexOf(":");
+		if (at < 1) throw new CliError(`--evidence items are kind:ref, got "${item}"`);
+		return { kind: item.slice(0, at), ref: item.slice(at + 1) };
+	});
+}
+
+function experimentLine(e) {
+	const decision = e.decision ? ` → ${e.decision}` : "";
+	return `${e.id}  [${e.status}${decision}]  ${e.question}${e.gist ? `\n    ${e.gist}` : ""}`;
+}
+
+/**
+ * `admin experiments …` — the experiment ledger (docs/architecture/kernel-experiment-agent.md),
+ * the headless half of the tuning console's Experiments tab. Needs `tuning:experiment` on the key.
+ */
+async function cmdAdminExperiments(ctx) {
+	const [sub, id, ...rest] = ctx.positionals;
+	const { flags, io } = ctx;
+	const json = flagBool(flags.json);
+	const out = (result, line) => (json ? printResult(io, flags, result) : io.log(line(result)));
+	const one = (r) => {
+		const e = r.experiment;
+		const lines = [experimentLine(e)];
+		if (e.restated) lines.push(`  hypothesis: ${e.restated}`);
+		if (e.plan) lines.push(`  plan: ${JSON.stringify(e.plan)}`);
+		lines.push(`  runs: ${e.runsSpent} of ${e.budgetRuns}`);
+		for (const ev of e.events ?? [])
+			lines.push(`  ${ev.at}  ${ev.kind}  ${ev.actorLabel ?? ev.actorKind}${ev.text ? `: ${ev.text}` : ""}`);
+		return lines.join("\n");
+	};
+	switch (sub) {
+		case "list": {
+			const params = new URLSearchParams(
+				compact({ q: flagStr(flags.q), status: flagStr(flags.status), limit: flagStr(flags.limit) })
+			);
+			const result = await staffRequest(ctx, "GET", `${EXPERIMENTS}?${params}`);
+			return out(result, (r) =>
+				r.experiments.length ? r.experiments.map(experimentLine).join("\n") : "(no experiments)"
+			);
+		}
+		case "show":
+			if (!id) throw new CliError("Usage: admin experiments show <id>");
+			return out(await staffRequest(ctx, "GET", `${EXPERIMENTS}/${id}`), one);
+		case "new": {
+			const question = [id, ...rest].filter(Boolean).join(" ").trim();
+			if (question.length < 3)
+				throw new CliError('Usage: admin experiments new "<question>" [--plan-file plan.json] [--tags a,b]');
+			const body = compact({
+				question,
+				restated: flagStr(flags.hypothesis),
+				plan: jsonFile(flags, "plan"),
+				method: flagStr(flags.method),
+				tags: flagList(flags.tags),
+				builds_on: flagList(flags["builds-on"]),
+				evidence: evidenceFrom(flags),
+				actor: actorFrom(flags),
+			});
+			return out(await staffRequest(ctx, "POST", EXPERIMENTS, body), one);
+		}
+		case "update": {
+			if (!id)
+				throw new CliError(
+					"Usage: admin experiments update <id> [--hypothesis …] [--plan-file …] [--result-file …] [--evidence kind:ref,…]"
+				);
+			const body = compact({
+				restated: flagStr(flags.hypothesis),
+				plan: jsonFile(flags, "plan"),
+				measures: jsonFile(flags, "measures"),
+				result: jsonFile(flags, "result"),
+				method: flagStr(flags.method),
+				tags: flagList(flags.tags),
+				budget_runs: flagNum(flags.budget),
+				engine_build: flagStr(flags.build),
+				add_evidence: evidenceFrom(flags),
+				actor: actorFrom(flags),
+			});
+			return out(await staffRequest(ctx, "PATCH", `${EXPERIMENTS}/${id}`, body), one);
+		}
+		case "note":
+		case "started": {
+			const text = rest.join(" ").trim();
+			if (!id || (sub === "note" && !text)) throw new CliError(`Usage: admin experiments ${sub} <id> "<text>"`);
+			const body = compact({ kind: sub, text: text || undefined, actor: actorFrom(flags) });
+			return out(await staffRequest(ctx, "POST", `${EXPERIMENTS}/${id}/events`, body), one);
+		}
+		case "spend": {
+			const runs = Number(rest[0]);
+			if (!id || !Number.isInteger(runs) || runs < 1)
+				throw new CliError("Usage: admin experiments spend <id> <runs> [--text …]");
+			const body = compact({ kind: "spend", runs, text: flagStr(flags.text), actor: actorFrom(flags) });
+			return out(await staffRequest(ctx, "POST", `${EXPERIMENTS}/${id}/events`, body), one);
+		}
+		case "conclude": {
+			const decision = flagStr(flags.decision);
+			const conclusion = flagStr(flags.conclusion);
+			if (!id || !decision || !conclusion)
+				throw new CliError(
+					'Usage: admin experiments conclude <id> --decision ship|drop|follow-up|inconclusive --conclusion "<what we learned and why>" [--evidence kind:ref,…] [--result-file r.json]'
+				);
+			const body = compact({
+				action: "conclude",
+				decision,
+				conclusion,
+				result: jsonFile(flags, "result"),
+				add_evidence: evidenceFrom(flags),
+				actor: actorFrom(flags),
+			});
+			return out(await staffRequest(ctx, "POST", `${EXPERIMENTS}/${id}/decide`, body), one);
+		}
+		case "abandon": {
+			const reason = flagStr(flags.reason);
+			if (!id || !reason) throw new CliError('Usage: admin experiments abandon <id> --reason "<why>"');
+			const body = compact({ action: "abandon", reason, actor: actorFrom(flags) });
+			return out(await staffRequest(ctx, "POST", `${EXPERIMENTS}/${id}/decide`, body), one);
+		}
+		default:
+			throw new CliError(
+				"Usage: admin experiments list|show|new|update|note|started|spend|conclude|abandon (see --help)"
+			);
+	}
+}
+
+/**
+ * `admin tuning-import <file.json>` — one brief's kernels lab results into a console session
+ * (the lab's `publish` writes these files; the body is POST /api/superadmin/tuning/lab-import's).
+ */
+async function cmdAdminTuningImport(ctx) {
+	const path = ctx.positionals[0];
+	if (!path) throw new CliError("Usage: admin tuning-import <brief-results.json> [--experiment <id>]");
+	let body;
+	try {
+		body = JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		throw new CliError(`${path}: ${err.message}`);
+	}
+	const experiment = flagStr(ctx.flags.experiment);
+	if (experiment) body.experiment_id = experiment;
+	const result = await staffRequest(ctx, "POST", "/api/superadmin/tuning/lab-import", body);
+	if (flagBool(ctx.flags.json)) return printResult(ctx.io, ctx.flags, result);
+	ctx.io.log(
+		`${result.trials} trials, ${result.runs} runs → ${ctx.client.url}/superadmin/tuning/${result.sessionId}`
+	);
+}
+
+/** `admin tuning-context [--q "<question>"]` — the experiment agent's context pack, as JSON. */
+async function cmdAdminTuningContext(ctx) {
+	const q = flagStr(ctx.flags.q) || ctx.positionals.join(" ").trim() || undefined;
+	const params = q ? `?${new URLSearchParams({ q })}` : "";
+	printResult(
+		ctx.io,
+		{ ...ctx.flags, json: true },
+		await staffRequest(ctx, "GET", `/api/superadmin/tuning/context${params}`)
+	);
+}
+
 export async function cmdAdmin(ctx) {
 	const sub = ctx.positionals[0];
 	if (sub === "create-org") return cmdAdminCreateOrg({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "ask") return cmdAdminAsk({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "experiments") return cmdAdminExperiments({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "tuning-context") return cmdAdminTuningContext({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "tuning-import") return cmdAdminTuningImport({ ...ctx, positionals: ctx.positionals.slice(1) });
 	throw new CliError(
-		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" (see --help)'
+		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin tuning-context (see --help)'
 	);
 }

package/lib/commands/lede.mjs

@@ -59,6 +59,15 @@ export const ARGS = {
 		enrich: { value: (flags) => (flags["no-enrich"] === true ? false : undefined) },
 		// A latency budget: optional evidence that cannot arrive in time is left out.
 		deadline_ms: { flag: "deadline-ms", type: "num" },
+		// Advanced: keep specific library lines out of this run (repeatable, by line id).
+		disabled_ledes: { flag: "disable-lede", type: "list" },
+		// Gently rotate away from openers this endpoint (or --recent-lede) already used.
+		// The negate spelling exists so a call can override an endpoint default to OFF.
+		optimize_diversity: { flag: "diverse", type: "bool", negate: "no-diverse" },
+		// The line ids this sequence already used (repeatable); counted by --diverse.
+		recent_ledes: { flag: "recent-lede", type: "list" },
+		// When no library line qualifies, WRITE one (strictly checked, marked generated).
+		high_temperature: { flag: "high-temp", type: "bool", negate: "no-high-temp" },
 	},
 	list_lede_runs: {
 		endpoint_id: "endpoint",
@@ -108,6 +117,42 @@ export const ARGS = {
 		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
 		config: { value: (flags) => readJsonFileFlag(flags, "file") },
 	},
+	// The editable library (`lede library ...`): the org's own opening lines, pre-built
+	// and custom. Reads seed the pre-built set idempotently; writes are validated server-
+	// side (known triggers, placeholder coverage, the custom-line engine ban).
+	list_ledes: {},
+	create_lede: {
+		text: { flag: "text", required: true },
+		alts: { flag: "alts", type: "list" },
+		peer_alts: { flag: "peer-alts", type: "list" },
+		requires: { flag: "requires", type: "list" },
+		// 0-100 strictness around the engine default (50): higher = pickier, lower = looser.
+		threshold: { flag: "threshold", type: "num" },
+		tone: { flag: "tone", enum: ["warm", "direct", "playful", "formal"] },
+		tags: { flag: "tag", type: "list" },
+	},
+	update_lede: {
+		id: { positional: 0, label: "lede-id", required: true },
+		text: "text",
+		alts: { flag: "alts", type: "list" },
+		peer_alts: { flag: "peer-alts", type: "list" },
+		requires: { flag: "requires", type: "list" },
+		threshold: { flag: "threshold", type: "num" },
+		tone: { flag: "tone", enum: ["warm", "direct", "playful", "formal"] },
+		tags: { flag: "tag", type: "list" },
+	},
+	set_lede_enabled: {
+		id: { positional: 0, label: "lede-id", required: true },
+		// `lede library enable|disable <id>` decides this; the subcommand passes it in.
+		enabled: { value: (_flags, _positionals, extra) => extra.enabled },
+	},
+	delete_lede: {
+		id: { positional: 0, label: "lede-id", required: true },
+	},
+	rewrite_ledes_voice: {
+		voice: { flag: "voice", required: true },
+		ids: { flag: "ids", type: "list" },
+	},
 };
 
 export async function cmdLede(ctx) {
@@ -125,6 +170,9 @@ export async function cmdLede(ctx) {
 			return ledeDelete(rest);
 		case "endpoint":
 			return ledeEndpoint(rest);
+		case "library":
+		case "lib":
+			return ledeLibrary(rest);
 		case "run":
 			return ledeRun(rest);
 		case "runs":
@@ -145,7 +193,103 @@ export async function cmdLede(ctx) {
 			return ledeFunnel(rest);
 		default:
 			throw new CliError(
-				`Unknown lede subcommand: ${sub ?? "(none)"}. Try: list, create, delete, endpoint, run, runs, history, evals, balance, outcome, funnel`
+				`Unknown lede subcommand: ${sub ?? "(none)"}. Try: list, create, delete, endpoint, library, run, runs, history, evals, balance, outcome, funnel`
+			);
+	}
+}
+
+/**
+ * `lede library list|create|update|enable|disable|delete|rewrite` — the org's own opener
+ * library (pre-built lines seeded on first read, plus lines the org authors). Runs pick
+ * only from enabled lines; `rewrite` only PROPOSES new wordings, and an accepted proposal
+ * is applied with `lede library update`.
+ */
+async function ledeLibrary(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const action = positionals[0];
+	const rest = { ...ctx, positionals: positionals.slice(1) };
+	switch (action) {
+		case "list":
+		case "ls": {
+			const result = await client.callTool("list_ledes", argsFromFlags(ARGS.list_ledes, flags));
+			// One line per row: state, id, provenance, then the wording. `--json` for the rest
+			// (alts, requires, threshold, tags) when editing.
+			printResult(io, flags, result, (r) =>
+				(r?.ledes ?? [])
+					.map(
+						(l) =>
+							`${l.enabled ? "on " : "off"}  ${l.id}  [${l.source}${l.engine ? `/${l.engine}` : ""}]  ${l.text}`
+					)
+					.join("\n")
+			);
+			return 0;
+		}
+		case "create":
+		case "new":
+		case "add": {
+			const args = argsFromFlags(ARGS.create_lede, flags, rest.positionals);
+			const result = await client.callTool("create_lede", args);
+			ok(ctx, "Added the line to the library.");
+			printResult(io, flags, result);
+			return 0;
+		}
+		case "update":
+		case "edit": {
+			const args = argsFromFlags(ARGS.update_lede, flags, rest.positionals);
+			const result = await client.callTool("update_lede", args);
+			ok(ctx, `Updated line ${args.id}.`);
+			printResult(io, flags, result);
+			return 0;
+		}
+		case "enable":
+		case "disable": {
+			const enabled = action === "enable";
+			const args = argsFromFlags(ARGS.set_lede_enabled, flags, rest.positionals, { enabled });
+			const result = await client.callTool("set_lede_enabled", args);
+			ok(ctx, `${enabled ? "Enabled" : "Disabled"} line ${args.id}.`);
+			printResult(io, flags, result);
+			return 0;
+		}
+		case "delete":
+		case "rm": {
+			const id = requirePositional(rest.positionals, 0, "lede-id");
+			if (!flags.yes) {
+				io.error(`Re-run with --yes to confirm: ${ctx.bin} lede library delete ${id} --yes`);
+				return 1;
+			}
+			const result = await client.callTool(
+				"delete_lede",
+				argsFromFlags(ARGS.delete_lede, flags, rest.positionals)
+			);
+			ok(
+				ctx,
+				"Line deleted. A pre-built line re-seeds at its seed wording on the next list; disable instead to keep one out."
+			);
+			printResult(io, flags, result);
+			return 0;
+		}
+		case "rewrite": {
+			const args = argsFromFlags(ARGS.rewrite_ledes_voice, flags, rest.positionals);
+			const result = await client.callTool("rewrite_ledes_voice", args);
+			// Nothing is applied: print the proposals for a human to vouch for, with the
+			// command that applies an accepted one.
+			printResult(io, flags, result, (r) => {
+				const proposals = (r?.proposals ?? []).map((p) => `${p.id}\n   ${p.text}`);
+				const rejected = (r?.rejected ?? []).map((x) => `${x.id}: ${(x.reasons ?? []).join("; ")}`);
+				const parts = [];
+				parts.push(
+					proposals.length
+						? `Proposed rewrites (nothing applied; accept one with: ${ctx.bin} lede library update <lede-id> --text "..."):\n${proposals.join("\n")}`
+						: "No rewrite cleared the checks; the originals stand."
+				);
+				if (rejected.length) parts.push(`Rejected (original stands):\n${rejected.join("\n")}`);
+				return parts.join("\n\n");
+			});
+			return 0;
+		}
+		default:
+			throw new CliError(
+				`Unknown lede library action: ${action ?? "(none)"}. Try: list, create, update, enable, disable, delete, rewrite`
 			);
 	}
 }
@@ -257,7 +401,8 @@ async function ledeRun(ctx) {
 			return "No line cleared the confidence floor for this person (not charged). More fields usually turn this into a match.";
 		}
 		const lines = (r?.candidates ?? []).map(
-			(c, i) => `${i + 1}. ${c.text}  [${Math.round((c.confidence ?? 0) * 100)}%${c.top ? ", top choice" : ""}]`
+			(c, i) =>
+				`${i + 1}. ${c.text}  [${Math.round((c.confidence ?? 0) * 100)}%${c.top ? ", top choice" : ""}${c.generated ? ", written for this prospect" : ""}]`
 		);
 		const prefix =
 			r?.status === "no_match"

package/lib/commands/outbound.mjs

@@ -0,0 +1,324 @@
+// `sequences`, `prospects` and `mail` — the outbound email stack, as thin wrappers
+// over the MCP tools, which call the same lib functions the app's /api/sequences
+// and /api/prospects routes do. Every call is built from the ARGS map below, so
+// `scripts/parity-check.ts` can hold each command to its tool's input schema.
+
+import { CliError } from "../client.mjs";
+import {
+	flagStr,
+	flagList,
+	requirePositional,
+	printResult,
+	argsFromFlags,
+	refuseUnknownFlags,
+	readTextInput,
+	ok,
+} from "./shared.mjs";
+
+// A JSON document from --<name> '<json>' or --<name>-file <path|->.
+function jsonInput(flag) {
+	return (flags) => {
+		const raw = readTextInput(flags, flag, `${flag}-file`);
+		if (raw === undefined) return undefined;
+		try {
+			return JSON.parse(raw);
+		} catch (err) {
+			throw new CliError(`--${flag} is not valid JSON: ${err.message}`);
+		}
+	};
+}
+
+// Recipients from repeatable --email <addr>, or a JSON array via --recipients/--recipients-file.
+function readRecipients(flags) {
+	const fromJson = jsonInput("recipients")(flags);
+	if (fromJson !== undefined) return fromJson;
+	const emails = flagList(flags.email);
+	return emails.length ? emails.map((email) => ({ email })) : undefined;
+}
+
+// `--custom key=value` (repeatable) → { key: value }.
+function readCustom(flags) {
+	const entries = flagList(flags.custom);
+	if (!entries.length) return undefined;
+	const out = {};
+	for (const entry of entries) {
+		const i = entry.indexOf("=");
+		if (i <= 0) throw new CliError(`--custom takes key=value (got ${entry})`);
+		out[entry.slice(0, i)] = entry.slice(i + 1);
+	}
+	return out;
+}
+
+const SEQUENCE_STATUSES = ["draft", "active", "paused", "archived"];
+const PROSPECT_STATUSES = ["new", "contacted", "replied", "unsubscribed", "archived"];
+const mailerIds = {
+	value: (flags) => {
+		const ids = flagList(flags.mailer);
+		return ids.length ? ids : undefined;
+	},
+};
+
+// How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
+export const ARGS = {
+	list_sequences: {},
+	get_sequence: {
+		sequence_id: { positional: 0, label: "sequence-id", required: true },
+	},
+	create_sequence: {
+		name: { flag: "name", required: true },
+		flow: {
+			value: (flags) => {
+				const flow = jsonInput("flow")(flags);
+				if (flow === undefined) throw new CliError("Missing required --flow '<json>' (or --flow-file <path>)");
+				return flow;
+			},
+		},
+		mailer_ids: mailerIds,
+	},
+	update_sequence: {
+		sequence_id: { positional: 0, label: "sequence-id", required: true },
+		name: "name",
+		flow: { value: jsonInput("flow") },
+		status: { flag: "status", enum: SEQUENCE_STATUSES },
+		mailer_ids: mailerIds,
+	},
+	enroll_in_sequence: {
+		sequence_id: { positional: 0, label: "sequence-id", required: true },
+		recipients: { value: readRecipients },
+		list_id: "list",
+	},
+	stop_sequence_enrollment: {
+		sequence_id: { positional: 0, label: "sequence-id", required: true },
+		enrollment_id: { positional: 1, label: "enrollment-id", required: true },
+	},
+	list_review_items: {},
+	update_review_item: {
+		item_id: { positional: 0, label: "item-id", required: true },
+		subject: "subject",
+		body: { value: (flags) => readTextInput(flags, "body", "file") },
+	},
+	decide_review_item: {
+		item_id: { positional: 0, label: "item-id", required: true },
+		action: { flag: "action", required: true, enum: ["approve", "skip", "delete"] },
+	},
+	list_dispatch_links: {},
+	create_dispatch_link: {
+		days: { flag: "days", type: "num", required: true },
+	},
+	revoke_dispatch_link: {
+		link_id: { positional: 0, label: "link-id", required: true },
+	},
+	list_prospect_lists: {},
+	get_prospect_list: {
+		list_id: { positional: 0, label: "list-id", required: true },
+	},
+	list_prospects: {
+		list_id: "list",
+		status: { flag: "status", enum: PROSPECT_STATUSES },
+		q: "q",
+		limit: { flag: "limit", type: "num" },
+	},
+	get_prospect: {
+		prospect_id: { positional: 0, label: "prospect-id", required: true },
+	},
+	create_prospect_list: {
+		name: { flag: "name", required: true },
+	},
+	import_prospects_csv: {
+		csv_text: {
+			value: (flags) => {
+				const csv = readTextInput(flags, "csv", "csv-file");
+				if (csv === undefined)
+					throw new CliError("Missing CSV: pass --csv-file <path> (or --csv-file - for stdin)");
+				return csv;
+			},
+		},
+		one_per_company: { flag: "one-per-company", type: "bool" },
+		list_id: "list",
+		list_name: "list-name",
+	},
+	create_prospect_list_from_prompt: {
+		description: { flag: "description", required: true },
+		list_id: "list",
+		list_name: "list-name",
+		limit: { flag: "limit", type: "num" },
+		one_per_company: { flag: "one-per-company", type: "bool" },
+	},
+	enrich_prospects: {
+		list_id: "list",
+		status: { flag: "status", enum: PROSPECT_STATUSES },
+		q: "q",
+	},
+	update_prospect: {
+		prospect_id: { positional: 0, label: "prospect-id", required: true },
+		status: { flag: "status", enum: PROSPECT_STATUSES },
+		name: "name",
+		first_name: "first-name",
+		last_name: "last-name",
+		title: "title",
+		company: "company",
+		website: "website",
+		linkedin_url: "linkedin",
+		school: "school",
+		city: "city",
+		country: "country",
+		years_at_company: "years",
+		notes: "notes",
+		custom: { value: readCustom },
+	},
+	get_mail_connections: {},
+};
+
+// Flags the computed `value` sources read (refuseUnknownFlags can't see them).
+const VALUE_FLAGS = {
+	create_sequence: ["flow", "flow-file", "mailer"],
+	update_sequence: ["flow", "flow-file", "mailer"],
+	enroll_in_sequence: ["recipients", "recipients-file", "email"],
+	update_review_item: ["body", "file"],
+	import_prospects_csv: ["csv", "csv-file"],
+	update_prospect: ["custom"],
+};
+
+async function run(ctx, tool, message) {
+	refuseUnknownFlags(ctx, ARGS[tool], VALUE_FLAGS[tool] ?? []);
+	const result = await ctx.client.callTool(tool, argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals));
+	if (message) ok(ctx, message);
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+const SEQUENCES_USAGE = `Usage: sequences <list|get|create|update|pause|resume|enroll|stop|review|links>`;
+
+export async function cmdSequences(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return run(rest, "list_sequences");
+		case "get":
+		case "show":
+			return run(rest, "get_sequence");
+		case "create":
+		case "new":
+			return run(rest, "create_sequence", "Created sequence (a draft: set --status active to send).");
+		case "update":
+			return run(rest, "update_sequence", "Updated sequence.");
+		case "pause":
+		case "resume": {
+			const id = requirePositional(rest.positionals, 0, "sequence-id");
+			const status = sub === "pause" ? "paused" : "active";
+			const result = await ctx.client.callTool(
+				"update_sequence",
+				argsFromFlags(ARGS.update_sequence, { status }, [id])
+			);
+			ok(ctx, sub === "pause" ? "Paused: nothing further sends." : "Resumed: sending again.");
+			printResult(ctx.io, ctx.flags, result);
+			return 0;
+		}
+		case "enroll":
+			return run(rest, "enroll_in_sequence", "Enrolled.");
+		case "stop":
+			return run(rest, "stop_sequence_enrollment", "Enrollment stopped.");
+		case "review":
+			return sequencesReview({ ...rest, positionals: rest.positionals.slice(1) }, rest.positionals[0]);
+		case "links":
+			return sequencesLinks({ ...rest, positionals: rest.positionals.slice(1) }, rest.positionals[0]);
+		default:
+			throw new CliError(`Unknown sequences subcommand: ${sub ?? "(none)"}. ${SEQUENCES_USAGE}`);
+	}
+}
+
+async function sequencesReview(ctx, sub) {
+	switch (sub) {
+		case "list":
+		case "ls":
+		case undefined:
+			return run(ctx, "list_review_items");
+		case "edit":
+			return run(ctx, "update_review_item", "Saved the edit.");
+		case "decide":
+			return run(ctx, "decide_review_item", "Decided.");
+		case "approve":
+		case "skip":
+		case "delete": {
+			const id = requirePositional(ctx.positionals, 0, "item-id");
+			const result = await ctx.client.callTool(
+				"decide_review_item",
+				argsFromFlags(ARGS.decide_review_item, { action: sub }, [id])
+			);
+			ok(ctx, sub === "approve" ? "Approved: sending now." : sub === "skip" ? "Skipped." : "Deleted.");
+			printResult(ctx.io, ctx.flags, result);
+			return 0;
+		}
+		default:
+			throw new CliError(`Unknown review subcommand: ${sub}. Try: list, edit, decide, approve, skip, delete`);
+	}
+}
+
+async function sequencesLinks(ctx, sub) {
+	switch (sub) {
+		case "list":
+		case "ls":
+		case undefined:
+			return run(ctx, "list_dispatch_links");
+		case "create":
+			return run(ctx, "create_dispatch_link", "Link minted. Anyone holding it can send; it is shown only once.");
+		case "revoke": {
+			if (!ctx.flags.yes) {
+				const id = flagStr(ctx.positionals[0]) ?? "<link-id>";
+				ctx.io.error(`Re-run with --yes to confirm: ${ctx.bin} sequences links revoke ${id} --yes`);
+				return 1;
+			}
+			return run(ctx, "revoke_dispatch_link", "Link revoked.");
+		}
+		default:
+			throw new CliError(`Unknown links subcommand: ${sub}. Try: list, create, revoke`);
+	}
+}
+
+const PROSPECTS_USAGE = `Usage: prospects <lists|list|ls|get|create-list|import|source|enrich|update>`;
+
+export async function cmdProspects(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "lists":
+			return run(rest, "list_prospect_lists");
+		case "list":
+			return run(rest, "get_prospect_list");
+		case "ls":
+			return run(rest, "list_prospects");
+		case "get":
+		case "show":
+			return run(rest, "get_prospect");
+		case "create-list":
+			return run(rest, "create_prospect_list", "List ready.");
+		case "import":
+			return run(rest, "import_prospects_csv", "Imported.");
+		case "source":
+			return run(
+				rest,
+				"create_prospect_list_from_prompt",
+				"Sourcing started; rows land in the list as they arrive."
+			);
+		case "enrich":
+			return run(rest, "enrich_prospects", "Enrichment queued.");
+		case "update":
+			return run(rest, "update_prospect", "Updated prospect.");
+		default:
+			throw new CliError(`Unknown prospects subcommand: ${sub ?? "(none)"}. ${PROSPECTS_USAGE}`);
+	}
+}
+
+export async function cmdMail(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "connections":
+		case "status":
+			return run(rest, "get_mail_connections");
+		default:
+			throw new CliError(`Unknown mail subcommand: ${sub ?? "(none)"}. Try: connections`);
+	}
+}

package/lib/commands.mjs

@@ -32,6 +32,7 @@ export * from "./commands/onboard.mjs";
 export * from "./commands/seers.mjs";
 export * from "./commands/shredder.mjs";
 export * from "./commands/landings.mjs";
+export * from "./commands/outbound.mjs";
 export * from "./commands/offerings.mjs";
 export * from "./commands/admin.mjs";
 export * from "./commands/feedback.mjs";

package/lib/documents.mjs

@@ -77,6 +77,8 @@ export const JSON_ARG_FLAG_PAIRS = [
 	["plan", "plan-file"],
 	// A reviewed plan handed back to be applied verbatim (onboard.mjs readAcceptedPlan).
 	["accept-plan-json", "accept-plan"],
+	// A prospects CSV, parsed and header-mapped server-side (outbound.mjs prospects import).
+	["csv", "csv-file"],
 ];
 
 /** Lower-case extension without the dot. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.36.1",
+	"version": "0.38.0",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",