@letterstory/cli 0.7.0 → 0.9.0

package/README.md

@@ -171,6 +171,22 @@ letterstory collections delete <id> --yes
 letterstory collections assign <article-id> <collection-id>
 ```
 
+## Landing pages
+
+A landing page is a link plus context describing what lives there. Collections with
+auto-mention enabled (toggle in Collection Settings) weave relevant landing pages into
+articles as they're written. Pass the URL as `--link` — `--url` is the global flag that
+overrides the API base URL.
+
+```bash
+letterstory landings list
+letterstory landings get <landing-id>
+letterstory landings create --link https://example.com/dataset --context "Our 2026 benchmark dataset. Cite it when an article discusses response-time or CSAT metrics."
+letterstory landings create --link https://example.com/report --file ./context.md   # context from a file (or --file - for stdin)
+letterstory landings update <landing-id> --context "Updated context"
+letterstory landings delete <landing-id> --yes
+```
+
 ## Flows
 
 Run an editorial pass over an article, check on it, and manage the completion webhook:
@@ -213,21 +229,6 @@ letterstory onboarding status
 letterstory onboarding step --complete connect_domain
 ```
 
-### Magical onboarding
-
-One command from a domain to a filled-out strategy: it infers and saves the manifesto,
-stances, and identity guardrail from the client's website (never clobbering anything
-hand-written), optionally imports the blog's post history from a sitemap, infers keywords
-and builds topic clusters, then detects the content series those posts already imply and
-adopts them — coverage reconstructed from existing posts, gaps left for the queue to write.
-Idempotent; safe to re-run.
-
-```bash
-letterstory onboarding magic                                # use the saved company domain
-letterstory onboarding magic --domain acme.com --sitemap https://acme.com/sitemap.xml
-letterstory onboarding magic --dry-run                      # preview series proposals only
-```
-
 ## Content series
 
 A series is a coverage obligation, not a keyword bet: "content that looks like this",
@@ -235,7 +236,6 @@ one post per declared item. Series feed the same planner queue as topic clusters
 
 ```bash
 letterstory series list
-letterstory series propose                                  # detect series in existing posts
 letterstory series create --name "Secrets, tool by tool" \
   --description "One practical secrets guide per IaC tool." \
   --coverage "Pulumi,Terraform,Ansible" --template <key>
@@ -330,7 +330,7 @@ Content templates (the compose structures seers bind via `config.template_key`):
 ```bash
 letterstory templates list                         # custom + read-only built-ins
 letterstory templates create --name "Release notes" --angle "What shipped and why" \
