@letterstory/cli 0.126.0 → 0.128.1

package/lib/cli.mjs

@@ -56,22 +56,36 @@ import {
 	cmdSite,
 	cmdEvals,
 	cmdOfferings,
+	cmdEnclosures,
 	cmdTargets,
 	cmdVisits,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.126.0";
+export const VERSION = "0.128.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. 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",
 	// shredder file / arena file: save the version as a candidate beside live.
 	"candidate",
+	// enclosures create/update: what it needs, and the AI-edited label.
+	"browser",
+	"image-model",
+	"record",
+	"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",
@@ -272,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.
@@ -350,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]
@@ -361,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 "…"]
@@ -431,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
@@ -524,6 +547,20 @@ Strategy & onboarding:
   directives apply <directive_id> --effect <id>...     Commit the levers you kept (or --reason to decline them all)
   directives off <directive_id> --reason <why>         Stop a live instruction; the reason is read back by the next proposal
 
+Enclosures (pictures, clips and sentences made for each prospect; each output is a Prospects column):
+  enclosures list                                      The org's enclosures with print counts
+  enclosures show <enclosure-id>                       One enclosure + its versions
+  enclosures create --name <n> --output key:shape:Label… [--instructions <text>] [--input website…] [--browser]
+                    [--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)
   offerings show <offering-id>                         One offering + its competitor overrides
@@ -886,6 +923,8 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
           | renewals [--days 90]
           | reach-outs [--day YYYY-MM-DD] [--fresh]   the day's reach-outs, N of 5 (#crm-reminders' count)
           | track-record [--since YYYY-MM-DD] | at-risk | expansion-signals
+          | collections [--org-ids a,b | --account-stages won,active]
+          | delivery-flags [--org-ids a,b | --account-stages won,active] [--include collections]
           | case <account-id> [--outcome <outcome-id>]
           | onboard <account-id> --domain acme.com [--name "Acme"] [--site "<direction>"]… [--sites N]
                    [--slack a@acme.com,b@acme.com] [--invite a@acme.com[:admin]]… [--no-checklist]
@@ -1355,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
@@ -1419,6 +1460,7 @@ const CLIENT_COMMANDS = {
 	strategy: cmdStrategy,
 	directives: cmdDirectives,
 	offerings: cmdOfferings,
+	enclosures: cmdEnclosures,
 	targets: cmdTargets,
 	probes: cmdProbes,
 	suggestions: cmdSuggestions,

package/lib/commands/admin.mjs

@@ -14,8 +14,8 @@
 //      The old names — evals, eval-add, eval-set, proposals, propose-eval, capture-eval, reject-eval — still work.)
 //   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|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 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|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)
@@ -3572,6 +3572,46 @@ async function cmdAdminCrm(ctx) {
 					: "(no next-product verdicts)"
 			);
 		}
+		case "collections": {
+			// admin crm collections [--org-ids a,b | --account-stages won,active] — what we publish for each client.
+			const params = new URLSearchParams(
+				compact({ org_ids: flagStr(flags["org-ids"]), account_stages: flagStr(flags["account-stages"]) })
+			);
+			return out(await staffRequest(ctx, "GET", `${CRM}/collections?${params}`), (r) =>
+				r.orgs.length
+					? r.orgs
+							.map(
+								(o) =>
+									`${o.orgName}  ${o.phantomCount} phantom · ${o.mainBlogCount} blog · ${o.postsLast30d} posts in 30d${o.internal.value ? `  (${o.internal.label ?? o.internal.source})` : ""}${o.issues.length ? `  ${o.issues.map((i) => i.message).join("; ")}` : ""}  ${o.orgId}`
+							)
+							.join("\n")
+					: "(no org with a collection in that scope)"
+			);
+		}
+		case "delivery-flags": {
+			// admin crm delivery-flags [--org-ids a,b | --account-stages won,active] [--include collections]
+			// — does what we spend on a client match what they pay? Findings per org, worst first.
+			const params = new URLSearchParams(
+				compact({
+					org_ids: flagStr(flags["org-ids"]),
+					account_stages: flagStr(flags["account-stages"]),
+					include: flagStr(flags.include),
+				})
+			);
+			return out(await staffRequest(ctx, "GET", `${CRM}/delivery-flags?${params}`), (r) => {
+				if (!r.accounts)
+					return "Billing cannot say who pays yet, so there are no flags (collections are in --json).";
+				const flagged = r.accounts.filter((a) => a.findings.length);
+				return flagged.length
+					? flagged
+							.map(
+								(a) =>
+									`${a.owedDelivery ? "owed  " : a.notPaying ? "unpaid" : "      "}  ${a.orgName}  ${a.findings.map((f) => f.message).join("; ")}  ${a.orgId}`
+							)
+							.join("\n")
+					: `(${r.accounts.length} org${r.accounts.length === 1 ? "" : "s"}, nothing flagged)`;
+			});
+		}
 		case "case": {
 			// admin crm case <account-id> [--outcome <id>] — the 90 days before an outcome, or before today.
 			if (!id) throw new CliError("Usage: admin crm case <account-id> [--outcome <outcome-id>]");
@@ -3650,7 +3690,7 @@ async function cmdAdminCrm(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: 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|case|onboard|onboarding|retry-onboarding|onboard-plan|payment-link … (see --help)"
+				"Usage: 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 … (see --help)"
 			);
 	}
 }
