@capxul/cli 4.20.0-beta.24 → 4.20.0-beta.27

package/README.md

@@ -10,9 +10,9 @@ capxul --help
 capxul --version
 capxul --completions bash
 capxul doctor --json
-capxul telemetry status --json
-capxul telemetry disable --json
-capxul telemetry enable --json
+capxul config telemetry status --json
+capxul config telemetry off --json
+capxul config telemetry on --json
 capxul doctor --online --timeout-ms 30000 --json
 ```
 
@@ -24,6 +24,49 @@ machinery and collection controls send no observation records.
 check uses the public Capxul SDK and verifies the backend response nonce.
 It does not authenticate a person or submit a transaction.
 
+## Agent plugin
+
+[`plugin/`](plugin/README.md) is the Claude Code plugin: one `capxul` skill that
+makes an agent act as the person's Capxul through this CLI, with journeys as
+references, local memory under `~/.capxul/`, and the paste-a-prompt. The
+marketplace entry is the repository root `.claude-plugin/marketplace.json`.
+
+## Command schema
+
+```sh
+capxul schema
+capxul schema payment send
+capxul schema org payroll
+```
+
+`capxul schema` prints every command as JSON: its name, what it does and whether
+it moves money, with the global flags and what each exit code means.
+`capxul schema <command…>` prints one command: usage, arguments, flags, global
+flags and examples, read from the command's own definition (Effect's help
+document, so `--help` and the schema always agree), plus `movesMoney`, `output`
+(what `data` is) and `errors` (the codes it can answer with). A group lists its
+commands. Agents look commands up here instead of copying flags.
+
+## Home screen
+
+```sh
+capxul
+capxul --json
+capxul --org acme
+```
+
+Bare `capxul` is the home screen. It prints where you are at once, from this
+machine: who you are, who you act as and the Safe. Then one backend read
+(`accounts.summaries.home`) returns your balances (or the Organization
+treasury) and what needs you, each with the command that resolves it (requests
+to pay, payroll runs to approve, payments to retry), and it shows a few
+commands to try. A backend without that read gets the separate reads instead.
+A read that fails shows its section as unavailable, never as empty. Signed out,
+it prints `Not signed in · capxul auth login` without a network call. `--json`
+returns the same as data: `where`, `signedIn`, `balances` (the asset
+positions), `needsYou` (each with `next.argv`) and `try`. `capxul --help` is
+the command list.
+
 ## Where you are
 
 ```sh
@@ -52,7 +95,7 @@ Red is only used for errors. JSON output has no header.
 The environment comes from `--env <name>`, then `CAPXUL_ENV`, then
 `CAPXUL_BOOTSTRAP_URL`, then the environment `use env` saved, then staging. The
 names are `staging` and `devnet`; production is not available in this CLI yet.
-The devnet needs `CAPXUL_PUBLISHABLE_KEY` from its `browser.env`.
+The devnet uses its fixed test key, so it needs no `CAPXUL_PUBLISHABLE_KEY`.
 
 `use org <handle>` finds the Organization among those you belong to and saves
 it for this environment. It grants no authority; the backend checks every
@@ -72,7 +115,7 @@ a time:
 ```sh
 capxul org permission change
 capxul org member invite
-capxul org payment get
+capxul payment get
 capxul document get
 ```
 
@@ -93,74 +136,80 @@ one final version 1 result on stdout. Account setup reports public signer states
 Activity shows that the CLI is waiting. It does not prove settlement or a healthy
 connection. A deadline stops observation; it does not cancel a submitted operation.
 
-## Status overview
+## Sending money through the approval page
 
 ```sh
-capxul status
-capxul status --email EMAIL --json
-capxul status --org ORGANIZATION_ID
+capxul payment send rex@example.com 50
+capxul payment send @rex 12.5 --asset USDT
+capxul payment send 0x91f2…aa10 40
+capxul payment send rex@example.com 50 --json
+capxul payment send rex@example.com 50 --org acme [--budget BUDGET_ID]
+capxul payment send --input payment.json [--org acme] [--request-key K]
+capxul payment wait APPROVAL_ID [--org acme] [--timeout-seconds N] [--json]
+```
+
+`send` prepares the payment and opens its approval page. The page is the one
+and only confirmation: there is no `[y/N]` and no `--confirm`. Nothing moves
+until a person approves it there with their own key; the CLI never signs.
+
+`<to>` is an email, a @handle or an 0x address (an address you type is your
+own choice, and the page shows it again). `<amount>` is in `--asset`, a symbol
+the payer holds (USDC by default). With `--org`, the payment spends from a
+Budget you hold in that Organization: the one Budget for the asset, or the one
+`--budget` names. `--input FILE|-` takes the SDK's payment JSON instead, with
+documents; an Organization's adds its `permissionId`.
+
+A person sees what they are approving (who pays and what is left, who receives
+it, the amount, and that there is no fee: every operation is sponsored). The
+CLI opens the page on a terminal, prints the link, and follows it: `✓ Signed`
+when the person approves, `✓ Confirmed` when the payment settles, then the paid
+amount, the transaction and the receipt command. A rejection on the page ends
+`✗ Not sent` with exit 130; an approval that lapses sends nothing (exit 2).
+Ctrl-C stops following; the link still works, and `payment wait` follows it.
+
+With `--json`, `send` returns at once:
+
+```json
+{
+  "status": "awaiting_approval",
+  "approvalId": "approval_01JA…",
+  "approvalUrl": "https://app.staging.capxul.com/approve/approval_01JA…",
+  "paymentIds": ["payment_01JB…"],
+  "expiresAt": 1791359237000,
+  "next": { "argv": ["capxul", "payment", "wait", "approval_01JA…", "--json"] }
+}
 ```
 
