zk-agent-cli 1.0.0 → 1.1.0

package/README.md

@@ -1,18 +1,100 @@
 # 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 -> verify-preview` 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
+npx zk-agent-cli mcp
+npm install -g zk-agent-cli
+```
+
+- `skills add`: install into an agent harness
+- `npx zk-agent-cli`: one-shot evaluation without a global install
+- `npx zk-agent-cli mcp`: start the AI-facing MCP stdio server instead of the human CLI
+- `npm install -g zk-agent-cli`: keep `zk-agent` on your shell path
+
+## AI-native entrypoint
+
+When the consumer already speaks MCP and wants tools rather than CLI text,
+start:
+
+```bash
+npx zk-agent-cli mcp
+```
+
+Current boundary:
+
+- the MCP server is built on top of `packages/agent-tools`
+- it exposes the same standard tool catalog plus `zkAgentRecommendedSequence`
+- keep shell automation on `zk-agent --json ...` or
+  `zk-agent --format json ...`; use `mcp` when the client already speaks MCP
+- `1.1.0` completes the packaged MCP baseline; it does not yet claim
+  framework-specific adapters or a fully expanded MCP ecosystem layer
+
+Minimal import surface:
+
+```ts
+import {
+  createZkAgentToolContext,
+  listZkAgentTools,
+  runZkAgentTool
+} from 'zk-agent-cli';
+import { createZkAgentMcpServer } from 'zk-agent-cli/mcp';
+```
+
+## 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
+```
+
+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
 
-- 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
+## 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` +
+  `zk-agent payment verify-preview`
+  already mark the hosted-preview boundary without claiming a multi-tenant
+  control plane
 
 ## What Makes It Different
 
@@ -22,12 +104,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 -> verify-preview`
 
 ## 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 +122,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 +160,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 +176,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 +191,13 @@ 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.
+`zk-agent payment verify-preview` validates that one hosted preview URL still
+matches the current `health` / `index` / `manifest` / `workspace` / `feed` /
+`handoff` export contract.
 
 If you are new, stop at the first successful `zk-agent pay`. Ignore
 `suite`, `payment`, and `relay` until that baseline path works once, unless
@@ -126,11 +223,13 @@ 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 three public proof paths today are:
+The four 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 Agent Pay preview: prove that the current workspace/feed/handoff
+  bundle can already be published and served behind one operator-controlled URL, then validated against that same public export contract
 - hosted approval recovery: prove remote-browser session recovery on the
   current single-host relay baseline
 
@@ -213,6 +312,24 @@ 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, `zk-agent payment serve` is the hosted half, and
+`zk-agent payment verify-preview` is the operator validation follow-up against
+the public URL. 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.
+
+The fastest hosted Agent Pay preview proof path is:
+
+```bash
+zk-agent payment publish --public-base-url <https-url>
+zk-agent payment serve --public-origin <https-url>
+zk-agent payment verify-preview --url <https-url>
+```
+
 For the shortest product demo narrative behind that path, use
 [`docs/20-agent-pay-demo-narrative.md`](../../docs/20-agent-pay-demo-narrative.md).
 
@@ -496,7 +613,8 @@ Current `suite` catalog categories:
 Current `suite` handoff surfaces:
 
 - `workflow`: flagship pay, approval-based pay, and funding recovery
-- `payment`: request capture, follow-up, sharing, export, and approval repair
+- `payment`: request capture, follow-up, sharing, export, approval repair,
+  and hosted preview
 - `discovery`: assets/defaults/token inspection
 - `relay`: hosted approval recovery
 
@@ -504,6 +622,7 @@ Current `suite` product journeys:
 
 - `send value now`
 - `capture and track payments`
+- `host current Agent Pay preview`
 - `inspect before acting`
 - `unstick a write`
 - `recover remote approval`
@@ -523,7 +642,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: