@letterstory/cli 0.19.0 → 0.23.0

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
@@ -46,18 +52,119 @@
 import { CliError } from "../client.mjs";
 import {
 	flagStr,
-	flagNum,
 	flagBool,
 	requirePositional,
 	printResult,
+	refuseUnknownFlags,
 	compact,
 	ok,
 	pollUntil,
 	readTextInput,
+	argsFromFlags,
 } from "./shared.mjs";
 
 const COVER_STYLES = ["editorial_image", "full_ai", "line_art"];
 const DOMAIN_MODES = ["subdomain", "buy_now", "connect_later"];
+const SEER_MODES = ["suggest", "skip"];
+const CMS_PROVIDERS = ["webflow", "framer", "sanity", "contentful"];
+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",
+		direction: ["about", "direction"],
+		sitemap_url: "sitemap",
+		// Source the existing blog from a connected CMS instead of a sitemap.
+		cms_provider: { flag: "cms", enum: CMS_PROVIDERS },
+		// Planner activation (#1731): the same one-call activation the app's Guided review
+		// step performs. Off unless asked for; needs a user-scoped key (an acting user).
+		enable_planner: { flag: "enable-planner", type: "bool" },
+		cadence_per_week: { flag: "cadence", type: "num" },
+		approval_mode: { flag: "approval", enum: APPROVAL_MODES },
+	},
+	get_collection_onboard_status: {
+		job_id: { internal: "the job id onboard_collection just returned" },
+	},
+	sync_collection_sitemap: {
+		collection_id: "collection",
+	},
+	onboard_domain: {
+		direction: ["about", "direction"],
+		sitemap_url: "sitemap",
+		cms_provider: { flag: "cms", enum: CMS_PROVIDERS },
+		collection_name: "name",
+		phantom: {
+			object: {
+				enabled: { flag: "no-phantom", type: "bool", invert: true },
+				posts_to_seed: { flag: "posts", type: "num" },
+				name: "phantom-name",
+				site_domain: "site-domain",
+				domain_mode: { flag: "domain-mode", enum: DOMAIN_MODES },
+			},
+		},
+		seers: { flag: "seers", enum: SEER_MODES },
+		visuals: { flag: "no-visuals", type: "bool", invert: true },
+		enhance: { flag: "no-enhance", type: "bool", invert: true },
+		is_test: { flag: "test", type: "bool" },
+		readiness_minutes: { flag: "readiness-minutes", type: "num" },
+		client_email: "client-email",
+	},
+	get_domain_onboard_status: {
+		job_id: "attach",
+	},
+	onboard_phantom: {
+		domain: { positional: 0, label: "domain", required: true },
+		// --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",
+				cadence_per_week: { flag: "cadence", type: "num" },
+				cover_canvas: { flag: "cover", enum: COVER_STYLES },
+				theme: "theme",
+				posts_to_seed: { flag: "posts", type: "num" },
+				// The highest-leverage override: it becomes the planner's steering prompt, so it
+				// shapes the topic map and every post, not just the masthead. A chosen topic
+				// plan (--plan-file) supplies it when no --about is given.
+				direction: {
+					value: (flags, _p, extra) =>
+						flagStr(flags.about) ?? flagStr(flags.direction) ?? extra.plan?.direction,
+				},
+				// The approved plan's content areas become the topic map's pillars VERBATIM.
+				pillars: { value: (_f, _p, extra) => extra.plan?.pillars },
+				site_domain: "domain",
+				domain_mode: { flag: "domain-mode", enum: DOMAIN_MODES },
+				is_test: { flag: "real", type: "bool", invert: true },
+			},
+		},
+	},
+	get_phantom_onboard_status: {
+		job_id: { internal: "the job id onboard_phantom just returned" },
+	},
+	propose_phantom_plan: {
+		client_domain: { positional: 0, label: "client-domain" },
+		direction: ["about", "direction"],
+		name: "name",
+	},
+	propose_phantom_mastheads: {
+		client_domain: { positional: 0, label: "client-domain", required: true },
+		plan: { value: (_f, _p, extra) => extra.plan },
+	},
+};
 
 function formatPlan(plan) {
 	const lines = [
@@ -126,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";
@@ -191,11 +330,7 @@ function formatMastheads(r, plan) {
 // because the tool falls back to the org's own recorded domain (the key's org IS the client).
 async function cmdOnboardPropose(ctx) {
 	const { client, flags, io } = ctx;
-	const args = compact({
-		client_domain: ctx.positionals[0],
-		direction: flagStr(flags.about) ?? flagStr(flags.direction),
-		name: flagStr(flags.name),
-	});
+	const args = argsFromFlags(ARGS.propose_phantom_plan, flags, ctx.positionals);
 	ok(ctx, "Proposing…");
 	const proposal = await client.callTool("propose_phantom_plan", args);
 	printResult(io, flags, proposal, formatProposal);
@@ -219,7 +354,10 @@ async function cmdOnboardMastheads(ctx) {
 		);
 	}
 	ok(ctx, `Proposing mastheads for "${plan.title}"…`);
-	const result = await client.callTool("propose_phantom_mastheads", { client_domain: clientDomain, plan });
+	const result = await client.callTool(
+		"propose_phantom_mastheads",
+		argsFromFlags(ARGS.propose_phantom_mastheads, flags, ctx.positionals, { plan })
+	);
 	printResult(io, flags, result, (r) => formatMastheads(r, plan));
 	if (result.options?.length) {
 		ok(
@@ -234,35 +372,13 @@ async function cmdOnboardMastheads(ctx) {
 function overridesFromFlags(flags) {
 	// A chosen topic plan pins direction + pillars; an explicit --about still wins on direction.
 	const plan = readTopicPlan(flags);
-	const cover = flagStr(flags.cover);
-	if (cover !== undefined && !COVER_STYLES.includes(cover)) {
-		throw new CliError(`--cover must be one of: ${COVER_STYLES.join(", ")}`);
-	}
-	const domainMode = flagStr(flags["domain-mode"]);
-	if (domainMode !== undefined && !DOMAIN_MODES.includes(domainMode)) {
-		throw new CliError(`--domain-mode must be one of: ${DOMAIN_MODES.join(", ")}`);
-	}
-	const siteDomain = flagStr(flags.domain);
+	const overrides = argsFromFlags(ARGS.onboard_phantom.overrides.object, flags, [], { plan });
 	// buy_now spends real money against a 2-per-org cap; refusing the mismatch here beats
 	// silently downgrading it to a subdomain launch the caller didn't ask for.
-	if (domainMode && domainMode !== "subdomain" && !siteDomain) {
-		throw new CliError(`--domain-mode ${domainMode} needs --domain <bare-domain>`);
-	}
-	return compact({
-		name: flagStr(flags.name),
-		cadence_per_week: flagNum(flags.cadence),
-		cover_canvas: cover,
-		theme: flagStr(flags.theme),
-		posts_to_seed: flagNum(flags.posts),
-		// The highest-leverage override: it becomes the planner's steering prompt, so it
-		// shapes the topic map and every post, not just the masthead.
-		direction: flagStr(flags.about) ?? flagStr(flags.direction) ?? plan?.direction,
-		// The approved plan's content areas become the topic map's pillars VERBATIM.
-		pillars: plan?.pillars,
-		site_domain: siteDomain,
-		domain_mode: domainMode,
-		is_test: flagBool(flags["real"]) ? false : undefined,
-	});
+	if (overrides.domain_mode && overrides.domain_mode !== "subdomain" && !overrides.site_domain) {
+		throw new CliError(`--domain-mode ${overrides.domain_mode} needs --domain <bare-domain>`);
+	}
+	return overrides;
 }
 
 // Final readback of a collection-onboarding job — the counts the engine PERSISTED.
@@ -282,7 +398,9 @@ function formatCollectionStatus(s) {
 			`  series:              ${r.series ?? 0}`,
 			`  open topics:         ${r.spokes_open ?? 0} (${r.spokes_seo_bound ?? 0} SEO-bound)`,
 			`  headlines suggested: ${r.headlines_suggested ?? 0}`,
-			`  Review them in Headlines & Queue — the Planner is configured but OFF (manual approval).`
+			s.enable_planner
+				? `  Planner:             ON — ${s.cadence_per_week ?? "?"}/week, ${s.approval_mode ?? "manual"} approval, queue filled.`
+				: `  Review them in Headlines & Queue — the Planner is configured but OFF (pass --enable-planner to turn it on).`
 		);
 	}
 	return lines.join("\n");
@@ -302,14 +420,38 @@ async function cmdOnboardCollection(ctx) {
 		);
 	}
 
-	const args = compact({
-		collection_id: flagStr(flags.collection),
-		collection_name: flagStr(flags.name),
-		direction: flagStr(flags.about) ?? flagStr(flags.direction),
-		sitemap_url: flagStr(flags.sitemap),
-		// Source the existing blog from a connected CMS instead of a sitemap.
-		cms_provider: flagStr(flags.cms),
-	});
+	// READ PATHS FIRST, before anything that writes. `--status` and `--attach` mean here
+	// exactly what they mean on `onboard domain`: show me the job, do not start one.
+	// They had no branch at all, so they fell through to onboard_collection and STARTED A
+	// SECOND ONBOARDING — a read verb that spent money and left a duplicate collection.
+	const attach = flagStr(flags.attach);
+	if (attach) {
+		const s = await client.callTool("get_collection_onboard_status", { job_id: attach });
+		printResult(ctx.io, flags, s, formatCollectionStatus);
+		return 0;
+	}
+	if (flagBool(flags.status)) {
+		const collectionId = flagStr(flags.collection);
+		const s = await client.callTool(
+			"get_collection_onboard_status",
+			collectionId ? { collection_id: collectionId } : {}
+		);
+		printResult(ctx.io, flags, s, formatCollectionStatus);
+		return 0;
+	}
+
+	// Everything below WRITES. A flag we do not understand is refused rather than ignored:
+	// the ARGS map that builds the call is the list of what may be passed to it.
+	refuseUnknownFlags(ctx, ARGS.onboard_collection, ["status", "attach", "watch", "no-wait", "domain"]);
+
+	const args = argsFromFlags(ARGS.onboard_collection, flags, ctx.positionals);
+	// --cadence / --approval only mean something once the Planner is being turned on; a
+	// silently ignored flag is exactly the kind of invisible opinion this lane exists to remove.
+	if ((args.cadence_per_week !== undefined || args.approval_mode !== undefined) && !args.enable_planner) {
+		throw new CliError(
+			"--cadence and --approval only apply with --enable-planner (the Planner stays OFF otherwise)."
+		);
+	}
 
 	ok(ctx, "Starting collection onboarding…");
 	const started = await client.callTool("onboard_collection", args);
@@ -357,13 +499,13 @@ async function cmdOnboardCollection(ctx) {
 // bounded per run, so it returns synchronously.
 async function cmdOnboardSyncSitemap(ctx) {
 	const { client, flags } = ctx;
-	const collectionId = flagStr(flags.collection);
-	if (!collectionId) {
+	const args = argsFromFlags(ARGS.sync_collection_sitemap, flags, ctx.positionals);
+	if (!args.collection_id) {
 		throw new CliError("onboard sync-sitemap requires --collection <uuid>.");
 	}
 
 	ok(ctx, "Re-checking the sitemap…");
-	const result = await client.callTool("sync_collection_sitemap", { collection_id: collectionId });
+	const result = await client.callTool("sync_collection_sitemap", args);
 
 	printResult(ctx.io, flags, result, (r) =>
 		[
@@ -383,9 +525,6 @@ async function cmdOnboardSyncSitemap(ctx) {
 	return 0;
 }
 
-const SEER_MODES = ["suggest", "skip"];
-const CMS_PROVIDERS = ["webflow", "framer", "sanity", "contentful"];
-
 // Final readback of a domain-onboarding job — the counts the engine PERSISTED.
 export function formatDomainStatus(s) {
 	const r = s.result ?? {};
@@ -474,35 +613,7 @@ async function cmdOnboardDomain(ctx) {
 		return 0;
 	}
 
-	const seers = flagStr(flags.seers);
-	if (seers !== undefined && !SEER_MODES.includes(seers)) {
-		throw new CliError(`--seers must be one of: ${SEER_MODES.join(", ")}`);
-	}
-	const cms = flagStr(flags.cms);
-	if (cms !== undefined && !CMS_PROVIDERS.includes(cms)) {
-		throw new CliError(`--cms must be one of: ${CMS_PROVIDERS.join(", ")}`);
-	}
-	const posts = flagNum(flags.posts);
-	const phantom = compact({
-		enabled: flagBool(flags["no-phantom"]) ? false : undefined,
-		posts_to_seed: posts,
-		name: flagStr(flags["phantom-name"]),
-		site_domain: flagStr(flags["site-domain"]),
-		domain_mode: flagStr(flags["domain-mode"]),
-	});
-	const args = compact({
-		direction: flagStr(flags.about) ?? flagStr(flags.direction),
-		sitemap_url: flagStr(flags.sitemap),
-		cms_provider: cms,
-		collection_name: flagStr(flags.name),
-		phantom: Object.keys(phantom).length ? phantom : undefined,
-		seers,
-		visuals: flagBool(flags["no-visuals"]) ? false : undefined,
-		enhance: flagBool(flags["no-enhance"]) ? false : undefined,
-		is_test: flagBool(flags.test) ? true : undefined,
-		readiness_minutes: flagNum(flags["readiness-minutes"]),
-		client_email: flagStr(flags["client-email"]),
-	});
+	const args = argsFromFlags(ARGS.onboard_domain, flags, ctx.positionals);
 
 	ok(ctx, "Starting domain onboarding…");
 	const started = await client.callTool("onboard_domain", args);
@@ -525,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) });
@@ -549,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);
+	// 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);
 
-	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 (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.");