zk-agent-cli 0.1.0-rc.1 → 0.1.0-rc.3

package/README.md

@@ -3,7 +3,65 @@
 `zk-agent-cli` is the packaged terminal CLI for the zk-agent operator path on
 zkSync Era and zkSync Sepolia.
 
-This file is the canonical operator manual for CLI users.
+This is the canonical CLI operator manual.
+
+Use:
+
+- [`skills/QUICKSTART.md`](../../skills/QUICKSTART.md) for the shortest
+  verified path
+- [`docs/15-codex-plugin-onboarding.md`](../../docs/15-codex-plugin-onboarding.md)
+  for the native Codex plugin/local marketplace path
+
+## One-minute path
+
+Use this path unless the task explicitly needs a lower-level command:
+
+```bash
+zk-agent setup
+zk-agent next
+zk-agent wallet create --await-local
+zk-agent next
+zk-agent workflow pay --wallet main --to <address> --amount <amount>
+zk-agent suite
+```
+
+What each step is doing:
+
+- `setup` writes local defaults
+- `next` gives the shortest valid follow-up step and now labels the current
+  product question as `bootstrap`, `recover`, `operate`, or `workflow`
+- `wallet create --await-local` is the preferred local approval path
+- `workflow pay` is the flagship zkSync-native AA native-send path
+- `suite` is the packaged surface
+
+If readiness is unclear before you choose a fix, use:
+
+```bash
+zk-agent doctor
+```
+
+When `doctor` shows local readiness is clear and the question is broader than
+one immediate next step, move to:
+
+```bash
+zk-agent suite
+```
+
+If you want one packaged readout that includes both first-run onboarding and
+the post-flagship operator surface, use:
+
+```bash
+zk-agent suite --include-onboarding
+```
+
+Use the surfaces this way:
+
+- `next`: the CLI is still deciding the shortest path across setup, wallet
+  readiness, recovery, or workflow continuation
+- `suite`: the wallet is already ready and you want the packaged operator
+  catalog after the flagship pay path
+- `suite --include-onboarding`: you want one combined readout from first-run
+  bootstrap through the packaged post-flagship surface
 
 ## Install
 
@@ -26,7 +84,10 @@ The package also ships the alias:
 zksync-agent --help
 ```
 
-## Defaults and prerequisites
+The `npx skills add ...` path belongs to the repo skill bundle, not the
+packaged CLI install surface.
+
+## Defaults
 
 - Node.js `>=24`
 - the default chain is `zksync-sepolia`
@@ -46,32 +107,19 @@ ZK_AGENT_TOKEN_DIRECTORY_ROOT=
 ZK_AGENT_STORAGE_DIR=
 ```
 
-## Fastest verified path
-
-Use this path unless the task explicitly needs a lower-level command:
-
-```bash
-zk-agent setup
-zk-agent next
-zk-agent wallet create --await-local
-zk-agent next
-zk-agent workflow pay --wallet main --to <address> --amount <amount>
-```
-
-Interpretation:
-
-- `setup` writes local defaults
-- `next` gives the shortest valid follow-up step
-- `wallet create --await-local` is the preferred local approval path
-- `workflow pay` is the flagship zkSync-native AA native-send path
+## Choose the right surface
 
-If readiness is unclear before you choose a fix, use:
-
-```bash
-zk-agent doctor
-```
+- `zk-agent next`: the top-level product entrypoint when the CLI still needs to
+  choose the shortest path
+- `zk-agent doctor`: local-only diagnosis before you choose a fix
+- `zk-agent wallet status --name <wallet>` and
+  `zk-agent wallet next --name <wallet>`: wallet-scoped repair and readiness
+- `zk-agent workflow ...`: explicit workflow planning, persistence, status, and
+  resume questions
+- `zk-agent suite`: the packaged post-flagship catalog once wallet readiness is
+  no longer the blocker
 
-## Existing wallet recovery
+## Repair locally first
 
 If the wallet already exists and approval is missing or expired:
 