-  --sections-file sections.json
+  --blocks-file blocks.json
 letterstory templates update <template-id> --angle "…"   # unset fields keep their values
 letterstory templates delete <template-id> --yes   # bound seers fall back to defaults
 ```

package/lib/cli.mjs

@@ -28,23 +28,28 @@ import {
 	cmdSeries,
 	cmdInsights,
 	cmdResearch,
+	cmdAutoPen,
 	cmdCovers,
 	cmdKernel,
 	cmdPhantomJob,
+	cmdOnboard,
 	cmdSeers,
 	cmdTemplates,
 	cmdShredder,
+	cmdLandings,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.7.0";
+export const VERSION = "0.9.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.
 const BOOLEAN_FLAGS = new Set([
 	"json",
 	"yes",
+	"confirm-missing-target",
 	"no-wait",
+	"accept",
 	"help",
 	"version",
 	"quiet",
@@ -167,6 +172,13 @@ Collections:
   collections update <id> [--name] [--description] [--cadence-target <n>] [--cadence-period week|month] [--cover-canvas-type-id <uuid>|none]
   collections delete <id> --yes
   collections assign <article-id> <collection-id>
+  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]
+      The Auto-Pen settings the app's panel writes. --template binds a content
+      template (from 'templates list') as this collection's default, which is how
+      a template you author here actually gets used. A patch: unset flags are
+      left alone.
 
 Authors (the per-collection author bank — recurring bylines):
   authors list <collection-id>                        List the bank + byline distribution
@@ -188,6 +200,8 @@ Flows:
 Connectors:
   connectors list                                      List external publish destinations
   connectors publish <article-id> --to <connector> --target <uuid> [--flow-run <uuid>]
+                                                       [--confirm-missing-target] re-publish even though
+                                                       the item was deleted/unpublished on the provider
   connectors status --connector <connector> --publish-id <id>
 
 Strategy & onboarding:
@@ -200,12 +214,7 @@ Strategy & onboarding:
   strategy topics set --collection <uuid> (--topic <topic-id> | --suggestion <suggestion-id>)
   onboarding status                                    Show the onboarding checklist
   onboarding step [--current <step>] [--complete <step>] [--skip <step>] [--status <status>]
-  onboarding magic [--domain <domain>] [--sitemap <url>] [--collection <uuid>] [--dry-run]
-                                                        Enter a domain -> strategy filled out:
-                                                        manifesto+stances, optional history import,
-                                                        clusters, detected series (see below)
   series list                                          The org's content series + coverage state
-  series propose [--collection <uuid>]                 Detect series existing posts already imply
   series create --name <n> --description <d> [--coverage a,b,c] [--collection <uuid>] [--template <key>]
   series backfill <series-id> [--collection <uuid>]    Reconstruct a series from existing posts
 
@@ -218,6 +227,12 @@ Research agent (deep research -> outline written into the post):
                                                         Answer the --gate pause
   research cancel --article <uuid>                      Cancel a run in flight
 
+Auto-Pen (research -> kernel -> Enhance, in one run — and the ONLY path that
+applies a collection's content template; kernel run does not):
+  autopen start --article <uuid>                        Start the run; takes 10-40 min
+  autopen status --article <uuid>                       Step states + the template in use
+  autopen cancel --article <uuid> --yes                 Stop a run in flight
+
 Cover images (which image model draws the post's cover):
   covers models                                        Image models connected right now
   covers variants --article <uuid> [--model <id> …] [--ref-url <url> …]
@@ -238,6 +253,21 @@ Phantom orchestrator:
                                                         Topic -> draft -> publish -> rebuild
   phantom-job status <job-id>                          Check a job's stage
 
+Phantom onboarding recipe (domain -> live phantom blog with first posts):
+  ${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]
+          [--accept] [--dry-run]
+                                                       Plan (read-only) then, with --accept
+                                                       or an override flag, provision + configure
+                                                       + seed. --about becomes the planner's
+                                                       steering prompt, so it shapes the topic map
+                                                       and every post — use it for a client's
+                                                       second phantom. --name is committed at
+                                                       create (it seeds the URL); pass it before
+                                                       applying. --domain-mode buy_now SPENDS
+                                                       money (2/org, $30 cap).
+
 Seers (event-driven signals -> drafts):
   seers list                                           List seers with recent activity
   seers get <seer-id>                                  One seer's full config + poll state
@@ -264,8 +294,14 @@ Seers (event-driven signals -> drafts):
 Content templates (compose structures seers bind via config.template_key):
   templates list                                       Custom + built-in catalog
   templates show <template-id>
-  templates create --name <n> --angle <text> (--sections '<json>'|--sections-file <path>)
-  templates update <template-id> [--name] [--angle] [--sections '<json>'|--sections-file <path>]
+  templates create --name <n> (--blocks '<json>'|--blocks-file <path>) [--angle <text>]
+  templates update <template-id> [--name] [--blocks '<json>'|--blocks-file <path>] [--angle]
+      A block is { id, kind: 'formatted'|'open', text (markdown), optional? }. In a
+      'formatted' block the markdown IS the shape: prose -> paragraphs; "- item" -> a
+      bulleted list; "1. item" -> numbered steps; a table skeleton -> a comparison;
+      "> quoted" -> reproduced word for word. Empty items ("- ") ask for a list without
+      dictating it — how many it has is decided from the material. An 'open' block asks
+      for coverage in your own words and lets the engine pick the shape.
   templates delete <template-id> --yes
 
 Shredder (diversify content produced outside Letterstory; structure preserved):
@@ -276,6 +312,14 @@ Shredder (diversify content produced outside Letterstory; structure preserved):
                                                        Shred prose through an endpoint (logs telemetry)
   shredder runs [--endpoint <id>] [--limit <n>]        Recent shred calls (telemetry), newest first
 
+Landings (a link + context; auto-mentioned in articles by collections you enable):
+  landings list                                        Your landing pages + mention counts
+  landings get <landing-id>                            Show one landing page
+  landings create --link <url> [--context <text>|--file <path>|--file -]
+                                                       Add a landing page (--link, not --url)
+  landings update <landing-id> [--link <url>] [--context <text>|--file <path>]
+  landings delete <landing-id> --yes
+
 Insights:
   insights site [--period 14d|30d|90d] [--collection <uuid>]
   insights post <article-id> [--period 14d|30d|90d]
@@ -283,7 +327,7 @@ Insights:
 
 Anything else:
   tools list                         List every tool this server exposes, by name
-  tools show <name>                  Show one tool's capability + full argument schema
+  tools show <name>                  Show one tool's capability, argument schema, and return shape
   call <tool> [--args '<json>'] [--flag value …]     Call any tool directly
   tool <name> [--arg k=v …] [--json-args '<json>'] [--stdin]
                                       Call any tool with schema-coerced arguments
@@ -334,12 +378,15 @@ const CLIENT_COMMANDS = {
 	series: cmdSeries,
 	insights: cmdInsights,
 	research: cmdResearch,
+	autopen: cmdAutoPen,
 	covers: cmdCovers,
 	kernel: cmdKernel,
 	"phantom-job": cmdPhantomJob,
+	"phantom-onboard": cmdOnboard,
 	seers: cmdSeers,
 	templates: cmdTemplates,
 	shredder: cmdShredder,
+	landings: cmdLandings,
 };
 
 // LETTERSTORY_POLL_INTERVAL_MS / LETTERSTORY_MAX_POLLS let an operator (or an
@@ -382,7 +429,10 @@ export async function run(argv, io = defaultIo()) {
 		return 0;
 	}
 
-	const handler = CLIENT_COMMANDS[command];
+	// Under the phantom-branded binary, `phantom onboard` is the natural spelling — accept
+	// it as an alias for the recipe so users don't type the stuttering `phantom phantom-onboard`.
+	// The `letterstory` binary keeps only `phantom-onboard`, so it never shadows `onboarding`.
+	const handler = CLIENT_COMMANDS[command] ?? (bin === "phantom" && command === "onboard" ? cmdOnboard : undefined);
 	if (!handler) {
 		io.error(`Unknown command: ${command}`);
 		io.error(`Run \`${bin} help\` for usage.`);

