@tokamak-private-dapps/private-state-cli 2.4.2 → 3.0.0

package/README.md

@@ -6,40 +6,86 @@ The full private-state DApp documentation is published with the repository:
 
 - https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/tree/main/docs/dapps/private-state
 
+The Service Privacy Notice is published in the repository:
+
+- https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/blob/main/docs/dapps/private-state/privacy-notice.md
+
+The Service Terms of Service are published in the repository:
+
+- https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/blob/main/docs/dapps/private-state/terms.md
+
 ## Terminology And Exchange Boundary
 
 This npm README uses the same terminology as the repository README:
 
 - `Tokamak Private App Channels`: Ethereum-settled, validity-proven execution domains for bridge-coupled DApps.
 - `private-state DApp`: the current reference DApp that programs confidential application state inside a channel.
-- `canonical Tokamak Network Token`: the L1 asset whose custody remains anchored on Ethereum.
-- `self-custody L1 wallet`: a user-controlled L1 account, not an exchange deposit address.
-- `L1-transparent bridge edge`: public bridge deposit and withdrawal transactions involving the canonical token.
+- `canonical Tokamak Network Token`: the Ethereum mainnet asset whose custody remains anchored on Ethereum.
+- `self-custody Ethereum wallet`: a user-controlled Ethereum account, not an exchange deposit address.
+- `public bridge edge`: public Ethereum mainnet bridge deposit and withdrawal transactions involving the canonical token.
 - `channel-local accounting balance`: liquid application balance inside a channel before or after note use.
 - `private-state note`: a channel-local application note, not an exchange-supported token or deposit asset.
+- `Join Toll`: the one-time Channel entry fee paid when a user joins a Channel.
 - `proof-backed confidential application state`: DApp state advanced by accepted proof-backed channel transitions.
-- `user-controlled selective disclosure`: optional user disclosure from local wallet state; Tokamak does not hold a master viewing key.
+- `user-controlled selective disclosure`: optional user disclosure from local wallet state; the Provider and Tokamak Network PTE. LTD. do not hold a master viewing key.
 - `viewing key`: the note-receive private key used to decrypt note-delivery events for the registered note-receive public key.
-- `spending key`: the channel-bound L2 private key used to authorize proof-backed note use.
+- `spending key`: the channel-bound private application key used to authorize proof-backed note use.
 
 Tokamak Private App Channels are not an exchange deposit network. Exchange-facing token transfers and bridge
-entry or exit remain public L1 activity. Internal private-state note counterparty relationships and note provenance are
-not public by default and are not reconstructed by Tokamak on a user's behalf.
+entry or exit remain public Ethereum mainnet activity. Internal private-state note counterparty relationships and note
+provenance are not public by default and are not reconstructed by the Provider or Tokamak Network PTE. LTD. on a user's
+behalf.
 
 ## Address And Key-Safety Warnings
 
 Do not use an exchange deposit address as a private-state wallet address. Private-state notes are not
-supported exchange assets. Always withdraw TON to a self-custody L1 wallet before using a channel.
+supported exchange assets. Always withdraw TON to a self-custody Ethereum wallet before using a channel.
+
+Bridge deposits and withdrawals are public Ethereum mainnet events. Internal note transfers are designed so public
+contract state does not automatically reconstruct the full note path.
+
+This CLI does not send your spending key, wallet secret, or private note plaintext to the Provider or Tokamak Network
+PTE. LTD.
+
+## Browser Wallet L1 Signing
+
+The CLI supports two L1 signing paths. Supplying `--account <ACCOUNT>` uses the protected local account secret imported
+with `account import`. Omitting `--account` on supported commands opens a local signing page and asks the user to approve
+the required L1 action in a MetaMask-compatible browser wallet. The browser-wallet path uses an injected EIP-1193
+provider and is not Chrome-specific. The CLI prints the localhost signing URL so the same approval page can be opened in
+another MetaMask-capable browser when the default browser is not the intended wallet browser.
 
-Bridge deposits and withdrawals are public L1 events. Internal note transfers are private by design and are not
-automatically reconstructible by Tokamak, exchanges, or public observers.
+The localhost page is a request relay, not an approval UI. It starts the wallet provider request when the page loads and
+returns the provider result to the terminal. Users should approve or reject only in the MetaMask-compatible wallet UI,
+not in UI provided by the CLI page. During one CLI command, sequential wallet requests use the same localhost origin so
+the wallet account permission granted at connection can apply to later signature and transaction requests. The relay page
+stays open and receives later wallet requests from the CLI instead of asking the user to trust a localhost approval
+button.
 