@@ -4224,6 +4264,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);
@@ -4298,7 +4402,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

@@ -0,0 +1,389 @@
+// `enclosures` — pictures, clips and sentences made for each prospect (generated
+// prospect columns). Each output IS a Prospects column that sequence emails read as
+// {{custom:<key>}}. Thin wrappers over the MCP tools, which call the same store functions
+// the app's /api/generators routes do.
+
+import { CliError } from "../client.mjs";
+import {
+	flagStr,
+	flagNum,
+	flagList,
+	requirePositional,
+	printResult,
+	argsFromFlags,
+	refuseUnknownFlags,
+	readTextInput,
+	ok,
+} from "./shared.mjs";
+
+const SHAPES = ["text", "image", "animation", "video"];
+
+// `--output key:shape:Label` (repeatable), e.g. --output audit_shot:image:"Site audit".
+function readOutputs(flags) {
+	const raw = flagList(flags.output);
+	if (!raw.length) return undefined;
+	return raw.map((entry) => {
+		const [key, shape, ...label] = entry.split(":");
+		if (!key || !SHAPES.includes(shape) || !label.length) {
+			throw new CliError(
+				`--output takes key:shape:Label with shape one of ${SHAPES.join(", ")} (got "${entry}")`
+			);
+		}
+		return { key, shape, label: label.join(":") };
+	});
+}
+
+// --browser, --login <app-connection-id>, --stealth, --record, --region, --image-model, --tool <op>…
+function readNeeds(flags) {
+	const browser = {};
+	if (flagStr(flags.login)) browser.login = flagStr(flags.login);
+	if (flags.stealth === true) browser.stealth = true;
+	if (flags.record === true) browser.record = true;
+	if (flagStr(flags.region)) browser.region = flagStr(flags.region);
+	const needs = {};
+	if (flags.browser === true || Object.keys(browser).length) needs.browser = browser;
+	if (flags["image-model"] === true) needs.image_model = true;
+	const tools = flagList(flags.tool);
+	if (tools.length) needs.tools = tools;
+	return Object.keys(needs).length ? needs : undefined;
+}
+
+const inputs = (flags) => {
+	const v = flagList(flags.input);
+	return v.length ? v : undefined;
+};
+
+const fields = {
+	name: "name",
+	instructions: { value: (flags) => readTextInput(flags, "instructions", "instructions-file") },
+	inputs: { value: inputs },
+	outputs: { value: readOutputs },
+	needs: { value: readNeeds },
+	cache_scope: { flag: "share", enum: ["prospect", "company_domain"] },
+	freshness_days: { flag: "fresh-days", type: "num" },
+	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",
+	"output",
+	"browser",
+	"login",
+	"stealth",
+	"record",
+	"region",
+	"image-model",
+	"tool",
+	"cta-label",
+	"cta-url",
+	"no-cta",
+];
+
+// 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_generators: {},
+	get_generator: {
+		generator_id: { positional: 0, label: "enclosure-id", required: true },
+	},
+	create_generator: {
+		key: "key",
+		starter: "starter",
+		...fields,
+	},
+	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"] },
+		limit: { flag: "limit", type: "num" },
+	},
+};
+
+const USAGE = `Usage: enclosures <list|show|create|update|prints>
+  enclosures list
+  enclosures show <enclosure-id>
+  enclosures create --name <n> --output key:shape:Label… [--key <k>] [--instructions <text>|--instructions-file <path>]
+                    [--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 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];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return enclosuresList(rest);
+		case "show":
+		case "get":
+			return enclosuresShow(rest);
+		case "create":
+			return enclosuresCreate(rest);
+		case "update":
+			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);
+	}
+}
+
+function formatEnclosure(g) {
+	const c = g.counts ?? {};
+	const lines = [
+		`${g.id}  ${g.key}  ${g.name}  [${g.status}${g.current_version ? `, version ${g.current_version}` : ""}]`,
+	];
+	lines.push(`  columns: ${(g.outputs ?? []).map((o) => `${o.label} {{custom:${o.key}}} (${o.shape})`).join(", ")}`);
+	if (g.inputs?.length) lines.push(`  reads: ${g.inputs.join(", ")}`);
+	lines.push(
+		`  prints: ${c.done ?? 0} ready, ${(c.queued ?? 0) + (c.running ?? 0)} making, ${c.no_fit ?? 0} no fit, ${c.failed ?? 0} failed`
+	);
+	return lines.join("\n");
+}
+
+async function enclosuresList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_generators", argsFromFlags(ARGS.list_generators, flags));
+	printResult(io, flags, result, (r) => {
+		const all = r.generators ?? [];
+		if (!all.length) return "No enclosures yet.";
+		return all.map(formatEnclosure).join("\n\n");
+	});
+	return 0;
+}
+
+async function enclosuresShow(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	const result = await client.callTool("get_generator", argsFromFlags(ARGS.get_generator, flags, positionals));
+	printResult(io, flags, result, (r) => {
+		const lines = [formatEnclosure(r.generator)];
+		for (const v of r.generator.versions ?? []) {
+			lines.push(
+				`  version ${v.version} (${v.author}): ${v.steps} steps${v.change_summary ? `, ${v.change_summary}` : ""}`
+			);
+		}
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function enclosuresCreate(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.create_generator, FIELD_FLAGS);
+	const result = await client.callTool("create_generator", argsFromFlags(ARGS.create_generator, flags, positionals));
+	ok(ctx, `Created ${result.generator?.name} (${result.generator?.id}).`);
+	printResult(io, flags, result, (r) => formatEnclosure(r.generator));
+	return 0;
+}
+
+async function enclosuresUpdate(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.update_generator, FIELD_FLAGS);
+	const args = argsFromFlags(ARGS.update_generator, flags, positionals);
+	if (Object.keys(args).length === 1) throw new CliError("Nothing to update. Pass a field flag.");
+	const result = await client.callTool("update_generator", args);
+	ok(ctx, `Updated ${result.generator?.name}.`);
+	printResult(io, flags, result, (r) => formatEnclosure(r.generator));
+	return 0;
+}
+
+async function enclosuresPrints(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	requirePositional(positionals, 0, "enclosure-id");
+	if (flags.limit !== undefined) flagNum(flags.limit);
+	const result = await client.callTool("list_generations", argsFromFlags(ARGS.list_generations, flags, positionals));
+	printResult(io, flags, result, (r) => {
+		const all = r.generations ?? [];
+		if (!all.length) return "No prints yet.";
+		return all
+			.map((g) => `${g.status.padEnd(8)} ${g.prospect?.email ?? g.prospect_id}${g.error ? `  ${g.error}` : ""}`)
+			.join("\n");
+	});
+	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/commands.mjs

@@ -38,6 +38,7 @@ export * from "./commands/enhance.mjs";
 export * from "./commands/landings.mjs";
 export * from "./commands/outbound.mjs";
 export * from "./commands/offerings.mjs";
+export * from "./commands/enclosures.mjs";
 export * from "./commands/targets.mjs";
 export * from "./commands/admin.mjs";
 export * from "./commands/feedback.mjs";

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.0",
+	"version": "0.128.1",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",