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

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command as Command13, CommanderError } from "commander";
+import { Command as Command14, CommanderError } from "commander";
 import { config as loadEnv } from "dotenv";
 
 // src/commands/operations.ts
@@ -79,6 +79,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+// ../agent-core/src/wallet-session.ts
+import { createHash } from "node:crypto";
+
 // ../agent-session-protocol/src/constants.ts
 var PROTOCOL_VERSION = "zk-agent-session-v1";
 
@@ -239,6 +242,10 @@ function buildApprovedSessionPayload(input) {
 function isHexPrivateKey(value) {
   return /^0x[a-fA-F0-9]{64}$/.test(value);
 }
+function deriveStableWalletId(wallet) {
+  const seed = `${wallet.walletAddress.trim().toLowerCase()}:${wallet.chainId}:${wallet.createdAt.trim()}`;
+  return `wal_${createHash("sha256").update(seed).digest("hex").slice(0, 24)}`;
+}
 function deriveLocalExecutionSignerAddress(privateKey) {
   if (!privateKey || !isHexPrivateKey(privateKey)) return void 0;
   try {
@@ -263,15 +270,25 @@ function resolveLocalExecutionPrivateKey(wallet) {
 function migrateWalletSessionRecord(wallet) {
   const legacyPrivateKey = wallet.sessionPayload?.sessionPrivateKey;
   const existingAuthority = wallet.localExecutionAuthority;
+  const walletId = wallet.walletId || deriveStableWalletId(wallet);
   if (!existingAuthority && !legacyPrivateKey) {
-    return wallet;
+    if (wallet.walletId === walletId) return wallet;
+    return {
+      ...wallet,
+      walletId
+    };
   }
   const privateKey = existingAuthority?.privateKey || legacyPrivateKey;
   if (!privateKey) {
-    return wallet;
+    if (wallet.walletId === walletId) return wallet;
+    return {
+      ...wallet,
+      walletId
+    };
   }
   return {
     ...wallet,
+    walletId,
     localExecutionAuthority: {
       privateKey,
       signerAddress: existingAuthority?.signerAddress || deriveLocalExecutionSignerAddress(privateKey),
@@ -375,6 +392,33 @@ function readEncryptedJson(filePath) {
 function storageDir() {
   return ensureStorageDir();
 }
+function ensureStorageCollectionDir(collectionName) {
+  const storageDirectory = ensureStorageDir();
+  const collectionDirectory = path.join(storageDirectory, collectionName);
+  if (!fs.existsSync(collectionDirectory)) {
+    fs.mkdirSync(collectionDirectory, { recursive: true, mode: 448 });
+  }
+  return collectionDirectory;
+}
+async function saveEncryptedStorageRecord(collectionName, recordId, value) {
+  const collectionDirectory = ensureStorageCollectionDir(collectionName);
+  writeEncryptedJson(path.join(collectionDirectory, `${recordId}.json`), value);
+}
+async function loadEncryptedStorageRecord(collectionName, recordId) {
+  const filePath = storagePath(collectionName, `${recordId}.json`);
+  if (!fs.existsSync(filePath)) return null;
+  return readEncryptedJson(filePath);
+}
+async function listEncryptedStorageRecordIds(collectionName) {
+  const collectionDirectory = ensureStorageCollectionDir(collectionName);
+  return fs.readdirSync(collectionDirectory).filter((entry) => entry.endsWith(".json")).map((entry) => entry.replace(/\.json$/, ""));
+}
+async function deleteEncryptedStorageRecord(collectionName, recordId) {
+  const filePath = storagePath(collectionName, `${recordId}.json`);
+  if (!fs.existsSync(filePath)) return false;
+  fs.unlinkSync(filePath);
+  return true;
+}
 async function saveProjectConfig(config) {
   const storageDirectory = ensureStorageDir();
   writeJson(path.join(storageDirectory, "config.json"), config);
@@ -385,64 +429,42 @@ async function loadProjectConfig() {
   return readJson(filePath);
 }
 async function saveWalletSession(record) {
-  const storageDirectory = ensureStorageDir();
-  writeEncryptedJson(
-    path.join(storageDirectory, "wallets", `${record.walletName}.json`),
-    migrateWalletSessionRecord(record)
-  );
+  await saveEncryptedStorageRecord("wallets", record.walletName, migrateWalletSessionRecord(record));
 }
 async function loadWalletSession(walletName) {
-  const filePath = storagePath("wallets", `${walletName}.json`);
-  if (!fs.existsSync(filePath)) return null;
-  return migrateWalletSessionRecord(readEncryptedJson(filePath));
+  const record = await loadEncryptedStorageRecord("wallets", walletName);
+  return record ? migrateWalletSessionRecord(record) : null;
 }
 async function listWalletNames() {
-  const storageDirectory = ensureStorageDir();
-  return fs.readdirSync(path.join(storageDirectory, "wallets")).filter((entry) => entry.endsWith(".json")).map((entry) => entry.replace(/\.json$/, ""));
+  return listEncryptedStorageRecordIds("wallets");
 }
 async function listWalletRequestIds() {
   const storageDirectory = ensureStorageDir();
   return fs.readdirSync(path.join(storageDirectory, "requests")).filter((entry) => entry.endsWith(".json")).map((entry) => entry.replace(/\.json$/, ""));
 }
 async function deleteWalletSession(walletName) {
-  const filePath = storagePath("wallets", `${walletName}.json`);
-  if (!fs.existsSync(filePath)) return false;
-  fs.unlinkSync(filePath);
-  return true;
+  return deleteEncryptedStorageRecord("wallets", walletName);
 }
 async function saveWalletRequest(record) {
-  const storageDirectory = ensureStorageDir();
-  writeEncryptedJson(path.join(storageDirectory, "requests", `${record.requestId}.json`), record);
+  await saveEncryptedStorageRecord("requests", record.requestId, record);
 }
 async function loadWalletRequest(requestId) {
-  const filePath = storagePath("requests", `${requestId}.json`);
-  if (!fs.existsSync(filePath)) return null;
-  return readEncryptedJson(filePath);
+  return loadEncryptedStorageRecord("requests", requestId);
 }
 async function deleteWalletRequest(requestId) {
-  const filePath = storagePath("requests", `${requestId}.json`);
-  if (!fs.existsSync(filePath)) return false;
-  fs.unlinkSync(filePath);
-  return true;
+  return deleteEncryptedStorageRecord("requests", requestId);
 }
 async function saveWorkflowCheckpoint(record) {
-  const storageDirectory = ensureStorageDir();
-  writeEncryptedJson(path.join(storageDirectory, "workflows", `${record.requestId}.json`), record);
+  await saveEncryptedStorageRecord("workflows", record.requestId, record);
 }
 async function loadWorkflowCheckpoint(requestId) {
-  const filePath = storagePath("workflows", `${requestId}.json`);
-  if (!fs.existsSync(filePath)) return null;
-  return readEncryptedJson(filePath);
+  return loadEncryptedStorageRecord("workflows", requestId);
 }
 async function listWorkflowCheckpointIds() {
-  const storageDirectory = ensureStorageDir();
-  return fs.readdirSync(path.join(storageDirectory, "workflows")).filter((entry) => entry.endsWith(".json")).map((entry) => entry.replace(/\.json$/, ""));
+  return listEncryptedStorageRecordIds("workflows");
 }
 async function deleteWorkflowCheckpoint(requestId) {
-  const filePath = storagePath("workflows", `${requestId}.json`);
-  if (!fs.existsSync(filePath)) return false;
-  fs.unlinkSync(filePath);
-  return true;
+  return deleteEncryptedStorageRecord("workflows", requestId);
 }
 async function renameWalletSession(walletName, nextWalletName) {
   const storageDirectory = ensureStorageDir();
@@ -461,7 +483,7 @@ async function renameWalletSession(walletName, nextWalletName) {
   if (fs.existsSync(targetFilePath)) {
     throw new Error(`Wallet already exists: ${targetName}`);
   }
-  const wallet = readEncryptedJson(currentFilePath);
+  const wallet = migrateWalletSessionRecord(readEncryptedJson(currentFilePath));
   wallet.walletName = targetName;
   writeEncryptedJson(targetFilePath, wallet);
   fs.unlinkSync(currentFilePath);
@@ -7823,7 +7845,7 @@ function appendPaymasterMode(command, paymasterMode) {
 function buildDefaultsRecommendedCommand() {
   return "zk-agent defaults";
 }
-function buildSuiteRecommendedCommand(walletName = "main", chain = "zksync-sepolia") {
+function buildSuiteRecommendedCommand(walletName = "main", chain = "zksync-sepolia", options = {}) {
   const flags = [];
   if (walletName !== "main") {
     flags.push(`--wallet ${walletName}`);
@@ -7831,14 +7853,18 @@ function buildSuiteRecommendedCommand(walletName = "main", chain = "zksync-sepol
   if (chain !== "zksync-sepolia") {
     flags.push(`--chain ${chain}`);
   }
+  if (options.includeOnboarding) {
+    flags.push("--include-onboarding");
+  }
   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";
+function buildTopLevelNextRecommendedCommand(requestId, paymasterMode, walletName = "main") {
+  const command = requestId ? `zk-agent next --request-id ${requestId}` : walletName !== "main" ? `zk-agent next --wallet ${walletName}` : "zk-agent next";
   return appendPaymasterMode(command, paymasterMode);
 }
-function buildWalletCreateRecommendedCommand(paymasterMode) {
-  return appendPaymasterMode("zk-agent wallet create --await-local", paymasterMode);
+function buildWalletCreateRecommendedCommand(paymasterMode, walletName = "main") {
+  const command = walletName !== "main" ? `zk-agent wallet create --name ${walletName} --await-local` : "zk-agent wallet create --await-local";
+  return appendPaymasterMode(command, paymasterMode);
 }
 function buildRelayInspectRecommendedCommand(relayUrl = "<url>") {
   return `zk-agent relay inspect --relay-url ${relayUrl}`;
@@ -7996,6 +8022,37 @@ function buildWorkflowPayRecommendedCommand(walletName, paymasterMode) {
   const command = `zk-agent workflow pay --wallet ${walletName} --to <address> --amount <amount>`;
   return appendPaymasterMode(command, paymasterMode);
 }
+function buildSendTokenRecommendedCommand(input) {
+  let command = `zk-agent send-token --wallet ${input.walletName}`;
+  command += ` --to ${input.to || "<address>"}`;
+  command += ` --amount ${input.amount || "<amount>"}`;
+  if (input.symbol) {
+    command += ` --symbol ${input.symbol}`;
+  }
+  if (input.tokenAddress) {
+    command += ` --token ${input.tokenAddress}`;
+  }
+  if (input.decimals !== void 0) {
+    command += ` --decimals ${input.decimals}`;
+  }
+  return appendPaymasterMode(command, input.paymasterMode);
+}
+function buildPaymentListRecommendedCommand() {
+  return "zk-agent payment list";
+}
+function buildPaymentShowRecommendedCommand(requestId) {
+  return `zk-agent payment show --request-id ${requestId}`;
+}
+function buildPaymentSetStatusRecommendedCommand(requestId, status, txHash) {
+  let command = `zk-agent payment set-status --request-id ${requestId} --status ${status}`;
+  if (txHash) {
+    command += ` --tx-hash ${txHash}`;
+  }
+  return command;
+}
+function buildPaymentRemoveRecommendedCommand(requestId) {
+  return `zk-agent payment remove --request-id ${requestId}`;
+}
 function buildWorkflowFundRecommendedCommand(walletName) {
   return `zk-agent workflow fund --wallet ${walletName}`;
 }
@@ -10175,28 +10232,28 @@ function recommendedPathLines(paths) {
     ...paths.remoteBrowser?.length ? [["path (remote-browser)", formatRecommendedPath(paths.remoteBrowser)]] : []
   ];
 }
-function buildSetupRecommendedPaths(relayUrl = "<url>", paymasterMode) {
-  const next = buildTopLevelNextRecommendedCommand(void 0, paymasterMode);
+function buildSetupRecommendedPaths(relayUrl = "<url>", paymasterMode, walletName = "main") {
+  const next = buildTopLevelNextRecommendedCommand(void 0, paymasterMode, walletName);
   return {
     local: [
       "zk-agent setup",
       next,
-      buildWalletCreateRecommendedCommand(paymasterMode),
+      buildWalletCreateRecommendedCommand(paymasterMode, walletName),
       next
     ],
     remoteBrowser: [
       "zk-agent setup",
       next,
       buildRelayInspectRecommendedCommand(relayUrl),
-      buildWalletCreateRemoteRecommendedCommand(relayUrl, paymasterMode),
+      buildWalletCreateRemoteRecommendedCommand(relayUrl, paymasterMode, walletName),
       next
     ]
   };
 }
 function buildWalletBootstrapRecommendedPaths(relayUrl = "<url>", paymasterMode, walletName = "main") {
-  const next = buildTopLevelNextRecommendedCommand(void 0, paymasterMode);
+  const next = buildTopLevelNextRecommendedCommand(void 0, paymasterMode, walletName);
   return {
-    local: [buildWalletCreateRecommendedCommand(paymasterMode), next],
+    local: [buildWalletCreateRecommendedCommand(paymasterMode, walletName), next],
     remoteBrowser: [
       buildRelayInspectRecommendedCommand(relayUrl),
       buildWalletCreateRemoteRecommendedCommand(relayUrl, paymasterMode, walletName),
@@ -10205,7 +10262,7 @@ function buildWalletBootstrapRecommendedPaths(relayUrl = "<url>", paymasterMode,
   };
 }
 function buildWalletReapprovalRecommendedPaths(walletName, relayUrl = "<url>", paymasterMode) {
-  const next = buildTopLevelNextRecommendedCommand(void 0, paymasterMode);
+  const next = buildTopLevelNextRecommendedCommand(void 0, paymasterMode, walletName);
   return {
     local: [buildWalletReapproveRecommendedCommand(walletName), next],
     remoteBrowser: [
@@ -10219,7 +10276,7 @@ function buildSignerRecoveryRecommendedPaths(walletName, paymasterMode) {
   return {
     local: [
       buildWalletSignerAttachRecommendedCommand(walletName),
-      buildTopLevelNextRecommendedCommand(void 0, paymasterMode)
+      buildTopLevelNextRecommendedCommand(void 0, paymasterMode, walletName)
     ]
   };
 }
@@ -10698,11 +10755,139 @@ function agentProfileLines(summary) {
   return lines;
 }
 
+// src/lib/product-entry-summary.ts
+function buildProductEntrySummary(input) {
+  const currentSurface = input.currentSurface ?? "next";
+  switch (input.stage) {
+    case "setup":
+      return {
+        view: "product-entry",
+        currentSurface,
+        stage: input.stage,
+        category: "bootstrap",
+        recommendedMode: "local-first",
+        nextSurface: input.nextSurface ?? "setup",
+        nextAction: input.nextAction ?? null,
+        suiteAvailable: false,
+        note: input.note ?? "Start with setup first. The operator path is still in first-run bootstrap."
+      };
+    case "wallet-bootstrap":
+      return {
+        view: "product-entry",
+        currentSurface,
+        stage: input.stage,
+        category: "bootstrap",
+        recommendedMode: "local-first",
+        nextSurface: input.nextSurface ?? "wallet",
+        nextAction: input.nextAction ?? null,
+        suiteAvailable: false,
+        note: input.note ?? "Local defaults exist, but wallet bootstrap is still the current product question."
+      };
+    case "wallet-recovery":
+      return {
+        view: "product-entry",
+        currentSurface,
+        stage: input.stage,
+        category: "recover",
+        recommendedMode: "local-first",
+        nextSurface: input.nextSurface ?? "wallet",
+        nextAction: input.nextAction ?? null,
+        suiteAvailable: false,
+        note: input.note ?? "Stay on wallet recovery until approval or local signer readiness stops being the blocker."
+      };
+    case "wallet-ready":
+      return {
+        view: "product-entry",
+        currentSurface,
+        stage: input.stage,
+        category: "operate",
+        recommendedMode: "local-first",
+        nextSurface: input.nextSurface ?? (currentSurface === "doctor" ? "next" : "workflow"),
+        nextAction: input.nextAction ?? null,
+        suiteAvailable: input.suiteAvailable === true,
+        note: input.note ?? (currentSurface === "doctor" ? "Local readiness is clear. Return to zk-agent next when you want the live operator path instead of a local-only diagnosis." : "The default product action is now the flagship workflow path. Switch to suite when the question becomes broader than one flagship pay step.")
+      };
+    case "workflow":
+      return {
+        view: "product-entry",
+        currentSurface,
+        stage: input.stage,
+        category: "workflow",
+        recommendedMode: "workflow-followup",
+        nextSurface: input.nextSurface ?? "workflow",
+        nextAction: input.nextAction ?? null,
+        suiteAvailable: input.suiteAvailable === true,
+        note: input.note ?? "A stored workflow checkpoint is now the active product context. Stay on workflow follow-up until the question is no longer workflow-specific."
+      };
+    default: {
+      const exhaustive = input.stage;
+      throw new Error(`Unsupported product entry stage: ${String(exhaustive)}`);
+    }
+  }
+}
+function productEntrySummaryLines(summary) {
+  return [
+    ["entry view", summary.view],
+    ["entry category", summary.category],
+    ["recommended mode", summary.recommendedMode],
+    ["next surface", summary.nextSurface],
+    ["suite available", summary.suiteAvailable ? "yes" : "no"],
+    ["entry note", summary.note]
+  ];
+}
+
 // src/lib/suite-handoff.ts
+function buildSuiteHandoffJourney(journeyId, walletName) {
+  switch (journeyId) {
+    case "send-value-now":
+      return {
+        id: journeyId,
+        title: "Send Value Now",
+        command: buildWorkflowPayRecommendedCommand(walletName)
+      };
+    case "inspect-before-acting":
+      return {
+        id: journeyId,
+        title: "Inspect Before Acting",
+        command: buildAssetsRecommendedCommand(walletName)
+      };
+    case "unstick-a-write":
+      return {
+        id: journeyId,
+        title: "Unstick a Write",
+        command: buildWorkflowPayRecommendedCommand(walletName, "approval-based")
+      };
+    case "recover-remote-approval":
+      return {
+        id: journeyId,
+        title: "Recover Remote Approval",
+        command: buildRelayInspectRecommendedCommand("<url>")
+      };
+    case null:
+    case void 0:
+      return null;
+    default: {
+      const exhaustive = journeyId;
+      throw new Error(`Unsupported suite handoff journey: ${String(exhaustive)}`);
+    }
+  }
+}
 function buildSuiteHandoffSummary(input) {
+  const walletName = input.walletName?.trim() || "main";
   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.";
+  const recommendedJourney = input.recommendedNow === true ? buildSuiteHandoffJourney(input.recommendedJourneyId ?? null, walletName) : null;
+  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, funding, and hosted recovery slices.";
   switch (input.currentSurface) {
+    case "doctor":
+      return {
+        currentSurface: input.currentSurface,
+        recommendedNow: input.recommendedNow,
+        command,
+        useWhen,
+        stayOnCurrentSurfaceWhen: "Stay on doctor when local config, approval metadata, or local signer state is still unclear and you need a local-only diagnosis before choosing the live path.",
+        note: input.recommendedNow ? "Local readiness is clear. Return to zk-agent next for the shortest live path, or start with the suggested suite journey when the operator question is broader than one immediate flagship workflow step." : "Suite is not the current recommendation because doctor is still diagnosing a local setup or wallet-readiness blocker.",
+        recommendedJourney
+      };
     case "next":
       return {
         currentSurface: input.currentSurface,
@@ -10710,7 +10895,8 @@ function buildSuiteHandoffSummary(input) {
         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."
+        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. Start with the suggested suite journey when the question is broader than one immediate workflow pay step." : "Suite is not the current recommendation because next is still steering setup or wallet remediation.",
+        recommendedJourney
       };
     case "wallet":
       return {
@@ -10719,7 +10905,8 @@ function buildSuiteHandoffSummary(input) {
         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."
+        note: input.recommendedNow ? "Wallet readiness is no longer the blocker, so suite is available as the broader packaged surface. Start with the suggested suite journey when the operator question is broader than one wallet-status remediation step." : "Suite is not the current recommendation because wallet-specific remediation is still the blocker.",
+        recommendedJourney
       };
     case "workflow":
       return {
@@ -10728,7 +10915,8 @@ function buildSuiteHandoffSummary(input) {
         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."
+        note: "This workflow surface stays authoritative for the current workflow. Switch to suite only after the question is no longer workflow-specific.",
+        recommendedJourney
       };
     default: {
       const exhaustive = input.currentSurface;
@@ -10741,6 +10929,13 @@ function suiteHandoffLines(summary) {
     ["suite", summary.command],
     ["suite ready", summary.recommendedNow ? "yes" : "no"],
     ["suite when", summary.useWhen],
+    ...summary.recommendedJourney ? [
+      [
+        "suite journey",
+        `${summary.recommendedJourney.id} (${summary.recommendedJourney.title})`
+      ],
+      ["suite journey start", summary.recommendedJourney.command]
+    ] : [],
     [`stay on ${summary.currentSurface} when`, summary.stayOnCurrentSurfaceWhen],
     ["suite note", summary.note]
   ];
@@ -10866,8 +11061,8 @@ function resolveNextCommandDeps(deps) {
 function buildSetupCommand() {
   return "zk-agent setup";
 }
-function buildTopLevelNextRecommendedCommand2(requestId) {
-  return requestId ? `zk-agent next --request-id ${requestId}` : "zk-agent next";
+function buildTopLevelNextRecommendedCommand2(requestId, walletName = "main") {
+  return requestId ? `zk-agent next --request-id ${requestId}` : walletName !== "main" ? `zk-agent next --wallet ${walletName}` : "zk-agent next";
 }
 function buildTopLevelWorkflowSummary(result, nextCommand) {
   return {
@@ -10888,10 +11083,11 @@ function appendPaymasterMode2(command, paymasterMode) {
   if (!paymasterMode) return command;
   return `${command} --paymaster-mode ${paymasterMode}`;
 }
-function topLevelNextLines(scope, lines, onboardingSummary) {
+function topLevelNextLines(scope, lines, onboardingSummary, productEntrySummary) {
   return [
     ["scope", scope],
     ...onboardingSummary ? onboardingSummaryLines(onboardingSummary) : [],
+    ...productEntrySummary ? productEntrySummaryLines(productEntrySummary) : [],
     ...lines
   ];
 }
@@ -10901,6 +11097,13 @@ function buildNextHelpText() {
     "Use `next` as the product entrypoint:",
     "  Stay on `next` until it points you at a wallet-specific or workflow-specific blocker.",
     "",
+    "  What `next` answers right now:",
+    "    bootstrap: config or wallet bootstrap is still the current blocker",
+    "    recover: wallet approval or local signer readiness still needs repair",
+    "    operate: wallet readiness is clear, so the flagship workflow path is next",
+    "    workflow: a stored checkpoint is already the active question",
+    "    suite: switch only when the question becomes broader than one immediate next step",
+    "",
     "  Fresh local-first routing:",
     "    zk-agent setup",
     "    zk-agent next",
@@ -10999,6 +11202,11 @@ function createNextCommand(deps) {
         walletName: wallet2.walletName,
         walletExists: true
       });
+      const productEntrySummary2 = buildProductEntrySummary({
+        stage: "workflow",
+        nextAction: nextCommand2,
+        suiteAvailable: false
+      });
       printResult(
         topLevelNextLines("workflow", [
           ["workflow request", requestId],
@@ -11017,7 +11225,7 @@ function createNextCommand(deps) {
             ["funding txHash", result.fundingProgress.txHash],
             ["funding status", result.fundingProgress.status]
           ] : []
-        ]),
+        ], void 0, productEntrySummary2),
         {
           ok: true,
           scope: "workflow",
@@ -11025,6 +11233,7 @@ function createNextCommand(deps) {
           workflowRequestId: requestId,
           walletName: wallet2.walletName,
           nextCommand: nextCommand2,
+          productEntrySummary: productEntrySummary2,
           agentProfile: workflowAgentProfile,
           agentFollowup: agentFollowup2,
           summary: buildTopLevelWorkflowSummary(result, nextCommand2),
@@ -11041,10 +11250,10 @@ function createNextCommand(deps) {
     if (!config) {
       const recommendedCommands2 = {
         setup: buildSetupCommand(),
-        afterSetup: buildTopLevelNextRecommendedCommand2(),
+        afterSetup: buildTopLevelNextRecommendedCommand2(void 0, walletName),
         inspectDefaults: buildDefaultsRecommendedCommand()
       };
-      const recommendedPaths2 = buildSetupRecommendedPaths("<url>", paymasterMode);
+      const recommendedPaths2 = buildSetupRecommendedPaths("<url>", paymasterMode, walletName);
       const onboardingSummary2 = buildOnboardingSummary({
         stage: "setup",
         localOnly: true,
@@ -11056,6 +11265,10 @@ function createNextCommand(deps) {
           "This scope is local-only and does not require live RPC reads."
         ]
       });
+      const productEntrySummary2 = buildProductEntrySummary({
+        stage: "setup",
+        nextAction: recommendedCommands2.setup
+      });
       printResult(
         topLevelNextLines("setup", [
           ["status", "No local config found"],
@@ -11065,12 +11278,13 @@ function createNextCommand(deps) {
           ["next", recommendedCommands2.setup],
           ["after setup", recommendedCommands2.afterSetup],
           ["inspect defaults", recommendedCommands2.inspectDefaults]
-        ], onboardingSummary2),
+        ], onboardingSummary2, productEntrySummary2),
         {
           ok: true,
           scope: "setup",
           status: "action-required",
           nextCommand: recommendedCommands2.setup,
+          productEntrySummary: productEntrySummary2,
           onboardingSummary: onboardingSummary2,
           recommendedPaths: recommendedPaths2,
           agentProfile,
@@ -11084,15 +11298,19 @@ function createNextCommand(deps) {
     if (!wallet) {
       const recommendedCommands2 = {
         createWallet: appendPaymasterMode2(
-          buildWalletCreateRecommendedCommand(),
+          buildWalletCreateRecommendedCommand(void 0, walletName),
           paymasterMode
         ),
         relayInspect: buildRelayInspectRecommendedCommand(),
         createWalletRemote: buildWalletCreateRemoteRecommendedCommand(
           "<url>",
+          paymasterMode,
+          walletName
+        ),
+        afterApproval: appendPaymasterMode2(
+          buildTopLevelNextRecommendedCommand2(void 0, walletName),
           paymasterMode
         ),
-        afterApproval: appendPaymasterMode2(buildTopLevelNextRecommendedCommand2(), paymasterMode),
         inspectDefaults: buildDefaultsRecommendedCommand()
       };
       const recommendedPaths2 = buildWalletBootstrapRecommendedPaths(
@@ -11113,6 +11331,10 @@ function createNextCommand(deps) {
           "Use the remote approval fallback only when the browser is not colocated with this terminal."
         ]
       });
+      const productEntrySummary2 = buildProductEntrySummary({
+        stage: "wallet-bootstrap",
+        nextAction: recommendedCommands2.createWallet
+      });
       printResult(
         topLevelNextLines("wallet-bootstrap", [
           ["status", `Wallet not found: ${walletName}`],
@@ -11126,13 +11348,14 @@ function createNextCommand(deps) {
           ["remote fallback", recommendedCommands2.createWalletRemote],
           ["after approval", recommendedCommands2.afterApproval],
           ["inspect defaults", recommendedCommands2.inspectDefaults]
-        ], onboardingSummary2),
+        ], onboardingSummary2, productEntrySummary2),
         {
           ok: true,
           scope: "wallet-bootstrap",
           walletName,
           config,
           nextCommand: recommendedCommands2.createWallet,
+          productEntrySummary: productEntrySummary2,
           onboardingSummary: onboardingSummary2,
           recommendedPaths: recommendedPaths2,
           agentProfile,
@@ -11216,11 +11439,14 @@ function createNextCommand(deps) {
       reapprove: buildWalletReapproveRecommendedCommand(wallet.walletName),
       relayInspect: buildRelayInspectRecommendedCommand(),
       reapproveRemote: buildWalletReapproveRemoteRecommendedCommand(wallet.walletName),
-      afterRecovery: appendPaymasterMode2(buildTopLevelNextRecommendedCommand2(), paymasterMode)
+      afterRecovery: appendPaymasterMode2(
+        buildTopLevelNextRecommendedCommand2(void 0, wallet.walletName),
+        paymasterMode
+      )
     } : !inspection.localExecutionKeyStored ? {
       attachSigner: buildWalletSignerAttachRecommendedCommand(wallet.walletName),
       afterRecovery: appendPaymasterMode2(
-        buildTopLevelNextRecommendedCommand2(),
+        buildTopLevelNextRecommendedCommand2(void 0, wallet.walletName),
         paymasterMode
       )
     } : {};
@@ -11242,7 +11468,13 @@ function createNextCommand(deps) {
       currentSurface: "next",
       recommendedNow: summary.status === "ready",
       walletName: wallet.walletName,
-      chain: wallet.chain
+      chain: wallet.chain,
+      recommendedJourneyId: summary.status === "ready" ? "send-value-now" : null
+    });
+    const productEntrySummary = buildProductEntrySummary({
+      stage: onboardingSummary.stage,
+      nextAction: nextCommand,
+      suiteAvailable: summary.status === "ready"
     });
     printResult(
       topLevelNextLines("wallet", [
@@ -11263,11 +11495,12 @@ function createNextCommand(deps) {
         ...mergedRecommendedCommands.inspectPaymasterToken ? [["inspect paymaster token", mergedRecommendedCommands.inspectPaymasterToken]] : [],
         ["inspect token", mergedRecommendedCommands.inspectToken],
         ["inspect defaults", mergedRecommendedCommands.inspectDefaults]
-      ], onboardingSummary),
+      ], onboardingSummary, productEntrySummary),
       {
         ok: true,
         scope: "wallet",
         walletName: wallet.walletName,
+        productEntrySummary,
         onboardingSummary,
         recommendedPaths,
         agentProfile,
@@ -11299,10 +11532,18 @@ function buildDoctorHelpText() {
     "  zk-agent doctor --wallet main",
     "  zk-agent doctor --wallet main --relay-url https://relay.example.com",
     "",
+    "  What `doctor` answers right now:",
+    "    bootstrap: local config or wallet bootstrap is still missing",
+    "    recover: local approval or signer state still needs repair",
+    "    operate: local readiness is clear, so return to `zk-agent next` for the live path",
+    "    suite: once readiness is clear, the broader packaged post-flagship surface is available too",
+    "",
     "Default behavior:",
     "  Inspects saved config, local wallet approval metadata, local signer state,",
     "  and the shortest next command without requiring live RPC reads.",
     "  Run this before guessing whether the blocker is setup, wallet approval, or local signer state.",
+    "  When doctor shows local readiness is clear and the question is broader than one next step:",
+    "    zk-agent suite",
     "",
     "Remote-browser variant:",
     "  Pass --relay-url when you want the remote approval fallback commands",
@@ -11328,25 +11569,25 @@ function summarizeLocalWalletState(wallet) {
     signerSource: wallet.localExecutionAuthority?.source || (wallet.sessionPayload?.sessionPrivateKey ? "legacy-session-payload" : null)
   };
 }
-function buildSetupRecommendedCommands() {
+function buildSetupRecommendedCommands(walletName) {
   return {
     setup: "zk-agent setup",
-    next: buildTopLevelNextRecommendedCommand(),
+    next: buildTopLevelNextRecommendedCommand(void 0, void 0, walletName),
     inspectDefaults: buildDefaultsRecommendedCommand()
   };
 }
 function buildWalletBootstrapRecommendedCommands(walletName, relayUrl) {
   return {
-    next: buildTopLevelNextRecommendedCommand(),
+    next: buildTopLevelNextRecommendedCommand(void 0, void 0, walletName),
     inspectDefaults: buildDefaultsRecommendedCommand(),
-    createWallet: buildWalletCreateRecommendedCommand(),
+    createWallet: buildWalletCreateRecommendedCommand(void 0, walletName),
     relayInspect: buildRelayInspectRecommendedCommand(relayUrl),
     createWalletRemote: buildWalletCreateRemoteRecommendedCommand(relayUrl, void 0, walletName)
   };
 }
 function buildWalletRecoveryRecommendedCommands(wallet, relayUrl) {
   const shared = {
-    next: buildTopLevelNextRecommendedCommand(),
+    next: buildTopLevelNextRecommendedCommand(void 0, void 0, wallet.walletName),
     walletStatus: buildWalletStatusRecommendedCommand(wallet.walletName),
     walletNext: buildWalletNextRecommendedCommand(wallet.walletName),
     signerShow: buildWalletSignerShowRecommendedCommand(wallet.walletName),
@@ -11367,7 +11608,8 @@ function buildWalletRecoveryRecommendedCommands(wallet, relayUrl) {
 }
 function buildWalletReadyRecommendedCommands(wallet) {
   return {
-    next: buildTopLevelNextRecommendedCommand(),
+    next: buildTopLevelNextRecommendedCommand(void 0, void 0, wallet.walletName),
+    suite: buildSuiteRecommendedCommand(wallet.walletName, wallet.chain),
     walletStatus: buildWalletStatusRecommendedCommand(wallet.walletName),
     walletNext: buildWalletNextRecommendedCommand(wallet.walletName),
     workflowPay: buildWorkflowPayRecommendedCommand(wallet.walletName),
@@ -11376,7 +11618,7 @@ function buildWalletReadyRecommendedCommands(wallet) {
 }
 function buildDoctorResult(options) {
   if (!options.config) {
-    const recommendedCommands2 = buildSetupRecommendedCommands();
+    const recommendedCommands2 = buildSetupRecommendedCommands(options.walletName);
     const onboardingSummary2 = buildOnboardingSummary({
       stage: "setup",
       localOnly: true,
@@ -11391,10 +11633,16 @@ function buildDoctorResult(options) {
         "Doctor is local-only by default and does not require live RPC reads."
       ]
     });
+    const productEntrySummary2 = buildProductEntrySummary({
+      currentSurface: "doctor",
+      stage: "setup",
+      nextAction: recommendedCommands2.setup
+    });
     return {
       scope: "setup",
       nextAction: recommendedCommands2.setup,
-      recommendedPaths: buildSetupRecommendedPaths(options.relayUrl),
+      recommendedPaths: buildSetupRecommendedPaths(options.relayUrl, void 0, options.walletName),
+      productEntrySummary: productEntrySummary2,
       onboardingSummary: onboardingSummary2,
       summary: {
         stage: "setup",
@@ -11432,10 +11680,16 @@ function buildDoctorResult(options) {
         "Use the remote relay path only when the browser is not colocated with this terminal."
       ]
     });
+    const productEntrySummary2 = buildProductEntrySummary({
+      currentSurface: "doctor",
+      stage: "wallet-bootstrap",
+      nextAction: recommendedCommands2.createWallet
+    });
     return {
       scope: "wallet-bootstrap",
       nextAction: recommendedCommands2.createWallet,
       recommendedPaths: buildWalletBootstrapRecommendedPaths(options.relayUrl, void 0, options.walletName),
+      productEntrySummary: productEntrySummary2,
       onboardingSummary: onboardingSummary2,
       summary: {
         stage: "wallet-bootstrap",
@@ -11475,6 +11729,11 @@ function buildDoctorResult(options) {
         "Use the remote reapproval path only when the browser cannot return directly to this terminal."
       ]
     });
+    const productEntrySummary2 = buildProductEntrySummary({
+      currentSurface: "doctor",
+      stage: "wallet-recovery",
+      nextAction: recommendedCommands2.reapprove
+    });
     return {
       scope: "wallet-recovery",
       nextAction: recommendedCommands2.reapprove,
@@ -11482,6 +11741,7 @@ function buildDoctorResult(options) {
         options.wallet.walletName,
         options.relayUrl
       ),
+      productEntrySummary: productEntrySummary2,
       onboardingSummary: onboardingSummary2,
       summary: {
         stage: "wallet-recovery",
@@ -11522,10 +11782,16 @@ function buildDoctorResult(options) {
         "Doctor is local-only: it confirms stored signer state, not live chain deployment or gas balance."
       ]
     });
+    const productEntrySummary2 = buildProductEntrySummary({
+      currentSurface: "doctor",
+      stage: "wallet-recovery",
+      nextAction: attachSigner
+    });
     return {
       scope: "wallet-recovery",
       nextAction: attachSigner,
       recommendedPaths: buildSignerRecoveryRecommendedPaths(options.wallet.walletName),
+      productEntrySummary: productEntrySummary2,
       onboardingSummary: onboardingSummary2,
       summary: {
         stage: "wallet-recovery",
@@ -11561,13 +11827,29 @@ function buildDoctorResult(options) {
       "Run zk-agent next for the current shortest live path; doctor does not confirm RPC reachability, deployment state, or funding."
     ]
   });
+  const productEntrySummary = buildProductEntrySummary({
+    currentSurface: "doctor",
+    stage: "wallet-ready",
+    nextAction: recommendedCommands.next,
+    suiteAvailable: true,
+    nextSurface: "next"
+  });
+  const suiteHandoffSummary = buildSuiteHandoffSummary({
+    currentSurface: "doctor",
+    recommendedNow: true,
+    walletName: options.wallet.walletName,
+    chain: options.wallet.chain,
+    recommendedJourneyId: "send-value-now"
+  });
   return {
     scope: "wallet-ready",
     nextAction: recommendedCommands.next,
     recommendedPaths: {
       local: [recommendedCommands.next]
     },
+    productEntrySummary,
     onboardingSummary,
+    suiteHandoffSummary,
     summary: {
       stage: "wallet-ready",
       configExists: true,
@@ -11589,6 +11871,7 @@ function buildDoctorLines(input) {
   const lines = [
     ["scope", input.scope],
     ...onboardingSummaryLines(input.onboardingSummary),
+    ...productEntrySummaryLines(input.productEntrySummary),
     ["config", input.config ? "present" : "missing"]
   ];
   if (input.config) {
@@ -11625,6 +11908,9 @@ function buildDoctorLines(input) {
   }
   lines.push(["next", input.nextAction]);
   lines.push(...recommendedPathLines(input.recommendedPaths));
+  if (input.suiteHandoffSummary) {
+    lines.push(...suiteHandoffLines(input.suiteHandoffSummary));
+  }
   if (input.recommendedCommands.createWallet) {
     lines.push(["create wallet (local)", input.recommendedCommands.createWallet]);
   }
@@ -11637,6 +11923,9 @@ function buildDoctorLines(input) {
   if (input.recommendedCommands.workflowPay) {
     lines.push(["workflow pay", input.recommendedCommands.workflowPay]);
   }
+  if (input.recommendedCommands.suite) {
+    lines.push(["suite command", input.recommendedCommands.suite]);
+  }
   if (input.recommendedCommands.relayInspect) {
     lines.push(["relay inspect", input.recommendedCommands.relayInspect]);
   }
@@ -11679,7 +11968,9 @@ function createDoctorCommand() {
           config,
           wallet,
           onboardingSummary: result.onboardingSummary,
+          productEntrySummary: result.productEntrySummary,
           summary: result.summary,
+          suiteHandoffSummary: "suiteHandoffSummary" in result ? result.suiteHandoffSummary : void 0,
           recommendedPaths: result.recommendedPaths,
           recommendedCommands: result.recommendedCommands,
           nextAction: result.nextAction
@@ -11700,8 +11991,10 @@ function createDoctorCommand() {
           exists: false
         },
         wallet,
+        productEntrySummary: result.productEntrySummary,
         onboardingSummary: result.onboardingSummary,
         summary: result.summary,
+        ..."suiteHandoffSummary" in result ? { suiteHandoffSummary: result.suiteHandoffSummary } : {},
         agentProfile,
         agentFollowup,
         nextAction: result.nextAction,
@@ -11805,7 +12098,11 @@ function createAgentCommand() {
     "after",
     [
       "",
-      "  Agent identity path:",
+      "  Agent profile surface:",
+      "    Use this layer only when you want explicit local operator identity metadata on top of the wallet path.",
+      "    Wallet approval and workflow execution still work without a saved local agent profile.",
+      "",
+      "  Basic local identity path:",
       "    zk-agent agent status",
       '    zk-agent agent set --name "SED Operator" --wallet main',
       "    zk-agent agent show",
@@ -11814,12 +12111,9 @@ function createAgentCommand() {
       "    zk-agent agent export",
       "    zk-agent agent import --payload @agent-profile.json --overwrite",
       "",
-      "  Remove the saved local profile:",
+      "  Clear the saved local profile:",
       "    zk-agent agent clear",
       "",
-      "  This profile is optional. Wallet approval and workflow execution still work",
-      "  without a saved local agent profile.",
-      "",
       "Examples:",
       "  zk-agent agent status",
       '  zk-agent agent set --name "SED Operator" --wallet main',
@@ -12597,8 +12891,615 @@ function createDefaultsCommand() {
   });
 }
 
-// src/commands/resolve-token.ts
+// src/commands/payment.ts
+import { randomBytes as randomBytes5 } from "node:crypto";
 import { Command as Command7 } from "commander";
+
+// ../agent-pay/src/execution-plan.ts
+function buildPaymentExecutionPlan(record) {
+  return {
+    action: record.asset.kind === "native" ? "native-transfer" : "erc20-transfer",
+    surface: record.executionPreference.surface,
+    walletId: record.walletId,
+    walletName: record.walletName,
+    chain: record.chain,
+    chainId: record.chainId,
+    paymasterMode: record.executionPreference.paymasterMode,
+    payeeAddress: record.payee.address,
+    asset: record.asset
+  };
+}
+
+// ../agent-pay/src/payment-request.ts
+import { randomBytes as randomBytes4 } from "node:crypto";
+var PAYMENT_REQUEST_STATUS_TRANSITIONS = {
+  draft: ["draft", "ready", "cancelled"],
+  ready: ["draft", "ready", "paid", "cancelled"],
+  paid: ["paid"],
+  cancelled: ["cancelled"]
+};
+function nowIso2() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function createPaymentHistoryEventId() {
+  return `payevt-${randomBytes4(4).toString("hex")}`;
+}
+function normalizeOptionalString4(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : void 0;
+}
+function normalizeMetadata2(metadata) {
+  if (!metadata) return {};
+  const normalized = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    const normalizedKey = key.trim();
+    const normalizedValue = value.trim();
+    if (!normalizedKey || !normalizedValue) continue;
+    normalized[normalizedKey] = normalizedValue;
+  }
+  return normalized;
+}
+function normalizePaymentAsset(asset) {
+  const amount = asset.amount.trim();
+  if (!amount) {
+    throw new AgentError("PAYMENT_AMOUNT_REQUIRED", "Payment amount is required.");
+  }
+  if (asset.kind === "native") {
+    return {
+      kind: "native",
+      amount,
+      symbol: normalizeOptionalString4(asset.symbol)
+    };
+  }
+  const tokenAddress = asset.tokenAddress?.trim();
+  if (!tokenAddress) {
+    throw new AgentError(
+      "PAYMENT_TOKEN_REQUIRED",
+      "ERC-20 payment requests require a token address."
+    );
+  }
+  if (!Number.isInteger(asset.decimals) || Number(asset.decimals) < 0) {
+    throw new AgentError(
+      "PAYMENT_TOKEN_DECIMALS_REQUIRED",
+      "ERC-20 payment requests require non-negative token decimals."
+    );
+  }
+  return {
+    kind: "erc20",
+    amount,
+    tokenAddress,
+    decimals: Number(asset.decimals),
+    symbol: normalizeOptionalString4(asset.symbol)
+  };
+}
+function inferExecutionSurface(asset) {
+  return asset.kind === "native" ? "workflow-pay" : "send-token";
+}
+function createPaymentHistoryEvent(input) {
+  return {
+    eventId: createPaymentHistoryEventId(),
+    type: input.type,
+    at: input.at,
+    status: input.status,
+    previousStatus: input.previousStatus,
+    txHash: normalizeOptionalString4(input.txHash),
+    note: normalizeOptionalString4(input.note)
+  };
+}
+function buildLegacyPaymentHistory(record) {
+  return [
+    {
+      eventId: `payevt-${record.requestId}-legacy-created`,
+      type: "created",
+      at: record.createdAt,
+      status: record.settlement.status,
+      txHash: record.settlement.txHash,
+      note: record.settlement.note
+    }
+  ];
+}
+function migratePaymentRequestRecord(record) {
+  return {
+    ...record,
+    history: Array.isArray(record.history) && record.history.length > 0 ? record.history.map((event) => ({
+      ...event,
+      txHash: normalizeOptionalString4(event.txHash),
+      note: normalizeOptionalString4(event.note)
+    })) : buildLegacyPaymentHistory(record)
+  };
+}
+function createPaymentRequestRecord(input) {
+  const timestamp = nowIso2();
+  const payeeAddress = input.payeeAddress.trim();
+  if (!payeeAddress) {
+    throw new AgentError("PAYMENT_PAYEE_REQUIRED", "Payment payee address is required.");
+  }
+  const asset = normalizePaymentAsset(input.asset);
+  const status = input.status ?? "ready";
+  return {
+    format: "zk-agent-payment-request",
+    version: 1,
+    requestId: input.requestId.trim(),
+    walletId: input.walletId.trim(),
+    walletName: input.walletName.trim(),
+    walletAddress: input.walletAddress.trim(),
+    chain: input.chain.trim(),
+    chainId: input.chainId,
+    payer: {
+      walletId: input.walletId.trim(),
+      walletName: input.walletName.trim(),
+      walletAddress: input.walletAddress.trim(),
+      name: normalizeOptionalString4(input.payerName)
+    },
+    payee: {
+      address: payeeAddress,
+      name: normalizeOptionalString4(input.payeeName)
+    },
+    asset,
+    description: normalizeOptionalString4(input.description),
+    memo: normalizeOptionalString4(input.memo),
+    metadata: normalizeMetadata2(input.metadata),
+    executionPreference: {
+      surface: inferExecutionSurface(asset),
+      paymasterMode: input.paymasterMode ?? "none"
+    },
+    settlement: {
+      status
+    },
+    history: [
+      createPaymentHistoryEvent({
+        type: "created",
+        at: timestamp,
+        status
+      })
+    ],
+    createdAt: timestamp,
+    updatedAt: timestamp
+  };
+}
+function applyPaymentRequestStatusUpdate(record, input) {
+  const nextStatus = input.status;
+  const allowedTransitions = PAYMENT_REQUEST_STATUS_TRANSITIONS[record.settlement.status];
+  if (!allowedTransitions.includes(nextStatus)) {
+    throw new AgentError(
+      "PAYMENT_STATUS_TRANSITION_INVALID",
+      `Cannot move payment request ${record.requestId} from ${record.settlement.status} to ${nextStatus}.`,
+      {
+        currentStatus: record.settlement.status,
+        nextStatus,
+        allowedTransitions
+      }
+    );
+  }
+  const timestamp = nowIso2();
+  const nextTxHash = normalizeOptionalString4(input.txHash);
+  const nextNote = normalizeOptionalString4(input.note);
+  return {
+    ...record,
+    updatedAt: timestamp,
+    settlement: {
+      status: nextStatus,
+      paidAt: nextStatus === "paid" ? timestamp : record.settlement.paidAt,
+      cancelledAt: nextStatus === "cancelled" ? timestamp : record.settlement.cancelledAt,
+      txHash: nextTxHash ?? record.settlement.txHash,
+      note: nextNote ?? record.settlement.note
+    },
+    history: [
+      ...record.history,
+      createPaymentHistoryEvent({
+        type: "status-updated",
+        at: timestamp,
+        status: nextStatus,
+        previousStatus: record.settlement.status,
+        txHash: nextTxHash,
+        note: nextNote
+      })
+    ]
+  };
+}
+
+// ../agent-pay/src/storage.ts
+var PAYMENT_REQUEST_COLLECTION = "payments";
+async function savePaymentRequest(record) {
+  await saveEncryptedStorageRecord(
+    PAYMENT_REQUEST_COLLECTION,
+    record.requestId,
+    migratePaymentRequestRecord(record)
+  );
+}
+async function loadPaymentRequest(requestId) {
+  const record = await loadEncryptedStorageRecord(
+    PAYMENT_REQUEST_COLLECTION,
+    requestId
+  );
+  return record ? migratePaymentRequestRecord(record) : null;
+}
+async function listPaymentRequestIds() {
+  return listEncryptedStorageRecordIds(PAYMENT_REQUEST_COLLECTION);
+}
+async function deletePaymentRequest(requestId) {
+  return deleteEncryptedStorageRecord(PAYMENT_REQUEST_COLLECTION, requestId);
+}
+async function renamePaymentRequestWalletReferences(options) {
+  const currentName = options.previousWalletName.trim();
+  const targetName = options.nextWalletName.trim();
+  const walletId = options.walletId?.trim();
+  if (!currentName) throw new Error("Current wallet name is required.");
+  if (!targetName) throw new Error("New wallet name is required.");
+  if (currentName === targetName) return [];
+  const updatedRequestIds = [];
+  for (const requestId of await listPaymentRequestIds()) {
+    const paymentRequest = await loadPaymentRequest(requestId);
+    if (!paymentRequest) continue;
+    const matchesWallet = walletId && paymentRequest.walletId ? paymentRequest.walletId === walletId : paymentRequest.walletName === currentName;
+    if (!matchesWallet) continue;
+    if (walletId) {
+      paymentRequest.walletId = walletId;
+      paymentRequest.payer.walletId = walletId;
+    }
+    paymentRequest.walletName = targetName;
+    paymentRequest.payer.walletName = targetName;
+    await savePaymentRequest(paymentRequest);
+    updatedRequestIds.push(requestId);
+  }
+  return updatedRequestIds;
+}
+
+// ../agent-pay/src/service.ts
+async function requirePaymentRequest(requestId) {
+  const record = await loadPaymentRequest(requestId);
+  if (!record) {
+    throw new AgentError(
+      "PAYMENT_REQUEST_NOT_FOUND",
+      `Payment request not found: ${requestId}`
+    );
+  }
+  return record;
+}
+async function createStoredPaymentRequest(input) {
+  const paymentRequest = createPaymentRequestRecord(input);
+  await savePaymentRequest(paymentRequest);
+  return {
+    paymentRequest,
+    executionPlan: buildPaymentExecutionPlan(paymentRequest)
+  };
+}
+async function getStoredPaymentRequest(requestId) {
+  const paymentRequest = await requirePaymentRequest(requestId);
+  return {
+    paymentRequest,
+    executionPlan: buildPaymentExecutionPlan(paymentRequest)
+  };
+}
+async function listStoredPaymentRequests(input = {}) {
+  const requestIds = await listPaymentRequestIds();
+  const requests = [];
+  for (const requestId of requestIds) {
+    const record = await loadPaymentRequest(requestId);
+    if (!record) continue;
+    if (input.walletName && record.walletName !== input.walletName) continue;
+    if (input.status && record.settlement.status !== input.status) continue;
+    requests.push(record);
+  }
+  return requests.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+}
+async function updateStoredPaymentRequestStatus(input) {
+  const paymentRequest = await requirePaymentRequest(input.requestId);
+  const updated = applyPaymentRequestStatusUpdate(paymentRequest, input);
+  await savePaymentRequest(updated);
+  return {
+    paymentRequest: updated,
+    executionPlan: buildPaymentExecutionPlan(updated)
+  };
+}
+async function removeStoredPaymentRequest(requestId) {
+  return deletePaymentRequest(requestId);
+}
+
+// src/commands/payment.ts
+function parseMetadataEntries2(entries) {
+  const metadata = {};
+  for (const entry of entries) {
+    const separatorIndex = entry.indexOf("=");
+    if (separatorIndex <= 0 || separatorIndex === entry.length - 1) {
+      throw new AgentError(
+        "PAYMENT_METADATA_INVALID",
+        `Invalid metadata entry: ${entry}. Use key=value.`
+      );
+    }
+    const key = entry.slice(0, separatorIndex).trim();
+    const value = entry.slice(separatorIndex + 1).trim();
+    if (!key || !value) {
+      throw new AgentError(
+        "PAYMENT_METADATA_INVALID",
+        `Invalid metadata entry: ${entry}. Use key=value.`
+      );
+    }
+    metadata[key] = value;
+  }
+  return metadata;
+}
+function resolvePaymentStatus(value) {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized) return "ready";
+  if (normalized === "draft" || normalized === "ready" || normalized === "paid" || normalized === "cancelled") {
+    return normalized;
+  }
+  throw new AgentError(
+    "PAYMENT_STATUS_INVALID",
+    `Unsupported payment status: ${value}. Use draft, ready, paid, or cancelled.`
+  );
+}
+function resolvePaymasterMode2(value) {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized) return void 0;
+  if (normalized === "none" || normalized === "sponsored" || normalized === "approval-based") {
+    return normalized;
+  }
+  throw new AgentError(
+    "PAYMENT_PAYMASTER_MODE_INVALID",
+    `Unsupported paymaster mode: ${value}. Use none, sponsored, or approval-based.`
+  );
+}
+function buildPaymentRequestId(value) {
+  const trimmed = value?.trim();
+  if (trimmed) return trimmed;
+  return `payreq-${randomBytes5(4).toString("hex")}`;
+}
+function formatPaymentAsset(record) {
+  const symbol = record.asset.kind === "native" ? record.asset.symbol || "native" : record.asset.symbol || record.asset.tokenAddress || "erc20";
+  return `${record.asset.amount} ${symbol}`;
+}
+function buildPaymentExecuteCommand(plan) {
+  if (plan.asset.kind === "native") {
+    return buildWorkflowPayRecommendedCommand(
+      plan.walletName,
+      plan.paymasterMode
+    ).replace("--to <address>", `--to ${plan.payeeAddress}`).replace("--amount <amount>", `--amount ${plan.asset.amount}`);
+  }
+  return buildSendTokenRecommendedCommand({
+    walletName: plan.walletName,
+    to: plan.payeeAddress,
+    amount: plan.asset.amount,
+    tokenAddress: plan.asset.tokenAddress,
+    symbol: plan.asset.symbol,
+    decimals: plan.asset.decimals,
+    paymasterMode: plan.paymasterMode
+  });
+}
+function buildPaymentRecommendedCommands(record, executionPlan) {
+  return {
+    list: buildPaymentListRecommendedCommand(),
+    show: buildPaymentShowRecommendedCommand(record.requestId),
+    execute: buildPaymentExecuteCommand(executionPlan),
+    ...record.settlement.status === "draft" ? {
+      markReady: buildPaymentSetStatusRecommendedCommand(record.requestId, "ready"),
+      cancel: buildPaymentSetStatusRecommendedCommand(record.requestId, "cancelled")
+    } : {},
+    ...record.settlement.status === "ready" ? {
+      markDraft: buildPaymentSetStatusRecommendedCommand(record.requestId, "draft"),
+      markPaid: buildPaymentSetStatusRecommendedCommand(
+        record.requestId,
+        "paid",
+        "<tx-hash>"
+      ),
+      cancel: buildPaymentSetStatusRecommendedCommand(record.requestId, "cancelled")
+    } : {},
+    remove: buildPaymentRemoveRecommendedCommand(record.requestId)
+  };
+}
+function paymentRequestLines(record, executionPlan) {
+  const lines = [
+    ["request", record.requestId],
+    ["status", record.settlement.status],
+    ["wallet", record.walletName],
+    ["chain", `${record.chain} (${record.chainId})`],
+    ["payer", `${record.payer.name || record.payer.walletName} ${record.payer.walletAddress}`],
+    ["payee", `${record.payee.name || "payee"} ${record.payee.address}`],
+    ["asset", formatPaymentAsset(record)],
+    ["execution surface", record.executionPreference.surface],
+    ["paymaster mode", record.executionPreference.paymasterMode],
+    ["execute", buildPaymentExecuteCommand(executionPlan)],
+    ["show", buildPaymentShowRecommendedCommand(record.requestId)],
+    ["remove", buildPaymentRemoveRecommendedCommand(record.requestId)]
+  ];
+  if (record.description) lines.splice(7, 0, ["description", record.description]);
+  if (record.memo) lines.splice(record.description ? 8 : 7, 0, ["memo", record.memo]);
+  if (record.settlement.txHash) lines.push(["txHash", record.settlement.txHash]);
+  if (record.settlement.note) lines.push(["note", record.settlement.note]);
+  if (record.settlement.paidAt) lines.push(["paid at", record.settlement.paidAt]);
+  if (record.settlement.cancelledAt) lines.push(["cancelled at", record.settlement.cancelledAt]);
+  lines.push(["history events", String(record.history.length)]);
+  lines.push(["metadata keys", String(Object.keys(record.metadata).length)]);
+  return lines;
+}
+function buildPaymentExecutionPlanJson(plan) {
+  return {
+    ...plan,
+    command: buildPaymentExecuteCommand(plan)
+  };
+}
+function buildPaymentListSummary(record) {
+  return `${record.requestId} ${record.settlement.status} ${formatPaymentAsset(record)} -> ${record.payee.address} (${record.walletName})`;
+}
+function createPaymentCommand() {
+  const payment = new Command7("payment").description(
+    "Manage local-first Agent Pay request records separately from the execution-layer workflow and send commands"
+  );
+  payment.addHelpText(
+    "after",
+    [
+      "",
+      "  Payment request surface:",
+      "    Use this layer to capture payer/payee intent and local settlement state before or after execution.",
+      "    `workflow pay` and `send-token` still execute the transfer; `payment` stores the request record and status lifecycle.",
+      "",
+      "  First platform path:",
+      "    zk-agent payment create --wallet main --to <address> --amount <amount>",
+      "    zk-agent payment show --request-id <id>",
+      "    zk-agent payment set-status --request-id <id> --status paid --tx-hash <tx-hash>",
+      "",
+      "  ERC-20 request path:",
+      "    zk-agent payment create --wallet main --to <address> --amount <amount> --symbol USDC",
+      "",
+      "  Stored request management:",
+      "    zk-agent payment list",
+      "    zk-agent payment remove --request-id <id>"
+    ].join("\n")
+  );
+  payment.command("create").description("Create a local payment request record for native value or an ERC-20 transfer").option("--wallet <name>", "Stored payer wallet name", "main").requiredOption("--to <address>", "Payee address").requiredOption("--amount <value>", "Amount in human-readable units").option("--token <address>", "ERC-20 token contract address").option("--symbol <symbol>", "ERC-20 token symbol for registry-backed resolution").option("--decimals <value>", "ERC-20 token decimals when registry metadata is unavailable").option("--payee-name <name>", "Optional payee display name").option("--payer-name <name>", "Optional payer display name").option("--description <text>", "Short payment description").option("--memo <text>", "Optional memo or invoice reference").option("--metadata <key=value>", "Additional payment metadata", collectRepeatedString2, []).option("--paymaster-mode <mode>", "Optional execution preference: none, sponsored, or approval-based").option("--status <status>", "Initial local payment status: draft, ready, paid, or cancelled").option("--request-id <id>", "Optional explicit payment request id").action(async (options) => {
+    const wallet = await loadWalletSession(options.wallet);
+    if (!wallet) {
+      throw new AgentError("PAYMENT_WALLET_NOT_FOUND", `Wallet not found: ${options.wallet}`);
+    }
+    if (!wallet.walletId) {
+      throw new AgentError(
+        "WALLET_ID_MISSING",
+        `Wallet ${wallet.walletName} is missing a stable walletId. Re-save or reapprove the wallet session before creating a payment request.`
+      );
+    }
+    const paymasterMode = resolvePaymasterMode2(options.paymasterMode) ?? wallet.paymasterMode ?? "none";
+    const status = resolvePaymentStatus(options.status);
+    const metadata = parseMetadataEntries2(options.metadata);
+    const requestId = buildPaymentRequestId(options.requestId);
+    const hasTokenInput = Boolean(options.token?.trim() || options.symbol?.trim());
+    const asset = hasTokenInput ? await resolveRequiredTokenInput({
+      tokenAddress: options.token,
+      symbol: options.symbol,
+      decimals: options.decimals,
+      chain: wallet.chain,
+      tokenOptionLabel: "--token",
+      symbolOptionLabel: "--symbol",
+      decimalsOptionLabel: "--decimals"
+    }).then((token) => ({
+      kind: "erc20",
+      amount: options.amount,
+      tokenAddress: token.address,
+      decimals: token.decimals,
+      symbol: token.symbol
+    })) : {
+      kind: "native",
+      amount: options.amount
+    };
+    const result = await createStoredPaymentRequest({
+      requestId,
+      walletId: wallet.walletId,
+      walletName: wallet.walletName,
+      walletAddress: wallet.walletAddress,
+      chain: wallet.chain,
+      chainId: wallet.chainId,
+      payerName: options.payerName,
+      payeeAddress: options.to,
+      payeeName: options.payeeName,
+      asset,
+      description: options.description,
+      memo: options.memo,
+      metadata,
+      paymasterMode,
+      status
+    });
+    printResult(paymentRequestLines(result.paymentRequest, result.executionPlan), {
+      ok: true,
+      paymentRequest: result.paymentRequest,
+      executionPlan: buildPaymentExecutionPlanJson(result.executionPlan),
+      recommendedCommands: buildPaymentRecommendedCommands(
+        result.paymentRequest,
+        result.executionPlan
+      )
+    });
+  });
+  payment.command("list").description("List stored local payment request records").option("--wallet <name>", "Optional payer wallet filter").option("--status <status>", "Optional status filter: draft, ready, paid, or cancelled").action(async (options) => {
+    const statusFilter = options.status ? resolvePaymentStatus(options.status) : void 0;
+    const requests = await listStoredPaymentRequests({
+      walletName: options.wallet,
+      status: statusFilter
+    });
+    printResult(
+      requests.length > 0 ? requests.flatMap((record) => [
+        ["payment", buildPaymentListSummary(record)],
+        ["show", buildPaymentShowRecommendedCommand(record.requestId)]
+      ]) : [
+        ["status", "No stored payment requests"],
+        ["next", "zk-agent payment create --wallet main --to <address> --amount <amount>"]
+      ],
+      {
+        ok: true,
+        count: requests.length,
+        filters: {
+          walletName: options.wallet || null,
+          status: statusFilter || null
+        },
+        requests,
+        recommendedCommands: requests.length === 0 ? {
+          create: "zk-agent payment create --wallet main --to <address> --amount <amount>"
+        } : {
+          list: buildPaymentListRecommendedCommand()
+        }
+      }
+    );
+  });
+  payment.command("show").description("Show one stored payment request record").requiredOption("--request-id <id>", "Stored payment request id").action(async (options) => {
+    const result = await getStoredPaymentRequest(options.requestId);
+    printResult(paymentRequestLines(result.paymentRequest, result.executionPlan), {
+      ok: true,
+      paymentRequest: result.paymentRequest,
+      executionPlan: buildPaymentExecutionPlanJson(result.executionPlan),
+      recommendedCommands: buildPaymentRecommendedCommands(
+        result.paymentRequest,
+        result.executionPlan
+      )
+    });
+  });
+  payment.command("set-status").description("Update the local settlement status of one stored payment request").requiredOption("--request-id <id>", "Stored payment request id").requiredOption("--status <status>", "Next status: draft, ready, paid, or cancelled").option("--tx-hash <hash>", "Optional settlement transaction hash").option("--note <text>", "Optional operator note for the status update").action(async (options) => {
+    const result = await updateStoredPaymentRequestStatus({
+      requestId: options.requestId,
+      status: resolvePaymentStatus(options.status),
+      txHash: options.txHash,
+      note: options.note
+    });
+    printResult(paymentRequestLines(result.paymentRequest, result.executionPlan), {
+      ok: true,
+      paymentRequest: result.paymentRequest,
+      executionPlan: buildPaymentExecutionPlanJson(result.executionPlan),
+      recommendedCommands: buildPaymentRecommendedCommands(
+        result.paymentRequest,
+        result.executionPlan
+      )
+    });
+  });
+  payment.command("remove").description("Delete one stored payment request record").requiredOption("--request-id <id>", "Stored payment request id").action(async (options) => {
+    const removed = await removeStoredPaymentRequest(options.requestId);
+    if (!removed) {
+      throw new AgentError(
+        "PAYMENT_REQUEST_NOT_FOUND",
+        `Payment request not found: ${options.requestId}`
+      );
+    }
+    printResult(
+      [
+        ["status", "Payment request removed"],
+        ["request", options.requestId],
+        ["next", buildPaymentListRecommendedCommand()]
+      ],
+      {
+        ok: true,
+        requestId: options.requestId,
+        removed: true,
+        recommendedCommands: {
+          list: buildPaymentListRecommendedCommand(),
+          create: "zk-agent payment create --wallet main --to <address> --amount <amount>"
+        }
+      }
+    );
+  });
+  return payment;
+}
+function collectRepeatedString2(value, previous) {
+  return [...previous, value];
+}
+
+// src/commands/resolve-token.ts
+import { Command as Command8 } from "commander";
 function resolveResolveTokenCommandDeps(deps) {
   return {
     loadWallet: deps?.loadWallet ?? (async (walletName) => {
@@ -12656,7 +13557,7 @@ function buildResolveTokenDiscoverySummary(result) {
 }
 function createResolveTokenCommand(deps) {
   const resolvedDeps = resolveResolveTokenCommandDeps(deps);
-  return new Command7("resolve-token").description("Resolve a token symbol or address against the configured local-first token registry").addHelpText(
+  return new Command8("resolve-token").description("Resolve a token symbol or address against the configured local-first token registry").addHelpText(
     "after",
     [
       "",
@@ -12790,33 +13691,67 @@ function normalizeSource(value) {
 }
 
 // src/commands/suite.ts
-import { Command as Command8 } from "commander";
+import { Command as Command9 } from "commander";
 
 // src/lib/operator-suite.ts
 function buildOperatorSuitePayload(options = {}) {
   const walletName = options.walletName?.trim() || "main";
   const chain = options.chain?.trim() || "zksync-sepolia";
+  const includeOnboarding = options.includeOnboarding === true;
   const flagshipCommand = buildWorkflowPayRecommendedCommand(walletName);
   const inspectDefaults = buildDefaultsRecommendedCommand();
+  const workflowSurfaceCommand = "zk-agent workflow --help";
+  const relaySurfaceCommand = "zk-agent relay --help";
   const discoveryCommand = buildAssetsRecommendedCommand(walletName);
   const paymasterCommand = buildWorkflowPayRecommendedCommand(walletName, "approval-based");
   const fundingCommand = buildWorkflowFundRecommendedCommand(walletName);
+  const nextCommand = buildTopLevelNextRecommendedCommand(void 0, void 0, walletName);
+  const hostedRelayInspectCommand = buildRelayInspectRecommendedCommand("<url>");
+  const hostedCreateWalletCommand = buildWalletCreateRemoteRecommendedCommand(
+    "<url>",
+    void 0,
+    walletName
+  );
+  const hostedReapproveCommand = buildWalletReapproveRemoteRecommendedCommand(
+    walletName,
+    "<url>"
+  );
+  const suiteCommand = buildSuiteRecommendedCommand(walletName, chain, {
+    includeOnboarding
+  });
+  const preflightPaths = includeOnboarding ? buildSetupRecommendedPaths("<url>", void 0, walletName) : void 0;
+  const preflight = preflightPaths ? {
+    id: "first-run-preflight",
+    title: "First-Run Preflight",
+    goal: "Start from a fresh install, write local defaults, and bootstrap a writable wallet session before using the packaged operator surface.",
+    useWhen: "Use this when the machine is new, the wallet is not ready yet, or you want the full operator map before choosing local-first versus remote-browser approval.",
+    diagnosticCommand: walletName === "main" ? "zk-agent doctor" : `zk-agent doctor --wallet ${walletName}`,
+    localPath: preflightPaths.local,
+    remoteBrowserPath: preflightPaths.remoteBrowser,
+    afterWalletReady: buildSuiteRecommendedCommand(walletName, chain)
+  } : void 0;
   const flagship = {
+    category: "operate",
+    surface: "workflow",
     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", buildWalletStatusRecommendedCommand(walletName), inspectDefaults],
+    surfaceCommand: workflowSurfaceCommand,
+    supportingCommands: [nextCommand, buildWalletStatusRecommendedCommand(walletName), inspectDefaults],
     skillPath: "skills/zk-aa/SKILL.md"
   };
   const slices = [
     {
+      category: "discover",
+      surface: "discovery",
       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,
+      surfaceCommand: inspectDefaults,
       supportingCommands: [
         inspectDefaults,
         `zk-agent tokens --chain ${chain}`,
@@ -12826,11 +13761,14 @@ function buildOperatorSuitePayload(options = {}) {
       smokeCommand: `pnpm smoke:discovery -- --wallet ${walletName}`
     },
     {
+      category: "pay",
+      surface: "workflow",
       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,
+      surfaceCommand: workflowSurfaceCommand,
       supportingCommands: [
         inspectDefaults,
         buildPaymasterFeeTokensRecommendedCommand(chain),
@@ -12840,11 +13778,14 @@ function buildOperatorSuitePayload(options = {}) {
       smokeCommand: `pnpm smoke:paymaster-success -- --wallet ${walletName}`
     },
     {
+      category: "fund",
+      surface: "workflow",
       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,
+      surfaceCommand: workflowSurfaceCommand,
       supportingCommands: [
         buildWorkflowFundRunRecommendedCommand(walletName),
         `zk-agent fund --wallet ${walletName} --amount <amount>`,
@@ -12852,48 +13793,197 @@ function buildOperatorSuitePayload(options = {}) {
       ],
       skillPath: "skills/zk-funding/SKILL.md",
       smokeCommand: `pnpm smoke:funding-readiness -- --wallet ${walletName}`
+    },
+    {
+      category: "recover",
+      surface: "relay",
+      id: "hosted-approval-recovery",
+      title: "Hosted Approval Recovery",
+      goal: "Validate a hosted relay URL and switch to the remote approval path when the browser is not colocated or a writable session must be reapproved remotely.",
+      useWhen: "Use this when local callback is not viable, the browser is remote, or an expired writable session must be recovered through the single-host hosted relay baseline.",
+      primaryCommand: hostedRelayInspectCommand,
+      surfaceCommand: relaySurfaceCommand,
+      supportingCommands: [
+        hostedCreateWalletCommand,
+        hostedReapproveCommand,
+        `pnpm smoke:hosted-operated-baseline -- --wallet ${walletName} --relay-url <url> --reapprove --prompt-code --plan`
+      ],
+      skillPath: "skills/zk-relay/SKILL.md"
     }
   ];
+  const surfaces = [
+    {
+      surface: "workflow",
+      title: "Workflow Surface",
+      useWhen: "Use this when the question is already about execution, approval-based pay, or funding recovery after suite has identified the right slice.",
+      command: workflowSurfaceCommand,
+      categoryIds: ["operate", "pay", "fund"],
+      entryIds: [flagship.id, "paymaster-readiness", "funding-readiness"]
+    },
+    {
+      surface: "discovery",
+      title: "Discovery Surface",
+      useWhen: "Use this when the question is about assets, defaults, token ownership, or symbol-first inspection after suite has identified the discovery slice.",
+      command: inspectDefaults,
+      categoryIds: ["discover"],
+      entryIds: ["discovery-defaults"]
+    },
+    {
+      surface: "relay",
+      title: "Relay Surface",
+      useWhen: "Use this when the browser is remote or hosted approval readiness must be checked before wallet recovery can continue.",
+      command: relaySurfaceCommand,
+      categoryIds: ["recover"],
+      entryIds: ["hosted-approval-recovery"]
+    }
+  ];
+  const journeys = [
+    {
+      id: "send-value-now",
+      title: "Send Value Now",
+      operatorQuestion: "I already have a ready wallet and want the shortest path to send native value now.",
+      useWhen: "Use this when the wallet is already ready and the operator wants the flagship zkSync-native pay path first.",
+      startCommand: flagshipCommand,
+      surface: "workflow",
+      categoryIds: ["operate"],
+      entryIds: [flagship.id]
+    },
+    {
+      id: "inspect-before-acting",
+      title: "Inspect Before Acting",
+      operatorQuestion: "I need to inspect assets, defaults, or token metadata before I choose a tokenized action.",
+      useWhen: "Use this when asset visibility, defaults, or symbol-first token inspection is still the real blocker.",
+      startCommand: discoveryCommand,
+      surface: "discovery",
+      categoryIds: ["discover"],
+      entryIds: ["discovery-defaults"]
+    },
+    {
+      id: "unstick-a-write",
+      title: "Unstick a Write",
+      operatorQuestion: "The write path is blocked on fee-token/default state or funding, and I need the shortest recovery route.",
+      useWhen: "Use this when approval-based pay or a workflow write is blocked and the CLI needs to recover paymaster or funding readiness.",
+      startCommand: paymasterCommand,
+      surface: "workflow",
+      categoryIds: ["pay", "fund"],
+      entryIds: ["paymaster-readiness", "funding-readiness"]
+    },
+    {
+      id: "recover-remote-approval",
+      title: "Recover Remote Approval",
+      operatorQuestion: "The browser is remote or local callback is not viable, so approval must move to the hosted relay path.",
+      useWhen: "Use this when a writable session must be recovered through the single-host hosted relay baseline.",
+      startCommand: hostedRelayInspectCommand,
+      surface: "relay",
+      categoryIds: ["recover"],
+      entryIds: ["hosted-approval-recovery"]
+    }
+  ];
+  const recommendedJourney = {
+    id: journeys[0].id,
+    title: journeys[0].title,
+    startCommand: journeys[0].startCommand,
+    surface: journeys[0].surface,
+    useWhen: journeys[0].useWhen
+  };
   return {
     ok: true,
     summary: {
       suiteId: "zk-agent-operator-suite",
+      catalogView: "operator-catalog",
       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.",
+      useWhen: "Use suite after wallet readiness when you want one packaged surface for flagship pay plus the current post-flagship discovery, paymaster, funding, and hosted recovery slices.",
+      entryModes: ["local-first", "hosted-recovery"],
+      startHereJourneyId: recommendedJourney.id,
+      journeyOrder: journeys.map((entry) => entry.id),
+      surfaceOrder: ["workflow", "discovery", "relay"],
+      categoryOrder: [flagship.category, ...slices.map((entry) => entry.category)],
       flagshipId: flagship.id,
       postFlagshipSliceIds: slices.map((entry) => entry.id),
       recommendedOrder: [flagship.id, ...slices.map((entry) => entry.id)],
       nextAction: flagship.primaryCommand
     },
+    ...preflight ? { preflight } : {},
+    recommendedJourney,
+    journeys,
+    surfaces,
     flagship,
     slices,
     recommendedCommands: {
-      suite: buildSuiteRecommendedCommand(walletName, chain),
+      suite: suiteCommand,
       flagship: flagshipCommand,
+      workflowSurface: workflowSurfaceCommand,
+      discoverySurface: inspectDefaults,
+      relaySurface: relaySurfaceCommand,
       discovery: discoveryCommand,
       paymaster: paymasterCommand,
       funding: fundingCommand,
+      hostedApproval: hostedRelayInspectCommand,
       inspectDefaults
     }
   };
 }
 function operatorSuiteLines(payload) {
+  const preflightLines = payload.preflight ? [
+    ["preflight", formatRecommendedPath(payload.preflight.localPath)],
+    ...payload.preflight.remoteBrowserPath?.length ? [["preflight (remote-browser)", formatRecommendedPath(payload.preflight.remoteBrowserPath)]] : [],
+    ["preflight when", payload.preflight.useWhen],
+    ["preflight diagnose", payload.preflight.diagnosticCommand],
+    ["preflight handoff", payload.preflight.afterWalletReady]
+  ] : [];
+  const journeyLines = payload.journeys.flatMap((journey) => [
+    [`journey ${journey.id}`, journey.startCommand],
+    [`journey ${journey.id} surface`, journey.surface],
+    [`journey ${journey.id} categories`, journey.categoryIds.join(" -> ")],
+    [`journey ${journey.id} entries`, journey.entryIds.join(" -> ")],
+    [`journey ${journey.id} when`, journey.useWhen]
+  ]);
   const sliceLines = payload.slices.flatMap((entry) => [
+    [`${entry.title.toLowerCase()} category`, entry.category],
+    [`${entry.title.toLowerCase()} surface`, entry.surface],
+    [`${entry.title.toLowerCase()} surface command`, entry.surfaceCommand],
     [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]] : []
   ]);
+  const surfaceLines = payload.surfaces.flatMap((surface) => [
+    [`${surface.surface} surface`, surface.command],
+    [`${surface.surface} surface categories`, surface.categoryIds.join(" -> ")],
+    [`${surface.surface} surface entries`, surface.entryIds.join(" -> ")],
+    [`${surface.surface} surface when`, surface.useWhen]
+  ]);
   return [
     ["suite", payload.summary.suiteId],
+    ["catalog", payload.summary.catalogView],
     ["wallet", payload.summary.walletName],
     ["chain", payload.summary.chain],
     ["stage", payload.summary.stage],
     ["use when", payload.summary.useWhen],
+    ["entry modes", payload.summary.entryModes.join(" -> ")],
+    ["start here journey", payload.summary.startHereJourneyId],
+    ["start here", payload.recommendedJourney.startCommand],
+    ["start here surface", payload.recommendedJourney.surface],
+    ["start here when", payload.recommendedJourney.useWhen],
+    ["journey order", payload.summary.journeyOrder.join(" -> ")],
+    ["surface order", payload.summary.surfaceOrder.join(" -> ")],
+    ["category order", payload.summary.categoryOrder.join(" -> ")],
+    ...preflightLines,
+    ...journeyLines,
+    ...surfaceLines,
     ["recommended order", payload.summary.recommendedOrder.join(" -> ")],
-    [payload.flagship.title.toLowerCase(), formatRecommendedPath([payload.flagship.primaryCommand, "zk-agent next"])],
+    [`${payload.flagship.title.toLowerCase()} category`, payload.flagship.category],
+    [`${payload.flagship.title.toLowerCase()} surface`, payload.flagship.surface],
+    [`${payload.flagship.title.toLowerCase()} surface command`, payload.flagship.surfaceCommand],
+    [
+      payload.flagship.title.toLowerCase(),
+      formatRecommendedPath([
+        payload.flagship.primaryCommand,
+        buildTopLevelNextRecommendedCommand(void 0, void 0, payload.summary.walletName)
+      ])
+    ],
     [`${payload.flagship.title.toLowerCase()} when`, payload.flagship.useWhen],
     [`${payload.flagship.title.toLowerCase()} skill`, payload.flagship.skillPath],
     ...sliceLines,
@@ -12903,35 +13993,70 @@ function operatorSuiteLines(payload) {
 
 // src/commands/suite.ts
 function createSuiteCommand() {
-  return new Command8("suite").description("Show the flagship and post-flagship zkSync-native operator suite").option("--wallet <name>", "Wallet name used in example commands", "main").option("--chain <chain>", "Chain key used in example commands", "zksync-sepolia").addHelpText(
+  return new Command9("suite").description("Show the flagship and post-flagship zkSync-native operator suite").option("--wallet <name>", "Wallet name used in example commands", "main").option("--chain <chain>", "Chain key used in example commands", "zksync-sepolia").option("--include-onboarding", "Include the first-run preflight and wallet-bootstrap map", false).addHelpText(
     "after",
     [
       "",
       "  Use `suite` after wallet readiness when you want one packaged surface",
       "  for flagship pay plus the current post-flagship slices.",
       "",
+      "  What `suite` answers right now:",
+      "    operate: send native value through the flagship workflow path",
+      "    discover: inspect owned assets and defaults before tokenized actions",
+      "    pay: stay on the approval-based paymaster path with exact fee-token follow-up",
+      "    fund: recover from gas/funding blockers without guessing the route",
+      "    recover: switch to hosted relay approval when the browser is remote",
+      "",
+      "  Most common operator journeys:",
+      "    send value now: go straight to the flagship pay path",
+      "    inspect before acting: open assets/defaults/token inspection first",
+      "    unstick a write: recover paymaster/funding readiness on the workflow path",
+      "    recover remote approval: move approval to the hosted relay path",
+      "",
+      "  If you only need one default starting point inside suite:",
+      "    send value now",
+      "",
+      "  Where `suite` hands you off next:",
+      "    workflow: flagship pay, approval-based pay, and funding recovery",
+      "    discovery: assets, defaults, and token inspection",
+      "    relay: hosted approval recovery and relay readiness",
+      "",
+      "  For the full first-run to post-flagship map:",
+      "    zk-agent suite --include-onboarding",
+      "",
       "  Recommended order inside the suite:",
       "    zk-agent workflow pay --wallet main --to <address> --amount <amount>",
       "    zk-agent assets --wallet main",
       "    zk-agent workflow pay --wallet main --to <address> --amount <amount> --paymaster-mode approval-based",
       "    zk-agent workflow fund --wallet main",
+      "    zk-agent relay inspect --relay-url <url>",
       "",
       "  Pass `--wallet` or `--chain` to retarget the entire suite contract.",
+      "  Pass `--include-onboarding` when you want setup, doctor, and wallet bootstrap",
+      "  guidance in the same packaged readout.",
       "",
-      "  In JSON mode, `summary.useWhen`, `summary.recommendedOrder`, and each",
-      "  entry `useWhen` field explain when to stay on one slice instead of guessing."
+      "  In JSON mode, `summary.catalogView`, `summary.entryModes`,",
+      "  `summary.startHereJourneyId`, `summary.journeyOrder`,",
+      "  `summary.surfaceOrder`, top-level `recommendedJourney`, top-level",
+      "  `journeys[]`, top-level `surfaces[]`, `summary.categoryOrder`,",
+      "  `summary.recommendedOrder`, optional `preflight`, and each entry",
+      "  `category` + `surface` + `surfaceCommand` + `useWhen` field explain",
+      "  which slice to choose and which deeper surface owns it next.",
+      "  `recommendedCommands.workflowSurface|discoverySurface|relaySurface`",
+      "  expose the direct deeper-surface entry commands."
     ].join("\n")
   ).action((options) => {
     const payload = buildOperatorSuitePayload({
       walletName: options.wallet,
-      chain: options.chain
+      chain: options.chain,
+      includeOnboarding: options.includeOnboarding
     });
     printResult(operatorSuiteLines(payload), payload);
   });
 }
 
 // src/commands/tokens.ts
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 var provider2 = new ZkSyncWalletProvider();
 function resolveTokensCommandDeps(deps) {
   return {
@@ -13061,7 +14186,7 @@ function buildTokenDiscoverySummary(result) {
 }
 function createTokensCommand(deps) {
   const resolvedDeps = resolveTokensCommandDeps(deps);
-  return new Command9("tokens").description("List discoverable tokens from the configured local-first token registry, or inspect the owned ERC-20 registry subset for one wallet").addHelpText(
+  return new Command10("tokens").description("List discoverable tokens from the configured local-first token registry, or inspect the owned ERC-20 registry subset for one wallet").addHelpText(
     "after",
     [
       "",
@@ -13266,7 +14391,7 @@ function normalizeRole2(value) {
 }
 
 // src/commands/relay.ts
-import { Command as Command10 } from "commander";
+import { Command as Command11 } from "commander";
 
 // src/lib/relay.ts
 import { createServer } from "node:http";
@@ -14131,14 +15256,18 @@ function buildRelayInspectPayload(relayUrl, rawHealth) {
   };
 }
 function createRelayCommand() {
-  const relay = new Command10("relay").description(
+  const relay = new Command11("relay").description(
     "Serve and inspect the single-host connector relay baseline for hosted approval"
   );
   relay.addHelpText(
     "after",
     [
       "",
-      "  Hosted remote-approval path:",
+      "  Relay surface:",
+      "    Use this layer only when approval must happen through a publicly reachable hosted path.",
+      "    Keep `wallet create|reapprove --await-local` as the default baseline when the browser and terminal are colocated.",
+      "",
+      "  Hosted remote-approval path today:",
       "    zk-agent relay serve --public-origin https://relay.example.com",
       "    zk-agent relay inspect --relay-url <url>",
       "    zk-agent wallet create --relay-url <url> --wait-relay --prompt-code",
@@ -14150,9 +15279,6 @@ function createRelayCommand() {
       "    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.",
-      "",
       "  Use `relay inspect` before sending operators to a hosted share link so",
       "  the public origin, connector UI, and hosted-readiness contract are visible."
     ].join("\n")
@@ -14392,7 +15518,7 @@ function createRelayCommand() {
 // src/commands/wallet.ts
 import { createServer as createServer2 } from "node:http";
 import { createInterface } from "node:readline/promises";
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 
 // ../account-profiles/src/profiles.ts
 import fs8 from "node:fs";
@@ -14977,8 +16103,9 @@ function stripSensitiveWalletRecord(wallet) {
   };
 }
 function sanitizeWalletRecord(wallet) {
+  const { walletId: _walletId, ...rest } = stripSensitiveWalletRecord(wallet);
   return {
-    ...stripSensitiveWalletRecord(wallet),
+    ...rest,
     sessionPayload: sanitizeSessionPayload(wallet.sessionPayload)
   };
 }
@@ -17059,62 +18186,62 @@ async function printBuiltinSmartAccountProfiles() {
 }
 function createWalletCommand(deps) {
   const resolvedDeps = resolveWalletCommandDeps(deps);
-  const wallet = new Command11("wallet").description(
+  const wallet = new Command12("wallet").description(
     "Create, inspect, and recover local-first wallet sessions"
   );
-  const request = new Command11("request").description("Inspect and finalize pending wallet requests");
-  const signer = new Command11("signer").description(
+  const request = new Command12("request").description("Inspect and finalize pending wallet requests");
+  const signer = new Command12("signer").description(
     "Inspect and manage the stored local execution signer for a wallet"
   );
-  const smartAccount = new Command11("smart-account").description(
+  const smartAccount = new Command12("smart-account").description(
     "Predict and deploy zkSync smart-account contracts from a supplied artifact or built-in profile"
   );
-  const sedLite = new Command11("sed-lite").description(
+  const sedLite = new Command12("sed-lite").description(
     "Inspect and manage the SED modular smart-account profile"
   );
-  const nativeCapHook = new Command11("native-cap-hook").description(
+  const nativeCapHook = new Command12("native-cap-hook").description(
     "Inspect and manage the first SED Lite validation-hook policy: native per-transaction spend caps"
   );
-  const targetAllowlistHook = new Command11("target-allowlist-hook").description(
+  const targetAllowlistHook = new Command12("target-allowlist-hook").description(
     "Inspect and manage the SED Lite validation-hook policy that restricts transactions to an allowlisted target set"
   );
-  const selectorAllowlistHook = new Command11("selector-allowlist-hook").description(
+  const selectorAllowlistHook = new Command12("selector-allowlist-hook").description(
     "Inspect and manage the SED Lite validation-hook policy that restricts contract calls to allowlisted target and selector pairs"
   );
-  const dailySpendLimit = new Command11("daily-spend-limit").description(
+  const dailySpendLimit = new Command12("daily-spend-limit").description(
     "Read and update the native-token daily spend limit used by the built-in daily-spend-limit smart-account profile"
   );
-  const paymaster = new Command11("paymaster").description(
+  const paymaster = new Command12("paymaster").description(
     "Manage saved paymaster defaults for stored wallets"
   );
   wallet.addHelpText(
     "after",
     [
       "",
-      "Local-first wallet path:",
-      "  Use this layer when the blocker is specifically about wallet approval or signer state.",
-      "  Otherwise start with `zk-agent next` or `zk-agent doctor`.",
+      "Wallet surface:",
+      "  Use this layer when the blocker is specifically wallet approval, signer state, or session recovery.",
+      "  If the CLI still needs to decide whether the problem is setup, wallet readiness, or workflow continuation, start with `zk-agent next` or `zk-agent doctor`.",
       "",
-      "  First bootstrap:",
+      "  First local-first bootstrap:",
       "    zk-agent wallet create --await-local",
       "    zk-agent next",
       "",
-      "  Restore approval metadata for an existing wallet:",
+      "  Repair an existing wallet session:",
       "    zk-agent wallet reapprove --name main --await-local",
       "    zk-agent next",
       "",
-      "  Attach a local signer when approval is still present:",
+      "  Repair signer-only local execution state:",
       "    zk-agent wallet signer attach --name main --private-key <hex>",
       "    zk-agent next",
       "",
-      "  Wallet-layer inspection:",
+      "  Wallet-scoped diagnosis:",
       "    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:",
+      "  Switch to the packaged catalog after wallet readiness:",
       "    zk-agent suite",
       "",
-      "  Hosted remote approval path:",
+      "  Hosted remote approval only when the browser is remote:",
       "    zk-agent relay inspect --relay-url <url>",
       "    zk-agent wallet create --relay-url <url> --wait-relay --prompt-code",
       "    zk-agent wallet reapprove --name main --relay-url <url> --wait-relay --prompt-code",
@@ -17592,6 +18719,13 @@ function createWalletCommand(deps) {
   wallet.command("list").description("List stored wallets").action(async () => printWalletList());
   wallet.command("rename").description("Rename a stored wallet and update any local pending requests that reference it").option("--name <name>", "Current wallet name", "main").requiredOption("--new-name <name>", "New wallet name").action(async (options) => {
     const result = await renameWalletSession(options.name, options.newName);
+    const updatedPaymentRequestIds = await renamePaymentRequestWalletReferences(
+      {
+        walletId: result.wallet.walletId,
+        previousWalletName: options.name,
+        nextWalletName: options.newName
+      }
+    );
     printResult(
       [
         ["status", "Wallet renamed"],
@@ -17599,6 +18733,7 @@ function createWalletCommand(deps) {
         ["to", result.wallet.walletName],
         ["address", result.wallet.walletAddress],
         ["requests updated", String(result.updatedRequestIds.length)],
+        ["payment requests updated", String(updatedPaymentRequestIds.length)],
         ["workflow checkpoints updated", String(result.updatedWorkflowRequestIds.length)],
         ...walletFollowUpLines(result.wallet)
       ],
@@ -17608,6 +18743,7 @@ function createWalletCommand(deps) {
         previousWalletName: options.name,
         wallet: sanitizeWalletRecord(result.wallet),
         updatedRequestIds: result.updatedRequestIds,
+        updatedPaymentRequestIds,
         updatedWorkflowRequestIds: result.updatedWorkflowRequestIds,
         recommendedCommands: buildWalletFollowUpRecommendedCommands(result.wallet)
       }
@@ -17713,7 +18849,8 @@ function createWalletCommand(deps) {
       currentSurface: "wallet",
       recommendedNow: summary.status === "ready",
       walletName: walletRecord.walletName,
-      chain: summary.chain
+      chain: summary.chain,
+      recommendedJourneyId: summary.status === "ready" ? "send-value-now" : null
     });
     printResult(
       [
@@ -17756,7 +18893,8 @@ function createWalletCommand(deps) {
       currentSurface: "wallet",
       recommendedNow: summary.status === "ready",
       walletName: walletRecord.walletName,
-      chain: summary.chain
+      chain: summary.chain,
+      recommendedJourneyId: summary.status === "ready" ? "send-value-now" : null
     });
     printResult(
       [
@@ -19731,8 +20869,8 @@ function createWalletCommand(deps) {
 }
 
 // src/commands/workflow.ts
-import { randomBytes as randomBytes4 } from "node:crypto";
-import { Command as Command12 } from "commander";
+import { randomBytes as randomBytes6 } from "node:crypto";
+import { Command as Command13 } from "commander";
 var defaultProvider2 = new ZkSyncWalletProvider();
 var defaultDefiProvider2 = new ZkSyncDefiProvider({
   walletWriter: defaultProvider2
@@ -19799,7 +20937,7 @@ function parseBooleanString(value, label) {
   throw new Error(`${label} must be true or false`);
 }
 function generateWorkflowRequestId() {
-  return randomBytes4(4).toString("hex");
+  return randomBytes6(4).toString("hex");
 }
 async function reserveWorkflowRequestId(requestId) {
   const explicit = requestId?.trim();
@@ -21438,25 +22576,26 @@ function assertWorkflowResumeReady(result) {
 function buildWorkflowHelpText() {
   return [
     "",
-    "  Flagship native pay path:",
+    "  Workflow surface:",
+    "    Use this layer when the question is already an explicit workflow, checkpoint, or execution state.",
+    "    If the CLI still needs to choose across setup, wallet readiness, or recovery, go back to `zk-agent next` or `zk-agent doctor`.",
+    "",
+    "  Fastest flagship pay path:",
     "    zk-agent workflow pay --wallet main --to <address> --amount <amount>",
     "",
-    "  Broader multi-intent guided path:",
+    "  Multi-intent guided path:",
     "    zk-agent workflow auto --wallet main --intent <intent> [goal flags] --create-checkpoint --execute-when-ready",
     "",
-    "  Checkpointed execution:",
+    "  Checkpoint lifecycle when you want explicit control:",
     "    zk-agent workflow start --wallet main --intent <intent> [goal flags]",
     "    zk-agent workflow status --request-id <id>",
     "    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:",
+    "  Funding-only recovery when execution is blocked on gas:",
     "    zk-agent workflow fund --wallet main --amount <amount> --execute",
     "",
-    "  Token/discovery recovery path:",
+    "  Discovery / token recovery before the workflow can continue:",
     "    zk-agent assets --wallet main",
     "    zk-agent tokens --wallet main --owned",
     "    zk-agent tokens --chain zksync-sepolia",
@@ -21467,6 +22606,9 @@ function buildWorkflowHelpText() {
     "    zk-agent resolve-token --chain zksync-sepolia --symbol <symbol> --role paymaster-fee-token",
     "    zk-agent defaults",
     "",
+    "  When the question becomes broader than one explicit workflow:",
+    "    zk-agent suite",
+    "",
     "  Lower-level one-shot escape hatch:",
     "    zk-agent workflow run --wallet main --intent <intent> [goal flags]"
   ].join("\n");
@@ -21501,7 +22643,7 @@ function applyWorkflowHelpCommandOrder(workflow) {
 }
 function createWorkflowCommand(deps) {
   const resolvedDeps = resolveWorkflowCommandDeps(deps);
-  const workflow = new Command12("workflow").description(
+  const workflow = new Command13("workflow").description(
     "Plan, persist, and execute higher-level wallet workflows"
   );
   workflow.addHelpText("after", buildWorkflowHelpText());
@@ -22187,6 +23329,23 @@ function buildDefaultOperatorPathHelpText() {
     "",
     "Operator suite beyond flagship pay:",
     "  zk-agent suite",
+    "  zk-agent suite --include-onboarding",
+    "",
+    "First local Agent Pay primitive:",
+    "  zk-agent payment create --wallet main --to <address> --amount <amount>",
+    "  zk-agent payment list",
+    "",
+    "Product routing by operator question:",
+    "  next  -> bootstrap | recover | operate | workflow",
+    "  suite -> operate | discover | pay | fund | recover",
+    "",
+    "Payment-first default path after wallet readiness:",
+    "  send native value now -> stay on approval-based pay when fee-token/default state matters -> recover funding only when blocked",
+    "  Default start inside suite: send value now",
+    "",
+    "Use `next` while the CLI still needs to choose across setup, wallet readiness, or stored workflow continuation.",
+    "Use `suite` once wallet readiness is no longer the blocker and you want the packaged post-flagship surface.",
+    "Use `zk-agent suite --include-onboarding` when you want one readout from first-run bootstrap through the packaged operator catalog.",
     "",
     "Validated first-run baseline:",
     "  setup defaults to zksync-sepolia and the local connector at http://localhost:4444",
@@ -22211,6 +23370,7 @@ var ROOT_HELP_COMMAND_ORDER = [
   "wallet",
   "workflow",
   "suite",
+  "payment",
   "assets",
   "balances",
   "fund",
@@ -22244,7 +23404,7 @@ function applyRootHelpCommandOrder(program) {
   program.commands = sortedCommands;
 }
 function createProgram() {
-  const program = new Command13().name("zk-agent").description(
+  const program = new Command14().name("zk-agent").description(
     "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";
@@ -22255,6 +23415,7 @@ function createProgram() {
   program.addCommand(createAgentCommand());
   program.addCommand(createDefaultsCommand());
   program.addCommand(createSuiteCommand());
+  program.addCommand(createPaymentCommand());
   program.addCommand(createTokensCommand());
   program.addCommand(createResolveTokenCommand());
   program.addCommand(createRelayCommand());