@letterstory/cli 0.49.2 → 0.52.0

package/README.md

@@ -352,6 +352,13 @@ long-running agent can watch the fleet on a schedule without a browser.
 export LETTERSTORY_STAFF_API_KEY=<your staff key with tuning:experiment>
 
 letterstory admin tuning-context --q "colons"          # what the agent knows (JSON)
+letterstory admin tuning kernels                       # every catalog kernel: live version, writer, candidates
+letterstory admin tuning kernel <service-kernel-id> --version live   # one version's kernel file (JSON)
+letterstory admin tuning candidate <service-kernel-id> --file hazel.json --note "Echo as the writer"
+letterstory admin tuning compare --title "Echo vs live" --candidates Hazel:21,Aspen:20
+letterstory admin tuning comparison <id>               # per-measure verdicts (better / worse / within noise / refused)
+letterstory admin tuning picks <id>                    # the blind queue; then: admin tuning pick <id> --cell <key> --pick left|right|tie
+letterstory admin tuning promote <experiment-id> --versions <service-kernel-id>:21   # from a concluded "ship" decision
 letterstory admin experiments list --q colons          # what we've tried
 letterstory admin experiments new "We use too many colons" --as "claude-code"
 letterstory admin experiments update <id> --plan-file plan.json --budget 120
@@ -491,11 +498,25 @@ letterstory arena run-status <run-id>                  # status: awaiting_direct
 letterstory arena direction <run-id> --choice 1
 letterstory arena direction <run-id> --custom "Lead with the hidden costs"
 letterstory arena direction <run-id> --skip            # let the agents decide
+letterstory arena run --topic "payroll solutions" --direction "Lead with the hidden costs"   # no gate, no vote
+
+# Watching runs (what an agent monitoring the account polls):
+letterstory arena runs --status awaiting_direction     # the gates waiting on you
+letterstory arena runs --since 2026-10-02T00:00:00Z --limit 50
+letterstory arena runs --before <next_cursor>          # the next (older) page
+letterstory arena latest --article <uuid>              # the post's latest run, whoever started it
+
+# What research decided each site is — and your call on one (research never overrides it):
+letterstory arena roles --rival                        # competitors research found that you never listed
+letterstory arena role set reviewsite.com --role context
+letterstory arena role set rival.com --role company --company "Rival" --rival
+letterstory arena role reset rival.com                 # hand it back to research
 
 # Arenas are callable endpoints with one-file defaults (the org's default arena is "Letterstory"):
 letterstory arena list
 letterstory arena endpoint create --name "Docs research" --defaults '{"depth":"barebones"}'
 letterstory arena endpoint config <arena-id> [--file cfg.json]
+letterstory arena endpoint update <arena-id> --name "Docs research v2"   # creator or org admin only
 letterstory arena endpoint delete <arena-id> --yes
 
 # Ledes: a prospect's context in, ready-to-send opening lines out (chosen from a

package/lib/cli.mjs

@@ -54,7 +54,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.49.2";
+export const VERSION = "0.52.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.

package/lib/commands/admin.mjs

@@ -7,6 +7,7 @@
 //   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)
+//   admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|promote …   (tuning:experiment)
 //   admin evals scoreboard|cases|runs|run|triage|guard|retire …                      (fleet:read / tuning: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 create-org --domain acme.com [--name "Acme"] [--test] [--no-key] [--key-name N]
@@ -412,6 +413,144 @@ async function cmdAdminTuningContext(ctx) {
 	);
 }
 
