@letterstory/cli 0.129.0 → 0.130.0

package/README.md

@@ -118,6 +118,8 @@ letterstory phantom config <phantom-id> --theme commons          # patch the sit
 letterstory phantom config <phantom-id> --collection-config '{"cadence":{"posts_per_week":4}}'
 letterstory phantom config <phantom-id> --configure --dry-run   # what re-configuring would decide, applying nothing
 letterstory phantom rebuild <phantom-id>                        # after publishing outside a collection run
+letterstory phantom pause <phantom-id>                          # stop new posts and probing; the site stays live (resume to undo)
+letterstory phantom resume <phantom-id>
 letterstory phantom diagnostics <phantom-id>                    # why is my site empty?
 letterstory phantom balance                                     # sites live / granted, and the cadence cap
 letterstory phantom spread-looks [--apply]                      # a different look per site; dry run unless --apply

package/lib/cli.mjs

@@ -62,7 +62,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.129.0";
+export const VERSION = "0.130.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
@@ -447,6 +447,7 @@ Reviewers:
   reviewers assigned                                   Posts waiting on your review, across letterbases
   automations list --collection <id>                   What a letterbase writes, how often, and why
   automations show <automation-id> --collection <id>  What it covers, its queued posts, its next ideas
+  automations ideas --collection <id>                  The ideas waiting, grouped by the automation that owns each
   automations suggest --collection <id>                What it could add: topics, series formats, signals
   automations preview topic|series --collection <id> [--name <name>|--topic <id>] [--brief <text>]
                                                        What it would write, before adding it
@@ -925,7 +926,8 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
           | track-record [--since YYYY-MM-DD] | at-risk | expansion-signals
           | weekly-note                       the Monday retention note for the last full week
           | collections [--org-ids a,b | --account-stages won,active]
-          | delivery-flags [--org-ids a,b | --account-stages won,active] [--include collections]
+          | delivery-flags [--org-ids a,b | --account-stages won,active] [--include collections] [--since 2026-10-19T20:00:00Z]
+          | pulse [--ids a,b] [--since 2026-10-19T20:00:00Z]   how each client is doing, worst churn risk first
           | case <account-id> [--outcome <outcome-id>]
           | onboard <account-id> --domain acme.com [--name "Acme"] [--site "<direction>"]… [--sites N]
                    [--slack a@acme.com,b@acme.com] [--invite a@acme.com[:admin]]… [--no-checklist]
@@ -1304,6 +1306,9 @@ Mail:
 
 Insights:
   insights summary [--period …] [--part <block>]...    Measure Overview: AI named/cited rates, share of voice, search, targets
+  insights reads [--period …] [--site all|own|phantoms|<key>]... [--path <path>] [--engine <operator>]
+                                                       Measure → Reads: AI engines and people reading your sites, counted one way
+  insights questions [--period 14d|30d|90d]            Measure → Questions: every question we ask, named / share / change / cited
   insights competitors [--period 14d|30d|90d]          GEO → Competitors: share of mentions per brand, is it moving, by engine/question
   insights question <key> [--period 14d|30d|90d] [--filter all|named_you|rival_not_you|no_one] [--limit n]
                                                        One By-question row: the wordings asked and the AI answers
@@ -1315,6 +1320,7 @@ Insights:
                                                        AI Visibility Bank: named / cited / breakthrough evidence (all time by default)
   insights access [--period 14d|30d|90d] [--collection <uuid>]
                                                        Page access: who's reading your phantom sites
+  insights activity [--phantom <uuid>] [--limit <n>]   What hit your phantom sites in the last 7 days, newest first
 
 The Site (one model of your whole marketing site, keyed by host and path):
   site list                                            Mapped hosts, and hosts you already have elsewhere
@@ -1336,6 +1342,8 @@ The Site (one model of your whole marketing site, keyed by host and path):
   site propose <host> [path] --tool <tool> --input '<json>'|--input-file <p> --label <text> [--why <text>]
                      [--observation <id>]...           Propose a registry tool call; input is validated now
   site decide <proposal-id> --decision accept|dismiss [--reason <why>]
+  site fix <host> <observation-id>... [--action build|build_pr|build_merge|slack|linear|handoff] [--with-preview]
+                                                       One change for N observations; handoff prints the prompt, slack/linear need no repo
   site competitors [--since <iso> | --days <n>] [--limit <n>]  Tracked competitors' sites: new and removed pages, by folder
   site watch-competitors [domain] [--limit <n>]        Map competitors' sitemaps (the next few unmapped, or one now)
   site highlight <domain> [--off]                      Highlight a competitor; its changes lead the top changes

package/lib/commands/admin.mjs

