posthorn 0.1.0 → 0.2.3

package/README.md

@@ -0,0 +1,165 @@
+# 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.**
+
+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.
+
+## 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
+> 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
+> something in my browser.
+
+The agent reads `posthorn guide` (which prints this document) and orchestrates
+the rest.
+
+## Install
+
+```
+npm install -g posthorn
+```
+
+Or run any command without installing via `npx posthorn <command>`.
+
+---
+
+# Agent playbook
+
+If you're an AI agent driving the `posthorn` CLI for a user, this is the
+knowledge you need that `--help` alone doesn't give you. Read it fully before
+starting. Run `posthorn guide` any time to reprint it.
+
+The platform is a pure orchestration layer: the USER owns their Cloudflare
+account, their Google Workspace, their domains, and their mailboxes. Posthorn
+never owns or bills for any of it.
+
+## The end-to-end flow (in order)
+
+1. Account        → `posthorn auth register` (anonymous API key, instant)
+2. Cloudflare     → user creates account + API token, then `posthorn accounts cloudflare <token>`
+3. Workspace      → user sets up domain-wide delegation, then `posthorn accounts workspace <admin-email>`
+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)
+8. Warmup         → `posthorn warmup start <mailbox-id>`
+
+Dependencies: you CANNOT create a mailbox until the domain status is `ready`.
+You CANNOT send or start warmup until the account is "verified" tier.
+
+Run `posthorn auth status --json` any time to see where things stand. State is
+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.
+
+### 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,
+  Zone>Zone>Edit, Zone>DNS>Edit. Resources: Include All.
+- Then: `posthorn accounts cloudflare <token>`
+- For domain PURCHASES, the user also needs a payment method on their Cloudflare
+  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 →
+  Domain-wide delegation → Add new
+- Client ID: 110137377718772968374
+- 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.
+
+### Nameservers (only for "managed DNS" or moving a domain to Cloudflare)
+- The CLI prints 2 nameservers. The user sets them at their domain REGISTRAR
+  (where they bought the domain), replacing the existing nameservers.
+- 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)
+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
+  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"
+  prefix). Read the TXT record value (starts with v=DKIM1; k=rsa; p=...).
+- Add it to DNS as a TXT record named google._domainkey.<domain>.
+- Click START AUTHENTICATION on the admin page.
+If no browser tools: have the user do the above and paste you the TXT value,
+then add it to their DNS.
+
+## Domain options (3 paths)
+
+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
+     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
+     a quota, so it's a separate explicit call, not part of `check`.)
+   - `posthorn domains buy <domain> --cloudflare <id> --contact '{...}'`
+
+2. EXISTING domain, recommended → user's own Cloudflare account.
+   - `posthorn domains connect <domain> --cloudflare <account-id>`
+   - (If the domain isn't on Cloudflare yet, the user adds it at dash.cloudflare.com
+     and points nameservers to their account first.)
+
+3. EXISTING domain, optional → Posthorn-managed DNS (no Cloudflare account needed).
+   - `posthorn domains managed <domain>` → prints 2 nameservers
+   - 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.
+
+After any path, poll `posthorn domains get <id>` until status is `ready`. DNS
+records (MX, SPF, DMARC) are configured automatically. Statuses progress:
+pending_* → purchased → dns_configuring → dns_configured → dns_verified →
+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.
+- 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 "..."`
+  (requires "verified" tier)
+
+## Account verification (unlocks sending/warmup)
+
+Anonymous tier can do setup (accounts, domains). To send/warmup, verify:
+`posthorn auth verify` → choose admin email or a custom email → confirm the code.
+
+## Warmup
+
+- `posthorn warmup start <mailbox-id>` → joins the shared warmup pool, ramps over ~30 days
+- `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>`.
+
+## 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
+  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.
+- 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

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { Command } from "commander";
-import chalk7 from "chalk";
+import chalk6 from "chalk";
 
 // src/commands/auth.ts
 import chalk from "chalk";
@@ -46,6 +46,13 @@ function getConfigPath() {
   return conf.path;
 }
 
+// src/output.ts
+function useJson(options = {}) {
+  if (options.json) return true;
+  if (options.pretty) return false;
+  return !process.stdout.isTTY;
+}
+
 // src/commands/auth.ts
 async function register(options) {
   const apiUrl = options.url ?? "https://api-production-08f2.up.railway.app";
@@ -78,8 +85,19 @@ async function register(options) {
     console.log(chalk.dim(`  Is the server running? Try: posthorn auth register --url <your-api-url>`));
   }
 }
-async function status() {
+async function status(options = {}) {
   const config = getConfig();
+  if (useJson(options)) {
+    console.log(JSON.stringify({
+      loggedIn: !!config.apiKey,
+      apiUrl: config.apiUrl,
+      userId: config.userId,
+      cloudflareConnected: config.cloudflareConnected,
+      workspaceConnected: config.workspaceConnected,
+      setupStep: config.setupStep
+    }, null, 2));
+    return;
+  }
   if (!config.apiKey) {
     console.log(chalk.yellow("Not logged in."));
     console.log(`  Run: ${chalk.cyan("posthorn auth register")}`);
@@ -117,7 +135,7 @@ var ApiError = class extends Error {
 async function api(path, options = {}) {
   const config = getConfig();
   if (!config.apiKey) {
-    throw new Error("Not logged in. Run: posthorn setup");
+    throw new Error("Not logged in. Run: posthorn auth register");
   }
   const url = `${config.apiUrl}${path}`;
   const res = await fetch(url, {
@@ -193,10 +211,12 @@ async function listAccounts() {
 // src/commands/domains.ts
 import chalk3 from "chalk";
 import ora3 from "ora";
-async function listDomains() {
-  const spinner = ora3("Fetching domains...").start();
+async function listDomains(options = {}) {
   const data = await api("/api/domains");
-  spinner.stop();
+  if (useJson(options)) {
+    console.log(JSON.stringify(data.domains, null, 2));
+    return;
+  }
   if (data.domains.length === 0) {
     console.log(chalk3.dim("  No domains yet. Run: posthorn domains buy <domain>"));
     return;
@@ -250,15 +270,57 @@ async function connectDomain(domain, options) {
   spinner.succeed(data.message);
   console.log(`  Domain ID: ${chalk3.dim(data.domain.id)}`);
 }
-async function getDomain(domainId) {
+async function managedDomain(domain, options) {
+  const spinner = ora3(`Adding ${domain} to managed DNS...`).start();
+  const body = { name: domain };
+  if (options.workspace) body.workspaceAccountId = options.workspace;
+  const data = await api("/api/domains/managed", { method: "POST", body });
+  spinner.succeed("Domain added to managed DNS!");
+  console.log();
+  console.log("  Set these 2 nameservers at your registrar:");
+  for (const ns of data.nameServers) {
+    console.log(`    ${chalk3.cyan(ns)}`);
+  }
+  console.log();
+  console.log(chalk3.dim("  Once changed (takes minutes to 24h), run:"));
+  console.log(chalk3.cyan(`    posthorn domains activate ${data.domain.id}`));
+}
+async function activateDomain(domainId) {
+  const spinner = ora3("Checking nameserver propagation...").start();
+  const data = await api(`/api/domains/${domainId}/activate`, { method: "POST" });
+  if (data.active) {
+    spinner.succeed(data.message);
+  } else {
+    spinner.warn(data.message);
+    console.log(chalk3.dim(`  Cloudflare status: ${data.cloudflareStatus ?? "pending"}`));
+  }
+}
+async function getDomain(domainId, options = {}) {
   const data = await api(`/api/domains/${domainId}`);
   const d = data.domain;
+  if (useJson(options)) {
+    console.log(JSON.stringify(d, null, 2));
+    return;
+  }
   console.log(chalk3.bold("Domain\n"));
   console.log(`  Name:   ${chalk3.cyan(d.name)}`);
   console.log(`  Status: ${d.status === "ready" ? chalk3.green(d.status) : chalk3.yellow(d.status)}`);
   console.log(`  ID:     ${chalk3.dim(d.id)}`);
+  console.log(`  DNS:    ${d.dns_mode === "managed" ? "managed by Posthorn" : "your Cloudflare"}`);
   if (d.cloudflare_zone_id) console.log(`  Zone:   ${chalk3.dim(d.cloudflare_zone_id)}`);
 }
+function verdictText(rep) {
+  switch (rep.verdict) {
+    case "avoid":
+      return chalk3.red(`\u26A0 ${rep.verdictLabel} \u2014 avoid`);
+    case "caution":
+      return chalk3.yellow(rep.verdictLabel);
+    case "clean":
+      return chalk3.green(rep.verdictLabel);
+    default:
+      return chalk3.dim(rep.verdictLabel);
+  }
+}
 async function checkDomains(domains2, options) {
   const spinner = ora3("Checking availability...").start();
   const data = await api("/api/domains/check", {
@@ -266,11 +328,35 @@ async function checkDomains(domains2, options) {
     body: { domains: domains2, cloudflareAccountId: options.cloudflare }
   });
   spinner.stop();
+  if (useJson(options)) {
+    console.log(JSON.stringify(data.results, null, 2));
+    return;
+  }
   console.log(chalk3.bold("Domain Availability\n"));
   for (const r of data.results) {
     const icon = r.available ? chalk3.green("  \u2713") : chalk3.red("  \u2717");
     const price = r.price ? chalk3.dim(`$${r.price}/yr`) : "";
-    console.log(`${icon} ${r.domain}  ${price}`);
+    console.log(`${icon} ${String(r.domain).padEnd(30)}${price}`);
+  }
+  console.log(chalk3.dim("\n  Vet a domain before buying: posthorn domains reputation <domain>"));
+}
+async function domainReputation(domains2, options = {}) {
+  const spinner = ora3("Checking reputation (blocklist + history)...").start();
+  const data = await api("/api/domains/reputation", {
+    method: "POST",
+    body: { domains: domains2 }
+  });
+  spinner.stop();
+  if (useJson(options)) {
+    console.log(JSON.stringify(data.results, null, 2));
+    return;
+  }
+  console.log(chalk3.bold("Domain Reputation\n"));
+  for (const rep of data.results) {
+    console.log(`  ${chalk3.cyan(rep.domain.padEnd(28))}${verdictText(rep)}`);
+    for (const w of rep.warnings) {
+      console.log(chalk3.dim(`      \u2022 ${w}`));
+    }
   }
 }
 
@@ -334,8 +420,8 @@ async function provisionCredentials(mailboxId, options) {
     method: "POST",
     body: { authType: options.type ?? "xoauth2" }
   });
-  if (data.connectivity.smtp && data.connectivity.imap) {
-    spinner.succeed("Credentials provisioned \u2014 SMTP and IMAP connected!");
+  if (data.connectivity.send && data.connectivity.imap) {
+    spinner.succeed(`Credentials provisioned \u2014 sending (${data.connectivity.sendMethod}) and IMAP connected!`);
   } else {
     spinner.warn("Credentials provisioned but connectivity issues:");
     for (const err of data.connectivity.errors) {
@@ -365,8 +451,12 @@ async function pauseWarmup(campaignId) {
   });
   console.log(chalk5.yellow("Warmup paused."));
 }
-async function warmupStats(campaignId) {
+async function warmupStats(campaignId, options = {}) {
   const data = await api(`/api/warmup/campaigns/${campaignId}`);
+  if (useJson(options)) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
   const s = data.stats;
   const c = data.campaign;
   console.log(chalk5.bold("Warmup Stats\n"));
@@ -403,221 +493,60 @@ async function listCampaigns() {
   }
 }
 
-// src/commands/setup.ts
-import chalk6 from "chalk";
-import ora6 from "ora";
-import inquirer from "inquirer";
-var STEPS = [
-  "Account",
-  "Cloudflare",
-  "Google Workspace",
-  "Domain",
-  "DKIM",
-  "Mailboxes",
-  "Warmup"
-];
-function printProgress(currentStep) {
-  console.log();
-  for (let i = 0; i < STEPS.length; i++) {
-    const icon = i < currentStep ? chalk6.green("  \u2713") : i === currentStep ? chalk6.cyan("  \u2192") : chalk6.dim("  \u25CB");
-    const label = i === currentStep ? chalk6.bold(STEPS[i]) : i < currentStep ? STEPS[i] : chalk6.dim(STEPS[i]);
-    console.log(`${icon} Step ${i + 1}: ${label}`);
+// src/commands/guide.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+function guide() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const readme = readFileSync(join(here, "..", "README.md"), "utf8");
+    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>."
+    );
   }
-  console.log();
-}
-async function setup(options) {
-  console.log(chalk6.bold("\n  Posthorn Setup\n"));
-  const config = getConfig();
-  let step = config.setupStep;
-  if (step < 1) {
-    printProgress(0);
-    if (!config.apiKey) {
-      await register({ url: options.url });
-    } else {
-      console.log(chalk6.green("  Account already exists."));
-    }
-    setConfig({ setupStep: 1 });
-    step = 1;
-  }
-  if (step < 2) {
-    printProgress(1);
-    if (!config.cloudflareConnected) {
-      const { hasCf } = await inquirer.prompt([
-        { type: "confirm", name: "hasCf", message: "Do you have a Cloudflare account?", default: true }
-      ]);
-      if (!hasCf) {
-        console.log();
-        console.log("  1. Go to " + chalk6.cyan("https://dash.cloudflare.com/sign-up"));
-        console.log("  2. Create a free account");
-        console.log("  3. Add a payment method if you want to purchase domains");
-        console.log();
-        await inquirer.prompt([{ type: "confirm", name: "ready", message: "Ready to continue?" }]);
-      }
-      console.log();
-      console.log("  Create an API token:");
-      console.log("  1. Go to " + chalk6.cyan("https://dash.cloudflare.com/profile/api-tokens"));
-      console.log('  2. Click "Create Token" \u2192 "Create Custom Token"');
-      console.log("  3. Add these permissions:");
-      console.log("     - Account \u2192 Registrar: Domains \u2192 Admin");
-      console.log("     - Account \u2192 Billing \u2192 Edit");
-      console.log("     - Zone \u2192 Zone \u2192 Edit");
-      console.log("     - Zone \u2192 DNS \u2192 Edit");
-      console.log("  4. Account/Zone Resources: Include All");
-      console.log('  5. Click "Continue to summary" \u2192 "Create Token"');
-      console.log();
-      const { token } = await inquirer.prompt([
-        { type: "password", name: "token", message: "Paste your Cloudflare API token:", mask: "*" }
-      ]);
-      await connectCloudflare(token);
-    } else {
-      console.log(chalk6.green("  Cloudflare already connected."));
-    }
-    setConfig({ setupStep: 2 });
-    step = 2;
-  }
-  if (step < 3) {
-    printProgress(2);
-    if (!config.workspaceConnected) {
-      const { hasWs } = await inquirer.prompt([
-        { type: "confirm", name: "hasWs", message: "Do you have a Google Workspace account?", default: true }
-      ]);
-      if (!hasWs) {
-        console.log();
-        console.log("  Set up a new Google Workspace:");
-        console.log("  1. Go to " + chalk6.cyan("https://workspace.google.com") + " \u2192 Get Started");
-        console.log('  2. Enter your business name, select "Just you"');
-        console.log('  3. Click "Set up using your existing domain" and enter your domain');
-        console.log("  4. Create your first email (this will be your outbound email)");
-        console.log("  5. Complete billing setup (14-day free trial available)");
-        console.log();
-        await inquirer.prompt([{ type: "confirm", name: "ready", message: "Done setting up Workspace?" }]);
-      }
-      console.log();
-      console.log("  Set up domain-wide delegation:");
-      console.log("  1. Go to " + chalk6.cyan("admin.google.com") + " \u2192 Security \u2192 API controls");
-      console.log("  2. Click Domain-wide delegation \u2192 Add new");
-      console.log("  3. Client ID: " + chalk6.yellow("110137377718772968374"));
-      console.log("  4. Scopes: " + chalk6.dim("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"));
-      console.log("  5. Click Authorize");
-      console.log();
-      await inquirer.prompt([{ type: "confirm", name: "ready", message: "Done with delegation?" }]);
-      const { adminEmail } = await inquirer.prompt([
-        { type: "input", name: "adminEmail", message: "Your Workspace admin email:" }
-      ]);
-      await connectWorkspace(adminEmail);
-    } else {
-      console.log(chalk6.green("  Google Workspace already connected."));
-    }
-    setConfig({ setupStep: 3 });
-    step = 3;
-  }
-  if (step < 4) {
-    printProgress(3);
-    const { domainChoice } = await inquirer.prompt([
-      {
-        type: "list",
-        name: "domainChoice",
-        message: "Domain setup:",
-        choices: [
-          { name: "Buy a new domain", value: "buy" },
-          { name: "Connect an existing domain (must be on Cloudflare)", value: "connect" },
-          { name: "Skip for now", value: "skip" }
-        ]
-      }
-    ]);
-    if (domainChoice === "connect") {
-      const { domain } = await inquirer.prompt([
-        { type: "input", name: "domain", message: "Domain name:" }
-      ]);
-      const accounts2 = await api("/api/accounts");
-      const cfAccount = accounts2.accounts.find((a) => a.provider === "cloudflare");
-      if (cfAccount) {
-        const spinner = ora6(`Connecting ${domain}...`).start();
-        try {
-          const data = await api("/api/domains/connect", {
-            method: "POST",
-            body: {
-              name: domain,
-              cloudflareAccountId: cfAccount.id,
-              workspaceAccountId: config.workspaceAccountId
-            }
-          });
-          spinner.succeed(data.message);
-        } catch (err) {
-          spinner.fail(err.message);
-          console.log(chalk6.dim("\n  If the domain isn't on Cloudflare yet:"));
-          console.log(chalk6.dim("  1. Go to dash.cloudflare.com \u2192 Add a site \u2192 enter your domain"));
-          console.log(chalk6.dim("  2. Change nameservers at your registrar to Cloudflare's"));
-          console.log(chalk6.dim("  3. Run this setup again\n"));
-        }
-      }
-    } else if (domainChoice === "buy") {
-      console.log(chalk6.dim("\n  Use the domains command to search and buy:"));
-      console.log(chalk6.cyan("  posthorn domains check example.com example.io --cloudflare <id>"));
-      console.log(chalk6.cyan("  posthorn domains buy example.com --cloudflare <id> --contact '{...}'"));
-      console.log();
-    }
-    setConfig({ setupStep: 4 });
-    step = 4;
-  }
-  if (step < 5) {
-    printProgress(4);
-    console.log("  DKIM needs to be set up per domain.");
-    console.log("  If you're using Claude Code, run the setup skill \u2014 it automates DKIM via browser.");
-    console.log("  Otherwise, go to admin.google.com \u2192 Apps \u2192 Gmail \u2192 Authenticate email");
-    console.log();
-    await inquirer.prompt([{ type: "confirm", name: "ready", message: "DKIM set up (or skipping for now)?" }]);
-    setConfig({ setupStep: 5 });
-    step = 5;
-  }
-  if (step < 6) {
-    printProgress(5);
-    console.log("  Create mailboxes with:");
-    console.log(chalk6.cyan("  posthorn mailboxes create <domain-id> --email john@yourdomain.com --first John --last Smith"));
-    console.log();
-    await inquirer.prompt([{ type: "confirm", name: "ready", message: "Mailboxes created (or skipping)?" }]);
-    setConfig({ setupStep: 6 });
-    step = 6;
-  }
-  if (step < 7) {
-    printProgress(6);
-    console.log("  Start warming your mailboxes:");
-    console.log(chalk6.cyan("  posthorn warmup start <mailbox-id>"));
-    console.log(chalk6.cyan("  posthorn warmup stats <campaign-id>"));
-    console.log();
-    await inquirer.prompt([{ type: "confirm", name: "ready", message: "Ready to finish setup?" }]);
-    setConfig({ setupStep: 7 });
-    step = 7;
-  }
-  printProgress(7);
-  console.log(chalk6.bold.green("  Setup complete!\n"));
-  console.log("  Useful commands:");
-  console.log(chalk6.cyan("  posthorn domains list"));
-  console.log(chalk6.cyan("  posthorn mailboxes list <domain-id>"));
-  console.log(chalk6.cyan("  posthorn warmup stats <campaign-id>"));
-  console.log(chalk6.cyan("  posthorn send <mailbox-id> --to user@example.com --subject 'Hi' --body 'Hello!'"));
-  console.log(chalk6.cyan("  posthorn auth status"));
-  console.log();
 }
 
 // src/index.ts
 var program = new Command();
 program.name("posthorn").description("Posthorn \u2014 domain setup, mailbox creation, and email warmup").version("0.1.0");
-program.command("setup").description("Guided setup \u2014 walk through the full onboarding flow").option("--url <url>", "API server URL", "https://api-production-08f2.up.railway.app").action(setup);
+program.addHelpText("after", `
+Agents: run 'posthorn guide' first for the full workflow playbook.
+
+Typical flow:
+  posthorn guide                                  learn the workflow
+  posthorn auth register                          create an account
+  posthorn accounts cloudflare <token>            connect Cloudflare
+  posthorn accounts workspace <admin-email>       connect Google Workspace
+  posthorn domains connect <domain> --cloudflare <id>
+  posthorn domains get <id> --json                poll until status: ready
+  posthorn mailboxes create <domain-id> --email you@dom.com --first A --last B
+  posthorn auth verify                            unlock sending + warmup
+  posthorn warmup start <mailbox-id>
+
+Output: read commands auto-detect \u2014 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);
 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").action(status);
