@attocash/cli 0.1.0

package/README.md

@@ -0,0 +1,707 @@
+# Atto CLI
+
+`@attocash/cli` provides the `atto` terminal wallet and the shared wallet engine
+used by [`@attocash/mcp`](https://github.com/attocash/integrations/tree/main/atto-mcp).
+Protocol signing and publication use [Atto Commons](https://github.com/attocash/commons).
+The CLI and MCP use the same password-store entry, public state, and spending
+budgets when run with the same data directory.
+
+## Install
+
+Requires **Node.js 24.15 or newer**. From the repository root:
+
+```sh
+npm ci
+npm run pack
+npm install --global ./attocash-cli-0.1.0.tgz
+atto --help
+```
+
+The CLI can be installed on its own. To install MCP as well before these package
+versions are published, install both local artifacts in one command:
+
+```sh
+npm install --global ./attocash-cli-0.1.0.tgz ./attocash-mcp-0.1.0.tgz
+```
+
+Use `npm run pack` from the repository root to create the supported artifacts.
+See the [repository packaging notes](https://github.com/attocash/integrations#packaging)
+for dependency locking and installed-package verification.
+
+Linux also requires `secret-tool` (usually the `libsecret-tools` package), an
+unlocked Secret Service provider such as GNOME Keyring or KWallet, and access to
+your desktop D-Bus session. macOS uses Keychain; Windows uses Credential Manager.
+An unavailable password store is an error; there is no plaintext file fallback.
+
+## Update notices
+
+Interactive CLI commands can show a notice on stderr when a newer stable CLI
+version is available. The notice includes the exact installation command;
+updates are always manual. Version checks run in the background, with each
+attempt cached for 24 hours, including failed attempts. Their results appear
+on a later command. Network and cache failures are silent.
+
+Use `--no-update-notifier` or set `NO_UPDATE_NOTIFIER` to disable notices and
+checks. They are also disabled with `--json`, redirected stdout or stderr,
+CI, or `NODE_ENV=test`. MCP and the `@attocash/cli/core` library do not check
+for updates or display notices.
+
+Checks request public package metadata from the npm registry and send no wallet
+data. The cache contains only public version information and timestamps,
+separately from wallet state:
+
+| OS | Update cache |
+| --- | --- |
+| Linux | `$XDG_CACHE_HOME/atto-cli/update.json`, or `~/.cache/atto-cli/update.json` |
+| macOS | `~/Library/Caches/atto-cli/update.json` |
+| Windows | `%LOCALAPPDATA%/atto-cli/Cache/update.json`, or `~/AppData/Local/atto-cli/Cache/update.json` |
+
+Once a version is published, replace `VERSION` below with that version to
+update a global CLI installation:
+
+```sh
+npm install --global @attocash/cli@VERSION
+```
+
+If MCP is installed too, update the matching pair and restart the MCP process:
+
+```sh
+npm install --global @attocash/cli@VERSION @attocash/mcp@VERSION
+```
+
+## Set up the wallet
+
+Run either command in an interactive terminal:
+
+```sh
+atto wallet create
+# Or import an existing recovery phrase through a hidden prompt:
+atto wallet import
+```
+
+Creation stores the mnemonic successfully before displaying the recovery phrase.
+Keep a private offline copy. `atto wallet backup` displays it again in the
+terminal and adds a JSON confirmation only when `--json` is requested.
+Wallet creation, import, and backup require terminal input and terminal
+stderr; they are unavailable as MCP tools or through redirected pipes. Mnemonics
+are never accepted in command arguments, JSON, configuration, or environment variables.
+
+Import refuses an initialized wallet before asking for the recovery phrase. To
+replace it, back up its phrase and public profile, stop any CLI or MCP sessions
+using that profile, then run:
+
+```sh
+atto wallet reset
+atto wallet import
+```
+
+For a custom profile, pass the same `--data-dir` to both commands. Reset requires
+an interactive terminal and typing `reset` after reviewing the selected wallet.
+It removes that profile's password-store credential and clears local addresses,
+personal labels, pinned destinations, payment history, settings, spending limits, and access permissions. You need the saved
+recovery phrase and account indexes to access its funds again. Profile metadata
+and database lock files stay in place so the credential namespace and coordination
+remain stable.
+Other open sessions and unresolved payments prevent reset. If reset is interrupted,
+run it again to finish before creating or importing a wallet. After upgrading from
+a version without reset support, restart existing CLI/MCP processes before using
+this command.
+
+New standard CLI profiles use the **Atto CLI** password-store service. Existing
+legacy and custom profiles retain **Atto MCP** and their existing credential
+accounts; no keys are moved. Neither service reads or overwrites the desktop
+Atto wallet. See [profiles and recovery](#profiles-and-recovery) for directories
+and compatibility. Index `0` starts active. Deriving another
+index saves its public address; activating it includes it in default balance
+queries and automatic receiving. The network account opens on its first receive.
+At most 100 addresses can be active at once; deactivate one before activating
+another when that limit is reached.
+
+```sh
+atto wallet status
+atto address add
+atto address list
+atto balances
+atto balances --all
+```
+
+`address add` saves and activates the next index after the highest saved index.
+Use `address derive N` to save a specific inactive address, or `address activate N`
+to derive and activate one. Balances include active accounts by default;
+`--all` includes every saved address and `--index N` selects one. Saved accounts
+show their index and activation state alongside their balance.
+
+Defaults use the Atto wallet's LIVE endpoints and twelve-representative pool.
+Automatic receiving is enabled with a minimum of `1 RAW`. It runs while
+`atto wallet receive` is running. MCP also runs it when that profile
+has locally approved spending access; read-only MCP does not receive funds or
+make other wallet changes. Finite CLI commands do their requested operation and
+exit. Stop a persistent command with Ctrl+C.
+
+`wallet receive` reports pending payments, processing, confirmed receives, and
+retries as they happen, including the account index, amount, and transaction hashes.
+Connection errors are shown with their retry delay. `--json` emits the initial
+wallet status followed by one `result` object per progress event; its `event`
+field is `pending`, `receiving`, `received`, `retry`, `skipped`, or `reconnecting`.
+Subscriptions use Commons' streaming APIs. The CLI does not impose a deadline
+for the first payment or response headers. Finite list commands still stop at
+their requested collection deadline.
+
+```sh
+atto wallet receive
+atto wallet configure --no-auto-receive
+atto wallet configure --auto-receive
+atto wallet configure --representative <atto-address>
+```
+
+Configuration updates preserve omitted settings. Supply at least one option.
+`--representative` changes the default used to open accounts; use
+`atto representative change <address>` to change an existing account's representative.
+`wallet status` shows the profile directory and whether receiving runs in that
+process; it does not report receiving sessions in other terminals.
+
+To use another network, configure its node, work server, and representative
+explicitly. A network name alone does not replace the other settings:
+
+```sh
+atto wallet configure --network LOCAL \
+  --node-url http://127.0.0.1:8080 --worker-url http://127.0.0.1:8081 \
+  --representative <atto-address>
+```
+
+Endpoint URLs accept HTTP(S) without embedded credentials, query strings, or
+fragments. Pending uncertain sends must be resolved before changing the network
+or node endpoint.
+
+Settings are saved in `state.sqlite` inside the selected profile directory
+(normally `~/.local/share/atto-cli` on Linux), in the `settings` table's
+`settings` row. Its JSON contains `nodeUrl`, `workerUrl`, and the other wallet
+settings. Use `atto wallet status` to view them and `atto wallet configure`
+to change them.
+
+## Use the CLI
+
+Run `atto` to see the available commands. Incomplete command groups such as
+`atto wallet`, and invalid commands or options, show an error and the relevant
+help on stderr. Explicit `--help` and bare `atto` print help on stdout and exit
+successfully. With `--json`, parser errors remain structured JSON on stdout.
+
+Amounts are exact decimal strings. The default unit is `ATTO`; use `--unit RAW`
+for raw amounts. `atto send` generates a unique request ID and displays it before
+starting. Use `--request-id` to supply your own or check a previous payment.
+**Running the command again without its original ID creates a new payment.**
+
+Temporary connection failures, timeouts, and HTTP 5xx responses retry automatically
+with delays of 1, 2, 4, 8, 16, then 30 seconds until success or Ctrl+C. HTTP 4xx
+responses (including 429), invalid responses, and local validation or policy errors
+stop the command. Retrying publication checks for confirmation first and otherwise
+resends the identical signed transaction; it never builds another debit.
+
+Ctrl+C stops further attempts. An in-flight Commons node request finishes or times
+out before shutdown; a payment may already have reached the node. Keep the request
+ID and inspect `atto journal show <request-id>` before starting another payment.
+Reusing an unresolved payment's ID checks its recorded transaction; it does not
+construct a replacement payment.
+With `--json`, stdout contains one result/error envelope; request ID and retry
+progress are JSON lines on stderr. Error details include the request ID.
+MCP and generic `atto call send` still require a caller-supplied ID and do not
+automatically retry.
+
+```sh
+atto account --index 0
+atto account <atto-address>
+atto balances --addresses <address-1>,<address-2>
+atto send <destination> 1.25
+atto send --to-index 1 --amount 1
+atto send --to-label "Savings" --amount 1
+atto send <destination> 1 --index 1 --request-id invoice-from-account-1
+atto send <destination> 100 --unit RAW --request-id invoice-2026-002
+atto send <destination> 1 --request-id order-42 --reason 'Invoice 42' --metadata '{"orderId":"42"}'
+atto pool status
+atto journal list --status unknown --limit 20
+atto journal show order-42
+atto quote --usd 1
+atto metrics
+atto receivables --limit 100
+atto receive <send-hash> --index 0
+atto receive-all --index 0
+atto representative change <atto-address> --index 0
+atto representative weight <atto-address>
+atto transaction <hash>
+atto entry <hash>
+atto history transaction --addresses <atto-address> --from-height 1 --limit 50
+atto history --index 0
+atto history entry --addresses <atto-address> --cursor <returned-cursor>
+atto watch account --addresses <atto-address>
+atto watch receivable --addresses <atto-address> --min-amount-raw 1
+atto watch transaction --network-wide
+```
+
+To send 1 ATTO from account 0 to saved account 1, use
+`atto send --to-index 1 --amount 1`. The destination must already be saved;
+`--to-index` does not derive it. Choose a destination address, `--to-index`, or `--to-label`,
+and use `--amount` or `--usd` with index/name targets. Each send generates its request ID
+when omitted; retain the printed ID for retries.
+
+`atto send` uses index `0` by default. Use `--index N` to select another derived
+account, or `--pool` to select automatically from the approved account pool.
+`--pool` and `--index` are mutually exclusive. Default and explicit source
+accounts must hold the full payment amount. The initial pool contains index `0`,
+with consolidation disabled. MCP selects from the approved pool when its `index`
+is omitted; explicit MCP indexes must also belong to that pool.
+
+Configure the pool in your own terminal:
+
+```sh
+atto pool configure --indexes 0,1,2
+# Allow sends using --pool to combine balances from these accounts:
+atto pool configure --indexes 0,1,2 --consolidate
+```
+
+This preserves the spending limits and MCP access mode, displays the exact pool
+change, and requires local approval. Omitted pool settings are preserved; `--no-consolidate` disables consolidation. Pool
+indexes must be unique, between `0` and `2147483647`, with at most 100 members.
+Approval derives missing indexes without activating them for automatic receiving.
+`pool status` reports balances, available totals, and account readiness.
+
+Pool selection prefers an available account with enough funds and valid work for
+its current account head. Public work is prepared when a spending session starts and
+after confirmed account mutations, and cached in the shared profile. Account
+locks allow independent accounts to send concurrently across CLI/MCP processes
+using that same local profile; unfinished payments keep their accounts reserved.
+
+When consolidation is approved, a payment using `--pool` may first move funds
+among verified wallet-owned pool accounts, then make one payment to the destination.
+Only the final payment consumes the spending allowance. Consolidation applies
+only to automatic pool selection (`--pool` for `atto send`). Spending limits and
+pool approval are checked again
+before each planned signature; a partially completed payment can pause until its
+remaining steps are authorized again. Retain `--pool` and the original request ID
+to resume confirmed progress. An unresolved block remains reserved until canonical network
+evidence establishes its outcome.
+
+```sh
+atto send <destination> 2 --pool --request-id pooled-invoice-2026-001
+# Retry that same payment after an interruption:
+atto send <destination> 2 --pool --request-id pooled-invoice-2026-001
+```
+
+`--metadata` accepts a JSON object of up to 4096 UTF-8 bytes with bounded nesting;
+`--reason` adds `metadata.reason`. Supplying the reason twice is rejected.
+Metadata stays in the local payment journal and is never published on the Atto
+network. Treat it as caller-supplied text and keep secrets out of it. A retry
+retains the original metadata when omitted; changed metadata for the same request
+ID is rejected.
+
+`journal list` returns newest records first, with an optional `--status` of
+`reserved`, `signed`, `published`, `unknown`, or `failed`. Use the returned
+`nextCursor` as `--cursor` with the same status filter; `--limit` accepts 1–100
+and defaults to 50. `journal show` reads one request's metadata, source, network,
+and recorded payment progress.
+
+USD-priced sends use an indicative market conversion. Read the terms, record
+your explicit acceptance of their current version, then send:
+
+```sh
+atto terms show
+atto terms accept --version <displayed-version> --accepted
+atto send --destination <atto-address> --usd 1 --request-id invoice-2026-003
+# Equivalent amount/unit form:
+atto send <atto-address> 1 --unit USD --request-id invoice-2026-004
+```
+
+USD sends are available on LIVE. Market data is dated daily, and conversions
+reject observations older than 72 hours. Amounts round down to whole RAW.
+The returned price and timestamp describe an indicative valuation;
+they do not guarantee an executable exchange price. No exchange trade is made.
+A USD send fixes its Atto amount for that request ID, so retries do not reprice
+the payment. Budget consumption always uses the resulting Atto amount. Reading
+metrics and previewing a quote do not require accepting terms.
+
+`history` defaults to account entries; use `history transaction` for transactions.
+History, receivables, balances, and watches default to active wallet addresses.
+Use `--index N` or `--addresses <address,...>` to select saved or external accounts;
+these selectors cannot be combined. Watches also accept `--network-wide` for
+account, transaction, and entry events, or `--hash` for one transaction or entry.
+These scopes are mutually exclusive. Watches only observe events and report
+connection status even when no events arrive; they do not start receiving.
+
+List commands return bounded results and explain when the scan window or record
+limit was reached. `history` and `journal list` support continuation cursors with
+the same filters; `receivables` does not support cursors. History also supports
+inclusive height ranges. Watch output reports retention gaps; account and
+receivable streams do not guarantee replay of every transition.
+
+`receive <hash>` receives one payment. `receive-all` processes a bounded batch
+for account 0 by default (`--index N` selects another account). Run it again if
+more remain, or use `wallet receive` for continuous receiving across active
+accounts. Continuous receiving requires an initialized wallet, enabled automatic
+receiving, and at least one active account.
+
+CLI commands print readable text by default, including when piped. Wallet import
+and creation show a confirmation and address; balances, payments, history, and
+watches show labeled values. Addresses, amounts, hashes, and cursors are never
+rounded or shortened. Wallet status omits internal fingerprints and public keys.
+Payment and network summaries show exact ATTO and RAW amounts, addresses, and
+transaction hashes. Human output omits signatures, work, and serialized blocks;
+`--json` includes the complete protocol data. Local payment metadata stays visible.
+
+Use `--json` whenever you want the complete structured result, especially in
+scripts. This applies to every command, including `call` and streaming watches:
+
+```sh
+atto wallet status
+atto --json wallet status
+atto --json balances
+atto --json journal list
+```
+
+In JSON mode, success is
+`{"result": ...}`; operational failure is
+`{"error":{"code":"...","message":"..."}}` and a nonzero exit status.
+Each response is one compact JSON line. Existing scripts that parsed the old
+default pretty-printed JSON must now pass `--json`. MCP response formats are unchanged.
+Without `--json`, failures and cancellations are readable messages on stderr.
+Cancelling a prompt exits with status `1` and leaves the wallet unchanged.
+Large protocol integers remain strings. Invalid CLI arguments return a sanitized
+`INVALID_INPUT` error; use command-specific `--help` for accepted arguments.
+Dependency diagnostics go to stderr.
+
+Single operations are available through the CLI's generic adapter. Inspect an
+operation's input schema before constructing its JSON:
+
+```sh
+atto operations
+atto operations send
+atto --json call account_get --input '{"index":0}'
+atto --json call history_list --input '{"event":"entry","limit":50}'
+```
+
+Generic `atto call send` follows the shared operation schema: omitting `index`
+selects from the approved pool. Include `"index": 0` to select account zero.
+
+`atto watch` keeps its session open and streams events directly. Generic
+`call watch_*` commands are rejected because their session would end immediately;
+use MCP for persistent watch IDs and cursor-based polling.
+
+## Diagnostics
+
+Run doctor in the environment where the failure happens:
+
+```sh
+atto doctor
+atto --json doctor
+atto --data-dir /absolute/path/to/profile doctor
+atto-mcp --data-dir /absolute/path/to/profile doctor
+# After publication, no global installation is needed:
+npx --yes @attocash/mcp@VERSION --data-dir /absolute/path/to/profile doctor
+```
+
+Both commands run full checks by default. Allow up to 60 seconds. The OS password
+store may ask you to unlock it or allow credential access, and the worker receives
+one fresh proof-of-work request. Doctor verifies the recovery phrase against the
+saved wallet identity inside a separate process; it never prints or returns the
+phrase, seed, or private key. Nothing is signed, published, or added to the work
+cache. Doctor does not start receiving or retry pending payments.
+
+The report includes:
+
+- Runtime and package versions, executable, selected profile, credential service
+  and account, configured node and worker URLs.
+- Public-state readability, supported state version, and directory/file access
+  and permissions, without initialization, migrations, or permission changes.
+- Password-store backend and credential access. On Linux, observations about
+  `secret-tool`, D-Bus, and the runtime directory help distinguish launch issues.
+- Actual node time and account APIs, configured network, and a bounded Commons
+  account stream. An unopened wallet account can use the configured representative
+  for an observable snapshot. No snapshot is reported as unverified, not as proof
+  that an infinite idle stream is broken.
+- Fresh worker output validated by Commons against a random public target.
+- Initialization, receiving prerequisites, unfinished reset/payments, and MCP
+  access when diagnosing MCP. Read-only MCP access is a valid choice.
+- LIVE USD-price freshness and terms acceptance. USD-only issues are warnings;
+  ordinary ATTO payments do not require market data or accepted USD terms.
+
+Each check has a stable `id`, `status` (`pass`, `warn`, `fail`, or `skipped`),
+`code`, and message, with safe evidence and remediation steps where useful.
+The JSON report contains `context`, `checks`, overall `status`, and `durationMs`.
+CLI output is readable text by default; `--json` wraps the full report in
+`{"result": ...}` even when checks fail. Exit status is `1` if any check fails,
+otherwise `0`. Missing prerequisites produce explicit skipped checks.
+
+Node reads and streaming each have a 10-second budget; credential and work probes
+have a 30-second budget, within the 60-second overall deadline. Ctrl+C cancels
+outstanding checks, including native credential probes and their subprocesses.
+Doctor does not check npm for updates.
+
+An agent should call the MCP **`doctor` tool** to inspect the server's own process.
+A terminal result cannot establish that an already-running MCP has the same
+environment. When a user-owned Linux session socket is available, doctor may test
+environment overrides in an isolated credential probe. It returns
+`remediation.suggestedEnv` only if the stored credential becomes readable and
+matches the wallet. The current check remains failed until the launcher is
+corrected. Apply only authorized configuration changes, restart the MCP
+connection, and rerun its tool. Doctor never changes environment variables,
+client configuration, spending approvals, or terms acceptance; there is no
+`--fix` option.
+
+If MCP cannot start because its profile is invalid, run `atto-mcp doctor` with
+that same `--data-dir` in a terminal. Its diagnostic entry point does not need to
+open a wallet session. An absent profile uses explicitly labelled defaults and
+is not created; an invalid profile is reported without substituting another one.
+SQLite may maintain its normal WAL coordination files during inspection; wallet
+data, settings, journal entries, approvals, and work caches are unchanged.
+
+The library exports `runDoctor({ directory?, access?: 'mcp', signal? })` from
+`@attocash/cli/core`, independently of `createApplication`. Applications with an
+open wallet can also use `call('doctor')`.
+
+## Spending limits and MCP access
+
+CLI spending starts without a cap; **MCP access defaults to read-only**. Set a
+per-request cap, multiple rolling day windows, or both. All configured rules must pass.
+Changing limits requires a human to review and confirm the change in an
+interactive terminal; reading them does not:
+
+```sh
+atto limits set --per-payment 10 --daily 25
+atto limits set --input '{"perRequest":{"amount":"10","unit":"ATTO"},"rolling":[{"days":1,"amount":"25","unit":"ATTO"},{"days":7,"amount":"100","unit":"ATTO"}]}'
+atto limits status
+atto limits clear
+```
+
+Amount flags default to ATTO; use `--unit RAW` for raw amounts. Omitted limits
+are preserved, and `--daily` replaces only the rolling 24-hour rule. Advanced
+`--input` replaces the entire policy and cannot be combined with amount flags.
+Pool configuration also preserves omitted settings; use `--no-consolidate` to
+disable consolidation explicitly.
+
+`limits set` preserves the existing MCP access mode unless you supply
+`--access read-only` or `--access spend`. `limits clear` also preserves that mode;
+if MCP already has spending access, clearing its limits permits unlimited sends.
+To enable MCP with a bounded policy explicitly:
+
+```sh
+atto --data-dir /absolute/path/to/profile limits set --access spend \
+  --input '{"perRequest":{"amount":"10","unit":"ATTO"},"rolling":[{"days":1,"amount":"25","unit":"ATTO"}]}'
+```
+
+MCP `limits_propose` and generic `atto call limits_propose` **only propose** a change.
+They cannot apply it. `limits_propose` also accepts `pool` with `indexes` and
+`consolidate`; omitting it preserves the current pool. `limits_get` returns the
+active policy, usage, `mcpAccess`, pool, and current proposal. A human approves or rejects the proposal in their own
+terminal, using the same directory as the MCP client's configuration:
+
+```sh
+atto --data-dir /absolute/path/to/profile limits approve PROPOSAL_ID
+atto --data-dir /absolute/path/to/profile limits reject PROPOSAL_ID
+```
+
+There is no MCP approval tool or noninteractive approval flag. Each proposal is
+bound to its profile directory, wallet identity, network, and policy revision.
+It expires after 24 hours; a newer proposal replaces the previous ID. Approval
+rechecks those details after you confirm.
+
+Read-only MCP can read data, manage personal labels, watch events, and propose limits. It cannot send,
+receive, derive or activate addresses, change representatives or wallet
+configuration, or record terms acceptance. Approved spending access enables
+these operations, with sends subject to the shared policy. This is an MCP tool
+boundary, not a sandbox for programs or shells running as the same OS user.
+
+Limits accept `ATTO` or `RAW` and aggregate sends through this CLI and MCP across
+all derived addresses, including ordinary payments to owned addresses. Internal
+transfers in an approved consolidation plan are excluded, so the final payment
+counts once. They also exclude
+payments made by other wallet applications. Receiving and representative changes do not consume an
+allowance. USD sends count their converted RAW amount. Changing limits preserves
+historical spending and pending reservations.
+
+Simultaneous CLI/MCP mutations are coordinated. A send reserves allowance before
+signing and records its block hash before publication. If publication is
+uncertain, the reservation stays counted. Retry **the same request ID** to check
+the existing outcome. A conflicting reuse is rejected; a timeout does not create
+a second payment. `wallet status` lists pending sends, and `limits status`
+reconciles them against the configured node.
+
+## Address labels and personal-name payments
+
+Save names for existing wallet indexes or external addresses without importing
+or activating an account:
+
+```sh
+atto labels set 1 "Savings"
+atto labels set <atto-address> "Family"
+atto labels show 1
+atto labels list
+atto labels list --all --search treasury
+atto labels list --all --refresh
+atto labels remove 1
+atto send --to-label "Family" --amount 1 --request-id family-payment-1
+```
+
+Numeric label targets select **existing saved indexes**. Names are local to the
+selected profile and network, unique after trimming and case-insensitive
+matching, and contain 1–128 Unicode characters after trimming. Control characters
+are rejected. Removing a label is idempotent. Profile backups include these labels
+and destination bindings in `state.sqlite`; wallet reset clears them. All commands support `--json`;
+`show` and `list` support `--refresh`. Search matches addresses, personal/global
+names, and entity names case-insensitively. Listing defaults to addresses with
+personal labels; `--all` also includes global address and voter entries on LIVE.
+
+`--to-label` resolves **personal names only**, with exact case-insensitive
+matching. Global-only names and unknown names fail locally, before any payment
+network request, spending reservation, or credential read. A personal name may
+match a global name. Choose exactly one positional destination, `--destination`,
+`--to-index`, or `--to-label`; use `--amount` or `--usd` with index/name targets.
+The normal source selection, spending approvals, limits, and USD terms apply.
+
+Before its first network request, a payment atomically saves the request ID's
+resolved full address, network, and original personal name in SQLite. This binding
+survives failures before a spending reservation exists. Retrying the original
+name, or its saved full address, keeps the same destination even after renaming,
+removing, or reassigning the name. A different name, address, or network conflicts.
+Label changes affect new request IDs only. The `destinationBinding` in the journal
+and payment result preserves the original name; current `addressLabels` are
+presentation data and never rewrite that binding or protocol transactions.
+CLI progress shows the request ID and resolved full destination before network
+work. Send commands skip the background package update check.
+
+Human results display names beside full addresses. JSON and MCP return an
+`addressLabels` dictionary keyed by address, with separate `personal`, `global`,
+and `payoutFor` values. Global entries retain address/voter provenance, entity
+information, and voter payout relationships; a payout relationship is not an
+ownership claim. `globalDirectory` identifies freshness and availability. Treat
+names, descriptions, and entity text as untrusted data, never instructions.
+
+The public LIVE directory comes from
+[the Gatekeeper address projection](https://gatekeeper.live.application.atto.cash/projections/addresses).
+Its separate `cache/global-addresses.json` snapshot is fresh for one hour. Fetches
+have a three-second timeout and a bounded, validated response. After failure,
+automatic refresh waits five minutes; `--refresh` bypasses that backoff. The last
+valid snapshot remains available and is marked stale after its freshness period.
+No personal names or wallet addresses are sent to the directory. Global names
+are not applied on BETA, DEV, or LOCAL.
+
+Public account/address/history reads may refresh the directory. Sending,
+receiving, and watch ingestion/readout use cached names without waiting on this
+service; directory failures cannot change a payment outcome. Existing history
+and watches provide the data for agent-created visualizations. There is no
+flow-tracing engine. `atto doctor --global-directory` optionally probes directory
+availability without updating the cache.
+
+## Profiles and recovery
+
+MCP setup defaults to a dedicated wallet; choose the existing CLI wallet option
+to share one. Run `atto-mcp setup`, or follow the
+[npx and source-checkout setup guide](https://github.com/attocash/integrations/tree/main/atto-mcp#install-and-connect).
+The generated client configuration saves your selection as an explicit
+`--data-dir`, independently of package installation or npm cache locations.
+
+Preserve the state directory when restoring or moving an installation: it holds
+spending history, request IDs, payment metadata and consolidation progress, pending
+publication records, personal labels for every network, pinned payment destinations,
+and public address metadata. Recreating a mnemonic alone
+does not restore those records.
+Stop wallet processes before backing up or moving state. New CLI installations
+use the standard CLI directory below. If the legacy directory already contains
+`state.sqlite`, CLI commands without `--data-dir` continue to use that legacy
+wallet:
+
+| OS | Standard CLI directory | Legacy directory |
+| --- | --- | --- |
+| Linux | `$XDG_DATA_HOME/atto-cli`, or `~/.local/share/atto-cli` | `$XDG_DATA_HOME/atto-mcp`, or `~/.local/share/atto-mcp` |
+| macOS | `~/Library/Application Support/Atto CLI` | `~/Library/Application Support/Atto MCP` |
+| Windows | `%LOCALAPPDATA%/Atto CLI` | `%LOCALAPPDATA%/Atto MCP` |
+
+Windows falls back to `~/AppData/Local` when `LOCALAPPDATA` is unset. The dedicated
+MCP directory is `profiles/mcp` inside the legacy directory. MCP without an
+explicit `--data-dir` selects that dedicated profile, not the CLI default.
+Existing MCP clients that previously omitted the option should choose their
+existing wallet during setup or specify its old directory explicitly.
+
+Both executables accept `--data-dir <directory>`. The legacy default keeps its
+`default` credential account; other accounts are derived from the absolute path.
+New standard CLI profiles also contain public `profile.json` metadata selecting
+the **Atto CLI** service. **Include this file in profile backups.** The marker
+also pins a newly selected standard CLI default, so legacy state created later
+does not silently switch wallets; creating an explicit standard profile alongside
+an existing legacy wallet preserves the legacy default. An older wallet already
+at that path without the marker retains **Atto MCP**. Custom and
+dedicated MCP profiles retain **Atto MCP** as well. Selecting the same absolute
+directory from either interface selects the same credential and spending state.
+
+Keep the same absolute directory when restoring whenever possible. A different
+path selects its own credential account and may select a different service;
+recovery there requires restoring the corresponding password-store entry before
+resuming payments. Preserve the original state and service metadata. No mnemonic
+is stored in the profile directory.
+
+If the password store is locked or unavailable, unlock it and retry. If the
+mnemonic is lost from the password store, recover it from your private backup
+using `atto wallet import` in an uninitialized profile. Preserve the old public
+state and pending-send records for reconciliation before resuming payments.
+
+## Library API
+
+Other local adapters can import the supported engine interface:
+
+```js
+import { createApplication, operations } from '@attocash/cli/core';
+
+const application = createApplication({ directory: '/absolute/path/to/profile' });
+try {
+  const balances = await application.call('balances_get');
+  console.log(balances);
+  console.log(operations.map(operation => operation.name));
+} finally {
+  await application.close();
+}
+```
+
+Omit `directory` to use the CLI default wallet. The exported `ApplicationSession`
+interface provides `call(name, input?)`, `start()`, and `close()`. Call `start()`
+for a persistent session that should run automatic receiving, and always call
+`close()` when the session ends. Watches belong to that application session.
+The library's `send` operation selects from the approved pool when `index` is
+omitted, matching MCP. The `atto send` command supplies index `0` by default and
+uses that automatic selection only with `--pool`.
+
+Adapters requiring the MCP permission policy pass `access: 'mcp'`; that session
+rechecks the profile's approved access before wallet mutations. Automatic
+receiving follows that access mode too. Generic `limits_propose` only creates a
+proposal in either mode.
+
+The entry point also exports `operations`, `errorResult`, and the `Operation`,
+`ApplicationOptions`, and `ApplicationSession` types. It does not expose recovery
+methods. Wallet creation, import, backup, and reset remain terminal commands. The MCP
+package calls this API directly and keeps one application session for its stdio
+connection. `@attocash/cli/profiles` provides shared directory resolution;
+`@attocash/cli/terminal` provides interactive setup and proposal review for the
+terminal executables.
+
+## Development and verification
+
+Run workspace commands from the repository root:
+
+```sh
+npm ci
+npm run check
+npm test
+npm run test:integration
+ATTO_TEST_KEYCHAIN=1 npm run test:keychain
+npm run pack
+npm run test:package
+```
+
+For CLI development alone, use `npm run build --workspace @attocash/cli`,
+`npm run check --workspace @attocash/cli`, and
+`npm test --workspace @attocash/cli` after building. Run the source checkout with
+`node atto-cli/dist/cli/main.js --help`.
+
+Tests use temporary state, synthetic recovery material, and mock nodes/workers.
+Platform credential-store tests run when `ATTO_TEST_KEYCHAIN=1`, use isolated
+entries, and remove them afterward. Linux native credential persistence has
+been verified in an isolated Secret Service session. macOS Keychain and Windows
+Credential Manager verification is configured in CI and requires those
+platforms. Container integration tests run on Linux. Tests never place live-fund
+transactions or publish the package.