zk-agent-cli 1.0.0 → 1.0.1

package/README.md

@@ -1,18 +1,68 @@
 # zk-agent-cli
 
-`zk-agent-cli` is the packaged terminal CLI for the default zk-agent product path on
-zkSync Era and zkSync Sepolia.
+`zk-agent-cli` is the packaged local-first, payment-first CLI for the default
+zk-agent product path on zkSync Era and zkSync Sepolia.
+
+**Prove one zkSync-native pay path in minutes, keep wallet control local, and
+grow into Agent Pay on the same runtime.**
 
 This is the packaged CLI manual for the public product shell:
-`start -> next -> wallet create/reapprove -> next -> pay -> suite`,
+`setup -> start -> wallet create --await-local -> next -> pay -> suite`,
 with `submit`, `workspace`, `handoff`, and `feed` as the current Agent Pay
 shortcuts.
 
-## Why This CLI Exists
+For npm users evaluating it quickly, the product claim is simple:
+
+- pay first on one local-first zkSync-native path
+- keep Agent Pay follow-up on the same runtime instead of splitting it into
+  another product
+- use `payment publish -> payment serve` as the current public hosted-preview
+  proof, not as a claim of multi-tenant hosting
+
+## Install in 30 Seconds
+
+Use the install path that matches your environment:
+
+```bash
+npx skills add https://github.com/AgiWeb3/zk-agent-cli
+npx zk-agent-cli --help
+npm install -g zk-agent-cli
+```
+
+- `skills add`: install into an agent harness
+- `npx zk-agent-cli`: one-shot evaluation without a global install
+- `npm install -g zk-agent-cli`: keep `zk-agent` on your shell path
+
+## First Minute After Install
+
+If you only want the shortest public proof, do this and stop at the first
+successful pay:
+
+```bash
+zk-agent setup
+zk-agent start
+zk-agent wallet create --await-local
+zk-agent next
+zk-agent pay --wallet main --to <address> --amount <amount>
+zk-agent suite
+```
 
-- 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
+That is the current packaged story in one minute:
+
+- install once
+- prove one zkSync-native pay path
+- open the broader packaged surface only after that first success
+
+## Product Shell
+
+- pay first: prove one zkSync-native send path before learning the broader
+  packaged surface
+- stay on one runtime: keep Agent Pay follow-up, workspace, handoff, and feed
+  on the same wallet runtime
+- current public hosted-preview proof:
+  `zk-agent payment publish` + `zk-agent payment serve`
+  already mark the hosted-preview boundary without claiming a multi-tenant
+  control plane
 
 ## What Makes It Different
 
@@ -22,12 +72,16 @@ shortcuts.
   execution
 - one Agent Pay layer that stays attached to the same wallet runtime instead
   of splitting into a separate product
+- one public hosted-preview proof on top of that same request/export layer:
+  `payment publish -> payment serve`
 
 ## 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
+- the shortest path should be "prove one pay route first" instead of reading a
+  broad command catalog first
 - Agent Pay should stay attached to the same wallet runtime instead of
   becoming a separate operator tool
 
@@ -36,6 +90,8 @@ shortcuts.
 - 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
+- the hosted-preview proof is real, but it is still one operator-controlled
+  boundary rather than a hosted platform or control plane
 
 Use:
 
@@ -72,7 +128,7 @@ the first proof from a clean machine:
 
 ```bash
 zk-agent setup
-zk-agent next
+zk-agent start
 zk-agent wallet create --await-local
 zk-agent next
 zk-agent pay --wallet main --to <address> --amount <amount>
@@ -88,9 +144,11 @@ 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. If local defaults do not exist yet, both `start`
-and `next` still send you through `zk-agent setup` first.
+first-touch command after install. Keep `next` as the canonical
+operator/runtime contract in scripts and JSON examples. If local defaults do
+not exist yet, both `start` and `next` still send you through `zk-agent setup`
+first. On the public first-proof path, `start` is the front door and `next`
+is the follow-up step after wallet approval.
 
 `zk-agent pay` is the public shortcut for the flagship send path. The scoped
 form remains `zk-agent workflow pay`.
@@ -101,6 +159,10 @@ 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`.
+`zk-agent payment publish` materializes the current
+`workspace` / `feed` / `handoff` Agent Pay bundle as a hostable static export.
+`zk-agent payment serve` hosts that same bundle from one operator-controlled
+static endpoint.
 
 If you are new, stop at the first successful `zk-agent pay`. Ignore
 `suite`, `payment`, and `relay` until that baseline path works once, unless
@@ -213,6 +275,15 @@ 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.
 
+That same `workspace -> handoff -> feed` chain is also the current public
+Agent Pay proof on the hosted-preview boundary: an external dashboard, agent,
+or backend can consume the stable exports today from the same runtime or one
+operator-controlled host. `zk-agent payment publish` is the static half of
+that proof, and `zk-agent payment serve` is the hosted half. That preview is
+already proven on one stable public URL; the next step is to grow from that
+proof toward clearer hosted platform semantics without claiming a
+multi-tenant control plane too early.
+
 For the shortest product demo narrative behind that path, use
 [`docs/20-agent-pay-demo-narrative.md`](../../docs/20-agent-pay-demo-narrative.md).
 
@@ -523,7 +594,7 @@ Inside `suite`, the shortest way to think about Agent Pay is:
 - `feed`: export the stable cross-request batch view
 
 The shortest tracked route inside `suite` remains:
-`submit -> next -> approval -> workspace -> handoff -> feed`.
+`submit -> payment next -> approval -> workspace -> handoff -> feed`.
 
 For the clearest Agent Pay proof path inside `suite`, follow: