@letterstory/cli 0.129.2 → 0.131.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.2";
+export const VERSION = "0.131.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
@@ -1305,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
@@ -1316,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
@@ -1350,10 +1355,11 @@ Repo changes (Claude Code edits your repo in a sandbox; the Letterstory GitHub A
   repo suggestions                                     Fixes found and not acted on yet, and how to start each
   repo settings [--action build|build_pr|build_merge|slack|linear] [--branch <name>|none] [--slack-agent <name|U…>|none]
                 [--slack-channel <C…>|none] [--slack-reports off|as_found|daily] [--reports-channel <C…>|none] [--autopilot-channel <C…>|none] [--listen <C…,C…>|none] [--autopilot on|off] [--autopilot-weekly <1-20>]
-                [--autopilot-severity critical|warning]
+                [--autopilot-severity critical|warning] [--auto-merge 1h|12h|24h|3d|off]
                                                        The org's defaults for every fix: build (preview first),
                                                        build_pr, or slack (post it to --slack-channel for your
-                                                       own agent, tagging --slack-agent), and the branch changes go to
+                                                       own agent, tagging --slack-agent), and the branch changes go to;
+                                                       --auto-merge merges Letter's PRs once open that long
   repo slack-targets                                   Slack channels and people Send to Slack can use, with ids
   repo slack-test                                      Post a test into the Send to Slack channel
   repo start --repo <owner/name> --instructions <text>|--instructions-file <path|->

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/repo.mjs

@@ -165,6 +165,8 @@ const ARGS = {
 			value: (flags) => (flags["autopilot-weekly"] === undefined ? undefined : Number(flags["autopilot-weekly"])),
 		},
 		autopilot_min_severity: { flag: "autopilot-severity", enum: ["critical", "warning"] },
+		// --auto-merge 1h|12h|24h|3d (or the hours: 1, 12, 24, 72), or --auto-merge off
+		auto_merge_after_hours: { value: (flags) => autoMergeHours(flags["auto-merge"]) },
 	},
 	get_repo_change: { run_id: { positional: 0, required: true, label: "run-id" } },
 	get_repo_change_activity: { run_id: { positional: 0, required: true, label: "run-id" } },
@@ -195,6 +197,16 @@ const ARGS = {
 	},
 };
 
+/** `--auto-merge`: off → null, 1h / 12h / 24h / 3d or plain hours → the hours; anything else is passed on for the tool to refuse. */
+function autoMergeHours(value) {
+	if (value === undefined) return undefined;
+	const text = String(value).trim().toLowerCase();
+	if (["off", "none", "false", "0"].includes(text)) return null;
+	const match = /^(\d+)\s*(h|hours?|d|days?)?$/.exec(text);
+	if (!match) return text;
+	return Number(match[1]) * (match[2]?.startsWith("d") ? 24 : 1);
+}
+
 const TERMINAL = new Set(["succeeded", "no_changes", "failed", "cancelled"]);
 
 function describe(run) {
@@ -634,6 +646,7 @@ async function repoSettings(ctx) {
 		"autopilot",
 		"autopilot-weekly",
 		"autopilot-severity",
+		"auto-merge",
 	];
 	refuseUnknownFlags(ctx, {}, settingFlags);
 	const setting = settingFlags.some((f) => flags[f] !== undefined);

package/package.json

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