openpouch 0.1.0 → 0.2.1

package/README.md

@@ -1,20 +1,34 @@
 # openpouch 🦘
 
-**The agent-native deployment control plane.** Deploy any folder to a live URL in one command — no account, no setup:
+**The agent-native hosting platform — built _for_ coding agents, not walled against them.** Deploy any folder to a live URL in one command — no account, no dashboard, no CAPTCHA:
 
 ```bash
 npx openpouch deploy
 ```
 
-> **Status: technical preview.** The instant lane (`openpouch deploy`) serves **static** sites today (HTML/SPAs/build output); a runtime for dynamic apps is coming. The governed Render/Vercel lanes (`init`/`preview`/`prod`) are fuller. Feedback welcome on GitHub.
+> **Status: technical preview.** `openpouch deploy` serves **static** sites (HTML/SPAs/build output) **and runs real Node.js apps** in a hardened container — autonomously, from any agent or terminal. Previews are ephemeral (unclaimed ones vanish after 72 h); durable production hosting and self-service billing are on the way. Feedback welcome on GitHub.
 
-You get a live `https://<slug>.openpouch.sh` preview plus a claim link. The agent deploys autonomously; a human claims it via the link (unclaimed previews vanish after 72 h). openpouch writes the deployment truth (`deploy.manifest.json`, `deploy.evidence.json`, `DEPLOYMENT.md`) back into your repo, so any agent can resume after context loss.
+You get a live `https://<slug>.openpouch.sh` URL plus a claim link. The agent deploys autonomously; a human claims it via the link to keep it. openpouch writes the deployment truth (`deploy.manifest.json`, `deploy.evidence.json`, `DEPLOYMENT.md`) back into your repo, so any agent can resume after context loss.
+
+## Accounts (optional)
+
+Start anonymous, or create a free account for higher limits — entirely from the agent, no dashboard:
+
+```bash
+npx openpouch signup --email you@example.com    # or: --github
+npx openpouch activate --account <id> --token <token-from-email>
+npx openpouch whoami --json                      # your tier + current usage
+```
+
+Your API key is stored locally; deploys then run under your account and quota. Abuse is controlled with accounts, quotas, rate limits and an egress filter — **never** by asking a machine to prove it's human.
+
+## Bring your own provider
 
 Already on Render or Vercel? `openpouch init` detects your project and maps the service; then `openpouch preview` / `openpouch prod` run a governed pipeline — previews autonomous, production gated behind a human approval. Agents can never self-approve production.
 
 ## Commands
 
-`deploy` · `init` · `inspect` · `plan` · `preview` · `prod` · `approve` · `verify` · `logs` · `rollback` — every command supports `--json` and stable exit codes, so any agent harness with a shell can drive it. An MCP server exposes the same tools.
+`deploy` · `signup` · `activate` · `whoami` · `init` · `inspect` · `plan` · `preview` · `prod` · `approve` · `verify` · `logs` · `rollback` — every command supports `--json` and stable exit codes, so any agent harness with a shell can drive it. An MCP server exposes the same tools.
 
 - Source & docs: https://github.com/openpouch/openpouch
 - License: Apache-2.0

package/openpouch.js

@@ -4258,93 +4258,14 @@ function findUsableApproval(file, match, now) {
   return file.requests.find((r) => r.status === "approved" && r.action === match.action && r.environment === match.environment && r.serviceId === match.serviceId && !isExpired(r, now));
 }
 
