posthorn 0.2.4 → 0.2.6

package/README.md

@@ -1,22 +1,22 @@
 # Posthorn
 
-**Posthorn spins up cold-email infrastructure — sending domains, mailboxes,
-SPF/DKIM/DMARC, and inbox warmup — on accounts you own, drivable entirely by an
-AI agent.**
+**Posthorn spins up cold-email infrastructure: sending domains, mailboxes,
+SPF/DKIM/DMARC, and inbox warmup. It runs on accounts you own and is drivable
+entirely by an AI agent.**
 
 It's a pure orchestration layer: you own your Cloudflare account, your Google
 Workspace, your domains, and your mailboxes. Posthorn automates the setup and
-warmup on top of accounts you control — it never owns or bills for any of it.
+warmup on top of accounts you control. It never owns or bills for any of it.
 
 ## Quick start with an AI agent (recommended)
 
 Posthorn is built to be driven by an agent (Claude Code, Codex, Cursor, etc.).
 Paste this into your agent:
 
-> I want to set up cold-email infrastructure — sending domains, mailboxes, and
+> I want to set up cold-email infrastructure: sending domains, mailboxes, and
 > inbox warmup. Use the Posthorn CLI to do it. First run `npm install -g posthorn`
 > then `posthorn guide`, read the guide, and walk me through the whole setup
-> step by step — run the commands for me and tell me whenever I need to do
+> step by step. Run the commands for me and tell me whenever I need to do
 > something in my browser.
 
 The agent reads `posthorn guide` (which prints this document) and orchestrates
@@ -50,7 +50,7 @@ never owns or bills for any of it.
 4. Domain         → buy new OR connect existing OR managed DNS
 5. DKIM           → browser step (see below)
 6. Mailboxes      → `posthorn mailboxes create ...`
-7. Verify account → `posthorn auth verify` (unlocks sending/warmup — "verified" tier)
+7. Verify account → `posthorn auth verify` (unlocks sending/warmup, "verified" tier)
 8. Warmup         → `posthorn warmup start <mailbox-id>`
 
 Dependencies: you CANNOT create a mailbox until the domain status is `ready`.
@@ -62,15 +62,24 @@ stored locally, so you can stop and continue any time.
 ## The external/manual steps (things that happen OUTSIDE the CLI)
 
 These are the steps you must GUIDE THE USER through in their browser. Give exact
-click-by-click instructions.
+click-by-click instructions. Tell the user up front that these are one-time
+setup steps; once done, they never repeat them. Future domains and mailboxes
+are fully automated (the only exceptions: DKIM is once per domain, delegation
+is once per Workspace org).
 
 ### Cloudflare API token (one-time, for "buy new" or "own Cloudflare" domains)
 - dash.cloudflare.com/profile/api-tokens → Create Token → Custom Token
-- Permissions: Account>Registrar:Domains>Admin, Account>Billing>Edit,
+- Permissions: Account>Account Settings>Read, Account>Registrar: Domains>Admin,
   Zone>Zone>Edit, Zone>DNS>Edit. Resources: Include All.
+- Do NOT add Billing permissions; they are not needed. Domain purchases charge
+  the payment method already on the Cloudflare account, which is a dashboard
+  setting, not a token permission.
 - Then: `posthorn accounts cloudflare <token>`
+- This token is only for Cloudflare (domains and DNS). Google Workspace is NOT
+  connected with this token; it has its own separate one-time step below
+  (domain-wide delegation, no token involved).
 - For domain PURCHASES, the user also needs a payment method on their Cloudflare
-  account (they pay Cloudflare directly — Posthorn never bills for domains).
+  account (they pay Cloudflare directly; Posthorn never bills for domains).
 
 ### Google Workspace domain-wide delegation (one-time per Workspace org)
 - admin.google.com → Security → Access and data control → API controls →
@@ -79,7 +88,7 @@ click-by-click instructions.
 - OAuth scopes (paste all, comma-separated):
   `https://mail.google.com/,https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.domain,https://www.googleapis.com/auth/siteverification`
 - Then ask for their admin email and run: `posthorn accounts workspace <admin-email>`
-- This replaces OAuth entirely — no consent screen, no app verification, no test users.
+- This replaces OAuth entirely: no consent screen, no app verification, no test users.
 
 ### Nameservers (only for "managed DNS" or moving a domain to Cloudflare)
 - The CLI prints 2 nameservers. The user sets them at their domain REGISTRAR
