zk-agent-cli 0.1.0-rc.5 → 0.1.0-rc.7

package/README.md

@@ -1,16 +1,22 @@
 # zk-agent-cli
 
-`zk-agent-cli` is the packaged terminal CLI for the zk-agent operator path on
+`zk-agent-cli` is the packaged terminal CLI for the default zk-agent product path on
 zkSync Era and zkSync Sepolia.
 
-This is the canonical CLI operator manual.
+This is the canonical CLI manual.
+
+## Why This CLI Exists
+
+- keep wallet and session control local-first
+- keep the default execution story zkSync-native and `sed-lite`-first
+- add an Agent Pay request layer above direct workflow execution
 
 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
+  for the native Codex plugin install path
 
 ## One-minute path
 
@@ -25,6 +31,16 @@ zk-agent workflow pay --wallet main --to <address> --amount <amount>
 zk-agent suite
 ```
 
+`zk-agent start` is the public onboarding command that keeps the same output
+contract as `zk-agent next`. Use `start` when you want the shortest obvious
+first-touch command. Keep `next` as the canonical operator/runtime contract in
+scripts and JSON examples.
+
+If you are new, stop at the first successful `zk-agent workflow pay`. Ignore
+remote approval and Agent Pay until that baseline path works once. Use
+`zk-agent suite` only after that first success or when you want the broader
+question-first packaged surface.
+
 What each step is doing:
 
 - `setup` writes local defaults
@@ -32,63 +48,158 @@ What each step is doing:
   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
+- `suite` is the broader question-first packaged surface
 
 The packaged default story is payment-first: send native value now, stay on
 the approval-based pay path when fee-token/default state matters, and recover
 funding only when the workflow says the write path is blocked.
 
-The first Agent Pay platform primitive now exists as a local-first payment
-ingress, request, routing, and approval-orchestration surface:
+The three public proof paths today are:
+
+- flagship pay: prove the default ready-wallet zkSync-native send path
+- Agent Pay: prove local request capture plus follow-up surfaces around the
+  same wallet runtime
+- hosted approval recovery: prove remote-browser session recovery on the
+  current single-host relay baseline
+
+The fastest flagship proof path after wallet readiness is:
+
+```bash
+zk-agent workflow pay --wallet main --to <address> --amount <amount>
+zk-agent workflow next --request-id <id>
+zk-agent workflow status --request-id <id>
+```
+
+That path proves the default ready-wallet execution route plus checkpoint
+follow-up and status inspection without leaving the flagship workflow surface.
+
+The current local-first Agent Pay entry surface is:
 
 ```bash
 zk-agent payment submit --wallet main --to <address> --amount <amount>
+zk-agent payment dashboard
+zk-agent payment feed
 zk-agent payment queue
 zk-agent payment report
 zk-agent payment approval --request-id <id>
-zk-agent payment sync-approval --request-id <id>
-zk-agent payment create --wallet main --to <address> --amount <amount>
+```
+
+The fastest Agent Pay proof path is:
+
+```bash
+zk-agent payment submit --wallet main --to <address> --amount <amount>
 zk-agent payment next --request-id <id>
-zk-agent payment inspect --request-id <id>
-zk-agent payment intent --request-id <id>
-zk-agent payment describe --request-id <id>
-zk-agent payment execution --request-id <id>
-zk-agent payment quote --request-id <id>
-zk-agent payment refresh-quote --request-id <id>
-zk-agent payment settlement --request-id <id>
-zk-agent payment reconcile --request-id <id> --status <status>
-zk-agent payment list
+zk-agent payment approval --request-id <id>
+zk-agent payment dashboard
+zk-agent payment handoff --request-id <id>
+zk-agent payment feed
+```
+
+That path shows compact ingress, wallet-aware follow-up, approval readiness,
+dashboard summary, single-request handoff bundling, and cross-request feed
+export without leaving the local-first surface.
+
+When the browser is remote, the fastest hosted approval proof path on the
+current supported recovery baseline is:
+
+```bash
+zk-agent relay inspect --relay-url <relay-url>
+zk-agent wallet reapprove --name main --relay-url <relay-url> --wait-relay --prompt-code
+zk-agent wallet status --name main
 ```
 
+That path proves outside-in relay readiness, one hosted reapproval, and the
+post-approval wallet-readiness readout without claiming multi-host durability.
+
+If the wallet does not exist yet, swap `wallet reapprove` for:
+
+```bash
+zk-agent wallet create --relay-url <relay-url> --wait-relay --prompt-code
+zk-agent next
+```
+
+Use those commands for the public "start here" path:
+
+- `submit`: capture one payment request through the compact ingress surface
+- `dashboard`: review one cross-request dashboard summary above wallet groups,
+  actionable queue items, and recent payment activity
+- `feed`: expose an integration-ready cross-request batch feed for external
+  dashboards, agents, or backend ingestion
+- `queue`: review the current actionable request queue
+- `report`: summarize cross-request state and next-action distribution
+- `approval`: inspect whether the linked wallet is still blocking execution
+
+When you already have a request id and need the deeper local lifecycle,
+integration-ready handoff bundle, request parties model, share-safe request
+view, routing, quote, settlement, or reconciliation views, use:
+
+```bash
+zk-agent payment --help
+```
+
+Use `zk-agent payment share --request-id <id>` when the request must be shared
+with a payee or external reviewer without exposing local wallet linkage or
+execution-preference details.
+
+Use `zk-agent payment parties --request-id <id>` when an external agent or
+backend needs the stable request parties model with separate local and
+share-safe payer projections.
+
+Use `zk-agent payment handoff --request-id <id>` when an external dashboard,
+agent, or backend needs one stable integration bundle instead of
+reassembling local reads.
+
+Use `zk-agent payment feed` when that same external surface needs the stable
+cross-request batch feed instead of one request at a time.
+
 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:
+When `doctor` shows local readiness is clear and you want the broader
+question-first packaged surface, 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:
+the post-flagship packaged surface, use:
 
 ```bash
 zk-agent suite --include-onboarding
 ```
 
+Inside `suite`, the smallest question-first entry layer is:
+
+- `send now`
+- `track payments`
+- `inspect before token action`
+- `unstick write`
+- `recover remote approval`
+
 Use the surfaces this way:
 
+- `start`: you are just beginning and want the public onboarding command that
+  mirrors `next`
 - `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
