@letterstory/cli 0.25.6 → 0.27.0

package/README.md

@@ -312,25 +312,34 @@ letterstory series create --name "Secrets, tool by tool" \
 letterstory series backfill <series-id> --collection <uuid>
 ```
 
-## Research and writing kernels
+## Arenas and writing kernels
 
-Two different steps, in this order. The **research agent** reads the live web and writes a
-sourced outline into the post; a **writing kernel** writes the draft from the brief it's
-given and does no retrieval of its own. Both take minutes, so both are start-then-poll:
+Two different steps, in this order. An **arena** — an adversarial cluster of research agents —
+reads the live web and writes a sourced, fact-checked outline (into the post when you pass
+`--article`, otherwise back on the run); a **writing kernel** writes the draft from the brief
+it's given and does no retrieval of its own. Both take minutes, so both are start-then-poll:
 
 ```bash
-# 1. Research the topic and write an outline into the post
-letterstory research start --article <uuid> --topic "payroll solutions" \
-  --url https://example.com/a --must-include "Pricing" --depth fleshed_out
-letterstory research status --article <uuid>       # phases, sources, outline
-letterstory research cancel --article <uuid>
+# 1. Research the topic — hosted on a post (outline written into it) or standalone
+letterstory arena run --article <uuid> --topic "payroll solutions" \
+  --source https://example.com/a --must-include "Pricing" --depth fleshed_out
+letterstory arena run --topic "payroll solutions" --no-wait   # standalone; prints the run id
+letterstory arena run-status <run-id>                  # phases, sources, outline, verification
+letterstory arena cancel <run-id>
+letterstory arena balance                              # arena runs left (direct runs only)
 
 # …with --gate, the run pauses for you to pick the angle:
-letterstory research start --article <uuid> --gate
-letterstory research status --article <uuid>       # status: awaiting_direction + direction_options
-letterstory research direction --article <uuid> --choice 1
-letterstory research direction --article <uuid> --custom "Lead with the hidden costs"
-letterstory research direction --article <uuid> --skip     # let the agent decide
+letterstory arena run --article <uuid> --gate
+letterstory arena run-status <run-id>                  # status: awaiting_direction + direction_options
+letterstory arena direction <run-id> --choice 1
+letterstory arena direction <run-id> --custom "Lead with the hidden costs"
+letterstory arena direction <run-id> --skip            # let the agents decide
+
+# Arenas are callable endpoints with one-file defaults (the org's default arena is "Letterstory"):
+letterstory arena list
+letterstory arena endpoint create --name "Docs research" --defaults '{"depth":"barebones"}'
+letterstory arena endpoint config <arena-id> [--file cfg.json]
+letterstory arena endpoint delete <arena-id> --yes
 
 # 2. Have a kernel write the draft
 letterstory kernel list

package/lib/cli.mjs

