@letterstory/cli 0.28.0 → 0.29.0

package/README.md

@@ -79,9 +79,9 @@ refresh automatically. Run `letterstory logout` to revoke the session and forget
 
 **Or use a static API key** (for CI/automation, or when you want scoped-down access):
 
-You need a Letterstory API key (starts with `ls_`; legacy `lb_` keys still work) with the `deployment:read` and
-`deployment:write` capabilities — mint one in the app under **Settings → API keys**.
-Add `deployment:domain` too if you plan to buy custom domains.
+You need a Letterstory API key (starts with `ls_`; legacy `lb_` keys still work) with the `phantom:read` and
+`phantom:write` capabilities — mint one in the app under **Settings → API keys**.
+Add `phantom:domain` too if you plan to buy custom domains.
 
 ```bash
 letterstory login --key ls_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -95,59 +95,48 @@ Run `letterstory whoami` (alias `status`) any time to confirm which key/url (or
 resolved and see your company profile. Run `letterstory config` to see the resolved url and
 credential source without making a network call.
 
-## Spin up a blog
+## Phantomstory — a collection Letterstory hosts as an independent publication
+
+A phantom is a site we host that renders one of your collections; it never carries your
+company's name. Phantoms are metered in SITES live at once (`phantom balance`), not posts.
 
 ```bash
-# create a blog and wait until it's live (polls for you)
-letterstory deploy create --name "My Blog" --theme gazette
-
-#   Created deployment 7c19c7… (provisioning)
-#     … provisioning · building
-#     … provisioning · connecting
-#   ✓ Live at https://my-blog-7c19c7.letterstory-staging.com
-
-letterstory deploy list
-letterstory deploy get <deployment-id>
-letterstory deploy update <deployment-id> --name "New Name"
-letterstory deploy rebuild <deployment-id>      # after publishing new articles
-letterstory deploy diagnostics <deployment-id>  # why is my blog empty?
-letterstory deploy delete <deployment-id> --yes
+# provision a site and follow it until it's live (then it configures itself in the background:
+# strategy, visuals, writing kernel, cadence, topic map)
+letterstory phantom new --name "Saved Query" --config '{"cadence":{"posts_per_week":6}}'
+
+#   Phantom 7c19c7… provisioning — following…
+#     … provisioning · deploy
+#     … provisioning · connect
+#   Live at https://saved-query-7c19c7.letterstory-staging.com. Configuration continues in the background
+
+letterstory phantom list
+letterstory phantom get <phantom-id>
+letterstory phantom config <phantom-id>                        # the site's file joined to its collection's
+letterstory phantom config <phantom-id> --theme commons          # patch the site (identity/theme rebuild it)
+letterstory phantom config <phantom-id> --collection-config '{"cadence":{"posts_per_week":4}}'
+letterstory phantom config <phantom-id> --configure --dry-run   # what re-configuring would decide, applying nothing
+letterstory phantom rebuild <phantom-id>                        # after publishing outside a collection run
+letterstory phantom diagnostics <phantom-id>                    # why is my site empty?
+letterstory phantom balance                                     # sites live / granted, and the cadence cap
+letterstory phantom delete <phantom-id> --yes
 ```
 
-Pass `--no-wait` to return immediately and poll later with `deploy get`, or `--dry-run`
-on `create` to print what would be sent without creating anything.
-
-### One-shot: bare `deploy`
+Pass `--no-wait` to return immediately and poll later with `phantom get`, `--no-configure`
+for a bare site, or `--dry-run` to see the plan without provisioning anything.
 
-For the common case — reserve a blog, price (and optionally buy) a domain, and rebuild,
-all in one call — skip the subcommand word entirely:
-
-```bash
-letterstory deploy --domain yourverticalreview.com --buy
-#   Reserved phantom blog "Yourverticalreview" (7c19c7…)
-#   Priced yourverticalreview.com
-#   Registered yourverticalreview.com
-#   SSL + DNS provisioned · sitemap + schema generated
-#
-#   Your phantom blog is live at https://yourverticalreview.com.
-
-letterstory deploy --blog 7c19c7… --rebuild   # rebuild an existing blog instead of creating one
-letterstory deploy --domain demo.com --dry-run  # preview without calling the API
-```
+Publishing to the site is a **collection run** on its collection (below). Letterstory's own
+launch recipe from a client domain — positioning inferred, a masthead proposed, the first
+posts seeded — is `phantom-onboard` (see "Propose, then onboard a phantom").
 
 ## Custom domains
 
 ```bash