@@ -14,7 +14,7 @@
 //      The old names — evals, eval-add, eval-set, proposals, propose-eval, capture-eval, reject-eval — still work.)
 //   admin evals scoreboard|cases|runs|run|triage|guard|retire …                      (fleet:read / tuning:experiment)
 //   admin fleet-experiments list|articles|clients|mark|unmark|new|assign|assign-eligible|assign-orgs|spin-up|apply|start|stop|decide …  (fleet:read / fleet:experiment)
-//   admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|revenue|reach-outs|record-churn|draft-churn-reason|undo-churn|outcomes|record-outcome|renewals|track-record|weekly-note|at-risk|expansion-signals|collections|delivery-flags|case|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
+//   admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|revenue|reach-outs|record-churn|draft-churn-reason|undo-churn|outcomes|record-outcome|renewals|track-record|weekly-note|at-risk|expansion-signals|collections|delivery-flags|pulse|case|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
 //   admin spend summary|reconcile|pnl|margin|pricing|entries|add|import|usage|remove|reference|stripe-sync|services|service …  (spend:read / spend:write)
 //   admin brand-detection <org-id>                                                   (fleet:read)
 //   admin brand-detection <org-id> [--term t]... [--exact t]... [--exclude p]... [--note "…"] | --clear [--note "…"]   (fleet:instrument)
@@ -3596,27 +3596,62 @@ async function cmdAdminCrm(ctx) {
 			);
 		}
 		case "delivery-flags": {
-			// admin crm delivery-flags [--org-ids a,b | --account-stages won,active] [--include collections]
+			// admin crm delivery-flags [--org-ids a,b | --account-stages won,active] [--include collections] [--since <ISO time, e.g. 2026-10-19T20:00:00Z>]
 			// — does what we spend on a client match what they pay? Findings per org, worst first.
+			// The post-sales stages come from a snapshot (~10 min); --since skips one older than that.
 			const params = new URLSearchParams(
 				compact({
 					org_ids: flagStr(flags["org-ids"]),
 					account_stages: flagStr(flags["account-stages"]),
 					include: flagStr(flags.include),
+					since: flagStr(flags.since),
 				})
 			);
 			return out(await staffRequest(ctx, "GET", `${CRM}/delivery-flags?${params}`), (r) => {
 				if (!r.accounts)
 					return "Billing cannot say who pays yet, so there are no flags (collections are in --json).";
 				const flagged = r.accounts.filter((a) => a.findings.length);
-				return flagged.length
-					? flagged
-							.map(
-								(a) =>
-									`${a.owedDelivery ? "owed  " : a.notPaying ? "unpaid" : "      "}  ${a.orgName}  ${a.findings.map((f) => f.message).join("; ")}  ${a.orgId}`
-							)
-							.join("\n")
-					: `(${r.accounts.length} org${r.accounts.length === 1 ? "" : "s"}, nothing flagged)`;
+				const asOf = r.snapshot
+					? `(as of ${r.snapshot.computedAt}${r.snapshot.stale ? ", STALE: the refresh is failing" : ""})\n`
+					: "";
+				return (
+					asOf +
+					(flagged.length
+						? flagged
+								.map(
+									(a) =>
+										`${a.owedDelivery ? "owed  " : a.notPaying ? "unpaid" : "      "}  ${a.orgName}  ${a.findings.map((f) => f.message).join("; ")}  ${a.orgId}`
+								)
+								.join("\n")
+						: `(${r.accounts.length} org${r.accounts.length === 1 ? "" : "s"}, nothing flagged)`)
+				);
+			});
+		}
+		case "pulse": {
+			// admin crm pulse [--ids a,b] [--since <ISO time, e.g. 2026-10-19T20:00:00Z>]
+			// — how is each client doing? One line per account, worst churn risk first.
+			// The default scope comes from a snapshot (~10 min); --since skips one older than that.
+			const params = new URLSearchParams(compact({ ids: flagStr(flags.ids), since: flagStr(flags.since) }));
+			return out(await staffRequest(ctx, "GET", `${CRM}/pulse?${params}`), (r) => {
+				const rank = { high: 0, watch: 1, ok: 2 };
+				const rows = Object.entries(r.pulses).sort(
+					([, a], [, b]) =>
+						rank[a.churnRisk.level] - rank[b.churnRisk.level] || b.churnRisk.score - a.churnRisk.score
+				);
+				const asOf = r.snapshot
+					? `(as of ${r.snapshot.computedAt}${r.snapshot.stale ? ", STALE: the refresh is failing" : ""})\n`
+					: "";
+				return (
+					asOf +
+					(rows.length
+						? rows
+								.map(
+									([id, p]) =>
+										`${p.churnRisk.level.padEnd(5)}  ${p.phantomPostsLast30d} phantom posts in 30d${p.clicksTrend === null ? "" : ` · clicks ${p.clicksTrend >= 0 ? "+" : ""}${Math.round(p.clicksTrend * 100)}%`}${p.slackWaiting ? ` · ${p.slackWaiting} waiting in Slack` : ""}${p.nextProduct ? ` · next: ${p.nextProduct}` : ""}${p.churnRisk.reasons.length ? `  ${p.churnRisk.reasons.join("; ")}` : ""}  ${id}`
+								)
+								.join("\n")
+						: "(no accounts in that scope)")
+				);
 			});
 		}
 		case "case": {
@@ -3697,7 +3732,7 @@ async function cmdAdminCrm(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|revenue|reach-outs|record-churn|draft-churn-reason|undo-churn|outcomes|record-outcome|renewals|track-record|weekly-note|at-risk|expansion-signals|collections|delivery-flags|case|onboard|onboarding|retry-onboarding|onboard-plan|payment-link … (see --help)"
+				"Usage: admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|revenue|reach-outs|record-churn|draft-churn-reason|undo-churn|outcomes|record-outcome|renewals|track-record|weekly-note|at-risk|expansion-signals|collections|delivery-flags|pulse|case|onboard|onboarding|retry-onboarding|onboard-plan|payment-link … (see --help)"
 			);
 	}
 }

