@letterstory/cli 0.20.0 → 0.25.0

package/README.md

@@ -287,6 +287,18 @@ single fallback plan, the client's existing publications with an overlap warning
 custom-domain headroom. `mastheads` returns names that never carry the client's own name. Without
 `--plan-file`, `phantom-onboard <domain>` still plans from the homepage alone.
 
+To review a plan and then apply **that** plan, hand it back with `--accept-plan`. A bare
+onboarding computes the plan twice — once for the dry run you read, once inside the job — and
+the second masthead proposal need not match the first, so the name committed into the URL
+would not be the one you approved. `--accept-plan` pins it, implies `--accept`, and skips the
+second homepage read.
+
+```bash
+letterstory phantom-onboard acme.com --json > plan.json     # dry run: read it, edit nothing
+letterstory phantom-onboard acme.com --accept-plan plan.json
+jq '.plan' plan.json | letterstory phantom-onboard acme.com --accept-plan -
+```
+
 ## Content series
 
 A series is a coverage obligation, not a keyword bet: "content that looks like this",
@@ -326,6 +338,34 @@ letterstory kernel run --article <uuid> --kernel <uuid> [--brief "…" | --brief
 letterstory kernel status <kernel-job-id>
 ```
 
+### The standalone kernel endpoint
+
+`kernel write` and `kernel polish` hit the standalone door: prose comes back, nothing is
+saved into an article, and it is metered in kernel-run credits rather than the AI-usage gate.
+
+```bash
+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>
+# Follows the run and prints the ARTICLE when it lands. --no-wait returns the run id instead.
+```
+
+### Shredding
+
+```bash
+letterstory shredder run <endpoint-id> --file post.md --format markdown
+# Queues, follows the job, prints the finished DOCUMENT. Exits non-zero if the job lands
+# as error or degraded, so a script can branch on it without parsing the payload.
+
+letterstory shredder run <endpoint-id> --file post.md --no-wait   # just queue it
+letterstory shredder job <job-id>                                 # poll it yourself
+```
+
+Both follow loops poll every 15–20 s. `LETTERSTORY_POLL_INTERVAL_MS` overrides that — set
+it to `0` in CI so a test does not wait on a real interval.
+
 `phantom-job create --topic "…" --collection <uuid>` runs topic → draft → publish → rebuild
 end to end, with `phantom-job status <job-id>` to follow it.
 

package/lib/cli.mjs

@@ -44,7 +44,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.20.0";
+export const VERSION = "0.25.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.
@@ -82,6 +82,9 @@ const BOOLEAN_FLAGS = new Set([
 	"no-visuals",
 	"no-enhance",
 	"no-key",
+	// `collections activate <id> --no-topic-map` / `--no-headlines`
+	"no-topic-map",
+	"no-headlines",
 	"onboard",
 	"test",
 	"real",
@@ -205,6 +208,8 @@ Collections:
                           [--cover-canvas-type-id <uuid>|none] [--seo-market <cc>]
   collections delete <id> --yes
   collections assign <article-id> <collection-id>
+  collections activate <id> [--cadence <n>] [--approval manual|review_window|autopilot] [--no-topic-map] [--no-headlines]
+                           The review is done: topic map from the areas, first headlines, Planner on, queue filled
   collections autopen <id> [--template <key>|none] [--kernel-family <name>|org]
                            [--mention off|subtle|woven] [--outline-depth barebones|fleshed_out]
                            [--direction-gate true|false] [--auto-start true|false]
@@ -306,17 +311,25 @@ Writing kernels (kernels write the draft; they do not research — run research
 
   Standalone — prose back, nothing saved into an article (metered in kernel-run credits):
   kernel endpoints                                     Your kernel endpoints
+  kernel endpoint create --name <n> [--kernel <uuid>] [--shredder <endpoint-id>]
+                                                        New kernel endpoint, optionally bound
+                                                        to a kernel and an in-loop shredder
+  kernel endpoint delete <endpoint-id> --yes           Remove one
   kernel write <endpoint-id> (--body <text>|--file <path>|--file -)
-                             [--kernel <uuid>] [--words <n>] [--no-wait]
-                             [--shredder <uuid>]  shred every round in the loop, so the
-                                                  kernel judges the text that ships
-                             [--read-as brief|blog|outline|research|notes]
                                                         WRITE a new article from a headline,
                                                         outline, notes or a finished post.
-                                                        Follows the run unless --no-wait.
-  kernel polish <endpoint-id> (--body <html>|--file <path>) [--format auto|html]
-                                                        POLISH the document you have: prose
-                                                        reworded, your own markup kept
+                                                        Follows the run unless --no-wait, and
+                                                        prints the article when it lands.
+  kernel polish <endpoint-id> (--body <html>|--file <path>|--file -) [--no-wait]
+                                                        Run the SAME pipeline against a
+                                                        document you already have instead of
+                                                        writing a new one: prose reworded,
+                                                        your own markup kept, the same rules
+                                                        and jury as any other run. Follows the
+                                                        run unless --no-wait, and costs a run
+                                                        exactly like 'kernel write' does —
+                                                        there is no separate free, instant
+                                                        polish any more.
   kernel run-status <run-id>                           Poll a write started with 'kernel write'
   kernel runs [--endpoint <id>] [--limit <n>]          Recent endpoint writes (telemetry)
   kernel balance                                       Kernel runs left on this org
@@ -344,6 +357,13 @@ Phantom onboarding recipe (domain -> live phantom blog with first posts):
                                                        lane below: its direction AND pillars are
                                                        applied verbatim, so the site covers what
                                                        was approved.
+          [--accept-plan <path|->]                     Apply a plan you already reviewed,
+                                                       verbatim — the "plan" from a dry run, or
+                                                       a whole saved --json response. Implies
+                                                       --accept and skips re-planning, so the
+                                                       masthead you approved is the one committed
+                                                       (without it the apply re-reads the homepage
+                                                       and may propose a different name).
 
 Propose lane (the Fleet wizard's Plan and Name screens; persists nothing, spends nothing):
   ${bin === "phantom" ? "onboard" : "phantom-onboard"} propose [<client-domain>] [--about "the beat"] [--name X] [--json]
@@ -361,6 +381,15 @@ Propose lane (the Fleet wizard's Plan and Name screens; persists nothing, spends
                                                        --plan-id picks the plan) or a single plan
                                                        (--plan '<json>' inline, or - for stdin).
 
+What does this org still need? (the router — reads only, decides nothing):
+  ${bin === "phantom" ? "onboard" : "phantom-onboard"} plan                         Every onboarding step (context, main blog,
+                                                       Planner, CMS, phantom) with its status:
+                                                       done / running / ready / blocked, and what
+                                                       a blocked step is waiting on.
+  ${bin === "phantom" ? "onboard" : "phantom-onboard"} next                         The first ready step Letterstory recommends,
+                                                       as the exact command to run next. Optional
+                                                       steps are listed, never chosen.
+
 Collection onboarding (your OWN blog, on your org's domain — no provisioning):
   ${bin === "phantom" ? "onboard" : "phantom-onboard"} collection [--collection <uuid>] [--name "<collection name>"]
           [--about "the direction"] [--sitemap <url>] [--cms <provider>]
@@ -463,6 +492,9 @@ Shredder (diversify content produced outside Letterstory; structure preserved):
   shredder create --name <n>                           New endpoint (returns a callable public id)
   shredder delete <endpoint-id> --yes
   shredder run <endpoint-id> (--body <text>|--file <path>|--file -) [--coverage <0..1>] [--attempts <n>]
+                                                       [--format auto|html|markdown]
+                                                       what the text IS; 'auto' reads a document
+                                                       containing block-level HTML as HTML
                                                        [--aggression standard|high|max]
                                                        standard (default) keeps the piece's own terminology;
                                                        high rewrites more and may reword recurring terms;
@@ -476,8 +508,11 @@ Shredder (diversify content produced outside Letterstory; structure preserved):
                                                        [--sync]     wait inside one request (only for a few
                                                                     sentences — anything longer is cut off)
                                                        Shred prose through an endpoint (logs telemetry).
-                                                       Queues the work and follows it; a shred takes minutes
-                                                       and keeps running on the server if you stop waiting.
+                                                       Queues the work and follows it, printing the finished
+                                                       document; a shred takes minutes and keeps running on
+                                                       the server if you stop waiting. Exits non-zero if the
+                                                       job lands as error or degraded. Pace the polling with
+                                                       LETTERSTORY_POLL_INTERVAL_MS.
   shredder job <job-id>                                Poll a queued shred and print it when it lands
   shredder runs [--endpoint <id>] [--limit <n>]        Recent shred calls (telemetry), newest first
 

package/lib/commands/collections.mjs

@@ -43,6 +43,17 @@ export const ARGS = {
 		collection_id: { positional: 1, label: "collection-id", required: true },
 	},
 	// `collections autopen <id>` — a PATCH: only the flags given are sent.
+	// `collections activate <id>` — the review is done, turn the Planner on. Omitted
+	// knobs keep the collection's saved values, so nothing here carries a default:
+	// an absent flag must stay absent rather than becoming an opinion (see #1773).
+	activate_collection: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+		cadence_per_week: { flag: "cadence", type: "num" },
+		approval_mode: { flag: "approval", enum: ["manual", "review_window", "autopilot"] },
+		// `--no-topic-map` / `--no-headlines` mean "skip that step"; absent means "do it".
+		regenerate_topic_map: { value: (flags) => (flags["no-topic-map"] === undefined ? undefined : false) },
+		stock_headlines: { value: (flags) => (flags["no-headlines"] === undefined ? undefined : false) },
+	},
 	update_auto_pen_config: {
 		collection_id: { positional: 0, label: "collection-id", required: true },
 		// `--template none` clears the binding; the server takes null for that.
@@ -87,13 +98,38 @@ export async function cmdCollections(ctx) {
 			return collectionsAssign(rest);
 		case "autopen":
 			return collectionsAutoPen(rest);
+		case "activate":
+			return collectionsActivate(rest);
 		default:
 			throw new CliError(
-				`Unknown collections subcommand: ${sub ?? "(none)"}. Try: list, new, update, delete, assign, autopen`
+				`Unknown collections subcommand: ${sub ?? "(none)"}. Try: list, new, update, delete, assign, autopen, activate`
 			);
 	}
 }
 
+/**
+ * `collections activate <id>` — the review is done: build the topic map from the
+ * collection's content areas, seed headlines, turn the Planner on with the queue
+ * filled. The same activation the app's Guided review step runs on Continue.
+ * Omitted knobs keep the collection's saved values; the response says, per knob,
+ * whether it came from you, from the saved config, or from the default.
+ */
+async function collectionsActivate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.activate_collection, flags, positionals);
+	const result = await client.callTool("activate_collection", args);
+	if (result && result.activated === false) {
+		// The K1 floor, as data: say why, and name the tools that clear it.
+		io.error(`Not activated: ${result.reason}`);
+		for (const r of result.remedies ?? []) io.error(`  ${r.tool} — ${r.why}`);
+		printResult(io, flags, result);
+		return 1;
+	}
+	ok(ctx, result?.note ?? `Activated collection ${args.collection_id}.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
 async function collectionsList(ctx) {
 	const { client, flags, io } = ctx;
 	const result = await client.callTool("list_collections", {});

package/lib/commands/connectors.mjs

@@ -1,12 +1,12 @@
 // `connectors` — export finished articles to external CMSs/doc tools (Webflow,
-// Framer, Google Docs, Contentful) and check publish status. Ported from
-// phantomstory-cli's connectors.ts.
+// Framer, Google Docs, Contentful, GitHub) and check publish status. Ported
+// from phantomstory-cli's connectors.ts.
 
 import { CliError } from "../client.mjs";
 import { printResult, ok, argsFromFlags } from "./shared.mjs";
 
 const CMS_PROVIDERS = ["webflow", "framer", "sanity", "contentful"];
-const PUBLISH_CONNECTORS = ["webflow", "framer", "google_docs", "contentful"];
+const PUBLISH_CONNECTORS = ["webflow", "framer", "google_docs", "contentful", "github"];
 
 // How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
 // `scripts/parity-check.ts` compares these keys against each tool's published input schema.

package/lib/commands/kernel.mjs

@@ -16,7 +16,42 @@
 // unless you tell it not to.
 
 import { CliError } from "../client.mjs";
-import { flagStr, requireFlag, requirePositional, printResult, compact, ok, readBodyInput } from "./shared.mjs";
+import {
+	flagStr,
+	flagBool,
+	requireFlag,
+	requirePositional,
+	printResult,
+	compact,
+	ok,
+	readBodyInput,
+	toolField,
+	followJob,
+	argsFromFlags,
+} from "./shared.mjs";
+
+/**
+ * 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
+ * each tool's published input schema.
+ *
+ * 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.
+ */
+export const ARGS = {
+	create_kernel_endpoint: {
+		name: { flag: "name", required: true },
+		// Both optional bindings the tool has always accepted at create: which kernel
+		// writes, and which shredder (if any) runs inside the loop. Exposed rather than
+		// left as a known gap — an endpoint you cannot bind at create is one you have to
+		// go and fix in the app.
+		kernel_id: "kernel",
+		shredder_endpoint_id: "shredder",
+	},
+	delete_kernel_endpoint: {
+		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
+	},
+};
 
 export async function cmdKernel(ctx) {
 	const sub = ctx.positionals[0];
@@ -31,6 +66,8 @@ export async function cmdKernel(ctx) {
 			return kernelStatus(rest);
 		case "endpoints":
 			return kernelEndpoints(rest);
+		case "endpoint":
+			return kernelEndpoint(rest);
 		case "write":
 			return kernelWrite(rest);
 		case "polish":
@@ -43,7 +80,7 @@ export async function cmdKernel(ctx) {
 			return kernelBalance(rest);
 		default:
 			throw new CliError(
-				`Unknown kernel subcommand: ${sub ?? "(none)"}. Try: list, endpoints, write, polish, run-status, runs, balance, run, status`
+				`Unknown kernel subcommand: ${sub ?? "(none)"}. Try: list, endpoints, endpoint, write, polish, run-status, runs, balance, run, status`
 			);
 	}
 }
@@ -84,19 +121,6 @@ const POLL_INTERVAL_MS = 20_000;
 /** Stop following after this; the run keeps going and `run-status` picks it up. */
 const POLL_CEILING_MS = 45 * 60 * 1000;
 
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-/** The tool result is a text payload holding JSON; pull one field out, leniently. */
-function readToolField(result, field) {
-	const raw = result?.content?.[0]?.text;
-	if (typeof raw !== "string") return undefined;
-	try {
-		return JSON.parse(raw)?.[field];
-	} catch {
-		return undefined;
-	}
-}
-
 async function kernelEndpoints(ctx) {
 	const { client, flags, io } = ctx;
 	const result = await client.callTool("list_kernel_endpoints", {});
@@ -121,10 +145,20 @@ async function kernelWrite(ctx) {
 		// 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 = readToolField(result, "run_id");
+	const runId = toolField(result, "run_id");
 	if (!runId) {
 		printResult(io, flags, result);
 		return 0;
@@ -136,25 +170,76 @@ async function kernelWrite(ctx) {
 	}
 
 	ok(ctx, `Write started as ${runId}. Waiting — this keeps running on the server if you stop.`);
-	const deadline = Date.now() + POLL_CEILING_MS;
-	for (;;) {
-		await sleep(POLL_INTERVAL_MS);
-		const polled = await client.callTool("get_kernel_endpoint_run", { run_id: runId });
-		const status = readToolField(polled, "status");
-		if (status && status !== "running") {
-			ok(ctx, `Write ${status}.`);
-			printResult(io, flags, polled);
-			return status === "done" ? 0 : 1;
-		}
-		if (Date.now() > deadline) {
-			ok(ctx, `Still running after 45 minutes. Follow it with: letterstory kernel run-status ${runId}`);
-			printResult(io, flags, polled);
-			return 0;
+	let lastStatus;
+	const { settled, value: polled } = await followJob(
+		io,
+		async () => {
+			const r = await client.callTool("get_kernel_endpoint_run", { run_id: runId });
+			lastStatus = toolField(r, "status");
+			return { done: !!lastStatus && lastStatus !== "running" && lastStatus !== "queued", value: r };
+		},
+		{ intervalMs: POLL_INTERVAL_MS, ceilingMs: POLL_CEILING_MS }
+	);
+
+	if (!settled) {
+		ok(ctx, `Still running after 45 minutes. Follow it with: letterstory kernel run-status ${runId}`);
+		printResult(io, flags, polled);
+		return 0;
+	}
+	ok(ctx, `Write ${lastStatus}.`);
+	// The operator waited for the ARTICLE; print it, not the envelope. --json still
+	// gets the whole payload.
+	printResult(io, flags, polled, (v) => (typeof v?.article === "string" ? v.article : JSON.stringify(v, null, 2)));
+	return lastStatus === "done" ? 0 : 1;
+}
+
+/**
+ * `kernel endpoint create|delete` — the standalone endpoint's own CRUD.
+ *
+ * `create_kernel_endpoint` and `delete_kernel_endpoint` existed as tools with no
+ * command at all, so provisioning the thing `kernel write` runs against could
+ * only be done through the app or hand-written JSON.
+ */
+async function kernelEndpoint(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const action = positionals[0];
+	if (action === "create" || action === "new") {
+		const args = argsFromFlags(ARGS.create_kernel_endpoint, flags, positionals);
+		const name = args.name;
+		const result = await client.callTool("create_kernel_endpoint", args);
+		ok(ctx, `Created kernel endpoint "${name}".`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (action === "delete" || action === "rm") {
+		const id = requirePositional(positionals, 1, "endpoint-id");
+		if (!flags.yes) {
+			io.error(`Re-run with --yes to confirm: ${ctx.bin} kernel endpoint delete ${id} --yes`);
+			return 1;
 		}
+		const result = await client.callTool(
+			"delete_kernel_endpoint",
+			argsFromFlags(ARGS.delete_kernel_endpoint, flags, positionals)
+		);
+		ok(ctx, "Kernel endpoint deleted.");
+		printResult(io, flags, result);
+		return 0;
 	}
+	throw new CliError(`Unknown kernel endpoint action: ${action ?? "(none)"}. Try: create, delete`);
 }
 
-/** The OTHER door: reword the document you already have, keeping its own markup. */
+/**
+ * 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.
+ *
+ * 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
+ * `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");
@@ -167,10 +252,38 @@ async function kernelPolish(ctx) {
 		document,
 		format: flagStr(flags.format),
 	});
-	// Synchronous by nature: a polish is one pass over the sentences, not a multi-round write.
 	const result = await client.callTool("run_kernel", args);
-	printResult(io, flags, result);
-	return 0;
+	const runId = toolField(result, "run_id");
+	if (!runId) {
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (flags["no-wait"] === true) {
+		ok(ctx, `Polish started as ${runId}. Follow it with: letterstory kernel run-status ${runId}`);
+		printResult(io, flags, result);
+		return 0;
+	}
+
+	ok(ctx, `Polish 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_kernel_endpoint_run", { run_id: runId });
+			lastStatus = toolField(r, "status");
+			return { done: !!lastStatus && lastStatus !== "running" && lastStatus !== "queued", value: r };
+		},
+		{ intervalMs: POLL_INTERVAL_MS, ceilingMs: POLL_CEILING_MS }
+	);
+
+	if (!settled) {
+		ok(ctx, `Still running after 45 minutes. Follow it with: letterstory kernel run-status ${runId}`);
+		printResult(io, flags, polled);
+		return 0;
+	}
+	ok(ctx, `Polish ${lastStatus}.`);
+	printResult(io, flags, polled, (v) => (typeof v?.article === "string" ? v.article : JSON.stringify(v, null, 2)));
+	return lastStatus === "done" ? 0 : 1;
 }
 
 async function kernelRunStatus(ctx) {

package/lib/commands/onboard.mjs

@@ -17,6 +17,12 @@
 // 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>`.
+//
+// `--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
+// command the dry run's plan is carried into the apply automatically; the flag is for the
+// two-command shape (`onboard acme.com --json > plan.json`, read it, then `onboard acme.com
+// --accept-plan plan.json`), which is what an agent or a script actually does.
 
 // `onboard domain` is the ONE-SHOT parent: a bare company domain in (the org's registered
 // domain, from the API key), a fully-configured organization out — the main blog onboarded
@@ -66,6 +72,11 @@ const APPROVAL_MODES = ["autopilot", "review_window", "manual"];
 // How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
 // `scripts/parity-check.ts` compares these keys against each tool's published input schema.
 export const ARGS = {
+	// The router read. It takes no arguments at all — the org comes from the API
+	// key — but it still declares an entry, because the parity ratchet's rule is
+	// that a curated command's tool is DECLARED, not that it has flags. An empty
+	// map says "no inputs" explicitly, where a missing one says "nobody checked".
+	get_onboarding_plan: {},
 	onboard_collection: {
 		collection_id: "collection",
 		collection_name: "name",
@@ -114,6 +125,11 @@ export const ARGS = {
 		// --accept gates the two-call flow below (dry run, then apply) rather than being
 		// forwarded: the first call never sends it, the second always sends true.
 		accept: { internal: "false on the dry run, true on apply — decided by the command" },
+		// The reviewed plan, pinned so the apply does not recompute the masthead the user
+		// just approved (#1773 / C2). Like `accept`, the command decides it rather than a
+		// flag mapping straight through: it comes from `--accept-plan <path|->` /
+		// `--accept-plan-json`, or from the dry run this same command just printed.
+		plan: { internal: "the reviewed plan — from --accept-plan, or the dry run just printed" },
 		overrides: {
 			object: {
 				name: "name",
@@ -217,6 +233,38 @@ export function readTopicPlan(flags) {
 	return doc;
 }
 
+// The plan a caller already reviewed, handed back to be applied VERBATIM: `--accept-plan
+// <path|->` (or `--accept-plan-json '<json>'`). Accepts either the plan object itself or a
+// saved dry-run response, whose `plan` key holds it — so `onboard <domain> --json > plan.json`
+// then `onboard <domain> --accept-plan plan.json` is the whole review-then-accept loop.
+//
+// Why it exists: without a pinned plan the apply RE-PLANS — a second homepage read and a
+// second masthead proposal, which can answer differently than the one just approved, and
+// that name is committed into the URL when the site is created.
+export function readAcceptedPlan(flags) {
+	const raw = readTextInput(flags, "accept-plan-json", "accept-plan");
+	if (raw === undefined) return undefined;
+	let doc;
+	try {
+		doc = JSON.parse(raw);
+	} catch (err) {
+		throw new CliError(`--accept-plan is not valid JSON: ${err.message}`);
+	}
+	// A saved dry-run response wraps the plan; the plan itself does not.
+	const plan = doc && typeof doc === "object" && doc.plan && typeof doc.plan === "object" ? doc.plan : doc;
+	if (!plan || typeof plan !== "object" || typeof plan.description !== "string" || !plan.defaults) {
+		throw new CliError(
+			"--accept-plan must be the `plan` object from an onboard dry run (or the whole saved --json response)."
+		);
+	}
+	if (!plan.name) {
+		throw new CliError(
+			"That plan has no masthead name, and the name is committed at create. Re-run the dry run with --name <MastheadName> and accept the plan it returns."
+		);
+	}
+	return plan;
+}
+
 // The recipe's spelling under this binary, for next-step hints.
 function recipeName(ctx) {
 	return ctx.bin === "phantom" ? "onboard" : "phantom-onboard";
@@ -588,8 +636,108 @@ async function cmdOnboardDomain(ctx) {
 	return watchDomainJob(ctx, started.job_id);
 }
 
+// `onboard plan` — what does this organization still need? One read of get_onboarding_plan
+// (the router), printed as a table. `onboard next` prints the first ready step's exact CLI
+// invocation with what the facts already determine (the main collection's id) filled in.
+// Neither decides anything: an optional step is listed, never chosen.
+const STATUS_ORDER = ["ready", "running", "blocked", "done"];
+
+function formatPlanTable(plan) {
+	const rows = plan.steps.map((s) => [
+		s.id,
+		s.status,
+		s.disposition,
+		s.blocked_by.length
+			? s.blocked_by.join(", ")
+			: s.missing.length && s.status === "done"
+				? `(${s.missing.join(", ")})`
+				: "",
+		s.cli,
+	]);
+	const head = ["step", "status", "opinion", "blocked by", "run"];
+	const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i]).length)));
+	const line = (cells) =>
+		cells
+			.map((c, i) => String(c).padEnd(widths[i]))
+			.join("  ")
+			.trimEnd();
+	const lines = [line(head), line(widths.map((w) => "-".repeat(w))), ...rows.map(line)];
+	lines.push("");
+	lines.push(
+		plan.next
+			? `Next: ${plan.next} — ${plan.steps.find((s) => s.id === plan.next)?.why ?? ""}`
+			: plan.steps.every((s) => s.status === "done")
+				? "Nothing left: every step is done."
+				: "Nothing is ready to run — see the blocked-by column."
+	);
+	if (plan.optional_ready?.length) lines.push(`Optional and ready (needs a yes): ${plan.optional_ready.join(", ")}`);
+	return lines.join("\n");
+}
+
+function cliInvocation(ctx, step) {
+	const hint = Object.entries(step.args_hint ?? {});
+	// The generic door: `tool <name> --arg k=v` takes the schema's own keys.
+	if (/^tool /.test(step.cli)) {
+		const args = hint.map(([k, v]) => ` --arg ${k}=${v}`).join("");
+		return `${ctx.bin} ${step.cli}${args}`;
+	}
+	// A curated command: the main collection's id is `--collection` on every one that takes it.
+	const collection = step.args_hint?.collection_id ? ` --collection ${step.args_hint.collection_id}` : "";
+	return `${ctx.bin} ${step.cli}${collection}`;
+}
+
+async function cmdOnboardPlan(ctx) {
+	const plan = await ctx.client.callTool("get_onboarding_plan", {});
+	if (!Array.isArray(plan.steps)) throw new CliError("get_onboarding_plan did not return steps.");
+	printResult(ctx.io, ctx.flags, plan, formatPlanTable);
+	return 0;
+}
+
+async function cmdOnboardNext(ctx) {
+	const plan = await ctx.client.callTool("get_onboarding_plan", {});
+	if (!Array.isArray(plan.steps)) throw new CliError("get_onboarding_plan did not return steps.");
+	const next = plan.next ? plan.steps.find((s) => s.id === plan.next) : null;
+	if (!next) {
+		const running = plan.steps.find((s) => s.status === "running");
+		if (running) {
+			printResult(ctx.io, ctx.flags, running, (s) => `Waiting on "${s.id}": ${s.why}`);
+			return 0;
+		}
+		const optional = (plan.optional_ready ?? []).map((id) => plan.steps.find((s) => s.id === id)).filter(Boolean);
+		printResult(ctx.io, ctx.flags, plan, () =>
+			[
+				plan.steps.every((s) => s.status === "done")
+					? "Nothing left: every step is done."
+					: "Nothing is ready to run.",
+				...optional.map((s) => `Optional (needs a yes): ${s.id} — ${cliInvocation(ctx, s)}`),
+				...plan.steps
+					.filter((s) => s.status === "blocked")
+					.sort((a, b) => STATUS_ORDER.indexOf(a.status) - STATUS_ORDER.indexOf(b.status))
+					.map((s) => `Blocked: ${s.id} — ${s.why}`),
+			].join("\n")
+		);
+		return 0;
+	}
+	printResult(ctx.io, ctx.flags, next, (s) =>
+		[
+			`Next: ${s.title} (${s.disposition})`,
+			`  ${s.purpose}`,
+			s.prepare.length ? `  Read first: ${s.prepare.join(", ")}` : null,
+			`  Run:  ${cliInvocation(ctx, s)}`,
+			s.poll ? `  Poll: ${s.poll}` : null,
+			`  Docs: https://app.letterstory.com${s.docs}`,
+		]
+			.filter(Boolean)
+			.join("\n")
+	);
+	return 0;
+}
+
 export async function cmdOnboard(ctx) {
 	const { client, flags, io } = ctx;
+	// `onboard plan` / `onboard next` — the router: what does this org still need?
+	if (ctx.positionals[0] === "plan") return cmdOnboardPlan(ctx);
+	if (ctx.positionals[0] === "next") return cmdOnboardNext(ctx);
 	// `onboard collection …` — the client-blog variant (no <domain>; org from the key).
 	if (ctx.positionals[0] === "collection") {
 		return cmdOnboardCollection({ ...ctx, positionals: ctx.positionals.slice(1) });
@@ -612,39 +760,54 @@ export async function cmdOnboard(ctx) {
 	const domain = requirePositional(ctx.positionals, 0, "domain");
 	const overrides = overridesFromFlags(flags);
 
-	// Step 1: dry-run plan (accept defaults to false server-side). Persists nothing.
-	const plan = await client.callTool(
-		"onboard_phantom",
-		compact({ domain, overrides: Object.keys(overrides).length ? overrides : undefined })
-	);
-	ok(ctx, "Onboarding plan:");
-	printResult(io, flags, plan, formatPlan);
-
-	if (flagBool(flags["dry-run"])) return 0;
+	// A plan handed in with --accept-plan was reviewed already, and re-running the dry run
+	// would re-read the homepage and re-propose a masthead — exactly what pinning prevents.
+	// So it also stands in for --accept: you cannot hand back a plan you have not read.
+	let reviewedPlan = readAcceptedPlan(flags);
 
-	// Step 2: the review gate. A bare, unaccepted run stops here so nothing is provisioned
-	// by accident — re-run with --accept (or an override flag) once happy.
-	const overrideGiven = Object.keys(overrides).length > 0;
-	if (!flagBool(flags.accept) && !overrideGiven) {
-		ok(
-			ctx,
-			"Re-run with --accept to apply, or pass --about/--name/--cadence/--cover/--posts/--theme/--domain to adjust " +
-				`(or pick the beat and name first: ${recipeName(ctx)} propose / mastheads). ` +
-				"Note: --name is committed at create (it seeds the URL)."
-		);
-		return 0;
-	}
-	if (plan.proposed_name === null && flagStr(flags.name) === undefined) {
-		throw new CliError(
-			"No blog name available: the plan proposed none (strategy soft-failed). Pass --name <MastheadName> to apply."
+	if (!reviewedPlan) {
+		// Step 1: dry-run plan (accept defaults to false server-side). Persists nothing.
+		const dryRun = await client.callTool(
+			"onboard_phantom",
+			compact({ domain, overrides: Object.keys(overrides).length ? overrides : undefined })
 		);
+		ok(ctx, "Onboarding plan:");
+		printResult(io, flags, dryRun, formatPlan);
+
+		if (flagBool(flags["dry-run"])) return 0;
+
+		// Step 2: the review gate. A bare, unaccepted run stops here so nothing is provisioned
+		// by accident — re-run with --accept (or an override flag) once happy.
+		const overrideGiven = Object.keys(overrides).length > 0;
+		if (!flagBool(flags.accept) && !overrideGiven) {
+			ok(
+				ctx,
+				"Re-run with --accept to apply, or pass --about/--name/--cadence/--cover/--posts/--theme/--domain to adjust " +
+					`(or pick the beat and name first: ${recipeName(ctx)} propose / mastheads). ` +
+					"Note: --name is committed at create (it seeds the URL)."
+			);
+			return 0;
+		}
+		if (dryRun.proposed_name === null && flagStr(flags.name) === undefined) {
+			throw new CliError(
+				"No blog name available: the plan proposed none (strategy soft-failed). Pass --name <MastheadName> to apply."
+			);
+		}
+		// Apply the plan that was just printed, not a fresh one: an old server that does not
+		// return `plan` leaves this undefined and the job plans for itself, as before.
+		reviewedPlan = dryRun.plan;
 	}
 
 	// Step 3: apply — start the durable onboarding job.
 	ok(ctx, "Applying — starting the onboarding job…");
 	const started = await client.callTool(
 		"onboard_phantom",
-		compact({ domain, accept: true, overrides: Object.keys(overrides).length ? overrides : undefined })
+		compact({
+			domain,
+			accept: true,
+			overrides: Object.keys(overrides).length ? overrides : undefined,
+			plan: reviewedPlan,
+		})
 	);
 	const jobId = started.job_id;
 	if (!jobId) throw new CliError("onboard_phantom did not return a job id.");

package/lib/commands/shared.mjs

@@ -221,6 +221,58 @@ export async function pollUntil(io, poll, opts = {}) {
 	}
 }
 
+// Pull one field out of a tool result.
+//
+// `client.callTool` ALREADY unwraps the MCP envelope and parses the JSON, so a
+// tool result here is the payload itself. Two commands used to reach for
+// `result.content[0].text` — the envelope shape — which is always undefined
+// after unwrapping, so the job id was never found, the follow loop never ran,
+// and `--no-wait` never printed its hint. The envelope fallback below is kept
+// only so a raw result passed in from somewhere else still reads correctly.
+export function toolField(result, field) {
+	if (result && typeof result === "object" && field in result) return result[field];
+	const raw = result?.content?.[0]?.text;
+	if (typeof raw === "string") {
+		try {
+			return JSON.parse(raw)?.[field];
+		} catch {
+			return undefined;
+		}
+	}
+	return undefined;
+}
+
+// Follow a queued job to a terminal state, SLEEPING FIRST.
+//
+// Unlike `pollUntil`, which checks immediately: a shred or a kernel run takes
+// minutes and starts on the next tick, so an instant first poll only ever says
+// "queued". Sleeping first is also what makes the interval the operator's —
+// both loops used a file-local `setTimeout`, so `io.sleep` (and with it
+// LETTERSTORY_POLL_INTERVAL_MS) was ignored and nobody could pace them.
+//
+// Returns `{ settled, value }`. `settled:false` means the ceiling passed — the
+// caller decides what to say, because the job is still running on the server
+// and that is not an error.
+export async function followJob(io, poll, opts = {}) {
+	// The default is the command's own (a shred is slow; polling fast only burns
+	// requests). An operator who EXPLICITLY sets LETTERSTORY_POLL_INTERVAL_MS
+	// means it, and that is what makes the interval theirs — a CI run or a test
+	// harness sets it to 0 and the same loop runs without the wait.
+	const explicit = process.env.LETTERSTORY_POLL_INTERVAL_MS;
+	const intervalMs =
+		explicit !== undefined && explicit !== "" && Number.isFinite(Number(explicit))
+			? Number(explicit)
+			: (opts.intervalMs ?? 15000);
+	const ceilingMs = opts.ceilingMs ?? 30 * 60 * 1000;
+	const deadline = Date.now() + ceilingMs;
+	for (;;) {
+		await io.sleep(intervalMs);
+		const { done, value } = await poll();
+		if (done) return { settled: true, value };
+		if (Date.now() > deadline) return { settled: false, value };
+	}
+}
+
 // Read a text value from an inline flag, or from a file flag (a path, or "-" for
 // stdin). Returns undefined if neither flag was given, so callers can decide whether
 // that's an error. `readBodyInput` is the --body/--file pairing; the propose lane reads

package/lib/commands/shredder.mjs

@@ -13,6 +13,8 @@ import {
 	printResult,
 	compact,
 	ok,
+	toolField,
+	followJob,
 } from "./shared.mjs";
 
 export async function cmdShredder(ctx) {
@@ -83,8 +85,6 @@ async function shredderDelete(ctx) {
 const POLL_INTERVAL_MS = 15_000;
 const POLL_CEILING_MS = 30 * 60 * 1000;
 
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
 async function shredderRun(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	const id = requirePositional(positionals, 0, "endpoint-id");
@@ -105,6 +105,9 @@ async function shredderRun(ctx) {
 		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
@@ -132,36 +135,35 @@ async function shredderRun(ctx) {
 	}
 
 	ok(ctx, `Shred queued as ${jobId}. Waiting — this keeps running on the server if you stop.`);
-	const deadline = Date.now() + POLL_CEILING_MS;
-	for (;;) {
-		await sleep(POLL_INTERVAL_MS);
-		const polled = await client.callTool("get_shred_job", { job_id: jobId });
-		const status = readStatus(polled);
-		if (status && status !== "queued" && status !== "running") {
-			ok(ctx, `Shred ${status}.`);
-			printResult(io, flags, polled);
-			return status === "done" ? 0 : 1;
-		}
-		if (Date.now() > deadline) {
-			ok(ctx, `Still ${status ?? "running"} after 30 minutes. Poll it with: letterstory shredder job ${jobId}`);
-			printResult(io, flags, polled);
-			return 0;
-		}
-	}
-}
+	let lastStatus;
+	const { settled, value: polled } = await followJob(
+		io,
+		async () => {
+			const result = await client.callTool("get_shred_job", { job_id: jobId });
+			lastStatus = readStatus(result);
+			const terminal = !!lastStatus && lastStatus !== "queued" && lastStatus !== "running";
+			return { done: terminal, value: result };
+		},
+		{ intervalMs: POLL_INTERVAL_MS, ceilingMs: POLL_CEILING_MS }
+	);
 
-/** The tool result is a text payload holding JSON; pull one field out of it, leniently. */
-function readToolField(result, field) {
-	const raw = result?.content?.[0]?.text;
-	if (typeof raw !== "string") return undefined;
-	try {
-		return JSON.parse(raw)?.[field];
-	} catch {
-		return undefined;
+	if (!settled) {
+		ok(ctx, `Still ${lastStatus ?? "running"} after 30 minutes. Poll it with: letterstory shredder job ${jobId}`);
+		printResult(io, flags, polled);
+		return 0;
 	}
+	ok(ctx, `Shred ${lastStatus}.`);
+	// The operator followed this job to get their DOCUMENT, so print the document
+	// and not the envelope around it. `--json` still gets the whole payload, which
+	// is what a script piping this wants.
+	printResult(io, flags, polled, (v) => (typeof v?.text === "string" ? v.text : JSON.stringify(v, null, 2)));
+	// A job that landed as error or degraded is not a success, and a script that
+	// pipes this needs to know without parsing the payload.
+	return lastStatus === "done" ? 0 : 1;
 }
-const readJobId = (result) => readToolField(result, "job_id");
-const readStatus = (result) => readToolField(result, "status");
+
+const readJobId = (result) => toolField(result, "job_id");
+const readStatus = (result) => toolField(result, "status");
 
 async function shredderJob(ctx) {
 	const { client, positionals, flags, io } = ctx;

package/package.json

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