-`status` reads the current personal Account unless one explicit Organization
-is selected with `--org`. It shows the saved session identity, selected actor
-profile and readiness, separate asset balances, received and issued requests,
-pending or active Payments, and five recent Activity rows. It gives scoped
-commands to inspect requests and Activity. A saved Organization default does
-not change the overview's personal scope.
-
-Each source read retains its own state. An unavailable balance or Inbox is
-not an empty balance or Inbox. Indexed Activity fallback is marked incomplete.
-JSON returns `state: "partial"` when a read fails or Activity is incomplete.
-Document counts include known references from available request and Payment
-reads. Activity detail can have additional documents. The overview does not
-render or download PDFs and does not prepare or submit Payments. Showing an
-existing scheduled or streaming Payment does not add recurring billing.
+An agent gives the person the link and runs `next.argv`. `payment wait
+APPROVAL_ID` follows the approval: once it is approved it sends it (unless the
+page already did; only one send can claim it) and waits for the payment to
+settle. Its result is the SDK's `{ approval, payments }`. An Organization
+payment's wait carries `--org`.
 
 ## Personal Payments
 
 ```sh
-capxul payment send --input payment.json --request-key REQUEST_KEY --confirm --json
-capxul payment send --resume REQUEST_KEY --confirm --json
-capxul payment retry --payment-id PAYMENT_ID --confirm --json
+capxul payment retry PAYMENT_ID --json
 capxul payment list --json
-capxul payment get --payment-id PAYMENT_ID --json
-capxul payment wait --payment-id PAYMENT_ID --timeout-seconds 120 --json
+capxul payment get PAYMENT_ID --json
+capxul payment wait PAYMENT_ID --timeout-seconds 120 --json
 ```
 
 These commands use the current authenticated session. Add `--email EMAIL` to
 select a saved session. In a terminal, omit the required Payment ID to enter it.
-`list` returns `{ payments }`. `get` returns `{ payment }` and refuses when the
-Payment is absent or unavailable to the session. Human output shows the full ID,
-status, amount, counterparty and available receipt.
+`get` refuses when the Payment is absent or unavailable to the session. Human
+output shows the full ID, status, amount, counterparty and available receipt.
 
 `wait` observes the exact Payment until it reaches a terminal state or needs an
 action. A failed Payment can be a completed observation. The timeout accepts
 1–3600 seconds and includes session restoration. A timeout or unavailable read
 prints exact get/wait commands. Waiting never resubmits a Payment.
 
-`send` accepts a bounded JSON file or `--input -` for stdin. An interactive
-send can collect the recipient, asset, amount and document options. It validates
-these fields, resolves the recipient, and previews the exact target before
-confirmation. A scripted send requires `--request-key` and `--confirm`. A human
-send generates a key when none was supplied. Signing starts after confirmation.
-
-The CLI saves the exact input in protected local state before preparation. It
-prints the request key and resume command, then prints prepared Payment IDs
-before signing. `--resume` uses that saved input and key; it refuses input or key
-overrides. Keep the same CLI home and authenticated person for recovery.
-A different input cannot replace the saved input for the same key.
-
-Send returns `{ payment, requestKey }` with the observed Payment state. Retry
-returns `{ payments }` and addresses the existing Payment command. It never
-creates a replacement send. Uncertain results keep exact read/wait or same-key
-resume guidance. A submitted result does not prove settlement.
-
-For an external address, JSON input must include
-`"externalAddressAcknowledged": true`. `--confirm` alone does not acknowledge
-the address. Human input shows the exact address and an unverified-recipient
-warning before one default-No confirmation. Known Capxul Parties resolved from
-addresses remain supported. Resume keeps the saved reference and acknowledgement.
-A saved key cannot gain new acknowledgement; use fresh input and a fresh key.
+Retry prepares the retry of the exact Payment and hands over to the approval
+page, exactly as `payment send` does: the page is the one and only
+confirmation, and `--json` returns `awaiting_approval`, the link and
+`next.argv` for `payment wait <approval id>`. It addresses the existing Payment
+command and never creates a replacement send.
 
 ## Activity
 
@@ -189,25 +238,25 @@ In a terminal, omit required fields for guided flags and annotation input.
 ```sh
 capxul request list
 capxul request issue --input invoice.json --confirm
-capxul request get --request-id REQUEST_ID
-capxul request cancel --request-id REQUEST_ID --confirm
+capxul request get REQUEST_ID
+capxul request cancel REQUEST_ID --confirm
 capxul inbox list
-capxul inbox get --request-id REQUEST_ID
-capxul inbox pay --request-id REQUEST_ID --confirm
-capxul inbox decline --request-id REQUEST_ID --confirm
-capxul org request list --org ORGANIZATION_ID
-capxul org request issue --org ORGANIZATION_ID --input invoice.json --confirm
-capxul org request get --org ORGANIZATION_ID --request-id REQUEST_ID
-capxul org request cancel --org ORGANIZATION_ID --request-id REQUEST_ID --confirm
-capxul org inbox list --org ORGANIZATION_ID
-capxul org inbox get --org ORGANIZATION_ID --request-id REQUEST_ID
-capxul org inbox pay --org ORGANIZATION_ID --request-id REQUEST_ID --permission-id PERMISSION_ID --confirm
-capxul org inbox decline --org ORGANIZATION_ID --request-id REQUEST_ID --confirm
+capxul inbox get REQUEST_ID
+capxul inbox pay REQUEST_ID
+capxul inbox decline REQUEST_ID --confirm
+capxul request list --org ORGANIZATION_ID
+capxul request issue --org ORGANIZATION_ID --input invoice.json --confirm
+capxul request get --org ORGANIZATION_ID REQUEST_ID
+capxul request cancel --org ORGANIZATION_ID REQUEST_ID --confirm
+capxul inbox list --org ORGANIZATION_ID
+capxul inbox get --org ORGANIZATION_ID REQUEST_ID
+capxul inbox pay --org ORGANIZATION_ID REQUEST_ID --permission-id PERMISSION_ID
+capxul inbox decline --org ORGANIZATION_ID REQUEST_ID --confirm
 ```
 
