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

package/README.md

@@ -3,7 +3,10 @@
 `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 manual.
+This is the packaged CLI manual for the public product shell:
+`start -> next -> wallet create/reapprove -> next -> pay -> suite`,
+with `submit`, `workspace`, `handoff`, and `feed` as the current Agent Pay
+shortcuts.
 
 ## Why This CLI Exists
 
@@ -11,6 +14,29 @@ This is the canonical CLI manual.
 - keep the default execution story zkSync-native and `sed-lite`-first
 - add an Agent Pay request layer above direct workflow execution
 
+## What Makes It Different
+
+- local-first by default, with hosted approval only as a fallback path when
+  the browser is remote
+- one zkSync-native operator path from wallet readiness to paymaster-aware
+  execution
+- one Agent Pay layer that stays attached to the same wallet runtime instead
+  of splitting into a separate product
+
+## Best Fit
+
+- local-first wallet and session control on zkSync is the real need
+- the first proof should be one zkSync-native pay path, not broad multichain
+  exploration
+- Agent Pay should stay attached to the same wallet runtime instead of
+  becoming a separate operator tool
+
+## Current Boundary
+
+- hosted relay is still the fallback path, not the default onboarding story
+- Agent Pay is a local-first workbench today, not yet a hosted multi-tenant
+  control plane
+
 Use:
 
 - [`skills/QUICKSTART.md`](../../skills/QUICKSTART.md) for the shortest
@@ -18,28 +44,74 @@ Use:
 - [`docs/15-codex-plugin-onboarding.md`](../../docs/15-codex-plugin-onboarding.md)
   for the native Codex plugin install path
 
+## Start Here
+
+- clean machine bootstrap: `zk-agent setup` once
+- first touch: `zk-agent start`
+- first successful proof: follow the one-minute path and stop at the first
+  `zk-agent pay`
+- compact Agent Pay ingress: `zk-agent submit`
+- cross-request Agent Pay workbench: `zk-agent workspace`
+- single-request Agent Pay export: `zk-agent handoff --request-id <id>`
+- cross-request Agent Pay export: `zk-agent feed`
+- broader post-flagship packaged surface: `zk-agent suite`
+- remote-browser fallback: `zk-agent relay baseline --relay-url <relay-url>`
+
+Rule of thumb:
+
+- start with `start`
+- prove the product once with `pay`
+- stay on `suite` when the question is broader than one send
+- stay on `submit` / `workspace` / `handoff` / `feed` when the question is specifically Agent Pay
+- switch to relay only when the browser is remote
+
 ## One-minute path
 
-Use this path unless the task explicitly needs a lower-level command:
+Use this path unless the task explicitly needs a lower-level command. This is
+the first proof from a clean machine:
 
 ```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
+zk-agent pay --wallet main --to <address> --amount <amount>
 ```
 
+On the default local-first path, the approved wallet now auto-syncs its local
+smart-account metadata when chain reads are available, so the happy path does
+not depend on a separate manual `zk-agent wallet sync`.
+
+If you are not sure whether the question is onboarding, recovery, direct send,
+or Agent Pay follow-up, jump to `Start here by question` below and take the
+smallest matching entrypoint.
+
 `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.
+scripts and JSON examples. If local defaults do not exist yet, both `start`
+and `next` still send you through `zk-agent setup` first.
+
+`zk-agent pay` is the public shortcut for the flagship send path. The scoped
+form remains `zk-agent workflow pay`.
+`zk-agent submit` is the public shortcut for the compact Agent Pay ingress
+path. The scoped form remains `zk-agent payment submit`.
+`zk-agent handoff --request-id <id>` is the public shortcut for the
+single-request integration-ready Agent Pay export. The scoped form remains
+`zk-agent payment handoff`.
+`zk-agent feed` is the public shortcut for the integration-ready Agent Pay
+cross-request export. The scoped form remains `zk-agent payment feed`.
+
+If you are new, stop at the first successful `zk-agent pay`. Ignore
+`suite`, `payment`, and `relay` until that baseline path works once, unless
+the CLI explicitly points you there. Use `zk-agent suite` only after that
+first success or when you want the broader question-first packaged surface.
+
+After that first success, the default broader follow-up is:
 
-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.
+```bash
+zk-agent suite
+```
 
 What each step is doing:
 
@@ -47,7 +119,7 @@ What each step is doing:
 - `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
+- `pay` is the flagship zkSync-native public native-send shortcut
 - `suite` is the broader question-first packaged surface
 
 The packaged default story is payment-first: send native value now, stay on
@@ -65,7 +137,7 @@ The three public proof paths today are:
 The fastest flagship proof path after wallet readiness is:
 
 ```bash
