@letterstory/cli 0.54.0 → 0.57.0

package/README.md

@@ -359,6 +359,12 @@ letterstory admin tuning compare --title "Echo vs live" --candidates Hazel:21,As
 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 reading-list <id> --n 10      # your next blind pairs as links (Text A / Text B), to read off the screen; pick in the console
+letterstory admin tuning pair <id> --cell <key>        # one pair named: live and candidate, both texts, the measures per arm (a key reads every pair)
+letterstory admin tuning candidates --kernels all --patch '{"writer":"echo/echo"}' --note "Echo"   # the same change as a candidate of each kernel
+letterstory admin tuning session-new --title "Echo round 1" --kernel Hazel --input-file brief.md --kind outline [--version 22]
+letterstory admin tuning propose <session> --text "Echo with rarity on; live with the shred after" --create   # trials from words, over the dials
+letterstory admin tuning trial-run <trial> --repeats 2  # runs advance on the server; poll `admin tuning session <id> --texts`
+letterstory admin tuning trial-save <trial> --note "…"  # a trial as a candidate version (never live); then `admin tuning compare`
 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"
@@ -573,6 +579,14 @@ letterstory shredder run <endpoint-id> --file post.md --format markdown
 
 letterstory shredder run <endpoint-id> --file post.md --no-wait   # just queue it
 letterstory shredder job <job-id>                                 # poll it yourself