-`request` reads the selected actor's issued Invoice and payment requests.
-`inbox` reads payment requests addressed to that actor. Organization reads
-require one explicit Organization ID. Add `--email EMAIL` to select a saved
+`request` reads the issued Invoice and payment requests of whoever you act as:
+you, or the Organization `--org`, `CAPXUL_ORG` or `use org` names. `inbox` reads
+payment requests addressed to that actor. Add `--email EMAIL` to select a saved
 session. No signer is required for these reads.
 
 For human reads, start with `capxul request --help` or `capxul inbox --help`.
@@ -222,9 +271,9 @@ stderr, and the process exit code separately. A refusal is still a version 1
 result on stdout. Inspect `outcome` and `error.code`; do not infer success from
 valid JSON. Missing required input exits 2. A missing authenticated session exits 3. Noninteractive human refusals use stderr. These runs do not prompt.
 
-A missing `--org` refuses an Organization request or Inbox read before session
-restoration. Supply that selector on every Organization command. Do not assume
-that `org use` selects request or Inbox scope.
+Agents pass `--org` on every Organization command, so a saved choice never
+decides whose money a command touches. `--org` takes a handle or an
+Organization ID.
 
 Local help, refusal, and cancellation checks do not prove authenticated
 request reads, document output, issuance, or payment; those are separate
@@ -335,7 +384,8 @@ capxul document export --document-hash H --content-hash C --out original.bin
 
 Each command uses the current authenticated session. Add `--email EMAIL` to
 select a saved session. In a terminal, omit required fields to enter them.
-`get` returns document metadata and saves a PDF. It does not print source bytes.
+`get` returns document metadata and the `render` command for it; it writes no
+file and does not print source bytes.
 `verify` reports `ok: false` when verification fails. `render` saves a PDF and its
 self-contained HTML source in the `documents` directory next to CLI settings.
 Use `--output-dir` to change this directory. Human and JSON output contain
@@ -343,36 +393,29 @@ file metadata. Each render uses a new private directory and preserves earlier
 files. `export` writes the original bytes to a new file.
 It refuses an existing output file.
 
-Personal and Organization Payment `send`, `get`, `wait`, `retry`, and `list`
-also save available documents as PDFs. Activity detail and Payroll results
-save available documents in the same directory. Their results include
-document output metadata.
-Pending or unavailable documents retain that state. A document failure does
-not change the Payment result or start another Payment.
+Reads never write files. Payment `get`, `wait` and `list`, Activity detail and
+Payroll `get` and `wait` name each document with the `document render` command
+that saves it. Payment `send` and `retry`, Payroll `run` and Inbox `pay` still
+save available documents as PDFs in the same directory and report them in their
+result. Pending or unavailable documents retain that state. A document failure
+does not change the Payment result or start another Payment.
 
 ## Contact commands
 
 ```sh
 capxul contact list [--include-hidden]
-capxul contact get --entry-id PARTY_ID
+capxul contact get PARTY_ID
 capxul contact add --input FILE|- [--confirm]
-capxul contact label --entry-id PARTY_ID --label TEXT [--confirm]
-capxul contact hide --entry-id PARTY_ID [--confirm]
-capxul contact unhide --entry-id PARTY_ID [--confirm]
-
-capxul org contact list --org ORGANIZATION_ID [--include-hidden]
-capxul org contact get --org ORGANIZATION_ID --entry-id PARTY_ID
-capxul org contact add --org ORGANIZATION_ID --input FILE|- [--confirm]
-capxul org contact label --org ORGANIZATION_ID --entry-id PARTY_ID --label TEXT [--confirm]
-capxul org contact hide --org ORGANIZATION_ID --entry-id PARTY_ID [--confirm]
-capxul org contact unhide --org ORGANIZATION_ID --entry-id PARTY_ID [--confirm]
+capxul contact label PARTY_ID --label TEXT [--confirm]
+capxul contact hide PARTY_ID [--confirm]
+capxul contact unhide PARTY_ID [--confirm]
+capxul contact list --org acme
 ```
 
-Personal commands use the authenticated Account address book. Organization
-commands require one explicit `--org` or `--org-id`; they never use the saved
-Organization read default. `list` omits hidden entries unless
+Contacts belong to whoever you act as: your Account's address book, or the
+Organization `--org`, `CAPXUL_ORG` or `use org` names. `list` omits hidden entries unless
 `--include-hidden` is present. `get`, `label`, `hide`, and `unhide` address one
-stable Party with `--entry-id`.
+stable Party by its ID.
 
 `add --input` reads the existing `AddressBookAddInput` JSON shape. For example:
 
@@ -398,35 +441,42 @@ relationships, hidden state, and last activity time.
 ## Personal Account reads
 
 ```bash
-capxul account status --email person@example.com
-capxul account balance --json
-capxul account deposit --wizard
+capxul account show --email person@example.com
+capxul balance --json
+capxul address --wizard
 ```
 
 These commands reuse your verified current session unless you provide an email.
-They do not start setup or open a signer. Status shows lifecycle and transaction
-readiness; a failed lifecycle exposes its stage and error code. Balance shows
-exact asset quantities and available fiat valuations. An unavailable valuation
-or failed read is not zero. Deposit uses the SDK's address and network.
+They do not start setup or open a signer. `account show` shows lifecycle and
+transaction readiness; a failed lifecycle exposes its stage and error code.
+`balance` and `address` act for whoever you act as: your Account, or the
+Organization's treasury with `--org`. Balance shows exact asset quantities and
+available fiat valuations. An unavailable valuation or failed read is not zero.
+`address` uses the SDK's address and network.
+
+`account retry --display-name NAME --country CC --handle HANDLE` is the first
+setup: it creates the Profile, the personal Account and its wallet, as
+`auth login` offers to on a terminal. Without Profile fields, `account retry`
+resumes the setup of the existing Account.
 
 ## Organization commands
 
 ```sh
 capxul org list --json
-capxul org status --org ORGANIZATION_ID --json
-capxul org get --json
+capxul org show --org acme --json
+capxul org show --json
 capxul org me --json
-capxul org members --json
 capxul org member list --json
-capxul org member get --account-id ACCOUNT_ID --json
+capxul org member get ACCOUNT_ID --json
 capxul org wait --timeout-seconds 120 --json
 capxul org create --name NAME --handle HANDLE --country CC [--bio TEXT] [--size TEXT] [--confirm]
 capxul org retry --org ORGANIZATION_ID [--confirm]
 ```
 
 These commands accept `--email`. Without it, they restore the protected current
