@capxul/cli 4.20.0-beta.11 → 4.20.0-beta.12

package/README.md

@@ -24,6 +24,119 @@ machinery and collection controls send no observation records.
 check uses the public Capxul SDK and verifies the backend response nonce.
 It does not authenticate a person or submit a transaction.
 
+## 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.
+
+## 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.
+
+## 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 > document.html
+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 the original base64 bytes and document metadata in JSON. `verify`
+reports `ok: false` when verification fails. `render` writes the SDK HTML
+exactly to standard output. `export` writes the original bytes to a new file.
+It refuses an existing output file.
+
 ## Contact commands
 
 ```sh
@@ -69,6 +182,20 @@ 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
@@ -92,11 +219,22 @@ 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.
-If more than one Organization is possible, give an exact --org. A ready
+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.
 
-org use saves a protected per-person read default. The default grants no
-authority. Member lookup uses an exact AccountId. Reads do not sign or change
+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
@@ -105,6 +243,187 @@ 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 V3 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
@@ -135,8 +454,35 @@ 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.
 
-`org invite wait` only reads. It finishes when the offer settles or when the
-recovery asks a person to act. It never retries, resends, or accepts.
+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.
@@ -172,6 +518,13 @@ 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
@@ -234,6 +587,14 @@ unsafe permissions, symlinks, and corrupt state produce a storage failure.
 
 ## Output
 
+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
@@ -304,6 +665,7 @@ silent and do not change the command result. This check sends no telemetry.
 ```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
 ```
@@ -314,11 +676,10 @@ installed executable with isolated settings and a local HTTP server. The CI
 
 ## Email login and session restoration
 
-This CLI establishes a first-party BetterAuth session. It has broader authority
-than the earlier native `account:read` grant. Existing native grants remain
-stored and tagged as `legacy-native-grant` in status. A profile read asks for an
-explicit new login; it never exchanges the old grant for a broader session.
-Logout forgets and attempts to revoke both credential types for the selected email.
+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
@@ -349,6 +710,20 @@ 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
@@ -411,3 +786,58 @@ the browser. Successful email authentication can return `setupState: "setup-requ
 `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`.