@capxul/cli 4.20.0-beta.2 → 4.20.0-beta.20

package/README.md

@@ -1,7 +1,9 @@
 # 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, terminal-owned
+signup, personal and Organization contacts, a bundled Openfort wallet page,
+backend profile and account reads, diagnostics, and one global collection
+preference. It requires Node 24 or later on macOS or Linux.
 
 ```sh
 capxul --help
@@ -14,27 +16,727 @@ capxul telemetry enable --json
 capxul doctor --online --timeout-ms 30000 --json
 ```
 
-Help, version, and completion do not read configuration or contact a server.
+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.
 
+## 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 org 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.
+
+## Status overview
+
+```sh
+capxul status
+capxul status --email EMAIL --json
+capxul status --org ORGANIZATION_ID
+```
+
+`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.
+
+## 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 list --json
+capxul payment get --payment-id PAYMENT_ID --json
+capxul payment wait --payment-id 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.
+
+`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.
+
+## 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 REQUEST_ID
+capxul request cancel --request-id 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
+```
+
+`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
+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.
+
+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.
+
+The [installed beta18 audit](../../docs/planning/checkout-cli/request-read-contract.md#installed-beta18-local-audit-c06)
+records local help, refusal, and cancellation checks. Authenticated request
+reads, document output, issuance, and payment remain 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 an Invoice request JSON object from `--input FILE` or `--input -`.
+It saves the issued Invoice PDF in the common document directory by default.
+Human and JSON output include `checkoutUrl` for an Invoice instruction with a link token.
+Memo requests do not receive an Invoice checkout URL.
+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.
+Use `--output-dir DIRECTORY` to change that location. A PDF failure retains the
+issued request and its document references. Do not issue it again to retry PDF
+output; use the printed document render command.
+
+```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" }]
+  }
+}
+```
+
+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.
+Returned documents use the same default PDF directory.
+
+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 saves a PDF. It 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.
+
+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.
+
+## Contact commands
+
+```sh
+capxul contact list [--include-hidden]
+capxul contact get --entry-id 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]
+```
+
+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
+`--include-hidden` is present. `get`, `label`, `hide`, and `unhide` address one
+stable Party with `--entry-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 status --email person@example.com
+capxul account balance --json
+capxul account deposit --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.
+
+## Organization commands
+
+```sh
+capxul org list --json
+capxul org use --org ORGANIZATION_ID
+capxul org status --org ORGANIZATION_ID --json
+capxul org get --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 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.
+
+A read without --org uses the saved read default, 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.
+
+org use saves a protected per-person read default. Without --org, an interactive
+use command offers current accessible Organizations and ignores the old default.
+A scripted use requires --org. The default grants no
+authority. 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
+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 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]
+```
+
+These commands require an explicit Organization. They do not use the saved
+read default. 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 org payment retry --org O --payment-id P --confirm --json
+capxul org payment retry
+```
+
+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.
+
+## Permissions
+
+```sh
+capxul org permission list [--org O] [--json]
+capxul org permission get --permission-id 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]
+```
+
+These commands use the explicit Organization, then the protected read default.
+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"]
+  }
+}
+```
+
+Use an exact admitted AssetId for `A`. The cap must be positive and finite.
+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. The preview shows all before/after rights
+and any allowance reset before one default-no confirmation. The CLI then records
+verified prepared IDs and compares the frozen policy with that confirmation.
+If it changed, the CLI refuses before signing. A missing human key is generated
+and printed before the first write. Scripted runs require `--request-key` and
+`--confirm`.
+
+Success means submitted and pending application. It does not prove active
+rights. 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 --confirm` 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 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.
+
+## 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 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]
+```
+
+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. One
+default-no approval precedes signing, including when `--confirm` is supplied.
+Machine runs require exact scope, input, key, and `--confirm`.
+
+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.
+
+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 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]
+```
+
+`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.
+
+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.
+
+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.
+
+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.
+
+`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.
+
+`org member invite` authorizes one exact offer. `--preview` writes nothing and
+needs neither a request key nor confirmation. A noninteractive write requires
+`--request-key` and `--confirm`. An interactive run prints the request key it
+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
+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. The
+returned view is the authorization-time view of the consent commit
+(`pending_grant`); read the settled `active` state with `get` or `wait`.
+
+## 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`          | PostHog ingestion origin.                                                                                    |
-| `CAPXUL_POSTHOG_PROJECT_TOKEN` | Project ingestion token. Both PostHog variables are required for export.                                     |
-| `CAPXUL_TELEMETRY_DISABLED`    | Set to `true` to disable remote observation regardless of the saved preference.                              |
+| 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_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.                                                                                                       |
 
