@letterstory/cli 0.19.0 → 0.23.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.19.0";
+export const VERSION = "0.23.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,9 +82,19 @@ 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",
+	// `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,9 +204,12 @@ 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 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]
@@ -245,11 +258,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
@@ -298,14 +311,16 @@ 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]
+export const VERSION = "0.23.0";
                                                         WRITE a new article from a headline,
                                                         outline, notes or a finished post.
-                                                        Follows the run unless --no-wait.
+                                                        Follows the run unless --no-wait, and
+                                                        prints the article when it lands.
   kernel polish <endpoint-id> (--body <html>|--file <path>) [--format auto|html]
                                                         POLISH the document you have: prose
                                                         reworded, your own markup kept
@@ -336,6 +351,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]
@@ -353,9 +375,19 @@ 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>] [--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 +395,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
@@ -449,6 +486,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;
@@ -462,8 +502,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

@@ -2,7 +2,82 @@
 // 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.
+	// `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.
+		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];
@@ -23,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", {});
@@ -39,35 +139,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 +162,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 +175,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 +193,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 +201,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,