zk-agent-cli 0.1.0-rc.1 → 0.1.0-rc.2

package/README.md

@@ -3,7 +3,41 @@
 `zk-agent-cli` is the packaged terminal CLI for the zk-agent operator path on
 zkSync Era and zkSync Sepolia.
 
-This file is the canonical operator manual for CLI users.
+This is the canonical CLI operator manual.
+
+Use:
+
+- [`skills/QUICKSTART.md`](../../skills/QUICKSTART.md) for the shortest
+  verified path
+- [`docs/15-codex-plugin-onboarding.md`](../../docs/15-codex-plugin-onboarding.md)
+  for the native Codex plugin/local marketplace path
+
+## One-minute path
+
+Use this path unless the task explicitly needs a lower-level command:
+
+```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
+```
+
+What each step is doing:
+
+- `setup` writes local defaults
+- `next` gives the shortest valid follow-up step
+- `wallet create --await-local` is the preferred local approval path
+- `workflow pay` is the flagship zkSync-native AA native-send path
+- `suite` is the packaged surface
+
+If readiness is unclear before you choose a fix, use:
+
+```bash
+zk-agent doctor
+```
 
 ## Install
 
@@ -26,7 +60,10 @@ The package also ships the alias:
 zksync-agent --help
 ```
 
-## Defaults and prerequisites
+The `npx skills add ...` path belongs to the repo skill bundle, not the
+packaged CLI install surface.
+
+## Defaults
 
 - Node.js `>=24`
 - the default chain is `zksync-sepolia`
@@ -46,32 +83,7 @@ ZK_AGENT_TOKEN_DIRECTORY_ROOT=
 ZK_AGENT_STORAGE_DIR=
 ```
 
-## Fastest verified path
-
-Use this path unless the task explicitly needs a lower-level command:
-
-```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>
-```
-
-Interpretation:
-
-- `setup` writes local defaults
-- `next` gives the shortest valid follow-up step
-- `wallet create --await-local` is the preferred local approval path
-- `workflow pay` is the flagship zkSync-native AA native-send path
-
-If readiness is unclear before you choose a fix, use:
-
-```bash
-zk-agent doctor
-```
-
-## Existing wallet recovery
+## Repair Paths
 
 If the wallet already exists and approval is missing or expired:
 
@@ -112,6 +124,15 @@ zk-agent wallet reapprove --name main --relay-url <relay-url> --wait-relay --pro
 zk-agent next
 ```
 
+Current supportable product shape on this path:
+
+- one externally reachable public origin
+- one relay host with same-host file persistence
+- one same-origin share-link + approval UI surface
+
+Do not assume multi-host or load-balanced durability on the current relay
+surface.
+
 If the relay is self-hosted through the built-in server:
 
 ```bash
@@ -125,16 +146,9 @@ path.
 For the supported hosted operating contract, use
 [`docs/16-hosted-approval-operated-baseline.md`](../../docs/16-hosted-approval-operated-baseline.md).
 
-## Funding and execution
-
-Only fund when the CLI tells you funding is required:
-
-```bash
-zk-agent workflow fund --wallet main
-zk-agent workflow fund --wallet main --amount <amount> --execute
-```
+## After Wallet Ready
 
