@letterstory/cli 0.87.1 → 0.89.0

package/lib/cli.mjs

@@ -57,7 +57,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.87.1";
+export const VERSION = "0.89.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
@@ -639,6 +639,12 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        read-only SQL across every org; --sql prints
                                                        the queries behind the answer. Needs the
                                                        fleet:query capability on the staff key.
+  admin brand-detection <org-id> [--term <t>]... [--exact <t>]... [--exclude <phrase>]... [--note "…"] | --clear [--note "…"]
+                                                       How a client's brand is detected in AI answers, with
+                                                       every earlier setting; with flags, set the exact set
+                                                       (fleet:instrument) — e.g. --term Context.dev for a name
+                                                       that is also a word. --clear goes back to inferred,
+                                                       recorded as your decision.
   admin replays [--org <uuid>] [--target <uuid>] [--status captured|not_reproduced|queued|running|unsupported|failed] [--limit <n>]
                                                        Live answer replays: breakthroughs re-asked in ChatGPT /
                                                        Gemini / Google / Perplexity / Claude, with screenshots.
@@ -1037,6 +1043,7 @@ Insights:
   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 detection                                   How your brand is detected in AI answers (terms, who set them)
   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

@@ -15,6 +15,8 @@
 //   admin fleet-experiments list|articles|clients|mark|unmark|new|assign|assign-eligible|assign-orgs|spin-up|apply|start|stop|decide …  (fleet:read / fleet:experiment)
 //   admin crm import|capture|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|record-churn|undo-churn|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
 //   admin spend summary|reconcile|pnl|entries|add|import|usage|remove|reference|stripe-sync|services|service …  (spend:read / spend:write)
+//   admin brand-detection <org-id>                                                   (fleet:read)
+//   admin brand-detection <org-id> [--term t]... [--exact t]... [--exclude p]... [--note "…"] | --clear [--note "…"]   (fleet:instrument)
 //   admin replays [--org <id>] [--target <id>] [--status …] [--limit n]                (fleet:read)
 //   admin replay --org <id> [<response-id> | --target <id>] [--surface …]           (fleet:replay)
 //   admin create-org --domain acme.com [--name "Acme"] [--test] [--no-key] [--key-name N]
@@ -41,7 +43,7 @@
 
 import { readFileSync } from "node:fs";
 import { CliError, LetterstoryClient } from "../client.mjs";
-import { flagStr, flagNum, flagBool, flagList, printResult, compact, ok } from "./shared.mjs";
+import { flagStr, flagNum, flagBool, flagList, printResult, compact, ok, requirePositional } from "./shared.mjs";
 import { watchDomainJob } from "./onboard.mjs";
 
 const SEER_MODES = ["suggest", "skip"];
