@letterstory/cli 0.28.0 → 0.29.1

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,82 +95,97 @@ 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`
+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.
 
-For the common case — reserve a blog, price (and optionally buy) a domain, and rebuild,
-all in one call — skip the subcommand word entirely:
-
-```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
 letterstory posts list [--limit <n>] [--collection <uuid>]
 letterstory posts show <article-id>
-letterstory posts new --title "…" --collection <uuid> --body "…"     # or --file <path|->
+letterstory posts new --title "…" --collection <uuid> --body "…" [--article-id <uuid>]   # or --file <path|->; --article-id updates that article instead of creating one
 letterstory posts publish <article-id>
 letterstory posts unpublish <article-id>
+letterstory posts delete --id <uuid> [--id <uuid> ...]                # permanent; content, history, and any published copy are all removed
 
 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 +295,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
@@ -385,8 +401,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,7 +33,6 @@ import {
 	cmdAutoPen,
 	cmdCovers,
 	cmdKernel,
-	cmdPhantomJob,
 	cmdOnboard,
 	cmdSeers,
 	cmdTemplates,
@@ -45,7 +43,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.28.0";
+export const VERSION = "0.29.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.
@@ -167,32 +165,50 @@ 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
   posts show <article-id>                            Show one article
-  posts new --title <t> --collection <uuid> (--body <text> | --file <path|->)
+  posts new --title <t> --collection <uuid> (--body <text> | --file <path|->) [--article-id <uuid>]
   posts publish <article-id>                         Publish an article
   posts unpublish <article-id>                       Unpublish an article
+  posts delete --id <uuid> [--id <uuid> ...]         Permanently delete article(s)
   published list [--limit <n>] [--collection <uuid>] [--format html|md]
   published show (--id <uuid> | --slug <slug>) [--format html|md]
 
@@ -347,12 +363,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]
@@ -607,11 +618,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,
@@ -629,7 +638,6 @@ const CLIENT_COMMANDS = {
 	autopen: cmdAutoPen,
 	covers: cmdCovers,
 	kernel: cmdKernel,
-	"phantom-job": cmdPhantomJob,
 	"phantom-onboard": cmdOnboard,
 	seers: cmdSeers,
 	templates: cmdTemplates,
@@ -708,6 +716,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() {