@letterstory/cli 0.121.0 → 0.121.1

package/README.md

@@ -568,6 +568,8 @@ letterstory arena endpoint delete <arena-id> --yes
 letterstory arena file <arena-id> > arena.json            # the file the arena runs now
 letterstory arena file <arena-id> --patch '{"rules":{"context-figures":"measure"}}' --note "try it"
 letterstory arena file <arena-id> --file arena.json        # save a whole file as the next version
+letterstory arena file <arena-id> --file arena.json --candidate  # save beside live; runs nothing yet
+letterstory arena promote <arena-id> <version> --yes       # ship a candidate, or roll back
 letterstory arena versions <arena-id>                      # your copy's versions and our releases
 letterstory arena pin <arena-id> <version-id|none>         # pin one of our releases, or follow live
 letterstory arena offer <arena-id> [--accept]              # our newer version, over your own changes
@@ -621,6 +623,8 @@ letterstory shredder job <job-id>                                 # poll it your
 # 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 file <endpoint-id> --file s.json --candidate  # save beside live; shreds nothing yet
+letterstory shredder promote <endpoint-id> <version> --yes     # ship a candidate, or roll back
 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
@@ -659,6 +663,7 @@ letterstory org export > acme.json                 # the bundle — the same doc
 letterstory org export --sections primitives.kernels --sections data.collections
 letterstory org export --split acme/               # one file per record, for keeping config in git
 letterstory org join acme/ > acme.json             # rebuild the identical bundle from the directory
+letterstory org fields data.collections            # what each setting means: label, path, how it's edited, its gate
 letterstory org diff acme.json                     # what applying the bundle would change: + add, ~ change, - only in the org
 letterstory org apply acme.json --dry-run           # what apply would write; then drop --dry-run to apply
 letterstory org apply acme.json --prune --yes      # also delete records the bundle lacks

package/lib/cli.mjs

