@letterstory/cli 0.87.1 → 0.90.0

package/README.md

@@ -346,6 +346,21 @@ letterstory admin ask "which clients published nothing in the last 30 days?" --s
 This is the headless half of `/superadmin/ask` — same function, same schema — so a
 long-running agent can watch the fleet on a schedule without a browser.
 
+### Staff: client patterns and Fable
+
+```bash
+# What separates clients whose AI visibility moves (docs/architecture/client-patterns.md):
+# every client against itself on share of voice, mention rate and page access, with what we
+# did for it. Needs fleet:read; `run` and `ask` spend Fable tokens and need fleet:query.
+letterstory admin patterns --period 30d
+letterstory admin patterns reports            # Fable's weekly reports and runs, newest first
+letterstory admin patterns report <id>        # one report's markdown
+letterstory admin patterns run                # a report now (takes minutes)
+letterstory admin patterns ask "do answer-gap posts help paying clients too?"
+```
+
+The headless half of Admin → Client performance → Patterns: same functions, same schemas.
+
 ### Staff: kernel experiments
 
 ```bash

package/lib/cli.mjs

@@ -57,13 +57,15 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.87.1";
+export const VERSION = "0.90.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
 // `negate` spelling) in a command's ARGS map must be listed; boolean-flags.test.ts enforces it.
 export const BOOLEAN_FLAGS = new Set([
 	"json",
+	// lede library update / lede proposals accept: clear or drop the line's condition.
+	"no-condition",
 	"yes",
 	"confirm-missing-target",
 	"no-wait",
@@ -639,6 +641,20 @@ 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 patterns [--period 14d|30d] [--segment "<segment>"] [--json]
+                                                       Client patterns: every client's share of voice,
+                                                       mention rate and page access against itself, with
+                                                       what we did for it. Needs fleet:read.
+  admin patterns reports [--kind reports|weekly|run|ask] | report <id>
+                                                       Fable's weekly reports, runs and Ask Fable answers.
+  admin patterns run | ask "<question>"                Run a Fable report now, or ask Fable a question
+                                                       about client patterns (minutes). Needs fleet:query.
   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.
@@ -926,7 +942,7 @@ Ledes (opening lines for cold email, chosen per prospect from a hand-approved li
   lede balance                                         Ledes left on this org
   lede library list                                    The org's opener library: pre-built + custom lines
   lede library create --text <line> [--alts <v>]... [--peer-alts <v>]... [--requires <trigger>]...
-           [--threshold <0..100>] [--tone warm|direct|playful|formal] [--tag <t>]...
+           [--threshold <0..100>] [--tone warm|direct|playful|formal] [--tag <t>]... [--condition <use when...>]
                                                        Add a custom line. A {{placeholder}} must appear in
                                                        --requires; proprietary-engine triggers stay
                                                        reserved for the pre-built lines. --threshold
@@ -935,6 +951,7 @@ Ledes (opening lines for cold email, chosen per prospect from a hand-approved li
                                                        lower = looser.
   lede library update <lede-id> [--text <line>] [--alts <v>]... [--peer-alts <v>]...
            [--requires <trigger>]... [--threshold <0..100>] [--tone <t>] [--tag <t>]...
+           [--condition <use when...> | --no-condition]
                                                        Edit a line; only the flags you pass change
   lede library enable <lede-id>                        Make a line a run candidate again
   lede library disable <lede-id>                       Keep a line out of runs (reversible; the way to
@@ -945,6 +962,13 @@ Ledes (opening lines for cold email, chosen per prospect from a hand-approved li
                                                        Propose brand-voice rewrites of the wording only.
                                                        Applies nothing: accept a proposal with
                                                        lede library update --text/--alts
+  lede proposals [list] [--status proposed|captured|active|rejected] [--limit <n>]
+                                                       Lines reviewers wrote while personalizing in
+                                                       Dispatch, templated and judged, each with a
+                                                       drafted "Use when ..." condition
+  lede proposals accept <proposal-id> [--text <line>] [--condition <c> | --no-condition] [--tone <t>]
+                                                       Add it to the library (live immediately)
+  lede proposals reject <proposal-id> --reason <why>   Keep it out; the reason stops it recurring
 
 Landings (a link + context; auto-mentioned in articles by collections you enable):
   landings list                                        Your landing pages + mention counts
@@ -976,6 +1000,7 @@ Sequences (multi-step cold email sent from your mailers; approving or enrolling
   sequences stop <sequence-id> <enrollment-id>         Stop one recipient
   sequences review list                                Emails waiting for a decision
   sequences review edit <item-id> [--subject <s>] [--body <text>|--file <path>]
+        [--personalize <line> [--personalize-mode replace|insert]]   Mark the edit a personalization (proposed to the opener library)
   sequences review approve|skip|delete <item-id>       Decide one (approve sends now)
   sequences links list                                 Live Pocket Dispatch links (no tokens)
   sequences links create --days <1..3>                 Mint a no-login review link (shown once)
@@ -1037,6 +1062,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

@@ -4,6 +4,7 @@
 // routes, because they exist precisely to act BEFORE an org exists.
 //
 //   admin ask "which kernels are hooked up to the most clients?" [--sql] [--json]
+//   admin patterns [--period 14d|30d] [--segment "…"] | reports [--kind reports|weekly|run|ask] | report <id> | run | ask "<question>"   (fleet:read / fleet:query)
 //   admin experiments list|show|new|update|note|started|spend|conclude|abandon …   (tuning:experiment)
 //   admin tuning-context [--q "<question>"]                                         (tuning:experiment)
 //   admin tuning-import <brief-results.json> [--experiment <id>]                    (tuning:experiment)
@@ -15,6 +16,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 +44,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"];
@@ -239,6 +242,80 @@ async function cmdAdminAsk(ctx) {
 	}
 }
 
+/* ------------------------------------------------------------ client patterns */
+
+const PATTERNS = "/api/superadmin/client-patterns";
+
+/**
+ * `admin patterns …` — the Patterns tab without a browser (docs/architecture/client-patterns.md):
+ * the data, Fable's report history, a report on demand, and Ask Fable. `run` and `ask` wait for
+ * the finished answer (minutes, not seconds) and print its markdown.
+ */
+async function cmdAdminPatterns(ctx) {
+	const [sub = "show", ...rest] = ctx.positionals;
+	const json = flagBool(ctx.flags.json);
+	switch (sub) {
+		case "show": {
+			const { payload } = await staffRequest(ctx, "GET", PATTERNS);
+			if (!payload) throw new CliError("The patterns snapshot has not been computed yet.");
+			const period = flagStr(ctx.flags.period) ?? "30d";
+			const segment = flagStr(ctx.flags.segment);
+			const clients = payload.clients.filter((c) => !segment || c.segment === segment);
+			if (json) return printResult(ctx.io, ctx.flags, { ...payload, clients });
+			const pts = (v) => (v == null ? "—" : `${v >= 0 ? "+" : "−"}${Math.abs(v * 100).toFixed(1)} pts`);
+			ctx.io.log(`${clients.length} clients, ${payload.postCount} posts · computed ${payload.generated}`);
+			for (const c of clients) {
+				const s = c.sov?.[period];
+				const n = c.named?.[period];
+				ctx.io.log(
+					`${c.name.padEnd(28)} ${c.segment.padEnd(30)} sov ${pts(s?.change)}  mention ${pts(n?.change)}  posts30 ${c.posts30}`
+				);
+			}
+			return;
+		}
+		case "reports": {
+			const kind = flagStr(ctx.flags.kind) ?? "reports";
+			const limit = flagStr(ctx.flags.limit) ?? "12";
+			const { reports } = await staffRequest(
+				ctx,
+				"GET",
+				`${PATTERNS}/reports?kind=${encodeURIComponent(kind)}&limit=${encodeURIComponent(limit)}`
+			);
+			if (json) return printResult(ctx.io, ctx.flags, { reports });
+			for (const r of reports)
+				ctx.io.log(
+					`${r.id}  ${r.created_at}  ${r.kind.padEnd(6)} ${r.status.padEnd(7)} ${(r.question ?? (r.summary ?? "").split("\n")[0] ?? "").slice(0, 80)}`
+				);
+			return;
+		}
+		case "report": {
+			const id = rest[0];
+			if (!id) throw new CliError("Usage: admin patterns report <id>");
+			const { report } = await staffRequest(ctx, "GET", `${PATTERNS}/reports/${encodeURIComponent(id)}`);
+			if (json) return printResult(ctx.io, ctx.flags, { report });
+			ctx.io.log(report.report ?? report.error ?? "(no report)");
+			return;
+		}
+		case "run": {
+			const { report } = await staffPost(ctx, `${PATTERNS}/reports`, {});
+			if (json) return printResult(ctx.io, ctx.flags, { report });
+			ctx.io.log(report.report ?? report.error ?? "(no report)");
+			return;
+		}
+		case "ask": {
+			const question = rest.join(" ").trim();
+			if (question.length < 3)
+				throw new CliError('Usage: admin patterns ask "do answer-gap posts help paying clients too?"');
+			const { answer } = await staffPost(ctx, `${PATTERNS}/ask`, { question });
+			if (json) return printResult(ctx.io, ctx.flags, { answer });
+			ctx.io.log(answer.report ?? answer.error ?? "(no answer)");
+			return;
+		}
+		default:
+			throw new CliError('Usage: admin patterns [show] | reports | report <id> | run | ask "<question>"');
+	}
+}
+
 /* ------------------------------------------------------------ kernel experiments */
 
 const EXPERIMENTS = "/api/superadmin/tuning/experiments";
@@ -453,12 +530,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 +593,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 +693,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 +885,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 +893,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 +914,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 +946,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 +1017,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 +1825,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 +3405,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) {
@@ -3556,13 +3651,72 @@ export async function cmdAdmin(ctx) {
 	if (sub === "spend") return cmdAdminSpend({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "create-org") return cmdAdminCreateOrg({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "ask") return cmdAdminAsk({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "patterns") return cmdAdminPatterns({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "experiments") return cmdAdminExperiments({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "fleet-experiments") return cmdAdminFleetExperiments({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "tuning-context") return cmdAdminTuningContext({ ...ctx, positionals: ctx.positionals.slice(1) });
 	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 patterns … | 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/lib/commands/lede.mjs

@@ -130,6 +130,8 @@ export const ARGS = {
 		threshold: { flag: "threshold", type: "num" },
 		tone: { flag: "tone", enum: ["warm", "direct", "playful", "formal"] },
 		tags: { flag: "tag", type: "list" },
+		// "Use when ..." clause, checked per prospect before the line is used.
+		condition: "condition",
 	},
 	update_lede: {
 		id: { positional: 0, label: "lede-id", required: true },
@@ -140,6 +142,8 @@ export const ARGS = {
 		threshold: { flag: "threshold", type: "num" },
 		tone: { flag: "tone", enum: ["warm", "direct", "playful", "formal"] },
 		tags: { flag: "tag", type: "list" },
+		// --condition "<clause>" sets it; --no-condition clears it.
+		condition: { value: (flags) => (flags["no-condition"] ? null : flagStr(flags.condition)) },
 	},
 	set_lede_enabled: {
 		id: { positional: 0, label: "lede-id", required: true },
@@ -153,6 +157,22 @@ export const ARGS = {
 		voice: { flag: "voice", required: true },
 		ids: { flag: "ids", type: "list" },
 	},
+	// Opener proposals (`lede proposals ...`): lines captured from Dispatch personalizations,
+	// evaluated, waiting for an admin to accept into the library or reject with a reason.
+	list_lede_proposals: {
+		status: { flag: "status", enum: ["captured", "proposed", "active", "rejected"] },
+		limit: { flag: "limit", type: "num" },
+	},
+	decide_lede_proposal: {
+		proposal_id: { positional: 0, label: "proposal-id", required: true },
+		// `lede proposals accept|reject <id>` decides this; the subcommand passes it in.
+		action: { value: (_flags, _positionals, extra) => extra.action },
+		text: "text",
+		// --condition "<clause>" edits it on accept; --no-condition accepts with none.
+		condition: { value: (flags) => (flags["no-condition"] ? null : flagStr(flags.condition)) },
+		tone: { flag: "tone", enum: ["warm", "direct", "playful", "formal"] },
+		reason: "reason",
+	},
 };
 
 export async function cmdLede(ctx) {
@@ -173,6 +193,9 @@ export async function cmdLede(ctx) {
 		case "library":
 		case "lib":
 			return ledeLibrary(rest);
+		case "proposals":
+		case "proposal":
+			return ledeProposals(rest);
 		case "run":
 			return ledeRun(rest);
 		case "runs":
@@ -193,7 +216,7 @@ export async function cmdLede(ctx) {
 			return ledeFunnel(rest);
 		default:
 			throw new CliError(
-				`Unknown lede subcommand: ${sub ?? "(none)"}. Try: list, create, delete, endpoint, library, run, runs, history, evals, balance, outcome, funnel`
+				`Unknown lede subcommand: ${sub ?? "(none)"}. Try: list, create, delete, endpoint, library, proposals, run, runs, history, evals, balance, outcome, funnel`
 			);
 	}
 }
@@ -445,3 +468,61 @@ async function ledeBalance(ctx) {
 	printResult(io, flags, result);
 	return 0;
 }
+
+/**
+ * `lede proposals [list] [--status proposed|captured|active|rejected] [--limit n]`,
+ * `lede proposals accept <id> [--text ...] [--condition ...|--no-condition] [--tone ...]`,
+ * `lede proposals reject <id> --reason ...` — lines reviewers wrote while personalizing on
+ * the Dispatch desk, templatized and judged; accept adds one to the library (live now).
+ */
+async function ledeProposals(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const action = positionals[0];
+	const rest = { ...ctx, positionals: positionals.slice(1) };
+	switch (action) {
+		case undefined:
+		case "list":
+		case "ls": {
+			const result = await client.callTool("list_lede_proposals", argsFromFlags(ARGS.list_lede_proposals, flags));
+			// One block per proposal: id, how often captured, the template, then its condition
+			// (or why it was rejected). `--json` for the judge's scores and the raw line.
+			printResult(
+				io,
+				flags,
+				result,
+				(r) =>
+					(r?.proposals ?? [])
+						.map((p) =>
+							[
+								`${p.id}  x${p.capture_count}  [${p.status}]  ${p.templated_text ?? p.raw_line}`,
+								p.status_reason
+									? `    why: ${p.status_reason}`
+									: p.suggested_condition
+										? `    ${p.suggested_condition}`
+										: null,
+							]
+								.filter(Boolean)
+								.join("\n")
+						)
+						.join("\n") || "No proposals."
+			);
+			return 0;
+		}
+		case "accept":
+		case "reject": {
+			const args = argsFromFlags(ARGS.decide_lede_proposal, flags, rest.positionals, { action });
+			if (action === "reject" && !args.reason) throw new CliError("A rejection needs --reason <why>.");
+			const result = await client.callTool("decide_lede_proposal", args);
+			ok(
+				ctx,
+				action === "accept"
+					? `Accepted ${args.proposal_id}: the line is in the library now.`
+					: `Rejected ${args.proposal_id}.`
+			);
+			printResult(io, flags, result);
+			return 0;
+		}
+		default:
+			throw new CliError(`Unknown lede proposals action: ${action}. Try: list, accept, reject`);
+	}
+}

package/lib/commands/outbound.mjs

@@ -197,6 +197,23 @@ export const ARGS = {
 		item_id: { positional: 0, label: "item-id", required: true },
 		subject: "subject",
 		body: { value: (flags) => readTextInput(flags, "body", "file") },
+		// --personalize "<line>" marks the edit as a personalization (captured as an opener
+		// proposal for the org's admins); --personalize-mode says whether the line replaced
+		// the opener (default) or was inserted after the greeting.
+		personalization: {
+			value: (flags) => {
+				const line = flagStr(flags.personalize);
+				const mode = flagStr(flags["personalize-mode"]);
+				if (line === undefined) {
+					if (mode !== undefined) throw new CliError("--personalize-mode needs --personalize <line>");
+					return undefined;
+				}
+				if (mode !== undefined && mode !== "replace" && mode !== "insert") {
+					throw new CliError(`--personalize-mode must be replace or insert (got ${mode})`);
+				}
+				return { line, mode: mode ?? "replace" };
+			},
+		},
 	},
 	decide_review_item: {
 		item_id: { positional: 0, label: "item-id", required: true },
@@ -366,7 +383,7 @@ const VALUE_FLAGS = {
 	create_sequence: ["flow", "flow-file", "mailer", "send-window-start", "send-window-end"],
 	update_sequence: ["flow", "flow-file", "mailer", "send-window-start", "send-window-end"],
 	enroll_in_sequence: ["recipients", "recipients-file", "email"],
-	update_review_item: ["body", "file"],
+	update_review_item: ["body", "file", "personalize", "personalize-mode"],
 	delete_prospects: ["id"],
 	import_prospects_csv: ["csv", "csv-file"],
 	update_prospect: ["custom"],

package/package.json

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