@pingroom/cli 0.6.0 → 0.6.1

package/README.md

@@ -6,21 +6,51 @@ from CI, scripts, and agents. Delivered as push straight to your phone.
 One dependency (`qrcode-terminal`, used only to draw the pairing QR). Works
 anywhere Node ≥ 20 runs.
 
+> **Release status:** npm currently serves 0.6.0. The automatic verified-phone
+> activation flow and `pingroom activate` documented below are in the tested
+> 0.6.1 release candidate on `main`; the public GitHub Action remains pinned to
+> 0.6.0 until 0.6.1 is published and clean-install verified.
+
+## Install and first run
+
+Install globally, then connect:
+
+```bash
+npm install --global @pingroom/cli
+pingroom
+```
+
+Or use it without a global install:
+
 ```bash
-npx @pingroom/cli ping -w "$PINGROOM_WEBHOOK_URL" -m "Deploy succeeded ✅"
+npx --yes @pingroom/cli
+```
+
+Either command starts the same connection prompt. QR pairing stores the selected
+account, credential, and delivery room in `~/.pingroom`; later commands reuse
+them, so a local invocation needs neither `PINGROOM_TOKEN` nor `PINGROOM_ROOM`.
+The email fallback stores the credential only. Setting
+`pingroom config set default_room <invite-code>` enables room-addressed commands,
+but private Agent Inbox and Handoff delivery require a connection approved with
+a delivery room. Use QR pairing for the complete flow.
+
+```bash
+pingroom ping -m "Deploy succeeded ✅"
+# or: npx --yes @pingroom/cli ping -m "Deploy succeeded ✅"
 ```
 
 Commands: `ping` (send), `ask` (ask a human), `watch` (block on an existing
 question), `list`, `cancel`, `handoff` (hand a decision to a specific human),
 `handoffs` (list open or recent Handoffs), `live` (lock-screen progress card),
-`hook` (Claude Code), `config`, and `logout`.
+`hook` (Claude Code), `mcp` (client setup), `activate` (retry the Agent Inbox
+test), `config`, and `logout`.
 Run `pingroom --help` for the full reference.
 
 ## Connecting
 
-Run `pingroom` with no arguments. It prints a QR code — scan it with the PingRoom
-app and pick both the account and the room the agent delivers to — or take the
-emailed-code fallback.
+Run `pingroom` (global install) or `npx --yes @pingroom/cli` (no install) with no
+arguments. It prints a QR code — scan it with the PingRoom app and pick both the
+account and the room the agent delivers to — or take the emailed-code fallback.
 
 ```
 $ pingroom
@@ -32,8 +62,38 @@ $ pingroom
   [QR]
   Or open: https://pingroom.io/app/agents/pair?token=…
   Waiting for approval… ✓ Connected as @agt_ab12cd34ef → #Project X
+  Sending a test question to PingRoom…
+  Answer “PingRoom connected. Can you answer this?” on your phone.
+✓ Test question answered (Yes). Agent Inbox is ready.
+```
+
+After QR approval, the CLI saves the active credential first, then sends one
+idempotent onboarding Question and observes it through the Handoff wait API.
+Short network and server failures are retried, and `Retry-After` is honored for
+rate limits within the two-minute overall deadline. An answer alone is not
+reported as success: the terminal response must also carry the server's exact
+`activation_completed: true` stamp. On supporting server and mobile builds,
+that stamp means the native phone returned the opaque proof carried in the push
+before the human answer, and this CLI then observed the result. An answered
+response whose stamp is false or missing is incomplete and is not retried as if
+history could be rewritten. If the Question is still pending when the local
+deadline elapses, or activation cannot start, the CLI prints the recovery
+command and exits with the connection still saved and usable. A terminal test
+without the stamp requires a current PingRoom app and a fresh numbered attempt;
+run `pingroom activate` again with the saved connection.
+
+Resume an open idempotent check with the saved QR credential:
+
+```bash
+pingroom activate
 ```
 
+An incomplete explicit retry exits `1`; it never deletes or replaces the saved
+credential. The command does not fall back to `PINGROOM_TOKEN`, an email-only
+credential, or a credential without `pingroom:handoffs:create` and a
+QR-selected delivery room. Email-code and other non-interactive credential
+flows do not run the phone-response loop automatically.
+
 There is deliberately no `login` command: being unconnected is a state the tool
 resolves, not one you have to discover. Once connected, bare `pingroom` prints
 that status line followed by the usual help.
@@ -67,6 +127,11 @@ So `--room` beats `PINGROOM_ROOM` beats `default_room` (and, last of all, the
 room the credential was paired to); `--api` beats `PINGROOM_API_URL` beats
 `api_url`.
 
+A stored paired credential is bound to the API origin that issued it. An API
+override can change the path on that origin, but the CLI refuses to send the
+stored bearer to a different origin. For an intentional custom-host override,
+provide that host's token explicitly with `--token` or `PINGROOM_TOKEN`.
+
 ## Getting a webhook URL
 
 In the PingRoom app, open a room → **Connections → Incoming webhooks → Add**. Copy the
@@ -85,6 +150,7 @@ pingroom ping [options]
       --button-label <t> Link button text (<= 26 chars; requires --url)
       --require-ack      Keep the ping open until an eligible recipient acknowledges it
       --ack-timeout <s>  Ack deadline in seconds (requires --require-ack)
+      --attach <path>    Attach a file; repeat for up to 10 (requires --token)
   -w, --webhook <url>    Room webhook URL (or env PINGROOM_WEBHOOK_URL)
       --token <token>    Agent access token (or env PINGROOM_TOKEN)
       --room <code>      Room invite code (used with --token)
@@ -115,6 +181,21 @@ pingroom ping -w "$PINGROOM_WEBHOOK_URL" -m "Build 512 ready" \
 
 The URL must be absolute http(s) (≤ 2048 chars); the label caps at 26 chars.
 
+To send the file itself rather than a link to it, use `--attach`. Each file is
+uploaded separately and only the resulting ids ride the ping; recipients open
+them from the ping, authenticated:
+
+```bash
+pingroom ping --token "$PINGROOM_TOKEN" --room AB12 -m "Nightly report" \
+  --attach ./report.pdf --attach ./summary.md
+```
+
+Accepted types are `md`, `pdf`, `html`, `txt`, `jpg`, `jpeg`, `png`, up to
+20 MiB each and 10 per ping. `--attach` needs an agent token — a webhook ping
+has no uploader identity to bind private files to — and the bound account must
+hold Pro (otherwise the upload fails with `pro_required`). An upload that never
+reaches a ping expires by itself after 24 hours.
+
 Exit codes: `0` success · `1` delivery failed · `2` bad usage. So CI fails loudly if a
 ping doesn't land.
 