-session. Organization reads accept `--org` or its alias `--org-id`. Identical
-repeated IDs are accepted. Different IDs are refused.
+session. `org` commands act as the Organization `--org` names (a handle or an
+ID), then `CAPXUL_ORG`, then the one `use org` saved. Two different `--org`
+values are refused.
 
 A read without --org uses the Organization `use org` saved, then this machine's
 recovery ID, then the one unfinished setup returned by the backend. org list
@@ -440,10 +490,9 @@ setup section and explicit empty results. Members without an Account ID remain
 visible. `org me` shows backend capabilities and exact per-payment Budget caps;
 these caps are not available balances. `--json` keeps the structured SDK data.
 
-Member lookup uses an exact AccountId. In a human terminal, omit
---account-id to select an attached Account from the authorized member list.
-Members without an Account ID cannot be selected. Scripted and JSON lookup
-requires --account-id. Reads do not sign or change
+Member lookup uses an exact AccountId. In a human terminal, omit the ID to
+select an attached Account from the authorized member list. Members without an
+Account ID cannot be selected. Scripted and JSON lookup requires the ID. Reads do not sign or change
 setup state.
 
 org wait opens one exact setup subscription. It continues when needsAttention
@@ -452,40 +501,16 @@ or attention without a next check. It does not request a check or poll. The
 timeout accepts 1 to 3600 seconds and defaults to 120. A deadline returns
 CLI_DEADLINE at exit 5; Ctrl-C returns CANCELLED at exit 130.
 
-## Organization Payment send
-
-```sh
-capxul org payment send --org O --input payment.json --request-key K --confirm --json
-capxul org payment send --org O --resume K --confirm --json
-capxul org payment send
-```
-
-The Organization input adds its exact Budget ID as `permissionId`. It supports
-the same recipient, amount, and document fields as Personal send. It rejects
-`timing` and payload actor, Organization, key, and lineage overrides. Scripted
-calls require an explicit Organization, request identity, and `--confirm`.
-A human terminal collects missing input and previews the selected actor, exact
-Organization, Budget, treasury asset position, recipient, and document summary.
-A saved read default does not select this write.
-
-One default-No confirmation precedes signing. The protected input binds actor,
-Organization, and key. Resume uses that input and forbids source/key overrides.
-Prepared IDs reach stderr before the next signature. Send reports submission;
-exact scoped get/wait establishes later state. JSON preview includes safe
-summary fields and omits document bytes. External recipients use the same
-literal-true input field and human warning as Personal send. Resume preserves
-the saved reference even when the current lookup resolves to a Party.
-
 ## Organization Payment reads
 
 ```sh
-capxul org payment list --org O [--json]
-capxul org payment get --org O --payment-id P [--json]
-capxul org payment wait --org O --payment-id P [--timeout-seconds N] [--json]
+capxul payment list --org O [--json]
+capxul payment get P --org O [--json]
+capxul payment wait P --org O [--timeout-seconds N] [--json]
 ```
 
-These commands require an explicit Organization. They do not use the saved
-read default. The backend checks current Organization participation and returns
+With `--org`, `CAPXUL_ORG` or `use org`, these commands read the Organization's
+Payments; without one they read yours. The backend checks current Organization participation and returns
 only that Organization's outgoing, incoming, and self Payments. Get refuses
 a missing or mismatched Payment ID. Reads do not need a signer.
 
@@ -498,37 +523,25 @@ instructions with both Organization and Payment IDs.
 ## Organization Payment retry
 
 ```sh
-capxul org payment retry --org O --payment-id P --confirm --json
-capxul org payment retry
+capxul payment retry P --org O --json
 ```
 
 Retry addresses the original command and every Payment in that command. It
-creates no replacement send or request key. A terminal can collect the Payment
-ID and select a currently accessible Organization. A saved read default does
-not choose the write target. JSON and scripted runs require both IDs and
-`--confirm`.
-
-Before signing, the preview shows every original Payment, recipient, exact
-asset and quantity, timing, and state. It also shows the original command and
-stored Budget. A human terminal asks one default-no question, including when
-`--confirm` is supplied. The signer starts after this step. A changed prepared cohort
-or actor refuses before signature.
-
-The result is `{ payments }` in the SDK's original order. Submitted Payments
-can still be pending. A failure, timeout, or interruption retains the selected
-Organization, Payment, and verified sibling IDs with same-scope get/wait
-commands. Retry does not claim settlement from a submission hash.
+creates no replacement send or request key. The Organization's retry is
+prepared for your own key and handed over to the approval page; the page
+shows the whole cohort. `--json` returns the link and `next.argv` for
+`payment wait <approval id> --org O`, which follows every Payment to its end.
 
 ## Permissions
 
 ```sh
 capxul org permission list [--org O] [--json]
-capxul org permission get --permission-id B [--org O] [--json]
+capxul org permission get B [--org O] [--json]
 capxul org permission create --org O --input budget.json --request-key K --confirm [--json]
-capxul org permission change --org O --permission-id B --input budget.json --request-key K --confirm [--json]
+capxul org permission change B --org O --input budget.json --request-key K --confirm [--json]
 ```
 
