@capxul/cli 4.20.0-beta.3 → 4.20.0-beta.31

package/README.md

@@ -1,46 +1,844 @@
 # Capxul CLI
 
-The CLI provides local diagnostics, an online backend check, and one global
-collection preference. It requires Node 24 or later on macOS or Linux.
+The CLI provides email OTP login, persistent first-party sessions, a handover to
+the web app for Account setup, personal and Organization contacts, a bundled
+Openfort wallet page for Organization setup,
+backend profile and account reads, diagnostics, and one global collection
+preference. It requires Node 24 or later on macOS or Linux.
 
 ```sh
 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
 ```
 
 Help and version do not require application credentials or a working backend.
+With no arguments, `capxul` shows the same generated help as `capxul --help`.
 They use the same observation policy as ordinary commands. Shell completion
 machinery and collection controls send no observation records.
 `doctor` checks local configuration unless `--online` is present. An online
 check uses the public Capxul SDK and verifies the backend response nonce.
 It does not authenticate a person or submit a transaction.
 
+## Agent plugin
+
+The Claude Code plugin lives in its own private repository,
+[`Xelmar-tech/capxul-plugin`](https://github.com/Xelmar-tech/capxul-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. Install it with:
+
+```sh
+claude plugin marketplace add Xelmar-tech/capxul-plugin
+claude plugin install capxul@capxul
+```
+
+That repository's CI checks every command the skill names against
+`capxul schema --json` from `@capxul/cli@latest`, so a renamed or removed command
+fails there.
+
+## 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
+capxul whoami                 # local, under 0.3 s
+capxul whoami --json          # the same, with where each value came from
+capxul auth login             # sign in with an email code
+capxul auth verify 123456     # finish a sign-in that auth login started (scripts and agents)
+capxul auth switch ada@example.com
+capxul auth logout
+capxul use org acme           # act as one of your Organizations
+capxul use personal           # act as yourself
+capxul use env devnet         # use this environment from now on
+```
+
+`whoami` prints the signed-in person, who you act as, the Safe, and the
+environment with its network. It reads only this machine's files and makes no
+network call. With `--json`, each value carries its `source`: `flag`, `env`
+(a variable), `saved`, or `default`.
+
+Every human command prints one header line on stderr when someone is signed in:
+`▸ <actor> · <environment> · <network>`, for example
+`▸ Acme Ltd · staging · Base Sepolia`. The environment name is highlighted on a
+terminal. Production is the normal case and will show no environment label.
+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 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
+command. `org` commands act as the saved Organization unless `--org` names
+another. `use personal` forgets it. Signing in as a different person forgets the
+previous person's Organization and Safe.
+
+Scripts and agents sign in with two commands: `auth login --email EMAIL` sends
+the code and returns `next.argv` for `auth verify <code>`, which finishes it.
+`--email` is not needed on later commands.
+
+## Guided terminal input
+
+In a human terminal, these commands collect missing required fields one step at
+a time:
+
+```sh
+capxul org permission change
+capxul org member invite
+capxul payment get
+capxul document get
+```
+
+Supplied valid values remain in the command. Preview and confirmation still
+apply to writes. `--wizard` provides an explicit entry to the same native input
+flow. Ctrl+C or Ctrl+D cancels with exit 130. Bare groups show help. JSON, CI,
+and noninteractive runs require their declared input and do not prompt.
+
+## Waiting output
+
+Pending setup and observation commands show a waiting message. Human terminals
+also show an activity indicator. The indicator stops before a prompt or final
+result. Noninteractive human output uses text without animation.
+
+Payment, Payroll, Permission, Organization, and Invitation waits print observed
+state changes on stderr. JSON mode uses declared progress objects on stderr and
+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.
+
+## Sending money through the approval page
+
+```sh
+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 [--from BUDGET]
+capxul payment send --input payment.json [--org acme] [--request-key K]
+capxul payment wait PAYMENT_ID_OR_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
+`--from` names (by its name or ID). `--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"] }
+}
+```
+
+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`. Without `--timeout-seconds`, `payment wait` follows
+until the approval lapses and the payment settles, as `send` does; with it, the wait
+stops after that many seconds (1 to 3600) with exit 5 and the same command to run again.
+
+## Personal Payments
+
+```sh
+capxul payment retry PAYMENT_ID --json
+capxul payment send rex@capxul.com 50 --json
+capxul payment cancel PAYMENT_ID --json
+capxul payment redirect PAYMENT_ID sam@acme.co --json
+capxul payment list --json
+capxul payment get PAYMENT_ID --json
+capxul payment wait 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.
+`wait` follows a Payment until it ends unless `--timeout-seconds` bounds it.
+`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.
+
+Scheduled sends are unavailable while scheduled payments are rebuilt.
+`send` has no release-date flag. The backend refuses scheduled timing with
+`INVALID_INPUT` on `timing`: `scheduled payments are being rebuilt`.
+
+Existing holds keep their claim, cancel and redirect operations. `cancel` returns
+a held payment to whoever funded it; `redirect` sends it to someone else. For an
+Organization's held payment only an Owner may cancel or redirect it; anyone else,
+a Budget member included, is refused before anything is prepared. Both hand over
+to the approval page as `send` does, then read the Payment until the chain shows
+the step (`payment wait <approval id>` reports them once sent). A cancelled
+payment keeps the amount it was for. A cancel or redirect of a payment that is
+no longer held is refused (`WRONG_STATE`, exit 2) with `Payment <id> is already
+cancelled.` or the state it is in. A held payment that was never signed reads
+`failed`, not `scheduled`.
+
+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
+
+```sh
+capxul activity list --limit 25 --json
+capxul activity get --kind payment --id PAYMENT_ID --json
+capxul activity get --kind movement --id MOVEMENT_ID --json
+capxul activity summary --from 1790553600000 --to 1790639999999 --json
+capxul activity annotate --input annotation.json --confirm --json
+```
+
+Add explicit `--org ORGANIZATION_ID` for Organization scope. The saved
+Organization read default does not select this scope. List supports kind,
+direction, status and inclusive epoch-millisecond bounds. Reuse a cursor with
+the same filters and actor. An unavailable indexer produces a visible incomplete
+activity warning. Movement rows remain Movements.
+
+Summary keeps exact per-asset raw-unit totals. Get returns exact detail and
+refuses a missing or unavailable reference. Annotation accepts only `reference`,
+`accountingCategory` and `memo`; it cannot alter settlement or documents. Human
+writes require preview and confirmation. Scripted writes require `--confirm`.
+In a terminal, omit required fields for guided flags and annotation input.
+
+## Issued requests and received Inbox
+
+```sh
+capxul request list
+capxul request issue --input invoice.json --confirm
+capxul request get REQUEST_ID
+capxul request cancel REQUEST_ID --confirm
+capxul inbox list
+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 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`.
+Run `request list` for requests you issued. Run `inbox list` for requests you
+received. Copy the full request ID from the list into the matching `get` command.
+In a terminal, omit required fields to start guided input. Ctrl+C or Ctrl+D
+cancels with exit 130. The wizard can ask about optional email selection before
+required fields. Provide `--email EMAIL` when you need one saved session.
+
+For agent reads, supply all required flags and add `--json`. Capture stdout,
+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.
+
+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
+journey checks.
+
+Human output shows request ID, reference, amount, status, counterparty
+reference, and document references. An unpaid Invoice can have a document
+before any Payment exists. The document guidance preserves the selected
+session. Run that explicit command to save a PDF. Request and Inbox reads do
+not render or download PDFs. JSON output preserves scope, direction, and the
+SDK item or list. Unavailable reads remain failures, not empty lists.
+
+Cancel changes an issued request. Decline changes a received request. Both
+commands read the exact request in the selected scope before the write.
+Terminal writes show a preview and ask for confirmation. Scripted writes
+require `--confirm` before session restoration. A lost write reply gives an
+exact readback command in the same scope and session. It never repeats the
+write. These commands start no signer and move no funds.
+
+Issue accepts a basic payment request or an Invoice request JSON object from
+`--input FILE` or `--input -`. Both require `payer` and an exact positive
+`amount`. A basic request requires an explicit `reference` and accepts an
+optional private `memo`. An Invoice request also supplies `invoice`.
+Issue saves no file. Its human output names the `document render` command for
+each document, and its JSON result is `{ scope, direction, item }`: the issued
+request with its document references, with no document output.
+Human and JSON output include `checkoutUrl` for an Invoice or Memo request
+instruction with a link token. Invoice requests keep `/checkout/invoices/`.
+Basic requests use `/checkout/requests/`. Movement documents do not create
+request links.
+The PDF includes the checkout link from the authorized backend render context.
+For a custom deployment, set `CAPXUL_CHECKOUT_FRONTEND_ORIGIN` in both the CLI
+and backend environments. Use the same frontend origin for both.
+Offer create, get, list, revise, and deactivate output also include `checkoutUrl`.
+The checkout page reads current terms and status when the link opens.
+Save a PDF with the printed `document render` command. Do not issue the request
+again to get a PDF.
+
+```json
+{
+  "payer": { "kind": "email", "email": "bob@example.com" },
+  "amount": { "asset": "<admitted asset ID>", "value": "9" },
+  "invoice": {
+    "kind": "invoice",
+    "invoiceNumber": "INV-002",
+    "payerRef": "Bob",
+    "payeeRef": "Alice",
+    "dueAt": 1900000000000,
+    "note": "Thank you",
+    "discountMinor": "1000000",
+    "lineItems": [{ "description": "Consulting", "quantity": 1, "unitMinor": "10000000" }]
+  }
+}
+```
+
+For a basic request, omit `invoice`:
+
+```json
+{
+  "payer": { "kind": "email", "email": "bob@example.com" },
+  "amount": { "asset": "<admitted asset ID>", "value": "9" },
+  "reference": "SESSION-001",
+  "memo": "Counselling session"
+}
+```
+
+Supply your Invoice number. The request reference defaults to that number;
+optional `reference` changes the request reference only. `dueAt` uses epoch
+milliseconds, as the shared Invoice document and frontend do. Set it to zero
+for no due date. Optional `expiresAt` also uses epoch milliseconds. `discountMinor` and
+`unitMinor` use the asset's exact minor units. The example is 10 USDC less
+1 USDC for a six-decimal USDC asset. The backend checks the Invoice total,
+registered payer, and issuer authority before creation. Optional `memo` is a
+request memo; `invoice.note` is the document note. Unknown fields refuse.
+
+Earlier CLI guidance incorrectly named Unix seconds for `dueAt`. Convert those
+values to milliseconds for new drafts. Rendering does not change the dates in
+an issued document. Inspect an incorrect Invoice before cancelling it and
+issuing a corrected request.
+
+A lost issuance reply provides issued-list readback in the same scope and
+session. Issuance has no automatic resend.
+
+Inbox pay reads and confirms exact backend-owned request terms. It uses the existing
+CLI signer and the SDK fulfillment API. Organization payment requires the
+selected Permission; the backend checks Budget and spending authority. The
+command publishes prepared Payment IDs before signing. A submitted Payment
+is not a settled Payment. Use the printed get/wait commands to inspect its state.
+
+A lost reply or timeout gives exact readback in the same session and scope.
+Pay refuses an already prepared Invoice unless you explicitly use `--resume`
+after readback. Resumption must retain its linked Payment ID and original
+Invoice terms. It does not create another request or Payment. Use
+`--timeout-seconds N` to change the bounded signing wait (default 120).
+An Invoice retains its issued instruction. A generic request uses a deterministic
+Memo instruction. Reading terms creates no Payment or document. Fulfillment
+checks those terms again and stores the Memo with the original request birth.
+
+## Payment documents
+
+```sh
+capxul document get --document-hash H --content-hash C --json
+capxul document verify --document-hash H --content-hash C --json
+capxul document render --document-hash H --content-hash C
+capxul document render --document-hash H --content-hash C --output-dir ./documents --json
+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 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
+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.
+
+Only `document render` and `document export` write files. Reads name each
+document with the `document render` command that saves it: Payment `get`, `wait`
+and `list`, Activity detail, Payroll `get` and `wait`. Writes save nothing either.
+Payment `send` and `retry`, Payroll `run` and Inbox `pay` end with
+`Save the receipt: capxul document render …` once the receipt exists, and
+`request issue` prints that command for each document it issued. No write
+result carries document output. A document that is still pending is named by
+`payment get`.
+
+## Contact commands
+
+```sh
+capxul contact list [--include-hidden]
+capxul contact get PARTY_ID
+capxul contact add --input FILE|- [--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
+```
+
+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 by its ID.
+
+`add --input` reads the existing `AddressBookAddInput` JSON shape. For example:
+
+```json
+{
+  "ref": { "kind": "email", "email": "supplier@example.test" },
+  "label": "New Supplier"
+}
+```
+
+Use `--input -` to read the same object from stdin. An interactive `add` can
+collect the reference kind, value, and optional label instead. Interactive
+writes show the actor and exact contact change, then ask a default-no question.
+JSON, CI, and other noninteractive writes require `--confirm` before the CLI
+creates a client. Contact writes do not start a browser signer.
+
+Success data is the SDK value without a CLI wrapper: `list` returns
+`AddressBookEntry[]`, `get` returns `AddressBookEntry | null`, and each mutation
+returns `AddressBookEntry`. Human `get` prints `No contact found` for null and
+exits successfully. Entries retain their stable PartyId, exact reference,
+relationships, hidden state, and last activity time.
+
+## Personal Account reads
+
+```bash
+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. `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 setup finishes in the Capxul web app, not in the CLI: it creates your
+wallet, which needs you in a browser, and the CLI never opens one. `account retry`
+reads your Account; when it is not ready, it prints the web app link. Run it again
+to check: it returns the same handover until the Account is ready.
+
+## Organization commands
+
+```sh
+capxul org list --json
+capxul org show --org acme --json
+capxul org show --json
+capxul org me --json
+capxul org member list --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. `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
+includes unfinished founder setups. This works from a clean authenticated home.
+Interactive status/wait offers a choice when several unfinished setups exist.
+Scripted and JSON reads require an exact --org in that case. A ready
+Organization must still appear in current access.
+
+Human output shows Organization identity and setup, with a separate unfinished
+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 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
+has a scheduled next check. It stops at ready, failed, awaitingAuthorization,
+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 reads
+
+```sh
+capxul payment list --org O [--json]
+capxul payment get P --org O [--json]
+capxul payment wait P --org O [--timeout-seconds N] [--json]
+```
+
+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.
+
+Wait observes the exact Organization and Payment through the SDK subscription.
+It stops on a terminal state, required action, or required retry. The timeout
+accepts 1 to 3600 seconds and defaults to 120. It covers session restoration
+and observation. Deadline exit 5 and interruption exit 130 retain read/wait
+instructions with both Organization and Payment IDs.
+
+## Organization Payment retry
+
+```sh
+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. 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 B [--org O] [--json]
+capxul org permission create --org O --input budget.json --request-key K [--wait] [--json]
+capxul org permission change B --org O --input budget.json --request-key K [--wait] [--json]
+```
+
+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.
+
+Human output shows Permission and assignment IDs, revisions, and states.
+Budget output labels the exact per-payment cap or no cap. It does not show a
+remaining balance. JSON preserves the public SDK result.
+
+Every Budget write supplies the complete policy:
+
+```json
+{
+  "type": "budget",
+  "asset": "A",
+  "limit": { "asset": "A", "value": "500" },
+  "scope": {
+    "recipients": { "type": "allowlist", "accounts": ["account_alice"] },
+    "actions": ["pay"]
+  },
+  "refill": "monthly"
+}
+```
+
+Use an exact admitted AssetId for `A`. The cap must be positive and finite.
+`refill` is `monthly`, which refills the cap every 30 days (a fixed period from
+the block that sets it, not a calendar month), or `none`. A create without
+`refill` means `none`. A change without `refill` keeps the Budget's current
+refill; write `"refill": "none"` to turn a refill off.
+Recipients are `anyone` or 1 to 32 unique Account IDs. Actions are `pay`,
+`commitments`, or both. `pay` covers single and batch Payments. Missing scope,
+duplicate recipients/actions, unknown fields, and an asset mismatch refuse.
+A Budget change keeps its asset. Management input is `{"type":"managePeople"}`.
+Use `--input -` for stdin. Input is limited to 64 KiB.
+
+A human terminal can guide policy input. Change prefills the exact active
+revision's complete stored policy. Every Permission write (`create`, `change`,
+`assign`, `revoke`, `replace`) goes through the approval page, as `payment
+send` does: the preview shows all before/after rights and any allowance reset,
+then the CLI prepares the command, records the verified prepared IDs, compares
+the frozen policy with the preview, and opens the approval. If the policy
+changed, nothing opens and the prepared command is closed. A person sees
+`✓ Prepared`, `… Approve in your browser` and the link; the page is the one and
+only confirmation, and the CLI follows it to `✓ Signed`. A rejection on the
+page is `cancelled` (exit 130). With `--json` the command returns at once with
+`status: "awaiting_approval"`, `approvalUrl` and `next.argv` for
+`payment wait <approval id> --org O`. A missing human key is generated and
+printed before the first write. Scripted runs require `--request-key`.
+
+Success means sent and pending application. It does not prove active rights.
+Add `--wait` to follow it through, as `org permission command wait` does: after
+you approve it, the CLI follows the command until it is applied (`✓ Confirmed`),
+failed or needs action. The result then also holds `command`, the command's view
+(`status` is `applied`, `failed` or `actionable`), and exits 0 in each case;
+read `status`. `--json --wait` writes the approval link to stderr as one
+`approval.awaiting` event and returns once it is followed through.
+`--timeout-seconds` bounds how long the CLI follows it (default: until the
+approval lapses). A follow that runs out of time fails with exit 5 and names the
+wait command. The same write run again with a request key whose command was
+already sent opens no approval and shows no link: it reads the command and
+prints `Already applied: …` (or where it stands), with the command's view in
+`command`. After an interruption or uncertain result, retain the original
+input, Organization ID, key, command ID, and execution ID. The key alone cannot
+restore wizard/stdin input.
+
+`org permission replace --org O --request-key K` replaces the current
+Roles module and carries its active Permissions, assignments, and admitted
+Invitation rights. Human mode guides missing scope and shows the full frozen
+before/after snapshot, then hands over to the approval page. Machine mode
+requires scope and key. A changed snapshot opens no approval. Unfinished Invitation configuration must complete or cancel first.
+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 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 [--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
+canonical `partyId`, draft `amount` text, and `currency`. An optional `id`
+updates that exact group. These commands do not sign or transfer money.
+Group amounts stay unchanged, including unfinished draft text. They do not
+supply payout quantities or currency conversion. A lost create response must
+be reconciled with the same scoped group list before another create.
+
+Terms retain raw rates, decimals, units, and effective dates. Run listing
+retains the backend `settledThisMonth` aggregate. The CLI does not sum a partial
+run page or compute earned pay.
+
+Run input contains `permissionId`, `asset`, `period`, and ordered `items`.
+Each item supplies a recipient Ref, asserted `partyId`, settlement `amount`,
+raw-unit `gross` and `net`, and signed `adjustments`. Net must equal the exact
+settlement quantity and gross plus adjustments. Keep Organization, actor, signer,
+and request-key routing outside the JSON. `--input -` reads bounded stdin.
+The current Payroll producer accepts email and Party Refs. Other Ref kinds
+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. 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.
+`--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
+waiting through partial settlement and ends when all Payments settle, a failure
+is recorded, or action is required. Timeout exits 5. Cancellation exits 130.
+Recovery retains exact Organization, run, and any observed request key.
+
+## Invitation commands
+
+```sh
+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]
+```
+
+`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.
+
+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.
+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 `get` command for the offer with the resolved session. Read the current
+offer before another transition; a lost response does not authorize replay.
+
+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 no request key. A noninteractive write requires `--request-key`. Every
+run prints the request key it used before it prepares, so a lost response is
+recoverable with the same identity. The write authors the invitation, prepares
+the configuration that sets up its offered rights, and hands over to the
+approval page, as `payment send` does: a person sees the preview, `✓ Prepared`,
+`… Approve in your browser` and the link, the CLI follows it to `✓ Signed`, and
+it prints the invitation as it stands. With `--json` it returns at once with
+`status: "awaiting_approval"`, `approvalUrl` and `next.argv` for
+`payment wait <approval id> --org O`. A request key whose invitation is already
+set up returns that invitation. At most one `--new-budget-name` is accepted per
+command.
+
+`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
+digest from the value it displayed. A digest you state is never replaced by the
+displayed one. `--expected-offer` remains a compatibility spelling, and both
+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.
+
+## Organization writes
+
+org create and org retry use the protected current session unless --email names
+one. A JSON or noninteractive write requires --confirm. A terminal write shows
+the current Organization and recovery information, then asks a default-no
+question. The signer starts after confirmation.
+
+`org create --wizard` guides name, handle, country, optional bio and size, then
+session email. Supplied flags remain in the generated command. The final write
+preview names the verified actor and starts with No selected.
+`org retry --wizard` collects the exact Organization ID before session email.
+Its final preview shows the verified actor and current lifecycle. Saved read
+defaults and creation recovery records cannot change that retry ID.
+
+org create validates name, handle, and country before client work. It calls
+onboarding.beginOrganization, saves and prints the exact Organization ID,
+authorizes only an awaitingAuthorization setup, then subscribes to setup
+changes. It reports success only after ready and current access. JSON progress
+uses one line per state:
+
+    { "type": "organization.lifecycle", "organizationId": "O", "status": "processing" }
+
+org retry requires one exact --org. It authorizes only awaitingAuthorization.
+For an accepted setup it asks the backend to check the same operation hash
+through setup.resume, then subscribes. Neither command replaces a submitted
+operation. The local recovery record keeps a safe handle and Organization ID
+for convenience; the backend unfinished list supports recovery without it.
+
+--timeout-seconds sets one 1-to-3600-second deadline for the command. A
+deadline stops local work and returns exit 5. If the last observed setup has
+another automatic check scheduled, the message is "Stopped waiting.
+Organization setup continues in the background." Before acceptance or without
+a scheduled check, the message is "Stopped waiting. Read the Organization
+setup status." The error details include the safe Organization ID when known,
+last observed setup state, setup reason, and bounded provider diagnostics.
+Ctrl-C stops local work at exit 130. Neither stop writes a backend failure.
+
 ## Configuration
 
-| Variable                       | Use                                                                                                          |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
-| `CAPXUL_CLI_HOME`              | Directory for global CLI settings. Defaults to `$XDG_CONFIG_HOME/capxul/cli`, or `$HOME/.config/capxul/cli`. |
-| `CAPXUL_PUBLISHABLE_KEY`       | Application publishable key, required for an online check.                                                   |
-| `CAPXUL_BOOTSTRAP_URL`         | Bootstrap origin. Defaults to `https://api.staging.capxul.com`. Convex Cloud origins are rejected.           |
-| `CAPXUL_POSTHOG_HOST`          | Optional development override for the built-in public PostHog ingestion origin.                              |
-| `CAPXUL_POSTHOG_PROJECT_TOKEN` | Optional development override for the built-in public project ingestion token.                               |
-| `CAPXUL_TELEMETRY_DISABLED`    | Set to `true` to disable remote observation regardless of the saved preference.                              |
-
-The published CLI includes Capxul-owned public ingestion configuration. You do
-not need PostHog environment variables. Collection defaults to enabled for
+| Variable                          | Use                                                                                                                                                                                   |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CAPXUL_CLI_HOME`                 | Directory for global CLI settings. Defaults to `$XDG_CONFIG_HOME/capxul/cli`, or `$HOME/.config/capxul/cli`.                                                                          |
+| `CAPXUL_PUBLISHABLE_KEY`          | Optional developer override for the bundled first-party staging key.                                                                                                                  |
+| `CAPXUL_ENV`                      | Environment for this process: `staging` or `devnet`. Beats `CAPXUL_BOOTSTRAP_URL` and the saved `use env`; `--env` beats it.                                                          |
+| `CAPXUL_BOOTSTRAP_URL`            | Bootstrap origin. Defaults to `https://api.staging.capxul.com`. Convex Cloud origins are rejected.                                                                                    |
+| `CAPXUL_CHECKOUT_FRONTEND_ORIGIN` | Checkout frontend origin. Staging uses `https://app.staging.capxul.com`. Devnet at `http://127.0.0.1:3211` uses `http://127.0.0.1:3002`. Custom bootstrap origins require this value. |
+| `CAPXUL_POSTHOG_HOST`             | Optional development override for the built-in public PostHog ingestion origin.                                                                                                       |
+| `CAPXUL_POSTHOG_PROJECT_TOKEN`    | Optional development override for the built-in public project ingestion token.                                                                                                        |
+| `CAPXUL_TELEMETRY_DISABLED`       | Set to `true` to disable remote observation regardless of the saved preference.                                                                                                       |
+
+The published CLI includes the verified first-party staging application key and
+Capxul-owned public ingestion configuration. You do not need key or PostHog
+environment variables. A different bootstrap origin requires an explicit key. Collection defaults to enabled for
 ordinary local and online commands, help, version, and safely attributed argument
 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.
