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

package/README.md

@@ -5,7 +5,8 @@ zkSync Era and zkSync Sepolia.
 
 This is the packaged CLI manual for the public product shell:
 `start -> next -> wallet create/reapprove -> next -> pay -> suite`,
-with `submit` and `workspace` as the current Agent Pay shortcuts.
+with `submit`, `workspace`, `handoff`, and `feed` as the current Agent Pay
+shortcuts.
 
 ## Why This CLI Exists
 
@@ -22,6 +23,20 @@ with `submit` and `workspace` as the current Agent Pay shortcuts.
 - 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
@@ -31,11 +46,14 @@ Use:
 
 ## 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>`
 
@@ -44,12 +62,13 @@ 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` when the question is specifically Agent Pay
+- 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
@@ -59,6 +78,10 @@ zk-agent next
 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.
@@ -66,12 +89,18 @@ 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
@@ -159,30 +188,34 @@ The current local-first Agent Pay entry surface is:
 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` and
-`zk-agent payment workspace`.
+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 submit --wallet main --to <address> --amount <amount>
 zk-agent payment next --request-id <id>
-zk-agent payment approval --request-id <id>
+zk-agent approval --request-id <id>
 zk-agent workspace
-zk-agent payment handoff --request-id <id>
-zk-agent payment feed
+zk-agent handoff --request-id <id>
+zk-agent feed
 ```
 
 That path shows compact ingress, wallet-aware follow-up, approval readiness,
 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:
 
@@ -218,6 +251,8 @@ 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
@@ -240,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:
@@ -340,6 +375,10 @@ ZK_AGENT_STORAGE_DIR=
   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
@@ -381,20 +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 baseline --relay-url <relay-url>
-zk-agent wallet create --relay-url <relay-url> --wait-relay --prompt-code
-zk-agent next
+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 relay baseline --relay-url <relay-url>
-zk-agent wallet reapprove --name main --relay-url <relay-url> --wait-relay --prompt-code
+zk-agent wallet create --relay-url <relay-url> --wait-relay --prompt-code
 zk-agent next
 ```
 
@@ -413,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 baseline` before sending users to a share link when you want the
-packaged public summary and proof paths first. Use `relay inspect` when you
-need the lower-level hosted-readiness, URL shape, and persistence contract.
-
 For the supported hosted operating contract, use
 [`docs/16-hosted-approval-operated-baseline.md`](../../docs/16-hosted-approval-operated-baseline.md).
 
@@ -466,6 +508,10 @@ 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`.
 
@@ -484,10 +530,10 @@ For the clearest Agent Pay proof path inside `suite`, follow:
 ```bash
 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 approval --request-id <id>
 zk-agent workspace
-zk-agent payment handoff --request-id <id>
-zk-agent payment feed
+zk-agent handoff --request-id <id>
+zk-agent feed
 ```
 
 That is the shortest packaged route from one local request write into