@letterstory/cli 0.27.1 → 0.29.0

package/README.md

@@ -79,9 +79,9 @@ refresh automatically. Run `letterstory logout` to revoke the session and forget
 
 **Or use a static API key** (for CI/automation, or when you want scoped-down access):
 
-You need a Letterstory API key (starts with `ls_`; legacy `lb_` keys still work) with the `deployment:read` and
-`deployment:write` capabilities — mint one in the app under **Settings → API keys**.
-Add `deployment:domain` too if you plan to buy custom domains.
+You need a Letterstory API key (starts with `ls_`; legacy `lb_` keys still work) with the `phantom:read` and
+`phantom:write` capabilities — mint one in the app under **Settings → API keys**.
+Add `phantom:domain` too if you plan to buy custom domains.
 
 ```bash
 letterstory login --key ls_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -95,59 +95,48 @@ Run `letterstory whoami` (alias `status`) any time to confirm which key/url (or
 resolved and see your company profile. Run `letterstory config` to see the resolved url and
 credential source without making a network call.
 
-## Spin up a blog
+## Phantomstory — a collection Letterstory hosts as an independent publication
+
+A phantom is a site we host that renders one of your collections; it never carries your
+company's name. Phantoms are metered in SITES live at once (`phantom balance`), not posts.
 
 ```bash
-# create a blog and wait until it's live (polls for you)
-letterstory deploy create --name "My Blog" --theme gazette
-
-#   Created deployment 7c19c7… (provisioning)
-#     … provisioning · building
-#     … provisioning · connecting
-#   ✓ Live at https://my-blog-7c19c7.letterstory-staging.com
-
-letterstory deploy list
-letterstory deploy get <deployment-id>
-letterstory deploy update <deployment-id> --name "New Name"
-letterstory deploy rebuild <deployment-id>      # after publishing new articles
-letterstory deploy diagnostics <deployment-id>  # why is my blog empty?
-letterstory deploy delete <deployment-id> --yes
+# provision a site and follow it until it's live (then it configures itself in the background:
+# strategy, visuals, writing kernel, cadence, topic map)
+letterstory phantom new --name "Saved Query" --config '{"cadence":{"posts_per_week":6}}'
+
+#   Phantom 7c19c7… provisioning — following…
+#     … provisioning · deploy
+#     … provisioning · connect
+#   Live at https://saved-query-7c19c7.letterstory-staging.com. Configuration continues in the background
+
+letterstory phantom list
+letterstory phantom get <phantom-id>
+letterstory phantom config <phantom-id>                        # the site's file joined to its collection's
+letterstory phantom config <phantom-id> --theme commons          # patch the site (identity/theme rebuild it)
+letterstory phantom config <phantom-id> --collection-config '{"cadence":{"posts_per_week":4}}'
+letterstory phantom config <phantom-id> --configure --dry-run   # what re-configuring would decide, applying nothing
+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 delete <phantom-id> --yes
 ```
 
-Pass `--no-wait` to return immediately and poll later with `deploy get`, or `--dry-run`
-on `create` to print what would be sent without creating anything.
-
-### One-shot: bare `deploy`
-
-For the common case — reserve a blog, price (and optionally buy) a domain, and rebuild,
-all in one call — skip the subcommand word entirely:
+Pass `--no-wait` to return immediately and poll later with `phantom get`, `--no-configure`
+for a bare site, or `--dry-run` to see the plan without provisioning anything.
 
-```bash
-letterstory deploy --domain yourverticalreview.com --buy
-#   Reserved phantom blog "Yourverticalreview" (7c19c7…)
-#   Priced yourverticalreview.com
-#   Registered yourverticalreview.com
-#   SSL + DNS provisioned · sitemap + schema generated
-#
-#   Your phantom blog is live at https://yourverticalreview.com.
-
-letterstory deploy --blog 7c19c7… --rebuild   # rebuild an existing blog instead of creating one
-letterstory deploy --domain demo.com --dry-run  # preview without calling the API
-```
+Publishing to the site is a **collection run** on its collection (below). Letterstory's own
+launch recipe from a client domain — positioning inferred, a masthead proposed, the first
+posts seeded — is `phantom-onboard` (see "Propose, then onboard a phantom").
 
 ## Custom domains
 
 ```bash
