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

package/lib/private-state-cli-command-registry.mjs

@@ -53,6 +53,7 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     type: "text",
     placeholder: "my-account",
     valueLabel: "<NAME>",
+    hint: "Local account alias. Omit it on supported commands to use a MetaMask-compatible browser wallet instead.",
     option: "--account",
   },
   leaderAccount: {
@@ -69,7 +70,7 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     type: "text",
     placeholder: "relayer-account",
     valueLabel: "<ACCOUNT>",
-    hint: "Optional for proof-backed note commands. Uses a separate local L1 account to submit executeChannelTransaction.",
+    hint: "Optional for proof-backed note commands. Use --tx-submitter <ACCOUNT> for a local submitter, or --tx-submitter without a value for browser-wallet submission of executeChannelTransaction.",
     option: "--tx-submitter",
     optional: true,
   },
@@ -99,7 +100,7 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
   wallet: {
     label: "Wallet Name",
     type: "text",
-    placeholder: "channel-0xYourL1Address",
+    placeholder: "channel-0xYourEthereumAddress",
     valueLabel: "<NAME>",
     option: "--wallet",
   },
@@ -110,6 +111,13 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     valueLabel: "<PATH>",
     option: "--output",
   },
+  random: {
+    label: "Random Secret",
+    type: "checkbox",
+    hint: "Generate a random wallet secret instead of prompting the user to type one.",
+    option: "--random",
+    optional: true,
+  },
   exportEvidence: {
     label: "Evidence ZIP",
     type: "text",
@@ -119,19 +127,6 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     option: "--export-evidence",
     optional: true,
   },
