zk-agent-cli 0.1.0-beta.6 → 0.1.0-beta.8

package/dist/index.js

@@ -7722,6 +7722,10 @@ function formatHumanErrorMessage(error) {
   pushDetailLine(lines, "reason", details.reason);
   pushDetailLine(lines, "note", details.note);
   pushDetailLine(lines, "suggested action", details.suggestedAction);
+  pushDetailLine(lines, "status command", details.statusCommand);
+  pushDetailLine(lines, "approve command", details.approveCommand);
+  pushDetailLine(lines, "relay inspect command", details.relayInspectCommand);
+  pushDetailLine(lines, "reissue remote approval command", details.reissueRemoteApprovalCommand);
   pushDetailLine(lines, "validation domain", details.validationDomain);
   pushDetailLine(lines, "validation stage", details.validationStage);
   const validation = asRecord2(details.validation);
@@ -7758,6 +7762,18 @@ function buildTopLevelNextRecommendedCommand(requestId, paymasterMode) {
 function buildWalletCreateRecommendedCommand() {
   return "zk-agent wallet create --await-local";
 }
+function buildRelayInspectRecommendedCommand(relayUrl = "<url>") {
+  return `zk-agent relay inspect --relay-url ${relayUrl}`;
+}
+function buildWalletCreateRemoteRecommendedCommand(relayUrl = "<url>", paymasterMode, walletName = "main", accountKind = "smart-account") {
+  const command = [
+    "zk-agent wallet create",
+    walletName !== "main" ? `--name ${walletName}` : "",
+    accountKind !== "smart-account" ? `--account-kind ${accountKind}` : "",
+    `--relay-url ${relayUrl} --wait-relay --prompt-code`
+  ].filter(Boolean).join(" ");
+  return appendPaymasterMode(command, paymasterMode);
+}
 function buildWalletListRecommendedCommand() {
   return "zk-agent wallet list";
 }
@@ -7784,6 +7800,12 @@ function buildResolveTokenRecommendedCommand(chain, symbol, role, source) {
   const withRole = role ? `${command} --role ${role}` : command;
   return source ? `${withRole} --source ${source}` : withRole;
 }
+function buildPaymasterFeeTokensRecommendedCommand(chain) {
+  return buildTokensRecommendedCommand(chain, void 0, "paymaster-fee-token");
+}
+function buildPaymasterFeeTokenResolveRecommendedCommand(chain, symbol) {
+  return buildResolveTokenRecommendedCommand(chain, symbol, "paymaster-fee-token");
+}
 function buildDiscoveryRecommendedCommands(input) {
   return {
     inspectDefaults: buildDefaultsRecommendedCommand(),
@@ -7814,6 +7836,9 @@ function buildDiscoveryRecommendedCommands(input) {
 function buildWalletReapproveRecommendedCommand(walletName) {
   return `zk-agent wallet reapprove --name ${walletName} --await-local`;
 }
+function buildWalletReapproveRemoteRecommendedCommand(walletName, relayUrl = "<url>") {
+  return `zk-agent wallet reapprove --name ${walletName} --relay-url ${relayUrl} --wait-relay --prompt-code`;
+}
 function buildWalletNextRecommendedCommand(walletName) {
   return `zk-agent wallet next --name ${walletName}`;
 }
@@ -8507,9 +8532,15 @@ function workflowFollowupLines(recommendedCommands) {
   if (recommendedCommands.discoverOwnedTokens) {
     lines.push(["discover owned tokens", recommendedCommands.discoverOwnedTokens]);
   }
+  if (recommendedCommands.discoverPaymasterTokens) {
+    lines.push(["discover paymaster tokens", recommendedCommands.discoverPaymasterTokens]);
+  }
   if (recommendedCommands.discoverTokens) {
     lines.push(["discover tokens", recommendedCommands.discoverTokens]);
   }
+  if (recommendedCommands.inspectPaymasterToken) {
+    lines.push(["inspect paymaster token", recommendedCommands.inspectPaymasterToken]);
+  }
   if (recommendedCommands.inspectToken) {
     lines.push(["inspect token", recommendedCommands.inspectToken]);
   }
@@ -9214,7 +9245,25 @@ function createBalancesCommand(deps) {
 }
 function createAssetsCommand(deps) {
   const resolvedDeps = resolveBalancesCommandDeps(deps);
-  return new Command("assets").description("Fetch the preferred single-chain asset view with native balance plus registry-backed ERC-20 holdings").option("--wallet <name>", "Wallet name", "main").option("--chain <chain>", "Single chain override").action(async (options) => {
+  return new Command("assets").description("Fetch the preferred single-chain asset view with native balance plus registry-backed ERC-20 holdings").addHelpText(
+    "after",
+    [
+      "",
+      "Discovery asset path:",
+      "  Preferred single-chain asset entrypoint:",
+      "    zk-agent assets --wallet main",
+      "",
+      "  Narrower owned ERC-20 registry subset:",
+      "    zk-agent tokens --wallet main --owned",
+      "",
+      "  Symbol-first token lookup before a tokenized command:",
+      "    zk-agent tokens --chain zksync-sepolia --symbol USDC",
+      "    zk-agent resolve-token --chain zksync-sepolia --symbol USDC",
+      "",
+      "  For the machine-readable registry/default catalog:",
+      "    zk-agent defaults"
+    ].join("\n")
+  ).option("--wallet <name>", "Wallet name", "main").option("--chain <chain>", "Single chain override").action(async (options) => {
     const walletName = options.wallet;
     const wallet = await resolvedDeps.loadWallet(walletName);
     if (!wallet) throw new Error(`Wallet not found: ${walletName}`);
@@ -9912,11 +9961,35 @@ function createPlannedCommands() {
 
 // src/commands/setup.ts
 import { Command as Command2 } from "commander";
+function buildSetupHelpText() {
+  return [
+    "",
+    "What setup does:",
+    "  Writes the local default chain and connector URL used by the first-run path.",
+    "",
+    "After setup, stay on the canonical local-first path:",
+    "  zk-agent next",
+    "  zk-agent wallet create --await-local",
+    "  zk-agent next",
+    "",
+    "If the browser is not colocated with this terminal, switch at the wallet step:",
+    "  zk-agent relay inspect --relay-url <url>",
+    "  zk-agent wallet create --relay-url <url> --wait-relay --prompt-code",
+    "  zk-agent next",
+    "",
+    "Environment note:",
+    "  No custom .env is required for setup, next, or wallet request creation.",
+    "  Add RPC env vars later, before live reads or broadcasts."
+  ].join("\n");
+}
 function createInitCommand() {
-  return new Command2("init").alias("setup").description("Initialize local zk-agent configuration").option("--default-chain <chain>", "Default chain key", "zksync-era").option("--connector-url <url>", "Connector UI base URL", "http://localhost:4444").option("--force", "Overwrite an existing config", false).action(async (options) => {
+  return new Command2("init").alias("setup").description("Initialize local zk-agent configuration for the default operator path").addHelpText("after", buildSetupHelpText()).option("--default-chain <chain>", "Default chain key", "zksync-era").option("--connector-url <url>", "Connector UI base URL", "http://localhost:4444").option("--force", "Overwrite an existing config", false).action(async (options) => {
     const recommendedCommands = {
+      next: buildTopLevelNextRecommendedCommand(),
       inspectDefaults: buildDefaultsRecommendedCommand(),
       createWallet: buildWalletCreateRecommendedCommand(),
+      relayInspect: buildRelayInspectRecommendedCommand(),
+      createWalletRemote: buildWalletCreateRemoteRecommendedCommand(),
       afterWalletApproval: buildTopLevelNextRecommendedCommand()
     };
     const existing = await loadProjectConfig();
@@ -9926,8 +9999,11 @@ function createInitCommand() {
           ["status", "Config already exists. Re-run with --force to overwrite."],
           ["default chain", existing.defaultChain],
           ["connector", existing.connectorUrl],
+          ["next", recommendedCommands.next],
           ["inspect defaults", recommendedCommands.inspectDefaults],
-          ["create wallet", recommendedCommands.createWallet],
+          ["create wallet (local)", recommendedCommands.createWallet],
+          ["relay inspect", recommendedCommands.relayInspect],
+          ["create wallet (remote)", recommendedCommands.createWalletRemote],
           ["after approval", recommendedCommands.afterWalletApproval]
         ],
         {
@@ -9952,8 +10028,11 @@ function createInitCommand() {
         ["status", "Config saved"],
         ["default chain", config.defaultChain],
         ["connector", config.connectorUrl],
+        ["next", recommendedCommands.next],
         ["inspect defaults", recommendedCommands.inspectDefaults],
-        ["create wallet", recommendedCommands.createWallet],
+        ["create wallet (local)", recommendedCommands.createWallet],
+        ["relay inspect", recommendedCommands.relayInspect],
+        ["create wallet (remote)", recommendedCommands.createWalletRemote],
         ["after approval", recommendedCommands.afterWalletApproval]
       ],
       { ok: true, config, recommendedCommands }
@@ -10383,9 +10462,17 @@ function buildTopLevelWorkflowRecommendedCommands(input) {
       discoverOwnedTokens: buildOwnedTokensRecommendedCommand(input.walletName),
       discoverTokens: buildTokensRecommendedCommand(input.chain),
       inspectToken: buildResolveTokenRecommendedCommand(input.chain)
+    } : {},
+    ...input.paymasterMode === "approval-based" ? {
+      discoverPaymasterTokens: buildPaymasterFeeTokensRecommendedCommand(input.chain),
+      inspectPaymasterToken: buildPaymasterFeeTokenResolveRecommendedCommand(input.chain)
     } : {}
   };
 }
+function extractCheckpointPaymasterMode(checkpoint) {
+  if (!("paymaster" in checkpoint.goal)) return void 0;
+  return checkpoint.goal.paymaster?.mode;
+}
 function resolveNextCommandDeps(deps) {
   return {
     provider: deps?.provider ?? defaultProvider,
@@ -10409,7 +10496,15 @@ function buildNextHelpText() {
   return [
     "",
     "Use `next` as the product entrypoint:",
-    "  Fresh operator routing:",
+    "  Fresh local-first routing:",
+    "    zk-agent setup",
+    "    zk-agent next",
+    "    zk-agent wallet create --await-local",
+    "    zk-agent next",
+    "",
+    "  If the browser is remote, switch at the wallet step instead of waiting for a local callback:",
+    "    zk-agent relay inspect --relay-url <url>",
+    "    zk-agent wallet create --relay-url <url> --wait-relay --prompt-code",
     "    zk-agent next",
     "",
     "  Continue a stored workflow checkpoint:",
@@ -10418,6 +10513,9 @@ function buildNextHelpText() {
     "  Stay on the wallet layer only when you need wallet-specific remediation:",
     "    zk-agent wallet next --name main",
     "",
+    "  Switch to the hosted remote-approval path only when the browser is not colocated:",
+    "    zk-agent wallet --help",
+    "",
     "  Stay on the workflow layer only when you already have an explicit workflow or checkpoint:",
     "    zk-agent workflow next --request-id <id>"
   ].join("\n");
@@ -10464,7 +10562,8 @@ function createNextCommand(deps) {
         walletName: wallet2.walletName,
         nextAction: nextCommand2,
         chain: result.plan.chain,
-        intent: result.intent
+        intent: result.intent,
+        paymasterMode: extractCheckpointPaymasterMode(updatedCheckpoint)
       });
       const workflowAgentProfile = await loadAgentIdentitySummary(wallet2.walletName);
       const agentFollowup2 = buildAgentFollowup(workflowAgentProfile, {
@@ -10509,6 +10608,7 @@ function createNextCommand(deps) {
     if (!config) {
       const recommendedCommands2 = {
         setup: buildSetupCommand(),
+        afterSetup: buildTopLevelNextRecommendedCommand2(),
         inspectDefaults: buildDefaultsRecommendedCommand()
       };
       printResult(
@@ -10517,6 +10617,7 @@ function createNextCommand(deps) {
           ...agentProfileLines(agentProfile),
           ...agentFollowupLines(defaultAgentFollowup),
           ["next", recommendedCommands2.setup],
+          ["after setup", recommendedCommands2.afterSetup],
           ["inspect defaults", recommendedCommands2.inspectDefaults]
         ]),
         {
@@ -10538,6 +10639,11 @@ function createNextCommand(deps) {
           buildWalletCreateRecommendedCommand(),
           paymasterMode
         ),
+        relayInspect: buildRelayInspectRecommendedCommand(),
+        createWalletRemote: buildWalletCreateRemoteRecommendedCommand(
+          "<url>",
+          paymasterMode
+        ),
         afterApproval: appendPaymasterMode2(buildTopLevelNextRecommendedCommand2(), paymasterMode),
         inspectDefaults: buildDefaultsRecommendedCommand()
       };
@@ -10549,6 +10655,8 @@ function createNextCommand(deps) {
           ...agentProfileLines(agentProfile),
           ...agentFollowupLines(defaultAgentFollowup),
           ["next", recommendedCommands2.createWallet],
+          ["relay inspect", recommendedCommands2.relayInspect],
+          ["remote fallback", recommendedCommands2.createWalletRemote],
           ["after approval", recommendedCommands2.afterApproval],
           ["inspect defaults", recommendedCommands2.inspectDefaults]
         ]),
@@ -10602,6 +10710,10 @@ function createNextCommand(deps) {
       walletStatus: buildWalletStatusRecommendedCommand(wallet.walletName),
       discoverAssets: buildAssetsRecommendedCommand(wallet.walletName),
       discoverOwnedTokens: buildOwnedTokensRecommendedCommand(wallet.walletName),
+      ...paymasterMode === "approval-based" ? {
+        discoverPaymasterTokens: buildPaymasterFeeTokensRecommendedCommand(wallet.chain),
+        inspectPaymasterToken: buildPaymasterFeeTokenResolveRecommendedCommand(wallet.chain)
+      } : {},
       discoverTokens: buildTokensRecommendedCommand(wallet.chain),
       inspectToken: buildResolveTokenRecommendedCommand(wallet.chain),
       workflowPay,
@@ -10617,7 +10729,9 @@ function createNextCommand(deps) {
         ...summary.recommendedCommand ? [] : [["next", workflowPay]],
         ["discover assets", recommendedCommands.discoverAssets],
         ["discover owned tokens", recommendedCommands.discoverOwnedTokens],
+        ...recommendedCommands.discoverPaymasterTokens ? [["discover paymaster tokens", recommendedCommands.discoverPaymasterTokens]] : [],
         ["discover tokens", recommendedCommands.discoverTokens],
+        ...recommendedCommands.inspectPaymasterToken ? [["inspect paymaster token", recommendedCommands.inspectPaymasterToken]] : [],
         ["inspect token", recommendedCommands.inspectToken],
         ["inspect defaults", recommendedCommands.inspectDefaults]
       ]),
@@ -10734,6 +10848,21 @@ function createAgentCommand() {
   agent.addHelpText(
     "after",
     [
+      "",
+      "  Agent identity path:",
+      "    zk-agent agent status",
+      '    zk-agent agent set --name "SED Operator" --wallet main',
+      "    zk-agent agent show",
+      "",
+      "  Portable local profile management:",
+      "    zk-agent agent export",
+      "    zk-agent agent import --payload @agent-profile.json --overwrite",
+      "",
+      "  Remove 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",
@@ -11380,7 +11509,24 @@ function buildDefaultsLines(input) {
   return lines;
 }
 function createDefaultsCommand() {
-  return new Command5("defaults").description("Show the machine-readable registry of supported, validated, experimental, and manually configured defaults").action(async () => {
+  return new Command5("defaults").description("Show the machine-readable registry of supported, validated, experimental, and manually configured defaults").addHelpText(
+    "after",
+    [
+      "",
+      "Discovery defaults path:",
+      "  Use `defaults` as the machine-readable registry escape hatch for:",
+      "    - validated or fallback swap / bridge paths",
+      "    - tracked token roles and source order",
+      "    - paymaster defaults and supported modes",
+      "",
+      "  For wallet-scoped asset discovery, prefer:",
+      "    zk-agent assets --wallet main",
+      "",
+      "  For symbol-first token discovery, prefer:",
+      "    zk-agent tokens --chain zksync-sepolia",
+      "    zk-agent resolve-token --chain zksync-sepolia --symbol USDC"
+    ].join("\n")
+  ).action(async () => {
     const defaults = loadValidatedDefaults();
     const localTokenRegistry = listLocalTokenRegistryEntries();
     const tokenRegistrySources = describeDefaultTokenRegistrySources();
@@ -11440,7 +11586,27 @@ async function resolveActiveChain(options, deps) {
 }
 function createResolveTokenCommand(deps) {
   const resolvedDeps = resolveResolveTokenCommandDeps(deps);
-  return new Command6("resolve-token").description("Resolve a token symbol or address against the configured local-first token registry").option("--wallet <name>", "Optional stored wallet name to infer the active chain").option("--chain <chain>", "Chain key or chain id override").option("--symbol <symbol>", "Token symbol to resolve on the active chain").option("--address <address>", "Token address to inspect on the active chain").option(
+  return new Command6("resolve-token").description("Resolve a token symbol or address against the configured local-first token registry").addHelpText(
+    "after",
+    [
+      "",
+      "Resolve-token path:",
+      "  Symbol-first resolution on one active chain:",
+      "    zk-agent resolve-token --chain zksync-sepolia --symbol USDC",
+      "",
+      "  Use the stored wallet to infer the active chain:",
+      "    zk-agent resolve-token --wallet main --symbol USDC",
+      "",
+      "  Use broader chain discovery before resolution when you still need the candidate set:",
+      "    zk-agent tokens --chain zksync-sepolia",
+      "",
+      "  Use the wallet asset entrypoint when the real question is balances/holdings:",
+      "    zk-agent assets --wallet main",
+      "",
+      "  Use the registry/default catalog when you need tracked roles or source order:",
+      "    zk-agent defaults"
+    ].join("\n")
+  ).option("--wallet <name>", "Optional stored wallet name to infer the active chain").option("--chain <chain>", "Chain key or chain id override").option("--symbol <symbol>", "Token symbol to resolve on the active chain").option("--address <address>", "Token address to inspect on the active chain").option(
     "--role <role>",
     `Optional defaults-registry role filter: ${REGISTRY_TOKEN_ROLES.join(", ")}`
   ).option(
@@ -11643,7 +11809,29 @@ function ownedTokenSummaryLines2(summary) {
 }
 function createTokensCommand(deps) {
   const resolvedDeps = resolveTokensCommandDeps(deps);
-  return new Command7("tokens").description("List discoverable tokens from the configured local-first token registry, or inspect the owned ERC-20 registry subset for one wallet").option("--wallet <name>", "Optional stored wallet name to infer the active chain").option("--chain <chain>", "Chain key or chain id override").option("--symbol <symbol>", "Optional exact symbol filter").option(
+  return new Command7("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",
+    [
+      "",
+      "Discovery token path:",
+      "  Start with the preferred wallet asset view when you need balances plus tracked ERC-20 holdings:",
+      "    zk-agent assets --wallet main",
+      "",
+      "  Use the narrower owned ERC-20 registry subset when you only want held tokens:",
+      "    zk-agent tokens --wallet main --owned",
+      "",
+      "  Use chain-scoped discovery before choosing a token address:",
+      "    zk-agent tokens --chain zksync-sepolia",
+      "    zk-agent tokens --chain zksync-sepolia --symbol USDC",
+      "    zk-agent tokens --chain zksync-sepolia --role paymaster-fee-token",
+      "",
+      "  For one direct token-resolution check:",
+      "    zk-agent resolve-token --chain zksync-sepolia --symbol USDC",
+      "",
+      "  For the full defaults/registry catalog:",
+      "    zk-agent defaults"
+    ].join("\n")
+  ).option("--wallet <name>", "Optional stored wallet name to infer the active chain").option("--chain <chain>", "Chain key or chain id override").option("--symbol <symbol>", "Optional exact symbol filter").option(
     "--role <role>",
     `Optional defaults-registry role filter: ${REGISTRY_TOKEN_ROLES.join(", ")}`
   ).option(
@@ -11829,21 +12017,157 @@ import { Command as Command8 } from "commander";
 // src/lib/relay.ts
 import { createServer } from "node:http";
 import fs7 from "node:fs";
-import path6 from "node:path";
+import path7 from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
+
+// src/lib/http.ts
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile as readFile2, rm as rm2 } from "node:fs/promises";
+import os2 from "node:os";
+import path6 from "node:path";
+function isDnsResolutionFailure(error) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const cause = "cause" in error ? error.cause : void 0;
+  if (!cause || typeof cause !== "object") {
+    return false;
+  }
+  const code = "code" in cause ? cause.code : void 0;
+  return code === "ENOTFOUND" || code === "EAI_AGAIN";
+}
+function isHttpUrl(value) {
+  return value.startsWith("http://") || value.startsWith("https://");
+}
+function parseCurlHeaders(rawHeaders) {
+  const blocks = rawHeaders.replace(/\r\n/g, "\n").split(/\n{2,}/).map((block) => block.trim()).filter((block) => block.startsWith("HTTP/"));
+  const lastBlock = blocks.at(-1);
+  if (!lastBlock) {
+    throw new Error("curl fallback did not emit an HTTP response header block.");
+  }
+  const [statusLine, ...headerLines] = lastBlock.split("\n");
+  const status = Number.parseInt(statusLine.split(/\s+/)[1] || "", 10);
+  if (!Number.isInteger(status)) {
+    throw new Error(`curl fallback emitted an invalid status line: ${statusLine}`);
+  }
+  const headers = new Headers();
+  for (const line of headerLines) {
+    const separator = line.indexOf(":");
+    if (separator <= 0) continue;
+    const key = line.slice(0, separator).trim();
+    const value = line.slice(separator + 1).trim();
+    if (key) {
+      headers.append(key, value);
+    }
+  }
+  return { status, headers };
+}
+async function runCurlRequest(url, options) {
+  const tempDir = await mkdtemp(path6.join(os2.tmpdir(), "zk-agent-http-"));
+  const headersPath = path6.join(tempDir, "headers.txt");
+  const bodyPath = path6.join(tempDir, "body.txt");
+  try {
+    const args = [
+      "--silent",
+      "--show-error",
+      "--output",
+      bodyPath,
+      "--dump-header",
+      headersPath,
+      "--request",
+      options.method || "GET"
+    ];
+    if (options.redirect === "follow") {
+      args.push("--location");
+    }
+    for (const [key, value] of Object.entries(options.headers || {})) {
+      args.push("--header", `${key}: ${value}`);
+    }
+    if (typeof options.body === "string") {
+      args.push("--data-raw", options.body);
+    }
+    args.push(url);
+    const child = spawn("curl", args, {
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    const exitCode = await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("close", resolve);
+    });
+    if (exitCode !== 0) {
+      throw new Error(stderr.trim() || stdout.trim() || `curl exited with code ${exitCode}`);
+    }
+    const [rawHeaders, body] = await Promise.all([
+      readFile2(headersPath, "utf8"),
+      readFile2(bodyPath, "utf8")
+    ]);
+    const { status, headers } = parseCurlHeaders(rawHeaders);
+    return {
+      ok: status >= 200 && status < 300,
+      status,
+      headers,
+      body
+    };
+  } finally {
+    await rm2(tempDir, { recursive: true, force: true });
+  }
+}
+async function fetchTextWithFallback(url, options = {}) {
+  try {
+    const response = await fetch(url, {
+      method: options.method,
+      headers: options.headers,
+      body: options.body,
+      redirect: options.redirect
+    });
+    return {
+      ok: response.ok,
+      status: response.status,
+      headers: response.headers,
+      body: await response.text()
+    };
+  } catch (error) {
+    if (!isHttpUrl(url) || !isDnsResolutionFailure(error)) {
+      throw error;
+    }
+    return await runCurlRequest(url, options);
+  }
+}
+async function fetchJsonWithFallback(url, options = {}) {
+  const response = await fetchTextWithFallback(url, options);
+  return {
+    ...response,
+    json: JSON.parse(response.body)
+  };
+}
+
+// src/lib/relay.ts
 var RELAY_BODY_LIMIT_BYTES = 1024 * 1024;
 var RELAY_SERVICE = "zk-agent-relay";
 var RELAY_PROTOCOL = "zk-agent-session-relay";
 var RELAY_SCHEMA_VERSION = 1;
+var RELAY_STATE_BACKEND = "local-filesystem";
+var RELAY_DEPLOYMENT_SCOPE = "single-host";
 function relayDir() {
-  const directory = path6.join(storageDir(), "relay");
+  const directory = path7.join(storageDir(), "relay");
   if (!fs7.existsSync(directory)) {
     fs7.mkdirSync(directory, { recursive: true, mode: 448 });
   }
   return directory;
 }
 function relayRecordPath(requestId) {
-  return path6.join(relayDir(), `${requestId}.json`);
+  return path7.join(relayDir(), `${requestId}.json`);
 }
 function writeRelayRecord(record) {
   fs7.writeFileSync(relayRecordPath(record.request_id), JSON.stringify(record, null, 2), {
@@ -11870,11 +12194,15 @@ function sanitizeRelayRecord(record) {
 }
 function relayStatusResponse(baseUrl, record) {
   const sanitized = sanitizeRelayRecord(record);
+  const shareUrl = relayShareUrl(baseUrl, sanitized.request_id);
+  const statusUrl = relayStatusUrl(baseUrl, sanitized.request_id);
   return {
     request_id: sanitized.request_id,
     status: relayStatus(record),
     approval_ready: Boolean(record.encrypted_payload),
-    approval_url: `${baseUrl}/r/${sanitized.request_id}`,
+    share_url: shareUrl,
+    status_url: statusUrl,
+    approval_url: shareUrl,
     expires_at: sanitized.expires_at,
     request: sanitized.request,
     approval_submitted_at: sanitized.approval_submitted_at
@@ -11925,14 +12253,14 @@ function writeBody(response, statusCode, contentType, value, extraHeaders = {})
 }
 function resolveConnectorUiDistRoot() {
   const currentFile = fileURLToPath3(import.meta.url);
-  const currentDir2 = path6.dirname(currentFile);
+  const currentDir2 = path7.dirname(currentFile);
   const candidates = [
-    path6.resolve(currentDir2, "./connector-ui"),
-    path6.resolve(currentDir2, "../../../zk-connector-ui/dist"),
-    path6.resolve(currentDir2, "../../zk-connector-ui/dist")
+    path7.resolve(currentDir2, "./connector-ui"),
+    path7.resolve(currentDir2, "../../../zk-connector-ui/dist"),
+    path7.resolve(currentDir2, "../../zk-connector-ui/dist")
   ];
   for (const candidate of candidates) {
-    if (fs7.existsSync(path6.join(candidate, "index.html"))) {
+    if (fs7.existsSync(path7.join(candidate, "index.html"))) {
       return candidate;
     }
   }
@@ -11961,7 +12289,7 @@ function relayCapabilities(connectorUiAvailable) {
     ...connectorUiAvailable ? ["connector-ui"] : []
   ];
 }
-function relayHealthResponse(bindBaseUrl, publicBaseUrl, connectorUiAvailable) {
+function relayHealthResponse(bindBaseUrl, publicBaseUrl, connectorUiAvailable, publicOriginSource) {
   return {
     ok: true,
     service: RELAY_SERVICE,
@@ -11970,6 +12298,10 @@ function relayHealthResponse(bindBaseUrl, publicBaseUrl, connectorUiAvailable) {
     relay_mode: "local-file",
     origin: normalizeRelayBaseUrl(bindBaseUrl),
     public_origin: normalizeRelayBaseUrl(publicBaseUrl),
+    public_origin_source: publicOriginSource,
+    state_backend: RELAY_STATE_BACKEND,
+    deployment_scope: RELAY_DEPLOYMENT_SCOPE,
+    same_host_restart_persists: true,
     connector_ui_available: connectorUiAvailable,
     capabilities: relayCapabilities(connectorUiAvailable)
   };
@@ -11984,31 +12316,34 @@ function relayApprovalUrl(baseUrl, requestId) {
   return `${relayStatusUrl(baseUrl, requestId)}/approval`;
 }
 async function publishRelayRequest(baseUrl, body) {
-  const response = await fetch(`${normalizeRelayBaseUrl(baseUrl)}/api/requests`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
-    body: JSON.stringify(body)
-  });
+  const response = await fetchJsonWithFallback(
+    `${normalizeRelayBaseUrl(baseUrl)}/api/requests`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    }
+  );
   if (!response.ok) {
     throw new Error(`Relay publish failed with status ${response.status}`);
   }
-  return await response.json();
+  return response.json;
 }
 async function fetchRelayStatus(baseUrl, requestId) {
-  const response = await fetch(relayStatusUrl(baseUrl, requestId));
+  const response = await fetchJsonWithFallback(relayStatusUrl(baseUrl, requestId));
   if (!response.ok) {
     throw new Error(`Relay status fetch failed with status ${response.status}`);
   }
-  return await response.json();
+  return response.json;
 }
 async function fetchRelayHealth(baseUrl) {
-  const response = await fetch(`${normalizeRelayBaseUrl(baseUrl)}/health`);
+  const response = await fetchJsonWithFallback(`${normalizeRelayBaseUrl(baseUrl)}/health`);
   if (!response.ok) {
     throw new Error(`Relay health fetch failed with status ${response.status}`);
   }
-  return await response.json();
+  return response.json;
 }
 function sleep(ms) {
   return new Promise((resolve) => {
@@ -12033,15 +12368,16 @@ async function waitForRelayApprovalReady(baseUrl, requestId, options) {
   );
 }
 async function fetchRelayApproval(baseUrl, requestId) {
-  const response = await fetch(relayApprovalUrl(baseUrl, requestId));
+  const response = await fetchJsonWithFallback(relayApprovalUrl(baseUrl, requestId));
   if (!response.ok) {
     throw new Error(`Relay approval fetch failed with status ${response.status}`);
   }
-  return await response.json();
+  return response.json;
 }
 async function startRelayServer(options) {
   const uiDistRoot = resolveConnectorUiDistRoot();
   let bindBaseUrl = "";
+  const publicOriginSource = options.publicOrigin?.trim() ? "configured" : "bind-origin-default";
   const server = createServer(async (request, response) => {
     try {
       const requestUrl = new URL(request.url || "/", "http://localhost");
@@ -12056,7 +12392,12 @@ async function startRelayServer(options) {
         writeJson2(
           response,
           200,
-          relayHealthResponse(bindBaseUrl, publicBaseUrl, Boolean(uiDistRoot))
+          relayHealthResponse(
+            bindBaseUrl,
+            publicBaseUrl,
+            Boolean(uiDistRoot),
+            publicOriginSource
+          )
         );
         return;
       }
@@ -12125,7 +12466,7 @@ async function startRelayServer(options) {
       }
       if (method === "GET" && uiDistRoot) {
         const relativePath = pathname === "/" ? "/index.html" : pathname;
-        const filePath = path6.resolve(uiDistRoot, `.${relativePath}`);
+        const filePath = path7.resolve(uiDistRoot, `.${relativePath}`);
         if (!filePath.startsWith(uiDistRoot)) {
           writeJson2(response, 403, { error: "Forbidden path" });
           return;
@@ -12134,7 +12475,7 @@ async function startRelayServer(options) {
           writeBody(response, 200, contentTypeFor(filePath), fs7.readFileSync(filePath));
           return;
         }
-        const indexPath = path6.join(uiDistRoot, "index.html");
+        const indexPath = path7.join(uiDistRoot, "index.html");
         if (fs7.existsSync(indexPath)) {
           writeBody(response, 200, "text/html; charset=utf-8", fs7.readFileSync(indexPath));
           return;
@@ -12181,8 +12522,14 @@ async function startRelayServer(options) {
 // src/commands/relay.ts
 function buildRelayServeRecommendedCommands(relayUrl) {
   return {
-    createWallet: `zk-agent wallet create --relay-url ${relayUrl}`,
-    reapproveWallet: `zk-agent wallet reapprove --name main --relay-url ${relayUrl}`
+    createWallet: `zk-agent wallet create --relay-url ${relayUrl} --wait-relay --prompt-code`,
+    reapproveWallet: `zk-agent wallet reapprove --name main --relay-url ${relayUrl} --wait-relay --prompt-code`
+  };
+}
+function buildAdvertisedRelayBases(publicOrigin) {
+  return {
+    shareLinkBaseUrl: `${publicOrigin}/r`,
+    statusApiBaseUrl: `${publicOrigin}/api/requests`
   };
 }
 function isRecord3(value) {
@@ -12198,6 +12545,15 @@ function isRelayCapability(value) {
     "connector-ui"
   ].includes(String(value));
 }
+function isRelayPublicOriginSource(value) {
+  return value === "configured" || value === "bind-origin-default";
+}
+function isRelayStateBackend(value) {
+  return value === "local-filesystem";
+}
+function isRelayDeploymentScope(value) {
+  return value === "single-host";
+}
 function asRelayHealthResponse(value) {
   if (!isRecord3(value)) return null;
   if (value.ok !== true) return null;
@@ -12207,6 +12563,18 @@ function asRelayHealthResponse(value) {
   if (value.relay_mode !== "local-file") return null;
   if (typeof value.origin !== "string") return null;
   if (typeof value.public_origin !== "string") return null;
+  if (typeof value.public_origin_source !== "undefined" && !isRelayPublicOriginSource(value.public_origin_source)) {
+    return null;
+  }
+  if (typeof value.state_backend !== "undefined" && !isRelayStateBackend(value.state_backend)) {
+    return null;
+  }
+  if (typeof value.deployment_scope !== "undefined" && !isRelayDeploymentScope(value.deployment_scope)) {
+    return null;
+  }
+  if (typeof value.same_host_restart_persists !== "undefined" && typeof value.same_host_restart_persists !== "boolean") {
+    return null;
+  }
   if (typeof value.connector_ui_available !== "boolean") return null;
   if (!Array.isArray(value.capabilities) || !value.capabilities.every(isRelayCapability)) {
     return null;
@@ -12225,6 +12593,38 @@ function relayPublicOriginLooksLocal(origin) {
     return false;
   }
 }
+function normalizeComparableRelayUrl(value) {
+  try {
+    return new URL(value).toString().replace(/\/+$/, "");
+  } catch {
+    return null;
+  }
+}
+function relayUrlMatches(left, right) {
+  const normalizedLeft = normalizeComparableRelayUrl(left);
+  const normalizedRight = right ? normalizeComparableRelayUrl(right) : null;
+  if (normalizedLeft === null || normalizedRight === null) {
+    return null;
+  }
+  return normalizedLeft === normalizedRight;
+}
+function inferRelayPublicOriginSource(options) {
+  const normalizedOrigin = options.origin ? normalizeComparableRelayUrl(options.origin) : null;
+  const normalizedPublicOrigin = normalizeComparableRelayUrl(options.publicOrigin);
+  if (!normalizedOrigin || !normalizedPublicOrigin) {
+    return null;
+  }
+  return normalizedOrigin === normalizedPublicOrigin ? "bind-origin-default" : "configured";
+}
+function inferRelayStateBackend(relayMode) {
+  return relayMode === "local-file" ? "local-filesystem" : null;
+}
+function inferRelayDeploymentScope(relayMode) {
+  return relayMode === "local-file" ? "single-host" : null;
+}
+function inferSameHostRestartPersists(relayMode) {
+  return relayMode === "local-file" ? true : null;
+}
 function relayHostedReadinessNotes(options) {
   const notes = [];
   if (!options.compatible) {
@@ -12235,7 +12635,7 @@ function relayHostedReadinessNotes(options) {
   }
   if (relayPublicOriginLooksLocal(options.publicOrigin)) {
     notes.push(
-      "Relay compatibility is present, but the advertised public origin still points at a local-only address. Set --public-origin to the externally reachable URL before using this as a hosted approval path."
+      options.publicOriginSource === "bind-origin-default" ? "Relay compatibility is present, but the relay is still advertising its bind origin as the public origin. Set --public-origin to the externally reachable URL before using this as a hosted approval path." : "Relay compatibility is present, but the advertised public origin still points at a local-only address. Set --public-origin to the externally reachable URL before using this as a hosted approval path."
     );
   }
   if (options.connectorUiAvailable === false) {
@@ -12245,19 +12645,70 @@ function relayHostedReadinessNotes(options) {
   }
   return notes;
 }
+function relayOperationalContractNotes(options) {
+  if (!options.compatible) {
+    return [];
+  }
+  if (options.stateBackend === "local-filesystem" && options.deploymentScope === "single-host" && options.sameHostRestartPersists === true) {
+    return [
+      "Relay state is stored on the relay host local filesystem. Restarts on the same host keep pending approval state, but multi-instance or load-balanced deployments do not share relay state."
+    ];
+  }
+  return [];
+}
+function relayOriginRelationshipNotes(options) {
+  const notes = [];
+  const relayUrlMatchesOrigin = relayUrlMatches(options.relayUrl, options.origin);
+  const relayUrlMatchesPublicOrigin = relayUrlMatches(options.relayUrl, options.publicOrigin);
+  if (relayUrlMatchesOrigin === false) {
+    notes.push(
+      "The inspected relay URL differs from the bind origin reported by /health. That is expected when you inspect a relay through a reverse proxy or tunnel instead of the local bind address."
+    );
+  }
+  if (relayUrlMatchesPublicOrigin === false) {
+    notes.push(
+      "The inspected relay URL differs from the advertised public origin. Share links and wallet approval commands will use the public origin, not the inspected relay URL."
+    );
+  }
+  return notes;
+}
 function buildRelayInspectPayload(relayUrl, rawHealth) {
   const health = asRelayHealthResponse(rawHealth);
   const fallbackPublicOrigin = isRecord3(rawHealth) && typeof rawHealth.public_origin === "string" ? rawHealth.public_origin : relayUrl;
   const publicOrigin = health?.public_origin || fallbackPublicOrigin;
+  const publicOriginSource = health?.public_origin_source || inferRelayPublicOriginSource({
+    origin: health?.origin || null,
+    publicOrigin
+  });
+  const stateBackend = health?.state_backend || inferRelayStateBackend(health?.relay_mode || null);
+  const deploymentScope = health?.deployment_scope || inferRelayDeploymentScope(health?.relay_mode || null);
+  const sameHostRestartPersists = typeof health?.same_host_restart_persists === "boolean" ? health.same_host_restart_persists : inferSameHostRestartPersists(health?.relay_mode || null);
   const compatible = Boolean(health && hasCoreRelayCapabilities(health.capabilities));
   const connectorUiAvailable = health?.connector_ui_available ?? null;
+  const relayUrlMatchesOrigin = relayUrlMatches(relayUrl, health?.origin || null);
+  const relayUrlMatchesPublicOrigin = relayUrlMatches(relayUrl, publicOrigin);
   const publicOriginLooksLocal = relayPublicOriginLooksLocal(publicOrigin);
   const hostedShareRedirectReady = compatible && connectorUiAvailable === true && !publicOriginLooksLocal;
-  const notes = relayHostedReadinessNotes({
-    compatible,
-    publicOrigin,
-    connectorUiAvailable
-  });
+  const { shareLinkBaseUrl, statusApiBaseUrl } = buildAdvertisedRelayBases(publicOrigin);
+  const notes = [
+    ...relayHostedReadinessNotes({
+      compatible,
+      publicOrigin,
+      publicOriginSource,
+      connectorUiAvailable
+    }),
+    ...relayOperationalContractNotes({
+      compatible,
+      stateBackend,
+      deploymentScope,
+      sameHostRestartPersists
+    }),
+    ...relayOriginRelationshipNotes({
+      relayUrl,
+      origin: health?.origin || null,
+      publicOrigin
+    })
+  ];
   return {
     ok: true,
     status: "relay-inspected",
@@ -12269,6 +12720,14 @@ function buildRelayInspectPayload(relayUrl, rawHealth) {
     relayMode: health?.relay_mode || null,
     origin: health?.origin || null,
     publicOrigin,
+    publicOriginSource,
+    stateBackend,
+    deploymentScope,
+    sameHostRestartPersists,
+    shareLinkBaseUrl,
+    statusApiBaseUrl,
+    relayUrlMatchesOrigin,
+    relayUrlMatchesPublicOrigin,
     publicOriginLooksLocal,
     connectorUiAvailable,
     hostedShareRedirectReady,
@@ -12279,6 +12738,23 @@ function buildRelayInspectPayload(relayUrl, rawHealth) {
 }
 function createRelayCommand() {
   const relay = new Command8("relay").description("Run the local connector relay prototype server");
+  relay.addHelpText(
+    "after",
+    [
+      "",
+      "  Hosted remote-approval path:",
+      "    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",
+      "    zk-agent wallet reapprove --name main --relay-url <url> --wait-relay --prompt-code",
+      "",
+      "  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")
+  );
   relay.command("serve").description("Serve the local relay API and, when available, the built connector UI").option("--host <host>", "Host to bind", "127.0.0.1").option("--port <port>", "Port to bind (0 = choose a free port)", "4445").option(
     "--public-origin <url>",
     "Public base URL to advertise in share/status links when the relay is behind a tunnel or reverse proxy"
@@ -12294,13 +12770,16 @@ function createRelayCommand() {
       publicOrigin: options.publicOrigin?.trim()
     });
     const publicOrigin = options.publicOrigin?.trim() || server.origin;
+    const publicOriginSource = options.publicOrigin?.trim() ? "configured" : "bind-origin-default";
     const publicOriginLooksLocal = relayPublicOriginLooksLocal(publicOrigin);
     const connectorUiAvailable = server.connectorUiAvailable;
     const hostedShareRedirectReady = connectorUiAvailable && !publicOriginLooksLocal;
+    const { shareLinkBaseUrl, statusApiBaseUrl } = buildAdvertisedRelayBases(publicOrigin);
     const recommendedCommands = buildRelayServeRecommendedCommands(publicOrigin);
     const notes = relayHostedReadinessNotes({
       compatible: true,
       publicOrigin,
+      publicOriginSource,
       connectorUiAvailable
     });
     const payload = {
@@ -12308,6 +12787,12 @@ function createRelayCommand() {
       status: "relay-serving",
       origin: server.origin,
       publicOrigin,
+      publicOriginSource,
+      stateBackend: "local-filesystem",
+      deploymentScope: "single-host",
+      sameHostRestartPersists: true,
+      shareLinkBaseUrl,
+      statusApiBaseUrl,
       publicOriginLooksLocal,
       port: server.port,
       healthUrl: `${server.origin}/health`,
@@ -12334,6 +12819,15 @@ function createRelayCommand() {
       if (publicOrigin !== server.origin) {
         humanLine("public origin", publicOrigin);
       }
+      humanLine("public origin source", publicOriginSource);
+      humanLine("state backend", payload.stateBackend);
+      humanLine("deployment scope", payload.deploymentScope);
+      humanLine(
+        "same-host restart persists",
+        payload.sameHostRestartPersists ? "yes" : "no"
+      );
+      humanLine("share-link base", shareLinkBaseUrl);
+      humanLine("status api base", statusApiBaseUrl);
       humanLine("health", `${server.origin}/health`);
       humanLine("hosted ready", hostedShareRedirectReady ? "yes" : "no");
       if (connectorUiAvailable !== null) {
@@ -12385,6 +12879,32 @@ function createRelayCommand() {
     if (payload.publicOrigin) {
       humanLine("public origin", payload.publicOrigin);
     }
+    if (payload.publicOriginSource) {
+      humanLine("public origin source", payload.publicOriginSource);
+    }
+    if (payload.stateBackend) {
+      humanLine("state backend", payload.stateBackend);
+    }
+    if (payload.deploymentScope) {
+      humanLine("deployment scope", payload.deploymentScope);
+    }
+    if (payload.sameHostRestartPersists !== null) {
+      humanLine(
+        "same-host restart persists",
+        payload.sameHostRestartPersists ? "yes" : "no"
+      );
+    }
+    humanLine("share-link base", payload.shareLinkBaseUrl);
+    humanLine("status api base", payload.statusApiBaseUrl);
+    if (payload.relayUrlMatchesOrigin !== null) {
+      humanLine("relay url matches origin", payload.relayUrlMatchesOrigin ? "yes" : "no");
+    }
+    if (payload.relayUrlMatchesPublicOrigin !== null) {
+      humanLine(
+        "relay url matches public origin",
+        payload.relayUrlMatchesPublicOrigin ? "yes" : "no"
+      );
+    }
     humanLine("public origin local", payload.publicOriginLooksLocal ? "yes" : "no");
     if (payload.connectorUiAvailable !== null) {
       humanLine("connector ui", payload.connectorUiAvailable ? "available" : "missing");
@@ -12400,10 +12920,9 @@ function createRelayCommand() {
       if (payload.recommendedCommands.reapproveWallet) {
         humanLine("reapprove wallet", payload.recommendedCommands.reapproveWallet);
       }
-    } else {
-      for (const note of payload.notes) {
-        humanLine("note", note);
-      }
+    }
+    for (const note of payload.notes) {
+      humanLine("note", note);
     }
   });
   return relay;
@@ -12416,12 +12935,12 @@ import { Command as Command9 } from "commander";
 
 // ../account-profiles/src/profiles.ts
 import fs8 from "node:fs";
-import path7 from "node:path";
+import path8 from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 var PACKAGE_NAME = "@zk-agent/account-profiles";
 var PACKAGE_ROOT_FALLBACK = `<${PACKAGE_NAME} package root unavailable>`;
 function isExpectedPackageRoot(candidate) {
-  const manifestPath = path7.join(candidate, "package.json");
+  const manifestPath = path8.join(candidate, "package.json");
   if (!fs8.existsSync(manifestPath)) return false;
   try {
     const manifest = JSON.parse(fs8.readFileSync(manifestPath, "utf8"));
@@ -12431,19 +12950,19 @@ function isExpectedPackageRoot(candidate) {
   }
 }
 function resolvePackageRoot() {
-  const moduleRoot = path7.resolve(path7.dirname(fileURLToPath4(import.meta.url)), "..");
+  const moduleRoot = path8.resolve(path8.dirname(fileURLToPath4(import.meta.url)), "..");
   const cwd = process.cwd();
   const candidates = [
     process.env.ZK_AGENT_ACCOUNT_PROFILES_ROOT,
-    path7.join(moduleRoot, "dist", "builtin-account-profiles"),
+    path8.join(moduleRoot, "dist", "builtin-account-profiles"),
     moduleRoot,
-    path7.join(cwd, "packages", "account-profiles"),
-    path7.join(cwd, "account-profiles"),
+    path8.join(cwd, "packages", "account-profiles"),
+    path8.join(cwd, "account-profiles"),
     cwd
   ].filter((value) => typeof value === "string" && value.trim().length > 0);
   const seen = /* @__PURE__ */ new Set();
   for (const candidate of candidates) {
-    const normalized = path7.resolve(candidate);
+    const normalized = path8.resolve(candidate);
     if (seen.has(normalized)) continue;
     seen.add(normalized);
     if (isExpectedPackageRoot(normalized)) {
@@ -12515,11 +13034,11 @@ function missingArtifactError(profileId, artifactPath2) {
 }
 function contractPath(...segments) {
   const packageRoot = tryResolvePackageRoot();
-  return packageRoot ? path7.join(packageRoot, "contracts", ...segments) : path7.join(PACKAGE_ROOT_FALLBACK, "contracts", ...segments);
+  return packageRoot ? path8.join(packageRoot, "contracts", ...segments) : path8.join(PACKAGE_ROOT_FALLBACK, "contracts", ...segments);
 }
 function artifactPath(...segments) {
   const packageRoot = tryResolvePackageRoot();
-  return packageRoot ? path7.join(packageRoot, "artifacts", ...segments) : path7.join(PACKAGE_ROOT_FALLBACK, "artifacts", ...segments);
+  return packageRoot ? path8.join(packageRoot, "artifacts", ...segments) : path8.join(PACKAGE_ROOT_FALLBACK, "artifacts", ...segments);
 }
 function createDailySpendLimitProfile() {
   const resolvedArtifactPath = artifactPath("daily-spend-limit", "Account.json");
@@ -13005,11 +13524,16 @@ function sanitizeWalletRecord(wallet) {
 function relayOutputAliases(relay) {
   const shareUrl = relay && "share_url" in relay ? relay.share_url : void 0;
   const statusUrl = relay && "status_url" in relay ? relay.status_url : void 0;
+  const approvalUrl = relay?.approval_url;
+  const shareLinkBaseUrl = shareUrl ? shareUrl.replace(/\/[^/]+$/, "") : approvalUrl ? approvalUrl.replace(/\/[^/]+$/, "") : void 0;
+  const statusApiBaseUrl = statusUrl ? statusUrl.replace(/\/[^/]+$/, "") : approvalUrl && relay?.request_id ? `${approvalUrl.replace(/\/r\/[^/]+$/, "")}/api/requests` : void 0;
   return {
     relayRequestId: relay?.request_id,
     relayShareUrl: shareUrl,
     relayStatusUrl: statusUrl,
-    relayApprovalUrl: relay?.approval_url
+    relayApprovalUrl: approvalUrl,
+    relayShareLinkBaseUrl: shareLinkBaseUrl,
+    relayStatusApiBaseUrl: statusApiBaseUrl
   };
 }
 function sanitizeWalletRequestRecord(request) {
@@ -14279,6 +14803,165 @@ function buildPendingRequestRecommendedCommands(walletName, requestId, relayUrl,
 function buildPendingRequestNextAction(recommendedCommands) {
   return recommendedCommands.relayStatus ?? recommendedCommands.awaitLocal;
 }
+function buildRelayWaitGuidanceLines(options) {
+  return [
+    ["status", "Waiting for relay approval"],
+    ["request", options.requestId],
+    ["wallet", options.walletName],
+    ["share url", options.relay.share_url],
+    ["status url", options.relay.status_url],
+    ["approval url", options.relay.approval_url],
+    ["expires", options.expiresAt],
+    ["browser step", "Open the share url in a browser and complete connector approval."],
+    [
+      "terminal step",
+      options.codeEntry === "prompt" ? "After the relay is ready, enter the 6-digit approval code in this terminal." : "The CLI will finalize automatically with the provided 6-digit approval code once the relay is ready."
+    ],
+    ["fallback status", options.statusCommand],
+    ["fallback approve", options.approveCommand]
+  ];
+}
+function printRelayWaitGuidance(options) {
+  if (shouldJsonOutput()) return;
+  for (const [label, value] of buildRelayWaitGuidanceLines(options)) {
+    humanLine(label, value);
+  }
+}
+async function buildRelayStatusFollowUp(options) {
+  if (options.relay.status === "expired") {
+    return await buildRelayExpiredRecoveryCommands({
+      walletName: options.relay.request?.walletName,
+      relayUrl: options.relayUrl,
+      paymasterMode: options.relay.request?.requestedPaymasterMode,
+      accountKind: options.relay.request?.requestedAccountKind
+    });
+  }
+  if (options.relay.approval_ready) {
+    const approve = buildWalletRequestRelayApproveRecommendedCommand(
+      options.relay.request_id,
+      options.relayUrl
+    );
+    return {
+      nextAction: approve,
+      recommendedCommands: {
+        status: buildWalletRequestRelayStatusRecommendedCommand(
+          options.relay.request_id,
+          options.relayUrl
+        ),
+        approve
+      }
+    };
+  }
+  return {
+    nextAction: buildWalletRequestRelayStatusRecommendedCommand(
+      options.relay.request_id,
+      options.relayUrl
+    ),
+    recommendedCommands: {
+      status: buildWalletRequestRelayStatusRecommendedCommand(
+        options.relay.request_id,
+        options.relayUrl
+      )
+    }
+  };
+}
+async function buildRelayExpiredRecoveryCommands(options) {
+  const relayInspect = buildRelayInspectRecommendedCommand(options.relayUrl);
+  const walletName = options.walletName?.trim();
+  if (!walletName) {
+    return {
+      nextAction: relayInspect,
+      recommendedCommands: {
+        relayInspect
+      },
+      note: "Relay approval expired. Inspect the hosted relay, then reissue the wallet request again."
+    };
+  }
+  const existingWallet = await loadWalletSession(walletName);
+  const reissueRemoteApproval = existingWallet ? buildWalletReapproveRemoteRecommendedCommand(walletName, options.relayUrl) : buildWalletCreateRemoteRecommendedCommand(
+    options.relayUrl,
+    options.paymasterMode,
+    walletName,
+    options.accountKind
+  );
+  return {
+    nextAction: reissueRemoteApproval,
+    recommendedCommands: {
+      relayInspect,
+      reissueRemoteApproval
+    },
+    note: "Relay approval expired. Reissue the remote request. If the original request used scoped session flags, add those same policy flags again."
+  };
+}
+function buildRelayApprovalTimeoutError(options) {
+  const statusCommand = buildWalletRequestRelayStatusRecommendedCommand(
+    options.requestId,
+    options.relayUrl
+  );
+  const approveCommand = buildWalletRequestRelayApproveRecommendedCommand(
+    options.requestId,
+    options.relayUrl
+  );
+  return new AgentError(
+    "RELAY_APPROVAL_TIMEOUT",
+    `Timed out waiting for relay approval after ${Math.ceil(options.timeoutMs / 1e3)} seconds.`,
+    {
+      requestId: options.requestId,
+      relayUrl: options.relayUrl,
+      timeoutMs: options.timeoutMs,
+      intervalMs: options.intervalMs,
+      retryable: true,
+      statusCommand,
+      approveCommand,
+      suggestedAction: "Check the current relay status, then finalize the wallet approval once approval_ready=true."
+    }
+  );
+}
+async function buildRelayApprovalExpiredError(options) {
+  const recovery = await buildRelayExpiredRecoveryCommands({
+    walletName: options.walletName,
+    relayUrl: options.relayUrl,
+    paymasterMode: options.paymasterMode,
+    accountKind: options.accountKind
+  });
+  return new AgentError(
+    "RELAY_APPROVAL_EXPIRED",
+    `Relay approval expired before the encrypted payload was ready for request ${options.requestId}.`,
+    {
+      requestId: options.requestId,
+      relayUrl: options.relayUrl,
+      retryable: true,
+      note: recovery.note,
+      relayInspectCommand: recovery.recommendedCommands.relayInspect,
+      reissueRemoteApprovalCommand: recovery.recommendedCommands.reissueRemoteApproval,
+      suggestedAction: "Inspect the hosted relay, then reissue the remote approval request."
+    }
+  );
+}
+function buildRelayApprovalNotReadyError(options) {
+  const statusCommand = buildWalletRequestRelayStatusRecommendedCommand(
+    options.requestId,
+    options.relayUrl
+  );
+  const approveCommand = buildWalletRequestRelayApproveRecommendedCommand(
+    options.requestId,
+    options.relayUrl
+  );
+  return new AgentError(
+    "RELAY_APPROVAL_NOT_READY",
+    `Relay approval is not ready yet for request ${options.requestId}.`,
+    {
+      requestId: options.requestId,
+      relayUrl: options.relayUrl,
+      status: options.status,
+      approvalReady: options.approvalReady,
+      retryable: true,
+      statusCommand,
+      approveCommand,
+      suggestedAction: "Check the current relay status, then retry approval once approval_ready=true."
+    }
+  );
+}
 function buildRequestListEntryRecommendedCommands(walletName, requestId, paymasterMode) {
   return {
     show: buildWalletRequestShowRecommendedCommand(requestId),
@@ -14421,25 +15104,55 @@ async function fetchEncryptedRelayApprovalPayload(relayUrl, requestId, options)
       intervalMs: options.intervalMs ?? 2e3
     });
     if (!relay.approval_ready) {
-      throw new Error(`Relay approval expired before the encrypted payload was ready for request ${requestId}.`);
+      throw await buildRelayApprovalExpiredError({
+        requestId,
+        relayUrl
+      });
     }
   }
   const approval = await fetchRelayApproval(relayUrl, requestId);
   if (!approval.approval_ready || !approval.encrypted_payload) {
-    throw new Error(`Relay approval is not ready yet for request ${requestId}.`);
+    throw buildRelayApprovalNotReadyError({
+      requestId,
+      relayUrl,
+      status: approval.status,
+      approvalReady: approval.approval_ready
+    });
   }
   return approval.encrypted_payload;
 }
 async function finalizePublishedRelayWalletRequest(options) {
-  const encryptedPayload = await fetchEncryptedRelayApprovalPayload(
-    options.relayUrl,
-    options.walletRequest.requestId,
-    {
-      wait: true,
-      timeoutMs: options.timeoutMs,
-      intervalMs: options.intervalMs
+  let encryptedPayload;
+  try {
+    encryptedPayload = await fetchEncryptedRelayApprovalPayload(
+      options.relayUrl,
+      options.walletRequest.requestId,
+      {
+        wait: true,
+        timeoutMs: options.timeoutMs,
+        intervalMs: options.intervalMs
+      }
+    );
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("Timed out waiting for relay approval after ")) {
+      throw buildRelayApprovalTimeoutError({
+        requestId: options.walletRequest.requestId,
+        relayUrl: options.relayUrl,
+        timeoutMs: options.timeoutMs,
+        intervalMs: options.intervalMs
+      });
     }
-  );
+    if (error instanceof AgentError && error.code === "RELAY_APPROVAL_EXPIRED") {
+      throw await buildRelayApprovalExpiredError({
+        requestId: options.walletRequest.requestId,
+        walletName: options.walletRequest.walletName,
+        relayUrl: options.relayUrl,
+        paymasterMode: options.walletRequest.requestedPaymasterMode,
+        accountKind: options.walletRequest.requestedAccountKind
+      });
+    }
+    throw error;
+  }
   const code = options.code || (options.promptCode ? await readApprovalCodeFromStdin() : void 0);
   if (!code) {
     throw new Error("Missing relay approval code.");
@@ -14806,7 +15519,9 @@ async function printBuiltinSmartAccountProfiles() {
 }
 function createWalletCommand(deps) {
   const resolvedDeps = resolveWalletCommandDeps(deps);
-  const wallet = new Command9("wallet").description("Manage wallet sessions");
+  const wallet = new Command9("wallet").description(
+    "Create, inspect, and recover local-first wallet sessions"
+  );
   const request = new Command9("request").description("Inspect and finalize pending wallet requests");
   const signer = new Command9("signer").description(
     "Inspect and manage the stored local execution signer for a wallet"
@@ -14836,13 +15551,14 @@ function createWalletCommand(deps) {
     "after",
     [
       "",
-      "Default wallet path:",
+      "Local-first wallet path:",
       "  First bootstrap:",
       "    zk-agent wallet create --await-local",
       "    zk-agent next",
       "",
       "  Restore approval metadata for an existing wallet:",
       "    zk-agent wallet reapprove --name main --await-local",
+      "    zk-agent next",
       "",
       "  Attach a local signer when approval is still present:",
       "    zk-agent wallet signer attach --name main --private-key <hex>",
@@ -14852,10 +15568,11 @@ function createWalletCommand(deps) {
       "    zk-agent wallet status --name main",
       "    zk-agent wallet next --name main",
       "",
-      "  Remote approval path:",
+      "  Hosted remote approval path:",
       "    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"
+      "    zk-agent wallet reapprove --name main --relay-url <url> --wait-relay --prompt-code",
+      "    zk-agent next"
     ].join("\n")
   );
   request.addHelpText(
@@ -14869,7 +15586,11 @@ function createWalletCommand(deps) {
       "  Remote relay completion:",
       "    zk-agent wallet request relay-publish --request-id <id> --relay-url <url>",
       "    zk-agent wallet request relay-status --request-id <id> --relay-url <url> --wait",
-      "    zk-agent wallet request approve --request-id <id> --relay-url <url> --code <code> --wait"
+      "    zk-agent wallet request approve --request-id <id> --relay-url <url> --code <code> --wait",
+      "",
+      "  If relay-status returns status = expired:",
+      "    zk-agent relay inspect --relay-url <url>",
+      "    zk-agent wallet create|reapprove --relay-url <url> --wait-relay --prompt-code"
     ].join("\n")
   );
   signer.addHelpText(
@@ -14968,6 +15689,23 @@ function createWalletCommand(deps) {
       }
       const relay = options.relayUrl ? await publishWalletRequestToRelay(request2, options.relayUrl) : void 0;
       if (relayWaitOptions) {
+        if (relay) {
+          printRelayWaitGuidance({
+            requestId: request2.requestId,
+            walletName: request2.walletName,
+            relay,
+            expiresAt: request2.expiresAt,
+            codeEntry: relayWaitOptions.promptCode ? "prompt" : "provided",
+            statusCommand: buildWalletRequestRelayStatusRecommendedCommand(
+              request2.requestId,
+              relayWaitOptions.relayUrl
+            ),
+            approveCommand: buildWalletRequestRelayApproveRecommendedCommand(
+              request2.requestId,
+              relayWaitOptions.relayUrl
+            )
+          });
+        }
         const { payload, walletRecord } = await finalizePublishedRelayWalletRequest({
           walletRequest: request2,
           ...relayWaitOptions
@@ -15010,7 +15748,9 @@ function createWalletCommand(deps) {
           ["approval url", request2.approvalUrl],
           ...relay ? [
             ["share url", relay.share_url],
-            ["status url", relay.status_url]
+            ["status url", relay.status_url],
+            ["share-link base", relay.share_url.replace(/\/[^/]+$/, "")],
+            ["status api base", relay.status_url.replace(/\/[^/]+$/, "")]
           ] : [],
           ["expires", request2.expiresAt],
           ["next local", buildWalletRequestAwaitLocalRecommendedCommand(request2.requestId)],
@@ -15114,6 +15854,23 @@ function createWalletCommand(deps) {
       }
       const relay = options.relayUrl ? await publishWalletRequestToRelay(request2, options.relayUrl) : void 0;
       if (relayWaitOptions) {
+        if (relay) {
+          printRelayWaitGuidance({
+            requestId: request2.requestId,
+            walletName: request2.walletName,
+            relay,
+            expiresAt: request2.expiresAt,
+            codeEntry: relayWaitOptions.promptCode ? "prompt" : "provided",
+            statusCommand: buildWalletRequestRelayStatusRecommendedCommand(
+              request2.requestId,
+              relayWaitOptions.relayUrl
+            ),
+            approveCommand: buildWalletRequestRelayApproveRecommendedCommand(
+              request2.requestId,
+              relayWaitOptions.relayUrl
+            )
+          });
+        }
         const { payload, walletRecord: approvedWallet } = await finalizePublishedRelayWalletRequest({
           walletRequest: request2,
           ...relayWaitOptions
@@ -15157,7 +15914,9 @@ function createWalletCommand(deps) {
           ["approval url", request2.approvalUrl],
           ...relay ? [
             ["share url", relay.share_url],
-            ["status url", relay.status_url]
+            ["status url", relay.status_url],
+            ["share-link base", relay.share_url.replace(/\/[^/]+$/, "")],
+            ["status api base", relay.status_url.replace(/\/[^/]+$/, "")]
           ] : [],
           ["expires", request2.expiresAt],
           ["next local", buildWalletRequestAwaitLocalRecommendedCommand(request2.requestId)],
@@ -15511,6 +16270,8 @@ function createWalletCommand(deps) {
         ["request", relay.request_id],
         ["share url", relay.share_url],
         ["status url", relay.status_url],
+        ["share-link base", relay.share_url.replace(/\/[^/]+$/, "")],
+        ["status api base", relay.status_url.replace(/\/[^/]+$/, "")],
         ["next status", buildWalletRequestRelayStatusRecommendedCommand(relay.request_id, options.relayUrl)],
         ["next approve", buildWalletRequestRelayApproveRecommendedCommand(relay.request_id, options.relayUrl)]
       ],
@@ -15529,38 +16290,53 @@ function createWalletCommand(deps) {
     );
   });
   request.command("relay-status").description("Inspect the relay status of a published wallet request, optionally waiting until approval is ready").requiredOption("--request-id <id>", "Wallet request id").requiredOption("--relay-url <url>", "Relay server base URL").option("--wait", "Poll until the encrypted relay approval is ready or the request expires").option("--timeout-seconds <seconds>", "How long to wait while polling relay status", "600").option("--interval-ms <milliseconds>", "How often to poll relay status while waiting", "2000").action(async (options) => {
-    const relay = options.wait ? await waitForRelayApprovalReady(options.relayUrl, options.requestId, {
-      timeoutMs: parsePositiveIntegerOption(options.timeoutSeconds, "--timeout-seconds", 600) * 1e3,
-      intervalMs: parsePositiveIntegerOption(options.intervalMs, "--interval-ms", 2e3)
-    }) : await fetchRelayStatus(options.relayUrl, options.requestId);
+    const timeoutMs = parsePositiveIntegerOption(options.timeoutSeconds, "--timeout-seconds", 600) * 1e3;
+    const intervalMs = parsePositiveIntegerOption(options.intervalMs, "--interval-ms", 2e3);
+    let relay;
+    try {
+      relay = options.wait ? await waitForRelayApprovalReady(options.relayUrl, options.requestId, {
+        timeoutMs,
+        intervalMs
+      }) : await fetchRelayStatus(options.relayUrl, options.requestId);
+    } catch (error) {
+      if (options.wait && error instanceof Error && error.message.startsWith("Timed out waiting for relay approval after ")) {
+        throw buildRelayApprovalTimeoutError({
+          requestId: options.requestId,
+          relayUrl: options.relayUrl,
+          timeoutMs,
+          intervalMs
+        });
+      }
+      throw error;
+    }
+    const followUp = await buildRelayStatusFollowUp({
+      relay,
+      relayUrl: options.relayUrl
+    });
     printResult(
       [
         ["status", relay.status],
         ["request", relay.request_id],
         ["approval ready", relay.approval_ready ? "yes" : "no"],
-        ["share url", relay.approval_url],
+        ["share url", relay.share_url],
+        ["status url", relay.status_url],
+        ["approval url", relay.approval_url],
+        ["share-link base", relay.share_url.replace(/\/[^/]+$/, "")],
+        ["status api base", relay.status_url.replace(/\/[^/]+$/, "")],
         ["expires", relay.expires_at],
-        ["next status", buildWalletRequestRelayStatusRecommendedCommand(relay.request_id, options.relayUrl)],
-        ...relay.approval_ready ? [[
-          "next approve",
-          buildWalletRequestRelayApproveRecommendedCommand(relay.request_id, options.relayUrl)
-        ]] : []
+        ...followUp.note ? [["note", followUp.note]] : [],
+        ...Object.entries(followUp.recommendedCommands).map(
+          ([label, command]) => [label, command]
+        )
       ],
       {
         ok: true,
         walletRequestId: relay.request_id,
         relay,
         ...relayOutputAliases(relay),
-        nextAction: relay.approval_ready ? buildWalletRequestRelayApproveRecommendedCommand(relay.request_id, options.relayUrl) : buildWalletRequestRelayStatusRecommendedCommand(relay.request_id, options.relayUrl),
-        recommendedCommands: {
-          status: buildWalletRequestRelayStatusRecommendedCommand(relay.request_id, options.relayUrl),
-          ...relay.approval_ready ? {
-            approve: buildWalletRequestRelayApproveRecommendedCommand(
-              relay.request_id,
-              options.relayUrl
-            )
-          } : {}
-        }
+        nextAction: followUp.nextAction,
+        recommendedCommands: followUp.recommendedCommands,
+        ...followUp.note ? { note: followUp.note } : {}
       }
     );
   });
@@ -15573,6 +16349,24 @@ function createWalletCommand(deps) {
     if (options.wait && !options.relayUrl) {
       throw new Error("--wait is only supported together with --relay-url.");
     }
+    if (options.wait && options.relayUrl && !shouldJsonOutput()) {
+      const relayStatus2 = await fetchRelayStatus(options.relayUrl, walletRequest.requestId);
+      printRelayWaitGuidance({
+        requestId: walletRequest.requestId,
+        walletName: walletRequest.walletName,
+        relay: relayStatus2,
+        expiresAt: walletRequest.expiresAt,
+        codeEntry: "provided",
+        statusCommand: buildWalletRequestRelayStatusRecommendedCommand(
+          walletRequest.requestId,
+          options.relayUrl
+        ),
+        approveCommand: buildWalletRequestRelayApproveRecommendedCommand(
+          walletRequest.requestId,
+          options.relayUrl
+        )
+      });
+    }
     const payload = options.payload ? parseJsonInput(options.payload) : decryptApprovedPayloadForWalletRequest(
       walletRequest,
       options.encryptedPayload ? parseJsonInput(options.encryptedPayload) : await fetchEncryptedRelayApprovalPayload(options.relayUrl, walletRequest.requestId, {
@@ -17818,6 +18612,7 @@ async function ensureWorkflowWalletSession(input, deps) {
 }
 function workflowWalletApprovalLines(walletApproval) {
   if (!walletApproval) return [];
+  const relayAliases = workflowWalletApprovalRelayAliases(walletApproval.relay);
   const lines = [
     ["wallet approval", walletApproval.stage],
     ["wallet request", walletApproval.request.requestId]
@@ -17837,6 +18632,12 @@ function workflowWalletApprovalLines(walletApproval) {
   if (walletApproval.relay?.status_url) {
     lines.push(["status url", walletApproval.relay.status_url]);
   }
+  if (relayAliases.walletApprovalRelayShareLinkBaseUrl) {
+    lines.push(["share-link base", relayAliases.walletApprovalRelayShareLinkBaseUrl]);
+  }
+  if (relayAliases.walletApprovalRelayStatusApiBaseUrl) {
+    lines.push(["status api base", relayAliases.walletApprovalRelayStatusApiBaseUrl]);
+  }
   if (walletApproval.stage === "request-created" && walletApproval.recommendedCommands) {
     lines.push(["next local", walletApproval.recommendedCommands.awaitLocal]);
     lines.push(["next remote", walletApproval.recommendedCommands.approve]);
@@ -17873,7 +18674,8 @@ async function printWorkflowRunCommandResult(execution) {
       walletName: execution.result.walletName,
       nextAction: execution.result.nextCommand,
       chain: execution.result.plan.chain,
-      intent: execution.result.intent
+      intent: execution.result.intent,
+      paymasterMode: execution.walletApproval?.request.requestedPaymasterMode ?? extractWorkflowGoalPaymasterMode(execution.goal)
     });
     printResult(
       prependWorkflowRequestId(
@@ -17896,6 +18698,7 @@ async function printWorkflowRunCommandResult(execution) {
         result: execution.result,
         walletRequestId: execution.walletApproval?.request.requestId,
         walletApprovalRelay: execution.walletApproval?.relay,
+        ...workflowWalletApprovalRelayAliases(execution.walletApproval?.relay),
         walletApprovalRecommendedCommands: execution.walletApproval?.recommendedCommands,
         walletApproval: serializeWalletApproval(execution.walletApproval),
         recommendedCommands: recommendedCommands2
@@ -17913,7 +18716,8 @@ async function printWorkflowRunCommandResult(execution) {
     walletName: execution.status.walletName,
     nextAction: execution.status.recommendedCommand,
     chain: execution.status.plan.chain,
-    intent: execution.status.intent
+    intent: execution.status.intent,
+    paymasterMode: execution.walletApproval?.request.requestedPaymasterMode ?? extractWorkflowGoalPaymasterMode(execution.checkpoint?.goal)
   });
   printResult(
     prependWorkflowRequestId(
@@ -17937,6 +18741,7 @@ async function printWorkflowRunCommandResult(execution) {
       checkpoint: execution.checkpoint,
       walletRequestId: execution.walletApproval?.request.requestId,
       walletApprovalRelay: execution.walletApproval?.relay,
+      ...workflowWalletApprovalRelayAliases(execution.walletApproval?.relay),
       walletApprovalRecommendedCommands: execution.walletApproval?.recommendedCommands,
       walletApproval: serializeWalletApproval(execution.walletApproval),
       recommendedCommands
@@ -18184,6 +18989,7 @@ async function executeWorkflowAutoCommand(options, deps = resolveWorkflowCommand
     action: result ? result.stage : walletApproval?.stage ?? status.status,
     requestId: context.requestId,
     checkpointPersisted: Boolean(checkpoint),
+    goal: context.goal,
     checkpoint,
     status,
     result,
@@ -18202,7 +19008,8 @@ async function printWorkflowAutoCommandResult(execution) {
     walletName: execution.status.walletName,
     nextAction,
     chain: execution.status.plan.chain,
-    intent: execution.status.intent
+    intent: execution.status.intent,
+    paymasterMode: execution.walletApproval?.request.requestedPaymasterMode ?? extractWorkflowGoalPaymasterMode(execution.goal) ?? extractWorkflowGoalPaymasterMode(execution.checkpoint?.goal)
   });
   const summaryLines = [
     ["source", execution.source],
@@ -18237,6 +19044,7 @@ async function printWorkflowAutoCommandResult(execution) {
       checkpoint: execution.checkpoint,
       walletRequestId: execution.walletApproval?.request.requestId,
       walletApprovalRelay: execution.walletApproval?.relay,
+      ...workflowWalletApprovalRelayAliases(execution.walletApproval?.relay),
       walletApprovalRecommendedCommands: execution.walletApproval?.recommendedCommands,
       walletApproval: serializeWalletApproval(execution.walletApproval),
       recommendedCommands
@@ -18263,7 +19071,21 @@ function buildWorkflowCheckpointRecommendedCommands(checkpoint) {
     walletStatus: buildWalletStatusRecommendedCommand(checkpoint.walletName)
   };
 }
+function extractWorkflowGoalPaymasterMode(goal) {
+  if (!goal || !("paymaster" in goal)) {
+    return void 0;
+  }
+  return goal.paymaster?.mode;
+}
+function extractPaymasterModeFromCommand(command) {
+  if (!command) {
+    return void 0;
+  }
+  const match = command.match(/--paymaster-mode (none|sponsored|approval-based)\b/);
+  return match?.[1];
+}
 function buildWorkflowRuntimeRecommendedCommands(input) {
+  const paymasterMode = extractPaymasterModeFromCommand(input.nextAction) ?? input.paymasterMode;
   return {
     inspectDefaults: "zk-agent defaults",
     list: buildWorkflowListRecommendedCommand(),
@@ -18287,6 +19109,10 @@ function buildWorkflowRuntimeRecommendedCommands(input) {
       } : {},
       discoverTokens: `zk-agent tokens --chain ${input.chain}`,
       inspectToken: `zk-agent resolve-token --chain ${input.chain} --symbol <symbol>`
+    } : {},
+    ...input.chain && paymasterMode === "approval-based" ? {
+      discoverPaymasterTokens: buildPaymasterFeeTokensRecommendedCommand(input.chain),
+      inspectPaymasterToken: buildPaymasterFeeTokenResolveRecommendedCommand(input.chain)
     } : {}
   };
 }
@@ -18304,6 +19130,10 @@ function buildWorkflowPlanRecommendedCommands(plan) {
       discoverOwnedTokens: buildOwnedTokensRecommendedCommand(plan.walletName),
       discoverTokens: buildTokensRecommendedCommand(plan.chain),
       inspectToken: buildResolveTokenRecommendedCommand(plan.chain)
+    } : {},
+    ...plan.paymasterMode === "approval-based" ? {
+      discoverPaymasterTokens: buildPaymasterFeeTokensRecommendedCommand(plan.chain),
+      inspectPaymasterToken: buildPaymasterFeeTokenResolveRecommendedCommand(plan.chain)
     } : {}
   };
 }
@@ -18367,11 +19197,29 @@ function serializeWalletApproval(walletApproval) {
   if (!walletApproval) return void 0;
   return {
     ...walletApproval,
+    ...workflowWalletApprovalRelayAliases(walletApproval.relay, {
+      shareLinkBaseField: "relayShareLinkBaseUrl",
+      statusApiBaseField: "relayStatusApiBaseUrl"
+    }),
     walletRequestId: walletApproval.request.requestId,
     request: sanitizeWalletRequestRecord(walletApproval.request),
     wallet: walletApproval.wallet ? sanitizeWalletRecord(walletApproval.wallet) : void 0
   };
 }
+function workflowWalletApprovalRelayAliases(relay, fieldNames = {
+  shareLinkBaseField: "walletApprovalRelayShareLinkBaseUrl",
+  statusApiBaseField: "walletApprovalRelayStatusApiBaseUrl"
+}) {
+  const shareUrl = relay?.share_url;
+  const statusUrl = relay?.status_url;
+  const approvalUrl = relay?.approval_url;
+  const shareLinkBaseUrl = shareUrl ? shareUrl.replace(/\/[^/]+$/, "") : approvalUrl ? approvalUrl.replace(/\/[^/]+$/, "") : void 0;
+  const statusApiBaseUrl = statusUrl ? statusUrl.replace(/\/[^/]+$/, "") : approvalUrl && relay?.request_id ? `${approvalUrl.replace(/\/r\/[^/]+$/, "")}/api/requests` : void 0;
+  return {
+    [fieldNames.shareLinkBaseField]: shareLinkBaseUrl,
+    [fieldNames.statusApiBaseField]: statusApiBaseUrl
+  };
+}
 function addWorkflowGoalOptions(command, config = {}) {
   if (config.includeExecutionFlags) {
     command.option("--broadcast", "Broadcast the underlying transaction(s) instead of returning a preview", false).option(
@@ -18533,6 +19381,7 @@ async function executeWorkflowRunCommand(options, deps = resolveWorkflowCommandD
     if (inspection.walletApproval?.stage === "request-created" || inspection.result.status === "blocked") {
       return {
         requestId: inspection.requestId,
+        goal: context.goal,
         status: inspection.result,
         walletApproval: inspection.walletApproval,
         checkpoint: inspection.checkpoint
@@ -18570,6 +19419,7 @@ async function executeWorkflowRunCommand(options, deps = resolveWorkflowCommandD
   );
   return {
     requestId: context.requestId,
+    goal: context.goal,
     result,
     walletApproval
   };
@@ -18646,14 +19496,13 @@ function assertWorkflowResumeReady(result) {
 }
 function buildWorkflowHelpText() {
   return [
-    "",
-    "Default workflow path:",
-    "  Guided default:",
-    "    zk-agent workflow auto --wallet main --intent <intent> [goal flags] --create-checkpoint --execute-when-ready",
     "",
     "  Flagship native pay path:",
     "    zk-agent workflow pay --wallet main --to <address> --amount <amount>",
     "",
+    "  Broader multi-intent guided path:",
+    "    zk-agent workflow auto --wallet main --intent <intent> [goal flags] --create-checkpoint --execute-when-ready",
+    "",
     "  Checkpointed execution:",
     "    zk-agent workflow start --wallet main --intent <intent> [goal flags]",
     "    zk-agent workflow status --request-id <id>",
@@ -18663,13 +19512,24 @@ function buildWorkflowHelpText() {
     "  Funding-only step:",
     "    zk-agent workflow fund --wallet main --amount <amount> --execute",
     "",
+    "  Token/discovery recovery path:",
+    "    zk-agent assets --wallet main",
+    "    zk-agent tokens --wallet main --owned",
+    "    zk-agent tokens --chain zksync-sepolia",
+    "    zk-agent resolve-token --chain zksync-sepolia --symbol USDC",
+    "",
+    "  Approval-based paymaster fee-token recovery:",
+    "    zk-agent tokens --chain zksync-sepolia --role paymaster-fee-token",
+    "    zk-agent resolve-token --chain zksync-sepolia --symbol <symbol> --role paymaster-fee-token",
+    "    zk-agent defaults",
+    "",
     "  Lower-level one-shot escape hatch:",
     "    zk-agent workflow run --wallet main --intent <intent> [goal flags]"
   ].join("\n");
 }
 var WORKFLOW_HELP_COMMAND_ORDER = [
-  "auto",
   "pay",
+  "auto",
   "start",
   "status",
   "next",
@@ -18698,7 +19558,7 @@ function applyWorkflowHelpCommandOrder(workflow) {
 function createWorkflowCommand(deps) {
   const resolvedDeps = resolveWorkflowCommandDeps(deps);
   const workflow = new Command10("workflow").description(
-    "Build a higher-level CLI workflow for a stored wallet and a concrete action intent"
+    "Plan, persist, and execute higher-level wallet workflows"
   );
   workflow.addHelpText("after", buildWorkflowHelpText());
   workflow.command("plan").description("Plan the prerequisite and execution steps for one concrete wallet workflow").requiredOption(
@@ -18710,15 +19570,19 @@ function createWorkflowCommand(deps) {
   ).option("--to-chain <chain>", "Optional destination chain override for bridge workflows").option("--paymaster-mode <mode>", "none, sponsored, or approval-based").option("--paymaster-address <address>", "Explicit paymaster contract address override").option("--paymaster-token <address>", "ERC-20 token address for approval-based paymaster mode").action(
     async (options) => {
       const intent = parseWorkflowIntent(options.intent);
+      const paymasterInput = resolveWorkflowPaymasterInput(options);
       const { inspection, plan } = await loadWorkflowPlanState(
         options.wallet,
         intent,
         parseWorkflowSwapProtocol(options.protocol),
         options.toChain,
-        resolveWorkflowPaymasterInput(options),
+        paymasterInput,
         resolvedDeps
       );
-      const recommendedCommands = buildWorkflowPlanRecommendedCommands(plan);
+      const recommendedCommands = buildWorkflowPlanRecommendedCommands({
+        ...plan,
+        paymasterMode: paymasterInput?.mode
+      });
       const agentProfile = await loadWorkflowAgentProfile(plan.walletName);
       const agentFollowup = buildAgentFollowup(agentProfile, {
         walletName: plan.walletName,
@@ -18936,7 +19800,8 @@ function createWorkflowCommand(deps) {
       walletName: inspection.result.walletName,
       nextAction: inspection.result.recommendedCommand,
       chain: inspection.result.plan.chain,
-      intent: inspection.result.intent
+      intent: inspection.result.intent,
+      paymasterMode: inspection.walletApproval?.request.requestedPaymasterMode ?? extractWorkflowGoalPaymasterMode(inspection.checkpoint?.goal)
     });
     const agentProfile = await loadWorkflowAgentProfile(inspection.result.walletName);
     const agentFollowup = buildAgentFollowup(agentProfile, {
@@ -18965,6 +19830,7 @@ function createWorkflowCommand(deps) {
         checkpoint: inspection.checkpoint,
         walletRequestId: inspection.walletApproval?.request.requestId,
         walletApprovalRelay: inspection.walletApproval?.relay,
+        ...workflowWalletApprovalRelayAliases(inspection.walletApproval?.relay),
         walletApprovalRecommendedCommands: inspection.walletApproval?.recommendedCommands,
         walletApproval: serializeWalletApproval(inspection.walletApproval),
         recommendedCommands
@@ -18986,7 +19852,8 @@ function createWorkflowCommand(deps) {
       walletName: inspection.result.walletName,
       nextAction: nextCommand,
       chain: inspection.result.plan.chain,
-      intent: inspection.result.intent
+      intent: inspection.result.intent,
+      paymasterMode: inspection.walletApproval?.request.requestedPaymasterMode ?? extractWorkflowGoalPaymasterMode(inspection.checkpoint?.goal)
     });
     const agentProfile = await loadWorkflowAgentProfile(inspection.result.walletName);
     const agentFollowup = buildAgentFollowup(agentProfile, {
@@ -19028,6 +19895,7 @@ function createWorkflowCommand(deps) {
         checkpoint: inspection.checkpoint,
         walletRequestId: inspection.walletApproval?.request.requestId,
         walletApprovalRelay: inspection.walletApproval?.relay,
+        ...workflowWalletApprovalRelayAliases(inspection.walletApproval?.relay),
         walletApprovalRecommendedCommands: inspection.walletApproval?.recommendedCommands,
         walletApproval: serializeWalletApproval(inspection.walletApproval),
         recommendedCommands
@@ -19050,7 +19918,8 @@ function createWorkflowCommand(deps) {
         walletName: inspection.result.walletName,
         nextAction: inspection.result.recommendedCommand,
         chain: inspection.result.plan.chain,
-        intent: inspection.result.intent
+        intent: inspection.result.intent,
+        paymasterMode: inspection.walletApproval.request.requestedPaymasterMode
       });
       const agentProfile2 = await loadWorkflowAgentProfile(inspection.result.walletName);
       const agentFollowup2 = buildAgentFollowup(agentProfile2, {
@@ -19079,6 +19948,7 @@ function createWorkflowCommand(deps) {
           checkpoint: inspection.checkpoint,
           walletRequestId: inspection.walletApproval.request.requestId,
           walletApprovalRelay: inspection.walletApproval.relay,
+          ...workflowWalletApprovalRelayAliases(inspection.walletApproval.relay),
           walletApprovalRecommendedCommands: inspection.walletApproval.recommendedCommands,
           walletApproval: serializeWalletApproval(inspection.walletApproval),
           recommendedCommands: recommendedCommands2
@@ -19100,7 +19970,8 @@ function createWorkflowCommand(deps) {
         walletName: execution.status.walletName,
         nextAction: execution.status.recommendedCommand,
         chain: execution.status.plan.chain,
-        intent: execution.status.intent
+        intent: execution.status.intent,
+        paymasterMode: execution.walletApproval?.request.requestedPaymasterMode ?? extractWorkflowGoalPaymasterMode(execution.checkpoint?.goal)
       });
       const agentProfile2 = await loadWorkflowAgentProfile(execution.status.walletName);
       const agentFollowup2 = buildAgentFollowup(agentProfile2, {
@@ -19129,6 +20000,7 @@ function createWorkflowCommand(deps) {
           checkpoint: execution.checkpoint,
           walletRequestId: execution.walletApproval?.request.requestId,
           walletApprovalRelay: execution.walletApproval?.relay,
+          ...workflowWalletApprovalRelayAliases(execution.walletApproval?.relay),
           walletApprovalRecommendedCommands: execution.walletApproval?.recommendedCommands,
           walletApproval: serializeWalletApproval(execution.walletApproval),
           recommendedCommands: recommendedCommands2
@@ -19141,7 +20013,8 @@ function createWorkflowCommand(deps) {
       walletName: execution.result.walletName,
       nextAction: execution.result.nextCommand,
       chain: execution.result.plan.chain,
-      intent: execution.result.intent
+      intent: execution.result.intent,
+      paymasterMode: execution.walletApproval?.request.requestedPaymasterMode ?? extractWorkflowGoalPaymasterMode(execution.goal)
     });
     const agentProfile = await loadWorkflowAgentProfile(execution.result.walletName);
     const agentFollowup = buildAgentFollowup(agentProfile, {
@@ -19170,6 +20043,7 @@ function createWorkflowCommand(deps) {
         result: execution.result,
         walletRequestId: inspection.walletApproval?.request.requestId,
         walletApprovalRelay: inspection.walletApproval?.relay,
+        ...workflowWalletApprovalRelayAliases(inspection.walletApproval?.relay),
         walletApprovalRecommendedCommands: inspection.walletApproval?.recommendedCommands,
         walletApproval: serializeWalletApproval(inspection.walletApproval),
         recommendedCommands
@@ -19207,15 +20081,24 @@ function createWorkflowCommand(deps) {
 function buildDefaultOperatorPathHelpText() {
   return [
     "",
-    "Default operator path:",
+    "Public entrypoints:",
+    "  Agent harness: npx skills add https://github.com/AgiWeb3/zk-agent-cli",
+    "  One-shot CLI:  npx zk-agent-cli --help",
+    "  Global CLI:    npm install -g zk-agent-cli",
+    "",
+    "Canonical terminal path:",
     "  zk-agent setup",
     "  zk-agent next",
     "  zk-agent wallet create --await-local",
     "  zk-agent next",
-    `  ${buildWorkflowAutoRecommendedCommand("main")}`,
+    `  ${buildWorkflowPayRecommendedCommand("main")}`,
+    "",
+    "No custom .env is required for setup, next, or wallet create/reapprove request generation.",
+    "Add RPC env vars later, before live reads or broadcasts.",
     "",
     "Use `zk-agent next --request-id <id>` to continue a stored workflow checkpoint.",
-    "Use `zk-agent wallet --help` for bootstrap/reapproval details and `zk-agent workflow --help` once the intent is known."
+    "Use `zk-agent relay inspect --relay-url <url>` plus `zk-agent wallet create|reapprove --relay-url <url> --wait-relay --prompt-code` when the browser is not colocated.",
+    "Use `zk-agent wallet --help` for wallet recovery details and `zk-agent workflow --help` when the intent is broader than the flagship native-send path."
   ].join("\n");
 }
 var ROOT_HELP_COMMAND_ORDER = [
@@ -19256,7 +20139,9 @@ function applyRootHelpCommandOrder(program) {
   program.commands = sortedCommands;
 }
 function createProgram() {
-  const program = new Command11().name("zk-agent").description("zkSync and ZK Stack CLI scaffold for agent workflows").showHelpAfterError().option("--json", "Force JSON output for agent harnesses", false).hook("preAction", (thisCommand) => {
+  const program = new Command11().name("zk-agent").description(
+    "Local-first zkSync Era CLI for wallet approval, workflow execution, and 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";
   });
   program.addCommand(createInitCommand());