+- `workflow pay`: the wallet is already ready and you want the flagship
+  native-send path now
+- `suite`: the wallet is already ready and you want the broader question-first
+  packaged surface because the task is broader than one immediate flagship pay
+  step
+- `payment`: the execution path is no longer the whole story and you need
+  local request capture, queueing, reporting, or approval tracking around it
 - `suite --include-onboarding`: you want one combined readout from first-run
   bootstrap through the packaged post-flagship surface
 
+The remote relay path is a fallback, not part of the default happy path. Only
+open it when the browser is on another machine or cannot return directly to
+the waiting terminal.
+
 ## Install
 
 One-shot execution:
@@ -110,7 +221,7 @@ The package also ships the alias:
 zksync-agent --help
 ```
 
-The `npx skills add ...` path belongs to the repo skill bundle, not the
+The `npx skills add ...` path belongs to the skill bundle, not the
 packaged CLI install surface.
 
 ## Defaults
@@ -137,15 +248,19 @@ ZK_AGENT_STORAGE_DIR=
 
 - `zk-agent next`: the top-level product entrypoint when the CLI still needs to
   choose the shortest path
+- `zk-agent workflow pay ...`: the direct flagship execution surface when you
+  already know the wallet is ready and the goal is "send value now"
+- `zk-agent suite`: the packaged post-flagship catalog once wallet readiness is
+  no longer the blocker and you want the broader question-first packaged
+  surface
 - `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 workflow ...`: explicit workflow planning, persistence, status,
+  resume questions, and the flagship pay execution path
 - `zk-agent payment ...`: local-first payment ingress, request capture, routing,
-  and settlement-state tracking for the Agent Pay platform layer
-- `zk-agent suite`: the packaged post-flagship catalog once wallet readiness is
-  no longer the blocker
+  queueing, approval tracking, and settlement-state tracking for the Agent Pay
+  platform layer
 
 ## Repair locally first
 
@@ -229,12 +344,13 @@ zk-agent suite
 ```
 
 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.
+for flagship pay, Agent Pay request work, discovery/defaults, funding
+readiness, approval-based paymaster readiness, and hosted approval recovery.
 
 Current `suite` catalog categories:
 
 - `operate`
+- `request`
 - `discover`
 - `pay`
 - `fund`
@@ -243,12 +359,14 @@ Current `suite` catalog categories:
 Current `suite` handoff surfaces:
 
 - `workflow`: flagship pay, approval-based pay, and funding recovery
+- `payment`: request capture, queueing, reporting, feed export, and approval repair
 - `discovery`: assets/defaults/token inspection
 - `relay`: hosted approval recovery
 
-Current `suite` operator journeys:
+Current `suite` product journeys:
 
 - `send value now`
+- `capture and track payments`
 - `inspect before acting`
 - `unstick a write`
 - `recover remote approval`
@@ -256,6 +374,21 @@ Current `suite` operator journeys:
 If you only need one default starting point inside `suite`, start with
 `send value now`.
 
+For the clearest Agent Pay proof path inside `suite`, follow:
+
+```bash
+zk-agent payment submit --wallet main --to <address> --amount <amount>
+zk-agent payment next --request-id <id>
+zk-agent payment approval --request-id <id>
+zk-agent payment dashboard
+zk-agent payment handoff --request-id <id>
+zk-agent payment feed
+```
+
+That is the shortest packaged route from one local request write into
+wallet-aware follow-up, approval readiness, dashboard summary, and
+integration-ready export.
+
 Use `--wallet <name>` or `--chain <chain>` when the returned suite commands
 should stay on a non-default wallet or chain.
 
@@ -271,7 +404,7 @@ Do not guess the route. Use the exact funding command suggested by `next`,
 
 ## Leave the default path only on purpose
 
-Prefer `suite` first when you want the packaged discovery/defaults/funding/
+Prefer `suite` first when you want the packaged Agent Pay/discovery/funding/
 paymaster surface. Drop to lower-level commands only when the question is
 already narrower than the packaged catalog.
 
@@ -299,7 +432,7 @@ Built-in smart-account profiles remain:
 
 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
+predict, deploy, or profile-level self-calls rather than the normal default
 path.
 
 ## Common failures
@@ -315,7 +448,7 @@ path.
   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
+  rerun from a normal shell or use the relay/manual approval path that
   matches the environment
 
 ## Reference
@@ -348,4 +481,4 @@ zk-agent relay --help
 
 ## License
 
-MIT. See the repository `LICENSE`.
+MIT. See the project `LICENSE`.