package/lib/commands/automations.mjs

@@ -1,5 +1,5 @@
 // `automations` — a letterbase's automations (docs/architecture/automations.md): what it writes,
-// how often, and why. list / show / suggest / preview / more / add / set / dismiss / remove, through the same tools the app uses.
+// how often, and why. list / show / ideas / suggest / preview / more / add / set / dismiss / remove, through the same tools the app uses.
 // Same flag/positional/io conventions as posts.mjs — no commander, no color.
 
 import { CliError } from "../client.mjs";
@@ -10,6 +10,9 @@ export const ARGS = {
 	list_automations: {
 		collection_id: { flag: "collection", required: true },
 	},
+	list_automation_ideas: {
+		collection_id: { flag: "collection", required: true },
+	},
 	suggest_automations: {
 		collection_id: { flag: "collection", required: true },
 	},
@@ -74,6 +77,8 @@ export async function cmdAutomations(ctx) {
 			return run(rest, "list_automations");
 		case "show":
 			return run(rest, "get_automation");
+		case "ideas":
+			return run(rest, "list_automation_ideas");
 		case "suggest":
 			return run(rest, "suggest_automations");
 		case "preview":
@@ -92,7 +97,7 @@ export async function cmdAutomations(ctx) {
 			return run(rest, "delete_automation", "Removed.");
 		default:
 			throw new CliError(
-				`Unknown automations subcommand: ${sub ?? "(none)"}. Try: list, show, suggest, preview, more, add, set, dismiss, remove`
+				`Unknown automations subcommand: ${sub ?? "(none)"}. Try: list, show, ideas, suggest, preview, more, add, set, dismiss, remove`
 			);
 	}
 }

package/lib/commands/insights.mjs

@@ -1,8 +1,9 @@
 // `insights` — Search Console impressions/clicks across the phantom network, at the
 // network, single-post, and top-posts levels (ported from phantomstory-cli's
 // insights.ts); plus Measure's Overview (`summary`), GEO → Competitors
-// (`competitors`), AI Visibility Bank (`bank`) and phantom Page Access (`access`)
-// — the same reads the web app's Measure tabs render.
+// (`competitors`), AI Visibility Bank (`bank`) and phantom Page Access (`access`);
+// Measure → Reads (`reads`) and Questions (`questions`), and the live feed of what
+// is reading the phantom sites (`activity`) — the same reads the web app renders.
 
 import { CliError } from "../client.mjs";
 import { flagStr, flagNum, requirePositional, printResult, compact, argsFromFlags } from "./shared.mjs";
@@ -28,6 +29,19 @@ export const ARGS = {
 		period: { flag: "period", enum: PERIODS },
 	},
 	get_brand_detection: {},
+	get_reads: {
+		period: { flag: "period", enum: PERIODS },
+		sites: { flag: "site", type: "list" },
+		path: { flag: "path" },
+		engine: { flag: "engine" },
+	},
+	list_measure_questions: {
+		period: { flag: "period", enum: PERIODS },
+	},
+	get_recent_activity: {
+		phantom_id: { flag: "phantom" },
+		limit: { flag: "limit", type: "num" },
+	},
 	get_share_of_voice_question: {
 		question_key: { positional: 0, label: "question-key", required: true },
 		period: { flag: "period", enum: PERIODS },
@@ -58,9 +72,15 @@ export async function cmdInsights(ctx) {
 			return call(rest, "get_share_of_voice_question");
 		case "detection":
 			return call(rest, "get_brand_detection");
+		case "reads":
+			return call(rest, "get_reads");
+		case "questions":
+			return call(rest, "list_measure_questions");
+		case "activity":
+			return call(rest, "get_recent_activity");
 		default:
 			throw new CliError(
-				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, competitors, question, detection, site, post, top, bank, access`
+				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, reads, questions, competitors, question, detection, activity, site, post, top, bank, access`
 			);
 	}
 }

package/lib/commands/phantom.mjs

@@ -111,6 +111,11 @@ export const ARGS = {
 	},
 	delete_phantom: { phantom_id: { positional: 0, label: "phantom-id", required: true } },
 	rebuild_phantom: { phantom_id: { positional: 0, label: "phantom-id", required: true } },
+	// `phantom pause <id>` / `phantom resume <id>` — the verb sets `paused`.
+	set_phantom_paused: {
+		phantom_id: { positional: 0, label: "phantom-id", required: true },
+		paused: { value: (flags, positionals, extra) => extra.paused },
+	},
 	get_phantom_diagnostics: { phantom_id: { positional: 0, label: "phantom-id", required: true } },
 	get_phantom_balance: {},
 	spread_phantom_looks: { apply: { flag: "apply", type: "bool" } },
@@ -154,6 +159,9 @@ export async function cmdPhantom(ctx) {
 			return call(rest, "delete_phantom");
 		case "rebuild":
 			return call(rest, "rebuild_phantom");
+		case "pause":
+		case "resume":
+			return phantomPause(rest, sub === "pause");
 		case "diagnostics":
 		case "diag":
 			return call(rest, "get_phantom_diagnostics");
@@ -165,11 +173,17 @@ export async function cmdPhantom(ctx) {
 			return phantomDomain(rest);
 		default:
 			throw new CliError(
-				`Unknown phantom subcommand: ${sub ?? "(none)"}. Try: list, get, new, config, visitors, delete, rebuild, diagnostics, balance, spread-looks, domain`
+				`Unknown phantom subcommand: ${sub ?? "(none)"}. Try: list, get, new, config, visitors, delete, rebuild, pause, resume, diagnostics, balance, spread-looks, domain`
 			);
 	}
 }
 
+async function phantomPause(ctx, paused) {
+	const args = argsFromFlags(ARGS.set_phantom_paused, ctx.flags, ctx.positionals, { paused });
+	printResult(ctx.io, ctx.flags, await ctx.client.callTool("set_phantom_paused", args));
+	return 0;
+}
+
 async function call(ctx, tool) {
 	const result = await ctx.client.callTool(tool, argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals));
 	printResult(ctx.io, ctx.flags, result);

package/lib/commands/site.mjs

@@ -177,7 +177,7 @@ const ARGS = {
 		},
 		base_branch: { flag: "base-branch" },
 		preview: { flag: "preview", type: "bool" },
-		action: { flag: "action", enum: ["build", "build_pr", "build_merge", "slack", "linear"] },
+		action: { flag: "action", enum: ["build", "build_pr", "build_merge", "slack", "linear", "handoff"] },
 		// --with-preview: the PR opens straight away and a preview of the fix stays up next to it.
 		with_preview: { flag: "with-preview", type: "bool" },
 	},