@@ -59,8 +857,68 @@ unsafe permissions, symlinks, and corrupt state produce a storage failure.
 
 ## Output
 
-`--json` writes one version 1 envelope to stdout. Success contains `data`.
-Failure contains `error.code` and CLI-owned `error.message`. Each envelope has
+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` 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. A list whose next cursor would show the same page again fails with
+exit 1 and `The list did not advance past the cursor <cursor>`, so a paging loop
+ends. `--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, and so does a typo: a name the result lacks that is a
+letter or two off a name it has (exit 2, `field: "fields"`); the message names it, the
+closest real field and the fields in this result. Any other name the result lacks, such as
+an optional `execution` on a Payment that has none, is left out, as `jq` would.
+The commands that move money (`payment send`, `payment retry`, `payment cancel`,
+`payment redirect`, `inbox pay`,
+`org payroll run`) check the names against the result they declare before they
+run, so a typo never costs an approval: `status`, `approvalId`, `approvalUrl`,
+`paymentIds`, `expiresAt` and `next`.
+
+A failure contains `error`:
+
+```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), then a dim last line, `ref <id>`, for
+support:
+
+```text
+✗ Unknown command "paymnt". Did you mean: capxul payment list
+✗ Not signed in. Try: capxul auth login
+ref 6a0e10d1-06fb-4eed-9c2a-1f6f0c2b7d11
+```
+
+The `ref` is the backend's request ID when the error carries one, else its
+correlation ID, else this run's `invocationId`. A mistyped command has none,
+because no command started. An error that already quotes its request ID in its
+sentence (a redacted backend error) has no `ref` line. JSON output has no `ref`
+line and is unchanged: read `error.details.requestId` or `invocationId`.
+
+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
+the result. These fields remain available when collection is off or
+`--log-level none` is set. Each envelope has
 `command`, `invocationId`, and `outcome`. An invocation ID is null before a
 command starts. Human errors go to stderr.
 
@@ -109,15 +967,295 @@ compinit
 Use `npm update -g @capxul/cli` or `brew upgrade xelmar-tech/tap/capxul` to update.
 Use one installer for the `capxul` executable to avoid conflicting PATH entries.
 
+After a successful human command, help, or version request, the CLI can show an
+update notice on terminal stderr. It checks the public npm `latest` tag at most
+once per 24 hours. It shows only the command for the verified running npm-global
+or Homebrew installation. It does not execute that command. Unknown installations,
+development versions, JSON output, redirected stderr, CI, shell completion, and
+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 `cli-journeys` job in
+`.github/workflows/devnet-integration.yml` starts the DevNet and runs it.
+
 ## Development commands
 
 ```sh
 vp test run apps/cli
 vp run --filter @capxul/cli check-types
