@letterstory/cli 0.39.1 → 0.41.0

package/README.md

@@ -172,6 +172,9 @@ letterstory collection run-status <run-id>                      # status, steps,
 letterstory collection runs --collection <id> --status ready
 letterstory collection approve <run-id> --now
 letterstory collection cancel <run-id>
+letterstory collection inventory <id>                           # every piece; each finished draft's publish-on-its-own time
+letterstory collection links <id>                               # internal-link refresh: on/off, posts due
+letterstory collection links <id> --refresh                     # run the next batch now
 letterstory collection delete <id> --yes
 
 # the legacy verbs still work under `collections`
@@ -245,6 +248,23 @@ letterstory onboarding status
 letterstory onboarding step --complete connect_domain
 ```
 
+### What needs you — the collection's "needs you" strip, from the terminal
+
+Everything in the strip either applies itself after its countdown or waits for your
+decision; the same reads and decisions are here.
+
+```bash
+letterstory suggestions list <collection-id>          # strategy cards + when each applies itself
+letterstory suggestions dismiss proposal <id>         # reject one inside its window
+letterstory collection inventory <collection-id>      # finished drafts + when each publishes on its own
+letterstory collection links <collection-id>          # internal links due for a refresh
+
+# proposed edits to live posts: a mention an AI citation earned, or fresher internal links
+letterstory revisions list --collection <collection-id>
+letterstory revisions accept <revision-id>                     # every change; live where we publish
+letterstory revisions reject <revision-id> --change <change-id> --note "not this one"
+```
+
 ### Offerings — one org, many products
 
 Context is layered **org → offering → collection**. An offering is anything the org would
@@ -347,6 +367,32 @@ The ledger behind Kernel Tuning's Experiments tab
 (docs/architecture/kernel-experiment-agent.md): every question asked of the kernels,
 how it was tested, and what we learned and why.
 
+### Staff: the CRM pipeline
+
+```bash
+# Needs a STAFF key with crm:read (reads) and crm:write (writes). The same routes the
+# crm.letter.dev front end calls with a staff JWT; any /api/superadmin/crm/* route takes
+# the key as x-staff-api-key (GET → crm:read, anything else → crm:write).
+export LETTERSTORY_STAFF_API_KEY=<your staff key with crm:read,crm:write>
+
+letterstory admin crm signals --status new             # the Inbound feed (unmatched signals)
+letterstory admin crm record --source bookface --kind message \
+  --title "Asked about phantoms on Bookface" --name "Jane Doe" --company Acme --domain acme.com
+letterstory admin crm record --source twitter --kind social_engagement \
+  --title "Liked our launch tweet" --name "Pat" --linkedin https://linkedin.com/in/pat
+letterstory admin crm signal <signal-id> qualify       # link/create the account
+letterstory admin crm signal <signal-id> dismiss       # the easy delete (kept, marked)
+letterstory admin crm accounts --stage demo_scheduled  # with likelihood
+letterstory admin crm score <account-id>               # recompute; prints the factors
+```
+
+Every trigger — Cal.com bookings, Circleback recordings, Letterhome dinner RSVPs, RB2B
+visits, and what an agent records here — goes through one intake (`ingestSignal`,
+src/lib/crm/signals-intake.ts), so an agent's signal dedupes against a webhook's exactly
+as two webhooks do. Qualified kinds (booking, call recording, dinner, message, form) link
+or create the account; unqualified ones (a visit, a like) only attach to an existing
+account and otherwise wait in the Inbound feed.
+
 ### Propose, then onboard a phantom
 
 The Fleet wizard's Plan and Name screens as two commands: pick the beat, then the name,

package/lib/cli.mjs

@@ -27,6 +27,7 @@ import {
 	cmdDirectives,
 	cmdProbes,
 	cmdSuggestions,
+	cmdRevisions,
 	cmdOnboarding,
 	cmdSeries,
 	cmdInsights,
@@ -51,7 +52,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.39.1";
+export const VERSION = "0.41.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.
@@ -208,6 +209,8 @@ Collections (the content engine as a primitive — one door, 'collection run'):
   collection runs [--collection <id>] [--status <s>] [--limit <n>]
   collection approve <run-id> [--now]                  Answer the gate (--now publishes immediately)
   collection cancel <run-id>
+  collection inventory <id>                            Where every piece is; each finished draft's publish-on-its-own time
+  collection links <id> [--refresh]                    Internal-link refresh: on/off, posts due (--refresh runs the next batch now)
   collection delete <id> --yes
 
 Phantomstory (a collection Letterstory hosts as an independent publication):
@@ -306,6 +309,9 @@ Strategy & onboarding:
   strategy topics set --collection <uuid> (--topic <topic-id> | --suggestion <suggestion-id>)
   suggestions list <collection_id>                     List pending strategy suggestions + their auto-apply countdown
   suggestions approve | dismiss | snooze <verdict|proposal> <id> [--days <n>]
+  revisions list [--collection <uuid>]                 Proposed edits to live posts waiting for a decision
+  revisions accept | reject <revision-id> [--change <change-id>] [--note <text>]
+                                                       Decide one change or all; accepting goes live where we publish
   directives list <collection_id>                      What is steering this collection right now
   directives propose <collection_id> <what you want>   Read one instruction back as concrete levers (applies nothing)
   directives apply <directive_id> --effect <id>...     Commit the levers you kept (or --reason to decline them all)
@@ -550,6 +556,16 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        session (a trial per arm), linked to its
                                                        ledger entry. Written by \`npm run lab --
                                                        publish\` in the kernels repo.
+  admin crm signals [--status new] [--intent qualified] [--source rb2b] [--account <id>]
+          | record --title "…" [--source bookface] [--kind other] [--intent qualified]
+                   [--name …] [--email …] [--company …] [--domain …] [--linkedin …] [--detail …]
+          | signal <id> qualify|dismiss|link [--account <id>]
+          | accounts [--stage lead] [--q acme] | account <id> | score <account-id>
+                                                       The staff CRM's pipeline: the inbound signal
+                                                       feed, recording a signal with no webhook
+                                                       (Bookface, a tweet like), qualifying or
+                                                       dismissing one, and the explained score.
+                                                       Needs crm:read (reads) / crm:write (writes).
   admin tuning-context [--q "<question>"]              The experiment agent's context pack (JSON):
                                                        the pipeline as deployed, levers, measures,
                                                        goals, related history.
@@ -826,6 +842,7 @@ const CLIENT_COMMANDS = {
 	targets: cmdTargets,
 	probes: cmdProbes,
 	suggestions: cmdSuggestions,
+	revisions: cmdRevisions,
 	onboarding: cmdOnboarding,
 	series: cmdSeries,
 	insights: cmdInsights,

package/lib/commands/admin.mjs

@@ -7,6 +7,7 @@
 //   admin experiments list|show|new|update|note|started|spend|conclude|abandon …   (tuning:experiment)
 //   admin tuning-context [--q "<question>"]                                         (tuning:experiment)
 //   admin tuning-import <brief-results.json> [--experiment <id>]                    (tuning:experiment)
+//   admin crm signals|record|signal|accounts|account|score …                        (crm:read / crm:write)
 //   admin create-org --domain acme.com [--name "Acme"] [--test] [--no-key] [--key-name N]
 //                    [--capabilities a,b] [--onboard] [--about "…"] [--sitemap <url>]
 //                    [--cms <provider>] [--posts N] [--seers suggest|skip] [--no-visuals]
@@ -410,14 +411,118 @@ async function cmdAdminTuningContext(ctx) {
 	);
 }
 
+/* ------------------------------------------------------------ the staff CRM */
+
+const CRM = "/api/superadmin/crm";
+
+function signalLine(s) {
+	const who = [s.personName, s.companyName ?? s.companyDomain].filter(Boolean).join(" · ");
+	return `${s.id}  [${s.status} · ${s.intent}]  ${s.occurredAt.slice(0, 10)}  ${s.source}/${s.kind}  ${s.title}${who ? `\n    ${who}` : ""}`;
+}
+
+function accountLine(a) {
+	const score = a.likelihood == null ? "—" : a.likelihood.toFixed(2);
+	return `${a.id}  [${a.stage}]  ${score}  ${a.name}${a.domain ? ` (${a.domain})` : ""}${a.isYc ? " · YC" : ""}`;
+}
+
+/**
+ * `admin crm …` — the headless half of the staff CRM, so a background agent can watch the
+ * pipeline and record the signals that have no webhook (Bookface, tweet likes, DMs).
+ * Reads need `crm:read` on the staff key, writes `crm:write`. Every write goes through the
+ * same ingestSignal / actOnSignal the webhooks and the app use.
+ */
+async function cmdAdminCrm(ctx) {
+	const [sub, id, action] = ctx.positionals;
+	const { flags, io } = ctx;
+	const json = flagBool(flags.json);
+	const out = (result, line) => (json ? printResult(io, flags, result) : io.log(line(result)));
+	switch (sub) {
+		case "signals": {
+			const params = new URLSearchParams(
+				compact({
+					status: flagStr(flags.status),
+					intent: flagStr(flags.intent),
+					source: flagStr(flags.source),
+					account_id: flagStr(flags.account),
+					limit: flagStr(flags.limit),
+				})
+			);
+			return out(await staffRequest(ctx, "GET", `${CRM}/signals?${params}`), (r) =>
+				r.signals.length ? r.signals.map(signalLine).join("\n") : "(no signals)"
+			);
+		}
+		case "record": {
+			const body = compact({
+				source: flagStr(flags.source) ?? "agent",
+				kind: flagStr(flags.kind) ?? "other",
+				intent: flagStr(flags.intent),
+				title: flagStr(flags.title),
+				person_name: flagStr(flags.name),
+				person_email: flagStr(flags.email),
+				person_title: flagStr(flags["person-title"]),
+				linkedin_url: flagStr(flags.linkedin),
+				company_name: flagStr(flags.company),
+				company_domain: flagStr(flags.domain),
+				detail: flagStr(flags.detail),
+				url: flagStr(flags.link),
+				external_id: flagStr(flags["external-id"]),
+				occurred_at: flagStr(flags.at),
+				account_id: flagStr(flags.account),
+			});
+			if (!body.title)
+				throw new CliError(
+					'Usage: admin crm record --title "Liked our launch tweet" [--source twitter] [--kind social_engagement] …'
+				);
+			const r = await staffPost(ctx, `${CRM}/signals`, body);
+			return out(r, (x) => `${x.duplicate ? "already recorded" : "recorded"}: ${signalLine(x.signal)}`);
+		}
+		case "signal": {
+			if (!id || !["qualify", "dismiss", "link"].includes(action)) {
+				throw new CliError("Usage: admin crm signal <id> qualify|dismiss|link [--account <account-id>]");
+			}
+			const r = await staffRequest(
+				ctx,
+				"PATCH",
+				`${CRM}/signals/${id}`,
+				compact({ action, account_id: flagStr(flags.account) })
+			);
+			return out(r, (x) => signalLine(x.signal));
+		}
+		case "accounts": {
+			const params = new URLSearchParams(compact({ stage: flagStr(flags.stage), q: flagStr(flags.q) }));
+			return out(await staffRequest(ctx, "GET", `${CRM}/accounts?${params}`), (r) =>
+				r.accounts.length ? r.accounts.map(accountLine).join("\n") : "(no accounts)"
+			);
+		}
+		case "account":
+			if (!id) throw new CliError("Usage: admin crm account <id>");
+			return printResult(io, { ...flags, json: true }, await staffRequest(ctx, "GET", `${CRM}/accounts/${id}`));
+		case "score": {
+			if (!id) throw new CliError("Usage: admin crm score <account-id>");
+			const r = await staffPost(ctx, `${CRM}/accounts/${id}/score`, {});
+			return out(r, (x) =>
+				[
+					accountLine(x.account),
+					...(x.account.scoreFactors ?? []).map(
+						(f) => `  ${f.direction === "risk" ? "−" : "+"}${f.weight.toFixed(2)}  ${f.label}`
+					),
+				].join("\n")
+			);
+		}
+		default:
+			throw new CliError("Usage: admin crm signals|record|signal|accounts|account|score … (see --help)");
+	}
+}
+
 export async function cmdAdmin(ctx) {
 	const sub = ctx.positionals[0];
+	if (sub === "crm") return cmdAdminCrm({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "create-org") return cmdAdminCreateOrg({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "ask") return cmdAdminAsk({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "experiments") return cmdAdminExperiments({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "tuning-context") return cmdAdminTuningContext({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "tuning-import") return cmdAdminTuningImport({ ...ctx, positionals: ctx.positionals.slice(1) });
 	throw new CliError(
-		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin tuning-context (see --help)'
+		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin crm … | admin tuning-context (see --help)'
 	);
 }

package/lib/commands/collection.mjs

@@ -10,7 +10,7 @@
 
 import { readFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
-import { flagStr, printResult, ok, toolField, followJob, argsFromFlags } from "./shared.mjs";
+import { flagStr, printResult, ok, toolField, followJob, argsFromFlags, refuseUnknownFlags } from "./shared.mjs";
 
 function readJsonFileFlag(flags, flag) {
 	const path = flagStr(flags[flag]);
@@ -114,6 +114,15 @@ export const ARGS = {
 	cancel_collection_run: {
 		run_id: { positional: 0, label: "run-id", required: true },
 	},
+	get_collection_inventory: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	get_internal_link_status: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	refresh_internal_links: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
 };
 
 export async function cmdCollection(ctx) {
@@ -142,9 +151,13 @@ export async function cmdCollection(ctx) {
 			return collectionApprove(rest);
 		case "cancel":
 			return collectionCancel(rest);
+		case "inventory":
+			return collectionInventory(rest);
+		case "links":
+			return collectionLinks(rest);
 		default:
 			throw new CliError(
-				`Unknown collection subcommand: ${sub ?? "(none)"}. Try: list, new, config, delete, run, run-status, runs, approve, cancel`
+				`Unknown collection subcommand: ${sub ?? "(none)"}. Try: list, new, config, delete, run, run-status, runs, approve, cancel, inventory, links`
 			);
 	}
 }
@@ -277,3 +290,72 @@ async function collectionCancel(ctx) {
 	printResult(ctx.io, ctx.flags, result);
 	return 0;
 }
+
+// `collection inventory <id>` — where every piece is, and each finished draft's
+// publish-on-its-own time (the collection room's Work tab + "needs you" strip).
+function formatInventory(r) {
+	const lines = [
+		`Planner: ${r.planner?.enabled ? "on" : "off"} (${r.planner?.approvalMode ?? "?"})`,
+		`Live ${r.live?.count ?? 0} · written, not live ${r.readyNotLive?.count ?? 0} · being written ${r.beingWritten?.count ?? 0} · imported ${r.imported?.count ?? 0}`,
+	];
+	const pending = r.pendingReview?.items ?? [];
+	if (pending.length) {
+		lines.push(`Finished drafts (${r.pendingReview.count}):`);
+		for (const d of pending) {
+			const when = d.autoPublishAt ? `publishes on its own ${d.autoPublishAt}` : "waits for a person";
+			lines.push(`  ${d.articleId}  ${d.title}  [${when}]`);
+		}
+	}
+	return lines.join("\n");
+}
+
+async function collectionInventory(ctx) {
+	refuseUnknownFlags(ctx, {});
+	const result = await ctx.client.callTool(
+		"get_collection_inventory",
+		argsFromFlags(ARGS.get_collection_inventory, ctx.flags, ctx.positionals)
+	);
+	printResult(ctx.io, ctx.flags, result, formatInventory);
+	return 0;
+}
+
+// `collection links <id>` reads the internal-link refresh; `--refresh` runs the next
+// batch now (republished, or proposed for approval on a manual-approval collection).
+async function collectionLinks(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, {}, ["refresh"]);
+	if (flags.refresh === true) {
+		const r = await client.callTool(
+			"refresh_internal_links",
+			argsFromFlags(ARGS.refresh_internal_links, flags, positionals)
+		);
+		const parts = [];
+		if (r.posts_started) parts.push(`${r.posts_started} refreshing (each republishes when it finishes)`);
+		if (r.posts_proposed) parts.push(`${r.posts_proposed} proposed for approval (see: revisions list)`);
+		if (r.posts_skipped) parts.push(`${r.posts_skipped} busy with another run`);
+		if (!parts.length) {
+			parts.push(
+				r.skipped?.no_sitemap
+					? "no sitemap to link from"
+					: r.next_due_in_days === null
+						? "nothing due: every post already links to everything published since"
+						: `nothing due yet (next in ${r.next_due_in_days ?? "?"} days)`
+			);
+		}
+		ok(ctx, `Internal links: ${parts.join("; ")}.`);
+		if (flags.json) printResult(io, flags, r);
+		return 0;
+	}
+	const s = await client.callTool(
+		"get_internal_link_status",
+		argsFromFlags(ARGS.get_internal_link_status, flags, positionals)
+	);
+	printResult(io, flags, s, (r) =>
+		[
+			`Internal links: ${r.enabled ? "on" : "off"}`,
+			`Due now: ${r.due}`,
+			`Next due: ${r.next_due_in_days === null ? "only when something new publishes" : `in ${r.next_due_in_days} days`}`,
+		].join("\n")
+	);
+	return 0;
+}

package/lib/commands/revisions.mjs

@@ -0,0 +1,81 @@
+// `revisions` — proposed edits to already-live posts, waiting for a decision: the
+// Approvals queue in a collection's "needs you" strip. A mention an AI citation
+// earned (review-posture collection), or internal links the nightly refresh would
+// add (manual-approval or client-CMS collection). Thin wrappers over the MCP tools
+// list_revisions / decide_revision, which call the same lib/revisions functions the
+// web queue does — accepting on a page we publish puts it live.
+
+import { CliError } from "../client.mjs";
+import { printResult, argsFromFlags, refuseUnknownFlags, ok } from "./shared.mjs";
+
+const DECISIONS = ["accepted", "rejected"];
+
+// How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
+// `scripts/parity-check.ts` compares these keys against each tool's published input schema.
+export const ARGS = {
+	list_revisions: { collection_id: "collection" },
+	decide_revision: {
+		revision_id: { positional: 0, label: "revision-id", required: true },
+		// `accept` / `reject` set this for you.
+		decision: { flag: "decision", enum: DECISIONS },
+		change_id: "change",
+		note: "note",
+	},
+};
+
+const USAGE = `Usage: revisions <list|accept|reject>
+  revisions list [--collection <uuid>]
+  revisions accept <revision-id> [--change <change-id>]
+  revisions reject <revision-id> [--change <change-id>] [--note <text>]`;
+
+export async function cmdRevisions(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return revisionsList(rest);
+		case "accept":
+			return revisionsDecide(rest, "accepted");
+		case "reject":
+			return revisionsDecide(rest, "rejected");
+		default:
+			throw new CliError(USAGE);
+	}
+}
+
+function formatRevision(r) {
+	const where = r.publish_control === "platform" ? "goes live on accept" : "apply it in your CMS after accepting";
+	const lines = [
+		`${r.id}  ${r.article_title ?? "Untitled"}  (${r.source}; ${where})${r.is_stale ? "  [STALE — needs recomputing]" : ""}`,
+	];
+	if (r.reason) lines.push(`  ${r.reason}`);
+	for (const c of r.changes ?? []) {
+		const state = c.decision ?? "undecided";
+		lines.push(`  - ${c.id} [${state}] ${c.before ? `${c.before} → ` : ""}${c.after}`);
+	}
+	return lines.join("\n");
+}
+
+async function revisionsList(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.list_revisions);
+	const result = await client.callTool("list_revisions", argsFromFlags(ARGS.list_revisions, flags));
+	printResult(io, flags, result, (r) => {
+		const items = r.revisions ?? [];
+		return items.length ? items.map(formatRevision).join("\n\n") : "No proposed edits waiting.";
+	});
+	return 0;
+}
+
+async function revisionsDecide(ctx, decision) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.decide_revision);
+	const result = await client.callTool(
+		"decide_revision",
+		argsFromFlags(ARGS.decide_revision, { ...flags, decision }, positionals)
+	);
+	ok(ctx, result.applied ?? `Revision is ${result.status}.`);
+	if (flags.json) printResult(io, flags, result);
+	return 0;
+}

package/lib/commands.mjs

@@ -18,6 +18,7 @@ export * from "./commands/connectors.mjs";
 export * from "./commands/strategy.mjs";
 export * from "./commands/directives.mjs";
 export * from "./commands/probes.mjs";
+export * from "./commands/revisions.mjs";
 export * from "./commands/series.mjs";
 export * from "./commands/insights.mjs";
 export * from "./commands/covers.mjs";

package/package.json

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