@letterstory/cli 0.5.1 → 0.7.0

package/README.md

@@ -213,6 +213,35 @@ 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",
+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>
+letterstory series backfill <series-id> --collection <uuid>
+```
+
 ## Research and writing kernels
 
 Two different steps, in this order. The **research agent** reads the live web and writes a

package/lib/cli.mjs

@@ -25,6 +25,7 @@ import {
 	cmdConnectors,
 	cmdStrategy,
 	cmdOnboarding,
+	cmdSeries,
 	cmdInsights,
 	cmdResearch,
 	cmdCovers,
@@ -32,10 +33,11 @@ import {
 	cmdPhantomJob,
 	cmdSeers,
 	cmdTemplates,
+	cmdShredder,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.5.1";
+export const VERSION = "0.7.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.
@@ -198,6 +200,14 @@ 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
 
 Research agent (deep research -> outline written into the post):
   research start --article <uuid> [--topic <text>] [--url <url> …] [--must-include <text> …]
@@ -258,6 +268,14 @@ Content templates (compose structures seers bind via config.template_key):
   templates update <template-id> [--name] [--angle] [--sections '<json>'|--sections-file <path>]
   templates delete <template-id> --yes
 
+Shredder (diversify content produced outside Letterstory; structure preserved):
+  shredder list                                        Your shredder endpoints + run counts
+  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>]
+                                                       Shred prose through an endpoint (logs telemetry)
+  shredder runs [--endpoint <id>] [--limit <n>]        Recent shred calls (telemetry), newest first
+
 Insights:
   insights site [--period 14d|30d|90d] [--collection <uuid>]
   insights post <article-id> [--period 14d|30d|90d]
@@ -313,6 +331,7 @@ const CLIENT_COMMANDS = {
 	connectors: cmdConnectors,
 	strategy: cmdStrategy,
 	onboarding: cmdOnboarding,
+	series: cmdSeries,
 	insights: cmdInsights,
 	research: cmdResearch,
 	covers: cmdCovers,
@@ -320,6 +339,7 @@ const CLIENT_COMMANDS = {
 	"phantom-job": cmdPhantomJob,
 	seers: cmdSeers,
 	templates: cmdTemplates,
+	shredder: cmdShredder,
 };
 
 // LETTERSTORY_POLL_INTERVAL_MS / LETTERSTORY_MAX_POLLS let an operator (or an

package/lib/commands/series.mjs

@@ -0,0 +1,101 @@
+// `series` — content series management (the coverage-driven strategy entry
+// point beside topic clusters, hierarchy revamp D/G). A series is a coverage
+// obligation: "content that looks like this", one post per declared item; the
+// planner queue writes the gaps and backfill reconstructs what existing posts
+// already fulfill.
+
+import { CliError } from "../client.mjs";
+import { compact, flagStr, ok, printResult, requireFlag, requirePositional } from "./shared.mjs";
+
+export async function cmdSeries(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+			return seriesList(rest);
+		case "create":
+			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`);
+	}
+}
+
+function formatSeriesList(result) {
+	const list = result?.series ?? [];
+	if (list.length === 0) return "No series yet. Create one, or run `series propose` to detect them.";
+	return list
+		.map((s) => {
+			const state = s.coverage_state ?? {};
+			const covered = state.covered?.length ?? 0;
+			const declared = s.coverage?.length ?? 0;
+			const missing = state.missing?.length ? ` — still to cover: ${state.missing.join(", ")}` : "";
+			return `${s.id}  ${s.name} [${s.status}] ${covered}/${declared || "∞"} covered${missing}`;
+		})
+		.join("\n");
+}
+
+async function seriesList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_series", {});
+	printResult(io, flags, result, formatSeriesList);
+	return 0;
+}
+
+async function seriesCreate(ctx) {
+	const { client, flags, io } = ctx;
+	const coverage = flagStr(flags.coverage);
+	const args = compact({
+		name: requireFlag(flags, "name"),
+		description: requireFlag(flags, "description"),
+		collection_id: flagStr(flags.collection),
+		template_key: flagStr(flags.template),
+		coverage: coverage
+			? coverage
+					.split(",")
+					.map((c) => c.trim())
+					.filter(Boolean)
+			: undefined,
+	});
+	const result = await client.callTool("create_series", args);
+	ok(ctx, "Series created — the queue starts covering its items.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function seriesBackfill(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({
+		series_id: requirePositional(ctx.positionals, 0, "series-id"),
+		collection_id: flagStr(flags.collection),
+	});
+	const result = await client.callTool("backfill_series", args);
+	ok(ctx, `Reconstructed ${result?.matched ?? 0} existing post(s) into the series.`);
+	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/shredder.mjs

