@letterstory/cli 0.25.0 → 0.25.2

package/lib/cli.mjs

@@ -44,7 +44,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.25.0";
+export const VERSION = "0.25.2";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.

package/lib/commands/autopen.mjs

@@ -11,7 +11,14 @@
 // finishes whether or not anyone polls.
 
 import { CliError } from "../client.mjs";
-import { flagBool, requireFlag, printResult, ok } from "./shared.mjs";
+import { flagBool, requireFlag, printResult, ok, argsFromFlags } from "./shared.mjs";
+
+/** See `argsFromFlags` in shared.mjs; `scripts/parity-check.ts` diffs these keys against the tool. */
+export const ARGS = {
+	run_auto_pen: {
+		article_id: { flag: "article", required: true },
+	},
+};
 
 export async function cmdAutoPen(ctx) {
 	const sub = ctx.positionals[0];
@@ -31,9 +38,9 @@ export async function cmdAutoPen(ctx) {
 
 async function autoPenStart(ctx) {
 	const { client, flags, io } = ctx;
-	const article = requireFlag(flags, "article");
-	const result = await client.callTool("run_auto_pen", { article_id: article });
-	ok(ctx, `Auto-Pen started. Check progress with: autopen status --article ${article}`);
+	const args = argsFromFlags(ARGS.run_auto_pen, flags, ctx.positionals);
+	const result = await client.callTool("run_auto_pen", args);
+	ok(ctx, `Auto-Pen started. Check progress with: autopen status --article ${args.article_id}`);
 	printResult(io, flags, result);
 	return 0;
 }

package/lib/commands/flows.mjs

@@ -2,7 +2,15 @@
 // flow_run.completed completion webhook. Ported from phantomstory-cli's flows.ts.
 
 import { CliError } from "../client.mjs";
-import { flagStr, requirePositional, printResult, compact, ok } from "./shared.mjs";
+import { flagStr, requirePositional, 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 = {
+	run_flow: {
+		flow_id: { positional: 0, label: "flow-id", required: true },
+		article_id: { positional: 1, label: "article-id", required: true },
+	},
+};
 
 export async function cmdFlows(ctx) {
 	const sub = ctx.positionals[0];
@@ -31,9 +39,7 @@ async function flowsList(ctx) {
 
 async function flowsRun(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const flowId = requirePositional(positionals, 0, "flow-id");
-	const articleId = requirePositional(positionals, 1, "article-id");
-	const result = await client.callTool("run_flow", { flow_id: flowId, article_id: articleId });
+	const result = await client.callTool("run_flow", argsFromFlags(ARGS.run_flow, flags, positionals));
 	ok(ctx, "Flow run started.");
 	printResult(io, flags, result);
 	return 0;

package/lib/commands/kernel.mjs

@@ -15,11 +15,10 @@
 // Neither door blocks: a write runs for minutes, so `write` submits and then follows the run
 // unless you tell it not to.
 
+import { readFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
 import {
 	flagStr,
-	flagBool,
-	requireFlag,
 	requirePositional,
 	printResult,
 	compact,
@@ -30,6 +29,38 @@ import {
 	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> <path>` → the file's text, or undefined when the flag is not set. */
+function readTextFileFlag(flags, flag) {
+	const path = flagStr(flags[flag]);
+	if (path === undefined) return undefined;
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		throw new CliError(
+			`Could not read --${flag} ${path}: ${error instanceof Error ? error.message : String(error)}`
+		);
+	}
+}
+
 /**
  * How the commands ADDED to this file source their arguments — see `argsFromFlags`
  * in shared.mjs, and `scripts/parity-check.ts`, which compares these keys against
@@ -39,6 +70,72 @@ import {
  * frozen UNMAPPED_TOOLS list. New commands declare; that list only shrinks.
  */
 export const ARGS = {
+	// The article-bound door: submit a kernel run INTO an article you already have.
+	submit_kernel_run: {
+		article_id: { flag: "article", required: true },
+		kernel_id: { flag: "kernel", required: true },
+		// A brief overrides the article's own content as the instruction; --brief-file reads
+		// it from a path. Omit both to write from the article as it stands.
+		brief: { value: (flags) => flagStr(flags.brief) ?? readBodyInput({ file: flagStr(flags["brief-file"]) }) },
+	},
+	// The standalone door. Two subcommands share this one tool: `write` and `polish` both
+	// send `input`, `polish` forcing content_kind to "document" — the map is one, so a field
+	// the tool gains is a field BOTH subcommands must learn (or knowingly gap) — that is the
+	// ratchet.
+	run_kernel: {
+		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
+		input: { value: (flags) => readBodyInput(flags) },
+		kernel_id: "kernel",
+		target_word_count: { flag: "words", type: "num" },
+		label: "label",
+		// The flag is --read-as, which is what shipped; an earlier draft called it --brief-mode.
+		content_kind: {
+			flag: "read-as",
+			enum: ["auto", "instruction", "document", "article", "outline", "research", "notes"],
+		},
+		// The two products, in one run: every round is shredded before the kernel's jury sees
+		// it, so the verdict lands on the text that actually ships. Costs a shred as well as a
+		// run.
+		shredder_endpoint_id: "shredder",
+		shred_aggression: { flag: "shred-aggression", enum: ["standard", "high", "max"] },
+		voice: {
+			object: {
+				person: { flag: "person", enum: ["third", "first_plural", "first_singular"] },
+				allow_experience_claims: { flag: "experience-claims", type: "bool" },
+			},
+		},
+		// The mechanism's full contract, declared on the door (2026-09-17, Kernels wave step 1).
+		// A shape and a typed brief are files, not flags — `--skeleton-file shape.json` is the
+		// 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") },
+		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.
+		shred: {
+			object: {
+				tier: { flag: "shred-tier", enum: ["cheap", "mid", "strong", "frontier"] },
+				families: { flag: "shred-family", type: "list" },
+				revise_shredded: { flag: "shred-revise", type: "bool" },
+				revision_model: "shred-revision-model",
+				skip_voice_bearing: { flag: "shred-skip-voice-bearing", type: "bool" },
+				judge: { flag: "shred-judge", type: "bool" },
+				attempts_per_unit: { flag: "shred-attempts", type: "num" },
+				max_changeable_retention: { flag: "shred-max-retention", type: "num" },
+				turnover_retries: { flag: "shred-turnover-retries", type: "num" },
+				turnover_avoid_list: { flag: "shred-turnover-avoid-list", type: "bool" },
+				evidence: { value: (flags) => readTextFileFlag(flags, "shred-evidence-file") },
+			},
+		},
+		// Named-entity treatment (2026-09-17, renamed 2026-09-18): a list, not a scalar flag,
+		// so it's a file like skeleton/brief_json — `--entities-file entities.json` of
+		// `[{"name":"...","treatment":"never"|"mention_once"|"mention_often"|"lead_company",
+		// "linkable":false}, ...]` (linkable optional, default true).
+		entities: { value: (flags) => readJsonFileFlag(flags, "entities-file") },
+		// content_kind "document" only: hold the document's own shape through the edit. Default
+		// true; pass --no-preserve-shape to let the kernel restructure freely.
+		preserve_shape: { flag: "preserve-shape", type: "bool" },
+	},
 	create_kernel_endpoint: {
 		name: { flag: "name", required: true },
 		// Both optional bindings the tool has always accepted at create: which kernel
@@ -51,6 +148,15 @@ export const ARGS = {
 	delete_kernel_endpoint: {
 		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
 	},
+	// The endpoint's configuration as ONE file: `kernel endpoint config <id>` prints it,
+	// `kernel endpoint config <id> --file cfg.json` replaces it with the file's document.
+	get_kernel_endpoint_config: {
+		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
+	},
+	set_kernel_endpoint_config: {
+		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
+		config: { value: (flags) => readJsonFileFlag(flags, "file") },
+	},
 };
 
 export async function cmdKernel(ctx) {
@@ -94,10 +200,7 @@ async function kernelList(ctx) {
 
 async function kernelRun(ctx) {
 	const { client, flags, io } = ctx;
-	const article = requireFlag(flags, "article");
-	const kernelId = requireFlag(flags, "kernel");
-	const brief = flagStr(flags.brief) ?? readBodyInput({ file: flagStr(flags["brief-file"]) });
-	const args = compact({ article_id: article, kernel_id: kernelId, brief });
+	const args = argsFromFlags(ARGS.submit_kernel_run, flags, ctx.positionals);
 	const result = await client.callTool("submit_kernel_run", args);
 	ok(ctx, `Kernel run started. Check progress with: kernel status ${result?.kernel_job_id ?? "<kernel-job-id>"}`);
 	printResult(io, flags, result);
@@ -130,33 +233,10 @@ async function kernelEndpoints(ctx) {
 
 async function kernelWrite(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const endpointId = requirePositional(positionals, 0, "endpoint-id");
-	const brief = readBodyInput(flags);
-	if (brief === undefined) {
+	const args = argsFromFlags(ARGS.run_kernel, flags, positionals);
+	if (args.input === undefined) {
 		throw new CliError("Provide the brief with --body <text>, --file <path>, or --file - (stdin).");
 	}
-	const args = compact({
-		endpoint_id: endpointId,
-		brief,
-		kernel_id: flagStr(flags.kernel),
-		target_word_count: flags.words === undefined ? undefined : Number(flags.words),
-		content_type: flagStr(flags["content-type"]),
-		// The two products, in one run: every round is shredded before the kernel's jury sees
-		// it, so the verdict lands on the text that actually ships. Costs a shred as well as a
-		// run. Reachable from every other surface and, until now, not from here.
-		shredder_endpoint_id: flagStr(flags.shredder),
-		// How hard that in-loop shred rewrites — 'standard' (default, recommended), 'high',
-		// or 'max'. Ignored when no shred runs.
-		shred_aggression: flagStr(flags["shred-aggression"]),
-		// The flag is --read-as, which is what shipped; an earlier draft of this branch
-		// called it --brief-mode and never reached anyone.
-		brief_mode: flagStr(flags["read-as"]),
-		// The other three `run_kernel` has always taken and the CLI still did not expose,
-		// so the only way to reach them was hand-written JSON through `mcp call`.
-		person: flagStr(flags.person),
-		author_name: flagStr(flags.author),
-		allow_experience_claims: flagBool(flags["experience-claims"]),
-	});
 	const result = await client.callTool("run_kernel", args);
 	const runId = toolField(result, "run_id");
 	if (!runId) {
@@ -225,33 +305,46 @@ async function kernelEndpoint(ctx) {
 		printResult(io, flags, result);
 		return 0;
 	}
-	throw new CliError(`Unknown kernel endpoint action: ${action ?? "(none)"}. Try: create, delete`);
+	if (action === "config") {
+		const id = requirePositional(positionals, 1, "endpoint-id");
+		if (flagStr(flags.file) === undefined) {
+			const result = await client.callTool(
+				"get_kernel_endpoint_config",
+				argsFromFlags(ARGS.get_kernel_endpoint_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_kernel_endpoint_config, flags, positionals);
+		const result = await client.callTool("set_kernel_endpoint_config", args);
+		ok(ctx, `Replaced the configuration of kernel endpoint ${id}.`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	throw new CliError(`Unknown kernel endpoint action: ${action ?? "(none)"}. Try: create, delete, config`);
 }
 
 /**
  * The OTHER door: run the same pipeline against a document you already have, instead of
- * writing a new one. Skips generation only — the rules, the in-loop shred and the jury all
- * still run, which is what keeps your own markup (images, embeds, links, tables, anchors,
- * shortcodes) intact through a real pass rather than an unguarded shortcut.
+ * writing a new one. Decomposed into a brief and GENERATED FRESH (content_kind: "document",
+ * forced below) — not edited in place — with your own headings and embedded media (images,
+ * tables) extracted first and spliced back into the generated draft afterward, so they
+ * survive a pass that would otherwise be text-only and lose them.
  *
  * ASYNCHRONOUS, same as `write` — this used to be a separate, synchronous, unmetered "polish"
- * that answered in one request. That path was deleted (2026-09-15, letterstory#1783): it
- * worked by skipping the rules and the jury, and that was the actual cost of being instant
- * and free. `document` now costs a run and follows the identical submit-and-poll shape
+ * that answered in one request, and before that an EARLIER `document` mode that skipped
+ * generation to hold shape "in place." Neither exists any more (2026-09-15, letterstory#1783;
+ * 2026-09-17). `document` now costs a run and follows the identical submit-and-poll shape
  * `write` does, so this command does too — `--no-wait` behaves the same way here.
  */
 async function kernelPolish(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const endpointId = requirePositional(positionals, 0, "endpoint-id");
-	const document = readBodyInput(flags);
-	if (document === undefined) {
+	const args = argsFromFlags(ARGS.run_kernel, flags, positionals);
+	if (args.input === undefined) {
 		throw new CliError("Provide the document with --body <text>, --file <path>, or --file - (stdin).");
 	}
-	const args = compact({
-		endpoint_id: endpointId,
-		document,
-		format: flagStr(flags.format),
-	});
+	args.content_kind = args.content_kind ?? "document";
 	const result = await client.callTool("run_kernel", args);
 	const runId = toolField(result, "run_id");
 	if (!runId) {

package/lib/commands/posts.mjs

@@ -12,8 +12,16 @@ import {
 	compact,
 	ok,
 	readBodyInput,
+	argsFromFlags,
 } from "./shared.mjs";
 
+/** See `argsFromFlags` in shared.mjs; `scripts/parity-check.ts` diffs these keys against the tool. */
+export const ARGS = {
+	publish_article: {
+		article_id: { positional: 0, label: "article-id", required: true },
+	},
+};
+
 export async function cmdPosts(ctx) {
 	const sub = ctx.positionals[0];
 	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
@@ -66,8 +74,7 @@ async function postsNew(ctx) {
 
 async function postsPublish(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const id = requirePositional(positionals, 0, "article-id");
-	const result = await client.callTool("publish_article", { article_id: id });
+	const result = await client.callTool("publish_article", argsFromFlags(ARGS.publish_article, flags, positionals));
 	ok(ctx, "Published.");
 	printResult(io, flags, result);
 	return 0;

package/lib/commands/research.mjs

@@ -4,7 +4,19 @@
 // kernels do NOT research — `research start` then `kernel run` is the full pipeline.
 
 import { CliError } from "../client.mjs";
-import { flagStr, flagNum, flagBool, flagList, requireFlag, printResult, compact, ok } from "./shared.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];
@@ -28,23 +40,9 @@ export async function cmdResearch(ctx) {
 
 async function researchStart(ctx) {
 	const { client, flags, io } = ctx;
-	const article = requireFlag(flags, "article");
-	const depth = flagStr(flags.depth);
-	if (depth !== undefined && depth !== "barebones" && depth !== "fleshed_out") {
-		throw new CliError(`--depth must be barebones or fleshed_out, got "${depth}"`);
-	}
-	const sourceUrls = flagList(flags.url);
-	const mustInclude = flagList(flags["must-include"]);
-	const args = compact({
-		article_id: article,
-		topic: flagStr(flags.topic),
-		source_urls: sourceUrls.length ? sourceUrls : undefined,
-		must_include: mustInclude.length ? mustInclude : undefined,
-		depth,
-		direction_gate: flagBool(flags.gate) ? true : undefined,
-	});
+	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 ${article}`);
+	ok(ctx, `Research started. Check progress with: research status --article ${args.article_id}`);
 	printResult(io, flags, result);
 	return 0;
 }

package/lib/commands/seers.mjs

@@ -12,7 +12,18 @@
 
 import { readFileSync, writeFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
-import { flagStr, flagNum, flagBool, requirePositional, printResult, compact, ok } from "./shared.mjs";
+import { flagStr, flagNum, flagBool, requirePositional, printResult, compact, ok, argsFromFlags } from "./shared.mjs";
+
+/**
+ * How the ratcheted commands in this file source their tool inputs — see `argsFromFlags` in
+ * shared.mjs and `scripts/parity-check.ts`. The rest of the module predates the field-level
+ * ratchet and stays in UNMAPPED_TOOLS; that list only shrinks.
+ */
+export const ARGS = {
+	run_seer: {
+		seer_id: { positional: 0, label: "seer-id", required: true },
+	},
+};
 
 export async function cmdSeers(ctx) {
 	const sub = ctx.positionals[0];
@@ -177,9 +188,9 @@ async function seersDelete(ctx) {
 
 async function seersRun(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const seerId = requirePositional(positionals, 0, "seer-id");
+	const args = argsFromFlags(ARGS.run_seer, flags, positionals);
 	ok(ctx, "Polling now — web-scan providers can take a few minutes…");
-	const result = await client.callTool("run_seer", { seer_id: seerId });
+	const result = await client.callTool("run_seer", args);
 	printResult(
 		io,
 		flags,

package/lib/commands/shredder.mjs

@@ -15,8 +15,32 @@ import {
 	ok,
 	toolField,
 	followJob,
+	argsFromFlags,
 } from "./shared.mjs";
 
+/**
+ * How `shredder run` sources `run_shred`'s inputs — see `argsFromFlags` in shared.mjs and
+ * `scripts/parity-check.ts`, which diffs these keys against the tool's published schema.
+ * The rest of this module predates the ratchet and stays in UNMAPPED_TOOLS.
+ */
+export const ARGS = {
+	run_shred: {
+		endpoint_id: { positional: 0, label: "endpoint-id", required: true },
+		text: { value: (flags) => readBodyInput(flags) },
+		coverage: { flag: "coverage", type: "num" },
+		attempts_per_unit: { flag: "attempts", type: "num" },
+		// What the text IS. Without this an HTML file could only go through the `auto`
+		// heuristic, which misreads a markdown post carrying an embed.
+		format: { flag: "format", enum: ["auto", "html", "markdown"] },
+		// How hard to rewrite. Validated service-side; sent only when the caller asked.
+		aggression: { flag: "aggression", enum: ["standard", "high", "max"] },
+		// Hold every rewrite to the live writing rules. A trade, not a free win.
+		apply_rules: { flag: "apply-rules", type: "bool" },
+		// ASYNCHRONOUS BY DEFAULT — `--sync` is the opt-out (see shredderRun for why).
+		async: { value: (flags) => (flags.sync === true ? undefined : true) },
+	},
+};
+
 export async function cmdShredder(ctx) {
 	const sub = ctx.positionals[0];
 	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
@@ -87,11 +111,6 @@ const POLL_CEILING_MS = 30 * 60 * 1000;
 
 async function shredderRun(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const id = requirePositional(positionals, 0, "endpoint-id");
-	const text = readBodyInput(flags);
-	if (text === undefined) {
-		throw new CliError("Provide the prose to shred with --body <text>, --file <path>, or --file - (stdin).");
-	}
 	// ASYNCHRONOUS BY DEFAULT, and `--sync` is the opt-out rather than the other way round.
 	//
 	// A shred has no workable synchronous ceiling — the identical article took 203s, 541s and
@@ -100,21 +119,10 @@ async function shredderRun(ctx) {
 	// answer, so the caller gets no text, no error, and no record. Defaulting the other way
 	// made the common case the broken one.
 	const sync = flags.sync === true;
-	const args = compact({
-		endpoint_id: id,
-		text,
-		coverage: flagNum(flags.coverage),
-		attempts_per_unit: flagNum(flags.attempts),
-		// What the text IS. Without this an HTML file could only go through the
-		// `auto` heuristic, which misreads a markdown post carrying an embed.
-		...(flags.format ? { format: String(flags.format) } : {}),
-		// How hard to rewrite. Validated service-side; sent only when the caller asked.
-		...(flags.aggression ? { aggression: String(flags.aggression) } : {}),
-		// Hold every rewrite to the live writing rules. A trade, not a free win: refused rewrites
-		// cost provider attempts and a sentence with no clean rewrite keeps its original.
-		...(flags["apply-rules"] === true ? { apply_rules: true } : {}),
-		...(sync ? {} : { async: true }),
-	});
+	const args = argsFromFlags(ARGS.run_shred, flags, positionals);
+	if (args.text === undefined) {
+		throw new CliError("Provide the prose to shred with --body <text>, --file <path>, or --file - (stdin).");
+	}
 	const result = await client.callTool("run_shred", args);
 	if (sync) {
 		ok(ctx, "Shred complete.");

package/package.json

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