@letterstory/cli 0.89.0 → 0.90.0

package/README.md

@@ -346,6 +346,21 @@ 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: client patterns and Fable
+
+```bash
+# What separates clients whose AI visibility moves (docs/architecture/client-patterns.md):
+# every client against itself on share of voice, mention rate and page access, with what we
+# did for it. Needs fleet:read; `run` and `ask` spend Fable tokens and need fleet:query.
+letterstory admin patterns --period 30d
+letterstory admin patterns reports            # Fable's weekly reports and runs, newest first
+letterstory admin patterns report <id>        # one report's markdown
+letterstory admin patterns run                # a report now (takes minutes)
+letterstory admin patterns ask "do answer-gap posts help paying clients too?"
+```
+
+The headless half of Admin → Client performance → Patterns: same functions, same schemas.
+
 ### Staff: kernel experiments
 
 ```bash

package/lib/cli.mjs

@@ -57,13 +57,15 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.89.0";
+export const VERSION = "0.90.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. Every `type: "bool"` flag (and its
 // `negate` spelling) in a command's ARGS map must be listed; boolean-flags.test.ts enforces it.
 export const BOOLEAN_FLAGS = new Set([
 	"json",
+	// lede library update / lede proposals accept: clear or drop the line's condition.
+	"no-condition",
 	"yes",
 	"confirm-missing-target",
 	"no-wait",
@@ -645,6 +647,14 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        (fleet:instrument) — e.g. --term Context.dev for a name
                                                        that is also a word. --clear goes back to inferred,
                                                        recorded as your decision.
+  admin patterns [--period 14d|30d] [--segment "<segment>"] [--json]
+                                                       Client patterns: every client's share of voice,
+                                                       mention rate and page access against itself, with
+                                                       what we did for it. Needs fleet:read.
+  admin patterns reports [--kind reports|weekly|run|ask] | report <id>
+                                                       Fable's weekly reports, runs and Ask Fable answers.
+  admin patterns run | ask "<question>"                Run a Fable report now, or ask Fable a question
+                                                       about client patterns (minutes). Needs fleet:query.
   admin replays [--org <uuid>] [--target <uuid>] [--status captured|not_reproduced|queued|running|unsupported|failed] [--limit <n>]
                                                        Live answer replays: breakthroughs re-asked in ChatGPT /
                                                        Gemini / Google / Perplexity / Claude, with screenshots.
@@ -932,7 +942,7 @@ Ledes (opening lines for cold email, chosen per prospect from a hand-approved li
   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>]...
+           [--threshold <0..100>] [--tone warm|direct|playful|formal] [--tag <t>]... [--condition <use when...>]
                                                        Add a custom line. A {{placeholder}} must appear in
                                                        --requires; proprietary-engine triggers stay
                                                        reserved for the pre-built lines. --threshold
@@ -941,6 +951,7 @@ Ledes (opening lines for cold email, chosen per prospect from a hand-approved li
                                                        lower = looser.
   lede library update <lede-id> [--text <line>] [--alts <v>]... [--peer-alts <v>]...
            [--requires <trigger>]... [--threshold <0..100>] [--tone <t>] [--tag <t>]...
+           [--condition <use when...> | --no-condition]
                                                        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
@@ -951,6 +962,13 @@ Ledes (opening lines for cold email, chosen per prospect from a hand-approved li
                                                        Propose brand-voice rewrites of the wording only.
                                                        Applies nothing: accept a proposal with
                                                        lede library update --text/--alts
+  lede proposals [list] [--status proposed|captured|active|rejected] [--limit <n>]
+                                                       Lines reviewers wrote while personalizing in
+                                                       Dispatch, templated and judged, each with a
+                                                       drafted "Use when ..." condition
+  lede proposals accept <proposal-id> [--text <line>] [--condition <c> | --no-condition] [--tone <t>]
+                                                       Add it to the library (live immediately)
+  lede proposals reject <proposal-id> --reason <why>   Keep it out; the reason stops it recurring
 
 Landings (a link + context; auto-mentioned in articles by collections you enable):
   landings list                                        Your landing pages + mention counts
@@ -982,6 +1000,7 @@ Sequences (multi-step cold email sent from your mailers; approving or enrolling
   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>]
+        [--personalize <line> [--personalize-mode replace|insert]]   Mark the edit a personalization (proposed to the opener library)
   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)

package/lib/commands/admin.mjs

@@ -4,6 +4,7 @@
 // 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 patterns [--period 14d|30d] [--segment "…"] | reports [--kind reports|weekly|run|ask] | report <id> | run | ask "<question>"   (fleet:read / fleet:query)
 //   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)
@@ -241,6 +242,80 @@ async function cmdAdminAsk(ctx) {
 	}
 }
 
+/* ------------------------------------------------------------ client patterns */
+
+const PATTERNS = "/api/superadmin/client-patterns";
+
+/**
+ * `admin patterns …` — the Patterns tab without a browser (docs/architecture/client-patterns.md):
+ * the data, Fable's report history, a report on demand, and Ask Fable. `run` and `ask` wait for
+ * the finished answer (minutes, not seconds) and print its markdown.
+ */
+async function cmdAdminPatterns(ctx) {
+	const [sub = "show", ...rest] = ctx.positionals;
+	const json = flagBool(ctx.flags.json);
+	switch (sub) {
+		case "show": {
+			const { payload } = await staffRequest(ctx, "GET", PATTERNS);
+			if (!payload) throw new CliError("The patterns snapshot has not been computed yet.");
+			const period = flagStr(ctx.flags.period) ?? "30d";
+			const segment = flagStr(ctx.flags.segment);
+			const clients = payload.clients.filter((c) => !segment || c.segment === segment);
+			if (json) return printResult(ctx.io, ctx.flags, { ...payload, clients });
+			const pts = (v) => (v == null ? "—" : `${v >= 0 ? "+" : "−"}${Math.abs(v * 100).toFixed(1)} pts`);
+			ctx.io.log(`${clients.length} clients, ${payload.postCount} posts · computed ${payload.generated}`);
+			for (const c of clients) {
+				const s = c.sov?.[period];
+				const n = c.named?.[period];
+				ctx.io.log(
+					`${c.name.padEnd(28)} ${c.segment.padEnd(30)} sov ${pts(s?.change)}  mention ${pts(n?.change)}  posts30 ${c.posts30}`
+				);
+			}
+			return;
+		}
+		case "reports": {
+			const kind = flagStr(ctx.flags.kind) ?? "reports";
+			const limit = flagStr(ctx.flags.limit) ?? "12";
+			const { reports } = await staffRequest(
+				ctx,
+				"GET",
+				`${PATTERNS}/reports?kind=${encodeURIComponent(kind)}&limit=${encodeURIComponent(limit)}`
+			);
+			if (json) return printResult(ctx.io, ctx.flags, { reports });
+			for (const r of reports)
+				ctx.io.log(
+					`${r.id}  ${r.created_at}  ${r.kind.padEnd(6)} ${r.status.padEnd(7)} ${(r.question ?? (r.summary ?? "").split("\n")[0] ?? "").slice(0, 80)}`
+				);
+			return;
+		}
+		case "report": {
+			const id = rest[0];
+			if (!id) throw new CliError("Usage: admin patterns report <id>");
+			const { report } = await staffRequest(ctx, "GET", `${PATTERNS}/reports/${encodeURIComponent(id)}`);
+			if (json) return printResult(ctx.io, ctx.flags, { report });
+			ctx.io.log(report.report ?? report.error ?? "(no report)");
+			return;
+		}
+		case "run": {
+			const { report } = await staffPost(ctx, `${PATTERNS}/reports`, {});
+			if (json) return printResult(ctx.io, ctx.flags, { report });
+			ctx.io.log(report.report ?? report.error ?? "(no report)");
+			return;
+		}
+		case "ask": {
+			const question = rest.join(" ").trim();
+			if (question.length < 3)
+				throw new CliError('Usage: admin patterns ask "do answer-gap posts help paying clients too?"');
+			const { answer } = await staffPost(ctx, `${PATTERNS}/ask`, { question });
+			if (json) return printResult(ctx.io, ctx.flags, { answer });
+			ctx.io.log(answer.report ?? answer.error ?? "(no answer)");
+			return;
+		}
+		default:
+			throw new CliError('Usage: admin patterns [show] | reports | report <id> | run | ask "<question>"');
+	}
+}
+
 /* ------------------------------------------------------------ kernel experiments */
 
 const EXPERIMENTS = "/api/superadmin/tuning/experiments";
@@ -3576,6 +3651,7 @@ export async function cmdAdmin(ctx) {
 	if (sub === "spend") return cmdAdminSpend({ ...ctx, positionals: ctx.positionals.slice(1) });
 	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 === "patterns") return cmdAdminPatterns({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "experiments") return cmdAdminExperiments({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "fleet-experiments") return cmdAdminFleetExperiments({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "tuning-context") return cmdAdminTuningContext({ ...ctx, positionals: ctx.positionals.slice(1) });
@@ -3584,7 +3660,7 @@ export async function cmdAdmin(ctx) {
 	if (sub === "evals") return cmdAdminEvals({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "brand-detection") return cmdAdminBrandDetection({ ...ctx, positionals: ctx.positionals.slice(1) });
 	throw new CliError(
-		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin fleet-experiments … | admin crm … | admin spend … | admin evals … | admin brand-detection … | admin tuning … | admin tuning-context | admin replays … (see --help)'
+		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin patterns … | admin experiments … | admin fleet-experiments … | admin crm … | admin spend … | admin evals … | admin brand-detection … | admin tuning … | admin tuning-context | admin replays … (see --help)'
 	);
 }
 

package/lib/commands/lede.mjs

@@ -130,6 +130,8 @@ export const ARGS = {
 		threshold: { flag: "threshold", type: "num" },
 		tone: { flag: "tone", enum: ["warm", "direct", "playful", "formal"] },
 		tags: { flag: "tag", type: "list" },
+		// "Use when ..." clause, checked per prospect before the line is used.
+		condition: "condition",
 	},
 	update_lede: {
 		id: { positional: 0, label: "lede-id", required: true },
@@ -140,6 +142,8 @@ export const ARGS = {
 		threshold: { flag: "threshold", type: "num" },
 		tone: { flag: "tone", enum: ["warm", "direct", "playful", "formal"] },
 		tags: { flag: "tag", type: "list" },
+		// --condition "<clause>" sets it; --no-condition clears it.
+		condition: { value: (flags) => (flags["no-condition"] ? null : flagStr(flags.condition)) },
 	},
 	set_lede_enabled: {
 		id: { positional: 0, label: "lede-id", required: true },
@@ -153,6 +157,22 @@ export const ARGS = {
 		voice: { flag: "voice", required: true },
 		ids: { flag: "ids", type: "list" },
 	},
+	// Opener proposals (`lede proposals ...`): lines captured from Dispatch personalizations,
+	// evaluated, waiting for an admin to accept into the library or reject with a reason.
+	list_lede_proposals: {
+		status: { flag: "status", enum: ["captured", "proposed", "active", "rejected"] },
+		limit: { flag: "limit", type: "num" },
+	},
+	decide_lede_proposal: {
+		proposal_id: { positional: 0, label: "proposal-id", required: true },
+		// `lede proposals accept|reject <id>` decides this; the subcommand passes it in.
+		action: { value: (_flags, _positionals, extra) => extra.action },
+		text: "text",
+		// --condition "<clause>" edits it on accept; --no-condition accepts with none.
+		condition: { value: (flags) => (flags["no-condition"] ? null : flagStr(flags.condition)) },
+		tone: { flag: "tone", enum: ["warm", "direct", "playful", "formal"] },
+		reason: "reason",
+	},
 };
 
 export async function cmdLede(ctx) {
@@ -173,6 +193,9 @@ export async function cmdLede(ctx) {
 		case "library":
 		case "lib":
 			return ledeLibrary(rest);
+		case "proposals":
+		case "proposal":
+			return ledeProposals(rest);
 		case "run":
 			return ledeRun(rest);
 		case "runs":
@@ -193,7 +216,7 @@ export async function cmdLede(ctx) {
 			return ledeFunnel(rest);
 		default:
 			throw new CliError(
-				`Unknown lede subcommand: ${sub ?? "(none)"}. Try: list, create, delete, endpoint, library, run, runs, history, evals, balance, outcome, funnel`
+				`Unknown lede subcommand: ${sub ?? "(none)"}. Try: list, create, delete, endpoint, library, proposals, run, runs, history, evals, balance, outcome, funnel`
 			);
 	}
 }
@@ -445,3 +468,61 @@ async function ledeBalance(ctx) {
 	printResult(io, flags, result);
 	return 0;
 }
+
+/**
+ * `lede proposals [list] [--status proposed|captured|active|rejected] [--limit n]`,
+ * `lede proposals accept <id> [--text ...] [--condition ...|--no-condition] [--tone ...]`,
+ * `lede proposals reject <id> --reason ...` — lines reviewers wrote while personalizing on
+ * the Dispatch desk, templatized and judged; accept adds one to the library (live now).
+ */
+async function ledeProposals(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const action = positionals[0];
+	const rest = { ...ctx, positionals: positionals.slice(1) };
+	switch (action) {
+		case undefined:
+		case "list":
+		case "ls": {
+			const result = await client.callTool("list_lede_proposals", argsFromFlags(ARGS.list_lede_proposals, flags));
+			// One block per proposal: id, how often captured, the template, then its condition
+			// (or why it was rejected). `--json` for the judge's scores and the raw line.
+			printResult(
+				io,
+				flags,
+				result,
+				(r) =>
+					(r?.proposals ?? [])
+						.map((p) =>
+							[
+								`${p.id}  x${p.capture_count}  [${p.status}]  ${p.templated_text ?? p.raw_line}`,
+								p.status_reason
+									? `    why: ${p.status_reason}`
+									: p.suggested_condition
+										? `    ${p.suggested_condition}`
+										: null,
+							]
+								.filter(Boolean)
+								.join("\n")
+						)
+						.join("\n") || "No proposals."
+			);
+			return 0;
+		}
+		case "accept":
+		case "reject": {
+			const args = argsFromFlags(ARGS.decide_lede_proposal, flags, rest.positionals, { action });
+			if (action === "reject" && !args.reason) throw new CliError("A rejection needs --reason <why>.");
+			const result = await client.callTool("decide_lede_proposal", args);
+			ok(
+				ctx,
+				action === "accept"
+					? `Accepted ${args.proposal_id}: the line is in the library now.`
+					: `Rejected ${args.proposal_id}.`
+			);
+			printResult(io, flags, result);
+			return 0;
+		}
+		default:
+			throw new CliError(`Unknown lede proposals action: ${action}. Try: list, accept, reject`);
+	}
+}

package/lib/commands/outbound.mjs

@@ -197,6 +197,23 @@ export const ARGS = {
 		item_id: { positional: 0, label: "item-id", required: true },
 		subject: "subject",
 		body: { value: (flags) => readTextInput(flags, "body", "file") },
+		// --personalize "<line>" marks the edit as a personalization (captured as an opener
+		// proposal for the org's admins); --personalize-mode says whether the line replaced
+		// the opener (default) or was inserted after the greeting.
+		personalization: {
+			value: (flags) => {
+				const line = flagStr(flags.personalize);
+				const mode = flagStr(flags["personalize-mode"]);
+				if (line === undefined) {
+					if (mode !== undefined) throw new CliError("--personalize-mode needs --personalize <line>");
+					return undefined;
+				}
+				if (mode !== undefined && mode !== "replace" && mode !== "insert") {
+					throw new CliError(`--personalize-mode must be replace or insert (got ${mode})`);
+				}
+				return { line, mode: mode ?? "replace" };
+			},
+		},
 	},
 	decide_review_item: {
 		item_id: { positional: 0, label: "item-id", required: true },
@@ -366,7 +383,7 @@ const VALUE_FLAGS = {
 	create_sequence: ["flow", "flow-file", "mailer", "send-window-start", "send-window-end"],
 	update_sequence: ["flow", "flow-file", "mailer", "send-window-start", "send-window-end"],
 	enroll_in_sequence: ["recipients", "recipients-file", "email"],
-	update_review_item: ["body", "file"],
+	update_review_item: ["body", "file", "personalize", "personalize-mode"],
 	delete_prospects: ["id"],
 	import_prospects_csv: ["csv", "csv-file"],
 	update_prospect: ["custom"],

package/package.json

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