@letterstory/cli 0.82.0 → 0.82.3

package/README.md

@@ -437,7 +437,9 @@ letterstory admin crm payment-link <account-id>        # Stripe Payment Link at
 
 `onboard` runs org → link → phantom sites → Slack channel → checklist → app invites →
 stage in one call. Each site is a real (not test) fleet build; `--site ""` lets the engine
-infer its beat from the client's homepage. `onboard-plan` reads the account's recorded calls
+infer its beat from the client's homepage. `--disclose 2` (or `--disclose all`) turns on sponsor
+disclosure ("safe mode") for that site, and `--disclose-note "…"` records the client's words
+as the reason; `onboard-plan` flags the sites whose calls asked for it. `onboard-plan` reads the account's recorded calls
 (newest first, cached per set of calls; `--refresh` re-reads) and says how many sites, what each
 is about, who to invite, and whether they've paid. `payment-link` stamps the account's org on
 the Stripe subscription, so paying through it binds and marks the account paid by itself.

package/lib/cli.mjs

@@ -57,7 +57,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.82.0";
+export const VERSION = "0.82.3";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value. Every `type: "bool"` flag (and its
@@ -81,6 +81,8 @@ export const BOOLEAN_FLAGS = new Set([
 	"rebuild",
 	"print-key",
 	"stdin",
+	// `authors generate <id> --with-bios`.
+	"with-bios",
 	// `covers generate <id> --regenerate` and `arena run --gate --article <id>`
 	// both put a value-less flag next to a value: without these entries the parser
 	// hands the following token to the flag and the real argument disappears.
@@ -331,14 +333,21 @@ Collections:
   collections autopen <id> [--template <key>|none] [--kernel-family <name>|org]
                            [--mention off|subtle|woven] [--outline-depth barebones|fleshed_out]
                            [--direction-gate true|false] [--auto-start true|false]
+                           [--prefer <site> …|none]
       The Auto-Pen settings the app's panel writes. --template binds a content
       template (from 'templates list') as this collection's default, which is how
       a template you author here actually gets used. A patch: unset flags are
-      left alone.
+      left alone. --prefer REPLACES the preferred sources: SITES research
+      searches for every post's topic and reaches for first when a figure fits
+      (a URL is saved as its site) — your own site included; 'none' clears them.
+  collections cite-preferred <id> [--limit <n>] [--dry-run]
+      Bring published posts up to the preferred sources: each eligible post gets
+      at most one preferred figure, linked on the figure, then republishes.
 
 Authors (the per-collection author bank — recurring bylines):
   authors list <collection-id>                        List the bank + byline distribution
-  authors generate <collection-id> [--count <n>]      Generate a believable masthead
+  authors generate <collection-id> [--count <n>] [--with-bios]
+                                                      Generate a masthead (names only; --with-bios adds a one-line bio + role)
   authors add <collection-id> --name <n> [--bio <t>] [--role <t>] [--expertise a,b] [--started-at YYYY-MM-DD]
   authors edit <collection-id> <author-id> [--name] [--bio] [--role] [--expertise a,b] [--started-at] [--active true|false]
   authors retire <collection-id> <author-id>          Stop assigning new posts to them
@@ -449,7 +458,7 @@ Ranking targets (what the org wants to be THE answer for — company-wide or on
 Arenas (adversarial clusters of research agents -> a sourced, fact-checked outline):
   arena run --topic <text> [--source <url> …] [--must-include <text> …] [--depth barebones|fleshed_out]
             [--gate] [--no-verify] [--provider native|exa|youcom|context-dev] [--mention off|subtle|woven]
-            [--context-file ctx.json] [--block <name> …] [--block-domain <domain> …]
+            [--context-file ctx.json] [--block <name> …] [--block-domain <domain> …] [--prefer <site> …]
             [--arena <arena-id>] [--article <uuid>] [--no-wait]
                                                         Start a run and follow it. --article makes
                                                         it HOSTED (outline written into that post,
@@ -521,6 +530,7 @@ Phantom launch recipe (a CLIENT domain -> a live phantom with its first posts; d
   ${bin === "phantom" ? "onboard" : "phantom-onboard"} <domain> [--about "the beat"] [--name X]
           [--posts N] [--cadence N] [--cover editorial_image|full_ai|line_art] [--theme T]
           [--real] [--domain host] [--domain-mode subdomain|buy_now|connect_later]
+          [--disclose [surfaces]] [--sponsor-label X] [--disclose-note "why"]
           [--accept] [--dry-run]
                                                        Plan (read-only) then, with --accept
                                                        or an override flag, provision + configure

package/lib/commands/admin.mjs

@@ -2405,7 +2405,11 @@ function planLines(p) {
 		`domain: ${p.domain ?? "(unknown)"}`,
 		`sites: ${p.sites.length}`,
 		...p.sites.map(
-			(s, i) => `  ${i + 1}. ${s.direction || "(infer from their homepage)"}${s.why ? `  — ${s.why}` : ""}`
+			(s, i) =>
+				`  ${i + 1}. ${s.direction || "(infer from their homepage)"}${s.why ? `  — ${s.why}` : ""}` +
+				(s.disclose_sponsor?.recommended
+					? `\n     disclose the sponsor (--disclose ${i + 1})${s.disclose_sponsor.quote ? `: “${s.disclose_sponsor.quote}”` : ""}`
+					: "")
 		),
 		`slack: ${p.slackEmails.join(", ") || "(nobody found)"}`,
 		`invites: ${p.invites.map((i) => `${i.email}:${i.role}`).join(", ") || "(none)"}`,
@@ -2418,19 +2422,35 @@ function planLines(p) {
 /**
  * `admin crm onboard` body from flags — the same CrmOnboardBodySchema the desk sends.
  * --site "<direction>" per site (repeatable; "" = infer from the homepage) and/or
- * --sites N (pads with inferred sites); --slack a@x,b@x (bare --slack = the channel, no
- * invites yet); --invite email[:admin|editor] (repeatable); --no-checklist.
+ * --sites N (pads with inferred sites); --disclose N (repeatable, 1-based; "all") turns on
+ * sponsor disclosure ("safe mode": the line after each article + schema.org sponsor) for
+ * that site, with --disclose-note "<the client's words>" as the reason; --slack a@x,b@x
+ * (bare --slack = the channel, no invites yet); --invite email[:admin|editor] (repeatable);
+ * --no-checklist.
  */
 function onboardBody(flags) {
 	const domain = flagStr(flags.domain);
 	if (!domain) {
 		throw new CliError(
-			'Usage: admin crm onboard <account-id> --domain acme.com [--name "Acme"] [--site "<direction>"]… [--sites N] [--slack a@x,b@x] [--invite a@x[:admin]]… [--no-checklist]'
+			'Usage: admin crm onboard <account-id> --domain acme.com [--name "Acme"] [--site "<direction>"]… [--sites N] [--disclose N|all]… [--disclose-note "…"] [--slack a@x,b@x] [--invite a@x[:admin]]… [--no-checklist]'
 		);
 	}
 	const sites = flagList(flags.site).map((direction) => ({ direction: direction.trim() || null }));
 	const total = flagNum(flags.sites);
 	while (total !== undefined && sites.length < total) sites.push({ direction: null });
+	const disclose = flagList(flags.disclose)
+		.flatMap((v) => String(v).split(","))
+		.map((v) => v.trim())
+		.filter(Boolean);
+	const note = flagStr(flags["disclose-note"]);
+	for (const which of disclose) {
+		const targets =
+			which === "all"
+				? sites.map((_, i) => i)
+				: [Number(which) - 1].filter((i) => Number.isInteger(i) && i >= 0 && i < sites.length);
+		if (targets.length === 0) throw new CliError(`--disclose ${which}: no such site (1–${sites.length}, or "all")`);
+		for (const i of targets) sites[i] = { ...sites[i], disclosure: compact({ note }) };
+	}
 	const slackEmails = flagList(flags.slack)
 		.flatMap((v) => v.split(","))
 		.map((e) => e.trim())

package/lib/commands/arena.mjs

@@ -22,6 +22,7 @@ import {
 	toolField,
 	followJob,
 	argsFromFlags,
+	preferredSourcesFlag,
 } from "./shared.mjs";
 
 /** `--<flag> <path>` → the file's parsed JSON, or undefined when the flag is not set. */
@@ -75,6 +76,8 @@ const RUN_OPTIONS = {
 	context: { value: (flags) => readJsonObjectFlag(flags, "context") },
 	blocked_mentions: { flag: "block", type: "list" },
 	blocked_domains: { flag: "block-domain", type: "list" },
+	// Pages (read every run) and sites research reaches for first; `--prefer none` declares none.
+	preferred_sources: { value: (flags) => preferredSourcesFlag(flags.prefer) },
 };
 
 /**

package/lib/commands/authors.mjs

@@ -61,7 +61,11 @@ async function authorsList(ctx) {
 
 async function authorsGenerate(ctx) {
 	const { client, flags, io } = ctx;
-	const args = compact({ collection_id: collectionId(ctx), count: flagNum(flags.count) });
+	const args = compact({
+		collection_id: collectionId(ctx),
+		count: flagNum(flags.count),
+		with_bios: flagBool(flags["with-bios"]) || undefined,
+	});
 	const result = await client.callTool("generate_collection_authors", args);
 	ok(ctx, "Generated authors.");
 	printResult(io, flags, result);

package/lib/commands/collections.mjs

@@ -2,7 +2,7 @@
 // Ported from phantomstory-cli's collections.ts.
 
 import { CliError } from "../client.mjs";
-import { flagStr, printResult, ok, argsFromFlags } from "./shared.mjs";
+import { flagStr, printResult, ok, argsFromFlags, preferredSourcesFlag } from "./shared.mjs";
 import { cmdCollection } from "./collection.mjs";
 
 // `--flag none|off|""` clears a nullable field; the server takes null for that.
@@ -47,6 +47,11 @@ export const ARGS = {
 		regenerate_topic_map: { value: (flags) => (flags["no-topic-map"] === undefined ? undefined : false) },
 		stock_headlines: { value: (flags) => (flags["no-headlines"] === undefined ? undefined : false) },
 	},
+	cite_preferred_sources: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+		limit: { flag: "limit", type: "num" },
+		dry_run: { value: (flags) => (flags["dry-run"] === true ? true : undefined) },
+	},
 	update_auto_pen_config: {
 		collection_id: { positional: 0, label: "collection-id", required: true },
 		// `--template none` clears the binding; the server takes null for that.
@@ -69,6 +74,8 @@ export const ARGS = {
 		},
 		mention: { object: { degree: "mention" } },
 		auto_start_on_curate: stringBool("auto-start"),
+		// Replaces the collection's preferred sources; `--prefer none` clears them.
+		preferred_sources: { value: (flags) => preferredSourcesFlag(flags.prefer) },
 	},
 };
 
@@ -99,9 +106,11 @@ export async function cmdCollections(ctx) {
 			return collectionsAutoPen(rest);
 		case "activate":
 			return collectionsActivate(rest);
+		case "cite-preferred":
+			return collectionsCitePreferred(rest);
 		default:
 			throw new CliError(
-				`Unknown collections subcommand: ${sub ?? "(none)"}. Try: list, new, update, delete, assign, autopen, activate`
+				`Unknown collections subcommand: ${sub ?? "(none)"}. Try: list, new, update, delete, assign, autopen, activate, cite-preferred`
 			);
 	}
 }
@@ -129,6 +138,26 @@ async function collectionsActivate(ctx) {
 	return 0;
 }
 
+/**
+ * `collections cite-preferred <id> [--limit <n>] [--dry-run]` — bring the collection's published
+ * posts up to its preferred sources: each eligible post places at most one preferred figure and
+ * republishes. The same function as the app's "Apply to published posts".
+ */
+async function collectionsCitePreferred(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.cite_preferred_sources, flags, positionals);
+	const result = await client.callTool("cite_preferred_sources", args);
+	const n = result?.started?.length ?? 0;
+	ok(
+		ctx,
+		result?.dry_run
+			? `Would run ${n} post${n === 1 ? "" : "s"}; ${result?.skipped?.length ?? 0} skipped.`
+			: `Started ${n} post${n === 1 ? "" : "s"}${result?.republishes === false ? " (changes wait on the draft for approval)" : ""}; ${result?.skipped?.length ?? 0} skipped.`
+	);
+	printResult(io, flags, result);
+	return 0;
+}
+
 async function collectionsUpdate(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	const patch = argsFromFlags(ARGS.update_collection, flags, positionals);
@@ -166,7 +195,7 @@ async function collectionsAutoPen(ctx) {
 	const patch = argsFromFlags(ARGS.update_auto_pen_config, flags, positionals);
 	if (Object.keys(patch).length === 1) {
 		throw new CliError(
-			"Nothing to change. Pass at least one of --template, --kernel-family, --mention, --outline-depth, --direction-gate, --auto-start."
+			"Nothing to change. Pass at least one of --template, --kernel-family, --mention, --outline-depth, --direction-gate, --auto-start, --prefer."
 		);
 	}
 

package/lib/commands/onboard.mjs

@@ -151,6 +151,23 @@ export const ARGS = {
 				is_test: { flag: "real", type: "bool", invert: true },
 				// A self-serve integrator's customers launch their own sites: no staff pings.
 				notify_staff: { flag: "no-notify-staff", type: "bool", invert: true },
+				// Sponsor disclosure ("safe mode"): bare --disclose = the safe-mode surfaces (the
+				// server's default); --disclose article_footer,cover_badge picks them. Off unless asked.
+				disclosure: {
+					value: (flags) => {
+						if (flags.disclose === undefined || flags.disclose === false) return undefined;
+						const listed = typeof flags.disclose === "string" ? flags.disclose : "";
+						const surfaces = listed
+							.split(",")
+							.map((s) => s.trim())
+							.filter(Boolean);
+						return compact({
+							surfaces: surfaces.length ? surfaces : undefined,
+							sponsor_label: flagStr(flags["sponsor-label"]),
+							note: flagStr(flags["disclose-note"]),
+						});
+					},
+				},
 			},
 		},
 	},

package/lib/commands/shared.mjs

@@ -32,6 +32,20 @@ export function flagList(v) {
 	return typeof v === "string" ? [v] : [];
 }
 
+/**
+ * `--prefer <site>` (repeatable or comma-separated) → preferred_sources `[{ url }]` (a site; a URL is read as its site); `--prefer none`
+ * → `[]` (clears a standing list); absent → undefined.
+ */
+export function preferredSourcesFlag(v) {
+	if (v === undefined) return undefined;
+	const list = flagList(v)
+		.flatMap((x) => x.split(","))
+		.map((x) => x.trim())
+		.filter(Boolean);
+	if (list.length === 1 && list[0] === "none") return [];
+	return list.map((url) => ({ url }));
+}
+
 export function requireFlag(flags, name) {
 	const v = flagStr(flags[name]);
 	if (v === undefined) throw new CliError(`Missing required --${name}`);

package/package.json

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