@@ -453,12 +455,12 @@ async function cmdAdminTuningContext(ctx) {
  *   admin tuning loop                                          where the loop stands: what waits at each station, and where to go next
  *   admin tuning ledger <comparison-id>                        the defect ledger: per arm, what the diagnosis read named, the floor and the ceiling, the candidate's next arm; then the reader edits per arm by lever, and the schema gaps
  *   admin tuning checklist                                     the checklist: every defect category with its status, the picks' agreement (n, agreement, suggestion) and its labels (+/−)   (alias: evals)
- *   admin tuning checklist-add --id … --label … --how … --layer … --lever … --locality local|structural --axis … [--example "span"]   add a category (starts unvetted)   (alias: eval-add)
- *   admin tuning checklist-set <id> [--status confirmed|rejected|unvetted] [--example "span" [--fix "…"]]   confirm / reject (a person's call), or add an example   (alias: eval-set)
+ *   admin tuning checklist-add --id … --label … --looks-like "…" --how "…" --layer … --lever … [--paths voice,…] --locality local|structural --axis … [--example "span"]   add a category (starts unvetted; an id already on the list is refused); --looks-like is the defect as the judge reads it, --how the fix, --paths what a bake-off merge copies   (alias: eval-add)
+ *   admin tuning checklist-set <id> [--status confirmed|rejected|unvetted] [--example "span" [--fix "…"]]   confirm / reject (a person's call, recorded as the key's owner), or add an example   (alias: eval-set)
  *   admin tuning checklist-labels <id>                         the labelled set of one category: positives (examples + feedback filed into it), negatives (rejected feedback suggested for it), grid overrules
  *   admin tuning feedback [--status proposed|captured|rejected]   the feedback: spans readers marked in a pair's text with their words, each with its disposition   (alias: proposals)
  *   admin tuning feedback-add --span "…" --comment "…" [--fix "…"] [--comparison <id> --cell <key> --side control|candidate] [--kind narrow|wide]   add feedback (no --side from a blind read); --fix is the reader's rewrite, classified and a disposition suggested   (alias: propose-eval)
- *   admin tuning feedback-file <id> --as checklist --id … --label … --how … --layer … --lever … --locality local|structural --axis …   file it on the checklist, the span (and its fix) as the category's example (appends when the id exists)   (alias: capture-eval; --as category)
+ *   admin tuning feedback-file <id> --as checklist --id … --label … --looks-like "…" --how "…" --layer … --lever … [--paths …] --locality local|structural --axis …   file it on the checklist, the span (and its fix) as the category's example (appends when the id exists)   (alias: capture-eval; --as category)
  *   admin tuning feedback-file <id> --as rule                   file it as a rule; the rule itself is written in the kernels rule lab
  *   admin tuning feedback-file <id> --as config [--note "…"]    file it as a lever this candidate should pull
  *   admin tuning feedback-file <id> --as implementation [--note "…"]   file it as a schema gap no setting can express, for the kernels repo (--as lever still works)
@@ -516,7 +518,9 @@ async function cmdAdminTuningContext(ctx) {
  *
  * The bake-off: a screen's versions graded item by item against the checklist's confirmed and
  * unvetted categories and the craft axes commitment / economy / movement, the winner
- * per item tallied across the inputs, and a merge that composes the best of each into one candidate.
+ * per item tallied across the inputs, and a merge that composes the best of each into one candidate:
+ * each kernel-file path takes the value the most trusted wins stand behind (a person-confirmed
+ * category or an axis); versions on another writer take no part.
  * Deterministic; a person overrides a grade and confirms the merge, which is a hypothesis until the
  * eye test confirms it.
  *   admin tuning bakeoff <screen-id> [--regrade]                 the winners table: item, trusted, leader, wins per version, graded; then the conflicts a merge would meet
@@ -614,7 +618,7 @@ function printProgramme(io, r) {
 		for (const row of sm.table ?? [])
 			if (row.leader !== null && row.leader !== sm.base)
 				io.log(
-					`    ${row.item.id.padEnd(32)} ${row.trusted ? "trusted  " : "unvetted "} v${row.leader}  ${Object.entries(
+					`    ${row.item.id.padEnd(32)} ${row.trusted ? "trusted  " : row.item.status === "confirmed" ? "undecided" : "unvetted "} v${row.leader}  ${Object.entries(
 						row.wins
 					)
 						.map(([v, n]) => `v${v}:${n}`)
@@ -806,6 +810,7 @@ async function cmdAdminTuning(ctx) {
 			if (json) return printResult(io, flags, r);
 			const rows = r.categories ?? [];
 			if (!rows.length) return io.log("(no categories)");
+			io.log('("confirmed?" = confirmed by nobody on record, a seeded status: graded, never merged)');
 			const cell = (v, w) => String(v ?? "—").padEnd(w);
 			io.log(
 				`${cell("id", 24)} ${cell("status", 10)} ${cell("layer", 10)} ${cell("lever", 30)} ${"n".padStart(4)} ${"agree".padStart(6)} ${cell("suggest", 10)} ${"+".padStart(3)} ${"−".padStart(3)}`
@@ -813,8 +818,10 @@ async function cmdAdminTuning(ctx) {
 			for (const c of rows) {
 				const v = c.vetting ?? {};
 				const l = c.labels ?? { positives: (c.examples ?? []).length, negatives: 0 };
+				// A confirmed status nobody is on record as deciding is a seeded one: the bake-off does not merge on it.
+				const status = c.status === "confirmed" && !c.decided_by ? "confirmed?" : c.status;
 				io.log(
-					`${cell(c.id, 24)} ${cell(c.status, 10)} ${cell(c.layer, 10)} ${cell(c.lever || "—", 30)} ${String(v.n ?? 0).padStart(4)} ${String(v.agreement ?? "—").padStart(6)} ${cell(v.suggestion, 10)} ${String(l.positives).padStart(3)} ${String(l.negatives).padStart(3)}`
+					`${cell(c.id, 24)} ${cell(status, 10)} ${cell(c.layer, 10)} ${cell(c.lever || "—", 30)} ${String(v.n ?? 0).padStart(4)} ${String(v.agreement ?? "—").padStart(6)} ${cell(v.suggestion, 10)} ${String(l.positives).padStart(3)} ${String(l.negatives).padStart(3)}${(c.paths ?? []).length ? "" : "  (no path)"}`
 				);
 			}
 			return;
@@ -832,30 +839,17 @@ async function cmdAdminTuning(ctx) {
 		}
 		case "checklist-add":
 		case "eval-add": {
-			const body = {
-				id: flagStr(flags.id),
-				label: flagStr(flags.label),
-				how: flagStr(flags.how),
-				layer: flagStr(flags.layer),
-				lever: flagStr(flags.lever) ?? "",
-				locality: flagStr(flags.locality),
-				axis: flagStr(flags.axis),
-			};
+			const body = checklistWords(flags);
 			const example = flagStr(flags.example);
-			if (
-				!body.id ||
-				!body.label ||
-				!body.how ||
-				!body.layer ||
-				!body.axis ||
-				!["local", "structural"].includes(body.locality ?? "")
-			)
-				throw new CliError(
-					'Usage: admin tuning checklist-add --id … --label … --how … --layer … --lever … --locality local|structural --axis … [--example "span"]'
-				);
+			if (!body)
+				throw new CliError(`Usage: admin tuning checklist-add ${CHECKLIST_WORDS_USAGE} [--example "span"]`);
 			if (example) body.examples = [{ span: example, ...(flags.fix ? { fix: flagStr(flags.fix) } : {}) }];
 			const r = await staffRequest(ctx, "POST", `${T}/evals`, body);
-			return json ? printResult(io, flags, r) : io.log(`added ${r.category.id} (${r.category.status})`);
+			if (json) return printResult(io, flags, r);
+			io.log(`added ${r.category.id} (${r.category.status})`);
+			if (!(r.category.paths ?? []).length)
+				io.log("  no --paths: a bake-off grades this item but can never merge on it");
+			return;
 		}
 		case "checklist-set":
 		case "eval-set": {
@@ -877,7 +871,9 @@ async function cmdAdminTuning(ctx) {
 			const r = await staffRequest(ctx, "PATCH", `${T}/evals/${encodeURIComponent(id)}`, patch);
 			return json
 				? printResult(io, flags, r)
-				: io.log(`${r.category.id}: ${r.category.status}, ${(r.category.examples ?? []).length} examples`);
+				: io.log(
+						`${r.category.id}: ${r.category.status}${r.category.decided_by ? ` (by ${r.category.decided_by})` : ""}, ${(r.category.examples ?? []).length} examples`
+					);
 		}
 		case "feedback":
 		case "proposals": {
@@ -946,32 +942,15 @@ async function cmdAdminTuning(ctx) {
 			const AS_ALIAS = { category: "checklist", lever: "implementation" };
 			const asGiven = flagStr(flags.as);
 			const as = AS_ALIAS[asGiven] ?? asGiven;
-			const usage =
-				'Usage: admin tuning feedback-file <id> --as checklist --id … --label … --how … --layer … --lever … --locality local|structural --axis … | --as rule | --as config|implementation|material [--note "…"] | --as note';
+			const usage = `Usage: admin tuning feedback-file <id> --as checklist ${CHECKLIST_WORDS_USAGE} | --as rule | --as config|implementation|material [--note "…"] | --as note`;
 			if (!id || !["checklist", "rule", "config", "implementation", "material", "note"].includes(as ?? ""))
 				throw new CliError(usage);
 			let body = { as };
 			if (as === "config" || as === "implementation" || as === "material")
 				body = compact({ as, note: flagStr(flags.note) });
 			if (as === "checklist") {
-				const category = {
-					id: flagStr(flags.id),
-					label: flagStr(flags.label),
-					how: flagStr(flags.how),
-					layer: flagStr(flags.layer),
-					lever: flagStr(flags.lever) ?? "",
-					locality: flagStr(flags.locality),
-					axis: flagStr(flags.axis),
-				};
-				if (
-					!category.id ||
-					!category.label ||
-					!category.how ||
-					!category.layer ||
-					!category.axis ||
-					!["local", "structural"].includes(category.locality ?? "")
-				)
-					throw new CliError(usage);
+				const category = checklistWords(flags);
+				if (!category) throw new CliError(usage);
 				body = { as, category };
 			}
 			const r = await staffRequest(ctx, "POST", `${T}/proposals/${id}/capture`, body);
@@ -1771,7 +1750,11 @@ async function cmdAdminTuning(ctx) {
 				`merged from v${r.base} → candidate v${r.version}${r.comparison_id ? ` · comparison ${r.comparison_id}` : ""}`
 			);
 			for (const p of r.provenance)
-				io.log(`  ${p.applied ? "applied" : `skipped (${p.skipped})`}  ${p.item}  ${p.path}  from v${p.from}`);
+				io.log(
+					`  ${p.applied ? (p.from === r.base ? "kept (the base's, back on top of a wider copy)" : "applied") : `skipped (${p.skipped})`}  ${p.item}  ${p.path}  from v${p.from}`
+				);
+			for (const e of r.excluded ?? [])
+				io.log(`  left out  v${e.version}: runs on ${e.writer}, not the base's writer`);
 			if (r.conflicts.length)
 				io.log(
 					`conflicts left (the base's value kept): ${r.conflicts.map((c) => `${c.path} ← ${c.candidates.map((x) => `${x.item} v${x.version}`).join(" | ")}`).join("; ")}`
@@ -3347,6 +3330,43 @@ async function cmdAdminSpend(ctx) {
 	}
 }
 
+/**
+ * A checklist item's words from the flags (checklist-add, feedback-file --as checklist): the
+ * service's add schema — `--looks-like` is the defect as the judge reads it, `--how` the fix,
+ * `--paths` the lever as kernel-file paths (comma-separated) so a bake-off can merge on it.
+ * Null when a required word is missing.
+ */
+function checklistWords(flags) {
+	const paths = (flagStr(flags.paths) ?? "")
+		.split(",")
+		.map((p) => p.trim())
+		.filter(Boolean);
+	const words = {
+		id: flagStr(flags.id),
+		label: flagStr(flags.label),
+		looks_like: flagStr(flags["looks-like"]),
+		how: flagStr(flags.how),
+		layer: flagStr(flags.layer),
+		lever: flagStr(flags.lever),
+		locality: flagStr(flags.locality),
+		axis: flagStr(flags.axis),
+		...(paths.length ? { paths } : {}),
+	};
+	const complete =
+		words.id &&
+		words.label &&
+		words.looks_like &&
+		words.how &&
+		words.layer &&
+		words.lever &&
+		words.axis &&
+		["local", "structural"].includes(words.locality ?? "");
+	return complete ? words : null;
+}
+
+const CHECKLIST_WORDS_USAGE =
+	'--id … --label … --looks-like "what the defect looks like" --how "the fix" --layer writer|frame|voice|economy|tells|length|material --lever … [--paths \'voice,rules["<id>"]\'] --locality local|structural --axis specificity|commitment|economy|movement|none';
+
 const FLEET_EXPERIMENTS = "/api/superadmin/experiments";
 
 function pct(rate) {
@@ -3562,7 +3582,65 @@ export async function cmdAdmin(ctx) {
 	if (sub === "tuning-import") return cmdAdminTuningImport({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "tuning") return cmdAdminTuning({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "evals") return cmdAdminEvals({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "brand-detection") return cmdAdminBrandDetection({ ...ctx, positionals: ctx.positionals.slice(1) });
 	throw new CliError(
-		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin fleet-experiments … | admin crm … | admin spend … | admin evals … | admin tuning … | admin tuning-context | admin replays … (see --help)'
+		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin fleet-experiments … | admin crm … | admin spend … | admin evals … | admin brand-detection … | admin tuning … | admin tuning-context | admin replays … (see --help)'
 	);
 }
+
+// `admin brand-detection <org-id>` — how the client's brand is detected in AI answers;
+// with --term / --exact / --exclude it SETS the exact set (replacing the inferred one),
+// --clear goes back to inferred (recorded as a decision, with --note as the why). Every
+// earlier setting is kept in `history`. The client's answers are recounted against the new set.
+async function cmdAdminBrandDetection(ctx) {
+	const { flags, positionals, io } = ctx;
+	const orgId = requirePositional(positionals, 0, "org-id");
+	const path = `/api/superadmin/fleet/mentions/${encodeURIComponent(orgId)}/detection`;
+	const terms = flagList(flags.term);
+	const exact = flagList(flags.exact);
+	const exclude = flagList(flags.exclude);
+	let result;
+	if (flags.clear === true)
+		result = await staffRequest(ctx, "PUT", path, {
+			clear: true,
+			...(flagStr(flags.note) !== undefined ? { note: flagStr(flags.note) } : {}),
+		});
+	else if (terms.length || exact.length || exclude.length || flagStr(flags.note) !== undefined) {
+		if (!terms.length && !exact.length) throw new CliError("Give at least one --term or --exact (or --clear).");
+		result = await staffRequest(ctx, "PUT", path, {
+			terms,
+			exact_case_terms: exact,
+			exclude_phrases: exclude,
+			...(flagStr(flags.note) !== undefined ? { note: flagStr(flags.note) } : {}),
+		});
+	} else result = await staffRequest(ctx, "GET", path);
+	printResult(io, flags, result, (r) => {
+		const e = r.effective;
+		const state = r.override
+			? `exact set, by ${r.override.setBy ?? "?"} at ${r.override.setAt ?? "?"}`
+			: r.cleared
+				? `inferred (exact set cleared by ${r.cleared.by ?? "?"} at ${r.cleared.at ?? "?"})`
+				: "inferred";
+		const lines = [
+			`${r.orgName}: ${state}`,
+			`  terms (any case): ${e.terms.join(", ") || "—"}`,
+			`  exact case:       ${e.exactCaseTerms.join(", ") || "—"}`,
+			`  excluded phrases: ${e.excludePhrases.join(", ") || "—"}`,
+		];
+		const why = r.override?.note ?? r.cleared?.note;
+		if (why) lines.push(`  why: ${why}`);
+		if (r.override) lines.push(`  inferred would be: ${r.inferred.terms.join(", ")}`);
+		for (const h of r.history ?? []) {
+			const set = [
+				h.terms.length ? `terms ${h.terms.join(", ")}` : "",
+				h.exactCaseTerms.length ? `exact ${h.exactCaseTerms.join(", ")}` : "",
+				h.excludePhrases.length ? `excludes ${h.excludePhrases.join(", ")}` : "",
+			].filter(Boolean);
+			lines.push(
+				`  earlier: ${h.action} by ${h.by ?? "?"} at ${h.at ?? "?"}${set.length ? ` — ${set.join("; ")}` : ""}${h.note ? ` (${h.note})` : ""}`
+			);
+		}
+		return lines.join("\n");
+	});
+	return 0;
+}

package/lib/commands/insights.mjs

@@ -27,6 +27,7 @@ export const ARGS = {
 	get_share_of_voice_detail: {
 		period: { flag: "period", enum: PERIODS },
 	},
+	get_brand_detection: {},
 	get_share_of_voice_question: {
 		question_key: { positional: 0, label: "question-key", required: true },
 		period: { flag: "period", enum: PERIODS },
@@ -55,9 +56,11 @@ export async function cmdInsights(ctx) {
 			return call(rest, "get_share_of_voice_detail");
 		case "question":
 			return call(rest, "get_share_of_voice_question");
+		case "detection":
+			return call(rest, "get_brand_detection");
 		default:
 			throw new CliError(
-				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, competitors, question, site, post, top, bank, access`
+				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, competitors, question, detection, site, post, top, bank, access`
 			);
 	}
 }

package/package.json

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