+
+# The shredder as ONE versioned file (like a kernel file; schema at /api/schema/shredder):
+letterstory shredder file <endpoint-id> > shredder.json       # the file the endpoint shreds with
+letterstory shredder file <endpoint-id> --patch '{"rewriters":{"excludeWriterFamily":true}}'
+letterstory shredder versions <endpoint-id>                    # your copy's versions and our releases
+letterstory shredder pin <endpoint-id> <version-id|none>       # pin one of our releases, or follow live
+letterstory shredder offer <endpoint-id> [--accept]            # our newer version, over your own changes
+letterstory shredder families [--hours 6]                      # how each rewriter family is doing
 ```
 
 Both follow loops poll every 15–20 s. `LETTERSTORY_POLL_INTERVAL_MS` overrides that — set

package/lib/cli.mjs

@@ -54,7 +54,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.54.0";
+export const VERSION = "0.57.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.
@@ -718,7 +718,15 @@ Shredder (diversify content produced outside Letterstory; structure preserved):
                                                        job lands as error or degraded. Pace the polling with
                                                        LETTERSTORY_POLL_INTERVAL_MS.
   shredder job <job-id>                                Poll a queued shred and print it when it lands
-  shredder runs [--endpoint <id>] [--limit <n>]        Recent shred calls (telemetry), newest first
+  shredder runs [--endpoint <id>] [--limit <n>]        Recent shred calls (telemetry), newest first:
+                                                       the shredder version, level, seats and models each ran
+  shredder file <endpoint-id>                          Print the shredder file the endpoint shreds with
+  shredder file <endpoint-id> (--file f.json | --patch '<json>') [--note "…"]
+                                                       Save a new version of the endpoint's own copy
+                                                       (schema: GET /api/schema/shredder)
+  shredder versions <endpoint-id>                      Your copy's versions and our released ones
+  shredder pin <endpoint-id> <version-id|none>         Pin one of our versions, or follow our live one
+  shredder offer <endpoint-id> [--accept]              What our newer version would change; --accept takes it
 
 Ledes (opening lines for cold email, chosen per prospect from a hand-approved library):
   lede list                                            Your lede endpoints + run counts
@@ -852,7 +860,7 @@ Feedback (tell us what's broken, missing, unclear, or wanted):
 
 Evals (how the pipeline is doing on your posts, and the regression cases captured from them):
   evals scoreboard [--collection <id>] [--days N]      Every measure by stage: posts, failing, rate
-  evals cases [--status open|guarding|proposed|retired|rejected] [--stage research|brief|links|mentions|accuracy|pipeline]
+  evals cases [--status open|guarding|proposed|retired|rejected] [--stage research|brief|links|mentions|accuracy|pipeline|shred]
   evals capture (--article <id> | --research-run <id> | --kernel-job <id>) --title "…"
                 (--description "…" | --body … | --file <path>) (--measure <key> | --assertion "…")
                 [--stage <s>] [--replay <stage>] [--auto-pen <id>] [--published-version N]

package/lib/commands/admin.mjs

@@ -424,12 +424,28 @@ async function cmdAdminTuningContext(ctx) {
  *   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
+ *                        (Hazel:23@22 reads v23 against the test version v22 instead of live; it cannot promote)
  *   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 reading-list <comparison-id> [--n 10]          your next blind pairs as links, to read off the screen
+ *   admin tuning pair <comparison-id> --cell <key>             one pair named: live and candidate, both texts, the measures per arm
+ *   admin tuning candidates --kernels Hazel,Aspen|all --patch '{…}' [--base N] [--note "…"]   the same changes as a candidate of each kernel
  *   admin tuning promote <experiment-id> --versions <service-kernel-id>:<version>,…   promote from a "ship" decision
  *
+ * Sessions: one input written many ways, side by side (the console's Write › Sessions). Runs advance
+ * on the server (the advance-tuning-runs cron), so a session finishes with no tab open; the blind
+ * read of the results is a person's, in the console.
+ *   admin tuning base-kernels                                  the kernels a session can run on (ids for --kernel)
+ *   admin tuning base-versions <kernel-id>                     the versions a session on it can run against
+ *   admin tuning sessions | session <id> [--texts]             list / one session: trials, runs and their numbers (--texts adds each trial's latest text)
+ *   admin tuning session-new --title "…" --kernel <id|name> (--input-file f.md | --input "…") [--kind article|outline|brief]
+ *                            [--version N] [--writers echo/echo,…] [--trials-from <session-id>]
+ *   admin tuning propose <session-id> --text "Echo with rarity on; live with the shred after" [--create]
+ *   admin tuning trial-add <session-id> [--name "…"] [--patch '{…}'] [--options '{…}'] [--from <trial-id>]
+ *   admin tuning trial-run <trial-id> [--repeats 2]            queue runs (guardrails apply)
+ *   admin tuning trial-save <trial-id> [--note "…"]            save a trial as a candidate version (never live)
+ *
  * Research (Phase 3): our arena's versions as files, research comparisons, the deploy split.
  *   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
@@ -437,7 +453,16 @@ async function cmdAdminTuningContext(ctx) {
  *   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
+ *
+ * Shred (Phase 4): the same, for shredder versions on shred's fixed inputs.
+ *   admin tuning shred-compare --title "…" (--candidate <version-id> | --patch '{…}' | --null-check) [--keys …]
+ *   admin tuning shred-inputs [--set v1] | shred-split [--since-hours 72] [--at <iso>,…] | shred-standing
  *   admin tuning promote-arena <experiment-id> --version <arena-version-id>   promote our arena from a "ship" decision
+ *
+ * Shred (Phase 4): our shredder's versions as files.
+ *   admin tuning shredders | shredder <version-id>             our shredder's versions / one version's file and diff
+ *   admin tuning shredder-candidate --patch '{…}' | --file f.json [--of <version-id>] [--note "…"]   save a candidate
+ *   admin tuning promote-shredder <experiment-id> --version <shredder-version-id>   promote our shredder from a "ship" decision (blind picks required)
  */
 /** `--flag '<json>'` → the parsed object, or undefined when the flag is absent. */
 function jsonFlag(raw, name) {
@@ -452,6 +477,44 @@ function jsonFlag(raw, name) {
 	}
 }
 
+/**
+ * A session as an agent reads it: each trial's changes and runs with their headline numbers, and
+ * (with `texts`) the latest finished text per trial. The full session (traces, records) is `--json`.
+ */
+function sessionSummary(session, texts) {
+	const runsOf = (trialId) => session.runs.filter((r) => r.trialId === trialId);
+	return {
+		id: session.id,
+		title: session.title,
+		kernel: session.baseKernelName,
+		base_version: session.baseVersion ?? "live",
+		material_ready: session.material?.ready ?? true,
+		trials: session.trials.map((t) => {
+			const runs = runsOf(t.id);
+			const latest = [...runs].reverse().find((r) => r.status === "done" && r.outputText);
+			return compact({
+				id: t.id,
+				name: t.name,
+				file_patch: t.filePatch,
+				run_options: t.runOptions,
+				saved_as_version: t.savedAsVersion ?? undefined,
+				runs: runs.map((r) =>
+					compact({
+						id: r.id,
+						status: r.status,
+						error: r.error ?? undefined,
+						quality: r.metrics?.qualityTotal,
+						quality_scale: r.metrics?.qualityScale,
+						p_machine: r.metrics?.pMachine,
+						words: r.metrics?.words,
+					})
+				),
+				latest_text: texts && latest ? latest.outputText : undefined,
+			});
+		}),
+	};
+}
+
 async function cmdAdminTuning(ctx) {
 	const [sub, id] = ctx.positionals;
 	const { flags, io } = ctx;
@@ -508,12 +571,17 @@ async function cmdAdminTuning(ctx) {
 				throw new CliError(
 					'Usage: admin tuning compare --title "…" --candidates Hazel:21,Aspen:20 [--experiment <id>]'
 				);
+			// kernel:version, or kernel:version@control to read it against a test version instead of live.
 			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 [v, c] = item.slice(at + 1).split("@");
+				const version = Number(v);
+				const control = c === undefined ? undefined : Number(c);
+				if (at < 1 || !Number.isInteger(version) || (control !== undefined && !Number.isInteger(control)))
+					throw new CliError(
+						`--candidates items are kernel:version or kernel:version@control, got "${item}"`
+					);
+				return compact({ kernel: item.slice(0, at), candidate_version: version, control_version: control });
 			});
 			const r = await staffRequest(
 				ctx,
@@ -556,6 +624,199 @@ async function cmdAdminTuning(ctx) {
 			);
 			return json ? printResult(io, flags, r) : io.log(r.text);
 		}
+		case "pair": {
+			const cell = flagStr(flags.cell);
+			if (!id || !cell) throw new CliError("Usage: admin tuning pair <comparison-id> --cell <key>");
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/comparisons/${id}/pair?${new URLSearchParams({ cell })}`)
+			);
+		}
+		case "candidates": {
+			const patch = jsonFlag(flags.patch, "--patch");
+			const wanted = flagList(flags.kernels);
+			if (!patch || !wanted?.length)
+				throw new CliError(
+					'Usage: admin tuning candidates --kernels Hazel,Aspen|all --patch \'{"writer":"echo/echo"}\' [--base N] [--note "…"]'
+				);
+			const { kernels } = await staffRequest(ctx, "GET", `${T}/kernel-files`);
+			const all = wanted.length === 1 && wanted[0].toLowerCase() === "all";
+			const picked = all
+				? kernels
+				: wanted.map((name) => {
+						const k = kernels.find(
+							(x) => x.kernel.toLowerCase() === name.toLowerCase() || x.serviceKernelId === name
+						);
+						if (!k) throw new CliError(`No catalog kernel named ${name}.`);
+						return k;
+					});
+			const base = flagNum(flags.base);
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/kernel-files/candidates`,
+				compact({
+					targets: picked.map((k) => compact({ service_kernel_id: k.serviceKernelId, base })),
+					file_patch: patch,
+					note: flagStr(flags.note),
+				})
+			);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				r.outcomes
+					.map((o) =>
+						o.version
+							? `${(o.kernel ?? o.serviceKernelId).padEnd(12)} candidate v${o.version} (from v${o.base}): ${o.changes.join(", ") || "no change"}`
+							: `${(o.kernel ?? o.serviceKernelId).padEnd(12)} refused: ${o.error}`
+					)
+					.join("\n")
+			);
+		}
+		// --- Sessions: one input written many ways, side by side ---
+		case "base-kernels": {
+			const r = await staffRequest(ctx, "GET", `${T}/kernels`);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				r.kernels.map((k) => `${k.name.padEnd(28)} ${(k.orgName ?? "shared").padEnd(20)} ${k.id}`).join("\n")
+			);
+		}
+		case "base-versions": {
+			if (!id) throw new CliError("Usage: admin tuning base-versions <kernel-id>");
+			const r = await staffRequest(ctx, "GET", `${T}/kernels/${id}/versions`);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				r.versions
+					.map((v) => `v${v.version}  ${v.status.padEnd(9)} ${v.writer}${v.note ? `  ${v.note}` : ""}`)
+					.join("\n") || "(no versions)"
+			);
+		}
+		case "sessions": {
+			const r = await staffRequest(ctx, "GET", `${T}?limit=${flagNum(flags.limit) ?? 30}`);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				r.sessions
+					.map(
+						(x) =>
+							`${x.id}  ${x.title}  · ${x.baseKernelName ?? "?"}${x.baseVersion ? ` v${x.baseVersion}` : ""} · ${x.trialCount} trials, ${x.runCount} runs`
+					)
+					.join("\n") || "(no sessions)"
+			);
+		}
+		case "session": {
+			if (!id) throw new CliError("Usage: admin tuning session <session-id> [--texts]");
+			const { session } = await staffRequest(ctx, "GET", `${T}/sessions/${id}`);
+			if (json) return printResult(io, flags, { session });
+			return printResult(io, { ...flags, json: true }, sessionSummary(session, flagBool(flags.texts)));
+		}
+		case "session-new": {
+			const title = flagStr(flags.title);
+			const kernel = flagStr(flags.kernel);
+			const path = flagStr(flags["input-file"]);
+			let input = flagStr(flags.input);
+			if (path) {
+				try {
+					input = readFileSync(path, "utf8");
+				} catch (err) {
+					throw new CliError(`--input-file ${path}: ${err.message}`);
+				}
+			}
+			if (!title || !kernel || !input)
+				throw new CliError(
+					'Usage: admin tuning session-new --title "…" --kernel <id|name> (--input-file f.md | --input "…") [--kind article|outline|brief] [--version N] [--writers a,b] [--trials-from <session-id>]'
+				);
+			let kernelId = kernel;
+			if (!/^[0-9a-f-]{36}$/i.test(kernel)) {
+				const { kernels } = await staffRequest(ctx, "GET", `${T}/kernels`);
+				const matches = kernels.filter((k) => k.name.toLowerCase() === kernel.toLowerCase());
+				const shared = matches.find((k) => !k.orgName) ?? matches[0];
+				if (!shared) throw new CliError(`No kernel named ${kernel} (admin tuning base-kernels lists them).`);
+				kernelId = shared.id;
+			}
+			const { session } = await staffRequest(
+				ctx,
+				"POST",
+				T,
+				compact({
+					title,
+					input_text: input,
+					input_kind: flagStr(flags.kind) ?? "unknown",
+					base_kernel_id: kernelId,
+					base_version: flagNum(flags.version),
+					trials_from_session_id: flagStr(flags["trials-from"]),
+					writers: (flagList(flags.writers) ?? []).map((model) => ({ model })),
+				})
+			);
+			if (json) return printResult(io, flags, { session });
+			return io.log(
+				`session ${session.id}: ${session.trials.length} trials on ${session.baseKernelName}${session.baseVersion ? ` v${session.baseVersion}` : " (live)"} → ${ctx.client.url}/superadmin/tuning/${session.id}`
+			);
+		}
+		case "propose": {
+			const text = flagStr(flags.text);
+			if (!id || !text)
+				throw new CliError(
+					'Usage: admin tuning propose <session-id> --text "Echo with rarity on; …" [--create]'
+				);
+			const r = await staffRequest(ctx, "POST", `${T}/sessions/${id}/propose`, { description: text });
+			if (flagBool(flags.create))
+				for (const t of r.trials)
+					await staffRequest(ctx, "POST", `${T}/sessions/${id}/trials`, {
+						name: t.name,
+						file_patch: t.file_patch,
+						run_options: t.run_options,
+					});
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				[
+					...r.trials.map(
+						(t) => `${flagBool(flags.create) ? "created" : "proposed"} ${t.name}: ${t.changes.join(", ")}`
+					),
+					...r.unsupported.map((u) => `not expressible with the dials: ${u}`),
+					...r.rejected.map((x) => `dropped from ${x.trial}: ${x.dial} (${x.reason})`),
+				].join("\n") || "(nothing proposed)"
+			);
+		}
+		case "trial-add": {
+			if (!id)
+				throw new CliError(
+					"Usage: admin tuning trial-add <session-id> [--name] [--patch '{…}'] [--options '{…}'] [--from <trial-id>]"
+				);
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/sessions/${id}/trials`,
+				compact({
+					name: flagStr(flags.name),
+					file_patch: jsonFlag(flags.patch, "--patch"),
+					run_options: jsonFlag(flags.options, "--options"),
+					from_trial_id: flagStr(flags.from),
+				})
+			);
+			return json ? printResult(io, flags, r) : io.log(`trial ${r.trial.id} (${r.trial.name})`);
+		}
+		case "trial-run": {
+			if (!id) throw new CliError("Usage: admin tuning trial-run <trial-id> [--repeats N]");
+			const r = await staffRequest(ctx, "POST", `${T}/trials/${id}/run`, {
+				repeats: flagNum(flags.repeats) ?? 1,
+			});
+			return json
+				? printResult(io, flags, r)
+				: io.log(`queued ${r.runs.length} run(s): ${r.runs.map((x) => x.id).join(", ")}`);
+		}
+		case "trial-save": {
+			if (!id) throw new CliError('Usage: admin tuning trial-save <trial-id> [--note "…"]');
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/trials/${id}/candidate`,
+				compact({ note: flagStr(flags.note) })
+			);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				`${r.kernel}: saved as candidate v${r.version}${r.baseVersion ? ` (from v${r.baseVersion})` : ""}${r.leftBehind.length ? `; per-run, not saved: ${r.leftBehind.join(", ")}` : ""}`
+			);
+		}
 		// --- Research: our arena's versions, research comparisons, the deploy split ---
 		case "arenas": {
 			const r = await staffRequest(ctx, "GET", `${T}/arena-files`);
@@ -633,6 +894,56 @@ async function cmdAdminTuning(ctx) {
 				await staffRequest(ctx, "GET", `${T}/research/deploy-split${q.size ? `?${q}` : ""}`)
 			);
 		}
+		case "shred-compare": {
+			const title = flagStr(flags.title);
+			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;
+			if (!title || named !== 1)
+				throw new CliError(
+					"Usage: admin tuning shred-compare --title \"…\" (--candidate <version-id> | --patch '{…}' | --null-check) [--keys k1,k2] [--concurrency 6] [--experiment <id>]"
+				);
+			const candidate = versionId ? { version_id: versionId } : patch ? { patch } : { null_check: true };
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/comparisons`,
+				compact({
+					primitive: "shred",
+					title,
+					candidate,
+					keys: flagList(flags.keys),
+					concurrency: flagNum(flags.concurrency),
+					experiment_id: flagStr(flags.experiment),
+				})
+			);
+			return json ? printResult(io, flags, r) : io.log(`shred comparison ${r.comparison?.id ?? ""} started`);
+		}
+		case "shred-inputs": {
+			const set = flagStr(flags.set);
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/shred/inputs${set ? `?${new URLSearchParams({ set })}` : ""}`)
+			);
+		}
+		case "shred-split": {
+			const q = new URLSearchParams(
+				compact({
+					since_hours: flagStr(flags["since-hours"]),
+					window_hours: flagStr(flags["window-hours"]),
+					at: flagStr(flags.at),
+				})
+			);
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/shred/deploy-split${q.size ? `?${q}` : ""}`)
+			);
+		}
+		case "shred-standing":
+			return printResult(io, { ...flags, json: true }, await staffRequest(ctx, "GET", `${T}/shred/standing`));
 		case "research-standing":
 			return printResult(io, { ...flags, json: true }, await staffRequest(ctx, "GET", `${T}/research/standing`));
 		case "promote-arena": {
@@ -650,6 +961,56 @@ async function cmdAdminTuning(ctx) {
 				)
 			);
 		}
