@allscale/cli 0.1.0 → 1.0.2

package/oclif.manifest.json

@@ -3,7 +3,7 @@
     "build-info": {
       "aliases": [],
       "args": {},
-      "description": "Show which API base (if any) this build is bound to, and its signing-key id. Never prints the signing key itself — only its (non-secret, already-forgeable) id.",
+      "description": "Show which API base (if any) this build is bound to, and its signing-key id. Never prints the signing key itself — only its non-secret id.",
       "examples": [
         "$ allscale build-info"
       ],
@@ -18,6 +18,7 @@
         "profile": {
           "description": "Named profile from ~/.allscale/config.toml",
           "helpGroup": "GLOBAL",
+          "hidden": true,
           "name": "profile",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -148,7 +149,7 @@
     "device-login": {
       "aliases": [],
       "args": {},
-      "description": "Log in via browser-confirmed device pairing. Use an existing web session or sign in there with Passkey or Email (enter the Email OTP on the webpage), then approve the CLI. The backend mints a scoped agent key — the only credential this CLI issues; no web sign-in secret is entered in the terminal.",
+      "description": "Log in via browser-confirmed device pairing. Use an existing web session or sign in there with Passkey or Email (enter the Email OTP on the webpage), then approve the CLI. The backend mints a scoped agent key — the credential issued by the current CLI login flows; no web sign-in secret is entered in the terminal.",
       "examples": [
         "$ allscale device-login",
         "$ allscale device-login --device-label tom-mbp-2026",
@@ -203,7 +204,7 @@
           "type": "option"
         },
         "scopes": {
-          "description": "Requested scopes for the eventual agent key, repeatable. Scope strings use `<category>:<tier>`; `:all` implies `:read_only` for the same category. Pairs the approval screen can grant: invoice:{read_only,all}, contact:{read_only,all}, transaction:read_only, wallet:read_only, claim_link:{read_only,all}, store:all. The final set is chosen — and can be overridden — on that screen, and is ENFORCED server-side on every request. The Wallets toggle is on by default and grants `wallet:read_only`, which `invoice pay` and `wallet list` both need.",
+          "description": "Requested scopes for the eventual agent key, repeatable. Scope strings use `<category>:<tier>`; `:all` implies `:read_only` for the same category. Pairs the approval screen can grant: invoice:{read_only,all}, contact:{read_only,all}, transaction:read_only, wallet:{read_only,all}, claim_link:{read_only,all}, store:{read_only,all}. The final set is chosen — and can be overridden — on that screen, and is checked by the backend on each request. The Wallets read toggle is on by default and grants `wallet:read_only`, which `wallet list` needs. `invoice pay` needs `invoice:all` AND `wallet:all` — its withdrawal registration rides the same broker op as `wallet send` (backend gates the op, not the verb), and the write tier covers its payer-address read via the implication — so request both (`--scopes invoice:all --scopes wallet:all`) and tick the Invoices write tier plus the Wallets Allow-changes tier on the screen (Invoices starts at Read; Allow-changes starts OFF). `wallet send` requires `wallet:all` the same way; every transfer still requires your in-browser confirmation. Values are checked locally first: an unrecognised `<category>:<tier>` string exits 2 before any pairing session is registered — the same check, and the same exit code, as `otp-login --scopes`. A recognised scope the screen has no toggle for is also rejected locally, with the remediation that actually works: otp-login for operational scopes (or `--allow-unrenderable-scopes` when your web app is newer than this CLI's catalog), nothing for payroll/admin:* — the approval page refuses the whole authorization when even one requested scope is unrenderable, so deferring the answer to the browser would strand you after a pairing session already exists. An explicitly requested `cli_op:*` is not an error: the backend appends it to every pairing-minted key, so it is omitted from the request with a note and the resulting key is identical. Only a scope the screen renders and the user declines is reported after the key is minted.",
           "name": "scopes",
           "hasDynamicHelp": false,
           "multiple": true,
@@ -215,6 +216,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "allow-unrenderable-scopes": {
+          "description": "Forward a scope to the approval screen even when this CLI's catalog says the screen has no toggle for it. Escape hatch for a stale catalog: the screen-grantable list above is a MIRROR of the web app's approval screen and can lag a frontend release, and without this flag a lagging mirror makes such a scope impossible to request until a CLI update ships. The screen stays the authority — if it truly cannot render the scope it refuses the WHOLE authorization after the pairing session exists (the stranding the local check normally prevents), so use this only when you have reason to believe the web app is newer than this CLI. Scopes no login path can mint (payroll/admin:*) are still rejected locally; this flag does not touch them.",
+          "name": "allow-unrenderable-scopes",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "yes": {
           "char": "y",
           "description": "Skip the interactive confirmation and start the pairing immediately. Only a BARE invocation is ever prompted, so passing any flag already skips it; use this to say so explicitly. Automation that allocates a pty for stdin/stdout/stderr and runs the command bare is indistinguishable from a human — that is the case this flag exists for.",
@@ -246,10 +253,10 @@
     "logout": {
       "aliases": [],
       "args": {},
-      "description": "Clear cached credentials (session token + store keys) for a profile. By default, clears BOTH the OS keychain and plaintext file store. With --insecure-storage or ALLSCALE_INSECURE_STORAGE=1, clears only plaintext files and never probes the keychain; omit/unset that opt-in when a full-machine sweep is wanted. If the keychain is suppressed or unavailable, a bare logout fails closed after attempting the plaintext-file cleanup.",
+      "description": "Clear cached credentials (session token + store keys) for a profile. By default, clears BOTH the OS keychain and plaintext file store. With --insecure-storage or ALLSCALE_INSECURE_STORAGE=1, clears only plaintext files and never probes the keychain; omit/unset that opt-in when a full-machine sweep is wanted. If the keychain is suppressed or unavailable, a bare logout fails closed after attempting the plaintext-file cleanup. A bare interactive invocation asks for confirmation before anything is removed; any flag (or --yes) skips the prompt, and machine callers are never prompted.",
       "examples": [
-        "$ allscale logout",
-        "$ allscale logout --profile staging"
+        "$ allscale logout --profile staging",
+        "$ allscale logout --yes"
       ],
       "flags": {
         "json": {
@@ -291,6 +298,13 @@
           "name": "insecure-storage",
           "allowNo": false,
           "type": "boolean"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Skip the interactive confirmation and clear the credentials immediately. Only a BARE invocation is ever prompted, so passing any flag already skips it; use this to say so explicitly. Automation that allocates a pty for stdin/stdout/stderr and runs the command bare is indistinguishable from a human — that is the case this flag exists for.",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -407,12 +421,12 @@
     "otp-login": {
       "aliases": [],
       "args": {},
-      "description": "Terminal-only Email OTP login for headless / scripted shells. Works with any account email (external domains included; the account must already exist). Sends the code (unless --otp-id is supplied), reads it in the terminal, and mints a scope-ENFORCED agent API key — the only credential this CLI issues. Scopes are set with --scopes (required; no full-permission default exists).",
+      "description": "Terminal-only Email OTP login for headless / scripted shells. Works with any account email (external domains included; the account must already exist). Sends the code (unless --otp-id is supplied), reads it in the terminal, and mints a scoped agent API key whose granted scopes the backend checks on each request — the credential issued by the current CLI login flows. Scopes are set with --scopes (required; no full-permission default exists).",
       "examples": [
         "$ allscale otp-login --email me@example.com --scopes invoice:read_only  # interactive: prompts on stdin",
         "$ printf '%s' \"$OTP\" | allscale otp-login --email me@example.com --scopes invoice:all --otp-stdin",
         "$ ALLSCALE_OTP=$(read-from-mailbox) allscale otp-login --email me@example.com --scopes claim_link:all",
-        "$ allscale otp-login --email me@example.com --scopes invoice:read_only --otp-id <id> --otp <code>"
+        "$ allscale otp-login --email me@example.com --scopes invoice:read_only --otp-id otp-request-id --otp 123456"
       ],
       "flags": {
         "json": {
@@ -466,7 +480,7 @@
           "type": "option"
         },
         "scopes": {
-          "description": "Scopes the minted agent key should carry, repeatable. Scope strings use `<category>:<tier>`; `:all` implies `:read_only` for the same category. Pairs that reach a real operation today: invoice:{read_only,all}, contact:{read_only,all}, claim_link:{read_only,all}, transaction:read_only, store:all, wallet:read_only. Other pairs are accepted by the catalog but grant nothing, and this command does NOT warn when a requested scope is clipped — verify with `allscale scope` after minting. Required — the backend deliberately has no full-permission default. Requested scopes are clipped to your account's role; keys are ENFORCED server-side on every request.",
+          "description": "Scopes the minted agent key should carry, repeatable. Scope strings use `<category>:<tier>`; `:all` implies `:read_only` for the same category. Pairs that reach a real operation today: invoice:{read_only,all}, contact:{read_only,all}, claim_link:{read_only,all}, transaction:{read_only,all}, store:{read_only,all}, wallet:{read_only,all}. transaction:all — read-only in practice: no write operation is wired there today, so the `:read_only` tier grants exactly as much; prefer it unless you have a reason to hold the wider scope. `wallet:all` additionally lets the key register `wallet send` transfers; every transfer still requires your in-browser confirmation. Other pairs are accepted by the catalog but grant nothing, and this command does NOT warn when a requested scope is clipped — verify with `allscale scope` after minting. Values are checked locally first: an unrecognised `<category>:<tier>` string exits 2 before any OTP is sent — the same check, and the same exit code, as `device-login --scopes`. Required — the backend deliberately has no full-permission default. Requested scopes are clipped to your account's role; granted scopes are checked by the backend on each request.",
           "helpGroup": "REQUIRED",
           "name": "scopes",
           "required": true,
@@ -624,7 +638,7 @@
     "scope": {
       "aliases": [],
       "args": {},
-      "description": "Show the capabilities granted to the current CLI session (chosen on the browser approval screen at `device-login`, or via --scopes on `otp-login`). Scopes are ENFORCED server-side on every request. Read from the cached token bundle; no network call.",
+      "description": "Show the capabilities granted to the current CLI session (chosen on the browser approval screen at `device-login`, or via --scopes on `otp-login`). Scopes are checked by the backend on each request. Scope controls reduce access but do not prevent credential compromise, misuse within a granted scope, configuration errors, or unauthorized actions by an otherwise authenticated caller. Read from the cached token bundle; no network call.",
       "examples": [
         "$ allscale scope",
         "$ allscale scope --profile prod"
@@ -646,7 +660,7 @@
           "type": "option"
         },
         "token": {
-          "description": "Override the access token for this invocation (precedence: --token > ALLSCALE_TOKEN > --profile)",
+          "description": "Not supported by this command. `scope` reads scopes recorded with a stored profile, so an arbitrary token has no authoritative scope source and is rejected locally. Use --profile to select the stored credential whose scopes should be shown.",
           "helpGroup": "GLOBAL",
           "hidden": true,
           "name": "token",
@@ -694,7 +708,7 @@
     "whoami": {
       "aliases": [],
       "args": {},
-      "description": "Show the current authenticated identity from the stored credential (agent-key sessions report business_id / scopes / expiry; legacy password sessions decode the cached JWT). No network call.",
+      "description": "Show the current authenticated identity from the stored credential (agent-key sessions report business_id / scopes / expiry; legacy password sessions decode the cached JWT). No network call. The reported `api_base` is the endpoint this session resolves to — its saved profile pin, else this build's own environment. A published build ignores ALLSCALE_API_BASE, and says so on stderr rather than echoing it as the session endpoint; an internal build honours the variable, so it is echoed there. Either way, a resolved endpoint that networked commands would refuse — an untrusted origin, or a real AllScale environment outside this build's signing binding, whether it came from the variable or from the profile's saved pin — is disclosed on stderr. This command stays usable offline and never fails closed.",
       "examples": [
         "$ allscale whoami",
         "$ allscale whoami --profile prod"
@@ -764,10 +778,10 @@
     "claim-link:claim": {
       "aliases": [],
       "args": {},
-      "description": "Claim a Claim Link. Anonymous claims require --to; authenticated business receivers can use --to-wallet. Only an on-chain-proven claimed outcome exits 0.",
+      "description": "Claim a Claim Link. Path-A claims (no AllScale account sign-in) require --to; authenticated business receivers can use --to-wallet. Only an on-chain-proven claimed outcome exits 0.",
       "examples": [
-        "$ allscale claim-link claim --claim-token <token> --to 0xabc...",
-        "$ allscale claim-link claim --claim-url https://app.allscale.io/claim/<token> --to-wallet"
+        "$ allscale claim-link claim --claim-token claim-token-from-share-link --to 0x1234567890abcdef1234567890abcdef12345678",
+        "$ allscale claim-link claim --claim-url https://app.allscale.io/claim/claim-token-from-share-link --to-wallet"
       ],
       "flags": {
         "json": {
@@ -812,7 +826,7 @@
         },
         "claim-token": {
           "description": "Raw bearer claim token. Secret: prefer env/history-safe invocation.",
-          "helpGroup": "REQUIRED (ONE OF)",
+          "helpGroup": "REQUIRED SOURCE (ONE OF)",
           "name": "claim-token",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -820,18 +834,18 @@
         },
         "claim-url": {
           "description": "Canonical claim URL, or a same-origin /s/ short URL resolved with one unauthenticated 302.",
-          "helpGroup": "REQUIRED (ONE OF)",
+          "helpGroup": "REQUIRED SOURCE (ONE OF)",
           "name": "claim-url",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "to": {
-          "description": "Receiver EVM address for anonymous Path-A claims.",
+          "description": "Receiver EVM address for Path-A claims (no AllScale account sign-in). This does not make the transaction anonymous: network, request, compliance, and public blockchain data may still be processed or observable.",
           "exclusive": [
             "to-wallet"
           ],
-          "helpGroup": "REQUIRED (ONE OF)",
+          "helpGroup": "REQUIRED DESTINATION (ONE OF)",
           "name": "to",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -842,7 +856,7 @@
           "exclusive": [
             "to"
           ],
-          "helpGroup": "REQUIRED (ONE OF)",
+          "helpGroup": "REQUIRED DESTINATION (ONE OF)",
           "name": "to-wallet",
           "allowNo": false,
           "type": "boolean"
@@ -855,7 +869,7 @@
       "pluginName": "@allscale/cli",
       "pluginType": "core",
       "strict": true,
-      "usage": "claim-link claim (--claim-token <value> | --claim-url <value>) [--json] [--profile <value>] [--insecure-storage] [--to <value> | --to-wallet]",
+      "usage": "claim-link claim (--claim-token <value> | --claim-url <value>) [--json] [--profile <value>] [--insecure-storage] (--to <value> | --to-wallet)",
       "enableJsonFlag": true,
       "legacyStagingNoticeShown": false,
       "emitsOwnOutput": false,
@@ -997,7 +1011,7 @@
           "type": "option"
         },
         "bridge-timeout": {
-          "description": "Shorten the browser confirmation deadline, in milliseconds. By default the CLI waits for the broker op TTL.",
+          "description": "Shorten the browser confirmation deadline, in milliseconds. By default the CLI waits the broker op's remaining life. It can only shorten the wait — a value above that is clamped to it, because the confirmation link cannot outlive its broker op. If the server's response carries no timestamp to measure that life against, the CLI says so on stderr and bounds the wait instead: with no --bridge-timeout this receipt-aware flow waits up to 240s and may be shortened by the best-effort bound from the stated expiry; an explicit value is honoured up to that same bound (clamped to 60s-15min), or 15min when the expiry itself is unreadable.",
           "name": "bridge-timeout",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -1042,15 +1056,15 @@
       "aliases": [],
       "args": {
         "id": {
-          "description": "Claim Link id_str.",
+          "description": "Claim Link id.",
           "name": "id",
           "required": true
         }
       },
-      "description": "Fetch one of your own Claim Links by id. Unknown or non-owned ids are indistinguishable on the backend.",
+      "description": "Fetch one of your own Claim Links by id. Unknown or non-owned ids are indistinguishable on the backend. Requires claim_link:read_only for an agent-key session.",
       "examples": [
-        "$ allscale claim-link get 65ab1234567890abcdef0123",
-        "$ allscale claim-link get 65ab... --select 'id status amount token_symbol chain'"
+        "Fetch the first Claim Link you own (requires jq and at least one existing link):\n$ CLAIM_LINK_ID=\"$(\n    allscale claim-link list --input '{\"limit\":1}' |\n    jq -er '.data.items[0].id'\n  )\" &&\n    allscale claim-link get \"$CLAIM_LINK_ID\"",
+        "Fetch selected fields from the first Claim Link you own (requires jq and at least one existing link):\n$ CLAIM_LINK_ID=\"$(\n    allscale claim-link list --input '{\"limit\":1}' |\n    jq -er '.data.items[0].id'\n  )\" &&\n    allscale claim-link get \"$CLAIM_LINK_ID\" \\\n      --select 'id status amount token_symbol chain'"
       ],
       "flags": {
         "json": {
@@ -1132,7 +1146,7 @@
     "claim-link:list": {
       "aliases": [],
       "args": {},
-      "description": "List your own Claim Links newest first. Defaults to the first 50 rows; pass --input or --all to override.",
+      "description": "List your own Claim Links newest first. Defaults to the first 50 rows; pass --input or --all to override. Requires claim_link:read_only for an agent-key session.",
       "examples": [
         "$ allscale claim-link list",
         "$ allscale claim-link list --status link_sent --input '{\"limit\":20}'",
@@ -1180,7 +1194,7 @@
           "type": "boolean"
         },
         "status": {
-          "description": "Optional ClaimLinkStatus filter. Accepts 1..6 or pending_deposit/link_sent/claiming/claimed/expired/cancelled.",
+          "description": "Optional ClaimLinkStatus filter. Accepts an integer from 1 through 6 or pending_deposit/link_sent/claiming/claimed/expired/cancelled.",
           "name": "status",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -1242,136 +1256,13 @@
         "list.js"
       ]
     },
-    "claim-link:preview": {
-      "aliases": [],
-      "args": {},
-      "description": "Preview Claim Link fees without creating a link. Mirrors create_claim_link validation.",
-      "examples": [
-        "$ allscale claim-link preview --amount 10 --chain base --per-transfer-gas 0.02"
-      ],
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "profile": {
-          "description": "Named profile from ~/.allscale/config.toml",
-          "helpGroup": "GLOBAL",
-          "name": "profile",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "token": {
-          "description": "Override the access token for this invocation (precedence: --token > ALLSCALE_TOKEN > --profile)",
-          "helpGroup": "GLOBAL",
-          "hidden": true,
-          "name": "token",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-base": {
-          "description": "Override the API base URL (public builds accept only https://app.allscale.io)",
-          "helpGroup": "GLOBAL",
-          "hidden": true,
-          "name": "api-base",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "insecure-storage": {
-          "description": "Force POSIX plaintext token storage at ~/.allscale/credentials.json (mode 0600) instead of the OS keychain — for headless / CI / agent use. Unavailable on Windows because Node cannot verify owner-only ACL/link safety. Also via ALLSCALE_INSECURE_STORAGE=1.",
-          "helpGroup": "GLOBAL",
-          "name": "insecure-storage",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "amount": {
-          "description": "Receiver amount as a decimal string in token units; at most 6 effective decimals, or 18 on BSC.",
-          "helpGroup": "REQUIRED",
-          "name": "amount",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "chain": {
-          "description": "EVM chain for the claim link.",
-          "helpGroup": "REQUIRED",
-          "name": "chain",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "options": [
-            "ethereum",
-            "bsc",
-            "base",
-            "polygon",
-            "arbitrum",
-            "optimism"
-          ],
-          "type": "option"
-        },
-        "per-transfer-gas": {
-          "description": "One ERC-20 transfer's gas estimate in token units.",
-          "helpGroup": "REQUIRED",
-          "name": "per-transfer-gas",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "stable-coin": {
-          "description": "Stablecoin for the link.",
-          "name": "stable-coin",
-          "default": "USDT",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "options": [
-            "USDT",
-            "USDC"
-          ],
-          "type": "option"
-        },
-        "show-doc": {
-          "description": "Print the GraphQL document to stderr.",
-          "name": "show-doc",
-          "allowNo": false,
-          "type": "boolean"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "claim-link:preview",
-      "pluginAlias": "@allscale/cli",
-      "pluginName": "@allscale/cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": true,
-      "legacyStagingNoticeShown": false,
-      "emitsOwnOutput": false,
-      "requiresEscapeHatch": false,
-      "requiresInput": false,
-      "isLocalOnly": false,
-      "isESM": false,
-      "relativePath": [
-        "dist",
-        "commands",
-        "claim-link",
-        "preview.js"
-      ]
-    },
     "claim-link:status": {
       "aliases": [],
       "args": {},
       "description": "Read the public receiver-facing status snapshot for a Claim Link bearer token or URL.",
       "examples": [
-        "$ allscale claim-link status --claim-token <token>",
-        "$ allscale claim-link status --claim-url https://app.allscale.io/claim/<token>"
+        "$ allscale claim-link status --claim-token claim-token-from-share-link",
+        "$ allscale claim-link status --claim-url https://app.allscale.io/claim/claim-token-from-share-link"
       ],
       "flags": {
         "json": {
@@ -1457,7 +1348,7 @@
       "aliases": [],
       "args": {
         "id": {
-          "description": "Invoice id_str (the backend's Payment.id_str)",
+          "description": "Invoice id, as returned by `invoice send` and listed by `invoice list`",
           "name": "id",
           "required": true
         }
@@ -1465,7 +1356,7 @@
       "description": "Fetch one invoice by id. Wraps the `payment` GraphQL query.",
       "examples": [
         "$ allscale invoice get 65ab1234567890abcdef0123",
-        "$ allscale invoice get 65ab... --select 'id status amount currency'"
+        "$ allscale invoice get 65ab1234567890abcdef0123 --select 'id status amount_coins display_amount payment_type'"
       ],
       "flags": {
         "json": {
@@ -1550,10 +1441,10 @@
       "description": "List invoices for a business. Wraps the `payments` GraphQL query. Defaults to the first 50 rows; pass --input '{\"limit\":N,\"skip\":M}' to paginate, or --all to request one unpaginated response. Filter with --status / --payment-type (repeatable), the creation-date range --from / --to (half-open: --from inclusive, --to exclusive), and --to-email, which narrows this both-directions view to the invoices you ISSUED to that contact.",
       "examples": [
         "$ allscale invoice list",
-        "$ allscale invoice list --business-id <id>",
+        "$ allscale invoice list --business-id 65ab1234567890abcdef0123",
         "$ allscale invoice list --input '{\"limit\":50,\"skip\":50}'   # second page",
         "$ allscale invoice list --all                                 # everything (be careful)",
-        "$ allscale invoice list --input '{\"limit\":5}' --select 'count items { id status amount }'",
+        "$ allscale invoice list --payment-type USDT --input '{\"limit\":5}' --select 'count items { id status amount_coins }'",
         "$ allscale invoice list --status SENT --status OVERDUE      # unpaid work",
         "$ allscale invoice list --payment-type USDC                 # only USDC invoices",
         "$ allscale invoice list --from 2026-07-01 --to 2026-08-01   # exactly July (--to is exclusive)",
@@ -1602,7 +1493,7 @@
         },
         "business-id": {
           "char": "b",
-          "description": "Business id_str. Defaults to the logged-in user's business when omitted.",
+          "description": "Business id. Defaults to the logged-in user's business when omitted.",
           "name": "business-id",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -1703,15 +1594,15 @@
       "aliases": [],
       "args": {
         "id": {
-          "description": "Invoice id_str (the backend Payment.id_str) to pay.",
+          "description": "Invoice id to pay, as listed by `invoice sent`.",
           "name": "id",
           "required": true
         }
       },
-      "description": "Pay a received invoice from your AllScale wallet. Resolves the invoice's destination + amount, moves the funds via the same signing path as `wallet send` (confirmed in the browser at /cli), then reports and confirms the payment. Needs TWO scopes: `invoice:all` to create, report and confirm the pay intent, and `wallet:read_only` to look up the address you are paying FROM. Neither flow grants `invoice:all` for you: on `device-login` the Invoices toggle starts at Read, so tick its write tier on the approval screen; on `otp-login` pass BOTH --scopes invoice:all --scopes wallet:read_only, because naming any scope turns every unnamed category off.",
+      "description": "Pay an invoice where you are the payer, from your AllScale wallet. Use `allscale invoice sent` to list the invoices you owe (add --status SENT --status ACKNOWLEDGED --status FAILED for the ones you can start paying). An OVERDUE invoice cannot start a new payment: if an earlier attempt of yours may still be in flight, reconcile that first — otherwise ask the issuer to extend its due date, which revives it. Resolves the invoice's destination + amount, moves the funds via the same signing path as `wallet send` (the transfer is confirmed in the browser), then reports and confirms the payment. Needs TWO scopes: `invoice:all` to create, report and confirm the pay intent, and `wallet:all` to register the withdrawal — the same broker op `wallet send` uses (backend gates the op, not the verb); it also covers the payer-address lookup, since `:all` implies `:read_only`. Neither LOGIN flow grants either write tier for you: on `device-login` the Invoices toggle starts at Read and the Wallets Allow-changes tier starts OFF, so tick both on the approval screen; on `otp-login` pass BOTH --scopes invoice:all --scopes wallet:all, because naming any scope turns every unnamed category off.",
       "examples": [
         "$ allscale invoice pay 65ab1234567890abcdef0123",
-        "$ allscale invoice pay 65ab... --chain bsc --stable-coin USDT"
+        "$ allscale invoice pay 65ab1234567890abcdef0123 --chain bsc --stable-coin USDT"
       ],
       "flags": {
         "json": {
@@ -1755,6 +1646,7 @@
           "type": "boolean"
         },
         "business-id": {
+          "char": "b",
           "description": "Your own business id. Optional and redundant — payment always comes from the wallet of the business you are signed in as. Supplying a different business id is rejected rather than silently paying from your own wallet; omit the flag unless a script needs to assert which business it is acting as.",
           "name": "business-id",
           "hasDynamicHelp": false,
@@ -1788,60 +1680,15 @@
           "type": "option"
         },
         "browser-base": {
-          "description": "Override the base URL of the /cli confirmation link (defaults to the session API base). (Browser-bridge only — not valid with --headless.)",
-          "exclusive": [
-            "headless"
-          ],
+          "description": "Override the base URL of the /cli confirmation link (defaults to the session API base).",
           "name": "browser-base",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "bridge-timeout": {
-          "description": "Override the confirmation deadline in milliseconds (default 180000). (Browser-bridge only — not valid with --headless.)",
-          "exclusive": [
-            "headless"
-          ],
+          "description": "Shorten the confirmation deadline, in milliseconds. By default the CLI waits the broker op's remaining life (~5 min). The browser only returns after the on-chain receipt confirms (it may poll for up to ~2 min after signing), so a shortened deadline must budget for the signing ceremony PLUS that receipt wait. Capped by the broker op TTL: a larger value is clamped, because the confirmation link cannot outlive its broker op. If no usable server-relative TTL is available, a withdraw waits up to 240s and may be shortened by the best-effort bound from the stated expiry.",
           "name": "bridge-timeout",
-          "default": 180000,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "headless": {
-          "description": "Pay without a browser via Turnkey email-OTP (accounts with email-OTP enabled and no passkey; passkey accounts must use the browser flow). Supply the OTP via --otp-stdin (recommended for automation) or interactively; --otp / ALLSCALE_OTP work ONLY combined with --otp-id. This removes the in-browser human confirmation, so use it only on a trusted machine. Requires an existing legacy JWT session, which this build cannot create — use the browser-bridge flow instead.",
-          "name": "headless",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "otp": {
-          "dependsOn": [
-            "headless"
-          ],
-          "description": "Turnkey signing OTP code (with --headless). Only works combined with --otp-id (an externally-triggered flow): without --otp-id the CLI emails a FRESH code at run time, so any pre-set --otp / ALLSCALE_OTP value is stale and fails with 'Invalid or expired OTP code'. For automation prefer --otp-stdin (CLI emails; pipe the fresh code back). Passing --otp as a flag also exposes it in shell history AND the process list (ps / /proc/<pid>/cmdline).",
-          "exclusive": [
-            "otp-stdin"
-          ],
-          "name": "otp",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "otp-stdin": {
-          "dependsOn": [
-            "headless"
-          ],
-          "description": "Read the Turnkey signing OTP as one line from stdin (with --headless).",
-          "name": "otp-stdin",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "otp-id": {
-          "dependsOn": [
-            "headless"
-          ],
-          "description": "Skip the OTP-send step and reuse a prior Turnkey otpId (with --headless). The OTP code itself is still required via --otp / ALLSCALE_OTP / --otp-stdin.",
-          "name": "otp-id",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -1874,7 +1721,7 @@
       "description": "List invoices you are the PAYEE on — where the money is owed to your business. Wraps `recipient_payments` (the backend's `recipient` is the payee). This INCLUDES every invoice you issued with `invoice send`. Defaults to the first 50 rows; pass --input or --all to override. Filter with --status / --payment-type (repeatable), the creation-date range --from / --to (half-open: --from inclusive, --to exclusive), and --to-email to narrow to the invoices you billed to one contact.",
       "examples": [
         "$ allscale invoice received",
-        "$ allscale invoice received --business-id <id> --input '{\"limit\":10}'",
+        "$ allscale invoice received --business-id 65ab1234567890abcdef0123 --input '{\"limit\":10}'",
         "$ allscale invoice received --all",
         "$ allscale invoice received --status SENT --status OVERDUE",
         "$ allscale invoice received --from 2026-07-01 --to 2026-08-01",
@@ -1923,7 +1770,7 @@
         },
         "business-id": {
           "char": "b",
-          "description": "Business id_str. Defaults to the logged-in user's business when omitted.",
+          "description": "Business id. Defaults to the logged-in user's business when omitted.",
           "name": "business-id",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -2023,15 +1870,15 @@
     "invoice:send": {
       "aliases": [],
       "args": {},
-      "description": "Send an invoice by email. Resolves the contact, selects receiving wallets, renders a minimal HTML invoice, and submits create_payment through the authenticated session. No browser ceremony — the payer signs when they pay, not when you issue. Returns a fixed summary (payment_id, contact, amount, wallet count) rather than a GraphQL selection, which is why there is no --select here; read the created invoice back with `invoice get <payment_id> --select ...`. Note the direction: an invoice you send lists YOU as the payee, so it appears under `invoice received`, not `invoice sent`.",
+      "description": "Send an invoice by email. Resolves the contact, selects receiving wallets, renders a minimal HTML invoice, and submits create_payment through the authenticated session. No browser ceremony — the payer signs when they pay, not when you issue. Returns a fixed summary (payment_id, contact, amount, wallet count) rather than a GraphQL selection, which is why there is no --select here; read the created invoice back with `invoice get \"$PAYMENT_ID\" --select 'id status amount_coins display_amount payment_type'`, using the payment_id returned by this command. The follow-up reflects the default USDT path; display_amount remains the denomination-aware value. Note the direction: an invoice you send lists YOU as the payee, so it appears under `invoice received`, not `invoice sent`.",
       "examples": [
         "$ allscale invoice send --to-email client@example.com --amount 1.00",
-        "$ allscale invoice send --to-email client@example.com --amount 250 --payment-type 2 --currency-label USDC --memo \"January retainer\" --due 2026-06-01",
+        "$ allscale invoice send --to-email client@example.com --amount 250 --payment-type 2 --currency-label USDC --memo \"January retainer\" --due \"$(node -p 'new Date(Date.now()+30*864e5).toISOString().slice(0,10)')\"",
         "$ allscale invoice send --to-contact-id 695da2cd3b9598f5edcdcb56 --amount 50 --line \"Design|1|30.00\" --line \"Copy|1|20.00\"",
         "$ allscale invoice send --to-email client@example.com --amount 75 --line \"Consulting retainer\"",
         "$ allscale invoice send --to-email client@example.com --amount 350 --line \"Discovery (4h)|4|25.00\" --line \"Implementation (10h)|10|25.00\"",
         "$ allscale invoice send --to-email client@example.com --line \"Discovery (4h)|4|25.00\" --line \"Implementation (10h)|10|25.00\"",
-        "$ allscale invoice send --to-email client@example.com --amount 100 --wallet-id 66ac....",
+        "$ allscale invoice send --to-email client@example.com --amount 100 --wallet-id 66ac1234567890abcdef0123",
         "$ allscale invoice send --to-email newclient@example.com --amount 100 --auto-create-contact",
         "$ allscale invoice send --to-email billing@acme.com --amount 100 --auto-create-contact --contact-name \"Acme Inc\""
       ],
@@ -2088,7 +1935,7 @@
           "type": "option"
         },
         "to-contact-id": {
-          "description": "Contact id_str directly (skip the email lookup). Mutually exclusive with --to-email.",
+          "description": "Contact id directly (skip the email lookup). Mutually exclusive with --to-email.",
           "exclusive": [
             "to-email"
           ],
@@ -2099,7 +1946,7 @@
           "type": "option"
         },
         "amount": {
-          "description": "Decimal amount in coin units (e.g. \"1.00\" for one USDT; minimum 0.10 for USDT/USDC). Optional when every --line is the three-field \"<description>|<quantity>|<amount>\" form — in that case the CLI sums the lines to derive the invoice total. Required otherwise.",
+          "description": "Exact decimal amount: USDT/USDC accept up to 6 effective decimal places (minimum 0.10), while fiat accepts up to 2. Redundant trailing zeroes are allowed and canonicalized; the CLI never rounds or truncates. Optional when every --line is the three-field \"<description>|<quantity>|<amount>\" form — in that case the CLI sums the lines to derive the invoice total. Required otherwise.",
           "helpGroup": "CONDITIONAL",
           "name": "amount",
           "hasDynamicHelp": false,
@@ -2116,7 +1963,7 @@
           "type": "boolean"
         },
         "contact-name": {
-          "description": "Display name to use when --auto-create-contact creates a new contact. Optional — defaults to the full email address (unique enough to avoid the BE's per-business name-uniqueness collision). Has no effect when the contact already exists or when --auto-create-contact is not set.",
+          "description": "Display name to use when --auto-create-contact creates a new contact. Optional — defaults to the full email address (unique enough to avoid a per-business name collision). Has no effect when the contact already exists or when --auto-create-contact is not set.",
           "exclusive": [
             "to-contact-id"
           ],
@@ -2126,15 +1973,14 @@
           "type": "option"
         },
         "currency-label": {
-          "description": "Label shown next to the amount in the rendered invoice (e.g. USDT, USDC). Display only; select the stablecoin with --payment-type=1 (USDT) or --payment-type=2 (USDC). --currency-int applies only to --payment-type=0 fiat invoices. Default: USDT.",
+          "description": "Label shown after each amount in the rendered invoice (e.g. \"250.00 USDT\"). Display only — it changes no amount, no asset, and nothing the payer is charged. Which stablecoins the invoice ACCEPTS is decided by --payment-type when you pass it explicitly (=1 USDT, =2 USDC); omit that flag and the invoice accepts whatever your business is configured for. Defaults to the label matching --payment-type (USDT or USDC; USD for --payment-type=0 fiat — pass this flag explicitly for a non-USD --currency-int).",
           "name": "currency-label",
-          "default": "USDT",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "currency-int": {
-          "description": "Backend Currency enum value (USD=1, AED=2, ...). Only sent when --payment-type=0 (CURRENCY/fiat invoice); ignored for stablecoin payment types. Default: 1 (USD).",
+          "description": "Fiat currency code, such as USD=1 or AED=2. Only sent when --payment-type=0 (fiat invoice); ignored for stablecoin payment types. Default: 1 (USD).",
           "name": "currency-int",
           "default": 1,
           "hasDynamicHelp": false,
@@ -2142,7 +1988,7 @@
           "type": "option"
         },
         "payment-type": {
-          "description": "CreatePaymentInput.payment_type. Run `allscale describe create_payment` for the enum. Default: 1.",
+          "description": "What the invoice is denominated in AND which stablecoin it may be paid with: 0 = fiat (pair with --currency-int), 1 = USDT, 2 = USDC. Passing 1 or 2 EXPLICITLY pins the invoice to that coin — a payment arriving in the other stablecoin is rejected, and the payer's email names only this coin. Omit the flag and the invoice accepts whichever stablecoins your business is configured for (it is still denominated in USDT, the default). For 0 the amount is fiat but settlement is still in a stablecoin, so the payer may likewise use any coin your business accepts. Any other value is rejected locally (exit 2) — the backend would otherwise issue an invoice in an undocumented asset. Default: 1 (denomination only — omitting the flag pins nothing).",
           "name": "payment-type",
           "default": 1,
           "hasDynamicHelp": false,
@@ -2150,14 +1996,14 @@
           "type": "option"
         },
         "memo": {
-          "description": "Free-form invoice memo / description shown to the payer.",
+          "description": "Free-form invoice memo / description shown to the payer. When omitted, defaults to the same note the web invoice editor generates: \"Thank you for your business! Payment is due within N days.\" with N derived from the due date (30 unless --due says otherwise).",
           "name": "memo",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "due": {
-          "description": "Invoice due date / datetime (ISO 8601), e.g. 2026-06-01, 2026-06-01T09:30:00, 2026-06-01T09:30:00Z, or 2026-06-01T09:30:00+08:00. A value without a UTC offset is read as UTC (so 2026-06-01 means 2026-06-01T00:00:00Z) — stated explicitly because interpreting it in the local timezone would make the same command mean different things on different machines. Rendered in the HTML body exactly as you typed it.",
+          "description": "Invoice due date / datetime (ISO 8601), e.g. YYYY-MM-DD, YYYY-MM-DDTHH:mm:ss, YYYY-MM-DDTHH:mm:ssZ, or YYYY-MM-DDTHH:mm:ss+08:00. A value without a UTC offset is read as UTC (so a date-only value means midnight UTC) — stated explicitly because interpreting it in the local timezone would make the same command mean different things on different machines. When omitted, defaults to 30 days from now, matching the web invoice editor. The rendered document shows the NORMALIZED date in the web's display format (\"MMM DD, YYYY\"), not the raw flag text. The examples compute the date with POSIX command substitution, which sh/bash/zsh and PowerShell expand but cmd.exe does not; on cmd.exe pass an explicit date instead.",
           "name": "due",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -2171,21 +2017,22 @@
           "type": "option"
         },
         "line": {
-          "description": "Line item on the rendered invoice. Repeatable. Two forms: \"<description>\" (qty=1, amount=full --amount) or \"<description>|<quantity>|<amount>\" (all explicit; same decimal units as --amount). Use the three-field form for more than one line: the single-field form gives EVERY line the full --amount, so two such lines sum to twice --amount and trigger the totals-mismatch warning. With three-field lines you may omit --amount entirely and the CLI sums them. The backend charges --amount regardless; --line only shapes the rendered HTML.",
+          "description": "Line item on the rendered invoice. Repeatable. Two forms: \"<description>\" (qty=1, amount=full --amount) or \"<description>|<quantity>|<amount>\" (all explicit; same exact decimal precision as --amount). Use the three-field form for more than one line: the single-field form gives EVERY line the full --amount, so two such lines sum to twice --amount and trigger the totals-mismatch warning. With three-field lines you may omit --amount entirely and the CLI sums them. Every line total (quantity x amount) must fit the selected denomination's precision, whether or not --amount is given; the CLI never rounds it.",
           "name": "line",
           "hasDynamicHelp": false,
           "multiple": true,
           "type": "option"
         },
         "wallet-id": {
-          "description": "id_str of a wallet to receive payment. Repeatable. When given, the backend resolves and validates the ids (no wallet read needed — works with an invoice-scope-only agent key). When omitted, the CLI fetches your wallets via the narrow `business_wallets` query, which requires the wallet:read_only scope on an agent key.",
+          "description": "id of a wallet to receive payment, as listed by `wallet list`. Repeatable. When given, the backend resolves and validates the ids (no wallet read needed — works with an invoice-scope-only agent key). When omitted, the CLI fetches your wallets via the narrow `business_wallets` query, which requires the wallet:read_only scope on an agent key.",
           "name": "wallet-id",
           "hasDynamicHelp": false,
           "multiple": true,
           "type": "option"
         },
         "business-id": {
-          "description": "Your own business id_str. Optional and redundant — the invoice is always issued as the business you are signed in as, and contacts and wallets always resolve against it. Supplying a different business id is rejected rather than silently ignored; omit the flag unless a script needs to assert which business it is acting as.",
+          "char": "b",
+          "description": "Your own business id. Optional and redundant — the invoice is always issued as the business you are signed in as, and contacts and wallets always resolve against it. Supplying a different business id is rejected rather than silently ignored; omit the flag unless a script needs to assert which business it is acting as.",
           "name": "business-id",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -2225,7 +2072,7 @@
       "description": "List invoices you are the PAYER on — where your business owes the money. Wraps `sender_payments` (the backend's `sender` is the payer). NOTE: invoices you issued with `invoice send` are NOT here — you are the payee on those, so they appear under `invoice received`. Defaults to the first 50 rows; pass --input or --all to override. Filter with --status / --payment-type (repeatable) and the creation-date range --from / --to, which is half-open: --from is inclusive, --to exclusive. There is no --to-email here: an invoice's contact record belongs to the business that issued it, so filtering the invoices you OWE by your own contacts is not possible — use `invoice received --to-email`.",
       "examples": [
         "$ allscale invoice sent",
-        "$ allscale invoice sent --business-id <id> --input '{\"limit\":10}'",
+        "$ allscale invoice sent --business-id 65ab1234567890abcdef0123 --input '{\"limit\":10}'",
         "$ allscale invoice sent --all",
         "$ allscale invoice sent --status SENT --status OVERDUE",
         "$ allscale invoice sent --from 2026-07-01 --to 2026-08-01"
@@ -2273,7 +2120,7 @@
         },
         "business-id": {
           "char": "b",
-          "description": "Business id_str. Defaults to the logged-in user's business when omitted.",
+          "description": "Business id. Defaults to the logged-in user's business when omitted.",
           "name": "business-id",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -2375,16 +2222,15 @@
       "aliases": [],
       "args": {
         "id": {
-          "description": "Invoice id_str (the backend's Payment.id_str)",
+          "description": "Invoice id, as returned by `invoice send` and listed by `invoice list`",
           "name": "id",
           "required": true
         }
       },
-      "description": "Update an existing invoice's memo, payer, or (for an overdue invoice) its due date. Only those three fields can be changed; anything else is rejected by the backend.",
+      "description": "Update an existing invoice's memo or (for an overdue invoice) its due date. Although sender_business_id exists in the GraphQL input type, the backend rejects attempts to change it; do not send that field.",
       "examples": [
-        "$ allscale invoice update 65ab... --input '{\"memo\":\"corrected memo\"}'",
-        "$ allscale invoice update 65ab... --input '{\"due_datetime\":\"2026-12-31T00:00:00Z\"}'",
-        "$ allscale invoice update 65ab... --input '{\"sender_business_id\":\"6a288fb5f9b4689d8b09a50a\"}'"
+        "$ allscale invoice update 65ab1234567890abcdef0123 --input '{\"memo\":\"corrected memo\"}'",
+        "OVERDUE only: due_datetime may move FORWARD only (example: 30 days out):\n$ DUE=\"$(node -p 'new Date(Date.now()+30*864e5).toISOString()')\"\n$ allscale invoice update 65ab1234567890abcdef0123 -i \"{\\\"due_datetime\\\":\\\"$DUE\\\"}\""
       ],
       "flags": {
         "json": {
@@ -2429,7 +2275,7 @@
         },
         "input": {
           "char": "i",
-          "description": "JSON object of fields to change. Exactly three are accepted: \"memo\" (free text), \"sender_business_id\" (the payer's business id), and \"due_datetime\" (ISO 8601, e.g. 2026-12-31 or 2026-12-31T00:00:00Z — a value without a UTC offset is read as UTC, exactly as `invoice send --due` does). Note that due_datetime only applies to an OVERDUE invoice and may only move FORWARD; extending past now also revives the invoice so buyers can pay again. Any other field is rejected by the backend.",
+          "description": "JSON object of fields to change. Use \"memo\" (free text) or \"due_datetime\" (ISO 8601, e.g. YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ — a value without a UTC offset is read as UTC, exactly as `invoice send --due` does). The GraphQL input also exposes \"sender_business_id\", but the backend rejects attempts to change it; do not send that field. Note that due_datetime only applies to an OVERDUE invoice and may only move FORWARD; extending past now also revives the invoice so buyers can pay again. Any other field is rejected by the backend. The example computes the value with POSIX command substitution, which sh/bash/zsh and PowerShell expand but cmd.exe does not; on cmd.exe pass an explicit ISO value.",
           "helpGroup": "REQUIRED",
           "name": "input",
           "required": true,
@@ -2478,8 +2324,8 @@
       "args": {},
       "description": "Create and auto-fund a claim link from this store's enabled auto-payout wallet. Authenticates with the store API key/secret (NOT your login), so it needs a store that has completed Payout onboarding. Idempotent on --reference-id.",
       "examples": [
-        "$ ALLSCALE_STORE_API_SECRET=… allscale payout send --api-key ak_… --amount 10 --chain base --reference-id order-1042",
-        "$ allscale payout send --payout-api-base https://openapi.allscale.io --api-key ak_… --api-secret … --amount 25 --stable-coin USDC --chain polygon --reference-id inv-77 --receiver-email client@example.com"
+        "$ ALLSCALE_STORE_API_SECRET=your_store_api_secret allscale payout send --api-key ak_your_api_key --amount 10 --chain base --reference-id order-1042",
+        "$ allscale payout send --payout-api-base https://openapi.allscale.io --api-key ak_your_api_key --api-secret your_store_api_secret --amount 25 --stable-coin USDC --chain polygon --reference-id inv-77 --receiver-email client@example.com"
       ],
       "flags": {
         "json": {
@@ -2721,11 +2567,11 @@
     "store:create": {
       "aliases": [],
       "args": {},
-      "description": "Create a store for the logged-in business. Returns the API key and one-time API secret in stdout; capture the result securely. Business must have checkout enabled; only one sandbox store is allowed per business.",
+      "description": "Create a store for the logged-in business. Returns the API key and an API secret that is shown only once (it cannot be retrieved later — capture it now). The secret itself stays valid for use — it just cannot be displayed again. Business must have checkout enabled; only one sandbox store is allowed per business.",
       "examples": [
         "$ allscale store create --name \"My Shop\"",
         "$ allscale store create --name \"Live Shop\" --live",
-        "$ allscale store create --name \"Acme\" --business-id 665f0c..."
+        "$ allscale store create --name \"Acme\" --business-id 665f0c1234567890abcdef12"
       ],
       "flags": {
         "json": {
@@ -2778,6 +2624,7 @@
           "type": "option"
         },
         "business-id": {
+          "char": "b",
           "description": "Owning business id. Defaults to the logged-in business (decoded from the session token). Admins creating for another business must pass this.",
           "name": "business-id",
           "hasDynamicHelp": false,
@@ -2791,7 +2638,7 @@
           "type": "boolean"
         },
         "type": {
-          "description": "Store type (backend StoreType int). Omit for the default.",
+          "description": "Store type. 1 = checkout (the default). Payout credential stores are provisioned by Payout onboarding, not by this command. Omit for checkout.",
           "name": "type",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -2830,7 +2677,7 @@
       "aliases": [],
       "args": {
         "id": {
-          "description": "Transaction id_str",
+          "description": "Transaction id",
           "name": "id",
           "required": true
         }
@@ -2838,7 +2685,7 @@
       "description": "Fetch one transaction by id. Wraps the `transaction` query.",
       "examples": [
         "$ allscale transaction get 65ab1234567890abcdef0123",
-        "$ allscale transaction get 65ab... --select 'id status type direction'"
+        "$ allscale transaction get 65ab1234567890abcdef0123 --select 'id status transaction_type direction'"
       ],
       "flags": {
         "json": {
@@ -2920,11 +2767,15 @@
     "transaction:list": {
       "aliases": [],
       "args": {},
-      "description": "List transactions. --scope picks between mine (default; backend my_transactions), business (business_transaction_records), or activities. All scopes default to the first 50 rows; pass --input or --all to override.",
+      "description": "List transactions. --scope picks between mine (default; backend my_transactions), business (business_transaction_records), or activities. All scopes default to the first 50 rows; pass --input or --all to override. Filter by time with --from / --to (all scopes; half-open: --from inclusive, --to exclusive), and with --direction / --transaction-type / --status under --scope business.",
       "examples": [
         "$ allscale transaction list",
+        "$ allscale transaction list --from 2026-07-01 --to 2026-08-01   # exactly July (--to is exclusive)",
+        "$ allscale transaction list --scope business --direction INFLOW --status SUCCESS",
+        "$ allscale transaction list --scope business --transaction-type CLAIM_LINK",
         "$ allscale transaction list --scope business --input '{\"limit\":20}'",
         "$ allscale transaction list --scope activities --skip 0 --limit 25",
+        "$ allscale transaction list --scope activities --from 2026-07-01",
         "$ allscale transaction list --scope activities --all"
       ],
       "flags": {
@@ -3009,12 +2860,50 @@
           "type": "option"
         },
         "limit": {
-          "description": "Pagination limit (activities scope only). Defaults to 50; --all requests one unpaginated response.",
+          "description": "Positive pagination limit (activities scope only). Defaults to 50; --all requests one unpaginated response.",
+          "exclusive": [
+            "all"
+          ],
           "name": "limit",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
+        "from": {
+          "description": "Only transactions at or after this time. INCLUSIVE. Filters created_at under --scope mine/business and transaction_time under --scope activities. Accepts a date (2026-08-05), a naive datetime (2026-08-05T12:30:00, read as UTC), or an offset datetime (2026-08-05T20:30:00+08:00); the CLI converts to UTC and pads it to the backend's required YYYY-MM-DDTHH:MM:SS.ffffffZ.",
+          "name": "from",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "to": {
+          "description": "Only transactions strictly before this time. EXCLUSIVE — --from 2026-07-01 --to 2026-08-01 is exactly July and consecutive ranges never overlap. Filters created_at under --scope mine/business and transaction_time under --scope activities. Accepts a date (2026-08-05), a naive datetime (2026-08-05T12:30:00, read as UTC), or an offset datetime (2026-08-05T20:30:00+08:00); the CLI converts to UTC and pads it to the backend's required YYYY-MM-DDTHH:MM:SS.ffffffZ.",
+          "name": "to",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "direction": {
+          "description": "Only transactions in this direction (--scope business only). Accepted: INFLOW, OUTFLOW (case-insensitive), or a raw integer (1=INFLOW, -1=OUTFLOW).",
+          "name": "direction",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "transaction-type": {
+          "description": "Only transactions of this type (--scope business only). Accepted: PAYMENT, REWARD, WITHDRAWAL, SERVICE_FEE, CHECKOUT_INTENT_EPHEMERAL, CHECKOUT_INTENT, ON_CHAIN_TX, CHECKOUT_INTENT_EPHEMERAL_REFUND, CHECKOUT_INTENT_SERVICE_FEE, CHECKOUT_INTENT_EPHEMERAL_NET_INCOME, CLAIM_LINK (case-insensitive), or a raw integer.",
+          "name": "transaction-type",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "status": {
+          "description": "Only transactions in this status (--scope business only). Accepted: NEW, SUCCESS, FAILED, CONFIRMING (case-insensitive), or a raw integer. These are transaction statuses, not invoice statuses.",
+          "name": "status",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "select": {
           "char": "s",
           "description": "Override the default selection set with a GraphQL fragment. Default (--scope mine, --scope business): 'count items { created_at updated_at id owner_type owner_business_id owner_employee_id transaction_type direction reference_type payment_id counterparty_business_id counterparty_employee_id counterparty_name payment_type currency amount_cents amount_coins status memo transaction_time tx_hash tx_block_chain tx_from tx_to tx_block_number total_fee network_fee service_fee }'. Default (--scope activities): 'count items { transaction_id amount_coins amount_cents transaction_time created_at transaction_status payment_id transaction_type direction wallet_address tx_hash tx_block_chain tx_block_number memo payment_type currency total_fee network_fee service_fee counterparty_business_id claim_link_id }'. Pass --show-doc to print the exact GraphQL document that gets sent.",
@@ -3139,13 +3028,12 @@
     "wallet:send": {
       "aliases": [],
       "args": {},
-      "description": "Withdraw a stablecoin from your AllScale wallet to an EVM address. Confirms in the browser by default; the CLI prints the transaction hash and explorer URL when the network accepts the transfer. Accounts with Turnkey email-OTP enabled and no passkey can sign without a browser via --headless. Requires an existing legacy JWT session, which this build cannot create — use the browser-bridge flow instead.",
+      "description": "Withdraw a stablecoin from your AllScale wallet to an EVM address. The transfer is confirmed in the browser; the CLI prints the transaction hash and explorer URL only after its on-chain receipt confirms. Needs `wallet:all` on an agent key: it registers the withdrawal op (`wallet:read_only` alone cannot). Every transfer still requires your in-browser confirmation.",
       "examples": [
-        "$ allscale wallet send --idempotency-key order-1042 --to 0xabc... --amount 100 --chain ethereum",
-        "$ allscale wallet send --idempotency-key order-1043 --to 0xabc... --amount 50 --chain polygon --stable-coin USDC",
-        "$ allscale wallet send --idempotency-key order-1044 --to 0xabc... --amount 1 --chain base --bridge-timeout 300000",
-        "$ allscale wallet send --idempotency-key order-1045 --to 0xabc... --amount 1 --chain bsc  # over SSH: open the printed URL on any device, paste the tx hash back",
-        "$ allscale wallet send --to 0xabc... --amount 1 --chain base --headless --otp-stdin --idempotency-key order-1042  # reuse the same key only when retrying this operation"
+        "$ allscale wallet send --idempotency-key order-1042 --to 0x1234567890abcdef1234567890abcdef12345678 --amount 100 --chain ethereum",
+        "$ allscale wallet send --idempotency-key order-1043 --to 0x1234567890abcdef1234567890abcdef12345678 --amount 50 --chain polygon --stable-coin USDC",
+        "$ allscale wallet send --idempotency-key order-1044 --to 0x1234567890abcdef1234567890abcdef12345678 --amount 1 --chain base --bridge-timeout 240000",
+        "$ allscale wallet send --idempotency-key order-1045 --to 0x1234567890abcdef1234567890abcdef12345678 --amount 1 --chain bsc  # over SSH: open the printed URL on any device, paste the full result JSON back"
       ],
       "flags": {
         "json": {
@@ -3189,7 +3077,7 @@
           "type": "boolean"
         },
         "to": {
-          "description": "Recipient EVM address (0x… 40-hex).",
+          "description": "Recipient EVM address (0x followed by 40 hex characters).",
           "helpGroup": "REQUIRED",
           "name": "to",
           "required": true,
@@ -3245,62 +3133,18 @@
           "type": "option"
         },
         "bridge-timeout": {
-          "description": "Shorten the confirmation deadline, in milliseconds. By default the CLI waits the full broker op TTL (~5 min, shared by the loopback and paste channels); pass this to abort sooner. (Browser-bridge only — not valid with --headless.)",
-          "exclusive": [
-            "headless"
-          ],
+          "description": "Shorten the confirmation deadline, in milliseconds. By default the CLI waits the broker op's remaining life (~5 min, shared by the loopback and paste channels); pass this to abort sooner. The browser only returns after the on-chain receipt confirms (it may poll for up to ~2 min after signing), so a shortened deadline must budget for the signing ceremony PLUS that receipt wait. It can only shorten the wait — a value above the op's remaining life is clamped to it, because the confirmation link cannot outlive its broker op. If the server's response carries no timestamp to measure that life against, the CLI says so on stderr and bounds the wait instead: with no --bridge-timeout a withdraw waits up to 240s (budgeting the signing ceremony plus the receipt wait) and may be shortened by the best-effort bound from the stated expiry; an explicit value is honoured up to that same bound (clamped to 60s-15min), or 15min when the expiry itself is unreadable.",
           "name": "bridge-timeout",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "browser-base": {
-          "description": "Override the base URL of the printed /cli confirmation link (defaults to the session API base). (Browser-bridge only — not valid with --headless.)",
-          "exclusive": [
-            "headless"
-          ],
+          "description": "Override the base URL of the printed /cli confirmation link (defaults to the session API base). Accepts only the trusted AllScale origin; invalid values report the allowed origin.",
           "name": "browser-base",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "headless": {
-          "description": "Sign without a browser via Turnkey email-OTP (accounts with email-OTP enabled and no passkey; passkey accounts must use the browser flow). Supply the OTP via --otp-stdin (recommended for automation) or interactively; --otp / ALLSCALE_OTP work ONLY combined with --otp-id. This removes the in-browser human confirmation, so use it only on a trusted machine. Requires an existing legacy JWT session, which this build cannot create — use the browser-bridge flow instead.",
-          "name": "headless",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "otp": {
-          "dependsOn": [
-            "headless"
-          ],
-          "description": "Turnkey signing OTP code (with --headless). Only works combined with --otp-id (an externally-triggered flow): without --otp-id the CLI emails a FRESH code at run time, so any pre-set --otp / ALLSCALE_OTP value is stale and fails with 'Invalid or expired OTP code'. For automation prefer --otp-stdin (CLI emails; pipe the fresh code back). Passing --otp as a flag also exposes it in shell history AND the process list (ps / /proc/<pid>/cmdline).",
-          "exclusive": [
-            "otp-stdin"
-          ],
-          "name": "otp",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "otp-stdin": {
-          "dependsOn": [
-            "headless"
-          ],
-          "description": "Read the Turnkey signing OTP as one line from stdin (with --headless).",
-          "name": "otp-stdin",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "otp-id": {
-          "dependsOn": [
-            "headless"
-          ],
-          "description": "Skip the OTP-send step and reuse a prior Turnkey otpId (with --headless). The OTP code itself is still required via --otp / ALLSCALE_OTP / --otp-stdin.",
-          "name": "otp-id",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -3325,5 +3169,5 @@
       ]
     }
   },
-  "version": "0.1.0"
+  "version": "1.0.2"
 }