+vp run --filter @capxul/cli lint
 vp run --filter @capxul/cli build
-vp exec node --test --test-name-pattern='@capxul/cli' scripts/__tests__/pack-install-smoke.test.mjs
+vp exec node --test --test-name-pattern='@capxul/cli' packages/tools/src/modules/release/release.pack-install.test.mjs
 ```
 
 The last command installs the tarball outside the workspace and exercises the
 installed executable with isolated settings and a local HTTP server. The CI
 `CLI / Linux / Node 24.0.0` job runs this proof at the declared minimum version.
+
+## Email login and session restoration
+
+This CLI establishes a first-party BetterAuth session. An older native
+`account:read` grant does not count as sign-in and cannot read the profile.
+Logout clears the selected email's session and attempts to revoke any native
+grant that was stored before the first-party flow replaced it.
+
+On a terminal, `auth login` is a wizard. It 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.
+
+`auth login` and `account retry` never open a browser, in any output mode. When
+your Account is not set up, they print where to finish it:
+
+```text
+Signed in as person@example.com.
+Account setup required.
+Finish setting up your Account in your browser, signed in as person@example.com:
+  https://app.staging.capxul.com/
+Then check it with: capxul account retry --email 'person@example.com'
+```
+
+With `--json`, `data` carries the same handover:
+`setupState: "setup-required"`, `status: "awaiting_setup"`, `setupUrl` and
+`next.argv` (`["capxul", "account", "retry", "--email", EMAIL, "--json"]`, with the
+`--org` and `--env` you typed). That read exits 0 and returns the handover again,
+or the ready report. `capxul schema auth login` declares the shape.
+
+Ctrl+C or Ctrl+D at a wizard prompt cancels the command. The command prints no
+success result and exits 130. A step that already finished keeps its result: a
+completed sign-in keeps its session.
+
+For an agent, send and verify in separate processes:
+
+```sh
+capxul auth login --email "$TEST_EMAIL" --json
+# The code from the email, as an argument or on stdin with --otp-stdin.
+capxul auth verify "$CODE" --json
+# A later process uses the same protected CLI home; no new code is required.
+capxul whoami --json
+capxul auth logout --json
+```
+
+After sending a code, the output names `capxul auth verify <code>`. If
+verification has no waiting sign-in, the error names `capxul auth login`.
+Neither command prints the code itself.
+
+Human profile/status output labels your Profile fields and available Account,
+wallet and Smart Account identifiers. Failed setup includes its stage and error
+code. These reads do not open the wallet browser. `--json` retains the structured
+result, including the same Profile and lifecycle values.
+
+A machine run never prompts. `auth login` with `--otp-stdin` sends the OTP and
+verifies one code from stdin. It returns the profile report, with the setup
+handover when the Account is not ready. It starts no setup work.
+
+`--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.
+Only `auth verify <code>` accepts a code as an argument: the code is single-use
+and expires in minutes. Codes are never persisted or included in output.
+
+`setupState: "ready"` is a personal Account that the Account readiness owner
+reads as ready and deployed. Its data carries the public identifiers: the
+Profile, the public wallet address (`smartAccount.signerAddress`), the personal
+Smart Account address (`smartAccount.smartAccountAddress`), the Account ID
+(`lifecycle.accountId`), and the ready status. Any other state is
+`setupState: "setup-required"` with the lifecycle, its failure code, and the
+handover above.
+
+A ready personal Account continues the same journey into Organization creation
+with `capxul org create --name NAME --handle HANDLE --country CC`. The create
+command records the safe recovery handle for that Organization, so an
+interruption or a restart resumes the exact same Organization.
+
+The version 2 `first-party-session` record stores the opaque provider credential
+in the existing protected plaintext store. Its scope includes the application
+key, issuer, environment, and email. Each process validates restoration with the
+backend; cached session data is not authority. Conditional replacement prevents
+a concurrent logout from being undone by a delayed credential save. The backend
+owns expiry and revocation. A failed remote logout is reported as `unconfirmed`;
+local sign-out remains in effect.
+
+`account show` returns a backend-read Profile and account lifecycle without opening
+the browser. Successful email authentication can return `setupState: "setup-required"`.
+`account retry` returns `setupState: "ready"` only after Core reads a ready Account;
+otherwise it returns the web app handover.
+After logout, profile reads refuse with `NOT_AUTHENTICATED` and exit 3. An invalid
+or expired OTP refuses with exit 2.
+
+Find where to finish an incomplete personal Account:
+
+```sh
+capxul account retry --email you@example.com
+```
+
+It writes nothing and opens no browser. Missing Account or Profile state in other
+commands directs to `account retry`.
+
+Read an Organization treasury or deposit target:
+
+```sh
+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
+backend treasury access. Deposit instructions use the public SDK's own-access
+projection. Neither command starts a signer or changes Organization setup.
+
+Contact reads show the selected scope, label, full Party ID, reference,
+relationships and hidden state. JSON keeps the existing array, entry or null.
+
+```sh
+capxul contact list --include-hidden
+capxul contact get party_example
+capxul contact get --org org_example --wizard
+```
+
+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.
+
+Contact add shows the reference and optional label before terminal confirmation.
+Without an input file, the wizard asks for these values. On an uncertain response,
+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 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 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 the ID. It confirms the change and shows the visible
+contact. Scripts provide the exact Party ID and `--confirm`.
+
+## Fixed offers
+
+Manage fixed service offers in your personal Account or an explicit Organization.
+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
+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
+```
+
+Add `--org ORG_ID` to run any of these as an Organization. Use `--email`
+to select a saved session. Scripts must supply `--confirm` for each write.
+A terminal shows the proposed change and asks for confirmation. Use `--json`
+for structured output. Lists and reads create no PDF.
+
+The input file contains the complete offer terms. Use `--input -` to read stdin.
+The input limit is 64 KiB. Supply an admitted Base Sepolia asset ID from the
+existing asset catalog. Amounts use exact decimal strings. Quantity limits use
+positive whole numbers.
+
+```json
+{
+  "title": "Consulting",
+  "description": "One hour of consulting",
+  "unitLabel": "hour",
+  "unitAmount": { "asset": "ASSET_ID", "value": "12" },
+  "quantity": { "min": 1, "max": 8 }
+}
+```
+
+Creation requires an explicit replay key. Keep the key and identical terms when
+recovering an uncertain result. Read the offer list before another write. Revision
+and deactivation require the revision you observed. A conflict requires a fresh
+read. The CLI does not retry a write automatically. Successful offer results
+include `checkoutUrl`. Share that URL for another purchase of the same offer.
+An offer link is not a saved purchase or proof of payment.
+
+The checkout page reads the current offer before the payer continues. A quantity
+in the URL is a hint. The backend checks its bounds and freezes the selected
+revision, quantity, price, asset, network, and recipient for that purchase.
+Changing the URL cannot change a saved purchase. Refresh retains its checkout
+reference. Separate purchasers receive separate checkout and settlement IDs.
+
+## Request and document flow
+
+Alice issues a basic request or an Invoice to Bob with `request issue`. For an Organization issuer,
+Alice uses `request issue --org ORGANIZATION_ID`. Issuance returns the request ID,
+document references, and checkout URL. Alice saves her PDF with the printed
+`document render` command.
+Bob runs `inbox list`, then `inbox get REQUEST_ID`. An Organization
+payer uses the same `inbox` commands with `--org`.
+
+Bob's Inbox contains the request and document references. Bob uses the printed
+`document render` command to save his copy. Both participants read the same verified document. Their files can
+have different local paths. The home screen (`capxul`) shows how many requests wait
+for you; it does not download documents.
+
+A direct Payment uses the existing Payment and Activity commands. Alice inspects
+her outgoing records. Bob inspects his incoming records after the backend observes
+them. Available document references can then be rendered by an authorized
+participant. Issuance, signing, submission, and settlement are separate states.
+A PDF file or checkout link does not prove that funds moved.
+
+Cancellation removes the request from the received Inbox list. Because `inbox get`
+reads that list, it cannot find the cancelled ID. Existing participant document
+access remains available through the saved document and content hashes. Keep
+those references when retaining a cancelled Invoice.
+
+The shared document directory is `documents` next to the CLI settings directory.
+`CAPXUL_CLI_HOME` selects a separate CLI settings directory. `document render
+--output-dir` changes the document output location. Each render preserves
+previous files. A failed PDF render does not repeat issuance or payment. Retry
+`document render` with the existing document references.
+
+## Checkout links
+
+A basic request URL has the form `/checkout/requests/LINK_TOKEN`. Existing Invoice
+URLs use `/checkout/invoices/LINK_TOKEN`. An offer URL uses `/checkout/offers/OFFER_ID`. Use the complete `checkoutUrl` returned by the
+CLI. Do not build a payment by sending funds directly to the printed Safe.
+
+A valid request link holder can fund its fixed obligation. The named debtor and
+actual sender remain separate. Public checkout shows the approved payment
+summary. It does not expose private billing details or original document bytes.
+Only authorized participants can open the private Invoice document.
+
+The checkout page offers registered Account or Organization funding and supported
+external wallet funding. Registered funding uses the selected actor's authority.
+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` 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.