-  acknowledgeFullNotePlaintextExport: {
-    label: "Acknowledge Note Plaintext Export",
-    type: "checkbox",
-    hint: "Required with --export-evidence. Confirms that all locally known note plaintext will be written to the ZIP.",
-    option: "--acknowledge-full-note-plaintext-export",
-    optional: true,
-  },
-  acknowledgeActionImpact: {
-    label: "Acknowledge Action Impact",
-    type: "checkbox",
-    hint: "Required for transaction-sending bridge, channel, and note commands. Confirms that the user reviewed the public/private action-impact warning.",
-    option: "--acknowledge-action-impact",
-  },
   input: {
     label: "Input File",
     type: "text",
@@ -165,9 +160,9 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
   recipients: {
     label: "Recipients JSON",
     type: "textarea",
-    placeholder: "[\"0xRecipientL2Address\"]",
+    placeholder: "[\"0xRecipientChannelAddress\"]",
     valueLabel: "<JSON_ARRAY>",
-    hint: "JSON array of recipient L2 addresses. Its length must match --amounts.",
+    hint: "JSON array of recipient channel-local addresses. Its length must match --amounts.",
     option: "--recipients",
   },
   docker: {
@@ -207,6 +202,20 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     option: "--read-only",
     optional: true,
   },
+  terminalTerms: {
+    label: "Terminal Terms Acceptance",
+    type: "checkbox",
+    hint: "Use terminal-only Terms acceptance instead of the default local browser Terms page.",
+    option: "--terminal-terms",
+    optional: true,
+  },
+  includeWalletKeys: {
+    label: "Include Wallet Keys",
+    type: "checkbox",
+    hint: "With uninstall, delete wallet spending-key and viewing-key files instead of preserving them.",
+    option: "--include-wallet-keys",
+    optional: true,
+  },
   fromGenesis: {
     label: "Scan From Genesis",
     type: "checkbox",
@@ -269,21 +278,31 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
 });
 
 const ACTION_IMPACT_HELP = Object.freeze({
-  acknowledgement: "Requires --acknowledge-action-impact after the user reviews the action-impact warning.",
+  warningSummary: "The CLI shows a warning summary before the command proceeds; User-Controlled AI Agents must not accept Terms or confirmations for the user.",
   illegalUse: "The command must not be used for money laundering, sanctions evasion, terrorist financing, illegal gambling, criminal-proceeds concealment, or regulatory evasion.",
-  secretRecovery: "Losing wallet secrets, viewing keys, or spending keys can prevent note discovery or note use; the CLI cannot recover lost secrets.",
+  secretRecovery: "Losing wallet secrets, viewing keys, or spending keys can prevent note discovery or note use; if all required secret material and backups are lost, no recovery method exists.",
   exchangeControlledAddress: "Do not use an exchange-controlled address as a self-custody bridge source or direct bridge withdrawal target.",
   policy: "The user must review the channel policy snapshot before accepting channel-bound actions.",
   provenance: "Public observers cannot reconstruct private note counterparty relationships or note provenance from public contract state alone.",
+  browserWalletAccount: "Omit --account to use a MetaMask-compatible browser wallet instead of a local account alias; the CLI does not read or store the raw L1 private key in this mode.",
+  browserWalletTxSubmitter: "Use --tx-submitter without a value when a browser wallet should submit executeChannelTransaction and pay gas.",
+  localL2Keys: "Browser-wallet L1 signing does not replace local wallet keys; note commands still use the local viewing key and spending key.",
 });
 
 export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
   {
     id: "install",
     description: "Install private-state CLI runtime artifacts in full or read-only mode.",
-    fields: ["readOnly", "docker", "includeLocalArtifacts", "groth16CliVersion", "tokamakZkEvmCliVersion"],
-    usage: "optional --read-only, --docker, --include-local-artifacts, --groth16-cli-version, and --tokamak-zk-evm-cli-version",
+    fields: ["network", "readOnly", "docker", "includeLocalArtifacts", "terminalTerms", "groth16CliVersion", "tokamakZkEvmCliVersion"],
+    optionalFields: ["network"],
+    usage: "optional --network, --read-only, --docker, --include-local-artifacts, --terminal-terms, --groth16-cli-version, and --tokamak-zk-evm-cli-version",
     help: [
+      "Use --network to install only that network's deployment artifacts",
+      "Mainnet install, or install without --network, opens a local browser Terms page and requires explicit human acceptance before installation proceeds",
+      "Sepolia and anvil installs do not require Terms acceptance",
+      "Use --terminal-terms only when the local browser flow cannot be used for a Terms-gated install",
+      "--json reports that browser-based interactive Terms acceptance is required for Terms-gated installs and does not install artifacts",
+      "Install results include the canonical Terms version and deterministic Terms hash",
       "Default full mode installs proof runtimes and all deployment artifacts needed by transaction-sending commands",
       "--read-only installs only artifacts needed by channel-state read commands and commands unrelated to channel state",
       "Version options install exact CLI package versions; omitted versions resolve to npm registry latest",
@@ -293,9 +312,14 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
   },
   {
     id: "uninstall",
-    description: "Interactively remove local private-state workspaces, wallet secrets, proof artifacts, Tokamak zk-EVM runtime data, and the global CLI package when installed.",
-    fields: [],
-    usage: "no options",
+    description: "Interactively remove local private-state CLI data. By default, wallet spending-key and viewing-key files are preserved.",
+    fields: ["includeWalletKeys"],
+    usage: "optional --include-wallet-keys",
+    help: [
+      "Default uninstall preserves wallet spending-key and viewing-key files under the CLI secret root",
+      "--include-wallet-keys deletes every local private-state CLI file, including wallet spending-key and viewing-key files",
+      "Both modes remove local workspaces, account secrets, wallet secret source files stored under the CLI root, proof artifacts, Tokamak zk-EVM runtime data, and the global CLI package when installed",
+    ],
   },
   {
     id: "set-rpc",
@@ -309,12 +333,42 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
       "All bridge-facing and wallet commands read RPC settings from this file and do not accept --rpc-url",
     ],
   },