@@ -557,9 +557,19 @@ async function siteFix(ctx) {
 	const result = await client.callTool("fix_site_observations", args);
 	ok(ctx, result.message);
 	printResult(io, flags, result, (r) => {
-		const lines = [`${r.run.id}  ${r.run.repo}  [${r.run.status}]${r.reused ? "  (already running)" : ""}`];
+		// Handed off (action handoff, or slack / linear with no repo): no run; the prompt itself, or where it went.
+		const lines = r.run
+			? [`${r.run.id}  ${r.run.repo}  [${r.run.status}]${r.reused ? "  (already running)" : ""}`]
+			: r.handoff?.kind === "slack"
+				? [`sent to Slack${r.handoff.permalink ? `  ${r.handoff.permalink}` : ""}`]
+				: r.handoff?.kind === "linear"
+					? [
+							`filed in Linear${r.handoff.issue ? `  ${r.handoff.issue.identifier}  ${r.handoff.issue.url}` : ""}`,
+						]
+					: [];
 		for (const id of r.fixing) lines.push(`  fixing  ${id}`);
 		for (const s of r.skipped) lines.push(`  skipped ${s.id}  ${s.reason}`);
+		if (r.handoff?.kind === "prompt") lines.push("", r.handoff.instructions);
 		return lines.join("\n");
 	});
 	return 0;

package/package.json

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