-Collection defaults to enabled. Local commands send no remote signals.
+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
 remote event. Already running CLI processes check the current preference before
 each export. Requests already sent cannot be recalled. `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.
+
+Eligible commands reuse a random anonymous identifier stored in the protected
+CLI directory. Invocation and trace identifiers remain separate. A first-use
+marker records the first eligible observed use, not a download or a verified
+person. If this state cannot be accessed safely, observation stops and the
+command retains its normal result. Delivery is bounded and best-effort; the CLI
+does not keep a persistent activity queue.
 
 Settings use a versioned JSON file in a directory with mode `0700`. The file has
 mode `0600`. Writes are atomic and serialize between processes. A later writer
@@ -43,8 +745,22 @@ 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 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`, 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
+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.
 
@@ -93,11 +809,21 @@ 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.
+
 ## 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
 ```
@@ -105,3 +831,211 @@ vp exec node --test --test-name-pattern='@capxul/cli' scripts/__tests__/pack-ins
 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.
+
+`capxul auth login` and `capxul auth signup` 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
+for the Profile fields: display name, two-letter country code, and handle. A
+known value is the prompt default, so Enter keeps it.
+
+The browser opens only when the shared Core onboarding journey needs Openfort
+wallet readiness. It shows wallet status only. It has no email, OTP, Profile, or
+approval form.
+
+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 send --email "$TEST_EMAIL" --json
+# Supply the delivered six-digit OTP through stdin, not a command argument.
+capxul auth verify --email "$TEST_EMAIL" --otp-stdin --json
+capxul auth profile --email "$TEST_EMAIL" --json
+# A later process uses the same protected CLI home; no new OTP is required.
+capxul auth profile --email "$TEST_EMAIL" --json
+capxul auth status --email "$TEST_EMAIL" --json
+capxul auth logout --email "$TEST_EMAIL" --json
+```
+
+After sending a code, human output includes the exact verification command with
+your email safely quoted. If verification has no pending code, the error gives
+the exact command to request one. Neither command includes the OTP 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
+same protected CLI home to resume the saved session. Explicit access/input
+refusals and non-retryable failures require their stated correction first.
+
+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 tagged result
+`setupState: "setup-required"` when the account needs setup. It does not start
+setup work, so sign-in never becomes signup.
+
+A fresh machine signup does verification and setup in one command. State every
+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 \
+  --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. A missing `--otp-stdin` refuses with exit 2 before the command starts client
+work. OTPs are never accepted in argv, persisted in the 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
+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
+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
+(`smartAccount.smartAccountAddress`), the Account ID
+(`lifecycle.accountId`), and the ready status. Any other state returns the typed
+recoverable result `setupState: "setup-required"`, with the lifecycle, its
+failure code, and the command that resumes the journey. A ready Account starts
+no wallet work, so a retry keeps the one Profile, wallet, Smart Account, and
+Account. An interruption keeps the stored session and stores no code, so the
+next command resumes the same setup.
+
+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 CLI checks `--display-name`, `--country`, and `--handle` before it opens a
+client, so a malformed value refuses with exit 2 and no code is sent. The handle
+check covers the grammar only: a handle that another person holds, and a reserved
+handle, refuse through the identity owner after sign-in. Both refusals name the
+handle, and neither offers verification-code recovery for a Profile problem.
+
+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.
+
+`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.
+After logout, profile reads refuse with `NOT_AUTHENTICATED` and exit 3. An invalid
+or expired OTP refuses with exit 2.
+
+Resume an existing personal Account after incomplete setup:
+
+```sh
+capxul account retry --email you@example.com --confirm --timeout-seconds 120
+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`
+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
+```
+
+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 --entry-id party_example
+capxul org contact get --org org_example --wizard
+```
+
+In a terminal, omit `--entry-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 --entry-id 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.
+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
+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 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
+```
+
+Use `org offer` and `--org ORG_ID` for each Organization command. 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. Checkout links are not emitted
+until the checkout route works.