@letterstory/cli 0.62.0 → 0.64.0

package/README.md

@@ -144,6 +144,7 @@ letterstory phantom domain connect <phantom-id> myblog.com      # attach one you
 letterstory posts list [--limit <n>] [--collection <uuid>]
 letterstory posts show <article-id>
 letterstory posts new --title "…" --collection <uuid> --body "…" [--article-id <uuid>]   # or --file <path|->; --article-id updates that article instead of creating one
+letterstory posts new --title "…" --collection <uuid> --body "…" --context "Internal data from 120 accounts: disputes fell 38%."   # your own data: stated in the post with your attribution
 letterstory posts publish <article-id>
 letterstory posts unpublish <article-id>
 letterstory posts delete --id <uuid> [--id <uuid> ...]                # permanent; content, history, and any published copy are all removed
@@ -725,6 +726,11 @@ letterstory insights top [--period 14d|30d|90d] [--collection <uuid>] [--limit <
 AI visibility and page access — the Measure tabs' reads, for scripts and agents:
 
 ```bash
+# The Measure Overview: how often AI answers name you and cite your pages (rates
+# with 95% intervals and gated trends), share of voice, search for your site and
+# the phantom network kept apart, and each ranking target's standing.
+letterstory insights summary [--period 14d|30d|90d]
+
 # The AI Visibility Bank: which questions named you, cited your pages, or both (a
 # breakthrough). All time unless --period; --source picks the phantom network
 # (default), your marketing site, or the whole portfolio; --phantom narrows to

package/lib/cli.mjs

@@ -55,7 +55,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.62.0";
+export const VERSION = "0.64.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.
@@ -240,7 +240,7 @@ Phantomstory (a collection Letterstory hosts as an independent publication):
 Content:
   posts list [--limit <n>] [--collection <uuid>]     List your articles
   posts show <article-id>                            Show one article
-  posts new --title <t> --collection <uuid> (--body <text> | --file <path|->) [--article-id <uuid>]
+  posts new --title <t> --collection <uuid> (--body <text> | --file <path|->) [--article-id <uuid>] [--context <text>]
   posts publish <article-id>                         Publish an article
   posts unpublish <article-id>                       Unpublish an article
   posts delete --id <uuid> [--id <uuid> ...]         Permanently delete article(s)
@@ -862,6 +862,7 @@ Mail:
   mail postal-address "<address>"                      Set the org's CAN-SPAM mailing address (email footers)
 
 Insights:
+  insights summary [--period 14d|30d|90d]              Measure Overview: AI named/cited rates, share of voice, search, targets
   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

@@ -452,6 +452,10 @@ async function cmdAdminTuningContext(ctx) {
  *   admin tuning arenas | arena <version-id>                   our arena's versions / one version's file and diff
  *   admin tuning arena-candidate --patch '{…}' | --file f.json [--of <version-id>] [--note "…"]   save a candidate
  *   admin tuning research-compare --title "…" (--candidate <version-id> | --patch '{…}' | --null-check) [--keys …]
+ *   admin tuning research-compare --title "…" --candidates <version-id>,… | --patches '[{…},{…}]'   several
+ *                            candidates against ONE control arm (k + 1 runs per input, not 2k)
+ *   admin tuning arena-dials                                   every arena setting: help, default, evidence, live's value
+ *   admin tuning comparison-extend <comparison-id> --keys k1,k2 | --all   add inputs to a comparison on fixed inputs
  *   admin tuning research-inputs [--set v1]                    research's fixed inputs
  *   admin tuning research-split [--since-hours 72] [--at <iso>,…]   what each deploy did to research in production
  *   admin tuning research-standing                             live's level on the fixed inputs, week by week
@@ -899,12 +903,34 @@ async function cmdAdminTuning(ctx) {
 			const versionId = flagStr(flags.candidate);
 			const patch = jsonFlag(flags.patch, "--patch");
 			const nullCheck = flagBool(flags["null-check"]);
-			const named = [versionId !== undefined, patch !== undefined, nullCheck === true].filter(Boolean).length;
+			const versionIds = flagList(flags.candidates);
+			const patches = jsonFlag(flags.patches, "--patches");
+			if (patches !== undefined && !Array.isArray(patches))
+				throw new CliError("--patches is a JSON array of patches: '[{…},{…}]'");
+			const named = [
+				versionId !== undefined,
+				patch !== undefined,
+				nullCheck === true,
+				(versionIds?.length ?? 0) + (patches?.length ?? 0) > 0,
+			].filter(Boolean).length;
 			if (!title || named !== 1)
 				throw new CliError(
-					"Usage: admin tuning research-compare --title \"…\" (--candidate <version-id> | --patch '{…}' | --null-check) [--keys k1,k2] [--concurrency 6] [--experiment <id>]"
+					"Usage: admin tuning research-compare --title \"…\" (--candidate <version-id> | --patch '{…}' | --null-check | --candidates <id>,… [--patches '[{…},…]']) [--keys k1,k2] [--concurrency 6] [--experiment <id>]"
 				);
-			const candidate = versionId ? { version_id: versionId } : patch ? { patch } : { null_check: true };
+			const several =
+				versionIds?.length || patches?.length
+					? [
+							...(versionIds ?? []).map((v) => ({ version_id: v })),
+							...(patches ?? []).map((p) => ({ patch: p })),
+						]
+					: undefined;
+			const candidate = several
+				? undefined
+				: versionId
+					? { version_id: versionId }
+					: patch
+						? { patch }
+						: { null_check: true };
 			const r = await staffRequest(
 				ctx,
 				"POST",
@@ -913,6 +939,7 @@ async function cmdAdminTuning(ctx) {
 					primitive: "research",
 					title,
 					candidate,
+					candidates: several,
 					keys: flagList(flags.keys),
 					concurrency: flagNum(flags.concurrency),
 					experiment_id: flagStr(flags.experiment),
@@ -920,6 +947,34 @@ async function cmdAdminTuning(ctx) {
 			);
 			return json ? printResult(io, flags, r) : io.log(`research comparison ${r.comparison?.id ?? ""} started`);
 		}
+		case "arena-dials": {
+			const r = await staffRequest(ctx, "GET", `${T}/arena-files/dials`);
+			if (json) return printResult(io, flags, r);
+			const valueOf = (key) => key.split(".").reduce((v, k) => (v == null ? v : v[k]), r.live.file);
+			const lines = [];
+			for (const panel of r.panels) {
+				lines.push(`${panel.title} — ${panel.question}`);
+				for (const d of r.dials.filter((x) => x.panel === panel.id))
+					lines.push(
+						`  ${d.key.padEnd(36)} live ${JSON.stringify(valueOf(d.key))}  (default ${JSON.stringify(d.fleetDefault)})  ${d.label}`
+					);
+			}
+			lines.push(
+				`providers: ${r.providers.map((p) => `${p.id}${p.configured ? "" : " (no key here)"}`).join(", ")}`
+			);
+			return io.log(lines.join("\n"));
+		}
+		case "comparison-extend": {
+			const keys = flagBool(flags.all) ? "all" : flagList(flags.keys);
+			if (!id || !keys?.length)
+				throw new CliError("Usage: admin tuning comparison-extend <comparison-id> --keys k1,k2 | --all");
+			const r = await staffRequest(ctx, "POST", `${T}/comparisons/${id}/extend`, { keys });
+			return json
+				? printResult(io, flags, r)
+				: io.log(
+						`comparison ${r.comparison.id}: ${r.comparison.added.length} input(s) added, ${r.comparison.pairs} in all`
+					);
+		}
 		case "research-inputs": {
 			const set = flagStr(flags.set);
 			return printResult(
@@ -1182,7 +1237,7 @@ async function cmdAdminTuning(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|reading-list|pair|side-by-side|candidates|base-kernels|base-versions|sessions|session|session-new|propose|trial-add|trial-run|trial-save|promote|arenas|arena|arena-candidate|research-compare|research-inputs|research-split|research-standing|promote-arena|shred-compare|shred-inputs|shred-split|shred-standing|shredders|shredder|shredder-candidate|promote-shredder|enhance-compare|enhance-inputs|enhance-split|enhance-standing|enhancers|enhancer|enhancer-candidate|promote-enhancer (see --help)"
+				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|reading-list|pair|side-by-side|candidates|base-kernels|base-versions|sessions|session|session-new|propose|trial-add|trial-run|trial-save|promote|arenas|arena|arena-candidate|arena-dials|comparison-extend|research-compare|research-inputs|research-split|research-standing|promote-arena|shred-compare|shred-inputs|shred-split|shred-standing|shredders|shredder|shredder-candidate|promote-shredder|enhance-compare|enhance-inputs|enhance-split|enhance-standing|enhancers|enhancer|enhancer-candidate|promote-enhancer (see --help)"
 			);
 	}
 }

package/lib/commands/insights.mjs

@@ -1,7 +1,7 @@
 // `insights` — Search Console impressions/clicks across the phantom network, at the
 // network, single-post, and top-posts levels (ported from phantomstory-cli's
-// insights.ts); plus Measure's AI Visibility Bank (`bank`) and phantom Page
-// Access (`access`) — the same reads the web app's Measure tabs render.
+// insights.ts); plus Measure's Overview (`summary`), AI Visibility Bank (`bank`)
+// and phantom Page Access (`access`) — the same reads the web app's Measure tabs render.
 
 import { CliError } from "../client.mjs";
 import { flagStr, flagNum, requirePositional, printResult, compact, argsFromFlags } from "./shared.mjs";
@@ -19,6 +19,9 @@ export const ARGS = {
 		period: { flag: "period", enum: PERIODS },
 		collection_id: { flag: "collection" },
 	},
+	get_measure_summary: {
+		period: { flag: "period", enum: PERIODS },
+	},
 };
 
 export async function cmdInsights(ctx) {
@@ -35,8 +38,12 @@ export async function cmdInsights(ctx) {
 			return call(rest, "get_ai_visibility_bank");
 		case "access":
 			return call(rest, "get_page_access");
+		case "summary":
+			return call(rest, "get_measure_summary");
 		default:
-			throw new CliError(`Unknown insights subcommand: ${sub ?? "(none)"}. Try: site, post, top, bank, access`);
+			throw new CliError(
+				`Unknown insights subcommand: ${sub ?? "(none)"}. Try: summary, site, post, top, bank, access`
+			);
 	}
 }
 

package/lib/commands/posts.mjs

@@ -73,7 +73,9 @@ async function postsNew(ctx) {
 	const body = readBodyInput(flags);
 	if (!body) throw new CliError("Provide --body or --file <path>.");
 	const articleId = flagStr(flags["article-id"]);
-	const args = compact({ title, body, collection_id: collection, article_id: articleId });
+	// Steering and/or your own data: figures in it are stated in the post with your attribution.
+	const context = flagStr(flags.context);
+	const args = compact({ title, body, collection_id: collection, article_id: articleId, context });
 	const result = await client.callTool("ingest_article", args);
 	ok(ctx, articleId ? `Updated "${title}".` : `Created draft "${title}".`);
 	printResult(io, flags, result);

package/package.json

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