@letterstory/cli 0.19.0 → 0.20.0

package/lib/cli.mjs

@@ -44,7 +44,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.19.0";
+export const VERSION = "0.20.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.
@@ -85,6 +85,13 @@ const BOOLEAN_FLAGS = new Set([
 	"onboard",
 	"test",
 	"real",
+	// `phantom-onboard collection --enable-planner`, `strategy sitemap --posts-only`, and the
+	// `strategy positioning set --clear-*` switches: value-less, and each sits next to a value.
+	"enable-planner",
+	"posts-only",
+	"clear-topics",
+	"clear-stances",
+	"clear-avoid",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -194,7 +201,8 @@ Reviewers:
 Collections:
   collections list                                   List your collections
   collections new --name <n> [--description <text>]
-  collections update <id> [--name] [--description] [--cadence-target <n>] [--cadence-period week|month] [--cover-canvas-type-id <uuid>|none]
+  collections update <id> [--name] [--description] [--cadence-target <n>] [--cadence-period week|month]
+                          [--cover-canvas-type-id <uuid>|none] [--seo-market <cc>]
   collections delete <id> --yes
   collections assign <article-id> <collection-id>
   collections autopen <id> [--template <key>|none] [--kernel-family <name>|org]
@@ -245,11 +253,11 @@ Connectors:
                                                        Wire a collection to a CMS + field mapping
 
 Strategy & onboarding:
-  strategy company get | set [--name] [--domain] [--manifesto <text>|--manifesto-file <path>]
+  strategy company get | set [--name] [--domain] [--market <cc>] [--manifesto <text>|--manifesto-file <path>]
   strategy positioning get | set [--topic <t> …] [--stance <s> …] [--avoid <t> …]
                                  [--clear-topics] [--clear-stances] [--clear-avoid]
   strategy competitors list | add <name> <domain>
-  strategy sitemap --collection <uuid> --url <sitemap_url> [--sub <url> …] [--pattern <glob>]
+  strategy sitemap --collection <uuid> --url <sitemap_url> [--sub <url> …] [--pattern <glob>] [--posts-only]
   strategy topics list --collection <uuid>             List the topic map's clusters/spokes
   strategy topics set --collection <uuid> (--topic <topic-id> | --suggestion <suggestion-id>)
   suggestions list <collection_id>                     List pending strategy suggestions + their auto-apply countdown
@@ -355,7 +363,8 @@ Propose lane (the Fleet wizard's Plan and Name screens; persists nothing, spends
 
 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>] [--watch]
+          [--about "the direction"] [--sitemap <url>] [--cms <provider>]
+          [--enable-planner [--cadence <n/week>] [--approval manual|review_window|autopilot]] [--watch]
                                                        Import the existing blog from its sitemap
                                                        (auto-discovered from the org's domain unless
                                                        --sitemap pins one) OR from a connected CMS with
@@ -363,7 +372,12 @@ Collection onboarding (your OWN blog, on your org's domain — no provisioning):
                                                        derive content areas + series, build the topic
                                                        map, bind SEO demand, and stock Headlines & Queue.
                                                        Omit --collection to create a fresh one (--name,
-                                                       default Blog). The Planner stays OFF (manual approval).
+                                                       default Blog). The Planner stays OFF unless you
+                                                       pass --enable-planner, which turns it on at the
+                                                       chosen cadence and approval and fills the queue
+                                                       (same activation as the app's Guided review step;
+                                                       needs a user-scoped key). --approval defaults to
+                                                       manual: nothing publishes unreviewed.
   ${bin === "phantom" ? "onboard" : "phantom-onboard"} sync-sitemap --collection <uuid>
                                                        Re-check an already-onboarded blog's sitemap
                                                        right now instead of waiting for its cadence

package/lib/commands/collections.mjs

@@ -2,7 +2,71 @@
 // Ported from phantomstory-cli's collections.ts.
 
 import { CliError } from "../client.mjs";
-import { flagStr, flagNum, requireFlag, requirePositional, printResult, compact, ok } from "./shared.mjs";
+import { flagStr, printResult, ok, argsFromFlags } from "./shared.mjs";
+
+// `--flag none|off|""` clears a nullable field; the server takes null for that.
+const clearable = (flag) => ({
+	value: (flags) => {
+		const v = flagStr(flags[flag]);
+		if (v === undefined) return undefined;
+		return ["none", "off", ""].includes(v.toLowerCase()) ? null : v;
+	},
+});
+
+// A `--flag false` boolean (the value is the string "false"; anything else is true).
+const stringBool = (flag) => ({
+	value: (flags) => (flags[flag] === undefined ? undefined : flags[flag] !== "false"),
+});
+
+// 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 = {
+	list_collections: {},
+	create_collection: {
+		name: { flag: "name", required: true },
+		description: "description",
+	},
+	update_collection: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+		name: "name",
+		description: "description",
+		cadence_target: { flag: "cadence-target", type: "num" },
+		cadence_period: { flag: "cadence-period", enum: ["week", "month"] },
+		cover_canvas_type_id: clearable("cover-canvas-type-id"),
+		seo_market: "seo-market",
+	},
+	delete_collection: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	assign_article_to_collection: {
+		article_id: { positional: 0, label: "article-id", required: true },
+		collection_id: { positional: 1, label: "collection-id", required: true },
+	},
+	// `collections autopen <id>` — a PATCH: only the flags given are sent.
+	update_auto_pen_config: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+		// `--template none` clears the binding; the server takes null for that.
+		template_key: clearable("template"),
+		outline: {
+			object: {
+				depth: "outline-depth",
+				direction_gate: stringBool("direction-gate"),
+			},
+		},
+		kernel: {
+			object: {
+				family: {
+					value: (flags) => {
+						const v = flagStr(flags["kernel-family"]);
+						return v === undefined ? undefined : v === "org" ? null : v;
+					},
+				},
+			},
+		},
+		mention: { object: { degree: "mention" } },
+		auto_start_on_curate: stringBool("auto-start"),
+	},
+};
 
 export async function cmdCollections(ctx) {
 	const sub = ctx.positionals[0];
@@ -39,35 +103,19 @@ async function collectionsList(ctx) {
 
 async function collectionsNew(ctx) {
 	const { client, flags, io } = ctx;
-	const name = requireFlag(flags, "name");
-	const args = compact({ name, description: flagStr(flags.description) });
+	const args = argsFromFlags(ARGS.create_collection, flags);
 	const result = await client.callTool("create_collection", args);
-	ok(ctx, `Created collection "${name}".`);
+	ok(ctx, `Created collection "${args.name}".`);
 	printResult(io, flags, result);
 	return 0;
 }
 
 async function collectionsUpdate(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const id = requirePositional(positionals, 0, "collection-id");
-	const coverCanvasTypeId = flagStr(flags["cover-canvas-type-id"]);
-	const patch = compact({
-		collection_id: id,
-		name: flagStr(flags.name),
-		description: flagStr(flags.description),
-		cadence_target: flagNum(flags["cadence-target"]),
-		cadence_period: flagStr(flags["cadence-period"]),
-	});
-	if (coverCanvasTypeId !== undefined) {
-		// compact() drops undefined, not null — set it after so "none"/"off" can clear
-		// the field instead of being dropped. Same convention as `webhook set --url none`.
-		patch.cover_canvas_type_id = ["none", "off", ""].includes(coverCanvasTypeId.toLowerCase())
-			? null
-			: coverCanvasTypeId;
-	}
+	const patch = argsFromFlags(ARGS.update_collection, flags, positionals);
 	if (Object.keys(patch).length <= 1) {
 		throw new CliError(
-			"Nothing to update — pass at least one of --name/--description/--cadence-target/--cadence-period/--cover-canvas-type-id."
+			"Nothing to update — pass at least one of --name/--description/--cadence-target/--cadence-period/--cover-canvas-type-id/--seo-market."
 		);
 	}
 	const result = await client.callTool("update_collection", patch);
@@ -78,12 +126,12 @@ async function collectionsUpdate(ctx) {
 
 async function collectionsDelete(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const id = requirePositional(positionals, 0, "collection-id");
+	const args = argsFromFlags(ARGS.delete_collection, flags, positionals);
 	if (!flags.yes) {
-		io.error(`Re-run with --yes to confirm: ${ctx.bin} collections delete ${id} --yes`);
+		io.error(`Re-run with --yes to confirm: ${ctx.bin} collections delete ${args.collection_id} --yes`);
 		return 1;
 	}
-	const result = await client.callTool("delete_collection", { collection_id: id });
+	const result = await client.callTool("delete_collection", args);
 	ok(ctx, "Collection deleted.");
 	printResult(io, flags, result);
 	return 0;
@@ -91,12 +139,10 @@ async function collectionsDelete(ctx) {
 
 async function collectionsAssign(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const articleId = requirePositional(positionals, 0, "article-id");
-	const collectionId = requirePositional(positionals, 1, "collection-id");
-	const result = await client.callTool("assign_article_to_collection", {
-		article_id: articleId,
-		collection_id: collectionId,
-	});
+	const result = await client.callTool(
+		"assign_article_to_collection",
+		argsFromFlags(ARGS.assign_article_to_collection, flags, positionals)
+	);
 	ok(ctx, "Article assigned.");
 	printResult(io, flags, result);
 	return 0;
@@ -111,27 +157,7 @@ async function collectionsAssign(ctx) {
  */
 async function collectionsAutoPen(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const collectionId = requirePositional(positionals, 0, "collection-id");
-	const patch = { collection_id: collectionId };
-
-	// `--template none` clears the binding; the server takes null for that.
-	const template = flagStr(flags.template);
-	if (template !== undefined) patch.template_key = template === "none" ? null : template;
-
-	const kernelFamily = flagStr(flags["kernel-family"]);
-	if (kernelFamily !== undefined) patch.kernel = { family: kernelFamily === "org" ? null : kernelFamily };
-
-	const mention = flagStr(flags.mention);
-	if (mention !== undefined) patch.mention = { degree: mention };
-
-	const depth = flagStr(flags["outline-depth"]);
-	if (depth !== undefined) patch.outline = { ...(patch.outline ?? {}), depth };
-
-	if (flags["direction-gate"] !== undefined) {
-		patch.outline = { ...(patch.outline ?? {}), direction_gate: flags["direction-gate"] !== "false" };
-	}
-	if (flags["auto-start"] !== undefined) patch.auto_start_on_curate = flags["auto-start"] !== "false";
-
+	const patch = argsFromFlags(ARGS.update_auto_pen_config, flags, positionals);
 	if (Object.keys(patch).length === 1) {
 		throw new CliError(
 			"Nothing to change. Pass at least one of --template, --kernel-family, --mention, --outline-depth, --direction-gate, --auto-start."
@@ -139,7 +165,7 @@ async function collectionsAutoPen(ctx) {
 	}
 
 	const result = await client.callTool("update_auto_pen_config", patch);
-	ok(ctx, `Auto-Pen settings updated for ${collectionId}.`);
+	ok(ctx, `Auto-Pen settings updated for ${patch.collection_id}.`);
 	printResult(io, flags, result);
 	return 0;
 }

package/lib/commands/connectors.mjs

@@ -3,7 +3,62 @@
 // phantomstory-cli's connectors.ts.
 
 import { CliError } from "../client.mjs";
-import { flagStr, flagBool, requireFlag, requirePositional, printResult, compact, ok } from "./shared.mjs";
+import { printResult, ok, argsFromFlags } from "./shared.mjs";
+
+const CMS_PROVIDERS = ["webflow", "framer", "sanity", "contentful"];
+const PUBLISH_CONNECTORS = ["webflow", "framer", "google_docs", "contentful"];
+
+// 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 = {
+	list_publish_targets: {},
+	publish_to_connector: {
+		article_id: { positional: 0, label: "article-id", required: true },
+		connector: { flag: "to", required: true, enum: PUBLISH_CONNECTORS },
+		target_id: { flag: "target", required: true },
+		flow_run_id: "flow-run",
+		// A re-publish whose external item was deleted or unpublished in the client's CMS
+		// is refused, and the refusal explains itself. --confirm-missing-target is the
+		// answer to that specific question: it re-creates / re-publishes the item there.
+		// Deliberately not bundled into a general --yes, and never set by default.
+		confirm_missing_target: { flag: "confirm-missing-target", type: "bool" },
+	},
+	get_publish_status: {
+		connector: { flag: "connector", required: true, enum: PUBLISH_CONNECTORS },
+		publish_id: { flag: "publish-id", required: true },
+	},
+	import_from_cms: {
+		collection_id: "collection",
+		provider: { flag: "provider", enum: CMS_PROVIDERS },
+	},
+	connect_cms: {
+		provider: { flag: "provider", required: true, enum: CMS_PROVIDERS },
+		// api_token is required for every provider; the rest are provider-specific.
+		api_token: { flag: "token", required: true },
+		project_url: "project-url",
+		auto_deploy: { flag: "auto-deploy", type: "bool", negate: "no-auto-deploy" },
+		project_id: "project-id",
+		dataset: "dataset",
+		project_name: "project-name",
+		workspace_name: "workspace",
+		space_id: "space-id",
+		environment_id: "environment",
+		space_name: "space-name",
+		default_locale: "locale",
+	},
+	disconnect_cms: {
+		provider: { flag: "provider", required: true, enum: CMS_PROVIDERS },
+	},
+	list_cms_connections: {},
+	list_cms_mappings: {
+		provider: { flag: "provider", required: true, enum: CMS_PROVIDERS },
+	},
+	bind_collection_cms: {
+		collection_id: { flag: "collection", required: true },
+		provider: { flag: "provider", required: true, enum: CMS_PROVIDERS },
+		mapping_id: "mapping",
+	},
+};
 
 export async function cmdConnectors(ctx) {
 	const sub = ctx.positionals[0];
@@ -46,31 +101,16 @@ async function connectorsList(ctx) {
 
 async function connectorsPublish(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const articleId = requirePositional(positionals, 0, "article-id");
-	const to = requireFlag(flags, "to");
-	const target = requireFlag(flags, "target");
-	// A re-publish whose external item was deleted or unpublished in the client's CMS
-	// is refused, and the refusal explains itself. --confirm-missing-target is the
-	// answer to that specific question: it re-creates / re-publishes the item there.
-	// Deliberately not bundled into a general --yes, and never set by default.
-	const args = compact({
-		article_id: articleId,
-		connector: to,
-		target_id: target,
-		flow_run_id: flagStr(flags["flow-run"]),
-		confirm_missing_target: flagBool(flags["confirm-missing-target"]) || undefined,
-	});
+	const args = argsFromFlags(ARGS.publish_to_connector, flags, positionals);
 	const result = await client.callTool("publish_to_connector", args);
-	ok(ctx, `Publishing to ${to}.`);
+	ok(ctx, `Publishing to ${args.connector}.`);
 	printResult(io, flags, result);
 	return 0;
 }
 
 async function connectorsStatus(ctx) {
 	const { client, flags, io } = ctx;
-	const connector = requireFlag(flags, "connector");
-	const publishId = requireFlag(flags, "publish-id");
-	const result = await client.callTool("get_publish_status", { connector, publish_id: publishId });
+	const result = await client.callTool("get_publish_status", argsFromFlags(ARGS.get_publish_status, flags));
 	printResult(io, flags, result);
 	return 0;
 }
@@ -79,16 +119,14 @@ async function connectorsPull(ctx) {
 	const { client, flags, io } = ctx;
 	// Dual key: --collection (a CMS-bound collection), or --provider (resolve/wire),
 	// or both (--provider wires an unbound --collection first). At least one required.
-	const collectionId = flagStr(flags.collection);
-	const provider = flagStr(flags.provider);
-	if (!collectionId && !provider) {
+	const args = argsFromFlags(ARGS.import_from_cms, flags);
+	if (!args.collection_id && !args.provider) {
 		throw new CliError("Pass --collection <id> and/or --provider <webflow|framer|sanity|contentful>");
 	}
-	const args = compact({ collection_id: collectionId, provider });
 	const result = await client.callTool("import_from_cms", args);
 	ok(
 		ctx,
-		`Pulled from ${result?.provider ?? provider ?? "CMS"} into collection ${result?.collection_id ?? collectionId ?? ""}.`
+		`Pulled from ${result?.provider ?? args.provider ?? "CMS"} into collection ${result?.collection_id ?? args.collection_id ?? ""}.`
 	);
 	printResult(io, flags, result);
 	return 0;
@@ -96,33 +134,18 @@ async function connectorsPull(ctx) {
 
 async function connectorsConnect(ctx) {
 	const { client, flags, io } = ctx;
-	const provider = requireFlag(flags, "provider");
-	// api_token is required for every provider; the rest are provider-specific.
-	const args = compact({
-		provider,
-		api_token: requireFlag(flags, "token"),
-		project_url: flagStr(flags["project-url"]),
-		auto_deploy: flags["no-auto-deploy"] ? false : flagBool(flags["auto-deploy"]) || undefined,
-		project_id: flagStr(flags["project-id"]),
-		dataset: flagStr(flags.dataset),
-		project_name: flagStr(flags["project-name"]),
-		workspace_name: flagStr(flags.workspace),
-		space_id: flagStr(flags["space-id"]),
-		environment_id: flagStr(flags.environment),
-		space_name: flagStr(flags["space-name"]),
-		default_locale: flagStr(flags.locale),
-	});
+	const args = argsFromFlags(ARGS.connect_cms, flags);
 	const result = await client.callTool("connect_cms", args);
-	ok(ctx, `Connected ${provider}${result?.label ? ` (${result.label})` : ""}.`);
+	ok(ctx, `Connected ${args.provider}${result?.label ? ` (${result.label})` : ""}.`);
 	printResult(io, flags, result);
 	return 0;
 }
 
 async function connectorsDisconnect(ctx) {
 	const { client, flags, io } = ctx;
-	const provider = requireFlag(flags, "provider");
-	const result = await client.callTool("disconnect_cms", { provider });
-	ok(ctx, `Disconnected ${provider}.`);
+	const args = argsFromFlags(ARGS.disconnect_cms, flags);
+	const result = await client.callTool("disconnect_cms", args);
+	ok(ctx, `Disconnected ${args.provider}.`);
 	printResult(io, flags, result);
 	return 0;
 }
@@ -136,19 +159,14 @@ async function connectorsConnections(ctx) {
 
 async function connectorsMappings(ctx) {
 	const { client, flags, io } = ctx;
-	const provider = requireFlag(flags, "provider");
-	const result = await client.callTool("list_cms_mappings", { provider });
+	const result = await client.callTool("list_cms_mappings", argsFromFlags(ARGS.list_cms_mappings, flags));
 	printResult(io, flags, result);
 	return 0;
 }
 
 async function connectorsBind(ctx) {
 	const { client, flags, io } = ctx;
-	const args = compact({
-		collection_id: requireFlag(flags, "collection"),
-		provider: requireFlag(flags, "provider"),
-		mapping_id: flagStr(flags.mapping),
-	});
+	const args = argsFromFlags(ARGS.bind_collection_cms, flags);
 	const result = await client.callTool("bind_collection_cms", args);
 	ok(
 		ctx,

package/lib/commands/onboard.mjs

@@ -46,18 +46,109 @@
 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 = {
+	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" },
+		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 = [
@@ -191,11 +282,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 +306,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 +324,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 +350,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 +372,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 +451,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 +477,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 +565,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);

package/lib/commands/shared.mjs

@@ -53,6 +53,138 @@ export function compact(obj) {
 	return out;
 }
 
+// Flags every command accepts: transport, output shape, and the ones the runner
+// consumes before a command ever sees them.
+export const GLOBAL_FLAGS = new Set([
+	"url",
+	"key",
+	"staff-key",
+	"json",
+	"quiet",
+	"verbose",
+	"help",
+	"version",
+	"yes",
+	"no-color",
+	"profile",
+]);
+
+/**
+ * Refuse a flag this command does not understand.
+ *
+ * On a WRITE command an unrecognised flag is not cosmetic. `phantom-onboard
+ * collection --status` used to fall straight through to `onboard_collection`
+ * and START A SECOND ONBOARDING — a read verb that spent money and left a
+ * duplicate collection behind — because nothing checked that `--status` meant
+ * anything here. Its sibling `phantom-onboard domain --status` reads, so the
+ * same flag meant "read" on one subcommand and "spend" on the other.
+ *
+ * `own` is the flags the command handles itself; the ARGS map supplies the
+ * rest, so the map that BUILDS the call is also the list of what may be passed
+ * to it — one source, the same principle the maps exist for.
+ */
+export function refuseUnknownFlags(ctx, argsMap, own = []) {
+	const allowed = new Set([...GLOBAL_FLAGS, ...own]);
+	for (const source of Object.values(argsMap ?? {})) {
+		if (typeof source === "string") allowed.add(source);
+		else if (Array.isArray(source)) source.forEach((f) => allowed.add(f));
+		else if (source && typeof source === "object" && source.flag) allowed.add(source.flag);
+	}
+	const unknown = Object.keys(ctx.flags).filter((f) => !allowed.has(f));
+	if (unknown.length) {
+		throw new CliError(
+			`Unknown flag${unknown.length > 1 ? "s" : ""} for this command: ${unknown.map((f) => `--${f}`).join(", ")}. ` +
+				"This command writes, so it refuses rather than ignoring a flag it does not understand."
+		);
+	}
+}
+
+// ---------------------------------------------------------------------------------
+// ARGS maps: the one place a curated command says how each tool input key is sourced.
+//
+// A command module exports `ARGS = { <tool name>: { <schema key>: <source> } }` and builds
+// its `callTool` payload with `argsFromFlags(ARGS[tool], flags, positionals)`. The map IS
+// the implementation — not a second copy of it — so `scripts/parity-check.ts` can import it
+// and compare its keys against the tool's published input schema. A tool that gains a
+// parameter the command never learned then FAILS parity instead of drifting silently
+// (#1731 shipped enable_planner to MCP and REST and the CLI never got the flags; nothing
+// noticed, because the old check compared tool NAMES only).
+//
+// Source forms, one per schema key:
+//   "flag"                              a string flag, --flag <value>
+//   ["about", "direction"]              the first of these string flags that is set
+//   { flag, type?, required?, enum?, invert?, negate?, positional?, label? }
+//       type:      "str" (default) | "num" | "bool" | "list" (a repeatable flag)
+//       required:  throw "Missing required --flag" when absent
+//       enum:      throw "--flag must be one of: …" on any other value
+//       invert:    (bool) a set --flag sends FALSE (e.g. --no-phantom → enabled:false)
+//       negate:    (bool) a second flag that sends FALSE (e.g. --no-auto-deploy)
+//       positional: an index into positionals instead of a flag (label names it in errors)
+//   { object: { <sub key>: <source> } } a nested object, omitted when every sub key is absent
+//   { value: (flags, positionals, extra) => v }
+//                                       computed from several flags or an earlier result;
+//                                       still DECLARED, so parity counts the key as exposed
+//   { internal: "why" }                 supplied by the command from a prior tool result
+//                                       (a job id it just received), never from the user
+export function argsFromFlags(spec, flags, positionals = [], extra = {}) {
+	const out = {};
+	for (const [key, source] of Object.entries(spec)) {
+		const v = readArgSource(key, source, flags, positionals, extra);
+		if (v !== undefined) out[key] = v;
+	}
+	return out;
+}
+
+function readArgSource(key, source, flags, positionals, extra) {
+	if (typeof source === "string") return flagStr(flags[source]);
+	if (Array.isArray(source)) {
+		for (const name of source) {
+			const v = flagStr(flags[name]);
+			if (v !== undefined) return v;
+		}
+		return undefined;
+	}
+	if (!source || typeof source !== "object") {
+		throw new CliError(`ARGS.${key}: unsupported source ${JSON.stringify(source)}`);
+	}
+	if (source.internal !== undefined) return undefined;
+	if (typeof source.value === "function") return source.value(flags, positionals, extra);
+	if (source.object) {
+		const nested = argsFromFlags(source.object, flags, positionals, extra);
+		return Object.keys(nested).length ? nested : undefined;
+	}
+	if (source.positional !== undefined) {
+		const v = positionals[source.positional];
+		if (v === undefined && source.required) {
+			throw new CliError(`Missing required <${source.label ?? key}>`);
+		}
+		return v;
+	}
+	const raw = flags[source.flag];
+	let v;
+	switch (source.type ?? "str") {
+		case "num":
+			v = flagNum(raw);
+			break;
+		case "bool":
+			if (source.negate && flags[source.negate] === true) return false;
+			v = raw === true ? (source.invert ? false : true) : undefined;
+			break;
+		case "list": {
+			const list = flagList(raw);
+			v = list.length ? list : undefined;
+			break;
+		}
+		default:
+			v = flagStr(raw);
+	}
+	if (v === undefined && source.required) throw new CliError(`Missing required --${source.flag}`);
+	if (v !== undefined && source.enum && !source.enum.includes(v)) {
+		throw new CliError(`--${source.flag} must be one of: ${source.enum.join(", ")}`);
+	}
+	return v;
+}
+
 export function printResult(io, flags, value, formatter) {
 	if (flags.json || !formatter) {
 		io.log(JSON.stringify(value, null, 2));

package/lib/commands/strategy.mjs

@@ -4,16 +4,72 @@
 // mirrored here as two exported handlers for the same reason.
 
 import { CliError } from "../client.mjs";
-import {
-	flagStr,
-	requireFlag,
-	requirePositional,
-	printResult,
-	compact,
-	flagList,
-	ok,
-	readBodyInput,
-} from "./shared.mjs";
+import { flagStr, printResult, flagList, ok, readBodyInput, argsFromFlags } from "./shared.mjs";
+
+// A list flag the API clears with an explicit empty array (which compact() keeps):
+// `--clear-topics` sends [], a repeated --topic sends the list, neither sends nothing.
+const clearableList = (flag, clearFlag) => ({
+	value: (flags) => {
+		if (flags[clearFlag]) return [];
+		const list = flagList(flags[flag]);
+		return list.length ? list : undefined;
+	},
+});
+
+// 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 = {
+	get_company_info: {},
+	set_company_info: {
+		name: "name",
+		domain: "domain",
+		// The API clears the manifesto with an empty string, which a plain flag read would
+		// drop — so it is set explicitly whenever the user supplied a source (text or file).
+		manifesto: {
+			value: (flags) => {
+				const inline = flagStr(flags.manifesto);
+				const file = flagStr(flags["manifesto-file"]);
+				if (inline === undefined && file === undefined) return undefined;
+				return inline ?? readBodyInput({ file }) ?? "";
+			},
+		},
+		market: "market",
+	},
+	get_positioning: {},
+	set_positioning: {
+		priority_topics: clearableList("topic", "clear-topics"),
+		stances: clearableList("stance", "clear-stances"),
+		avoid_topics: clearableList("avoid", "clear-avoid"),
+	},
+	list_competitors: {},
+	add_competitor: {
+		name: { positional: 0, label: "name", required: true },
+		domain: { positional: 1, label: "domain", required: true },
+	},
+	import_sitemap: {
+		collection_id: { flag: "collection", required: true },
+		sitemap_url: { flag: "url", required: true },
+		sitemap_urls: { flag: "sub", type: "list" },
+		url_pattern: "pattern",
+		posts_only: { flag: "posts-only", type: "bool" },
+	},
+	list_topics: {
+		collection_id: { flag: "collection", required: true },
+	},
+	set_topic: {
+		collection_id: { flag: "collection", required: true },
+		topic_id: "topic",
+		suggestion_id: "suggestion",
+	},
+	get_onboarding_status: {},
+	// Step ids are the server's to define (the registry is the authority); forwarded as given.
+	set_onboarding_step: {
+		current_step: "current",
+		complete_step: "complete",
+		skip_step: "skip",
+		status: "status",
+	},
+};
 
 export async function cmdStrategy(ctx) {
 	const sub = ctx.positionals[0];
@@ -60,16 +116,11 @@ async function companyGet(ctx) {
 
 async function companySet(ctx) {
 	const { client, flags, io } = ctx;
-	const args = compact({ name: flagStr(flags.name), domain: flagStr(flags.domain) });
-	// The API clears the manifesto with an empty string, which compact() would drop —
-	// so set it explicitly whenever the user supplied a source (text or file).
-	const manifesto = flagStr(flags.manifesto);
-	const manifestoFile = flagStr(flags["manifesto-file"]);
-	if (manifesto !== undefined || manifestoFile !== undefined) {
-		args.manifesto = manifesto ?? readBodyInput({ file: manifestoFile }) ?? "";
-	}
+	const args = argsFromFlags(ARGS.set_company_info, flags);
 	if (Object.keys(args).length === 0) {
-		throw new CliError('Nothing to set — pass --name/--domain/--manifesto (empty --manifesto "" clears it).');
+		throw new CliError(
+			'Nothing to set — pass --name/--domain/--manifesto/--market (empty --manifesto "" clears it).'
+		);
 	}
 	const result = await client.callTool("set_company_info", args);
 	ok(ctx, "Company profile updated.");
@@ -101,15 +152,7 @@ async function positioningGet(ctx) {
 
 async function positioningSet(ctx) {
 	const { client, flags, io } = ctx;
-	const topics = flagList(flags.topic);
-	const stances = flagList(flags.stance);
-	const avoid = flagList(flags.avoid);
-	// The API clears a list with an explicit empty array (which compact() keeps).
-	const args = compact({
-		priority_topics: flags["clear-topics"] ? [] : topics.length ? topics : undefined,
-		stances: flags["clear-stances"] ? [] : stances.length ? stances : undefined,
-		avoid_topics: flags["clear-avoid"] ? [] : avoid.length ? avoid : undefined,
-	});
+	const args = argsFromFlags(ARGS.set_positioning, flags);
 	if (Object.keys(args).length === 0) {
 		throw new CliError("Pass at least one --topic/--stance/--avoid (or a --clear-* flag).");
 	}
@@ -144,10 +187,9 @@ async function competitorsList(ctx) {
 
 async function competitorsAdd(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const name = requirePositional(positionals, 0, "name");
-	const domain = requirePositional(positionals, 1, "domain");
-	const result = await client.callTool("add_competitor", { name, domain });
-	ok(ctx, `Added competitor ${name}.`);
+	const args = argsFromFlags(ARGS.add_competitor, flags, positionals);
+	const result = await client.callTool("add_competitor", args);
+	ok(ctx, `Added competitor ${args.name}.`);
 	printResult(io, flags, result);
 	return 0;
 }
@@ -156,15 +198,7 @@ async function competitorsAdd(ctx) {
 
 async function strategySitemap(ctx) {
 	const { client, flags, io } = ctx;
-	const collection = requireFlag(flags, "collection");
-	const url = requireFlag(flags, "url");
-	const sub = flagList(flags.sub);
-	const args = compact({
-		collection_id: collection,
-		sitemap_url: url,
-		sitemap_urls: sub.length ? sub : undefined,
-		url_pattern: flagStr(flags.pattern),
-	});
+	const args = argsFromFlags(ARGS.import_sitemap, flags);
 	const result = await client.callTool("import_sitemap", args);
 	ok(ctx, "Sitemap import started.");
 	printResult(io, flags, result);
@@ -189,21 +223,17 @@ async function strategyTopics(ctx) {
 
 async function topicsList(ctx) {
 	const { client, flags, io } = ctx;
-	const collection = requireFlag(flags, "collection");
-	const result = await client.callTool("list_topics", { collection_id: collection });
+	const result = await client.callTool("list_topics", argsFromFlags(ARGS.list_topics, flags));
 	printResult(io, flags, result);
 	return 0;
 }
 
 async function topicsSet(ctx) {
 	const { client, flags, io } = ctx;
-	const collection = requireFlag(flags, "collection");
-	const topicId = flagStr(flags.topic);
-	const suggestionId = flagStr(flags.suggestion);
-	if ((topicId === undefined) === (suggestionId === undefined)) {
+	const args = argsFromFlags(ARGS.set_topic, flags);
+	if ((args.topic_id === undefined) === (args.suggestion_id === undefined)) {
 		throw new CliError("Pass exactly one of --topic <topic-id> or --suggestion <suggestion-id>.");
 	}
-	const args = compact({ collection_id: collection, topic_id: topicId, suggestion_id: suggestionId });
 	const result = await client.callTool("set_topic", args);
 	ok(ctx, "Topic queued.");
 	printResult(io, flags, result);
@@ -234,12 +264,7 @@ async function onboardingStatus(ctx) {
 
 async function onboardingStep(ctx) {
 	const { client, flags, io } = ctx;
-	const args = compact({
-		current_step: flagStr(flags.current),
-		complete_step: flagStr(flags.complete),
-		skip_step: flagStr(flags.skip),
-		status: flagStr(flags.status),
-	});
+	const args = argsFromFlags(ARGS.set_onboarding_step, flags);
 	if (Object.keys(args).length === 0) {
 		throw new CliError("Pass --current/--complete/--skip/--status.");
 	}

package/package.json

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