-zk-agent workflow pay --wallet main --to <address> --amount <amount>
+zk-agent pay --wallet main --to <address> --amount <amount>
 zk-agent workflow next --request-id <id>
 zk-agent workflow status --request-id <id>
 ```
@@ -73,37 +145,93 @@ 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.
 
+Choose between the direct flagship pay surface and Agent Pay this way:
+
+- `pay`: the same public shortcut when you want the shortest first-screen
+  flagship send path
+- `workflow pay`: the same execution surface once you are already working
+  inside the scoped workflow layer
+- `submit`: the public shortcut when execution is no longer the whole story
+  and you want the shortest Agent Pay ingress path
+- `payment`: execution is no longer the whole story and you need request
+  capture plus follow-up, sharing, reporting, export, or approval repair
+  around the write path
+
+`payment` does not replace the execution path. It keeps local request state,
+follow-up, and export surfaces around `pay`, `submit`, `workflow pay`, and
+`send-token`.
+
+Choose between the two Agent Pay-facing surfaces this way:
+
+- `payment`: the packaged question has already narrowed to one request layer
+  and its follow-up surface
+- `suite`: wallet readiness is already clear, but you still want the broader
+  packaged catalog across requests, discovery, paymaster, funding, and hosted
+  recovery
+
+The shortest way to think about Agent Pay is:
+
+- `submit`: capture one payment request
+- `workspace`: review the cross-request operator surface
+- `handoff`: export one stable integration bundle
+- `feed`: export the stable cross-request batch view
+
+Why Agent Pay instead of only direct execution:
+
+- capture one request before or after the write path
+- keep a cross-request operator workspace around the same wallet runtime
+- export stable handoff and feed views for external agents, dashboards, or backends
+
 The current local-first Agent Pay entry surface is:
 
 ```bash
-zk-agent payment submit --wallet main --to <address> --amount <amount>
+zk-agent submit --wallet main --to <address> --amount <amount>
+zk-agent workspace
 zk-agent payment dashboard
-zk-agent payment feed
+zk-agent feed
 zk-agent payment queue
 zk-agent payment report
-zk-agent payment approval --request-id <id>
+zk-agent approval --request-id <id>
 ```
 
+The scoped equivalents remain `zk-agent payment submit`,
+`zk-agent payment workspace`, `zk-agent payment handoff`,
+`zk-agent payment feed`, and `zk-agent payment approval`.
+
 The fastest Agent Pay proof path is:
 
 ```bash
-zk-agent payment submit --wallet main --to <address> --amount <amount>
+zk-agent 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
+zk-agent approval --request-id <id>
+zk-agent workspace
+zk-agent handoff --request-id <id>
+zk-agent feed
 ```
 
 That path shows compact ingress, wallet-aware follow-up, approval readiness,
-dashboard summary, single-request handoff bundling, and cross-request feed
+workspace summary, single-request handoff bundling, and cross-request feed
 export without leaving the local-first surface.
 
+For the shortest product demo narrative behind that path, use
+[`docs/20-agent-pay-demo-narrative.md`](../../docs/20-agent-pay-demo-narrative.md).
+
+If request capture is no longer enough and you need one current cross-request
+operator view, open the workbench directly:
+
+```bash
+zk-agent workspace
+```
+
+That is the current public shortcut to the Agent Pay workbench anchor above
+dashboard, queue, report, and feed. The scoped form remains
+`zk-agent payment workspace`.
+
 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 relay baseline --relay-url <relay-url>
 zk-agent wallet reapprove --name main --relay-url <relay-url> --wait-relay --prompt-code
 zk-agent wallet status --name main
 ```
@@ -118,11 +246,13 @@ zk-agent wallet create --relay-url <relay-url> --wait-relay --prompt-code
 zk-agent next
 ```
 
-Use those commands for the public "start here" path:
+Current compact Agent Pay command layer:
 
 - `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
+- `handoff`: expose one stable single-request export bundle for external
+  dashboards, agents, or backend ingestion
 - `feed`: expose an integration-ready cross-request batch feed for external
   dashboards, agents, or backend ingestion
 - `queue`: review the current actionable request queue
@@ -145,11 +275,11 @@ 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,
+Use `zk-agent 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
+Use `zk-agent 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:
@@ -180,22 +310,6 @@ Inside `suite`, the smallest question-first entry layer is:
 - `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
-- `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.
@@ -244,23 +358,42 @@ ZK_AGENT_TOKEN_DIRECTORY_ROOT=
 ZK_AGENT_STORAGE_DIR=
 ```
 
-## Choose the right surface
+## Start here by question
 
-- `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 start`: the public first-touch command when you want the shortest
+  obvious entrypoint
+- `zk-agent next`: the CLI still needs to choose bootstrap, recovery, or
+  workflow continuation
 - `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,