@@ -87,10 +96,10 @@ click-by-click instructions.
 - Propagation takes minutes to 24h. Check with `posthorn domains activate <id>`
   (managed) or by polling `posthorn domains get <id>`.
 
-### DKIM (per domain — Google has no DKIM API)
+### DKIM (per domain, Google has no DKIM API)
 If you have browser-automation tools, do it for the user:
 - Navigate to https://admin.google.com/ac/apps/gmail/authenticateemail
-  (the URL may need /u/N/ for the right account slot — verify the "Selected
+  (the URL may need /u/N/ for the right account slot, verify the "Selected
   domain" on the page matches).
 - If status is "Authenticating email with DKIM" → already done, skip.
 - Otherwise click GENERATE NEW RECORD → GENERATE (defaults: 2048-bit, "google"
@@ -106,11 +115,11 @@ PRINCIPLE: domain purchase ALWAYS happens on the user's own Cloudflare account
 and card. Posthorn never owns or bills for domains.
 
 1. NEW domain → requires the user's own Cloudflare account (+ payment method).
-   - `posthorn domains check name1.com name2.io --cloudflare <id>` — fast availability + price
-   - `posthorn domains reputation <domain>` — VET it before buying (Spamhaus
+   - `posthorn domains check name1.com name2.io --cloudflare <id>`, fast availability + price
+   - `posthorn domains reputation <domain>`, VET it before buying (Spamhaus
      blocklist/score + archive.org prior-use). Verdicts: clean / caution (used
      before) / avoid (blocklisted or poor reputation). Run this on the candidate
-     before `buy` — you can't tell a tainted domain from its name. (Slower + uses
+     before `buy`; you can't tell a tainted domain from its name. (Slower + uses
      a quota, so it's a separate explicit call, not part of `check`.)
    - `posthorn domains buy <domain> --cloudflare <id> --contact '{...}'`
 
@@ -124,7 +133,7 @@ and card. Posthorn never owns or bills for domains.
    - user sets them at their registrar
    - `posthorn domains activate <domain-id>` → checks propagation, starts DNS setup
    - Best for DEDICATED email-only domains. Don't use on a domain running a live
-     website — Posthorn becomes authoritative for ALL its DNS.
+     website; Posthorn becomes authoritative for ALL its DNS.
 
 After any path, poll `posthorn domains get <id>` until status is `ready`. DNS
 records (MX, SPF, DMARC) are configured automatically. Statuses progress:
@@ -134,7 +143,7 @@ workspace_verifying → workspace_verified → ready.
 ## Mailboxes & sending
 
 - Create: `posthorn mailboxes create <domain-id> --email john@dom.com --first John --last Smith`
-  Returns a one-time password (Google Workspace login). Save it — not shown again.
+  Returns a one-time password (Google Workspace login). Save it (not shown again).
 - Credentials for IMAP/SMTP are auto-provisioned via the service account
   (domain-wide delegation). Google mailboxes need no per-mailbox setup.
 - Send: `posthorn send <mailbox-id> --to x@y.com --subject "Hi" --body "..."`
@@ -148,16 +157,19 @@ Anonymous tier can do setup (accounts, domains). To send/warmup, verify:
 ## Warmup
 
 - `posthorn warmup start <mailbox-id>` → joins the shared warmup pool, ramps over ~30 days
+  - Volume and reply behavior are platform-managed (ramps from 2/day to 5/day;
+    peers reply to ~30% of warmup mail). Not configurable: the pool is shared,
+    so settings are tuned for everyone's deliverability.
 - `posthorn warmup stats <campaign-id>` → placement rate, reputation, daily breakdown
 - `posthorn warmup list` → all campaigns
-- Warmup never fully stops on its own — pause with `posthorn warmup pause <id>`.
+- Warmup never fully stops on its own, pause with `posthorn warmup pause <id>`.
 
 ## Feedback (bugs, feature requests)
 
 `posthorn feedback --type bug|feature|question|other "<message>"`
 
 If you hit a bug, missing capability, or rough edge while driving this CLI,
-report it — it goes straight to the Posthorn team. Agents: you are encouraged
+report it, it goes straight to the Posthorn team. Agents: you are encouraged
 to file feedback yourself when something doesn't work the way you expected
 (include the command you ran and what you expected). Works on any tier, no
 verification needed.
@@ -165,11 +177,11 @@ verification needed.
 ## Tips for agents
 
 - Read commands auto-detect output: when stdout isn't a TTY (i.e. you're an agent
-  capturing output), they emit JSON automatically — no flag needed. Humans in a
+  capturing output), they emit JSON automatically, no flag needed. Humans in a
   terminal get formatted text. Force either way with `--json` / `--pretty`.
 - Async steps (domain provisioning, nameserver propagation) need polling, not blocking.
 - Every command stores state locally (~/.config), so the user doesn't re-enter keys.
 - Translate everything into plain English for the user. Never show them raw JSON
-  or ask them to run curl — you run the CLI on their behalf.
+  or ask them to run curl, you run the CLI on their behalf.
 - When a step needs the user's browser (Cloudflare token, delegation, nameservers,
   DKIM), give exact click-by-click instructions and wait for confirmation.

package/dist/index.js

@@ -78,7 +78,7 @@ async function register(options) {
     console.log(`  API Key: ${chalk.cyan(data.api_key)}`);
     console.log(`  Tier:    ${chalk.yellow(data.user.tier)}`);
     console.log();
-    console.log(chalk.dim("  Save this API key \u2014 it won't be shown again."));
+    console.log(chalk.dim("  Save this API key, it won't be shown again."));
     console.log(chalk.dim(`  Config stored at: ${getConfigPath()}`));
   } catch (err) {
     spinner.fail(`Could not reach ${apiUrl}`);
@@ -338,7 +338,7 @@ async function getDomain(domainId, options = {}) {
 function verdictText(rep) {
   switch (rep.verdict) {
     case "avoid":
-      return chalk3.red(`\u26A0 ${rep.verdictLabel} \u2014 avoid`);
+      return chalk3.red(`\u26A0 ${rep.verdictLabel}, avoid`);
     case "caution":
       return chalk3.yellow(rep.verdictLabel);
     case "clean":
@@ -419,7 +419,7 @@ async function createMailbox(domainId, options) {
   console.log(`  ${chalk4.bold("Email:")}    ${data.credentials.email}`);
   console.log(`  ${chalk4.bold("Password:")} ${chalk4.yellow(data.credentials.password)}`);
   console.log();
-  console.log(chalk4.red("  Save this password now \u2014 it will not be shown again."));
+  console.log(chalk4.red("  Save this password now, it will not be shown again."));
   console.log(chalk4.dim("  Login at: https://mail.google.com"));
 }
 async function sendEmail(mailboxId, options) {
@@ -447,7 +447,7 @@ async function provisionCredentials(mailboxId, options) {
     body: { authType: options.type ?? "xoauth2" }
   });
   if (data.connectivity.send && data.connectivity.imap) {
-    spinner.succeed(`Credentials provisioned \u2014 sending (${data.connectivity.sendMethod}) and IMAP connected!`);
+    spinner.succeed(`Credentials provisioned, sending (${data.connectivity.sendMethod}) and IMAP connected!`);
   } else {
     spinner.warn("Credentials provisioned but connectivity issues:");
     for (const err of data.connectivity.errors) {
@@ -461,14 +461,19 @@ import chalk5 from "chalk";
 import ora5 from "ora";
 async function startWarmup(mailboxId) {
   const spinner = ora5("Starting warmup...").start();
-  const data = await api("/api/warmup/campaigns", {
-    method: "POST",
-    body: { mailboxId, autoStart: true }
-  });
+  const data = await api(
+    "/api/warmup/campaigns",
+    {
+      method: "POST",
+      body: { mailboxId, autoStart: true }
+    }
+  );
+  const effective = data.campaign.config ?? {};
   spinner.succeed("Warmup started!");
   console.log(`  Campaign ID: ${chalk5.dim(data.campaign.id)}`);
   console.log(`  Status:      ${chalk5.green("active")}`);
-  console.log(chalk5.dim("  Emails will ramp up gradually over 30 days."));
+  console.log(`  Daily cap:   ${effective.daily_limit ?? 5}/day (ramps up from 2)`);
+  console.log(`  Reply rate:  ${Math.round((effective.reply_rate ?? 0.3) * 100)}%`);
 }
 async function pauseWarmup(campaignId) {
   await api(`/api/warmup/campaigns/${campaignId}`, {
@@ -553,7 +558,7 @@ async function sendFeedback(messageWords, options) {
       }
     }
   });
-  console.log(chalk6.green("Feedback recorded \u2014 thank you!"));
+  console.log(chalk6.green("Feedback recorded, thank you!"));
   console.log(`  id:   ${chalk6.dim(data.feedback.id)}`);
   console.log(`  type: ${chalk6.dim(data.feedback.type)}`);
 }
@@ -569,14 +574,14 @@ function guide() {
     console.log(readme);
   } catch {
     console.log(
-      "Posthorn \u2014 see the full guide at https://www.npmjs.com/package/posthorn\nQuick start: posthorn auth register, then posthorn accounts cloudflare <token>, posthorn accounts workspace <admin-email>, posthorn domains connect <domain> --cloudflare <id>."
+      "Posthorn, see the full guide at https://www.npmjs.com/package/posthorn\nQuick start: posthorn auth register, then posthorn accounts cloudflare <token>, posthorn accounts workspace <admin-email>, posthorn domains connect <domain> --cloudflare <id>."
     );
   }
 }
 
 // src/index.ts
 var program = new Command();
-program.name("posthorn").description("Posthorn \u2014 domain setup, mailbox creation, and email warmup").version("0.2.4");
+program.name("posthorn").description("Posthorn: domain setup, mailbox creation, and email warmup").version("0.2.6");
 program.addHelpText("after", `
 Agents: run 'posthorn guide' first for the full workflow playbook.
 
@@ -591,10 +596,10 @@ Typical flow:
   posthorn auth verify                            unlock sending + warmup
   posthorn warmup start <mailbox-id>
 
-Output: read commands auto-detect \u2014 agents (non-TTY) get JSON, humans get
+Output: read commands auto-detect. Agents (non-TTY) get JSON, humans get
 formatted text. Force either with --json or --pretty.
 `);
-program.command("guide").description("Print the full agent playbook \u2014 workflow, external steps, and how to drive the CLI. Run this first.").action(guide);
+program.command("guide").description("Print the full agent playbook: workflow, external steps, and how to drive the CLI. Run this first.").action(guide);
 var auth = program.command("auth").description("Account management");
 auth.command("register").description("Create a new account and get an API key").option("--url <url>", "API server URL", "https://api-production-08f2.up.railway.app").action(register);
 auth.command("status").description("Show current account info and setup progress").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(status);
@@ -607,7 +612,7 @@ var domains = program.command("domains").description("Domain management");
 domains.command("list").description("List all domains").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(listDomains);
 domains.command("get <domain-id>").description("Get domain details (poll this until status is 'ready')").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(getDomain);
 domains.command("check <domains...>").description("Check domain availability + pricing (fast)").requiredOption("--cloudflare <account-id>", "Cloudflare account ID").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(checkDomains);
-domains.command("reputation <domains...>").description("Vet a domain before buying \u2014 blocklist + reputation + prior-use history").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(domainReputation);
+domains.command("reputation <domains...>").description("Vet a domain before buying, blocklist + reputation + prior-use history").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(domainReputation);
 domains.command("buy <domain>").description("Purchase a domain").requiredOption("--cloudflare <account-id>", "Cloudflare account ID").option("--contact <json>", "Registrant contact info as JSON").action(buyDomain);
 domains.command("connect <domain>").description("Connect an existing domain on your own Cloudflare account").requiredOption("--cloudflare <account-id>", "Cloudflare account ID").option("--workspace <account-id>", "Workspace account ID").action(connectDomain);
 domains.command("managed <domain>").description("Add an existing domain to Posthorn-managed DNS (returns nameservers to set at your registrar)").option("--workspace <account-id>", "Workspace account ID").action(managedDomain);
@@ -622,7 +627,7 @@ warmup.command("list").description("List warmup campaigns").action(listCampaigns
 warmup.command("start <mailbox-id>").description("Start warming a mailbox").action(startWarmup);
 warmup.command("pause <campaign-id>").description("Pause a warmup campaign").action(pauseWarmup);
 warmup.command("stats <campaign-id>").description("Show warmup stats and daily breakdown").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(warmupStats);
-program.command("feedback <message...>").description("Send feedback to the Posthorn team \u2014 bug reports, feature requests, anything").option("-t, --type <type>", "bug | feature | question | other", "other").action(sendFeedback);
+program.command("feedback <message...>").description("Send feedback to the Posthorn team: bug reports, feature requests, anything").option("-t, --type <type>", "bug | feature | question | other", "other").action(sendFeedback);
 program.hook("preAction", () => {
 });
 program.parseAsync(process.argv).catch((err) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "posthorn",
-  "version": "0.2.4",
-  "description": "Posthorn — domain setup, mailbox creation, and email warmup from the command line",
+  "version": "0.2.6",
+  "description": "Domain setup, mailbox creation, and email warmup from the command line",
   "type": "module",
   "bin": {
     "posthorn": "dist/index.js"