@letterstory/cli 0.38.0 → 0.39.1

package/README.md

@@ -590,6 +590,20 @@ letterstory insights post <article-id> [--period 14d|30d|90d]
 letterstory insights top [--period 14d|30d|90d] [--collection <uuid>] [--limit <n>] [--sort clicks|impressions]
 ```
 
+AI visibility and page access — the Measure tabs' reads, for scripts and agents:
+
+```bash
+# The AI Visibility Bank: which questions named you, cited your pages, or both (a
+# breakthrough). All time unless --period; --source picks the phantom network
+# (default), your marketing site, or the whole portfolio; --phantom narrows to
+# specific phantom sites (repeatable); --answers caps receipts per question.
+letterstory insights bank [--source phantoms|marketing|all] [--phantom <uuid>]... [--period 14d|30d|90d] [--answers <n>]
+
+# Page access: AI answer engines, search crawlers and confirmed human readers on
+# your phantom sites; --collection narrows to the site(s) a collection publishes.
+letterstory insights access [--period 14d|30d|90d] [--collection <uuid>]
+```
+
 ## Anything else
 
 Every Letterstory tool is reachable, not just the ones with a dedicated command group:

package/lib/cli.mjs

@@ -47,10 +47,11 @@ import {
 	cmdAdmin,
 	cmdFeedback,
 	cmdOfferings,
+	cmdTargets,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.38.0";
+export const VERSION = "0.39.1";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -116,6 +117,8 @@ const BOOLEAN_FLAGS = new Set([
 	"none",
 	// `prospects import|source --one-per-company`.
 	"one-per-company",
+	// `targets update <id> --clear-framing`.
+	"clear-framing",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -344,6 +347,19 @@ Offerings (context layered org → offering → collection; a layer sets only wh
   series create --name <n> --description <d> [--coverage a,b,c] [--collection <uuid>] [--template <key>]
   series backfill <series-id> [--collection <uuid>]    Reconstruct a series from existing posts
 
+Ranking targets (what the org wants to be THE answer for — company-wide or on one offering):
+  targets list [--offering <offering-id|company>]      Targets grouped by scope, each with its active cap and usage
+  targets add <phrase> [--framing <f>] [--offering <offering-id|company>]
+                                                       Lands active while its scope has room, inactive after —
+                                                       adding never fails on the cap
+  targets update <target-id> [--phrase <p>] [--framing <f> | --clear-framing] [--offering <offering-id|company>]
+                   [--position <n>] [--state active|inactive|achieved|retired]
+                                                       Moving an ACTIVE target needs room in the new scope
+  targets activate | deactivate <target-id>            Switch a target on/off; activating is refused at the cap
+  targets cap <offering-id|company> <n|default>        Active targets allowed in that scope (preset 5; default =
+                                                       inherit the company's cap / back to the preset)
+  targets suggest [--offering <offering-id|company>]   Evidence-informed suggestions (nothing saved)
+
 Arenas (adversarial clusters of research agents -> a sourced, fact-checked outline):
   arena run --topic <text> [--source <url> …] [--must-include <text> …] [--depth barebones|fleshed_out]
             [--gate] [--no-verify] [--provider native|exa|youcom|firecrawl] [--mention off|subtle|woven]
@@ -740,12 +756,17 @@ Prospects (who you write to):
            [--city] [--country] [--years] [--notes] [--custom key=value]...
 
 Mail:
-  mail connections                                     Connected mailboxes, Google connect + Vercel key status
+  mail connections                                     Connected mailboxes, Google connect, Vercel key + mailing address status
+  mail postal-address "<address>"                      Set the org's CAN-SPAM mailing address (email footers)
 
 Insights:
   insights site [--period 14d|30d|90d] [--collection <uuid>]
   insights post <article-id> [--period 14d|30d|90d]
   insights top [--period 14d|30d|90d] [--collection <uuid>] [--limit <n>] [--sort clicks|impressions]
+  insights bank [--source phantoms|marketing|all] [--phantom <uuid>]... [--period 14d|30d|90d] [--answers <n>]
+                                                       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
 
 Feedback (tell us what's broken, missing, unclear, or wanted):
   feedback submit --category bug|missing_feature|unclear|feature_request|praise|other
@@ -802,6 +823,7 @@ const CLIENT_COMMANDS = {
 	strategy: cmdStrategy,
 	directives: cmdDirectives,
 	offerings: cmdOfferings,
+	targets: cmdTargets,
 	probes: cmdProbes,
 	suggestions: cmdSuggestions,
 	onboarding: cmdOnboarding,

package/lib/commands/insights.mjs

@@ -1,9 +1,25 @@
 // `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.
