@letterstory/cli 0.36.0 → 0.37.0

package/README.md

@@ -324,6 +324,29 @@ letterstory admin ask "which clients published nothing in the last 30 days?" --s
 This is the headless half of `/superadmin/ask` — same function, same schema — so a
 long-running agent can watch the fleet on a schedule without a browser.
 
+### Staff: kernel experiments
+
+```bash
+# Needs a STAFF key with the tuning:experiment capability. A key always acts as an
+# agent: it can propose, plan, note, spend and conclude, never approve a plan.
+export LETTERSTORY_STAFF_API_KEY=<your staff key with tuning:experiment>
+
+letterstory admin tuning-context --q "colons"          # what the agent knows (JSON)
+letterstory admin experiments list --q colons          # what we've tried
+letterstory admin experiments new "We use too many colons" --as "claude-code"
+letterstory admin experiments update <id> --plan-file plan.json --budget 120
+# ...a person approves the plan in Kernel Tuning -> Experiments...
+letterstory admin experiments spend <id> 54
+letterstory admin tuning-import lab/results/colons/publish/<brief>.json --experiment <id>
+letterstory admin experiments conclude <id> --decision drop \
+  --conclusion "Colons fell 60%; P(machine) did not move; quality held." \
+  --evidence lab:"kernels lab/results/colons/report.md"
+```
+
+The ledger behind Kernel Tuning's Experiments tab
+(docs/architecture/kernel-experiment-agent.md): every question asked of the kernels,
+how it was tested, and what we learned and why.
+
 ### Propose, then onboard a phantom
 
 The Fleet wizard's Plan and Name screens as two commands: pick the beat, then the name,
