@letterstory/cli 0.3.0 → 0.4.1

package/README.md

@@ -207,6 +207,54 @@ letterstory onboarding status
 letterstory onboarding step --complete connect_domain
 ```
 
+## Research and writing kernels
+
+Two different steps, in this order. The **research agent** reads the live web and writes a
+sourced outline into the post; a **writing kernel** writes the draft from the brief it's
+given and does no retrieval of its own. Both take minutes, so both are start-then-poll:
+
+```bash
+# 1. Research the topic and write an outline into the post
+letterstory research start --article <uuid> --topic "payroll solutions" \
+  --url https://example.com/a --must-include "Pricing" --depth fleshed_out
+letterstory research status --article <uuid>       # phases, sources, outline
+letterstory research cancel --article <uuid>
+
+# …with --gate, the run pauses for you to pick the angle:
+letterstory research start --article <uuid> --gate
+letterstory research status --article <uuid>       # status: awaiting_direction + direction_options
+letterstory research direction --article <uuid> --choice 1
+letterstory research direction --article <uuid> --custom "Lead with the hidden costs"
+letterstory research direction --article <uuid> --skip     # let the agent decide
+
+# 2. Have a kernel write the draft
+letterstory kernel list
+letterstory kernel run --article <uuid> --kernel <uuid> [--brief "…" | --brief-file brief.md]
+letterstory kernel status <kernel-job-id>
+```
+
+`phantom-job create --topic "…" --collection <uuid>` runs topic → draft → publish → rebuild
+end to end, with `phantom-job status <job-id>` to follow it.
+
+## Cover images
+
+Which image model draws a post's cover is a CLI decision, not a UI-only one. `variants`
+fans one headline out across up to four models and hands back a preview per model;
+`select` commits the one you want:
+
+```bash
+letterstory covers models                          # image models connected to this org
+letterstory covers variants --article <uuid> --model bloom --model openai
+letterstory covers select --article <uuid> --url <variant-url> --provider bloom
+
+# …or skip the comparison and let the server pick, using the collection's cover template:
+letterstory covers generate <article-id> [--regenerate] [--stock-only]
+```
+
+`--ref-url <url>` (repeatable) conditions the look on existing images — pair it with
+`extract_blog_reference_images` to match a site you're mirroring. Each variant costs one
+image generation, which is why the fan-out is capped at four models.
+
 ## Insights
 
 Search Console performance, network-wide, per post, or top posts:

package/lib/cli.mjs

@@ -20,17 +20,20 @@ import {
 	cmdPosts,
 	cmdPublished,
 	cmdCollections,
+	cmdAuthors,
 	cmdFlows,
 	cmdConnectors,
 	cmdStrategy,
 	cmdOnboarding,
 	cmdInsights,
+	cmdResearch,
+	cmdCovers,
 	cmdKernel,
 	cmdPhantomJob,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.3.0";
+export const VERSION = "0.4.1";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -48,6 +51,13 @@ const BOOLEAN_FLAGS = new Set([
 	"rebuild",
 	"print-key",
 	"stdin",
+	// `covers generate <id> --regenerate` and `research start --gate --article <id>`
+	// both put a value-less flag next to a value: without these entries the parser
+	// hands the following token to the flag and the real argument disappears.
+	"regenerate",
+	"stock-only",
+	"gate",
+	"skip",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -150,10 +160,20 @@ Content:
 Collections:
   collections list                                   List your collections
   collections new --name <n> [--description <text>]
-  collections update <id> [--name] [--description] [--cadence-target <n>] [--cadence-period week|month]
+  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>
 
+Authors (the per-collection author bank — recurring bylines):
+  authors list <collection-id>                        List the bank + byline distribution
+  authors generate <collection-id> [--count <n>]      Generate a believable masthead
+  authors add <collection-id> --name <n> [--bio <t>] [--role <t>] [--expertise a,b] [--started-at YYYY-MM-DD]
+  authors edit <collection-id> <author-id> [--name] [--bio] [--role] [--expertise a,b] [--started-at] [--active true|false]
+  authors retire <collection-id> <author-id>          Stop assigning new posts to them
+  authors delete <collection-id> <author-id> --yes
+  authors assign <collection-id> (--all | --articles id,id) [--author <id>] [--no-rebuild]
+                                                      Batch-swap bylines (auto-distribute, or --author to pin one)
+
 Flows:
   flows list                                          List available editorial flows
   flows run <flow-id> <article-id>                    Start a flow run
@@ -177,7 +197,25 @@ Strategy & onboarding:
   onboarding status                                    Show the onboarding checklist
   onboarding step [--current <step>] [--complete <step>] [--skip <step>] [--status <status>]
 
-Writing kernels:
+Research agent (deep research -> outline written into the post):
+  research start --article <uuid> [--topic <text>] [--url <url> …] [--must-include <text> …]
+                 [--depth barebones|fleshed_out] [--gate]
+                                                        Start a run; takes minutes
+  research status --article <uuid>                      Phases, sources, outline
+  research direction --article <uuid> (--choice <n> | --custom <text> | --skip)
+                                                        Answer the --gate pause
+  research cancel --article <uuid>                      Cancel 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> …]
+                                                        One preview per model (max 4)
+  covers select --article <uuid> --url <url> --provider <p> [--model <id>]
+                                                        Commit a previewed variant
+  covers generate <article-id> [--regenerate] [--stock-only]
+                                                        Single-shot mint, default provider
+
+Writing kernels (kernels write the draft; they do not research — run research first):
   kernel list                                          List available writing kernels
   kernel run --article <uuid> --kernel <uuid> [--brief <text>|--brief-file <path>]
                                                         Submit a run; takes 15-20 min
@@ -238,11 +276,14 @@ const CLIENT_COMMANDS = {
 	posts: cmdPosts,
 	published: cmdPublished,
 	collections: cmdCollections,
+	authors: cmdAuthors,
 	flows: cmdFlows,
 	connectors: cmdConnectors,
 	strategy: cmdStrategy,
 	onboarding: cmdOnboarding,
 	insights: cmdInsights,
+	research: cmdResearch,
+	covers: cmdCovers,
 	kernel: cmdKernel,
 	"phantom-job": cmdPhantomJob,
 };

package/lib/commands/authors.mjs

@@ -0,0 +1,165 @@
+// `authors` — manage a collection's author bank: the recurring bylines its posts
+// publish under, instead of a fresh throwaway name per article. The editable-at-
+// scale escape hatch behind the in-app Authors panel.
+
+import { CliError } from "../client.mjs";
+import {
+	flagStr,
+	flagNum,
+	flagBool,
+	flagList,
+	requireFlag,
+	requirePositional,
+	printResult,
+	compact,
+	ok,
+} from "./shared.mjs";
+
+export async function cmdAuthors(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return authorsList(rest);
+		case "generate":
+			return authorsGenerate(rest);
+		case "add":
+		case "create":
+			return authorsAdd(rest);
+		case "edit":
+		case "update":
+			return authorsEdit(rest);
+		case "retire":
+			return authorsSetActive(rest, false);
+		case "activate":
+			return authorsSetActive(rest, true);
+		case "delete":
+		case "rm":
+			return authorsDelete(rest);
+		case "assign":
+		case "swap":
+			return authorsAssign(rest);
+		default:
+			throw new CliError(
+				`Unknown authors subcommand: ${sub ?? "(none)"}. Try: list, generate, add, edit, retire, activate, delete, assign`
+			);
+	}
+}
+
+/** Positional 0 is the collection id for every subcommand except delete/edit (which take an author id too). */
+function collectionId(ctx) {
+	return requirePositional(ctx.positionals, 0, "collection-id");
+}
+
+async function authorsList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_collection_authors", { collection_id: collectionId(ctx) });
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function authorsGenerate(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({ collection_id: collectionId(ctx), count: flagNum(flags.count) });
+	const result = await client.callTool("generate_collection_authors", args);
+	ok(ctx, "Generated authors.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function authorsAdd(ctx) {
+	const { client, flags, io } = ctx;
+	const cid = collectionId(ctx);
+	const name = requireFlag(flags, "name");
+	const args = compact({
+		collection_id: cid,
+		name,
+		bio: flagStr(flags.bio),
+		role: flagStr(flags.role),
+		expertise: flagList(flags.expertise),
+		started_at: flagStr(flags["started-at"]),
+	});
+	const result = await client.callTool("upsert_collection_author", args);
+	ok(ctx, `Added author "${name}".`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function authorsEdit(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const cid = requirePositional(positionals, 0, "collection-id");
+	const authorId = requirePositional(positionals, 1, "author-id");
+	const patch = compact({
+		collection_id: cid,
+		author_id: authorId,
+		name: flagStr(flags.name),
+		bio: flagStr(flags.bio),
+		role: flagStr(flags.role),
+		expertise: flagList(flags.expertise),
+		started_at: flagStr(flags["started-at"]),
+		active: flagBool(flags.active),
+	});
+	if (Object.keys(patch).length <= 2) {
+		throw new CliError(
+			"Nothing to edit — pass at least one of --name/--bio/--role/--expertise/--started-at/--active."
+		);
+	}
+	const result = await client.callTool("upsert_collection_author", patch);
+	ok(ctx, "Updated author.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function authorsSetActive(ctx, active) {
+	const { client, positionals, flags, io } = ctx;
+	const cid = requirePositional(positionals, 0, "collection-id");
+	const authorId = requirePositional(positionals, 1, "author-id");
+	const result = await client.callTool("upsert_collection_author", {
+		collection_id: cid,
+		author_id: authorId,
+		active,
+	});
+	ok(ctx, active ? "Author activated." : "Author retired.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function authorsDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const cid = requirePositional(positionals, 0, "collection-id");
+	const authorId = requirePositional(positionals, 1, "author-id");
+	if (!flags.yes) {
+		io.error(`Re-run with --yes to confirm: ${ctx.bin} authors delete ${cid} ${authorId} --yes`);
+		return 1;
+	}
+	const result = await client.callTool("delete_collection_author", { collection_id: cid, author_id: authorId });
+	ok(ctx, "Author deleted.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function authorsAssign(ctx) {
+	const { client, flags, io } = ctx;
+	const cid = collectionId(ctx);
+	// --author <id> pins one author; omit it to auto-distribute by topic.
+	// --all reassigns every post; otherwise pass --articles <id,id,...>.
+	const authorId = flagStr(flags.author);
+	const articleIds = flagList(flags.articles);
+	const all = flagBool(flags.all) === true;
+	if (!all && (!articleIds || articleIds.length === 0)) {
+		throw new CliError("Provide --all to reassign every post, or --articles <id,id,...> for specific posts.");
+	}
+	const args = compact({
+		collection_id: cid,
+		mode: authorId ? "set" : "auto",
+		author_id: authorId,
+		article_ids: all ? undefined : articleIds,
+		all: all ? true : undefined,
+		rebuild: flags["no-rebuild"] ? false : undefined,
+	});
+	const result = await client.callTool("assign_collection_authors", args);
+	ok(ctx, authorId ? "Reassigned bylines to the chosen author." : "Auto-distributed bylines across active authors.");
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/collections.mjs

@@ -48,6 +48,7 @@ async function collectionsNew(ctx) {
 async function collectionsUpdate(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	const id = requirePositional(positionals, 0, "collection-id");
+	const coverCanvasTypeId = flagStr(flags["cover-canvas-type-id"]);
 	const patch = compact({
 		collection_id: id,
 		name: flagStr(flags.name),
@@ -55,9 +56,16 @@ async function collectionsUpdate(ctx) {
 		cadence_target: flagNum(flags["cadence-target"]),
 		cadence_period: flagStr(flags["cadence-period"]),
 	});
+	if (coverCanvasTypeId !== undefined) {
+		// compact() drops undefined, not null — set it after so "none"/"off" can clear
+		// the field instead of being dropped. Same convention as `webhook set --url none`.
+		patch.cover_canvas_type_id = ["none", "off", ""].includes(coverCanvasTypeId.toLowerCase())
+			? null
+			: coverCanvasTypeId;
+	}
 	if (Object.keys(patch).length <= 1) {
 		throw new CliError(
-			"Nothing to update — pass at least one of --name/--description/--cadence-target/--cadence-period."
+			"Nothing to update — pass at least one of --name/--description/--cadence-target/--cadence-period/--cover-canvas-type-id."
 		);
 	}
 	const result = await client.callTool("update_collection", patch);

package/lib/commands/covers.mjs

@@ -0,0 +1,89 @@
+// `covers` — a post's cover image, including WHICH image model draws it. `models`
+// lists what's connected, `variants` fans a headline out across models and returns a
+// preview per model, `select` commits the one you want, and `generate` is the
+// single-shot headless mint (collection's template + the server's default provider).
+// Each variant costs one image generation, so the fan-out is capped at 4 models.
+
+import { CliError } from "../client.mjs";
+import { flagStr, flagBool, flagList, requireFlag, requirePositional, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdCovers(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "models":
+			return coverModels(rest);
+		case "variants":
+		case "compare":
+			return coverVariants(rest);
+		case "select":
+		case "pick":
+			return coverSelect(rest);
+		case "generate":
+			return coverGenerate(rest);
+		default:
+			throw new CliError(
+				`Unknown covers subcommand: ${sub ?? "(none)"}. Try: models, variants, select, generate`
+			);
+	}
+}
+
+async function coverModels(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_image_models", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function coverVariants(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const modelIds = flagList(flags.model);
+	const refs = flagList(flags["ref-url"]);
+	const args = compact({
+		article_id: article,
+		model_ids: modelIds.length ? modelIds : undefined,
+		reference_image_urls: refs.length ? refs : undefined,
+	});
+	const result = await client.callTool("generate_cover_variants", args);
+	const first = (result?.variants ?? []).find((v) => v.url);
+	ok(
+		ctx,
+		first
+			? `Generated ${result.variants.length} variant(s). Commit one with: covers select --article ${article} --url <url> --provider <provider>`
+			: "No variant produced an image — see the per-model errors below."
+	);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function coverSelect(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const args = compact({
+		article_id: article,
+		image_url: requireFlag(flags, "url"),
+		provider: requireFlag(flags, "provider"),
+		model: flagStr(flags.model),
+	});
+	const result = await client.callTool("select_cover_variant", args);
+	ok(ctx, "Cover set on the post.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function coverGenerate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	// `covers generate <article-id>` reads naturally, but --article keeps it
+	// consistent with every other post-scoped command; accept both.
+	const article = flagStr(flags.article) ?? requirePositional(positionals, 0, "article-id");
+	const args = compact({
+		article_id: article,
+		regenerate: flagBool(flags.regenerate) ? true : undefined,
+		stock_only: flagBool(flags["stock-only"]) ? true : undefined,
+	});
+	const result = await client.callTool("generate_article_cover", args);
+	ok(ctx, result?.generated ? "Cover generated and attached." : `No cover generated: ${result?.reason ?? "unknown"}`);
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/research.mjs

@@ -0,0 +1,89 @@
+// `research` — the deep-research agent: read supplied URLs, search the live web, and
+// write a sourced outline into a post. Same shape as `kernel`: a run takes minutes, so
+// `start` returns as soon as the run is queued and `status` checks on demand. Writing
+// kernels do NOT research — `research start` then `kernel run` is the full pipeline.
+
+import { CliError } from "../client.mjs";
+import { flagStr, flagNum, flagBool, flagList, requireFlag, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdResearch(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "start":
+		case "run":
+			return researchStart(rest);
+		case "status":
+			return researchStatus(rest);
+		case "direction":
+			return researchDirection(rest);
+		case "cancel":
+			return researchCancel(rest);
+		default:
+			throw new CliError(
+				`Unknown research subcommand: ${sub ?? "(none)"}. Try: start, status, direction, cancel`
+			);
+	}
+}
+
+async function researchStart(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const depth = flagStr(flags.depth);
+	if (depth !== undefined && depth !== "barebones" && depth !== "fleshed_out") {
+		throw new CliError(`--depth must be barebones or fleshed_out, got "${depth}"`);
+	}
+	const sourceUrls = flagList(flags.url);
+	const mustInclude = flagList(flags["must-include"]);
+	const args = compact({
+		article_id: article,
+		topic: flagStr(flags.topic),
+		source_urls: sourceUrls.length ? sourceUrls : undefined,
+		must_include: mustInclude.length ? mustInclude : undefined,
+		depth,
+		direction_gate: flagBool(flags.gate) ? true : undefined,
+	});
+	const result = await client.callTool("start_research", args);
+	ok(ctx, `Research started. Check progress with: research status --article ${article}`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function researchStatus(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const result = await client.callTool("get_research_status", { article_id: article });
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function researchDirection(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const choice = flagNum(flags.choice);
+	const custom = flagStr(flags.custom);
+	const skip = flagBool(flags.skip);
+	const given = [choice !== undefined, custom !== undefined, skip].filter(Boolean).length;
+	if (given !== 1) {
+		throw new CliError("Provide exactly one of --choice <n>, --custom <text>, --skip");
+	}
+	const args = compact({
+		article_id: article,
+		choice,
+		custom,
+		skip: skip ? true : undefined,
+	});
+	const result = await client.callTool("submit_research_direction", args);
+	ok(ctx, "Direction recorded; the run resumed into synthesis.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function researchCancel(ctx) {
+	const { client, flags, io } = ctx;
+	const article = requireFlag(flags, "article");
+	const result = await client.callTool("cancel_research", { article_id: article });
+	ok(ctx, result?.cancelled ? "Research run cancelled." : "No research run was in flight.");
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands.mjs

@@ -10,9 +10,12 @@ export * from "./commands/deploy.mjs";
 export * from "./commands/mcp.mjs";
 export * from "./commands/posts.mjs";
 export * from "./commands/collections.mjs";
+export * from "./commands/authors.mjs";
 export * from "./commands/flows.mjs";
 export * from "./commands/connectors.mjs";
 export * from "./commands/strategy.mjs";
 export * from "./commands/insights.mjs";
+export * from "./commands/covers.mjs";
+export * from "./commands/research.mjs";
 export * from "./commands/kernel.mjs";
 export * from "./commands/phantom-job.mjs";

package/package.json

@@ -1,18 +1,18 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.3.0",
+	"version": "0.4.1",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",
 	"author": "Letterstory",
-	"homepage": "https://github.com/letterstory/Letterbrace/tree/main/cli#readme",
+	"homepage": "https://github.com/letterstory/letterstory/tree/main/cli#readme",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/letterstory/Letterbrace.git",
+		"url": "git+https://github.com/letterstory/letterstory.git",
 		"directory": "cli"
 	},
 	"bugs": {
-		"url": "https://github.com/letterstory/Letterbrace/issues"
+		"url": "https://github.com/letterstory/letterstory/issues"
 	},
 	"keywords": [
 		"letterstory",