+// network, single-post, and top-posts levels (ported from phantomstory-cli's
+// insights.ts); plus Measure's AI Visibility Bank (`bank`) and phantom Page
+// Access (`access`) — the same reads the web app's Measure tabs render.
 
 import { CliError } from "../client.mjs";
-import { flagStr, flagNum, requirePositional, printResult, compact } from "./shared.mjs";
+import { flagStr, flagNum, requirePositional, printResult, compact, argsFromFlags } from "./shared.mjs";
+
+const PERIODS = ["14d", "30d", "90d"];
+
+export const ARGS = {
+	get_ai_visibility_bank: {
+		source: { flag: "source", enum: ["phantoms", "marketing", "all"] },
+		phantom_ids: { flag: "phantom", type: "list" },
+		period: { flag: "period", enum: PERIODS },
+		answers_per_prompt: { flag: "answers", type: "num" },
+	},
+	get_page_access: {
+		period: { flag: "period", enum: PERIODS },
+		collection_id: { flag: "collection" },
+	},
+};
 
 export async function cmdInsights(ctx) {
 	const sub = ctx.positionals[0];
@@ -15,8 +31,12 @@ export async function cmdInsights(ctx) {
 			return insightsPost(rest);
 		case "top":
 			return insightsTop(rest);
+		case "bank":
+			return call(rest, "get_ai_visibility_bank");
+		case "access":
+			return call(rest, "get_page_access");
 		default:
-			throw new CliError(`Unknown insights subcommand: ${sub ?? "(none)"}. Try: site, post, top`);
+			throw new CliError(`Unknown insights subcommand: ${sub ?? "(none)"}. Try: site, post, top, bank, access`);
 	}
 }
 
@@ -49,3 +69,9 @@ async function insightsTop(ctx) {
 	printResult(io, flags, result);
 	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);
+	return 0;
+}

package/lib/commands/outbound.mjs

@@ -167,6 +167,9 @@ export const ARGS = {
 		custom: { value: readCustom },
 	},
 	get_mail_connections: {},
+	set_mail_postal_address: {
+		mail_postal_address: { positional: 0, label: "address", required: true },
+	},
 };
 
 // Flags the computed `value` sources read (refuseUnknownFlags can't see them).
@@ -318,7 +321,9 @@ export async function cmdMail(ctx) {
 		case "connections":
 		case "status":
 			return run(rest, "get_mail_connections");
+		case "postal-address":
+			return run(rest, "set_mail_postal_address", "Mailing address saved.");
 		default:
-			throw new CliError(`Unknown mail subcommand: ${sub ?? "(none)"}. Try: connections`);
+			throw new CliError(`Unknown mail subcommand: ${sub ?? "(none)"}. Try: connections, postal-address`);
 	}
 }

package/lib/commands/targets.mjs