+/* ------------------------------------------------------------ the tuning console's Write area */
+
+/**
+ * `admin tuning …` — kernel versions as files, comparisons of a candidate against live, blind picks
+ * and promotion from the ledger (docs/architecture/tuning-foundation.md): the headless half of the
+ * tuning console's Write › Kernels and Compare tabs. Needs `tuning:experiment` on the key.
+ *
+ *   admin tuning kernels                                       every catalog kernel, live version, writer, candidates
+ *   admin tuning kernel <service-kernel-id> [--version N|live]  one version's file (JSON)
+ *   admin tuning candidate <service-kernel-id> --file f.json [--note "…"]   save a file as a candidate version
+ *   admin tuning compare --title "…" --candidates Hazel:21,Aspen:20 [--experiment <id>]   start a comparison
+ *   admin tuning comparisons | comparison <id>                list / read one (per-measure verdicts)
+ *   admin tuning picks <comparison-id>                         the blind queue (next pairs)
+ *   admin tuning pick <comparison-id> --cell <key> --pick left|right|tie   record a blind pick
+ *   admin tuning promote <experiment-id> --versions <service-kernel-id>:<version>,…   promote from a "ship" decision
+ */
+async function cmdAdminTuning(ctx) {
+	const [sub, id] = ctx.positionals;
+	const { flags, io } = ctx;
+	const json = flagBool(flags.json);
+	const T = "/api/superadmin/tuning";
+	switch (sub) {
+		case "kernels": {
+			const r = await staffRequest(ctx, "GET", `${T}/kernel-files`);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				r.kernels
+					.map((k) => {
+						const c = k.versions
+							.filter((v) => v.status === "candidate")
+							.map((v) => `v${v.version} ${v.writer}`);
+						return `${k.kernel.padEnd(12)} live v${k.live}  ${k.writer}  ${k.serviceKernelId}${c.length ? `\n    candidates: ${c.join(", ")}` : ""}`;
+					})
+					.join("\n") || "(no kernels)"
+			);
+		}
+		case "kernel": {
+			if (!id) throw new CliError("Usage: admin tuning kernel <service-kernel-id> [--version N|live]");
+			const version = flagStr(flags.version) ?? "live";
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/kernel-files/${id}/versions/${version}`)
+			);
+		}
+		case "candidate": {
+			const path = flagStr(flags.file);
+			let file;
+			if (path) {
+				try {
+					file = JSON.parse(readFileSync(path, "utf8"));
+				} catch (err) {
+					throw new CliError(`--file ${path}: ${err.message}`);
+				}
+			}
+			if (!id || !file)
+				throw new CliError('Usage: admin tuning candidate <service-kernel-id> --file kernel.json [--note "…"]');
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/kernel-files/${id}/versions`,
+				compact({ file, note: flagStr(flags.note) })
+			);
+			return json ? printResult(io, flags, r) : io.log(`saved candidate v${r.version}`);
+		}
+		case "compare": {
+			const title = flagStr(flags.title);
+			const list = flagList(flags.candidates);
+			if (!title || !list?.length)
+				throw new CliError(
+					'Usage: admin tuning compare --title "…" --candidates Hazel:21,Aspen:20 [--experiment <id>]'
+				);
+			const candidates = list.map((item) => {
+				const at = item.lastIndexOf(":");
+				const version = Number(item.slice(at + 1));
+				if (at < 1 || !Number.isInteger(version))
+					throw new CliError(`--candidates items are kernel:version, got "${item}"`);
+				return { kernel: item.slice(0, at), candidate_version: version };
+			});
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/comparisons`,
+				compact({ title, candidates, experiment_id: flagStr(flags.experiment) })
+			);
+			return json ? printResult(io, flags, r) : io.log(`comparison ${r.comparison?.id ?? r.id ?? ""} started`);
+		}
+		case "comparisons":
+			return printResult(io, { ...flags, json: true }, await staffRequest(ctx, "GET", `${T}/comparisons`));
+		case "comparison":
+			if (!id) throw new CliError("Usage: admin tuning comparison <id>");
+			return printResult(io, { ...flags, json: true }, await staffRequest(ctx, "GET", `${T}/comparisons/${id}`));
+		case "picks":
+			if (!id) throw new CliError("Usage: admin tuning picks <comparison-id>");
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/comparisons/${id}/picks`)
+			);
+		case "pick": {
+			const cell = flagStr(flags.cell);
+			const pick = flagStr(flags.pick);
+			if (!id || !cell || !["left", "right", "tie"].includes(pick ?? ""))
+				throw new CliError("Usage: admin tuning pick <comparison-id> --cell <key> --pick left|right|tie");
+			return printResult(
+				io,
+				flags,
+				await staffRequest(ctx, "POST", `${T}/comparisons/${id}/picks`, { cell_key: cell, outcome: pick })
+			);
+		}
+		case "promote": {
+			const list = flagList(flags.versions);
+			if (!id || !list?.length)
+				throw new CliError(
+					"Usage: admin tuning promote <experiment-id> --versions <service-kernel-id>:<version>,…"
+				);
+			const versions = list.map((item) => {
+				const at = item.lastIndexOf(":");
+				return { service_kernel_id: item.slice(0, at), version: Number(item.slice(at + 1)) };
+			});
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(
+					ctx,
+					"POST",
+					`${EXPERIMENTS}/${id}/promote`,
+					compact({ versions, actor: actorFrom(flags) })
+				)
+			);
+		}
+		default:
+			throw new CliError(
+				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|promote (see --help)"
+			);
+	}
+}
+
 /* ------------------------------------------------------------ the staff CRM */
 
 const CRM = "/api/superadmin/crm";
