@letterstory/cli 0.95.0 → 0.97.0

package/README.md

@@ -353,7 +353,7 @@ long-running agent can watch the fleet on a schedule without a browser.
 # 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 kernels --by version --outcome impressions14   # what each kernel/version change did
+letterstory admin patterns chain --dimension arenaVersion --outcome cited14   # what each kernel/arena/research change did
 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)

package/lib/cli.mjs

@@ -58,7 +58,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.95.0";
+export const VERSION = "0.97.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
@@ -660,10 +660,12 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        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 kernels [--by version|family] [--outcome cited14|read14|named|impressions14|clicks14|cited28|impressions28]
-                                                       What each kernel and version change did: the client's
-                                                       change minus clients that held still, pooled by
-                                                       transition. Needs fleet:read.
+  admin patterns chain [--dimension kernel|kernelVersion|arena|arenaVersion|researchPrompt] [--outcome cited14|read14|named|impressions14|clicks14|cited28|impressions28]
+                                                       What each change to the writing chain did (kernel,
+                                                       version, research arena, arena version, research
+                                                       prompt): the client's change minus the comparison,
+                                                       what changed with it, pooled by transition.
+                                                       "kernels" = --dimension kernelVersion. 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

package/lib/commands/admin.mjs

@@ -4,7 +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 "…"] | kernels [--by version|family] [--outcome cited14] | reports [--kind reports|weekly|run|ask] | report <id> | run | ask "<question>"   (fleet:read / fleet:query)
+//   admin patterns [--period 14d|30d] [--segment "…"] | chain [--dimension kernel|kernelVersion|arena|arenaVersion|researchPrompt] [--outcome cited14] | 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)
@@ -273,25 +273,25 @@ async function cmdAdminPatterns(ctx) {
 			}
 			return;
 		}
+		case "chain":
 		case "kernels": {
 			const params = new URLSearchParams();
-			if (flagStr(ctx.flags.by)) params.set("by", flagStr(ctx.flags.by));
+			const dimension = flagStr(ctx.flags.dimension) ?? (sub === "kernels" ? "kernelVersion" : undefined);
+			if (dimension) params.set("dimension", dimension);
 			if (flagStr(ctx.flags.outcome)) params.set("outcome", flagStr(ctx.flags.outcome));
-			const result = await staffRequest(ctx, "GET", `${PATTERNS}/kernels${params.size ? `?${params}` : ""}`);
+			const result = await staffRequest(ctx, "GET", `${PATTERNS}/chain${params.size ? `?${params}` : ""}`);
 			if (json) return printResult(ctx.io, ctx.flags, result);
 			const fmt = (v) => (v == null ? "—" : `${v >= 0 ? "+" : "−"}${Math.abs(v).toFixed(3)}`);
-			ctx.io.log(
-				`Kernel changes on ${result.outcome}, by ${result.by} (effect = change minus clients that held still):`
-			);
+			ctx.io.log(`Changes to ${result.dimension} on ${result.outcome} (effect = change minus the comparison):`);
 			for (const t of result.transitions)
 				ctx.io.log(
-					`  ${`${t.from} → ${t.to}`.padEnd(30)} ${fmt(t.effect)} (${fmt(t.lo)} to ${fmt(t.hi)})  ${t.verdict}  · ${t.swaps} swaps, ${t.clients} clients`
+					`  ${`${t.from} → ${t.to}`.padEnd(34)} ${fmt(t.effect)} (${fmt(t.lo)} to ${fmt(t.hi)})  ${t.verdict}  · ${t.swaps} changes${t.confounded ? `, ${t.confounded} with another` : ""}, ${t.clients} clients`
 				);
 			if (!result.transitions.length) ctx.io.log("  none yet");
-			ctx.io.log(`\n${result.by === "version" ? "Versions" : "Kernels"} (descriptive):`);
-			for (const k of result.kernels)
+			ctx.io.log(`\nEvery value (descriptive):`);
+			for (const k of result.values)
 				ctx.io.log(
-					`  ${k.label.padEnd(16)} ${String(k.posts).padStart(6)} posts  ${String(k.clients).padStart(4)} clients  ${k.outcome ? k.outcome.mean.toFixed(3) : "—"}`
+					`  ${k.label.padEnd(26)} ${String(k.posts).padStart(6)} posts  ${String(k.clients).padStart(4)} clients  ${k.outcome ? k.outcome.mean.toFixed(3) : "—"}`
 				);
 			return;
 		}
@@ -334,9 +334,7 @@ async function cmdAdminPatterns(ctx) {
 			return;
 		}
 		default:
-			throw new CliError(
-				'Usage: admin patterns [show] | kernels | reports | report <id> | run | ask "<question>"'
-			);
+			throw new CliError('Usage: admin patterns [show] | chain | reports | report <id> | run | ask "<question>"');
 	}
 }
 
@@ -639,6 +637,8 @@ 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 … --write Hazel              write every arm into an article with one kernel
+ *                            (live version, pinned): the arena the only difference, read with Write's measures and blind
  *   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
@@ -1995,7 +1995,7 @@ async function cmdAdminTuning(ctx) {
 			].filter(Boolean).length;
 			if (!title || named !== 1)
 				throw new CliError(
-					"Usage: admin tuning research-compare --title \"…\" (--candidate <version-id> | --patch '{…}' | --null-check | --candidates <id>,… [--patches '[{…},…]']) [--keys k1,k2] [--concurrency 6] [--experiment <id>]"
+					"Usage: admin tuning research-compare --title \"…\" (--candidate <version-id> | --patch '{…}' | --null-check | --candidates <id>,… [--patches '[{…},…]']) [--write Hazel] [--keys k1,k2] [--concurrency 6] [--experiment <id>]"
 				);
 			const several =
 				versionIds?.length || patches?.length
@@ -2020,6 +2020,8 @@ async function cmdAdminTuning(ctx) {
 					title,
 					candidate,
 					candidates: several,
+					// The kernel that writes every arm into a finished article (the arena the only difference).
+					write: flagStr(flags.write) ? { kernel: flagStr(flags.write) } : undefined,
 					keys: flagList(flags.keys),
 					concurrency: flagNum(flags.concurrency),
 					experiment_id: flagStr(flags.experiment),

package/package.json

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