@letterstory/cli 0.4.1 → 0.5.1

package/README.md

@@ -11,9 +11,15 @@ The CLI is plain ESM with **zero dependencies** and needs no build step (Node
 ```bash
 npm install -g @letterstory/cli   # puts `letterstory` (and `phantom`) on your PATH
 # …or run it without installing:
-npx @letterstory/cli --help
+npx -p @letterstory/cli letterstory --help
 ```
 
+The `-p` is not optional. This package ships two commands, `letterstory` and `phantom`,
+and npx only infers one for you when a package has a single command or one named after
+the package — neither is true here, so a bare `npx @letterstory/cli` exits with
+`could not determine executable to run`. Name the command you want (`letterstory` or
+`phantom`) and pass the package with `-p`.
+
 Contributing to the CLI itself? Run it straight from a checkout instead:
 
 ```bash
@@ -236,6 +242,70 @@ 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.
 
+## Seers — event-driven signals
+
+A **seer** watches an external source (a GitHub repo, a Notion workspace, a spec URL, a
+news or regulation query) and turns what it detects into headline suggestions — or, in
+`auto` mode, straight into drafts. Needs `seer:read` / `seer:write` capabilities
+(`template:read` / `template:write` for the templates group).
+
+```bash
+letterstory seers providers                        # the self-describing config catalog — start here
+letterstory seers list
+letterstory seers create --name "Ship notes" --collection <uuid> --provider github_pr \
+  --config '{"owner":"letterstory","repo":"letterbrace"}'
+letterstory seers update <seer-id> --mode auto --interval 60
+letterstory seers run <seer-id>                    # poll + produce now (minutes; spends AI budget)
+letterstory seers events <seer-id>                 # detected signals, dedup aliases, relevance verdicts
+letterstory seers dismiss <seer-id> <event-id>
+letterstory seers headlines [--collection <uuid>]  # the seer-sourced suggestion feed
+letterstory seers held                             # drafts parked pending human review
+letterstory seers release <article-id>             # …or: seers discard <article-id>
+```
+
+Reproducible setup — the onboarding path. `export` writes the org's seers as a
+manifest; `apply` is an idempotent, **name-keyed** upsert from one (it never deletes;
+seers in the org but missing from the manifest are listed as extras and left alone):
+
+```bash
+letterstory seers export --file seers.json
+letterstory seers apply --file seers.json --dry-run   # print the create/update/ok plan
+letterstory seers apply --file seers.json             # apply it
+```
+
+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                   # no token: prints how to mint one + which pages to share
+letterstory seers connect notion --token ntn_xxx   # store a Notion internal-integration secret
+```
+
+**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`):
+
+```bash
+letterstory templates list                         # custom + read-only built-ins
+letterstory templates create --name "Release notes" --angle "What shipped and why" \
+  --sections-file sections.json
+letterstory templates update <template-id> --angle "…"   # unset fields keep their values
+letterstory templates delete <template-id> --yes   # bound seers fall back to defaults
+```
+
 ## Cover images
 
 Which image model draws a post's cover is a CLI decision, not a UI-only one. `variants`

package/lib/cli.mjs

@@ -30,10 +30,12 @@ import {
 	cmdCovers,
 	cmdKernel,
 	cmdPhantomJob,
+	cmdSeers,
+	cmdTemplates,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.4.1";
+export const VERSION = "0.5.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.
@@ -226,6 +228,36 @@ Phantom orchestrator:
                                                         Topic -> draft -> publish -> rebuild
   phantom-job status <job-id>                          Check a job's stage
 
+Seers (event-driven signals -> drafts):
+  seers list                                           List seers with recent activity
+  seers get <seer-id>                                  One seer's full config + poll state
+  seers providers                                      Provider catalog: config fields + behavior keys
+  seers create --name <n> --collection <uuid> --provider <p>
+               [--mode suggest|auto] [--interval <min>] [--config '<json>'|--config-file <path>]
+  seers update <seer-id> [--name] [--collection] [--mode] [--enabled true|false]
+               [--interval <min>] [--config '<json>'|--config-file <path>]
+  seers delete <seer-id> --yes
+  seers run <seer-id>                                  Poll + produce now (can take minutes; spends AI budget)
+  seers events <seer-id> [--limit <n>] [--offset <n>]  Detected signals w/ dedup + relevance
+  seers dismiss <seer-id> <event-id>                   Dismiss a signal (feeds the relevance judge)
+  seers headlines [--collection <uuid>]                Seer-sourced suggestion feed
+  seers held [--collection <uuid>]                     Drafts parked pending human review
+  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 --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)
+
+Content templates (compose structures seers bind via config.template_key):
+  templates list                                       Custom + built-in catalog
+  templates show <template-id>
+  templates create --name <n> --angle <text> (--sections '<json>'|--sections-file <path>)
+  templates update <template-id> [--name] [--angle] [--sections '<json>'|--sections-file <path>]
+  templates delete <template-id> --yes
+
 Insights:
   insights site [--period 14d|30d|90d] [--collection <uuid>]
   insights post <article-id> [--period 14d|30d|90d]
@@ -286,6 +318,8 @@ const CLIENT_COMMANDS = {
 	covers: cmdCovers,
 	kernel: cmdKernel,
 	"phantom-job": cmdPhantomJob,
+	seers: cmdSeers,
+	templates: cmdTemplates,
 };
 
 // LETTERSTORY_POLL_INTERVAL_MS / LETTERSTORY_MAX_POLLS let an operator (or an

package/lib/commands/seers.mjs

@@ -0,0 +1,691 @@
+// `seers` + `templates` — event-driven signal watchers and the content templates
+// that shape what they compose. Wraps the seer:*/template:* tools 1:1 with the
+// app's Seers tab, plus two CLI-only compositions for reproducible onboarding:
+// `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).
+//
+// 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";
+import { flagStr, flagNum, flagBool, requirePositional, printResult, compact, ok } from "./shared.mjs";
+
+export async function cmdSeers(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return seersList(rest);
+		case "get":
+		case "show":
+			return seersGet(rest);
+		case "create":
+		case "new":
+			return seersCreate(rest);
+		case "update":
+			return seersUpdate(rest);
+		case "delete":
+		case "rm":
+			return seersDelete(rest);
+		case "run":
+			return seersRun(rest);
+		case "events":
+			return seersEvents(rest);
+		case "dismiss":
+			return seersDismiss(rest);
+		case "headlines":
+			return seersHeadlines(rest);
+		case "held":
+			return seersHeld(rest);
+		case "release":
+			return seersResolveHeld(rest, "release");
+		case "discard":
+			return seersResolveHeld(rest, "discard");
+		case "providers":
+			return seersProviders(rest);
+		case "connections":
+			return seersConnections(rest);
+		case "connect":
+			return seersConnect(rest);
+		case "export":
+			return seersExport(rest);
+		case "apply":
+			return seersApply(rest);
+		default:
+			throw new CliError(
+				`Unknown seers subcommand: ${sub ?? "(none)"}. Try: list, get, create, update, delete, run, events, dismiss, headlines, held, release, discard, providers, connections, connect, export, apply`
+			);
+	}
+}
+
+// --- JSON input helpers ------------------------------------------------------------
+
+// Read a JSON object from --<name> '<json>' or --<name>-file <path>.
+function readJsonObjectFlag(flags, name) {
+	const inline = flagStr(flags[name]);
+	const file = flagStr(flags[`${name}-file`]);
+	if (inline === undefined && file === undefined) return undefined;
+	const raw = inline !== undefined ? inline : readFileOrThrow(file, `--${name}-file`);
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new CliError(`--${name} is not valid JSON: ${err.message}`);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new CliError(`--${name} must be a JSON object`);
+	}
+	return parsed;
+}
+
+function readFileOrThrow(path, label) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (err) {
+		throw new CliError(`Could not read ${label} ${path}: ${err.message}`);
+	}
+}
+
+// --- Seer CRUD ---------------------------------------------------------------------
+
+function formatSeerLine(s) {
+	const state = s.enabled === false ? "paused" : "enabled";
+	const events = s.event_count !== undefined ? ` · ${s.event_count} events, ${s.produced_count} produced` : "";
+	const coll = s.collection_name ? ` → ${s.collection_name}` : "";
+	return `${s.id}  [${s.provider}/${s.mode}, ${state}, every ${s.poll_interval_minutes}m]  ${s.name}${coll}${events}`;
+}
+
+async function seersList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_seers", {});
+	printResult(io, flags, result, (r) => {
+		const lines = (r.seers ?? []).map(formatSeerLine);
+		if (!lines.length) lines.push("No seers yet. Create one with `seers create` (see `seers providers`).");
+		if (r.positioning_status && !r.positioning_status.configured) {
+			lines.push("");
+			lines.push("Note: org positioning is not configured — relevance judging has nothing to gate on.");
+		}
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function seersGet(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const seerId = requirePositional(positionals, 0, "seer-id");
+	const result = await client.callTool("get_seer", { seer_id: seerId });
+	printResult(io, flags, result);
+	return 0;
+}
+
+function seerWriteArgsFromFlags(flags) {
+	const enabledRaw = flagStr(flags.enabled);
+	if (enabledRaw !== undefined && enabledRaw !== "true" && enabledRaw !== "false") {
+		throw new CliError('--enabled must be "true" or "false"');
+	}
+	return compact({
+		name: flagStr(flags.name),
+		collection_id: flagStr(flags.collection),
+		mode: flagStr(flags.mode),
+		poll_interval_minutes: flagNum(flags.interval),
+		enabled: enabledRaw === undefined ? undefined : enabledRaw === "true",
+		config: readJsonObjectFlag(flags, "config"),
+	});
+}
+
+async function seersCreate(ctx) {
+	const { client, flags, io } = ctx;
+	const args = seerWriteArgsFromFlags(flags);
+	if (!args.name) throw new CliError("Missing required --name");
+	if (!args.collection_id) throw new CliError("Missing required --collection <uuid>");
+	const provider = flagStr(flags.provider);
+	if (!provider) throw new CliError("Missing required --provider (run `seers providers` for the catalog)");
+	delete args.enabled; // create has no enabled field; new seers start enabled
+	const result = await client.callTool("create_seer", { ...args, provider, config: args.config ?? {} });
+	ok(ctx, "Seer created.");
+	printResult(io, flags, result, (r) => formatSeerLine(r.seer));
+	return 0;
+}
+
+async function seersUpdate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const seerId = requirePositional(positionals, 0, "seer-id");
+	const args = seerWriteArgsFromFlags(flags);
+	if (Object.keys(args).length === 0) {
+		throw new CliError("Nothing to update — pass --name/--collection/--mode/--enabled/--interval/--config");
+	}
+	const result = await client.callTool("update_seer", { seer_id: seerId, ...args });
+	ok(ctx, "Seer updated.");
+	printResult(io, flags, result, (r) => formatSeerLine(r.seer));
+	return 0;
+}
+
+async function seersDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const seerId = requirePositional(positionals, 0, "seer-id");
+	if (!flagBool(flags.yes)) throw new CliError("Deleting a seer removes its detected events. Re-run with --yes.");
+	const result = await client.callTool("delete_seer", { seer_id: seerId });
+	ok(ctx, "Seer deleted.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function seersRun(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const seerId = requirePositional(positionals, 0, "seer-id");
+	ok(ctx, "Polling now — web-scan providers can take a few minutes…");
+	const result = await client.callTool("run_seer", { seer_id: seerId });
+	printResult(
+		io,
+		flags,
+		result,
+		(r) =>
+			`Detected ${r.detected}, produced ${r.produced} (auto-drafted ${r.auto_drafted}, suggested-only ${r.suggested_only}, dismissed ${r.dismissed}).`
+	);
+	return 0;
+}
+
+// --- Events / headlines / holding pen ----------------------------------------------
+
+async function seersEvents(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const seerId = requirePositional(positionals, 0, "seer-id");
+	const args = compact({ seer_id: seerId, limit: flagNum(flags.limit), offset: flagNum(flags.offset) });
+	const result = await client.callTool("list_seer_events", args);
+	printResult(io, flags, result, (r) => {
+		const lines = (r.events ?? []).map((e) => {
+			const blocked = e.auto_production_blocked_reason ? ` [blocked: ${e.auto_production_blocked_reason}]` : "";
+			const aliases = e.aliases?.length ? ` (+${e.aliases.length} aliases)` : "";
+			return `${e.id}  [${e.status}] ${e.detected_at}  ${e.title}${aliases}${blocked}`;
+		});
+		if (!lines.length) lines.push("No events detected yet.");
+		if (r.has_more) lines.push(`… more available (--offset ${r.next_offset})`);
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function seersDismiss(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const seerId = requirePositional(positionals, 0, "seer-id");
+	const eventId = requirePositional(positionals, 1, "event-id");
+	const result = await client.callTool("dismiss_seer_event", { seer_id: seerId, event_id: eventId });
+	ok(ctx, "Event dismissed.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function seersHeadlines(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({
+		collection_id: flagStr(flags.collection),
+		limit: flagNum(flags.limit),
+		offset: flagNum(flags.offset),
+	});
+	const result = await client.callTool("list_seer_headlines", args);
+	printResult(io, flags, result, (r) => {
+		const lines = (r.headlines ?? []).map(
+			(h) => `${h.id}  [${h.status}]  ${h.title ?? h.headline ?? "(untitled)"}`
+		);
+		if (!lines.length) lines.push("No seer-sourced headlines right now.");
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function seersHeld(ctx) {
+	const { client, flags, io } = ctx;
+	const args = compact({ collection_id: flagStr(flags.collection) });
+	const result = await client.callTool("list_held_drafts", args);
+	printResult(io, flags, result, (r) => {
+		const lines = (r.drafts ?? []).map(
+			(d) => `${d.articleId}  [${d.kind}] ${d.title} — ${d.reason} (dropped ${d.dropped}, unsure ${d.unsure})`
+		);
+		if (!lines.length) lines.push("Holding pen is empty.");
+		else lines.push("", "Release with `seers release <article-id>`, or drop with `seers discard <article-id>`.");
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function seersResolveHeld(ctx, action) {
+	const { client, positionals, flags, io } = ctx;
+	const articleId = requirePositional(positionals, 0, "article-id");
+	const result = await client.callTool("resolve_held_draft", { article_id: articleId, action });
+	ok(ctx, action === "release" ? "Draft released — it can publish through the normal path." : "Draft discarded.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+// --- Providers & connections -------------------------------------------------------
+
+async function seersProviders(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_seer_providers", {});
+	printResult(io, flags, result, (r) => {
+		const blocks = (r.providers ?? []).map((p) => {
+			const fields = p.fields
+				.map((f) => `      ${f.key}${f.required ? " (required)" : ""} — ${f.help ?? f.label}`)
+				.join("\n");
+			const conn = p.requires_connection ? `    connection: ${p.requires_connection}\n` : "";
+			return `  ${p.id} — ${p.tagline}\n${conn}${fields}`;
+		});
+		const behavior = Object.entries(r.behavior_keys ?? {})
+			.map(([k, v]) => `  ${k} — ${v}`)
+			.join("\n");
+		return `Providers:\n${blocks.join("\n\n")}\n\nShared config behavior keys (all providers):\n${behavior}`;
+	});
+	return 0;
+}
+
+async function seersConnections(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("get_seer_connections", {});
+	printResult(io, flags, result, (r) => {
+		const gh = r.github.connected
+			? `GitHub: connected as ${r.github.account_login} (${r.github.connected_at})`
+			: `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${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;
+}
+
+async function seersConnect(ctx) {
+	const which = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	if (which === "github") {
+		const token = flagStr(rest.flags.token);
+		if (!token) throw new CliError("Missing required --token <github-pat> (repo read access)");
+		const result = await rest.client.callTool("set_github_connection", { access_token: token });
+		ok(rest, "GitHub connected.");
+		printResult(rest.io, rest.flags, result);
+		return 0;
+	}
+	if (which === "notion") {
+		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`);
+}
+
+// --- Export / apply (reproducible onboarding) --------------------------------------
+
+const MANIFEST_VERSION = 1;
+// The seer fields a manifest owns. Cursor/lease/poll state is deliberately NOT
+// exported — a manifest describes configuration, not runtime progress.
+function manifestEntryFromSeer(s) {
+	return {
+		name: s.name,
+		provider: s.provider,
+		mode: s.mode,
+		enabled: s.enabled !== false,
+		poll_interval_minutes: s.poll_interval_minutes,
+		collection_id: s.collection_id,
+		collection_name: s.collection_name ?? undefined,
+		config: s.config ?? {},
+	};
+}
+
+async function seersExport(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_seers", {});
+	const manifest = {
+		version: MANIFEST_VERSION,
+		seers: (result.seers ?? []).map(manifestEntryFromSeer),
+	};
+	const out = JSON.stringify(manifest, null, 2);
+	const file = flagStr(flags.file);
+	if (file) {
+		writeFileSync(file, `${out}\n`);
+		ok(ctx, `Exported ${manifest.seers.length} seers to ${file}.`);
+	} else {
+		io.log(out);
+	}
+	return 0;
+}
+
+// Key-order-independent flat-object equality — the same rule the server uses to
+// decide whether an update actually changed the config (and must reset the cursor).
+function sameFlatObject(a, b) {
+	const stable = (o) =>
+		JSON.stringify(
+			Object.keys(o ?? {})
+				.sort()
+				.map((k) => [k, o[k]])
+		);
+	return stable(a) === stable(b);
+}
+
+function loadManifest(flags) {
+	const file = flagStr(flags.file);
+	if (!file) throw new CliError("Missing required --file <manifest.json> (produce one with `seers export`)");
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileOrThrow(file, "--file"));
+	} catch (err) {
+		throw err instanceof CliError ? err : new CliError(`--file is not valid JSON: ${err.message}`);
+	}
+	if (parsed?.version !== MANIFEST_VERSION || !Array.isArray(parsed.seers)) {
+		throw new CliError(`Manifest must be { "version": ${MANIFEST_VERSION}, "seers": [...] }`);
+	}
+	for (const [i, entry] of parsed.seers.entries()) {
+		if (!entry?.name) throw new CliError(`Manifest seers[${i}] is missing "name" (names key the upsert)`);
+		if (!entry.provider) throw new CliError(`Manifest seers[${i}] ("${entry.name}") is missing "provider"`);
+	}
+	const names = parsed.seers.map((s) => s.name);
+	const dupes = names.filter((n, i) => names.indexOf(n) !== i);
+	if (dupes.length) throw new CliError(`Manifest has duplicate seer names: ${[...new Set(dupes)].join(", ")}`);
+	return parsed;
+}
+
+// Resolve each manifest entry's destination collection: an explicit collection_id
+// wins; otherwise collection_name is matched against the org's collections.
+async function resolveCollections(client, entries) {
+	const needsLookup = entries.some((e) => !e.collection_id && e.collection_name);
+	if (!needsLookup) return;
+	let collections;
+	try {
+		const result = await client.callTool("list_collections", {});
+		collections = result.collections ?? result;
+	} catch (err) {
+		throw new CliError(
+			`Manifest entries name collections by collection_name, which needs the list_collections tool (capability article:read): ${err.message}`
+		);
+	}
+	const byName = new Map((collections ?? []).map((c) => [c.name, c.id]));
+	for (const entry of entries) {
+		if (entry.collection_id || !entry.collection_name) continue;
+		const id = byName.get(entry.collection_name);
+		if (!id) throw new CliError(`Manifest seer "${entry.name}": no collection named "${entry.collection_name}"`);
+		entry.collection_id = id;
+	}
+}
+
+function planSeerApply(existingSeers, entries) {
+	const byName = new Map(existingSeers.map((s) => [s.name, s]));
+	const plan = [];
+	for (const entry of entries) {
+		if (!entry.collection_id) {
+			throw new CliError(`Manifest seer "${entry.name}" needs a collection_id or collection_name`);
+		}
+		const current = byName.get(entry.name);
+		if (!current) {
+			plan.push({ action: "create", entry });
+			continue;
+		}
+		if (current.provider !== entry.provider) {
+			throw new CliError(
+				`Manifest seer "${entry.name}" is ${entry.provider} but the existing seer is ${current.provider}. ` +
+					"A seer's provider can't change — rename one of them."
+			);
+		}
+		const changes = {};
+		if (entry.collection_id !== current.collection_id) changes.collection_id = entry.collection_id;
+		if (entry.mode !== undefined && entry.mode !== current.mode) changes.mode = entry.mode;
+		if (entry.enabled !== undefined && entry.enabled !== (current.enabled !== false))
+			changes.enabled = entry.enabled;
+		if (
+			entry.poll_interval_minutes !== undefined &&
+			entry.poll_interval_minutes !== current.poll_interval_minutes
+		) {
+			changes.poll_interval_minutes = entry.poll_interval_minutes;
+		}
+		if (entry.config !== undefined && !sameFlatObject(entry.config, current.config)) changes.config = entry.config;
+		plan.push(
+			Object.keys(changes).length
+				? { action: "update", entry, current, changes }
+				: { action: "unchanged", entry, current }
+		);
+	}
+	const manifestNames = new Set(entries.map((e) => e.name));
+	const extras = existingSeers.filter((s) => !manifestNames.has(s.name));
+	return { plan, extras };
+}
+
+function describePlan(plan, extras) {
+	const lines = [];
+	for (const step of plan) {
+		if (step.action === "create") {
+			lines.push(`  + create  ${step.entry.name}  [${step.entry.provider}/${step.entry.mode ?? "suggest"}]`);
+		} else if (step.action === "update") {
+			lines.push(`  ~ update  ${step.entry.name}  (${Object.keys(step.changes).join(", ")})`);
+		} else {
+			lines.push(`  = ok      ${step.entry.name}`);
+		}
+	}
+	if (extras.length) {
+		lines.push("");
+		lines.push("  Present in the org but not in the manifest (left untouched — apply never deletes):");
+		for (const s of extras) lines.push(`  ? extra   ${s.name}  [${s.provider}]`);
+	}
+	return lines.join("\n");
+}
+
+async function seersApply(ctx) {
+	const { client, flags, io } = ctx;
+	const manifest = loadManifest(flags);
+	await resolveCollections(client, manifest.seers);
+
+	const current = await client.callTool("list_seers", {});
+	const { plan, extras } = planSeerApply(current.seers ?? [], manifest.seers);
+
+	const creates = plan.filter((p) => p.action === "create");
+	const updates = plan.filter((p) => p.action === "update");
+
+	if (flags.json) {
+		// Machine-readable plan; on a real apply the executed flag flips below.
+		const payload = { plan, extras: extras.map((s) => ({ name: s.name, id: s.id })), executed: false };
+		if (flagBool(flags["dry-run"]) || (!creates.length && !updates.length)) {
+			io.log(JSON.stringify(payload, null, 2));
+			if (flagBool(flags["dry-run"])) return 0;
+		}
+	} else {
+		io.log(`Plan for ${manifest.seers.length} manifest seers:`);
+		io.log(describePlan(plan, extras));
+	}
+
+	if (flagBool(flags["dry-run"])) {
+		ok(ctx, "\nDry run — nothing applied.");
+		return 0;
+	}
+	if (!creates.length && !updates.length) {
+		ok(ctx, "\nEverything already matches the manifest.");
+		return 0;
+	}
+
+	const applied = [];
+	for (const step of creates) {
+		const { entry } = step;
+		const result = await client.callTool("create_seer", {
+			name: entry.name,
+			provider: entry.provider,
+			collection_id: entry.collection_id,
+			...(entry.mode !== undefined ? { mode: entry.mode } : {}),
+			...(entry.poll_interval_minutes !== undefined
+				? { poll_interval_minutes: entry.poll_interval_minutes }
+				: {}),
+			config: entry.config ?? {},
+		});
+		applied.push({ action: "created", name: entry.name, id: result.seer?.id });
+		ok(ctx, `Created ${entry.name}.`);
+		// The create tool has no enabled field; a manifest that wants it paused
+		// needs a follow-up update.
+		if (entry.enabled === false && result.seer?.id) {
+			await client.callTool("update_seer", { seer_id: result.seer.id, enabled: false });
+			ok(ctx, `  …and paused it (manifest says enabled: false).`);
+		}
+	}
+	for (const step of updates) {
+		await client.callTool("update_seer", { seer_id: step.current.id, ...step.changes });
+		applied.push({
+			action: "updated",
+			name: step.entry.name,
+			id: step.current.id,
+			changes: Object.keys(step.changes),
+		});
+		ok(ctx, `Updated ${step.entry.name} (${Object.keys(step.changes).join(", ")}).`);
+	}
+
+	if (flags.json) {
+		io.log(
+			JSON.stringify(
+				{ plan, extras: extras.map((s) => ({ name: s.name, id: s.id })), executed: true, applied },
+				null,
+				2
+			)
+		);
+	} else {
+		ok(
+			ctx,
+			`\nApplied: ${creates.length} created, ${updates.length} updated, ${plan.length - creates.length - updates.length} unchanged.`
+		);
+	}
+	return 0;
+}
+
+// --- Templates ---------------------------------------------------------------------
+
+export async function cmdTemplates(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return templatesList(rest);
+		case "show":
+		case "get":
+			return templatesShow(rest);
+		case "create":
+		case "new":
+			return templatesCreate(rest);
+		case "update":
+			return templatesUpdate(rest);
+		case "delete":
+		case "rm":
+			return templatesDelete(rest);
+		default:
+			throw new CliError(
+				`Unknown templates subcommand: ${sub ?? "(none)"}. Try: list, show, create, update, delete`
+			);
+	}
+}
+
+async function templatesList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_templates", {});
+	printResult(io, flags, result, (r) => {
+		const custom = (r.templates ?? []).map((t) => `  ${t.key}  ${t.name} — ${t.angle} (id ${t.id})`);
+		const builtIn = (r.built_ins ?? []).map((t) => `  ${t.key}  ${t.name}`);
+		return [
+			custom.length ? "Custom templates:" : "No custom templates yet.",
+			...custom,
+			"",
+			"Built-in templates (read-only):",
+			...builtIn,
+		].join("\n");
+	});
+	return 0;
+}
+
+async function templatesShow(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const templateId = requirePositional(positionals, 0, "template-id");
+	const result = await client.callTool("get_template", { template_id: templateId });
+	printResult(io, flags, result);
+	return 0;
+}
+
+function templateSectionsFromFlags(flags) {
+	const inline = flagStr(flags.sections);
+	const file = flagStr(flags["sections-file"]);
+	if (inline === undefined && file === undefined) return undefined;
+	const raw = inline !== undefined ? inline : readFileOrThrow(file, "--sections-file");
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new CliError(`--sections is not valid JSON: ${err.message}`);
+	}
+	if (!Array.isArray(parsed)) throw new CliError("--sections must be a JSON array of section objects");
+	return parsed;
+}
+
+async function templatesCreate(ctx) {
+	const { client, flags, io } = ctx;
+	const name = flagStr(flags.name);
+	const angle = flagStr(flags.angle);
+	const sections = templateSectionsFromFlags(flags);
+	if (!name) throw new CliError("Missing required --name");
+	if (!angle) throw new CliError("Missing required --angle");
+	if (!sections) throw new CliError("Missing required --sections '<json>' or --sections-file <path>");
+	const result = await client.callTool("create_template", { name, angle, sections });
+	ok(ctx, `Template created — key ${result.template?.key}.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function templatesUpdate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const templateId = requirePositional(positionals, 0, "template-id");
+	const name = flagStr(flags.name);
+	const angle = flagStr(flags.angle);
+	const sections = templateSectionsFromFlags(flags);
+	// update_template replaces the whole template; fetch current values for any
+	// field the caller didn't pass so a partial edit doesn't blank the rest.
+	let current;
+	if (!name || !angle || !sections) {
+		const existing = await client.callTool("get_template", { template_id: templateId });
+		current = existing.template;
+	}
+	const result = await client.callTool("update_template", {
+		template_id: templateId,
+		name: name ?? current.name,
+		angle: angle ?? current.angle,
+		sections: sections ?? current.sections,
+	});
+	ok(ctx, "Template updated.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function templatesDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const templateId = requirePositional(positionals, 0, "template-id");
+	if (!flagBool(flags.yes)) {
+		throw new CliError("Seers bound to this template fall back to defaults. Re-run with --yes to delete.");
+	}
+	const result = await client.callTool("delete_template", { template_id: templateId });
+	ok(ctx, "Template deleted.");
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands.mjs

@@ -19,3 +19,4 @@ 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";

package/package.json

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