@letterstory/cli 0.29.2 → 0.29.4

package/lib/cli.mjs

@@ -44,7 +44,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.29.2";
+export const VERSION = "0.29.4";
 
 // 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/kernel.mjs

@@ -93,14 +93,15 @@ export const ARGS = {
 		// 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. Same flag name as run_kernel's.
+		// 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` forcing content_kind to "document" — the map is one, so a field
+	// 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
 	// ratchet.
 	run_kernel: {
@@ -169,8 +170,9 @@ export const ARGS = {
 		// `[{"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.
+		// Hold the input's own shape and embedded media through the rewrite, on any kind that
+		// is decomposed. Default true; pass --no-preserve-shape to let the kernel restructure
+		// freely.
 		preserve_shape: { flag: "preserve-shape", type: "bool" },
 	},
 	create_kernel_endpoint: {
@@ -364,16 +366,22 @@ async function kernelEndpoint(ctx) {
 
 /**
  * The OTHER door: run the same pipeline against a document you already have, instead of
- * 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,
+ * writing a new one. Decomposed into a brief and GENERATED FRESH (content_kind: "article",
+ * defaulted 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.
  *
+ * IT IS NOT ITS OWN CONTENT KIND any more (2026-09-22). This used to send `document`, the one
+ * kind that held media — which meant `letterstory kernel write --read-as article` on the same
+ * file quietly dropped it. Holding what a text-only decompose cannot carry is now the default
+ * on every decomposed kind, so `polish` is `write` with the kind named for you, and nothing
+ * else. `document` still parses if you pass it; it resolves to `article`.
+ *
  * ASYNCHRONOUS, same as `write` — this used to be a separate, synchronous, unmetered "polish"
  * 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.
+ * 2026-09-17). It 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;
@@ -381,7 +389,7 @@ async function kernelPolish(ctx) {
 	if (args.input === undefined) {
 		throw new CliError("Provide the document with --body <text>, --file <path>, or --file - (stdin).");
 	}
-	args.content_kind = args.content_kind ?? "document";
+	args.content_kind = args.content_kind ?? "article";
 	const result = await client.callTool("run_kernel", args);
 	const runId = toolField(result, "run_id");
 	if (!runId) {

package/lib/commands/onboard.mjs

@@ -15,8 +15,8 @@
 //
 // IMPORTANT: the masthead name is committed when the site is created (it seeds the URL),
 // so to use a name other than the inferred one, pass --name BEFORE applying. The first
-// posts are written by background jobs (20-40min each); they're reported as job ids and
-// this command does not block on them — poll with `phantom-job status <job-id>`.
+// posts are written by background runs (20-60min each); they're reported as run ids and
+// this command does not block on them — poll with `collection run-status <run-id>`.
 //
 // `--accept-plan <path|->` closes the review loop: the apply PINS the plan instead of
 // recomputing it, so the masthead that was reviewed is the masthead that is committed. In one

package/package.json

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