-This CLI does not send your spending key, wallet secret, or private note plaintext to Tokamak.
+Browser-wallet mode avoids CLI access to the raw L1 private key. It does not remove the local private-state wallet key
+model: `channel join` still reads `--wallet-secret-path` once, derives the channel-bound spending key, derives the
+note-receive viewing key, and stores those L2 keys under the existing protected wallet-key rules. Note commands such as
+`wallet mint-notes`, `wallet transfer-notes`, and `wallet redeem-notes` still use the local spending key and viewing key
+for proof generation and note recovery.
 
-## Tokamak-Operated Mainnet Channels
+When the browser wallet is connected to a different chain than the CLI `--network`, the CLI asks the wallet to switch to
+the selected chain with `wallet_switchEthereumChain` and then verifies `eth_chainId` again. The command continues only
+after the user approves the switch and the wallet reports the expected chain. The CLI does not send local RPC URLs or API
+keys to the browser to add missing chains.
 
-The table below lists private-state mainnet channels directly opened by Tokamak Network. Dates are
-UTC.
+`channel join` in browser-wallet mode asks the user to approve the following browser wallet requests: account connection,
+chain check, network switch when needed, the EIP-191 message signature for L2 spending-key derivation, the EIP-712
+typed-data signature for note-receive viewing-key derivation, any Join Toll token approval, and the final join
+transaction. User-Controlled AI Agents must not click browser wallet approval UI for the user.
+
+Proof-backed note commands can also separate local L2 authority from L1 gas payment. Use `--tx-submitter <ACCOUNT>` to
+submit `executeChannelTransaction` through a separate imported local account, or pass `--tx-submitter` without a value
+to submit through a browser wallet. If `--tx-submitter` is omitted and the wallet owner L1 key is not available locally,
+the CLI falls back to the browser wallet and requires the selected browser account to match the wallet owner address.
+
+## Documented Mainnet Channels
+
+The table below lists private-state mainnet channels documented by this package. Dates are UTC.
 
 | Channel name | Channel creator / leader | Created at | Genesis block | Channel manager |
 | --- | --- | --- | ---: | --- |
@@ -80,6 +126,18 @@ artifacts needed by transaction-sending channel commands:
 private-state-cli install
 ```
 
+`install` accepts optional `--network <NAME>` to install only that network's deployment artifacts. Mainnet install, and
+install without `--network`, opens a local browser page for the current Service Terms and requires explicit human
+acceptance before installation proceeds. Sepolia and anvil installs do not require Terms acceptance. The browser page is
+served from `127.0.0.1`, uses a one-time local token, and lets the user review the Terms in the browser. After browser
+acceptance succeeds, the CLI immediately prints that installation is starting before any long-running install work
+begins. Use `--terminal-terms` only when the local browser flow cannot be used for a Terms-gated install. The CLI package
+includes the canonical Terms Markdown and reports its `termsVersion` and deterministic `termsHash` in install results.
+JSON mode cannot accept Terms for the user. For Terms-gated installs, `private-state-cli install --json` reports that
+browser-based interactive installation is required and includes Terms references without installing artifacts.
+The acceptance record is stored in the user's local private-state CLI workspace and is not sent to the Provider by
+default.
+
 By default, `install` resolves the latest `@tokamak-zk-evm/cli` from the npm registry and uses the bundled
 `@tokamak-private-dapps/groth16` dependency version selected by the installed private-state CLI package. To pin exact
 proof backend versions for a channel, pass explicit versions:
@@ -106,12 +164,17 @@ zk-EVM runtime, Groth16 runtime, Groth16 zkey, callable DApp ABI, or DApp regist
 create or mutate channel state require a later full `private-state-cli install`.
 
 `install` downloads public deployment artifacts from the configured artifact index. It does not read repository-local
-`deployment/` outputs by default. Repository development workflows that need local anvil artifacts can opt in explicitly:
+`deployment/` outputs by default. Repository development and release-readiness workflows that intentionally need local
+deployment artifacts can opt in explicitly:
 
 ```bash
 private-state-cli install --include-local-artifacts
 ```
 
+When `--include-local-artifacts` is used, the CLI scans local `deployment/chain-id-*` directories for the selected DApp
+and records the final installed artifact source once per chain. Local artifacts override downloaded artifacts for the
+same chain.
+
 Run the CLI with:
 
 ```bash
@@ -140,16 +203,22 @@ private-state-cli help update
 from a repository checkout or npm does not report a global install, it does not edit local source files; it prints the
 recommended `npm install -g @tokamak-private-dapps/private-state-cli@latest` command instead.
 