@@ -94,7 +142,7 @@ zk-agent wallet status --name main
 zk-agent wallet next --name main
 ```
 
-## Remote approval
+## Switch to remote approval only when needed
 
 Use the relay-backed path only when the browser is not colocated with the
 terminal:
@@ -112,6 +160,15 @@ zk-agent wallet reapprove --name main --relay-url <relay-url> --wait-relay --pro
 zk-agent next
 ```
 
+Current supportable product shape on this path:
+
+- one externally reachable public origin
+- one relay host with same-host file persistence
+- one same-origin share-link + approval UI surface
+
+Do not assume multi-host or load-balanced durability on the current relay
+surface.
+
 If the relay is self-hosted through the built-in server:
 
 ```bash
@@ -125,16 +182,9 @@ path.
 For the supported hosted operating contract, use
 [`docs/16-hosted-approval-operated-baseline.md`](../../docs/16-hosted-approval-operated-baseline.md).
 
-## Funding and execution
+## After the wallet is ready
 
-Only fund when the CLI tells you funding is required:
-
-```bash
-zk-agent workflow fund --wallet main
-zk-agent workflow fund --wallet main --amount <amount> --execute
-```
-
-Flagship pay path:
+Default flagship write path:
 
 ```bash
 zk-agent workflow pay --wallet main --to <address> --amount <amount>
@@ -144,112 +194,117 @@ zk-agent workflow pay --wallet main --to <address> --amount <amount> --broadcast
 Keep `sed-lite` as the default AA baseline. Use `daily-spend-limit` only when
 you intentionally need that narrower policy profile.
 
-## Operator suite
-
-Use:
+Default packaged surface:
 
 ```bash
 zk-agent suite
 ```
 
-when you want the flagship path plus the current post-flagship surfaces in one
-place.
+Use `suite` when the wallet is already ready and you want one packaged surface
+for flagship pay, discovery/defaults, funding readiness, approval-based
+paymaster readiness, and hosted approval recovery.
 
-Current suite shape:
+Current `suite` catalog categories:
 
-- flagship pay:
-  `zk-agent workflow pay --wallet main --to <address> --amount <amount>`
-- discovery/defaults:
-  `zk-agent assets --wallet main`
-  `zk-agent defaults`
-  `zk-agent resolve-token --chain zksync-sepolia --symbol USDC`
-- funding readiness:
-  `zk-agent workflow fund --wallet main`
-- paymaster readiness:
-  `zk-agent workflow pay --wallet main --to <address> --amount <amount> --paymaster-mode approval-based`
-  `zk-agent tokens --chain zksync-sepolia --role paymaster-fee-token`
+- `operate`
+- `discover`
+- `pay`
+- `fund`
+- `recover`
 
-## Discovery and direct commands
+Current `suite` handoff surfaces:
 
-Preferred discovery order:
+- `workflow`: flagship pay, approval-based pay, and funding recovery
+- `discovery`: assets/defaults/token inspection
+- `relay`: hosted approval recovery
 
-- `zk-agent assets --wallet main`
-- `zk-agent tokens --wallet main --owned`
-- `zk-agent defaults`
-- `zk-agent resolve-token --chain zksync-sepolia --symbol <symbol>`
-
-Use the direct commands when you intentionally want to bypass the workflow
-layer:
+Current `suite` operator journeys:
 
-- `zk-agent send-token --wallet main --symbol USDC --to <address> --amount <amount>`
-- `zk-agent swap --wallet main --token-in-symbol USDC --token-out-symbol ETH --amount-in <amount>`
-- `zk-agent fund --wallet main --symbol USDC --amount <amount>`
-- `zk-agent deposit --wallet main --symbol USDC --amount <amount>`
-- `zk-agent withdraw --wallet main --symbol USDC --amount <amount>`
+- `send value now`
+- `inspect before acting`
+- `unstick a write`
+- `recover remote approval`
 
-## Local storage
+Use `--wallet <name>` or `--chain <chain>` when the returned suite commands
+should stay on a non-default wallet or chain.
 
-By default the CLI stores local state under:
+Only fund when the CLI tells you funding is required:
 