-Flagship pay path:
+Default flagship write path:
 
 ```bash
 zk-agent workflow pay --wallet main --to <address> --amount <amount>
@@ -144,32 +158,34 @@ zk-agent workflow pay --wallet main --to <address> --amount <amount> --broadcast
 Keep `sed-lite` as the default AA baseline. Use `daily-spend-limit` only when
 you intentionally need that narrower policy profile.
 
-## Operator suite
-
-Use:
+Default packaged surface:
 
 ```bash
 zk-agent suite
 ```
 
-when you want the flagship path plus the current post-flagship surfaces in one
-place.
+Use `suite` when the wallet is already ready and you want one packaged surface
+for flagship pay, discovery/defaults, funding readiness, and approval-based
+paymaster readiness.
+
+Use `--wallet <name>` or `--chain <chain>` when the returned suite commands
+should stay on a non-default wallet or chain.
+
+Only fund when the CLI tells you funding is required:
+
+```bash
+zk-agent workflow fund --wallet main
+zk-agent workflow fund --wallet main --amount <amount> --execute
+```
 
-Current suite shape:
+Do not guess the route. Use the exact funding command suggested by `next`,
+`doctor`, `wallet status`, a blocked workflow, or `suite`.
 
-- flagship pay:
-  `zk-agent workflow pay --wallet main --to <address> --amount <amount>`
-- discovery/defaults:
-  `zk-agent assets --wallet main`
-  `zk-agent defaults`
-  `zk-agent resolve-token --chain zksync-sepolia --symbol USDC`
-- funding readiness:
-  `zk-agent workflow fund --wallet main`
-- paymaster readiness:
-  `zk-agent workflow pay --wallet main --to <address> --amount <amount> --paymaster-mode approval-based`
-  `zk-agent tokens --chain zksync-sepolia --role paymaster-fee-token`
+## Direct Paths
 
-## Discovery and direct commands
+Prefer `suite` first when you want the packaged discovery/defaults/funding/
+paymaster surface. Use the commands below only when you intentionally want a
+narrower path.
 
 Preferred discovery order:
 
@@ -178,8 +194,7 @@ Preferred discovery order:
 - `zk-agent defaults`
 - `zk-agent resolve-token --chain zksync-sepolia --symbol <symbol>`
 
-Use the direct commands when you intentionally want to bypass the workflow
-layer:
+Bypass examples:
 
 - `zk-agent send-token --wallet main --symbol USDC --to <address> --amount <amount>`
 - `zk-agent swap --wallet main --token-in-symbol USDC --token-out-symbol ETH --amount-in <amount>`
@@ -187,24 +202,9 @@ layer:
 - `zk-agent deposit --wallet main --symbol USDC --amount <amount>`
 - `zk-agent withdraw --wallet main --symbol USDC --amount <amount>`
 
-## Local storage
-
-By default the CLI stores local state under:
-
-```text
-~/.zk-agent/
-```
-
-Common files:
-
-- `config.json`
-- `wallets/*.json`
-- `requests/*.json`
-- `workflows/*.json`
-
-## Smart-account profiles
+## Smart-account Profiles
 
-The packaged CLI includes built-in profile artifacts for:
+Built-in profiles:
 
 - `sed-lite`
 - `daily-spend-limit`
@@ -224,32 +224,38 @@ zk-agent wallet smart-account deploy --profile sed-lite
 
 ## Common failures
 
-Connector callback never arrives:
+- connector callback never arrives:
+  verify the connector URL saved by `zk-agent setup`; if local callback is not
+  viable in the current environment, switch to the relay-backed path
+- wallet is missing a writable session:
+  run `zk-agent doctor --wallet <wallet>`, then inspect
+  `zk-agent wallet status --name <wallet>`; reapprove when approval is missing,
+  attach the signer when approval is still present
+- workflow stops on funding:
+  do not guess the route; run the exact `workflow fund` command suggested by
+  the CLI
+- locked-down environment blocks local callback or relay binding:
+  rerun from a normal host shell or use the relay/manual approval path that
+  matches the environment
 
-- verify the connector URL saved by `zk-agent setup`
-- if local callback is impossible in the current environment, switch to the
-  relay-backed path
+## Reference
 
-CLI says the wallet is missing a writable session:
+Local storage:
 
-- run `zk-agent doctor --wallet <wallet>`
-- inspect `zk-agent wallet status --name <wallet>`
-- reapprove when approval is missing
-- attach the signer when approval is present but local write readiness is not
-
-Workflow stops on funding:
-
-- do not guess the route
-- run the exact `workflow fund` command suggested by the CLI
+By default the CLI stores local state under:
 
-Locked-down environment blocks local callback or relay binding:
+```text
+~/.zk-agent/
+```
 
-- rerun from a normal host shell
-- or use a relay/manual approval path that matches the environment
+Common files:
 
-## Command help
+- `config.json`
+- `wallets/*.json`
+- `requests/*.json`
+- `workflows/*.json`
 
-Use:
+Help surfaces:
 
 ```bash
 zk-agent --help

package/dist/index.js

@@ -7654,7 +7654,10 @@ function isTTY() {
   return Boolean(process.stdout.isTTY);
 }
 function shouldJsonOutput() {
-  return !isTTY() || process.env.ZK_AGENT_OUTPUT === "json";
+  const requestedOutput = process.env.ZK_AGENT_OUTPUT?.trim().toLowerCase();
+  if (requestedOutput === "text") return false;
+  if (requestedOutput === "json") return true;
+  return !isTTY();
 }
 function jsonOut(value) {
   console.log(JSON.stringify(value, null, 2));
@@ -7820,6 +7823,16 @@ function appendPaymasterMode(command, paymasterMode) {
 function buildDefaultsRecommendedCommand() {
   return "zk-agent defaults";
 }
+function buildSuiteRecommendedCommand(walletName = "main", chain = "zksync-sepolia") {
+  const flags = [];
+  if (walletName !== "main") {
+    flags.push(`--wallet ${walletName}`);
+  }
+  if (chain !== "zksync-sepolia") {
+    flags.push(`--chain ${chain}`);
+  }
+  return flags.length > 0 ? `zk-agent suite ${flags.join(" ")}` : "zk-agent suite";
+}
 function buildTopLevelNextRecommendedCommand(requestId, paymasterMode) {
   const command = requestId ? `zk-agent next --request-id ${requestId}` : "zk-agent next";
   return appendPaymasterMode(command, paymasterMode);
@@ -10685,6 +10698,54 @@ function agentProfileLines(summary) {
   return lines;
 }
 
+// src/lib/suite-handoff.ts
+function buildSuiteHandoffSummary(input) {
+  const command = buildSuiteRecommendedCommand(input.walletName, input.chain);
+  const useWhen = "Use suite once wallet approval and local signer readiness are no longer the blocker and you want one packaged surface for flagship pay plus the current post-flagship discovery, paymaster, and funding slices.";
+  switch (input.currentSurface) {
+    case "next":
+      return {
+        currentSurface: input.currentSurface,
+        recommendedNow: input.recommendedNow,
+        command,
+        useWhen,
+        stayOnCurrentSurfaceWhen: "Stay on next when you still need the CLI to choose across setup, wallet readiness, and the shortest flagship workflow entry.",
+        note: input.recommendedNow ? "Wallet readiness is no longer the blocker. The default shortest action can still be workflow pay, while suite is the broader packaged follow-up surface." : "Suite is not the current recommendation because next is still steering setup or wallet remediation."
+      };
+    case "wallet":
+      return {
+        currentSurface: input.currentSurface,
+        recommendedNow: input.recommendedNow,
+        command,
+        useWhen,
+        stayOnCurrentSurfaceWhen: "Stay on wallet status or wallet next when approval, signer attach, deployment sync, or wallet-specific remediation is still the blocker.",
+        note: input.recommendedNow ? "Wallet readiness is no longer the blocker, so suite is available as the broader packaged surface." : "Suite is not the current recommendation because wallet-specific remediation is still the blocker."
+      };
+    case "workflow":
+      return {
+        currentSurface: input.currentSurface,
+        recommendedNow: input.recommendedNow,
+        command,
+        useWhen,
+        stayOnCurrentSurfaceWhen: "Stay on workflow when you already have an explicit workflow question, checkpoint, or execution state to inspect, continue, or resume.",
+        note: "This workflow surface stays authoritative for the current workflow. Switch to suite only after the question is no longer workflow-specific."
+      };
+    default: {
+      const exhaustive = input.currentSurface;
+      throw new Error(`Unsupported suite handoff surface: ${String(exhaustive)}`);
+    }
+  }
+}
+function suiteHandoffLines(summary) {
+  return [
+    ["suite", summary.command],
+    ["suite ready", summary.recommendedNow ? "yes" : "no"],
+    ["suite when", summary.useWhen],
+    [`stay on ${summary.currentSurface} when`, summary.stayOnCurrentSurfaceWhen],
+    ["suite note", summary.note]
+  ];
+}
+
 // src/lib/wallet-next.ts
 function buildWalletNextRecommendedCommands(walletName, summary, paymasterMode) {
   return {
@@ -10696,6 +10757,7 @@ function buildWalletNextRecommendedCommands(walletName, summary, paymasterMode)
     } : {},
     discoverTokens: buildTokensRecommendedCommand(summary.chain),
     inspectToken: buildResolveTokenRecommendedCommand(summary.chain),
+    suite: buildSuiteRecommendedCommand(walletName, summary.chain),
     walletStatus: buildWalletStatusRecommendedCommand(walletName),
     ...summary.recommendedCommand ? { nextAction: summary.recommendedCommand } : {}
   };
@@ -10777,6 +10839,7 @@ function buildTopLevelWorkflowRecommendedCommands(input) {
     resume: buildWorkflowResumeRecommendedCommand(input.requestId),
     delete: buildWorkflowDeleteRecommendedCommand(input.requestId),
     walletStatus: buildWalletStatusRecommendedCommand(input.walletName),
+    suite: buildSuiteRecommendedCommand(input.walletName, input.chain),
     ...input.nextAction ? { nextAction: input.nextAction } : {},
     ...workflowIntentSupportsTokenDiscovery2(input.intent) ? {
       discoverAssets: buildAssetsRecommendedCommand(input.walletName),
@@ -10857,6 +10920,9 @@ function buildNextHelpText() {
     "  Stay on the wallet layer only when you need wallet-specific remediation:",
     "    zk-agent wallet next --name main",
     "",
+    "  When the wallet is already ready and you want the packaged surface:",
+    "    zk-agent suite",
+    "",
     "  Switch to the hosted remote-approval path only when the browser is not colocated:",
     "    zk-agent relay inspect --relay-url <url>",
     "    zk-agent wallet create|reapprove --relay-url <url> --wait-relay --prompt-code",
@@ -10922,6 +10988,12 @@ function createNextCommand(deps) {
         paymasterMode: extractCheckpointPaymasterMode(updatedCheckpoint),
         recommendedCommands: recommendedCommands2
       });
+      const suiteHandoffSummary2 = buildSuiteHandoffSummary({
+        currentSurface: "workflow",
+        recommendedNow: false,
+        walletName: wallet2.walletName,
+        chain: result.plan.chain
+      });
       const workflowAgentProfile = await loadAgentIdentitySummary(wallet2.walletName);
       const agentFollowup2 = buildAgentFollowup(workflowAgentProfile, {
         walletName: wallet2.walletName,
@@ -10937,6 +11009,7 @@ function createNextCommand(deps) {
           ...agentProfileLines(workflowAgentProfile),
           ...agentFollowupLines(agentFollowup2),
           ...nextCommand2 ? [["next", nextCommand2]] : [],
+          ...suiteHandoffLines(suiteHandoffSummary2),
           ["inspect defaults", recommendedCommands2.inspectDefaults],
           ...result.blockingActionIds.map((actionId) => ["blocking action", actionId]),
           ...result.fundingProgress ? [
@@ -10958,6 +11031,7 @@ function createNextCommand(deps) {
           result,
           checkpoint: updatedCheckpoint,
           tokenDiscoverySummary: tokenDiscoverySummary2,
+          suiteHandoffSummary: suiteHandoffSummary2,
           recommendedCommands: recommendedCommands2
         }
       );
@@ -11124,6 +11198,7 @@ function createNextCommand(deps) {
     const recommendedCommands = {
       walletNext: buildWalletNextRecommendedCommand(wallet.walletName),
       walletStatus: buildWalletStatusRecommendedCommand(wallet.walletName),
+      suite: buildSuiteRecommendedCommand(wallet.walletName, wallet.chain),
       discoverAssets: buildAssetsRecommendedCommand(wallet.walletName),
       discoverOwnedTokens: buildOwnedTokensRecommendedCommand(wallet.walletName),
       ...paymasterMode === "approval-based" ? {
@@ -11163,6 +11238,12 @@ function createNextCommand(deps) {
       paymasterMode,
       recommendedCommands: mergedRecommendedCommands
     });
+    const suiteHandoffSummary = buildSuiteHandoffSummary({
+      currentSurface: "next",
+      recommendedNow: summary.status === "ready",
+      walletName: wallet.walletName,
+      chain: wallet.chain
+    });
     printResult(
       topLevelNextLines("wallet", [
         ...walletNextLines(summary),
@@ -11174,6 +11255,7 @@ function createNextCommand(deps) {
         ...mergedRecommendedCommands.attachSigner ? [["attach signer", mergedRecommendedCommands.attachSigner]] : [],
         ...mergedRecommendedCommands.relayInspect ? [["relay inspect", mergedRecommendedCommands.relayInspect]] : [],
         ...mergedRecommendedCommands.reapproveRemote ? [["remote fallback", mergedRecommendedCommands.reapproveRemote]] : [],
+        ...suiteHandoffLines(suiteHandoffSummary),
         ["discover assets", mergedRecommendedCommands.discoverAssets],
         ["discover owned tokens", mergedRecommendedCommands.discoverOwnedTokens],
         ...mergedRecommendedCommands.discoverPaymasterTokens ? [["discover paymaster tokens", mergedRecommendedCommands.discoverPaymasterTokens]] : [],
@@ -11194,6 +11276,7 @@ function createNextCommand(deps) {
         summary,
         nextCommand,
         tokenDiscoverySummary,
+        suiteHandoffSummary,
         recommendedCommands: mergedRecommendedCommands
       }
     );
@@ -12722,12 +12805,9 @@ function buildOperatorSuitePayload(options = {}) {
     id: "flagship-pay",
     title: "Flagship Pay",
     goal: "Run the default zkSync-native native-send path through the workflow layer.",
+    useWhen: "Start here when the wallet is already ready and the next real goal is a native send.",
     primaryCommand: flagshipCommand,
-    supportingCommands: [
-      "zk-agent next",
-      "zk-agent wallet status --name main",
-      inspectDefaults
-    ],
+    supportingCommands: ["zk-agent next", buildWalletStatusRecommendedCommand(walletName), inspectDefaults],
     skillPath: "skills/zk-aa/SKILL.md"
   };
   const slices = [
@@ -12735,6 +12815,7 @@ function buildOperatorSuitePayload(options = {}) {
       id: "discovery-defaults",
       title: "Discovery / Defaults",
       goal: "Discover owned assets, tracked defaults, and symbol-first token resolution before acting.",
+      useWhen: "Use this before tokenized actions or whenever asset/default context is unclear.",
       primaryCommand: discoveryCommand,
       supportingCommands: [
         inspectDefaults,
@@ -12748,6 +12829,7 @@ function buildOperatorSuitePayload(options = {}) {
       id: "paymaster-readiness",
       title: "Paymaster Readiness",
       goal: "Stay on the approval-based flagship path and recover the exact fee-token/default metadata when needed.",
+      useWhen: "Use this when approval-based pay or another sponsored write needs fee-token/default recovery.",
       primaryCommand: paymasterCommand,
       supportingCommands: [
         inspectDefaults,
@@ -12761,6 +12843,7 @@ function buildOperatorSuitePayload(options = {}) {
       id: "funding-readiness",
       title: "Funding Readiness",
       goal: "Ask the workflow layer for the exact funding route before executing bridge/deposit follow-up.",
+      useWhen: "Use this when the workflow path is blocked on gas or the CLI says funding is required.",
       primaryCommand: fundingCommand,
       supportingCommands: [
         buildWorkflowFundRunRecommendedCommand(walletName),
@@ -12777,14 +12860,17 @@ function buildOperatorSuitePayload(options = {}) {
       suiteId: "zk-agent-operator-suite",
       walletName,
       chain,
+      stage: "wallet-ready-post-flagship",
+      useWhen: "Use suite after wallet readiness when you want one packaged surface for flagship pay plus the current post-flagship discovery, paymaster, and funding slices.",
       flagshipId: flagship.id,
       postFlagshipSliceIds: slices.map((entry) => entry.id),
+      recommendedOrder: [flagship.id, ...slices.map((entry) => entry.id)],
       nextAction: flagship.primaryCommand
     },
     flagship,
     slices,
     recommendedCommands: {
-      suite: "zk-agent suite",
+      suite: buildSuiteRecommendedCommand(walletName, chain),
       flagship: flagshipCommand,
       discovery: discoveryCommand,
       paymaster: paymasterCommand,
@@ -12795,15 +12881,21 @@ function buildOperatorSuitePayload(options = {}) {
 }
 function operatorSuiteLines(payload) {
   const sliceLines = payload.slices.flatMap((entry) => [
-    [entry.id, formatRecommendedPath([entry.primaryCommand, ...entry.supportingCommands])],
-    [`${entry.id} skill`, entry.skillPath],
-    ...entry.smokeCommand ? [[`${entry.id} smoke`, entry.smokeCommand]] : []
+    [entry.title.toLowerCase(), formatRecommendedPath([entry.primaryCommand, ...entry.supportingCommands])],
+    [`${entry.title.toLowerCase()} when`, entry.useWhen],
+    [`${entry.title.toLowerCase()} skill`, entry.skillPath],
+    ...entry.smokeCommand ? [[`${entry.title.toLowerCase()} smoke`, entry.smokeCommand]] : []
   ]);
   return [
     ["suite", payload.summary.suiteId],
     ["wallet", payload.summary.walletName],
     ["chain", payload.summary.chain],
-    ["flagship", formatRecommendedPath([payload.flagship.primaryCommand, "zk-agent next"])],
+    ["stage", payload.summary.stage],
+    ["use when", payload.summary.useWhen],
+    ["recommended order", payload.summary.recommendedOrder.join(" -> ")],
+    [payload.flagship.title.toLowerCase(), formatRecommendedPath([payload.flagship.primaryCommand, "zk-agent next"])],
+    [`${payload.flagship.title.toLowerCase()} when`, payload.flagship.useWhen],
+    [`${payload.flagship.title.toLowerCase()} skill`, payload.flagship.skillPath],
     ...sliceLines,
     ["next action", payload.summary.nextAction]
   ];
@@ -12815,14 +12907,19 @@ function createSuiteCommand() {
     "after",
     [
       "",
-      "  Current operator suite:",
+      "  Use `suite` after wallet readiness when you want one packaged surface",
+      "  for flagship pay plus the current post-flagship slices.",
+      "",
+      "  Recommended order inside the suite:",
       "    zk-agent workflow pay --wallet main --to <address> --amount <amount>",
       "    zk-agent assets --wallet main",
-      "    zk-agent workflow fund --wallet main",
       "    zk-agent workflow pay --wallet main --to <address> --amount <amount> --paymaster-mode approval-based",
+      "    zk-agent workflow fund --wallet main",
+      "",
+      "  Pass `--wallet` or `--chain` to retarget the entire suite contract.",
       "",
-      "  Use `suite` when you want the flagship path plus the current",
-      "  post-flagship discovery/defaults, funding, and paymaster surfaces in one place."
+      "  In JSON mode, `summary.useWhen`, `summary.recommendedOrder`, and each",
+      "  entry `useWhen` field explain when to stay on one slice instead of guessing."
     ].join("\n")
   ).action((options) => {
     const payload = buildOperatorSuitePayload({
@@ -14034,7 +14131,9 @@ function buildRelayInspectPayload(relayUrl, rawHealth) {
   };
 }
 function createRelayCommand() {
-  const relay = new Command10("relay").description("Run the local connector relay prototype server");
+  const relay = new Command10("relay").description(
+    "Serve and inspect the single-host connector relay baseline for hosted approval"
+  );
   relay.addHelpText(
     "after",
     [
@@ -14045,6 +14144,12 @@ function createRelayCommand() {
       "    zk-agent wallet create --relay-url <url> --wait-relay --prompt-code",
       "    zk-agent wallet reapprove --name main --relay-url <url> --wait-relay --prompt-code",
       "",
+      "  Supported product claim today:",
+      "    one externally reachable public origin",
+      "    one relay host with same-host file persistence",
+      "    one same-origin share-link + approval UI surface",
+      "    Do not assume multi-host or load-balanced durability.",
+      "",
       "  Keep `wallet create|reapprove --await-local` as the default baseline when",
       "  the browser and terminal are colocated.",
       "",
@@ -17006,6 +17111,9 @@ function createWalletCommand(deps) {
       "    zk-agent wallet status --name main",
       "    zk-agent wallet next --name main",
       "",
+      "  When wallet readiness is no longer the blocker and you want the packaged surface:",
+      "    zk-agent suite",
+      "",
       "  Hosted remote approval path:",
       "    zk-agent relay inspect --relay-url <url>",
       "    zk-agent wallet create --relay-url <url> --wait-relay --prompt-code",
@@ -17601,9 +17709,16 @@ function createWalletCommand(deps) {
       paymasterMode: resolveEffectivePaymasterSelection(walletRecord)?.mode,
       recommendedCommands
     });
+    const suiteHandoffSummary = buildSuiteHandoffSummary({
+      currentSurface: "wallet",
+      recommendedNow: summary.status === "ready",
+      walletName: walletRecord.walletName,
+      chain: summary.chain
+    });
     printResult(
       [
         ...walletStatusLines(inspection, summary),
+        ...suiteHandoffLines(suiteHandoffSummary),
         ["discover assets", recommendedCommands.discoverAssets],
         ["discover owned tokens", recommendedCommands.discoverOwnedTokens],
         ...recommendedCommands.discoverPaymasterTokens ? [["discover paymaster tokens", recommendedCommands.discoverPaymasterTokens]] : [],
@@ -17617,6 +17732,7 @@ function createWalletCommand(deps) {
         inspection,
         summary,
         tokenDiscoverySummary,
+        suiteHandoffSummary,
         recommendedCommands
       }
     );
@@ -17636,9 +17752,16 @@ function createWalletCommand(deps) {
       paymasterMode: resolveEffectivePaymasterSelection(walletRecord)?.mode,
       recommendedCommands
     });
+    const suiteHandoffSummary = buildSuiteHandoffSummary({
+      currentSurface: "wallet",
+      recommendedNow: summary.status === "ready",
+      walletName: walletRecord.walletName,
+      chain: summary.chain
+    });
     printResult(
       [
         ...walletNextLines(summary),
+        ...suiteHandoffLines(suiteHandoffSummary),
         ["discover assets", recommendedCommands.discoverAssets],
         ["discover owned tokens", recommendedCommands.discoverOwnedTokens],
         ...recommendedCommands.discoverPaymasterTokens ? [["discover paymaster tokens", recommendedCommands.discoverPaymasterTokens]] : [],
@@ -17652,6 +17775,7 @@ function createWalletCommand(deps) {
         inspection,
         summary,
         tokenDiscoverySummary,
+        suiteHandoffSummary,
         recommendedCommands
       }
     );
@@ -20338,6 +20462,10 @@ async function printWorkflowRunCommandResult(execution, command) {
       result: execution.result,
       nextCommand: execution.result.nextCommand
     });
+    const suiteHandoffSummary2 = buildWorkflowSuiteHandoff({
+      walletName: execution.result.walletName,
+      chain: execution.result.plan.chain
+    });
     const workflowEntrySummary2 = buildWorkflowEntrySummary({
       command,
       source: execution.requestId ? "checkpoint" : "input",
@@ -20355,6 +20483,7 @@ async function printWorkflowRunCommandResult(execution, command) {
           [
             ...workflowRunLines(execution.result),
             ...workflowWalletApprovalLines(execution.walletApproval),
+            ...suiteHandoffLines(suiteHandoffSummary2),
             ...workflowFollowupLines(recommendedCommands2)
           ],
           agentProfile2,
@@ -20371,6 +20500,7 @@ async function printWorkflowRunCommandResult(execution, command) {
         result: execution.result,
         ...serializeWorkflowWalletApprovalOutput(execution.walletApproval),
         tokenDiscoverySummary: tokenDiscoverySummary2,
+        suiteHandoffSummary: suiteHandoffSummary2,
         recommendedCommands: recommendedCommands2
       }
     );
@@ -20405,6 +20535,10 @@ async function printWorkflowRunCommandResult(execution, command) {
     status,
     nextCommand: status.recommendedCommand
   });
+  const suiteHandoffSummary = buildWorkflowSuiteHandoff({
+    walletName: status.walletName,
+    chain: status.plan.chain
+  });
   const workflowEntrySummary = buildWorkflowEntrySummary({
     command,
     source: execution.requestId ? "checkpoint" : "input",
@@ -20421,6 +20555,7 @@ async function printWorkflowRunCommandResult(execution, command) {
         [
           ...workflowStatusLines(status),
           ...workflowWalletApprovalLines(execution.walletApproval),
+          ...suiteHandoffLines(suiteHandoffSummary),
           ...workflowFollowupLines(recommendedCommands)
         ],
         agentProfile,
@@ -20438,6 +20573,7 @@ async function printWorkflowRunCommandResult(execution, command) {
       checkpoint: execution.checkpoint,
       ...serializeWorkflowWalletApprovalOutput(execution.walletApproval),
       tokenDiscoverySummary,
+      suiteHandoffSummary,
       recommendedCommands
     }
   );
@@ -20718,6 +20854,10 @@ async function printWorkflowAutoCommandResult(execution, command) {
     result: execution.result,
     nextCommand: nextAction
   });
+  const suiteHandoffSummary = buildWorkflowSuiteHandoff({
+    walletName: execution.status.walletName,
+    chain: execution.status.plan.chain
+  });
   const workflowEntrySummary = buildWorkflowEntrySummary({
     command,
     source: execution.source,
@@ -20742,6 +20882,7 @@ async function printWorkflowAutoCommandResult(execution, command) {
           ...summaryLines,
           ...detailLines,
           ...workflowWalletApprovalLines(execution.walletApproval),
+          ...suiteHandoffLines(suiteHandoffSummary),
           ...workflowFollowupLines(recommendedCommands)
         ],
         agentProfile,
@@ -20763,6 +20904,7 @@ async function printWorkflowAutoCommandResult(execution, command) {
       checkpoint: execution.checkpoint,
       ...serializeWorkflowWalletApprovalOutput(execution.walletApproval),
       tokenDiscoverySummary,
+      suiteHandoffSummary,
       recommendedCommands
     }
   );
@@ -20800,6 +20942,14 @@ function extractPaymasterModeFromCommand(command) {
   const match = command.match(/--paymaster-mode (none|sponsored|approval-based)\b/);
   return match?.[1];
 }
+function buildWorkflowSuiteHandoff(input) {
+  return buildSuiteHandoffSummary({
+    currentSurface: "workflow",
+    recommendedNow: false,
+    walletName: input.walletName,
+    chain: input.chain
+  });
+}
 function buildWorkflowRuntimeRecommendedCommands(input) {
   const paymasterMode = extractPaymasterModeFromCommand(input.nextAction) ?? input.paymasterMode;
   return {
@@ -21300,6 +21450,9 @@ function buildWorkflowHelpText() {
     "    zk-agent workflow next --request-id <id>",
     "    zk-agent workflow resume --request-id <id> [--broadcast]",
     "",
+    "  When the explicit workflow is no longer the real question and you want the broader packaged surface:",
+    "    zk-agent suite",
+    "",
     "  Funding-only step:",
     "    zk-agent workflow fund --wallet main --amount <amount> --execute",
     "",
@@ -21636,6 +21789,10 @@ function createWorkflowCommand(deps) {
       status: inspection.result,
       nextCommand: inspection.result.recommendedCommand
     });
+    const suiteHandoffSummary = buildWorkflowSuiteHandoff({
+      walletName: inspection.result.walletName,
+      chain: inspection.result.plan.chain
+    });
     const workflowEntrySummary = buildWorkflowEntrySummary({
       command: "status",
       source: options.requestId?.trim() ? "checkpoint" : "input",
@@ -21652,6 +21809,7 @@ function createWorkflowCommand(deps) {
           [
             ...workflowStatusLines(inspection.result),
             ...workflowWalletApprovalLines(inspection.walletApproval),
+            ...suiteHandoffLines(suiteHandoffSummary),
             ...workflowFollowupLines(recommendedCommands)
           ],
           agentProfile,
@@ -21669,6 +21827,7 @@ function createWorkflowCommand(deps) {
         checkpoint: inspection.checkpoint,
         ...serializeWorkflowWalletApprovalOutput(inspection.walletApproval),
         tokenDiscoverySummary,
+        suiteHandoffSummary,
         recommendedCommands
       }
     );
@@ -21708,6 +21867,10 @@ function createWorkflowCommand(deps) {
       status: inspection.result,
       nextCommand
     });
+    const suiteHandoffSummary = buildWorkflowSuiteHandoff({
+      walletName: inspection.result.walletName,
+      chain: inspection.result.plan.chain
+    });
     const workflowEntrySummary = buildWorkflowEntrySummary({
       command: "next",
       source: options.requestId?.trim() ? "checkpoint" : "input",
@@ -21724,6 +21887,7 @@ function createWorkflowCommand(deps) {
           [
             ...workflowNextLines(inspection.result),
             ...workflowWalletApprovalLines(inspection.walletApproval),
+            ...suiteHandoffLines(suiteHandoffSummary),
             ...workflowFollowupLines(recommendedCommands)
           ],
           agentProfile,
@@ -21741,6 +21905,7 @@ function createWorkflowCommand(deps) {
         checkpoint: inspection.checkpoint,
         ...serializeWorkflowWalletApprovalOutput(inspection.walletApproval),
         tokenDiscoverySummary,
+        suiteHandoffSummary,
         recommendedCommands
       }
     );
@@ -21781,6 +21946,10 @@ function createWorkflowCommand(deps) {
         status: inspection.result,
         nextCommand: inspection.result.recommendedCommand
       });
+      const suiteHandoffSummary2 = buildWorkflowSuiteHandoff({
+        walletName: inspection.result.walletName,
+        chain: inspection.result.plan.chain
+      });
       const workflowEntrySummary2 = buildWorkflowEntrySummary({
         command: "resume",
         source: options.requestId?.trim() ? "checkpoint" : "input",
@@ -21797,6 +21966,7 @@ function createWorkflowCommand(deps) {
             [
               ...workflowStatusLines(inspection.result),
               ...workflowWalletApprovalLines(inspection.walletApproval),
+              ...suiteHandoffLines(suiteHandoffSummary2),
               ...workflowFollowupLines(recommendedCommands2)
             ],
             agentProfile2,
@@ -21814,6 +21984,7 @@ function createWorkflowCommand(deps) {
           checkpoint: inspection.checkpoint,
           ...serializeWorkflowWalletApprovalOutput(inspection.walletApproval),
           tokenDiscoverySummary: tokenDiscoverySummary2,
+          suiteHandoffSummary: suiteHandoffSummary2,
           recommendedCommands: recommendedCommands2
         }
       );
@@ -21857,6 +22028,10 @@ function createWorkflowCommand(deps) {
         status: status2,
         nextCommand: status2.recommendedCommand
       });
+      const suiteHandoffSummary2 = buildWorkflowSuiteHandoff({
+        walletName: status2.walletName,
+        chain: status2.plan.chain
+      });
       const workflowEntrySummary2 = buildWorkflowEntrySummary({
         command: "resume",
         source: options.requestId?.trim() ? "checkpoint" : "input",
@@ -21873,6 +22048,7 @@ function createWorkflowCommand(deps) {
             [
               ...workflowStatusLines(status2),
               ...workflowWalletApprovalLines(execution.walletApproval),
+              ...suiteHandoffLines(suiteHandoffSummary2),
               ...workflowFollowupLines(recommendedCommands2)
             ],
             agentProfile2,
@@ -21890,6 +22066,7 @@ function createWorkflowCommand(deps) {
           checkpoint: execution.checkpoint,
           ...serializeWorkflowWalletApprovalOutput(execution.walletApproval),
           tokenDiscoverySummary: tokenDiscoverySummary2,
+          suiteHandoffSummary: suiteHandoffSummary2,
           recommendedCommands: recommendedCommands2
         }
       );
@@ -21921,6 +22098,10 @@ function createWorkflowCommand(deps) {
       result: execution.result,
       nextCommand: execution.result.nextCommand ?? inspection.result.recommendedCommand
     });
+    const suiteHandoffSummary = buildWorkflowSuiteHandoff({
+      walletName: execution.result.walletName,
+      chain: execution.result.plan.chain
+    });
     const workflowEntrySummary = buildWorkflowEntrySummary({
       command: "resume",
       source: options.requestId?.trim() ? "checkpoint" : "input",
@@ -21938,6 +22119,7 @@ function createWorkflowCommand(deps) {
           [
             ...workflowRunLines(execution.result),
             ...workflowWalletApprovalLines(inspection.walletApproval),
+            ...suiteHandoffLines(suiteHandoffSummary),
             ...workflowFollowupLines(recommendedCommands)
           ],
           agentProfile,
@@ -21955,6 +22137,7 @@ function createWorkflowCommand(deps) {
         result: execution.result,
         ...serializeWorkflowWalletApprovalOutput(inspection.walletApproval),
         tokenDiscoverySummary,
+        suiteHandoffSummary,
         recommendedCommands
       }
     );
@@ -22017,6 +22200,7 @@ function buildDefaultOperatorPathHelpText() {
     "",
     "Use `zk-agent next --request-id <id>` to continue a stored workflow checkpoint.",
     "Use `zk-agent relay inspect --relay-url <url>` plus `zk-agent wallet create|reapprove --relay-url <url> --wait-relay --prompt-code` when the browser is not colocated.",
+    "Current hosted approval claim: one public origin, one relay host, and one same-origin share-link + approval UI surface.",
     "Use `zk-agent wallet --help` for wallet recovery details and `zk-agent workflow --help` when the intent is broader than the flagship native-send path."
   ].join("\n");
 }
@@ -22061,7 +22245,7 @@ function applyRootHelpCommandOrder(program) {
 }
 function createProgram() {
   const program = new Command13().name("zk-agent").description(
-    "Local-first zkSync Era CLI for wallet approval, workflow execution, and hosted relay recovery"
+    "Local-first zkSync-native CLI for wallet approval, workflow execution, and single-host hosted relay recovery"
   ).showHelpAfterError().option("--json", "Force JSON output for agent harnesses", false).hook("preAction", (thisCommand) => {
     if (thisCommand.optsWithGlobals().json) process.env.ZK_AGENT_OUTPUT = "json";
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zk-agent-cli",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.2",
   "description": "Local-first zkSync Era and ZK Stack agent CLI with wallet session recovery, workflow orchestration, relay-backed approval, and SED smart-account support.",
   "license": "MIT",
   "type": "module",
@@ -46,6 +46,10 @@
     "smoke:hosted-operated-baseline": "node --import tsx ./src/smoke-hosted-operated-baseline.ts",
     "smoke:remote-approval": "node --import tsx ./src/smoke-remote-approval.ts",
     "typecheck": "tsc --noEmit",
+    "test:onboarding": "pnpm --filter @zk-agent/agent-core build && pnpm run build && node --import ../../scripts/ensure-test-storage-isolation.mjs --import tsx --test ./tests/setup-cli.test.mjs",
+    "test:suite": "pnpm --filter @zk-agent/agent-core build && pnpm run build && node --import ../../scripts/ensure-test-storage-isolation.mjs --import tsx --test ./tests/suite-cli.test.mjs",
+    "test:wallet-status": "pnpm --filter @zk-agent/agent-core build && node --import ../../scripts/ensure-test-storage-isolation.mjs --import tsx --test ./tests/wallet-status-cli.test.mjs",
+    "test:product-surface": "pnpm --filter @zk-agent/agent-core build && pnpm run build && node --import ../../scripts/ensure-test-storage-isolation.mjs --import tsx --test ./tests/setup-cli.test.mjs ./tests/suite-cli.test.mjs ./tests/wallet-status-cli.test.mjs",
     "test": "pnpm --filter @zk-agent/agent-core build && pnpm run build && node --import ../../scripts/ensure-test-storage-isolation.mjs --import tsx --test ./tests/*.test.mjs ./tests/*.test.ts"
   },
   "engines": {