+  {
+    id: "secret-create-private-key-source",
+    display: "secret create-private-key-source",
+    description: "Prompt for an Ethereum private key and write a local source file for account import.",
+    fields: ["output"],
+    usage: "--output",
+    help: [
+      "Prompts in the terminal with masked input and never prints the private key",
+      "Writes the source file with restrictive permissions where the operating system supports it",
+      "Refuses to overwrite an existing file",
+      "After creating the file, import it with account import --private-key-file",
+    ],
+  },
+  {
+    id: "secret-create-wallet-secret-source",
+    display: "secret create-wallet-secret-source",
+    description: "Prompt for a wallet secret, or explicitly generate a random one, and write a local source file for channel join.",
+    fields: ["output", "random"],
+    optionalFields: ["random"],
+    usage: "--output and optional --random",
+    help: [
+      "Prompts in the terminal with masked input by default so the user can type a memorable secret",
+      "Use --random only when the user explicitly wants a random wallet secret",
+      "Never prints the wallet secret and refuses to overwrite an existing file",
+      "After creating the file, pass it to channel join --wallet-secret-path",
+    ],
+  },
   {
     id: "help-commands",
     display: "help commands",
     description: "Show the private-state CLI command reference.",
-    fields: [],
-    usage: "no options",
+    fields: ["json"],
+    usage: "optional --json",
+    help: [
+      "Use --json to emit the full command reference as structured JSON on stdout.",
+    ],
   },
   {
     id: "help-update",
@@ -350,17 +404,20 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
       "Does not accept --rpc-url and never writes RPC configuration",
       "Recommends bridge deposits only after a wallet is joined and needs channel liquidity",
       "Channel leaders publish workspace mirror files through channel recover-workspace --publish-workspace-mirror, not a standalone publish command",
+      "Channel workspace mirror and observer URLs are read from on-chain Channel metadata when available",
     ],
   },
   {
     id: "help-observer",
     display: "help observer",
-    description: "Show the deployed public observer URL.",
-    fields: [],
-    usage: "no options",
+    description: "Show the public observer URL registered on-chain for a selected Channel.",
+    installMode: "read-only",
+    fields: ["network", "channelName", "json"],
+    usage: "--network, --channel-name, and optional --json",
     help: [
-      "Prints the deployed observer URL so terminals can present it as a clickable link",
-      "The observer is a public monitoring surface; it is not a wallet, key manager, or disclosure authority",
+      "Reads the selected Channel's observer URL from on-chain Channel metadata",
+      "Fails clearly when the Channel Provider has not registered an observer URL for that Channel",
+      "The observer is a Channel-scoped public monitoring surface; it is not a wallet, key manager, or disclosure authority",
     ],
   },
   {
@@ -372,7 +429,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     help: [
       "Uses packages/apps/private-state/cli/assets/tx-fees.json as the measured gas source packaged with the CLI",
       "Reads live fee data from the selected network RPC and live ETH/USD from CoinGecko",
-      "AI agents should run this command with --json when users ask about gas, transaction fees, transaction cost, or USD cost",
+      "Use --json for machine-readable fee data when another tool needs to inspect the fee table",
     ],
   },
   {
@@ -384,21 +441,26 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
       "Prints the local investigator HTML path and opens it in the default browser",
       "Use wallet get-notes --export-evidence first, then load the raw ZIP in the investigator GUI",
       "The raw evidence ZIP contains full locally known note plaintext and should not be submitted as-is unless full wallet-history disclosure is intended",
+      "Do not give the raw evidence ZIP to User-Controlled AI Agents, support channels, or untrusted parties",
     ],
   },
   {
     id: "account-import",
     display: "account import",
-    description: "Import a private-key source file into a protected local L1 account secret for later --account use.",
+    description: "Import a private-key source file into a protected local Ethereum account secret for later --account use.",
     fields: ["account", "network", "privateKeyFile"],
     usage: "--account, --network, and --private-key-file",
   },
   {
     id: "account-get-l1-address",
     display: "account get-l1-address",
-    description: "Derive the L1 address for a local account.",
+    description: "Read the Ethereum address from a local account alias or the browser wallet.",
     fields: ["account", "network"],
-    usage: "--network and --account",
+    optionalFields: ["account"],
+    usage: "--network and optional --account",
+    help: [
+      ACTION_IMPACT_HELP.browserWalletAccount,
+    ],
   },
   {
     id: "account-get-bridge-fund",
@@ -406,7 +468,11 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Read the local account's current shared bridge vault balance.",
     installMode: "read-only",
     fields: ["network", "account"],
-    usage: "--network, --account",
+    optionalFields: ["account"],
+    usage: "--network and optional --account",
+    help: [
+      ACTION_IMPACT_HELP.browserWalletAccount,
+    ],
   },
   {
     id: "channel-create",
@@ -414,8 +480,10 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Create a bridge channel and initialize its workspace.",
     installMode: "full",
     fields: ["channelName", "joinToll", "network", "account"],
-    usage: "--channel-name, --join-toll, --network, --account",
+    optionalFields: ["account"],
+    usage: "--channel-name, --join-toll, --network, and optional --account",
     help: [
+      ACTION_IMPACT_HELP.browserWalletAccount,
       "Prints the immutable policy snapshot before sending the transaction",
       "Initializes the local channel workspace by replaying channel logs from channel genesis",
     ],
@@ -451,16 +519,34 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Register or update the channel leader's workspace mirror base URL.",
     installMode: "full",
     fields: ["channelName", "network", "account", "url"],
-    usage: "--channel-name, --network, --account, --url",
+    optionalFields: ["account"],
+    usage: "--channel-name, --network, --url, and optional --account",
     help: [
+      ACTION_IMPACT_HELP.browserWalletAccount,
       "Only the on-chain channel leader can update the registered mirror URL",
       "The URL points to a server implementing the private-state channel workspace mirror protocol",
     ],
   },