@@ -60,13 +60,15 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.121.0";
+export const VERSION = "0.121.1";
 
 // 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
 // `negate` spelling) in a command's ARGS map must be listed; boolean-flags.test.ts enforces it.
 export const BOOLEAN_FLAGS = new Set([
 	"json",
+	// shredder file / arena file: save the version as a candidate beside live.
+	"candidate",
 	// site tree: include children a fold-by-default family would hide; items over the whole subtree.
 	"unfold",
 	"subtree",
@@ -105,6 +107,11 @@ export const BOOLEAN_FLAGS = new Set([
 	"prune",
 	// org git sync --force
 	"force",
+	// `series create --paused`; `series update <id> --pause | --resume | --retire`.
+	"paused",
+	"pause",
+	"resume",
+	"retire",
 	"buy",
 	"rebuild",
 	// phantom spread-looks --apply
@@ -178,6 +185,8 @@ export const BOOLEAN_FLAGS = new Set([
 	"retired",
 	"retire",
 	"restore",
+	// `collection add "<headline>" --collection <id> --queue`.
+	"queue",
 	// Bool flags from command ARGS maps that were missing here.
 	"apply-rules",
 	"async",
@@ -332,6 +341,14 @@ Collections (the content engine as a primitive — one door, 'collection run'):
                                                        publish → (hosted) rebuild. Spends one of the
                                                        week's cadence slots. 20–60 min; followed unless
                                                        --no-wait; stops at the gate under manual approval.
+  collection queue <suggestion-id>                     Queue a headline, as the app's queue button does: the
+                                                       next slot of the schedule when the Planner is on,
+                                                       else a draft to write by hand
+  collection add "<headline>" --collection <id> [--queue]
+                                                       A headline you wrote: joins Up next, or with --queue
+                                                       is queued at once (the next slot, or a draft)
+  collection headline <suggestion-id> [--dismiss | --later | --restore] [--headline "…"]
+                                                       Dismiss, park, bring back or reword a headline
   collection run-status <run-id>                       Status, steps, constraints, verification
   collection runs [--collection <id>] [--status <s>] [--limit <n>]
   collection approve <run-id> [--now]                  Answer the gate (--now publishes immediately)
@@ -349,6 +366,7 @@ Phantomstory (a collection Letterstory hosts as an independent publication):
                                                        'collection run --collection <its collection_id>'.
   phantom get <phantom-id>                             Status, URL, domain, DNS
   phantom config <phantom-id> [--name … --theme … --collection …] [--collection-config '<json>']
+                              [--style '<json>'|none] [--stock-cover '<json>'|none] [--logo '<pick json>']
                               [--configure [--dry-run]]
                                                        The site's file joined to its collection's
   phantom rebuild <phantom-id> · phantom diagnostics <phantom-id> · phantom balance
@@ -492,7 +510,11 @@ Offerings (context layered org → offering → collection; a layer sets only wh
   onboarding status                                    Show the onboarding checklist
   onboarding step [--current <step>] [--complete <step>] [--skip <step>] [--status <status>]
   series list                                          The org's content series + coverage state
-  series create --name <n> --description <d> [--coverage a,b,c] [--collection <uuid>] [--template <key>]
+  series create --name <n> [--description <d>] [--coverage a,b,c] [--collection <uuid>] [--template <key>]
+                [--templates a,b] [--every-days <n>] [--purpose <text>] [--paused]
+  series update <series-id> [--every-days <n>|default] [--templates a,b] [--template <key>] [--purpose <text>]
+                [--description <d>] [--name <n>] [--coverage a,b,c] [--pause|--resume] [--retire]
+                                                       Pace, templates, pause; --retire is the delete
   series backfill <series-id> [--collection <uuid>]    Reconstruct a series from existing posts
 
 Ranking targets (what the org wants to be THE answer for — company-wide or on one offering):
@@ -992,9 +1014,11 @@ Shredder (diversify content produced outside Letterstory; structure preserved):
   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 "…"]
+  shredder file <endpoint-id> (--file f.json | --patch '<json>') [--note "…"] [--candidate]
                                                        Save a new version of the endpoint's own copy
-                                                       (schema: GET /api/schema/shredder)
+                                                       (schema: GET /api/schema/shredder); --candidate
+                                                       stores it beside live without changing a shred
+  shredder promote <endpoint-id> <version> --yes       Make a version live: ship a candidate, or roll back
   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

package/lib/commands/arena.mjs

@@ -197,11 +197,17 @@ export const ARGS = {
 	get_arena_file: {
 		arena_id: { positional: 0, label: "arena-id", required: true },
 	},
+	// Live unless --candidate: a candidate changes nothing until `arena promote` ships it.
 	save_arena_file: {
 		arena_id: { positional: 0, label: "arena-id", required: true },
 		file: { value: (flags) => readJsonFileFlag(flags, "file") },
 		patch: { value: (flags) => readJsonObjectFlag(flags, "patch") },
 		note: "note",
+		status: { value: (flags) => (flags.candidate === true ? "candidate" : undefined) },
+	},
+	promote_arena_version: {
+		arena_id: { positional: 0, label: "arena-id", required: true },
+		version: { value: (_flags, positionals) => positiveInt(positionals[1], "version") },
 	},
 	list_arena_versions: {
 		arena_id: { positional: 0, label: "arena-id", required: true },
@@ -255,13 +261,15 @@ export async function cmdArena(ctx) {
 			return arenaFile(rest);
 		case "versions":
 			return arenaTool(rest, "list_arena_versions");
+		case "promote":
+			return arenaPromote(rest);
 		case "pin":
 			return arenaTool(rest, "pin_arena_version");
 		case "offer":
 			return rest.flags.accept === true ? arenaTool(rest, "accept_arena_offer") : arenaOffer(rest);
 		default:
 			throw new CliError(
-				`Unknown arena subcommand: ${sub ?? "(none)"}. Try: run, run-status, runs, latest, direction, cancel, balance, list, endpoint, file, versions, pin, offer, roles, role`
+				`Unknown arena subcommand: ${sub ?? "(none)"}. Try: run, run-status, runs, latest, direction, cancel, balance, list, endpoint, file, promote, versions, pin, offer, roles, role`
 			);
 	}
 }
@@ -450,7 +458,13 @@ async function arenaFile(ctx) {
 		"save_arena_file",
 		argsFromFlags(ARGS.save_arena_file, flags, ctx.positionals)
 	);
-	ok(ctx, `Saved ${toolField(result, "version")?.label ?? "a new version"}; the arena runs it from now on.`);
+	const saved = toolField(result, "saved");
+	ok(
+		ctx,
+		saved?.status === "candidate"
+			? `Saved ${saved.label} as a candidate; ship it: ${ctx.bin} arena promote ${ctx.positionals[0]} ${saved.version} --yes`
+			: `Saved ${saved?.label ?? toolField(result, "version")?.label ?? "a new version"}; the arena runs it from now on.`
+	);
 	printResult(io, flags, result);
 	return 0;
 }
@@ -520,3 +534,30 @@ async function arenaEndpoint(ctx) {
 	}
 	throw new CliError(`Unknown arena endpoint action: ${action ?? "(none)"}. Try: create, update, delete, config`);
 }
+
+function positiveInt(raw, label) {
+	if (raw === undefined) throw new CliError(`Missing required <${label}>`);
+	const n = Number(raw);
+	if (!Number.isInteger(n) || n < 1) throw new CliError(`<${label}> must be a positive whole number (got "${raw}")`);
+	return n;
+}
+
+/** `arena promote <arena-id> <version> --yes` — make a version live: ship a candidate, or roll back. */
+async function arenaPromote(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.promote_arena_version, flags, positionals);
+	if (!flags.yes) {
+		io.error(
+			`Every run of this arena will use version ${args.version} from its next call. Re-run with --yes to confirm: ${ctx.bin} arena promote ${args.arena_id} ${args.version} --yes`
+		);
+		return 1;
+	}
+	const result = await client.callTool("promote_arena_version", args);
+	const previous = toolField(result, "previous_live");
+	ok(
+		ctx,
+		`Version ${args.version} is live.${previous ? ` To undo: ${ctx.bin} arena promote ${args.arena_id} ${previous} --yes` : ""}`
+	);
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/collection.mjs

@@ -87,6 +87,22 @@ export const ARGS = {
 		rebuild: { flag: "no-rebuild", type: "bool", invert: true },
 		schedule_for: { flag: "at" },
 	},
+	queue_suggestion: {
+		suggestion_id: { positional: 0, label: "suggestion-id", required: true },
+	},
+	add_headline: {
+		collection_id: { flag: "collection", required: true },
+		headline: { positional: 0, label: "headline", required: true },
+		queue: { flag: "queue", type: "bool" },
+	},
+	update_suggestion: {
+		suggestion_id: { positional: 0, label: "suggestion-id", required: true },
+		status: {
+			value: (flags) =>
+				flags.dismiss ? "dismissed" : flags.later ? "backlog" : flags.restore ? "suggested" : undefined,
+		},
+		headline: { flag: "headline" },
+	},
 	get_collection_run: {
 		run_id: { positional: 0, label: "run-id", required: true },
 	},
@@ -143,6 +159,12 @@ export async function cmdCollection(ctx) {
 			return collectionDelete(rest);
 		case "run":
 			return collectionRun(rest);
+		case "queue":
+			return collectionQueue(rest);
+		case "headline":
+			return collectionHeadline(rest);
+		case "add":
+			return collectionAdd(rest);
 		case "run-status":
 		case "status":
 			return collectionRunStatus(rest);
@@ -160,7 +182,7 @@ export async function cmdCollection(ctx) {
 			return collectionLinks(rest);
 		default:
 			throw new CliError(
-				`Unknown collection subcommand: ${sub ?? "(none)"}. Try: list, overview, new, config, delete, run, run-status, runs, approve, cancel, inventory, links`
+				`Unknown collection subcommand: ${sub ?? "(none)"}. Try: list, overview, new, config, delete, run, add, queue, headline, run-status, runs, approve, cancel, inventory, links`
 			);
 	}
 }
@@ -266,6 +288,60 @@ async function collectionRun(ctx) {
 	return 0;
 }
 
+// `collection headline <suggestion-id> [--dismiss | --later | --restore] [--headline "…"]` —
+// the app's Dismiss and Edit on a suggested headline (update_suggestion).
+async function collectionHeadline(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.update_suggestion, ["dismiss", "later", "restore"]);
+	const result = await client.callTool(
+		"update_suggestion",
+		argsFromFlags(ARGS.update_suggestion, flags, ctx.positionals)
+	);
+	ok(ctx, "Headline updated.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+// `collection add "<headline>" --collection <id> [--queue]` — the letterbase page's New post: a
+// headline you wrote joins Up next, or with --queue takes the next slot (a draft, planner off).
+async function collectionAdd(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("add_headline", argsFromFlags(ARGS.add_headline, flags, ctx.positionals));
+	const queued = toolField(result, "queued");
+	ok(
+		ctx,
+		!queued
+			? "Added to Up next."
+			: queued.via === "slot"
+				? `Queued for ${queued.scheduled_for ?? "?"} (run ${queued.run_id ?? "?"}).`
+				: `The Planner is off: drafted as post ${queued.article?.id ?? "?"}.`
+	);
+	printResult(io, flags, result);
+	return 0;
+}
+
+// `collection queue <suggestion-id>` — the app's queue button: the Planner's next slot when
+// it is on (a run that writes on the slot's lead time), else a draft to write by hand.
+async function collectionQueue(ctx) {
+	const { client, flags, io, bin } = ctx;
+	const result = await client.callTool(
+		"queue_suggestion",
+		argsFromFlags(ARGS.queue_suggestion, flags, ctx.positionals)
+	);
+	const via = toolField(result, "via");
+	if (via === "slot") {
+		const runId = toolField(result, "run_id");
+		ok(
+			ctx,
+			`Queued on the schedule for ${toolField(result, "scheduled_for") ?? "?"} (run ${runId ?? "?"}). Follow it with: ${bin} collection run-status ${runId ?? "<run-id>"}`
+		);
+	} else {
+		ok(ctx, `The Planner is off: drafted as post ${toolField(result, "article")?.id ?? "?"}.`);
+	}
+	printResult(io, flags, result);
+	return 0;
+}
+
 async function collectionRunStatus(ctx) {
 	const result = await ctx.client.callTool(
 		"get_collection_run",

package/lib/commands/kernel.mjs

@@ -18,6 +18,7 @@
 // unless you tell it not to.
 
 import { readFileSync } from "node:fs";
+import { basename } from "node:path";
 import { CliError } from "../client.mjs";
 import {
 	flagStr,
@@ -241,8 +242,25 @@ export const ARGS = {
 		source_kernel_id: { positional: 0, label: "source-kernel-id", required: true },
 		name: "name",
 	},
+	// `--name` names the new kernel (over the file's own name); `--from` starts from a kernel you can
+	// see; `--skill SKILL.md` makes one from your own writing instructions.
 	create_kernel: {
-		file: { value: (flags) => readJsonFileFlag(flags, "file") },
+		file: {
+			value: (flags) => {
+				const file = readJsonFileFlag(flags, "file");
+				const name = flagStr(flags.name);
+				if (name === undefined) return file;
+				return { ...(file ?? {}), name };
+			},
+		},
+		from: "from",
+		skill: { value: (flags) => readTextFileFlag(flags, "skill") },
+		skill_filename: {
+			value: (flags) => {
+				const path = flagStr(flags.skill);
+				return path === undefined ? undefined : basename(path);
+			},
+		},
 	},
 	get_org_writing_kernel: {},
 	set_org_writing_kernel: {
@@ -767,15 +785,28 @@ async function kernelFork(ctx) {
 	return 0;
 }
 
-/** `kernel create --file kernel.json` — bring your own: a kernel made from a file (a name and a voice is enough). */
+/**
+ * `kernel create` — a kernel your org owns, from one of three starts (combinable):
+ *   --file kernel.json          a kernel file (a name and a voice is enough)
+ *   --from <kernel-id|name>     a kernel you can see: your current one for a new kernel, any other to fork
+ *   --skill SKILL.md            your own writing instructions, over --from or else your current kernel
+ * `--name` names it.
+ */
 async function kernelCreate(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	if (flagStr(flags.file) === undefined) {
-		throw new CliError('Provide the kernel file with --file <path> (as short as {"name": "…", "voice": "…"}).');
+	if (flagStr(flags.file) === undefined && flagStr(flags.from) === undefined && flagStr(flags.skill) === undefined) {
+		throw new CliError(
+			'Provide --file <path> (as short as {"name": "…", "voice": "…"}), --from <kernel-id|name> or --skill <SKILL.md>.'
+		);
 	}
 	const result = await client.callTool("create_kernel", argsFromFlags(ARGS.create_kernel, flags, positionals));
 	const kernel = toolField(result, "kernel");
-	if (kernel?.id) ok(ctx, `Created "${kernel.name}" (${kernel.id}), version 1, live.`);
+	const basedOn = toolField(result, "based_on");
+	if (kernel?.id)
+		ok(
+			ctx,
+			`Created "${kernel.name}" (${kernel.id}), version 1, live${basedOn ? `, from ${basedOn.name} v${basedOn.version}` : ""}.`
+		);
 	printResult(io, flags, result);
 	return 0;
 }

package/lib/commands/org.mjs

@@ -25,6 +25,7 @@ export const ARGS = {
 		allow: { flag: "allow", type: "list" },
 		confirm: { flag: "confirm" },
 	},
+	describe_org_config_fields: {},
 	get_org_config_source: {},
 	list_integrations: {},
 	get_linear_connection: {},
@@ -63,11 +64,13 @@ export async function cmdOrg(ctx) {
 			return orgGit(rest);
 		case "integrations":
 			return orgIntegrations(rest);
+		case "fields":
+			return orgFields(rest);
 		case "linear":
 			return orgLinear(rest);
 		default:
 			throw new CliError(
-				`Unknown org subcommand: ${sub ?? "(none)"}. Try: export, join, diff, apply, git, integrations, linear`
+				`Unknown org subcommand: ${sub ?? "(none)"}. Try: export, join, diff, apply, git, integrations, linear, fields`
 			);
 	}
 }
@@ -84,6 +87,24 @@ async function orgIntegrations(ctx) {
 	return 0;
 }
 
+/** `org fields [section]`: what each setting in the bundle means (describe_org_config_fields). */
+async function orgFields(ctx) {
+	const { client, flags, io, positionals } = ctx;
+	refuseUnknownFlags(ctx, {}, []);
+	const section = positionals[0];
+	const result = await client.callTool("describe_org_config_fields", {});
+	printResult(io, flags, result, (r) =>
+		r.fields
+			.filter((f) => !section || f.section === section)
+			.map(
+				(f) =>
+					`${f.section}  ${f.path}  ${f.label}${f.readOnly ? "  (read-only)" : ""}${f.gate ? `  [${f.gate}]` : ""}`
+			)
+			.join("\n")
+	);
+	return 0;
+}
+
 /**
  * `org linear` — where Letter files Linear issues (connecting is OAuth, in Settings):
  *   org linear                                   the connection (get_linear_connection)

package/lib/commands/phantom.mjs

@@ -42,6 +42,10 @@ function readJsonObjectFlag(flags, name) {
 	}
 	return readJsonFileFlag(flags, `${name}-file`);
 }
+/** `--<name> none` → null (clear it); otherwise the JSON object, inline or from `--<name>-file`. */
+function readJsonObjectOrNone(flags, name) {
+	return flagStr(flags[name]) === "none" ? null : readJsonObjectFlag(flags, name);
+}
 function stripScheme(domain) {
 	return String(domain)
 		.replace(/^https?:\/\//i, "")
@@ -79,6 +83,11 @@ export const ARGS = {
 					value: (flags) =>
 						flags.layout === undefined ? undefined : flags.layout === "none" ? null : String(flags.layout),
 				},
+				// The site's palette and fonts, stock covers ('{"enabled":true}'), each `none` to clear;
+				// a logo pick ('{"spec":{"archetype":"geometric","variantId":"…"}}') to compose.
+				style: { value: (flags) => readJsonObjectOrNone(flags, "style") },
+				stock_cover: { value: (flags) => readJsonObjectOrNone(flags, "stock-cover") },
+				logo: { value: (flags) => readJsonObjectFlag(flags, "logo") },
 				maverick_enabled: { flag: "maverick", type: "bool", negate: "no-maverick" },
 				// `--maverick-customer-id none` clears it (identification back to pending).
 				maverick_customer_id: {

package/lib/commands/repo.mjs

@@ -144,7 +144,10 @@ const ARGS = {
 		status: { flag: "status", enum: ["running", "succeeded", "no_changes", "failed", "cancelled", "sent"] },
 		limit: { flag: "limit", type: "num" },
 		audit_id: "audit",
-		source_kind: { flag: "source", enum: ["site_audit_issue", "site_quick_check", "letterprove_install"] },
+		source_kind: {
+			flag: "source",
+			enum: ["site_audit_issue", "site_quick_check", "letterprove_install", "collection_publish"],
+		},
 		site_host: "site",
 	},
 	list_github_app_repos: {},

package/lib/commands/series.mjs

@@ -2,10 +2,69 @@
 // point beside topic clusters, hierarchy revamp D/G). A series is a coverage
 // obligation: "content that looks like this", one post per declared item; the
 // planner queue writes the gaps and backfill reconstructs what existing posts
-// already fulfill.
+// already fulfill. It is an automation on the collection it writes into
+// (docs/architecture/content-databases.md): "a comparison post every 7 days" is
+// a series with a comparison template and --every-days 7.
 
 import { CliError } from "../client.mjs";
-import { compact, flagStr, ok, printResult, requireFlag, requirePositional } from "./shared.mjs";
+import { argsFromFlags, compact, flagStr, ok, printResult, refuseUnknownFlags, requirePositional } from "./shared.mjs";
+
+/** `--coverage a,b,c` (or `--templates a,b`) → a list; absent → undefined. */
+const commaList = (name) => (flags) => {
+	const v = flagStr(flags[name]);
+	return v === undefined
+		? undefined
+		: v
+				.split(",")
+				.map((c) => c.trim())
+				.filter(Boolean);
+};
+
+/** `--every-days 7` → 7; `--every-days default` → null (the default pace, 7). */
+const everyDays = (flags) => {
+	const v = flagStr(flags["every-days"]);
+	if (v === undefined) return undefined;
+	if (v === "default") return null;
+	const n = Number(v);
+	if (!Number.isInteger(n) || n < 1) throw new CliError(`--every-days must be a whole number of days or "default"`);
+	return n;
+};
+
+/**
+ * How every command in this file sources its tool inputs — see `argsFromFlags` in
+ * shared.mjs and `scripts/parity-check.ts`, which compares these keys against each tool's
+ * published input schema.
+ */
+export const ARGS = {
+	create_series: {
+		name: { flag: "name", required: true },
+		description: { flag: "description" },
+		collection_id: { flag: "collection" },
+		template_key: { flag: "template" },
+		template_keys: { value: commaList("templates") },
+		coverage: { value: commaList("coverage") },
+		purpose: { flag: "purpose" },
+		every_days: { value: everyDays },
+		paused: { flag: "paused", type: "bool" },
+	},
+	update_series: {
+		series_id: { positional: 0, label: "series-id", required: true },
+		name: { flag: "name" },
+		description: { flag: "description" },
+		template_key: { flag: "template" },
+		template_keys: { value: commaList("templates") },
+		coverage: { value: commaList("coverage") },
+		purpose: { flag: "purpose" },
+		every_days: { value: everyDays },
+		paused: { flag: "pause", type: "bool", negate: "resume" },
+		// `--retire` is the delete (members keep their history). `--status` is a global value-less flag.
+		status: { value: (flags) => (flags.retire === true ? "retired" : undefined) },
+	},
+	queue_series_next: {
+		series_id: { positional: 0, label: "series-id", required: true },
+		collection_id: { flag: "collection", required: true },
+	},
+};
 
 export async function cmdSeries(ctx) {
 	const sub = ctx.positionals[0];
@@ -15,10 +74,16 @@ export async function cmdSeries(ctx) {
 			return seriesList(rest);
 		case "create":
 			return seriesCreate(rest);
+		case "update":
+			return seriesUpdate(rest);
 		case "backfill":
 			return seriesBackfill(rest);
+		case "queue":
+			return seriesQueue(rest);
 		default:
-			throw new CliError(`Unknown series subcommand: ${sub ?? "(none)"}. Try: list, create, backfill`);
+			throw new CliError(
+				`Unknown series subcommand: ${sub ?? "(none)"}. Try: list, create, update, queue, backfill`
+			);
 	}
 }
 
@@ -45,25 +110,41 @@ async function seriesList(ctx) {
 
 async function seriesCreate(ctx) {
 	const { client, flags, io } = ctx;
-	const coverage = flagStr(flags.coverage);
-	const args = compact({
-		name: requireFlag(flags, "name"),
-		description: requireFlag(flags, "description"),
-		collection_id: flagStr(flags.collection),
-		template_key: flagStr(flags.template),
-		coverage: coverage
-			? coverage
-					.split(",")
-					.map((c) => c.trim())
-					.filter(Boolean)
-			: undefined,
-	});
-	const result = await client.callTool("create_series", args);
+	refuseUnknownFlags(ctx, ARGS.create_series);
+	const result = await client.callTool("create_series", argsFromFlags(ARGS.create_series, flags, ctx.positionals));
 	ok(ctx, "Series created — the queue starts covering its items.");
 	printResult(io, flags, result);
 	return 0;
 }
 
+async function seriesUpdate(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.update_series);
+	const args = argsFromFlags(ARGS.update_series, flags, ctx.positionals);
+	if (Object.keys(args).length < 2) {
+		throw new CliError(
+			"Nothing to update. Pass --every-days, --templates, --purpose, --description, --name, --coverage, --pause/--resume or --retire."
+		);
+	}
+	const result = await client.callTool("update_series", args);
+	ok(ctx, "Series updated.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+/** `series queue <series-id> --collection <id>`: its next installment, now (queue_series_next). */
+async function seriesQueue(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.queue_series_next);
+	const result = await client.callTool(
+		"queue_series_next",
+		argsFromFlags(ARGS.queue_series_next, flags, ctx.positionals)
+	);
+	ok(ctx, `Queued "${result?.headline ?? "the next installment"}".`);
+	printResult(io, flags, result);
+	return 0;
+}
+
 async function seriesBackfill(ctx) {
 	const { client, flags, io } = ctx;
 	const args = compact({

package/lib/commands/shredder.mjs

@@ -109,11 +109,17 @@ export const ARGS = {
 	get_shredder_file: {
 		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
 	},
+	// Live unless --candidate: a candidate changes nothing until `shredder promote` ships it.
 	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",
+		status: { value: (flags) => (flags.candidate === true ? "candidate" : undefined) },
+	},
+	promote_shredder_version: {
+		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
+		version: { value: (_flags, positionals) => positiveInt(positionals[1], "version") },
 	},
 	list_shredder_versions: {
 		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
@@ -163,6 +169,8 @@ export async function cmdShredder(ctx) {
 			return shredderFile(rest);
 		case "versions":
 			return shredderTool(rest, "list_shredder_versions");
+		case "promote":
+			return shredderPromote(rest);
 		case "pin":
 			return shredderTool(rest, "pin_shredder_version");
 		case "offer":
@@ -171,7 +179,7 @@ export async function cmdShredder(ctx) {
 			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, file, versions, pin, offer, families`
+				`Unknown shredder subcommand: ${sub ?? "(none)"}. Try: list, create, delete, endpoint, run, job, runs, balance, file, promote, versions, pin, offer, families`
 			);
 	}
 }
@@ -366,9 +374,12 @@ async function shredderFile(ctx) {
 		"save_shredder_file",
 		argsFromFlags(ARGS.save_shredder_file, flags, ctx.positionals)
 	);
+	const saved = toolField(result, "saved");
 	ok(
 		ctx,
-		`Saved ${toolField(result, "version")?.label ?? "a new version"}; the endpoint shreds with it from now on.`
+		saved?.status === "candidate"
+			? `Saved ${saved.label} as a candidate; ship it: ${ctx.bin} shredder promote ${ctx.positionals[0]} ${saved.version} --yes`
+			: `Saved ${saved?.label ?? toolField(result, "version")?.label ?? "a new version"}; the endpoint shreds with it from now on.`
 	);
 	printResult(io, flags, result);
 	return 0;
@@ -393,3 +404,30 @@ async function shredderTool(ctx, tool) {
 	printResult(ctx.io, ctx.flags, result);
 	return 0;
 }
+
+function positiveInt(raw, label) {
+	if (raw === undefined) throw new CliError(`Missing required <${label}>`);
+	const n = Number(raw);
+	if (!Number.isInteger(n) || n < 1) throw new CliError(`<${label}> must be a positive whole number (got "${raw}")`);
+	return n;
+}
+
+/** `shredder promote <endpoint-id> <version> --yes` — make a version live: ship a candidate, or roll back. */
+async function shredderPromote(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.promote_shredder_version, flags, positionals);
+	if (!flags.yes) {
+		io.error(
+			`Every shred through this endpoint will use version ${args.version} from its next call. Re-run with --yes to confirm: ${ctx.bin} shredder promote ${args.endpoint_id} ${args.version} --yes`
+		);
+		return 1;
+	}
+	const result = await client.callTool("promote_shredder_version", args);
+	const previous = toolField(result, "previous_live");
+	ok(
+		ctx,
+		`Version ${args.version} is live.${previous ? ` To undo: ${ctx.bin} shredder promote ${args.endpoint_id} ${previous} --yes` : ""}`
+	);
+	printResult(io, flags, result);
+	return 0;
+}

package/package.json

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