-letterstory domain check myblog.com                       # price it (no charge)
-letterstory domain buy <deployment-id> myblog.com        # buys + attaches the domain
+letterstory phantom domain check myblog.com                     # price it (no charge)
+letterstory phantom domain buy <phantom-id> myblog.com --yes    # buys + attaches (spends money; phantom:domain)
+letterstory phantom domain connect <phantom-id> myblog.com      # attach one you already own
 ```
 
-`blogs` and `domains` are aliases for `deploy` and `domain` — the exact same commands
-under Phantomstory's vocabulary (`blogs ls`, `blogs new`, `blogs rm`, `blogs update`,
-`domains buy`, etc. all call the identical handler as their `deploy`/`domain`
-counterpart). Use whichever set of verbs you prefer; both are always available from
-both `letterstory` and `phantom`.
-
 ## Content
 
 ```bash
@@ -161,16 +150,41 @@ letterstory published list [--limit <n>] [--collection <uuid>] [--format html|md
 letterstory published show --slug my-post-slug [--format html|md]    # or --id <uuid>
 ```
 
-## Collections
+## Collections — the content engine, one door
+
+A collection is a publication with a ONE-FILE configuration (identity, content, cadence,
+publishing, targets, measurement) that produces and publishes posts on a cadence.
+`collection run` produces ONE post: source → write → gate → publish → (hosted) rebuild.
 
 ```bash
-letterstory collections list
-letterstory collections new --name "Launches" --description "…"
+letterstory collection list                                     # public_id = the HTTP door's address
+letterstory collection new --name "Launches" --config-file cfg.json
+letterstory collection config <id>                              # print the one file
+letterstory collection config <id> --config '{"targets":{"enabled":true,"tier":"ramping"}}'   # patch it
+
+# one post, followed to the end (20–60 min); stops at the gate under manual approval
+letterstory collection run --collection <id> --spoke <topic-id>
+letterstory collection run --collection <id> --topic "…" --approval manual --no-wait
+letterstory collection run --collection <id> --at 2026-10-01T09:00:00Z   # a future slot
+letterstory collection run-status <run-id>                      # status, steps, constraints, verification
+letterstory collection runs --collection <id> --status ready
+letterstory collection approve <run-id> --now
+letterstory collection cancel <run-id>
+letterstory collection delete <id> --yes
+
+# the legacy verbs still work under `collections`
 letterstory collections update <id> --cadence-target 4 --cadence-period week
-letterstory collections delete <id> --yes
 letterstory collections assign <article-id> <collection-id>
+letterstory collections activate <id> --cadence 6 --approval autopilot
+letterstory collections autopen <id> --kernel-family gazette
 ```
 
+A direct run spends one of the collection's weekly cadence slots (its `posts_per_week`,
+capped by the org's cadence cap) and is refused — never queued silently — once the week is
+spent; the planner's own slots are the budget being spent as designed. The same door over
+HTTP: `POST /api/collection/ingest/{public_id}` (202 + `poll_url`), `GET …/runs/{run_id}`,
+`POST …/runs/{run_id}/approve`.
+
 ## Landing pages
 
 A landing page is a link plus context describing what lives there. Collections with
@@ -280,6 +294,7 @@ jq '.topicPlans[1]' proposal.json | letterstory phantom-onboard mastheads acme.c
 # Then onboard with the plan (direction + pillars), the masthead and, if any, the domain.
 letterstory phantom-onboard acme.com --plan-file proposal.json --plan-id plan-2 \
   --name "The Compliance Wire" --domain compliancewire.com --domain-mode buy_now --real
+# (drives plan_phantom; the seeded posts are collection runs — poll them with `collection run-status`)
 ```
 
 `propose` reads the client's homepage and returns distinct editorial angles (`topicPlans`), the
@@ -385,8 +400,8 @@ letterstory shredder job <job-id>                                 # poll it your
 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.
+`collection run --topic "…" --collection <uuid>` runs topic → draft → publish → rebuild
+end to end, with `collection run-status <job-id>` to follow it.
 
 ## Seers — event-driven signals
 

package/lib/cli.mjs

@@ -3,6 +3,7 @@
 // never throws for user-facing problems (those become a printed CliError + code 1).
 
 import { LetterstoryClient, CliError, resolveConfig, readConfigFile, writeConfigFile } from "./client.mjs";
+import { resolveDocumentFlags } from "./documents.mjs";
 import { checkForUpdate } from "./update-check.mjs";
 import {
 	cmdLogin,
@@ -13,10 +14,8 @@ import {
 	cmdCall,
 	cmdTool,
 	cmdMcp,
-	cmdDeploy,
-	cmdDomain,
-	cmdBlogs,
-	cmdDomains,
+	cmdCollection,
+	cmdPhantom,
 	cmdPosts,
 	cmdPublished,
 	cmdReviewers,
@@ -34,7 +33,6 @@ import {
 	cmdAutoPen,
 	cmdCovers,
 	cmdKernel,
-	cmdPhantomJob,
 	cmdOnboard,
 	cmdSeers,
 	cmdTemplates,
@@ -45,7 +43,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.28.0";
+export const VERSION = "0.29.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.
@@ -167,25 +165,42 @@ Auth:
   logout                             Forget saved credentials (revokes an OAuth session, if any)
   config                             Show the resolved url + credential source
 
-Phantom blogs:
-  deploy [--domain <d>] [--name <n>] [--theme <t>] [--collection <uuid>]
-         [--blog <id>] [--buy] [--rebuild] [--dry-run]
-                                                      One-shot: reserve/locate a blog, price
-                                                      the domain, optionally buy it, rebuild
-  deploy create --name <name> [--description <text>] [--theme <theme>]
-                [--collection <uuid>] [--no-wait]   Create a blog; waits until it's live
-  deploy list [--limit <n>]                          List your blogs
-  deploy get <deployment-id>                         Show one blog's status + URL
-  deploy rebuild <deployment-id>                     Rebuild to pull in newly-published content
-  deploy diagnostics <deployment-id>                 Why is my blog empty? snapshot
-  deploy delete <deployment-id> --yes                Tear down the blog (keeps the collection)
-
-Custom domains:
-  domain check <domain>                              Price a domain (read-only, no charge)
-  domain buy <deployment-id> <domain>                Buy + attach a custom domain
-
-  "blogs" and "domains" are aliases for "deploy" and "domain" (same commands, ls/new/
-  show/update/rm verbs also accepted) — use whichever vocabulary you prefer.
+Collections (the content engine as a primitive — one door, 'collection run'):
+  collection list                                      Your collections (public_id = the HTTP door's address)
+  collection new --name <n> [--description <t>] [--config '<json>'|--config-file cfg.json]
+  collection config <id> [--config '<json>'|--config-file cfg.json]
+                                                       Print the ONE FILE (identity, content, cadence,
+                                                       publishing, targets, measurement) — or PATCH it
+  collection run --collection <id> [--topic <t> | --spoke <topic-id> | --headline <suggestion-id>]
+                 [--source <url> …] [--must-include <t> …] [--depth barebones|fleshed_out]
+                 [--kernel <id>] [--no-verify] [--shred] [--mention off|subtle|woven]
+                 [--approval autopilot|review_window|manual] [--no-publish] [--no-rebuild]
+                 [--at <iso-datetime>] [--no-wait]
+                                                       Produce ONE post: source → write → gate →
+                                                       publish → (hosted) rebuild. Spends one of the
+                                                       week's cadence slots. 20–60 min; followed unless
+                                                       --no-wait; stops at the gate under manual approval.
+  collection run-status <run-id>                       Status, steps, constraints, verification
+  collection runs [--collection <id>] [--status <s>] [--limit <n>]
+  collection approve <run-id> [--now]                  Answer the gate (--now publishes immediately)
+  collection cancel <run-id>
+  collection delete <id> --yes
+
+Phantomstory (a collection Letterstory hosts as an independent publication):
+  phantom list                                         Your phantoms (metered in SITES live at once)
+  phantom new --name <n> [--description <t>] [--theme <t>] [--collection <id>] [--customer-ref <r>]
+              [--no-configure] [--config '<json>'] [--client-domain <d>] [--dry-run] [--no-wait]
+                                                       Provision a site + configure it (strategy,
+                                                       visuals, kernel, cadence, topic map). Then
+                                                       'collection run --collection <its collection_id>'.
+  phantom get <phantom-id>                             Status, URL, domain, DNS
+  phantom config <phantom-id> [--name … --theme … --collection …] [--collection-config '<json>']
+                              [--configure [--dry-run]]
+                                                       The site's file joined to its collection's
+  phantom rebuild <phantom-id> · phantom diagnostics <phantom-id> · phantom balance
+  phantom domain check <domain> · phantom domain buy <phantom-id> <domain> --yes
+  phantom domain connect <phantom-id> <domain>
+  phantom delete <phantom-id> --yes
 
 Content:
   posts list [--limit <n>] [--collection <uuid>]     List your articles
@@ -347,12 +362,7 @@ Writing kernels (kernels write the draft; they do not research — run research
   kernel runs [--endpoint <id>] [--limit <n>]          Recent endpoint writes (telemetry)
   kernel balance                                       Kernel runs left on this org
 
-Phantom orchestrator:
-  phantom-job create --topic <text> --collection <uuid> [--kernel <uuid>]
-                                                        Topic -> draft -> publish -> rebuild
-  phantom-job status <job-id>                          Check a job's stage
-
-Phantom onboarding recipe (domain -> live phantom blog with first posts):
+Phantom launch recipe (a CLIENT domain -> a live phantom with its first posts; drives plan_phantom):
   ${bin === "phantom" ? "onboard" : "phantom-onboard"} <domain> [--about "the beat"] [--name X]
           [--posts N] [--cadence N] [--cover editorial_image|full_ai|line_art] [--theme T]
           [--real] [--domain host] [--domain-mode subdomain|buy_now|connect_later]
@@ -607,11 +617,9 @@ const CLIENT_COMMANDS = {
 	// argument coercion (--arg/--json-args/--stdin) added on top.
 	tool: cmdTool,
 	mcp: cmdMcp,
-	deploy: cmdDeploy,
-	domain: cmdDomain,
-	// Mathew's phantomstory-cli names for the exact same deploy/domain commands.
-	blogs: cmdBlogs,
-	domains: cmdDomains,
+	// The Collections primitive (one door: `collection run`) and its hosted profile.
+	collection: cmdCollection,
+	phantom: cmdPhantom,
 	posts: cmdPosts,
 	published: cmdPublished,
 	reviewers: cmdReviewers,
@@ -629,7 +637,6 @@ const CLIENT_COMMANDS = {
 	autopen: cmdAutoPen,
 	covers: cmdCovers,
 	kernel: cmdKernel,
-	"phantom-job": cmdPhantomJob,
 	"phantom-onboard": cmdOnboard,
 	seers: cmdSeers,
 	templates: cmdTemplates,
@@ -708,6 +715,15 @@ export async function run(argv, io = defaultIo()) {
 			verboseLog: io.error,
 			bin,
 		});
+		// DOCUMENT `--*-file` FLAGS BECOME TEXT BEFORE THE COMMAND RUNS.
+		//
+		// One interception point rather than per-command handling: `readTextInput` prefers a
+		// flag's inline twin over its path, so resolving a document is setting that twin — no
+		// change to `argsFromFlags` (which is synchronous, and has 75 call sites) and no command
+		// that can forget. `--file notes.md` still reads locally; `--file report.docx` and
+		// `--file paper.pdf` go through the app's extractor, which is the only one there is.
+		await resolveDocumentFlags(client, flags);
+
 		const ctx = { client, config, positionals: positionals.slice(1), flags, io, bin };
 		return await handler(ctx);
 	} catch (err) {

package/lib/client.mjs

@@ -155,6 +155,59 @@ export class LetterstoryClient {
 		return body.result;
 	}
 
+	/**
+	 * One multipart POST to a REST route on the same host, for the routes that take BYTES.
+	 *
+	 * The MCP envelope is JSON, so a document would have to be base64'd into it — a 10MB PDF
+	 * becomes ~13MB of base64 in a single JSON string. `POST /api/documents/extract` takes the
+	 * file directly, so this exists for it (and any future byte-taking route). Same auth and
+	 * the same one-shot refresh-and-retry as `rpc`, because an expired session should fail the
+	 * same way whichever door the command happened to use.
+	 *
+	 * Deliberately no `content-type` header: `fetch` sets it from the FormData, including the
+	 * multipart boundary, and overriding it produces a body the server cannot parse.
+	 *
+	 * @param {string} path Route path, e.g. `/api/documents/extract`
+	 * @param {FormData} form
+	 * @returns {Promise<any>} the parsed JSON body
+	 */
+	async postForm(path, form, { _retried = false } = {}) {
+		const authHeaders = this.authHeaders();
+		if (!authHeaders) {
+			throw new CliError(
+				`Not logged in. Run \`${this.bin} login\` (opens your browser) or \`${this.bin} login --key <ls_…>\`.`
+			);
+		}
+		const url = `${this.url}${path}`;
+		if (this.verbose) this.verboseLog(`» POST ${url} (multipart)`);
+		let res;
+		try {
+			res = await this.fetch(url, {
+				method: "POST",
+				headers: { accept: "application/json", ...authHeaders },
+				body: form,
+			});
+		} catch (err) {
+			throw new CliError(`Could not reach ${url}: ${err.message}`);
+		}
+		if (this.verbose) this.verboseLog(`« ${res.status}`);
+		if (res.status === 401 || res.status === 403) {
+			if (!_retried && this.oauth?.refresh_token && (await this.tryRefresh())) {
+				return this.postForm(path, form, { _retried: true });
+			}
+			const hint = this.oauth
+				? `Your session has expired. Run \`${this.bin} login\` again.`
+				: "Check your API key and its capabilities.";
+			throw new CliError(`Authentication failed (HTTP ${res.status}). ${hint}`);
+		}
+		const body = await res.json().catch(() => null);
+		if (!res.ok) {
+			throw new CliError(body?.error ? String(body.error) : `Request failed (HTTP ${res.status}) at ${url}`);
+		}
+		if (!body) throw new CliError(`Unexpected non-JSON response (HTTP ${res.status}) from ${url}`);
+		return body;
+	}
+
 	// Best-effort silent refresh. Returns false (never throws) so rpc() can
 	// fall through to its normal "please log in again" error on any failure.
 	async tryRefresh() {

package/lib/commands/collection.mjs

@@ -0,0 +1,279 @@
+// `collection` — the content engine as a primitive, on both of its doors.
+//
+// A collection is a publication with a one-file configuration that produces and publishes
+// posts on a cadence; `collection run` produces ONE post on it (sourced, written, gated,
+// published, and — when Letterstory hosts the site — rebuilt). Runs are 20–60 minutes, so
+// `collection run` submits and then follows the run unless you tell it not to
+// (`--no-wait`); `collection run-status` picks it up later. A direct run spends the
+// collection's weekly cadence budget (its posts_per_week); the planner's own slots are the
+// budget being spent as designed.
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import { flagStr, printResult, ok, toolField, followJob, argsFromFlags } from "./shared.mjs";
+
+function readJsonFileFlag(flags, flag) {
+	const path = flagStr(flags[flag]);
+	if (path === undefined) return undefined;
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new CliError(
+			`Could not read --${flag} ${path}: ${error instanceof Error ? error.message : String(error)}`
+		);
+	}
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new CliError(`--${flag} ${path} is not valid JSON.`);
+	}
+}
+function readJsonObjectFlag(flags, name) {
+	const inline = flagStr(flags[name]);
+	if (inline !== undefined) {
+		let parsed;
+		try {
+			parsed = JSON.parse(inline);
+		} catch (err) {
+			throw new CliError(`--${name} is not valid JSON: ${err.message}`);
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+			throw new CliError(`--${name} must be a JSON object`);
+		return parsed;
+	}
+	return readJsonFileFlag(flags, `${name}-file`);
+}
+
+const TERMINAL = new Set(["published", "failed", "skipped", "cancelled"]);
+
+/**
+ * How every command in this file sources its tool inputs — see `argsFromFlags` in
+ * shared.mjs and `scripts/parity-check.ts`, which compares these keys against each tool's
+ * published input schema.
+ */
+export const ARGS = {
+	list_collections: {},
+	create_collection: {
+		name: { flag: "name", required: true },
+		description: "description",
+		config: { value: (flags) => readJsonObjectFlag(flags, "config") },
+	},
+	get_collection_config: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	set_collection_config: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+		config: { value: (flags) => readJsonObjectFlag(flags, "config") },
+	},
+	delete_collection: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	run_collection: {
+		collection_id: { flag: "collection", required: true },
+		topic: "topic",
+		topic_id: { flag: "spoke" },
+		suggestion_id: { flag: "headline" },
+		source_urls: { flag: "source", type: "list" },
+		must_include: { flag: "must-include", type: "list" },
+		research_depth: { flag: "depth", enum: ["barebones", "fleshed_out"] },
+		kernel_id: { flag: "kernel" },
+		verify: { value: (flags) => (flags["no-verify"] === true ? false : undefined) },
+		shred: { flag: "shred", type: "bool" },
+		mention_degree: { flag: "mention", enum: ["off", "subtle", "woven"] },
+		approval_mode: { flag: "approval", enum: ["autopilot", "review_window", "manual"] },
+		publish: { value: (flags) => (flags["no-publish"] === true ? false : undefined) },
+		rebuild: { value: (flags) => (flags["no-rebuild"] === true ? false : undefined) },
+		schedule_for: { flag: "at" },
+	},
+	get_collection_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+	},
+	list_collection_runs: {
+		collection_id: { flag: "collection" },
+		status: {
+			flag: "status",
+			enum: [
+				"scheduled",
+				"sourcing",
+				"writing",
+				"ready",
+				"publishing",
+				"published",
+				"failed",
+				"skipped",
+				"cancelled",
+			],
+		},
+		limit: { flag: "limit", type: "num" },
+	},
+	approve_collection_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+		publish_now: { flag: "now", type: "bool" },
+	},
+	cancel_collection_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+	},
+};
+
+export async function cmdCollection(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return collectionList(rest);
+		case "new":
+		case "create":
+			return collectionCreate(rest);
+		case "config":
+			return collectionConfig(rest);
+		case "delete":
+		case "rm":
+			return collectionDelete(rest);
+		case "run":
+			return collectionRun(rest);
+		case "run-status":
+		case "status":
+			return collectionRunStatus(rest);
+		case "runs":
+			return collectionRuns(rest);
+		case "approve":
+			return collectionApprove(rest);
+		case "cancel":
+			return collectionCancel(rest);
+		default:
+			throw new CliError(
+				`Unknown collection subcommand: ${sub ?? "(none)"}. Try: list, new, config, delete, run, run-status, runs, approve, cancel`
+			);
+	}
+}
+
+async function collectionList(ctx) {
+	const result = await ctx.client.callTool("list_collections", argsFromFlags(ARGS.list_collections, ctx.flags));
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+async function collectionCreate(ctx) {
+	const result = await ctx.client.callTool(
+		"create_collection",
+		argsFromFlags(ARGS.create_collection, ctx.flags, ctx.positionals)
+	);
+	ok(
+		ctx,
+		`Collection ${toolField(result, "collection.name") ?? ""} created (${toolField(result, "collection.collection_id") ?? "?"}).`
+	);
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+// `collection config <id>` prints the one file; `--config '<json>'` or `--config-file cfg.json` patches it.
+async function collectionConfig(ctx) {
+	const { client, flags, io, positionals } = ctx;
+	const patch = readJsonObjectFlag(flags, "config");
+	if (patch === undefined) {
+		const result = await client.callTool(
+			"get_collection_config",
+			argsFromFlags(ARGS.get_collection_config, flags, positionals)
+		);
+		printResult(io, flags, result);
+		return 0;
+	}
+	const result = await client.callTool(
+		"set_collection_config",
+		argsFromFlags(ARGS.set_collection_config, flags, positionals)
+	);
+	ok(ctx, `Applied: ${(toolField(result, "applied") ?? []).join(", ") || "nothing"}.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function collectionDelete(ctx) {
+	if (ctx.flags.yes !== true) {
+		ctx.io.error("Refusing to delete without --yes.");
+		return 1;
+	}
+	const result = await ctx.client.callTool(
+		"delete_collection",
+		argsFromFlags(ARGS.delete_collection, ctx.flags, ctx.positionals)
+	);
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+async function collectionRun(ctx) {
+	const { client, flags, io, bin } = ctx;
+	const args = argsFromFlags(ARGS.run_collection, flags, ctx.positionals);
+	const result = await client.callTool("run_collection", args);
+	const runId = toolField(result, "run_id");
+	if (flags["no-wait"] === true || !runId) {
+		ok(ctx, `Run started as ${runId ?? "?"}. Follow it with: ${bin} collection run-status ${runId ?? "<run-id>"}`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	io.log(`Run ${runId} started — following (20–60 min; Ctrl-C and use run-status to pick it up later)…`);
+	let lastLine = "";
+	const followed = await followJob(
+		io,
+		async () => {
+			const r = await client.callTool("get_collection_run", { run_id: runId });
+			const run = toolField(r, "run") ?? r;
+			const line = `${run.status}${run.phase ? ` · ${run.phase}` : ""}${run.phase_detail ? ` — ${run.phase_detail}` : ""}`;
+			if (line !== lastLine) {
+				io.log(`  … ${line}`);
+				lastLine = line;
+			}
+			if (run.status === "ready" && run.approval?.mode !== "autopilot" && !run.approval?.approved_at)
+				return { done: true, value: run };
+			return { done: TERMINAL.has(run.status), value: run };
+		},
+		{ intervalMs: 30000, ceilingMs: 90 * 60 * 1000 }
+	);
+	const run = followed.value;
+	if (run?.status === "ready") {
+		ok(ctx, `Written and waiting for approval. Approve with: ${bin} collection approve ${runId} [--now]`);
+	} else if (!followed.settled) {
+		io.log(`Still running. Pick it up with: ${bin} collection run-status ${runId}`);
+	}
+	printResult(io, flags, run ?? result);
+	return 0;
+}
+
+async function collectionRunStatus(ctx) {
+	const result = await ctx.client.callTool(
+		"get_collection_run",
+		argsFromFlags(ARGS.get_collection_run, ctx.flags, ctx.positionals)
+	);
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+async function collectionRuns(ctx) {
+	const result = await ctx.client.callTool(
+		"list_collection_runs",
+		argsFromFlags(ARGS.list_collection_runs, ctx.flags)
+	);
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+async function collectionApprove(ctx) {
+	const result = await ctx.client.callTool(
+		"approve_collection_run",
+		argsFromFlags(ARGS.approve_collection_run, ctx.flags, ctx.positionals)
+	);
+	ok(ctx, `Approved${ctx.flags.now === true ? " — publishing now" : ""}.`);
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
+async function collectionCancel(ctx) {
+	const result = await ctx.client.callTool(
+		"cancel_collection_run",
+		argsFromFlags(ARGS.cancel_collection_run, ctx.flags, ctx.positionals)
+	);
+	ok(ctx, toolField(result, "cancelled") ? "Cancelled." : "Nothing was in flight.");
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}