-letterstory domain check myblog.com                       # price it (no charge)
-letterstory domain buy <deployment-id> myblog.com        # buys + attaches the domain
+letterstory phantom domain check myblog.com                     # price it (no charge)
+letterstory phantom domain buy <phantom-id> myblog.com --yes    # buys + attaches (spends money; phantom:domain)
+letterstory phantom domain connect <phantom-id> myblog.com      # attach one you already own
 ```
 
-`blogs` and `domains` are aliases for `deploy` and `domain` — the exact same commands
-under Phantomstory's vocabulary (`blogs ls`, `blogs new`, `blogs rm`, `blogs update`,
-`domains buy`, etc. all call the identical handler as their `deploy`/`domain`
-counterpart). Use whichever set of verbs you prefer; both are always available from
-both `letterstory` and `phantom`.
-
 ## Content
 
 ```bash
@@ -161,16 +150,41 @@ letterstory published list [--limit <n>] [--collection <uuid>] [--format html|md
 letterstory published show --slug my-post-slug [--format html|md]    # or --id <uuid>
 ```
 
-## Collections
+## Collections — the content engine, one door
+
+A collection is a publication with a ONE-FILE configuration (identity, content, cadence,
+publishing, targets, measurement) that produces and publishes posts on a cadence.
+`collection run` produces ONE post: source → write → gate → publish → (hosted) rebuild.
 
 ```bash
-letterstory collections list
-letterstory collections new --name "Launches" --description "…"
+letterstory collection list                                     # public_id = the HTTP door's address
+letterstory collection new --name "Launches" --config-file cfg.json
+letterstory collection config <id>                              # print the one file
+letterstory collection config <id> --config '{"targets":{"enabled":true,"tier":"ramping"}}'   # patch it
+
+# one post, followed to the end (20–60 min); stops at the gate under manual approval
+letterstory collection run --collection <id> --spoke <topic-id>
+letterstory collection run --collection <id> --topic "…" --approval manual --no-wait
+letterstory collection run --collection <id> --at 2026-10-01T09:00:00Z   # a future slot
+letterstory collection run-status <run-id>                      # status, steps, constraints, verification
+letterstory collection runs --collection <id> --status ready
+letterstory collection approve <run-id> --now
+letterstory collection cancel <run-id>
+letterstory collection delete <id> --yes
+
+# the legacy verbs still work under `collections`
 letterstory collections update <id> --cadence-target 4 --cadence-period week
-letterstory collections delete <id> --yes
 letterstory collections assign <article-id> <collection-id>
+letterstory collections activate <id> --cadence 6 --approval autopilot
+letterstory collections autopen <id> --kernel-family gazette
 ```
 
+A direct run spends one of the collection's weekly cadence slots (its `posts_per_week`,
+capped by the org's cadence cap) and is refused — never queued silently — once the week is
+spent; the planner's own slots are the budget being spent as designed. The same door over
+HTTP: `POST /api/collection/ingest/{public_id}` (202 + `poll_url`), `GET …/runs/{run_id}`,
+`POST …/runs/{run_id}/approve`.
+
 ## Landing pages
 
 A landing page is a link plus context describing what lives there. Collections with
@@ -280,6 +294,7 @@ jq '.topicPlans[1]' proposal.json | letterstory phantom-onboard mastheads acme.c
 # Then onboard with the plan (direction + pillars), the masthead and, if any, the domain.
 letterstory phantom-onboard acme.com --plan-file proposal.json --plan-id plan-2 \
   --name "The Compliance Wire" --domain compliancewire.com --domain-mode buy_now --real
+# (drives plan_phantom; the seeded posts are collection runs — poll them with `collection run-status`)
 ```
 
 `propose` reads the client's homepage and returns distinct editorial angles (`topicPlans`), the
@@ -341,6 +356,16 @@ letterstory arena endpoint create --name "Docs research" --defaults '{"depth":"b
 letterstory arena endpoint config <arena-id> [--file cfg.json]
 letterstory arena endpoint delete <arena-id> --yes
 
+# Ledes: a prospect's context in, ready-to-send opening lines out (chosen from a
+# hand-approved library, never generated; the top choice is flagged). Synchronous.
+letterstory lede create --name "Clay outbound table"
+letterstory lede run <endpoint-id> --first-name Jane --company Acme --company-url acme.com --years 3
+letterstory lede run <endpoint-id> --email jane@acme.com --tone direct --candidates 3
+letterstory lede run <endpoint-id> --company Acme --default-lede "Came across {{company}} this week."
+letterstory lede runs --limit 20
+letterstory lede balance
+letterstory lede endpoint config <endpoint-id> [--file cfg.json]
+
 # 2. Have a kernel write the draft
 letterstory kernel list
 letterstory kernel run --article <uuid> --kernel <uuid> [--brief "…" | --brief-file brief.md]
@@ -375,8 +400,8 @@ letterstory shredder job <job-id>                                 # poll it your
 Both follow loops poll every 15–20 s. `LETTERSTORY_POLL_INTERVAL_MS` overrides that — set
 it to `0` in CI so a test does not wait on a real interval.
 
-`phantom-job create --topic "…" --collection <uuid>` runs topic → draft → publish → rebuild
-end to end, with `phantom-job status <job-id>` to follow it.
+`collection run --topic "…" --collection <uuid>` runs topic → draft → publish → rebuild
+end to end, with `collection run-status <job-id>` to follow it.
 
 ## Seers — event-driven signals
 

package/lib/cli.mjs

@@ -3,6 +3,7 @@
 // never throws for user-facing problems (those become a printed CliError + code 1).
 
 import { LetterstoryClient, CliError, resolveConfig, readConfigFile, writeConfigFile } from "./client.mjs";
+import { resolveDocumentFlags } from "./documents.mjs";
 import { checkForUpdate } from "./update-check.mjs";
 import {
 	cmdLogin,
@@ -13,10 +14,8 @@ import {
 	cmdCall,
 	cmdTool,
 	cmdMcp,
-	cmdDeploy,
-	cmdDomain,
-	cmdBlogs,
-	cmdDomains,
+	cmdCollection,
+	cmdPhantom,
 	cmdPosts,
 	cmdPublished,
 	cmdReviewers,
@@ -34,17 +33,17 @@ import {
 	cmdAutoPen,
 	cmdCovers,
 	cmdKernel,
-	cmdPhantomJob,
 	cmdOnboard,
 	cmdSeers,
 	cmdTemplates,
 	cmdShredder,
+	cmdLede,
 	cmdLandings,
 	cmdAdmin,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.27.1";
+export const VERSION = "0.29.0";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -166,25 +165,42 @@ Auth:
   logout                             Forget saved credentials (revokes an OAuth session, if any)
   config                             Show the resolved url + credential source
 
-Phantom blogs:
-  deploy [--domain <d>] [--name <n>] [--theme <t>] [--collection <uuid>]
-         [--blog <id>] [--buy] [--rebuild] [--dry-run]
-                                                      One-shot: reserve/locate a blog, price
-                                                      the domain, optionally buy it, rebuild
-  deploy create --name <name> [--description <text>] [--theme <theme>]
-                [--collection <uuid>] [--no-wait]   Create a blog; waits until it's live
-  deploy list [--limit <n>]                          List your blogs
-  deploy get <deployment-id>                         Show one blog's status + URL
-  deploy rebuild <deployment-id>                     Rebuild to pull in newly-published content
-  deploy diagnostics <deployment-id>                 Why is my blog empty? snapshot
-  deploy delete <deployment-id> --yes                Tear down the blog (keeps the collection)
-
-Custom domains:
-  domain check <domain>                              Price a domain (read-only, no charge)
-  domain buy <deployment-id> <domain>                Buy + attach a custom domain
-
-  "blogs" and "domains" are aliases for "deploy" and "domain" (same commands, ls/new/
-  show/update/rm verbs also accepted) — use whichever vocabulary you prefer.
+Collections (the content engine as a primitive — one door, 'collection run'):
+  collection list                                      Your collections (public_id = the HTTP door's address)
+  collection new --name <n> [--description <t>] [--config '<json>'|--config-file cfg.json]
+  collection config <id> [--config '<json>'|--config-file cfg.json]
+                                                       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]
+                 [--kernel <id>] [--no-verify] [--shred] [--mention off|subtle|woven]
+                 [--approval autopilot|review_window|manual] [--no-publish] [--no-rebuild]
+                 [--at <iso-datetime>] [--no-wait]
+                                                       Produce ONE post: source → write → gate →
+                                                       publish → (hosted) rebuild. Spends one of the
+                                                       week's cadence slots. 20–60 min; followed unless
+                                                       --no-wait; stops at the gate under manual approval.
+  collection run-status <run-id>                       Status, steps, constraints, verification
+  collection runs [--collection <id>] [--status <s>] [--limit <n>]
+  collection approve <run-id> [--now]                  Answer the gate (--now publishes immediately)
+  collection cancel <run-id>
+  collection delete <id> --yes
+
+Phantomstory (a collection Letterstory hosts as an independent publication):
+  phantom list                                         Your phantoms (metered in SITES live at once)
+  phantom new --name <n> [--description <t>] [--theme <t>] [--collection <id>] [--customer-ref <r>]
+              [--no-configure] [--config '<json>'] [--client-domain <d>] [--dry-run] [--no-wait]
+                                                       Provision a site + configure it (strategy,
+                                                       visuals, kernel, cadence, topic map). Then
+                                                       'collection run --collection <its collection_id>'.
+  phantom get <phantom-id>                             Status, URL, domain, DNS
+  phantom config <phantom-id> [--name … --theme … --collection …] [--collection-config '<json>']
+                              [--configure [--dry-run]]
+                                                       The site's file joined to its collection's
+  phantom rebuild <phantom-id> · phantom diagnostics <phantom-id> · phantom balance
+  phantom domain check <domain> · phantom domain buy <phantom-id> <domain> --yes
+  phantom domain connect <phantom-id> <domain>
+  phantom delete <phantom-id> --yes
 
 Content:
   posts list [--limit <n>] [--collection <uuid>]     List your articles
@@ -346,12 +362,7 @@ Writing kernels (kernels write the draft; they do not research — run research
   kernel runs [--endpoint <id>] [--limit <n>]          Recent endpoint writes (telemetry)
   kernel balance                                       Kernel runs left on this org
 
-Phantom orchestrator:
-  phantom-job create --topic <text> --collection <uuid> [--kernel <uuid>]
-                                                        Topic -> draft -> publish -> rebuild
-  phantom-job status <job-id>                          Check a job's stage
-
-Phantom onboarding recipe (domain -> live phantom blog with first posts):
+Phantom launch recipe (a CLIENT domain -> a live phantom with its first posts; drives plan_phantom):
   ${bin === "phantom" ? "onboard" : "phantom-onboard"} <domain> [--about "the beat"] [--name X]
           [--posts N] [--cadence N] [--cover editorial_image|full_ai|line_art] [--theme T]
           [--real] [--domain host] [--domain-mode subdomain|buy_now|connect_later]
@@ -538,6 +549,24 @@ Shredder (diversify content produced outside Letterstory; structure preserved):
   shredder job <job-id>                                Poll a queued shred and print it when it lands
   shredder runs [--endpoint <id>] [--limit <n>]        Recent shred calls (telemetry), newest first
 
+Ledes (opening lines for cold email, chosen per prospect from a hand-approved library):
+  lede list                                            Your lede endpoints + run counts
+  lede create --name <n>                               New endpoint (returns a callable public id)
+  lede delete <endpoint-id> --yes
+  lede endpoint config <endpoint-id> [--file cfg.json] Print the endpoint's config, or replace it
+  lede run <endpoint-id> [--first-name <n>] [--name <full>] [--email <e>] [--title <t>]
+           [--company <c>] [--company-url <url>] [--school <s>] [--city <c>] [--country <c>]
+           [--years <n>] [--linkedin <url>] [--notes <text>]
+           [--candidates <1..10>] [--tone warm|direct|playful|formal] [--no-enrich]
+                                                       Synchronous: prints the candidate lines with the
+                                                       top choice flagged. Needs at least one of
+                                                       --first-name, --name, --email, --company or
+                                                       --company-url. Only a match consumes a lede;
+                                                       no_match is free. --no-enrich skips the company
+                                                       lookup when latency matters more than fit.
+  lede runs [--endpoint <id>] [--limit <n>]            Recent lede calls (telemetry), newest first
+  lede balance                                         Ledes left on this org
+
 Landings (a link + context; auto-mentioned in articles by collections you enable):
   landings list                                        Your landing pages + mention counts
   landings get <landing-id>                            Show one landing page
@@ -588,11 +617,9 @@ const CLIENT_COMMANDS = {
 	// argument coercion (--arg/--json-args/--stdin) added on top.
 	tool: cmdTool,
 	mcp: cmdMcp,
-	deploy: cmdDeploy,
-	domain: cmdDomain,
-	// Mathew's phantomstory-cli names for the exact same deploy/domain commands.
-	blogs: cmdBlogs,
-	domains: cmdDomains,
+	// The Collections primitive (one door: `collection run`) and its hosted profile.
+	collection: cmdCollection,
+	phantom: cmdPhantom,
 	posts: cmdPosts,
 	published: cmdPublished,
 	reviewers: cmdReviewers,
@@ -610,11 +637,12 @@ const CLIENT_COMMANDS = {
 	autopen: cmdAutoPen,
 	covers: cmdCovers,
 	kernel: cmdKernel,
-	"phantom-job": cmdPhantomJob,
 	"phantom-onboard": cmdOnboard,
 	seers: cmdSeers,
 	templates: cmdTemplates,
 	shredder: cmdShredder,
+	lede: cmdLede,
+	ledes: cmdLede,
 	landings: cmdLandings,
 	// Platform-scoped (staff key) — the only commands that act BEFORE an org exists.
 	admin: cmdAdmin,
@@ -687,6 +715,15 @@ export async function run(argv, io = defaultIo()) {
 			verboseLog: io.error,
 			bin,
 		});
+		// DOCUMENT `--*-file` FLAGS BECOME TEXT BEFORE THE COMMAND RUNS.
+		//
+		// One interception point rather than per-command handling: `readTextInput` prefers a
+		// flag's inline twin over its path, so resolving a document is setting that twin — no
+		// change to `argsFromFlags` (which is synchronous, and has 75 call sites) and no command
+		// that can forget. `--file notes.md` still reads locally; `--file report.docx` and
+		// `--file paper.pdf` go through the app's extractor, which is the only one there is.
+		await resolveDocumentFlags(client, flags);
+
 		const ctx = { client, config, positionals: positionals.slice(1), flags, io, bin };
 		return await handler(ctx);
 	} catch (err) {

package/lib/client.mjs

@@ -155,6 +155,59 @@ export class LetterstoryClient {
 		return body.result;
 	}
 
+	/**
+	 * One multipart POST to a REST route on the same host, for the routes that take BYTES.
+	 *
+	 * The MCP envelope is JSON, so a document would have to be base64'd into it — a 10MB PDF
+	 * becomes ~13MB of base64 in a single JSON string. `POST /api/documents/extract` takes the
+	 * file directly, so this exists for it (and any future byte-taking route). Same auth and
+	 * the same one-shot refresh-and-retry as `rpc`, because an expired session should fail the
+	 * same way whichever door the command happened to use.
+	 *
+	 * Deliberately no `content-type` header: `fetch` sets it from the FormData, including the
+	 * multipart boundary, and overriding it produces a body the server cannot parse.
+	 *
+	 * @param {string} path Route path, e.g. `/api/documents/extract`
+	 * @param {FormData} form
+	 * @returns {Promise<any>} the parsed JSON body
+	 */
+	async postForm(path, form, { _retried = false } = {}) {
+		const authHeaders = this.authHeaders();
+		if (!authHeaders) {
+			throw new CliError(
+				`Not logged in. Run \`${this.bin} login\` (opens your browser) or \`${this.bin} login --key <ls_…>\`.`
+			);
+		}
+		const url = `${this.url}${path}`;
+		if (this.verbose) this.verboseLog(`» POST ${url} (multipart)`);
+		let res;
+		try {
+			res = await this.fetch(url, {
+				method: "POST",
+				headers: { accept: "application/json", ...authHeaders },
+				body: form,
+			});
+		} catch (err) {
+			throw new CliError(`Could not reach ${url}: ${err.message}`);
+		}
+		if (this.verbose) this.verboseLog(`« ${res.status}`);
+		if (res.status === 401 || res.status === 403) {
+			if (!_retried && this.oauth?.refresh_token && (await this.tryRefresh())) {
+				return this.postForm(path, form, { _retried: true });
+			}
+			const hint = this.oauth
+				? `Your session has expired. Run \`${this.bin} login\` again.`
+				: "Check your API key and its capabilities.";
+			throw new CliError(`Authentication failed (HTTP ${res.status}). ${hint}`);
+		}
+		const body = await res.json().catch(() => null);
+		if (!res.ok) {
+			throw new CliError(body?.error ? String(body.error) : `Request failed (HTTP ${res.status}) at ${url}`);
+		}
+		if (!body) throw new CliError(`Unexpected non-JSON response (HTTP ${res.status}) from ${url}`);
+		return body;
+	}
+
 	// Best-effort silent refresh. Returns false (never throws) so rpc() can
 	// fall through to its normal "please log in again" error on any failure.
 	async tryRefresh() {