@tokamak-private-dapps/private-state-cli 1.2.1 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## Unreleased
+
+## 2.1.0 - 2026-05-14
+
+- Required current epoch-aware wallet workspaces for wallet commands and backup imports. Local
+  wallet metadata must include the wallet index and epoch metadata; users with older local
+  workspaces should rebuild them with `wallet recover-workspace`.
+- Required current epoch-aware evidence bundle note paths in the investigator and removed the
+  special-case legacy evidence layout branch.
+- Consolidated the static evidence investigator into the CLI package under `cli/investigator/`
+  and removed the duplicate top-level investigator copy.
+- Simplified wallet command argument validation by removing unused schema fallback wrappers.
+
+## 2.0.0 - 2026-05-13
+
+- Split wallet export/import into `wallet export backup`, `wallet export viewing-key`,
+  `wallet export spending-key`, `wallet import backup`, `wallet import viewing-key`, and
+  `wallet import spending-key`.
+- Changed wallet backups so they exclude spending keys, viewing keys, key derivation material,
+  and plaintext note `owner`, `value`, and `salt` fields. Backups retain commitments,
+  nullifiers, encrypted note payloads, and channel workspace cache files.
+- Replaced the previous full-control wallet workspace format with separate note-tracking,
+  spending-key metadata, and viewing-key metadata files. The CLI now loads only the current
+  wallet metadata format.
+- Added action-impact acknowledgements for bridge-facing, channel, and note-mutating commands.
+  The warning output covers public event exposure, private note-state impact, note provenance
+  boundaries, illegal-use prohibition, CEX deposit-address warnings, secret-recovery limits, and
+  channel policy acceptance.
+- Added full-note raw evidence export through `wallet get-notes --export-evidence` with an explicit
+  plaintext-export acknowledgement. Evidence bundles include note plaintext facts, derived
+  commitments and nullifiers, creation/spend transaction references, receipts, events, calldata, and
+  filtering indexes, while excluding viewing keys, spending keys, wallet secrets, account private
+  keys, and `.key` files.
+- Made local wallet workspaces epoch-aware. `channel exit` now marks the active wallet epoch as
+  exited and retains its local note metadata instead of deleting the wallet workspace, while
+  `wallet recover-workspace` and `wallet get-notes --export-evidence` can still use retained exited
+  epochs for historical disclosure.
+- Added a local static evidence investigator GUI and bundled it with the NPM package. The new
+  top-level `private-state-cli investigator` command prints the bundled HTML path, prints the file
+  URL, and opens the GUI in the default browser.
+- Clarified wallet authority recovery in the NPM README: viewing-key rederivation needs the original
+  L1 private key and channel context, while spending-key rederivation additionally needs the same
+  wallet secret source used at `channel join`.
+- Added a `channel join` success warning that losing both the spending-key file and wallet secret
+  source prevents spending-key rederivation.
+- Aligned README terminology around `private-state DApp`, `private-state CLI`, `viewing key`,
+  `spending key`, `wallet secret source`, `user-controlled selective disclosure`, and
+  `privacy-preserving note semantics`.
+- Added LLM-assistant guidance requiring strong user warnings and explicit confirmation before an
+  assistant runs commands that require `--acknowledge-*` options on a user's behalf.
+- Simplified internal CLI code paths by removing a dead `loadWallet` parameter and redundant
+  `channel join` result aliases.
+
 ## 1.2.1 - 2026-05-11
 
 - Changed pre-command automatic recovery from an RPC log request time estimate to a fixed

package/README.md

@@ -6,6 +6,35 @@ The full private-state DApp documentation is published with the repository:
 
 - https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/tree/main/packages/apps/private-state/docs
 
