@connortessaro/pai 0.4.2 → 0.5.0

package/dist/pai.mjs

@@ -14,7 +14,7 @@ import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import os from 'node:os';
 import { createHash, createPublicKey, generateKeyPairSync, verify as cryptoVerify } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
@@ -22,11 +22,16 @@ import { address, appendTransactionMessageInstructions, createKeyPairSignerFromB
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import * as z from 'zod';
+/** The Phantom AI API address pai calls when PHANTOM_BASE_URL is unset. */
 export const DEFAULT_BASE_URL = 'https://phantom.codes/v1';
-export const VERSION = '0.4.2';
+/** This release of pai. `npm version` keeps it equal to the version in package.json. */
+export const VERSION = '0.5.0';
 // ── errors ───────────────────────────────────────────────────────────────────
+/** An error answer from the Phantom AI API. {@link handleError} maps a 401 or 403 to exit code 2. */
 export class PhantomApiError extends Error {
+    /** The HTTP status code of the answer. */
     status;
+    /** The API's error code, or the status code as text when the answer carries none. */
     code;
     constructor(status, code, message) {
         super(message);
@@ -35,8 +40,11 @@ export class PhantomApiError extends Error {
         this.code = code;
     }
 }
+/** An error pai raises itself, such as a missing flag or a refused payment. */
 export class CliError extends Error {
+    /** A short code for the error, such as `wallet_cap_exceeded`. `cli_error` when none is given. */
     code;
+    /** The process exit code {@link run} returns for it. 1 unless given. */
     exitCode;
     constructor(message, code = 'cli_error', exitCode = 1) {
         super(message);
@@ -45,10 +53,27 @@ export class CliError extends Error {
         this.exitCode = exitCode;
     }
 }
+/**
+ * Throws a {@link CliError}. Every refusal in pai goes through here.
+ * @param msg The message the user sees.
+ * @param code The error code, printed in the JSON error.
+ * @param exitCode The process exit code.
+ */
 export function die(msg, code = 'cli_error', exitCode = 1) {
     throw new CliError(msg, code, exitCode);
 }
 // ── request ──────────────────────────────────────────────────────────────────
+/**
+ * Calls the Phantom AI API with the key as a Bearer token and returns the
+ * JSON answer. Every client function in this file goes through it.
+ * @param method The HTTP method.
+ * @param path The path after the base URL, such as `/key/balance`.
+ * @param apiKey The key sent in the Authorization header.
+ * @param body Sent as JSON when given.
+ * @param baseUrl The API base. Defaults to PHANTOM_BASE_URL, then {@link DEFAULT_BASE_URL}. Must be https ({@link httpsOnly}).
+ * @param headers Extra headers to send.
+ * @throws {@link PhantomApiError} when the API answers with an error status.
+ */
 export async function request(method, path, apiKey, body, baseUrl, headers = {}) {
     const url = `${apiBase(baseUrl)}${path}`;
     const res = await fetch(url, {
@@ -66,10 +91,27 @@ export async function request(method, path, apiKey, body, baseUrl, headers = {})
     return json;
 }
 function apiBase(baseUrl) {
-    return (baseUrl ||
+    return httpsOnly(baseUrl ||
         (typeof process !== 'undefined' && process.env.PHANTOM_BASE_URL) ||
         DEFAULT_BASE_URL);
 }
+/**
+ * The API base must be https. The key goes to it on every call, so plain http
+ * is refused, localhost included.
+ */
+export function httpsOnly(baseUrl) {
+    let protocol = '';
+    try {
+        protocol = new URL(baseUrl).protocol;
+    }
+    catch {
+        die(`PHANTOM_BASE_URL is not a web address: ${baseUrl}`, 'base_url_invalid');
+    }
+    if (protocol !== 'https:') {
+        die(`PHANTOM_BASE_URL must start with https://, not ${baseUrl}. pai sends your API key there, so it refuses plain http, even on localhost.`, 'base_url_insecure');
+    }
+    return baseUrl;
+}
 function apiError(status, json) {
     const err = json.error;
     let code = String(status);
@@ -90,33 +132,49 @@ function apiError(status, json) {
     return new PhantomApiError(status, code, msg);
 }
 // ── client functions ─────────────────────────────────────────────────────────
+/** Credit left, credit spent and expiry of a key (GET /key/balance). */
 export function getBalance(apiKey, baseUrl) {
     return request('GET', '/key/balance', apiKey, undefined, baseUrl);
 }
+/** A key's caps, plan and pace (GET /key/budget). */
 export function getBudget(apiKey, baseUrl) {
     return request('GET', '/key/budget', apiKey, undefined, baseUrl);
 }
+/**
+ * Sets or clears a key's period cap and per-minute cap (PATCH /key/budget).
+ * A field left out stays as it is; null clears it. A child key cannot change its caps.
+ */
 export function setBudget(apiKey, opts, baseUrl) {
     return request('PATCH', '/key/budget', apiKey, opts, baseUrl);
 }
+/**
+ * Sets or clears a plan: a cap of `amount_usd` over `days` (PATCH /key/budget
+ * with `budget_usd` and `period_days`). `days` null means one calendar month.
+ * Setting an amount starts a fresh period.
+ */
 export function setPlan(apiKey, opts, baseUrl) {
     const body = { budget_usd: opts.amount_usd };
     if (opts.days !== undefined)
         body.period_days = opts.days;
     return request('PATCH', '/key/budget', apiKey, body, baseUrl);
 }
+/** The key's route policy (GET /key/route). */
 export function getRoute(apiKey, baseUrl) {
     return request('GET', '/key/route', apiKey, undefined, baseUrl);
 }
+/** Replaces the key's route policy (PUT /key/route). The server checks it before saving. */
 export function putRoute(apiKey, policy, baseUrl) {
     return request('PUT', '/key/route', apiKey, policy, baseUrl);
 }
+/** Changes some top-level fields of the route policy and keeps the rest (PATCH /key/route). A list sent here replaces the whole list. */
 export function patchRoute(apiKey, fields, baseUrl) {
     return request('PATCH', '/key/route', apiKey, fields, baseUrl);
 }
+/** Removes the key's route policy (DELETE /key/route). */
 export function clearRoute(apiKey, baseUrl) {
     return request('DELETE', '/key/route', apiKey, undefined, baseUrl);
 }
+/** Which model a request would run on now, and why (POST /key/route/test). Nothing is charged and no model is called. */
 export function testRoute(apiKey, opts, baseUrl) {
     return request('POST', '/key/route/test', apiKey, opts, baseUrl);
 }
@@ -130,9 +188,15 @@ export function parseCondition(raw) {
     const value = text === 'true' ? true : text === 'false' ? false : text !== '' && Number.isFinite(Number(text)) ? Number(text) : text;
     return { [name]: value };
 }
+/**
+ * Makes a child key that spends this key's balance up to `limit_usd`
+ * (POST /key/child). No credit moves. `ttl_hours` defaults to 24 on the server.
+ * A child key cannot make children.
+ */
 export function createChild(apiKey, opts, baseUrl) {
     return request('POST', '/key/child', apiKey, opts, baseUrl);
 }
+/** The child keys this key made (GET /key/children). */
 export function listChildren(apiKey, baseUrl) {
     return request('GET', '/key/children', apiKey, undefined, baseUrl);
 }
@@ -154,6 +218,11 @@ export function parseBuyCoin(coin) {
 export function requestSolanaPayment(apiKey, opts, baseUrl) {
     return request('POST', '/purchase/solana', apiKey, { ...opts, target_api_key: apiKey }, baseUrl);
 }
+/**
+ * Where a payment stands (GET /purchase/{id}/status). The server checks the
+ * chain on each call. The recovery code, when given, goes in the
+ * `x-phantom-recovery-code` header.
+ */
 export function getPaymentStatus(apiKey, paymentId, baseUrl, recoveryCode) {
     return request('GET', `/purchase/${encodeURIComponent(paymentId)}/status`, apiKey, undefined, baseUrl, recoveryCode ? { 'x-phantom-recovery-code': recoveryCode } : {});
 }
@@ -180,9 +249,11 @@ export async function waitForPayment(apiKey, paymentId, opts = {}) {
         await sleep(intervalMs);
     }
 }
+/** Issues a new key and retires this one (POST /key/rotate). */
 export function rotateKey(apiKey, baseUrl) {
     return request('POST', '/key/rotate', apiKey, undefined, baseUrl);
 }
+/** Revokes the key it is called with (DELETE /key). Its children stop too, and credit left on it is forfeited. */
 export function burnKey(apiKey, baseUrl) {
     return request('DELETE', '/key', apiKey, undefined, baseUrl);
 }
@@ -194,6 +265,11 @@ export function burnKey(apiKey, baseUrl) {
  */
 /** Matches RECEIPT_VERSION in lib/receipts.ts. */
 const RECEIPT_VERSION = 1;
+/**
+ * Checks a compact receipt (`payload.signature`, both base64url) against the
+ * public key from GET /receipts/key. Needs no API key.
+ * @throws {@link PhantomApiError} when the public key cannot be fetched.
+ */
 export async function checkReceipt(compact, baseUrl) {
     const res = await fetch(`${apiBase(baseUrl)}/receipts/key`);
     const json = (await res.json().catch(() => ({})));
@@ -280,10 +356,23 @@ export async function verifyModel(apiKey, model, baseUrl) {
  * was asked for, so a wrong or hostile PHANTOM_BASE_URL cannot make the wallet
  * sign more.
  */
+/** The coins an agent wallet can pay in, with the decimal places of each. */
 export const WALLET_COINS = {
-    sol: { decimals: 9 },
-    usdc: { decimals: 6 },
-    usdcsol: { decimals: 6 },
+    /** SOL, counted in lamports. */
+    sol: {
+        /** A SOL has 9 decimal places. */
+        decimals: 9,
+    },
+    /** USDC on Solana. */
+    usdc: {
+        /** A USDC has 6 decimal places. */
+        decimals: 6,
+    },
+    /** The older spelling of usdc. */
+    usdcsol: {
+        /** A USDC has 6 decimal places. */
+        decimals: 6,
+    },
 };
 const USDC_MINT = {
     mainnet: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
@@ -299,6 +388,7 @@ const READONLY = 0;
 const WRITABLE = 1;
 const READONLY_SIGNER = 2;
 const WRITABLE_SIGNER = 3;
+/** True when `coin` is a name in {@link WALLET_COINS}. */
 export function isWalletCoin(coin) {
     return Object.prototype.hasOwnProperty.call(WALLET_COINS, coin);
 }
@@ -322,6 +412,93 @@ function stateDir(env) {
 function walletsDir(env) {
     return path.join(stateDir(env), 'wallets');
 }
+// ── secrets ──────────────────────────────────────────────────────────────────
+/**
+ * On macOS, saved keys, wallets and the mail login live in the login Keychain
+ * rather than in files. The file stays, holding only a pointer
+ * (`pai-keychain:<id>`), so listing and existence checks work the same on
+ * every system. Elsewhere, or with PAI_KEYCHAIN=0, the file holds the secret,
+ * readable by this user only.
+ *
+ * Items are written through /usr/bin/security, which the Keychain then trusts
+ * to read them back, so there is no prompt. That also means any program
+ * running as this user can read them the same way: the Keychain keeps secrets
+ * out of files, backups and sync folders, not away from local programs.
+ *
+ * A secret file written before this is moved into the Keychain the first time
+ * it is read, and replaced with a pointer only after the Keychain returns it
+ * intact.
+ */
+const KEYCHAIN_SERVICE = 'pai';
+const KEYCHAIN_POINTER = 'pai-keychain:';
+/** Reads and writes pai's items in the macOS login Keychain through /usr/bin/security, under the service name `pai`. */
+export const keychain = {
+    /** The secret saved under `id`, or null when there is none or the Keychain can't be read. */
+    get(id) {
+        const r = spawnSync('/usr/bin/security', ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', id, '-w'], { encoding: 'utf-8' });
+        return r.status === 0 ? Buffer.from(r.stdout.trim(), 'base64').toString('utf-8') : null;
+    },
+    /** Saves `value` under `id`, replacing what was there. Returns false when the Keychain refuses, as it does when locked. */
+    set(id, label, value) {
+        // Sent on stdin rather than as an argument, so the secret never shows in
+        // the process list. Base64 keeps it one unquoted word.
+        const cmd = `add-generic-password -U -s ${KEYCHAIN_SERVICE} -a ${id} -l "pai ${label}" -w ${Buffer.from(value, 'utf-8').toString('base64')}\n`;
+        return spawnSync('/usr/bin/security', ['-i'], { input: cmd, stdio: ['pipe', 'ignore', 'ignore'] }).status === 0;
+    },
+    /** Removes the item saved under `id`, if any. */
+    delete(id) {
+        spawnSync('/usr/bin/security', ['delete-generic-password', '-s', KEYCHAIN_SERVICE, '-a', id], { stdio: 'ignore' });
+    },
+};
+function keychainOn(env) {
+    const flag = env.PAI_KEYCHAIN ?? process.env.PAI_KEYCHAIN;
+    return flag === '1' || (process.platform === 'darwin' && flag !== '0');
+}
+function keychainId(file) {
+    if (!existsSync(file))
+        return null;
+    const raw = readFileSync(file, 'utf-8').trim();
+    return raw.startsWith(KEYCHAIN_POINTER) ? raw.slice(KEYCHAIN_POINTER.length) : null;
+}
+function writeSecret(env, file, value, opts = {}) {
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    let contents = value;
+    if (keychainOn(env)) {
+        const id = keychainId(file) ?? randomBytes(12).toString('hex');
+        if (!keychain.set(id, path.relative(stateDir(env), file), value)) {
+            die('Could not save to the macOS Keychain. If it is locked (common over SSH), run: security unlock-keychain. Or set PAI_KEYCHAIN=0 to save to a file.', 'keychain_failed');
+        }
+        contents = KEYCHAIN_POINTER + id + '\n';
+    }
+    writeFileSync(file, contents, { mode: 0o600, flag: opts.flag });
+    // `mode` applies only when the file is created; tighten one that was already there.
+    chmodSync(file, 0o600);
+}
+function readSecret(env, file) {
+    const raw = readFileSync(file, 'utf-8');
+    if (raw.trim().startsWith(KEYCHAIN_POINTER)) {
+        const value = keychain.get(raw.trim().slice(KEYCHAIN_POINTER.length));
+        if (value === null)
+            die(`${file} points to a macOS Keychain item that could not be read. If the Keychain is locked (common over SSH), run: security unlock-keychain`, 'keychain_failed');
+        return value;
+    }
+    if (keychainOn(env)) {
+        const id = randomBytes(12).toString('hex');
+        if (keychain.set(id, path.relative(stateDir(env), file), raw)) {
+            if (keychain.get(id) === raw)
+                writeFileSync(file, KEYCHAIN_POINTER + id + '\n', { mode: 0o600 });
+            else
+                keychain.delete(id);
+        }
+    }
+    return raw;
+}
+function removeSecret(file) {
+    const id = keychainId(file);
+    if (id)
+        keychain.delete(id);
+    rmSync(file);
+}
 // ── saved key ────────────────────────────────────────────────────────────────
 /**
  * `login` saves the key to a file only the user can read, so an agent that
@@ -348,6 +525,11 @@ function namedKeyPath(env, name) {
 export function keyId(key) {
     return createHash('sha256').update(key.trim()).digest('hex').slice(0, 12);
 }
+/**
+ * Which key a command runs as: the saved key named by PHANTOM_KEY_NAME, then
+ * PHANTOM_API_KEY, then the login key. It only looks; {@link resolveApiKey}
+ * reads the key.
+ */
 export function keySource(env) {
     // A named key is the more specific choice, so it wins. A subagent started
     // with PHANTOM_KEY_NAME=<child> from a shell that also exports the parent's
@@ -358,6 +540,7 @@ export function keySource(env) {
         return { from: 'env' };
     return existsSync(keyPath(env)) ? { from: 'login' } : { from: 'none' };
 }
+/** The key a command runs as, chosen by {@link keySource}. An empty string when there is none. */
 export function resolveApiKey(env) {
     const src = keySource(env);
     if (src.from === 'env')
@@ -365,36 +548,47 @@ export function resolveApiKey(env) {
     if (src.from === 'named')
         return readNamedKey(env, src.name);
     if (src.from === 'login')
-        return readFileSync(keyPath(env), 'utf-8').trim();
+        return readSecret(env, keyPath(env)).trim();
     return '';
 }
-function writeKeyFile(file, key) {
+function writeKeyFile(env, file, key) {
     const k = key.trim();
     if (!k.startsWith('sk-phantom-'))
         die('That is not a Phantom AI key. Keys start with sk-phantom-');
-    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-    writeFileSync(file, k + '\n', { mode: 0o600 });
+    writeSecret(env, file, k + '\n');
 }
+/**
+ * A key saved by name.
+ * @throws {@link CliError} when no key has that name, or the name is not valid.
+ */
 export function readNamedKey(env, name) {
     const file = namedKeyPath(env, name);
     if (!existsSync(file))
         die(`No saved key named ${name}. See: pai key list`);
-    return readFileSync(file, 'utf-8').trim();
+    return readSecret(env, file).trim();
 }
+/**
+ * Saves a key by name, in the Keychain or a mode 600 file (see {@link keychain}).
+ * Refuses a name already in use unless `replace` is set, and anything that
+ * doesn't start with `sk-phantom-`.
+ * @returns The name, and the key's {@link keyId}.
+ */
 export function saveNamedKey(env, name, key, opts = {}) {
     const file = namedKeyPath(env, name);
     if (existsSync(file) && !opts.replace)
         die(`A key named ${name} is already saved. Pick another name, or remove it first.`);
-    writeKeyFile(file, key);
+    writeKeyFile(env, file, key);
     return { name, id: keyId(key) };
 }
+/** Forgets a saved key. The key itself keeps working. */
 export function removeNamedKey(env, name) {
     const file = namedKeyPath(env, name);
     if (!existsSync(file))
         return { name, removed: false };
-    rmSync(file);
+    removeSecret(file);
     return { name, removed: true };
 }
+/** Every key saved by name, sorted, with its id. Never returns the keys. */
 export function listNamedKeys(env) {
     const dir = path.join(stateDir(env), 'keys');
     if (!existsSync(dir))
@@ -402,7 +596,7 @@ export function listNamedKeys(env) {
     const keys = readdirSync(dir)
         .filter((n) => KEY_NAME.test(n))
         .sort()
-        .map((name) => ({ name, id: keyId(readFileSync(path.join(dir, name), 'utf-8')) }));
+        .map((name) => ({ name, id: keyId(readSecret(env, path.join(dir, name))) }));
     return { keys };
 }
 /** After a rotate, put the new key where the old one was saved. */
@@ -412,20 +606,22 @@ function replaceSavedKey(env, src, key) {
         return src.name;
     }
     if (src.from === 'login') {
-        writeKeyFile(keyPath(env), key);
+        writeKeyFile(env, keyPath(env), key);
         return 'login';
     }
     return null;
 }
+/** Saves the login key, the one used when neither PHANTOM_KEY_NAME nor PHANTOM_API_KEY is set. */
 export function saveApiKey(env, key) {
-    writeKeyFile(keyPath(env), key);
+    writeKeyFile(env, keyPath(env), key);
     return { saved: keyPath(env) };
 }
+/** Forgets the login key. */
 export function removeApiKey(env) {
     const p = keyPath(env);
     if (!existsSync(p))
         return { removed: false };
-    rmSync(p);
+    removeSecret(p);
     return { removed: true };
 }
 function memoryDir(env, space) {
@@ -433,6 +629,7 @@ function memoryDir(env, space) {
         die(`Memory space names use letters, numbers, - and _ (up to 32): ${space}`);
     return path.join(stateDir(env), 'memory', space);
 }
+/** The notebook to use: the `--space` flag, then PAI_MEMORY_SPACE, then PHANTOM_KEY_NAME, then `main`. The browser uses the same name. */
 export function memorySpace(env, flag) {
     return flag || env.PAI_MEMORY_SPACE || env.PHANTOM_KEY_NAME || 'main';
 }
@@ -472,6 +669,10 @@ function readNotes(env, space) {
         .sort()
         .map((f) => parseNote(space, f.slice(0, -3), readFileSync(path.join(dir, f), 'utf-8')));
 }
+/**
+ * Saves a note as a markdown file with the title, time and tags at the top.
+ * @throws {@link CliError} when the text is empty or the space name is not valid.
+ */
 export function addMemory(env, space, text, opts = {}) {
     const body = text.trim();
     if (!body)
@@ -528,10 +729,15 @@ export function searchMemory(env, space, query, opts = {}) {
         .sort((a, b) => b.score - a.score || b.id.localeCompare(a.id));
     return hits.slice(0, opts.limit ?? 10);
 }
+/** The newest notes in a space, optionally with one tag. 50 by default. */
 export function listMemory(env, space, opts = {}) {
     const notes = readNotes(env, space).filter((n) => !opts.tag || n.tags.includes(opts.tag));
     return notes.reverse().slice(0, opts.limit ?? 50);
 }
+/**
+ * One note by id.
+ * @throws {@link CliError} when the id is not a note id or no such note exists.
+ */
 export function getMemory(env, space, id) {
     if (!NOTE_ID.test(id))
         die(`Not a note id: ${id}`);
@@ -540,6 +746,7 @@ export function getMemory(env, space, id) {
         die(`No note ${id} in space ${space}`);
     return parseNote(space, id, readFileSync(file, 'utf-8'));
 }
+/** Deletes one note by id. */
 export function removeMemory(env, space, id) {
     if (!NOTE_ID.test(id))
         die(`Not a note id: ${id}`);
@@ -549,6 +756,7 @@ export function removeMemory(env, space, id) {
     rmSync(file);
     return { id, removed: true };
 }
+/** Every notebook and how many notes it holds. */
 export function memorySpaces(env) {
     const root = path.join(stateDir(env), 'memory');
     if (!existsSync(root))
@@ -576,6 +784,11 @@ export function memorySpaces(env) {
 function onPath(bin) {
     return spawnSync(process.platform === 'win32' ? 'where' : 'which', [bin], { stdio: 'ignore' }).status === 0;
 }
+/**
+ * The environment agent-browser runs with for a space: AGENT_BROWSER_SESSION
+ * (default `pai-<space>`) and AGENT_BROWSER_PROFILE (default
+ * `browser/<space>` in the state folder). Values set in `env` win.
+ */
 export function browserEnv(env, space) {
     if (!KEY_NAME.test(space))
         die(`Browser space names use letters, numbers, - and _ (up to 32): ${space}`);
@@ -584,6 +797,7 @@ export function browserEnv(env, space) {
         AGENT_BROWSER_PROFILE: env.AGENT_BROWSER_PROFILE || path.join(stateDir(env), 'browser', space),
     };
 }
+/** Whether agent-browser is installed, and the session and profile a space would use. */
 export function browserStatus(env, space) {
     const installed = onPath('agent-browser');
     const r = installed ? spawnSync('agent-browser', ['--version'], { encoding: 'utf-8' }) : null;
@@ -609,6 +823,11 @@ export function runBrowser(env, space, args) {
     return r.status ?? 1;
 }
 const SANDBOX_ENGINES = ['docker', 'podman'];
+/**
+ * The container engine to run the sandbox with: PAI_SANDBOX_ENGINE if set,
+ * else docker, then podman. An engine counts only when it is installed and
+ * running. null when none is.
+ */
 export function sandboxEngine(env) {
     const wanted = env.PAI_SANDBOX_ENGINE;
     for (const engine of wanted ? [wanted] : SANDBOX_ENGINES) {
@@ -683,6 +902,12 @@ export function parseServer(raw, insecure = false) {
     const port = m[2] ? Number(m[2]) : 993;
     return { host: m[1], port, secure: !insecure && (port === 993 || port === 465), ...(insecure ? { insecure: true } : {}) };
 }
+/**
+ * A mailbox login from an address and password. The servers come from
+ * `imap` and `smtp` when given, else from the preset for the address's
+ * domain (Gmail, Outlook, Hotmail, iCloud, Fastmail).
+ * @throws {@link CliError} when there is no preset and no servers were given, or no password.
+ */
 export function buildMailConfig(opts) {
     const domain = opts.user.split('@')[1]?.toLowerCase() ?? '';
     const preset = MAIL_PRESETS[domain];
@@ -694,19 +919,24 @@ export function buildMailConfig(opts) {
         die('mail setup needs the account password (for Gmail, an app password)');
     return { user: opts.user, pass: opts.pass, imap, smtp };
 }
+/** Saves a mailbox login to mail.json, in the Keychain on macOS (see {@link keychain}). */
 export function saveMailConfig(env, config) {
-    mkdirSync(stateDir(env), { recursive: true, mode: 0o700 });
-    writeFileSync(mailPath(env), JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+    writeSecret(env, mailPath(env), JSON.stringify(config, null, 2) + '\n');
     return { user: config.user, imap: config.imap, smtp: config.smtp, saved: mailPath(env) };
 }
+/** Builds a mailbox login with {@link buildMailConfig} and saves it, without checking it first. `pai mail setup` checks it before saving. */
 export function mailSetup(env, opts) {
     return saveMailConfig(env, buildMailConfig(opts));
 }
+/**
+ * The saved mailbox login.
+ * @throws {@link CliError} `mail_missing` when `mail setup` has not run.
+ */
 export function mailConfig(env) {
     const file = mailPath(env);
     if (!existsSync(file))
         die('No mailbox set up. Run: pai mail setup --user you@example.com', 'mail_missing');
-    return JSON.parse(readFileSync(file, 'utf-8'));
+    return JSON.parse(readSecret(env, file));
 }
 async function imapClient(cfg) {
     const { ImapFlow } = await import('imapflow');
@@ -726,6 +956,11 @@ async function imapClient(cfg) {
 function addr(list) {
     return (list ?? []).map((a) => (a.name ? `${a.name} <${a.address}>` : a.address ?? '')).join(', ');
 }
+/**
+ * The newest messages in a folder (INBOX by default), newest first, over
+ * IMAP. `query` matches words in the subject or body. 20 by default.
+ * @param unsaved A login not saved yet, so `mail setup` can check it first.
+ */
 export async function mailList(env, opts = {}, 
 // A login not saved yet, so `mail setup` can check it first.
 unsaved) {
@@ -767,6 +1002,11 @@ unsaved) {
         await client.logout();
     }
 }
+/**
+ * One message as plain text, by uid. The body is cut at 20,000 characters so
+ * one message can't fill an agent's context.
+ * @throws {@link CliError} when the folder has no message with that uid.
+ */
 export async function mailRead(env, uid, opts = {}) {
     const cfg = mailConfig(env);
     const folder = opts.folder ?? 'INBOX';
@@ -802,7 +1042,7 @@ export async function mailRead(env, uid, opts = {}) {
     }
 }
 async function compose(cfg, msg) {
-    const { default: MailComposer } = await import('nodemailer/lib/mail-composer/index.js');
+    const { default: MailComposer } = await import('nodemailer/lib/mail-composer');
     const mail = new MailComposer({
         from: cfg.from ?? cfg.user,
         to: msg.to,
@@ -828,6 +1068,7 @@ export async function mailDraft(env, msg) {
         await client.logout();
     }
 }
+/** Whether sending is on (PAI_MAIL_SEND=1) and the daily recipient cap (PAI_MAIL_MAX_PER_DAY, default 10; 0 when it is not a positive number). */
 export function mailSendLimit(env) {
     const perDay = Number(env.PAI_MAIL_MAX_PER_DAY ?? 10);
     return { allowed: env.PAI_MAIL_SEND === '1', perDay: Number.isFinite(perDay) && perDay > 0 ? perDay : 0 };
@@ -911,11 +1152,39 @@ export async function mailSend(env, msg, now = Date.now()) {
  * server is extra, for agents that support MCP; `setup` only prints how to add
  * it unless called with --mcp.
  */
+/**
+ * The agents `pai setup` knows. `home` is the folder in the home directory
+ * whose presence means the agent is installed; `skills` is where the skill goes.
+ */
 export const SETUP_AGENTS = {
-    pi: { home: '.pi', skills: '.agents/skills' },
-    codex: { home: '.codex', skills: '.agents/skills' },
-    claude: { home: '.claude', skills: '.claude/skills' },
-    cursor: { home: '.cursor', skills: '.cursor/skills' },
+    /** pi. */
+    pi: {
+        /** ~/.pi */
+        home: '.pi',
+        /** ~/.agents/skills */
+        skills: '.agents/skills',
+    },
+    /** Codex. */
+    codex: {
+        /** ~/.codex */
+        home: '.codex',
+        /** ~/.agents/skills */
+        skills: '.agents/skills',
+    },
+    /** Claude Code. */
+    claude: {
+        /** ~/.claude */
+        home: '.claude',
+        /** ~/.claude/skills */
+        skills: '.claude/skills',
+    },
+    /** Cursor. */
+    cursor: {
+        /** ~/.cursor */
+        home: '.cursor',
+        /** ~/.cursor/skills */
+        skills: '.cursor/skills',
+    },
 };
 const MCP_ARGS = ['-y', '@connortessaro/pai', 'mcp'];
 function mcpHint(agent) {
@@ -961,7 +1230,6 @@ export function claudeProvider(env, opts = {}) {
             die(`${file} is not valid JSON; fix it first so setup doesn't overwrite it`);
         }
     }
-    const baseUrl = (env.PHANTOM_BASE_URL || DEFAULT_BASE_URL).replace(/\/v1\/?$/, '');
     const ours = typeof settings.apiKeyHelper === 'string' && /pai.* key show$/.test(settings.apiKeyHelper);
     const vars = { ...(settings.env ?? {}) };
     if (opts.off) {
@@ -979,6 +1247,7 @@ export function claudeProvider(env, opts = {}) {
     }
     if (!resolveApiKey(env))
         die('No API key to give Claude Code. Run: pai login', 'no_key');
+    const baseUrl = httpsOnly(env.PHANTOM_BASE_URL || DEFAULT_BASE_URL).replace(/\/v1\/?$/, '');
     const onPathFn = opts.onPath ?? onPath;
     // `pai` if it's installed, else this very pai by absolute path: Claude Code
     // runs the helper outside this shell, so a relative or npx path won't do.
@@ -1000,6 +1269,13 @@ export function claudeProvider(env, opts = {}) {
         warnings.push('auto runs what the key\'s route policy picks; set one with: pai route set --models a,b');
     return { settings: file, on: true, base_url: baseUrl, model: vars.ANTHROPIC_MODEL, warnings };
 }
+/**
+ * Installs the phantom-ai skill for one agent, or for every agent found
+ * (see {@link SETUP_AGENTS}). With `mcp`, also adds the MCP server to Claude
+ * Code, Codex (through their CLIs) or Cursor (~/.cursor/mcp.json). With
+ * `provider`, also runs {@link claudeProvider}.
+ * @throws {@link CliError} when no agent is found, the agent is unknown, or `provider` is set without claude.
+ */
 export function setupAgents(env, opts = {}) {
     const home = env.HOME || os.homedir();
     const names = Object.keys(SETUP_AGENTS);
@@ -1090,6 +1366,10 @@ export function resolveWalletName(env, name) {
         die(`No saved wallet named ${pick}. Saved: ${saved.join(', ') || 'none'}`, 'wallet_missing');
     return pick;
 }
+/**
+ * The most one wallet payment may spend, from PHANTOM_WALLET_MAX_USD.
+ * @throws {@link CliError} `wallet_cap_missing` when it is unset or not a positive number, so no payment happens without a cap.
+ */
 export function walletCap(env) {
     const cap = Number(env.PHANTOM_WALLET_MAX_USD);
     if (!env.PHANTOM_WALLET_MAX_USD || !Number.isFinite(cap) || cap <= 0) {
@@ -1223,6 +1503,10 @@ export async function checkPaymentRequest(env, req, amountUsd, coin) {
         die(`The payment request asks for ${Number(units) / 1e9} SOL (about $${usd.toFixed(2)}) for $${amountUsd}`, 'wallet_request_mismatch');
     }
 }
+/**
+ * A 64-byte Solana secret key from base58 text or a JSON array of numbers (the format solana-keygen writes).
+ * @throws {@link CliError} `wallet_invalid` when the result is not 64 bytes.
+ */
 export function parseWalletSecret(raw) {
     const text = raw.trim();
     const bytes = text.startsWith('[')
@@ -1232,12 +1516,18 @@ export function parseWalletSecret(raw) {
         die('The wallet key must be a 64-byte Solana secret key', 'wallet_invalid');
     return bytes;
 }
+/**
+ * The wallet that pays, as a signer: PHANTOM_WALLET_KEY, else
+ * PHANTOM_WALLET_FILE, else the saved wallet {@link resolveWalletName} picks.
+ */
 export async function loadWallet(env, name) {
     const which = resolveWalletName(env, name);
     // By the environment, not the name, so a saved wallet may be called env or file.
     const raw = env.PHANTOM_WALLET_KEY
         ? env.PHANTOM_WALLET_KEY
-        : readFileSync(env.PHANTOM_WALLET_FILE ? env.PHANTOM_WALLET_FILE : walletPath(env, which), 'utf-8');
+        : env.PHANTOM_WALLET_FILE
+            ? readFileSync(env.PHANTOM_WALLET_FILE, 'utf-8')
+            : readSecret(env, walletPath(env, which));
     return createKeyPairSignerFromBytes(parseWalletSecret(raw));
 }
 /** A new keypair as solana-keygen writes it: 32-byte seed then public key. */
@@ -1267,6 +1557,7 @@ function u64le(value) {
     new DataView(out.buffer).setBigUint64(0, value, true);
     return out;
 }
+/** A Solana System Program transfer of `lamports` from one address to another. */
 export function solTransferInstruction(from, to, lamports) {
     const data = new Uint8Array(12);
     new DataView(data.buffer).setUint32(0, 2, true); // SystemProgram::Transfer
@@ -1280,6 +1571,7 @@ export function solTransferInstruction(from, to, lamports) {
         data,
     };
 }
+/** The address of `owner`'s standard token account for `mint`. */
 export async function associatedTokenAddress(owner, mint) {
     const enc = getAddressEncoder();
     const [ata] = await getProgramDerivedAddress({
@@ -1288,6 +1580,7 @@ export async function associatedTokenAddress(owner, mint) {
     });
     return ata;
 }
+/** Creates `owner`'s token account for `mint`, paid by `payer`. Does nothing if the account exists. */
 export function createTokenAccountInstruction(payer, ata, owner, mint) {
     return {
         programAddress: address(ATA_PROGRAM),
@@ -1302,6 +1595,7 @@ export function createTokenAccountInstruction(payer, ata, owner, mint) {
         data: new Uint8Array([1]), // CreateIdempotent: a no-op if the account exists
     };
 }
+/** A token transfer of `amount` base units from one token account to another, checked against the mint and its decimals. */
 export function tokenTransferInstruction(source, mint, destination, owner, amount, decimals) {
     const data = new Uint8Array(10);
     data[0] = 12; // TransferChecked
@@ -1327,6 +1621,7 @@ async function tokenUnits(rpc, ata) {
         return BigInt(0); // no token account yet
     }
 }
+/** A wallet's address and its SOL and USDC balance, read from the Solana RPC. */
 export async function walletStatus(env, name) {
     const which = resolveWalletName(env, name);
     const wallet = await loadWallet(env, which);
@@ -1363,8 +1658,7 @@ export async function createWallet(env, name = 'main') {
     let created = false;
     if (!existsSync(file)) {
         const first = savedWalletNames(env).length === 0;
-        mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-        writeFileSync(file, JSON.stringify(Array.from(newSecretKey())), { mode: 0o600, flag: 'wx' });
+        writeSecret(env, file, JSON.stringify(Array.from(newSecretKey())), { flag: 'wx' });
         if (first)
             useWallet(env, name);
         created = true;
@@ -1446,12 +1740,20 @@ function pendingPath(apiKey, env) {
  * money may have left the wallet and paying again is the costly mistake.
  */
 function readPending(apiKey, env) {
+    const file = pendingPath(apiKey, env);
+    if (!existsSync(file))
+        return null;
+    // A file that exists but can't be read may record a payment already sent.
+    // Treating it as "nothing pending" would pay again, so stop instead.
     try {
-        return JSON.parse(readFileSync(pendingPath(apiKey, env), 'utf-8'));
+        const p = JSON.parse(readFileSync(file, 'utf-8'));
+        if (p && typeof p === 'object' && typeof p.payment_id === 'string')
+            return p;
     }
     catch {
-        return null;
+        /* falls through */
     }
+    die(`The pending payment record at ${file} is unreadable, so pai won't pay again in case it was already sent. Check the wallet's history, then delete the file.`, 'pending_corrupt');
 }
 /** Codes that mean Phantom AI reported the payment dead, so nothing more will be credited. */
 const PAYMENT_DEAD = new Set(['payment_expired', 'payment_failed', 'payment_refunded']);
@@ -1461,8 +1763,9 @@ function writePending(apiKey, env, p) {
         rmSync(file, { force: true });
         return;
     }
-    mkdirSync(path.dirname(file), { recursive: true });
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
     writeFileSync(file, JSON.stringify(p), { mode: 0o600 });
+    chmodSync(file, 0o600);
 }
 const COIN_LABEL = { usdc: 'USDC', usdcsol: 'USDC', sol: 'SOL' };
 const coinLabel = (c) => COIN_LABEL[c.toLowerCase()] ?? c.toUpperCase();
@@ -1598,6 +1901,7 @@ export async function autoTopup(apiKey, env, opts) {
     const payment = await buyAndPay(apiKey, env, opts);
     return { balance_usd: payment.balance_after_usd, below_usd: opts.below_usd, bought: true, payment };
 }
+/** `--table` output for one wallet. */
 export function tableWallet(d) {
     const w = d;
     return [
@@ -1609,6 +1913,7 @@ export function tableWallet(d) {
         ...(w.file ? [`file            ${w.file}${w.created ? ' (new, back it up)' : ''}`] : []),
     ].join('\n');
 }
+/** `--table` output for a list of wallets, numbered. */
 export function tableWallets(d) {
     const { wallets } = d;
     if (wallets.length === 0)
@@ -1617,6 +1922,7 @@ export function tableWallets(d) {
         .map((w, i) => `${i + 1}. ${w.name}${w.default ? ' (default)' : ''}  ${w.address}  ${w.usdc} USDC  ${w.sol} SOL`)
         .join('\n');
 }
+/** `--table` output for `buy --pay`. */
 export function tableSelfPay(d) {
     const r = d;
     return [
@@ -1641,6 +1947,7 @@ export function progress(io) {
     };
     const draw = () => io.stderr(`\r\x1b[2K${frames[(i = (i + 1) % frames.length)]} ${fit(text)}`);
     return {
+        /** Shows `next` as the current step, and marks the one before it done. */
         step(next) {
             if (next === text)
                 return;
@@ -1655,6 +1962,7 @@ export function progress(io) {
             draw();
             timer ??= setInterval(draw, 100);
         },
+        /** Marks the current step done, and prints `final` if given. */
         end(final) {
             if (timer)
                 clearInterval(timer);
@@ -1699,6 +2007,7 @@ async function pickWallet(env, io) {
         rl.close();
     }
 }
+/** `--table` output for `autotopup`. */
 export function tableAutoTopup(d) {
     const r = d;
     return [
@@ -1708,6 +2017,11 @@ export function tableAutoTopup(d) {
     ].join('\n');
 }
 // ── helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Prints an error to stderr as one line of JSON, `{"error":{...}}`, and
+ * returns the exit code: 2 for a key the API rejected (401 or 403), the
+ * {@link CliError}'s own code, or 1 for anything else.
+ */
 export function handleError(err, stderr = (s) => process.stderr.write(s)) {
     if (err instanceof PhantomApiError) {
         stderr(JSON.stringify({
@@ -1725,6 +2039,11 @@ export function handleError(err, stderr = (s) => process.stderr.write(s)) {
     stderr(JSON.stringify({ error: { code: 'unknown', message: msg } }) + '\n');
     return 1;
 }
+/**
+ * Reads `--name value`, `--name=value` and bare `--name` (true) from the
+ * arguments. A value that starts with `--` counts as the next flag. Anything
+ * not after a `--name` is skipped.
+ */
 export function parseFlags(args) {
     const flags = {};
     for (let i = 0; i < args.length; i++) {
@@ -1744,6 +2063,10 @@ export function parseFlags(args) {
     }
     return flags;
 }
+/**
+ * A flag's value as a number, or undefined when the flag is absent.
+ * @throws {@link CliError} when the flag has no value or the value is not a number.
+ */
 export function flagNum(flags, name) {
     const v = flags[name];
     if (v === undefined)
@@ -1756,6 +2079,7 @@ export function flagNum(flags, name) {
         die(`--${name} must be a number`);
     return n;
 }
+/** Prints a result: JSON by default, or `render(data)` with `--table`. */
 export function out(data, table, render, stdout = (s) => process.stdout.write(s)) {
     if (table) {
         stdout(render(data) + '\n');
@@ -1765,6 +2089,7 @@ export function out(data, table, render, stdout = (s) => process.stdout.write(s)
     }
 }
 // ── table renderers ──────────────────────────────────────────────────────────
+/** `--table` output for `balance`. */
 export function tableBalance(d) {
     const b = d;
     return [
@@ -1775,6 +2100,7 @@ export function tableBalance(d) {
         `expires_at      ${b.expires_at}`,
     ].join('\n');
 }
+/** `--table` output for `budget`. */
 export function tableBudget(d) {
     const b = d;
     return [
@@ -1787,6 +2113,7 @@ export function tableBudget(d) {
         `rate_exceeded   ${b.rate_exceeded}`,
     ].join('\n');
 }
+/** `--table` output for `plan`. */
 export function tablePlan(d) {
     const b = d;
     if (b.budget_usd === null)
@@ -1801,6 +2128,7 @@ export function tablePlan(d) {
         `ends            ${b.period_ends ?? '—'}`,
     ].join('\n');
 }
+/** `--table` output for `route`. */
 export function tableRoute(d) {
     const p = d.route_policy;
     if (!p)
@@ -1815,6 +2143,7 @@ export function tableRoute(d) {
         ...(rules.length ? rules.map((r, i) => `rule ${String(i + 1).padEnd(11)}if ${Object.entries(r.if).map(([k, v]) => `${k}=${v}`).join(' ')} use ${r.use}`) : ['rules           none (auto runs the first model)']),
     ].join('\n');
 }
+/** `--table` output for `route test`. */
 export function tableRouteTest(d) {
     const t = d;
     return [`model           ${t.model}`, `reason          ${t.reason}`].join('\n');
@@ -1826,6 +2155,7 @@ function savedChild(env, name, result) {
     delete rest.api_key;
     return { ...rest, saved_as: saved.name, id: saved.id };
 }
+/** `--table` output for `memory list` and `memory search`. */
 export function tableNotes(d) {
     const { notes } = d;
     if (notes.length === 0)
@@ -1834,10 +2164,12 @@ export function tableNotes(d) {
         .map((n) => `${n.id}  ${n.title}${n.tags.length ? `  [${n.tags.join(', ')}]` : ''}`)
         .join('\n');
 }
+/** `--table` output for `memory show`. */
 export function tableNote(d) {
     const n = d;
     return [`# ${n.title}`, `${n.id} · ${n.space}${n.tags.length ? ` · ${n.tags.join(', ')}` : ''}`, '', n.text].join('\n');
 }
+/** `--table` output for `key list`. */
 export function tableKeys(d) {
     const { keys } = d;
     if (keys.length === 0)
@@ -1849,6 +2181,7 @@ export function tableKeys(d) {
     })
         .join('\n');
 }
+/** `--table` output for `child`. */
 export function tableChild(d) {
     const c = d;
     return [
@@ -1859,6 +2192,7 @@ export function tableChild(d) {
         `parent_balance  $${c.parent_balance_usd.toFixed(4)}`,
     ].join('\n');
 }
+/** `--table` output for `children`. */
 export function tableChildren(d) {
     const r = d;
     const cap = (v, unit = '') => (v === null ? 'uncapped' : '$' + v.toFixed(4) + unit);
@@ -1877,6 +2211,7 @@ export function tableChildren(d) {
     ];
     return lines.join('\n');
 }
+/** `--table` output for `buy` without `--pay`: what to send, and where. */
 export function tableSolanaPayment(d) {
     const p = d;
     return [
@@ -1888,6 +2223,7 @@ export function tableSolanaPayment(d) {
         `expires         ${p.expires_at}`,
     ].join('\n');
 }
+/** `--table` output for `payment`. */
 export function tablePaymentStatus(d) {
     const s = d;
     return [
@@ -1895,6 +2231,7 @@ export function tablePaymentStatus(d) {
         `credit          $${s.credit_usd.toFixed(4)}${s.topped_up ? ' added to this key' : ''}`,
     ].join('\n');
 }
+/** `--table` output for `rotate`. */
 export function tableRotate(d) {
     const r = d;
     return [
@@ -1902,6 +2239,7 @@ export function tableRotate(d) {
         `rotated_at      ${r.rotated_at}`,
     ].join('\n');
 }
+/** `--table` output for `setup`. */
 export function tableSetup(d) {
     const r = d;
     return r.agents
@@ -1920,6 +2258,7 @@ export function tableSetup(d) {
     ].join('\n'))
         .join('\n');
 }
+/** `--table` output for `verify --model`. */
 export function tableVerifyModel(d) {
     const v = d;
     return [
@@ -1931,6 +2270,7 @@ export function tableVerifyModel(d) {
         ...(v.reason ? [`reason          ${v.reason}`] : []),
     ].join('\n');
 }
+/** `--table` output for `verify --receipt`. */
 export function tableReceiptCheck(d) {
     const c = d;
     return [
@@ -1941,6 +2281,7 @@ export function tableReceiptCheck(d) {
         ...(c.reason ? [`reason          ${c.reason}`] : []),
     ].join('\n');
 }
+/** `--table` output for `burn`. */
 export function tableBurn(d) {
     const b = d;
     return [
@@ -1957,8 +2298,9 @@ export function tableBurn(d) {
 export const ENV_VARS = [
     { name: 'PHANTOM_API_KEY', group: 'general', about: 'your Phantom AI API key (or save one with login)', secret: true },
     { name: 'PHANTOM_KEY_NAME', group: 'general', about: 'run as a key saved with key save or child --save; wins over PHANTOM_API_KEY' },
-    { name: 'PHANTOM_BASE_URL', group: 'general', about: `API base (default ${DEFAULT_BASE_URL})` },
+    { name: 'PHANTOM_BASE_URL', group: 'general', about: `API base, https:// only (default ${DEFAULT_BASE_URL})` },
     { name: 'PHANTOM_STATE_DIR', group: 'general', about: 'where pai keeps keys, wallets, notes and mail settings (default ~/.config/phantom-key)' },
+    { name: 'PAI_KEYCHAIN', group: 'general', about: '0 saves keys, wallets and the mail login to files instead of the macOS Keychain; 1 uses the Keychain on any system, which fails where /usr/bin/security is missing' },
     { name: 'PAI_MEMORY_SPACE', group: 'general', about: 'which space memory and browser use (default: the key name, or main)' },
     { name: 'PAI_SANDBOX_ENGINE', group: 'general', about: 'docker or podman (default: whichever is running)' },
     { name: 'PAI_MAIL_PASSWORD', group: 'general', about: 'the mail password for mail setup, instead of the prompt', secret: true },
@@ -1987,13 +2329,15 @@ function envHelp() {
         '  Saved wallets live in ~/.config/phantom-key/wallets/.',
     ].join('\n');
 }
+/** The text `pai --help` prints. */
 export const HELP = `
 pai — keys, money and subagents for AI agents (Phantom AI)
 
 Commands:
   balance                           show credit balance and expiry
   budget get                        show current budget / rate caps
-  budget set --budget <usd>         set monthly budget cap
+  budget set --budget <usd>         set the spending cap per period (a calendar
+                                    month, unless a plan set another length)
              --rate <usd/min>       set per-minute rate cap (can combine)
   budget clear                      remove all caps
   child --limit <usd|none>          mint a child key that spends this key's balance,
@@ -2010,7 +2354,7 @@ Commands:
   plan                              money for a set period, and how the pace is going
   plan set --amount <usd> [--days n] set a plan (default period: a calendar month)
   plan clear                        remove the plan
-  route                             show which model "auto" runs, and why
+  route [get]                       show which model "auto" runs, and why
   route set --models a,b,c          models for "auto", first is the default
             [--applies-to auto|all] [--on-empty stop|cheapest] [--fallback]
             [--stick-minutes n]  keep a conversation's model this long (default 5)
@@ -2043,18 +2387,22 @@ Commands:
   burn [--key-name <name>]          revoke this key (or a saved one) and forget the
                                     saved copy; its children stop too
   memory add <text> [--tag a,b] [--title t]   keep a note (or pipe it on stdin)
-  memory search <words> [--tag t] [--any]     notes that match, best first
-  memory list [--tag t] / show <id> / rm <id> newest notes, one note, forget one
+  memory search <words> [--tag t] [--any] [--limit n]   notes that match, best first (default 10)
+  memory list [--tag t] [--limit n] / show <id> / rm <id>   newest notes (default 50), one note, forget one
   memory spaces                     every notebook and how many notes it holds
+                                    (memory takes --space <name>; notes stay on this machine)
   browser setup [--install]         check (or install) agent-browser, a browser for agents
-  browser <command>                 drive it: open <url>, snapshot -i, click @e1, fill @e2 "x",
+  browser status                    the same as browser setup
+  browser <command> [--space <name>]  drive it: open <url>, snapshot -i, click @e1, fill @e2 "x",
                                     screenshot; each space keeps its own session and logins
   mail setup --user <address> [--imap h:p] [--smtp h:p]
                                     connect your own mailbox with an app password
                                     (Gmail, Outlook, iCloud, Fastmail are preset)
+             [--insecure]           allow a plain-text login, for a local test server only
   mail [status]                     which mailbox, and whether sending is on
   mail list [--unread] [--from x] [--limit n] / mail search <words>
   mail read <uid>                   one message as text
+                                    (list, search, read and --reply take --folder <name>, default INBOX)
   mail draft --to <a> --subject <s> [--reply <uid>] [--body "..."]  (or pipe the body)
                                     save to Drafts; nothing is sent
   mail send  (same flags)           only with PAI_MAIL_SEND=1, to PAI_MAIL_SEND_TO, up to PAI_MAIL_MAX_PER_DAY recipients
@@ -2062,7 +2410,6 @@ Commands:
   sandbox run [--image i] [--net] [--write] [--timeout s] -- <command>
                                     run a command in a throwaway container: no network,
                                     this folder read-only, unless --net / --write
-                                    (all take --space <name>; notes stay on this machine)
   login [key]                       save your key so you don't need PHANTOM_API_KEY
                                     (prompts if no key is given)
   logout                            remove the saved key
@@ -2074,13 +2421,26 @@ Commands:
   verify --model <id>               make one tiny call and check its signed receipt
                                     names the model you asked for (costs a fraction of a cent)
   verify --receipt <receipt>        check a receipt you already have
-  mcp                              run as an MCP server over stdio
+  mcp                               run as an MCP server over stdio
 
 Flags:
-  --table   human-readable output instead of JSON
+  --table          human-readable output instead of JSON
+  --help, -h       print this help and run nothing
+  --version, -v    print the version
 
 ${envHelp()}
 `.trim();
+/**
+ * Runs one CLI command and returns its exit code: 0 on success, 2 when the
+ * API rejected the key, 1 for other errors. `verify` returns 1 when the check
+ * fails. `browser` and `sandbox run` return the exit code of the command they
+ * ran (124 when the sandbox times out). Errors go to `io.stderr` as JSON
+ * through {@link handleError}. It never calls `process.exit`, except that
+ * `autotopup --every` loops until the process is stopped.
+ * @param argv The arguments after `pai`.
+ * @param env The environment to read settings from.
+ * @param io Where output goes, and whether stderr is a terminal (for progress lines).
+ */
 export async function run(argv = process.argv.slice(2), env = process.env, io = {
     stdout: (s) => process.stdout.write(s),
     stderr: (s) => process.stderr.write(s),
@@ -2090,7 +2450,10 @@ export async function run(argv = process.argv.slice(2), env = process.env, io =
         io.stdout(VERSION + '\n');
         return 0;
     }
-    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    // `--help` anywhere before a `--` asks for help, so `pai setup --help`
+    // prints it rather than running setup.
+    const own = argv.includes('--') ? argv.slice(0, argv.indexOf('--')) : argv;
+    if (argv.length === 0 || own.includes('--help') || own.includes('-h')) {
         io.stdout(HELP + '\n');
         return 0;
     }
@@ -2729,7 +3092,8 @@ export async function run(argv = process.argv.slice(2), env = process.env, io =
 // ── MCP server ──────────────────────────────────────────────────────────────
 /**
  * The same calls as the commands above, as MCP tools. Each tool reads the key
- * (PHANTOM_API_KEY, else the one saved by login) and PHANTOM_BASE_URL when it
+ * ({@link resolveApiKey}: PHANTOM_KEY_NAME, then PHANTOM_API_KEY, then the one
+ * saved by login) and PHANTOM_BASE_URL when it
  * runs, so the server starts and lists its tools without a key and reports a
  * missing key as a tool error.
  */
@@ -2989,13 +3353,13 @@ export function createMcpServer(env = process.env) {
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, ({ model }) => call((key, base) => testRoute(key, { model: model ?? 'auto' }, base)));
     server.registerTool('get_budget', {
-        description: 'Monthly spending cap and per-minute cap of the configured key, and what has been spent against each.',
+        description: 'Spending cap for the period (a calendar month unless a plan set another length) and per-minute cap of the configured key, and what has been spent against each.',
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, () => call(getBudget));
     server.registerTool('set_budget', {
-        description: 'Set or remove the monthly cap and per-minute cap on the configured key. Pass null to remove a cap.',
+        description: 'Set or remove the spending cap for the period (a calendar month unless a plan set another length) and the per-minute cap on the configured key. Pass null to remove a cap.',
         inputSchema: {
-            budget_usd: usd.nullable().optional().describe('Monthly cap in USD, or null to remove it'),
+            budget_usd: usd.nullable().optional().describe('Cap for the period in USD, or null to remove it'),
             rate_usd_per_min: usd.nullable().optional().describe('Per-minute cap in USD, or null to remove it'),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
@@ -3054,9 +3418,11 @@ export function createMcpServer(env = process.env) {
     }, (args) => call((key, base) => getPaymentStatus(key, args.payment_id, base)));
     return server;
 }
+/** Runs {@link createMcpServer} over stdio, as `pai mcp` does. */
 export async function startMcpServer(env = process.env) {
     await createMcpServer(env).connect(new StdioServerTransport());
 }
+/** The installed entry point: {@link run} with the process's arguments, then `process.exit` with its code when it is not 0. */
 export async function main() {
     const code = await run();
     if (code !== 0) {