@letterstory/cli 0.15.3 → 0.15.5

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

@@ -19,6 +19,7 @@ import {
 	cmdDomains,
 	cmdPosts,
 	cmdPublished,
+	cmdReviewers,
 	cmdCollections,
 	cmdAuthors,
 	cmdFlows,
@@ -43,7 +44,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.15.3";
+export const VERSION = "0.15.5";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -183,6 +184,13 @@ Content:
   published list [--limit <n>] [--collection <uuid>] [--format html|md]
   published show (--id <uuid> | --slug <slug>) [--format html|md]
 
+Reviewers:
+  reviewers standing list                             List the org's standing reviewers
+  reviewers standing add --email <e> [--name <n>]      Auto-invite this contact as a
+                                                         guest reviewer on every future
+                                                         finished draft (no email sent now)
+  reviewers standing remove <reviewer-id>              Stop future auto-invites
+
 Collections:
   collections list                                   List your collections
   collections new --name <n> [--description <text>]
@@ -305,6 +313,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>"]
@@ -402,6 +430,10 @@ 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>]
+                                                       [--aggression standard|high|max]
+                                                       standard (default) keeps the piece's own terminology;
+                                                       high rewrites more and may reword recurring terms;
+                                                       max rewrites hardest — expect vocabulary drift
                                                        Shred prose through an endpoint (logs telemetry)
   shredder runs [--endpoint <id>] [--limit <n>]        Recent shred calls (telemetry), newest first
 
@@ -462,6 +494,7 @@ const CLIENT_COMMANDS = {
 	domains: cmdDomains,
 	posts: cmdPosts,
 	published: cmdPublished,
+	reviewers: cmdReviewers,
 	collections: cmdCollections,
 	authors: cmdAuthors,
 	flows: cmdFlows,

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/reviewers.mjs

@@ -0,0 +1,62 @@
+// `reviewers standing` — an org's standing reviewers (organization_standing_reviewers):
+// external contacts auto-invited as a guest reviewer on every article that reaches a
+// finished, never-published draft (src/lib/services/standing-reviewers.ts + the
+// notify-standing-reviewers cron), instead of inviting them by hand on each article.
+// Same flag/positional/io conventions as posts.mjs — no commander, no color.
+
+import { CliError } from "../client.mjs";
+import { flagStr, requireFlag, requirePositional, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdReviewers(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "standing":
+			return cmdStandingReviewers(rest);
+		default:
+			throw new CliError(`Unknown reviewers subcommand: ${sub ?? "(none)"}. Try: standing`);
+	}
+}
+
+async function cmdStandingReviewers(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return standingList(rest);
+		case "add":
+			return standingAdd(rest);
+		case "remove":
+		case "rm":
+			return standingRemove(rest);
+		default:
+			throw new CliError(`Unknown reviewers standing subcommand: ${sub ?? "(none)"}. Try: list, add, remove`);
+	}
+}
+
+async function standingList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_standing_reviewers", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function standingAdd(ctx) {
+	const { client, flags, io } = ctx;
+	const email = requireFlag(flags, "email");
+	const args = compact({ email, name: flagStr(flags.name) });
+	const result = await client.callTool("add_standing_reviewer", args);
+	ok(ctx, `Added ${email} as a standing reviewer.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function standingRemove(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "reviewer-id");
+	const result = await client.callTool("remove_standing_reviewer", { reviewer_id: id });
+	ok(ctx, "Removed.");
+	printResult(io, flags, result);
+	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/lib/commands/shredder.mjs

@@ -80,6 +80,8 @@ async function shredderRun(ctx) {
 		text,
 		coverage: flagNum(flags.coverage),
 		attempts_per_unit: flagNum(flags.attempts),
+		// How hard to rewrite. Validated service-side; sent only when the caller asked.
+		...(flags.aggression ? { aggression: String(flags.aggression) } : {}),
 	});
 	const result = await client.callTool("run_shred", args);
 	ok(ctx, "Shred complete.");

package/lib/commands.mjs

@@ -9,6 +9,7 @@ export * from "./commands/discovery.mjs";
 export * from "./commands/deploy.mjs";
 export * from "./commands/mcp.mjs";
 export * from "./commands/posts.mjs";
+export * from "./commands/reviewers.mjs";
 export * from "./commands/collections.mjs";
 export * from "./commands/authors.mjs";
 export * from "./commands/flows.mjs";

package/package.json

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