-These commands use the explicit Organization, then the protected read default.
+These commands use `--org`, then `CAPXUL_ORG`, then the Organization `use org` saved.
 A human terminal can select an accessible Organization when neither exists.
 Each read checks current Organization access. `get` requires an exact Permission
 ID and refuses a missing or mismatched result. Reads do not need a signer.
@@ -577,21 +590,23 @@ Invitation rights. Human mode guides missing scope and shows the full frozen
 before/after snapshot before one default-no approval. Machine mode requires
 scope, key, and confirmation. A changed snapshot refuses before staging or
 signature. Unfinished Invitation configuration must complete or cancel first.
-Submission remains pending application. Use exact command get/wait after an
-uncertain result; the command does not promise unconditional replacement replay.
+Submission remains pending application. After an uncertain result, follow the
+exact command with `org permission command get` or `org permission command wait`
+and the request key (not listed in the help); the command does not promise
+unconditional replacement replay.
 
 ## Payroll runs, rosters, and reads
 
 ```sh
 capxul org payroll groups list --org O [--json]
 capxul org payroll groups save --org O --input group.json --confirm [--json]
-capxul org payroll groups remove --org O --group-id G --confirm [--json]
+capxul org payroll groups remove G --org O --confirm [--json]
 capxul org payroll terms --org O [--json]
 capxul org payroll list --org O [--json]
-capxul org payroll run --org O --input run.json --request-key K --confirm [--json]
-capxul org payroll run --org O --resume K --confirm [--json]
-capxul org payroll get --org O --run-id R [--json]
-capxul org payroll wait --org O --run-id R --timeout-seconds 120 [--json]
+capxul org payroll run --org O --input run.json --request-key K [--json]
+capxul org payroll run --org O --resume K [--json]
+capxul org payroll get --org O R [--json]
+capxul org payroll wait --org O R --timeout-seconds 120 [--json]
 ```
 
 Group input contains `name`, `tone`, and `members`. Each member supplies a
@@ -616,16 +631,18 @@ refuse before client work.
 In a human terminal, `capxul org payroll run` guides the current Organization,
 Budget, settlement asset, date, roster or known Parties, and actual payout
 quantities. Roster amounts and terms are reference data. The complete preview
-shows each recipient and Safe, quantity, raw units, and adjustment. One
-default-no approval precedes signing, including when `--confirm` is supplied.
-Machine runs require exact scope, input, key, and `--confirm`.
+shows each recipient and Safe, quantity, raw units, and adjustment. The run
+is then prepared and handed over to the approval page, the one and only
+confirmation. Machine runs require exact scope, input and key; `--json`
+returns the approval link and `next.argv` for `payment wait <approval id> --org O`.
 
 The command saves the exact input in protected storage under the verified actor,
 Organization, and key before execution. `--resume K` restores that snapshot.
 It requires the same explicit Organization and cannot combine fresh input or
 another key. Payroll accepts email and Party references. Raw external addresses
 are outside the current run contract.
-Success returns `{ run, requestKey }`; submission does not prove settlement.
+`--resume K` prepares the same run again, so it reopens a pending approval
+rather than paying twice.
 
 Get returns the full authorized run detail, command, ordered items, and recorded
 times. Wait observes the exact run without polling or submitting. It keeps
@@ -636,69 +653,50 @@ Recovery retains exact Organization, run, and any observed request key.
 ## Invitation commands
 
 ```sh
-capxul org invite list [--mine] [--limit N] [--cursor C] [--phase PHASE ...] [--org O]
-capxul org invite get --invitation-id I [--org O]
-capxul org invite wait --invitation-id I [--org O] [--timeout-seconds N]
-capxul org invite review --invitation-id I --org O [--timeout-seconds N]
-capxul org invite accept --invitation-id I --offer-digest D --org O [--confirm] [--timeout-seconds N]
-capxul org invite decline --invitation-id I --org O [--confirm]
-capxul org invite cancel --invitation-id I --org O [--confirm]
-capxul org invite resend --invitation-id I --org O [--confirm]
-capxul org invite retry --invitation-id I --org O [--confirm]
-capxul org member invite (--to-email E | --account-id ID) [--budget-id B ...] [--permission-id M ...] [--new-budget-name N --asset A (--limit Q | --unlimited) (--recipient-account ID ... | --any-recipient) --actions pay[,commitments]] --org O [--request-key K] [--preview] [--confirm]
+capxul invite list [--limit N] [--after C] [--phase PHASE ...]
+capxul invite accept [ID] --offer-digest D [--confirm] [--timeout-seconds N]
+capxul invite decline [ID] [--confirm]
+capxul org invite list [--limit N] [--after C] [--phase PHASE ...]
+capxul org invite cancel [ID] [--confirm]
+capxul org invite resend [ID] [--confirm]
+capxul org member invite [EMAIL | --account-id ID] [--budget-id B ...] [--permission-id M ...] [--new-budget-name N --asset A (--limit Q | --unlimited) (--recipient-account ID ... | --any-recipient) --actions pay[,commitments]] [--request-key K] [--preview] [--confirm]
 ```
 