+		// --- Shred: our shredder's versions as files ---
+		case "shredders": {
+			const r = await staffRequest(ctx, "GET", `${T}/shredder-files`);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				r.versions
+					.map((v) => `${v.label.padEnd(18)} ${v.status.padEnd(9)} ${v.id}${v.note ? `  ${v.note}` : ""}`)
+					.join("\n") || "(no versions)"
+			);
+		}
+		case "shredder": {
+			if (!id) throw new CliError("Usage: admin tuning shredder <version-id>");
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/shredder-files/${id}`)
+			);
+		}
+		case "shredder-candidate": {
+			const patch = jsonFlag(flags.patch, "--patch");
+			const file = jsonFile({ "shredder-file": flags.file }, "shredder");
+			if ((patch === undefined) === (file === undefined))
+				throw new CliError(
+					'Usage: admin tuning shredder-candidate --patch \'{"rewriters":{"excludeWriterFamily":true}}\' | --file shredder.json [--of <version-id>] [--note "…"]'
+				);
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/shredder-files`,
+				compact({ patch, file, patch_of: flagStr(flags.of), note: flagStr(flags.note) })
+			);
+			return json ? printResult(io, flags, r) : io.log(`saved candidate ${r.version.label} (${r.version.id})`);
+		}
+		case "promote-shredder": {
+			const version = flagStr(flags.version);
+			if (!id || !version)
+				throw new CliError(
+					"Usage: admin tuning promote-shredder <experiment-id> --version <shredder-version-id>"
+				);
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(
+					ctx,
+					"POST",
+					`${EXPERIMENTS}/${id}/promote`,
+					compact({ shredder_version_id: version, actor: actorFrom(flags) })
+				)
+			);
+		}
 		case "promote": {
 			const list = flagList(flags.versions);
 			if (!id || !list?.length)
@@ -673,7 +1034,7 @@ async function cmdAdminTuning(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|reading-list|promote|arenas|arena|arena-candidate|research-compare|research-inputs|research-split|research-standing|promote-arena (see --help)"
+				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|reading-list|pair|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 (see --help)"
 			);
 	}
 }