-Remove all local private-state CLI data with:
+Remove local private-state CLI data with:
 
 ```bash
 private-state-cli uninstall
 ```
 
-`uninstall` is intentionally interactive. It requires typing
-`I understand that the wallet secrets deleted due to this decision cannot be recovered` before deleting
-`~/tokamak-private-channels/`, including local account secrets and wallet key files, the Tokamak zk-EVM runtime cache,
-and the global CLI npm package when npm reports that it is globally installed.
+`uninstall` is intentionally interactive. By default, it deletes local workspaces, account secrets, wallet secret source
+files stored under the CLI root, installed private-state artifacts, the Groth16 workspace, the Tokamak zk-EVM runtime
+cache, and the global CLI npm package when npm reports that it is globally installed. It preserves wallet spending-key
+and viewing-key files under the CLI secret root.
+
+To delete every local private-state CLI file, including wallet spending-key and viewing-key files, run:
+
+```bash
+private-state-cli uninstall --include-wallet-keys
+```
 
 ## Commands
 
@@ -167,35 +236,39 @@ A common note-use flow after channel policy review is:
 10. `channel exit`
 11. `account withdraw-bridge`
 
-`channel join` pays any join toll directly from the L1 wallet; `account deposit-bridge` funds later channel liquidity and does not pay the join toll.
+`channel join` pays any Join Toll directly from the Ethereum wallet; `account deposit-bridge` funds later channel liquidity and does not pay the Join Toll.
 
 Use `private-state-cli help commands` for the full command list and required options. `private-state-cli --help`
-continues to print the same command list for shell compatibility.
+continues to print the same command list for shell compatibility. Add `--json` to either form to print the command
+reference as structured JSON on stdout.
+
+### Command Warnings And User Confirmation
 
-### Action-impact acknowledgement
+The CLI prints warning summaries before commands that send transactions, move funds, accept Channel policy, expose
+plaintext evidence, or delete local data. These warnings explain whether the command emits public Ethereum mainnet
+events, whether it changes private-state note state, which addresses or amounts become public, which note facts are not
+public by default, illegal-use prohibitions, no-recovery limits, and Channel policy acceptance.
 
-Transaction-sending bridge, channel, and note commands require `--acknowledge-action-impact`. Before submitting any
-transaction, the CLI prints a static action-impact summary covering whether the command emits public L1 events, whether
-it changes private-state note state, which addresses or amounts become public, which note facts are not public by default,
-illegal-use prohibition, secret-recovery limits, and channel policy acceptance. In non-interactive contexts, such as
-scripts and LLM-assisted execution, the command fails unless the flag is present.
+Terms acceptance is handled at install and renewal time. Destructive commands and sensitive exports use interactive
+confirmation prompts. User-Controlled AI Agents must explain warnings to the user, but they must not accept Terms,
+confirm destructive actions, or handle secret material for the user.
 
 Static warning scope:
 
 | Command | Public surface | Private-state note state | Not public by default |
 |---|---|---|---|
-| `account deposit-bridge` | L1 account, bridge vault, amount, approval/funding txs | No note change | No note plaintext or provenance is created |
-| `account withdraw-bridge` | L1 recipient/account, bridge vault, amount, withdrawal tx | No note change | Prior private-state note path is not reconstructed |
-| `channel join` | L1 account, L2 address, note-receive public key, join toll, channel id | No note change | Wallet secret, spending key, viewing key, and note plaintext |
-| `wallet deposit-channel` | L1 submitter, registered L2 address, amount, channel id, accounting update | No note change | No note provenance is created |
-| `wallet mint-notes` | L1 submitter, registered L2 address, commitments, encrypted note events, root update | Creates notes | Note owner, value, salt, and later provenance |
-| `wallet transfer-notes` | L1 submitter, input nullifiers, output commitments, encrypted note events, root update | Spends and creates notes | Sender-recipient relationship, note plaintext, and provenance |
-| `wallet redeem-notes` | L1 submitter, input nullifier, accounting update, root update | Consumes notes | Prior path by which the note was received |
-| `wallet withdraw-channel` | L1 submitter, registered L2 address, amount, channel id, accounting update | No direct note spend | Prior private-state note path behind the liquid balance |
+| `account deposit-bridge` | Ethereum account, bridge vault, amount, approval/funding txs | No note change | No note plaintext or provenance is created |
+| `account withdraw-bridge` | Ethereum recipient/account, bridge vault, amount, withdrawal tx | No note change | Prior private-state note path is not reconstructed |
+| `channel join` | Ethereum account, channel-local address, note-receive public key, Join Toll, channel id | No note change | Wallet secret, spending key, viewing key, and note plaintext |
+| `wallet deposit-channel` | Ethereum submitter, registered channel-local address, amount, channel id, accounting update | No note change | No note provenance is created |
+| `wallet mint-notes` | Ethereum submitter, registered channel-local address, commitments, encrypted note events, root update | Creates notes | Note owner, value, salt, and later provenance |
+| `wallet transfer-notes` | Ethereum submitter, input nullifiers, output commitments, encrypted note events, root update | Spends and creates notes | Sender-recipient relationship, note plaintext, and provenance |
+| `wallet redeem-notes` | Ethereum submitter, input nullifier, accounting update, root update | Consumes notes | Prior path by which the note was received |
+| `wallet withdraw-channel` | Ethereum submitter, registered channel-local address, amount, channel id, accounting update | No direct note spend | Prior private-state note path behind the liquid balance |
 
 `account deposit-bridge` and `account withdraw-bridge` also print an exchange-controlled address warning. Do not use an
 exchange-controlled address as a self-custody bridge source or as the direct bridge withdrawal target