@@ -360,13 +441,19 @@ Print a ready-to-paste config:
 
 ```bash
 pingroom hook --print-config
+# no global install: npx --yes @pingroom/cli hook --print-config
 ```
 
-Then set your credentials and merge the printed `hooks` block into
-`~/.claude/settings.json`:
+If you have not connected yet, run `pingroom` (or `npx --yes @pingroom/cli`) and
+scan the QR first. The hook reads the stored credential and the room selected
+during pairing automatically. No environment variables are needed for a normal
+local setup; merge the printed `hooks` block into `~/.claude/settings.json`.
+
+Environment variables remain available for CI and other headless shells, and
+take precedence over the paired values:
 
 ```bash
-export PINGROOM_TOKEN="<your agent token>"   # a room the agent belongs to
+export PINGROOM_TOKEN="<your agent token>"
 export PINGROOM_ROOM="<room invite code>"
 ```
 
@@ -386,8 +473,23 @@ blocks the agent. Because the `PreToolUse` hook holds the tool call open while i
 waits for you, give it a generous `timeout` (the printed config uses 960s) and
 tune the approval-question expiry with `--ttl <seconds>` (default 900).
 
+## MCP client setup
+
+Print the canonical remote endpoint, a copy-ready Claude Code command, Cursor
+JSON, and the Claude Desktop custom-connector steps:
+
+```bash
+pingroom mcp
+# no global install: npx --yes @pingroom/cli mcp
+```
+
+`pingroom mcp add claude-code` prints the exact `claude mcp add` command but does
+not execute it or modify client configuration. After adding the server, use the
+client's MCP controls to authenticate in the browser; no PingRoom API key is
+pasted into its config.
+
 For a fully typed client, use [`@pingroom/sdk`](https://www.npmjs.com/package/@pingroom/sdk).
-See <https://pingroom.io/connect-mcp.md> to connect Cursor, Claude Desktop, or Claude Code.
+See <https://pingroom.io/connect-mcp.md> for the complete MCP and OAuth guide.
 
 ## License
 

package/bin/pingroom.js

@@ -21,6 +21,8 @@
 //   handoffs List the agent's open handoffs or bounded recent history.
 //   live     Drive a live progress card (iOS Live Activity / Android live
 //            update) on the room members' lock screen: start / update / end.
+//   mcp      Print the canonical remote MCP endpoint and client setup snippets.
+//   activate Retry Agent Inbox activation with the saved QR-paired credential.
 //   config   Read/write ~/.pingroom/config.json (default_room, api_url).
 //   logout   Forget the credential in ~/.pingroom/credentials.json.
 //
@@ -35,12 +37,13 @@ import {
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-// Kept in lockstep with package.json / package-lock.json / action.yml (a test
-// asserts the GitHub Action pins this exact version). `hook --print-config`
-// emits an `npx @pingroom/cli@<VERSION>` command, so it must match too.
-const VERSION = '0.6.0';
+// Kept in lockstep with package.json / package-lock.json. The GitHub Action is
+// pinned independently to the latest version already published on npm; a test
+// makes that release gate explicit. `hook --print-config` emits this candidate.
+const VERSION = '0.6.1';
 
 const BUILTIN_API = 'https://api.pingroom.io';
+const MCP_ENDPOINT = `${BUILTIN_API}/api/agent/mcp`;
 const DEFAULT_API = process.env.PINGROOM_API_URL || BUILTIN_API;
 
 const HELP = `pingroom — send a ping, or ask a human a question, from CI/scripts/agents
@@ -60,6 +63,9 @@ Commands:
   live     Drive a live progress card on the lock screen (Live Activity)
   hook     Claude Code hook: ping on Stop/Notification, and route tool
            permission prompts to a PingRoom question you answer from your phone
+  mcp      Print the remote MCP endpoint and setup for Claude Code, Cursor, and
+           Claude Desktop
+  activate Retry Agent Inbox activation with the saved QR-paired credential
   config   Read/write local settings (config list | get <key> | set <key> <val>)
   logout   Forget the stored credential
 
@@ -72,6 +78,8 @@ ping options:
       --button-label <t> Link button text (<= 26 chars; requires --url)
       --require-ack      Keep the ping open until an eligible recipient acknowledges it
       --ack-timeout <s>  Ack deadline in seconds (requires --require-ack)
+      --attach <path>    Attach a file (md/pdf/html/txt/jpg/jpeg/png, <= 20 MiB);
+                         repeat for up to 10. Requires --token and a Pro account
   -w, --webhook <url>    Room webhook URL (or env PINGROOM_WEBHOOK_URL)
       --token <token>    Agent access token (or env PINGROOM_TOKEN)
       --room <code>      Room invite code (used with --token)
@@ -145,12 +153,21 @@ live <start|update|end|get> options (agent token, or a room webhook):
       --room <code>          Room invite code (used with --token)
   -w, --webhook <url>        Room webhook URL instead of a token
 
-hook options (agent token required; reads a Claude Code hook event on stdin):
-      --room <code>      Room invite code (or env PINGROOM_ROOM)
+hook options (reads a Claude Code event; defaults to stored credentials/config):
+      --room <code>      Room invite code (or env/config/paired room)
       --ttl <seconds>    Approval-question expiry for PreToolUse (default 900)
       --quiet            Suppress the informational stderr lines
       --print-config     Print a ready-to-paste ~/.claude/settings.json block
 
+mcp:
+  pingroom mcp                     Print the endpoint and client setup snippets
+  pingroom mcp add claude-code     Print the Claude Code setup command
+                                   (output-only; does not change client config)
+
+activate:
+  pingroom activate                Replay or create the next Agent Inbox test using
+                                   the saved QR-paired credential
+
 config options:
   pingroom config list              Print the stored settings
   pingroom config get <key>         Print one setting
@@ -162,12 +179,26 @@ Shared:
       --api <url>        API base URL (default ${DEFAULT_API}; env PINGROOM_API_URL)
       --json             Print the raw JSON response
   -h, --help             Show this help
+  -v, --version          Show the CLI version
 
 Connecting:
-  Run "pingroom" with no arguments to connect. It prints a QR code you scan with
-  the PingRoom app — you pick the account and the delivery room there — or you
-  can choose the emailed-code fallback. There is no "login" command: being
-  unconnected is a state the tool resolves, not one you have to discover.
+  Install globally, then run with no arguments:
+    npm install --global @pingroom/cli
+    pingroom
+
+  Or connect without installing globally:
+    npx --yes @pingroom/cli
+
+  It prints a QR code you scan with the PingRoom app — you pick the account and
+  delivery room there. Once paired, it saves the credential, sends one test
+  Question, and waits briefly for the server to confirm the completed phone
+  round-trip; an answer alone is not treated as activation, and a setup problem
+  never discards the usable connection. Run "pingroom activate" to retry that
+  test later. The emailed-code fallback stores no server-side delivery room.
+  "config set default_room" enables room-addressed commands, but private
+  Inbox/Handoff delivery requires QR pairing.
+  There is no "login" command: being unconnected is a state the tool resolves,
+  not one you have to discover.
 
   The credential is written to ~/.pingroom/credentials.json (mode 0600, in a
   0700 directory). PINGROOM_HOME overrides that directory. PINGROOM_TOKEN in the
@@ -179,8 +210,10 @@ Connecting:
     credential  >  built-in default
   So --room beats PINGROOM_ROOM beats "config set default_room", and --api beats
   PINGROOM_API_URL beats "config set api_url" beats the host you paired against,
-  beats ${BUILTIN_API}. The credential layer is why a token minted by a
-  self-hosted server is never presented to ${BUILTIN_API}.
+  beats ${BUILTIN_API}. A stored credential is bound to the origin it was paired
+  against: an API override may change the path on that origin, but a different
+  origin is refused before the token is sent. To target another origin
+  intentionally, provide that host's token with --token or PINGROOM_TOKEN.
 
   Non-interactive shells (CI, pipes) never prompt and never draw a QR: set
   PINGROOM_TOKEN there instead.
@@ -225,15 +258,22 @@ Examples:
   # ...or end it as a failure, which still delivers one completion alert:
   #   pingroom live end ... --failed -m "Rollback triggered"
 
-  # Connect Claude Code to your phone (prints the settings.json to paste):
+  # Connect Claude Code hooks to your paired credential (no env vars needed):
   pingroom hook --print-config
 
+  # Connect an MCP client through browser OAuth (no API key needed):
+  pingroom mcp
+
 Security:
   Prefer the env vars (PINGROOM_WEBHOOK_URL / PINGROOM_TOKEN) over passing
   secrets as --webhook / --token flags: argv is visible to other users via the
   process table (ps) and may be captured in shell history. URLs must use https
   (loopback http is allowed for local dev).
 
+  A paired credential is only sent to its recorded API origin. --api,
+  PINGROOM_API_URL and config.api_url cannot redirect that stored bearer to a
+  different origin; provide an explicit --token or PINGROOM_TOKEN to override.
+
 Exit codes: 0 on success (answered / acked), 1 on error (network/auth/5xx),
 2 on bad usage, 3 when a handoff or question expired, 4 when it was cancelled
 or the recipient was not ready (409 recipient_not_ready). A question answered
@@ -338,6 +378,11 @@ function resolveToken(args) {
  * this layer the next command would present that bearer to api.pingroom.io —
  * leaking it to a host it was never issued for. resolveRoom() already consults
  * the credential last, so the two layerings now agree.
+ *
+ * It is also an issuer boundary when resolveToken() falls through to the stored
+ * credential. Overrides may change the path on the same origin, but
+ * requireStoredCredentialOrigin() refuses a different origin unless the caller
+ * supplies an explicit --token or PINGROOM_TOKEN for that host.
  */
 function resolveApiBase(args) {
   const raw = args.api
@@ -348,6 +393,38 @@ function resolveApiBase(args) {
   return String(raw).replace(/\/$/, '');
 }
 
+/**
+ * A paired bearer belongs to the API origin that minted it. API settings still
+ * resolve independently so callers can select a path or an intentional custom
+ * host, but a stored token may only follow them within its recorded origin.
+ * Supplying --token / PINGROOM_TOKEN makes the token source explicit and opts
+ * out of this stored-credential binding.
+ */
+function storedCredentialOriginError(args, apiBase) {
+  if (args.token || process.env.PINGROOM_TOKEN) return null;
+
+  const credential = readStoredCredential();
+  if (!credential || typeof credential.api_url !== 'string' || credential.api_url === '') return null;
+
+  let credentialOrigin;
+  let targetOrigin;
+  try {
+    credentialOrigin = new URL(credential.api_url).origin;
+    targetOrigin = new URL(apiBase).origin;
+  } catch {
+    // URL validation owns malformed values. This guard only compares origins.
+    return null;
+  }
+
+  if (credentialOrigin === targetOrigin) return null;
+  return `stored credential is bound to ${credentialOrigin}; refusing to send it to ${targetOrigin}. Provide --token or PINGROOM_TOKEN for an intentional API origin override`;
+}
+
+function requireStoredCredentialOrigin(args, apiBase) {
+  const error = storedCredentialOriginError(args, apiBase);
+  if (error) fail(error, EXIT.USAGE);
+}
+
 /**
  * Room invite code: --room > PINGROOM_ROOM > config.default_room > the room the
  * credential was paired to. The paired room is last because it is the weakest
@@ -404,6 +481,7 @@ function parseArgs(argv) {
     '--button-label': 'button_label',
     '--require-ack': 'require_ack',
     '--ack-timeout': 'ack_timeout',
+    '--attach': 'attach',
     '--token': 'token',
     '--room': 'room',
     '--api': 'api',
@@ -411,6 +489,7 @@ function parseArgs(argv) {
     '-h': 'help', '--help': 'help',
   };
   const booleans = new Set(['require_ack', 'json', 'help']);
+  const repeatable = new Set(['attach']);
 
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i];
@@ -426,7 +505,8 @@ function parseArgs(argv) {
       if (value === undefined) {
         fail(`option ${token} needs a value`, EXIT.USAGE);
       }
-      args[key] = value;
+      if (repeatable.has(key)) (args[key] ||= []).push(value);
+      else args[key] = value;
     } else if (token.startsWith('-')) {
       fail(`Unknown option: ${token}`, EXIT.USAGE);
     } else {
@@ -540,17 +620,30 @@ function parseHandoffArgs(argv) {
   return args;
 }
 
+// True when a URL is safe to attach a bearer token or webhook secret to: https,
+// or http on loopback so local dev against http://localhost still works.
+// Split out of requireSafeUrl for the `hook` command, which must apply the same
+// rule but fails open (it defers instead of exiting — see hook()).
+function isSafeUrl(raw) {
+  let u;
+  try {
+    u = new URL(raw);
+  } catch {
+    return false;
+  }
+  const isLoopback = u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '[::1]';
+  return u.protocol === 'https:' || (u.protocol === 'http:' && isLoopback);
+}
+
 // Refuse to send a bearer token or webhook secret over cleartext http. A
 // loopback host is allowed so local dev against http://localhost still works.
 function requireSafeUrl(kind, raw) {
-  let u;
   try {
-    u = new URL(raw);
+    new URL(raw);
   } catch {
     fail(`${kind} is not a valid URL`, EXIT.USAGE);
   }
-  const isLoopback = u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '[::1]';
-  if (u.protocol !== 'https:' && !(u.protocol === 'http:' && isLoopback)) {
+  if (!isSafeUrl(raw)) {
     fail(`${kind} must use https (refusing to send credentials over cleartext)`, EXIT.USAGE);
   }
   return raw;
@@ -569,11 +662,11 @@ function parseDataObject(raw) {
   return data;
 }
 
-// `soft: true` returns { error } instead of exiting on a transport failure. Only
-// the pairing poll passes it: there, a single DNS blip or dropped connection
-// would otherwise kill a 15-minute wait the human is still walking towards their
-// phone for. Every other caller keeps the hard exit.
-async function httpJson(method, url, { body, headers = {}, soft = false } = {}) {
+// `soft: true` returns { error } instead of exiting on a transport failure. The
+// bounded pairing and activation loops use it so a single DNS blip or dropped
+// connection does not discard an otherwise recoverable human workflow. Every
+// other caller keeps the hard exit.
+async function httpJson(method, url, { body, headers = {}, soft = false, signal } = {}) {
   let res;
   try {
     res = await fetch(url, {
@@ -584,6 +677,7 @@ async function httpJson(method, url, { body, headers = {}, soft = false } = {})
         ...headers,
       },
       ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      ...(signal ? { signal } : {}),
     });
   } catch (err) {
     if (soft) return { res: null, text: '', json: null, error: err };
@@ -604,6 +698,90 @@ async function httpJson(method, url, { body, headers = {}, soft = false } = {})
   return { res, text, json };
 }
 
+// The extensions the attachment endpoint accepts. Mirrored here so a typo is a
+// local usage error instead of a 422 after the bytes have already been sent.
+// Keep in lockstep with laravel config/attachments.php `allowed_extensions`.
+const ATTACHMENT_EXTENSIONS = ['md', 'pdf', 'html', 'txt', 'jpg', 'jpeg', 'png'];
+const ATTACHMENT_MAX_BYTES = 20 * 1024 * 1024;
+const ATTACHMENT_MAX_COUNT = 10;
+const ATTACHMENT_MIME = {
+  md: 'text/markdown',
+  pdf: 'application/pdf',
+  html: 'text/html',
+  txt: 'text/plain',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  png: 'image/png',
+};
+
+/**
+ * Upload each --attach path and return the ids in flag order. Bytes go up as
+ * multipart; only the resulting ids ride the ping body. An id we never manage
+ * to attach expires server-side after 24h, so a mid-run failure leaks nothing
+ * permanent.
+ */
+async function uploadAttachments(paths, apiBase, token) {
+  if (paths.length > ATTACHMENT_MAX_COUNT) {
+    fail(`--attach accepts at most ${ATTACHMENT_MAX_COUNT} files`, EXIT.USAGE);
+  }
+
+  const { readFile, stat } = await import('node:fs/promises');
+  const { basename, extname } = await import('node:path');
+  const ids = [];
+
+  for (const path of paths) {
+    const name = basename(path);
+    const ext = extname(name).slice(1).toLowerCase();
+    if (!ATTACHMENT_EXTENSIONS.includes(ext)) {
+      fail(`--attach ${name}: only ${ATTACHMENT_EXTENSIONS.join(', ')} files are supported`, EXIT.USAGE);
+    }
+
+    let info;
+    try {
+      info = await stat(path);
+    } catch {
+      fail(`--attach ${path}: file not found`, EXIT.USAGE);
+    }
+    if (!info.isFile()) fail(`--attach ${path}: not a file`, EXIT.USAGE);
+    if (info.size < 1) fail(`--attach ${name}: file is empty`, EXIT.USAGE);
+    if (info.size > ATTACHMENT_MAX_BYTES) {
+      fail(`--attach ${name}: file exceeds the 20 MiB limit`, EXIT.USAGE);
+    }
+
+    const body = new FormData();
+    body.append('file', new Blob([await readFile(path)], { type: ATTACHMENT_MIME[ext] }), name);
+
+    let res;
+    try {
+      // Not httpJson: that helper JSON-encodes the body and would strip the
+      // multipart boundary the runtime generates for us.
+      res = await fetch(`${apiBase}/api/agent/attachments`, {
+        method: 'POST',
+        headers: { Accept: 'application/json', Authorization: `Bearer ${token}` },
+        body,
+      });
+    } catch (err) {
+      fail(`network error uploading ${name}: ${err.message}`);
+    }
+
+    const text = await res.text().catch(() => '');
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON response */ }
+
+    if (res.status === 402) {
+      fail(`--attach ${name}: ping attachments are a Pro feature`, EXIT.USAGE);
+    }
+    if (!res.ok || !json?.attachment?.id) {
+      const detail = json?.message || json?.error || `HTTP ${res.status}`;
+      fail(`upload failed for ${name}: ${detail}`);
+    }
+
+    ids.push(json.attachment.id);
+  }
+
+  return ids;
+}
+
 async function ping(args) {
   if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
 
@@ -662,6 +840,13 @@ async function ping(args) {
 
   let result;
 
+  // Attachments exist only on the agent-token path: an incoming webhook has no
+  // uploader identity to bind private files to, so the API takes no ids there.
+  const attachPaths = args.attach ?? [];
+  if (attachPaths.length && (webhook || !token)) {
+    fail('--attach requires an agent token (--token / PINGROOM_TOKEN), not a webhook ping', EXIT.USAGE);
+  }
+
   if (webhook) {
     if (ackTimeout !== undefined && (ackTimeout < 1 || ackTimeout > 86_400)) {
       fail('--ack-timeout must be between 1 and 86400 seconds for a webhook ping', EXIT.USAGE);
@@ -675,6 +860,7 @@ async function ping(args) {
     if (ackTimeout !== undefined) body.ack_timeout_seconds = ackTimeout;
     result = await httpJson('POST', webhook, { body });
   } else if (token) {
+    requireStoredCredentialOrigin(args, apiBase);
     if (!room) fail('--room is required when using --token (or set one with "pingroom config set default_room <code>")', EXIT.USAGE);
     if (ackTimeout !== undefined && (ackTimeout < 60 || ackTimeout > 86_400)) {
       fail('--ack-timeout must be between 60 and 86400 seconds for an agent room ping', EXIT.USAGE);
@@ -687,6 +873,9 @@ async function ping(args) {
     if (data) body.data = data;
     if (args.require_ack) body.requires_ack = true;
     if (ackTimeout !== undefined) body.ack_timeout_seconds = ackTimeout;
+    if (attachPaths.length) {
+      body.attachment_ids = await uploadAttachments(attachPaths, apiBase, token);
+    }
     result = await httpJson('POST', url, { body, headers: { Authorization: `Bearer ${token}` } });
   } else {
     fail('provide a webhook (--webhook / PINGROOM_WEBHOOK_URL) or an agent token (--token / PINGROOM_TOKEN, or run "pingroom" to connect)', EXIT.USAGE);
@@ -711,6 +900,11 @@ async function ping(args) {
 
 // --- live status -----------------------------------------------------------
 
+// The templates the server accepts on `live start`. Mirrored here so a typo is
+// a local usage error instead of a 422 from the API. Keep in lockstep with the
+// --template line in HELP and with LIVE_ACTIVITY_TEMPLATES.md.
+const LIVE_TEMPLATES = ['status', 'steps', 'progress', 'metrics', 'countdown', 'question', 'matchup'];
+
 // Parser for `live`: a leading subcommand (start|update|end|get) plus the
 // live-status flags. Unknown flags fail like the other parsers.
 function parseLiveArgs(argv) {
@@ -844,6 +1038,7 @@ async function live(args) {
 
   if (sub === 'get') {
     if (!token) fail('live get requires an agent token (--token or PINGROOM_TOKEN)', EXIT.USAGE);
+    requireStoredCredentialOrigin(args, apiBase);
     if (!room) fail('--room is required', EXIT.USAGE);
     requireSafeUrl('--api', apiBase);
     const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/live/${encodeURIComponent(correlationId)}`;
@@ -896,7 +1091,15 @@ async function live(args) {
   // Template, category and step labels are fixed when the stream is created;
   // sending them on an update is a no-op server-side, so only `start` takes them.
   if (sub === 'start') {
-    if (args.template) liveStatus.template = args.template;
+    // Validated locally for the same reason --category is: a typo'd name is a
+    // usage error, and letting it reach the server turns it into a 422 round
+    // trip that reads like an outage.
+    if (args.template) {
+      if (!LIVE_TEMPLATES.includes(args.template)) {
+        fail(`--template must be one of: ${LIVE_TEMPLATES.join(', ')}`, EXIT.USAGE);
+      }
+      liveStatus.template = args.template;
+    }
     // `alert` has no template equivalent and is the only way to start a stream
     // time-sensitive (breaking through Focus) without also demanding an ack.
     if (args.category) {
@@ -935,6 +1138,7 @@ async function live(args) {
     requireSafeUrl('--webhook', webhook);
     result = await httpJson('POST', webhook, { body });
   } else if (token) {
+    requireStoredCredentialOrigin(args, apiBase);
     if (!room) fail('--room is required when using --token (or set one with "pingroom config set default_room <code>")', EXIT.USAGE);
     requireSafeUrl('--api', apiBase);
     const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/live`;
@@ -972,6 +1176,7 @@ function agentContext(args, { needRoom = false } = {}) {
     );
   }
   const apiBase = resolveApiBase(args);
+  requireStoredCredentialOrigin(args, apiBase);
   requireSafeUrl('--api', apiBase);
   const room = resolveRoom(args);
   if (needRoom && !room) {
@@ -1526,7 +1731,7 @@ async function hookWaitForAnswer(id, { token, apiBase }) {
 
 async function hookPreToolUse(event, { token, room, apiBase, args }) {
   if (!token || !room) {
-    emitPreToolUseDecision('ask', 'PingRoom not configured (set PINGROOM_TOKEN and PINGROOM_ROOM)');
+    emitPreToolUseDecision('ask', 'PingRoom not configured (pair by QR, or configure both a token and room)');
     return EXIT.OK;
   }
 
@@ -1596,7 +1801,7 @@ async function hookPreToolUse(event, { token, room, apiBase, args }) {
 
 async function hookNotify(event, name, { token, room, apiBase, args }) {
   if (!token || !room) {
-    if (!args.quiet) process.stderr.write('pingroom: hook skipped (set PINGROOM_TOKEN and PINGROOM_ROOM)\n');
+    if (!args.quiet) process.stderr.write('pingroom: hook skipped (pair by QR, or configure both a token and room)\n');
     return EXIT.OK;
   }
 
@@ -1653,9 +1858,12 @@ function printHookConfig() {
   process.stdout.write(
 `# PingRoom × Claude Code — merge this into ~/.claude/settings.json
 #
-# 1. Set your credentials in the environment (e.g. in your shell profile):
-#      export PINGROOM_TOKEN="<your agent token>"
-#      export PINGROOM_ROOM="<room invite code>"
+# 1. Connect once and choose a delivery room when you scan the QR:
+#      npm install --global @pingroom/cli && pingroom
+#    Or, without a global install:
+#      npx --yes @pingroom/cli@${VERSION}
+#    The hook reads that stored credential and paired room automatically; you do
+#    not need to export PINGROOM_TOKEN or PINGROOM_ROOM for a local setup.
 #
 # 2. Merge the "hooks" block below into ~/.claude/settings.json.
 #      Stop / Notification  -> ping your phone.
@@ -1665,6 +1873,7 @@ function printHookConfig() {
 #
 # If PingRoom is unreachable the hook defers to the normal local prompt — it
 # never auto-approves and never blocks the agent.
+# PINGROOM_TOKEN / PINGROOM_ROOM remain supported for CI and headless shells.
 
 ${JSON.stringify(config, null, 2)}
 `);
@@ -1685,12 +1894,82 @@ async function hook(args) {
   const room = resolveRoom(args);
   const apiBase = resolveApiBase(args);
 
+  const originError = storedCredentialOriginError(args, apiBase);
+  if (originError) {
+    if (name === 'PreToolUse') {
+      emitPreToolUseDecision('ask', `${originError}; deferring to local prompt`);
+    } else if (!args.quiet) {
+      process.stderr.write(`pingroom: hook skipped (${originError})\n`);
+    }
+    return EXIT.OK;
+  }
+
+  // Every other command that attaches a bearer gates its base through
+  // requireSafeUrl first; the hook was the one that didn't, so a config or env
+  // pointing at plain http shipped `Authorization: Bearer …` in the clear with
+  // nothing on screen. Same rule here — but enforced by deferring, not by
+  // exiting: the hook's whole contract is that it never blocks the agent, so a
+  // hard failure would trade a credential leak for a broken session.
+  if (!isSafeUrl(apiBase)) {
+    const why = `${apiBase} is not https — refusing to send credentials over cleartext`;
+    if (name === 'PreToolUse') {
+      emitPreToolUseDecision('ask', `PingRoom API base ${why}; deferring to local prompt`);
+    } else if (!args.quiet) {
+      process.stderr.write(`pingroom: hook skipped (API base ${why})\n`);
+    }
+    return EXIT.OK;
+  }
+
   if (name === 'PreToolUse') {
     return hookPreToolUse(event, { token, room, apiBase, args });
   }
   return hookNotify(event, name, { token, room, apiBase, args });
 }
 
+// --- MCP client setup ------------------------------------------------------
+
+function mcp(rest) {
+  const claudeCommand = `claude mcp add --transport http pingroom ${MCP_ENDPOINT}`;
+
+  if (rest.length === 0 || (rest.length === 1 && (rest[0] === '-h' || rest[0] === '--help'))) {
+    const config = {
+      mcpServers: {
+        pingroom: { url: MCP_ENDPOINT },
+      },
+    };
+    process.stdout.write(
+`PingRoom MCP endpoint:
+  ${MCP_ENDPOINT}
+
+Claude Code:
+  ${claudeCommand}
+
+Cursor JSON (~/.cursor/mcp.json):
+${JSON.stringify(config, null, 2)}
+
+Claude Desktop:
+  Customize > Connectors > Add custom connector
+  Name: PingRoom
+  URL:  ${MCP_ENDPOINT}
+
+After adding the server, use your client's MCP controls to authenticate in the
+browser. No API key is needed.
+This command only prints setup instructions and does not modify client config.
+`);
+    return EXIT.OK;
+  }
+
+  if (rest.length === 2 && rest[0] === 'add' && rest[1] === 'claude-code') {
+    process.stdout.write(
+`No client configuration was changed. Copy and run:
+  ${claudeCommand}
+`);
+    return EXIT.OK;
+  }
+
+  fail('usage: pingroom mcp [add claude-code]', EXIT.USAGE);
+}
+
 // --- connecting (pairing + email fallback) ---------------------------------
 //
 // Wire contract: AGENT_PAIRING_SPEC.md. The shape is deliberately one gesture —
@@ -1711,6 +1990,28 @@ const CLI_SCOPES = [
 ];
 
 const AGENT_LABEL = 'pingroom-cli';
+// A connect command should prove the phone round-trip, but it must not hold a
+// terminal for the onboarding Question's full 24-hour server TTL. The Question
+// remains answerable after this local deadline and the credential is already
+// durable before the wait begins.
+const ACTIVATION_MAX_WAIT_MS = 2 * 60 * 1000;
+// The wait route is limited to 30 requests/minute. Keep immediate pending or
+// answered-without-completion observations safely below that ceiling while a
+// mixed-version or commit-propagation race is still being reconciled.
+const ACTIVATION_MIN_POLL_INTERVAL_MS = 2100;
+
+function activationMaxWaitMs() {
+  // Keep production fixed at two minutes. The guarded override lets the real
+  // subprocess tests exercise deadline behavior without holding the suite for
+  // two minutes; it is ignored outside NODE_ENV=test.
+  if (process.env.NODE_ENV === 'test') {
+    const testValue = Number(process.env.PINGROOM_INTERNAL_ACTIVATION_TIMEOUT_MS);
+    if (Number.isInteger(testValue) && testValue > 0 && testValue <= ACTIVATION_MAX_WAIT_MS) {
+      return testValue;
+    }
+  }
+  return ACTIVATION_MAX_WAIT_MS;
+}
 
 // Widest QR we render (compact half-block form of a ~110-char pair URL is 39
 // columns). Anything narrower would wrap and become unscannable, so we print
@@ -1843,6 +2144,284 @@ function connectedLine(cred) {
   return `✓ Connected as ${who}${room ? ` → #${room}` : ''}`;
 }
 
+function activationFailureDetail(result) {
+  if (result.error) return result.error.message;
+  const status = result.res ? `HTTP ${result.res.status}` : 'request failed';
+  return (result.json && (result.json.message || result.json.error || result.json.code)) || status;
+}
+
+function isJsonObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function isNullableString(value) {
+  return value === null || typeof value === 'string';
+}
+
+function validateActivationEnsure(json) {
+  const room = json?.room;
+  const question = json?.question;
+  const validState = question?.state === 'pending'
+    || question?.state === 'answered'
+    || question?.state === 'expired'
+    || question?.state === 'cancelled';
+  if (
+    !isJsonObject(json)
+    || json.onboarded !== true
+    || typeof json.replayed !== 'boolean'
+    || !isJsonObject(room)
+    || !isNonEmptyString(room.id)
+    || typeof room.name !== 'string'
+    || !isNonEmptyString(room.invite_code)
+    || typeof room.is_agent_inbox !== 'boolean'
+    || !isJsonObject(question)
+    || !isNonEmptyString(question.id)
+    || question.kind !== 'question'
+    || !isNonEmptyString(question.prompt)
+    || !Array.isArray(question.options)
+    || question.options.some((option) => (
+      !isJsonObject(option)
+      || !isNonEmptyString(option.value)
+      || !isNonEmptyString(option.label)
+    ))
+    || !validState
+    || !isNullableString(question.expires_at)
+    || !isNullableString(question.created_at)
+  ) {
+    return { error: 'PingRoom returned an incomplete Agent Inbox ensure response' };
+  }
+  return { question };
+}
+
+function validateActivationWait(json, questionId) {
+  const state = json?.state;
+  const validState = state === 'pending' || state === 'answered' || state === 'expired' || state === 'cancelled';
+  if (
+    !isJsonObject(json)
+    || !isNonEmptyString(json.id)
+    || json.id !== questionId
+    || json.kind !== 'question'
+    || !validState
+    || (json.activation_completed !== undefined && typeof json.activation_completed !== 'boolean')
+    || (state !== 'answered' && json.activation_completed === true)
+  ) {
+    return { error: 'PingRoom returned a mismatched Agent Inbox wait response' };
+  }
+
+  if (state === 'answered') {
+    const answer = json.answer;
+    const responder = answer?.responder;
+    if (
+      !isJsonObject(answer)
+      || !isNullableString(answer.value)
+      || !isNullableString(answer.label)
+      || !isNullableString(answer.text)
+      || (!isNonEmptyString(answer.value) && !isNonEmptyString(answer.text))
+      || !isNullableString(answer.answered_at)
+      || (responder !== null && !isJsonObject(responder))
+      || (isJsonObject(responder)
+        && (!isNullableString(responder.id) || !isNullableString(responder.display_name)))
+    ) {
+      return { error: 'PingRoom returned an answered activation without a valid answer' };
+    }
+  } else if (json.answer !== undefined && json.answer !== null) {
+    return { error: 'PingRoom returned an answer for an unresolved activation' };
+  }
+
+  return { value: json };
+}
+
+function retryAfterMs(response) {
+  const raw = response?.headers?.get('retry-after')?.trim();
+  if (!raw) return null;
+  if (/^\d+(?:\.\d+)?$/.test(raw)) return Number(raw) * 1000;
+  const at = Date.parse(raw);
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : null;
+}
+
+function activationRetryDelay(result, transientRun, deadline) {
+  const fromHeader = result.res?.status === 429 ? retryAfterMs(result.res) : null;
+  const fallback = Math.min(1000 * 2 ** Math.max(0, transientRun - 1), 10_000);
+  return Math.max(0, Math.min(fromHeader ?? fallback, deadline - Date.now()));
+}
+
+function activationIncomplete(detail, instruction = 'Run "pingroom activate" to retry with this saved connection.') {
+  const safeDetail = detail ? `: ${stripControlChars(detail)}` : '';
+  process.stdout.write(`  Agent Inbox activation is not complete${safeDetail}\n`);
+  process.stdout.write('  Your connection is saved and usable.\n');
+  process.stdout.write(`  ${instruction}\n`);
+}
+
+/**
+ * Prove the freshly paired credential can complete a human round-trip. This is
+ * intentionally best-effort: saveCredential() has already committed the active
+ * bearer atomically, so no activation outage can roll back or corrupt it.
+ */
+async function activateInboxAfterPairing(cred) {
+  const headers = { Authorization: `Bearer ${cred.token}` };
+  const overallDeadline = Date.now() + activationMaxWaitMs();
+  process.stdout.write('  Sending a test question to PingRoom…\n');
+
+  let ensured;
+  let ensureTransientRun = 0;
+  while (Date.now() < overallDeadline) {
+    ensured = await httpJson('POST', `${cred.apiBase}/api/agent/inbox/ensure`, {
+      body: {},
+      headers,
+      soft: true,
+      signal: AbortSignal.timeout(Math.max(1, Math.min(15_000, overallDeadline - Date.now()))),
+    });
+    const transient = ensured.error || ensured.res?.status === 429 || ensured.res?.status >= 500;
+    if (!transient) break;
+    ensureTransientRun += 1;
+    await sleep(activationRetryDelay(ensured, ensureTransientRun, overallDeadline));
+  }
+
+  if (!ensured.res?.ok) {
+    const detail = Date.now() >= overallDeadline
+      ? 'the two-minute activation deadline elapsed while PingRoom was unavailable'
+      : activationFailureDetail(ensured);
+    activationIncomplete(detail);
+    return false;
+  }
+
+  const ensureEnvelope = validateActivationEnsure(ensured.json);
+  if (ensureEnvelope.error) {
+    activationIncomplete(ensureEnvelope.error);
+    return false;
+  }
+  const { question } = ensureEnvelope;
+
+  process.stdout.write('  Answer “PingRoom connected. Can you answer this?” on your phone.\n');
+  // The server stamp, not the terminal state by itself, is the activation
+  // authority. A terminal answer without the stamp cannot become a valid
+  // receipt-before-answer sequence later, so fail clearly instead of polling a
+  // state the server intentionally will not rewrite.
+  const deadline = overallDeadline;
+  let transientRun = 0;
+
+  while (Date.now() < deadline) {
+    const pollStartedAt = Date.now();
+    const remainingSeconds = Math.max(0, Math.ceil((deadline - Date.now()) / 1000));
+    const hold = Math.min(20, remainingSeconds);
+    const waited = await httpJson(
+      'GET',
+      `${cred.apiBase}/api/agent/handoffs/${encodeURIComponent(question.id)}/wait?timeout=${hold}`,
+      {
+        headers,
+        soft: true,
+        signal: AbortSignal.timeout(Math.max(1, Math.min(
+          hold * 1000 + 10_000,
+          deadline - Date.now(),
+        ))),
+      },
+    );
+
+    const transient = waited.error || waited.res?.status === 429 || waited.res?.status >= 500;
+    if (transient) {
+      transientRun += 1;
+      const retryDelay = activationRetryDelay(waited, transientRun, deadline);
+      const cadenceDelay = ACTIVATION_MIN_POLL_INTERVAL_MS - (Date.now() - pollStartedAt);
+      await sleep(Math.max(0, Math.min(Math.max(retryDelay, cadenceDelay), deadline - Date.now())));
+      continue;
+    }
+    transientRun = 0;
+
+    if (!waited.res?.ok) {
+      activationIncomplete(activationFailureDetail(waited));
+      return false;
+    }
+
+    const waitEnvelope = validateActivationWait(waited.json, question.id);
+    if (waitEnvelope.error) {
+      activationIncomplete(waitEnvelope.error);
+      return false;
+    }
+    const resolved = waitEnvelope.value;
+    const state = resolved.state;
+    if (state === 'answered') {
+      if (resolved.activation_completed !== true) {
+        activationIncomplete(
+          'the test question was answered without verified phone receipt before the answer',
+          'Update the PingRoom app if needed, then run "pingroom activate" to send a fresh test with this saved connection.',
+        );
+        return false;
+      }
+      const answer = resolved.answer.text || resolved.answer.label || resolved.answer.value;
+      process.stdout.write(`✓ Test question answered (${stripControlChars(answer)}). Agent Inbox is ready.\n`);
+      return true;
+    }
+    if (state === 'expired' || state === 'cancelled') {
+      activationIncomplete(
+        `the test question ${state}`,
+        'Run "pingroom activate" to send a fresh test with this saved connection.',
+      );
+      return false;
+    }
+    // `pending` at the bounded hold timeout — continue at a throttle-safe
+    // cadence until the local/server deadline.
+    const cadenceDelay = ACTIVATION_MIN_POLL_INTERVAL_MS - (Date.now() - pollStartedAt);
+    await sleep(Math.max(0, Math.min(cadenceDelay, deadline - Date.now())));
+  }
+
+  activationIncomplete(
+    'still waiting for the test answer at the activation deadline',
+  );
+  return false;
+}
+
+/** Retry activation only for the durable credential created by QR pairing. */
+async function activateStoredInbox(args) {
+  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args._.length > 0) fail('usage: pingroom activate', EXIT.USAGE);
+  if (args.token !== undefined) {
+    fail('pingroom activate uses the saved QR-paired credential; remove --token', EXIT.USAGE);
+  }
+  const unsupported = Object.keys(args).filter((key) => !['_', 'help', 'api', 'token'].includes(key));
+  if (unsupported.length > 0) {
+    fail('usage: pingroom activate [--api <url>]', EXIT.USAGE);
+  }
+
+  const credential = readStoredCredential();
+  if (!credential) {
+    fail('no saved QR-paired credential; run "pingroom" in an interactive terminal first', EXIT.USAGE);
+  }
+  if (!credential.room || !isNonEmptyString(credential.room.invite_code)) {
+    fail('the saved credential has no QR-selected delivery room; reconnect with QR pairing before running "pingroom activate"', EXIT.USAGE);
+  }
+  if (!Array.isArray(credential.scopes) || !credential.scopes.includes('pingroom:handoffs:create')) {
+    fail('the saved credential lacks pingroom:handoffs:create; reconnect with QR pairing before running "pingroom activate"', EXIT.USAGE);
+  }
+
+  const apiBase = resolveApiBase(args);
+  requireSafeUrl('--api', apiBase);
+  if (!isNonEmptyString(credential.api_url)) {
+    fail('the saved QR-paired credential has no trusted API origin; pair again before running "pingroom activate"', EXIT.USAGE);
+  }
+  let credentialOrigin;
+  let targetOrigin;
+  try {
+    credentialOrigin = new URL(credential.api_url).origin;
+    targetOrigin = new URL(apiBase).origin;
+  } catch {
+    fail('the saved QR-paired credential has an invalid API origin; pair again', EXIT.USAGE);
+  }
+  if (credentialOrigin !== targetOrigin) {
+    fail(`stored credential is bound to ${credentialOrigin}; refusing to send it to ${targetOrigin}`, EXIT.USAGE);
+  }
+  process.stdout.write(`${connectedLine(credential)}\n`);
+
+  const completed = await activateInboxAfterPairing({
+    ...credential,
+    apiBase,
+  });
+  return completed ? EXIT.OK : EXIT.ERROR;
+}
+
 /**
  * The QR path. Mints a pre-claim credential, asks the server for a pairing
  * token, renders it, then polls until the human approves. Returns a credential
@@ -1943,6 +2522,7 @@ async function connectByPairing(apiBase, ask) {
         };
         saveCredential(cred);
         process.stdout.write(`${connectedLine(cred)}\n`);
+        await activateInboxAfterPairing(cred);
         return cred;
       }
       if (status === 'expired') break;
@@ -2017,7 +2597,8 @@ async function connectByEmail(apiBase, ask) {
       saveCredential(cred);
       process.stdout.write(`${connectedLine(cred)}\n`);
       if (!cred.room) {
-        process.stdout.write('  Pick a delivery room with: pingroom config set default_room <invite code>\n');
+        process.stdout.write('  For room commands: pingroom config set default_room <invite code>\n');
+        process.stdout.write('  For private Inbox/Handoff delivery, reconnect with QR pairing.\n');
       }
       return cred;
     }
@@ -2224,6 +2805,8 @@ const COMMANDS = {
   handoff: (rest) => handoff(parseHandoffArgs(rest)),
   handoffs: (rest) => listHandoffs(parseQArgs(rest)),
   hook: (rest) => hook(parseHookArgs(rest)),
+  mcp,
+  activate: (rest) => activateStoredInbox(parseQArgs(rest)),
   live: (rest) => live(parseLiveArgs(rest)),
   config: (rest) => config(parseQArgs(rest)),
   logout: (rest) => logout(parseQArgs(rest)),
@@ -2242,6 +2825,11 @@ async function main() {
     process.exit(EXIT.OK);
   }
 
+  if (command === '-v' || command === '--version') {
+    process.stdout.write(`${VERSION}\n`);
+    process.exit(EXIT.OK);
+  }
+
   // Bare `pingroom` resolves the auth state instead of only printing help:
   // connected -> status + help; not connected -> pair (interactive only).
   // A leading flag with no subcommand (`pingroom --api …`) counts as bare — it

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pingroom/cli",
-  "version": "0.6.0",
-  "description": "Send PingRoom pings and ask humans blocking questions from CI, scripts, and agents.",
+  "version": "0.6.1",
+  "description": "Send PingRoom Pings and wait for human decisions from CI, scripts, and agents.",
   "type": "module",
   "bin": {
     "pingroom": "bin/pingroom.js"
@@ -29,7 +29,10 @@
   "homepage": "https://pingroom.io",
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/pingroom/cli.git"
+    "url": "git+https://github.com/pingroom/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pingroom/cli/issues"
   },
   "dependencies": {
     "qrcode-terminal": "^0.12.0"