package/lib/commands/evals.mjs

@@ -16,7 +16,7 @@
 import { CliError } from "../client.mjs";
 import { flagStr, readBodyInput, printResult, ok, argsFromFlags } from "./shared.mjs";
 
-const STAGES = ["research", "brief", "links", "mentions", "accuracy", "pipeline"];
+const STAGES = ["research", "brief", "links", "mentions", "accuracy", "pipeline", "shred"];
 const STATUSES = ["proposed", "open", "guarding", "retired", "rejected"];
 
 /** `--keys a,b,c` (or repeated `--keys`) → ["a", "b", "c"]; undefined when unset. */

package/lib/commands/shredder.mjs

@@ -35,6 +35,23 @@ function readJsonFileFlag(flags, flag) {
 	}
 }
 
+/** `--<flag> '<json>'` inline, or `--<flag>-file <path>` → a JSON object, or undefined. */
+function readJsonObjectFlag(flags, name) {
+	const inline = flagStr(flags[name]);
+	if (inline !== undefined) {
+		let parsed;
+		try {
+			parsed = JSON.parse(inline);
+		} catch (err) {
+			throw new CliError(`--${name} is not valid JSON: ${err.message}`);
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+			throw new CliError(`--${name} must be a JSON object`);
+		return parsed;
+	}
+	return readJsonFileFlag(flags, `${name}-file`);
+}
+
 /**
  * How every command in this file sources its tool's inputs — see `argsFromFlags` in
  * shared.mjs and `scripts/parity-check.ts`, which diffs these keys against each tool's
@@ -68,6 +85,10 @@ export const ARGS = {
 	},
 	list_shredder_endpoints: {},
 	get_shred_balance: {},
+	// The rewriter families behind the shredder, as the platform's hourly watch reads them.
+	get_shred_family_health: {
+		hours: { flag: "hours", type: "num" },
+	},
 	create_shredder_endpoint: {
 		name: { flag: "name", required: true },
 	},
@@ -83,6 +104,33 @@ export const ARGS = {
 		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
 		config: { value: (flags) => readJsonFileFlag(flags, "file") },
 	},
+	// The shredder as a versioned file (the arena file's twin): `shredder file <id>` prints it,
+	// `--file f.json` saves a whole file, `--patch '{…}'` only the fields to change.
+	get_shredder_file: {
+		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
+	},
+	save_shredder_file: {
+		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
+		file: { value: (flags) => readJsonFileFlag(flags, "file") },
+		patch: { value: (flags) => readJsonObjectFlag(flags, "patch") },
+		note: "note",
+	},
+	list_shredder_versions: {
+		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
+	},
+	pin_shredder_version: {
+		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
+		version_id: {
+			value: (_flags, positionals) => {
+				const v = positionals[1];
+				if (v === undefined) throw new CliError("Missing required <version-id|none>");
+				return v === "none" ? null : v;
+			},
+		},
+	},
+	accept_shredder_offer: {
+		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
+	},
 };
 
 export async function cmdShredder(ctx) {
@@ -111,9 +159,19 @@ export async function cmdShredder(ctx) {
 			return shredderRuns(rest);
 		case "balance":
 			return shredderBalance(rest);
+		case "file":
+			return shredderFile(rest);
+		case "versions":
+			return shredderTool(rest, "list_shredder_versions");
+		case "pin":
+			return shredderTool(rest, "pin_shredder_version");
+		case "offer":
+			return rest.flags.accept === true ? shredderTool(rest, "accept_shredder_offer") : shredderOffer(rest);
+		case "families":
+			return shredderTool(rest, "get_shred_family_health");
 		default:
 			throw new CliError(
-				`Unknown shredder subcommand: ${sub ?? "(none)"}. Try: list, create, delete, endpoint, run, job, runs, balance`
+				`Unknown shredder subcommand: ${sub ?? "(none)"}. Try: list, create, delete, endpoint, run, job, runs, balance, file, versions, pin, offer, families`
 			);
 	}
 }
@@ -284,3 +342,54 @@ async function shredderBalance(ctx) {
 	printResult(io, flags, result);
 	return 0;
 }
+
+/**
+ * `shredder file <endpoint-id>` prints the file the endpoint shreds with (the file itself, so
+ * `> f.json` round-trips); `shredder file <endpoint-id> --file f.json | --patch '{…}' [--note …]`
+ * saves a new live version of the endpoint's own copy.
+ */
+async function shredderFile(ctx) {
+	const { client, flags, io } = ctx;
+	const saving =
+		flagStr(flags.file) !== undefined ||
+		flagStr(flags.patch) !== undefined ||
+		flagStr(flags["patch-file"]) !== undefined;
+	if (!saving) {
+		const result = await client.callTool(
+			"get_shredder_file",
+			argsFromFlags(ARGS.get_shredder_file, flags, ctx.positionals)
+		);
+		printResult(io, flags, result, (r) => JSON.stringify(r?.file ?? r, null, 2));
+		return 0;
+	}
+	const result = await client.callTool(
+		"save_shredder_file",
+		argsFromFlags(ARGS.save_shredder_file, flags, ctx.positionals)
+	);
+	ok(
+		ctx,
+		`Saved ${toolField(result, "version")?.label ?? "a new version"}; the endpoint shreds with it from now on.`
+	);
+	printResult(io, flags, result);
+	return 0;
+}
+
+/** `shredder offer <endpoint-id>`: what our newer version would change; `--accept` takes it. */
+async function shredderOffer(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool(
+		"get_shredder_file",
+		argsFromFlags(ARGS.get_shredder_file, flags, ctx.positionals)
+	);
+	const offer = toolField(result, "offer");
+	if (!offer) ok(ctx, "No offer: your endpoint shreds with our latest version, or a copy based on it.");
+	printResult(io, flags, result, (r) => JSON.stringify(r?.offer ?? null, null, 2));
+	return 0;
+}
+
+/** One shredder-file tool, its arguments from ARGS. */
+async function shredderTool(ctx, tool) {
+	const result = await ctx.client.callTool(tool, argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals));
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}

package/package.json

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