-unless the user explicitly understands the compliance implications. Prefer a self-custody L1 wallet.
+unless the user explicitly understands the compliance implications. Prefer a self-custody Ethereum wallet.
 
 Workspace recovery commands use saved recovery indexes by default. If the local channel workspace is missing,
 corrupted, or does not contain a usable index, `channel recover-workspace` stops with an explicit error instead of
@@ -241,7 +314,7 @@ Wallet commands that need channel state, including `wallet recover-workspace`, `
 `wallet get-channel-fund`, and `wallet get-notes`, refresh stale local channel workspaces through saved recovery
 indexes before reading state. `wallet get-notes` and `wallet recover-workspace` also refresh received-note logs
 through the saved wallet note recovery index. Wallet note freshness is measured against the fresh channel workspace
-frontier, not the provider's latest L1 block, so unrelated new L1 blocks do not make a wallet stale by themselves.
+frontier, not the provider's latest Ethereum mainnet block, so unrelated new Ethereum mainnet blocks do not make a wallet stale by themselves.
 Automatic refresh never replays from channel genesis and only runs when the recovery delta fits within the 7,200-block
 pre-command budget. If a saved index is missing, unusable, or too far behind, the command stops and asks the user to
 run the appropriate recovery command first.
@@ -271,6 +344,16 @@ If the existing mirror manifest is unreadable or invalid, add `--force` to write
 without trusting that remote manifest as a delta base. The CLI protocol is documented at
 https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/blob/main/docs/dapps/private-state/channel-workspace-mirror-protocol.md.
 
+Channel public observer URLs are also Channel-scoped. The CLI does not use a Tonigma-wide observer URL. To open a
+Channel's public observer, read the URL registered in that Channel's on-chain metadata:
+
+```bash
+private-state-cli help observer --channel-name <CHANNEL> --network mainnet
+```
+
+If no observer URL is registered, ask the Channel Provider for the correct observer location. A static observer URL in
+documentation is only an example for a specific Channel and is not a default for every Channel.
+
 Back up a local wallet with:
 
 ```bash
@@ -283,9 +366,12 @@ nullifiers, and encrypted note payloads only; `owner`, `value`, and `salt` are e
 Importing this backup restores encrypted tracking state and channel cache files, not wallet authority.
 
 ```bash
-private-state-cli wallet import backup --input ./wallet-backup.zip
+private-state-cli wallet import backup --network mainnet --input ./wallet-backup.zip
 ```
 
+Mainnet imports, and imports without a network selector, require current Service Terms acceptance. Sepolia and anvil
+imports can pass `--network sepolia` or `--network anvil` to run without interactive Terms acceptance.
+
 Export viewing and spending authority separately:
 
 ```bash
@@ -293,29 +379,38 @@ private-state-cli wallet export viewing-key --network mainnet --wallet <WALLET>
 private-state-cli wallet export spending-key --network mainnet --wallet <WALLET> --output ./wallet-spending.key
 ```
 
+On mainnet, these export commands are intentionally interactive. They print a warning summary and require the user to
+type the exact confirmation phrase before writing secret-bearing `.key` files. Sepolia and anvil key exports do not
+require interactive confirmation. A viewing-key export can reveal readable note history when other required wallet state
+is available. A spending-key export can authorize note use when other required wallet state is available. Do not send
+exported key files to User-Controlled AI Agents, support channels, or untrusted parties.
+
 Import those capabilities only when the target machine should receive them:
 
 ```bash
-private-state-cli wallet import viewing-key --input ./wallet-viewing.key
-private-state-cli wallet import spending-key --input ./wallet-spending.key
+private-state-cli wallet import viewing-key --network mainnet --input ./wallet-viewing.key
+private-state-cli wallet import spending-key --network mainnet --input ./wallet-spending.key
 ```
 
 A backup plus a viewing key can reconstruct the wallet's readable note view from encrypted events, but it still cannot
 spend notes. A backup plus a spending key is still missing event-log decryption authority. A normal operational restore
