@letterstory/cli 0.81.2 → 0.82.2

package/README.md

@@ -437,7 +437,9 @@ letterstory admin crm payment-link <account-id>        # Stripe Payment Link at
 
 `onboard` runs org → link → phantom sites → Slack channel → checklist → app invites →
 stage in one call. Each site is a real (not test) fleet build; `--site ""` lets the engine
-infer its beat from the client's homepage. `onboard-plan` reads the account's recorded calls
+infer its beat from the client's homepage. `--disclose 2` (or `--disclose all`) turns on sponsor
+disclosure ("safe mode") for that site, and `--disclose-note "…"` records the client's words
+as the reason; `onboard-plan` flags the sites whose calls asked for it. `onboard-plan` reads the account's recorded calls
 (newest first, cached per set of calls; `--refresh` re-reads) and says how many sites, what each
 is about, who to invite, and whether they've paid. `payment-link` stamps the account's org on
 the Stripe subscription, so paying through it binds and marks the account paid by itself.

package/lib/cli.mjs

@@ -57,11 +57,12 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.81.2";
+export const VERSION = "0.82.2";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
-// can't accidentally swallow the id as --json's value.
-const BOOLEAN_FLAGS = new Set([
+// 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",
 	"yes",
 	"confirm-missing-target",
@@ -80,6 +81,8 @@ const BOOLEAN_FLAGS = new Set([
 	"rebuild",
 	"print-key",
 	"stdin",
+	// `authors generate <id> --with-bios`.
+	"with-bios",
 	// `covers generate <id> --regenerate` and `arena run --gate --article <id>`
 	// both put a value-less flag next to a value: without these entries the parser
 	// hands the following token to the flag and the real argument disappears.
@@ -129,8 +132,68 @@ const BOOLEAN_FLAGS = new Set([
 	// `prospects import|source --one-per-company`, `prospects source --enrich`.
 	"one-per-company",
 	"enrich",
-	// `targets update <id> --clear-framing`.
+	// `targets update <id> --clear-framing`; `targets subqueries --retired`,
+	// `targets subquery update <id> --retire` / `--restore`.
 	"clear-framing",
+	"retired",
+	"retire",
+	"restore",
+	// Bool flags from command ARGS maps that were missing here.
+	"apply-rules",
+	"async",
+	"configure",
+	"detect-reply-opt-outs",
+	"experience-claims",
+	"maverick",
+	"no-detect-reply-opt-outs",
+	"no-maverick",
+	"no-notify-staff",
+	"no-opt-out-footer",
+	"no-postal-address-footer",
+	"no-redesign",
+	"no-test-mode",
+	"no-unsubscribe-links",
+	"now",
+	"opt-out-footer",
+	"postal-address-footer",
+	"redesign",
+	"release-mailbox",
+	"rival",
+	"shred",
+	"shred-judge",
+	"shred-skip-voice-bearing",
+	"shred-turnover-avoid-list",
+	"test-mode",
+	"unsubscribe-links",
+	// Switches read directly (`flags["x"] === true` / `flagBool(flags["x"])`) or once read
+	// through `value:` functions.
+	"active-only",
+	"clear-seer",
+	"flag-wrong",
+	"ledger-scope",
+	"lift-budget",
+	"no-configure",
+	"no-produce",
+	"no-publish",
+	"no-rebuild",
+	"null-check",
+	"replied",
+	"sent",
+	"sweep",
+	// Switches read in dot form (`flags.x === true` / `flagBool(flags.x)`).
+	"all",
+	"byok",
+	"clear",
+	"closed",
+	"create",
+	"live",
+	"regrade",
+	"rule",
+	"sql",
+	"steps",
+	"suggested",
+	"sync",
+	"texts",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -277,7 +340,8 @@ Collections:
 
 Authors (the per-collection author bank — recurring bylines):
   authors list <collection-id>                        List the bank + byline distribution
-  authors generate <collection-id> [--count <n>]      Generate a believable masthead
+  authors generate <collection-id> [--count <n>] [--with-bios]
+                                                      Generate a masthead (names only; --with-bios adds a one-line bio + role)
   authors add <collection-id> --name <n> [--bio <t>] [--role <t>] [--expertise a,b] [--started-at YYYY-MM-DD]
   authors edit <collection-id> <author-id> [--name] [--bio] [--role] [--expertise a,b] [--started-at] [--active true|false]
   authors retire <collection-id> <author-id>          Stop assigning new posts to them
@@ -381,6 +445,9 @@ Ranking targets (what the org wants to be THE answer for — company-wide or on
   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)
+  targets subqueries [<target-id>] [--retired]         The phrasings asked under each target (who retired one, and why)
+  targets subquery add <target-id> <phrasing>          Another way your buyers ask a target's question
+  targets subquery update <subquery-id> [--text <t>] [--retire | --restore]
 
 Arenas (adversarial clusters of research agents -> a sourced, fact-checked outline):
   arena run --topic <text> [--source <url> …] [--must-include <text> …] [--depth barebones|fleshed_out]
@@ -457,6 +524,7 @@ Phantom launch recipe (a CLIENT domain -> a live phantom with its first posts; d
   ${bin === "phantom" ? "onboard" : "phantom-onboard"} <domain> [--about "the beat"] [--name X]
           [--posts N] [--cadence N] [--cover editorial_image|full_ai|line_art] [--theme T]
           [--real] [--domain host] [--domain-mode subdomain|buy_now|connect_later]
+          [--disclose [surfaces]] [--sponsor-label X] [--disclose-note "why"]
           [--accept] [--dry-run]
                                                        Plan (read-only) then, with --accept
                                                        or an override flag, provision + configure
@@ -930,6 +998,9 @@ Mail:
 
 Insights:
   insights summary [--period …] [--part <block>]...    Measure Overview: AI named/cited rates, share of voice, search, targets
+  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
   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]

package/lib/commands/admin.mjs

@@ -2405,7 +2405,11 @@ function planLines(p) {
 		`domain: ${p.domain ?? "(unknown)"}`,
 		`sites: ${p.sites.length}`,
 		...p.sites.map(
-			(s, i) => `  ${i + 1}. ${s.direction || "(infer from their homepage)"}${s.why ? `  — ${s.why}` : ""}`
+			(s, i) =>
+				`  ${i + 1}. ${s.direction || "(infer from their homepage)"}${s.why ? `  — ${s.why}` : ""}` +
+				(s.disclose_sponsor?.recommended
+					? `\n     disclose the sponsor (--disclose ${i + 1})${s.disclose_sponsor.quote ? `: “${s.disclose_sponsor.quote}”` : ""}`
+					: "")
 		),
 		`slack: ${p.slackEmails.join(", ") || "(nobody found)"}`,
 		`invites: ${p.invites.map((i) => `${i.email}:${i.role}`).join(", ") || "(none)"}`,
@@ -2418,19 +2422,35 @@ function planLines(p) {
 /**
  * `admin crm onboard` body from flags — the same CrmOnboardBodySchema the desk sends.
  * --site "<direction>" per site (repeatable; "" = infer from the homepage) and/or
- * --sites N (pads with inferred sites); --slack a@x,b@x (bare --slack = the channel, no
- * invites yet); --invite email[:admin|editor] (repeatable); --no-checklist.
+ * --sites N (pads with inferred sites); --disclose N (repeatable, 1-based; "all") turns on
+ * sponsor disclosure ("safe mode": the line after each article + schema.org sponsor) for
+ * that site, with --disclose-note "<the client's words>" as the reason; --slack a@x,b@x
+ * (bare --slack = the channel, no invites yet); --invite email[:admin|editor] (repeatable);
+ * --no-checklist.
  */
 function onboardBody(flags) {
 	const domain = flagStr(flags.domain);
 	if (!domain) {
 		throw new CliError(
-			'Usage: admin crm onboard <account-id> --domain acme.com [--name "Acme"] [--site "<direction>"]… [--sites N] [--slack a@x,b@x] [--invite a@x[:admin]]… [--no-checklist]'
+			'Usage: admin crm onboard <account-id> --domain acme.com [--name "Acme"] [--site "<direction>"]… [--sites N] [--disclose N|all]… [--disclose-note "…"] [--slack a@x,b@x] [--invite a@x[:admin]]… [--no-checklist]'
 		);
 	}
 	const sites = flagList(flags.site).map((direction) => ({ direction: direction.trim() || null }));
 	const total = flagNum(flags.sites);
 	while (total !== undefined && sites.length < total) sites.push({ direction: null });
+	const disclose = flagList(flags.disclose)
+		.flatMap((v) => String(v).split(","))
+		.map((v) => v.trim())
+		.filter(Boolean);
+	const note = flagStr(flags["disclose-note"]);
+	for (const which of disclose) {
+		const targets =
+			which === "all"
+				? sites.map((_, i) => i)
+				: [Number(which) - 1].filter((i) => Number.isInteger(i) && i >= 0 && i < sites.length);
+		if (targets.length === 0) throw new CliError(`--disclose ${which}: no such site (1–${sites.length}, or "all")`);
+		for (const i of targets) sites[i] = { ...sites[i], disclosure: compact({ note }) };
+	}
 	const slackEmails = flagList(flags.slack)
 		.flatMap((v) => v.split(","))
 		.map((e) => e.trim())

package/lib/commands/authors.mjs

@@ -61,7 +61,11 @@ async function authorsList(ctx) {
 
 async function authorsGenerate(ctx) {
 	const { client, flags, io } = ctx;
-	const args = compact({ collection_id: collectionId(ctx), count: flagNum(flags.count) });
+	const args = compact({
+		collection_id: collectionId(ctx),
+		count: flagNum(flags.count),
+		with_bios: flagBool(flags["with-bios"]) || undefined,
+	});
 	const result = await client.callTool("generate_collection_authors", args);
 	ok(ctx, "Generated authors.");
 	printResult(io, flags, result);
@@ -98,7 +102,7 @@ async function authorsEdit(ctx) {
 		role: flagStr(flags.role),
 		expertise: flagList(flags.expertise),
 		started_at: flagStr(flags["started-at"]),
-		active: flagBool(flags.active),
+		active: flags.active === true || flags.active === "true" ? true : flags.active === "false" ? false : undefined,
 	});
 	if (Object.keys(patch).length <= 2) {
 		throw new CliError(
@@ -156,7 +160,7 @@ async function authorsAssign(ctx) {
 		author_id: authorId,
 		article_ids: all ? undefined : articleIds,
 		all: all ? true : undefined,
-		rebuild: flags["no-rebuild"] ? false : undefined,
+		rebuild: flags["no-rebuild"] === true ? false : undefined,
 	});
 	const result = await client.callTool("assign_collection_authors", args);
 	ok(ctx, authorId ? "Reassigned bylines to the chosen author." : "Auto-distributed bylines across active authors.");

package/lib/commands/collection.mjs

@@ -79,12 +79,12 @@ export const ARGS = {
 		must_include: { flag: "must-include", type: "list" },
 		research_depth: { flag: "depth", enum: ["barebones", "fleshed_out"] },
 		kernel_id: { flag: "kernel" },
-		verify: { value: (flags) => (flags["no-verify"] === true ? false : undefined) },
+		verify: { flag: "no-verify", type: "bool", invert: true },
 		shred: { flag: "shred", type: "bool" },
 		mention_degree: { flag: "mention", enum: ["off", "subtle", "woven"] },
 		approval_mode: { flag: "approval", enum: ["autopilot", "review_window", "manual"] },
-		publish: { value: (flags) => (flags["no-publish"] === true ? false : undefined) },
-		rebuild: { value: (flags) => (flags["no-rebuild"] === true ? false : undefined) },
+		publish: { flag: "no-publish", type: "bool", invert: true },
+		rebuild: { flag: "no-rebuild", type: "bool", invert: true },
 		schedule_for: { flag: "at" },
 	},
 	get_collection_run: {

package/lib/commands/insights.mjs

@@ -27,6 +27,12 @@ export const ARGS = {
 	get_share_of_voice_detail: {
 		period: { flag: "period", enum: PERIODS },
 	},
+	get_share_of_voice_question: {
+		question_key: { positional: 0, label: "question-key", required: true },
+		period: { flag: "period", enum: PERIODS },
+		filter: { flag: "filter", enum: ["all", "named_you", "rival_not_you", "no_one"] },
+		limit: { flag: "limit", type: "num" },
+	},
 };
 
 export async function cmdInsights(ctx) {
@@ -47,9 +53,11 @@ export async function cmdInsights(ctx) {
 			return call(rest, "get_measure_summary");
 		case "competitors":
 			return call(rest, "get_share_of_voice_detail");
+		case "question":
+			return call(rest, "get_share_of_voice_question");
 		default:
 			throw new CliError(
-				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, competitors, site, post, top, bank, access`
+				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, competitors, question, site, post, top, bank, access`
 			);
 	}
 }

package/lib/commands/lede.mjs

@@ -56,7 +56,7 @@ export const ARGS = {
 		// Your own fallback line, returned (unbilled, still no_match) when nothing qualifies.
 		default_lede: { flag: "default-lede" },
 		// Enrichment is ON by default server-side; `--no-enrich` skips it for latency.
-		enrich: { value: (flags) => (flags["no-enrich"] === true ? false : undefined) },
+		enrich: { flag: "no-enrich", type: "bool", invert: true },
 		// A latency budget: optional evidence that cannot arrive in time is left out.
 		deadline_ms: { flag: "deadline-ms", type: "num" },
 		// Advanced: keep specific library lines out of this run (repeatable, by line id).
@@ -75,7 +75,7 @@ export const ARGS = {
 	},
 	// The state of the quality exercise: which evals still count above zero.
 	lede_eval_briefing: {
-		sweep: { value: (flags) => (flags.sweep === true ? true : undefined) },
+		sweep: { flag: "sweep", type: "bool" },
 	},
 	// What has already been said to an account, so the next send does not repeat it.
 	lede_account_history: {
@@ -90,10 +90,10 @@ export const ARGS = {
 	report_lede_outcome: {
 		run_id: { positional: 0, label: "run-id", required: true },
 		shipped_template_id: { flag: "shipped-template" },
-		sent: { value: (flags) => (flags.sent === true ? true : undefined) },
-		replied: { value: (flags) => (flags.replied === true ? true : undefined) },
+		sent: { flag: "sent", type: "bool" },
+		replied: { flag: "replied", type: "bool" },
 		reply_sentiment: { flag: "sentiment", enum: ["positive", "neutral", "negative"] },
-		flagged_wrong: { value: (flags) => (flags["flag-wrong"] === true ? true : undefined) },
+		flagged_wrong: { flag: "flag-wrong", type: "bool" },
 		flagged_reason: { flag: "reason" },
 	},
 	// Per line: picked, sent, replied, positive, flagged wrong.

package/lib/commands/onboard.mjs

@@ -151,6 +151,23 @@ export const ARGS = {
 				is_test: { flag: "real", type: "bool", invert: true },
 				// A self-serve integrator's customers launch their own sites: no staff pings.
 				notify_staff: { flag: "no-notify-staff", type: "bool", invert: true },
+				// Sponsor disclosure ("safe mode"): bare --disclose = the safe-mode surfaces (the
+				// server's default); --disclose article_footer,cover_badge picks them. Off unless asked.
+				disclosure: {
+					value: (flags) => {
+						if (flags.disclose === undefined || flags.disclose === false) return undefined;
+						const listed = typeof flags.disclose === "string" ? flags.disclose : "";
+						const surfaces = listed
+							.split(",")
+							.map((s) => s.trim())
+							.filter(Boolean);
+						return compact({
+							surfaces: surfaces.length ? surfaces : undefined,
+							sponsor_label: flagStr(flags["sponsor-label"]),
+							note: flagStr(flags["disclose-note"]),
+						});
+					},
+				},
 			},
 		},
 	},

package/lib/commands/phantom.mjs

@@ -57,7 +57,7 @@ export const ARGS = {
 		theme: "theme",
 		collection_id: { flag: "collection" },
 		customer_ref: { flag: "customer-ref" },
-		configure: { value: (flags) => (flags["no-configure"] === true ? false : undefined) },
+		configure: { flag: "no-configure", type: "bool", invert: true },
 		config: { value: (flags) => readJsonObjectFlag(flags, "config") },
 		composition: { value: (flags) => readJsonObjectFlag(flags, "composition") },
 		client_domain: { flag: "client-domain" },

package/lib/commands/seers.mjs

@@ -39,7 +39,7 @@ export const ARGS = {
 	run_seer: {
 		seer_id: { positional: 0, label: "seer-id", required: true },
 		dry_run: { flag: "dry-run", type: "bool" },
-		produce: { value: (flags) => (flags["no-produce"] === true ? false : undefined) },
+		produce: { flag: "no-produce", type: "bool", invert: true },
 		async: { flag: "async", type: "bool" },
 	},
 	get_seer_run: {

package/lib/commands/targets.mjs

@@ -86,9 +86,35 @@ export const ARGS = {
 		},
 	},
 	suggest_ranking_targets: { offering_id: offering },
+	list_ranking_subqueries: {
+		target_id: { positional: 0, label: "target-id" },
+		include_retired: { flag: "retired", type: "bool" },
+	},
+	add_ranking_subquery: {
+		target_id: { positional: 0, label: "target-id", required: true },
+		// The phrasing is every positional after the target, so it needs no quotes.
+		text: {
+			value: (_flags, positionals) => {
+				const text = positionals.slice(1).join(" ").trim();
+				if (!text) throw new CliError("Missing required <phrasing>");
+				return text;
+			},
+		},
+	},
+	update_ranking_subquery: {
+		subquery_id: { positional: 0, label: "subquery-id", required: true },
+		text: "text",
+		status: {
+			value: (flags) => {
+				if (flags.retire === true && flags.restore === true)
+					throw new CliError("Pass --retire or --restore, not both");
+				return flags.retire === true ? "retired" : flags.restore === true ? "active" : undefined;
+			},
+		},
+	},
 };
 
-const USAGE = `Usage: targets <list|add|update|activate|deactivate|cap|suggest>
+const USAGE = `Usage: targets <list|add|update|activate|deactivate|cap|suggest|subqueries|subquery>
   targets list [--offering <offering-id|company>]
   targets add <phrase> [--framing <f>] [--offering <offering-id|company>] [--priority high|normal|low]
   targets update <target-id> [--phrase <p>] [--framing <f> | --clear-framing] [--offering <offering-id|company>]
@@ -96,7 +122,10 @@ const USAGE = `Usage: targets <list|add|update|activate|deactivate|cap|suggest>
   targets activate <target-id>
   targets deactivate <target-id>
   targets cap <offering-id|company> <n|default>
-  targets suggest [--offering <offering-id|company>]`;
+  targets suggest [--offering <offering-id|company>]
+  targets subqueries [<target-id>] [--retired]            the phrasings asked under each target
+  targets subquery add <target-id> <phrasing>
+  targets subquery update <subquery-id> [--text <t>] [--retire | --restore]`;
 
 export async function cmdTargets(ctx) {
 	const sub = ctx.positionals[0];
@@ -117,6 +146,10 @@ export async function cmdTargets(ctx) {
 			return targetsCap(rest);
 		case "suggest":
 			return targetsSuggest(rest);
+		case "subqueries":
+			return subqueriesList(rest);
+		case "subquery":
+			return subqueryWrite(rest);
 		default:
 			throw new CliError(USAGE);
 	}
@@ -239,3 +272,56 @@ async function targetsSuggest(ctx) {
 	});
 	return 0;
 }
+
+function formatSubquery(q) {
+	const who = q.source === "user" ? "  (yours)" : "";
+	const retired = q.status === "retired" ? `  [retired by ${q.retired_by ?? "?"}: ${q.retired_reason ?? ""}]` : "";
+	return `  ${q.id}  ${q.text}${who}${retired}`;
+}
+
+async function subqueriesList(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	const result = await client.callTool(
+		"list_ranking_subqueries",
+		argsFromFlags(ARGS.list_ranking_subqueries, flags, positionals)
+	);
+	printResult(io, flags, result, (r) => {
+		const items = r.items ?? [];
+		if (!items.length)
+			return "No phrasings yet — the next GEO cycle proposes them, or add one: targets subquery add";
+		const byTarget = new Map();
+		for (const q of items) byTarget.set(q.target_id, [...(byTarget.get(q.target_id) ?? []), q]);
+		return [...byTarget]
+			.map(([target, qs]) => [`Target ${target}`, ...qs.map(formatSubquery)].join("\n"))
+			.join("\n\n");
+	});
+	return 0;
+}
+
+// `subquery add <target-id> <phrasing>` / `subquery update <subquery-id> [--text] [--retire|--restore]`
+async function subqueryWrite(ctx) {
+	const { client, flags, io } = ctx;
+	const action = ctx.positionals[0];
+	const positionals = ctx.positionals.slice(1);
+	if (action === "add") {
+		refuseUnknownFlags(ctx, ARGS.add_ranking_subquery);
+		const result = await client.callTool(
+			"add_ranking_subquery",
+			argsFromFlags(ARGS.add_ranking_subquery, flags, positionals)
+		);
+		ok(ctx, "Added — it is asked from the next GEO cycle.");
+		printResult(io, flags, result, (r) => formatSubquery(r.subquery));
+		return 0;
+	}
+	if (action === "update") {
+		refuseUnknownFlags(ctx, ARGS.update_ranking_subquery, ["retire", "restore"]);
+		const args = argsFromFlags(ARGS.update_ranking_subquery, flags, positionals);
+		if (Object.keys(args).length === 1)
+			throw new CliError("Nothing to update — pass --text, --retire or --restore.");
+		const result = await client.callTool("update_ranking_subquery", args);
+		ok(ctx, `Saved — ${result.subquery?.status}.`);
+		printResult(io, flags, result, (r) => formatSubquery(r.subquery));
+		return 0;
+	}
+	throw new CliError(USAGE);
+}

package/package.json

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