@letterstory/cli 0.5.0 → 0.6.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
@@ -273,19 +302,28 @@ letterstory seers apply --file seers.json --dry-run   # print the create/update/
 letterstory seers apply --file seers.json             # apply it
 ```
 
-Connections, and one honest gap:
+Connections — both providers connect headlessly (no browser required):
 
 ```bash
 letterstory seers connections                      # GitHub + Notion status
 letterstory seers connect github --token <pat>     # org-wide token; unlocks private repos
-letterstory seers connect notion                   # prints instructions — see below
+letterstory seers connect notion                   # no token: prints how to mint one + which pages to share
+letterstory seers connect notion --token ntn_xxx   # store a Notion internal-integration secret
 ```
 
-> **Known gaps.** Notion connects via browser OAuth in the app only — the CLI/API can
-> read connection status but cannot complete the OAuth flow. `seers run` executes
-> synchronously server-side (up to ~5 minutes for web-scan providers); there is no
-> start-then-poll variant yet. And `create`'s config takes raw JSON — `seers providers`
-> is the schema reference the server validates against.
+**Connecting Notion.** Notion uses an _internal integration_ (the direct analogue of a
+GitHub PAT), so it's fully scriptable:
+
+1. Create one at [notion.so/my-integrations](https://www.notion.so/my-integrations) → **New integration → Internal**, with the **Read content** capability.
+2. Copy the **Internal Integration Secret** (`ntn_…` / `secret_…`).
+3. In Notion, open each page/database the seer should watch → **••• → Connections →** add your integration. **A Notion integration only sees pages explicitly shared with it** — this step is required, or the seer connects but detects nothing.
+4. `letterstory seers connect notion --token ntn_…`
+
+The app's browser OAuth flow (Seers tab → Connect Notion) is an equivalent alternative, not a requirement.
+
+> **Remaining gap.** `seers run` executes synchronously server-side (up to ~5 minutes for
+> web-scan providers); there is no start-then-poll variant yet. And `create`'s config takes
+> raw JSON — `seers providers` is the schema reference the server validates against.
 
 Content templates (the compose structures seers bind via `config.template_key`):
 

package/lib/cli.mjs

@@ -25,6 +25,7 @@ import {
 	cmdConnectors,
 	cmdStrategy,
 	cmdOnboarding,
+	cmdSeries,
 	cmdInsights,
 	cmdResearch,
 	cmdCovers,
@@ -35,7 +36,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.5.0";
+export const VERSION = "0.6.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 +199,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> …]
@@ -245,7 +254,8 @@ Seers (event-driven signals -> drafts):
   seers release <article-id> | seers discard <article-id>
   seers connections                                    GitHub/Notion connection status
   seers connect github --token <pat>                   Store an org-wide GitHub token
-  seers connect notion                                 (browser-only OAuth — prints instructions)
+  seers connect notion --token <secret>                Store a Notion internal-integration token
+  seers connect notion                                 (no token: prints how to mint one + share pages)
   seers export [--file <path>]                         Dump the org's seers as a manifest
   seers apply --file <path> [--dry-run]                Idempotent, name-keyed upsert from a manifest
                                                        (never deletes; --dry-run prints the plan)
@@ -312,6 +322,7 @@ const CLIENT_COMMANDS = {
 	connectors: cmdConnectors,
 	strategy: cmdStrategy,
 	onboarding: cmdOnboarding,
+	series: cmdSeries,
 	insights: cmdInsights,
 	research: cmdResearch,
 	covers: cmdCovers,

package/lib/commands/seers.mjs

@@ -4,11 +4,11 @@
 // `seers export` (dump the org's seers as a manifest) and `seers apply` (idempotent,
 // name-keyed diff-then-upsert from a manifest, with --dry-run).
 //
-// Known surface gaps, stated here because this is where operators hit them:
-//   - Notion connects via browser OAuth in the app only. `seers connect notion`
-//     prints instructions; there is no headless flow.
-//   - `seers run` executes synchronously server-side (news/regulation web scans can
-//     take minutes) and spends model budget — it is usage-gated per org.
+// Connections are both headless: `seers connect github --token` (a PAT) and
+// `seers connect notion --token` (a Notion internal-integration secret; run
+// `seers connect notion` with no token for how to mint one and which pages to share).
+// One thing to know: `seers run` executes synchronously server-side (news/regulation
+// web scans can take minutes) and spends model budget — it is usage-gated per org.
 
 import { readFileSync, writeFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
@@ -292,7 +292,7 @@ async function seersConnections(ctx) {
 			: `GitHub: not connected${r.github.configured ? " — connect with `seers connect github --token <pat>`" : " (token storage not configured on this deployment)"}`;
 		const notion = r.notion.connected
 			? `Notion: connected to ${r.notion.workspace_name} (${r.notion.connected_at})`
-			: "Notion: not connected — connect via browser in the app (Seers tab → Connect Notion); there is no headless flow";
+			: `Notion: not connected${r.notion.configured ? " — connect with `seers connect notion --token <secret>` (run `seers connect notion` for how to get one)" : " (token storage not configured on this deployment)"}`;
 		return `${gh}\n${notion}`;
 	});
 	return 0;
@@ -310,11 +310,29 @@ async function seersConnect(ctx) {
 		return 0;
 	}
 	if (which === "notion") {
-		// Deliberate gap: Notion's OAuth flow needs a browser session; the integrations
-		// surface can read status but can't complete the dance.
-		rest.io.log("Notion connects via browser OAuth and can't be completed from the CLI.");
-		rest.io.log(`Open ${rest.config.url.replace(/\/$/, "")}/seers and use "Connect Notion", then verify with:`);
-		rest.io.log(`  ${rest.bin} seers connections`);
+		const token = flagStr(rest.flags.token);
+		if (!token) {
+			// No token yet — print how to mint one and which pages to share. Notion
+			// internal integrations only see pages explicitly shared with them, so the
+			// share step is load-bearing, not optional.
+			rest.io.log("Connect Notion with an internal-integration secret (headless — no browser needed):");
+			rest.io.log("");
+			rest.io.log("  1. Go to https://www.notion.so/my-integrations → New integration → Internal.");
+			rest.io.log("  2. Give it the 'Read content' capability, then copy the Internal Integration Secret");
+			rest.io.log("     (starts with ntn_ or secret_).");
+			rest.io.log("  3. In Notion, open each page/database the seer should watch → ••• → Connections →");
+			rest.io.log("     add your integration. (An integration only sees pages shared with it.)");
+			rest.io.log(`  4. Run:  ${rest.bin} seers connect notion --token ntn_your_secret`);
+			rest.io.log("");
+			rest.io.log(
+				"The app's browser OAuth flow (Seers tab → Connect Notion) is an alternative, not a requirement."
+			);
+			return 0;
+		}
+		const result = await rest.client.callTool("set_notion_connection", { access_token: token });
+		ok(rest, `Notion connected${result.workspace_name ? ` to ${result.workspace_name}` : ""}.`);
+		ok(rest, "Reminder: the integration only watches pages you've shared with it in Notion.");
+		printResult(rest.io, rest.flags, result);
 		return 0;
 	}
 	throw new CliError(`Unknown connect target: ${which ?? "(none)"}. Try: github, notion`);

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/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,6 +14,7 @@ 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";

package/package.json

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