-imports the backup, the viewing key, and the spending key, and still needs the relevant local L1 account secret for
+imports the backup, the viewing key, and the spending key, and still needs the relevant local Ethereum account secret for
 commands that submit bridge or channel-registration transactions.
 
 Export a local full-note evidence bundle with:
 
 ```bash
-private-state-cli wallet get-notes --network mainnet --wallet <WALLET> --export-evidence ./wallet-evidence.zip --acknowledge-full-note-plaintext-export
+private-state-cli wallet get-notes --network mainnet --wallet <WALLET> --export-evidence ./wallet-evidence.zip
 ```
 
-This ZIP is an input for `private-state-cli investigator`. It contains plaintext for all locally known
-notes, derived commitments and nullifiers, creation and spend transaction references, transaction calldata, receipts,
-events, and indexes for filtering by note, nullifier, transaction, block range, or available counterparty metadata. It
-includes all local epochs for the selected wallet, including exited epochs retained after `channel exit`. It does not
-include viewing keys, spending keys, wallet secret material, account private keys, or `.key` files. Do not submit the
+On mainnet, this export is intentionally interactive. The CLI prints a warning summary and requires the user to type the
+exact confirmation phrase before writing plaintext evidence. Sepolia and anvil evidence exports do not require
+interactive confirmation. The raw ZIP is an input for `private-state-cli investigator`. It
+contains plaintext for all locally known notes, derived commitments and nullifiers, creation and spend transaction
+references, transaction calldata, receipts, events, and indexes for filtering by note, nullifier, transaction, block
+range, or available counterparty metadata. It includes all local epochs for the selected wallet, including exited epochs
+retained after `channel exit`. It does not include viewing keys, spending keys, wallet secret material, account private
+keys, or `.key` files. User-Controlled AI Agents must not confirm this export or receive the raw ZIP. Do not submit the
 raw ZIP as an exchange or auditor package unless full wallet-history disclosure is intended.
 
 Open the local evidence investigator with:
@@ -328,7 +423,7 @@ The command prints the bundled investigator HTML path and file URL, then opens t
 evidence ZIP in that GUI, choose the disclosure request type, inspect the interactive note-linkage graph, and export a
 narrower user-consent disclosure ZIP. The graph view renders every matched note as a node and shows creation, spend,
 and local note-to-note linkage edges when the raw bundle contains enough local evidence. The GUI can also export a
-Markdown ASCII-art linkage report with a compact graph section and per-note detail sections. The GUI runs locally in the
+Markdown plain-text linkage report with a compact graph section and per-note detail sections. The GUI runs locally in the
 browser and does not send files over the network.
 
 The investigator accepts current epoch-aware evidence bundles only. If a bundle was generated by an older CLI, rebuild
@@ -343,22 +438,24 @@ private-state-cli help transaction-fees --network mainnet
 `help transaction-fees` uses the measured gas data packaged in `assets/tx-fees.json`, the selected network's live fee data,
 and live ETH/USD pricing to print an ETH/USD fee table for transaction-sending commands. The table separates typical
 cost, based on the RPC `gasPrice`, from worst-case cost, based on `maxFeePerGas` when the network reports EIP-1559 fee
-data. AI agents answering user questions about gas, transaction fees, transaction cost, or USD cost should run
-`private-state-cli help transaction-fees --network <NETWORK> --json` and answer from the returned table.
+data. Use `private-state-cli help transaction-fees --network <NETWORK> --json` when another tool needs
+machine-readable fee data.
 
-Proof-backed note commands can use a separate L1 transaction submitter:
+Proof-backed note commands can use a separate Ethereum transaction submitter:
 
 ```bash
-private-state-cli wallet mint-notes --wallet <WALLET> --network mainnet --amounts '[1]' --acknowledge-action-impact --tx-submitter <ACCOUNT>
+private-state-cli wallet mint-notes --wallet <WALLET> --network mainnet --amounts '[1]' --tx-submitter <ACCOUNT>
 ```
 
 `--tx-submitter <ACCOUNT>` is available on `wallet mint-notes`, `wallet transfer-notes`, and `wallet redeem-notes`. The wallet still proves
 note ownership and builds the ZK proof, but the selected local account submits `executeChannelTransaction` and pays gas.