@@ -30,7 +30,7 @@ import {
 	cmdOnboarding,
 	cmdSeries,
 	cmdInsights,
-	cmdResearch,
+	cmdArena,
 	cmdAutoPen,
 	cmdCovers,
 	cmdKernel,
@@ -44,7 +44,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.25.6";
+export const VERSION = "0.27.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.
@@ -64,7 +64,7 @@ const BOOLEAN_FLAGS = new Set([
 	"rebuild",
 	"print-key",
 	"stdin",
-	// `covers generate <id> --regenerate` and `research start --gate --article <id>`
+	// `covers generate <id> --regenerate` and `arena run --gate --article <id>`
 	// both put a value-less flag next to a value: without these entries the parser
 	// hands the following token to the flag and the real argument disappears.
 	"regenerate",
@@ -74,6 +74,7 @@ const BOOLEAN_FLAGS = new Set([
 	"no-auto-deploy",
 	"stock-only",
 	"gate",
+	"no-verify",
 	"skip",
 	// `phantom-onboard domain` / `admin create-org --onboard` switches.
 	"watch",
@@ -277,14 +278,25 @@ Strategy & onboarding:
   series create --name <n> --description <d> [--coverage a,b,c] [--collection <uuid>] [--template <key>]
   series backfill <series-id> [--collection <uuid>]    Reconstruct a series from existing posts
 
-Research agent (deep research -> outline written into the post):
-  research start --article <uuid> [--topic <text>] [--url <url> …] [--must-include <text> …]
-                 [--depth barebones|fleshed_out] [--gate]
-                                                        Start a run; takes minutes
-  research status --article <uuid>                      Phases, sources, outline
-  research direction --article <uuid> (--choice <n> | --custom <text> | --skip)
+Arenas (adversarial clusters of research agents -> a sourced, fact-checked outline):
+  arena run --topic <text> [--source <url> …] [--must-include <text> …] [--depth barebones|fleshed_out]
+            [--gate] [--no-verify] [--provider native|exa|youcom|firecrawl] [--mention off|subtle|woven]
+            [--context-file ctx.json] [--block <name> …] [--block-domain <domain> …]
+            [--arena <arena-id>] [--article <uuid>] [--no-wait]
+                                                        Start a run and follow it. --article makes
+                                                        it HOSTED (outline written into that post,
+                                                        its title is the default topic); otherwise
+                                                        everything comes back on the run.
+  arena run-status <run-id>                            Phases, sources, outline, verification
+  arena runs [--arena <id>] [--limit <n>]              Recent runs (origin, caller, verification)
+  arena direction <run-id> (--choice <n> | --custom <text> | --skip)
                                                         Answer the --gate pause
-  research cancel --article <uuid>                      Cancel a run in flight
+  arena cancel <run-id>                                Cancel a run in flight
+  arena balance                                        Arena runs left on this org
+  arena list                                           Your arenas (callable endpoints)
+  arena endpoint create --name <n> [--defaults '<json>'|--defaults-file <path>]
+  arena endpoint config <arena-id> [--file cfg.json]   Print the one-file config, or replace it
+  arena endpoint delete <arena-id> --yes
 
 Auto-Pen (research -> kernel -> Enhance, in one run — and the ONLY path that
 applies a collection's content template; kernel run does not):
@@ -594,7 +606,7 @@ const CLIENT_COMMANDS = {
 	onboarding: cmdOnboarding,
 	series: cmdSeries,
 	insights: cmdInsights,
-	research: cmdResearch,
+	arena: cmdArena,
 	autopen: cmdAutoPen,
 	covers: cmdCovers,
 	kernel: cmdKernel,

package/lib/commands/arena.mjs

@@ -0,0 +1,348 @@
+// `arena` — Arenas, adversarial clusters of research agents, on both of their doors.
+//
+// An arena turns a TOPIC into a sourced, fact-checked outline: gather agents for the topic
+// and for every named subject it finds, a reader, a direction agent proposing competing
+// theses, a synthesis gated on a ledger of sourced figures, and a verifier that argues
+// every claim against the sources and the live web. Minutes long, so `arena run` submits
+// and then follows the run unless you tell it not to (`--no-wait`); `arena run-status`
+// picks it up later. Pass `--article <id>` to make it a HOSTED run (the outline is written
+// into that post — what the post editor's Research panel does); omit it and everything
+// comes back on the run. Every direct run spends one arena run (`arena balance`).
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import {
+	flagStr,
+	flagNum,
+	flagBool,
+	requirePositional,
+	printResult,
+	compact,
+	ok,
+	toolField,
+	followJob,
+	argsFromFlags,
+} from "./shared.mjs";
+
+/** `--<flag> <path>` → the file's parsed JSON, or undefined when the flag is not set. */
+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.`);
+	}
+}
+
+/** `--<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`);
+}
+
+/** The per-run knobs, shared by run_arena and the arena's own defaults. */
+const RUN_OPTIONS = {
+	depth: { flag: "depth", enum: ["barebones", "fleshed_out"] },
+	direction_gate: { flag: "gate", type: "bool" },
+	provider: { flag: "provider", enum: ["native", "exa", "youcom", "firecrawl"] },
+	// --no-verify turns the fact-check off; nothing sent otherwise (the default is on).
+	verify: { value: (flags) => (flags["no-verify"] === true ? false : undefined) },
+	mention_degree: { flag: "mention", enum: ["off", "subtle", "woven"] },
+	// Positioning as data — a file, not flags: `--context-file ctx.json` of
+	// {manifesto, stances[], priority_topics[], avoid_topics[], identity{is[],is_not[],one_liner}}.
+	context: { value: (flags) => readJsonObjectFlag(flags, "context") },
+	blocked_mentions: { flag: "block", type: "list" },
+	blocked_domains: { flag: "block-domain", type: "list" },
+};
+
+/**
+ * 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.
+ */
+/** `--var Name=Value` (repeatable) → `{ Name: "Value" }` for a template's {Variables}. */
+function templateVariablesFromFlags(flags) {
+	const raw = flags.var;
+	if (raw === undefined) return undefined;
+	const list = Array.isArray(raw) ? raw : [raw];
+	const out = {};
+	for (const entry of list) {
+		const text = String(entry);
+		const eq = text.indexOf("=");
+		if (eq <= 0) throw new CliError(`--var must be Name=Value (got "${text}").`);
+		out[text.slice(0, eq).trim()] = text.slice(eq + 1).trim();
+	}
+	return Object.keys(out).length ? out : undefined;
+}
+
+export const ARGS = {
+	run_arena: {
+		arena_id: { flag: "arena" },
+		topic: "topic",
+		source_urls: { flag: "source", type: "list" },
+		must_include: { flag: "must-include", type: "list" },
+		shape: { value: (flags) => readJsonObjectFlag(flags, "shape") },
+		// A TEMPLATE INSTEAD OF LISTING THE SHAPE BY HAND. Resolving one fills both
+		// `must_include` and `shape`; the `constraints` it returns come back on the run, and
+		// passing them to `kernel write --template-constraints` is what stops the same template
+		// being resolved twice into two different sets of section labels.
+		template: {
+			object: {
+				key: { flag: "template" },
+				blocks: { value: (flags) => readJsonFileFlag(flags, "template-blocks") },
+				title: { flag: "title" },
+				variables: { value: (flags) => templateVariablesFromFlags(flags) },
+				constraints: { value: (flags) => readJsonFileFlag(flags, "template-constraints") },
+			},
+		},
+		existing_content: { value: (flags) => flagStr(flags["existing-content"]) },
+		article_id: { flag: "article" },
+		...RUN_OPTIONS,
+	},
+	get_arena_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+	},
+	list_arena_runs: {
+		arena_id: { flag: "arena" },
+		limit: { flag: "limit", type: "num" },
+	},
+	submit_arena_direction: {
+		run_id: { positional: 0, label: "run-id", required: true },
+		choice: { flag: "choice", type: "num" },
+		custom: "custom",
+		skip: { flag: "skip", type: "bool" },
+	},
+	cancel_arena_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+	},
+	get_arena_run_balance: {},
+	list_arenas: {},
+	create_arena: {
+		name: { flag: "name", required: true },
+		defaults: { value: (flags) => readJsonObjectFlag(flags, "defaults") },
+	},
+	delete_arena: {
+		arena_id: { positional: 1, label: "arena-id", required: true },
+	},
+	// The arena's configuration as ONE file: `arena endpoint config <id>` prints it,
+	// `arena endpoint config <id> --file cfg.json` replaces it with the file's document.
+	get_arena_config: {
+		arena_id: { positional: 1, label: "arena-id", required: true },
+	},
+	set_arena_config: {
+		arena_id: { positional: 1, label: "arena-id", required: true },
+		config: { value: (flags) => readJsonFileFlag(flags, "file") },
+	},
+};
+
+export async function cmdArena(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "run":
+		case "start":
+			return arenaRun(rest);
+		case "run-status":
+		case "status":
+			return arenaRunStatus(rest);
+		case "runs":
+			return arenaRuns(rest);
+		case "direction":
+			return arenaDirection(rest);
+		case "cancel":
+			return arenaCancel(rest);
+		case "balance":
+			return arenaBalance(rest);
+		case "list":
+		case "ls":
+		case "endpoints":
+			return arenaList(rest);
+		case "endpoint":
+			return arenaEndpoint(rest);
+		default:
+			throw new CliError(
+				`Unknown arena subcommand: ${sub ?? "(none)"}. Try: run, run-status, runs, direction, cancel, balance, list, endpoint`
+			);
+	}
+}
+
+/** A run takes minutes; this is about feeling alive. */
+const POLL_INTERVAL_MS = 15_000;
+/** Stop following after this; the run keeps going and `run-status` picks it up. */
+const POLL_CEILING_MS = 30 * 60 * 1000;
+
+function isActive(status) {
+	return status === "running";
+}
+
+async function arenaRun(ctx) {
+	const { client, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.run_arena, flags, ctx.positionals);
+	if (args.topic === undefined && args.article_id === undefined) {
+		throw new CliError("Provide --topic <text> (or --article <id> to research a post by its title).");
+	}
+	const result = await client.callTool("run_arena", args);
+	const runId = toolField(result, "run_id");
+	if (!runId) {
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (flags["no-wait"] === true) {
+		ok(ctx, `Run started as ${runId}. Follow it with: ${ctx.bin} arena run-status ${runId}`);
+		printResult(io, flags, result);
+		return 0;
+	}
+
+	ok(ctx, `Run started as ${runId}. Waiting — this keeps running on the server if you stop.`);
+	let lastStatus;
+	const { settled, value: polled } = await followJob(
+		io,
+		async () => {
+			const r = await client.callTool("get_arena_run", { run_id: runId });
+			lastStatus = toolField(r?.run ?? r, "status");
+			return { done: !!lastStatus && !isActive(lastStatus), value: r };
+		},
+		{ intervalMs: POLL_INTERVAL_MS, ceilingMs: POLL_CEILING_MS }
+	);
+
+	if (!settled) {
+		ok(ctx, `Still running after 30 minutes. Follow it with: ${ctx.bin} arena run-status ${runId}`);
+		printResult(io, flags, polled);
+		return 0;
+	}
+	if (lastStatus === "awaiting_direction") {
+		ok(
+			ctx,
+			`Paused for a direction. Answer with: ${ctx.bin} arena direction ${runId} (--choice <n> | --custom <text> | --skip)`
+		);
+		printResult(io, flags, polled);
+		return 0;
+	}
+	ok(ctx, `Run ${lastStatus}.`);
+	// The operator waited for the OUTLINE; print it, not the envelope. --json gets it all.
+	printResult(io, flags, polled, (v) =>
+		typeof v?.run?.outline === "string" ? v.run.outline : JSON.stringify(v, null, 2)
+	);
+	return lastStatus === "done" ? 0 : 1;
+}
+
+async function arenaRunStatus(ctx) {
+	const { client, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.get_arena_run, flags, ctx.positionals);
+	const result = await client.callTool("get_arena_run", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function arenaRuns(ctx) {
+	const { client, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.list_arena_runs, flags, ctx.positionals);
+	const result = await client.callTool("list_arena_runs", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function arenaDirection(ctx) {
+	const { client, flags, io } = ctx;
+	const runId = requirePositional(ctx.positionals, 0, "run-id");
+	const choice = flagNum(flags.choice);
+	const custom = flagStr(flags.custom);
+	const skip = flagBool(flags.skip);
+	const given = [choice !== undefined, custom !== undefined, skip].filter(Boolean).length;
+	if (given !== 1) {
+		throw new CliError("Provide exactly one of --choice <n>, --custom <text>, --skip");
+	}
+	const args = compact({ run_id: runId, choice, custom, skip: skip ? true : undefined });
+	const result = await client.callTool("submit_arena_direction", args);
+	ok(ctx, "Direction recorded; the run resumed into synthesis.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function arenaCancel(ctx) {
+	const { client, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.cancel_arena_run, flags, ctx.positionals);
+	const result = await client.callTool("cancel_arena_run", args);
+	ok(ctx, result?.cancelled ? "Arena run cancelled." : "No run was in flight.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function arenaBalance(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("get_arena_run_balance", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function arenaList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_arenas", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+/**
+ * `arena endpoint create|delete|config` — the arena's own CRUD, and its configuration as
+ * one file (the same document `get_arena_config` returns and `set_arena_config` accepts).
+ */
+async function arenaEndpoint(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const action = positionals[0];
+	if (action === "create" || action === "new") {
+		const args = argsFromFlags(ARGS.create_arena, flags, positionals);
+		const result = await client.callTool("create_arena", args);
+		ok(ctx, `Created arena "${args.name}".`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (action === "delete" || action === "rm") {
+		const id = requirePositional(positionals, 1, "arena-id");
+		if (!flags.yes) {
+			io.error(`Re-run with --yes to confirm: ${ctx.bin} arena endpoint delete ${id} --yes`);
+			return 1;
+		}
+		const result = await client.callTool("delete_arena", argsFromFlags(ARGS.delete_arena, flags, positionals));
+		ok(ctx, "Arena deleted.");
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (action === "config") {
+		const id = requirePositional(positionals, 1, "arena-id");
+		if (flagStr(flags.file) === undefined) {
+			const result = await client.callTool(
+				"get_arena_config",
+				argsFromFlags(ARGS.get_arena_config, flags, positionals)
+			);
+			// The document itself, so `> cfg.json` round-trips into `--file cfg.json`.
+			printResult(io, flags, result, (r) => JSON.stringify(r?.config ?? r, null, 2));
+			return 0;
+		}
+		const args = argsFromFlags(ARGS.set_arena_config, flags, positionals);
+		const result = await client.callTool("set_arena_config", args);
+		ok(ctx, `Replaced the configuration of arena ${id}.`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	throw new CliError(`Unknown arena endpoint action: ${action ?? "(none)"}. Try: create, delete, config`);
+}

package/lib/commands/kernel.mjs

@@ -69,6 +69,21 @@ function readTextFileFlag(flags, flag) {
  * The rest of this module predates the field-level ratchet and is covered by the
  * frozen UNMAPPED_TOOLS list. New commands declare; that list only shrinks.
  */
+/** `--var Name=Value` (repeatable) → `{ Name: "Value" }` for a template's {Variables}. */
+function variablesFromFlags(flags) {
+	const raw = flags.var;
+	if (raw === undefined) return undefined;
+	const list = Array.isArray(raw) ? raw : [raw];
+	const out = {};
+	for (const entry of list) {
+		const text = String(entry);
+		const eq = text.indexOf("=");
+		if (eq <= 0) throw new CliError(`--var must be Name=Value (got "${text}").`);
+		out[text.slice(0, eq).trim()] = text.slice(eq + 1).trim();
+	}
+	return Object.keys(out).length ? out : undefined;
+}
+
 export const ARGS = {
 	// The article-bound door: submit a kernel run INTO an article you already have.
 	submit_kernel_run: {
@@ -109,6 +124,22 @@ export const ARGS = {
 		// field a template resolves to, sent by a caller who has their own.
 		skeleton: { value: (flags) => readJsonFileFlag(flags, "skeleton-file") },
 		brief_json: { value: (flags) => readJsonFileFlag(flags, "brief-json-file") },
+		// A TEMPLATE INSTEAD OF HAND-BUILDING THOSE. `--template <key>` resolves one of your
+		// templates against the material you sent and fills `skeleton`, `target_word_count` and
+		// `brief_json` for this call — and the finished run comes back ASSEMBLED rather than as
+		// the scaffolding the kernel writes. `--template-constraints <path>` passes back the
+		// answer `templates resolve` already gave, so the same template is not resolved twice
+		// (which would relabel the sections the outline planned). `--var Name=Value` fills a
+		// {Variable} the template declares.
+		template: {
+			object: {
+				key: { flag: "template" },
+				blocks: { value: (flags) => readJsonFileFlag(flags, "template-blocks") },
+				title: { flag: "title" },
+				variables: { value: (flags) => variablesFromFlags(flags) },
+				constraints: { value: (flags) => readJsonFileFlag(flags, "template-constraints") },
+			},
+		},
 		max_iterations: { flag: "max-iterations", type: "num" },
 		kernel_version: { flag: "kernel-version", type: "num" },
 		// In-loop shred tuning. Only sent when a flag is set; ignored when no shred runs.

package/lib/commands/seers.mjs

@@ -14,7 +14,7 @@
 
 import { readFileSync, writeFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
-import { flagStr, flagBool, requirePositional, printResult, ok, argsFromFlags } from "./shared.mjs";
+import { flagStr, flagBool, printResult, ok, argsFromFlags } from "./shared.mjs";
 
 // A single-value flag the API clears with an explicit `null` (same idiom as
 // strategy.mjs's clearableList): `--clear-collection` sends null, `--collection <uuid>`
@@ -721,123 +721,3 @@ async function seersApply(ctx) {
 	}
 	return 0;
 }
-
-// --- Templates ---------------------------------------------------------------------
-
-export async function cmdTemplates(ctx) {
-	const sub = ctx.positionals[0];
-	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
-	switch (sub) {
-		case "list":
-		case "ls":
-			return templatesList(rest);
-		case "show":
-		case "get":
-			return templatesShow(rest);
-		case "create":
-		case "new":
-			return templatesCreate(rest);
-		case "update":
-			return templatesUpdate(rest);
-		case "delete":
-		case "rm":
-			return templatesDelete(rest);
-		default:
-			throw new CliError(
-				`Unknown templates subcommand: ${sub ?? "(none)"}. Try: list, show, create, update, delete`
-			);
-	}
-}
-
-async function templatesList(ctx) {
-	const { client, flags, io } = ctx;
-	const result = await client.callTool("list_templates", {});
-	printResult(io, flags, result, (r) => {
-		const custom = (r.templates ?? []).map((t) => `  ${t.key}  ${t.name} — ${t.angle} (id ${t.id})`);
-		const builtIn = (r.built_ins ?? []).map((t) => `  ${t.key}  ${t.name}`);
-		return [
-			custom.length ? "Custom templates:" : "No custom templates yet.",
-			...custom,
-			"",
-			"Built-in templates (read-only):",
-			...builtIn,
-		].join("\n");
-	});
-	return 0;
-}
-
-async function templatesShow(ctx) {
-	const { client, positionals, flags, io } = ctx;
-	const templateId = requirePositional(positionals, 0, "template-id");
-	const result = await client.callTool("get_template", { template_id: templateId });
-	printResult(io, flags, result);
-	return 0;
-}
-
-function templateBlocksFromFlags(flags) {
-	const inline = flagStr(flags.blocks);
-	const file = flagStr(flags["blocks-file"]);
-	if (inline === undefined && file === undefined) return undefined;
-	const raw = inline !== undefined ? inline : readFileOrThrow(file, "--blocks-file");
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (err) {
-		throw new CliError(`--blocks is not valid JSON: ${err.message}`);
-	}
-	if (!Array.isArray(parsed)) throw new CliError("--blocks must be a JSON array of block objects");
-	return parsed;
-}
-
-async function templatesCreate(ctx) {
-	const { client, flags, io } = ctx;
-	const name = flagStr(flags.name);
-	const angle = flagStr(flags.angle);
-	const blocks = templateBlocksFromFlags(flags);
-	if (!name) throw new CliError("Missing required --name");
-	// `--angle` is OPTIONAL, and omitting it is the better answer. It was required here while
-	// the server schema had already made it optional and the app had dropped the field: a
-	// template constrains a post's SHAPE and never says what it is about, so an angle belongs
-	// to the post — which already has one, from its research direction.
-	if (!blocks) throw new CliError("Missing required --blocks '<json>' or --blocks-file <path>");
-	const result = await client.callTool("create_template", { name, blocks, ...(angle ? { angle } : {}) });
-	ok(ctx, `Template created — key ${result.template?.key}.`);
-	printResult(io, flags, result);
-	return 0;
-}
-
-async function templatesUpdate(ctx) {
-	const { client, positionals, flags, io } = ctx;
-	const templateId = requirePositional(positionals, 0, "template-id");
-	const name = flagStr(flags.name);
-	const angle = flagStr(flags.angle);
-	const blocks = templateBlocksFromFlags(flags);
-	// update_template replaces the whole template; fetch current values for any
-	// field the caller didn't pass so a partial edit doesn't blank the rest.
-	let current;
-	if (!name || !angle || !blocks) {
-		const existing = await client.callTool("get_template", { template_id: templateId });
-		current = existing.template;
-	}
-	const result = await client.callTool("update_template", {
-		template_id: templateId,
-		name: name ?? current.name,
-		angle: angle ?? current.angle,
-		blocks: blocks ?? current.blocks,
-	});
-	ok(ctx, "Template updated.");
-	printResult(io, flags, result);
-	return 0;
-}
-
-async function templatesDelete(ctx) {
-	const { client, positionals, flags, io } = ctx;
-	const templateId = requirePositional(positionals, 0, "template-id");
-	if (!flagBool(flags.yes)) {
-		throw new CliError("Seers bound to this template fall back to defaults. Re-run with --yes to delete.");
-	}
-	const result = await client.callTool("delete_template", { template_id: templateId });
-	ok(ctx, "Template deleted.");
-	printResult(io, flags, result);
-	return 0;
-}

package/lib/commands/templates.mjs

@@ -0,0 +1,267 @@
+// `templates` — the Templates FORMAT: authoring it, and the two operations that make it
+// composable.
+//
+// MOVED OUT OF `seers.mjs` (2026-09-18) for the same reason `src/lib/templates/` moved out of
+// `src/lib/seers/`: a template stopped being seer-owned when collections, series and per-article
+// overrides started binding them, and two of the primitives that consume one have nothing to do
+// with seers at all.
+//
+// A template is not a primitive: no endpoint, no run, no balance, nothing to poll. It is a SHAPE
+// two primitives consume — what sections an article has, in what order, in what form. What it has
+// instead of a door is a RESOLUTION:
+//
+//   templates resolve <key>                    the SHAPE: feeds `arena run --template`
+//   templates resolve <key> --file material.md the PLAN too: skeleton, budget and brief for `kernel write`
+//   templates assemble --spans s.json --file a.md   a templated run's output, turned back into the article
+//
+// Resolve ONCE and pass `--constraints` back on every later call. Resolving twice is a model call
+// twice and two different sets of section labels — and the writer writes each section under its
+// label while assembly matches output back by that label, so a second resolution files sections
+// under headings the outline never planned.
+//
+// For a single write with no research, skip all of this: `kernel write --template <key>` resolves
+// through the same function and returns the article already assembled.
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import { flagStr, flagBool, requirePositional, printResult, ok, argsFromFlags, readBodyInput } from "./shared.mjs";
+
+/** `--<flag> <path>` → the file's parsed JSON, or undefined when the flag is not set. */
+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.`);
+	}
+}
+
+/** Read a file, or throw a CLI error naming the flag that asked for it. */
+function readFileOrThrow(path, flag) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		throw new CliError(`Could not read ${flag} ${path}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/** `--var Name=Value` (repeatable) → `{ Name: "Value" }`. */
+function variablesFromFlags(flags) {
+	const raw = flags.var;
+	if (raw === undefined) return undefined;
+	const list = Array.isArray(raw) ? raw : [raw];
+	const out = {};
+	for (const entry of list) {
+		const text = String(entry);
+		const eq = text.indexOf("=");
+		if (eq <= 0) throw new CliError(`--var must be Name=Value (got "${text}").`);
+		out[text.slice(0, eq).trim()] = text.slice(eq + 1).trim();
+	}
+	return Object.keys(out).length ? out : undefined;
+}
+
+/**
+ * How the RESOLVE and ASSEMBLE commands source their arguments — see `argsFromFlags` in
+ * shared.mjs, and `scripts/parity-check.ts`, which compares these keys against each tool's
+ * published input schema. The CRUD commands below predate the field-level ratchet and are
+ * covered by the frozen `UNMAPPED_TOOLS` list, which only shrinks.
+ */
+export const ARGS = {
+	resolve_template: {
+		key: { positional: 0, label: "template-key" },
+		blocks: { value: (flags) => readJsonFileFlag(flags, "blocks-file") },
+		title: "title",
+		material: { value: (flags) => readBodyInput(flags) },
+		variables: { value: variablesFromFlags },
+		constraints: { value: (flags) => readJsonFileFlag(flags, "constraints") },
+		// The brand a {Brand}-style variable names. Omitted = this org's own; an org with no
+		// positioning simply resolves no brand variable rather than failing.
+		brand: {
+			object: {
+				name: { flag: "brand" },
+				one_liner: { flag: "brand-one-liner" },
+			},
+		},
+	},
+	// Declared rather than re-frozen. These two were on the `UNMAPPED_TOOLS` list while they lived
+	// in `seers.mjs`; moving the file is not a reason to re-freeze them, and they are one
+	// positional each.
+	get_template: {
+		template_id: { positional: 0, label: "template-id", required: true },
+	},
+	delete_template: {
+		template_id: { positional: 0, label: "template-id", required: true },
+	},
+	assemble_template: {
+		spans: { value: (flags) => readJsonFileFlag(flags, "spans") },
+		article: { value: (flags) => readBodyInput(flags) },
+	},
+};
+
+export async function cmdTemplates(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return templatesList(rest);
+		case "show":
+		case "get":
+			return templatesShow(rest);
+		case "create":
+		case "new":
+			return templatesCreate(rest);
+		case "update":
+			return templatesUpdate(rest);
+		case "delete":
+		case "rm":
+			return templatesDelete(rest);
+		case "resolve":
+			return templatesResolve(rest);
+		case "assemble":
+			return templatesAssemble(rest);
+		default:
+			throw new CliError(
+				`Unknown templates subcommand: ${sub ?? "(none)"}. Try: list, show, create, update, delete, resolve, assemble`
+			);
+	}
+}
+
+async function templatesList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_templates", {});
+	printResult(io, flags, result, (r) => {
+		const custom = (r.templates ?? []).map((t) => `  ${t.key}  ${t.name} — ${t.angle} (id ${t.id})`);
+		const builtIn = (r.built_ins ?? []).map((t) => `  ${t.key}  ${t.name}`);
+		return [
+			custom.length ? "Custom templates:" : "No custom templates yet.",
+			...custom,
+			"",
+			"Built-in templates (read-only):",
+			...builtIn,
+		].join("\n");
+	});
+	return 0;
+}
+
+async function templatesShow(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "template-id");
+	const result = await client.callTool("get_template", argsFromFlags(ARGS.get_template, flags, positionals));
+	printResult(io, flags, result);
+	return 0;
+}
+
+function templateBlocksFromFlags(flags) {
+	const inline = flagStr(flags.blocks);
+	const file = flagStr(flags["blocks-file"]);
+	if (inline === undefined && file === undefined) return undefined;
+	const raw = inline !== undefined ? inline : readFileOrThrow(file, "--blocks-file");
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new CliError(`--blocks is not valid JSON: ${err.message}`);
+	}
+	if (!Array.isArray(parsed)) throw new CliError("--blocks must be a JSON array of block objects");
+	return parsed;
+}
+
+async function templatesCreate(ctx) {
+	const { client, flags, io } = ctx;
+	const name = flagStr(flags.name);
+	const angle = flagStr(flags.angle);
+	const blocks = templateBlocksFromFlags(flags);
+	if (!name) throw new CliError("Missing required --name");
+	// `--angle` is OPTIONAL, and omitting it is the better answer. It was required here while
+	// the server schema had already made it optional and the app had dropped the field: a
+	// template constrains a post's SHAPE and never says what it is about, so an angle belongs
+	// to the post — which already has one, from its research direction.
+	if (!blocks) throw new CliError("Missing required --blocks '<json>' or --blocks-file <path>");
+	const result = await client.callTool("create_template", { name, blocks, ...(angle ? { angle } : {}) });
+	ok(ctx, `Template created — key ${result.template?.key}.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function templatesUpdate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const templateId = requirePositional(positionals, 0, "template-id");
+	const name = flagStr(flags.name);
+	const angle = flagStr(flags.angle);
+	const blocks = templateBlocksFromFlags(flags);
+	// update_template replaces the whole template; fetch current values for any
+	// field the caller didn't pass so a partial edit doesn't blank the rest.
+	let current;
+	if (!name || !angle || !blocks) {
+		const existing = await client.callTool("get_template", { template_id: templateId });
+		current = existing.template;
+	}
+	const result = await client.callTool("update_template", {
+		template_id: templateId,
+		name: name ?? current.name,
+		angle: angle ?? current.angle,
+		blocks: blocks ?? current.blocks,
+	});
+	ok(ctx, "Template updated.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function templatesDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "template-id");
+	if (!flagBool(flags.yes)) {
+		throw new CliError("Seers bound to this template fall back to defaults. Re-run with --yes to delete.");
+	}
+	const result = await client.callTool("delete_template", argsFromFlags(ARGS.delete_template, flags, positionals));
+	ok(ctx, "Template deleted.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+/**
+ * `templates resolve <key> [--title t] [--body/--file material] [--var K=V] [--constraints c.json]`
+ *
+ * THE ONE PLACE A TEMPLATE BECOMES CONSTRAINTS. Without material: the SHAPE — `must_include`,
+ * `gather_hints`, `form_guidance`, which is what `arena run` takes. With it: the PLAN as well —
+ * `skeleton`, `target_word_count`, `brief`, `brief_json`, `spans`, which is what `kernel write`
+ * takes. Pass `--constraints` back on the second call so nothing is re-decided.
+ */
+async function templatesResolve(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.resolve_template, flags, positionals);
+	if (args.key === undefined && args.blocks === undefined) {
+		throw new CliError(
+			"Name the template: `templates resolve <template-key>`, or --blocks-file <path> for an inline one."
+		);
+	}
+	const result = await client.callTool("resolve_template", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+/** `templates assemble --spans spans.json --file article.md` — the way back. */
+async function templatesAssemble(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.assemble_template, flags, positionals);
+	if (args.spans === undefined) {
+		throw new CliError("--spans <path> is required: the spans `templates resolve` returned.");
+	}
+	if (args.article === undefined) {
+		throw new CliError("Provide the run's output with --body <text>, --file <path>, or --file - (stdin).");
+	}
+	const result = await client.callTool("assemble_template", args);
+	// The article itself, so `> post.html` works.
+	printResult(io, flags, result, (r) => r?.article ?? "");
+	return 0;
+}

package/lib/commands.mjs

@@ -19,7 +19,8 @@ export * from "./commands/probes.mjs";
 export * from "./commands/series.mjs";
 export * from "./commands/insights.mjs";
 export * from "./commands/covers.mjs";
-export * from "./commands/research.mjs";
+export * from "./commands/arena.mjs";
+export * from "./commands/templates.mjs";
 export * from "./commands/autopen.mjs";
 export * from "./commands/kernel.mjs";
 export * from "./commands/phantom-job.mjs";

package/package.json

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

package/lib/commands/research.mjs

@@ -1,87 +0,0 @@
-// `research` — the deep-research agent: read supplied URLs, search the live web, and
-// write a sourced outline into a post. Same shape as `kernel`: a run takes minutes, so
-// `start` returns as soon as the run is queued and `status` checks on demand. Writing
-// kernels do NOT research — `research start` then `kernel run` is the full pipeline.
-
-import { CliError } from "../client.mjs";
-import { flagStr, flagNum, flagBool, requireFlag, printResult, compact, ok, argsFromFlags } from "./shared.mjs";
-
-/** See `argsFromFlags` in shared.mjs; `scripts/parity-check.ts` diffs these keys against the tool. */
-export const ARGS = {
-	start_research: {
-		article_id: { flag: "article", required: true },
-		topic: "topic",
-		source_urls: { flag: "url", type: "list" },
-		must_include: { flag: "must-include", type: "list" },
-		depth: { flag: "depth", enum: ["barebones", "fleshed_out"] },
-		direction_gate: { flag: "gate", type: "bool" },
-	},
-};
-
-export async function cmdResearch(ctx) {
-	const sub = ctx.positionals[0];
-	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
-	switch (sub) {
-		case "start":
-		case "run":
-			return researchStart(rest);
-		case "status":
-			return researchStatus(rest);
-		case "direction":
-			return researchDirection(rest);
-		case "cancel":
-			return researchCancel(rest);
-		default:
-			throw new CliError(
-				`Unknown research subcommand: ${sub ?? "(none)"}. Try: start, status, direction, cancel`
-			);
-	}
-}
-
-async function researchStart(ctx) {
-	const { client, flags, io } = ctx;
-	const args = argsFromFlags(ARGS.start_research, flags, ctx.positionals);
-	const result = await client.callTool("start_research", args);
-	ok(ctx, `Research started. Check progress with: research status --article ${args.article_id}`);
-	printResult(io, flags, result);
-	return 0;
-}
-
-async function researchStatus(ctx) {
-	const { client, flags, io } = ctx;
-	const article = requireFlag(flags, "article");
-	const result = await client.callTool("get_research_status", { article_id: article });
-	printResult(io, flags, result);
-	return 0;
-}
-
-async function researchDirection(ctx) {
-	const { client, flags, io } = ctx;
-	const article = requireFlag(flags, "article");
-	const choice = flagNum(flags.choice);
-	const custom = flagStr(flags.custom);
-	const skip = flagBool(flags.skip);
-	const given = [choice !== undefined, custom !== undefined, skip].filter(Boolean).length;
-	if (given !== 1) {
-		throw new CliError("Provide exactly one of --choice <n>, --custom <text>, --skip");
-	}
-	const args = compact({
-		article_id: article,
-		choice,
-		custom,
-		skip: skip ? true : undefined,
-	});
-	const result = await client.callTool("submit_research_direction", args);
-	ok(ctx, "Direction recorded; the run resumed into synthesis.");
-	printResult(io, flags, result);
-	return 0;
-}
-
-async function researchCancel(ctx) {
-	const { client, flags, io } = ctx;
-	const article = requireFlag(flags, "article");
-	const result = await client.callTool("cancel_research", { article_id: article });
-	ok(ctx, result?.cancelled ? "Research run cancelled." : "No research run was in flight.");
-	printResult(io, flags, result);
-	return 0;
-}