-// packages/cli/src/commands/approve.ts
-import { createInterface } from "node:readline/promises";
-
-// packages/cli/src/approvals.ts
-import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-import { mkdir, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
-import { homedir, userInfo } from "node:os";
-import { join as join2 } from "node:path";
-var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
-async function loadApprovals(cwd) {
-  try {
-    const raw = await readFile2(join2(cwd, APPROVALS_FILENAME), "utf8");
-    return approvalsFileSchema.parse(JSON.parse(raw));
-  } catch {
-    return { version: 0, requests: [] };
-  }
-}
-async function saveApprovals(cwd, file) {
-  await mkdir(join2(cwd, APPROVALS_DIR), { recursive: true });
-  await ensureGitignored(cwd);
-  await writeFile2(
-    join2(cwd, APPROVALS_FILENAME),
-    `${JSON.stringify(approvalsFileSchema.parse(file), null, 2)}
-`,
-    "utf8"
-  );
-}
-async function ensureGitignored(cwd) {
-  const path = join2(cwd, ".gitignore");
-  let content = "";
-  try {
-    content = await readFile2(path, "utf8");
-  } catch {
-  }
-  if (!content.split("\n").some((line) => line.trim() === ".openpouch/")) {
-    const addition = `${content.length > 0 && !content.endsWith("\n") ? "\n" : ""}.openpouch/
-`;
-    await writeFile2(path, content + addition, "utf8");
-  }
-}
-function newApprovalRequest(match, now) {
-  return {
-    id: randomBytes(4).toString("hex"),
-    action: match.action,
-    environment: match.environment,
-    serviceId: match.serviceId,
-    requestedAt: now.toISOString(),
-    expiresAt: new Date(now.getTime() + DEFAULT_TTL_MS).toISOString(),
-    status: "pending"
-  };
-}
-async function getApproverSecret(createIfMissing, home) {
-  const dir = join2(home ?? homedir(), ".openpouch");
-  const path = join2(dir, "approver.secret");
-  try {
-    const existing = (await readFile2(path, "utf8")).trim();
-    if (existing.length > 0) return existing;
-  } catch {
-  }
-  if (!createIfMissing) return void 0;
-  const secret = randomBytes(32).toString("hex");
-  await mkdir(dir, { recursive: true });
-  await writeFile2(path, `${secret}
-`, { mode: 384 });
-  return secret;
-}
-function signApproval(request, secret) {
-  return createHmac("sha256", secret).update(canonicalApprovalPayload(request)).digest("hex");
-}
-function signatureValid(request, secret) {
-  if (request.signature === void 0) return false;
-  const expected = Buffer.from(signApproval(request, secret), "hex");
-  const actual = Buffer.from(request.signature, "hex");
-  return expected.length === actual.length && timingSafeEqual(expected, actual);
-}
-function approverName() {
-  try {
-    return userInfo().username;
-  } catch {
-    return "unknown";
-  }
-}
+// packages/cli/src/commands/activate.ts
+import { mkdir, readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
+import { dirname } from "node:path";
 
 // packages/cli/src/shared.ts
-import { readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
-import { homedir as homedir2 } from "node:os";
-import { join as join3 } from "node:path";
+import { readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
 
 // packages/adapter-render/dist/index.js
 var RenderApiError = class extends Error {
@@ -4481,29 +4402,36 @@ var RunApiError = class extends Error {
   category;
   status;
   fix;
-  constructor(status, detail) {
-    const category = status === 429 ? "quota" : "provider";
+  constructor(status, detail, fix) {
+    const category = status === 401 ? "auth" : status === 429 || status === 413 ? "quota" : "provider";
     super(`openpouch-run ${status}: ${detail}`);
     this.name = "RunApiError";
     this.status = status;
     this.category = category;
-    this.fix = status === 429 ? "Instant-lane rate limit hit \u2014 wait and retry, or use a BYO provider for higher volume." : "Check the openpouch-run service status; the deployment may have expired (72h unclaimed).";
+    this.fix = fix ?? (category === "auth" ? "Your openpouch API key is missing, invalid, or revoked \u2014 run `openpouch signup` to get one, or check OPENPOUCH_API_KEY / ~/.openpouch/openpouch-run.key." : category === "quota" ? "A limit was reached \u2014 wait for the window to roll over, delete an old preview, or use a higher tier." : "Check the openpouch-run service status; the deployment may have expired (72h unclaimed).");
   }
 };
 function createRunAdapter(config) {
   const doFetch = config.fetchImpl ?? fetch;
   const base = config.apiBase.replace(/\/$/, "");
+  const authHeader = config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {};
   async function api(path, init) {
-    const res = await doFetch(`${base}${path}`, init);
+    const res = await doFetch(`${base}${path}`, {
+      ...init,
+      headers: { ...authHeader, ...init?.headers }
+    });
     if (!res.ok) {
       let detail = res.statusText;
+      let fix;
       try {
         const body = await res.json();
         if (body.error)
           detail = body.error;
+        if (body.fix)
+          fix = body.fix;
       } catch {
       }
-      throw new RunApiError(res.status, detail);
+      throw new RunApiError(res.status, detail, fix);
     }
     return res.json();
   }
@@ -4519,6 +4447,26 @@ function createRunAdapter(config) {
       const body = await api("/api/deployments", { method: "POST", headers, body: tarball });
       return body;
     },
+    async whoami() {
+      return await api("/api/account");
+    },
+    async signupEmail(email) {
+      return await api("/api/accounts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email })
+      });
+    },
+    async verifyEmail(accountId, token) {
+      return await api("/api/accounts/verify", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ account: accountId, token })
+      });
+    },
+    githubStartUrl() {
+      return `${base}/api/auth/github/start`;
+    },
     async listServices() {
       return [];
     },
@@ -4673,7 +4621,154 @@ function createVercelAdapter(config) {
   };
 }
 
+// packages/cli/src/summary.ts
+function humanList(items) {
+  if (items.length === 0) return "";
+  if (items.length === 1) return items[0] ?? "";
+  return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+function friendlyUtc(iso) {
+  const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(iso);
+  return m ? `${m[1]} ${m[2]} UTC` : iso;
+}
+function instantDeploySummary(i) {
+  return `Your app "${i.name}" is now live on the internet at ${i.url} \u2014 anyone you share that link with can open it right away. It's a free temporary preview and will disappear on ${friendlyUtc(i.expiresAt)} (about 72 hours) unless you save it. To keep it, open ${i.claimUrl}. Nothing technical is needed from you.`;
+}
+function deploySummary(i) {
+  const at = i.url !== void 0 ? ` at ${i.url}` : "";
+  const approved = i.approvedBy !== void 0 ? `With your approval, ` : "";
+  if (!i.live) {
+    return `The ${i.environment} update did not go live \u2014 something failed while deploying. Your previous version is unaffected. I can check the logs to find out why.`;
+  }
+  if (i.smokePassed === false) {
+    return `${approved}your ${i.environment} app deployed and is online${at}, but my automatic health check found a problem \u2014 it may not be working correctly for visitors right now. You may want me to look into it.`;
+  }
+  const checked = i.smokePassed === true ? ` and I checked that it's responding correctly` : "";
+  const lead = approved !== "" ? approved : "Your ";
+  const subject = approved !== "" ? `your ${i.environment} app` : `${i.environment} app`;
+  return `${lead}${subject} is live${at}${checked}. Nothing else is needed from you.`;
+}
+function inspectSummary(projectName, environments) {
+  const names = Object.keys(environments);
+  if (names.length === 0) {
+    return `"${projectName}" isn't connected to any live service yet, so there's nothing deployed.`;
+  }
+  const lines = [`Here's the current status of "${projectName}":`];
+  for (const [name, env] of Object.entries(environments)) {
+    if (env.status === "unmapped" || env.service === void 0) {
+      lines.push(`\u2022 ${name}: not connected to a live service yet.`);
+      continue;
+    }
+    const where = env.service.url !== void 0 ? `live at ${env.service.url}` : `set up (no public address yet)`;
+    const paused = env.service.suspended ? " It's currently paused." : "";
+    const missing = env.envVars?.missingRequired ?? [];
+    const needs = missing.length > 0 ? ` It still needs ${missing.length === 1 ? "this setting" : "these settings"} before it can fully work: ${humanList(missing)}.` : "";
+    lines.push(`\u2022 ${name}: ${where}.${paused}${needs}`);
+  }
+  return lines.join("\n");
+}
+function verifySummary(i) {
+  const total = i.checks.length;
+  const passedCount = i.checks.filter((c) => c.passed).length;
+  if (i.passed) {
+    return `Good news \u2014 your ${i.environment} app at ${i.url} is healthy and responding correctly. ${total === 1 ? "The check" : `All ${total} checks`} passed.`;
+  }
+  const firstFail = i.checks.find((c) => !c.passed);
+  const reason = firstFail?.detail !== void 0 ? ` (${firstFail.detail})` : "";
+  return `Heads up \u2014 your ${i.environment} app at ${i.url} has a problem${reason}. ${passedCount} of ${total} checks passed. It may not be working correctly for visitors right now, so you may want me to look into it.`;
+}
+function planSummary(projectName, plans) {
+  const names = Object.keys(plans);
+  if (names.length === 0) {
+    return `"${projectName}" has no environments set up to deploy yet.`;
+  }
+  const lines = [`Here's what can be published for "${projectName}":`];
+  for (const [name, p] of Object.entries(plans)) {
+    if (!p.ready) {
+      lines.push(`\u2022 ${name}: not ready yet \u2014 ${humanList(p.blockers)}.`);
+    } else if (p.decision === "requires-approval") {
+      lines.push(`\u2022 ${name}: ready, but it will need your approval before it goes live.`);
+    } else {
+      lines.push(`\u2022 ${name}: ready to go live.`);
+    }
+  }
+  return lines.join("\n");
+}
+function initSummary(i) {
+  if (i.alreadyInitialized === true) {
+    return `"${i.name}" is already set up for deployment. You can deploy it whenever you'd like.`;
+  }
+  const kind = i.framework !== void 0 ? ` (a ${i.framework} app)` : "";
+  const connected = i.matchedProvider !== void 0 ? ` I connected it to your existing ${i.matchedProvider} service.` : "";
+  return `I've set up "${i.name}"${kind} for deployment.${connected} You're ready to deploy it whenever you'd like \u2014 just say the word.`;
+}
+function logsSummary(environment, count) {
+  if (count === 0) {
+    return `There are no recent log entries for your ${environment} app.`;
+  }
+  return `Here are the ${count} most recent log entries from your ${environment} app \u2014 these are mainly useful for spotting errors.`;
+}
+function rollbackSummary(i) {
+  if (!i.live) {
+    return `The rollback did not complete \u2014 the previous version of your ${i.environment} app could not be brought back online. I can investigate.`;
+  }
+  const at = i.url !== void 0 ? ` at ${i.url}` : "";
+  const health = i.smokePassed === false ? ` My health check still flags a problem, so you may want me to look closer.` : i.smokePassed === true ? ` I checked that it's responding correctly.` : "";
+  return `I restored your ${i.environment} app to the previous working version. It's live again${at}.${health}`;
+}
+function approveListSummary(pending) {
+  if (pending.length === 0) {
+    return `Nothing is waiting for your approval right now.`;
+  }
+  const ids = pending.map((p) => p.id);
+  return `There ${pending.length === 1 ? "is 1 change" : `are ${pending.length} changes`} waiting for your approval before going live. To approve, run this in your own terminal: ${ids.map((id) => `openpouch approve ${id}`).join(" ; ")}`;
+}
+function approveResultSummary(approved) {
+  return approved ? `Approved. The change can now be published.` : `Not approved \u2014 nothing was published.`;
+}
+function approvalRequiredSummary(environment, requestId) {
+  return `Publishing to ${environment} needs your go-ahead first \u2014 for safety, an agent can't approve production changes by itself. To approve, open your own terminal and run: openpouch approve ${requestId}. Then I'll continue.`;
+}
+function signupEmailSummary(email) {
+  return `I've started creating your openpouch account for ${email}. Check that inbox for a message from openpouch and open the link inside to finish \u2014 that gives you a private key I use to publish apps under your account.`;
+}
+function signupGithubSummary(url) {
+  return `To create your openpouch account with GitHub, open this link in your browser and approve it: ${url}. When you're done you'll get a private key I use to publish apps under your account.`;
+}
+function activateSummary(saved) {
+  return saved ? `Your openpouch account is ready, and I've saved your private key on this computer \u2014 so from now on I publish apps under your account. Nothing else is needed from you.` : `Your openpouch account is ready. Keep the private key somewhere safe \u2014 it's what lets me publish apps under your account.`;
+}
+function whoamiSummary(i) {
+  if (!i.authenticated) {
+    return `You don't have an openpouch account set up here yet, so your apps publish anonymously on the free temporary tier. To get your own account \u2014 higher limits, and your apps grouped together \u2014 just say the word and I'll start it.`;
+  }
+  const using = i.liveDeployments !== void 0 && i.maxLive !== void 0 ? ` You're using ${i.liveDeployments} of your ${i.maxLive} live apps.` : "";
+  return `You're signed in to openpouch on the ${i.tier} plan.${using} Everything looks fine.`;
+}
+var ERROR_LEADS = {
+  auth: "I couldn't sign in to the hosting provider \u2014 an access key is missing or invalid.",
+  "policy-denied": "This action isn't allowed by your current safety settings.",
+  "human-required": "This needs a person to approve it \u2014 an agent can't do it.",
+  env: "This project isn't fully set up for deployment yet.",
+  quota: "The hosting provider reported that a limit was reached.",
+  provider: "The hosting provider ran into a problem.",
+  usage: "That command wasn't used correctly.",
+  internal: "Something went wrong inside openpouch."
+};
+function errorSummary(category, message, fix) {
+  const lead = ERROR_LEADS[category] ?? `Something didn't work: ${message}.`;
+  return `${lead} What to do next: ${fix}`;
+}
+
 // packages/cli/src/shared.ts
+function summarized(exitCode, json, summary, human) {
+  const { ok, ...rest } = json;
+  return {
+    exitCode,
+    json: { ok, summary, ...rest },
+    human: [...human, "", summary]
+  };
+}
 var EXIT = {
   OK: 0,
   UNEXPECTED: 1,
@@ -4690,16 +4785,17 @@ function isProviderApiError(e) {
   return e instanceof Error && "category" in e && "fix" in e;
 }
 function errorResult(exitCode, category, message, fix) {
+  const summary = errorSummary(category, message, fix);
   return {
     exitCode,
-    json: { ok: false, error: { category, message, fix } },
-    human: [`error [${category}]: ${message}`, `fix: ${fix}`]
+    json: { ok: false, summary, error: { category, message, fix } },
+    human: [`error [${category}]: ${message}`, `fix: ${fix}`, "", summary]
   };
 }
 async function loadManifest(cwd) {
   let raw;
   try {
-    raw = await readFile3(join3(cwd, MANIFEST_FILENAME), "utf8");
+    raw = await readFile2(join2(cwd, MANIFEST_FILENAME), "utf8");
   } catch {
     return { status: "missing" };
   }
@@ -4713,13 +4809,13 @@ async function loadManifest(cwd) {
   return result2.ok ? { status: "ok", manifest: result2.value } : { status: "invalid", errors: result2.errors };
 }
 async function writeJsonFile(path, value) {
-  await writeFile3(path, `${JSON.stringify(value, null, 2)}
+  await writeFile2(path, `${JSON.stringify(value, null, 2)}
 `, "utf8");
 }
 async function loadPolicy(cwd) {
   let raw;
   try {
-    raw = await readFile3(join3(cwd, POLICY_FILENAME), "utf8");
+    raw = await readFile2(join2(cwd, POLICY_FILENAME), "utf8");
   } catch {
     return { status: "default", policy: defaultPolicy(), usedDefault: true };
   }
@@ -4734,15 +4830,32 @@ var PROVIDER_CREDENTIALS = {
   vercel: { envVar: "VERCEL_TOKEN", file: "vercel.token" }
 };
 var ANONYMOUS_KEY = "anonymous";
+var RUN_KEY = { envVar: "OPENPOUCH_API_KEY", file: "openpouch-run.key" };
+function runKeyPath(env) {
+  const override = env["OPENPOUCH_KEY_FILE"]?.trim();
+  if (override) return override;
+  const home = env["OPENPOUCH_HOME"] ?? homedir();
+  return join2(home, ".openpouch", RUN_KEY.file);
+}
+async function resolveRunKey(env) {
+  const fromEnv = env[RUN_KEY.envVar]?.trim();
+  if (fromEnv) return fromEnv;
+  try {
+    const fromFile = (await readFile2(runKeyPath(env), "utf8")).trim();
+    if (fromFile.length > 0) return fromFile;
+  } catch {
+  }
+  return ANONYMOUS_KEY;
+}
 async function resolveProviderApiKey(env, provider) {
-  if (provider === "openpouch-run") return ANONYMOUS_KEY;
+  if (provider === "openpouch-run") return resolveRunKey(env);
   const cred = PROVIDER_CREDENTIALS[provider];
   if (!cred) return void 0;
   const fromEnv = env[cred.envVar]?.trim();
   if (fromEnv) return fromEnv;
   try {
-    const home = env["OPENPOUCH_HOME"] ?? homedir2();
-    const fromFile = (await readFile3(join3(home, ".openpouch", cred.file), "utf8")).trim();
+    const home = env["OPENPOUCH_HOME"] ?? homedir();
+    const fromFile = (await readFile2(join2(home, ".openpouch", cred.file), "utf8")).trim();
     return fromFile.length > 0 ? fromFile : void 0;
   } catch {
     return void 0;
@@ -4767,7 +4880,10 @@ function missingKeyError(provider) {
 function makeAdapter(ctx, provider, apiKey) {
   if (ctx.createAdapter !== void 0) return ctx.createAdapter(provider, apiKey);
   if (provider === "openpouch-run") {
-    return createRunAdapter({ apiBase: runApiBase(ctx.env) });
+    return createRunAdapter({
+      apiBase: runApiBase(ctx.env),
+      ...apiKey && apiKey !== ANONYMOUS_KEY ? { apiKey } : {}
+    });
   }
   if (provider === "vercel") {
     const teamId = ctx.env["VERCEL_TEAM_ID"]?.trim();
@@ -4776,6 +4892,169 @@ function makeAdapter(ctx, provider, apiKey) {
   return createRenderAdapter({ apiKey });
 }
 
+// packages/cli/src/commands/activate.ts
+function keyPublicPrefix(key) {
+  const m = /^(op_live_[0-9a-f]+)_/.exec(key);
+  return m ? m[1] : "op_live_\u2026";
+}
+function looksLikeOpenpouchKey(content) {
+  const t = content.trim();
+  if (t.length === 0) return true;
+  if (t.includes("\n")) return false;
+  return /^op_(?:live|test)_[0-9a-f]{6,}_[A-Za-z0-9_-]+$/.test(t);
+}
+function looksLikePrivateKey(content) {
+  return /-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----/.test(content);
+}
+async function activateCommand(ctx, opts) {
+  const account = opts.account?.trim();
+  const token = opts.token?.trim();
+  if (!account || !token) {
+    return errorResult(
+      EXIT.USAGE,
+      "usage",
+      "activate needs --account and --token",
+      "Run `openpouch signup --email <you@example.com>` first; the verification email contains both."
+    );
+  }
+  const adapter = makeAdapter(ctx, "openpouch-run", "anonymous");
+  if (typeof adapter.verifyEmail !== "function") {
+    return errorResult(EXIT.UNEXPECTED, "provider", "activation unavailable", "This is an internal wiring error.");
+  }
+  try {
+    const res = await adapter.verifyEmail(account, token);
+    let saved = false;
+    let reason;
+    const keyPath = opts.keyFile?.trim() || runKeyPath(ctx.env);
+    try {
+      let existing = null;
+      try {
+        existing = await readFile3(keyPath, "utf8");
+      } catch (e) {
+        if (e.code !== "ENOENT") throw e;
+      }
+      if (existing !== null && existing.trim().length > 0 && !looksLikeOpenpouchKey(existing)) {
+        const how = "Set OPENPOUCH_KEY_FILE (or pass --key-file) to a free path, or move that file.";
+        reason = looksLikePrivateKey(existing) ? `refusing to overwrite ${keyPath} \u2014 it looks like an existing private key. ${how}` : `refusing to overwrite ${keyPath} \u2014 it is not an openpouch key file. ${how}`;
+      } else {
+        await mkdir(dirname(keyPath), { recursive: true });
+        if (existing !== null && existing.trim().length > 0) {
+          await writeFile3(`${keyPath}.bak`, existing, { mode: 384 });
+        }
+        await writeFile3(keyPath, `${res.key}
+`, { mode: 384 });
+        saved = true;
+      }
+    } catch (e) {
+      reason = `could not save the key to ${keyPath}: ${e.message}`;
+    }
+    return summarized(
+      EXIT.OK,
+      {
+        ok: true,
+        account: res.account,
+        keyPrefix: keyPublicPrefix(res.key),
+        saved,
+        ...saved ? { keyPath } : { reason, key: res.key }
+      },
+      activateSummary(saved),
+      [
+        `openpouch activate \u2713 ${res.account.id} [${res.account.tier}]`,
+        ...saved ? [`  saved your key to ${keyPath} (chmod 600) \u2014 deploys now run under your account`] : [`  \u26A0 key NOT saved: ${reason}`, `  \u2192 use it now:  export OPENPOUCH_API_KEY=${res.key}`],
+        `  key: ${keyPublicPrefix(res.key)}\u2026`
+      ]
+    );
+  } catch (e) {
+    if (isProviderApiError(e)) {
+      return errorResult(e.category === "auth" ? EXIT.AUTH : EXIT.PROVIDER, e.category, e.message, e.fix);
+    }
+    throw e;
+  }
+}
+
+// packages/cli/src/commands/approve.ts
+import { createInterface } from "node:readline/promises";
+
+// packages/cli/src/approvals.ts
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { mkdir as mkdir2, readFile as readFile4, writeFile as writeFile4 } from "node:fs/promises";
+import { homedir as homedir2, userInfo } from "node:os";
+import { join as join3 } from "node:path";
+var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+async function loadApprovals(cwd) {
+  try {
+    const raw = await readFile4(join3(cwd, APPROVALS_FILENAME), "utf8");
+    return approvalsFileSchema.parse(JSON.parse(raw));
+  } catch {
+    return { version: 0, requests: [] };
+  }
+}
+async function saveApprovals(cwd, file) {
+  await mkdir2(join3(cwd, APPROVALS_DIR), { recursive: true });
+  await ensureGitignored(cwd);
+  await writeFile4(
+    join3(cwd, APPROVALS_FILENAME),
+    `${JSON.stringify(approvalsFileSchema.parse(file), null, 2)}
+`,
+    "utf8"
+  );
+}
+async function ensureGitignored(cwd) {
+  const path = join3(cwd, ".gitignore");
+  let content = "";
+  try {
+    content = await readFile4(path, "utf8");
+  } catch {
+  }
+  if (!content.split("\n").some((line) => line.trim() === ".openpouch/")) {
+    const addition = `${content.length > 0 && !content.endsWith("\n") ? "\n" : ""}.openpouch/
+`;
+    await writeFile4(path, content + addition, "utf8");
+  }
+}
+function newApprovalRequest(match, now) {
+  return {
+    id: randomBytes(4).toString("hex"),
+    action: match.action,
+    environment: match.environment,
+    serviceId: match.serviceId,
+    requestedAt: now.toISOString(),
+    expiresAt: new Date(now.getTime() + DEFAULT_TTL_MS).toISOString(),
+    status: "pending"
+  };
+}
+async function getApproverSecret(createIfMissing, home) {
+  const dir = join3(home ?? homedir2(), ".openpouch");
+  const path = join3(dir, "approver.secret");
+  try {
+    const existing = (await readFile4(path, "utf8")).trim();
+    if (existing.length > 0) return existing;
+  } catch {
+  }
+  if (!createIfMissing) return void 0;
+  const secret = randomBytes(32).toString("hex");
+  await mkdir2(dir, { recursive: true });
+  await writeFile4(path, `${secret}
+`, { mode: 384 });
+  return secret;
+}
+function signApproval(request, secret) {
+  return createHmac("sha256", secret).update(canonicalApprovalPayload(request)).digest("hex");
+}
+function signatureValid(request, secret) {
+  if (request.signature === void 0) return false;
+  const expected = Buffer.from(signApproval(request, secret), "hex");
+  const actual = Buffer.from(request.signature, "hex");
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+function approverName() {
+  try {
+    return userInfo().username;
+  } catch {
+    return "unknown";
+  }
+}
+
 // packages/cli/src/commands/approve.ts
 async function realConfirm(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -4788,15 +5067,16 @@ async function approveCommand(ctx, requestId) {
   const now = /* @__PURE__ */ new Date();
   if (requestId === void 0) {
     const pending = approvals.requests.filter((r) => r.status === "pending" && !isExpired(r, now));
-    return {
-      exitCode: EXIT.OK,
-      json: { ok: true, pending },
-      human: pending.length === 0 ? ["no pending approval requests"] : [
+    return summarized(
+      EXIT.OK,
+      { ok: true, pending },
+      approveListSummary(pending),
+      pending.length === 0 ? ["no pending approval requests"] : [
         "pending approval requests:",
         ...pending.map((r) => `  ${r.id}  ${r.action} on ${r.environment} (service ${r.serviceId}, expires ${r.expiresAt})`),
         "approve with: openpouch approve <id>"
       ]
-    };
+    );
   }
   const request = approvals.requests.find((r) => r.id === requestId);
   if (request === void 0) {
@@ -4826,7 +5106,7 @@ async function approveCommand(ctx, requestId) {
     `Approve "${request.action}" on ${request.environment} (service ${request.serviceId})? [y/N] `
   );
   if (!confirmed) {
-    return { exitCode: EXIT.OK, json: { ok: true, approved: false }, human: ["not approved"] };
+    return summarized(EXIT.OK, { ok: true, approved: false }, approveResultSummary(false), ["not approved"]);
   }
   const secret = await getApproverSecret(true, ctx.env["OPENPOUCH_HOME"]);
   if (secret === void 0) {
@@ -4837,14 +5117,15 @@ async function approveCommand(ctx, requestId) {
   request.approvedBy = approverName();
   request.signature = signApproval(request, secret);
   await saveApprovals(ctx.cwd, approvals);
-  return {
-    exitCode: EXIT.OK,
-    json: { ok: true, approved: true, request: { id: request.id, approvedBy: request.approvedBy, approvedAt: request.approvedAt } },
-    human: [
+  return summarized(
+    EXIT.OK,
+    { ok: true, approved: true, request: { id: request.id, approvedBy: request.approvedBy, approvedAt: request.approvedAt } },
+    approveResultSummary(true),
+    [
       `approved \u2713 ${request.id} (${request.action} on ${request.environment}) by ${request.approvedBy}`,
       "the agent can now re-run the deploy command"
     ]
-  };
+  );
 }
 
 // packages/cli/src/deploy-engine.ts
@@ -4956,12 +5237,14 @@ async function passPolicyGate(ctx, policy, environment, action, serviceId, rerun
     approvals.requests.push(request);
     await saveApprovals(ctx.cwd, approvals);
   }
+  const summary = approvalRequiredSummary(environment, request.id);
   return {
     ok: false,
     result: {
       exitCode: EXIT.POLICY,
       json: {
         ok: false,
+        summary,
         error: {
           category: "approval-required",
           message: `"${action}" on ${environment} requires human approval`,
@@ -4972,7 +5255,9 @@ async function passPolicyGate(ctx, policy, environment, action, serviceId, rerun
       human: [
         `approval required: "${action}" on ${environment}`,
         `request id: ${request.id} (expires ${request.expiresAt})`,
-        `next: a human runs \`openpouch approve ${request.id}\`, then re-run \`${rerunCommand}\``
+        `next: a human runs \`openpouch approve ${request.id}\`, then re-run \`${rerunCommand}\``,
+        "",
+        summary
       ]
     }
   };
@@ -5026,15 +5311,24 @@ async function deployCommand(ctx, environment) {
     });
     const exitCode = !result2.deployLive ? EXIT.DEPLOY_FAILED : result2.smokePassed === false ? EXIT.VERIFY_FAILED : EXIT.OK;
     const d = result2.record;
-    return {
+    return summarized(
       exitCode,
-      json: {
+      {
         ok: exitCode === EXIT.OK,
+        // R5: live link prominent at the top level when the deploy went live.
+        ...d.url !== void 0 && result2.deployLive ? { url: d.url } : {},
         deployment: d,
         smokePassed: result2.smokePassed ?? null,
         evidence: ["deploy.evidence.json", "DEPLOYMENT.md"]
       },
-      human: [
+      deploySummary({
+        environment,
+        live: result2.deployLive,
+        url: d.url,
+        smokePassed: result2.smokePassed,
+        approvedBy: d.approvedBy
+      }),
+      [
         `openpouch ${environment === "preview" ? "preview" : "prod"} ${exitCode === EXIT.OK ? "\u2713" : "\u2717"} ${manifest.project.name} \u2192 ${environment}`,
         `  deploy: ${d.id} [${d.status}]${d.commit !== void 0 ? ` commit ${d.commit.slice(0, 10)}` : ""}`,
         ...d.url !== void 0 ? [`  url: ${d.url}`] : [],
@@ -5043,7 +5337,7 @@ async function deployCommand(ctx, environment) {
         ...d.rollbackAnchor !== void 0 ? [`  rollback anchor: ${d.rollbackAnchor}`] : [],
         `  evidence: deploy.evidence.json + DEPLOYMENT.md updated`
       ]
-    };
+    );
   } catch (e) {
     if (isProviderApiError(e)) {
       return errorResult(e.category === "auth" ? EXIT.AUTH : EXIT.PROVIDER, e.category, e.message, e.fix);
@@ -5056,7 +5350,7 @@ async function deployCommand(ctx, environment) {
 import { join as join6 } from "node:path";
 
 // packages/cli/src/agentsmd.ts
-import { readFile as readFile4, writeFile as writeFile4 } from "node:fs/promises";
+import { readFile as readFile5, writeFile as writeFile5 } from "node:fs/promises";
 import { join as join4 } from "node:path";
 var AGENTS_MD_FILENAME = "AGENTS.md";
 var START = "<!-- openpouch:start -->";
@@ -5071,7 +5365,8 @@ function renderAgentsSection(projectName) {
     "",
     "- **Deployment truth** (what is live, where, which commit, rollback anchor): read `DEPLOYMENT.md` or `deploy.evidence.json`. Config lives in `deploy.manifest.json`, agent permissions in `deploy.policy.json`.",
     "- **CLI:** `openpouch inspect` \xB7 `plan` \xB7 `preview` (autonomous if policy allows) \xB7 `prod` \xB7 `verify` \xB7 `logs` \xB7 `rollback`. Add `--json` for a single machine-readable JSON object; errors come as `{category, message, fix}` \u2014 act on the fix. Exit codes are documented API.",
-    "- **MCP alternative:** the `openpouch-mcp` stdio server exposes the same capabilities as typed tools.",
+    "- **Relay the `summary` to your human:** every result (CLI `--json` and MCP) carries a top-level `summary` \u2014 plain-language, jargon-free text written for a non-technical operator. Pass it on verbatim: it says what happened, whether the app is live and healthy, the live link, and what (if anything) the human needs to do. The **live URL is the primary result** \u2014 on a successful deploy it's the top-level `url` field, ready to share.",
+    "- **MCP alternative:** the `openpouch-mcp` stdio server exposes the same capabilities as typed tools (the `summary` is also surfaced as a leading text block to relay).",
     "- **Production rule:** `prod` and `rollback` may return `approvalRequest{id}`. **You cannot approve it \u2014 no agent can.** Ask your human to run `openpouch approve <id>` in their own terminal, then re-run the command.",
     "- Never write secret values into any of these files; env vars are tracked by name only.",
     "",
@@ -5083,12 +5378,12 @@ async function upsertAgentsSection(cwd, projectName) {
   const section = renderAgentsSection(projectName);
   let existing;
   try {
-    existing = await readFile4(path, "utf8");
+    existing = await readFile5(path, "utf8");
   } catch {
     existing = void 0;
   }
   if (existing === void 0) {
-    await writeFile4(path, `# AGENTS.md
+    await writeFile5(path, `# AGENTS.md
 
 ${section}
 `, "utf8");
@@ -5105,12 +5400,12 @@ ${section}
 `;
   }
   if (next === existing) return "unchanged";
-  await writeFile4(path, next, "utf8");
+  await writeFile5(path, next, "utf8");
   return "updated";
 }
 
 // packages/cli/src/detect.ts
-import { readFile as readFile5, readdir } from "node:fs/promises";
+import { readFile as readFile6, readdir } from "node:fs/promises";
 import { basename, extname, join as join5 } from "node:path";
 var FRAMEWORK_BY_DEP = [
   ["next", "nextjs"],
@@ -5163,7 +5458,7 @@ async function scanEnvVarNames(root) {
   for (const file of await collectSourceFiles(root)) {
     let content;
     try {
-      const buf = await readFile5(file);
+      const buf = await readFile6(file);
       if (buf.byteLength > MAX_FILE_BYTES) continue;
       content = buf.toString("utf8");
     } catch {
@@ -5181,7 +5476,7 @@ async function scanEnvVarNames(root) {
 async function detectProject(cwd) {
   let pkg = {};
   try {
-    pkg = JSON.parse(await readFile5(join5(cwd, "package.json"), "utf8"));
+    pkg = JSON.parse(await readFile6(join5(cwd, "package.json"), "utf8"));
   } catch {
   }
   const deps = { ...pkg.dependencies, ...pkg.devDependencies };
@@ -5223,21 +5518,23 @@ function matchService(projectName, services) {
 async function initCommand(ctx, flags) {
   const existing = await loadManifest(ctx.cwd);
   if (existing.status !== "missing" && !flags.force) {
+    const existingName = existing.status === "ok" ? existing.manifest.project.name : "this project";
     const agentsMd2 = existing.status === "ok" ? await upsertAgentsSection(ctx.cwd, existing.manifest.project.name) : "unchanged";
-    return {
-      exitCode: EXIT.OK,
-      json: {
+    return summarized(
+      EXIT.OK,
+      {
         ok: true,
         alreadyInitialized: true,
         agentsMd: agentsMd2,
         hints: [`${MANIFEST_FILENAME} exists \u2014 use --force to regenerate, or run \`openpouch inspect\``]
       },
-      human: [
+      initSummary({ name: existingName, alreadyInitialized: true }),
+      [
         `openpouch init: already initialized (${MANIFEST_FILENAME} exists)`,
         ...agentsMd2 !== "unchanged" ? [`  ${AGENTS_MD_FILENAME}: openpouch section ${agentsMd2}`] : [],
         "hint: use --force to regenerate, or run `openpouch inspect`"
       ]
-    };
+    );
   }
   const detected = await detectProject(ctx.cwd);
   const hints = [];
@@ -5293,9 +5590,9 @@ async function initCommand(ctx, flags) {
   await writeJsonFile(join6(ctx.cwd, POLICY_FILENAME), defaultPolicy());
   const agentsMd = await upsertAgentsSection(ctx.cwd, detected.name);
   hints.push("policy default: previews autonomous, production requires approval \u2014 edit deploy.policy.json to change");
-  return {
-    exitCode: EXIT.OK,
-    json: {
+  return summarized(
+    EXIT.OK,
+    {
       ok: true,
       created: [MANIFEST_FILENAME, POLICY_FILENAME],
       detected: {
@@ -5309,7 +5606,12 @@ async function initCommand(ctx, flags) {
       agentsMd,
       hints
     },
-    human: [
+    initSummary({
+      name: detected.name,
+      framework: detected.framework,
+      ...matched !== void 0 ? { matchedProvider: "render" } : {}
+    }),
+    [
       `openpouch init \u2713 ${detected.name}${detected.framework !== void 0 ? ` (${detected.framework})` : ""}`,
       `  created: ${MANIFEST_FILENAME}, ${POLICY_FILENAME}`,
       `  ${AGENTS_MD_FILENAME}: openpouch section ${agentsMd} (cross-harness discovery)`,
@@ -5320,12 +5622,12 @@ async function initCommand(ctx, flags) {
       ...hints.map((h) => `  hint: ${h}`),
       "  next: openpouch inspect"
     ]
-  };
+  );
 }
 
 // packages/cli/src/commands/instant.ts
 import { spawn } from "node:child_process";
-import { readFile as readFile6 } from "node:fs/promises";
+import { readFile as readFile7 } from "node:fs/promises";
 import { basename as basename2, join as join7 } from "node:path";
 var TAR_EXCLUDES = [
   "./node_modules",
@@ -5355,7 +5657,7 @@ function buildTarball(cwd) {
 }
 async function projectHint(cwd) {
   try {
-    const pkg = JSON.parse(await readFile6(join7(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(await readFile7(join7(cwd, "package.json"), "utf8"));
     if (pkg.name) return pkg.name.replace(/^@[^/]+\//, "");
   } catch {
   }
@@ -5364,12 +5666,16 @@ async function projectHint(cwd) {
 async function instantCommand(ctx) {
   const loaded = await loadManifest(ctx.cwd);
   if (loaded.status === "ok") {
-    return errorResult(
-      EXIT.USAGE,
-      "usage",
-      "this project already has deploy.manifest.json",
-      "Use `openpouch preview` / `openpouch prod` for a configured project. `openpouch deploy` is the zero-config instant lane."
-    );
+    const envs = Object.values(loaded.manifest.environments ?? {});
+    const hasGovernedEnv = envs.some((e) => e.provider !== "openpouch-run");
+    if (hasGovernedEnv) {
+      return errorResult(
+        EXIT.USAGE,
+        "usage",
+        "this project already has deploy.manifest.json",
+        "Use `openpouch preview` / `openpouch prod` for a configured project. `openpouch deploy` is the zero-config instant lane."
+      );
+    }
   }
   let tarball;
   try {
@@ -5381,7 +5687,8 @@ async function instantCommand(ctx) {
     return errorResult(EXIT.USAGE, "usage", "nothing to deploy", "The directory appears empty after excludes.");
   }
   const hint = await projectHint(ctx.cwd);
-  const adapter = makeAdapter(ctx, "openpouch-run", "anonymous");
+  const runKey = await resolveProviderApiKey(ctx.env, "openpouch-run") ?? "anonymous";
+  const adapter = makeAdapter(ctx, "openpouch-run", runKey);
   if (typeof adapter.instantDeploy !== "function") {
     return errorResult(EXIT.UNEXPECTED, "provider", "instant lane adapter unavailable", "This is an internal wiring error.");
   }
@@ -5406,27 +5713,33 @@ async function instantCommand(ctx) {
       deployedAt: (/* @__PURE__ */ new Date()).toISOString(),
       notes: `instant preview \u2014 expires ${result2.expiresAt}; claim: ${result2.claimUrl}`
     });
-    return {
-      exitCode: EXIT.OK,
-      json: {
+    const kind = result2.kind ?? "static";
+    return summarized(
+      EXIT.OK,
+      {
         ok: true,
+        // R5: the live link is the primary, immediately shareable result — top-level.
+        url: result2.url,
+        claimUrl: result2.claimUrl,
         deployment: {
           id: result2.slug,
           url: result2.url,
           claimUrl: result2.claimUrl,
           expiresAt: result2.expiresAt,
-          status: result2.status
+          status: result2.status,
+          kind
         },
         evidence: ["deploy.manifest.json", "deploy.policy.json", "deploy.evidence.json", "DEPLOYMENT.md"]
       },
-      human: [
-        `openpouch deploy \u2713 ${hint} \u2192 instant preview`,
+      instantDeploySummary({ name: hint, url: result2.url, claimUrl: result2.claimUrl, expiresAt: result2.expiresAt }),
+      [
+        `openpouch deploy \u2713 ${hint} \u2192 instant preview${kind === "dynamic" ? " (dynamic app \u2014 running in a container)" : ""}`,
         `  url:     ${result2.url}`,
         `  expires: ${result2.expiresAt} (unclaimed previews vanish after 72h)`,
         `  claim:   ${result2.claimUrl}`,
         `  wrote:   deploy.manifest.json, deploy.policy.json, deploy.evidence.json, DEPLOYMENT.md`
       ]
-    };
+    );
   } catch (e) {
     if (isProviderApiError(e)) {
       return errorResult(EXIT.PROVIDER, e.category, e.message, e.fix);
@@ -5555,16 +5868,17 @@ async function inspectCommand(ctx) {
     }
   }
   human.push(...hints.map((h) => `  hint: ${h}`));
-  return {
-    exitCode: EXIT.OK,
-    json: {
+  return summarized(
+    EXIT.OK,
+    {
       ok: true,
       project: { name: manifest.project.name, framework: manifest.project.framework ?? null },
       environments,
       hints
     },
+    inspectSummary(manifest.project.name, environments),
     human
-  };
+  );
 }
 
 // packages/cli/src/commands/logs.ts
@@ -5590,14 +5904,15 @@ async function logsCommand(ctx, environment, limit) {
   const adapter = makeAdapter(ctx, cfg.provider, apiKey);
   try {
     const lines = await adapter.getLogs(cfg.serviceId, { limit });
-    return {
-      exitCode: EXIT.OK,
-      json: { ok: true, environment, serviceId: cfg.serviceId, count: lines.length, logs: lines },
-      human: [
+    return summarized(
+      EXIT.OK,
+      { ok: true, environment, serviceId: cfg.serviceId, count: lines.length, logs: lines },
+      logsSummary(environment, lines.length),
+      [
         `openpouch logs \u2014 ${environment} (${cfg.serviceId}), ${lines.length} lines:`,
         ...lines.map((l) => `  ${l.timestamp ?? ""} ${l.message}`.trimEnd())
       ]
-    };
+    );
   } catch (e) {
     if (isProviderApiError(e)) {
       return errorResult(e.category === "auth" ? EXIT.AUTH : EXIT.PROVIDER, e.category, e.message, e.fix);
@@ -5667,11 +5982,12 @@ async function planCommand(ctx) {
   }
   if (Object.keys(plans).length === 0) human.push("  no environments mapped \u2014 run `openpouch init --force` or edit the manifest");
   human.push(...hints.map((h) => `  hint: ${h}`));
-  return {
-    exitCode: EXIT.OK,
-    json: { ok: true, project: manifest.project.name, environments: plans, hints },
+  return summarized(
+    EXIT.OK,
+    { ok: true, project: manifest.project.name, environments: plans, hints },
+    planSummary(manifest.project.name, plans),
     human
-  };
+  );
 }
 
 // packages/cli/src/commands/rollback.ts
@@ -5732,22 +6048,24 @@ async function rollbackCommand(ctx, environment) {
     });
     const exitCode = !result2.deployLive ? EXIT.DEPLOY_FAILED : result2.smokePassed === false ? EXIT.VERIFY_FAILED : EXIT.OK;
     const d = result2.record;
-    return {
+    return summarized(
       exitCode,
-      json: {
+      {
         ok: exitCode === EXIT.OK,
+        ...d.url !== void 0 && result2.deployLive ? { url: d.url } : {},
         rolledBackTo: { commit: anchorDeploy.commit, anchorDeploy: latest.rollbackAnchor },
         deployment: d,
         smokePassed: result2.smokePassed ?? null
       },
-      human: [
+      rollbackSummary({ environment, live: result2.deployLive, url: d.url, smokePassed: result2.smokePassed }),
+      [
         `openpouch rollback ${exitCode === EXIT.OK ? "\u2713" : "\u2717"} ${environment} \u2192 commit ${anchorDeploy.commit.slice(0, 10)}`,
         `  deploy: ${d.id} [${d.status}]`,
         ...result2.smokePassed !== void 0 ? [`  smoke: ${result2.smokePassed ? "passed" : "FAILED"}`] : [],
         ...d.approvedBy !== void 0 ? [`  approved by: ${d.approvedBy}`] : [],
         `  evidence: deploy.evidence.json + DEPLOYMENT.md updated`
       ]
-    };
+    );
   } catch (e) {
     if (isProviderApiError(e)) {
       return errorResult(e.category === "auth" ? EXIT.AUTH : EXIT.PROVIDER, e.category, e.message, e.fix);
@@ -5756,6 +6074,57 @@ async function rollbackCommand(ctx, environment) {
   }
 }
 
+// packages/cli/src/commands/signup.ts
+async function signupCommand(ctx, opts) {
+  const adapter = makeAdapter(ctx, "openpouch-run", "anonymous");
+  if (opts.github === true) {
+    const url = typeof adapter.githubStartUrl === "function" ? adapter.githubStartUrl() : "";
+    return summarized(
+      EXIT.OK,
+      { ok: true, method: "github", startUrl: url },
+      signupGithubSummary(url),
+      ["openpouch signup (GitHub)", `  Open this URL in your browser and approve: ${url}`, "  You'll get your API key on the page that follows."]
+    );
+  }
+  const email = opts.email?.trim();
+  if (!email) {
+    return errorResult(
+      EXIT.USAGE,
+      "usage",
+      "no signup method given",
+      "Use `openpouch signup --email <you@example.com>` or `openpouch signup --github`."
+    );
+  }
+  if (typeof adapter.signupEmail !== "function") {
+    return errorResult(EXIT.UNEXPECTED, "provider", "signup unavailable", "This is an internal wiring error.");
+  }
+  try {
+    const res = await adapter.signupEmail(email);
+    return summarized(
+      EXIT.OK,
+      {
+        ok: true,
+        method: "email",
+        accountId: res.accountId,
+        message: res.message,
+        ...res.devVerifyToken ? { devVerifyToken: res.devVerifyToken } : {}
+      },
+      signupEmailSummary(email),
+      [
+        `openpouch signup \u2713 ${email}`,
+        `  account: ${res.accountId}`,
+        `  ${res.message}`,
+        ...res.devVerifyToken ? [`  finish: openpouch activate --account ${res.accountId} --token ${res.devVerifyToken}`] : [`  then:   openpouch activate --account ${res.accountId} --token <token-from-email>`]
+      ]
+    );
+  } catch (e) {
+    if (isProviderApiError(e)) {
+      return errorResult(EXIT.PROVIDER, e.category, e.message, e.fix);
+    }
+    throw e;
+  }
+}
+
 // packages/cli/src/commands/verify.ts
 async function verifyCommand(ctx, environment) {
   const loaded = await loadManifest(ctx.cwd);
@@ -5788,15 +6157,62 @@ async function verifyCommand(ctx, environment) {
       evidenceUpdated = true;
     }
   }
-  return {
-    exitCode: passed ? EXIT.OK : EXIT.VERIFY_FAILED,
-    json: { ok: passed, environment, url: cfg.url, checks: smoke, evidenceUpdated },
-    human: [
+  return summarized(
+    passed ? EXIT.OK : EXIT.VERIFY_FAILED,
+    { ok: passed, environment, url: cfg.url, checks: smoke, evidenceUpdated },
+    verifySummary({ environment, url: cfg.url, passed, checks: smoke }),
+    [
       `openpouch verify ${passed ? "\u2713" : "\u2717"} ${environment} (${cfg.url})`,
       ...smoke.map((s) => `  ${s.passed ? "\u2713" : "\u2717"} ${s.name} \u2014 ${s.detail ?? ""}`),
       evidenceUpdated ? "  evidence: smoke results appended to latest record" : "  evidence: no deployment record for this environment yet"
     ]
-  };
+  );
+}
+
+// packages/cli/src/commands/whoami.ts
+async function whoamiCommand(ctx) {
+  const key = await resolveProviderApiKey(ctx.env, "openpouch-run") ?? ANONYMOUS_KEY;
+  if (key === ANONYMOUS_KEY) {
+    return summarized(
+      EXIT.OK,
+      { ok: true, authenticated: false },
+      whoamiSummary({ authenticated: false }),
+      [
+        "openpouch whoami \u2014 not signed in (anonymous instant lane)",
+        "  Deploys use the free anonymous tier.",
+        "  Create an account: openpouch signup --email <you@example.com>  (or --github)"
+      ]
+    );
+  }
+  const adapter = makeAdapter(ctx, "openpouch-run", key);
+  if (typeof adapter.whoami !== "function") {
+    return errorResult(EXIT.UNEXPECTED, "provider", "account lookup unavailable", "This is an internal wiring error.");
+  }
+  try {
+    const status = await adapter.whoami();
+    const identities = status.account.identities.map((i) => i.label ?? i.value).join(", ") || "\u2014";
+    return summarized(
+      EXIT.OK,
+      { ok: true, authenticated: true, account: status.account, tier: status.tier, usage: status.usage },
+      whoamiSummary({
+        authenticated: true,
+        tier: status.tier.name,
+        liveDeployments: status.usage.liveDeployments,
+        maxLive: status.tier.maxLiveDeployments
+      }),
+      [
+        `openpouch whoami \u2713 ${status.account.id} [${status.tier.name}]`,
+        `  identities: ${identities}`,
+        `  live apps:  ${status.usage.liveDeployments}/${status.tier.maxLiveDeployments} (${status.usage.dynamicDeployments} running)`,
+        `  deploys:    ${status.usage.deploysLastHour}/hour, ${status.usage.deploysLastDay}/day`
+      ]
+    );
+  } catch (e) {
+    if (isProviderApiError(e)) {
+      return errorResult(e.category === "auth" ? EXIT.AUTH : EXIT.PROVIDER, e.category, e.message, e.fix);
+    }
+    throw e;
+  }
 }
 
 // packages/cli/src/main.ts
@@ -5806,7 +6222,10 @@ var USAGE = [
   "usage: openpouch <command> [--json]",
   "",
   "commands:",
-  "  deploy         zero-config instant preview on openpouch's own infra (no account/key; deploy-then-claim)",
+  "  deploy         zero-config instant preview on openpouch's own infra (anonymous, or under your account if a key is set)",
+  "  signup         create an openpouch account: --email <addr> or --github (gives you an API key)",
+  "  activate       finish an email signup: --account <id> --token <token> (saves your API key)",
+  "  whoami         show the account behind your API key: tier + current usage",
   "  init           detect the project, write deploy.manifest.json + deploy.policy.json (idempotent; --force regenerates)",
   "  inspect        answer: what is deployed, where, on which commit, which env vars are missing",
   "  plan           per environment: policy decision, blockers, readiness, next steps",
@@ -5822,7 +6241,13 @@ var USAGE = [
   "  --force        (init) overwrite existing manifest/policy",
   "  --env <name>   (verify/logs/rollback) target environment, default: production",
   "  --limit <n>    (logs) number of log lines, default: 50",
+  "  --email <addr> (signup) create an account anchored to this email",
+  "  --github       (signup) create an account via GitHub (prints the authorize URL)",
+  "  --account <id> (activate) the account id from signup",
+  "  --token <tok>  (activate) the verification token from the signup email",
+  "  --key-file <p> (activate) where to save the issued key (default ~/.openpouch/openpouch-run.key; never overwrites a non-openpouch file)",
   "",
+  "account key: deploys send Authorization: Bearer from OPENPOUCH_API_KEY or ~/.openpouch/openpouch-run.key (override the path with OPENPOUCH_KEY_FILE; optional \u2014 no key = anonymous)",
   "exit codes: 0 ok \xB7 1 unexpected \xB7 2 usage \xB7 3 manifest/policy missing or invalid \xB7 4 auth \xB7 5 provider \xB7 6 policy gate (approval required/denied/human required) \xB7 7 deploy failed \xB7 8 verify failed"
 ].join("\n");
 function render(result2, json) {
@@ -5840,8 +6265,13 @@ async function run(argv, ctx) {
         json: { type: "boolean", default: false },
         force: { type: "boolean", default: false },
         help: { type: "boolean", default: false },
+        github: { type: "boolean", default: false },
         env: { type: "string" },
-        limit: { type: "string" }
+        limit: { type: "string" },
+        email: { type: "string" },
+        account: { type: "string" },
+        token: { type: "string" },
+        "key-file": { type: "string" }
       },
       allowPositionals: true
     });
@@ -5867,6 +6297,19 @@ async function run(argv, ctx) {
     switch (command) {
       case "deploy":
         return render(await instantCommand(ctx), json);
+      case "signup":
+        return render(await signupCommand(ctx, { email: parsed.values.email, github: parsed.values.github === true }), json);
+      case "activate":
+        return render(
+          await activateCommand(ctx, {
+            account: parsed.values.account,
+            token: parsed.values.token,
+            keyFile: parsed.values["key-file"]
+          }),
+          json
+        );
+      case "whoami":
+        return render(await whoamiCommand(ctx), json);
       case "init":
         return render(await initCommand(ctx, { force: parsed.values.force === true }), json);
       case "inspect":

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openpouch",
-  "version": "0.1.0",
-  "description": "openpouch 🦘 — the agent-native deployment control plane. Deploy any folder to a live URL in one command: npx openpouch deploy",
+  "version": "0.2.1",
+  "description": "openpouch 🦘 — agent-native hosting, built for coding agents. Deploy any folder to a live URL in one command: npx openpouch deploy",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
     "vercel",
     "preview"
   ],
-  "homepage": "https://openpouch.sh",
+  "homepage": "https://openpouch.dev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/openpouch/openpouch.git"