@letterstory/cli 0.100.4 → 0.101.1

package/README.md

@@ -120,6 +120,7 @@ letterstory phantom config <phantom-id> --configure --dry-run   # what re-config
 letterstory phantom rebuild <phantom-id>                        # after publishing outside a collection run
 letterstory phantom diagnostics <phantom-id>                    # why is my site empty?
 letterstory phantom balance                                     # sites live / granted, and the cadence cap
+letterstory phantom spread-looks [--apply]                      # a different look per site; dry run unless --apply
 letterstory phantom delete <phantom-id> --yes
 ```
 

package/lib/cli.mjs

@@ -52,6 +52,7 @@ import {
 	cmdAdmin,
 	cmdFeedback,
 	cmdRepo,
+	cmdSite,
 	cmdEvals,
 	cmdOfferings,
 	cmdTargets,
@@ -59,13 +60,17 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.100.4";
+export const VERSION = "0.101.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([
 	"json",
+	// site tree: include children a fold-by-default family would hide.
+	"unfold",
+	// site map: do not start an audit for a host that has none.
+	"no-audit",
 	// lede library update / lede proposals accept: clear or drop the line's condition.
 	"no-condition",
 	// prospects update: clear the HeyReach LinkedIn-reply marker.
@@ -77,6 +82,7 @@ export const BOOLEAN_FLAGS = new Set([
 	"no-control",
 	"own-beat",
 	"refresh",
+	"preview",
 	"accept",
 	"help",
 	"version",
@@ -89,6 +95,8 @@ export const BOOLEAN_FLAGS = new Set([
 	"force",
 	"buy",
 	"rebuild",
+	// phantom spread-looks --apply
+	"apply",
 	"print-key",
 	"stdin",
 	// `authors generate <id> --with-bios`.
@@ -326,6 +334,7 @@ Phantomstory (a collection Letterstory hosts as an independent publication):
                               [--configure [--dry-run]]
                                                        The site's file joined to its collection's
   phantom rebuild <phantom-id> · phantom diagnostics <phantom-id> · phantom balance
+  phantom spread-looks [--apply]                         Give each live site a different look (dry run by default)
   phantom domain check <domain> · phantom domain buy <phantom-id> <domain> --yes
   phantom domain connect <phantom-id> <domain>
   phantom delete <phantom-id> --yes
@@ -1116,14 +1125,31 @@ Insights:
   insights access [--period 14d|30d|90d] [--collection <uuid>]
                                                        Page access: who's reading your phantom sites
 
+The Site (one model of your whole marketing site, keyed by host and path):
+  site list                                            Mapped hosts, and hosts you already have elsewhere
+  site map <host> [--sitemap <url>] [--max-pages <n>] [--no-audit]
+                                                       Map a host from its sitemap; starts an audit if it has none
+  site tree <host> [path] [--depth <n>] [--unfold]     The tree one folder at a time, one item per node
+  site page <host> <path>                              One page: facts, bindings, raw URLs, open items
+  site observations <host> [path] [--state open|dismissed|resolved] [--tone risk|warn|info]
+  site observe <host> [path] [--max-pages <n>]         Jev pass: meta accuracy, title, outdated
+  site dismiss <host> <observation-id> --reason <why> [--decision dismiss|reopen]
+  site families <host> [path] [--state suggested|tracked|dismissed]
+  site decide-family <family-id> [--decision tracked|dismissed] [--reason <why>] [--name <n>]
+                     [--include <path>]... [--exclude <path>]...
+  site proposals <host> [path] [--state proposed|accepted|shipped|failed|dismissed]
+  site propose <host> [path] --tool <tool> --input '<json>'|--input-file <p> --label <text> [--why <text>]
+                     [--observation <id>]...           Propose a registry tool call; input is validated now
+  site decide <proposal-id> --decision accept|dismiss [--reason <why>]
+
 Repo changes (Claude Code edits your repo in a sandbox; the Letterstory GitHub App opens a PR):
   repo repos                                           Repos the Letterstory GitHub App can reach
   repo branches --repo owner/name                      Branches a change can start from (default first)
   repo start --repo <owner/name> --instructions <text>|--instructions-file <path|->
-             [--branch <base>] [--attach <path>]... [--attach-url <name>=<https url>]... [--wait]
+             [--branch <base>] [--attach <path>]... [--attach-url <name>=<https url>]... [--preview] [--wait]
                                                        Start a change (attached files go to the sandbox);
                                                        --wait follows it to the PR
-  repo fix-audit --issue <issue-type> [--audit <id>] [--branch <base>] [--wait]
+  repo fix-audit --issue <issue-type> [--audit <id>] [--branch <base>] [--preview] [--wait]
                                                        One PR fixing a site-audit issue on every affected page,
                                                        in the repo verified to build the site
   repo sites [--detect [--force]]                      Which website each repo builds, and the evidence
@@ -1132,7 +1158,8 @@ Repo changes (Claude Code edits your repo in a sandbox; the Letterstory GitHub A
   repo reset-site --repo <owner/name> --site <host>    Back to automatic detection
   repo status <run-id>                                 Phase, spend, PR link and Claude's summary
   repo list [--status running|succeeded|no_changes|failed|cancelled] [--limit n] [--audit <id>]
-  repo cancel <run-id>                                 Stop it and delete the sandbox; no PR
+  repo publish <run-id>                                Make PR on a preview in review
+  repo cancel <run-id>                                 Stop it and delete the sandbox; no PR (Discard a preview)
 
 Feedback (tell us what's broken, missing, unclear, or wanted):
   feedback submit --category bug|missing_feature|unclear|feature_request|praise|other
@@ -1239,6 +1266,7 @@ const CLIENT_COMMANDS = {
 	mailers: cmdMailers,
 	feedback: cmdFeedback,
 	repo: cmdRepo,
+	site: cmdSite,
 	evals: cmdEvals,
 	visits: cmdVisits,
 	// Platform-scoped (staff key) — the only commands that act BEFORE an org exists.

package/lib/commands/admin.mjs

@@ -2839,6 +2839,8 @@ async function cmdAdminCrmCapture(ctx, paths) {
  *                [--ask …] [--linkedin …] [--email …] [--lookup]
  *   outreach lookup "Jane Doe from Acme" [shot.png …]  prefilled from the web; writes nothing
  *   outreach relookup [--missing linkedin]           the web lookup again for whoever lacks it
+ *   outreach drafts [--kind ask|thanks] [--owner …]  drafts or thank-yous for everyone without one
+ *   outreach engagement --outcome upvoted [shot.png] who upvoted, matched by exact name
  *   outreach customers [--dry-run]                   every customer's primary contact onto the list
  *   outreach catch-up [--dry-run]                    handle #launch-outreach posts the bot missed
  *   outreach set <id> [--reached|--not-reached] [--response "…" --tone positive]
@@ -2968,6 +2970,67 @@ async function cmdAdminCrmOutreach(ctx, args) {
 			}
 			return io.log(`looked up ${total}`);
 		}
+		case "drafts": {
+			// admin crm outreach drafts [--kind ask|thanks] [--owner Neha] — write drafts (or
+			// thank-yous) for everyone without one, in rounds; a person's own text is kept.
+			const kind = flags.kind === undefined ? "ask" : flagStr(flags.kind);
+			if (!["ask", "thanks"].includes(kind))
+				throw new CliError("Usage: admin crm outreach drafts [--kind ask|thanks] [--owner …] [--list …]");
+			const owner = flagStr(flags.owner)?.toLowerCase();
+			const r0 = await staffRequest(
+				ctx,
+				"GET",
+				`${CRM}/outreach${list ? `?list=${encodeURIComponent(list)}` : ""}`
+			);
+			const helped = ["shared", "upvoted", "commented", "introduced"];
+			let pending = r0.people
+				.filter((p) => !owner || (p.ownerName ?? "").toLowerCase().includes(owner))
+				.filter((p) => !p.noContactReason)
+				.filter((p) =>
+					kind === "thanks" ? !p.thanksMessage && p.outcomes.some((o) => helped.includes(o)) : !p.draftMessage
+				)
+				.map((p) => p.id);
+			let written = 0;
+			for (let i = 0; i < 60 && pending.length; i++) {
+				const r = await staffPost(
+					ctx,
+					`${CRM}/outreach/drafts`,
+					compact({ list, kind, ids: pending.slice(0, 500) })
+				);
+				for (const p of r.written) io.log(`wrote ${p.name}`);
+				const done = new Set([...r.written.map((p) => p.id), ...r.skipped.map((x) => x.id)]);
+				written += r.written.length;
+				const before = pending.length;
+				pending = pending.filter((id) => !done.has(id));
+				if (pending.length === before) break;
+			}
+			return io.log(`wrote ${written} ${kind === "thanks" ? "thank-yous" : "drafts"}`);
+		}
+		case "engagement": {
+			// admin crm outreach engagement --outcome upvoted [shot.png …] [--text "Jane Doe, Tom Ray"]
+			// — who upvoted / commented / shared, matched to the list by exact full name.
+			const outcome = flagStr(flags.outcome) ?? "upvoted";
+			const images = rest
+				.filter((a) => CRM_CAPTURE_TYPES[a.split(".").pop()?.toLowerCase() ?? ""])
+				.map((path) => ({
+					media_type: CRM_CAPTURE_TYPES[path.split(".").pop().toLowerCase()],
+					data: readFileSync(path).toString("base64"),
+				}));
+			const text = flagStr(flags.text);
+			if (!images.length && !text)
+				throw new CliError(
+					'Usage: admin crm outreach engagement --outcome upvoted [shot.png …] [--text "Jane Doe, Tom Ray"]'
+				);
+			const r = await staffPost(
+				ctx,
+				`${CRM}/outreach/engagement`,
+				compact({ list, outcome, text, images: images.length ? images : undefined })
+			);
+			if (json) return printResult(io, flags, r);
+			io.log(`marked ${r.matched.length}: ${r.matched.map((p) => p.name).join(", ") || "nobody"}`);
+			if (r.unmatched.length) io.log(`not on the list: ${r.unmatched.join(", ")}`);
+			return;
+		}
 		case "customers": {
 			// admin crm outreach customers [--dry-run] — every customer's primary contact onto the list.
 			const r = await staffPost(
@@ -3012,7 +3075,7 @@ async function cmdAdminCrmOutreach(ctx, args) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin crm outreach [list|add|lookup|set|relookup|customers|catch-up] … (see --help)"
+				"Usage: admin crm outreach [list|add|lookup|set|relookup|drafts|engagement|customers|catch-up] … (see --help)"
 			);
 	}
 }

package/lib/commands/phantom.mjs

@@ -104,6 +104,7 @@ export const ARGS = {
 	rebuild_phantom: { phantom_id: { positional: 0, label: "phantom-id", required: true } },
 	get_phantom_diagnostics: { phantom_id: { positional: 0, label: "phantom-id", required: true } },
 	get_phantom_balance: {},
+	spread_phantom_looks: { apply: { flag: "apply", type: "bool" } },
 	check_domain: {
 		domain: { value: (flags, positionals) => stripScheme(requirePositional(positionals, 0, "domain")) },
 	},
@@ -149,11 +150,13 @@ export async function cmdPhantom(ctx) {
 			return call(rest, "get_phantom_diagnostics");
 		case "balance":
 			return call(rest, "get_phantom_balance");
+		case "spread-looks":
+			return call(rest, "spread_phantom_looks");
 		case "domain":
 			return phantomDomain(rest);
 		default:
 			throw new CliError(
-				`Unknown phantom subcommand: ${sub ?? "(none)"}. Try: list, get, new, config, visitors, delete, rebuild, diagnostics, balance, domain`
+				`Unknown phantom subcommand: ${sub ?? "(none)"}. Try: list, get, new, config, visitors, delete, rebuild, diagnostics, balance, spread-looks, domain`
 			);
 	}
 }

package/lib/commands/repo.mjs

@@ -2,6 +2,7 @@
 // pull request by the Letterstory GitHub App (src/lib/repo-changes). One subcommand per tool:
 //   repo start   → start_repo_change     repo status → get_repo_change
 //   repo list    → list_repo_changes     repo cancel → cancel_repo_change
+//   repo publish → publish_repo_change (Make PR on a preview)
 //   repo repos   → list_github_app_repos  repo branches → list_repo_branches
 
 import { readFileSync } from "node:fs";
@@ -36,6 +37,7 @@ const ARGS = {
 		instructions: { value: (flags) => readTextInput(flags, "instructions", "instructions-file") },
 		// --attach <path> (uploaded first) and --attach-url <name>=<https url>, both repeatable.
 		files: { value: (_flags, _positionals, extra) => (extra.files?.length ? extra.files : undefined) },
+		preview: { flag: "preview", type: "bool" },
 	},
 	create_repo_change_upload: { file_names: { internal: "the basenames of the --attach files" } },
 	list_repo_sites: {},
@@ -55,9 +57,11 @@ const ARGS = {
 		issue_type: { flag: "issue", required: true },
 		audit_id: "audit",
 		base_branch: "branch",
+		preview: { flag: "preview", type: "bool" },
 	},
 	get_repo_change: { run_id: { positional: 0, required: true, label: "run-id" } },
 	cancel_repo_change: { run_id: { positional: 0, required: true, label: "run-id" } },
+	publish_repo_change: { run_id: { positional: 0, required: true, label: "run-id" } },
 	list_repo_changes: {
 		status: { flag: "status", enum: ["running", "succeeded", "no_changes", "failed", "cancelled"] },
 		limit: { flag: "limit", type: "num" },
@@ -76,6 +80,9 @@ function describe(run) {
 	const lines = [
 		`${run.id}  ${run.repo}@${run.baseBranch}  ${run.status} (${run.phase})  $${run.costUsd.toFixed(2)}`,
 	];
+	if (run.preview?.url) lines.push(`  Preview: ${run.preview.url}`);
+	if (run.preview?.state === "failed") lines.push(`  Preview failed: ${run.preview.detail ?? ""}`);
+	if (run.phase === "review") lines.push(`  Make PR: letterstory repo publish ${run.id}`);
 	if (run.prUrl) lines.push(`  PR: ${run.prUrl} (${run.prState ?? "state unknown"})`);
 	if (run.errorCode) lines.push(`  Error (${run.errorCode}): ${run.errorDetail ?? ""}`);
 	if (run.summary) lines.push(...run.summary.split("\n").map((l) => `  ${l}`));
@@ -102,13 +109,15 @@ export async function cmdRepo(ctx) {
 			return repoList(rest);
 		case "cancel":
 			return repoCancel(rest);
+		case "publish":
+			return repoPublish(rest);
 		case "repos":
 			return repoRepos(rest);
 		case "branches":
 			return repoBranches(rest);
 		default:
 			throw new CliError(
-				`Unknown repo subcommand: ${sub ?? "(none)"}. Try: start, fix-audit, sites, set-site, reset-site, status, list, cancel, repos, branches`
+				`Unknown repo subcommand: ${sub ?? "(none)"}. Try: start, fix-audit, sites, set-site, reset-site, status, list, publish, cancel, repos, branches`
 			);
 	}
 }
@@ -162,6 +171,7 @@ async function repoStart(ctx) {
 		"instructions-file",
 		"attach",
 		"attach-url",
+		"preview",
 		"wait",
 	]);
 	const files = [
@@ -183,7 +193,7 @@ async function repoStart(ctx) {
 		async () => {
 			const polled = await client.callTool("get_repo_change", { run_id: started.run.id });
 			ok(ctx, `… ${polled.run.status} (${polled.run.phase})`);
-			return { done: TERMINAL.has(polled.run.status), value: polled.run };
+			return { done: settledFor(polled.run), value: polled.run };
 		},
 		{ intervalMs: 30000, ceilingMs: 60 * 60 * 1000 }
 	);
@@ -192,6 +202,11 @@ async function repoStart(ctx) {
 	return value.status === "failed" ? 1 : 0;
 }
 
+/** --wait stops at a terminal state, or at review: a preview waits on a person, not on time. */
+function settledFor(run) {
+	return TERMINAL.has(run.status) || run.phase === "review";
+}
+
 async function followRun(ctx, run) {
 	const { client, flags, io } = ctx;
 	const { settled, value } = await followJob(
@@ -199,7 +214,7 @@ async function followRun(ctx, run) {
 		async () => {
 			const polled = await client.callTool("get_repo_change", { run_id: run.id });
 			ok(ctx, `… ${polled.run.status} (${polled.run.phase})`);
-			return { done: TERMINAL.has(polled.run.status), value: polled.run };
+			return { done: settledFor(polled.run), value: polled.run };
 		},
 		{ intervalMs: 30000, ceilingMs: 60 * 60 * 1000 }
 	);
@@ -211,7 +226,7 @@ async function followRun(ctx, run) {
 /** `repo fix-audit --issue <type> [--audit <id>] [--wait]`: one audit issue → one PR, in the repo verified to build the site. */
 async function repoFixAudit(ctx) {
 	const { client, flags, io } = ctx;
-	refuseUnknownFlags(ctx, {}, ["issue", "audit", "branch", "wait"]);
+	refuseUnknownFlags(ctx, {}, ["issue", "audit", "branch", "preview", "wait"]);
 	const result = await client.callTool(
 		"fix_audit_issue",
 		argsFromFlags(ARGS.fix_audit_issue, flags, ctx.positionals)
@@ -297,6 +312,18 @@ async function repoCancel(ctx) {
 	return 0;
 }
 
+/** `repo publish <run-id>`: Make PR on a preview in review. */
+async function repoPublish(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool(
+		"publish_repo_change",
+		argsFromFlags(ARGS.publish_repo_change, flags, ctx.positionals)
+	);
+	ok(ctx, result.message);
+	printResult(io, flags, result.run, describe);
+	return 0;
+}
+
 async function repoRepos(ctx) {
 	const { client, flags, io } = ctx;
 	const result = await client.callTool("list_github_app_repos", argsFromFlags(ARGS.list_github_app_repos, flags));

package/lib/commands/site.mjs

@@ -0,0 +1,341 @@
+// `site` — The Site: one model of the org's whole marketing site keyed by host and path
+// (src/lib/site). One subcommand per tool:
+//   site list                → list_sites               site map <host>            → map_site
+//   site tree <host> [path]  → get_site_tree            site page <host> <path>    → get_site_page
+//   site observations <host> → list_site_observations   site observe <host>        → observe_site
+//   site dismiss <host> <id> → dismiss_site_observation
+//   site families <host>     → list_site_families       site decide-family <id>    → decide_site_family
+//   site proposals <host>    → list_site_proposals      site propose <host>        → create_site_proposal
+//   site decide <proposal>   → decide_site_proposal
+
+import { CliError } from "../client.mjs";
+import { argsFromFlags, flagList, flagStr, ok, printResult, readTextInput, refuseUnknownFlags } from "./shared.mjs";
+
+/** --include <path>… / --exclude <path>… (+ --reason) → decide_site_family members. */
+function familyMembers(flags) {
+	const include = flagList(flags.include).map((path) => ({ path, included: true }));
+	const reason = flagStr(flags.reason);
+	const exclude = flagList(flags.exclude).map((path) => ({ path, included: false, reason }));
+	const members = [...include, ...exclude];
+	return members.length ? members : undefined;
+}
+
+/** --input '<json>' or --input-file <path|-> → the proposal's tool input. */
+function proposalInput(flags) {
+	const raw = readTextInput(flags, "input", "input-file");
+	if (raw === undefined) return undefined;
+	try {
+		const parsed = JSON.parse(raw);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("not an object");
+		return parsed;
+	} catch (err) {
+		throw new CliError(`--input must be a JSON object: ${err.message}`);
+	}
+}
+
+const ARGS = {
+	list_sites: {},
+	map_site: {
+		host: { positional: 0, label: "host" },
+		url: "url",
+		sitemap_url: "sitemap",
+		max_pages: { flag: "max-pages", type: "num" },
+		audit: { flag: "no-audit", type: "bool", invert: true },
+	},
+	get_site_tree: {
+		host: { positional: 0, required: true, label: "host" },
+		path: { positional: 1, label: "path" },
+		depth: { flag: "depth", type: "num" },
+		unfold: { flag: "unfold", type: "bool" },
+	},
+	get_site_page: {
+		host: { positional: 0, required: true, label: "host" },
+		path: { positional: 1, required: true, label: "path" },
+	},
+	list_site_observations: {
+		host: { positional: 0, required: true, label: "host" },
+		path: { positional: 1, label: "path" },
+		status: { flag: "state", enum: ["open", "dismissed", "resolved"] },
+		tone: { flag: "tone", enum: ["ok", "warn", "risk", "info"] },
+		source: "source",
+		limit: { flag: "limit", type: "num" },
+	},
+	observe_site: {
+		host: { positional: 0, required: true, label: "host" },
+		path: { positional: 1, label: "path" },
+		max_pages: { flag: "max-pages", type: "num" },
+	},
+	dismiss_site_observation: {
+		host: { positional: 0, required: true, label: "host" },
+		observation_id: { positional: 1, required: true, label: "observation-id" },
+		decision: { flag: "decision", enum: ["dismiss", "reopen"] },
+		reason: "reason",
+	},
+	list_site_families: {
+		host: { positional: 0, required: true, label: "host" },
+		status: { flag: "state", enum: ["suggested", "tracked", "dismissed"] },
+		path: { positional: 1, label: "path" },
+	},
+	decide_site_family: {
+		family_id: { positional: 0, required: true, label: "family-id" },
+		decision: { flag: "decision", enum: ["tracked", "dismissed", "suggested"] },
+		reason: "reason",
+		name: "name",
+		members: { value: (flags) => familyMembers(flags) },
+	},
+	list_site_proposals: {
+		host: { positional: 0, required: true, label: "host" },
+		path: { positional: 1, label: "path" },
+		status: { flag: "state", enum: ["proposed", "accepted", "shipped", "failed", "dismissed"] },
+		limit: { flag: "limit", type: "num" },
+	},
+	create_site_proposal: {
+		host: { positional: 0, required: true, label: "host" },
+		path: { positional: 1, label: "path" },
+		tool: { flag: "tool", required: true },
+		input: { value: (flags) => proposalInput(flags) },
+		label: { flag: "label", required: true },
+		rationale: "why",
+		observation_ids: { flag: "observation", type: "list" },
+	},
+	decide_site_proposal: {
+		proposal_id: { positional: 0, required: true, label: "proposal-id" },
+		decision: { flag: "decision", required: true, enum: ["accept", "dismiss"] },
+		reason: "reason",
+	},
+};
+
+export async function cmdSite(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+			return siteList(rest);
+		case "map":
+			return siteMap(rest);
+		case "tree":
+			return siteTree(rest);
+		case "page":
+			return sitePage(rest);
+		case "observations":
+			return siteObservations(rest);
+		case "observe":
+			return siteObserve(rest);
+		case "dismiss":
+			return siteDismiss(rest);
+		case "families":
+			return siteFamilies(rest);
+		case "decide-family":
+			return siteDecideFamily(rest);
+		case "proposals":
+			return siteProposals(rest);
+		case "propose":
+			return sitePropose(rest);
+		case "decide":
+			return siteDecide(rest);
+		default:
+			throw new CliError(
+				`Unknown site subcommand: ${sub ?? "(none)"}. Try: list, map, tree, page, observations, observe, dismiss, families, decide-family, proposals, propose, decide`
+			);
+	}
+}
+
+const GLYPH = { risk: "!!", warn: "!", info: "·", ok: " " };
+
+function describeNode(node, indent = "") {
+	const glyph = node.item ? (GLYPH[node.item.tone] ?? "·") : " ";
+	const line = node.item
+		? `${node.item.summary}${node.more ? ` and ${node.more} more` : ""}${node.item.action ? ` → ${node.item.action.label}` : ""}`
+		: "";
+	const counts = node.hasChildren ? ` (${node.rollup.pages} pages)` : "";
+	const out = [`${indent}${glyph.padEnd(2)} ${node.name}${counts}${line ? `  ${line}` : ""}`];
+	for (const child of node.children ?? []) out.push(describeNode(child, `${indent}  `));
+	return out.join("\n");
+}
+
+async function siteList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_sites", argsFromFlags(ARGS.list_sites, flags, ctx.positionals));
+	printResult(io, flags, result, (r) => {
+		const lines = r.sites.map(
+			(s) =>
+				`${s.host}  ${s.mapStatus}  ${s.pagesTotal} pages${s.mapTruncated ? " (truncated)" : ""}${s.mappedAt ? `  mapped ${s.mappedAt.slice(0, 10)}` : ""}`
+		);
+		if (r.suggestions.length) {
+			lines.push("Not yet mapped:");
+			for (const s of r.suggestions) lines.push(`  ${s.host}  (${s.from.join(", ")})`);
+		}
+		return lines.join("\n") || "No sites yet. Map one with: letterstory site map <host>";
+	});
+	return 0;
+}
+
+async function siteMap(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.map_site);
+	const args = argsFromFlags(ARGS.map_site, flags, ctx.positionals);
+	if (!args.host && !args.url && !args.sitemap_url) throw new CliError("Give a <host>, --url or --sitemap");
+	const result = await client.callTool("map_site", args);
+	ok(ctx, result.message);
+	printResult(
+		io,
+		flags,
+		result.summary,
+		(s) =>
+			`${s.pages} pages, ${s.fromAuditOnly} crawl-only, ${s.aliases} aliases, ${s.gone} gone; families +${s.families.created}`
+	);
+	return 0;
+}
+
+async function siteTree(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.get_site_tree);
+	const result = await client.callTool("get_site_tree", argsFromFlags(ARGS.get_site_tree, flags, ctx.positionals));
+	printResult(io, flags, result, (r) => describeNode(r.root));
+	return 0;
+}
+
+async function sitePage(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.get_site_page);
+	const result = await client.callTool("get_site_page", argsFromFlags(ARGS.get_site_page, flags, ctx.positionals));
+	printResult(io, flags, result.page, (p) => {
+		const lines = [describeNode(p.node)];
+		for (const item of p.items)
+			lines.push(
+				`  ${GLYPH[item.tone]} ${item.summary}${item.action ? ` → ${item.action.label}` : ""}  [${item.id}]`
+			);
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function siteObservations(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.list_site_observations);
+	const result = await client.callTool(
+		"list_site_observations",
+		argsFromFlags(ARGS.list_site_observations, flags, ctx.positionals)
+	);
+	printResult(
+		io,
+		flags,
+		result,
+		(r) =>
+			r.observations
+				.map((o) => `${GLYPH[o.tone].padEnd(2)} ${o.path}  ${o.summary}  [${o.status}] ${o.id}`)
+				.join("\n") || "Nothing noticed."
+	);
+	return 0;
+}
+
+async function siteObserve(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.observe_site);
+	const result = await client.callTool("observe_site", argsFromFlags(ARGS.observe_site, flags, ctx.positionals));
+	ok(ctx, result.message);
+	printResult(io, flags, result.summary, () => "");
+	return 0;
+}
+
+async function siteDismiss(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.dismiss_site_observation);
+	const result = await client.callTool(
+		"dismiss_site_observation",
+		argsFromFlags(ARGS.dismiss_site_observation, flags, ctx.positionals)
+	);
+	printResult(
+		io,
+		flags,
+		result.observation,
+		(o) => `${o.path}  ${o.summary}  [${o.status}${o.statusReason ? `: ${o.statusReason}` : ""}]`
+	);
+	return 0;
+}
+
+async function siteFamilies(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.list_site_families);
+	const result = await client.callTool(
+		"list_site_families",
+		argsFromFlags(ARGS.list_site_families, flags, ctx.positionals)
+	);
+	printResult(
+		io,
+		flags,
+		result,
+		(r) =>
+			r.families
+				.map((f) => {
+					const members = f.members.filter((m) => m.included);
+					return `${f.id}  ${f.name}  [${f.status}]  ${members.length} members  (${f.source})`;
+				})
+				.join("\n") || "No families yet."
+	);
+	return 0;
+}
+
+async function siteDecideFamily(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.decide_site_family, ["include", "exclude"]);
+	const result = await client.callTool(
+		"decide_site_family",
+		argsFromFlags(ARGS.decide_site_family, flags, ctx.positionals)
+	);
+	printResult(
+		io,
+		flags,
+		result.family,
+		(f) => `${f.name}  [${f.status}]  ${f.members.filter((m) => m.included).length} members`
+	);
+	return 0;
+}
+
+async function siteProposals(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.list_site_proposals);
+	const result = await client.callTool(
+		"list_site_proposals",
+		argsFromFlags(ARGS.list_site_proposals, flags, ctx.positionals)
+	);
+	printResult(
+		io,
+		flags,
+		result,
+		(r) =>
+			r.proposals
+				.map((p) => `${p.id}  ${p.path}  ${p.label}  (${p.tool} via ${p.channel})  [${p.status}]`)
+				.join("\n") || "No proposals yet."
+	);
+	return 0;
+}
+
+async function sitePropose(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.create_site_proposal, ["input", "input-file"]);
+	const args = argsFromFlags(ARGS.create_site_proposal, flags, ctx.positionals);
+	if (!args.input) throw new CliError("Missing --input '<json>' (or --input-file <path|->)");
+	const result = await client.callTool("create_site_proposal", args);
+	printResult(
+		io,
+		flags,
+		result.proposal,
+		(p) => `${p.id}  ${p.path}  ${p.label}  (${p.tool} via ${p.channel})  [${p.status}]`
+	);
+	return 0;
+}
+
+async function siteDecide(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.decide_site_proposal);
+	const result = await client.callTool(
+		"decide_site_proposal",
+		argsFromFlags(ARGS.decide_site_proposal, flags, ctx.positionals)
+	);
+	ok(ctx, result.message);
+	printResult(io, flags, result.proposal, (p) => `${p.id}  ${p.label}  [${p.status}]`);
+	return 0;
+}
+
+export { ARGS };

package/lib/commands.mjs

@@ -41,5 +41,6 @@ export * from "./commands/targets.mjs";
 export * from "./commands/admin.mjs";
 export * from "./commands/feedback.mjs";
 export * from "./commands/repo.mjs";
+export * from "./commands/site.mjs";
 export * from "./commands/evals.mjs";
 export * from "./commands/visits.mjs";

package/lib/documents.mjs

@@ -81,6 +81,8 @@ export const JSON_ARG_FLAG_PAIRS = [
 	["accept-plan-json", "accept-plan"],
 	// A prospects CSV, parsed and header-mapped server-side (outbound.mjs prospects import).
 	["csv", "csv-file"],
+	// A site proposal's tool input, parsed as JSON (site.mjs proposalInput).
+	["input", "input-file"],
 ];
 
 /** Lower-case extension without the dot. */

package/package.json

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