-Use this option when a separate imported local account should submit the L1 transaction and pay gas for a proof-backed
-note command.
+Use this option when a separate imported local account should submit the transaction on the selected network and pay gas for a proof-backed
+note command. Use `--tx-submitter` without a value when the L1 submitter should be selected in a MetaMask-compatible
+browser wallet instead. In both cases, the local wallet spending key remains the authority for the private-state note
+transition.
 
 `wallet transfer-notes` takes JSON arrays for note selection and outputs. `--note-ids` is a JSON array of input note
-commitment IDs from `wallet get-notes`; `--recipients` is a JSON array of recipient L2 addresses; `--amounts` is a JSON
+commitment IDs from `wallet get-notes`; `--recipients` is a JSON array of recipient channel-local addresses; `--amounts` is a JSON
 array of token amounts. Quote decimal amounts to avoid shell or JSON ambiguity. The recipient count must match the
 amount count, only `1->1`, `1->2`, and `2->1` transfer shapes are supported, and the output amount sum must equal the
 selected input note value sum.
@@ -368,9 +465,8 @@ private-state-cli wallet transfer-notes \
   --wallet <WALLET> \
   --network mainnet \
   --note-ids '["0xNOTE1","0xNOTE2"]' \
-  --recipients '["0xL2RECIPIENT1","0xL2RECIPIENT2"]' \
+  --recipients '["0xRECIPIENT1","0xRECIPIENT2"]' \
   --amounts '["1.5","2"]' \
-  --acknowledge-action-impact \
   --tx-submitter <ACCOUNT>
 ```
 
@@ -397,51 +493,65 @@ commands are reported unavailable until full install is completed.
 Local helper commands:
 
 ```bash
-private-state-cli account import --account <ACCOUNT_NAME> --network sepolia --private-key-file <PATH>
-private-state-cli account get-l1-address --account <ACCOUNT_NAME> --network sepolia
-private-state-cli wallet list --network sepolia --channel-name cuda
-private-state-cli wallet get-meta --wallet <WALLET_NAME> --network sepolia
-private-state-cli wallet export backup --network sepolia --wallet <WALLET_NAME> --output ./wallet-backup.zip
-private-state-cli wallet import backup --input ./wallet-backup.zip
+private-state-cli secret create-private-key-source --output ./ethereum-private-key.txt
+private-state-cli account import --account <ACCOUNT_NAME> --network mainnet --private-key-file ./ethereum-private-key.txt
+private-state-cli account get-l1-address --account <ACCOUNT_NAME> --network mainnet
+private-state-cli account get-l1-address --network mainnet
+private-state-cli secret create-wallet-secret-source --output ./wallet-secret.txt
+private-state-cli wallet list --network mainnet --channel-name <CHANNEL>
+private-state-cli wallet get-meta --wallet <WALLET_NAME> --network mainnet
+private-state-cli wallet export backup --network mainnet --wallet <WALLET_NAME> --output ./wallet-backup.zip
+private-state-cli wallet import backup --network mainnet --input ./wallet-backup.zip
 ```
 
-`account import` is the only supported way to bring an L1 signing key into the CLI: it reads `--private-key-file` once
-and stores a protected local account secret for later `--account` use. The source file does not need `0600` permissions.
-`channel join` reads `--wallet-secret-path <PATH>` once while creating the channel-bound spending key and then stores
+`secret create-private-key-source` prompts in the terminal with masked input and creates a local source file for
+`account import`. `account import` is the only supported way to bring an Ethereum signing key into the CLI: it reads
+`--private-key-file` once and stores a protected local account secret for later `--account` use. The source file does
+not need `0600` permissions. `secret create-wallet-secret-source` prompts in the terminal with masked input by default
+and creates a local wallet secret source file for `channel join`. Use `--random` only when a random wallet secret is
+explicitly wanted. `channel join` reads `--wallet-secret-path <PATH>` once while creating the channel-bound spending key and then stores
 wallet backup metadata, viewing-key metadata, and spending-key metadata as separate files. `wallet list` reads only the local workspace and prints saved wallet names that can be reused with
 `--wallet`.
-`wallet get-meta` opens the wallet metadata and reports the stored L1/L2 identity metadata plus the current
+`wallet get-meta` opens the wallet metadata and reports the stored Ethereum/channel-local identity metadata plus the current
 on-chain channel registration match state, including the registered note-receive public key when present. On
 epoch-aware wallet workspaces it also reports the selected wallet epoch and whether that epoch is active or exited.
-`account get-l1-address` is a simple offline helper that derives the L1 address for a local account.
+`account get-l1-address --account <ACCOUNT_NAME>` is a simple offline helper that derives the Ethereum address for a
+local account. Omitting `--account` opens the browser-wallet path and reports the selected browser account address.
 
 ### Wallet Secret Source File
 
 `channel join` needs a wallet secret source file because the CLI no longer accepts raw wallet secrets on the command
-line. The source file is arbitrary high-entropy secret text that the CLI reads once for channel-bound spending-key
-derivation. It is not persisted in the wallet workspace.
+line. The source file is secret text that the CLI reads once for channel-bound spending-key derivation. It is not
+persisted in the wallet workspace.
 
 Create one before joining a channel:
 
 ```bash
