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

package/dist/index.js

@@ -7823,7 +7823,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 +7831,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}`;
@@ -10175,28 +10179,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 +10209,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 +10223,7 @@ function buildSignerRecoveryRecommendedPaths(walletName, paymasterMode) {
   return {
     local: [
       buildWalletSignerAttachRecommendedCommand(walletName),
-      buildTopLevelNextRecommendedCommand(void 0, paymasterMode)
+      buildTopLevelNextRecommendedCommand(void 0, paymasterMode, walletName)
     ]
   };
 }
@@ -10698,11 +10702,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 +10842,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 +10852,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 +10862,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 +10876,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 +11008,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 +11030,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 +11044,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 +11149,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 +11172,7 @@ function createNextCommand(deps) {
             ["funding txHash", result.fundingProgress.txHash],
             ["funding status", result.fundingProgress.status]
           ] : []
-        ]),
+        ], void 0, productEntrySummary2),
         {
           ok: true,
           scope: "workflow",
@@ -11025,6 +11180,7 @@ function createNextCommand(deps) {
           workflowRequestId: requestId,
           walletName: wallet2.walletName,
           nextCommand: nextCommand2,
+          productEntrySummary: productEntrySummary2,
           agentProfile: workflowAgentProfile,
           agentFollowup: agentFollowup2,
           summary: buildTopLevelWorkflowSummary(result, nextCommand2),
@@ -11041,10 +11197,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 +11212,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 +11225,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 +11245,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 +11278,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 +11295,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 +11386,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 +11415,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 +11442,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 +11479,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 +11516,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 +11555,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 +11565,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 +11580,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 +11627,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 +11676,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 +11688,7 @@ function buildDoctorResult(options) {
         options.wallet.walletName,
         options.relayUrl
       ),
+      productEntrySummary: productEntrySummary2,
       onboardingSummary: onboardingSummary2,
       summary: {
         stage: "wallet-recovery",
@@ -11522,10 +11729,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 +11774,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 +11818,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 +11855,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 +11870,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 +11915,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 +11938,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 +12045,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 +12058,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',
@@ -12796,27 +13037,61 @@ import { Command as Command8 } from "commander";
 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 +13101,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 +13118,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 +13133,184 @@ 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"]
     }
   ];
   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"],
+      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 } : {},
+    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(" -> ")],
+    ["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,28 +13320,59 @@ 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 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").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",
+      "",
+      "  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.journeyOrder`, `summary.surfaceOrder`, 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);
   });
@@ -14138,7 +14586,11 @@ function createRelayCommand() {
     "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 +14602,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")
@@ -17091,30 +17540,30 @@ function createWalletCommand(deps) {
     "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",
@@ -17713,7 +18162,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 +18206,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(
       [
@@ -21438,25 +21889,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 +21919,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");
@@ -22187,6 +22642,15 @@ function buildDefaultOperatorPathHelpText() {
     "",
     "Operator suite beyond flagship pay:",
     "  zk-agent suite",
+    "  zk-agent suite --include-onboarding",
+    "",
+    "Product routing by operator question:",
+    "  next  -> bootstrap | recover | operate | workflow",
+    "  suite -> operate | discover | pay | fund | recover",
+    "",
+    "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",