@@ -0,0 +1,223 @@
+// `targets` — ranking targets: what the org wants to be THE answer for.
+//
+// A target belongs to the company (company-wide) or to one offering. Each scope — the
+// company layer and every offering — holds its own ACTIVE targets up to its cap (a preset
+// of 5, adjustable per scope with `targets cap`); inactive targets are never capped, so
+// `add` never fails on the cap: it lands inactive when the scope is full. Thin wrappers
+// over the MCP tools, which call the same store functions the app's /api/ranking-targets
+// routes and staff Fleet do.
+
+import { CliError } from "../client.mjs";
+import { flagStr, flagNum, printResult, argsFromFlags, refuseUnknownFlags, ok } from "./shared.mjs";
+
+const STATUSES = ["active", "inactive", "achieved", "retired"];
+const COMPANY = "company";
+
+// `--offering <offering-id|company>`: company = the company layer (null). Absent = not sent.
+function readOffering(flags) {
+	const v = flagStr(flags.offering);
+	if (v === undefined) {
+		if (flags.offering === true) throw new CliError("--offering takes an offering id, or `company`");
+		return undefined;
+	}
+	return v === COMPANY ? null : v;
+}
+const offering = { value: readOffering };
+
+// How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
+// `scripts/parity-check.ts` compares these keys against each tool's published input schema.
+export const ARGS = {
+	list_ranking_targets: { offering_id: offering },
+	add_ranking_target: {
+		// The phrase is every positional, so `targets add best payroll software` needs no quotes.
+		phrase: {
+			value: (_flags, positionals) => {
+				const phrase = positionals.join(" ").trim();
+				if (!phrase) throw new CliError("Missing required <phrase>");
+				return phrase;
+			},
+		},
+		mention_framing: "framing",
+		offering_id: offering,
+	},
+	update_ranking_target: {
+		target_id: { positional: 0, label: "target-id", required: true },
+		phrase: "phrase",
+		mention_framing: {
+			value: (flags) => (flags["clear-framing"] === true ? null : flagStr(flags.framing)),
+		},
+		// `activate` / `deactivate` set this for you.
+		status: { flag: "state", enum: STATUSES },
+		offering_id: offering,
+		position: { flag: "position", type: "num" },
+	},
+	set_ranking_target_cap: {
+		offering_id: {
+			value: (_flags, positionals) => {
+				const scope = positionals[0];
+				if (scope === undefined) throw new CliError("Missing required <offering-id|company>");
+				return scope === COMPANY ? null : scope;
+			},
+		},
+		// `default` = back to inheriting (an offering → the company's cap; the company → the preset).
+		cap: {
+			value: (_flags, positionals) => {
+				const raw = positionals[1];
+				if (raw === undefined) throw new CliError("Missing required <n|default>");
+				return raw === "default" ? null : flagNum(raw);
+			},
+		},
+	},
+	suggest_ranking_targets: { offering_id: offering },
+};
+
+const USAGE = `Usage: targets <list|add|update|activate|deactivate|cap|suggest>
+  targets list [--offering <offering-id|company>]
+  targets add <phrase> [--framing <f>] [--offering <offering-id|company>]
+  targets update <target-id> [--phrase <p>] [--framing <f> | --clear-framing] [--offering <offering-id|company>]
+                 [--position <n>] [--state active|inactive|achieved|retired]
+  targets activate <target-id>
+  targets deactivate <target-id>
+  targets cap <offering-id|company> <n|default>
+  targets suggest [--offering <offering-id|company>]`;
+
+export async function cmdTargets(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return targetsList(rest);
+		case "add":
+			return targetsAdd(rest);
+		case "update":
+			return targetsUpdate(rest);
+		case "activate":
+			return targetsSetStatus(rest, "active");
+		case "deactivate":
+			return targetsSetStatus(rest, "inactive");
+		case "cap":
+			return targetsCap(rest);
+		case "suggest":
+			return targetsSuggest(rest);
+		default:
+			throw new CliError(USAGE);
+	}
+}
+
+const scopeName = (s) => (s.offeringId === null ? "Company-wide" : s.label);
+
+function formatScope(s) {
+	const where = s.capSetHere ? "set here" : s.offeringId === null ? "preset" : "company's cap";
+	return `${scopeName(s)} — ${s.active}/${s.cap} active (${where})`;
+}
+
+function formatTarget(t) {
+	const framing = t.mention_framing ? ` — as ${t.mention_framing}` : "";
+	return `  ${t.id}  [${t.status}]  ${t.phrase}${framing}`;
+}
+
+// Targets grouped under their scope, each headed by its cap and usage. A target on an
+// offering the scopes list doesn't carry (archived) still shows, under its id.
+export function formatTargets(r) {
+	const scopes = r.scopes ?? [];
+	const items = r.items ?? [];
+	if (!items.length && !scopes.length) return "No ranking targets yet.";
+	const lines = [];
+	const shown = new Set();
+	for (const s of scopes) {
+		const mine = items.filter((t) => (t.offering_id ?? null) === s.offeringId);
+		lines.push(formatScope(s));
+		for (const t of mine) {
+			lines.push(formatTarget(t));
+			shown.add(t.id);
+		}
+		if (!mine.length) lines.push("  (none)");
+	}
+	const orphans = items.filter((t) => !shown.has(t.id));
+	for (const id of [...new Set(orphans.map((t) => t.offering_id))]) {
+		lines.push(`Offering ${id} (not active)`);
+		for (const t of orphans.filter((o) => o.offering_id === id)) lines.push(formatTarget(t));
+	}
+	return lines.join("\n");
+}
+
+async function targetsList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_ranking_targets", argsFromFlags(ARGS.list_ranking_targets, flags));
+	printResult(io, flags, result, formatTargets);
+	return 0;
+}
+
+async function targetsAdd(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.add_ranking_target, ["offering"]);
+	const result = await client.callTool(
+		"add_ranking_target",
+		argsFromFlags(ARGS.add_ranking_target, flags, positionals)
+	);
+	const t = result.target;
+	ok(
+		ctx,
+		t?.status === "active"
+			? `Added "${t.phrase}" — active.`
+			: `Added "${t?.phrase}" as inactive: its scope is at its active cap. Deactivate one there, or raise the cap (targets cap), then: ${ctx.bin} targets activate ${t?.id}`
+	);
+	printResult(io, flags, result, (r) => formatTarget(r.target));
+	return 0;
+}
+
+async function update(ctx, flags) {
+	const { client, positionals, io } = ctx;
+	const args = argsFromFlags(ARGS.update_ranking_target, flags, positionals);
+	if (Object.keys(args).length === 1) {
+		throw new CliError(
+			"Nothing to update — pass --phrase, --framing, --clear-framing, --offering, --position or --state."
+		);
+	}
+	const result = await client.callTool("update_ranking_target", args);
+	ok(ctx, `Updated "${result.target?.phrase}" — ${result.target?.status}.`);
+	printResult(io, ctx.flags, result, (r) => formatTarget(r.target));
+	return 0;
+}
+
+async function targetsUpdate(ctx) {
+	refuseUnknownFlags(ctx, ARGS.update_ranking_target, ["framing", "clear-framing", "offering"]);
+	return update(ctx, ctx.flags);
+}
+
+// Activate / deactivate are the first-class switch. Activating is refused when the
+// target's scope is at its cap — the server's message names the scope.
+async function targetsSetStatus(ctx, status) {
+	refuseUnknownFlags(ctx, {});
+	return update(ctx, { ...ctx.flags, state: status });
+}
+
+async function targetsCap(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, {});
+	const result = await client.callTool(
+		"set_ranking_target_cap",
+		argsFromFlags(ARGS.set_ranking_target_cap, flags, positionals)
+	);
+	ok(ctx, "Cap saved.");
+	printResult(io, flags, result, (r) => (r.scopes ?? []).map(formatScope).join("\n"));
+	return 0;
+}
+
+async function targetsSuggest(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("suggest_ranking_targets", argsFromFlags(ARGS.suggest_ranking_targets, flags));
+	printResult(io, flags, result, (r) => {
+		const all = r.suggestions ?? [];
+		if (!all.length) return "No suggestions yet — add positioning first.";
+		const scope = r.offering_id ? ` --offering ${r.offering_id}` : "";
+		const lines = all.map(
+			(s) =>
+				`  ${s.phrase} [${s.basis}]${s.suggestedFraming ? ` — as ${s.suggestedFraming}` : ""}\n    ${s.rationale}`
+		);
+		lines.push(`Nothing saved. Keep one with: ${ctx.bin} targets add <phrase>${scope}`);
+		return lines.join("\n");
+	});
+	return 0;
+}

package/lib/commands.mjs

@@ -34,5 +34,6 @@ export * from "./commands/shredder.mjs";
 export * from "./commands/landings.mjs";
 export * from "./commands/outbound.mjs";
 export * from "./commands/offerings.mjs";
+export * from "./commands/targets.mjs";
 export * from "./commands/admin.mjs";
 export * from "./commands/feedback.mjs";

package/package.json

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