@letterstory/cli 0.94.0 → 0.96.0

package/README.md

@@ -353,6 +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 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.94.0";
+export const VERSION = "0.96.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,6 +660,10 @@ 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 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 "…"] | reports [--kind reports|weekly|run|ask] | report <id> | run | ask "<question>"   (fleet:read / fleet:query)
+//   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 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,6 +273,28 @@ async function cmdAdminPatterns(ctx) {
 			}
 			return;
 		}
+		case "kernels": {
+			const params = new URLSearchParams();
+			if (flagStr(ctx.flags.by)) params.set("by", flagStr(ctx.flags.by));
+			if (flagStr(ctx.flags.outcome)) params.set("outcome", flagStr(ctx.flags.outcome));
+			const result = await staffRequest(ctx, "GET", `${PATTERNS}/kernels${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):`
+			);
+			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`
+				);
+			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(
+					`  ${k.label.padEnd(16)} ${String(k.posts).padStart(6)} posts  ${String(k.clients).padStart(4)} clients  ${k.outcome ? k.outcome.mean.toFixed(3) : "—"}`
+				);
+			return;
+		}
 		case "reports": {
 			const kind = flagStr(ctx.flags.kind) ?? "reports";
 			const limit = flagStr(ctx.flags.limit) ?? "12";
@@ -312,7 +334,9 @@ async function cmdAdminPatterns(ctx) {
 			return;
 		}
 		default:
-			throw new CliError('Usage: admin patterns [show] | reports | report <id> | run | ask "<question>"');
+			throw new CliError(
+				'Usage: admin patterns [show] | kernels | reports | report <id> | run | ask "<question>"'
+			);
 	}
 }
 
@@ -615,6 +639,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
@@ -1971,7 +1997,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
@@ -1996,6 +2022,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.94.0",
+	"version": "0.96.0",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",