@letterstory/cli 0.126.1 → 0.128.2

package/lib/cli.mjs

@@ -62,12 +62,13 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.126.1";
+export const VERSION = "0.128.2";
 
 // 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
 // `negate` spelling) in a command's ARGS map must be listed; boolean-flags.test.ts enforces it.
 export const BOOLEAN_FLAGS = new Set([
+	"remap",
 	"json",
 	// admin models runs: only the starred ones.
 	"starred",
@@ -80,6 +81,11 @@ export const BOOLEAN_FLAGS = new Set([
 	"stealth",
 	"disclosure",
 	"no-disclosure",
+	"no-cta",
+	"remember",
+	"no-remember",
+	// enclosures print: make a new one even for people with a recent print.
+	"redo",
 	// site tree: include children a fold-by-default family would hide; items over the whole subtree.
 	"unfold",
 	"subtree",
@@ -280,6 +286,8 @@ export const BOOLEAN_FLAGS = new Set([
 	"not-reached",
 	"reached",
 	"todo",
+	// admin spend margin: list nested work (never billed twice) beside its parent.
+	"nested",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -358,7 +366,7 @@ Collections (the content engine as a primitive — one door, 'collection run'):
                                                        Print the ONE FILE (identity, content, cadence,
                                                        publishing, targets, measurement) — or PATCH it
   collection run --collection <id> [--topic <t> | --spoke <topic-id> | --headline <suggestion-id>]
-                 [--source <url> …] [--must-include <t> …] [--depth barebones|fleshed_out]
+                 [--source <url> …] [--notes <text>] [--must-include <t> …] [--depth barebones|fleshed_out]
                  [--kernel <id>] [--no-verify] [--shred] [--mention off|subtle|woven]
                  [--approval autopilot|review_window|manual] [--no-publish] [--no-rebuild]
                  [--at <iso-datetime>] [--no-wait]
@@ -369,7 +377,7 @@ Collections (the content engine as a primitive — one door, 'collection run'):
   collection queue <suggestion-id>                     Queue a headline, as the app's queue button does: the
                                                        next slot of the schedule when the Planner is on,
                                                        else a draft to write by hand
-  collection add "<headline>" --collection <id> [--queue]
+  collection add "<headline>" --collection <id> [--notes <text>] [--queue]
                                                        A headline you wrote: joins Up next, or with --queue
                                                        is queued at once (the next slot, or a draft)
   collection headline <suggestion-id> [--dismiss | --later | --restore] [--headline "…"]
@@ -439,9 +447,16 @@ Reviewers:
   reviewers assigned                                   Posts waiting on your review, across letterbases
   automations list --collection <id>                   What a letterbase writes, how often, and why
   automations show <automation-id> --collection <id>  What it covers, its queued posts, its next ideas
+  automations suggest --collection <id>                What it could add: topics, series formats, signals
+  automations preview topic|series --collection <id> [--name <name>|--topic <id>] [--brief <text>]
+                                                       What it would write, before adding it
+  automations more --collection <id>                   New topics it doesn't cover yet
+  automations dismiss <topic-id> --collection <id>     Set one subject aside
   automations add topic|series|signal|best --collection <id> [--topic <id>] [--goal <target-id>]
-                  [--seer <id>] [--pace <n>]           Add one (refused if it says the same as another)
+                  [--seer <id>] [--pace <n>] [--brief <text>] [--new-topic <name>] [--new-series <name>]
+                                                       Add one (refused if it says the same as another)
   automations set <automation-id> --collection <id> [--pace <n>] [--pause | --resume] [--goal <id>]
+                  [--brief <text>] [--remap]
   automations remove <automation-id> --collection <id>
   reviewers invite <article-id> --email <e> [--name <n>]
                                                        Invite a guest to review one post
@@ -539,6 +554,12 @@ Enclosures (pictures, clips and sentences made for each prospect; each output is
                     [--login <app-connection-id>] [--tool run_site_audit…] [--skip-when <sentence>]
   enclosures update <enclosure-id> [same flags]        Outputs are fixed once a version is in use
   enclosures prints <enclosure-id> [--status <s>]      Its current prints, newest first
+  enclosures starters                                  What an enclosure can begin from (each with a version 1)
+  enclosures approve <enclosure-id> --version <n>      Choose the version prints run
+  enclosures print <enclosure-id> (--prospect <id>…|--list <id>) [--dry-run]  Test (3 people) or print
+  enclosures apps list|show <app-id>                   Your apps: sign-ins enclosures use, with their state
+  enclosures apps connect <sign-in-url> [--no-remember] A sign-in link a person opens (no password passes through)
+  enclosures apps disconnect <app-id> --yes            Remove it here and at the browser provider
 
 Offerings (context layered org → offering → collection; a layer sets only what it overrides):
   offerings list                                       The org's offerings (things you'd name when recommending them)
@@ -862,7 +883,7 @@ 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 models runs [--model M] [--starred] | run <id> | star|unstar <id> | scoreboard --model M
+  admin models runs [--search T] [--model M] [--starred] | run <id> | star|unstar <id> | scoreboard --model M
                                                        The model hub's saved runs and blind arena (models.letter.dev)
   admin spend summary [--range day|week|month|year | --from D --to D] [--grain day|week|month]
           | reconcile [--from D --to D] | pnl [--range day|week|month|year | --from D --to D]
@@ -1373,6 +1394,8 @@ Visits (Visitors: AI agents reading your site, and AI answers sending people to
                                                        Pages one agent read that the other didn't
   visits export [--since 30d] [--format json|csv] [--table agent_visits|citations]
   visits sites                                         Your Visitors sites and their install checks
+  visits pages [--since 28d] [--path '/docs/*'] [--agent <id>] [--limit <n>] [--site <id>]
+                                                       People and AI agents per page
 
 Evals (how the pipeline is doing on your posts, and the regression cases captured from them):
   evals scoreboard [--collection <id>] [--days N]      Every measure by stage: posts, failing, rate

package/lib/commands/admin.mjs

@@ -15,7 +15,7 @@
 //   admin evals scoreboard|cases|runs|run|triage|guard|retire …                      (fleet:read / tuning:experiment)
 //   admin fleet-experiments list|articles|clients|mark|unmark|new|assign|assign-eligible|assign-orgs|spin-up|apply|start|stop|decide …  (fleet:read / fleet:experiment)
 //   admin crm import|capture|outreach|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|revenue|reach-outs|record-churn|draft-churn-reason|undo-churn|outcomes|record-outcome|renewals|track-record|at-risk|expansion-signals|collections|delivery-flags|case|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
-//   admin spend summary|reconcile|pnl|entries|add|import|usage|remove|reference|stripe-sync|services|service …  (spend:read / spend:write)
+//   admin spend summary|reconcile|pnl|margin|pricing|entries|add|import|usage|remove|reference|stripe-sync|services|service …  (spend:read / spend:write)
 //   admin brand-detection <org-id>                                                   (fleet:read)
 //   admin brand-detection <org-id> [--term t]... [--exact t]... [--exclude p]... [--note "…"] | --clear [--note "…"]   (fleet:instrument)
 //   admin recipes list|show|vocab|export|import|save|delete …                        (recipes:read / recipes:write)
@@ -4005,7 +4005,7 @@ function spendEntryFromFlags(flags) {
 
 const MODELS = "/api/superadmin/models";
 const MODELS_USAGE =
-	"Usage: admin models runs [--model ballpoint-1] [--starred] [--limit N] | run <id> | star <id> | unstar <id> | scoreboard --model ballpoint-1";
+	"Usage: admin models runs [--search TEXT] [--model ballpoint-1] [--starred] [--limit N] | run <id> | star <id> | unstar <id> | scoreboard --model ballpoint-1";
 
 /** The model hub's saved runs and blind arena (models.letter.dev), same functions as its pages. */
 async function cmdAdminModels(ctx) {
@@ -4015,6 +4015,7 @@ async function cmdAdminModels(ctx) {
 		case "runs": {
 			const params = new URLSearchParams(
 				compact({
+					q: flagStr(flags.search),
 					model: flagStr(flags.model),
 					starred: flagBool(flags.starred) ? "true" : undefined,
 					limit: flagNum(flags.limit)?.toString(),
@@ -4264,6 +4265,70 @@ async function cmdAdminSpend(ctx) {
 			);
 			return 0;
 		}
+		case "margin": {
+			// Shadow usage metering: usage per SKU, our cost, draft tokens and margin
+			// (GET /api/superadmin/spend/usage-margin → summarizeUsage).
+			const params = new URLSearchParams(
+				compact({
+					from: flagStr(flags.from),
+					to: flagStr(flags.to),
+					orgId: flagStr(flags.org),
+					groupBy: flagStr(flags["group-by"]),
+					includeNested: flagBool(flags.nested) ? "true" : undefined,
+					rateCard: flagStr(flags["rate-card"]),
+				})
+			);
+			const result = await staffRequest(ctx, "GET", `${SPEND}/usage-margin${params.size ? `?${params}` : ""}`);
+			printResult(io, flags, result, (m) =>
+				[
+					`${m.range.from} → ${m.range.to}: ${m.totals.billableEvents} billable of ${m.totals.events} events · ${m.totals.tokens ?? "?"} tokens (${m.rateCard?.version ?? "no card"}) · cost ${usd(m.totals.cost?.totalUsd)} · margin ${m.totals.marginUsd === null ? "?" : usd(m.totals.marginUsd)}`,
+					"",
+					...m.rows.map(
+						(r) =>
+							`  ${[r.day, r.orgId, r.collectionId, r.customerRef, r.sku].filter(Boolean).join(" ").slice(0, 60).padEnd(60)} ${String(r.billableQuantity).padStart(9)} ${r.unit.padEnd(10)} ${String(r.tokens ?? "?").padStart(9)} tok  cost ${usd(r.cost?.totalUsd).padStart(9)}${r.cost?.eventsWithoutCost ? ` (${r.cost.eventsWithoutCost} unpriced)` : ""}`
+					),
+				].join("\n")
+			);
+			return 0;
+		}
+		case "pricing": {
+			// What shadow metering says prices should be (GET /api/superadmin/spend/pricing-read
+			// → readPricing). Reads only; nothing changes a price.
+			const params = new URLSearchParams(
+				compact({
+					from: flagStr(flags.from),
+					to: flagStr(flags.to),
+					multiple: flagStr(flags.multiple),
+					tiers: flagStr(flags.tiers),
+					rateCard: flagStr(flags["rate-card"]),
+				})
+			);
+			const result = await staffRequest(ctx, "GET", `${SPEND}/pricing-read${params.size ? `?${params}` : ""}`);
+			const cents = (c) => usd((c ?? 0) / 100);
+			const unit = (n) => (n === null || n === undefined ? "?" : `$${Number(n).toFixed(n < 0.1 ? 4 : 2)}`);
+			printResult(io, flags, result, (p) =>
+				[
+					`${p.range.from} → ${p.range.to} (${p.range.days}d, ${p.range.buckets} month buckets) · card ${p.rateCard.version}${p.rateCard.published ? "" : " (draft)"} · proposal at ${p.multiple}× p75 cost · revenue as of ${p.revenueCapturedOn ?? "no snapshot"}`,
+					"",
+					"Per SKU: unit cost p50 / p75 / p90 · priced of billable events · tokens a unit now → proposed",
+					...p.skus
+						.filter((s) => s.events > 0)
+						.map(
+							(s) =>
+								`  ${s.sku.padEnd(30)} ${unit(s.unitCostUsd.p50).padStart(8)} ${unit(s.unitCostUsd.p75).padStart(8)} ${unit(s.unitCostUsd.p90).padStart(8)}  ${String(s.pricedEvents).padStart(6)}/${String(s.events).padEnd(6)} ${s.pricing === "per_unit" ? `${s.current ?? "?"} → ${s.proposedTokensPerUnit ?? "?"}` : `cost × ${s.current ?? "?"}`}${s.confidence === "measured" ? "" : ` (${s.confidence})`}${s.gaps.unattributed || s.gaps.unpricedCalls || s.gaps.partialOwnCost || s.gaps.withoutCost ? `  [left out: ${s.gaps.unattributed} unattributed, ${s.gaps.unpricedCalls} unpriced calls, ${s.gaps.partialOwnCost} partial own cost, ${s.gaps.withoutCost} no cost]` : ""}`
+						),
+					"",
+					`Paying clients: ${p.fleet.clients} · monthly tokens p50 ${p.fleet.monthlyTokens.p50 ?? "?"} · p75 ${p.fleet.monthlyTokens.p75 ?? "?"} · p90 ${p.fleet.monthlyTokens.p90 ?? "?"}`,
+					"Per client (child accounts rolled up): revenue/mo · tokens/mo mean, peak · cost/mo · tier · complimentary tokens",
+					...p.clients.map(
+						(o) =>
+							`  ${`${o.name ?? o.clientId}${o.orgIds.length > 1 ? ` (${o.orgIds.length} orgs)` : ""}`.slice(0, 28).padEnd(28)} ${cents(o.revenueMonthlyCents).padStart(9)} ${String(o.monthlyTokens.mean).padStart(9)} ${String(o.monthlyTokens.peak).padStart(9)} ${usd(o.monthlyCostUsd.mean).padStart(9)}  ${o.ratioTier ? `${o.ratioTier}×` : "—"}  ${o.complimentaryTokens ?? "—"}${o.flags.length ? `  [${o.flags.join(", ")}]` : ""}`
+					),
+					...p.notes.map((n) => `· ${n}`),
+				].join("\n")
+			);
+			return 0;
+		}
 		case "reference": {
 			const vendor = flagStr(flags.vendor);
 			const metric = flagStr(flags.metric);
@@ -4338,7 +4403,7 @@ async function cmdAdminSpend(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin spend summary [--range day|week|month|year | --from D --to D] [--grain day|week|month] | reconcile [--from D --to D] | pnl [--range …] | reference add … | stripe-sync --from D --to D | entries [--from D] [--to D] [--vendor V] [--area A] [--source S] | add --vendor V --amount N --from D … | import <file.csv> … | usage <events.json> | usage list --source S --from D --to D | remove <entry-id> | services | service <slug> --owner … --monthly …"
+				"Usage: admin spend summary [--range day|week|month|year | --from D --to D] [--grain day|week|month] | reconcile [--from D --to D] | pnl [--range …] | margin [--from D --to D] [--org <uuid>] [--group-by sku,org,collection,customer_ref,day] [--nested] [--rate-card V] | pricing [--from D --to D] [--multiple 3] [--tiers 1,2,4,8] [--rate-card V] | reference add … | stripe-sync --from D --to D | entries [--from D] [--to D] [--vendor V] [--area A] [--source S] | add --vendor V --amount N --from D … | import <file.csv> … | usage <events.json> | usage list --source S --from D --to D | remove <entry-id> | services | service <slug> --owner … --monthly …"
 			);
 	}
 }

package/lib/commands/automations.mjs

@@ -1,5 +1,5 @@
 // `automations` — a letterbase's automations (docs/architecture/automations.md): what it writes,
-// how often, and why. list / show / add / set / remove, through the same tools the app uses.
+// how often, and why. list / show / suggest / preview / more / add / set / dismiss / remove, through the same tools the app uses.
 // Same flag/positional/io conventions as posts.mjs — no commander, no color.
 
 import { CliError } from "../client.mjs";
@@ -10,6 +10,9 @@ export const ARGS = {
 	list_automations: {
 		collection_id: { flag: "collection", required: true },
 	},
+	suggest_automations: {
+		collection_id: { flag: "collection", required: true },
+	},
 	get_automation: {
 		collection_id: { flag: "collection", required: true },
 		automation_id: { positional: 0, label: "automation-id", required: true },
@@ -21,6 +24,13 @@ export const ARGS = {
 		target_id: { flag: "goal" },
 		seer_id: { flag: "seer" },
 		pace_per_week: { flag: "pace", type: "num" },
+		brief: { flag: "brief" },
+		new_topic: {
+			value: (flags) => (typeof flags["new-topic"] === "string" ? { name: flags["new-topic"] } : undefined),
+		},
+		new_series: {
+			value: (flags) => (typeof flags["new-series"] === "string" ? { name: flags["new-series"] } : undefined),
+		},
 	},
 	update_automation: {
 		collection_id: { flag: "collection", required: true },
@@ -30,6 +40,24 @@ export const ARGS = {
 			value: (flags) => (flags.pause === true ? true : flags.resume === true ? false : undefined),
 		},
 		target_id: { flag: "goal" },
+		brief: { flag: "brief" },
+		remap: { value: (flags) => (flags.remap === true ? true : undefined) },
+		subjects: { value: () => undefined },
+	},
+	preview_automation: {
+		collection_id: { flag: "collection", required: true },
+		kind: { positional: 0, label: "kind", required: true, enum: ["topic", "series"] },
+		cluster_id: { flag: "topic" },
+		name: { flag: "name" },
+		brief: { flag: "brief" },
+		items: { flag: "items", type: "list" },
+	},
+	suggest_more_topics: {
+		collection_id: { flag: "collection", required: true },
+	},
+	dismiss_subject: {
+		collection_id: { flag: "collection", required: true },
+		topic_id: { positional: 0, label: "topic-id", required: true },
 	},
 	delete_automation: {
 		collection_id: { flag: "collection", required: true },
@@ -46,16 +74,26 @@ export async function cmdAutomations(ctx) {
 			return run(rest, "list_automations");
 		case "show":
 			return run(rest, "get_automation");
+		case "suggest":
+			return run(rest, "suggest_automations");
+		case "preview":
+			return run(rest, "preview_automation");
+		case "more":
+			return run(rest, "suggest_more_topics");
+		case "dismiss":
+			return run(rest, "dismiss_subject", "Set aside.");
 		case "add":
 			return run(rest, "create_automation", "Added.");
 		case "set":
-			refuseUnknownFlags(rest, ARGS.update_automation, ["pause", "resume"]);
+			refuseUnknownFlags(rest, ARGS.update_automation, ["pause", "resume", "remap"]);
 			return run(rest, "update_automation", "Changed.");
 		case "remove":
 		case "rm":
 			return run(rest, "delete_automation", "Removed.");
 		default:
-			throw new CliError(`Unknown automations subcommand: ${sub ?? "(none)"}. Try: list, show, add, set, remove`);
+			throw new CliError(
+				`Unknown automations subcommand: ${sub ?? "(none)"}. Try: list, show, suggest, preview, more, add, set, dismiss, remove`
+			);
 	}
 }
 

package/lib/commands/collection.mjs

@@ -76,6 +76,7 @@ export const ARGS = {
 		topic_id: { flag: "spoke" },
 		suggestion_id: { flag: "headline" },
 		source_urls: { flag: "source", type: "list" },
+		context: { flag: "notes" },
 		must_include: { flag: "must-include", type: "list" },
 		research_depth: { flag: "depth", enum: ["barebones", "fleshed_out"] },
 		kernel_id: { flag: "kernel" },
@@ -93,6 +94,7 @@ export const ARGS = {
 	add_headline: {
 		collection_id: { flag: "collection", required: true },
 		headline: { positional: 0, label: "headline", required: true },
+		context: { flag: "notes" },
 		queue: { flag: "queue", type: "bool" },
 	},
 	update_suggestion: {
@@ -302,7 +304,7 @@ async function collectionHeadline(ctx) {
 	return 0;
 }
 
-// `collection add "<headline>" --collection <id> [--queue]` — the letterbase page's New post: a
+// `collection add "<headline>" --collection <id> [--notes <text>] [--queue]` — the letterbase page's New post: a
 // headline you wrote joins Up next, or with --queue takes the next slot (a draft, planner off).
 async function collectionAdd(ctx) {
 	const { client, flags, io } = ctx;

package/lib/commands/enclosures.mjs

@@ -64,10 +64,19 @@ const fields = {
 	budget_per_person_usd: { flag: "budget", type: "num" },
 	no_fit_rule: "skip-when",
 	disclosure: { flag: "disclosure", type: "bool", negate: "no-disclosure" },
+	cta: {
+		value: (flags) => {
+			if (flags["no-cta"] === true) return null;
+			const label = flagStr(flags["cta-label"]);
+			const url = flagStr(flags["cta-url"]);
+			return label || url ? { label, url } : undefined;
+		},
+	},
 };
 
 // Flags the computed sources above read (refuseUnknownFlags can't see inside `value`).
 const FIELD_FLAGS = [
+	"starter",
 	"instructions",
 	"instructions-file",
 	"input",
@@ -79,6 +88,9 @@ const FIELD_FLAGS = [
 	"region",
 	"image-model",
 	"tool",
+	"cta-label",
+	"cta-url",
+	"no-cta",
 ];
 
 // How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
@@ -90,13 +102,58 @@ export const ARGS = {
 	},
 	create_generator: {
 		key: "key",
+		starter: "starter",
 		...fields,
-		name: { flag: "name", required: true },
 	},
 	update_generator: {
 		generator_id: { positional: 0, label: "enclosure-id", required: true },
 		...fields,
 	},
+	list_generator_starters: {},
+	add_generator_version: {
+		generator_id: { positional: 0, label: "enclosure-id", required: true },
+		script: { value: (flags) => readTextInput(flags, "script", "script-file") },
+		steps: {
+			value: (flags) => {
+				const v = flagList(flags.step);
+				return v.length ? v.map((text, i) => ({ n: i + 1, text })) : undefined;
+			},
+		},
+		allowed_hosts: { flag: "host", type: "list" },
+		region: {
+			value: (flags) => {
+				const v = flagList(flags["region-selector"]);
+				return v.length ? { selectors: v } : undefined;
+			},
+		},
+		params_schema: { internal: "set by the app when a person edits steps; not a flag" },
+		record_span: { internal: "set by the app when a recording is marked; not a flag" },
+		change_summary: "summary",
+	},
+	approve_generator_version: {
+		generator_id: { positional: 0, label: "enclosure-id", required: true },
+		version: { flag: "version", type: "num", required: true },
+	},
+	print_generator: {
+		generator_id: { positional: 0, label: "enclosure-id", required: true },
+		prospect_ids: { flag: "prospect", type: "list" },
+		list_id: "list",
+		version: { flag: "version", type: "num" },
+		redo: { flag: "redo", type: "bool" },
+		dry_run: { flag: "dry-run", type: "bool" },
+	},
+	list_app_connections: {},
+	get_app_connection: {
+		connection_id: { positional: 0, label: "app-id", required: true },
+	},
+	connect_app: {
+		login_url: { positional: 0, label: "sign-in-url", required: true },
+		name: "name",
+		remember_sign_in: { flag: "remember", type: "bool", negate: "no-remember" },
+	},
+	disconnect_app: {
+		connection_id: { positional: 0, label: "app-id", required: true },
+	},
 	list_generations: {
 		generator_id: { positional: 0, label: "enclosure-id", required: true },
 		status: { flag: "status", enum: ["queued", "running", "done", "no_fit", "failed", "skipped"] },
@@ -111,8 +168,18 @@ const USAGE = `Usage: enclosures <list|show|create|update|prints>
                     [--input website…] [--browser] [--login <app-connection-id>] [--stealth] [--record] [--region us-east|eu-west]
                     [--image-model] [--tool run_site_audit…] [--share prospect|company_domain] [--fresh-days <n>]
                     [--budget <usd>] [--skip-when <sentence>] [--no-disclosure]
+                    [--cta-label "Book a time" --cta-url <https link>] [--no-cta]
   enclosures update <enclosure-id> [same flags]
-  enclosures prints <enclosure-id> [--status done|failed|no_fit|…] [--limit <n>]`;
+  enclosures prints <enclosure-id> [--status done|failed|no_fit|…] [--limit <n>]
+  enclosures starters
+  enclosures create --starter site_audit --login <app-id>       Begin from a starter (its version 1 included)
+  enclosures add-version <enclosure-id> (--script <code>|--script-file <path>) --step <text>… [--host <h>…] [--summary <s>]
+  enclosures approve <enclosure-id> --version <n>
+  enclosures print <enclosure-id> (--prospect <id>…|--list <list-id>) [--version <n>] [--redo] [--dry-run]
+  enclosures apps list
+  enclosures apps show <app-id>
+  enclosures apps connect <sign-in-url> [--name <n>] [--no-remember]   Prints a sign-in link a person opens
+  enclosures apps disconnect <app-id> --yes`;
 
 export async function cmdEnclosures(ctx) {
 	const sub = ctx.positionals[0];
@@ -130,6 +197,16 @@ export async function cmdEnclosures(ctx) {
 			return enclosuresUpdate(rest);
 		case "prints":
 			return enclosuresPrints(rest);
+		case "apps":
+			return enclosuresApps(rest);
+		case "starters":
+			return enclosuresStarters(rest);
+		case "add-version":
+			return enclosuresAddVersion(rest);
+		case "approve":
+			return enclosuresApprove(rest);
+		case "print":
+			return enclosuresPrint(rest);
 		default:
 			throw new CliError(USAGE);
 	}
@@ -208,3 +285,105 @@ async function enclosuresPrints(ctx) {
 	});
 	return 0;
 }
+
+function formatApp(a) {
+	const state = { connected: "signed in", connecting: "signing in", needs_login: "signed out", error: "error" }[
+		a.status
+	];
+	const lines = [`${a.id}  ${a.name}  [${state ?? a.status}]  ${a.login_url}`];
+	if (a.last_error) lines.push(`  ${a.last_error}`);
+	if (a.static_ip) lines.push(`  requests come from ${a.static_ip}`);
+	return lines.join("\n");
+}
+
+async function enclosuresApps(ctx) {
+	const { client, flags, io } = ctx;
+	const sub = ctx.positionals[0];
+	const positionals = ctx.positionals.slice(1);
+	if (sub === "list" || sub === "ls") {
+		const result = await client.callTool("list_app_connections", argsFromFlags(ARGS.list_app_connections, flags));
+		printResult(io, flags, result, (r) =>
+			r.connections?.length ? r.connections.map(formatApp).join("\n\n") : "No apps yet."
+		);
+		return 0;
+	}
+	if (sub === "show" || sub === "get") {
+		const result = await client.callTool(
+			"get_app_connection",
+			argsFromFlags(ARGS.get_app_connection, flags, positionals)
+		);
+		printResult(io, flags, result, (r) => formatApp(r.connection));
+		return 0;
+	}
+	if (sub === "connect") {
+		refuseUnknownFlags({ ...ctx, positionals }, ARGS.connect_app, []);
+		const result = await client.callTool("connect_app", argsFromFlags(ARGS.connect_app, flags, positionals));
+		ok(ctx, `Open this page and sign in (it expires about 10 minutes after it opens):\n${result.hosted_url}`);
+		printResult(io, flags, result, (r) => formatApp(r.connection));
+		return 0;
+	}
+	if (sub === "disconnect") {
+		const id = requirePositional(positionals, 0, "app-id");
+		if (!flags.yes) {
+			io.error(`Re-run with --yes to confirm: ${ctx.bin} enclosures apps disconnect ${id} --yes`);
+			return 1;
+		}
+		await client.callTool("disconnect_app", argsFromFlags(ARGS.disconnect_app, flags, positionals));
+		ok(ctx, "App removed. Enclosures that use it stop printing; prints already made stay.");
+		return 0;
+	}
+	throw new CliError(USAGE);
+}
+
+async function enclosuresStarters(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_generator_starters", argsFromFlags(ARGS.list_generator_starters, flags));
+	printResult(io, flags, result, (r) =>
+		(r.starters ?? [])
+			.map((s) => `${s.key}  ${s.name}: ${s.blurb}\n${s.steps.map((st) => `  ${st.n}. ${st.text}`).join("\n")}`)
+			.join("\n\n")
+	);
+	return 0;
+}
+
+async function enclosuresAddVersion(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.add_generator_version, ["script", "script-file", "step", "region-selector"]);
+	const result = await client.callTool(
+		"add_generator_version",
+		argsFromFlags(ARGS.add_generator_version, flags, positionals)
+	);
+	ok(ctx, `Added version ${result.version}. Prints keep running the chosen version until you approve this one.`);
+	printResult(io, flags, result, (r) => `version ${r.version}`);
+	return 0;
+}
+
+async function enclosuresApprove(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.approve_generator_version, []);
+	const result = await client.callTool(
+		"approve_generator_version",
+		argsFromFlags(ARGS.approve_generator_version, flags, positionals)
+	);
+	ok(ctx, `${result.generator?.name} now prints version ${result.generator?.current_version}.`);
+	printResult(io, flags, result, (r) => formatEnclosure(r.generator));
+	return 0;
+}
+
+async function enclosuresPrint(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.print_generator, []);
+	const result = await client.callTool("print_generator", argsFromFlags(ARGS.print_generator, flags, positionals));
+	printResult(io, flags, result, (r) => {
+		const skipped = [
+			r.recent && `${r.recent} already have a recent one`,
+			r.no_website && `${r.no_website} have no website`,
+			r.never_emailed && `${r.never_emailed} unsubscribed`,
+		].filter(Boolean);
+		const head = r.dry_run
+			? `Would print ${r.will_print} (version ${r.version}): about $${r.estimate.usd}, about ${r.estimate.minutes} minutes.`
+			: `Printing ${r.queued} (version ${r.version}). Watch: enclosures prints ${positionals[0]}`;
+		return skipped.length ? `${head}\n${skipped.join(". ")}. They're skipped.` : head;
+	});
+	return 0;
+}

package/lib/commands/site.mjs

@@ -373,13 +373,24 @@ async function siteMetrics(ctx) {
 	);
 	printResult(io, flags, result, (r) => {
 		const lines = [`${r.host}  ${r.window} (${r.range.start} to ${r.range.end})  source: ${r.source}`];
+		const counted = r.unit === "accesses";
 		if (r.source !== "lettervisit") lines.push(`  ${r.message}`);
 		for (const p of r.pages) {
-			const value = r.source === "lettervisit" ? p.accesses?.total : p.clicks;
-			const delta = r.source === "lettervisit" ? p.accesses_delta_pct : p.clicks_delta_pct;
-			const split = p.accesses
-				? `  (AI ${p.accesses.ai_agents}, crawlers ${p.accesses.search_crawlers}, people ${p.accesses.humans})`
+			const value = counted ? p.accesses?.total : p.clicks;
+			const delta = counted ? p.accesses_delta_pct : p.clicks_delta_pct;
+			const agents = p.accesses?.by_agent?.length
+				? ` [${p.accesses.by_agent
+						.slice(0, 3)
+						.map((a) => `${a.agent} ${a.requests}`)
+						.join(", ")}]`
 				: "";
+			const identified =
+				p.accesses?.identified_humans != null ? `, ${p.accesses.identified_humans} identified` : "";
+			const split = !p.accesses
+				? ""
+				: r.source === "visitors"
+					? `  (AI ${p.accesses.ai_agents}${agents}, people ${p.accesses.humans}${identified})`
+					: `  (AI ${p.accesses.ai_agents}, crawlers ${p.accesses.search_crawlers}, people ${p.accesses.humans})`;
 			const marks = p.indicators.map((i) => i.label).join(", ");
 			lines.push(
 				`  ${p.path}  ${value ?? "-"} ${r.unit ?? ""}${delta !== null ? ` ${delta > 0 ? "+" : ""}${delta}%` : ""}${split}${marks ? `  [${marks}]` : ""}`
@@ -464,7 +475,11 @@ async function siteFamilies(ctx) {
 			r.families
 				.map((f) => {
 					const members = f.members.filter((m) => m.included);
-					return `${f.id}  ${f.name}  [${f.status}]  ${members.length} members  (${f.source})`;
+					const line = `${f.id}  ${f.name}  [${f.status}]  ${members.length} members  (${f.source})`;
+					if (!f.coverage) return line;
+					const total = f.coverage.covered.length + f.coverage.missing.length;
+					const missing = f.coverage.missing.length ? `  missing: ${f.coverage.missing.join(", ")}` : "";
+					return `${line}  ${f.coverage.covered.length} of ${total} ${f.universe?.list ?? ""}${missing}`;
 				})
 				.join("\n") || "No families yet."
 	);

package/lib/commands/visits.mjs

@@ -9,6 +9,7 @@
 //   letterstory visits citations --since 30d
 //   letterstory visits export --since 30d --format csv
 //   letterstory visits sites
+//   letterstory visits pages --since 28d [--path '/docs/*'] [--agent openai-crawler]
 
 import { CliError } from "../client.mjs";
 import { flagStr, printResult, argsFromFlags } from "./shared.mjs";
@@ -27,6 +28,13 @@ export const ARGS = {
 		purpose: { flag: "purpose", enum: PURPOSES },
 	},
 	visitors_get_citations: { site_id: "site", days },
+	visitors_get_page_traffic: {
+		site_id: "site",
+		days,
+		path: "path",
+		agent: "agent",
+		limit: { flag: "limit", type: "num" },
+	},
 	visitors_compare_agents: {
 		site_id: "site",
 		a: { positional: 0, label: "agent-a (e.g. chatgpt)", required: true },
@@ -70,8 +78,10 @@ export async function cmdVisits(ctx) {
 			return visitsExport(rest);
 		case "sites":
 			return visitsSites(rest);
+		case "pages":
+			return visitsPages(rest);
 		default:
-			throw new CliError("Usage: visits [list|citations|compare|export|sites]");
+			throw new CliError("Usage: visits [list|citations|compare|export|sites|pages]");
 	}
 }
 
@@ -156,6 +166,29 @@ async function visitsExport(ctx) {
 	return 0;
 }
 
+async function visitsPages(ctx) {
+	const { flags, io } = ctx;
+	const result = await call(ctx, "visitors_get_page_traffic");
+	printResult(io, flags, result, (r) => {
+		if (r.unavailable) return r.message ?? `No page traffic (${r.unavailable}).`;
+		const t = r.totals;
+		const identified = t.identified_humans != null ? `, ${t.identified_humans} identified` : "";
+		const lines = [
+			`${r.host}  ${r.since} to ${r.until}: ${t.humans} people page views (${t.unique_visitors} visitors${identified}), ${t.ai_requests} AI agent requests`,
+		];
+		if (r.agents?.length) lines.push(`Agents: ${r.agents.map((a) => `${a.agent} ${a.requests}`).join(", ")}`);
+		if (!r.server_collected)
+			lines.push("No server snippet requests yet: AI agents need the server snippet (visits sites).");
+		lines.push("", "  people     AI  page");
+		for (const p of r.pages.slice(0, 50)) {
+			const who = p.people?.length ? `  (${p.people.map((x) => x.name ?? x.id).join(", ")})` : "";
+			lines.push(`  ${String(p.humans).padStart(6)} ${String(p.ai_requests).padStart(6)}  ${p.path}${who}`);
+		}
+		return lines.join("\n");
+	});
+	return 0;
+}
+
 async function visitsSites(ctx) {
 	const { flags, io } = ctx;
 	const result = await call(ctx, "visitors_list_sites");

package/lib/documents.mjs

@@ -87,6 +87,8 @@ export const JSON_ARG_FLAG_PAIRS = [
 	["value", "value-file"],
 	// A Vercel API token read verbatim, so it stays out of shell history (outbound.mjs mail vercel-key set).
 	["token", "token-file"],
+	// An enclosure version's script (enclosures.mjs add-version): code, read verbatim.
+	["script", "script-file"],
 ];
 
 /** Lower-case extension without the dot. */

package/package.json

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