+## Terminology And CEX 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 a centralized-exchange deposit address.
+- `L1-transparent bridge edge`: public 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.
+- `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.
+- `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.
+
+Tokamak Private App Channels are not a centralized-exchange deposit network. CEX-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.
+
+## Tokamak-Operated Mainnet Channels
+
+The table below lists private-state mainnet channels directly opened by Tokamak Network. Dates are
+UTC.
+
+| Channel name | Channel creator / leader | Created at | Genesis block | Channel manager |
+| --- | --- | --- | ---: | --- |
+| `the-great-first-channel` | [`0x32e6EE3d9820F0843E3e596132368747d36425F0`](https://etherscan.io/address/0x32e6EE3d9820F0843E3e596132368747d36425F0) | 2026-05-04 01:30:59 UTC | `25018368` | [`0x3108d92A38bFb4B3396DE7ad4D92318a8fbE61D7`](https://etherscan.io/address/0x3108d92A38bFb4B3396DE7ad4D92318a8fbE61D7) |
+
 ## Install
 
 ```bash
@@ -75,8 +104,8 @@ 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/`, the Tokamak zk-EVM runtime cache, and the global CLI npm package when npm reports that it
-is globally installed.
+`~/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.
 
 ## Commands
 
@@ -97,6 +126,31 @@ A common private-state flow is:
 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.
 
+### Action-impact acknowledgement
+
+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.
+
+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` and `account withdraw-bridge` also print a centralized-exchange address warning. Do not use a
+centralized-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.
+
 Workspace recovery commands use the saved recovery index by default. If the local workspace is missing, corrupted, or
 does not contain a usable index, `channel recover-workspace` and `wallet recover-workspace` stop with an explicit error instead of
 silently replaying logs from channel genesis. Use `--source rpc --from-genesis` only when you intentionally want to
@@ -122,6 +176,16 @@ channel genesis and only runs when the recovery delta fits within the 7,200-bloc
 is missing, unusable, or too far behind, the command stops and asks the user to run the appropriate recovery command
 with `--from-genesis` explicitly when needed.
 
+Local wallet workspaces are epoch-aware. Each successful channel registration creates a wallet epoch under the
+canonical wallet directory. `channel exit` does not delete the local wallet workspace; it marks the active epoch as
+exited with the exit transaction, block, and timestamp, then keeps that epoch read-only for historical note inspection
+and evidence export. If the same account later joins the same channel again, the new registration is a separate active
+epoch under the same canonical wallet name.
+
+The current CLI only supports this epoch-aware wallet workspace layout. If a local wallet directory was created by an
+older CLI and does not contain `wallet-index.metadata.json` plus `epochs/<epoch-id>/` metadata files, rebuild it with
+`wallet recover-workspace` before using wallet commands.
+
 Channel leaders can optionally register a workspace mirror server so users can bootstrap recovery
 from a signed checkpoint and download only the local-to-checkpoint delta when a local recovery index
 already exists. The channel leader can build the static mirror files with
@@ -134,33 +198,63 @@ https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/blob/main/packages/a
 Back up a local wallet with:
 
 ```bash
-private-state-cli wallet export --network mainnet --wallet <WALLET> --output ./wallet-backup.zip
+private-state-cli wallet export backup --network mainnet --wallet <WALLET> --output ./wallet-backup.zip
 ```
 
-The default export stores the encrypted wallet, wallet metadata, and wallet-local secret. The encrypted `wallet.json`
-contains the wallet's current key material and tracked note state. The export intentionally excludes account secrets
-because wallet commands restore the L1 signer from the encrypted `wallet.json`; account secrets are only needed for
-account-level bridge-vault commands and optional `--tx-submitter` use. After importing a default export on a new machine,
-run `channel recover-workspace` before using wallet commands that need channel state:
+The backup export stores note-tracking metadata and the channel workspace cache, but it does not include spending keys,
+viewing keys, key derivation material, or plaintext note secrets. Note records in the backup keep commitments,
+nullifiers, and encrypted note payloads only; `owner`, `value`, and `salt` are excluded.
+Importing this backup restores encrypted tracking state and channel cache files, not wallet authority.
 
 ```bash
-private-state-cli wallet import --input ./wallet-backup.zip
-private-state-cli channel recover-workspace --channel-name <CHANNEL> --network mainnet --source rpc --from-genesis
+private-state-cli wallet import backup --input ./wallet-backup.zip
+```
+
+Export viewing and spending authority separately:
+
+```bash
+private-state-cli wallet export viewing-key --network mainnet --wallet <WALLET> --output ./wallet-viewing.key
+private-state-cli wallet export spending-key --network mainnet --wallet <WALLET> --output ./wallet-spending.key
 ```
 
-For a wider backup that can run wallet commands immediately when the imported channel workspace cache is still
-chain-aligned, add `--include-notes`:
+Import those capabilities only when the target machine should receive them:
 
 ```bash
-private-state-cli wallet export --network mainnet --wallet <WALLET> --output ./wallet-backup.zip --include-notes
+private-state-cli wallet import viewing-key --input ./wallet-viewing.key
+private-state-cli wallet import spending-key --input ./wallet-spending.key
 ```
 
-Use `--all` to export every local mainnet wallet into one ZIP:
+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
+commands that submit bridge or channel-registration transactions.
+
+Export a local full-note evidence bundle with:
 
 ```bash
-private-state-cli wallet export --all --output ./mainnet-wallets.zip
+private-state-cli wallet get-notes --network mainnet --wallet <WALLET> --export-evidence ./wallet-evidence.zip --acknowledge-full-note-plaintext-export
 ```
 
+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
+raw ZIP as an exchange or auditor package unless full wallet-history disclosure is intended.
+
+Open the local evidence investigator with:
+
+```bash
+private-state-cli investigator
+```
+
+The command prints the bundled investigator HTML path and file URL, then opens the static browser GUI. Load the raw
+evidence ZIP in that GUI, apply the requested filters, and export a narrower user-consent disclosure ZIP. 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
+the wallet workspace with `wallet recover-workspace` and export a new bundle with `wallet get-notes --export-evidence`.
+
 Estimate live transaction costs before sending commands with:
 
 ```bash
@@ -175,13 +269,13 @@ data.
 Proof-backed note commands can use a separate L1 transaction submitter:
 
 ```bash
-private-state-cli wallet mint-notes --wallet <WALLET> --network mainnet --amounts '[1]' --tx-submitter <ACCOUNT>
+private-state-cli wallet mint-notes --wallet <WALLET> --network mainnet --amounts '[1]' --acknowledge-action-impact --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 you want stronger privacy by avoiding a direct on-chain link between the note owner's wallet L1
-account and the proof-submission transaction.
+Use this option when a separate imported local account should submit the L1 transaction and pay gas for a proof-backed
+note command.
 
 Channel policy warning:
 
@@ -208,34 +302,67 @@ private-state-cli account import --account <ACCOUNT_NAME> --network sepolia --pr
 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 --network sepolia --wallet <WALLET_NAME> --output ./wallet-backup.zip
-private-state-cli wallet import --input ./wallet-backup.zip
+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
 ```
 
 `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` imports `--wallet-secret-path <PATH>` into the protected wallet-local default secret while creating the
-encrypted local wallet. `wallet list` reads only the local workspace and prints saved wallet names that can be reused with
+`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 an encrypted local wallet and reports the stored L1/L2 identity metadata plus the current
-on-chain channel registration match state. `account get-l1-address` is a simple offline helper that derives the L1
-address for a local account.
+`wallet get-meta` opens the wallet metadata and reports the stored L1/L2 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.
 
 ### 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 and imports into the protected
-wallet-local canonical secret.
+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.
 
 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
+private-state-cli channel join --channel-name <CHANNEL> --network sepolia --account <ACCOUNT> --wallet-secret-path ./wallet-secret.txt --acknowledge-action-impact
 ```
 
-The import source file does not need `0600` permissions. The canonical wallet-local secret written by the CLI remains
-protected: macOS/Linux uses `0600`, while Windows uses ACL repair and inspection when possible.
+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
+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.
+
+### Wallet Backup, Viewing, And Spending Authority
+
+The wallet workspace is split so that a backup is not a full-control wallet export. Backup metadata stores the
+recoverable local view of the channel: commitments, nullifiers, encrypted note-delivery payloads, scan checkpoints,
+operation history, and the channel workspace cache. It deliberately omits plaintext note fields and key material.
+
+The viewing key is the note-receive private key. It lets `wallet get-notes` decrypt bridge-propagated encrypted
+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
+that consume existing notes, such as `wallet transfer-notes` and `wallet redeem-notes`, need both the viewing key and
+the spending key because the CLI must first reconstruct the plaintext notes and then prove authorized use of them.
+
+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
+secret source used at `channel join`. 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.
 
 ## Workspace
 
@@ -245,8 +372,8 @@ The CLI stores user workspaces under:
 ~/tokamak-private-channels/workspace/<network>/<channel>/
 ```
 
-Wallet data is encrypted with the wallet-local default secret file under
-`~/tokamak-private-channels/secrets/<network>/wallets/<wallet>/secret`.
+Wallet backup metadata lives under the channel workspace. Viewing and spending private keys live as separate protected
+key files under `~/tokamak-private-channels/secrets/<network>/wallets/<wallet>/`.
 
 Bridge-facing commands accept optional `--rpc-url <URL>`. When `--rpc-url` is provided, the CLI stores it in
 `~/tokamak-private-channels/secrets/<network>/.env` as `RPC_URL=<URL>` with protected canonical secret permissions.
@@ -257,16 +384,19 @@ When `--rpc-url` is omitted, the CLI reads `RPC_URL` from that file. The `anvil`
 ## LLM Agent Guidance
 
 You may act as an interactive guide for users who do not understand this CLI or the private-state DApp. Assume the
-user only knows that the DApp is a way to send funds privately. Translate the user's intent into safe, step-by-step CLI
-actions.
+user wants to use confidential channel-local notes while keeping L1 bridge deposits and withdrawals transparent.
+Translate the user's intent into safe, step-by-step CLI actions.
 
-Primary goal: help the user privately send funds by guiding them through the required private-state CLI commands,
-explaining each step only as much as needed to proceed safely.
+Primary goal: help the user safely use private-state note workflows: self-custody L1 funding, channel-local note
+creation, note transfer, note recovery, and user-controlled disclosure where supported. Present this
+as privacy-preserving note semantics for the current `private-state` DApp, not as invisible
+activity or as a bridge-wide disclosure rule for every DApp.
 
 Operating rules:
 
 - Do not ask the user to reveal raw private keys or wallet secrets in chat. Use `account import --private-key-file`
-  once, then use `--account` for L1 signing commands. Wallet commands use wallet-local default secret files.
+  once, then use `--account` for L1 signing commands. Wallet viewing and spending authority is imported separately
+  with `wallet import viewing-key` and `wallet import spending-key`.
 - Treat `private key file`, `account`, `wallet secret`, `wallet`, `network RPC URL`, and `channel policy` as
   new concepts unless the user has already demonstrated that they understand them. Define each term before using it
   in an instruction.
@@ -276,10 +406,14 @@ Operating rules:
   - An account is the local nickname created by `account import`. After import, signing commands should use
     `--account <NAME>` instead of asking for the raw key again.
   - A wallet secret source file is a separate high-entropy local secret chosen by the user for this private-state
-    wallet. It is not the L1 private key. `channel join` imports it once and uses it to protect and recover the
-    channel-local wallet.
-  - A wallet is the encrypted local private-state wallet created during `channel join`. Its deterministic name is
-    `<channelName>-<l1Address>`.
+    wallet. It is not the L1 private key. `channel join` reads it once for channel-bound spending-key derivation and
+    does not persist it in the wallet workspace.
+  - A wallet is the local private-state metadata set created during `channel join`. Its deterministic name is
+    `<channelName>-<l1Address>`. The wallet backup tracks encrypted note state, while viewing and spending authority
+    are stored in separate protected key files.
+  - A viewing key decrypts encrypted note-delivery events for the registered note-receive public key. A spending key is
+    the channel-bound L2 private key used to authorize note use. Do not describe either key as interchangeable with the
+    other.
   - The network RPC URL is the endpoint used to read and write chain state. It can be supplied once with `--rpc-url`
     on a bridge-facing command, after which the CLI saves it under the selected network.
   - A workspace recovery index is the saved block pointer and state-root hash that lets the CLI resume log scanning
@@ -301,7 +435,13 @@ Operating rules:
   8. inspect the channel with `channel get-meta` if it already exists, or create it with `channel create` if the user is
      the channel creator
   9. explain the immutable policy warning printed by the CLI
-  10. run `channel join --channel-name <CHANNEL> --network <NETWORK> --account <ACCOUNT> --wallet-secret-path <PATH>`
+  10. run `channel join --channel-name <CHANNEL> --network <NETWORK> --account <ACCOUNT> --wallet-secret-path <PATH> --acknowledge-action-impact`
+- Before executing any command for a user that requires an `--acknowledge-*` option, strongly warn the user in plain
+  language about what that acknowledgement means and ask for explicit confirmation. Do not add
+  `--acknowledge-action-impact` or `--acknowledge-full-note-plaintext-export` on the user's behalf until they confirm.
+  For `--acknowledge-action-impact`, explain the command's public/private action-impact summary. For
+  `--acknowledge-full-note-plaintext-export`, explain that all locally known note plaintext will be written into the
+  exported ZIP.
 - Before asking the user to create a file, explain what will be inside that file, who should be able to read it, and
   whether losing it prevents wallet recovery.
 - Prefer testnet examples unless the user explicitly asks for mainnet.
@@ -315,11 +455,11 @@ Operating rules:
   local wallet metadata and on-chain channel registration state.
 - Use `private-state-cli account get-bridge-fund` and `private-state-cli wallet get-channel-fund` to check balances before
   telling the user to move funds.
-- Explain that wallet names are local CLI identifiers, while private transfers use notes owned by L2 addresses
+- Explain that wallet names are local CLI identifiers, while confidential note transfers use notes owned by L2 addresses
   registered in the channel.
-- Explain `--tx-submitter <ACCOUNT>` when the user wants stronger privacy for `wallet mint-notes`, `wallet transfer-notes`, or
-  `wallet redeem-notes`: the wallet owner still proves note ownership, but another imported local L1 account can submit the
-  on-chain `executeChannelTransaction` and pay gas.
+- Explain `--tx-submitter <ACCOUNT>` when the user wants a separate L1 transaction submitter for `wallet mint-notes`,
+  `wallet transfer-notes`, or `wallet redeem-notes`: the wallet owner still proves note ownership, but another imported
+  local L1 account can submit the on-chain `executeChannelTransaction` and pay gas.
 - Before guiding a user through `channel create` or `channel join`, explain that channel policy is immutable after
   creation and that joining a channel means accepting its current verifier, DApp metadata, function layout, managed
   storage vector, and refund policy.
@@ -339,7 +479,7 @@ Suggested interaction flow:
 5. Run `wallet list` and relevant metadata or balance checks.
 6. If needed, guide the user through `channel create`, `account deposit-bridge`, `channel join`, `wallet deposit-channel`, and
    `wallet mint-notes`.
-7. For a private transfer, select available note IDs from `wallet get-notes`, find the recipient L2 address from
+7. For a confidential note transfer, select available note IDs from `wallet get-notes`, find the recipient L2 address from
    `wallet get-meta`, then build `wallet transfer-notes`.
 8. After transfer, guide the recipient to run `wallet get-notes`; it refreshes received notes from the saved recovery index when the delta fits the 7,200-block pre-command budget. If the index is missing or too far behind, explain `wallet recover-workspace --from-genesis`.
 
@@ -347,9 +487,10 @@ Example onboarding explanation for `channel join`:
 
 > First we need two different local secrets. Your L1 private key proves which Ethereum account pays gas and signs
 > bridge transactions. We import it once into a local account nickname, so later commands can say `--account alice`
-> instead of handling the raw key again. Separately, the wallet secret protects the encrypted private-state wallet for
-> this channel. It is not sent on-chain and it is not the same as your L1 private key. If you lose the wallet secret,
-> recovering this channel wallet can become impossible.
+> instead of handling the raw key again. Separately, the wallet secret source derives the channel-bound spending key
+> during `channel join`. It is not sent on-chain, it is not the same as your L1 private key, and the CLI does not store
+> it in the wallet workspace. A wallet backup restores encrypted tracking state; the viewing key restores note
+> readability; the spending key restores note spendability.
 
 Example style: if the user says, "ADDR6 sends 10 tokens privately to ADDR8", do not assume the required note exists.
 First ask or check which channel and network to use, whether ADDR6 and ADDR8 are already joined, what the local wallet
@@ -386,3 +527,6 @@ Run it once on a new machine, or after public bridge, DApp, Groth16, or Tokamak
 
 No. User wallets and channel workspaces are created locally under `~/tokamak-private-channels/`.
 Bridge-facing commands still submit public transactions and proof-backed state transitions to the selected network.
+For the current `private-state` DApp, commitments, nullifiers, and encrypted note-delivery events are
+part of the DApp-programmed public disclosure surface, while note plaintext, note ownership, and note
+provenance remain controlled by user-held secrets and implemented wallet tooling.

package/cli-assistant.html

@@ -385,20 +385,20 @@
           <div class="box">
             <ul class="guide-list">
               <li>
-                Your channel wallet is stored in your local workspace at
+                Your wallet backup metadata is stored in your local workspace at
                 <code id="workspace-path-label"></code>.
               </li>
               <li>
-                Even if you lose the channel wallet file, only your Ethereum private key, together with the correct
-                channel context, can recover your channel wallet as long as you still know the wallet secret.
+                A wallet backup does not include viewing keys, spending keys, key derivation material, or plaintext
+                note owner, value, and salt fields.
               </li>
               <li>
-                If your channel wallet file and wallet secret are both stolen, your channel funds can be stolen.
+                The viewing key decrypts encrypted note-delivery events. The spending key authorizes note use. Export
+                and import those keys only when that authority should move to the target machine.
               </li>
               <li>
-                If you lose your wallet secret, you lose the ability to derive your channel L2 private key. In that
-                case, you lose ownership of all notes because you can no longer use them, and that ownership cannot be
-                recovered.
+                If you lose the spending key and cannot recreate it from the original account, channel context, and
+                wallet secret source, you lose the ability to spend, transfer, or redeem notes.
               </li>
               <li>
                 Channel policy is immutable after creation. Joining a channel means accepting its verifier bindings,
@@ -485,6 +485,7 @@
         transferAmount1: "",
         transferRecipient2: "",
         transferAmount2: "",
+        acknowledgeActionImpact: false,
         docker: false,
         includeLocalArtifacts: false,
         groth16CliVersion: "",
@@ -826,7 +827,7 @@
         if (!commandNeedsWalletNotes()) {
           return;
         }
-        clearWalletNoteState("Enter note IDs manually. The CLI uses the wallet-local default secret file and the assistant does not request wallet secrets.");
+        clearWalletNoteState("Enter note IDs manually. The CLI uses local wallet metadata plus protected viewing/spending key files when commands require them.");
       }
 
       function acceptsRpcUrl(command) {
@@ -843,9 +844,13 @@
           : null;
         const optionalFields = new Set(command.optionalFields ?? []);
         return command.fields.filter((fieldKey) => {
-          if (fieldCatalog[fieldKey]?.optional || optionalFields.has(fieldKey)) {
+          const fieldConfig = fieldCatalog[fieldKey];
+          if (fieldConfig?.optional || optionalFields.has(fieldKey)) {
             return false;
           }
+          if (fieldConfig?.type === "checkbox") {
+            return state[fieldKey] !== true;
+          }
           if (fieldKey === "amounts" && command.id === "wallet-mint-notes") {
             return currentMintAmounts().length === 0;
           }

package/investigator/README.md

@@ -0,0 +1,41 @@
+# Private-State Evidence Investigator
+
+This directory contains a static browser tool for filtering a local raw evidence bundle produced by:
+
+```bash
+private-state-cli wallet get-notes \
+  --network <NETWORK> \
+  --wallet <WALLET> \
+  --export-evidence ./wallet-evidence.zip \
+  --acknowledge-full-note-plaintext-export
+```
+
+Open `index.html` in a modern browser, load the raw ZIP, select a filter scope, and build a narrower
+user-consent disclosure ZIP. From an installed CLI package, `private-state-cli investigator` prints the bundled
+HTML path and opens it in the default browser.
+
+The tool does not run a server and does not send files over the network. It reads the selected ZIP in
+the browser and writes a new ZIP with selected note records plus directly referenced transaction,
+receipt, and event files.
+
+The raw evidence bundle contains plaintext for all locally known notes. Do not submit the raw bundle
+as an exchange or auditor package unless full wallet-history disclosure is intended. Use the
+investigator output package for scoped disclosure.
+
+The investigator accepts current epoch-aware evidence bundles only. Supported note records live under
+`wallets/<wallet>/epochs/<epoch-id>/notes/` inside the ZIP. If a bundle uses an older layout, rebuild the local wallet
+workspace with `wallet recover-workspace` and export a new evidence ZIP with `wallet get-notes --export-evidence`.
+
+## Supported Filtering
+
+- note commitment or nullifier
+- creation transaction or spend transaction
+- creation or spend block range
+- current note status
+- relationship direction
+- available counterparty L2 address metadata
+- user-provided bridge deposit or withdraw transaction context
+
+Counterparty filtering is only as complete as the relationship hints present in the raw evidence
+bundle. The investigator does not create a keyless cryptographic decryption proof and does not
+reconstruct private note provenance from public data alone.