+auth.command("status").description("Show current account info and setup progress").option("--json", "Force JSON output").option("--pretty", "Force human-readable output").action(status);
 auth.command("logout").description("Clear stored credentials").action(logout);
 var accounts = program.command("accounts").description("Connected accounts (Cloudflare, Workspace)");
 accounts.command("list").description("List connected accounts").action(listAccounts);
 accounts.command("cloudflare <token>").description("Connect a Cloudflare account").option("--label <label>", "Account label", "main").action(connectCloudflare);
 accounts.command("workspace <admin-email>").description("Connect Google Workspace via domain-wide delegation").action(connectWorkspace);
 var domains = program.command("domains").description("Domain management");
-domains.command("list").description("List all domains").action(listDomains);
-domains.command("get <domain-id>").description("Get domain details").action(getDomain);
-domains.command("check <domains...>").description("Check domain availability").requiredOption("--cloudflare <account-id>", "Cloudflare account ID").action(checkDomains);
+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("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 (must be on Cloudflare)").requiredOption("--cloudflare <account-id>", "Cloudflare account ID").option("--workspace <account-id>", "Workspace account ID").action(connectDomain);
+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);
+domains.command("activate <domain-id>").description("Check if managed-DNS nameservers propagated, then start DNS setup").action(activateDomain);
 var mailboxes = program.command("mailboxes").description("Mailbox management");
 mailboxes.command("list <domain-id>").description("List mailboxes for a domain").action(listMailboxes);
 mailboxes.command("create <domain-id>").description("Create a new mailbox").requiredOption("--email <email>", "Email address (e.g. john@example.com)").requiredOption("--first <name>", "First name").requiredOption("--last <name>", "Last name").action(createMailbox);