-```text
-~/.zk-agent/
+```bash
+zk-agent workflow fund --wallet main
+zk-agent workflow fund --wallet main --amount <amount> --execute
 ```
 
-Common files:
+Do not guess the route. Use the exact funding command suggested by `next`,
+`doctor`, `wallet status`, a blocked workflow, or `suite`.
 
-- `config.json`
-- `wallets/*.json`
-- `requests/*.json`
-- `workflows/*.json`
+## Leave the default path only on purpose
 
-## Smart-account profiles
+Prefer `suite` first when you want the packaged discovery/defaults/funding/
+paymaster surface. Drop to lower-level commands only when the question is
+already narrower than the packaged catalog.
 
-The packaged CLI includes built-in profile artifacts for:
+Preferred discovery order:
 
-- `sed-lite`
-- `daily-spend-limit`
+- `zk-agent assets --wallet main`
+- `zk-agent tokens --wallet main --owned`
+- `zk-agent defaults`
+- `zk-agent resolve-token --chain zksync-sepolia --symbol <symbol>`
 
-Inspect them with:
+- direct token transfer or send path:
+  `zk-agent send-token --wallet main --symbol USDC --to <address> --amount <amount>`
+- explicit workflow planning, swap, bridge, deposit, withdraw, or resume:
+  `zk-agent workflow --help`
+- wallet lifecycle, recovery, approval requests, signer management, or
+  smart-account profile operations:
+  `zk-agent wallet --help`
+- hosted relay inspection or built-in relay serving:
+  `zk-agent relay --help`
 
-```bash
-zk-agent wallet smart-account profiles --json
-```
+Built-in smart-account profiles remain:
 
-Use the packaged path for:
+- `sed-lite`
+- `daily-spend-limit`
 
-```bash
-zk-agent wallet smart-account predict --profile sed-lite
-zk-agent wallet smart-account deploy --profile sed-lite
-```
+Keep `sed-lite` as the default product baseline. Use
+`zk-agent wallet smart-account --help` when the task is specifically about
+predict, deploy, or profile-level self-calls rather than the normal operator
+path.
 
 ## Common failures
 
-Connector callback never arrives:
-
-- verify the connector URL saved by `zk-agent setup`
-- if local callback is impossible in the current environment, switch to the
-  relay-backed path
-
-CLI says the wallet is missing a writable session:
+- connector callback never arrives:
+  verify the connector URL saved by `zk-agent setup`; if local callback is not
+  viable in the current environment, switch to the relay-backed path
+- wallet is missing a writable session:
+  run `zk-agent doctor --wallet <wallet>`, then inspect
+  `zk-agent wallet status --name <wallet>`; reapprove when approval is missing,
+  attach the signer when approval is still present
+- workflow stops on funding:
+  do not guess the route; run the exact `workflow fund` command suggested by
+  the CLI
+- locked-down environment blocks local callback or relay binding:
+  rerun from a normal host shell or use the relay/manual approval path that
+  matches the environment
 
-- run `zk-agent doctor --wallet <wallet>`
-- inspect `zk-agent wallet status --name <wallet>`
-- reapprove when approval is missing
-- attach the signer when approval is present but local write readiness is not
+## Reference
 
-Workflow stops on funding:
+Local storage:
 
-- do not guess the route
-- run the exact `workflow fund` command suggested by the CLI
+By default the CLI stores local state under:
 
-Locked-down environment blocks local callback or relay binding:
+```text
+~/.zk-agent/
+```
 
-- rerun from a normal host shell
-- or use a relay/manual approval path that matches the environment
+Common files:
 
-## Command help
+- `config.json`
+- `wallets/*.json`
+- `requests/*.json`
+- `workflows/*.json`
 
-Use:
+Help surfaces:
 
 ```bash
 zk-agent --help
@@ -257,6 +312,7 @@ zk-agent doctor --help
 zk-agent wallet --help
 zk-agent workflow --help
 zk-agent suite --help
+zk-agent relay --help
 ```
 
 ## License