@@ -522,6 +545,22 @@ letterstory templates update <template-id> --angle "…"   # unset fields keep t
 letterstory templates delete <template-id> --yes   # bound seers fall back to defaults
 ```
 
+Primitive compositions (a named bundle of kernel/shredder/template/seer references —
+`docs/formats/compositions.md`; not a primitive, no endpoint or run. Needs
+`composition:read` / `composition:write`):
+
+```bash
+letterstory compositions list
+letterstory compositions create --name "Regulation-watch site kit" \
+  --content '{"kernel_family":"Cedar","shred":true,"template_key":"tmpl_howto"}' \
+  --phantom '{"theme":"gazette"}' \
+  --seer '{"name":"AI regulation watch","provider":"regulation_change","mode":"auto","config":{"query":"AI regulation"}}'
+letterstory compositions resolve comp_9f1a2b3c4d5e     # preview, read-only — costs nothing
+letterstory compositions update <composition-id> --clear-seer
+letterstory compositions delete <composition-id> --yes  # non-destructive to phantoms already built from it
+letterstory phantom create --name "EU AI Act Weekly" --composition '{"key":"comp_9f1a2b3c4d5e"}'
+```
+
 ## Cover images
 
 Which image model draws a post's cover is a CLI decision, not a UI-only one. `variants`

package/lib/cli.mjs

@@ -37,6 +37,7 @@ import {
 	cmdOnboard,
 	cmdSeers,
 	cmdTemplates,
+	cmdCompositions,
 	cmdShredder,
 	cmdLede,
 	cmdLandings,
@@ -46,7 +47,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.36.0";
+export const VERSION = "0.37.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.
@@ -505,6 +506,24 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        read-only SQL across every org; --sql prints
                                                        the queries behind the answer. Needs the
                                                        fleet:query capability on the staff key.
+  admin experiments list [--q colons] [--status proposed] | show <id>
+          | new "<question>" [--hypothesis …] [--plan-file p.json] [--tags a,b] [--as "<agent>"]
+          | update <id> [--plan-file …] [--result-file …] [--evidence kind:ref,…] [--budget N]
+          | note|started <id> "<text>" | spend <id> <runs>
+          | conclude <id> --decision ship|drop|follow-up|inconclusive --conclusion "…" [--evidence …]
+          | abandon <id> --reason "…"
+                                                       The kernel experiment ledger: what we tried,
+                                                       how, what it found and why. Approving a plan
+                                                       stays with a signed-in person. Needs the
+                                                       tuning:experiment capability.
+  admin tuning-import <brief-results.json> [--experiment <id>]
+                                                       One brief's kernels lab results as a console
+                                                       session (a trial per arm), linked to its
+                                                       ledger entry. Written by \`npm run lab --
+                                                       publish\` in the kernels repo.
+  admin tuning-context [--q "<question>"]              The experiment agent's context pack (JSON):
+                                                       the pipeline as deployed, levers, measures,
+                                                       goals, related history.
   admin create-org --domain <bare-domain> [--name "Acme"] [--test] [--no-key]
           [--key-name N] [--capabilities a,b] [--onboard] [--watch] [+ the onboard domain flags]
                                                        The key exchange: create the client org from
@@ -564,6 +583,26 @@ Content templates (compose structures seers bind via config.template_key):
       for coverage in your own words and lets the engine pick the shape.
   templates delete <template-id> --yes
 
+Primitive compositions (named bundles of kernel/shredder/template/seer; not a primitive —
+no endpoint, no run. Applied on phantom create --composition '{"key":"..."}'):
+  compositions list                                     Org's compositions, by key
+  compositions show <composition-id>
+  compositions create --name <n> [--description <text>]
+      [--content '<json>'|--content-file <path>]        The collection's own content
+                                                       section (kernel_family, shred,
+                                                       shredder_endpoint_id, template_key,
+                                                       mention_degree, cover, visuals, verify).
+      [--phantom '<json>'|--phantom-file <path>]        Phantom-hosting defaults ({theme}).
+      [--seer '<json>'|--seer-file <path>]              Optional — the same shape
+                                                       'seers create' takes, minus
+                                                       collection/org (filled in once
+                                                       the phantom's collection exists).
+  compositions update <composition-id> [--name] [--description]
+      [--content ...] [--phantom ...] [--seer '<json>'|--seer-file <path>|--clear-seer]
+  compositions delete <composition-id> --yes
+  compositions resolve <composition-key>                Preview what create_phantom would
+                                                       merge in — read-only, costs nothing.
+
 Shredder (diversify content produced outside Letterstory; structure preserved):
   shredder list                                        Your shredder endpoints + run counts
   shredder create --name <n>                           New endpoint (returns a callable public id)
@@ -696,6 +735,7 @@ const CLIENT_COMMANDS = {
 	"phantom-onboard": cmdOnboard,
 	seers: cmdSeers,
 	templates: cmdTemplates,
+	compositions: cmdCompositions,
 	shredder: cmdShredder,
 	lede: cmdLede,
 	ledes: cmdLede,

package/lib/commands/admin.mjs

@@ -4,6 +4,9 @@
 // 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 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)
 //   admin create-org --domain acme.com [--name "Acme"] [--test] [--no-key] [--key-name N]
 //                    [--capabilities a,b] [--onboard] [--about "…"] [--sitemap <url>]
 //                    [--cms <provider>] [--posts N] [--seers suggest|skip] [--no-visuals]
@@ -26,6 +29,7 @@
 // The staff key comes from --staff-key or LETTERSTORY_STAFF_API_KEY; the base URL from the
 // usual --url / LETTERSTORY_API_URL / config resolution.
 
+import { readFileSync } from "node:fs";
 import { CliError, LetterstoryClient } from "../client.mjs";
 import { flagStr, flagNum, flagBool, flagList, printResult, compact, ok } from "./shared.mjs";
 import { watchDomainJob } from "./onboard.mjs";
@@ -46,12 +50,17 @@ function staffKeyFrom(flags) {
 
 /** POST a superadmin route with the staff key; surfaces the server's error text on non-2xx. */
 async function staffPost(ctx, path, body) {
+	return staffRequest(ctx, "POST", path, body);
+}
+
+/** Any method against a superadmin route with the staff key. */
+async function staffRequest(ctx, method, path, body) {
 	const { client, flags } = ctx;
 	const url = `${client.url}${path}`;
 	const res = await client.fetch(url, {
-		method: "POST",
+		method,
 		headers: { "content-type": "application/json", "x-staff-api-key": staffKeyFrom(flags) },
-		body: JSON.stringify(body),
+		...(body === undefined ? {} : { body: JSON.stringify(body) }),
 	});
 	let payload = null;
 	try {
@@ -220,11 +229,195 @@ async function cmdAdminAsk(ctx) {
 	}
 }
 
+/* ------------------------------------------------------------ kernel experiments */
+
+const EXPERIMENTS = "/api/superadmin/tuning/experiments";
+
+/** `--as "<agent name>"` records the actor as that agent; a staff key always acts as an agent. */
+function actorFrom(flags) {
+	const as = flagStr(flags.as);
+	return as ? { kind: "agent", label: as } : undefined;
+}
+
+/** A JSON object from `--<name>-file <path>` (or `-` for stdin is not supported: pass a file). */
+function jsonFile(flags, name) {
+	const path = flagStr(flags[`${name}-file`]);
+	if (!path) return undefined;
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		throw new CliError(`--${name}-file ${path}: ${err.message}`);
+	}
+}
+
+/** `--evidence kind:ref[,kind:ref…]`, e.g. `lab:kernels lab/results/colons/report.md,session:<uuid>`. */
+function evidenceFrom(flags) {
+	const items = flagList(flags.evidence);
+	if (!items?.length) return undefined;
+	return items.map((item) => {
+		const at = item.indexOf(":");
+		if (at < 1) throw new CliError(`--evidence items are kind:ref, got "${item}"`);
+		return { kind: item.slice(0, at), ref: item.slice(at + 1) };
+	});
+}
+
+function experimentLine(e) {
+	const decision = e.decision ? ` → ${e.decision}` : "";
+	return `${e.id}  [${e.status}${decision}]  ${e.question}${e.gist ? `\n    ${e.gist}` : ""}`;
+}
+
+/**
+ * `admin experiments …` — the experiment ledger (docs/architecture/kernel-experiment-agent.md),
+ * the headless half of the tuning console's Experiments tab. Needs `tuning:experiment` on the key.
+ */
+async function cmdAdminExperiments(ctx) {
+	const [sub, id, ...rest] = ctx.positionals;
+	const { flags, io } = ctx;
+	const json = flagBool(flags.json);
+	const out = (result, line) => (json ? printResult(io, flags, result) : io.log(line(result)));
+	const one = (r) => {
+		const e = r.experiment;
+		const lines = [experimentLine(e)];
+		if (e.restated) lines.push(`  hypothesis: ${e.restated}`);
+		if (e.plan) lines.push(`  plan: ${JSON.stringify(e.plan)}`);
+		lines.push(`  runs: ${e.runsSpent} of ${e.budgetRuns}`);
+		for (const ev of e.events ?? [])
+			lines.push(`  ${ev.at}  ${ev.kind}  ${ev.actorLabel ?? ev.actorKind}${ev.text ? `: ${ev.text}` : ""}`);
+		return lines.join("\n");
+	};
+	switch (sub) {
+		case "list": {
+			const params = new URLSearchParams(
+				compact({ q: flagStr(flags.q), status: flagStr(flags.status), limit: flagStr(flags.limit) })
+			);
+			const result = await staffRequest(ctx, "GET", `${EXPERIMENTS}?${params}`);
+			return out(result, (r) =>
+				r.experiments.length ? r.experiments.map(experimentLine).join("\n") : "(no experiments)"
+			);
+		}
+		case "show":
+			if (!id) throw new CliError("Usage: admin experiments show <id>");
+			return out(await staffRequest(ctx, "GET", `${EXPERIMENTS}/${id}`), one);
+		case "new": {
+			const question = [id, ...rest].filter(Boolean).join(" ").trim();
+			if (question.length < 3)
+				throw new CliError('Usage: admin experiments new "<question>" [--plan-file plan.json] [--tags a,b]');
+			const body = compact({
+				question,
+				restated: flagStr(flags.hypothesis),
+				plan: jsonFile(flags, "plan"),
+				method: flagStr(flags.method),
+				tags: flagList(flags.tags),
+				builds_on: flagList(flags["builds-on"]),
+				evidence: evidenceFrom(flags),
+				actor: actorFrom(flags),
+			});
+			return out(await staffRequest(ctx, "POST", EXPERIMENTS, body), one);
+		}
+		case "update": {
+			if (!id)
+				throw new CliError(
+					"Usage: admin experiments update <id> [--hypothesis …] [--plan-file …] [--result-file …] [--evidence kind:ref,…]"
+				);
+			const body = compact({
+				restated: flagStr(flags.hypothesis),
+				plan: jsonFile(flags, "plan"),
+				measures: jsonFile(flags, "measures"),
+				result: jsonFile(flags, "result"),
+				method: flagStr(flags.method),
+				tags: flagList(flags.tags),
+				budget_runs: flagNum(flags.budget),
+				engine_build: flagStr(flags.build),
+				add_evidence: evidenceFrom(flags),
+				actor: actorFrom(flags),
+			});
+			return out(await staffRequest(ctx, "PATCH", `${EXPERIMENTS}/${id}`, body), one);
+		}
+		case "note":
+		case "started": {
+			const text = rest.join(" ").trim();
+			if (!id || (sub === "note" && !text)) throw new CliError(`Usage: admin experiments ${sub} <id> "<text>"`);
+			const body = compact({ kind: sub, text: text || undefined, actor: actorFrom(flags) });
+			return out(await staffRequest(ctx, "POST", `${EXPERIMENTS}/${id}/events`, body), one);
+		}
+		case "spend": {
+			const runs = Number(rest[0]);
+			if (!id || !Number.isInteger(runs) || runs < 1)
+				throw new CliError("Usage: admin experiments spend <id> <runs> [--text …]");
+			const body = compact({ kind: "spend", runs, text: flagStr(flags.text), actor: actorFrom(flags) });
+			return out(await staffRequest(ctx, "POST", `${EXPERIMENTS}/${id}/events`, body), one);
+		}
+		case "conclude": {
+			const decision = flagStr(flags.decision);
+			const conclusion = flagStr(flags.conclusion);
+			if (!id || !decision || !conclusion)
+				throw new CliError(
+					'Usage: admin experiments conclude <id> --decision ship|drop|follow-up|inconclusive --conclusion "<what we learned and why>" [--evidence kind:ref,…] [--result-file r.json]'
+				);
+			const body = compact({
+				action: "conclude",
+				decision,
+				conclusion,
+				result: jsonFile(flags, "result"),
+				add_evidence: evidenceFrom(flags),
+				actor: actorFrom(flags),
+			});
+			return out(await staffRequest(ctx, "POST", `${EXPERIMENTS}/${id}/decide`, body), one);
+		}
+		case "abandon": {
+			const reason = flagStr(flags.reason);
+			if (!id || !reason) throw new CliError('Usage: admin experiments abandon <id> --reason "<why>"');
+			const body = compact({ action: "abandon", reason, actor: actorFrom(flags) });
+			return out(await staffRequest(ctx, "POST", `${EXPERIMENTS}/${id}/decide`, body), one);
+		}
+		default:
+			throw new CliError(
+				"Usage: admin experiments list|show|new|update|note|started|spend|conclude|abandon (see --help)"
+			);
+	}
+}
+
+/**
+ * `admin tuning-import <file.json>` — one brief's kernels lab results into a console session
+ * (the lab's `publish` writes these files; the body is POST /api/superadmin/tuning/lab-import's).
+ */
+async function cmdAdminTuningImport(ctx) {
+	const path = ctx.positionals[0];
+	if (!path) throw new CliError("Usage: admin tuning-import <brief-results.json> [--experiment <id>]");
+	let body;
+	try {
+		body = JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		throw new CliError(`${path}: ${err.message}`);
+	}
+	const experiment = flagStr(ctx.flags.experiment);
+	if (experiment) body.experiment_id = experiment;
+	const result = await staffRequest(ctx, "POST", "/api/superadmin/tuning/lab-import", body);
+	if (flagBool(ctx.flags.json)) return printResult(ctx.io, ctx.flags, result);
+	ctx.io.log(
+		`${result.trials} trials, ${result.runs} runs → ${ctx.client.url}/superadmin/tuning/${result.sessionId}`
+	);
+}
+
+/** `admin tuning-context [--q "<question>"]` — the experiment agent's context pack, as JSON. */
+async function cmdAdminTuningContext(ctx) {
+	const q = flagStr(ctx.flags.q) || ctx.positionals.join(" ").trim() || undefined;
+	const params = q ? `?${new URLSearchParams({ q })}` : "";
+	printResult(
+		ctx.io,
+		{ ...ctx.flags, json: true },
+		await staffRequest(ctx, "GET", `/api/superadmin/tuning/context${params}`)
+	);
+}
+
 export async function cmdAdmin(ctx) {
 	const sub = ctx.positionals[0];
 	if (sub === "create-org") return cmdAdminCreateOrg({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "ask") return cmdAdminAsk({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "experiments") return cmdAdminExperiments({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "tuning-context") return cmdAdminTuningContext({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "tuning-import") return cmdAdminTuningImport({ ...ctx, positionals: ctx.positionals.slice(1) });
 	throw new CliError(
-		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" (see --help)'
+		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin tuning-context (see --help)'
 	);
 }

package/lib/commands/compositions.mjs

@@ -0,0 +1,193 @@
+// `compositions` — Primitive Compositions, the FORMAT that bundles a kernel, a shredder, a
+// content template and a seer into one named, reusable reference (docs/formats/compositions.md).
+//
+// Not a primitive: no endpoint, no run, no balance. What it has instead of a door is a
+// RESOLUTION — `compositions resolve <key>` — and one consuming door, `phantom create
+// --composition '{"key":"..."}'` (see phantom.mjs), which resolves it exactly once and merges
+// it in. Authoring (list/show/create/update/delete) is CLI/REST parity work only; the mechanism
+// itself shipped with the format.
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import { flagStr, requirePositional, printResult, ok, argsFromFlags } from "./shared.mjs";
+
+function readJsonFileFlag(flags, flag) {
+	const path = flagStr(flags[flag]);
+	if (path === undefined) return undefined;
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new CliError(
+			`Could not read --${flag} ${path}: ${error instanceof Error ? error.message : String(error)}`
+		);
+	}
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new CliError(`--${flag} ${path} is not valid JSON.`);
+	}
+}
+
+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`);
+}
+
+// `--seer '<json>'`/`--seer-file <path>` sets it, `--clear-seer` sends null (the composition
+// stands up no seer), neither leaves it unchanged — same idiom as seers.mjs's clearableValue.
+function seerFromFlags(flags) {
+	if (flags["clear-seer"] === true) return null;
+	return readJsonObjectFlag(flags, "seer");
+}
+
+/**
+ * How this command sources its tool inputs — see `argsFromFlags` in shared.mjs and
+ * `scripts/parity-check.ts`. `content`/`phantom`/`seer` are each a JSON object (the collection
+ * content section, `{theme}`, and a create_seer-shaped spec, respectively) — the same
+ * `--flag '<json>'`/`--flag-file <path>` idiom `phantom create --composition` already uses,
+ * not decomposed field-by-field: they're bundles authored once and read back, not edited a
+ * field at a time from the CLI.
+ */
+export const ARGS = {
+	list_compositions: {},
+	get_composition: {
+		composition_id: { positional: 0, label: "composition-id", required: true },
+	},
+	resolve_composition: {
+		key: { positional: 0, label: "composition-key", required: true },
+	},
+	create_composition: {
+		name: { flag: "name", required: true },
+		description: "description",
+		content: { value: (flags) => readJsonObjectFlag(flags, "content") },
+		phantom: { value: (flags) => readJsonObjectFlag(flags, "phantom") },
+		seer: { value: (flags) => readJsonObjectFlag(flags, "seer") },
+	},
+	update_composition: {
+		composition_id: { positional: 0, label: "composition-id", required: true },
+		name: "name",
+		description: "description",
+		content: { value: (flags) => readJsonObjectFlag(flags, "content") },
+		phantom: { value: (flags) => readJsonObjectFlag(flags, "phantom") },
+		seer: { value: (flags) => seerFromFlags(flags) },
+	},
+	delete_composition: {
+		composition_id: { positional: 0, label: "composition-id", required: true },
+	},
+};
+
+export async function cmdCompositions(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return compositionsList(rest);
+		case "show":
+		case "get":
+			return compositionsShow(rest);
+		case "create":
+		case "new":
+			return compositionsCreate(rest);
+		case "update":
+			return compositionsUpdate(rest);
+		case "delete":
+		case "rm":
+			return compositionsDelete(rest);
+		case "resolve":
+			return compositionsResolve(rest);
+		default:
+			throw new CliError(
+				`Unknown compositions subcommand: ${sub ?? "(none)"}. Try: list, show, create, update, delete, resolve`
+			);
+	}
+}
+
+async function compositionsList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_compositions", {});
+	printResult(io, flags, result, (r) =>
+		(r.compositions ?? []).length
+			? (r.compositions ?? [])
+					.map((c) => `  ${c.key}  ${c.name}${c.seer ? " (+seer)" : ""} — id ${c.id}`)
+					.join("\n")
+			: "No compositions yet."
+	);
+	return 0;
+}
+
+async function compositionsShow(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "composition-id");
+	const result = await client.callTool("get_composition", argsFromFlags(ARGS.get_composition, flags, positionals));
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function compositionsCreate(ctx) {
+	const { client, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.create_composition, flags, []);
+	if (!args.name) throw new CliError("Missing required --name");
+	const result = await client.callTool("create_composition", args);
+	ok(ctx, `Composition created — key ${result.composition?.key}.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function compositionsUpdate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "composition-id");
+	const result = await client.callTool(
+		"update_composition",
+		argsFromFlags(ARGS.update_composition, flags, positionals)
+	);
+	ok(ctx, "Composition updated.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function compositionsDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "composition-id");
+	if (!flags.yes) {
+		throw new CliError(
+			"Non-destructive to phantoms already built from it (their resolved_from_composition becomes a name pointing at nothing). Re-run with --yes to delete."
+		);
+	}
+	const result = await client.callTool(
+		"delete_composition",
+		argsFromFlags(ARGS.delete_composition, flags, positionals)
+	);
+	ok(ctx, "Composition deleted.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+/**
+ * `compositions resolve <key>` — turn a composition into the sections `phantom create
+ * --composition` would merge in. Read-only, costs nothing. Preview a bundle, or build the
+ * sections yourself for a door that doesn't take `composition` directly yet (`collection
+ * config` / `seers create`).
+ */
+async function compositionsResolve(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "composition-key");
+	const result = await client.callTool(
+		"resolve_composition",
+		argsFromFlags(ARGS.resolve_composition, flags, positionals)
+	);
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands.mjs

@@ -23,6 +23,7 @@ export * from "./commands/insights.mjs";
 export * from "./commands/covers.mjs";
 export * from "./commands/arena.mjs";
 export * from "./commands/templates.mjs";
+export * from "./commands/compositions.mjs";
 export * from "./commands/autopen.mjs";
 export * from "./commands/kernel.mjs";
 export * from "./commands/lede.mjs";

package/package.json

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