@@ -627,18 +556,18 @@ var warmup = program.command("warmup").description("Email warmup management");
 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").action(warmupStats);
+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.hook("preAction", () => {
 });
 program.parseAsync(process.argv).catch((err) => {
   if (err.statusCode === 401) {
-    console.log(chalk7.red("\n  Authentication failed. Run: posthorn auth register\n"));
+    console.log(chalk6.red("\n  Authentication failed. Run: posthorn auth register\n"));
   } else if (err.statusCode === 403) {
-    console.log(chalk7.red("\n  Account not verified. Complete onboarding: posthorn setup\n"));
+    console.log(chalk6.red("\n  Account not verified. Run: posthorn auth verify\n"));
   } else if (err.statusCode === 429) {
-    console.log(chalk7.yellow("\n  Rate limit exceeded. Try again in a minute.\n"));
+    console.log(chalk6.yellow("\n  Rate limit exceeded. Try again in a minute.\n"));
   } else {
-    console.error(chalk7.red(`
+    console.error(chalk6.red(`
   Error: ${err.message}
 `));
   }

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "posthorn",
-  "version": "0.1.0",
+  "version": "0.2.3",
   "description": "Posthorn — domain setup, mailbox creation, and email warmup from the command line",
   "type": "module",
   "bin": {
     "posthorn": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "email",