-`org invite list` returns your own offers. It accepts `--limit` (1--100),
-`--cursor`, and repeated `--phase` values, and its result carries `invitations`,
-`nextCursor`, and `observedAt`: pass `nextCursor` back as `--cursor`, and change
-no other filter between the two calls. `--mine` names the own-offer projection,
-which is already the default. With `--org O` the command returns that
-Organization's invitations for a current Admin instead; the Organization list is
-not filtered to you, so `--mine` together with `--org` refuses with exit 2. The
-other invitation commands require an exact `--invitation-id`.
-
-`org invite get` and `org invite wait` use `--org` when you name it. Without
-`--org` they walk your own-offer pages, 100 rows per request, until they find
-the invitation or the pages end. They never consult the saved read default, and
-an offer you cannot see is refused. `--timeout-seconds` bounds the resolution
-and the read together on both commands.
+`invite` holds the invitations you received; `org invite` holds the invitations
+the Organization you act as sent. `invite list` returns your own offers.
+`org invite list` returns that Organization's invitations for a current Admin.
+Both accept `--limit` (1--100), `--after`, and repeated `--phase` values, and
+their result carries `invitations`, `nextCursor`, and `observedAt`: pass
+`nextCursor` back as `--after`, and change no other filter between the two calls.
+
+A received invitation names its own Organization: `invite accept` and
+`invite decline` walk your own-offer pages, 100 rows per request, to find it.
+`org invite cancel` and `org invite resend` act in the Organization `--org`,
+`CAPXUL_ORG` or `use org` names.
+
+Recovery guidance can also name `invite get`, `invite review`, `invite wait`,
+`org invite get`, `org invite wait` and `org invite retry`. They work as before
+but are not listed in the help: `get` and `review` read one offer, `wait`
+follows it until it settles with one SDK subscription, and `retry` resumes the
+backend's own recovery action. None of them writes a new offer.
 
 Invitation lists label own-offer or Organization Admin scope and the verified
-actor. They show an explicit empty page, next cursor, or end of results. Page
-filters and cursor values stay in their selected scope.
+actor. They show an explicit empty page, next cursor, or end of results.
 
 Invitation human output shows the authoritative phase, delivery, expiry, and
 offered policies. An offer does not prove active membership. Manual resend/retry commands come only
 from the backend action projection, with exact scope/session and earliest time.
-Older responses without that projection show read-back guidance. Lifecycle
-recovery remains separate from manual options. Member-invite
-previews show exact per-payment caps and allowed recipients/actions; expiry is
-unavailable before authoring. The native authoring wizard asks for Organization,
-recipient, grants and policy before session email. New-Budget labels identify
-policy inputs; skip them for existing grants. Wizard answers use the same request
-validation as flags. Every authoring write prints its request key
-before submission. JSON result data stays unchanged.
+Member-invite previews show exact per-payment caps and allowed recipients/actions;
+expiry is unavailable before authoring. Every authoring write prints its request
+key before submission. JSON result data stays unchanged.
 
 Uncertain decline/cancel/resend/retry failures and transition deadlines print an
-exact `org invite get` command with the resolved session. Read the current offer
-before another transition; a lost response does not authorize replay.
-
-`org invite wait` uses one exact SDK subscription after resolving scope. It
-finishes when the offer settles or lifecycle recovery asks a person to act.
-Manual recovery options do not stop the wait. It never polls, retries, resends,
-or accepts. The deadline covers resolution and observation; completion, failure
-and interruption release the subscription, including a handle that arrives late.
-
-Native invitation target prompts ask Organization and invitation IDs before
-session email. Transition confirmation shows the verified actor and the current
-resolved offer, including grants and expiry, before the default-No question.
+exact `get` command for the offer with the resolved session. Read the current
+offer before another transition; a lost response does not authorize replay.
 
-`org invite review` requires `--org`, returns the current `InvitationView`
-directly in `data`, and performs no write or signing.
-
-The four transitions require `--org` in both modes, as `accept` does. They never
-author a new offer. A noninteractive or JSON run requires `--confirm`. An
-interactive run shows the resolved current offer and asks a default-no question.
+The transitions never author a new offer. A noninteractive or JSON run requires
+`--confirm`. An interactive run shows the resolved current offer and asks a
+default-no question.
 
 `org member invite` authorizes one exact offer. `--preview` writes nothing and
 needs neither a request key nor confirmation. A noninteractive write requires
@@ -706,7 +704,7 @@ needs neither a request key nor confirmation. A noninteractive write requires
 used before it submits, so a lost response is recoverable with the same
 identity. At most one `--new-budget-name` is accepted per command.
 
-`org invite accept` is the exact grantee's consent commit. It takes the exact
+`invite accept` is the exact grantee's consent commit. It takes the exact
 digest the offer shows as `--offer-digest`: a noninteractive or JSON run must
 supply it, and without it the command refuses with exit 2 before it creates a
 client. An interactive run may omit it, and then reads the offer and fills the
@@ -716,9 +714,7 @@ spellings must match when supplied together. The command returns the
 `InvitationView` directly in `data`. The grant is executed by the deployment's
 technical executor, so the command needs no browser bridge and works in a
 headless or CI session. A repeat with the stored digest returns the same
-accepted result; a different digest refuses and cannot overwrite consent. The
-returned view is the authorization-time view of the consent commit
-(`pending_grant`); read the settled `active` state with `get` or `wait`.
+accepted result; a different digest refuses and cannot overwrite consent.
 
 ## Organization writes
 
@@ -777,9 +773,9 @@ ordinary local and online commands, help, version, and safely attributed argumen
 refusals. Parser refusals produce a completion without a start. Early native
 global errors with no resolved command route send nothing, because the CLI
 cannot determine whether they belong to a silent collection control.
-`telemetry disable` saves one preference for the OS user and sends no final
+`config telemetry off` saves one preference for the OS user and sends no final
 remote event. Already running CLI processes check the current preference before
-each export. Requests already sent cannot be recalled. `telemetry status`
+each export. Requests already sent cannot be recalled. `config telemetry status`
 reports the stored preference, effective policy, configuration, and reason.
 `--log-level` controls normal diagnostic output, not collection. An eligible
 invocation still produces its remote completion unless collection is disabled.
@@ -802,13 +798,41 @@ Organization setup failures include a copyable command with the exact ID and
 selected email. When state is uncertain, read status first. A supported retry
 includes `--confirm`; terminal runs still ask for confirmation. If no ID is
 known, the command lists your Organizations instead of guessing one.
