zk-agent-cli 0.1.0-rc.4 → 0.1.0-rc.6

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,11 @@ zk-agent workflow pay --wallet main --to <address> --amount <amount>
 zk-agent suite
 ```
 
+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 the question becomes
+broader than one immediate write.
+
 What each step is doing:
 
 - `setup` writes local defaults
@@ -38,14 +49,66 @@ 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
-request 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>
+```
+
+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 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.
+
+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 create --wallet main --to <address> --amount <amount>
-zk-agent payment list
+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
@@ -60,7 +123,7 @@ 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
@@ -70,11 +133,19 @@ 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
+- `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 packaged surface
+  because the question 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:
@@ -96,7 +167,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
@@ -123,14 +194,18 @@ 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 the question is broader than one immediate write
 - `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 payment ...`: local-first payment request capture 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
+- `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,
+  queueing, approval tracking, and settlement-state tracking for the Agent Pay
+  platform layer
 
 ## Repair locally first
 
@@ -214,12 +289,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`
@@ -228,12 +304,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`
@@ -241,6 +319,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.
 
@@ -256,7 +349,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.
 
@@ -284,7 +377,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
@@ -300,7 +393,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
@@ -333,4 +426,4 @@ zk-agent relay --help
 
 ## License
 
-MIT. See the repository `LICENSE`.
+MIT. See the project `LICENSE`.