@letterstory/cli 0.129.2 → 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.2";
+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
@@ -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

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/package.json

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