-JSON errors can include `error.details.recovery` with `kind` (`read` or `retry`)
-and an `argv` array for that primary action. These arguments preserve the same
-scope as the human command; they do not grant authority or bypass current checks.
+`--json` writes one version 1 envelope to stdout. Success contains `data`: the
+SDK's own value for the command, with no CLI wrapper. A list is the SDK page,
+`{ items, nextCursor }`; pass `nextCursor` back as `--after` where the command
+takes one. `--fields a,b` keeps only those fields of `data` (`amount.value`
+reaches inside an object; a list keeps `nextCursor` and picks from each item).
+`--fields` without `--json` refuses.
+
+A failure contains `error`:
 
-`--json` writes one version 1 envelope to stdout. Success contains `data`, which
-can be an object, array, or null according to the command's SDK result.
-Failure contains `error.code` and CLI-owned `error.message`. A wallet failure
+```json
+{
+  "code": "CLI_USAGE",
+  "message": "Unknown command \"paymnt\".",
+  "hint": "Did you mean: capxul payment list",
+  "next": { "argv": ["capxul", "payment", "list"] }
+}
+```
+
+`code` and `message` are always present. `hint` says what to do when a sentence
+helps, `field` names the refused input, and `next.argv` is the command that
+fixes it or reads where an interrupted command stands: `capxul auth login` when
+no one is signed in, the corrected command for a typo, or the exact `get` for an
+uncertain write. `next` preserves the same scope as the human command; it does
+not grant authority or bypass current checks. `error.details.recovery` keeps
+its `kind` (`read` or `retry`) next to the same `argv`.
+
+A person sees one red line for what happened and one for what fixes it (on the
+same line when both fit in 80 columns):
+
+```text
+✗ Unknown command "paymnt". Did you mean: capxul payment list
+✗ Not signed in. Try: capxul auth login
+```
+
+A wallet failure
 also includes its known `error.mode` and allowed `error.details`: wallet stage,
 operation, provider, provider code, and HTTP status. An unknown browser failure
 uses mode `unknown`. No provider message, token, signature, or native cause enters
@@ -871,6 +895,32 @@ all `telemetry` commands receive no notice. The optional check has one 500 ms
 budget. Safe failed attempts are cached. Storage or network failures remain
 silent and do not change the command result. This check sends no telemetry.
 
+## Sandbox: `capxul dev`
+
+`capxul dev` is for building and testing on Capxul, agents included, without real
+money. It works on a test deployment: staging, or a local DevNet
+(`capxul-devnet up --browser-origin http://localhost:3000` in this repository, then
+`capxul use env devnet`). Production refuses both commands.
+
+```sh
+capxul dev fund 100              # test money into your own Safe (default 100 USDC)
+capxul dev fund 50 --asset USDT
+capxul dev key                   # a test publishable key for http://localhost:3000, into .env.local
+capxul dev key --origin http://localhost:3100 --print
+```
+
+`dev fund` needs you signed in and funds only your own Safe. `dev key` needs no
+sign-in; it sets `NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY` and `CAPXUL_SITE_URL` in
+`.env.local` and keeps every other line. On staging, sign-in works only from
+`http://localhost:3000` or `http://localhost:3100`.
+
+[`tests/dev-journeys.mjs`](tests/dev-journeys.mjs) runs the agent plugin's
+journeys with the built CLI against the local DevNet: sign in, `dev fund`, the home
+screen, a payment (refused with its fix while the wallet setup is unfinished, as
+it is on a DevNet with no wallet provider), requests, offers, Inbox, Organizations,
+the account, `schema`, a typo's fix and `dev key`. The `capxul dev journeys` job in
+`.github/workflows/devnet-integration.yml` starts the DevNet and runs it.
+
 ## Development commands
 
 ```sh
@@ -892,11 +942,11 @@ This CLI establishes a first-party BetterAuth session. An older native
 Logout clears the selected email's session and attempts to revoke any native
 grant that was stored before the first-party flow replaced it.
 
-`capxul auth login` and `capxul auth signup` stay separate commands. On a
+`capxul auth login` and `capxul account retry` stay separate commands. On a
 terminal, each command is a wizard. `auth login` asks for the email and a masked
 OTP. It accepts the code as a paste. It retries an invalid code at most three
 times for one request. After sign-in, an incomplete account gets one offer to
-continue setup in the same command. `auth signup` authenticates first, then asks
+continue setup in the same command. `account retry` authenticates first, then asks
 for the Profile fields: display name, two-letter country code, and handle. A
 known value is the prompt default, so Enter keeps it.
 
@@ -924,7 +974,7 @@ verification has no waiting sign-in, the error names `capxul auth login`.
 Neither command prints the code itself.
 
 If account setup or its final read fails recoverably, the CLI prints an exact
-`auth signup` continuation with your email and Profile fields. Run it with the
+`account retry` continuation with your email and Profile fields. Run it with the
 same protected CLI home to resume the saved session. Explicit access/input
 refusals and non-retryable failures require their stated correction first.
 
@@ -943,13 +993,13 @@ Profile field; a missing field refuses with exit 2:
 
 ```sh
 # Supply only the delivered OTP through stdin.