package/lib/client.mjs

@@ -87,8 +87,9 @@ export class LetterstoryClient {
 		return `${this.url}/api/mcp`;
 	}
 
-	// Unauthenticated discovery (GET /api/mcp): tool names + descriptions, no schema.
-	// Lets `letterstory tools` work before you've logged in.
+	// Unauthenticated discovery (GET /api/mcp): tool names, descriptions, capability, and
+	// the derived input + output schemas. Lets `letterstory tools`/`tools show` work before
+	// you've logged in.
 	async discover() {
 		if (this.verbose) this.verboseLog(`» GET ${this.mcpEndpoint}`);
 		let res;

package/lib/commands/autopen.mjs

@@ -0,0 +1,59 @@
+// `autopen` — run a collection's full Auto-Pen sequence over an existing draft:
+// research, write with the writing kernel, then the collection's Enhance flow.
+//
+// This is the command that makes a TEMPLATE take effect. A template bound with
+// `collections autopen <id> --template-key <key>` is read inside the Auto-Pen run and
+// nowhere else, so `kernel run` (which hands the draft's current text straight to a
+// kernel) will not produce a templated post no matter how the collection is configured.
+//
+// A run takes 10-40 minutes, so `start` returns as soon as it is queued. `status` both
+// reports and nudges the run along; a sweep also advances it every 5 minutes, so a run
+// finishes whether or not anyone polls.
+
+import { CliError } from "../client.mjs";
+import { flagBool, requireFlag, printResult, ok } from "./shared.mjs";
+
+export async function cmdAutoPen(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "start":
+		case "run":
+			return autoPenStart(rest);
+		case "status":
+			return autoPenStatus(rest);
+		case "cancel":
+			return autoPenCancel(rest);
+		default:
+			throw new CliError(`Unknown autopen subcommand: ${sub ?? "(none)"}. Try: start, status, cancel`);
+	}
+}
+
+async function autoPenStart(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const result = await client.callTool("run_auto_pen", { article_id: article });
+	ok(ctx, `Auto-Pen started. Check progress with: autopen status --article ${article}`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function autoPenStatus(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const result = await client.callTool("get_auto_pen_status", { article_id: article });
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function autoPenCancel(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	if (!flagBool(flags.yes)) {
+		throw new CliError("Cancelling stops a run in progress. Re-run with --yes to confirm.");
+	}
+	const result = await client.callTool("cancel_auto_pen", { article_id: article });
+	ok(ctx, "Auto-Pen cancelled.");
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/collections.mjs

@@ -21,9 +21,11 @@ export async function cmdCollections(ctx) {
 			return collectionsDelete(rest);
 		case "assign":
 			return collectionsAssign(rest);
+		case "autopen":
+			return collectionsAutoPen(rest);
 		default:
 			throw new CliError(
-				`Unknown collections subcommand: ${sub ?? "(none)"}. Try: list, new, update, delete, assign`
+				`Unknown collections subcommand: ${sub ?? "(none)"}. Try: list, new, update, delete, assign, autopen`
 			);
 	}
 }
@@ -99,3 +101,45 @@ async function collectionsAssign(ctx) {
 	printResult(io, flags, result);
 	return 0;
 }
+
+/**
+ * `collections autopen <id>` — the Auto-Pen settings the app's panel writes, including which
+ * template the collection's posts compose with. Without it, a template authored through this
+ * CLI could be created but never actually used by anything.
+ *
+ * A patch: only the flags given are sent, and the server leaves the rest alone.
+ */
+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";
+
+	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."
+		);
+	}
+
+	const result = await client.callTool("update_auto_pen_config", patch);
+	ok(ctx, `Auto-Pen settings updated for ${collectionId}.`);
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/connectors.mjs

@@ -3,7 +3,7 @@
 // phantomstory-cli's connectors.ts.
 
 import { CliError } from "../client.mjs";
-import { flagStr, requireFlag, requirePositional, printResult, compact, ok } from "./shared.mjs";
+import { flagStr, flagBool, requireFlag, requirePositional, printResult, compact, ok } from "./shared.mjs";
 
 export async function cmdConnectors(ctx) {
 	const sub = ctx.positionals[0];
@@ -34,11 +34,16 @@ async function connectorsPublish(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 result = await client.callTool("publish_to_connector", args);
 	ok(ctx, `Publishing to ${to}.`);

package/lib/commands/discovery.mjs

@@ -73,17 +73,55 @@ function renderTool(io, tool) {
 		const detail = detailOf(props[name]);
 		io.log(`    ${name} (${typeLabel(props[name])}, ${req})${detail ? ` — ${detail}` : ""}`);
 	}
+	renderReturns(io, tool.outputSchema);
+}
+
+// The object node to descend into for a field: the node itself if it has
+// properties, or an array's element when that element is an object. Mirrors the
+// `/docs` "Returns" tree so the CLI and the web console describe one shape.
+function returnObject(node) {
+	if (!node || typeof node !== "object") return null;
+	if (node.properties) return node;
+	if (node.type === "array" && node.items?.properties) return node.items;
+	if (Array.isArray(node.anyOf)) return node.anyOf.find((n) => n?.properties) ?? null;
+	return null;
+}
+
+// Print the tool's success-response shape as an indented `name (type)` tree, so a
+// caller sees what comes back without running the call. Fed by the `outputSchema`
+// that `tools/list` now advertises; silent for a tool whose return isn't modelled.
+function renderReturns(io, schema) {
+	const root = returnObject(schema);
+	if (!root?.properties) return;
+	io.log(``);
+	io.log(`  returns:`);
+	const walk = (node, indent) => {
+		const obj = returnObject(node);
+		if (!obj?.properties) return;
+		const req = new Set(obj.required ?? []);
+		for (const [name, child] of Object.entries(obj.properties)) {
+			const opt = req.has(name) ? "" : ", optional";
+			const desc = child.description ? ` — ${child.description}` : "";
+			io.log(`${" ".repeat(indent)}${name} (${typeLabel(child)}${opt})${desc}`);
+			walk(child, indent + 2);
+		}
+	};
+	walk(root, 4);
 }
 
 function typeLabel(prop) {
 	if (!prop) return "any";
 	if (prop.enum) return "enum";
+	if (prop.type === "array") return `${typeLabel(prop.items)}[]`;
 	if (typeof prop.type === "string") return prop.type;
 	if (Array.isArray(prop.type)) return prop.type.filter((t) => t !== "null").join("|") || "any";
 	if (prop.anyOf) {
-		const types = prop.anyOf.map((a) => (typeof a.type === "string" ? a.type : "any")).filter((t) => t !== "null");
-		return [...new Set(types)].join("|") || "any";
+		const nullable = prop.anyOf.some((a) => a?.type === "null");
+		const types = prop.anyOf.filter((a) => a?.type !== "null").map(typeLabel);
+		const base = [...new Set(types)].join("|") || "any";
+		return nullable ? `${base}|null` : base;
 	}
+	if (prop.properties) return "object";
 	return "any";
 }
 

package/lib/commands/landings.mjs

@@ -0,0 +1,86 @@
+// `landings` — manage landing pages: a link plus context describing what lives there.
+// Collections with auto-mention enabled weave relevant landing pages into articles as
+// they're written. NOTE: the landing's URL is passed as --link, not --url, because
+// --url is the global flag that overrides the API base URL.
+
+import { CliError } from "../client.mjs";
+import { flagStr, requireFlag, requirePositional, readBodyInput, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdLandings(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return landingsList(rest);
+		case "get":
+			return landingsGet(rest);
+		case "new":
+		case "create":
+			return landingsCreate(rest);
+		case "update":
+			return landingsUpdate(rest);
+		case "delete":
+		case "rm":
+			return landingsDelete(rest);
+		default:
+			throw new CliError(
+				`Unknown landings subcommand: ${sub ?? "(none)"}. Try: list, get, create, update, delete`
+			);
+	}
+}
+
+async function landingsList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_landings", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function landingsGet(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "landing-id");
+	const result = await client.callTool("get_landing", { landing_id: id });
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function landingsCreate(ctx) {
+	const { client, flags, io } = ctx;
+	// --link (not --url: --url is the global API-base override) is the landing's URL.
+	const url = requireFlag(flags, "link");
+	// Context comes from --context, or --body/--file/stdin for a larger blob.
+	const context = flagStr(flags.context) ?? readBodyInput(flags);
+	const result = await client.callTool("create_landing", compact({ url, context }));
+	ok(ctx, `Created landing page ${url}.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function landingsUpdate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "landing-id");
+	const url = flagStr(flags.link);
+	const context = flagStr(flags.context) ?? readBodyInput(flags);
+	const patch = compact({ landing_id: id, url, context });
+	if (Object.keys(patch).length <= 1) {
+		throw new CliError("Nothing to update — pass --link <url> and/or --context <text> (or --file <path>).");
+	}
+	const result = await client.callTool("update_landing", patch);
+	ok(ctx, "Updated landing page.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function landingsDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "landing-id");
+	if (!flags.yes) {
+		io.error(`Re-run with --yes to confirm: ${ctx.bin} landings delete ${id} --yes`);
+		return 1;
+	}
+	const result = await client.callTool("delete_landing", { landing_id: id });
+	ok(ctx, "Landing page deleted.");
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/onboard.mjs

@@ -0,0 +1,154 @@
+// `onboard` — the one-shot phantom onboarding recipe: a client domain in, a live phantom
+// blog with its first post(s) out. It drives ONE server tool, `onboard_phantom`:
+//   - a bare `onboard <domain>` is a safe DRY RUN (accept:false) — it prints the proposed
+//     plan (masthead name, description, strategy, cadence/cover/seed defaults) and stops.
+//   - `--accept` (or any override flag) APPLIES: `onboard_phantom{accept:true}` starts a
+//     durable onboarding job server-side and returns a job_id; this command then polls
+//     `get_phantom_onboard_status` until the job is done (provision → configure → seed).
+//
+// `--about "<the beat>"` is the highest-leverage flag: it becomes the publication's planner
+// steering prompt, so it shapes the topic map and every post the site ever writes — not just
+// the name. Use it when the client already has a phantom and this one needs a different beat.
+//
+// `--domain <host>` records a custom domain; nothing is bought unless you also pass
+// `--domain-mode buy_now`, which SPENDS money against a 2-per-org, $30-per-domain cap.
+//
+// IMPORTANT: the masthead name is committed when the site is created (it seeds the URL),
+// so to use a name other than the inferred one, pass --name BEFORE applying. The first
+// posts are written by background jobs (20-40min each); they're reported as job ids and
+// this command does not block on them — poll with `phantom-job status <job-id>`.
+
+import { CliError } from "../client.mjs";
+import { flagStr, flagNum, flagBool, requirePositional, printResult, compact, ok, pollUntil } from "./shared.mjs";
+
+const COVER_STYLES = ["editorial_image", "full_ai", "line_art"];
+const DOMAIN_MODES = ["subdomain", "buy_now", "connect_later"];
+
+function formatPlan(plan) {
+	const lines = [
+		`Plan for ${plan.domain} (client: ${plan.client_label})`,
+		`  proposed name: ${plan.proposed_name ?? "(none — pass --name)"}`,
+		`  description:   ${plan.description}`,
+		`  defaults:      ${plan.defaults.cadence_per_week}/week · ${plan.defaults.cover_canvas} · seed ${plan.defaults.posts_to_seed}`,
+	];
+	if (plan.direction) lines.push(`  direction:     ${plan.direction}`);
+	if (plan.domain_plan?.site_domain) {
+		lines.push(`  domain:        ${plan.domain_plan.site_domain} (${plan.domain_plan.mode})`);
+	}
+	if (plan.strategy) {
+		lines.push(`  topics:        ${(plan.strategy.priority_topics ?? []).slice(0, 5).join(", ") || "(none)"}`);
+	} else {
+		lines.push(`  strategy:      (none inferred)`);
+	}
+	lines.push(`  note:          ${plan.note}`);
+	return lines.join("\n");
+}
+
+function formatStatus(s) {
+	const lines = [
+		`Onboarding ${s.status} at stage "${s.stage}"`,
+		`  domain:     ${s.domain}`,
+		`  deployment: ${s.deployment_id ?? "(pending)"}`,
+		`  collection: ${s.collection_id ?? "(pending)"}`,
+	];
+	if (s.error) lines.push(`  error:      ${s.error}`);
+	if (s.seed_job_ids?.length) {
+		lines.push(`  seeded ${s.seed_job_ids.length} post job(s):`);
+		for (const id of s.seed_job_ids) lines.push(`    - ${id}`);
+		lines.push(`  poll them with: phantom-job status <job-id>`);
+	}
+	return lines.join("\n");
+}
+
+// Build the overrides object the tool accepts from the CLI flags (snake_case keys).
+function overridesFromFlags(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);
+	// 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),
+		site_domain: siteDomain,
+		domain_mode: domainMode,
+		is_test: flagBool(flags["real"]) ? false : undefined,
+	});
+}
+
+export async function cmdOnboard(ctx) {
+	const { client, flags, io } = ctx;
+	const domain = requirePositional(ctx.positionals, 0, "domain");
+	const overrides = overridesFromFlags(flags);
+
+	// Step 1: dry-run plan (accept defaults to false server-side). Persists nothing.
+	const plan = await client.callTool(
+		"onboard_phantom",
+		compact({ domain, overrides: Object.keys(overrides).length ? overrides : undefined })
+	);
+	ok(ctx, "Onboarding plan:");
+	printResult(io, flags, plan, formatPlan);
+
+	if (flagBool(flags["dry-run"])) return 0;
+
+	// Step 2: the review gate. A bare, unaccepted run stops here so nothing is provisioned
+	// by accident — re-run with --accept (or an override flag) once happy.
+	const overrideGiven = Object.keys(overrides).length > 0;
+	if (!flagBool(flags.accept) && !overrideGiven) {
+		ok(
+			ctx,
+			"Re-run with --accept to apply, or pass --about/--name/--cadence/--cover/--posts/--theme/--domain to adjust. " +
+				"Note: --name is committed at create (it seeds the URL)."
+		);
+		return 0;
+	}
+	if (plan.proposed_name === null && flagStr(flags.name) === undefined) {
+		throw new CliError(
+			"No blog name available: the plan proposed none (strategy soft-failed). Pass --name <MastheadName> to apply."
+		);
+	}
+
+	// Step 3: apply — start the durable onboarding job.
+	ok(ctx, "Applying — starting the onboarding job…");
+	const started = await client.callTool(
+		"onboard_phantom",
+		compact({ domain, accept: true, overrides: Object.keys(overrides).length ? overrides : undefined })
+	);
+	const jobId = started.job_id;
+	if (!jobId) throw new CliError("onboard_phantom did not return a job id.");
+
+	// Step 4: poll the job to a terminal state, printing stage transitions.
+	let lastStage = null;
+	const final = await pollUntil(
+		io,
+		async () => {
+			const s = await client.callTool("get_phantom_onboard_status", { job_id: jobId });
+			if (s.status === "failed")
+				throw new CliError(`Onboarding failed at stage "${s.stage}": ${s.error ?? "unknown error"}`);
+			if (s.stage !== lastStage) {
+				ok(ctx, `  … ${s.stage}`);
+				lastStage = s.stage;
+			}
+			return { done: s.status === "done", value: s };
+		},
+		{ label: "onboarding to finish", timeoutMs: 20 * 60 * 1000, intervalMs: 4000 }
+	);
+
+	printResult(io, flags, final, formatStatus);
+	return 0;
+}

package/lib/commands/seers.mjs

@@ -625,18 +625,18 @@ async function templatesShow(ctx) {
 	return 0;
 }
 
-function templateSectionsFromFlags(flags) {
-	const inline = flagStr(flags.sections);
-	const file = flagStr(flags["sections-file"]);
+function templateBlocksFromFlags(flags) {
+	const inline = flagStr(flags.blocks);
+	const file = flagStr(flags["blocks-file"]);
 	if (inline === undefined && file === undefined) return undefined;
-	const raw = inline !== undefined ? inline : readFileOrThrow(file, "--sections-file");
+	const raw = inline !== undefined ? inline : readFileOrThrow(file, "--blocks-file");
 	let parsed;
 	try {
 		parsed = JSON.parse(raw);
 	} catch (err) {
-		throw new CliError(`--sections is not valid JSON: ${err.message}`);
+		throw new CliError(`--blocks is not valid JSON: ${err.message}`);
 	}
-	if (!Array.isArray(parsed)) throw new CliError("--sections must be a JSON array of section objects");
+	if (!Array.isArray(parsed)) throw new CliError("--blocks must be a JSON array of block objects");
 	return parsed;
 }
 
@@ -644,11 +644,14 @@ async function templatesCreate(ctx) {
 	const { client, flags, io } = ctx;
 	const name = flagStr(flags.name);
 	const angle = flagStr(flags.angle);
-	const sections = templateSectionsFromFlags(flags);
+	const blocks = templateBlocksFromFlags(flags);
 	if (!name) throw new CliError("Missing required --name");
-	if (!angle) throw new CliError("Missing required --angle");
-	if (!sections) throw new CliError("Missing required --sections '<json>' or --sections-file <path>");
-	const result = await client.callTool("create_template", { name, angle, sections });
+	// `--angle` is OPTIONAL, and omitting it is the better answer. It was required here while
+	// the server schema had already made it optional and the app had dropped the field: a
+	// template constrains a post's SHAPE and never says what it is about, so an angle belongs
+	// to the post — which already has one, from its research direction.
+	if (!blocks) throw new CliError("Missing required --blocks '<json>' or --blocks-file <path>");
+	const result = await client.callTool("create_template", { name, blocks, ...(angle ? { angle } : {}) });
 	ok(ctx, `Template created — key ${result.template?.key}.`);
 	printResult(io, flags, result);
 	return 0;
@@ -659,11 +662,11 @@ async function templatesUpdate(ctx) {
 	const templateId = requirePositional(positionals, 0, "template-id");
 	const name = flagStr(flags.name);
 	const angle = flagStr(flags.angle);
-	const sections = templateSectionsFromFlags(flags);
+	const blocks = templateBlocksFromFlags(flags);
 	// update_template replaces the whole template; fetch current values for any
 	// field the caller didn't pass so a partial edit doesn't blank the rest.
 	let current;
-	if (!name || !angle || !sections) {
+	if (!name || !angle || !blocks) {
 		const existing = await client.callTool("get_template", { template_id: templateId });
 		current = existing.template;
 	}
@@ -671,7 +674,7 @@ async function templatesUpdate(ctx) {
 		template_id: templateId,
 		name: name ?? current.name,
 		angle: angle ?? current.angle,
-		sections: sections ?? current.sections,
+		blocks: blocks ?? current.blocks,
 	});
 	ok(ctx, "Template updated.");
 	printResult(io, flags, result);

package/lib/commands/series.mjs

@@ -17,10 +17,8 @@ export async function cmdSeries(ctx) {
 			return seriesCreate(rest);
 		case "backfill":
 			return seriesBackfill(rest);
-		case "propose":
-			return seriesPropose(rest);
 		default:
-			throw new CliError(`Unknown series subcommand: ${sub ?? "(none)"}. Try: list, create, backfill, propose`);
+			throw new CliError(`Unknown series subcommand: ${sub ?? "(none)"}. Try: list, create, backfill`);
 	}
 }
 
@@ -77,25 +75,3 @@ async function seriesBackfill(ctx) {
 	printResult(io, flags, result);
 	return 0;
 }
-
-function formatProposals(result) {
-	const proposals = result?.proposals ?? [];
-	if (proposals.length === 0) return "No series detected — this blog has no clearly repeating shapes.";
-	return proposals
-		.map((p) => {
-			const matched = p.matchedTitles?.length ?? 0;
-			return [
-				`${p.name} — ${p.description}`,
-				`  covers ${matched} existing post(s); items: ${p.coverage.join(", ")}`,
-			].join("\n");
-		})
-		.join("\n");
-}
-
-async function seriesPropose(ctx) {
-	const { client, flags, io } = ctx;
-	const args = compact({ collection_id: flagStr(flags.collection) });
-	const result = await client.callTool("propose_series", args);
-	printResult(io, flags, result, formatProposals);
-	return 0;
-}

package/lib/commands/shared.mjs

@@ -70,6 +70,25 @@ export function ok(ctx, message) {
 	ctx.io.log(message);
 }
 
+// Poll an async step to a terminal state. `poll` runs one check and returns
+// `{ done, value }`: `done:true` ends the loop and `pollUntil` resolves to `value`.
+// Progress logging is the caller's job (it happens inside `poll`, which has ctx),
+// so this stays --json/--quiet-clean. Throws a CliError once the deadline passes.
+export async function pollUntil(io, poll, opts = {}) {
+	const intervalMs = opts.intervalMs ?? 3000;
+	const timeoutMs = opts.timeoutMs ?? 300000;
+	const label = opts.label ?? "operation";
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		const { done, value } = await poll();
+		if (done) return value;
+		if (Date.now() >= deadline) {
+			throw new CliError(`Timed out waiting for ${label} after ${Math.round(timeoutMs / 1000)}s.`);
+		}
+		await io.sleep(intervalMs);
+	}
+}
+
 // Read a text body from --body, or --file (a path, or "-" for stdin). Returns
 // undefined if neither flag was given, so callers can decide whether that's an error.
 export function readBodyInput(flags) {

package/lib/commands/strategy.mjs

@@ -220,120 +220,11 @@ export async function cmdOnboarding(ctx) {
 			return onboardingStatus(rest);
 		case "step":
 			return onboardingStep(rest);
-		case "magic":
-			return onboardingMagic(rest);
 		default:
-			throw new CliError(`Unknown onboarding subcommand: ${sub ?? "(none)"}. Try: status, step, magic`);
+			throw new CliError(`Unknown onboarding subcommand: ${sub ?? "(none)"}. Try: status, step`);
 	}
 }
 
-// --- magic: enter a domain → strategy filled out -------------------------
-//
-// The G1 "magical onboarding": one command that composes the platform's
-// existing inference into a filled-out strategy — manifesto + stances +
-// identity (infer_org_strategy), optional post-history import from the
-// sitemap, keywords + topic clusters (infer_client_keywords), and detected
-// content series (propose_series → create_series → backfill_series). Every
-// step is idempotent and never clobbers hand-authored data, so re-running is
-// always safe. --dry-run previews series proposals instead of adopting them.
-
-async function onboardingMagic(ctx) {
-	const { client, flags, io } = ctx;
-	const dryRun = flags["dry-run"] === true;
-	const summary = {};
-
-	// 1. Company profile → the domain everything reads from.
-	ok(ctx, "Reading company profile…");
-	const company = await client.callTool("get_company_info", {});
-	const domain = flagStr(flags.domain) ?? company.domain ?? undefined;
-	summary.domain = domain ?? null;
-
-	// 2. Strategy: manifesto, stances, identity — saved with never-clobber guards.
-	ok(ctx, domain ? `Inferring strategy from ${domain}…` : "Inferring strategy…");
-	const strategy = await client.callTool("infer_org_strategy", compact({ domain }));
-	summary.strategy = strategy;
-	if (strategy.status === "skipped") {
-		ok(ctx, `Strategy skipped (${strategy.reason}): ${strategy.detail}`);
-	} else {
-		ok(ctx, strategy.status === "reused" ? "Strategy already in place — kept as-is." : "Strategy saved.");
-	}
-
-	// 3. Post history: optionally import the blog's existing posts from a sitemap
-	//    so clustering/series have an inventory to read.
-	let inventory = await client.callTool("get_content_inventory", {});
-	if (flagStr(flags.sitemap)) {
-		const collectionId = flagStr(flags.collection) ?? (await resolveMainCollection(client));
-		ok(ctx, "Importing existing posts from the sitemap (this can take a while)…");
-		const imported = await client.callTool("import_sitemap", {
-			collection_id: collectionId,
-			sitemap_url: flagStr(flags.sitemap),
-		});
-		summary.sitemap_import = imported;
-		inventory = await client.callTool("get_content_inventory", {});
-	} else if ((inventory.total ?? 0) === 0) {
-		ok(ctx, "No posts in the inventory yet — pass --sitemap <url> to import the blog's history.");
-	}
-	summary.inventory = inventory;
-
-	// 4. Keywords + topic clusters over whatever inventory exists.
-	if ((inventory.total ?? 0) > 0) {
-		ok(ctx, "Inferring keywords and building topic clusters…");
-		summary.keywords = await client.callTool("infer_client_keywords", {});
-	}
-
-	// 5. Series detection — adopt each grounded proposal (create + backfill),
-	//    or just show them under --dry-run.
-	ok(ctx, "Detecting content series…");
-	const proposed = await client.callTool("propose_series", compact({ collection_id: flagStr(flags.collection) }));
-	const proposals = proposed.proposals ?? [];
-	summary.series = [];
-	for (const p of proposals) {
-		if (dryRun) {
-			summary.series.push({ name: p.name, coverage: p.coverage, adopted: false });
-			continue;
-		}
-		const created = await client.callTool("create_series", {
-			name: p.name,
-			description: p.description,
-			coverage: p.coverage,
-		});
-		const backfilled = await client.callTool("backfill_series", {
-			series_id: created.id,
-			collection_id: proposed.collection_id,
-		});
-		summary.series.push({ name: p.name, coverage: p.coverage, adopted: true, backfilled: backfilled.matched });
-		ok(ctx, `Series "${p.name}" created — ${backfilled.matched} existing post(s) reconstructed into it.`);
-	}
-	if (proposals.length === 0) ok(ctx, "No series detected — this blog has no clearly repeating shapes.");
-
-	printResult(io, flags, summary, (s) => {
-		const lines = [];
-		lines.push(`Strategy: ${s.strategy.status}${s.strategy.reason ? ` (${s.strategy.reason})` : ""}`);
-		lines.push(`Inventory: ${s.inventory.total ?? 0} post(s)${s.inventory.lowInventory ? " (low)" : ""}`);
-		if (s.keywords) {
-			lines.push(
-				`Clusters: ${s.keywords.assigned ?? 0} post(s) assigned, ${s.keywords.newClusters ?? 0} new cluster(s)`
-			);
-		}
-		lines.push(
-			s.series.length === 0
-				? "Series: none detected"
-				: `Series: ${s.series.map((x) => `${x.name}${x.adopted ? "" : " (proposed)"}`).join("; ")}`
-		);
-		return lines.join("\n");
-	});
-	return 0;
-}
-
-// The org's main (non-phantom) collection — where history imports and
-// org-level series live. list_collections includes `kind` for exactly this.
-async function resolveMainCollection(client) {
-	const result = await client.callTool("list_collections", {});
-	const main = (result.items ?? []).find((c) => c.kind !== "phantom");
-	if (!main) throw new CliError("No main collection found — create one first, or pass --collection <id>.");
-	return main.collection_id;
-}
-
 async function onboardingStatus(ctx) {
 	const { client, flags, io } = ctx;
 	const result = await client.callTool("get_onboarding_status", {});

package/lib/commands.mjs

@@ -18,7 +18,10 @@ export * from "./commands/series.mjs";
 export * from "./commands/insights.mjs";
 export * from "./commands/covers.mjs";
 export * from "./commands/research.mjs";
+export * from "./commands/autopen.mjs";
 export * from "./commands/kernel.mjs";
 export * from "./commands/phantom-job.mjs";
+export * from "./commands/onboard.mjs";
 export * from "./commands/seers.mjs";
 export * from "./commands/shredder.mjs";
+export * from "./commands/landings.mjs";

package/package.json

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