@palmyr/cli 1.6.0 → 1.8.0

package/dist/cli.js

@@ -376,6 +376,336 @@ const WALLET_HELP = {
         { flag: '--src-decimals <n>', desc: 'Source token decimals', hint: 'default 18' },
         { flag: '--dst-decimals <n>', desc: 'Dest token decimals', hint: 'default 6 (USDC-like)' },
     ],
+    'pay-preflight': [
+        { flag: '--chain <c>', desc: 'Override the default pay chain', hint: 'solana | base (default: config.defaultPayChain)' },
+        { flag: '--wallet <ID>', desc: 'Override the wallet to check', hint: 'default: config.defaultPayWalletId / PALMYR_PAY_WALLET / auto-pick' },
+        { flag: '--min-usdc <N>', desc: 'Required USDC balance to pass (default 0 — just check the wallet exists)' },
+        { flag: '--passphrase <p>', desc: 'Wallet passphrase if no OS-keychain session secret', hint: 'or PALMYR_WALLET_PASSPHRASE env' },
+        { flag: '(price)', desc: 'Free — one RPC call to read USDC balance' },
+        { flag: '(example)', desc: 'palmyr wallet pay-preflight --chain base --min-usdc 3 --json' },
+        { flag: '(note)', desc: 'Local-only version runs automatically before every paid command (set PALMYR_NO_PREFLIGHT=1 to disable)' },
+    ],
+};
+const PHONE_HELP = {
+    search: [
+        { flag: '--country <ISO>', desc: 'Country code', hint: 'default US (e.g. US, GB, AE)' },
+        { flag: '--limit <N>', desc: 'Max results to return' },
+        { flag: '(price)', desc: 'Free — no payment required' },
+        { flag: '(example)', desc: 'palmyr phone search --country US --json' },
+    ],
+    buy: [
+        { flag: '--country <ISO>', desc: 'Country code (required)', hint: 'e.g. US, GB' },
+        { flag: '--area <code>', desc: 'Preferred area code (optional, US only)' },
+        { flag: '(price)', desc: '$3.00 per number provisioned' },
+        { flag: '(example)', desc: 'palmyr phone buy --country US' },
+    ],
+    sms: [
+        { flag: '--id <PHONE_ID>', desc: 'Source phone number id (required)' },
+        { flag: '--to <+E.164>', desc: 'Destination phone number (required)', hint: 'e.g. +15551234567' },
+        { flag: '--body <text>', desc: 'Message body (required)' },
+        { flag: '(price)', desc: '$0.05 per SMS sent' },
+        { flag: '(example)', desc: 'palmyr phone sms --id PN_abc --to +15551234567 --body "hi"' },
+    ],
+    call: [
+        { flag: '--id <PHONE_ID>', desc: 'Source phone number id (required)' },
+        { flag: '--to <+E.164>', desc: 'Destination phone number (required)' },
+        { flag: '--tts <text>', desc: 'Text-to-speech to play on answer (optional)' },
+        { flag: '(price)', desc: '$0.10 per call placed' },
+        { flag: '(example)', desc: 'palmyr phone call --id PN_abc --to +15551234567 --tts "hello"' },
+    ],
+    list: [
+        { flag: '(no args)', desc: 'List phone numbers owned by your wallet' },
+        { flag: '(price)', desc: '$0.01 per call' },
+        { flag: '(example)', desc: 'palmyr phone list --json' },
+    ],
+    messages: [
+        { flag: '--id <PHONE_ID>', desc: 'Phone number id to read SMS for (required; positional also accepted)' },
+        { flag: '(price)', desc: '$0.02 per call' },
+        { flag: '(example)', desc: 'palmyr phone messages --id PN_abc' },
+    ],
+    calls: [
+        { flag: '--id <PHONE_ID>', desc: 'Phone number id to list calls for (required; positional also accepted)' },
+        { flag: '(price)', desc: '$0.02 per call' },
+        { flag: '(example)', desc: 'palmyr phone calls --id PN_abc' },
+    ],
+    release: [
+        { flag: '--id <PHONE_ID>', desc: 'Phone number id to release (required; positional also accepted)' },
+        { flag: '(price)', desc: '$0.01 per release (stops monthly Telnyx billing)' },
+        { flag: '(example)', desc: 'palmyr phone release --id PN_abc' },
+    ],
+    'call-info': [
+        { flag: '--call <CALL_ID>', desc: 'Call control id (required; --id and positional also accepted)' },
+        { flag: '(price)', desc: '$0.02 per lookup' },
+        { flag: '(example)', desc: 'palmyr phone call-info --call CC_abc' },
+    ],
+    speak: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '--text <text>', desc: 'TTS text to speak (required; --tts alias accepted)' },
+        { flag: '--voice <name>', desc: 'TTS voice (optional, provider default otherwise)' },
+        { flag: '--language <code>', desc: 'TTS language code (optional, e.g. en-US)' },
+        { flag: '(price)', desc: '$0.08 per speak action' },
+        { flag: '(example)', desc: 'palmyr phone speak --call CC_abc --text "please hold"' },
+    ],
+    play: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '--url <audio_url>', desc: 'Public audio URL to play (required; --audio-url alias accepted)' },
+        { flag: '(price)', desc: '$0.08 per playback' },
+        { flag: '(example)', desc: 'palmyr phone play --call CC_abc --url https://example.com/hold.mp3' },
+    ],
+    dtmf: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '--digits <seq>', desc: 'DTMF digit sequence (required; positional also accepted)', hint: 'e.g. "1234#"' },
+        { flag: '(price)', desc: '$0.02 per DTMF send' },
+        { flag: '(example)', desc: 'palmyr phone dtmf --call CC_abc --digits "1234#"' },
+    ],
+    gather: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '--min-digits <N>', desc: 'Minimum digits to collect (optional)' },
+        { flag: '--max-digits <N>', desc: 'Maximum digits to collect (optional)' },
+        { flag: '--timeout <ms>', desc: 'Per-input timeout in milliseconds (optional)' },
+        { flag: '--terminating-digit <d>', desc: 'Digit that ends collection (optional, e.g. "#")' },
+        { flag: '--prompt <text>', desc: 'Optional TTS prompt to play before gathering' },
+        { flag: '--prompt-voice <name>', desc: 'TTS voice for the prompt (optional)' },
+        { flag: '(price)', desc: '$0.08 per gather action' },
+        { flag: '(example)', desc: 'palmyr phone gather --call CC_abc --max-digits 4 --terminating-digit "#" --prompt "Enter PIN"' },
+    ],
+    record: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '--format <fmt>', desc: 'Recording format (optional, provider default otherwise)' },
+        { flag: '(price)', desc: '$0.10 per record start' },
+        { flag: '(example)', desc: 'palmyr phone record --call CC_abc --format mp3' },
+    ],
+    'record-stop': [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '(price)', desc: '$0.02 per stop' },
+        { flag: '(example)', desc: 'palmyr phone record-stop --call CC_abc' },
+    ],
+    hangup: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '(price)', desc: '$0.02 per hangup' },
+        { flag: '(example)', desc: 'palmyr phone hangup --call CC_abc' },
+    ],
+    answer: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of an inbound call (required)' },
+        { flag: '(price)', desc: '$0.02 per answer' },
+        { flag: '(example)', desc: 'palmyr phone answer --call CC_abc' },
+    ],
+    transfer: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '--to <+E.164>', desc: 'Destination phone number to bridge into (required)' },
+        { flag: '(price)', desc: '$0.10 per transfer' },
+        { flag: '(example)', desc: 'palmyr phone transfer --call CC_abc --to +15557654321' },
+    ],
+};
+const EMAIL_HELP = {
+    create: [
+        { flag: '--name <name>', desc: 'Inbox name (required)' },
+        { flag: '--domain <domain>', desc: 'Wallet-owned domain to host the inbox on (optional)', hint: 'default: Palmyr-hosted domain' },
+        { flag: '--wallet <id|name>', desc: 'Wallet to own the inbox (optional)' },
+        { flag: '(price)', desc: '$2.00 per inbox provisioned' },
+        { flag: '(example)', desc: 'palmyr email create --name agent --domain example.com' },
+    ],
+    list: [
+        { flag: '(no args)', desc: 'List inboxes owned by your wallet' },
+        { flag: '(price)', desc: '$0.01 per call' },
+        { flag: '(example)', desc: 'palmyr email list --json' },
+    ],
+    status: [
+        { flag: '<domain>', desc: 'Domain to check (positional or --domain)', hint: 'e.g. example.com' },
+        { flag: '(price)', desc: '$0.01 per call' },
+        { flag: '(example)', desc: 'palmyr email status example.com' },
+    ],
+    register: [
+        { flag: '<domain>', desc: 'Wallet-owned domain to (re-)register with Mailgun (positional or --domain)' },
+        { flag: '(price)', desc: '$0.05 per registration' },
+        { flag: '(example)', desc: 'palmyr email register example.com' },
+    ],
+    read: [
+        { flag: '--id <INBOX_ID>', desc: 'Inbox id (required; positional also accepted)' },
+        { flag: '(price)', desc: '$0.02 per call' },
+        { flag: '(example)', desc: 'palmyr email read --id INB_abc123' },
+    ],
+    send: [
+        { flag: '--id <INBOX_ID>', desc: 'Source inbox id (required)' },
+        { flag: '--to <addr>', desc: 'Destination email (required)' },
+        { flag: '--subject <text>', desc: 'Subject line (required)' },
+        { flag: '--body <text>', desc: 'Message body (required)' },
+        { flag: '(price)', desc: '$0.08 per email sent' },
+        { flag: '(example)', desc: 'palmyr email send --id INB_abc --to user@x.com --subject Hi --body "..."' },
+    ],
+    threads: [
+        { flag: '--id <INBOX_ID>', desc: 'Inbox id (required; positional also accepted)' },
+        { flag: '(price)', desc: '$0.02 per call' },
+        { flag: '(example)', desc: 'palmyr email threads --id INB_abc123' },
+    ],
+};
+const COMPUTE_HELP = {
+    plans: [
+        { flag: '--location <loc>', desc: 'Filter to types deployable in this datacenter (optional)', hint: 'e.g. fsn1, nbg1, hel1, ash, hil' },
+        { flag: '(price)', desc: 'Free — live discovery from Hetzner' },
+        { flag: '(example)', desc: 'palmyr compute plans --location fsn1 --json' },
+    ],
+    locations: [
+        { flag: '(no args)', desc: 'List Hetzner datacenters + per-location server-type availability' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    'install-recipes': [
+        { flag: '(no args)', desc: 'List available agent install recipes (hermes, openclaw, …)' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    'ssh-key': [
+        { flag: 'add <pubkey-file>', desc: 'Upload a key to Hetzner', hint: '[--name "label"]' },
+        { flag: 'list', desc: 'List uploaded Hetzner SSH keys' },
+        { flag: 'delete <id>', desc: 'Remove a Hetzner SSH key' },
+        { flag: '(price)', desc: 'add $0.10 · list $0.01 · delete $0.01' },
+    ],
+    deploy: [
+        { flag: '--type <name>', desc: 'Hetzner server type', hint: 'default cx23' },
+        { flag: '--name <name>', desc: 'Server name', hint: 'default agent-<timestamp>' },
+        { flag: '--location <loc>', desc: 'Hetzner datacenter (optional)', hint: 'e.g. fsn1, nbg1' },
+        { flag: '--install <recipes>', desc: 'Comma-separated install recipes', hint: 'e.g. hermes,openclaw' },
+        { flag: '--no-install', desc: 'Skip cloud-init entirely (vanilla Ubuntu)' },
+        { flag: '--generate-ssh-key', desc: 'GOLDEN PATH (default): generate a fresh keypair locally' },
+        { flag: '--pubkey-file <path>', desc: 'Use an existing public key from disk' },
+        { flag: '--pubkey "ssh-..."', desc: 'Use an inline public key string' },
+        { flag: '--ssh-key <id>', desc: 'Numeric Hetzner key id (already uploaded)' },
+        { flag: '--no-wait', desc: 'Return immediately instead of waiting for SSH-ready' },
+        { flag: '--wait-timeout <s>', desc: 'Override readiness timeout (30–900s)' },
+        { flag: '(price)', desc: '$6.00 per deploy (Hetzner billing flows through)' },
+        { flag: '(example)', desc: 'palmyr compute deploy --type cx23 --install hermes' },
+    ],
+    wait: [
+        { flag: '<name|id>', desc: 'Server (positional, name or numeric id)' },
+        { flag: '--install <recipes>', desc: 'Also gate on the install marker file (e.g. hermes)' },
+        { flag: '--key <path>', desc: 'Path to the private key for SSH verification' },
+        { flag: '--wait-timeout <s>', desc: 'Override readiness timeout (30–900s)' },
+        { flag: '(price)', desc: '$0.01 per readiness poll (server status check)' },
+        { flag: '(example)', desc: 'palmyr compute wait my-vps --install hermes' },
+    ],
+    ssh: [
+        { flag: '<name|id>', desc: 'Server (positional)' },
+        { flag: '(price)', desc: 'Free — local cache lookup only' },
+        { flag: '(example)', desc: 'palmyr compute ssh my-vps' },
+    ],
+    exec: [
+        { flag: '<name|id> -- <cmd> [args...]', desc: 'Run a one-shot command via Palmyr SSH bridge' },
+        { flag: '--timeout <s>', desc: 'Command timeout (1–120s)' },
+        { flag: '(price)', desc: '$0.05 per command' },
+        { flag: '(example)', desc: 'palmyr compute exec my-vps -- systemctl status openclaw' },
+    ],
+    rename: [
+        { flag: '<name|id> <new-name>', desc: 'Rename server (metadata-only, no reboot)' },
+        { flag: '(price)', desc: '$0.01 per rename' },
+    ],
+    'reset-password': [
+        { flag: '<name|id>', desc: 'Rotate the root password (Hetzner-side)' },
+        { flag: '(price)', desc: '$0.10 per action' },
+    ],
+    console: [
+        { flag: '<name|id>', desc: 'Get a noVNC console URL (break-glass)' },
+        { flag: '(price)', desc: '$0.10 per action' },
+    ],
+    reboot: [
+        { flag: '<name|id>', desc: 'Reboot the server' },
+        { flag: '(price)', desc: '$0.10 per action' },
+    ],
+    'setup-ssh': [
+        { flag: '--id <SERVER_ID>', desc: 'Server id (required; positional also accepted)' },
+        { flag: '--pubkey-file <path>', desc: 'Public key file to inject' },
+        { flag: '--pubkey "ssh-..."', desc: 'Inline public key string' },
+        { flag: '(price)', desc: '$0.01 per call' },
+        { flag: '(example)', desc: 'palmyr compute setup-ssh --id 12345 --pubkey-file ~/.ssh/id_ed25519.pub' },
+    ],
+    list: [
+        { flag: '(no args)', desc: 'List your deployed servers' },
+        { flag: '(price)', desc: '$0.01 per call' },
+    ],
+    delete: [
+        { flag: '--id <SERVER_ID>', desc: 'Server id (required; positional also accepted)' },
+        { flag: '(price)', desc: '$0.10 per deletion (Hetzner billing stops on confirm)' },
+    ],
+};
+const DOMAIN_HELP = {
+    check: [
+        { flag: '--name <domain>', desc: 'Domain or root name (positional also accepted)' },
+        { flag: '(price)', desc: 'Free — availability lookup only' },
+        { flag: '(example)', desc: 'palmyr domain check example.dev' },
+    ],
+    pricing: [
+        { flag: '--name <root>', desc: 'Root name to price across TLDs (positional also accepted)' },
+        { flag: '(price)', desc: 'Free' },
+        { flag: '(example)', desc: 'palmyr domain pricing example' },
+    ],
+    buy: [
+        { flag: '--name <domain>', desc: 'Fully-qualified domain (required, e.g. example.dev)' },
+        { flag: '(price)', desc: 'Dynamic — registrar cost × 1.25 markup (charged via x402)' },
+        { flag: '(example)', desc: 'palmyr domain buy --name example.dev' },
+    ],
+    list: [
+        { flag: '(no args)', desc: 'List domains owned or shared with your wallet' },
+        { flag: '(price)', desc: '$0.0001 ownership-proof micro-payment' },
+    ],
+    dns: [
+        { flag: '--name <domain>', desc: 'Domain to read DNS for (positional also accepted)' },
+        { flag: '(price)', desc: '$0.0001 ownership-proof micro-payment' },
+    ],
+    'transfer-ownership': [
+        { flag: '--name <domain>', desc: 'Domain to transfer (required)' },
+        { flag: '--to <wallet>', desc: 'Recipient wallet address (required)' },
+        { flag: '(price)', desc: '$0.0001 ownership-proof micro-payment' },
+    ],
+    share: [
+        { flag: '--name <domain>', desc: 'Domain to share (required)' },
+        { flag: '--with <wallet>', desc: 'Wallet to grant shared access (required)' },
+        { flag: '(price)', desc: '$0.0001 ownership-proof micro-payment' },
+    ],
+    unshare: [
+        { flag: '--name <domain>', desc: 'Domain to revoke from (required)' },
+        { flag: '--from <wallet>', desc: 'Wallet to revoke (required)' },
+        { flag: '(price)', desc: '$0.0001 ownership-proof micro-payment' },
+    ],
+};
+const CHAT_HELP = {
+    run: [
+        { flag: '"<intent>"', desc: 'Plain-string intent (positional or --intent)' },
+        { flag: '--budget <USDC>', desc: 'Max spend cap (required, positive USDC)' },
+        { flag: '--quality <q>', desc: 'Quality tier', hint: 'fast | cheap | best (default best)' },
+        { flag: '--execute', desc: 'Auto-execute the plan once generated' },
+        { flag: '--auto-approve-under <USDC>', desc: 'Skip approval prompts for steps cheaper than this' },
+        { flag: '(price)', desc: '$0.10 orchestration fee + sum of per-step costs (capped by --budget)' },
+        { flag: '(example)', desc: 'palmyr chat run "launch a sneaker brand" --budget 50' },
+    ],
+    resume: [
+        { flag: '<session_id>', desc: 'Existing session id (positional)' },
+        { flag: '"<follow-up>"', desc: 'Follow-up intent (positional remainder or --intent)' },
+        { flag: '--approve', desc: 'Approve a previously-generated plan' },
+        { flag: '--plan-id <id>', desc: 'Plan id to approve (pair with --approve)' },
+        { flag: '--budget <USDC>', desc: 'Override session budget (default $20)' },
+        { flag: '--execute', desc: 'Auto-execute the new plan' },
+        { flag: '(price)', desc: '$0.10 orchestration fee per new plan + per-step costs' },
+        { flag: '(example)', desc: 'palmyr chat resume sess_abc "now post 3 videos"' },
+    ],
+    status: [
+        { flag: '<session_id>', desc: 'Session id (positional)' },
+        { flag: '(price)', desc: 'Free — session inspection' },
+    ],
+    cancel: [
+        { flag: '<session_id>', desc: 'Session id (positional)' },
+        { flag: '(price)', desc: 'Free — halts execution and refunds remaining escrow' },
+    ],
+    sessions: [
+        { flag: '(no args)', desc: 'List your active i402 sessions' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    capabilities: [
+        { flag: '(no args)', desc: 'List canonical capability classes (e.g. web_search, mint_nft)' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    providers: [
+        { flag: '--capability <name>', desc: 'Filter providers by capability (optional)' },
+        { flag: '(price)', desc: 'Free' },
+        { flag: '(example)', desc: 'palmyr chat providers --capability web_search' },
+    ],
 };
 /**
  * Render a per-command menu (no subcommand given). On a TTY → Ink MenuScreen
@@ -673,7 +1003,7 @@ async function main() {
                 break;
             }
             case 'phone': {
-                if (!subcommand || flags.help) {
+                if (!subcommand || (flags.help && !PHONE_HELP[subcommand])) {
                     showMenu({
                         command: 'phone',
                         title: 'phone',
@@ -682,17 +1012,42 @@ async function main() {
                         commands: [
                             { name: 'search', description: 'Search available numbers', hint: '--country US' },
                             { name: 'buy', description: 'Buy a phone number', hint: '--country US' },
+                            { name: 'list', description: 'List numbers owned by your wallet' },
+                            { name: 'release', description: 'Release a phone number', hint: '--id PHONE_ID' },
                             { name: 'sms', description: 'Send an SMS', hint: '--id ID --to +1... --body "hi"' },
+                            { name: 'messages', description: 'Read SMS messages received on a number', hint: '--id PHONE_ID' },
                             { name: 'call', description: 'Place a voice call', hint: '--id ID --to +1... --tts "hello"' },
+                            { name: 'calls', description: 'List calls placed/received on a number', hint: '--id PHONE_ID' },
+                            { name: 'call-info', description: 'Get details on a single call', hint: '--call CALL_CONTROL_ID' },
+                            { name: 'speak', description: 'TTS into a live call', hint: '--call ID --text "..." [--voice V]' },
+                            { name: 'play', description: 'Play an audio URL into a live call', hint: '--call ID --url https://...' },
+                            { name: 'dtmf', description: 'Send DTMF tones to a live call', hint: '--call ID --digits "1234#"' },
+                            { name: 'gather', description: 'Collect DTMF input from caller', hint: '--call ID [--min-digits N --max-digits N --timeout MS --prompt "..."]' },
+                            { name: 'record', description: 'Start recording a live call', hint: '--call ID [--format mp3]' },
+                            { name: 'record-stop', description: 'Stop recording a live call', hint: '--call ID' },
+                            { name: 'hangup', description: 'End a live call', hint: '--call ID' },
+                            { name: 'answer', description: 'Answer an inbound call', hint: '--call ID' },
+                            { name: 'transfer', description: 'Transfer a live call to another number', hint: '--call ID --to +1...' },
                         ],
                         fromHome,
                     });
                     break;
                 }
+                if (flags.help && subcommand && PHONE_HELP[subcommand]) {
+                    subcommandHelp('phone', subcommand, PHONE_HELP[subcommand]);
+                    break;
+                }
                 switch (subcommand) {
                     case 'search': {
                         const country = flags.country || 'US';
                         const data = await ao.phoneSearch(country, flags.limit ? parseInt(flags.limit) : undefined);
+                        // Empty result is a valid response but `{numbers: []}` alone made it
+                        // ambiguous whether the API failed or the country has no inventory.
+                        // Add a non-breaking `note` field — agents that already key off
+                        // `.numbers.length` keep working; new readers get a clear signal.
+                        if (data && Array.isArray(data.numbers) && data.numbers.length === 0 && !data.note) {
+                            data.note = `No numbers available for ${country}. Try a different country code (US, GB, CA, DE, etc.).`;
+                        }
                         return print(data);
                         render(React.createElement(RecordsScreen, {
                             version: VERSION,
@@ -757,12 +1112,130 @@ async function main() {
                         render(React.createElement(SuccessScreen, { version: VERSION, title: 'calling', subtitle: to, details: [{ label: 'To', value: to }, { label: 'Call ID', value: data.callControlId || data.id || '' }], footerLeft: 'Call initiated' }));
                         break;
                     }
-                    default: err(`Unknown phone command: ${subcommand}. Try: search, buy, sms, call`);
+                    case 'list': {
+                        const data = await ao.phoneListNumbers();
+                        return print(data);
+                    }
+                    case 'messages': {
+                        const id = flags.id || positional[0];
+                        if (!id)
+                            err('--id PHONE_ID required');
+                        const data = await ao.phoneMessages(id);
+                        return print(data);
+                    }
+                    case 'calls': {
+                        const id = flags.id || positional[0];
+                        if (!id)
+                            err('--id PHONE_ID required');
+                        const data = await ao.phoneCalls(id);
+                        return print(data);
+                    }
+                    case 'release': {
+                        const id = flags.id || positional[0];
+                        if (!id)
+                            err('--id PHONE_ID required');
+                        const data = await ao.phoneRelease(id);
+                        return print(data);
+                    }
+                    case 'call-info': {
+                        const callId = flags.call || flags.id || positional[0];
+                        if (!callId)
+                            err('--call CALL_CONTROL_ID required');
+                        const data = await ao.phoneCallInfo(callId);
+                        return print(data);
+                    }
+                    case 'speak': {
+                        const callId = flags.call || flags.id;
+                        const text = flags.text || flags.tts;
+                        if (!callId || !text)
+                            err('--call <id>, --text <text> required');
+                        const voice = flags.voice;
+                        const language = flags.language;
+                        const data = await ao.phoneSpeak(callId, text, { ...(voice ? { voice } : {}), ...(language ? { language } : {}) });
+                        return print(data);
+                    }
+                    case 'play': {
+                        const callId = flags.call || flags.id;
+                        const audioUrl = flags.url || flags['audio-url'];
+                        if (!callId || !audioUrl)
+                            err('--call <id>, --url <https://...> required');
+                        const data = await ao.phonePlay(callId, audioUrl);
+                        return print(data);
+                    }
+                    case 'dtmf': {
+                        const callId = flags.call || flags.id;
+                        const digits = flags.digits || positional[0];
+                        if (!callId || !digits)
+                            err('--call <id>, --digits "1234#" required');
+                        const data = await ao.phoneDtmf(callId, digits);
+                        return print(data);
+                    }
+                    case 'gather': {
+                        const callId = flags.call || flags.id;
+                        if (!callId)
+                            err('--call <id> required');
+                        const parseInt0 = (v) => (typeof v === 'string' ? parseInt(v, 10) : undefined);
+                        const opts = {};
+                        const minDigits = parseInt0(flags['min-digits']);
+                        if (minDigits !== undefined && Number.isFinite(minDigits))
+                            opts.minDigits = minDigits;
+                        const maxDigits = parseInt0(flags['max-digits']);
+                        if (maxDigits !== undefined && Number.isFinite(maxDigits))
+                            opts.maxDigits = maxDigits;
+                        const timeoutMillis = parseInt0(flags.timeout);
+                        if (timeoutMillis !== undefined && Number.isFinite(timeoutMillis))
+                            opts.timeoutMillis = timeoutMillis;
+                        if (flags['terminating-digit'])
+                            opts.terminatingDigit = flags['terminating-digit'];
+                        if (flags.prompt)
+                            opts.prompt = flags.prompt;
+                        if (flags['prompt-voice'])
+                            opts.promptVoice = flags['prompt-voice'];
+                        const data = await ao.phoneGather(callId, opts);
+                        return print(data);
+                    }
+                    case 'record': {
+                        const callId = flags.call || flags.id;
+                        if (!callId)
+                            err('--call <id> required');
+                        const data = await ao.phoneRecord(callId, flags.format);
+                        return print(data);
+                    }
+                    case 'record-stop': {
+                        const callId = flags.call || flags.id;
+                        if (!callId)
+                            err('--call <id> required');
+                        const data = await ao.phoneRecordStop(callId);
+                        return print(data);
+                    }
+                    case 'hangup': {
+                        const callId = flags.call || flags.id;
+                        if (!callId)
+                            err('--call <id> required');
+                        const data = await ao.phoneHangup(callId);
+                        return print(data);
+                    }
+                    case 'answer': {
+                        const callId = flags.call || flags.id;
+                        if (!callId)
+                            err('--call <id> required');
+                        const data = await ao.phoneAnswer(callId);
+                        return print(data);
+                    }
+                    case 'transfer': {
+                        const callId = flags.call || flags.id;
+                        const to = flags.to;
+                        if (!callId || !to)
+                            err('--call <id>, --to <+E.164> required');
+                        const data = await ao.phoneTransfer(callId, to);
+                        return print(data);
+                    }
+                    default: err(`Unknown phone command: ${subcommand}. Try: search, buy, list, release, sms, messages, call, calls, call-info, speak, play, dtmf, gather, record, record-stop, hangup, answer, transfer`);
                 }
                 break;
             }
             case 'email': {
-                if (!subcommand || flags.help) {
+                if (!subcommand || (flags.help && !EMAIL_HELP[subcommand])) {
                     showMenu({
                         command: 'email',
                         title: 'email',
@@ -781,6 +1254,10 @@ async function main() {
                     });
                     break;
                 }
+                if (flags.help && subcommand && EMAIL_HELP[subcommand]) {
+                    subcommandHelp('email', subcommand, EMAIL_HELP[subcommand]);
+                    break;
+                }
                 switch (subcommand) {
                     case 'create': {
                         const name = flags.name || positional[0];
@@ -872,7 +1349,7 @@ async function main() {
                 break;
             }
             case 'compute': {
-                if (!subcommand || flags.help) {
+                if (!subcommand || (flags.help && !COMPUTE_HELP[subcommand])) {
                     showMenu({
                         command: 'compute',
                         title: 'compute',
@@ -899,6 +1376,10 @@ async function main() {
                     });
                     break;
                 }
+                if (flags.help && subcommand && COMPUTE_HELP[subcommand]) {
+                    subcommandHelp('compute', subcommand, COMPUTE_HELP[subcommand]);
+                    break;
+                }
                 switch (subcommand) {
                     case 'plans': {
                         // --location filters to types deployable in that location. Each
@@ -1474,7 +1955,7 @@ async function main() {
                 break;
             }
             case 'domain': {
-                if (!subcommand || flags.help) {
+                if (!subcommand || (flags.help && !DOMAIN_HELP[subcommand])) {
                     showMenu({
                         command: 'domain',
                         title: 'domain',
@@ -1494,6 +1975,10 @@ async function main() {
                     });
                     break;
                 }
+                if (flags.help && subcommand && DOMAIN_HELP[subcommand]) {
+                    subcommandHelp('domain', subcommand, DOMAIN_HELP[subcommand]);
+                    break;
+                }
                 switch (subcommand) {
                     case 'check': {
                         const name = flags.name || positional[0];
@@ -1684,6 +2169,7 @@ async function main() {
                             { name: 'watch', description: 'Maintain a watchlist of CAs to monitor', hint: 'add <CA> --trigger "..." | list' },
                             { name: 'brief', description: 'Show thesis + PnL brief for a position', hint: '<CA>' },
                             { name: 'doctor', description: 'Health check for the wallet-trading subsystem', hint: '[--wallet <ref>]' },
+                            { name: 'pay-preflight', description: 'Check the x402 pay flow is ready (chain, wallet, signing, USDC balance)', hint: '[--chain solana|base] [--min-usdc N]' },
                             { name: 'smoke-test', description: 'End-to-end validation of wallet trading on Solana + Base', hint: '--wallet <ref> [--chain solana|base|all]' },
                             { name: 'readiness', description: 'Go/no-go autonomous-trading readiness — sign, gas, quotes, daemon, open positions', hint: '--wallet <ref>' },
                             { name: 'live-test', description: 'Execute tiny real round trips on Solana + Base, verify no leftover positions', hint: '--wallet <ref> --budget Nusdc [--chain ...]' },
@@ -3337,6 +3823,59 @@ async function main() {
                             process.exit(EXIT.GENERAL);
                         break;
                     }
+                    case 'pay-preflight': {
+                        // Five-question readiness check for the x402 pay flow. Local-only
+                        // siblings of this same module run automatically before every paid
+                        // command (see paidRequest/paidStreamRequest); this command is the
+                        // explicit, full-fat version with the RPC USDC balance check.
+                        const ppChain = flags.chain?.toLowerCase();
+                        if (ppChain && ppChain !== 'solana' && ppChain !== 'base') {
+                            err(`--chain must be solana or base (got ${ppChain})`, EXIT.BAD_INPUT);
+                        }
+                        const ppWallet = flags.wallet || undefined;
+                        const ppMinUsdcRaw = flags['min-usdc'];
+                        const ppMinUsdc = typeof ppMinUsdcRaw === 'string' ? Number(ppMinUsdcRaw) : undefined;
+                        if (ppMinUsdc !== undefined && (!Number.isFinite(ppMinUsdc) || ppMinUsdc < 0)) {
+                            err(`--min-usdc must be a non-negative number (got ${String(ppMinUsdcRaw)})`, EXIT.BAD_INPUT);
+                        }
+                        const { fullPreflight } = await import('./pay-preflight.js');
+                        const report = await fullPreflight({
+                            ...(ppChain ? { chain: ppChain } : {}),
+                            ...(ppWallet ? { walletRef: ppWallet } : {}),
+                            ...(ppMinUsdc !== undefined ? { minUsdc: ppMinUsdc } : {}),
+                            ...(passphrase ? { passphrase } : {}),
+                        });
+                        if (AGENT_MODE) {
+                            print(report);
+                            if (!report.ok)
+                                process.exit(EXIT.GENERAL);
+                            break;
+                        }
+                        // TTY rendering — mirrors the doctor command's layout.
+                        console.log();
+                        section('Pay preflight');
+                        kv('Verdict', report.ok ? `${t.success}ready${t.reset}` : `${t.error}not ready${t.reset}`);
+                        kv('Pay chain', report.payChain);
+                        kv('Wallet ID', report.walletId || `${t.muted}(none)${t.reset}`);
+                        kv('Address', report.walletAddress || `${t.muted}(unknown)${t.reset}`);
+                        kv('Can sign', report.canSign ? `${t.success}yes${t.reset}` : `${t.error}no${t.reset}`);
+                        if (report.usdc) {
+                            const bal = report.usdc.balance;
+                            kv('USDC balance', bal === null ? `${t.muted}(unknown)${t.reset}` : `${bal.toFixed(6)} USDC`);
+                            if (report.usdc.requiredMin > 0)
+                                kv('Required min', `${report.usdc.requiredMin.toFixed(6)} USDC`);
+                            if (report.usdc.ataStatus)
+                                kv('Solana ATA', report.usdc.ataStatus);
+                        }
+                        if (report.fix) {
+                            console.log();
+                            console.log(`  ${t.warn}Fix:${t.reset} ${report.fix}`);
+                        }
+                        console.log();
+                        if (!report.ok)
+                            process.exit(EXIT.GENERAL);
+                        break;
+                    }
                     case 'smoke-test': {
                         const smokeWalletRef = flags.wallet || undefined;
                         if (!smokeWalletRef)
@@ -3917,7 +4456,7 @@ async function main() {
                 break;
             }
             case 'chat': {
-                if (!subcommand || flags.help) {
+                if (!subcommand || (flags.help && !CHAT_HELP[subcommand])) {
                     showMenu({
                         command: 'chat',
                         title: 'chat',
@@ -3936,6 +4475,10 @@ async function main() {
                     });
                     break;
                 }
+                if (flags.help && subcommand && CHAT_HELP[subcommand]) {
+                    subcommandHelp('chat', subcommand, CHAT_HELP[subcommand]);
+                    break;
+                }
                 switch (subcommand) {
                     case 'run': {
                         const intent = (positional.join(' ') || flags.intent || '').trim();