-capxul auth signup --email "$TEST_EMAIL" --otp-stdin \
+capxul account retry --email "$TEST_EMAIL" --otp-stdin \
   --display-name "Test Person" --country GH --handle test_person --json
 ```
 
 `--otp-stdin` reads up to 64 bytes, ending at EOF. Pipe from a secret provider or
 use input redirection from a protected file. An invalid value refuses with exit 2.
-For `auth signup`, a missing `--otp-stdin` refuses with exit 2 before the command
+For `account retry`, a missing `--otp-stdin` refuses with exit 2 before the command
 starts client work. Only `auth verify <code>` accepts a code as an argument: the
 code is single-use and expires in minutes. Codes are never persisted in the
 continuation or included in output.
@@ -957,11 +1007,11 @@ continuation or included in output.
 The local page binds to an OS-selected loopback port. A random launch capability
 is redeemed once and removed from the URL before Openfort starts. The page receives
 only the authenticated wallet token and encryption session in memory. Closing it
-ends the current wallet attempt. Re-run `auth signup` with the same CLI home to
+ends the current wallet attempt. Re-run `account retry` with the same CLI home to
 resume the same Profile and Account without another OTP while the backend session
 remains valid.
 
-`auth signup` returns only two readiness results. `setupState: "ready"` is a
+`account retry` returns only two readiness results. `setupState: "ready"` is a
 personal Account that the Account readiness owner reads as ready and deployed,
 and its data carries the public identifiers: the Profile, the public wallet
 address (`smartAccount.signerAddress`), the personal Smart Account address
@@ -994,7 +1044,7 @@ local sign-out remains in effect.
 
 `auth profile` returns a backend-read Profile and account lifecycle without opening
 the browser. Successful email authentication can return `setupState: "setup-required"`.
-`auth signup` returns `setupState: "ready"` only after Core reads a ready Account.
+`account retry` returns `setupState: "ready"` only after Core reads a ready Account.
 After logout, profile reads refuse with `NOT_AUTHENTICATED` and exit 3. An invalid
 or expired OTP refuses with exit 2.
 
@@ -1007,15 +1057,15 @@ capxul account retry --email you@example.com --wizard
 
 The terminal shows the verified session, Account ID and current lifecycle before
 confirmation. A ready Account starts no wallet work. Missing Account or Profile
-state directs to `auth signup`. A deadline stops waiting; check `account status`
+state directs to `account retry`. A deadline stops waiting; check `account status`
 for the same session before retrying.
 
 Read an Organization treasury or deposit target:
 
 ```sh
-capxul org balance --org org_example --email you@example.com
-capxul org deposit --org org_example --email you@example.com
-capxul org balance --wizard
+capxul balance --org org_example --email you@example.com
+capxul address --org org_example --email you@example.com
+capxul balance --wizard
 ```
 
 These commands use the existing Organization read selection. Balances require
@@ -1027,11 +1077,11 @@ relationships and hidden state. JSON keeps the existing array, entry or null.
 
 ```sh
 capxul contact list --include-hidden
-capxul contact get --entry-id party_example
-capxul org contact get --org org_example --wizard
+capxul contact get party_example
+capxul contact get --org org_example --wizard
 ```
 
-In a terminal, omit `--entry-id` to select a contact, including hidden contacts.
+In a terminal, omit the ID to select a contact, including hidden contacts.
 In a script, provide the exact Party ID. Organization contacts always require
 an explicit `--org`; they never use the personal book as a fallback.
 
@@ -1040,17 +1090,17 @@ Without an input file, the wizard asks for these values. On an uncertain respons
 use the printed list command to check the same address book before adding again.
 Adding an existing contact can unhide it or change its label.
 
-Change a contact label with `contact label --entry-id party_example --label
+Change a contact label with `contact label party_example --label
 "New label" --confirm`. In a terminal, omit the Party ID to select from the
 same book, including hidden contacts. Organization labels require `--org`.
 After an uncertain response, use the exact get command printed by the CLI.
 
-`contact hide` can select a contact in a terminal when `--entry-id` is omitted.
+`contact hide` can select a contact in a terminal when the ID is omitted.
 It confirms the hidden state, then prints the exact `contact unhide` command for
 the same Party, session and scope. The contact's history remains available.
 
 `contact unhide` uses the same scoped selector, including hidden contacts, when
-a terminal omits `--entry-id`. It confirms the change and shows the visible
+a terminal omits the ID. It confirms the change and shows the visible
 contact. Scripts provide the exact Party ID and `--confirm`.
 
 ## Fixed offers
@@ -1061,10 +1111,10 @@ These commands do not sign payments or create checkout purchases.
 ```sh
 capxul offer create --input offer.json --request-key consulting-001 --confirm
 capxul offer list
-capxul offer get --offer-id OFFER_ID
-capxul offer revise --offer-id OFFER_ID --expected-revision 1 --input offer.json --confirm
-capxul offer deactivate --offer-id OFFER_ID --expected-revision 2 --confirm
-capxul org offer list --org ORG_ID
+capxul offer get OFFER_ID
+capxul offer revise OFFER_ID --expected-revision 1 --input offer.json --confirm
+capxul offer deactivate OFFER_ID --expected-revision 2 --confirm
+capxul offer list --org ORG_ID
 ```
 
 Use `org offer` and `--org ORG_ID` for each Organization command. Use `--email`
@@ -1105,7 +1155,7 @@ reference. Separate purchasers receive separate checkout and settlement IDs.
 Alice issues a basic request or an Invoice to Bob with `request issue`. For an Organization issuer,
 Alice uses `org request issue --org ORGANIZATION_ID`. Issuance saves Alice's PDF
 by default and returns the request ID, document references, and checkout URL.
-Bob runs `inbox list`, then `inbox get --request-id REQUEST_ID`. An Organization
+Bob runs `inbox list`, then `inbox get REQUEST_ID`. An Organization
 payer uses the equivalent `org inbox` commands with its explicit Organization.
 
 Bob's Inbox contains the request and document references. It does not receive a
@@ -1148,9 +1198,10 @@ External funding requires the correct network, balance, gas, and any exact token
 approval. Payment goes through the Payments contract with the validated snapshot.
 Inspect the resulting state and receipt before reporting payment complete.
 
-CLI `inbox pay` retains its existing CLI signing flow. It does not depend on the
-hosted checkout page. A rejected signature or uncertain reply is not permission
-to send another Payment. Use the printed readback and recovery instructions.
+CLI `inbox pay` prepares the request's Payment and hands over to the approval
+page, as `payment send` does. It does not depend on the hosted checkout page.
+A rejection on the approval page is not permission to send another Payment.
+`--resume` reopens the approval of a request whose Payment is already prepared.
 
 Checkout links do not create recurring billing, automatic debits, booking,
 refunds, or QR codes.