@letterstory/cli 0.33.11 → 0.35.0

package/README.md

@@ -389,10 +389,16 @@ letterstory lede endpoint config <endpoint-id> [--file cfg.json]
 
 # 2. Have a kernel write the draft
 letterstory kernel list
-letterstory kernel run --article <uuid> --kernel <uuid> [--brief "…" | --brief-file brief.md]
+letterstory kernel write <endpoint-id> --article <uuid> [--kernel <uuid>] [--file brief.md]
 letterstory kernel status <kernel-job-id>
 ```
 
+`kernel run` (and the `submit_kernel_run` tool behind it) was removed on 2026-09-27. Its one
+job is `kernel write <endpoint-id> --article <uuid>`: with no `--body`/`--file` it writes from
+the article's own content, and `kernel status` still polls the job it starts. Its
+`--brief`/`--brief-file` flags have no replacement: the input is `--body`/`--file`, and
+guidance that is not content goes in `--directives`.
+
 ### The standalone kernel endpoint
 
 `kernel write` and `kernel polish` hit the standalone door: prose comes back, nothing is
@@ -403,7 +409,7 @@ letterstory kernel endpoint create --name "Writer"
 letterstory kernel endpoint delete <endpoint-id> --yes
 
 letterstory kernel write <endpoint-id> --file outline.md \
-  --brief-mode outline --person first --author "Ada" --shredder <endpoint-id>
+  --read-as outline --person first --author "Ada" --shredder <endpoint-id>
 # Follows the run and prints the ARTICLE when it lands. --no-wait returns the run id instead.
 ```
 

package/lib/cli.mjs