-openssl rand -hex 32 > ./wallet-secret.txt
-private-state-cli channel join --channel-name <CHANNEL> --network sepolia --account <ACCOUNT> --wallet-secret-path ./wallet-secret.txt --acknowledge-action-impact
+private-state-cli secret create-wallet-secret-source --output ./wallet-secret.txt
+private-state-cli channel join --channel-name <CHANNEL> --network mainnet --wallet-secret-path ./wallet-secret.txt
 ```
 
+Add `--account <ACCOUNT>` only when the join should use an imported local account alias instead of browser-wallet L1
+signing.
+
+The default helper flow lets the user type a wallet secret so it can be retained more easily. If random generation is
+explicitly wanted, run `private-state-cli secret create-wallet-secret-source --output ./wallet-secret.txt --random`.
+
 The import source file does not need `0600` permissions. The CLI does not persist a wallet-local secret:
-it reads the source once for channel-bound L2 spending-key derivation. The join flow stores the viewing key and
+it reads the source once for channel-bound spending-key derivation. The join flow stores the viewing key and
 spending key as separate protected key files under the CLI secret root; macOS/Linux uses `0600`, while Windows uses ACL
 repair and inspection when possible.
 
 Keep the wallet secret source separately backed up if you expect to rederive the spending key later. The viewing key can
-be rederived from the same L1 private key and channel context because it comes from the note-receive typed-data signing
-flow. The spending key needs the same L1 private key, the same channel context, and the same wallet secret source. If the
-spending-key file is lost and the wallet secret source is also lost, the CLI cannot reconstruct the spending key and the
-notes for that wallet cannot be spent, transferred, or redeemed through the normal note flow.
+be rederived from the same Ethereum account signing authority and channel context because it comes from the note-receive
+typed-data signing flow. The spending key needs the same Ethereum account signing authority, the same channel context,
+and the same wallet secret source. If the spending-key file is lost and the wallet secret source is also lost, no
+recovery method exists for the spending key and the notes for that wallet cannot be spent, transferred, or redeemed
+through the normal note flow.
 
 `wallet recover-workspace` restores the viewing key by default. Add `--wallet-secret-path <PATH>` only when the
 account is currently active in the channel and you need to rederive the spending key. In that mode, the CLI checks the
-derived L2 address and channel token-vault storage key against the current on-chain registration before received-note
+derived channel-local address and channel token-vault storage key against the current on-chain registration before received-note
 recovery starts, then stores the protected spending-key file. Exited or non-active accounts must be recovered without
 `--wallet-secret-path`; that restores viewing/evidence history but not spending authority. The wallet secret source is
 read for derivation and is not stored.
@@ -456,21 +566,22 @@ The viewing key is the note-receive private key. It lets `wallet get-notes` decr
 note-delivery events and rebuild the user's readable note view. Sharing it gives read access to notes addressed to the
 registered note-receive public key, but not spending authority.
 
-The spending key is the channel-bound L2 private key. It authorizes proof-backed use of the wallet identity. Commands
+The spending key is the channel-bound private application key. It authorizes proof-backed use of the wallet identity. Commands
 that create or consume notes, such as `wallet mint-notes`, `wallet transfer-notes`, and `wallet redeem-notes`, need both
 the viewing key and the spending key because the CLI refreshes the readable note workspace after accepted note
 transactions and then proves authorized note use when inputs are consumed.
 
-Key recovery is intentionally split. Recreating the viewing key requires the original L1 private key and the same channel
-context. Recreating the spending key requires the original L1 private key, the same channel context, and the same wallet
+Key recovery is intentionally split. Recreating the viewing key requires the original Ethereum account signing authority and the same channel
+context. Recreating the spending key requires the original Ethereum account signing authority, the same channel context, and the same wallet
 secret source used at `channel join`. `wallet recover-workspace --wallet-secret-path <PATH>` performs this spending-key
 rederivation only for active channel registrations. Importing `wallet-viewing.key` or `wallet-spending.key` restores the
 corresponding capability without rerunning derivation, but a backup ZIP alone never restores either capability.
 
-`wallet get-notes --export-evidence <PATH> --acknowledge-full-note-plaintext-export` writes a local raw evidence ZIP.
-The bundle is not a key export. It includes plaintext note facts for locally known notes so that
-`private-state-cli investigator` can create narrower consent-disclosure packages without requiring viewing-key or
-spending-key sharing.
+`wallet get-notes --export-evidence <PATH>` writes a local raw evidence ZIP. Mainnet export requires interactive
+confirmation; Sepolia and anvil export do not. The bundle is not a key export. It includes plaintext note facts for
+locally known notes and may include retained exited epochs for the selected wallet, so it can reveal sensitive wallet
+history. `private-state-cli investigator` can create narrower consent-disclosure packages without requiring viewing-key
+or spending-key sharing. User-Controlled AI Agents must not confirm the export or receive the raw ZIP.
 
 ## Workspace
 
@@ -486,7 +597,7 @@ key files under `~/tokamak-private-channels/secrets/<network>/wallets/<wallet>/`
 Configure the network RPC endpoint before bridge-facing or wallet recovery commands:
 
 ```bash
