zk-agent-cli 1.0.1 → 1.1.0

package/README.md

@@ -16,8 +16,8 @@ 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
+- 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
 
@@ -26,13 +26,44 @@ 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
@@ -60,7 +91,8 @@ That is the current packaged story in one minute:
 - 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 publish` + `zk-agent payment serve` +
+  `zk-agent payment verify-preview`
   already mark the hosted-preview boundary without claiming a multi-tenant
   control plane
 
@@ -73,7 +105,7 @@ That is the current packaged story in one minute:
 - 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`
+  `payment publish -> payment serve -> verify-preview`
 
 ## Best Fit
 
@@ -163,6 +195,9 @@ cross-request export. The scoped form remains `zk-agent payment feed`.
 `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
@@ -188,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
 
@@ -279,10 +316,19 @@ 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.
+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).
@@ -567,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
 
@@ -575,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`