+  {
+    id: "channel-abandon-operation",
+    display: "channel abandon-operation",
+    description: "Let the channel leader permanently stop new joins and channel deposits for a channel.",
+    installMode: "full",
+    fields: ["channelName", "network", "account"],
+    optionalFields: ["account"],
+    usage: "--channel-name, --network, and optional --account",
+    help: [
+      ACTION_IMPACT_HELP.browserWalletAccount,
+      "Only the on-chain channel leader can abandon channel operation",
+      "Abandonment is immediate after the transaction on the selected network is accepted",
+      "After abandonment, channel join and wallet deposit-channel are rejected for that channel",
+      "Abandonment does not block existing note activity, wallet redeem-notes, wallet withdraw-channel, or channel exit",
+    ],
+  },
   {
     id: "channel-get-meta",
     display: "channel get-meta",
-    description: "Read channel existence, manager, vault, toll, refund schedule, and immutable policy snapshot.",
+    description: "Read channel existence, manager, vault, Join Toll, refund schedule, operation status, and immutable policy snapshot.",
     installMode: "read-only",
     fields: ["channelName", "network"],
     usage: "--channel-name, --network",
@@ -470,14 +556,16 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     display: "account deposit-bridge",
     description: "Deposit canonical tokens into the shared bridge vault.",
     installMode: "read-only",
-    fields: ["amount", "network", "account", "acknowledgeActionImpact"],
-    usage: "--amount, --network, --account, --acknowledge-action-impact",
+    fields: ["amount", "network", "account"],
+    optionalFields: ["account"],
+    usage: "--amount, --network, and optional --account",
     help: [
-      "Action impact: emits public L1 approval and bridge funding events that expose the local L1 account, bridge vault, amount, and transaction hashes.",
-      "Private note state is not changed by this command; it does not pay a channel join toll.",
+      ACTION_IMPACT_HELP.browserWalletAccount,
+      "Warning summary: emits public Ethereum mainnet approval and bridge funding events that expose the local Ethereum account, bridge vault, amount, and transaction hashes.",
+      "Private note state is not changed by this command; it does not pay a channel Join Toll.",
       ACTION_IMPACT_HELP.exchangeControlledAddress,
       ACTION_IMPACT_HELP.illegalUse,
-      ACTION_IMPACT_HELP.acknowledgement,
+      ACTION_IMPACT_HELP.warningSummary,
     ],
   },
   {
@@ -485,14 +573,16 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     display: "account withdraw-bridge",
     description: "Withdraw tokens from the shared bridge vault back to the wallet.",
     installMode: "read-only",
-    fields: ["amount", "network", "account", "acknowledgeActionImpact"],
-    usage: "--amount, --network, --account, --acknowledge-action-impact",
+    fields: ["amount", "network", "account"],
+    optionalFields: ["account"],
+    usage: "--amount, --network, and optional --account",
     help: [
-      "Action impact: emits a public L1 bridge withdrawal event that exposes the local L1 recipient, bridge vault, amount, and transaction hash.",
+      ACTION_IMPACT_HELP.browserWalletAccount,
+      "Warning summary: emits a public Ethereum mainnet bridge withdrawal event that exposes the local Ethereum recipient, bridge vault, amount, and transaction hash.",
       "Private note state is not changed by this command; prior note provenance is not public by default.",
       ACTION_IMPACT_HELP.exchangeControlledAddress,
       ACTION_IMPACT_HELP.illegalUse,
-      ACTION_IMPACT_HELP.acknowledgement,
+      ACTION_IMPACT_HELP.warningSummary,
     ],
   },
   {
@@ -501,13 +591,14 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Rebuild a recoverable local wallet from on-chain channel state.",
     installMode: "read-only",
     fields: ["channelName", "network", "account", "walletSecretPath", "fromGenesis"],
-    optionalFields: ["walletSecretPath"],
-    usage: "--channel-name, --network, --account, optional --wallet-secret-path, optional --from-genesis",
+    optionalFields: ["account", "walletSecretPath"],
+    usage: "--channel-name, --network, optional --account, optional --wallet-secret-path, optional --from-genesis",
     help: [
+      ACTION_IMPACT_HELP.browserWalletAccount,
       "Rebuilds backup metadata from channel state without recreating the spending key by default",
-      "Derives and stores the viewing key when the local account signer can reproduce the registered viewing public key",
+      "Derives and stores the viewing key when the selected L1 signer can reproduce the registered viewing public key",
       "Use --wallet-secret-path only for an active channel registration when you need to rederive and store the spending key",
-      "--wallet-secret-path requires the derived spending key to match the current on-chain L2 address and storage key before note recovery starts",
+      "--wallet-secret-path requires the derived spending key to match the current on-chain channel-local address and storage key before note recovery starts",
       "Exited or non-active accounts can be recovered for viewing/evidence history only; omit --wallet-secret-path for those wallets",
       "Before wallet recovery, refreshes stale channel workspace state only when the saved recovery index delta fits the pre-command budget",
       "Fails and asks for channel recover-workspace first when the channel workspace is missing, unusable, or too stale for automatic recovery",
@@ -519,22 +610,26 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
   {
     id: "channel-join",
     display: "channel join",
-    description: "Pay the channel join toll and bind a wallet to a channel-specific L2 identity.",
+    description: "Pay the channel Join Toll, the one-time Channel entry fee, and bind a wallet to a channel-specific private application identity.",
     installMode: "full",
-    fields: ["channelName", "network", "account", "walletSecretPath", "acknowledgeActionImpact"],
-    usage: "--channel-name, --network, --account, --wallet-secret-path, --acknowledge-action-impact",
+    fields: ["channelName", "network", "account", "walletSecretPath"],
+    optionalFields: ["account"],
+    usage: "--channel-name, --network, --wallet-secret-path, and optional --account",
     help: [
+      ACTION_IMPACT_HELP.browserWalletAccount,
       "Refreshes the local channel workspace through the saved recovery index before joining when the scan fits the 7,200-block pre-command budget",
       "Fails instead of replaying from genesis; recover from a registered workspace mirror first, and use channel recover-workspace --source rpc --from-genesis only when no compatible mirror is available",
-      "--wallet-secret-path is read once for channel-bound L2 spending-key derivation and is not stored in the wallet workspace",
-      "Pays any join toll directly from the L1 wallet, not from bridge-deposited balance",
+      "--wallet-secret-path is read once for channel-bound spending-key derivation and is not stored in the wallet workspace",
+      "With browser-wallet mode, the user approves account connection, chain check, the L2 spending-key message signature, the note-receive viewing-key typed-data signature, any Join Toll token approval, and the join transaction in the browser wallet",
+      "Pays any Join Toll directly from the Ethereum wallet, not from bridge-deposited balance",
+      "Fails when the selected channel has been abandoned",
       "Prints the immutable policy snapshot before first registration",
-      "Action impact: emits public channel join and token-vault registration events exposing the L1 account, L2 address pair, note-receive public key, join toll, and channel id.",
+      "Warning summary: emits public channel join and token-vault registration events exposing the Ethereum account, channel-local address pair, note-receive public key, Join Toll, and channel id.",
       "Private note state is not changed by this command.",
       ACTION_IMPACT_HELP.policy,
       ACTION_IMPACT_HELP.secretRecovery,
       ACTION_IMPACT_HELP.illegalUse,
-      ACTION_IMPACT_HELP.acknowledgement,
+      ACTION_IMPACT_HELP.warningSummary,
     ],
   },
   {
@@ -565,7 +660,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "--network, --wallet, and --output",
     help: [
       "Includes wallet note-tracking metadata, public key metadata, and channel workspace cache",
-      "Excludes L1 private keys, L2 spending keys, viewing private keys, wallet secrets, owner, value, and salt",
+      "Excludes Ethereum private keys, spending keys, viewing private keys, wallet secrets, owner, value, and salt",
     ],
   },
   {
@@ -574,21 +669,36 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Export a secret .key file containing the wallet viewing private key and public viewing-key metadata.",
     fields: ["network", "wallet", "output"],
     usage: "--network, --wallet, and --output",
+    help: [
+      "Requires an interactive terminal on mainnet because the output file contains secret-bearing viewing authority",
+      "Sepolia and anvil exports do not require interactive confirmation",
+      "Anyone with the exported file may be able to read and reconstruct note history addressed to this wallet when other required wallet state is available",
+      "User-Controlled AI Agents must not confirm this export or receive the exported key file",
+    ],
   },
   {
     id: "wallet-export-spending-key",
     display: "wallet export spending-key",
-    description: "Export a secret .key file containing the wallet L2 spending private key and public spending-key metadata.",
+    description: "Export a secret .key file containing the wallet spending private key and public spending-key metadata.",
     fields: ["network", "wallet", "output"],
     usage: "--network, --wallet, and --output",
+    help: [
+      "Requires an interactive terminal on mainnet because the output file contains secret-bearing spending authority",
+      "Sepolia and anvil exports do not require interactive confirmation",
+      "Anyone with the exported file may be able to spend, transfer, or redeem Private Notes when other required wallet state is available",
+      "User-Controlled AI Agents must not confirm this export or receive the exported key file",
+    ],
   },
   {
     id: "wallet-import-backup",
     display: "wallet import backup",
     description: "Import a backup ZIP created by wallet export backup.",
-    fields: ["input"],
-    usage: "--input",
+    fields: ["input", "network"],
+    optionalFields: ["network"],
+    usage: "--input and optional --network",
     help: [
+      "Use --network anvil or --network sepolia for non-mainnet imports that should not require Service Terms acceptance",
+      "Mainnet imports, and imports without a network selector, require current Service Terms acceptance",
       "Refuses to overwrite existing wallet metadata or workspace cache files",
       "Does not grant viewing or spending authority; import the corresponding key files separately when needed",
     ],
@@ -597,59 +707,62 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "wallet-import-viewing-key",
     display: "wallet import viewing-key",
     description: "Import a secret .key file created by wallet export viewing-key.",
-    fields: ["input"],
-    usage: "--input",
+    fields: ["input", "network"],
+    optionalFields: ["network"],
+    usage: "--input and optional --network",
   },
   {
     id: "wallet-import-spending-key",
     display: "wallet import spending-key",
     description: "Import a secret .key file created by wallet export spending-key.",
-    fields: ["input"],
-    usage: "--input",
+    fields: ["input", "network"],
+    optionalFields: ["network"],
+    usage: "--input and optional --network",
   },
   {
     id: "wallet-deposit-channel",
     display: "wallet deposit-channel",
-    description: "Move bridged funds into the channel L2 accounting balance.",
+    description: "Move bridged funds into the channel accounting balance.",
     installMode: "full",
-    fields: ["wallet", "network", "amount", "acknowledgeActionImpact"],
-    usage: "--wallet, --network, --amount, and --acknowledge-action-impact",
+    fields: ["wallet", "network", "amount"],
+    usage: "--wallet, --network, --amount",
     help: [
       "Refreshes the local channel workspace through the saved recovery index before proving the deposit when the scan fits the 7,200-block pre-command budget",
-      "Action impact: emits public proof-backed bridge/channel accounting events exposing the L1 submitter, registered L2 address, amount, channel id, and transaction hash.",
+      "Fails when the selected channel has been abandoned",
+      "Warning summary: emits public proof-backed bridge/channel accounting events exposing the Ethereum submitter, registered channel-local address, amount, channel id, and transaction hash.",
       "Private note state is not changed by this command.",
       ACTION_IMPACT_HELP.policy,
       ACTION_IMPACT_HELP.secretRecovery,
       ACTION_IMPACT_HELP.illegalUse,
-      ACTION_IMPACT_HELP.acknowledgement,
+      ACTION_IMPACT_HELP.warningSummary,
     ],
   },
   {
     id: "wallet-withdraw-channel",
     display: "wallet withdraw-channel",
-    description: "Move channel L2 balance back into the shared bridge vault.",
+    description: "Move channel balance back into the shared bridge vault.",
     installMode: "full",
-    fields: ["wallet", "network", "amount", "acknowledgeActionImpact"],
-    usage: "--wallet, --network, --amount, and --acknowledge-action-impact",
+    fields: ["wallet", "network", "amount"],
+    usage: "--wallet, --network, --amount",
     help: [
       "Refreshes the local channel workspace through the saved recovery index before proving the withdrawal when the scan fits the 7,200-block pre-command budget",
-      "Action impact: emits public proof-backed bridge/channel accounting events exposing the L1 submitter, registered L2 address, amount, channel id, and transaction hash.",
+      "Warning summary: emits public proof-backed bridge/channel accounting events exposing the Ethereum submitter, registered channel-local address, amount, channel id, and transaction hash.",
       "Private note state is not changed by this command; prior note provenance is not public by default.",
       ACTION_IMPACT_HELP.provenance,
       ACTION_IMPACT_HELP.policy,
       ACTION_IMPACT_HELP.secretRecovery,
       ACTION_IMPACT_HELP.illegalUse,
-      ACTION_IMPACT_HELP.acknowledgement,
+      ACTION_IMPACT_HELP.warningSummary,
     ],
   },
   {
     id: "wallet-get-channel-fund",
     display: "wallet get-channel-fund",
-    description: "Read the current channel L2 accounting balance.",
+    description: "Read the current channel accounting balance.",
     installMode: "read-only",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
-    help: ["Refreshes the local channel workspace through the saved recovery index before reading the L2 accounting balance when the scan fits the 7,200-block pre-command budget"],
+    help: ["Refreshes the local channel workspace through the saved recovery index before reading the channel accounting balance when the scan fits the 7,200-block pre-command budget"],
   },
   {
     id: "channel-exit",
@@ -660,6 +773,13 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "--wallet and --network",
     help: [
       "Refreshes the local channel workspace through the saved recovery index before checking the channel balance when the scan fits the 7,200-block pre-command budget",
+      "Warning summary: emits public channel exit and Join Toll refund events exposing the Ethereum account, channel id, refund quote, transaction hash, and wallet registration exit status.",
+      "Private note plaintext and prior note provenance are not public by default, but the wallet epoch is locally marked as exited.",
+      ACTION_IMPACT_HELP.provenance,
+      ACTION_IMPACT_HELP.policy,
+      ACTION_IMPACT_HELP.secretRecovery,
+      ACTION_IMPACT_HELP.illegalUse,
+      ACTION_IMPACT_HELP.warningSummary,
       "Marks the current local wallet epoch as exited and keeps its note metadata available for historical evidence export",
     ],
   },
@@ -668,19 +788,21 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     display: "wallet mint-notes",
     description: "Mint one or two private-state notes from the wallet's channel balance.",
     installMode: "full",
-    fields: ["wallet", "network", "amounts", "acknowledgeActionImpact", "txSubmitter"],
-    usage: "--wallet, --network, --amounts, --acknowledge-action-impact, and optional --tx-submitter",
+    fields: ["wallet", "network", "amounts", "txSubmitter"],
+    usage: "--wallet, --network, --amounts, and optional --tx-submitter",
     help: [
       "Refreshes the local channel workspace through the saved recovery index before proving the mint when the scan fits the 7,200-block pre-command budget",
       "Requires both viewing and spending key capability so the accepted mint can be recovered through the normal note event path",
-      "Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy",
-      "Action impact: emits public accepted-transition, commitment, encrypted note-delivery, root update, and transaction events.",
+      "Use --tx-submitter <ACCOUNT> when a separate local Ethereum account should submit the transaction and pay gas",
+      ACTION_IMPACT_HELP.browserWalletTxSubmitter,
+      ACTION_IMPACT_HELP.localL2Keys,
+      "Warning summary: emits public accepted-transition, commitment, encrypted note-delivery, root update, and transaction events.",
       "Private note state changes by creating local note plaintext and public commitments; note owner/value/salt are not public by default.",
       ACTION_IMPACT_HELP.provenance,
       ACTION_IMPACT_HELP.policy,
       ACTION_IMPACT_HELP.secretRecovery,
       ACTION_IMPACT_HELP.illegalUse,
-      ACTION_IMPACT_HELP.acknowledgement,
+      ACTION_IMPACT_HELP.warningSummary,
     ],
   },
   {
@@ -688,23 +810,25 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     display: "wallet transfer-notes",
     description: "Spend input notes into the registered 1->1, 1->2, or 2->1 private transfer shapes.",
     installMode: "full",
-    fields: ["wallet", "network", "noteIds", "recipients", "amounts", "acknowledgeActionImpact", "txSubmitter"],
-    usage: "--wallet, --network, --note-ids <JSON_ARRAY>, --recipients <JSON_ARRAY>, --amounts <JSON_ARRAY>, --acknowledge-action-impact, and optional --tx-submitter",
+    fields: ["wallet", "network", "noteIds", "recipients", "amounts", "txSubmitter"],
+    usage: "--wallet, --network, --note-ids <JSON_ARRAY>, --recipients <JSON_ARRAY>, --amounts <JSON_ARRAY>, and optional --tx-submitter",
     help: [
       "--note-ids must be a JSON array of input note commitment IDs from wallet get-notes, for example '[\"0xNOTE1\",\"0xNOTE2\"]'",
-      "--recipients must be a JSON array of recipient L2 addresses, for example '[\"0xL2RECIPIENT1\",\"0xL2RECIPIENT2\"]'",
+      "--recipients must be a JSON array of recipient channel-local addresses, for example '[\"0xRECIPIENT1\",\"0xRECIPIENT2\"]'",
       "--amounts must be a JSON array of token amounts, preferably quoted for decimals, for example '[\"1.5\",\"2\"]'",
       "--recipients length must equal --amounts length; supported transfer shapes are 1->1, 1->2, and 2->1",
       "The sum of output amounts must equal the sum of the selected input note values",
       "Refreshes the local channel workspace and received-note logs through saved recovery indexes before proving the transfer when scans fit the 7,200-block pre-command budget",
-      "Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy",
-      "Action impact: emits public accepted-transition, input nullifier, output commitment, encrypted note-delivery, root update, and transaction events.",
+      "Use --tx-submitter <ACCOUNT> when a separate local Ethereum account should submit the transaction and pay gas",
+      ACTION_IMPACT_HELP.browserWalletTxSubmitter,
+      ACTION_IMPACT_HELP.localL2Keys,
+      "Warning summary: emits public accepted-transition, input nullifier, output commitment, encrypted note-delivery, root update, and transaction events.",
       "Private note state changes by consuming selected input notes and creating output notes; sender-recipient relationship, note plaintext, and note provenance are not public by default.",
       ACTION_IMPACT_HELP.provenance,
       ACTION_IMPACT_HELP.policy,
       ACTION_IMPACT_HELP.secretRecovery,
       ACTION_IMPACT_HELP.illegalUse,
-      ACTION_IMPACT_HELP.acknowledgement,
+      ACTION_IMPACT_HELP.warningSummary,
     ],
   },
   {
@@ -712,18 +836,20 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     display: "wallet redeem-notes",
     description: "Redeem one tracked note back into the wallet's channel balance.",
     installMode: "full",
-    fields: ["wallet", "network", "noteIds", "acknowledgeActionImpact", "txSubmitter"],
-    usage: "--wallet, --network, --note-ids, --acknowledge-action-impact, and optional --tx-submitter",
+    fields: ["wallet", "network", "noteIds", "txSubmitter"],
+    usage: "--wallet, --network, --note-ids, and optional --tx-submitter",
     help: [
       "Refreshes the local channel workspace and received-note logs through saved recovery indexes before proving the redeem when scans fit the 7,200-block pre-command budget",
-      "Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy",
-      "Action impact: emits public accepted-transition, note nullifier, accounting update, root update, and transaction events.",
+      "Use --tx-submitter <ACCOUNT> when a separate local Ethereum account should submit the transaction and pay gas",
+      ACTION_IMPACT_HELP.browserWalletTxSubmitter,
+      ACTION_IMPACT_HELP.localL2Keys,
+      "Warning summary: emits public accepted-transition, note nullifier, accounting update, root update, and transaction events.",
       "Private note state changes by consuming selected notes; prior note provenance is not public by default.",
       ACTION_IMPACT_HELP.provenance,
       ACTION_IMPACT_HELP.policy,
       ACTION_IMPACT_HELP.secretRecovery,
       ACTION_IMPACT_HELP.illegalUse,
-      ACTION_IMPACT_HELP.acknowledgement,
+      ACTION_IMPACT_HELP.warningSummary,
     ],
   },
   {
@@ -731,14 +857,16 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     display: "wallet get-notes",
     description: "Refresh received notes when the saved recovery index is recent, then show tracked note state.",
     installMode: "read-only",
-    fields: ["wallet", "network", "exportEvidence", "acknowledgeFullNotePlaintextExport"],
-    usage: "--wallet, --network, optional --export-evidence, and optional --acknowledge-full-note-plaintext-export",
+    fields: ["wallet", "network", "exportEvidence"],
+    usage: "--wallet, --network, and optional --export-evidence",
     help: [
       "Refreshes the local channel workspace through the saved recovery index before reading notes when the scan fits the 7,200-block pre-command budget",
       "Refreshes received-note logs through the saved wallet note recovery index when the scan fits the 7,200-block pre-command budget",
       "Fails instead of replaying from genesis; run wallet recover-workspace first when explicit wallet recovery is required",
-      "Use --export-evidence <PATH> with --acknowledge-full-note-plaintext-export to write a local full-note evidence ZIP for private-state-cli investigator",
-      "Evidence export includes all local epochs for the selected wallet, including exited epochs retained for dispute evidence",
+      "Use --export-evidence <PATH> to write a local full-note evidence ZIP for private-state-cli investigator; mainnet export requires interactive confirmation",
+      "Sepolia and anvil evidence exports do not require interactive confirmation",
+      "The raw evidence ZIP may include plaintext note facts for all locally known notes and retained exited epochs for the selected wallet",
+      "User-Controlled AI Agents must not confirm this export or receive the raw evidence ZIP",
     ],
   },
 ]);