@letterstory/cli 0.15.3 → 0.15.4

package/README.md

@@ -261,6 +261,32 @@ LETTERSTORY_STAFF_API_KEY=<your staff key with org:create> \
 Everything the parent job does is also its own tool for existing orgs:
 `ensure_collection_enhance_flow`, `provision_org_visuals`, `propose_seers` (`--args '{"apply":true}'`).
 
+### Propose, then onboard a phantom
+
+The Fleet wizard's Plan and Name screens as two commands: pick the beat, then the name,
+before anything is created. Both persist nothing and spend nothing (domain checks are
+read-only). Save the proposal as JSON; the chosen plan travels by `--plan-file` + `--plan-id`,
+so its direction AND its content areas are pinned on the site exactly as approved.
+
+```bash
+# Step one: the beat. Omit the domain to use your org's own.
+letterstory phantom-onboard propose acme.com --json > proposal.json
+letterstory phantom-onboard propose acme.com --about "bank regulators on agentic AI"   # variations on a beat
+
+# Step two: the name — candidate mastheads for ONE plan, each with its own priced domains.
+letterstory phantom-onboard mastheads acme.com --plan-file proposal.json --plan-id plan-2
+jq '.topicPlans[1]' proposal.json | letterstory phantom-onboard mastheads acme.com --plan-file -
+
+# 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
+```
+
+`propose` reads the client's homepage and returns distinct editorial angles (`topicPlans`), the
+single fallback plan, the client's existing publications with an overlap warning, and the org's
+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.
+
 ## Content series
 
 A series is a coverage obligation, not a keyword bet: "content that looks like this",

package/lib/cli.mjs

@@ -43,7 +43,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.15.3";
+export const VERSION = "0.15.4";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -305,6 +305,26 @@ Phantom onboarding recipe (domain -> live phantom blog with first posts):
                                                        create (it seeds the URL); pass it before
                                                        applying. --domain-mode buy_now SPENDS
                                                        money (2/org, $30 cap).