-private-state-cli set rpc --network mainnet --rpc-url <RPC_URL> --provider alchemy
+private-state-cli set rpc --network mainnet --rpc-url <RPC_URL> --provider ankr
 ```
 
 The CLI writes `~/tokamak-private-channels/workspace/<network>/rpc-config.env` and later commands read `RPC_URL`,
@@ -518,11 +629,50 @@ provider's documented `eth_getLogs` policy, then retry the recovery command.
 Canonical CLI secrets are checked on read: macOS/Linux uses `0600`, while Windows uses ACL repair and inspection when
 possible.
 
-## LLM Agent Guidance
+## User-Controlled AI Agent Guidance
+
+User-Controlled AI Agents that help users operate this CLI should start with the state-aware guide in JSON mode:
+
+```bash
+private-state-cli help guide --json
+```
 
-LLM agents that guide users through this CLI should read [`agents.md`](agents.md) before suggesting or running
-commands. That file contains the agent-specific operating rules, including secret-handling boundaries, onboarding
-sequence, acknowledgement handling, recovery behavior, and error-response policy.
+The JSON guide is the machine-readable entrypoint for deciding the next safe instruction to give the user. Read
+`agentGuidance` from the result:
+
+- `agentGuidance.source` identifies the instruction file, currently [`agents.md`](agents.md)
+- `agentGuidance.refs` lists the indexed items in that file that apply to the next step
+- `agentGuidance.step` is the symbolic guide step that selected those refs
+- `agentGuidance.termsSource` identifies the Terms document
+- `agentGuidance.termsRefs` lists the Terms sections the agent must read and explain for legal and safety context
+
+The purpose of `--json` mode is to let the user's AI agent guide the user through the smallest safe next action while
+preserving the user's informed consent. JSON output is an instruction surface for the user's tool. It is not permission
+for the tool to bypass human review, accept Terms, confirm destructive actions, confirm sensitive exports, or handle
+secret material. When a command reports required warnings, prohibitions, Terms, Channel policy, or Provider Party and
+Channel Operator disclaimers, the agent must explain those points to the user and must not accept Terms or confirmations
+on the user's behalf.
+
+After reading the referenced `agents.md` items and Terms sections, translate the recipe into a short, safe instruction
+for the user.
+Do not ask users to paste raw private keys, wallet secrets, seed phrases, provider passwords, or provider dashboard
+access into a conversation or prompt. Use the CLI's local helper commands for secret source files.
+
+Human `private-state-cli help guide` output is for people. It provides one plain next step. User-Controlled AI Agents
+should prefer `help guide --json` when deciding what to read and what safe instruction to give next.
+
+When `--json` is used, the CLI follows one output contract for all commands:
+
+- the final success result is one JSON object on stdout
+- command failures are one JSON object on stdout with `ok: false`
+- progress, warning, and informational events are JSON Lines on stderr
+- human-readable mode remains the default when `--json` is omitted
+- Terms-gated `install --json` reports that browser-based interactive Terms acceptance is required, includes Terms
+  references, and does not install artifacts
+- install results include canonical Terms metadata: `termsVersion`, `termsHash`, `termsHashAlgorithm`, and Terms source
+  paths
+
+Agents should parse stdout for the final result and may stream stderr JSONL events to explain progress to the user.
 
 ## Artifacts