-  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
+  `zk-agent wallet next --name <wallet>`: the blocker is clearly wallet-scoped
+  but the exact repair step is still unclear
+- `zk-agent pay ...`: the wallet is ready and the goal is "send value now"
+- `zk-agent workflow ...`: the question is already workflow-specific and you
+  need planning, persistence, status, resume, or multi-intent execution
+- `zk-agent payment ...`: execution is no longer the whole story and you need
+  the Agent Pay request layer around the write path
+- `zk-agent workspace`: you already know you need the current cross-request
+  Agent Pay workbench anchor
+- `zk-agent handoff --request-id <id>`: you already need one stable
+  single-request Agent Pay export bundle
+- `zk-agent feed`: you already need the integration-ready cross-request Agent
+  Pay export
+- `zk-agent suite`: wallet readiness is clear and the question is broader than
+  one immediate send
+- `zk-agent relay baseline --relay-url <relay-url>`: the browser is remote and
+  approval must move to the hosted fallback path
+
+Keep the split strict: `pay` is the public direct send surface, `workflow pay`
+is the scoped workflow form of that same path, and `payment` is the request
+and follow-up layer around the send surface.
+
+Use `suite` when the question is broader than one request lifecycle and you
+still need the packaged catalog.
+
+Use `workspace` when the question has already narrowed to the current
+cross-request Agent Pay workbench. The scoped form remains
+`payment workspace`.
 
 ## Repair locally first
 
@@ -287,19 +420,27 @@ zk-agent wallet next --name main
 
 ## Switch to remote approval only when needed
 
-Use the relay-backed path only when the browser is not colocated with the
-terminal:
+Use the relay-backed path only when the browser is remote and cannot return to
+the waiting terminal.
+
+Start with `relay baseline`. It is the packaged hosted-approval entrypoint and
+tells you whether the relay matches the current supported fallback contract.
+Open `relay inspect` only when you need the raw hosted-readiness, URL-shape,
+and persistence fields directly.
+
+Existing wallet:
 
 ```bash
-zk-agent relay inspect --relay-url <relay-url>
-zk-agent wallet create --relay-url <relay-url> --wait-relay --prompt-code
-zk-agent next
+zk-agent relay baseline --relay-url <relay-url>
+zk-agent wallet reapprove --name main --relay-url <relay-url> --wait-relay --prompt-code
+zk-agent wallet status --name main
 ```
 
-For an existing wallet:
+No saved wallet yet:
 
 ```bash
-zk-agent wallet reapprove --name main --relay-url <relay-url> --wait-relay --prompt-code
+zk-agent relay baseline --relay-url <relay-url>
+zk-agent wallet create --relay-url <relay-url> --wait-relay --prompt-code
 zk-agent next
 ```
 
@@ -318,10 +459,6 @@ If the relay is self-hosted through the built-in server:
 zk-agent relay serve --public-origin https://relay.example.com
 ```
 
-Use `relay inspect` before sending users to a share link. It exposes hosted
-readiness, URL shape, persistence mode, and the exact create/reapprove follow-up
-path.
-
 For the supported hosted operating contract, use
 [`docs/16-hosted-approval-operated-baseline.md`](../../docs/16-hosted-approval-operated-baseline.md).
 
@@ -359,7 +496,7 @@ 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
+- `payment`: request capture, follow-up, sharing, export, and approval repair
 - `discovery`: assets/defaults/token inspection
 - `relay`: hosted approval recovery
 
@@ -371,22 +508,36 @@ Current `suite` product journeys:
 - `unstick a write`
 - `recover remote approval`
 
+In JSON mode, `suite` now also returns a top-level `platformLayer` summary so
+wrappers, docs, and demos can read the current product shell directly without
+reconstructing it from `proofPaths[]` and `journeys[]`.
+
 If you only need one default starting point inside `suite`, start with
 `send value now`.
 
+Inside `suite`, the shortest way to think about Agent Pay is:
+
+- `submit`: capture one payment request
+- `workspace`: review the cross-request operator surface
+- `handoff`: export one stable single-request bundle
+- `feed`: export the stable cross-request batch view
+
+The shortest tracked route inside `suite` remains:
+`submit -> next -> approval -> workspace -> handoff -> feed`.
+
 For the clearest Agent Pay proof path inside `suite`, follow:
 
 ```bash
-zk-agent payment submit --wallet main --to <address> --amount <amount>
+zk-agent 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
+zk-agent approval --request-id <id>
+zk-agent workspace
+zk-agent handoff --request-id <id>
+zk-agent feed
 ```
 
 That is the shortest packaged route from one local request write into
-wallet-aware follow-up, approval readiness, dashboard summary, and
+wallet-aware follow-up, approval readiness, workspace summary, and
 integration-ready export.
 
 Use `--wallet <name>` or `--chain <chain>` when the returned suite commands