@@ -1078,8 +1217,9 @@ export async function cmdAdmin(ctx) {
 	if (sub === "experiments") return cmdAdminExperiments({ ...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) });
 	throw new CliError(
-		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin crm … | admin evals … | admin tuning-context (see --help)'
+		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin crm … | admin evals … | admin tuning … | admin tuning-context (see --help)'
 	);
 }

package/lib/commands/arena.mjs

@@ -68,6 +68,8 @@ const RUN_OPTIONS = {
 	// --no-verify turns the fact-check off; nothing sent otherwise (the default is on).
 	verify: { value: (flags) => (flags["no-verify"] === true ? false : undefined) },
 	mention_degree: { flag: "mention", enum: ["off", "subtle", "woven"] },
+	// What the fact-check does with a claim it can neither fix nor stand behind: flag or remove it.
+	unresolved_claims: { flag: "unresolved", enum: ["comment", "drop"] },
 	// Positioning as data — a file, not flags: `--context-file ctx.json` of
 	// {manifesto, stances[], priority_topics[], avoid_topics[], identity{is[],is_not[],one_liner}}.
 	context: { value: (flags) => readJsonObjectFlag(flags, "context") },
@@ -116,6 +118,8 @@ export const ARGS = {
 			},
 		},
 		existing_content: { value: (flags) => flagStr(flags["existing-content"]) },
+		// Your own thesis: adopted as the run's direction, so a gate never pauses for it.
+		direction: { flag: "direction" },
 		article_id: { flag: "article" },
 		...RUN_OPTIONS,
 	},
@@ -124,8 +128,32 @@ export const ARGS = {
 	},
 	list_arena_runs: {
 		arena_id: { flag: "arena" },
+		article_id: { flag: "article" },
+		status: { flag: "status", type: "list" },
+		since: { flag: "since" },
+		before: { flag: "before" },
 		limit: { flag: "limit", type: "num" },
 	},