+          [--plan-file <path|-> --plan-id <id>]        Pin a topic plan chosen with the propose
+                                                       lane below: its direction AND pillars are
+                                                       applied verbatim, so the site covers what
+                                                       was approved.
+
+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]
+                                                       Step ONE: read the client's homepage and
+                                                       propose distinct editorial angles
+                                                       (topicPlans), the fallback plan, the
+                                                       client's existing publications (overlap
+                                                       warning) and domain headroom. Omit the
+                                                       domain to use the org's own. Save it with
+                                                       --json > proposal.json for step two.
+  ${bin === "phantom" ? "onboard" : "phantom-onboard"} mastheads <client-domain> --plan-file <path|-> [--plan-id <id>]
+                                                       Step TWO: names for ONE chosen plan, each
+                                                       with its own priced, buyable domains.
+                                                       --plan-file takes a saved proposal (then
+                                                       --plan-id picks the plan) or a single plan
+                                                       (--plan '<json>' inline, or - for stdin).
 
 Collection onboarding (your OWN blog, on your org's domain — no provisioning):
   ${bin === "phantom" ? "onboard" : "phantom-onboard"} collection [--collection <uuid>] [--name "<collection name>"]

package/lib/commands/onboard.mjs

@@ -33,8 +33,28 @@
 // map, binds SEO demand, and stocks the Headlines tab. `--watch` polls to completion,
 // printing each review note as the job writes it.
 
+// `onboard propose` / `onboard mastheads` are the PROPOSE lane — the Fleet wizard's Plan and
+// Name screens, driven by the same two tools those screens call (`propose_phantom_plan`,
+// `propose_phantom_mastheads`) — so a script or an agent can pick the beat, then the name,
+// BEFORE `onboard <domain>` commits anything. Both persist nothing and spend nothing (domain
+// checks are read-only). The chosen topic plan travels as JSON: save the proposal with
+// `--json > proposal.json`, then hand it back with `--plan-file proposal.json --plan-id <id>`
+// (or one plan on stdin with `--plan-file -`). `onboard <domain> --plan-file … --plan-id …`
+// pins that plan's direction AND pillars verbatim, which is what makes an approved plan
+// binding instead of a preview the topic map may wander from.
+
 import { CliError } from "../client.mjs";
-import { flagStr, flagNum, flagBool, requirePositional, printResult, compact, ok, pollUntil } from "./shared.mjs";
+import {
+	flagStr,
+	flagNum,
+	flagBool,
+	requirePositional,
+	printResult,
+	compact,
+	ok,
+	pollUntil,
+	readTextInput,
+} from "./shared.mjs";
 
 const COVER_STYLES = ["editorial_image", "full_ai", "line_art"];
 const DOMAIN_MODES = ["subdomain", "buy_now", "connect_later"];
@@ -75,8 +95,145 @@ function formatStatus(s) {
 	return lines.join("\n");
 }
 
+// The topic plan a step-two command needs, as JSON from --plan '<json>' or --plan-file
+// <path|->. Accepts either one plan object (as `propose` lists them under topicPlans) or a
+// whole saved proposal (`propose … --json`), in which case --plan-id names which of its
+// topic plans to use. Returns undefined when neither flag was given.
+export function readTopicPlan(flags) {
+	const raw = readTextInput(flags, "plan", "plan-file");
+	if (raw === undefined) return undefined;
+	let doc;
+	try {
+		doc = JSON.parse(raw);
+	} catch (err) {
+		throw new CliError(`--plan is not valid JSON: ${err.message}`);
+	}
+	const planId = flagStr(flags["plan-id"]);
+	if (doc && Array.isArray(doc.topicPlans)) {
+		const ids = doc.topicPlans.map((p) => p.id).join(", ") || "none";
+		if (!planId) {
+			throw new CliError(`That is a whole proposal; pass --plan-id to pick one of its topic plans (${ids}).`);
+		}
+		const plan = doc.topicPlans.find((p) => p.id === planId);
+		if (!plan) throw new CliError(`No topic plan "${planId}" in the proposal (have: ${ids}).`);
+		return plan;
+	}
+	if (!doc || typeof doc !== "object" || typeof doc.direction !== "string" || !Array.isArray(doc.pillars)) {
+		throw new CliError(
+			"--plan must be one topic plan {id, title, direction, pillars} as `propose` returns them, or a saved --json proposal plus --plan-id."
+		);
+	}
+	return doc;
+}
+
+// The recipe's spelling under this binary, for next-step hints.
+function recipeName(ctx) {
+	return ctx.bin === "phantom" ? "onboard" : "phantom-onboard";
+}
+
+// A priced domain candidate on one line: what it costs, or why it can't be bought.
+function formatDomainSuggestion(d) {
+	if (!d.available) return `${d.domain} (taken)`;
+	const price = d.purchasePrice === null || d.purchasePrice === undefined ? "unpriced" : `$${d.purchasePrice}`;
+	const renews = d.renewalPrice === null || d.renewalPrice === undefined ? "" : `, renews $${d.renewalPrice}`;
+	return `${d.domain} ${price}${renews}${d.purchasable ? "" : " — over the cap"}`;
+}
+
+function formatTopicPlan(p) {
+	const lines = [`    ${p.id}  ${p.title}`, `      direction: ${p.direction}`];
+	lines.push(`      pillars:   ${(p.pillars ?? []).map((x) => x.name).join(" · ") || "(none)"}`);
+	if (p.rationale) lines.push(`      why:       ${p.rationale}`);
+	return lines;
+}
+
+function formatProposal(r) {
+	const plan = r.plan;
+	const lines = [
+		`Proposal for ${r.clientDomain} (client: ${r.clientName})`,
+		`  fallback plan: ${plan.name ?? "(no name — pass --name)"} — ${plan.description}`,
+		`  defaults:      ${plan.defaults.cadence_per_week}/week · ${plan.defaults.cover_canvas} · seed ${plan.defaults.posts_to_seed}`,
+	];
+	if (r.topicPlans?.length) {
+		lines.push(`  topic plans (pick one):`);
+		for (const p of r.topicPlans) lines.push(...formatTopicPlan(p));
+	} else {
+		lines.push(`  topic plans:   (none proposed — the fallback plan is the answer)`);
+	}
+	if (r.siblings?.length) {
+		lines.push(`  this client already publishes:`);
+		for (const s of r.siblings) lines.push(`    - ${s.name}${s.direction ? ` — ${s.direction}` : ""}`);
+	}
+	if (r.overlapWarning) lines.push(`  overlap:       ${r.overlapWarning}`);
+	if (r.domains?.length) {
+		lines.push(`  domains (for the fallback masthead):`);
+		for (const d of r.domains) lines.push(`    - ${formatDomainSuggestion(d)}`);
+	}
+	lines.push(
+		`  domain headroom: ${r.domainHeadroom === null || r.domainHeadroom === undefined ? "unlimited" : `${r.domainHeadroom} more custom domain(s)`}`
+	);
+	lines.push(`  note:          ${plan.note}`);
+	return lines.join("\n");
+}
+
+function formatMastheads(r, plan) {
+	if (!r.options?.length) {
+		return `No mastheads proposed for "${plan.title}" (model unavailable) — keep the fallback plan's name.`;
+	}
+	const lines = [`Mastheads for "${plan.title}" (best first):`];
+	r.options.forEach((o, i) => {
+		lines.push(`  ${i + 1}. ${o.masthead} — ${o.description}`);
+		if (o.domains?.length) lines.push(`     domains: ${o.domains.map(formatDomainSuggestion).join(" · ")}`);
+	});
+	return lines.join("\n");
+}
+
+// `onboard propose [<client-domain>]` — step ONE of the propose lane. The domain is optional
+// because the tool falls back to the org's own recorded domain (the key's org IS the client).
+async function cmdOnboardPropose(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({
+		client_domain: ctx.positionals[0],
+		direction: flagStr(flags.about) ?? flagStr(flags.direction),
+		name: flagStr(flags.name),
+	});
+	ok(ctx, "Proposing…");
+	const proposal = await client.callTool("propose_phantom_plan", args);
+	printResult(io, flags, proposal, formatProposal);
+	if (proposal.topicPlans?.length) {
+		ok(
+			ctx,
+			`Next: save this with --json > proposal.json, pick a plan, then ${recipeName(ctx)} mastheads ${proposal.clientDomain} --plan-file proposal.json --plan-id <id>`
+		);
+	}
+	return 0;
+}
+
+// `onboard mastheads <client-domain> --plan-file <path|-> [--plan-id <id>]` — step TWO.
+async function cmdOnboardMastheads(ctx) {
+	const { client, flags, io } = ctx;
+	const clientDomain = requirePositional(ctx.positionals, 0, "client-domain");
+	const plan = readTopicPlan(flags);
+	if (!plan) {
+		throw new CliError(
+			"onboard mastheads needs the chosen topic plan: --plan '<json>' or --plan-file <path|-> (add --plan-id when the file is a whole proposal)."
+		);
+	}
+	ok(ctx, `Proposing mastheads for "${plan.title}"…`);
+	const result = await client.callTool("propose_phantom_mastheads", { client_domain: clientDomain, plan });
+	printResult(io, flags, result, (r) => formatMastheads(r, plan));
+	if (result.options?.length) {
+		ok(
+			ctx,
+			`Next: ${recipeName(ctx)} ${clientDomain} --name "<masthead>" --plan-file proposal.json --plan-id ${plan.id} [--domain <host> --domain-mode buy_now] [--real]`
+		);
+	}
+	return 0;
+}
+
 // Build the overrides object the tool accepts from the CLI flags (snake_case keys).
 function overridesFromFlags(flags) {
+	// A chosen topic plan pins direction + pillars; an explicit --about still wins on direction.
+	const plan = readTopicPlan(flags);
 	const cover = flagStr(flags.cover);
 	if (cover !== undefined && !COVER_STYLES.includes(cover)) {
 		throw new CliError(`--cover must be one of: ${COVER_STYLES.join(", ")}`);
@@ -99,7 +256,9 @@ function overridesFromFlags(flags) {
 		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),
+		direction: flagStr(flags.about) ?? flagStr(flags.direction) ?? plan?.direction,
+		// The approved plan's content areas become the topic map's pillars VERBATIM.
+		pillars: plan?.pillars,
 		site_domain: siteDomain,
 		domain_mode: domainMode,
 		is_test: flagBool(flags["real"]) ? false : undefined,
@@ -380,6 +539,13 @@ export async function cmdOnboard(ctx) {
 	if (ctx.positionals[0] === "sync-sitemap") {
 		return cmdOnboardSyncSitemap({ ...ctx, positionals: ctx.positionals.slice(1) });
 	}
+	// `onboard propose [<client-domain>]` / `onboard mastheads <client-domain>` — the propose lane.
+	if (ctx.positionals[0] === "propose") {
+		return cmdOnboardPropose({ ...ctx, positionals: ctx.positionals.slice(1) });
+	}
+	if (ctx.positionals[0] === "mastheads") {
+		return cmdOnboardMastheads({ ...ctx, positionals: ctx.positionals.slice(1) });
+	}
 	const domain = requirePositional(ctx.positionals, 0, "domain");
 	const overrides = overridesFromFlags(flags);
 
@@ -399,7 +565,8 @@ export async function cmdOnboard(ctx) {
 	if (!flagBool(flags.accept) && !overrideGiven) {
 		ok(
 			ctx,
-			"Re-run with --accept to apply, or pass --about/--name/--cadence/--cover/--posts/--theme/--domain to adjust. " +
+			"Re-run with --accept to apply, or pass --about/--name/--cadence/--cover/--posts/--theme/--domain to adjust " +
+				`(or pick the beat and name first: ${recipeName(ctx)} propose / mastheads). ` +
 				"Note: --name is committed at create (it seeds the URL)."
 		);
 		return 0;

package/lib/commands/shared.mjs

@@ -89,16 +89,20 @@ export async function pollUntil(io, poll, opts = {}) {
 	}
 }
 
-// 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) {
-	const body = flagStr(flags.body);
-	if (body !== undefined) return body;
-	const file = flagStr(flags.file);
+// Read a text value from an inline flag, or from a file flag (a path, or "-" for
+// stdin). Returns undefined if neither flag was given, so callers can decide whether
+// that's an error. `readBodyInput` is the --body/--file pairing; the propose lane reads
+// a topic plan the same way through --plan/--plan-file.
+export function readTextInput(flags, valueFlag, fileFlag) {
+	const inline = flagStr(flags[valueFlag]);
+	if (inline !== undefined) return inline;
+	const file = flagStr(flags[fileFlag]);
 	if (file === undefined) return undefined;
 	if (file === "-") {
 		if (process.stdin.isTTY) {
-			throw new CliError("No data on stdin. Pipe input in, or use --body/--file <path> instead of --file -.");
+			throw new CliError(
+				`No data on stdin. Pipe input in, or use --${valueFlag}/--${fileFlag} <path> instead of --${fileFlag} -.`
+			);
 		}
 		try {
 			return readFileSync(0, "utf8");
@@ -109,6 +113,11 @@ export function readBodyInput(flags) {
 	try {
 		return readFileSync(file, "utf8");
 	} catch (err) {
-		throw new CliError(`Could not read --file ${file}: ${err.message}`);
+		throw new CliError(`Could not read --${fileFlag} ${file}: ${err.message}`);
 	}
 }
+
+// Read a text body from --body, or --file (a path, or "-" for stdin).
+export function readBodyInput(flags) {
+	return readTextInput(flags, "body", "file");
+}

package/package.json

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