@letterstory/cli 0.176.72 → 0.176.73

package/lib/cli.mjs

@@ -85,7 +85,7 @@ import {
 import { fetchParkedSections, withoutParked } from "./parked.mjs";
 
 // Matches cli/package.json; publish-cli.yml rewrites both to the published version.
-export const VERSION = "0.176.72";
+export const VERSION = "0.176.73";
 
 /** The exit code for a gate refusal (CARD_REQUIRED, PAYMENT_FAILED, OUT_OF_TOKENS): 1 is a plain error. */
 export const EXIT_PAYMENT_REQUIRED = 3;
@@ -94,6 +94,8 @@ export const EXIT_PAYMENT_REQUIRED = 3;
 // 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([
+	// admin targets check: check every target again, checked or not.
+	"recheck",
 	// build list: also move the builds' open changes along while polling.
 	"advance",
 	// build list: only what the Plan started.
@@ -828,6 +830,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 candidates [--limit <n>]                     New questions the market asks (new Search Console queries,
+                                                       questions rivals win, rivals' new pages, answer criteria),
+                                                       each checked and deduped against your targets (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]
@@ -1059,6 +1064,15 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
   admin recipes reread --org <id>,…                    Read these companies from their sites again: what was
                                                        only ever inferred is replaced, what the company changed
                                                        is kept. Refit them after. Needs recipes:write.
+  admin targets check [--org <id>,…] [--recheck] [--limit 10]
+                                                       Check ranking targets' phrases (buyer intent, self-named,
+                                                       search demand, fit) and store each verdict: --org those
+                                                       accounts; neither, every account with unchecked ones.
+                                                       Needs fleet:instrument.
+  admin targets add-candidates <org-id> [--limit 5] [--apply]
+                                                       Add the account's keep-verdict question candidates as
+                                                       active targets within its cap; a dry run unless --apply.
+                                                       Needs fleet:instrument.
   admin letterpress status [--customers]               Letterpress as it runs now: per lens its mode, bar, recipes,
                                                        runs, model and prompt hash, how often the shadow agreed,
                                                        how runs grounded (a recipe / none). Needs recipes:read.

package/lib/commands/admin.mjs

@@ -6981,13 +6981,75 @@ export async function cmdAdmin(ctx) {
 	if (sub === "recipes") return cmdAdminRecipes({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "letterpress") return cmdAdminLetterpress({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "demo") return cmdAdminDemo({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "targets") return cmdAdminTargets({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "deployments" || sub === "deploys")
 		return cmdAdminDeployments({ ...ctx, positionals: ctx.positionals.slice(1) });
 	throw new CliError(
-		'Usage: admin recipes … | admin letterpress … | admin demo … | admin deployments … | admin republish … | admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin patterns … | admin experiments … | admin fleet-experiments … | admin crm … | admin spend … | admin evals … | admin brand-detection … | admin tuning … | admin tuning-context | admin replays … (see --help)'
+		'Usage: admin recipes … | admin letterpress … | admin demo … | admin targets … | admin deployments … | admin republish … | admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin patterns … | admin experiments … | admin fleet-experiments … | admin crm … | admin spend … | admin evals … | admin brand-detection … | admin tuning … | admin tuning-context | admin replays … (see --help)'
 	);
 }
 
+const TARGETS_USAGE = `Usage: admin targets <check|add-candidates>
+  admin targets check [--org <id>,…] [--recheck] [--limit 10]
+  admin targets add-candidates <org-id> [--limit 5] [--apply]`;
+
+// `admin targets` — ranking-target accuracy (docs/architecture/ranking-target-accuracy.md): the phrase
+// check over targets already there (score_ranking_targets), and an account's keep-verdict question
+// candidates added as targets (add_question_candidates, a dry run unless --apply). Needs fleet:instrument.
+async function cmdAdminTargets(ctx) {
+	const { flags, positionals, io } = ctx;
+	switch (positionals[0]) {
+		case "check": {
+			const orgs = (flagStr(flags.org) ?? "")
+				.split(",")
+				.map((s) => s.trim())
+				.filter(Boolean);
+			const limit = flagNum(flags.limit);
+			const result = await staffPost(ctx, "/api/superadmin/ranking-targets/check", {
+				...(orgs.length ? { org_ids: orgs } : {}),
+				...(flagBool(flags.recheck) ? { recheck: true } : {}),
+				...(limit !== undefined ? { limit } : {}),
+			});
+			printResult(io, flags, result, (r) =>
+				[
+					...r.outcomes.map(
+						(o) =>
+							`${o.status.padEnd(16)} ${o.org_id}  keep ${o.counts.keep} · weak ${o.counts.weak} · reject ${o.counts.reject}${
+								o.counts.unchecked ? ` · unchecked ${o.counts.unchecked}` : ""
+							}${o.reason ? `  ${o.reason}` : ""}`
+					),
+					`${r.picked} account(s) taken (${r.mode})${r.left ? `, ${r.left} more past the limit` : ""}.`,
+				].join("\n")
+			);
+			return result.outcomes?.some((o) => o.status === "failed") ? 1 : 0;
+		}
+		case "add-candidates": {
+			const orgId = requirePositional(positionals, 1, "org-id");
+			const limit = flagNum(flags.limit);
+			const result = await staffPost(ctx, "/api/superadmin/ranking-targets/candidates", {
+				org_id: orgId,
+				dry_run: !flagBool(flags.apply),
+				...(limit !== undefined ? { limit } : {}),
+			});
+			printResult(io, flags, result, (r) =>
+				[
+					`${r.dry_run ? "Would add" : "Added"} ${r.added.length} (room under the cap: ${r.room}):`,
+					...r.added.map(
+						(a) => `  ${a.phrase}  [${a.source}]${a.target_id ? `  ${a.target_id} ${a.status}` : ""}`
+					),
+					...r.skipped.map((k) => `  skipped ${k.phrase}: ${k.reason}`),
+					r.dry_run ? "Nothing added. Run again with --apply to add them." : "",
+				]
+					.filter(Boolean)
+					.join("\n")
+			);
+			return 0;
+		}
+		default:
+			throw new CliError(TARGETS_USAGE);
+	}
+}
+
 const MANAGED_HEALTH = ["down", "failing", "blocked", "setting_up", "live", "paused", "archived"];
 
 // `admin deployments` — every site Letter built and hosts, across every organization

package/lib/commands/targets.mjs

@@ -98,6 +98,7 @@ export const ARGS = {
 		},
 	},
 	suggest_ranking_targets: { offering_id: offering },
+	list_question_candidates: { limit: { flag: "limit", type: "num" } },
 	list_ranking_subqueries: {
 		target_id: { positional: 0, label: "target-id" },
 		include_retired: { flag: "retired", type: "bool" },
@@ -126,7 +127,7 @@ export const ARGS = {
 	},
 };
 
-const USAGE = `Usage: targets <list|add|update|activate|deactivate|cap|suggest|subqueries|subquery>
+const USAGE = `Usage: targets <list|add|update|activate|deactivate|cap|suggest|candidates|subqueries|subquery>
   targets list [--offering <offering-id|company>]
   targets add <phrase> [--framing <f>] [--offering <offering-id|company>] [--priority high|normal|low]
                  [--stance <s>]...                       points of view held on this target's ground only
@@ -137,6 +138,7 @@ const USAGE = `Usage: targets <list|add|update|activate|deactivate|cap|suggest|s
   targets deactivate <target-id>
   targets cap <offering-id|company> <n|default>
   targets suggest [--offering <offering-id|company>]
+  targets candidates [--limit <n>]                        new questions the market asks, checked and deduped
   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]
@@ -161,6 +163,8 @@ export async function cmdTargets(ctx) {
 			return targetsCap(rest);
 		case "suggest":
 			return targetsSuggest(rest);
+		case "candidates":
+			return targetsCandidates(rest);
 		case "subqueries":
 			return subqueriesList(rest);
 		case "subquery":
@@ -179,11 +183,24 @@ function formatScope(s) {
 	return `${scopeName(s)} — ${s.active}/${s.cap} active (${where})`;
 }
 
+// The phrase check's verdict and its first reason, then whether an automation may act on it and
+// whether it is losing (docs/architecture/ranking-target-accuracy.md).
+function formatAccuracy(t) {
+	const lines = [];
+	const check = t.phrase_check;
+	if (check) lines.push(`check: ${check.verdict}${check.reasons?.[0] ? ` — ${check.reasons[0]}` : ""}`);
+	else if (t.phrase_check === null) lines.push("check: not checked yet");
+	if (typeof t.actionable === "boolean")
+		lines.push(`${t.actionable ? "actionable" : "not actionable"}: ${t.actionable_reason}`);
+	if (t.losing === true) lines.push(t.losing_reason);
+	return lines.map((l) => `\n      ${l}`).join("");
+}
+
 function formatTarget(t) {
 	const framing = t.mention_framing ? ` — as ${t.mention_framing}` : "";
 	const prio = t.priority ? `  (${t.priority} priority)` : "";
 	const stances = (t.stances ?? []).map((s) => `\n      · ${s}`).join("");
-	return `  ${t.id}  [${t.status}]  ${t.phrase}${framing}${prio}${stances}`;
+	return `  ${t.id}  [${t.status}]  ${t.phrase}${framing}${prio}${stances}${formatAccuracy(t)}`;
 }
 
 // Targets grouped under their scope, each headed by its cap and usage. A target on an
@@ -323,6 +340,38 @@ async function targetsSuggest(ctx) {
 	return 0;
 }
 
+export function formatCandidates(r) {
+	const all = r.candidates ?? [];
+	if (!all.length) return "No new questions found yet.";
+	const lines = all.map((c) => {
+		const verdict = c.check ? c.check.verdict : "unchecked";
+		const why = c.check?.reasons?.[0] ? `\n    ${c.check.reasons[0]}` : "";
+		const evidence = (c.evidence ?? []).map((e) => `\n    · ${e.source}: ${e.detail}`).join("");
+		return `  [${verdict}] ${c.phrase}${why}${evidence}`;
+	});
+	const f = r.found ?? {};
+	lines.push(
+		`Found: ${f.search_console ?? 0} in Search Console, ${f.answer_gap ?? 0} answer gaps, ${f.rival_pages ?? 0} rival pages, ${f.answer_fit ?? 0} answer criteria; ${r.duplicates ?? 0} already tracked.`
+	);
+	return lines.join("\n");
+}
+
+async function targetsCandidates(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.list_question_candidates);
+	const result = await client.callTool(
+		"list_question_candidates",
+		argsFromFlags(ARGS.list_question_candidates, flags)
+	);
+	printResult(
+		io,
+		flags,
+		result,
+		(r) => `${formatCandidates(r)}\nNothing saved. Track one with: ${ctx.bin} targets add <phrase>`
+	);
+	return 0;
+}
+
 function formatSubquery(q) {
 	const who = q.source === "user" ? "  (yours)" : "";
 	const retired = q.status === "retired" ? `  [retired by ${q.retired_by ?? "?"}: ${q.retired_reason ?? ""}]` : "";

package/package.json

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