+	get_latest_arena_run: {
+		article_id: { flag: "article", required: true },
+	},
+	// What research decided each site is, and your call on one (never overridden by the model).
+	list_source_roles: {
+		role: { flag: "role", enum: ["authority", "company", "context"] },
+		rival: { flag: "rival", type: "bool" },
+		decided_by: { flag: "decided-by", enum: ["model", "customer", "staff"] },
+		limit: { flag: "limit", type: "num" },
+	},
+	set_source_role: {
+		site: { positional: 1, label: "site", required: true },
+		role: { flag: "role", enum: ["authority", "company", "context"], required: true },
+		company: { flag: "company" },
+		rival: { flag: "rival", type: "bool" },
+		note: { flag: "note" },
+	},
+	reset_source_role: {
+		site: { positional: 1, label: "site", required: true },
+	},
 	submit_arena_direction: {
 		run_id: { positional: 0, label: "run-id", required: true },
 		choice: { flag: "choice", type: "num" },
@@ -144,6 +172,11 @@ export const ARGS = {
 	delete_arena: {
 		arena_id: { positional: 1, label: "arena-id", required: true },
 	},
+	update_arena: {
+		arena_id: { positional: 1, label: "arena-id", required: true },
+		name: { flag: "name" },
+		defaults: { value: (flags) => readJsonObjectFlag(flags, "defaults") },
+	},
 	// The arena's configuration as ONE file: `arena endpoint config <id>` prints it,
 	// `arena endpoint config <id> --file cfg.json` replaces it with the file's document.
 	get_arena_config: {
@@ -167,6 +200,12 @@ export async function cmdArena(ctx) {
 			return arenaRunStatus(rest);
 		case "runs":
 			return arenaRuns(rest);
+		case "latest":
+			return arenaLatest(rest);
+		case "roles":
+			return arenaRoles(rest);
+		case "role":
+			return arenaRole(rest);
 		case "direction":
 			return arenaDirection(rest);
 		case "cancel":
@@ -181,7 +220,7 @@ export async function cmdArena(ctx) {
 			return arenaEndpoint(rest);
 		default:
 			throw new CliError(
-				`Unknown arena subcommand: ${sub ?? "(none)"}. Try: run, run-status, runs, direction, cancel, balance, list, endpoint`
+				`Unknown arena subcommand: ${sub ?? "(none)"}. Try: run, run-status, runs, latest, direction, cancel, balance, list, endpoint, roles, role`
 			);
 	}
 }
@@ -262,6 +301,47 @@ async function arenaRuns(ctx) {
 	return 0;
 }
 
+async function arenaLatest(ctx) {
+	const { client, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.get_latest_arena_run, flags, ctx.positionals);
+	const result = await client.callTool("get_latest_arena_run", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function arenaRoles(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool(
+		"list_source_roles",
+		argsFromFlags(ARGS.list_source_roles, flags, ctx.positionals)
+	);
+	printResult(io, flags, result);
+	return 0;
+}
+
+/** `arena role set <site> --role …` / `arena role reset <site>` — your call on one site. */
+async function arenaRole(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const action = positionals[0];
+	if (action === "set") {
+		const args = argsFromFlags(ARGS.set_source_role, flags, positionals);
+		const result = await client.callTool("set_source_role", args);
+		ok(ctx, `${result?.role?.site ?? args.site} is now ${args.role}${args.rival ? " (a rival)" : ""}.`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (action === "reset") {
+		const result = await client.callTool(
+			"reset_source_role",
+			argsFromFlags(ARGS.reset_source_role, flags, positionals)
+		);
+		ok(ctx, result?.reset ? "Handed back to research." : "Research had not recorded that site.");
+		printResult(io, flags, result);
+		return 0;
+	}
+	throw new CliError(`Unknown arena role action: ${action ?? "(none)"}. Try: set, reset`);
+}
+
 async function arenaDirection(ctx) {
 	const { client, flags, io } = ctx;
 	const runId = requirePositional(ctx.positionals, 0, "run-id");
@@ -327,6 +407,14 @@ async function arenaEndpoint(ctx) {
 		printResult(io, flags, result);
 		return 0;
 	}
+	if (action === "update" || action === "edit") {
+		const id = requirePositional(positionals, 1, "arena-id");
+		const args = argsFromFlags(ARGS.update_arena, flags, positionals);
+		const result = await client.callTool("update_arena", args);
+		ok(ctx, `Updated arena ${id}.`);
+		printResult(io, flags, result);
+		return 0;
+	}
 	if (action === "config") {
 		const id = requirePositional(positionals, 1, "arena-id");
 		if (flagStr(flags.file) === undefined) {
@@ -344,5 +432,5 @@ async function arenaEndpoint(ctx) {
 		printResult(io, flags, result);
 		return 0;
 	}
-	throw new CliError(`Unknown arena endpoint action: ${action ?? "(none)"}. Try: create, delete, config`);
+	throw new CliError(`Unknown arena endpoint action: ${action ?? "(none)"}. Try: create, update, delete, config`);
 }

package/package.json

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