@@ -0,0 +1,99 @@
+// `shredder` — create shredder endpoints and run content produced OUTSIDE Letterstory
+// through the cross-provider shredder. A shred rewrites each sentence across multiple
+// LLM providers to diversify, leaving structure (headings, lists, tables) untouched, and
+// logs every call to telemetry.
+
+import { CliError } from "../client.mjs";
+import {
+	flagStr,
+	flagNum,
+	requireFlag,
+	requirePositional,
+	readBodyInput,
+	printResult,
+	compact,
+	ok,
+} from "./shared.mjs";
+
+export async function cmdShredder(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return shredderList(rest);
+		case "new":
+		case "create":
+			return shredderCreate(rest);
+		case "delete":
+		case "rm":
+			return shredderDelete(rest);
+		case "run":
+		case "shred":
+			return shredderRun(rest);
+		case "runs":
+		case "telemetry":
+			return shredderRuns(rest);
+		default:
+			throw new CliError(`Unknown shredder subcommand: ${sub ?? "(none)"}. Try: list, create, delete, run, runs`);
+	}
+}
+
+async function shredderList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_shredder_endpoints", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function shredderCreate(ctx) {
+	const { client, flags, io } = ctx;
+	const name = requireFlag(flags, "name");
+	const result = await client.callTool("create_shredder_endpoint", { name });
+	ok(ctx, `Created shredder endpoint "${name}".`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function shredderDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "endpoint-id");
+	if (!flags.yes) {
+		io.error(`Re-run with --yes to confirm: ${ctx.bin} shredder delete ${id} --yes`);
+		return 1;
+	}
+	const result = await client.callTool("delete_shredder_endpoint", { endpoint_id: id });
+	ok(ctx, "Shredder endpoint deleted.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function shredderRun(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const id = requirePositional(positionals, 0, "endpoint-id");
+	const text = readBodyInput(flags);
+	if (text === undefined) {
+		throw new CliError("Provide the prose to shred with --body <text>, --file <path>, or --file - (stdin).");
+	}
+	const args = compact({
+		endpoint_id: id,
+		text,
+		coverage: flagNum(flags.coverage),
+		attempts_per_unit: flagNum(flags.attempts),
+	});
+	const result = await client.callTool("run_shred", args);
+	ok(ctx, "Shred complete.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function shredderRuns(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({
+		endpoint_id: flagStr(flags.endpoint),
+		limit: flagNum(flags.limit),
+	});
+	const result = await client.callTool("list_shred_runs", args);
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/strategy.mjs

@@ -220,11 +220,120 @@ 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`);
+			throw new CliError(`Unknown onboarding subcommand: ${sub ?? "(none)"}. Try: status, step, magic`);
 	}
 }
 
+// --- 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

@@ -14,9 +14,11 @@ export * from "./commands/authors.mjs";
 export * from "./commands/flows.mjs";
 export * from "./commands/connectors.mjs";
 export * from "./commands/strategy.mjs";
+export * from "./commands/series.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";
 export * from "./commands/seers.mjs";
+export * from "./commands/shredder.mjs";

package/package.json

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