@@ -45,7 +45,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.33.11";
+export const VERSION = "0.35.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.
@@ -84,6 +84,8 @@ const BOOLEAN_FLAGS = new Set([
 	"no-visuals",
 	"no-enhance",
 	"no-key",
+	// `autopen start --article <id> --from-scratch`
+	"from-scratch",
 	// `collections activate <id> --no-topic-map` / `--no-headlines`
 	"no-topic-map",
 	"no-headlines",
@@ -319,8 +321,9 @@ Arenas (adversarial clusters of research agents -> a sourced, fact-checked outli
   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):
+applies a collection's content template; kernel write --article does not):
   autopen start --article <uuid>                        Start the run; takes 10-40 min
+  autopen start --article <uuid> --from-scratch         Clear the draft first, then run
   autopen status --article <uuid>                       Step states + the template in use
   autopen cancel --article <uuid> --yes                 Stop a run in flight
 
@@ -337,9 +340,11 @@ Writing kernels (kernels write the draft; they do not research — run research
   kernel list                                          List available writing kernels
 
   Into an article you already have (metered on the AI-usage gate):
-  kernel run --article <uuid> --kernel <uuid> [--brief <text>|--brief-file <path>]
-                                                        Submit a run; takes 15-20 min
-  kernel status <kernel-job-id>                        Check a run's status
+  kernel write <endpoint-id> --article <uuid> [--kernel <uuid>] [--body <text>|--file <path>]
+                                                        Write into the article (from its own
+                                                        content when no input is given);
+                                                        takes 15-20 min
+  kernel status <kernel-job-id>                        Check that run's status
 
   Standalone — prose back, nothing saved into an article (metered in kernel-run credits):
   kernel endpoints                                     Your kernel endpoints

package/lib/commands/autopen.mjs

@@ -3,7 +3,7 @@
 //
 // This is the command that makes a TEMPLATE take effect. A template bound with
 // `collections autopen <id> --template-key <key>` is read inside the Auto-Pen run and
-// nowhere else, so `kernel run` (which hands the draft's current text straight to a
+// nowhere else, so `kernel write --article` (which hands the draft's current text straight to a
 // kernel) will not produce a templated post no matter how the collection is configured.
 //
 // A run takes 10-40 minutes, so `start` returns as soon as it is queued. `status` both
@@ -17,6 +17,7 @@ import { flagBool, requireFlag, printResult, ok, argsFromFlags } from "./shared.
 export const ARGS = {
 	run_auto_pen: {
 		article_id: { flag: "article", required: true },
+		from_scratch: { flag: "from-scratch", type: "bool" },
 	},
 };
 

package/lib/commands/kernel.mjs

@@ -3,11 +3,13 @@
 // TWO PRODUCTS SHARE THIS NOUN, and the subcommands are split along that line because
 // confusing them wastes fifteen minutes and a credit:
 //
-//   kernel run/status        writes INTO an article you already have (submit_kernel_run).
-//                            Metered on the AI-usage gate; needs --article.
 //   kernel write/…           the STANDALONE endpoint (run_kernel) — you get prose back and
 //                            nothing is saved into an article. Metered in kernel-run
 //                            credits, the balance the Kernels page shows.
+//   kernel write --article   the same tool writing INTO an article you already have (with no
+//     + kernel status        input, from the article's own content). Metered on the AI-usage
+//                            gate; follow it with `kernel status <kernel-job-id>`. This
+//                            replaced `kernel run` (and its tool) on 2026-09-27.
 //
 // The standalone door had MCP tools and no CLI at all, so the only way to reach the product
 // the Kernels page bills for was `letterstory mcp call run_kernel` with hand-written JSON.
@@ -85,21 +87,6 @@ function variablesFromFlags(flags) {
 }
 
 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"]) }) },
-		// How to read --brief: auto (default) treats a short topic as instruction and a pasted
-		// draft/article as source material to decompose first — your own finished post is
-		// `article`. Same flag name as run_kernel's.
-		content_kind: {
-			flag: "read-as",
-			enum: ["auto", "instruction", "document", "article", "outline", "research", "notes"],
-		},
-	},
 	// The standalone door. Two subcommands share this one tool: `write` and `polish` both
 	// send `input`, `polish` defaulting content_kind to "article" — the map is one, so a field
 	// the tool gains is a field BOTH subcommands must learn (or knowingly gap) — that is the
@@ -111,14 +98,14 @@ export const ARGS = {
 		target_word_count: { flag: "words", type: "num" },
 		target_word_tolerance: { flag: "words-tolerance", type: "num" },
 		// Write into an article instead of handing the text back (2026-09-27): the one call that
-		// replaces `kernel submit`. With `--article` and no input, the article's own content is
-		// the input.
+		// replaced `kernel run`. With `--article` and no input, the article's own content is the
+		// input.
 		article_id: { flag: "article" },
 		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"],
+			enum: ["auto", "instruction", "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
@@ -159,8 +146,6 @@ export const ARGS = {
 			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" },
@@ -248,8 +233,6 @@ export async function cmdKernel(ctx) {
 		case "list":
 		case "ls":
 			return kernelList(rest);
-		case "run":
-			return kernelRun(rest);
 		case "status":
 			return kernelStatus(rest);
 		case "endpoints":
@@ -274,7 +257,7 @@ export async function cmdKernel(ctx) {
 			return kernelBalance(rest);
 		default:
 			throw new CliError(
-				`Unknown kernel subcommand: ${sub ?? "(none)"}. Try: list, endpoints, endpoint, eval, update, archive, write, polish, run-status, runs, balance, run, status`
+				`Unknown kernel subcommand: ${sub ?? "(none)"}. Try: list, endpoints, endpoint, eval, update, archive, write, polish, run-status, runs, balance, status`
 			);
 	}
 }
@@ -286,15 +269,6 @@ async function kernelList(ctx) {
 	return 0;
 }
 
-async function kernelRun(ctx) {
-	const { client, flags, io } = ctx;
-	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);
-	return 0;
-}
-
 async function kernelStatus(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	const jobId = requirePositional(positionals, 0, "kernel-job-id");
@@ -358,10 +332,21 @@ async function kernelEndpoints(ctx) {
 async function kernelWrite(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	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).");
+	// With --article the article's own content is the input, so only a standalone write needs one.
+	if (args.input === undefined && args.article_id === undefined) {
+		throw new CliError(
+			"Provide the brief with --body <text>, --file <path>, or --file - (stdin), or --article <uuid> to write from that article."
+		);
 	}
 	const result = await client.callTool("run_kernel", args);
+	// An article-bound run is a kernel job, polled by `kernel status` (get_kernel_run_status),
+	// not an endpoint run: the finished draft lands in the article, not here.
+	const kernelJobId = toolField(result, "kernel_job_id");
+	if (kernelJobId) {
+		ok(ctx, `Kernel run started into the article. Check progress with: kernel status ${kernelJobId}`);
+		printResult(io, flags, result);
+		return 0;
+	}
 	const runId = toolField(result, "run_id");
 	if (!runId) {
 		printResult(io, flags, result);

package/lib/commands/phantom.mjs

@@ -59,6 +59,7 @@ export const ARGS = {
 		customer_ref: { flag: "customer-ref" },
 		configure: { value: (flags) => (flags["no-configure"] === true ? false : undefined) },
 		config: { value: (flags) => readJsonObjectFlag(flags, "config") },
+		composition: { value: (flags) => readJsonObjectFlag(flags, "composition") },
 		client_domain: { flag: "client-domain" },
 		dry_run: { flag: "dry-run", type: "bool" },
 	},

package/package.json

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